标签#Agent原理#任务编排#错误恢复#架构深度Claude Code 之所以能像人一样“边想边做”是因为其内部有一个严谨的循环结构——Agent Loop。它把任务计划、工具调用、结果观察、错误恢复串成一个闭环让 AI 能够自主推进复杂工作。1. 什么是 Agent LoopAgent Loop智能体循环是 Claude Code 执行任何非平凡任务的核心运行模型。它模仿了人类工程师的工作方式理解目标你给出的任务制定计划拆解步骤执行动作读写文件、运行命令观察结果成功/失败、输出内容调整计划根据新信息修正重复直到目标达成或需要用户介入与传统“一次性生成”不同Agent Loop 是多轮、自适应的。每一轮中Claude 模型会决定下一步做什么而不是一次性输出最终答案。2. Agent Loop 的三阶段拆解一个完整的 Agent 循环可以细分为三个阶段阶段作用具体行为计划Plan确定目标与策略将用户指令分解为子任务选择工具设定成功标准执行Execute调用工具通过工具接口Read/Write/Bash/Grep等执行具体操作观察与评估Observe Evaluate分析结果获取工具输出判断是否成功决定下一步行动这三个阶段循环运行直到以下情况之一发生所有子任务完成目标达成遇到无法自动解决的错误请求用户介入达到最大循环步数默认 50 步用户中断CtrlC3. 一次典型 Agent Loop 的完整追踪我们用一个具体例子逐轮看 Agent Loop 的内部状态。用户输入把 utils.js 中的 formatPrice 函数移到 helpers/price.js并更新所有引用。第 1 轮计划与执行感知用户指令 当前目录结构通过LS已知计划需要找到utils.js中formatPrice的定义同时找到所有引用它的文件。采用工具Read utils.js和Grep formatPrice行动调用Read(utils.js)→ 获得文件内容定位函数定义的行范围调用Grep(formatPrice, path.)→ 获得引用列表如cart.js:23,checkout.js:47第 2 轮观察与再计划观察utils.js中formatPrice函数定义在第 45-52 行函数体使用了toFixed和currency符号。引用共有 5 处分布在 3 个文件中。评估当前进度——已定位源和引用尚未执行移动和更新引用。计划下一步需要创建helpers/price.js如果目录不存在则先创建目录将函数定义复制到新文件并添加必要的export从utils.js中删除该函数修改每个引用文件的 import 语句从./utils改为./helpers/price或补全导入第 3 轮执行多个动作行动Bash(mkdir -p helpers)→ 创建目录Write(helpers/price.js, content)→ 写入函数定义含export function formatPrice...Edit(utils.js, old_string第45-52行函数定义, new_string)→ 删除原函数对于每个引用文件如果文件已有import { ... } from ./utils修改为import { ..., formatPrice } from ./helpers/price如果文件之前通过import * as utils调用改为直接导入formatPrice或保持命名空间但修改路径第 4 轮验证与恢复观察所有编辑操作成功但需要验证项目是否还能正常运行。计划运行测试套件或执行npm run build检查。行动Bash(npm test)如果测试通过 → 任务完成输出报告。如果测试失败 → 进入错误恢复子循环见第 5 节。整个过程中你只输入了一次AI 自主完成了 4 轮循环。4. 任务计划的内部表示Claude Code 并不是显式维护一个“待办列表”数据结构而是通过对话历史中的推理链隐式地推进计划。但在每个 Agent 步骤中模型会生成类似这样的“计划 token”{reasoning:我需要先将函数定义移动到新文件然后更新所有引用。当前已经找到了所有引用位置共5处。接下来我会创建新文件并复制函数定义。,next_tool:Write,tool_args:{file_path:helpers/price.js,content:export function formatPrice(price) { ... }}}这种结构化的思考输出使得计划可追溯、可调试。你可以在对话历史中看到 AI 的“内心独白”如果启用了详细日志模式。5. 错误恢复机制Agent Loop 最强大的特性之一是自动错误恢复。当工具调用失败时Claude Code 不会直接放弃而是尝试多种策略。常见错误及恢复策略错误类型示例恢复动作文件不存在Read(config/unknown.json)返回 ENOENT检查路径是否拼写错误或搜索类似文件名权限拒绝Write(/etc/hosts)无权限提示用户需要 sudo建议改用用户目录或请求授权命令失败npm run build返回非零退出码读取错误输出分析原因缺少依赖、语法错误自动修复后重试语法错误修改代码后 ESLint 报错读取 ESLint 输出定位错误行修正代码重新验证超时Bash命令执行超过 30 秒考虑是否命令需要更长超时或可能存在死循环询问用户是否增加超时或终止循环依赖编辑 A 文件导致 B 文件报错修复 B 又影响 A检测到反复修改同一组文件后停止并提示用户手动解决恢复流程示例假设在第 3 轮中AI 尝试运行npm test失败输出Error: Cannot find module ./helpers/price.js from cart.js错误恢复子循环检测测试失败错误指向cart.js中导入路径错误。分析AI 意识到可能在新文件创建时相对路径计算有误项目根目录 vs 子目录。修复计划重新计算正确的导入路径例如../helpers/price或./helpers/price取决于文件深度。执行修复Edit修改cart.js中的导入语句。重新验证再次运行npm test。如果仍失败重复步骤 2-5直到测试通过或达到重试上限默认 3 次。如果 3 次后仍失败AI 会输出当前状态和失败原因并请求你的介入“我尝试了修改导入路径为相对路径和绝对路径但测试仍然报错。可能项目配置了特殊的模块解析规则请检查 webpack 或 tsconfig.json。”6. 循环控制与用户干预虽然 Agent Loop 是自动的但你在任何时候都可以干预中断按CtrlC一次会取消当前生成模型停止输出再次按CtrlC退出 Claude Code。修改指令在 AI 执行过程中你可以在输入区输入新消息AI 会暂停当前循环优先处理你的新指令类似于“打断”。拒绝工具调用当 AI 请求执行写操作或危险命令时默认会弹出确认提示。你可以选择拒绝然后告诉 AI “不要做这个操作换一种方式”。切换模式输入/mode plan让 AI 只输出计划不执行你审核后再执行。通过CLAUDE.md预设循环行为你可以在CLAUDE.md中定义对 Agent Loop 的约束## Agent Loop 偏好 - 最大循环步数20 - 在修改超过 3 个文件之前先输出计划并等待我确认 - 遇到任何测试失败优先修复失败的测试最多重试 2 次如果仍失败则停止并报告 - 禁止自动执行 rm -rf 或 sudo 命令7. Agent Loop 的性能与成本每多一轮循环就多一次模型调用输入 输出 token。因此复杂任务可能消耗较多 token。任务复杂度典型循环轮数预估 token 消耗成本示例单文件简单修改1-2 轮5-15K$0.05-0.15跨文件重构10 个文件5-10 轮50-150K$0.5-1.5全项目迁移50 文件15-30 轮150-400K$1.5-4.0优化技巧尽可能提供清晰的初始指令减少 AI 因误解而走的弯路。使用 Plan 模式预先审核计划避免执行中的错误导致额外轮次。如果任务可以拆分为多个独立的子任务分批让 AI 执行每个子任务单独会话避免长循环中的上下文膨胀。定期执行/compact压缩历史降低后续轮次的输入 token。8. Agent Loop 的设计哲学Claude Code 的 Agent Loop 设计受到以下原则驱动透明性用户可以观察 AI 的每一步思考和行动而不是黑盒。可控性用户可以在任何点打断、修改、拒绝AI 不会“自作主张”。容错性AI 被设计为会从错误中恢复而不是崩溃。节俭性尽可能减少不必要的循环例如通过计划阶段合并多个工具调用。可扩展性通过 MCP 协议开发者可以添加新工具扩展 Agent Loop 的能力边界。9. 与其他 Agent 框架的对比框架循环结构错误恢复工具集适用场景Claude Code内置专有循环强自动重试回溯文件系统ShellMCP开发者终端LangChainReAct 或 Plan-and-Execute依赖用户实现自定义通用 Agent 应用AutoGPT循环目标分解有限容易死循环文件搜索API自主任务ChatGPT Code Interpreter单轮工具调用无循环无Python 沙箱数据分析Claude Code 的优势在于为开发者场景深度优化的循环控制和错误恢复以及开箱即用的丰富工具集。10. 下篇预告Agent Loop 让 Claude Code 能够自主行动但如何保证它不会误删重要文件或执行危险命令下一篇我们将深入权限系统——Default、Plan、Bypass、Auto 四种模式如何保护你的代码安全。下一篇权限系统深度解析Default、Plan、Bypass、Auto四种模式如何保护代码安全思考题自测理解假设 Agent Loop 在第 5 轮时陷入了重复修改同一个文件的死循环比如交替修改 A 和 B。你认为 Claude Code 内置的循环检测机制会如何处理你可以如何手动干预在 Plan 模式下AI 输出的计划包含“步骤 3删除deprecated.js”。但你发现这个文件还在被其他模块引用。你会如何向 AI 反馈让它修正计划如果你的任务需要超过 50 轮循环例如重构一个巨型 monorepo你应该如何拆分任务避免达到默认上限Agent Loop 是 Claude Code 的引擎而权限系统就是它的刹车和方向盘——下一篇我们学驾驶。
