① 五步 SOP 全景
从「看着坏了」到「定位根因、修复并防复发」，一条标准化流水线。
① 复现
钉版本+temperature=0 同例跑 3 次
→
② 缩小范围
Trace 结构五层还原 session→raw
→
③ 逐层定位
输入→检索→工具→模型→编排
→
④ 修复
最便宜层 · 一轮只改一项
→
⑤ 回归+护栏
配对检验 + 入回归集防复发
核心：Agent 是「黑盒 + 多环节 + 非确定」，排障不是看模型输出猜，也不是"固定输入必然固定复现"，而是钉住版本基线、按固定顺序逐层隔离变量，把问题从「玄学」变成「可定位」。归因类别固定（模型能力/提示词与上下文/工具 schema/知识与数据/编排逻辑/环境依赖），才能按周聚合出"哪一类问题最值得修"。
② 五类故障速查
先分诊：Agent 故障不外乎五类，先判类型再排障。
| 故障类型 | 典型症状 | 首查方向 |
|---|
| 质量下降 | 输出变差但能跑 | Prompt 版本 / 数据漂移 |
| 工具失败 | 调用报错 / 返回异常 | 工具参数 / 权限 / 服务 |
| 幻觉 | 编造事实 / 张冠李戴 | 检索质量 / 来源标注 |
| 性能退化 | 变慢 / 卡住 / 超时 | 上下文膨胀 / 循环 |
| 行为漂移 | 越跑越偏 | 记忆污染 / 自进化失控 |
③ 第 1 步 · 复现：钉基线，同例跑 3 次
Agent 是非确定系统——"固定输入必然固定复现"根本不可操作。复现的正确做法：钉住版本基线，同例重跑多次。
复现基线：固定 model 版本 + prompt_hash + temperature=0，同一用例跑 3 次取中位数——3 次里出现同一偏离（如 3 次 2 次答对且命中约束）才判"可复现"进入定位；否则按偶发样本继续观察，不动代码。
复现核对单（四项对齐才有资格谈"定位根因"）：
• 模型版本一致？（model@版本——厂商可能静默升级权重）
• prompt_hash 一致？（把一次输出对应回那一版提示词）
• context_ref 能取回当时喂进去的上下文快照？（截断点在哪一目了然）
• temperature=0，同例 ×3 取中位数
④ 第 2 步 · 缩小范围：Trace 结构还原五层
"答错了"要先变成"第几步、看了什么、调了什么"，靠的是每条会话都能下钻五层结构。
session→
turn→
step→
tool call→
raw request/response
缺任何一层，"答错了"就退化成"感觉不对"：session 关联一段连续交互，turn 定位第几轮，step 定位第几步决策（decision），tool call 看调了什么工具、status 与 error_class，raw 冷存储快照看当时真正喂进去什么（context_ref）。
为什么分层存：raw 全文动辄数万 token，不可能全量进热存储——热层留摘要与指纹、冷层留全文，异常轨迹全量保留，才撑得起"48 小时后还能取到当时的上下文快照"。
⑤ 第 3 步 · 逐层定位：输入 → 检索 → 工具 → 模型 → 编排
按固定顺序逐层排除——次序不是偏好，是失败的伪装方式决定的。
① 输入：看 prompt_hash 与该版预期是否一致、问题是否被截断/改写/带错上下文 → 排除「喂进去的就是错的」
② 检索：看 Recall@k——该召回的文档有没有召回、排序是否把正确文档压下去 → 排除「召不回 / 召回了被埋没」
③ 工具：看 tool span 的 status 与 error_class、参数是否过 Schema、超时还是业务失败 → 排除「执行链断了」
④ 模型：前三层都干净，再看给定上下文下输出是否合理（钉版本重跑 3 次）→ 这时才有资格归因模型
⑤ 编排：看分支命中、循环次数、终止原因（decision/stop_reason）→ 排除「走错分支 / 提前结束」
为什么是这个次序：越靠前的环节失败，越会伪装成靠后环节的失败——检索没召回时，模型的「编造」只是拿错误材料作答；反过来从模型查起，会把上游问题当模型能力问题去调。归因记录必须写明「模型层为何被排除」，否则下次故障仍先怀疑模型。
⑥ 第 4 步 · 修复：从最便宜层动手，一轮只改一项
定位到层之后，修复按成本排序：改截断/检索策略的成本远低于动模型；一轮实验只改一项，否则不知道是什么起了作用。
| 修复类型 | 例子 | 验证方式 |
|---|
| 提示词/上下文 | 补边界条件、改工具描述、调截断策略 | 离线评测集 + 灰度对比 |
| 工具/数据 | 修 Schema、补知识、加校验 | 单测 + 端到端回放 |
| 编排/代码 | 改分支、加终止条件 | 回归测试 + 线上观察 |
修复清单（速查）：工具选错→换工具+校验类型；参数错→补 Schema 校验；死循环→加步数/预算上限；超时→返回「Timed out, try smaller scope」；幻觉→强制标注来源+domain_facts 加 TTL。被评分的必须是新生成的回答与新轨迹，不能拿旧输出验证新修复。
⑦ 第 5 步 · 回归+护栏 + 排障工具箱
排障工具箱
- Langfuse Trace：按 session→turn→step→tool→raw 五层下钻
- prompt_hash 比对：把输出对应回那一版提示词
- 检索抽查：按 context_ref 取快照，直接看喂给模型的 chunk
- error_class 聚合：按失败类型看本周 Top 5 占比，不做个案分析
- LLM 原始输出：绕过框架看裸输出
- Checkpoint 回放：钉版本重放事故现场
修复后护栏
- 回归：每例跑 3 次取中位数，与基线配对检验 p<0.05 才算"修好了"
- P95 延迟 / 成本 / 安全拦截率护栏不退化
- 加监控：该环节补可观测字段与告警
- 防复发：错误样本写清输入、期望约束、失败层后进回归集——用例只增不删，删除等于允许复发
一句话：排障不是「猜模型」，是「隔离变量」——钉版本基线复现（model+prompt_hash+temperature=0 跑 3 次）、沿 Trace 结构五层缩小范围、按 输入→检索→工具→模型→编排 逐层定位、从最便宜层修复且一轮只改一项、最后以回归护栏收尾，让每次事故 48 小时内变成一条用例。