57
0这一章深入解析了 Claude Code 如何在不稳定的网络和 API 过载环境下，通过一套精密、具备韧性的通信子系统来保证 Agent 的可靠性。
以下是该章节的核心内容总结：
1. 核心哲学：通信失败是常态
该系统将 API 通信层视为 Agent 的控制平面（Control Plane），而非简单的 SDK 封装。其核心理念是：通信失败是常态而非异常，系统必须在每一层都有预案。所有的降级、重试和缓存保护策略都在这一层完成决策。
2. 多级重试策略与模型降级
系统通过 withRetry.ts 实现了一套高度可调优的重试机制：
- 指数退避与随机抖动：默认提供 10 次重试预算，采用 500ms 基数的指数退避，并叠加 0-25% 的随机抖动（Jitter）以避免“雷群效应”。
- 差异化重试决策：
shouldRetry()函数会根据错误类型做决策。例如，对于按量计费用户的 429（限流）会重试，但对于 ClaudeAI 订阅用户的 429 则不重试，因为后者的限制窗口通常长达数小时，重试无意义。 - 529 过载特殊处理：这是系统级的减载（Load Shedding）策略。连续 3 次 529 错误会触发模型降级（例如从 Opus 降级到 Sonnet），且只有前台请求才会重试 529，后台任务会立即放弃以减轻后端压力。
3. 流式通信的双重“看门狗”
为了应对流式连接静默挂起的问题，系统设计了两层检测机制：
- Idle Timeout 看门狗（中断型）：如果 90 秒完全没有收到任何流式事件，判定流已死，强制中断并触发非流式回退。
- Stall 检测（日志型）：如果两个事件之间的间隔超过 30 秒，系统会记录遥测事件但不会中断连接。这种机制主要用于识别“服务端响应慢”而非“连接已死”。
- 非流式回退：当流式失败时，系统会尝试回退到非流式模式，并确保重试计数在切换过程中不会重置。
4. Fast Mode 与缓存感知重试
在加速模式（Fast Mode）下，重试决策会优先考虑 Prompt Cache（提示词缓存） 的保护：
- 20 秒阈值：如果
Retry-After头部指示等待时间 小于 20 秒，系统会原地等待以保留缓存；如果大于等于 20 秒，则认为缓存可能已失效，转而切换到标准模式并进入冷却期。
5. 持久重试模式与“心跳保活”
针对 CI/CD 等无人值守场景，系统提供了持久重试模式：
- 无限重试：对 429/529 错误进行无限重试，退避时间最高可增长至 5 分钟。
- 心跳机制：为了防止远程容器因长时间无输出而被回收，系统将长达 5 分钟的等待切片为多个 30 秒片段，每个片段后通过
yield产生一条心跳消息，从而保持流活跃并允许用户随时中断等待。
6. 三事件遥测模型
系统的可观测性基于三个核心事件构建：tengu_api_query（请求发出）、tengu_api_success（成功响应）和 tengu_api_error（失败响应）。
- 精细化诊断：错误分类多达 25 种，能够精确区分是 SSL 证书问题、模型访问受限还是 API 密钥无效。
- 网关指纹检测：系统能识别请求是否经过了 LiteLLM、Cloudflare 等第三方 AI 网关，以便诊断特定代理环境下的错误模式。
7. 模式提炼
- 有限重试预算 + 独立降级阈值：全局 10 次，529 错误 3 次。
- 双重看门狗：区分“死连接”与“慢连接”。
- 缓存感知的重试：在等待时间与缓存重建成本之间寻找平衡。
- 心跳保活：将同步等待转为异步协作，解决容器回收与中断响应问题。
总结而言， Claude Code 如何将 API 调用从一个简单的网络请求升华为一个高度可观测、具备自愈能力且成本感知的工业级控制系统。
