---
name: error-recovery
description: 排查或加固 Agent 故障恢复机制时使用——当 Agent 陷入无限循环、流式响应中途断开、上下文溢出、模型服务限流过载、需要跨厂商接管跑到一半的轨迹、设计重试与熔断策略、防止错误处理路径自身引发连锁故障时使用。覆盖四层故障分类、检测方法、分级恢复策略、熔断上限与流式中断恢复。
---

# 故障与错误恢复

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

## 核心原则

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

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

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

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

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

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

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

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

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

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

**死亡螺旋防护。** 错误处理路径中的逻辑本身又调用 LLM，再次出错引发连锁。真实案例：上下文溢出触发"结束时自动提交代码"钩子，钩子调 LLM 生成 commit message 再次溢出，又一次触发钩子。防护两条：错误路径上禁用一切会再次调用模型的副作用逻辑（宁可丢掉自动记忆提取之类的辅助功能），以及用递归深度计数器检测并打断残余连锁。最后叠加全局终止条件：最大迭代轮数、会话预算上限、连续失败超阈值升级人工。

**流式中断的三个断点、三种恢复方式。** 断点可能出现在：思考中途、正文中途、工具调用参数中途。恢复方式：① 丢弃半截内容整轮重发（最贵但最稳）；② 把半截内容作为末尾 assistant 消息要求模型接着写（部分厂商原生支持，其余需显式标注待续写消息，没有该接口则退回下一种）；③ 追加一条元指令说明从断点继续。注意：半截的工具调用无法以原生结构回传，需先转成文字再让模型补完，拼接后重新解析校验；若半截输出里已有工具因流式提前执行，续写前按调用指纹去重，避免重复副作用；拼接处容易多出空白或重复字符——参数合法不等于语义正确。

## 实践模式

**建一张错误 → 策略映射表**（比"出错就重试"的根本改进）：

1. 捕获异常 → 归入 API/工具/上下文/控制流四层之一
2. 可重试？→ 指数退避 + 抖动静默重试（前台重试、后台放弃）
3. 改变请求可救？→ 提升输出上限 / 追加接续元指令 / 降级备用模型 / 回落标准模式
4. 工具层错误 → 结构化错误结果喂回上下文，让模型下轮自我纠正
5. 持续失败 → 查恢复路径的连续失败计数器，超阈值熔断（阈值从生产日志统计得出）
6. 全部失败 → 统一向用户暴露，附已尝试的恢复动作清单

**流式恢复实现清单**：记录断点类型（思考/正文/参数）；半截工具调用转文字 + 指纹去重；拼接后重新解析校验参数；对比三种方式的 token 成本与恢复成功率，选默认路径。

**接管实现清单**：轨迹存中立格式（文字/凭证分离）；渲染层按目标厂商重组；凭证一律丢弃；遇强制凭证校验的厂商，历史调用改写为文字叙述；切换后监控重复调用指纹。

## 常见陷阱
- 笼统"出错就重试"：不可重试的错误（参数不合法、权限不足）重试多少次都一样
- 只依赖连接超时：静默卡死（连接通但无数据）检测不到，必须配空闲看门狗
- 后台辅助调用也重试：重试放大挤占主链路配额
- 恢复期间把中间错误暴露给用户或下游事件订阅者
- 没有熔断上限：一条恢复路径连续失败三千次，白白烧掉海量 API 调用
- 错误处理路径自身调用 LLM：死亡螺旋，连锁故障
- 以为删掉思考就安全跨厂商接管：凭证可能挂在工具调用上
- 续写半截输出不按调用指纹去重：已执行的工具产生重复副作用
- 训练数据收集模式用占位符修补缺失消息：污染训练数据

## 配套代码
- `chapter5/provider-failover/` — 实验 5-1/5-2：中立轨迹格式实现跨厂商接管（直传/剥离/中立三臂对照）与流式三断点接续
- `chapter5/log-diagnosis/` — 诊断 Agent 读轨迹定位根因、生成回归测试、真实重放验证并建 Issue 的完整闭环
- `chapter5/adaptive-log-parser/` — 自愈循环示范：解析失败不报错，而是把失败样本交给 Agent 生成代码、测试、热更新

## 深度阅读
- `book/chapter5.md`「故障与错误恢复」
- `book/chapter5.md`「Coding Agent」→「实现技巧」（并行工具调用、流式执行与级联中止）
- `book/chapter1.md`「Harness 工程：模型之外的竞争力」（纠正机制与"不暴露中间态"原则）