> ## Documentation Index > Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt > Use this file to discover all available pages before exploring further. # 代码贡献 欢迎贡献代码！无论您是修复错误、添加功能还是改进性能，您的贡献都能为成千上万的开发者带来更好的开发体验。 ## 入门 如果您想寻找一些可以参与的工作，请查看我们仓库中标记为“help wanted”的问题： 标签 标签 标签 在提交大型**新功能或重构**之前，请先开一个 issue 或在[论坛](https://forum.langchain.com/)上发帖讨论。这可以确保与项目目标保持一致，并防止重复工作。 ### 快速修复：提交错误修复 对于简单的错误修复，您可以立即开始： 在克隆仓库之前，请确保您能够可靠地重现该错误。这有助于确认问题，并为您的修复提供起点。维护者和其他贡献者应该能够根据您的描述重现该问题，而无需额外的设置或修改。 将 [LangChain](https://github.com/langchain-ai/langchain)、[LangGraph](https://github.com/langchain-ai/langgraph) 或 [Deep Agents](https://github.com/langchain-ai/deepagents) 仓库 Fork 到您的个人 GitHub 账户 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} git clone https://github.com/your-username/name-of-forked-repo.git # 例如，对于 LangChain： git clone https://github.com/parrot123/langchain.git ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 在您的仓库内，初始化环境并安装依赖项 uv venv && source .venv/bin/activate uv sync --all-groups # 或者，仅安装特定组： uv sync --group test ``` 如果您之前没有安装过 [`uv`](https://docs.astral.sh/uv/)，则需要安装它。 为您的修复创建一个新分支。这有助于保持您的更改井然有序，并使稍后提交拉取请求更容易。 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} git checkout -b your-username/short-bugfix-name ``` 添加[单元测试](#test-writing-guidelines)，这些测试在没有您的修复的情况下会失败。这使我们能够验证错误已解决，并防止回归。 在遵循我们的[代码质量标准](#code-quality-standards)的同时修复错误。进行**解决该问题所需的最小更改**。我们强烈鼓励贡献者在开始编码之前在 issue 上发表评论。例如： > *“我想处理这个问题。我打算的方法是 \[...简要描述...]。这是否符合维护者的期望？”* 30 秒的评论通常可以防止在您的初始方法错误时浪费精力。 确保测试通过且没有引入回归。在提交 PR 之前，请确保所有测试在本地通过。 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} make format make lint make test # 对于涉及集成的错误修复，还需运行： make integration_tests # （您可能需要设置 API 测试凭据） ``` 如果行为发生变化，请更新文档字符串和/或内联注释。 遵循提供的 PR 模板。如果适用，请使用[关闭关键字](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)（例如 `Fixes #ISSUE_NUMBER`）引用您正在修复的 issue，以便在您的 PR 合并时自动关闭该 issue。 ### 完整开发设置 对于持续开发或较大的贡献： 1. 查阅我们的[贡献指南](#contribution-guidelines)，了解功能、错误修复和集成 2. 按照下面的[设置指南](#development-environment)设置您的环境 3. 了解[仓库结构](#repository-structure)和包组织 4. 了解我们的[开发工作流程](#development-workflow)，包括测试和代码检查 *** ## 贡献指南 在您开始为 LangChain 项目做贡献之前，请花点时间思考一下您为什么想这样做。如果您的唯一目标是在简历上添加“首次贡献”（或者如果您只是想快速获得成功），那么您可能更适合参加训练营或在线教程。 为开源项目做贡献需要时间和精力，但它也可以帮助您成为更好的开发者并学习新技能。然而，重要的是要知道这可能比参加培训课程更困难、更慢。也就是说，如果您愿意花时间把事情做好，那么为开源做贡献是值得的！ ### 向后兼容性 除了关键的安全修复外，不允许对公共 API 进行破坏性更改。 有关主要版本发布的详细信息，请参阅我们的[版本控制策略](/oss/python/versioning)。 通过以下方式保持兼容性： **始终保留**： * 函数签名和参数名称 * 类接口和方法名称 * 返回值结构和类型 * 公共 API 的导入路径 **可接受的修改**： * 添加新的可选参数 * 向类添加新方法 * 在不改变行为的情况下提高性能 * 添加新模块或函数 * **这会破坏现有用户代码吗？** * 检查您的目标是否是公共的 * 如果需要，它是否在 `__init__.py` 中导出？ * 测试中是否存在现有的使用模式？ ### 新功能 我们致力于保持新功能的高标准。我们通常不接受外部贡献者提出的新核心抽象，除非有现有的 issue 证明其迫切需要。这也适用于对基础设施和依赖项的更改。 一般来说，功能贡献要求包括： 开一个 issue 描述： * 您要解决的问题 * 提议的 API 设计 * 预期的使用模式 * 遵循现有的代码模式 * 包括全面的测试和文档 * 考虑安全影响 * 这如何与现有功能交互？ * 是否有性能影响？ * 这是否引入了新的依赖项？ 我们将拒绝那些可能导致安全漏洞或报告的功能。 ### 安全指南 安全至关重要。切勿引入漏洞或不安全的模式。 安全检查清单： * 验证和清理所有用户输入 * 在模板和查询中正确转义数据 * 切勿对用户数据使用 `eval()`、`exec()` 或 `pickle`，因为这可能导致任意代码执行漏洞。 * 使用特定的异常类型 * 不要在错误消息中暴露敏感信息 * 实现适当的资源清理 * 避免添加硬依赖项 * 保持可选依赖项最小化 * 审查第三方包的安全问题 *** ## 开发环境 **使用 AI 编码代理？** 安装 [LangChain Skills](https://github.com/langchain-ai/langchain-skills) 以提高您的代理在 LangChain 生态系统任务上的性能，然后单击此页面右上角的“复制页面”按钮，并将原始内容粘贴到您的代理中，让它自动设置您的环境。 我们的 Python 项目使用 [`uv`](https://docs.astral.sh/uv/getting-started/installation/) 进行依赖管理。确保您安装了最新版本。 我们努力在所有 Python 包中保持设置一致。从包目录运行： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uv sync --all-groups make test # 在开始开发之前验证单元测试是否通过 ``` 一旦您查阅了[贡献指南](#contribution-guidelines)，请在下面的[仓库结构](#repository-structure)部分找到您正在处理的组件的包目录。 *** ## 仓库结构 LangChain 是一个包含多个包的 monorepo： * **[`langchain`](https://github.com/langchain-ai/langchain/tree/master/libs/langchain#readme)**（位于 `libs/langchain/`）：包含链、代理和检索逻辑的主包 * **[`langchain-core`](https://github.com/langchain-ai/langchain/tree/master/libs/core#readme)**（位于 `libs/core/`）：基础接口和核心抽象 位于 `libs/partners/`，这些是针对特定集成的独立版本控制包。例如： * **[`langchain-openai`](https://github.com/langchain-ai/langchain/tree/master/libs/partners/openai#readme)**：[OpenAI](/oss/python/integrations/providers/openai) 集成 * **[`langchain-anthropic`](https://github.com/langchain-ai/langchain/tree/master/libs/partners/anthropic#readme)**：[Anthropic](/oss/python/integrations/providers/anthropic) 集成 * **[`langchain-google-genai`](https://github.com/langchain-ai/langchain-google/)**：[Google Generative AI](/oss/python/integrations/chat/google_generative_ai) 集成 许多合作伙伴包位于外部仓库中。请查看[集成列表](/oss/python/integrations/providers/overview)了解详情。 * **[`langchain-text-splitters`](https://github.com/langchain-ai/langchain/tree/master/libs/text-splitters#readme)**：文本分割工具 * **[`langchain-standard-tests`](https://github.com/langchain-ai/langchain/tree/master/libs/standard-tests#readme)**：集成的标准测试套件 * **[`langchain-community`](https://github.com/langchain-ai/langchain-community)**：社区维护的集成（位于单独的仓库中） LangGraph 是一个包含多个 Python 包的 monorepo： * **[`langgraph`](https://github.com/langchain-ai/langgraph/tree/main/libs/langgraph#readme)**（位于 `libs/langgraph/`）：构建有状态、多参与者代理的核心框架 * **[`langgraph-prebuilt`](https://github.com/langchain-ai/langgraph/tree/main/libs/prebuilt#readme)**（位于 `libs/prebuilt/`）：用于创建和运行代理及工具的高级 API * **[`langgraph-checkpoint`](https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint#readme)**（位于 `libs/checkpoint/`）：检查点保存器的基础接口 * **[`langgraph-checkpoint-postgres`](https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres#readme)**（位于 `libs/checkpoint-postgres/`）：Postgres 实现 * **[`langgraph-checkpoint-sqlite`](https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-sqlite#readme)**（位于 `libs/checkpoint-sqlite/`）：SQLite 实现 * **[`langgraph-sdk`](https://github.com/langchain-ai/langgraph/tree/main/libs/sdk-py#readme)**（位于 `libs/sdk-py/`）：Agent Server API 的 Python SDK * **[`langgraph-cli`](https://github.com/langchain-ai/langgraph/tree/main/libs/cli#readme)**（位于 `libs/cli/`）：官方命令行界面 Deep Agents 是一个包含多个 Python 包的 monorepo： * **[`deepagents`](https://github.com/langchain-ai/deepagents/tree/main/libs/deepagents#readme)**（位于 `libs/deepagents/`）：构建具有规划、文件系统和子代理能力的深度代理的核心框架 * **[`deepagents-cli`](https://github.com/langchain-ai/deepagents/tree/main/libs/cli#readme)**（位于 `libs/cli/`）：具有对话恢复、网络搜索和沙箱功能的交互式终端界面 * **[`deepagents-harbor`](https://github.com/langchain-ai/deepagents/tree/main/libs/harbor#readme)**（位于 `libs/harbor/`）：与 LangSmith 追踪集成的 Harbor 集成 * **[`deepagents-acp`](https://github.com/langchain-ai/deepagents/tree/main/libs/acp#readme)**（位于 `libs/acp/`）：Agent Client Protocol 集成 *** ## 开发工作流程 ### 预提交钩子 [LangChain](https://github.com/langchain-ai/langchain) 和 [Deep Agents](https://github.com/langchain-ai/deepagents) 仓库包含 [pre-commit](https://pre-commit.com/) 钩子，可在每次提交前自动运行格式化、代码检查和验证检查。从仓库根目录安装它们： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} pip install pre-commit # 或：uv tool install pre-commit pre-commit install ``` 钩子强制执行： * 不允许直接提交到受保护的分支 * YAML 和 TOML 语法验证 * 尾随空格和文件末尾修复 * 智能引号和非标准空格规范化 * 每个包的 `make format` 和 `make lint` ### 运行测试 目录是相对于您正在处理的包的。 我们尽可能倾向于单元测试而非集成测试。单元测试在每个拉取请求上运行，因此它们应该快速且可靠。集成测试按计划运行，需要更多设置，因此应保留用于确认与外部服务的接口点。 #### 单元测试 **位置**：`tests/unit_tests/` 单元测试涵盖不需要调用外部 API 的模块化逻辑。如果您添加了新逻辑，则应添加单元测试。在单元测试中，检查预处理/后处理并模拟外部依赖项。 **要求**： * 不允许网络调用 * 测试所有代码路径，包括边缘情况 * 对外部依赖项使用模拟 运行单元测试： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} 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 密钥 * 如果凭据不可用，则优雅地跳过 运行集成测试： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} 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 ``` ### 代码质量标准 贡献必须遵守以下质量要求： **必需**：所有函数的完整类型注解 ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} def process_documents( docs: list[Document], processor: DocumentProcessor, *, batch_size: int = 100 ) -> ProcessingResult: """批量处理文档。 Args: docs: 要处理的文档列表。 processor: 文档处理实例。 batch_size: 每批文档数量。 Returns: 包含成功/失败计数的处理结果。 """ ``` **必需**：所有公共函数的 [Google 风格文档字符串](https://google.github.io/styleguide/pyguide.html)。 **指导原则**：文档字符串描述“是什么”；本站上的文档解释“如何做”和“为什么”。 | 内容类型 | 位置 | 目的 | | ------- | ----- | ------------- | | 参数类型 | 签名 | 自动生成到 API 参考中 | | 参数描述 | 文档字符串 | 自动生成到 API 参考中 | | 返回类型和异常 | 文档字符串 | API 参考 | | 最小使用示例 | 文档字符串 | 显示基本实例化模式 | | 功能教程 | 本站 | 深入演练 | | 端到端示例 | 本站 | 真实用例模式 | | 概念解释 | 本站 | 理解和上下文 | **文档字符串应包含：** 1. 类/函数功能的单行摘要 2. 指向本站的教程、指南和使用模式的链接 3. 带类型和描述的参数文档 4. 返回值描述 5. 可能引发的异常 6. 必要时显示基本实例化/用法的单个最小示例 ````python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} class ChatAnthropic(BaseChatModel): """Claude 聊天模型的接口。 有关教程、功能演练和示例，请参阅[使用指南](https://docs.langchain.com/oss/python/integrations/chat/anthropic)。 Args: model: 模型标识符（例如，`'claude-sonnet-4-6'`）。 temperature: 介于 `0` 和 `1` 之间的采样温度。 max_tokens: 要生成的最大令牌数。 api_key: Anthropic API 密钥。 如果未提供，则从 `ANTHROPIC_API_KEY` 环境变量读取。 timeout: 请求超时时间（秒）。 max_retries: 失败请求的最大重试次数。 Returns: 可以使用消息调用的聊天模型实例。 Raises: ValueError: 如果模型标识符无法识别。 AuthenticationError: 如果 API 密钥无效。 Example: ```python from langchain_anthropic import ChatAnthropic model = ChatAnthropic(model="claude-sonnet-4-6") response = model.invoke("Hello!") ``` """ ```` 避免重复属于文档字符串的内容： * **参数类型**：这些在函数签名中，并自动生成到 API 参考中。 * **功能教程**：不要包含扩展演练。而是链接到本站： ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} """ ... 有关配置选项，请参阅[扩展思考指南](https://docs.langchain.com/oss/integrations/chat/anthropic#extended-thinking)。 """ ``` * **多个示例变体**：包含一个最小示例，然后链接到综合指南： ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} """ Example: \`\`\`python message = HumanMessage(content=[ {"type": "image", "url": "https://example.com/image.jpg"} ]) \`\`\` 有关所有支持的输入格式，请参阅[多模态指南](https://docs.langchain.com/oss/integrations/chat/anthropic#multimodal)。 """ ``` * **概念解释**：坚持事实性的参数描述。链接到文档以获取更深入的上下文。 * **MkDocs 特定语法**：避免在文档字符串中使用 `???+`、手风琴或标签页。它们在 IDE 中无法渲染。 **自动化**：通过 [`ruff`](https://docs.astral.sh/ruff/) 进行格式化和代码检查 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} make format # 应用格式化 make lint # 检查样式和类型 ``` **标准**： * 描述性变量名 * 拆分复杂函数（目标少于 20 行） * 遵循代码库中的现有模式 ### 依赖项 LangChain 包区分**硬依赖项**和**可选依赖项**，以保持包轻量级并最小化用户的安装开销。 几乎所有新依赖项都应该是可选的。在以下情况下使用可选依赖项： * 该依赖项仅用于特定集成或功能 * 用户可以在没有此依赖项的情况下有意义地使用该包 * 该依赖项很大或有许多传递依赖项 **要求：** * 没有安装依赖项的用户必须能够**导入**您的代码而没有任何副作用（没有警告、没有错误、没有异常） * **不**修改 `pyproject.toml` 和 `uv.lock` **添加可选依赖项：** 1. 将依赖项添加到适当的测试依赖项文件（例如 `extended_testing_deps.txt`） 2. 添加一个单元测试，该测试至少尝试导入新代码。理想情况下，单元测试使用轻量级夹具来测试代码的逻辑。 3. 对于任何需要该依赖项的单元测试，使用 `@pytest.mark.requires("package_name")` 装饰器。 硬依赖项在用户安装包时自动安装。仅在以下情况下使用硬依赖项： * 该包没有该依赖项就根本无法运行 * 该依赖项很小且传递依赖项最少 * 没有合理的方法使该功能可选 添加硬依赖项会增加所有用户的安装时间和潜在的版本冲突。 维护者将仔细审查硬依赖项的添加！ **添加硬依赖项：** 1. 开一个 issue 或讨论，解释为什么该依赖项必须是硬依赖项而不是可选依赖项 2. 将依赖项添加到 `pyproject.toml` 的适当部分 3. 运行 `uv lock` 以更新锁文件 4. 包括涵盖新功能的全面测试 *** ### 测试编写指南 为了编写有效的测试，需要遵循一些良好的实践： * 使用自然语言在文档字符串中描述测试 * 使用描述性变量名 * 断言要详尽 ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} 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 ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} @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 ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} def test_retry_mechanism(mocker): """测试重试机制处理暂时性故障。""" mock_client = mocker.Mock() mock_client.call.side_effect = [ ConnectionError("Temporary failure"), {"result": "success"} ] service = APIService(client=mock_client) result = service.call_with_retry() assert result["result"] == "success" assert mock_client.call.call_count == 2 ``` ### 提交您的 PR 一旦您的测试通过且代码符合质量标准： 1. 推送您的分支并打开一个拉取请求 2. 遵循提供的 PR 模板 3. 使用[关闭关键字](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)（例如 `Fixes #123`）引用相关 issue 4. 等待 CI 检查完成 如果您的 PR 包含 AI 生成的内容，您必须遵守我们的 [LLM 可接受使用](/oss/python/contributing/overview#acceptable-uses-of-llms)政策。看起来是低质量、AI 生成的垃圾内容的 PR 将被关闭且不作评论。 及时处理 CI 失败。维护者可能会关闭在合理时间内未通过 CI 的 PR。 ## 获取帮助 我们的目标是提供尽可能易于访问的开发者设置。如果您在设置过程中遇到任何困难，请在[社区 Slack](https://www.langchain.com/join-community) 中提问或开一个[论坛帖子](https://forum.langchain.com/)。 您现在已准备好为 LangChain 贡献高质量代码！ ***
[将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。 [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/contributing/code.mdx) 或 [提交 issue](https://github.com/langchain-ai/docs/issues/new/choose)。