plan — 先想清楚，再动手改

简介

让 agent 直接改代码，常见失败模式不是「写不出代码」，而是：过早动手（仓库没摸清就 edit）、范围失控（小需求扯出半个重构）、进度不可见、上下文压缩丢状态。Plan Mode 解决的是工作流问题：先只读探索 → 产出可审批的编号计划 → 用户点头后再全工具执行 → 用 [DONE:n] 推进进度。

技术原理

两种模式两套工具边界：Plan 模式只留 read/bash(受限)/grep/find/ls，禁用 edit/write——不是提示词劝导，而是真正从 active tools 拿掉写工具。Execution 模式恢复全工具。

bash 走白名单 + shell 词法分析（默认拒绝、按规则放行）：按 ;|&& 分段，重定向/子 shell/命令替换/变量展开/glob 一律拒绝；只读命令直接放行，git/find/sed/npm 带专属参数校验器。从「拦已知坏」换成「只放已知好」，绕过面收敛到白名单本身。

计划与提问走结构化工具 plan_complete/plan_question，从工具参数直取，Plan: 正则作 fallback。状态用 appendEntry 扛 compaction，计划落 PLAN.md；指令走 systemPrompt 每 turn 重建，消息历史不留 plan 制品。

使用说明

安装

pi install npm:@piex-dev/plan

仓库源码：extensions/plan

配置

plan 有额外 peer 依赖：@earendil-works/pi-tui、@earendil-works/pi-agent-core、@earendil-works/pi-ai（TUI 集成），不同于其他扩展仅需 pi-coding-agent。

用法

/plan
  → 只读探索（plan_question 澄清关键决策）
  → plan_complete 提交完整计划（含 Plan: 编号步骤）
  → UI 提供 Execute / Stay / Refine 选择
  → Execute：打开全工具，按步执行
  → [DONE:n] 推进
  → 全部完成提示 Plan Complete

辅助命令：/todos 开关 todo widget；CLI flag plan 启动即进入 plan mode。

验证

pi -e ./extensions/plan/src/plan.ts -p "what is 1+1" --no-session

实现方案

入口约 1430 行单文件。piex 里「扩展 API 用得最全」的包之一：registerCommand/registerTool/setActiveTools/on("tool_call") 拦截/on("before_agent_start") 注入 systemPrompt/on("turn_end") 解析 [DONE:n]/appendEntry 持久化/ctx.ui.select 交互。

工具集合并：进入 plan 记住 toolsBeforePlanMode，计划工具集 =（原 active 去掉 edit/write）∪ 只读工具集；退出时恢复并保留其它扩展注册的工具，与 hashline/lsp/dap 共存不误杀。

轻量的好处：依赖面小、行为可预测、和上游 pi 示例同源好维护。

设计参考

核心取舍：坚持 pi 示例同源路线（轻、可预测、好维护），放弃 omp 式重 UI；用 appendEntry 扛 compaction。

迭代记录

路线图

版本记录

0.1.1 教训：正则黑名单拦不住等价绕过，正文正则提取计划在模型不按格式输出时会漏，context 消息注入会被 compaction 吞掉。0.2.0 换成结构化方案：白名单收敛绕过面、工具参数取代正文解析、systemPrompt 取代消息注入。

附录：pi plan 生态能力逐项对比

四个项目（omp / pi 官方示例 / pi-extensions pi-plan-mode / piex plan）的客观能力差异。