29｜故障诊断手册：从现象到最小有效修复

目标：面对失败不立即换模型或叠加规则，而是提出竞争解释、寻找区分证据并修复正确层。案例为作者构造，不是用户仓库已确认事故。

继续看相关机制：F29 · 从两个候选列表，走到可用证据F22 · 把一个Agent任务拆成真正发生的几轮F34 · 测试是找反例，不是给代码盖绿章

案例一：Skill显示加载，但代码仍不专业

观察：日志有技能名称，输出却未处理事务超时。竞争解释包括：只加载了元数据；正文被裁剪；子Agent未得到内容；正文根本没有有效专业知识；模型看到但未应用；测试没有要求该行为。

最小排查先看实际加载范围与正文，再看执行轨迹中是否涉及相应风险，最后用能触发该错误的任务验证。不应第一步增加一个路由Agent，因为选择可能已经正确。修复可能只是补一条具体事务边界知识与对应测试。

回归同时包含需要事务处理与无关任务，防止把所有任务都升级成分布式系统分析。验收是错误行为减少，而不是回答更频繁提到“事务”。

案例二：压缩后工作方向改变

观察：原要求只改description，压缩后开始重构执行器。竞争解释：负约束丢失、假设升级、旧记忆覆盖、新用户输入未进入、子任务说明截断。

取压缩前后任务状态，检查“不能改什么”是否保留；比较下游委派说明与当前权威目标。若宿主压缩不可读，用相同前缀分叉继续执行，测试具体约束。修复优先持久化少量关键约束与证据入口，不必默认自建第二套全历史摘要服务。

回归应包含多次压缩与新的目标变更，避免系统过度固定旧约束，反而不能遵循用户后来授权的变化。保真不是永远不变，而是正确保留时间与权威。

案例三：检索结果相关，却总是旧版本

观察：回答术语正确，但API字段已废弃。可能是索引未更新、向量语义偏爱旧长文、缓存键没有版本、重排未使用时间范围或生成阶段混合旧证据。

沿管线检查当前文档是否入库、候选是否包含、过滤后是否保留、排序/选择是否丢弃、最终引用是否对应。修复点可能是索引代次与版本过滤，而不是更换Embedding模型。

回归加入同名不同版本、回滚场景和历史查询。不能简单永远选择时间最新的一条，因为用户可能问旧版本迁移原因。第15章有效时间与知晓时间帮助区分这些需求。

案例四：测试全绿，用户仍发现问题

可能原因包括测试根本没运行、关键项被跳过、测试被模型弱化、测试版本陈旧、新要求未覆盖、环境与生产不同。首先读取实际命令、数量、退出码和工件版本，不能只读模型总结。

修复应针对原因：空测试集设置明确失败；新要求补断言；验证绑定当前版本；高风险测试资源隔离。不要机械再加三轮自然语言Review，因为它们可能重复相信同一份错误绿色报告。

回归故意修改测试后文件、删除关键断言、制造超时，观察系统是否仍会宣布成功。第27章已实测其中的陈旧验证拒绝。

案例五：任务越来越慢，Token越来越多

先分解模型、工具、排队、检索、压缩与Review耗时。可能是多Agent重复读相同文件、技能默认全加载、输出冗长、失败重试、模型强度过高或外部工具慢。

一个针对性修复是让研究子任务返回精确证据入口，主Agent不再重复全库发现；另一个是移除对小问题重复重设计的流程。只有证明成本下降且专业质量不退化，才算有效优化。减少输入但提高失败率不是成功。

回归要覆盖复杂任务，防止简单任务更快而复杂任务被过度简化。用任务成功成本而非平均Token做主要判断。

案例六：重试导致重复副作用

观察：网络超时后出现两个工单。根因可能是每次重试生成新操作ID，或远程服务不支持幂等而客户端把unknown当失败。修复需要业务幂等/对账，不是把Prompt写成“不要重复”。

测试应在“远程已成功但客户端未收到”窗口断开，而不仅模拟调用前报错。本书本地文件崩溃实验验证类似窗口，但远程业务还需要相应服务能力，不能直接套用文件哈希。

案例七：记忆越多，错误越稳定

观察：系统坚持旧经验，即使当前代码相反。检查记忆的来源、版本、作用域、写入权限和检索优先级。一次猜测被自动保存为active，可能在多次摘要中逐渐变成“已验证规则”。

修复先清理错误权威与适用边界，再评价写入策略。必要时减少记忆，而不是增加更复杂图结构。回归包含新证据推翻旧结论、权限撤回、相互冲突与无匹配场景；系统应能不使用记忆。

统一诊断方法

把现象、竞争解释、区分证据、最小修复和回归样本放在一起。每次额外读取应减少一个重要不确定性；每项代码改动应对应真实失败。没有这些联系的“全面优化”很容易扩大系统而没有提升能力。

确定性Bug用测试修，信息缺口用检索补，专业缺口用知识补，执行缺口用Harness修，能力上限才考虑模型或训练。顺序不是绝对规则，但能避免把一切归咎于模型不够聪明。