@logictan/dsh-config-manager 0.1.60

package/lib/core/exporter.js

@@ -0,0 +1,375 @@
+/**
+ * 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.js';
+import { stringifyJsonSafe } from '../utils/json.js';
+import { buildManifest, CHECKSUMS_FILE, MANIFEST_FILE, EXPORTER_NAME } from '../schema/manifest.js';
+import { SECTION_JSON_PATHS, SECTION_FILE_PREFIXES, isFileSection } from '../schema/config.js';
+import { DEFAULT_SENSITIVE_RELS, refreshVault } from '../security/vault.js';
+import { writeZip } from '../utils/zip.js';
+import { msgOf } from './messages.js';
+/** 缺省 SecretScanner：递归黑名单字段剥离（字段名大小写不敏感；二进制/Uint8Array 原样跳过） */
+export function defaultSecretScanner() {
+    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) {
+            const hits = [];
+            const walk = (v, p) => {
+                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 = {};
+                for (const [k, val] of Object.entries(v)) {
+                    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) {
+    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, data) {
+    const scanText = scanner.scanText;
+    if (typeof scanText !== 'function')
+        return [];
+    const files = extractFileEntries(data);
+    if (files === null)
+        return [];
+    const hits = [];
+    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;
+        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) {
+    if (data === null || typeof data !== 'object')
+        return null;
+    const files = data.files;
+    if (!Array.isArray(files))
+        return null;
+    return files.filter((f) => (f !== null && typeof f === 'object'
+        && typeof f.relativePath === 'string'
+        && f.data instanceof Uint8Array));
+}
+export class Exporter {
+    ctx;
+    adapters;
+    scanner;
+    encryption;
+    exporterVersion;
+    now;
+    msg;
+    onSection;
+    vaultDataDir;
+    constructor(opts) {
+        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) {
+        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 = [];
+        const warnings = [];
+        const redactedHits = [];
+        const included = [];
+        const excluded = 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;
+            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 = [];
+                    const seenPaths = new Set();
+                    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 = [];
+        const sectionFlags = buildSectionFlags(sections);
+        let containsSecrets = false;
+        let encrypted = false;
+        let encryption = null;
+        for (const section of sections) {
+            if (isFileSection(section.sectionId)) {
+                const prefix = SECTION_FILE_PREFIXES[section.sectionId];
+                const files = section.data.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;
+            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,
+            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]),
+            redactedFields: redactedHits.length,
+            containsSecrets,
+            encrypted,
+            vaultRefreshed,
+        });
+        const report = {
+            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) {
+    const flags = {};
+    for (const id of Object.keys(SECTION_JSON_PATHS))
+        flags[id] = false;
+    for (const id of Object.keys(SECTION_FILE_PREFIXES))
+        flags[id] = false;
+    flags['secrets'] = false;
+    for (const section of sections)
+        flags[section.sectionId] = true;
+    return flags;
+}
+function defaultOutPath(now) {
+    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 };
+//# sourceMappingURL=exporter.js.map

package/lib/core/ghost-sweep.d.ts

@@ -0,0 +1,19 @@
+import type { SnapshotEntry } from './types.ts';
+/** 会话文件目录键提取：把会话相对路径归一为会话目录键 <projectKey>/<sessionId>。
+ * 分隔符统一为 '/'（兼容 Windows '\'）；不足两段（无法归一会话目录）返回 null。 */
+export declare function sessionKeyOf(relPath: string): string | null;
+/**
+ * 幽灵会话检测（纯函数）：
+ * 期望存在的会话（快照/备份记录的会话条目）在磁盘 sessions 目录已无任何对应文件 → 幽灵。
+ *
+ * @param sessionIds 快照/备份记录的会话条目（相对 sessions 基准目录的路径，如
+ *   'proj-a/s1/session.jsonl.zstd' 或目录键 'proj-a/s1'）
+ * @param diskEntries 磁盘 sessions 目录扫描出的实际相对路径（同样相对 sessions 基准目录，
+ *   分隔符不限 Windows/Unix）
+ * @returns 失效（幽灵）会话键清单（<projectKey>/<sessionId>，去重保序）；
+ *   仅磁盘有、备份没有的会话不是幽灵（属备份后新建），不返回。
+ */
+export declare function sweepGhostSessions(sessionIds: string[], diskEntries: string[]): string[];
+/** 从快照条目中提取「恢复后应存在于磁盘」的会话文件相对路径（sessions 分区、existed=true）。
+ * 仅参与过导入且快照时存在的会话文件才算期望项；existed=false（导入新增、恢复时删除）不算。 */
+export declare function expectedSessionRefs(entries: SnapshotEntry[]): string[];

package/lib/core/ghost-sweep.js

@@ -0,0 +1,52 @@
+/** 会话文件目录键提取：把会话相对路径归一为会话目录键 <projectKey>/<sessionId>。
+ * 分隔符统一为 '/'（兼容 Windows '\'）；不足两段（无法归一会话目录）返回 null。 */
+export function sessionKeyOf(relPath) {
+    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, diskEntries) {
+    const disk = new Set();
+    for (const d of diskEntries) {
+        const key = sessionKeyOf(d);
+        if (key !== null)
+            disk.add(key);
+    }
+    const ghosts = [];
+    const seen = new Set();
+    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) {
+    return entries
+        .filter((e) => e.kind === 'file' && e.adapter === 'sessions' && e.existed === true)
+        .map((e) => e.ref);
+}
+//# sourceMappingURL=ghost-sweep.js.map

package/lib/core/importer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 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 declare class Importer {
+    private readonly analyzer;
+    constructor(opts: ImporterOptions);
+    /** 步骤 1-8 + 分析：只读，返回 ImportAnalysis（含兼容性/路径/依赖/秘密摘要） */
+    analyzeImport(zipPath: string): Promise<ImportAnalysis>;
+    /** 步骤 9：Dry Run / Preview —— 合并用户冲突决策与路径映射，输出最终可执行计划（零写入） */
+    createImportPlan(zipPath: string, decisions: ImportDecisions): Promise<ImportPlan>;
+    /** 步骤 10-14：确认 → 快照 → 执行 → 校验 → 结果；失败可整体回滚并如实报告 */
+    executeImportPlan(zipPath: string, plan: ImportPlan, opts: ExecuteOptions): Promise<ImportResult>;
+}

package/lib/core/importer.js

@@ -0,0 +1,29 @@
+import { Analyzer } from './analyzer.js';
+export class Importer {
+    analyzer;
+    constructor(opts) {
+        this.analyzer = new Analyzer(opts);
+    }
+    /** 步骤 1-8 + 分析：只读，返回 ImportAnalysis（含兼容性/路径/依赖/秘密摘要） */
+    analyzeImport(zipPath) {
+        return this.analyzer.analyzeImport(zipPath);
+    }
+    /** 步骤 9：Dry Run / Preview —— 合并用户冲突决策与路径映射，输出最终可执行计划（零写入） */
+    createImportPlan(zipPath, decisions) {
+        return this.analyzer.createImportPlan(zipPath, decisions);
+    }
+    /** 步骤 10-14：确认 → 快照 → 执行 → 校验 → 结果；失败可整体回滚并如实报告 */
+    executeImportPlan(zipPath, plan, opts) {
+        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,
+        });
+    }
+}
+//# sourceMappingURL=importer.js.map

package/lib/core/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 核心引擎公共出口：m5（适配器）、m6（UI）、m7（测试）与宿主插件统一从这里引用。
+ */
+export { Exporter, defaultSecretScanner, EXPORTER_INFO, type ExporterOptions, } from './exporter.ts';
+export { Importer, type ImporterOptions, type ExecuteOptions, } from './importer.ts';
+export { Analyzer, type AnalyzerOptions, } from './analyzer.ts';
+export { createSnapshot, FileSnapshotStore, resolveFileTarget, verifySnapshot, type CreateSnapshotOptions, type FileSnapshotStoreOptions, type SnapshotVerifyResult, } from './backup.ts';
+export { rollback, type RollbackOptions } from './rollback.ts';
+export { planRestore, restore, listSnapshots, type RestoreAction, type RestoreActionKind, type RestoreOptions, type RestorePlan, type RestoreReport, type SnapshotMeta, } from './restore.ts';
+export { computeCompatibility, describeCompatibility, describeSchemaStatus, validateSections, } from './validator.ts';
+export { ImportNotConfirmedError, ImportFailedError, } from './types.ts';
+export type * from './types.ts';
+export { MigrationStore, sanitizeEntry, queryHistory, summarizeHistory, renderExport, parseHistoryQuery, isValidMigrationKind, redactHistoryText, makeHistoryFilename, isHistoryBasename, MIGRATION_HISTORY_DIR, DEFAULT_MIGRATION_RETENTION, MIGRATION_HISTORY_SCHEMA_VERSION, type MigrationKind, type MigrationResult, type MigrationHistoryEntry, type StoredMigrationHistoryEntry, type MigrationQuery, type MigrationHistoryStats, type ExportFormat, type ReadMigrationResult, type AppendResult, type MigrationIo, type MigrationStoreOptions, type MigrationSource, } from './migration-history.ts';
+export type { ExportOptions, ExportSection, ValidationResult, HostContext, SettingsFacade, CredentialsFacade, PluginsFacade, WorkspaceFacade, PatchFileFacade, FileSystemFacade, NamespaceInfo, PluginInfo, ConfigAdapter, Portability, SecretScanner, SensitiveHit, EncryptionProvider, PlanItem, PlanItemKind, ItemResolution, GlobalConflictStrategy, ImportAnalysis, ImportDecisions, ImportPlan, ImportResult, ExecutedItem, ImportContext, SnapshotTarget, SnapshotEntry, Snapshot, SnapshotStore, RollbackReport, PathMapping, PathIssue, CompatibilityInput, CompatibilityScore, ExportReport, ApplyResult, ConflictDecision, } from './types.ts';

package/lib/core/index.js

@@ -0,0 +1,14 @@
+/**
+ * 核心引擎公共出口：m5（适配器）、m6（UI）、m7（测试）与宿主插件统一从这里引用。
+ */
+export { Exporter, defaultSecretScanner, EXPORTER_INFO, } from './exporter.js';
+export { Importer, } from './importer.js';
+export { Analyzer, } from './analyzer.js';
+export { createSnapshot, FileSnapshotStore, resolveFileTarget, verifySnapshot, } from './backup.js';
+export { rollback } from './rollback.js';
+export { planRestore, restore, listSnapshots, } from './restore.js';
+export { computeCompatibility, describeCompatibility, describeSchemaStatus, validateSections, } from './validator.js';
+export { ImportNotConfirmedError, ImportFailedError, } from './types.js';
+/* —— 迁移历史引擎（Phase 6） —— */
+export { MigrationStore, sanitizeEntry, queryHistory, summarizeHistory, renderExport, parseHistoryQuery, isValidMigrationKind, redactHistoryText, makeHistoryFilename, isHistoryBasename, MIGRATION_HISTORY_DIR, DEFAULT_MIGRATION_RETENTION, MIGRATION_HISTORY_SCHEMA_VERSION, } from './migration-history.js';
+//# sourceMappingURL=index.js.map