排障与迁移：旧教程、旧项目与报错
网上多数 LangChain 教程写于 0.1 到 0.3 时期，照着在 v1 上运行，常常第一行就报错。先判断你面对的是旧教程、旧项目，还是一行具体报错，再按对应方法处理。
你手上的问题属于哪一类
| 症状 | 从这里开始 |
|---|---|
| 照着旧教程敲代码，第一行 import 就报错 | 旧教程对照与报错速查 |
升级 langchain 之后出现 ModuleNotFoundError | 导入兼容矩阵，再按迁移 Runbook操作 |
项目里还在用 AgentExecutor、LLMChain | 迁移 Runbook |
旧的 RetrievalQA 要迁到 LCEL | RetrievalQA 与 LLMChain 迁移到 LCEL |
| 对话历史丢了，或者不同用户的会话串线 | 对话记忆迁移 |
| 手里只有一行报错原文 | 生产故障速查 |
| 模型给工具传错了参数，或者工具抛异常后 Agent 的行为不符合预期 | 工具调用 schema 排障 |
旧项目升级到 v1
从旧教程的写法出发，一步步升级到 v1，并且每一步都留好回滚点。
- 旧教程在 LangChain v1 跑不通？新旧写法对照与报错速查
对着旧教程，把 import、调用方式和参数名逐条换成 v1 写法。
- LangChain 导入兼容矩阵：0.3.27 与 1.4.7 下 36 个常用符号的可用性
找出代码里不能再直接导入的符号，并查到各自的迁移目标。
- LangChain 从 v0.x 升级到 v1：双轨迁移 Runbook（含回滚）
先用 langchain-classic 零行为变更地换 import，再迁到 create_agent，每一步都有可回滚的检查点。
- RetrievalQA 与 LLMChain 迁移到 LCEL：对等性与调用次数实测
迁移前后量出消息内容、返回值形状、模型调用次数和检索为空时的差异，调用方不用改。
- ConversationBufferMemory 迁移到 v1：thread_id 与历史裁剪实测
迁移对话记忆，并验证不同 thread_id 之间互相隔离、没有静默失忆。
按症状排查故障
拿报错原文对号入座，再进入对应的实验定位原因。
- LangChain 生产故障诊断：13 个已复现问题
按报错原文或症状找到条目，并跳到对应的详细实验。
- 工具调用 schema 排障：docstring、参数校验与工具异常实测
定位并修好工具 schema 与参数校验导致的调用失败。
只查一个写法或报错
只需查询某个 import 或报错时，直接使用速查。v0.1 / v0.2 的内容仅用于维护旧项目，不适合作为 v1 实现依据，保存在历史归档，只为让旧链接继续可用。