00-学习路线与官方对齐

核对日期：2026-05-18
官方资料：LangChain JS overview https://docs.langchain.com/oss/javascript/langchain/overview；Python overview https://docs.langchain.com/oss/python/langchain/overview。

官方概念

LangChain v1 把 LLM 应用拆成 model、messages、tools、agents、structured output、memory、retrieval、middleware、runtime 和 observability 等模块。官方文档还把复杂 Agent 的状态化执行与 LangGraph 关联起来，因此学习 LangChain 不能只停在 prompt template。

机制

学习顺序应该先模型调用，再工具和结构化输出，然后进入 Agent loop、RAG、memory、middleware、guardrails 和 LangSmith。原因很简单：Agent 的大多数线上问题不是“模型不会回答”，而是上下文不完整、工具边界不清、输出不可解析、权限没拦住、失败不可观测。

TypeScript 写法

TypeScript 主线建议把 schema 当成工程契约：

import { z } from "zod";

const answerSchema = z.object({
  answer: z.string(),
  citations: z.array(z.string()),
});

本手册的 src/core/agent-runtime.ts 用离线实现模拟 createAgent、tool、runtime context 和 trace，帮助你在没有 API Key 时理解流程。

Python 差异

Python 文档和示例常用 create_agent、函数工具和 checkpointer/store；TypeScript 通常使用 camelCase API 与 zod schema。概念一致时可以对照学习，参数名、包名和 provider 初始化方式必须以目标语言官方文档为准。

工程边界

• LangChain 适合做应用集成层，不等于生产工作流平台。
• 长事务、暂停恢复、人工审批、多分支状态机应优先考虑 LangGraph。
• 任何 RAG/Agent 系统都需要 eval，不应只用人工试聊验收。

常见反模式

反模式	后果
只学 quickstart	会调用模型，但不会处理权限、观测和失败
先上 Agent 再补工具治理	工具误调用和越权成本很高
不锁版本	LangChain 与 provider 集成变化会影响线上行为

练习任务

1. 运行 npm run examples，记录每个 example 对应的官方章节。
2. 运行 npm run projects:eval，观察三类项目的验收断言。
3. 把一个 eval case 改成失败，确认脚本会退出非 0。