开始使用
在提交大型 新功能或重构 之前,请先打开一个 issue 或在 论坛 上发帖进行讨论。这可以确保与项目目标保持一致,并防止重复工作。
快速修复:提交错误修复
对于简单的错误修复,您可以立即开始:Fork 仓库
将 LangChain、LangGraph 或 Deep Agents 仓库 Fork 到您的
编写失败测试
添加如果不应用您的修复就会失败的 单元测试。这使我们能够验证错误已解决并防止回归
进行更改
按照我们的 代码质量标准 修复错误。进行 必要的最小更改 以解决问题。我们强烈建议贡献者在开始编码之前对 issue 发表评论。例如:
“I’d like to work on this. My intended approach would be to […brief description…]. Does this align with maintainer expectations?”30 秒的评论通常可以防止因您的初始方法错误而浪费精力。
提交一个 pull request
遵循提供的 PR 模板。如果适用,请使用 关闭关键字(例如
Fixes #ISSUE_NUMBER)引用您正在修复的 issue,以便在合并您的 PR 时自动关闭该 issue。完整的开发设置
对于持续的开发或较大的贡献:贡献指南
在开始为 LangChain 项目做贡献之前,请花点时间思考一下您为什么要这样做。如果您唯一的目标是在简历中添加“第一次贡献”(或者如果您只是想寻求速胜),那么您最好参加训练营或在线教程。 为开源项目做贡献需要时间和精力,但它也可以帮助您成为更好的开发者并学习新技能。但是,重要的是要知道,这可能比遵循培训课程更难、更慢。也就是说,如果您愿意花时间把事情做好,那么为开源做贡献是值得的!向后兼容性
通过以下方式保持兼容性:稳定的接口
稳定的接口
始终保留:
- 函数签名和参数名称
- 类接口和方法名称
- 返回值结构和类型
- 公共 API 的导入路径
安全的更改
安全的更改
可接受的修改:
- 添加新的可选参数/类型参数
- 向类添加新方法
- 在不改变行为的情况下提高性能
- 添加新模块或函数
在进行更改之前
在进行更改之前
- 这会破坏现有的用户代码吗?
- 检查您的目标是否公开
- 测试中是否存在现有的使用模式?
新功能
我们的目标是对新功能保持高标准。我们通常不接受来自外部贡献者的新的核心抽象,除非存在表明迫切需要它们的现有 issue。这也适用于对基础设施和依赖项的更改。 一般来说,功能贡献要求包括:安全指南
安全检查清单:输入验证
输入验证
- 验证并清理所有用户输入
- 正确转义模板和查询中的数据
-
切勿使用
eval(),因为这会导致任意代码执行漏洞
错误处理
错误处理
- 使用特定的异常类型
- 不要在错误消息中暴露敏感信息
- 实施适当的资源清理
依赖项
依赖项
- 避免添加硬依赖
- 保持可选依赖项最小化
- 审查第三方包的安全问题
开发环境
我们努力保持所有 JS/TS 包的设置一致。从仓库根目录运行:
仓库结构
- LangChain
- LangGraph
- Deep Agents
LangChain 被组织为一个包含多个包的单一仓库(monorepo):
核心包
核心包
langchain(位于libs/langchain/): 包含链、代理和检索逻辑的主包@langchain/core(位于libs/langchain-core/): 基础接口和核心抽象
合作伙伴包
合作伙伴包
位于
libs/providers/,这些是用于特定集成的独立版本包。例如:支持包
支持包
@langchain/textsplitters: 文本分割实用程序@langchain/standard-tests: 集成的标准测试套件langchain-community: 社区维护的集成
开发工作流程
运行测试
目录是相对于您正在使用的包的。
单元测试
位置:src/tests/FILENAME_BEING_TESTED.test.ts
单元测试涵盖不需要调用外部 API 的模块化逻辑。如果您添加新逻辑,则应添加单元测试。在单元测试中,检查前/后处理并模拟外部依赖项。
要求:
- 不允许网络调用
- 测试所有代码路径,包括边缘情况
- 对外部依赖项使用 mocks
集成测试
位置:src/tests/FILENAME_BEING_TESTED.int.test.ts
集成测试涵盖需要调用外部 API(通常是与其他服务集成)的逻辑。
集成测试需要访问外部服务/提供商 API(可能需要付费),因此默认情况下不运行。
并非每个代码更改都需要集成测试,但请记住,作为审查过程的一部分,我们将单独要求/运行集成测试。
要求:
- 测试与外部服务的真实集成
- 使用环境变量作为 API 密钥
- 如果凭据不可用,请优雅地跳过
代码质量标准
贡献必须遵守以下质量要求:- 类型提示
- 文档
- 代码风格
必需: 所有函数的完整类型
测试编写指南
为了编写有效的测试,有一些好的做法需要遵循:- 将测试封装在描述正在测试的组件的
describe块中 - 使用自然语言描述测试名称
- 详尽的断言
- 仅对大小合理的数据对象使用快照
- 单元测试
- 集成测试
- Mock 使用
提交您的 PR
一旦您的测试通过且代码符合质量标准:- 推送您的分支并打开一个 pull request
- 遵循提供的 PR 模板
- 使用 关闭关键字(例如,
Fixes #123)引用相关 issue - 等待 CI 检查完成
获得帮助
我们的目标是拥有尽可能简单的开发者设置。如果您在设置过程中遇到任何困难,请在 社区 slack 中提问或打开一个 论坛帖子。您现在已准备好向 LangChain 贡献高质量的代码!
通过 MCP 将 这些文档 连接到 Claude、VSCode 等,以获得实时解答。

