2026-07-19 Plan Workflow Extension

Plan Mode:先想清楚,再动手改

给 agent 一套「先调研再动工」的制度。

导语

/plan 的价值不是多一个命令,而是给 agent 一套「先调研再动工」的制度:写工具暂时没收,计划可见可批,执行进度可盯。

问题背景

agent 失败常不是写不出代码,而是过早动手、范围失控、进度不可见、compaction 丢计划。Plan Mode 解决工作流:先只读探索,再审批执行。

@piex-dev/plan/plan 切换模式,/todos 看清单,footer 显示进度。

技术原理

计划模式从 active tools 拿掉 edit/write,并对 bash 做危险命令拦截。解析 Plan: 编号列表;执行期用 [DONE:n] 推进。状态经 appendEntryPLAN.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-modepi plan-mode 示例piex plan
/plan 命令
只读工具限制
危险 bash 拦截
Todo 提取
执行进度追踪
Footer 状态
Widget 进度
状态持久化✅ appendEntry✅ appendEntry + PLAN.md
会话恢复
快捷键Shift+PCtrl+Alt+PShift+Alt+P
写计划到文件✅ PLAN.md
计划审批弹窗❌ select 替代
Plan TOC 侧栏
子 agent 计划传递
Compaction 保护✅ appendEntry

piex plan 的策略:坚守 pi 示例同源路线,用 appendEntry 跨 turn 持久化 + PLAN.md 落盘补 compaction 缺口;放弃 omp 重 UI。