贡献文档 - Docs by LangChain中文

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

快速开始 - 本地开发

要在本地预览文档，请运行：

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

cd docs

make install

make dev

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

使用 AI 编码助手？ 安装 LangChain Skills 以提高您的助手在 LangChain 生态系统任务上的性能，然后点击此页面右上角的“复制页面”按钮，将原始内容粘贴到您的助手中，让其自动为您设置环境。

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

先决条件

必需：

Python 3.13+
uv - Python 包管理器
Node.js 和 npm
Make
Git

可选：

markdownlint-cli - npm install -g markdownlint-cli
Mintlify MDX VSCode 扩展

编辑文档

在 GitHub 上快速编辑

对于拼写错误或微小更改，可直接在 GitHub 上编辑，无需本地设置：

点击任何页面底部的 在 GitHub 上编辑此页面。
Fork 到您的个人账户。
在 GitHub 的 Web 编辑器中进行更改。
创建一个拉取请求。

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

按照我们的写作标准编辑 src/ 中的文件。
提交前运行质量检查。
创建一个拉取请求以供审核。

所有拉取请求都必须链接到一个经维护者批准解决方案的议题或讨论。请参阅我们的拉取请求要求。

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

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

从评论中复制预览分支的 ID。
在 Mintlify 控制面板中，点击创建预览部署。
输入预览分支的 ID 并点击创建部署。
选择该预览并点击访问进行查看。

要使用最新更改重新部署，请在控制面板上点击重新部署。

运行质量检查

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

# 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 中的可用命令部分。

文档类型

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

操作指南

面向知道要完成什么目标的用户的任务型说明。

概念指南

提供深入理解和见解的说明。

参考

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

教程

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

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

操作指南

操作指南是面向知道要完成什么目标的用户的任务型说明。操作指南的示例位于 LangChain 和 LangGraph 标签页。

特点

任务导向：专注于特定任务或问题。
分步进行：将任务分解为更小的步骤。
实践性强：提供具体示例和代码片段。

技巧

专注于 如何做 而不是 为什么。
使用具体示例和代码片段。
将任务分解为更小的步骤。
链接到相关的概念指南和参考文档。

示例

概念指南

概念指南抽象地涵盖核心概念，提供深入理解。

特点

理解导向：解释事物为何如此运作。
视角广阔：比其他类型具有更高更广的视角。
设计导向：解释决策和权衡。
语境丰富：使用类比和比较。

技巧

专注于 “为什么” 而不是 “如何”。
提供不一定是功能使用所必需的补充信息。
可以使用类比并参考替代方案。
避免混入过多参考内容。
链接到相关的教程和操作指南。

示例

参考

参考文档包含详细的底层信息，精确描述存在的功能及其使用方法。

Python 参考

JavaScript/TypeScript 参考

一个好的参考应该：

描述存在的内容（所有参数、选项、返回值）
全面且结构化，便于查找
作为技术细节的权威来源

贡献参考文档

reference.langchain.com 上生成的 API 参考文档是在此仓库之外构建和部署的。要报告那里的错误、缺失的包或损坏的页面，请提交参考文档议题。

LangChain 参考最佳实践

保持一致性；遵循现有的特定提供商文档模式。
包括基本用法（代码片段）和常见的边缘情况/失败模式。
注意功能需要特定版本的情况。

何时创建新的参考文档

符合托管指南资格标准的新集成（每月下载量 50,000+ 或精选）。
复杂的配置选项需要详细解释。
API 变更引入了新的参数或行为。
社区频繁询问特定功能。

教程

教程是更长的分步指南，通过循序渐进的方式引导用户完成特定的实践活动以构建理解。教程通常位于学习标签页。

我们通常不会合并来自外部贡献者的新教程，除非有迫切需求。如果您觉得文档中缺少某个主题或覆盖不足，请提交新议题。

特点

实用：专注于通过实践活动构建理解。
分步进行：将活动分解为更小的步骤。
实践性强：提供顺序的、可工作的代码片段。
补充性：提供不一定是功能使用所必需的额外背景和信息。

技巧

如果用户按顺序遵循步骤，代码片段应该是顺序的、可工作的。
为活动提供一些背景信息，但链接到相关的概念指南和参考文档以获取更详细的信息。

示例

写作标准

reference.langchain.com 上的页面标准存在于该网站的构建流程中，不在此仓库中。有关生成的 API 参考内容的问题或修复，请使用参考文档议题模板。

Mintlify 组件

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

标注
结构
代码

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

<Steps> 用于顺序流程的概述。不用于长步骤列表或教程。
<Tabs> 用于特定于平台的内容。
<AccordionGroup> 和 <Accordion> 用于默认可折叠的、可选的信息（例如，完整的代码示例）。
<CardGroup> 和 <Card> 用于突出显示内容。

<CodeGroup> 用于多语言示例。
始终在代码块上指定语言标签（例如， ```python， ```javascript）。
代码块的标题（例如，Success，Error Response）

Mermaid 图表

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

角色	填充色	描边色	文字色
过程	`#E5F4FF`	`#006DDD`	`#030710`
触发器	`#F6FFDB`	`#6E8900`	`#2E3900`
决策	`#FDF3FF`	`#7E65AE`	`#504B5F`
输出	`#EBD0F0`	`#885270`	`#441E33`
警报	`#F8E8E6`	`#B27D75`	`#634643`
中性	`#F2FAFF`	`#40668D`	`#2F4B68`

不要使用 Tailwind 默认值、Material Design 颜色或其他非品牌调色板。

页面结构

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

---
title: "清晰、具体的标题"
sidebarTitle: "侧边栏的短标题（可选）"
---

共置 Python 和 JavaScript/TypeScript 内容

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

:::python
Python 特定内容。在实际文档中，`python` 前面的反斜杠被省略。
:::

:::js
JavaScript/TypeScript 特定内容。在实际文档中，`js` 前面的反斜杠被省略。
:::

两种语言共有的内容（不包装）

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

我们不希望缺乏对等性阻碍贡献。如果一个功能仅在一种语言中可用，那么仅在该语言中拥有文档是可以的，直到另一种语言迎头赶上。在这种情况下，请包含一个说明，指出该功能尚未在另一种语言中可用。如果您在 Python 和 JavaScript/TypeScript 之间翻译内容需要帮助，请在社区 Slack 中提问，或在您的 PR 中标记维护者。

质量标准

一般准则

避免重复

涵盖相同材料的多个页面难以维护并会造成混淆。每个概念或功能应该只有一个规范页面。链接到其他指南而不是重新解释。

频繁链接

文档部分并非孤立存在。频繁链接到其他部分，让用户可以学习不熟悉的主题。这包括链接到 API 参考和概念部分。

简洁

采取少即是多的方法。如果存在另一个有良好解释的部分，请链接到它而不是重新解释，除非您的内容提出了新的角度。

无障碍要求

确保文档对所有用户可用：

使用标题和列表构建内容结构，便于扫描
使用具体、可操作的链接文本，而不是“点击这里”
为所有图片和图表包含描述性的替代文本

交叉引用

使用一致的交叉引用来连接文档和 API 参考文档。 从文档到 API 参考： 使用 @[] 语法链接到 API 参考页面：

参见 @[`ChatAnthropic`] 了解所有配置选项。

@[`bind_tools`][ChatAnthropic.bind_tools] 方法接受...

构建流程会根据当前语言范围（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]`（无链接 - 这正是本页面正在使用的！）

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

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

从 API 参考存根到 OSS 文档： 已发布的 Python API 参考中的交叉链接和深度锚点是在此仓库之外生成的。如果从 reference.langchain.com 到 docs.langchain.com 的链接错误或过时，请提交议题并提供源 URL 和目标 URL。

本地化

如果功能同时存在于两个 SDK 中，请同时为 Python 和 JavaScript/TypeScript 编写文档。如果仅支持一种语言，请确保该功能及对其的引用仅对该语言可见。

代码内文档

示例必须正确，在可能的情况下可复制粘贴，并且在您提交拉取请求之前必须经过测试。请明确标记不可运行的代码片段（例如，伪代码或说明性片段）。

获取帮助

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

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​快速开始 - 本地开发

​编辑文档

​运行质量检查

​文档类型

操作指南

概念指南

参考

教程

​操作指南

​概念指南

​参考

Python 参考

JavaScript/TypeScript 参考

​教程

​写作标准

​Mintlify 组件

​Mermaid 图表

​页面结构

​共置 Python 和 JavaScript/TypeScript 内容

​质量标准

​一般准则

​无障碍要求

​交叉引用

​本地化

​代码内文档

​获取帮助

快速开始 - 本地开发

编辑文档

运行质量检查

文档类型

操作指南

概念指南

参考

教程

写作标准

Mintlify 组件

Mermaid 图表

页面结构

共置 Python 和 JavaScript/TypeScript 内容

质量标准

一般准则

无障碍要求

交叉引用

本地化

代码内文档

获取帮助