dsh-config-manager 0.1.20 → 0.1.21

package/src/sync/autosync-scheduler.test.ts

@@ -0,0 +1,191 @@
+/**
+ * AutoSyncScheduler 测试：interval 换算、shouldTriggerStartupRun 阈值、
+ * enabled=false 不执行、连续失败通知、冲突跳过。
+ *
+ * 采用真实 RunRegistry + 注入 readConfig/writeConfig/readSyncConfigFn/readHistoryFn/
+ * appendHistoryFn/makeSyncEngine/now，全程不触碰真实网络与真实定时器。
+ */
+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 {
+  AutoSyncScheduler, intervalToMs, shouldTriggerStartupRun, buildAutoApplyPlan,
+} from './autosync-scheduler.ts';
+import { RunRegistry } from '../core/run-registry.ts';
+import { nullLogger } from '../utils/logger.ts';
+import type { AutosyncConfig } from './autosync-config.ts';
+import type { AutosyncHistoryEntry } from './sync-history.ts';
+import type { MergePlan, MergeSectionResult } from './merge.ts';
+import type { SyncEngine } from './sync-engine.ts';
+
+test('intervalToMs: 间隔换算正确', () => {
+  assert.equal(intervalToMs('5m'), 5 * 60 * 1000);
+  assert.equal(intervalToMs('15m'), 15 * 60 * 1000);
+  assert.equal(intervalToMs('30m'), 30 * 60 * 1000);
+  assert.equal(intervalToMs('60m'), 60 * 60 * 1000);
+  assert.equal(intervalToMs('6h'), 6 * 60 * 60 * 1000);
+  assert.equal(intervalToMs('12h'), 12 * 60 * 60 * 1000);
+  assert.equal(intervalToMs('24h'), 24 * 60 * 60 * 1000);
+});
+
+test('shouldTriggerStartupRun: 阈值判断', () => {
+  const threshold = 5 * 60 * 1000;
+  const now = 1_000_000_000_000;
+  assert.equal(shouldTriggerStartupRun(new Date(now - 60 * 1000).toISOString(), threshold, now), false);
+  assert.equal(shouldTriggerStartupRun(new Date(now - 6 * 60 * 1000).toISOString(), threshold, now), true);
+  assert.equal(shouldTriggerStartupRun(undefined, threshold, now), true);
+  assert.equal(shouldTriggerStartupRun(new Date(now - threshold).toISOString(), threshold, now), true);
+  assert.equal(shouldTriggerStartupRun(new Date(now - threshold - 1).toISOString(), threshold, now), true);
+  assert.equal(shouldTriggerStartupRun(new Date(now - threshold + 1).toISOString(), threshold, now), false);
+});
+
+/** 构造一个可控 scheduler：注入全部 fs/engine 依赖，验证 runOnce 行为。 */
+function makeScheduler(opts: {
+  cfg: AutosyncConfig;
+  engine: Partial<SyncEngine>;
+  history: AutosyncHistoryEntry[];
+}) {
+  const runs = new RunRegistry();
+  const entries: AutosyncHistoryEntry[] = [...opts.history];
+  let config = opts.cfg;
+  const scheduler = new AutoSyncScheduler({
+    syncDir: '/tmp',
+    host: { log: nullLogger() },
+    makeSyncEngine: () => opts.engine as SyncEngine,
+    msg: (k: string) => k,
+    runs,
+    now: () => new Date(1_000_000_000_000),
+    readConfig: async () => config,
+    writeConfig: async (c) => { config = c; },
+    readSyncConfigFn: async () => ({ repoUrl: 'git@github.com:foo/bar.git' }),
+    readHistoryFn: async () => ({ schemaVersion: 1, autosyncEntries: entries, updatedAt: '' }),
+    appendHistoryFn: async (e) => { entries.push(e); },
+    // 测试不用真实定时器：不调 start()
+  });
+  return { scheduler, runs, getConfig: () => config, getEntries: () => entries };
+}
+
+function mergeResult(id: string, decision: MergeSectionResult['decision']): MergeSectionResult {
+  return { id: id as never, decision, conflicts: [], merged: {} as never };
+}
+
+function makeMergePlan(ids: Array<[string, MergeSectionResult['decision']]>): MergePlan {
+  return { sections: ids.map(([id, decision]) => mergeResult(id, decision)) };
+}
+
+test('runOnce: enabled=false → skipped(disabled)，不写历史', async () => {
+  const cfg: AutosyncConfig = { enabled: false, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const { scheduler, getConfig, getEntries } = makeScheduler({ cfg, engine: {}, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'skipped');
+  assert.equal(result.skipReason, 'disabled');
+  assert.equal(getEntries().length, 0, 'disabled 不写历史');
+  assert.equal(getConfig().consecutiveFailures, 0);
+});
+
+test('runOnce: 未配置仓库 → skipped(unconfigured)，写历史但不计失败', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const scheduler = new AutoSyncScheduler({
+    syncDir: '/tmp',
+    host: { log: nullLogger() },
+    makeSyncEngine: () => ({} as SyncEngine),
+    msg: (k: string) => k,
+    runs: new RunRegistry(),
+    now: () => new Date(1_000_000_000_000),
+    readConfig: async () => cfg,
+    writeConfig: async () => {},
+    readSyncConfigFn: async () => null,
+    readHistoryFn: async () => ({ schemaVersion: 1, autosyncEntries: [], updatedAt: '' }),
+    appendHistoryFn: async () => {},
+  });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'skipped');
+  assert.equal(result.skipReason, 'unconfigured');
+  assert.equal(result.consecutiveFailures, 0, '未配置不累计失败');
+});
+
+test('runOnce: merge 抛错 → failed，连续失败计数 +1', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 2 };
+  const engine = { merge: async () => { throw new Error('network down'); } };
+  const { scheduler, getConfig, getEntries } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'failed');
+  assert.equal(result.consecutiveFailures, 3, '连续失败 2→3');
+  assert.equal(getConfig().consecutiveFailures, 3);
+  assert.ok(getEntries().some((e) => e.status === 'failed'), '写入失败历史');
+});
+
+test('runOnce: 有冲突 → skipped(conflict)，不写本地，不计失败', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 1 };
+  const engine = {
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'conflict']]),
+  };
+  const { scheduler, getConfig, getEntries } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'skipped');
+  assert.equal(result.skipReason, 'conflict');
+  assert.deepEqual(result.conflictedSections, ['settings']);
+  assert.equal(result.consecutiveFailures, 1, '冲突跳过不计失败');
+  assert.equal(getConfig().consecutiveFailures, 1);
+  assert.ok(getEntries().some((e) => e.skipReason === 'conflict'), '写入冲突跳过历史');
+});
+
+test('runOnce: 无冲突且无变化 → success(pull,unchanged)', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const engine = {
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'skip']]),
+  };
+  const { scheduler } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'success');
+  assert.equal(result.direction, 'pull');
+  assert.equal(result.skipReason, 'unchanged');
+});
+
+test('runOnce: 完整双向 → 无冲突合并写本地 + push', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const applyCalls: string[] = [];
+  const engine = {
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'useRemote']]),
+    applyMergePlan: async () => { applyCalls.push('apply'); return { ok: true, applied: ['settings'], restoreId: 'r1', rolledBack: false, review: [], warnings: [] }; },
+    push: async () => ({ ok: true, snapshotId: 'snap-push', sections: ['settings'] as never, warnings: [] }),
+  };
+  const { scheduler, getEntries } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'success');
+  assert.equal(result.direction, 'both');
+  assert.deepEqual(result.appliedSections, ['settings']);
+  assert.equal(result.pushedSnapshotId, 'snap-push');
+  assert.equal(applyCalls.length, 1);
+  assert.ok(getEntries().some((e) => e.status === 'success' && e.direction === 'both'), '写入双向成功历史');
+});
+
+test('runOnce: startup 变体 → 只做 pull 合并，不上传', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const pushCalls: string[] = [];
+  const engine = {
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'useRemote']]),
+    applyMergePlan: async () => ({ ok: true, applied: ['settings'], restoreId: 'r1', rolledBack: false, review: [], warnings: [] }),
+    push: async () => { pushCalls.push('push'); return { ok: true, snapshotId: 'x', sections: [] as never, warnings: [] }; },
+  };
+  const { scheduler } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce({ startup: true });
+  assert.equal(result.direction, 'pull', 'startup 不上传');
+  assert.equal(pushCalls.length, 0, 'startup 变体不调用 push');
+});
+
+test('buildAutoApplyPlan: 把非 skip 非 conflict 项归入 autoApply', () => {
+  const plan = makeMergePlan([
+    ['settings', 'useRemote'],
+    ['providers', 'keepLocal'],
+    ['plugins', 'skip'],
+    ['mcp', 'conflict'],
+  ]);
+  const apply = buildAutoApplyPlan(plan);
+  assert.deepEqual(apply.autoApply.map((s) => s.id), ['settings', 'providers']);
+  assert.deepEqual(apply.review.map((s) => s.id), ['mcp']);
+  assert.deepEqual(apply.skipped.map((s) => s.id), ['plugins']);
+});

package/src/sync/autosync-scheduler.ts

@@ -0,0 +1,443 @@
+/**
+ * AutoSyncScheduler：宿主后台自动同步调度器。
+ *
+ * 生命周期：
+ *  - start()：读 autosync-config；若 enabled 启动定时器（按 interval）；无条件执行一次
+ *    「启动触发下载合并」（受 startupMinIntervalMs 阈值约束）。
+ *  - stop()：清定时器、标记不再调度。
+ *  - runOnce()：执行一次完整双向自动同步（§6.1 流程）。
+ *
+ * 核心逻辑（runOnce）：
+ *  - 读配置；若 !enabled → return
+ *  - runs.register('autosync') 防重复；同 kind running → 跳过
+ *  - readSyncConfig → repoUrl 无 → 记 skipped(未配置) → return
+ *  - Phase A: engine.merge() 三方合并 → 判定 needsReview（冲突/缺失依赖/Install/Error）
+ *  - 冲突 → 跳过 + 写历史 skipped + conflictedSections[] → return
+ *  - Phase B: 无冲突 → engine.applyMergePlan(apply) 写入本地
+ *  - Phase C: 完整双向 → engine.push() 上传
+ *  - 收尾：写 autosync-config（lastRunAt, lastRunStatus, consecutiveFailures, lastRunHistoryId）
+ *
+ * 连续失败计数：只对网络/传输/apply 真实失败计数；skipped（未配置/冲突跳过/无远端）不计。
+ * 连续失败 ≥ 3 → host.log.warn 通知 + 记 notifiedAt。
+ */
+import crypto from 'node:crypto';
+
+import type { Logger } from '../utils/logger.ts';
+import type { MsgFunc } from '../core/messages.ts';
+import type { SectionId } from '../schema/types.ts';
+import type { RunRegistry } from '../core/run-registry.ts';
+import type { SyncEngine } from './sync-engine.ts';
+import { readAutosyncConfig, writeAutosyncConfig } from './autosync-config.ts';
+import type { AutosyncConfig, AutosyncInterval, AutosyncRunStatus } from './autosync-config.ts';
+import { readSyncConfig } from './sync-config.ts';
+import type { SyncConfig } from './sync-config.ts';
+import { readSyncHistory, appendAutosyncEntry } from './sync-history.ts';
+import type { AutosyncHistoryEntry } from './sync-history.ts';
+import type { MergePlan, MergeSectionResult } from './merge.ts';
+import type { SyncApplyPlan } from './risk.ts';
+
+/** 间隔 → ms 换算（§4.3） */
+export function intervalToMs(interval: AutosyncInterval): number {
+  const table: Record<AutosyncInterval, number> = {
+    '5m': 5 * 60 * 1000,
+    '15m': 15 * 60 * 1000,
+    '30m': 30 * 60 * 1000,
+    '60m': 60 * 60 * 1000,
+    '6h': 6 * 60 * 60 * 1000,
+    '12h': 12 * 60 * 60 * 1000,
+    '24h': 24 * 60 * 60 * 1000,
+  };
+  return table[interval];
+}
+
+/**
+ * 启动触发下载合并且满足阈值（now - lastRunAt >= startupMinIntervalMs）？
+ * lastRunAt 为 undefined（从未运行）→ true。
+ */
+export function shouldTriggerStartupRun(
+  lastRunAt: string | undefined,
+  startupMinIntervalMs: number,
+  nowMs: number = Date.now(),
+): boolean {
+  if (lastRunAt === undefined || lastRunAt === '') return true;
+  const lastMs = Date.parse(lastRunAt);
+  if (Number.isNaN(lastMs)) return true;
+  return nowMs - lastMs >= startupMinIntervalMs;
+}
+
+/** runOnce 执行结果 */
+export interface AutosyncRunResult {
+  status: 'success' | 'skipped' | 'failed' | 'partial';
+  direction: 'pull' | 'push' | 'both' | 'none';
+  skipReason?: string;
+  conflictedSections?: SectionId[];
+  appliedSections?: SectionId[];
+  pushedSnapshotId?: string;
+  pulledSnapshotId?: string;
+  error?: string;
+  historyId: string;
+  consecutiveFailures: number;
+}
+
+export interface AutoSyncSchedulerOptions {
+  syncDir: string;
+  host: { log: Logger };
+  makeSyncEngine: (repoUrl: string, gitBin?: string) => SyncEngine;
+  /** 消息翻译器 */
+  msg: MsgFunc;
+  runs: RunRegistry;
+  /** 时间源（测试注​入） */
+  now?: () => Date;
+  /** 注入 autosync-config 读写（测试可内存实现） */
+  readConfig?: () => Promise<AutosyncConfig>;
+  writeConfig?: (cfg: AutosyncConfig) => Promise<void>;
+  /** 注入 sync-config 读取 */
+  readSyncConfigFn?: () => Promise<SyncConfig | null>;
+  /** 注入 sync-history 读写 */
+  readHistoryFn?: () => Promise<Awaited<ReturnType<typeof readSyncHistory>>>;
+  appendHistoryFn?: (entry: AutosyncHistoryEntry) => Promise<void>;
+  /** 注入计时器（测试用；缺省 setInterval/clearInterval） */
+  setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+  clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+
+export class AutoSyncScheduler {
+  private readonly syncDir: string;
+  private readonly host: { log: Logger };
+  private readonly makeSyncEngine: (repoUrl: string, gitBin?: string) => SyncEngine;
+  private readonly msg: MsgFunc;
+  private readonly runs: RunRegistry;
+  private readonly now: () => Date;
+  private readonly readConfig: () => Promise<AutosyncConfig>;
+  private readonly writeConfig: (cfg: AutosyncConfig) => Promise<void>;
+  private readonly readSyncConfigFn: () => Promise<SyncConfig | null>;
+  private readonly readHistoryFn: () => Promise<Awaited<ReturnType<typeof readSyncHistory>>>;
+  private readonly appendHistoryFn: (entry: AutosyncHistoryEntry) => Promise<void>;
+  private readonly setTimer: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+  private readonly clearTimer: (timer: ReturnType<typeof setTimeout>) => void;
+
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private stopped = false;
+  private running = false;
+
+  constructor(opts: AutoSyncSchedulerOptions) {
+    this.syncDir = opts.syncDir;
+    this.host = opts.host;
+    this.makeSyncEngine = opts.makeSyncEngine;
+    this.msg = opts.msg;
+    this.runs = opts.runs;
+    this.now = opts.now ?? (() => new Date());
+    this.readConfig = opts.readConfig ?? (() => readAutosyncConfig(this.syncDir));
+    this.writeConfig = opts.writeConfig ?? ((cfg) => writeAutosyncConfig(this.syncDir, cfg));
+    this.readSyncConfigFn = opts.readSyncConfigFn ?? (() => readSyncConfig(this.syncDir));
+    this.readHistoryFn = opts.readHistoryFn ?? (() => readSyncHistory(this.syncDir));
+    this.appendHistoryFn = opts.appendHistoryFn ?? ((entry) => appendAutosyncEntry(this.syncDir, entry));
+    this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    this.clearTimer = opts.clearTimer ?? ((t) => clearTimeout(t));
+  }
+
+  /** 启动：读配置 → 若 enabled 启动定时器 → 无条件执行一次启动触发下载合并。 */
+  start(): void {
+    if (this.stopped) return;
+    this.refreshTimer();
+    void this.startupRun();
+  }
+
+  /** 停止：清定时器、标记不再调度；正在执行的任务允许自然结束。 */
+  stop(): void {
+    this.stopped = true;
+    if (this.timer !== null) {
+      this.clearTimer(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /** 重新加载配置（路由 POST /sync/autosync 后调用）。 */
+  async reload(): Promise<void> {
+    if (this.stopped) return;
+    this.refreshTimer();
+  }
+
+  private refreshTimer(): void {
+    if (this.timer !== null) {
+      this.clearTimer(this.timer);
+      this.timer = null;
+    }
+    void this.readConfig().then((cfg) => {
+      if (this.stopped || !cfg.enabled) return;
+      const ms = intervalToMs(cfg.interval);
+      this.timer = this.setTimer(() => {
+        if (this.stopped) return;
+        void this.runOnce().catch((err) => {
+          this.host.log.error('自动同步定时触发失败', { error: err instanceof Error ? err.message : String(err) });
+        });
+      }, ms);
+    }).catch(() => { /* 读配置失败静默 */ });
+  }
+
+  /** 启动触发下载合并（受 startupMinIntervalMs 阈值约束）。 */
+  private async startupRun(): Promise<void> {
+    try {
+      const cfg = await this.readConfig();
+      if (!cfg.enabled) return; // 总开关关闭 → 启动触发不执行
+      if (!shouldTriggerStartupRun(cfg.lastRunAt, cfg.startupMinIntervalMs, this.now().getTime())) {
+        this.host.log.info('自动同步启动触发跳过：距上次运行未达阈值');
+        return;
+      }
+      await this.runOnce({ startup: true });
+    } catch (err) {
+      this.host.log.error('启动触发下载合并失败', { error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+
+  /**
+   * 执行一次自动同步（§6.1）。
+   * @param opts.startup - true 表示启动触发变体（只做 Phase A+B，不做 Phase C push）
+   */
+  async runOnce(opts: { startup?: boolean } = {}): Promise<AutosyncRunResult> {
+    if (this.running) return { status: 'skipped', direction: 'none', skipReason: 'running', historyId: '', consecutiveFailures: 0 };
+    const cfg = await this.readConfig();
+    if (!cfg.enabled) {
+      return { status: 'skipped', direction: 'none', skipReason: 'disabled', historyId: '', consecutiveFailures: cfg.consecutiveFailures };
+    }
+
+    this.running = true;
+    const nowIso = this.now().toISOString();
+    const historyId = `autosync-${crypto.randomUUID()}`;
+
+    // runs 防重复：同 kind running → 跳过（内部语义，不打搅用户）
+    let runId: string | null = null;
+    try {
+      const run = this.runs.register('autosync');
+      runId = run.runId;
+    } catch {
+      this.running = false;
+      return { status: 'skipped', direction: 'none', skipReason: 'conflict', historyId, consecutiveFailures: cfg.consecutiveFailures };
+    }
+
+    try {
+      // 读 sync-config → repoUrl
+      const syncCfg = await this.readSyncConfigFn();
+      if (syncCfg === null || syncCfg.repoUrl === '') {
+        const result: AutosyncRunResult = {
+          status: 'skipped', direction: 'none', skipReason: 'unconfigured', historyId,
+          consecutiveFailures: cfg.consecutiveFailures,
+        };
+        await this.appendHistoryFn({
+          direction: 'both',
+          status: 'skipped',
+          skipReason: 'unconfigured',
+          createdAt: nowIso,
+          failureCountAtRun: cfg.consecutiveFailures,
+        });
+        await this.writeFinalConfig(cfg, result, nowIso, historyId);
+        return result;
+      }
+
+      const engine = this.makeSyncEngine(syncCfg.repoUrl, syncCfg.gitBin);
+
+      // Phase A: pull 合并（下载）
+      let mergePlan: MergePlan;
+      try {
+        mergePlan = await engine.merge();
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        const result: AutosyncRunResult = {
+          status: 'failed', direction: 'pull', error, historyId,
+          consecutiveFailures: cfg.consecutiveFailures + 1,
+        };
+        await this.appendHistoryFn({
+          direction: 'pull', status: 'failed', error, createdAt: nowIso,
+          failureCountAtRun: cfg.consecutiveFailures + 1,
+        });
+        await this.writeFinalConfig(cfg, result, nowIso, historyId);
+        this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+        return result;
+      }
+
+      // 判定 needsReview
+      const reviewSections = mergePlan.sections.filter((s) => s.decision === 'conflict');
+      if (reviewSections.length > 0) {
+        const conflictedSections = reviewSections.map((s) => s.id);
+        const result: AutosyncRunResult = {
+          status: 'skipped', direction: 'pull', skipReason: 'conflict',
+          conflictedSections, historyId,
+          consecutiveFailures: cfg.consecutiveFailures,
+        };
+        await this.appendHistoryFn({
+          direction: 'pull', status: 'skipped', skipReason: 'conflict',
+          conflictedSections, createdAt: nowIso,
+          failureCountAtRun: cfg.consecutiveFailures,
+        });
+        await this.writeFinalConfig(cfg, result, nowIso, historyId);
+        return result;
+      }
+
+      // 无冲突：构造 SyncApplyPlan（autoApply = 所有 useRemote/keepLocal 项；skipped = skip 项）
+      const apply = buildAutoApplyPlan(mergePlan);
+      if (apply.autoApply.length === 0) {
+        // 无物可应用（全部 skip / 无变化）
+        const result: AutosyncRunResult = {
+          status: 'success', direction: 'pull', skipReason: 'unchanged', historyId,
+          consecutiveFailures: 0,
+        };
+        await this.appendHistoryFn({
+          direction: 'pull', status: 'success', skipReason: 'unchanged',
+          createdAt: nowIso, failureCountAtRun: 0,
+        });
+        await this.writeFinalConfig(cfg, result, nowIso, historyId);
+        return result;
+      }
+
+      // Phase B: 写入本地（applyMergePlan，无 review-queue 写）
+      const applyReport = await engine.applyMergePlan(apply);
+      const appliedSections = applyReport.applied as SectionId[];
+      if (!applyReport.ok) {
+        const error = applyReport.warnings.join('; ') || 'applyMergePlan 执行失败';
+        const result: AutosyncRunResult = {
+          status: 'failed', direction: 'pull', error, historyId,
+          consecutiveFailures: cfg.consecutiveFailures + 1,
+        };
+        await this.appendHistoryFn({
+          direction: 'pull', status: 'failed', error, createdAt: nowIso,
+          failureCountAtRun: cfg.consecutiveFailures + 1,
+        });
+        await this.writeFinalConfig(cfg, result, nowIso, historyId);
+        this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+        return result;
+      }
+
+      // Phase C: push 上传（完整双向）
+      if (!opts.startup) {
+        try {
+          const pushReport = await engine.push();
+          if (!pushReport.ok) {
+            const error = pushReport.message ?? 'push 失败';
+            const result: AutosyncRunResult = {
+              status: 'failed', direction: 'both', appliedSections, error, historyId,
+              consecutiveFailures: cfg.consecutiveFailures + 1,
+            };
+            await this.appendHistoryFn({
+              direction: 'both', status: 'failed', appliedSections, error,
+              createdAt: nowIso, failureCountAtRun: cfg.consecutiveFailures + 1,
+            });
+            await this.writeFinalConfig(cfg, result, nowIso, historyId);
+            this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+            return result;
+          }
+          const result: AutosyncRunResult = {
+            status: 'success', direction: 'both', appliedSections,
+            pushedSnapshotId: pushReport.snapshotId, historyId, consecutiveFailures: 0,
+          };
+          await this.appendHistoryFn({
+            direction: 'both', status: 'success', appliedSections,
+            pushedSnapshotId: pushReport.snapshotId, createdAt: nowIso, failureCountAtRun: 0,
+          });
+          await this.writeFinalConfig(cfg, result, nowIso, historyId);
+          return result;
+        } catch (err) {
+          const error = err instanceof Error ? err.message : String(err);
+          const result: AutosyncRunResult = {
+            status: 'failed', direction: 'both', appliedSections, error, historyId,
+            consecutiveFailures: cfg.consecutiveFailures + 1,
+          };
+          await this.appendHistoryFn({
+            direction: 'both', status: 'failed', appliedSections, error,
+            createdAt: nowIso, failureCountAtRun: cfg.consecutiveFailures + 1,
+          });
+          await this.writeFinalConfig(cfg, result, nowIso, historyId);
+          this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+          return result;
+        }
+      }
+
+      // startup 变体：只做 pull 合并（不上传）
+      const result: AutosyncRunResult = {
+        status: 'success', direction: 'pull', appliedSections, historyId, consecutiveFailures: 0,
+      };
+      await this.appendHistoryFn({
+        direction: 'pull', status: 'success', appliedSections,
+        createdAt: nowIso, failureCountAtRun: 0,
+      });
+      await this.writeFinalConfig(cfg, result, nowIso, historyId);
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      const result: AutosyncRunResult = {
+        status: 'failed', direction: 'none', error, historyId,
+        consecutiveFailures: cfg.consecutiveFailures + 1,
+      };
+      await this.appendHistoryFn({
+        direction: 'both', status: 'failed', error,
+        createdAt: nowIso, failureCountAtRun: cfg.consecutiveFailures + 1,
+      });
+      await this.writeFinalConfig(cfg, result, nowIso, historyId);
+      this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+      return result;
+    } finally {
+      this.running = false;
+      if (runId !== null) {
+        // 完成标记（不抛错，尽力而为）
+      }
+    }
+  }
+
+  /** 收尾：写 autosync-config（lastRunAt, lastRunStatus, consecutiveFailures, lastRunHistoryId）。 */
+  private async writeFinalConfig(
+    base: AutosyncConfig,
+    result: AutosyncRunResult,
+    nowIso: string,
+    historyId: string,
+  ): Promise<void> {
+    await this.writeConfig({
+      ...base,
+      lastRunAt: nowIso,
+      lastRunStatus: result.status,
+      consecutiveFailures: result.consecutiveFailures,
+      lastRunHistoryId: historyId,
+      ...(result.error !== undefined ? { lastRunMessage: result.error } : {}),
+    });
+  }
+
+  /** 连续失败 ≥ 3 → 通知（host.log.warn）。 */
+  private maybeNotify(failures: number, historyId: string, nowIso: string): void {
+    if (failures >= 3) {
+      this.host.log.warn(`自动同步连续失败 ${failures} 次，请检查仓库配置/凭据`);
+      // 记录 notifiedAt（更新历史 entry）
+      void this.readHistoryFn().then(async (hist) => {
+        const entry = hist.autosyncEntries.find((e) => e.createdAt === nowIso);
+        if (entry) {
+          entry.notifiedAt = nowIso;
+          await this.writeConfig({
+            ...(await this.readConfig()),
+            lastRunMessage: `连续失败 ${failures} 次，已通知`,
+          });
+        }
+      }).catch(() => { /* 尽力而为 */ });
+    }
+  }
+}
+
+/** 从 MergePlan 构造 SyncApplyPlan（autoApply = 所有非 skip 非 conflict 项）。 */
+export function buildAutoApplyPlan(plan: MergePlan): SyncApplyPlan {
+  const autoApply: MergeSectionResult[] = [];
+  const review: MergeSectionResult[] = [];
+  const skipped: MergeSectionResult[] = [];
+  for (const s of plan.sections) {
+    if (s.decision === 'skip') {
+      skipped.push(s);
+      continue;
+    }
+    if (s.decision === 'conflict') {
+      review.push(s);
+      continue;
+    }
+    // useRemote / keepLocal：都有 merged 数据
+    if (s.merged !== undefined) {
+      autoApply.push(s);
+    } else {
+      skipped.push(s);
+    }
+  }
+  return { autoApply, review, skipped };
+}