LogicFlow 完整开发指南：安装、快速上手、AI 编程支持与生态架构解析-育师

LogicFlow 完整开发指南：安装、快速上手、AI 编程支持与生态架构解析

【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架，支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow

LogicFlow 是一款专注于业务自定义的流程图编辑框架，本文基于官方英文 README（README.en-US.md）整理成完整技术指南。你将了解到如何安装@logicflow/core与@logicflow/extension两个核心包、如何用数行代码渲染出一张可交互的流程图、如何利用随 npm 包发布的本地文档让 AI 编程工具（Agent）在实现功能前先查阅官方能力，以及整个仓库的分包架构、执行引擎与数据转换生态。读完本文，你不仅能跑通第一个 LogicFlow 页面，还能清楚知道"官方已提供什么、该去哪里查文档、什么时候自己写扩展"。

项目概览：专注于业务自定义的流程图编辑框架

LogicFlow 是一个流程图编辑框架（flowchart editing framework），其定位不是提供一个固定功能的编辑器，而是提供一套"流程图交互与编辑所必需的能力" + "简单灵活的节点自定义、插件等扩展机制"，从而帮助开发者在业务系统内快速满足类流程图（flowchart-like）的需求。

从仓库根目录的 package.json 可以看到项目自述为"A highly scalable, execution-oriented, professional flowchart editing library."（高度可扩展、面向执行、专业的流程图编辑库）。借助这些能力，LogicFlow 可以支撑脑图、ER 图、UML、工作流等多种图编辑场景。

五大核心能力

能力	说明
可视化模型（Visualization model）	通过直观的可视化界面，用户可以轻松创建、编辑和管理复杂的逻辑流程图
高可定制性（High customizability）	用户可以根据需要定制节点、连接器和样式，创建符合特定用例的定制逻辑流程图
丰富插件（Rich Plug-ins）	内置丰富的官方插件，用户也可以根据自身需求定制复杂插件实现业务需求
自执行引擎（Self-executing engine）	执行引擎支持在浏览器端执行流程图逻辑，为无代码执行提供新思路
数据可转换（Data convertible）	支持 LogicFlow 数据与 BPMN、Turbo 等各种后端执行引擎数据结构之间的转换

Monorepo 分包架构

当前仓库采用 pnpm workspace + turbo 的 Monorepo 结构（见 pnpm-workspace.yaml、turbo.json），核心包均位于 packages/ 目录：

@logicflow/core（packages/core/package.json）：核心图编辑器运行时，包含画布、节点、边、模型、事件、渲染、主题与基础交互。它依赖preact、mobx、mousetrap（键盘快捷键）等库，发布产物同时提供lib（CJS）、es（ESM）与dist（UMD，可经 unpkg/jsdelivr 直接引用）。
@logicflow/extension（packages/extension/package.json）：官方插件集合，覆盖常见产品功能，如 MiniMap（缩略图）、Group（分组）、DndPanel（拖拽面板）、Menu（右键菜单）、Control（控制栏）、SelectionSelect（框选）、Snapshot（快照）等，源码位于 packages/extension/src/。它以@logicflow/core为 peerDependency，二者需要配套使用。
@logicflow/layout（packages/layout/package.json）：官方布局插件，提供自动图布局能力。其入口（packages/layout/src/index.ts）同时导出基于dagre与ELK两套布局算法的实现，并额外导出GroupLayoutOption、ResizeGroupMode等分组布局配置类型（实现在 packages/layout/src/utils/groupLayout.ts）。
@logicflow/engine（packages/engine/package.json）：独立于编辑器的执行引擎，负责加载图数据并在浏览器端按流程执行，下文"自执行引擎"一节详述。
@logicflow/react-node-registry与@logicflow/vue-node-registry：分别提供 React / Vue 生态的节点注册与渲染封装。

此外，仓库还提供了多个可直接运行的示例工程（examples/），例如feature-examples（功能示例）、engine-browser-examples、next-app（Next.js 集成）、vue3-app（Vue 3 集成）等，可作为快速验证与参考。

安装与工程环境

环境要求

根据根目录 package.json 的engines字段，本地开发要求：

Node.js>= 16.0.0
pnpm>= 9.0.0（且项目通过preinstall: npx only-allow pnpm强制使用 pnpm）

对于普通业务项目，使用任意主流包管理器均可安装发布到 npm 的产物。

安装命令

# npm $ npm install @logicflow/core @logicflow/extension --save # yarn $ yarn add @logicflow/core @logicflow/extension # pnpm $ pnpm add @logicflow/core @logicflow/extension

需要说明的是：

最简场景下仅安装@logicflow/core即可渲染画布；@logicflow/extension按需安装以启用官方插件。
@logicflow/core在postinstall阶段会执行node scripts/postinstall-ai-prompt.js（见 packages/core/package.json），在终端打印一段可复制给 AI Agent 的规则，详见下文"AI 编程支持"。
需要自动布局时，再额外安装@logicflow/layout；需要无代码执行时，可选用@logicflow/engine。

从源码构建（开发贡献）

如果你是希望在仓库内二次开发，README 给出了本地开发流程：

# 安装项目依赖（prepare 会自动执行 build:all，见根 package.json） $ pnpm install # 终端 1：监听 packages，热更新 es/lib $ pnpm run dev # 终端 2：启动 feature-examples 演示项目 $ cd examples/feature-examples && pnpm dev

根目录 package.json 中的build系列脚本借助 turbo 并行构建所有子包：build:cjs（CommonJS）、build:esm（ES Module）、build:umd（Rollup 打包）与build:docs（复制 AI 文档，见 scripts/copy-ai-docs.js）。

快速上手：渲染第一张流程图

README 提供了一段完整的、可复制运行的示例，展示了 LogicFlow 最核心的两步：准备图数据 → 实例化并渲染。

1. 准备容器 DOM

<!-- LogicFlow 容器 DOM --> <div id="container"></div>;

2. 准备图数据

// 准备数据 const data = { // 节点 nodes: [ { id: '21', type: 'rect', x: 100, y: 200, text: 'Rect Node', }, { id: '50', type: 'circle', x: 300, y: 400, text: 'Circle Node', }, ], // 边 edges: [ { type: 'polyline', sourceNodeId: '50', targetNodeId: '21', }, ], };

3. 实例化并渲染

// 渲染画布 const lf = new LogicFlow({ container: document.querySelector('#container'), width: 700, height: 600, }); lf.render(data);

数据模型语义说明

对照 packages/engine/src/index.ts 中的类型定义（NodeData/EdgeData/GraphConfigData），可以更准确地理解上述数据结构：

节点（nodes）：每个节点至少包含id（唯一标识）、type（节点类型，如内置的rect、circle）、x/y（画布坐标）、text（节点文本，可以是字符串或{ x, y, value }对象），可选zIndex与properties。
边（edges）：核心字段是sourceNodeId与targetNodeId（起止节点）；type不传时使用 LogicFlow 内部默认值polyline（折线）；可选sourceAnchorId/targetAnchorId指定锚点、startPoint/endPoint指定起止点、pointsList提供折线途经点、text提供边文本。
lf.render(data)：将整份图数据一次性渲染到画布。渲染之后，拖拽、连线、框选、缩放等基础交互即开箱可用——这正是 README 所说的"提供了一系列流程图交互、编辑所必需的功能"。

AI 编程支持：让 AI Agent 学会"先查官方文档"

这是 README 中一个非常贴合当下开发趋势的特性：LogicFlow 将官方文档随 npm 包一起发布，为 AI 编程工具提供本地可检索的知识库。

版本前提

@logicflow/core@2.2.2及以上版本会包含随包发布的文档（当前仓库 core 版本为2.2.4，见 packages/core/package.json）。安装或升级之后，把下面这段提示词复制给你的 AI Agent，它就会在实现 LogicFlow 功能前先查阅本地官方文档。

可复制的 Agent 规则提示词

<!-- BEGIN:logicflow-agent-rules --> # LogicFlow Agent Rules LogicFlow documentation is available at: - `node_modules/@logicflow/core/dist/docs/` Package roles: - `@logicflow/core`: core graph editor runtime, including canvas, nodes, edges, models, events, rendering, themes, and basic interactions. - `@logicflow/extension`: official plugins for common product features. - `@logicflow/layout`: official layout plugins for automatic graph layout. The docs for `@logicflow/extension` and `@logicflow/layout` are included under: - `node_modules/@logicflow/core/dist/docs/tutorial/extension/` Before implementing any LogicFlow feature, check the local docs first to see whether LogicFlow already provides a built-in, extension, or layout capability. If it does, prefer the documented official capability instead of reimplementing it from scratch. If an official package is needed but not installed, ask the user before installing it. <!-- END:logicflow-agent-rules -->

升级@logicflow/core后，记得把最新版的提示词重新提供给 Agent，以保证它始终拿到与当前版本匹配的文档位置与规则。

本地文档从哪来：发布链路

这份文档并不是手工塞进 npm 包的，而是有一套完整的构建链路，可以从源码确认：

文档源：官网文档位于 sites/docs/docs/，包括tutorial/（教程）与api/（API 参考）两大部分，并且同时保留中英文版本（.zh.md+.en.md）。
复制脚本：根目录执行pnpm build:docs会运行 scripts/copy-ai-docs.js。该脚本先清空packages/core/dist/docs/，再把tutorial/与api/整体复制进去，并自动生成一份index.md文档入口索引（指向 get-started 教程、API 参考与 extension 插件指南），最后统计复制的 markdown 文件数量。
随包发布：@logicflow/core的files字段包含dist、es、lib与scripts（见 packages/core/package.json），因此dist/docs/会随包发布到 npm，用户安装后即可在node_modules/@logicflow/core/dist/docs/读到。
不复制的内容：article/（面向读者的技术文章）与release/（版本发布说明）不进入 AI 文档目录，保证 Agent 拿到的是聚焦"怎么用"的高信噪比内容。

postinstall 提醒：安装即提示

用户执行npm install @logicflow/core时，postinstall钩子会执行 packages/core/scripts/postinstall-ai-prompt.js，在终端打印一段提醒与上述 Agent 规则。该脚本的实现细节（与 docs/superpowers/specs/2026-05-11-postinstall-ai-prompt-reminder-design.md 中描述的设计一致）值得注意：

输出结构分三段：上部是提醒区（"请将下方的规则复制给你的 AI Agent"），中间用─分割线隔开，下部是到的纯规则文本，方便用户从 BEGIN 到 END 一次复制、不夹带提醒句。
ANSI 样式按环境降级：shouldUseAnsi()会检查process.stdout.isTTY、NO_COLOR环境变量与TERM=dumb；仅当终端支持时才使用加粗 + 黄底黑字（\x1b[1m\x1b[43m\x1b[30m）突出提醒区，在 CI / 管道等非 TTY 环境自动降级为纯文本，避免污染日志。
零新增运行时依赖：整个提醒输出没有引入boxen、chalk等依赖（设计文档明确将"不新增依赖"列为验收项之一）。

为什么这样设计：与 Next.js 的对比

根据 docs/superpowers/specs/2026-04-27-ai-docs-integration-design.md，这一机制参考了 Next.js 的做法——Next.js 16.2 起在 npm 包中附带完整文档，让本地 AI 工具自动理解框架用法。但二者场景不同：

Next.js 用户通常由create-next-app脚手架创建项目，脚手架会把AGENTS.md模板复制到项目根目录，AI 工具读取AGENTS.md后自然找到node_modules/next/dist/docs/。
LogicFlow 用户通常在现有项目中直接安装，没有脚手架介入，因此改用postinstall 输出 prompt的方式引导：让用户手动把规则粘贴给 AI Agent，Agent 便记住了"文档在哪、各包职责是什么、动手前先查文档"。

这一差异也解释了为什么@logicflow/extension和@logicflow/layout不单独发布文档、也没有 postinstall 钩子——它们的文档统一放在@logicflow/core/dist/docs/中，方便 AI 一次性获取完整知识；即使某用户只装了 core，Agent 也能根据文档提示"如需 MiniMap 请安装@logicflow/extension"，而不是从零造轮子。

生态能力纵深：执行引擎与数据转换

README 提到的"自执行引擎"与"数据可转换"是整个生态的两大亮点，下面结合仓库源码做展开说明。

自执行引擎（@logicflow/engine）

执行引擎位于 packages/engine/src/index.ts，导出Engine类，支持在浏览器端加载图数据并按流程执行，为"无代码执行"提供了一种落地思路。其核心 API 与流程为：

构造：new Engine(options?)，options.debug为true时会挂载Recorder（执行记录器）；构造时默认注册StartNode（开始节点）与TaskNode（任务节点）两种内置节点。
注册自定义节点：engine.register({ type, model })可将自定义节点类注册进nodeModelMap。
加载图数据：engine.load({ graphData, startNodeType, globalData })将图数据交给FlowModel构建可执行模型，默认起始节点类型为'StartNode'。
执行：await engine.execute(param?)触发流程执行，允许多次调用；engine.resume(param)支持中断后的流程恢复（interrupted是ActionStatus枚举之一，见同文件类型定义）。
记录与查询：engine.getExecutionList()/getExecutionRecord(executionId)用于查询执行历史；setCustomRecorder(recorder)允许把记录存储替换为自定义持久化实现（默认浏览器用sessionStorage，Node.js 用内存存储）。

引擎的完整能力（含中断恢复、条件执行等）在 packages/engine/test/ 下有对应测试，如07_interruptedAndResume.test.ts、03_condition.test.ts，可作进一步研读入口。

数据可转换（BPMN / Turbo 适配器）

"数据可转换"指 LogicFlow 图数据可以与后端执行引擎常用的数据结构互相转换，仓库在 packages/extension/src/ 中提供了两类官方适配器：

BPMN 适配器：bpmn-adapter（packages/extension/src/bpmn-adapter/index.ts）负责 LogicFlow 数据与 BPMNJSON之间的双向转换；bpmn-elements-adapter（packages/extension/src/bpmn-elements-adapter/index.ts）负责 LogicFlow 数据与 BPMNXML的双向转换，二者都包含json2xml/xml2json等转换实现。
Turbo 适配器：turbo-adapter（packages/extension/src/turbo-adapter/index.ts）支持与 Turbo 执行引擎数据结构的互转。

这类适配器在 packages/extension/test/ 下拥有成套测试（如bpmn-adapter、bpmn-elements-adapter目录），是理解数据转换细节的好素材。在业务中，这意味着你可以用 LogicFlow 做前端可视化编辑，再把图数据交给 BPMN/Turbo 等后端执行引擎去驱动业务流程。