> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 贡献文档

我们欢迎对LangChain文档的贡献，包括新功能、[集成](/oss/python/contributing/publish-langchain)以及对现有文档的改进。

## 快速开始 - 本地开发

要运行文档的本地预览：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
git clone https://github.com/langchain-ai/docs.git
```

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
cd docs
```

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
make install
```

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
make dev
```

这将启动一个支持热重载的开发服务器，地址为 `http://localhost:3000`。编辑 `src/` 目录中的文件，即可立即看到更改。

<Tip>
  **使用AI编码代理？** 安装 [LangChain Skills](https://github.com/langchain-ai/langchain-skills) 以提升您的代理在LangChain生态系统任务上的表现，然后点击本页右上角的“复制页面”按钮，将原始内容粘贴到您的代理中，让它自动设置您的环境。
</Tip>

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

<Accordion title="前提条件">
  **必需：**

  * Python 3.13+
  * [uv](https://docs.astral.sh/uv/) - Python 包管理器
  * [Node.js](https://nodejs.org/en) 和 npm
  * [Make](https://www.gnu.org/software/make/)
  * [Git](https://git-scm.com/)

  **可选：**

  * [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) - `npm install -g markdownlint-cli`
  * [Mintlify MDX VSCode 扩展](https://www.mintlify.com/blog/mdx-vscode-extension)
</Accordion>

## 编辑文档

<Accordion title="在 GitHub 上快速编辑">
  对于拼写错误或小改动，可以直接在 GitHub 上编辑，无需本地设置：

  1. 点击任何页面底部的 **在 GitHub 上编辑此页面**。
  2. Fork 到您的个人账户。
  3. 在 GitHub 的网页编辑器中进行更改。
  4. 创建一个拉取请求。
</Accordion>

<Note>
  **仅编辑 `src/` 中的文件** -- `build/` 目录是自动生成的。
</Note>

1. 按照我们的[写作标准](#写作标准)编辑 `src/` 中的文件。
2. 提交前运行[质量检查](#运行质量检查)。
3. 创建拉取请求以供审核。

<Note>
  所有拉取请求必须链接到一个解决方案已由维护者批准的议题或讨论。请参阅我们的[拉取请求要求](/oss/python/contributing/overview#pull-request-requirements)。
</Note>

<Accordion title="创建可共享的预览构建（仅限 LangChain 团队）">
  当您创建或更新 PR 时，会自动生成一个[预览分支/ID](https://github.com/langchain-ai/docs/actions/workflows/create-preview-branch.yml)。PR 上会留下一条包含该 ID 的评论。

  1. 从评论中复制预览分支的 ID
  2. 在 [Mintlify 仪表板](https://dashboard.mintlify.com/langchain-5e9cc07a/langchain-5e9cc07a?section=previews)中，点击 **创建预览部署**
  3. 输入预览分支的 ID 并点击 **创建部署**
  4. 选择预览并点击 **访问** 以查看

  要使用最新更改重新部署，请在仪表板上点击 **重新部署**。
</Accordion>

### 运行质量检查

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 检查断开的链接
make broken-links

# 自动格式化代码
make format

# 检查代码检查问题
make lint

# 修复 Markdown 问题
make lint_md_fix

# 运行测试以确保您的更改不会破坏现有功能
make test
```

更多详情，请参阅 `README` 中的[可用命令](https://github.com/langchain-ai/docs?tab=readme-ov-file#available-commands)部分。

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

## 文档类型

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

<CardGroup cols={2}>
  <Card title="操作指南" icon="tool" href="#操作指南">
    面向知道要完成什么任务的用户的任务导向型说明。
  </Card>

  <Card title="概念指南" icon="bulb" href="#概念指南">
    提供更深入理解和见解的解释。
  </Card>

  <Card title="参考" icon="book" href="#参考">
    API 和实现细节的技术描述。
  </Card>

  <Card title="教程" icon="school" href="#教程">
    指导用户通过实践活动建立理解的课程。
  </Card>
</CardGroup>

<Note>
  在适用的情况下，所有文档必须同时包含 Python 和 JavaScript/TypeScript 内容。更多详情，请参阅[将 Python 和 JavaScript/TypeScript 内容共置](#将-python-和-javascript%2Ftypescript-内容共置)部分。
</Note>

### 操作指南

操作指南是面向知道要完成什么任务的用户的任务导向型说明。操作指南的示例可在 [LangChain](/oss/python/langchain/overview) 和 [LangGraph](/oss/python/langgraph/overview) 选项卡中找到。

<AccordionGroup>
  <Accordion title="特点">
    * **任务聚焦**：专注于特定任务或问题
    * **分步进行**：将任务分解为更小的步骤
    * **实践性**：提供具体的示例和代码片段
  </Accordion>

  <Accordion title="提示">
    * 关注 **如何做** 而不是 **为什么**
    * 使用具体的示例和代码片段
    * 将任务分解为更小的步骤
    * 链接到相关的概念指南和参考
  </Accordion>

  <Accordion title="示例">
    * [消息](/oss/python/langchain/messages)
    * [工具](/oss/python/langchain/tools)
    * [流式处理](/oss/python/langgraph/streaming)
  </Accordion>
</AccordionGroup>

### 概念指南

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

<AccordionGroup>
  <Accordion title="特点">
    * **理解聚焦**：解释事物为何如此运作
    * **广角视角**：比其他类型具有更高更广的视角
    * **设计导向**：解释决策和权衡
    * **上下文丰富**：使用类比和比较
  </Accordion>

  <Accordion title="提示">
    * 关注 **“为什么”** 而不是“如何做”
    * 提供功能使用不一定需要的补充信息
    * 可以使用类比和参考替代方案
    * 避免混入过多的参考内容
    * 链接到相关的教程和操作指南
  </Accordion>

  <Accordion title="示例">
    * [记忆](/oss/python/concepts/memory)
    * [上下文](/oss/python/concepts/context)
    * [图 API](/oss/python/langgraph/graph-api)
    * [函数式 API](/oss/python/langgraph/functional-api)
  </Accordion>
</AccordionGroup>

### 参考

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

<CardGroup cols={2}>
  <Card title="Python 参考" href="https://reference.langchain.com/python/" icon="brand-python" arrow />

  <Card title="JavaScript/TypeScript 参考" href="https://reference.langchain.com/javascript/" icon="brand-javascript" arrow />
</CardGroup>

一个好的参考应该：

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

<AccordionGroup>
  <Accordion title="为参考文档做贡献">
    请参阅 [Python 参考文档](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md)的贡献指南。
  </Accordion>

  <Accordion title="LangChain 参考最佳实践">
    * **保持一致**；遵循现有特定于提供者的文档模式
    * 包括基本用法（代码片段）和常见的边缘情况/故障模式
    * 注意功能何时需要特定版本
  </Accordion>

  <Accordion title="何时创建新的参考文档">
    * 新的集成或提供者需要专门的参考页面
    * 复杂的配置选项需要详细解释
    * API 变更引入了新参数或行为
    * 社区经常询问有关特定功能的问题
  </Accordion>
</AccordionGroup>

### 教程

教程是较长的分步指南，它逐步构建，引导用户通过特定的实践活动来建立理解。教程通常可在 [学习](/oss/python/learn) 选项卡中找到。

<Note>
  我们通常不会合并外部贡献者的新教程，除非有迫切需要。如果您觉得文档中缺少某个主题或涵盖不足，请[提交新议题](https://github.com/langchain-ai/docs/issues)。
</Note>

<AccordionGroup>
  <Accordion title="特点">
    * **实践性**：专注于实践活动以建立理解。
    * **分步进行**：将活动分解为更小的步骤。
    * **实践性**：提供顺序的、可运行的代码片段。
    * **补充性**：提供功能使用不一定需要的额外上下文和信息。
  </Accordion>

  <Accordion title="提示">
    * 代码片段应该是顺序的，并且如果用户按顺序执行步骤，应该是可运行的。
    * 为活动提供一些上下文，但链接到相关的概念指南和参考以获取更详细的信息。
  </Accordion>

  <Accordion title="示例">
    * [语义搜索](/oss/python/langchain/knowledge-base)
    * [RAG 代理](/oss/python/langchain/rag)
  </Accordion>
</AccordionGroup>

## 写作标准

<Note>
  参考文档有不同的标准 - 详情请参阅[参考文档贡献指南](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md)。
</Note>

### Mintlify 组件

使用 [Mintlify 组件](https://mintlify.com/docs/text) 来增强可读性：

<Tabs>
  <Tab title="标注">
    * `<Note>` 用于有用的补充信息
    * `<Warning>` 用于重要的注意事项和破坏性更改
    * `<Tip>` 用于最佳实践和建议
    * `<Info>` 用于中性的上下文信息
    * `<Check>` 用于成功确认
  </Tab>

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

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

### Mermaid 图表

添加 mermaid 图表时，使用 LangChain 品牌调色板进行节点样式设置。从任何现有图表中复制 `classDef` 行，或使用 [`CLAUDE.md`](https://github.com/langchain-ai/docs/blob/main/CLAUDE.md#mermaid-diagram-styling) 中的参考表。

| 角色       | 填充        | 描边        | 文本        |
| -------- | --------- | --------- | --------- |
| process  | `#E5F4FF` | `#006DDD` | `#030710` |
| trigger  | `#F6FFDB` | `#6E8900` | `#2E3900` |
| decision | `#FDF3FF` | `#7E65AE` | `#504B5F` |
| output   | `#EBD0F0` | `#885270` | `#441E33` |
| alert    | `#F8E8E6` | `#B27D75` | `#634643` |
| neutral  | `#F2FAFF` | `#40668D` | `#2F4B68` |

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

### 页面结构

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

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
---
title: "清晰、具体的标题"
sidebarTitle: "侧边栏的简短标题（可选）"
---
```

### 将 Python 和 JavaScript/TypeScript 内容共置

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

```mdx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
:::python
特定于 Python 的内容。在实际文档中，前面的反斜杠（在 `python` 之前）被省略。
:::

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

两种语言通用的内容（不包装）
```

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

<Note>
  我们不希望缺乏对等性阻碍贡献。如果某个功能仅在一种语言中可用，那么在另一种语言赶上之前，仅在该语言中提供文档是可以的。在这种情况下，请包含一个说明，指出该功能在另一种语言中尚不可用。

  如果您需要帮助在 Python 和 JavaScript/TypeScript 之间翻译内容，请在[社区 Slack](https://www.langchain.com/join-community) 中提问，或在您的 PR 中标记维护者。
</Note>

## 质量标准

### 通用指南

<AccordionGroup>
  <Accordion title="避免重复">
    涵盖相同材料的多个页面难以维护并会引起混淆。每个概念或功能应只有一个规范页面。链接到其他指南，而不是重新解释。
  </Accordion>

  <Accordion title="频繁链接">
    文档部分不是孤立存在的。频繁链接到其他部分，以便用户了解不熟悉的主题。这包括链接到 API 参考和概念部分。
  </Accordion>

  <Accordion title="保持简洁">
    采取少即是多的方法。如果存在另一个有良好解释的部分，请链接到它，而不是重新解释，除非您的内容提供了新的角度。
  </Accordion>
</AccordionGroup>

### 无障碍要求

确保文档对所有用户都易于访问：

* 使用标题和列表构建内容，便于快速浏览
* 使用具体、可操作的链接文本，而不是“点击此处”
* 为所有图像和图表包含描述性的替代文本

### 交叉引用

使用一致的交叉引用来连接文档和 API 参考文档。

**从文档到 API 参考：**

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

```mdx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
请参阅 @[`ChatAnthropic`] 了解所有配置选项。

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

构建管道会根据当前语言范围（Python 或 JavaScript）将这些转换为适当的 markdown 链接。例如，`@[ChatAnthropic]` 将根据构建的文档版本链接到 Python 或 JS API 参考页面，**但前提是 `link_map.py` 文件中存在相应条目！** 详情请参见下文。

<Accordion title="自动链接如何工作">
  `@[]` 语法由 [`handle_auto_links.py`](https://github.com/langchain-ai/docs/blob/main/pipeline/preprocessors/handle_auto_links.py) 处理。它在 [`link_map.py`](https://github.com/langchain-ai/docs/blob/main/pipeline/preprocessors/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]` 中使用的链接名称，值是相对于参考主机的路径
</Accordion>

**从 API 参考存根到 OSS 文档：**

有关从 API 参考存根链接到 Python OSS 文档的更多信息，请参阅 [`README`](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md)。具体请参阅 `mkdocstrings` 交叉引用[链接语法](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md#mkdocsmkdocstrings-python-cross-reference-linking-syntax)。

### 本地化

如果某个功能在两个 SDK 中都存在，请[同时为 Python 和 JavaScript/TypeScript 编写文档](#将-python-和-javascript%2Ftypescript-内容共置)。如果目前仅支持一种语言，请确保该功能及其引用仅对该语言可见。

### 代码内文档

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

## 获取帮助

我们的目标是尽可能简化开发者的设置。如果您在设置过程中遇到任何困难，请在[社区 Slack](https://www.langchain.com/join-community) 中提问或发布[论坛帖子](https://forum.langchain.com/)。内部团队成员可以在 [#documentation](https://langchain.slack.com/archives/C04GWPE38LV) Slack 频道中联系。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/contributing/documentation.mdx) 或 [提交议题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>