Skip to main content
永远欢迎代码贡献!无论您是修复错误、添加功能还是改进性能,您的贡献都有助于为成千上万的开发者提供更好的开发体验。

开始使用

在提交大型 新功能或重构 之前,请先打开一个 issue 或在 论坛 上发帖进行讨论。这可以确保与项目目标保持一致,并防止重复工作。

快速修复:提交错误修复

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

复现问题

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

Fork 仓库

LangChainLangGraphDeep Agents 仓库 Fork 到您的
3

克隆并设置

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
4

创建一个分支

为您的修复创建一个新分支。这有助于让您的更改井井有条,并使以后提交 pull request 更加容易。
git checkout -b your-username/short-bugfix-name
5

编写失败测试

添加如果不应用您的修复就会失败的 单元测试。这使我们能够验证错误已解决并防止回归
6

进行更改

按照我们的 代码质量标准 修复错误。进行 必要的最小更改 以解决问题。我们强烈建议贡献者在开始编码之前对 issue 发表评论。例如:
“I’d like to work on this. My intended approach would be to […brief description…]. Does this align with maintainer expectations?”
30 秒的评论通常可以防止因您的初始方法错误而浪费精力。
7

运行构建

运行构建命令以确保包仍然可以正确构建
pnpm build
# or build a specific workspace package
pnpm --filter @langchain/core build
8

验证修复

确保测试通过且未引入回归。在提交 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
9

记录更改

如果行为发生变化,请更新文档字符串和/或内联注释
10

提交一个 pull request

遵循提供的 PR 模板。如果适用,请使用 关闭关键字(例如 Fixes #ISSUE_NUMBER)引用您正在修复的 issue,以便在合并您的 PR 时自动关闭该 issue。

完整的开发设置

对于持续的开发或较大的贡献:
  1. 查看我们关于功能、错误修复和集成的 贡献指南
  2. 按照下面的 设置指南 设置您的环境
  3. 了解 仓库结构 和包组织
  4. 学习我们的 开发工作流程,包括测试和 linting

贡献指南

在开始为 LangChain 项目做贡献之前,请花点时间思考一下您为什么要这样做。如果您唯一的目标是在简历中添加“第一次贡献”(或者如果您只是想寻求速胜),那么您最好参加训练营或在线教程。 为开源项目做贡献需要时间和精力,但它也可以帮助您成为更好的开发者并学习新技能。但是,重要的是要知道,这可能比遵循培训课程更难、更慢。也就是说,如果您愿意花时间把事情做好,那么为开源做贡献是值得的!

向后兼容性

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

新功能

我们的目标是对新功能保持高标准。我们通常不接受来自外部贡献者的新的核心抽象,除非存在表明迫切需要它们的现有 issue。这也适用于对基础设施和依赖项的更改。 一般来说,功能贡献要求包括:
1

设计讨论

打开一个 issue 描述:
  • 您正在解决的问题
  • 提议的 API 设计
  • 预期的使用模式
2

实施

  • 遵循现有的代码模式
  • 包含全面的测试和文档
  • 考虑安全隐患
3

集成注意事项

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

安全指南

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

开发环境

我们的 JS/TS 项目使用 pnpm 进行依赖项管理。确保您安装了最新版本,或者运行 corepack enable(在 Node 24+ 上)以设置所需的 pnpm 版本。
我们努力保持所有 JS/TS 包的设置一致。从仓库根目录运行:
pnpm install
pnpm --filter {package-name} test  # Verify tests pass before starting development
一旦查看了 贡献指南,请在下面的 仓库结构 部分中找到您正在处理的组件的包目录。

仓库结构

LangChain 被组织为一个包含多个包的单一仓库(monorepo):

核心包

  • langchain (位于 libs/langchain/): 包含链、代理和检索逻辑的主包
  • @langchain/core (位于 libs/langchain-core/): 基础接口和核心抽象
位于 libs/providers/,这些是用于特定集成的独立版本包。例如:

开发工作流程

运行测试

目录是相对于您正在使用的包的。
如果可能,我们更倾向于单元测试而不是集成测试。单元测试在每个 pull request 上运行,因此它们应该快速可靠。集成测试按计划运行,需要更多设置,因此应保留用于确认与外部服务的接口点。

单元测试

位置: src/tests/FILENAME_BEING_TESTED.test.ts 单元测试涵盖不需要调用外部 API 的模块化逻辑。如果您添加新逻辑,则应添加单元测试。在单元测试中,检查前/后处理并模拟外部依赖项。 要求:
  • 不允许网络调用
  • 测试所有代码路径,包括边缘情况
  • 对外部依赖项使用 mocks
要运行单元测试:
# Run the entire test suite
pnpm test

# Or run a specific test file
pnpm test src/tests/FILENAME_BEING_TESTED.test.ts

# Or run a specific test function
pnpm test -t "the test that should be run"

集成测试

位置: src/tests/FILENAME_BEING_TESTED.int.test.ts 集成测试涵盖需要调用外部 API(通常是与其他服务集成)的逻辑。 集成测试需要访问外部服务/提供商 API(可能需要付费),因此默认情况下不运行。 并非每个代码更改都需要集成测试,但请记住,作为审查过程的一部分,我们将单独要求/运行集成测试。 要求:
  • 测试与外部服务的真实集成
  • 使用环境变量作为 API 密钥
  • 如果凭据不可用,请优雅地跳过
要运行集成测试:
pnpm test:int

代码质量标准

贡献必须遵守以下质量要求:
必需: 所有函数的完整类型
function processDocuments(
    docs: Document[],
    processor: DocumentProcessor,
    batchSize: number = 100
): ProcessingResult {
    // ...
}

测试编写指南

为了编写有效的测试,有一些好的做法需要遵循:
  • 将测试封装在描述正在测试的组件的 describe 块中
  • 使用自然语言描述测试名称
  • 详尽的断言
  • 仅对大小合理的数据对象使用快照
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);
    });
});

提交您的 PR

一旦您的测试通过且代码符合质量标准:
  1. 推送您的分支并打开一个 pull request
  2. 遵循提供的 PR 模板
  3. 使用 关闭关键字(例如,Fixes #123)引用相关 issue
  4. 等待 CI 检查完成
及时解决 CI 故障。维护者可能会关闭在合理时间内未通过 CI 的 PR。

获得帮助

我们的目标是拥有尽可能简单的开发者设置。如果您在设置过程中遇到任何困难,请在 社区 slack 中提问或打开一个 论坛帖子
您现在已准备好向 LangChain 贡献高质量的代码!