@lokvis/runtime 0.2.0-beta.0 → 0.2.1

package/src/types.ts

@@ -11,12 +11,33 @@ import type {
   AssetSource,
   Capability,
   EngineSelectionStrategy,
+  ExifData,
   HistoryEntry,
   McpManifest,
+  PluginConfig,
+  PluginInstaller,
 } from '@lokvis/schema';
 import type { Workflow, WorkflowResult } from '@lokvis/schema';
 import type { EventBus } from '@lokvis/schema';
 import type { AssetStore } from './asset-store.js';
+import type { BatchProcessor } from './batch-processor.js';
+import type { HistoryStore, HistoryStoreOptions } from './history-store.js';
+
+/**
+ * 待安装的插件条目。
+ *
+ * 由 SDK 的 `createLokvis({ plugins })` 与 `loadPlugin()` 构造,
+ * 交给 `LokvisRuntime.installPlugin()` 在 runtime 内部完成注册
+ * (能力声明 + 调用 installer + 发射 plugin:loaded 事件)。
+ *
+ * 把"插件安装"提升为 Runtime 公共接口,避免 SDK 通过
+ * `instanceof LokvisRuntimeImpl` + 私有 `_getAssetStore()` /
+ * `_getCapabilityRegistry()` 反向耦合具体实现类。
+ */
+export interface PluginInstallEntry {
+  config: PluginConfig;
+  install: PluginInstaller;
+}
 
 /** Runtime 配置 */
 export interface RuntimeConfig {
@@ -40,6 +61,29 @@ export interface RuntimeConfig {
    * 按 OPFS → IndexedDB → Memory 降级。
    */
   assetStore?: AssetStore;
+  /**
+   * 注入自定义 HistoryStore(W7.2 历史持久化)。
+   * 默认由 createRuntime 在 enableIndexedDB 时通过 createHistoryStore 自动创建;
+   * IndexedDB 不可用时为 undefined,历史退化为仅内存模式。
+   */
+  historyStore?: HistoryStore;
+  /**
+   * HistoryStore 工厂选项(W7.2,仅 historyStore 未注入时生效)。
+   * 测试可注入 dbInstance 或自定义 dbName。
+   */
+  historyStoreOptions?: HistoryStoreOptions;
+  /**
+   * 是否启用 Pro 模式(W6.2 / PROJECT_PLAN 17.4)。
+   * - false(默认):批量上限 10 文件、并发 4、workflow 槽位 5
+   * - true:批量无上限、并发 16、workflow 槽位无限
+   * 由 cloud 侧 createLokvis({ auth }) 注入 session 后置为 true。
+   */
+  isPro?: boolean;
+  /**
+   * 内存预算(字节,W3.3 MemoryGuard)。
+   * 默认 512MB。BatchProcessor 据此在内存压力高时收缩并发槽位。
+   */
+  memoryBudget?: number;
 }
 
 /** Runtime 状态 */
@@ -74,6 +118,10 @@ export interface LokvisRuntime {
   readonly status: RuntimeStatus;
   /** 事件总线 */
   readonly eventBus: EventBus;
+  /** 是否为 Pro 模式(影响批量上限/并发槽位/workflow 数,W6.2) */
+  readonly isPro: boolean;
+  /** 批量处理器(W6.1:并发控制 + 进度 + 失败重试) */
+  readonly batch: BatchProcessor;
 
   // ─── 工作流执行 ──────────────────────────────────────
   /** 运行工作流 */
@@ -104,10 +152,24 @@ export interface LokvisRuntime {
   // ─── 历史与撤销 ──────────────────────────────────────
   /** 获取工作流的执行历史 */
   history(workflowId: string): Promise<HistoryEntry[]>;
+  /**
+   * 获取工作流历史状态(条目 + 当前游标)。
+   * 游标 -1 表示无已应用条目(初始状态);i 表示第 i 条已应用。
+   * 比 history() 多返回 cursor,UI 据此高亮当前步骤。
+   */
+  getHistoryState(
+    workflowId: string
+  ): Promise<{ entries: HistoryEntry[]; cursor: number }>;
   /** 撤销一步 */
   undo(workflowId: string): Promise<void>;
   /** 重做一步 */
   redo(workflowId: string): Promise<void>;
+  /**
+   * 跳转到指定历史条目(按时间顺序的索引,-1 表示回到初始)。
+   * 用于 HistoryPanel 点击条目直接跳转,等价于连续 undo/redo 到目标位置。
+   * 越界或游标未变时为 no-op。
+   */
+  jumpTo(workflowId: string, index: number): Promise<void>;
 
   // ─── Asset 管理 ──────────────────────────────────────
   /** 导入资产 */
@@ -116,10 +178,36 @@ export interface LokvisRuntime {
   getAsset(id: AssetId): Promise<Asset>;
   /** 导出资产为 Blob */
   exportAsset(id: AssetId, format?: string): Promise<Blob>;
+  /**
+   * 读取 image 资产的 EXIF 元数据(W7.3/7.4)。
+   *
+   * 长期方案(MetadataReader 依赖反转):Runtime 持有 plugin-image 通过
+   * `ctx.registerMetadataReader('image.read-exif', fn)` 注册的读取器引用,
+   * 按名调用。Plugin 未安装时优雅降级返回 null。
+   * readExif 实现位于 plugin-image(Capability 层),不进 engine-image
+   * (不符合 Engine 层 Blob↔Blob 纯函数约束)。
+   * UI 通过此方法访问 EXIF,不直接依赖 Engine/Plugin 包(五层架构单向依赖)。
+   *
+   * @param id 资产 ID(须为 image 类型)
+   * @returns ExifData;非 image / 无 EXIF / 解析失败 / reader 未注册返回 null
+   */
+  readAssetExif(id: AssetId): Promise<ExifData | null>;
   /** 删除资产 */
   removeAsset(id: AssetId): Promise<void>;
   /** 列出所有资产 */
   listAssets(): Promise<Asset[]>;
+  /**
+   * 查询存储配额使用情况(W6.7)。
+   *
+   * 返回 `{ usage, quota }`:
+   * - `usage`:当前已用字节数(所有资产 metadata.size 之和)
+   * - `quota`:配置的存储配额上限(RuntimeConfig.storageQuota,默认 1GB)
+   *
+   * UI 据此展示"已用/总额"进度条,接近上限(>=80%)时警告。
+   * 注意:usage 基于 listAssets 实时计算,反映 runtime 实际占用,
+   * 与浏览器 `navigator.storage.estimate()`(origin 整体 OPFS)不同。
+   */
+  getStorageUsage(): Promise<{ usage: number; quota: number }>;
 
   // ─── 能力查询 ────────────────────────────────────────
   /** 列出所有已注册能力 */
@@ -145,4 +233,23 @@ export interface LokvisRuntime {
    * 仅为接口对称性(未来可能涉及异步加载)。
    */
   toMcpManifest(options?: ToMcpManifestOptions): McpManifest;
+
+  // ─── 插件安装 ────────────────────────────────────────
+  /**
+   * 在 Runtime 上安装一个插件。
+   *
+   * 步骤:
+   * 1. 把 plugin.config.capabilities 注册到 CapabilityRegistry(声明能力)
+   * 2. 构造受限 PluginContext(只暴露 getAsset/importAsset/getAssetBlob/
+   *    createAsset/listCapabilities + eventBus + registerCapability +
+   *    registerMetadataReader + registerPanel + log)
+   * 3. 调用 plugin.install(ctx),让插件注册 CapabilityImplementation
+   * 4. 发射 `plugin:loaded` 事件
+   *
+   * SDK 的 `createLokvis({ plugins })` 与 `loadPlugin()` 都委托到这里,
+   * 不再需要 `instanceof LokvisRuntimeImpl` + `_getAssetStore()` 等内部 API。
+   *
+   * @throws plugin.install 抛出的任何错误(runtime 不吞错,由 SDK 包成 PluginLoadError)
+   */
+  installPlugin(plugin: PluginInstallEntry): Promise<void>;
 }

package/src/worker-host.ts

@@ -28,6 +28,7 @@ import {
   isWorkerFatalError,
   type WorkerRequest,
   type WorkerPing,
+  type WorkerCancel,
 } from './worker-protocol.js';
 
 // ─── 传输层抽象 ─────────────────────────────────────────────────
@@ -105,6 +106,22 @@ export class WorkerHandshakeError extends Error {
   }
 }
 
+/**
+ * 请求被 AbortSignal 取消(W3.5 cancel 贯穿)。
+ *
+ * 与超时/崩溃不同:cancel 是调用方主动发起的,Host 会向 Worker
+ * 发送 WorkerCancel 消息让在途操作尽快中止,同时本地立即 reject,
+ * 不等 Worker 回响应。
+ */
+export class WorkerRequestAbortedError extends Error {
+  readonly method: string;
+  constructor(method: string) {
+    super(`Request "${method}" was aborted via AbortSignal`);
+    this.name = 'WorkerRequestAbortedError';
+    this.method = method;
+  }
+}
+
 // ─── Host 选项与事件 ────────────────────────────────────────────
 
 export interface WorkerHostOptions {
@@ -230,14 +247,8 @@ export class WorkerHost {
   async dispose(): Promise<void> {
     if (this.status === 'disposed') return;
     this.status = 'disposed';
-    this.clearHeartbeat();
     this.rejectAllPending(new Error('WorkerHost disposed'));
-    this.offMessage?.();
-    this.offError?.();
-    this.offMessage = null;
-    this.offError = null;
-    this.transport?.terminate();
-    this.transport = null;
+    this.teardownTransport();
     this.listeners.clear();
   }
 
@@ -247,7 +258,12 @@ export class WorkerHost {
   async request<T = unknown>(
     method: string,
     params?: unknown,
-    options?: { transfer?: Transferable[]; timeoutMs?: number }
+    options?: {
+      transfer?: Transferable[];
+      timeoutMs?: number;
+      /** 取消信号:触发时向 Worker 发送 WorkerCancel 并立即 reject(W3.5) */
+      signal?: AbortSignal;
+    }
   ): Promise<T> {
     if (this.status === 'disposed') throw new Error('WorkerHost is disposed');
     if (this.status === 'dead') throw new WorkerDeadError(this.restartCount);
@@ -255,6 +271,12 @@ export class WorkerHost {
       throw new WorkerRestartingError();
     }
 
+    const signal = options?.signal;
+    // 已取消:不发送,直接 reject
+    if (signal?.aborted) {
+      throw new WorkerRequestAbortedError(method);
+    }
+
     const id = createRequestId();
     const timeoutMs = options?.timeoutMs ?? this.opts.requestTimeoutMs;
     const msg: WorkerRequest = { id, type: 'request', method, params };
@@ -262,13 +284,34 @@ export class WorkerHost {
     return new Promise<T>((resolve, reject) => {
       const timer = setTimeout(() => {
         if (this.pending.delete(id)) {
+          offAbort();
           reject(new WorkerRequestTimeoutError(method, timeoutMs));
         }
       }, timeoutMs);
 
+      // W3.5:signal 触发 → 发 WorkerCancel + 立即 reject(不等 Worker 回响应)
+      const onAbort = () => {
+        if (this.pending.delete(id)) {
+          clearTimeout(timer);
+          const cancelMsg: WorkerCancel = { type: 'cancel', id };
+          this.send(cancelMsg);
+          reject(new WorkerRequestAbortedError(method));
+        }
+      };
+      const offAbort = signal
+        ? () => signal.removeEventListener('abort', onAbort)
+        : () => {};
+      if (signal) signal.addEventListener('abort', onAbort, { once: true });
+
       this.pending.set(id, {
-        resolve: (v) => resolve(v as T),
-        reject,
+        resolve: (v) => {
+          offAbort();
+          resolve(v as T);
+        },
+        reject: (e) => {
+          offAbort();
+          reject(e);
+        },
         timer,
         method,
       });
@@ -315,12 +358,9 @@ export class WorkerHost {
       });
     } catch (err) {
       clearTimeout(readyTimer!);
-      this.offMessage?.();
-      this.offError?.();
-      this.offMessage = null;
-      this.offError = null;
-      transport.terminate();
-      this.transport = null;
+      // this.transport 在 spawn 顶部已赋值,teardownTransport 可安全清理
+      // (clearHeartbeat 对未启动的心跳是无害 no-op)
+      this.teardownTransport();
       throw err as Error;
     }
 

package/src/worker-protocol.ts

@@ -48,7 +48,17 @@ export interface WorkerPing {
   ts: number;
 }
 
-export type WorkerMessageToWorker = WorkerRequest | WorkerPing;
+/**
+ * 取消一个正在执行的请求(W3.5 cancel 贯穿)。
+ * Host 在 AbortSignal 触发时发送,Worker 据此中止当前计算。
+ */
+export interface WorkerCancel {
+  type: 'cancel';
+  /** 要取消的请求 id */
+  id: string;
+}
+
+export type WorkerMessageToWorker = WorkerRequest | WorkerPing | WorkerCancel;
 
 // ─── Worker → Host 消息 ─────────────────────────────────────────
 

package/src/workflow-builder.ts

@@ -0,0 +1,303 @@
+/**
+ * WorkflowBuilder - 线性工作流链式构造器(W10.1)
+ *
+ * 提供链式 API 构造线性 Workflow(第一年不支持 Branch/Loop/Condition/Parallel)。
+ *
+ * 限制:
+ *   - 最多 5 步(M1 MVP 约束,免费用户定位,避免复杂度过高)
+ *   - 节点必须为 transform 类型(load/export 由执行器隐式处理)
+ *   - 自动生成线性 edges:node[i] → node[i+1]
+ *
+ * 使用示例:
+ * ```typescript
+ * const workflow = new WorkflowBuilder('my-workflow', 'Web 优化')
+ *   .setInput({ type: 'image', multiple: true })
+ *   .setOutput({ type: 'image', format: 'webp' })
+ *   .add('image.resize', { width: 1920, fit: 'inside' })
+ *   .add('image.compress', { format: 'webp', quality: 80 })
+ *   .add('image.watermark', { text: '@lokvis' })
+ *   .build();
+ * ```
+ *
+ * 与 workflow-slice 的 buildLinearWorkflow 区别:
+ *   - buildLinearWorkflow 是内部工具函数,从 WorkspaceNode[] 构造无校验
+ *   - WorkflowBuilder 是公开 API,链式调用 + 5 步上限校验 + 元数据完善
+ *
+ * @module workflow-builder
+ */
+
+import type {
+  AssetType,
+  Workflow,
+  WorkflowAuthor,
+  WorkflowCategory,
+  WorkflowEdge,
+  WorkflowInput,
+  WorkflowNode,
+  WorkflowOutput,
+} from '@lokvis/schema';
+
+/** 工作流最大节点数(M1 MVP 约束) */
+export const MAX_WORKFLOW_STEPS = 5;
+
+/** Builder 内部节点结构(构造中,与 WorkflowNode 略有差异:label 可独立设置) */
+interface BuilderNode {
+  /** 内部生成的节点 id(builder 内部唯一) */
+  id: string;
+  capability: string;
+  params: Record<string, unknown>;
+  label?: string;
+}
+
+/** WorkflowBuilder 构造选项 */
+export interface WorkflowBuilderOptions {
+  /** 工作流 ID(必填,需全局唯一) */
+  id: string;
+  /** 工作流名称 */
+  name: string;
+  /** 工作流描述(可选,默认为空字符串) */
+  description?: string;
+  /** 作者信息(可选,默认本地用户) */
+  author?: WorkflowAuthor;
+  /** 分类(可选,默认 'image') */
+  category?: WorkflowCategory;
+  /** 标签(可选) */
+  tags?: string[];
+  /** 是否为官方工作流(可选,默认 false) */
+  official?: boolean;
+  /** 最大节点数(可选,默认 MAX_WORKFLOW_STEPS;测试或特殊场景可放宽) */
+  maxSteps?: number;
+}
+
+/**
+ * WorkflowBuilder - 链式构造线性 Workflow。
+ *
+ * 抛错时机:
+ *   - add() 超过 maxSteps 时立即抛错(避免构造完才发现步数超限)
+ *   - build() 在节点为空 / 输入输出未设置时抛错
+ *   - remove()/move() 在节点 id 不存在时静默(链式 API 容错)
+ */
+export class WorkflowBuilder {
+  private readonly options: WorkflowBuilderOptions;
+  private readonly maxSteps: number;
+  private nodes: BuilderNode[] = [];
+  private input: WorkflowInput | null = null;
+  private output: WorkflowOutput | null = null;
+  private nodeCounter = 0;
+
+  constructor(options: WorkflowBuilderOptions) {
+    if (!options.id) throw new Error('WorkflowBuilder: id is required');
+    if (!options.name) throw new Error('WorkflowBuilder: name is required');
+    this.options = options;
+    this.maxSteps = options.maxSteps ?? MAX_WORKFLOW_STEPS;
+  }
+
+  /** 设置工作流输入定义 */
+  setInput(input: WorkflowInput): this {
+    this.input = input;
+    return this;
+  }
+
+  /** 设置工作流输出定义 */
+  setOutput(output: WorkflowOutput): this {
+    this.output = output;
+    return this;
+  }
+
+  /**
+   * 添加一个节点到链尾。
+   *
+   * @param capability 能力名,如 `image.resize`
+   * @param params 能力参数(可选,默认空对象)
+   * @param label 节点标签(可选,UI 显示用)
+   * @throws Error 当节点数达到 maxSteps 时
+   */
+  add(
+    capability: string,
+    params: Record<string, unknown> = {},
+    label?: string
+  ): this {
+    if (!capability) throw new Error('WorkflowBuilder.add: capability is required');
+    if (this.nodes.length >= this.maxSteps) {
+      throw new Error(
+        `WorkflowBuilder.add: max steps (${this.maxSteps}) reached; ` +
+          `cannot add more nodes. Adjust maxSteps option if needed.`
+      );
+    }
+    this.nodeCounter += 1;
+    this.nodes.push({
+      id: `${this.options.id}-node-${this.nodeCounter}`,
+      capability,
+      params,
+      label,
+    });
+    return this;
+  }
+
+  /**
+   * 按 capability 或节点 id 移除节点。
+   * 若有多个同 capability 节点,只移除第一个。
+   * 若不存在则静默(链式 API 容错)。
+   *
+   * @param capabilityOrId 能力名或节点 id
+   */
+  remove(capabilityOrId: string): this {
+    const idx = this.nodes.findIndex(
+      (n) => n.id === capabilityOrId || n.capability === capabilityOrId
+    );
+    if (idx >= 0) {
+      this.nodes.splice(idx, 1);
+    }
+    return this;
+  }
+
+  /**
+   * 移动节点到新位置(线性链中重排)。
+   *
+   * @param from 源位置(0-based 索引)
+   * @param to 目标位置(0-based 索引,移动后该节点的新位置)
+   * @throws Error 当索引越界
+   */
+  move(from: number, to: number): this {
+    if (from < 0 || from >= this.nodes.length) {
+      throw new Error(`WorkflowBuilder.move: from index ${from} out of range`);
+    }
+    if (to < 0 || to >= this.nodes.length) {
+      throw new Error(`WorkflowBuilder.move: to index ${to} out of range`);
+    }
+    if (from === to) return this;
+    const [node] = this.nodes.splice(from, 1);
+    // splice(from, 1) 在已校验的 in-range 索引上必返回 1 元素;
+    // 此处显式检查以满足 noUncheckedIndexedAccess,并在不变量被打破时报错
+    if (!node) {
+      throw new Error(`WorkflowBuilder.move: source node at index ${from} missing`);
+    }
+    this.nodes.splice(to, 0, node);
+    return this;
+  }
+
+  /** 交换两个节点位置 */
+  swap(i: number, j: number): this {
+    if (i < 0 || i >= this.nodes.length || j < 0 || j >= this.nodes.length) {
+      throw new Error('WorkflowBuilder.swap: index out of range');
+    }
+    if (i === j) return this;
+    const a = this.nodes[i];
+    const b = this.nodes[j];
+    // 上方范围校验保证 i / j 在界内;显式检查以满足 noUncheckedIndexedAccess
+    if (!a || !b) {
+      throw new Error('WorkflowBuilder.swap: node missing (invariant violated)');
+    }
+    this.nodes[i] = b;
+    this.nodes[j] = a;
+    return this;
+  }
+
+  /** 更新指定节点的参数 */
+  updateParams(nodeId: string, params: Record<string, unknown>): this {
+    const node = this.nodes.find((n) => n.id === nodeId);
+    if (node) {
+      node.params = { ...node.params, ...params };
+    }
+    return this;
+  }
+
+  /** 当前节点数 */
+  get size(): number {
+    return this.nodes.length;
+  }
+
+  /** 是否已达最大节点数 */
+  get isFull(): boolean {
+    return this.nodes.length >= this.maxSteps;
+  }
+
+  /** 获取节点的只读副本(用于 UI 预览) */
+  getNodes(): ReadonlyArray<Readonly<BuilderNode>> {
+    return this.nodes.map((n) => ({ ...n }));
+  }
+
+  /**
+   * 构造 Workflow 实例。
+   *
+   * @throws Error 当节点为空 / 输入未设置 / 输出未设置
+   */
+  build(): Workflow {
+    if (this.nodes.length === 0) {
+      throw new Error('WorkflowBuilder.build: no nodes added');
+    }
+    if (!this.input) {
+      throw new Error('WorkflowBuilder.build: input not set (call setInput first)');
+    }
+    if (!this.output) {
+      throw new Error('WorkflowBuilder.build: output not set (call setOutput first)');
+    }
+
+    const workflowNodes: WorkflowNode[] = this.nodes.map((n) => ({
+      id: n.id,
+      type: 'transform' as const,
+      capability: n.capability,
+      params: n.params,
+      label: n.label,
+    }));
+
+    const edges: WorkflowEdge[] = [];
+    for (let i = 0; i < workflowNodes.length - 1; i++) {
+      const fromNode = workflowNodes[i];
+      const toNode = workflowNodes[i + 1];
+      // 循环边界 i < length - 1 保证 i 与 i+1 均在界内;显式检查以满足 noUncheckedIndexedAccess
+      if (!fromNode || !toNode) {
+        throw new Error('WorkflowBuilder.build: edge node missing (invariant violated)');
+      }
+      edges.push({
+        from: fromNode.id,
+        to: toNode.id,
+      });
+    }
+
+    const now = Date.now();
+    return {
+      $schema: `https://lokvis.dev/schemas/workflow.json`,
+      id: this.options.id,
+      version: '1.0.0',
+      name: this.options.name,
+      description: this.options.description ?? '',
+      author: this.options.author ?? { id: 'local', name: 'Local User' },
+      category: this.options.category ?? 'image',
+      tags: this.options.tags ?? [],
+      nodes: workflowNodes,
+      edges,
+      inputs: this.input,
+      outputs: this.output,
+      official: this.options.official ?? false,
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+}
+
+/** 从 Workflow 反向构造 Builder(用于编辑已有工作流) */
+export function workflowToBuilder(workflow: Workflow, maxSteps?: number): WorkflowBuilder {
+  const builder = new WorkflowBuilder({
+    id: workflow.id,
+    name: workflow.name,
+    description: workflow.description,
+    author: workflow.author,
+    category: workflow.category,
+    tags: workflow.tags,
+    official: workflow.official,
+    maxSteps,
+  });
+  builder.setInput(workflow.inputs);
+  builder.setOutput(workflow.outputs);
+  // 按拓扑顺序添加节点(线性链 nodes 数组即顺序)
+  for (const node of workflow.nodes) {
+    if (node.type === 'transform' && node.capability) {
+      builder.add(node.capability, node.params ?? {}, node.label);
+    }
+  }
+  return builder;
+}
+
+/** AssetType 用于类型导出(便于消费方) */
+export type { AssetType };