排错实战：从坏轨迹到根因的定位工作流
前置知识
一句话定义
多智能体排错的工作流是：固化复现 → 沿轨迹倒推 → 对照失败分类 → 分层定位（单智能体/交接/编排/共享状态）→ 二分实验锁定根因 → 修复 → 回归验证；核心手法是「用理想中间产物做替换实验」，把开放问题切成可判定的上游/下游问题。
直观类比
水管漏水：先关阀复现（固化），从水渍倒着找管线（读轨迹），对照管网图判断是哪一段（分类定位），然后逐段拆开试压（二分实验）——而不是把整栋楼的水管全换掉（盲目改提示词）。
为什么重要
单 Agent 排错看一条对话即可；多智能体的失败分散在多个智能体、多次交接与共享状态里，且常是复合失败（kp-020），「从头到尾读一遍」既贵又无效。没有结构化流程的团队最常见的浪费是：凭感觉改提示词 → 换个地方坏 → 循环往复。本知识点把 kp-018 的重放、kp-020 的分类表、kp-025 的 trace 织成一条可执行的定位流水线。
前置知识
kp-020（七类失败对照表——本工作流的诊断字典）；kp-018（重放——二分实验的执行机制）。
核心概念：七步工作流
- 固化复现：固定输入与种子（温度归零或固定采样参数），保存完整 trace 与检查点（kp-018），确保失败可重复触发；
- 倒推读轨迹：从最终错误出发问「它引用了谁的产物」，逐跳向上游走，直到找到第一个「产物本身不合格但被下游照单全收」的交接点——那是嫌疑最大处；
- 对照分类：用 kp-020 的对照表给失败贴类型标签（级联/循环/漂移/幻觉扩散/角色失效/资源失控/死锁），类型决定首查位置；
- 分层定位：按四层逐一排除——单智能体内（角色卡/提示问题）、交接（交接包字段缺失）、编排（路由/终止条件错误）、共享状态（竞态/黑板污染）；
- 二分实验：把嫌疑节点的输入替换为「理想值」（手工构造的正确产物），从该检查点重放下游（kp-018 时间旅行）：下游恢复 → 根因在上游；下游依旧坏 → 根因在下游或编排。对半切，两三轮锁定到单节点；
- 修复：按根因选择手段——角色卡契约（kp-005）、交接包补字段（kp-012）、加防护栏（kp-022）、改编排（kp-017）；避免「顺手改提示词」这种未定位先修复；
- 回归验证：把该失败加入回归测试集（固定输入 + 期望断言），确认修复且未引入新失败。
症状 → 根因 → 首查动作速查表
| 症状 | 最可能根因 | 首查动作 |
|---|---|---|
| 产物格式错乱 | 输出契约缺失或示例不足 | 查角色卡 schema 与示例（kp-005） |
| 下游「自信地胡说」 | 交接包缺验收标准/上下文摘要 | 查交接点字段完整性（kp-012） |
| 同一产物被反复修改 | 收敛判定权缺失、无轮数上限 | 查图循环出口与仲裁者（kp-008/kp-017） |
| 结论与任务无关 | 验收标准被上下文压缩丢弃 | 查上下文快照中目标的位置（kp-015） |
| 偶发字段互相覆盖 | 共享 State 竞态 | 查字段所有权与 reducer（kp-019） |
| 费用莫名翻倍 | 隐藏重试循环/僵尸分支 | 查 trace 中重复调用簇与取消传播（kp-025） |
原理与机制
工作流有效的原因是把「开放性失败」转化为「可判定实验」：替换实验天然构成对根因位置的二分判定——每次实验把嫌疑空间减半，与 KP-021 的思想同源（用可控干预代替整体重试）。固化复现是前提：多智能体的非确定性会让「看一眼就没了」的失败永远无法归因；温度、检索快照、时间相关的输入都要钉住。回归集是闭环的关键：多智能体系统改动一处常牵动全链，无回归集的修复等于掷骰子。
实例或案例
故障：交付报告的第三部分与数据对不上。执行工作流——固化输入重跑，失败复现（第 1 步）；倒推发现第三部分引用了分析产物 A7，而 A7 的数字在黑板中被二次覆盖（第 2–3 步，怀疑共享状态层）；从 A7 写入前的检查点重放下游，下游恢复正确（第 5 步二分）——锁定为分析智能体与补充检索工人对同一字段的竞态写；修复：字段所有权拆分 + reducer 改追加（第 6 步）；该场景入回归集（第 7 步）。
公式或模型
二分定位的收敛性：设根因所在节点均匀分布于 L 个候选节点，每次替换实验区分「上游/下游」可将候选减半，期望实验次数 ⌈log₂L⌉——L = 16 时仅需 4 次实验，远低于逐节点排查的 L/2 = 8 次，且每次实验只重放部分图，成本递减。
常见误区
- 误区一：未固化就开修。 不可复现的失败无法验证修复，先钉住输入与快照；
- 误区二：修最后一个症状。 复合失败必须沿轨迹找第一因，否则错误换个马甲再来；
- 误区三：只改提示词。 提示词是最后的手段——结构问题（交接、编排、竞态）改提示词等于在错误的地基上刷漆。
与其他知识点的关系
重放与检查点是执行手段（kp-018）；trace 与重复调用检测是观察手段（kp-025）；分类表是诊断字典（kp-020）；修复手段分别对应 kp-005/kp-012/kp-017/kp-022。
自测题
- 七步工作流的顺序？哪一步是核心手法？
要点：固化复现→倒推→分类→分层定位→二分实验→修复→回归；核心是「理想中间产物替换 + 检查点重放」的二分实验。
- 替换实验的判定逻辑？
要点：换入理想产物后下游恢复→根因在上游；依旧坏→根因在下游或编排，候选空间每次减半。
- 为什么「只改提示词」常是错误修复？
要点：交接、编排、竞态类根因是结构问题，提示词修改不触碰结构且引入新的不可控行为。
延伸阅读
MAST 论文附带的失败案例库可作为排错练习材料；各框架的 trace 查看器（kp-025）是执行本工作流的日常工具。