欢迎贡献代码！无论你是修复 bug、添加新功能还是改进性能，你的贡献都能为成千上万的开发者带来更好的开发体验。
开始指南 如果你正在寻找可以工作的项目，请查看我们仓库中带有 “help wanted” 标签的问题：
在提交大型的新功能或重构之前，请先打开一个 issue 或在 论坛 发帖讨论。这可以确保与项目目标保持一致，并避免重复工作。 简单修复：提交 bug 修复 对于简单的 bug 修复，你可以立即开始：
重现问题
在克隆仓库之前，请确保能够可靠地重现该 bug。这有助于确认问题并提供一个起点来解决它。维护者和其他贡献者应能根据你的描述在无需额外设置或修改的情况下重现该问题。
创建分支
为修复的问题创建一个新的分支。这样可以保持更改的组织，并使稍后提交 pull request 更加容易。 git checkout -b your-username/short-bugfix-name
编写失败测试
添加在没有你的修复之前会失败的单元测试。这允许我们验证 bug 已被解决并防止回退。
进行更改
在遵循我们的 代码质量标准 的前提下修复 bug。只需做出解决问题所需的最小变更。我们强烈建议在开始编码之前就问题发表评论。例如：
“我想解决这个问题。我的计划是 [… 简要描述 …]。这与维护者的期望一致吗？” 一个简短的评论通常可以防止如果初始方法错误而导致浪费努力。
验证修复
确保测试通过并且没有引入回退。在提交 pull request 之前确保所有本地测试都已通过。 make format make lint make test # 如果涉及集成，则还需运行： make integration_tests # (可能需要设置 API 测试凭证)
记录变更
更新文档字符串和/或内联注释，如果行为发生变化的话。
提交 pull request
按照提供的 pull request 模板操作。如果适用，请使用 关闭关键字 （例如 Fixes #ISSUE_NUMBER）来引用你正在修复的问题，以便在 pull request 合并时自动关闭问题。 完整开发环境设置 对于持续开发或更大规模的贡献：
请参阅我们的 贡献指南 以了解功能、bug 修复和集成的要求
按照下面提供的 设置指南 设置你的环境
理解仓库结构和包组织
学习我们的 开发工作流 ，包括测试和 linting
贡献指南 在开始为 LangChain 项目贡献代码之前，请花时间思考一下你为什么要这样做。如果你的唯一目标是添加一个“首次贡献”到你的简历（或者只是寻找一个快速胜利），你可能更适合参加培训营或在线教程。
参与开源项目需要时间和努力，但它也可以帮助你成为一个更好的开发者并学习新技能。然而，重要的是要知道这可能比跟随训练课程更难和慢一些。不过，如果你愿意花时间做好事情的话，为开源做出贡献是值得的！
向后兼容性 除非是为了关键的安全修复，否则不允许对公共 API 进行破坏性的更改。 有关主要版本发布的详细信息，请参阅我们的 版本策略 。 保持兼容性的方式：
始终保留 ：
函数签名和参数名称
类的接口和方法名称
返回值结构和类型
公共 API 的导入路径
可接受的修改 ：
添加新的可选参数
为类添加新方法
在不改变行为的情况下提高性能
添加新模块或函数
这个更改是否会破坏现有的用户代码？
检查你的目标是否是公共的
如果需要，它是否导出在 __init__.py 中？
在测试中是否有现有的用法模式？
新功能 我们希望保持新功能的标准很高。通常情况下，除非有现有问题表明它们具有迫切需求，否则我们不会接受来自外部贡献者的新的核心抽象。这同样适用于基础设施和依赖项的更改。
一般而言，新功能贡献的要求包括：
设计讨论
打开一个 issue 来描述：
你解决的问题
提议的 API 设计
预期的使用模式
实现
遵循现有代码模式
包含全面的测试和文档
考虑安全影响
集成考虑
这个功能如何与现有的功能交互？
是否有性能影响？
是否引入了新的依赖项？
我们将拒绝那些可能导致安全漏洞或报告的功能。 安全指南 安全检查清单：
验证和清理所有用户输入
正确地在模板和查询中转义数据
从用户数据中绝不能使用 eval()、exec() 或 pickle，因为这可能导致任意代码执行漏洞
使用特定的异常类型
不要在错误消息中暴露敏感信息
实现适当的资源清理
避免添加硬依赖项
保持可选依赖项最小化
审查第三方包的安全问题
开发环境 使用 AI 编码代理？ 安装 LangChain Skills 以提高你在 LangChain 生态系统任务中的代理性能，然后点击此页面右上角的“复制页面”按钮并粘贴原始内容到你的代理中，使其自动为你设置环境。我们的 Python 项目使用 uv 进行依赖管理。请确保安装了最新版本。
我们力求在所有 Python 包中保持设置的一致性。从包目录运行： uv sync --all-groups make test # 在开始开发之前验证单元测试通过
一旦你已经审阅了 贡献指南 ，请找到你在 仓库结构 部分中工作的组件的包目录。
仓库结构
LangChain 是一个包含多个包的单体仓库：
位于 libs/partners/ 中，这些是为特定集成独立版本的包。例如： 许多合作伙伴包位于外部仓库中。请参阅 集成列表 以获取详细信息。
LangGraph 是一个包含多个 Python 包的单体仓库： Deep Agents 是一个包含多个 Python 包的单体仓库： 开发工作流 预提交钩子 LangChain 和 Deep Agents 仓库包含预提交钩子，这些钩子在每次提交之前自动运行格式化、检查和验证。从仓库根目录安装它们：pip install pre-commit # 或: uv tool install pre-commit pre-commit install
这些钩子强制执行：
不直接向受保护分支提交更改
YAML 和 TOML 语法验证
检查尾随空格和文件末尾的修复
标点符号和非标准空格的规范化
每个包的 make format 和 make lint
运行测试 我们倾向于在可能的情况下使用单元测试而不是集成测试。单元测试会在每次 pull request 中运行，因此它们应该快速且可靠。集成测试按计划运行，并需要更多设置，因此应仅用于确认与外部服务的接口点。
单元测试 位置 : tests/unit_tests/单元测试覆盖不需要调用外部 API 的模块逻辑。如果你添加了新逻辑，你应该添加一个单元测试。在单元测试中检查预处理和后处理，并模拟外部依赖项。
要求 :
不允许网络请求
测试所有代码路径，包括边界情况
使用 mock 对外部依赖项进行测试
运行单元测试：
make test # 或直接： uv run --group test pytest tests/unit_tests # 运行特定的测试： TEST_FILE = tests/unit_tests/test_imports.py make test
集成测试 位置 : tests/integration_tests/集成测试覆盖需要调用外部 API 的逻辑（通常与其他服务进行集成）。
集成测试需要访问外部服务提供程序 API（这可能会产生费用），因此默认情况下不会运行它们。
并非每次代码更改都需要集成测试，但请记住，在我们的审查过程中我们将单独要求并运行集成测试。
要求 :
测试与外部服务的真实集成
使用环境变量来存储 API 密钥
如果凭据不可用，则优雅地跳过
运行集成测试：
make integration_tests # 或直接： uv run --group test --group test_integration pytest --retries 3 --retry-delay 1 tests/integration_tests # 运行特定的测试： TEST_FILE = tests/integration_tests/test_openai.py make integration_tests
代码质量标准 贡献必须遵守以下质量要求：
必需 : 所有函数的完整类型注解def process_documents ( docs : list [ Document ], processor : DocumentProcessor , * , batch_size : int = 100 ) -> ProcessingResult : """按批次处理文档。 参数: docs: 要处理的文档列表。 processor: 文档处理器实例。 batch_size: 每个批次中的文档数量。 返回值: 处理结果，包括成功和失败计数。 """
必需 : 所有公共函数的 Google 风格文档字符串 。指导原则 : 文档字符串描述 “what”；而本站点解释 “how” 和 “why”。内容类型 位置 目的 参数类型 签名 自动生成到 API 参考中 参数描述 文档字符串 自动生成到 API 参考中 返回值和异常 文档字符串 API 参考 最小使用示例 文档字符串 展示基本实例化模式 功能教程 本站点 深入的走查 端到端示例 本站点 实际用法模式 概念解释 本站点 理解和背景
文档字符串应包含:
一句话描述该类/函数的作用
链接到本站点以获取教程、指南和使用模式
参数说明，包括类型和描述
返回值描述
可能抛出的异常
单个最小示例来展示基本实例化/用法
class ChatAnthropic ( BaseChatModel ): """接口到 Claude 聊天模型。 请参阅 [使用指南](https://docs.langchain.com/oss/python/integrations/chat/anthropic) 以获取教程、功能走查和示例。 参数: model: 模型标识符（例如，`'claude-sonnet-4-6'`）。 temperature: 介于 `0` 和 `1` 之间的采样温度。 max_tokens: 生成的最大令牌数。 api_key: Anthropic API 密钥。 如果未提供，则从环境变量 `ANTHROPIC_API_KEY` 中读取。 timeout: 请求超时（秒）。 max_retries: 失败请求的最大重试次数。 返回值: 一个可以调用消息的聊天模型实例。 抛出: ValueError: 如果未识别到模型标识符。 AuthenticationError: 如果 API 密钥无效。 示例: ```python from langchain_anthropic import ChatAnthropic model = ChatAnthropic(model="claude-sonnet-4-6") response = model.invoke("Hello!")
""" </Accordion> <Accordion title="不属于文档字符串的内容"> 避免在文档字符串中重复属于文档字符串的内容： - **参数类型**: 这些已经在签名中，并且会自动生成到 API 参考中。 - **功能教程**: 不要包含扩展的走查。相反，链接到本站点: ```python """ ... 请参阅 [扩展思考指南](https://docs.langchain.com/oss/integrations/chat/anthropic#extended-thinking) 以获取配置选项。 """
多个示例变体 : 包含一个最小的示例，然后链接到全面的指南:""" 示例: \`\`\`python message = HumanMessage(content=[ {"type": "image", "url": "https://example.com/image.jpg"} ]) \`\`\` 请参阅 [多模态指南](https://docs.langchain.com/oss/integrations/chat/anthropic#multimodal) 以获取所有支持的输入格式。 """
概念解释 : 保持参数描述的事实性。链接到文档以获得更深入的理解。
MkDocs 特定语法 : 避免在文档字符串中使用 ???+、折叠或标签。它们不会在 IDE 中渲染。
自动化 : 通过 ruff 进行格式化和检查make format # 应用格式化 make lint # 检查样式和类型
标准 :
描述性的变量名
分解复杂函数（目标少于20行）
遵循代码库中的现有模式
依赖项 LangChain 包将硬依赖项和可选依赖项区分开来，以保持包轻量级并减少用户的安装开销。
几乎所有新的依赖项都应该为可选的。使用可选依赖项的情况包括：
该依赖项仅用于特定集成或功能
用户可以有意义地不使用此依赖项
该依赖项较大，具有许多传递性依赖
要求 :
没有安装依赖项的情况下用户能够导入你的代码而不产生任何副作用（没有警告、错误或异常）
pyproject.toml 和 uv.lock 不会更改 添加可选依赖项:
将依赖项添加到适当的测试依赖文件中（例如，extended_testing_deps.txt）
添加一个至少尝试导入新代码的单元测试。理想情况下，该单元测试使用轻量级固定装置来测试代码逻辑。
使用 @pytest.mark.requires("package_name") 装饰器为需要依赖项的任何单元测试。
硬依赖项会自动在用户安装包时被安装。仅当：
包无法没有该依赖项的情况下运行
该依赖项较小且具有少量传递性依赖
没有合理的办法使其功能可选
添加硬依赖项会增加所有用户的安装时间和潜在版本冲突。 维护者将仔细审查硬依赖项的添加!
添加硬依赖项:
打开一个 issue 或讨论解释为什么必须将其作为硬依赖项而不是可选依赖项
将依赖项添加到 pyproject.toml 中相应的部分
运行 uv lock 更新锁文件
包含全面测试以覆盖新功能
测试编写指南 为了编写有效的测试，有一些好的实践要遵循：
使用自然语言在文档字符串中描述测试
使用描述性的变量名
累积断言
def test_document_processor_handles_empty_input (): """测试处理器优雅地处理空文档列表。""" processor = DocumentProcessor () result = processor . process ([]) assert result . success assert result . processed_count == 0 assert len ( result . errors ) == 0
@pytest . mark . requires ( "openai" ) def test_openai_chat_integration (): """测试与真实 API 的 OpenAI 聊天集成。""" chat = ChatOpenAI () response = chat . invoke ( "Hello" ) assert isinstance ( response . content , str ) assert len ( response . content ) > 0
def test_retry_mechanism ( mocker ): """测试重试机制处理瞬时失败。""" 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
提交 pull request 一旦你的测试通过且代码符合质量标准：
推送分支并打开一个 pull request
按照提供的 pull request 模板操作
使用 关闭关键字 （例如 Fixes #123）来引用你正在修复的问题，以便在 pull request 合并时自动关闭问题
等待 CI 检查完成
如果你的 pull request 包含 AI 生成的内容，请遵循我们的 LLM 的可接受用途 政策。看起来像是低努力、AI 生成的垃圾内容的 pull request 将会无评论地关闭。 及时解决 CI 失败。维护者可能会在合理的时间框架内关闭未通过 CI 的 pull request。
获取帮助 我们的目标是使开发者的设置尽可能易于访问。如果你遇到任何难以设置的问题，请在 社区 Slack 或打开一个 论坛帖子 。
你现在可以为 LangChain 贡献高质量的代码了！
通过 MCP 将这些文档连接到 Claude、VSCode 和更多工具，以获得实时答案。
