dsh-config-manager 0.1.19 → 0.1.21

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,9 +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 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 type { PlanItemProgress } from '../core/analyzer.ts';
 
 export interface SyncEngineOptions {
   ctx: HostContext;
@@ -107,6 +116,50 @@ 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;
+  /** 实际写入本地的分区 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;
+}
+
 /** 同步通道结构性排除的敏感分区（即使 portable 判定有误也双保险拒绝；
  * 注：'credentials' 不是合法 SectionId——凭据状态分区为 credentialsStatus） */
 const FORBIDDEN_SECTIONS: readonly SectionId[] = ['credentialsStatus', 'secrets'];
@@ -216,14 +269,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 as SectionId] = { hash: hashSection(data as SectionData), 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) as SectionId[], warnings };
   }
@@ -277,6 +324,332 @@ 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) {
+      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: SyncSnapshot | undefined;
+    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: Partial<Record<SectionId, SectionData>> = {};
+    for (const adapter of this.portableAdapters()) {
+      let section: ExportSection;
+      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 as SectionData;
+    }
+    const portableIds = new Set(this.portableAdapters().map((a) => a.id));
+    const remotePortable: Partial<Record<SectionId, SectionData>> = {};
+    for (const [id, data] of Object.entries(remote.sections)) {
+      if (portableIds.has(id as SectionId)) remotePortable[id as SectionId] = data as SectionData;
+    }
+    const ancestorPortable: Partial<Record<SectionId, SectionData>> = {};
+    if (ancestor) {
+      for (const [id, data] of Object.entries(ancestor.sections)) {
+        if (portableIds.has(id as SectionId)) ancestorPortable[id as SectionId] = data as SectionData;
+      }
+    }
+    return mergeSections(localSections, remotePortable, ancestorPortable);
+  }
+
+  /**
+   * 记录祖先基线：写本地祖先副本 + 更新 sync-state（lastSnapshotId、每分区 hash/updatedAt、lastSyncAt、transport）+ 裁剪到 keep。
+   * 通常由 push() 在上传成功后调用，也可被上层（合并 apply 完成后）显式调用以更新基线到合并后的快照。
+   */
+  async recordBaseline(
+    snapshotId: string,
+    sections: SyncSnapshot['sections'],
+    nowIso?: string,
+  ): Promise<void> {
+    const ts = nowIso ?? this.now().toISOString();
+    // 1) 写本地祖先副本（如有 localSnapshotsDir）
+    if (this.localSnapshotsDir !== undefined) {
+      const snapshot: SyncSnapshot = {
+        id: snapshotId,
+        createdAt: ts,
+        manifest: {
+          schemaVersion: CURRENT_SCHEMA_VERSION,
+          dshVersion: this.ctx.dshVersion,
+          platform: this.ctx.platform as Platform,
+          sectionIds: Object.keys(sections) as SectionId[],
+          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 as SectionId] = { hash: hashSection(data as SectionData), 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: SyncApplyPlan): Promise<ApplyReport> {
+    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: SyncSnapshot = {
+      id: this.snapshotIdFn(),
+      createdAt: this.now().toISOString(),
+      manifest: {
+        schemaVersion: CURRENT_SCHEMA_VERSION,
+        dshVersion: this.ctx.dshVersion,
+        platform: this.ctx.platform as Platform,
+        sectionIds: apply.autoApply.map((r) => r.id) as SectionId[],
+        containsSecrets: false,
+      },
+      sections: apply.autoApply.reduce<Record<string, SectionData>>((acc, r) => {
+        if (r.merged !== undefined) acc[r.id] = r.merged as SectionData;
+        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: SnapshotStore = new FileSnapshotStore({ dir: this.stateDir });
+      let snapshot: Snapshot | undefined;
+      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: SyncSnapshot['sections'] = apply.autoApply.reduce<Record<string, SectionData>>((acc, r) => {
+        if (r.merged !== undefined) acc[r.id] = r.merged as SectionData;
+        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: 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;
+  }
+}