# flow-editor

**Repository Path**: NBegin/flow-editor

## Basic Information

- **Project Name**: flow-editor
- **Description**: 基于 Vue 3 + Vite + process-editor + Ant Design Vue 的可视化流程设计器示例工程。

本工程同时是 process-editor 核心库抽象层的参考实现：AI 能力（src/ai/）、实时协同（src/collab/）等可替换能力的具体实现均在此提供，通过继承核心库抽象基类注入，便于二次开发参考。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-11-06
- **Last Updated**: 2026-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Process Designer

基于 Vue 3 + Vite + process-editor + Ant Design Vue 的可视化流程设计器示例工程。

本工程同时是 process-editor 核心库**抽象层的参考实现**：AI 能力（`src/ai/`）、实时协同（`src/collab/`）等可替换能力的具体实现均在此提供，通过继承核心库抽象基类注入，便于二次开发参考。

#### [在线演示](https://flow-editor.pages.dev/)

---

## 功能特性

### 核心功能

- **可视化流程设计**：拖拽式节点添加和连接，直观的流程画布操作
- **丰富节点类型**：支持开始事件、结束事件、用户任务、服务任务、脚本任务、网关节点等 BPMN 2.0 标准节点
- **灵活属性配置**：支持节点属性的详细配置和自定义属性面板
- **流程管理**：支持流程导入导出（JSON / BPMN 2.0 XML）、流程验证、版本管理
- **多语言支持**：内置中英文，完整的国际化架构，支持自定义语言扩展
- **生命周期事件**：提供 BEFORE_INIT、AFTER_INIT、AFTER_LOAD、BEFORE_ADD_NODE、AFTER_ADD_NODE、SELECTED_NODE 等丰富事件监听机制
- **自定义扩展**：支持自定义节点（HtmlTask + Vue 组件）、自定义属性面板（tabConfig）、自定义字段类型、自定义上下文菜单
- **工具栏自定义**：支持动态配置工具栏按钮，自定义图标、文本、点击行为和权限控制
- **画布交互**：支持右键菜单、拖拽缩放、小地图导航、网格显示、坐标显示

### 高级功能

- **AI 智能助手（五层抽象）**：基于核心库 `AIAdvisor` 抽象层实现 L1 生成流程 / L2 节点推荐 / L3 自然语言修改 / L4 校验解释 / L5 优化报告，提供 OpenAI、Mock 两种客户端实现
- **实时协同**：基于核心库 `CollaborationAdapter` 抽象层实现 BroadcastChannel（同源标签页，零依赖）与 Yjs CRDT（多端强一致）两种适配器，支持在线状态、光标 awareness、操作广播
- **冲突解决面板**：基于核心库 `ConflictResolverPanel` 组件实现人工冲突解决 UI
- **Element Template**：声明式节点模板注册，沉淀业务节点规范（审批、会签、或签等）
- **BPMN Lint**：10 条 bpmnlint 风格语义规则（label-required、single-start-event 等），支持 error/warning/off 三级级别与运行时动态调整
- **DMN 决策引擎**：FEEL 表达式求值、命中策略（唯一/首条/任意/优先/收集）、决策表校验
- **Agent 编排**：AgentStateMachine 状态机、Guardrail 护栏（正则注入检测、Prompt 注入检测、JSON Schema 输出校验）、AgentOrchestrator 多步编排
- **出码引擎**：从流程 IR 生成 H5 / 小程序 / 移动端页面模型
- **连接器市场**：REST / Kafka / Webhook 等内置连接器模板与执行引擎
- **MCP 双向能力**：MCPClient / MCPServer 实现 Model Context Protocol，设计器能力暴露为 MCP 工具
- **流程挖掘**：事件日志采集、变体分析、瓶颈分析、热力图
- **版本治理**：版本图、修订级 diff、分支/合并冲突检测
- **方言插件**：Flowable BPMN / Freeform JSON 序列化方言
- **安全表达式**：基于 expr-eval 的安全表达式引擎，替代 eval
- **流程模拟**：支持流程模拟运行，可视化展示执行路径，支持单步调试和断点
- **自动布局**：基于 dagre 的分层布局算法，支持 TB / BT / LR / RL / GRID 多种布局模式
- **模板库**：提供丰富的预置流程模板，涵盖请假审批、报销、采购等常见业务场景
- **版本管理**：支持流程版本自动保存、历史记录、版本对比和版本回滚
- **高级校验**：支持基础校验和自定义规则校验，检查流程完整性和正确性
- **全局搜索**：按节点名称或类型快速搜索，点击结果自动定位并选中画布节点
- **画布设置**：支持网格显示、对齐辅助线、缩放比例等参数配置
- **性能优化**：视口剔除（ViewportCulling）+ 虚拟小地图（VirtualMinimap）支持千节点流畅渲染，内置 100/500/1000 节点压测
- **快捷键**：提供保存、撤销、重做、删除、全选等常用快捷键

---

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | ^3.5 | 渐进式 JavaScript 框架 |
| Vite | ^8.0 | 下一代前端构建工具 |
| TypeScript | ~5.8 | 类型安全 |
| Ant Design Vue | ^4.2 | UI 组件库 |
| process-editor | 1.0.38 | 流程设计器核心库（抽象层 + 视图层） |
| vue-i18n | ^9.14 | 国际化 |
| Pinia | ^3.0 | 状态管理 |
| Vue Router | ^4.5 | 路由管理 |
| dagre | ^0.8 | 自动布局算法 |
| axios | ^1.11 | HTTP 请求（后端 API 集成） |
| Less | ^4.4 | CSS 预处理器 |

---

## 项目结构

```
src/
├── ai/                        # AI 抽象层实现（核心库 AIAdvisor 参考实现）
│   ├── index.ts               # AI 能力入口：构造注册表、注册顾问
│   ├── DefaultAIAdvisor.ts    # 默认 AI 顾问（L1-L5 实现，无 client 回退本地模板）
│   ├── OpenAIAIClient.ts      # OpenAI 客户端（chat/chatStream/embed）
│   ├── MockAIClient.ts        # Mock 客户端（离线调试）
│   └── flowTemplates.ts       # AI 流程生成模板
├── agent/                     # Agent 编排实现（核心库 AgentOrchestrator 参考实现）
│   ├── index.ts               # Agent 能力入口
│   └── DefaultAgentOrchestrator.ts # 默认 Agent 编排器
├── collab/                    # 协同抽象层实现（核心库 CollaborationAdapter 参考实现）
│   ├── index.ts               # 协同能力入口：注册 BroadcastChannel / Yjs 适配器
│   ├── BroadcastChannelAdapter.ts  # 同源标签页协同（零依赖）
│   └── YjsCollaborationAdapter.ts  # Yjs + y-websocket CRDT 协同（动态加载）
├── codegen/                   # 出码引擎实现（核心库 CodegenEngine 参考实现）
│   └── index.ts               # 出码能力入口
├── connector/                 # 连接器市场实现（核心库 ConnectorManager 参考实现）
│   └── index.ts               # 连接器能力入口
├── dmn/                       # DMN 决策引擎实现（核心库 DecisionEngine 参考实现）
│   └── index.ts               # DMN 能力入口
├── formDesigner/              # 表单设计器实现（核心库 FormNodeBindingManager 参考实现）
│   └── index.ts               # 表单设计器入口
├── mcp/                       # MCP 双向能力实现（核心库 MCPClient/MCPServer 参考实现）
│   ├── index.ts               # MCP 能力入口
│   ├── HttpMCPClient.ts       # HTTP 传输的 MCP 客户端
│   └── designerBindings.ts    # 设计器 MCP 工具绑定
├── processMining/             # 流程挖掘实现（核心库 ProcessMiner 参考实现）
│   └── index.ts               # 流程挖掘入口
├── components/                # 组件
│   ├── toolbar.vue            # 工具栏
│   ├── AIAssistant.vue        # AI 智能助手
│   ├── AIFloatingButton.vue   # AI 悬浮按钮
│   ├── AutoLayoutPanel.vue    # 自动布局面板
│   ├── CanvasSettings.vue     # 画布设置
│   ├── CollaborationBar.vue   # 实时协作栏
│   ├── ExpressionEditor.vue   # 表达式编辑器
│   ├── HelpDrawer.vue         # 帮助文档抽屉
│   ├── IntroductionDrawer.vue # 介绍抽屉
│   ├── JsonEditorModal.vue    # JSON 编辑器弹窗
│   ├── MdImportModal.vue      # Markdown 导入弹窗
│   ├── MiniMap.vue            # 小地图
│   ├── OnboardingTour.vue     # 新手引导
│   ├── ProcessManagerDrawer.vue # 流程管理抽屉
│   ├── SearchPanel.vue        # 搜索面板
│   ├── ShortcutsPanel.vue     # 快捷键面板
│   ├── SimulationPanel.vue    # 流程模拟面板
│   ├── SimulationReport.vue   # 模拟报告
│   ├── SmartRecommendation.vue# 智能推荐
│   ├── TemplateSelector.vue   # 模板选择器
│   ├── ValidationPanel.vue    # 校验面板
│   ├── VersionCompare.vue     # 版本对比
│   ├── VersionHistoryDrawer.vue# 版本历史
│   ├── customNodes/           # 自定义节点
│   │   ├── ApprovalNode.vue   # 审批节点
│   │   ├── NoticeNode.vue     # 通知节点
│   │   ├── ScriptNode.vue     # 脚本节点
│   │   ├── customHtml.vue     # HTML 自定义节点
│   │   ├── customDataV.vue    # DataV 数据可视化节点
│   │   └── customDataV2.vue   # DataV 数据可视化节点 v2
│   └── customFields/          # 自定义字段
│       └── field-switch.vue   # 开关字段
├── composables/               # 组合式函数
│   ├── useProcessEditor.js    # 流程编辑器核心逻辑
│   ├── useProcessApi.js       # 后端 API 调用封装
│   ├── useSimulation.js       # 流程模拟
│   ├── useVersionHistory.js   # 版本历史管理
│   └── useFetch.ts            # 数据请求封装
├── config/                    # 配置
│   ├── toolbarButtons.js      # 工具栏按钮配置
│   ├── tabConfig.js           # 属性面板 Tab 配置
│   ├── customTabConfig.js     # 自定义 Tab 配置
│   ├── fieldTypes.js          # 字段类型配置
│   ├── nodeTypeRegistry.js    # 节点类型注册表
│   ├── nodePropertyPresets.js # 节点属性预设
│   └── validationRules.js     # 校验规则配置
├── data/
│   └── flowTemplates.js       # 流程模板数据
├── mock/                      # Mock 数据
│   ├── data.json              # 静态数据源
│   ├── staticDataSource.json  # 静态数据源（中文）
│   ├── staticDataSource.en.json# 静态数据源（英文）
│   ├── customNodesData.json   # 自定义节点数据
│   └── demos/                 # 各 demo 的 Mock 数据
├── utils/                     # 工具函数
│   ├── validate.js            # 基础校验
│   ├── advancedValidate.js    # 高级校验
│   ├── bpmnConverter.js       # BPMN XML 转换
│   ├── simulationEngine.js    # 模拟引擎
│   ├── simulationRecorder.js  # 模拟录制
│   ├── simulationVariables.js # 模拟变量
│   ├── recommendationEngine.js# 推荐引擎
│   ├── aiFlowGenerator.js     # AI 流程生成
│   ├── collaborationMock.js   # 协同 Mock
│   ├── versionCompare.js      # 版本对比
│   ├── clipboard.js           # 剪贴板
│   ├── notification.js        # 通知
│   ├── request.ts / axios.ts  # 请求封装
│   └── i18nHelper.js          # 国际化辅助
├── stores/                    # Pinia 状态
│   ├── i18n.ts                # 国际化状态
│   └── counter.ts             # 计数器示例
├── locales/                   # 国际化
│   ├── zh/                    # 中文语言包
│   └── en/                    # 英文语言包
├── views/                     # 页面视图
│   ├── index.vue              # 主页面
│   └── demos/                 # 示例页面 (d0 ~ d11)
└── router/                    # 路由配置
```

---

## 快速开始

### 前端

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npm run preview
```

### 后端 API（可选）

后端工程位于 `./api/`，基于 Spring Boot 3 + MyBatis-Plus + MySQL，提供 BPMN 流程引擎 RESTful API。以下命令均在 `flow-editor/` 目录下执行：

```bash
# 启动后端（默认端口 8080）
npm run dev:api

# 打包后端 jar
npm run build:api

# 同时启动前后端（前后端联调）
npm run dev:all
```

> 后端启动后会自动执行 `./api/src/main/resources/db/schema.sql` 创建表结构。前端 Vite 已配置代理，`/api` 请求自动转发到 `http://localhost:8080`。

### 示例页面

启动后访问根路径可看到示例导航，包含 d0 ~ d11 共 12 个演示：

| Demo | 主题 | 说明 |
|------|------|------|
| d0 | 基础流程设计器 | 完整功能，自定义节点、属性配置 |
| d1 | 自定义节点 | HTML 自定义节点 |
| d2 | 数据可视化节点 | 集成 DataV 组件 |
| d3 | 复杂流程 | 复杂业务流程设计与配置 |
| d4 | 多语言 | 多语言切换 |
| d5 | 高级属性配置 | 复杂节点属性配置 |
| d6 | 流程导入导出 | JSON / BPMN 导入导出 |
| d7 | 生命周期钩子 | 生命周期事件扩展 |
| d8 | 自定义工具栏 | 工具栏按钮自定义 |
| d9 | AI 能力 | 五层 AI 抽象：生成/推荐/校验解释/优化报告 |
| d10 | 协同能力 | 加入房间/在线用户/操作广播/awareness |
| d11 | Element Template + 性能 | 模板注册、千节点压测、视口剔除 |

---

## 工具栏功能

| 分组 | 功能 | 快捷键 |
|------|------|--------|
| 文件 | 保存、导入 JSON、导出 JSON、导入 BPMN、导出 BPMN | Ctrl+S |
| 编辑 | 撤销、重做、清空、自动布局 | Ctrl+Z / Ctrl+Y |
| 视图 | 放大、缩小、适应画布、搜索节点 | Ctrl+F |
| 运行 | 流程校验、流程模拟 | - |
| AI | AI 助手、模板库 | - |
| 更多 | 发布流程、快捷键、版本历史、介绍、帮助 | - |

---

## 效果图

### 流程设计主界面

![流程设计主界面](public/imgs/image.png)

### 流程属性配置

![流程属性配置](public/imgs/image1.png)

### 节点属性配置

![节点属性配置](public/imgs/image2.png)

### 自定义节点 / 自定义属性

![自定义节点与自定义属性](public/imgs/image3.png)

### 图形属性配置

![图形属性配置](public/imgs/image4.png)

---

## 自定义开发

### 自定义节点

```vue
<!-- ApprovalNode.vue -->
<template>
  <div class="approval-node">
    <img :src="icon" alt="" />
    <span>审批任务</span>
  </div>
</template>
```

```js
// 在页面中注册
const customNodes = [
  {
    bpmnType: 'HtmlTask',
    bizType: 'approval',
    text: '审批节点',
    name: '审批节点',
    component: ApprovalNode,
    width: 160,
    height: 80,
    resizable: true,
  },
]
```

### 生命周期事件

```js
const { registerLifecycleHook } = useProcessEditor(editorRef)

registerLifecycleHook('AFTER_INIT', (canvas) => {
  console.log('编辑器初始化完成')
})

registerLifecycleHook('AFTER_ADD_NODE', (figure) => {
  console.log('节点已添加:', figure.id)
})
```

### 工具栏按钮配置

```js
import { toolbarButtons } from '@/config/toolbarButtons'

const buttons = toolbarButtons.getDesignButtons(i18nMessages)
```

### AI 能力抽象层接入

`src/ai/` 是核心库 `AIAdvisor` 抽象层的参考实现。通过 `initAI()` 构造注册表并注册 `DefaultAIAdvisor`，可传入 `OpenAIAIClient` 或 `MockAIClient` 激活五层 AI 能力：

```ts
import { initAI } from '@/ai'

// 初始化 AI 注册表（默认注册 DefaultAIAdvisor，无 client 时回退本地模板）
const registry = initAI()

// 注入设计器，供 recommendNext / analyzeOptimization 使用
registry.getActive()?.setDesigner(editorRef.value.designer)

// 调用 AI 能力
const result = await registry.getActive()?.generateFlow('帮我生成一个请假审批流程')
```

> 如需接入 OpenAI，参考 `src/ai/OpenAIAIClient.ts`；离线调试使用 `src/ai/MockAIClient.ts`。完整示例见 `views/demos/d9.vue`。

### 协同能力抽象层接入

`src/collab/` 是核心库 `CollaborationAdapter` 抽象层的参考实现。默认使用 `BroadcastChannelAdapter`（同源标签页协同，零依赖），Yjs 协同通过动态加载 `YjsCollaborationAdapter` 接入：

```ts
import { initCollaboration } from '@/collab'

// 初始化协同管理器（默认注册 BroadcastChannelAdapter）
const manager = initCollaboration()

// 注入设计器并连接房间
manager.getAdapter()?.setDesigner(editorRef.value.designer)
await manager.getAdapter()?.connect({ roomId: 'demo-room-001' })
```

> Yjs CRDT 协同为可选项，运行时动态加载 `yjs` + `y-websocket`，未安装不影响构建。完整示例见 `views/demos/d10.vue`。

---

## 浏览器兼容

如需本地开发调试跨域请求，可启动 Chrome 并禁用 Web 安全策略：

```bash
# Windows
chrome.exe --disable-web-security --user-data-dir="C:/ChromeDevSession"

# macOS
open -n -a "Google Chrome" --args --disable-web-security --user-data-dir="/tmp/chrome_dev_test"
```

---

## 后端集成

### 数据库连接（MySQL）

后端默认连接本地 MySQL，建议使用 Sequel Ace 等客户端连接。注意端口为 **3306**（非 3386）：

| 字段 | 正确值 |
|------|--------|
| Host | 127.0.0.1 |
| Username | root |
| Password | （留空） |
| Database | process_editor |
| Port | 3306 |

### 数据库准备

```sql
CREATE DATABASE process_editor DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

启动后端时会自动执行 `./api/src/main/resources/db/schema.sql` 创建表结构。

### API 模块概览

| 模块 | 基础路径 | 功能 |
| ---- | -------- | ---- |
| 流程定义 | `/api/v1/process-definitions` | 流程定义 CRUD、BPMN XML 获取、流程校验 |
| 流程实例 | `/api/v1/process-instances` | 启动/取消/挂起/激活流程实例 |
| 任务管理 | `/api/v1/tasks` | 任务查询、完成、委派、签收 |
| 历史查询 | `/api/v1/history` | 历史实例、任务、活动查询 |

完整 OpenAPI 3.0.3 契约见 `docs/api-contract/openapi.yaml`。

---

## 相关文档

| 文档 | 路径 | 说明 |
|------|------|------|
| 运行时架构 | `docs/runtime-architecture.md` | 核心库运行时架构设计说明 |
| 使用指南 | `docs/guide/` | 安装、快速开始、基础用法、节点类型、属性配置、生命周期、BPMN XML、国际化 |
| 设计系统 | `docs/design-system/` | 颜色、字体、组件、无障碍设计规范 |
| API 文档 | `docs/api/` | 组件、组合式函数、校验器、错误处理、ProcessDesigner API |
| API 契约 | `docs/api-contract/openapi.yaml` | 后端 OpenAPI 3.0.3 接口契约 |
| 变更记录 | `docs/changelog.md` | 版本变更记录 |

npm install --legacy-peer-deps

yarn cache clean
rm -rf node_modules yarn.lock
yarn install --ignore-engines

---

## 开源协议

本仓库以「**源码可见 + 研究学习**」方式向社区开放，**并非传统 OSI 开源许可证**，完整条款见 [`LICENSE`](./LICENSE)。核心约定：

- ✅ **允许**：个人学习、技术研究与探讨、阅读源码、Fork 与本地二次开发参考（须保留版权与许可声明）。
- ❌ **禁止**：未经授权将本仓库全部或任何部分（含对 process-editor 核心库抽象层的参考实现、衍生作品）用于**任何商业用途**（商业产品、SaaS、付费系统、对外收费培训等）。
- 💼 **商用授权**：任何商业用途须事先**购买商业授权**并取得书面许可。请联系作者获取授权方案（见下方「商业合作」）。

> 我们希望这份代码能成为开发者研究流程引擎、BPMN 设计与 Vue 3 工程实践的优质参考素材，欢迎在合规范围内自由学习与交流。

---

## 商业合作与授权

如果你希望将本设计器或其核心能力用于商业产品、企业项目或付费服务，我们提供以下合作方式：

- **商业授权**：按使用规模与场景提供商业授权，授予合法商用权利。
- **企业定制开发**：基于本仓库进行私有化部署、定制节点/属性面板、对接自有 BPM 引擎（Flowable、Camunda、自研等）。
- **技术咨询与培训**：流程引擎架构设计、AI 编排、实时协同（CRDT）、BPMN Lint 等专项支持。


联系方式：

- 邮箱：`<nbreak@126.com>`

---

## 参与贡献

我们非常欢迎并鼓励社区参与，一起把这套流程设计器做得更好！

- ⭐ **Star 支持**：在仓库主页点个 Star，让更多开发者发现这个项目。
- 🐛 **Issue 反馈**：遇到 Bug 或有功能建议，欢迎提 Issue（尽量附复现步骤与截图）。
- 🔧 **Pull Request**：欢迎提交修复与增强；请保持代码风格一致并附必要的说明。
- 💬 **技术讨论**：关于架构、BPMN 规范、Vue 3 实践、AI/协同方案等话题，欢迎在 Issue 或讨论区交流。
- 📚 **文档完善**：使用指南、设计系统、API 文档的勘误与补充同样重要。

> 无论是改一个错别字，还是贡献一个完整功能模块，每一份参与都会被认真对待。让我们一起推动开源流程引擎生态的发展。