dsh-config-manager 0.1.20 → 0.1.21

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

@@ -0,0 +1,82 @@
+/**
+ * m-sync-ui (方案 A)：同步历史投影（含自动同步记录）纯函数测试。
+ * TDD：先写失败测试，再实现 history-model.ts 对应函数。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import type { SyncHistoryEntry } from './sync-api.ts';
+import {
+  autosyncStatusLabel, describeSkipReason, directionLabel, formatDateTime,
+  projectAutosyncEntry, projectSyncHistoryEntries,
+} from './history-model.ts';
+import type { AutosyncHistoryEntry } from './sync-api.ts';
+
+const autosyncEntry = (overrides: Partial<AutosyncHistoryEntry>): AutosyncHistoryEntry => ({
+  direction: 'both',
+  status: 'skipped',
+  skipReason: 'conflict',
+  conflictedSections: ['settings', 'plugins'],
+  appliedSections: [],
+  failureCountAtRun: 0,
+  createdAt: '2026-08-17T10:00:00.000Z',
+  ...overrides,
+});
+
+test('projectSyncHistoryEntries：快照 + 自动同步 按 createdAt 倒序合并', () => {
+  const entries: SyncHistoryEntry[] = [
+    { id: 'a', createdAt: '2026-08-17T10:00:00.000Z', kind: 'apply', sectionCount: 3, reviewCount: 0 },
+    {
+      id: 'b', createdAt: '2026-08-17T12:00:00.000Z', kind: 'autosync',
+      autosync: autosyncEntry({ createdAt: '2026-08-17T12:00:00.000Z' }),
+    },
+    { id: 'c', createdAt: '2026-08-17T11:00:00.000Z', kind: 'apply', sectionCount: 2, reviewCount: 0 },
+  ];
+  const sorted = projectSyncHistoryEntries(entries);
+  assert.equal(sorted[0]!.id, 'b');
+  assert.equal(sorted[1]!.id, 'c');
+  assert.equal(sorted[2]!.id, 'a');
+});
+
+test('directionLabel / autosyncStatusLabel：方向与状态映射', () => {
+  assert.equal(directionLabel('pull'), '下载');
+  assert.equal(directionLabel('push'), '上传');
+  assert.equal(directionLabel('both'), '双向');
+  assert.equal(autosyncStatusLabel('success'), '成功');
+  assert.equal(autosyncStatusLabel('skipped'), '已跳过');
+  assert.equal(autosyncStatusLabel('failed'), '失败');
+  assert.equal(autosyncStatusLabel('partial'), '部分成功');
+});
+
+test('describeSkipReason：已知原因映射，未知回退原串', () => {
+  assert.equal(describeSkipReason('conflict'), '冲突项被跳过');
+  assert.equal(describeSkipReason('no-remote'), '远端无快照');
+  assert.equal(describeSkipReason('not-configured'), '未配置仓库');
+  assert.equal(describeSkipReason('network'), '网络问题');
+  assert.equal(describeSkipReason('weird'), 'weird');
+  assert.equal(describeSkipReason(undefined), '未知');
+});
+
+test('projectAutosyncEntry：摘要行 + 可展开明细（冲突分区 / 应用分区 / 错误）', () => {
+  const row = projectAutosyncEntry(autosyncEntry({}));
+  assert.equal(row.direction, '双向');
+  assert.equal(row.status, '已跳过');
+  assert.match(row.summary, /双向/);
+  assert.match(row.summary, /已跳过/);
+  assert.match(row.summary, /冲突项被跳过/);
+  assert.deepEqual(row.conflictedSections, ['settings', 'plugins']);
+  assert.equal(row.hasDetail, true);
+});
+
+test('projectAutosyncEntry：无冲突/无应用/无错误 → hasDetail=false', () => {
+  const row = projectAutosyncEntry(autosyncEntry({
+    conflictedSections: undefined, appliedSections: undefined, error: undefined,
+  }));
+  assert.equal(row.hasDetail, false);
+});
+
+test('formatDateTime：合法 ISO → 本地格式；空/非法回退', () => {
+  assert.match(formatDateTime('2026-08-17T10:30:00.000Z'), /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/);
+  assert.equal(formatDateTime(''), '—');
+  assert.equal(formatDateTime('not-a-date'), 'not-a-date');
+});

package/src/client/sync/history-model.ts

@@ -1,6 +1,13 @@
 /**
  * m-sync-ui (P2b)：SyncHistoryView 的纯函数投影。
+ *
+ * 现状：本地祖先快照目录（manifest.json）→ SnapshotHistoryEntry；倒序排序 + ISO 格式化。
+ * 方案 A 扩展：/sync/history 现返回 { entries: SyncHistoryEntry[] }（快照 kind=apply
+ * + 自动同步 kind=autosync），投影需统一处理两源，并生成自动同步跳过冲突的可读明细。
  */
+import type { AutosyncHistoryEntry, SyncHistoryEntry } from './sync-api.ts';
+
+/** 兼容旧快照条目（manifest.json 投影）。 */
 export interface SnapshotHistoryEntry {
   id: string;
   createdAt: string;
@@ -10,9 +17,18 @@ export interface SnapshotHistoryEntry {
   reviewCount: number;
 }
 
-/** 把 entries 排序（createdAt 倒序）并组装展示字段。 */
+/** 把快照 entries 排序（createdAt 倒序）并组装展示字段。 */
 export function projectHistoryRows(entries: readonly SnapshotHistoryEntry[]): SnapshotHistoryEntry[] {
-  return [...entries].sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+  return [...entries].sort(byCreatedAtDesc);
+}
+
+/** 统一历史条目（快照 + 自动同步）按 createdAt 倒序排序。 */
+export function projectSyncHistoryEntries(entries: readonly SyncHistoryEntry[]): SyncHistoryEntry[] {
+  return [...entries].sort(byCreatedAtDesc);
+}
+
+function byCreatedAtDesc(a: { createdAt: string }, b: { createdAt: string }): number {
+  return a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0;
 }
 
 /** ISO 时间 → 本地可读字符串（短格式） */
@@ -23,3 +39,74 @@ export function formatDateTime(iso: string): string {
   const pad = (n: number) => String(n).padStart(2, '0');
   return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
 }
+
+/* ---------------------------------------------------------------- 自动同步记录投影 */
+
+/** 自动同步执行记录的方向可读标签。 */
+export function directionLabel(direction: AutosyncHistoryEntry['direction']): string {
+  switch (direction) {
+    case 'pull': return '下载';
+    case 'push': return '上传';
+    default: return '双向';
+  }
+}
+
+/** 自动同步执行状态可读标签。 */
+export function autosyncStatusLabel(status: AutosyncHistoryEntry['status']): string {
+  switch (status) {
+    case 'success': return '成功';
+    case 'skipped': return '已跳过';
+    case 'partial': return '部分成功';
+    default: return '失败';
+  }
+}
+
+/** 跳过原因 → 可读描述（host 透传语义；未知原因回退原串）。 */
+export function describeSkipReason(reason: string | undefined): string {
+  switch (reason) {
+    case 'conflict': return '冲突项被跳过';
+    case 'no-remote': return '远端无快照';
+    case 'not-configured': return '未配置仓库';
+    case 'network': return '网络问题';
+    default: return reason ?? '未知';
+  }
+}
+
+/** 把一条自动同步记录投影为展示行（摘要文本 + 可展开的被跳过冲突分区明细）。 */
+export interface AutosyncHistoryRow {
+  id: string;
+  createdAt: string;
+  direction: string;
+  status: string;
+  /** 摘要行文本（如「下载 · 已跳过 · 冲突项被跳过」）。 */
+  summary: string;
+  /** 被跳过的冲突分区 id（展开明细用）；无则 undefined。 */
+  conflictedSections?: string[];
+  /** 实际应用的分区 id。 */
+  appliedSections?: string[];
+  error?: string;
+  notifiedAt?: string;
+  /** 是否有关联的跳过分区明细可展开。 */
+  hasDetail: boolean;
+}
+
+/** 自动同步记录 → 展示行投影。 */
+export function projectAutosyncEntry(entry: AutosyncHistoryEntry): AutosyncHistoryRow {
+  const parts: string[] = [directionLabel(entry.direction), autosyncStatusLabel(entry.status)];
+  if (entry.skipReason !== undefined) parts.push(describeSkipReason(entry.skipReason));
+  return {
+    id: entry.createdAt,
+    createdAt: entry.createdAt,
+    direction: directionLabel(entry.direction),
+    status: autosyncStatusLabel(entry.status),
+    summary: parts.join(' · '),
+    conflictedSections: entry.conflictedSections,
+    appliedSections: entry.appliedSections,
+    error: entry.error,
+    notifiedAt: entry.notifiedAt,
+    hasDetail:
+      (entry.conflictedSections !== undefined && entry.conflictedSections.length > 0) ||
+      (entry.appliedSections !== undefined && entry.appliedSections.length > 0) ||
+      entry.error !== undefined,
+  };
+}

package/src/client/sync/sync-api.test.ts

@@ -177,3 +177,158 @@ test('S-09 api.githubCancel()：POST /sync/github/cancel 携带 flowId', async (
   const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>;
   assert.equal(sent['flowId'], 'flow-1');
 });
+
+/* ------------------------------------------------ 一键同步（方案 A）端点契约 */
+
+test('S-10 api.snapshotsList()：POST /sync/snapshots-list，解析倒序快照列表 + currentSnapshotId', async () => {
+  const body = {
+    ok: true,
+    snapshots: [
+      { id: 'sync-2', createdAt: '2026-08-17T10:00:00.000Z', sectionCount: 3, platform: 'darwin', dshVersion: '1.0.0' },
+      { id: 'sync-1', createdAt: '2026-08-16T10:00:00.000Z', sectionCount: 2, platform: 'darwin', dshVersion: '1.0.0' },
+    ],
+    currentSnapshotId: 'sync-1',
+  };
+  const calls: FetchCall[] = [];
+  installFetchMock((call) => {
+    calls.push(call);
+    return jsonResponse(200, body);
+  });
+  const api = new SyncApi();
+  const result = await api.snapshotsList({ repoUrl: 'https://github.com/u/r.git' });
+  assert.equal(result.ok, true);
+  assert.equal(result.snapshots.length, 2);
+  assert.equal(result.snapshots[0]?.id, 'sync-2');
+  assert.equal(result.currentSnapshotId, 'sync-1');
+  assert.equal(calls[0]?.url, SYNC_API.snapshotsList);
+  assert.equal(calls[0]?.init?.method, 'POST');
+});
+
+test('S-11 api.sync()：POST /sync/sync，请求体携带 snapshotId；响应含 items/needsReview/compatibility', async () => {
+  const body = {
+    ok: true,
+    syncSessionId: 'sess-1',
+    snapshotId: 'sync-3',
+    items: [{ itemId: 'settings:a', adapter: 'settings', kind: 'Update', description: '更新', severity: 'info', defaultAdopt: true, adopt: true }],
+    needsReview: false,
+    compatibility: 'good',
+  };
+  const calls: FetchCall[] = [];
+  installFetchMock((call) => {
+    calls.push(call);
+    return jsonResponse(200, body);
+  });
+  const api = new SyncApi();
+  const result = await api.sync({ repoUrl: 'https://github.com/u/r.git', snapshotId: 'sync-3' });
+  assert.equal(result.syncSessionId, 'sess-1');
+  assert.equal(result.items.length, 1);
+  assert.equal(result.compatibility, 'good');
+  assert.equal(calls[0]?.url, SYNC_API.sync);
+  const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>;
+  assert.equal(sent['snapshotId'], 'sync-3');
+});
+
+test('S-12 api.applyItems()：POST /sync/apply-items，携带 adoptions（含 Conflict resolution）', async () => {
+  const body = {
+    ok: true, applied: ['settings'], skipped: ['plugin:x'], needsRestart: false,
+    warnings: [], restoreId: 'rest-1', rolledBack: false, failed: [], result: {},
+  };
+  const calls: FetchCall[] = [];
+  installFetchMock((call) => {
+    calls.push(call);
+    return jsonResponse(200, body);
+  });
+  const api = new SyncApi();
+  const result = await api.applyItems({
+    syncSessionId: 'sess-1',
+    adoptions: [
+      { itemId: 'settings:a', adopt: true },
+      { itemId: 'plugin:x', adopt: true, resolution: 'useRemote' },
+    ],
+  });
+  assert.equal(result.applied[0], 'settings');
+  assert.equal(result.restoreId, 'rest-1');
+  assert.equal(calls[0]?.url, SYNC_API.applyItems);
+  const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>;
+  assert.equal(sent['syncSessionId'], 'sess-1');
+  const adoptions = sent['adoptions'] as Array<Record<string, unknown>>;
+  assert.equal(adoptions[1]?.['resolution'], 'useRemote');
+});
+
+test('S-13 api.cancel()：POST /sync/cancel 携带 syncSessionId', async () => {
+  const calls: FetchCall[] = [];
+  installFetchMock((call) => {
+    calls.push(call);
+    return jsonResponse(200, { ok: true });
+  });
+  const api = new SyncApi();
+  const result = await api.cancel('sess-1');
+  assert.equal(result.ok, true);
+  assert.equal(calls[0]?.url, SYNC_API.cancel);
+  const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>;
+  assert.equal(sent['syncSessionId'], 'sess-1');
+});
+
+/* ------------------------------------------------ 自动同步端点契约 */
+
+test('S-14 api.autosyncStatus()：GET /sync/autosync，解析 enabled/interval/elapsedMs', async () => {
+  const body = {
+    enabled: true, interval: '30m', lastRunAt: '2026-08-17T10:00:00.000Z',
+    lastRunStatus: 'success', consecutiveFailures: 0, elapsedMs: 60000,
+  };
+  let called: FetchCall | null = null;
+  installFetchMock((call) => {
+    called = call;
+    return jsonResponse(200, body);
+  });
+  const lastCall = (): FetchCall | null => called;
+  const api = new SyncApi();
+  const result = await api.autosyncStatus();
+  assert.equal(result.enabled, true);
+  assert.equal(result.interval, '30m');
+  assert.equal(result.consecutiveFailures, 0);
+  assert.equal(result.elapsedMs, 60000);
+  assert.equal(lastCall()?.url, SYNC_API.autosync);
+});
+
+test('S-15 api.autosyncUpdate()：POST /sync/autosync，请求体携带 enabled/interval', async () => {
+  const body = {
+    enabled: true, interval: '60m', consecutiveFailures: 0, elapsedMs: -1,
+  };
+  const calls: FetchCall[] = [];
+  installFetchMock((call) => {
+    calls.push(call);
+    return jsonResponse(200, body);
+  });
+  const api = new SyncApi();
+  const result = await api.autosyncUpdate({ enabled: true, interval: '60m' });
+  assert.equal(result.enabled, true);
+  assert.equal(result.interval, '60m');
+  assert.equal(calls[0]?.url, SYNC_API.autosync);
+  assert.equal(calls[0]?.init?.method, 'POST');
+  const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>;
+  assert.equal(sent['enabled'], true);
+  assert.equal(sent['interval'], '60m');
+});
+
+test('S-16 api.history()：GET /sync/history，解析 { entries }（含 autosync 记录）', async () => {
+  const body = {
+    entries: [
+      { id: 'sync-1', createdAt: '2026-08-17T10:00:00.000Z', kind: 'apply', sectionCount: 3, reviewCount: 0 },
+      {
+        id: '2026-08-17T09:00:00.000Z', createdAt: '2026-08-17T09:00:00.000Z', kind: 'autosync',
+        autosync: {
+          direction: 'both', status: 'skipped', skipReason: 'conflict',
+          conflictedSections: ['settings'], failureCountAtRun: 0, createdAt: '2026-08-17T09:00:00.000Z',
+        },
+      },
+    ],
+  };
+  installFetchMock(() => jsonResponse(200, body));
+  const api = new SyncApi();
+  const result = await api.history();
+  assert.equal(result.entries.length, 2);
+  assert.equal(result.entries[0]?.kind, 'apply');
+  assert.equal(result.entries[1]?.kind, 'autosync');
+  assert.deepEqual(result.entries[1]?.autosync?.conflictedSections, ['settings']);
+});

package/src/client/sync/sync-api.ts

@@ -22,7 +22,9 @@
  *  - 错误消息由 Host 侧已脱敏（GitTransport 统一 [REDACTED]），UI 侧再经 ErrorBanner redact 兜底；
  *  - 本文件不 import 任何 node 模块（纯浏览器 bundle；sync-engine 仅作 type-only 引用）。
  */
-import type { ApplyReport, SyncPullReport, SyncPushReport } from '../../sync/sync-engine.ts';
+import type { SyncPullReport, SyncPushReport } from '../../sync/sync-engine.ts';
+import type { PlanItemKind } from '../../core/types.ts';
+import type { SectionId } from '../../schema/types.ts';
 import { ConfigManagerApiError } from '../api.ts';
 import { zhUiT, type UiT } from '../../ui/i18n.ts';
 
@@ -36,7 +38,11 @@ export const SYNC_API = {
   githubPoll: '/api/dsh-config-manager/sync/github/poll',
   githubCancel: '/api/dsh-config-manager/sync/github/cancel',
   history: '/api/dsh-config-manager/sync/history',
-  apply: '/api/dsh-config-manager/sync/apply',
+  snapshotsList: '/api/dsh-config-manager/sync/snapshots-list',
+  sync: '/api/dsh-config-manager/sync/sync',
+  applyItems: '/api/dsh-config-manager/sync/apply-items',
+  cancel: '/api/dsh-config-manager/sync/cancel',
+  autosync: '/api/dsh-config-manager/sync/autosync',
   rollback: '/api/dsh-config-manager/sync/rollback',
 } as const;
 
@@ -59,6 +65,8 @@ export interface SyncStatusResponse {
   /** sync-state.sections 条目数 */
   sectionCount: number;
   transport?: { type: string; ref: string };
+  /** 自动同步当前状态（供 UI 顶部开关回填；§3.9） */
+  autosync?: AutosyncStatusResponse;
 }
 
 /** push 请求体（token 可选：非空则 Host 先写入 DSH credentials 再使用） */
@@ -74,6 +82,172 @@ export interface SyncPullPayload extends SyncPushPayload {
   snapshotId?: string;
 }
 
+/* ---------------------------------------------------------------- 一键同步（方案 A） */
+
+/** GET /sync/snapshots-list 响应：远端历史快照列表（按 createdAt 倒序）。 */
+export interface SyncSnapshotsListResponse {
+  ok: boolean;
+  /** 按 createdAt 倒序（最新在前） */
+  snapshots: SyncSnapshotLite[];
+  /** 当前本地祖先指针（sync-state.lastSnapshotId），用于高亮当前基线 */
+  currentSnapshotId?: string;
+}
+
+/** 远端快照摘要（「选择历史快照」下拉项）。 */
+export interface SyncSnapshotLite {
+  id: string;
+  createdAt: string;
+  sectionCount: number;
+  platform: string;
+  dshVersion: string;
+}
+
+/** POST /sync/sync 请求体（一键同步第一步：拉取 → 差异确认会话）。 */
+export interface SyncStartPayload {
+  repoUrl: string;
+  gitBin?: string;
+  token?: string;
+  /** 缺省 = 最新快照；传入则对该历史快照拉取 */
+  snapshotId?: string;
+}
+
+/** POST /sync/sync 响应：差异确认会话（items 供 UI 逐项确认）。 */
+export interface SyncStartResponse {
+  ok: boolean;
+  /** 差异确认会话 id：后续 apply-items / cancel 引用 */
+  syncSessionId: string;
+  /** 被拉取的远端快照 id */
+  snapshotId: string;
+  items: SyncConfirmItem[];
+  /** 是否包含任何需人工决策项 */
+  needsReview: boolean;
+  compatibility: 'excellent' | 'good' | 'partial' | 'unsupported';
+  message?: string;
+}
+
+/** 单条可确认的差异项（由 ImportPlan.item 投影 + 冲突详情）。 */
+export interface SyncConfirmItem {
+  itemId: string;
+  adapter: SectionId;
+  kind: PlanItemKind;
+  description: string;
+  severity: 'info' | 'warning' | 'error';
+  /** 默认采纳方向；Conflict/MissingSecret 等人工项默认 false */
+  defaultAdopt: boolean;
+  /** 用户最终决策（缺省 = defaultAdopt） */
+  adopt: boolean;
+  /** 冲突项内联解决所需详情（仅 Conflict 项非空） */
+  conflict?: SyncConflictDetail;
+  /** 该项若采用将写入的目标摘要 */
+  target?: { adapter: SectionId; ref: string };
+}
+
+/** 冲突项内联解决详情（来源 MergeConflict + 可读 diff）。 */
+export interface SyncConflictDetail {
+  path: string;
+  kind: 'key' | 'file' | 'section';
+  local?: unknown;
+  remote?: unknown;
+  ancestor?: unknown;
+  diff?: string;
+}
+
+/** POST /sync/apply-items 请求体（一键同步第二步：按逐项决策执行导入）。 */
+export interface ApplyItemsPayload {
+  syncSessionId: string;
+  /** 每项的最终采纳决策（未列出项视为 adopt=false） */
+  adoptions: SyncItemAdoption[];
+}
+
+/** 单条采纳决策。 */
+export interface SyncItemAdoption {
+  itemId: string;
+  adopt: boolean;
+  /** 冲突项解决方案（仅当该项是 Conflict 且 adopt=true 时必须） */
+  resolution?: 'useRemote' | 'keepLocal' | 'skip';
+}
+
+/** POST /sync/apply-items 响应。 */
+export interface ApplyItemsResponse {
+  ok: boolean;
+  applied: string[];
+  skipped: string[];
+  needsRestart: boolean;
+  warnings: string[];
+  /** 应用前快照 id（UI 一键回滚用） */
+  restoreId: string;
+  /** 任一失败是否整体回滚 */
+  rolledBack: boolean;
+  failed: { itemId: string; message?: string }[];
+  result: unknown;
+}
+
+/* ---------------------------------------------------------------- 自动同步 */
+
+/** 统一间隔类型。 */
+export type AutosyncInterval = '5m' | '15m' | '30m' | '60m' | '6h' | '12h' | '24h';
+
+/** 最近一次自动同步执行状态。 */
+export type AutosyncRunStatus = 'success' | 'skipped' | 'failed' | 'partial';
+
+/** GET/POST /sync/autosync 响应：自动同步状态。 */
+export interface AutosyncStatusResponse {
+  enabled: boolean;
+  interval: AutosyncInterval;
+  lastRunAt?: string;
+  lastRunStatus?: AutosyncRunStatus;
+  lastRunMessage?: string;
+  consecutiveFailures: number;
+  /** 距上次自动同步已过 ms（host 计算，供 UI 倒计时/立即触发判断） */
+  elapsedMs: number;
+  lastRunHistoryId?: string;
+}
+
+/** POST /sync/autosync 请求体。 */
+export interface AutosyncUpdatePayload {
+  enabled: boolean;
+  interval?: AutosyncInterval;
+  startupMinIntervalMs?: number;
+}
+
+/* ---------------------------------------------------------------- 同步历史 */
+
+/** 自动同步执行记录（§3.7 AutosyncHistoryEntry）。 */
+export interface AutosyncHistoryEntry {
+  direction: 'pull' | 'push' | 'both';
+  status: 'success' | 'skipped' | 'failed' | 'partial';
+  /** 跳过原因（冲突项 / 缺失依赖 / Install / 错误 / 无远端 / 网络） */
+  skipReason?: string;
+  /** 被跳过的冲突分区 id（冲突跳过时列出） */
+  conflictedSections?: string[];
+  /** 本次自动合并实际写入的分区 */
+  appliedSections?: string[];
+  /** 本次 push 产生的快照 id */
+  pushedSnapshotId?: string;
+  /** 本次 pull 来源快照 id */
+  pulledSnapshotId?: string;
+  error?: string;
+  notifiedAt?: string;
+  /** 本次触发时的连续失败计数 */
+  failureCountAtRun: number;
+  createdAt: string;
+}
+
+/** 同步历史条目（Host 端返回；kind='autosync' 时 autosync 非空）。 */
+export interface SyncHistoryEntry {
+  id: string;
+  createdAt: string;
+  kind: 'push' | 'pull' | 'apply' | 'autosync' | 'rollback';
+  sectionCount?: number;
+  reviewCount?: number;
+  autosync?: AutosyncHistoryEntry;
+}
+
+/** GET /sync/history 响应：{ entries }。 */
+export interface SyncHistoryResponse {
+  entries: SyncHistoryEntry[];
+}
+
 /* ---------------------------------------------------------------- GitHub OAuth device flow */
 
 /** POST /sync/github/start 响应：UI 展示用（device_code 只存宿主，绝不回传） */
@@ -193,15 +367,41 @@ export class SyncApi {
     return postJson<{ ok: boolean }>(SYNC_API.githubCancel, { flowId }, this.t);
   }
 
-  /** 同步历史：列出 localSnapshotsDir 下的快照目录（manifest.json: id/createdAt/sectionHashes） */
-  async history(): Promise<SyncHistoryEntry[]> {
+  /** 同步历史：列出本地祖先快照 + 自动同步执行记录（按 createdAt 倒序合并）。 */
+  async history(): Promise<SyncHistoryResponse> {
     const response = await fetch(SYNC_API.history);
-    return readJson<SyncHistoryEntry[]>(response, this.t);
+    return readJson<SyncHistoryResponse>(response, this.t);
   }
 
-  /** 应用自动应用计划：写本地 + backup + (失败时) rollback + enqueue review；返回 ApplyReport */
-  async apply(payload: SyncPushPayload): Promise<ApplyReport> {
-    return postJson<ApplyReport>(SYNC_API.apply, payload, this.t);
+  /** 远端历史快照列表（供「选择历史快照」下拉）。 */
+  async snapshotsList(payload: SyncPushPayload): Promise<SyncSnapshotsListResponse> {
+    return postJson<SyncSnapshotsListResponse>(SYNC_API.snapshotsList, payload, this.t);
+  }
+
+  /** 一键同步第一步：拉取 → 差异确认会话（items 逐项确认，暂不导入）。 */
+  async sync(payload: SyncStartPayload): Promise<SyncStartResponse> {
+    return postJson<SyncStartResponse>(SYNC_API.sync, payload, this.t);
+  }
+
+  /** 一键同步第二步：按用户对差异项的逐项决策执行导入。 */
+  async applyItems(payload: ApplyItemsPayload): Promise<ApplyItemsResponse> {
+    return postJson<ApplyItemsResponse>(SYNC_API.applyItems, payload, this.t);
+  }
+
+  /** 取消/清理差异确认会话（丢弃临时 ZIP，零副作用）。 */
+  async cancel(syncSessionId: string): Promise<{ ok: boolean }> {
+    return postJson<{ ok: boolean }>(SYNC_API.cancel, { syncSessionId }, this.t);
+  }
+
+  /** 自动同步状态（GET /sync/autosync）。 */
+  async autosyncStatus(): Promise<AutosyncStatusResponse> {
+    const response = await fetch(SYNC_API.autosync);
+    return readJson<AutosyncStatusResponse>(response, this.t);
+  }
+
+  /** 自动同步配置更新（POST /sync/autosync）。 */
+  async autosyncUpdate(payload: AutosyncUpdatePayload): Promise<AutosyncStatusResponse> {
+    return postJson<AutosyncStatusResponse>(SYNC_API.autosync, payload, this.t);
   }
 
   /** 一键回滚：按 restoreId 调用 backup→rollback */
@@ -209,11 +409,3 @@ export class SyncApi {
     return postJson<{ ok: boolean; full: boolean }>(SYNC_API.rollback, payload, this.t);
   }
 }
-
-/** 同步历史条目（Host 端返回） */
-export interface SyncHistoryEntry {
-  id: string;
-  createdAt: string;
-  sectionCount: number;
-  reviewCount: number;
-}