@modusensus/dsh-mneme 0.7.31 → 0.8.0

package/src/runtime/layout.js

@@ -0,0 +1,235 @@
+// 运行时目录契约（issue #131 / PR-A）
+//
+// 背景：@huggingface/transformers 及其原生闭包（onnxruntime-node 解包 210 MB、
+// onnxruntime-web 128 MB、sharp 19 MB）只要留在插件的 dependencies 里，就会进
+// 宿主 profile 的安装图。profile 是所有插件共用的依赖图，于是「装任何插件都要替
+// 它重走一遍这条链」，弱网下直接把安装卡死。本模块定义插件自管运行时的落地契约，
+// 让这份运行时与宿主依赖图解耦。
+//
+// 只有三件事是稳定契约，其余实现都可以换：
+//
+//   <runtimeDir>/<payloadId>/mneme-runtime.json   来源与版本清单
+//   <runtimeDir>/<payloadId>/node_modules/        扁平依赖闭包（与 hoisted 同形）
+//   <runtimeDir>/<payloadId>/node_modules/@huggingface/transformers/dist/transformers.node.mjs
+//
+// 为什么必须是「扁平 node_modules」：transformers.node.mjs 内部全是裸导入
+// （`import sharp from "sharp"`、`import * as ONNX_NODE from "onnxruntime-node"`），
+// 它们相对该文件自身位置解析。所以只要把闭包按扁平结构放好，再用绝对 file URL
+// import 入口，整套就能跑起来——不需要动宿主的 node_modules，也不需要 overrides。
+//
+// @module dsh-mneme/runtime/layout
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** 运行时清单文件名，与 payload 目录同级。 */
+export const RUNTIME_MANIFEST = "mneme-runtime.json";
+/** 唯一会被本插件 import 的入口：transformers 的 Node 构建。 */
+export const TRANSFORMERS_ENTRY =
+  "node_modules/@huggingface/transformers/dist/transformers.node.mjs";
+/**
+ * 结构检查要求的包。三个都是硬要求：
+ * - @huggingface/transformers 是入口本身；
+ * - onnxruntime-node 被 Node 构建顶层 import；
+ * - sharp 也被 Node 构建顶层 `import sharp from "sharp"`，缺了入口 import 就抛。
+ */
+export const REQUIRED_PACKAGES = ["@huggingface/transformers", "onnxruntime-node", "sharp"];
+/** 认可的 transformers 版本区间：peer 提案的 >=4.2.0 <5（见 issue #131）。 */
+export const TRANSFORMERS_MIN = [4, 2, 0];
+export const TRANSFORMERS_MAX_MAJOR = 5;
+
+/**
+ * 解析 major.minor.patch。解析不出来返回 null —— 这里刻意不抛错，
+ * 让调用方把「版本读不懂」当成一条可报告的失败，而不是异常。
+ * @param {unknown} value - 版本字符串。
+ * @returns {number[]|null} [major, minor, patch] 或 null。
+ */
+function parseVersion(value) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(value ?? ""));
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/** 三元版本比较：a < b 返回负数。 */
+function compareVersion(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+/**
+ * 版本是否落在认可区间内。
+ *
+ * 刻意只实现「>=TRANSFORMERS_MIN <TRANSFORMERS_MAX_MAJOR」这一条区间，
+ * 不是通用 semver —— 运行时要认的只有 transformers 一个包，写通用实现
+ * 反而引入没被使用、也没被测试的分支。
+ * @param {unknown} version - 待检查版本。
+ * @returns {boolean} 是否认可。
+ */
+export function transformersVersionOk(version) {
+  const v = parseVersion(version);
+  if (v === null) return false;
+  if (v[0] >= TRANSFORMERS_MAX_MAJOR) return false;
+  return compareVersion(v, TRANSFORMERS_MIN) >= 0;
+}
+
+/**
+ * 运行时根目录的默认位置。与 embedModelCacheDir 的既有约定保持一致
+ * （都挂在 ~/.dsh/mneme/ 下，便于用户整个删掉重来）。
+ * @param {string} [home] - 家目录，测试时可注入。
+ * @returns {string} 运行时根目录。
+ */
+export function defaultRuntimeDir(home = homedir()) {
+  return join(home, ".dsh", "mneme", "runtime");
+}
+
+/**
+ * 本机 libc —— 且只在**能正面确认**时给出答案，否则 null。
+ *
+ * 用来在下载闭包时剔掉另一套 libc 的变体（linux-x64 上 `@img/sharp-linuxmusl-x64` 与
+ * `sharp-libvips-linuxmusl-x64` 加起来十几 MB，glibc 机器一辈子用不到；评审建议做，
+ * 收益真实）。
+ *
+ * 为什么只认「正面确认的 glibc」：Node 的 report 里 glibcVersionRuntime 为空时无法区分
+ * 「musl」与「这份 Node 没报」，而猜错的方向（把 glibc 变体滤掉、装上 musl 变体）会得到
+ * 一份必然 import 不起来的运行时，且本仓库没有 Linux 机器能验证这条路径。所以拿不到证据
+ * 就不过滤：Alpine 用户多下十几兆，但没人会因此装坏。
+ * @param {string} [platform] - 目标平台；只在「就是本机且是 linux」时才可能给出答案。
+ * @returns {"glibc"|null} 确认到的 libc。
+ */
+export function detectLibc(platform = process.platform) {
+  // 目标平台不是本机（比如在 win32 上为 linux 生成/统计）时，本机 report 毫无意义。
+  if (platform !== "linux" || platform !== process.platform) return null;
+  try {
+    const glibc = process.report?.getReport?.()?.header?.glibcVersionRuntime;
+    return typeof glibc === "string" && glibc !== "" ? "glibc" : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 本地模型的默认缓存目录。
+ *
+ * 收在这里是因为它必须**唯一**：embedder、reranker、verify 三方若各写一份字面量，
+ * 一旦漂移，verify 就会拿另一份模型去验证，验证结果不再是运行时的真实证据。
+ * @param {string} [home] - 家目录，测试时可注入。
+ * @returns {string} 模型缓存目录。
+ */
+export function defaultModelCacheDir(home = homedir()) {
+  return join(home, ".dsh", "mneme", "models");
+}
+
+/**
+ * 一个 payload 的目录名。带平台与架构，因此多份可以共存，
+ * 加载器按平台挑一份可用的即可。
+ * @param {{version: string, platform?: string, arch?: string}} opts - 版本与平台。
+ * @returns {string} 形如 transformers-4.2.0-node-win32-x64。
+ */
+export function payloadId({ version, platform = process.platform, arch = process.arch }) {
+  return `transformers-${version}-node-${platform}-${arch}`;
+}
+
+/** payload 目录。@param {string} runtimeDir @param {string} id @returns {string} */
+export function payloadDir(runtimeDir, id) {
+  return join(runtimeDir, id);
+}
+
+/** payload 内的扁平依赖目录。@param {string} dir @returns {string} */
+export function nodeModulesDir(dir) {
+  return join(dir, "node_modules");
+}
+
+/** 清单文件路径。@param {string} dir @returns {string} */
+export function runtimeManifestPath(dir) {
+  return join(dir, RUNTIME_MANIFEST);
+}
+
+/**
+ * 读取 JSON，读不到或解析失败都返回 undefined（结构检查不应因缺文件而抛错）。
+ * @param {string} file - 文件路径。
+ * @returns {any|undefined} 解析结果。
+ */
+export function readJsonSafe(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 列出运行时根目录下所有 payload 目录（名称排序）。目录不存在返回空数组。
+ * 加载器用它挑候选，再逐个 describePayload 判断可用性。
+ * @param {string} runtimeDir - 运行时根目录。
+ * @returns {string[]} payload 目录名。
+ */
+export function listPayloadDirs(runtimeDir) {
+  try {
+    return readdirSync(runtimeDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 结构检查：这份 payload 是否至少「该有的文件都在」。
+ *
+ * 它故意不做功能验证（真 import 并跑一次推理）——那一步要看运行环境，
+ * 由 verify 模块负责。这里只回答「解压完整没有、版本对不对、平台对不对」，
+ * 用来在下载/搬运之后立刻发现缺件。
+ * @param {string} dir - payload 目录。
+ * @param {{platform?: string, arch?: string}} [opts] - 目标平台。
+ * @returns {{dir: string, ok: boolean, version: string|null, manifest: any, missing: string[], reasons: string[]}}
+ */
+export function describePayload(dir, { platform = process.platform, arch = process.arch } = {}) {
+  const report = {
+    dir,
+    ok: false,
+    version: null,
+    manifest: readJsonSafe(runtimeManifestPath(dir)),
+    missing: [],
+    reasons: []
+  };
+
+  const nm = nodeModulesDir(dir);
+  if (!existsSync(nm)) {
+    report.reasons.push(`node_modules 不存在：${nm}`);
+    return report;
+  }
+
+  // 1) 必需包逐个点名 —— 缺哪个报哪个，用户能照着单子手工补。
+  for (const name of REQUIRED_PACKAGES) {
+    if (!existsSync(join(nm, name, "package.json"))) report.missing.push(name);
+  }
+
+  // 2) 版本必须落在认可区间（装了别的 major 的闭包，行为不可预期）。
+  const transformers = readJsonSafe(join(nm, "@huggingface/transformers", "package.json"));
+  report.version = transformers?.version ?? null;
+  if (transformers !== undefined && !transformersVersionOk(transformers.version)) {
+    report.reasons.push(
+      `@huggingface/transformers@${transformers.version} 不在认可区间（>=${TRANSFORMERS_MIN.join(".")} <${TRANSFORMERS_MAX_MAJOR}）`
+    );
+  }
+
+  // 3) 入口文件本身（前面只确认了包目录在）。
+  if (!existsSync(join(dir, TRANSFORMERS_ENTRY))) report.missing.push(TRANSFORMERS_ENTRY);
+
+  // 4) onnxruntime-node 一个包内含多平台 × 多架构的二进制，裁剪或跨机搬运时最容易只留下
+  //    别的平台/架构。必须点名到**平台 + 架构**：真实包结构是
+  //    bin/napi-v6/{darwin,linux,win32}/{arm64,x64}，只查平台的话 linux-arm64 的 payload
+  //    在 linux-x64 上也会通过结构检查，被 loader 选中后才在 import 原生模块时失败。
+  const nativeDir = join(nm, "onnxruntime-node", "bin", "napi-v6", platform, arch);
+  if (existsSync(join(nm, "onnxruntime-node")) && !existsSync(nativeDir)) {
+    report.reasons.push(
+      `onnxruntime-node 缺少 ${platform}/${arch} 的二进制子树（bin/napi-v6/${platform}/${arch}）`
+    );
+  }
+
+  report.ok = report.missing.length === 0 && report.reasons.length === 0;
+  return report;
+}

package/src/runtime/loader.js

@@ -0,0 +1,249 @@
+// 运行时加载器：三层解析（issue #131 / PR-A）
+//
+//   ① 插件自管目录 ~/.dsh/mneme/runtime/<payloadId>/ —— 收编来的或下载来的
+//   ② 宿主裸 specifier —— 用户自己装的、或别的插件带进来的
+//   ③ 都没有 —— 抛出带可操作提示的错误，由调用方降级
+//
+// 为什么第 ② 层不能省：PR-A 只是「先建基础设施」，依赖声明不动，所以老用户
+// 升级后宿主那份还在。第 ② 层保证他们在收编完成前照常可用；等 PR-B 真的把依赖
+// 摘掉、pnpm 把宿主那份 prune 掉之后，第 ① 层顶上，本地嵌入不断。
+//
+// 为什么第 ① 层要 import 绝对 file URL 而不是改 node_modules：入口内部全是裸导入
+// （`import sharp from "sharp"`、`import * as ONNX_NODE from "onnxruntime-node"`），
+// 按自身位置解析。把闭包按扁平结构放在 payload 里、用绝对 URL import 入口，
+// 整套就自洽了——不需要动宿主的 node_modules，也不需要 overrides。
+//
+// 失败必须可见：第 ① 层如果「找到了但加载不起来」，不能静默滑到第 ② 层就完事，
+// 那条错误要带出来——它是「这份 payload 坏了」和「本机根本没有」的区别。
+//
+// @module dsh-mneme/runtime/loader
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { join } from "node:path";
+import {
+  TRANSFORMERS_ENTRY,
+  TRANSFORMERS_MAX_MAJOR,
+  TRANSFORMERS_MIN,
+  defaultRuntimeDir,
+  describePayload,
+  listPayloadDirs,
+  payloadDir,
+  transformersVersionOk
+} from "./layout.js";
+
+/** 默认 import 实现；测试用来注入，避免真的加载原生模块。 */
+const defaultImport = (specifier) => import(specifier);
+
+/**
+ * 给用户看的可操作提示。用插件自身的相对位置推出绝对路径 —— src/ 与 lib/ 都在
+ * 包根下一层，所以 `../../scripts` 在两处都解析到同一个文件，提示不会因为跑源码
+ * 还是跑构建产物而指错。
+ */
+const RUNTIME_HINT =
+  "本地推理运行时不可用。查看状态：" +
+  `node "${fileURLToPath(new URL("../../scripts/mneme-runtime.mjs", import.meta.url))}" status` +
+  "；宿主里已有这份依赖时用 `adopt --from <宿主 node_modules 目录>` 收编，" +
+  "本机哪里都没有时可在任意空目录 `npm i @huggingface/transformers@^4.2.0` 再收编那个 node_modules，" +
+  "最后用 `verify` 验证。" +
+  "检索会自动降级为关键词/BM25，不影响记忆读写。";
+
+/**
+ * 空/空白 runtimeDir 视为「用默认目录」。配置项 runtimeDir 的默认值就是空串，
+ * 原样传下去会变成相对路径（`readdirSync("")` 直接失败），把「没配」误报成「坏了」。
+ * 收在这一处，省得每个调用方各写一遍 `|| defaultRuntimeDir()`。
+ */
+function effectiveRuntimeDir(runtimeDir) {
+  const value = String(runtimeDir ?? "").trim();
+  return value === "" ? defaultRuntimeDir() : value;
+}
+
+/**
+ * 在运行时根目录里挑一份可用的 payload。
+ *
+ * 多份并存时取目录名倒序的第一个通过结构检查的（同平台通常只会有一份；
+ * 需要严格挑版本时由调用方先自己筛 runtimeDir）。
+ * @param {object} [opts] - 选项。
+ * @returns {{dir: string, payloadId: string, entryUrl: string, version: string|null, manifest: any}|null}
+ *   没有可用 payload 时返回 null（不是错误——第 ② 层还有机会）。
+ */
+export function resolveRuntimeEntry({
+  runtimeDir = defaultRuntimeDir(),
+  platform = process.platform,
+  arch = process.arch
+} = {}) {
+  const dir = effectiveRuntimeDir(runtimeDir);
+  for (const id of listPayloadDirs(dir).reverse()) {
+    const payload = payloadDir(dir, id);
+    const report = describePayload(payload, { platform, arch });
+    if (!report.ok) continue;
+    return {
+      dir: payload,
+      payloadId: id,
+      entryUrl: pathToFileURL(join(payload, TRANSFORMERS_ENTRY)).href,
+      version: report.version,
+      manifest: report.manifest
+    };
+  }
+  return null;
+}
+
+/**
+ * 只读地报告自管运行时的当前状态，供状态接口 / 面板 / CLI 展示。
+ *
+ * 刻意只做结构检查，不做功能验证：这是被 GET 端点按次调用的探针，而真跑一次
+ * 推理要加载原生模块、还会碰模型缓存。所以 `functional` 如实返回 "unknown"，
+ * 并给出去哪验证的提示 —— 宁可说「没验过」，也不假装验过。
+ *
+ * 挑选口径直接复用 resolveRuntimeEntry，避免出现「状态接口报的那份」和
+ * 「真正加载的那份」不是同一个。
+ * @param {{runtimeDir?: string, platform?: string}} [opts] - 选项。
+ * @returns {{status: string, runtimeDir: string, hint: string}} 状态；任何异常都降级成状态对象，不抛。
+ */
+export function describeLocalRuntime({
+  runtimeDir = defaultRuntimeDir(),
+  platform = process.platform,
+  arch = process.arch
+} = {}) {
+  let candidate = null;
+  const dir = effectiveRuntimeDir(runtimeDir);
+  try {
+    candidate = resolveRuntimeEntry({ runtimeDir: dir, platform, arch });
+  } catch (error) {
+    // 配置里的 runtimeDir 是用户输入（可能是离奇的字符串让 pathToFileURL 抛错），
+    // 这里是唯一的边界，收在这里比每个调用方各包一层稳。
+    return {
+      status: "unreadable",
+      runtimeDir: dir,
+      reason: String(error?.message ?? error),
+      functional: "unknown",
+      hint: RUNTIME_HINT
+    };
+  }
+
+  if (candidate !== null) {
+    return {
+      status: "available",
+      runtimeDir: dir,
+      payloadId: candidate.payloadId,
+      version: candidate.version,
+      procedure: candidate.manifest?.procedure ?? null,
+      materialize: candidate.manifest?.materialize?.mode ?? null,
+      // 历史 payload（收编来的）清单里没有 integrity 字段，如实报 unverified；
+      // 下载通道会把校验结果写进清单，这里不改代码就能读到。
+      integrity: candidate.manifest?.integrity ?? "unverified",
+      functional: "unknown",
+      hint: RUNTIME_HINT
+    };
+  }
+
+  const ids = listPayloadDirs(dir);
+  if (ids.length === 0) {
+    return { status: "missing", runtimeDir: dir, functional: "unknown", hint: RUNTIME_HINT };
+  }
+  // 有目录但一份都没通过结构检查：把最新那份的缺件和原因带出来，别只说「坏了」。
+  const id = ids[ids.length - 1];
+  const report = describePayload(payloadDir(dir, id), { platform, arch });
+  return {
+    status: "broken",
+    runtimeDir: dir,
+    payloadId: id,
+    version: report.version,
+    missing: report.missing,
+    reasons: report.reasons,
+    functional: "unknown",
+    hint: RUNTIME_HINT
+  };
+}
+
+/**
+ * 把 describeLocalRuntime 的结果投影成「允许出现在免鉴权 HTTP 端点里」的形状。
+ *
+ * 为什么必须投影：`/api/dsh-mneme/semantic` 是刻意不鉴权的只读端点（与 list/search 同列），
+ * 而完整状态里有**绝对路径**（`runtimeDir`、`hint` 里嵌的脚本路径）和**原始错误文本**
+ * （`reason`/`reasons` 会带上完整文件路径，例如「node_modules 不存在：C:\...」）。
+ * 把它们发给任何能连上该端口的人，属于信息泄漏（CWE-200）。
+ *
+ * 完整诊断留给本机的 CLI（`status`）——那里本来就有文件系统权限，也才是真正需要这些细节的场景。
+ * 面板侧不需要这些：它只需要 status，其余文案用本地 i18n。
+ * @param {object} report - describeLocalRuntime 的返回值。
+ * @returns {{status: string, payloadId: string|null, version: string|null, procedure: string|null, materialize: string|null, integrity: string|null, functional: string|null}}
+ */
+export function publicRuntimeStatus(report) {
+  return {
+    status: report?.status ?? "unknown",
+    payloadId: report?.payloadId ?? null,
+    version: report?.version ?? null,
+    procedure: report?.procedure ?? null,
+    materialize: report?.materialize ?? null,
+    integrity: report?.integrity ?? null,
+    functional: report?.functional ?? null
+  };
+}
+
+/**
+ * 按三层解析加载 transformers。任何一层失败都不抛给调用方之外的语义：
+ * 全部失败时抛一个带「试过哪些、各自为什么失败」的错误，便于面板/状态接口直接展示。
+ * @param {object} [opts] - 选项。
+ * @param {string} [opts.runtimeDir] - 运行时根目录。
+ * @param {string} [opts.platform] - 平台。
+ * @param {Function} [opts.importModule] - import 实现（测试注入）。
+ * @param {(message: string) => void} [opts.onFailure] - 每次降级/失败的回调：
+ *   第 ① 层坏了却退到第 ② 层时，调用方（面板/日志）要能看见，不能静默。
+ * @returns {Promise<{module: any, source: "runtime"|"host", payloadId?: string, version?: string, entryUrl?: string}>}
+ */
+export async function loadTransformers({
+  runtimeDir = defaultRuntimeDir(),
+  platform = process.platform,
+  importModule = defaultImport,
+  onFailure = null
+} = {}) {
+  const failures = [];
+  const note = (message) => {
+    failures.push(message);
+    onFailure?.(message);
+  };
+
+  // ① 自管运行时
+  const candidate = resolveRuntimeEntry({ runtimeDir, platform });
+  if (candidate !== null) {
+    try {
+      const module = await importModule(candidate.entryUrl);
+      return {
+        module,
+        source: "runtime",
+        payloadId: candidate.payloadId,
+        version: candidate.version,
+        entryUrl: candidate.entryUrl
+      };
+    } catch (error) {
+      // 找到了却加载不起来 —— 这条必须带出去，「坏了」和「没有」不是一回事。
+      note(`自管运行时 ${candidate.payloadId} 加载失败：${error?.message ?? error}`);
+    }
+  }
+
+  // ② 宿主（用户自己装的 / 别的插件带进来的）
+  try {
+    const module = await importModule("@huggingface/transformers");
+    // 版本门禁：宿主装到 v5 时这一层会**静默**用起来，而 mneme 只验证过
+    // >=4.2 <5 的 API（详见 issue #131 的 peer 提案）。顶层没有 version 时看
+    // env.version —— transformers 的 Node 构建（实测 4.2.0）就是把版本挂在 env 上的。
+    //
+    // 拿不到版本不算「版本越界」：那会让第 ② 层对某些打包形态直接失效，
+    // 而它正是老用户在收编完成前的不断线保障。只拦明确越界的。
+    const version = module?.version ?? module?.env?.version;
+    if (version === undefined || transformersVersionOk(version)) {
+      return { module, source: "host", version };
+    }
+    note(
+      `宿主的 @huggingface/transformers 版本越界：${version}` +
+        `（只认可 >=${TRANSFORMERS_MIN.join(".")} 且 <${TRANSFORMERS_MAX_MAJOR}）`
+    );
+  } catch (error) {
+    note(`宿主未提供 @huggingface/transformers：${error?.message ?? error}`);
+  }
+
+  // ③ 都没有：给出可操作的下一步，而不是一句 module not found
+  const error = new Error(`${RUNTIME_HINT}\n${failures.map((f) => `  - ${f}`).join("\n")}`);
+  error.code = "MNEME_RUNTIME_UNAVAILABLE";
+  error.failures = failures;
+  throw error;
+}