@modusensus/dsh-mneme 0.7.31 → 0.8.0

package/scripts/build-runtime-manifest.mjs

@@ -0,0 +1,217 @@
+// 生成 runtime-manifest.json（issue #131 / PR-C）
+//
+// **平台无关**是这份清单的核心设计：数据源是 `package-lock.json` 而不是「本机装好的那棵树」。
+// npm 的 lockfile 里包含**所有平台**的包条目（各自的 os / cpu 与 integrity），所以一份清单就能
+// 覆盖 win32 / darwin / linux × x64 / arm64 —— 下载时再按平台过滤（`matchesPlatform`）。
+//
+// 为什么不做成「按平台各存一份、谁在哪个系统上生成」：那样 macOS 用户在一台没人跑过脚本的机器上
+// 会看到「清单里没有 darwin-arm64 的条目」而直接卡住。清单是随包发布的静态数据，它必须一次覆盖
+// 所有平台，而不是依赖某个贡献者手上有对应的机器。
+//
+// 哈希取自 lockfile 的 integrity（npm 自己算的），所以维护成本是「改依赖后重跑一次脚本」。
+//
+// 用法：
+//   node scripts/build-runtime-manifest.mjs            # 生成/更新
+//   node scripts/build-runtime-manifest.mjs --check     # 只校验现有文件与 lockfile 一致（CI 用）
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { matchesPlatform } from "../src/runtime/closure.js";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const MANIFEST = join(ROOT, "runtime-manifest.json");
+const MANIFEST_VERSION = 2;
+const ENTRY = "@huggingface/transformers";
+
+/**
+ * 证据：`@huggingface/transformers` 的 Node 构建（dist/transformers.node.mjs）顶层只 import
+ * onnxruntime-node 与 sharp，从不 import onnxruntime-web（把一个空的 onnxruntime-web 打桩进去，
+ * 嵌入结果逐字节相同：dims=[2,512]、L2 范数 1.0000、cos 0.3053）。而它解包后 127.7MB，占整个
+ * 闭包约三分之一。所以清单里剔除它，风险由 verify 的真实推理兜底。
+ */
+const EXCLUDED = { "onnxruntime-web": "Node 构建从不 import 它（打桩验证：嵌入结果逐字节相同）" };
+
+/**
+ * 被剔除的包，以及**它子树下的一切**。
+ *
+ * 只按包名过滤会漏掉嵌套条目：闭包是按源布局镜像的，所以存在
+ * `onnxruntime-web/node_modules/onnxruntime-common` 这种位于被剔除包内部的包 ——
+ * 那个位置根本不会被取回来，留在清单里就是让下载器去填一个不存在的坑。
+ * 同名但位于别处（例如顶层 onnxruntime-common）不受影响。
+ */
+export function isExcluded(pkg) {
+  return Object.keys(EXCLUDED).some(
+    (name) => pkg.name === name || pkg.rel === name || pkg.rel.startsWith(`${name}/`)
+  );
+}
+
+/** lockfile 的路径 → 包名（最后一段 `node_modules/` 之后的部分）。 */
+export function nameOfPath(path) {
+  const marker = path.lastIndexOf("node_modules/");
+  return marker === -1 ? path : path.slice(marker + "node_modules/".length);
+}
+
+/** lockfile 的路径 → payload 里的相对路径（去掉开头的 `node_modules/`）。 */
+export function relOfPath(path) {
+  return path.startsWith("node_modules/") ? path.slice("node_modules/".length) : path;
+}
+
+/**
+ * 按 Node 的解析语义列出候选路径：从引用者自身的 `node_modules` 逐级向上，最后兜底到根部。
+ *
+ * 例：引用者在 `node_modules/a/node_modules/b`、依赖 `x` →
+ *   `…/b/node_modules/x` → `node_modules/a/node_modules/x` → `node_modules/x`
+ * @param {string} fromPath - 引用者的 lockfile 路径。
+ * @param {string} name - 依赖名。
+ * @returns {string[]} 候选路径，由近到远。
+ */
+export function resolveCandidates(fromPath, name) {
+  const out = [`${fromPath}/node_modules/${name}`];
+  let cursor = fromPath;
+  while (cursor.includes("/node_modules/")) {
+    cursor = cursor.slice(0, cursor.lastIndexOf("/node_modules/"));
+    out.push(cursor === "" ? `node_modules/${name}` : `${cursor}/node_modules/${name}`);
+  }
+  if (!out.includes(`node_modules/${name}`)) out.push(`node_modules/${name}`);
+  return out;
+}
+
+/** registry 的 tarball 地址：lockfile 记了 resolved 就用它（与 integrity 同源），否则按 npm 约定推。 */
+function tarballUrl(name, version, resolved) {
+  if (typeof resolved === "string" && resolved.startsWith("http")) return resolved;
+  const base = name.startsWith("@") ? name.slice(name.indexOf("/") + 1) : name;
+  return `https://registry.npmjs.org/${name}/-/${base}-${version}.tgz`;
+}
+
+/**
+ * 从 lockfile 走一遍闭包。
+ * @param {object} lock - package-lock.json 的内容。
+ * @returns {{packages: object[], missing: string[]}} 包列表（按 rel 排序）与解析不到的依赖。
+ */
+export function closureFromLockfile(lock) {
+  const all = lock.packages ?? {};
+  const known = new Set(
+    Object.entries(all)
+      .filter(([path, meta]) => path.includes("node_modules/") && meta?.version !== undefined)
+      .map(([path]) => path)
+  );
+  const seen = new Map();
+  const missing = [];
+  const queue = [`node_modules/${ENTRY}`];
+
+  while (queue.length > 0) {
+    const path = queue.shift();
+    if (seen.has(path)) continue;
+    const meta = all[path];
+    if (meta?.version === undefined) {
+      missing.push(path);
+      continue;
+    }
+    if (isExcluded({ name: nameOfPath(path), rel: relOfPath(path) })) continue;
+    seen.set(path, meta);
+
+    const deps = { ...(meta.dependencies ?? {}), ...(meta.optionalDependencies ?? {}) };
+    for (const name of Object.keys(deps)) {
+      const resolved = resolveCandidates(path, name).find((option) => known.has(option));
+      if (resolved === undefined) missing.push(`${name}（被 ${relOfPath(path)} 需要）`);
+      else queue.push(resolved);
+    }
+  }
+
+  const packages = [...seen.entries()]
+    .map(([path, meta]) => ({
+      name: nameOfPath(path),
+      version: meta.version,
+      rel: relOfPath(path),
+      integrity: meta.integrity ?? null,
+      tarball: tarballUrl(nameOfPath(path), meta.version, meta.resolved),
+      // 平台约束照抄 lockfile：下载器按它过滤。没有这三个字段 = 与平台无关。
+      ...(Array.isArray(meta.os) ? { os: meta.os } : {}),
+      ...(Array.isArray(meta.cpu) ? { cpu: meta.cpu } : {}),
+      // libc 也带上：linux-x64 的 glibc 机器靠它剔掉两套 musl 变体（十几 MB）。
+      // 下载器只在**确认**了本机 libc 时才据此过滤，拿不到证据就不看这个字段。
+      ...(Array.isArray(meta.libc) ? { libc: meta.libc } : {})
+    }))
+    .sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+
+  return { packages, missing };
+}
+
+/** 某个平台实际需要取哪些包（与下载器用同一条判据）。 */
+export function packagesForPlatform(manifest, platform, arch, libc = null) {
+  return manifest.packages.filter((pkg) => matchesPlatform(pkg, platform, arch, libc));
+}
+
+/** 生成一份**平台无关**的清单。 */
+export function build() {
+  const lock = JSON.parse(readFileSync(join(ROOT, "package-lock.json"), "utf8"));
+  const { packages, missing } = closureFromLockfile(lock);
+  // 解析不到的依赖必须让生成**失败**：带缺口的清单会让用户在下载时才失败，而且「少了一个包」
+  // 这种缺口结构检查看不出来（它只点三个必需包）。生成期的数据问题就该在生成期炸掉 ——
+  // 这也是我第一版真正踩过的：被剔除包的孤儿依赖留在了清单里，而生成器一声不吭。
+  if (missing.length > 0) {
+    throw new Error(`这些依赖在 package-lock.json 里解析不到：${missing.slice(0, 10).join("、")}`);
+  }
+
+  const entry = packages.find((pkg) => pkg.rel === ENTRY);
+  if (entry === undefined) throw new Error(`闭包入口没解析出来：${missing.join("; ") || "lockfile 里没有它"}`);
+  // 查不到 sha512 就不能写进清单：那等于让下载器「先信任再校验」，是假校验。
+  const withoutIntegrity = packages.filter(
+    (pkg) => typeof pkg.integrity !== "string" || !pkg.integrity.startsWith("sha512-")
+  );
+  if (withoutIntegrity.length > 0) {
+    throw new Error(`这些包在 package-lock.json 里没有 sha512 integrity：${withoutIntegrity.map((p) => p.rel).join("、")}`);
+  }
+
+  return {
+    manifestVersion: MANIFEST_VERSION,
+    entry: ENTRY,
+    transformersVersion: entry.version,
+    excluded: EXCLUDED,
+    // 平台无关：下载时按 os/cpu/libc 过滤（payloadId 也由下载器按本机平台算）。
+    packages
+  };
+}
+
+/** 应当被覆盖的平台（自检与 CI 断言用）。 */
+export const COVERED_PLATFORMS = [
+  ["win32", "x64"],
+  ["win32", "arm64"],
+  ["darwin", "x64"],
+  ["darwin", "arm64"],
+  ["linux", "x64"],
+  ["linux", "arm64"]
+];
+
+/** 命令行入口。`--check` 只校验，不写文件。 */
+export function main(args = process.argv.slice(2)) {
+  const check = args.includes("--check");
+  const built = build();
+  const coverage = COVERED_PLATFORMS.map(([platform, arch]) => {
+    const set = packagesForPlatform(built, platform, arch);
+    const hasEntry = set.some((pkg) => pkg.rel === ENTRY);
+    const hasNative = set.some((pkg) => pkg.rel === "onnxruntime-node");
+    // linux 再报一次「确认 glibc 时」的包数：下载器会剔掉另一套 libc 的变体，这行让
+    // 「剔掉了多少」在 --check 里看得见，而不是只能翻清单。
+    const glibc = platform === "linux" ? `；确认 glibc 时 ${packagesForPlatform(built, platform, arch, "glibc").length} 个` : "";
+    return `${platform}-${arch}: ${set.length} 个包${glibc}${hasEntry && hasNative ? "" : "（缺入口或原生依赖！）"}`;
+  });
+
+  if (check) {
+    const existing = existsSync(MANIFEST) ? readFileSync(MANIFEST, "utf8") : "";
+    const same = existing === `${JSON.stringify(built, null, 2)}\n`;
+    process.stdout.write(`${same ? "✓" : "✗"} 清单与 package-lock.json ${same ? "一致" : "不一致，请重跑生成"}\n`);
+    for (const line of coverage) process.stdout.write(`   ${line}\n`);
+    return same ? 0 : 1;
+  }
+
+  writeFileSync(MANIFEST, `${JSON.stringify(built, null, 2)}\n`, "utf8");
+  process.stdout.write(`写入 ${MANIFEST}\n共 ${built.packages.length} 个包（已剔除 ${Object.keys(EXCLUDED).join("、")} 及其子树）\n`);
+  for (const line of coverage) process.stdout.write(`   ${line}\n`);
+  return 0;
+}
+
+// 只有被直接执行时才干活：被 import 时（测试里）不该顺手改写清单文件。
+const invokedDirectly =
+  process.argv[1] != null && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/").split("/").pop() ?? "");
+if (invokedDirectly) process.exitCode = main();

package/scripts/mneme-runtime.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * 本地推理运行时管理入口（issue #131 / PR-A）
+ *
+ * 为什么不在 bin/cli.mjs 里加子命令：那个 CLI 的契约是「外部 HTTP API 客户端」，
+ * 要求 dsh-mneme 服务正在运行。而收编/验证运行时恰恰发生在服务没起来、插件甚至
+ * 装不上的时候 —— 两者是相反的使用场景。scripts/ 是与 benchmark-embed.js 同类的
+ * 本地工具目录，放这里符合既有约定，也不用动物那个零依赖 CLI 的契约。
+ *
+ * 用法（在插件目录下运行）：
+ *   node scripts/mneme-runtime.mjs status  [--runtime <dir>] [--json]
+ *   node scripts/mneme-runtime.mjs adopt   --from <宿主 node_modules 目录> [--runtime <dir>] [--overwrite] [--json]
+ *   node scripts/mneme-runtime.mjs verify  [--runtime <dir>] [--cache-dir <dir>] [--json]
+ *
+ * 退出码：0 = 健康 / 1 = 不健康或失败 / 2 = 用法错误。
+ * 每一档都要能被脚本直接拿去 gate，所以「没装」和「装坏了」返回的都是 1，
+ * 具体区别看输出里的 status。
+ */
+import process from "node:process";
+import { adoptRuntime } from "../lib/runtime/adopt.js";
+import { describeLocalRuntime, resolveRuntimeEntry } from "../lib/runtime/loader.js";
+import { defaultModelCacheDir, defaultRuntimeDir, describePayload } from "../lib/runtime/layout.js";
+import { verifyPayload } from "../lib/runtime/verify.js";
+
+// 注意：下面是模板字面量，帮助正文里**不能出现反引号** —— 会把字面量提前截断。
+// 这个坑踩过一次，而且因为本文件原本不在任何测试覆盖里，CI 完全没抓到；
+// 现在由 test/runtime-cli.test.js 动态 import 本文件来兜底（语法错会在测试里直接炸）。
+const USAGE = `本地推理运行时管理（dsh-mneme / issue #131）
+
+用法：
+  node scripts/mneme-runtime.mjs status  [--runtime <dir>] [--json]
+  node scripts/mneme-runtime.mjs adopt   --from <宿主 node_modules 目录> [--runtime <dir>] [--overwrite] [--json]
+  node scripts/mneme-runtime.mjs verify  [--runtime <dir>] [--cache-dir <dir>] [--json]
+
+说明：
+  status  只读探查：这份运行时在哪、来源是什么、结构完不完整。不加载模型。
+  adopt   把宿主 node_modules 里已有的那份依赖闭包收编进插件自管目录，
+          优先用硬链接（同盘时几乎不额外占盘）。收编后宿主那份可以随时被 pnpm 删掉。
+          本机哪里都没有这份依赖时，可在任意空目录先装一份：
+              npm i @huggingface/transformers@^4.2.0
+          再把那个 node_modules 作为 --from 传进来。必须让安装脚本正常执行（npm 默认会，
+          pnpm 10+ 默认拦截构建脚本），否则取不到 onnxruntime-node / sharp 的原生二进制。
+  verify  真加载运行时并跑一次推理，外加结构与完整性检查。
+          ⚠ 功能验证是离线的（allowRemoteModels=false）：模型必须已在缓存目录里，
+          否则会明确失败 —— 这是有意的，验证不该偷偷触网。
+          默认缓存目录若与你的 embedModelCacheDir 不一致，用 --cache-dir 指过去。
+
+默认运行时目录：${defaultRuntimeDir()}
+默认模型缓存目录：${defaultModelCacheDir()}
+`;
+
+class UsageError extends Error {}
+
+/** 必须带值的选项；缺值时是用法错误，不能把 "true" 当成路径用下去。 */
+const VALUE_OPTIONS = new Set(["runtime", "from", "cache-dir"]);
+/** 纯开关。 */
+const FLAG_OPTIONS = new Set(["json", "overwrite"]);
+
+/**
+ * 参数解析：只支持 `--key value` 与 `--flag`。
+ * 够用就不引库 —— 这个脚本要在「插件装不上」的场景下还能跑，依赖越少越好。
+ *
+ * 两个刻意的严格行为：
+ * - 缺值的 `--runtime` / `--from` / `--cache-dir` 直接报用法错误（exit 2）。宽松处理会让
+ *   它们变成 `true`，再被当作一个叫 "true" 的路径用下去，最后以 exit 1 收场 ——
+ *   真正的「你少打了一个值」被伪装成「运行时坏了」。
+ * - 未知选项也报用法错误，而不是静默忽略：打错字应当立刻可见。
+ */
+function parseArgs(argv) {
+  const options = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    const key = token.startsWith("--") ? token.slice(2) : null;
+    if (key === null || (!VALUE_OPTIONS.has(key) && !FLAG_OPTIONS.has(key))) {
+      const accepted = [
+        ...[...VALUE_OPTIONS].map((k) => `--${k} <值>`),
+        ...[...FLAG_OPTIONS].map((k) => `--${k}`)
+      ].join("、");
+      throw new UsageError(`无法识别的参数：${token}（可用：${accepted}）`);
+    }
+    if (FLAG_OPTIONS.has(key)) {
+      options[key] = true;
+      continue;
+    }
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new UsageError(`--${key} 需要带一个值`);
+    }
+    options[key] = value;
+    i++;
+  }
+  return options;
+}
+
+const printJson = (value) => process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+
+/** payloadId → 人类可读的标签，纯展示。 */
+function describePayloadLabel(report) {
+  const parts = [];
+  if (report.version) parts.push(`transformers ${report.version}`);
+  if (report.procedure) parts.push(`来源 ${report.procedure}`);
+  if (report.materialize) parts.push(`物化 ${report.materialize}`);
+  return parts.join("，");
+}
+
+function runStatus({ runtimeDir, asJson }) {
+  const report = describeLocalRuntime({ runtimeDir });
+  const healthy = report.status === "available";
+  if (asJson) {
+    printJson(report);
+    return healthy ? 0 : 1;
+  }
+
+  const label = { available: "可用", missing: "未安装", broken: "损坏", unreadable: "读不到" }[report.status] ?? report.status;
+  console.log(`运行时目录：${report.runtimeDir}`);
+  console.log(`状态：${label}`);
+  if (report.payloadId) console.log(`payload：${report.payloadId}`);
+  const extra = describePayloadLabel(report);
+  if (extra) console.log(`       ${extra}`);
+  if (healthy) {
+    console.log(`完整性：${report.integrity}`);
+    // 明说「结构通过 ≠ 验过」，否则这个面板会给出虚假的安心感。
+    console.log(`功能：${report.functional}（状态探查不加载模型，跑 verify 才能确认真的能推理）`);
+  }
+  for (const item of report.missing ?? []) console.log(`缺失：${item}`);
+  for (const reason of report.reasons ?? []) console.log(`原因：${reason}`);
+  if (report.reason) console.log(`原因：${report.reason}`);
+  if (!healthy) console.log(`\n${report.hint}`);
+  return healthy ? 0 : 1;
+}
+
+async function runAdopt({ runtimeDir, asJson, options }) {
+  const from = String(options.from ?? "").trim();
+  if (!from) {
+    throw new UsageError(
+      "adopt 需要 --from <宿主 node_modules 目录>，例如：\n" +
+        "  .../profiles/<profile>/node_modules\n" +
+        "（就是当前装着 @huggingface/transformers 的那个 node_modules）"
+    );
+  }
+
+  const result = await adoptRuntime({
+    fromModulesDir: from,
+    runtimeDir,
+    overwrite: options.overwrite === true
+  });
+
+  // 收编失败时 adoptRuntime **不带 payloadDir**（入口包解析不到就是这条路径）。
+  // 必须先处理，否则下面拿 undefined 当路径喂给 describePayload，用户看到的是
+  // `TypeError: The "path" argument must be of type string` 的堆栈，
+  // 而不是「入口包不存在 + 下一步该做什么」——而这是文档里给用户的第一条命令。
+  if (result.ok === false) {
+    if (asJson) printJson(result);
+    else console.log(`收编失败：${result.reason}`);
+    return 1;
+  }
+
+  // 搬运完立刻做结构检查：缺件现在就能发现，不必等到第一次推理才炸。
+  const structural = describePayload(result.payloadDir);
+
+  // 两条判据都要过：describePayload 只点三个必需包，**不看闭包计划里的必需依赖缺口**。
+  // 只认 structural.ok 的话，「缺传递依赖、入口一 import 就炸」的收编会报 exit 0，
+  // 脚本化的 gate 就在最需要它的时候误报健康。
+  const gaps = result.plan.gaps;
+  const healthy = structural.ok && gaps.length === 0;
+
+  if (asJson) {
+    printJson({ ...result, structural, healthy });
+    return healthy ? 0 : 1;
+  }
+
+  console.log(`已收编到：${result.payloadDir}`);
+  console.log(`payload：${result.payloadId}`);
+  console.log(`包数：${result.plan.packages.length}    文件：${result.totals.files}    字节：${result.totals.bytes}`);
+  console.log(`物化方式：${result.manifest.materialize.mode}` + (result.manifest.materialize.linkError ? `（硬链接失败原因：${result.manifest.materialize.linkError}）` : ""));
+  if (result.plan.skipped.length) {
+    console.log(`跳过（平台不适用）：${result.plan.skipped.map((s) => s.name).join("、")}`);
+  }
+  for (const warning of result.manifest.warnings) console.log(`警告：${warning}`);
+  for (const gap of gaps) {
+    console.log(`缺失依赖：${gap.name}（被 ${gap.from} 需要：${gap.reason}）`);
+  }
+  for (const item of structural.missing) console.log(`缺失文件：${item}`);
+  for (const reason of structural.reasons) console.log(`结构问题：${reason}`);
+  console.log(`结构检查：${structural.ok ? "通过" : "未通过"}`);
+  if (gaps.length > 0) {
+    console.log(`闭包完整性：未通过（${gaps.length} 个必需依赖缺失，入口加载时会失败）`);
+  }
+  if (healthy) {
+    console.log(`\n下一步：node scripts/mneme-runtime.mjs verify   # 真跑一次推理确认可用`);
+  }
+  return healthy ? 0 : 1;
+}
+
+async function runVerify({ runtimeDir, asJson, options }) {
+  const candidate = resolveRuntimeEntry({ runtimeDir });
+  if (candidate === null) {
+    // 「没得验」不是用法错误，是不健康 —— 复用 status 的提示，别自己编一套说法。
+    const report = describeLocalRuntime({ runtimeDir });
+    if (asJson) printJson(report);
+    else console.log(`没有可用的运行时 payload。\n\n${report.hint}`);
+    return 1;
+  }
+
+  const cacheDir = String(options["cache-dir"] ?? "").trim() || defaultModelCacheDir();
+  if (!asJson) {
+    console.log(`验证 payload：${candidate.payloadId}`);
+    console.log(`模型缓存目录：${cacheDir}`);
+    console.log("正在加载运行时并推理（首次可能要几十秒）...");
+  }
+
+  const result = await verifyPayload(candidate.dir, { cacheDir });
+
+  if (asJson) {
+    printJson(result);
+    return result.ok ? 0 : 1;
+  }
+
+  console.log(`结构检查：${result.structural.ok ? "通过" : "未通过"}`);
+  for (const item of result.structural.missing) console.log(`  缺失：${item}`);
+  for (const reason of result.structural.reasons) console.log(`  原因：${reason}`);
+  const fn = result.functional;
+  console.log(`功能验证：${fn.ok ? `通过（维度 ${fn.dim}，${fn.rows} 行，${fn.elapsedMs}ms）` : "未通过"}`);
+  if (!fn.ok) {
+    console.log(`  原因：${fn.reason}`);
+    // 最常见的失败是模型不在这个目录 —— 注意这里的默认值不一定等于用户配置的
+    // embedModelCacheDir，所以要明确告诉他能改。
+    console.log(`  提示：功能验证不触网（allowRemoteModels=false），模型必须已在缓存目录里。`);
+    console.log(`        若模型在别处，用 --cache-dir <目录> 指过去（应与配置项 embedModelCacheDir 一致）；`);
+    console.log(`        或先用 embedProvider="local" 触发一次下载（走 embedModelMirror 镜像）。`);
+  }
+  console.log(`完整性：${result.integrity.status}${result.integrity.detail ? `（${result.integrity.detail}）` : ""}`);
+  console.log(`\n总判定：${result.ok ? "通过" : "未通过"}`);
+  return result.ok ? 0 : 1;
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    process.stdout.write(USAGE);
+    return command ? 0 : 2;
+  }
+  const options = parseArgs(rest);
+  const runtimeDir = String(options.runtime ?? "").trim() || defaultRuntimeDir();
+  const asJson = options.json === true;
+
+  if (command === "status") return runStatus({ runtimeDir, asJson });
+  if (command === "adopt") return runAdopt({ runtimeDir, asJson, options });
+  if (command === "verify") return runVerify({ runtimeDir, asJson, options });
+  throw new UsageError(`未知命令：${command}\n\n${USAGE}`);
+}
+
+/**
+ * 只有被直接执行时才跑 CLI。这样测试可以安全地 `import` 本文件来验证它能被解析并求值
+ * —— 脚本不在任何其它测试覆盖里，一个模板字面量里的反引号就足以让它整体坏掉而 CI 全绿。
+ * 与 scripts/benchmark-recall.js 的 invokedDirectly 同一套写法。
+ */
+const invokedDirectly =
+  process.argv[1] != null && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/").split("/").pop() ?? "");
+
+if (invokedDirectly) {
+  try {
+    process.exitCode = await main();
+  } catch (error) {
+    if (error instanceof UsageError) {
+      process.stderr.write(`${error.message}\n`);
+      process.exitCode = 2;
+    } else {
+      // 验证/收编本身是 fail-safe 的；能走到这里的多半是环境问题（磁盘、权限），
+      // 如实打出来，别吞。
+      process.stderr.write(`失败：${error?.stack ?? error}\n`);
+      process.exitCode = 1;
+    }
+  }
+}
+
+export { main, parseArgs, runAdopt, UsageError };