先说句实话很多开发者不好意思承认我一开始并没真想做一个“平台”我只是想把一段嵌套了五层 if/else 的 AI Agent 代码理清楚。那个项目最可怕的不是模型返回不对而是当工具调用、条件分支、重试策略、变量传递全混在一起之后任何一次逻辑调整都要在代码里翻上半天。后来我决定换个角度既然代码已经无法表达这个流程的复杂度那干脆把它“画”出来。这就是我用 Next.js React Flow 从零搭建可视化 AI 工作流编排平台的起因。做出来之后我才发现一个能拖拽、能连线、能实时看到每步执行结果的画布不仅拯救了团队的协作效率还顺手解决了一个我一直头疼的问题——怎么让非研发同事也能理解智能体到底是怎么工作的。这篇文章不打算复读官方文档。我想记录的是实际搭建过程中真正的关键决策为什么选 React Flow 而不是其他流程图库、数据结构怎么设计才不返工、画布交互怎么做才顺手、后端执行引擎怎么跟 LLM 调用打通以及我踩过的那些不太容易搜到答案的坑。如果你正准备做类似的可视化工作流编排、AI Agent 拖拽平台这篇至少能帮你节省几个晚上的排查时间。1. 技术选型为什么是 Next.js React Flow而不是更“专业”的方案1.1 我和其他可视化库的对比结论先聊画布。市面上能拖拽连线的库其实不算少但我一开始就排除了那几个重型方案。先说 bpmn-js。它沿用的 BPMN 2.0 符号系统非常完整审批流、事件网关、子流程全都覆盖。但问题在于它太重了BPMN 有自己的一套 XML 规范和语义为了让 AI 工作流适配它我得做大量的语义映射比如一个 LLM 节点到底是 userTask 还是 serviceTask。这套体系适合做严谨的流程审批不适合做 AI 应用的 RD 原型迭代。项目里我们每周都在加新节点类型BPMN 的规矩反而成了最大的阻力。然后是 AntV X6 和 XFlow。X6 底层能力确实强连线规则、端口、群组、小地图一应俱全。但说实话XFlow 的文档在我做选型那会儿还处于“抽象且不完整”的状态很多能力得翻源码才能确定。对于一个人要扛前后端的项目来说这个学习成本太高了。React Flow现在 npm 上的包名是 xyflow/reactv12 之后不再叫 reactflow是我的最终选择。理由很朴素它不是一个脱离 React 生态的独立图形库而是把节点、连线、画布全部当作 React 组件来渲染。这意味着我想在节点里放任何自定义 UI——下拉框、输入框、状态指示灯、Markdown 预览——都只是写一个普通的 React 组件而已。对于 AI 工作流这种节点类型高度自定义、迭代极快的场景React Flow 的灵活性和心智负担都最合适。1.2 Next.js 在这里解决的不只是 SSR 问题画布组件定了之后剩下的是一个很实际的问题前端画布做完后端执行引擎放哪主流方案有两种。一种是前后端彻底分离前端用 Vite React后端用 FastAPI 或 Node 服务。另一种是把 Next.js 作为全栈框架前端页面、API 路由、后端的图执行引擎全放在一个项目里。我选了后者核心原因是部署和迭代效率。AI 工作流平台在一开始并不能准确定义“平台边界”今天加一个模型配置页明天加一个执行日志面板如果前后端分离每一次小改动都要处理跨域、联调、两套部署流程。Next.js 的 App Router 让我可以在app/api/workflows/execute/route.ts里直接写执行接口前端页面和接口共享同一个 TypeScript 类型定义改一个数据结构两端都同步生效。单人开发时这个收益极其明显即使以后团队变大再拆出独立后端也不迟因为接口边界是清晰的。另外还有一个容易被忽略的点AI 工作流平台通常不是一个纯 ToC 的对外站点而是要嵌入到内部系统里或者作为团队工具使用。Next.js 的 SSR 对 SEO 帮助有限但可以保证仪表盘首屏的渲染速度稳定尤其当画布上已经有几十个节点时客户端渲染的首屏体验确实会改善。从搭建效率到运行时表现Next.js 整体是最均衡的选择。2. 先定义好“图”的数据模型后面才不用返工2.1 节点统一 Schema把所有配置放进 data.config很多人在初始化 React Flow 项目时直接就往nodes数组里塞{ id: 1, position: {x:0, y:0}, data: { label: xxx } }。这种写法跑通 Demo 很快但等到节点类型一多你会发现自己陷入混乱有的节点把配置直接摊在data上有的需要从外部接口拉配置有的还带复杂的校验逻辑。我的做法是给节点定义一个统一的结构export type NodeType start | ai | tool | condition | output; export interface WorkflowNode { id: string; type: NodeType; position: { x: number; y: number }; data: { label: string; config: Recordstring, any; inputs: Array{ name: string; required: boolean; type: string }; outputs: Array{ name: string; type: string }; }; }注意这里的思路data里既有label这种 UI 展示字段也有config这种业务配置字段还有inputs和outputs这种结构描述字段。把业务配置全部收敛到config对象里有几个好处序列化和反序列化非常简单直接JSON.stringify整个节点就能存数据库。节点组件渲染时只依赖data.config不会因为加了一个不入库的临时 UI 状态而污染持久化数据。配置结构变更时可以做版本迁移比如读取config.version来决定是否需要升级数据格式。在定义inputs/outputs时我的建议是不要把它们放到config里而要作为节点的显式元数据。因为后面的连线合法性检查、自动布局、上下文变量注入都依赖这些声明。一个小技巧是outputs里的type字段可以标记为text | number | object前端连边时可以根据类型过滤避免把瘦文本输出连到一个只接受结构化 JSON 的输入端口。2.2 边的连接规则与 DAG 循环校验定义了节点边的结构也不难但需要额外考虑几个字段export interface WorkflowEdge { id: string; source: string; target: string; sourceHandle?: string; targetHandle?: string; data?: { label?: string; condition?: string; }; }sourceHandle和targetHandle一定要用。它们对应节点上的输出端口和输入端口。没有 handle 时 React Flow 也能连线但多输入多输出节点会有歧义而且执行时你不知道数据到底要从哪个出口传递。AI 工作流跟普通业务流程最大的不同是它必须是一个有向无环图DAG。如果允许环路一个节点循环调自己轻则无限执行重则让 API 账单直接爆炸。所以在用户试图连线时就要做循环检测。我用的检测算法是标准的 DFS 染色法function hasCycle(nodes: WorkflowNode[], edges: WorkflowEdge[]): boolean { const graph new Mapstring, string[](); for (const node of nodes) graph.set(node.id, []); for (const edge of edges) { graph.get(edge.source)?.push(edge.target); } const visiting new Setstring(); const visited new Setstring(); const dfs (id: string): boolean { if (visiting.has(id)) return true; if (visited.has(id)) return false; visiting.add(id); for (const next of graph.get(id) ?? []) { if (dfs(next)) return true; } visiting.delete(id); visited.add(id); return false; }; return nodes.some((node) dfs(node.id)); }有个细节前端校验通过了后端还要再校验一遍。因为接口是可以被 curl 直接调用的如果攻击者或误操作直接 POST 一个带环的图你的执行引擎就挂了。所以我把这个hasCycle函数放在独立的工具文件里前后端公用。同样类型的还有“目标节点是否存在于图中”这种基础校验也必须下沉到后端执行引擎里。3. 从空白画布到能拖拽的工作台交互细节全记录3.1 在 Next.js 里挂载 React Flow 的正确姿势如果你在 Next.js 的 App Router 下直接用 React Flow大概率会撞上第一个报错window is not defined。原因很简单React Flow 的底层依赖window和ResizeObserver而 Next.js 在服务端渲染组件时会尝试执行这些代码。解决办法是让画布组件只在客户端渲染用 Next.js 的dynamic手动关闭 SSRuse client; import dynamic from next/dynamic; const WorkflowCanvas dynamic(() import(./WorkflowCanvas), { ssr: false, loading: () p正在加载画布.../p, }); export default function Page() { return WorkflowCanvas /; }然后把真正引入ReactFlow的组件放在WorkflowCanvas.tsx里。这里也是一个新手容易踩的坑如果WorkflowCanvas里再引入xyflow/react请确保xyflow/react的 CSS 也引入了import { ReactFlow, Background, Controls, MiniMap } from xyflow/react; import xyflow/react/dist/style.css;不引入 CSS 的话画布能渲染节点但连线没箭头、背景没有网格、缩放按钮全部消失排查起来很费劲。3.2 自定义节点为什么 nodeTypes 必须定义在组件外部我要用平台承载不同类型的 AI 节点所以自定义节点是必然的。React Flow 自定义节点的方式是通过nodeTypes属性注入import { ReactFlow } from xyflow/react; import LLMNode from ./nodes/LLMNode; import ToolNode from ./nodes/ToolNode; import ConditionNode from ./nodes/ConditionNode; const nodeTypes { llm: LLMNode, tool: ToolNode, condition: ConditionNode, }; export default function WorkflowCanvas() { return ( ReactFlow nodeTypes{nodeTypes} // ... / ); }这里有个几乎所有 React Flow 新手都会踩的性能陷阱不要把nodeTypes定义在组件函数内部。如果你写成export default function WorkflowCanvas() { const nodeTypes { llm: LLMNode }; // 错误做法 return ReactFlow nodeTypes{nodeTypes} /; }那么每次WorkflowCanvas重新渲染nodeTypes都是一个新的对象引用React Flow 会认为所有节点类型都变了从而强制卸载并重新挂载画布里的所有节点。拖拽一次、画布闪一下那种体验直接劝退用户。同理如果你不想让每个节点在画布状态变化时都跟着重渲染节点组件本身建议用memo包一层const LLMNode memo(function LLMNode({ id, data, selected }: NodeProps) { // ... });这里的selected是从 NodeProps 里透传下来的React Flow 已经做了相当细粒度的更新但memo可以进一步减少不必要的渲染次数尤其是在节点数量超过三十个之后。3.3 从侧边栏拖到画布坐标转换是关键工作台一般长这样左边一个面板罗列着所有可用的节点类型中间是 React Flow 画布右侧是选中节点后的配置面板。从左侧拖拽新节点到画布这一步难点不在于“拖”而在于“坐标转换”。React Flow 里的坐标分为两种屏幕坐标clientX/clientY和流坐标即画布内部世界坐标。如果你直接把clientX、clientY作为节点的position传入在画布缩放或平移之后新节点会出现在完全错误的位置。正确做法是用useReactFlow提供的screenToFlowPosition方法const onDrop useCallback( (event: React.DragEvent) { event.preventDefault(); const type event.dataTransfer.getData(application/reactflow); if (!type) return; const position screenToFlowPosition({ x: event.clientX, y: event.clientY, }); const newNode { id: ${type}-${Date.now()}, type, position, data: { label: type, config: {} }, }; setNodes((nds) [...nds, newNode]); }, [screenToFlowPosition, setNodes] );这个细节看起来简单但忘了它的人不在少数。我自己第一次做的时候就是因为因为坐标没转换导出的流程图在缩放后看起来完全是乱的耽误了一晚上。3.4 状态管理Zustand 还是 useState当工作台有画布、节点配置面板、执行结果面板三个区域时状态管理就不能只用组件局部的useState了。我当时选的是 Zustand原因不是它比 Redux 更“潮”而是它在 React Flow 场景里确实顺手React Flow 的onNodesChange、onEdgesChange、setNodes、setEdges这些 API 可以非常自然地塞进一个 store 的方法里。我的 store 结构大致如下import { create } from zustand; interface WorkflowState { nodes: WorkflowNode[]; edges: WorkflowEdge[]; setNodes: (nodes: WorkflowNode[]) void; setEdges: (edges: WorkflowEdge[]) void; updateNodeConfig: (id: string, config: Recordstring, any) void; }updateNodeConfig是配置面板里最常用的方法。用户在右侧面板修改 LLM 的模型参数时它只需要更新nodes中某个节点的data.config不用重建整个节点数组。Zustand 的细粒度订阅机制能够保证这个更新只触发对应节点组件的重渲染。有一点要提前想清楚节点配置面板是一个受控表单它的输入框值一定来自store。如果用户每敲一个字母就同步到全局 store整个画布上的其他组件都会不必要地收到通知。我的做法是配置面板内部先维护一个本地draft等用户失焦或点击“应用”时才调用updateNodeConfig。这个小调整能明显提升长配置表单的输入流畅度。4. 让节点真正跑起来后端执行引擎与 AI 调用链路4.1 API 路由设计与执行请求的接收画布上的图最终要变成一个能执行的任务。我在 Next.js 里设计了两个核心接口POST /api/workflows/execute接收完整的节点数组和边数组执行整个工作流返回最终输出。POST /api/workflows/run接收workflowId和初始输入按保存的图结构执行适合从配置好的工作流模板运行。execute接口的实现骨架如下// app/api/workflows/execute/route.ts import { NextResponse } from next/server; import { topologicalSort } from /lib/graph; import { executeNode } from /lib/executor; export async function POST(request: Request) { const body await request.json(); const { nodes, edges, input } body as ExecuteRequest; if (!nodes?.length || !edges) { return NextResponse.json({ error: 缺少 nodes 或 edges 参数 }, { status: 400 }); } // 重要后端必须再次校验图的合法性 const cycleError validateDAG(nodes, edges); if (cycleError) { return NextResponse.json({ error: cycleError }, { status: 400 }); } try { const output await runWorkflow(nodes, edges, input ?? {}); return NextResponse.json({ success: true, output }); } catch (error) { return NextResponse.json({ success: false, error: String(error) }, { status: 500 }); } }看到这里有人会问为什么execute不接收workflowId而是直接把整张图传过来原因很现实在编辑器的“试运行”场景里用户可能还没保存工作流就是想在当前画布上跑一下看看结果。这时候后端拿到的不是一个持久化的工作流 ID而是一堆节点和边。所以execute接口天然是一个无状态接口它接收当前画布快照执行完后返回结果不落库。这样做的好处是前后端之间的耦合极低前端任何时候都能发起一次试运行。4.2 图的执行顺序拓扑排序与上下文传递有向无环图的执行顺序用拓扑排序最稳妥。我的做法是先对节点做拓扑排序再按顺序依次执行节点同时维护一个context对象保存每个节点的输出供后续节点引用。拓扑排序可以用 Kahn 算法实现function topologicalSort(nodes: WorkflowNode[], edges: WorkflowEdge[]): string[] { const indegree new Mapstring, number(); const graph new Mapstring, string[](); for (const node of nodes) { indegree.set(node.id, 0); graph.set(node.id, []); } for (const edge of edges) { graph.get(edge.source)!.push(edge.target); indegree.set(edge.target, (indegree.get(edge.target) ?? 0) 1); } const queue nodes .filter((node) (indegree.get(node.id) ?? 0) 0) .map((node) node.id); const result: string[] []; while (queue.length 0) { const current queue.shift()!; result.push(current); for (const next of graph.get(current) ?? []) { indegree.set(next, (indegree.get(next) ?? 0) - 1); if (indegree.get(next) 0) queue.push(next); } } return result; }执行时executeNode会根据节点类型分发async function executeNode(node: WorkflowNode, context: Recordstring, any) { switch (node.type) { case start: return { output: context.input }; case ai: return runLLMNode(node.data.config, context); case tool: return runToolNode(node.data.config, context); case condition: return runConditionNode(node.data.config, context); default: throw new Error(未知节点类型: ${node.type}); } }这里变量替换是整个平台细节设计的一个重要环节。用户可以在 LLM 节点的提示词里写{{上一步的输出}}也可以写{{input}}。在runLLMNode里我会先把提示词模板里的这些占位符替换成context里的实际值再调用大模型。可以给这个替换函数一个小小的正则实现function renderTemplate(template: string, context: Recordstring, any): string { return template.replace(/\{\{\s*([\w.])\s*\}\}/g, (match, path: string) { const value path.split(.).reduce((acc, key) acc?.[key], context); return value undefined || value null ? : String(value); }); }这也是从零搭建平台时容易忽略但实际价值极高的功能它让非研发同事可以通过“变量占位符”的方式编排工作流而不是在代码里拼接上下文。4.3 LLM 调用超时、重试与流式响应执行引擎的核心节点是 AI 节点。调用大模型的接口时有几个工程化的细节必须提前处理。第一是超时。LLM 接口响应时间波动极大3 秒到 60 秒都有可能。如果用户的图里串联了三个 AI 节点体验就会非常漫长。我给每个节点设了一个timeoutMs配置默认 60 秒超过就终止。实现方式是用AbortControllersetTimeout。第二是重试。网络抖动、模型限流在真实业务里非常常见。我的做法是只对“可重试的失败”重试比如 429 限流和 5xx 服务端错误4xx 参数错误不重试因为重试也没用。重试次数默认 2 次而且每次间隔要带随机抖动避免所有节点在同一时刻重试形成流量洪峰。第三是流式响应。如果整个工作流是同步执行用户要等很久才能看到最终结果对心智很不友好。所以我在执行接口里支持了 SSEServer-Sent Events。前端在执行时监听 SSE 事件每跑完一个节点就推送一条进度消息画布上对应节点实时亮起“运行中”“成功”或“失败”的颜色。这个体验提升比任何装修画布样式都管用因为用户能看到 AI 每个环节的执行过程而不是面对一个空白加载页发呆。SSE 接口的核心部分可以简短描述// app/api/workflows/execute/route.ts (流式版本) const encoder new TextEncoder(); const stream new ReadableStream({ async start(controller) { for (const nodeId of sortedNodes) { const result await executeNode(node, context); controller.enqueue(encoder.encode(event: nodeDone\ndata: ${JSON.stringify({ nodeId, result })}\n\n)); context[nodeId] result.output; } controller.enqueue(encoder.encode(event: done\ndata: ${JSON.stringify({ output: context })}\n\n)); controller.close(); }, }); return new Response(stream, { headers: { Content-Type: text/event-stream } });从实际使用反馈来看这个“实时执行进度反馈”是整个平台最受欢迎的功能之一。没有它这就是个花哨的画图工具有了它才是真正的工作流编排平台。5. 实测中踩过的坑文档里不会告诉你的那些细节5.1window is not defined与 Canvas 组件的位置这个坑刚才已经提过但值得再强调一次。用dynamic关闭 SSR 只对“整个画布组件”有效如果你在画布组件的子组件里又引了一个使用window的库而那个子组件不是通过 dynamic 加载的它依然可能在服务端渲染时报错。我的经验是凡是和 React Flow 强相关的组件统一走dynamic加载。凡是纯业务组件保持普通导入。如果你写的是use client组件不要理所当然地认为它不在服务端执行——Next.js 的客户端组件在服务端也会执行一次用于预渲染。只有dynamic(..., { ssr: false })能严格保证只在浏览器执行。5.2 React StrictMode 双重调用导致重复节点Next.js 默认开发环境下开启 StrictMode所有useEffect会执行两次。这里有一个很隐蔽的坑如果你在某个useEffect里初始化默认节点比如“打开页面就在画布中心放一个开始节点”StrictMode 下这个 effect 执行两次页面上会出现两个重叠的开始节点。解决办法不是关掉 StrictMode而是让初始化逻辑具备幂等性。我的做法是在 store 初始化时先检查nodes.length 0才塞入默认节点。更严谨的方案是把“恢复画布”和“新建空白画布”分开默认不自动创建节点用户通过点击或拖拽主动添加第一个节点。5.3 节点详情面板的受控输入与画布联动导致卡顿我在做右侧配置面板时遇到过很折磨人的问题用户在一个输入框里连续打字画布上的节点也跟着重新渲染整个界面掉帧严重。排查下来罪魁祸首是输入框直接绑定到了全局 store并在每次 onChange 时更新 nodes。这会让所有订阅了 nodes 的组件包括画布、缩略图、边全部重新渲染。解决办法前面已经提到配置面板内使用本地draft状态 失焦或“应用”按钮再同步全局 store。如果你确实需要实时预览比如修改节点标题时画布上同步显示那也要用类似 debounce 的手段比如输入值 300ms 没有变化后再更新 store。5.4 保存工作流防抖和增量持久化“保存”这个功能听起来简单但在画布场景里有个高频操作的问题用户拖动一个节点会触发非常多次onNodesChange如果每触发一次就调用一次后端保存 API后端会被打爆。我的方案是前端做防抖保存。拖动结束或边变化后等待 800ms 没有再次变化才把整张图序列化后发给后端。在 localStorage 层面则可以做得更频繁每次内存中的图状态变化就写入 localStorage实现本地草稿的“自动保存”。这里推荐loadNodes、loadEdges时做一次 JSON.parse 的 try/catch 容错避免旧版本数据结构导致整个页面崩溃。应用退出前最后的 localStorage 数据形状大致是 { version: 1, nodes: [...], edges: [...], updatedAt: 1715585478371 }保存version字段是个极其划算的习惯。后面只要数据结构有变化读出来时发现 version 不匹配就可以做迁移而不是让用户清缓存。5.5useReactFlow必须在ReactFlowProvider内使用如果你在画布组件之外比如侧边栏、工具栏想调用screenToFlowPosition、setCenter这类方法直接使用useReactFlow会报错因为它要求组件树位于ReactFlowProvider或ReactFlow组件内部。我最后把整个工作台页面包了一层 Providerexport default function WorkflowPage() { return ( ReactFlowProvider SidePanel / WorkflowCanvas / ConfigPanel / /ReactFlowProvider ); }这样侧边栏、配置面板、工具栏就都能共享同一个 React Flow 实例方法了。如果某天你遇到“useReactFlowmust be used withinReactFlowProvider”这种报错第一反应就是去检查组件层级而不是去查网络。6. 从“能跑”到“好用”给想复刻这个项目的人的建议6.1 从最小闭环开始别一上来就做完整平台第一个版本只需要三类节点一个“开始”节点、一个“AI 模型”节点、一个“输出”节点。能实现从空白画布拖出节点连上线点击“执行”跑出一个文本结果这个闭环就足够了。条件分支、工具调用、循环、并行执行这些功能等核心闭环稳定后再逐步加。我见过很多类似项目死在“完整体验”上花了两周做节点库、模板市场、权限系统结果核心的“拖一个节点然后执行”还没跑通。这样的平台是一栋没有地基的楼。6.2 持久化先行最后再接数据库早期我没急着连 PostgreSQL而是把工作流图存到了 localStorage。原因有两个一是前端迭代时改数据结构的频率极高存在服务端要频繁迁库二是 localStorage 天然适合做本地草稿用户可以随时刷新而不用担心中断。等到真的需要多人协作、版本管理时再把“保存工作流”接口从 localStorage 切到数据库。这时候由于图数据结构已经稳定数据库迁移只需要做一次。6.3 后端的执行引擎和前端画布要共享类型定义我强烈建议把节点的 TypeScript 类型定义放在一个shared/或lib/types.ts文件里前端画布和后端执行引擎都从同一个地方导入。Next.js 的全栈项目结构天然方便这一点会带来两个直接好处前端新增一个节点类型时后端执行引擎会立刻因为 switch-case 缺少这个类型而编译报错提醒你还没有实现执行逻辑。src/tree 一致性让调试变得非常快前后端联调时几乎不会出现“前端传的字段名和后端读的字段名不一致”这种低级错误。6.4 留好“日志”和“调试”的持久化位置AI 工作流排错比普通 Web 开发难得多因为每个节点的输入输出都是对象和文本而且 LLM 是概率性的。我的做法是每次执行结束把完整的执行记录每个节点的入参、出参、耗时、错误信息保存到一个execution_logs列表里。前端做一个侧边抽屉展示历史执行记录用户可以对比同一次工作流在不同运行下的变化差异。这个功能听起来不酷但实际使用频率远高于节点库。6.5 给未来的“版本管理”留条后路当工作流编排平台面向团队使用时版本管理几乎必然会出现。所以工作流数据结构里一定要有version字段服务端保存时不要覆盖原记录而是插入新版本。这意味着执行引擎应该永远基于某个版本的图快照来执行而不是基于“当前最新版本”。在一开始就养成“每条执行记录都与一张具体的图快照绑定”这个习惯后面做回滚和对比功能会非常省心。我现在的体会是可视化 AI 工作流平台的核心竞争力不在酷炫的拖拽动画不在花哨的节点皮肤而是在于“图能存、能跑、能排错、能对比”。只要这四个基本能力扎实哪怕 UI 朴素一点团队也会愿意每天使用它。反过来说如果一张图画得再漂亮但一执行就报错、一保存就丢数据那它永远只能停留在 Demo 阶段。如果你也打算从零搭建这么一套平台我最后想分享的一个实操心得是先把整个链路的“最小闭环”打通中间遇到的所有坑都要记录到项目文档里因为前端画布的坑和后端执行引擎的坑往往不在一起隔几天再排查时很容易忘。别问我为什么知道——如果你也做过半夜被线上工作流执行超时报警叫醒的经历你会明白我在说什么。