LangChain 与 LangGraph 项目实战:从对话生成到可编辑工作流

假设我们要做一个文章生成工具,用户输入这样的需求:

输入一个技术主题,先生成提纲,再根据提纲写正文。提纲和正文的提示要求都可以修改,同一套流程下次还能换一个主题运行。

一次模型调用也能直接返回整篇文章。但如果用户想单独检查提纲、调整正文的输入,或者看清失败发生在哪一步,就需要把过程显式表达出来。工作流编辑器的价值,正是让这些步骤成为可以理解、修改和重复执行的对象。

本文围绕“主题 → 提纲 → 正文 → 最终结果”展开:先说明工作流怎样描述,再解释 LangChain 与 LangGraph 各自承担的工作,最后讨论画布编辑、异步交互和运行反馈。

前端实现可以参考我放在 GitHub 的 **LangChainWeb**,使用 React、React Flow 和 Zustand。文中的前端实现说明对应公开仓库;执行器、校验和持久化部分讨论通用设计,不代表该前端仓库单独提供了完整服务。

一、先分清“设计流程”和“执行流程”

用户说“帮我生成一套文章工作流”,与用户点击“运行这套工作流”,发生的是两件不同的事。

设计阶段把自然语言转换成流程定义:需要哪些节点,怎么连接,每个节点的输入从哪里来。执行阶段读取已经确认的定义,再按照依赖关系处理某次输入。

工作流的两个阶段:设计阶段生成草稿并经过编辑校验保存;执行阶段读取已保存定义和本次输入,调度节点并记录结果

如果把两者混在一起,就容易出现一个问题:用户只是想把正文改得简短一些,应用却已经开始调用整套流程。更清楚的交互是,先更新流程草稿,展示变更,保存后再由运行操作触发执行。

在这个例子中,几个组件的职责可以这样理解:

组件 负责什么 在文章工作流中的位置
LangChain 组织消息、模板、模型调用与结果解析 设计草稿、生成提纲、生成正文时的模型调用
LangGraph 管理状态、节点及执行路径 决定哪些节点就绪,如何合并结果,接下来走哪一步
React Flow 展示和编辑节点、连线 用户看到的可视化画布
应用业务层 定义节点能力、校验规则、保存与运行行为 把编辑器、模型服务与执行器连接起来

LangGraph 的节点可以包含模型调用,也可以只做数据转换或规则检查。React Flow 的一条可见连线,则需要业务层赋予依赖语义,才能参与实际执行。框架的工作流与代理定位可以结合官方说明阅读。

把提纲和正文分开也有成本:多一次模型请求,就多了请求开销、等待和失败的可能。它适合需要检查中间结果、复用步骤或分别调参的任务。如果只是偶尔生成一小段文字,一次调用通常更简单。

二、先定义数据,再画节点

搭建工作流时,很容易先做出一个能拖拽的画布,然后才考虑这些方框应该怎样执行。更稳妥的顺序是先定义业务数据,再为它提供可视化编辑。

一份流程至少需要表达什么

以下是一个教学用的定义方式,字段名称可以根据自己的系统调整:

内容 例子 为什么需要
流程标识与版本 “技术文章生成”,第 3 版 把一次运行对应到确定的配置
节点标识 outline、article 稳定引用,修改显示名称后仍能定位
节点类型 输入、文本生成、结果整理 找到对应的执行能力
节点配置 提示要求、模型选项 描述这个步骤具体做什么
输入绑定 正文读取提纲节点的文本 说明数据从哪里来
连线 提纲完成后才能生成正文 说明执行依赖
画布布局 位置、视野 改善编辑体验,不决定业务结果

同一个节点的“显示名称”和“稳定标识”应分开。把“生成提纲”改名为“技术提纲”只是显示变化,不应导致所有下游引用失效。

连线和输入绑定也不能互相替代。连线回答“什么时候能执行”,输入绑定回答“拿什么执行”。 正文节点需要等待提纲完成,同时明确读取提纲的哪个字段。如果只画线而没有数据绑定,执行器不知道该传什么;只写引用却没有依赖,则可能在数据尚未产生时就开始运行。

用四个节点走一遍

节点 输入 输出 执行前提
输入主题 本次运行的主题和读者 规范化的输入数据 必填项完整
生成提纲 主题、读者、提纲要求 可检查的章节提纲 输入节点完成
撰写正文 主题、提纲、正文要求 正文文本 提纲生成并通过校验
整理结果 正文及需要展示的元信息 面向页面的最终结果 正文节点完成

这时还要分开保存三类数据:

  • 流程定义:节点、配置、连线以及版本,描述以后应该怎样执行。
  • 本次运行状态:这次输入、各节点输出、错误与执行进度,描述这一次发生了什么。
  • 编辑器状态:选中的节点、缩放位置、未保存标记、撤销历史,描述用户正在怎样编辑。

三者的生命周期不同。拖动方框不应改变旧运行记录;重新运行不应覆盖前一次结果;查看历史结果,也不应把当时的节点输出写进当前配置。

三、让模型生成可检查的流程草稿

设计助手需要的上下文,通常包括本轮需求、当前流程、必要的对话历史,以及应用支持的节点目录。

节点目录尤其重要。模型可能知道“发送邮件”“查询知识库”这样的概念,但应用不一定具备对应能力。设计提示应明确告诉它可用节点、参数约束和输出格式;超出能力的需求,可以解释缺少的部分,或者继续澄清。

设计结果可以分为三类内容:面向用户的说明、完整流程草稿、仍待确认的问题。用户说“改成更正式一点”时,如果无法判断要修改提纲还是正文,就应保留当前图并澄清,而不是任意重建整个流程。

获得结构化结果后,建议按以下次序检查:

检查 一个会被拦下的例子
结构检查 节点列表不是数组,缺少节点类型
标识与引用检查 两个节点使用相同 ID,连线指向不存在的节点
能力检查 生成了未注册的节点类型或不支持的配置
图结构检查 节点无法从入口到达,或出现当前执行协议不允许的环
数据依赖检查 正文引用了提纲输出,却没有可保证其就绪的依赖关系
任务检查 用户要的是提纲与正文,草稿却只生成了标题

这些检查应由应用执行,不能只写在提示词里。对服务端而言,用户手动编辑的定义和模型生成的定义,都需要经过一致的验证。

还要区分可自动补齐的展示信息和影响语义的错误。缺少节点坐标可以按拓扑层级布局;缺少关键依赖边却不适合静默猜测。布局修复只是让图更易读,依赖修复可能改变执行含义。

关于输出结构,可以借助模型支持的约束能力,但业务规则仍然需要单独检查,参见LangChain 结构化输出说明。

四、LangGraph 如何把流程变成执行过程

理解 LangGraph,先抓住三个概念:State 保存数据,Node 处理数据,Edge 描述下一步。 实际执行时,节点读取状态,返回更新,图运行时再根据各字段的更新规则合并结果。

状态怎样一步步变化

仍然使用文章生成例子,可以把运行状态想成下面这张表。表中只展示逻辑内容,不绑定具体接口:

执行位置 输入主题 已保留的结果 下一步需要什么
开始 Promise 的错误传播 暂无 生成提纲
提纲完成 保持不变 提纲 正文读取主题与提纲
正文完成 保持不变 提纲、正文 整理最终输出
结束 保持不变 提纲、正文、最终结果 展示或保存运行结果

节点通常只返回自己产生的更新,不需要把整个状态重新构造一遍。例如,正文节点返回新的正文结果,输入主题和提纲应该继续保留。

这里要注意更新的粒度:保留其他顶层字段,与自动深度合并一个对象,是两回事。如果所有节点结果都放在同一个 outputs 字段中,后一个节点只写入自己的结果时,就需要为这个字段定义合适的 reducer。

reducer 为什么重要

Reducer 决定某个状态字段收到更新时如何合并。对文章流程,可以选择让输入保持不变,让节点结果按节点 ID 合并,让当前阶段按最新状态替换。

假设提纲结果已经保存,正文节点又写入正文结果。如果整个结果集合被直接替换,提纲就丢了;按不同节点 ID 合并,就能同时保留两份内容。若两个并发节点写入同一个 ID,浅合并也无法替你决定哪个版本才正确,应通过唯一写入者或明确的冲突规则解决。

状态、节点、reducer 与边的基本语义见 LangGraph Graph API。

从保存的定义到可运行的图

实现图编译时,可以按这样的顺序组织:

  1. 检查节点类型和依赖关系,把业务节点标识映射到图中的节点。
  2. 为每种节点找到执行函数,约定输入读取和输出写入方式。
  3. 建立入口、结束点,以及固定边或条件路由。
  4. 声明状态字段和各自的合并规则,再编译为可执行的图。
  5. 运行时传入本次输入,并配置超时、步数等执行边界。

“节点类型 → 执行函数”应由应用的节点注册表决定。模型生成的是受约束的数据定义,不能直接成为任意可执行脚本。

分支可以并行,汇合必须等待正确的依赖

如果提纲完成后,可以同时撰写正文和准备封面提示,那么两个分支没有互相依赖。最终整理节点则需要等待它实际使用的两个结果。

在 LangGraph 中,多起点的 addEdge 可以表达等待全部指定前置节点完成的汇合关系;使用前可以核对 StateGraph API。不要把“多条线都画向一个节点”直接理解为任意执行器都会自动等待所有结果。

并行是否值得,还取决于模型限流、任务体量和失败处理。可以先把串行结果做正确,再针对独立节点加入并发控制。图上存在分支,并不能证明应用已经实现了并行调用。

五、分支、重试与恢复分别解决什么问题

最小版本可以只支持有向无环图,也就是 DAG。这样依赖关系容易检查,用户也容易理解运行顺序。等到需要“检查正文,不合格就修改”时,再考虑引入条件和循环。

条件分支应基于明确的数据

例如,正文检查节点输出“是否通过”和“修改意见”。通过时进入结果节点;不通过时进入修改节点。判断依据要能被后续逻辑读取,而不是去模型的一段解释里猜测“它似乎觉得可以”。

如果允许返回修改节点,还要保存修改次数并设定退出条件。业务上的“最多修改两轮”和图执行器的步数限制用途不同:前者控制产品行为,后者用于限制异常执行。达到上限后,应返回最后结果和未解决的问题,或转入人工处理。

LangGraph 支持循环,不代表每个可视化编辑器都应该开放任意环。是否允许循环、怎样向用户展示循环次数,需要在编辑协议和执行规则中一起定义。

日志不能直接替代检查点

运行记录通常回答“执行了什么、花了多久、哪里失败”。检查点还要保存能够恢复执行的状态及相关运行信息。仅有一张节点日志表,无法自动推导出准确的恢复位置。

LangGraph 的 checkpointer 用于保存线程关联的图状态。要实现人工确认后继续执行,还需要配置检查点存储、使用相应线程标识,并提供恢复入口。进程重启后的恢复需要可持久保存的存储,内存中的检查点不能承担这个用途。相关机制见持久化说明和中断说明。

恢复时还要考虑副作用。比如,“提交图片生成任务”已经成功,随后本地记录写入失败;直接重跑可能又提交一次。可以在执行前确定稳定的幂等键,在上游支持时一并传递,并记录任务 ID 供恢复时查询。上游不支持幂等或查询时,必须承认存在重复执行风险,再选择补偿或人工处理方式。

六、从 LangChainWeb 看可编辑画布的实现

前面的执行原理可以用于不同后端。前端部分则可以直接参考 GitHub 的 LangChainWeb。以下链接固定到本文查看的公开提交,便于以后对照阅读,不贴整段实现代码。

1. 在画布模型与业务定义之间做转换

React Flow 节点需要位置、组件类型以及供组件渲染的数据。业务节点则更关心节点能力、参数和依赖。两种结构有交集,但不应该依靠同一个“type”字段隐式表达所有含义。

公开的工作流编辑器提供了画布节点与业务节点之间的转换:进入画布时补齐展示信息,保存时提取业务类型和参数。

这层转换让修改节点外观不必改变执行含义。继续扩展时,还可以把布局信息与业务配置分别管理,减少 UI 字段进入执行层的机会。React Flow 自定义节点的机制可以参考官方文档。

2. 用版本比较处理慢请求

一个典型冲突是:用户发出生成请求后,手动改了正文节点;几秒钟后,模型返回了基于旧画布生成的新草稿。

对话助手组件会在请求开始时取得当前编辑版本,响应回来后再比较。期间没有相关变化时可以应用结果;已经发生变化时,把结果保留为候选,交给用户选择。

请求本身也有身份与取消状态。停止请求或组件卸载后,过期响应需要被忽略。仅仅把加载动画隐藏掉,不能阻止旧响应继续写入状态。

3. 把“应用 AI 草稿”作为一次完整编辑

AI 一次可能修改多个节点、连线和流程名称。如果撤销只能恢复节点,却没有恢复输入或其他元信息,用户看到的流程仍然不一致。

公开的状态管理模块管理图的历史和未保存状态,编辑器同时记录生成前后的元信息。这种实现值得借鉴:批量生成应该作为一次有边界的编辑操作,应用和撤销都要恢复一份一致的成果。

节点拖拽也需要考虑历史粒度。鼠标移动每一帧都记一份快照,既占空间,也会让一次撤销只后退几个像素。以一次完成的编辑动作为单位,更符合用户预期。

4. 让保存状态与运行对象保持一致

公开编辑器把服务器保存和本地草稿保存区分开来;点击运行时,会先保存当前画布,再使用保存得到的标识发起运行。这样可以减少“页面上改好了,实际跑的还是旧配置”的问题。

对于多人协作或多窗口编辑,还应进一步让一次运行绑定确定的流程版本或快照。先保存再运行可以解决一部分单客户端问题,但无法独自解决所有并发更新冲突。

结果展示可以参考执行结果组件:把总状态、节点结果以及不同输出类型分开呈现。对于媒体任务,“提交成功”和“已有可用资源”是不同状态,界面需要让用户看出差别。

七、运行反馈要能回答“卡在哪一步”

工作流运行十几秒没有任何变化,用户往往会重复点击。相比只展示一个全局转圈,更有帮助的信息是当前节点、已完成节点,以及失败后的处理方向。

一份运行记录可以包含流程版本、运行标识、本次输入、节点开始与结束时间、阶段输出和错误分类。对于模型节点,还可以记录模型标识、提示模板版本和用量元数据;敏感输入按需要裁剪或脱敏。

现象 应优先检查 合理的处理方向
一开始就失败 输入与流程定义是否合法 明确指出缺少字段或无效引用
长时间等待模型 上游响应、限流与超时预算 有界重试,向用户说明等待阶段
返回内容却无法继续 输出结构及业务校验 给出具体反馈,修正结果或保留草稿
用户取消后仍出现结果 取消传播与过期响应判断 停止后续调度,忽略过期 UI 更新
同一步执行了两次 重复提交、重试与恢复记录 使用幂等键,查询已有任务状态

流式反馈还可以分成两类:模型生成的文字片段,以及节点开始、完成、失败等流程事件。只传文字片段,用户仍不知道整个图运行到了哪里;只传节点状态,又无法实现逐步阅读正文。LangGraph 的流式输出文档介绍了可消费的状态与消息信息,应用还需要把它们转换成自己的页面事件。

取消也有层次。浏览器中止连接,只能说明客户端不再等待;服务端是否停止、外部任务是否撤销,需要各层支持。对于已经提交的耗时任务,保留任务标识和查询入口,通常比让用户重新提交更有用。

八、从最小版本开始,逐步增加能力

如果准备自己做一个类似工具,可以先按四个阶段推进:

  1. 固定流程。 实现主题、提纲、正文和结果四个步骤,用固定结果验证数据传递,再接真实模型。
  2. 可编辑定义。 保存节点、参数、连线和版本,让用户能调整配置并重复运行。
  3. 对话生成草稿。 增加能力目录、结构化校验、候选结果和撤销,接入已有编辑流程。
  4. 复杂执行控制。 有明确需求后,再增加并行、条件循环、人工确认与持久化恢复。

每个阶段都可以用具体场景验收:修改提纲要求是否只影响对应步骤;删除节点后能否发现失效引用;生成期间手动编辑是否得到保护;保存失败时是否仍保留草稿;某个节点失败后能否定位到输入和阶段结果。

对于生成质量,还要单独准备一组固定需求,检查流程是否覆盖用户目标、参数是否可编辑、结果是否有用。图能跑通只是基础,用户能理解并修正它,才有持续使用的价值。

感兴趣的话,可以到 GitHub:hujinbin/LangChainWeb 查看可视化编辑器,重点阅读对话助手、画布转换、历史记录和结果展示部分。欢迎 Star,也欢迎通过 Issue 交流工作流编辑和 AI 应用的实现思路。仓库提供前端实现,完整的生成与执行体验需要配套服务或自己的服务适配。

如果还想回顾一次模型调用内部的数据流,可以接着阅读:LangChain 入门:用 JavaScript 组织模型调用与提示模板。

作者

hujinbin

发布于

2026-10-14

更新于

2026-11-14

许可协议

评论