@lokvis/runtime 0.2.2 → 0.4.2

package/src/managers/asset-manager.ts

@@ -0,0 +1,259 @@
+/**
+ * Asset Manager
+ *
+ * 从 runtime.ts 抽取的资产操作逻辑,包装为独立类。
+ *
+ * 职责:
+ * - importAsset:URL fetch + 超时保护 / OPFS 不支持错误 / blob 导入 + 事件发射
+ * - getAsset:资产查找(不存在抛 "Asset not found")
+ * - exportAsset:OPFS fallback MIME 补全 + arrayBuffer 显式拉取(避免悬空引用)
+ * - readAssetExif:MetadataReader 依赖反转查找与降级
+ * - removeAsset:删除 + 事件发射
+ * - listAssets:列表
+ * - getStorageUsage:O(1) 缓存路径 + O(n) fallback
+ *
+ * 设计:
+ * - 通过 deps 注入 assetStore / eventBus / metadataReaders / storageQuota,
+ *   不持有 Runtime 实例,避免循环依赖。
+ * - metadataReaders 由 Runtime 持有并通过 `_registerMetadataReader` 写入,
+ *   这里按引用读取(Map 突变对 AssetManager 立即可见),保持 Plugin 注册语义不变。
+ */
+
+import type {
+  Asset,
+  AssetId,
+  AssetSource,
+  EventBus,
+  ExifData,
+  ImageMetadata,
+  MetadataReader,
+  MetadataReaderContext,
+  PdfInfo,
+} from '@lokvis/schema';
+import type { QuotaAwareAssetStore } from './quota-manager.js';
+import { AssetNotFoundError } from '../errors.js';
+
+/** AssetManager 依赖 */
+export interface AssetManagerDeps {
+  assetStore: QuotaAwareAssetStore;
+  eventBus: EventBus;
+  metadataReaders: Map<string, MetadataReader>;
+  /** 配额上限,用于 getStorageUsage 返回值(不参与校验,校验在 quota-manager 内) */
+  storageQuota: number;
+}
+
+/** OPFS 后端用 .bin 存储时,File.type 退化的兜底 MIME */
+const OPFS_FALLBACK_MIME = 'application/octet-stream';
+
+/** URL 导入超时(覆盖绝大多数正常图片下载) */
+const URL_FETCH_TIMEOUT_MS = 30_000;
+
+/** AssetManager:资产操作封装,由 RuntimeImpl 持有并委托 */
+export class AssetManager {
+  constructor(private readonly deps: AssetManagerDeps) {}
+
+  /**
+   * 导入资产。
+   *
+   * - file/blob 源直接透传给 assetStore.import
+   * - url 源在 runtime 层 fetch → blob(含 30s 超时保护),再走 blob 导入
+   * - opfs 源暂不支持(OPFS 路径访问需要 filesystem access permission,未来单独实现)
+   */
+  async importAsset(source: AssetSource): Promise<AssetId> {
+    // 修复 review 报告：原实现直接透传 source 给 assetStore.import，
+    // 但 MemoryAssetStore/OpfsAssetStore/IdbAssetStore 的 extractBlobFromSource
+    // 仅支持 file/blob 两种 kind，url/opfs 会抛 "not supported"。
+    // 这里在 runtime 层兜底处理 url（fetch → blob），opfs 暂不支持（OPFS
+    // 路径访问需要 filesystem access permission，未来单独实现）
+    let effectiveSource = source;
+    if (source.kind === 'url') {
+      // 超时保护:防止慢响应或挂起的 URL 无限期阻塞 import。
+      // 30s 覆盖绝大多数正常图片下载;超时后 abort 并抛明确错误。
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), URL_FETCH_TIMEOUT_MS);
+      try {
+        const resp = await fetch(source.url, { signal: controller.signal });
+        if (!resp.ok) {
+          throw new Error(`Failed to fetch asset from ${source.url}: ${resp.status} ${resp.statusText}`);
+        }
+        const blob = await resp.blob();
+        const name = source.url.split('/').pop()?.split('?')[0] || 'asset';
+        effectiveSource = { kind: 'blob', blob, name };
+      } catch (err) {
+        if (err instanceof DOMException && err.name === 'AbortError') {
+          throw new Error(`Failed to fetch asset from ${source.url}: timed out after 30s`);
+        }
+        throw err;
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } else if (source.kind === 'opfs') {
+      throw new Error(
+        "AssetSource kind 'opfs' is not yet supported by importAsset; " +
+          'use the OPFS-aware AssetStore directly or convert to blob first'
+      );
+    }
+
+    const asset = await this.deps.assetStore.import(effectiveSource);
+    this.deps.eventBus.emit({
+      type: 'asset:imported',
+      assetId: asset.id,
+      metadata: asset.metadata,
+    });
+    return asset.id;
+  }
+
+  /**
+   * 获取资产(不存在抛 AssetNotFoundError,SDK 经 instanceof 转换)。
+   */
+  async getAsset(id: AssetId): Promise<Asset> {
+    const asset = await this.deps.assetStore.get(id);
+    if (!asset) throw new AssetNotFoundError(id);
+    return asset;
+  }
+
+  /**
+   * 导出资产为 Blob。
+   *
+   * OPFS 存储后端用 .bin 扩展名存储,读取时 fileHandle.getFile() 返回的
+   * File.type 可能为空字符串或 'application/octet-stream'(浏览器对未知扩展名
+   * 的默认兜底 MIME)。这两种情况都会导致 Object URL 的 Content-Type 退化,
+   * 下载时文件扩展名变成 .octet-stream。
+   * 用 asset metadata 的 mimeType 补全 Blob type(IDB/Memory 后端不受影响)。
+   *
+   * 关键:用 arrayBuffer() 显式读取数据到内存,再构造新 Blob。
+   * 不能用 new Blob([blob]) —— 浏览器实现中它可能延迟引用底层 OPFS 文件,
+   * WatermarkBatchTool 在 export 后立即 removeAsset 删除 OPFS 文件,
+   * 导致后续 downloadBlob 读取悬空引用失败("check internet connection")。
+   * arrayBuffer() 立即拉取数据,确保返回的 Blob 完全独立于底层存储。
+   */
+  async exportAsset(id: AssetId, format?: string): Promise<Blob> {
+    const asset = await this.getAsset(id);
+    const blob = await this.deps.assetStore.getBlob(asset.blob);
+    const mimeType =
+      !blob.type || blob.type === OPFS_FALLBACK_MIME
+        ? asset.metadata.mimeType
+        : blob.type;
+    const buffer = await blob.arrayBuffer();
+    const exported = new Blob([buffer], { type: mimeType });
+    this.deps.eventBus.emit({
+      type: 'export:completed',
+      assetId: id,
+      format: format ?? asset.metadata.format,
+      size: blob.size,
+    });
+    return exported;
+  }
+
+  /**
+   * 读取 image 资产的 EXIF 元数据(W7.3/7.4 长期方案:MetadataReader 依赖反转)。
+   *
+   * Runtime 持有 plugin-image 通过 ctx.registerMetadataReader('image.read-exif', fn)
+   * 注册的 reader 引用,按名调用。reader 内部调 readExifFromBlob(exifr)。
+   * Plugin 未安装时优雅降级返回 null(不抛错)。
+   *
+   * 架构决策:readExif 是 Blob→ExifData 查询,不符合 Engine 层 Blob↔Blob 纯函数
+   * 约束,也不符合 Capability Asset[]→Asset[] 契约,故走 MetadataReader 机制,
+   * 不进 engine-image、不走 Capability execute。
+   */
+  async readAssetExif(id: AssetId): Promise<ExifData | null> {
+    const asset = await this.getAsset(id);
+    if (asset.type !== 'image') return null;
+    const reader = this.deps.metadataReaders.get('image.read-exif');
+    if (!reader) return null; // Plugin 未安装,优雅降级
+
+    // TD-3.4 长期方案:构造 MetadataReaderContext,为 reader 提供可观测信号。
+    // log 前缀含 assetId,便于 Sentry 上报与调试时关联具体资产。
+    // info 级别不输出(避免噪音),warn/error 走 console。
+    const readerCtx: MetadataReaderContext = {
+      log: (level, message) => {
+        const prefix = `[lokvis:read-asset-exif:${id}]`;
+        if (level === 'error') console.error(`${prefix} ${message}`);
+        else if (level === 'warn') console.warn(`${prefix} ${message}`);
+        // info 不输出(避免噪音)
+      },
+    };
+    return reader(asset, readerCtx) as Promise<ExifData | null>;
+  }
+
+  /**
+   * 读取 image 资产的 dimensions/format 元数据(MetadataReader 依赖反转)。
+   *
+   * Runtime 持有 plugin-image 通过 ctx.registerMetadataReader(
+   * 'image.read-metadata', fn) 注册的 reader 引用,按名调用。reader 内部调
+   * engine-image/node 的 getMetadata(sharp .metadata())。
+   * Plugin 未安装时优雅降级返回 null(不抛错)。
+   *
+   * 架构意义:mcp-server 经此方法读取处理后输出图像的精确尺寸,不再直接
+   * import @lokvis/engine-image(五层架构单向依赖,见 A1 修复)。
+   */
+  async readAssetImageMetadata(id: AssetId): Promise<ImageMetadata | null> {
+    const asset = await this.getAsset(id);
+    if (asset.type !== 'image') return null;
+    const reader = this.deps.metadataReaders.get('image.read-metadata');
+    if (!reader) return null; // Plugin 未安装,优雅降级
+
+    const readerCtx: MetadataReaderContext = {
+      log: (level, message) => {
+        const prefix = `[lokvis:read-asset-image-metadata:${id}]`;
+        if (level === 'error') console.error(`${prefix} ${message}`);
+        else if (level === 'warn') console.warn(`${prefix} ${message}`);
+      },
+    };
+    return reader(asset, readerCtx) as Promise<ImageMetadata | null>;
+  }
+
+  /**
+   * 读取 pdf 资产的页数(MetadataReader 依赖反转)。
+   *
+   * Runtime 持有 plugin-pdf 通过 ctx.registerMetadataReader(
+   * 'pdf.read-info', fn) 注册的 reader 引用,按名调用。reader 内部调
+   * engine-pdf 的 getPdfInfo(pdf-lib getPageCount)。
+   * Plugin 未安装时优雅降级返回 null(不抛错)。
+   *
+   * 架构意义:mcp-server 经此方法读取处理后输出 PDF 的页数,不再直接
+   * import @lokvis/engine-pdf(五层架构单向依赖,见 A1 修复)。
+   */
+  async readAssetPdfInfo(id: AssetId): Promise<PdfInfo | null> {
+    const asset = await this.getAsset(id);
+    if (asset.type !== 'pdf') return null;
+    const reader = this.deps.metadataReaders.get('pdf.read-info');
+    if (!reader) return null; // Plugin 未安装,优雅降级
+
+    const readerCtx: MetadataReaderContext = {
+      log: (level, message) => {
+        const prefix = `[lokvis:read-asset-pdf-info:${id}]`;
+        if (level === 'error') console.error(`${prefix} ${message}`);
+        else if (level === 'warn') console.warn(`${prefix} ${message}`);
+      },
+    };
+    return reader(asset, readerCtx) as Promise<PdfInfo | null>;
+  }
+
+  async removeAsset(id: AssetId): Promise<void> {
+    await this.deps.assetStore.remove(id);
+    this.deps.eventBus.emit({ type: 'asset:removed', assetId: id });
+  }
+
+  async listAssets(): Promise<Asset[]> {
+    return this.deps.assetStore.list();
+  }
+
+  /**
+   * 获取存储使用情况。
+   *
+   * m6 优化:优先用配额包装器内部维护的 usage(O(1),import/create/remove
+   * 时增量更新),避免每次 O(n) 全量 listAssets 影响 StatusBar 刷新。
+   * 包装器未就绪(ensureInit 未完成)返回 -1 时,fallback 到 listAssets
+   * 实时计算(source of truth,与 W6.4 富元数据一致)。
+   */
+  async getStorageUsage(): Promise<{ usage: number; quota: number }> {
+    const cached = this.deps.assetStore._getQuotaUsage();
+    if (cached >= 0) {
+      return { usage: cached, quota: this.deps.storageQuota };
+    }
+    const all = await this.deps.assetStore.list();
+    const usage = all.reduce((sum, a) => sum + a.metadata.size, 0);
+    return { usage, quota: this.deps.storageQuota };
+  }
+}

package/src/managers/history-manager.ts

@@ -0,0 +1,327 @@
+/**
+ * History Manager(W1.3 从 runtime.ts 抽取)
+ *
+ * 持有每个工作流的 HistoryStack + initialInputs / currentOutputs 映射,
+ * 提供 history / undo / redo / jumpTo,监听 node:finished 自动 append,
+ * LRU 上限清理,持久化快照到 historyStore(IDB)支持跨会话恢复。
+ * deps 注入 eventBus / assetStore / historyStore?,不持有 Runtime 实例避免
+ * 循环依赖。prepareForRun / recordRunResult 供 WorkflowCoordinator 调用。
+ */
+
+import type {
+  AssetId,
+  EventBus,
+  HistoryEntry,
+  LokvisEvent,
+} from '@lokvis/schema';
+import { generateId } from '../asset-store.js';
+import { HistoryStack, type HistoryStackConfig } from '../history.js';
+import type { HistoryStore } from '../history-store.js';
+import type { QuotaAwareAssetStore } from './quota-manager.js';
+
+const DEFAULT_MAX_HISTORY = 10;
+
+/** 同时持有的工作流历史栈上限(W2.8);超限按 FIFO 清理最旧 stack。 */
+const MAX_CONCURRENT_WORKFLOW_STACKS = 32;
+
+export interface HistoryManagerDeps {
+  eventBus: EventBus;
+  assetStore: QuotaAwareAssetStore;
+  /** undefined 时退化为仅内存历史(刷新后丢失) */
+  historyStore?: HistoryStore;
+}
+
+/** 历史栈管理封装,由 RuntimeImpl 持有并委托 */
+export class HistoryManager {
+  private historyStacks = new Map<string, HistoryStack>();
+  private initialInputsMap = new Map<string, AssetId[]>();
+  private currentOutputsMap = new Map<string, AssetId[]>();
+  /** 加载快照期间守卫:restore() 触发 onChanged → persistHistory 时跳过冗余写回 */
+  private isLoadingHistory = false;
+  /**
+   * 加载期间被跳过的 persistHistory 加入此 Set,loadPersistedHistory 结束后
+   * 逐个补 persist,避免加载期间变更被永久丢弃(W7.2 review 修复)。
+   */
+  private dirtyDuringLoad = new Set<string>();
+
+  constructor(private readonly deps: HistoryManagerDeps) {
+    this.deps.eventBus.on('node:finished', (event) => {
+      this.recordFromNodeEvent(
+        event as Extract<LokvisEvent, { type: 'node:finished' }>
+      );
+    });
+  }
+
+  async history(workflowId: string): Promise<HistoryEntry[]> {
+    return this.historyStacks.get(workflowId)?.list() ?? [];
+  }
+
+  async getHistoryState(
+    workflowId: string
+  ): Promise<{ entries: HistoryEntry[]; cursor: number }> {
+    const stack = this.historyStacks.get(workflowId);
+    if (!stack) return { entries: [], cursor: -1 };
+    const snap = stack.snapshot();
+    return { entries: snap.entries, cursor: snap.cursor };
+  }
+
+  /** 工作流当前输出 AssetId(undo/redo 后的"当前"状态) */
+  getCurrentOutputs(workflowId: string): AssetId[] {
+    return this.currentOutputsMap.get(workflowId) ?? [];
+  }
+
+  // history:changed 事件由 stack.onChanged 统一发射,避免双发
+  async undo(workflowId: string): Promise<void> {
+    const stack = this.getOrCreateStack(workflowId);
+    const result = stack.undo();
+    if (result === undefined) return;
+    // null 表示回到初始状态 → 用 initialInputs;entry → 用其 outputs
+    const newCurrent = result === null
+      ? (this.initialInputsMap.get(workflowId) ?? [])
+      : result.outputs;
+    this.currentOutputsMap.set(workflowId, newCurrent);
+  }
+
+  async redo(workflowId: string): Promise<void> {
+    const stack = this.getOrCreateStack(workflowId);
+    const entry = stack.redo();
+    if (entry === undefined) return;
+    this.currentOutputsMap.set(workflowId, entry.outputs);
+  }
+
+  async jumpTo(workflowId: string, index: number): Promise<void> {
+    const stack = this.getOrCreateStack(workflowId);
+    const result = stack.jumpTo(index);
+    if (result === undefined) return;
+    const newCurrent = result === null
+      ? (this.initialInputsMap.get(workflowId) ?? [])
+      : result.outputs;
+    this.currentOutputsMap.set(workflowId, newCurrent);
+  }
+
+  /**
+   * run() 前的历史栈准备:
+   * - appendHistory=true 且已有栈:保留栈与 currentOutputs,仅确保初始输入已记录
+   * - 否则(默认重置):丢弃旧历史,重新初始化
+   * 然后执行 LRU 上限清理。
+   */
+  prepareForRun(
+    workflowId: string,
+    inputIds: AssetId[],
+    appendHistory: boolean
+  ): void {
+    if (appendHistory && this.historyStacks.has(workflowId)) {
+      if (!this.initialInputsMap.has(workflowId)) {
+        this.initialInputsMap.set(workflowId, inputIds);
+      }
+    } else {
+      const existingStack = this.historyStacks.get(workflowId);
+      if (existingStack) {
+        existingStack.reset();
+      }
+      this.initialInputsMap.set(workflowId, inputIds);
+      this.currentOutputsMap.set(workflowId, inputIds);
+    }
+    this.enforceStacksLimit(workflowId);
+  }
+
+  /** run() 成功完成后,记录最终输出为当前(outputs 非空时)。 */
+  recordRunResult(workflowId: string, outputs: AssetId[]): void {
+    if (outputs.length > 0) {
+      this.currentOutputsMap.set(workflowId, outputs);
+    }
+  }
+
+  /** node:finished 事件处理:append 到对应工作流栈,inputs 取上一步 outputs。 */
+  recordFromNodeEvent(
+    event: Extract<LokvisEvent, { type: 'node:finished' }>
+  ): void {
+    if (!event.outputs || event.outputs.length === 0) return;
+
+    const stack = this.getOrCreateStack(event.workflowId);
+    const outputs = event.outputs.map((a) => a.id);
+    const inputs = this.currentOutputsMap.get(event.workflowId) ?? [];
+
+    const entry: HistoryEntry = {
+      id: generateId(),
+      workflowId: event.workflowId,
+      nodeId: event.nodeId,
+      capability: event.capability,
+      params: event.params,
+      inputs,
+      outputs,
+      timestamp: Date.now(),
+    };
+
+    stack.append(entry);
+    this.currentOutputsMap.set(event.workflowId, outputs);
+  }
+
+  /**
+   * LRU 上限清理:超 MAX_CONCURRENT_WORKFLOW_STACKS 时按 FIFO 删最旧 stack
+   * (reset 触发 onEvict → assetStore.remove 回收资产)。
+   * appendHistory 模式下当前工作流栈必须跳过,否则 FIFO 首位时被误删。
+   */
+  enforceStacksLimit(currentWorkflowId: string): void {
+    while (this.historyStacks.size >= MAX_CONCURRENT_WORKFLOW_STACKS) {
+      let oldestId = this.historyStacks.keys().next().value;
+      if (oldestId === undefined) break;
+      if (oldestId === currentWorkflowId) {
+        const iter = this.historyStacks.keys();
+        iter.next();
+        oldestId = iter.next().value;
+        if (oldestId === undefined) break;
+      }
+      const stack = this.historyStacks.get(oldestId);
+      if (stack) {
+        stack.reset();
+      }
+      this.historyStacks.delete(oldestId);
+      this.initialInputsMap.delete(oldestId);
+      this.currentOutputsMap.delete(oldestId);
+    }
+  }
+
+  /** 获取或创建工作流对应的 HistoryStack */
+  getOrCreateStack(workflowId: string): HistoryStack {
+    let stack = this.historyStacks.get(workflowId);
+    if (!stack) {
+      const stackConfig: Partial<HistoryStackConfig> = {
+        maxEntries: DEFAULT_MAX_HISTORY,
+        onEvict: (entry) => {
+          // 淘汰条目时清理其 outputs 资产(避免 OPFS 泄漏)
+          // TD-3.2: opfs/idb asset-store 的 remove 已对 NotFoundError 静默忽略
+          // (幂等删除),因此此处 catch 到的都是真实错误(权限/IO/quota 等),
+          // 用 error 级别记录,便于 Sentry 上报与孤儿资产排查
+          for (const assetId of entry.outputs) {
+            this.deps.assetStore.remove(assetId).catch((err) => {
+              console.error(`[lokvis] onEvict: remove(${assetId}) failed:`, err);
+            });
+          }
+        },
+        onChanged: (wfId, entries, currentIndex) => {
+          this.deps.eventBus.emit({
+            type: 'history:changed',
+            workflowId: wfId,
+            entries,
+            currentIndex,
+          });
+          void this.persistHistory(wfId);
+        },
+      };
+      stack = new HistoryStack(workflowId, stackConfig);
+      this.historyStacks.set(workflowId, stack);
+    }
+    return stack;
+  }
+
+  /**
+   * 清理指定工作流的历史栈(reset 触发 onEvict 回收资产),不取消运行中执行。
+   *
+   * TD-2.1 长期方案:返回 Promise 并在末尾 `await persistHistory`,使调用方
+   * (disposeWorkflow / disposeAll)能在持久化完成后才返回,消除测试轮询。
+   * stack.reset() 触发 onChanged → fire-and-forget persistHistory(删除空记录),
+   * 此处显式 await 保证 IDB 删除已落地;两次 delete 幂等,无副作用。
+   */
+  async disposeHistory(workflowId: string): Promise<void> {
+    const stack = this.historyStacks.get(workflowId);
+    if (stack) {
+      stack.reset();
+      this.historyStacks.delete(workflowId);
+    }
+    this.initialInputsMap.delete(workflowId);
+    this.currentOutputsMap.delete(workflowId);
+    await this.persistHistory(workflowId);
+  }
+
+  /**
+   * 清理所有工作流的历史栈(W21.6 runtime.dispose 用)。
+   *
+   * 复制 keys 后逐个 await disposeHistory,触发 onEvict 回收 outputs 资产。
+   * TD-2.1:改为 async 顺序 await,确保 runtime.dispose() 返回前所有持久化
+   * 删除已落地(避免 dispose 后 IDB 仍有残留记录的竞态)。
+   */
+  async disposeAll(): Promise<void> {
+    // 复制一份:disposeHistory 内 stack.reset() → onEvict → assetStore.remove
+    // 可能间接触发其他 listener 改动 historyStacks(理论上不会,但防御性写法)
+    for (const workflowId of [...this.historyStacks.keys()]) {
+      await this.disposeHistory(workflowId);
+    }
+    this.dirtyDuringLoad.clear();
+  }
+
+  /**
+   * 把工作流当前历史快照写入 historyStore(W7.2)。
+   *
+   * 时序:currentOutputs 从 stack snapshot 派生(cursor === -1 用 initialInputs,
+   * 否则用 entries[cursor].outputs),不读 currentOutputsMap —— onChanged 在
+   * undo/redo/jumpTo/run 内部同步触发时 map 尚未更新会读到旧值。
+   * 竞态:多个 fire-and-forget save 的 IDB readwrite 事务由 IndexedDB 引擎按发起
+   * 顺序串行化,无需应用层加链。
+   * entries 为空 → delete;加载期间跳过写回,记入 dirtyDuringLoad 后续补 persist。
+   */
+  async persistHistory(workflowId: string): Promise<void> {
+    if (!this.deps.historyStore) return;
+    if (this.isLoadingHistory) {
+      this.dirtyDuringLoad.add(workflowId);
+      return;
+    }
+    // fire-and-forget 调用方用 `void this.persistHistory(...)`,故内部必须 try/catch,
+    // 否则 IDB 故障会变成 unhandled promise rejection。
+    try {
+      const stack = this.historyStacks.get(workflowId);
+      // 栈已从内存移除(disposeHistory / enforceStacksLimit 后异步到达)→ 删除持久化记录
+      if (!stack) {
+        await this.deps.historyStore.delete(workflowId);
+        return;
+      }
+      const { entries, cursor } = stack.snapshot();
+      if (entries.length === 0) {
+        await this.deps.historyStore.delete(workflowId);
+        return;
+      }
+      const initialInputs = this.initialInputsMap.get(workflowId) ?? [];
+      const currentOutputs = cursor === -1
+        ? initialInputs
+        : (entries[cursor]?.outputs ?? initialInputs);
+      await this.deps.historyStore.save({
+        workflowId,
+        entries,
+        cursor,
+        initialInputs,
+        currentOutputs,
+        updatedAt: Date.now(),
+      });
+    } catch (err) {
+      console.warn(`[lokvis] persistHistory failed for workflow ${workflowId}:`, err);
+    }
+  }
+
+  /**
+   * 从 historyStore 预加载所有持久化的历史快照(由 createRuntime 工厂调用)。
+   * 加载期间置 isLoadingHistory 守卫;被跳过的 persist 记入 dirtyDuringLoad,
+   * 加载结束后补 persist,避免加载期间其他来源变更被永久丢弃。
+   */
+  async loadPersistedHistory(): Promise<void> {
+    if (!this.deps.historyStore) return;
+    let records: Awaited<ReturnType<HistoryStore['loadAll']>> = [];
+    this.isLoadingHistory = true;
+    try {
+      records = await this.deps.historyStore.loadAll();
+      for (const record of records) {
+        if (record.entries.length === 0) continue; // 跳过空记录(双重防御)
+        const stack = this.getOrCreateStack(record.workflowId);
+        stack.restore({ entries: record.entries, cursor: record.cursor });
+        this.initialInputsMap.set(record.workflowId, record.initialInputs);
+        this.currentOutputsMap.set(record.workflowId, record.currentOutputs);
+      }
+    } finally {
+      this.isLoadingHistory = false;
+      // 补 persist:逐个 await 保证顺序;复制一份避免补 persist 过程中
+      // 新触发 onChanged → dirtyDuringLoad 死循环
+      const pending = [...this.dirtyDuringLoad];
+      this.dirtyDuringLoad.clear();
+      for (const wfId of pending) await this.persistHistory(wfId);
+    }
+  }
+}

package/src/managers/mcp-manifest-builder.ts

@@ -0,0 +1,108 @@
+/**
+ * MCP Manifest Builder(W1.5 从 runtime.ts 抽取)
+ *
+ * 把已注册 Capability 列表转换为 MCP server manifest(纯函数,无 `this`,
+ * 不依赖 CapabilityRegistry)。Runtime.toMcpManifest() 委托本模块。
+ *
+ * 暴露规则(见 docs/AI生态冲击调整方案.md §6):
+ * - private:任何模式都不暴露
+ * - batch-only:仅在 options.batchMode=true 时暴露(避免单文件误用)
+ * - 其余(默认 public):总是暴露
+ * tool 名取 capability.mcpToolName 或 `lokvis_${name.replace(/\./g, '_')}`;
+ * resource 固定为 capabilities 与 workflows 两个清单。
+ */
+
+import type {
+  Capability, CapabilityParam, CapabilityParamType,
+  McpManifest, McpToolManifest,
+} from '@lokvis/schema';
+import type { ToMcpManifestOptions } from '../types.js';
+
+const SERVER_NAME = 'lokvis';
+const CAPABILITIES_URI = 'lokvis://capabilities';
+const WORKFLOWS_URI = 'lokvis://workflows';
+
+/** 生成 MCP server manifest(不启动 server,仅描述可被 MCP 暴露的能力)。 */
+export function toMcpManifest(
+  capabilities: Capability[],
+  options: ToMcpManifestOptions = {},
+  version: string
+): McpManifest {
+  const { batchMode = false } = options;
+  const tools: McpToolManifest[] = [];
+  for (const cap of capabilities) {
+    if (cap.mcpExposure === 'private') continue;
+    if (cap.mcpExposure === 'batch-only' && !batchMode) continue;
+    const toolName = cap.mcpToolName ?? `lokvis_${cap.name.replace(/\./g, '_')}`;
+    tools.push({
+      name: toolName,
+      description: cap.description,
+      inputSchema: capabilityParamsToJsonSchema(cap.params),
+      capabilities: [cap.name],
+    });
+  }
+  return {
+    serverName: SERVER_NAME, version, tools,
+    resources: [
+      { uri: CAPABILITIES_URI, name: 'Capabilities',
+        description: 'List all available Lokvis capabilities',
+        mimeType: 'application/json' },
+      { uri: WORKFLOWS_URI, name: 'Workflows',
+        description: 'List saved workflows', mimeType: 'application/json' },
+    ],
+  };
+}
+
+/** Capability.params(CapabilityParam[])→ JSON Schema 对象(手写,非 zod-to-json-schema)。 */
+function capabilityParamsToJsonSchema(params: CapabilityParam[]): object {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const p of params) {
+    properties[p.name] = capabilityParamToJsonSchemaProperty(p);
+    if (p.required) required.push(p.name);
+  }
+  return { type: 'object', properties,
+    ...(required.length > 0 ? { required } : {}) };
+}
+
+/**
+ * CapabilityParamType → 合法 JSON Schema 类型片段。
+ * color/file/enum 非 JSON Schema 标准类型,color→string+format,
+ * file/enum→string(enum 值由外层 enum 字段追加);其余同名 JSON Schema 类型。
+ */
+function capabilityParamTypeToJsonType(
+  type: CapabilityParamType
+): { type: string; format?: string } {
+  switch (type) {
+    case 'color': return { type: 'string', format: 'color' };
+    case 'file':
+    case 'enum': return { type: 'string' };
+    case 'number':
+    case 'string':
+    case 'boolean':
+    case 'object':
+    case 'array': return { type };
+    default: return { type: 'string' };
+  }
+}
+
+/** 单个 CapabilityParam → JSON Schema property */
+function capabilityParamToJsonSchemaProperty(
+  p: CapabilityParam
+): Record<string, unknown> {
+  const { type: jsonType, format } = capabilityParamTypeToJsonType(p.type);
+  const prop: Record<string, unknown> = { type: jsonType };
+  if (format) prop.format = format;
+  if (p.description) prop.description = p.description;
+  if (p.default !== undefined) prop.default = p.default;
+  // min/max 仅对 number 合法(string 应为 minLength/maxLength)
+  if (p.type === 'number') {
+    if (typeof p.min === 'number') prop.minimum = p.min;
+    if (typeof p.max === 'number') prop.maximum = p.max;
+  }
+  if (p.type === 'enum' && p.values) prop.enum = p.values;
+  if (p.type === 'array' && p.items) {
+    prop.items = capabilityParamTypeToJsonType(p.items);
+  }
+  return prop;
+}