@modusensus/dsh-mneme 0.7.31 → 0.8.0

package/src/runtime/adopt.js

@@ -0,0 +1,176 @@
+// 收编宿主已有的运行时（issue #131 / PR-A）
+//
+// 场景：老用户（以及本机）profile 里已经装好了整套 transformers + onnxruntime，
+// 而且它就是能跑的。删依赖之前先把这套「收编」进插件自管的目录，老用户的本地
+// 嵌入就不会因为后续的 prune 而断掉——这是分两步发版里第一步的全部意义。
+//
+// 两条实现约束：
+//
+// 1) 同卷硬链接、跨卷回退复制。收编的源和目标通常都在用户家目录（同卷），
+//    硬链接是瞬时的、不额外占盘；一旦跨卷 linkSync 会抛 EXDEV，则逐个文件回退复制。
+//
+// 2) 不跟随符号链接。pnpm 的 isolated 布局用符号链接指向虚拟store，跟随它会把
+//    宿主 store 里的东西拖进来、还会让目录层级失真。这里选择跳过并如实记进
+//    warnings，让上层的验证去发现「收编不完整」，而不是悄悄产出一份半对的运行时。
+//
+// @module dsh-mneme/runtime/adopt
+import { copyFileSync, existsSync, linkSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_MAX_PACKAGES, planClosure } from "./closure.js";
+import { defaultRuntimeDir, nodeModulesDir, payloadDir, payloadId, runtimeManifestPath } from "./layout.js";
+
+/** 清单版本：将来字段变化时用来判断怎么读。 */
+export const RUNTIME_MANIFEST_VERSION = 1;
+
+/**
+ * 把一个包目录物化到目标位置。跳过嵌套的 `node_modules`——那些包在闭包计划里
+ * 是独立条目，会各自落到自己的相对位置；不跳就会重复搬一遍。
+ * @param {object} opts - 选项。
+ * @param {Function} [opts.link] - 硬链接实现，默认 fs.linkSync；测试用来注入失败。
+ * @returns {{files: number, bytes: number, linked: number, copied: number, symlinks: number, linkError: string|null}}
+ */
+export function materializePackage({ srcDir, destDir, warnings = [], link = linkSync }) {
+  const stats = { files: 0, bytes: 0, linked: 0, copied: 0, symlinks: 0, linkError: null };
+
+  const walk = (src) => {
+    for (const entry of readdirSync(src, { withFileTypes: true })) {
+      // 嵌套 node_modules 由闭包计划单独负责；跳过以免重复搬运。
+      if (entry.isDirectory() && entry.name === "node_modules") continue;
+      const full = join(src, entry.name);
+      const dest = join(destDir, full.slice(srcDir.length + 1));
+      if (entry.isSymbolicLink()) {
+        stats.symlinks++;
+        warnings.push(`跳过符号链接：${full}`);
+        continue;
+      }
+      if (entry.isDirectory()) {
+        mkdirSync(dest, { recursive: true });
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      mkdirSync(join(dest, ".."), { recursive: true });
+      try {
+        link(full, dest);
+        stats.linked++;
+      } catch (error) {
+        // 跨卷（EXDEV）、权限、文件系统不支持硬链接：逐个文件回退复制。
+        // 这里只记录原因（返回给调用方），不往 warnings 里塞——warnings 是「按文件」
+        // 的事件（例如跳过符号链接），而「为什么整体变成复制」是「按整次收编」的事实，
+        // 去重与呈现由 adoptRuntime 负责，否则每个包都会重复记一条。
+        if (stats.linkError === null) {
+          stats.linkError = `${error?.code ?? ""} ${error?.message ?? error}`.trim();
+        }
+        copyFileSync(full, dest);
+        stats.copied++;
+      }
+      stats.files++;
+      stats.bytes += statSync(full).size;
+    }
+  };
+
+  mkdirSync(destDir, { recursive: true });
+  walk(srcDir);
+  return stats;
+}
+
+/**
+ * 从一份现成的 `node_modules` 收编出一份自管运行时，并写下清单。
+ * @param {object} opts - 选项。
+ * @param {string} opts.fromModulesDir - 源 node_modules（通常是宿主的）。
+ * @param {string} [opts.runtimeDir] - 运行时根目录。
+ * @param {string} [opts.platform] - 目标平台。
+ * @param {string} [opts.arch] - 目标架构。
+ * @param {string} [opts.procedure] - 来源标记（adopted / downloaded / manual）。
+ * @param {boolean} [opts.overwrite] - 目标已存在时是否覆盖。
+ * @param {number} [opts.maxPackages] - 闭包条目上限。
+ * @param {Function} [opts.link] - 硬链接实现，默认 fs.linkSync；测试用来注入失败以覆盖回退分支
+ *   （与 src/local-embedder.js 的 engineFactory 同一思路：把不可复现的环境差异变成可注入的依赖）。
+ * @returns {object} 结果；失败时 ok=false 且带 reason，不抛异常。
+ */
+export function adoptRuntime({
+  fromModulesDir,
+  runtimeDir = defaultRuntimeDir(),
+  platform = process.platform,
+  arch = process.arch,
+  procedure = "adopted",
+  overwrite = false,
+  maxPackages,
+  link
+}) {
+  const plan = planClosure({ rootModulesDir: fromModulesDir, platform, arch, maxPackages });
+  const entryPackage = plan.packages[0];
+  if (entryPackage === undefined) {
+    return { ok: false, reason: plan.gaps[0]?.reason ?? "入口包未解析到", plan };
+  }
+
+  const version = entryPackage.version ?? "unknown";
+  const id = payloadId({ version, platform, arch });
+  const dir = payloadDir(runtimeDir, id);
+
+  if (existsSync(dir) && !overwrite) {
+    return { ok: false, reason: `目标已存在：${dir}（需要覆盖请传 overwrite: true）`, payloadDir: dir, payloadId: id, plan };
+  }
+
+  // 截断的闭包必须拒绝。maxPackages 截断会静默丢掉传递依赖，而结构检查（describePayload）
+  // 只看必需包、版本和入口文件 —— 于是一份残缺的 payload 会被判为可用、被 loader 选中，
+  // 直到 import 原生模块时才炸，且错误现场离真正的原因很远。宁可在物化前明确失败。
+  if (plan.truncated) {
+    return {
+      ok: false,
+      reason: `依赖闭包被截断（上限 ${maxPackages ?? DEFAULT_MAX_PACKAGES} 个包），拒绝收编；请提高 maxPackages 后重试`,
+      payloadDir: dir,
+      payloadId: id,
+      plan
+    };
+  }
+
+  // 覆盖前必须先清空目标目录。不清的话，linkSync 对已存在的目标路径抛 EEXIST，
+  // 于是每个文件都落到复制分支：物化方式会假报成 "copy"、警告会错说「硬链接不可用」、
+  // 整份闭包真实占盘，而且上一次闭包留下的残留文件永远不会被清掉。
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+
+  const warnings = [];
+  const totals = { files: 0, bytes: 0, linked: 0, copied: 0, symlinks: 0 };
+  let linkError = null;
+  try {
+    for (const pkg of plan.packages) {
+      const stats = materializePackage({
+        srcDir: pkg.srcDir,
+        destDir: join(nodeModulesDir(dir), pkg.rel),
+        warnings,
+        link
+      });
+      for (const key of Object.keys(totals)) totals[key] += stats[key];
+      if (linkError === null && stats.linkError !== null) linkError = stats.linkError;
+    }
+  } catch (error) {
+    // 契约是「失败时 ok=false 且带 reason，不抛」。物化到一半失败更要清干净：半份 payload 会被
+    // 结构检查看成「差不多能用」，然后在 import 原生模块时才炸，错误现场离原因很远。
+    rmSync(dir, { recursive: true, force: true });
+    return { ok: false, reason: `物化失败：${String(error?.message ?? error)}` };
+  }
+  // 物化方式如实记进清单：收编「本该不占盘却占了盘」时，用户和面板都能看到原因。
+  const mode = totals.copied === 0 ? "hardlink" : totals.linked === 0 ? "copy" : "mixed";
+  if (linkError !== null) warnings.push(`硬链接不可用，已回退为复制：${linkError}`);
+
+  const manifest = {
+    manifestVersion: RUNTIME_MANIFEST_VERSION,
+    payloadId: id,
+    entry: plan.entry,
+    version,
+    platform,
+    arch,
+    procedure,
+    createdAt: new Date().toISOString(),
+    materialize: { mode, linkError },
+    packages: plan.packages.map((p) => ({ name: p.name, version: p.version, rel: p.rel, optional: p.optional })),
+    gaps: plan.gaps,
+    skipped: plan.skipped,
+    warnings
+  };
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(runtimeManifestPath(dir), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+  return { ok: true, payloadDir: dir, payloadId: id, version, plan, manifest, totals };
+}

package/src/runtime/closure.js

@@ -0,0 +1,172 @@
+// 依赖闭包遍历 + 平台过滤（issue #131 / PR-A）
+//
+// 用途：adopt（从宿主 node_modules 收编）与 export（导出给别的机器）要回答的是
+// 同一个问题——「一份能跑的运行时，到底需要哪些包，各自该落到哪个位置」。
+//
+// 两个刻意的设计：
+//
+// 1) 按源布局镜像，不压平。入口 transformers.node.mjs 内部是裸导入
+//    （`import sharp from "sharp"`、`import * as ONNX_NODE from "onnxruntime-node"`），
+//    靠 Node 逐级向上查找解析。只要目标目录的嵌套结构与源一致，解析行为就一致；
+//    压平会把「同一个包的两个版本分别落在不同层」这类情形悄悄改成另一种结果。
+//    所以 rel 保留 `a/node_modules/b` 这种层级。
+//
+// 2) 跳过 peerDependencies。peer 由宿主提供（例如 @deepseek-ai/* 那些服务），
+//    插件自管的运行时不该把宿主的实现复制进来——复制了反而会和宿主的实例分叉。
+//
+// @module dsh-mneme/runtime/closure
+import { existsSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { readJsonSafe } from "./layout.js";
+
+/** 闭包条目数上限：纯属防呆，命中即截断并如实上报，不静默丢包。 */
+export const DEFAULT_MAX_PACKAGES = 400;
+
+/**
+ * 包是否匹配当前平台。npm 用 package.json 的 os / cpu / libc 字段声明平台，
+ * 支持 `["win32"]` 正向匹配与 `["!darwin"]` 反向排除两种写法。
+ * 字段缺省表示「不限平台」。
+ *
+ * libc（glibc / musl）与前两者不同：**只有确实知道本机 libc 时才据此过滤**。
+ * 传 null（拿不到证据）就一律放行 —— 反过来「拿不到就当 musl」会把 glibc 变体滤掉，
+ * 装出一份必然 import 不起来的运行时，而本仓库没有 Linux 机器能验证这条路径。
+ * 少省十几兆，换「不会静默装错」。
+ * @param {any} manifest - 包的 package.json（或清单条目）。
+ * @param {string} platform - process.platform 取值。
+ * @param {string} arch - process.arch 取值。
+ * @param {string|null} [libc] - 本机 libc；null/缺省 = 不据此过滤。
+ * @returns {boolean} 是否匹配。
+ */
+export function matchesPlatform(manifest, platform, arch, libc = null) {
+  const check = (values, actual) => {
+    if (!Array.isArray(values) || values.length === 0) return true;
+    const negated = values.filter((v) => typeof v === "string" && v.startsWith("!"));
+    const positive = values.filter((v) => typeof v === "string" && !v.startsWith("!"));
+    // 反向排除优先：命中任一 `!x` 即不匹配（与 npm 的语义一致）。
+    if (negated.some((v) => v.slice(1) === actual)) return false;
+    if (positive.length === 0) return true;
+    return positive.includes(actual);
+  };
+  if (!check(manifest?.os, platform) || !check(manifest?.cpu, arch)) return false;
+  if (libc === null || libc === undefined) return true;
+  return check(manifest?.libc, libc);
+}
+
+/**
+ * 按 Node 的解析规则，从 fromDir 出发找 name 的包目录，但**不越出 rootModulesDir**。
+ *
+ * Node 的规则是：从所在目录逐级向上，每级查 `<级>/node_modules/<name>`。所以对
+ * `root/@scope/pkg` 而言，候选依次是 `root/@scope/pkg/node_modules/...`、
+ * `root/@scope/node_modules/...`、`root/node_modules/...`（这一级是
+ * node_modules 套 node_modules，通常不存在），最后到 `dirname(root)/node_modules/...`
+ * ——正好就是 `root/<name>`。因此循环要允许走到 root 的上一级再停。
+ * @param {string} fromDir - 从哪个包目录出发解析。
+ * @param {string} name - 依赖名。
+ * @param {string} rootModulesDir - 允许查找的边界 node_modules 目录。
+ * @returns {string|null} 包目录绝对路径，找不到返回 null。
+ */
+export function resolvePackageDir(fromDir, name, rootModulesDir) {
+  const limit = dirname(rootModulesDir);
+  let dir = fromDir;
+  for (;;) {
+    const candidate = join(dir, "node_modules", name);
+    if (existsSync(join(candidate, "package.json"))) return candidate;
+    if (dir === limit || dir === dirname(dir)) return null;
+    dir = dirname(dir);
+  }
+}
+
+/** 转成 manifest 里使用的、与平台无关的相对路径（始终用 `/`）。 */
+function toRel(root, dir) {
+  return relative(root, dir).split(sep).join("/");
+}
+
+/**
+ * 计算一份运行时的依赖闭包。
+ *
+ * 只走 dependencies 与 optionalDependencies：
+ * - 必需依赖缺失 → 记进 gaps（让调用方能如实报「这份闭包不完整」）；
+ * - 可选依赖缺失 → 静默跳过（这正是平台分片包在别的平台上的正常形态）；
+ * - 平台不匹配的包 → 记进 skipped（导出给别的机器时，跨平台的残留不会被带走）。
+ * @param {object} opts - 选项。
+ * @param {string} opts.rootModulesDir - 源 node_modules 目录。
+ * @param {string} [opts.entry] - 入口包名。
+ * @param {string} [opts.platform] - 目标平台。
+ * @param {string} [opts.arch] - 目标架构。
+ * @param {number} [opts.maxPackages] - 条目上限。
+ * @returns {{rootModulesDir: string, entry: string, platform: string, arch: string,
+ *   packages: {name: string, version: string|null, rel: string, srcDir: string, optional: boolean}[],
+ *   gaps: {name: string, from: string, reason: string}[],
+ *   skipped: {name: string, rel: string, reason: string}[], truncated: boolean}}
+ */
+export function planClosure({
+  rootModulesDir,
+  entry = "@huggingface/transformers",
+  platform = process.platform,
+  arch = process.arch,
+  maxPackages = DEFAULT_MAX_PACKAGES
+} = {}) {
+  const packages = [];
+  const gaps = [];
+  const skipped = [];
+  const seen = new Set();
+
+  const entryDir = resolvePackageDir(rootModulesDir, entry, rootModulesDir);
+  if (entryDir === null) {
+    gaps.push({ name: entry, from: ".", reason: "入口包不存在" });
+    return { rootModulesDir, entry, platform, arch, packages, gaps, skipped, truncated: false };
+  }
+
+  // BFS：队列里放已被解析出来的包目录。用真实目录去重，避免软链接/重复边导致来回走。
+  const queue = [{ dir: entryDir, rel: toRel(rootModulesDir, entryDir), optional: false }];
+  let truncated = false;
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (seen.has(current.dir)) continue;
+    seen.add(current.dir);
+
+    const manifest = readJsonSafe(join(current.dir, "package.json"));
+    if (manifest === undefined) {
+      gaps.push({ name: current.rel, from: current.rel, reason: "package.json 读不到" });
+      continue;
+    }
+    // 入口包本身不做平台过滤：它是用户明确要的那一个。
+    if (current.rel !== toRel(rootModulesDir, entryDir) && !matchesPlatform(manifest, platform, arch)) {
+      skipped.push({ name: manifest.name ?? current.rel, rel: current.rel, reason: "平台不匹配" });
+      continue;
+    }
+    if (packages.length >= maxPackages) {
+      truncated = true;
+      break;
+    }
+    packages.push({
+      name: manifest.name ?? current.rel,
+      version: manifest.version ?? null,
+      rel: current.rel,
+      srcDir: current.dir,
+      optional: current.optional
+    });
+
+    const required = Object.keys(manifest.dependencies ?? {});
+    const optional = Object.keys(manifest.optionalDependencies ?? {});
+    for (const name of [...required, ...optional]) {
+      const isOptional = optional.includes(name);
+      const dir = resolvePackageDir(current.dir, name, rootModulesDir);
+      if (dir === null) {
+        // 可选依赖缺失是正常形态（平台分片包在别的平台就是这样），不报警。
+        if (!isOptional) gaps.push({ name, from: current.rel, reason: "必需依赖未找到" });
+        continue;
+      }
+      const rel = toRel(rootModulesDir, dir);
+      // 不允许越出源树：越出说明解析跑到了宿主其它位置，这份闭包就不是自包含的。
+      if (rel.startsWith("..")) {
+        gaps.push({ name, from: current.rel, reason: "解析结果越出源 node_modules" });
+        continue;
+      }
+      queue.push({ dir, rel, optional: isOptional });
+    }
+  }
+
+  return { rootModulesDir, entry, platform, arch, packages, gaps, skipped, truncated };
+}

package/src/runtime/download.js

@@ -0,0 +1,247 @@
+// 运行时取件（issue #131 / PR-C）
+//
+// 三档来源，按可用性依次尝试。第一档「收编本机 node_modules」在 adopt.js；这里管后两档：
+//   ② 本地 .tgz 目录 —— 给「某个包网络下不到」的情况（本机就有一份 82MB 的 vendor tarball）；
+//   ③ registry（可换镜像）—— 有网络时的常规路径。
+//
+// 三条硬规矩：
+//   1. **先校验 sha512 再落盘**。不匹配就不写、整次判失败。没有「先信任再校验」这种中间态。
+//   2. **tar 条目路径必须落在该包目录内**。registry 与本地 tarball 都是外来输入，`../` 这类
+//      路径遍历要在这里挡住 —— 这是信任边界上的校验，不是美化。
+//   3. **任何一步失败都清掉半份 payload**。结构检查只看必需包与入口，半份 payload 可能
+//      「看起来能用」，然后在 import 原生模块时才炸，错误现场离真正的原因很远。
+//
+// @module dsh-mneme/runtime/download
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { RUNTIME_MANIFEST_VERSION } from "./adopt.js";
+import { REQUIRED_PACKAGES, defaultRuntimeDir, detectLibc, nodeModulesDir, payloadDir, payloadId, runtimeManifestPath } from "./layout.js";
+import { matchesPlatform } from "./closure.js";
+import { stripPackagePrefix, verifyIntegrity, walkTgz } from "./tarball.js";
+
+const DEFAULT_ATTEMPTS = 3;
+// 单次请求的总超时。连接僵住（对端不回也不断）时，没有它就会永远等着 —— 用户看到的是一个
+// 卡死的按钮，而没有任何错误可看。给得宽松：几百 MB 的包在慢网下也要能下完。
+const DEFAULT_REQUEST_TIMEOUT_MS = 10 * 60 * 1000;
+
+/**
+ * 把 registry 地址换成镜像地址：只换前缀，保留 `/name/-/file.tgz` 这段路径。
+ * 换不了（不是 registry.npmjs.org 的地址）就原样返回 —— 清单里写死的地址优先。
+ * @param {string} url - 清单里的地址。
+ * @param {string} mirror - 镜像前缀，空 = 不换。
+ * @returns {string} 实际要取的地址。
+ */
+export function applyMirror(url, mirror) {
+  const base = String(mirror ?? "").trim().replace(/\/+$/, "");
+  if (base === "") return url;
+  // 只换 registry.npmjs.org 的地址：别的来源（自建 registry、file:、清单里已是镜像的地址）一律
+  // 原样返回。这里曾经用 indexOf(...) 直接加偏移量拼字符串 —— 地址里没有那个域名时 indexOf 返回
+  // -1，slice 出的是垃圾名字，把一条本来可用的地址改坏。
+  const prefix = "https://registry.npmjs.org/";
+  const marker = url.indexOf("/-/");
+  if (marker === -1 || !url.startsWith(prefix)) return url;
+  const name = url.slice(prefix.length, marker);
+  return name === "" ? url : `${base}/${name}${url.slice(marker)}`;
+}
+
+/**
+ * 本地 tarball 目录里的候选文件名。用 npm 的约定（`<basename>-<version>.tgz`），
+ * 这样 
+pm pack` 出来的东西直接丢进目录就能用，不需要改名字。
+ * @param {string} dir - 目录。
+ * @param {{name: string, version: string}} pkg - 包。
+ * @returns {string} 候选路径。
+ */
+export function localTarballPath(dir, pkg) {
+  const base = pkg.name.startsWith("@") ? pkg.name.slice(pkg.name.indexOf("/") + 1) : pkg.name;
+  return join(dir, `${base}-${pkg.version}.tgz`);
+}
+
+/**
+ * 取一个 .tgz 的字节。失败重试；已经收到部分字节时用 `Range` **续传**而不是从头再来
+ * —— 82MB 的 onnxruntime-node 在移动网络上重来一次的代价太大。
+ * @param {string} url - 地址。
+ * @param {object} [opts] - 选项。
+ * @returns {Promise<{buffer: Buffer, attempts: number, resumed: boolean}>}
+ */
+export async function fetchTarball(url, { attempts = DEFAULT_ATTEMPTS, fetchImpl = fetch, onProgress, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = {}) {
+  let lastError = null;
+  let chunks = [];
+  let received = 0;
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      const options = received > 0 ? { headers: { Range: `bytes=${received}-` } } : {};
+      // AbortSignal.timeout 是**总时长**上限，不是空闲超时：宁可给得宽松，也不要掐断正常的慢速下载。
+      if (Number.isFinite(timeoutMs) && timeoutMs > 0) options.signal = AbortSignal.timeout(timeoutMs);
+      const res = await fetchImpl(url, Object.keys(options).length > 0 ? options : undefined);
+      if (res.status === 206) {
+        // 续传被接受：已有字节保留，接着追加。
+      } else if (res.ok) {
+        // 服务端不支持续传（或首次请求）：从头来。
+        chunks = [];
+        received = 0;
+      } else {
+        throw new Error(`HTTP ${res.status}`);
+      }
+
+      if (res.body?.getReader === undefined) {
+        const whole = Buffer.from(await res.arrayBuffer());
+        // 206 的响应体只是**剩余**那段，必须追加；200 才是完整的一份 —— 覆盖会丢掉前半段，
+        // 于是 sha512 校验必挂（而这次失败看起来像「来源不可信」，与真实原因不符）。
+        if (res.status === 206) {
+          chunks.push(whole);
+          received += whole.length;
+        } else {
+          chunks = [whole];
+          received = whole.length;
+        }
+      } else {
+        const reader = res.body.getReader();
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          const chunk = Buffer.from(value);
+          chunks.push(chunk);
+          received += chunk.length;
+          // 事件带 type：同一个回调同时承载「字节级」与「包级」两种进度，不标类型调用方就只能猜。
+          onProgress?.({ type: "bytes", received, attempt });
+        }
+      }
+      return { buffer: Buffer.concat(chunks, received), attempts: attempt, resumed: attempt > 1 };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw new Error(`取件失败（试了 ${attempts} 次）：${lastError?.message ?? lastError}`);
+}
+
+/** 解一个 .tgz 到该包的目录里；条目路径必须落在目录内。 */
+function extractInto(buffer, pkgDir, skipped) {
+  const stats = { files: 0, bytes: 0 };
+  const guard = pkgDir.endsWith(sep) ? pkgDir : `${pkgDir}${sep}`;
+  const walked = walkTgz(buffer, (entry) => {
+    const target = join(pkgDir, stripPackagePrefix(entry.path));
+    // 越界即整次失败：把外来归档里的 ../ 写出去是不可接受的。
+    if (!target.startsWith(guard)) throw new Error(`归档里有越出包目录的路径：${entry.path}`);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, entry.data);
+    stats.files++;
+    stats.bytes += entry.data.length;
+  });
+  for (const item of walked.skipped) skipped.push(item);
+  return stats;
+}
+
+/**
+ * 按清单把运行时取回来并落盘（第二、三档来源）。
+ * @param {object} opts - 选项。
+ * @param {object} opts.manifest - runtime-manifest.json 的内容。
+ * @param {string} [opts.runtimeDir] - 运行时根目录。
+ * @param {string} [opts.localTarballDir] - 本地 .tgz 目录（有就用，优先于网络）。
+ * @param {string} [opts.mirror] - registry 镜像前缀。
+ * @param {boolean} [opts.overwrite] - 目标已存在时是否覆盖。
+ * @returns {Promise<object>} 与 adoptRuntime 同形的结果；失败时 ok=false 且带 reason，不抛。
+ */
+export async function downloadRuntime({
+  manifest,
+  platform = process.platform,
+  arch = process.arch,
+  libc = detectLibc(platform),
+  runtimeDir = defaultRuntimeDir(),
+  localTarballDir = "",
+  mirror = "",
+  overwrite = false,
+  attempts = DEFAULT_ATTEMPTS,
+  fetchImpl = fetch,
+  onProgress
+}) {
+  // v2 清单是**平台无关**的：里面是所有平台的包（各带 os / cpu / libc），这里按本机平台过滤。
+  // 这样一份随包发布的静态清单就覆盖 win32 / darwin / linux × x64 / arm64 —— 不需要
+  // 「谁在哪个系统上跑一次生成脚本」，也就不会让 macOS 用户卡在「清单里没有我的平台」。
+  const all = Array.isArray(manifest?.packages) ? manifest.packages : null;
+  if (all === null) return { ok: false, reason: "运行时清单不可用（缺少 packages 列表）" };
+
+  const wanted = all.filter((pkg) => matchesPlatform(pkg, platform, arch, libc));
+  const missingRequired = REQUIRED_PACKAGES.filter((name) => !wanted.some((pkg) => pkg.rel === name));
+  if (missingRequired.length > 0) {
+    // 目标平台在清单里就缺必需包时，现在失败好过装出一份「结构看着全、import 原生模块才炸」的
+    // 运行时 —— 那时错误现场离原因已经很远。
+    return { ok: false, reason: `清单里 ${platform}-${arch} 缺少必需包：${missingRequired.join("、")}` };
+  }
+
+  const id = payloadId({ version: manifest.transformersVersion, platform, arch });
+
+  const dir = payloadDir(runtimeDir, id);
+  if (existsSync(dir) && !overwrite) {
+    return {
+      ok: false,
+      reason: `目标已存在：${dir}（需要覆盖请传 overwrite: true）`,
+      payloadDir: dir,
+      payloadId: id
+    };
+  }
+  // 覆盖前先清空：否则上一次的残留文件会让结构检查看到「完整」，掩盖这一次的缺件。
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+
+  const totals = { packages: 0, files: 0, bytes: 0, fromLocal: 0, fromNetwork: 0 };
+  const warnings = [];
+  const packages = [];
+  const skipped = [];
+
+  try {
+    for (const pkg of wanted) {
+      const local = localTarballDir ? localTarballPath(localTarballDir, pkg) : "";
+      const useLocal = local !== "" && existsSync(local);
+      const url = applyMirror(pkg.tarball, mirror);
+      const buffer = useLocal ? readFileSync(local) : (await fetchTarball(url, { attempts, fetchImpl, onProgress })).buffer;
+      if (useLocal) totals.fromLocal++;
+      else totals.fromNetwork++;
+
+      if (!verifyIntegrity(buffer, pkg.integrity)) {
+        // 校验失败必须停在这里：写下去就等于把「来源不可信」变成「已装好」。
+        throw new Error(`${pkg.name}@${pkg.version} 的 sha512 与清单不符（来源：${useLocal ? local : url}）`);
+      }
+
+      const stats = extractInto(buffer, join(nodeModulesDir(dir), pkg.rel), skipped);
+      totals.files += stats.files;
+      totals.bytes += stats.bytes;
+      totals.packages++;
+      packages.push({ name: pkg.name, version: pkg.version, rel: pkg.rel, optional: pkg.optional === true });
+      onProgress?.({ type: "package", package: pkg.name, done: totals.packages, total: wanted.length });
+    }
+  } catch (error) {
+    // 半份 payload 比没有更糟：清掉，让「没装成」这件事在磁盘上也成立。
+    rmSync(dir, { recursive: true, force: true });
+    return { ok: false, reason: String(error?.message ?? error) };
+  }
+
+  const written = {
+    manifestVersion: RUNTIME_MANIFEST_VERSION,
+    payloadId: id,
+    entry: manifest.entry ?? "@huggingface/transformers",
+    version: manifest.transformersVersion,
+    platform,
+    arch,
+    procedure: "downloaded",
+    // 每个 tarball 都与清单里的 sha512 比对过 —— 这是下载档独有的、可如实声明的来源完整性。
+    integrity: { status: "verified", checked: packages.length, detail: "每个 tarball 的 sha512 与 runtime-manifest.json 一致" },
+    createdAt: new Date().toISOString(),
+    materialize: { mode: "download", linkError: null },
+    sources: { mirror: mirror || null, localTarballDir: localTarballDir || null, counts: { local: totals.fromLocal, network: totals.fromNetwork } },
+    packages,
+    gaps: [],
+    skipped,
+    warnings
+  };
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(runtimeManifestPath(dir), `${JSON.stringify(written, null, 2)}\n`, "utf8");
+  return {
+    ok: true,
+    payloadDir: dir,
+    payloadId: id,
+    version: manifest.transformersVersion,
+    totals,
+    manifest: written
+  };
+}