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.

Packages

Package details

extension

Install pi-scope from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-scope
Package
pi-scope
Version
0.0.1
Published
Nov 10, 2026
Downloads
351/mo · 351/wk
Author
kxw
License
MIT
Types
extension
Size
34.1 KB
Dependencies
0 dependencies · 0 peers

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.x releases 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 apply
  • write 工具没有 diff(新文件)→ 自己生成 +N −0
  • firstChangedLine → 在 diff 里定位,或在编辑器打开并跳转到该行

交互

动作 行为
点文件 展开 diff(统一 / 双栏可切换)
复制 patch 拿 details.patch 写剪贴板
导出 写出 session.patch,可直接 git apply
跳回对话 点时间戳 → 滚动到对应 tool call 卡片
头部 显示 git status 摘要(可能有人手改过)

三个必须做对的点

  1. 按文件合并,不是按 tool call 列。同一文件改 3 次 → 1 行 M +120 −30,点开看 3 个 hunk
  2. 不嵌 Monaco。为看 diff 塞 10MB 编辑器 + 2 秒启动,不值。用 diff 库 + CSS grid 自己画
  3. 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

认真评估过并否掉:

  1. 机器上没有独立 Node。node -v 显示 v22.13.1,那正是 pi 自带的 node.exe;而 pi 1.5.0 要求 Node ≥ 22.19。走 SDK 就得打包一个 Node 运行时,安装包 +60~80MB
  2. SDK 的唯一独有优势是 SessionManager.list(),而这个用 60 行 TS 扫目录就能替代
  3. 官方文档明确:"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 许可。