ARTICLE · 1374330
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)。
下表汇总本讲涉及的全部重试参数,后面逐节展开:
二、重试前的准备: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)。"降级可能放大副作用"是这条兜底路径的固有代价,所以留了逃生门。
至此错误处理的完整分层已经清晰。下表汇总本讲拆解过的全部故障场景与对应策略:
最后用一张数据流图串起一次请求的完整旅程——从进入 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+ 个上过榜的项目,能按分类、星级、上榜天数筛。免费看,不用注册。

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















































































