modelstage 0.0.0-stage → 0.5.24

package/src/server/unpack/runtime/index.mjs

@@ -0,0 +1,141 @@
+// src/server/unpack/runtime/index.mjs —— 运行时适配器的选择器 + 安全门禁
+//
+// 为什么要有这一层：插件"用什么运行时"从一个硬编码事实（vm 沙盒）变成了清单里的一个字段
+//   （plugin.json 的 runtime）。上层（plugin-runner）只认这里的统一接口，不认识具体运行时。
+//
+// 统一接口（两种 runtime 必须同形，上层无感）：
+//   load(meta, ctx) → { ok: true, api } | { ok: false, error, code? }
+//   dispose()       → void（进程内沙盒是空操作；exec 通道将来要杀子进程）
+// 其中 api 需提供 canHandle(file) / resolve(file)，可选 explainReject(file) / estimateMemory。
+//
+// **安全门禁（本文件的核心职责）**：
+//   runtime:"node" 是"进程内沙盒"，行为与历史一致；runtime:"exec" 是"在你机器上跑一个陌生可执行文件"。
+//   两者安全模型完全不同，所以 exec **默认关闭**：必须用户在 config 里显式开启才允许装载。
+//   这不是"防君子"的软提示 —— 未开启时装载器会直接拒绝并给出可读原因（不是静默降级）。
+import fs from 'node:fs';
+import path from 'node:path';
+import nodeVm from './node-vm.mjs';
+import execRuntime from './exec.mjs';
+// 配置允许注释：用项目统一的 JSONC 解析器（与 config/plugins.json、resources.json 同一条路径）
+import { parseJsonc } from '../../../../tool/parse-jsonc.mjs';
+
+/** 缺省运行时：插件不写 runtime 时按历史行为走 vm 沙盒 */
+export const DEFAULT_RUNTIME = 'node';
+
+/** 已注册的适配器表（加新运行时只需在这里登记） */
+const ADAPTERS = new Map([
+  [nodeVm.runtime, nodeVm],
+  [execRuntime.runtime, execRuntime],
+]);
+
+/** 允许出现在清单里的 runtime 名（用于校验，不用于实例化） */
+export const KNOWN_RUNTIMES = [...ADAPTERS.keys()];
+
+/**
+ * 危险运行时的开关配置文件：与 config/plugins.json 同级，但**独立成文件**。
+ * 为什么独立：这个开关决定「是否允许插件在本机执行任意可执行文件」，
+ *   让它在部署时是一个显眼、可单独审计与回收的文件，而不是混在大配置里的一个布尔字段。
+ * 内容形如：{"allowExecRuntime": true}
+ */
+export const EXEC_PERMISSION_FILE = 'config/plugin-runtime.json';
+
+/**
+ * 读"是否允许 exec 运行时"。
+ *
+ * 判据顺序：
+ *   ① 环境变量 `MODELSTAGE_ALLOW_EXEC_PLUGINS=1`（部署期覆盖，便于容器化）
+ *   ② 配置文件 `<数据根>/config/plugin-runtime.json` 的 allowExecRuntime === true
+ *   ③ 都没有 ⇒ **false（默认关闭）**
+ * 任何读取/解析失败都按"未开启"处理（失败要保守，不能因为配置坏了就把门打开）。
+ *
+ * **数据根优先**（与 core/paths.mjs 的 configDir 同口径）：设了 MODELSTAGE_DATA_ROOT 的实例
+ *   （测试实例）读自己的配置，不设的（主实例）读项目根的配置。
+ *   早前只按项目根读 ⇒ 测试实例无法单独开关这个危险通道，只能改项目根，
+ *   而项目根那份主实例也在用 —— 等于"一开就两个实例全开"。
+ * @param {string} root 项目根
+ * @returns {{allowed: boolean, source: string, error?: string, file?: string}}
+ */
+export function readExecPermission(root) {
+  const fromEnv = process.env.MODELSTAGE_ALLOW_EXEC_PLUGINS;
+  if (fromEnv === '1' || String(fromEnv).toLowerCase() === 'true') {
+    return { allowed: true, source: 'env:MODELSTAGE_ALLOW_EXEC_PLUGINS' };
+  }
+  const dataRoot = (process.env.MODELSTAGE_DATA_ROOT || '').trim();
+  const base = dataRoot ? path.resolve(dataRoot) : String(root || '');
+  const file = path.join(base, EXEC_PERMISSION_FILE);
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    // 文件不存在是最常见的正常情况（默认关闭），不算错误
+    if (e && e.code === 'ENOENT') return { allowed: false, source: 'default', file };
+    return { allowed: false, source: 'default', error: `读取 ${EXEC_PERMISSION_FILE} 失败：${e.message}`, file };
+  }
+  try {
+    // 允许注释（与其他配置一致）；用项目统一的 JSONC 解析器，不另写一套
+    const cfg = parseJsonc(text, EXEC_PERMISSION_FILE);
+    if (cfg && cfg.allowExecRuntime === true) return { allowed: true, source: EXEC_PERMISSION_FILE, file };
+    return { allowed: false, source: EXEC_PERMISSION_FILE, file };
+  } catch (e) {
+    // 配置坏了按"未开启"：宁可插件用不了，也不要因为一个笔误把危险通道打开
+    return { allowed: false, source: EXEC_PERMISSION_FILE, error: `${EXEC_PERMISSION_FILE} 解析失败：${e.message}`, file };
+  }
+}
+
+/**
+ * 取某个插件该用的运行时名（缺省 node；非法值直接报错，不猜）。
+ * @param {object} meta 插件清单
+ * @returns {{ok: true, runtime: string} | {ok: false, error: string}}
+ */
+export function resolveRuntimeName(meta) {
+  const raw = meta && meta.runtime !== undefined && meta.runtime !== null ? String(meta.runtime) : '';
+  if (!raw) return { ok: true, runtime: DEFAULT_RUNTIME };
+  if (!ADAPTERS.has(raw)) {
+    return { ok: false, error: `未知 runtime："${raw}"（可用：${KNOWN_RUNTIMES.join(' / ')}）` };
+  }
+  return { ok: true, runtime: raw };
+}
+
+/**
+ * 按清单选适配器并装载插件（**唯一入口**，plugin-runner 只调这个）。
+ *
+ * 门禁顺序（先拦后装，任何一步不过都不进适配器）：
+ *   ① runtime 名合法？
+ *   ② exec ⇒ 用户是否显式开启？（未开启直接拒绝，给出怎么开）
+ *   ③ 交给对应适配器装载
+ * @param {object} meta 插件清单（含 id / files / runtime? / entry? / frameProtocol?）
+ * @param {{pluginsDir: string, root?: string, execAllowed?: {allowed:boolean, source:string}}} ctx
+ * @returns {{ok: boolean, api?: object, error?: string, code?: string, runtime: string}}
+ */
+export function loadWithRuntime(meta, ctx) {
+  const rn = resolveRuntimeName(meta);
+  if (!rn.ok) return { ok: false, runtime: DEFAULT_RUNTIME, error: rn.error, code: 'UNKNOWN_RUNTIME' };
+  const runtime = rn.runtime;
+
+  if (runtime === 'exec') {
+    // ctx.execAllowed 允许调用方（测试/上层）注入判定结果，避免这里自己再读一遍盘；
+    //   没注入时按默认门禁读配置
+    const gate = ctx && ctx.execAllowed ? ctx.execAllowed : readExecPermission(ctx && ctx.root);
+    if (!gate.allowed) {
+      return {
+        ok: false,
+        runtime,
+        code: 'EXEC_RUNTIME_DISABLED',
+        error: `插件「${meta && meta.id}」声明了 runtime:"exec"，但宿主**未开启**该通道，已拒绝装载。`
+          + `开启方式（二选一）：① 在 ${EXEC_PERMISSION_FILE} 写 {"allowExecRuntime": true}；`
+          + '② 设环境变量 MODELSTAGE_ALLOW_EXEC_PLUGINS=1。'
+          + '注意：exec 通道意味着该插件可以执行任意本地命令（读写你的文件、发起网络请求），'
+          + '只应对你信任的插件开启。',
+      };
+    }
+  }
+
+  const adapter = ADAPTERS.get(runtime);
+  const r = adapter.load(meta, ctx);
+  return { ...r, runtime };
+}
+
+/** 列出已注册运行时（诊断/自检用） */
+export function listRuntimes() {
+  return KNOWN_RUNTIMES.map((name) => ({ runtime: name }));
+}

package/src/server/unpack/runtime/node-vm.mjs

@@ -0,0 +1,111 @@
+// src/server/unpack/runtime/node-vm.mjs —— 「node」运行时适配器（原 plugin-runner 的 vm 沙盒）
+//
+// 职责：把一个纯 JS 的 classic-script 插件装进 vm 沙盒并跑起来，交出统一的 provider 接口。
+// 这段逻辑原本直接写在 plugin-runner.mjs 的 loadPlugin() 里；抽出来的唯一目的是让
+//   「插件用什么运行时」变成一个可选项（将来接 exec 通道），**行为一个字节都不变**。
+//
+// 三条硬约束（从原注释原样保留，都是踩过的坑）：
+//   1. **跨 realm 禁止 instanceof**：vm 里建出来的 Map/Blob 与宿主各有一套内置构造器，
+//      `instanceof Map` 恒 false、`Object.keys(map)` 恒空（Map 没有自有可枚举键）。
+//   2. **装载只做一次**：沙盒 0.9ms + lib 41ms + index.js 6.4ms（实测 58ms）；resolve 本体是秒级，
+//      真正重要的是别每次请求都重建沙盒（会重复 58ms + 丢掉插件内部的 profile 缓存）。
+//   3. **产物不复制**：见 plugin-runner 的 unpackBytes 注释。
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import zlib from 'node:zlib';
+import crypto from 'node:crypto';
+
+/** 本适配器能处理的 runtime 名（plugin.json 的 runtime 字段） */
+export const RUNTIME = 'node';
+
+/**
+ * 在 vm 沙盒里装载一个纯 JS 插件。
+ *
+ * 错误隔离：**绝不抛给上层** —— 一个插件语法错误/装不起来，只让它自己返回 {ok:false,error}，
+ *   其它插件与服务启动都不受影响（调用方按 ok 决定跳过）。
+ *
+ * @param {{files: string[], entry?: string|null}} meta 插件清单（files 是相对 plugins 目录的 POSIX 路径）
+ * @param {{pluginsDir: string}} ctx 主进程侧的路径上下文
+ * @returns {{ok: boolean, api?: object, error?: string}}
+ */
+export function loadPluginModule(meta, ctx) {
+  try {
+    const pluginsDir = ctx && ctx.pluginsDir;
+    if (!pluginsDir) throw new Error('node-vm 适配器缺少 pluginsDir');
+    const files = Array.isArray(meta && meta.files) ? meta.files : [];
+    if (!files.length) throw new Error('插件清单里没有 files[]（node 运行时需要按序加载的脚本清单）');
+
+    const sandbox = {
+      globalThis: {},
+      console,
+      TextEncoder,
+      TextDecoder,
+      Blob,
+      // node 侧不该建 blob URL：插件里有能力判断，真调到就是回归
+      URL: { createObjectURL: () => { throw new Error('node 侧不应调用 createObjectURL'); } },
+      AbortController,
+      // 插件会用 fetch 拉 profile；拿不到就走内置默认规则（与 17a 同口径）
+      fetch: () => Promise.resolve({ ok: false, status: 404, json: async () => ({}) }),
+      setTimeout, clearTimeout, setInterval, clearInterval,
+    };
+    sandbox.globalThis = sandbox;
+    vm.createContext(sandbox);
+    // 加载顺序完全取清单 files[]：lib 的先后 + 入口文件都在 plugin.json 里声明，
+    //   runner 不再维护一串写死的 lib 名（加插件/调顺序都不该改代码）
+    for (const rel of files) {
+      vm.runInContext(fs.readFileSync(path.join(pluginsDir, rel), 'utf8'), sandbox, { filename: rel });
+    }
+    const NS = sandbox.__ULB__;
+    // 清单里有 lib/ 的插件必须把能力挂到 __ULB__（manifest 与代码不一致时要响亮报错）；
+    //   没有 lib/ 的插件不建这个命名空间，跳过即可 —— 通用化后不能强制要求它存在
+    const hasLibDir = files.some((f) => f.includes('/lib/'));
+    if (hasLibDir && (!NS || !NS.bytes)) throw new Error('lib/bytes.js 未能挂载 __ULB__');
+    // 以下几块能力在浏览器由 DecompressionStream / 原生 API 提供，node 侧注入等价实现。
+    //   均按"插件是否建了该命名空间/该钩子"判空注入：别的插件不一定有 bytes/png。
+    if (NS && NS.bytes && typeof NS.bytes.setSha256 === 'function') {
+      NS.bytes.setSha256((u8) => crypto.createHash('sha256').update(u8).digest('hex'));
+    }
+    if (NS && NS.png) {
+      NS.png.setInflate((u8) => new Uint8Array(zlib.inflateSync(Buffer.from(u8))));
+      NS.png.setDeflate((u8) => new Uint8Array(zlib.deflateSync(Buffer.from(u8), { level: 6 })));
+      // 流式版：编码器按 64 行一块喂进来，这里不攒整张、不转 Buffer。
+      //   输出与一次性 deflateSync 逐字节相同（deflate 的切分不影响结果，只要不 flush）。
+      //   返回**片段数组**（不 concat）：编码器会把片段直接 set 进一次预分配的 PNG 缓冲，
+      //   多一次 concat 就是多一份 18MB。
+      NS.png.setDeflateStream(async (chunks) => {
+        const d = zlib.createDeflate({ level: 6 });
+        const out = [];
+        d.on('data', (c) => out.push(c));
+        const done = new Promise((res, rej) => { d.on('end', res); d.on('error', rej); });
+        for (const c of chunks) d.write(c);
+        d.end();
+        await done;
+        return out;
+      });
+    }
+    // 统一契约 __PLUGIN_API__；__ULB_NODE__ 是首版键名，保留兼容（老插件继续能装）
+    const api = sandbox.__PLUGIN_API__ || sandbox.__ULB_NODE__;
+    if (!api || typeof api.resolve !== 'function' || typeof api.canHandle !== 'function') {
+      throw new Error('插件未挂载 __PLUGIN_API__（或兼容键 __ULB_NODE__）的 resolve/canHandle');
+    }
+    return { ok: true, api };
+  } catch (e) {
+    // 只记原因、不抛：一个插件坏掉不能带走别的插件，也不能带走服务启动
+    return { ok: false, error: String((e && e.message) || e) };
+  }
+}
+
+/**
+ * node 运行时的适配器对象（统一接口，见 runtime/index.mjs）。
+ * node 运行时的插件是"进程内同步调用"，没有子进程要管，所以 dispose 是空操作。
+ */
+export default {
+  runtime: RUNTIME,
+  /** @param {object} meta @param {object} ctx */
+  load(meta, ctx) {
+    return loadPluginModule(meta, ctx);
+  },
+  /** 进程内沙盒，没有外部资源可释放（保留接口是为了两种 runtime 同形） */
+  dispose() { /* no-op */ },
+};

package/src/server/unpack/unpack-worker.mjs

@@ -0,0 +1,105 @@
+// server/unpack/unpack-worker.mjs —— 解包 worker（常驻、单实例）
+//
+// 搬进来的**整段**：读包 → vm 沙盒装载插件（复用 runtime/index.mjs 的 loadWithRuntime，
+//   由 plugin-runner 内部调用，这里不另写一份）→ 插件 resolve → 原子落盘 → 写 probe。
+//
+// 为什么落盘也搬进来：落盘是"23~39 个小文件写 SMB"，实测同样是阻塞源；只搬解压等于把一半
+//   的卡顿留在主线程。落盘后只回传**清单**（相对路径 + 字节数 + 指纹），不回传 files Buffer
+//   —— 那可能是几十 MB，postMessage 复制一份毫无必要。
+//
+// 内存口径：worker_threads 里 /proc/self 指向同一进程 ⇒ rssNow/recordMeasuredPeak 的口径
+//   与搬之前完全一致，测量代码一个字都没改（只是换了执行线程）。
+
+import { parentPort, workerData } from 'node:worker_threads';
+
+import { unpackFile, listProviderPlugins, ensurePlugin } from './plugin-runner.mjs';
+import { writeResult } from './write-result.mjs';
+import { createProbeStore } from './probe-store.mjs';
+import { rssNow } from './mem-probe.mjs';
+
+const rootDir = workerData && workerData.rootDir;
+if (!rootDir) throw new Error('unpack-worker: workerData.rootDir 必填');
+
+const probeStore = createProbeStore({ rootDir });
+// 非 Linux 兜底峰值（主线程那边是 counters.peakRss，worker 里各自维护一份；VmHWM 可用时用不到）
+let localPeak = 0;
+function sampleRss() {
+  const rss = process.memoryUsage().rss;
+  if (rss > localPeak) localPeak = rss;
+  return rss;
+}
+
+// ── 预热：把 provider 插件在**收到任何请求之前**装好 ─────────────────────────────
+// 为什么必须预热：插件 lib（16 个文件 + LZMA 解码器）的装载分配发生在本 worker 首次
+//   ensurePlugin 时（由 unpackFile 内部触发）。不预热，这份**一次性开销**会被算进第一个包的
+//   measuredPeakBytes —— 实测把锚点包 z46_2 从 136.7MB 顶到 232.6MB（+70%），而该值又被准入
+//   当"下限兜底"用 ⇒ 同样大小的包"有时过有时不过"，判据随"是不是第一个包"抖动。
+//   worker 常驻、插件本来就要装，预热顺便让第一次解包更快。
+// 失败不阻断：ensurePlugin 本身绝不抛（失败进 {ok:false,error}），这里只记 warn，
+//   后续 unpackFile 自己会再试 —— 预热的目的只是"移出测量窗口"，不是"保证装成功"。
+try {
+  for (const meta of listProviderPlugins()) {
+    const r = ensurePlugin(meta.id);
+    if (r && r.ok) continue;
+    console.warn(`[unpack-worker] 预热插件失败（不影响后续解包，届时会重试）：${meta.id} ${(r && r.error) || ''}`);
+  }
+} catch (e) {
+  console.warn(`[unpack-worker] 预热插件异常（不影响后续解包）：${(e && e.message) || e}`);
+}
+
+parentPort.on('message', async (msg) => {
+  const { id, rootId, rel, absPath, fp, meta, decl } = msg || {};
+  try {
+    const before = rssNow(localPeak);
+    // 进度是**跨线程**的：主线程没法把回调函数传进来（structured clone 不支持函数），
+    //   所以这里把插件上报的进度原样 postMessage 出去，由 worker-client 转成回调。
+    //   发送失败（通道已关）只丢这一帧，绝不影响解包本身。
+    const res = await unpackFile({
+      rootId, rel, absPath,
+      onProgress: (progress) => {
+        try {
+          parentPort.postMessage({ id, progress });
+        } catch { /* 主线程已断开：进度丢掉即可 */ }
+      },
+    });
+    if (!res.ok) {
+      parentPort.postMessage({ id, ok: false, reason: res.reason, message: res.message });
+      return;
+    }
+    const tWrite0 = Date.now();
+    // pluginId 必须记「**真正解出产物的那个**插件」：store 传进来的 meta.pluginId 来自 runnerInfo()，
+    //   它恒为**列表第一个**注册插件（多插件环境下常与真正命中的不是同一个）⇒ 与 prefix 自相矛盾
+    //   （prefix 是 picked.id 算出来的，而 index.json 却记了别人，prefix 校验因此 25/25 报不一致）。
+    //   这里用 unpackFile 回传的 picked.id 覆盖，不再多写一次盘（方案 B 才需要回写）。
+    const { index } = await writeResult({
+      rootDir,
+      fp,
+      res,
+      meta: { ...meta, pluginId: res.pluginId || meta.pluginId },
+      probeStore,
+      sampleRss,
+    });
+    const writeMs = Date.now() - tWrite0;
+    const after = rssNow(localPeak);
+    // **顺序不变**：recordMeasuredPeak 必须在 writeResult 之后 ——
+    //   它会在 <fp>/ 下 mkdir + 写 probe.json；若在 rename 之前写，目标目录非空 ⇒ rename 报 ENOTEMPTY。
+    const tProbe0 = Date.now();
+    probeStore.recordMeasuredPeak(fp, before, after, decl);
+    const probeMs = Date.now() - tProbe0;
+    parentPort.postMessage({
+      id,
+      ok: true,
+      index,
+      prefix: res.prefix,
+      entry: res.entry,
+      unpackMs: res.unpackMs,
+      readMs: res.readMs,
+      writeMs,
+      probeMs,
+      measured: { before, after },
+    });
+  } catch (e) {
+    // 落盘/装载抛错：如实回传，主线程据此走原有的失败分支（计数、日志、返回 HTTP）
+    parentPort.postMessage({ id, ok: false, reason: 'worker-error', message: String((e && e.message) || e) });
+  }
+});

package/src/server/unpack/worker-client.mjs

@@ -0,0 +1,184 @@
+// server/unpack/worker-client.mjs —— 主线程侧的 worker 句柄（常驻 1 个、串行、可自愈）
+//
+// 三条职责，都很窄：
+//   ① 常驻复用：Node 起 worker 有几十 ms 开销，而解包本身秒级；每次新建还会让 vm 沙盒/插件
+//      lib 重新装载一遍。这里只在"没句柄"时建，进程内一直复用。
+//   ② 串行：内部一条 promise 链 —— worker 是单线程，同时 post 两条只会排队；显式串行让
+//      "第二个请求在等第一个"这件事在代码里可读，也与上层 store 的 enqueue 语义一致（不并行解包，
+//      并行会把进程内存峰值顶穿）。
+//   ③ 自愈：卡死（硬超时）或崩溃（error/exit）都要把本次请求变成**可读错误**、把句柄置空，
+//      下一次 run 自动重建 —— 绝不能让一个死掉的 worker 把队列永久堵住。
+//
+// 硬超时语义（写死在注释里，避免被误读成"包太大被拒"）：
+//   120s 只用于**防死循环把队列永久堵住**，不是"约束合法解包"。
+//   锚点包（azurlane_bundle/live2d/z46_2，解压 33.4MB 的 LZMA）实测墙钟 17.83s、unpackMs 9416ms，
+//   120s 有 6.7 倍余量 —— 正常解包一辈子不该触发它。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { Worker } from 'node:worker_threads';
+
+const WORKER_URL = new URL('./unpack-worker.mjs', import.meta.url);
+
+/**
+ * @param {{
+ *   rootDir: string,
+ *   timeoutMs?: number,
+ *   log?: (level: string, message: string, extra?: object) => void,
+ * }} opts
+ */
+export function createUnpackWorkerClient(opts) {
+  const rootDir = opts && opts.rootDir;
+  if (!rootDir) throw new Error('createUnpackWorkerClient: rootDir 必填');
+  const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : 120000;
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+
+  /** @type {Worker|null} */
+  let worker = null;
+  let seq = 0;
+  /** @type {{id:number, resolve:Function, reject:Function, timer:any}|null} */
+  let current = null;
+  /** 内部串行链：保证同一时刻只有一条任务在 worker 里 */
+  let chain = Promise.resolve();
+
+  /** 只清理该 fp 自己的临时目录（writeResult 的命名规则），不扫整个 rootDir */
+  function cleanupTmp(fp) {
+    try {
+      const prefix = `.tmp-${fp}-`;
+      for (const name of fs.readdirSync(rootDir)) {
+        if (!name.startsWith(prefix)) continue;
+        const full = path.join(rootDir, name);
+        try {
+          fs.rmSync(full, { recursive: true, force: true });
+          log('warn', `清理解包临时目录：${full}（上次 worker 被终止，产物未完成）`);
+        } catch (e) {
+          // 清理是尽力而为：失败只记日志，不许影响本次请求的错误返回
+          log('warn', `清理临时目录失败：${full}（${(e && e.message) || e}）`);
+        }
+      }
+    } catch (e) {
+      log('warn', `扫描临时目录失败：${(e && e.message) || e}`);
+    }
+  }
+
+  function onMessage(msg) {
+    const cur = current;
+    if (!cur || !msg || msg.id !== cur.id) return;   // 迟到/陌生消息：忽略（重建后可能收到旧 id）
+    // 进度消息：**不终结请求** —— worker 后面还会发真正的回复（契约 §四·⑦）。
+    //   所以这里 early return，绝不能落到下面的 clearTimeout + resolve。
+    if (msg.progress) {
+      if (typeof cur.onProgress === 'function') {
+        try {
+          cur.onProgress(msg.progress);
+        } catch (e) {
+          // 进度是旁路信息：回调抛错不能影响本次解包
+          log('warn', `进度回调抛错（已忽略）：${(e && e.message) || e}`);
+        }
+      }
+      return;
+    }
+    clearTimeout(cur.timer);
+    current = null;
+    cur.resolve(msg);
+  }
+
+  /** 该 worker 上的所有等待都失败（崩溃/退出路径） */
+  function failCurrent(reason, detail) {
+    const cur = current;
+    if (!cur) return;
+    clearTimeout(cur.timer);
+    current = null;
+    cur.reject(new Error(`${reason}：${detail}`));
+  }
+
+  function disposeWorker(reason) {
+    const w = worker;
+    worker = null;
+    if (!w) return Promise.resolve();
+    // 先把句柄置空再 terminate：exit 回调据此判断"是我们主动丢掉的"（见 ensureWorker 的 exit）
+    return w.terminate().catch(() => undefined);
+  }
+
+  function ensureWorker() {
+    if (worker) return worker;
+    const w = new Worker(WORKER_URL, { workerData: { rootDir } });
+    w.on('message', onMessage);
+    w.on('error', (e) => {
+      // worker 自己抛未捕获异常 ⇒ 该次请求 reject、句柄置空、下次重建
+      failCurrent('unpack worker crashed', (e && e.message) || e);
+      worker = null;
+    });
+    w.on('exit', (code) => {
+      // 只有"它仍是当前句柄"才算意外退出：超时/close 路径会先把 worker 置空再 terminate，
+      //   所以这里判断句柄归属比维护一个全局 terminating 标志更硬 —— 不依赖 exit 与 finally 的先后。
+      const wasCurrent = worker === w;
+      if (wasCurrent) worker = null;
+      if (!wasCurrent) return;
+      if (code !== 0) {
+        failCurrent('unpack worker exited unexpectedly', `exit code ${code}`);
+        log('warn', `解包 worker 异常退出（code ${code}），已丢弃句柄，下次请求将重建`);
+      }
+    });
+    worker = w;
+    return w;
+  }
+
+  /**
+   * 跑一次解包。串行：前一个没完成时，调用方会在这条链上等待。
+   * @param {object} task {rootId, rel, absPath, fp, meta, decl}
+   * @param {{onProgress?: (p: {phase: string, ms: number|null}) => void}} [opts]
+   *   onProgress：worker 线程里 exec 插件上报的进度帧会转成这个回调（可选）。
+   *   为什么要回调而不是靠返回值：进度必须**边跑边报**，等 run() 回来就已经晚了。
+   * @returns {Promise<object>} worker 的回复（ok:true 带 index，ok:false 带 reason/message）
+   */
+  function run(task, opts = {}) {
+    const go = () => new Promise((resolve, reject) => {
+      const w = ensureWorker();
+      const id = (seq += 1);
+      const fp = task.fp;
+      const timer = setTimeout(() => {
+        if (!current || current.id !== id) return;
+        const waitedMs = timeoutMs;
+        current = null;
+        log('warn',
+          `解包 worker 超时：${task.rootId}/${task.rel} 已等待 ${waitedMs}ms，正在终止并重建 worker`,
+          { rootId: task.rootId, rel: task.rel, waitedMs });
+        // 先置空句柄再 terminate：exit 回调据"句柄已不是它"判定为主动丢弃，不会再去 reject 已 reject 的请求
+        const dead = worker;
+        worker = null;
+        Promise.resolve(dead && dead.terminate && dead.terminate()).catch(() => undefined);
+        // 清理该 fp 的残留临时目录（writeResult 的 .tmp-<fp>-* 命名规则）
+        cleanupTmp(fp);
+        reject(new Error(`unpack worker timeout after ${timeoutMs}ms（本次解包未完成，已终止并重建 worker）`));
+      }, timeoutMs);
+      current = { id, resolve, reject, timer, onProgress: typeof opts.onProgress === 'function' ? opts.onProgress : null };
+      try {
+        w.postMessage({
+          id,
+          rootId: task.rootId,
+          rel: task.rel,
+          absPath: task.absPath,
+          fp,
+          meta: task.meta,
+          decl: task.decl,
+        });
+      } catch (e) {
+        clearTimeout(timer);
+        current = null;
+        reject(e);
+      }
+    });
+    const next = chain.then(go, go);
+    chain = next.then(() => undefined, () => undefined);
+    return next;
+  }
+
+  /** 关掉 worker（进程退出/测试清理用） */
+  async function close() {
+    await disposeWorker('close');
+  }
+
+  return { run, close, get worker() { return worker; } };
+}
+
+export default createUnpackWorkerClient;

package/src/server/unpack/write-result.mjs

@@ -0,0 +1,84 @@
+// server/unpack/write-result.mjs —— 把一次解包结果**原子落盘**
+//
+// 从 plugin-store.mjs 搬出来的唯一实现（主线程那份已删除）：worker 里解完直接落盘，
+//   只把清单回传主线程（几十 MB 的 files Buffer 不过 postMessage）。
+//
+// 原子性靠"同卷 rename"：先全写进 `.tmp-<fp>-<pid>-<rand>/`，再 rename 成 `<rootDir>/<fp>/`。
+//   rename 前要先取走 probe.json、删掉旧目录再 rename（POSIX rename 到非空目录报 ENOTEMPTY），
+//   然后把 probe 写回 —— 否则"重新解包"会把历史内存实测值一起丢掉。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/** 建目录（递归；已存在不报错） */
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * 把一次解包结果原子落盘。**失败一律清掉半成品临时目录**。
+ * @param {{
+ *   rootDir: string,            解包缓存根
+ *   fp: string,                 指纹（目录名）
+ *   res: object,                unpackFile 的返回（含 files 视图 / prefix / entry / unpackMs）
+ *   meta: object,               写进 index.json 的源信息（rootId/rel/size/mtimeMs/pluginId/pluginVersion）
+ *   probeStore: object,         createProbeStore(...) 的实例（取走/写回 probe）
+ *   sampleRss?: Function,       采样回调（可选；只要统计不影响正确性）
+ * }} args
+ * @returns {Promise<{index: object, files: Array<{path:string,size:number}>}>}
+ */
+export async function writeResult({ rootDir, fp, res, meta, probeStore, sampleRss }) {
+  const tmpDir = path.join(rootDir, `.tmp-${fp}-${process.pid}-${crypto.randomBytes(3).toString('hex')}`);
+  const fpDir = path.join(rootDir, fp);
+  ensureDir(path.join(tmpDir, 'files'));
+  const files = [];
+  try {
+    for (const { path: relPath } of res.files.entries) {
+      const bytes = await res.files.take(relPath);
+      if (!bytes) continue;
+      const dst = path.join(tmpDir, 'files', relPath);
+      ensureDir(path.dirname(dst));
+      fs.writeFileSync(dst, bytes);
+      files.push({ path: relPath, size: bytes.length });
+      // 写完立刻从沙盒 Map 里删掉引用（42MB 包 RSS 增量约 210MB，逐个释放能显著削峰）
+      res.files.release(relPath);
+      if (typeof sampleRss === 'function') sampleRss();
+    }
+    const now = new Date().toISOString();
+    const index = {
+      v: 1,
+      fingerprint: fp,
+      pluginId: meta.pluginId,
+      pluginVersion: meta.pluginVersion,
+      source: { rootId: meta.rootId, rel: meta.rel, size: meta.size, mtimeMs: Math.round(meta.mtimeMs) },
+      prefix: res.prefix,
+      entry: res.entry,
+      files,
+      createdAt: now,
+      lastUsedAt: now,
+      unpackMs: res.unpackMs,
+    };
+    fs.writeFileSync(path.join(tmpDir, 'index.json'), JSON.stringify(index, null, 2), 'utf8');
+    // 同卷 rename：原子替换，读者要么看到旧目录要么看到新目录。
+    // 目标目录已存在时 POSIX rename 会报 ENOTEMPTY（旧实现直接失败 ⇒
+    //   "files 缺失要重新解包"这条恢复路径其实一直不可用）。这里先取走 probe 缓存、
+    //   删掉旧目录再 rename，然后把缓存写回，避免重新解包把内存实测值一起丢掉。
+    const keepProbe = probeStore ? probeStore.read(fp) : null;
+    try {
+      fs.renameSync(tmpDir, fpDir);
+    } catch (e) {
+      if (e && (e.code === 'ENOTEMPTY' || e.code === 'EEXIST' || e.code === 'EPERM')) {
+        fs.rmSync(fpDir, { recursive: true, force: true });
+        fs.renameSync(tmpDir, fpDir);
+        if (keepProbe) probeStore.write(fp, keepProbe);
+      } else throw e;
+    }
+    return { index, files };
+  } catch (e) {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* 清理失败不影响主流程 */ }
+    throw e;
+  }
+}
+
+export default writeResult;