深入理解 FlowGram.AI：可组合的工作流开发框架，如何帮你构建 AI 工作流平台

• 前端
• 低代码
• 工作流自动化
• 流程编排

本文以 FlowGram.AI 的中文说明文档为核心，结合开源仓库中的 monorepo 结构、create-app 脚手架源码与示例工程代码，系统讲解 FlowGram 的定位与四大核心能力（自由布局画布、固定布局画布、表单引擎、变量引擎）、从npx @flowgram.ai/create-app到本地运行的完整上手流程，以及将自由布局编辑器集成进自有 React 项目的典型代码范式，读完即可在本地跑通官方 Demo 并理解各功能包之间的调用关系。

一、FlowGram 是什么：框架，而非现成平台

FlowGram 是一个可组合、可视化、易于集成且可扩展的工作流开发框架与工具集，目标是帮助开发者以更快、更简单的方式搭建 AI 工作流平台。它内置了开箱即用的工作流开发能力：

• 可视化流程画布（自由布局 + 固定布局两种形态）；
• 节点配置表单引擎；
• 变量作用域链；
• 开箱即用的物料（LLM、条件、代码编辑器等）。

需要特别强调官方文档的定位表述：FlowGram 并非一个现成的工作流平台，而是帮助你构建平台的框架与工具。这一区别直接体现在仓库的组织方式上——仓库rush.json中以 Rush monorepo 管理了约 70 个项目，按职责划分为引擎层（packages/canvas-engine、packages/node-engine、packages/variable-engine、packages/runtime）、客户端编辑器（packages/client）、插件（packages/plugins，含 30 余个独立插件包）、物料（packages/materials）以及多个可独立运行的示例应用（apps/demo-*）。用户既可以整体使用示例工程，也可以按需取用其中任意一层。

二、快速上手：从一条命令到本地运行

官方文档给出的最短上手路径是三步：

1. 创建一个新的 FlowGram 项目：

npx @flowgram.ai/create-app@latest

官方推荐选择Free Layout Demo模板。

2. 启动项目：

cd demo-free-layout npm install npm start

3. 在浏览器中打开http://localhost:3000。

模板选项与 create-app 的底层实现

上述命令背后的实现位于 apps/create-app/src/index.ts。从源码看，交互式界面提供的 7 个模板选择为：

除了交互式选择，create-app还支持直接传参创建，源码中合法参数为fixed-layout、free-layout、fixed-layout-simple、free-layout-simple、playground、nextjs，会自动拼接为demo-<参数名>文件夹名。

其工作流可以归纳为：

1. 通过npm view查询对应 demo 包的 latest 版本号；
2. 从 npm registry 下载@flowgram.ai/<模板名>的 tarball 并解压到当前目录；
3. 将解压目录重命名为<模板名>，并批量把package.json中所有@flowgram.ai前缀的依赖版本对齐为@flowgram.ai/core的最新版本，保证整套包版本一致。

因此模板工程并非从 Git 仓库克隆，而是以 npm 包分发的形式落地，这也解释了为什么每个 demo 包都带有files字段（如 apps/demo-free-layout/package.json 中声明发布src/、rsbuild.config.ts、index.html等文件）。

运行脚本与依赖结构

以官方推荐的 demo-free-layout 为例，npm start实际执行的是cross-env NODE_ENV=development rsbuild dev --open，即基于 Rsbuild 的开发服务器。其依赖清单本身就是一份"自由布局编辑器所需插件"的完整清单：

{ "dependencies": { "@flowgram.ai/free-layout-editor": "workspace:*", "@flowgram.ai/free-snap-plugin": "workspace:*", "@flowgram.ai/free-lines-plugin": "workspace:*", "@flowgram.ai/free-node-panel-plugin": "workspace:*", "@flowgram.ai/minimap-plugin": "workspace:*", "@flowgram.ai/export-plugin": "workspace:*", "@flowgram.ai/free-container-plugin": "workspace:*", "@flowgram.ai/free-group-plugin": "workspace:*", "@flowgram.ai/form-materials": "workspace:*", "@flowgram.ai/panel-manager-plugin": "workspace:*", "@flowgram.ai/free-stack-plugin": "workspace:*", "@flowgram.ai/runtime-js": "workspace:*" } }

（monorepo 内以workspace:*协议引用；脚手架生成的模板工程中会被替换为具体版本号。）可以看到自由布局编辑器由"核心编辑器包 + 若干能力插件"组合而成：连线（lines）、吸附（snap）、节点面板（node-panel）、小地图（minimap）、分组（group）、容器（container）、导出（export）、面板管理（panel-manager）等能力均以独立插件包形式提供，这正是"可组合"定位的具体体现。

参与源码开发的运行环境要求

若需要直接基于本仓库开发，rush.json 声明了官方工具链约束：

• Rush 版本：5.150.0，包管理器为pnpm10.6.5（Rush 会安装隔离的本地副本）；
• Node.js 支持版本范围：>=18.20.3 <19.0.0 || >=20.14.0 <23.0.0。

仓库还配套了 git hooks（common/git-hooks）与自动安装脚本（common/scripts/install-run-rush.js、install-run-rushx.js），用于在提交前执行 lint 与依赖一致性检查。

三、官方 Demo 演示的工作流全貌

README 中描述的演示案例是一条典型的 AI 工作流：

遍历一组城市，通过 HTTP 获取实时天气，用 Code 节点解析温度，借助 LLM 生成穿搭建议，经由 Condition 进行筛选，在循环中汇总结果，最后使用 Advisor LLM 选出最舒适的城市，并将结果发送至 End 节点。

这条流程与 Demo 工程注册的节点类型一一对应。apps/demo-free-layout/src/nodes/index.ts 中注册了 15 类节点：

export const nodeRegistries: FlowNodeRegistry[] = [ ConditionNodeRegistry, StartNodeRegistry, EndNodeRegistry, LLMNodeRegistry, LoopNodeRegistry, CommentNodeRegistry, BlockStartNodeRegistry, BlockEndNodeRegistry, HTTPNodeRegistry, CodeNodeRegistry, ContinueNodeRegistry, BreakNodeRegistry, VariableNodeRegistry, GroupNodeRegistry, MultiConditionNodeRegistry, ];

演示提到的"循环中汇总"对应LoopNodeRegistry配合ContinueNodeRegistry/BreakNodeRegistry，"HTTP 获取天气"对应HTTPNodeRegistry，"解析温度"对应CodeNodeRegistry，"生成穿搭建议 / Advisor LLM"对应LLMNodeRegistry，"Condition 筛选"对应ConditionNodeRegistry/MultiConditionNodeRegistry，起始与收尾则是StartNodeRegistry/EndNodeRegistry。节点注册表（FlowNodeRegistry[]）是把业务节点接入画布的统一入口，下一节会展示它在编辑器中的用法。

四、四大核心能力

官方文档将特性归纳为表格形式，这里逐条展开，并映射到仓库中对应的实现包。

4.1 Free Layout Canvas：自由布局画布

自由布局画布中，节点可任意摆放，并可在节点间创建边进行链接，适合无固定流程拓扑的图编辑场景。

实现上由 packages/canvas-engine 提供地基：

• core（@flowgram.ai/core）：画布核心；
• document（@flowgram.ai/document）：节点/边/画布的文档模型；
• renderer（@flowgram.ai/renderer）：渲染层；
• free-layout-core（@flowgram.ai/free-layout-core）：自由布局专有逻辑；
• 客户端封装packages/client/free-layout-editor（@flowgram.ai/free-layout-editor）。

从 packages/client/free-layout-editor/src/index.ts 的导出结构看，该包对外聚合了核心模块（@flowgram.ai/editor）、自由布局核心（free-layout-core）、预设（preset）、Hooks、工具函数，并直接再导出free-history-plugin（历史/撤销能力），即"一个包拿到可用的自由布局编辑器"：

export * from '@flowgram.ai/editor'; export * from '@flowgram.ai/free-layout-core'; export * from './components'; export * from './preset'; export * from './hooks'; export * from './tools'; export * from '@flowgram.ai/free-history-plugin';

4.2 Fixed Layout Canvas：固定布局画布

固定布局画布中节点可拖拽至指定位置，并支持复合节点（如分支与循环），适合流程结构相对规整、需要层级化表达的业务流程。对应实现包为packages/canvas-engine/fixed-layout-core与packages/client/fixed-layout-editor，另有fixed-drag-plugin（固定布局拖拽）、fixed-history-plugin（固定布局历史）、fixed-semi-materials（基于 Semi 设计的固定布局物料）等配套包。

4.3 Form：表单引擎

表单引擎负责管理节点数据的增删改查，并提供渲染、验证、副作用、联动和错误捕获等能力，从而简化节点配置界面的开发。仓库中对应packages/node-engine下的form-core（@flowgram.ai/form-core，表单核心）与form（@flowgram.ai/form），物料侧则提供packages/materials/form-materials、form-antd-materials等表单物料包。仓库中专有apps/demo-node-form示例工程，专门演示"节点表单"这一场景；表单元数据驱动的写法可参考该工程的form-meta.tsx与node-registries.tsx（见 apps/demo-node-form/src）。

4.4 Variable：变量引擎

变量引擎支持作用域约束、变量结构检查和类型推断，用于管理工作流中的数据流。实现位于packages/variable-engine：

• variable-core（@flowgram.ai/variable-core）：变量模型与作用域链核心；
• variable-layout（@flowgram.ai/variable-layout）：变量选择器相关的布局能力；
• json-schema（@flowgram.ai/json-schema）：基于 JSON Schema 的结构描述。

配合插件packages/plugins/node-variable-plugin、packages/plugins/variable-plugin以及物料packages/materials/type-editor（类型编辑器），即可在节点表单中引用上游节点输出的变量并获得类型约束——这是 AI 工作流中"数据沿边流动"体验的关键一环。

五、编辑器集成范式：自由布局 Demo 的编辑器写法

官方 Demo 的编辑器入口非常短小，是理解 FlowGram 集成方式的最好样本。apps/demo-free-layout/src/editor.tsx 全文核心如下：

import { DockedPanelLayer } from '@flowgram.ai/panel-manager-plugin'; import { EditorRenderer, FreeLayoutEditorProvider } from '@flowgram.ai/free-layout-editor'; import '@flowgram.ai/free-layout-editor/index.css'; import { nodeRegistries } from './nodes'; import { initialData } from './initial-data'; import { useEditorProps } from './hooks'; export const Editor = () => { const editorProps = useEditorProps(initialData, nodeRegistries); return ( <div className="doc-free-feature-overview"> <FreeLayoutEditorProvider {...editorProps}> <div className="demo-container"> <DockedPanelLayer> <EditorRenderer className="demo-editor" /> </DockedPanelLayer> </div> </FreeLayoutEditorProvider> </div> ); };

其中三个关键构件：

1. FreeLayoutEditorProvider：自由布局编辑器的 Provider，承载画布上下文、节点注册表与初始数据；其内部通过free-layout-preset预置默认插件集（preset 目录见 packages/client/free-layout-editor/src/preset），组件实现位于 packages/client/free-layout-editor/src/components。
2. EditorRenderer：真正渲染画布的组件；
3. DockedPanelLayer：来自@flowgram.ai/panel-manager-plugin，负责节点配置面板等浮层的停靠管理。

useEditorProps(initialData, nodeRegistries)这一 Hook（位于apps/demo-free-layout/src/hooks）把初始画布数据（initial-data.ts）与节点注册表（上一节列出的 15 类节点）组装成 Provider 所需 props。换言之，集成 FlowGram 自由布局编辑器的标准动作就是：注册节点 → 准备初始数据 → 用 Provider 包裹 Renderer。固定布局侧（@flowgram.ai/fixed-layout-editor）遵循同样的 Provider/Renderer 模式，差异在于布局模型与复合节点能力。

六、仓库工程全景：monorepo 结构与配套工具

围绕 README 描述的能力，仓库按如下层次组织（均出自 rush.json 的项目清单）：

值得注意的两点工程事实：

• 运行时独立成层：packages/runtime同时提供浏览器端（runtime-js）与 Node.js 端（runtime-nodejs）运行时，并通过runtime-interface定义契约，说明工作流执行能力与画布编辑能力是解耦的——画布产出的是可序列化的工作流数据，执行交给运行时。
• CLI 工具链：除create-app外，仓库还提供@flowgram.ai/cli（apps/cli/src/index.ts），内置四个子命令：create-app（创建项目）、materials（同步物料到项目，支持--refresh-project-imports、--target-material-root-dir、--select-multiple选项）、find-used-materials（查找项目中已使用的物料）、update-version（批量更新项目中的 flowgram 版本）。这套工具面向"从官方物料库按需取材"的开发模式。

七、文档体系与多语言支持

本仓库自带完整文档站点工程 apps/docs，基于 Rspress 构建，内容分中文（apps/docs/src/zh，135 篇 MDX）与英文（apps/docs/src/en）两套，覆盖与 README 章节清单一致的十大板块：

• 快速入门
• 自由画布
• 固定画布
• 表单
• 变量
• 素材（materials）
• 运行时
• 进阶指南
• API 参考
• 获取支持与贡献指南

文档中的代码示例还通过 apps/docs/components/tsx-editor.tsx 等组件做了交互式处理，并在apps/docs/scripts/auto-generate.ts中支持示例代码的自动生成。

八、生态采用与参与方式

README 列出了采用 FlowGram 的开源项目，可作为集成参考：

• Coze Studio：一体化 AI Agent 开发工具；
• NNDeploy：基于工作流的多平台 AI 部署工具；
• Certimate：借助可视化工作流自动申请与部署 SSL 证书的开源工具。

参与渠道方面，问题反馈走仓库 Issues；贡献流程可参考仓库根目录的 CONTRIBUTING.md，开发约束见 AGENTS.md 与 CLAUDE.md；文档的多语言版本（英文、西班牙文、俄文、葡萄牙文、德文、日文）分别位于 README.md、README_ES.md、README_RU.md、README_PT.md、README_DE.md、README_JA.md。

小结

FlowGram.AI 的价值在于把"AI 工作流平台"拆解为可独立取用的四层能力——画布引擎、表单引擎、变量引擎与运行时——并以 30 余个插件包和 9 个可运行的 demo 工程证明其组合方式。上手路径始终是一条命令（npx @flowgram.ai/create-app@latest）加三步运行；深入路径则是沿着 demo-free-layout 的Provider → Renderer → DockedPanelLayer集成范式，逐包阅读packages/canvas-engine、packages/node-engine、packages/variable-engine与packages/runtime的源码，最终把这套框架组装进自己的平台。

• 前端
• 低代码
• 工作流自动化
• 流程编排