npm package: @kingne/workflow
Description: Canvas-only workflow demo and embeddable workflow renderer powered by Bun.
Latest version: 0.1.0

# workflow

一个完全基于 `canvas` 绘制的 workflow 引擎原型，使用 `bun` 管理构建与本地运行。项目既包含编辑器 demo，也提供了可供第三方应用直接集成的 `WorkflowApp` 入口。

在线演示：

- demo: [https://kingne.github.io/workflow/](https://kingne.github.io/workflow/)


## 预览

### 主界面

![Workflow overview](./docs/images/workflow-overview.svg)

### 第三方接入示例

![Workflow integration](./docs/images/workflow-integration.svg)

## 当前能力

- 纯 `canvas` 节点、端口、连线、表格、图片、文字绘制
- `RenderManager` 调度渲染、缩放、平移、`fitView`、`focusNode`
- `Mouse` 统一处理 hover、click、拖拽、框选、连线吸附
- `EventManager` 向外委托 `hover / select / click / drag / connect` 事件
- `Scene + History + KeyControl` 支持选择、删除、撤销、重做
- `Node` 支持 `header / content / footer`、端口、参数表、运行态动画
- `Edge` 支持类型校验、连线吸附、运行中虚线流动特效
- 对外导出 `WorkflowApp`，支持 `start / destory / createNode / updateNode`

## 安装

```bash
bun install
```

## 本地运行

```bash
bun run dev
```

默认页面：

- 主 demo: `http://localhost:3000/`
- benchmark: `http://localhost:3000/benchmark.html`
- 第三方接入示例: `http://localhost:3000/integration.html`

如果 `3000` 被占用，服务会自动尝试后续端口。

## 构建

构建 demo 页面资源：

```bash
bun run build
```

### 最小接入

```ts
import { WorkflowApp, type WorkflowEdgeModel, type WorkflowNodeModel } from "@kingne/workflow";

const canvas = document.querySelector("canvas") as HTMLCanvasElement;

const nodes: WorkflowNodeModel[] = [
  {
    id: "prompt",
    title: "Prompt Builder",
    logoText: "PB",
    actionLabel: "Run",
    x: 120,
    y: 140,
    width: 440,
    height: 320,
    color: "#2563eb",
    inputs: [],
    outputs: [{ id: "prompt", label: "Prompt", dataType: "markdown" }],
    parameters: [{ label: "Model", value: "gpt-5.4-mini" }],
    statusLabel: "Ready",
    statusTone: "idle",
    errorText: "",
  },
];

const edges: WorkflowEdgeModel[] = [];

const app = new WorkflowApp({ canvas, nodes, edges });
app.start();
```

### 生命周期

```ts
app.start();
app.destory();
```

### 宿主应用创建一个 Node

```ts
app.createNode(
  {
    id: "insight",
    title: "Insight Ranker",
    logoText: "IR",
    actionLabel: "Run",
    x: 980,
    y: 120,
    width: 420,
    height: 280,
    color: "#7c3aed",
    inputs: [{ id: "notes", label: "Notes", dataType: "array" }],
    outputs: [{ id: "summary", label: "Summary", dataType: "markdown" }],
    parameters: [{ label: "Model", value: "gpt-5.4-mini" }],
    statusLabel: "Ready",
    statusTone: "idle",
    errorText: "",
  },
  { focus: true },
);
```

### 宿主应用更新某个 Node

```ts
app.updateNode("prompt", {
  title: "Prompt Builder v2",
  statusTone: "running",
  statusLabel: "Running",
  errorText: "Streaming prompt assembly",
});
```

### 宿主应用动态更新端口

```ts
app.updateNode("prompt", {
  outputs: [
    { id: "prompt", label: "Prompt", dataType: "markdown" },
    { id: "meta", label: "Meta", dataType: "json" },
    { id: "tonePreset", label: "Tone", dataType: "string" },
  ],
});
```

### 监听全局事件

```ts
app.on("click", (event) => {
  console.log(event.target?.nodeId, event.target?.item);
});

app.on("dragmove", (event) => {
  console.log(event.drag?.nodePosition);
});

app.on("connectend", (event) => {
  console.log(event.connection?.state, event.connection?.createdEdgeId);
});
```

### 视口控制

```ts
app.fitView();
app.focusNode("review", { scale: 1.15 });
```

## 可运行 examples

- 接入示例页面: `public/integration.html`
- 接入示例逻辑: `src/integration-example.ts`
- 主 demo 页面: `public/index.html`
- benchmark 页面: `public/benchmark.html`

`integration.html` 演示了这些典型宿主操作：

- `start()` 启动 workflow
- `destory()` 销毁实例
- `createNode(...)` 创建新节点
- `focusNode("review")` 聚焦节点
- `updateNode("review", ...)` 切换运行状态
- `updateNode("prompt", ...)` 修改标题、参数和输出端口

## 项目结构

- `src/index.ts`
  对外导出入口
- `src/WorkflowApp.ts`
  第三方应用集成类
- `src/render/RenderManager.ts`
  画布尺寸、渲染调度、视口控制
- `src/input/Mouse.ts`
  hover、拖拽、平移、缩放、连线
- `src/events/EventManager.ts`
  全局事件委托
- `src/workflow/Scene.ts`
  场景节点、边、选择和同步
- `src/draw/NodeDraw.ts`
  节点绘制与交互语义
- `src/draw/EdgeDraw.ts`
  连线绘制与运行态效果
- `src/draw/TableDraw.ts`
  表格绘制与行交互