拆解 Claude Code 的完整智能体循环

此前的十篇文章逐一拆解了权限、hooks、工具调度、状态机、流式处理、错误恢复、中断和 sub-agent。这篇收官文章不再引入新机制，而是要把这些部分重新组装成一个完整的 Agent loop。

值得记住的五个核心观点

如果你只打算记住这个系列中的五件事，那就记住下面这五件。

1. 循环会自主运行，通常不需要人工介入

用户只需按一次 Enter，循环就会自行推进。通常，用户不需要指挥每一个中间步骤。只有当工具需要权限时，循环才会暂停，而用户随时都可以中断它。

这正是 Agent 与普通聊天机器人的本质区别。聊天机器人生成一次回答后就会停止。Agent 则可以在用户输入一次之后，反复调用模型和工具，直到任务完成。

2. 循环是状态机，不只是一条 while 语句

循环的核心并不是五行伪代码，而是一组显式定义的状态。每一轮结束时，系统都会记录接下来应该做什么。下一轮再根据这个状态，选择常规调用路径、重试路径、压缩路径或恢复路径。

因此，发生错误后，系统不会在同一轮的 try/catch 中层层重试。控制权会回到主循环，由后续轮次执行恢复工作。参见第 5 篇：《作为状态机的 QueryEngine 主循环》。

3. 错误会变成循环可以继续处理的状态

失败的工具调用会被转换成 tool_result，交给 LLM。当主循环自身需要恢复时，这一需求会转化为下一轮的状态转移。这两种情况遵循同一个原则：把错误转化为循环可以继续处理的状态或数据，而不是让异常直接打断循环。

因此，这个循环不只是一个等待问题发生的错误处理器，更是一个会主动尝试修复执行进程的恢复引擎。只有内部恢复也失败后，最终的错误才会呈现给用户。参见第 7 篇：《重试与八层错误恢复》。

4. 自主执行有三道保障

自动执行并不意味着 Agent 不受控制。以下三种机制，让用户或系统能够重新掌握控制权：

权限审批——在有风险的工具运行之前，循环会暂停，等待用户决定。

中断——用户随时可以停止正在运行的循环。

maxTurns——即使没有人工干预，循环也会在达到轮次上限时停止。

它们分别对应三个不同的时刻：执行前确认、执行中刹车，以及最终的硬性上限。三者共同约束着自主循环。

5. 主 Agent 与 sub-agent 复用同一个循环

sub-agent 并不是用另一套循环实现的。主 Agent 和每个 sub-agent 都调用同一份 queryLoop 代码，独立运行，并通过 agentId 区分各自的角色。

这说明，这个循环并不是专门为聊天窗口编写的代码。它是 Claude Code 用来让 AI 自主推进任务的通用执行引擎。参见第 9 篇：《Sidechain、sub-agent 与 agentId 路由》。

从五行骨架到完整系统

回顾整个系列：

第 0 篇：《从聊天窗口到循环》，从聊天窗口的直观认识出发，引出了一个五行的循环骨架。

第 1 篇：《从工具声明到执行前审批》，到第 4 篇：《从回答完成到 stop_reason 的七种含义》，拆解了单轮执行中的工具声明、权限、hooks、并行调度和停止决策。

第 5 篇：《作为状态机的 QueryEngine 主循环》，用状态机统一了这些局部机制。

第 6 篇：《从 SSE 事件到逐字渲染》，深入展开了一次模型调用内部的流式处理过程。

第 7 篇：《重试与八层错误恢复》，解释了循环如何在失败后恢复。

第 8 篇：《从 Ctrl-C 到合成的 tool_result》，解释了用户如何从循环外部中断自动执行。

第 9 篇：《Sidechain、sub-agent 与 agentId 路由》，将同一个循环推广到了 sub-agent。

最初那五行伪代码从来没有错。它只是省略了最重要的部分：执行如何在步骤之间分支，失败之后如何恢复，用户如何重新掌握控制权，以及一个循环如何服务于不同类型的 Agent。

循环负责执行，上下文承载信息

循环是骨架。它解释的是事情如何发生：何时调用模型、何时运行工具、何时重试，以及何时停止。

信息则在这副骨架中流动：消息如何组装、prompt cache 如何复用、压缩如何缩短历史记录，以及 CLAUDE.md 如何注入。这些问题属于配套的 Claude Code 上下文管理研究系列。

两个系列的分工，可以用两句话概括：

循环解释事情如何发生。

上下文解释信息如何组织。

两者结合，才能完整呈现一个 Claude Code Agent 的运行方式。

Claude Code 上下文管理研究系列——消息、缓存、压缩与上下文注入。

Claude Code 工具研究系列——各个工具的能力与设计。

如果还想采取进一步行动，你可以考虑屏蔽此人和／或举报滥用行为。