zipcalm 0.0.0-stage → 1.0.2

package/server/core/auth/store.js

@@ -0,0 +1,261 @@
+// 认证存储（M1）：Session + Bearer 双通道
+//
+// 契约（docs/M0/API规范.md §二）：
+// - Session：HttpOnly Cookie `zc_session`，7 天**滑动续期**；
+// - Bearer：`Authorization: Bearer <token>`，30 天；
+// - 两者同时存在时 **Bearer 优先**；
+// - 凭据只存哈希（sha256），磁盘上不出现明文（INV-16）。
+//
+// 会话放内存（重启即失效，属可接受语义）；Bearer token 落盘持久化，
+// 这样 APK/脚本重启服务后仍可用（数据模型 §六 storage/auth-tokens.json）。
+
+import path from 'node:path';
+
+import { readJson, writeJsonAtomic } from '../../lib/atomic-json.js';
+import { randomToken, sha256 } from './password.js';
+
+/** 滑动续期阈值：剩余时间低于 TTL 的一半时才重新签发 Cookie（避免每个请求都 Set-Cookie） */
+const RENEW_THRESHOLD_RATIO = 0.5;
+/** token 落盘节流窗口：把同一窗口内的多次变更合并成一次原子写（登录/续期/清理都会触发变更） */
+const TOKEN_PERSIST_THROTTLE_MS = 50;
+/** 过期条目清理周期（1 分钟；定时器 unref，不阻止进程退出） */
+const CLEANUP_INTERVAL_MS = 60 * 1000;
+
+/**
+ * 清掉已过期的条目并返回清掉的条数。
+ * token 与 session 两张表结构相同（都是 {expiresAt}），所以共用这一份实现。
+ */
+function pruneExpired(map, nowTs) {
+  let removed = 0;
+  for (const [key, value] of map) {
+    if (value.expiresAt > nowTs) continue;
+    map.delete(key);
+    removed += 1;
+  }
+  return removed;
+}
+
+/** 登录失败计数按限流窗口过期（窗口外的不再计入） */
+function pruneLoginFailures(records, windowMs, nowTs) {
+  for (const [ip, record] of records) {
+    if (nowTs - record.firstAt > windowMs) records.delete(ip);
+  }
+}
+
+export function createAuthStore({ config, logger, dataDir }) {
+  const sessionTtlMs = config.sessionTtlMs;
+  const tokenTtlMs = config.tokenTtlMs;
+  const username = config.username;
+  const tokenFilePath = path.join(dataDir, 'auth-tokens.json');
+
+  /** Map<sha256(sid), {user, expiresAt, issuedAt, lastSeenAt}> */
+  const sessions = new Map();
+  /** Map<sha256(token), {user, expiresAt, issuedAt}> */
+  const tokens = new Map();
+  /** 登录失败计数：Map<ip, {count, firstAt}> */
+  const loginFailures = new Map();
+
+  let persistTimer = null;
+
+  // ===== 持久化（只存哈希 + 过期时间）=====
+
+  /** 一条落盘 token 是否还能用（字段合法 + 未过期）；不合法/过期一律丢弃 */
+  function isUsableToken(tokenEntry, nowTs) {
+    if (!tokenEntry || typeof tokenEntry.hash !== 'string' || typeof tokenEntry.expiresAt !== 'number') return false;
+    return tokenEntry.expiresAt > nowTs;
+  }
+
+  /** 把落盘记录灌进内存索引（过期与不合法条目直接跳过） */
+  function restoreTokens(entries, nowTs) {
+    for (const tokenEntry of entries) {
+      if (!isUsableToken(tokenEntry, nowTs)) continue;
+      tokens.set(tokenEntry.hash, {
+        user: tokenEntry.user || username,
+        expiresAt: tokenEntry.expiresAt,
+        issuedAt: tokenEntry.issuedAt || nowTs,
+      });
+    }
+  }
+
+  async function load() {
+    const storedTokens = await readJson(tokenFilePath, { tokens: [] });
+    if (!storedTokens.ok) {
+      if (storedTokens.reason !== 'not-found') {
+        logger.warn('auth token store unreadable, starting empty', { reason: storedTokens.reason });
+      }
+      return;
+    }
+    const entries = Array.isArray(storedTokens.data && storedTokens.data.tokens) ? storedTokens.data.tokens : [];
+    restoreTokens(entries, Date.now());
+    if (tokens.size > 0) logger.info('auth tokens restored', { count: tokens.size });
+  }
+
+  function schedulePersist() {
+    if (persistTimer) return;
+    persistTimer = setTimeout(() => {
+      persistTimer = null;
+      persist().catch((error) => logger.error('persist auth tokens failed', { error: error.message }));
+    }, TOKEN_PERSIST_THROTTLE_MS);
+    if (typeof persistTimer.unref === 'function') persistTimer.unref();
+  }
+
+  async function persist() {
+    const payload = {
+      version: 1,
+      updatedAt: new Date().toISOString(),
+      tokens: [...tokens.entries()].map(([hash, value]) => ({
+        hash, // sha256(token)：磁盘上无法反推出可登录明文
+        user: value.user,
+        issuedAt: value.issuedAt,
+        expiresAt: value.expiresAt,
+      })),
+    };
+    await writeJsonAtomic(tokenFilePath, payload);
+  }
+
+  /**
+   * 立即落盘（关停时调用）。
+   * 为什么需要：签发 token 后走的是 50ms 节流；若进程在这 50ms 内退出，
+   * 刚发出的 token 就没落盘 —— 重启后拿着有效凭据的客户端会突然 401（实测踩过）。
+   */
+  async function flush() {
+    if (persistTimer) {
+      clearTimeout(persistTimer);
+      persistTimer = null;
+    }
+    await persist();
+  }
+
+  // ===== Session =====
+
+  function createSession(user = username) {
+    const sid = randomToken(32);
+    const now = Date.now();
+    const expiresAt = now + sessionTtlMs;
+    sessions.set(sha256(sid), { user, expiresAt, issuedAt: now, lastSeenAt: now });
+    return { sid, expiresAt };
+  }
+
+  /**
+   * 校验 Session；命中且已过续期阈值时返回 renewed=true（调用方据此重发 Cookie）。
+   */
+  function verifySession(sid) {
+    if (!sid) return null;
+    const key = sha256(sid);
+    const session = sessions.get(key);
+    if (!session) return null;
+
+    const now = Date.now();
+    if (session.expiresAt <= now) {
+      sessions.delete(key);
+      return null;
+    }
+
+    session.lastSeenAt = now;
+    const remaining = session.expiresAt - now;
+    let renewed = false;
+    if (remaining < sessionTtlMs * RENEW_THRESHOLD_RATIO) {
+      session.expiresAt = now + sessionTtlMs;
+      renewed = true;
+    }
+    return { key, user: session.user, expiresAt: session.expiresAt, renewed };
+  }
+
+  function revokeSession(sid) {
+    if (!sid) return false;
+    return sessions.delete(sha256(sid));
+  }
+
+  // ===== Bearer Token =====
+
+  function createToken(user = username) {
+    const token = randomToken(32);
+    const now = Date.now();
+    const expiresAt = now + tokenTtlMs;
+    tokens.set(sha256(token), { user, expiresAt, issuedAt: now });
+    schedulePersist();
+    return { token, expiresAt };
+  }
+
+  function verifyToken(token) {
+    if (!token) return null;
+    const key = sha256(token);
+    const record = tokens.get(key);
+    if (!record) return null;
+    if (record.expiresAt <= Date.now()) {
+      tokens.delete(key);
+      schedulePersist();
+      return null;
+    }
+    return { key, user: record.user, expiresAt: record.expiresAt };
+  }
+
+  function revokeToken(token) {
+    const key = sha256(token);
+    const existed = tokens.delete(key);
+    if (existed) schedulePersist();
+    return existed;
+  }
+
+  // ===== 登录失败限流（内存计数，够 M1 用）=====
+
+  function isLoginBlocked(ip, limit) {
+    const record = loginFailures.get(ip);
+    if (!record) return false;
+    if (Date.now() - record.firstAt > limit.windowMs) {
+      loginFailures.delete(ip);
+      return false;
+    }
+    return record.count >= limit.max;
+  }
+
+  function recordLoginFailure(ip, limit) {
+    const now = Date.now();
+    const record = loginFailures.get(ip);
+    if (!record || now - record.firstAt > limit.windowMs) {
+      loginFailures.set(ip, { count: 1, firstAt: now });
+      return;
+    }
+    record.count += 1;
+  }
+
+  function clearLoginFailures(ip) {
+    loginFailures.delete(ip);
+  }
+
+  // ===== 过期清理（定时器 unref，不阻止进程退出）=====
+
+  function startCleanup() {
+    const timer = setInterval(() => {
+      const now = Date.now();
+      const removedTokens = pruneExpired(tokens, now);
+      pruneExpired(sessions, now);
+      pruneLoginFailures(loginFailures, config.loginRateLimit.windowMs, now);
+      if (removedTokens > 0) {
+        schedulePersist();
+        logger.debug('expired auth tokens cleaned', { removedTokens });
+      }
+    }, CLEANUP_INTERVAL_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+    return () => clearInterval(timer);
+  }
+
+  return {
+    load,
+    flush,
+    sessionTtlMs,
+    tokenTtlMs,
+    createSession,
+    verifySession,
+    revokeSession,
+    createToken,
+    verifyToken,
+    revokeToken,
+    isLoginBlocked,
+    recordLoginFailure,
+    clearLoginFailures,
+    startCleanup,
+    /** 仅用于测试/诊断，不暴露明文 */
+    stats: () => ({ sessions: sessions.size, tokens: tokens.size }),
+  };
+}

package/server/core/compress/blacklist.js

@@ -0,0 +1,236 @@
+// 压缩黑名单（三层：全局默认 / 用户自定义 / 任务级临时）+ 匹配与「命中哪一层」
+//
+// 契约：
+// - docs/04 §三：三层表 + 「命中后跳过但保留在原目录」（绝不能进删除集合）
+// - docs/M0/API规范.md §4.5：三端点形状；§4.2 目录列表的 blacklisted/blacklistLayer；
+//   §compress/preflight 的 skipped[]{path,pattern,layer}
+// - docs/09 §五：黑名单匹配归服务端（不信任前端）
+//
+// 为什么要单独一个模块：匹配规则会被三处消费 —— 预检（告知"会跳过几个"）、真实打包（真的不压）、
+// 目录列表（给每个条目标注）。三处必须用**同一份判定**，否则"预检说跳过 3 个、实际压了 3 个"这种
+// 漂移几乎必然会来。所以这里既提供纯函数（compile/resolve/match），也提供用户层的读写。
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { writeJsonAtomic } from '../../lib/atomic-json.js';
+
+/** 层名（对外字段 blacklistLayer 的取值；顺序即优先级：越靠前越具体） */
+export const BLACKLIST_LAYERS = Object.freeze({
+  TASK: 'task',
+  USER: 'user',
+  GLOBAL: 'global',
+});
+
+/**
+ * 全局默认层：已压缩格式 + 系统垃圾（不可删、不可改；可被任务级开关整体关掉）。
+ * 依据 docs/04 §四「智能跳过」表：jpg/png/mp4/mp3、zip/7z/rar/gz、docx/xlsx/pptx 再压几乎无收益。
+ * 系统垃圾（Thumbs.db/.DS_Store/@eaDir）本来就不该进包。
+ */
+export const GLOBAL_PATTERNS = Object.freeze([
+  // 只放**系统垃圾**：这些文件进包没有任何意义（缩略图缓存、Finder 元数据、群晖元目录）。
+  //
+  // 曾经默认还包含 jpg/png/mp4/zip/docx 等 12 个"已压缩格式"，已移除 ——
+  // 原因：打包不总是为了省空间（"把照片打包发给别人"是常见需求），默认静默跳过会让打包结果
+  // 与预期不符。机制保留：这些规则可以显式加进用户层，或在任务级用 extraPatterns 临时加。
+  'Thumbs.db',
+  '.DS_Store',
+  '@eaDir',
+]);
+
+/** 契约 §4.5 的校验上限 */
+export const MAX_PATTERN_LENGTH = 128;
+export const MAX_PATTERNS = 200;
+
+/** 用户层文件名（独立文件：config.json 是启动期只读快照，没有写回通道，不适合放用户可改的设置） */
+const USER_FILE = 'blacklist-user.json';
+
+/** 用户层默认值 */
+function emptyUserLayer() {
+  return { enabled: true, patterns: [], updatedAt: null };
+}
+
+/**
+ * 校验一串 pattern（PUT /blacklist/user 用）。
+ * 契约要求：单条 ≤128 字符、总数 ≤200、拒绝绝对路径与 `/`。
+ * 另外这里把"空串/纯空白"也拒掉（否则会变成"什么都不匹配"的死条目，用户看不出为什么没生效）。
+ * @returns {{ok: true, patterns: string[]} | {ok: false, message: string}}
+ */
+/** 单条校验（返回规范化后的字符串，或错误消息） */
+function validateOnePattern(raw) {
+  if (typeof raw !== 'string') return { ok: false, message: 'patterns 里每一项都必须是字符串' };
+  const pattern = raw.trim();
+  if (pattern.length === 0) return { ok: false, message: 'patterns 里不允许空字符串' };
+  if (pattern.length > MAX_PATTERN_LENGTH) return { ok: false, message: `单条 pattern 最多 ${MAX_PATTERN_LENGTH} 字符` };
+  // 绝对路径与分隔符：黑名单只描述"名字/扩展名"，不是路径规则（否则会误以为支持目录前缀）
+  if (pattern.includes('/') || pattern.includes('\\')) return { ok: false, message: `pattern 不允许包含路径分隔符：${pattern}` };
+  if (path.isAbsolute(pattern)) return { ok: false, message: `pattern 不允许是绝对路径：${pattern}` };
+  return { ok: true, pattern };
+}
+
+export function validatePatterns(rawPatterns) {
+  if (!Array.isArray(rawPatterns)) return { ok: false, message: 'patterns 必须是字符串数组' };
+  if (rawPatterns.length > MAX_PATTERNS) return { ok: false, message: `patterns 最多 ${MAX_PATTERNS} 条` };
+
+  const patterns = [];
+  for (const raw of rawPatterns) {
+    const checked = validateOnePattern(raw);
+    if (!checked.ok) return checked;
+    if (!patterns.includes(checked.pattern)) patterns.push(checked.pattern);
+  }
+  return { ok: true, patterns };
+}
+
+/**
+ * 单条 pattern → 判定器。
+ * 支持的三种形态（契约 §4.5「按扩展名 / 按文件名」+ 全局层里的 @eaDir 目录名）：
+ *   - `*.jpg` → 扩展名（大小写不敏感；`*.gz` 也能命中 `a.tar.gz`，因为按后缀比）
+ *   - `Thumbs.db` / `.DS_Store` → 精确文件名（大小写不敏感：NAS 上大小写混写很常见）
+ *   - `@eaDir` → 任一路径段同名（这样 @eaDir 里的文件也一并跳过）
+ * @param {string} pattern
+ * @returns {{pattern: string, test: (name: string, segments: string[]) => boolean}}
+ */
+export function compilePattern(pattern) {
+  const lowered = pattern.toLowerCase();
+  if (lowered.startsWith('*.')) {
+    const suffix = lowered.slice(1); // '*.jpg' → '.jpg'
+    return {
+      pattern,
+      test: (name) => name.toLowerCase().endsWith(suffix),
+    };
+  }
+  return {
+    pattern,
+    test: (name, segments) => name.toLowerCase() === lowered
+      || (Array.isArray(segments) && segments.some((segment) => segment.toLowerCase() === lowered)),
+  };
+}
+
+/**
+ * 把三层解析成"按优先级排好的判定层"（task > user > global）。
+ * 关掉的层不参与匹配；`enabled:false` 的任务级开关表示**整条黑名单不生效**（三层都跳过）。
+ * @param {object} input
+ * @param {{enabled?: boolean, patterns?: string[]}} [input.task] 任务级临时层（extraPatterns）
+ * @param {{enabled?: boolean, patterns?: string[]}} [input.user] 用户层
+ * @param {{enabled?: boolean}} [input.global] 全局层（默认开）
+ * @returns {Array<{layer: string, enabled: boolean, patterns: string[]}>}
+ */
+export function resolveLayers({ task, user, global } = {}) {
+  const layers = [];
+  if (task && task.enabled !== false && Array.isArray(task.patterns) && task.patterns.length > 0) {
+    layers.push({ layer: BLACKLIST_LAYERS.TASK, patterns: task.patterns });
+  }
+  if (user && user.enabled !== false && Array.isArray(user.patterns) && user.patterns.length > 0) {
+    layers.push({ layer: BLACKLIST_LAYERS.USER, patterns: user.patterns });
+  }
+  if (!global || global.enabled !== false) {
+    layers.push({ layer: BLACKLIST_LAYERS.GLOBAL, patterns: [...GLOBAL_PATTERNS] });
+  }
+  return layers;
+}
+
+/**
+ * 判定一个条目。
+ * @param {Array<{layer: string, patterns: string[]}>} layers resolveLayers() 的结果（已按优先级排列）
+ * @param {{name: string, segments?: string[]}} entry name=文件名；segments=相对路径的各段（用于目录名规则）
+ * @returns {{pattern: string, layer: string} | null} 命中返回到层与 pattern，未命中 null
+ */
+export function matchEntry(layers, entry) {
+  if (!Array.isArray(layers) || layers.length === 0) return null;
+  const name = String((entry && entry.name) || '');
+  if (!name) return null;
+  const segments = Array.isArray(entry.segments) ? entry.segments : [];
+  for (const layer of layers) {
+    for (const pattern of layer.patterns) {
+      if (compilePattern(pattern).test(name, segments)) {
+        return { pattern, layer: layer.layer };
+      }
+    }
+  }
+  return null;
+}
+
+/** 有效 pattern 条数（GET /blacklist 的 effectiveCount：三层去重后总数） */
+export function countEffective(layers) {
+  const seen = new Set();
+  for (const layer of layers || []) {
+    for (const pattern of layer.patterns || []) seen.add(pattern.toLowerCase());
+  }
+  return seen.size;
+}
+
+/**
+ * 黑名单服务：持有用户层的读写（其余两层由调用方传入）。
+ * 用户层落盘到 `<dataDir>/blacklist-user.json`，原子写（写坏一个文件不该让设置彻底失效）。
+ */
+export function createBlacklistService({ dataDir, logger }) {
+  const userFile = path.join(dataDir, USER_FILE);
+  let cached = null; // 懒加载缓存：GET /blacklist 与预检都可能频繁读
+
+  /** 读用户层（缓存 + 文件；读取失败按默认值，并告警 —— 不能因为一个坏文件让压缩任务起不来） */
+  async function loadUser() {
+    if (cached) return cached;
+    try {
+      const text = await fsp.readFile(userFile, 'utf8');
+      const parsed = JSON.parse(text);
+      const checked = validatePatterns(parsed && parsed.patterns);
+      cached = {
+        enabled: parsed && parsed.enabled !== false,
+        patterns: checked.ok ? checked.patterns : [],
+        updatedAt: Number.isFinite(parsed && parsed.updatedAt) ? parsed.updatedAt : null,
+      };
+      if (!checked.ok) logger.warn('blacklist 用户层文件不合法，已按空处理', { reason: checked.message });
+    } catch (error) {
+      if (error.code !== 'ENOENT') logger.warn('blacklist 用户层读取失败，按默认值处理', { error: error.message });
+      cached = emptyUserLayer();
+    }
+    return cached;
+  }
+
+  /** 全量替换用户层（幂等）；返回替换后的用户层 */
+  async function replaceUser({ patterns, enabled }) {
+    const checked = validatePatterns(patterns);
+    if (!checked.ok) {
+      const error = new Error(checked.message);
+      error.validation = true;
+      throw error;
+    }
+    const next = {
+      enabled: enabled !== false,
+      patterns: checked.patterns,
+      updatedAt: Date.now(),
+    };
+    await fsp.mkdir(dataDir, { recursive: true });
+    await writeJsonAtomic(userFile, { version: 1, ...next });
+    cached = next;
+    return next;
+  }
+
+  /** 三层快照（GET /blacklist 的 data；global 的 enabled 恒 true —— 契约 locked 表示不可改） */
+  async function snapshot({ taskPatterns = [] } = {}) {
+    const user = await loadUser();
+    const layers = resolveLayers({
+      task: { enabled: true, patterns: taskPatterns },
+      user,
+      global: { enabled: true },
+    });
+    return {
+      global: { locked: true, enabled: true, patterns: [...GLOBAL_PATTERNS] },
+      user: { enabled: user.enabled, patterns: [...user.patterns], updatedAt: user.updatedAt },
+      effectiveCount: countEffective(layers),
+    };
+  }
+
+  /** 解析出本次判定用的层（taskPatterns = 任务级临时层；enabled=false 表示整条黑名单关掉） */
+  async function layersFor({ enabled = true, taskPatterns = [] } = {}) {
+    if (!enabled) return [];
+    const user = await loadUser();
+    return resolveLayers({
+      task: { enabled: true, patterns: taskPatterns },
+      user,
+      global: { enabled: true },
+    });
+  }
+
+  return { loadUser, replaceUser, snapshot, layersFor, userFile };
+}

package/server/core/compress/capRegistry.js

@@ -0,0 +1,171 @@
+// 能力注册表（docs/19 §三/§五 图 1：扫 capabilities/<id>/index.js）
+//
+// 照 registry.js 的模式：
+// - 自动发现：扫描 server/plugins/capabilities/<id>/index.js；
+// - 启动校验：必需成员/方法齐全；**不合规只禁用该包并告警，不影响其他包**；
+// - 额外对账：appliesTo 声明的格式 id 必须存在于格式注册表（双向声明任一方缺失即不生效，
+//   docs/19 §4.2——避免「格式说支持但能力没实现」或反之）；
+// - 运行时重扫：目录 mtime 变化即重扫（与 registry 一致，加能力包零改动生效）。
+//
+// 与 registry 的差异：能力不参与「按扩展名匹配」，索引只有 id；
+// 查询口径是「某格式启用的能力集合」= 格式 capabilities ∩ 能力 appliesTo ∩ 能力已加载。
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { CAPABILITY_IDS } from '../../../shared/capabilities.js';
+
+const DEFAULT_CAPS_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../plugins/capabilities',
+);
+
+/** 能力契约必需成员（docs/19 §4.2） */
+const REQUIRED_MEMBERS = ['id', 'name', 'appliesTo', 'params'];
+const REQUIRED_METHODS = ['validateParams', 'prepareCreate', 'verify', 'prepareExtract', 'redact'];
+
+function validateCapability(cap, source) {
+  const problems = [];
+  for (const member of REQUIRED_MEMBERS) {
+    if (cap[member] === undefined) problems.push(`缺少成员 ${member}`);
+  }
+  for (const method of REQUIRED_METHODS) {
+    if (typeof cap[method] !== 'function') problems.push(`缺少方法 ${method}()`);
+  }
+  if (Array.isArray(cap.appliesTo) === false) problems.push('appliesTo 必须是数组');
+  if (problems.length > 0) {
+    return { ok: false, reason: `${source}: ${problems.join('；')}` };
+  }
+  return { ok: true };
+}
+
+export function createCapabilityRegistry(options = {}) {
+  const logger = options.logger || { info() {}, warn() {} };
+  const capsDir = options.capsDir || DEFAULT_CAPS_DIR;
+  /** 格式 id 列表（对账用；由 orchestrator/启动流程喂进来或用 isFormatKnown 动态查） */
+  const knownFormatIds = new Set(options.formatIds || []);
+  const byId = new Map();
+  const loadFailures = [];
+  let lastScanMtimeMs = 0;
+
+  /** 已加载能力 ∩ 已声明该能力的格式 ∩ 能力 appliesTo → 三方交集查询 */
+  function capabilitiesForFormat(formatId) {
+    const result = [];
+    for (const cap of byId.values()) {
+      if (Array.isArray(cap.appliesTo) && cap.appliesTo.includes(formatId)) result.push(cap);
+    }
+    return result;
+  }
+
+  /**
+   * 校验「格式声明了能力但能力不存在/不适用」——PW-4 的数据面：后端独立判定。
+   * 返回 {ok, reason?}；格式未声明任何能力 → ok（能力交集为空，装配循环自然跳过）。
+   */
+  function checkFormatCapabilities(plugin) {
+    const declared = plugin.capabilities || [];
+    for (const capId of declared) {
+      const cap = byId.get(capId);
+      if (!cap) return { ok: false, reason: `格式 ${plugin.id} 声明的能力 ${capId} 未加载` };
+      if (!cap.appliesTo.includes(plugin.id)) {
+        return { ok: false, reason: `能力 ${capId} 不适用于格式 ${plugin.id}` };
+      }
+    }
+    return { ok: true };
+  }
+
+  async function rescan() {
+    let dirStat;
+    try {
+      dirStat = await fs.stat(capsDir);
+    } catch {
+      return; // 目录不存在 = 尚无任何能力插件（合法状态）
+    }
+    if (dirStat.mtimeMs === lastScanMtimeMs && byId.size > 0) return; // 无变化
+    lastScanMtimeMs = dirStat.mtimeMs;
+
+    byId.clear();
+    let entries;
+    try {
+      entries = await fs.readdir(capsDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (!CAPABILITY_IDS.includes(entry.name)) continue; // 白名单外不加载（未知能力不静默启用）
+      const source = path.join(capsDir, entry.name, 'index.js');
+      try {
+        const module = await import(`${source}?t=${Date.now()}`);
+        const cap = module.default;
+        const verdict = validateCapability(cap, source);
+        if (!verdict.ok) {
+          loadFailures.push(verdict.reason);
+          logger.warn('capability plugin rejected', { reason: verdict.reason });
+          continue;
+        }
+        // 对账：appliesTo 里的格式如果已知名单里没有，记告警（格式包可能还没装）
+        for (const formatId of cap.appliesTo) {
+          if (knownFormatIds.size > 0 && !knownFormatIds.has(formatId)) {
+            logger.warn('能力 appliesTo 指向未知格式（对账告警，不阻止加载）', { capability: cap.id, formatId });
+          }
+        }
+        byId.set(cap.id, cap);
+      } catch (error) {
+        loadFailures.push(`${source}: ${error.message}`);
+        logger.warn('capability plugin rejected', { reason: `${source}: ${error.message}` });
+      }
+    }
+    if (loadFailures.length > 0) logger.warn('capability registry load failures', { count: loadFailures.length });
+  }
+
+  /**
+   * 落盘脱敏（PW-1）：遍历任务 options.capabilities，用各能力的 redact() 剔除 secret
+   * 字段（明文永不落 tasks.json）。manager 不认识具体能力，由 registry 提供通用剥离器。
+   * 能力未加载但参数还在（重启后重试场景）→ 保留方法名等非敏感字段，剔除 password。
+   */
+  function sanitizeOptionsForPersist(options) {
+    if (!options) return options;
+    // P4：解压侧的顶层 options.password 同样是明文（PW-1）——落盘时替换为 hasPassword 布尔
+    const hasTopPassword = typeof options.password === 'string' && options.password.length > 0;
+    const caps = options.capabilities;
+    if (!caps || typeof caps !== 'object') {
+      if (!hasTopPassword) return options;
+      const { password: _removed, ...rest } = options;
+      return { ...rest, hasPassword: true };
+    }
+    const sanitized = { ...options, capabilities: {} };
+    for (const [capId, params] of Object.entries(caps)) {
+      const cap = byId.get(capId);
+      if (cap && typeof cap.redact === 'function') {
+        sanitized.capabilities[capId] = cap.redact(params);
+        continue;
+      }
+      const filtered = {};
+      for (const [key, value] of Object.entries(params || {})) {
+        const isSecret = Boolean(value) && (key === 'password' || key === 'value');
+        if (!isSecret) filtered[key] = value;
+      }
+      sanitized.capabilities[capId] = filtered;
+    }
+    if (hasTopPassword) {
+      delete sanitized.password;
+      sanitized.hasPassword = true;
+    }
+    return sanitized;
+  }
+
+  return {
+    /** 启动/变更时重扫（幂等） */
+    rescan,
+    /** 查某格式启用的能力集合（已加载 ∩ appliesTo；格式自己的 capabilities 声明由调用方用 checkFormatCapabilities 校验） */
+    capabilitiesForFormat,
+    checkFormatCapabilities,
+    /** PW-1：任务落盘前的通用脱敏器（剔除 capabilities 里的 secret 字段） */
+    sanitizeOptionsForPersist,
+    /** 能力元数据（给 GET /capabilities/:id：脱敏字段描述 + methods 动态列表） */
+    get: (id) => byId.get(id) || null,
+    list: () => [...byId.values()],
+    loadFailures: () => [...loadFailures],
+  };
+}