Repository navigation
Commit 3b2b443
* feat(runtime): 新增插件自管运行时的目录契约与结构检查(issue #131)
profile 是所有插件共用的依赖图。@huggingface/transformers 及其原生闭包
(onnxruntime-node 解包 210 MB / tarball 86 MB、onnxruntime-web 128 MB、
sharp 19 MB)只要留在 dependencies 里,就会让「装或更新任何插件」都得重走
一遍这条链,弱网下直接把 profile 安装卡死。本提交先定义运行时落地契约与
结构检查,作为后续 adopt / install / verify 的地基;依赖声明本提交不动。
契约(<runtimeDir>/<payloadId>/):
mneme-runtime.json 来源与版本清单
node_modules/ 扁平依赖闭包(与 hoisted 同形)
必须是扁平结构:transformers.node.mjs 内部全是裸导入(`import sharp`、
`import * as ONNX_NODE from "onnxruntime-node"`),按自身位置解析;把闭包按
扁平结构放好、对入口做绝对 file URL import,整套即可运行,无需动宿主
node_modules,也无需 overrides。
- src/runtime/layout.js:payloadId、defaultRuntimeDir、listPayloadDirs、
describePayload(只做结构检查,功能验证留给后续 verify 模块,避免枚举
sharp 平台分片包带来的脆性)、transformersVersionOk(只实现本包需要的
一条区间,不做通用 semver)
- test/runtime-layout.test.js:11 个用例(完整 / 缺件 / 版本越界 / 平台
子树缺失 / 目录不存在)
- lib/runtime/layout.js:由 npm run sync 同步
测试:全量 50/51 通过。test/peer-blockers.test.js 的「8 进程并发原子递增」
用例在本机沙箱下失败(子进程 spawn EPERM,命名管道限制),与本次改动无关,
CI 环境不受影响。
* feat(runtime): 依赖闭包遍历与平台过滤(issue #131)
adopt(从宿主 node_modules 收编)与 export(导出给别的机器)共用的地基:
给定源 node_modules 与入口包,算出「一份能跑的运行时需要哪些包、各自落到
哪个相对位置」。
- 按源布局镜像、不压平。入口内部是裸导入,靠 Node 逐级向上查找解析;压平会
悄悄改掉「同一个包的两个版本分别落在不同层」的解析结果——用例用
onnxruntime-web 自带的那份 onnxruntime-common 守住这条。
- 解析绝不越出源 node_modules:越出就记 gap,保证产出是自包含的。
- 平台过滤:os/cpu 支持正向匹配与 `!` 反向排除,不匹配的记进 skipped。
onnxruntime-node 单包内含三平台、sharp 走 @img/sharp-* 分片,这条是止血点。
- 可选依赖缺失静默跳过(平台分片包在别的平台就是这个形态);必需依赖缺失
才记 gap。
- 跳过 peerDependencies:宿主提供的服务实现不该被复制进插件自管的运行时。
- maxPackages 防呆上限,命中如实上报 truncated,不静默丢包。
- src/runtime/closure.js:planClosure / resolvePackageDir / matchesPlatform
- test/runtime-closure.test.js:9 个用例(嵌套镜像、平台过滤、peer 排除、
可选缺失、成环终止、截断上报、入口缺失、解析边界、平台匹配语义)
- lib/runtime/closure.js:由 npm run sync 同步
测试:runtime 两个测试文件 20/20 通过。
* feat(runtime): 运行时验证三件套(结构 / 功能 / 完整性)
为什么要分三层,而不是「能 import 就算通过」:
- 结构:入口在不在、版本对不对、平台子树对不对、闭包有没有缺口。便宜、确定,
能立刻发现「解压到一半」。
- 功能:真的 import 入口并跑一次推理。这是唯一能证明「这份运行时在这个环境里
真的算得出来」的一层——结构全对但原生二进制与本机 ABI 不匹配时只有它能发现。
- 完整性:只对「有原始产物可比对」的来源做(下载的 tarball、本地 tarball);
收编来的目录没有原始产物,如实标 unverified,不假装验过。
- src/runtime/verify.js:verifyFunctional(断言行数一致、维度一致、L2 归一、
非退化;一切失败返回结果对象而不抛异常——验证本身必须 fail-safe,否则一条
坏运行时会把面板和状态接口一起带崩)、verifyPayload(结构不过就跳过功能
验证,省掉一次无谓的加载;integrity 由调用方传入)、defaultEngine(强制
env.allowRemoteModels = false:验证过程绝不能偷偷下载模型,否则「验证」
本身就成了新的网络依赖点)
- test/runtime-verify.test.js:10 个用例,重点覆盖「坏的那几种能被抓住」——
行数不符、非归一化向量、向量退化、加载失败、推理失败、空向量、结构不过时
跳过功能验证、unverified 不判失败、哈希不匹配时整体不通过
- lib/runtime/verify.js:由 npm run sync 同步
测试:runtime 四个测试文件 37 通过。
* feat(runtime): 收编宿主已有的运行时(硬链接 + 回退复制)
老用户 profile 里已经装好、而且能跑的那套闭包,先收进插件自管目录;后续
profile prune 掉依赖时才不会让本地嵌入断掉——这是「分两步发版」第一步的全部意义。
- src/runtime/adopt.js:
· materializePackage —— 跳过嵌套 node_modules(那些包在闭包计划里是独立条目,
各自落到自己的相对位置,不跳就重复搬一遍);跳过符号链接并记 warnings
(不跟随 pnpm isolated 布局指向虚拟 store 的链接,避免把宿主 store 拖进来、
也让目录层级失真);同卷走 linkSync,失败则逐个文件回退 copyFileSync。
· adoptRuntime —— 闭包计划 → 物化 → 写 mneme-runtime.json;目标已存在且未
overwrite 时拒绝;入口包未解析时返回可读原因,不抛异常。
- 回退原因如实记进清单 materialize.{mode, linkError},并整体只记一条 warning:
「收编本该不占盘却占了盘」时用户和面板要能看到原因;静默回退会让预期落空却
无从查起。link 做成可注入,本机不可复现的环境差异(跨卷 EXDEV / 权限 EPERM)
因此可测。
- test/runtime-adopt.test.js:8 个用例,含注入 EPERM 覆盖回退分支,并断言整次
收编只记一条回退原因(这条断言当场抓到了「按包去重」的真 bug)。
实测(本机真实 profile 树,源目录全程只读):闭包 49 包 / 375.0 MB;收编
3183 个文件;收编产物跑真推理通过(维度 512,约 370ms,离线)。
环境说明:本机沙箱拒绝把 workspace 之外的文件硬链接进来(EPERM),因此实测走
的是回退复制;真实插件进程无此限制,同卷(~/.dsh/mneme/runtime 与 profile 同在
C:)会走硬链接。硬链接路径由单元测试覆盖(同根目录下 linked > 0)。
* feat(runtime): 三层运行时解析加载器
self-managed runtime 缺的最后一块:插件怎么找到并加载那份运行时。
三层,缺一层都不行:
- ① `~/.dsh/mneme/runtime/<payloadId>/`(收编来的或下载来的)——import 绝对
file URL 而不是改 node_modules:入口内部全是裸导入(`import sharp from "sharp"`、
`import * as ONNX_NODE from "onnxruntime-node"`),按自身位置解析,把扁平闭包放好
再用绝对 URL import 入口,整套就自洽了。
- ② 宿主裸 specifier —— PR-A 期间依赖声明不动,老用户宿主那份还在,这层保证他们
在完成收编前照常可用;等 PR-B 真的摘掉依赖、pnpm prune 掉宿主那份之后,第 ① 层顶上。
- ③ 两层都没有 —— 抛 MNEME_RUNTIME_UNAVAILABLE,带可执行的下一步(面板安装 /
runtime adopt)与「每层各自为什么失败」,由调用方降级为关键词/BM25 检索。
两条不放过的细节:
- 降级不许静默:第 ① 层「找到了却加载不起来」与「本机根本没有」是两件事,前者
必须经 onFailure 回吐给面板/日志,不能因为退到第 ② 层成功就当无事发生。
- 第 ③ 层的错误要能直接展示:把两层失败原因都列出来,而不是一句 module not found。
- src/runtime/loader.js:resolveRuntimeEntry / loadTransformers
(importModule 可注入,测试不需要真的加载原生模块)
- test/runtime-loader.test.js:6 个用例(自管优先、退回宿主、坏 payload 可见、
两层都失败的错误内容与 error.code、多 payload 取可用者、根目录不存在返回 null)
- lib/runtime/loader.js:由 npm run sync 同步
测试:runtime 五个测试文件 43 通过。
* feat(runtime): 本地嵌入/重排改经三层解析加载运行时(issue #131)
接线:embedder 与 reranker 不再各自 `await import("@huggingface/transformers")`,
统一走 src/runtime/loader.js —— ① 自管 payload 优先,② 宿主裸 specifier 兜底。
- src/config.js:新增 runtimeDir(默认空字符串 = ~/.dsh/mneme/runtime)
- src/index.js:把 cfg.runtimeDir 传给 createEmbedderByProvider 与 LocalReranker
- src/local-embedder.js:defaultPipelineLoader 经 loadTransformers 取 module;
LocalEmbedder 新增 this.runtimeDir,随 engine factory 的 options 传递
(runtimeDir 取走后不混进 transformers 的 pipeline 选项)
- src/reranker.js:同样处理;_engineOptions() 带上 runtimeDir
- 惰性加载语义不变:动态 import 只出现在 loader 内部,index.js 仍按需触发
(rerank 的 opt-in 门、openai 分支不加载 ONNX 都保持原样)
test/config.test.js 的启动探针(防止静态导入把 onnxruntime 拉进模块加载)随之
更新判据 —— 不是放宽:原来断言 reranker.js 里存在
`await import("@huggingface/transformers")`;现在改成断言 reranker 经
runtime/loader.js 取运行时、且 loader 里才是唯一的动态 import 落点,并保留
「任何形式的静态导入都不允许」。
测试:config 4/4、local-embedder 14/14、reranker 14/14、lib-smoke 5/5、semantic 7/7。
* feat(runtime): 运行时状态探针与收编/验证入口(issue #131)
- loader 新增 describeLocalRuntime:只读结构探针,functional 如实为 unknown
(GET 端点不该加载原生模块跑推理);available 分支复用 resolveRuntimeEntry,
保证「状态报的那份」就是「真正加载的那份」。
- 空/空白 runtimeDir 统一按默认目录处理:配置项默认值是空串,原样传下去会变成
相对路径,把「没配」误报成「坏了」。
- /api/dsh-mneme/semantic 增加 localRuntime 字段(面板与 CLI 同源)。
- 新增 scripts/mneme-runtime.mjs:status / adopt / verify,退出码 0 健康 / 1 不健康
/ 2 用法错误。不放 bin/cli.mjs —— 那个 CLI 是需服务在跑的外部 API 客户端,
而收编恰恰发生在服务没起来、插件装不上的时候。
- defaultModelCacheDir 收敛到 layout.js:embedder / reranker / verify 共用同一份,
避免漂移后「拿另一份模型去验证」而得到假证据。
- 修正上一提交里指向不存在子命令的错误提示,并加测试守住该提示路径真实存在。
本机测试 791 passed / 1 failed;唯一失败 test/peer-blockers.test.js 属环境限制
(Node 子进程 piped stdio 在本沙箱 spawn EPERM),改动前即如此,与本次无关。
* docs: 补自管运行时的收编/校验说明(issue #131)
- LOCAL_MODEL.md 新增 §2.5:status / adopt / verify 三个命令、退出码语义、
「先收编再升级」的原因(profile 是全部插件共用的依赖图)。
- 修正 :16 的依赖描述:解析是三层的,且当前仍声明在 dependencies,
摘掉声明需先把运行时收编到位,否则升级后本地嵌入不可用。
- 修正缓存布局描述:实测 transformers.js 4.2.0 离线加载按 <cacheDir>/<org>/<model>/
解析(本机验证时的报错路径即为此),与原文的 hub/models-- 布局不一致。
- README 语义增强一节补该能力与三条命令。
* test(runtime): entryUrl 断言改用 fileURLToPath 精确比较(修 Windows CI 误报)
原断言拿 file URL 字符串去 includes 一个 OS 路径字符串,会被 pathToFileURL 的
百分号编码打败(含空格等字符的路径上必误报)—— CI 的 windows-latest 上就挂了,
本机路径恰好没有这类字符所以一直没暴露。
改为断言「URL 反解回来就是那个入口文件」,并把两个值带进失败信息,
以后这类不一致能直接读出是谁错了。本机 10/10。
* fix(runtime): 按评审修收编覆盖/截断、架构校验、向量假通过与端点信息泄漏
- adopt:overwrite 前先清空目标目录。不清的话 linkSync 对已存在目标抛 EEXIST,
每个文件都掉进复制分支 —— 物化方式假报成 copy、警告错说「硬链接不可用」、
整份闭包真实占盘,且上次收编的残留文件永远清不掉。真实数据复验:49 包 /
3203 文件 / 393206416 字节,覆盖后仍为 hardlink。
- adopt:物化前拒绝 plan.truncated。结构检查只看必需包/版本/入口,截断的 payload
会被判为可用、被 loader 选中,直到 import 原生模块才失败;错误现场离原因太远。
- layout:describePayload 的 arch 参数此前文档里写了却没用(loader 也只传 platform),
于是 linux-arm64 的 payload 在 linux-x64 上能通过结构检查。现在点名到
bin/napi-v6/<平台>/<架构>(真实包结构即如此),并让 loader 把 arch 透传下去。
- verify:先逐行确认「是数组」且「全为有限数」。non-finite 会让 abs(NaN - 1) > tol
这类比较恒为 false —— 坏运行时会被判成「验证通过」,这是最危险的假通过;
非数组行还会直接抛,违背「任何失败都返回结果对象,不抛」的契约。
- api/loader:新增 publicRuntimeStatus 投影。/semantic 是免鉴权端点,而完整状态里有
runtimeDir 绝对路径、hint 内嵌的脚本路径、以及 reason/reasons 里的原始文件路径,
属于信息泄漏(CWE-200)。用精确白名单投影,完整诊断留给本机 CLI。
- reranker:补上 cache_dir → env.cacheDir 的镜像。embedder 侧早就有了(issue #13),
reranker 侧一直漏着 —— 已缓存 + 离线时重排初始化会失败。
本机 801 passed / 1 failed(唯一失败为环境限制:test/peer-blockers.test.js 的
Node 子进程管道 stdio 在本沙箱 spawn EPERM,改动前即如此)。
* fix(cli): 参数解析严格化,并把 CLI 纳入测试覆盖
- 带值选项缺值时必须是用法错误(exit 2)。宽松处理会让 --runtime/--from/--cache-dir
变成 true,再被当成一个叫 "true" 的路径用下去,最后以 exit 1 收场 ——
真正的「少打一个值」被伪装成「运行时坏了」。未知选项同样立刻报错。
- 新增 test/runtime-cli.test.js:动态 import 本脚本(脚本侧加 invokedDirectly 守卫,
import 不会顺带跑 CLI)。这条覆盖是被迫补的 —— 之前本文件不在任何测试覆盖里,
我在 USAGE 模板字面量里写了一个反引号把它整个截断,CI 依然全绿,脚本直接坏掉。
现在语法错会让测试当场炸。
本机:runtime-cli 4/4;三个缺值场景 + 未知选项 + 未知命令 + 无命令均实测 exit 2,
正常路径 exit 0。
* fix(cli): adopt 失败时报干净原因,并把闭包缺口纳入退出码(评审阻塞项)
- runAdopt 在 adoptRuntime 返回 ok:false 时直接打印 reason 并 exit 1。此前它无条件
用 result.payloadDir,而「入口包解析不到」这条路径上该字段不存在,于是用户看到的是
TypeError: The "path" argument must be of type string. Received undefined 的堆栈
—— 而这是文档里给用户的第一条迁移命令,也是最容易踩的两种输入(profile 没装、
--from 指错目录)。
- adopt 退出码改为 structural.ok && plan.gaps.length === 0。describePayload 只点
REQUIRED_PACKAGES 那三个包,不看闭包计划的必需依赖缺口,所以「闭包缺件、入口一
import 就炸」的收编此前报 exit 0 —— 脚本化 gate 会在最需要它的时候误报健康。
- 新增 3 条 CLI 用例:源无入口包(不抛、报原因、exit 1)、缺必需传递依赖
(结构检查通过但 exit 1)、闭包完整仍 exit 0(防止上面那条修复过度触发)。
本机 804 passed / 1 failed;唯一失败仍是 test/peer-blockers.test.js 的 spawn EPERM
(本环境禁止 Node 子进程管道 stdio,CI 上通过)。真实命令行复现:--from 指向没有
transformers 的目录现在输出「收编失败:入口包不存在」exit 1;真实源仍 49 包 / 3203
文件 / exit 0。
---------
Co-authored-by: Modusensus <[email protected]>
1 parent 7bbfe40 commit 3b2b443
30 files changed
Lines changed: 3424 additions & 38 deletions
File tree
- dsh-mneme
- docs
- lib
- runtime
- scripts
- src
- runtime
- test
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
153 | 153 | | |
154 | 154 | | |
155 | 155 | | |
| 156 | + | |
156 | 157 | | |
157 | 158 | | |
158 | 159 | | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
159 | 168 | | |
160 | 169 | | |
161 | 170 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
13 | 13 | | |
14 | 14 | | |
15 | 15 | | |
16 | | - | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
17 | 21 | | |
18 | 22 | | |
19 | 23 | | |
| |||
31 | 35 | | |
32 | 36 | | |
33 | 37 | | |
| 38 | + | |
| 39 | + | |
34 | 40 | | |
35 | 41 | | |
36 | 42 | | |
| |||
61 | 67 | | |
62 | 68 | | |
63 | 69 | | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
64 | 96 | | |
65 | 97 | | |
66 | 98 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
6 | 6 | | |
7 | 7 | | |
8 | 8 | | |
| 9 | + | |
9 | 10 | | |
10 | 11 | | |
11 | 12 | | |
| |||
616 | 617 | | |
617 | 618 | | |
618 | 619 | | |
619 | | - | |
| 620 | + | |
| 621 | + | |
| 622 | + | |
| 623 | + | |
| 624 | + | |
| 625 | + | |
| 626 | + | |
620 | 627 | | |
621 | 628 | | |
622 | 629 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
138 | 138 | | |
139 | 139 | | |
140 | 140 | | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
141 | 147 | | |
142 | 148 | | |
143 | 149 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
225 | 225 | | |
226 | 226 | | |
227 | 227 | | |
| 228 | + | |
228 | 229 | | |
229 | 230 | | |
230 | 231 | | |
| |||
276 | 277 | | |
277 | 278 | | |
278 | 279 | | |
| 280 | + | |
279 | 281 | | |
280 | 282 | | |
281 | 283 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
3 | 3 | | |
4 | 4 | | |
5 | 5 | | |
6 | | - | |
7 | | - | |
| 6 | + | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| |||
20 | 20 | | |
21 | 21 | | |
22 | 22 | | |
23 | | - | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
24 | 32 | | |
25 | | - | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
26 | 38 | | |
27 | 39 | | |
28 | 40 | | |
29 | 41 | | |
30 | 42 | | |
31 | | - | |
32 | | - | |
| 43 | + | |
| 44 | + | |
33 | 45 | | |
34 | 46 | | |
35 | 47 | | |
| |||
56 | 68 | | |
57 | 69 | | |
58 | 70 | | |
59 | | - | |
60 | | - | |
61 | | - | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
62 | 74 | | |
63 | 75 | | |
64 | 76 | | |
| |||
77 | 89 | | |
78 | 90 | | |
79 | 91 | | |
| 92 | + | |
| 93 | + | |
80 | 94 | | |
81 | 95 | | |
82 | 96 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | | - | |
2 | | - | |
| 1 | + | |
| 2 | + | |
3 | 3 | | |
4 | 4 | | |
5 | 5 | | |
| |||
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
22 | | - | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
23 | 29 | | |
24 | | - | |
25 | | - | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
26 | 40 | | |
27 | 41 | | |
28 | 42 | | |
| |||
68 | 82 | | |
69 | 83 | | |
70 | 84 | | |
71 | | - | |
72 | | - | |
73 | | - | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
74 | 88 | | |
75 | 89 | | |
76 | 90 | | |
| |||
107 | 121 | | |
108 | 122 | | |
109 | 123 | | |
| 124 | + | |
110 | 125 | | |
111 | 126 | | |
112 | 127 | | |
| |||
0 commit comments