LangChain 学习手册
核对日期：2026-05-18
定位：面向工程师的 LangChain v1 TypeScript 学习系统，包含文档、离线可运行案例、三个综合项目和本地 eval。
官方资料：以 LangChain Docs 为主，入口为 https://docs.langchain.com/oss/javascript/langchain/overview 和 https://docs.langchain.com/oss/python/langchain/overview。
1. 学习目标
本手册不是 LangChain API 摘抄，而是把官方能力映射到工程任务：
| 阶段 | 目标 | 对应产物 |
|---|---|---|
| 基础接口 | 理解 chat model、messages、tools、structured output | docs/01-* 到 docs/03-*、src/examples/01-* 到 04-* |
| Agent 能力 | 理解 Agent loop、middleware、runtime、context engineering | docs/02-*、docs/06-*、src/examples/03-* |
| 知识系统 | 理解 RAG、memory、ACL、citation、eval | docs/04-*、docs/05-*、企业知识库项目 |
| 生产闭环 | 理解 guardrails、HITL、MCP、streaming、LangSmith、上线验收 | docs/07-*、docs/08-*、多工具任务 Agent |
| 真实落地 | 把离线 demo 替换成官方 LangChain 包、接真实 provider、加 CI gate | docs/11-* 到 docs/16-* |
2. 运行方式
cd /Users/luhanguo/Desktop/AI/LangChain学习手册
npm install
npm run typecheck
npm test
npm run examples
npm run projects:eval
npm run docs:check
默认运行离线 mock runtime，不需要 API Key。需要连接真实模型时，复制 .env.example 为 .env，再按官方 provider 文档安装对应集成包。
3. 目录结构
LangChain学习手册/
docs/ # 分章学习文档
src/core/ # 离线 runtime、RAG、memory、eval 公共模块
src/examples/ # 递进式小案例
src/projects/ # 三个综合项目
test/ # Node test 回归测试
4. 机制总览
LangChain v1 的核心不是“替你做智能”，而是把模型、工具、上下文、结构化输出、状态、观测连接成可组合的应用层接口。复杂 Agent 的持久化、恢复、人类审批和多步状态管理通常会进入 LangGraph 底座；LangChain 更适合做应用开发层和集成层。
5. TypeScript 主线
本仓库的代码用 TypeScript 主线实现，原因是：
- 前端和全栈工程更容易把 LangChain 接到 API route、worker、BFF 或内部工具台。
zodschema 可以同时服务 tool input、structured output 和测试断言。- 所有示例默认严格类型，避免裸
any和隐式数据形状。
离线 runtime 中的 createAgent、tool、runtime context 是学习用最小实现，不冒充官方包；真实项目应回到官方 langchain、@langchain/* 集成包。
6. Python 差异
Python 官方文档通常是 LangChain 新能力最完整的说明线之一；TypeScript 文档也有独立入口。学习时建议：
- 机制先读 Python 和 JS/TS 两边 overview，确认概念是否一致。
- API 以目标语言官方文档为准，不用 Python 参数名硬套 TypeScript。
- 生产项目锁定包版本，并保存文档核对日期。
7. 三个综合项目
| 项目 | 覆盖能力 | 运行验证 |
|---|---|---|
| 企业知识库 Agent | RAG、ACL、citation、结构化答案、冲突文档、安全拒答、eval | npm run projects:eval |
| 个人学习助手 | 长期记忆、学习计划、用户画像、复习记录 | npm run projects:eval |
| 多工具任务 Agent | 动态工具暴露、审批、重试、审计日志 | npm run projects:eval |
8. 可用化文档索引
如果目标是“照着做功能”，优先读这些文档：
| 文档 | 解决的问题 |
|---|---|
| 11. 真实 LangChain 接入指南 | 如何从本地 mock 迁移到官方 langchain / provider 包 |
| 12. 企业知识库 Agent 实战任务书 | 如何把 RAG、ACL、citation、eval 做成完整功能 |
| 13. 个人学习助手实战任务书 | 如何实现长期记忆、学习计划和复习提醒 |
| 14. 多工具任务 Agent 实战任务书 | 如何做动态工具、审批、重试和审计 |
| 15. 故障排查与反模式手册 | 工具不调用、schema 失败、RAG 胡答、trace 泄露怎么排查 |
| 16. 代码案例索引与改造练习 | 每个 example 要改哪里、加什么测试、怎样验收 |
| 17. 官方核心组件全景 | 官方 v1 核心组件、middleware、高阶模块的总图 |
| 18. Models / Messages / Streaming 官方深读 | 模型接口、消息结构、invoke/stream/batch、event streaming |
| 19. Agents / Tools / Structured Output 官方深读 | Agent runtime、动态模型/工具、工具返回、结构化输出策略 |
| 20. Memory / Retrieval / Context 官方深读 | 短期记忆、长期记忆、RAG、context engineering |
| 21. Middleware / Runtime / Guardrails / HITL 官方深读 | middleware 生命周期、runtime context、安全护栏、人类审批 |
| 22. 官方 API 与参数语义手册 | createAgent、model、tool、runtime、streaming、memory 的参数语义 |
| 23. 高阶组合 Recipes | 动态模型、动态工具、RAG+结构化输出、HITL、MCP、LangSmith 等组合模式 |
| 24. Workbench 源码对照学习 | 把官方概念映射到 ../LangChain/ 参考实现 |
| 25. 官方核对索引与学习验收 | 官方资料核对路径、学习深度验收、章节补全路线 |
9. 常见反模式
| 反模式 | 问题 |
|---|---|
| 只照抄 quickstart | 缺少权限、失败路径、eval 和 trace，很难上线 |
| 把 RAG 当搜索框 | 没有 ACL、引用、召回评测和冲突处理，答案不可审计 |
| Agent 直接连生产 API | 缺少 Tool Gateway、审批、幂等和审计 |
| 只看 happy path | schema 失败、工具超时、模型拒答、provider 差异都会在线上出现 |
10. 官方资料
- LangChain JS overview: https://docs.langchain.com/oss/javascript/langchain/overview
- LangChain Python overview: https://docs.langchain.com/oss/python/langchain/overview
- Agents: https://docs.langchain.com/oss/javascript/langchain/agents
- Tools: https://docs.langchain.com/oss/javascript/langchain/tools
- Structured output: https://docs.langchain.com/oss/javascript/langchain/structured-output
- Short-term memory: https://docs.langchain.com/oss/javascript/langchain/short-term-memory
- Long-term memory: https://docs.langchain.com/oss/javascript/langchain/long-term-memory
- Retrieval: https://docs.langchain.com/oss/javascript/langchain/retrieval
- Middleware: https://docs.langchain.com/oss/javascript/langchain/middleware
- Runtime: https://docs.langchain.com/oss/javascript/langchain/runtime
- Guardrails: https://docs.langchain.com/oss/javascript/langchain/guardrails
- Human-in-the-loop: https://docs.langchain.com/oss/javascript/langchain/human-in-the-loop
- MCP: https://docs.langchain.com/oss/javascript/langchain/mcp
- LangSmith observability: https://docs.langchain.com/langsmith/observability-quickstart
核对日期：2026-05-18。