pi-chat-helper
pi coding agent 扩展包:浏览器会话轨迹回放 + TUI 提问跳转面板(trajectory web viewer + question panel)
Package details
Install pi-chat-helper from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-chat-helper- Package
pi-chat-helper- Version
0.10.4- Published
- Nov 17, 2026
- Downloads
- 1,315/mo · 670/wk
- Author
- zhubblego
- License
- MIT
- Types
- extension
- Size
- 5.2 MB
- Dependencies
- 0 dependencies · 2 peers
Pi manifest JSON
{
"extensions": [
"./index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-chat-helper
中文 | English
pi coding agent 扩展包:在浏览器里完整回看会话轨迹(trajectory-web),在 TUI 里快速跳转历史提问(question-panel)。轨迹观察不只支持 pi——宿主机上有哪个 agent 的会话,左侧 Agent 选择栏就亮哪个按钮(当前支持 pi 与 Codex)。

轨迹页:会话栏 + 问题栏 + 按提问分段的轨迹,工具调用与结果成对展示
主要功能
轨迹回看 · trajectory-web
按提问分段回看完整轨迹:思维链、工具调用与结果、回答、错误与上下文事件成链展示;错误与回答高亮,轮次可折叠,运行中的会话带 live 徽标。
消息类型过滤——提问、思考、工具、过程、回答、压缩、上下文、错误、审批自由组合,工具名可多选;过滤偏好跨会话记住。轨迹视角——「全量」显示文件里的全部条目(含已被压缩的历史),「模型」只看模型当前上下文:压缩摘要+其后未被裁剪的条目,被压缩掉的轮次整轮隐藏;视角偏好跨会话记住。

详情弹窗——点击任意条目展开:Markdown、表格、mermaid 图表、工具参数与结果、tokens 与耗时;无遮罩不挡页面,可在对话栏边打字边看;可拖动、右下角拖拽放大,切换条目只换内容,位置与尺寸一直保留;✕ 或 Esc 关闭。压缩条目抬头还带压缩比与调用开销徽标(如 9 轮 83 万字 → 1.9 万字摘要 ≈1/44,in/out/推理 tokens·费用,自动超限或 hook 触发)。复制——⧉ 按钮弹四项菜单:复制原文、复制译文、带格式复制原文、带格式复制译文(保留标题/列表/代码块/表格等 Markdown 结构)。

裁剪与蒸馏——两种编辑态,直接在轨迹上管理上下文:

- 裁剪:点剪刀把整轮或单条从模型上下文剪掉,之后的对话里模型看不到它们;再点一次取消。仅当前 pi 会话可裁剪,其它会话只读
- 蒸馏:勾选有价值的条目(轮头一键全选本轮的可见条目——过滤/搜索隐藏的不选)作为对话页的上下文,随消息发给模型
- 两个模式可同时开,勾选与裁剪互不影响
其他能力:
- 全文搜索:命中高亮,无命中的轮次自动收起
- 轮次排序:过滤左侧按钮切换从旧到新/从新到旧(「会话开始」不参与排序,恒在最前)
- 轮次折叠:「轮次」按钮一键收起/展开;全部收起的状态会记住,切会话与刷新页面后仍保持收起
- 多 agent 源:pi 原生解析 + Codex 轨迹翻译;Codex 的派生会话点击跳转、一键回主会话
- 会话右键菜单:复制 Session ID;右键会话行真删除会话文件(两步确认;仅 pi 源,live /运行中的会话拒绝删除)
- 会话多选:Shift 连选、Ctrl/⌘ 逐个增删(不切会话),右键多选项可批量删除(多少个就一个个删,运行中/被占用的单独计失败)
- 多开 pi TUI 时,最新活跃控制台所在的会话标「当前」徽标,一眼定位正在用的会话
- 正文逐段翻译(微软 / Google,免 key),双语对照或仅译文;一键复制原文或译文
- 深浅主题跟随系统,也可手动切换;URL 记住当前源、会话与位置,刷新即恢复
对话页 · chat
在浏览器里针对任意轨迹会话直接问 pi——回答走独立子进程,不污染你正在用的 TUI 会话。思考与工具调用合成一行活动块(dsh 的活动行,步骤可展开),点开就地看每一步的参数与完整结果。

- 蒸馏模式勾选轨迹条目作为上下文,模型按需用只读工具取正文
/model换模型,/skill用技能,工具权限三档(仅对话 / 只读 / 可写,逐次审批)- 对话线程独立落盘,删除不影响轨迹历史;服务只监听本机回环地址
控制台转发——留在网页里指挥你的 agent:把提问直接送进正在运行的 pi TUI 控制台,agent 在那边干活、回答与工具审批都在控制台完成,你不用在网页和终端之间来回切换。侧栏会把接入了控制台的目录与会话排在前面,目录收起时也能看到控制台标记(与会话行同款方形+座数:空心=已接入,实心=正在对话,两种可同时出现)。

- 目标菜单:多开控制台时列出全部候选(PID、运行状态、打开时间),选定即定向转发;「自动」在只有一座控制台时直接路由
- 方式菜单:控制台忙碌时可选「排队」或「插话」
- 「独立 / 转发」单钮切换,模式按会话记住
TUI 提问面板 · question-panel
/questions 打开浮动面板(停靠右上角):单击条目,transcript 直接跳回那一问;双击 / d 进入回合分析视图(思考→工具→输出节点树);↑↓ 选择、回车跳转、q / Esc 关闭,/questions 60% 调宽度。

注意:对话经历过上下文压缩(compaction)后,早期提问的跳转可能失效——条目仍列在面板里,但 transcript 中已无对应位置。
安装
pi install git:github.com/zhubblego/pi-chat-helper
# 或已发布到 npm:
pi install npm:pi-chat-helper
新开会话生效。pi list 查看已装扩展包,pi remove git:github.com/zhubblego/pi-chat-helper 移除。
运行环境要求 Node >= 22.19(状态库使用 node:sqlite)。
想先试用一次、不写入配置:
pi -e git:github.com/zhubblego/pi-chat-helper
快速上手
安装后两件事开箱即用:
1.TUI 里跳回任意历史提问
/questions
2.浏览器里看会话轨迹
/chat-helper start # 默认 127.0.0.1:7788,全部项目历史 + 全部可用轨迹源
/chat-helper start 7799 # 指定端口(已起实例会先停再起,保证只有一个后台)
/chat-helper status # 查看运行中服务的地址与 pid
/chat-helper stop # 停止服务
服务是独立后台进程(TUI 退出不死,跨项目看全部历史);裁剪/工具归属/聚焦/转发经控制台桥回调到活着的 pi TUI。也可以直接跑:
npm run dev # 等价:node trajectory-web/server/main.mjs --scope all --port 7788
服务承载
唯一入口是 /chat-helper(原 /deepseek-trail 进程内模式已退役):spawn 独立后台进程(main.mjs --scope all,detached),默认端口 7788,TUI 退出不牵连;start 先停后起(探针确认的旧实例全停掉再拉新,含 npm run dev 起的),保证只有一个后台。裁剪/上下文编辑、工具归属、会话聚焦与控制台转发都经桥回调到活着的 pi TUI(心跳 15s TTL)。
轨迹源
| 源 | 位置 | 投影方式 |
|---|---|---|
| pi | ~/.pi/agent/sessions/--<cwd>--/*.jsonl |
原生解析(分支树、工具配对、用量) |
| Codex | ~/.codex/sessions/年/月/日/rollout-*.jsonl |
翻译层:rollout 事件流转成 pi 条目流后复用同一投影(消息、思维、工具配对、压缩、模型切换、思考等级);连续上下文注入合并为一条「系统上下文」事件;跳过 UI 事件流与内部状态 |
列表扫描只读文件头(pi 256KB、Codex 分块增量早停)并用 mtime+size 缓存;live = 30 秒内有写入。服务只读会话文件,仅监听回环地址。
已知限制
- 对话页交互已用 headless Chromium 自动化验证,尚未做真实 Chrome 人工视觉验收。
- 控制台转发只支持启动时已加载 pi-chat-helper 的 pi TUI(旧控制台不 retrofit);转发模式不镜像控制台回答,不携带侧边上下文、模型、技能、profile。
- Codex 的
read_trajectory工具已支持,但 Codex send 上下文链路未做 e2e。 /resume只提供线程选择,不支持重命名/删除;不支持图片/语音/多模态输入。
开发与测试
git clone git:github.com/zhubblego/pi-chat-helper
cd pi-chat-helper
# 开发加载(根 index.ts 是聚合入口,注册 /questions 与 /chat-helper)
pi -e .
pi -ne -e . # 只加载本仓库开发版,不叠加其它已装扩展
# trajectory-web(纯 node,不需要 PI_HOME)
node tests/test-projection.cjs # 投影:分组/工具配对/统计/分支重建/light 截断
node tests/test-sessions.cjs # 会话扫描:列表字段/项目范围/尾部会话名/live/排序
node tests/test-chat.cjs # 对话 host:RPC/线程/SSE/上下文/审批/进程池/安全纯函数
node tests/test-console.cjs # 控制台桥:注册/心跳/状态/token/forward/转发 client 超时
node tests/test-server.cjs # HTTP:多会话列表/指定会话/增量/详情/双范围/热更新/对话/控制台/安全/退出
node tests/test-web-lib.cjs # 前端纯函数:过滤映射/Markdown 转义/会话列表助手/搜索结果高亮切分
node tests/test-codex.cjs # Codex 轨迹源:rollout 扫描/翻译映射(消息/思维/工具配对/redacted/子 agent 派发任务)/投影复用
node tests/test-tool-origins.cjs # 工具归属静态扫描:分组/保护规则/相似度竞争
node tests/test-state-db.cjs # SQLite 状态库:schema/WAL/CRUD/旧 JSON 迁移/权限/降级
# trajectory-web 扩展命令(需要 PI_HOME 提供 jiti)
PI_HOME=<pi 安装目录> node tests/test-extension.cjs
# question-panel(无头,需要 PI_HOME)
PI_HOME=<pi 安装目录> node tests/test-question-panel.cjs
PI_HOME=<pi 安装目录> node tests/test-render.cjs
PI_HOME=<pi 安装目录> node tests/test-turn.cjs
PI_HOME=<pi 安装目录> node tests/test-headless-tui.cjs
# 类型检查(仓库无本地 typescript,用 npx 缓存路径)
# 先把 pi 安装目录的依赖链进来(node_modules 已在 .gitignore,tsc/LSP 靠它解析类型):
# ln -s <pi 安装目录>/node_modules node_modules
node ~/.npm/_npx/483d2954a4c5190c/node_modules/typescript/bin/tsc -p tsconfig.json
环境变量 PI_HOME 指向本机 pi 安装目录:旧布局要求 dist/ 与 node_modules/ 同在 PI_HOME 根。managed install 的 package 目录通常只有自己的 dist/,而 test-turn/test-render/test-question-panel/test-headless-tui 还需要 @earendil-works/pi-tui;可建一个临时 PI_HOME 指向两层:
mkdir -p /tmp/pi-home
ln -s <pi 安装目录>/node_modules /tmp/pi-home/node_modules
ln -s <pi 安装目录>/node_modules/@earendil-works/pi-coding-agent/dist /tmp/pi-home/dist
PI_HOME=/tmp/pi-home node tests/test-turn.cjs
License
MIT。trajectory-web/web/tokens.css 复刻自 deepseek-harness 的 ui-theme(MIT,上游提交 571902028a),上游归属见 LICENSE;它是生成产物,请勿手改。