代码贡献指南

我们始终欢迎代码贡献！无论是修复错误、添加功能还是提升性能，您的贡献都将帮助为数以千计的开发者提供更好的开发体验。

在提交大型新功能或重构之前，请先在论坛中讨论您的想法。这有助于确保与项目目标一致，并避免重复工作。

此要求不适用于错误修复或小型改进，您可以直接通过拉取请求贡献这些内容。请务必在PR描述中链接任何相关的问题。使用关闭关键词以便在PR合并时自动关闭问题。

新的集成应遵循集成指南。

核心理念

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

向后兼容

保持稳定的公共接口，避免破坏性变更

测试优先

每次变更必须包含全面的测试，以验证正确性并防止回归

代码质量

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

安全为重

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

---

开始贡献

快速修复：提交错误修复

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

1. 复刻仓库

   将 LangChain 或 LangGraph 仓库复刻到您的个人 GitHub 账户

2. 克隆与设置

   git clone https://github.com/您的用户名/复刻的仓库名.git
   
   # 例如，对于 LangChain：
   git clone https://github.com/parrot123/langchain.git
   
   # 对于 LangGraph：
   git clone https://github.com/parrot123/langgraph.git
   

   # 在您的仓库内，安装依赖
   uv sync --all-groups
   

   如果您之前没有安装过 uv，则需要先安装。

3. 创建分支

   git checkout -b 您的用户名/简短的错误修复名称
   
4. 进行修改

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

5. 添加测试

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

6. 运行测试

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

   make lint
   make test
   
   # 对于涉及集成的错误修复，还需运行：
   make integration_tests
   
7. 提交拉取请求

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

完整开发设置

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

1. 开发环境

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

2. 仓库结构

   了解仓库结构和包组织方式

3. 开发工作流

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

4. 贡献指南

   查看我们的贡献指南，了解功能、错误修复和集成的相关内容

开发环境

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

为您正在处理的包设置开发环境。

LangChain

核心抽象

对于 langchain-core 的更改：

cd libs/core
uv sync --all-groups
make test  # 在开始开发前确保测试通过

主包

对于 langchain 的更改：

cd libs/langchain
uv sync --all-groups
make test  # 在开始开发前确保测试通过

合作伙伴包

对于合作伙伴集成的更改：

cd libs/partners/langchain-{partner}
uv sync --all-groups
make test  # 在开始开发前确保测试通过

社区包

对于社区集成（位于单独的仓库）的更改：

cd libs/community/langchain_community/path/to/integration
uv sync --all-groups
make test  # 在开始开发前确保测试通过

LangGraph

正在开发中 - 即将推出！在此期间，请遵循 LangChain 的说明。

---

仓库结构

LangChain

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-cli：命令行界面
• langchain-community：社区维护的集成（位于单独的仓库中）

LangGraph

正在开发中 - 即将推出！在此期间，请遵循 LangChain 的说明。

---

开发工作流

测试要求

目录路径是相对于您正在处理的包而言的。

每次代码变更都必须包含全面的测试。

1. 单元测试

   位置：tests/unit_tests/

   要求：

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

   make test
   # 或者直接运行：
   uv run --group test pytest tests/unit_tests
   
2. 集成测试

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

   并非每次代码变更都需要集成测试，但请注意，我们将在审查过程中单独要求/运行集成测试。

   位置：tests/integration_tests/

   要求：

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

   make integration_tests
   
3. 测试质量检查清单

   • 当您的代码出错时，测试会失败
   • 测试了边界情况和错误条件
   • 正确使用了夹具和模拟

代码质量标准

质量要求：

类型提示

必需：所有函数都需要完整的类型注解

def process_documents(
    docs: list[Document],
    processor: DocumentProcessor,
    *,
    batch_size: int = 100
) -> ProcessingResult:
    """批量处理文档。

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

    返回：
        包含成功/失败计数的处理结果。
    """

文档

必需：所有公共函数都需要Google 风格文档字符串

• 记录所有参数和返回值
• 对于复杂函数，包含使用示例
• 记录引发的异常
• 关注”为什么”而非”是什么”

代码风格

自动化：通过 ruff 进行格式化和代码检查

make format  # 应用格式化
make lint    # 检查风格和类型

标准：

• 描述性的变量名
• 拆分复杂函数（目标少于 20 行）
• 遵循代码库中的现有模式

手动格式化和代码检查

代码格式化和代码检查通过 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

1. 单元测试

   make test
   

   所有单元测试必须通过

2. 集成测试

   make integration_tests
   

   （如果您的更改影响集成，请运行）

3. 格式化

   make format
   make lint
   

   代码必须通过所有风格检查

4. 类型检查

   make type_check
   

   所有类型提示必须有效

5. PR 提交

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

LangGraph

正在开发中 - 即将推出！在此期间，请遵循 LangChain 的说明。

测试编写指南

为了编写有效的测试，有几个良好实践需要遵循：

• 在文档字符串中使用自然语言描述测试
• 使用描述性的变量名
• 断言要详尽

单元测试

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

集成测试

@pytest.mark.requires("openai")
def test_openai_chat_integration():
    """使用真实 API 测试 OpenAI 聊天集成。"""

    chat = ChatOpenAI()
    response = chat.invoke("Hello")

    assert isinstance(response.content, str)
    assert len(response.content) > 0

模拟使用

def test_retry_mechanism(mocker):
    """测试重试机制能否处理瞬时故障。"""
    mock_client = mocker.Mock()
    mock_client.call.side_effect = [
        ConnectionError("临时故障"),
        {"result": "success"}
    ]

    service = APIService(client=mock_client)
    result = service.call_with_retry()

    assert result["result"] == "success"
    assert mock_client.call.call_count == 2

获取帮助

我们的目标是提供尽可能易于使用的开发者设置。如果您在设置过程中遇到任何困难，请在社区 Slack 中提问或打开论坛帖子。

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

---

在 GitHub 上编辑此页面的源代码。

以编程方式连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。