Skip to main content
欢迎贡献代码！无论您是修复错误、添加功能还是改进性能，您的贡献都能为成千上万的开发者带来更好的开发体验。

​
入门

如果您想寻找一些可以参与的工作，请查看我们仓库中标记为“help wanted”的问题：

LangChain

标签

LangGraph

标签

Deep Agents

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

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

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

重现问题

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

Fork 仓库

将 LangChain、LangGraph 或 Deep Agents 仓库 Fork 到您的
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）引用您正在修复的 issue，以便在您的 PR 合并时自动关闭该 issue。

​
完整开发设置

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

​
贡献指南

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

​
向后兼容性

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

​
新功能

我们致力于保持新功能的高标准。我们通常不接受外部贡献者提出的新核心抽象，除非有现有的 issue 证明其迫切需要。这也适用于对基础设施和依赖项的更改。 一般来说，功能贡献要求包括：
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/，这些是针对特定集成的独立版本控制包。例如：许多合作伙伴包位于外部仓库中。请查看集成列表了解详情。

​
开发工作流程

​
预提交钩子

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）引用相关 issue
  4. 等待 CI 检查完成
如果您的 PR 包含 AI 生成的内容，您必须遵守我们的 LLM 可接受使用政策。看起来是低质量、AI 生成的垃圾内容的 PR 将被关闭且不作评论。
及时处理 CI 失败。维护者可能会关闭在合理时间内未通过 CI 的 PR。

​
获取帮助

我们的目标是提供尽可能易于访问的开发者设置。如果您在设置过程中遇到任何困难，请在社区 Slack 中提问或开一个论坛帖子。
您现在已准备好为 LangChain 贡献高质量代码！
将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
在 GitHub 上编辑此页面 或 提交 issue。