为代码做贡献

欢迎贡献代码！无论你是在修复缺陷、添加功能还是改进性能，你的贡献都能帮助为成千上万的开发者带来更好的开发体验。

入门

如果你想找点事情做，请查看我们仓库中标记为 "help wanted" 的 issue：

⛓LangChain

标签

•LangGraph

标签

•Deep Agents

标签

NOTE

在提交大型新功能或重构之前，请先开一个 issue 或到论坛发帖讨论。这样可以确保与项目目标保持一致，并避免重复工作。

快速修复：提交缺陷修复

对于简单的缺陷修复，你可以立即开始：

Reproduce the issue

在克隆仓库之前，请确保你能可靠地复现该缺陷。这有助于确认问题，并为你的修复提供起点。维护者和其他贡献者应能根据你的描述复现该问题，而无需额外的设置或修改。

Fork the repository

将 LangChain、LangGraph 或 Deep Agents 仓库 fork 到你的

个人 GitHub 账户

Clone and setup

git clone https://github.com/your-username/name-of-forked-repo.git

# For instance, for LangChain:
git clone https://github.com/parrot123/langchain.git

WARNING

LangChain Python 仓库是一个 monorepo——仓库根目录没有 pyproject.toml。每个包在 libs/ 下都有自己的配置（例如 libs/core/、libs/langchain/、libs/partners/openai/）。在运行 uv 命令之前，你必须 cd 进入相关的包目录。

# Navigate into the package you want to work on, then install dependencies
cd libs/core          # or libs/langchain, libs/partners/openai, etc.
uv sync --all-groups

# or, to install a specific group only:
uv sync --group test

如果你之前没有安装过 uv，则需要安装它。有关包及其位置的完整列表，请参阅仓库结构部分。

Create a branch

为你的修复创建一个新分支。这有助于保持你的更改井然有序，并使之后提交拉取请求更容易。

git checkout -b your-username/short-bugfix-name

Write failing tests

添加在没有你的修复时会失败的单元测试。这让我们能够验证缺陷已被解决并防止回归

Make your changes

在遵循我们的代码质量标准的同时修复缺陷。做出解决该问题所需的最小必要更改。我们强烈鼓励贡献者在开始编码之前在该 issue 下发表评论。例如：

"我想着手处理这个。我打算采用的方法是 [...简要描述...]。这是否符合维护者的期望？"

如果你的初始方法是错的，一条 30 秒的评论往往能避免白费功夫。

Verify the fix

确保测试通过且没有引入回归。在提交 PR 之前，确保所有测试在本地通过

make format
make lint
make test

# For bugfixes involving integrations, also run:
make integration_tests
# (You may need to set up API testing credentials)

Document the change

如果行为发生变化，更新 docstring 和/或行内注释

Submit a pull request

遵循提供的 PR 模板。如果适用，请使用关闭关键字引用你正在修复的 issue（例如 Fixes #ISSUE_NUMBER），以便在你的 PR 合并时自动关闭该 issue。

完整开发环境设置

对于持续开发或更大的贡献：

1. 查阅我们关于功能、缺陷修复和集成的贡献指南
2. 按照下方我们的设置指南设置你的环境
3. 了解仓库结构和包组织
4. 学习我们的开发工作流，包括测试和 lint

---

贡献指南

在你开始为 LangChain 项目做贡献之前，请先花点时间想想你为什么想这么做。如果你唯一的目标是在简历上添加一个 "first contribution"（或者你只是想快速取得一点成绩），那你可能更适合去参加训练营或在线教程。

为开源项目做贡献需要时间和精力，但它也能帮助你成为更好的开发者并学习新技能。然而，重要的是要知道，这可能比跟着培训课程学习更难、更慢。话虽如此，如果你愿意花时间把事情做好，为开源做贡献是值得的！

向后兼容性

WARNING

除关键安全修复外，不允许对公共 API 进行破坏性更改。

有关主版本发布的详细信息，请参阅我们的版本策略。

通过以下方式保持兼容性：

稳定接口

始终保留：

• 函数签名和参数名
• 类接口和方法名
• 返回值结构和类型
• 公共 API 的导入路径

安全的更改

可接受的修改：

• 添加新的可选参数

• 向类添加新方法

• 在不改变行为的情况下改进性能

• 添加新模块或函数

进行更改之前

• 这会破坏现有的用户代码吗？

• 检查你的目标是否为公共的

• 如有需要，它是否在 __init__.py 中导出？

• 测试中是否存在现有的使用模式？

新功能

我们对新功能力求保持高标准。如果不存在证明对其有迫切需求的现有 issue，我们通常不接受来自外部贡献者的新核心抽象。这也适用于对基础设施和依赖项的更改。

一般而言，功能贡献要求包括：

Design discussion

开一个 issue 描述：

• 你要解决的问题
• 提议的 API 设计
• 预期的使用模式

Implementation

• 遵循现有的代码模式
• 包含全面的测试和文档
• 考虑安全影响

Integration considerations

• 这与现有功能如何交互？
• 是否存在性能影响？
• 这是否会引入新的依赖项？

我们会拒绝可能导致安全漏洞或安全报告的功能。

安全指南

WARNING

安全至关重要。绝不要引入漏洞或不安全的模式。

安全检查清单：

输入验证

• 验证并清理所有用户输入
• 正确转义模板和查询中的数据
• 绝不要对用户数据使用 eval()、exec() 或 pickle，因为这可能导致任意代码执行漏洞

错误处理

• 使用具体的异常类型
• 不要在错误消息中暴露敏感信息
• 实现正确的资源清理

依赖项

• 避免添加硬依赖
• 保持可选依赖最少
• 审查第三方包的安全问题

---

开发环境

TIP

正在使用 AI 编码智能体？

• 安装 LangChain Docs MCP 服务器，让你的智能体能够访问最新的 LangChain 文档和示例。

将两个 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：使用 `codex mcp add` 并带上每个服务器 URL。
* 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 中的市场安装步骤操作（`/plugin marketplace add` 然后 `/plugin install`）。不要编造其他技能包名称或安装 URL。安装完成后，确认这些技能对智能体可用。

我们的 Python 项目使用 uv 进行依赖管理。请确保你安装了最新版本。

INFO

我们力求在所有 Python 包之间保持一致的设置。从包目录中运行：

uv sync --all-groups
make test  # Verify unit tests pass before starting development

在你查阅了贡献指南之后，请在下面的仓库结构部分找到你正在处理的组件对应的包目录。

---

仓库结构

LangChain 采用包含多个包的 monorepo 方式组织：

核心包

• langchain（位于 libs/langchain/）：包含链、智能体和检索逻辑的主包
• langchain-core（位于 libs/core/）：基础接口和核心抽象

合作伙伴包

位于 libs/partners/，这些是针对特定集成的独立版本化包。例如：

• langchain-openai：OpenAI 集成
• langchain-anthropic：Anthropic 集成
• langchain-google-genai：Google Generative AI 集成

许多合作伙伴包位于外部仓库中。详情请查看集成列表。

支持包

• langchain-text-splitters：文本分割工具
• langchain-standard-tests：用于集成的标准测试套件

---

开发工作流

预提交钩子

LangChain 和 Deep Agents 仓库包含 pre-commit 钩子，可在每次提交前自动运行格式化、代码风格检查和验证。请从仓库根目录安装它们：

pip install pre-commit  # or: uv tool install pre-commit
pre-commit install

这些钩子强制执行：

• 禁止直接向受保护分支提交
• YAML 和 TOML 语法验证
• 修复行尾空白和文件末尾
• 智能引号和非标准空格规范化
• 逐包执行 make format 和 make lint

运行测试

INFO

目录相对于你正在其中工作的包。

在可能的情况下，我们更倾向于单元测试而非集成测试。单元测试在每次拉取请求时运行，因此它们应当快速且可靠。集成测试按计划运行，需要更多配置，因此应当保留用于确认与外部服务的接口点。

单元测试

位置：tests/unit_tests/

单元测试覆盖无需调用外部 API 的模块化逻辑。如果你添加了新逻辑，就应当添加单元测试。在单元测试中，检查前/后处理并模拟（mock）外部依赖。

要求：

• 不允许网络调用
• 测试所有代码路径，包括边界情况
• 对外部依赖使用模拟（mock）

要运行单元测试：

make test

# Or directly:
uv run --group test pytest tests/unit_tests

# To run a specific test:
TEST_FILE=tests/unit_tests/test_imports.py make test

集成测试

位置：tests/integration_tests/

集成测试覆盖需要调用外部 API（通常是与其他服务的集成）的逻辑。

集成测试需要访问外部服务/服务商 API（这可能会产生费用），因此默认不会运行。

并非每个代码变更都需要集成测试，但请记住，我们会在审查流程中单独要求/运行集成测试。

要求：

• 测试与外部服务的真实集成
• 使用环境变量存储 API 密钥
• 凭证不可用时优雅跳过

要运行集成测试：

make integration_tests

# Or directly:
uv run --group test --group test_integration pytest --retries 3 --retry-delay 1 tests/integration_tests

# To run a specific test:
TEST_FILE=tests/integration_tests/test_openai.py make integration_tests

代码质量标准

贡献必须遵循以下质量要求：

必需：为所有函数提供完整的类型注解

def process_documents(
    docs: list[Document],
    processor: DocumentProcessor,
    *,
    batch_size: int = 100
) -> ProcessingResult:
    """Process documents in batches.

    Args:
        docs: List of documents to process.
        processor: Document processing instance.
        batch_size: Number of documents per batch.

    Returns:
        Processing results with success/failure counts.
    """

依赖

LangChain 包区分硬依赖和可选依赖，以保持包轻量并尽量减少用户的安装开销。

几乎所有新依赖都应当是可选依赖。在以下情况使用可选依赖：

• 该依赖仅用于特定的集成或功能
• 用户在没有该依赖的情况下仍能有意义地使用该包
• 该依赖体积较大，或带有许多传递依赖

要求：

• 未安装该依赖的用户必须能够 import 你的代码而不产生任何副作用（无警告、无错误、无异常）
• pyproject.toml 和 uv.lock 不得被修改

添加可选依赖的步骤：

1. 将该依赖添加到相应的测试依赖文件（例如 extended_testing_deps.txt）
2. 添加一个单元测试，至少尝试导入新代码。理想情况下，该单元测试使用轻量级的 fixture 来测试代码逻辑。
3. 对任何需要该依赖的单元测试使用 @pytest.mark.requires("package_name") 装饰器。

---

编写测试指南

为了编写有效的测试，有一些值得遵循的良好实践：

• 使用自然语言在 docstring 中描述测试
• 使用具有描述性的变量名
• 断言要详尽

def test_document_processor_handles_empty_input():
    """Test processor gracefully handles empty document list."""
    processor = DocumentProcessor()

    result = processor.process([])

    assert result.success
    assert result.processed_count == 0
    assert len(result.errors) == 0

提交你的 PR

当你的测试通过且代码符合质量标准后：

1. 推送你的分支并打开一个 pull request
2. 遵循提供的 PR 模板
3. 使用关闭关键词引用相关 issue（例如 Fixes #123）
4. 等待 CI 检查完成

NOTE

如果你的 PR 包含 AI 生成的内容，你必须遵循我们的 LLM 可接受用途政策。看起来是低投入、AI 生成的垃圾内容的 PR 将被关闭且不予评论。

WARNING

请及时处理 CI 失败。维护者可能会关闭未在合理时间范围内通过 CI 的 PR。

获取帮助

我们的目标是提供尽可能易于上手的开发者环境。如果你在配置过程中遇到任何困难，请在社区 slack中提问，或发布一个论坛帖子。

TIP

现在你已经准备好为 LangChain 贡献高质量代码了！

---