4 · 智能体主循环与错误恢复状态机

4.1 教科书版本的循环，以及它会死在哪

如果你去搜「怎么写一个智能体」，得到的答案基本都是这五行：

（llm 是 large language model 的缩写，指调用大语言模型；resp 是 response 即回复；tool_calls 就是第 1.5 节讲的那些「便条」。）

这五行确实能跑通一个演示。但把它放到真实环境里，它会死在下面每一条上：

4.2 Claude Code 的做法：写成显式状态机

先解释什么是「状态机」

Claude Code 把跨轮次的状态收进一个结构体

type State = {
  messages: Message[]                       // 当前的完整消息历史
  toolUseContext: ToolUseContext            // 工具执行需要的上下文对象

  // 下面这些字段全部是"恢复用的记账"——
  autoCompactTracking: ... | undefined      // 自动压缩的追踪状态
  maxOutputTokensRecoveryCount: number      // 输出被截断后已经重试了几次
  hasAttemptedReactiveCompact: boolean      // 这一轮是否已经做过反应式压缩（幂等锁）
  maxOutputTokensOverride: number | undefined  // 是否已经把输出上限升过档
  pendingToolUseSummary: Promise<...> | undefined
  stopHookActive: boolean | undefined
  turnCount: number                         // 已经进行了几轮

  transition: Continue | undefined          // ★ 上一轮是"因为什么原因"继续的
}

claude-code/src/query.ts · State 类型定义

（type State = {...} 是 TypeScript 语言定义一个数据结构的写法，可以理解成「这个叫 State 的东西，包含以下这些字段」。number 是数字，boolean 是真/假，undefined 表示「这个字段现在没有值」。）

最后那个 transition 字段是点睛之笔

transition 这个字段完全不参与业务逻辑。它存在的唯一目的，是记录「上一轮循环是因为什么原因决定继续的」。源代码里的注释直接说明了原因：

为什么这很重要？举个具体例子。假设你要写一个测试，验证「输出被截断时会正确重试」：

七条转移边逐条解释

循环里有 7 个 continue 语句（continue 的意思是「跳过本轮剩余部分，直接开始下一轮循环」）。每一个都对应一条具名的恢复路径：

那条「接着写」的指令值得单独看

const recoveryMessage = createUserMessage({
  content:
    `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.`,
  isMeta: true,
})

claude-code/src/query.ts · 输出截断恢复

这段英文的意思是：「输出 token 上限到了。直接继续 —— 不要道歉，不要复述你刚才在做什么。如果是在句子中间被切断的，就从那里接上。把剩下的工作拆成更小的块。」

三句话解决三个真实问题：

• 「不要道歉」 —— 模型的默认行为是先说一句「抱歉，我的回复被截断了」。这句话本身就要花钱，而且毫无信息量。
• 「从句子中间接上」 —— 不这样明确许可的话，模型倾向于把刚才那段重新说一遍再往下写，浪费更多 token。
• 「拆成更小的块」 —— 防止下一次又被截断，陷入反复截断的循环。

isMeta: true 这个标记的作用是：这条消息只发给模型，不显示给用户看。用户看到的是连贯的输出，感觉不到中间发生过一次截断恢复。

每条恢复路径都必须有幂等锁

关键细节：锁只在正常推进时重置

看那张状态机图上的绿色边：只有 next_turn（正常推进，也就是模型给了工具调用、工具执行成功）这条路径，才会把所有恢复计数器清零。

为什么？因为「正常推进」意味着系统真的往前走了一步，之前的问题解决了。而走恢复路径时绝不能清零 —— 恢复本身不代表问题解决了，如果清零，就等于允许无限次重试。上面那段注释里的事故，本质就是在恢复路径上清零了。

4.3 错误扣留：可恢复的错误不能立刻往外发

这是 Claude Code 一个很精巧、也很容易被忽略的设计。

先说清楚背景：Claude Code 的主循环是一个「生成器」（generator）—— 它一边处理一边把消息吐给外部调用方（可能是终端界面，也可能是桌面应用、软件开发工具包）。

现在的问题是：当 API 返回一个可以恢复的错误（上下文过长、输出被截断、图片过大）时，该不该把这个错误吐给外部？

Claude Code 的答案是不吐，先扣住：

let withheld = false                          // withheld = 被扣留的

// 三类可恢复错误，任何一类命中就扣住
if (contextCollapse?.isWithheldPromptTooLong(message, ...)) withheld = true
if (reactiveCompact?.isWithheldPromptTooLong(message))      withheld = true
if (mediaRecoveryEnabled &&
    reactiveCompact?.isWithheldMediaSizeError(message))      withheld = true
if (isWithheldMaxOutputTokens(message))                      withheld = true

if (!withheld) { yield yieldMessage }         // 没被扣住的才吐出去

// 但无论扣不扣，都要放进内部数组，供下面的恢复逻辑找到它
if (message.type === 'assistant') assistantMessages.push(message)

claude-code/src/query.ts · 流式循环内部

只有当所有恢复路径都试过、都失败了，才把这条错误吐出去。

4.4 中断的正确处理姿势

用户按下 Ctrl+C 时，系统可能正处在这样一个状态：

（400 是另一个网络错误码，表示「你发来的请求格式不合法」。和 413「内容太长」是不同的错误。）

Claude Code 的处理分两条路：

if (toolUseContext.abortController.signal.aborted) {     // 检测到中止信号
  if (streamingToolExecutor) {
    // 用了流式执行器的情况：
    // 必须消费 getRemainingResults()，它会为"排队中"和"执行中"的工具
    // 生成合成的（也就是假造的）tool_result
    for await (const update of streamingToolExecutor.getRemainingResults()) {
      if (update.message) yield update.message
    }
  } else {
    // 没用流式执行器的情况：
    // 为每一个 tool_use 兜底造一条标记为错误的 tool_result
    yield* yieldMissingToolResultBlocks(assistantMessages, 'Interrupted by user')
  }
  return { reason: 'aborted_streaming' }
}

claude-code/src/query.ts · 中断处理

那个兜底函数 yieldMissingToolResultBlocks（意思是「吐出缺失的工具结果块」）实现很简单，但它是整个系统的安全网：

function* yieldMissingToolResultBlocks(assistantMessages, errorMessage) {
  for (const assistantMessage of assistantMessages) {       // 遍历每条模型回复
    const toolUseBlocks = assistantMessage.message.content
        .filter(c => c.type === 'tool_use')                  // 找出所有便条
    for (const toolUse of toolUseBlocks) {
      yield createUserMessage({                              // 为每张便条造一条回复
        content: [{ type:'tool_result',
                    content: errorMessage,                   // 内容是错误说明
                    is_error: true,                          // 标记为错误
                    tool_use_id: toolUse.id }],              // ★ 关键：id 必须对上
        ...
      })
    }
  }
}

这个函数在四个地方被调用：用户中断时、切换备用模型时、流式请求失败回退时、以及最外层的异常捕获里。

4.5 切换备用模型：一个想不到的坑

当主模型过载（服务器返回「容量不足」）时，需要切换到备用模型重试。Claude Code 在这里做了三件事，第三件是大多数人想不到的：

1. 把已经产生的模型回复全部打上「墓碑」标记（tombstone）—— 从界面和对话记录里彻底删除。因为这些回复来自旧模型，混在历史里会造成混乱。
2. 丢弃流式执行器里所有待定的结果，重建一个新的执行器 —— 避免带着旧工具调用 id 的孤儿结果泄露到重试后的请求里。
3. 剥离所有「思考块」的数字签名。

// Thinking signatures are model-bound: replaying a protected-thinking
// block (e.g. capybara) to an unprotected fallback (e.g. opus) 400s.
// Strip before retry so the fallback model gets clean history.
messagesForQuery = stripSignatureBlocks(messagesForQuery)

译：思考块的签名是和模型绑定的：把一个受保护的思考块（比如来自代号 capybara 的模型）重放给一个不受保护的备用模型（比如 opus），会返回 400 错误。所以重试前先剥掉签名，让备用模型拿到干净的历史。

（什么是「思考块」？较新的模型在正式回答前会先做一段内部推理，这段推理内容可以被返回给调用方，叫做 thinking block。为了防止被篡改，它带有一个加密签名。签名是特定模型生成的，换模型就验证不通过。）

源代码里关于思考块的三条规则，写得像魔法书

玩笑归玩笑，第 3 条是真正的硬约束，而且它直接限制了第 6 章所有上下文压缩的实现：

4.6 Hermes 的做法：预算驱动的循环

Hermes 的主循环入口条件本身就带了三个约束：

while (api_call_count < agent.max_iterations           # 调用次数没超上限
       and agent.iteration_budget.remaining > 0)       # 迭代预算还有余额
      or agent._budget_grace_call:                     # 或者：还有一次"宽限调用"

hermes-agent/agent/conversation_loop.py 第 2029 行

最后那个 _budget_grace_call（宽限调用）是个很有意思的设计：预算耗尽时不是硬性切断，而是再给模型一次机会，通常用来让它把已有的结果总结一下再退出。这一次调用之后无条件退出：

if agent._budget_grace_call:
    agent._budget_grace_call = False          # 消费掉宽限标记，下一轮就退出了
elif not agent.iteration_budget.consume():    # 尝试扣一次预算，扣不动了
    _turn_exit_reason = "budget_exhausted"    # 记录退出原因
    break

Hermes 也维护了一个 _turn_exit_reason（本轮退出原因）字符串，作用和 Claude Code 的 transition 字段类似 —— 纯粹为了可观测。已经在代码里见到的取值包括 interrupted_by_user（被用户中断）、review_input_budget_exhausted（审查输入预算耗尽）、budget_exhausted（预算耗尽）。

4.7 Hermes 独有的能力：轮次中途插话

这是 Claude Code 完全没有的功能：模型正在思考的时候，用户可以插一句话，而且这句话在本轮就生效。Hermes 管这个功能叫 /steer（引导）。

实现这个功能的难点有两个，而且都和前面讲过的概念直接相关：

Hermes 的解法很聪明：不新增消息，而是把插话追加到「最新一条工具结果消息」的末尾。

_pre_api_steer = agent._drain_pending_steer()       # 取出待处理的插话
if _pre_api_steer:
    for _si in range(len(messages) - 1, -1, -1):    # 从最后一条消息往前找
        _sm = messages[_si]
        if _sm.get("role") == "tool":               # 找到最近的一条"工具结果"消息
            marker = format_steer_marker(_pre_api_steer)
            _sm["content"] = existing + marker      # ★ 追加到它末尾，不新增消息
            _injected = True
            break
    if not _injected:
        # 还没有任何工具结果消息（比如第一轮）——
        # 把插话放回队列，等下一批工具结果出现时再注入
        agent._pending_steer = _pre_api_steer

hermes-agent/agent/conversation_loop.py · 调用 API 前排空插话队列

4.8 两家对照与取舍