# LangGraph_js_cn

**Repository Path**: snail_wn/lang-graph_js_cn

## Basic Information

- **Project Name**: LangGraph_js_cn
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 《LangGraph.js 中文入门》

> 面向 **JS / TS 工程师**的 LangGraph 系统化教程 —— 从"链"到"图"，把智能体编排讲透。
> 15 章 · 71 个**真实跑通**的代码示例 · 适配任意兼容 OpenAI 接口的大模型服务商。

---

## 这本书解决什么问题

如果你搜 "LangGraph 教程"，找到的 **95% 是 Python**：官方课程 LangChain Academy 只有 Python 版，中文社区的资料也几乎全是 Jupyter Notebook。

而 LangGraph.js **不是** 社区移植、也不是阉割版 —— 它是官方一等公民：

| 事实 | 证据 |
| --- | --- |
| 官方库持续发版 | `@langchain/langgraph` v1.4.21 |
| 官方文档有完整 JS 分支 | [docs.langchain.com/oss/javascript/langgraph/overview](https://docs.langchain.com/oss/javascript/langgraph/overview) |
| JS 与 Python 文档**逐页对应** | 两边的 26 个页面 slug 完全一致 |
| npm 生态齐全 | `langgraph` / `checkpoint-*` / `supervisor` / `swarm` / `sdk-react` … |
| 生产用户 | Replit、Uber、LinkedIn、GitLab |

**所以缺的不是"库"，是"中文的、写给 JS 工程师看的课"。** 这本书就是来补这个缺口的。

---

## 三句话讲清这本书的特点

1. **每个示例都真能跑**。正文里所有"真实输出"都是从终端复制出来的实际运行结果，不是编造的"预期输出"。并且配了 `npm run verify` 一键全量校验。
2. **禁止省略号**。不出现 `...` 这种敷衍写法 —— 每个示例都是「完整代码 + 运行命令 + 真实输出」三件套，对着抄就能跑通。
3. **只讲 JS/TS**。所有代码用 TypeScript 写，不出现一行 Python；需要提 Python 的地方会明确说明差异。

---

## 目录

| 章节 | 内容 | 关键收获 |
| --- | --- | --- |
| [第 0 章 · 环境准备](./00-course-setup/README.md) | Node、依赖、密钥、验证 | 10 分钟把机器点着 |
| [第 1 章 · 第一个图](./01-first-graph/README.md) | State / Node / Edge、ReAct 智能体 | 理解"智能体就是一张带循环的图" |
| [第 2 章 · 状态与 Reducer](./02-state-and-reducers/README.md) | 状态设计、reducer、私有字段 | 搞懂状态怎么合并、怎么追加 |
| [第 3 章 · 节点、边与控制流](./03-edges-and-control-flow/README.md) | 条件边、并行、循环、Send、Command | 把流程控制权真正握在手里 |
| [第 4 章 · 持久化与记忆](./04-persistence-and-memory/README.md) | Checkpointer、thread_id、长期记忆 | 让智能体"记得住"、能断点续跑 |
| [第 5 章 · 人工介入（HITL）](./05-human-in-the-loop/README.md) | interrupt、Command、审批、时间旅行 | 在关键节点插进人的判断 |
| [第 6 章 · 流式输出](./06-streaming/README.md) | streamMode、token 级流式、自定义进度 | 前端体验：打字机效果与实时进度 |
| [第 7 章 · 多智能体](./07-multi-agent/README.md) | 子图、Supervisor、Swarm | 多个专家如何协作与移交 |
| [第 8 章 · 工程化与部署](./08-production/README.md) | 重试、缓存、错误恢复、HTTP 服务、可观测 | 从 demo 走到能用 |
| [第 9 章 · 编排设计模式](./09-design-patterns/README.md) | 提示链、路由、并行化、编排者-工作者、评估者-优化者 | 把机制拼成模式，知道什么形状配什么场景 |
| [第 10 章 · 应用结构](./10-project-structure/README.md) | 分层项目、图只编译一次、运行时参数、结构复用 | 代码怎么组织才不烂 |
| [第 11 章 · 从 LangChain 迁移](./11-from-langchain/README.md) | LCEL 对照、链当节点用、何时该迁/何时别迁 | 把已有的链升级成图（含迁移映射表） |
| [第 12 章 · 测试与调试](./12-testing-and-debugging/README.md) | 节点单测、假模型、集成测试、报错速查手册 | 敢改代码的底气 |
| [第 13 章 · 函数式 API](./13-functional-api/README.md) | entrypoint、task、并行、与图混用 | 第二套写法：不画图，写代码 |
| [第 14 章 · 前端集成](./14-frontend-integration/README.md) | SSE 流式、事件协议、HTTP 人工介入、React 接入 | 送到真正使用它的人面前 |
| [术语表](./GLOSSARY.md) | 中英对照 + 一句话解释 | 查名字不再懵 |

---

## 快速开始

```bash
# 1. 克隆（两个地址选一个，内容同步）
git clone https://github.com/cleversnail/LangGraph_js_cn.git
cd LangGraph_js_cn

# 或国内（Gitee，通常更快）
# git clone https://gitee.com/snail_wn/lang-graph_js_cn.git
# cd lang-graph_js_cn

# 2. 装依赖（需要 Node >= 20）
npm install

# 3. 配置密钥
cp .env.example .env      # 然后编辑 .env，填入 AI_API_KEY

# 4. 跑通第一个图
npx tsx 01-first-graph/code/01-hello-graph.ts

# 5. （可选）一键验证全书 71 个示例，约 20-30 分钟
npm run verify
```

详细说明见 [第 0 章 · 环境准备](./00-course-setup/README.md)。

---

## 阅读方式

**每章"先跑、再看、最后改"：**

1. **先跑** —— 照着正文的运行命令把示例跑一遍，看真实输出
2. **再看** —— 回头读讲解，把"为什么这么写"对上
3. **最后改** —— 改点东西再跑一次。能改坏的代码，才是你学过的代码

运行命令一律在**项目根目录**执行：

```bash
npx tsx <章节目录>/code/<示例文件>.ts
```

---

## 技术栈

| 项目 | 版本 | 说明 |
| --- | --- | --- |
| Node.js | >= 20 | 本书在 v24.18.0 验证 |
| TypeScript | 5.9 | 全书 TS，ESM 模块 |
| `@langchain/langgraph` | ^1.0 | 本书主角 |
| `@langchain/core` | ^1.0 | 消息、工具、模型抽象 |
| `@langchain/openai` | ^1.0 | 兼容 OpenAI 协议的模型接入 |
| `zod` | ^3.25 | 工具参数与结构化输出 |
| 模型服务 | 任意 | 默认 DeepSeek，换服务商只改 `.env` |

---

## 电子书站点

本仓库同时是一本 VitePress 电子书：

```bash
npm run docs:dev       # 本地预览（热更新）
npm run docs:build     # 构建静态站点
npm run docs:preview   # 预览构建产物
```

在线地址：[https://cleversnail.github.io/LangGraph_js_cn/](https://cleversnail.github.io/LangGraph_js_cn/)

---

## 仓库

| 平台 | 地址 |
| --- | --- |
| GitHub | https://github.com/cleversnail/LangGraph_js_cn |
| Gitee（国内镜像） | https://gitee.com/snail_wn/lang-graph_js_cn |
| 在线站点 | https://cleversnail.github.io/LangGraph_js_cn/ |

两个仓库内容保持一致：本项目配成了一条 `git push origin main` 同时推两边（详见 `DEPLOY.md`）。站点部署在 GitHub Pages。

---

## 参考与致谢

本书基于 **LangGraph.js 官方文档与示例**（[langchain-ai/langgraphjs](https://github.com/langchain-ai/langgraphjs)，MIT License）整理、翻译并重排为中文学习路径，补充了大量 JS 工程师视角的讲解、踩坑记录与工程化实践。

Issue / PR 都欢迎。