跳到主要内容

25-官方核对索引与学习验收

核对日期：2026-05-18
官方资料：LangChain Docs https://docs.langchain.com/；LangSmith Docs https://docs.langchain.com/langsmith/。

官方概念​

LangChain 更新快，学习资料必须区分三类：官方稳定概念、快速变化 API、工程自定义实践。本章给出核对索引和学习验收标准，避免文档越写越厚但仍然不可用。

机制​

学习 LangChain 的完成标准不是“读完多少页”，而是能完成以下动作：

  1. 解释官方组件的边界。
  2. 写出可运行工具和 Agent。
  3. 接入 RAG、memory、middleware、structured output。
  4. 对失败路径写 eval。
  5. 能把 mock 迁移到官方 provider。

官方核对索引​

主题官方页面本地章节
Overviewhttps://docs.langchain.com/oss/javascript/langchain/overview00、17
Modelshttps://docs.langchain.com/oss/javascript/langchain/models01、18、22
Messageshttps://docs.langchain.com/oss/javascript/langchain/messages01、18
Agentshttps://docs.langchain.com/oss/javascript/langchain/agents02、17、19
Toolshttps://docs.langchain.com/oss/javascript/langchain/tools02、19、22
Structured outputhttps://docs.langchain.com/oss/javascript/langchain/structured-output03、19、22
Short-term memoryhttps://docs.langchain.com/oss/javascript/langchain/short-term-memory04、20
Long-term memoryhttps://docs.langchain.com/oss/javascript/langchain/long-term-memory04、20
Retrievalhttps://docs.langchain.com/oss/javascript/langchain/retrieval05、20
Middlewarehttps://docs.langchain.com/oss/javascript/langchain/middleware/overview06、21、23
Runtimehttps://docs.langchain.com/oss/javascript/langchain/runtime06、21、22
Context engineeringhttps://docs.langchain.com/oss/javascript/langchain/context-engineering06、20
Guardrailshttps://docs.langchain.com/oss/javascript/langchain/guardrails07、21、23
HITLhttps://docs.langchain.com/oss/javascript/langchain/human-in-the-loop07、21、23
MCPhttps://docs.langchain.com/oss/javascript/langchain/mcp07、23
Streaminghttps://docs.langchain.com/oss/javascript/langchain/streaming07、18、23
LangSmith Observabilityhttps://docs.langchain.com/langsmith/observability-quickstart08、23
LangSmith Evaluationhttps://docs.langchain.com/langsmith/evaluation08、25

TypeScript 学习验收​

等级能力验收任务
L1会调用模型写一个 messages 输入，拿到输出，记录 model config
L2会写工具写 schema、权限、错误处理、单测
L3会做 Agent动态选择工具，处理工具失败
L4会结构化输出schema 成功/失败都有测试
L5会 RAGACL、citation、低召回拒答、conflict eval
L6会 memory短期 state、长期 store、隐私过滤
L7会 middleware/runtime动态模型/工具、contextSchema、trace
L8会 HITL/guardrails高风险工具审批，PII/prompt injection 防护
L9会观测/evalLangSmith 或自建 trace + dataset + gate
L10会迁移生产mock/live 双模式，provider 差异回归

项目验收矩阵​

项目必须覆盖的官方能力当前本地位置
企业知识库 AgentRetrieval、Tools、Structured output、Guardrails、EvalLangChain学习手册/src/projects/enterprise-kb-agent.ts、LangChain/src/core/rag.ts
个人学习助手Long-term memory、Short-term memory、Structured outputLangChain学习手册/src/projects/learning-assistant.ts、LangChain/src/core/memory-store.ts
多工具任务 AgentAgents、Tools、Middleware、Runtime、HITL、AuditLangChain学习手册/src/projects/multi-tool-task-agent.ts、LangChain/src/middleware/*
WorkbenchAgent team、API、Streaming、MCP mock、EvalLangChain/src/*

Python 差异​

官方 Python 页面通常覆盖面也很完整，但学习验收不应变成“看 Python 示例”。TypeScript 主线要以 JS 文档为准；Python 只作为概念补充和生态对照。若生产语言是 Python，再把本章验收矩阵翻译成 Python 项目。

工程边界​

  • 官方内容必须保留核对日期。
  • 任何“推荐做法”都要区分官方明确说明、官方示例推导、工程实践推导。
  • 本手册的 mock runtime 不等于官方 SDK；它只用于教学和离线 eval。
  • ../LangChain/ Workbench 是参考实现，不应和 LangChain学习手册/ 混成一个发布包。

常见反模式​

反模式后果
把博客当官方API 过期或语义不准
只看 Python 示例写 TSimport、schema、middleware 全错位
只读不做 eval学会的是概念，不是工程能力
不区分 mock/live真实 provider 问题上线才暴露

练习任务​

  1. 按 L1-L10 给自己打分，每级至少找一个本地文件证明。
  2. 选择一个官方页面，核对本手册对应章节是否有过期 API 名称。
  3. 给 ../LangChain/PROGRESS.md 补一条“官方核对日期”和“live adapter 风险”记录。