解剖 Claude Code（二）：ReAct 循环 — while(true) 里的五个阶段与七层恢复

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

用户输入 → QueryEngine.submitMessage()
                    ↓
            ┌──────────────────┐
            │  query.ts        │  ← 本篇聚焦
            │  while(true) {   │
            │    ...1,700 行... │
            │  }               │
            └──────────────────┘
                    ↓
            Ink 渲染引擎 → 终端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

type State = {
  messages: Message[]                         // 对话历史（持续增长）
  toolUseContext: ToolUseContext               // 工具执行上下文
  autoCompactTracking: AutoCompactTrackingState  // 压缩状态追踪
  maxOutputTokensRecoveryCount: number        // 输出截断恢复次数（上限 3）
  hasAttemptedReactiveCompact: boolean        // 是否已尝试紧急压缩
  maxOutputTokensOverride: number | undefined // Token 上限覆盖（8K→64K）
  pendingToolUseSummary: Promise<...>         // 上一轮的工具摘要（异步）
  stopHookActive: boolean                     // Stop Hook 是否激活
  turnCount: number                           // 当前轮次
  transition: Continue | undefined            // 上一次继续的原因
}

1
2
3
4
5
6
7
8
9

Tool Result Budget (单消息上限)
       ↓
    Snip (历史裁剪)
       ↓
    Microcompact (工具结果压缩)
       ↓
    Context Collapse (选择性归档)
       ↓
    Autocompact (AI 全量摘要)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

for await (const message of deps.callModel({
  messages: prependUserContext(messagesForQuery, userContext),
  systemPrompt: fullSystemPrompt,
  tools: toolUseContext.options.tools,
  signal: toolUseContext.abortController.signal,
  options: {
    model: currentModel,
    fallbackModel,
    maxOutputTokensOverride,   // 可能已从 8K 升至 64K
    fastMode: appState.fastMode,
    taskBudget: { total, remaining },
    queryTracking: { chainId, depth },
    // ...
  }
})) {
  // 流式处理每个消息块
}

1
2
3
4

if (msgToolUseBlocks.length > 0) {
  toolUseBlocks.push(...msgToolUseBlocks)
  needsFollowUp = true   // 标记：本轮需要继续循环
}

1
2
3
4
5
6
7

canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executing = this.tools.filter(t => t.status === 'executing')
  return (
    executing.length === 0 ||
    (isConcurrencySafe && executing.every(t => t.isConcurrencySafe))
  )
}

1

queued → executing → completed → yielded

1
2
3

partitionToolCalls(toolUseBlocks)
  → 并发安全工具分到同一批（并行，最多 10 个）
  → 非安全工具各自一批（串行）

1
2
3
4
5

// 工具摘要是异步的——这一轮生成，下一轮才消费
nextPendingToolUseSummary = generateToolUseSummary({
  tools: toolInfoForSummary,
  signal: toolUseContext.abortController.signal,
}).catch(() => null)  // 失败也不阻塞

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

模型调用了工具？
  ├─ 是 → needsFollowUp = true → 继续循环
  └─ 否 → 进入终止检查

终止检查链：
  1. API 错误？→ 执行失败 Hook，返回 'completed'
  2. Stop Hook 阻止？→ 返回 'stop_hook_prevented'
  3. Stop Hook 报错？→ 注入错误消息，继续循环（reason: 'stop_hook_blocking'）
  4. Token Budget 未用完？→ 注入 nudge 消息，继续循环
  5. 超过 maxTurns？→ 返回 'max_turns'
  6. 以上都不是 → 返回 'completed'

1
2
3
4
5
6
7

if (state.transition?.reason !== 'collapse_drain_retry') {
  // 只尝试一次，避免双重 drain
  const drained = contextCollapse.recoverFromOverflow(messagesForQuery)
  if (drained.committed > 0) {
    continue  // reason: 'collapse_drain_retry'
  }
}

1
2
3
4
5
6

if (!hasAttemptedReactiveCompact) {
  const result = reactiveCompact.tryReactiveCompact({...})
  if (result) {
    continue  // reason: 'reactive_compact_retry'
  }
}

1
2
3
4

// 代码注释原文：
// Do NOT fall through to stop hooks: the model never produced a valid response,
// so hooks have nothing meaningful to evaluate. Running stop hooks on
// prompt-too-long creates a death spiral: error → hook blocking → retry → error → …

1
2
3
4
5

if (capEnabled && maxOutputTokensOverride === undefined) {
  // 从默认的 8K 升级到 64K——单次升级，同一请求内立即重试
  maxOutputTokensOverride = 64_000  // ESCALATED_MAX_TOKENS
  continue  // reason: 'max_output_tokens_escalate'
}

1
2
3
4
5
6
7
8

if (maxOutputTokensRecoveryCount < 3) {  // MAX_OUTPUT_TOKENS_RECOVERY_LIMIT
  const recoveryMessage = createUserMessage({
    content: 'Output token limit hit. Resume directly — no apology, no recap...',
    isMeta: true,  // 对 UI 不可见
  })
  maxOutputTokensRecoveryCount++
  continue  // reason: 'max_output_tokens_recovery'
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

Turn 1: 用户输入 "帮我重构 parseConfig 函数"
  Phase 1: 无需压缩（对话刚开始）
  Phase 2: 模型调用 GrepTool 搜索 "parseConfig"
  Phase 3: GrepTool 并发执行（read-only，并发安全）
  Phase 4: 收集搜索结果
  Phase 5: needsFollowUp=true → continue (reason: 'next_turn')

Turn 2:
  Phase 1: 无需压缩
  Phase 2: 模型调用 FileReadTool 读取文件 + GlobTool 查找相关文件
  Phase 3: 两个工具并行执行（都是只读）
  Phase 4: 收集文件内容
  Phase 5: needsFollowUp=true → continue

Turn 3:
  Phase 1: 无需压缩
  Phase 2: 模型调用 FileEditTool 修改代码
  Phase 3: FileEditTool 串行执行（写操作，非并发安全）
  Phase 4: 记录文件变更
  Phase 5: needsFollowUp=true → continue

Turn 4:
  Phase 1: 无需压缩
  Phase 2: 模型调用 BashTool 运行测试
  Phase 3: BashTool 串行执行
  Phase 4: 收集测试结果
  Phase 5: needsFollowUp=true → continue

Turn 5:
  Phase 1: 无需压缩
  Phase 2: 模型输出最终回复（无工具调用）
  Phase 3: 跳过
  Phase 4: 后台生成工具摘要、提取记忆
  Phase 5: needsFollowUp=false → Stop Hook 通过 → 返回 'completed'

1
2
3
4
5
6
7
8

Turn 3 (异常路径):
  Phase 2: API 返回 413 → 暂扣错误
  Recovery L4: Context Collapse → 释放了 20K Token → continue (reason: 'collapse_drain_retry')
  
Turn 3 (重试):
  Phase 1: 上下文已缩小
  Phase 2: API 调用成功，模型继续编辑
  → 恢复正常流程