npm package: @huanban/rulego-editor-core
Description: RuleGo 规则链编辑器核心库 - 框架无关的 Headless 编辑器引擎 + API 抽象层 (WorkflowFetcher)
Author: HuanBan Team
Latest version: 1.1.1

# @huanban/rulego-editor-core

> RuleGo 规则链编辑器核心库 — 框架无关的 Headless 编辑器引擎 + 独立编辑器 + API 抽象层

[![npm version](https://img.shields.io/npm/v/@huanban/rulego-editor-core.svg)](https://www.npmjs.com/package/@huanban/rulego-editor-core)
[![license](https://img.shields.io/npm/l/@huanban/rulego-editor-core.svg)](https://github.com/openclaw/rulego-editor/blob/main/LICENSE)

## ✨ 特性

- **框架无关** — 纯 TypeScript 实现，不依赖任何前端框架（React / Vue / Angular 均可）
- **Headless 架构** — 核心逻辑与 UI 完全解耦，可自由定制界面
- **独立编辑器** — `HuanbanRulegoEditor` 一行代码即用，内置完整 UI（工具栏、侧边栏、属性面板、右键菜单、小地图、搜索等）
- **API 抽象层** — 提供 `WorkflowFetcher` 接口 + `RuleChainAPI` 默认实现
- **路径可配置** — 所有 API 端点均通过 `RuleChainRoutes` 自定义
- **基于 LogicFlow** — 底层使用 LogicFlow 流程图引擎，提供强大的节点编排能力
- **完整事件系统** — EventBus 事件总线，支持节点/边/编辑器事件监听
- **状态管理** — 内置 StateStore 响应式状态管理
- **6 套主题** — 经典(Classic) / 暗夜(Dark) / 自然(Nature) / 优雅(Elegant) / 科技(Tech) / 现代(Modern)
- **国际化** — 中/英文双语支持，一键切换
- **撤销/重做** — 内置 undo/redo 操作历史
- **调试日志** — 内置调试开关，默认关闭，可按需开启
- **节点分组** — DynamicGroup 容器节点，支持拖入/折叠/调整大小
- **WebSocket 调试** — 内置实时调试面板，支持节点日志追踪

## 📦 安装

```bash
npm install @huanban/rulego-editor-core
# 或
pnpm add @huanban/rulego-editor-core
```

## 🚀 快速开始

### 独立编辑器（推荐）

最简单的使用方式，一行代码即可拥有完整编辑器：

```html
<div id="editor" style="width: 100%; height: 100vh;"></div>
<script src="dist/index.umd.js"></script>
<script>
  const editor = new RuleGoEditorCore.HuanbanRulegoEditor('#editor', {
    apiBase: 'http://127.0.0.1:9090/api/v1',
    theme: 'modern',
    lang: 'zh-CN',
    onReady: ({ lf, core }) => console.log('编辑器就绪'),
    onNodeClick: (node) => console.log('点击节点', node),
    onSaveSuccess: (data) => console.log('保存成功', data),
  })
</script>
```

### ESM 模块化用法

```typescript
import { HuanbanRulegoEditor } from '@huanban/rulego-editor-core'

const editor = new HuanbanRulegoEditor('#editor', {
  apiBase: 'http://127.0.0.1:9090/api/v1',
  lang: 'zh-CN',
  theme: 'modern',
  toolbarTitle: '我的工作流',
})
```

### API 客户端（独立使用）

```typescript
import { RuleChainAPI } from '@huanban/rulego-editor-core'

const api = new RuleChainAPI({
  apiBase: 'http://127.0.0.1:9090/api/v1',
})

// 获取列表
const list = await api.list(1, 10)

// 获取内容
const content = await api.getContent('chain-001')

// 保存
await api.updateContent('chain-001', chainData)
```

## 🎨 内置 UI 组件（独立编辑器）

`HuanbanRulegoEditor` 内置完整的 UI，**无需额外安装任何框架组件**：

| 功能 | 说明 |
|------|------|
| **工具栏** | 保存、撤销/重做、部署、运行、导入/导出、主题切换、语言切换 |
| **组件侧边栏** | 按分类展示节点组件，支持搜索和拖拽添加 |
| **右键菜单** | 节点/边/画布右键菜单（复制、删除、查看属性等）|
| **节点属性面板** | 点击节点弹出属性编辑 Drawer |
| **边属性面板** | 点击连线弹出路由关系编辑 Drawer |
| **小地图** | 全局视图鸟瞰，可通过工具栏切换显隐 |
| **搜索面板** | 支持按节点名称/类型搜索并定位 |
| **链信息面板** | 规则链设置弹窗（名称、描述、是否主链等）|
| **调试面板** | WebSocket 实时调试日志追踪 |
| **代码编辑器** | 基于 CodeMirror 6 的 JSON/JS 编辑器（属性配置用）|
| **键盘快捷键** | Ctrl+S 保存 / Ctrl+Z 撤销 / Ctrl+C/V 复制粘贴 / Delete 删除 |

## 🔧 调试日志

调试日志**默认关闭**，可通过以下方式开启：

```javascript
// 方式1: 静态方法（推荐）
HuanbanRulegoEditor.setDebug(true)

// 方式2: URL 参数
// 浏览器地址栏加 ?debug=1

// 方式3: localStorage 持久化
localStorage.setItem('huanban_debug', '1')

// 方式4: ESM 直接导入
import { setDebug } from '@huanban/rulego-editor-core'
setDebug(true)
```

## 📖 核心模块

| 模块 | 说明 |
|------|------|
| `HuanbanRulegoEditor` | 独立编辑器主类，全功能即开即用 |
| `EditorCore` | 编辑器引擎，管理生命周期和数据流 |
| `RuleChainAPI` | 默认 API 客户端，实现 `WorkflowFetcher` 接口 |
| `DEFAULT_ROUTES` | 默认 API 路径映射 (RuleGo 标准路径) |
| `EventBus` | 事件总线，支持 on / off / emit 模式 |
| `StateStore` | 响应式状态容器，支持 subscribe |
| `ThemeManager` | 主题管理器，6 套主题自由切换 |
| `I18nManager` | 国际化管理器，中英文切换 |
| `ValidationEngine` | 规则链验证引擎 |
| `setDebug` / `isDebug` | 调试日志开关 |

## 📋 导出类型

```typescript
// 数据类型
WorkflowItem          // 工作流列表项
PagedResponse<T>      // 分页响应
ApiResult             // 操作结果

// 请求抽象
WorkflowFetcher       // 请求适配器接口（8 个方法）
RuleChainAPIOptions   // API 客户端配置
RuleChainRoutes       // 路径映射（支持函数式路由）

// UI 自定义
WorkflowListIcons     // 列表组件图标映射
WorkflowInfoIcons     // 信息面板图标映射
WorkflowTheme         // 主题类型

// 编辑器类型
EditorOptions, RuleChainData, RuleChainConfig
RuleNodeConfig, RuleConnectionConfig, RuleEndpointConfig
ComponentDefinition, ComponentGroup, ComponentField
EditorEventMap, EditorEventName
HuanbanRulegoEditorOptions
```

## 🏗️ 构建产物

| 格式 | 文件 | 说明 |
|------|------|------|
| ESM | `dist/index.esm.js` | 现代打包工具 (Vite/Webpack) |
| CJS | `dist/index.cjs.js` | Node.js / 旧项目 |
| UMD | `dist/index.umd.js` | `<script>` 标签直接引入，暴露 `window.RuleGoEditorCore` |

> 所有格式均全量打包 LogicFlow + CodeMirror，无需额外安装。
> CSS 通过 `editor-styles.ts` 动态注入，无需单独引入样式文件。

## 🔗 相关包

| 包 | 说明 |
|---|---|
| [`@huanban/rulego-editor-react`](../editor-react) | React 适配层（薄封装 HuanbanRulegoEditor）|
| [`@huanban/rulego-editor-vue`](../editor-vue) | Vue 3 适配层 |
| [`@huanban/rulego-editor-ui`](../editor-ui) | 纯 DOM UI 组件 |

## 📄 协议

Apache-2.0