Pi Coding Agent 上手（二）：Plan Mode、Subagents 与 Workspace History

上一篇装完 Pi CLI 和第一批 Extension，也完成了模型调用。不过那时的 Pi 仍然很接近它所说的 minimal harness：能工作，但 Plan Mode、Goal Mode、Subagent、MCP 和 Workspace History 都要我们自己定制。

这次继续看七个包：

pi install npm:pi-slopchop
pi install npm:@narumitw/pi-goal
pi install npm:@narumitw/pi-plan-mode
pi install npm:pi-subagents
pi install npm:pi-btw
pi install npm:pi-mcp-adapter
pi install npm:pi-workspace-history

这里最需要先处理的是 pi-subagents。上一篇已经安装了 @router-for-me/pi-subagents-lite，两边做的都是 Subagent。我想先弄清楚它们会不会冲突，以及功能更完整的那一个到底多了什么。

1. 七个包各自做什么

截至这次检查，npm 发布版本如下：

Package	版本	主要入口
`pi-slopchop`	0.10.1	`/slopchop`、`/diff`
`@narumitw/pi-goal`	0.24.0	`/goal`
`@narumitw/pi-plan-mode`	0.24.0	`/plan`
`pi-subagents`	0.35.1	`subagent`、`subagent_wait`
`pi-btw`	0.4.1	`/btw`
`pi-mcp-adapter`	2.11.0	`mcp`、`/mcp`
`pi-workspace-history`	0.2.2	`/undo`、`/redo`、`/checkpoint`

我大致按一次开发任务的顺序理解它们：先用 Plan Mode 把事情想清楚，再交给 Goal Mode 或 Subagent 执行；中途有问题，可以开一个 BTW side conversation；做完以后用 Slopchop 看 diff。Workspace History 管 rewind，MCP Adapter 则负责接外部工具。

看起来能拼成一套完整工作流，但它们毕竟来自不同作者。命令能同时出现，不代表状态和生命周期一定配合得好。

2. Slopchop：把 review 留在终端里

pi-slopchop 提供一个终端内的 diff review 界面。它可以检查未提交修改、最后一次 commit，或者当前分支相对默认分支的全部改动。

它不是再启动一个 Agent 做 Code Review，而是让我自己先看 diff，再把意见标到具体行、文件或整个变更上。每条意见分成两种：

FIX：下一轮需要修改；
DISCUSS：只解释、讨论或提出方案，不要为了回应而直接改代码。

完成 review 后，插件只把整理好的反馈放进 Pi 编辑器，不会自动发送。我还可以再改一遍 prompt，然后决定要不要交给 Agent。

/slopchop

也可以使用更短的：

/diff

3. Plan Mode 和 Goal Mode 不是一回事

这两个名字放在一起很容易混淆。Plan Mode 用来收敛方案，Goal Mode 用来把已经明确的任务继续做完。

Plan Mode：先把实现边界说清楚

@narumitw/pi-plan-mode 添加 /plan。进入以后，默认只开放 read、受限的 bash、grep、find 和 ls 等只读工具，并禁用 edit、write 以及其他 Extension 工具。

/plan 设计用户认证缓存的迁移方案

Agent 先检查代码、补齐重要决策，最后通过 plan_mode_complete 提交完整 plan。确认后再执行：

/plan implement

这里的“只读”不是操作系统级 sandbox，只是 Extension 对工具名和 shell 命令做了限制。测试和构建仍可能写缓存；从 /plan tools 手动放进来的第三方工具，也不一定只读。

Plan Mode 默认隐藏 subagent、mcp 这类 Extension 工具。确实需要时可以从 /plan tools 打开，但工具名里带着 search 或 read，不等于它没有副作用。

Goal Mode：让已经明确的任务持续跑到终点

@narumitw/pi-goal 会记录 session 级 goal。在 Pi 完全空闲后，它可以继续触发下一轮，直到 Agent 明确完成、遇到真正的 blocker、达到 token budget，或者被用户暂停。

/goal --tokens 100k 修复失败测试并完成验证

它注册了两个终止工具：

goal_complete：目标确实完成；
goal_blocked：同一个阻塞至少连续出现三轮，并附带具体证据。

比起在 system prompt 里写一句“不要停”，这里至少能看到 goal ID、状态和 token 用量。pause、provider usage limit、budget limit 和 blocker 也被分开记录。

两个包可以一起安装，但不适合同时活动。Plan Mode 会收紧工具集合；正在运行的 Goal 如果看不到自己的终止工具，会主动暂停，不会把工具强行加回来。

需求还有关键决策：先 /plan；
任务已经明确，只需要持续实现和验证：使用 /goal。

4. pi-subagents 多了什么

pi-subagents 内置了 scout、researcher、planner、worker、reviewer、oracle 等角色。最简单的用法仍然是自然语言：

让 scout 先梳理认证流程，再让 planner 给出 implementation plan。

它不只启动单个 Subagent，还能处理：

foreground 和 background task；
parallel、chain 和 dynamic fan-out；
fresh context 与真实 session fork；
worktree 隔离；
Subagent 状态、日志、artifact 与完成通知；
interrupt、resume、wait 和并发上限；
nested delegation 的深度限制；
内置 prompt workflow 和自定义 Agent；
面向其他 Extension 的事件与 RPC。

这已经接近一层 orchestration。相应地，它的工具 schema、配置和运行 artifact 也更多。只想偶尔启动一个 Explore Agent，不一定需要这一整套。

5. 它和 pi-subagents-lite 冲突吗

我把两个包安装进同一个临时 PI_CODING_AGENT_DIR，再用 Pi 0.81.1 离线启动。两个 Extension 都能加载，没有重复工具或重复命令错误。

原因是它们注册的名字不同：

	`pi-subagents`	`@router-for-me/pi-subagents-lite`
主要工具	`subagent`、`subagent_wait`	`Agent`、`StopAgent`、`AgentStatus`
主要命令	`/subagents`、`/run`、`/chain`、`/parallel` 等	`/agents`
内置角色	8 个面向完整开发流程的角色	`general-purpose`、`Explore`
编排	chain、parallel、fan-out、后台任务、调度	前台/后台单 Agent，多次调用可并发
隔离	fresh/fork context，可自动创建 worktree	独立 session，可进入已有 worktree
界面重点	fleet、运行状态和 artifact	直接切换到 Subagent transcript 并继续对话
配置取向	能力和策略较完整	schema 简单、prompt 开销较小

从加载结果看，没有硬冲突。问题出在用起来以后：

模型会同时看到两套意思相近的委派工具，不一定每次都选中预期的那个；
并发、子 session、状态组件和输出文件各管一套，出问题后不太好查；
自定义 Agent 如果默认继承全部 Extension，子进程还可能加载另一套 Subagent 工具；
两边的 Agent 定义、模型配置和状态文件也不通用。

我的结论是：可以共存，但没有必要长期共存。

单看功能，pi-subagents 明显更完整。它有 chain、dynamic fan-out、真实 session fork、自动 worktree、后台控制、Acceptance Gates、watchdog 和更多运行 artifact。Lite 的长处不在功能数量，而是工具少，TUI 里可以直接切换 Subagent transcript，再继续对话。

如果只需要 Explore 和几个简单并发任务，我会保留 Lite。需要把 scout → planner → worker → reviewer 这类流程固定下来，就换成 pi-subagents。

这次我选择后者，先移除上一篇安装的 Lite：

pi remove npm:@router-for-me/pi-subagents-lite
pi install npm:pi-subagents

pi remove 不会把 Lite 的配置迁到 pi-subagents。原来的 ~/.pi/agent/subagents-lite.json 和自定义 Agent 文件还要自己检查。

6. BTW：不打断主任务的 side conversation

pi-btw 会打开一个真实的 Pi sub-session。主 Agent 还在运行时，也能直接提问：

/btw 这个路由是在哪个文件里定义的？

普通 /btw 继承 main session context，并延续同一条 side conversation。/btw:tangent 不继承主对话，适合临时换一个思路。聊出结果以后，可以把完整 thread 交回主 Agent，也可以先生成 summary：

/btw:inject 按刚才的结论继续实现
/btw:summarize 整理成三条检查项

BTW 不是另一套 Subagent orchestration。它更像我主动打开的第二条对话线：主 Agent 继续跑，我在旁边查一个文件、确认一个想法，聊完再决定要不要把结果交回去。

7. MCP Adapter：用一个代理工具按需发现

pi-mcp-adapter 默认只向模型注册一个 mcp 代理工具。MCP server 延迟连接，工具元数据缓存在本地，需要时再搜索和调用：

mcp({ search: "screenshot" })
mcp({ tool: "chrome_devtools_take_screenshot", args: "{\"format\":\"png\"}" })

配置优先读取共享的 ~/.config/mcp/mcp.json 和项目 .mcp.json，也支持 Pi 自己的全局、项目覆盖文件。已经在 Cursor、Claude Code 或 Codex 中配置过 MCP 时，可以用 /mcp setup 选择性导入，而不是手工复制一遍。

少量高频工具可以通过 directTools 直接注册给 Pi。不过每多一个 direct tool，就多一份 schema 进入上下文。我准备先用 proxy，碰到确实经常调用的工具再单独提升。

MCP server 可以启动进程、访问网络、读取凭据，远程 server 还可能要求 OAuth。lazy 只是延迟连接，不会缩小权限。项目里的 .mcp.json 仍然要先看再用。

8. Workspace History：最值得谨慎验证的一个

pi-workspace-history 在每轮 Agent 前后保存 workspace snapshot，并把它与 session history node 关联起来：

/checkpoint 手动修改完成
/undo
/redo

它使用独立的 shadow Git，不会往项目自己的 Git history 写 commit。检测到尚未 snapshot 的手动修改时，它会阻止切换，要求先创建 checkpoint。这样 /undo 回退的不只是 conversation，workspace 也会回到同一个 history node。

这个包我暂时不敢直接启用。版本 0.2.2 的 peerDependencies 仍然声明：

@mariozechner/pi-coding-agent: ^0.70.5

当前使用的是 @earendil-works/pi-coding-agent 0.81.1。隔离测试中，它能安装，也能完成基础启动；源码里的旧依赖只是 TypeScript type import。但这些结果证明不了 /undo、/redo、/tree event 和 workspace restore 已经兼容。

restore 会直接修改 workspace。我准备先在一次性 repo 里验证：

tracked、untracked 和 ignored 文件的快照范围；
Agent 修改后的 /undo 与 /redo；
两轮之间存在手工修改时的 dirty guard；
/tree 在不同 history branch 之间切换；
多个 Pi session 是否保持隔离。

基础加载成功，只能说明 Extension API 没有立即报错。就算这些 restore 测试都通过，重要改动还是要先交给项目自己的 Git。

9. 最后保留的组合

最后不保留两套 Subagent。安装命令整理成下面这样：

pi remove npm:@router-for-me/pi-subagents-lite

pi install npm:pi-slopchop
pi install npm:@narumitw/pi-goal
pi install npm:@narumitw/pi-plan-mode
pi install npm:pi-subagents
pi install npm:pi-btw
pi install npm:pi-mcp-adapter
pi install npm:pi-workspace-history

装完以后我先跑了 pi list，七个包都在，Lite 已经不在列表里。Pi 启动时没有报 Extension 加载错误，--plan 和 --mcp-config 也能出现在帮助信息里。旧会话要执行一次 /reload，新会话直接打开就行。

安装过程中 npm audit 报了 3 个 moderate。我继续查了一下，实际是同一个 @hono/node-server 漏洞沿依赖链重复计数，不是三个独立问题。它只影响 Windows 上特定的 serve-static 用法，我现在用的是 Linux，不在它的触发条件里。暂时不用为了这条警告移除 Extension，等上游更新依赖就可以。

所以这轮确认的是“能安装、能加载”，还不是“这套组合已经稳定”。Plan Mode、Goal Mode 和 Subagent 放在一起会不会互相改变工具状态，得等实际任务跑起来才知道。Workspace History 会直接恢复工作区，我还是先拿一次性 repo 测。用过一轮以后，再决定哪些留下。