langchainjs 项目说明书

Doramagic 项目包 · 项目说明书

langchainjs 项目

智能体工程平台

Repository Overview and Monorepo Architecture

langchainjs 是 LangChain 在 JavaScript/TypeScript 生态中的官方实现，提供用于构建大语言模型（LLM）驱动应用的标准接口、链式调用抽象、智能体（agent）编排能力以及与模型提供商、向量数据库、工具集成的丰富生态。仓库根目录的 README.md 将其定位为「面向生产环境的 LLM 编排框架」，并强调与 LangGraph、Lan...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 核心包

继续阅读本节完整说明和来源证据。

章节 第三方集成包

继续阅读本节完整说明和来源证据。

章节 内部工具

继续阅读本节完整说明和来源证据。

仓库总览

langchainjs 是 LangChain 在 JavaScript/TypeScript 生态中的官方实现，提供用于构建大语言模型（LLM）驱动应用的标准接口、链式调用抽象、智能体（agent）编排能力以及与模型提供商、向量数据库、工具集成的丰富生态。仓库根目录的 README.md 将其定位为「面向生产环境的 LLM 编排框架」，并强调与 LangGraph、LangSmith、Deep Agents 等上层/旁系产品的协同关系（资料来源：README.md）。

在发布版本层面，最新的 langchain 稳定版本为 1.4.2（2025 年末发布），其 Patch 变更中包含 fix(langchain): unwrap tool message outputs in agent streams 等流式行为修正（资料来源：[email protected] release notes）。同一时期，社区重点关注 ChatGoogle 的 token 计数、AWS Bedrock Converse 的空内容校验、Google Gemini 的代码执行块转换等 provider 级问题（资料来源：#11055、#10518、#10567），这些 issue 揭示了 monorepo 中各 provider 包独立演进但共享抽象的现状。

Monorepo 包结构

仓库采用 pnpm workspace + Turbo 的多包管理方案，并按职责将代码切分为三层：libs/langchain*（核心框架与生态）、libs/providers/*（第三方模型/向量库集成）以及 internal/*（仓库级工具）。

核心包

langchain：主入口包，package.json 声明 "version": "1.4.5"、"engines": { "node": ">=20" }，并通过 exports 字段同时暴露 ESM 与 CJS 入口（./dist/index.js / ./dist/index.cjs）（资料来源：libs/langchain/package.json）。
@langchain/core：核心抽象与 schema，版本 1.1.49，与 langsmith、zod、js-tiktoken、mustache、p-queue 等关键依赖绑定，是所有上层 provider 包的 peerDependency（资料来源：libs/langchain-core/package.json）。
@langchain/mcp-adapters：连接 Model Context Protocol 服务器的适配器包，声明对 @modelcontextprotocol/sdk、@langchain/core、@langchain/langgraph 的 peer 依赖，并通过 optionalDependencies 引入 extended-eventsource 以支持 Edge 场景（资料来源：libs/langchain-mcp-adapters/package.json、libs/langchain-mcp-adapters/README.md）。
@langchain/textsplitters：独立的文本切分实现，版本 1.0.1，仅依赖 js-tiktoken，与 core 解耦（资料来源：libs/langchain-textsplitters/package.json）。

第三方集成包

libs/providers/* 目录集中放置第三方集成包，包名遵循 @langchain/<provider> 命名约定，并各自维护独立的版本号与发布节奏。典型代表包括 @langchain/openai、@langchain/anthropic、@langchain/ibm、@langchain/pinecone 等（资料来源：libs/providers/langchain-openai/package.json、libs/providers/langchain-anthropic/package.json、libs/providers/langchain-ibm/package.json、libs/providers/langchain-pinecone/package.json）。这些 provider 包共享 @langchain/core 作为基础抽象，并独立打包 dist/ 产物对外发布。

内部工具

internal/model-profiles/ 是一个基于 models.dev API 自动生成 TypeScript 模型能力配置文件的 CLI 工具，依赖 TOML 配置，支持 provider 级与 model 级 override，并通过 TypeScript AST 写出类型安全的 ModelProfile 定义（资料来源：internal/model-profiles/README.md）。

graph LR
  A[apps/docs<br/>示例与文档] --> C(@langchain/core)
  B[langchain<br/>主框架] --> C
  C --> D[@langchain/mcp-adapters]
  C --> E[@langchain/textsplitters]
  C --> P1[libs/providers/<br/>langchain-openai]
  C --> P2[libs/providers/<br/>langchain-anthropic]
  C --> P3[libs/providers/<br/>langchain-pinecone]
  C --> Pn[libs/providers/*<br/>其余集成]
  Internal[internal/model-profiles<br/>模型能力生成器] -.生成.-> P1
  Internal -.生成.-> P2

构建与依赖管理

各子包均启用 "type": "module"，构建脚本统一调用 tsdown（build:compile），并通过 turbo build:compile --filter <pkg> 协调跨包增量编译。package.json 的 files 字段（如 ["dist/", "CHANGELOG.md", "README.md", "LICENSE"]）与双格式 exports（require / import）确保发布产物同时兼容 CommonJS 与 ESM 消费方（资料来源：libs/providers/langchain-openai/package.json、libs/providers/langchain-pinecone/package.json）。包级 scripts 还包含 lint:dpdm 循环依赖检查、vitest 单测与 test:int 集成测试，并使用 pnpm lint:eslint / pnpm format 进行静态质量控制。

运行环境与生态

仓库根级 README.md 明确列出 LangChain.js 的支持环境：Node.js 20.x / 22.x / 24.x（ESM 与 CJS）、Cloudflare Workers、Vercel/Next.js（Browser、Serverless、Edge）、Supabase Edge Functions、Browser 以及 Deno。该多端兼容能力正是 monorepo 拆分带来的直接收益——核心抽象在 @langchain/core 中保持平台无关，具体传输层（如 extended-eventsource）在边缘环境下按需加载（资料来源：README.md、libs/langchain-mcp-adapters/package.json）。

围绕主仓库的生态还包括 LangSmith（调试与可观测性）、LangGraph（底层 agent 编排）、Deep Agents（高层规划与子 agent 模式），它们在 README 中被显式列出（资料来源：README.md）。

常见失败模式

从社区 issue 来看，monorepo 模式下几类典型问题需要关注：

Provider 级回归：各 provider 独立发版，使得 ChatOpenAI、ChatGoogle、ChatBedrockConverse 等可能在 token 上报、空内容、流式分块等行为上出现不一致（资料来源：#10518、#11055、#7694）。
TypeScript 深度实例化：嵌套 zod schema 容易触发「Type instantiation is excessively deep」类编译错误（资料来源：#2310）。
Edge 兼容：历史上因 axios 等 Node 专属依赖而需要持续替换；mcp-adapters 通过 optionalDependencies 与 extended-eventsource 缓解该问题（资料来源：#62、libs/langchain-mcp-adapters/package.json）。

Core Abstractions: Runnables, Messages, Tools, and Outputs

LangChain.js 的核心抽象层（位于 @langchain/core）围绕四个相互协作的概念构建：Runnable（可运行单元）、Message（消息）、Tool（工具）和 Output（输出）。这一层为上层 provider 包（OpenAI、Anthropic、xAI、IBM 等）提供了统一的接口，使开发者能够以一致的方式组合、调用、监听和流式传输 LLM 行为...

章节 相关页面

继续阅读本节完整说明和来源证据。

核心抽象：Runnables、Messages、Tools 和 Outputs

概述

LangChain.js 的核心抽象层（位于 @langchain/core）围绕四个相互协作的概念构建：Runnable（可运行单元）、Message（消息）、Tool（工具）和 Output（输出）。这一层为上层 provider 包（OpenAI、Anthropic、xAI、IBM 等）提供了统一的接口，使开发者能够以一致的方式组合、调用、监听和流式传输 LLM 行为。从仓库整体结构看，libs/langchain 负责组合高层 API，provider 包负责与具体模型通信，而 langchain-core 则提供这些可复用的契约资料来源：[README.md](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/README.md)。

flowchart LR
    U[用户输入] --> R[Runnable 链]
    R --> M[Messages]
    M --> LLM[Chat Model]
    LLM --> T[Tools / Tool Calls]
    T --> O[Output / Stream]
    O --> R
    O --> CB[Callbacks / Usage Metadata]

Runnables：统一的执行接口

Runnable 是所有可调用组件（聊天模型、提示模板、检索器、链）的基类，提供一致的 invoke / stream / batch 方法族，并通过 RunnableConfig 传递回调、运行 ID、标签和元数据。RunnableBranch（branch.ts）允许在链内部按条件路由输入到不同分支，而 RunnableSequence / RunnableParallel 则是构建复杂管道的核心。

在 provider 端，ChatOpenAI 与 ChatAnthropic 都实现 Runnable，因此能够直接被 bindTools 链式增强资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-openai/src/chat_models/index.ts)；资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-anthropic/src/chat_models.ts)。这意味着同一个 .invoke() / .stream() 接口既能用于基础问答，也能用于工具调用、Agent 循环等高级场景。社区中反馈的"Type instantiation is excessively deep"问题（issue #2310）正是因为 DynamicStructuredTool 与 Runnable 泛型嵌套过深所致。

Messages 与内容块

消息（Message）是对话轮次的基本单位，分多种类型：HumanMessage、AIMessage、SystemMessage、ToolMessage、FunctionMessage 等，定义见 messages/index.ts。v1 标准引入了结构化的 content 块，使单一消息可同时承载文本、推理、引用、图片等多种模态。

内容块类型	用途	示例来源
`output_text`	模型输出的纯文本	xAI Responses
`refusal`	模型拒绝回答	xAI Responses
`url_citation`	联网搜索得到的 URL 引用	xAI Responses
`file_citation`	文件检索引用	xAI Responses

资料来源：[libs/providers/langchain-xai/src/chat_models/responses-types.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-xai/src/chat_models/responses-types.ts)

block_translators 负责在不同 provider 的原生格式（如 OpenAI 的 content 数组、Anthropic 的 content 块）与 LangChain 标准块之间相互转换，确保跨模型语义一致。社区中 issue #11055 报告的 ChatBedrockConverse 空 content 校验错误，正是块转换边界处的已知陷阱；issue #10567 反映的 Gemini codeExecutionResult 错位问题，也需在转换器层面修复。

Tools：可声明的能力

工具是赋予 LLM 副作用或外部数据访问能力的方式。Tool 抽象在 v1 中扩展为多种形态：

函数工具：通过 Zod schema 描述入参，如 bindTools([GetWeather, GetPopulation]) 资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-anthropic/src/chat_models.ts)。
搜索工具：xAI Responses 中区分 web_search、x_search、file_search、code_interpreter 等资料来源：[libs/providers/langchain-xai/src/chat_models/responses-types.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-xai/src/chat_models/responses-types.ts)。
MCP 工具：OpenAI 的 tools.mcp() 通过 server_url 接入远程 MCP 服务，支持 allowed_tools、require_approval、authorization 等治理参数资料来源：[libs/providers/langchain-openai/src/tools/mcp.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-openai/src/tools/mcp.ts)；与之配套的 @langchain/mcp-adapters 则为 LangChain.js 提供多服务器连接能力。
计算机使用：Computer20250124Options 要求显式传入 displayWidthPx / displayHeightPx，使模型可以执行截图、键鼠操作资料来源：[libs/providers/langchain-anthropic/src/tools/computer.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-anthropic/src/tools/computer.ts)。
工具检索（Tool Search）：Anthropic 的 tools.toolSearchBM25_20251119() 配合 defer_loading 元数据，延迟加载大量工具资料来源：[libs/providers/langchain-anthropic/src/tools/toolSearch.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-anthropic/src/tools/toolSearch.ts)。
代码补丁：tools.applyPatch() 接收 create_file / edit_file 等操作，由宿主执行实际的 diff 合并资料来源：[libs/providers/langchain-openai/src/tools/applyPatch.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-openai/src/tools/applyPatch.ts)。

社区中 issue #11063 提出的 @kakunin/langchain 适配器即在此抽象之上注入 X.509 身份校验与工具级权限策略。

Outputs：消息块与用量元数据

模型返回的 AIMessage / AIMessageChunk 是 Output 的基本载体，承载：

content（可能是字符串或内容块数组）；
tool_calls（结构化工具调用）；
response_metadata（provider 私有字段，如 finish_reason、system_fingerprint）；
usage_metadata（input_tokens / output_tokens / total_tokens）资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/234c8bbb97444357847de5751d81ee9c51a7d33f/libs/providers/langchain-openai/src/chat_models/index.ts)。

流式场景下，每个 AIMessageChunk 可独立携带增量 token；社区中 issue #7694 的"completion_tokens 重复合并"错误、#10518 的 Google Chat 缺失 usage_metadata 问题，以及 #1640 中 handleLLMNewToken 收到空 token 的现象，都集中在流式块与元数据聚合边界，提示使用方应在回调里使用 concat() 辅助器并显式校验 usage_metadata 是否存在资料来源：[libs/providers/langchain-mistralai/CHANGELOG（间接）](https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/mistralai%401.1.0)。[email protected] 的补丁 "unwrap tool message outputs in agent streams" (release) 也属于 Output 层标准化的一部分。

常见失败模式

流式中类型嵌套过深：复杂的工具链 + 泛型 Runnable 容易触发 TypeScript 递归上限；可拆解 zod schema 或显式标注中间变量类型。
空内容或重复内容：Bedrock、xAI Responses 等在多模态或推理场景下可能返回空 content，需在块转换器层做兜底。
用量元数据丢失：部分 provider（尤其在流式路径上）不会自动填充 usage_metadata，需要在批量推理时主动累加 chunk。
工具调用治理缺失：MCP / 工具检索 / 补丁类工具具备副作用（写文件、执行代码），生产部署必须结合审批流与沙箱。

Agent Runtime, Middleware, and createAgent

LangChain.js 的 createAgent 是 langchain 包提供的顶层智能体（agent）构建入口，它把模型（chat model）、工具（tools）、系统提示（system prompt）与运行时行为组合为一个可调用对象。当需要更底层的编排能力时，createAgent 通常与 LangGraph.js 协同使用，而后者提供可控的工作流、长期记忆与人...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与目标

LangChain.js 的 createAgent 是 langchain 包提供的顶层智能体（agent）构建入口，它把模型（chat model）、工具（tools）、系统提示（system prompt）与运行时行为组合为一个可调用对象。当需要更底层的编排能力时，createAgent 通常与 LangGraph.js 协同使用，而后者提供可控的工作流、长期记忆与人机协同循环资料来源：libs/langchain/README.md。在 v1.4.x 版本中，运行时层面修复了智能体流式输出时工具消息解包问题资料来源：[email protected] release notes。

运行时与支持环境

LangChain.js 智能体运行时在多种 JavaScript 环境上得到官方支持，覆盖 Node.js（ESM 与 CommonJS，版本 20.x / 22.x / 24.x）、Cloudflare Workers、Vercel / Next.js（浏览器、Serverless 与 Edge Functions）、Supabase Edge Functions、Browser、Deno 以及 Bun 资料来源：README.md 与 libs/langchain/README.md。对于历史上影响 Edge 部署的 axios 依赖等问题，社区长期跟踪并已完成替换，因此新版本智能体运行时可在 Edge 环境直接使用 createAgent 资料来源：issue #62。

中间件（Middleware）与工具生态

createAgent 支持通过中间件插入横切关注点（cross-cutting concerns），并通过统一的 tools 接口接入多模型提供方内置工具。下表汇总了主要提供方的内置工具能力，这些工具可直接绑定到 createAgent 的 tools 字段：

提供方	内置工具	关键能力	来源文件
Anthropic	`tools.toolSearchBM25_20251119`	自然语言检索已注册工具；需要 `advanced-tool-use-2025-11-20` beta header	toolSearch.ts
Anthropic	`tools.webSearch_20250305`	实时联网搜索，支持 `maxUses`、`allowedDomains`、`userLocation` 等选项	webSearch.ts
Anthropic	`tools.computer_20250124`	截图与键鼠控制，依赖 `displayWidthPx` / `displayHeightPx` 配置	computer.ts
OpenAI	`tools.mcp`	通过 `serverUrl` 远程 MCP 或 `connectorId` 托管连接器，支持 `requireApproval` 与 `allowedTools` 细粒度控制	mcp.ts
xAI	`webSearch` / `xSearch`	网络搜索与 X（Twitter）帖子搜索，支持 allowed/excluded 域名或 handle 列表	web_search.ts / x_search.ts

flowchart LR
  A[createAgent] --> B[Chat Model]
  A --> C[Tools]
  A --> D[System Prompt]
  A --> E[Middleware]
  C --> F[Provider Built-in Tools]
  C --> G[MCP Servers]
  F --> H[Anthropic / OpenAI / xAI]
  G --> I[MultiServerMCPClient]
  E --> J[Summarization / Context Editing / HITL]
  B --> K[Reasoning & Service Tier]

在使用工具调用与函数调用（function calling）场景下，社区反馈 handleLLMNewToken 可能在流式事件中收到空 token，需要在中间件或回调层进行过滤资料来源：issue #1640；此外，completion_tokens 字段在消息块中重复写入时会抛出 "field already exists" 异常，应避免在中间件中重复累加资料来源：issue #7694。

MCP 集成与运行时配置

@langchain/mcp-adapters 提供了 MultiServerMCPClient，它把一个或多个 MCP 服务器（stdio、SSE、HTTP、可流式 HTTP）转换为可被 createAgent 直接使用的工具列表资料来源：libs/langchain-mcp-adapters/README.md。其对等依赖包含 @langchain/core 与 @langchain/langgraph，并通过可选依赖 extended-eventsource 在受限环境中启用 EventSource 兼容的流式传输资料来源：libs/langchain-mcp-adapters/package.json。MultiServerMCPClient 支持的关键配置包括 throwOnLoadError、prefixToolNameWithServerName、useStandardContentBlocks 与 onConnectionError，便于在中间件中按需定制工具命名空间与错误传播策略。

模型能力建模

createAgent 所选用的 chat model 应当具备明确的工具调用与结构化输出能力。internal/model-profiles 工具会自动从 models.dev 拉取模型清单，按 TOML 配置覆盖 provider / model 级别的 toolCalling、structuredOutput、maxInputTokens 等字段，并生成与 @langchain/core 的 ModelProfile 类型对齐的 TypeScript 文件资料来源：internal/model-profiles/README.md。在 OpenAI 提供方中，reasoning.effort 与 service_tier（包含 auto / default / flex）可用于控制推理强度与服务层级资料来源：libs/providers/langchain-openai/src/chat_models/base.ts。

常见故障与社区注意事项

流式工具消息解包：v1.4.2 修复了智能体流中工具消息输出的解包问题资料来源：[email protected] release notes。
类型递归过深：使用 DynamicStructuredTool 与复杂 Zod schema 时 TypeScript 可能触发 "Type instantiation is excessively deep"，建议在中间件层拆分 schema 或使用类型断言资料来源：issue #2310。
MCP 加载失败：若 throwOnLoadError: false 且 onConnectionError: "ignore"，MCP 加载错误将被静默吞掉，调试时建议临时切换为 throw 以暴露问题资料来源：libs/langchain-mcp-adapters/README.md。

另请参阅

LangGraph.js 文档 — 底层智能体编排框架
LangSmith Deployment — 长时运行、有状态工作流的部署平台
Deep Agents (JS) — 基于 LangChain 的高级智能体包

来源：https://github.com/langchain-ai/langchainjs / 项目说明书

Model Providers, Vector Stores, and Integrations

LangChain.js 通过一组独立发布的 provider 包（位于 libs/providers/）与协议适配包（位于 libs/langchain-mcp-adapters/）为上层 langchain 提供模型、工具与向量存储能力。本页梳理这些模块的职责、典型用例以及社区关注的常见问题。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 2.1 主流 provider 包结构

继续阅读本节完整说明和来源证据。

章节 2.2 工具调用与 Responses API

继续阅读本节完整说明和来源证据。

章节 2.3 模型 Profile 自动生成

继续阅读本节完整说明和来源证据。

Model Providers、Vector Stores 与 Integrations

LangChain.js 通过一组独立发布的 provider 包（位于 libs/providers/）与协议适配包（位于 libs/langchain-mcp-adapters/）为上层 langchain 提供模型、工具与向量存储能力。本页梳理这些模块的职责、典型用例以及社区关注的常见问题。

1. 整体架构与分层

LangChain.js 的集成层采用 monorepo + pnpm workspace 形式：核心抽象在 @langchain/core，而具体供应商实现以独立 npm 包发布。README.md:1-30 指出仓库支持 Node.js 20+/22+/24+、Cloudflare Workers、Vercel Edge、Supabase Edge Functions 与 Deno 等运行时，这要求所有 provider 包保持轻量并避免依赖 Node-only API（如早期 axios）。

flowchart LR
  A["langchain (顶层 API)"] --> B["@langchain/core (抽象)"]
  A --> C["providers/* (模型与工具)"]
  A --> D["@langchain/mcp-adapters (MCP 协议)"]
  C --> B
  D --> B
  C -- "streamTools / bindTools" --> E["OpenAI / Anthropic / xAI / Google APIs"]
  D -- "MultiServerMCPClient" --> F["STDIO / HTTP / Docker MCP Servers"]
  C --> G["Vector Stores (Pinecone 等)"]

资料来源：README.md:1-30、libs/langchain/README.md:1-20。

2. 模型供应商（Chat Models）

2.1 主流 provider 包结构

每个 provider 包遵循统一的 package.json 约定：双格式导出（./dist/index.cjs 与 ./dist/index.js）、独立 types 声明路径，以及 engines.node >= 20 约束。libs/providers/langchain-openai/package.json:1-40 与 libs/providers/langchain-anthropic/package.json:1-30 均采用 tsdown 进行 build:compile，并通过 lint:dpdm 检查循环依赖。

2.2 工具调用与 Responses API

ChatOpenAI 支持流式调用与结构化工具定义。libs/providers/langchain-openai/src/chat_models/index.ts:1-30 示例显示 invoke 返回的 AIMessage 会同时填充 response_metadata.tokenUsage 与 usage_metadata（input_tokens/output_tokens/total_tokens）——但社区 issue #10518 报告 Google provider 存在 token usage 未上报的问题（见 issue 10518），需要分别排查。

xAI Responses provider 在 responses-types.ts 中定义了 XAIResponsesReasoning、XAIResponsesSearchSource*、XAIResponsesFunctionTool 等类型，将 X 搜索、Web 搜索、文件检索与 MCP 工具统一映射为 Responses API 结构。

2.3 模型 Profile 自动生成

internal/model-profiles/README.md:1-30 描述了一个基于 models.dev API + TypeScript AST 的工具，它从 TOML 配置生成与 ModelProfile 接口兼容的类型安全文件，并自动应用 provider 级与 model 级覆盖。

资料来源：libs/providers/langchain-openai/src/chat_models/index.ts:1-30、libs/providers/langchain-xai/src/chat_models/responses-types.ts:1-50、internal/model-profiles/README.md:1-30。

3. 工具与协议集成（Tools & Integrations）

3.1 内置工具集

OpenAI 与 Anthropic provider 各自提供 tools 命名空间工厂：

OpenAI mcp()：libs/providers/langchain-openai/src/tools/mcp.ts 通过 McpRemoteServerOptions 或 McpConnectorOptions 把 MCP 服务器声明为 ServerTool，支持 requireApproval 与 allowed_tools。
OpenAI applyPatch()：libs/providers/langchain-openai/src/tools/applyPatch.ts 包装 apply_patch_call，用于代码生成、迁移与机械编辑。
Anthropic 工具集：tools.toolSearchBM25_20251119（需要 anthropic-beta: advanced-tool-use-2025-11-20 头）、tools.computer_20251124（截图+键鼠控制，模型 Sonnet 4.5 / Haiku 4.5 等）、tools.webSearch_20250305（实时检索并自动引用）均以函数式 API 暴露。

3.2 MCP 适配器

libs/langchain-mcp-adapters/package.json 把 @modelcontextprotocol/sdk ^1.29 作为直接依赖，并把 @langchain/core ^1.0、@langchain/langgraph ^1.3.4 列为强制 peer。其 README 介绍 MultiServerMCPClient 支持 STDIO、HTTP/SSE、可选 extended-eventsource，以及 useStandardContentBlocks、throwOnLoadError、prefixToolNameWithServerName 等行为开关。examples/README.md 演示了 LangGraph 简单/复杂配置、Docker 容器化 MCP 服务器等典型用法。

社区同时在跟进第三方适配器，例如 issue 11063 申请将 @kakunin/langchain 加入 Community Integrations Directory，用于 X.509 状态校验与工具级权限治理。

资料来源：libs/providers/langchain-openai/src/tools/mcp.ts:1-20、libs/providers/langchain-anthropic/src/tools/toolSearch.ts:1-30、libs/providers/langchain-anthropic/src/tools/computer.ts:1-20、libs/providers/langchain-anthropic/src/tools/webSearch.ts:1-30、libs/langchain-mcp-adapters/README.md:1-30。

4. 向量存储与数据层

libs/providers/langchain-pinecone/package.json 体现向量存储包的共性：版本化发布（当前 1.0.3）、flat 等最小依赖，并通过 turbo build:compile --filter 触发增量编译。其 test:int 目标使用 vitest --mode int 区分单元测试与集成测试，避免在 CI 中误连真实 Pinecone 集群。

4.1 常见集成注意事项

场景	已知问题	参考
流式调用 OpenAI function	`handleLLMNewToken` 收到空 token 块	issue #1640
Gemini 内容块转换	`codeExecutionResult`/`executableCode` 映射错误	issue #10567
AWS Bedrock Converse	空 content 触发 `ValidationException`	issue #11055
TypeScript 类型递归	`DynamicStructuredTool` + `z.object` 触发了过深实例化	issue #2310
Gemini Flex/Priority tier	尚未透出配置	issue #10655

资料来源：libs/providers/langchain-pinecone/package.json:1-20。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：@langchain/aws - ChatBedrockConverse throws ValidationException due to empty content field

可能增加新用户试用和生产接入成本。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

medium 维护活跃度未知

新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。

medium 存在评分风险

风险会影响是否适合普通用户安装。

Pitfall Log / 踩坑日志

项目：langchain-ai/langchainjs

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：@langchain/aws - ChatBedrockConverse throws ValidationException due to empty content field。

1. 安全/权限坑 · 来源证据：@langchain/aws - ChatBedrockConverse throws ValidationException due to empty content field

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：@langchain/aws - ChatBedrockConverse throws ValidationException due to empty content field
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/langchain-ai/langchainjs/issues/11055 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 能力坑 · 能力判断依赖假设

严重度：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.

3. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium

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

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium

6. 安全/权限坑 · 来源证据：Add @kakunin/langchain to Community Integrations Directory

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add @kakunin/langchain to Community Integrations Directory
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/langchain-ai/langchainjs/issues/11063 | 来源类型 github_issue 暴露的待验证使用条件。

7. 安全/权限坑 · 来源证据：ChatGoogle not reporting input and output token use

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ChatGoogle not reporting input and output token use
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/langchain-ai/langchainjs/issues/10518 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

8. 安全/权限坑 · 来源证据：bug(@langchain/google): `codeExecutionResult` and `executableCode` content chunks are incorrectly transformed for Gemin…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(@langchain/google): codeExecutionResult and executableCode content chunks are incorrectly transformed for Gemini API
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/langchain-ai/langchainjs/issues/10567 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | issue_or_pr_quality=unknown

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

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | release_recency=unknown

来源：Doramagic 发现、验证与编译记录