Native / WASM 加速

ST-BME 对几个计算密集操作提供 Rust/WASM 加速，灰度发布，默认 fail-open（失败自动回退 JS）。本文档说明加速了什么、怎么门控、怎么回退。

实现：native/stbme-core/（Rust 源）、vendor/wasm/stbme_core.js（JS 包装）、ui/graph-native-bridge.js、sync/bme-db.js 的 native gate。

加速了什么

操作	native 钩子	阈值（达到才用 native）
图谱布局	`solve_layout`	节点 ≥ 280 或边 ≥ 1600
持久化增量构建	`build_persist_delta*`	记录 ≥ 20000 且结构增量 ≥ 600 且序列化字符 ≥ 4000000
快照 hydrate/加载	`build_hydrate_records`	记录 ≥ 30000

没有加速：embedding 和召回图扩散。embedding 走 vector/ 的 API/直连路径；扩散是纯 JS（retrieval/diffusion.js）。注意 host/st-native-render.js 不是 WASM 加速器，是 ST 原生模板/宏渲染助手。

Fail-open 回退

核心标志：

nativeEngineFailOpen: true（默认）— native 失败时回退 JS，不报错
graphNativeForceDisable: false（默认）— 全局禁用 native

回退逻辑：

图谱布局：worker 不可用时，fail-open 返回 skipped 让渲染器跑 JS 布局；strict 模式（fail-open false）才抛 native-failed-hard。
持久化增量：native 预加载/构建失败且 fail-open 时，记警告、用 JS 增量。
hydrate：同理，native 不可用且 fail-open 时用 JS hydrate。

graphNativeForceDisable 为真时，布局、hydrate、持久化增量全部跳过 native 尝试。

灰度发布

设置文件明确把这块标为"灰度"。通过 nativeRolloutVersion 做迁移：

当前 NATIVE_ROLLOUT_VERSION = 2
持久版本 < 1：迁移开启 native 布局/增量/hydrate 默认
持久版本 < 2 且 hydrate 阈值是旧值 12000：更新到 30000
然后设 nativeRolloutVersion = 2

这套迁移让老用户平滑升级到新默认，同时保留用户手动 opt-out（手动关掉的不被迁移覆盖）。

WASM 核心模块

JS 包装 vendor/wasm/stbme_core.js：

先尝试 wasm-pack 产物（./pkg/stbme_core_pkg.js + .wasm）
失败则用全局 fallback loader globalThis.__stBmeLoadRustWasmLayout
通过 getNativeModuleStatus() 暴露状态

暴露的函数：solveLayout()、installNativePersistDeltaHook()（装 __stBmeNativeBuildPersistDelta）、installNativeHydrateHook()（装 __stBmeNativeHydrateSnapshotRecords）、getNativeModuleStatus() / resetNativeModuleStatus()。

Rust 导出：solve_layout、build_persist_delta / _compact / _compact_hash、build_hydrate_records。

桥接模式 persistNativeDeltaBridgeMode（默认 json）控制增量传输格式；hash 模式走 compact hash 路径。

测试

tests/native-layout-parity.mjs — native 布局结果与 JS 布局的平均绝对差在阈值内（保证 native 和 JS 算出来一致）。
tests/native-rollout-matrix.mjs — 迁移、选项归一化、各操作的阈值门控（边界值如 279/280、29999/30000）。

面板控件

面板显示 native 状态（全局禁用 / 按阈值自动尝试，fail-open / strict），并绑定 graphNativeForceDisable、nativeEngineFailOpen、graphUseNativeLayout、persistUseNativeDelta、loadUseNativeHydrate 等开关和阈值输入。遇到异常可在面板强制关闭 native。

3.4 KiB Raw Blame History Unescape Escape