LangChain / LangGraph 生产检查清单

适用 LangChain v1.x、LangGraph 1.x。每条都可勾选，括号内是默认值或判断依据。只列“不做会出事”的动作，机制解释见各篇正文。

上线前

[ ] 版本锁定：langchain、langchain-core、langgraph、厂商适配包写入 lock 文件，不用浮动版本。
[ ] 超时与循环上限：单次模型调用、单次工具调用、整次 run 三层超时；ModelCallLimitMiddleware + ToolCallLimitMiddleware 都配置，LangGraph 另设 recursion_limit（默认 25）。
[ ] 上下文预算：配置摘要或裁剪策略，明确触发阈值与保留条数；不要等模型报超长。
[ ] 状态外部化：生产用 PostgresSaver/AsyncPostgresSaver，setup() 放进迁移脚本，多副本共享同一库；thread_id 稳定、唯一、长度 <255，多租户带前缀并在入口校验归属。
[ ] 评测与追踪：评测集覆盖检索、工具选择、最终答案、安全四类，发版前跑回归；模型与工具调用是独立 span，trace 中不落密钥、手机号、身份证原文。
[ ] 安全、成本与降级：工具最小权限，写操作带幂等键，代码执行进沙箱，危险操作走人工审批；按用户/租户限流并估算单请求 token 与费用；主模型失败切备用，备用失败返回可解释错误；thread、store namespace、向量库过滤三处都按租户隔离并有越权测试。

[ ] 核心面板：run 成功率、P50/P99 延迟、每 run 模型调用次数、token 与费用、工具错误率。
[ ] 上限与重试：因 run_limit/recursion_limit 退出的比例、fallback 触发率、429 比例、重试成功率；重试暴涨先查下游限流。
[ ] 挂起与存储：interrupt 待审批数量与等待时长，超 SLA 告警；checkpoint 表大小、store 条目数、单 thread 的 checkpoint 数按策略归档或删除。
[ ] 版本可追溯：每次 run 记录 prompt 版本、模型 ID、工具版本、图版本，便于回滚与对比。
[ ] 抽样复盘：每周抽 trace 看工具入参、上下文拼接、引用是否合理，不只依赖自动指标。

先过两道门：trace 能不能打开、末端是什么形态。trace 不通先修可观测，通了再按末端形态选分支。

形态判错，后面要查的字段就都查偏；完整分支见下图。

排查按列读：第一列判形态，第二列分错误类型或环节，第三列才是具体查什么。六条 R 分支的差别在于第一眼看的是模型、工具、检索还是轨迹，先落到分支再调参。

[ ] Agent 反复调同一个工具 → 看 trace 中的 tool_calls → 检查工具返回值是否为空/报错 → 修工具或加循环上限。
[ ] 上下文溢出 → 看 token 曲线 → 确认摘要是否生效 → 降低检索条数/工具返回长度。
[ ] 恢复失败或状态错乱 → 核对 thread_id、checkpoint 是否存在、图结构/节点名是否改过；跨版本恢复先做兼容验证。
[ ] 费用、工具与注入异常 → 费用突增按租户拆 token，查并行扇出、长上下文、重试次数，先限流再优化；工具超时看下游依赖与连接池，熔断并启用降级；疑似提示注入先定位不可信输入来源，收紧工具权限与出参校验，不能只改 system prompt；审批卡住查待处理队列与通知渠道，补超时关闭或升级策略。

适用：LangChain v1.x / LangGraph 1.x | 初稿 2026-10