fault-recovery

name	fault-recovery
description	当 Agent 陷入死循环、反复重试同一失败、静默卡死、工具调用失败后无法自恢复、或单点故障导致任务中断时使用；当需要设计错误处理、重试策略、熔断与降级时使用。不适用于工具的日常设计（见 tool-design），聚焦运行期故障的检测、恢复与终止。

故障恢复（Fault Recovery）

角色与读者

面向生产级 Agent 的开发者与运维者。本 Skill 服务的目标：Agent 的可靠性不取决于模型犯不犯错，而取决于每类故障是否都有对应的检测、恢复与终止路径。核心认识：错误处理的边界不是单次请求，而是整个恢复循环；在确认无法恢复之前，中间错误不应暴露给用户。

核心原则（配正例/反例）

1. 先分类，再计数（值不值得重试 > 要不要重试）

   • 四层故障：API 层（限流/超时/连接中断）、工具层（幻觉调用/参数畸形/执行异常/反复返回同一错误）、上下文层（窗口溢出/压缩失败/轨迹结构损坏）、控制流层（死循环/死亡螺旋）。
   • 可重试错误（限流/过载/网络抖动）重试才有意义；不可重试错误（参数不合法/权限不足/工具不存在）原样重试多少次都一样，必须改变输入或策略。
   • 维护"错误→恢复策略"映射表，而非笼统"出错就重试"。

2. 检测模式：重复调用指纹 + 连续失败计数 + 活性监控

   • 对"工具名+参数"计算指纹，相同指纹反复出现 = 无进展循环信号。
   • 流式连接最危险是静默卡死（连接成功但数据流停止），SDK 超时只覆盖初始连接 → 需独立空闲看门狗（watchdog）。每个长连接都需要活性信号。

3. 分级恢复：静默重试 → 降级接续 → 暴露给用户

   • 静默重试：指数退避 + 随机抖动（避免同步重试二次拥塞），区分前台/后台调用（后台辅助失败直接放弃，避免"重试放大"）。
   • 降级接续：输出触顶先提上限重发、仍不够末尾追加元指令从断点接续；主模型过载降级备用模型（先剥离旧模型私有格式块）。
   • 工具错误变成模型输入（结构化错误喂回，模型自我纠正），而非终止会话。

4. 每条恢复路径都有熔断上限，阈值来自生产数据

   • 例：上下文压缩连续失败 N 次放弃压缩（N 来自真实会话统计，而非拍脑袋）。
   • 防死亡螺旋：错误路径上禁用一切会再次调用模型的副作用逻辑 + 递归深度计数器。

5. 未完成工具用显式占位符，不能伪造成功

   • 打断时给未完成工具生成占位符响应（"工具正在后台执行，请优先处理新事件"），保持 assistant 与 tool result 配对完好。

执行流程（SOP 检查清单）

1. 建故障分类表（四层）+ 错误→恢复策略映射表。
2. 实现检测：重复指纹、连续失败计数、空闲看门狗、完整性监控（工具调用缺配对结果自动修复）。
3. 实现分级恢复：静默重试（退避+抖动）→ 降级接续 → 暴露给用户；工具错误结构化喂回。
4. 设熔断上限（每条路径）+ 死亡螺旋防护 + 全局终止条件（最大轮数/预算/连续失败升级人工）。
5. 产品模式宽容、训练模式严格（训练模式拒绝用占位符修补，避免污染训练数据）。

禁止清单（写清合法例外）

• 禁止对不可重试错误原样重试。例外：可重试错误（限流/过载/网络抖动）才重试。
• 禁止静默卡死无看门狗。例外：每个长连接都设空闲看门狗，超时主动杀死挂起流并重试。
• 禁止伪造工具成功。例外：未完成工具用显式占位符，且后续真实结果到达时作为新事件追加。
• 禁止后台辅助调用失败也重试（挤占主链路配额形成"重试放大"）。例外：后台调用失败直接放弃。
• 禁止把最后一个报错当根因（应定位首个导致任务偏离的错误）。例外：失败归因区分根因与后果。

参考资料

• 本书第 5.1.5 节《故障与错误恢复》（四层故障分类、检测、分级恢复、终止）+ 第 6.2.7 节《如何让同步模型支持异步打断》。
• 笔记 05-Coding-Agent与通用Agent.md 第 5.1.5 节、06-交互.md 第 6.2.7 节。