easy-agent Plan Mode实战:先只读规划再执行,再也不怕AI改坏代码
easy-agent Plan Mode实战:先只读规划再执行,再也不怕AI改坏代码
easy-agent(eagent)是一款生产级开源终端编程智能体,它内置的 Plan Mode(计划模式)让 AI 先以只读方式探索代码、产出一份可审批的变更计划,经你确认后才开始动手改文件。本文带你快速掌握 easy-agent Plan Mode 的开启方法、规划流程与审批技巧,让 AI 编程从"边想边改"变成"先出方案再施工",从根源上避免 AI 改坏代码。
Plan Mode 是什么?一句话:先读后写
easy-agent 有 3 种权限模式:
| 模式 | 启动方式 | 行为 |
|---|---|---|
default |
默认 | 写文件、跑命令前逐项询问 |
plan |
eagent --plan |
只读规划,禁止任何写操作 |
auto |
eagent --auto |
分类器自动放行安全调用 |
plan 模式由 src/permissions/permissions.ts 定义,核心逻辑只有一条:规划阶段一切写操作都被拒绝,唯一例外是把计划写到专属计划文件里。也就是说,AI 在规划期能读、能搜、能跑 ls/git status 这类只读命令,但碰不到你的任何一行代码。
如何开启 Plan Mode:两种方式
方式一:启动时直接指定(推荐)
eagent --plan # 只读规划模式
方式二:会话中由 AI 主动申请
当你描述的任务比较复杂时,模型会调用 EnterPlanMode 工具申请进入规划,并附带一句"为什么需要规划"的说明。此时 easy-agent 一定会弹权限确认——切换模式是你的一次主动选择,AI 不能偷偷切换(见 src/permissions/permissions.ts 中的强制 ask 逻辑)。
💡 经验法则:跨多个文件的改动、不熟悉的陌生代码库、风险较高的重构,都先开
--plan。
规划阶段:AI 在做什么、不能做什么
进入 Plan Mode 后,权限系统只放行一批白名单工具(src/permissions/permissions.ts 的 PLAN_ALLOWED_TOOLS):
| ✅ 允许 | ❌ 拒绝 |
|---|---|
| Read 读文件、Grep 搜内容、Glob 找文件 | Write / Edit / MultiEdit 修改代码 |
只读 Bash 命令(ls、cat、git status) |
一切有副作用的 Bash 命令 |
| WebSearch、MCP 资源读取 | 除计划文件外的任何写盘操作 |
AI 按固定三步走(EnterPlanMode 工具说明):
- EXPLORE —— 用只读工具摸清代码结构;
- PLAN —— 把方案写进计划文件;
- EXIT —— 调用 ExitPlanMode 请求审批。
计划文件存放在 ~/.easy-agent/plans/<会话slug>.md(由 src/context/plans.ts 管理),且要求包含 5 个固定小节:
## Context —— 问题是什么、期望结果
## Recommended approach —— 推荐方案(可直接执行)
## Critical files —— 将新增/修改的关键文件
## Reuse —— 应复用的现有函数与模式
## Verification —— 如何端到端验证
审批时刻:ExitPlanMode 的 4 个选择
AI 写完计划会调用 ExitPlanMode 请求退出规划。终端会弹出"Ready to code?"审批框(PlanApprovalDialog),给你 4 个选项:
- Yes, auto-accept edits (clear context) —— 批准后自动接受写入,清空上下文重新出发,适合大型任务;
- Yes, auto-accept edits (keep context) —— 同上,但保留对话上下文;
- Yes, manually approve edits —— 每次写入仍需你 y/n 确认,最稳妥;
- No, keep planning —— 继续规划,并可直接输入反馈意见让 AI 修改方案。
两个高频进阶技巧:
- 先改计划再批准:审批时你可以直接编辑计划内容,AI 会收到"edited by user"标记并严格按你改过的版本执行(exitPlanModeTool.ts);
- 预授权安全命令:退出时 AI 可声明
allowedPrompts,例如把npm test、安装依赖等命令加入本会话自动放行清单,执行阶段少刷一堆确认弹窗(buildAllowRulesFromPrompts)。
执行后仍有兜底:/rewind 一键回滚
规划能降低出错概率,但不会 100% 消除。easy-agent 对文件变更做检查点,执行阶段即使 AI 改得不对,输入 /rewind 即可检查或恢复改动(详见 README 中数据存放表,检查点位于 ~/.easy-agent/file-history/)。
新手速查:什么时候该用 Plan Mode
- 📖 接手陌生仓库,先让 AI 只读梳理再提改动;
- 🔀 多文件重构 / 架构调整,先审方案再动手;
- 🧪 高风险区域(鉴权、数据迁移、删除逻辑);
- ⚡ 日常小修小补则不必,
default模式逐次确认即可。
延伸阅读:核心源码与文档
| 模块 | 路径 |
|---|---|
| 进入规划工具 | src/tools/enterPlanModeTool.ts |
| 退出规划工具 | src/tools/exitPlanModeTool.ts |
| 计划文件管理 | src/context/plans.ts |
| 权限与模式裁决 | src/permissions/permissions.ts |
| 规划审批对话框 | src/ui/components/PlanApprovalDialog.tsx |
| 安全模型说明 | README 安全模型章节 |
一句话总结:easy-agent 的 Plan Mode 用"只读探索 → 结构化计划 → 人工审批 → 受控执行"的流水线,把 AI 改坏代码的风险拦在了动手之前——复杂任务,永远值得先花几分钟看一份计划。

