RuleGo-Editor 提供了完整的调试功能，支持实时查看规则链执行过程、节点状态高亮、调试日志输出等功能。调试功能基于 WebSocket 连接实现，能够实时接收后端推送的调试数据。

调试功能概览

调试功能主要包含以下模块：

模块	组件/Composable	说明
WebSocket 调试连接	useDebugWebSocket.js	建立 WebSocket 连接，接收实时调试数据
画布调试高亮	useCanvasDebug.js	在画布上高亮显示节点执行状态
调试控制台	DebugConsole.vue	实时显示调试日志，支持过滤和折叠
运行面板	RunPanel.vue	发送测试数据并查看执行结果
执行历史	RunHistory.vue	查看历史执行记录

---

WebSocket 调试连接

基本用法

useDebugWebSocket Composable 用于建立与 RuleGo 后端的 WebSocket 连接，实时接收调试数据。

import { useDebugWebSocket } from '@rulego/editor'

// 建立调试连接
const { status, data, connect, disconnect, clearData, reconnect } = useDebugWebSocket(chainId, wsConfig)

参数说明

参数	类型	必选	说明
chainId	string	是	规则链 ID，用于标识调试的目标规则链
wsConfig	object	否	WebSocket 配置对象，详见下方配置表

wsConfig 配置项

字段	类型	默认值	说明
baseUrl	string	-	WebSocket 服务地址，如 ws://127.0.0.1:9090

返回值

字段	类型	说明
status	Ref<string>	连接状态：connecting、connected、disconnected、error
data	Ref<Array>	接收到的调试数据数组（最多缓冲 500 条，超出裁剪）
connect	Function	建立连接方法
disconnect	Function	断开连接方法
clearData	Function	清空已缓冲的调试数据
reconnect	Function	手动重连

连接状态说明

状态	说明
connecting	正在建立连接
connected	连接成功
disconnected	连接已断开
error	连接错误

WebSocket URL 格式

WebSocket 连接 URL 格式为：

{baseUrl}/api/v1/logs/ws/{chainId}/{clientId}

• baseUrl：WebSocket 服务地址，自动将 http 转换为 ws
• chainId：当前规则链 ID
• clientId：客户端唯一标识，自动生成

地址配置优先级

WebSocket 地址按以下优先级获取：

1. wsConfig.baseUrl 参数
2. window.rulegoEditorConfig.wsUrl 全局配置
3. window.rulegoEditorConfig.baseUrl（自动转换 http 为 ws）
4. 默认地址：ws://127.0.0.1:9090

全局配置示例

在 HTML 中通过全局变量配置 WebSocket 地址：

<script>
  window.rulegoEditorConfig = {
    baseUrl: 'http://127.0.0.1:9090',
    // 或直接指定 wsUrl
    wsUrl: 'ws://127.0.0.1:9090'
  }
</script>

自动重连机制

WebSocket 连接支持自动重连功能：

• 最大重试次数：10 次
• 重连间隔：采用指数退避策略
• 重连触发条件：连接意外断开时自动尝试重连

JWT Token 认证

当后端服务需要认证时，支持通过 URL query 参数传递 JWT Token：

ws://127.0.0.1:9090/api/v1/logs/ws/chain-001/client-123?token=eyJhbGciOiJIUzI1NiIs...

Token 获取方式与 HTTP 请求一致，通过 setTokenProvider 配置的 getToken 函数获取。

---

调试高亮功能

基本用法

useCanvasDebug Composable 在画布上高亮显示节点的执行状态。它是自驱动的：内部 watch(lfRef)，就绪后在 LogicFlow eventCenter 上注册 DEBUG_DATA 事件监听，每条调试数据到达时自动设置节点状态、高亮流动的边、累计运行指标——调用方不需要手动逐节点设状态。

注意：useCanvasDebug 与 EDITOR_EVENTS 都是内部模块，未从 @rulego/editor 公共入口导出，仅供二次开发（改源码）使用。库消费方调试高亮由 editor 内置自动完成，无需自行接入。

// 仅二次开发场景：内部路径
import { useCanvasDebug } from '../hooks/useCanvasDebug'

const { clearHighlight, highlightedNodes, highlightedEdges } = useCanvasDebug(lfRef, chainId)

参数说明

参数	类型	必选	说明
lfRef	Ref<LogicFlow>	是	LogicFlow 实例引用
chainId	string | Ref<string>	是	当前规则链 ID，用于过滤跨链调试事件（子链 nodeId 与主链重名时不误高亮）

返回值

字段	类型	说明
clearHighlight	Function	清除所有节点状态、边高亮与运行指标（不收 lf 参数，内部读 lfRef.value）
highlightedNodes	Ref<Set>	当前已高亮的节点 id 集合
highlightedEdges	Ref<Set>	当前已高亮的边 id 集合

调试事件载荷

监听 EDITOR_EVENTS.DEBUG_DATA 时，每条事件载荷字段：

字段	说明
flowType	'IN'（节点开始处理）或 'OUT'（节点处理完成）
nodeId	节点 id
err	OUT 时是否有错（决定 success / error 状态）
relationType	OUT 时匹配出边的关系类型（多出边节点如 switch/fork 精确到一条边）
chainId	事件所属链 id，用于跨链过滤
msgId	消息 id（运行指标的 key，避免并发消息互相串）
ts	时间戳（算耗时用）

节点状态与运行指标

收到 flowType: 'IN' 时节点置 processing（蓝色边框）；收到 'OUT' 时按 err 置 success（绿色）或 error（红色）。同时：

• 边流动动画：按 nodeId + flowType + relationType 定位边并开启动画（lf.openEdgeAnimation）
• 运行指标：IN 记开始时刻，OUT 算耗时并累加执行次数，叠在节点角上（runCount / runDuration）

清除高亮

// 清除所有节点状态、边高亮、运行指标（lf 由 composable 内部读取）
clearHighlight()

调试期间 composable 会标记 _debugHighlighting，并刷新脏态抑制窗口，防止节点样式变更触发 history:change 把 isDirty 误设为 true。

实时调试高亮示例

useCanvasDebug 自己监听 DEBUG_DATA，通常与 useDebugWebSocket（建立 WS 连接、把数据通过 eventCenter 广播）配合，无需手动 watch：

// 二次开发场景
import { useDebugWebSocket } from '../hooks/useDebugWebSocket'
import { useCanvasDebug } from '../hooks/useCanvasDebug'

// WS 连接：收到调试数据后由 DebugConsole 广播 DEBUG_DATA 事件
const { status, data: debugData } = useDebugWebSocket(chainId)
// 画布高亮：自动消费 DEBUG_DATA，无需手动驱动
const { clearHighlight, highlightedNodes } = useCanvasDebug(lfRef, chainId)

---

调试控制台

功能说明

调试控制台（DebugConsole.vue）用于实时显示规则链执行过程中的调试日志信息。

主要功能

• 实时日志显示：实时接收并展示 WebSocket 推送的调试日志
• 按节点过滤：支持按节点 ID 过滤日志，快速定位特定节点的执行情况
• 折叠/展开：支持折叠日志详情，方便查看大量日志
• 自动滚动：新日志到达时自动滚动到底部

使用方式

调试控制台集成在编辑器中，通过工具栏按钮控制显示/隐藏：

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

<script setup>
import { ref } from 'vue'

const options = ref({
  toolbar: {
    showDebugConsole: true, // 显示调试控制台按钮
  }
})
</script>

日志数据结构

调试日志数据结构如下：

{
  id: 'log-001',           // 日志 ID
  nodeId: 'node-1',        // 节点 ID
  nodeName: 'REST API',    // 节点名称
  timestamp: 1705756800000,// 时间戳
  level: 'info',           // 日志级别：info、warn、error、debug
  message: '处理请求',     // 日志消息
  data: {                  // 附加数据
    input: {},
    output: {},
    duration: 125          // 执行耗时（毫秒）
  }
}

事件监听

通过事件系统监听调试控制台的显示/隐藏：

import { EDITOR_EVENTS } from '../constants/events'  // 仅二次开发场景，库消费方用 Vue emit / lf.on

const eventCenter = lf.graphModel.eventCenter

// 监听调试控制台切换事件
eventCenter.on(EDITOR_EVENTS.TOGGLE_DEBUG_CONSOLE, (isVisible) => {
  console.log('调试控制台可见性:', isVisible)
})

相关教程

图文教程：更详细的调试规则链教程（含截图）请参考 调试规则链 (opens new window)

---

运行面板

功能说明

运行面板（RunPanel.vue）用于发送测试数据到规则链并查看执行结果。

主要功能

• 发送测试数据：输入 JSON 格式的测试数据，发送到规则链执行
• AI 对话模式：当规则链包含 ai/agent 类型节点时，可切换到 AI 对话模式直接与智能体对话测试
• 查看执行结果：实时显示规则链执行的输出结果
• 执行历史：查看历史执行记录，支持重放历史数据
• 消息类型选择：支持选择不同的消息类型（msgType）
• 集成说明：展示同步/异步执行 API 和 OpenAI 兼容 Chat API 的调用方式

使用方式

运行面板通过工具栏的「运行」按钮打开：

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

<script setup>
import { ref } from 'vue'

const options = ref({
  url: 'http://127.0.0.1:9090',
  toolbar: {
    showTest: true, // 显示运行按钮
  }
})
</script>

发送测试数据

运行面板提供表单输入测试数据：

1. 选择消息类型（msgType）
2. 输入 JSON 格式的测试数据
3. 点击「运行」按钮发送请求

示例测试数据：

{
  "msgType": "TEST_MSG",
  "data": {
    "temperature": 25.5,
    "humidity": 60,
    "deviceId": "device-001"
  }
}

执行结果

执行结果包含以下信息：

字段	说明
执行状态	成功/失败
执行耗时	规则链执行耗时
输出数据	规则链执行后的输出结果
节点执行详情	每个节点的执行状态和耗时

执行历史

执行历史（RunHistory.vue）记录所有执行记录，支持：

• 查看历史执行记录列表（时间、消息类型、耗时、状态）
• 日期范围筛选，默认查询最近 7 天
• 查看每次执行的详细节点日志（输入/输出数据）
• 重放历史数据（使用相同数据再次执行）
• 单条删除和全部删除

需要在 config.conf 中配置 save_run_log = true 才会记录执行历史。

---

单步节点测试

每个节点右上角悬浮操作按钮（NodeOperate.vue）支持两种单步测试方式：

按钮	图标	说明
从此节点开始执行	VideoPlay	从指定节点开始运行，后续节点正常执行
仅执行此节点	CaretRight	只运行选中的单个节点，不执行后续节点

使用方式

1. 鼠标悬停在节点上，出现悬浮操作按钮
2. 点击「从此节点开始执行」或「仅执行此节点」
3. 在弹出的运行面板中填写测试数据
4. 点击运行，查看执行结果

运行面板配置

运行面板支持选择起始节点：

• 起始节点：下拉选择从哪个节点开始执行（自动填充为点击的节点）
• 仅执行此节点：勾选后只执行选中的节点，不触发后续节点

AI 对话模式

当规则链包含 ai/agent、agent-node 或 agent-orchestration-node 类型节点时，运行面板会显示 发送测试 和 AI 对话 的模式切换。AI 对话模式下可以直接与规则链中的智能体进行多轮对话测试。

API 配置

运行面板使用的 API 路径配置：

const options = ref({
  url: 'http://127.0.0.1:9090',
  executeApi: '/api/v1/rules/:id/execute/:msgType', // 执行规则链 API
})

API 路径中的占位符说明：

• :id：规则链 ID
• :msgType：消息类型

---

调试事件

调试功能通过事件系统与其他模块通信，以下是调试相关的事件：

事件常量	事件名	说明
TOGGLE_DEBUG_CONSOLE	rulego-editor:toggleDebugConsole	切换调试控制台显示
CLEAR_DEBUG_HIGHLIGHT	rulego-editor:clearDebugHighlight	清除调试高亮
DEBUG_DATA	rulego-editor:debugData	接收调试数据
OPEN_NODE_DETAIL	rulego-editor:openNodeDetail	打开节点详情面板

监听调试事件

import { EDITOR_EVENTS } from '../constants/events'  // 仅二次开发场景，库消费方用 Vue emit / lf.on

const eventCenter = lf.graphModel.eventCenter

// 监听调试数据
eventCenter.on(EDITOR_EVENTS.DEBUG_DATA, (data) => {
  console.log('收到调试数据:', data)
})

// 监听清除高亮事件
eventCenter.on(EDITOR_EVENTS.CLEAR_DEBUG_HIGHLIGHT, () => {
  console.log('清除所有调试高亮')
})

// 监听打开节点详情事件
eventCenter.on(EDITOR_EVENTS.OPEN_NODE_DETAIL, (nodeId) => {
  console.log('打开节点详情:', nodeId)
})

---

完整调试流程示例

库消费方接入调试非常简单：editor 内置了画布高亮与调试控制台，只需开启工具栏相关按钮；画布高亮会自动消费调试数据，无需手动驱动。如需独立的调试 WebSocket 或自定义控制台，再用导出的 useDebugWebSocket / DebugConsole。

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

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

const ruleGoEditorRef = ref()
const data = ref()

// 开启调试相关工具栏按钮即可：画布高亮、调试控制台、运行、清除高亮
// （这些按钮默认就是开的，这里仅作显式说明）
const options = ref({
  url: 'http://127.0.0.1:9090',
  toolbar: {
    showTest: true,
    showDebugConsole: true,
    showClearDebugHighlight: true,
  }
})

// lf 是属性（不是函数）；如需调用 LogicFlow 原生 API，用 computed 取一份响应式引用
const lf = computed(() => ruleGoEditorRef.value?.lf)

onMounted(() => {
  setTokenProvider({
    getToken: () => localStorage.getItem('token'),
    clearToken: () => localStorage.removeItem('token'),
  })
})

const onSaveOk = (data) => console.log('规则链保存成功', data)
</script>

如需在工作区形态（RuleGoWorkspace）下调试，底 dock 的「调试」面板已是内置面板之一，开 capabilities.workspace.dock = true（mode: 'app' 默认开）即可，无需额外编码。

---

常见问题

WebSocket 连接失败

问题：WebSocket 连接无法建立，状态显示 error。

解决方案：

1. 检查后端服务是否正常运行
2. 确认 WebSocket 地址配置是否正确
3. 检查防火墙或网络代理设置
4. 确认 Token 认证是否配置正确（如果后端需要认证）

调试高亮不生效

问题：节点状态高亮没有显示。

解决方案：

1. 确认 useCanvasDebug 的 lfRef 参数是否正确指向 LogicFlow 实例
2. 检查调试数据中的 nodeId 是否与画布中的节点 ID 匹配
3. 确认 CSS 样式是否正确加载

调试控制台无日志

问题：调试控制台打开后没有日志输出。

解决方案：

1. 确认 WebSocket 连接状态是否为 connected
2. 检查后端是否正确推送调试数据
3. 确认规则链是否正在执行

---

相关文档

• 配置选项 - 编辑器完整配置说明
• 事件系统 - 事件监听和使用说明
• 组件说明 - 节点组件开发指南