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/langchainjs.git

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

        # Inside your repo, install dependencies
        pnpm install
        # Create a build for all packages to resolve workspace dependencies
        pnpm build
        

Create a branch

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

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

Write failing tests

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

Make your changes

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

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

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

Run build

运行构建命令以确保包仍然正确构建

        pnpm build
        # or build a specific workspace package
        pnpm --filter @langchain/core build
        

Verify the fix

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

        pnpm lint
        pnpm test

        # For bugfixes involving integrations, also run:
        pnpm test:int

        # Or run tests in a specific workspace package
        cd libs/langchain-core
        pnpm test
        pnpm lint

        # Or run tests for a specific package from the root of the repo
        pnpm --filter @langchain/core test
        pnpm --filter @langchain/core lint
        

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

可接受的修改:

• - Adding new optional parameters/type parameters

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

Before making changes

• 这会破坏现有用户代码吗？
• - 检查您的目标是否是公共的

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

Design discussion

打开一个问题描述：

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

Implementation

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

Integration considerations

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

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

Input validation

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

Error handling

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

Dependencies

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

LangChain

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

LangGraph

LangGraph 采用多包 monorepo 结构组织：

Deep Agents

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

Type hints

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

        function processDocuments(
            docs: Document[],
            processor: DocumentProcessor,
            batchSize: number = 100
        ): ProcessingResult {
            // ...
        }
        

Documentation

必需: JSDocs 适用于所有导出的函数和接口

        /**
         * Document processing instance.
         */
        interface FooDocumentProcessor {
            /**
             * Process documents in batches.
             *
             * @param docs - List of documents to process.
             * @returns Processing results with success/failure counts.
             */
            process(docs: Document[]): ProcessingResult;
        }

        /**
         * Process documents in batches.
         *
         * @param docs - List of documents to process.
         * @param processor - Document processing instance.
         * @param batchSize - Number of documents per batch.
         * @returns Processing results with success/failure counts.
         */

            docs: Document[],
            processor: DocumentProcessor,
            batchSize: number = 100
        ): ProcessingResult {
            // ...
        }
        

Code style

自动化：格式化和检查：

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

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

Unit tests

        describe("DocumentProcessor", () => {
            it("Should handle empty document list", () => {
                const processor = new DocumentProcessor();
                const result = processor.process([]);

                expect(result.success).toBe(true);
                expect(result.processedCount).toBe(0);
                expect(result.errors).toHaveLength(0);
            });
        });
        

Integration tests

        describe("ChatOpenAI", () => {
            it("Should test with real API", () => {
                const chat = new ChatOpenAI();
                const response = chat.invoke("Hello");
            });
        });
        

Mock usage

        describe("APIService", () => {
            it("Should call with retry", () => {
                const mockClient = new MockClient();
                const service = new APIService(client: mockClient);
                const result = service.callWithRetry();
            });
        });