pi-scope
A multi-session desktop console for the pi coding agent. Watch every session like oscilloscope channels — live streams, file changes, model switching, all at once.
Package details
Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-scope
A multi-session desktop console for the pi coding agent.
Watch every session like oscilloscope channels — live streams, file changes, model switching, all at once.
Status: design phase.
0.0.xreleases contain design documentation only — no implementation yet. Star / watch this repo to follow along.
把 pi 当成一台多通道示波器:每个会话是一条通道,实时波形、触发、测量,一眼看全。 终端一次只能看清一条通道。这个项目就是为了解决这件事。
目录
为什么做这个
五个真实痛点
| # | 痛点 | 现状(终端里) |
|---|---|---|
| 1 | 忘记命令 | 当前环境有 95 个 slash 命令(实测)。靠脑子记不可能,靠文档查是灾难 |
| 2 | 想看改了哪些文件 | diff 散落在滚动历史里,要往上翻;同一文件改 3 次就是 3 段 |
| 3 | 不想敲命令换模型 | /model 要记名字、记 provider、记 thinking 档位 |
| 4 | 想同时跑多个会话 | 一个终端一个会话流。开 6 个 tmux 窗口,谁卡住了你不知道 |
| 5 | 想要科技感 | TUI 的美学上限就在那里 |
为什么必须是 GUI 而不是更好的 TUI
前 3 个痛点在终端里能凑合(补全、git diff、/model 选择器)。真正做不到的是第 4 个:
终端是一个单通道设备。
你可以开 6 个 tmux 窗口,但你只能看一个。你不知道哪个在跑、哪个在等你确认、哪个已经崩了、哪个烧了 2 美元。你只能逐个 Ctrl+b n 去翻。
GUI 的价值不是"更好看",而是同时呈现多个并发状态——这正是示波器存在的理由:它不是因为波形好看,而是因为多通道 + 触发 + 游标测量让并发系统可观测。
前 3 个痛点之所以也值得做,不是因为做不到,而是因为在终端里做它们的摩擦足够高,高到你宁愿不去做。换模型时你在想"算了就用现在的",看 diff 时你在想"算了反正编译过了"。
不做什么
这个项目不是:
- ❌ 一个内嵌 IDE(不写代码,只审阅)
- ❌ pi 的分支/替代品(不碰 agent loop,不重写 pi)
- ❌ 一个 Web 应用(是桌面应用;Web 版是未来可选项)
- ❌ 一个终端模拟器(不嵌 xterm.js)
MVP 功能设计
MVP = 4 个功能块,每个对应一个痛点。痛点 5(视觉)贯穿全部,不作为独立里程碑。
F1 · 模型控制条(对应痛点 3)
为什么先做:最便宜,一天有回报,而且它验证了整条 RPC 通路。
┌────────────────────────────────────────────────────────────┐
│ pi·scope ▸ deepseek-flash ●max ▾ ◐ 32% $0.45 │
└────────────────────────────────────────────────────────────┘
| 元素 | 数据来源 | 说明 |
|---|---|---|
| 当前模型 | get_state → data.model |
完整 Model 对象 |
| 思考档位 | get_state → thinkingLevel |
显示为 ●max |
| Context 占用 | get_session_stats → contextUsage.percent |
环形进度 ◐ |
| 成本 | get_session_stats → cost |
累计美元 |
点击弹出选择器:
┌─ 选择模型 ─────────────────────────────────┐
│ cc-switch-deep-seek │
│ ● deepseek-flash 1M ctx reasoning │
│ cc-switch-open-code-go │
│ qwen3.8-max 984K ctx reasoning │
│ deepseek-v4.1-flash 1M ctx │
├────────────────────────────────────────────┤
│ 思考强度 [ off │ high │ max ] │
└────────────────────────────────────────────┘
关键技术约束(实测):
- 模型列表来自
get_available_models,字段含id/name/provider/contextWindow/reasoning/cost/thinkingLevelMap - 思考档位必须动态渲染。
get_available_thinking_levels实测返回["off","high","max"]—— 不是固定的 6 档。写死会在不同模型上露出不存在的选项 set_model之后必须重新拉一次档位列表,因为档位随模型变化
快捷键:Ctrl+1..9 直切前 9 个模型;Ctrl+Tab 用 cycle_model 轮转。
验收:点开选择器能看到全部模型 + 上下文窗口 + 是否支持思考;切换后顶栏立即更新,thinking 档位同步变化;不用敲任何命令。
F2 · 变更面板 + Diff 审阅(对应痛点 2)
核心洞察:终端里 diff 是按工具调用排列的;人想知道的是按文件聚合的结果。
┌─────────────────────────┬──────────────────────┐
│ 对话流 │ 变更 · 4 文件 │
│ │ +218 −64 │
│ assistant ▍ ├──────────────────────┤
│ ▸ edit Login.vue │ ▾ M src/Login.vue │
│ +48 −12 │ +48 −12 │
│ ▸ edit Auth.ts │ ▾ M src/Auth.ts │
│ +96 −40 │ +96 −40 │
│ ▸ write README.md │ ▸ A README.md │
│ │ +74 −0 │
└─────────────────────────┴──────────────────────┘
数据来源(实测字段)
edit 工具的 tool_execution_end → result.details:
interface EditToolDetails {
diff: string; // 面向显示的 diff
patch: string; // 标准 unified patch
firstChangedLine?: number; // 用于跳转定位
}
patch是标准 unified diff → 可复制、可导出.patch、可git applywrite工具没有 diff(新文件)→ 自己生成+N −0firstChangedLine→ 在 diff 里定位,或在编辑器打开并跳转到该行
交互
| 动作 | 行为 |
|---|---|
| 点文件 | 展开 diff(统一 / 双栏可切换) |
| 复制 patch | 拿 details.patch 写剪贴板 |
| 导出 | 写出 session.patch,可直接 git apply |
| 跳回对话 | 点时间戳 → 滚动到对应 tool call 卡片 |
| 头部 | 显示 git status 摘要(可能有人手改过) |
三个必须做对的点
- 按文件合并,不是按 tool call 列。同一文件改 3 次 → 1 行
M +120 −30,点开看 3 个 hunk - 不嵌 Monaco。为看 diff 塞 10MB 编辑器 + 2 秒启动,不值。用
diff库 + CSS grid 自己画 - diff 要增量渲染。大文件(2000 行)直接全量渲染会卡
验收:一个会话跑完,打开变更面板能一眼看到"改了哪些文件、每个文件改了多少行";点进去能逐行看改动;能一键导出 patch。
F3 · 命令面板(对应痛点 1)
核心洞察:95 个命令的问题不是"没有文档",而是查找成本高于使用收益。
你敲 / ────► 面板立即弹出
┌────────────────────────────────────────┐
│ /pl │
├────────────────────────────────────────┤
│ ▸ /plan Toggle plan mode [ext] │
│ /plan-mode ... │
├────────────────────────────────────────┤
│ 最近使用 │
│ /memory Browse saved memories │
│ /subagents Administer subagents │
└────────────────────────────────────────┘
↑↓ 选择 Enter 填入 Esc 关闭
数据来源
get_commands 实测返回 95 条:
{
"name": "memory",
"description": "Browse saved memories; pick one to pin or forget.",
"source": "extension",
"sourceInfo": { "scope": "user", "path": "...", "origin": "package" }
}
设计规则
| 规则 | 理由 |
|---|---|
/ 就是触发器 |
你本来就要在输入框里敲 /,不要额外的面板 |
Ctrl/Cmd+K 全局唤起 |
填入输入框,不直接执行 |
| 模糊匹配 name 和 description | 只匹配前缀会漏掉一半 |
按 source 分组着色(extension / prompt / skill) |
跑一次就知道哪些是自己的 |
sourceInfo.scope = project 打徽章 |
提醒这条命令只在当前项目有效 |
| 最近使用置顶(localStorage) | 90% 的使用集中在 10% 的命令上 |
加分:允许 pin 5~8 个命令到输入框上方的快捷条。把 95 个降到日常可见的 8 个。
验收:不查文档,输入 / 后 2 秒内能找到任意一个命令并填入。
F4 · 多会话通道(对应痛点 4)← 核心
这是整个项目存在的理由。 前面三个功能是"顺手做对了",这个才是"终端做不到"。
┌────────────────────────┬────────────────────────┐
│ ● CH1 D:\projA │ ○ CH2 D:\projB │
│ 优化登录页 │ 修复 Gradle 构建 │
│ ▍运行中 2m31s │ 空闲 · 12m 前 │
│ 3.2k tok · $0.08 │ 18k tok · $0.41 │
│ ~ 4 文件 │ ~ 7 工具 │
├────────────────────────┼────────────────────────┤
│ ◐ CH3 C:\work │ + 新建通道 │
│ 排查 OOM │ │
│ 等待输入 ⚠ │ │
└────────────────────────┴────────────────────────┘
进程模型:一个通道一个 pi 进程
Rust pi 进程池
├─ spawn cwd=D:\projA → pi --mode rpc (CH1)
├─ spawn cwd=D:\projB → pi --mode rpc (CH2)
└─ spawn cwd=C:\work → pi --mode rpc (CH3)
红利:故障隔离 + 真并行。一个通道崩了不影响其他,一个在跑 Gradle 另一个照样能对话。
四种状态与判定依据
| 状态 | 判定 |
|---|---|
| 运行中 | agent_start 之后,agent_settled 之前 |
| 等待输入 | 收到 extension_ui_request 的 confirm/select/input 且未回复 |
| 空闲 | agent_settled 之后 |
| 已退出 | 子进程 exit |
⚠️ 不能用
agent_end判定空闲。agent_end之后可能紧跟自动重试、压缩重试或排队的 followUp。只有agent_settled表示"真的停了"。绑错会让状态灯在自动重试时空闲闪一下。
历史会话:自己扫目录
RPC 没有 list_sessions 命令(命令全表已确认)。会话存在:
~/.pi/agent/sessions/--C--Users-kxw--/2026-09-05T13-21-53-649Z_<uuid>.jsonl
~/.pi/agent/sessions/--D--projA--/...
↑ cwd 里的 \ / : 换成 -
只读第一行(会话文件可能几十 MB):
{"type":"session","version":3,"id":"01a071bb...",
"timestamp":"2026-09-05T13:21:53.649Z","cwd":"C:\\"}
标题取首条 user message 前 60 字(sessionName 优先)。恢复用 switch_session。
进程池约束
| 约束 | 对策 |
|---|---|
| 每进程约 150~300MB 内存 | LRU 休眠:超过 N 个(默认 6)杀掉最久未活动的,UI 显示 💤 已休眠,点击时 switch_session 恢复 |
多进程共享 ~/.pi/agent/(settings、memory 扩展数据) |
写入方使用原子替换(tmp + rename);UI 避免并发改同一设置 |
| 进程崩溃 | 卡片标红,保留会话文件,可重启恢复 |
验收:同时开 4 个不同项目的会话,其中一个在跑长任务;能从卡片墙一眼看出谁在跑、谁在等、谁改了哪些文件;点击卡片进入任一通道,对话流完整。
MVP 不做的事(明确划界)
| 不做 | 原因 |
|---|---|
| 内嵌代码编辑器 | 不是 IDE。要改代码用 pi 或你的编辑器 |
| 权限确认弹窗做成策略引擎 | pi 已有 permission-gate 等扩展,GUI 只负责呈现 |
| Subagent 可视化树 | 复杂度高,等 v0.3 |
| 会话导出 HTML | export_html 命令能直接用,不做 UI |
| i18n 框架 | 先用中文,需要时再抽 |
| 自动更新 | 手动下载,等 v0.3 |
未来功能设计
v0.2 · 打磨(MVP 之后 1~2 周)
- 工具调用树:右侧栏以树形展示 tool calls(含 subagent 嵌套)
- 会话搜索:跨项目全文搜索历史会话(扫 JSONL,建本地索引)
- 会话树视图:pi 的会话是
id/parentId树,可视化分支 + 点击切换(get_tree/fork) - 通知:通道完成 / 需要确认时,系统 Toast + 托盘角标
- 托盘汇总:
3 运行中 · 1 等待输入,点击跳转
v0.3 · 工作流
- 批量发送:向所有空闲通道发同一句("都跑一遍测试")
- 项目级分组:按 cwd 分组通道,一个项目 3 个通道并排
- Diff 工作流:逐 hunk 接受/拒绝(需要写回文件,要谨慎)
- 自定义会话模板:一键用某个模型 + thinking + 提示词开新通道
- 快捷键体系:
Ctrl+Tab切通道、Ctrl+Shift+P命令面板
v1.0 · 平台
- Web 模式:把 Rust 管道换成 WebSocket 服务,浏览器可用(架构上已预留)
- 远程会话:连 SSH 上的 pi(
ssh://目标) - 插件化面板:把"变更"换成"Gradle 任务图"、"logcat 流"等(对你自己的 Android 工作流)
- 多语言:中/英
想清楚但不打算做
| 想法 | 结论 |
|---|---|
| 内嵌完整 IDE | 不做。编辑器领域已被 VS Code / JetBrains 占满 |
| 云同步会话 | 不做。会话可能含敏感代码 |
| 移动端 | 不做。pi 本体在 Termux 里已经可用 |
| 替代 pi CLI | 不做。CLI 是第一公民,GUI 是并行选项 |
架构设计
核心原则
Rust 只做管道,协议和状态全在 TypeScript。
这是针对技术栈的刻意选择。pi 的协议是 JSONL + JSON,用 TS 处理比 serde 快得多地迭代;而 Rust 只需要管进程生命周期。
分层
┌─────────────────────────────────────────────────────────────┐
│ Vue 3 + TypeScript(WebView) │
│ │
│ views/ ChannelWall · Conversation · Changes · Model │
│ stores/ channels · conversation · changes · models │
│ pi/client JSONL 分帧 + 请求响应关联 + 事件分流 │
│ pi/reducer 事件 → 状态归约(纯函数,可单测) │
└────────────────────────┬────────────────────────────────────┘
│ Tauri IPC
│ emit "pi:line" (stdout 原样一行)
│ invoke("pi_send", { line })
┌────────────────────────▼────────────────────────────────────┐
│ Rust(~200 行) │
│ spawn / kill / write stdin / forward stdout │
│ 会话目录扫描(可选放前端,用 plugin-fs) │
└────────────────────────┬────────────────────────────────────┘
│ stdio(JSONL)
┌────────────────────────▼────────────────────────────────────┐
│ pi --mode rpc │
│ + 用户已安装的全部扩展(memory / plan-mode / web-tools…) │
└─────────────────────────────────────────────────────────────┘
为什么 Rust 侧不解析 JSON
| 方案 | Rust 代码量 | 缺点 |
|---|---|---|
| Rust 解析协议 | 800+ 行 | 类型要抄两遍;pi 改协议要改 Rust |
| Rust 只转发(本方案) | ~200 行 | 无。WebView 的 JSON.parse 足够快(每秒几十条事件无压力) |
数据流
pi stdout ──► Rust read_until(b'\n') ──► emit("pi:line")
│
前端 listen
│
JSON.parse → 按 type 分流
│
┌───────────────────────────────┼──────────────────────┐
▼ ▼ ▼
response event extension_ui_request
→ 关联 pending Promise → reducer(state, event) → 弹窗,等用户,回写 stdin
目录结构
pi-scope/
├── package.json # name: pi-scope, keywords: pi-package
├── README.md
├── src/ # Vue 前端
│ ├── main.ts
│ ├── App.vue
│ ├── styles/
│ │ ├── tokens.css # 设计 token(颜色/字体/动效)
│ │ └── base.css
│ ├── pi/
│ │ ├── client.ts # 连接、分帧、send/request
│ │ ├── protocol.ts # Command / Event / Response 类型
│ │ ├── reducer.ts # 事件归约(纯函数)
│ │ └── sessions.ts # 扫描会话目录、读 header
│ ├── stores/
│ │ ├── channels.ts # Map<channelId, ChannelState>
│ │ ├── conversation.ts
│ │ ├── changes.ts # 按文件聚合的 diff
│ │ └── models.ts
│ ├── components/
│ │ ├── ChannelCard.vue
│ │ ├── ConversationStream.vue
│ │ ├── MessageItem.vue
│ │ ├── ToolCallCard.vue
│ │ ├── DiffView.vue
│ │ ├── CommandPalette.vue
│ │ ├── ModelPicker.vue
│ │ └── ExtensionDialog.vue
│ └── views/
│ ├── ChannelWall.vue
│ └── ChannelView.vue
├── src-tauri/
│ ├── Cargo.toml
│ ├── tauri.conf.json
│ └── src/
│ ├── main.rs
│ └── pi.rs # 进程管道(唯一的 Rust 逻辑)
└── scripts/
└── protocol-check.mjs # 协议契约测试(见下)
状态模型(多通道从第一天就做对)
即使 MVP 只开一个通道,数据结构必须是 Map,否则 F4 会全面返工。
interface ChannelState {
id: string;
cwd: string;
status: "running" | "waiting" | "idle" | "exited" | "asleep";
model: Model | null;
thinkingLevel: string | null;
messages: Message[]; // 权威:message_end
streaming: {
blocks: Map<number, { type: string; text: string }>;
} | null;
toolCalls: Map<string, ToolCallState>;
changes: Map<string, FileChange>; // 按路径聚合
extUi: { statuses: Map<string,string>; widgets: Map<string,string[]> };
pendingUi: Map<string, PendingDialog>;
queue: { steering: string[]; followUp: string[] };
stats: { tokens: number; cost: number; contextPercent: number | null } | null;
}
interface FileChange {
path: string;
kind: "M" | "A" | "D";
insertions: number;
deletions: number;
hunks: Array<{ patch: string; firstChangedLine?: number; at: number }>;
}
协议契约(不读文档会踩的六个坑)
这六条都来自实测与文档,写在这里是为了不在实现时重新踩一遍。
① 分帧只能用 \n
Node
readline不是协议合规的,因为它还会在U+2028/U+2029处切分,而这两个字符在 JSON 字符串里合法。
Rust 用 read_until(b'\n');前端不要用任何按 Unicode 行分隔符切分的库。容忍尾部 \r。
② 三种消息共用 stdout,且乱序
实测启动瞬间就在第一个响应之前插入了 4 条扩展 UI 请求:
{"type":"extension_ui_request","method":"setStatus","statusKey":"plan-mode"}
{"type":"extension_ui_request","method":"setWidget","widgetKey":"plan-todos"}
{"type":"extension_ui_request","method":"notify","message":"Web tools loaded..."}
{"type":"extension_ui_request","method":"setWidget","widgetKey":"subagent-async"}
{"id":"s1","type":"response","command":"get_state", ...}
必须按 type 分流,不能假设顺序。
③ 扩展对话框必须回复,否则卡死
select / confirm / input / editor 是阻塞的——扩展线程在等你。notify / setStatus / setWidget / setTitle / set_editor_text 是 fire-and-forget,可以不回。
// 回复
{ type: "extension_ui_response", id, value } // select/input/editor
{ type: "extension_ui_response", id, confirmed } // confirm
{ type: "extension_ui_response", id, cancelled: true } // 取消
④ 两种增量的语义相反
| 事件 | 语义 | 正确做法 |
|---|---|---|
message_update.assistantMessageEvent.delta |
纯增量 | 按 contentIndex 追加 |
tool_execution_update.partialResult |
累积快照 | 整体替换 |
写反了表现为:bash 输出重复 N 遍,或只显示最后一个字符。
⑤ streaming 期间发 prompt 必须带 streamingBehavior
{"type":"prompt","message":"...","streamingBehavior":"steer"}
{"type":"prompt","message":"...","streamingBehavior":"followUp"}
不带会直接返回 success: false。UI 上正好对应「插话」和「排队」两个按钮。
⑥ Windows 下不能直接启动 sh shim
实测从 WSL 调用 pi(sh shim)会得到:
Error: Cannot find module 'C:\mnt\c\Users\...\cli.js'
- Windows:
cmd /c pi --mode rpc ... - macOS/Linux:直接
pi --mode rpc - 找不到
pi时:读启动器 shim 文本反解包路径(参考locate-pi思路)
状态归约的关键不变量
// 1. message_end 是权威,覆盖 streaming 拼装结果
case "message_end":
channel.messages.push(event.message);
channel.streaming = null;
// 2. 空闲只看 agent_settled,不看 agent_end
case "agent_start": channel.status = "running"; break;
case "agent_settled": channel.status = "idle"; break;
// 3. 工具结束才把 partial 换成 result
case "tool_execution_end":
const call = channel.toolCalls.get(event.toolCallId);
call.result = event.result; call.isError = event.isError;
if (event.toolName === "edit") collectChange(channel, event);
break;
协议契约测试
scripts/protocol-check.mjs:启动 pi --mode rpc --no-session,依次发 get_state / get_available_models / get_available_thinking_levels / get_commands,断言字段存在。
不调模型,零成本,几秒跑完。pi 升级后第一件事就是跑它。
node scripts/protocol-check.mjs
技术选型设计
前端
| 领域 | 选择 | 理由 | 拒绝的 |
|---|---|---|---|
| 框架 | Vue 3.5 + <script setup> |
已有技术栈;响应式对高频流式更新友好 | React(无优势)、Svelte(生态小) |
| 语言 | TypeScript 5(strict) | 协议类型是唯一真相源 | — |
| 构建 | Vite 6 | Tauri 官方模板默认 | webpack(慢) |
| 状态 | Pinia | 官方方案;Map 类型状态需要它 |
Vuex(过时)、纯 ref(多通道会失控) |
| 样式 | CSS 变量 + Tailwind v4 | token 用 CSS 变量(可主题化),布局用 utility(快) | 纯 Tailwind(科技感 token 表达不了)、Sass |
| 组件库 | 无(自研) | 要精确控制 1px 边框和等宽数字,任何 UI 库都会打架 | Element Plus、Naive UI、Vuetify |
| 图标 | lucide-vue-next | 线条统一,和精密仪器风一致 | FontAwesome |
| Markdown | markdown-it | 轻、插件成熟 | unified/remark(重) |
| 代码高亮 | Shiki | 使用 VS Code 主题,准确且可控 | highlight.js(配色土)、Prism(还得自己配主题) |
| Diff 渲染 | 自研(diff 库 + CSS grid) |
需要统一/双栏切换 + 增量渲染 | Monaco(10MB+)、diff2html(样式难改) |
| 虚拟滚动 | @tanstack/vue-virtual | headless,无样式污染;长会话必须 | vue-virtual-scroller(有内置样式) |
| 测试 | Vitest | reducer 是纯函数,好测 | Jest(配置烦) |
桌面壳
| 领域 | 选择 | 理由 | 拒绝的 |
|---|---|---|---|
| 壳 | Tauri 2 | 体积 ~10MB、内存低、原生窗口/托盘/通知 | Electron(100MB+)、Wails(Go 生态) |
| Rust 运行时 | tokio(Tauri 自带) | 异步进程管理 | — |
| 序列化 | 不用 serde(只做字符串转发) | 见架构章节 | serde_json(类型要抄两遍) |
| 插件 | plugin-dialog(选目录)、plugin-notification(通知)、plugin-fs(读会话目录)、plugin-shell(跑 git) |
官方维护 | 自己造轮子 |
为什么不用 Node sidecar + SDK
认真评估过并否掉:
- 机器上没有独立 Node。
node -v显示v22.13.1,那正是 pi 自带的node.exe;而 pi 1.5.0 要求 Node ≥ 22.19。走 SDK 就得打包一个 Node 运行时,安装包 +60~80MB - SDK 的唯一独有优势是
SessionManager.list(),而这个用 60 行 TS 扫目录就能替代 - 官方文档明确:"RPC mode is preferred when: You're integrating from another language / You want process isolation / You're building a language-agnostic client" —— 正是本项目的场景
只有未来需要「在进程内注入自定义工具」时,才值得考虑 SDK。
版本策略
| 项 | 策略 |
|---|---|
| pi 依赖 | 不打包。使用用户已安装的 pi,package.json 声明 engines 提示最低版本 |
| pi 版本探测 | 启动时执行 get_state,失败则提示升级 |
| 协议契约测试 | CI 里跑 protocol-check.mjs,pi 升级后立刻能发现破绽 |
| 自身版本 | 语义化版本;MVP 阶段 0.x |
设计 token
:root {
--bg-base: #08090B;
--bg-panel: #0E1014;
--bg-elevated: #14171D;
--bg-hover: #1A1E26;
--border-subtle: rgba(255,255,255,0.06);
--border-strong: rgba(255,255,255,0.12);
--border-glow: rgba(0,229,160,0.35);
--accent: #00E5A0;
--accent-dim: #00B37D;
--state-running: #00E5A0;
--state-waiting: #FFB020;
--state-error: #FF5C5C;
--state-idle: #5A6472;
--text-primary: #E6EAF0;
--text-secondary: #9AA4B2;
--text-muted: #5A6472;
--font-mono: "JetBrains Mono", "Cascadia Code", Consolas, monospace;
--font-ui: "Inter", system-ui, sans-serif;
--t-fast: 90ms;
--t-base: 140ms;
--ease: cubic-bezier(0.2, 0, 0, 1);
}
五条硬规则(决定"高级"还是"廉价")
| ❌ 廉价 | ✅ 高级 |
|---|---|
到处 text-shadow 发光 |
只在运行中状态有 1px 呼吸边框 |
| 紫粉渐变背景 | 纯深色 + 40px 间距的极暗网格 |
玻璃拟态 backdrop-filter |
实色面板 + 1px 边框分层 |
| 数字用比例字体 | 全部 font-variant-numeric: tabular-nums |
| 圆角 16px | 圆角 6~8px,工具卡片 4px |
协议回调三处动效,仅此三处:流式光标闪烁、工具运行呼吸、面板切入。
性能预算
| 指标 | 目标 |
|---|---|
| 冷启动到可交互 | < 1.5s |
| 流式 token 渲染 | 60fps(delta 批量合并到 requestAnimationFrame) |
| 会话消息数 | 1000 条不卡(虚拟滚动) |
| 通道数 | 6 个同时活跃 |
| 空闲内存(6 通道) | < 1.2GB |
路线图
| 里程碑 | 内容 | 覆盖痛点 | 估时 |
|---|---|---|---|
| M0 | 设计 token + 布局骨架 + Rust 管道 + 单通道对话流 + F1 模型条 | 3 | 4 天 |
| M1 | F2 变更面板 + diff 审阅 | 2 | 3 天 |
| M2 | F3 命令面板 | 1 | 2 天 |
| M3 | F4 多通道卡片墙 + 进程池 + 历史会话 | 4 | 6 天 |
| M4 | 视觉统一打磨、托盘、通知、快捷键 | 5 | 3 天 |
约 3 周出可用版本。
M0 的关键要求:数据结构必须按多通道设计(Map<channelId, ChannelState>),即使 UI 上只有一个。M3 就只是加界面,不返工。
已知限制
扩展降级
RPC 模式下部分 ctx.ui 方法不可用:
| 方法 | 行为 |
|---|---|
custom() |
返回 undefined |
setWorkingMessage / setFooter / setHeader / setEditorComponent |
无操作 |
getTheme() / getAllThemes() / setTheme() |
空 / 失败 |
后果:用 ctx.ui.custom() 画自定义 TUI 组件的扩展在 pi-scope 里无法工作(如 plan-mode 的 /todos 交互列表、questionnaire.ts 这类)。
select / confirm / input / editor / notify / setWidget 类扩展完全正常。
对策:命令面板里这类命令标灰 + 提示「此命令需要终端」。
其他
- 依赖用户已安装的
pi,不打包运行时 - 多进程共享
~/.pi/agent/,并发写以原子替换保证不损坏 - 首版以 Windows 为主,macOS/Linux 未验证
- 会话目录扫描在大历史量下(>1000 会话)需要缓存,首版不做
开发
环境要求
| 依赖 | 版本 |
|---|---|
| Node.js | ≥ 22.19 |
| Rust | ≥ 1.77 |
| Tauri CLI | 2.x |
| pi | ≥ 1.5.0(pi --version) |
| Windows | WebView2(Win10/11 自带) |
命令
npm install
npm run dev # Tauri 开发模式(热更新)
npm run build # 生产构建
npm run test # Vitest(reducer / protocol)
npm run check:protocol # 协议契约测试(不调模型)
第一次验证(M0 之前)
不需要写代码,确认 RPC 通路存在:
# Windows
printf '{"type":"get_state"}\n' | cmd /c pi --mode rpc --no-session
能看到一行 {"type":"response","command":"get_state",...} 就说明一切可行。
与 pi-deck 的区别
npm 上存在一个 pi-deck("A full-featured web UI for Pi coding agent"),需要正面说明:
| pi-deck | pi-scope | |
|---|---|---|
| 形态 | Web UI(本地 express 服务) | Tauri 桌面应用 |
| 状态 | 版本 0.1.6、无 license、无仓库链接、依赖 pi 改名前的旧 scope @mariozechner/pi-coding-agent |
活跃开发 |
| 核心场景 | 单会话 Web 界面 | 多通道并行 + 变更审阅 |
| 模型切换 | 未提供 | 一等公民(含动态 thinking 档位) |
| Diff 审阅 | 未提供 | 按文件聚合 + patch 导出 |
pi-deck 证明了「pi 的图形界面」有真实需求,但它已经不再维护。pi-scope 的差异点不是"也有个界面",而是做终端结构上做不到的事:多通道并发可观测。
License
MIT
pi-scope 与 pi 项目无隶属关系。pi 由 Earendil Inc. 开发,MIT 许可。