RuleGo-Editor 以 npm 库 @rulego/editor 的形式发布，提供规则链可视化编辑能力。宿主按需选择集成形态，所有形态共享同一套核心：RuleGoEditor（画布）+ RuleGoShell（dock 布局外壳）+ RuleGoWorkspace（开箱即用 IDE 外壳）+ 内置面板。差别只在于谁管规则链的生命周期与显示哪些外壳元素。

本文是集成的总参考：先用 基础用法 跑通，再按 集成形态 选型，细项查 options 属性 与 能力开关。

目录

• 基础用法
• 集成形态
• 能力开关（mode + capabilities）
• 组件 Props
• data 属性
• options 属性
• toolbar 配置
• extensions 属性
• config.js 配置文件
• AI 服务商配置
• Token 管理
• 事件
• 方法
• 导出清单
• 高级配置示例
• 后端要求

---

基础用法

安装：

npm i @rulego/editor

@rulego/editor 把 vue / element-plus / @logicflow/* 作为 peerDependencies，宿主需自行安装（详见 安装）。

形态 B：一行接入（推荐，开箱即用 IDE）

自带顶栏 / 多 tab / 资源树 / 组件库 / 诊断 / 运行调试 / 运行记录 / 草稿 / 会话恢复，workspace 全权管理规则链生命周期：

<template>
  <RuleGoWorkspace :options="options" />
</template>

<script setup>
import { RuleGoWorkspace } from '@rulego/editor'
import '@rulego/editor/style.css'   // 必须引入样式
import logoUrl from './assets/logo.png'

const options = {
  mode: 'app',                      // 工作区形态
  url: 'http://127.0.0.1:9090',     // rulego-server 地址（同源部署可省略）
  logoUrl,
}
</script>

形态 A：单画布嵌入（宿主自管规则链）

宿主自己加载规则链 DSL、处理保存、管导航，editor 只当画布用：

<template>
  <RuleGoEditor
    ref="ruleGoEditorRef"
    :data="data"
    :options="options"
    @saveOk="onSaveOk"
    @saveError="onSaveError"
  />
</template>

<script setup>
import { RuleGoEditor } from '@rulego/editor'
import '@rulego/editor/style.css'
import { ref } from 'vue'

const ruleGoEditorRef = ref()
const data = ref()
const options = ref({
  url: 'http://127.0.0.1:9090',
  loadComponentsFromApi: true,
})

const onSaveOk = (data) => console.log('保存成功', data)
const onSaveError = (data, e) => console.error('保存失败', data, e)
</script>

形态选择与更多示例见 集成形态。

---

集成形态

形态	组件	TopBar	多 Tab	规则链生命周期	适用场景
A：单链嵌入	RuleGoShell + RuleGoEditor	关	无	宿主自管	宿主已有外壳（列表页/侧边栏/路由），只缺一块画布
B：工作区	RuleGoWorkspace mode:'app'	开	开	workspace 自管	独立部署 / 开箱即用 IDE
B-lite：单链工作区	RuleGoWorkspace 关 topbar/tabs	关	无	workspace 自管	iframe 嵌入 / 无外壳宿主想要单链 + dock 面板

形态 A：单链嵌入（宿主自管）

宿主自己加载规则链 DSL、自己处理保存按钮、自己管导航。editor 只当画布用，但可以借助 RuleGoShell 拿到三 dock 面板（组件库/诊断/运行记录等）：

<template>
  <RuleGoShell
    :capabilities="{ workspace: { topBar: false, tabs: false, explorer: false } }"
    :chain-info="chainInfo"
    :lf="lf"
  >
    <RuleGoEditor
      v-if="dsl"
      ref="editorRef"
      :data="dsl"
      :options="{ url, toolbar: { showSave: true } }"
      @saveOk="onSaved"
    />
  </RuleGoShell>
</template>

<script setup>
import { ref, computed } from 'vue'
import { RuleGoEditor, RuleGoShell } from '@rulego/editor'
import '@rulego/editor/style.css'

const editorRef = ref()
const dsl = ref(null)
const lf = computed(() => editorRef.value?.lf || null)
const chainInfo = computed(() => ({
  chain_title: dsl.value?.ruleChain?.name || '',
  chain_id: dsl.value?.ruleChain?.id || '',
}))

// 宿主自己加载 DSL（走自己的 API 封装）
async function loadChain(id) {
  dsl.value = await fetchRuleChain(id)
}
function onSaved(newDsl) {
  dsl.value = newDsl
}
</script>

关键点：

• workspace.topBar: false 关掉顶栏（保存/部署/用户菜单由宿主提供）
• workspace.tabs: false / workspace.explorer: false 关掉多 tab 与资源树（宿主自管规则链列表）
• 保存由 editor 内置 Toolbar 的 showSave 按钮触发，或宿主调 editorRef.value.save()

形态 B：工作区（开箱即用 IDE）

见 基础用法。能力开关可细粒度覆盖，详见 能力开关 中的 capabilities.workspace.* 表。

形态 B-lite：单链工作区（iframe / 嵌入）

想要 workspace 的链加载/保存/草稿能力，但只要单链、不要顶栏与多 tab：

<template>
  <RuleGoWorkspace ref="workspaceRef" :options="options" />
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { RuleGoWorkspace } from '@rulego/editor'
import '@rulego/editor/style.css'

const workspaceRef = ref()
const options = {
  mode: 'app',
  url: 'http://127.0.0.1:9090',
  capabilities: {
    workspace: {
      topBar: false,         // 去顶栏
      tabs: false,           // 去多 tab
      chainSwitcher: false,  // 关 Ctrl+P
      globalSearch: false,   // 关 Ctrl+Shift+F
      sessionRestore: false, // 不恢复会话，按 chainId 显式打开
    }
  }
}

onMounted(() => {
  // 显式打开指定链
  workspaceRef.value?.openChain('your-chain-id')
})
</script>

与形态 A 的区别：链的加载/保存/草稿/dirty 跟踪交给 workspace（调用 workspaceRef.openChain(id)），宿主不用自己写 getWorkflow/save 逻辑。

iframe 嵌入

editor 支持通过 iframe 嵌入到任何宿主页面（React / Angular / 原生 HTML 等）。

方式一：URL 参数（最简单，零前端代码）

editor 独立部署后，直接在 iframe 的 src 中传参：

<iframe
  src="http://your-server:9090/?mode=single&chainId=xxx&token=xxx"
  style="width:100%;height:100vh;border:none"
></iframe>

参数	说明
mode=single	切单链形态（默认 app，全功能工作区）
chainId=xxx	打开指定规则链
token=xxx	租户/鉴权 key，写入 localStorage，由 http 拦截器自动带 Authorization: Bearer 头
apiBase=xxx	显式指定后端地址（跨域部署时必填，同源可省略）

方式二：宿主 Vue 应用内嵌（形态 B-lite）

见上方 形态 B-lite。

方式三：跨源 iframe（后端在不同域名）

当 editor 和 rulego-server 不在同一个域名时：

1. src 中必须带 apiBase 参数指向后端地址
2. 后端必须开启 CORS（allow_cors = true，默认已开启）
3. 后端不要设置 X-Frame-Options: DENY 或 Content-Security-Policy: frame-ancestors 'none'
4. 建议通过 token 参数传递鉴权 token

<iframe
  src="http://editor-host:3000/?mode=single&chainId=xxx&token=xxx&apiBase=http://api-host:9090"
  style="width:100%;height:100vh;border:none"
></iframe>

iframe 通信

当前版本不提供 postMessage 协议层，iframe 内的 editor 自行与后端通信。如需宿主页面控制 iframe 内的 editor（如切换链、触发保存），建议通过 URL 参数传入初始配置，或直接调用后端 API（如 POST /api/v1/rules/{id} 保存）。

---

能力开关（mode + capabilities）

编辑器用「能力树」表达形态：粗粒度的 mode 覆盖多数场景，细粒度的 capabilities 按需覆盖单项。

EditorMode（粗粒度形态）

mode	含义	典型用法
'standalone'	默认基线，工具栏/AI 面板全开	RuleGoEditor 单画布的默认形态
'app'	工作区形态，多 tab + 底 dock + 租户管理	RuleGoWorkspace 的默认形态
'embedded'	嵌入形态，去工具栏/标题、链打开交宿主、不注册 beforeunload	宿主嵌入单画布
'readonly'	只读，去工具栏、editor.readOnly=true、保存只 emit	链路展示/预览

const options = {
  mode: 'embedded',       // 一行选定形态
  url: 'http://127.0.0.1:9090',
}

capabilities（细粒度覆盖）

options.capabilities 是一棵对象树，任意层级可选，未给的走 mode 基线。优先级：显式 capabilities > 老 props > mode 基线。

const options = {
  mode: 'app',
  capabilities: {
    ui: { chat: false },                    // 关 AI 助手面板（默认开）
    workspace: { tabs: false, dock: true }, // 关多 tab、开底 dock
  },
}

ui.*（画布层 UI）

字段	类型	standalone 默认	app 默认	说明
toolbar	boolean	true	true	内置工具栏（LogicFlow 扩展）
sidebar	boolean	true	true	内置组件面板（LogicFlow 扩展）。宿主自渲染唯一一份时关掉
minimap	boolean	true	true	小地图
commandPalette	boolean	true	true	命令面板
contextMenu	boolean	true	true	右键菜单
header	boolean	true	true	工具栏里的标题区
statusBar	boolean	true	true	画布右下角状态条（缩放/节点数/选中数/诊断数）
chat	boolean	true	true	AI 助手面板。工作区形态下会话跟随活动 tab 切换
tour	boolean	true	true	新手引导（空画布入口 + 命令面板项；readonly 形态为 false）
nodeActions	boolean	true	true	节点/连线选中后浮出的 HTML 操作手柄（编辑/删除/运行 等）
nodeRunFrom	boolean	true	true	选中手柄与右键菜单上的「从此节点运行」
runFromDock	boolean	false	false	「从此节点运行」是否交给外层 shell/workspace 的右 dock 调试面板（嵌入 shell 时自动开启，宿主无需配）
legacyNodeDrawer	boolean	false	false	双击节点是否弹旧版模态抽屉。默认 false：编辑走右 dock 配置 tab。宿主要保留旧行为显式传 true

editor.*

字段	类型	说明
readOnly	boolean	只读模式

features.*

字段	类型	说明
hostOwnsChainOpen	boolean	true 时编辑器不替换自己的画布，改 emit(open-chain, id) 交宿主处理

persistence.*

字段	类型	说明
saveToServer	boolean	false 时保存只 emit，由宿主落库
syncUrlHash	boolean	保存时是否同步 URL hash
warnOnUnload	boolean	是否自己注册 beforeunload。多 tab 宿主应关掉，由宿主统一问一次

workspace.*（仅 RuleGoWorkspace 消费，RuleGoEditor 忽略）

字段	standalone 默认	app 默认	说明
topBar	true	true	顶栏（连接灯/保存/部署/⋯菜单/用户）。关掉后保存与部署要宿主自己提供入口
explorer	true	true	左 dock：资源管理（规则链/子规则链/共享节点三分区）
palette	true	true	左 dock：组件库。关掉后 editor 显示自己内置的 palette（二者互斥）
sharedNodes	false	false	资源管理面板内的「共享节点」分区。关掉时工作区连列表都不请求
information	true	true	右 dock tab：信息（选中对象的只读速览）
nodeConfigPanel	true	true	右 dock tab：配置/日志/文档（单击节点即编辑配置，表单改动自动回传画布）
problems	true	true	右 dock tab：诊断（拓扑问题，点条目定位到节点）
runDebug	true	true	右 dock tab：调试（填参发送消息执行规则链）
dock	false	true	底 dock（运行记录/调试控制台）。关掉后这些功能退回 editor 自己的弹窗
tabs	false	true	多 tab。关掉后 TabBar 不渲染，切链直接替换画布
globalSearch	true	true	Ctrl+Shift+F 跨规则链搜索
chainSwitcher	true	true	Ctrl+P 规则链切换浮层
drafts	true	true	本地草稿自动存（按 username.chainId 分键）
conflictDetection	true	true	保存前用内容指纹比对服务端，检测并发覆盖（弱乐观锁）
sessionRestore	true	true	刷新后恢复上次打开的 tab 集合
admin	false	true	租户管理入口。server 专属，宿主自备账号体系时关掉

与老 props 的关系：options.toolbar.showXxx（见 toolbar 配置）、顶层 updateUrl、disabled 仍有效，由 resolveCapabilities 内部转译为能力树。老集成方零改动；新集成推荐用 mode + capabilities。

---

组件 Props

RuleGoEditor：

属性	类型	必选	说明
data	object	否	RuleGo 规则链配置数据，用于渲染流程图
options	object	否	编辑器配置选项，详见 options 属性
extensions	array	否	LogicFlow 扩展插件数组
disabled	boolean	否	只读（老 props，内部转译为 editor.readOnly）
updateUrl	boolean	否	是否启用保存时更新 URL（老 props，内部转译为 persistence.syncUrlHash）

RuleGoWorkspace：

属性	类型	必选	说明
options	object	否	同 RuleGoEditor 的 options，额外支持 logoUrl
panels	array	否	面板集合，缺省 BUILTIN_PANELS。传 [...BUILTIN_PANELS, myPanel] 即可扩展，详见 导出清单
layoutKey	string	否	dock 布局持久化命名空间；多账号同浏览器时用它隔离

RuleGoShell：

属性	类型	说明
panels	array	面板集合
ctx	object	面板上下文（可由 useSingleChainShell 组装）
capabilities	object	能力树
chainInfo	object	当前链信息
serverStatus / busy / username / roles / logoUrl / lf / layoutKey	-	详见类型声明

---

data 属性

data 属性接受 RuleGo 规则链配置 JSON 对象，用于渲染流程图。如果不提供，则工作区为初始化状态。

数据格式参考：规则链配置 (opens new window)

const data = {
  ruleChain: {
    id: 'chain-001',
    name: '我的规则链',
    root: true,
  },
  metadata: {
    firstNodeIndex: 0,
    nodes: [
      {
        id: 'node-1',
        type: 'endpoint/rest/api',
        name: 'REST API',
        configuration: {},
      },
    ],
    connections: [
      {
        fromId: 'node-1',
        toId: 'node-2',
        type: 'Success',
      },
    ],
  },
}

---

options 属性

options 属性用于配置编辑器的行为、API 地址、工具栏按钮显隐等。

服务端 API 配置

字段	类型	必选	默认值	说明
url	string	否	http://127.0.0.1:9090	RuleGo 服务交互 API 根路径
componentsApi	string	否	/api/v1/components	获取组件列表 API 路径
debugDataApi	string	否	/api/v1/logs/debug	获取调试日志 API 路径
executeApi	string	否	/api/v1/rules/:id/execute/:msgType	执行规则链 API 路径，:id 和 :msgType 为占位符
notifyApi	string	否	/api/v1/rules/:id/notify/msgType	通知消息 API 路径
chainsApi	string	否	/api/v1/rules	规则链 CRUD API 路径
loadComponentsFromApi	boolean	否	true	是否从 API 动态加载组件列表
loadEndpointComponents	boolean	否	true	是否加载端点(endpoint)类型组件

形态与能力

字段	类型	必选	默认值	说明
mode	string	否	standalone	编辑器形态，取值 standalone/app/embedded/readonly，详见 能力开关
capabilities	object	否	-	细粒度能力开关，优先级高于 mode 与老 props
disabled	boolean	否	false	只读（老 props）
getToken	function	否	-	自定义 token 获取（老 props，推荐用 setTokenProvider）
clearToken	function	否	-	自定义 token 清除（老 props）
iconsUrl	string	否	-	组件图标基础路径
showPropertyDialogOnDndAdd	boolean	否	false	拖入节点后是否自动弹出属性配置面板（置 true 恢复旧行为）
lang	string	否	zh	语言 zh/en
baseUrl	string	否	-	后端 API 基础路径（同 url）

布局配置

字段	类型	必选	默认值	说明
startX	number	否	280	第一个 INPUT 节点的 X 坐标
startY	number	否	280	第一个 INPUT 节点的 Y 坐标
topOffset	number	否	100	顶部偏移量
relationTypeSplit	string	否	/	节点关系类型分隔符
endpointRelationTypeSplit	string	否	\n	端点关系类型分隔符

LogicFlow 配置

以下选项直接透传给 LogicFlow 实例，详见 LogicFlow 文档 (opens new window)。

字段	类型	必选	默认值	说明
adjustEdge	boolean	否	true	允许拖拽调整连线
adjustEdgeStartAndEnd	boolean	否	true	允许调整连线的起点和终点
textEdit	boolean	否	false	允许双击编辑文本
stopMoveGraph	boolean	否	false	禁止拖动画布
hoverOutline	boolean	否	false	悬停时显示节点外框
edgeSelectedOutline	boolean	否	false	连线选中时显示外框
allowResize	boolean	否	true	允许调整节点大小
keyboard	object	否	-	键盘快捷键配置，enabled 默认为 true

网格配置

字段	类型	必选	默认值	说明
grid	object	否	{ visible: true, type: 'mesh', size: 10, config: { color: '#eeeeee' } }	画布网格配置

grid 对象字段说明：

字段	类型	说明
visible	boolean	是否显示网格
type	string	网格类型，可选值：mesh、dot
size	number	网格大小
config	object	网格样式配置，如 { color: '#eeeeee' }

国际化配置

字段	类型	必选	默认值	说明
locales	object	否	{}	自定义国际化文本
setting	object	否	{}	编辑器设置项

组件配置

字段	类型	必选	默认值	说明
builtinComponents	object	否	{ builtins: {}, endpoints: [], nodes: [] }	内置组件定义
components	object	否	{ endpoints: [], nodes: [] }	自定义组件列表，格式参考 节点组件

---

toolbar 配置

options.toolbar 用于控制工具栏中各按钮的显示与隐藏，是细粒度覆盖（能力树 ui.toolbar 的子项）。所有字段均为可选 Boolean 类型，默认值为 true。

字段	类型	默认值	说明
showTile	boolean	true	是否显示规则链标题
showSelection	boolean	true	是否显示【框选】按钮
showUndo	boolean	true	是否显示【撤销】按钮
showRedo	boolean	true	是否显示【重做】按钮
showMinMap	boolean	true	是否显示【小地图】按钮
showTest	boolean	true	是否显示【运行】按钮
showSetting	boolean	true	是否显示【设置】按钮
showFullScreen	boolean	true	是否显示【全屏】按钮
showNew	boolean	true	是否显示【设置-新建】按钮
showOpen	boolean	true	是否显示【设置-打开】按钮
showEdit	boolean	true	是否显示【设置-编辑】按钮
showIntegration	boolean	true	是否显示【设置-集成】按钮
showExport	boolean	true	是否显示【设置-导出】按钮
showImport	boolean	true	是否显示【设置-导入】按钮
showNodeMgt	boolean	true	是否显示【设置-组件管理】按钮
showSharedNodeMgt	boolean	true	是否显示【设置-共享节点管理】按钮
showUserSetting	boolean	true	是否显示【设置-用户设置】按钮
showAbout	boolean	true	是否显示【设置-关于】按钮
showDoc	boolean	true	是否显示【设置-文档】按钮（当前版本已隐藏）
showSave	boolean	true	是否显示【保存】按钮
showReset	boolean	true	是否显示【重置】按钮
showDelete	boolean	true	是否显示【删除选定】按钮
showAiChat	boolean	true	是否显示【AI 助手】按钮
showDebugConsole	boolean	true	是否显示【调试控制台】按钮
showClearDebugHighlight	boolean	true	是否显示【清除调试高亮】按钮

示例：只保留保存和导出功能

const options = ref({
  toolbar: {
    showSelection: false,
    showUndo: false,
    showRedo: false,
    showMinMap: false,
    showTest: false,
    showSetting: false,
    showFullScreen: false,
    showNew: false,
    showOpen: false,
    showEdit: false,
    showIntegration: false,
    showImport: false,
    showNodeMgt: false,
    showUserSetting: false,
    showAbout: false,
    showDelete: false,
    showReset: false,
    showAiChat: false,
    showDebugConsole: false,
    showClearDebugHighlight: false,
    // 保留以下按钮
    showTile: true,
    showSave: true,
    showExport: true,
  },
})

---

extensions 属性

extensions 属性接受 LogicFlow 扩展插件数组，用于扩展编辑器功能。传入后编辑器会在初始化时注册这些扩展。

import { DndPanel, SelectionSelect } from '@logicflow/extension'

const extensions = ref([
  DndPanel,
  SelectionSelect,
])

<RuleGoEditor
  ref="ruleGoEditorRef"
  :extensions="extensions"
/>

LogicFlow 内置扩展参考：LogicFlow 扩展 (opens new window)

---

config.js 配置文件

编辑器内置了 config.js 配置文件，定义了 AI 聊天功能的默认参数。如需自定义，可在源码中修改。

字段	类型	默认值	说明
maxHistoryPerChain	number	50	每条规则链最大聊天历史记录数
maxContextMessages	number	20	发送给 AI 的最大上下文消息数
maxMessageLength	number	2000	单条消息最大字符数
storageKeyPrefix	string	rulego-chat-history-	本地存储 key 前缀
maxActiveChains	number	20	最大活跃规则链聊天会话数

---

AI 服务商配置

RuleGo-Editor 内置了多个 AI 服务商，可在 AI 助手面板中选择使用。所有服务商均兼容 OpenAI Chat Completions API 格式。

内置服务商列表

服务商	ID	默认 API 地址	默认模型
Gitee AI	gitee_ai	https://ai.gitee.com/v1	DeepSeek-V4-Flash
DeepSeek	deepseek	https://api.deepseek.com	deepseek-chat
通义千问	qwen	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-plus
智谱 AI	zhipu	https://open.bigmodel.cn/api/paas/v4	glm-5
OpenAI	openai	https://api.openai.com/v1	gpt-4o
Ollama (本地)	ollama	http://localhost:11434/v1	llama3

使用方式

在 AI 助手面板中，用户可以：

1. 选择 AI 服务商
2. 填写 API Key（Ollama 本地部署无需 API Key）
3. 选择模型
4. 自定义 API 地址（可选）

详细介绍参考 AI 功能。

---

Token 管理

当 RuleGo-Editor 对接需要认证的后端服务时，通过 @rulego/editor 导出的 token 管理方法配置。编辑器内置 http 拦截器从 localStorage.token / localStorage.access_token 读取，请求头加 Authorization: Bearer <token>；宿主自管鉴权时注入自己的 token 提供器。

API

import {
  setTokenProvider,
  addResponseInterceptor,
  getToken,
  clearToken,
} from '@rulego/editor'

setTokenProvider({
  getToken: () => string | null,    // 获取 Token 的函数
  clearToken: () => void,           // 清除 Token 的函数（如 token 过期时调用）
})

// 适配非标准响应包：注入响应拦截器，把后端返回包规整成 editor 期望的结构
addResponseInterceptor((response) => {
  // 例：后端把真实数据包了一层 { code, data }
  return response.data ?? response
})

集成示例

<script setup>
import { RuleGoEditor, setTokenProvider } from '@rulego/editor'
import '@rulego/editor/style.css'
import { ref, onMounted } from 'vue'

// 配置 Token 提供者
onMounted(() => {
  setTokenProvider({
    getToken: () => localStorage.getItem('auth_token'),
    clearToken: () => {
      localStorage.removeItem('auth_token')
      // 可在此处跳转登录页
    },
  })
})

const options = ref({
  url: 'https://your-rulego-server.com',
  loadComponentsFromApi: true,
})
</script>

当后端返回 401 状态码时，编辑器会自动调用 clearToken 清除过期 Token。

工作区形态（形态 B）内置全屏登录页：后端开启 require_auth 且请求返回 401 时自动弹出；顶栏用户菜单也提供 login / logout 命令。

API 地址自适应

resolveBaseUrl()（源码 src/components/config/config.js）按以下优先级解析后端地址，前后端同源部署时无需任何配置：

1. URL 参数 ?apiBase=xxx —— iframe 场景显式指定
2. localStorage 用户手动设置 —— SettingDialog 里填的
3. public/config/config.js 的 baseUrl —— 部署期静态配置
4. window.location.origin —— 同源兜底（editor 产物由 rulego-server 托管时自动命中）
5. http://127.0.0.1:9090 —— 开发环境兜底

跨源部署时只需配 1/2/3 任一项；同源部署零配置。

---

事件

RuleGoEditor 通过 Vue emit 向宿主通信：

事件名	说明	回调参数
saveOk	保存成功	data：规则链数据
saveError	保存失败	data：规则链数据，e：错误信息
reset	重置规则链	data：规则链数据
updateLocales	更新国际化	locales：国际化数据
dirty-change	脏态变化。宿主据此在 tab 上打脏点	dirty：boolean
open-chain	请求打开另一条链。仅 features.hostOwnsChainOpen 为 true 时发出	chainId：string
request-info	请求打开链元信息/集成弹窗，宿主接管	chainId：string
selection-change	选中元素变化	payload：选中项信息
sidebar-toggled	组件面板折叠态变化（把手点击、Ctrl+B、宿主调 setSidebarExpanded 都会发）	{ expanded: boolean }

使用示例

<template>
  <RuleGoEditor
    :options="options"
    @saveOk="onSaveOk"
    @saveError="onSaveError"
    @reset="onReset"
    @updateLocales="onUpdateLocales"
    @dirty-change="onDirtyChange"
    @open-chain="onOpenChain"
    @selection-change="onSelectionChange"
  />
</template>

<script setup>
const onSaveOk = (data) => console.log('规则链保存成功', data)
const onSaveError = (data, e) => console.error('规则链保存失败', e)
const onReset = (data) => console.log('规则链已重置', data)
const onUpdateLocales = (locales) => console.log('国际化已更新', locales)
const onDirtyChange = (dirty) => console.log('脏态:', dirty)
const onOpenChain = (chainId) => console.log('请求打开链:', chainId)
const onSelectionChange = (payload) => console.log('选中变化:', payload)
</script>

编辑器内部各模块（工具栏、侧边栏等独立 Vue 应用实例）之间还通过 LogicFlow eventCenter 通信，那套是内部事件，库消费方一般用不到。如需监听画布元素事件（节点/边点击等），通过 ruleGoEditorRef.value.lf 的 LogicFlow 实例 API，详见 事件系统。

---

方法

通过组件引用（ref）调用 RuleGoEditor 暴露的方法：

方法名	说明	调用参数	返回值
render	渲染规则链	data：规则链数据	-
save	触发保存	-	-
getData	获取当前规则链数据	-	规则链 data JSON 对象
setLocales	设置国际化文本	locales：国际化配置对象	-
lf	获取 LogicFlow 实例（属性，非函数）	-	LogicFlow 实例 (opens new window)
reloadComponents	重新加载组件列表	-	-
openChain	命令式打开一条链（传 id 或完整 DSL）	idOrData：string | object	-
isDirty	是否有未保存修改（ComputedRef）	-	ComputedRef<boolean>
capabilities	解析后的能力对象（ComputedRef）	-	ComputedRef<EditorCapabilities>
invokeAction	转发本实例的动作注册表，供宿主命令面板/菜单复用编辑器动作	id：string, ...args	boolean（动作不存在返回 false）
listActions	列出已注册动作	-	EditorAction[]
setSidebarExpanded	设置组件面板展开态（用于多 tab 宿主把折叠态同步到每个实例）	expanded：boolean	-

使用示例

<template>
  <RuleGoEditor ref="ruleGoEditorRef" :options="options" />
  <button @click="handleSave">保存</button>
  <button @click="handleGetData">获取数据</button>
</template>

<script setup>
import { RuleGoEditor } from '@rulego/editor'
import '@rulego/editor/style.css'
import { ref, onMounted } from 'vue'

const ruleGoEditorRef = ref()
const options = ref({
  url: 'http://127.0.0.1:9090',
})

// 获取 LogicFlow 实例，调用原生 API（lf 是属性，不是函数）
onMounted(() => {
  const lf = ruleGoEditorRef.value.lf
  if (lf) {
    // 例如：监听节点点击事件
    lf.on('node:click', ({ data }) => {
      console.log('节点被点击', data)
    })
  }
})

const handleSave = () => ruleGoEditorRef.value.save()
const handleGetData = () => {
  const data = ruleGoEditorRef.value.getData()
  console.log('当前规则链数据', JSON.stringify(data, null, 2))
}
</script>

---

导出清单

@rulego/editor 导出约 50 个符号。完整声明见库附带的 index.d.ts 与 workspace-types.d.ts。

组件

导出名	说明	典型用途
RuleGoEditor (default)	单画布编辑器	形态 A，宿主自管规则链生命周期
RuleGoWorkspace	工作区容器（顶栏 + 三 dock + 画布）	形态 B / B-lite
RuleGoShell	dock 布局外壳（无画布，slot 插入画布）	形态 A，宿主自管但要 dock 面板
PanelDock	单个 dock 容器（左/右/底）	宿主自建布局
PanelShell	单面板壳（标题栏 + 折叠 + 动作位）	宿主自建布局

面板零件

导出名	说明
NodePalette	组件面板（LogicFlow 扩展外壳）
PaletteCore	纯组件面板（零 lf 依赖，宿主自备数据）
PaletteSection	工作区组件面板（自带取数）
ChainExplorerPanel	资源管理面板
InformationPanel	说明面板（只读速览）
ProblemsPanel	诊断面板
RunHistoryPanel	运行记录面板
SendMessagePanel	发送消息面板
RunCasesPanel	运行调试面板
DebugConsole	调试控制台
DocBrowser	文档浏览器
ChainManager	规则链管理表（搜索/分类/部署/删除）
Marketplace	规则链市场
WorkspaceTopBar	工作区顶栏
WorkspaceTabBar	工作区 tab 条
RgEmpty	空状态组件
RgSkeleton	骨架屏组件

Composable

导出名	说明
useTabPool	tab 池（8 上限 + LRU + pinned + 拖拽重排）
useDrafts	本地草稿（按 username.chainId 分键）
useServerStatus	后端连通性探测（附带 SERVER_STATUS_KEY）
useTheme	深浅色主题
useSingleChainShell	单链 Shell ctx 组装器
useDockLayout	dock 布局状态（尺寸/开合/折叠/显隐）
useDebugWebSocket	调试 WebSocket（按 chainId 隔离）

工具函数

导出名	说明
resolveCapabilities	解析能力树（mode + capabilities + 老 props）
CAPABILITY_BASE	能力树基线
CAPABILITY_PROFILES	预设 profile 集合
createActionRegistry	动作注册表工厂
BUILTIN_PANELS	内置面板集合（10 个）
resolvePanels	面板分组/过滤/排序
DOCKS	dock 槽位名
setTokenProvider	注入 token 提供器
addResponseInterceptor	注入响应拦截器
getToken / clearToken	获取/清除 token
fingerprintOf / isConflicting	保存冲突检测
createNotifier / errorIdOf	通知去重
buildChainTree / byRecent	规则链树组装
loadCases / saveCase / deleteCase / clearCases	命名测试用例

面板注册表契约

宿主注册自定义面板时需实现 PanelDefinition：

interface PanelDefinition {
  id: string                              // 唯一标识
  dock: 'left' | 'right' | 'bottom'      // 槽位
  title: string                           // 标题
  order?: number                          // 同槽内排序（默认 100）
  capability?: string                     // 关联的能力开关名
  component: Component                    // Vue 组件
  defaultOpen?: boolean                   // 默认展开（默认 true）
  grow?: boolean | number                 // 是否吃剩余空间（数字当权重）
  actions?: PanelAction[]                 // 标题栏动作按钮
  props?: (ctx: PanelContext) => object   // 从上下文取 props
  on?: (ctx: PanelContext) => object      // 事件处理表
  key?: (ctx: PanelContext) => string     // 返回值变化时重新挂载
}

PanelContext 只读暴露 activeChainId / baseUrl / chain / dsl / nodeCount / chains / loadingChains / chainsError / sharedNodes / openedIds / dirtyIds / selection / lf / locales / offline / busy / capabilities / editorContext / response / runCount / fromNodeId / onlyThisNode，以及方法 openChain / createChain / reloadChains / operateChain / deleteChain / renameChain / exportChain / openChainInfo / runCase / openSendPanel / openHistory。不暴露 tab 池与工作区内部状态（守分层纪律）。

扩展面板示例：

import { RuleGoWorkspace, BUILTIN_PANELS } from '@rulego/editor'
import MyDevicePanel from './MyDevicePanel.vue'

const panels = [...BUILTIN_PANELS, {
  id: 'devices',
  dock: 'left',
  title: '设备',
  capability: 'devices',  // 配套 capabilities.workspace.devices = true 才显示
  component: MyDevicePanel,
  props: (ctx) => ({ chains: ctx.chains, activeChainId: ctx.activeChainId }),
}]

---

高级配置示例

最小化嵌入（只读展示）

适合在已有系统中展示规则链，隐藏所有编辑功能。推荐用 mode: 'readonly'：

<template>
  <RuleGoEditor :data="ruleChainData" :options="readOnlyOptions" />
</template>

<script setup>
import { RuleGoEditor } from '@rulego/editor'
import '@rulego/editor/style.css'
import { ref } from 'vue'

const ruleChainData = ref({ /* 规则链数据 */ })

const readOnlyOptions = ref({
  mode: 'readonly',
  url: 'http://127.0.0.1:9090',
  loadComponentsFromApi: false,
})
</script>

等价的细粒度写法（关工具栏各项）：

const readOnlyOptions = ref({
  loadComponentsFromApi: false,
  toolbar: {
    showSelection: false, showUndo: false, showRedo: false, showTest: false,
    showSetting: false, showNew: false, showOpen: false, showEdit: false,
    showDelete: false, showSave: false, showReset: false, showAiChat: false,
    showDebugConsole: false, showClearDebugHighlight: false, showExport: false,
    showImport: false, showNodeMgt: false, showSharedNodeMgt: false,
    showUserSetting: false, showIntegration: false, showAbout: false, showDoc: false,
    showTile: true, showMinMap: true, showFullScreen: true,
  },
  stopMoveGraph: false,
})

自定义 API 地址与认证

对接自部署的 RuleGo 后端服务，并配置 Token 认证：

<template>
  <RuleGoEditor
    ref="ruleGoEditorRef"
    :options="options"
    @saveOk="onSaveOk"
    @saveError="onSaveError"
  />
</template>

<script setup>
import { RuleGoEditor, setTokenProvider } from '@rulego/editor'
import '@rulego/editor/style.css'
import { ref, onMounted } from 'vue'

const ruleGoEditorRef = ref()

onMounted(() => {
  setTokenProvider({
    getToken: () => localStorage.getItem('token'),
    clearToken: () => {
      localStorage.removeItem('token')
      window.location.href = '/login'
    },
  })
})

const options = ref({
  url: 'https://api.example.com',
  componentsApi: '/api/v1/components',
  chainsApi: '/api/v1/rules',
  executeApi: '/api/v1/rules/:id/execute/:msgType',
  debugDataApi: '/api/v1/logs/debug',
  loadComponentsFromApi: true,
  loadEndpointComponents: true,
})

const onSaveOk = (data) => console.log('保存成功', data)
const onSaveError = (data, e) => console.error('保存失败', e)
</script>

完整配置参考

以下为包含所有常用配置项的完整示例：

const options = {
  // 形态与能力（推荐）
  mode: 'standalone',
  // capabilities: { ui: {...}, workspace: {...} },

  // 服务端 API
  url: 'http://127.0.0.1:9090',
  componentsApi: '/api/v1/components',
  debugDataApi: '/api/v1/logs/debug',
  executeApi: '/api/v1/rules/:id/execute/:msgType',
  notifyApi: '/api/v1/rules/:id/notify/msgType',
  chainsApi: '/api/v1/rules',
  loadComponentsFromApi: true,
  loadEndpointComponents: true,

  // 布局
  startX: 280,
  startY: 280,
  topOffset: 100,
  relationTypeSplit: '/',
  endpointRelationTypeSplit: '\n',

  // 网格
  grid: {
    visible: true,
    type: 'mesh',
    size: 10,
    config: { color: '#eeeeee' },
  },

  // LogicFlow 选项
  adjustEdge: true,
  adjustEdgeStartAndEnd: true,
  textEdit: false,
  stopMoveGraph: false,
  hoverOutline: false,
  edgeSelectedOutline: false,
  allowResize: true,
  keyboard: { enabled: true, shortcuts: [] },

  // 国际化与组件
  locales: {},
  builtinComponents: { builtins: {}, endpoints: [], nodes: [] },
  components: { endpoints: [], nodes: [] },
  setting: {},

  // 工具栏（细粒度覆盖；推荐用 mode + capabilities 替代）
  toolbar: {
    showTile: true,
    showSelection: true,
    showUndo: true,
    showRedo: true,
    showMinMap: true,
    showTest: true,
    showSetting: true,
    showFullScreen: true,
    showNew: true,
    showOpen: true,
    showEdit: true,
    showIntegration: true,
    showExport: true,
    showImport: true,
    showNodeMgt: true,
    showSharedNodeMgt: true,
    showUserSetting: true,
    showAbout: true,
    showDoc: true,
    showSave: true,
    showReset: true,
    showDelete: true,
    showAiChat: true,
    showDebugConsole: true,
    showClearDebugHighlight: true,
  },
}

自定义 LogicFlow 扩展

结合 LogicFlow 扩展插件，增强编辑器能力：

<template>
  <RuleGoEditor
    ref="ruleGoEditorRef"
    :options="options"
    :extensions="extensions"
  />
</template>

<script setup>
import { RuleGoEditor } from '@rulego/editor'
import '@rulego/editor/style.css'
import { ref, onMounted } from 'vue'

const ruleGoEditorRef = ref()
const extensions = ref([])

const options = ref({
  url: 'http://127.0.0.1:9090',
  // 启用键盘快捷键
  keyboard: {
    enabled: true,
    shortcuts: [
      { keys: 'ctrl+z', callback: 'undo' },
      { keys: 'ctrl+shift+z', callback: 'redo' },
    ],
  },
  // 自定义网格样式
  grid: {
    visible: true,
    type: 'dot',
    size: 20,
    config: { color: '#d0d0d0' },
  },
})

onMounted(() => {
  // 通过 lf 实例调用 LogicFlow 原生方法（lf 是属性，不是函数）
  const lf = ruleGoEditorRef.value.lf
  if (lf) {
    // 自定义右键菜单等高级功能
    lf.extension.menu.setMenuConfig({
      nodeMenu: [
        { text: '复制', callback: (node) => { lf.cloneNode(node.id) } },
        { text: '删除', callback: (node) => { lf.deleteNode(node.id) } },
      ],
      edgeMenu: [
        { text: '删除', callback: (edge) => { lf.deleteEdge(edge.id) } },
      ],
      graphMenu: [],
    })
  }
})
</script>

---

后端要求

rulego-server（默认后端）

editor 默认对接 rulego-server 的 REST API（/api/v1/*）。后端默认配置已满足多数场景：

配置项	默认值	说明
allow_cors	true	跨域资源共享（iframe 跨源部署时必须开启）
base_path	空	API 路由前缀，嵌入式部署时设为 /rulego 避免路由冲突
require_auth	false	鉴权开关。关闭时未带 token 的请求以 default_username（默认 admin）身份放行；开启后 401 时 editor 弹全屏登录页

iframe 嵌入的后端注意事项

1. CORS：跨源 iframe 部署时，后端必须开启 allow_cors = true（默认已开启）
2. 安全头：不要设置 X-Frame-Options: DENY 或 Content-Security-Policy: frame-ancestors 'none'，否则 iframe 无法加载
3. Cookie：如使用 cookie 鉴权，需设置 SameSite=None; Secure（HTTPS 场景）
4. 单二进制部署：editor 产物已通过 go:embed 打入 server 二进制，http://server:9090/ 直接访问即可

自定义后端

editor 的 API 调用集中在 src/components/api/ 下。支持任意后端的最佳方式是实现与 rulego-server 相同的 REST API 路径（/api/v1/*），或通过反向代理转发；如需适配非标准响应包，用 Token 管理 中的 addResponseInterceptor 规整。