Reproduce the issue

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

Fork the repository

将 LangChain, LangGraph, or Deep Agents 仓库分叉到您的 个人 GitHub 账户

Clone and setup

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

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

        # Inside your repo, initialize environment and install dependencies
        uv venv && source .venv/bin/activate
        uv sync --all-groups

        # or, to install a specific group only:
        uv sync --group test
        

您需要安装 uv 如果您之前没有安装过

Create a branch

为您的修复创建一个新分支。这有助于保持您的更改井然有序，并使以后提交拉取请求更加容易。

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

Write failing tests

添加 单元测试 来确保修复后能通过。这样我们可以验证问题已解决并防止回归

Make your changes

修复错误时遵循我们的 代码质量标准。进行 **最小必要更改** 来解决问题。我们强烈鼓励贡献者在开始编码之前先在问题上评论。例如：

> *"我想处理这个问题。我的预期方法是[...简要描述...]。这是否符合维护者的期望？"*

30 秒的评论通常可以防止在您最初的方法错误时浪费精力。

Verify the fix

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

        make format
        make lint
        make test

        # For bugfixes involving integrations, also run:
        make integration_tests
        # (You may need to set up API testing credentials)
        

Document the change

Update docstrings and/or inline comments if behavior changes

Submit a pull request

请遵循提供的 PR 模板。如果适用，请使用 关闭关键字 (e.g. Fixes #ISSUE_NUMBER以便在您的PR合并时自动关闭该问题。

Stable interfaces

始终保留:

- 函数签名和参数名称 - 类接口和方法名称 - 返回值结构和类型 - 公共API的导入路径

Safe changes

可接受的修改:

• - 添加新的可选参数

- 向类添加新方法 - 在不改写行为的情况下提高性能 - 添加新模块或函数

Before making changes

• 这会破坏现有用户代码吗？
• - 检查您的目标是否是公共的
• - 如果需要，它是否在以下位置导出 __init__.py?

- 测试中是否有现有的使用模式？

Design discussion

打开一个问题描述：

- 您要解决的问题 - 拟议的API设计 - 预期的使用模式

Implementation

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

Integration considerations

• - 这如何与现有功能交互？
• - 是否有性能影响？
• - 这是否引入新的依赖项？

我们将拒绝可能导致安全漏洞或报告的功能。

Input validation

• - 验证并清理所有用户输入
• - 正确转义模板和查询中的数据
• - 切勿使用 eval(), exec(), or pickle 处理用户数据，因为这可能导致任意代码执行漏洞

Error handling

- 使用特定的异常类型 - 不要在错误消息中暴露敏感信息 - 实施适当的资源清理

Dependencies

- 避免添加硬依赖 - 将可选依赖项保持在最少 - 检查第三方包的安全问题

LangChain

LangChain 被组织为一个包含多个包的单体仓库：

LangGraph

LangGraph 采用多包 monorepo 结构组织：

Deep Agents

Deep Agents 采用多包 monorepo 结构组织：

Type hints

必需：为所有函数提供完整的类型注解

        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.
            """
        

Documentation

必需: Google 风格的文档字符串 用于所有公共函数。

指导原则：文档字符串描述"是什么"；此站点的文档解释"如何"和"为什么"。

文档字符串应包含：

1. One-line summary of what the class/function does
2. 链接到本站点以获取教程、指南和使用模式
3. 包含类型和描述的参数文档
4. 返回值描述
5. 可能引发的异常
6. Single minimal example showing basic instantiation/usage as necessary

                class ChatAnthropic(BaseChatModel):
                    """Interface to Claude chat models.

                    See the [usage guide](https://docs.langchain.com/oss/python/integrations/chat/anthropic)
                    for tutorials, feature walkthroughs, and examples.

                    Args:
                        model: Model identifier (e.g., `'claude-sonnet-4-6'`).
                        temperature: Sampling temperature between `0` and `1`.
                        max_tokens: Maximum number of tokens to generate.
                        api_key: Anthropic API key.

                            If not provided, reads from the `ANTHROPIC_API_KEY`
                            environment variable.
                        timeout: Request timeout in seconds.
                        max_retries: Maximum number of retries for failed requests.

                    Returns:
                        A chat model instance that can be invoked with messages.

                    Raises:
                        ValueError: If the model identifier is not recognized.
                        AuthenticationError: If the API key is invalid.

                    Example:
                        

                    """
                

                    """
                    ...

                    See the [extended thinking guide](https://docs.langchain.com/oss/integrations/chat/anthropic#extended-thinking)
                    for configuration options.
                    """
                    

                    """
                    Example:
                        \`\`\`python
                        message = HumanMessage(content=[
                            {"type": "image", "url": "https://example.com/image.jpg"}
                        ])
                        \`\`\`

                    See the [multimodal guide](https://docs.langchain.com/oss/integrations/chat/anthropic#multimodal)
                    for all supported input formats.
                    """
                    

Code style

自动化：通过以下方式进行格式化和检查 ruff

        make format  # Apply formatting
        make lint    # Check style and types
        

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

Optional dependencies

几乎所有新依赖都应该是可选的。使用可选依赖的场景：

• - 该依赖仅在特定集成或功能时才需要
• - 用户可以在没有此依赖的情况下有意义地使用该包
• - 该依赖很大或有很多传递依赖

Requirements:

• - 未安装该依赖的用户必须能够 **导入** 你的代码而没有任何副作用（无警告、无错误、无异常）
• - pyproject.toml 并且 uv.lock 是 **不** 被修改

添加可选依赖：

1. 将依赖添加到相应的测试依赖文件中（例如， extended_testing_deps.txt) 2. 添加一个至少尝试导入新代码的单元测试。理想情况下，该单元测试使用轻量级 fixture 来测试代码逻辑。 3. 使用 @pytest.mark.requires("package_name") 装饰器来处理需要该依赖的单元测试。

Hard dependencies

硬依赖在用户安装包时会自动安装。仅在以下情况下使用硬依赖：

• - 此包在没有该依赖的情况下根本无法运行
• - 该依赖很小，且具有最少的传递依赖
• - 没有合理的方法使该功能变为可选

添加硬依赖：

1. 提交一个问题或讨论，解释为什么该依赖必须是硬依赖而非可选依赖 2. 将依赖添加到 pyproject.toml 下的相应部分 3. 运行 uv lock 来更新 lockfile 4. 包含覆盖新功能的全面测试

Unit tests

        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
        

Integration tests

        @pytest.mark.requires("openai")
        def test_openai_chat_integration():
            """Test OpenAI chat integration with real API."""

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

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

Mock usage

        def test_retry_mechanism(mocker):
            """Test retry mechanism handles transient failures."""
            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