zipcalm 0.0.0-stage → 1.0.1

package/server/plugins/formats/rar/index.js

@@ -0,0 +1,354 @@
+// RAR 格式包（**只读：仅解压，不支持压缩**）
+//
+// 法律边界（docs/18 §附三）：RAR 的压缩算法是闭源商业算法，未经授权不能生成 RAR 文件；
+// 因此 `create()` / `estimate()` 一律拒绝，并在 `unavailableReason()` 里写明原因。
+// 解压走**用户已安装**的 unrar（优先）或 7z —— 调用外部程序合法，且**绝不把二进制打进仓库**。
+//
+// 复用的既有设施（不造第二套）：
+// - 条目安全：`_shared/entrySafety.js` 的 planTargets / writePlan（与 zip、tar 同一套 zip-slip 防护
+//   与「不覆盖同名」检查），外部程序先解到中转目录，再由这套代码做白名单判定后搬进目标目录
+// - 错误三态（P4）：MISSING_PASSWORD / BAD_PASSWORD / ARCHIVE_CORRUPTED，判定见 unrar.js 的 mapToolFailure
+//
+// 为什么先解到中转目录再搬：unrar 会按归档内的路径直接写盘，若归档里有 `../` 或绝对路径条目，
+// 外部程序可能写到目标目录之外。中转 + planTargets 才能保证"写之前先判定"。
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError } from '../../../lib/errors.js';
+import { planTargets, writePlan } from '../_shared/entrySafety.js';
+import { jsExtractTo, jsInspect, jsTest } from './js-engine.js';
+import { repairName } from '../_shared/nameRepair.js';
+import {
+  EXTRACT_TIMEOUT_MS,
+  LIST_TIMEOUT_MS,
+  hasEncryptionFlag,
+  mapToolFailure,
+  parseBareList,
+  parseTechnicalList,
+  resolveEngine,
+  resetProbeCache,
+  runCommand,
+} from './unrar.js';
+
+const FORMAT_ID = 'rar';
+
+/** 压缩侧的统一拒绝文案（法律边界，措辞不要弱化） */
+const CREATE_REFUSED = 'RAR 压缩算法为闭源商业算法，未授权不能生成 RAR 文件；本插件仅支持解压';
+
+/** 进度上报的最小间隔（解析外部程序输出时自己节流，避免每行都推一次） */
+const PROGRESS_INTERVAL_MS = 120;
+
+/** 当前引擎（三级回退：原生 unrar → node-unrar-js → 7z；具体见 unrar.js 的 resolveEngine） */
+function currentEngine() {
+  const engine = resolveEngine();
+  return engine.kind ? engine : null;
+}
+
+async function available() {
+  return currentEngine() !== null;
+}
+
+async function unavailableReason() {
+  const engine = resolveEngine();
+  if (engine.reason) {
+    return `RAR 解压不可用：${engine.reason}（请安装 unrar 7.x 以上，或用 ZC_UNRAR_BIN 指定路径）`;
+  }
+  if (engine.kind && engine.filenameSafe === false) {
+    // 能用但文件名不可靠：把话说清楚，别让用户以为是编码识别问题
+    return `当前 unrar 版本 ${engine.version || '未知'} 对 RAR5 中文文件名有已知 bug（解出会乱码），建议升级到 7.x 以上`;
+  }
+  return '未找到 unrar / node-unrar-js / 7z，无法解压 RAR（请安装 unrar，或用 ZC_UNRAR_BIN 指定路径）';
+}
+
+async function estimate() {
+  // 压缩侧不支持：抛错而不是返回 0，避免"预检通过然后建任务失败"
+  throw apiError(ERROR_CODES.UNSUPPORTED_FORMAT, CREATE_REFUSED);
+}
+
+async function create() {
+  throw apiError(ERROR_CODES.UNSUPPORTED_FORMAT, CREATE_REFUSED);
+}
+
+/** 7z 的技术列表（`-slt` 的 `Key = Value` 形式）——只在没有 unrar 时用到 */
+function parseSevenZipList(output) {
+  const entries = [];
+  let current = null;
+  for (const rawLine of String(output || '').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith('Path = ')) {
+      if (current && current.name) entries.push(current);
+      current = { name: line.slice(7), type: 'file', size: 0, compressedSize: 0 };
+      continue;
+    }
+    if (!current) continue;
+    if (line === 'Folder = +') current.type = 'dir';
+    const sizeMatch = line.match(/^Size = (\d+)/);
+    if (sizeMatch) current.size = Number(sizeMatch[1]);
+    const packedMatch = line.match(/^Packed Size = (\d+)/);
+    if (packedMatch) current.compressedSize = Number(packedMatch[1]);
+  }
+  if (current && current.name) entries.push(current);
+  // 7z 会把归档自身作为第一条列出来，去掉它
+  return entries.slice(1).map((entry) => ({
+    name: String(entry.name).replace(/\\/g, '/'),
+    type: entry.type,
+    size: entry.type === 'dir' ? 0 : entry.size,
+    compressedSize: entry.compressedSize,
+  }));
+}
+
+/**
+ * 读条目清单；同时判定是否加密。
+ * 解析失败（输出格式随版本变）→ 降级成 `lb` 裸名列表，**不报错**。
+ * @returns {Promise<{entries: Array, encrypted: boolean, degraded: boolean}>}
+ */
+async function inspectEntries(archivePath, engine) {
+  if (engine.kind === 'js') {
+    // js 引擎自己解析文件头（不走外部进程），错误已在适配层映射成契约错误码
+    return { ...(await jsInspect(archivePath)), degraded: false };
+  }
+  if (engine.kind === '7z') {
+    const outcome = await runCommand(engine.bin, ['l', '-slt', '-p-', archivePath], { timeoutMs: LIST_TIMEOUT_MS });
+    if (outcome.code !== 0) mapToolFailure(outcome, { hasPassword: false });
+    const entries = parseSevenZipList(outcome.stdout);
+    const encrypted = /Encrypted = \+/i.test(outcome.stdout);
+    return { entries, encrypted, degraded: false };
+  }
+
+  const technical = await runCommand(engine.bin, ['lt', '-p-', archivePath], { timeoutMs: LIST_TIMEOUT_MS });
+  if (technical.code !== 0) mapToolFailure(technical, { hasPassword: false });
+  const entries = parseTechnicalList(technical.stdout);
+  const encrypted = hasEncryptionFlag(technical.stdout);
+  if (entries.length > 0) return { entries, encrypted, degraded: false };
+
+  // 降级：只拿名字（大小未知 → 0）。宁可"信息少一点"，也不要因为解析不了就报错。
+  const bare = await runCommand(engine.bin, ['lb', '-p-', archivePath], { timeoutMs: LIST_TIMEOUT_MS });
+  if (bare.code !== 0) mapToolFailure(bare, { hasPassword: false });
+  return { entries: parseBareList(bare.stdout), encrypted, degraded: true };
+}
+
+async function list(archivePath) {
+  const engine = currentEngine();
+  if (!engine) throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, await unavailableReason());
+  const info = await inspectEntries(archivePath, engine);
+  const items = info.entries.map((entry) => ({
+    // 列表也要还原名字：前端"内含 N 个条目"与解压后的实际文件名必须一致
+    name: repairName(entry.name).name,
+    type: entry.type,
+    size: entry.size,
+    compressedSize: entry.compressedSize,
+  }));
+  // encrypted 必须透出：解压预检据此让前端弹密码框（P4 三态的第一道）
+  return { entries: items, count: items.length, truncated: false, encrypted: info.encrypted };
+}
+
+async function test(archivePath, options = {}) {
+  const engine = currentEngine();
+  if (!engine) throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, await unavailableReason());
+  const password = options && typeof options.password === 'string' ? options.password : '';
+  if (engine.kind === 'js') {
+    // js 没有独立 test API：完整解一遍到临时目录并核对条数/字节数（见 js-engine.js 的说明）
+    return jsTest(archivePath, { password });
+  }
+  const { entries } = await inspectEntries(archivePath, engine);
+  const args = ['t', password ? `-p${password}` : '-p-', archivePath];
+  const outcome = await runCommand(engine.bin, args, { timeoutMs: LIST_TIMEOUT_MS });
+  if (outcome.code !== 0) mapToolFailure(outcome, { hasPassword: Boolean(password) });
+  return {
+    ok: true,
+    checked: entries.filter((entry) => entry.type !== 'dir').length,
+    failures: [],
+    strategy: `${engine.kind}-test`,
+  };
+}
+
+/** 递归收集中转目录里的条目（符号链接一律不收：解压产物里不该有链接） */
+async function collectStaged(stagingDir) {
+  const collected = [];
+  const walk = async (dirAbs, relativePrefix) => {
+    const dirents = await fsp.readdir(dirAbs, { withFileTypes: true });
+    for (const dirent of dirents) {
+      const abs = path.join(dirAbs, dirent.name);
+      const relative = relativePrefix ? `${relativePrefix}/${dirent.name}` : dirent.name;
+      if (dirent.isSymbolicLink()) continue;
+      if (dirent.isDirectory()) {
+        collected.push({ name: `${relative}/`, isDir: true, size: 0, link: false, open: null });
+        await walk(abs, relative);
+        continue;
+      }
+      if (!dirent.isFile()) continue;
+      const stat = await fsp.lstat(abs).catch(() => null);
+      collected.push({
+        name: relative,
+        isDir: false,
+        size: stat ? stat.size : 0,
+        link: false,
+        open: () => fs.createReadStream(abs),
+      });
+    }
+  };
+  await walk(stagingDir, '');
+  return collected;
+}
+
+/**
+ * 阶段一（外部程序解到中转目录）的进度：解析 `Extracting  <name>  OK` 行 → **文件级**。
+ *
+ * 为什么 processedBytes 固定为 0：unrar 不报字节数（只给文件名与百分比），若这里按文件数
+ * 比例估算字节，阶段二搬移时 writePlan 会从 0 重新计数 → 进度会**倒退**。宁可这一阶段只给
+ * 文件名（"正在解第 N 个"），阶段二再给精确字节，保证整条进度流单调不减。
+ */
+function makeExtractReporter(onProgress, totalFiles) {
+  let processedFiles = 0;
+  let lastAt = 0;
+  const report = typeof onProgress === 'function' ? onProgress : () => {};
+  return (line) => {
+    // 真实输出形如 `Extracting  s2/a.txt      OK`；头部还有一行 `Extracting from <archive>` 要排除
+    if (/^Extracting\s+from\s+/i.test(line)) return;
+    const matched = line.match(/^Extracting\s+(.+)$/i);
+    if (!matched) return;
+    const name = matched[1].replace(/\s+\d+%\s*$/, '').replace(/\s+OK\s*$/i, '').trim();
+    if (!name) return;
+    processedFiles += 1;
+    const now = Date.now();
+    if (now - lastAt < PROGRESS_INTERVAL_MS) return;
+    lastAt = now;
+    report({ processedFiles, totalFiles, processedBytes: 0, currentFile: name });
+  };
+}
+
+async function extract(ctx) {
+  const engine = currentEngine();
+  if (!engine) throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, await unavailableReason());
+
+  const startedAt = Date.now();
+  const targetDir = path.resolve(ctx.targetDir);
+  const overwrite = Boolean(ctx.options && ctx.options.overwrite);
+  const password = ctx.options && typeof ctx.options.password === 'string' ? ctx.options.password : '';
+  const signal = ctx.options && ctx.options.signal;
+
+  // ⓪ 先读清单：既拿到文件数（进度分母/校验），也判定是否加密
+  const info = await inspectEntries(ctx.archivePath, engine);
+  if (info.encrypted && !password) {
+    throw apiError(ERROR_CODES.MISSING_PASSWORD, '该压缩包已加密，请输入密码');
+  }
+
+  // ① 解到目标目录**旁边**的中转目录（外部程序不直接写用户目录）
+  const stagingDir = path.join(path.dirname(targetDir), `.${path.basename(targetDir)}.hl-rar-${Date.now()}`);
+  await fsp.mkdir(stagingDir, { recursive: true });
+  try {
+    const fileCount = info.entries.filter((entry) => entry.type !== 'dir').length;
+    if (engine.kind === 'js') {
+      // js 引擎在进程内解析并落盘（Node fs，CIFS 上没问题），自带"少文件/少字节"的损坏检测
+      await jsExtractTo(ctx.archivePath, stagingDir, { password });
+    } else {
+      const args = ['x', '-o-', '-y', password ? `-p${password}` : '-p-', ctx.archivePath, `${stagingDir}/`];
+      const outcome = await runCommand(engine.bin, args, {
+        timeoutMs: EXTRACT_TIMEOUT_MS,
+        signal,
+        onLine: makeExtractReporter(ctx.onProgress, fileCount),
+      });
+      if (outcome.code !== 0) mapToolFailure(outcome, { hasPassword: Boolean(password) });
+    }
+
+    // ② 安全判定 + 搬进目标目录（zip-slip / 不覆盖同名 / 进度 / 半成品清理 都由这套共享代码负责）
+    const staged = await collectStaged(stagingDir);
+    const planned = await planTargets(staged, targetDir, overwrite);
+    const written = await writePlan(planned, targetDir, { signal, onProgress: ctx.onProgress });
+    return {
+      targetDir,
+      entries: written.entries,
+      namesDecoded: planned.repairedNames || 0,
+      bytesOut: written.bytesOut,
+      durationMs: Date.now() - startedAt,
+      encrypted: info.encrypted,
+    };
+  } finally {
+    // 中转目录无论成败都清掉（加密包的明文副本不留盘）
+    await fsp.rm(stagingDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+export { resetProbeCache };
+
+export default {
+  id: FORMAT_ID,
+  name: 'RAR（仅解压）',
+  ext: '.rar',
+  // RAR5 也走同一扩展名，没有别的别名
+  extAliases: [],
+  mime: 'application/vnd.rar',
+  // 压缩侧不可用：levelRange/defaultLevel 置空，前端压缩设置不该出现它
+  levelRange: null,
+  defaultLevel: null,
+  capabilities: [],
+  /** 只解压标记：压缩列表据此排除本格式（消费方见 README 的格式说明） */
+  extractOnly: true,
+  available,
+  unavailableReason,
+  estimate,
+  create,
+  extract,
+  list,
+  test,
+  /**
+   * 探测归档是否加密（供解压预检决定是否弹密码输入框）。
+   *
+   * 实现方式是复用列表阶段已经拿到的信息：`unrar lt` 的输出里每一条都带
+   * `* Encrypted = +` 标志，`7z -slt` 同理，所以不需要额外开一次进程去猜测。
+   * RAR 没有 ZIP 那种 AES/ZipCrypto 之分，`isAes` 恒为 false（保持与 ZIP 同构的返回形状）。
+   *
+   * @param {string} archivePath
+   * @returns {Promise<{encrypted: boolean, isAes: boolean}>}
+   */
+  async probeEncryption(archivePath) {
+    const engine = currentEngine();
+    if (!engine) throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, await unavailableReason());
+    const info = await inspectEntries(archivePath, engine);
+    return { encrypted: info.encrypted === true, isAes: false };
+  },
+  /**
+   * 用给定密码完整试解一次（供解压侧「先校验」阶段调用）。
+   *
+   * 为什么必须由本插件提供、而不是让编排层统一用 7z：
+   * p7zip 16.02 读不了加密 RAR5（实测报 `Can not open the file as archive`），
+   * 而本机 `unrar 5.70` 可以。工具能力按格式不同，这个知识属于插件自己。
+   *
+   * @param {string} archivePath
+   * @param {string} password
+   * @returns {Promise<{ok: boolean, checked?: number, strategy?: string, error?: string}>}
+   */
+  async verifyWithPassword(archivePath, password) {
+    try {
+      const result = await test(archivePath, { password });
+      return { ok: true, checked: result.checked, strategy: result.strategy };
+    } catch (error) {
+      // 保留原始错误码（BAD_PASSWORD / ARCHIVE_CORRUPTED / ABORTED），交给上层原样抛给用户。
+      // 如果在这里一律收敛成 VERIFY_FAILED，用户看到的就只是"校验未通过"，
+      // 分不清到底是密码打错了还是包坏了 —— 三态区分就白做了。
+      return {
+        ok: false,
+        code: (error && error.code) || null,
+        error: (error && error.message) || '加密包校验失败',
+      };
+    }
+  },
+  /**
+   * 诊断：当前用哪个引擎、版本多少、文件名是否可靠。
+   * 形如 `{kind:'unrar', bin:'/bin/unrar', version:'5.70', filenameSafe:false}`
+   * 或 `{kind:'js', bin:null, version:'2.0.2', filenameSafe:false}`。
+   */
+  probe: () => {
+    const engine = resolveEngine();
+    return {
+      kind: engine.kind,
+      bin: engine.bin,
+      version: engine.version,
+      filenameSafe: engine.filenameSafe,
+      jsPackage: engine.kind === 'js' ? 'node-unrar-js' : null,
+      reason: engine.reason,
+    };
+  },
+};

package/server/plugins/formats/rar/js-engine.js

@@ -0,0 +1,122 @@
+// RAR 的纯 JS/WASM 引擎适配（node-unrar-js）——**客户端侧**：只负责起子进程、解析信封、映射错误码
+//
+// 真正的解压在 `js-runner.mjs` 子进程里跑。原因（务必保留这段说明，别再改回同进程）：
+//   1) `node-unrar-js` 的 `extract()` 是**同步**的（返回 ArcFiles，不是 Promise）。
+//      在服务进程里直接调 → 解压期间事件循环停摆：SSE 不推进度、HTTP 全站无响应、取消按钮点不动。
+//   2) WASM 内存会占在服务进程里（7z 那边峰值 460MB 在子进程），WASM 崩了会带走整个服务。
+//   3) 同步执行无法取消 —— 子进程 + SIGKILL 是唯一可靠的超时/取消手段。
+//
+// CPU 纪律（绑核「总核数 − 1」+ nice + 全局串行）统一由 `server/core/engineRunner.js` 提供，与 7z 共用同一把锁。
+//
+// **实测能力边界（node-unrar-js@2.0.2，内置 unrar 6.1.7）**：
+//   ✅ rar4 / rar5、嵌套目录、纯 ASCII 文件名
+//   ✅ 多卷（给 part1 自动续卷）
+//   ✅ 加密包：正确密码可解；缺密码 → MISSING_PASSWORD；错密码 → BAD_PASSWORD
+//   ❌ **RAR5 中文名仍然乱码**（与 unrar 5.70 一致）→ 这一层**修不了文件名**，所以有原生 unrar 时仍优先原生
+//   ⚠️ 损坏包**不报错**：静默只解出部分文件（原生 unrar 会明确报 ARCHIVE_CORRUPTED）；
+//      这里用「解出条数/字节数 vs 清单」兜底，清单本身被截断时抓不到（已知限制）
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ERROR_CODES, apiError } from '../../../lib/errors.js';
+import { runEngineProcess } from '../../../core/engineRunner.js';
+
+const JS_PACKAGE = 'node-unrar-js';
+const RUNNER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'js-runner.mjs');
+
+const LIST_TIMEOUT_MS = 60 * 1000;
+const EXTRACT_TIMEOUT_MS = 30 * 60 * 1000;
+
+let loaded = null;
+
+/** 载入 node-unrar-js（只用于"能不能用"的探测与版本号；真正干活在子进程） */
+export function loadUnrarJs() {
+  if (loaded !== null) return loaded.module;
+  try {
+    loaded = { module: createRequire(import.meta.url)(JS_PACKAGE) };
+  } catch {
+    loaded = { module: null };
+  }
+  return loaded.module;
+}
+
+export function jsAvailable() {
+  return Boolean(loadUnrarJs());
+}
+
+export function jsVersion() {
+  if (!jsAvailable()) return null;
+  try {
+    return createRequire(import.meta.url)(`${JS_PACKAGE}/package.json`).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/** 错误码 → 契约错误（三态与原生 unrar 完全一致） */
+function throwMapped(errorCode, message, details) {
+  if (errorCode === 'MISSING_PASSWORD') throw apiError(ERROR_CODES.MISSING_PASSWORD, message || '该压缩包已加密，请输入密码');
+  if (errorCode === 'BAD_PASSWORD') throw apiError(ERROR_CODES.BAD_PASSWORD, message || '密码错误');
+  throw apiError(ERROR_CODES.ARCHIVE_CORRUPTED, message || '压缩包损坏', details);
+}
+
+/**
+ * 跑一次 js 引擎子进程。
+ * @param {{op: 'list'|'extract'|'test', archivePath: string, targetPath?: string, password?: string}} spec
+ * @param {{timeoutMs?: number, signal?: AbortSignal}} [options]
+ * @returns {Promise<object>} 信封内容
+ */
+export async function runJsEngine(spec, options = {}) {
+  if (!jsAvailable()) throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, 'node-unrar-js 不可用');
+  const timeoutMs = options.timeoutMs || (spec.op === 'list' ? LIST_TIMEOUT_MS : EXTRACT_TIMEOUT_MS);
+  // 测试用：允许把超时压到很小，验证"超时能被 SIGKILL 掉"
+  const overrideTimeout = Number(process.env.ZC_RAR_JS_TIMEOUT_MS);
+  const effectiveTimeout = Number.isInteger(overrideTimeout) && overrideTimeout > 0 ? overrideTimeout : timeoutMs;
+
+  const outcome = await runEngineProcess(
+    { command: process.execPath, args: [RUNNER, JSON.stringify(spec)], label: 'unrar-js' },
+    { timeoutMs: effectiveTimeout, signal: options.signal },
+  );
+
+  if (outcome.aborted) throw apiError(ERROR_CODES.ABORTED, '任务已取消');
+  if (outcome.timedOut) {
+    throw apiError(ERROR_CODES.INTERNAL_ERROR, 'RAR 解压超时（js 引擎未在限定时间内完成，已强制终止）');
+  }
+
+  const lastLine = String(outcome.stdout || '').trim().split(/\r?\n/).filter((line) => line.startsWith('{')).pop();
+  if (!lastLine) {
+    // 子进程崩了/没输出：任务失败即可，**服务不受影响**（这正是子进程化的收益）
+    throw apiError(ERROR_CODES.INTERNAL_ERROR, 'js 引擎异常退出（详见服务日志）', {
+      exitCode: outcome.code,
+      reason: String(outcome.stderr || '').slice(-120),
+    });
+  }
+  const envelope = JSON.parse(lastLine);
+  if (envelope.ok !== true) throwMapped(envelope.errorCode, envelope.message, { reason: envelope.reason });
+  return envelope;
+}
+
+/** 读清单（含是否加密） */
+export async function jsInspect(archivePath) {
+  const envelope = await runJsEngine({ op: 'list', archivePath });
+  return { entries: envelope.entries || [], encrypted: envelope.encrypted === true };
+}
+
+/** 校验：完整解一遍到临时目录（子进程自己清理），并核对条数/字节数 */
+export async function jsTest(archivePath, options = {}) {
+  const password = options && typeof options.password === 'string' ? options.password : '';
+  const envelope = await runJsEngine({ op: 'test', archivePath, ...(password ? { password } : {}) });
+  return { ok: true, checked: envelope.fileCount || 0, failures: [], strategy: 'unrar-js-extract' };
+}
+
+/** 解压到指定目录 */
+export async function jsExtractTo(archivePath, targetDir, options = {}) {
+  const password = options && typeof options.password === 'string' ? options.password : '';
+  const envelope = await runJsEngine(
+    { op: 'extract', archivePath, targetPath: targetDir, ...(password ? { password } : {}) },
+    { signal: options.signal },
+  );
+  return { fileCount: envelope.fileCount || 0, bytesOut: envelope.bytesOut || 0 };
+}

package/server/plugins/formats/rar/js-runner.mjs

@@ -0,0 +1,129 @@
+// RAR 的 js 引擎执行器（**子进程**，每次操作一个独立进程）
+//
+// 为什么必须子进程（不能像最初那样在服务进程里直接调）：
+//   1) `node-unrar-js` 的 `extract()` 是**同步**的（返回 ArcFiles，不是 Promise）。在服务进程里直接调
+//      = 解压期间 Node 事件循环停摆 → SSE 不推进度、全站 HTTP 无响应、任务取消按钮点不动。
+//   2) WASM 内存占在服务进程里（7z 那边峰值 460MB 在子进程），且 WASM 崩溃会**带走整个服务**。
+//   3) 同步执行无法取消；子进程 + SIGKILL 是唯一可靠的超时/取消手段。
+//
+// 协议（父进程 ↔ 本脚本）：
+//   入参：argv[2] = JSON spec
+//     { op: 'list'|'extract'|'test', archivePath, targetPath?, password? }
+//   出参：stdout **只打印一行 JSON** 结果信封；诊断/异常文本走 stderr。
+//     成功：{"ok":true, ...}
+//     失败：{"ok":false,"errorCode":"MISSING_PASSWORD|BAD_PASSWORD|ARCHIVE_CORRUPTED","message":"…"}
+
+import { createRequire } from 'node:module';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const spec = JSON.parse(process.argv[2] || '{}');
+
+/** 结果信封只走 stdout 一行，父进程按最后一行 JSON 解析 */
+function emitEnvelope(payload) {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+/** js 侧异常 → 契约错误码（与原生 unrar 的三态口径保持一致） */
+function classify(error) {
+  const reason = String((error && (error.reason || error.message)) || '');
+  if (/MISSING_PASSWORD/i.test(reason)) return { errorCode: 'MISSING_PASSWORD', message: '该压缩包已加密，请输入密码' };
+  if (/BAD_PASSWORD|WRONG_PASSWORD/i.test(reason)) {
+    return spec.password
+      ? { errorCode: 'BAD_PASSWORD', message: '密码错误' }
+      : { errorCode: 'MISSING_PASSWORD', message: '该压缩包已加密，请输入密码' };
+  }
+  return { errorCode: 'ARCHIVE_CORRUPTED', message: '压缩包损坏', reason: reason.slice(0, 80) };
+}
+
+function headerList(extractor) {
+  const listed = extractor.getFileList();
+  const container = Array.isArray(listed) ? listed[0] : listed;
+  return Array.from((container && container.fileHeaders) || []);
+}
+
+function toEntry(header) {
+  const name = String(header.name || '').replace(/\\/g, '/');
+  const isDir = Boolean(header.flags && header.flags.directory) || name.endsWith('/');
+  return {
+    name,
+    type: isDir ? 'dir' : 'file',
+    size: isDir ? 0 : Number(header.unpSize || 0),
+    compressedSize: Number(header.packSize || 0),
+    encrypted: Boolean(header.flags && header.flags.encrypted),
+  };
+}
+
+async function walkFiles(dirAbs, prefix = '') {
+  const out = [];
+  for (const dirent of await fsp.readdir(dirAbs, { withFileTypes: true }).catch(() => [])) {
+    const relative = prefix ? `${prefix}/${dirent.name}` : dirent.name;
+    if (dirent.isDirectory()) {
+      out.push(...await walkFiles(path.join(dirAbs, dirent.name), relative));
+      continue;
+    }
+    const stat = await fsp.lstat(path.join(dirAbs, dirent.name)).catch(() => null);
+    out.push({ name: relative, size: stat ? stat.size : 0 });
+  }
+  return out;
+}
+
+async function main() {
+  const lib = createRequire(import.meta.url)('node-unrar-js');
+
+  if (spec.op === 'list') {
+    const extractor = await lib.createExtractorFromFile({ filepath: spec.archivePath });
+    const entries = headerList(extractor).map(toEntry);
+    emitEnvelope({ ok: true, entries, encrypted: entries.some((entry) => entry.encrypted) });
+    return;
+  }
+
+  // extract / test 都要真正解一遍（js 没有独立的 test API）
+  const targetDir = spec.targetPath || (await fsp.mkdtemp(path.join(os.tmpdir(), 'zc-rarjs-')));
+  const ownTemp = !spec.targetPath;
+  try {
+    await fsp.mkdir(targetDir, { recursive: true });
+    const extractor = await lib.createExtractorFromFile({
+      filepath: spec.archivePath,
+      targetPath: targetDir,
+      ...(spec.password ? { password: spec.password } : {}),
+    });
+    const expected = headerList(extractor).map(toEntry).filter((entry) => entry.type === 'file');
+
+    // 关键：`files` 是**惰性迭代**，必须消费才会真正写盘（只调 extract() 不迭代 = 目标目录为空）
+    const result = extractor.extract();
+    let consumed = 0;
+    for (const item of result.files || []) {
+      if (item && item.fileHeader) consumed += 1;
+    }
+
+    const actual = await walkFiles(targetDir);
+    const actualBytes = actual.reduce((sum, item) => sum + item.size, 0);
+    const expectedBytes = expected.reduce((sum, item) => sum + item.size, 0);
+
+    // 损坏包在 js 侧不报错（静默少文件）：用「条数/字节数 vs 清单」兜底。
+    // 注意：清单本身被截断时这条也抓不到（已知限制，已记 docs/17 D-11）。
+    if (expected.length > 0 && (actual.length < expected.length || actualBytes < expectedBytes)) {
+      emitEnvelope({
+        ok: false,
+        errorCode: 'ARCHIVE_CORRUPTED',
+        message: '压缩包损坏',
+        expectedFiles: expected.length,
+        actualFiles: actual.length,
+      });
+      return;
+    }
+
+    emitEnvelope({ ok: true, fileCount: actual.length, bytesOut: actualBytes, consumed, targetDir });
+  } finally {
+    if (ownTemp) await fsp.rm(targetDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+main().catch((error) => {
+  const classified = classify(error);
+  process.stderr.write(`[rar-js-runner] ${(error && (error.reason || error.message)) || 'failed'}\n`);
+  emitEnvelope({ ok: false, ...classified });
+  process.exitCode = 0;
+});