claude-code with OpenAI mode fix

2026-06-18 14:25:51 +00:00 · 2026-04-04 01:21:00 +08:00
commit c9f95fc34d
3050 changed files with 557030 additions and 0 deletions
--- a/docs/conversation/multi-turn.mdx
+++ b/docs/conversation/multi-turn.mdx
@@ -0,0 +1,184 @@
+---
+title: "多轮对话管理 - QueryEngine 会话编排与持久化"
+description: "从源码角度解析 Claude Code 多轮对话管理：QueryEngine 的会话状态机、JSONL transcript 持久化、成本追踪模型和模型热切换机制。"
+keywords: ["多轮对话", "会话管理", "QueryEngine", "transcript", "成本追踪"]
+---
+
+{/* 本章目标：从源码角度揭示会话编排、持久化存储、成本追踪和模型切换的完整链路 */}
+
+## 单轮 vs 多轮：架构层面的差异
+
+- **单轮**（一次 Agentic Loop）：`query()` 函数的一次完整执行——组装上下文 → 调 API → 处理工具调用 → 循环直到结束
+- **多轮**（一个 Session）：`QueryEngine` 类管理的一次会话——跨越数十轮 `submitMessage()` 调用，持续数小时
+
+`QueryEngine`（`src/QueryEngine.ts:186`）是单轮 Agentic Loop 之上的**会话编排器**，它管理的状态远不止消息列表：
+
+```
+QueryEngine 内部状态
+├── mutableMessages: Message[]         ← 完整对话历史，跨 turn 累积
+├── readFileState: FileStateCache      ← 已读文件内容缓存，避免重复读取
+├── totalUsage: NonNullableUsage       ← 累计 token 消耗（input/output/cache）
+├── permissionDenials: SDKPermissionDenial[]  ← 权限拒绝记录
+├── discoveredSkillNames: Set<string>  ← 当前 turn 已发现的 skill
+└── abortController: AbortController   ← 会话级中断控制
+```
+
+## QueryEngine 的核心方法：submitMessage()
+
+每次用户输入一条消息，REPL 或 SDK 调用 `submitMessage()`，它会执行完整的 turn 初始化链路：
+
+```typescript
+// src/QueryEngine.ts:211 — 简化的 submitMessage 流程
+async *submitMessage(prompt, options?): AsyncGenerator<SDKMessage> {
+  // 1. 清除 turn 级追踪状态
+  this.discoveredSkillNames.clear()
+  
+  // 2. 解析模型（用户可能中途切换了模型）
+  const mainLoopModel = userSpecifiedModel
+    ? parseUserSpecifiedModel(userSpecifiedModel)
+    : getMainLoopModel()
+  
+  // 3. 动态组装 System Prompt（每次 turn 都重新构建）
+  const { defaultSystemPrompt, userContext, systemContext } =
+    await fetchSystemPromptParts({ tools, mainLoopModel, mcpClients })
+  
+  // 4. 包装权限检查（追踪每次拒绝）
+  const wrappedCanUseTool = async (tool, input, ...) => {
+    const result = await canUseTool(tool, input, ...)
+    if (result.behavior !== 'allow') {
+      this.permissionDenials.push({ tool_name: tool.name, ... })
+    }
+    return result
+  }
+  
+  // 5. 调用核心 query() 函数执行 agentic loop
+  yield* query({
+    systemPrompt, messages: this.mutableMessages,
+    tools, model: mainLoopModel, ...
+  })
+}
+```
+
+关键设计：`submitMessage()` 是 `async *Generator`——它逐步 yield `SDKMessage`，让调用方（REPL/SDK）能实时展示进度，而不是等整个 turn 结束。
+
+## 会话持久化：JSONL Transcript
+
+每次对话事件都被追加写入 transcript 文件（`src/utils/sessionStorage.ts`）：
+
+### 存储路径
+
+```
+~/.claude/projects/<project-hash>/<session-id>.jsonl
+```
+
+- `project-hash` 由 `getProjectDir(originalCwd)` 生成，同一项目目录的会话归入同一子目录
+- 每条记录是一行 JSON（JSONL 格式），支持追加写入而不需要读取-修改-写入整个文件
+- 读取上限为 50MB（`MAX_TRANSCRIPT_READ_BYTES`），防止超大会话导致 OOM
+
+### Transcript 写入器
+
+`TranscriptWriter`（`src/utils/sessionStorage.ts:1200+`）是一个写队列，确保并发的消息追加不会互相覆盖：
+
+```
+写入流程：
+  appendEntryToFile(sessionId, entry)
+    ↓
+  ensureCurrentSessionFile()   ← 懒初始化：首次写入时才创建文件
+    ↓
+  序列化为 JSON + 换行符
+    ↓
+  appendFile(path, line)       ← 原子追加
+    ↓
+  如果配置了远程持久化：
+    persistToRemote(sessionId, entry)
+      ├── CCR v2: internalEventWriter('transcript', entry)
+      └── v1 Ingress: sessionIngress.appendSessionLog(...)
+```
+
+### 会话恢复链路
+
+`--resume` 参数触发的恢复流程（`src/main.tsx:3620+`）：
+
+```
+1. 解析 resume 参数：
+   ├── UUID 格式 → getTranscriptPathForSession(uuid)
+   ├── .jsonl 文件路径 → 直接使用
+   └── boolean → 最近一次会话的 picker
+   
+2. loadTranscriptFromFile(path)
+   ├── 按 JSONL 行解析
+   ├── 过滤出消息类型记录
+   └── 重建 Message[] 数组
+
+3. 恢复上下文状态：
+   ├── restoreCostStateForSession(sessionId)  ← 恢复累计费用
+   ├── 恢复 agentSetting（用户选择的 Agent 类型）
+   └── 如果有 --rewind-files，恢复文件到指定消息时的快照
+
+4. 创建 QueryEngine({ initialMessages: restoredMessages })
+   └── 从恢复的消息继续对话
+```
+
+## 成本追踪：从 API Usage 到美元
+
+成本追踪贯穿三个模块，形成完整的记录→累计→展示链路：
+
+### 记录层：API 响应中的 Usage
+
+每个 `message_delta` 事件携带 `usage` 字段（`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens`）。`accumulateUsage()` 将增量 usage 累加到会话总量。
+
+### 累计层：cost-tracker.ts
+
+```typescript
+// src/cost-tracker.ts — StoredCostState 数据模型
+type StoredCostState = {
+  totalCostUSD: number                       // 累计美元花费
+  totalAPIDuration: number                   // API 调用总时长（含重试）
+  totalAPIDurationWithoutRetries: number     // 不含重试的纯推理时间
+  totalToolDuration: number                  // 工具执行总时长
+  totalLinesAdded: number                    // 代码增加行数
+  totalLinesRemoved: number                  // 代码删除行数
+  modelUsage: { [modelName: string]: ModelUsage }  // 按模型分拆的用量
+}
+```
+
+`addToTotalSessionCost()` 根据模型定价计算每次 API 调用的费用，累计到 `totalCostUSD`。按模型的 `ModelUsage` 支持在同一会话中切换模型后分别统计。
+
+### 持久化：跨重启保留
+
+```typescript
+// 每次会话结束时保存到项目配置
+saveCurrentSessionCosts(sessionId)
+  → projectConfig.lastCost = totalCostUSD
+  → projectConfig.lastSessionId = sessionId
+  → projectConfig.lastModelUsage = modelUsage
+```
+
+### 预算熔断
+
+`QueryEngineConfig.maxBudgetUsd` 提供了会话级的硬性预算上限。在 REPL 中，当累计费用超过 $5 时（`src/screens/REPL.tsx:2208`），弹出费用提醒对话框——这不是硬性阻断，而是"软提醒"。
+
+## 模型热切换
+
+在一个会话中切换模型不会丢失对话历史——因为 `mutableMessages` 与模型选择是解耦的：
+
+```
+/model sonnet → setMainLoopModelOverride('claude-sonnet-4-20250514')
+  ↓
+下一次 submitMessage() 开始时：
+  ↓
+parseUserSpecifiedModel(userSpecifiedModel)
+  → 返回新的模型配置
+  ↓
+fetchSystemPromptParts({ mainLoopModel: newModel })
+  → System Prompt 根据新模型能力重新组装
+  ↓
+query({ model: newModel, messages: this.mutableMessages })
+  → 使用完整历史 + 新模型继续对话
+```
+
+切换模型时，`contextWindowTokens` 和 `maxOutputTokens` 也会根据新模型的规格重新计算——例如从 Sonnet 切换到 Opus 时，上下文窗口可能从 200K 变为 1M。
+
+## 文件快照与回滚
+
+`fileHistoryMakeSnapshot()`（`src/utils/fileHistory.ts`）在 AI 每次修改文件前自动保存当前内容。快照绑定到具体的 `message.id`，使得 `--rewind-files <user-message-id>` 可以精确恢复到对话中任意时间点的文件状态——这比 git 更细粒度（git 只追踪已提交的内容）。
--- a/docs/conversation/streaming.mdx
+++ b/docs/conversation/streaming.mdx
@@ -0,0 +1,183 @@
+---
+title: "流式响应机制 - Claude Code 打字机效果原理"
+description: "解析 Claude Code 流式响应实现：如何通过 SSE 逐 token 接收 AI 输出，实现实时打字机效果，提升用户等待体验。"
+keywords: ["流式响应", "SSE", "streaming", "实时输出", "API streaming"]
+---
+
+## 为什么需要流式
+
+想象 AI 需要 30 秒才能生成完整回答——如果等 30 秒后才一次性显示，用户体验是灾难性的。
+
+流式响应让用户**实时看到 AI 的思考过程**：
+- 文字逐字出现，用户能提前判断方向是否正确
+- 工具调用的参数在生成过程中就能预览
+- 长时间任务不会让用户觉得"卡死了"
+
+## `BetaRawMessageStreamEvent` 核心事件类型
+
+流式 API 返回的是一系列 `BetaRawMessageStreamEvent`，每种事件类型对应流式响应的不同阶段（`src/services/api/claude.ts`）：
+
+```
+message_start           ← 消息开始，包含 model、usage 初始值
+  ├── content_block_start   ← 内容块开始（text / tool_use / thinking）
+  │   ├── content_block_delta  ← 增量数据（text_delta / input_json_delta / thinking_delta）
+  │   ├── content_block_delta  ← ... 持续到达
+  │   └── content_block_stop   ← 内容块结束，yield AssistantMessage
+  ├── content_block_start   ← 下一个内容块...
+  │   └── ...
+  └── message_delta       ← stop_reason + 最终 usage
+message_stop            ← 消息结束
+```
+
+### 事件处理状态机
+
+`src/services/api/claude.ts:1980-2298` 实现了一个基于 `switch(part.type)` 的状态机：
+
+| 事件类型 | 处理逻辑 | 状态变更 |
+|----------|----------|----------|
+| `message_start` | 初始化 `partialMessage`，记录 TTFT（首字节延迟） | `usage` 初始化 |
+| `content_block_start` | 按 `part.index` 创建对应类型的内容块 | `contentBlocks[index]` 初始化 |
+| `content_block_delta` | 按子类型增量追加数据 | text / thinking / input 累加 |
+| `content_block_stop` | 构建完整 `AssistantMessage` 并 yield | 消息推入 `newMessages` |
+| `message_delta` | 更新 stop_reason 和最终 usage | 写回最后一条消息 |
+| `message_stop` | 无操作（流结束标记） | — |
+
+### 内容块类型及其增量数据
+
+`content_block_start` 中的 `content_block.type` 决定了如何处理后续 delta：
+
+| 内容块类型 | Delta 类型 | 累加逻辑 |
+|-----------|-----------|----------|
+| `text` | `text_delta` | `text += delta.text` |
+| `thinking` | `thinking_delta` + `signature_delta` | `thinking += delta.thinking`，`signature = delta.signature` |
+| `tool_use` | `input_json_delta` | `input += delta.partial_json`（JSON 字符串增量拼接） |
+| `server_tool_use` | `input_json_delta` | 同 tool_use |
+| `connector_text` | `connector_text_delta` | 特殊连接器文本（feature flag 控制） |
+
+关键设计：`content_block_start` 时所有文本字段初始化为空字符串，只通过 `content_block_delta` 累加。这是因为 SDK 有时在 start 和 delta 中重复发送相同文本。
+
+## 文本 chunk 和 tool_use block 的交织
+
+一次 AI 响应可能包含多个内容块，交替出现：
+
+```
+content_block_start (text, index=0)     "我来帮你修复这个 bug。"
+content_block_delta  (text_delta)       "首先..."
+content_block_stop  (index=0)
+content_block_start (tool_use, index=1) { name: "Read", input: "..." }
+content_block_delta  (input_json_delta) '{"file_p' → 'ath":' → '"src/foo.ts"}'
+content_block_stop  (index=1)
+content_block_start (text, index=2)     "我已经看到了问题所在..."
+content_block_stop  (index=2)
+```
+
+每个 `content_block_stop` 触发一次 `yield`，将完整的 AssistantMessage 推送给消费者。这意味着一个 AI 响应会产生**多条** `AssistantMessage`——文本消息和工具调用消息交替产出。
+
+`stop_reason` 要等到 `message_delta` 才确定（可能是 `end_turn`、`tool_use`、`max_tokens` 等），所以最后一条消息的 `stop_reason` 是**回写**的：
+
+```typescript
+// claude.ts:2246 — 直接属性修改，不用对象替换
+// 因为 transcript 写队列持有 message.message 的引用
+const lastMsg = newMessages.at(-1)
+if (lastMsg) {
+  lastMsg.message.usage = usage
+  lastMsg.message.stop_reason = stopReason
+}
+```
+
+## 流式中的错误处理
+
+### 网络断开
+
+流式连接依赖 SSE（Server-Sent Events）。当连接中断时：
+
+1. **Stream idle watchdog**：定时检测事件间隔，超过阈值（stall）触发告警和重试
+2. **Stream abort**：如果 watchdog 检测到长时间无事件，抛出错误进入重试流程
+3. **非流式降级**：作为最后手段，回退到非流式请求（一次性获取完整响应）
+
+```typescript
+// claude.ts:2338-2355 — 检测空流
+// 1. 完全没有事件 → 代理返回了非 SSE 响应
+// 2. 有 message_start 但没有 content_block_stop → 流被截断
+```
+
+### API 限流
+
+当 API 返回限流错误时，系统使用 `withRetry` 包装器进行指数退避重试。重试逻辑考虑了：
+- 错误类型（429 限流 vs 500 服务器错误）
+- 重试次数上限
+- 退避间隔
+
+### Token 超限
+
+两种 token 超限场景有不同的处理：
+
+| 场景 | stop_reason | 处理方式 |
+|------|------------|----------|
+| **输出超限** | `max_tokens` | 生成错误消息，建议设置 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` |
+| **上下文窗口超限** | `model_context_window_exceeded` | 触发 compaction 压缩对话历史后重试 |
+
+```typescript
+// claude.ts:2267-2293
+if (stopReason === 'max_tokens') {
+  yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
+}
+if (stopReason === 'model_context_window_exceeded') {
+  // 复用 max_output_tokens 的恢复路径
+  yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
+}
+```
+
+### 流式停滞检测
+
+系统持续监控事件到达间隔，检测"停滞"（stall）：
+
+```typescript
+// claude.ts:1940-1966
+const STALL_THRESHOLD_MS = 10_000  // 10 秒无事件视为停滞
+if (timeSinceLastEvent > STALL_THRESHOLD_MS) {
+  stallCount++
+  totalStallTime += timeSinceLastEvent
+  logEvent('tengu_streaming_stall', { stall_duration_ms, stall_count, ... })
+}
+```
+
+多个 stall 累积后，watchdog 可能决定中断流并触发重试。
+
+## 工具执行的流式反馈
+
+BashTool 的命令执行也是流式的——通过 `onProgress` 回调逐行推送输出：
+
+```
+BashTool.call() → runShellCommand() → AsyncGenerator
+  ├── 每秒轮询输出文件 → onProgress(lastLines, allLines, ...)
+  ├── yield { type: 'progress', output, fullOutput, elapsedTimeSeconds }
+  └── return { code, stdout, interrupted, ... }
+```
+
+UI 层通过 `useToolCallProgress` hook 实时展示命令输出，而不是等命令完全结束。长时间运行的命令还支持自动后台化（`shouldAutoBackground`）。
+
+## 多 Provider 适配
+
+| Provider | 流式协议 | 特殊处理 |
+|----------|----------|----------|
+| **Anthropic Direct** | 原生 SSE | 延迟最低，TTFT 最快 |
+| **AWS Bedrock** | AWS SDK 流式接口 | 需要额外的 beta header 和认证 |
+| **Google Vertex** | gRPC → 事件流 | 通过 `getMergedBetas()` 适配 |
+| **Azure** | Anthropic 兼容 API | 自定义 base URL |
+
+所有 Provider 通过统一的 `Stream<BetaRawMessageStreamEvent>` 抽象层屏蔽差异。上层代码（QueryEngine、REPL）不需要关心底层用的是哪个 Provider。
+
+### Provider 选择
+
+`src/utils/model/providers.ts` 中的 `getAPIProvider()` 根据配置决定使用哪个 Provider：
+
+```typescript
+// 根据 api_provider 配置选择：
+// "anthropic" → 直连
+// "bedrock"   → AWS SDK
+// "vertex"    → Google SDK
+// 第三方 base URL → 自动检测
+```
+
+每个 Provider 需要适配的细节包括：认证方式、beta header、请求参数格式、错误码映射——但这些差异在 `claude.ts` 的 `queryStream()` 函数中被统一处理。
--- a/docs/conversation/the-loop.mdx
+++ b/docs/conversation/the-loop.mdx
@@ -0,0 +1,182 @@
+---
+title: "Agentic Loop：AI 自主循环的核心机制"
+description: "深入解析 Claude Code 的 query() 异步生成器循环——从流式 API 调用、工具并行执行、上下文压缩、错误恢复到终止条件的完整状态机，基于 src/query.ts 的源码级分析。"
+keywords: ["Agentic Loop", "query loop", "tool_use", "状态机", "auto-compact", "streaming", "recovery"]
+---
+
+{/* 本章目标：基于 src/query.ts 揭示 Agentic Loop 的完整状态机 */}
+
+## 什么是 Agentic Loop
+
+传统聊天机器人：你问一句，它答一句。  
+Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
+
+这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数（第 241 行）。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
+
+<Frame caption="Agentic Loop 循环示意">
+  <img src="/docs/images/agentic-loop.png" alt="Agentic Loop 循环图" />
+</Frame>
+
+## 循环的完整结构
+
+`queryLoop()` 的每次迭代（`src/query.ts:307` `while(true)`）包含以下阶段：
+
+### 阶段 1：上下文预处理（Pre-Processing Pipeline）
+
+在调用 API 之前，依次执行 5 个压缩/优化步骤：
+
+```
+messagesForQuery（原始消息）
+  ↓ applyToolResultBudget()    — 工具结果预算截断（按 maxResultSizeChars）
+  ↓ snipCompactIfNeeded()      — 历史 Snip 压缩（HISTORY_SNIP feature）
+  ↓ microcompact()             — 微压缩（工具结果摘要）
+  ↓ applyCollapsesIfNeeded()   — 上下文折叠（CONTEXT_COLLAPSE feature）
+  ↓ autocompact()              — 自动压缩（超出阈值时触发）
+messagesForQuery（处理后的消息）→ 发往 API
+```
+
+每个步骤的输出是下一步的输入，形成串行管道。Snip 和 Microcompact 的释放 token 数会传递给 autocompact 的阈值计算（`snipTokensFreed`），避免重复压缩。
+
+### 阶段 2：流式 API 调用（Streaming Loop）
+
+`deps.callModel()` 发起流式请求（第 659 行），返回一个 AsyncGenerator。在流式过程中：
+
+- **AssistantMessage** 被收集到 `assistantMessages[]` 数组
+- **tool_use 块** 被提取到 `toolUseBlocks[]`，设置 `needsFollowUp = true`
+- **StreamingToolExecutor** 在流式过程中就开始并行执行工具（不等流结束）
+- 可恢复的错误（prompt-too-long、max-output-tokens）被**暂扣**（withheld），先尝试恢复
+
+流式回调中的关键守卫：
+- `backfillObservableInput()`（第 763 行）—— 为 tool_use 块回填可观察字段（如文件路径展开），但只在添加了新字段时才克隆消息，避免破坏 prompt cache 的字节一致性
+- 流式降级检测——如果 `streamingFallbackOccured`，已收集的消息被标记为 tombstone（第 717 行），清空后重试
+
+### 阶段 3：工具执行（Tool Execution）
+
+如果 `needsFollowUp` 为 true，循环不会终止，而是执行工具：
+
+```typescript
+// 两种工具执行器（互斥）
+const toolUpdates = streamingToolExecutor
+  ? streamingToolExecutor.getRemainingResults()  // 流式：获取已完成的+等待中的
+  : runTools(toolUseBlocks, assistantMessages, canUseTool, toolUseContext)
+```
+
+工具结果通过 `normalizeMessagesForAPI()` 标准化后，与原始消息合并，进入**下一轮循环迭代**。
+
+### 阶段 4：终止或继续
+
+每次迭代结束时，根据条件决定 `return`（终止）或 `continue`（继续）：
+
+## 7 种终止条件（源码级）
+
+| 终止原因 | 触发位置 | 机制 |
+|----------|---------|------|
+| **completed** | 第 1360 行 | AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
+| **blocking_limit** | 第 646 行 | Token 计数超过硬限制（非 autocompact 模式）→ 生成 PTL 错误消息 → 返回 |
+| **aborted_streaming** | 第 1054 行 | `abortController.signal.aborted` → 为未完成的 tool_use 生成合成 tool_result → 返回 |
+| **model_error** | 第 999 行 | `callModel()` 抛出异常 → 生成错误消息 → 返回 |
+| **prompt_too_long** | 第 1178 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
+| **image_error** | 第 980/1178 行 | 图片尺寸/大小错误 → 直接返回 |
+| **stop_hook_prevented** | 第 1282 行 | Stop hook 返回 `preventContinuation: true` → 返回 |
+
+## 4 种继续条件（恢复路径）
+
+循环不仅是一个简单的"有 tool_use 就继续"，它还包含多种恢复/重试路径：
+
+### 1. 正常工具循环
+`needsFollowUp = true` → 执行工具 → 新消息追加到 `messagesForQuery` → `continue`
+
+### 2. max_output_tokens 恢复（第 1191-1255 行）
+当 AI 输出被截断时（`apiError === 'max_output_tokens'`）：
+- **首次**：尝试将 `maxOutputTokens` 从默认值提升到 `ESCALATED_MAX_TOKENS`（64K），无 meta 消息，静默重试
+- **后续**：注入恢复消息"Output token limit hit. Resume directly..."，最多重试 `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3` 次
+- 恢复耗尽后，暂扣的错误消息被释放
+
+### 3. Prompt-Too-Long 恢复（第 1088-1186 行）
+当遇到 413 错误时，有两个恢复阶段：
+- **Context Collapse Drain**（第 1097 行）：提交所有已暂存的折叠，释放空间后重试。如果上一轮已经是 collapse_drain_retry 则跳过
+- **Reactive Compact**（第 1123 行）：触发即时压缩，生成摘要后重试。`hasAttemptedReactiveCompact` 防止无限循环
+
+### 4. Stop Hook 阻塞重试（第 1285-1308 行）
+Stop hook 可以注入阻塞错误消息，强制 AI 重新思考。新的消息（包含阻塞错误）被追加到对话中，`stopHookActive = true`，进入下一轮迭代。
+
+## 模型降级（Fallback）
+
+当主模型不可用时（`FallbackTriggeredError`，第 897 行）：
+
+1. 已收集的 `assistantMessages` 被清空，tool_use 块收到合成 tool_result："Model fallback triggered"
+2. 思维签名块被移除（`stripSignatureBlocks`）—— 因为思维签名与模型绑定，跨模型回放会 400
+3. 切换到 `fallbackModel`，更新 `toolUseContext.options.mainLoopModel`
+4. 生成系统消息："Switched to {fallback} due to high demand for {original}"
+5. 重新发起流式请求
+
+## 状态机：State 对象
+
+每次迭代的状态通过 `State` 类型（第 204 行）传递：
+
+```typescript
+type State = {
+  messages: Message[]                        // 当前对话消息
+  toolUseContext: ToolUseContext              // 工具上下文（含权限）
+  autoCompactTracking: AutoCompactTrackingState  // 压缩跟踪
+  maxOutputTokensRecoveryCount: number       // 输出截断恢复计数
+  hasAttemptedReactiveCompact: boolean       // 是否已尝试即时压缩
+  maxOutputTokensOverride: number | undefined // 输出 token 上限覆盖
+  pendingToolUseSummary: Promise<...> | undefined  // 异步工具摘要
+  stopHookActive: boolean | undefined        // Stop hook 是否激活
+  turnCount: number                          // 轮次计数
+  transition: Continue | undefined           // 上一次继续的原因
+}
+```
+
+每次 `continue` 都创建新的 State 对象（不可变更新），而非就地修改。`transition` 字段记录了为什么继续——让后续迭代能检测特定恢复路径（如 `collapse_drain_retry`）避免循环。
+
+## Token Budget（实验性）
+
+当 `TOKEN_BUDGET` feature 启用时（第 1311 行），循环在终止前会检查 token 消耗：
+
+- **continuation**：未达到预算但超过阈值 → 注入 nudge 消息，让 AI 加速收尾
+- **diminishing_returns**：检测到收益递减 → 提前终止
+- 预算数据来自 `createBudgetTracker()`，跨迭代累计
+
+## 为什么不是"一次规划，批量执行"
+
+<Note>
+源码揭示了为什么 Claude Code 选择逐步循环：
+</Note>
+
+- **每一步都产生真实信息**：`runTools()` 返回的 `toolResults` 是 API 不可能预知的——命令输出、文件内容、错误信息
+- **动态上下文管理**：每轮迭代前都重新评估压缩需求（autocompact → microcompact → snip），基于最新的 token 计数
+- **错误即时恢复**：工具失败不需要推倒重来——stop hook 可以注入阻塞错误让 AI 修正策略
+- **用户可控**：`abortController.signal` 在循环的多个检查点被检测（第 1018、1048、1488 行），用户按 ESC 可以优雅中断
+- **成本控制**：Token Budget 在每轮终止前检查，防止 AI 无效循环
+
+## 一个完整的迭代示例
+
+> 用户："帮我找到项目里所有未使用的导入语句，然后删掉它们"
+
+```
+迭代 1: 思考→行动
+  预处理: 无需压缩（上下文很短）
+  API 调用: 返回 tool_use(Glob, "**/*.ts")
+  工具执行: 返回 42 个文件路径
+  → needsFollowUp = true, continue
+
+迭代 2: 思考→行动
+  预处理: 42 个文件结果仍在预算内
+  API 调用: 返回 tool_use(Grep, "import.*from")
+  工具执行: 在 15 个文件中找到 120 条 import
+  → needsFollowUp = true, continue
+
+迭代 3: 思考→行动（多轮）
+  预处理: 120 条 Grep 结果触发 microcompact → 摘要化
+  API 调用: 返回 3 个 tool_use(FileEdit, ...)
+  工具执行: 删除 5 条未使用导入
+  → needsFollowUp = true, continue
+
+迭代 4: 总结
+  API 调用: 返回纯文本"已清理 3 个文件中的 5 条未使用导入"
+  → needsFollowUp = false
+  → Stop hooks 通过
+  → return { reason: 'completed' }
+```