@blueking/flow-canvas 0.0.1-beta.1

package/README.md

@@ -0,0 +1,725 @@
+# @blueking/flow-canvas 使用文档
+
+## 概述
+
+`@blueking/flow-canvas` 是一个通用流程画布编辑引擎，基于 AntV X6 构建，提供数据驱动的图编辑能力。适用于 DAG / 流程图 / 工作流等场景。
+
+## 安装
+
+```bash
+npm install @blueking/flow-canvas
+```
+
+### 必需的对等依赖
+
+```bash
+npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-plugin-snapline @antv/x6-vue-shape vue
+```
+
+### 可选依赖
+
+```bash
+npm install @antv/x6-plugin-dnd  # 拖拽建节点（DND）功能需要
+```
+
+## 快速开始
+
+```vue
+<template>
+  <CanvasLayout>
+    <template #sidebar>
+      <!-- 自定义侧边栏 -->
+    </template>
+    <CanvasRuntime :editor="editor" @ui-event="handleUiEvent">
+      <template #node-overlay="{ node, screenAnchors, api }">
+        <!-- 节点悬浮操作按钮 -->
+      </template>
+    </CanvasRuntime>
+    <CanvasToolbar :editor="editor" />
+  </CanvasLayout>
+</template>
+
+<script setup lang="ts">
+  import {
+    useCanvasEditor,
+    CanvasRuntime,
+    CanvasLayout,
+    CanvasToolbar,
+    selectionPlugin,
+    snaplinePlugin,
+    connectionValidatorPlugin,
+    type CanvasSchema,
+    type CanvasUiEvent,
+    type FlowModel,
+  } from '@blueking/flow-canvas';
+  import '@blueking/flow-canvas/style';
+  import MyTaskNode from './components/my-task-node.vue';
+
+  const schema: CanvasSchema = {
+    nodeTypes: {
+      task: {
+        component: MyTaskNode,
+        getSize: () => ({ width: 180, height: 60 }),
+        getPorts: () => [
+          { id: 'left', group: 'left' },
+          { id: 'right', group: 'right' },
+        ],
+      },
+    },
+    edgeTypes: {
+      default: {
+        router: { name: 'manhattan', args: { padding: 10 } },
+        connector: 'rounded',
+      },
+    },
+    defaultEdgeType: 'default',
+  };
+
+  const initialFlowModel: FlowModel = {
+    version: '1.0',
+    nodes: {
+      node1: { id: 'node1', type: 'task', position: { x: 100, y: 200 }, label: '任务 1' },
+      node2: { id: 'node2', type: 'task', position: { x: 400, y: 200 }, label: '任务 2' },
+    },
+    edges: {
+      edge1: {
+        id: 'edge1',
+        source: { nodeId: 'node1', portId: 'right' },
+        target: { nodeId: 'node2', portId: 'left' },
+      },
+    },
+  };
+
+  const editor = useCanvasEditor({
+    initialFlowModel,
+    schema,
+    plugins: [
+      selectionPlugin(),
+      snaplinePlugin(),
+      connectionValidatorPlugin((ctx) => {
+        if (ctx.sourceNode.id === ctx.targetNode.id) {
+          return { valid: false, reason: '不允许自环连线' };
+        }
+        return { valid: true };
+      }),
+    ],
+    onFlowModelChange(event) {
+      console.log('流程变更:', event.flowModel);
+    },
+  });
+
+  function handleUiEvent(event: CanvasUiEvent) {
+    if (event.type === 'node.click') {
+      console.log('点击了节点:', event.nodeId);
+    }
+  }
+</script>
+```
+
+---
+
+## 核心 API
+
+### useCanvasEditor(options)
+
+创建画布编辑器实例。
+
+#### CanvasEditorOptions
+
+| 参数              | 类型                   | 必填 | 默认     | 说明                                    |
+| ----------------- | ---------------------- | ---- | -------- | --------------------------------------- |
+| initialFlowModel  | `FlowModel`            | 是   | -        | 初始流程模型                            |
+| schema            | `CanvasSchema`         | 是   | -        | 节点/边类型定义                         |
+| plugins           | `CanvasPlugin[]`       | 否   | `[]`     | 插件列表                                |
+| mode              | `CanvasMode`           | 否   | `'edit'` | `'edit'` / `'readonly'` / `'thumbnail'` |
+| historyOptions    | `CanvasHistoryOptions` | 否   | -        | 历史配置                                |
+| onCommandResult   | `(result) => void`     | 否   | -        | 命令执行结果回调                        |
+| onFlowModelChange | `(event) => void`      | 否   | -        | FlowModel 变更回调                      |
+
+#### CanvasEditorContext（返回值）
+
+| 属性/方法                | 类型                                          | 说明                           |
+| ------------------------ | --------------------------------------------- | ------------------------------ |
+| flowModel                | `Readonly<Ref<FlowModel>>`                    | 当前流程模型（响应式）         |
+| history                  | `CanvasHistory`                               | 历史管理器                     |
+| schema                   | `CanvasSchema`                                | Schema 定义                    |
+| mode                     | `Ref<CanvasMode>`                             | 当前模式                       |
+| api                      | `Ref<CanvasApi \| null>`                      | 画布 API（Runtime 挂载后可用） |
+| toolbarItems             | `Ref<CanvasToolbarItem[]>`                    | 插件聚合的工具栏项             |
+| extendedApi              | `Record<string, Function>`                    | 插件扩展的 API                 |
+| executeCommand(envelope) | `(CommandEnvelope) => CommandExecutionResult` | 执行命令                       |
+| replaceFlowModel(model)  | `(FlowModel) => void`                         | 整体替换流程模型               |
+| setMode(mode)            | `(CanvasMode) => void`                        | 切换模式                       |
+
+---
+
+## FlowModel 数据结构
+
+```typescript
+interface FlowModel {
+  version: '1.0';
+  nodes: Record<string, FlowNodeModel>; // 节点字典，key = nodeId
+  edges: Record<string, FlowEdgeModel>; // 边字典，key = edgeId
+  meta?: Record<string, unknown>; // 全局元数据
+  extensions?: Record<string, unknown>; // 扩展数据
+}
+
+interface FlowNodeModel {
+  id: string;
+  type: string; // 对应 schema.nodeTypes 的 key
+  position: { x: number; y: number };
+  label?: string;
+  ports?: FlowPortModel[];
+  payload?: Record<string, unknown>; // 业务数据
+  extensions?: Record<string, unknown>; // 扩展数据
+}
+
+interface FlowEdgeModel {
+  id: string;
+  type?: string; // 对应 schema.edgeTypes 的 key
+  source: { nodeId: string; portId?: string };
+  target: { nodeId: string; portId?: string };
+  labels?: FlowEdgeLabelModel[];
+  payload?: Record<string, unknown>;
+  extensions?: Record<string, unknown>;
+}
+```
+
+---
+
+## CanvasSchema 配置
+
+### 节点类型定义
+
+```typescript
+interface CanvasNodeDefinition {
+  component: Component; // Vue 组件，渲染节点内容
+  getSize: (node) => { width; height };
+  getPorts?: (node) => FlowPortModel[];
+  getBehavior?: (node, ctx) => NodeBehaviorConfig;
+  getOverlayAnchors?: (node) => NodeOverlayAnchors;
+  x6CellConfig?: Record<string, unknown>; // 透传给 X6 的额外配置
+}
+```
+
+节点 Vue 组件内可通过 `inject('getNode')` 获取 X6 Node 实例，读取 `node.getData()` 访问 `FlowNodeModel`。
+
+### 边类型定义
+
+```typescript
+interface CanvasEdgeDefinition {
+  router?: string | { name: string; args?: Record<string, unknown> };
+  connector?: string | { name: string; args?: Record<string, unknown> };
+  style?: (edge, state: EdgeRenderState) => EdgeStyle; // 动态样式
+  labelDraggable?: boolean;
+  x6EdgeConfig?: Record<string, unknown>; // 透传给 X6 的额外配置
+
+  // @experimental — 尚未完整实现，请勿在生产环境依赖
+  // labelRenderer?: Component;
+}
+```
+
+**EdgeRenderState** 包含 `selected`、`highlighted`、`hovered` 三个布尔值，`style()` 可据此返回不同的 `stroke`、`strokeWidth`、`strokeDasharray`。
+
+> **注意：** `labelRenderer` 字段在类型定义中存在但标记为 `@experimental`，当前版本尚未完整实现。如需自定义边标签样式，建议通过 `x6EdgeConfig.defaultLabel` 配置 X6 原生标签 markup。
+
+> **注意：** `labelRenderer` 字段在类型定义中存在但标记为 `@experimental`，当前版本尚未完整实现。如需自定义边标签样式，建议通过 `x6EdgeConfig.defaultLabel` 配置 X6 原生标签 markup。
+
+---
+
+## 命令系统
+
+所有 FlowModel 变更必须通过命令执行：
+
+```typescript
+import { generateId } from '@blueking/flow-canvas';
+
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '添加节点',
+  timestamp: Date.now(),
+  commands: [
+    { type: 'node.add', node: { id: 'n1', type: 'task', position: { x: 100, y: 100 } } },
+    { type: 'edge.add', edge: { id: 'e1', source: { nodeId: 'n0' }, target: { nodeId: 'n1' } } },
+  ],
+});
+```
+
+### 命令类型一览
+
+| 命令                  | 说明                                        |
+| --------------------- | ------------------------------------------- |
+| `node.add`            | 添加节点                                    |
+| `node.move`           | 移动节点位置                                |
+| `node.remove`         | 删除节点（自动级联删除关联边）              |
+| `node.update`         | 更新节点结构字段（不含 payload/extensions） |
+| `node.set-payload`    | 按路径更新节点 payload                      |
+| `node.set-extensions` | 按路径更新节点 extensions                   |
+| `edge.add`            | 添加边                                      |
+| `edge.remove`         | 删除边                                      |
+| `edge.reconnect`      | 重连边端点                                  |
+| `edge.update`         | 更新边结构字段                              |
+| `edge.set-payload`    | 按路径更新边 payload                        |
+| `edge.label.update`   | 更新边标签                                  |
+| `model.set-meta`      | 按路径更新全局 meta                         |
+
+`path` 参数使用 `string[]` 格式：`{ path: ['config', 'timeout'], value: 30 }`。
+
+### CommandSource 类型
+
+`'user:drag'` | `'user:keyboard'` | `'user:toolbar'` | `'user:quick-add'` | `'user:panel'` | `'plugin'` | `'system'` | `'system:replace'`
+
+---
+
+## 组件
+
+### CanvasRuntime
+
+核心渲染组件，负责创建 X6 Graph 并双向桥接 FlowModel。
+
+| Prop         | 类型                      | 说明                                       |
+| ------------ | ------------------------- | ------------------------------------------ |
+| editor       | `CanvasEditorContext`     | 编辑器实例（必填）                         |
+| graphOptions | `Record<string, unknown>` | 额外 X6 Graph 选项                         |
+| nodeActions  | `NodeActionsConfig`       | 节点快捷操作工具栏配置（见下方详细说明）   |
+| quickAdd     | `QuickAddConfig`          | 右侧端口快捷添加按钮配置（见下方详细说明） |
+
+| Emit     | 参数            | 说明                 |
+| -------- | --------------- | -------------------- |
+| ui-event | `CanvasUiEvent` | 非命令类 UI 交互事件 |
+
+| Slot            | Props                                            | 说明                                                        |
+| --------------- | ------------------------------------------------ | ----------------------------------------------------------- |
+| node-overlay    | `{ node, screenAnchors, api }`                   | 节点悬浮层，鼠标移入节点时显示                              |
+| quick-add-panel | `{ node, api, insertNodeToRight, closePopover }` | 快捷添加弹层内容，点击右侧"+"按钮时显示（默认显示提示文字） |
+
+#### 节点快捷操作工具栏
+
+`CanvasRuntime` 内置节点快捷操作工具栏，hover 节点时在右下角显示。通过 `nodeActions` prop 进行全局配置：
+
+```html
+<CanvasRuntime :editor="editor" :node-actions="{ showDebug: true, showCopy: false }" />
+```
+
+**NodeActionsConfig（全局开关）**
+
+| 属性             | 类型      | 默认    | 说明                         |
+| ---------------- | --------- | ------- | ---------------------------- |
+| `showDebug`      | `boolean` | `false` | 是否显示调试按钮             |
+| `showDelete`     | `boolean` | `true`  | 是否显示删除按钮             |
+| `showCopy`       | `boolean` | `true`  | 是否显示复制按钮             |
+| `showCopyInsert` | `boolean` | `true`  | 是否显示复制并插入按钮       |
+| `showDisconnect` | `boolean` | `true`  | 是否显示断开连线按钮         |
+| `insertGap`      | `number`  | `100`   | 向右插入节点的水平间距（px） |
+
+**NodeBehaviorConfig 中的工具栏相关字段（逐节点控制）**
+
+通过 schema `getBehavior` 返回值控制每个节点类型的工具栏行为：
+
+| 属性                 | 说明                                                     |
+| -------------------- | -------------------------------------------------------- |
+| `showActions`        | `false` → 该节点类型不显示整个工具栏                     |
+| `deletable`          | `false` → 隐藏删除按钮                                   |
+| `copyable`           | `false` → 隐藏复制和复制并插入按钮                       |
+| `disconnectable`     | `false` → 隐藏断开连线按钮                               |
+| `debuggable`         | `false` → 隐藏调试按钮（需全局 `showDebug` 也为 `true`） |
+| `deleteDisabled`     | `true` → 删除按钮可见但置灰不可点击                      |
+| `copyDisabled`       | `true` → 复制按钮置灰                                    |
+| `copyInsertDisabled` | `true` → 复制并插入按钮置灰                              |
+| `disconnectDisabled` | `true` → 断开连线按钮置灰                                |
+| `debugDisabled`      | `true` → 调试按钮置灰                                    |
+
+按钮有效可见性 = 全局 `show*` AND 逐节点 `*able !== false`；
+按钮禁用状态 = 逐节点 `*Disabled === true`。
+
+操作触发后通过 `@ui-event` 发出对应事件：`node.action.delete` / `node.action.copy` / `node.action.copy-insert` / `node.action.disconnect` / `node.action.debug`。
+
+#### 节点快捷添加按钮
+
+hover 节点时，右侧端口显示为"+"按钮，支持点击弹出面板和拖拽发起连线。通过 `quickAdd` prop 进行全局配置：
+
+```html
+<CanvasRuntime :editor="editor" :quick-add="{ enabled: true }">
+  <template #quick-add-panel="{ node, api, insertNodeToRight, closePopover }">
+    <!-- 自定义节点选择面板 -->
+  </template>
+</CanvasRuntime>
+```
+
+**QuickAddConfig（全局配置）**
+
+| 属性          | 类型      | 默认   | 说明                                    |
+| ------------- | --------- | ------ | --------------------------------------- |
+| `enabled`     | `boolean` | `true` | 全局开关                                |
+| `tooltipText` | `string`  | `''`   | 自定义 tooltip 文案（空值使用内置提示） |
+
+**NodeBehaviorConfig 中的快捷添加相关字段（逐节点控制）**
+
+| 属性              | 说明                                                            |
+| ----------------- | --------------------------------------------------------------- |
+| `quickAddEnabled` | `false` → 该节点不显示"+"按钮（如结束节点、已有出边的开始节点） |
+
+生效规则：显示 = `global.enabled !== false` AND `perNode.quickAddEnabled !== false`。
+
+**quick-add-panel Slot Props**
+
+| Prop                | 类型                                              | 说明                            |
+| ------------------- | ------------------------------------------------- | ------------------------------- |
+| `node`              | `FlowNodeModel`                                   | 当前触发的源节点                |
+| `api`               | `CanvasApi`                                       | 画布 API                        |
+| `insertNodeToRight` | `(node: Omit<FlowNodeModel, 'position'>) => void` | 快捷插入方法（自动连线 + 事件） |
+| `closePopover`      | `() => void`                                      | 关闭弹层                        |
+
+操作触发后通过 `@ui-event` 发出对应事件：`node.quick-add`（弹层打开时）/ `node.action.quick-insert`（插入成功时）。
+
+### CanvasLayout
+
+可选的布局骨架组件。
+
+| Prop             | 类型      | 默认    | 说明           |
+| ---------------- | --------- | ------- | -------------- |
+| sidebarCollapsed | `boolean` | `false` | 侧边栏是否收起 |
+| sidebarWidth     | `number`  | `260`   | 侧边栏宽度     |
+| hideSidebar      | `boolean` | `false` | 是否隐藏侧边栏 |
+| hideFooter       | `boolean` | `false` | 是否隐藏底部栏 |
+
+| Slot    | 说明                                             |
+| ------- | ------------------------------------------------ |
+| sidebar | 侧边栏内容                                       |
+| default | 主画布区域（放置 CanvasRuntime + CanvasToolbar） |
+| footer  | 底部栏                                           |
+
+### CanvasToolbar
+
+可选的工具栏组件。默认浮动在画布左上角，包含搜索、下载、缩放、重置等操作。
+
+| Prop    | 类型                   | 默认       | 说明                                    |
+| ------- | ---------------------- | ---------- | --------------------------------------- |
+| editor  | `CanvasEditorContext`  | -          | 编辑器实例（必填）                      |
+| items   | `CanvasToolbarItem[]`  | 内置默认项 | 工具栏项列表，传入后完全替换默认项      |
+| exclude | `BuiltinToolbarType[]` | -          | 排除特定默认项（仅在未传 items 时生效） |
+
+#### createDefaultToolbarItems(options?)
+
+工厂函数，用于获取默认工具栏项列表，便于自定义组合。
+
+```typescript
+import { createDefaultToolbarItems } from '@blueking/flow-canvas';
+
+// 排除搜索，追加自定义项
+const items = [
+  ...createDefaultToolbarItems({ exclude: ['search'] }),
+  { id: 'my-tool', type: 'custom', icon: 'my-icon-class', onClick: handleClick },
+];
+```
+
+#### CanvasToolbarItem 字段
+
+| 字段        | 类型                                   | 说明                                      |
+| ----------- | -------------------------------------- | ----------------------------------------- |
+| id          | `string`                               | 唯一标识                                  |
+| type        | `BuiltinToolbarType \| 'custom'`       | 操作类型                                  |
+| icon        | `string`                               | CSS 类名（字体图标）                      |
+| component   | `Component`                            | Vue 组件，渲染在按钮内部作为图标/内容区域 |
+| text        | `string`                               | 无图标时的兜底显示文字                    |
+| description | `string`                               | 操作说明，有值时 hover 显示 tooltip 气泡  |
+| onClick     | `(ctx: CanvasCallbackContext) => void` | 点击回调                                  |
+
+---
+
+## CanvasApi
+
+`editor.api.value` 在 `CanvasRuntime` 挂载后可用，之前为 `null`。
+
+| 方法                                            | 说明                                             |
+| ----------------------------------------------- | ------------------------------------------------ |
+| zoomIn() / zoomOut()                            | 缩放                                             |
+| zoomTo(value)                                   | 缩放到指定比例                                   |
+| zoomToFit()                                     | 自适应画布                                       |
+| getZoom()                                       | 获取当前缩放比例                                 |
+| centerContent()                                 | 居中画布内容                                     |
+| scrollToNode(nodeId)                            | 滚动到指定节点                                   |
+| getSelection()                                  | 获取当前选区 `{ nodeIds, edgeIds }`              |
+| selectNodes(ids)                                | 选中指定节点                                     |
+| selectEdges(ids)                                | 选中指定边                                       |
+| clearSelection()                                | 清除选区                                         |
+| registerDndSource(el, factory)                  | 注册 DND 拖拽源，返回清理函数                    |
+| startConnection(nodeId, portId?)                | 从指定节点/端口发起连线                          |
+| highlightNodes(ids) / highlightEdges(ids)       | 高亮指定元素                                     |
+| clearHighlight()                                | 清除所有高亮                                     |
+| exportAsImage(options?)                         | 导出为 PNG Blob                                  |
+| exportAsSVG()                                   | 导出为 SVG 字符串                                |
+| overlay                                         | `OverlayManager` 实例，提供节点屏幕定位          |
+| insertNodeToRight(sourceNodeId, node, options?) | 在指定节点右侧插入新节点，支持自动连线和重叠检测 |
+| getContextMenuItems(position)                   | 收集插件提供的右键菜单项                         |
+| onGraphEvent(event, handler)                    | 监听 X6 底层事件，返回取消函数                   |
+| unsafeGetGraph()                                | 获取 X6 Graph 实例（谨慎使用）                   |
+
+---
+
+## 内置插件
+
+### selectionPlugin(options?)
+
+启用节点/边的框选和多选能力。
+
+```typescript
+selectionPlugin({
+  rubberband: true, // 框选，默认 true
+  multiple: true, // 多选，默认 true
+  movable: true, // 选中后可拖拽移动，默认 true
+});
+```
+
+### snaplinePlugin(options?)
+
+节点拖拽时显示对齐辅助线。
+
+```typescript
+snaplinePlugin({ tolerance: 10 }); // 对齐容差，默认 10
+```
+
+### connectionValidatorPlugin(validator)
+
+连线校验。
+
+```typescript
+connectionValidatorPlugin((ctx) => {
+  // ctx.flowModel: 当前 FlowModel
+  // ctx.sourceNode / targetNode: 源/目标节点
+  // ctx.existingEdges: 已有边列表
+  if (ctx.sourceNode.id === ctx.targetNode.id) {
+    return { valid: false, reason: '不允许自环' };
+  }
+  return { valid: true };
+});
+```
+
+### minimapPlugin(options?)
+
+小地图。传入 `container` 后启用。
+
+```typescript
+minimapPlugin({
+  container: document.getElementById('minimap'),
+  width: 200,
+  height: 160,
+});
+```
+
+### clipboardPlugin()
+
+Cmd/Ctrl+C 复制选中节点/边，Cmd/Ctrl+V 粘贴（生成新 ID、偏移位置）。
+
+---
+
+## 自定义插件
+
+```typescript
+const myPlugin: CanvasPlugin = {
+  name: 'my-plugin',
+  priority: 50,
+
+  // editor 阶段：仅有 flowModel / history / schema
+  install(ctx) {},
+
+  // runtime 阶段：api / graph 已可用
+  attachRuntime(ctx) {
+    ctx.api.onGraphEvent('cell:mouseenter', () => {
+      /* ... */
+    });
+  },
+  detachRuntime() {},
+
+  // 命令拦截/增强（不可变管道）
+  transformCommand(envelope, preview, ctx) {
+    // 返回新 envelope = 修改后的命令
+    // 返回 { rejected: true, reason: '...' } = 拒绝
+    // 返回 null = 丢弃
+    return envelope;
+  },
+
+  // 命令执行后
+  afterCommand(envelope, prevModel, newModel, ctx) {},
+
+  // UI 事件
+  onUiEvent(event, ctx) {},
+  onKeyboardShortcut(event, ctx) {
+    return false;
+  },
+  onSelectionChange(selection, ctx) {},
+
+  // 视觉装饰
+  decorateNode(node, ctx) {
+    if (node.payload?.hasError) {
+      return { borderColor: '#ff4d4d', badge: { text: '!', color: '#ff4d4d' } };
+    }
+  },
+  decorateEdge(edge, ctx) {},
+
+  // 工具栏扩展
+  provideToolbarItems(ctx) {
+    return [{ id: 'my-tool', type: 'custom', text: '自定义工具', onClick: () => {} }];
+  },
+
+  // API 扩展
+  extendApi(api, ctx) {
+    return {
+      doSomething: () => {
+        /* ... */
+      },
+    };
+  },
+};
+```
+
+---
+
+## 工具函数与底层 API
+
+| 导出                                              | 说明                                                                              |
+| ------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `createEmptyFlowModel()`                          | 创建一个空的 FlowModel（`version: '1.0'`, 空 nodes/edges）                        |
+| `generateId()`                                    | 生成唯一 ID                                                                       |
+| `applyCanvasCommand(model, cmd)`                  | 纯函数 reducer，将单条命令应用到 FlowModel，返回新 FlowModel                      |
+| `createCanvasHistory(initialFlowModel, options?)` | 创建独立的历史管理器实例（通常由 `useCanvasEditor` 内部调用，高级场景可直接使用） |
+| `CanvasConstraintError`                           | 命令违反 FlowModel 不变量时抛出的错误类（如重复 ID、悬挂引用等）                  |
+| `CanvasSchemaError`                               | 未知节点/边类型等 Schema 级错误类                                                 |
+
+```typescript
+import { createEmptyFlowModel, generateId } from '@blueking/flow-canvas';
+
+const emptyModel = createEmptyFlowModel();
+// { version: '1.0', nodes: {}, edges: {} }
+```
+
+---
+
+## 撤销/重做
+
+```typescript
+editor.history.undo();
+editor.history.redo();
+editor.history.canUndo.value; // boolean
+editor.history.canRedo.value; // boolean
+editor.history.clear();
+```
+
+---
+
+## 事件类型 (CanvasUiEvent)
+
+| type                     | 附加字段                | 说明             |
+| ------------------------ | ----------------------- | ---------------- |
+| node.click               | nodeId                  | 节点点击         |
+| node.dblclick            | nodeId                  | 节点双击         |
+| node.contextmenu         | nodeId, position        | 节点右键         |
+| edge.click               | edgeId                  | 边点击           |
+| edge.label.click         | edgeId, labelId         | 边标签点击       |
+| blank.click              | position                | 空白区域点击     |
+| blank.contextmenu        | position                | 空白区域右键     |
+| selection.change         | nodeIds, edgeIds        | 选区变更         |
+| node.action.delete       | nodeId                  | 快捷删除节点     |
+| node.action.copy         | sourceNodeId, newNodeId | 快捷复制节点     |
+| node.action.copy-insert  | sourceNodeId, newNodeId | 快捷复制并插入   |
+| node.action.disconnect   | nodeId, edgeIds         | 快捷断开连线     |
+| node.action.debug        | nodeId                  | 快捷调试         |
+| node.quick-add           | nodeId, position        | 快捷添加弹层打开 |
+| node.action.quick-insert | sourceNodeId, newNodeId | 快捷插入节点     |
+
+---
+
+## 公开类型参考
+
+以下类型从包入口公开导出，供 TypeScript 接入方使用。
+
+### 数据模型
+
+| 类型                 | 说明                         |
+| -------------------- | ---------------------------- |
+| `FlowModel`          | 流程模型，编辑态唯一权威状态 |
+| `FlowNodeModel`      | 节点模型                     |
+| `FlowEdgeModel`      | 边模型                       |
+| `FlowPortModel`      | 端口模型                     |
+| `FlowEdgeLabelModel` | 边标签模型                   |
+
+### Schema 与渲染
+
+| 类型                    | 说明                                                                                                                                                             |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CanvasSchema`          | 画布配置（nodeTypes / edgeTypes）                                                                                                                                |
+| `CanvasNodeDefinition`  | 节点类型定义（component / getSize / getPorts / getBehavior / getOverlayAnchors）                                                                                 |
+| `CanvasEdgeDefinition`  | 边类型定义（router / connector / style / labelDraggable）。`labelRenderer` 字段为 `@experimental`，当前未实现                                                    |
+| `CanvasCallbackContext` | 运行时上下文（api / flowModel / history / mode）                                                                                                                 |
+| `CanvasMode`            | 模式：`'edit'` / `'readonly'` / `'thumbnail'`                                                                                                                    |
+| `NodeBehaviorConfig`    | 节点行为配置（showActions / draggable / selectable / deletable / connectable / copyable / disconnectable / debuggable / quickAddEnabled + 各按钮 Disabled 状态） |
+| `EdgeRenderState`       | 边渲染状态（selected / highlighted / hovered）                                                                                                                   |
+| `EdgeStyle`             | 边样式（stroke / strokeWidth / strokeDasharray）                                                                                                                 |
+
+### 命令系统
+
+| 类型                                | 说明                                          |
+| ----------------------------------- | --------------------------------------------- |
+| `CanvasCommand`                     | 原子命令联合类型（node.add / edge.remove 等） |
+| `CommandEnvelope`                   | 命令信封（id / source / commands[]）          |
+| `CommandSource`                     | 命令来源标识                                  |
+| `CommandExecutionResult`            | 命令执行结果                                  |
+| `CommandExecutionError`             | 命令执行错误详情                              |
+| `CommandPreview`                    | 命令预览接口（用于 transformCommand）         |
+| `CommandRejection`                  | 命令拒绝结果                                  |
+| `FlowModelChangeEvent`              | FlowModel 变更事件                            |
+| `CanvasUiEvent`                     | UI 交互事件联合类型                           |
+| `ScreenPosition` / `CanvasPosition` | 坐标类型                                      |
+
+### 插件系统
+
+| 类型                   | 说明                                                                       |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `CanvasPlugin`         | 插件接口（install / attachRuntime / transformCommand / decorateNode 等）   |
+| `EditorPluginContext`  | editor 阶段插件上下文（flowModel / history / schema / executeCommand）     |
+| `RuntimePluginContext` | runtime 阶段插件上下文（继承 EditorPluginContext + api / graph / overlay） |
+| `CanvasSelection`      | 选区数据（nodeIds / edgeIds）                                              |
+| `NodeDecoration`       | 节点装饰（className / badge / borderColor）                                |
+| `EdgeDecoration`       | 边装饰（className / strokeColor）                                          |
+| `ContextMenuItem`      | 右键菜单项                                                                 |
+
+### API 与工具栏
+
+| 类型                        | 说明                                                                                                                                                   |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `CanvasApi`                 | 画布公共 API 接口（含 `insertNodeToRight`）                                                                                                            |
+| `CanvasToolbarItem`         | 工具栏项配置                                                                                                                                           |
+| `BuiltinToolbarType`        | 内置工具类型（`'undo'` / `'redo'` / `'select'` / `'auto-layout'` / `'search'` / `'minimap'` / `'export'` / `'zoom-in'` / `'zoom-out'` / `'reset'` 等） |
+| `NodeActionsConfig`         | 节点快捷操作工具栏全局配置（showDebug / showDelete / showCopy / showCopyInsert / showDisconnect / insertGap）                                          |
+| `QuickAddConfig`            | 快捷添加按钮全局配置（enabled / tooltipText）                                                                                                          |
+| `InsertNodeOptions`         | `insertNodeToRight` 选项（autoWireEdges / gap / source / label）                                                                                       |
+| `ExportOptions`             | 导出选项（backgroundColor / padding / quality）                                                                                                        |
+| `ConnectionValidator`       | 连接校验函数类型                                                                                                                                       |
+| `ConnectionValidateContext` | 连接校验上下文                                                                                                                                         |
+| `ConnectionValidateResult`  | 连接校验结果                                                                                                                                           |
+
+### 历史与 Overlay
+
+| 类型                   | 说明                       |
+| ---------------------- | -------------------------- |
+| `CanvasHistory`        | 历史管理器接口             |
+| `CanvasHistoryOptions` | 历史配置（maxHistorySize） |
+| `OverlayManager`       | Overlay 管理器接口         |
+| `NodeOverlayAnchors`   | 节点 Overlay 锚点定义      |
+| `OverlayAnchor`        | 单个锚点坐标               |
+
+### 编辑器
+
+| 类型                  | 说明                           |
+| --------------------- | ------------------------------ |
+| `CanvasEditorContext` | `useCanvasEditor()` 返回值类型 |
+| `CanvasEditorOptions` | `useCanvasEditor()` 参数类型   |
+
+### 插件选项
+
+| 类型                     | 说明                 |
+| ------------------------ | -------------------- |
+| `SelectionPluginOptions` | selectionPlugin 配置 |
+| `SnaplinePluginOptions`  | snaplinePlugin 配置  |
+| `MinimapPluginOptions`   | minimapPlugin 配置   |