RuleGo-Server 所有 API 基于 /api/v1 路径，可通过 JWT 或 API Key 认证（require_auth = true 时启用）。

• 完整 API 参考（含请求/响应示例、错误码、配置参考）：api-reference.md (opens new window)

通用说明

认证

Authorization: Bearer {jwtToken或apiKey}

或

X-API-Key: {apiKey}

分页参数

参数	说明
page	页码，从 1 开始
size	每页数量

权限标识

格式为 resource:action，如 rule:read、rule:write。

认证

方法	路径	权限	说明
POST	/api/v1/login	无	登录获取 JWT 令牌

规则链管理

方法	路径	权限	说明
GET	/api/v1/rules	rule:read	列出规则链
GET	/api/v1/rules/:id	rule:read	获取规则链 DSL
GET	/api/v1/rules/_/latest	rule:read	获取当前用户最近修改的规则链
POST	/api/v1/rules/:id	rule:write	创建/更新规则链（保存后自动加载）
POST	/api/v1/rules/:id/base	rule:write	更新基础信息（名称、描述、分类）
POST	/api/v1/rules/:id/config/:varType	rule:write	保存配置变量
DELETE	/api/v1/rules/:id	rule:delete	删除规则链
POST	/api/v1/rules/:id/operate/:type	rule:operate	部署操作（start/stop/set-to-main）

列出规则链

GET /api/v1/rules?keywords=&root=&disabled=&category=&page=1&size=20
Authorization: Bearer {token}

参数	类型	说明
keywords	string	关键词过滤
root	bool	过滤根规则链
disabled	bool	过滤已禁用的规则链
category	string	按分类过滤
page / size	int	分页

创建/更新规则链

POST /api/v1/rules/{id}
Authorization: Bearer {token}
Content-Type: application/json

{规则链 DSL JSON}

部署操作

POST /api/v1/rules/{id}/operate/{operateType}
Authorization: Bearer {token}

operateType	说明
start	部署规则链（开始运行）
stop	停止规则链（取消部署）
set-to-main	设为主规则链

规则链 DSL 结构

{
  "ruleChain": {
    "id": "myChain",
    "name": "我的规则链",
    "debugMode": false,
    "root": false,
    "disabled": false,
    "additionalInfo": {
      "description": "规则链描述",
      "category": "分类",
      "inputSchema": {},
      "createTime": "2026/01/01 00:00:00"
    }
  },
  "metadata": {
    "endpoints": [],
    "nodes": [
      {
        "id": "node_1",
        "type": "jsFilter",
        "name": "过滤节点",
        "debugMode": false,
        "configuration": { "jsScript": "return msg.age > 18;" },
        "additionalInfo": { "layoutX": 300, "layoutY": 200 }
      }
    ],
    "connections": [
      { "fromId": "node_1", "toId": "node_2", "type": "True" }
    ]
  }
}

additionalInfo 字段说明

字段	说明
description	规则链描述
category	分类标识
inputSchema	输入参数 JsonSchema（用于 MCP 工具、AI Agent）
createTime / updateTime	创建/更新时间
layoutX / layoutY	编辑器画布坐标（仅节点级别）
username	所属用户

应用集成端点

保存规则链后，系统自动为其生成以下端点：

端点	说明
POST /api/v1/rules/{id}/execute/{msgType}	同步执行
POST /api/v1/rules/{id}/notify/{msgType}	异步通知
POST /api/v1/rules/{id}/v1/chat/completions	OpenAI 兼容对话

规则链执行

方法	路径	权限	说明
POST	/api/v1/rules/:id/execute/:msgType	rule:execute	同步执行
POST	/api/v1/rules/:id/notify/:msgType	rule:execute	异步通知
POST	/api/v1/rules/:id/v1/chat/completions	rule:execute	OpenAI 兼容对话

同步执行

POST /api/v1/rules/{id}/execute/{msgType}
Authorization: Bearer {token}
Content-Type: application/json

{ "message": "hello", "metadata": { "key": "value" } }

curl -X POST http://localhost:9090/api/v1/rules/myChain/execute/TEST \
  -H "Content-Type: application/json" \
  -d '{"temperature": 36.5, "deviceId": "sensor001"}'

异步通知

触发后立即返回，不等待结果。适用于日志处理、消息分发等场景。

OpenAI 兼容对话

规则链包含 ai/agent 节点时，可通过 OpenAI 兼容接口执行，支持 SSE 流式输出：

POST /api/v1/rules/{id}/v1/chat/completions
Authorization: Bearer {token}
Content-Type: application/json

{
  "model": "rulego",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": true
}

实时调试

方法	路径	权限	说明
WS	/api/v1/logs/ws/:chainId/:clientId	认证	WebSocket 实时调试

WebSocket 连接

ws://{host}:{port}/api/v1/logs/ws/{chainId}/{clientId}?token={jwtToken}

参数	说明
chainId	规则链 ID
clientId	客户端唯一标识（自定义）
token	JWT 令牌（query 参数）

服务端推送数据包含：节点 ID、方向（IN/OUT）、消息数据、元数据。

const ws = new WebSocket(
  'ws://localhost:9090/api/v1/logs/ws/myChain/client001?token=' + token
)
ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log(`[${data.direction}] Node: ${data.nodeId}`, data.msg)
}

连接支持自动重连（指数退避，最多 10 次）。

编辑器调试

RuleGo-Editor 可视化调试：点击【运行】→ 配置输入 → 画布节点颜色标识状态（蓝=处理中、绿=成功、红=失败）→ 底部控制台实时显示 IN/OUT 数据。

组件管理

方法	路径	权限	说明
GET	/api/v1/components	component:read	获取完整组件目录

返回内容包括 endpoints（输入端点）、nodes（处理节点）、tools（工具）、builtins（内置处理器）。

共享节点

方法	路径	权限	说明
GET	/api/v1/shared-nodes	component:read	列出共享节点
POST	/api/v1/shared-nodes/:id/:type	component:write	创建/更新共享节点
GET	/api/v1/shared-nodes/:id/:type	component:read	获取共享节点
DELETE	/api/v1/shared-nodes/:id/:type	component:delete	删除共享节点

在规则链中使用 ref:// 前缀引用：

{ "type": "dbClient", "configuration": { "driverName": "ref://mysqlConn" } }

动态组件

方法	路径	权限	说明
GET	/api/v1/dynamic-components	component:read	列出动态组件
GET	/api/v1/dynamic-components/:id	component:read	获取组件 DSL
POST	/api/v1/dynamic-components/:id	component:write	安装/升级组件
DELETE	/api/v1/dynamic-components/:id	component:delete	卸载组件

运行时安装和卸载，无需重启服务。

系统配置

方法	路径	权限	说明
GET	/api/v1/config/global	config:read	获取全局配置
POST	/api/v1/config/global	config:write	更新全局配置

AI 助手

方法	路径	权限	说明
GET	/api/v1/system/agents/:id/prompt	config:read	获取助手系统提示词
POST	/api/v1/system/agents/:id/prompt	config:write	更新助手系统提示词
GET	/api/v1/system/agents/:id/model	config:read	获取助手模型配置
POST	/api/v1/system/agents/:id/model	config:write	更新助手模型配置

技能

方法	路径	权限	说明
GET	/api/v1/skills	skill:read	列出技能
GET	/api/v1/skills/:id	skill:read	获取技能详情
POST	/api/v1/skills	skill:write	创建技能
PUT	/api/v1/skills/:id	skill:write	更新技能
DELETE	/api/v1/skills/:id	skill:delete	删除技能
POST	/api/v1/skills/upload	skill:write	上传技能（multipart）

运行日志

方法	路径	权限	说明
GET	/api/v1/logs/runs	log:read	查询执行历史
GET	/api/v1/logs/debug	log:read	获取节点调试数据
DELETE	/api/v1/logs/runs	log:delete	删除执行记录

国际化

方法	路径	权限	说明
GET	/api/v1/locales	locale:read	列出/获取语言包
POST	/api/v1/locales	locale:write	保存/更新语言包

组件市场

方法	路径	权限	说明
GET	/api/v1/marketplace/components	marketplace:read	浏览市场组件
GET	/api/v1/marketplace/chains	marketplace:read	浏览市场规则链

MCP

方法	路径	认证	说明
GET/POST/DELETE	/api/v1/mcp/:apiKey	API Key	MCP 默认端点
GET/POST/DELETE	/api/v1/mcp/:apiKey/group/:group	API Key	MCP 分组端点

静态资源

方法	路径	说明
GET	/	重定向到 /editor/
GET	/editor/*	编辑器静态文件