# Error Recovery

排查或加固 Agent 故障恢复机制时使用, , 当 Agent...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill error-recovery -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill error-recovery -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill error-recovery -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill error-recovery -g -a gemini-cli -y`

## Description

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 故障与错误恢复

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

## 核心原则

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

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

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

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

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

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

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

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

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

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/error-recovery/SKILL.md