夜雨聆风学习资料网

ARTICLE · 1361807

Claude Code 源码-QueryEngine 流式事件循环与错误恢复

Claude Code 源码-QueryEngine 流式事件循环与错误恢复

Claude Code 源码解析系列

第 6 讲:QueryEngine 流式事件循环与错误恢复

基于 Claude Code 源码快照 · 2026-11-16

💡 本讲一句话:上一讲讲 turn 状态机怎么"编排工具",这一讲讲更底层的问题——模型的事件流是一条随时会断的管道:过载、限流、网络抖动、用户按 Esc。Claude Code 用 tombstone 清场、错误扣留(withhold)、指数退避心跳和模型降级四套机制,保证任何一条路径上 UI 都不出现"半截消息 + 悬空 tool_use"这种脏状态。

一、流式消费循环:每条消息要过三道闸

第 5 讲我们看过 query() 生成器的骨架。这一讲钻进它最核心的那段循环:for await (const message of deps.callModel(...))。模型不是"一次返回一个答案",而是一条事件流——每个 content block、每次 usage 更新都是独立的消息对象,逐条 yield 出来。UI 的增量渲染就靠这个:消息一到就画,不用等整轮结束。

但"边收边画"有个致命问题:流到一半出事了怎么办?已经画出去的消息、已经启动的工具执行器、已经发给 API 的 tool_use——这些状态在降级或重试时全部要处理。源码的答案是:每条消息进入循环体后,先过三道闸(fallback 清场 → backfill 克隆 → withhold 扣留),只有全过的才 yield 给 UI。

📄 src/query.ts (第 650-708 行,节选)

let attemptWithFallback = true // 降级开关:只有模型降级后才会让 while 循环再进一次try { // 外层 try:兜住整个流式阶段的异常  while (attemptWithFallback) { // 默认只跑一遍;降级后才会再进    attemptWithFallback = false // 先复位——默认每轮只跑一遍,不主动重试    try { // 内层 try:捕获单次尝试的异常(含 FallbackTriggeredError)      let streamingFallbackOccured = false // 记录"流到一半"是否发生了降级      queryCheckpoint('query_api_streaming_start') // 打点:测量流式阶段耗时(性能剖析用)      for await (const message of deps.callModel({ // 逐条消费模型事件流——本讲的核心循环        messages: prependUserContext(messagesForQuery, userContext), // 发送前注入用户上下文前缀        systemPrompt: fullSystemPrompt, // 完整系统提示词(含 CLAUDE.md 等)        thinkingConfig: toolUseContext.options.thinkingConfig, // extended thinking 配置        tools: toolUseContext.options.tools, // 可用工具清单        signal: toolUseContext.abortController.signal, // 中断信号——用户按 Esc 会一路传到 API 层        options: { // API 层选项包          model: currentModel, // 当前主循环模型(可能被降级替换)          fallbackModel, // 备用模型:529 过载达到阈值时 withRetry 抛 FallbackTriggeredError          onStreamingFallback: () => { // 降级回调函数体            streamingFallbackOccured = true // API 层回调:告知"这条流已经发生过程内降级"          }, // 降级回调结束        }, // options 包结束      })) { // 开始消费事件流——每条消息过下面三道闸

为什么这样设计:注意 attemptWithFallback 这个标志位——它把"模型降级重试"和"普通错误重试"分成了两个层次。withRetry 内部的退避重试是同参数重发(同一个模型、同一份消息),而这里的外层 while 是换模型重放(整个请求重来)。两层分离的好处:降级只发生一次(标志位复位后不会再触发),不会因为"降级后又过载"陷入无限循环;同时 onStreamingFallback 回调让 API 层能在流式过程中主动上报降级,而不是等整条流结束才暴露。

另外注意 signal 的传递:abortController 的信号一路穿透到 HTTP 请求层。这意味着用户按 Esc 不是"UI 假装停了",而是真正掐断网络请求——后面第九节会看到中断路径如何善后。

二、闸 0:降级后的 tombstone 清场

假设流已经画出去一半(几个 thinking block、一个 tool_use),这时 API 层触发降级。问题是:这些"半截消息"已经进了 UI 和 transcript,而且它们的 thinking 签名是无效的(流没走完,签名不完整)。如果带着它们重放给新模型,API 会直接报 "thinking blocks cannot be modified"。

📄 src/query.ts (第 712-740 行)

if (streamingFallbackOccured) { // 流内降级发生 → 先把失败流的所有状态清干净  for (const msg of assistantMessages) { // 遍历失败流的全部半截消息    yield { type: 'tombstone' as const, message: msg } // tombstone:通知 UI 和 transcript 删除这条半截消息  }  logEvent('tengu_orphaned_messages_tombstoned', { // 埋点:清掉了多少孤儿消息(线上可观测)    orphanedMessageCount: assistantMessages.length, // 埋点计数  })  assistantMessages.length = 0 // 清空失败流的全部状态——降级后的响应是全新对话  toolResults.length = 0 // 工具结果状态一并清空  toolUseBlocks.length = 0 // tool_use 块列表一并清空  needsFollowUp = false // 重置后续标记——降级后是全新对话  if (streamingToolExecutor) { // 若存在有工具在跑的执行器    streamingToolExecutor.discard() // 丢弃在途工具结果——防止旧 id 的孤儿 tool_result 泄漏出去    streamingToolExecutor = new StreamingToolExecutor( // 为降级流重建一个全新执行器      toolUseContext.options.tools, canUseTool, toolUseContext, // 用同样的三参数重建执行器    )  }}

为什么这样设计:tombstone(墓碑)是个很克制的方案——不是"回滚 UI",而是 yield 一条删除指令消息。因为 query() 是生成器、UI 是单向消费流,没有"撤回上一条"的通道;但"追加一条删除标记"永远可行。transcript 落盘时遇到 tombstone 就把对应 uuid 的消息剪掉,resume 时历史就是干净的。

streamingToolExecutor.discard() 解决的是另一个脏状态:降级前可能已经有工具在跑(比如 Bash 命令执行到一半)。这些工具产出的 tool_result 带着旧对话的 tool_use_id,如果降级后还 yield 出去,API 会看到"一个从未出现在新历史里的 tool_use 被引用了"——直接 400。所以整个执行器推倒重建。

源码注释里还有一句值得注意的自白:"We won't use the tool_calls from the first attempt — We could.. but then we'd have to merge assistant messages with different ids and double up on full the tool_results"。团队明确考虑过"保留第一次尝试的工具调用",但合并不同 id 的 assistant 消息太脏,放弃了。宁可重跑工具,也不做消息缝合——这是流式系统里很典型的取舍。

三、闸 1:backfill 克隆与 prompt cache 保护

每条 assistant 消息 yield 之前,还有一道精细的克隆逻辑。某些工具(典型是文件类)希望对外展示"展开后的输入"——比如把相对路径补成绝对路径,方便 SDK 消费者和 hooks 看到完整信息。这个动作叫 backfillObservableInput。

📄 src/query.ts (第 742-786 行)

let yieldMessage: typeof message = message // 默认原样发出if (message.type === 'assistant') { // 只有 assistant 消息需要 backfill 处理  let clonedContent: typeof message.message.content | undefined // content 克隆体——只有 backfill 真的加了字段才创建  for (let i = 0; i < message.message.content.length; i++) { // 逐个遍历 content block    const block = message.message.content[i]! // 当前块(非空断言)    if (block.type === 'tool_use' && typeof block.input === 'object' && block.input !== null) { // 只处理 input 是对象的 tool_use 块      const tool = findToolByName(toolUseContext.options.tools, block.name) // 按名字找工具定义      if (tool?.backfillObservableInput) { // 部分工具声明了"回填"钩子——为可观测性补派生字段        const originalInput = block.input as Record<string, unknown> // input 按通用对象处理        const inputCopy = { ...originalInput } // 先浅拷贝——绝不改动原始消息        tool.backfillObservableInput(inputCopy) // 例如文件工具把相对路径展开成绝对路径        const addedFields = Object.keys(inputCopy).some(k => !(k in originalInput)) // 只统计"新增"的字段        if (addedFields) { // 如果只是覆盖已有字段就不克隆——那会改变序列化 transcript,破坏 resume 时的 VCR fixture hash          clonedContent ??= [...message.message.content] // 首次需要时才惰性创建克隆数组          clonedContent[i] = { ...block, input: inputCopy } // 只替换这一个块为回填版        }      }    }  }  if (clonedContent) { // 只有真克隆了才发克隆体——原始消息保持字节不变,继续流回 API(保护 prompt cache)    yieldMessage = { ...message, message: { ...message.message, content: clonedContent } } // 两层浅拷贝构造克隆体——原对象保持不动  }}

为什么这样设计:这段代码的精髓在注释里写得很直白:原始 message 之后还要 push 进 assistantMessages、流回 API。Anthropic 的 prompt caching 是字节级匹配——历史消息任何一个字符变了,缓存就 miss,下一轮请求又贵又慢。所以"对外展示用克隆体,对内回流用原件"。

更微妙的是 addedFields 判断:backfill 分两种——新增字段(SDK 流需要、API 不关心)和覆盖已有字段(比如把 file_path 从相对改成绝对)。后者会改变 transcript 的序列化结果,而 Claude Code 内部有 VCR fixture 机制(录制/回放 API 交互做测试),resume 时 hash 对不上就全挂。所以规则是:只新增才克隆,纯覆盖一律不动。一个 if 背后是三条约束(prompt cache、VCR hash、SDK 展示)的交集。

四、闸 2:可恢复错误的扣留(withhold)

第三道闸处理一类特殊消息:API 返回的错误,但客户端其实有救。prompt-too-long(上下文超长)、max_output_tokens(输出被截断)、media size error(图片太大)——这三种错误如果立刻 yield 给 UI/SDK,用户看到的就是报错;但实际上 Claude Code 手里还有牌可打:context collapse、reactive compact、truncation retry。

📄 src/query.ts (第 799-825 行)

let withheld = false // 这条消息是否是"可恢复错误"、要不要先扣住不发if (feature('CONTEXT_COLLAPSE')) { // feature() 只能出现在 if/三元里——bun:bundle tree-shaking 的硬约束  if (contextCollapse?.isWithheldPromptTooLong(message, isPromptTooLongMessage, querySource)) { // 判断这条消息是否是 collapse 能救的 prompt-too-long    withheld = true // context-collapse 路径:先扣住 prompt-too-long,尝试折叠上下文后恢复  }}if (reactiveCompact?.isWithheldPromptTooLong(message)) { // reactive compact 路径同理  withheld = true // reactive-compact 路径:与上面独立——任一子系统扣留即生效(互不依赖)}if (mediaRecoveryEnabled && reactiveCompact?.isWithheldMediaSizeError(message)) { // 媒体尺寸错误且恢复功能开启  withheld = true // 媒体尺寸错误:先扣住,尝试剥离/压缩图片后恢复}if (isWithheldMaxOutputTokens(message)) { // 输出截断错误  withheld = true // max_output_tokens:先扣住,进入截断重试循环(最多 MAX_OUTPUT_TOKENS_RECOVERY_LIMIT=3 次)}if (!withheld) { // 没有任何子系统扣留,才真正发出  yield yieldMessage // 所有恢复路径都不可用,才真正发给 UI/SDK}

为什么这样设计:isWithheldMaxOutputTokens 的文档注释(第 166-174 行)把动机说透了:"Yielding early leaks an intermediate error to SDK consumers (e.g. cowork/desktop) that terminate the session on any error field — the recovery loop keeps running but nobody is listening."——SDK 消费者(Claude Desktop、cowork 这类宿主)看到任何 error 字段就直接终止会话。如果客户端先 yield 错误再尝试恢复,宿主已经挂了,恢复白做。所以必须"先救、救不活才报"。

注意四个判断是并列的 if而不是 else-if:context collapse 和 reactive compact 是两个独立子系统,注释明确说 "Either subsystem's withhold is sufficient — they're independent so turning one off doesn't break the other's recovery path"。任何一个开着都能接住错误,关掉另一个不影响恢复链路——这是典型的防御性分层。

还有一个工程细节:feature('CONTEXT_COLLAPSE') 必须直接写在 if 条件里。因为 bun:bundle 的 tree-shaking 只认这种静态可分析的形式——如果写成 const enabled = feature(...) 再判断,外部构建版本可能无法把整段代码连同字符串一起摇掉(这些是 Anthropic 内部实验功能,不能泄漏到发布产物里)。

五、三套恢复机制对照

机制
触发条件
动作
模型降级
 FallbackTriggeredError
529 过载连续 ≥3 次,且配置了 fallbackModel
换备用模型、清失败流状态(tombstone + 重建执行器)、整请求重放
错误扣留
 withhold
prompt-too-long / max_output_tokens / 媒体尺寸错误
先扣住不发 UI,尝试 collapse/compact/截断恢复;救不活才 yield 报错
指数退避重试
 withRetry
429 / 5xx / 网络错误(可重试类)
按 Retry-After 或指数退避 sleep,同参数重发同一请求

三套机制的分工很清晰:withRetry 管"同一个请求再试一次"(网络/限流层),fallback 管"换个模型重来"(容量层),withhold 管"先别报错,我自己能修"(上下文层)。它们互不替代——529 重试 3 次失败才升级成 fallback;prompt-too-long 走 withhold 而不是退避(退避对参数错误毫无意义)。

六、模型降级路径:换模型 + 剥签名 + 重放

withRetry 在连续 529 达到阈值后抛出一个特殊错误 FallbackTriggeredError(第 160-167 行,携带 originalModel 和 fallbackModel)。它不是"失败",而是一个控制流信号——被 query.ts 的 catch 精确捕获:

📄 src/query.ts (第 893-951 行,节选)

} catch (innerError) { // 单次尝试的异常:先判断是不是降级信号  if (innerError instanceof FallbackTriggeredError && fallbackModel) { // withRetry 抛出"降级"信号,且确实配置了备用模型    currentModel = fallbackModel // 换上备用模型    attemptWithFallback = true   // 让外层 while 循环再进一次——整请求重放    yield* yieldMissingToolResultBlocks(assistantMessages, 'Model fallback triggered') // 给已发出的 tool_use 补上 tool_result,保持配对完整    assistantMessages.length = 0 // 清空失败尝试的全部状态——重试是全新对话    toolResults.length = 0 // 工具结果状态一并清空    toolUseBlocks.length = 0 // tool_use 块列表一并清空    needsFollowUp = false // 重置后续标记——降级后是全新对话    if (streamingToolExecutor) { // 若存在有工具在跑的执行器      streamingToolExecutor.discard() // 丢弃失败尝试的在途结果(旧 id 不能泄漏进新历史)      streamingToolExecutor = new StreamingToolExecutor(toolUseContext.options.tools, canUseTool, toolUseContext) // 为降级流重建全新执行器    }    toolUseContext.options.mainLoopModel = fallbackModel // 同步更新上下文里的主循环模型(影响 token 预算等计算)    if (process.env.USER_TYPE === 'ant') { // 仅内部构建:降级重放前必须剥签名      messagesForQuery = stripSignatureBlocks(messagesForQuery) // thinking 签名是绑定模型的——重放到另一个模型会 400,先剥掉    }    logEvent('tengu_model_fallback_triggered', { original_model: ..., fallback_model: ... }) // 埋点:降级事件全量可观测    yield createSystemMessage( // 告知用户发生了降级(warning 级——不开 verbose 也能看到)      `Switched to ${renderModelName(innerError.fallbackModel)} due to high demand for ${renderModelName(innerError.originalModel)}`, 'warning', // 通知文案:“X 高负载,已切换到 Y”    )    continue // 跳回 while(attemptWithFallback),用新模型重新发整个请求  }  throw innerError // 非降级错误:抛给外层 catch 走通用错误路径}

为什么这样设计:这段代码里最容易被忽略的是 stripSignatureBlocks。extended thinking 的 block 带一个加密签名,签名和模型绑定——把 A 模型的 protected-thinking block 重放给 B 模型(注释举例:capybara → opus)会直接 400。所以降级前必须把历史里的签名块剥掉,让备用模型拿到"干净的历史"。这是多模型系统里很隐蔽的兼容性问题。

另一个细节:降级时 yield 的是 'warning' 级 system message 而不是 error——因为对用户来说这不是失败,是"服务在高峰期自动切了个更快的模型"。错误语义和通知级别分离,避免用户恐慌。

注意降级路径里没有 sleep——529 的退避已经在 withRetry 内部消化完了(每次 529 都按 Retry-After/指数退避等过),走到这里说明"等了 3 轮还是过载",继续等不如换模型。这是"重试预算用尽 → 升级策略"的经典模式。

七、withRetry:一个会 yield 心跳的重试生成器

现在看 withRetry 本体(src/services/api/withRetry.ts,822 行)。它的设计很特别:不是返回 Promise,而是 AsyncGenerator——因为重试等待期间需要持续向宿主 yield "api_retry" 心跳消息,否则长会话会被判为空闲。

📄 src/services/api/withRetry.ts (第 170-253 行,节选)

export async function* withRetry<T>( // 泛型 T = operation 的返回类型;生成器形态才能边重试边 yield 心跳  getClient: () => Promise<Anthropic>, // API client 工厂——认证失败后可以重建  operation: (client: Anthropic, attempt: number, context: RetryContext) => Promise<T>, // 真正的请求函数,每次尝试调一次  options: RetryOptions, // 重试选项(maxRetries / signal / querySource 等)): AsyncGenerator<SystemAPIErrorMessage, T> { // 返回类型是生成器——重试等待期间能持续 yield 心跳  const maxRetries = getMaxRetries(options) // 最大重试次数(按 querySource 等区分)  let consecutive529Errors = options.initialConsecutive529Errors ?? 0 // 连续 529(过载)计数器  let lastError: unknown // 记住上轮错误——决定本轮要不要重建 client / 刷新 token  let persistentAttempt = 0 // persistent 模式的独立计数(外层 attempt 会被钳制,不增长)  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) { // 共 maxRetries+1 次机会(首次 + 重试)    if (options.signal?.aborted) throw new APIUserAbortError() // 先查中断——用户已按 Esc 就不浪费下一次请求    const wasFastModeActive = isFastModeEnabled() ? retryContext.fastMode && !isFastModeCooldown() : false // 尝试前快照 fast mode 状态(降级可能中途改变它)    try { // 一次完整尝试:前置检查 + 发请求      const isStaleConnection = isStaleConnectionError(lastError) // ECONNRESET/EPIPE:keep-alive 连接已死      if (isStaleConnection && getFeatureValue_CACHED_MAY_BE_STALE('tengu_disable_keepalive_on_econnreset', false)) { // 死连接且对应 feature flag 打开        disableKeepAlive() // 关掉连接池强制新建连接——否则重试还会拿到同一根死 socket      }      if (client === null || (lastError instanceof APIError && lastError.status === 401) || isOAuthTokenRevokedError(lastError) || isStaleConnection) { // 首次、或认证/连接失败 → 重建 client        if ((lastError instanceof APIError && lastError.status === 401) || isOAuthTokenRevokedError(lastError)) { // token 过期或被吊销:先刷新再重建 client          const failedAccessToken = getClaudeAIOAuthTokens()?.accessToken // 取出失效的 token          if (failedAccessToken) await handleOAuth401Error(failedAccessToken) // 先强制刷新 OAuth token,再用新凭据建 client        }        client = await getClient() // 用新凭据建一个全新 client      }      return await operation(client, attempt, retryContext) // 成功:直接 return 结束生成器——不需要再重试    } catch (error) { /* 错误分类 + 退避,见下 */ }

为什么这样设计:这个循环把"重试前检查"做成了三件事的组合拳:查中断(abort 优先于一切,省一次请求)、查连接健康(ECONNRESET 说明 keep-alive 池里是死连接,不关池子重试等于白试)、查凭据有效性(401/token revoked 时先刷新 OAuth 再重建 client)。三者都基于 lastError——错误不是被吞掉,而是驱动下一轮的行为。这是"错误即状态"的设计。

还有一个容易被忽略的分支:fast mode(快速模式)遇到 429/529 时的处理(第 267-304 行)。核心逻辑是用 prompt cache 保命:

📄 src/services/api/withRetry.ts (第 267-304 行,节选)

if (wasFastModeActive && !isPersistentRetryEnabled() && error instanceof APIError && (error.status === 429 || is529Error(error))) { // fast mode 撞限流/过载 → 决定保 fast 还是降级  const overageReason = error.headers?.get('anthropic-ratelimit-unified-overage-disabled-reason') // 服务端明确说"没有额外额度"  if (overageReason !== null && overageReason !== undefined) { // 服务端明确返回了“无额外额度”    handleFastModeOverageRejection(overageReason) // 记录拒绝原因(供 UI/埋点)    retryContext.fastMode = false // 永久关闭 fast mode——继续试只会一直撞墙    continue // 立即以标准速度重试  }  const retryAfterMs = getRetryAfterMs(error) // 从响应头解析 Retry-After(毫秒)  if (retryAfterMs !== null && retryAfterMs < SHORT_RETRY_THRESHOLD_MS) { // 短等待:值得为缓存保住 fast mode    await sleep(retryAfterMs, options.signal, { abortError }) // 短等待:保持 fast mode 重试——模型名不变,prompt cache 不失效    continue // 回到循环顶部再试(仍是 fast mode)  }  const cooldownMs = Math.max(retryAfterMs ?? DEFAULT_FAST_MODE_FALLBACK_HOLD_MS, MIN_COOLDOWN_MS) // 长等待:进冷却期(切标准速度),设下限防止来回抖动  triggerFastModeCooldown(Date.now() + cooldownMs, is529Error(error) ? 'overloaded' : 'rate_limit') // 进入冷却期并记录原因(过载/限流)  if (isFastModeEnabled()) retryContext.fastMode = false // 本次放弃 fast mode——下一轮走标准速度  continue // 回到循环顶部再试(已是标准速度)}

为什么这样设计:fast mode 和标准模式用的是不同的模型名。prompt cache 按前缀字节匹配——换模型名 = 缓存全 miss = 重试时重新付全价 token + 更慢。所以决策规则是:Retry-After 短(说明马上就好)→ 咬牙等、保住 fast mode 和缓存;Retry-After 长 → 切标准速度,但设 MIN_COOLDOWN_MS 下限防止"刚冷却完又撞限流"的抖动。这是延迟、成本、缓存命中率三者的显式权衡,而且全部参数化可灰度(feature flag + growthbook)。

529 → fallback 的升级路径(第 316-364 行)则是另一条线:

📄 src/services/api/withRetry.ts (第 316-364 行,节选)

if (is529Error(error) && !shouldRetry529(options.querySource)) { // 529 且该来源不允许重试  logEvent('tengu_api_529_background_dropped', {...}) // 后台任务:529 直接丢弃——容量级联时不做重试放大,用户也看不到这些失败  throw new CannotRetryError(error, retryContext) // 立即放弃——不参与容量级联}if (is529Error(error) && (process.env.FALLBACK_FOR_ALL_PRIMARY_MODELS || (!isClaudeAISubscriber() && isNonCustomOpusModel(options.model)))) { // 只统计"有降级路径可走"的模型的 529  consecutive529Errors++ // 连续过载计数  if (consecutive529Errors >= MAX_529_RETRIES) { // 连续 3 次(MAX_529_RETRIES=3)→ 触发模型降级    if (options.fallbackModel) { // 配置了备用模型:升级为降级路径      logEvent('tengu_api_opus_fallback_triggered', {...}) // 埋点:降级事件(模型对 + provider)      throw new FallbackTriggeredError(options.model, options.fallbackModel) // 特殊错误:被 query.ts 捕获后换模型重放(第六节)    }    if (process.env.USER_TYPE === 'external' && !process.env.IS_SANDBOX && !isPersistentRetryEnabled()) { // 外部用户、非沙箱、非 persistent 模式      throw new CannotRetryError(new Error(REPEATED_529_ERROR_MESSAGE), retryContext) // 没有备用模型:直接给用户"过载"报错,不再空转    }  }}

为什么这样设计:两个细节值得注意。其一,shouldRetry529(querySource):交互式会话的 529 要重试(用户在等),后台任务(摘要、记忆抽取之类)的 529 直接丢弃——注释说得很直白 "no retry amplification during capacity cascades"。容量级联时,每个客户端的重试都会加剧过载;后台任务价值低,主动退出是对全局友好的行为。

其二,529 计数有条件门槛:只有"非 Claude AI 订阅用户 + 非自定义 Opus 模型"才计入(或显式打开 FALLBACK_FOR_ALL_PRIMARY_MODELS)。因为 fallback 的目标是"Opus 过载时切到 Sonnet"——如果你本来就在用 Sonnet,529 重试就够了,不需要降级逻辑介入。错误处理策略是按用户身份和模型分层下发的。

八、退避公式与心跳 yield

常量
值
作用
BASE_DELAY_MS
500ms
指数退避基数:500 × 2^(n-1),上限 32s
MAX_529_RETRIES
3
连续过载达到此数触发模型降级
FLOOR_OUTPUT_TOKENS
3000
上下文溢出自愈后 max_tokens 的下限
HEARTBEAT_INTERVAL_MS
30s
persistent 模式心跳分片大小(防宿主判空闲)
PERSISTENT_MAX_BACKOFF_MS
5min
persistent 重试的退避上限
PERSISTENT_RESET_CAP_MS
6hr
绝对等待上限(防病态 Retry-After 头无限等)

📄 src/services/api/withRetry.ts (第 530-548 行)

export function getRetryDelay(attempt: number, retryAfterHeader?: string | null, maxDelayMs = 32000): number { // 计算本次尝试的退避时长  if (retryAfterHeader) { // 服务端给了 Retry-After 头    const seconds = parseInt(retryAfterHeader, 10) // 服务端 Retry-After 优先——它是指令不是建议(源码注释:honoring it is correct)    if (!isNaN(seconds)) return seconds * 1000 // 解析成功:直接用服务端的值  }  const baseDelay = Math.min(BASE_DELAY_MS * Math.pow(2, attempt - 1), maxDelayMs) // 指数退避:500ms × 2^(n-1),封顶 32s——避免重试间隔无限拉长  const jitter = Math.random() * 0.25 * baseDelay // 加最多 25% 随机抖动——防止大量客户端同一时刻集体重试(惊群)打爆服务端  return baseDelay + jitter // 退避 = 指数基数 + 随机抖动}

为什么这样设计:教科书级的退避实现,三个要素齐全:指数增长(给服务端恢复时间)、硬上限(32s——普通重试不该让用户等几分钟)、抖动(25% 随机量打散同步重试)。Retry-After 优先于公式是正确做法:限流窗口是服务端的真实状态,客户端猜不如听。

persistent 模式(长会话持续重试)的等待则被切成 30s 的心跳片:

📄 src/services/api/withRetry.ts (第 477-516 行,节选)

if (persistent) { // persistent 模式:一直重试到成功或中断——面向长会话  if (delayMs > 60_000) logEvent('tengu_api_persistent_retry_wait', {...}) // 等待超 1 分钟额外埋点(线上可观测)  let remaining = delayMs // 待等待的总时长(将被切片)  while (remaining > 0) { // 把长 sleep 切成小片——每片 yield 一次心跳    if (options.signal?.aborted) throw new APIUserAbortError() // 每片都查中断——不能让用户按了 Esc 还要睡完整个退避    if (error instanceof APIError) { // 只对真正的 API 错误做进一步处理      yield createSystemAPIErrorMessage(error, remaining, reportedAttempt, maxRetries) // 心跳:宿主看到 stdout 有活动,不会把会话标记为 idle    }    const chunk = Math.min(remaining, HEARTBEAT_INTERVAL_MS) // 30s 一片(HEARTBEAT_INTERVAL_MS=30_000)    await sleep(chunk, options.signal, { abortError }) // 睡一片;期间被中断则立即抛出    remaining -= chunk // 剩余时长减去已睡部分  }  if (attempt >= maxRetries) attempt = maxRetries // 钳制:persistent 模式下 for 循环永不结束——退避用独立的 persistentAttempt 计数,持续增长到 5min 上限} else { // 非 persistent:单次等待  if (error instanceof APIError) yield createSystemAPIErrorMessage(error, delayMs, attempt, maxRetries) // 非 persistent:睡之前发一次心跳  await sleep(delayMs, options.signal, { abortError }) // 完整退避睡眠(可被中断打断)}

为什么这样设计:"把 sleep 切片 + 每片 yield"是个很务实的 hack。宿主进程(SDK、CI runner)通常靠 stdout 活动判断会话是否存活——一个静默睡 5 分钟的子进程会被判死杀掉。切成 30s 一片、每片吐一条 {type:'system', subtype:'api_retry'},既保活了进程,又让用户在终端里看到"正在重试,还剩 Xms"的真实进度。生成器形态在这里不是炫技,是心跳通道的物理载体——Promise 做不到边等边说话。

attempt = maxRetries 这行钳制配合 persistentAttempt 独立计数,实现了"for 循环永不退出但退避持续升级":普通模式 attempt 增长到上限就抛 CannotRetryError;persistent 模式把 attempt 钉死、让 persistentAttempt 自由增长(5min 封顶)。两个计数器各管一件事,互不污染。

九、上下文溢出自愈:从报错文本里算出新参数

withRetry 里最"脏"也最聪明的一段:API 返回 400 "input length and max_tokens exceed context limit"——这不是限流,是参数算错了(输入 + 输出预算超过了上下文窗口)。退避重试毫无意义,正确动作是缩小 max_tokens 重发。而新值从哪来?从错误消息的文本里正则解析:

📄 src/services/api/withRetry.ts (第 388-426 行,节选)

if (error instanceof APIError) { // 只对真正的 API 错误做进一步处理  const overflowData = parseMaxTokensContextOverflowError(error) // 正则解析错误消息里的 "input length and max_tokens exceed context limit: X + Y > Z"  if (overflowData) { // 命中 → 这是参数问题不是限流——直接重发,不 sleep    const { inputTokens, contextLimit } = overflowData // 解构解析出的数字(maxTokens 此处用不到)    const safetyBuffer = 1000 // 留 1k token 安全余量(服务端计数和客户端估算可能有偏差)    const availableContext = Math.max(0, contextLimit - inputTokens - safetyBuffer) // 输出还能用的空间    if (availableContext < FLOOR_OUTPUT_TOKENS) { // 连 3000(FLOOR_OUTPUT_TOKENS)都凑不出——重试没意义,直接抛      logError(new Error(`availableContext ${availableContext} is less than FLOOR_OUTPUT_TOKENS ${FLOOR_OUTPUT_TOKENS}`)) // 记录这种异常状态便于排查      throw error // 放弃自愈:原样抛出错误    }    const minRequired = (retryContext.thinkingConfig.type === 'enabled' ? retryContext.thinkingConfig.budgetTokens : 0) + 1 // thinking 预算 + 至少 1 个输出 token(不满足 API 会再报 400)    const adjustedMaxTokens = Math.max(FLOOR_OUTPUT_TOKENS, availableContext, minRequired) // 三者取最大:下限 / 剩余空间 / thinking 需求    retryContext.maxTokensOverride = adjustedMaxTokens // 下一次尝试用这个缩小后的 max_tokens——无人工干预的自愈    logEvent('tengu_max_tokens_context_overflow_adjustment', { inputTokens, contextLimit, adjustedMaxTokens, attempt }) // 埋点:参数调整前后全记录(线上分析用)    continue // 立即重试(continue 跳过退避 sleep)  }}

为什么这样设计:parseMaxTokensContextOverflowError(第 550-595 行)用正则 /input length and `max_tokens` exceed context limit: (\d+) \+ (\d+) > (\d+)/ 从错误文本里抠出三个数。解析失败就返回 undefined、走普通重试——宁可保守也不猜参数。

新 max_tokens 的公式 max(3000, contextLimit - inputTokens - 1000, thinkingBudget + 1) 每一项都有存在理由:3000 是"输出太短等于没回答"的体验下限;减 1000 是因为服务端 token 计数和客户端估算有偏差,不留余量会二次撞墙;thinking budget + 1 是因为 extended thinking 的预算必须被 max_tokens 覆盖。三个约束取最大,保证一次修到位。

源码注释还留了个时代痕迹:"With extended-context-window beta, this 400 error should not occur... Keeping for backward compatibility."——新 API 会改用 model_context_window_exceeded stop_reason,这个正则解析是为旧行为保留的兼容层。读源码时看到"看起来过度设计"的代码,先查注释里的兼容性说明。

十、中断善后:tool_use / tool_result 配对不能断

最后一类异常路径是用户主动按 Esc。API 有个硬约束:每个 tool_use block 必须有配对的 tool_result,否则下一轮请求直接 400。中断发生时可能正好有工具在跑、结果没回来——这时必须"伪造"一个错误 result 把配对补上:

📄 src/query.ts (第 1015-1052 行,节选)

if (toolUseContext.abortController.signal.aborted) { // 用户按了 Esc——中断必须最先处理,优先级高于一切后续逻辑  if (streamingToolExecutor) { // 若存在有工具在跑的执行器    for await (const update of streamingToolExecutor.getRemainingResults()) { // 排空执行器:它会为排队中/执行中的工具生成合成 tool_result      if (update.message) yield update.message // 不消费的话,那些 tool_use 就缺配对——下一轮 API 请求直接 400    }  } else { // 非流式路径:没有执行器可排空    yield* yieldMissingToolResultBlocks(assistantMessages, 'Interrupted by user') // 非流式路径:自己补缺失的 tool_result  }  if (feature('CHICAGO_MCP') && !toolUseContext.agentId) { // computer-use 功能开启且是主线程(非子代理)    try { await cleanupComputerUseAfterTurn(toolUseContext) } catch {} // 仅主线程:中断时释放 computer-use 锁——与自然结束走同一套清理(失败静默,非关键路径)  }  if (toolUseContext.abortController.signal.reason !== 'interrupt') { // 区分“纯中断”与“提交式中断”    yield createUserInterruptionMessage({ toolUse: false }) // 发中断标记消息;submit-interrupt 跳过——后面排队的用户消息本身已提供上下文  }  return { reason: 'aborted_streaming' } // 返回 turn 结果:流式阶段被中止}

补配对的生成器本体(第 123-149 行):

📄 src/query.ts (第 123-149 行)

function* yieldMissingToolResultBlocks(assistantMessages: AssistantMessage[], errorMessage: string) { // 给所有"已发出但未应答"的 tool_use 补上 tool_result  for (const assistantMessage of assistantMessages) { // 遍历本轮所有 assistant 消息    const toolUseBlocks = assistantMessage.message.content.filter(content => content.type === 'tool_use') as ToolUseBlock[] // 抽出这条消息里的全部 tool_use 块    for (const toolUse of toolUseBlocks) { // 对每个未应答的 tool_use 补一条      yield createUserMessage({ // 合成一条 user 消息,携带错误 tool_result        content: [{ type: 'tool_result', content: errorMessage, is_error: true, tool_use_id: toolUse.id }], // id 必须与原 tool_use 一致——API 靠它配对        toolUseResult: errorMessage, // 错误文本同时挂在消息对象上(UI 展示用)        sourceToolAssistantUUID: assistantMessage.uuid, // 记录归属的 assistant 消息(transcript 重建用)      })    }  }}

为什么这样设计:注意 signal.reason !== 'interrupt' 这个判断——abort 分两种:纯中断(用户按 Esc,reason='interrupt')和提交式中断(用户在输入框里发了新消息打断当前轮)。后者不需要额外的 "[Request interrupted by user]" 标记,因为紧接着的用户消息本身就是上下文。这种对"为什么中断"的区分说明:中断不是单一事件,而是带语义的状态机。

还有一个容易忽略的细节(第 986-992 行):外层 catch 里 yield 真实错误消息前,注释专门解释——"Surface the real error instead of a misleading '[Request interrupted by user]' — this path is a model/runtime failure, not a user action. SDK consumers were seeing phantom interrupts on e.g. Node 18's missing Array.prototype.with(), masking the actual cause."——曾经有 bug 把运行时错误伪装成用户中断,SDK 消费者看到"phantom interrupt"完全摸不到真因(Node 18 缺 Array.prototype.with)。错误的语义必须精确:谁的责任就标谁的标签。

十一、数据流图:一条消息的完整旅程

流式事件循环(query.ts + withRetry.ts)

① 发请求:deps.callModel → withRetry 包裹 operation

attempt=1;先查 abort / 连接健康 / token 有效性,再真正发 HTTP。

▼

② 消费流:for await message,每条过三道闸

🔹 闸 0 fallback 检查:streamingFallbackOccured → tombstone 清场 + 重建执行器🔹 闸 1 backfill:克隆 tool_use input(原件字节不变,保 prompt cache)🔹 闸 2 withhold:可恢复错误先扣住,救不活才 yield

▼

③ 流结束 / 出错:三条分支

🔹 FallbackTriggeredError → 换模型 + stripSignatureBlocks + 整请求重放🔹 CannotRetryError → yieldMissingToolResultBlocks 补配对 + 发真实错误消息🔹 429/5xx → Retry-After / 指数退避 sleep(persistent 模式每 30s yield 心跳)后重试

▼

④ 中断:signal.aborted → 排空执行器

getRemainingResults() 为在途工具生成合成 tool_result,保证配对完整;reason≠'interrupt' 才发中断标记。

十二、本讲小结

这一讲的代码量不大,但密度极高——query.ts 的流式循环 + withRetry.ts 的重试引擎加起来不到 1200 行,却覆盖了生产级 agent 的全部异常面。几个可以带走的设计模式:

🔹 tombstone 模式:单向消息流里"撤回"的唯一办法是追加删除标记,而不是回滚状态。

🔹 克隆体/原件分离:对外展示可以加工,对内回流必须字节不变——prompt cache 是字节级匹配的。

🔹 错误即控制流信号:FallbackTriggeredError / CannotRetryError 不是"失败",是带语义的分支指令;lastError 驱动下一轮行为(重建 client、刷 token、关连接池)。

🔹 生成器 = 心跳通道:AsyncGenerator 形态让重试等待期间能持续 yield 进度,宿主不会判会话死亡——Promise 做不到这一点。

🔹 配对完整性是硬约束:任何异常路径(降级、报错、中断)退出前都必须保证 tool_use/tool_result 一一配对,否则下一轮 API 请求必挂。

🔹 分层重试预算:同参数退避(withRetry)→ 换模型重放(fallback)→ 自愈改参(overflow adjustment),每一层都有明确的升级条件和次数上限,后台任务还会主动放弃重试避免容量级联。

下一讲进入 services/api/claude.ts(3419 行)上段:请求体到底怎么组装、headers/auth 怎么挂、模型路由和 beta flags 在哪里生效——把"发出去的那条 HTTP 请求"彻底拆开。

📚 系列导航

← 第 5 讲:QueryEngine turn 状态机与工具编排

→ 第 7 讲:API 请求构造与模型路由

关注公众号「AI技术推荐官」获取更多源码解析内容

📌 每天 30 条,挑出真能用的 AI 东西

UnitAI 每天从 GitHub / Hacker News / Hugging Face 抓一遍 AI 热榜,还收录了 50+ 个上过榜的项目,能按分类、星级、上榜天数筛。免费看,不用注册。

长按识别二维码打开 · 或点左下角「阅读原文」

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料