dsh-config-manager 0.1.20 → 0.1.21

package/src/sync/sync-engine.test.ts

@@ -414,14 +414,11 @@ test('applyMergePlan: 失败路径 → 整体回滚 + enqueueItems + ApplyReport
     assert.equal(report.rolledBack, true);
     assert.equal(report.applied.length, 0);
     assert.notEqual(report.restoreId, '', 'restoreId 应透传以便排查');
-    assert.ok(report.review.length > 0, 'auto 项应入 review 队列');
-    assert.equal(report.review[0]!.sectionId, 'settings');
-    // sync-review-queue.json 应被写入
+    assert.deepEqual(report.review, [], '不再写 review-queue（§7.4）');
+    // sync-review-queue.json 不应被写入
     const rqPath = path.join(tmp, 'sync-review-queue.json');
-    assert.ok(await fs.stat(rqPath).then(() => true).catch(() => false), 'review-queue.json 已写盘');
-    const rq = JSON.parse(await fs.readFile(rqPath, 'utf8')) as { items: Array<{ sectionId: string }> };
-    assert.equal(rq.items.length, 1);
-    assert.equal(rq.items[0]!.sectionId, 'settings');
+    const rqExists = await fs.stat(rqPath).then(() => true).catch(() => false);
+    assert.equal(rqExists, false, 'review-queue.json 不应再被写入');
     // recordBaseline 不应在失败路径调用：sync-state.lastSnapshotId 应仍为空
     const state = await loadSyncState(tmp);
     assert.equal(state.lastSnapshotId, '', '失败时不应 recordBaseline');
@@ -586,3 +583,106 @@ test('merge: 不写本地配置、不执行导入，返回 MergePlan', async ()
     await fs.rm(tmp, { recursive: true, force: true });
   }
 });
+
+// ─── P3：applyItems（一键同步逐项执行）测试 ──────────────────────────────
+
+import type { ImportPlan } from '../core/types.ts';
+
+function makeImportPlan(seed: string): ImportPlan {
+  return {
+    items: [{
+      id: `settings:general-${seed}`,
+      kind: 'Update',
+      adapter: 'settings',
+      description: `Update settings.general (${seed})`,
+      severity: 'info',
+      target: { adapter: 'settings', ref: 'general' },
+    }],
+    globalStrategy: 'merge',
+    pathMappings: [],
+    missingSecrets: [],
+    needsRestart: false,
+    estimatedActions: { settings: 1 } as unknown as Record<SectionId, number>,
+  };
+}
+
+test('applyItems: 成功路径 → 执行子计划 + recordBaseline', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-applyitems-ok-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new MemSyncTransport();
+    const mock = new MockImporter();
+    mock.ok = true;
+    const engine = makeEngineWithMockImporter({
+      ctx, transport, stateDir: tmp, mockImporter: mock,
+    });
+
+    // 需要真实 ZIP 路径（applyItems 用 executeImportPlan 的 zipPath）
+    // 用 mock importer 时 zipPath 可以被 mock 忽略
+    const zipPath = path.join(tmp, 'session.zip');
+    await fs.writeFile(zipPath, 'mock-zip-content');
+
+    const report = await engine.applyItems(zipPath, makeImportPlan('ok'));
+    assert.equal(report.ok, true);
+    assert.deepEqual(report.applied, ['settings']);
+    assert.notEqual(report.restoreId, '', 'restoreId 应非空');
+    assert.equal(report.rolledBack, false);
+    assert.equal(mock.executeCalls, 1, 'Importer.executeImportPlan 应被调用一次');
+    // recordBaseline 应被调用（lastSnapshotId 非空）
+    const state = await loadSyncState(tmp);
+    assert.notEqual(state.lastSnapshotId, '', 'applyItems 成功后 lastSnapshotId 非空');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('applyItems: 失败路径 → 整体回滚 + ok:false', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-applyitems-fail-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new MemSyncTransport();
+    const mock = new MockImporter();
+    mock.ok = false;
+    const engine = makeEngineWithMockImporter({
+      ctx, transport, stateDir: tmp, mockImporter: mock,
+    });
+
+    const zipPath = path.join(tmp, 'session.zip');
+    await fs.writeFile(zipPath, 'mock-zip-content');
+
+    const report = await engine.applyItems(zipPath, makeImportPlan('fail'));
+    assert.equal(report.ok, false);
+    assert.equal(report.rolledBack, true);
+    assert.notEqual(report.restoreId, '', 'restoreId 应透传');
+    // 不再写 review-queue
+    const rqPath = path.join(tmp, 'sync-review-queue.json');
+    const rqExists = await fs.stat(rqPath).then(() => true).catch(() => false);
+    assert.equal(rqExists, false, '失败路径不应写 review-queue');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('applyItems: 空子计划 → 直接返回 ok:true（不调 Importer）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-applyitems-empty-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new MemSyncTransport();
+    const mock = new MockImporter();
+    const engine = makeEngineWithMockImporter({
+      ctx, transport, stateDir: tmp, mockImporter: mock,
+    });
+    const emptyPlan: ImportPlan = {
+      items: [], globalStrategy: 'merge', pathMappings: [], missingSecrets: [], needsRestart: false, estimatedActions: {} as unknown as Record<SectionId, number>,
+    };
+    const report = await engine.applyItems(path.join(tmp, 'none.zip'), emptyPlan);
+    assert.equal(report.ok, true);
+    assert.deepEqual(report.applied, []);
+    assert.equal(mock.executeCalls, 0, '空子计划不应触发 Importer');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});

package/src/sync/sync-engine.ts

@@ -23,7 +23,7 @@ import { defaultSecretScanner } from '../core/exporter.ts';
 import { Importer } from '../core/importer.ts';
 import type {
   ConfigAdapter, ExportSection, GlobalConflictStrategy, HostContext,
-  PlanItem, PlanItemKind, SecretScanner,
+  ImportAnalysis, ImportPlan, ImportResult, PlanItem, PlanItemKind, SecretScanner,
 } from '../core/types.ts';
 import { isFileSection, SECTION_FILE_PREFIXES, SECTION_JSON_PATHS } from '../schema/config.ts';
 import { buildManifest, CHECKSUMS_FILE, MANIFEST_FILE } from '../schema/manifest.ts';
@@ -37,19 +37,18 @@ import { createSnapshotFs, joinFs } from './fs.ts';
 import type { SnapshotFs } from './fs.ts';
 import { writeSnapshotToDir } from './layout.ts';
 import { hashSection, loadSyncState, saveSyncState } from './sync-state.ts';
-import type { SyncSnapshot, SyncTransport } from './transport.ts';
+import type { SyncSnapshot, SyncSnapshotMeta, SyncTransport } from './transport.ts';
 import { msgOf, zhMsg } from '../core/messages.ts';
 import type { MsgFunc } from '../core/messages.ts';
 import { DEFAULT_ANCESTOR_KEEP, loadAncestor, pruneAncestors, writeAncestor } from './ancestor.ts';
 import type { MergePlan, MergeSectionResult } from './merge.ts';
 import { merge as mergeSections } from './merge.ts';
-import { classifyMergePlan } from './risk.ts';
 import type { SyncApplyPlan } from './risk.ts';
 import { createSnapshot } from '../core/backup.ts';
 import { rollback } from '../core/rollback.ts';
 import { FileSnapshotStore } from '../core/backup.ts';
 import type { Snapshot, SnapshotStore } from '../core/types.ts';
-import { enqueueItems as enqueueReviewItems } from './review-queue.ts';
+import type { PlanItemProgress } from '../core/analyzer.ts';
 
 export interface SyncEngineOptions {
   ctx: HostContext;
@@ -117,6 +116,17 @@ export interface SyncPullReport {
   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;
@@ -132,6 +142,24 @@ export interface ApplyReport {
   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;
+}
+
 /** 同步通道结构性排除的敏感分区（即使 portable 判定有误也双保险拒绝；
  * 注：'credentials' 不是合法 SectionId——凭据状态分区为 credentialsStatus） */
 const FORBIDDEN_SECTIONS: readonly SectionId[] = ['credentialsStatus', 'secrets'];
@@ -296,6 +324,41 @@ export class SyncEngine {
     }
   }
 
+  /** 列出远端已有快照（按 createdAt 升序）—— 供「选择历史快照」下拉。 */
+  async listSnapshots(): Promise<SyncSnapshotMeta[]> {
+    return this.transport.list();
+  }
+
+  /**
+   * 一键同步预览：拉取远端（最新或指定历史快照）→ 转临时 ZIP → Importer 分析出计划。
+   * 与 pull 的区别：临时 ZIP **不清理**（由调用方 / 会话持有，供 apply-items 复用），
+   * 并返回完整 plan/analysis/snapshotId 供会话登记。
+   * 调用方负责在会话消费或取消后清理 zipPath 所在目录。
+   */
+  async preview(opts: SyncPullOptions = {}): Promise<SyncPreviewResult> {
+    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: { snapshotId?: string } = {}): Promise<MergePlan> {
     const metas = await this.transport.list();
     if (metas.length === 0) {
@@ -381,9 +444,9 @@ export class SyncEngine {
 
   /**
    * 应用自动应用计划：写本地（走 Importer.executeImportPlan 标准路径；应用前调 backup.createSnapshot 兜底）；
-   * 任一 auto 项失败 → 整体 rollback + 把全部 auto 项移到 review 队列（写回 sync-review-queue.json）；
-   * 成功后 recordBaseline 更新祖先基线。
+   * 任一 auto 项失败 → 整体 rollback；成功后 recordBaseline 更新祖先基线。
    * 返回 ApplyReport；不抛错到调用方（失败返回 ok:false + rolledBack:true）。
+   * 不再写 review-queue（§2.3/§7.4：待审语义改由同步历史 skipped 标记表达）。
    */
   async applyMergePlan(apply: SyncApplyPlan): Promise<ApplyReport> {
     if (!this.importer) {
@@ -453,19 +516,13 @@ export class SyncEngine {
       });
       if (!result.ok) {
         try { await rollback({ ctx: this.ctx, snapshot, store, adapters: this.adapters }); } catch { /* noop */ }
-        // 4) 把全部 auto 项移到 review 队列
-        const review = await enqueueReviewItems(this.stateDir, apply.autoApply.map((r) => ({
-          sectionId: r.id,
-          kind: 'section' as const,
-          description: `自动应用失败：${r.id}（已回滚）`,
-          merged: r.merged,
-        })));
+        // 失败路径不再写 review-queue（§7.4）：历史 skipped/failed 标记由上层（路由/调度器）写入。
         return {
           ok: false,
           applied: [],
           restoreId: snapshot.id,
           rolledBack: true,
-          review: review.items,
+          review: [],
           warnings: result.warnings ?? [],
         };
       }
@@ -488,6 +545,111 @@ export class SyncEngine {
     }
   }
 
+  /**
+   * 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: string,
+    subPlan: ImportPlan,
+    opts: { onItem?: (info: PlanItemProgress) => void } = {},
+  ): Promise<ApplyItemsReport> {
+    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: SnapshotStore = new FileSnapshotStore({ dir: this.stateDir });
+    let snapshot: Snapshot | undefined;
+    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: SyncSnapshot['sections'] = {};
+    // 从 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 as SectionData;
+      } 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 + 平铺分区 */
   private async snapshotToZip(snapshot: SyncSnapshot, portableIds: Set<SectionId>): Promise<string> {
     const entries: ZipWriteEntry[] = [];

package/src/sync/sync-history.test.ts

@@ -0,0 +1,85 @@
+/**
+ * sync-history 测试：自动同步执行记录读写（sync-history.json）、append 升序、
+ * 读不存在 → 空、损坏拒绝、裁剪 N 条。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  readSyncHistory, appendAutosyncEntry, SYNC_HISTORY_FILE,
+  AUTOSYNC_HISTORY_KEEP,
+} from './sync-history.ts';
+import type { AutosyncHistoryEntry } from './sync-history.ts';
+import type { SectionId } from '../schema/types.ts';
+
+function makeEntry(seed: number, status: AutosyncHistoryEntry['status']): AutosyncHistoryEntry {
+  return {
+    direction: 'both',
+    status,
+    appliedSections: (seed % 2 === 0 ? ['settings'] : []) as SectionId[],
+    createdAt: new Date(2026, 7, 16, 12, seed).toISOString(),
+    failureCountAtRun: 0,
+  };
+}
+
+test('appendAutosyncEntry：追加记录 → readSyncHistory 读回升序列表', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-append-'));
+  try {
+    await appendAutosyncEntry(dir, makeEntry(0, 'success'));
+    await appendAutosyncEntry(dir, makeEntry(1, 'skipped'));
+    const hist = await readSyncHistory(dir);
+    assert.equal(hist.schemaVersion, 1);
+    assert.equal(hist.autosyncEntries.length, 2);
+    assert.equal(hist.autosyncEntries[0]!.status, 'success');
+    assert.equal(hist.autosyncEntries[1]!.status, 'skipped');
+    // updatedAt 非空
+    assert.ok(hist.updatedAt !== '', 'updatedAt 已写入');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncHistory：文件不存在 → 返回空列表（schemaVersion=1）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-missing-'));
+  try {
+    const hist = await readSyncHistory(dir);
+    assert.equal(hist.schemaVersion, 1);
+    assert.deepEqual(hist.autosyncEntries, []);
+    assert.equal(hist.updatedAt, '');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncHistory：损坏 JSON → 抛错', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-corrupt-'));
+  try {
+    await fs.writeFile(path.join(dir, SYNC_HISTORY_FILE), '{not-json', 'utf8');
+    await assert.rejects(() => readSyncHistory(dir), /损坏/);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('appendAutosyncEntry：裁剪到 AUTOSYNC_HISTORY_KEEP 条', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-prune-'));
+  try {
+    // 预置 250 条
+    for (let i = 0; i < AUTOSYNC_HISTORY_KEEP + 50; i++) {
+      await appendAutosyncEntry(dir, makeEntry(i, 'success'));
+    }
+    const hist = await readSyncHistory(dir);
+    assert.ok(hist.autosyncEntries.length <= AUTOSYNC_HISTORY_KEEP, `裁剪后不超过 ${AUTOSYNC_HISTORY_KEEP} 条`);
+    assert.equal(hist.autosyncEntries.length, AUTOSYNC_HISTORY_KEEP);
+    // 保留的是最新的（末尾的 createdAt 最大）
+    const first = hist.autosyncEntries[0]!;
+    const last = hist.autosyncEntries[hist.autosyncEntries.length - 1]!;
+    assert.ok(first.createdAt <= last.createdAt, '升序排列，最新的在末尾');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('appendAutosyncEntry：原子写（不残留 .tmp 文件）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-atomic-'));
+  try {
+    await appendAutosyncEntry(dir, makeEntry(0, 'failed'));
+    const files = await fs.readdir(dir);
+    assert.ok(!files.some((f) => f.includes('.tmp')), '不应残留 .tmp 临时文件');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});

package/src/sync/sync-history.ts

@@ -0,0 +1,126 @@
+/**
+ * m-autosync：自动同步执行记录持久化（sync-history.json）。
+ *
+ * 与 sync-config/autosync-config 并列独立文件。schemaVersion:1，
+ * 结构 { schemaVersion, autosyncEntries: AutosyncHistoryEntry[], updatedAt }。
+ *
+ * - append 追加（升序）并裁剪保留最近 AUTOSYNC_HISTORY_KEEP 条；
+ * - 原子写（临时文件 + rename）；
+ * - 损坏 JSON 严格拒绝（不静默降级到空列表）。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
+import type { SectionId } from '../schema/types.ts';
+
+export const SYNC_HISTORY_FILE = 'sync-history.json';
+export const SYNC_HISTORY_SCHEMA_VERSION = 1;
+/** 自动同步历史保留上限 */
+export const AUTOSYNC_HISTORY_KEEP = 200;
+
+/** 自动同步执行记录（§3.7 AutosyncHistoryEntry） */
+export interface AutosyncHistoryEntry {
+  /** 执行方向 */
+  direction: 'pull' | 'push' | 'both';
+  status: 'success' | 'skipped' | 'failed' | 'partial';
+  /** 跳过原因（冲突项 / 缺失依赖 / Install / 错误 / 无远端 / 网络） */
+  skipReason?: string;
+  /** 被跳过的冲突分区 id（冲突跳过时列出） */
+  conflictedSections?: SectionId[];
+  /** 本次自动合并实际写入的分区 */
+  appliedSections?: SectionId[];
+  /** 本次 push 产生的快照 id（direction 含 push 时） */
+  pushedSnapshotId?: string;
+  /** 本次 pull 来源快照 id */
+  pulledSnapshotId?: string;
+  /** failed 时的错误摘要（脱敏） */
+  error?: string;
+  /** 连续失败 3 次通知时间（ISO-8601 UTC） */
+  notifiedAt?: string;
+  /** 本次触发时的连续失败计数 */
+  failureCountAtRun: number;
+  /** 记录创建时间（ISO-8601 UTC） */
+  createdAt: string;
+}
+
+/** sync-history.json 文件结构 */
+export interface SyncHistoryFile {
+  schemaVersion: number;
+  autosyncEntries: AutosyncHistoryEntry[];
+  updatedAt: string;
+}
+
+/** 读取同步历史；文件不存在 → 空列表（schemaVersion=1）。损坏 JSON 抛错。 */
+export async function readSyncHistory(dir: string): Promise<SyncHistoryFile> {
+  const file = path.join(dir, SYNC_HISTORY_FILE);
+  let raw: string;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch {
+    return { schemaVersion: SYNC_HISTORY_SCHEMA_VERSION, autosyncEntries: [], updatedAt: '' };
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseJsonSafe(raw);
+  } catch {
+    throw new Error(`${SYNC_HISTORY_FILE} 损坏：JSON 解析失败`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${SYNC_HISTORY_FILE} 损坏：必须是对象`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (obj['schemaVersion'] !== SYNC_HISTORY_SCHEMA_VERSION) {
+    throw new Error(`${SYNC_HISTORY_FILE} 损坏：schemaVersion 必须是 ${SYNC_HISTORY_SCHEMA_VERSION}`);
+  }
+  if (!Array.isArray(obj['autosyncEntries'])) {
+    throw new Error(`${SYNC_HISTORY_FILE} 损坏：autosyncEntries 必须是数组`);
+  }
+  const entries: AutosyncHistoryEntry[] = [];
+  for (const it of obj['autosyncEntries']) {
+    if (it === null || typeof it !== 'object' || Array.isArray(it)) {
+      throw new Error(`${SYNC_HISTORY_FILE} 损坏：每个 entry 必须是对象`);
+    }
+    const e = it as Record<string, unknown>;
+    if (typeof e['direction'] !== 'string' || typeof e['status'] !== 'string' || typeof e['createdAt'] !== 'string') {
+      throw new Error(`${SYNC_HISTORY_FILE} 损坏：entry 必须含字符串 direction/status/createdAt`);
+    }
+    entries.push(it as unknown as AutosyncHistoryEntry);
+  }
+  return {
+    schemaVersion: SYNC_HISTORY_SCHEMA_VERSION,
+    autosyncEntries: entries,
+    updatedAt: typeof obj['updatedAt'] === 'string' ? obj['updatedAt'] : '',
+  };
+}
+
+/** 追加一条自动同步执行记录（升序），裁剪到 AUTOSYNC_HISTORY_KEEP 条，原子写。 */
+export async function appendAutosyncEntry(
+  dir: string,
+  entry: AutosyncHistoryEntry,
+  now: () => Date = () => new Date(),
+): Promise<void> {
+  const current = await readSyncHistory(dir);
+  current.autosyncEntries.push(entry);
+  // 裁剪：保留最近 AUTOSYNC_HISTORY_KEEP 条（升序 → 去掉最前的超限条）
+  if (current.autosyncEntries.length > AUTOSYNC_HISTORY_KEEP) {
+    current.autosyncEntries = current.autosyncEntries.slice(current.autosyncEntries.length - AUTOSYNC_HISTORY_KEEP);
+  }
+  current.updatedAt = now().toISOString();
+
+  await fs.mkdir(dir, { recursive: true });
+  const target = path.join(dir, SYNC_HISTORY_FILE);
+  const tmp = path.join(
+    dir,
+    `.${SYNC_HISTORY_FILE}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`,
+  );
+  const data = stringifyJsonSafe(current, { space: 2 });
+  try {
+    await fs.writeFile(tmp, data, 'utf8');
+    await fs.rename(tmp, target);
+  } catch (err) {
+    try { await fs.rm(tmp, { force: true }); } catch { /* ignore */ }
+    throw err;
+  }
+}