05. 权限、计划与安全

先计划再动手

计划模式是以读为主的阶段：助手先探索、写计划，等你同意后再改项目。

先定方案再动手

计划模式打开时，助手唯一可以改的文件是会话计划文件。批准计划才开始实现。退出计划会关掉计划模式，且不实施。

计划模式怎么工作

助手（或你）进入计划模式。它读取和搜索，写入 plan.md，可能问澄清问题，然后调用 exit_plan_mode。TUI 打开可滚动预览，底部有操作栏。

计划文件在会话目录下：

~/.matcha/sessions/<encoded-cwd>/<session-id>/plan.md

<encoded-cwd> 是 URL 编码后的工作目录名，不是字面路径。设置 MATCHA_HOME 可挪走主目录树。

一份典型计划会写上下文、一条推荐做法、关键路径、可复用目标，以及如何端到端核对。

生命周期

状态	含义
`Inactive`	普通模式。没有计划文件闸门。
`Pending`	你打开了计划；下一次提示会激活它。
`Active`	计划文件的编辑自动批准；其他文件编辑被拒绝。
`ExitPending`	一轮还在跑时，你关掉了计划。

从普通模式用 /plan 或 Shift+Tab 会走 Inactive → Pending，你下一次发送提示时变成 Active。助手的 enter_plan_mode 工具若你批准，会直接 Inactive → Active。计划状态会保存；重启时 Pending 和 ExitPending 会收成 Inactive。

改计划文件以外的任何文件都会失败，并给出短消息，点明唯一可编辑路径是计划文件。这道闸在每种权限模式里都成立，包括始终批准。

激活时状态片显示 plan。若底下开着始终批准，退出计划模式后会回到它的状态片。/compact 会把计划模式提醒留在压缩后的上下文里。

什么时候用

方案本身很贵时用计划模式：认证形状、流水线重做、几种说得通的缓存设计。打错一个字、按现有界面加删除按钮、或看完代码就能修的 bug，可以跳过。

一个好习惯：「到底该怎么做？」用计划模式，「直接做」用询问模式。

进入计划模式

/plan
/plan Redesign the auth middleware

/plan — Pending。你发送下一次提示时激活计划模式。
/plan <description> — 进入并用这段文字开始一轮。

Shift+Tab（焦点在提示符）也会从普通落到计划。助手可以提议 enter_plan_mode；拒绝后仍留在普通模式。

查看已保存的计划

/view-plan

别名：/show-plan、/plan-view。计划存在后重新打开保存的预览。磁盘上没有内容时，TUI 提示 No plan written yet.

若助手带着空的或缺失的 plan.md 退出计划模式，同一套批准界面仍会打开。预览正文是以 # No plan written yet 开头的占位，状态行写 No plan written — approve or request changes，让你可以批准、要求修改或退出。/view-plan 在没有保存内容时提示 No plan written yet.

批准快捷键

用方向键或 j / k 滚动。Tab 在预览和提示符之间切换焦点。批准前仍可用 Ctrl+P 换模型。

按键	动作
`a`	批准并开始实现。若有待发送的行内评论，会显示 approve w/ comments，并随批准一起送出。
`s`	要求修改。焦点移到提示符；`Enter` 发送备注。计划模式保持打开。
`c`	给选中的行或范围写评论（在一行上按 `Enter` 也会开始评论）。
`y`	把整份计划复制到剪贴板。
`q`	退出计划——放弃它并关掉计划模式。
`Esc`	从提示符把焦点交回预览。不会退出。

不实施就离开

在批准视图按 q。这会放弃拟定的计划并关掉计划模式。空闲时关掉计划（再循环一次 Shift+Tab，或用模式控件）也会退出，前提是没有正在跑的一轮。