Skip to main content
我们欢迎对 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。
必需：可选：

​
编辑文档

对于拼写错误或小的更改，无需本地设置即可直接在 GitHub 上编辑：
  1. 在任何页面底部单击 在 GitHub 上编辑此页面。
  2. 复刻到您的个人账户。
  3. 在 GitHub 的 Web 编辑器中进行更改。
  4. 创建拉取请求。
仅编辑 src/ 中的文件 — build/ 目录是自动生成的。
  1. 按照我们的编写标准编辑 src/ 中的文件。
  2. 在提交前运行质量检查。
  3. 创建拉取请求以供审查。
所有拉取请求必须链接到已由维护者批准解决方案的问题或讨论。请参阅我们的拉取请求要求。
当您创建或更新 PR 时，会自动生成一个预览分支/ID。将在 PR 上留下一条包含 ID 的评论。
  1. 从评论中复制预览分支的 ID
  2. 在 Mintlify 仪表板 中，单击 创建预览部署
  3. 输入预览分支的 ID 并单击 创建部署
  4. 选择预览并单击 访问 以查看
要使用最新更改重新部署，请在仪表板上单击 重新部署。

​
运行质量检查

在提交更改之前，确保您的代码通过格式化和 linting 检查： 
# 检查损坏的链接
make broken-links

# 自动格式化代码
make format

# 检查 linting 问题
make lint

# 修复 markdown 问题
make lint_md_fix

# 运行测试以确保您的更改不会破坏现有功能
make test
有关更多详细信息，请参阅 README 中的可用命令部分。

​
文档类型

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

操作指南

面向任务的说明，适用于知道他们想要完成什么的用户。

概念指南

提供更深层次理解和见解的解释。

参考

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

教程

指导用户通过实际活动来构建理解的课程。
在适用的情况下，所有文档必须同时包含 Python 和 JavaScript/TypeScript 内容。有关更多详细信息，请参阅共置 Python 和 JavaScript/TypeScript 内容部分。

​
操作指南

操作指南是面向任务的说明，适用于知道他们想要完成什么的用户。操作指南的示例位于 LangChain 和 LangGraph 选项卡上。
  • 任务聚焦：专注于特定任务或问题
  • 分步进行：将任务分解为更小的步骤
  • 动手实践：提供具体示例和代码片段
  • 专注于 如何做 而不是 为什么
  • 使用具体示例和代码片段
  • 将任务分解为更小的步骤
  • 链接到相关的概念指南和参考

​
概念指南

概念指南抽象地涵盖核心概念，提供深入的理解。
  • 理解聚焦：解释事物为何如此运作
  • 广阔视角：比其他类型具有更高和更广的视野
  • 设计导向：解释决策和权衡
  • 上下文丰富：使用类比和比较
  • 专注于 “为什么” 而不是“如何”
  • 提供不一定需要用于功能使用的补充信息
  • 可以使用类比和参考替代方案
  • 避免过多地混合参考内容
  • 链接到相关的教程和操作指南

​
参考

参考文档包含详细、低级别的信息，准确描述存在的功能以及如何使用它。

Python 参考

JavaScript/TypeScript 参考

一个好的参考应该：
  • 描述存在的内容（所有参数、选项、返回值）
  • 全面且结构化，便于查找
  • 作为技术细节的权威来源
请参阅 JavaScript/TypeScript 参考文档 的贡献指南。
  • 保持一致；遵循现有模式以获取特定于提供者的文档
  • 包括基本用法（代码片段）和常见边缘情况/失败模式
  • 注意功能需要特定版本时
  • 新的集成或提供者需要专用的参考页面
  • 复杂的配置选项需要详细解释
  • API 更改引入了新参数或行为
  • 社区经常询问特定功能的问题

​
教程

教程是更长的分步指南，它建立在自身之上，并引导用户通过特定的实践活动来构建理解。教程通常位于 学习 选项卡上。
我们通常不会合并外部贡献者的新教程，除非有迫切需要。如果您觉得文档中缺少某个主题或未充分涵盖，请提出新问题。
  • 实用：专注于构建理解的实践活动。
  • 分步进行：将活动分解为更小的步骤。
  • 动手实践：提供顺序的、可工作的代码片段。
  • 补充性：提供不一定需要用于功能使用的额外上下文和信息。
  • 代码片段应该是顺序的，并且如果用户按顺序遵循步骤，则可以工作。
  • 为活动提供一些上下文，但链接到相关的概念指南和参考以获取更详细的信息。

​
编写标准

参考文档有不同的标准 - 有关详细信息，请参阅参考文档贡献指南。

​
Mintlify 组件

使用 Mintlify 组件 来增强可读性：
  • <Note> 用于有用的补充信息
  • <Warning> 用于重要的注意事项和重大更改
  • <Tip> 用于最佳实践和建议
  • <Info> 用于中性上下文信息
  • <Check> 用于成功确认

​
页面结构

每个文档页面必须以 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]（无链接 - 本页正在使用！）
添加新链接：如果在映射中找不到链接，它将在输出中保持不变。要添加新的自动链接：
  1. 打开 pipeline/preprocessors/link_map.py
  2. 在 LINK_MAPS 中的适当范围（python 或 js）添加一个条目
  3. 键是 @[key] 或 @[text][key] 中使用的链接名称，值是相对于参考主机的路径

​
本地化

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

​
代码内文档

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

​
获取帮助

我们的目标是尽可能简化开发人员设置。如果您在设置过程中遇到任何困难，请在社区 Slack 中提问或在论坛帖子 中提问。内部团队成员可以通过 #documentation Slack 频道联系。
在 GitHub 上编辑此页面 或提出问题。
通过 MCP 将这些文档 连接到 Claude、VSCode 等，以获取实时答案。