夜雨聆风学习资料网

ARTICLE · 1374330

Claude Code 源码-SSE 流式解析与重试退避

Claude Code 源码-SSE 流式解析与重试退避

Claude Code 源码解析系列

第 8 讲:SSE 流式解析与重试退避

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

💡 本讲一句话:第 7 讲讲请求怎么"发"出去,这一讲讲响应以 SSE 流回来之后发生什么——以及它根本没来的时候。services/api/withRetry.ts(822 行)是重试引擎:指数退避+抖动、529 预算与模型降级、上下文溢出自愈、无人值守持久模式四条特殊路径;claude.ts 后半段是事件消费者:逐块拼装消息、90 秒看门狗杀挂死流。每一行都是"别浪费用户时间"和"别把过载的服务器打得更死"之间的权衡。

一、重试引擎骨架:为什么是一个 generator

先看四个常量,它们定义了整套重试策略的边界(withRetry.ts 第 52-55 行):

📄 src/services/api/withRetry.ts (第 52-55 行)

const DEFAULT_MAX_RETRIES = 10        // 默认最大重试次数:首次尝试之外最多再试 10 次const FLOOR_OUTPUT_TOKENS = 3000      // 输出 token 下限:上下文溢出自愈时 max_tokens 不得低于此值const MAX_529_RETRIES = 3             // 连续 529(过载)预算:达到后触发模型降级或放弃export const BASE_DELAY_MS = 500      // 指数退避基数:第 1 次重试等 500ms,之后逐次翻倍

为什么这样设计:四个常量把"重试多久、等多久、何时放弃"全部参数化——后面所有特殊路径(529 预算、溢出自愈、持久模式)都是在这些边界内做文章,而不是各写一套逻辑。

再看引擎本体 withRetry()(第 170-192 行)。注意它的签名——这是一个异步生成器,不是普通 async 函数:

📄 src/services/api/withRetry.ts (第 170-192 行)

export async function* withRetry<T>(   // 异步生成器:等待期间能 yield"重试中"心跳,最终 return T  getClient: () => Promise<Anthropic>, // client 工厂(惰性):首次尝试或鉴权失败后才调用  operation: (                          // 真正的请求函数:拿到 client、attempt 序号、重试上下文    client: Anthropic,                  // SDK 客户端实例    attempt: number,                    // 当前是第几次尝试(从 1 开始)    context: RetryContext,              // model / thinkingConfig / maxTokensOverride 等可变状态  ) => Promise<T>,                     // 返回业务结果(流式场景下是 SSE Stream)  options: RetryOptions,                // fallbackModel / signal / querySource 等配置): AsyncGenerator<SystemAPIErrorMessage, T> { // yield 系统消息给 UI,return 最终结果  const maxRetries = getMaxRetries(options)   // env CLAUDE_CODE_MAX_RETRIES 可覆盖,默认 10  let consecutive529Errors = options.initialConsecutive529Errors ?? 0 // 预置 529 计数:流式路径的 529 也计入同一预算  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) { // 总尝试次数 = 重试数+1,即首次+最多 10 次重试    if (options.signal?.aborted) {      // 每轮开头检查中止信号:用户按了 ESC 就立刻退出      throw new APIUserAbortError()     // 抛专用错误类型,上游能把它和网络错误区分开    }

为什么这样设计:generator 是这里最关键的架构选择。重试意味着要 sleep,而 sleep 期间 UI 需要知道"正在第 N 次重试、还要等多少秒"——普通 async 函数只能阻塞或抛错,生成器可以在每次等待前 yield 一条 SystemAPIErrorMessage(QueryEngine 会把它转成 stdout 上的 {type:'system', subtype:'api_retry'}),用户看到"Retrying in 3s (attempt 2/10)"而不是干等。另外注意 initialConsecutive529Errors:流式请求失败后降级到非流式时,会把已发生的 529 预置进计数器——保证"触发模型降级前总共允许几次 529"这个预算在两种模式下口径一致(源码注释明确说这是修 issue #1513)。

下表汇总本讲涉及的全部重试参数,后面逐节展开:

参数
值
作用
DEFAULT_MAX_RETRIES
10
普通模式最大重试次数(env 可覆盖)
BASE_DELAY_MS / maxDelayMs
500ms / 32s
指数退避基数与上限(+25% 抖动)
MAX_529_RETRIES
3
连续过载预算,达到后模型降级或放弃
FLOOR_OUTPUT_TOKENS
3000
溢出自愈时 max_tokens 下限
PERSISTENT_MAX_BACKOFF_MS
5min
持久模式退避上限(无限重试)
PERSISTENT_RESET_CAP_MS
6h
持久模式单次等待上限(防病态 header)
HEARTBEAT_INTERVAL_MS
30s
持久模式心跳分片间隔(防宿主判 idle)
STREAM_IDLE_TIMEOUT_MS
90s
流式看门狗:无 chunk 超时即 abort(默认关闭)

二、重试前的准备:client 刷新与连接池自愈

每次尝试真正发请求前,withRetry 会先判断"上一轮失败是不是身份/连接问题"——是的话必须重建 client,否则重试一百次也是同一个错(第 218-251 行):

📄 src/services/api/withRetry.ts (第 218-251 行)

const isStaleConnection = isStaleConnectionError(lastError) // ECONNRESET/EPIPE = keep-alive 池里的陈旧 socketif (isStaleConnection && getFeatureValue_CACHED_MAY_BE_STALE(  // 特性门控:远程可开关,出问题能回滚  'tengu_disable_keepalive_on_econnreset', false,             // 默认关闭——先观察再放量)) {  disableKeepAlive()                  // 关掉连接池复用,重试时强制新建 TCP/TLS 握手}if (client === null ||                // 首次尝试:还没有 client    (lastError instanceof APIError && lastError.status === 401) || // 401 = token 过期,刷新后重建    isOAuthTokenRevokedError(lastError) ||                          // 403 "token revoked":别的进程抢先刷了 token    isBedrockAuthError(lastError) ||                                // Bedrock 凭证错误(可能不是 APIError)    isVertexAuthError(lastError) ||                                 // Vertex 凭证刷新失败    isStaleConnection                // 陈旧连接:必须重建 client 才能生效) {  if ((lastError instanceof APIError && lastError.status === 401) || // 两类"token 失效"      isOAuthTokenRevokedError(lastError)) {                        // 都要先走 OAuth 刷新    const failedAccessToken = getClaudeAIOAuthTokens()?.accessToken // 拿到刚被服务端拒绝的那个 token    if (failedAccessToken) {      await handleOAuth401Error(failedAccessToken)  // 强制刷新:丢弃旧 token、换新 token    }  }  client = await getClient()         // 用新凭证重建 SDK client(其余情况直接复用缓存)}return await operation(client, attempt, retryContext) // 成功路径:返回结果,整个生成器结束

为什么这样设计:这段代码把"失败原因"分成两类处理:身份问题(401/403 revoked/云厂商凭证)——重试前必须先修好凭证,否则是无效重试;连接问题(ECONNRESET/EPIPE 是 keep-alive 池里死掉的 socket)——必须禁用复用、强制新握手。两个细节值得注意:其一,禁用 keep-alive 放在特性门控后面且默认关闭——这是"先灰度再全量"的典型做法,一个连接池行为变更影响面太大;其二,handleOAuth401Error 只在 401/revoked 时调用,普通网络错误不会触发 token 刷新——避免把网络抖动误判成凭证问题、白白消耗 refresh token。

三、该不该重试:shouldRetry() 决策表

catch 到错误后,第一道门是 shouldRetry(error)(第 696-787 行)。它不是简单的状态码白名单,而是一套带"身份感知"的决策链。先看最微妙的一段——529 嗅探与服务端指令(第 719-751 行):

📄 src/services/api/withRetry.ts (第 719-751 行)

// Check for overloaded errors first by examining the message contentif (error.message?.includes('"type":"overloaded_error"')) { // SDK 有时在流式场景传不出 529 状态码,只能从错误文本嗅探  return true                                             // 判定为可重试:这是服务端过载,不是我们的错}const shouldRetryHeader = error.headers?.get('x-should-retry') // 非标准头:服务端明确告诉我们该不该重试if (shouldRetryHeader === 'true' &&                        // 服务端说"可以重试"    (!isClaudeAISubscriber() || isEnterpriseSubscriber())) // 但 Max/Pro 订阅用户除外:额度重置要等几小时,重试只是白等) {  return true                                             // API key / 企业 PAYG 用户:听服务端的}if (shouldRetryHeader === 'false') {                       // 服务端明确禁止重试  const is5xxError = error.status !== undefined && error.status >= 500 // 只有内部用户对 5xx 能破例  if (!(process.env.USER_TYPE === 'ant' && is5xxError)) { // 外部用户必须服从服务端裁决    return false                                          // 直接放弃,不进入退避逻辑  }}

为什么这样设计:三个点。其一,"type":"overloaded_error" 字符串嗅探是典型的"防御 SDK 缺陷"——源码注释直说"The SDK sometimes fails to properly pass the 529 status code during streaming":流式请求中错误发生在 body 阶段时状态码可能丢失,只能靠报文内容兜底。其二,x-should-retry 是 Anthropic 私有头(非 HTTP 标准),服务端用它表达"这次失败重试也没用/要等很久"——客户端默认服从,但给订阅用户开了后门:Max/Pro 的额度窗口按小时计,服务端说"可以重试"实际意思是"几小时后",对交互式 CLI 来说不如直接报错让用户知道。其三,内部用户(ant)对 5xx 无视 false——生产环境排障时宁可多打几次请求也要拿到结果。

再看状态码部分(第 753-786 行),这是决策链的兜底:

📄 src/services/api/withRetry.ts (第 753-786 行)

if (error instanceof APIConnectionError) {   // 网络层错误(DNS/TLS/断连):恒可重试  return true                                // 连接问题与请求内容无关,重发一定有意义}if (!error.status) return false              // 无状态码且不是连接错误:未知情况,不赌if (error.status === 408) return true        // Request Timeout:服务端没处理完,安全可重发if (error.status === 409) return true        // Lock Timeout:瞬时资源竞争if (error.status === 429) {                  // Rate Limit:分人群处理  return !isClaudeAISubscriber() || isEnterpriseSubscriber() // 订阅用户额度按窗口计,重试=白等;企业 PAYG 可以试}if (error.status === 401) {                  // 鉴权失败:清 key 缓存后允许再试一次  clearApiKeyHelperCache()                   // 旧 key 可能已被其他进程轮换(配合第二节的刷新逻辑)  return true                                // 给"凭证已更新"一个生效的机会}if (isOAuthTokenRevokedError(error)) {       // "token revoked":走与 401 相同的刷新路径  return true                                // 刷新后重试,而不是直接失败}if (error.status && error.status >= 500) return true // 所有服务端错误视为瞬时故障,值得重试return false                                  // 其余 4xx(400/403 等):请求本身有问题,重试无意义

为什么这样设计:决策顺序本身就是优先级:连接错误 > 状态码白名单 > 默认拒绝。408/409 被单独列出是因为它们语义上"服务端没执行",重发无副作用;而 425、413 这类不在表里的 4xx 一律不重试——对 CLI 来说,一次明确的失败比十次无效的重试更尊重用户时间。注意 401 分支里顺手调了 clearApiKeyHelperCache():错误处理与状态清理耦合在同一处,避免"清了缓存但没重试"或"重试了但用的还是旧 key"的时序漏洞。

四、等多久:指数退避 + 抖动 + 服务端指令

决定重试后,延迟由 getRetryDelay() 计算(第 530-548 行)——教科书式的"指数退避 + 抖动",但有两个工程化细节:

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

export function getRetryDelay(  attempt: number,                            // 当前尝试序号(从 1 开始)  retryAfterHeader?: string | null,           // 服务端 Retry-After 头(单位秒),如有  maxDelayMs = 32000,                         // 退避上限:默认 32s;持久模式会传 5min): number {  if (retryAfterHeader) {                     // 服务端给了明确等待时间    const seconds = parseInt(retryAfterHeader, 10)    if (!isNaN(seconds)) {      return seconds * 1000                   // 服务端指令优先:它比客户端更清楚自己的容量恢复时间    }  }  const baseDelay = Math.min(                 // 指数退避主体    BASE_DELAY_MS * Math.pow(2, attempt - 1), // 500ms × 2^(n-1):第 1 次 0.5s、第 2 次 1s、第 3 次 2s……    maxDelayMs,                               // 封顶,避免后期等待无限增长  )  const jitter = Math.random() * 0.25 * baseDelay // 加最多 25% 随机抖动:打散重试时刻  return baseDelay + jitter                   // 最终延迟 = 退避值 + 抖动

为什么这样设计:抖动的存在是为了防惊群(thundering herd):过载恢复瞬间,成千上万个客户端如果都在同一时刻醒来重试,会把刚恢复的容量再次打穿。25% 的正向抖动让重试时刻在 [base, 1.25×base] 区间内散开。而 Retry-After 优先于本地退避——服务端知道自己什么时候能处理请求,客户端猜不如听。注意 maxDelayMs 是参数:普通模式传默认 32s(交互式场景不能等太久),持久模式传 5min(无人值守可以慢慢等)。

还有一个更聪明的等待策略——窗口型额度直接睡到重置时刻(第 814-822 行):

📄 src/services/api/withRetry.ts (第 814-822 行)

function getRateLimitResetDelayMs(error: APIError): number | null { // 窗口型额度(如 5hr Max/Pro)的响应头带重置时间戳  const resetHeader = error.headers?.get?.('anthropic-ratelimit-unified-reset') // Unix 秒:额度何时恢复  if (!resetHeader) return null                          // 没有重置时间:退回普通退避逻辑  const delayMs = Number(resetHeader) * 1000 - Date.now() // 换算成"还需等待的毫秒数"  if (delayMs <= 0) return null                          // 已过期:无需等待,立即重试  return Math.min(delayMs, PERSISTENT_RESET_CAP_MS)      // 封顶 6h:防病态 header 让客户端无限期挂起

为什么这样设计:源码注释说得很直白:"Wait until reset rather than polling every 5 min uselessly"——Max/Pro 的 5 小时窗口额度,按普通退避每 5 分钟探一次要探几十次全失败;直接睡到重置时刻只试一次就成功。这是"客户端理解服务端配额模型"的例子:重试策略不是通用算法,而是对具体业务(订阅制额度)的适配。

五、三条特殊路径:529 预算、溢出自愈、持久模式

5.1 背景任务在过载时主动让路

529(overloaded)的处理首先按"谁在等结果"分流。非前台来源(摘要、标题生成、建议、分类器)直接放弃,不进入重试(第 316-324 行):

📄 src/services/api/withRetry.ts (第 316-324 行)

// Non-foreground sources bail immediately on 529 — no retry amplificationif (is529Error(error) && !shouldRetry529(options.querySource)) { // 529 + 非前台来源(querySource 不在白名单里)  logEvent('tengu_api_529_background_dropped', {...})            // 埋点:记录哪个后台任务被丢弃,便于评估影响面  throw new CannotRetryError(error, retryContext)                 // 立即放弃:容量级联期间每次重试都是 3-10× 网关放大,而用户根本看不到这些失败

为什么这样设计:shouldRetry529()(第 84-89 行)维护一个 FOREGROUND_529_RETRY_SOURCES 白名单——repl 主线程、SDK、agent、compact、安全分类器等"用户在等结果"的来源才允许重试。注释点破了核心权衡:容量级联(capacity cascade)期间,每个后台任务的重试都会放大网关压力 3-10 倍,而这些失败用户根本看不见。主动丢弃不可见的失败是保护全局容量的手段——这是把"重试"从纯客户端行为升级成了系统级资源调度。

5.2 连续 529:预算耗尽后模型降级

📄 src/services/api/withRetry.ts (第 326-360 行)

if (is529Error(error) &&                      // 本次是 529 过载错误    (process.env.FALLBACK_FOR_ALL_PRIMARY_MODELS ||   // 或:所有主模型都参与降级(实验开关)      (!isClaudeAISubscriber() && isNonCustomOpusModel(options.model)))) // 否则仅"非订阅 + Opus 主线模型"符合资格) {  consecutive529Errors++                      // 连续计数器 +1(本次调用内跨尝试累计,成功即结束)  if (consecutive529Errors >= MAX_529_RETRIES) { // 连续 3 次过载:该模型容量确实打满了    if (options.fallbackModel) {                // 配置了备用模型(如 Opus → Sonnet)      logEvent('tengu_api_opus_fallback_triggered', {...}) // 埋点:记录降级事件与两个模型名      throw new FallbackTriggeredError(         // 抛专用错误:上游 query.ts 捕获后真正切换模型重发        options.model,                          // 原模型(日志用)        options.fallbackModel,                  // 目标模型      )    }    if (process.env.USER_TYPE === 'external' && !process.env.IS_SANDBOX && !isPersistentRetryEnabled()) { // 外部用户 + 非沙箱 + 非持久模式      throw new CannotRetryError(new Error(REPEATED_529_ERROR_MESSAGE), retryContext) // 放弃:给用户明确的"服务器过载"提示而非无限等待    }  }}

为什么这样设计:FallbackTriggeredError 是一个"控制流信号"而非真正的错误——它必须穿透到 query.ts 才能触发模型切换(claude.ts 第 2598-2604 行专门 catch 后原样 rethrow,注释警告"吞掉它会让降级变成 no-op")。预算设为 3 次而不是无限:过载时同一模型的容量不会自己恢复,继续重试只是排队;换一个小一号的模型反而可能立刻成功。资格限制(非订阅 + Opus)则体现了成本意识——降级意味着用更便宜的模型回答,只对 API key 用户(按量付费、可接受)开放。

5.3 上下文溢出自愈:解析错误文本改参数

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

if (error instanceof APIError) {  const overflowData = parseMaxTokensContextOverflowError(error) // 解析错误文本 "input length and `max_tokens` exceed context limit: A + B > C"  if (overflowData) {                                  // 解析成功:这是"输入+输出超出上下文窗口"的 400    const { inputTokens, contextLimit } = overflowData // 已用输入 token 数 + 模型上下文总上限    const safetyBuffer = 1000                          // 预留 1k buffer,防边界计算漂移    const availableContext = Math.max(0, contextLimit - inputTokens - safetyBuffer) // 输出还能占用的空间    if (availableContext < FLOOR_OUTPUT_TOKENS) {      // 剩余不足 3000 token:重试也产不出有意义的回答      throw error                                      // 放弃自愈,交给上层(如触发 compaction)处理    }    const minRequired = (retryContext.thinkingConfig.type === 'enabled' ? retryContext.thinkingConfig.budgetTokens : 0) + 1 // thinking 预算 + 至少 1 个输出 token    const adjustedMaxTokens = Math.max(FLOOR_OUTPUT_TOKENS, availableContext, minRequired) // 三者取最大:下限 / 剩余空间 / thinking 需求    retryContext.maxTokensOverride = adjustedMaxTokens // 写回重试上下文:下次尝试的 paramsFromContext 会读到这个值    continue                                           // 跳过退避直接重试——这是参数错误不是容量问题,等没有意义

为什么这样设计:这是全文件最"聪明"的一段:把错误文本当协议用。服务端在 400 的 message 里写死了 A + B > C 三个数字,客户端用正则(第 570-572 行)把它们抠出来,反推出"max_tokens 最多能设多少",然后改参数重试——而不是傻等。注意两个边界:剩余空间不足 3000 token 时直接放弃(说明上下文真的满了,该压缩历史而不是调小输出);continue 跳过退避(参数错误与服务端容量无关,立即重发)。另外 minRequired 把 thinking budget 算进去——extended thinking 的预算也占输出配额,漏掉它重试还会再失败一次。

5.4 持久模式:无人值守会话的无限重试

📄 src/services/api/withRetry.ts (第 477-512 行)

if (persistent) {                                    // 无人值守持久模式:429/529 无限重试(feature + env 双开关)  if (delayMs > 60_000) {                            // 等待超过 1 分钟值得单独埋点(正常交互不会到这)    logEvent('tengu_api_persistent_retry_wait', {...})  }  let remaining = delayMs                             // 把长 sleep 切成小块:让宿主进程看到周期性活动  while (remaining > 0) {                             // 每块 ≤30s,先 yield 心跳再睡    if (options.signal?.aborted) throw new APIUserAbortError() // 每个分片边界都检查中止信号    if (error instanceof APIError) {      yield createSystemAPIErrorMessage(error, remaining, reportedAttempt, maxRetries) // yield"重试中"系统消息:QueryEngine 转成 stdout 的 api_retry 事件    }    const chunk = Math.min(remaining, HEARTBEAT_INTERVAL_MS) // 一次睡一块(30s)——宿主不会把会话判为 idle 而杀掉    await sleep(chunk, options.signal, { abortError })    remaining -= chunk                                // 从总等待时长里扣掉这一块  }  if (attempt >= maxRetries) attempt = maxRetries     // 钳制:for 循环计数永不超限 → 循环永不结束(退避用独立的 persistentAttempt 计数器继续增长到 5min 上限)} else {                                              // 普通模式:睡一次就回到 for 循环顶部  if (error instanceof APIError) {    yield createSystemAPIErrorMessage(error, delayMs, attempt, maxRetries) // 同样的心跳机制:UI 显示"第 N/10 次重试,等待 Xs"  }  await sleep(delayMs, options.signal, { abortError }) // 睡退避时长;期间用户按 ESC 立即抛出中止

为什么这样设计:持久模式(CLAUDE_CODE_UNATTENDED_RETRY,内部功能)解决的是无人值守场景:CI、后台 agent 跑几小时,中途撞上额度窗口重置是常态。两个工程细节:其一,心跳分片——宿主环境(容器/调度器)通常按"多久没有 stdout 活动"判定会话 idle 并杀掉它,30s 一次的 yield 让进程持续"看起来活着";其二,attempt = maxRetries 的钳制是"无限循环"的实现技巧——for 条件 attempt <= maxRetries + 1 永远为真,而退避计算用独立的 persistentAttempt(第 434/449 行)继续增长直到 5min 上限。普通模式与持久模式共用同一个循环体,靠 persistent 布尔分流——一套代码两种生命周期。

顺带一提 fast mode(高速模型)还有一条独立分支(第 267-305 行):429/529 时若 Retry-After 短于 20s,保持 fast mode 等待重试以保住 prompt cache(同模型名才能命中缓存);长于 20s 则进入至少 10 分钟的冷却、切回标准速度——用"慢一点"换"缓存不失效",是成本与延迟的又一处权衡。

六、SSE 事件流解析:逐块拼装一条消息

重试引擎拿到的是 operation() 的返回值——一条 SSE 流。先看它是怎么创建的(claude.ts 第 1818-1836 行):

📄 src/services/api/claude.ts (第 1818-1836 行)

// Use raw stream instead of BetaMessageStream to avoid O(n²) partial JSON parsingconst result = await anthropic.beta.messages      // 调 Messages API(参数来自第 7 讲的 paramsFromContext)  .create(    { ...params, stream: true },                  // 请求体 + 流式开关:服务端以 SSE 事件逐块返回    { signal, ...(clientRequestId && { headers: { [CLIENT_REQUEST_ID_HEADER]: clientRequestId } }) }, // 中止信号 + 客户端生成的请求 ID(超时时没有服务端 ID,靠它关联日志)  )  .withResponse()                                 // 要原始 Response 而不是 SDK 包装好的流对象queryCheckpoint('query_response_headers_received') // TTFB 检查点:发起到收到响应头streamRequestId = result.request_id                // 服务端请求 ID(排障时关联两端日志)streamResponse = result.response                   // 保留 Response 引用:之后解析额度 header + 释放资源都要用它return result.data                                 // 返回原始 SSE 流 Stream<BetaRawMessageStreamEvent>

为什么这样设计:注释直接点题:SDK 的 BetaMessageStream 会对每个 input_json_delta 调一次 partialParse()——工具参数越长,重复解析的总代价越高(O(n²))。Claude Code 自己累积 JSON 文本、最后一次性 parse,所以改用 raw stream。另外注意第 1781 行(withRetry 调用处)maxRetries: 0——SDK 自带的自动重试被显式关掉,"手动实现优先":因为 SDK 的重试不理解 529 预算、模型降级、fast mode 冷却这些业务规则,两层重试叠加只会放大请求量。

流建好后,进入事件消费循环(第 1940-1977 行)。每个事件先过两道"健康监测":

📄 src/services/api/claude.ts (第 1940-1977 行)

for await (const part of stream) {                 // 逐个消费 SSE 事件(raw Stream,无 SDK 包装)  resetStreamIdleTimer()                           // 每收到一个事件就重置看门狗计时器  const now = Date.now()  if (lastEventTime !== null) {                    // 首个 chunk 跳过:TTFB(首字节延迟)不算卡顿    const timeSinceLastEvent = now - lastEventTime    if (timeSinceLastEvent > STALL_THRESHOLD_MS) { // 相邻两事件间隔超 30s → 记一次 stall      stallCount++                                 // 本次流的卡顿次数 +1      totalStallTime += timeSinceLastEvent         // 累计卡顿总时长(流结束后汇总上报)      logEvent('tengu_streaming_stall', {...})     // 埋点:时长+次数+事件类型,供离线分析慢流分布    }  }  lastEventTime = now                              // 更新"上次事件时间"基准  if (isFirstChunk) {                              // 首个 chunk 到达(只触发一次)    queryCheckpoint('query_first_chunk_received')  // TTFB 检查点:请求发出 → 第一个 SSE 事件    endQueryProfile()                              // 结束启动阶段 profiling    isFirstChunk = false                           // 后续 chunk 不再进这个分支  }

为什么这样设计:stall 检测是被动的——它只在"下一个 chunk 到达时"才发现上一个间隔太长,所以流彻底挂死(永远没有下一个 chunk)时它无能为力。这正是下一节看门狗存在的理由:主动用 setTimeout 杀流。两者互补:stall 检测负责度量(埋点、定位慢在哪类事件),watchdog 负责兜底(保证会话不会无限挂起)。TTFB 被显式排除在 stall 统计之外——首字节延迟受网络/排队影响大,混进卡顿指标会污染数据。

看门狗本体(第 1895-1928 行):

📄 src/services/api/claude.ts (第 1895-1928 行)

function resetStreamIdleTimer(): void {            // 每个 chunk 到达时调用:重启两个计时器  clearStreamIdleTimers()                          // 先清旧定时器,防止重复触发  if (!streamWatchdogEnabled) return               // 看门狗默认关闭(env CLAUDE_ENABLE_STREAM_WATCHDOG 开启)  streamIdleWarningTimer = setTimeout(             // 警告定时器:超时的一半(45s)    warnMs => { logForDebugging(`Streaming idle warning: no chunks received for ${warnMs / 1000}s`, ...) }, // 只记日志,不打断流——给慢响应留余地    STREAM_IDLE_WARNING_MS, STREAM_IDLE_WARNING_MS,  )  streamIdleTimer = setTimeout(() => {             // 杀流定时器:90s 完全无 chunk    streamIdleAborted = true                       // 标记"被看门狗中止":循环退出后走非流式降级路径    streamWatchdogFiredAt = performance.now()      // 记录触发时刻:之后测量 abort 传播延迟(区分真挂死 vs 错误退出)    logEvent('tengu_streaming_idle_timeout', {...}) // 埋点:模型 + request_id + 超时值    releaseStreamResources()                       // cancel Response.body,释放原生 TLS/socket buffer——它在 V8 堆外,不显式释放会内存泄漏(GH #32920)  }, STREAM_IDLE_TIMEOUT_MS)                        // 默认 90s;env CLAUDE_STREAM_IDLE_TIMEOUT_MS 可覆盖}

为什么这样设计:源码注释解释了必要性:"the SDK's request timeout only covers the initial fetch(), not the streaming body"——SDK 的超时只管请求建立,不管流式 body;连接被静默丢弃(NAT 超时、代理断连)时,for-await 会永远等下去。看门狗用 setTimeout 主动 abort 补上这个洞。两个工程细节:其一,警告与杀流分离(45s 只记日志、90s 才动手),避免网络抖动误杀;其二,releaseStreamResources()(第 1519-1526 行)显式 body.cancel()——Node 的 Response body 持有堆外原生 buffer,GC 不会及时回收,必须手动释放。看门狗默认关闭也值得注意:这是"先埋点观察、再决定全量"的保守策略。

事件本身按 Anthropic SSE 协议分五类:message_start → content_block_start/delta/stop(可多个块)→ message_delta → message_stop。消费端的核心状态机在 switch (part.type) 里。先看 content_block_start——这里藏着两个 SDK 怪癖的防御代码(第 2019-2051 行):

📄 src/services/api/claude.ts (第 2019-2051 行)

case 'text':  contentBlocks[part.index] = {                    // 按 index 登记 text 块(多块并行时靠下标区分)    ...part.content_block,                         // 浅拷贝 SDK 对象——SDK 会原地 mutate,我们要不可变副本自己累积    text: '',                                      // 故意清空:SDK 有时在 start 事件里带全文、又在 delta 里重复发一遍  }                                                // 保留它首句就会翻倍;没有可靠办法检测重复,忽略最安全case 'thinking':  contentBlocks[part.index] = {                    // thinking 块同理    ...part.content_block,    thinking: '',                                  // 同样的"start 带文本"怪癖,清空重来    signature: '',                                 // 预置空签名:即使 signature_delta 永远不来,字段也存在(下游不用判 undefined)  }default:  contentBlocks[part.index] = { ...part.content_block } // 其他类型(tool_result 等):拷贝登记即可

为什么这样设计:源码注释连用三个"awkwardly"——这是与 SDK 行为搏斗留下的战壕。核心矛盾:SDK 的流式对象是可变的(边收边改),而 Claude Code 需要自己维护一份不可变累积状态(每个块独立成消息、可回溯)。解法是"拷贝 + 清空可疑字段 + 只信 delta":text: '' 和 thinking: '' 把 start 事件里可能携带的重复内容丢弃,后续一律靠 content_block_delta 增量拼接。signature: '' 预置则是防御性编程——extended thinking 的签名用于服务端校验推理完整性,字段缺失会让下游序列化出 undefined。

delta 分支对每种类型都先做类型断言再拼接(第 2087-2112 行,以工具参数为例):

📄 src/services/api/claude.ts (第 2087-2112 行)

case 'input_json_delta':                           // 工具调用参数以 JSON 片段形式到达  if (contentBlock.type !== 'tool_use' && contentBlock.type !== 'server_tool_use') { // 先断言:这种 delta 只能落在工具块上    logEvent('tengu_streaming_error', {...})        // 埋点:记录期望类型 vs 实际类型(协议违规取证)    throw new Error('Content block is not a input_json block') // fail fast:状态机失步时立即报错,而不是静默拼出脏数据  }  if (typeof contentBlock.input !== 'string') {    // start 阶段已把 input 初始化为 '',这里必须是字符串    logEvent('tengu_streaming_error', {...})        // 埋点:记录实际类型    throw new Error('Content block input is not a string') // 不是 → 状态机失步(start/delta 乱序),立即失败  }  contentBlock.input += delta.partial_json         // 片段追加到 JSON 文本——不做 partialParse,避免 O(n²)(见第六节开头)

为什么这样设计:SSE 流是"信任边界"——服务端、代理、SDK 任何一层出 bug 都可能让事件乱序或错配。这里的策略是每个 delta 都验证它落在正确的块上,违规就抛错(配合埋点留证),而不是 try-catch 吞掉继续拼:工具参数 JSON 拼错了,下游执行的是错误命令,静默容错的代价远高于 fail fast。text_delta/thinking_delta/signature_delta 分支是同样的模式(第 2113-2161 行)。

content_block_stop 时把累积好的块规范化成一条 AssistantMessage 并 yield 给上层(第 2192-2211 行)——每个内容块独立成消息,UI 可以逐块渲染。最后的关键在 message_delta:它携带最终的 usage 和 stop_reason,而写回方式藏着一条微妙的引用语义(第 2236-2248 行):

📄 src/services/api/claude.ts (第 2236-2248 行)

// IMPORTANT: Use direct property mutation, not object replacement.// The transcript write queue holds a reference to message.message// and serializes it lazily (100ms flush interval). Object replacement would// disconnect the queued reference; direct mutation ensures the transcript captures final values.stopReason = part.delta.stop_reason                // 最终停止原因(end_turn / max_tokens / tool_use …)const lastMsg = newMessages.at(-1)                 // content_block_stop 时刚 yield 的最后一条消息if (lastMsg) {  lastMsg.message.usage = usage                    // 直接改属性:把最终 token 统计写回原对象  lastMsg.message.stop_reason = stopReason         // stop_reason 同样原地写回

为什么这样设计:这是全文件最容易被"重构坏"的一处。消息在 content_block_stop 时创建,那时 usage 还是初始值(output_tokens: 0、stop_reason: null);真正的数值要等 message_delta 才到。而 transcript 落盘队列持有的是对象引用、按 100ms 间隔惰性序列化——如果这里写成 lastMsg.message = { ...lastMsg.message, usage }(替换整个对象),队列里排队的还是旧引用,落盘的永远是 output_tokens: 0。原地 mutate 让"已入队未刷盘"的引用自动拿到最终值。共享可变状态 + 惰性序列化的组合下,mutate 不是坏味道而是正确性要求——这类 bug 只在时序窗口内出现(100ms 内没刷盘就替换),极难复现,所以源码用大写 IMPORTANT 注释钉死。

流正常结束后还有一道"假成功"检测(第 2350-2363 行)——代理返回 200 但 body 根本不是 SSE:

📄 src/services/api/claude.ts (第 2350-2363 行)

// Detect when the stream completed without producing any assistant messages.if (!partialMessage || (newMessages.length === 0 && !stopReason)) { // 两种假成功:① 连 message_start 都没有;② 有 start 但没有任何块完成且没收到 stop_reason  logEvent('tengu_stream_no_events', {...})        // 埋点:模型 + request_id(定位是哪个代理/网关出的问题)  throw new Error('Stream ended without receiving any events') // 抛错 → 外层 catch 走非流式降级,而不是静默返回空结果

为什么这样设计:注释列了两类代理故障:200 + 非 SSE body(!partialMessage),以及只发了 message_start 就断流。没有这道检查,生成器会"成功"返回零条消息——headless -p 模式下表现为莫名其妙的 "Execution error"。注意条件里特意带上 && !stopReason:结构化输出场景(--json-schema)下模型第二轮合法地只回 end_turn、不带内容块,那是正常空响应不是断流——用 stop_reason 区分"合法的无内容"和"异常的未完成",避免误杀。

七、错误分流:谁中止的?降级到哪一层?

流式路径的 catch 块(第 2404 行起)先解决一个身份问题——APIUserAbortError 可能是用户按 ESC,也可能是 SDK 内部超时,两者处理完全相反(第 2434-2461 行):

📄 src/services/api/claude.ts (第 2434-2461 行)

if (streamingError instanceof APIUserAbortError) { // SDK 抛"被中止"——但到底是谁中止的?  if (signal.aborted) {                            // 我们的 AbortSignal 确实被触发 → 用户按了 ESC    logForDebugging(`Streaming aborted by user: ${errorMessage(streamingError)}`)    throw streamingError                           // 用户主动:原样上抛,不重试、不降级(尊重用户意图)  } else {                                         // signal 没动过 → 是 SDK 内部超时自己触发的 abort    logForDebugging(`Streaming timeout (SDK abort): ${streamingError.message}`, ...)    throw new APIConnectionTimeoutError({ message: 'Request timed out' }) // 转译成"超时"错误:下游按可重试的瞬时故障处理  }}

为什么这样设计:同一个异常类型、两种相反语义——用户中止必须立即停止一切重试(再试就是违背指令),SDK 超时则应该进入重试路径。区分手段很朴素:检查我们自己的 AbortSignal 是否被触发过。这种"用外部状态给异常定性"的模式,比让 SDK 抛两种不同错误类型更可靠——因为 SDK 的行为不受我们控制。

确认是瞬时故障后,进入流式 → 非流式降级(第 2534-2569 行)。这是比"重试"更进一步的兜底:换一种请求模式:

📄 src/services/api/claude.ts (第 2534-2569 行)

const result = yield* executeNonStreamingRequest(  // 委托非流式路径(它内部有自己的 withRetry 循环)  { model: options.model, source: options.querySource },  {    model: options.model,                           // 同一模型参数    fallbackModel: options.fallbackModel,           // 降级模型配置原样传递    thinkingConfig,                                 // thinking 配置不变    signal,                                         // 中止信号与流式路径共享(用户 ESC 依然有效)    initialConsecutive529Errors: is529Error(streamingError) ? 1 : 0, // 若流式失败本身就是 529,预置计数 +1:两种模式共用同一 529 预算(修 issue #1513)    querySource: options.querySource,               // 来源标签透传(决定 529 是否允许重试)  },  paramsFromContext,                                // 复用同一个参数构造闭包——两条路径请求体完全一致  (attempt, _startTime, tokens) => { attemptNumber = attempt; maxOutputTokens = tokens }, // 回写尝试序号与输出上限(埋点用)  params => captureAPIRequest(params, options.querySource), // 捕获请求体供 bug report  streamRequestId,                                  // 关联原始流式请求 ID,两端日志可串起来)

为什么这样设计:非流式降级针对的是"流式通道本身坏了"的场景——网关不支持 SSE、代理截断 body、404 streaming endpoint(第 2607-2654 行专门处理:某些网关对 /stream 返回 404 但普通端点正常)。注意 initialConsecutive529Errors 的传递:流式阶段吃掉的 529 预算要带进非流式循环,否则"流式 3 次 + 非流式 3 次 = 6 次 529"会突破设计上限。还有一个反向开关(第 2464-2502 行):CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK 可以关掉降级——因为流式执行工具时中途失败再非流式重发,同一个 tool_use 会被执行两次(源码注释引用了内部事故 inc-4258)。"降级可能放大副作用"是这条兜底路径的固有代价,所以留了逃生门。

至此错误处理的完整分层已经清晰。下表汇总本讲拆解过的全部故障场景与对应策略:

故障场景
处理策略
代码位置
408 / 409 / 5xx
指数退避重试(≤10 次,32s 封顶 + 抖动)
withRetry.ts L753-786
429(API key / 企业)
重试;Retry-After 优先于本地退避
withRetry.ts L767-769, L530-548
429(Max/Pro 订阅)
默认不重试;持久模式睡到额度重置时刻
withRetry.ts L767-769, L814-822
529(前台来源)
重试;连续 3 次 → 模型降级或明确报错
withRetry.ts L326-364
529(后台来源)
立即放弃,不放大网关压力
withRetry.ts L316-324
上下文溢出 400
解析错误文本反推 max_tokens,改参立即重试
withRetry.ts L388-427
ECONNRESET / EPIPE
禁用 keep-alive,重建 client 强制新握手
withRetry.ts L218-251
401 / token revoked
刷新 OAuth token + 清 key 缓存后重试
withRetry.ts L240-251, L773-781
流式挂死(无 chunk)
90s 看门狗 abort → 非流式降级
claude.ts L1895-1928, L2310-2334
假成功(200 + 非 SSE)
空流检测抛错 → 非流式降级
claude.ts L2350-2364
流式端点 404
网关兼容:切非流式端点重发
claude.ts L2607-2654
用户按 ESC
立即终止,不重试不降级(尊重意图)
claude.ts L2434-2451

最后用一张数据流图串起一次请求的完整旅程——从进入 withRetry 到拿到消息或触发降级:

一次模型请求的完整旅程(流式路径)

① 尝试循环:withRetry for-loop

检查中止信号 → 鉴权/陈旧连接则刷新 client → 调 operation()。失败进 catch 分流。

▼

② 建流:messages.create(stream:true).withResponse()

SDK 自动重试关闭(maxRetries:0);raw Stream 避免 O(n²) partialParse。

▼

③ 消费:for await (const part of stream)

🔹 message_start → 记 TTFB + usage🔹 content_block_* → 类型断言后增量拼装,块完成即 yield AssistantMessage🔹 message_delta → 原地 mutate 写回最终 usage/stop_reason

▼

④ 监测:三层超时防线并行

🔹 SDK fetch timeout:只覆盖请求建立🔹 stall 检测(30s):被动度量,埋点定位慢流🔹 idle watchdog(90s):主动 abort + releaseStreamResources

▼

⑤ 失败升级:shouldRetry → 退避重试 → 降级

🔹 可重试:指数退避+抖动(或睡到额度重置)🔹 流式通道坏:非流式重发(529 预算跨模式共享)🔹 连续 3×529:FallbackTriggeredError → query.ts 切备用模型

本讲小结:Claude Code 的流式层把"重试"做成了一个分层系统——参数级自愈(溢出改 max_tokens)、模式级降级(流式切非流式)、模型级切换(529 预算耗尽换小模型),每一层都有明确的触发条件、预算上限和埋点。而所有重试的底层约束只有一条:区分"服务端的问题"(值得等)与"我们的问题"(立即失败),并且永远不让不可见的后台任务为全局容量买单。

📚 系列导航

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

→ 第 9 讲:认证 / OAuth / 额度护栏

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

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

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

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

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

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

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

相关学习资料