easy-agent Plan Mode实战:先只读规划再执行,再也不怕AI改坏代码

原创2026-10-17 21:40:422,252 阅读

easy-agent Plan Mode实战:先只读规划再执行,再也不怕AI改坏代码

easy-agent(eagent)是一款生产级开源终端编程智能体,它内置的 Plan Mode(计划模式)让 AI 先以只读方式探索代码、产出一份可审批的变更计划,经你确认后才开始动手改文件。本文带你快速掌握 easy-agent Plan Mode 的开启方法、规划流程与审批技巧,让 AI 编程从"边想边改"变成"先出方案再施工",从根源上避免 AI 改坏代码。

easy-agent 终端智能体分层架构与 Plan-Execute-Observe 流程

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 工具说明):

  1. EXPLORE —— 用只读工具摸清代码结构;
  2. PLAN —— 把方案写进计划文件;
  3. EXIT —— 调用 ExitPlanMode 请求审批。

计划文件存放在 ~/.easy-agent/plans/<会话slug>.md(由 src/context/plans.ts 管理),且要求包含 5 个固定小节:

## Context          —— 问题是什么、期望结果
## Recommended approach —— 推荐方案(可直接执行)
## Critical files   —— 将新增/修改的关键文件
## Reuse            —— 应复用的现有函数与模式
## Verification     —— 如何端到端验证

easy-agent 桌面端欢迎界面:打开工作区后 Agent 在里面读代码、改文件、跑命令

审批时刻:ExitPlanMode 的 4 个选择

AI 写完计划会调用 ExitPlanMode 请求退出规划。终端会弹出"Ready to code?"审批框(PlanApprovalDialog),给你 4 个选项:

  1. Yes, auto-accept edits (clear context) —— 批准后自动接受写入,清空上下文重新出发,适合大型任务;
  2. Yes, auto-accept edits (keep context) —— 同上,但保留对话上下文;
  3. Yes, manually approve edits —— 每次写入仍需你 y/n 确认,最稳妥;
  4. 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 改坏代码的风险拦在了动手之前——复杂任务,永远值得先花几分钟看一份计划。

登录后查看全文
easy-agent