Plan Mode:先想清楚,再动手改
给 agent 一套「先调研再动工」的制度。
导语
/plan 的价值不是多一个命令,而是给 agent 一套「先调研再动工」的制度:写工具暂时没收,计划可见可批,执行进度可盯。
问题背景
agent 失败常不是写不出代码,而是过早动手、范围失控、进度不可见、compaction 丢计划。Plan Mode 解决工作流:先只读探索,再审批执行。
@piex-dev/plan:/plan 切换模式,/todos 看清单,footer 显示进度。
技术原理
计划模式从 active tools 拿掉 edit/write,并对 bash 做危险命令拦截。解析 Plan: 编号列表;执行期用 [DONE:n] 推进。状态经 appendEntry 与 PLAN.md 扛 compaction。
实现方案
单文件扩展,重度使用 registerCommand/Shortcut、setActiveTools、tool_call 拦截、before_agent_start 注入、turn_end 解析、UI status/widget。相对 omp 全屏 overlay 有意做轻。
设计参考
| 项目 | 机制 | piex 取舍 |
|---|---|---|
| pi 官方 plan-mode 示例 | registerCommand + setActiveTools + tool_call 拦截 bash | 采纳核心 API 方案:工具切换、bash 拦截、DONE 标记解析。 增强:appendEntry 跨 turn 持久化 + PLAN.md 落盘 + UI widget |
| oh-my-pi plan | 全屏 plan-review overlay + TOC 侧栏 + 子 agent handoff | 不采纳:pi API 不支持全屏 overlay,子 agent 未就绪。借鉴:步骤审批(改 select 交互)、工具白名单可配置、与 review 联动 |
核心取舍:坚持 pi 示例同源路线(轻、可预测、好维护),放弃 omp 式重 UI;用 appendEntry 扛 compaction。
优化计划
更稳计划 IR(可选 JSON);DONE 弱验证;与 /review 收尾联动;PLAN.md frontmatter;工具白名单可配置。黑名单不是沙箱。
附录:omp 与 pi plan-mode 能力逐项对比
来源:迁移预研文档,记录两项目能力差距以供实现与演进参考。
| 能力 | omp plan-mode | pi plan-mode 示例 | piex plan |
|---|---|---|---|
| /plan 命令 | ✅ | ✅ | ✅ |
| 只读工具限制 | ✅ | ✅ | ✅ |
| 危险 bash 拦截 | ✅ | ✅ | ✅ |
| Todo 提取 | ✅ | ✅ | ✅ |
| 执行进度追踪 | ✅ | ✅ | ✅ |
| Footer 状态 | ✅ | ✅ | ✅ |
| Widget 进度 | ✅ | ✅ | ✅ |
| 状态持久化 | ✅ appendEntry | ✅ | ✅ appendEntry + PLAN.md |
| 会话恢复 | ✅ | ✅ | ✅ |
| 快捷键 | Shift+P | Ctrl+Alt+P | Shift+Alt+P |
| 写计划到文件 | ✅ | ❌ | ✅ PLAN.md |
| 计划审批弹窗 | ✅ | ❌ | ❌ select 替代 |
| Plan TOC 侧栏 | ✅ | ❌ | ❌ |
| 子 agent 计划传递 | ✅ | ❌ | ❌ |
| Compaction 保护 | ✅ | ❌ | ✅ appendEntry |
piex plan 的策略:坚守 pi 示例同源路线,用 appendEntry 跨 turn 持久化 + PLAN.md 落盘补 compaction 缺口;放弃 omp 重 UI。
源稿 Markdown: docs/notes/plan.md