先规划、后动手claude-code-from-scratch Plan Mode只读规划与审批工作流实现原理【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. Claude Code 开源了 50 万行代码读不动用 ~5000 行 TypeScript / Python 从零复现核心架构11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratchcLAUDE-code-from-scratch 是一个用约 5000 行 TypeScript / Python 代码从零复现 Claude Code 核心架构的开源教学项目。这篇文章带你读懂它其中最有工程安全感的一个功能——Plan Mode只读规划模式Agent 先只读探索代码、把方案写进 plan 文件再由你在四选项审批工作流中决定照做、改改再做、手动执行还是继续规划。不啃几十行代码一篇讲透原理。为什么需要 Plan Mode先想清楚再动手改用过 Coding Agent 的人都有过这种经历让它顺便加个功能结果它一上来就改了三个文件方向还不对回滚半天。Plan Mode 解决的就是这个问题把规划和执行拆成两个阶段。规划阶段Agent 只能读文件、搜索代码、思考写文件、跑 Shell 全被拦下审批阶段Agent 把完整方案写进 plan 文件提交给你你拍板执行阶段批准后按你的选择切换权限模式开始真正动手关键点是「只读」这条约束不是靠提示词求它别乱动而是权限系统在代码层面强制的。提示词负责引导权限闸负责兜底——双保险。三个入口启动时、会话中、Agent 自主决定进入 Plan Mode 有三条路径对应不同的工作流入口实现在 src/cli.ts 中入口方式适用场景--plan参数启动命令时带上整个会话从规划开始/plan命令REPL 中随时切换先聊后规划中途切入enter_plan_mode工具Agent 自主调用它自己判断这个任务该先规划其中enter_plan_mode/exit_plan_mode两个工具定义在 src/tools.ts标记为deferred延迟加载——因为大多数会话用不到 Plan Mode延迟加载可以节省提示词空间。一键体验看它如何把写文件拦下来想直接感受效果无需 API key跑一条命令即可完整可运行代码在 steps/ 目录git clone https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch cd claude-code-from-scratch npm install npm run build node steps/run.mjs 10在--plan模式下哪怕模型主动发起write_file想写report.txt也会当场被拦这条演示脚本对应场景文件 steps/scenarios/plan-blocks-write.json$ mini-claude --plan Create a file report.txt with the plan. → write_file({file_path:report.txt,content:the plan}) That was blocked because were in plan (read-only) mode.什么都没写进去。只读是怎么强制的权限闸 plan 文件白名单Plan Mode 的核心逻辑在 src/agent.ts 的权限检查环节checkPermission规则很简洁编辑类工具write_file、edit_file默认全部拒绝唯一的例外目标路径完全等于plan 文件路径时放行Shell 工具run_shell一律拒绝enter_plan_mode/exit_plan_mode始终允许这是状态切换工具这里有个精巧设计plan 文件路径是作为参数传进权限检查的写文件前逐一比对路径。也就是说系统提示词里那句你只能写这个 plan 文件不只是建议而是代码层面的硬约束——模型就算忘了规矩写操作也会被闸拦截并返回错误。Plan 文件按会话 ID 生成在~/.claude/plans/plan-{sessionId}.md每个会话互不干扰。四选项审批工作流批准后到底发生什么规划完成后Agent 调用exit_plan_mode终端会打印计划内容并弹出四个选项审批 UI 在 src/ui.ts选项行为权限切换适用场景1️⃣ Clear Execute清空对话历史再执行→acceptEdits自动接受编辑计划已完善上下文很长从零执行最高效2️⃣ Execute保留历史直接执行→acceptEditsAgent 已有足够上下文直接开工3️⃣ Manual恢复进入前的权限模式→ 原模式计划大致可以但想逐个审批每次修改4️⃣ Keep Planning留在规划模式把你的反馈喂回给 Agent不变计划要改让它继续打磨选项 4 是闭环的关键你的反馈会作为工具结果返回给模型它据此修改 plan 文件后再次调用exit_plan_mode直到你满意为止——形成一个规划 → 审批 → 反馈 → 再规划的迭代环。三个值得偷师的细节plan 文件写在磁盘不是留在对话里。选Clear Execute时对话历史会被清空以释放上下文但计划文件安然躺在~/.claude/plans/里Agent 可以重新读取、跨会话查看。计划不随上下文蒸发。审批是回调注入不是 Agent 内置。Agent 类通过setPlanApprovalFn挂接审批函数见 src/cli.tsCLI 用 readline、IDE 可以换成 GUI、测试时注入模拟函数——Agent 完全不知道也不关心 UI 长什么样。没有审批函数时优雅降级。子 Agent见 src/subagent.ts没有交互式审批此时exit_plan_mode直接退出并恢复原模式把计划内容原样返回给调用方不需要任何特殊分支。小结Plan Mode 用极小的代码量实现了一个完整的人机协作范式只读探索 → 落盘成文 → 人工审批 → 按决策执行。它证明了一件事限制 Agent 的能力只读反而是放大它价值的手段——先想清楚再动手比一上来就改文件靠谱得多。想深入源码级细节推荐按章节读官方教程docs/10-plan-mode.md本章全文、docs/06-permissions.md权限系统和 docs/01-agent-loop.mdAgent 主循环教学代码快照在 steps/canonical/ 目录TypeScript 版与 Python 版一一对应。【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. Claude Code 开源了 50 万行代码读不动用 ~5000 行 TypeScript / Python 从零复现核心架构11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考