zipcalm 0.0.0-stage → 1.0.2

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

@@ -0,0 +1,266 @@
+// RAR 外部解压工具封装（unrar 优先，7z 兜底）
+//
+// 为什么必须走外部二进制：RAR 的压缩算法是闭源商业算法，Node 生态没有合规实现。
+// **绝不把 rar/unrar 打进项目或仓库**（docs/18 §附三法律边界）；调用用户已安装的程序是合法的。
+//
+// 实测结论（UNRAR 5.70 / p7zip 16.02）：
+// - `unrar lt` 是机器可读的技术列表（Name / Type / Size / Packed size / Flags: encrypted）
+// - 缺密码与错密码在 unrar 侧**同为 exit 11 + 同一句提示**，无法从输出区分 —— 只能由调用方
+//   根据"我们有没有传密码"来判定 MISSING_PASSWORD / BAD_PASSWORD（三态口径见 P4）
+// - 损坏包 exit 1（"Unexpected end of archive" / "Total errors: N"）
+// - p7zip 16.02 对 rar5 返回 exit 2（实测），所以 **unrar 是唯一可靠后端**，7z 仅作兜底
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+
+import { ERROR_CODES, apiError } from '../../../lib/errors.js';
+import { runEngineProcess } from '../../../core/engineRunner.js';
+import { jsAvailable, jsVersion } from './js-engine.js';
+
+/** 二进制探测结果缓存 60s（与格式注册表的可用性缓存同频，装了工具最多一分钟就该亮起来） */
+const PROBE_TTL_MS = 60 * 1000;
+let probeCache = null;
+
+/** 单次命令超时：列表/校验给 60s，解压给 30min（大包慢盘） */
+export const LIST_TIMEOUT_MS = 60 * 1000;
+export const EXTRACT_TIMEOUT_MS = 30 * 60 * 1000;
+
+/** 候选路径：环境变量优先，其次常见安装位置（禁止写死单一绝对路径） */
+/**
+ * 候选二进制。
+ *
+ * `ZC_UNRAR_BIN` / `ZC_7Z_BIN` **设了就独占**（不是"优先再回落"）：语义是"我明确指定用哪个二进制"，
+ * 指到不可执行的文件说明部署配错，应当如实报不可用并让人去修，而不是悄悄换另一个
+ * （那样运维看不出自己配错，回退链也测不出来）。与 7z 的 `ZC_7Z_BIN` 同规则。
+ */
+function candidatesOf(kind) {
+  const envValue = kind === 'unrar' ? process.env.ZC_UNRAR_BIN : process.env.ZC_7Z_BIN;
+  if (typeof envValue === 'string' && envValue.length > 0) return [envValue];
+  return kind === 'unrar'
+    ? ['/bin/unrar', '/usr/bin/unrar', '/usr/local/bin/unrar']
+    : ['/bin/7z', '/usr/bin/7z', '/usr/local/bin/7z'];
+}
+
+/** 可执行文件判定：必须存在且真的能执行（只看存在会把坏链接/无执行位当可用） */
+function isExecutable(candidate) {
+  try {
+    fs.accessSync(candidate, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 探测可用后端。
+ * @returns {{unrar: string|null, sevenZip: string|null}}
+ */
+export function resolveTools() {
+  const now = Date.now();
+  if (probeCache && now - probeCache.at < PROBE_TTL_MS) return probeCache.tools;
+  const tools = {
+    unrar: candidatesOf('unrar').find(isExecutable) || null,
+    sevenZip: candidatesOf('sevenZip').find(isExecutable) || null,
+  };
+  probeCache = { at: now, tools };
+  return tools;
+}
+
+/** 测试用：清掉探测缓存（换了环境变量后不必等 60s） */
+export function resetProbeCache() {
+  probeCache = null;
+}
+
+/**
+ * 运行外部命令，按行回调（用于进度解析）。
+ * @param {string} bin
+ * @param {string[]} args
+ * @param {{timeoutMs?: number, onLine?: (line: string) => void, signal?: AbortSignal}} [options]
+ * @returns {Promise<{code: number, stdout: string, stderr: string, timedOut: boolean, aborted: boolean}>}
+ */
+export function runCommand(bin, args, options = {}) {
+  // 绑核 / nice / 全局串行 / 超时硬杀 / 取消：统一由 core/engineRunner.js 处理（与 7z 共用一把锁）
+  return runEngineProcess({
+    command: bin,
+    args,
+    // **必须**强制 UTF-8 locale：默认 locale 与 C.UTF-8 都会让 unrar 输出有损的 `?`（不可还原），
+    // 只有 en_US.UTF-8 / zh_CN.UTF-8 才输出可逆的 PUA 转义（详见 _shared/nameRepair.js 头注释）
+    env: { LANG: 'en_US.UTF-8', LC_ALL: 'en_US.UTF-8' },
+    timeoutMs: options.timeoutMs || LIST_TIMEOUT_MS,
+    onLine: options.onLine,
+    signal: options.signal,
+    label: 'unrar',
+  });
+}
+
+/** 是否加密：`lt` 的条目块里出现 `Flags: encrypted` */
+export function hasEncryptionFlag(ltOutput) {
+  return /Flags:.*encrypted/i.test(String(ltOutput || ''));
+}
+
+/**
+ * 解析 `unrar lt` 的技术列表。
+ * 输出随版本变化 → 解析不出来就返回空数组，由调用方降级到 `lb`（裸名列表），**不报错**。
+ * @returns {Array<{name: string, type: 'dir'|'file', size: number, compressedSize: number}>}
+ */
+export function parseTechnicalList(ltOutput) {
+  const entries = [];
+  let current = null;
+  for (const rawLine of String(ltOutput || '').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const nameMatch = line.match(/^Name:\s*(.+)$/);
+    if (nameMatch) {
+      if (current && current.name) entries.push(current);
+      current = { name: nameMatch[1], type: 'file', size: 0, compressedSize: 0 };
+      continue;
+    }
+    if (!current) continue;
+    const typeMatch = line.match(/^Type:\s*(\S+)/);
+    if (typeMatch) {
+      current.type = /dir/i.test(typeMatch[1]) ? 'dir' : 'file';
+      continue;
+    }
+    const sizeMatch = line.match(/^Size:\s*(\d+)/);
+    if (sizeMatch) {
+      current.size = Number(sizeMatch[1]);
+      continue;
+    }
+    const packedMatch = line.match(/^Packed size:\s*(\d+)/);
+    if (packedMatch) current.compressedSize = Number(packedMatch[1]);
+  }
+  if (current && current.name) entries.push(current);
+  return entries.map((entry) => ({
+    // 归档内路径统一成 POSIX：RAR 可能用反斜杠（Windows 打的包）
+    name: String(entry.name).replace(/\\/g, '/'),
+    type: entry.type,
+    size: entry.type === 'dir' ? 0 : entry.size,
+    compressedSize: entry.compressedSize,
+  }));
+}
+
+/** `lb` 裸名列表（解析降级路径）：只有名字，大小未知 */
+export function parseBareList(lbOutput) {
+  return String(lbOutput || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      const name = line.replace(/\\/g, '/');
+      return { name, type: name.endsWith('/') ? 'dir' : 'file', size: 0, compressedSize: 0 };
+    });
+}
+
+/**
+ * 把 unrar/7z 的失败翻译成契约错误码（**四种情况不能混用**）。
+ * @param {{stderr: string, stdout: string, code: number, timedOut?: boolean, aborted?: boolean}} outcome
+ * @param {{hasPassword: boolean}} context
+ */
+export function mapToolFailure(outcome, context) {
+  if (outcome.aborted) throw apiError(ERROR_CODES.ABORTED, '任务已取消');
+  if (outcome.timedOut) {
+    throw apiError(ERROR_CODES.INTERNAL_ERROR, 'RAR 解压超时（外部程序未在限定时间内完成）');
+  }
+  const text = `${outcome.stdout}\n${outcome.stderr}`;
+  // 密码相关：unrar 对"没给密码"和"密码给错"都是同一句提示，只能靠我们是否传了密码来判定
+  if (/password/i.test(text)) {
+    if (!context.hasPassword) throw apiError(ERROR_CODES.MISSING_PASSWORD, '该压缩包已加密，请输入密码');
+    throw apiError(ERROR_CODES.BAD_PASSWORD, '密码错误');
+  }
+  if (/cannot open|No such file|is not RAR archive|Unexpected end|corrupt|CRC failed|checksum/i.test(text)) {
+    throw apiError(ERROR_CODES.ARCHIVE_CORRUPTED, '压缩包损坏');
+  }
+  throw apiError(ERROR_CODES.ARCHIVE_CORRUPTED, '压缩包损坏', {
+    exitCode: outcome.code,
+    detail: text.trim().split(/\r?\n/).slice(-2).join(' / ').slice(0, 200),
+  });
+}
+
+/** 是否存在可用的后端（unrar 优先） */
+export function pickBinaries() {
+  const tools = resolveTools();
+  return { unrar: tools.unrar, sevenZip: tools.sevenZip };
+}
+
+/** 同步探测版本（供 /formats 的 unavailableReason 附带线索；失败返回 null） */
+export function probeUnrarVersion(bin) {
+  try {
+    const output = execFileSync(bin, [], { encoding: 'utf8', timeout: 5000 });
+    const matched = String(output).match(/UNRAR\s+([\d.]+)/i);
+    return matched ? matched[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 版本号比较（只比较数字段，缺位按 0 算）：a<b 返回 -1，相等 0，a>b 返回 1 */
+export function compareVersion(a, b) {
+  const left = String(a || '0').split('.').map((part) => Number.parseInt(part, 10) || 0);
+  const right = String(b || '0').split('.').map((part) => Number.parseInt(part, 10) || 0);
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const diff = (left[index] || 0) - (right[index] || 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * 「文件名是否可靠」的版本阈值。
+ *
+ * 实测依据（同一份 RAR5 中文名样本 `scripts/fixtures/rar/s7-chinese.rar`）：
+ *   unrar 5.70（DSM 自带）→ `s7/????????????????.txt` / 落盘字节 `efbfbe ee83a5…`（UTF-8 被当 UTF-16）✗
+ *   unrar 7.23（新版）    → `s7/中文文件名.txt` / 落盘字节 `e4b8ad e69687…` ✓
+ *   node-unrar-js 2.0.2（内置 unrar 6.1.7）→ 仍是乱码 ✗
+ * 所以阈值取 **7.0**（保守）：低于它一律认为文件名不可靠，需要提示用户升级。
+ */
+export const FILENAME_SAFE_MIN_VERSION = '7.0';
+
+export function isFilenameSafe(version) {
+  if (!version) return false;
+  return compareVersion(version, FILENAME_SAFE_MIN_VERSION) >= 0;
+}
+
+/**
+ * 解析 RAR 引擎（三级回退：原生 unrar → node-unrar-js → 7z → 无）。
+ *
+ * 默认策略（`ZC_UNRAR_ENGINE=auto`）：**有原生 unrar 就用原生**，哪怕版本旧——
+ * 因为实测 js 引擎修不了中文名，且对损坏包不报错，换过去是能力退化；
+ * 原生缺失时才回落到 js（至少"能解"），再不行看 7z。
+ * `ZC_UNRAR_ENGINE=native|js` 可强制指定（验收与排障用）。
+ *
+ * @returns {{kind: 'unrar'|'js'|'7z'|null, bin: string|null, version: string|null, filenameSafe: boolean, reason: string|null}}
+ */
+export function resolveEngine() {
+  const mode = String(process.env.ZC_UNRAR_ENGINE || 'auto').toLowerCase();
+  const tools = resolveTools();
+  const native = tools.unrar
+    ? { kind: 'unrar', bin: tools.unrar, version: probeUnrarVersion(tools.unrar) }
+    : null;
+  const nativeEngine = native
+    ? { ...native, filenameSafe: isFilenameSafe(native.version), reason: null }
+    : null;
+  const jsEngine = jsAvailable()
+    ? { kind: 'js', bin: null, version: jsVersion(), filenameSafe: false, reason: null }
+    : null;
+  const sevenEngine = tools.sevenZip
+    ? { kind: '7z', bin: tools.sevenZip, version: probe7zVersion(tools.sevenZip), filenameSafe: false, reason: null }
+    : null;
+
+  if (mode === 'native') return nativeEngine || { kind: null, bin: null, version: null, filenameSafe: false, reason: 'ZC_UNRAR_ENGINE=native 但没找到可执行的 unrar' };
+  if (mode === 'js') return jsEngine || { kind: null, bin: null, version: null, filenameSafe: false, reason: 'ZC_UNRAR_ENGINE=js 但 node-unrar-js 不可用' };
+
+  const picked = nativeEngine || jsEngine || sevenEngine;
+  if (picked) return picked;
+  return { kind: null, bin: null, version: null, filenameSafe: false, reason: '未找到 unrar / node-unrar-js / 7z' };
+}
+
+/** 7z 的版本（只在没有 unrar/js 时用于兜底诊断） */
+function probe7zVersion(bin) {
+  try {
+    const output = execFileSync(bin, [], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    const matched = String(output).match(/7-Zip[^\n]*?(\d+\.\d+)/i);
+    return matched ? matched[1] : null;
+  } catch {
+    return null;
+  }
+}

package/server/plugins/formats/sevenzip/engine.js

@@ -0,0 +1,355 @@
+// 7z 外部引擎封装（三级回退：系统 7z/7za → WASM 引擎 → 不可用）
+//
+// 为什么先探测系统二进制：系统 `/bin/7z`（p7zip 16.02）零新增依赖、零加载开销，
+// 只有部署机上没有 7z 时才需要 WASM 兜底（WASM 引擎需额外依赖，见 docs/18 §附四）。
+//
+// 实测事实（p7zip 16.02，本项目验证环境）：
+// - `7z a -t7z -mx0..9` 的级别真实生效（同一份 20 KB 文本：-mx0=20210B / -mx9=282B）
+// - 加密：`7z a -p<密码>` 可加密；**解压时"没给密码"与"给错密码"退出码相同（都是 2）**，
+//   无法从退出码区分 —— 只能按"调用方有没有传密码"判定 MISSING_PASSWORD / BAD_PASSWORD
+// - `7z l -slt` 是机器可读列表：`Path / Size / Packed Size / Attributes / Encrypted`
+// - 符号链接条目在 `Attributes` 里体现为权限位以 `l` 开头（如 `A_ lrwxrwxrwx`）
+// - 目录条目 `Attributes = D_ ...`（压缩包里不含空目录时可能没有目录条目，父目录由解压时自动创建）
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pipeline } from 'node:stream/promises';
+import { fileURLToPath } from 'node:url';
+
+import { ERROR_CODES, apiError } from '../../../lib/errors.js';
+import { currentCpuCores, runEngineProcess } from '../../../core/engineRunner.js';
+
+// 供 index.js 的 `-mmt` 对齐使用
+export { currentCpuCores };
+
+/**
+ * WASM 引擎能不能直接写这个路径所在的文件系统？
+ *
+ * **不能写网络盘（CIFS/SMB/NFS）**：WASM 侧通过 Emscripten 的 NODEFS 落盘，它创建文件后会做
+ * chmod/chown/utime 这类元数据操作，而 CIFS 挂载会直接拒绝 → 7z 报 `errno=63 : Operation not permitted`
+ * （该构建里 errno 63 = EPERM，已在 js7z.js 的 ERRNO_CODES 表里核对过）。
+ *
+ * 对照实验（同一份 runner，只改挂载根）：
+ *   挂 CIFS 目录  → exit=2，产物 0B，报 errno=63
+ *   挂本地 btrfs → exit=0，产物 166B
+ *   读 CIFS + 写本地 → exit=0（**读没问题，只有写不行**）
+ *
+ * 因此：WASM 模式下**可写路径一律先落本地盘**，再由 Node 拷到目标（Node 的 fs 在 CIFS 上正常）。
+ */
+export function needsLocalWorkPath(engine) {
+  return Boolean(engine) && engine.kind === 'wasm';
+}
+
+/** 在本地盘（os.tmpdir()）建一个临时工作目录，供 WASM 引擎写产物 */
+export async function makeLocalWorkDir(prefix) {
+  return fsp.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+/**
+ * 把本地盘上的文件搬到目标路径（可能是 CIFS 网络盘）。
+ *
+ * **不能用 `fs.copyFile`**：CIFS 挂载上它必报 `EPERM: operation not permitted, copyfile`
+ * （实测 copyFile / COPYFILE_EXCL 都失败，而 `readFile+writeFile` 与流式 pipeline 都成功）。
+ * 这里用流式管道：内存占用与文件大小无关，适合大压缩包。
+ */
+export async function copyLocalToTarget(sourcePath, targetPath) {
+  await pipeline(fs.createReadStream(sourcePath), fs.createWriteStream(targetPath));
+}
+
+// CPU 纪律（绑核「总核数 − 1」+ nice + 全局串行）统一由 `server/core/engineRunner.js` 提供，与 7z 共用同一把锁。
+// 这是部署环境约束（CPU 核数少的机器上跑满可能影响系统响应），不是 7z 私有实现，RAR 的 js 引擎同样要用。
+
+/** 探测结果缓存（60s，与格式注册表的可用性缓存同频） */
+const PROBE_TTL_MS = 60 * 1000;
+let probeCache = null;
+
+export const LIST_TIMEOUT_MS = 60 * 1000;
+export const CREATE_TIMEOUT_MS = 60 * 60 * 1000;
+export const EXTRACT_TIMEOUT_MS = 60 * 60 * 1000;
+
+/**
+ * 候选二进制。
+ *
+ * `ZC_7Z_BIN` **设了就独占**（不是"优先再回落"）：这个变量的语义是"我明确指定用哪个二进制"，
+ * 若它指向不可执行的文件，说明部署配置有误——此时应当如实报"不可用"并让人去修，
+ * 而不是悄悄换用另一个 7z（那样"回退链②③"永远测不出来，运维也看不出自己配错了）。
+ */
+function nativeCandidates() {
+  const fromEnv = process.env.ZC_7Z_BIN;
+  if (typeof fromEnv === 'string' && fromEnv.length > 0) return [fromEnv];
+  return ['/bin/7z', '/usr/bin/7z', '/usr/local/bin/7z', '/bin/7za', '/usr/bin/7za'];
+}
+
+function isExecutable(candidate) {
+  try {
+    fs.accessSync(candidate, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** WASM 引擎的包名（可选依赖）：装了就用，没装就不算可用 */
+const WASM_PACKAGES = ['js7z-tools'];
+
+/**
+ * 探测可用引擎。
+ * @returns {{kind: 'native'|'wasm'|null, bin: string|null, wasmPackage: string|null, nativePresent: boolean}}
+ */
+export function resolveEngine() {
+  const now = Date.now();
+  if (probeCache && now - probeCache.at < PROBE_TTL_MS) return probeCache.engine;
+
+  const bin = nativeCandidates().find(isExecutable) || null;
+  let engine = { kind: bin ? 'native' : null, bin, wasmPackage: null, nativePresent: Boolean(bin) };
+
+  // WASM 兜底：系统没有二进制时才启用。判定标准是"依赖可解析"
+  // （真正的加载/执行放到子进程里，见 wasm-runner.mjs —— 缺依赖时子进程启动即失败，不会误报可用）。
+  let resolvableWasm = null;
+  // ZC_7Z_DISABLE_WASM=1：用于验收"回退③两者都没有"，也供运维在 WASM 出问题时临时关掉
+  const wasmDisabled = process.env.ZC_7Z_DISABLE_WASM === '1';
+  if (!bin && !wasmDisabled) {
+    const requireFromHere = createRequire(import.meta.url);
+    for (const name of WASM_PACKAGES) {
+      try {
+        requireFromHere.resolve(name);
+        resolvableWasm = name;
+        break;
+      } catch {
+        /* 未安装：继续看下一个候选 */
+      }
+    }
+  }
+  engine = {
+    kind: bin ? 'native' : (resolvableWasm ? 'wasm' : null),
+    bin,
+    wasmPackage: resolvableWasm,
+    nativePresent: Boolean(bin),
+  };
+
+  probeCache = { at: now, engine };
+  return engine;
+}
+
+/** 测试用：清掉探测缓存（换了环境变量后不必等 60 秒） */
+export function resetProbeCache() {
+  probeCache = null;
+}
+
+/** 版本探测（供 probe()/诊断；失败返回 null） */
+export function probeVersion(bin) {
+  try {
+    const output = execFileSync(bin, [], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    const matched = String(output).match(/7-Zip[^\n]*?(\d+\.\d+)/i);
+    return matched ? matched[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 跑一次 7z 命令（薄封装：绑核/降优先级/串行/超时硬杀都在 `core/engineRunner.js` 里统一做）。
+ * @param {string} bin
+ * @param {string[]} args
+ * @param {{cwd?: string, timeoutMs?: number, onLine?: (line: string) => void, signal?: AbortSignal}} [options]
+ */
+export function run7z(bin, args, options = {}) {
+  return runEngineProcess({
+    command: bin,
+    args,
+    cwd: options.cwd,
+    timeoutMs: options.timeoutMs || LIST_TIMEOUT_MS,
+    onLine: options.onLine,
+    signal: options.signal,
+    label: '7z',
+  });
+}
+
+/**
+ * 解析 `7z l -slt` 输出。
+ * 结构：头部块（Path/Type/Physical Size…）→ `----------` 分隔线 → 每个条目一块。
+ * @returns {Array<{name: string, type: 'dir'|'file', size: number, compressedSize: number, encrypted: boolean, symlink: boolean}>}
+ */
+export function parseSlt(output) {
+  const lines = String(output || '').split(/\r?\n/);
+  const separatorAt = lines.findIndex((line) => /^-{5,}$/.test(line.trim()));
+  if (separatorAt < 0) return [];
+
+  const entries = [];
+  let current = null;
+  const flush = () => {
+    if (current && current.name) entries.push(current);
+    current = null;
+  };
+  for (const rawLine of lines.slice(separatorAt + 1)) {
+    const line = rawLine.trim();
+    if (line.startsWith('Path = ')) {
+      flush();
+      current = {
+        name: line.slice(7).replace(/\\/g, '/'),
+        type: 'file',
+        size: 0,
+        compressedSize: 0,
+        encrypted: false,
+        symlink: false,
+      };
+      continue;
+    }
+    if (!current) continue;
+    const attributes = line.match(/^Attributes = (.*)$/);
+    if (attributes) {
+      const attributeText = attributes[1];
+      // 目录标记：p7zip 16.02 写 `D_ drwxr-xr-x`，7-Zip 25.01（WASM）写 `D drwxr-xr-x` —— 两者都要认
+      if (/^D[\s_]/.test(attributeText) || /^D$/.test(attributeText)) current.type = 'dir';
+      // 符号链接判定：**权限串首字符必须是 `l`**（`A_ lrwxrwxrwx`）。
+      // 不能宽匹配 `-rw-r--r--`——普通文件的权限串也以 `-` 开头，宽匹配会把所有普通文件误判成链接（实测踩过）。
+      const permission = attributeText.split(/\s+/).find((token) => /^[dl-][rwx-]{9}$/.test(token)) || '';
+      if (permission.startsWith('l')) current.symlink = true;
+      continue;
+    }
+    const size = line.match(/^Size = (\d+)/);
+    if (size) {
+      current.size = Number(size[1]);
+      continue;
+    }
+    const packed = line.match(/^Packed Size = (\d+)/);
+    if (packed) {
+      current.compressedSize = Number(packed[1]);
+      continue;
+    }
+    if (/^Encrypted = \+/.test(line)) current.encrypted = true;
+    // 25.01 用 `Folder = +` 表达目录（与 Attributes 双保险）
+    if (/^Folder = \+/.test(line)) current.type = 'dir';
+  }
+  flush();
+  return entries;
+}
+
+/** 列表里是否含加密内容（任一文件条目 Encrypted=+ 即视为加密包） */
+export function isEncryptedList(entries) {
+  return entries.some((entry) => entry.encrypted === true);
+}
+
+/**
+ * 失败 → 契约错误码（四种情况不能混用）。
+ * @param {{stdout: string, stderr: string, code: number, timedOut?: boolean, aborted?: boolean}} outcome
+ * @param {{hasPassword: boolean, operation: 'list'|'test'|'extract'|'create'}} context
+ */
+export function mapFailure(outcome, context) {
+  if (outcome.aborted) throw apiError(ERROR_CODES.ABORTED, '任务已取消');
+  if (outcome.timedOut) throw apiError(ERROR_CODES.INTERNAL_ERROR, '7z 操作超时（外部程序未在限定时间内完成）');
+  const text = `${outcome.stdout}\n${outcome.stderr}`;
+  const passwordState = () => {
+    if (!context.hasPassword) throw apiError(ERROR_CODES.MISSING_PASSWORD, '该压缩包已加密，请输入密码');
+    throw apiError(ERROR_CODES.BAD_PASSWORD, '密码错误');
+  };
+  // 明确的密码字样（p7zip 16.02 会打 "Wrong password"/"Enter password"）
+  if (/wrong password|enter password|can not open encrypted|password/i.test(text)) passwordState();
+  // 明确的数据损坏信号
+  if (/data error|crc failed|unexpected end|headers error|is not archive/i.test(text)) {
+    // 落到下面的"损坏"分支
+  } else if (context.archiveEncrypted) {
+    // 关键：WASM 版 7-Zip（25.01）密码错时只说 "Archives with Errors"，**不含 password 字样**。
+    // 已知包是加密的，又没命中损坏信号 → 就是密码问题（有没有传密码决定是哪一态）。
+    passwordState();
+  }
+  if (context.operation === 'create') {
+    throw apiError(ERROR_CODES.INTERNAL_ERROR, '7z 压缩失败', {
+      detail: sanitizeDetail(text),
+    });
+  }
+  throw apiError(ERROR_CODES.ARCHIVE_CORRUPTED, '压缩包损坏', {
+    exitCode: outcome.code,
+    detail: sanitizeDetail(text),
+  });
+}
+
+/**
+ * 把 7z 输出里的**宿主绝对路径**收敛成文件名，避免把存储根路径带进任务 error（进而出现在 API 响应里）。
+ *
+ * 为什么必须做：原生引擎调 7z 时传的是宿主绝对路径，失败时 7z 会把路径原样打出来；
+ * 而 m2/m3/probes 都有"响应不含绝对路径"的断言 —— 带路径的错误文案会让这些断言变红，
+ * 也确实属于信息泄漏（用户看到的错误不需要知道服务器目录结构）。
+ * 完整原文仍写服务日志，便于排查。
+ */
+function sanitizeDetail(rawText) {
+  const tail = String(rawText || '').trim().split(/\r?\n/).slice(-2).join(' / ').slice(0, 200);
+  if (tail.length === 0) return '';
+  console.error(`[sevenzip] 7z 失败原文：${tail}`);
+  return tail.replace(/\/[^\s'":,]+/g, (matched) => matched.split('/').filter(Boolean).pop() || matched);
+}
+
+/** WASM 执行器脚本路径（与被本文件同目录） */
+const WASM_RUNNER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'wasm-runner.mjs');
+
+/**
+ * 把宿主绝对路径翻译成 WASM 虚拟路径，并给出需要挂载的目录清单。
+ *
+ * 规则：
+ *   - `-o/abs/dir`      → 挂载 `/abs/dir` 本身，参数变 `-o/mN`
+ *   - `/abs/file`       → 挂载其父目录，参数变 `/mN/file`
+ *   - 相对名（create 的条目名）→ 原样保留，靠 `cwd` 决定基准
+ * @returns {{argv: string[], cwdWasm: string|null, mounts: Array<{host: string, wasm: string}>}}
+ */
+export function planWasmMounts(argv, cwd) {
+  const mounts = [];
+  const mountOf = (hostAbs) => {
+    const found = mounts.find((item) => item.host === hostAbs);
+    if (found) return found.wasm;
+    const wasmPath = `/m${mounts.length}`;
+    mounts.push({ host: hostAbs, wasm: wasmPath });
+    return wasmPath;
+  };
+  const translated = argv.map((arg) => {
+    const outputPrefix = arg.match(/^-o(\/.*)$/);
+    if (outputPrefix) return `-o${mountOf(outputPrefix[1])}`;
+    if (arg.startsWith('/')) return `${mountOf(path.dirname(arg))}/${path.basename(arg)}`;
+    return arg;
+  });
+  return { argv: translated, cwdWasm: cwd ? mountOf(cwd) : null, mounts };
+}
+
+/**
+ * 统一执行入口：引擎是原生二进制就走 spawn，是 WASM 就走子进程执行器。
+ *
+ * 串行闸门与绑核/降优先级都来自 `server/core/engineRunner.js`（跨插件共享一把锁），
+ * 避免"每个格式各写一份 CPU 纪律、下一个格式必然漏掉"。
+ */
+export function runEngine(engine, options = {}) {
+  // 串行/限核由 runEngineProcess 内部统一处理，这里不再自己排队（避免双重排队）
+  return runEngineUnsafe(engine, options);
+}
+
+async function runEngineUnsafe(engine, options = {}) {
+  if (engine.kind === 'native') return run7z(engine.bin, options.argv, options);
+  if (engine.kind !== 'wasm') {
+    throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, '没有可用的 7z 引擎（系统二进制与 WASM 都不可用）');
+  }
+
+  const spec = planWasmMounts(options.argv, options.cwd);
+  // 绑核 / nice / 全局串行 / 超时硬杀 / 取消：统一由 core/engineRunner.js 处理
+  const outcome = await runEngineProcess({
+    command: process.execPath,
+    args: [WASM_RUNNER, JSON.stringify(spec)],
+    timeoutMs: options.timeoutMs || LIST_TIMEOUT_MS,
+    signal: options.signal,
+    onLine: options.onLine,
+    label: '7z-wasm',
+  });
+
+  // 信封是 stderr 的**最后一行** JSON（前面的行是运行器诊断信息）
+  let code = -1;
+  try {
+    const lastLine = String(outcome.stderr || '').trim().split('\n').filter((line) => line.startsWith('{')).pop() || '{}';
+    const parsed = JSON.parse(lastLine);
+    code = typeof parsed.exit === 'number' ? parsed.exit : -1;
+  } catch {
+    code = -1;
+  }
+  // WASM 模式下把 7z 输出放进 stdout，让 parseSlt 等既有解析逻辑无需分支
+  return { code, stdout: outcome.stdout, stderr: '', timedOut: outcome.timedOut, aborted: outcome.aborted };
+}