贡献代码

如要为本项目贡献代码，请遵循 "fork 并提交 PR" 的工作流。
除非你是项目维护者，否则请不要尝试直接向本仓库提交代码。

提交 Pull Request 时，请使用项目提供的 PR 模板。请注明相关的 Issue 并 @ 相关的维护者。

Pull Request 必须通过格式化、代码检查和测试后才能被合并。如何在本地运行这些检查，请参见 测试 和 格式化与代码检查。

维护高质量的文档和测试是非常重要的。如果你：

• 修复了一个 bug
  • 在可能的情况下添加相应的单元测试或集成测试。这些测试文件位于 **/tests/*.test.ts 和 **/tests/*.int.test.ts 中。
• 做了改进
  • 更新受影响的示例笔记本和文档。这些内容位于 docs 文件夹中。
  • 在需要时更新单元测试和集成测试。
• 添加了新功能
  • 在 docs/core_docs/docs 中添加演示用的笔记本或 MDX 文件。
  • 添加单元测试和集成测试。

我们是一个小而注重进展的团队。如果你想添加或修改某些内容，最有效的方式就是提交一个 Pull Request 来引起我们的注意。

🚀 快速开始

本快速入门指南解释了如何在本地运行本仓库。
关于 开发容器，请参见 .devcontainer 文件夹。

🏭 发布流程

目前，LangChain 使用的是临时的发布流程：由开发人员高频次地进行版本发布，并发布到 npm。

LangChain 遵循 语义化版本号 的标准。但因为是 1.0 之前的版本，即使是补丁版本也可能包含不兼容的变更。

如果你的贡献已被包含在某个发布版本中，我们希望在 Twitter 上给予你致谢（当然仅在你同意的情况下）！
如果你有希望我们提及的 Twitter 账号，请在 PR 中或通过其他方式告知我们。

集成发布

发布脚本只能在干净的 main 分支上执行，且不能有任何未提交的更改，需从包根目录调用。如果使用的是仓库的 fork，请确保先将 fork 的 main 分支与上游的 main 分支同步。

你可以通过调用 yarn release 来执行该脚本。如果集成包中新增了依赖项，请先安装它们（即运行 yarn，然后再运行 yarn release）。

该脚本可以接受三个参数，其中一个是必填的，两个是可选的。

• 必填：<workspace name>。例如：@langchain/core。这是要发布的包的名称，可以在该包的 package.json 文件中的 name 字段找到。
• 可选：--bump-deps。例如：--bump-deps。该参数会查找仓库中依赖该工作区的所有包，创建一个新分支、更新依赖版本、运行 yarn install、提交并推送到新分支。通常情况下不需要使用该参数。
• 可选：--tag <tag>。例如：--tag beta。为 NPM 发布添加一个标签。当你希望发布一个候选版本时很有用。

该脚本会自动增加包版本号，创建一个新的发布分支，将更改推送到 GitHub，使用 release-it 自动发布到 NPM，具体行为取决于传入的标志。

在执行该脚本的过程中，你将被提示输入一个 NPM OTP（通常来自身份验证应用）。该值不会存储在任何地方，仅用于认证 NPM 发布。

注意：除非发布的是 langchain，否则在出现 Publish @langchain/<package> to npm? 提示时应回答 no。然后应手动提交更改，并使用以下提交信息：<package>[patch]: Release <new version>。例如：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 的入口点，它从 tools/index.ts 导入，你可以在 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 文件中的 import map。

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

示例：

// Node 中的导入：
import { z } from "zod";
// Deno 中的导入：
import { z } from "npm:/zod";

更多示例请参见 deno.json 文件。

文档主要通过 TypeDoc 从代码注释中自动生成。

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

与代码检查类似，我们理解文档编写可能令人厌烦。如果你不想编写文档，请联系项目维护者，他们可以协助你完成。我们不希望文档成为高质量代码贡献的障碍。

文档和骨架文件位于 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