贡献代码

要为该项目做出贡献，请遵循 “fork 和 pull request” 工作流程。除非您是维护者，否则请不要尝试直接推送到此仓库。

打开 pull request 时，请遵循签入的 pull request 模板。注意相关问题并标记相关维护者。

Pull request 必须先通过格式化、代码风格检查和测试检查才能合并。请参阅 测试 和 格式化和代码风格检查，了解如何在本地运行这些检查。

维护良好的文档和测试至关重要。如果您

• 修复错误
  • 尽可能添加相关的单元或集成测试。这些位于 **/tests/*.test.ts 和 **/tests/*.int.test.ts/ 中。
• 进行改进
  • 更新任何受影响的示例笔记本和文档。这些位于 docs 中。
  • 更新单元和集成测试（如果相关）。
• 添加功能
  • 在 docs/core_docs/docs 中添加一个演示笔记本/MDX 文件。
  • 添加单元和集成测试。

我们是一个小型、注重进度的团队。如果您想添加或更改某些内容，打开 pull request 是获得我们关注的最佳方式。

🚀 快速入门

本快速入门指南介绍了如何在本地运行仓库。有关 开发容器，请参阅 .devcontainer 文件夹。

🏭 发布流程

目前，LangChain 采用了一种临时发布流程：发布版本由开发人员高频发布并发布到 npm。

LangChain 遵循 semver 版本控制标准。但是，作为 1.0 之前的软件，即使是补丁版本也可能包含 不向后兼容的更改。

如果您的贡献已包含在发布版本中，我们将希望在 Twitter 上为您点赞（但仅在您希望的情况下！）。如果您有希望我们提及的 Twitter 帐户，请在 PR 或其他方式中告知我们。

集成发布

发布脚本只能在全新的 main 分支上执行，并且没有未提交的更改，从包根目录开始。如果从仓库的分支进行工作，请确保先将分叉的 main 分支与上游 main 分支同步。

您可以通过调用 yarn release 来调用脚本。如果已将新依赖项添加到集成包中，请先安装它们（即，运行 yarn，然后运行 yarn release）。

此脚本有三个参数可以传递，一个必选，两个可选。

• **必选**：<工作区名称>。例如：@langchain/core 要发布的包的名称。可以在包的 package.json 的 name 值中找到。
• **可选**：--bump-deps 例如 --bump-deps 将查找存储库中所有依赖于此工作区的包，并检出一个新分支，更新依赖项版本，运行 yarn install，提交并推送到新分支。通常，这不是必需的。
• **可选**：--tag <标签> 例如 --tag beta 向 NPM 发布版本添加标签。如果您想推送候选版本，这很有用。

此脚本会自动更新包版本，创建包含更改的新发布分支，将分支推送到 GitHub，使用 release-it 自动发布到 NPM，以及根据传递的标志执行更多操作。

在此脚本的中间，系统会提示您输入 NPM OTP（通常来自身份验证器应用程序）。此值不会存储在任何位置，仅用于对 NPM 发布进行身份验证。

**注意** 除非发布 langchain、@langchain/core 或 @langchain/community，否则在 Publish @langchain/<package> to npm? 之后的所有提示都应回答 no。然后，应使用以下提交消息手动提交更改：<package>[patch]: Release <新版本>。例如：groq[patch]: Release 0.0.1。

如果发布 langchain、@langchain/core 或 @langchain/community 之一，则 Docker 必须正在运行。这些包运行 LangChain 的导出测试，这些测试在 Docker 容器内运行。

完整示例：yarn release @langchain/core。

🛠️ 工具

此项目使用以下工具，如果您计划做出贡献，则值得熟悉这些工具

• yarn (v3.4.1) - 依赖项管理
• eslint - 强制执行标准的代码风格规则
• prettier - 强制执行标准的代码格式
• jest - 测试代码
• TypeDoc - 从注释生成参考文档
• Docusaurus - 用于文档的静态网站生成

🚀 快速入门

克隆此仓库，然后进入其中

cd langchainjs

接下来，尝试运行以下常见任务

✅ 常见任务

我们的目标是让您尽可能轻松地为该项目做出贡献。除非另有说明，否则以下所有命令都应在工作区目录（例如，langchain、libs/langchain-community）中运行。

cd langchain

或者，如果您正在处理社区集成

cd libs/langchain-community

设置

**先决条件**：需要 Node 版本 18+。请检查 node 版本 node -v，并在需要时更新它。

要开始，您需要安装项目的依赖项。为此，请运行

yarn

然后，您需要切换到 langchain-core 目录，并通过运行以下命令构建核心

cd ../langchain-core
yarn
yarn build

代码风格检查

我们使用 eslint 强制执行标准的代码风格规则。要运行代码风格检查器，请运行

yarn lint

格式化

我们使用 prettier 强制执行代码格式样式。要运行格式化程序，请运行

yarn format

要仅检查格式差异，而不修复它们，请运行

yarn format:check

测试

通常，应在测试的模块旁边的 tests/ 文件夹中添加测试。

**单元测试** 涵盖不需要调用外部 API 的模块化逻辑。

如果添加了新的逻辑，请添加单元测试。单元测试应命名为 *.test.ts。

要仅运行单元测试，请运行

yarn test

运行单个测试

要运行单个测试，请在工作区内运行以下命令

yarn test:single /path/to/yourtest.test.ts

这对于开发单个功能很有用。

**集成测试** 涵盖需要对外部 API 进行调用的逻辑（通常与其他服务集成）。

如果添加了对新外部 API 的支持，请添加新的集成测试。集成测试应命名为 *.int.test.ts。

请注意，大多数集成测试需要凭据或其他设置。您可能需要设置 langchain/.env 或 libs/langchain-community/.env 文件，例如 此处所示的示例。

我们通常建议仅使用 yarn test:single 运行集成测试，但如果您想运行所有集成测试，请运行

yarn test:integration

构建

要构建项目，请运行

yarn build

添加入口点

LangChain 公开了用户可以从中导入的多个子路径，例如

import { OpenAI } from "langchain/llms/openai";

我们称这些子路径为“入口点”。通常，如果您正在添加与第三方库的新集成，则应创建一个新的入口点。如果您正在添加没有外部依赖项的自包含功能，则可以将其添加到现有入口点。

为了声明用户可以从中导入的新入口点，您应该编辑 langchain/langchain.config.js 或 libs/langchain-community/langchain.config.js 文件。要添加一个从 tools/index.ts 导入的入口点 tools，您需要将以下内容添加到 config 变量内的 entrypoints 键中

// ...
entrypoints: {
  // ...
  tools: "tools/index",
},
// ...

如果您正在添加需要安装第三方依赖项的新集成，则必须将入口点添加到 requiresOptionalDependency 数组中，该数组也位于 langchain/langchain.config.js 或 libs/langchain-community/langchain.config.js 中。

// ...
requiresOptionalDependency: [
  // ...
  "tools/index",
],
// ...

这将确保入口点包含在已发布的包中，并在生成的文档中。

文档

贡献文档

安装依赖项

注意：如果您是在本地构建文档站点，则只需执行以下步骤。

1. Quarto - 将 Jupyter 笔记本（.ipynb 文件）转换为 .mdx 文件以在 Docusaurus 中提供服务的包。
2. yarn build --filter=core_docs - 就这么简单！（或者您可以从 docs/core_docs/ 简单地运行 yarn build）

所有笔记本都转换为 .md 文件并自动被 gitignore 忽略。如果您想创建一个非笔记本文档，它必须是 .mdx 文件。

编写笔记本

在笔记本内部添加新依赖项时，必须更新 LangChain 仓库根目录中 deno.json 内部的导入映射。

这是必需的，因为笔记本使用 Deno 运行时，而 Deno 的导入格式与 Node.js 不同。

示例

// Import in Node:
import { z } from "zod";
// Import in Deno:
import { z } from "npm:/zod";

有关更多详细信息，请参阅 deno.json 中的示例。

文档在很大程度上是由 TypeDoc 从代码自动生成的。

因此，我们要求您为所有类和方法添加良好的文档。

与 lint 类似，我们认识到文档可能会很烦人。如果您不想这样做，请联系项目维护者，他们可以帮助您。我们不希望这成为贡献优秀代码的障碍。

文档和骨架位于 docs/ 文件夹下。示例代码从 examples/ 文件夹下导入。

运行示例

如果您添加了新的主要功能，添加一个示例来展示如何使用它会很有帮助。我们的大多数用户发现示例是最有帮助的文档类型。

示例可以添加到 examples/src 目录中，例如 examples/src/path/to/example。然后可以通过在仓库的顶层使用 yarn example path/to/example 调用此示例。

要运行需要环境变量的示例，您需要在 examples/.env 下添加一个 .env 文件。

在本地构建文档

要在本地生成和查看文档，请更改到项目根目录并运行 yarn 以确保在 docs/ 和 examples/ 工作区中都安装了依赖项。

cd ..
yarn

然后运行

yarn docs

高级

环境测试 测试 LangChain 是否可在不同的 JS 环境中工作，包括 Node.js（ESM 和 CJS）、Edge 环境（例如 Cloudflare Workers）和浏览器（使用 Webpack）。

要使用 Docker 运行环境测试，请从项目根目录运行以下命令

yarn test:exports:docker