附录 C · 全链路故障排查：先取证，再改参数

⏱ 按症状查阅 ｜从数据进入系统到答案与动作落地

🎯 一句话

先找失败发生在哪一层，再决定是修数据、改参数、降级还是对账。 本手册覆盖常见故障类别；每次遇到新故障，把最小复现补回自己的回归集。

零、先保存这份现场

记录 request_id / run_id、发生时间、可信租户/用户标识、模型/提示/工具/索引版本、脱敏输入、候选与引用 ID、各阶段耗时、错误分类、用量和已发生的业务对象号。对敏感正文只保存获得授权的最小样本或摘要哈希；不记录 token、密钥和整份私有文档。

先确认有没有越权或重复业务动作；必要时暂停相应写工具、回退配置或只返回可验证证据。随后固定输入，在隔离环境复现。恢复用户服务与查清根因可以并行，但恢复操作也要可审计。

一、入库与新鲜度

症状	最先取得的证据	修复 / 调优方向	验收与回滚
上传成功但搜不到	对象版本、任务状态、已发布块数	区分上传、解析、索引三种成功	失败可回放，旧版可服务
PDF 有字却顺序错	原页与提取顺序对照	版面解析、双栏、表格边界	按版面类型抽样，保留原页
表格答案少单位	块正文、表头与脚注	保护表格/说明，父子块	数字、单位、适用条件同时出现
空白/乱码入库	编码、页面字符数、解析日志	编码修正、OCR 或人工复核	不发布空块；回放同文件
重复块越来越多	文档 ID、内容哈希、事件键	幂等入库、稳定 ID	重投后数量不增长
旧版覆盖新版	事件顺序与 revision	发布前比较版本	乱序测试，保持新版
删除后又出现	墓碑、迟到任务、缓存	阻断旧事件、清缓存	重放旧任务不能复活
更新后部分新部分旧	发布事务与索引水位	原子切换或版本一致快照	故障中旧/新版各自完整
换模型后突然变差	维度、前缀、模型/向量版本	新建完整索引，双写增量	保留旧索引，撤权仍同步

详细实验见11b。

二、查询、召回与排序

症状	最先取得的证据	修复 / 调优方向	验收与回滚
型号、错误码混淆	原 query、改写、分词、各路候选	保留精确实体、BM25 与过滤条件	相近型号难负例分组
同义问法漏召回	语种、query 前缀、截断率	embedding 配置、词典/改写对照	原始问题保留，分组 Recall
严格 ACL 后不足 K	过滤前后数量、引擎扫描参数	前置过滤/迭代扫描、候选预算	不放宽权限，测过滤选择率
ANN 漏正确近邻	同过滤条件的精确搜索	ef/nprobe、量化重评分	ANN recall 与 p95 双曲线
重排把正确证据挤走	固定候选的前后次序	语种、训练域、长度、模型选择	逐题差值，不达标退回无重排
top-K 全是同文档	文档与块 ID 分布	文档去重、多样性与合并	有效文档 Recall，防刷分
多跳问题只答一半	子问题与多 gold 标签	拆问题、多轮检索、覆盖检查	证据完整率与总调用预算
检索耗时高	编码、查库、过滤、融合分段耗时	缓存模型、批量、索引与 K	冷热/并发分开，复测质量

详细实验见11c。

三、上下文、生成与显示

症状	最先取得的证据	修复 / 调优方向	验收与回滚
候选正确，答案仍找不到	最终 prompt 的证据 ID 与实际 token	修预算、截断、去重与排序	正确证据实际进入模型
引用真实但结论错	断言与 quote、型号/日期/单位	检查语义支持与冲突	人工复核集，拒绝伪支持
没资料却答得肯定	无答案题、分数分布	澄清/拒答校准，禁止假阈值	应拒答时回答率及误拒率
引用打开已撤权内容	当前 ACL、页面缓存与原文下载	每次读重新授权、缓存失效	历史答案重开负例
输出 JSON 截断	结束原因、输出预算、原始返回	schema 约束、有限修复	缺字段不能当成功
流式首字快但不结束	首帧、终帧、取消与总耗时	超时、终止信号、代理缓冲	断流/取消后无悬挂任务
引用编号错位	chunk ID 到显示编号映射	稳定 ID、排序后重新映射	点每条引用对照正文
文档指令改变行为	外部内容、调用 trace、最终副作用	工具权限、隔离、最小上下文	泄漏与动作分别测，不能只查关键词

详细诊断见11d。

四、MCP 与身份

症状	最先取得的证据	修复 / 调优方向	验收与回滚
stdio 首次连接失败	stdout 原始行、stderr、启动路径	stdout 只留协议；解释器与 cwd 明确	真子进程 Client 连接
新宿主遇到旧握手代码	协议日期、SDK、协商记录	版本适配，区分 2025 与 2026	新旧两套独立测试
HTTP 401 / 403	audience、scope、有效期、资源元数据	修凭证签发与资源配置	缺失/过期/撤权负例
本地通、代理后失败	Content-Type、转发头、buffering	JSON/SSE、路径、超时与合法 Host	经真实代理联调，凭证不打日志
工具有结果但字段为空	outputSchema、structuredContent	明确输出模型、适配旧文本结果	类型、条数、字段断言
错误提示泄漏堆栈	对外错误与内部日志	预期 ToolError、意外错误脱敏	客户端可行动且无内部秘密
资源 URI 绕过搜索权限	resource 读取身份与 ACL	统一业务授权函数	直接读 URI 负例
重连制造第二笔动作	RPC ID 与业务操作号	新 RPC ID、原业务号、对账	响应丢失后仅一笔

HTTP session 不是身份。2026-07-28 与旧版会话机制不同，排查前先确认所用协议；不要为了“让它连上”删除权限检查。见08c。

五、Agent、审批与任务恢复

症状	最先取得的证据	修复 / 调优方向	验收与回滚
Agent 一直搜同一句	工具名称/参数序列与预算	重复检测、轮数/时间/成本边界	有明确停止原因
模型自报 approved	可信审批记录与操作者	独立审批接口、动作指纹	没有记录即拒绝
批准后参数被改	规范化前后与指纹	重新审批，禁止复用旧批准	改金额/对象/正文负例
超时不知道做没做	操作号、下游对象与审计	先对账，再决定重试	丢响应后无重复
取消后仍产生动作	取消时间与执行状态	不再排新动作，查已执行副作用	说明取消与撤销的不同
重启后任务从头跑	checkpoint 路径、thread_id	持久化、稳定 ID、节点幂等	用两个进程验证
并行节点互相覆盖	状态更新和合并规则	reducer、版本控制、任务所有权	乱序/重复/部分失败
升级后旧任务恢复失败	图版本、状态 schema、暂停点	迁移或旧 worker 兼容	新版本恢复旧待办
记忆串用户/不可删除	memory 作用域、来源、缓存	租户隔离、TTL、撤销与删除传播	跨用户与恢复后复测

详细实验见12b与16d。

六、评测、容量与发布

症状	最先取得的证据	修复 / 调优方向	验收与回滚
新版分数突然完美	判分字段、漏字段与空集	写反例：缺 sort、重复 gold、空数据	判分器先接受已知对错样本
离线好、线上差	数据划分、题型、版本与流量	排查污染、选择偏差与漂移	按时间/用户分组，保留集
裁判分数不稳定	裁判版本、顺序、rubric	人工校准、盲化、重复抽样	分歧率与人工相关性
高并发 p99 爆炸	到达率、队列、各阶段分位数	限并发、背压、批量、资源池	过载降级，无无限排队
模型 OOM	长度分布、KV/激活/参数内存	限上下文、batch、量化/并行	同负载复测质量与延迟
成本突然翻倍	token、重试、工具次数、缓存命中	归因到租户与任务，限预算	降本后质量与完成率不退化
回滚后泄漏旧数据	索引/备份水位与权限事件	同步删除撤权再切换	恢复后权限回归
日志无法定位或泄密	trace 关联、采样、字段	最小必要日志、脱敏与访问控制	能定位事故且不含凭证

指标的“好坏”来自业务目标和实测基线，表格没有通用阈值。线上变更先固定旧配置与回滚路径，再做影子/小流量对照；发生越权、重复动作等硬约束失败，即使平均任务分数上升也不能接受。

✅ 检查点

遇到一个新故障，用五句话写清：触发输入、可观察症状、最早偏离预期的层、最小修复、能够阻止复发的反例。修复后复跑相邻边界，保留不确定点与复查条件。

看一个例子

用户问 XR-200，答案给出 XR-300 功率。原 query 正确；检索候选有两型号，正确文档排第二；引用真实但不支持用户型号。修复时先测实体匹配与排序，再验证答案断言；回归加入相近型号、同义问法和无答案型号，不能只改这一句提示。

🛑 查到对应层就回正文实践，不必从头背完整张手册。

⚡ 走神救援

保留现场，找到最早偏离预期的层；修复有对照，恢复有边界，新故障变成回归样本。

🔗 接下来去哪

➡️ 返回：企业知识助手交付项目。

打卡记录保存在你的浏览器里，首页能看到总进度