15-故障排查与反模式手册
核对日期：2026-05-18
官方资料：Agents https://docs.langchain.com/oss/javascript/langchain/agents；Guardrails https://docs.langchain.com/oss/javascript/langchain/guardrails；LangSmith observability https://docs.langchain.com/langsmith/observability-quickstart。
目标
本章用于排查“能跑但不好用”的 LangChain 应用。它不是概念解释，而是把常见故障映射到检查项、日志、eval 和修复方式。
机制
排查顺序：
输入 -> 上下文 -> 模型 -> 工具 -> 输出 -> trace -> eval
不要一上来改 prompt。多数线上问题来自 schema、权限、检索、上下文预算、工具失败或 provider 差异。
TypeScript 排查表
| 症状 | 优先检查 | 修复 |
|---|---|---|
| 工具不调用 | tool description、schema、动态工具列表、用户意图 | 简化工具列表，补 few-shot 或路由规则 |
| 工具误调用 | 相似工具过多、description 重叠 | 动态暴露工具，增加负例 eval |
| schema 经常失败 | 字段太多、约束不清、模型不支持 | 拆小 schema，增加 fallback |
| RAG 胡答 | 低召回、无 citation、prompt 允许猜测 | 低证据拒答，citation 强约束 |
| 权限泄露 | 检索后过滤、工具无后端鉴权 | 检索前 ACL，Tool Gateway |
| trace 有敏感信息 | 日志未脱敏 | 写 redact middleware |
| streaming 半截答案 | 错误事件没处理 | 定义 chunk/error/done 协议 |
Debug Checklist
- 保存一条失败输入，不要只口头描述。
- 打印实际 messages，不只看 UI。
- 打印最终暴露给模型的 tools。
- 打印 tool call input 和 schema error。
- 打印 retrieved document ids 和 citations。
- 确认 trace 脱敏。
- 把失败样本加入 eval。
Python 差异
Python 和 TypeScript 的排查思想一致。区别是 tracing 接入、回调、中间件和 schema 错误对象形状不同。跨语言项目要把失败样本抽成 JSON case，而不是只保留某个语言的测试。
常见反模式
| 反模式 | 后果 |
|---|---|
| 只调 prompt | 问题可能在工具、检索或权限 |
| 不保存失败样本 | 下次还会复现但没人知道原因 |
| 线上临时热改 schema | 前端和下游解析崩掉 |
| trace 不脱敏 | 调试系统变成安全风险 |
故障复盘模板
## 现象
## 失败输入
## 实际 messages / tools / retrieved docs
## 根因分类
## 修复
## 新增 eval
## 回归结果
练习任务
- 故意把
enterprise-kb-agent.ts的minScore调低，观察 ACL deny 是否仍通过。 - 给
multi-tool-task-agent.ts增加相似工具，设计误调用 eval。 - 给 docs check 增加“每个文档必须有练习任务”的规则。