pi-desktop-transcript

✨ 功能

• 四套内置方案 —— detailed（默认过程流）/ focus / zen / native，一条命令切换，不用改代码。
• 规则可覆盖到单个工具 —— 每一类工具、每一个具体工具名，都能单独设成摘要 / 单行 / Pi 原生渲染；Pi 原生是否完整展开仍由 Pi 自己的工具输出开关决定。
• 过程轨道 —— 插件内容统一带弱化 │ 轨道，动作标题使用 Pi 的 toolTitle，参数使用 muted，和无轨道的最终 Markdown 回答明确分开。
• 可读过程流 —— 默认用 Read File、Search Files、Edit File、Run Command 等语义标签保留每一步；长路径从中间收起，始终保留文件名，编辑行分别着色显示 +N -N。
• 动态活动区 —— 编辑器上方最多 4 行（可调 1~6），Thinking 约 800ms、Working 400ms 切换一帧；只在运行时动画，结束立即停止，也可用 animateActivity 关闭。活动区包含 current 时会自动隐藏 Pi 重复的内置 Working...；zen 等不显示当前动作的配置仍保留它。
• 完成收束 —— 一轮结束后用 ╰─ ✓ 单行元信息展示完成状态、修改文件、命令、失败和步骤；focus / zen 运行中保留编辑、命令和未知工具的一行轨道，结束后再折叠成功步骤。
• 关键工具豁免 —— subagent、subagent_spawn、goal_complete、goal_blocked、goal_wait 始终保持 Pi 原生渲染；失败和提问至少保留一行，不能被覆盖规则静默隐藏。todo 更新行在紧凑方案中隐藏，避免和固定 Todo 列表重复。
• 随时还原 —— Ctrl+O 按 Pi 原生行为切换所有工具输出的展开状态，/desktop-transcript off 一键回到 Pi 原始显示。
• 参数脱敏 —— 摘要里的 TOKEN=…、--api-key …、Bearer … 显示为 ***，对所有工具生效，包括未识别的工具和 MCP 调用。
• 中英双语 —— 计数与总结的文案默认跟随 shell 语言环境，可用 lang 固定。

📸 效果

执行中，编辑器上方固定不超过 4 行；内容来自实际事件，不生成假的进度：

│ ◑ 思考  正在追踪 token 失效路径… · 12s  ← 慢速 Thinking 动画
│ ⠹ Run Command $ npm test                ← Working 动画
│   ↳ 12 passing                          ← 最新有效输出（脱 ANSI/脱敏）
│   读取 4 · 搜索 3 · 命令 1 · 42s         ← 计数器 + 时长

默认 detailed 会把插件范围内的 Agent 输出组织成过程流：

│ ⌕ Search Files "invalidate" · src
│ ▤ Read File src/api/auth.ts
│ ✎ Edit File src/api/auth.ts +2 -1
│ › Run Command $ npm test

已修改 `auth.ts` 的 token 失效逻辑。          ← Pi 原生最终回答，无轨道

╰─ ✓ 已完成 · 42s · 修改 auth.ts、lib.ts · 命令 Run Command $ npm test ✓ · 步骤 读取 4 · 搜索 3 · 修改 1 · 命令 1

focus / zen 会把读取和搜索压成摘要，但运行中的编辑、命令和未知工具仍保留一行；完成后成功行按 keep-failures 收束。

native 不精简任何工具行，保持 Pi 原生输出，但保留活动区和结束总结。临时调试可用 /desktop-transcript session native，不会改动持久方案。

工具分类表（决定配置里哪条规则管它）：

分类	工具
read	read、ls
search	grep、find、web_search、source_check、get_search_content、fetch_content、只读 bash（ls/cat/git status/npm view 等）
mutation	edit、write、replace、lsp_fix、figma 渲染与导出
command	其余 bash、mcp 调用、mcpScript
interactive	ask_user_question、plan_mode_*
other	其余未识别的工具
protected	subagent、subagent_spawn、goal_complete、goal_blocked、goal_wait

失败的工具行走单独的 failure 规则，不受它原本分类的影响。

📦 安装

要求 Pi ≥ 0.84、Node ≥ 22。

pi install npm:pi-desktop-transcript

也可以直接装 Git 仓库：

pi install git:github.com/nanvon/pi-desktop-transcript

装完重启 Pi，进入后执行 /desktop-transcript status，看到 patch installed 即生效。

卸载：

pi remove npm:pi-desktop-transcript

[!TIP] Pi 隐藏完整 thinking 时，扩展会同时移除隐藏块遗留的空行，并在活动区展示模型真实 thinking 头部（默认两行，/desktop-transcript thinking <1-4> 可调行数）；Pi 显示完整 thinking 时，这份预览自动消失，避免重复。Ctrl+T 会实时同步两者。hideThinkingBlock 与 outputPad 仍是 Pi 自带设置，按喜好开。

📋 用法

操作	效果
Ctrl+O	按 Pi 原生行为切换所有工具输出的展开状态（再按收起）
Ctrl+T	切换完整思考块（Pi 原生功能）
/desktop-transcript status	查看开关、方案与补丁是否生效
/desktop-transcript config	打印当前实际生效的全部规则，* 标出你的覆盖
/desktop-transcript preset <focus|detailed|zen|native>	切换并持久保存方案
/desktop-transcript session <focus|detailed|zen|native|reset>	只在当前会话临时切换，reset 回到已保存方案
/desktop-transcript show <分类|工具名> <hidden|line|full>	覆盖单条规则
/desktop-transcript settle <collapse|keep-failures|keep>	一轮结束后如何处理工具行
/desktop-transcript rows <1-6>	调整活动区最大行数
/desktop-transcript thinking <1-4>	活动区 thinking 预览行数（默认 2）
/desktop-transcript lang <auto|en|zh>	切换计数与总结的语言
/desktop-transcript reset	清掉所有覆盖，回到纯方案
/desktop-transcript on / off	启用 / 关闭精简视图

举几个例子：

/desktop-transcript preset zen          # 以后默认只看结果
/desktop-transcript session native      # 当前会话临时查看完整过程
/desktop-transcript show search line    # 搜索我想看见
/desktop-transcript show web_search full # 唯独联网搜索交给 Pi 原生渲染
/desktop-transcript settle keep         # 结束后什么都别折叠

除 session 外，命令改动会立即写回配置文件，重启后仍然有效；写入失败时会明确提示，并在当前会话继续使用未保存的设置。

🔧 配置

配置分两层：先选一套方案，再按需覆盖单条规则。没写的键跟着方案走 —— 所以换方案时，你没手动改过的项会自动跟着变。

三种显示档位

档位	含义
hidden	零高度，普通工具只进计数；仅适合读取/搜索等低风险噪声（todo 更新不计数）
line	单行摘要；运行中的编辑、命令和未知工具默认保留此级别
full	Pi 原生渲染；是否显示完整输出仍由 Pi 的展开状态决定

四套方案

方案	读 / 搜	改 / 命令	提问	失败	结束后	活动区
detailed（默认）	line	line	line	line	全部保留	4 行
focus	hidden	line	line	line	只留失败/提问	4 行
zen	hidden	line	line	line	只留失败/提问	2 行
native	full	full	full	full	全部保留	4 行

protected 工具在所有方案里都是 full，而且按工具覆盖也不能把它们降级；失败和提问至少是 line，不能被静默隐藏。todo 按 other 分类，但仍会被专门隐藏以避免和固定 Todo 列表重复。

focus / zen 只把读取和搜索压成摘要；编辑、命令和未知工具在运行中保留一行，keep-failures 会在结束后折叠成功行。zen 的活动区仍特意换成「思考 + 计数」两行，让终端保持安静，但不会让正在执行的关键动作完全消失。

过程总结只使用本轮已发生的工具事件，不额外调用 LLM：成功修改最多列出三个文件名，命令最多列出两个并带 ✓/✕ 状态，更多内容折叠成数量；失败时显示最后一个失败步骤及其余失败数量。

配置文件

~/.pi/agent/desktop-transcript.json（权限 0600，原子写入；文件不存在时用默认值，session_start 与 agent_start 时热加载）：

{
  "preset": "detailed",              // 方案；其余键不写就跟着它走
  "display": { "search": "line" },   // 按分类覆盖
  "tools": { "web_search": "line" }, // 按工具名覆盖，优先级最高
  "onSettled": "keep-failures",      // collapse | keep-failures | keep
  "activityLines": ["thinking", "current", "counters"], // 可重排、可删、可空
  "activityRows": 4,
  "thinkingLines": 2,               // 活动区 thinking 预览行数，1-4
  "animateActivity": true              // false 时使用静态 ◌ / ›
}

优先级与显示底线

普通规则的生效顺序是 方案 → display → tools，后者覆盖前者；但重要内容有最低可见级别：

1. 失败和交互至少显示一行 —— tools 或 display 里的 hidden 会被提升为 line。
2. 受保护工具始终使用 Pi 原生渲染 —— subagent、subagent_spawn、goal_complete、goal_blocked、goal_wait 不能被降级隐藏。
3. Ctrl+O 不受本插件配置影响 —— 按 Pi 原生行为切换所有工具输出的展开状态，它不是单行展开按钮。

全部键

键	默认	说明
enabled	true	总开关；false 时补丁仍在但不改变渲染
preset	"detailed"	方案名；已有配置继续使用已保存值
display	{}	按分类覆盖，键取自上面的分类表，外加 failure 与 protected
tools	{}	按工具名覆盖（server.tool 与 tool 等价）
onSettled	跟随方案	collapse 折叠成功普通行（失败/提问仍保留） / keep-failures 只留失败与提问 / keep 全保留
activityLines	["thinking","current","counters"]	活动区显示哪几行、什么顺序；thinking 仅在 Pi 隐藏完整思考时出现，空数组表示不显示活动区
activityRows	跟随方案（detailed 默认 4）	活动区最大物理行数，硬上限 6
language	"auto"	auto 跟随 LC_ALL/LANG，也可写死 en 或 zh
thinkingPreviewChars	110	每行 thinking 头部截断长度（行数由 thinkingLines 决定）
thinkingLines	2	活动区 thinking 预览行数，1–4
showDurations	true	是否显示思考与整轮时长
animateActivity	true	Thinking / Working 是否在活动区动态切帧；关闭后使用静态符号
highlightMutations	true	是否强调历史轨道中的修改标记
showFinalRunSummary	true	结束后追加 ╰─ ✓ 单行运行元信息
redactSensitiveArguments	true	摘要中脱敏 token、密钥与 Bearer 凭据

$PI_CODING_AGENT_DIR 有值时，配置文件跟着走。

🔒 安全与降级

• 只改执行显示 —— 不注册或替换工具，不修改工具参数、工具结果或模型上下文；off 可完整还原。插件会追加自己的 summary/config custom entry 供 session 显示，但 Pi 不会把这类 entry 送进 LLM 上下文。
• 版本守卫 —— 加载时从 pi 包的 package.json 探测版本，低于 0.84.0，或工具行 / Assistant 消息原型形状不符时，对应补丁会安全跳过，绝不猜测或隐藏内容；status 会打印跳过原因。
• 与同类扩展共存 —— 其他同样改写工具行渲染的扩展（例如 pi-zentui）可以和它一起启用，互不覆盖；本扩展退出时只撤走自己的改动，把渲染交还成接手时的样子。
• 配置有下限 —— 失败和交互至少显示一行，受保护工具始终是 Pi 原生渲染；按工具覆盖只能让它们更显眼，不能降级隐藏。普通读取/搜索可以在 focus / zen 中压成摘要。
• 脱敏 —— XXX_TOKEN=…、api_key: …、--token …、Bearer … 在摘要里显示为 ***。开关是 redactSensitiveArguments，对每个工具的摘要统一生效（不只是 shell 命令），且在截断之前完成，不会留下密钥的前半截。这是显示层的兜底，不能替代不在命令行里写明文密钥的习惯。
• 不伪造内容 —— 活动区只取模型实际输出的 thinking 块头部（默认两行，行数可配）；命令输出只取工具事件里的最新非空行，并清理 ANSI/控制字符后脱敏。提供商不返回可见 reasoning 时不显示 thinking 行。

已知边界：

1. 补丁只影响新的渲染，历史会话里已有的工具行不会变形。
2. 并行工具在活动区最多列出 4 个名称，更多以数量为准。
3. Pi 若改动 ToolExecutionComponent 或 AssistantMessageComponent 的内部形状，对应显示补丁会安全降级，而不是显示错乱。

🤝 参与开发

欢迎提 issue 和 PR。开发环境、代码结构与测试见 CONTRIBUTING.md，参与前请读 行为准则。

发现安全问题请勿公开提 issue —— 见 SECURITY.md 里的私有报告通道。

🙏 致谢

渲染区域的处理参考了这几个同类扩展：

• @zenspc/pi-quiet —— 工具行精简的基本思路。
• pi-quiet-activity —— 活动区 widget 的形态。
• pi-zentui —— 原型补丁的 owners 共存机制。

📄 许可证

MIT