process-editor

《在混沌中寻找清醒，于深渊中仰望星空》

process-editor

process-editor 是一款基于 Vue3 和 draw2d_native 的流程编排工具，可以帮助开发者快速构建流程图编辑器，适用于工作流引擎、业务流程管理等场景。项目提供完整的前后端一体化方案：前端为可视化流程设计器组件库，后端为基于 Spring Boot 3 + MyBatis-Plus + MySQL 的 BPMN 流程引擎 RESTful API。

自 v1.0.36 起，核心库升级为分层纯净架构（npm 当前版本 v1.1.0）：核心层（packages/）只定义接口契约与抽象基类，不引入任何具体 LLM SDK、协同引擎或重量级第三方依赖；AI 能力、实时协同、Element Template 等具体实现均放在 example/ 中作为第三方引用，通过 DI 容器与抽象层注入核心库。这一设计确保核心库纯净、轻量、可独立发布，同时保留无限的扩展空间。

大厂流程编排设计方案深度分析与对比

1. 主流大厂流程编排方案概述

1.1 阿里巴巴 CompileFlow

• 核心设计理念：编译执行的高性能流程编排引擎
• 技术架构：基于DAG（有向无环图）数据结构，将流程定义转换为优化的Java代码，动态编译为字节码直接执行
• 性能特点：原生Java级别的极致性能，无解释器开销
• 适用场景：高性能、高并发的业务流程场景
• 核心优势：编译执行、轻量级、易扩展

1.2 字节跳动 FlowGram

• 核心设计理念：AI时代的可视化工作流引擎
• 技术架构：面向AI Bot开发的可视化流程编排，支持多模态输入输出
• 性能特点：图形化设计、低代码开发、快速集成
• 适用场景：AI Bot开发、自动化流程、智能服务编排
• 核心优势：可视化设计、AI能力集成、易用性强

1.3 传统工作流引擎对比（Activiti/Flowable）

• 核心设计理念：基于BPMN 2.0标准的完整工作流解决方案
• 技术架构：重量级架构，包含流程引擎、任务引擎、历史引擎等多个组件
• 性能特点：功能全面但性能相对较低
• 适用场景：复杂业务流程、审批流、企业级BPM系统
• 核心优势：标准兼容、功能全面、成熟稳定

2. process-editor 架构设计

2.1 核心架构（分层纯净架构）

核心库采用「纯净核心 + 抽象层 + 第三方实现」的分层设计：核心层只暴露接口契约与抽象基类，所有可替换能力（AI、协同、命令栈、模板、序列化）均通过 DI 容器注入，确保核心库零三方依赖、可独立发布。

┌─────────────────────────────────────────────────────────────────┐
│                       example（第三方实现层）                     │
│   AI: OpenAIAIClient / DefaultAIAdvisor / MockAIClient          │
│   协同: BroadcastChannelAdapter / YjsCollaborationAdapter       │
└──────────────────────────────┬──────────────────────────────────┘
                               │ 注入（继承抽象类 / 实现接口）
┌──────────────────────────────▼──────────────────────────────────┐
│                    抽象层（核心库 packages/core）                │
│  ┌────────────┬─────────────┬──────────────┬──────────────────┐ │
│  │ DI 容器    │ AI 抽象层    │ 协同抽象层    │ Element Template │ │
│  │DIContainer │AIAdvisor     │Collaboration │   Registry       │ │
│  │            │AIAdvisorReg  │Adapter/Mgr   │SchemaValidator   │ │
│  ├────────────┼─────────────┼──────────────┼──────────────────┤ │
│  │ 标准命令栈 │ BPMN 序列化  │ 视口剔除      │ Moddle 扩展      │ │
│  │CommandStack│XmlSerializer │ViewportCulling│ ModdleExtension │ │
│  └────────────┴─────────────┴──────────────┴──────────────────┘ │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                     ProcessEditor 视图层                         │
├─────────────────┬─────────────────┬─────────────────────────────┤
│   Vue3 组件     │  draw2d_native  │   流程配置系统               │
│   （响应式）     │  （渲染引擎）    │   （业务层）                 │
├─────────────────┼─────────────────┼─────────────────────────────┤
│ - 响应式状态    │ - 图形渲染       │ - 节点管理                  │
│ - 组件通信      │ - 事件处理       │ - 属性配置                  │
│ - 生命周期管理  │ - 画布操作       │ - 流程导入导出              │
└─────────────────┴─────────────────┴─────────────────────────────┘
                               │
                               ▼
                ┌───────────────────────────────┐
                │   核心设计器 ProcessDesigner   │
                │   生命周期 LIFE_CYCLE_EVENTS   │
                └───────────────────────────────┘

设计原则：核心库（packages/）不依赖任何具体 LLM SDK（如 openai）、协同引擎（如 yjs、y-websocket），这些仅作为 example/ 的可选依赖按需动态加载，未安装时核心库与构建产物不受影响。

2.2 技术栈

前端技术栈

后端技术栈

2.3 核心功能模块

3. 功能特性对比

4. 优势与不足分析

4.1 process-editor 优势

1. 基于Vue3技术栈：利用Vue3的响应式系统和组件化设计，提供现代化的开发体验
2. 分层纯净核心：核心库零三方依赖，AI/协同/模板等可替换能力通过抽象层 + DI 容器注入，可独立发布与复用
3. 轻量级架构：核心功能聚焦，易于集成和扩展
4. 可视化设计：直观的拖拽式设计，降低开发门槛
5. 自定义扩展性强：支持自定义节点、自定义属性、自定义字段、Element Template 模板
6. 前后端分离：前端专注于流程设计，后端专注于流程执行
7. AI能力集成：核心库定义五层 AI 抽象（L1 生成/L2 推荐/L3 修改/L4 校验解释/L5 优化），example 提供 OpenAI 实现
8. 实时协同能力：核心库定义协同抽象层，example 提供 BroadcastChannel 与 Yjs（CRDT）两种适配器
9. 丰富的模板库：预置企业级流程模板，覆盖多业务类别
10. 高级校验系统：死循环检测、不可达节点检测、流程完整性检查
11. 流程模拟运行：支持单步调试、断点、执行路径可视化
12. 自动布局：内置 dagre 分层布局算法，支持 TB/BT/LR/RL/GRID 多种布局模式
13. 大画布性能优化：内核具备视口剔除（ViewportCulling）能力，可显式开启以支撑千节点渲染（本仓默认未开启，见 4.2 节说明）

4.2 process-editor 不足

1. BPMN标准支持持续完善中：已支持大部分常用BPMN节点类型，仍在持续扩展
2. 后端是 Flowable 门面，不是自研引擎：example/api 基于 Spring Boot 3 + Flowable 7.1.0（flowable-spring-boot-starter-process）做了一层 REST 封装，流程部署/推进/任务/历史全部由 Flowable 承载；自建业务表只有 process_definition 一张（存元数据与原始 BPMN XML）。文档中若出现「未集成 Flowable」的旧表述，以本节为准。
3. 后端默认能力边界（重要，运行前请先读）：
   • 默认/demo profile 关闭了 Flowable 异步执行器（flowable.async-executor-activate=false）：定时器、边界定时事件、异步续行（flowable:async=true）、死信与自动重试都不会触发，等待时间语义的实例会永久停留在当前活动。生产请使用 application-prod.yml（已开启异步执行器与历史清理）。启动日志会打印实际生效的能力（EngineCapabilityReporter）。
   • 中国式审批已提供（TaskController）：任务「完成 / 委派 / 签收 / 取消签收」+ 转办 /transfer、退回 /return、驳回 /reject、撤回 /withdraw、加签 /add-signer、减签 /remove-signer、催办 /urge；实例「启动 / 挂起 / 激活 / 取消」、历史查询、流程定义 CRUD 与 BPMN 规范校验。
     • 语义边界：加签 = 追加候选办理人（或签/抢单），不是"必须全部通过"的并行会签；比例通过 / 一人否决 / 动态票数请用建模期 multiInstance + completionCondition 表达。
     • 超时升级仍依赖定时器：demo profile 关闭异步执行器时不会自动触发（见上一条）。
     • 上述端点尚未在真实 Flowable 实例上做端到端回归。
   • 实例卡死的补救入口：/api/v1/jobs/** 可查四类作业队列（可执行/定时器/死信/挂起）、看失败堆栈、手工触发定时器与死信重试（异步执行器关闭时的唯一推进手段）。
   • 每个请求带 X-Request-Id 关联 ID（可透传，响应头回传），日志按 traceId 串联；并暴露 /actuator/health、/actuator/prometheus（引擎能力与作业积压详见 /actuator/health 的 details）。
4. 前端仍存在「已实现但未接线」的能力（下列为已核实项，其余历史陈述已随修复更新）：
   • AI 助手已接线（见 3.1）：未配置 VITE_AI_API_KEY 时为离线模板模式，配置后走真实 LLM，失败自动回退本地生成器；MockAIClient 保留为纯离线客户端；
   • XmlSerializerRegistry + 40 余个序列化器构成「影子架构」，运行时仍走 bpmnXml.js；ModdleExtension 全局注册表零消费者；
   • 视口剔除（ViewportCulling）本仓未接线：全仓无 viewportCulling / setViewportCulling 引用，且内核 1.0.6 起默认不再自动启用（阈值默认 0）——需要显式开启并补性能回归；
   • DMN 缺 XML 导入导出：决策表编辑器与求值链路完整（BusinessRuleTask → dmn-decision-table.vue → FEEL 引擎），但决策表只存在于节点属性中，无法与 Camunda Modeler / Trisotech 等外部 DMN 建模器交换。

已更正的历史陈述（原先写作"尚未实现/尚未导出/未接线"，实际均已具备）：中国式审批 7 个动作（后端 + packages/api/client.ts + 示例 UI）、DMN 编辑器入口、YjsAdapter（经 process-editor/collab-yjs 子入口导出）、Agent 的 stepTimeoutMs/totalTimeoutMs/retry（已在 AgentOrchestrator 实现）、AI 助手到五层抽象的接线（见 3.1）。

5. 未来发展方向

1. 完善BPMN标准支持：逐步实现完整的BPMN 2.0标准支持
2. 深化AI能力：在五层 AI 抽象基础上引入大模型驱动的智能补全、异常预警、自动修复
3. 增强协同能力：扩展协同抽象层的冲突解决策略、离线编辑、操作回放
4. 增强后端引擎能力：在已集成的 Flowable 之上补齐中国式审批动作（加签/减签/退回/驳回/催办/转办）、job/死信管理面与指标可观测性

快速开始

前端安装

yarn install

使用

# npm
npm install process-editor
# yarn
yarn add process-editor
# pnpm
pnpm add process-editor

调试日志开关（默认关闭）

发布后不输出任何调试日志——组件注册中心、BPMN 语义层、校验/lint 等模块的调试输出 统一由中央开关控制；真实的失败仍然走 console.error（不受开关影响）。

需要排查时按优先级任选其一开启：

import { setDebugEnabled, isDebugEnabled, debugLog, debugWarnOnce } from 'process-editor';

setDebugEnabled(true);                      // 运行时开启
debugLog('MyPlugin', '节点数 %d', figures.length);
debugWarnOnce('MyPlugin:timer', 'MyPlugin', '重复注册，忽略本次');  // 同一 key 只提示一次

参数来源中，URL / localStorage 在首次读取后缓存（不刷新页面不会变化）；setDebugEnabled() 与 window.__PROCESS_EDITOR_DEBUG__ 每次实时判断。

发布构建的差异：yarn build:lib 会把 console.debug / info / log 替换为空函数 （见 vite.config.lib.ts 的 define），因此 npm 包产物里调试日志不可能输出； console.warn 级别的诊断（如"组件已注册，忽略本次注册"）仍会保留但受本开关控制。 需要完整调试日志时请使用开发构建。

后端启动

后端工程位于 example/api/ 目录，基于 Spring Boot 3 + MyBatis-Plus + MySQL。

环境要求

• Java 17+
• Maven 3.9+
• MySQL 8.x

数据库准备

CREATE DATABASE process_editor DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

启动命令

以下命令需在 example/ 目录下执行（后端 API 服务于示例项目）：

cd example

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

# 打包后端 jar
npm run build:api

# 同时启动前后端（需先安装依赖: npm install）
npm run dev:all

注意：根目录的 npm run build 等命令用于构建 packages/ 下的前端 npm 包库产物，与后端 API 无关。

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

在 main.ts 中引入：

import { createApp } from 'vue';
import App from './App.vue';
import ProcessEditor from 'process-editor';
import 'process-editor/styles';

const app = createApp(App);
app.use(ProcessEditor);
app.mount('#app');

在 App.vue 中使用：

<template>
  <ProcessEditor
    ref="editor"
    class="process-editor"
    :processData="processData"
    :tabConfig="null"
    :customNodes="customNodes"
    :customFields="customFields"
    :staticDataSource="staticDataSource"
  />
</template>

npm 包功能总览

子入口（package.json exports）

顶层导出 API 分组

import {
  // ── 组件 ──
  ProcessEditor, PropertyPanel, PropertyField, Branches,
  CommonIcons, DragDrawer, CommonToolBar, HistoryPanel, ConflictResolverPanel,
  // ── 安装与注册 ──
  // default export 为 installer（app.use(ProcessEditor) 即走它）
  registerGlobalProperties,
  // ── 核心工具类 ──
  ComponentRegistry, ConfigValidator, TemplateEngine, ConfigVersionManager,
  BpmnXml, EventBus, LIFE_CYCLE_EVENTS, createPersistence,
  PluginManager, DIContainer, StandardCommandStack, registerModdleExtension,
  // ── 能力抽象层（纯净接口契约，具体实现由第三方注入）──
  AIAdvisor, AIAdvisorRegistry,                    // AI 五层抽象（L1-L5）
  CollaborationAdapter, CollaborationManager,      // 实时协同
  VersionGraph, computeDiff, diffStats, detectDiffConflicts,  // 版本治理
  ProcessMiner, EventLogCollector, VariantAnalyzer, BottleneckAnalyzer, HeatmapBuilder,  // 流程挖掘
  DecisionEngine, FeelEvaluator, HitPolicyExecutor, DecisionTableValidator,  // DMN 决策表
  ProcessFormBinder, FieldValidator, FormNodeBindingManager,  // 表单-流程绑定
  CodegenEngine, IRToPageModel, H5Generator, MiniAppGenerator, MobileGenerator,  // 出码
  ConnectorManager, ConnectorExecutionEngine,      // 连接器
  AgentStateMachine, AgentOrchestrator,            // Agent 编排（含 Guardrail 护栏）
  MCPClient, MCPServer, MCPRegistry, designerTools,  // MCP 双向能力
  elementTemplateRegistry, TemplateSchemaValidator,  // Element Template
  DialectRegistry, flowableDialect, freeformJsonDialect,  // 序列化方言
  ViewportCulling, VirtualMinimap,                 // 大画布性能
  ExportPlugin,                                    // 内置导出插件
  // ── 配置与 i18n ──
  createConfig, getConfig, updateConfig,
  getLocale, setLocale, useLocale, useReactiveI18n, createGetLangText,
  // ── 横切工具 ──
  setDebugEnabled, debugLog,          // 调试开关
  validateProcess, registerValidator, // 流程校验
} from 'process-editor';

// 20 个 composables 聚合在命名空间下
import { useCore } from 'process-editor';
// useCore.useAutoSave / useSimulation / useVersionHistory / useTheme / ...

useCore composables 一览

核心功能

1. 可视化流程设计

• 拖拽式节点添加和连接
• 直观的流程画布操作
• 支持节点复制、粘贴、删除
• 支持画布缩放和平移
• 小地图导航
• 网格显示和对齐辅助线
• 坐标显示

2. BPMN节点支持

3. AI 智能助手（五层抽象能力）

核心库定义五层 AI 抽象（L1-L5），具体大模型实现由第三方注入，未注入时可回退本地模板：

• L1 自然语言生成流程：输入文字描述，自动生成 BPMN 流程（支持中英文）
• L2 智能节点推荐：根据当前节点类型和画布上下文，推荐下一个可能添加的节点
• L3 自然语言修改流程：通过自然语言指令修改已有流程
• L4 AI 校验解释：解释校验错误并给出修复建议
• L5 流程优化报告：分析流程瓶颈、SLA 违规、给出优化建议与评分
• AI 入口：由工具栏 AI 按钮打开助手抽屉（AIFloatingButton.vue 是可选的画布浮标入口，当前示例未挂载）
• 打字机效果：逐字输出回复，提升交互体验
• 流程预览：生成流程后可预览和一键应用

3.1 example 侧接线与配置（AI 助手走哪条路径）

example 已把 AI 助手接到五层抽象上（example/src/ai/assistantBridge.ts），按环境变量选择实现， 任何情况下都不会比原来的本地生成器更差：

# example/.env（三项都可留空）
VITE_AI_API_KEY=sk-xxx
VITE_AI_BASE_URL=https://api.openai.com/v1   # 可指向兼容网关
VITE_AI_MODEL=gpt-4

之所以要显式区分：core 的 AI 抽象只承诺与编辑器无关的 {nodes, lines}， 而导入画布需要图元结构。转换由 aiFlowGenerator.aiResultToProcessData 完成 （id 重发、坐标补全、分支条件映射），与本地生成器共用同一条导入路径。

4. 模板库

• 预置模板：覆盖人事、财务、行政、业务、技术、合规等多业务类别
• 分类筛选：按业务类别快速定位模板
• 关键词搜索：支持按模板名称和描述搜索
• 一键应用：选择模板后自动加载到画布
• 模板预览：应用前可预览模板结构和节点

5. 流程模拟

• 可视化执行路径：模拟运行时高亮显示执行路径
• 单步调试：逐步执行流程节点
• 断点功能：在指定节点设置断点暂停执行
• 模拟报告：生成模拟执行结果报告

6. 自动布局

• Sugiyama分层算法：自动优化节点布局
• 三种布局模式：层级布局、水平布局、网格布局
• 一键整理：快速整理混乱的流程图

7. 高级校验

• 死循环检测：DFS 环检测算法
• 不可达节点检测：发现无法到达的结束节点
• 网关分支检查：排他网关分支条件完整性
• 数据接线校验：条件表达式引用的变量是否真被某个节点生产（resultVariable），以及同一变量是否被多个节点重复生产（运行期"后写覆盖先写"，下游取值不确定）
• 孤立节点检测：发现没有连入或连出的节点
• 重复名称检测：同一流程中的同名节点警告
• 自定义校验规则：支持扩展业务级校验

8. 版本管理

• 自动保存：流程编辑时自动保存版本
• 历史记录：最多保存 50 个版本
• 版本对比：可视化对比不同版本的差异
• 版本回滚：一键恢复到历史版本
• 导入导出：支持版本的导入和导出

9. 自定义扩展

• 自定义节点：支持添加自定义业务节点
• 自定义属性：支持扩展节点属性配置
• 自定义字段：支持自定义表单字段类型（6大分类、20+字段类型）
• 自定义工具栏：支持动态配置工具栏按钮
• 自定义上下文菜单：支持画布右键菜单扩展
• 节点属性预设：7种预定义属性模板（标准审批、会签、或签等）

10. 流程管理

• 流程导入：支持从JSON数据导入流程
• 流程导出：支持将流程导出为JSON数据
• BPMN XML导入导出：支持BPMN 2.0 XML格式
• 流程验证：基础校验 + 高级校验
• 全局搜索：按节点名称或类型搜索，自动定位

11. 画布设置

• 背景类型：网格、点阵、线条、空白
• 网格配置：大小、颜色、对齐
• 缩放控制：放大、缩小、适应画布

12. 多语言支持

• 内置中英文支持
• 支持自定义语言扩展
• 动态语言切换

13. 实时协同能力

核心库定义协同抽象层，具体协同引擎由第三方适配器实现：

• 多适配器支持：BroadcastChannel（同源标签页，零依赖）、Yjs CRDT（多端强一致）
• 在线状态感知：用户光标、选中节点、在线列表（awareness）
• 操作广播：节点/连线/画布操作实时同步
• 冲突解决策略：可配置的冲突处理机制
• 操作历史回放：支持从协同历史回放操作

14. 性能优化

• 视口剔除（ViewportCulling）：仅渲染可视区域节点，支持千节点流畅交互
• 大画布测试：内置 100/500/1000 节点性能压测示例
• 命令栈事务：自动布局等批量操作支持事务，保障撤销/重做一致性

15. Element Template 模板

• 声明式节点模板：通过 Schema 定义节点属性、校验、默认值、可见性条件
• 模板注册表：elementTemplateRegistry 统一管理模板注册与查询
• Schema 校验器：TemplateSchemaValidator 校验模板合法性
• 业务节点沉淀：将企业级审批、会签等业务节点固化为可复用模板

16. BPMN Lint 语义规则

• 10 条内置规则：label-required、single-start-event、single-end-event、exclusive-gateway-default-flow、no-implicit-start、event-based-gateway-following-events、boundary-event-attached-to-activity、subprocess-non-empty、no-duplicate-flow-conditions、message-flow-between-pools
• 三级级别：error / warning / off，支持运行时动态调整
• 可扩展：支持自定义 lint 规则注册

17. DMN 决策表引擎

• FEEL 表达式：FEEL 友好表达式求值器
• 命中策略：唯一/首条/任意/优先/收集（含 sum/count/min/max/aggregate）
• 决策表校验：规则完整性、类型一致性校验

18. Agent 编排

• 状态机：AgentStateMachine 定义 Agent 执行状态流转
• 护栏（Guardrail）：正则注入检测、Prompt 注入检测、JSON Schema 输出校验、工具白名单、长度限制
• 编排器：AgentOrchestrator 支持多步执行、工具调用、人工接管

19. 出码引擎

• 三端出码：H5、小程序、移动端页面模型生成
• IR → PageModel：从设计器 IR 中间表示转换为平台页面模型
• 可扩展平台：通过 PlatformSpec 扩展新平台

20. 连接器市场

• 内置模板：REST 调用、Kafka/RabbitMQ 发布、Webhook 触发、钉钉/企微消息、邮件/短信、数据库查询
• 传输层：FetchRestTransport、InMemoryMessageTransport、FetchWebhookTransport
• 执行引擎：ConnectorExecutionEngine 支持重试策略、执行事件

21. MCP 双向能力

• MCP 客户端/服务端：MCPClient / MCPServer 实现 Model Context Protocol
• 设计器 MCP 工具：将设计器能力暴露为 MCP 工具/资源/Prompt，支持 AI Agent 远程操作流程设计器
• JSON-RPC 传输：标准 JSON-RPC 2.0 协议

22. 流程挖掘

• 事件日志采集：EventLogCollector 收集流程执行事件
• 变体分析：VariantAnalyzer 分析流程执行变体
• 瓶颈分析：BottleneckAnalyzer 识别流程瓶颈
• 热力图：HeatmapBuilder 生成节点/连线热力图

23. 版本治理

• 版本图：VersionGraph 管理流程版本树、分支、标签
• 修订级 diff：computeDiff 检测节点/连线/属性级变更
• 合并冲突检测：detectDiffConflicts 识别分支合并冲突

24. 方言插件体系

• Flowable 方言：FlowableDialect 实现 Flowable BPMN 序列化
• Freeform JSON 方言：FreeformJsonDialect 实现自由 JSON 序列化
• 可扩展：通过 DialectRegistry 注册自定义序列化方言

25. 安全表达式引擎

• expr-eval 替代 eval：基于 expr-eval 的安全表达式解析与求值
• 条件表达式：支持 || / && 短路求值
• 防注入：杜绝 eval() 安全风险

示例

在线演示

在线演示地址 - 展示process-editor的核心功能和使用方式

示例分类

process-editor提供了丰富的示例，涵盖了不同的使用场景和功能点：

扩展场景

1. 自定义节点开发

process-editor支持灵活的自定义节点扩展，您可以根据业务需求创建各种类型的节点：

HTML自定义节点示例

<template>
  <div class="custom-html-node">
    <h3>{{ title }}</h3>
    <div class="content">{{ content }}</div>
  </div>
</template>

<script setup>
const props = defineProps({
  userData: {
    type: Object,
    default: () => ({}),
  },
  figure: {
    type: Object,
    default: null,
  },
});

const title = computed(() => props.userData?.title || '自定义节点');
const content = computed(() => props.userData?.content || '这是一个HTML自定义节点');
</script>

<style scoped>
.custom-html-node {
  padding: 10px;
  border: 2px solid #409eff;
  border-radius: 8px;
  background-color: #fff;
  min-width: 150px;
  min-height: 80px;
}

.custom-html-node h3 {
  margin: 0 0 5px 0;
  color: #409eff;
  font-size: 14px;
}
</style>

注册自定义节点

const customNodes = computed(() => [
  {
    type: 'HtmlTask',
    bpmnType: 'CustomHtmlTask',
    text: 'HTML自定义节点',
    component: CustomHtmlNode,
    attr: {
      width: 200,
      height: 80,
      resizable: true,
    },
  },
]);

2. 自定义属性字段

process-editor支持扩展自定义属性字段，以满足特定的业务需求：

const customFields = computed(() => ({
  SWITCH: {
    component: FieldSwitch,
    props: {},
    events: {},
  },
  COLOR_PICKER: {
    component: ColorPicker,
    props: {
      showText: true,
    },
    events: {
      change: (value) => console.log('Color changed:', value),
    },
  },
}));

3. 生命周期钩子扩展

process-editor提供了丰富的生命周期钩子，可以在流程设计的各个阶段进行扩展：

// 注册生命周期钩子
const registerHooks = () => {
  // 初始化后钩子
  editor.value.designer.on(
    'afterInit',
    () => {
      console.log('流程编辑器初始化完成');
    },
    { blockAble: true }
  );

  // 节点添加前钩子
  editor.value.designer.on(
    'beforeAddNode',
    ({ emitter, event }) => {
      // 可以在这里进行节点添加前的验证和处理
      return true; // 返回false可以阻止节点添加
    },
    { blockAble: true }
  );

  // 节点删除前钩子
  editor.value.designer.on(
    'beforeRemoveNode',
    ({ event: { figure } }) => {
      if (figure.bpmnType === 'StartEvent') {
        message.warning('开始节点不允许删除');
        return false; // 阻止删除开始节点
      }
      return true;
    },
    { blockAble: true }
  );

  // 节点选择钩子
  editor.value.designer.on('selectedNode', ({ figure }) => {
    console.log('选中节点:', figure.id);
  });
};

4. 自定义工具栏

您可以根据业务需求自定义流程编辑器的工具栏：

const toolbarButtons = {
  getDefaultButtons() {
    return [
      {
        key: 'save',
        text: '保存',
        icon: 'save',
        onClick: () => saveProcess(),
      },
      {
        key: 'export',
        text: '导出',
        icon: 'export',
        onClick: () => exportProcess(),
      },
      {
        key: 'import',
        text: '导入',
        icon: 'import',
        onClick: () => importProcess(),
      },
      {
        key: 'zoomIn',
        text: '放大',
        icon: 'zoom-in',
        onClick: () => zoomIn(),
      },
      {
        key: 'zoomOut',
        text: '缩小',
        icon: 'zoom-out',
        onClick: () => zoomOut(),
      },
    ];
  },
};

5. 多语言扩展

process-editor支持多语言扩展，您可以添加自定义语言包：

// 自定义语言包
const customLang = {
  'process.common.StartEvent': '开始事件',
  'process.common.EndEvent': '结束事件',
  'process.common.UserTask': '用户任务',
  'process.common.ServiceTask': '服务任务',
  // 更多自定义翻译...
};

// 注册自定义语言
app.config.globalProperties.$getLangText = (key, defaultText) => {
  return customLang[key] || defaultText || key;
};

6. 流程验证扩展

您可以扩展流程验证功能，确保设计的流程符合业务规则：

const validateProcess = () => {
  const processData = editor.value.exportProcess();
  const errors = [];

  // 检查是否有开始节点
  const hasStartNode = processData.figures.some((node) => node.bpmnType === 'StartEvent');
  if (!hasStartNode) {
    errors.push('流程必须包含开始节点');
  }

  // 检查是否有结束节点
  const hasEndNode = processData.figures.some((node) => node.bpmnType === 'EndEvent');
  if (!hasEndNode) {
    errors.push('流程必须包含结束节点');
  }

  // 检查每个节点是否都有连接
  processData.figures.forEach((node) => {
    if (node.bpmnType !== 'StartEvent' && node.bpmnType !== 'EndEvent') {
      const hasIncoming = processData.lines.some((line) => line.target === node.id);
      const hasOutgoing = processData.lines.some((line) => line.source === node.id);

      if (!hasIncoming) {
        errors.push(`节点 ${node.config.name} 没有入连接`);
      }

      if (!hasOutgoing) {
        errors.push(`节点 ${node.config.name} 没有出连接`);
      }
    }
  });

  return errors;
};

7. 与后端集成

process-editor 提供完整的 Spring Boot 后端工程（位于 example/api/ 目录），实现 BPMN 流程引擎 RESTful API，包含流程定义管理、流程实例管理、任务管理和历史查询四大模块，共 23 个端点。

API 模块概览

前端调用示例

// 创建流程定义
const createProcessDefinition = async (bpmnXml, name, key) => {
  const response = await axios.post('/api/v1/process-definitions', {
    name,
    key,
    bpmnXml,
    category: '默认分类',
  });
  return response.data.data; // ApiResponse 结构: { code, message, data }
};

// 启动流程实例
const startProcess = async (definitionId, variables) => {
  const response = await axios.post('/api/v1/process-instances', {
    definitionId,
    businessKey: `BIZ-${Date.now()}`,
    startUserId: 'current-user',
    variables,
  });
  return response.data.data;
};

// 查询待办任务
const getTodoTasks = async (assignee) => {
  const response = await axios.get('/api/v1/tasks', {
    params: { type: 'todo', assignee, page: 1, pageSize: 20 },
  });
  return response.data.data; // { total, items }
};

// 完成任务并推进流程
const completeTask = async (taskId, variables, comment) => {
  await axios.post(`/api/v1/tasks/${taskId}/complete`, {
    variables,
    comment,
  });
};

API 契约文档

完整的 OpenAPI 3.0.3 契约定义见 example/docs/api-contract/openapi.yaml，前端 API 客户端见 packages/api/client.ts。

8. AI 能力抽象层接入

核心库只定义 AI 接口契约（AIAdvisor 抽象类 + AIClient 接口），不引入任何具体 LLM SDK。第三方通过继承 AIAdvisor 并实现 AIClient 即可接入任意大模型服务，再通过 AIAdvisorRegistry 注册激活。

AI 抽象层五层能力

接入示例（参考 example/src/ai/）

import { AIAdvisorRegistry, type AIAdvisor } from 'process-editor';
import { OpenAIAIClient } from './ai/OpenAIAIClient';
import { DefaultAIAdvisor } from './ai/DefaultAIAdvisor';

// 1. 创建注册表
const registry = new AIAdvisorRegistry();

// 2. 注册顾问（具体实现由第三方提供）
registry.register('default', DefaultAIAdvisor);

// 3. 激活并注入 AI 客户端与设计器
registry.activate('default', { client: new OpenAIAIClient({ apiKey, model }) });
registry.getActive()?.setDesigner(editorRef.value.designer);

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

核心库导出：AIAdvisor、AIAdvisorRegistry 及 AIClient/ChatRequest/NodeSuggestion/OptimizationReport/FlowGenerationResult 等类型。未注入 client 时 isAvailable() 返回 false，可回退到本地模板实现（见 example 的 DefaultAIAdvisor）。

9. 协同能力抽象层接入

核心库定义协同接口契约（CollaborationAdapter 抽象类 + CollaborationManager），不依赖 yjs、y-websocket 等协同引擎。第三方实现适配器后注册到管理器即可启用实时协同。

接入示例（参考 example/src/collab/）

import { CollaborationManager } from 'process-editor';
import { BroadcastChannelAdapter } from './collab/BroadcastChannelAdapter';

// 1. 创建管理器并注册适配器（同源标签页协同，零依赖）
const manager = new CollaborationManager();
manager.registerAdapter('broadcast', new BroadcastChannelAdapter());
manager.use('broadcast');

// 2. 注入设计器
manager.getAdapter()?.setDesigner(editorRef.value.designer);
manager.getAdapter()?.setUser({ id: 'u1', name: '张三', color: '#13c2c2' });

// 3. 连接协同房间
await manager.getAdapter()?.connect({ roomId: 'demo-room-001' });

// 4. 监听协同事件
manager.getAdapter()?.on('presence-change', (users) => {
  console.log('在线用户', users);
});

Yjs CRDT 协同（可选）

需要强一致性多端协同时，可动态加载 Yjs 适配器（example/src/collab/YjsCollaborationAdapter.ts），基于 Y.Doc + Y.Array + y-websocket awareness 实现操作同步与在线状态。Yjs 相关依赖仅作为 example 的可选依赖，未安装时不影响核心库构建：

// 动态加载，避免未安装 yjs 时构建失败
const { YjsCollaborationAdapter } = await import('./collab/YjsCollaborationAdapter');
manager.registerAdapter('yjs', new YjsCollaborationAdapter({ url: 'ws://localhost:1234' }));
manager.use('yjs');

10. Element Template 模板注册

Element Template 提供声明式的节点模板定义，支持属性字段、校验规则、默认值、可见性条件等，可用于沉淀业务节点规范。

import { elementTemplateRegistry, type ElementTemplate } from 'process-editor';

const approvalTemplate: ElementTemplate = {
  id: 'approval-task',
  name: '审批节点',
  bpmnType: 'UserTask',
  paletteGroup: '审批',
  defaultSize: { width: 200, height: 56 },
  color: '#13c2c2',
  properties: [
    { id: 'assignee', label: '审批人', type: 'personnel-select', required: true },
    { id: 'approvalMode', label: '审批模式', type: 'select', defaultValue: 'single',
      options: [
        { label: '单人审批', value: 'single' },
        { label: '会签', value: 'countersign' },
        { label: '或签', value: 'or-sign' },
      ] },
  ],
  validation: [
    { rule: 'required', field: 'assignee', message: '审批人不能为空', level: 'error' },
  ],
};

elementTemplateRegistry.register(approvalTemplate);

11. DI 容器与模块化扩展

核心库提供轻量级 DI 容器，支持服务注册、工厂注册、声明式模块加载与子容器，便于将自定义能力注入核心流程。

import { DIContainer, type Module } from 'process-editor';

const container = new DIContainer();

// 注册实例 / 工厂
container.register('logger', { log: () => console.log('hi') });
container.registerFactory('designer', () => createDesigner());

// 声明式模块
const myModule: Module = {
  __depends__: [],
  __init__: ['logger'],
  logger: () => ({ log: () => console.log('module logger') }),
};
container.load(myModule);

// 解析
const logger = container.resolve('logger');

// 子容器隔离
const child = container.createChild();

更多功能使用示例

1. 编辑器实例 API（ref 方法）

ProcessEditor 组件通过 ref 暴露完整的画布操作方法：

<template>
  <ProcessEditor ref="editor" :processData="processData" />
</template>

<script setup>
const editor = ref();

// ── 数据导入导出 ──
const data = editor.value.exportProcess();          // 导出流程 JSON
editor.value.importProcess(data);                   // 导入流程 JSON
const xml = await editor.value.exportToXml();       // 导出 BPMN 2.0 XML
await editor.value.importFromXml(xml);              // 导入 BPMN XML

// ── 画布操作 ──
editor.value.setZoom(1.25);                         // 设置缩放
editor.value.fitCanvas();                           // 适应画布
editor.value.autoLayout({ direction: 'LR' });       // 自动布局（TB/BT/LR/RL，默认 TB）

// ── 撤销/重做（CommandStack 驱动）──
editor.value.undo();
editor.value.redo();

// ── 节点高亮与执行路径 ──
editor.value.highlightNode('UserTask_1');
editor.value.highlightPath(['node1', 'node2']);     // 高亮执行路径
editor.value.clearHighlight();

// ── 子流程导航 ──
editor.value.drillDown('SubProcess_1');             // 进入子流程
editor.value.drillUp();                             // 返回上级
const stack = editor.value.getNavigationStack();    // 导航栈
</script>

2. 全局安装配置（i18n / 主题 / 数据源 / API 客户端）

app.use(ProcessEditor, options) 或 registerGlobalProperties 接受统一的全局配置：

import ProcessEditor from 'process-editor';

app.use(ProcessEditor, {
  locale: 'zh',                        // 'en' | 'zh'
  translations: { 'process.custom.key': '自定义词条' },  // 与内置词条合并
  // getLangText: (key, def) => ...,   // 自定义翻译函数（优先级最高）
  // 主题定制：注入为 $theme，覆盖主色/圆角/字号
  theme: {
    primaryColor: '#1677ff',
    borderRadius: 6,
    fontSize: 14,
  },
  // dataProvider / apiClient / messageTemplateEditorUrl 见下文
});

3. DataProvider 对接外部系统

DataProvider 是人员/组织/表单/决策表等业务数据的统一取数接口，有两种注入方式：app.use(ProcessEditor, { dataProvider }) 全局注入（挂为 $dataProvider），或组件级 :dataProvider prop（就近覆盖）：

import ProcessEditor from 'process-editor';

app.use(ProcessEditor, {
  dataProvider: {
    // 按需实现接口方法：人员 / 组织 / 角色 / 表单 Schema /
    // 消息模板 / 决策表 / 流程变量 等（见 config/DataProvider 类型定义）
    async getPerson(id) {
      const res = await fetch(`/api/users/${id}`);
      return res.json();
    },
  },
});

<template>
  <!-- 也可组件级注入 -->
  <ProcessEditor :dataProvider="myDataProvider" />
</template>

4. 自动保存（useAutoSave）

import { useCore } from 'process-editor';

const { isSaving, lastSavedAt, hasUnsavedChanges, save, restoreFromCache, clearCache } =
  useCore.useAutoSave({
    delay: 30_000,                       // 自动保存间隔，默认 30s
    storageKey: 'my-process-autosave',
    getData: () => editor.value.exportProcess(),
    onSave: async (data) => { await api.saveDraft(data); },
    enabled: true,
  });

// 页面加载时恢复上次未保存的草稿
onMounted(() => restoreFromCache());

5. 流程仿真（useSimulation）

import { useCore } from 'process-editor';

const {
  state, isRunning, currentNodeName, executionPath,
  variables, pendingGateway,
  start, pause, resume, stop, step, selectPath,
  setVariable,
} = useCore.useSimulation(processData, {
  stepDelay: 500,                       // 每步间隔
  initialVariables: { days: 3, amount: 8000 },
  autoStep: false,                      // true = 自动逐步执行
  onNodeEnter: (node) => console.log('进入节点', node),
  onComplete: (path) => console.log('执行路径', path),
});

await start();                          // 从开始节点启动仿真
// 遇到网关时 pendingGateway 有值（availablePaths 为候选分支），选择其中一条：
if (pendingGateway.value) selectPath(pendingGateway.value.availablePaths[0].lineId);
setVariable('days', 10);                // 运行中修改变量

6. 版本历史与 diff（useVersionHistory）

import { useCore } from 'process-editor';

const {
  versions, versionCount, hasUnsavedChanges,
  createVersion, restoreVersion, getDiff, deleteVersion,
  exportVersions, importVersions, clear,
} = useCore.useVersionHistory({
  maxVersions: 50,
  processData: () => editor.value.exportProcess(),
  onRestore: (data) => editor.value.importProcess(data),
});

const version = createVersion('调整审批链');            // 手动存版本（同步返回 Version）
const { hasChanges, changes } = getDiff(v1Id, v2Id);  // 节点/连线/属性级 diff
restoreVersion(v1Id);                                 // 一键回滚

7. 流程分析（useProcessAnalytics）

import { useCore } from 'process-editor';

const { executionHistory, bottlenecks, slaData, statistics, suggestions, analyze } =
  useCore.useProcessAnalytics({
    slaTargetDuration: 3600_000,        // SLA 目标时长（毫秒）
    p90WarningThreshold: 0.8,
    p95CriticalThreshold: 0.95,
  });

analyze();  // 产出：执行历史、瓶颈节点、SLA 达成率、优化建议

8. 明暗主题（useTheme）

import { useCore } from 'process-editor';

const { theme, isDark, toggleTheme, setTheme } = useCore.useTheme();
toggleTheme();   // light <-> dark，通过 data-theme 属性生效，localStorage 持久化

9. 插件系统（PluginManager + ExportPlugin）

插件是实现 install(ctx) / uninstall(ctx) 契约的对象，通过 PluginContext 拿到组件注册表、画布与事件通道：

import { PluginManager, ExportPlugin } from 'process-editor';

// 构造参数：节点注册表与 API 客户端
const plugins = new PluginManager(nodeRegistry, apiClient);
plugins.setDesigner(editor.value.designer);   // 让插件能访问画布

// 内置导出插件：SVG/PNG/JPEG 图像导出与部署到流程引擎
await plugins.install(new ExportPlugin());

// 自定义插件
await plugins.install({
  name: 'my-audit-plugin',
  install(ctx) {
    // ctx: { componentRegistry, nodeRegistry, apiClient, designer, canvas, on, emit, ... }
    ctx.on('node:added', (node) => auditLog(node));
  },
  uninstall(ctx) { /* 清理 */ },
});

await plugins.uninstall('my-audit-plugin');

10. Yjs CRDT 协同（process-editor/collab-yjs 子入口）

多端强一致协同使用独立子入口，yjs 与 provider 依赖由消费方自行安装：

import { YjsAdapter } from 'process-editor/collab-yjs';
import { CollaborationManager } from 'process-editor';

const manager = new CollaborationManager();
manager.registerAdapter('yjs', new YjsAdapter({
  url: 'ws://localhost:1234',           // y-websocket 服务地址
  roomId: 'process-42',
}));
manager.use('yjs');

manager.getAdapter()?.setDesigner(editorRef.value.designer);
manager.getAdapter()?.setUser({ id: 'u1', name: '张三', color: '#13c2c2' });
await manager.getAdapter()?.connect({ roomId: 'process-42' });

11. 响应式多语言切换

import { getLocale, setLocale, useLocale, useReactiveI18n } from 'process-editor';

setLocale('zh');                        // 全局切换（内置 zh/en 词条）
const { locale } = useLocale();         // 组件内响应式读取/切换

也可按需引入内置语言包：

import zh from 'process-editor/i18n/zh';
import en from 'process-editor/i18n/en';

12. 能力抽象层速用（DMN / 流程挖掘 / 出码 / MCP）

以下能力均在主入口导出，可脱离 UI 独立使用：

import {
  DecisionEngine, FeelEvaluator, HitPolicyExecutor,   // DMN 决策表
  ProcessMiner, EventLogCollector,                    // 流程挖掘
  CodegenEngine,                                      // 出码
  MCPClient, MCPServer, MCPRegistry,                  // MCP
} from 'process-editor';

// ── DMN：FEEL 表达式求值 + 命中策略执行 ──
const feel = new FeelEvaluator();
feel.evaluate('amount > 10000', { amount: 20000 });   // true

// ── 流程挖掘：事件日志 → 轨迹/变体/瓶颈/热力图 ──
const miner = new ProcessMiner();
const log = { processName: '请假审批', events: [
  { caseId: 'c1', activity: '提交申请', timestamp: Date.now(), /* ...ProcessEvent */ },
] };
const report = miner.mine(log);              // 汇总报告
miner.analyzeVariants(log);                  // 执行变体分析
miner.analyzeBottlenecks(log);               // 瓶颈分析
miner.buildHeatmap(log);                     // 节点/连线热力图

// ── 出码：IR 上下文 → 多平台代码文件 ──
const result = new CodegenEngine().generate(
  { platform: 'h5' },
  { process: irProcess, forms: formSchemas, bindings: formNodeBindings },
);
// result.files: OutputFile[]（页面组件、路由配置等）

最佳实践

1. 节点设计原则

• 单一职责：每个节点只负责一个特定的业务功能
• 可复用性：设计通用的节点类型，便于在不同流程中复用
• 可配置性：提供丰富的配置选项，适应不同的业务场景
• 可视化友好：节点的外观应直观反映其功能和状态

2. 流程设计建议

• 清晰的流程结构：使用网关合理组织流程分支和合并
• 完整的生命周期：确保流程有明确的开始和结束节点
• 适当的节点粒度：节点的粒度应适中，既不过于细化也不过于粗糙
• 良好的命名规范：为节点和流程提供清晰、有意义的名称

3. 性能优化

• 合理使用自定义节点：避免过度复杂的自定义节点，影响渲染性能
• 优化流程规模：对于大型流程，考虑分页或分层设计
• 减少不必要的计算：在自定义节点中避免频繁的重计算
• 合理使用缓存：对于不经常变化的数据，使用缓存提高性能

4. 扩展性设计

• 使用生命周期钩子：通过生命周期钩子扩展功能，避免修改核心代码
• 模块化设计：将自定义功能封装为独立的模块，便于维护和升级
• 遵循开放封闭原则：对扩展开放，对修改封闭
• 提供清晰的扩展文档：为其他开发者提供详细的扩展指南

常见问题解答

Q: 如何添加自定义节点？

A: 您可以通过创建Vue组件，并将其注册为自定义节点来添加新的节点类型。具体步骤如下：

1. 创建自定义节点组件
2. 在编辑器中注册自定义节点
3. 配置节点的属性和行为

Q: 如何扩展节点属性？

A: 您可以通过自定义属性字段和属性配置面板来扩展节点属性。具体方法包括：

1. 创建自定义属性字段组件
2. 在属性配置中引用自定义字段
3. 配置字段的验证规则和默认值

Q: 如何实现流程的导入导出？

A: process-editor提供了内置的导入导出功能，您可以直接调用编辑器的方法：

// 导出流程
const processData = editor.value.exportProcess();

// 导入流程
editor.value.importProcess(processData);

Q: 如何实现多语言支持？

A: 您可以通过注册自定义翻译函数来实现多语言支持：

app.config.globalProperties.$getLangText = (key, defaultText) => {
  return langMap[key] || defaultText || key;
};

Q: 如何与后端工作流引擎集成？

A: process-editor 已内置完整的 Spring Boot 后端工程（example/api/ 目录），提供 23 个 RESTful API 端点。集成步骤：

1. 启动 MySQL 并创建 process_editor 数据库
2. 在 example/ 目录下运行 npm run dev:api 启动后端服务（端口 8080）
3. 在 example/ 目录下运行 npm run dev 启动前端，Vite 会自动将 /api 请求代理到后端
4. 使用 editor.value.exportProcess() 导出流程数据，调用 POST /api/v1/process-definitions 创建流程定义
5. 调用 POST /api/v1/process-instances 启动流程实例
6. 完整 API 契约见 example/docs/api-contract/openapi.yaml

Q: 如何自定义节点的外观？

A: 您可以通过以下方式自定义节点外观：

1. 在节点注册时配置attr属性
2. 使用CSS样式自定义节点外观
3. 在自定义节点组件中实现复杂的视觉效果
4. 利用图形属性配置面板动态调整节点样式

开源支持

如果您喜欢这个项目，请在 Gitee 上给我们一个 Star ⭐️！

打赏&支持

           

协议

本项目使用 Apache-2.0 协议。详情请参阅 LICENSE 文件。

--- 神即道，道法自然，如来 ---