仓库概览与 Monorepo 结构

项目定位与目标

langgraphjs 是 LangChain 官方维护的 JavaScript/TypeScript 实现，用于构建有状态、多角色（multi-actor）的大语言模型应用。仓库自述文件强调，该库为开发者提供基于图（graph）的编排原语，以便在生产环境中可靠地协调 LLM 调用、工具调用与人工介入。资料来源：README.md:1-30

设计上，langgraphjs 借鉴了 Google 的 Pregel 与 Apache Beam 的执行模型，并参考 NetworkX 的图 API 风格。公共 API 允许仅使用核心 LangGraph 库，不强制依赖 LangChain 本身。资料来源：README.md:60-72

Monorepo 拓扑与工作区结构

仓库根目录采用 pnpm 工作区 + Turborepo 的多包管理模式。libs/ 目录下按职责拆分为多个独立可发布的 npm 包，每个包都自带 package.json、README.md、src/ 与 dist/，并通过 peerDependencies 与 workspace:* 协议相互引用。资料来源：libs/langgraph-core/package.json:1-40 libs/langgraph/package.json:1-40

下表总结了主要子包及其职责：

资料来源：libs/langgraph-core/package.json:1-40 libs/langgraph/package.json:1-20 libs/checkpoint/package.json:1-30 libs/create-langgraph/package.json:1-20 libs/langgraph-cua/package.json:1-40

包之间的依赖关系

graph TD
  A["@langchain/langgraph (libs/langgraph-core)"] --> B["@langchain/langgraph-checkpoint (libs/checkpoint)"]
  C["langgraph (libs/langgraph)"] --> A
  D["@langchain/langgraph-cua"] --> C
  E["create-langgraph CLI"] -.scaffolds.-> C
  F["@langchain/vue / @langchain/angular SDK"] --> G["@langchain/langgraph-sdk"]
  G -.remote runs.-> A

核心关系链：langgraph 公开包仅依赖 @langchain/langgraph，而 @langchain/langgraph 又依赖 @langchain/langgraph-checkpoint。检查点包定义了 BaseStore、PutOperation 等基础接口，供不同后端实现遵循。资料来源：libs/langgraph/package.json:30-44 libs/langgraph-core/package.json:30-44 libs/checkpoint/src/store/base.ts:1-50

框架 SDK（Vue/Angular）通过 useStream 等 hook 暴露流式响应、工具调用解析、中断（interrupts）以及运行生命周期状态（如 isLoading、interrupt），它们与 LangGraph Platform 的远程运行配合使用。资料来源：libs/sdk-angular/src/use-stream.ts:1-30 libs/sdk-vue/README.md:1-20

示例与脚手架

examples/ 目录集中放置教程与端到端样例，每个子目录均为独立的 pnpm 包，共享同一份依赖声明模板（@langchain/openai、@langchain/anthropic、@langchain/tavily、zod 等）。常见示例包括：

• examples/quickstart —— 最简入门
• examples/how-tos —— 分主题的用法集合
• examples/rag、examples/reflection、examples/rewoo、examples/plan-and-execute —— 进阶 Agent 范式

资料来源：examples/quickstart/package.json:1-20 examples/how-tos/package.json:1-20

对于新项目，create-langgraph CLI 既能下载模板项目，又能通过 npx create-langgraph config 扫描现有仓库，自动识别 createAgent()、new StateGraph(...).compile()、workflow.compile() 三类导出模式，并生成 langgraph.json。仅已导出的 agent 会被纳入配置，未导出者会以警告形式列出。资料来源：libs/create-langgraph/README.md:1-50

构建、运行时与版本约束

所有库均声明 "type": "module"，主入口同时提供 ESM 与 CJS 两种解析路径（通过 exports 字段的 import / require 子句区分）。engines.node 约束为 >=18（核心库为 >=20），保证 async_hooks 等现代 Node API 可用。资料来源：libs/langgraph-core/package.json:5-44 libs/checkpoint/package.json:5-30

构建管线使用共享脚本 pnpm turbo build:internal --filter=<pkg>，内部调用 @langchain/build 编译；测试使用 vitest，并区分 test、test:watch、test:int、test:browser 等模式。这种统一抽象让核心库、SDK、CLI 三类产物能在同一仓库内独立演进。资料来源：libs/langgraph-core/package.json:18-30 libs/langgraph-cua/package.json:12-30

社区关注点与已知差异

仓库的 issue 列表反映出用户在不同运行环境下遇到的痛点：例如 async_hooks 在浏览器侧的兼容问题（#1699）、LangGraph Studio 对类内构建的 graph 的支持差异（#1722）、以及 useStream 通过 Next.js 代理时的状态更新问题（#1295）。这些上下文也解释了 SDK 包持续维护 useStream API 与传输类的原因。资料来源：libs/sdk-angular/src/use-stream.ts:1-30 libs/sdk-vue/README.md:1-20

See Also

• LangGraph 核心概念与 API：libs/langgraph-core/README.md
• 检查点与 Store 接口：libs/checkpoint/src/store/base.ts
• 项目脚手架 CLI：libs/create-langgraph/README.md
• Vue SDK 使用指南：libs/sdk-vue/README.md

Core Graph Engine: StateGraph、Channels 与 Pregel

概述与定位

LangGraph.js 的核心图引擎是构建有状态、多角色 LLM 应用的运行时基础。该项目在多个 README 中明确指出：LangGraph 受到 Pregel 与 Apache Beam 的启发，公共接口则借鉴自 NetworkX。资料来源：README.md

仓库采用 monorepo 结构，将图引擎拆分为两个核心 npm 包：

资料来源：libs/langgraph/package.json、libs/langgraph-core/package.json、libs/checkpoint/package.json

langgraph-core 通过多入口字段暴露子模块，例如 ./zod/schema，表明核心引擎自带 Zod 集成用于状态模式校验。资料来源：libs/langgraph-core/package.json

StateGraph：状态模式的声明式定义

StateGraph 是用户构建图时最常使用的入口。create-langgraph 的文档描述了三种被自动检测的声明模式：

// 使用 createAgent
export const agent = createAgent({ model, tools });

// 使用 StateGraph
export const graph = new StateGraph(annotation).compile();

// 使用 workflow builder
export const app = workflow.compile();

资料来源：libs/create-langgraph/README.md

其关键设计要点为：

• Annotation 驱动的状态：通过 StateGraph(annotation) 传入状态注解，自动派生出 channel 与 reducer 映射。
• 节点函数：节点接收当前状态并返回部分更新，由核心引擎合并。
• 边与条件路由：支持固定边与条件函数，从而实现循环、分支与人机协同（human-in-the-loop）。
• .compile()：将声明式图编译为可执行的 Pregel 运行时实例。

社区中较常见的痛点是 LangGraph Studio 不会显示在类（class）内部构建的 Chat 标签（issue #1722，共 26 条评论），该问题正是与 StateGraph 实例化与导出方式相关，需要确保编译后的图在模块顶层 export。资料来源：libs/create-langgraph/README.md

Channels：状态的读写抽象

Channel 是核心引擎中管理单个状态字段的基本单元，提供了隔离的写入/读取语义与更新合并规则。

• Channel 是 StateGraph 在编译阶段根据 annotation 自动生成的底层数据结构，每个被声明的状态字段对应一个 channel 实例。
• 由于 LangGraph 受到 Pregel 与 Apache Beam 的启发，Channel 的更新语义（update/consume）与 Beam 的 PCollection 思想类似——只有显式标记已消费的值才会被下一轮 superstep 看到。
• Channel 还支持 reducer（如 messages 字段默认追加），通过 messages_reducer 实现对话历史的累积。

flowchart LR
    A[State Annotation] --> B[StateGraph 编译]
    B --> C[Channels 映射]
    C --> D[Pregel Superstep]
    D --> E{有下一节点?}
    E -- 是 --> F[节点函数读取]
    F --> G[写入 Channel]
    G --> D
    E -- 否 --> H[Checkpoint 持久化]

Pregel 风格的执行模型

核心引擎采用 Pregel 风格的同步超级步（superstep）模型：

1. 每个 superstep 中，所有被调度的节点以当前快照状态作为输入并发执行。
2. 节点返回的部分更新被写入到对应的 channel，不会立即覆盖全局状态。
3. 当本轮 superstep 中所有节点执行完毕后，引擎统一将 channel 的写入合并到状态中，并依据条件边决定下一轮要激活的节点。
4. 若存在 checkpoint saver，则在每一步 superstep 之后持久化。

资料来源：libs/checkpoint/src/store/base.ts、libs/checkpoint/package.json

Pregel 模型直接带来三项关键能力：

• 流式输出（Streaming）：每个 superstep 都可对外发出增量事件，从而支持 token 级、节点级、状态级的多种 stream 模式。
• 人机协同：执行可暂停在某个 superstep，等待外部输入再恢复，这正是 checkpoint 的核心价值。
• 时间旅行 / 重放：依赖持久化的 checkpoint 可回放到任意历史 superstep。

社区中 useStream Hook 在代理后无法更新消息（issue #1295）即与 superstep 流事件通过 SSE 协议跨代理透传有关——开发者需要保证代理正确转发 LangGraph 的流式事件格式。

Checkpoint 与存储抽象

@langchain/langgraph-checkpoint 包提供了 checkpoint saver 的基础接口，对外暴露统一的存储/读取 API。资料来源：libs/checkpoint/src/store/base.ts

在基础 store 接口中定义了关键操作，例如 PutOperation：

• namespace: string[] —— 层级化路径，作为类文件夹结构组织条目。
• key: string —— 命名空间内的唯一标识。
• value: Record<string, any> | null —— JSON 可序列化的载荷；为 null 时表示删除。
• 索引控制参数 —— 控制字段是否被索引以支持搜索。

query 参数允许按字符串进行最近邻式语义检索，例如 query: "machine learning papers from 2023"。资料来源：libs/checkpoint/src/store/base.ts

Checkpoint 库同时被上层多智能体库使用，例如：

• @langchain/langgraph-swarm（群聊式多智能体）
• @langchain/langgraph-supervisor（层级监督者多智能体）
• @langchain/langgraph-cua（Computer Use Agent）

它们都依赖核心引擎的流式、记忆与人机协同能力。资料来源：libs/langgraph-swarm/README.md、libs/langgraph-supervisor/README.md、libs/langgraph-cua/README.md

常见失败模式与注意事项

参见

• Streaming 与事件流协议
• Checkpoint 与记忆
• 人机协同（Human-in-the-loop）
• @langchain/langgraph-sdk 客户端
• Pregel 论文

客户端 SDK、流式协议与框架 Hook

概述与定位

LangGraph.js 的客户端 SDK 与流式协议层为前端框架（React、Vue、Svelte、Angular 等）提供了一套统一的接入方式，让浏览器或 Node.js 端应用能够与运行中的 LangGraph 图（Graph）进行实时、低延迟的双向通信。整个客户端栈由 @langchain/langgraph-sdk（核心传输与子客户端）、@langchain/vue、@langchain/svelte 与 Angular 包中的 useStream 共同组成。

根据 libs/sdk/README.md 的描述，SDK 的核心职责是「创建与管理 assistants、threads、runs、cron schedules 与 KV store，并实时流式推送图执行过程」。默认连接地址是 http://localhost:2024，对应 langgraph dev 本地开发服务器。

资料来源：libs/sdk/README.md

核心 SDK 与流式协议

`ThreadStream` 流式通道

client.threads.stream(...) 返回一个 ThreadStream 对象，提供多种类型化、惰性（lazy）投影，让前端无需关心底层 SSE / WebSocket 细节即可消费数据。常用字段包括：

• thread.messages / thread.toolCalls：组装后的聊天输出与工具调用；
• thread.values / thread.output：图状态与最终结果；
• thread.interrupts / thread.interrupted：人机协同（human-in-the-loop）中断；
• thread.subgraphs / thread.subagents：嵌套图 / Deep Agent 的子执行轨迹；
• thread.extensions.<name>：类型化自定义服务器投影；
• thread.audio / thread.images / thread.video / thread.files：多媒体通道。

资料来源：libs/sdk/README.md

快速上手示例

import { Client } from "@langchain/langgraph-sdk";

const client = new Client({ apiUrl: "http://localhost:2024" });

// 推荐的线程中心化流式入口
const thread = client.threads.stream({ assistantId: "my-agent" });

await thread.run.start({
  input: { messages: [{ role: "user", content: "hello" }] },
});

for await (const message of thread.messages) {
  for await (const token of message.text) {
    process.stdout.write(token);
  }
}

console.log(await thread.output);
await thread.close();

资料来源：libs/sdk/README.md

社区关注点：Issue #504 多次提及希望 LangGraph 兼容 Vercel 的 Data Stream Protocol，以便在已使用 ai SDK 的 React 应用中无缝接入。ThreadStream 的 messages / toolCalls 等强类型投影正是为这类场景设计，可经轻量适配层映射到 Vercel 的数据流格式。

框架 Hook 与响应式集成

Vue 集成

@langchain/vue 通过 useStream 将 LangGraph 代理绑定到 Vue 组件，响应式字段以 getter 形式暴露在稳定的 stream 句柄上。组件模板中可直接访问 stream.messages、stream.isLoading 等，配合 stream.submit(...) 即可发送消息。

资料来源：libs/sdk-vue/README.md

Svelte 5 集成

@langchain/svelte 同样基于 Svelte 5 runes，通过 useStream 返回响应式句柄，模板与 $derived 表达式会自动追踪更新。重要提示：必须通过 stream.xxx 访问字段，因为解构会冻结值。

<script lang="ts">
  import { useStream } from "@langchain/svelte";

  const stream = useStream({
    assistantId: "agent",
    apiUrl: "http://localhost:2024",
  });
</script>

{#each stream.messages as msg (msg.id)}
  <div>{msg.content}</div>
{/each}

<button
  disabled={stream.isLoading}
  onclick={() =>
    stream.submit({ messages: [{ type: "human", content: "Hello!" }] })}
>
  Send
</button>

资料来源：libs/sdk-svelte/README.md

Angular 集成

Angular 包在 libs/sdk-angular/src/use-stream.ts 中导出 useStream，利用 Angular Signals 提供响应式能力。关键字段包括：

• toolCalls: Signal<InferToolCalls<T>[]>：从 tools 通道组装得到的完整 AssembledToolCall（含 name、args、id），可用于审批 UI 或无头工具处理器；
• interrupts: Signal<Interrupt<InterruptType>[]>：活动线程上根命名空间未处理的协议中断，初始由 thread.getState() 水合，新运行开始或调用 respond 时会被乐观清空；
• interrupt: Signal<Interrupt<InterruptType> | undefined>：interrupts[0] 的便捷别名；
• isLoading: Signal<boolean>：由根命名空间的 running → 终端 生命周期事件驱动，可用于禁用提交按钮与展示加载状态。

资料来源：libs/sdk-angular/src/use-stream.ts

数据流与持久化抽象

flowchart LR
  UI[前端框架<br/>React/Vue/Svelte/Angular] -->|useStream| Hook[框架 Hook 句柄]
  Hook -->|HTTP/SSE/WS| SDK[langgraph-sdk Client]
  SDK -->|ThreadStream| Server[LangGraph API Server]
  Server -->|事件流| SDK
  SDK -->|messages/values/interrupts| Hook
  Hook -->|Signals/getters| UI
  Server <-->|Checkpoint| Store[(MemorySaver / Postgres)]
  Server <-->|KV / 语义搜索| KV[Store 子客户端]

Checkpoint 与 Store

后端通过 MemorySaver 等 Checkpoint 机制持久化图状态；client.store 则提供带命名空间与可选索引字段的 KV / 语义搜索能力。其基础类型定义见 libs/checkpoint/src/store/base.ts：

• SearchOperation.query：用于语义搜索的查询字符串；
• PutOperation.namespace：层级化路径，充当文件夹结构；
• PutOperation.key：在命名空间内的唯一标识；
• PutOperation.value：JSON 可序列化对象（设为 null 即删除）。

资料来源：libs/checkpoint/src/store/base.ts

生态扩展

• @langchain/langgraph-swarm：在 LangGraph 之上构建多智能体群（Swarm），提供 createSwarm、createHandoffTool 与开箱即用的流式、记忆、人机协同支持。资料来源：libs/langgraph-swarm/README.md
• @langchain/langgraph-cua：基于 LangGraph.js 的 Computer Use Agent 实现，提供屏幕感知与操作能力。资料来源：libs/langgraph-cua/README.md
• @langchain/langgraph-core 与 @langchain/langgraph：核心图运行时、检查点与预构建组件。资料来源：libs/langgraph-core/README.md 与 libs/langgraph/README.md
• create-langgraph：脚手架 CLI，提供 create-langgraph config [path] 子命令，自动扫描项目中的 createAgent、new StateGraph(...).compile()、workflow.compile() 等模式生成 langgraph.json。资料来源：libs/create-langgraph/README.md

常见失败模式与社区反馈

• 代理路径下的流式更新丢失（Issue #1295）：当 useStream 通过 Next.js API 代理使用时，可能无法填充 messages 或 values，但 SSE 事件本身已被正确接收。建议在代理层保持 text/event-stream 头与分块传输，并避免缓冲整段响应。
• 浏览器中 async_hooks 不可用（Issue #1699）：@langchain/core 升级到 ^1.0.0-alpha.x 后部分 API 在浏览器中受限，需确认 SDK 入口使用支持浏览器的 web 子导出路径。
• 类包裹的图在 Studio 中不显示 Chat 标签（Issue #1722）：若图实例由类封装且未导出，create-langgraph config 扫描器会将其列为 warning。在 Studio 中需确保图是模块级 export 产物。
• Data Stream 协议互通（Issue #504）：若需对接 Vercel AI SDK，可通过 ThreadStream 的标准化消息/工具调用投影进行转译，避免直接解析裸 SSE。

See Also

• 核心运行时与图 API：libs/langgraph/README.md
• Checkpoint 与 Store 抽象：libs/checkpoint/src/store/base.ts
• 多智能体群（Swarm）模式：libs/langgraph-swarm/README.md
• Computer Use Agent 模板：libs/langgraph-cua/README.md
• 项目脚手架与配置扫描：libs/create-langgraph/README.md

持久化抽象层：BaseCheckpointSaver

LangGraph.js 的持久化能力由 @langchain/langgraph-checkpoint 包提供（name、version 字段见 package.json）资料来源：[libs/checkpoint/package.json]。该包对外暴露 BaseCheckpointSaver<V extends string | number> 抽象类，作为所有具体检查点保存器（Postgres、SQLite、内存等）必须实现的契约 资料来源：[libs/checkpoint/src/base.ts]。

抽象类内置了一个可被构造函数覆盖的 serde 字段，默认使用 JsonPlusSerializer，用于对通道写入值进行序列化 资料来源：[libs/checkpoint/src/base.ts]。核心方法包括：getTuple(config) 按 RunnableConfig 解析线程/命名空间并返回 CheckpointTuple（包含 config、checkpoint、metadata?、parentConfig?、pendingWrites?）；get(config) 是其便捷封装；list(config, options?) 返回 AsyncGenerator<CheckpointTuple>，支持 limit、before、filter 三种列表选项；put(config, checkpoint, metadata, newVersions) 写入检查点并返回新配置；putWrites(config, writes, taskId) 存储与某检查点关联的中间写入；deleteThread(threadId) 删除线程级别的全部检查点与写入 资料来源：[libs/checkpoint/src/base.ts]。

检查点元数据与存储模型

每个检查点都带有 CheckpointMetadata 元数据，描述其产生方式、步数与父节点关系 资料来源：[libs/checkpoint/src/types.ts]。source 字段限定为 "input" | "loop" | "update" | "fork" 四种枚举值，分别表示来自 invoke/stream/batch 的输入、内部 pregel 循环、手工状态更新、以及从另一检查点复制而来的分叉 资料来源：[libs/checkpoint/src/types.ts]。PendingWrite<Channel> 与 CheckpointPendingWrite<TaskId> 分别定义为 [Channel, PendingWriteValue] 与 [TaskId, ...PendingWrite<string>] 的元组结构，配合 putWrites 实现细粒度的任务级写入 资料来源：[libs/checkpoint/src/types.ts]。

在长期记忆 Store 子系统中，PutOperation 接口定义了 namespace: string[]、key: string、value: Record<string, any> | null 三个字段——namespace 提供层级路径（类似文件夹）用于组织跨会话记忆，当 value 为 null 时即表示删除该条目 资料来源：[libs/checkpoint/src/store/base.ts]。

数据库实现：Postgres 检查点保存器

PostgresSaver 是官方基于 node-postgres 实现的检查点保存器 资料来源：[libs/checkpoint-postgres/src/index.ts]。其 PostgresSaverOptions 仅含 schema 字段（默认 "public"），可通过 fromConnString 静态工厂快速创建 资料来源：[libs/checkpoint-postgres/src/index.ts]。

底层数据库模式由 getSQLStatements 与 getMigrations 共同维护。migrations.ts 显式创建了 checkpoint_writes 表（包含 thread_id、checkpoint_ns、checkpoint_id、task_id、idx、channel、type、blob 列），并对 checkpoint_blobs.blob 列放宽了 NOT NULL 约束以支持 null 删除语义 资料来源：[libs/checkpoint-postgres/src/migrations.ts]。这种"每条写入一行、以 (thread_id, checkpoint_ns, checkpoint_id, task_id, idx) 为主键"的设计，使 putWrites 能按主键高效地增量持久化通道级状态。

检查点验证、CLI 工具与部署

@langchain/langgraph-checkpoint-validation（v1.1.0，engines 限定 Node ^20.0.0 || ^22.0.0 || >=24.0.0）是官方提供的检查点实现校验工具 资料来源：[libs/checkpoint-validation/package.json] 资料来源：[libs/checkpoint-validation/README.md]。它既可作为 CLI 在终端执行，也可作为库接入测试套件；典型流程为：实现自定义检查点 → 编写默认导出 CheckpointerTestInitializer 的文件 → 运行工具验证 → 根据失败用例迭代 资料来源：[libs/checkpoint-validation/README.md]。

部署侧则由 create-langgraph CLI 提供脚手架与配置生成能力。其 create-langgraph config [path] 子命令会扫描项目源码，自动识别 createAgent()、new StateGraph(...).compile()、workflow.compile()、builder.compile() 等模式（同时支持 ESM export 与 CommonJS module.exports / exports.x），并仅将已导出的代理写入生成的 langgraph.json，未导出的会以警告形式提示用户补加 export 资料来源：[libs/create-langgraph/README.md]。

对顶层框架而言，LangGraph 官方文档将"持久化执行（durable execution）"与"生产级部署"列为核心卖点——前者依赖上述检查点机制在故障后从中断点恢复，后者通过 LangSmith Deployments 提供托管运行环境 资料来源：[libs/langgraph/README.md] 资料来源：[libs/langgraph-core/README.md]。

常见失效模式与社区关注点

社区侧多个高互动议题都集中在持久化与 SDK 的边界场景：#1722 报告 LangGraph Studio 的 Chat 标签在图构建于 class 内部时无法显示；#1699 指出 @langchain/core 1.0.0-alpha 在浏览器中与 async_hooks 冲突，影响浏览器端 Vue/React SDK 的流式行为 资料来源：[libs/sdk-vue/README.md](https://github.com/langchain-ai/langgraphjs/blob/e6082e05755797a92e9d24149496923e044319ee/libs/sdk-vue/README.md)。在引入自定义 BaseCheckpointSaver 实现或使用浏览器端 SDK 之前，应先通过 langgraph-checkpoint-validation 工具做一轮合规性测试，并优先选用官方 PostgresSaver 作为生产基线。

See Also

• LangGraph API 参考
• Durable Execution 概念文档
• LangSmith Deployments 部署指南
• create-langgraph CLI 目录
• langgraph-checkpoint-validation 工具

Pitfall Log / 踩坑日志

项目：langchain-ai/langgraphjs

摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 langgraphjs 与安装入口 @langchain/langgraph 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npm install @langchain/langgraph
• 证据：identity.distribution | https://www.npmjs.com/package/@langchain/langgraph | repo=langgraphjs; install=@langchain/langgraph

2. 安装坑 · 来源证据：`streamEvents` v3 produces `AIMessage` with empty `tool_calls` when model emits text alongside a tool call, breaking `c…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：streamEvents v3 produces AIMessage with empty tool_calls when model emits text alongside a tool call, breaking createAgent's ReAct loop
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/2496 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://www.npmjs.com/package/@langchain/langgraph | README/documentation is current enough for a first validation pass.

4. 运行坑 · 来源证据：MongoDBSaver missing indexes causes full collection scans

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：MongoDBSaver missing indexes causes full collection scans
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/2551 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://www.npmjs.com/package/@langchain/langgraph | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://www.npmjs.com/package/@langchain/langgraph | no_demo; severity=medium

8. 安全/权限坑 · 来源证据：Cross-thread checkpoint data contamination when using singleton agent with concurrent invocations

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Cross-thread checkpoint data contamination when using singleton agent with concurrent invocations
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/2040 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

9. 安全/权限坑 · 来源证据：What format data does `AIMessage` has to have to give `contentBlock` with `{type:"reasoning"}`

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：What format data does AIMessage has to have to give contentBlock with {type:"reasoning"}
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/1836 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@langchain/langgraph | issue_or_pr_quality=unknown

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

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