跳到主要内容
欢迎随时贡献代码！无论是修复错误、添加功能还是提高性能，您的贡献都有助于为成千上万的开发者提供更好的开发体验。
在提交大型新功能或重构之前，请先在论坛中讨论您的想法。这确保了与项目目标的一致性并防止重复工作。这不适用于错误修复或小改进，您可以直接通过拉取请求贡献。请务必在您的 PR 描述中链接任何相关问题。使用以在 PR 合并时自动关闭问题。新集成应遵循集成指南。

​
理念

所有代码贡献均应遵循以下核心原则

向后兼容性

维护稳定的公共接口并避免破坏性更改

测试优先

每项更改都必须包含全面的测试以验证正确性并防止回归

代码质量

遵循一致的样式、文档和架构模式

安全优先

优先考虑安全编码实践和漏洞预防

​
入门

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

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

分叉仓库

将 LangChain 或 LangGraph 仓库分叉到您的
2

克隆并设置

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

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

# For LangGraph:
git clone https://github.com/parrot123/langgraph.git

# Inside your repo, install dependencies
uv sync --all-groups
如果您之前没有安装 uv，则需要安装它。
3

创建分支

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

进行更改

在遵循我们的代码质量标准的同时修复错误
5

添加测试

包括如果没有您的修复将失败的单元测试。这使我们能够验证错误已解决并防止回归
6

运行测试

在提交 PR 之前，确保所有测试都在本地通过
make lint
make test

# For bugfixes involving integrations, also run:
make integration_tests
7

提交拉取请求

遵循提供的 PR 模板。如果适用，使用关闭关键字（例如 Fixes #123）引用您正在修复的问题。

​
完整的开发设置

对于正在进行的开发或较大贡献
1

开发环境

按照下面的设置指南设置您的环境
2

仓库结构

了解仓库结构和包组织
3

开发工作流程

学习我们的开发工作流程，包括测试和代码检查
4

贡献指南

查阅我们关于功能、错误修复和集成的贡献指南

​
开发环境

我们的 Python 项目使用 uv 进行依赖管理。请确保您已安装最新版本。
为您正在处理的包设置开发环境。
  • LangChain
  • LangGraph
用于更改 langchain-core
cd libs/core
uv sync --all-groups
make test  # Ensure tests pass before starting development
用于更改 langchain
cd libs/langchain
uv sync --all-groups
make test  # Ensure tests pass before starting development
用于更改合作伙伴集成
cd libs/partners/langchain-{partner}
uv sync --all-groups
make test  # Ensure tests pass before starting development
用于更改社区集成（位于单独的仓库中）
cd libs/community/langchain_community/path/to/integration
uv sync --all-groups
make test  # Ensure tests pass before starting development

​
仓库结构

  • LangChain
  • LangGraph
LangChain 以多包单体仓库的形式组织

核心包

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

​
开发工作流程

​
测试要求

目录是相对于您正在处理的包的。
每项代码更改都必须包含全面的测试。
1

单元测试

位置：tests/unit_tests/要求：
  • 不允许进行网络调用
  • 测试所有代码路径，包括边界情况
  • 对外部依赖使用模拟
make test
# Or directly:
uv run --group test pytest tests/unit_tests
2

集成测试

集成测试需要访问外部服务/提供商 API（这可能需要付费），因此默认情况下不会运行。并非每个代码更改都需要集成测试，但请记住，我们将在审查过程中单独要求/运行集成测试。位置：tests/integration_tests/要求：
  • 使用外部服务测试真实集成
  • 对 API 密钥使用环境变量
  • 如果凭据不可用，则优雅跳过
make integration_tests
3

测试质量检查表

  • 当您的代码损坏时，测试会失败
  • 边界情况和错误条件已测试
  • 正确使用 fixture 和 mock

​
代码质量标准

质量要求
  • 类型提示
  • 文档
  • 代码风格
必需：所有函数都必须有完整的类型注解
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.
    """

​
手动格式化和代码检查

代码格式和代码检查通过 CI/CD 执行。在提交之前运行这些命令，以确保您的代码通过检查。
运行格式化和代码检查
1

格式化代码

make format
2

运行代码检查

make lint
3

验证更改

这两个命令都将显示需要在提交之前解决的任何格式化或代码检查问题。

​
贡献指南

​
向后兼容性

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

​
错误修复

对于错误修复贡献
1

重现问题

创建演示错误的最小测试用例。维护者和其他贡献者应该能够在无需额外设置或修改的情况下运行此测试并看到失败
2

编写失败测试

添加如果没有您的修复就会失败的单元测试
3

实施修复

进行必要的最小更改以解决问题
4

验证修复

确保测试通过且没有引入回归
5

记录更改

如果行为发生变化，更新文档字符串；对于复杂逻辑，添加注释

​
新功能

我们旨在保持新功能的高门槛。我们通常不接受来自外部贡献者的新核心抽象、基础架构更改、依赖项更改或新的代理/链，除非有现有问题表明其迫切需求。 一般来说，功能贡献要求包括：
1

设计讨论

提出问题，描述
  • 您正在解决的问题
  • 提议的 API 设计
  • 预期使用模式
2

实施

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

集成注意事项

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

​
安全指南

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

​
测试和验证

​
本地运行测试

在提交 PR 之前，请确保您已完成以下步骤。请注意，LangChain 和 LangGraph 的要求略有不同。
  • LangChain
  • LangGraph
1

单元测试

make test
所有单元测试必须通过
2

集成测试

make integration_tests
（如果您的更改影响集成，则运行）
3

格式化

make format
make lint
代码必须通过所有样式检查
4

类型检查

make type_check
所有类型提示必须有效
5

PR 提交

推送您的分支并打开拉取请求。遵循提供的表单模板。使用关闭关键字注明相关问题。提交后，请等待并检查以确保 CI 检查通过。如果任何检查失败，请及时解决问题——维护者可能会在合理的时间范围内关闭未通过 CI 的 PR。

​
测试编写指南

为了编写有效的测试，需要遵循一些良好实践
  • 在文档字符串中使用自然语言描述测试
  • 使用描述性变量名
  • 详尽地使用断言
  • 单元测试
  • 集成测试
  • 模拟使用
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

​
获取帮助

我们的目标是提供最易于访问的开发者设置。如果您在设置过程中遇到任何困难，请在社区 Slack 中提问或发布论坛帖子。
您现在已准备好为 LangChain 贡献高质量的代码！
在 GitHub 上编辑此页面源文件。
以编程方式连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。
© . This site is unofficial and not affiliated with LangChain, Inc.