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

​
快速入门 - 本地开发

要运行文档的本地预览： 
git clone https://github.com/langchain-ai/docs.git

cd docs

make install

make dev
这将在 http://localhost:3000 启动支持热重载的开发服务器。编辑 src/ 中的文件，立即查看更改。
如果您的本地预览出现问题，请尝试运行 mint update 以确保您使用的是最新版本的 Mintlify。
必需：可选：

​
编辑文档

对于拼写错误或小改动，无需本地设置即可直接在 GitHub 上编辑：
  1. 点击任意页面底部的在 GitHub 上编辑本页。
  2. Fork 到您的个人账户。
  3. 在 GitHub 的网页编辑器中进行更改。
  4. 创建 Pull Request。
只编辑 src/ 中的文件——build/ 目录是自动生成的。
  1. 按照我们的写作规范编辑 src/ 中的文件。
  2. 提交前运行质量检查。
  3. 创建 Pull Request 以供审查。
当您创建或更新 PR 时，会自动生成一个预览分支/ID。PR 上会留下一条包含该 ID 的评论。
  1. 从评论中复制预览分支的 ID
  2. 在 Mintlify 仪表板中，点击创建预览部署
  3. 输入预览分支的 ID 并点击创建部署
  4. 选择预览并点击访问以查看
要使用最新更改重新部署，请在仪表板上点击重新部署。

​
运行质量检查

提交更改前，请确保您的代码通过格式化和代码检查： 
# 检查断链
make mint-broken-links

# 自动格式化代码
make format

# 检查代码检查问题
make lint

# 修复 markdown 问题
make lint_md_fix

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

​
文档类型

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

操作指南

面向知道自己想要完成什么的用户的任务导向说明。

概念指南

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

参考

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

教程

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

​
操作指南

操作指南是面向知道自己想要完成什么的用户的任务导向说明。操作指南的示例位于 LangChain 和 LangGraph 标签页上。
  • 任务导向：专注于特定任务或问题
  • 逐步说明：将任务分解为更小的步骤
  • 实践性强：提供具体的示例和代码片段
  • 专注于如何而非为什么
  • 使用具体的示例和代码片段
  • 将任务分解为更小的步骤
  • 链接到相关概念指南和参考资料

​
概念指南

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

​
参考

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

Python 参考

JavaScript/TypeScript 参考

好的参考应该：
  • 描述存在什么（所有参数、选项、返回值）
  • 全面且结构清晰，便于查找
  • 作为技术细节的权威来源
  • 保持一致；遵循供应商特定文档的现有模式
  • 包含基本用法（代码片段）和常见边界情况/失败模式
  • 注明功能需要特定版本的情况
  • 新集成或供应商需要专用参考页面
  • 复杂的配置选项需要详细说明
  • API 更改引入了新参数或行为
  • 社区经常询问特定功能的问题

​
教程

教程是更长篇幅的逐步指南，在自身基础上不断深入，引导用户完成特定的实践活动以建立理解。教程通常位于学习标签页上。
通常情况下，我们不合并来自外部贡献者的新教程，除非有迫切需求。如果您认为文档中缺少某个主题或覆盖不够充分，请提交新 Issue。
  • 实践性：专注于构建理解的实践活动。
  • 逐步说明：将活动分解为更小的步骤。
  • 实操性强：提供顺序的、可运行的代码片段。
  • 补充性：提供功能使用不一定必需的额外上下文和信息。
  • 如果用户按顺序执行步骤，代码片段应该是顺序的且可运行的。
  • 为活动提供一些上下文，但链接到相关概念指南和参考资料以获取更详细的信息。

​
写作规范

参考文档有不同的标准——详情请参阅参考文档贡献指南。

​
Mintlify 组件

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

​
页面结构

每个文档页面必须以 YAML 前言开头： 
---
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 文件中存在对应条目！**详情请参阅下方说明。
从 API 参考存根到 OSS 文档： 请参阅 README 了解从 API 参考存根链接到 Python OSS 文档的更多信息。具体请参阅 mkdocstrings 交叉引用链接语法。

​
获取帮助

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