@acelance/graph-dsl-ui
v1.0.6
Published
Ace Graph DSL visual designer components for spring-ai-alibaba-graph
Readme
@acelance/graph-dsl-ui
面向 spring-ai-alibaba-graph 的 Graph DSL 可视化设计器 Vue 组件库。基于 LogicFlow 提供拖拽式流程编排,支持草稿保存、校验、PlantUML 预览与版本发布。
功能特性
- 可视化编排:拖拽节点、连线,支持普通边与条件分发边(Dispatcher);自定义 SVG 节点(分类配色)与贝塞尔连线
- 连线参数校验:连线后实时校验入参可达性,失败连线标红,左下角悬浮提示;发布时后端同步校验(保存草稿不校验)
- Graph 管理:目录列表、新建 / 切换 Graph DSL、版本摘要展示
- 草稿与发布:保存草稿、服务端校验、发布并切换运行时 Graph
- 编译配置:Key Strategy、Saver(Memory / JDBC / Redis)、HITL 中断点
- 预览能力:PlantUML / Mermaid 预览(通过后端 API)
- 可组合:提供完整页面组件,也支持拆分使用工具栏、画布、属性面板等子组件
- 脚本节点:设计器内新建脚本节点,支持 Aviator / SpEL / QLExpress / Groovy(按后端引擎列表),语法校验与试跑(详见 脚本节点样例文档)
- 通用 Agent 节点:节点面板 AGENT 标签下新建 / 复用通用 Agent 实体(双通道:注册式复用 / 内联拖入),支持 prompt / skill / mcp 资源引用与试跑
- 子图编排(graph-in-graph):从节点面板拖入子图节点,选择内联(下钻编辑空白子图)或引用(指向目录中已有图);画布上方浮动面包屑支持下钻 / 返回,编译期循环引用与嵌套深度(≤3 层)防护
- 菜单权限:按后端返回的菜单权限自动控制按钮显隐,支持对接宿主权限框架(详见 菜单权限接入指南)
文档
| 文档 | 说明 |
|------|------|
| 设计器嵌入集成方案(组件 / iframe) | A1/A2、B1 组件与 B2/B3 同源 iframe、EmbedContext、过滤/重排与安全 |
| 脚本节点填写与使用样例 | 四引擎字段说明、样例、条件边、REST API |
| 多脚本引擎方案 | Phase A/B/C、分包、开关与验收进度 |
| 菜单/功能权限抽象与接入指南 | 菜单权限 SPI、REST API 与前端 usePermissionStore 用法 |
| 后续优化与功能规划建议 | 按 P0–P3 优先级的后续优化项与落地顺序 |
| 架构总览 | 前后端架构、校验与数据流 |
技术栈
| 依赖 | 用途 | |------|------| | Vue 3 | 组件框架 | | Pinia | 状态管理 | | Element Plus | UI 组件 | | LogicFlow | 流程图画布 | | Axios | HTTP 客户端 |
安装
npm install @acelance/graph-dsl-ui同时安装 peer dependencies:
npm install vue pinia element-plus axios @logicflow/core @logicflow/extension快速开始
1. 注册依赖与样式
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import '@logicflow/core/dist/index.css'
import '@logicflow/extension/lib/style/index.css'
import { GraphDslManager } from '@acelance/graph-dsl-ui'
createApp(GraphDslManager)
.use(createPinia())
.use(ElementPlus)
.mount('#app')容器需具备明确高度,例如:
html, body, #app {
height: 100%;
}2. 配置后端代理(开发环境)
组件默认请求相对路径 /api/graph/**,开发时可通过 Vite 代理转发到 Graph DSL 后端:
// vite.config.js
export default defineConfig({
server: {
proxy: {
'/api': {
target: 'http://127.0.0.1:8087',
changeOrigin: true
}
}
}
})组件说明
GraphDslManager
带左侧目录的完整管理页,适合作为独立页面或业务页签嵌入。
| Prop | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| title | String | ''(回落 i18n) | 目录面板标题 |
| apiBaseUrl | String | '/' | 后端 API 根路径 |
| locale | String | 'zh-CN' | 界面语言 |
| embed | Object | null | 嵌入上下文 { graphId?, agentCode?, otherBizParams? }(推荐) |
| graphId / agentCode / otherBizParams | String | — | 扁平别名;与 embed 同时存在时以 embed 为准 |
<!-- A1 独立设计器 -->
<GraphDslManager api-base-url="/" />
<!-- A2 Agent 详情页签 -->
<GraphDslManager
api-base-url="/"
:embed="{ graphId: 'order_flow', agentCode: 'agent_order', otherBizParams: JSON.stringify({ tenantId: 't1' }) }"
/>完整契约、iframe 同源部署与验收见 设计器嵌入集成方案。
GraphDslDesigner
单 Graph 设计器,不含目录,适合嵌入已有路由或弹窗。
| Prop | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| graphId | String | 必填 | Graph 唯一标识 |
| apiBaseUrl | String | '/' | 后端 API 根路径 |
| title | String | '' | 工具栏显示标题,默认同 graphId |
| 事件 | 说明 |
|------|------|
| saved | 草稿保存成功后触发 |
| published | 发布成功后触发 |
<GraphDslDesigner
graph-id="order-flow"
title="订单流程"
@saved="onSaved"
@published="onPublished"
/>子组件(高级用法)
可按需组合布局:
| 导出名称 | 说明 |
|----------|------|
| DesignerToolbar | 顶部工具栏(保存 / 校验 / 预览 / 发布) |
| DesignerNodePanel | 左侧节点面板 |
| DesignerCanvas | LogicFlow 画布 |
| DesignerPropertyPanel | 右侧属性面板 |
Store 与 API
Pinia Stores
import { useGraphEditorStore, useNodeRegistryStore } from '@acelance/graph-dsl-ui'
const editor = useGraphEditorStore() // 当前 Graph 编辑状态
const nodeStore = useNodeRegistryStore() // 节点 / Dispatcher 注册表useGraphEditorStore 主要能力:
loadLatest()/save()/validate()/publishCurrent()buildDefinition()/applyDefinition()— DSL 对象读写setFromLfData()— 从 LogicFlow 画布同步到 storerefreshEdgeParamValidation()/edgeParamIssues— 连线参数可达性校验(画布连线变更后自动刷新)
API 客户端
默认导出基于 baseURL='/' 的便捷方法;也可创建自定义实例:
import { createGraphApi, listSummaries, saveDraft } from '@acelance/graph-dsl-ui'
const api = createGraphApi('https://your-backend.example.com')
await api.listSummaries()
await api.saveDraft('order-flow', definition)后端 API 约定
组件库依赖以下 REST 接口(路径前缀 /api/graph):
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /nodes | 可用节点类型列表 |
| GET | /dispatchers | 条件边 Dispatcher 列表 |
| GET | /catalog/summaries | Graph 摘要列表 |
| GET | /definitions/{graphId} | 获取最新定义 |
| GET | /definitions/{graphId}/versions | 版本历史 |
| POST | /definitions/{graphId}/draft | 保存草稿(不做连线参数可达性校验) |
| POST | /definitions/{graphId}/validate | 校验定义(含连线参数可达性等) |
| POST | /definitions/{graphId}/preview/plantuml | PlantUML 预览 |
| POST | /definitions/{graphId}/preview/mermaid | Mermaid 预览 |
| POST | /definitions/{graphId}/publish | 发布版本(发布前强制校验,含连线参数可达性) |
| POST | /definitions/{graphId}/rollback | 回滚版本 |
| GET | /definitions/{graphId}/enabled | 当前启用版本 |
本地开发
# 安装依赖
npm install
# 启动 Demo(默认 http://127.0.0.1:5173)
npm run dev
# 构建
npm run build
# 预览构建产物
npm run previewDemo 入口为 demo/main.js,挂载 GraphDslManager 组件。请确保 Graph DSL 后端服务(默认 8087 端口)已启动,否则节点列表与 Graph 数据将无法加载。
项目结构
ace-graph-dsl-ui/
├── demo/ # 本地 Demo 入口
├── src/
│ ├── api/graph.js # Graph DSL HTTP 客户端
│ ├── stores/
│ │ ├── graphEditor.js # 编辑器状态与 DSL 转换
│ │ └── nodeRegistry.js # 节点 / Dispatcher 注册表
│ ├── components/
│ │ ├── GraphDslManager.vue # 管理页(目录 + 设计器)
│ │ ├── GraphDslDesigner.vue # 单 Graph 设计器
│ │ └── Designer/ # 设计器子组件(含 EdgeParamValidationPanel)
│ ├── utils/
│ │ └── edgeParamValidation.js # 连线参数可达性校验
│ └── index.js # 库导出入口
├── index.html
├── vite.config.js
└── package.jsonGraphDefinition 数据模型(简要)
设计器维护的核心 DSL 结构:
{
"graphId": "order-flow",
"displayName": "订单流程",
"version": "1.0.0",
"description": "",
"keyStrategies": { "messages": "REPLACE" },
"nodes": [
{ "nodeId": "llmNode", "config": {} }
],
"edges": [
{ "from": "__START__", "to": "llmNode", "type": "normal" },
{ "from": "routerNode", "to": "", "type": "conditional", "dispatcher": "routeDispatcher", "mapping": { "A": "nodeA" } }
],
"compile": {
"interruptBefore": ["hitlNode"],
"saver": "memory"
}
}画布中的 START / END 节点会自动映射为保留字 __START__ / __END__。
画布视觉与交互
自定义节点与连线(LogicFlow v2)
| 文件 | 说明 |
|------|------|
| Designer/DspNode.js | 自定义 SVG 节点:dsp-rect(普通/MERGE/HITL)、dsp-diamond(ROUTER 六边形)、dsp-circle(START/END) |
| Designer/DspEdge.js | 自定义贝塞尔连线 dsp-bezier;普通边 / 条件边分色;校验失败边标红(paramInvalid) |
节点分类配色
| 分类 | 说明 | 画布配色 |
|------|------|----------|
| NORMAL | 普通业务节点 | 蓝色 |
| ROUTER | 路由 / 分支节点 | 橙色(六边形) |
| MERGE | 合并节点 | 绿色 |
| HITL | 人机协同节点 | 紫色 |
| SUBGRAPH | 子图节点 | 蓝色(primary) |
| GENERIC_AGENT | 通用 Agent 节点(注册式) | 红色(danger) |
| START / END | 保留起止节点 | 青色圆形 |
连线参数校验 UI
- 触发时机:连线增删、节点变更、图加载后画布同步到 store 时自动校验
- 提示面板:
EdgeParamValidationPanel,悬浮于画布左下角(红底半透明磨砂,固定高度,内容可滚动) - 失败连线标红:通过
lf.setProperties增量更新paramInvalid,不触发全图重绘 - 切换 Graph:
selectGraph清空并重新计算当前图的edgeParamIssues
EdgeParamValidationPanel为设计器内部组件,随GraphDslDesigner挂载,未在index.js单独导出。
快问快答
如何选择脚本引擎?
设计器通过 GET /nodes/engines 拉取当前可用引擎,在脚本节点编辑器与条件边属性面板中选择:
| 引擎 | 适用场景 | 备注 |
|------|----------|------|
| Aviator(默认) | 单行表达式、轻量计算 | 无需额外依赖 |
| SpEL | 熟悉 Spring 表达式、Map 字面量 | core 内置;禁止 T() 任意类 |
| QLExpress | 多行 if/else 业务规则 | 需引入 ace-graph-dsl-script-qlexpress |
| Groovy | 集合分组等复杂脚本 | 需引入 ace-graph-dsl-script-groovy 且 groovy-enabled=true |
选中引擎后,脚本区行数按 multiLine 自动调整(约 3 / 14 行),并显示引擎 hint。更多样例见 SCRIPT_NODE_EXAMPLES.md。
连线参数校验如何工作?
设计器在连线增删或画布同步到 store 后,根据节点元数据的 inputKeys / outputKeys 沿图路径累积上游产出 key,判断目标节点入参是否可达:
- 前端:
edgeParamIssues驱动左下角红色半透明提示面板;失败连线在画布上标红(properties.paramInvalid,增量setProperties,不重绘全图) - 后端:
GraphValidator第 6 步调用EdgeParamReachabilityValidator;发布与工具栏「校验」会拦截;保存草稿不经过此校验
豁免规则(避免误报):
| 连线类型 | 是否校验 | 原因 |
|----------|----------|------|
| __START__ → 业务节点 | 否 | 入参来自图调用初始 state |
| 普通节点 → HITL | 否 | 入参来自 interrupt / resume 注入 |
| 普通节点 → 普通节点 | 是 | 须由上游节点产出所需 key |
是否支持 Vue 2 + JS 项目集成?
不支持直接在 Vue 2 项目中作为组件库集成。 本库面向 Vue 3 生态设计与构建:
| 项 | 说明 |
|----|------|
| peerDependencies | 要求 vue ^3.5.0 |
| 组件写法 | 全部使用 <script setup>(Vue 3 特性) |
| UI 库 | Element Plus(仅支持 Vue 3) |
| 状态管理 | Pinia 2.x |
| 构建产物 | ESM(dist/index.js),运行时依赖 Vue 3 API |
Vue 3 + JS 项目可直接按上文「快速开始」或 :embed 对象集成;Vue 2 / 非 Vue 请用同源 iframe(/ace-graph-designer/embed.html?embed=…),详见 designer-embed-integration.md。不要尝试在 Vue 2 宿主内硬嵌 Vue 3 SFC。
构建 iframe 静态包:
npm run build:embed
# 产出 dist-embed/,反代挂到 /ace-graph-designer/通用 Agent 节点
通用 Agent 节点采用与脚本节点一致的「先定义 → 入库 → 复用」范式,提供双通道:
| 通道 | 说明 | 拖入来源 |
|------|------|----------|
| 注册式(引用型) | 图中仅存 nodeId,元数据来自持久化的 GenericAgentDefinition,origin=GENERIC_AGENT,可跨图复用 | 节点面板 AGENT 标签 → 已入库的 Agent 列表 |
| 内联式 | 结构型节点拖入时携带完整 agentSpec,ad-hoc 编译执行 | 节点面板结构节点区域拖入(自动带 agentSpec) |
使用流程
- 节点面板切到 AGENT 标签,点「新建通用 Agent」打开
AgentNodeEditor模态框。 - 填写 12 个字段(含 prompt / skill / mcp 资源引用、API Key 掩码处理),保存即入库(
POST /agents)。 - 在 AGENT 标签列表中点对应 Agent 拖入画布 → 走注册式通道(只读引用 + 「前往节点面板编辑」)。
- 注册式 Agent 的 keys / 配置变更在
GenericAgentDefinition一处完成,引用它的所有图共享更新。
资源候选在注册式编辑弹窗「资源勾选」区请求 GET /api/agent-resources/{mcp|skills}(可带 agentCode / graphId / otherBizParams)。有数据时 MCP 为三级勾选树,Skill 为多选。目录为空或失败时退回逗号文本。图入口打开时用 embed 初值并静默透传 otherBizParams;节点面板新建/编辑时空 agentCode 框可手填。详见 designer-embed-integration.md 与 designer-resource-catalog-browse.md。
权限:新建 / 删除 / 试跑受
agent-node:create / delete / test菜单权限控制;只读用户仅可拖入引用。
子图(graph-in-graph)
子图节点(SUBGRAPH)支持两种形态,在属性面板的内联 / 引用 radio 中切换:
| 形态 | 说明 | 下钻行为 |
|------|------|----------|
| 内联(inline) | 子图内容嵌在父图节点 subgraph 字段中 | 点「进入子图」→ 空白子图画布,可独立编辑,面包屑返回主图 |
| 引用(reference) | 节点 subgraphRef 指向目录中已有图(graphId) | 引用下拉框选择目标图(已排除当前图自身),引用型子图编译期从仓库加载最新版本 |
版本锁定(P2)
引用型子图支持锁定特定版本,避免被引用图更新后父图行为静默变化:
- 引用图选择器下方有「版本锁定」下拉,默认「最新(默认)」= 跟随最新版本(
subgraphRef存纯graphId) - 下拉选择具体版本后,
subgraphRef存为graphId@version,编译期加载该锁定版本 - 版本列表在选图后懒加载(调
listVersions);切换版本即时生效
使用流程
- 节点面板结构节点区域拖入「子图」节点 → 画布选中该节点。
- 右侧属性面板:内联 直接点「进入子图」;引用 先从下拉框选一张已有图。
- 下钻后,画布上方出现浮动面包屑条:路径 根图 / 子图 … + 「返回上级」按钮 + 深度指示器
X/3。 - 点面包屑或「返回上级」回到上层;进入受
MAX_SUBGRAPH_DEPTH=3约束,达到上限前端ElMessage.warning拦截。
注意事项
- 引用 radio 切换为纯 UI 操作,不立即写入图数据;真正建立引用发生在下拉框选定具体图后,避免切换时丢失节点选中。
- 编译期(
GraphValidator+DynamicGraphBuilder)检测跨图subgraphRef循环引用,并限制嵌套深度 ≤3 层;保存时校验会拦截违规图。
许可证
与上游 spring-ai-alibaba-graph 项目保持一致,使用前请查阅对应仓库的许可证说明。
