# https://github.com/langchain-ai/langchainjs 项目说明书

生成时间：2026-05-16 04:29:18 UTC

## 目录

- [项目概述与生态系统](#page-1)
- [系统架构与核心抽象](#page-2)
- [Agent 与 Chains 实现](#page-3)
- [向量存储与检索系统](#page-4)
- [主要模型提供商集成](#page-5)
- [扩展提供商与工具集成](#page-6)
- [多环境部署支持](#page-7)
- [依赖管理与测试策略](#page-8)
- [扩展开发指南](#page-9)
- [示例代码与最佳实践](#page-10)

<a id='page-1'></a>

## 项目概述与生态系统

### 相关页面

相关主题：[系统架构与核心抽象](#page-2), [主要模型提供商集成](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/langchain-ai/langchainjs/blob/main/README.md)
- [libs/langchain-core/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/README.md)
- [libs/langchain/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/README.md)
- [libs/langchain-classic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/README.md)
- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)
- [libs/create-langchain-integration/template/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/README.md)
</details>

# 项目概述与生态系统

LangChain.js 是一个用于构建 LLM 驱动应用的框架，旨在通过可组合性简化 AI 应用开发过程。它帮助开发者将可互操作的组件和第三方集成链在一起，同时为底层技术演进提供未来保障。

## 核心定位与价值主张

LangChain.js 的核心价值在于提供一个灵活的框架，使开发者能够：

- **链式组合**：将多个组件组合成复杂的工作流
- **第三方集成**：轻松接入各种 LLM 提供商和工具
- **模块化设计**：各组件独立可替换，便于维护和升级
- **开发效率**：提供开箱即用的抽象，加速应用开发

## 生态系统架构

LangChain.js 采用多包架构，将不同功能模块分离到独立的包中，以提高可维护性和灵活度。

```mermaid
graph TD
    A[用户应用] --> B[langchain 主包]
    A --> C[@langchain/classic 经典包]
    B --> D[@langchain/core 核心包]
    C --> D
    B --> E[@langchain/textsplitters 文本分割]
    D --> F[Provider 包]
    F --> G[langchain-openai]
    F --> H[langchain-anthropic]
    F --> I[langchain-google-common]
```

## 核心包结构

### @langchain/core 核心包

`@langchain/core` 是整个生态系统的基础库，定义了 LangChain 的核心抽象和接口。它包含：

- **消息系统**：定义各种消息类型和消息处理逻辑
- **语言模型接口**：统一的 LLM 调用抽象
- **工具系统**：定义工具的创建和调用方式
- **输出解析器**：将 LLM 输出解析为结构化数据
- **事件系统**：支持流式事件和状态更新

资料来源：[libs/langchain-core/README.md]()

### langchain 主包

`langchain` 是面向现代 Agent 开发的主包，提供了构建 AI Agent 的高级 API。

#### 主要特性

| 特性 | 描述 |
|------|------|
| createAgent | 创建 Agent 的主要入口 |
| 中间件支持 | 支持 HITL 等中间件功能 |
| 工具集成 | 内置工具调用和工具管理 |

#### Agent 架构

```mermaid
graph LR
    A[用户输入] --> B[Agent 核心]
    B --> C[工具调用]
    C --> D[外部服务]
    D --> B
    B --> E[响应输出]
```

`langchain` 包支持通过中间件扩展功能，例如人机交互中间件（Human-in-the-Loop），允许在 Agent 执行过程中进行干预和控制。

资料来源：[libs/langchain/README.md](), [libs/langchain/src/agents/middleware/hitl.ts:1-100]()

### @langchain/classic 经典包

`@langchain/classic` 是为了向后兼容而保留的包，包含从 LangChain v0.x 移出的功能。

#### 何时使用

建议使用 `@langchain/classic` 的场景：

| 场景 | 说明 |
|------|------|
| 遗留链 | 使用 `LLMChain`、`ConversationalRetrievalQAChain` 等 |
| 索引 API | 使用文档索引和向量存储功能 |
| 社区集成 | 依赖之前从 `langchain` 重新导出的社区功能 |
| 应用迁移 | 维护现有应用，尚未准备好迁移到新 API |

#### 何时不使用

**对于新项目，应使用 langchain v1.0**，新 API 提供：

- 更清晰的 `createAgent` 构建方式
- 更好的性能优化
- 更聚焦的 API 表面
- 活跃的开发支持

#### 迁移路径

```typescript
// 旧导入（已弃用）
import { LLMChain } from "langchain";

// 新导入
import { LLMChain } from "@langchain/classic";
```

资料来源：[libs/langchain-classic/README.md](), [libs/langchain-classic/src/util/entrypoint_deprecation.ts:1-50]()

### @langchain/textsplitters 文本分割包

`@langchain/textsplitters` 提供各种文本分割器实现，是 RAG（检索增强生成）管道的常用组件。

#### 支持的分割模式

| 语言 | 说明 |
|------|------|
| html | HTML 特定的分块策略 |
| javascript | JavaScript 代码分割 |
| typescript | TypeScript 代码分割 |
| markdown | Markdown 文档分割 |
| python | Python 代码分割 |
| json | JSON 数据分割 |

#### 基本使用

```typescript
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
});

const output = await splitter.createDocuments([htmlText]);
```

资料来源：[libs/langchain-textsplitters/README.md](), [examples/src/langchain-classic/indexes/html_text_splitter.ts:1-50]()

## Provider 包生态

Provider 包提供了与各个 LLM 服务商的集成。

### 主要 Provider

| Provider | 包名 | 功能 |
|----------|------|------|
| OpenAI | langchain-openai | GPT 系列模型集成 |
| Anthropic | langchain-anthropic | Claude 模型集成 |
| Google | langchain-google-common | Google AI 集成 |

### Provider 架构

```mermaid
graph TD
    A[统一接口] --> B[langchain-core]
    B --> C[OpenAI 适配器]
    B --> D[Anthropic 适配器]
    B --> E[Google 适配器]
    C --> F[OpenAI API]
    D --> G[Anthropic API]
    E --> H[Google API]
```

每个 Provider 包都实现了统一的接口规范，确保应用可以在不同 LLM 之间切换而不需要大量代码改动。

资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts](), [libs/providers/langchain-anthropic/src/chat_models.ts](), [libs/providers/langchain-google-common/src/utils/anthropic.ts]()

### 工具调用支持

Provider 包普遍支持：

- **函数调用**：通过 `withStructuredOutput()` 实现结构化输出
- **工具使用**：内置工具调用和工具管理
- **流式处理**：支持流式响应和增量输出

```typescript
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async (input) => `Weather in ${input.location}`,
  {
    name: "get_weather",
    description: "Get weather for a location",
    schema: z.object({ location: z.string() }),
  }
);
```

## 开发工具与模板

### 创建新集成

`create-langchain-integration` 提供了创建新 Provider 包的标准模板：

```bash
npm install @langchain/<PACKAGE_NAME>
```

新包需要配置与 `@langchain/core` 的版本对齐：

```json
{
  "dependencies": {
    "@langchain/<PACKAGE_NAME>": "^0.0.0",
    "@langchain/core": "^0.3.0"
  },
  "resolutions": {
    "@langchain/core": "^0.3.0"
  }
}
```

资料来源：[libs/create-langchain-integration/template/README.md]()

## 核心抽象与接口

### 消息系统

LangChain.js 定义了完整的消息类型体系：

| 类型 | 说明 |
|------|------|
| HumanMessage | 用户消息 |
| AIMessage | AI 响应消息 |
| SystemMessage | 系统级指令 |
| ToolMessage | 工具执行结果 |

```typescript
import { AIMessageChunk } from '@langchain/core/messages';
import { concat } from '@langchain/core/utils';
```

资料来源：[libs/langchain-core/src/messages/block_translators/openai.ts](), [libs/langchain-core/src/testing/matchers.ts:1-100]()

### 事件系统

核心库提供了完整的事件系统，支持流式处理和状态追踪：

| 事件类型 | 说明 |
|----------|------|
| content-block-delta | 内容块增量更新 |
| content-block-finish | 内容块完成 |
| usage | 使用量更新 |
| provider | 原始 Provider 事件 |

```typescript
interface ContentBlockDeltaEvent {
  event: "content-block-delta";
  index: number;
  delta: ContentBlockDelta;
}
```

资料来源：[libs/langchain-core/src/language_models/event.ts]()

### 索引系统

LangChain.js 提供了文档索引的基础设施，用于 RAG 场景：

```mermaid
graph LR
    A[文档] --> B[DocumentLoader]
    B --> C[TextSplitter]
    C --> D[Document 数组]
    D --> E[RecordManager]
    D --> F[VectorStore]
```

索引功能使用 RecordManager 追踪文档状态，支持增量更新和删除管理。

资料来源：[libs/langchain-core/src/indexing/base.ts]()

## 版本演进与兼容性

### v1.0 架构变化

LangChain v1.0 进行了重要的架构调整：

1. **核心功能下沉**：`@langchain/core` 成为基础抽象层
2. **功能分离**：`@langchain/classic` 承接遗留功能
3. **现代 API**：`langchain` 主包专注于 Agent 构建
4. **Provider 解耦**：各 Provider 独立维护

### 弃用警告

导入路径迁移会产生弃用警告：

```typescript
// 旧路径
import { SomeClass } from "langchain";

// 新路径
import { SomeClass } from "@langchain/classic";
```

可通过环境变量抑制警告：

```bash
LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS=true
```

资料来源：[libs/langchain-classic/src/util/entrypoint_deprecation.ts]()

## 安装与依赖管理

### 推荐的依赖配置

为确保各包之间的 `@langchain/core` 版本一致，建议在项目中添加版本锁定：

```json
{
  "resolutions": {
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  },
  "pnpm": {
    "overrides": {
      "@langchain/core": "^0.3.0"
    }
  }
}
```

### 开发依赖

克隆仓库后的标准开发流程：

```bash
pnpm install
pnpm build
pnpm test
pnpm lint && pnpm format
```

资料来源：[libs/langchain-textsplitters/README.md](), [libs/create-langchain-integration/template/README.md]()

## 总结

LangChain.js 生态系统通过模块化设计提供了灵活的 LLM 应用构建能力：

- **核心层**：`@langchain/core` 提供统一抽象
- **主包**：`langchain` 专注现代 Agent 开发
- **兼容层**：`@langchain/classic` 支持平滑迁移
- **集成层**：多种 Provider 包连接各 LLM 服务商
- **工具层**：文本分割等实用工具支持 RAG 场景

这种架构既保证了新项目的开发效率，也照顾了现有代码的向后兼容性，使 LangChain.js 成为构建 LLM 应用的可靠选择。

---

<a id='page-2'></a>

## 系统架构与核心抽象

### 相关页面

相关主题：[项目概述与生态系统](#page-1), [Agent 与 Chains 实现](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libs/langchain-core/src/runnables/base.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/runnables/base.ts)
- [libs/langchain-core/src/callbacks/base.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/callbacks/base.ts)
- [libs/langchain-core/src/memory.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/memory.ts)
- [libs/langchain-core/src/tools/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/tools/index.ts)
- [libs/langchain-core/src/language_models/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/chat_models.ts)
- [libs/langchain-core/src/vectorstores.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/vectorstores.ts)
</details>

# 系统架构与核心抽象

## 概述

LangChain.js 的系统架构采用模块化设计，核心抽象层位于 `@langchain/core` 包中，为上层应用提供统一的接口和组件。架构设计遵循以下原则：可组合性、可扩展性和类型安全。整个系统以 **Runnable** 抽象为核心，构建了一套完整的大语言模型应用开发框架。

LangChain.js 的核心抽象主要包括：Runnable 执行单元、Callbacks 事件系统、Memory 记忆管理、Tools 工具系统、Chat Models 聊天模型接口，以及 Vector Stores 向量存储接口。这些抽象共同构成了构建复杂 LLM 应用的基石。

## 核心架构图

```mermaid
graph TB
    subgraph "核心抽象层 @langchain/core"
        Runnable[Runnable 执行单元]
        Callbacks[Callbacks 事件系统]
        Memory[Memory 记忆管理]
        Tools[Tools 工具系统]
        ChatModels[Chat Models 接口]
        VectorStores[Vector Stores 接口]
    end
    
    subgraph "应用层"
        Agents[Agent 代理]
        Chains[Chain 链]
        VectorRetrieval[向量检索]
    end
    
    subgraph "集成层"
        Providers[第三方集成]
    end
    
    Runnable --> Callbacks
    Runnable --> Memory
    Runnable --> Tools
    Runnable --> ChatModels
    Runnable --> VectorStores
    
    Agents --> Runnable
    Chains --> Runnable
    VectorRetrieval --> VectorStores
    
    Providers --> ChatModels
    Providers --> Tools
    Providers --> VectorStores
```

## Runnable 执行单元

### 设计理念

**Runnable** 是 LangChain.js 最核心的抽象，它代表了任何可以被执行的组件。所有的 Chain、Agent、Tool、Memory 等都实现或扩展了 Runnable 接口。这种设计使得系统中的任意组件都可以被统一地组合、管道化和执行。

Runnable 接口定义了一套标准的执行方法，包括同步调用、批量处理、流式输出等。这确保了无论组件的具体实现如何，调用者都可以用统一的方式与它们交互。

### 核心接口方法

| 方法名 | 说明 | 返回类型 |
|--------|------|----------|
| `invoke(input)` | 同步执行单个输入 | `Output` |
| `batch(inputs)` | 批量处理多个输入 | `Output[]` |
| `stream(input)` | 流式输出 | `AsyncGenerator<Chunk>` |
| `pipe(destination)` | 管道连接到另一个 Runnable | `Runnable` |
| `bind(config)` | 绑定运行时配置 | `Runnable` |

### 可组合性

```mermaid
graph LR
    A[输入] --> B[Prompt]
    B --> C[LLM]
    C --> D[Output Parser]
    D --> E[最终结果]
    
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#e8f5e8
```

Runnable 支持两种组合方式：顺序组合和并行组合。顺序组合通过 `pipe()` 方法实现，将前一个 Runnable 的输出作为下一个 Runnable 的输入。并行组合则可以将多个 Runnable 同时应用于同一输入，然后合并结果。

## Callbacks 事件系统

### 架构设计

Callbacks 系统提供了一套完整的事件通知机制，允许在 Runnable 执行过程中的各个阶段插入自定义逻辑。这种设计实现了关注点分离：核心逻辑与监控、调试、日志记录等辅助功能解耦。

事件系统采用发布-订阅模式，定义了清晰的事件生命周期钩子。开发者可以通过实现 `CallbackHandler` 接口来订阅感兴趣的事件，并在事件触发时执行相应操作。

### 主要事件类型

| 事件名称 | 触发时机 | 典型用途 |
|----------|----------|----------|
| `handleStart` | Runnable 开始执行 | 记录开始时间 |
| `handleEnd` | Runnable 完成执行 | 记录结束时间、收集结果 |
| `handleError` | 执行过程中发生错误 | 错误日志、告警通知 |
| `handleText` | 输出文本片段 | 实时显示、流式输出 |
| `handleChainStart` | Chain 开始执行 | 追踪调用链 |
| `handleChainEnd` | Chain 完成执行 | 性能监控 |

### 使用场景

Callbacks 系统常用于以下场景：

1. **性能监控**：测量各个 Runnable 的执行时间
2. **日志记录**：记录完整的调用链和中间结果
3. **流式输出**：实时处理模型生成的内容片段
4. **调试开发**：在执行过程中输出中间状态
5. **成本追踪**：统计 token 使用量和 API 调用次数

## Memory 记忆管理

### 抽象接口

Memory 接口定义了与对话历史交互的标准方式。它允许 Chain 和 Agent 在多次调用之间保持状态，实现真正的多轮对话能力。Memory 的设计独立于具体的存储后端，支持内存、数据库、文件系统等多种实现。

```mermaid
sequenceDiagram
    participant User as 用户
    participant Chain as Chain
    participant Memory as Memory
    
    User->>Chain: 第一轮输入
    Chain->>Memory: 读取历史
    Memory-->>Chain: 历史消息
    Chain->>LLM: 组合输入
    LLM-->>Chain: 响应
    Chain->>Memory: 保存对话
    Chain-->>User: 返回结果
    
    User->>Chain: 第二轮输入
    Chain->>Memory: 读取历史
    Memory-->>Chain: 历史消息
    Chain->>LLM: 组合输入
    LLM-->>Chain: 响应
    Chain->>Memory: 保存对话
    Chain-->>User: 返回结果
```

### 核心方法

| 方法名 | 说明 |
|--------|------|
| `loadMemoryVariables()` | 加载当前记忆变量 |
| `saveContext(inputs, outputs)` | 保存输入输出对到记忆 |
| `clear()` | 清除所有记忆内容 |

Memory 系统支持多种实现方式，包括基础缓冲记忆、会话窗口记忆、摘要记忆等。开发者可以根据应用需求选择合适的记忆策略，或实现自定义的 Memory 类。

## Tools 工具系统

### 工具定义接口

Tools 系统允许 LLM 调用外部函数和 API，扩展了模型的能力边界。每个 Tool 都是一个独立的 Runnable，具有明确定义的输入模式（通过 Zod schema 定义）和返回值格式。

```mermaid
graph TD
    LLM[LLM] -->|决定调用| ToolCall[Tool Call]
    ToolCall --> Tool[Tool 执行]
    Tool --> Result[结果]
    Result --> LLM
    
    subgraph "Tool 定义"
        Name[名称]
        Desc[描述]
        Schema[输入模式]
        Func[执行函数]
    end
    
    Tool --> Name
    Tool --> Desc
    Tool --> Schema
    Tool --> Func
```

### 工具属性

| 属性 | 类型 | 说明 |
|------|------|------|
| name | string | 工具的唯一标识名 |
| description | string | 工具功能描述，用于 LLM 理解何时调用 |
| argsSchema | ZodSchema | 输入参数的模式定义 |

### 工具调用流程

1. **描述注册**：工具注册时提供名称和描述
2. **意图识别**：LLM 根据用户问题和工具描述判断是否需要调用
3. **参数生成**：LLM 根据工具的 schema 生成调用参数
4. **安全执行**：系统验证参数并执行工具
5. **结果返回**：工具执行结果返回给 LLM 继续处理

Tools 系统还支持动态工具调用配置，允许在运行时修改工具行为和可见性。

## Chat Models 聊天模型接口

### 接口设计

Chat Models 接口抽象了所有聊天语言模型的通用能力，提供了一套标准化的 API。通过这个接口，LangChain.js 可以统一地与不同的 LLM 提供商（如 OpenAI、Anthropic、Cohere 等）交互。

接口设计遵循流式优先的原则，所有模型都支持流式输出，允许实时处理生成的内容。这对于需要即时反馈的应用场景至关重要。

### 核心能力

| 能力 | 说明 | 重要性 |
|------|------|--------|
| 同步调用 | 等待完整响应返回 | 高 |
| 流式输出 | 实时获取生成的文本片段 | 高 |
| 批量处理 | 一次处理多个请求 | 中 |
| 结构化输出 | 生成符合 schema 的 JSON | 高 |
| 工具调用 | 支持 function calling | 高 |
| 多模态 | 支持图像、音频等输入 | 中 |

### 消息类型

接口定义了标准化的消息类型系统，包括：

- **HumanMessage**：用户发送的消息
- **AIMessage**：AI 生成的响应
- **SystemMessage**：系统级指令
- **ToolMessage**：工具执行结果
- **AIMessageChunk**：流式输出的消息片段

## Vector Stores 向量存储接口

### 检索增强生成支持

Vector Stores 接口为检索增强生成（RAG）提供了向量存储和相似性检索的基础设施。接口设计兼容多种向量数据库，包括本地内存存储和云服务（如 Pinecone、Weaviate、Chroma 等）。

```mermaid
graph LR
    A[文档] --> B[文档加载器]
    B --> C[文本分割器]
    C --> D[嵌入模型]
    D --> E[向量存储]
    
    F[用户查询] --> G[嵌入模型]
    G --> H[相似性搜索]
    H --> E
    E --> I[相关文档]
    I --> J[LLM 生成]
```

### 核心方法

| 方法名 | 说明 |
|--------|------|
| `addDocuments()` | 添加文档到向量存储 |
| `similaritySearch()` | 基于向量相似性搜索 |
| `similaritySearchWithScore()` | 返回相似性得分 |
| `delete()` | 删除指定文档 |
| `getCapabilities()` | 获取存储能力信息 |

### 索引管理

向量存储支持灵活的索引管理，允许：

- 增量更新文档而无需重建整个索引
- 基于元数据过滤搜索结果
- 配置不同的相似性度量方法（余弦相似度、欧氏距离等）

## 模块协作示例

以下流程图展示了一个典型 RAG 应用中各模块的协作方式：

```mermaid
sequenceDiagram
    participant User as 用户
    participant Chain as Chain
    participant Memory as Memory
    participant Retriever as Retriever
    participant VS as Vector Store
    participant LLM as LLM
    
    User->>Chain: 用户查询
    Chain->>Memory: 获取对话上下文
    Memory-->>Chain: 历史消息
    Chain->>Retriever: 检索请求
    Retriever->>VS: 向量相似性搜索
    VS-->>Retriever: 相关文档
    Retriever-->>Chain: 上下文文档
    Chain->>LLM: 组合查询+上下文
    LLM-->>Chain: 生成回答
    Chain->>Memory: 保存对话
    Chain-->>User: 返回结果
```

## 类型系统与验证

### Zod Schema 集成

LangChain.js 深度集成了 Zod 进行类型验证和模式定义。这种集成提供了：

1. **编译时类型检查**：TypeScript 编译器可以验证类型安全
2. **运行时验证**：确保输入输出符合预期格式
3. **自动类型推断**：减少手写类型定义的工作量
4. **LLM 输出验证**：验证模型生成的响应是否符合 schema

### 层级化类型定义

| 层级 | 用途 | 示例 |
|------|------|------|
| `input` | API 输入参数 | 用户提供的原始数据 |
| `z.input<Schema>` | 输入模式 | 验证后的输入类型 |
| `z.output<Schema>` | 输出模式 | 模型生成的响应类型 |
| `z.infer<Schema>` | 推断类型 | TypeScript 类型推导 |

## 最佳实践建议

### 组件设计原则

1. **优先使用接口**：通过抽象接口编程，提高代码的可测试性和可替换性
2. **利用类型系统**：充分利用 TypeScript 和 Zod 的类型检查能力
3. **模块化组合**：将复杂逻辑拆分为可复用的 Runnable 组件

### 性能优化

1. **流式处理**：对实时性要求高的场景使用流式 API
2. **批量操作**：批量处理多个独立请求以提高吞吐量
3. **缓存策略**：对不频繁变化的计算结果进行缓存

### 错误处理

1. **使用 Callbacks**：通过事件系统监控执行过程中的错误
2. **类型验证**：在处理外部输入前进行严格的类型验证
3. **优雅降级**：为可能的失败场景准备降级方案

---

本页面基于 LangChain.js 源码分析了其核心架构和抽象设计。各核心模块相互协作，共同支撑起构建复杂 LLM 应用的基础能力。开发者可以根据这些抽象接口进行扩展和定制，构建满足特定需求的 LangChain 应用。

---

<a id='page-3'></a>

## Agent 与 Chains 实现

### 相关页面

相关主题：[系统架构与核心抽象](#page-2), [向量存储与检索系统](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libs/langchain-core/src/agents/types.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/agents/types.ts)
- [libs/langchain-core/src/messages/ai.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/ai.ts)
- [libs/langchain/src/agents/middleware/hitl.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/middleware/hitl.ts)
- [libs/langchain-classic/src/agents/format_scratchpad/xml.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/agents/format_scratchpad/xml.ts)
- [libs/langchain-classic/src/chains/question_answering/load.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/chains/question_answering/load.ts)
- [libs/langchain-classic/src/chains/llm_chain.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/chains/llm_chain.ts)
</details>

# Agent 与 Chains 实现

## 概述

LangChain.js 中的 Agent 与 Chains 模块构成了构建 LLM 驱动应用的核心架构。Agent 负责动态决策和工具调用，而 Chains 则提供了将多个组件组合成连贯工作流的机制。这两者共同支持了从简单的问答系统到复杂的自主代理应用。

## 核心架构

### Agent 类型系统

LangChain.js 定义了完善的类型系统来支持不同类型的 Agent 实现：

```typescript
// 资料来源：libs/langchain-core/src/agents/types.ts
export type N = typeof START | "model_request" | "tools";
```

类型推断助手允许开发者从 Agent 配置中提取特定类型：

| 工具函数 | 用途 |
|---------|------|
| `InferAgentType<T, "Context">` | 提取上下文类型 |
| `InferAgentMiddleware<T>` | 提取中间件类型 |
| `InferAgentTools<T>` | 提取工具类型 |
| `InferAgentStreamTransformers<T>` | 提取流转换器类型 |

```typescript
// 资料来源：libs/langchain-core/src/agents/types.ts
/**
 * Shorthand helper to extract the Tools type from an AgentTypeConfig or ReactAgent.
 */
export type InferAgentTools<T> = InferAgentType<T, "Tools">;
```

### 中断机制

Agent 系统支持中断功能，用于实现 Human-in-the-Loop (HITL) 模式：

```typescript
// 资料来源：libs/langchain/src/agents/middleware/hitl.ts
export interface Interrupt<TValue = unknown> {
  // 表示中断状态的接口
}
```

Interrupt 配置支持动态描述生成：

```typescript
// 资料来源：libs/langchain/src/agents/middleware/hitl.ts
const formatToolDescription: DescriptionFactory = (
  toolCall: ToolCall,
  state: AgentBuiltInState,
  runtime: Runtime<unknown>
) => {
  return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
};
```

## Agent 实现类型

### ReAct Agent

ReAct (Reasoning + Acting) Agent 结合了推理和行动能力，通过中间步骤处理复杂任务。

### OpenAI Functions Agent

针对 OpenAI 函数调用能力优化的 Agent，利用结构化输出进行工具选择。

### Structured Chat Agent

支持结构化聊天交互的 Agent，适合需要复杂参数的工具调用场景。

## Chains 实现

### LLMChain

LLMChain 是最基本的链实现，用于将提示模板与 LLM 结合：

```typescript
// 资料来源：libs/langchain-classic/src/chains/llm_chain.ts
const llmChain = new LLMChain({ prompt, llm, verbose });
```

### 问答链加载

LangChain 提供了灵活的问答链加载机制：

```typescript
// 资料来源：libs/langchain-classic/src/chains/question_answering/load.ts
export function loadQAStuffChain(
  llm: BaseLanguageModelInterface,
  params: StuffQAChainParams = {}
) {
  const { prompt = QA_PROMPT_SELECTOR.getPrompt(llm), verbose } = params;
  const llmChain = new LLMChain({ prompt, llm, verbose });
  const chain = new StuffDocumentsChain({ llmChain, verbose });
  return chain;
}
```

支持三种主要的问答链类型：

| 链类型 | 描述 | 使用场景 |
|-------|------|---------|
| `stuff` | 将所有文档塞入单个提示 | 文档较少时 |
| `map_reduce` | 分别处理每个文档后汇总 | 文档较多时 |
| `refine` | 迭代式精炼答案 | 需要渐进式推理 |

### 参数配置

```typescript
// 资料来源：libs/langchain-classic/src/chains/question_answering/load.ts
export interface StuffQAChainParams {
  prompt?: BasePromptTemplate;
  verbose?: boolean;
}

export interface MapReduceQAChainParams {
  returnIntermediateSteps?: MapReduceDocumentsChainInput["returnIntermediateSteps"];
  combineMapPrompt?: BasePromptTemplate;
  combinePrompt?: BasePromptTemplate;
  combineLLM?: BaseLanguageModelInterface;
  verbose?: boolean;
}
```

## 工具调用系统

### AIMessage 与 Tool Calls

AIMessage 类集成了工具调用支持，处理消息内容块转换：

```typescript
// 资料来源：libs/langchain-core/src/messages/ai.ts
if (this.tool_calls) {
  const missingToolCalls = this.tool_calls.filter(
    (block) =>
      !blocks.some((b) => b.id === block.id && b.name === block.name)
  );
  blocks.push(
    ...(missingToolCalls.map((block) => ({
      type: "tool_call" as const,
      id: block.id,
      name: block.name,
      args: block.args,
    })) as ContentBlock.Tools.ToolCall[])
  );
}
```

### Action 接口

```typescript
// 资料来源：libs/langchain/src/agents/middleware/hitl.ts
export interface Action {
  /**
   * 动作类型或名称（如 "add_numbers"）
   */
  name: string;
  /**
   * 动作所需参数的键值对（如 {"a": 1, "b": 2}）
   */
  args: Record<string, any>;
}
```

## Scratchpad 格式化

Agent 使用 scratchpad 记录中间推理步骤，支持 XML 格式：

```typescript
// 资料来源：libs/langchain-classic/src/agents/format_scratchpad/xml.ts
export function formatXml(intermediateSteps: AgentStep[]) {
  let log = "";
  for (const step of intermediateSteps) {
    const { action, observation } = step;
    log += `<tool>${action.tool}</tool><tool_input>${action.toolInput}\n</tool_input><observation>${observation}</observation>`;
  }
  return log;
}
```

## 架构流程图

```mermaid
graph TD
    A[用户输入] --> B[Agent 决策]
    B --> C{选择工具?}
    C -->|是| D[执行工具]
    D --> E[获取观察结果]
    E --> B
    C -->|否| F[生成最终响应]
    B --> G{需要人工确认?}
    G -->|是| H[中断并等待]
    H --> I[人类决策]
    I --> B
    G -->|否| F
```

## 消息传递流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant M as AIMessage
    participant T as 工具

    U->>A: 输入请求
    A->>M: 生成消息
    M->>M: 处理 tool_calls
    M->>M: 转换 contentBlocks
    A->>T: 调用工具
    T->>A: 返回结果
    A->>U: 最终响应
```

## 配置与中间件

### InterruptOnConfig 配置

```typescript
// 资料来源：libs/langchain/src/agents/middleware/hitl.ts
const config: InterruptOnConfig = {
  allowedDecisions: ["approve", "edit"],
  description: formatToolDescription,
  argsSchema: z.record(z.any()).optional(),
};
```

### 配置参数说明

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `allowedDecisions` | `string[]` | 否 | 允许的决策列表 |
| `description` | `string \| DescriptionFunction` | 否 | 决策描述 |
| `argsSchema` | `Record<string, any>` | 否 | 参数的 JSON Schema |

## 测试匹配器

LangChain 提供了专门的测试匹配器用于验证 Agent 行为：

```typescript
// 资料来源：libs/langchain-core/src/testing/matchers.ts
export const langchainMatchers = {
  toBeHumanMessage,
  toBeAIMessage,
  toBeSystemMessage,
  toBeToolMessage,
  toHaveToolCalls,
  toHaveToolCallCount,
  toContainToolCall,
  toHaveToolMessages,
  toHaveBeenInterrupted,
  toHaveStructuredResponse,
};
```

## 最佳实践

### 工具选择策略

1. **评估任务复杂度**：简单任务使用单一工具，复杂任务考虑多工具协作
2. **定义清晰的工具描述**：确保 Agent 能准确理解工具用途
3. **处理工具调用失败**：实现降级策略和错误恢复机制

### Chain 组合建议

1. **从 LLMChain 开始**：验证基础功能后再组合复杂链
2. **使用输入输出映射**：确保数据在链之间正确传递
3. **添加错误处理**：为每个链组件添加适当的异常处理

## 版本迁移

`@langchain/classic` 包保留了 v0.x 版本的链实现，用于向后兼容：

```typescript
// 资料来源：libs/langchain-classic/README.md
- `LLMChain` - Basic chain for calling an LLM with a prompt template
- `ConversationalRetrievalQAChain` - Chain for conversational question-answering
- `RetrievalQAChain` - Chain for question-answering over documents
```

新项目推荐使用 `createAgent` API 获取更好的性能和更清晰的接口。

---

<a id='page-4'></a>

## 向量存储与检索系统

### 相关页面

相关主题：[Agent 与 Chains 实现](#page-3), [扩展提供商与工具集成](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libs/langchain-classic/src/vectorstores/memory.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/vectorstores/memory.ts)
- [libs/providers/langchain-pinecone/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-pinecone/README.md)
- [libs/providers/langchain-qdrant/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-qdrant/README.md)
- [libs/langchain-classic/src/retrievers/parent_document.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/retrievers/parent_document.ts)
- [libs/langchain-classic/src/retrievers/multi_query.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/retrievers/multi_query.ts)
- [examples/src/langchain-classic/indexes/html_text_splitter.ts](https://github.com/langchain-ai/langchainjs/blob/main/examples/src/langchain-classic/indexes/html_text_splitter.ts)
- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)
</details>

# 向量存储与检索系统

## 概述

LangChain.js 的向量存储与检索系统是构建检索增强生成（RAG）应用的核心基础设施。该系统提供了一套完整的接口和实现，用于将文档转换为向量表示、存储在各种向量数据库中，并通过语义相似性进行高效检索。

系统设计遵循模块化原则，提供了统一的 `VectorStore` 接口规范，使得不同的向量存储后端可以无缝切换。开发者可以根据数据规模、查询性能和部署需求选择合适的存储方案，同时保持上层应用代码的一致性。

LangChain.js 支持多种主流向量数据库集成，包括内存存储（用于开发测试）、Pinecone、Qdrant、MongoDB Atlas Search、PostgreSQL PGVector 等，为企业级应用提供了丰富的选择。

## 核心架构

### 系统组件关系

LangChain.js 的向量存储与检索系统由多个核心组件构成，这些组件协同工作以实现完整的文档处理和检索流程。

```mermaid
graph TD
    A[文档输入] --> B[文本分割器 Text Splitters]
    B --> C[向量化 Embeddings]
    C --> D[向量存储 VectorStore]
    D --> E[检索器 Retrievers]
    E --> F[应用层]
    
    G[Embedding Models] --> C
    
    H[Pinecone] --> D
    I[Qdrant] --> D
    J[MongoDB] --> D
    K[PGVector] --> D
    L[Memory] --> D
```

### 数据处理流程

文档从原始格式到可检索向量的转换过程涉及多个阶段，每个阶段都有明确的职责边界。

```mermaid
graph LR
    A[原始文档] --> B[文本分割]
    B --> C[小文档块]
    C --> D[调用 Embeddings API]
    D --> E[向量 + 元数据]
    E --> F[存储到 VectorStore]
    
    G[用户查询] --> H[查询向量化]
    H --> I[相似度搜索]
    I --> J[返回相关文档]
```

## 向量存储接口

### VectorStore 基类

`VectorStore` 是所有向量存储实现的基础抽象接口，定义了向量存储的核心操作方法。所有具体的向量存储实现都继承自这个接口，确保了 API 的一致性和可替换性。

接口主要包含以下几个核心方法：

```typescript
class VectorStore {
  // 添加文档到向量存储
  async addDocuments(documents: Document[]): Promise<void>
  
  // 通过相似度搜索查找相关文档
  async similaritySearch(
    query: string, 
    k?: number
  ): Promise<Document[]>
  
  // 带相似度分数的搜索
  async similaritySearchWithScore(
    query: string,
    k?: number
  ): Promise<[Document, number][]>
  
  // 删除文档
  async delete(ids?: string[]): Promise<void>
  
  // 跨链支持
  asRetriever(config?: SimilarityRetrieverConfig): BaseRetriever
}
```

### 内存向量存储

`MemoryVectorStore` 是最简单的向量存储实现，将所有向量存储在内存中。这种实现适用于开发测试、小规模数据集，或作为原型验证阶段的首选方案。由于数据存储在内存中，应用重启后数据会丢失，不适合生产环境使用。

```typescript
import { MemoryVectorStore } from 'langchain/vectorstores/memory'
import { OpenAIEmbeddings } from '@langchain/openai'

const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
})

const vectorStore = new MemoryVectorStore(embeddings)

const documents = [
  { pageContent: "文档内容示例", metadata: { source: "doc1" } },
  { pageContent: "另一篇文档内容", metadata: { source: "doc2" } }
]

await vectorStore.addDocuments(documents)

const results = await vectorStore.similaritySearch("查询文本", 2)
```

## 第三方向量存储集成

### Pinecone 集成

Pinecone 是一个托管的向量数据库服务，提供高性能的向量存储和检索能力。LangChain.js 通过 `@langchain/pinecone` 包提供了完整的集成支持。

#### 安装配置

```bash
npm install @langchain/pinecone @langchain/core @pinecone-database/pinecone
```

#### 使用示例

```typescript
import { PineconeStore } from '@langchain/pinecone'
import { Pinecone } from '@pinecone-database/pinecone'
import { OpenAIEmbeddings } from '@langchain/openai'

const pinecone = new Pinecone()
const index = pinecone.Index('your-index-name')

const vectorStore = await PineconeStore.fromExistingIndex(
  new OpenAIEmbeddings(),
  { pineconeIndex: index }
)
```

### Qdrant 集成

Qdrant 是一个开源的向量相似度搜索引擎，支持混合搜索和过滤。`@langchain/qdrant` 包提供了与 Qdrant 的完整集成。

#### 安装配置

```bash
npm install @langchain/qdrant
```

#### 核心特性

| 特性 | 说明 |
|------|------|
| 混合搜索 | 支持向量搜索与关键词搜索结合 |
| 过滤条件 | 支持元数据过滤 |
| 集合管理 | 提供集合创建和管理接口 |
| 距离度量 | 支持 Cosine、Euclidean、Dot 产品 |

### MongoDB Atlas Search

MongoDB Atlas Search 提供了基于 Lucene 的全文搜索能力，结合 MongoDB 的文档模型，可以存储和检索带有多维向量的文档。`@langchain/mongodb` 包提供了这一集成。

### PGVector 集成

对于已在使用 PostgreSQL 的团队，PGVector 提供了在关系数据库中存储和检索向量的能力。`@langchain/pgvector` 包支持这一集成，使得可以利用现有的 PostgreSQL 基础设施。

#### 配置参数

| 参数 | 类型 | 说明 |
|------|------|------|
| connectionString | string | PostgreSQL 连接字符串 |
| tableName | string | 存储向量的表名（默认：langchain_vectorstore） |
| columns | object | 向量和元数据列的配置 |
| distanceStrategy | string | 距离计算策略 |

## 检索器系统

检索器（Retriever）是连接向量存储和应用逻辑的关键组件。LangChain.js 提供了多种检索器实现，以适应不同的检索场景和需求。

### 父文档检索器

`ParentDocumentRetriever` 解决了小文本块丢失上下文信息的问题。该检索器首先检索与查询相关的小文本块，然后返回这些小块所属的完整父文档。

```mermaid
graph TD
    A[用户查询] --> B[检索小块]
    B --> C[获取父文档ID]
    C --> D[加载完整父文档]
    D --> E[返回带上下文的结果]
    
    F[小块1] --> G[父文档A]
    H[小块2] --> G
    I[小块3] --> J[父文档B]
```

这种策略在保持检索精确性的同时，确保返回的内容具有完整的上下文信息，特别适用于需要返回较长连续文本的场景。

### 多查询检索器

`MultiQueryRetriever` 通过使用语言模型生成多个不同角度的查询，然后对所有查询的结果进行去重合并，从而提高检索的召回率。

```typescript
import { MultiQueryRetriever } from 'langchain/retrievers/multi_query'

const retriever = MultiQueryRetriever.fromLLM({
  llm: chatModel,
  retriever: baseRetriever,
  includeOriginal: true,
  verbose: true,
})
```

| 参数 | 说明 |
|------|------|
| llm | 用于生成多查询的语言模型 |
| retriever | 基础检索器 |
| includeOriginal | 是否包含原始查询的结果 |
| verbose | 是否输出详细日志 |

### 检索器配置

所有检索器都支持通过配置对象进行定制化设置，主要配置选项包括：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| k | 返回的文档数量 | 4 |
| filter | 元数据过滤条件 | undefined |
| namespace | 命名空间（部分向量存储支持） | undefined |

## 文本分割器

文本分割器是将长文档拆分为适合嵌入和检索的小块的关键组件。`@langchain/textsplitters` 包提供了多种分割策略。

### 递归字符分割器

`RecursiveCharacterTextSplitter` 是最常用的分割器，它按照预定义的字符优先级递归地分割文本，确保语义完整性。

```typescript
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters"

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
})

const output = await splitter.createDocuments([text])
```

### 分割参数说明

| 参数 | 类型 | 说明 |
|------|------|------|
| chunkSize | number | 每个块的最大字符数 |
| chunkOverlap | number | 相邻块之间的重叠字符数 |
| separators | string[] | 分割符列表（按优先级排序） |

### 语言特定分割

分割器支持针对不同内容类型进行优化配置：

```typescript
// Markdown 文档
const mdSplitter = RecursiveCharacterTextSplitter.fromLanguage("markdown", {
  chunkSize: 1000,
  chunkOverlap: 100,
})

// 代码文件
const codeSplitter = RecursiveCharacterTextSplitter.fromLanguage("js", {
  chunkSize: 500,
  chunkOverlap: 50,
})

// HTML 文档
const htmlSplitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
})
```

## Embeddings 集成

Embeddings 是将文本转换为向量表示的模型。LangChain.js 通过标准化的接口支持多种 Embeddings 提供商。

### 接口定义

```typescript
interface Embeddings {
  embedQuery(text: string): Promise<number[]>
  embedDocuments(texts: string[]): Promise<number[][]>
}
```

### 支持的提供商

| 提供商 | 包名 | 说明 |
|--------|------|------|
| OpenAI | @langchain/openai | text-embedding-3-small/large |
| Google | @langchain/google-vertexai | Palm/Embedding-Gecko |
| Anthropic | @langchain/anthropic | Claude 内置支持 |
| Cohere | @langchain/cohere | Embed v3/v4 |
| HuggingFace | @langchain/huggingface | 数千种开源模型 |

## 最佳实践

### 数据处理流程

构建高效的向量检索系统需要遵循系统化的数据处理流程。在数据准备阶段，应根据内容类型选择合适的分割策略：结构化文档使用语义分割，代码文件按函数或类分割，网页内容按 HTML 标签语义分割。

```mermaid
graph TD
    A[数据收集] --> B[数据清洗]
    B --> C[内容分类]
    C --> D[选择分割策略]
    D --> E[文本分割]
    E --> F[向量化]
    F --> G[质量检查]
    G --> H{是否合格}
    H -->|否| E
    H -->|是| I[存储向量]
    I --> J[索引优化]
```

### 查询优化

在进行相似性搜索时，应充分利用向量数据库的过滤功能，在向量相似度计算前先进行元数据过滤，以减少搜索范围并提高准确性。对于复杂的查询场景，考虑使用混合搜索策略，结合向量相似度和关键词匹配。

### 生产环境考虑

生产环境中应重点关注向量存储的索引配置、查询延迟监控、以及 Embeddings 模型的选择。对于大规模数据集，Pinecone 或 Qdrant 等专用向量数据库通常比通用数据库提供更好的性能。同时应建立 Embeddings 缓存机制，避免对相同文本重复进行向量化计算。

## 相关资源

- [官方文档](https://docs.langchain.com/oss/javascript/langchain)
- [@langchain/textsplitters 文档](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)
- [@langchain/pinecone 文档](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-pinecone/README.md)
- [@langchain/qdrant 文档](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-qdrant/README.md)

---

<a id='page-5'></a>

## 主要模型提供商集成

### 相关页面

相关主题：[系统架构与核心抽象](#page-2), [扩展提供商与工具集成](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/src/chat_models.ts)
- [libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/chat_models/index.ts)
- [libs/langchain-classic/src/vectorstores/memory.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/vectorstores/memory.ts)
- [libs/langchain-core/src/messages/message.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/message.ts)
- [libs/langchain-core/src/language_models/utils.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/utils.ts)
</details>

# 主要模型提供商集成

## 概述

LangChain.js 的主要模型提供商集成模块为开发者提供了统一的接口，用于对接多个主流 AI 服务提供商的 chat models。这些集成通过标准化的抽象层，使得应用程序能够在不同提供商之间无缝切换，同时保持代码的兼容性和可维护性。

集成模块位于 `libs/providers/` 目录下，支持的提供商包括 OpenAI、Anthropic、Google Vertex AI、Google GenAI、Mistral AI 等主流 LLM 服务商。每个提供商都实现了统一的 chat model 接口规范，确保了调用方式的一致性。

## 架构设计

### 核心抽象层

LangChain.js 采用分层架构设计，模型提供商集成位于基础设施层之上，为上层应用提供统一的 AI 能力访问接口。

```mermaid
graph TD
    A[应用层 Application] --> B[链与代理层 Chains & Agents]
    B --> C[模型抽象层 Model Abstraction]
    C --> D[提供商集成层 Provider Integrations]
    D --> E[OpenAI]
    D --> F[Anthropic]
    D --> G[Google Vertex]
    D --> H[Mistral AI]
    E --> I[外部 API 服务]
    F --> I
    G --> I
    H --> I
```

### 消息标准化

每个模型集成都实现了消息格式的标准化转换，确保不同提供商的消息结构能够被正确处理。核心的消息类型定义位于 `libs/langchain-core/src/messages/message.ts`，包括工具定义（`MessageToolDefinition`）、工具集（`MessageToolSet`）等关键数据结构。

```mermaid
graph LR
    A[用户消息] --> B[标准化消息格式]
    B --> C[Provider-specific 转换]
    C --> D[API 请求格式]
    D --> E[模型提供商]
```

## 核心功能特性

### 统一调用接口

所有 chat model 实现都遵循统一的调用模式，支持 `invoke` 方法进行同步调用和 `stream` 方法进行流式响应处理。这种设计使得开发者可以在不修改应用代码的情况下更换底层模型提供商。

```typescript
// 统一的调用方式
const result = await llm.invoke(input);
for await (const chunk of await llm.stream(input)) {
  console.log(chunk);
}
```

资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()

### 结构化输出

模型集成支持通过 `withStructuredOutput()` 方法实现结构化输出，该功能使用提供商的原生工具调用能力来约束输出格式到特定的 JSON schema。

| 功能 | 描述 | 实现方式 |
|------|------|----------|
| 函数调用 | 使用工具调用约束输出 | `withStructuredOutput()` |
| JSON Schema | 使用原生 JSON schema 支持 | Provider 原生功能 |
| 类型安全 | 提供完整的 TypeScript 类型推导 | Zod schema 定义 |

资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()

### 工具调用支持

集成模块提供了完整的工具调用（Tool Calling）支持，允许模型调用外部工具和函数。这一功能通过 `tool()` 辅助函数实现，支持 Zod schema 定义工具参数。

```typescript
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async (input) => `Weather in ${input.location}`,
  {
    name: "get_weather",
    description: "Get weather for a location",
    schema: z.object({ location: z.string() }),
  }
);
```

资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()

## OpenAI 集成

### 基本配置

OpenAI 集成提供了对 GPT 系列模型的访问支持，核心实现在 `libs/providers/langchain-openai/src/chat_models/index.ts`。

```typescript
import { ChatOpenAI } from "@langchain/openai";

const llm = new ChatOpenAI({
  model: "gpt-4o",
  temperature: 0.7,
  // 其他配置参数...
});
```

### 流式响应处理

OpenAI 集成支持流式输出，响应包含内容块、元数据和 token 使用统计信息。

```txt
AIMessageChunk {
  "id": "chatcmpl-9u4NWB7yUeHCKdLr6jP3HpaOYHTqs",
  "content": ""
}
AIMessageChunk {
  "content": "J"
}
AIMessageChunk {
  "content": "'adore"
}
```

资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts]()

## Anthropic 集成

### 特性概述

Anthropic 集成专门针对 Claude 系列模型进行了优化，提供了额外的特性支持，包括高级工具使用和搜索功能。

| 特性 | 描述 | 适用版本 |
|------|------|----------|
| 标准工具调用 | 基础函数调用功能 | 所有版本 |
| 工具搜索 | 使用 regex 或 bm25 搜索工具 | 需 `advanced-tool-use-2025-11-20` beta |
| 延迟加载工具 | 按需加载不常用工具 | 支持 `defer_loading: true` |

资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()

### 消息块翻译

Anthropic 集成实现了消息块翻译器（BlockTranslator）接口，用于在标准格式和提供商特定格式之间进行转换：

```typescript
BlockTranslator = {
  translateContent: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletions(message);
    }
    return convertToV1FromResponses(message);
  },
  translateContentChunk: (message) => { /* ... */ },
};
```

资料来源：[libs/langchain-core/src/messages/block_translators/openai.ts]()

## 向量存储与嵌入集成

### 内存向量存储

LangChain.js 提供了 `MemoryVectorStore` 实现，用于在内存中存储和检索文档向量。该存储与嵌入模型配合使用，支持添加文档和相似性搜索功能。

```typescript
import { MemoryVectorStore } from 'langchain/vectorstores/memory';
import { OpenAIEmbeddings } from '@langchain/openai';

const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const vectorStore = new MemoryVectorStore(embeddings);

// 添加文档
await vectorStore.addDocuments(documents);

// 相似性搜索
const results = await vectorStore.similaritySearch("thud", 1);
```

资料来源：[libs/langchain-classic/src/vectorstores/memory.ts]()

### 嵌入模型配置

嵌入模型是 RAG（检索增强生成）管道的核心组件，用于将文本转换为向量表示。每个模型提供商都提供了相应的嵌入实现。

## 消息与工具系统

### 消息结构

LangChain.js 定义了标准化的消息结构体系，包括基础消息类型、工具定义和工具调用块等核心组件。

```mermaid
classDiagram
    class MessageToolDefinition {
        +TInput input
        +TOutput output
    }
    
    class MessageToolSet {
        +[key: string]: MessageToolDefinition
    }
    
    class MessageToolCallBlock {
        +string type
        +string name
        +Record args
        +string? id
    }
    
    MessageToolSet --> MessageToolDefinition : contains
```

资料来源：[libs/langchain-core/src/messages/message.ts]()

### 工具调用块类型

工具调用块是消息系统中表示工具调用的关键数据结构，其类型定义如下：

```typescript
type $MessageToolCallBlock<TStructure extends MessageStructure> = {
  type: "tool_call";
  name: string;
  args: TStructure["tools"][keyof TStructure["tools"]]["input"];
  id?: string;
};
```

资料来源：[libs/langchain-core/src/messages/message.ts]()

## 标准消息内容转换

### 内容转换工具

`castStandardMessageContent` 函数是 LangChain.js 消息处理的核心工具，用于标准化消息内容格式：

```typescript
function castStandardMessageContent<T extends BaseMessage>(message: T) {
  const Cls = message.constructor as Constructor<T>;
  return new Cls({
    ...message,
    content: message.contentBlocks,
    response_metadata: {
      ...message.response_metadata,
      output_version: "v1",
    },
  });
}
```

该函数将消息的内容块转换为标准内容格式，并附加 v1 输出版本元数据，确保了不同提供商之间的兼容性。

资料来源：[libs/langchain-core/src/language_models/utils.ts]()

## 安装与配置

### 依赖管理

每个模型提供商包都依赖 `@langchain/core` 作为 peer dependency。建议在项目 `package.json` 中统一管理依赖版本以避免冲突：

```json
{
  "dependencies": {
    "@langchain/anthropic": "^0.0.9",
    "@langchain/openai": "^0.0.9",
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  }
}
```

资料来源：[libs/providers/langchain-anthropic/README.md]()

### 环境变量配置

不同的提供商需要设置相应的 API 密钥：

```bash
# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Google Cloud
export GOOGLEAPPLICATIONCREDENTIALS="/path/to/credentials.json"
```

## 最佳实践

### 提供商选择指南

| 使用场景 | 推荐提供商 | 理由 |
|----------|------------|------|
| 通用对话 | OpenAI GPT-4o | 性能与成本平衡 |
| 长上下文 | Anthropic Claude | 支持 200K token 上下文 |
| 代码生成 | OpenAI / Anthropic | 两者都有优秀的代码能力 |
| 本地部署 | Ollama / Llama.cpp | 无需 API 费用 |

### 错误处理策略

实现模型调用时应考虑网络错误、速率限制和配额耗尽等异常情况。建议使用指数退避重试机制，并实现适当的降级策略。

### 性能优化建议

1. **批量处理**：将多个请求合并为批量调用（如果提供商支持）
2. **流式响应**：对于长文本输出，使用流式响应减少等待时间
3. **缓存**：对重复查询实现结果缓存
4. **连接复用**：保持 HTTP 连接活跃以减少建立开销

## 相关资源

- 官方文档：[LangChain.js 文档](https://js.langchain.com/)
- API 参考：[Provider 包文档](https://github.com/langchain-ai/langchainjs/tree/main/libs/providers)
- 示例代码：[examples 目录](https://github.com/langchain-ai/langchainjs/tree/main/examples)

---

<a id='page-6'></a>

## 扩展提供商与工具集成

### 相关页面

相关主题：[主要模型提供商集成](#page-5), [扩展开发指南](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/src/chat_models.ts)
- [libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/chat_models/index.ts)
- [libs/providers/langchain-openai/src/utils/tools.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/utils/tools.ts)
- [libs/langchain-core/src/messages/block_translators/openai.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/block_translators/openai.ts)
- [libs/langchain-core/src/messages/ai.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/ai.ts)
- [libs/langchain-core/src/messages/message.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/message.ts)
- [libs/langchain-core/src/language_models/utils.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/utils.ts)
- [libs/langchain/src/agents/types.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/types.ts)
- [libs/langchain/src/agents/middleware/hitl.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/middleware/hitl.ts)
- [libs/langchain-core/src/testing/matchers.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/testing/matchers.ts)
</details>

# 扩展提供商与工具集成

## 概述

LangChain.js 的扩展提供商系统是一个模块化架构，允许通过不同的提供商 SDK 集成各种大语言模型（LLM）服务。每个提供商都实现了统一的接口规范，同时保留了各自平台特有的功能特性。工具集成是这些提供商的核心能力之一，它使得 AI 模型能够调用外部函数来执行特定任务，如计算、搜索、数据处理等。

在 LangChain.js 的架构中，工具集成涉及三个主要层面的抽象：工具定义层、消息传输层和提供商适配层。工具定义使用统一的 TypeScript 类型系统描述工具的输入输出结构，消息传输层负责在不同格式之间进行转换，而提供商适配层则处理与各个 AI 服务提供商的特定集成细节。

## 工具定义系统

### 核心类型定义

LangChain.js 在 `libs/langchain-core/src/messages/message.ts` 中定义了工具系统的核心类型结构。这些类型构成了整个工具集成的基础架构，提供了类型安全的工具定义和调用机制。

```typescript
export interface MessageToolDefinition<TInput = unknown, TOutput = unknown> {
  input: TInput;
  output: TOutput;
}

export interface MessageToolSet {
  [key: string]: MessageToolDefinition;
}
```

资料来源：[libs/langchain-core/src/messages/message.ts:1-15]()

`MessageToolDefinition` 接口使用泛型参数定义工具的输入和输出类型，允许开发者为每个工具指定精确的数据结构。`MessageToolSet` 接口则是一个映射类型，将工具名称与对应的工具定义关联起来。

### 工具调用块结构

工具调用块（Tool Call Block）是消息中表示工具调用的数据结构，包含工具名称、参数和可选的调用标识符。这个结构在 `MessageStructure` 的工具扩展部分定义：

```typescript
type CalcToolCall = $MessageToolCallBlock<MyStructure>;
// Resolves to:
// {
//   type: "tool_call";
//   name: "calculator";
//   args: { operation: string, numbers: number[] };
//   id?: string;
// }
```

资料来源：[libs/langchain-core/src/messages/message.ts:50-70]()

这种结构设计确保了工具调用的自包含性，每个调用都包含足够的上下文信息来执行对应的工具函数。`id` 字段是可选的，允许在不需要追踪单个调用的情况下省略。

## 消息格式转换层

### OpenAI 格式翻译器

LangChain.js 的 `block_translators` 模块提供了不同消息格式之间的转换能力。在 `libs/langchain-core/src/messages/block_translators/openai.ts` 中实现的 `BlockTranslator` 是核心的转换逻辑：

```typescript
BlockTranslator = {
  translateContent: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletions(message);
    }
    return convertToV1FromResponses(message);
  },
  translateContentChunk: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletionsChunk(message);
    }
    return convertToV1FromResponsesChunk(message);
  },
};
```

资料来源：[libs/langchain-core/src/messages/block_translators/openai.ts:1-15]()

翻译器根据消息内容类型选择不同的转换路径。对于字符串内容，它使用 Chat Completions 格式的转换器；对于数组格式的内容，则使用 Responses API 格式的转换器。这种设计允许系统同时支持 OpenAI 的两种主要 API 风格。

### 标准消息内容转换

`libs/langchain-core/src/language_models/utils.ts` 中的 `castStandardMessageContent` 函数提供了标准消息内容的转换能力，确保消息格式在不同版本之间保持兼容性：

```typescript
function castStandardMessageContent<T extends BaseMessage>(message: T) {
  const Cls = message.constructor as Constructor<T>;
  return new Cls({
    ...message,
    content: message.contentBlocks,
    response_metadata: {
      ...message.response_metadata,
      output_version: "v1",
    },
  });
}
```

资料来源：[libs/langchain-core/src/language_models/utils.ts:8-20]()

该函数通过重建消息实例来确保内容块被正确格式化，同时在响应元数据中添加版本标识，便于后续处理和调试。

## AIMessage 工具集成

### 内容块生成逻辑

`AIMessage` 类在 `libs/langchain-core/src/messages/ai.ts` 中实现了复杂的工具调用整合逻辑。其 `contentBlocks` getter 方法负责合并基础内容与工具调用信息：

```typescript
override get contentBlocks(): ContentBlock[] {
  if (
    "model_provider" in this.response_metadata &&
    typeof this.response_metadata.model_provider === "string"
  ) {
    const translator = getTranslator(this.response_metadata.model_provider);
    if (translator) {
      return translator.translateContent(this as AIMessage);
    }
  }

  const blocks = super.contentBlocks;

  if (this.tool_calls) {
    const missingToolCalls = this.tool_calls.filter(
      (block) =>
        !blocks.some((b) => b.id === block.id && b.name === block.name)
    );
    blocks.push(
      ...(missingToolCalls.map((block) => ({
        type: "tool_call" as const,
        id: block.id,
        name: block.name,
        args: block.args,
      })) as ContentBlock.Tools.ToolCall[])
    );
  }

  return blocks;
}
```

资料来源：[libs/langchain-core/src/messages/ai.ts:1-35]()

该逻辑首先检查响应元数据中是否包含模型提供商信息，如果有则使用对应的翻译器进行格式转换。如果不存在翻译器，则采用默认逻辑，将 `tool_calls` 数组中的工具调用转换为内容块。过滤逻辑确保不会重复添加已存在于基础内容中的工具调用。

### 类型守卫机制

AIMessage 类提供了静态类型守卫方法来安全地识别消息类型：

```typescript
static isInstance<T extends MessageStructure>(
  obj: BaseMessage<T>
): obj is BaseMessage<T> & AIMessage<T>;
static isInstance(obj: unknown): obj is AIMessage;
```

资料来源：[libs/langchain-core/src/messages/ai.ts:60-68]()

这两个重载分别处理泛型和非泛型场景，允许在类型安全的情况下进行类型收窄和断言。

## 提供商工具格式处理

### OpenAI 工具格式

`libs/providers/langchain-openai/src/utils/tools.ts` 中定义了 OpenAI 特定的工具格式转换逻辑：

```typescript
IClient.Chat.ChatCompletionCustomTool = {
  getFormat: () => {
    if (!tool.format) {
      return undefined;
    }
    if (tool.format.type === "grammar") {
      return {
        type: "grammar" as const,
        grammar: {
          definition: tool.format.definition,
          syntax: tool.format.syntax,
        },
      };
    }
    if (tool.format.type === "text") {
      return {
        type: "text" as const,
      };
    }
    return undefined;
  },
  return {
    type: "custom",
    custom: {
      name: tool.name,
      description: tool.description,
      format: getFormat(),
    },
  };
};
```

资料来源：[libs/providers/langchain-openai/src/utils/tools.ts:1-35]()

OpenAI 支持多种工具格式类型，包括 `grammar` 格式（包含语法定义和语法规则）和 `text` 格式。这种灵活性允许开发者为不同的用例选择最合适的格式定义方式。`custom` 类型包装了所有自定义工具，确保符合 OpenAI API 的工具规范。

### Anthropic 流式响应

Anthropic 提供商在 `libs/providers/langchain-anthropic/src/chat_models.ts` 中处理流式响应，其输出格式与 OpenAI 不同，使用 `additional_kwargs` 传递工具元数据：

```txt
AIMessageChunk {
  "id": "msg_01N8MwoYxiKo9w4chE4gXUs4",
  "content": "",
  "additional_kwargs": {
    "id": "msg_01N8MwoYxiKo9w4chE4gXUs4",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4-5-20250929"
  },
  "usage_metadata": {
    "input_tokens": 25,
    "output_tokens": 1,
    "total_tokens": 26
  }
}
```

资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts:50-75]()

Anthropic 的流式响应以增量方式返回内容块，每个 `AIMessageChunk` 包含部分内容。这种设计优化了响应延迟，使得用户可以尽快看到初始输出。

## Agent 工具集成

### Agent 类型定义

`libs/langchain/src/agents/types.ts` 中定义了 Agent 的类型系统，包括工具配置选项：

```typescript
interface AgentConfig {
  model: string | AgentLanguageModelLike;
  
  tools?: (ServerTool | ClientTool)[];
  
  systemMessage?: string | SystemMessage;
}
```

资料来源：[libs/langchain/src/agents/types.ts:1-20]()

Agent 配置中的 `tools` 字段接受 `ServerTool` 或 `ClientTool` 类型的数组，允许 Agent 访问可用的工具集合。系统消息可以是简单的字符串或包含数组内容的 `SystemMessage`，后者支持更复杂的结构化内容。

### 工具调用中间件

`libs/langchain/src/agents/middleware/hitl.ts` 实现了人机协作的中间件系统，允许在工具执行前进行干预：

```typescript
export interface Action {
  name: string;
  args: Record<string, any>;
}

export interface InterruptOnConfig {
  description?: z.union([z.string(), DescriptionFunctionSchema]).optional();
  argsSchema?: z.record(z.any()).optional();
}
```

资料来源：[libs/langchain/src/agents/middleware/hitl.ts:1-30]()

`Action` 接口定义了工具调用的基本结构，包含动作名称和参数记录。`InterruptOnConfig` 提供了描述工具的选项，可以是静态字符串或动态函数，允许在执行前格式化工具调用的展示信息。

## 测试与验证

### 工具相关匹配器

LangChain.js 提供了专门的测试匹配器来验证工具调用行为，在 `libs/langchain-core/src/testing/matchers.ts` 中实现：

```typescript
export const langchainMatchers = {
  toBeHumanMessage,
  toBeAIMessage,
  toBeSystemMessage,
  toBeToolMessage,
  toHaveToolCalls,
  toHaveToolCallCount,
  toContainToolCall,
  toHaveToolMessages,
  toHaveBeenInterrupted,
  toHaveStructuredResponse,
};
```

资料来源：[libs/langchain-core/src/testing/matchers.ts:1-15]()

这些匹配器提供了丰富的工具调用验证能力：

| 匹配器 | 用途 |
|--------|------|
| `toHaveToolCalls` | 验证消息包含指定数量的工具调用 |
| `toHaveToolCallCount` | 验证工具调用的精确数量 |
| `toContainToolCall` | 验证包含特定名称或参数的工具调用 |
| `toHaveToolMessages` | 验证工具执行后的响应消息 |

工具调用匹配器的使用示例：

```typescript
expect(message).toHaveToolCalls([
  { name: "calculator", args: { operation: "add", a: 1, b: 2 } },
  { name: "translator", args: { text: "hello", targetLanguage: "french" } }
]);
```

资料来源：[libs/langchain-core/src/testing/matchers.ts:25-40]()

## 架构流程图

```mermaid
graph TD
    A[用户定义工具] --> B[MessageToolDefinition]
    B --> C[工具注册到模型]
    C --> D[模型生成工具调用]
    D --> E[工具调用块创建]
    E --> F{提供商类型}
    F -->|OpenAI| G[Chat Completions / Responses API]
    F -->|Anthropic| H[additional_kwargs]
    F -->|其他| I[提供商特定格式]
    G --> J[BlockTranslator转换]
    H --> J
    I --> J
    J --> K[标准v1格式]
    K --> L[Agent执行工具]
    L --> M[工具响应消息]
    M --> N[继续对话循环]
```

## 不同提供商的工具调用差异

| 特性 | OpenAI | Anthropic | 其他提供商 |
|------|--------|-----------|------------|
| 工具定义格式 | `custom` 类型 + `format` | 集成到消息结构 | 各不相同 |
| 流式响应 | `AIMessageChunk` 增量 | `AIMessageChunk` 增量 | 差异较大 |
| 元数据传递 | `tool_calls` 数组 | `additional_kwargs` | 需适配 |
| 格式翻译器 | `BlockTranslator` | 需扩展 | 需扩展 |

## 最佳实践

### 工具定义规范

在 LangChain.js 中定义工具时，应遵循以下规范以确保最佳的跨提供商兼容性：

1. **使用精确的 TypeScript 类型**：为工具的输入和输出定义完整的类型，避免使用 `any` 类型
2. **提供清晰的描述**：工具描述应准确反映功能，便于模型理解何时调用
3. **使用 Zod Schema**：通过 Zod 定义参数验证架构，确保传入参数的有效性

### 消息处理建议

处理包含工具调用的消息时，建议采用以下策略：

1. **始终检查翻译器**：在处理提供商特定格式时，先检查是否存在对应的翻译器
2. **合并重复工具调用**：使用 `AIMessage` 中的过滤逻辑避免重复添加
3. **处理缺失字段**：工具调用块中的 `id` 是可选的，应有合理的降级处理

### 扩展新提供商

为新的 AI 服务提供商添加工具集成支持时，需要实现以下组件：

1. 创建提供商特定的工具格式转换器
2. 实现 `BlockTranslator` 接口的转换方法
3. 在 `getTranslator` 注册新的翻译器
4. 编写集成测试验证功能正确性

## 总结

LangChain.js 的扩展提供商与工具集成系统通过分层架构实现了灵活而强大的工具调用能力。核心类型系统提供了统一的工具定义规范，消息格式转换层确保了不同提供商之间的互操作性，而 Provider 适配层则处理了各个平台的特定实现细节。

这套系统的主要优势包括：类型安全的消息处理、统一的工具定义接口、灵活的消息格式转换，以及完善的测试支持。开发者可以通过实现对应的翻译器和适配器，将新的 AI 提供商集成到 LangChain.js 生态系统中，同时保持与其他提供商的一致性体验。

---

<a id='page-7'></a>

## 多环境部署支持

### 相关页面

相关主题：[依赖管理与测试策略](#page-8), [示例代码与最佳实践](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [environment_tests/README.md](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/README.md)
- [environment_tests/docker-compose.yml](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/docker-compose.yml)
- [environment_tests/test-exports-bun/src/entrypoints.js](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/test-exports-bun/src/entrypoints.js)
- [environment_tests/test-exports-cf/src/entrypoints.js](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/test-exports-cf/src/entrypoints.js)
- [environment_tests/test-exports-vite/src/entrypoints.js](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/test-exports-vercel/src/entrypoints.js)
- [libs/langchain-core/src/utils/signal.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/utils/signal.ts)
</details>

# 多环境部署支持

LangChain.js 通过一套完整的多环境部署测试框架，确保核心库能够在不同的 JavaScript 运行时环境和构建工具中正确运行。该系统覆盖了从服务器端 Node.js 到边缘计算平台的多样化部署场景。

## 概述与设计目标

LangChain.js 的多环境部署支持旨在验证包的导出结构（exports）与目标运行时环境的兼容性。不同的部署环境对模块格式、异步处理和文件系统访问有着截然不同的要求，LangChain.js 通过自动化测试确保这些差异不会导致运行时错误。

核心设计原则包括：

- **环境无关性**：核心抽象层独立于特定运行时环境
- **导出兼容性**：通过 `package.json` 的 `exports` 字段精细控制不同环境的入口点
- **异步标准化**：统一 `AsyncLocalStorage` 和 `AbortSignal` 等跨环境 API 的行为

资料来源：[libs/langchain-core/src/utils/signal.ts:1-50]()

## 支持的部署环境

LangChain.js 维护了一套针对主流运行时和构建工具的兼容性测试：

| 环境类型 | 包名 | 用途说明 |
|---------|------|---------|
| Node.js | `@langchain/core` | 服务端默认环境，支持完整 Node.js API |
| Bun | `test-exports-bun` | Bun 运行时兼容性测试 |
| Cloudflare Workers | `test-exports-cf` | 边缘计算环境测试 |
| Vercel Edge Functions | `test-exports-vercel` | Vercel 边缘函数环境测试 |
| Vite | `test-exports-vite` | 前端构建工具兼容性测试 |

资料来源：[environment_tests/README.md]()
资料来源：[environment_tests/test-exports-bun/src/entrypoints.js]()
资料来源：[environment_tests/test-exports-cf/src/entrypoints.js]()

## 测试框架架构

### 目录结构

```
environment_tests/
├── README.md                    # 测试框架说明文档
├── docker-compose.yml           # Docker 编排配置
├── test-exports-bun/            # Bun 运行时测试
│   └── src/
│       └── entrypoints.js       # 入口点导出验证
├── test-exports-cf/              # Cloudflare Workers 测试
│   └── src/
│       └── entrypoints.js
├── test-exports-vercel/          # Vercel Edge Functions 测试
│   └── src/
│       └── entrypoints.js
└── test-exports-vite/            # Vite 构建工具测试
    └── src/
        └── entrypoints.js
```

资料来源：[environment_tests/docker-compose.yml]()

### 测试流程

```mermaid
graph TD
    A[开始测试] --> B[加载 Docker Compose 配置]
    B --> C{选择测试环境}
    C -->|Bun| D[运行 test-exports-bun]
    C -->|Cloudflare| E[运行 test-exports-cf]
    C -->|Vercel| F[运行 test-exports-vercel]
    C -->|Vite| G[运行 test-exports-vite]
    D --> H[验证入口点导出]
    E --> H
    F --> H
    G --> H
    H --> I{所有测试通过?}
    I -->|是| J[测试成功]
    I -->|否| K[报告环境兼容性问题]
```

## Docker 容器化测试环境

LangChain.js 使用 Docker Compose 管理多环境测试容器，确保测试环境的一致性和可重复性。

### 服务配置

测试框架定义了多个服务容器，每个容器运行特定的运行时环境：

- **基础镜像选择**：针对不同运行环境选择合适的基础镜像
- **依赖安装**：在容器启动时安装项目依赖
- **测试执行**：运行入口点验证脚本

资料来源：[environment_tests/docker-compose.yml]()

## 核心导出机制

### package.json exports 字段

LangChain.js 通过 `package.json` 的 `exports` 字段实现条件导出，为不同环境提供定制化的模块入口：

```javascript
// 条件导出的典型配置
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "default": "./dist/index.js"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.js"
    }
  }
}
```

资料来源：[libs/langchain-core/package.json:1-30]()

### 入口点验证

每个环境测试包包含一个 `entrypoints.js` 文件，用于验证关键导出是否正确可用：

```javascript
// test-exports-bun/src/entrypoints.js 示例
export * from "@langchain/core";
// 验证核心导出在 Bun 环境中可访问
```

资料来源：[environment_tests/test-exports-bun/src/entrypoints.js]()

## 异步与信号处理

LangChain.js 的核心模块实现了跨环境兼容的异步处理机制，这对于在边缘计算环境中运行至关重要。

### AbortSignal 支持

核心模块支持标准的 `AbortSignal` 接口，允许调用者取消异步操作：

```typescript
// libs/langchain-core/src/utils/signal.ts
export interface AbortSignalLike {
  readonly aborted: boolean;
  addEventListener: (type: "abort", listener: () => void) => void;
  removeEventListener: (type: "abort", listener: () => void) => void;
}
```

资料来源：[libs/langchain-core/src/utils/signal.ts:1-30]()

### AsyncLocalStorage 适配

在不支持 `AsyncLocalStorage` 的环境中（如某些边缘运行时），LangChain.js 提供了优雅的降级处理机制，确保核心功能不受影响。

## 边缘计算环境特殊考虑

### Cloudflare Workers

Cloudflare Workers 环境对代码有以下限制：

| 限制类型 | 说明 | 处理方式 |
|---------|------|---------|
| 文件系统 | 仅支持 KV 和 R2 存储 | 使用抽象层访问存储 |
| 运行时 | V8  isolates，无 Node.js API | 使用 web 标准 API |
| 启动时间 | 需极快初始化 | 懒加载非关键模块 |

资料来源：[environment_tests/test-exports-cf/src/entrypoints.js]()

### Vercel Edge Functions

Vercel Edge Functions 运行在 V8 isolates 上，与 Cloudflare Workers 类似需要避免使用 Node.js 特定 API。

## 开发工作流

### 本地测试

开发者可以使用以下命令在本地运行多环境测试：

```bash
# 启动所有测试环境容器
docker-compose up

# 运行特定环境测试
pnpm --filter test-exports-bun test
pnpm --filter test-exports-cf test
```

### CI/CD 集成

多环境测试通常集成到持续集成流程中，确保每次代码变更不会破坏特定环境的兼容性：

1. 检出代码
2. 安装依赖
3. 构建核心包
4. 运行各环境测试
5. 收集并报告结果

## 最佳实践

### 包开发者指南

1. **避免 Node.js 特定 API**：使用 web 标准 API 或条件导入
2. **使用条件导出**：在 `package.json` 中正确配置 `exports` 字段
3. **测试所有目标环境**：在开发周期早期发现问题
4. **处理缺失的全局对象**：如 `AsyncLocalStorage` 不可用时的降级方案

### 环境检测模式

```typescript
// 检测当前环境类型
const isEdge = typeof EdgeRuntime !== "undefined";
const isNode = typeof process !== "undefined" && process.versions?.node;
const isBrowser = typeof window !== "undefined";
```

## 相关资源

- [LangChain.js 主仓库](https://github.com/langchain-ai/langchainjs)
- [@langchain/core 核心包](https://github.com/langchain-ai/langchainjs/tree/main/libs/langchain-core)
- [环境测试框架](https://github.com/langchain-ai/langchainjs/tree/main/environment_tests)

---

<a id='page-8'></a>

## 依赖管理与测试策略

### 相关页面

相关主题：[多环境部署支持](#page-7), [扩展开发指南](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)
- [pnpm-workspace.yaml](https://github.com/langchain-ai/langchainjs/blob/main/pnpm-workspace.yaml)
- [internal/standard-tests/src/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/internal/standard-tests/src/index.ts)
- [dependency_range_tests/docker-compose.yml](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/docker-compose.yml)
- [dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js)
</details>

# 依赖管理与测试策略

## 概述

LangChain.js 是一个采用 monorepo 架构的 TypeScript 项目，使用 pnpm workspaces 进行依赖管理，并通过多层次的测试策略确保代码质量。依赖管理策略涵盖了版本控制、依赖范围测试和标准化测试，而测试策略则包括单元测试、集成测试、标准单元测试和标准集成测试等多种测试模式。

该项目的依赖管理核心目标是确保所有 `@langchain/*` 包共享相同版本的 `@langchain/core`，避免因核心库版本不一致导致的兼容性问题。资料来源：[libs/langchain-core/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/package.json)()

## Monorepo 架构

### 工作区结构

LangChain.js 使用 pnpm workspaces 管理多包工作区，所有包位于 `libs/` 目录下。资料来源：[pnpm-workspace.yaml](https://github.com/langchain-ai/langchainjs/blob/main/pnpm-workspace.yaml)()

```mermaid
graph TD
    A[langchainjs Root] --> B[pnpm-workspace.yaml]
    A --> C[package.json]
    A --> D[libs/]
    
    D --> E[langchain-core]
    D --> F[langchain-classic]
    D --> G[langchain-textsplitters]
    D --> H[providers/]
    D --> I[community/]
    
    H --> H1[langchain-anthropic]
    H --> H2[langchain-aws]
    H --> H3[langchain-cohere]
    H --> H4[langchain-xai]
    H --> H5[langchain-mistralai]
    H --> H6[langchain-tavily]
```

### 包类型分类

| 目录 | 包类型 | 说明 |
|------|--------|------|
| `libs/langchain-core` | 核心包 | 包含 LangChain.js 的核心抽象和模式定义 |
| `libs/langchain-classic` | 兼容性包 | 包含从 v0.x 迁移的遗留链和功能 |
| `libs/langchain-textsplitters` | 工具包 | 文本分割器实现 |
| `libs/providers/*` | 集成包 | 各第三方服务提供商集成 |
| `libs/community/*` | 社区包 | 社区维护的集成 |
| `internal/standard-tests` | 内部工具 | 标准化测试框架 |

## 依赖管理策略

### 核心依赖一致性

LangChain.js 要求所有包共享同一个 `@langchain/core` 实例。核心库采用 tilde 依赖版本策略，确保向后兼容性。资料来源：[libs/langchain-core/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/README.md)()

```json
{
  "peerDependencies": {
    "@langchain/core": "~0.3.0"
  },
  "devDependencies": {
    "@langchain/core": "~0.3.0"
  }
}
```

### 依赖覆盖机制

项目推荐在用户项目的 `package.json` 中添加依赖覆盖配置，以强制所有包使用相同版本的核心库：

```mermaid
graph LR
    A[用户项目] --> B[dependencies]
    A --> C[resolutions]
    A --> D[overrides]
    A --> E[pnpm.overrides]
    
    B --> F[@langchain/core]
    B --> G[@langchain/anthropic]
    B --> H[@langchain/cohere]
    
    C --> F
    D --> F
    E --> F
```

支持的包管理器及其覆盖字段：

| 包管理器 | 配置字段 | 示例 |
|----------|----------|------|
| npm/yarn | `resolutions` | `"@langchain/core": "^0.3.0"` |
| npm/yarn | `overrides` | `"@langchain/core": "^0.3.0"` |
| pnpm | `pnpm.overrides` | `"@langchain/core": "^0.3.0"` |

资料来源：[libs/providers/langchain-anthropic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/README.md)()

### 依赖范围测试

项目通过 Docker 环境测试不同依赖版本组合的兼容性，确保包在依赖版本变化时仍能正常工作。

#### Docker 测试环境配置

依赖范围测试使用 Docker Compose 定义测试环境：

```yaml
services:
  test:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - .:/app
    environment:
      - NODE_ENV=test
    command: pnpm test:ranges
```

资料来源：[dependency_range_tests/docker-compose.yml](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/docker-compose.yml)()

#### 自动更新依赖脚本

项目提供脚本自动更新依赖到最新版本：

```javascript
// update_resolutions_latest.js
async function updateResolutions() {
  // 获取 @langchain/core 最新版本
  const latestCore = await getLatestVersion("@langchain/core");
  
  // 更新所有包的 resolutions
  await updateWorkspaceResolutions(latestCore);
}
```

该脚本遍历工作区中的所有包，将 `@langchain/core` 依赖更新到最新版本，验证兼容性后提交更改。资料来源：[dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js)()

## 测试策略

### 测试类型概览

LangChain.js 采用多层次的测试策略，确保代码质量和向后兼容性：

```mermaid
graph TD
    A[测试策略] --> B[单元测试]
    A --> C[集成测试]
    A --> D[标准测试]
    A --> E[导出测试]
    A --> F[依赖范围测试]
    
    B --> B1[vitest run]
    C --> C1[vitest run --mode int]
    D --> D1[standard-unit]
    D --> D2[standard-int]
    E --> E1[test:exports:docker]
    F --> F1[test:ranges:docker]
```

资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()

### 单元测试

单元测试使用 Vitest 框架运行，每个包在 `src/` 目录下包含 `tests/` 文件夹：

| 测试类型 | 文件后缀 | 运行命令 |
|----------|----------|----------|
| 单元测试 | `.test.ts` | `vitest run` |
| 集成测试 | `.int.test.ts` | `vitest run --mode int` |
| 监视模式 | - | `vitest` 或 `vitest --watch` |

```bash
# 运行单元测试
pnpm test

# 运行集成测试
pnpm test:int

# 监视模式运行
pnpm test:watch
```

资料来源：[libs/langchain-core/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/package.json)()

### 标准测试框架

`@langchain/standard-tests` 是项目内部的标准化测试框架，为所有 LangChain 包提供一致的测试接口。资料来源：[internal/standard-tests/src/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/internal/standard-tests/src/index.ts)()

#### 标准测试模块结构

```mermaid
classDiagram
    class StandardTests {
        +runUnitTests()
        +runIntegrationTests()
        +runChatModelTests()
        +runEmbeddingsTests()
        +runVectorStoreTests()
    }
    
    class UnitTestRunner {
        +run()
        +validateOutput()
    }
    
    class IntegrationTestRunner {
        +run()
        +setupFixtures()
        +teardown()
    }
    
    StandardTests --> UnitTestRunner
    StandardTests --> IntegrationTestRunner
```

#### 测试模式

| 模式 | 命令 | 说明 |
|------|------|------|
| 标准单元测试 | `test:standard:unit` | 使用标准测试框架的单元测试 |
| 标准集成测试 | `test:standard:int` | 使用标准测试框架的集成测试 |
| 完整标准测试 | `test:standard` | 运行所有标准测试 |

```bash
# 运行标准测试
pnpm test:standard:unit
pnpm test:standard:int
pnpm test:standard
```

资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()

### 导出兼容性测试

导出测试验证包的导出接口在不同环境（ESM/CJS）下的兼容性：

```mermaid
graph LR
    A[导出测试] --> B[ESM环境]
    A --> C[CJS环境]
    A --> D[Docker容器]
    
    B --> E[import测试]
    C --> F[require测试]
    D --> G[跨环境验证]
```

使用 Docker 环境进行导出测试：

```bash
pnpm test:exports:docker
```

资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()

### 依赖范围测试

依赖范围测试验证包在不同核心库版本下的行为：

```mermaid
graph TD
    A[依赖范围测试] --> B[Docker环境]
    A --> C[版本矩阵]
    A --> D[兼容性验证]
    
    C --> C1[@langchain/core ^0.2.0]
    C --> C2[@langchain/core ^0.3.0]
    C --> C3[@langchain/core latest]
    
    D --> D1[API兼容性]
    D --> D2[类型检查]
    D --> D3[运行时测试]
```

运行依赖范围测试：

```bash
pnpm test:ranges:docker
```

资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()

## CI/CD 集成

### Turbo 构建系统

项目使用 Turbo 进行构建和测试编排：

```json
{
  "scripts": {
    "test:unit:ci": "turbo test",
    "build": "turbo build"
  }
}
```

Turbo 的优势：

| 特性 | 说明 |
|------|------|
| 增量构建 | 仅重新构建变更的包 |
| 并行执行 | 充分利用多核 CPU |
| 远程缓存 | 共享 CI 缓存 |
| 任务管道 | 自动解析任务依赖 |

资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()

### 过滤规则

CI 配置使用过滤器排除不需要测试的包：

```bash
# 排除导出测试、示例和创建集成模板
pnpm test:unit:ci --filter="!test-exports-*" --filter="!examples" --filter="!create-langchain-integration"
```

## 包开发指南

### 创建新集成包

项目提供了集成包模板 `create-langchain-integration`，开发者可以使用该模板快速创建新的提供商集成。资料来源：[libs/create-langchain-integration/template/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/README.md)()

新包开发流程：

1. 使用模板创建包结构
2. 添加 `@langchain/core` 为 peer dependency 和 dev dependency
3. 实现集成代码
4. 添加单元测试和集成测试
5. 运行标准测试验证
6. 提交更改

### 包配置示例

```json
{
  "name": "@langchain/example-provider",
  "version": "0.0.1",
  "type": "module",
  "dependencies": {
    "@example/sdk": "^1.0.0"
  },
  "peerDependencies": {
    "@langchain/core": "~0.3.0"
  },
  "devDependencies": {
    "@langchain/core": "~0.3.0"
  }
}
```

## 最佳实践

### 依赖管理

| 实践 | 说明 |
|------|------|
| 使用 peerDependencies | 声明运行时依赖，让消费者提供核心库 |
| 使用 devDependencies | 仅开发时需要的依赖 |
| 避免直接依赖 | 集成包不应直接依赖其他 `@langchain/*` 包 |
| 版本一致性 | 确保所有包使用相同版本的 `@langchain/core` |

### 测试覆盖

| 测试类型 | 覆盖率目标 | 运行频率 |
|----------|------------|----------|
| 单元测试 | 80%+ | 每次提交 |
| 集成测试 | 核心功能全覆盖 | 每次 PR |
| 标准测试 | 所有包必须通过 | 发布前 |
| 导出测试 | ESM/CJS 双环境 | 发布前 |
| 依赖范围测试 | 主流版本组合 | 每周 |

### 构建验证

在发布包之前，确保完成以下验证步骤：

```mermaid
graph LR
    A[代码编写] --> B[单元测试]
    B --> C[集成测试]
    C --> D[标准测试]
    D --> E[导出测试]
    E --> F[依赖范围测试]
    F --> G[发布]

---

<a id='page-9'></a>

## 扩展开发指南

### 相关页面

相关主题：[扩展提供商与工具集成](#page-6), [示例代码与最佳实践](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libs/create-langchain-integration/create-app.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/create-app.ts)
- [libs/create-langchain-integration/template/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/package.json)
- [CONTRIBUTING.md](https://github.com/langchain-ai/langchainjs/blob/main/CONTRIBUTING.md)
- [libs/langchain-mcp-adapters/src/client.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/client.ts)
- [libs/langchain-mcp-adapters/src/tools.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/tools.ts)
- [libs/langchain-core/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/README.md)
- [libs/providers/langchain-anthropic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/README.md)
- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)
</details>

# 扩展开发指南

LangChain.js 采用模块化架构设计，支持开发者通过扩展机制集成第三方服务和功能。本指南涵盖创建新的集成包、扩展现有功能以及贡献代码的完整流程。

## 概述

LangChain.js 的扩展开发体系包含以下核心组件：

| 组件类型 | 说明 | 位置 |
|---------|------|------|
| 集成包 | 特定服务商的 SDK 封装（如 Anthropic、AWS、Cohere） | `libs/providers/` |
| 核心扩展 | 文本分割器、工具适配器等核心功能 | `libs/langchain-*` |
| MCP 适配器 | Model Context Protocol 工具集成 | `libs/langchain-mcp-adapters/` |
| 社区扩展 | 社区贡献的集成 | `libs/community/` |

## 项目结构

LangChain.js 使用 pnpm monorepo 管理所有包，每个扩展包遵循统一的目录结构：

```
libs/
├── create-langchain-integration/   # 集成创建脚手架
│   ├── create-app.ts               # CLI 入口
│   └── template/                  # 包模板目录
│       └── package.json           # 模板 package.json
├── providers/                      # 官方提供商集成
│   ├── langchain-anthropic/
│   ├── langchain-aws/
│   └── langchain-cohere/
├── langchain-core/                 # 核心抽象层
├── langchain-textsplitters/        # 文本分割实现
└── langchain-mcp-adapters/         # MCP 协议适配器
```

## 创建新集成包

### 使用脚手架工具

LangChain.js 提供了自动化工具来生成新的集成包骨架：

```bash
pnpm create @langchain/integration <package-name>
```

该命令调用 `create-app.ts` 中的逻辑，生成符合规范的包结构。脚手架会自动配置：

- TypeScript 编译配置
- 包名命名规范（`@langchain/<name>`）
- 依赖版本锁定策略

### 包模板结构

生成的模板包含以下关键文件：

| 文件路径 | 用途 |
|---------|------|
| `package.json` | 包元数据、脚本、依赖声明 |
| `README.md` | 安装和使用文档 |
| `src/index.ts` | 包导出入口 |
| `src/<ClassName>.ts` | 主要功能实现 |

### package.json 配置要求

集成包的 `package.json` 必须遵循以下配置规范：

```json
{
  "name": "@langchain/<package-name>",
  "version": "0.0.1",
  "type": "module",
  "dependencies": {
    "<vendor-sdk>": "^<version>"
  },
  "peerDependencies": {
    "@langchain/core": "^1.0.0"
  },
  "devDependencies": {
    "@langchain/core": "workspace:^"
  }
}
```

**关键配置说明：**

| 字段 | 要求 | 说明 |
|-----|------|------|
| `type` | 必须为 `"module"` | ESM 模块支持 |
| `peerDependencies` | 必须包含 `@langchain/core` | 运行时依赖核心包 |
| `devDependencies` | 建议使用 `workspace:^` | 开发时引用本地 core |

资料来源：[libs/create-langchain-integration/template/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/package.json)

## 依赖管理策略

### @langchain/core 版本锁定

为确保所有 LangChain 包使用相同版本的 `@langchain/core`，需要在项目根目录的 `package.json` 中添加版本覆盖配置：

```json
{
  "resolutions": {
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  },
  "pnpm": {
    "overrides": {
      "@langchain/core": "^0.3.0"
    }
  }
}
```

资料来源：[libs/providers/langchain-anthropic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/README.md)

## MCP 适配器开发

Model Context Protocol (MCP) 适配器允许 LangChain 与外部 MCP 服务器通信，访问其提供的工具。

### 客户端架构

```mermaid
graph TD
    A[LangChain Agent] --> B[MCPClient]
    B --> C[MCP Server]
    C --> D[Remote Tools]
    B --> E[MCPTools]
    E --> A
```

### 核心组件

**MCPTools 类** 提供 MCP 工具到 LangChain 工具的转换：

```typescript
// 将 MCP 工具适配为 LangChain 可用格式
export class MCPTools {
  constructor(
    private client: MCPClient,
    private toolNames?: string[]
  ) {}

  getTools(): Tool[] {
    // 返回适配后的工具列表
  }
}
```

资料来源：[libs/langchain-mcp-adapters/src/tools.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/tools.ts)

### 客户端初始化

```typescript
import { MCPClient } from "./client";

const client = new MCPClient({
  name: "my-mcp-client",
  version: "1.0.0",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
});
```

资料来源：[libs/langchain-mcp-adapters/src/client.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/client.ts)

## 构建和测试

### 构建脚本

集成包应包含标准的构建和测试脚本：

| 脚本 | 用途 |
|-----|------|
| `pnpm build` | 编译 TypeScript 生成 dist 目录 |
| `pnpm test` | 运行单元测试 |
| `pnpm test:int` | 运行集成测试 |
| `pnpm lint` | 代码风格检查 |
| `pnpm format` | 代码格式化 |

### 构建流程

LangChain.js 使用 `turbo` 作为构建编排工具：

```bash
pnpm build --filter @langchain/<package-name>
```

单包构建命令：

```bash
cd libs/providers/langchain-anthropic
pnpm build
```

### 测试规范

- 单元测试文件命名：`<name>.test.ts`
- 集成测试文件命名：`<name>.int.test.ts`
- 测试文件位置：`src/tests/` 或根目录 `tests/`

资料来源：[libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)

## 贡献代码

### 贡献流程

```mermaid
graph LR
    A[Fork 仓库] --> B[创建功能分支]
    B --> C[开发实现]
    C --> D[编写测试]
    D --> E[提交 Pull Request]
    E --> F[Code Review]
    F --> G[合并到主分支]
```

### 代码规范

- 遵循 TypeScript 最佳实践
- 使用 ESLint 进行代码检查
- 使用 Prettier 进行代码格式化
- 确保所有新功能包含测试覆盖

### 提交规范

```bash
pnpm lint && pnpm format
```

运行提交前的检查：

```bash
pnpm lint:eslint && pnpm lint:dpdm
```

`dpdm` 工具检查动态导入的循环依赖问题。

资料来源：[CONTRIBUTING.md](https://github.com/langchain-ai/langchainjs/blob/main/CONTRIBUTING.md)

## 包导出配置

### package.json exports 字段

新包应配置 `exports` 字段以支持按需导入：

```json
{
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./<subpath>": {
      "import": "./dist/<subpath>.js",
      "types": "./dist/<subpath>.d.ts"
    }
  }
}
```

添加新导出后，需要执行 `pnpm build` 重新生成入口文件。

资料来源：[libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)

## 最佳实践

### 1. 版本兼容性

- 使用 `~` 而非 `^` 来锁定 `@langchain/core` 依赖
- 允许补丁版本更新，限制次版本兼容性

```json
"peerDependencies": {
  "@langchain/core": "~0.3.0"
}
```

### 2. ESM 和 CJS 兼容

构建步骤应生成兼容两种模块系统的代码。使用 `tsdown` 进行编译：

```bash
tsdown src/index.ts --dts
```

### 3. 文档编写

每个集成包应包含 README.md，包含：

- 安装说明
- 环境变量配置
- 基本使用示例
- API 参考链接

### 4. 类型安全

- 导出完整的 TypeScript 类型定义
- 使用 Zod 进行运行时验证
- 避免使用 `any` 类型

## 扩展包注册表

| 包类型 | 命名空间 | 示例 |
|-------|---------|------|
| 官方提供商 | `@langchain/` | `@langchain/anthropic`, `@langchain/cohere` |
| 核心功能 | `@langchain/` | `@langchain/textsplitters`, `@langchain/core` |
| 社区包 | `@langchain/community` | 社区维护的集成 |
| MCP 适配器 | `@langchain/mcp-adapters` | MCP 协议支持 |

## 常见问题

**Q: 如何为现有包添加新功能？**

在 `src/` 目录创建新文件，然后在 `src/index.ts` 中导出。修改后运行 `pnpm build` 更新构建产物。

**Q: 如何测试包之间的依赖关系？**

使用 `pnpm why <package>` 检查依赖树，确保没有意外的版本冲突。

**Q: MCP 适配器支持哪些 MCP 服务器？**

理论上支持所有符合 MCP 协议规范的服务器，包括文件操作、数据库访问、API 调用等类型。

---

<a id='page-10'></a>

## 示例代码与最佳实践

### 相关页面

相关主题：[Agent 与 Chains 实现](#page-3), [扩展开发指南](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)
- [libs/langchain/src/agents/middleware/hitl.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/middleware/hitl.ts)
- [libs/langchain/src/agents/utils.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/utils.ts)
- [libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/src/chat_models.ts)
- [libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/chat_models/index.ts)
- [libs/langchain-core/src/language_models/event.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/event.ts)
</details>

# 示例代码与最佳实践

本页面汇集了 LangChain.js 框架的核心示例代码和最佳实践指南，涵盖文本分割、代理中间件、聊天模型集成、事件处理等关键功能模块。通过这些示例，开发者可以快速掌握如何在实际项目中应用 LangChain.js 构建 LLM 驱动的应用程序。

## 核心功能概览

LangChain.js 提供了丰富的功能模块，帮助开发者构建模块化、可组合的 LLM 应用程序。以下表格总结了主要功能模块及其用途：

| 功能模块 | 包名 | 主要用途 |
|---------|------|---------|
| 文本分割 | `@langchain/textsplitters` | 将长文档分割成适合处理的块 |
| 代理中间件 | `langchain/agents` | 为代理添加人机交互、监控等能力 |
| 聊天模型 | `@langchain/anthropic`, `@langchain/openai` | 与各种 LLM 提供商集成 |
| 事件系统 | `@langchain/core` | 处理流式输出和状态更新 |
| 工具系统 | `@langchain/core/tools` | 定义和执行 LLM 工具调用 |

## 文本分割器使用指南

文本分割是 RAG（检索增强生成）流水线中的关键步骤。LangChain.js 提供了多种文本分割器实现，最常用的是 `RecursiveCharacterTextSplitter`。

### HTML 文档分割示例

以下示例展示了如何分割 HTML 文档：

```typescript
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";

const text = `<!DOCTYPE html>
<html>
  <head>
    <title>🦜️🔗 LangChain</title>
    <style>
      body { font-family: Arial, sans-serif; }
      h1 { color: darkblue; }
    </style>
  </head>
  <body>
    <div>
      <h1>🦜️🔗 LangChain</h1>
      <p>⚡ Building applications with LLMs through composability ⚡</p>
    </div>
  </body>
</html>`;

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
});
const output = await splitter.createDocuments([text]);
```

资料来源：[examples/src/langchain-classic/indexes/html_text_splitter.ts:1-28]()

### 分割器配置参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `chunkSize` | number | 每个文本块的最大字符数 |
| `chunkOverlap` | number | 相邻块之间的重叠字符数 |
| `separators` | string[] | 分割符列表，按优先级排序 |

### 开发与测试

`@langchain/textsplitters` 包的开发流程如下：

```bash
# 安装依赖
pnpm install

# 构建包
pnpm build
# 或从仓库根目录
pnpm build --filter @langchain/textsplitters

# 运行测试
pnpm test        # 单元测试
pnpm test:int    # 集成测试
```

资料来源：[libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)

## 代理中间件系统

LangChain.js 的代理系统支持中间件扩展，允许开发者在代理执行过程中插入自定义逻辑。

### 中间件状态解析

代理中间件使用状态模式管理状态架构，支持两种主要类型：

```typescript
function parseMiddlewareState(
  stateSchema: unknown,
  state: Record<string, unknown>
): Record<string, unknown> {
  // 处理 LangGraph StateSchema（具有 fields 属性）
  if (StateSchema.isInstance(stateSchema)) {
    const result: Record<string, unknown> = {};
    for (const key of Object.keys(stateSchema.fields)) {
      if (key in state) {
        result[key] = state[key];
      }
    }
    return result;
  }

  // 使用 interopParse 处理 Zod schemas
  if (isInteropZodSchema(stateSchema)) {
    return interopParse(stateSchema as InteropZodObject, state);
  }

  throw new Error(`Invalid state schema type: ${typeof stateSchema}`);
}
```

资料来源：[libs/langchain/src/agents/utils.ts:1-40]()

### HITL 中断配置

人机交互（HITL）中间件提供了精细的中断控制能力：

```typescript
export interface InterruptOnConfig {
  /**
   * 允许的决策列表
   */
  allowedDecisions?: string[];
  /**
   * 动态可调用描述
   */
  description?: z.union([z.string(), DescriptionFunctionSchema]).optional();
  /**
   * 如果允许编辑，则关联参数的 JSON schema
   */
  argsSchema?: z.record(z.any()).optional();
}
```

资料来源：[libs/langchain/src/agents/middleware/hitl.ts:1-50]()

### 中间件架构流程

```mermaid
graph TD
    A[用户输入] --> B[代理处理器]
    B --> C{检查中间件}
    C -->|存在 HITL| D[显示工具调用信息]
    C -->|其他中间件| E[执行中间件逻辑]
    D --> F[等待用户批准/编辑]
    E --> G[继续执行]
    F --> G
    G --> H[返回结果]
```

### 动态工具描述示例

```typescript
import type {
  AgentBuiltInState,
  Runtime,
  DescriptionFactory,
  ToolCall,
  InterruptOnConfig
} from "langchain";

const formatToolDescription: DescriptionFactory = (
  toolCall: ToolCall,
  state: AgentBuiltInState,
  runtime: Runtime<unknown>
) => {
  return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
};

const config: InterruptOnConfig = {
  allowedDecisions: ["approve", "edit"],
  description: formatToolDescription
};
```

## 聊天模型集成

LangChain.js 提供了统一的接口来集成多种聊天模型提供商。

### Anthropic 模型

`ChatAnthropicMessages` 类扩展了基础聊天模型，支持完整的 Anthropic API 功能：

```typescript
export class ChatAnthropicMessages<
  CallOptions extends ChatAnthropicCallOptions = ChatAnthropicCallOptions,
>
  extends BaseChatModel<CallOptions, AIMessageChunk>
  implements AnthropicInput
{
  static lc_name() {
    return "ChatAnthropic";
  }

  get lc_secrets(): { [key: string]: string } | undefined {
    return {
      anthropicApiKey: "ANTHROPIC_API_KEY",
      apiKey: "ANTHROPIC_API_KEY",
    };
  }
}
```

资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts:1-30]()

### OpenAI 模型

OpenAI 聊天模型同样提供了流式输出和完整响应支持：

```typescript
for await (const chunk of await llm.stream(input)) {
  console.log(chunk);
}
```

输出示例：

```txt
AIMessageChunk {
  "id": "chatcmpl-9u4NWB7yUeHCKdLr6jP3HpaOYHTqs",
  "content": ""
}
AIMessageChunk {
  "content": "J"
}
AIMessageChunk {
  "content": "'adore"
}
```

资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts:1-50]()

### 工具调用与结构化输出

聊天模型支持两种结构化输出方式：

| 方式 | 说明 | 使用场景 |
|------|------|---------|
| `withStructuredOutput()` | 使用函数调用 | 需要严格约束输出格式 |
| JSON Schema Mode | 使用原生 JSON schema | 直接结构化输出 |

```typescript
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async (input) => `Weather in ${input.location}`,
  {
    name: "get_weather",
    description: "Get weather for a location",
    schema: z.object({ location: z.string() }),
    extras: { defer_loading: true },
  }
);
```

## 事件系统

LangChain.js 的事件系统用于追踪和响应语言模型运行时的状态变化。

### 内容块事件

```typescript
/**
 * 内容块增量更新时触发
 */
export interface ContentBlockDeltaEvent {
  event: "content-block-delta";
  /** 正在更新的块的位置索引 */
  index: number;
  /** 增量内容块 */
  delta: ContentBlockDelta;
}

/**
 * 内容块完成时触发
 */
export interface ContentBlockFinishEvent {
  event: "content-block-finish";
  /** 完成的块的位置索引 */
  index: number;
  /** 最终内容块 */
  content: ContentBlock;
}
```

资料来源：[libs/langchain-core/src/language_models/event.ts:1-30]()

### 使用量事件

```typescript
/**
 * 提供商报告使用量更新时触发
 * 每个事件携带运行快照（非增量）
 */
export interface UsageUpdateEvent {
  event: "usage";
  /** 当前使用量快照 */
  usage: Partial<UsageMetadata>;
}
```

### 提供商事件

```typescript
/**
 * 用于原生提供商事件的透传
 */
export interface ProviderEvent {
  event: "provider";
  /** 提供商标识符 */
  provider: string;
  /** 来自提供商 SDK 的原始事件类型名 */
  name: string;
  /** 来自提供商 SDK 的原始事件载荷 */
  payload: unknown;
}
```

### 事件处理流程

```mermaid
graph LR
    A[流式调用] --> B[接收 AIMessageChunk]
    B --> C{检查事件类型}
    C -->|content-block-delta| D[更新文本内容]
    C -->|content-block-finish| E[标记块完成]
    C -->|usage| F[更新 token 统计]
    C -->|provider| G[透传原始事件]
    D --> H[累积完整响应]
    E --> H
    F --> H
    G --> H
```

### 聚合流式块

```typescript
import { AIMessageChunk } from '@langchain/core/messages';
import { concat } from '@langchain/core/utils';

let fullForMetadata: AIMessageChunk | undefined;
for await (const chunk of await llm.stream(input)) {
  fullForMetadata = fullForMetadata
    ? concat(fullForMetadata, chunk)
    : chunk;
}
console.log(fullForMetadata?.usage_metadata);
// 输出: { input_tokens: 25, output_tokens: 20, total_tokens: 45 }
```

## 包依赖管理最佳实践

当在项目中使用多个 LangChain 包时，建议统一 `@langchain/core` 版本以避免兼容性问题：

```json
{
  "name": "your-project",
  "version": "0.0.0",
  "dependencies": {
    "@langchain/anthropic": "^0.3.0",
    "@langchain/core": "^0.3.0"
  },
  "resolutions": {
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  },
  "pnpm": {
    "overrides": {
      "@langchain/core": "^0.3.0"
    }
  }
}
```

资料来源：[libs/create-langchain-integration/template/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/README.md)

## 迁移与弃用处理

LangChain.js 在演进过程中会迁移某些功能，开发者应注意弃用警告：

```typescript
if (
  getEnvironmentVariable("LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS") !== "true"
) {
  console.warn(warningText);
}
```

通过设置环境变量 `LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS=true` 可以抑制迁移警告。

资料来源：[libs/langchain-classic/src/util/entrypoint_deprecation.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/util/entrypoint_deprecation.ts)

## 常见模式总结

| 模式 | 描述 | 适用场景 |
|------|------|---------|
| 链式调用 | 使用 `Runnable` 接口组合多个组件 | 数据处理流水线 |
| 工具调用 | LLM 调用外部函数 | 需要获取外部数据 |
| 流式处理 | 实时获取 LLM 输出 | 对话式应用 |
| 中间件拦截 | 在代理执行中插入逻辑 | 监控、HITL |
| 状态管理 | 使用 Zod 或 StateSchema | 结构化代理状态 |

这些示例代码和最佳实践为开发者提供了构建生产级 LLM 应用的坚实基础。建议从简单的示例开始，逐步探索更高级的功能。

---

---

## Doramagic 踩坑日志

项目：langchain-ai/langchainjs

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：[Feature request] React Native support。

## 1. 配置坑 · 来源证据：[Feature request] React Native support

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature request] React Native support
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_39933028ef894033b30ff784e81f185f | https://github.com/langchain-ai/langchainjs/issues/4239 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：@langchain/core@1.1.46

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@langchain/core@1.1.46
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_36a7a58d5cd84bda8dde7918402a6f8a | https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 3. 配置坑 · 来源证据：Must pass in at least 1 record to upsert.

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Must pass in at least 1 record to upsert.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_26c3acaad9e14ed3953206f25870c0b0 | https://github.com/langchain-ai/langchainjs/issues/10890 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | last_activity_observed missing

## 6. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium

## 8. 安全/权限坑 · 来源证据：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4d2a6bed33284a3cbd2f3319321d9e4c | https://github.com/langchain-ai/langchainjs/issues/10894 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | release_recency=unknown

<!-- canonical_name: langchain-ai/langchainjs; human_manual_source: deepwiki_human_wiki -->