zipcalm 0.0.0-stage → 1.0.2

package/server/core/compress/preflight.js

@@ -0,0 +1,376 @@
+// 压缩/解压预检（M2 最小版：权限 + 2 倍空间 + 目标可写）
+//
+// 契约：INV-07「剩余空间 ≥ 待压文件 × preflightFactor（默认 2）」、INV-08「绝不覆盖」。
+// M6 才做黑名单与滚动预检的完整逻辑；M2 只做「够不够空间 + 权限够不够」这两件最关键的事，
+// 并且**先拦后做**：预检失败不建任务（docs/06 §三）。
+//
+// 结构：每个预检拆成"收集事实 → 判定拦截原因 → 组装响应"三步，避免一个函数里混着 I/O、
+// 判定与响应拼装（那种函数既难测也改不动）。
+
+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 { matchEntry } from './blacklist.js';
+import { collectFilesUnder } from './sourceWalk.js';
+import { accumulateHardlink, createHardlinkAccumulator, discardHardlink, finalizeHardlinks } from './hardlinkScan.js';
+import { formatPreservesHardlinks, shouldHintHardlink } from '../../../shared/hardlink-hint.js';
+import { pathExists } from '../../lib/fs-probe.js';
+
+/** 压缩估算的粗比值（M2 只用于给前端一个量级；真实压缩比由格式包 estimate 决定） */
+const ESTIMATED_OUTPUT_RATIO = 0.6;
+
+/** 读取目录所在文件系统的可用字节（statfs 在 Node 18.15+ / 22 可用） */
+async function freeBytesOf(dir) {
+  try {
+    const stats = await fsp.statfs(dir);
+    return Number(stats.bavail) * Number(stats.bsize);
+  } catch {
+    return null; // 拿不到就不拦（宁可放过也不误杀），但会在响应里体现 freeBytes=null
+  }
+}
+
+async function isWritable(dir) {
+  try {
+    await fsp.access(dir, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 单个源 → 预检条目（不存在 / 不可读都在这里定下来，后续判定只看条目） */
+async function sourceItemOf(source, hardlinkAccumulator) {
+  let fileStat;
+  try {
+    fileStat = await fsp.lstat(source.absPath);
+  } catch (error) {
+    return {
+      path: source.path,
+      name: source.name,
+      kind: source.kind,
+      size: 0,
+      exists: false,
+      readable: false,
+      error: error.code === 'ENOENT' ? ERROR_CODES.PATH_NOT_FOUND : ERROR_CODES.PERMISSION_DENIED,
+    };
+  }
+
+  let readable = true;
+  try {
+    await fsp.access(source.absPath, fs.constants.R_OK);
+  } catch {
+    readable = false;
+  }
+
+  const isDir = fileStat.isDirectory();
+  let size = isDir ? 0 : fileStat.size;
+  let fileCount = isDir ? 0 : 1;
+  if (isDir) {
+    const nested = await directoryStats(source.absPath, hardlinkAccumulator);
+    size = nested.bytes;
+    fileCount = nested.files;
+  } else {
+    accumulateHardlink(hardlinkAccumulator, {
+      absPath: source.absPath,
+      dev: fileStat.dev,
+      ino: fileStat.ino,
+      size: fileStat.size,
+    });
+  }
+
+  return {
+    path: source.path,
+    name: source.name,
+    kind: isDir ? 'dir' : 'file',
+    size,
+    fileCount,
+    exists: true,
+    readable,
+  };
+}
+
+async function collectSourceItems(sources, hardlinkAccumulator) {
+  const items = [];
+  for (const source of sources) items.push(await sourceItemOf(source, hardlinkAccumulator));
+  return items;
+}
+
+/**
+ * 给每个源标注"是否会被整体跳过"，并汇总被跳过的文件清单。
+ *
+ * 为什么跳过项要从"待压字节"里扣掉：它们根本不会进包（不耗压缩 CPU、不占产物空间），
+ * 若仍按 totalBytes 做 2 倍空间判定，会出现"明明只剩几个文本文件，却因为目录里有 100GB 视频被拒"。
+ *
+ * @param {Array} items collectSourceItems 的结果
+ * @param {Array} sources 与 items 同序的源（要 absPath）
+ * @param {Array} layers resolveLayers 的结果（空数组 = 黑名单关闭）
+ * @returns {Promise<{items: Array, skipped: Array<{path: string, pattern: string, layer: string}>, skippedBytes: number}>}
+ */
+async function annotateWithBlacklist(items, sources, layers, hardlinkAccumulator) {
+  const skipped = [];
+  let skippedBytes = 0;
+  const annotated = [];
+
+  for (let index = 0; index < items.length; index += 1) {
+    const one = await annotateOneSource(items[index], sources[index], layers, hardlinkAccumulator);
+    annotated.push(one.item);
+    skipped.push(...one.skipped);
+    skippedBytes += one.skippedBytes;
+  }
+
+  return { items: annotated, skipped, skippedBytes };
+}
+
+/**
+ * 单个源的标注：返回标注后的条目、命中清单与命中字节数。
+ * 抽出来是为了让 annotateWithBlacklist 只做"遍历 + 汇总"（圈复杂度压在阈值内）。
+ */
+async function annotateOneSource(sourceItem, sourceRef, layers, hardlinkAccumulator) {
+  const annotatedItem = { ...sourceItem, willSkip: false, skipReason: null, keptFiles: Number(sourceItem.fileCount) || 0 };
+  if (!sourceItem.exists || !sourceRef || layers.length === 0) return { item: annotatedItem, skipped: [], skippedBytes: 0 };
+
+  const files = await collectFilesUnder(sourceRef.absPath);
+  const skipped = [];
+  let keptFiles = 0;
+  let skippedBytes = 0;
+  for (const file of files) {
+    const hit = matchEntry(layers, { name: file.name, segments: file.segments });
+    if (!hit) {
+      keptFiles += 1;
+      continue;
+    }
+    skipped.push({ path: joinUserPath(sourceItem.path, file.relative), pattern: hit.pattern, layer: hit.layer });
+    skippedBytes += Number(file.size) || 0;
+    // 被跳过的文件不会进包 → 从硬链接统计里扣掉，避免"两个成员都被跳过却提示会存两份"
+    discardHardlink(hardlinkAccumulator, file);
+  }
+  annotatedItem.keptFiles = keptFiles;
+  // 整个源都被跳过（且确实有文件）：前端据此提示"该目录没有可压缩文件"，single 模式据此不建空包
+  if (files.length > 0 && keptFiles === 0) {
+    annotatedItem.willSkip = true;
+    annotatedItem.skipReason = 'blacklisted';
+  }
+  return { item: annotatedItem, skipped, skippedBytes };
+}
+
+/** 用户路径拼接（POSIX 风格；relative 为空表示源本身就是文件） */
+function joinUserPath(base, relative) {
+  if (!relative) return base;
+  const prefix = base === '/' ? '' : String(base).replace(/\/$/, '');
+  return `${prefix}/${relative}`;
+}
+
+/** 压缩预检的拦截判定（顺序即优先级：不存在 > 不可读 > 目录不存在 > 不可写 > 空间不足） */
+function compressBlockedReason({ items, outputExists, outputWritable, freeBytes, requiredBytes, factor, totalBytes, keptBytes }) {
+  const missing = items.filter((item) => !item.exists);
+  const unreadable = items.filter((item) => item.exists && !item.readable);
+
+  if (missing.length > 0) return { code: ERROR_CODES.PATH_NOT_FOUND, message: '有源条目不存在' };
+  if (unreadable.length > 0) return { code: ERROR_CODES.PERMISSION_DENIED, message: '有源条目不可读' };
+  // 输出目录必须已存在：我们不会替用户"静默创建目录"（那是副作用）；不存在 → PATH_NOT_FOUND（诚实错误码）
+  if (!outputExists) return { code: ERROR_CODES.PATH_NOT_FOUND, message: '输出目录不存在' };
+  if (!outputWritable) return { code: ERROR_CODES.PERMISSION_DENIED, message: '输出目录不可写' };
+  // 全部命中黑名单：没有可压的东西（契约错误码 ALL_SOURCES_SKIPPED，422）
+  if (totalBytes > 0 && keptBytes === 0) {
+    return { code: ERROR_CODES.ALL_SOURCES_SKIPPED, message: '没有可压缩的文件：全部命中黑名单（可在设置里调整或关闭黑名单）' };
+  }
+  if (freeBytes !== null && freeBytes < requiredBytes) {
+    return {
+      code: ERROR_CODES.DISK_FULL,
+      message: `空间不足：需要 ${requiredBytes} 字节（待压 × ${factor}），剩余 ${freeBytes} 字节`,
+    };
+  }
+  return null;
+}
+
+/**
+ * 组装硬链接响应块。
+ *
+ * 只做"提示所需的信息"，**不参与任何空间判定**（INV-07 保持原样）：
+ * - `duplicateBytes` 与格式无关（同一份数据被多存多少），便于前端在 tar 下做正向说明
+ * - `estimatedBytes` 只体现"存几份"，**不含压缩比**（压缩比因内容而异，不能承诺最终大小）
+ */
+function buildHardlinksBlock(format, keptBytes, hardlinkAccumulator) {
+  const stats = finalizeHardlinks(hardlinkAccumulator);
+  const preservedByFormat = formatPreservesHardlinks(format);
+  return {
+    groups: stats.groups,
+    files: stats.files,
+    // 逻辑大小 = 真正会进包的文件字节（已扣掉黑名单跳过项）
+    logicalBytes: keptBytes,
+    duplicateBytes: stats.duplicatedBytes,
+    preservedByFormat,
+    estimatedBytes: preservedByFormat ? Math.max(0, keptBytes - stats.duplicatedBytes) : keptBytes,
+    hint: !preservedByFormat && shouldHintHardlink({ logicalBytes: keptBytes, duplicatedBytes: stats.duplicatedBytes }),
+  };
+}
+
+/**
+ * 压缩预检。
+ * @param {{config: object, rootAbs: string}} deps
+ * @param {{sources: Array<{path: string, absPath: string, name: string, kind: string}>, format: string, mode: string, outputDir: string}} input
+ */
+export async function compressPreflight(deps, input) {
+  const factor = deps.config.compress.preflightFactor;
+  // 硬链接统计与"目录字节数"共用同一次遍历（dev/ino 来自已有的 lstat，不额外多 syscall）
+  const hardlinkAccumulator = createHardlinkAccumulator();
+  const rawItems = await collectSourceItems(input.sources, hardlinkAccumulator);
+  // 黑名单层由调用方解析（路由里一次性解析，预检与打包共用同一份判定语义）
+  const layers = Array.isArray(deps.blacklistLayers) ? deps.blacklistLayers : [];
+  const { items, skipped, skippedBytes } = await annotateWithBlacklist(rawItems, input.sources, layers, hardlinkAccumulator);
+
+  const totalBytes = items.reduce((sum, item) => sum + item.size, 0);
+  // 「待压字节」= 全部源 − 黑名单跳过：跳过项不进包，不该占用 2 倍空间额度
+  const keptBytes = Math.max(0, totalBytes - skippedBytes);
+
+  const outputDir = input.outputDir;
+  const outputExists = await pathExists(outputDir);
+  const outputWritable = outputExists ? await isWritable(outputDir) : false;
+  const freeBytes = await freeBytesOf(outputExists ? outputDir : path.dirname(outputDir));
+  const requiredBytes = keptBytes * factor;
+
+  const blockedReason = compressBlockedReason({
+    items,
+    outputExists,
+    outputWritable,
+    freeBytes,
+    requiredBytes,
+    factor,
+    totalBytes,
+    keptBytes,
+  });
+
+  const hardlinks = buildHardlinksBlock(input.format, keptBytes, hardlinkAccumulator);
+
+  return {
+    canProceed: blockedReason === null,
+    blockedReason,
+    mode: input.mode,
+    format: input.format,
+    totalBytes,
+    estimatedOutputBytes: Math.ceil(keptBytes * ESTIMATED_OUTPUT_RATIO),
+    requiredBytes,
+    freeBytes,
+    preflightFactor: factor,
+    items,
+    // 硬链接提示（只读信息；hint=false 时前端不应展示任何提示条）
+    hardlinks,
+    // 契约 §compress/preflight：skipped[] = { path, pattern, layer }（对外只有用户路径）
+    skipped,
+    packages: [],
+  };
+}
+
+/** 递归统计目录（字节数 + 文件数；异步、不跟随符号链接）—— 进度分母用 */
+async function directoryStats(dirAbs, hardlinkAccumulator) {
+  let bytes = 0;
+  let files = 0;
+  let dirents;
+  try {
+    dirents = await fsp.readdir(dirAbs, { withFileTypes: true });
+  } catch {
+    return { bytes, files };
+  }
+  for (const dirent of dirents) {
+    const child = path.join(dirAbs, dirent.name);
+    if (dirent.isSymbolicLink()) continue;
+    if (dirent.isDirectory()) {
+      const nested = await directoryStats(child, hardlinkAccumulator);
+      bytes += nested.bytes;
+      files += nested.files;
+    } else if (dirent.isFile()) {
+      try {
+        const childStat = await fsp.lstat(child);
+        bytes += childStat.size;
+        files += 1;
+        accumulateHardlink(hardlinkAccumulator, {
+          absPath: child,
+          dev: childStat.dev,
+          ino: childStat.ino,
+          size: childStat.size,
+        });
+      } catch {
+        /* 竞态删除：忽略 */
+      }
+    }
+  }
+  return { bytes, files };
+}
+
+/**
+ * 解压预检：归档可读 + 目标目录可写 + 空间够（解压后总量 × factor）。
+ * @param {{config: object, plugin: object}} deps
+ */
+export async function extractPreflight(deps, input) {
+  assertExtractInput(input);
+  await assertArchiveReadable(input);
+
+  // 用 list() 校验归档可解析，并取解压后总量（不解析 → ARCHIVE_CORRUPTED）
+  const listing = await deps.plugin.list(input.archiveAbsPath);
+  const totalBytes = listing.entries
+    .filter((entry) => entry.type === 'file')
+    .reduce((sum, entry) => sum + entry.size, 0);
+
+  const factor = deps.config.compress.preflightFactor;
+  const targetExists = await pathExists(input.targetAbsDir);
+  // 目标目录**可能尚不存在**（解压时才创建）：存在则检查它本身，否则检查其父目录。
+  // 注意必须用**绝对路径**（input.targetAbsDir）做文件系统检查——早期版本误用了 API 用户路径，
+  // 结果把 "/m2-test/out" 当成了文件系统根下的 /m2-test/out，误报 PERMISSION_DENIED（真实踩过）。
+  const checkDir = targetExists ? input.targetAbsDir : path.dirname(input.targetAbsDir);
+  const targetWritable = await isWritable(checkDir);
+  const freeBytes = await freeBytesOf(checkDir);
+  const requiredBytes = totalBytes * factor;
+
+  let blockedReason = null;
+  if (!targetWritable) blockedReason = { code: ERROR_CODES.PERMISSION_DENIED, message: '目标目录不可写' };
+  else if (freeBytes !== null && freeBytes < requiredBytes) {
+    blockedReason = {
+      code: ERROR_CODES.DISK_FULL,
+      message: `空间不足：需要 ${requiredBytes} 字节（解压后 × ${factor}），剩余 ${freeBytes} 字节`,
+    };
+  }
+
+  return {
+    canProceed: blockedReason === null,
+    blockedReason,
+    archive: input.archivePath,
+    targetDir: input.targetDir,
+    targetExists,
+    entries: listing.entries.length,
+    totalBytes,
+    requiredBytes,
+    freeBytes,
+    preflightFactor: factor,
+  };
+}
+
+/** 入参完整性：内部绝对路径由编排器从 record.internal 传进来，缺了就说明调用方写错了
+ *  （必须显式报错，不能靠"stat 失败"兜底，否则会伪装成权限问题） */
+function assertExtractInput(input) {
+  if (!input || typeof input.archiveAbsPath !== 'string' || !input.archiveAbsPath) {
+    throw apiError(ERROR_CODES.INTERNAL_ERROR, '解压预检缺少归档绝对路径（内部错误）');
+  }
+  if (typeof input.targetAbsDir !== 'string' || !input.targetAbsDir) {
+    throw apiError(ERROR_CODES.INTERNAL_ERROR, '解压预检缺少目标目录绝对路径（内部错误）');
+  }
+}
+
+/** 归档必须存在且是普通文件；文件系统错误翻译成契约错误码 */
+async function assertArchiveReadable(input) {
+  let archiveStat;
+  try {
+    archiveStat = await fsp.stat(input.archiveAbsPath);
+  } catch (error) {
+    if (!error || !error.code) throw error; // 非文件系统错误：交给上层按 INTERNAL_ERROR 处理
+    throw apiError(
+      error.code === 'ENOENT' ? ERROR_CODES.PATH_NOT_FOUND : ERROR_CODES.PERMISSION_DENIED,
+      '压缩包不可读',
+      { archive: path.basename(input.archivePath || input.archiveAbsPath) },
+    );
+  }
+  if (!archiveStat.isFile()) {
+    throw apiError(ERROR_CODES.NOT_A_DIRECTORY, '目标不是文件', { archive: path.basename(input.archivePath) });
+  }
+}

package/server/core/compress/registry.js

@@ -0,0 +1,240 @@
+// 格式注册表（M2：先只 zip；M4 扩展四格式时**只需加目录**，不改本文件）
+//
+// 契约（docs/M0/插件契约.md §五）：
+// - 自动发现：扫描 server/plugins/formats/<id>/index.js；
+// - 双索引：按 id 与按**每个扩展名**（含 extAliases）建索引；
+// - 匹配优先级：最长复合扩展名优先（.tar.gz 不能被 .gz 抢走）；
+// - 启动校验：id/ext 唯一 + 必需方法齐全；**不合规只禁用该包并告警，不影响其他包**；
+// - 可用性结果缓存 ≤ 60s（用户现场装了 zstd 之类，最多一分钟 UI 就该亮起来）。
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+
+const DEFAULT_PLUGINS_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../plugins/formats',
+);
+
+const AVAILABILITY_TTL_MS = 60 * 1000;
+/** 被拒格式包的统一日志文案（三处拒绝原因共用，避免文案漂移） */
+const REJECTED_LOG = 'format plugin rejected';
+
+/** 契约要求的必需成员 */
+const REQUIRED_MEMBERS = ['id', 'name', 'ext', 'mime'];
+const REQUIRED_METHODS = ['available', 'estimate', 'create', 'extract', 'list', 'test'];
+
+function validatePlugin(plugin, source) {
+  const problems = [];
+  for (const member of REQUIRED_MEMBERS) {
+    if (typeof plugin[member] !== 'string' || plugin[member].length === 0) problems.push(`缺少字符串元数据 ${member}`);
+  }
+  for (const method of REQUIRED_METHODS) {
+    if (typeof plugin[method] !== 'function') problems.push(`缺少方法 ${method}()`);
+  }
+  if (typeof plugin.ext === 'string' && !plugin.ext.startsWith('.')) problems.push('ext 必须以 . 开头');
+  if (problems.length > 0) {
+    return { ok: false, reason: `${source}: ${problems.join('；')}` };
+  }
+  return { ok: true };
+}
+
+export function createRegistry(options = {}) {
+  const logger = options.logger || { info() {}, warn() {} };
+  const pluginsDir = options.pluginsDir || DEFAULT_PLUGINS_DIR;
+
+  /** Map<id, plugin> */
+  const byId = new Map();
+  /** Map<ext(lowercase), plugin> */
+  const byExt = new Map();
+  /** 扩展名按长度降序（最长优先匹配） */
+  let extKeysDesc = [];
+  /** Map<id, {available:boolean, at:number}> —— 可用性探测结果（60 秒内复用，避免每次列格式都探测） */
+  const availabilityCache = new Map();
+  const loadFailures = [];
+  /** 插件目录上次扫描时的 mtime：用于「加/删一个目录即注册」的运行时重扫 */
+  let lastScanMtimeMs = 0;
+
+  /**
+   * 目录内容变化时重扫（"新增一个格式 = 新增一个目录"的运行时支撑）。
+   * 目录 mtime 在增删子项时会变；没有变化就直接跳过，代价只有一次 stat。
+   * @returns {Promise<boolean>} 是否真的重扫了
+   */
+  async function refreshIfChanged() {
+    try {
+      const stat = await fs.stat(pluginsDir);
+      if (stat.mtimeMs === lastScanMtimeMs) return false;
+      lastScanMtimeMs = stat.mtimeMs;
+      await discover();
+      return true;
+    } catch (error) {
+      logger.warn('format plugins dir stat failed', { dir: pluginsDir, error: error.message });
+      return false;
+    }
+  }
+
+  /**
+   * 单个目录 → 注册所需信息。
+   * 加载失败 / 校验不过 / id 或扩展名冲突都只记原因并返回 null（**不影响其他格式包**）。
+   * @returns {Promise<{plugin: object, exts: string[]}|null>}
+   */
+  async function registerPluginFrom(dirent) {
+    const source = `plugins/formats/${dirent.name}`;
+    const entryFile = path.join(pluginsDir, dirent.name, 'index.js');
+    let plugin;
+    try {
+      const module = await import(pathToFileURL(entryFile).href);
+      plugin = module.default || module.plugin || module;
+    } catch (error) {
+      loadFailures.push(`${source}: 加载失败 ${error.message}`);
+      logger.warn('format plugin import failed', { source, error: error.message });
+      return null;
+    }
+
+    const valid = validatePlugin(plugin, source);
+    if (!valid.ok) {
+      loadFailures.push(valid.reason);
+      logger.warn(REJECTED_LOG, { source, reason: valid.reason });
+      return null;
+    }
+
+    // id / ext 全局唯一：冲突时禁用后来者（不影响已注册的包）
+    if (byId.has(plugin.id)) {
+      loadFailures.push(`${source}: id 与已注册格式冲突（${plugin.id}）`);
+      logger.warn(REJECTED_LOG, { source, reason: `id 冲突 ${plugin.id}` });
+      return null;
+    }
+    const exts = [plugin.ext, ...(Array.isArray(plugin.extAliases) ? plugin.extAliases : [])].map((ext) => ext.toLowerCase());
+    const extConflict = exts.find((ext) => byExt.has(ext));
+    if (extConflict) {
+      loadFailures.push(`${source}: 扩展名与已注册格式冲突（${extConflict}）`);
+      logger.warn(REJECTED_LOG, { source, reason: `扩展名冲突 ${extConflict}` });
+      return null;
+    }
+    return { plugin, exts };
+  }
+
+  /** 扫描插件目录并注册 */
+  async function discover() {
+    byId.clear();
+    byExt.clear();
+    extKeysDesc = [];
+    loadFailures.length = 0;
+
+    let dirents;
+    try {
+      dirents = await fs.readdir(pluginsDir, { withFileTypes: true });
+    } catch (error) {
+      logger.warn('format plugins dir unreadable', { dir: pluginsDir, error: error.message });
+      return { loaded: 0, failed: 0 };
+    }
+
+    for (const dirent of dirents) {
+      if (!dirent.isDirectory()) continue;
+      // `_shared` 之类的下划线目录是内部共享代码目录，不是格式包（约定：格式包 id 不用下划线打头）
+      if (dirent.name.startsWith('_')) continue;
+      const registered = await registerPluginFrom(dirent);
+      if (!registered) continue;
+      byId.set(registered.plugin.id, registered.plugin);
+      for (const ext of registered.exts) byExt.set(ext, registered.plugin);
+    }
+
+    extKeysDesc = [...byExt.keys()].sort((a, b) => b.length - a.length);
+    // 记下本次扫描时的目录 mtime，供 refreshIfChanged 判断"有没有增删过"
+    try {
+      lastScanMtimeMs = (await fs.stat(pluginsDir)).mtimeMs;
+    } catch {
+      lastScanMtimeMs = 0;
+    }
+    const loadedFormatIds = [...byId.keys()];
+    logger.info('format registry loaded', { formats: loadedFormatIds, failures: loadFailures.length });
+    return { loaded: byId.size, failed: loadFailures.length };
+  }
+
+  /** 可用性（带 60s 缓存） */
+  async function isAvailable(id) {
+    const plugin = byId.get(id);
+    if (!plugin) return false;
+    const cached = availabilityCache.get(id);
+    if (cached && Date.now() - cached.at < AVAILABILITY_TTL_MS) return cached.available;
+
+    let probeResult = false;
+    try {
+      probeResult = Boolean(await plugin.available());
+    } catch (error) {
+      logger.warn('format availability probe failed', { id, error: error.message });
+      probeResult = false;
+    }
+    availabilityCache.set(id, { available: probeResult, at: Date.now() });
+    return probeResult;
+  }
+
+  /** 供 API /formats 使用 */
+  async function list() {
+    // 每次列格式前先看看插件目录有没有增删（放一个目录进去就能出现，不需要改注册代码、也不需要重启）
+    await refreshIfChanged();
+    const formatItems = [];
+    for (const plugin of byId.values()) {
+      const available = await isAvailable(plugin.id);
+      let unavailableReason = null;
+      if (!available && typeof plugin.unavailableReason === 'function') {
+        try {
+          unavailableReason = await plugin.unavailableReason();
+        } catch {
+          unavailableReason = null;
+        }
+      }
+      formatItems.push({
+        id: plugin.id,
+        name: plugin.name,
+        ext: plugin.ext,
+        extAliases: plugin.extAliases || [],
+        mime: plugin.mime,
+        available,
+        unavailableReason,
+        levelRange: plugin.levelRange || null,
+        defaultLevel: plugin.defaultLevel ?? null,
+        // 只读格式（如 RAR）：可解压但不能压缩。前端压缩抽屉要靠这个字段把它过滤掉，
+        // 否则它会出现在压缩格式列表里、甚至被默认选中，用户点「开始压缩」才失败。
+        extractOnly: plugin.extractOnly === true,
+      });
+    }
+    return formatItems;
+  }
+
+  function get(id) {
+    return byId.get(id) || null;
+  }
+
+  /** 取插件；取不到抛契约错误码（调用方不用自己拼错） */
+  function require(id) {
+    const plugin = byId.get(id);
+    if (!plugin) {
+      throw apiError(ERROR_CODES.UNSUPPORTED_FORMAT, `不支持的压缩格式：${id}`, { supported: [...byId.keys()] });
+    }
+    return plugin;
+  }
+
+  /** 按扩展名取插件（最长优先）；找不到返回 null */
+  function byExtension(ext) {
+    if (typeof ext !== 'string' || ext === '') return null;
+    const lower = ext.toLowerCase();
+    // extKeysDesc 已按长度降序排好：find 取到的就是最长匹配（与"逐个 endsWith 提前返回"等价）
+    const matched = extKeysDesc.find((candidate) => lower === candidate || lower.endsWith(candidate));
+    return matched ? byExt.get(matched) : null;
+  }
+
+  return {
+    discover,
+    refreshIfChanged,
+    list,
+    get,
+    require,
+    byExtension,
+    isAvailable,
+    ids: () => [...byId.keys()],
+    failures: () => [...loadFailures],
+  };
+}