@logictan/dsh-config-manager 0.1.60

package/src/core/exporter.ts

@@ -0,0 +1,417 @@
+/**
+ * Export 编排（规范 §1/§18/§21，设计 §4.4）：
+ *   adapter 收集各分区 → Secret 过滤 → manifest → checksum → ZIP。
+ *
+ * 安全不变量：
+ *  - Secret 值默认永不进入导出数据（结构化分区逐一过 SecretScanner）；
+ *  - includeSecrets=true 必须注入 EncryptionProvider（m4 实现），否则拒绝导出；
+ *  - 注入 EncryptionProvider 时备份标记为加密（encrypted=true）：includeSecrets=false
+ *    时 secrets.enc 加密空内容占位，备份仍需要密码导入，但不含任何凭据值；
+ *  - 加密密码/秘密值绝不写入 manifest 与日志。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { buildChecksums } from '../utils/hashing.ts';
+import { stringifyJsonSafe } from '../utils/json.ts';
+import { buildManifest, CHECKSUMS_FILE, MANIFEST_FILE, EXPORTER_NAME } from '../schema/manifest.ts';
+import { SECTION_JSON_PATHS, SECTION_FILE_PREFIXES, isFileSection } from '../schema/config.ts';
+import { DEFAULT_SENSITIVE_RELS, refreshVault } from '../security/vault.ts';
+import { writeZip } from '../utils/zip.ts';
+import { msgOf } from './messages.ts';
+import type { MsgFunc } from './messages.ts';
+import type { Manifest, SectionId } from '../schema/types.ts';
+import type {
+  ConfigAdapter, EncryptionProvider, ExportOptions, ExportReport,
+  ExportSection, HostContext, SecretScanner, SensitiveHit,
+} from './types.ts';
+
+/** m1：每导出一个分区前的进度回调信息（Host 侧 run 状态更新用；section = adapter id） */
+export interface SectionProgress {
+  section: string;
+  /** 当前分区序号（1 起） */
+  index: number;
+  /** 选中分区总数 */
+  total: number;
+}
+
+export interface ExporterOptions {
+  ctx: HostContext;
+  adapters: ConfigAdapter[];
+  /** Secret 扫描器；缺省用字段名黑名单剥离（m4 可注入强化版） */
+  scanner?: SecretScanner;
+  /** 加密提供者（m4 用 node:crypto 实现）；includeSecrets 时必填；提供时备份标记 encrypted=true */
+  encryption?: EncryptionProvider | null;
+  /** 插件自身版本（manifest.exporter.version） */
+  exporterVersion?: string;
+  now?: () => Date;
+  /** 消息翻译器（缺省 ctx.msg ?? zh） */
+  msg?: MsgFunc;
+  /** m1：每导出一个分区前调用（真实进度埋点；不传则无埋点） */
+  onSection?: (info: SectionProgress) => void;
+  /**
+   * 插件数据目录（文件级 vault 位于 <vaultDataDir>/vault，缺省 <homeDir>/dsh-config-manager）。
+   * includeSecrets=false 时导出会自动刷新 vault；宿主自定义 dataDir 时应注入实际值
+   * （HostContext 不携带 dataDir，故经选项注入）。
+   */
+  vaultDataDir?: string;
+}
+
+/** 缺省 SecretScanner：递归黑名单字段剥离（字段名大小写不敏感；二进制/Uint8Array 原样跳过） */
+export function defaultSecretScanner(): SecretScanner {
+  const SENSITIVE_FIELDS = [
+    'password', 'passwd', 'token', 'accesstoken', 'refreshtoken', 'apikey',
+    'secret', 'credential', 'authorization', 'cookie', 'privatekey', 'clientsecret',
+  ];
+  /** 仅存「引用名」而非值的字段（如 apiKeyEnv=DEEPSEEK_API_KEY 是环境变量名，不是秘密） */
+  const REFERENCE_FIELDS = new Set([
+    'apikeyenv', 'api_key_env', 'apikeyname', 'tokenenv', 'accesstokenenv',
+    'refreshtokenenv', 'clientsecretenv', 'passwordenv',
+  ]);
+  return {
+    scanAndRedact(data: unknown): { sanitized: unknown; hits: SensitiveHit[] } {
+      const hits: SensitiveHit[] = [];
+      const walk = (v: unknown, p: string): unknown => {
+        if (v === null || typeof v !== 'object') return v;
+        if (v instanceof Uint8Array) return v; // 二进制内容不按字段展开
+        if (Array.isArray(v)) return v.map((item, i) => walk(item, `${p}[${i}]`));
+        const out: Record<string, unknown> = {};
+        for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+          const lower = k.toLowerCase().replace(/[^a-z0-9]/g, '');
+          const isRefName = REFERENCE_FIELDS.has(lower);
+          const sensitive = !isRefName && SENSITIVE_FIELDS.some((f) => lower.includes(f));
+          if (sensitive && typeof val === 'string' && val !== '') {
+            hits.push({ path: p === '' ? k : `${p}.${k}`, field: k });
+            out[k] = ''; // 值剥离为空串（保留字段名与位置，供「需补录」提示）
+            continue;
+          }
+          out[k] = walk(val, p === '' ? k : `${p}.${k}`);
+        }
+        return out;
+      };
+      return { sanitized: walk(data, ''), hits };
+    },
+  };
+}
+
+/* ---------------- G-09：文件类分区文本级扫描（只报告，绝不改写） ---------------- */
+
+/**
+ * 单文件扫描字节上限（1 MiB）。超大文件只扫描前 1 MiB：
+ * 凭据通常出现在配置/脚本的头部；超过上限的剩余部分放弃扫描，避免单个巨型文件拖垮导出。
+ */
+export const FILE_SECTION_SCAN_MAX_BYTES = 1024 * 1024;
+
+/** 一次导出中所有文件类分区的累计扫描字节上限（16 MiB），防「成千上万小文件」拖慢导出 */
+export const FILE_SECTION_SCAN_TOTAL_BUDGET_BYTES = 16 * 1024 * 1024;
+
+/** 每个分区最多告警的**不同文件**数（不是 hit 条数）；命中仍全量计入 redactedHits（报告统计通道），超出部分由一条汇总告警兜底，避免「真有凭据的文件被静默淹没」或「截断即静默丢失」 */
+export const MAX_FILE_SECTION_WARNINGS_PER_SECTION = 5;
+
+/** 二进制探测窗口（前 4 KiB 出现 NUL 即视为二进制，不按文本扫描） */
+const BINARY_SNIFF_BYTES = 4096;
+
+/** 是否为二进制内容（含 NUL 字节 → 不是 UTF-8 文本；避免对二进制做无意义的文本扫描/误报） */
+function looksBinary(bytes: Uint8Array): boolean {
+  const n = Math.min(bytes.length, BINARY_SNIFF_BYTES);
+  for (let i = 0; i < n; i++) {
+    if (bytes[i] === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * 文件类分区内容扫描（G-09）：
+ *  - 走注入 scanner 的 `scanText`（只报告不改写；`scanAndRedact` 会剥离值，**不得**用于用户文件）；
+ *  - 扫描档位与 `src/market/prepare.ts` 的导出侧扫描保持一致：默认保守档 +
+ *    值形状启发式（`valuePatterns` 默认开），**不启用** `highEntropy`（默认关，误报率高）；
+ *  - 二进制文件（含 NUL）跳过：文本扫描对它无意义且必然误报；
+ *  - 单文件上限 `FILE_SECTION_SCAN_MAX_BYTES`、累计上限 `FILE_SECTION_SCAN_TOTAL_BUDGET_BYTES`：
+ *    超限即停止扫描（不是停止导出），被跳过的部分不产生命中也不产生告警；
+ *  - scanner 未实现 `scanText`（如 core 内置的字段名黑名单 defaultSecretScanner）→ 返回空，
+ *    行为与修复前一致（生产路径注入的是含 scanText 的强化扫描器）。
+ *
+ * 返回命中清单，`path` 为「分区内文件相对路径」，`field` 为 `line:N`（值永不外泄）。
+ */
+function scanFileSectionText(scanner: SecretScanner, data: unknown): SensitiveHit[] {
+  const scanText = scanner.scanText;
+  if (typeof scanText !== 'function') return [];
+  const files = extractFileEntries(data);
+  if (files === null) return [];
+
+  const hits: SensitiveHit[] = [];
+  let budget = FILE_SECTION_SCAN_TOTAL_BUDGET_BYTES;
+  for (const file of files) {
+    if (budget <= 0) break;
+    const bytes = file.data;
+    if (!(bytes instanceof Uint8Array) || bytes.length === 0) continue;
+    const window = bytes.subarray(0, Math.min(bytes.length, FILE_SECTION_SCAN_MAX_BYTES, budget));
+    budget -= window.length;
+    if (looksBinary(window)) continue;
+    let text: string;
+    try {
+      text = new TextDecoder('utf-8').decode(window);
+    } catch {
+      continue;
+    }
+    for (const hit of scanText(text)) {
+      hits.push({ path: file.relativePath, field: hit.path });
+    }
+  }
+  return hits;
+}
+
+/** 从分区数据里取出文件条目（非文件类/结构异常 → null；只看 files 数组，不展开其他字段） */
+function extractFileEntries(data: unknown): { relativePath: string; data: Uint8Array }[] | null {
+  if (data === null || typeof data !== 'object') return null;
+  const files = (data as { files?: unknown }).files;
+  if (!Array.isArray(files)) return null;
+  return files.filter((f): f is { relativePath: string; data: Uint8Array } => (
+    f !== null && typeof f === 'object'
+    && typeof (f as { relativePath?: unknown }).relativePath === 'string'
+    && (f as { data?: unknown }).data instanceof Uint8Array
+  ));
+}
+
+export class Exporter {
+  private readonly ctx: HostContext;
+  private readonly adapters: ConfigAdapter[];
+  private readonly scanner: SecretScanner;
+  private readonly encryption: EncryptionProvider | null;
+  private readonly exporterVersion: string;
+  private readonly now: () => Date;
+  private readonly msg: MsgFunc;
+  private readonly onSection: ((info: SectionProgress) => void) | undefined;
+  private readonly vaultDataDir: string;
+
+  constructor(opts: ExporterOptions) {
+    this.ctx = opts.ctx;
+    this.adapters = opts.adapters;
+    this.scanner = opts.scanner ?? defaultSecretScanner();
+    this.encryption = opts.encryption ?? null;
+    this.exporterVersion = opts.exporterVersion ?? '0.1.0';
+    this.now = opts.now ?? (() => new Date());
+    this.msg = opts.msg ?? msgOf(opts.ctx);
+    this.onSection = opts.onSection;
+    this.vaultDataDir = opts.vaultDataDir ?? path.join(opts.ctx.homeDir, 'dsh-config-manager');
+  }
+
+  /**
+   * 导出：收集 → 过滤 → checksum → manifest → ZIP。
+   * 返回 zipPath（含文件名）、manifest、报告。
+   */
+  async export(options: ExportOptions): Promise<{ zipPath: string; manifest: Manifest; report: ExportReport }> {
+    const { includeSecrets, only } = options;
+    if (includeSecrets && !this.encryption) {
+      throw new Error(this.msg('export.encryptionRequired'));
+    }
+
+    // 1. 选定分区（only 过滤 + 默认包含）
+    const selected = this.adapters
+      .filter((a) => (only === undefined ? a.defaultIncluded : only.includes(a.id)))
+      .map((a) => a.id);
+
+    // 2. 逐 adapter 收集（导出数据）
+    const sections: ExportSection[] = [];
+    const warnings: string[] = [];
+    const redactedHits: SensitiveHit[] = [];
+    const included: ExportReport['included'] = [];
+    const excluded: SectionId[] = this.adapters.filter((a) => !selected.includes(a.id)).map((a) => a.id);
+
+    // m1 埋点：每导出一个分区前上报真实进度（onSection 抛错不得中断导出）
+    let sectionIndex = 0;
+    for (const adapter of this.adapters) {
+      if (!selected.includes(adapter.id)) continue;
+      sectionIndex += 1;
+      try {
+        this.onSection?.({ section: adapter.id, index: sectionIndex, total: selected.length });
+      } catch {
+        // 埋点回调失败不影响导出本身（进度是尽力而为）
+      }
+      let section: ExportSection;
+      try {
+        section = await adapter.export(this.ctx, options);
+      } catch (err) {
+        // 单个分区失败不拖垮整体（§34.17）；如实告警并跳过
+        warnings.push(this.msg('export.sectionFailed', { adapter: adapter.id, reason: err instanceof Error ? err.message : String(err) }));
+        excluded.push(adapter.id);
+        continue;
+      }
+      // 3. Secret 过滤：结构化数据逐一过 scanner（剥离值）；
+      //    文件类分区（skills/agentPresets/agentInstructions/pluginFiles/sessions/self）是用户的真实文件，
+      //    只做**文本级扫描 + 告警**，绝不改写/剥离内容（见 scanFileSectionText）。
+      let sanitized = section.data;
+      if (!isFileSection(adapter.id)) {
+        const scanned = this.scanner.scanAndRedact(section.data);
+        redactedHits.push(...scanned.hits);
+        sanitized = scanned.sanitized;
+      } else {
+        const fileHits = scanFileSectionText(this.scanner, section.data);
+        if (fileHits.length > 0) {
+          // redactedHits 是**报告统计**通道（非告警通道）：仍计入全量命中（含同一文件的多行/多形态命中）。
+          redactedHits.push(...fileHits);
+          // 告警按**文件**去重（G-09/H1）：同一路径只告警一次。
+          // 修复前按 hit 计数，同一行同时命中「字段名」与「值形状」会产出两条同路径告警，
+          // 使少数文件就吃满上限，导致含真实明文凭据的其它文件被静默淹没（实测 redactedHits=8 而 5 条告警全属一个文件）。
+          const hitPaths: string[] = [];
+          const seenPaths = new Set<string>();
+          for (const hit of fileHits) {
+            if (seenPaths.has(hit.path)) continue;
+            seenPaths.add(hit.path);
+            hitPaths.push(hit.path);
+          }
+          // 上限语义 = 不同**文件**数 ≤ MAX_FILE_SECTION_WARNINGS_PER_SECTION（避免大分区刷屏）
+          const warnedPaths = hitPaths.slice(0, MAX_FILE_SECTION_WARNINGS_PER_SECTION);
+          for (const hitPath of warnedPaths) {
+            warnings.push(this.msg('export.fileSectionSecrets', { section: adapter.id, path: hitPath }));
+          }
+          // 被截断的文件数必须**显式**汇总告警，否则截断本身又变成静默丢失。
+          // 说明：此处未新增消息键（如 export.fileSectionSecretsTruncated）是为避免与并行任务冲突
+          // （src/core/messages.ts 属他人改动范围）；故复用 export.fileSectionSecrets，仅 path 传汇总文案。
+          const truncatedCount = hitPaths.length - warnedPaths.length;
+          if (truncatedCount > 0) {
+            warnings.push(this.msg('export.fileSectionSecrets', { section: adapter.id, path: `（另有 ${truncatedCount} 个文件命中，详见报告）` }));
+          }
+        }
+      }
+      sections.push({ ...section, data: sanitized });
+      included.push({ section: adapter.id, counts: section.counts });
+      warnings.push(...section.warnings);
+    }
+
+    // 4. 组装 ZIP 条目（JSON 分区 + 文件类分区 + secrets.enc + checksums + manifest）
+    const entries: { name: string; data: Uint8Array }[] = [];
+    const sectionFlags = buildSectionFlags(sections);
+    let containsSecrets = false;
+    let encrypted = false;
+    let encryption: Manifest['security']['encryption'] = null;
+
+    for (const section of sections) {
+      if (isFileSection(section.sectionId)) {
+        const prefix = SECTION_FILE_PREFIXES[section.sectionId]!;
+        const files = (section.data as { files?: { relativePath: string; data: Uint8Array }[] }).files ?? [];
+        for (const file of files) {
+          entries.push({ name: `${prefix}${file.relativePath}`, data: file.data });
+        }
+        continue;
+      }
+      const jsonPath = SECTION_JSON_PATHS[section.sectionId];
+      if (jsonPath === undefined) continue;
+      entries.push({
+        name: jsonPath,
+        data: Buffer.from(stringifyJsonSafe(section.data, { space: 2 }), 'utf8'),
+      });
+    }
+
+    // secrets.enc：有加密提供者即生成。includeSecrets=true 时加密真实的凭据原文；
+    // 只勾选加密（不导出密钥）时加密空内容占位，备份仍标记 encrypted（导入需密码），
+    // 但绝不把凭据值放进去（containsSecrets 保持 false；安全不变量不破）。
+    if (this.encryption) {
+      const credentialsFile = path.join(this.ctx.homeDir, '.credentials.yaml');
+      let plaintext: string;
+      if (includeSecrets) {
+        try {
+          const raw = await this.ctx.fs.readFile(credentialsFile);
+          plaintext = Buffer.from(raw).toString('utf8');
+        } catch (err) {
+          warnings.push(this.msg('export.credentialsReadFailed', { reason: err instanceof Error ? err.message : String(err) }));
+          plaintext = '';
+        }
+      } else {
+        plaintext = '';
+      }
+      const result = await this.encryption.encrypt(plaintext);
+      entries.push({ name: 'security/secrets.enc', data: result.blob });
+      encryption = result.info;
+      containsSecrets = includeSecrets && plaintext !== '';
+      encrypted = true;
+    }
+
+    // 4b. 文件级 vault（includeSecrets=false：敏感文件明文不进归档 → 镜像到本机 vault）。
+    //     尽力而为：任何失败仅记警告，不中断导出。includeSecrets=true 时秘密已加密进归档，
+    //     无需镜像（vault 只服务于「明文不进备份」的本机留存场景）。
+    let vaultRefreshed = 0;
+    if (!includeSecrets) {
+      try {
+        const vault = await refreshVault(this.ctx.fs, this.vaultDataDir, this.ctx.homeDir, DEFAULT_SENSITIVE_RELS);
+        vaultRefreshed = vault.mirrored.length;
+        if (vault.mirrored.length > 0) {
+          warnings.push(this.msg('export.vaultRefreshed', { count: vault.mirrored.length }));
+        }
+        for (const s of vault.skipped) {
+          warnings.push(this.msg('export.vaultRefreshSkipped', { rel: s.rel, reason: s.reason }));
+        }
+      } catch (err) {
+        warnings.push(this.msg('export.vaultRefreshFailed', { reason: err instanceof Error ? err.message : String(err) }));
+      }
+    }
+
+    // 5. checksums（覆盖除 manifest/checksums 外的全部条目）
+    const checksums = buildChecksums(entries);
+    entries.push({ name: CHECKSUMS_FILE, data: Buffer.from(stringifyJsonSafe(checksums, { space: 2 }), 'utf8') });
+
+    // 6. manifest（最后写：需要完整分区与安全信息）
+    const manifest = buildManifest({
+      exporterVersion: this.exporterVersion,
+      dshVersion: this.ctx.dshVersion,
+      platform: this.ctx.platform as Manifest['source']['platform'],
+      arch: this.ctx.arch,
+      sections: sectionFlags,
+      containsSecrets,
+      encrypted,
+      encryption,
+      exportedAt: this.now().toISOString(),
+    });
+    entries.push({ name: MANIFEST_FILE, data: Buffer.from(stringifyJsonSafe(manifest, { space: 2 }), 'utf8') });
+
+    // 7. 落盘
+    const outPath = options.outPath ?? defaultOutPath(this.now());
+    await writeZip(outPath, entries);
+    const stat = await fs.stat(outPath);
+
+    // 日志不泄值：只记分区与命中数量
+    this.ctx.log.info('导出完成', {
+      file: path.basename(outPath),
+      sizeBytes: stat.size,
+      sections: Object.keys(sectionFlags).filter((k) => sectionFlags[k as SectionId]),
+      redactedFields: redactedHits.length,
+      containsSecrets,
+      encrypted,
+      vaultRefreshed,
+    });
+
+    const report: ExportReport = {
+      included,
+      excluded,
+      security: {
+        secretsExcluded: !includeSecrets,
+        containsSecrets,
+        encrypted,
+        redactedHits: redactedHits.length,
+        vaultRefreshed,
+      },
+      file: { name: path.basename(outPath), sizeBytes: stat.size },
+      warnings,
+    };
+    return { zipPath: outPath, manifest, report };
+  }
+}
+
+/** 构建 manifest.sections 布尔表（只含实际导出分区） */
+function buildSectionFlags(sections: ExportSection[]): Manifest['sections'] {
+  const flags = {} as Manifest['sections'];
+  for (const id of Object.keys(SECTION_JSON_PATHS) as SectionId[]) flags[id] = false;
+  for (const id of Object.keys(SECTION_FILE_PREFIXES) as SectionId[]) flags[id] = false;
+  flags['secrets'] = false;
+  for (const section of sections) flags[section.sectionId] = true;
+  return flags;
+}
+
+function defaultOutPath(now: Date): string {
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  return `dsh-config-${y}-${m}-${d}.zip`;
+}
+
+/** 供报告使用：导出器身份（避免与 manifest 常量重复维护） */
+export const EXPORTER_INFO = { name: EXPORTER_NAME };

package/src/core/ghost-sweep.test.ts

@@ -0,0 +1,94 @@
+/**
+ * 幽灵会话检测纯函数单测（F5 失效归档清理）。
+ * 覆盖：sessionKeyOf 归一化（Unix/Windows 分隔符、缺段、空串）、
+ * sweepGhostSessions 缺失/存在/混合/去重/磁盘多余会话不算幽灵、
+ * expectedSessionRefs 只取 sessions 分区 existed=true 的 file 条目。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { expectedSessionRefs, sessionKeyOf, sweepGhostSessions } from './ghost-sweep.ts';
+import type { SnapshotEntry } from './types.ts';
+
+test('G-01 sessionKeyOf：归一为 <projectKey>/<sessionId>', () => {
+  assert.equal(sessionKeyOf('proj-a/s1/session.jsonl.zstd'), 'proj-a/s1');
+  assert.equal(sessionKeyOf('proj-a/s1/meta.json'), 'proj-a/s1');
+  assert.equal(sessionKeyOf('proj-a/s1'), 'proj-a/s1', '两段路径自身就是目录键');
+  assert.equal(sessionKeyOf('proj-a/s1/sub/deep.jsonl'), 'proj-a/s1', '更深层路径取前两段');
+  assert.equal(sessionKeyOf('a\\b\\c.jsonl'), 'a/b', 'Windows 分隔符归一为 /');
+  assert.equal(sessionKeyOf('a//b///c'), 'a/b', '连续分隔符合并');
+});
+
+test('G-02 sessionKeyOf：无法归一会话目录 → null', () => {
+  assert.equal(sessionKeyOf(''), null);
+  assert.equal(sessionKeyOf('proj-a'), null, '单段（项目级）无法归一会话');
+  assert.equal(sessionKeyOf('/'), null);
+  assert.equal(sessionKeyOf('  '), null);
+});
+
+test('G-03 sweepGhostSessions：全部存在 → 无幽灵', () => {
+  const ghosts = sweepGhostSessions(
+    ['proj-a/s1/session.jsonl.zstd', 'proj-b/s2/session.jsonl.zstd'],
+    ['proj-a/s1/session.jsonl.zstd', 'proj-b/s2/meta.json'],
+  );
+  assert.deepEqual(ghosts, []);
+});
+
+test('G-04 sweepGhostSessions：全部缺失（磁盘空）→ 全部幽灵', () => {
+  const ghosts = sweepGhostSessions(
+    ['proj-a/s1/session.jsonl.zstd', 'proj-b/s2/session.jsonl.zstd'],
+    [],
+  );
+  assert.deepEqual(ghosts.sort(), ['proj-a/s1', 'proj-b/s2'].sort());
+});
+
+test('G-05 sweepGhostSessions：混合 —— 只有磁盘缺失的会话算幽灵', () => {
+  const ghosts = sweepGhostSessions(
+    ['proj-a/s1/session.jsonl.zstd', 'proj-b/s2/session.jsonl.zstd', 'proj-c/s3/session.jsonl.zstd'],
+    ['proj-a/s1/session.jsonl.zstd'],
+  );
+  assert.deepEqual(ghosts.sort(), ['proj-b/s2', 'proj-c/s3'].sort());
+});
+
+test('G-06 sweepGhostSessions：磁盘多余会话（备份后新建）不算幽灵', () => {
+  const ghosts = sweepGhostSessions(
+    ['proj-a/s1/session.jsonl.zstd'],
+    ['proj-a/s1/session.jsonl.zstd', 'proj-x/new-sess/session.jsonl.zstd'],
+  );
+  assert.deepEqual(ghosts, []);
+});
+
+test('G-07 sweepGhostSessions：目录键粒度匹配 —— 会话目录尚存即不算幽灵', () => {
+  const ghosts = sweepGhostSessions(
+    ['proj-a/s1/session.jsonl.zstd', 'proj-b/s2/session.jsonl.zstd'],
+    ['proj-a/s1', 'proj-b/s2/meta.json'],
+  );
+  assert.deepEqual(ghosts, [], '磁盘出现会话目录（即使部分文件缺失）即视为会话存在');
+});
+
+test('G-08 sweepGhostSessions：去重保序 + Windows 分隔符磁盘条目', () => {
+  const ghosts = sweepGhostSessions(
+    ['proj-a/s1/a.jsonl', 'proj-a/s1/b.jsonl', 'proj-b/s2/x.jsonl'],
+    ['proj-b\\s2\\x.jsonl'],
+  );
+  assert.deepEqual(ghosts, ['proj-a/s1'], '同一会话多个文件缺失只报一次');
+});
+
+test('G-09 sweepGhostSessions：无法归一（单段/空）的期望条目不参与判定', () => {
+  const ghosts = sweepGhostSessions(
+    ['proj-a', 'proj-b/s2/session.jsonl.zstd', ''],
+    [],
+  );
+  assert.deepEqual(ghosts, ['proj-b/s2']);
+});
+
+test('G-10 expectedSessionRefs：只取 sessions 分区 existed=true 的 file 条目', () => {
+  const entries: SnapshotEntry[] = [
+    { kind: 'file', adapter: 'sessions', ref: 'proj-a/s1/session.jsonl.zstd', before: null, existed: true, copiedTo: 'blobs/x' },
+    { kind: 'file', adapter: 'sessions', ref: 'proj-b/s2/session.jsonl.zstd', before: null, existed: false },
+    { kind: 'file', adapter: 'skills', ref: 'coding.md', before: null, existed: true, copiedTo: 'blobs/y' },
+    { kind: 'settingsNamespace', adapter: 'settings', ref: 'general', before: null, revision: 1, existed: true },
+  ];
+  assert.deepEqual(expectedSessionRefs(entries), ['proj-a/s1/session.jsonl.zstd']);
+  assert.deepEqual(expectedSessionRefs([]), []);
+});

package/src/core/ghost-sweep.ts

@@ -0,0 +1,67 @@
+/**
+ * 幽灵会话检测（F5 失效归档清理，对应 dsh-backup-sync 的 sweepArchives 设计）。
+ *
+ * 背景：会话日志被删除 / 恢复覆盖后，DSH 的归档列表会产生「幽灵归档」——归档 ID
+ * 指向已不存在的会话日志，恢复后应识别这些失效归档。
+ *
+ * dsh-backup-sync 走 ctx.workspaceRegistry.archivedSessionIds + unarchiveSession；
+ * 本仓库 HostContext（core/types.ts）未暴露该能力（workspace facade 只有
+ * WorkspaceRecord 的 list/write/remove），故按仓库纪律降级为「本地校验」：
+ * 把快照/备份记录的会话文件清单与磁盘 sessions 目录实际文件对比，找出
+ * 「备份里有、磁盘上已不存在的会话」（幽灵），报告给用户人工确认清理。
+ *
+ * 本模块只含纯函数（零 IO、零 DSH 运行时依赖），供 restore.ts 与测试使用；
+ * 磁盘扫描等副作用放在 restore.ts 内部。
+ */
+import type { SectionId } from '../schema/types.ts';
+import type { SnapshotEntry } from './types.ts';
+
+/** 会话文件目录键提取：把会话相对路径归一为会话目录键 <projectKey>/<sessionId>。
+ * 分隔符统一为 '/'（兼容 Windows '\'）；不足两段（无法归一会话目录）返回 null。 */
+export function sessionKeyOf(relPath: string): string | null {
+  if (typeof relPath !== 'string' || relPath === '') return null;
+  const norm = relPath.replace(/\\/g, '/').replace(/\/{2,}/g, '/').replace(/^\/+|\/+$/g, '');
+  if (norm === '') return null;
+  const segments = norm.split('/');
+  if (segments.length < 2) return null;
+  return `${segments[0]}/${segments[1]}`;
+}
+
+/**
+ * 幽灵会话检测（纯函数）：
+ * 期望存在的会话（快照/备份记录的会话条目）在磁盘 sessions 目录已无任何对应文件 → 幽灵。
+ *
+ * @param sessionIds 快照/备份记录的会话条目（相对 sessions 基准目录的路径，如
+ *   'proj-a/s1/session.jsonl.zstd' 或目录键 'proj-a/s1'）
+ * @param diskEntries 磁盘 sessions 目录扫描出的实际相对路径（同样相对 sessions 基准目录，
+ *   分隔符不限 Windows/Unix）
+ * @returns 失效（幽灵）会话键清单（<projectKey>/<sessionId>，去重保序）；
+ *   仅磁盘有、备份没有的会话不是幽灵（属备份后新建），不返回。
+ */
+export function sweepGhostSessions(sessionIds: string[], diskEntries: string[]): string[] {
+  const disk = new Set<string>();
+  for (const d of diskEntries) {
+    const key = sessionKeyOf(d);
+    if (key !== null) disk.add(key);
+  }
+  const ghosts: string[] = [];
+  const seen = new Set<string>();
+  for (const id of sessionIds) {
+    const key = sessionKeyOf(id);
+    if (key === null) continue; // 无法归一会话目录的条目不参与判定
+    if (!disk.has(key) && !seen.has(key)) {
+      seen.add(key);
+      ghosts.push(key);
+    }
+  }
+  return ghosts;
+}
+
+/** 从快照条目中提取「恢复后应存在于磁盘」的会话文件相对路径（sessions 分区、existed=true）。
+ * 仅参与过导入且快照时存在的会话文件才算期望项；existed=false（导入新增、恢复时删除）不算。 */
+export function expectedSessionRefs(entries: SnapshotEntry[]): string[] {
+  return entries
+    .filter((e): e is SnapshotEntry & { kind: 'file' } =>
+      e.kind === 'file' && e.adapter === ('sessions' as SectionId) && e.existed === true)
+    .map((e) => e.ref);
+}

package/src/core/importer.ts

@@ -0,0 +1,83 @@
+/**
+ * Importer 门面：封装导入 14 步流程（规范 §9），委托 Analyzer 三段式。
+ *
+ *  1 选 ZIP → 2 校验 ZIP → 3 读 manifest → 4 完整性 → 5 schema → 6 兼容
+ *  → 7 扫描 → 8 ImportPlan → 9 Preview(Dry Run) → 10 用户确认
+ *  → 11 快照 → 12 执行 → 13 校验 → 14 结果（失败则回滚）
+ *
+ * 安全阀：executeImportPlan 必须显式 confirm，否则拒绝（ImportNotConfirmedError）。
+ * Dry Run：analyzeImport / createImportPlan 零写入（ZIP 全程内存解析，不进磁盘）。
+ */
+import type { ZipArchive, ZipSafetyLimits } from '../utils/zip.ts';
+import type { MsgFunc } from './messages.ts';
+import { Analyzer } from './analyzer.ts';
+import type { PlanItemProgress } from './analyzer.ts';
+import type {
+  ConfigAdapter, HostContext, ImportAnalysis, ImportDecisions, ImportPlan,
+  ImportResult, SnapshotStore, TransactionSnapshotContext,
+} from './types.ts';
+import type { SectionId } from '../schema/types.ts';
+
+export interface ImporterOptions {
+  ctx: HostContext;
+  adapters: ConfigAdapter[];
+  snapshotStore: SnapshotStore;
+  limits?: ZipSafetyLimits;
+  /** 依赖存在性检查器（缺省不检查） */
+  dependencyChecker?: (command: string) => Promise<boolean>;
+  /** m4 可注入强化版 ZIP 安全解析 */
+  parseZipOverride?: (buf: Uint8Array, limits?: ZipSafetyLimits) => ZipArchive;
+  /** 消息翻译器（缺省 ctx.msg ?? zh） */
+  msg?: MsgFunc;
+}
+
+export interface ExecuteOptions {
+  /** 用户确认（UI 收集）；非 true 一律拒绝执行 */
+  confirm: boolean;
+  /** 用户补录的秘密值（仅内存） */
+  secretInputs?: Record<string, string>;
+  /** 加密备份解密结果（仅内存；解密必须经 m4 encryption provider） */
+  decryptedCredentials?: Map<string, string>;
+  /** 任一项失败立即整体回滚（默认 false：单项失败如实记录并继续其余项） */
+  rollbackOnError?: boolean;
+  /** m1：每完成一个计划项的进度回调（透传给 Analyzer；不传则无埋点） */
+  onItem?: (info: PlanItemProgress) => void;
+  /** m1：每开始一个计划项的进度回调（供 UI 显示「正在执行项 X」/ 判定跳过按钮；不传则无埋点） */
+  onItemStart?: (info: { adapter: SectionId; index: number; total: number; detail: string }) => void;
+  /** 执行日志回调（逐计划项操作 + 子进程命令行，仅非敏感文本；透传给 Analyzer → ImportContext） */
+  onLog?: (line: string) => void;
+  /** Phase 4 生产 journal↔snapshot 绑定（deferred；透传给 Analyzer；不传 = 无 journal 绑定） */
+  snapshotBinding?: TransactionSnapshotContext;
+}
+
+export class Importer {
+  private readonly analyzer: Analyzer;
+
+  constructor(opts: ImporterOptions) {
+    this.analyzer = new Analyzer(opts);
+  }
+
+  /** 步骤 1-8 + 分析：只读，返回 ImportAnalysis（含兼容性/路径/依赖/秘密摘要） */
+  analyzeImport(zipPath: string): Promise<ImportAnalysis> {
+    return this.analyzer.analyzeImport(zipPath);
+  }
+
+  /** 步骤 9：Dry Run / Preview —— 合并用户冲突决策与路径映射，输出最终可执行计划（零写入） */
+  createImportPlan(zipPath: string, decisions: ImportDecisions): Promise<ImportPlan> {
+    return this.analyzer.createImportPlan(zipPath, decisions);
+  }
+
+  /** 步骤 10-14：确认 → 快照 → 执行 → 校验 → 结果；失败可整体回滚并如实报告 */
+  executeImportPlan(zipPath: string, plan: ImportPlan, opts: ExecuteOptions): Promise<ImportResult> {
+    return this.analyzer.executeImportPlan(zipPath, plan, {
+      confirm: opts.confirm,
+      secretInputs: opts.secretInputs,
+      decryptedCredentials: opts.decryptedCredentials,
+      rollbackOnError: opts.rollbackOnError,
+      onItem: opts.onItem,
+      onItemStart: opts.onItemStart,
+      onLog: opts.onLog,
+      snapshotBinding: opts.snapshotBinding,
+    });
+  }
+}