# plan-mode

为 `@hex4c59/pi-ext-permissions` 提供“调查 → 保存计划 → 用户审批 → 实施”的可选工作流，由 permissions 包中的独立 plan-mode 扩展入口实现。与权限审批一同加载，不再作为独立 Pi 包安装或发布。已针对 Pi **1.5.0 / 1.5.2** 验证。本地使用，不需要 Claude Code、额外模型或第三方运行库。

流程参考 Codex CLI 的开源计划提示词、`Proposed Plan` 对话卡片与底部实施选择，用 Pi 原生扩展接口实现。固定源码版本与本地适配见 [THIRD_PARTY.md](../THIRD_PARTY.md#plan-mode-参考来源)。

## 安装与使用

在本仓库根目录安装 permissions 包：

```sh
pi install ./permissions
```

随后在已有 Pi 会话中执行 `/reload`，或重新启动 Pi。该包同时加载 permissions 与 plan-mode 两个扩展入口。临时试用：

```sh
pi -ne -e ./permissions --plan
```

日常流程：

1. 在 Auto 下输入“先给方案，批准后再实现”或“写详细实施计划”，空闲时会直接开始只读规划。也可用 `/plan on` 或 `--plan` 手工进入。
2. 模型先调查现有实现，再澄清会改变范围、接口或验收标准的选择。决定完整后，用 `save_plan` 保存一份可交给另一位工程师直接实施的 Markdown。
3. 模型单独调用 `exit_plan_mode` 提交计划，当前运行先停下来。TUI 在对话中显示完整的 `Proposed Plan`，用主题底色区分正文。对话记录保留原任务和修改意见，长计划可用 Pi 的原生滚动查看。
4. 输入框位置显示 `Implement this plan?`，默认选中 `Yes, implement this plan`，按 Enter 确认实施当前版本。可用上下键或 `1` / `2` / `3` 切换选项，fullscreen 下也可单击选项。Fullscreen 的滚轮和 PageUp / PageDown 滚动对话，regular 使用终端滚动历史。
5. 选择 `Revise plan`、按 Tab 或直接输入文字，会在底部打开单行意见框，支持中文和粘贴。Enter 发送意见并继续规划。Esc 返回菜单并保留本次输入，再按 Esc 关闭审阅。每次修订提交完整的新版本，实施前都要确认该版本。
6. 批准后自动继续实施，恢复进入前的工具清单；模型通过 `plan_progress` 更新步骤，全部完成后清除计划状态。使用 `/plan status` 查询模式和步骤进度。

审批没有自动通过或自动超时机制。普通文字中的“计划已批准”、工具返回中的许可说明、`exit_plan_mode` 的调用本身都不会切换到实施状态。其他基础模式沿用进入确认。手工 `/plan on` 和启动参数 `--plan` 直接进入规划。

自动分流的条件、5 秒分类时限和直接实施指令见 [Auto 下的计划分流](../README.md#auto-下的计划分流)。批准当前版本后恢复基础工具和权限审查。已有活动计划可继续修订，自动开始的新任务使用空草稿。

## 计划正文

计划用用户的语言撰写。标题下通常包含摘要、实施变更、测试计划和适用的假设。简单任务保持简短。复杂任务写清受影响的接口或模块、数据怎样流转、关键边界和失败处理，以及适用的迁移或上线步骤。测试写明操作和预期结果，例如重启客户端后校验旧配置仍能读取，而不只写「运行测试」。

`save_plan` 的 `markdown` 是完整正文。扩展保留标题、列表、表格、代码块和段落结构，统一换行为 LF。`steps` 是按实施顺序排列的进度项，供 `plan_progress` 引用。审阅、保存文件和 Guardian 的计划证据均使用同一份正文。

## 命令和工具

| 命令 | 行为 |
| --- | --- |
| `/plan` | 空闲时切换计划模式 |
| `/plan on` | 进入计划模式；已有草稿可继续修改 |
| `/plan off` | 手工结束计划限制，恢复原工具清单；不标记计划已批准，也不自动开始实施 |
| `/plan show` | 在会话中显示当前分支的计划快照与文件路径 |
| `/plan status` | 查看模式、计划路径、进度和本分支信任的工具 |
| `/plan approve` | 重新打开当前计划的审阅界面，实施前须明确确认当前版本 |
| `/plan allow <tool>` | 明确信任一个已注册工具，可在当前分支中用于调查 |
| `/plan revoke <tool>` | 撤销上面的额外信任 |
| `Ctrl+Alt+P`（配合 permissions） | 空闲时按 `ask → plan → navigator → auto → full → ask` 循环；plan-mode 未加载时跳过 plan；从 plan 切到其他权限会结束限制，不批准计划或自动实施 |
| `--plan` | 启动、新建或恢复会话时进入计划模式；`/reload` 恢复已保存状态，不重复覆盖已批准的执行状态 |

执行过程中先用 Esc 中断，再切换模式。`/plan off` 是显式结束计划限制的入口；审阅中的“继续规划”只关闭当前审阅，仍保持只读。修改计划后需再次提交并由用户批准，只有批准当前版本才会自动继续实施。

| 模型工具 | 职责 |
| --- | --- |
| `enter_plan_mode` | 单独调用。符合条件的 Auto 任务可在只读调查后直接进入。其他情况沿用进入确认 |
| `save_plan` | 用 `markdown` 保存完整的新版本，用 `steps` 指定按顺序跟踪的进度项 |
| `exit_plan_mode` | 提交当前版本并结束当前运行，必须单独调用 |
| `plan_progress` | 实施期间将指定 `step` 标为 `done` 或 `pending` |

计划最多 30 步，每步一行、最多 512 个字符；完整 Markdown 最多 32KiB / 1000 行。没有针对某个固定模型的配置，也不改变 provider、模型或 thinking level。步骤完成情况由模型报告，不等于独立测试证据；最终回复仍应说明实际验证结果。

## 计划模式下的工具边界

本包同时管理活动工具清单和实际的 `tool_call` 检查。隐藏、动态加载或由其他工具嵌套调用的工具也经过检查。codemode 本身在计划期间停用。

| 入口 | 默认行为 |
| --- | --- |
| Pi 内置 `read`、`grep`、`find`、`ls` | 可用，进入计划时补充启用；同名自定义覆盖不会自动继承许可 |
| Pi 内置 Bash | 只接受单条字面命令：`pwd`、有限选项的 `ls`、明确带 `--no-config` 的有限选项 `rg` |
| PowerShell、测试、构建、安装及任意脚本 | 计划期间阻止，批准后使用原有工具和权限 |
| `edit`、`write`、`lsp_apply` | 计划期间阻止；写计划只走 `save_plan` 的固定存储入口 |
| 当前 `@ian-pascoe/pi-lsp` 的状态、诊断、悬停、定义、引用、符号查询 | 可用，核对工具来源路径 |
| 该包的 `lsp_rename`、`lsp_code_actions` | 可创建 Workspace Edit Preview；应用预览仍被阻止 |
| `pi-web-search` 的 `web_search` 和本仓库 Qoder / WorkBuddy 搜索工具 | 核对来源后可用 |
| Pi 内置 tool_search | 保留原有启用状态；动态发现工具不会绕过实际调用检查 |
| codemode | 计划期间停用；其 `models.generateImages()` 等入口不经过嵌套工具事件，批准后恢复原有启用状态 |
| 其他 MCP、自定义工具 | 默认阻止；不自动采信 `readOnlyHint` |
| 用户 `!` / `!!` Shell 命令 | 计划期间阻止；需要手工 `/plan off` 后运行 |

若 permissions 基础模式为 Navigator，外层权限门仍保持项目只读：经核实来源的内置 `read` 在工作目录内自动放行，越界或无法自动确认时由 permissions 询问 `Allow once` / `Deny`；内置 `ls` 列出工作目录外或无法自动确认的目录时也会询问，`find` / `grep` 等其他内置读取仍按工作目录范围检查。用户显式进入 plan 后，planning / review 期间只有 `save_plan` 与 `exit_plan_mode` 两个固定计划流程工具交由 plan-mode 处理；模型调用的 `enter_plan_mode`、`plan_progress`、项目写入、测试和构建仍会阻止。计划批准不改变基础 Navigator 权限；需要实施时先切换到 ask、auto 或 full。

允许的 Bash 示例：

```sh
pwd
ls -la 'src'
rg --no-config -n 'handleRequest' src
rg --no-config --files -g '*.ts'
```

管道、分号、`&&`、重定向、多行、命令展开、环境赋值、`rg --pre` 和未审查的命令选项均不在范围内。`git status` / `git diff` 也未自动放行：仓库过滤器和配置可能运行外部程序。优先使用内置读取与搜索工具调查；需要运行命令验证的内容写进计划，批准后执行。

例如，确认某个 MCP 搜索工具确实只查询文档后，可以输入：

```text
/plan allow mcp__docs__search
```

这是用户对该工具实现的明确信任，不能证明它实际上没有副作用。额外信任跟随当前会话分支，Shell、内置写入和计划控制工具不能通过这条命令放行。也不会取消 `permissions` 对该工具的审批。

扩展运行在 Pi 进程内，这些限制是工具调度策略，不是操作系统沙箱。语言服务器可能更新自己的缓存；网页搜索仍会联系其服务。其他已加载扩展可直接调用文件系统或网络，其后台行为不经过本包检查。本包自身不发起外部网络请求；模型和搜索请求由用户现有 provider / 搜索扩展处理。

## 计划文件、恢复与分支

每次保存都会新建：

```text
getAgentDir()/plans/pi-plan-mode/<random-uuid>.md
```

通常位于 `~/.pi/agent/plans/pi-plan-mode/`，跟随 `PI_CODING_AGENT_DIR`，不在项目中创建 `.pi` 或计划文件。文件名由扩展生成，模型不能指定写入路径。文件采用独占创建，不覆盖旧版本；在支持的文件系统上请求目录权限 0700、文件权限 0600，Windows 的实际访问权限仍取决于 ACL。

权威内容、工具快照、进度和额外信任保存在当前分支的 `pi-plan-mode-state` 会话条目中。`/reload`、恢复会话和 `/tree` 使用 `getBranch()` 重建状态；上下文压缩不会删掉原始条目。不同分支可引用同一个旧版本，后续保存会创建新文件，不改写旧版本。

审阅前、用户选择批准后都会核对磁盘文件与会话快照。文件缺失或被外部编辑时，保留计划限制，要求模型重新 `save_plan`；不会把外部编辑静默当成已批准内容。请通过模型修订计划。打开文件查看不影响审批；`/plan show` 显示当前会话中的快照。

恢复待审批会话时不会自行弹出审批界面，使用 `/plan approve` 继续。已有批准的执行状态会在普通恢复时继续保留；显式重新以 `--plan` 启动会回到规划。使用 `--no-session` 时不会保留会话状态，Markdown 文件仍会保留，但不能仅凭它恢复执行许可。

计划文件与会话可能含项目资料，按会话数据保管。本包没有后台监视器、定时器或自动清理，不会因为卸载而删除历史计划。

## 与现有扩展配合

- `compact-footer`：规划和待审批时，原权限标签的位置显示浅蓝色纯文字 `plan`（无背景块）；退出计划模式或批准实施后恢复当前 `ask` / `navigator` / `auto` / `full` 标签。不显示输入框上方的计划提示组件，也不追加独立的 Plan 状态行；通过 `/plan status` 查看进度。状态仍通过标准 `setStatus` 发布，单独使用本包时由默认页脚显示。
- `claude-tools` / `code-cards`：使用普通工具结果，不覆盖它们的 renderer。
- `permissions`：当前仓库版本增加可选 `permissions:tool-check` 协作事件，提前拒绝受限调用，避免先审批后被计划模式拒绝。本包四个内部工具交给本包处理，最终审批由用户决定。其余工具继续接受原有 `ask` / `navigator` / `auto` / `full` 策略。Navigator 只允许已验证的内置只读操作和上述显式计划草稿流程；批准计划不会改变基础审批策略。内部工具不重复写入 permissions 的工具审计日志，模式与内容保存在计划会话条目中。通过可选 `plan-mode:control` / `plan-mode:changed` 事件，permissions 的 `Ctrl+Alt+P` 与权限选择菜单读取真实计划状态，支持 `ask → plan → navigator → auto → full → ask`；`/permissions plan` 同样可以进入。成功切换只更新底栏，不追加通知。只有统一循环键和计划命令可切换模式，不再提供单独的计划快捷键。

从 plan 按 `Ctrl+Alt+P` 切到其他权限，或显式选择 `/permissions ask|navigator|learner|auto|full`，会主动结束计划限制，恢复原工具，不标记计划已批准，也不自动继续实施。Navigator 下可显式进入规划；planning / review 期间仅 `save_plan` 与 `exit_plan_mode` 通过固定计划流程，项目修改和批准后的实施仍受基础只读权限阻止。要实施先切换基础权限到 ask、auto 或 full。手工切换计划模式需要会话空闲，忙时可先用 Esc 中断。计划恢复与内容仍由本包保存，基础策略仍由 permissions 保存；启动参数 `--permissions` 接受 ask / navigator / learner / auto / full，启动规划继续使用 `--plan`。

配合使用需要加载本仓库包含该协作事件的 permissions 源码版本。旧版 permissions 仍可能在内部计划工具前显示一次普通工具审批，之后还需计划审批。`full` 只关闭 permissions 的自身审批，计划限制仍生效。

## RPC、JSON 与 print

TUI 在聊天记录与底部操作区中审阅同一版本，选中项使用浅色或深色主题相应的底色。终端过小时提示放大并暂停确认。操作区的键位提示遵循 Pi 的自定义按键，计划路径可用 `/plan status` 或 `/plan show` 查看。意见框里的未发送内容只保留到当前审阅关闭。

RPC 通过官方 `select` 协议传递完整计划和文件路径，并附上最多 2000 字符的任务原文节选及适用的修改意见。选项为 `Keep planning (no approval)`、`Request changes`、`Approve and implement`。取消选择或超时都不会批准。客户端通过标准 `input` 协议收集修改意见，提交后保持只读规划并重新生成计划。

JSON 和 print 可以通过 Auto 分流或 `--plan` 调查、保存并提交计划；没有交互式批准时始终保留限制。需要取得完整工具结果时使用 `--mode json`；print 的最后消息若只有终止工具调用，可能没有最终助手文字。保留会话后在 TUI 或支持 extension UI 的 RPC 客户端恢复，用 `/plan approve` 审阅。不存在无交互自动批准开关。

## 验证与卸载

在仓库根目录运行 permissions 包的验证脚本：

```sh
npm --prefix permissions ci --ignore-scripts --legacy-peer-deps
npm --prefix permissions run typecheck
npm --prefix permissions test
```

测试包括真实 Pi CLI 的 JSON / print 和 RPC 流程，使用确定性离线提供方与临时工作区；也验证 codemode 被停用，以及受信任包装工具对未验证 deferred 工具的内部调用仍被拦截。plan-mode 测试与权限扩展测试由同一包脚本统一运行。

本机另以真实 Pi 1.5.0 的 fullscreen / regular TUI 核对了滚动审阅、60×24 窗口、取消、`/reload`、批准后实施及与 compact-footer / claude-tools 配合。Codex 风格布局在 Pi 1.5.2 上用同一 112×38 终端、任务和主题录制首次审阅与底部反馈的前后差异。录制脚本还核对了提交新版本、批准后写入和完成验证。录像位于维护者工作副本的 `permissions/quality/ui/plan-proposed-review-0.9.0-412e4baae35e-vs-working.gif`。

默认高亮的前后对比以同一份计划和 112×38 终端录制。两侧均在输入前取帧，随后按 Enter 验证对应操作。录像位于 `permissions/quality/ui/plan-review-default-action-0.10.0-before-vs-after.gif`。

卸载 permissions 包会同时移除权限审批与计划工作流。卸载前可用 `/plan off` 恢复原工具选择；历史会话条目和计划文件保留。
