Skip to main content
欢迎贡献代码！无论是修复错误、添加功能还是改进性能，您的贡献都将帮助为数千名开发者提供更好的开发体验。

​
快速入门

如果您正在寻找可以着手的工作，请查看我们仓库中标记为 “help wanted” 的问题：

LangChain

Labels

LangGraph

Labels

Deep Agents

Labels
在提交大型新功能或重构之前，请先创建一个 issue 或在论坛发帖讨论。这有助于确保与项目目标保持一致，并避免重复工作。

​
快速修复：提交错误修复

对于简单的错误修复，您可以立即开始：
1

重现问题

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

复刻仓库

将 LangChain、LangGraph 或 Deep Agents 仓库复刻到您的
3

克隆与设置

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

# 例如，对于 LangChain：
git clone https://github.com/parrot123/langchain.git

# 在您的仓库内部，初始化环境并安装依赖
uv venv && source .venv/bin/activate
uv sync --all-groups

# 或者，仅安装特定组：
uv sync --group test
如果您之前没有安装过 uv，则需要安装它。
4

创建分支

为您的修复创建一个新分支。这有助于保持更改的组织性，并使后续提交拉取请求更加容易。
git checkout -b your-username/short-bugfix-name
5

编写失败的测试

添加在没有您的修复时会失败的单元测试。这使我们能够验证错误是否已解决，并防止回归。
6

进行更改

在遵循我们的代码质量标准的同时修复错误。进行解决问题所必需的最小更改。我们强烈建议贡献者在开始编码之前先对 issue 发表评论。例如：
“我想解决这个问题。我打算的方法是 […简要描述…]。这符合维护者的期望吗？”
如果您的初始方法是错误的，30 秒的评论通常可以避免浪费精力。
7

验证修复

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

# 对于涉及集成的错误修复，还要运行：
make integration_tests
# （您可能需要设置 API 测试凭据）
8

记录更改

如果行为发生变化，请更新文档字符串和/或内联注释。
9

提交拉取请求

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

​
完整开发设置

对于持续开发或较大的贡献：
  1. 查看我们的贡献指南（针对功能、错误修复和集成）
  2. 按照下面的设置指南设置您的环境
  3. 了解仓库结构和包组织
  4. 学习我们的开发工作流，包括测试和代码检查

​
贡献指南

在开始为 LangChain 项目贡献代码之前，请花点时间思考一下您为什么要这样做。如果您唯一的目标是在简历上增加一个“首次贡献”（或者您只是想快速获胜），那么参加训练营或在线教程可能更适合您。 为开源项目贡献代码需要时间和精力，但它也可以帮助您成为更好的开发者并学习新技能。然而，重要的是要知道，这可能比参加培训课程更难、更慢。话虽如此，如果您愿意花时间把事情做好，为开源做贡献是值得的！

​
向后兼容性

除关键安全修复外，不允许对公共 API 进行破坏性更改。有关主要版本发布的详细信息，请参阅我们的版本控制政策。
通过以下方式保持兼容性：
始终保留：
  • 函数签名和参数名称
  • 类接口和方法名称
  • 返回值结构和类型
  • 公共 API 的导入路径
可接受的修改：
  • 添加新的可选参数
  • 向类添加新方法
  • 在不改变行为的情况下提高性能
  • 添加新模块或函数
  • 这会破坏现有的用户代码吗？
  • 检查您的目标是否是公开的
  • 如果需要，它是否在 __init__.py 中导出？
  • 测试中是否有现有的使用模式？

​
新功能

我们旨在对新功能保持高标准。通常，如果没有现有问题表明对核心抽象有迫切需求，我们不接受外部贡献者提供的新核心抽象。这也适用于对基础设施和依赖项的更改。 通常，功能贡献要求包括：
1

设计讨论

打开一个 issue，描述：
  • 您要解决的问题
  • 提议的 API 设计
  • 预期的使用模式
2

实现

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

集成考虑因素

  • 这将如何与现有功能交互？
  • 是否有性能影响？
  • 这会引入新的依赖项吗？
我们将会拒绝可能导致安全漏洞或报告的功能。

​
安全指南

安全至关重要。切勿引入漏洞或不安全的模式。
安全检查表：
  • 验证并清理所有用户输入
  • 在模板和查询中正确转义数据
  • 切勿对用户数据使用 eval()、exec() 或 pickle，因为这可能导致任意代码执行漏洞
  • 使用特定的异常类型
  • 不要在错误消息中暴露敏感信息
  • 实现正确的资源清理
  • 避免添加硬依赖项
  • 保持可选依赖项最少
  • 审查第三方包的安全问题

​
开发环境

使用 AI 编码代理？ 安装 LangChain Skills 以提高您的代理在 LangChain 生态系统任务上的性能，然后单击本页右上角的“复制页面”按钮，将原始内容粘贴到您的代理中，让它自动设置您的环境。
我们的 Python 项目使用 uv 进行依赖管理。请确保您安装了最新版本。
我们努力在所有 Python 包中保持设置一致。从包目录中运行：
uv sync --all-groups
make test  # 在开始开发之前验证单元测试是否通过
一旦您查看了贡献指南，请在下面的仓库结构部分找到您正在处理的组件的包目录。

​
仓库结构

LangChain 组织为一个包含多个包的 monorepo：

核心包

  • langchain（位于 libs/langchain/）：包含链、代理和检索逻辑的主包
  • langchain-core（位于 libs/core/）：基础接口和核心抽象
位于 libs/partners/，这些是独立版本化的特定集成包。例如：许多合作伙伴包位于外部仓库中。请查看集成列表了解详情。

​
开发工作流

​
Pre-commit 钩子

LangChain 和 Deep Agents 仓库包含 pre-commit 钩子，可在每次提交前自动运行格式化、代码检查和验证检查。从仓库根目录安装它们： 
pip install pre-commit  # 或：uv tool install pre-commit
pre-commit install
这些钩子强制执行：
  • 不直接提交到受保护分支
  • YAML 和 TOML 语法验证
  • 修复尾随空格和文件结尾
  • 智能引号和非标准空格规范化
  • 每个包的 make format 和 make lint

​
运行测试

目录是相对于您正在处理的包的。
我们尽可能倾向于使用单元测试而不是集成测试。单元测试在每个拉取请求上运行，因此它们应该快速且可靠。集成测试按计划运行并且需要更多设置，因此它们应保留用于确认与外部服务的接口点。

​
单元测试

位置：tests/unit_tests/ 单元测试涵盖不需要调用外部 API 的模块化逻辑。如果您添加了新逻辑，则应该添加一个单元测试。在单元测试中，检查前/后处理并模拟外部依赖项。 要求：
  • 不允许网络调用
  • 测试所有代码路径，包括边缘情况
  • 对外部依赖项使用模拟
运行单元测试： 
make test

# 或直接运行：
uv run --group test pytest tests/unit_tests

# 运行特定测试：
TEST_FILE=tests/unit_tests/test_imports.py make test

​
集成测试

位置：tests/integration_tests/ 集成测试涵盖需要调用外部 API（通常是与其它服务集成）的逻辑。 集成测试需要访问外部服务/提供者 API（可能需要付费），因此默认情况下不会运行。 并非每个代码更改都需要集成测试，但请记住，我们将作为审查过程的一部分单独要求/运行集成测试。 要求：
  • 测试与外部服务的真实集成
  • 对环境变量使用 API 密钥
  • 如果凭据不可用，则优雅跳过
运行集成测试： 
make integration_tests

# 或直接运行：
uv run --group test --group test_integration pytest --retries 3 --retry-delay 1 tests/integration_tests

# 运行特定测试：
TEST_FILE=tests/integration_tests/test_openai.py make integration_tests

​
代码质量标准

贡献必须遵守以下质量要求：
必需：所有函数的完整类型注解
def process_documents(
    docs: list[Document],
    processor: DocumentProcessor,
    *,
    batch_size: int = 100
) -> ProcessingResult:
    """批量处理文档。

    Args:
        docs: 要处理的文档列表。
        processor: 文档处理实例。
        batch_size: 每批处理的文档数。

    Returns:
        包含成功/失败计数的处理结果。
    """

​
依赖项

LangChain 包区分硬依赖项和可选依赖项，以保持包轻量级并最大限度地减少用户的安装开销。
几乎所有新依赖项都应该是可选的。在以下情况下使用可选依赖项：
  • 依赖项仅用于特定集成或功能
  • 用户可以在没有此依赖项的情况下有意义地使用包
  • 依赖项很大或有许多传递依赖项
要求：
  • 未安装依赖项的用户必须能够导入您的代码而没有任何副作用（无警告、无错误、无异常）
  • pyproject.toml 和 uv.lock 不被修改
添加可选依赖项：
  1. 将依赖项添加到适当的测试依赖项文件中（例如 extended_testing_deps.txt）
  2. 添加一个至少尝试导入新代码的单元测试。理想情况下，单元测试使用轻量级夹具来测试代码的逻辑。
  3. 对任何需要该依赖项的单元测试使用 @pytest.mark.requires("package_name") 装饰器。

​
测试编写指南

为了编写有效的测试，需要遵循一些好的实践：
  • 在文档字符串中使用自然语言描述测试
  • 使用描述性变量名
  • 详尽地使用断言
def test_document_processor_handles_empty_input():
    """测试处理器优雅地处理空文档列表。"""
    processor = DocumentProcessor()

    result = processor.process([])

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

​
提交您的 PR

一旦您的测试通过且代码符合质量标准：
  1. 推送您的分支并打开一个拉取请求
  2. 遵循提供的 PR 模板
  3. 使用关闭关键字（例如 Fixes #123）引用相关问题
  4. 等待 CI 检查完成
如果您的 PR 包含 AI 生成的内容，您必须遵守我们的LLM 可接受使用政策。看起来是低质量、AI 生成的垃圾邮件的 PR 将被关闭，恕不另行评论。
及时处理 CI 失败。维护者可能会关闭在合理时间范围内未通过 CI 的 PR。

​
获取帮助

我们的目标是拥有最易访问的开发者设置。如果您在设置过程中遇到任何困难，请在社区 Slack 中提问或在论坛发帖。
您现在已准备好为 LangChain 贡献高质量的代码！
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.