排查或加固 Agent 故障恢复机制时使用——当 Agent 陷入无限循环、流式响应中途断开、上下文溢出、模型服务限流过载、需要跨厂商接管跑到一半的轨迹、设计重试与熔断策略、防止错误处理路径自身引发连锁故障时使用。覆盖四层故障分类、检测方法、分级恢复策略、熔断上限与流式中断恢复。
インストールする前に、エージェントに与えられる指示の中身を確認できます。
故障分类学：四层。 先分类再处理，不同层的故障走完全不同的恢复路径：
检测：先分类，再计数。 第一个判断不是"要不要重试"而是"值不值得重试"：可重试错误（限流、过载、网络抖动）重试才有意义；不可重试错误（参数不合法、权限不足、工具不存在）原样重试一万次结果相同，必须改变输入或策略。生产级 Harness 维护一张"错误 → 恢复策略"的映射表，而不是笼统地"出错就重试"。单次错误之外还要检测模式：对"工具名 + 参数"计算指纹，相同指纹反复出现就是无进展循环的明确信号；每条恢复路径维护独立的连续失败计数，为熔断提供依据。
活性与完整性监控。 流式连接最危险的失败不是断开（会立即报错），而是静默卡死——连接建立但数据流停止。SDK 超时往往只覆盖初始连接而非传输过程，需要独立的空闲看门狗（超过设定时间无新输出即判定卡死，主动杀死挂起的流并重试）。可推广为：每个长连接都需要活性信号，而非仅依赖连接超时。完整性监控针对轨迹结构：发现工具调用缺少配对结果消息时，在注入上下文前自动修复配对，而不是把结构异常抛给模型或用户。产品模式可用占位符宽容修补，训练数据收集模式则拒绝修复——合成占位符会污染训练数据。
恢复：分级升级，逐级透明。 能用低级别解决就不升级：
工具层错误走另一条路：不终止会话，把错误变成模型的输入。 幻觉调用收到"工具不存在"的结构化错误结果；参数校验失败收到附带输入约束提示的错误；畸形参数（该是对象却输出字符串）在执行前先程序化修复。错误以普通工具结果身份进入上下文，由模型下一轮自行纠正——喂回的错误越具体，自我纠正成功率越高。
错误处理的边界不是单次请求，而是整个恢复循环。 在确认无法恢复之前，中间错误不暴露给消费者（用户或订阅事件的下游系统）：恢复期间扣留错误消息，恢复成功则消费者毫无感知，所有手段均失败后才统一呈现。
跨厂商接管：带走文字，带不走凭证。 换一家模型把轨迹接着跑完，真正的障碍不是接口地址，而是轨迹里有只属于原厂商的东西。工具调用与结果各家结构不同但语义一致，重新渲染即可；难办的是思考——它由可读文字和厂商凭证（证明这段思考出自它自己）构成，文字换一家仍读得懂，凭证换一家就失效。且凭证未必附在思考上，也可能附在工具调用上（如 Google 的 thoughtSignature），所以"把思考删干净就安全"反而会在严格校验的厂商处失败。接管方案按最严格的一端设计：把历史工具调用改写成文字叙述，模型不再当作真正调用过，但至少能接着跑。由此得到设计原则：轨迹按中立格式存储——思考拆成可移植文字与不可移植凭证两个槽位，工具调用只记名称与参数，标识符渲染成具体请求时按目标厂商重新生成；切换时凭证一律丢弃，文字以普通内容身份带入。中立轨迹还服务于评估重放、训练样本构造、经验提取。
终止：每条恢复路径都要有上限。 恢复机制本身也可能失效：上下文压缩连续失败若干次就放弃压缩，权限分类连续失败就回退人工询问，输出接续最多固定轮数。阈值来自生产数据而非拍脑袋——Claude Code 的"连续 3 次"压缩熔断阈值来自真实会话统计（曾有会话连续失败三千余次，仅此一类无效重试每天全球浪费约 25 万次 API 调用；3 次是"绝大多数故障此前已恢复"与"继续重试基本无望"之间的经验拐点）。
死亡螺旋防护。 错误处理路径中的逻辑本身又调用 LLM，再次出错引发连锁。真实案例：上下文溢出触发"结束时自动提交代码"钩子，钩子调 LLM 生成 commit message 再次溢出，又一次触发钩子。防护两条：错误路径上禁用一切会再次调用模型的副作用逻辑（宁可丢掉自动记忆提取之类的辅助功能），以及用递归深度计数器检测并打断残余连锁。最后叠加全局终止条件：最大迭代轮数、会话预算上限、连续失败超阈值升级人工。
流式中断的三个断点、三种恢复方式。 断点可能出现在：思考中途、正文中途、工具调用参数中途。恢复方式：① 丢弃半截内容整轮重发（最贵但最稳）；② 把半截内容作为末尾 assistant 消息要求模型接着写（部分厂商原生支持，其余需显式标注待续写消息，没有该接口则退回下一种）；③ 追加一条元指令说明从断点继续。注意：半截的工具调用无法以原生结构回传，需先转成文字再让模型补完，拼接后重新解析校验；若半截输出里已有工具因流式提前执行，续写前按调用指纹去重，避免重复副作用；拼接处容易多出空白或重复字符——参数合法不等于语义正确。
建一张错误 → 策略映射表（比"出错就重试"的根本改进）：
流式恢复实现清单：记录断点类型（思考/正文/参数）；半截工具调用转文字 + 指纹去重；拼接后重新解析校验参数；对比三种方式的 token 成本与恢复成功率，选默认路径。
接管实现清单：轨迹存中立格式（文字/凭证分离）；渲染层按目标厂商重组；凭证一律丢弃；遇强制凭证校验的厂商，历史调用改写为文字叙述；切换后监控重复调用指纹。
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 工程：模型之外的竞争力」（纠正机制与"不暴露中间态"原则）まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
为 Agent 建立或改进评估体系时使用——设计评估指标（Pass@k/Pass^k/成本）、搭建可重复运行的评估环境、选择确定性验证器或 LLM-as-a-Judge 及各自适用边界、编写 Rubric、做失败归因与回归任务、评估驱动的模型选型、判断统计显著性、建设可观测性与内部评估基础设施（消融、AB 测试、特性开关、提示词回归）、从 Benchmark 报告走到系统改进。
日本語の概要は準備中です。原文の説明を表示しています。
让 Agent 从运行经验中持续学习、构建自进化闭环时使用——涵盖从运行轨迹提取学习信号（三层轨迹验证）、四种进化方式（经验知识库、Prompt/Skill、程序/Harness、模型参数）的适用边界与选择依据、Prompt 自动优化、轨迹编译为程序、Agent 自我修改与安全门禁、睡眠学习与长期分层评估。触发词：持续进化、自进化、经验学习、轨迹验证器、自我修改、进化闭环。
日本語の概要は準備中です。原文の説明を表示しています。
Agent 陷入无限循环、数不清工具调用次数、遗忘 TODO 或目标偏离、长任务中思考 token 持续膨胀时使用——Agent 状态栏机制、作为 user 消息注入末尾的 KV Cache 理由、每轮替换与持久追加两种实现及成本模型、五种状态栏技术（时间戳、工具计数器、TODO、详细错误、系统状态）与维护铁律。
日本語の概要は準備中です。原文の説明を表示しています。
中文文案去「AI 味」检查清单，由用户纠正反馈持续提炼而来
日本語の概要は準備中です。原文の説明を表示しています。
构建异步/事件驱动 Agent，或让 Agent 响应外部事件（新邮件、webhook 回调、IM 消息、定时器、系统告警）、 处理工具执行期间的用户打断与多任务并发时使用。覆盖事件循环与安全点、三类事件触发工具、用户沟通与多渠道召回、 虚拟身份与隔离执行环境、队列式/取消式/并行式三种事件处理策略及紧急度判定，以及模型原生异步与同步接口兼容两条路线。 触发词：异步 Agent、事件驱动、event-driven、webhook、定时器、心跳、任务句柄、打断、steering、并行工具执行。
日本語の概要は準備中です。原文の説明を表示しています。
把生产 bad case / 失败轨迹转成训练数据时使用——从失败归因、轨迹前缀截取、DPO 偏好对构造、LoRA 训练到边界集与保留集双集验证的完整链路；也用于判断某类问题该走 SFT、DPO、RL 还是先修 Harness/工具/tokenizer，以及如何从运行轨迹中提取带证据的结构化学习信号。触发词：bad case、失败归因、DPO、偏好对、轨迹前缀、拒绝采样、过度矫正、边界集、保留集、过早结束、reward hacking、LoRA 微调、训练评估隔离。
日本語の概要は準備中です。原文の説明を表示しています。