开始
如果你正在寻找可以着手处理的问题,请查看各仓库中标记为 “help wanted” 的 issue:LangChain
标签
LangGraph
标签
Deep Agents
标签
提交大型新功能或重构之前,请先打开 issue 或在论坛发帖讨论。这可以确保变更与项目目标一致,并避免重复工作。
快速修复:提交 bugfix
对于简单 bugfix,你可以立即开始:Fork 仓库
将 LangChain、LangGraph 或 Deep Agents 仓库 fork 到你的
编写失败测试
添加在没有你的修复时会失败的单元测试。这能验证 bug 已解决,并防止回归。
进行修改
按照代码质量标准修复 bug。做出解决问题所需的最小变更。强烈建议贡献者在开始编码前先在 issue 中留言。例如:
“我想处理这个问题。我的计划方法是 […简短说明…]。这是否符合维护者预期?”30 秒的留言通常可以避免在初始方案不正确时浪费精力。
提交 pull request
按照提供的 PR 模板操作。如果适用,请使用 closing keyword 引用你正在修复的 issue,例如
Fixes #ISSUE_NUMBER,这样 PR 合并时会自动关闭该 issue。完整开发设置
对于持续开发或更大的贡献:贡献指南
在开始为 LangChain 项目贡献之前,请花点时间思考你为什么想贡献。如果你的唯一目标是在简历中添加一次 “first contribution”,或者只是想快速完成一个小任务,你可能更适合参加 boot-camp 或在线教程。 为开源项目贡献需要时间和精力,但它也能帮助你成为更好的开发者并学习新技能。不过,请了解它可能比跟随培训课程更难、更慢。也就是说,如果你愿意花时间把事情做好,贡献开源是值得的。向后兼容性
通过以下方式保持兼容性:稳定接口
稳定接口
始终保留:
- 函数签名和参数名
- 类接口和方法名
- 返回值结构和类型
- 公共 API 的 import 路径
安全变更
安全变更
可接受的修改:
- 添加新的可选参数/type parameter
- 向类添加新方法
- 在不改变行为的情况下提升性能
- 添加新模块或函数
修改前
修改前
- 这会破坏现有用户代码吗?
- 检查你的目标是否为公共接口
- 测试中是否已有使用模式?
新功能
项目对新功能保持较高标准。通常,如果没有现有 issue 展示迫切需求,项目不会接受外部贡献者提出的新核心抽象。这也适用于基础设施和依赖项变更。 一般来说,功能贡献要求包括:安全指南
安全检查清单:输入验证
输入验证
- 验证并清理所有用户输入
- 在模板和查询中正确转义数据
-
不要使用
eval(),因为这可能导致任意代码执行漏洞
错误处理
错误处理
- 使用具体的异常类型
- 不要在错误消息中暴露敏感信息
- 实现正确的资源清理
依赖项
依赖项
- 避免添加硬依赖
- 尽量减少可选依赖
- 检查第三方包是否存在安全问题
开发环境
项目会尽力保持所有 JS/TS 包的设置方式一致。从仓库根目录运行:
仓库结构
- LangChain
- LangGraph
- Deep Agents
LangChain 以 monorepo 形式组织,包含多个包:
核心包
核心包
langchain(位于libs/langchain/):包含 chains、agents 和 retrieval 逻辑的主包@langchain/core(位于libs/langchain-core/):基础接口和核心抽象
Partner 包
Partner 包
这些包位于
libs/providers/,是针对特定集成独立版本化的包。例如:支持包
支持包
@langchain/textsplitters:文本分割工具@langchain/standard-tests:集成的标准测试套件
开发流程
Pre-commit hooks
运行测试
目录路径相对于你正在处理的包。
单元测试
位置:src/tests/FILENAME_BEING_TESTED.test.ts
单元测试覆盖不需要调用外部 API 的模块化逻辑。如果添加新逻辑,你应该添加单元测试。在单元测试中,请检查前处理/后处理,并 mock 外部依赖。
要求:
- 不允许网络调用
- 测试所有代码路径,包括边界情况
- 对外部依赖使用 mock
集成测试
位置:src/tests/FILENAME_BEING_TESTED.int.test.ts
集成测试覆盖需要调用外部 API 的逻辑,通常是与其他服务的集成。
集成测试需要访问外部服务或提供商 API,这可能产生费用,因此默认不会运行。
并非每次代码变更都需要集成测试,但请记住,评审过程中可能会单独要求或运行集成测试。
要求:
- 使用外部服务测试真实集成
- 使用环境变量存储 API key
- 在凭据不可用时优雅跳过
代码质量标准
贡献必须遵循以下质量要求:- 类型提示
- 文档
- 代码风格
必需:所有函数都要有完整类型
测试编写指南
为了编写有效测试,请遵循以下良好实践:- 将测试封装在描述被测组件的
describeblock 中 - 使用自然语言描述测试名称
- 断言要全面
- 只对大小合理的数据对象使用 snapshot
- 单元测试
- 集成测试
- Mock 使用
提交 PR
测试通过且代码符合质量标准后:- 推送分支并打开 pull request
- 遵循提供的 PR 模板
- 使用 closing keyword 引用相关 issue,例如
Fixes #123 - 等待 CI 检查完成
如果你的 PR 包含 AI 生成内容,必须遵循可接受的 LLM 使用方式政策。看起来像低投入 AI 生成垃圾内容的 PR 会被直接关闭且不作评论。
获取帮助
目标是让开发者设置尽可能易于使用。如果在设置过程中遇到任何困难,请在 community slack 提问,或打开论坛帖子。现在你已经准备好为 LangChain 贡献高质量代码了!
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

