LokvisRuntime

Defined in: packages/runtime/src/types.ts:164

核心 Runtime API（第一版，必须克制）

Properties

version

readonly version: string

Defined in: packages/runtime/src/types.ts:166

Runtime 版本

status

readonly status: RuntimeStatus

Defined in: packages/runtime/src/types.ts:168

当前状态

eventBus

readonly eventBus: EventBus

Defined in: packages/runtime/src/types.ts:170

事件总线

isPro

readonly isPro: boolean

Defined in: packages/runtime/src/types.ts:172

是否为 Pro 模式(影响批量上限/并发槽位/workflow 数,W6.2)

plan

readonly plan: Plan

Defined in: packages/runtime/src/types.ts:177

用户订阅计划(G1)。比 isPro 更细粒度,用于 AI 调用计费判定。 isPro === (plan !== 'free'),二者保持一致。

batch

readonly batch: BatchProcessor

Defined in: packages/runtime/src/types.ts:179

批量处理器(W6.1:并发控制 + 进度 + 失败重试)

Methods

run()

run(workflow, inputs, options?): Promise<WorkflowResult>

Defined in: packages/runtime/src/types.ts:183

运行工作流

Parameters

workflow

Workflow

inputs

string[] | Asset[]

options?

RunOptions

Returns

Promise<WorkflowResult>

cancel()

cancel(workflowId): Promise<void>

Defined in: packages/runtime/src/types.ts:185

取消运行

Parameters

workflowId

string

Returns

Promise<void>

pause()

pause(workflowId): Promise<void>

Defined in: packages/runtime/src/types.ts:187

暂停运行

Parameters

workflowId

string

Returns

Promise<void>

resume()

resume(workflowId): Promise<void>

Defined in: packages/runtime/src/types.ts:189

恢复运行

Parameters

workflowId

string

Returns

Promise<void>

getCurrentOutputs()

getCurrentOutputs(workflowId): Promise<string[]>

Defined in: packages/runtime/src/types.ts:198

获取工作流当前输出 AssetId（undo/redo 后的“当前”状态）。

用途：

UI 实时展示工作流中间结果
MCP server 查询当前工作流产物
暂停时检查中间输出

Parameters

workflowId

string

Returns

Promise<string[]>

disposeWorkflow()

disposeWorkflow(workflowId): Promise<void>

Defined in: packages/runtime/src/types.ts:205

销毁工作流的运行时状态（取消运行 + 清空历史栈 + 回收历史 outputs 资产）。

修复 review 报告：原接口无清理入口，长会话累积导致 historyStacks Map 与 AssetStore 中孤儿资产泄漏。ui-react 应在 Workspace 卸载时调用。

Parameters

workflowId

string

Returns

Promise<void>

dispose()

dispose(): Promise<void>

Defined in: packages/runtime/src/types.ts:224

销毁整个 Runtime:取消所有运行中 workflow + 批处理任务, 清空所有历史栈(触发 outputs 资产回收),清理 eventBus 订阅。

W21.6: 修复长会话 / SPA 卸载场景的资源泄漏。在以下时机调用:

SPA 整体卸载(window beforeunload 或 React root unmount)
测试 afterEach 清理
消费方明确知道不再使用此 runtime 实例时

AssetStore 的清理策略:

若 Runtime 通过 createRuntime 工厂创建 store(默认路径):dispose() 会调用 assetStore.dispose?.() 关闭 Dexie 连接 / 清空内存 Map
若消费方注入 store(config.assetStore):Runtime 不清理,由消费方在合适的时机调用 store.dispose?.()

调用 dispose() 后再调 run()/cancel() 等方法会抛 ‘Runtime is disposed’。幂等:重复调用为 no-op。

Returns

Promise<void>

history()

history(workflowId): Promise<HistoryEntry[]>

Defined in: packages/runtime/src/types.ts:228

获取工作流的执行历史

Parameters

workflowId

string

Returns

Promise<HistoryEntry[]>

getHistoryState()

getHistoryState(workflowId): Promise<{ entries: HistoryEntry[]; cursor: number; }>

Defined in: packages/runtime/src/types.ts:234

获取工作流历史状态(条目 + 当前游标)。游标 -1 表示无已应用条目(初始状态);i 表示第 i 条已应用。比 history() 多返回 cursor,UI 据此高亮当前步骤。

Parameters

workflowId

string

Returns

Promise<{ entries: HistoryEntry[]; cursor: number; }>

undo()

undo(workflowId): Promise<void>

Defined in: packages/runtime/src/types.ts:238

撤销一步

Parameters

workflowId

string

Returns

Promise<void>

redo()

redo(workflowId): Promise<void>

Defined in: packages/runtime/src/types.ts:240

重做一步

Parameters

workflowId

string

Returns

Promise<void>

jumpTo()

jumpTo(workflowId, index): Promise<void>

Defined in: packages/runtime/src/types.ts:246

跳转到指定历史条目(按时间顺序的索引,-1 表示回到初始)。用于 HistoryPanel 点击条目直接跳转,等价于连续 undo/redo 到目标位置。越界或游标未变时为 no-op。

Parameters

workflowId

string

index

number

Returns

Promise<void>

importAsset()

importAsset(source): Promise<string>

Defined in: packages/runtime/src/types.ts:250

导入资产

Parameters

source

AssetSource

Returns

Promise<string>

getAsset()

getAsset(id): Promise<Asset>

Defined in: packages/runtime/src/types.ts:252

获取资产

Parameters

id

string

Returns

Promise<Asset>

exportAsset()

exportAsset(id, format?): Promise<Blob>

Defined in: packages/runtime/src/types.ts:254

导出资产为 Blob

Parameters

id

string

format?

string

Returns

Promise<Blob>

readAssetExif()

readAssetExif(id): Promise<ExifData | null>

Defined in: packages/runtime/src/types.ts:268

读取 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 包(五层架构单向依赖)。

Parameters

id

string

资产 ID(须为 image 类型)

Returns

Promise<ExifData | null>

ExifData;非 image / 无 EXIF / 解析失败 / reader 未注册返回 null

readAssetImageMetadata()

readAssetImageMetadata(id): Promise<ImageMetadata | null>

Defined in: packages/runtime/src/types.ts:286

读取 image 资产的 dimensions/format 元数据。

走 MetadataReader 机制(与 readAssetExif 同一设计):Runtime 持有 plugin-image 通过 ctx.registerMetadataReader('image.read-metadata', fn) 注册的 reader 引用,按名调用。reader 内部调 engine-image/node 的 getMetadata(sharp .metadata())。

用途:mcp-server 在 image tool 处理完成后,读取输出 Blob 的精确尺寸用于结果文本报告。Plugin 未安装时优雅降级返回 null。

架构意义:使 mcp-server 不再直接 import @lokvis/engine-image(违反五层架构单向依赖),改为通过 Runtime 间接调用(见 A1 修复)。

Parameters

id

string

资产 ID(须为 image 类型)

Returns

Promise<ImageMetadata | null>

ImageMetadata;非 image / reader 未注册 / 解析失败返回 null

readAssetPdfInfo()

readAssetPdfInfo(id): Promise<PdfInfo | null>

Defined in: packages/runtime/src/types.ts:303

读取 pdf 资产的页数。

走 MetadataReader 机制:Runtime 持有 plugin-pdf 通过 ctx.registerMetadataReader('pdf.read-info', fn) 注册的 reader 引用, 按名调用。reader 内部调 engine-pdf 的 getPdfInfo(pdf-lib getPageCount)。

用途:mcp-server 在 pdf tool 处理完成后,读取输出 Blob 的页数用于结果文本报告。Plugin 未安装时优雅降级返回 null。

架构意义:使 mcp-server 不再直接 import @lokvis/engine-pdf(违反五层架构单向依赖),改为通过 Runtime 间接调用(见 A1 修复)。

Parameters

id

string

资产 ID(须为 pdf 类型)

Returns

Promise<PdfInfo | null>

PdfInfo;非 pdf / reader 未注册 / 解析失败返回 null

removeAsset()

removeAsset(id): Promise<void>

Defined in: packages/runtime/src/types.ts:305

删除资产

Parameters

id

string

Returns

Promise<void>

listAssets()

listAssets(): Promise<Asset[]>

Defined in: packages/runtime/src/types.ts:307

列出所有资产

Returns

Promise<Asset[]>

getStorageUsage()

getStorageUsage(): Promise<{ usage: number; quota: number; }>

Defined in: packages/runtime/src/types.ts:319

查询存储配额使用情况(W6.7)。

返回 { usage, quota }:

usage:当前已用字节数(所有资产 metadata.size 之和)
quota:配置的存储配额上限(RuntimeConfig.storageQuota,默认 1GB)

UI 据此展示“已用/总额”进度条,接近上限(>=80%)时警告。注意:usage 基于 listAssets 实时计算,反映 runtime 实际占用, 与浏览器 navigator.storage.estimate()(origin 整体 OPFS)不同。

Returns

Promise<{ usage: number; quota: number; }>

capabilities()

capabilities(): Promise<Capability[]>

Defined in: packages/runtime/src/types.ts:323

列出所有已注册能力

Returns

Promise<Capability[]>

hasCapability()

hasCapability(name): Promise<boolean>

Defined in: packages/runtime/src/types.ts:325

检查能力是否可用

Parameters

name

string

Returns

Promise<boolean>

isStubOnly()

isStubOnly(name): Promise<boolean>

Defined in: packages/runtime/src/types.ts:333

检查能力是否仅有 stub 实现(无可用引擎)。

UI 层据此为 stub-only 能力显示 “Coming Soon” 标记(A7), 避免用户选择后在工作流执行阶段才收到 stub error。返回 true 表示该能力已声明但仅有占位实现,resolve() 会跳过。

Parameters

name

string

Returns

Promise<boolean>

toMcpManifest()

toMcpManifest(options?): McpManifest

Defined in: packages/runtime/src/types.ts:352

生成 MCP server manifest(不启动 server,仅描述当前可被 MCP 暴露的能力)。用于:

@lokvis/mcp-server 注册 tools 前的能力探测
Dashboard 展示“可被 AI 调用的能力”
文档站自动生成 MCP tools 列表

options.batchMode 控制是否暴露 mcpExposure='batch-only' 的能力:

默认 false(单文件模式):不暴露 batch-only 能力
true(batch 模式):暴露 batch-only 能力 mcpExposure='private' 的能力在任何模式下都不暴露。

注:本方法同步返回 —— manifest 是对 capabilityRegistry.list() (同步)的纯计算,无 I/O,故无需 async。capabilities() 仍为 async 仅为接口对称性(未来可能涉及异步加载)。

Parameters

options?

ToMcpManifestOptions

Returns

McpManifest

installPlugin()

installPlugin(plugin): Promise<void>

Defined in: packages/runtime/src/types.ts:371

在 Runtime 上安装一个插件。

步骤:

把 plugin.config.capabilities 注册到 CapabilityRegistry(声明能力)
构造受限 PluginContext(只暴露 getAsset/importAsset/getAssetBlob/ createAsset/listCapabilities + eventBus + registerCapability + registerMetadataReader + registerPanel + log)
调用 plugin.install(ctx),让插件注册 CapabilityImplementation
发射 plugin:loaded 事件

SDK 的 createLokvis({ plugins }) 与 loadPlugin() 都委托到这里, 不再需要 instanceof LokvisRuntimeImpl + _getAssetStore() 等内部 API。

Parameters

plugin

PluginInstallEntry

Returns

Promise<void>

Throws

plugin.install 抛出的任何错误(runtime 不吞错,由 SDK 包成 PluginLoadError)

listPanels()

listPanels(): PanelDefinition[]

Defined in: packages/runtime/src/types.ts:385

列出插件通过 ctx.registerPanel() 注册的全部 UI Panel。

Panel 注册时同步发射 panel:registered 事件;UI 层(ui-react) 订阅该事件并调用本方法刷新面板列表,按 PanelDefinition.location 挂载到 Workspace 对应区域。component 字段为渲染器标识,由 UI 层的 panel renderer 注册表解析(依赖反转:runtime 只持有定义, 不持有 React 组件)。

同步方法:panel 列表是纯内存状态,无 I/O。

Returns

PanelDefinition[]