BytesRouter

主题

LangChain 文档版本 跟随上游 源快照 0751dc2a 更新于 2026-10-08

为文档做贡献

我们欢迎对 LangChain 文档的贡献，包括新功能、集成，以及对现有文档的改进。

快速开始 - 本地开发

要运行文档的本地预览：

bash
git clone https://github.com/langchain-ai/docs.git
bash
cd docs

使用 mise 安装锁定版本的工具链，它会从 .mise.toml 中读取 Python、Node.js、uv、Vale 和 Mintlify CLI 的版本，并安装该仓库的 git hooks：

bash
mise trust && mise install
bash
make install
bash
make dev

这会在 http://localhost:3000 启动一个带热重载的开发服务器。编辑 src/ 中的文件即可立即看到更改。

TIP

正在使用 AI 编码智能体？

将两个 LangChain 文档 MCP 服务器都连接到我的编码智能体，以便它能够查找最新的 LangChain、LangGraph 和 LangSmith 文档及 API 参考。

要添加的服务器：

* `docs-langchain`: [https://docs.langchain.com/mcp](/mcp)
* `reference-langchain`: [https://reference.langchain.com/mcp](https://reference.langchain.com/mcp)

检测我正在使用哪个智能体或编辑器（Claude Code、Cursor、Codex CLI、Claude Desktop、Deep Agents Code、VS Code、Antigravity 或其他兼容 MCP 的客户端）。使用 [https://docs.langchain.com/use-these-docs.md](/langchain/use-these-docs) 中与你匹配的配置方式：

* Claude Code：为每个服务器运行 `claude mcp add --transport http`（默认项目范围；仅当我要求全局访问时才使用 `--scope user`）。
* Codex CLI：为每个服务器 URL 运行 `codex mcp add`。
* Cursor、Deep Agents Code、VS Code 或 Antigravity：按照该页面针对我的客户端所示的字段名，将两个条目合并到 MCP 设置 JSON 中。
* Claude Desktop：在 Settings > Connectors 下添加这两个 URL。

不要臆造其他 MCP URL。配置完成后，确认两个服务器都已列出并可访问。
  • 安装 LangChain Skills，以提升你的智能体在 LangChain 生态系统任务上的表现，然后点击本页右上角的 Copy page 按钮，将原始内容粘贴到你的智能体中，让它自动配置你的环境。
为我的编码智能体安装 LangChain Skills，使其在 LangChain、LangGraph 和 Deep Agents 任务上表现更好。

使用 [https://github.com/langchain-ai/langchain-skills](https://github.com/langchain-ai/langchain-skills) 中的 Agent Skills 安装器：

```bash
npx skills add langchain-ai/langchain-skills --skill '*' --yes
```

如果我要求改为全局安装，则使用：

```bash
npx skills add langchain-ai/langchain-skills --skill '*' --yes --global
```

检测我正在使用哪个智能体或编辑器。如果我使用 Claude Code 且偏好插件方式，请遵循该仓库 README 中的 marketplace 安装方式（先 `/plugin marketplace add`，再 `/plugin install`）。不要臆造其他技能包名称或安装 URL。安装完成后，确认这些技能对智能体可用。
  • 本仓库自带其创作技能，位于 .agents/skills/，涵盖页面创建、导航放置和重定向。大多数智能体会直接读取该路径。对于 Claude Code，运行 make skills 将它们链接起来。

TIP

如果你在本地预览时遇到问题，请尝试运行 mint update，以确保你使用的是最新的 Mintlify 版本。

前置条件

推荐： 运行 mise trust && mise install 一次性获取所有锁定版本。.mise.toml 是工具链的权威锁定文件，其 postinstall hook 会接好 pre-commit 和 pre-push hooks。

必需：

  • Python 3.13+
  • uv 0.9.26 或更高版本 - Python 包管理器
  • Node.js 22.x 和 npm。Mintlify 不支持 Node 25 或更高版本
  • Make
  • Git

可选：

编辑文档

在 GitHub 上快速编辑

对于拼写错误或小改动，无需本地环境，直接在 GitHub 上编辑：

  1. 在任意页面底部点击 Edit this page on GitHub。
  2. Fork 到你的个人账户。
  3. 在 GitHub 的网页编辑器中做出修改。
  4. 创建一个 pull request。

NOTE

只编辑 src/ 中的文件-- build/ 目录是自动生成的。

  1. 按照我们的写作规范编辑 src/ 中的文件。
  2. 提交前运行质量检查。
  3. 创建一个 pull request 以供审查。

NOTE

所有 pull request 都必须链接到一个已由维护者批准解决方案的 issue 或讨论。请参阅我们的 pull request 要求。

创建可共享的预览构建（仅限 LangChain 团队）

当你创建或更新 PR 时，会自动生成一个预览分支/ID。PR 上会留下一条包含该 ID 的评论。

  1. 从评论中复制预览分支的 ID
  2. 在 Mintlify 控制台中，点击 Create preview deployment
  3. 输入预览分支的 ID 并点击 Create deployment
  4. 选择该预览并点击 Visit 查看

要用最新更改重新部署，请在控制台上点击 Redeploy。

运行质量检查

在提交更改之前，请确保你的代码通过格式化和 linting 检查：

bash
# Check broken links
make broken-links

# Format code automatically
make format

# Check for linting issues
make lint

# Fix markdown issues
make lint_md_fix

# Run tests to ensure your changes don't break existing functionality
make test

有关更多细节，请参阅 README 中的可用命令部分。

WARNING

所有拉取请求都会由 CI/CD 自动检查。将强制执行相同的代码风格检查和格式化标准，如果这些检查失败，PR 将无法合并。

文档类型

所有文档都属于以下四个类别之一：

How-to guides

面向任务的说明，适用于明确自己想要完成什么的用户。

Conceptual guides

提供更深入理解和洞察的解释。

Reference

对 API 和实现细节的技术性描述。

Tutorials

引导用户通过实践活动来建立理解的课程。

NOTE

在适用的情况下，所有文档都必须同时包含 Python 和 JavaScript/TypeScript 内容。更多详情，请参阅并置 Python 和 JavaScript/TypeScript 内容一节。

操作指南

操作指南是面向任务的说明，适用于明确自己想要完成什么的用户。操作指南的示例位于 LangChain 和 LangGraph 标签页中。

特点
  • 任务导向：聚焦于特定的任务或问题
  • 循序渐进：将任务拆解为更小的步骤
  • 实操性：提供具体的示例和代码片段
提示
  • 关注如何做，而非为什么
  • 使用具体的示例和代码片段
  • 将任务拆解为更小的步骤
  • 链接到相关的概念指南和参考
示例

概念指南

概念指南以抽象的方式涵盖核心概念，提供深入的理解。

特点
  • 以理解为核心：解释事物为何如此运作
  • 宏观视角：较其他类型有更高、更广的视角
  • 设计导向：解释决策与权衡
  • 背景丰富：使用类比和对比
提示
  • 关注**“为什么”**，而非“如何做”
  • 提供并非功能使用所必需的补充信息
  • 可以使用类比并提及替代方案
  • 避免混入过多的参考内容
  • 链接到相关的教程和操作指南
示例

参考

参考文档包含详细、底层的信息，准确描述存在哪些功能以及如何使用它们。

Python reference

JavaScript/TypeScript reference

一份好的参考应当：

  • 描述存在的内容（所有参数、选项、返回值）
  • 全面且有结构，便于快速查阅
  • 作为技术细节的权威来源
为参考做贡献

reference.langchain.com 上生成的 API 参考在本仓库之外构建和部署。如需报告那里的 bug、缺失的包或损坏的页面，请提交参考文档问题。

LangChain 参考最佳实践
  • 保持一致；遵循服务商专有文档的现有模式
  • 同时包含基本用法（代码片段）和常见边界情况/失败模式
  • 注明功能需要特定版本的情形
何时创建新的参考文档
  • 符合托管指南资格标准的新集成（每月下载量 50,000+ 或被推荐）
  • 复杂的配置选项需要详细解释
  • API 变更引入了新的参数或行为
  • 社区频繁就特定功能提问

教程

教程是篇幅较长的循序渐进式指南，层层递进，带领用户完成某项具体的实践活动以建立理解。教程通常位于 Learn 标签页中。

NOTE

除非有迫切需求，我们通常不会合并来自外部贡献者的新教程。如果你认为文档中缺少某个主题，或某个主题覆盖不够充分，请提交新问题。

特点
  • 实践性：聚焦于通过实践活动来建立理解。
  • 循序渐进：将活动拆解为更小的步骤。
  • 实操性：提供可依次运行、能够工作的代码片段。
  • 补充性：提供并非功能使用所必需的额外背景和信息。
提示
  • 如果用户按顺序执行步骤，代码片段应当是可依次运行且能够工作的。
  • 为活动提供一些背景，但更详细的信息请链接到相关的概念指南和参考。
示例

写作标准

NOTE

reference.langchain.com 上的页面标准随该站点的构建流水线而定，并不在本仓库中。有关生成的 API 参考内容的问题或修正，请使用参考文档问题模板。

Mintlify 组件

使用 Mintlify 组件来增强可读性：

  • <Note> 用于有帮助的补充信息
  • <Warning> 用于重要的注意事项和破坏性变更
  • <Tip> 用于最佳实践和建议
  • <Info> 用于中性的上下文信息
  • <Check> 用于成功确认

Mermaid 图表

添加 mermaid 图表时，请使用 LangChain 品牌配色对节点进行样式设置。可从任何现有图表中复制 classDef 行，或使用 AGENTS.md 中的参考表。

角色填充描边文本
处理#E5F4FF#006DDD#030710
触发#F6FFDB#6E8900#2E3900
判断#FDF3FF#7E65AE#504B5F
输出#EBD0F0#885270#441E33
警告#F8E8E6#B27D75#634643
中性#F2FAFF#40668D#2F4B68

不要使用 Tailwind 默认配色、Material Design 配色或其他非品牌配色。

页面结构

每个文档页面都必须以 YAML frontmatter 开头：

yaml
---
title: "Clear, specific title"
sidebarTitle: "Short title for the sidebar (optional)"
---

并置 Python 和 JavaScript/TypeScript 内容

在可能的情况下，所有文档都必须同时用 Python 和 JavaScript/TypeScript 编写。为此，我们使用一种自定义的行内语法来区分应出现在一种还是两种语言中的章节：

mdx
:::python
Python-specific content. In real docs, the preceding backslash (before `python`) is omitted.
:::

:::js
JavaScript/TypeScript-specific content. In real docs, the preceding backslash (before `js`) is omitted.
:::

Content for both languages (not wrapped)

这将在 /oss/python/concepts/foo.mdx 和 /oss/javascript/concepts/foo.mdx 生成两个输出（每种语言一个）。每个输出的页面都需要添加到 /src/docs.json 文件中，才会包含在导航中。

NOTE

我们不希望因为缺乏对等性而阻碍贡献。如果某个功能仅在一种语言中可用，那么在其他语言跟上之前，只在该语言中提供文档是可以的。在这种情况下，请添加一条说明，指出该功能在其他语言中尚不可用。

如果你在 Python 和 JavaScript/TypeScript 之间翻译内容时需要帮助，请在社区 Slack 中提问，或在你的 PR 中 @ 一位维护者。

质量标准

通用准则

避免重复

多个页面覆盖相同的内容会难以维护并造成混淆。每个概念或功能都应只有一个权威页面。请链接到其他指南，而不是重新解释。

频繁链接

文档章节并非孤立存在。请经常链接到其他章节，让用户能够了解不熟悉的主题。这包括链接到 API 参考和概念章节。

保持简洁

采取少即是多的方法。如果已存在解释得好的章节，请链接到它，而不是重新解释，除非你的内容提供了新的角度。

无障碍要求

确保所有用户都能访问文档：

  • 使用标题和列表组织内容，便于快速浏览
  • 使用具体、可操作的链接文字，而不是“点击这里”
  • 为所有图像和图表提供描述性的替代文本

交叉引用

使用一致的交叉引用来将文档与 API 参考文档关联起来。

从文档到 API 参考：

使用 @[] 语法链接到 API 参考页面：

mdx
See @[`ChatAnthropic`] for all configuration options.

The @[`bind_tools`][ChatAnthropic.bind_tools] method accepts...

构建流水线会根据当前语言范围（Python 或 JavaScript）将这些转换为正确的 markdown 链接。例如，@[ChatAnthropic] 会根据正在构建的文档版本，变成指向 Python 或 JS API 参考页面的链接，但前提是 link_map.py 文件中存在对应条目！ 详情见下文。

自动链接如何工作

@[] 语法由 handle_auto_links.py 处理。它会在 link_map.py 中查找链接键，该文件包含 Python 和 JavaScript 两种范围的字典映射。

支持的格式：

语法结果
@[ChatAnthropic]链接，显示文本为 "ChatAnthropic"
@[`ChatAnthropic`]链接，文本为 `ChatAnthropic`（代码格式）
@[text][ChatAnthropic]链接，文本为 "text"，并以 ChatAnthropic 作为链接映射中的键
\@[ChatAnthropic]转义：渲染为字面量 @[ChatAnthropic]（无链接——本页使用的就是这个！）

添加新链接：

如果映射中找不到某个链接，它将在输出中保持原样。要添加新的自动链接：

  1. 打开 pipeline/preprocessors/link_map.py
  2. 在 LINK_MAPS 中为适当范围（python 或 js）添加条目
  3. 键是用于 @[key] 或 @[text][key] 中的链接名称，值是相对于参考主机的路径

从 API 参考存根到 OSS 文档：

已发布的 Python API 参考中的交叉链接和深层锚点是在本仓库之外生成的。如果从 reference.langchain.com 到 docs.langchain.com 的链接有误或已过时，请提交问题，并附上源 URL 和目标 URL。

本地化

如果某个功能在两个 SDK 中都存在，请将其同时面向 Python 和 JavaScript/TypeScript 记录。如果目前仅支持一种语言，请确保该功能及其引用仅对该语言可见。

代码内文档

示例必须正确，尽可能可直接复制粘贴，并且在打开拉取请求之前经过测试。请清楚地标记不可运行的片段（例如伪代码或说明性片段）。

获取帮助

我们的目标是尽可能简化开发者配置。如果你在配置过程中遇到任何困难，请在社区 Slack 中提问，或发表论坛帖子。内部团队成员可以在 #documentation Slack 频道中联系。

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可