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

# @huanban/editor-core

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

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

## ✨ 特性

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

## 📦 安装

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

## 🚀 快速开始

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

```html
<script src="dist/index.umd.js"></script>
<script>
  const editor = new RuleGoEditorCore.HuanbanRulegoEditor('#editor', {
    apiBase: 'http://127.0.0.1:9090/api/v1',
    onReady: ({ lf, core }) => console.log('就绪'),
    onNodeClick: (node) => console.log('点击节点', node),
  })
</script>
```

### ESM 模块化用法

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

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

### API 客户端

```typescript
import { RuleChainAPI } from '@huanban/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')
```

## 🔧 调试日志

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

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

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

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

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

## 📁 包结构

```
src/
├── index.ts              # 包入口（统一导出）
├── iconRegistry.ts       # 90 个 SVG 图标内联注册
├── core/                 # 核心引擎模块
│   ├── EditorCore.ts       # 编辑器主引擎
│   ├── EventBus.ts         # 类型安全事件总线
│   ├── StateStore.ts       # 响应式状态容器
│   ├── DataAdapter.ts      # RuleGo ↔ LogicFlow 数据转换
│   ├── ComponentRegistry.ts # 组件注册表
│   ├── HistoryManager.ts   # 撤销/重做管理
│   ├── ThemeManager.ts     # 6 套主题管理
│   ├── I18nManager.ts      # 国际化管理
│   └── ValidationEngine.ts # 图验证引擎
├── standalone/           # 独立编辑器（全功能 UMD 打包）
│   ├── HuanbanRulegoEditor.ts  # 主类入口
│   ├── editor-events.ts     # 事件桥接
│   ├── editor-toolbar.ts    # 工具栏逻辑
│   ├── editor-sidebar.ts    # 侧边栏渲染
│   ├── editor-dialogs.ts    # 弹窗/面板
│   ├── editor-property-drawers.ts # 属性 Drawer
│   ├── editor-chain-info.ts # 链信息面板
│   ├── editor-context-menu.ts # 右键菜单
│   ├── editor-debug-ws.ts   # WebSocket 调试
│   ├── editor-styles.ts     # CSS 动态注入
│   ├── custom-nodes.ts      # 自定义节点注册
│   ├── group-node.ts        # 分组容器节点
│   ├── themes.ts            # 主题定义（6 套）
│   ├── node-definitions.ts  # 节点分类配置
│   ├── node-views-data.ts   # 节点视觉数据
│   ├── code-editor.ts       # CodeMirror 集成
│   ├── icon-utils.ts        # 图标工具
│   └── logger.ts            # 调试日志工具
├── api/                  # API 客户端
│   ├── RuleChainAPI.ts     # 默认 HTTP 客户端
│   └── types.ts            # WorkflowFetcher 接口
├── types/                # TypeScript 类型定义
│   ├── editor.ts           # 编辑器配置/状态类型
│   ├── rule-chain.ts       # 规则链数据类型
│   ├── component.ts        # 组件定义类型
│   └── events.ts           # 事件映射类型
├── defaults/             # 默认数据
│   ├── components.ts       # 内置组件定义
│   ├── locale-zh-CN.ts     # 中文语言包
│   └── locale-en-US.ts     # 英文语言包
├── utils/                # 工具函数
│   ├── helpers.ts          # 通用辅助函数
│   └── pinyin-search.ts    # 拼音搜索
├── styles/               # CSS 样式文件
│   ├── editor.css          # 编辑器主样式
│   ├── info-panel.css      # 信息面板样式
│   └── list.css            # 列表组件样式
└── icons/                # 90 个 SVG 图标源文件
```

## 📖 核心模块

| 模块 | 说明 |
|------|------|
| `EditorCore` | 编辑器主类，管理生命周期和数据流 |
| `HuanbanRulegoEditor` | 独立编辑器主类，全功能即开即用 |
| `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
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/editor-react`](../editor-react) | React 适配层 (Hooks + 组件) |
| [`@huanban/editor-vue`](../editor-vue) | Vue 3 适配层 |

## 📄 协议

Apache-2.0