dsh-config-manager 0.1.19 → 0.1.21

package/lib/sync/risk.js

@@ -0,0 +1,76 @@
+/**
+ * 分区风险映射（v1 静态表；可后续接入适配器声明的 risk 字段动态化）。
+ * - low    ：低风险——自动应用（无冲突时）
+ *   settings / ui / providers / prompts
+ * - medium ：中风险——待审队列（路径映射、安装、变更）
+ *   workspaces / plugins / mcp
+ * - high   ：高风险——永不自动（含双向冲突、设备专属、凭据/秘密）
+ *   credentialsStatus / secrets / sessions / pluginFiles / workspaces? 不，
+ *   按规划表 workspaces 归 medium（中风险），credentialsStatus/secrets 归 high；
+ *   agentPresets / skills 暂归 low（受 sync 通道的 portable 过滤实际不会携带 skills）。
+ */
+export const SECTION_RISK_TIER = {
+    settings: 'low',
+    ui: 'low',
+    providers: 'low',
+    prompts: 'low',
+    workspaces: 'medium',
+    plugins: 'medium',
+    mcp: 'medium',
+    skills: 'low',
+    agentPresets: 'low',
+    pluginFiles: 'high',
+    sessions: 'high',
+    credentialsStatus: 'high',
+    secrets: 'high',
+};
+/**
+ * 按风险等级 + firstSync 标志将 MergePlan 分流到三组。
+ * 纯函数：相同输入 → 相同输出；不读 fs、不发网络。
+ */
+export function classifyMergePlan(plan, opts) {
+    const autoApply = [];
+    const review = [];
+    const skipped = [];
+    for (const r of plan.sections) {
+        // 跳过：决策为 skip（远端缺且本地未改 / 完全无变化）
+        if (r.decision === 'skip') {
+            skipped.push(r);
+            continue;
+        }
+        // 双向冲突永远进 review（最高优先级）
+        if (r.decision === 'conflict') {
+            review.push(r);
+            continue;
+        }
+        // 首次同步强制预览：所有非 skip 项一律进 review
+        if (opts.firstSync) {
+            review.push(r);
+            continue;
+        }
+        const tier = SECTION_RISK_TIER[r.id];
+        // 未知分区（防御性）一律进 review 而非自动应用
+        if (tier === undefined) {
+            review.push(r);
+            continue;
+        }
+        if (tier === 'low') {
+            // 低风险且决策明确（useRemote / keepLocal）→ 自动应用
+            autoApply.push(r);
+        }
+        else {
+            // medium / high → 待审
+            review.push(r);
+        }
+    }
+    return { autoApply, review, skipped };
+}
+export function summarizeApplyPlan(apply) {
+    return {
+        autoApplyCount: apply.autoApply.length,
+        reviewCount: apply.review.length,
+        skippedCount: apply.skipped.length,
+        totalCount: apply.autoApply.length + apply.review.length + apply.skipped.length,
+    };
+}
+//# sourceMappingURL=risk.js.map

package/lib/sync/risk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.js","sourceRoot":"","sources":["../../src/sync/risk.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA0C;IACtE,QAAQ,EAAE,KAAK;IACf,EAAE,EAAE,KAAK;IACT,SAAS,EAAE,KAAK;IAChB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,QAAQ;IACpB,OAAO,EAAE,QAAQ;IACjB,GAAG,EAAE,QAAQ;IACb,MAAM,EAAE,KAAK;IACb,YAAY,EAAE,KAAK;IACnB,WAAW,EAAE,MAAM;IACnB,QAAQ,EAAE,MAAM;IAChB,iBAAiB,EAAE,MAAM;IACzB,OAAO,EAAE,MAAM;CAChB,CAAC;AAkBF;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAe,EAAE,IAAqB;IACtE,MAAM,SAAS,GAAyB,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAyB,EAAE,CAAC;IACxC,MAAM,OAAO,GAAyB,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9B,gCAAgC;QAChC,IAAI,CAAC,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,SAAS;QACX,CAAC;QACD,wBAAwB;QACxB,IAAI,CAAC,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACf,SAAS;QACX,CAAC;QACD,gCAAgC;QAChC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACf,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACrC,6BAA6B;QAC7B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;YACnB,wCAAwC;YACxC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,qBAAqB;YACrB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACxC,CAAC;AAaD,MAAM,UAAU,kBAAkB,CAAC,KAAoB;IACrD,OAAO;QACL,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM;QACtC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM;QAChC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;QAClC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM;KAChF,CAAC;AACJ,CAAC"}

package/lib/sync/sync-config.d.ts

@@ -1,13 +1,18 @@
 import type { MsgFunc } from '../core/messages.ts';
 export declare const SYNC_CONFIG_FILE = "sync-config.json";
+/** 当前 sync-config.json schema 版本号。 */
+export declare const SYNC_CONFIG_SCHEMA_VERSION = 1;
+/** 历史可读取版本：v1 缺 schemaVersion 字段做兼容读取（视为 v1）。 */
+export declare const SYNC_CONFIG_SUPPORTED_VERSIONS: readonly number[];
 /** 持久化的仓库配置（不含任何凭据） */
 export interface SyncConfig {
     repoUrl: string;
     gitBin?: string;
 }
-/** 读取仓库配置；文件不存在/损坏 → null（视为未配置，UI 显示空表单） */
+/** 读取仓库配置；文件不存在/损坏/不支持 schema → null（视为未配置，UI 显示空表单）。
+ * 兼容旧文件：缺 schemaVersion 字段视为 v1（保留字段）。 */
 export declare function readSyncConfig(dir: string): Promise<SyncConfig | null>;
-/** 保存仓库配置（自动创建目录；覆盖旧值） */
+/** 保存仓库配置（自动创建目录；覆盖旧值；写 schemaVersion=1） */
 export declare function writeSyncConfig(dir: string, cfg: SyncConfig): Promise<void>;
 /**
  * 仓库地址合法性校验（返回错误消息；null = 合法）。

package/lib/sync/sync-config.js

@@ -12,7 +12,12 @@ import path from 'node:path';
 import { zhMsg } from "../core/messages.js";
 import { parseJsonSafe, stringifyJsonSafe } from "../utils/json.js";
 export const SYNC_CONFIG_FILE = 'sync-config.json';
-/** 读取仓库配置；文件不存在/损坏 → null（视为未配置，UI 显示空表单） */
+/** 当前 sync-config.json schema 版本号。 */
+export const SYNC_CONFIG_SCHEMA_VERSION = 1;
+/** 历史可读取版本：v1 缺 schemaVersion 字段做兼容读取（视为 v1）。 */
+export const SYNC_CONFIG_SUPPORTED_VERSIONS = [1];
+/** 读取仓库配置；文件不存在/损坏/不支持 schema → null（视为未配置，UI 显示空表单）。
+ * 兼容旧文件：缺 schemaVersion 字段视为 v1（保留字段）。 */
 export async function readSyncConfig(dir) {
     const file = path.join(dir, SYNC_CONFIG_FILE);
     let raw;
@@ -22,10 +27,24 @@ export async function readSyncConfig(dir) {
     catch {
         return null;
     }
-    const parsed = parseJsonSafe(raw);
+    let parsed;
+    try {
+        parsed = parseJsonSafe(raw);
+    }
+    catch {
+        // 损坏 JSON / 体积超限 / 嵌套过深 → 视为未配置（不抛错）
+        return null;
+    }
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
         return null;
     const obj = parsed;
+    // schemaVersion：缺省视为 v1（兼容旧文件）；非缺省但不在支持列表 → 拒绝
+    if (obj['schemaVersion'] !== undefined && typeof obj['schemaVersion'] !== 'number') {
+        return null;
+    }
+    const ver = typeof obj['schemaVersion'] === 'number' ? obj['schemaVersion'] : 1;
+    if (!SYNC_CONFIG_SUPPORTED_VERSIONS.includes(ver))
+        return null;
     if (typeof obj['repoUrl'] !== 'string' || obj['repoUrl'] === '')
         return null;
     const cfg = { repoUrl: obj['repoUrl'] };
@@ -33,10 +52,11 @@ export async function readSyncConfig(dir) {
         cfg.gitBin = obj['gitBin'];
     return cfg;
 }
-/** 保存仓库配置（自动创建目录；覆盖旧值） */
+/** 保存仓库配置（自动创建目录；覆盖旧值；写 schemaVersion=1） */
 export async function writeSyncConfig(dir, cfg) {
     await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(path.join(dir, SYNC_CONFIG_FILE), stringifyJsonSafe(cfg, { space: 2 }), 'utf8');
+    const payload = { schemaVersion: SYNC_CONFIG_SCHEMA_VERSION, repoUrl: cfg.repoUrl, ...(cfg.gitBin !== undefined && cfg.gitBin !== '' ? { gitBin: cfg.gitBin } : {}) };
+    await fs.writeFile(path.join(dir, SYNC_CONFIG_FILE), stringifyJsonSafe(payload, { space: 2 }), 'utf8');
 }
 /**
  * 仓库地址合法性校验（返回错误消息；null = 合法）。

package/lib/sync/sync-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-config.js","sourceRoot":"","sources":["../../src/sync/sync-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync-config.js","sourceRoot":"","sources":["../../src/sync/sync-config.ts"],"names":[],"mappings":"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"}

package/lib/sync/sync-engine.d.ts

@@ -1,9 +1,12 @@
 import { Importer } from '../core/importer.ts';
-import type { ConfigAdapter, GlobalConflictStrategy, HostContext, PlanItem, PlanItemKind, SecretScanner } from '../core/types.ts';
+import type { ConfigAdapter, GlobalConflictStrategy, HostContext, ImportAnalysis, ImportPlan, ImportResult, PlanItem, PlanItemKind, SecretScanner } from '../core/types.ts';
 import type { SectionId } from '../schema/types.ts';
 import type { SnapshotFs } from './fs.ts';
-import type { SyncTransport } from './transport.ts';
+import type { SyncSnapshot, SyncSnapshotMeta, SyncTransport } from './transport.ts';
 import type { MsgFunc } from '../core/messages.ts';
+import type { MergePlan } from './merge.ts';
+import type { SyncApplyPlan } from './risk.ts';
+import type { PlanItemProgress } from '../core/analyzer.ts';
 export interface SyncEngineOptions {
     ctx: HostContext;
     transport: SyncTransport;
@@ -64,6 +67,50 @@ export interface SyncPullReport {
     needsReview: boolean;
     message?: string;
 }
+/** 一键同步预览结果（preview() 返回；临时 ZIP 由调用方持有并负责清理）。 */
+export interface SyncPreviewResult {
+    ok: boolean;
+    /** 临时标准 ZIP 路径（apply-items 复用 executeImportPlan 需要；调用方清理） */
+    zipPath: string;
+    plan: ImportPlan | null;
+    analysis: ImportAnalysis | null;
+    snapshotId: string;
+    message?: string;
+}
+/** 自动应用执行器（P2b）报告 */
+export interface ApplyReport {
+    ok: boolean;
+    /** 实际写入本地的分区 id 列表 */
+    applied: string[];
+    /** 应用前快照 id（UI 可借此一键回滚）；失败时仍透传以便排查 */
+    restoreId: string;
+    /** 是否触发了整体回滚 */
+    rolledBack: boolean;
+    /** 失败时移到 review 队列的项（ReviewQueueItem 形态供 UI 直接渲染） */
+    review: import('./review-queue.ts').ReviewQueueItem[];
+    /** 来自 Importer.ImportResult 的 warnings；UI 可用于红条提示 */
+    warnings: string[];
+}
+/** applyItems 报告（§3.4 ApplyItemsResponse 的服务端形态） */
+export interface ApplyItemsReport {
+    ok: boolean;
+    /** 实际写入的分区 id 列表（去重） */
+    applied: string[];
+    /** 未采纳的 itemId 列表 */
+    skipped?: string[];
+    /** 应用前快照 id（UI 一键回滚用；失败时仍透传以便排查） */
+    restoreId: string;
+    /** 任一失败是否整体回滚 */
+    rolledBack: boolean;
+    warnings: string[];
+    failed: {
+        itemId: string;
+        message?: string;
+    }[];
+    /** 透传 executeImportPlan 结果 */
+    result: ImportResult | null;
+    needsRestart?: boolean;
+}
 export declare class SyncEngine {
     private readonly ctx;
     private readonly transport;
@@ -95,6 +142,45 @@ export declare class SyncEngine {
      * 绝不直接写配置、绝不执行导入；执行由上层按用户确认后走 Importer.executeImportPlan。
      */
     pull(opts?: SyncPullOptions): Promise<SyncPullReport>;
+    /** 列出远端已有快照（按 createdAt 升序）—— 供「选择历史快照」下拉。 */
+    listSnapshots(): Promise<SyncSnapshotMeta[]>;
+    /**
+     * 一键同步预览：拉取远端（最新或指定历史快照）→ 转临时 ZIP → Importer 分析出计划。
+     * 与 pull 的区别：临时 ZIP **不清理**（由调用方 / 会话持有，供 apply-items 复用），
+     * 并返回完整 plan/analysis/snapshotId 供会话登记。
+     * 调用方负责在会话消费或取消后清理 zipPath 所在目录。
+     */
+    preview(opts?: SyncPullOptions): Promise<SyncPreviewResult>;
+    merge(opts?: {
+        snapshotId?: string;
+    }): Promise<MergePlan>;
+    /**
+     * 记录祖先基线：写本地祖先副本 + 更新 sync-state（lastSnapshotId、每分区 hash/updatedAt、lastSyncAt、transport）+ 裁剪到 keep。
+     * 通常由 push() 在上传成功后调用，也可被上层（合并 apply 完成后）显式调用以更新基线到合并后的快照。
+     */
+    recordBaseline(snapshotId: string, sections: SyncSnapshot['sections'], nowIso?: string): Promise<void>;
+    /**
+     * 应用自动应用计划：写本地（走 Importer.executeImportPlan 标准路径；应用前调 backup.createSnapshot 兜底）；
+     * 任一 auto 项失败 → 整体 rollback；成功后 recordBaseline 更新祖先基线。
+     * 返回 ApplyReport；不抛错到调用方（失败返回 ok:false + rolledBack:true）。
+     * 不再写 review-queue（§2.3/§7.4：待审语义改由同步历史 skipped 标记表达）。
+     */
+    applyMergePlan(apply: SyncApplyPlan): Promise<ApplyReport>;
+    /**
+     * applyItems：按用户对差异项的逐项决策执行导入（§3.4/§5.3）。
+     *
+     * 与 applyMergePlan 的区别：applyItems 接收「会话级临时 ZIP + 子计划」，
+     * 直接执行（backup.createSnapshot 兜底 → importer.executeImportPlan →
+     * 成功 recordBaseline / 失败 rollback），不构造中间 SyncApplyPlan。
+     *
+     * @param zipPath 会话级临时标准 ZIP（由 sync/sync 生成，包含采纳项的 merged payload）
+     * @param subPlan 子计划（仅含采纳项的 ImportPlan；globalStrategy/pathMappings/needsRestart 沿用会话 plan）
+     * @param opts 执行选项（onItem 进度回调）
+     * @returns ApplyItemsReport（ok/applied/restoreId/rolledBack/warnings/result）
+     */
+    applyItems(zipPath: string, subPlan: ImportPlan, opts?: {
+        onItem?: (info: PlanItemProgress) => void;
+    }): Promise<ApplyItemsReport>;
     /** 散文件快照 → 标准导出 ZIP（临时目录，用完即删）：buildManifest + checksums + 平铺分区 */
     private snapshotToZip;
 }

package/lib/sync/sync-engine.js

@@ -30,6 +30,11 @@ import { createSnapshotFs, joinFs } from "./fs.js";
 import { writeSnapshotToDir } from "./layout.js";
 import { hashSection, loadSyncState, saveSyncState } from "./sync-state.js";
 import { msgOf, zhMsg } from "../core/messages.js";
+import { DEFAULT_ANCESTOR_KEEP, loadAncestor, pruneAncestors, writeAncestor } from "./ancestor.js";
+import { merge as mergeSections } from "./merge.js";
+import { createSnapshot } from "../core/backup.js";
+import { rollback } from "../core/rollback.js";
+import { FileSnapshotStore } from "../core/backup.js";
 /** 同步通道结构性排除的敏感分区（即使 portable 判定有误也双保险拒绝；
  * 注：'credentials' 不是合法 SectionId——凭据状态分区为 credentialsStatus） */
 const FORBIDDEN_SECTIONS = ['credentialsStatus', 'secrets'];
@@ -133,14 +138,8 @@ export class SyncEngine {
         }
         // ② 上传远端（传输通道负责散文件落盘 + 提交推送）
         await this.transport.upload(snapshot);
-        // ③ 更新 sync-state：每分区 hash + updatedAt；lastSyncAt；transport 绑定
-        const state = await loadSyncState(this.stateDir, this.fsx, this.msg);
-        for (const [sid, data] of Object.entries(sections)) {
-            state.sections[sid] = { hash: hashSection(data), updatedAt: nowIso };
-        }
-        state.lastSyncAt = nowIso;
-        state.transport = { type: this.transport.type, ref: this.transportRef };
-        await saveSyncState(this.stateDir, state, this.fsx);
+        // ③ 记录祖先基线：写 sync-state（lastSnapshotId + 每分区 hash/updatedAt + lastSyncAt + transport）+ 裁剪
+        await this.recordBaseline(id, snapshot.sections, nowIso);
         return { ok: true, snapshotId: id, sections: Object.keys(sections), warnings };
     }
     /**
@@ -189,6 +188,332 @@ export class SyncEngine {
             await fs.rm(path.dirname(zipPath), { recursive: true, force: true });
         }
     }
+    /** 列出远端已有快照（按 createdAt 升序）—— 供「选择历史快照」下拉。 */
+    async listSnapshots() {
+        return this.transport.list();
+    }
+    /**
+     * 一键同步预览：拉取远端（最新或指定历史快照）→ 转临时 ZIP → Importer 分析出计划。
+     * 与 pull 的区别：临时 ZIP **不清理**（由调用方 / 会话持有，供 apply-items 复用），
+     * 并返回完整 plan/analysis/snapshotId 供会话登记。
+     * 调用方负责在会话消费或取消后清理 zipPath 所在目录。
+     */
+    async preview(opts = {}) {
+        if (!this.importer) {
+            throw new Error(this.msg('sync.missingImporter'));
+        }
+        const metas = await this.transport.list();
+        if (metas.length === 0) {
+            return { ok: false, zipPath: '', plan: null, analysis: null, snapshotId: '', message: this.msg('sync.remoteEmpty') };
+        }
+        const targetId = opts.snapshotId ?? metas[metas.length - 1].id;
+        const snapshot = await this.transport.download(targetId);
+        if (snapshot.manifest.containsSecrets) {
+            throw new Error(this.msg('sync.remoteContainsSecrets', { id: targetId }));
+        }
+        const portableIds = new Set(this.portableAdapters().map((a) => a.id));
+        const zipPath = await this.snapshotToZip(snapshot, portableIds);
+        const analysis = await this.importer.analyzeImport(zipPath);
+        const plan = await this.importer.createImportPlan(zipPath, {
+            strategy: opts.strategy ?? 'merge',
+            resolutions: {},
+            pathMappings: [],
+        });
+        return { ok: analysis.valid, zipPath, plan, analysis, snapshotId: targetId, message: undefined };
+    }
+    async merge(opts = {}) {
+        const metas = await this.transport.list();
+        if (metas.length === 0) {
+            return { sections: [] };
+        }
+        const targetId = opts.snapshotId ?? metas[metas.length - 1].id;
+        const remote = await this.transport.download(targetId);
+        if (remote.manifest.containsSecrets) {
+            throw new Error(`远端快照 ${targetId} 声明 containsSecrets=true，拒绝合并（同步通道永不携带秘密）`);
+        }
+        // 共同祖先：从 sync-state.lastSnapshotId 读本地副本；空 = 首次/无祖先
+        const state = await loadSyncState(this.stateDir, this.fsx, this.msg);
+        let ancestor;
+        if (state.lastSnapshotId !== '' && this.localSnapshotsDir !== undefined) {
+            ancestor = await loadAncestor(this.localSnapshotsDir, state.lastSnapshotId, this.fsx);
+        }
+        // 本地当前：现场 export（含 s​e​c​r​e​t 剥离），与 push 同口径
+        const localSections = {};
+        for (const adapter of this.portableAdapters()) {
+            let section;
+            try {
+                section = await adapter.export(this.ctx, { includeSecrets: false });
+            }
+            catch {
+                continue;
+            }
+            const data = isFileSection(adapter.id) ? section.data : this.scanner.scanAndRedact(section.data).sanitized;
+            localSections[adapter.id] = data;
+        }
+        const portableIds = new Set(this.portableAdapters().map((a) => a.id));
+        const remotePortable = {};
+        for (const [id, data] of Object.entries(remote.sections)) {
+            if (portableIds.has(id))
+                remotePortable[id] = data;
+        }
+        const ancestorPortable = {};
+        if (ancestor) {
+            for (const [id, data] of Object.entries(ancestor.sections)) {
+                if (portableIds.has(id))
+                    ancestorPortable[id] = data;
+            }
+        }
+        return mergeSections(localSections, remotePortable, ancestorPortable);
+    }
+    /**
+     * 记录祖先基线：写本地祖先副本 + 更新 sync-state（lastSnapshotId、每分区 hash/updatedAt、lastSyncAt、transport）+ 裁剪到 keep。
+     * 通常由 push() 在上传成功后调用，也可被上层（合并 apply 完成后）显式调用以更新基线到合并后的快照。
+     */
+    async recordBaseline(snapshotId, sections, nowIso) {
+        const ts = nowIso ?? this.now().toISOString();
+        // 1) 写本地祖先副本（如有 localSnapshotsDir）
+        if (this.localSnapshotsDir !== undefined) {
+            const snapshot = {
+                id: snapshotId,
+                createdAt: ts,
+                manifest: {
+                    schemaVersion: CURRENT_SCHEMA_VERSION,
+                    dshVersion: this.ctx.dshVersion,
+                    platform: this.ctx.platform,
+                    sectionIds: Object.keys(sections),
+                    containsSecrets: false,
+                },
+                sections,
+            };
+            await writeAncestor(this.localSnapshotsDir, snapshot, this.fsx);
+        }
+        // 2) 更新 sync-state：lastSnapshotId + 每分区 hash/updatedAt + lastSyncAt + transport
+        const state = await loadSyncState(this.stateDir, this.fsx, this.msg);
+        state.lastSnapshotId = snapshotId;
+        state.lastSyncAt = ts;
+        state.transport = { type: this.transport.type, ref: this.transportRef };
+        for (const [sid, data] of Object.entries(sections)) {
+            state.sections[sid] = { hash: hashSection(data), updatedAt: ts };
+        }
+        await saveSyncState(this.stateDir, state, this.fsx);
+        // 3) 裁剪祖先副本（最近 N 个）
+        if (this.localSnapshotsDir !== undefined) {
+            await pruneAncestors(this.localSnapshotsDir, DEFAULT_ANCESTOR_KEEP, this.fsx);
+        }
+    }
+    /**
+     * 应用自动应用计划：写本地（走 Importer.executeImportPlan 标准路径；应用前调 backup.createSnapshot 兜底）；
+     * 任一 auto 项失败 → 整体 rollback；成功后 recordBaseline 更新祖先基线。
+     * 返回 ApplyReport；不抛错到调用方（失败返回 ok:false + rolledBack:true）。
+     * 不再写 review-queue（§2.3/§7.4：待审语义改由同步历史 skipped 标记表达）。
+     */
+    async applyMergePlan(apply) {
+        if (!this.importer) {
+            throw new Error('applyMergePlan: SyncEngine 缺少 importer（需在 options 中注​入）');
+        }
+        const appliedIds = apply.autoApply.map((r) => r.id);
+        // 0) 空 autoApply：无物可应用，直接短路（不构造 ZIP、不调 Importer）
+        if (appliedIds.length === 0) {
+            return { ok: true, applied: [], restoreId: '', rolledBack: false, review: [], warnings: [] };
+        }
+        // 1) 构造临时 ZIP（仅含 autoApply 项的 merged payload）+ 分析 + 计划
+        const portableIds = new Set(this.portableAdapters().map((a) => a.id));
+        const tempSnapshot = {
+            id: this.snapshotIdFn(),
+            createdAt: this.now().toISOString(),
+            manifest: {
+                schemaVersion: CURRENT_SCHEMA_VERSION,
+                dshVersion: this.ctx.dshVersion,
+                platform: this.ctx.platform,
+                sectionIds: apply.autoApply.map((r) => r.id),
+                containsSecrets: false,
+            },
+            sections: apply.autoApply.reduce((acc, r) => {
+                if (r.merged !== undefined)
+                    acc[r.id] = r.merged;
+                return acc;
+            }, {}),
+        };
+        const zipPath = await this.snapshotToZip(tempSnapshot, portableIds);
+        try {
+            const analysis = await this.importer.analyzeImport(zipPath);
+            const plan = await this.importer.createImportPlan(zipPath, {
+                strategy: 'replace', // auto 路径：冲突已在外部分流；这里 replace = 接受导入值
+                resolutions: {},
+                pathMappings: [],
+            });
+            if (!plan.items.length) {
+                // 没有可执行项 → 视为 ok 但空 applied
+                return { ok: true, applied: [], restoreId: '', rolledBack: false, review: [], warnings: [] };
+            }
+            // 2) 兜底：先建快照（拿到 restoreId 给 UI 一键回滚用）
+            const store = new FileSnapshotStore({ dir: this.stateDir });
+            let snapshot;
+            try {
+                snapshot = await createSnapshot({
+                    ctx: this.ctx,
+                    plan,
+                    sourceZip: zipPath,
+                    store,
+                    adapters: this.adapters,
+                });
+            }
+            catch (backupErr) {
+                return {
+                    ok: false,
+                    applied: [],
+                    restoreId: '',
+                    rolledBack: false,
+                    review: [],
+                    warnings: [`应用前快照失败：${backupErr instanceof Error ? backupErr.message : String(backupErr)}`],
+                };
+            }
+            // 3) 真正执行：Importer.executeImportPlan（rollbackOnError=true → 任一失败整体回滚）
+            const result = await this.importer.executeImportPlan(zipPath, plan, {
+                confirm: true,
+                rollbackOnError: true,
+                secretInputs: undefined,
+                decryptedCredentials: undefined,
+            });
+            if (!result.ok) {
+                try {
+                    await rollback({ ctx: this.ctx, snapshot, store, adapters: this.adapters });
+                }
+                catch { /* noop */ }
+                // 失败路径不再写 review-queue（§7.4）：历史 skipped/failed 标记由上层（路由/调度器）写入。
+                return {
+                    ok: false,
+                    applied: [],
+                    restoreId: snapshot.id,
+                    rolledBack: true,
+                    review: [],
+                    warnings: result.warnings ?? [],
+                };
+            }
+            // 5) 全成功 → recordBaseline（更新祖先基线指向合并后的快照）
+            const mergedSections = apply.autoApply.reduce((acc, r) => {
+                if (r.merged !== undefined)
+                    acc[r.id] = r.merged;
+                return acc;
+            }, {});
+            await this.recordBaseline(tempSnapshot.id, mergedSections);
+            return {
+                ok: true,
+                applied: appliedIds,
+                restoreId: snapshot.id,
+                rolledBack: false,
+                review: [],
+                warnings: result.warnings ?? [],
+            };
+        }
+        finally {
+            try {
+                await fs.rm(path.dirname(zipPath), { recursive: true, force: true });
+            }
+            catch { /* noop */ }
+        }
+    }
+    /**
+     * applyItems：按用户对差异项的逐项决策执行导入（§3.4/§5.3）。
+     *
+     * 与 applyMergePlan 的区别：applyItems 接收「会话级临时 ZIP + 子计划」，
+     * 直接执行（backup.createSnapshot 兜底 → importer.executeImportPlan →
+     * 成功 recordBaseline / 失败 rollback），不构造中间 SyncApplyPlan。
+     *
+     * @param zipPath 会话级临时标准 ZIP（由 sync/sync 生成，包含采纳项的 merged payload）
+     * @param subPlan 子计划（仅含采纳项的 ImportPlan；globalStrategy/pathMappings/needsRestart 沿用会话 plan）
+     * @param opts 执行选项（onItem 进度回调）
+     * @returns ApplyItemsReport（ok/applied/restoreId/rolledBack/warnings/result）
+     */
+    async applyItems(zipPath, subPlan, opts = {}) {
+        if (!this.importer) {
+            throw new Error('applyItems: SyncEngine 缺少 importer（需在 options 中注​入）');
+        }
+        if (subPlan.items.length === 0) {
+            return { ok: true, applied: [], restoreId: '', rolledBack: false, warnings: [], failed: [], result: null };
+        }
+        // 兜底快照（拿到 restoreId 给 UI 一键回滚用）
+        const store = new FileSnapshotStore({ dir: this.stateDir });
+        let snapshot;
+        try {
+            snapshot = await createSnapshot({
+                ctx: this.ctx,
+                plan: subPlan,
+                sourceZip: zipPath,
+                store,
+                adapters: this.adapters,
+            });
+        }
+        catch (backupErr) {
+            return {
+                ok: false,
+                applied: [],
+                restoreId: '',
+                rolledBack: false,
+                warnings: [`应用前快照失败：${backupErr instanceof Error ? backupErr.message : String(backupErr)}`],
+                failed: subPlan.items.map((i) => ({ itemId: i.id })),
+                result: null,
+            };
+        }
+        // 真正执行：Importer.executeImportPlan（confirm:true + rollbackOnError:true → 任一失败整体回滚）
+        const result = await this.importer.executeImportPlan(zipPath, subPlan, {
+            confirm: true,
+            rollbackOnError: true,
+            secretInputs: undefined,
+            decryptedCredentials: undefined,
+            onItem: opts.onItem,
+        });
+        if (!result.ok) {
+            // executeImportPlan 已内部回滚（rollbackOnError）；这里再显式 rollback 兜底（幂等）
+            try {
+                await rollback({ ctx: this.ctx, snapshot, store, adapters: this.adapters });
+            }
+            catch { /* noop */ }
+            return {
+                ok: false,
+                applied: [],
+                restoreId: snapshot.id,
+                rolledBack: true,
+                warnings: result.warnings ?? [],
+                failed: result.executed.filter((e) => e.status === 'failed').map((e) => ({ itemId: e.itemId, message: e.message })),
+                result,
+            };
+        }
+        // 成功：recordBaseline 更新祖先基线（合并后的快照）
+        const appliedIds = [...new Set(subPlan.items.map((i) => i.adapter))];
+        const mergedSections = {};
+        // 从 subPlan 中按 adapter 收集写入的分区数据（无法直接从 plan item 获取 merged data，
+        // 但这里不需要精确的 merged 数据——recordBaseline 只需要 sectionIds 与数据来源；
+        // 用现有应用后的 adapter export 作为快照数据更准确）
+        // 注意：recordBaseline 需要各分区内容 hash，因此导出当前各分区最新状态。
+        for (const adapter of this.portableAdapters()) {
+            if (!appliedIds.includes(adapter.id))
+                continue;
+            try {
+                const section = await adapter.export(this.ctx, { includeSecrets: false });
+                const data = isFileSection(adapter.id)
+                    ? section.data
+                    : this.scanner.scanAndRedact(section.data).sanitized;
+                mergedSections[adapter.id] = data;
+            }
+            catch {
+                // 单个分区导出失败不拖垮 recordBaseline（已应用的分区数据从 subPlan 兜底）
+            }
+        }
+        const snapshotId = this.snapshotIdFn();
+        await this.recordBaseline(snapshotId, mergedSections);
+        return {
+            ok: true,
+            applied: appliedIds,
+            skipped: subPlan.items.filter((i) => i.kind === 'Skip').map((i) => i.id),
+            restoreId: snapshot.id,
+            rolledBack: false,
+            warnings: result.warnings ?? [],
+            failed: [],
+            needsRestart: result.needsRestart,
+            result,
+        };
+    }
     /** 散文件快照 → 标准导出 ZIP（临时目录，用完即删）：buildManifest + checksums + 平铺分区 */
     async snapshotToZip(snapshot, portableIds) {
         const entries = [];