error-recovery

故障与错误恢复

何时使用

• Agent 反复调用同一工具毫无进展、陷入死循环或死亡螺旋
• 流式响应在思考/正文/工具调用参数中途断开，需要续写
• 模型 API 限流、过载、超时、输出触顶，需要重试或降级
• 上下文窗口溢出、压缩失败、轨迹结构损坏（工具调用缺配对结果）
• 主模型持续不可用，要把轨迹交给另一家模型接着跑
• 设计重试策略、熔断阈值、错误暴露边界
• 工具调用幻觉/参数畸形，需要让模型自我纠正

核心原则

故障分类学：四层。 先分类再处理，不同层的故障走完全不同的恢复路径：

• API 层：限流（429）、过载、请求超时、连接中断、输出触顶被截断。与任务内容无关，是基础设施噪声——可重试。
• 工具层：幻觉调用（调用不存在的工具）、参数畸形、执行抛异常，以及最危险的一种：工具反复返回同一错误，模型不加改变地反复重试。
• 上下文层：窗口溢出、压缩失败、轨迹结构损坏。
• 控制流层：死循环（相同操作无进展）与死亡螺旋（恢复逻辑自身又调 LLM、再次出错、连锁反应）。

检测：先分类，再计数。 第一个判断不是"要不要重试"而是"值不值得重试"：可重试错误（限流、过载、网络抖动）重试才有意义；不可重试错误（参数不合法、权限不足、工具不存在）原样重试一万次结果相同，必须改变输入或策略。生产级 Harness 维护一张"错误 → 恢复策略"的映射表，而不是笼统地"出错就重试"。单次错误之外还要检测模式：对"工具名 + 参数"计算指纹，相同指纹反复出现就是无进展循环的明确信号；每条恢复路径维护独立的连续失败计数，为熔断提供依据。

活性与完整性监控。 流式连接最危险的失败不是断开（会立即报错），而是静默卡死——连接建立但数据流停止。SDK 超时往往只覆盖初始连接而非传输过程，需要独立的空闲看门狗（超过设定时间无新输出即判定卡死，主动杀死挂起的流并重试）。可推广为：每个长连接都需要活性信号，而非仅依赖连接超时。完整性监控针对轨迹结构：发现工具调用缺少配对结果消息时，在注入上下文前自动修复配对，而不是把结构异常抛给模型或用户。产品模式可用占位符宽容修补，训练数据收集模式则拒绝修复——合成占位符会污染训练数据。

恢复：分级升级，逐级透明。 能用低级别解决就不升级：

1. 静默重试——可重试错误的默认动作。指数退避叠加随机抖动（避免客户端同步重试造成二次拥塞，尊重服务端的等待时长提示）；区分前台与后台调用：主循环失败要重试，标题生成、输入建议这类辅助性后台调用失败直接放弃，否则后台重试挤占主链路配额，形成"重试放大"。
2. 降级与接续——重试无效时改变请求本身。输出触顶：先静默提升输出上限重发，仍不够再在消息末尾追加元指令让模型从断点接续；主模型过载时降级到备用模型（先剥离旧模型私有格式块，否则新模型解析不了历史）；高成本模式被限流时暂时回落到标准模式。
3. 暴露给用户——所有自动手段用尽后才呈现错误，并附上已尝试过的恢复动作。

工具层错误走另一条路：不终止会话，把错误变成模型的输入。 幻觉调用收到"工具不存在"的结构化错误结果；参数校验失败收到附带输入约束提示的错误；畸形参数（该是对象却输出字符串）在执行前先程序化修复。错误以普通工具结果身份进入上下文，由模型下一轮自行纠正——喂回的错误越具体，自我纠正成功率越高。

错误处理的边界不是单次请求，而是整个恢复循环。 在确认无法恢复之前，中间错误不暴露给消费者（用户或订阅事件的下游系统）：恢复期间扣留错误消息，恢复成功则消费者毫无感知，所有手段均失败后才统一呈现。

跨厂商接管：带走文字，带不走凭证。 换一家模型把轨迹接着跑完，真正的障碍不是接口地址，而是轨迹里有只属于原厂商的东西。工具调用与结果各家结构不同但语义一致，重新渲染即可；难办的是思考——它由可读文字和厂商凭证（证明这段思考出自它自己）构成，文字换一家仍读得懂，凭证换一家就失效。且凭证未必附在思考上，也可能附在工具调用上（如 Google 的 thoughtSignature），所以"把思考删干净就安全"反而会在严格校验的厂商处失败。接管方案按最严格的一端设计：把历史工具调用改写成文字叙述，模型不再当作真正调用过，但至少能接着跑。由此得到设计原则：轨迹按中立格式存储——思考拆成可移植文字与不可移植凭证两个槽位，工具调用只记名称与参数，标识符渲染成具体请求时按目标厂商重新生成；切换时凭证一律丢弃，文字以普通内容身份带入。中立轨迹还服务于评估重放、训练样本构造、经验提取。

终止：每条恢复路径都要有上限。 恢复机制本身也可能失效：上下文压缩连续失败若干次就放弃压缩，权限分类连续失败就回退人工询问，输出接续最多固定轮数。阈值来自生产数据而非拍脑袋——Claude Code 的"连续 3 次"压缩熔断阈值来自真实会话统计（曾有会话连续失败三千余次，仅此一类无效重试每天全球浪费约 25 万次 API 调用；3 次是"绝大多数故障此前已恢复"与"继续重试基本无望"之间的经验拐点）。