Claude Code 的 Agent Loop

第一章建立了整体运行时地图。这一章进入核心：queryLoop()。

不要把它理解成“while 里反复问模型”。从源码看，Claude Code 的 Agent Loop 更像一个自修改任务状态机：每一轮都会重建上下文、调用模型、处理流式响应、执行工具、回写结果，然后根据 Continue.reason 或 Terminal.reason 决定下一步。

先看源码入口

这一章先抓这些源码点：

这几个点足够支撑一条完整阅读路线：入口包装、状态结构、预处理、API 请求、工具分支、恢复/终止、下一轮状态重建。

总流程图

这张图里要注意两个分叉：

• 有 tool_use：进入工具执行，结果回写，通常以 next_turn 继续。
• 没有 tool_use：不一定完成，还要走恢复、stop hook、token budget continuation。

query() 只是外层包装，queryLoop() 才是状态机

源码里的入口很短：

export async function* query(params: QueryParams) {
  const consumedCommandUuids: string[] = [];
  const terminal = yield* queryLoop(params, consumedCommandUuids);

  for (const uuid of consumedCommandUuids) {
    notifyCommandLifecycle(uuid, 'completed');
  }

  return terminal;
}

这段代码证明了边界：

原文指出 queryLoop() 内部是 while (true)，每个继续点用 state = next; continue 进入下一轮，每个终止点用 return { reason: '...' } 退出。也就是说，它不是“自然跑完”的函数，而是一张显式状态转移图。

State：跨轮携带的任务现场

State 是读 queryLoop() 的第一把钥匙。原文定位在 restored-src/src/query.ts:204-217，字段包括：

源码注释里有一个非常关键的约束：Continue sites 写完整 state = { ... }，而不是 9 个字段分别赋值。这个设计不是风格问题，而是 bug 防线。

伪源码可以写成：

state = {
  messages: nextMessages,
  toolUseContext: nextToolUseContext,
  autoCompactTracking,
  maxOutputTokensRecoveryCount,
  hasAttemptedReactiveCompact,
  maxOutputTokensOverride,
  pendingToolUseSummary,
  stopHookActive,
  turnCount: turnCount + 1,
  transition: { reason: 'next_turn' },
};
continue;

这段结构证明：每个继续点都必须声明“下一轮继承哪些状态、重置哪些状态、为什么继续”。在一个有多种恢复路径的 while (true) 里，这比 state.maxOutputTokensRecoveryCount++ 这类增量修改安全得多。

Continue 与 Terminal：循环为什么继续、为什么停止

Agent Loop 必须把“继续”和“停止”都变成可观察状态，否则出了问题只能看到“模型没反应了”。

Continue.reason 的主要分支：

Terminal.reason 则说明最终停在哪里：

每轮开始：上下文先过一条从轻到重的预处理管线

模型调用前，messages 不会原样送进 API。原文把 query.ts:379-468 的管线拆成五级：

applyToolResultBudget()
-> snipCompactIfNeeded()
-> microcompact()
-> contextCollapse()
-> autocompact()

它们的顺序很重要：

源码注释里最值得保留的是 context collapse 的读时投影思想。原文引用的大意是：collapse 不向 REPL 历史 yield 新消息，summary 存在 collapse store，折叠视图是在读取时投影出来的。

这证明 contextCollapse() 不是简单“把数组里一段消息替换成摘要”，而是在模型读取路径上生成视图。好处是 UI 的完整历史和模型看到的压缩视图可以分离。

请求拼装：system context 和 user context 分层进入 API

上下文预处理后，还要注入运行时上下文。源码里两个函数边界很清楚：

export function appendSystemContext(
  systemPrompt: SystemPrompt,
  context: { [k: string]: string },
): string[] {
  return [
    ...systemPrompt,
    Object.entries(context)
      .map(([key, value]) => `${key}: ${value}`)
      .join('\n'),
  ].filter(Boolean);
}

这段代码证明 system context 是追加到 system prompt 末尾的。稳定、全局、适合缓存的内容更适合放这里。

另一个函数：

export function prependUserContext(
  messages: Message[],
  context: { [k: string]: string },
): Message[] {
  return [
    createUserMessage({
      content: `<system-reminder>\n...\n</system-reminder>\n`,
      isMeta: true,
    }),
    ...messages,
  ];
}

这段代码证明 user context 被包装成 @@INLINE_0@@，作为 meta user message 插到消息数组最前面。

调用点的形状是：

messages: prependUserContext(messagesForQuery, userContext),
systemPrompt: fullSystemPrompt,

这里有一个设计判断：prependUserContext() 在 API 调用时执行，而不是在前面的压缩管线里执行。也就是说，它不是历史消息的一部分，不参与同样的压缩和 token 管线；它更像每次请求前临时贴上的运行时提醒。

消息标准化：内部消息不能直接发给模型

Claude Code 内部消息比 Anthropic API 要丰富：有虚拟消息、进度消息、附件、工具输入的 UI backfill、媒体错误等。发 API 前必须标准化。

原文给出的顺序是：

其中 ensureToolResultPairing() 很关键。Agent 的上下文里，tool_use 和 tool_result 必须配对；远程会话恢复、降级重试、会话裁剪都可能造成孤立块。如果不修复，下一次 API 调用可能直接失败。

模型调用：流式响应里也有恢复分支

API 调用阶段被 attemptWithFallback 包住。原文给出的片段：

let attemptWithFallback = true;
while (attemptWithFallback) {
  attemptWithFallback = false;
  try {
    for await (const message of deps.callModel({
      messages: prependUserContext(messagesForQuery, userContext),
      systemPrompt: fullSystemPrompt,
      // ...
    })) {
      // 处理流式响应消息
    }
  } catch (innerError) {
    if (innerError instanceof FallbackTriggeredError && fallbackModel) {
      currentModel = fallbackModel;
      attemptWithFallback = true;
      // 清理孤立消息, 重置 executor
      continue;
    }
    throw innerError;
  }
}

这段代码证明：模型降级不是外层 queryLoop() 的下一轮，而是同一轮 API 调用内部的重试。这样可以保留当前预处理结果，同时清理已经产生但不能继续使用的流式中间状态。

原文还提到三个流式阶段的源码判断：

这里的取舍是：流式输出对用户是实时的，但对状态机不能天真地“发出去就算数”。 可恢复错误要扣留，降级后旧片段要 tombstone，缓存相关消息不能被随意 mutate。

工具分支：tool_use 变成现实反馈

模型响应结束后，Loop 判断有没有 tool_use blocks。有的话进入工具执行阶段：

tool_use blocks
-> StreamingToolExecutor.getRemainingResults()
   或 runTools()
-> toolResults[]
-> normalizeMessagesForAPI()
-> 追加到下一轮 messages
-> transition.reason = 'next_turn'

原文指出 Claude Code 有两种工具执行模式：

流式并行执行说明 Claude Code 没有把“模型完整说完”作为工具执行的唯一起点。只要某个 tool_use block 参数完整，就可以提前开始，把工具耗时和模型流式输出重叠起来。

工具完成后，Loop 还会注入附件：

这些后台任务利用的是模型流式响应和工具执行期间的等待窗口。它们不挡在 API 调用前面，而是在下一轮准备阶段消费。

无工具分支：恢复、hook 和终止

没有 tool_use 时，Loop 不是直接 completed。它先检查多条恢复和拦截路径。

输出截断恢复

当模型输出触达 max_output_tokens，Claude Code 先尝试升级输出上限：

默认 max output
-> 输出被截断
-> maxOutputTokensOverride = ESCALATED_MAX_TOKENS
-> transition.reason = 'max_output_tokens_escalate'
-> 原样重试

如果升级后仍截断，再走多轮恢复。原文给出的恢复提示强调：

Output token limit hit. Resume directly - no apology, no recap of what you were doing.
Pick up mid-thought if that is where the cut happened.
Break remaining work into smaller pieces.

这条提示证明恢复不是简单“请继续”。它明确禁止道歉和回顾，要求直接接上，并拆小剩余工作。原因很工程化：道歉和 recap 都会浪费刚刚变稀缺的输出 token。

提示过长恢复

prompt 太长时，恢复顺序是：

prompt-too-long
-> collapse_drain_retry
-> reactive_compact_retry
-> 仍失败则 Terminal.reason = prompt_too_long

源码注释里有一个重要判断：prompt-too-long 时不要 fall through 到 stop hooks。因为模型没有产生有效响应，hook 没有可评估对象；如果强行跑 hook，可能形成 error -> hook blocking -> retry -> error 的 death spiral。

这说明恢复路径必须有边界：不是所有错误都能进入所有后处理系统。

停止钩子与 token budget

当模型没有工具调用且响应有效时，Loop 才有条件运行 stop hooks：

const stopHookResult = yield* handleStopHooks(
  messagesForQuery,
  assistantMessages,
  systemPrompt,
  userContext,
  systemContext,
  toolUseContext,
  querySource,
  stopHookActive,
);

如果 stop hook 返回 blockingErrors，Loop 不会直接结束，而是把阻塞错误注入消息流，并用 transition.reason = 'stop_hook_blocking' 继续，让模型有机会修正。

token budget 则处理另一类情况：模型以为完成了，但预算还允许继续，系统可以注入 nudge，以 token_budget_continuation 再跑一轮。这里还有 diminishing returns 判断，防止“预算没用完所以硬续”。

状态和数据结构

这一章最值得记住的结构不是某个类，而是三组 reason 和 counters。

这些字段共同防止三类问题：

• 无限循环：用 hasAttemptedReactiveCompact、maxOutputTokensRecoveryCount、turnCount 限制恢复和轮次。
• 不可解释失败：用 Terminal.reason 说明停止原因。
• 调试不可见：用 transition 让测试和日志知道上一轮为什么继续。

设计取舍

真实任务怎么流动

假设用户说：“npm run build 挂了，帮我修一下。”

如果第 1 轮构建日志过长，会先被 applyToolResultBudget() 裁剪；如果多轮后上下文过大，会走 snip / microcompact / collapse / autocompact；如果模型回答被截断，会走 max output recovery；如果用户中断，会返回 abort 类 terminal reason。

这就是 Agent Loop 的本质：每一轮不是照脚本执行下一步，而是根据新证据重建下一轮决策现场。

读源码抓手

读 queryLoop() 这种长函数，不建议从第一行追到最后一行。按下面顺序更稳：

1. 先看 State 类型，标出哪些字段是计数器、哪些字段是上下文、哪些字段是恢复守卫。
2. 搜 transition: { reason:，把所有 continue 点画出来。
3. 搜 return { reason:，把所有 terminal 点画出来。
4. 再看每轮开头的预处理管线，确认 messagesForQuery 怎么来。
5. 进入 API 调用，看 attemptWithFallback 如何处理降级和流式消息。
6. 搜 toolUseBlocks、StreamingToolExecutor、runTools，追工具结果如何变成下一轮消息。
7. 最后看无工具分支：max output recovery、reactive compact、stop hooks、token budget。