pi-plan-mode

pi 的计划模式扩展：强制只读探索模式 + 计划提取 + 执行进度跟踪。

开启计划模式后安全地探索代码库，让模型输出编号计划，然后一键执行——模型每完成一步标记 [DONE:n]，侧边 widget 实时显示进度。

English

特性

• 硬性只读保证——三层独立防线：
  1. 工具层：从活动工具集中移除 edit/write/computer_use*
  2. 命令层：每条 bash 命令必须通过严格白名单（安全命令且不含破坏性模式）
  3. 提示层：明确告知模型处于只读模式
• bash 白名单：只允许单个只读命令——禁止重定向、管道、命令链接、命令替换、多行脚本；curl 仅限 GET 查询
• 计划提取：从 Plan: 段落提取编号步骤
• 执行跟踪：[DONE:n] 标记 + 实时进度 widget（☑/☐）
• 会话持久化：状态跨会话恢复，恢复后重扫 [DONE:n]
• 子代理支持：计划模式下 subagent 保持可用，子 pi 进程继承同样的只读限制（需要带计划模式传播的 subagent 扩展，见下文）
• CLI 参数：pi --plan 直接以计划模式启动

安装

pi install npm:@adamcjm/pi-plan-mode

或仅本次运行：

pi -e npm:@adamcjm/pi-plan-mode

安全提示： 扩展以完整系统权限执行任意代码，安装前请审查源码。

使用

1. 开启计划模式：/plan   （或 Ctrl+Alt+P，或启动时加 --plan）
2. 让模型分析代码并生成计划
3. 模型在 "Plan:" 标题下输出编号计划：

   Plan:
   1. 第一步做什么
   2. 第二步做什么
   3. 第三步做什么

4. 弹窗选择"执行计划"（也可先"完善计划"）
5. 执行中模型每完成一步标记 [DONE:n]
6. 进度 widget 显示 ☑/☐ 完成状态

命令

| 命令 | 说明 | |------|------| | /plan | 切换计划模式 | | /todos | 显示当前计划步骤与进度 | | Ctrl+Alt+P | 切换计划模式 |

状态机

IDLE ──/plan──▶ PLAN（只读探索）
PLAN ──"执行计划"──▶ EXECUTE（完整工具 + [DONE:n] 跟踪）
EXECUTE ──全部完成──▶ IDLE（完成消息）
PLAN ──"完善计划"──▶ 回到 PLAN（编辑器输入反馈）

只读保证

纵深防御，计划模式无法写入、修改或删除文件：

1. 工具列表：edit、write、computer_use* 从活动工具中移除。进入前的工具集快照保存，退出时原样恢复（自定义工具不受影响）。
2. bash 过滤：每条命令必须同时满足：在白名单中、不含破坏性模式。
3. 提示词：模型收到明确的只读指令。

bash 白名单（放行）

| 类别 | 命令 | |------|------| | 文件查看 | cat、head、tail、less、more、strings、xxd、hexdump、md5、shasum | | 搜索 | grep、find、rg、fd | | 目录 | ls、pwd、tree、du、df | | git 只读 | status、log、diff、show、blame、grep、rev-parse、describe、remote -v、config --get | | 包信息 | npm list/view/audit、pip list/show、pnpm outdated、brew info | | 版本检查 | node --version、python3 --version、go version、java -version、rustc --version | | 系统信息 | uname、whoami、date、ps、uptime | | 网络 | curl 仅 GET 查询、wget -O -（仅输出到 stdout） |

拦截（写 / 改 / 删 / 执行）

• 文件操作：rm、rmdir、mv、cp、mkdir、touch、unlink、ln、chmod、chown、chflags、truncate、tee、dd、shred、install、mkfifo、重定向 > >>
• git 写操作：commit、push、add、fetch、merge、reset、checkout、stash、remote add/set-url、clean、worktree add（含 git -C dir ... 变体）
• 包安装：npm install、npm audit fix、yarn add、pip install、brew install
• curl 写标志：-o、-O、-d、-T、-F、-X POST/PUT/PATCH/DELETE、--output、--data*、--cookie-jar
• 执行：shell（sh、bash、zsh…）、python -c、node -e、osascript、eval、source、find -exec/-delete
• 命令链接：; && || | &、反引号、$(...)、多行命令
• 系统：sudo、doas、kill、reboot、systemctl restart
• 编辑器/应用：vim、nano、nvim、code、open

子代理集成

计划模式下 subagent 保持可用。subagent 扩展检测计划模式（持久化的会话状态），spawn 子 pi 进程时附加 --plan；子进程在同样的只读限制下运行（写工具被剥离、bash 被过滤）。嵌套子代理通过 PI_SUBAGENT 环境变量逐层传播。

这需要带计划模式传播逻辑的 subagent 扩展：

// subagent 工具的 execute() 中：
const planModeActive = /* 从会话条目或 PI_SUBAGENT 环境变量读取 */;
if (planModeActive) args.push("--plan"); // 子 pi 进程

开发

git clone [email protected]:adamcjm/pi-plan-mode.git
cd pi-plan-mode
bun extensions/plan-mode/test_utils.ts   # 153 个过滤断言

命令过滤器位于 extensions/plan-mode/utils.ts（纯函数）；修改白名单/黑名单时同步扩展 test_utils.ts。

License

MIT