dsh-config-manager 0.1.20 → 0.1.21

package/src/index.ts

@@ -68,7 +68,7 @@ import {
 } from './core/plugin-cli.ts'
 import type {
   ConfigAdapter, CredentialsFacade, FileSystemFacade, HostContext, ImportDecisions,
-  ImportPlan, NamespaceInfo, PatchFileFacade, PluginInfo, PluginsFacade,
+  ImportPlan, NamespaceInfo, PatchFileFacade, PlanItemKind, PluginInfo, PluginsFacade,
   SettingsFacade, WorkspaceFacade,
 } from './core/types.ts'
 import { createAdapters, USER_PATCH_FILE } from './adapters/index.ts'
@@ -77,9 +77,13 @@ import { createHardenedZipParser } from './security/zip-security.ts'
 import { GitTransport } from './sync/git/git-transport.ts'
 import { DeviceFlowStore, GitHubAuthClient } from './sync/github-auth.ts'
 import { SyncEngine } from './sync/sync-engine.ts'
+import { SyncSessionStore } from './sync/sync-session.ts'
+import { AutoSyncScheduler } from './sync/autosync-scheduler.ts'
+import { defaultAutosyncConfig, readAutosyncConfig, writeAutosyncConfig } from './sync/autosync-config.ts'
+import type { AutosyncInterval, AutosyncRunStatus } from './sync/autosync-config.ts'
+import { appendAutosyncEntry, readSyncHistory } from './sync/sync-history.ts'
 import { loadSyncState, saveSyncState } from './sync/sync-state.ts'
 import { readSyncConfig, writeSyncConfig, validateRepoUrl } from './sync/sync-config.ts'
-import { classifyMergePlan } from './sync/risk.ts'
 import { MANIFEST_FILE, parseManifest } from './schema/manifest.ts'
 import { SECTION_IDS } from './schema/config.ts'
 import type { Manifest, SectionId, WorkspaceRecord } from './schema/types.ts'
@@ -152,8 +156,13 @@ const API = {
   syncGithubCancel: '/api/dsh-config-manager/sync/github/cancel',
   // P2：同步历史 / 自动应用 / 一键回滚
   syncHistory: '/api/dsh-config-manager/sync/history',
-  syncApply: '/api/dsh-config-manager/sync/apply',
   syncRollback: '/api/dsh-config-manager/sync/rollback',
+  // m-sync-v2：一键同步（差异确认会话）+ 自动同步 + 历史快照
+  syncSnapshotsList: '/api/dsh-config-manager/sync/snapshots-list',
+  syncSync: '/api/dsh-config-manager/sync/sync',
+  syncApplyItems: '/api/dsh-config-manager/sync/apply-items',
+  syncCancel: '/api/dsh-config-manager/sync/cancel',
+  syncAutosync: '/api/dsh-config-manager/sync/autosync',
 } as const
 
 /**
@@ -828,6 +837,88 @@ export function writeSyncRouteError(res: ServerResponse, error: unknown): void {
   writeJson(res, 500, { error: message })
 }
 
+/** 需要人工决策的 PlanItemKind（一键同步 needsReview 判定 + 逐项确认标记） */
+const REVIEW_KINDS: ReadonlySet<PlanItemKind> = new Set([
+  'Conflict', 'MissingSecret', 'MissingDependency', 'Install', 'Error', 'PathMapping',
+])
+
+/** 一键同步差异项（client 逐项确认的最小契约；与 sync-api.ts SyncConfirmItem 对齐） */
+interface SyncConfirmItem {
+  itemId: string
+  adapter: SectionId
+  kind: PlanItemKind
+  description: string
+  severity: 'info' | 'warning' | 'error'
+  defaultAdopt: boolean
+  adopt: boolean
+  conflict?: { path: string; kind: 'key' | 'file' | 'section'; local?: unknown; remote?: unknown; ancestor?: unknown; diff?: string }
+  target?: { adapter: SectionId; ref: string }
+}
+
+/** 把 ImportPlan 投影为逐项可确认的差异项（默认采用 Create/Update/Install；人工项默认不采用）。 */
+function planToConfirmItems(plan: ImportPlan): SyncConfirmItem[] {
+  return plan.items.map((item) => {
+    const manual = REVIEW_KINDS.has(item.kind)
+    let conflict: SyncConfirmItem['conflict']
+    if (item.kind === 'Conflict') {
+      const c = (item as { conflict?: { path?: string; kind?: string; local?: unknown; remote?: unknown; ancestor?: unknown } }).conflict
+      conflict = {
+        path: c?.path ?? '$',
+        kind: c?.kind === 'file' ? 'file' : c?.kind === 'section' ? 'section' : 'key',
+        ...(c?.local !== undefined ? { local: c.local } : {}),
+        ...(c?.remote !== undefined ? { remote: c.remote } : {}),
+        ...(c?.ancestor !== undefined ? { ancestor: c.ancestor } : {}),
+      }
+    }
+    return {
+      itemId: item.id,
+      adapter: item.adapter,
+      kind: item.kind,
+      description: item.description,
+      severity: item.severity,
+      defaultAdopt: !manual,
+      adopt: !manual,
+      ...(conflict !== undefined ? { conflict } : {}),
+      ...(item.target !== undefined ? { target: item.target } : {}),
+    }
+  })
+}
+
+/** autosync interval 类型守卫 */
+function isAutosyncInterval(v: unknown): v is AutosyncInterval {
+  return v === '5m' || v === '15m' || v === '30m' || v === '60m' || v === '6h' || v === '12h' || v === '24h'
+}
+
+/** 自动同步状态响应（GET /sync/autosync 与 POST 回填；读盘计算 elapsedMs）。 */
+async function buildAutosyncStatus(dir: string): Promise<AutosyncStatusResponse> {
+  const cfg = await readAutosyncConfig(dir)
+  const elapsedMs = cfg.lastRunAt === undefined || cfg.lastRunAt === ''
+    ? -1
+    : Math.max(0, Date.now() - Date.parse(cfg.lastRunAt))
+  return {
+    enabled: cfg.enabled,
+    interval: cfg.interval,
+    ...(cfg.lastRunAt !== undefined ? { lastRunAt: cfg.lastRunAt } : {}),
+    ...(cfg.lastRunStatus !== undefined ? { lastRunStatus: cfg.lastRunStatus } : {}),
+    ...(cfg.lastRunMessage !== undefined ? { lastRunMessage: cfg.lastRunMessage } : {}),
+    consecutiveFailures: cfg.consecutiveFailures,
+    elapsedMs,
+    ...(cfg.lastRunHistoryId !== undefined ? { lastRunHistoryId: cfg.lastRunHistoryId } : {}),
+  }
+}
+
+/** GET /sync/autosync 响应类型（与 sync-api.ts AutosyncStatusResponse 对齐） */
+interface AutosyncStatusResponse {
+  enabled: boolean
+  interval: AutosyncInterval
+  lastRunAt?: string
+  lastRunStatus?: AutosyncRunStatus
+  lastRunMessage?: string
+  consecutiveFailures: number
+  elapsedMs: number
+  lastRunHistoryId?: string
+}
+
 /* -------------------------------------------------- restore 路由（M4） */
 
 /** POST /restore 请求体校验（纯函数；snapshotId 拒绝路径分隔符防 join 越界）。 */
@@ -1049,6 +1140,21 @@ function makeRoutes(deps: RoutesDeps): WebRoute[] {
     });
   }
 
+  /** 一键同步差异确认会话存储（进程内存；/sync/sync 预览 → /sync/apply-items 逐项执行解耦） */
+  const syncSessions = new SyncSessionStore()
+
+  /** 自动同步后台调度器（宿主进程生命周期，不依赖浏览器） */
+  let scheduler: AutoSyncScheduler | undefined
+  scheduler = new AutoSyncScheduler({
+    syncDir,
+    host,
+    makeSyncEngine,
+    msg,
+    runs,
+  })
+  // 启动：读 autosync-config；若 enabled 启动定时器；无条件执行一次「启动触发下载合并」（受阈值约束）
+  scheduler.start()
+
   return [
     // ------------------------------------------------------------- status
     {
@@ -1407,6 +1513,7 @@ function makeRoutes(deps: RoutesDeps): WebRoute[] {
             lastSyncAt: state.lastSyncAt === '' ? undefined : state.lastSyncAt,
             sectionCount: Object.keys(state.sections).length,
             transport: state.transport,
+            autosync: await buildAutosyncStatus(syncDir),
           })
         } catch (error) {
           writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
@@ -1627,21 +1734,28 @@ function makeRoutes(deps: RoutesDeps): WebRoute[] {
             } catch { /* skip */ }
           }
           rows.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
-          writeJson(res, 200, rows)
+          // 合并自动同步执行记录（sync-history.json）
+          const hist = await readSyncHistory(syncDir)
+          const merged = [
+            ...rows.map((r) => ({ ...r, kind: 'apply' as const })),
+            ...hist.autosyncEntries.map((e) => ({
+              id: e.createdAt,
+              createdAt: e.createdAt,
+              kind: 'autosync' as const,
+              autosync: e,
+            })),
+          ].sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+          writeJson(res, 200, { entries: merged })
         } catch (error) {
           writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
         }
       },
     },
-    // ------------------------------------------------------ sync/apply
-    // P2：应用自动应用计划。流程：
-    //   1) engine.merge 拉取远端 → 三方合并 → classifyMergePlan(firstSync)
-    //   2) engine.applyMergePlan(apply) → backup + Importer.executeImportPlan(rollbackOnError=true)
-    //      失败 → rollback + enqueueItems → return ApplyReport{ok:false,rolledBack:true,review}
-    //   3) 全成功 → recordBaseline + 标记 firstSyncCompleted
+    // ------------------------------------------------------ sync/snapshots-list
+    // m-sync-v2：远端历史快照列表（供「选择历史快照」下拉）。
     {
       kind: 'exact',
-      path: API.syncApply,
+      path: API.syncSnapshotsList,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
         const body = await readJsonBody(req)
@@ -1652,21 +1766,199 @@ function makeRoutes(deps: RoutesDeps): WebRoute[] {
         try {
           const { repoUrl, gitBin } = await prepareSync(body)
           const engine = makeSyncEngine(repoUrl, gitBin)
-          const merge = await withTimeout(
-            engine.merge(),
+          const metas = await withTimeout(
+            engine.listSnapshots(),
             ROUTE_TIMEOUT_MS,
-            '同步三方合并超时（5 分钟）',
+            msg('host.syncPullTimeout'),
           )
-          // 首次强制预览：sync-state.lastSyncAt === '' 时一律 review
+          const snapshots = [...metas]
+            .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+            .map((m) => ({
+              id: m.id,
+              createdAt: m.createdAt,
+              sectionCount: m.manifest.sectionIds.length,
+              platform: m.manifest.platform,
+              dshVersion: m.manifest.dshVersion,
+            }))
           const state = await loadSyncState(syncDir)
-          const firstSync = state.lastSyncAt === ''
-          const apply = classifyMergePlan(merge, { firstSync })
-          if (firstSync) {
-            state.lastSyncAt = new Date().toISOString()
-            await saveSyncState(syncDir, state)
+          writeJson(res, 200, { ok: true, snapshots, currentSnapshotId: state.lastSnapshotId === '' ? undefined : state.lastSnapshotId })
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/sync
+    // m-sync-v2：一键同步第一步 —— 拉取 → 差异确认会话（内存登记临时 ZIP + ImportPlan）。
+    {
+      kind: 'exact',
+      path: API.syncSync,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const { repoUrl, gitBin } = await prepareSync(body)
+          const engine = makeSyncEngine(repoUrl, gitBin)
+          const snapshotId = typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined
+          const preview = await withTimeout(
+            engine.preview(snapshotId === undefined ? {} : { snapshotId }),
+            ROUTE_TIMEOUT_MS,
+            msg('host.syncPullTimeout'),
+          )
+          if (!preview.ok || preview.plan === null || preview.analysis === null) {
+            writeJson(res, 200, { ok: false, syncSessionId: '', snapshotId: preview.snapshotId, items: [], needsReview: false, compatibility: 'unsupported', message: preview.message ?? '同步预览失败' })
+            return
           }
-          const report = await engine.applyMergePlan(apply)
-          writeJson(res, 200, report)
+          const syncSessionId = syncSessions.set({
+            zipPath: preview.zipPath,
+            plan: preview.plan,
+            analysis: preview.analysis,
+            snapshotId: preview.snapshotId,
+            repoUrl,
+            gitBin,
+          })
+          const items = planToConfirmItems(preview.plan)
+          const needsReview = items.some((i) => REVIEW_KINDS.has(i.kind)) || preview.analysis.pathIssues.length > 0
+          writeJson(res, 200, {
+            ok: true,
+            syncSessionId,
+            snapshotId: preview.snapshotId,
+            items,
+            needsReview,
+            compatibility: preview.analysis.compatibility,
+          })
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/apply-items
+    // m-sync-v2：一键同步第二步 —— 按用户对差异项的逐项决策执行导入。
+    {
+      kind: 'exact',
+      path: API.syncApplyItems,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const syncSessionId = typeof body['syncSessionId'] === 'string' ? body['syncSessionId'] : ''
+          const session = syncSessions.get(syncSessionId)
+          if (session === undefined) {
+            writeJson(res, 400, { error: '同步会话不存在或已过期，请重新拉取预览' })
+            return
+          }
+          const adoptions = Array.isArray(body['adoptions']) ? body['adoptions'] : []
+          // 构造子计划（仅含采纳项）
+          const byId = new Map<string, { adopt: boolean; resolution?: string }>()
+          for (const a of adoptions as Array<Record<string, unknown>>) {
+            if (typeof a?.['itemId'] !== 'string') continue
+            byId.set(a['itemId'], { adopt: a['adopt'] === true, resolution: typeof a['resolution'] === 'string' ? a['resolution'] : undefined })
+          }
+          const subItems = session.plan.items.filter((item) => {
+            const d = byId.get(item.id)
+            if (d === undefined || !d.adopt) return false
+            // Conflict 项必须有 resolution，且 keepLocal/skip 从子计划剔除
+            if (item.kind === 'Conflict') {
+              if (d.resolution === undefined) throw new SyncRouteError(`冲突项 ${item.id} 必须提供 resolution（useRemote/keepLocal/skip）`)
+              if (d.resolution === 'keepLocal' || d.resolution === 'skip') return false
+            }
+            return true
+          })
+          const subPlan: ImportPlan = {
+            ...session.plan,
+            items: subItems,
+          }
+          // 消费会话（同一 session 只允许一次 apply-items）
+          syncSessions.delete(syncSessionId)
+          await fs.rm(dirname(session.zipPath), { recursive: true, force: true }).catch(() => { /* 尽力清理临时 ZIP */ })
+          const engine = makeSyncEngine(session.repoUrl, session.gitBin)
+          const report = await engine.applyItems(session.zipPath, subPlan, {
+            onItem: (info) => { /* 进度可选：runs 已由 applyItems 内部处理 */ },
+          })
+          writeJson(res, 200, {
+            ok: report.ok,
+            applied: report.applied,
+            skipped: subItems.map((i) => i.id),
+            needsRestart: report.needsRestart === true,
+            warnings: report.warnings,
+            restoreId: report.restoreId,
+            rolledBack: report.rolledBack,
+            failed: report.failed,
+            result: report.result,
+          })
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/cancel
+    // m-sync-v2：取消 / 清理差异确认会话（丢弃临时 ZIP，零副作用）。
+    {
+      kind: 'exact',
+      path: API.syncCancel,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const syncSessionId = typeof body['syncSessionId'] === 'string' ? body['syncSessionId'] : ''
+          if (syncSessionId !== '') {
+            const session = syncSessions.get(syncSessionId)
+            if (session !== undefined) {
+              await fs.rm(dirname(session.zipPath), { recursive: true, force: true }).catch(() => { /* 尽力清理临时 ZIP */ })
+            }
+            syncSessions.delete(syncSessionId)
+          }
+          writeJson(res, 200, { ok: true })
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/autosync
+    // m-sync-v2：自动同步配置读写（总开关 + 间隔 + 启动阈值 + 状态）。
+    {
+      kind: 'exact',
+      path: API.syncAutosync,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'GET')) return
+        try {
+          writeJson(res, 200, await buildAutosyncStatus(syncDir))
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API.syncAutosync,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const cfg = await readAutosyncConfig(syncDir)
+          if (typeof body['enabled'] === 'boolean') cfg.enabled = body['enabled']
+          if (typeof body['interval'] === 'string' && isAutosyncInterval(body['interval'])) cfg.interval = body['interval']
+          if (typeof body['startupMinIntervalMs'] === 'number' && Number.isFinite(body['startupMinIntervalMs']) && body['startupMinIntervalMs'] > 0) {
+            cfg.startupMinIntervalMs = body['startupMinIntervalMs']
+          }
+          await writeAutosyncConfig(syncDir, cfg)
+          if (scheduler) scheduler.reload().catch(() => { /* 尽力而为 */ })
+          writeJson(res, 200, await buildAutosyncStatus(syncDir))
         } catch (error) {
           writeSyncRouteError(res, error)
         }

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

@@ -0,0 +1,93 @@
+/**
+ * autosync-config 测试：sync-autosync.json 读写往返、缺省值、损坏 JSON 回退缺省、原子写。
+ */
+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 {
+  readAutosyncConfig, writeAutosyncConfig, AUTOSYNC_CONFIG_FILE,
+  AUTOSYNC_CONFIG_SCHEMA_VERSION, DEFAULT_AUTOSYNC_INTERVAL,
+  DEFAULT_STARTUP_MIN_INTERVAL_MS,
+} from './autosync-config.ts';
+
+test('writeAutosyncConfig + readAutosyncConfig：写入 → 读回字段一致', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-rt-'));
+  try {
+    await writeAutosyncConfig(dir, {
+      enabled: true,
+      interval: '15m',
+      startupMinIntervalMs: 300000,
+      consecutiveFailures: 2,
+      lastRunAt: '2026-08-16T12:00:00.000Z',
+      lastRunStatus: 'skipped',
+      lastRunMessage: '有冲突项，跳过',
+      lastRunHistoryId: 'hist-1',
+    });
+    const cfg = await readAutosyncConfig(dir);
+    assert.equal(cfg.enabled, true);
+    assert.equal(cfg.interval, '15m');
+    assert.equal(cfg.startupMinIntervalMs, 300000);
+    assert.equal(cfg.consecutiveFailures, 2);
+    assert.equal(cfg.lastRunAt, '2026-08-16T12:00:00.000Z');
+    assert.equal(cfg.lastRunStatus, 'skipped');
+    assert.equal(cfg.lastRunMessage, '有冲突项，跳过');
+    assert.equal(cfg.lastRunHistoryId, 'hist-1');
+    // 原始文件校验
+    const raw = JSON.parse(await fs.readFile(path.join(dir, AUTOSYNC_CONFIG_FILE), 'utf8'));
+    assert.equal(raw.schemaVersion, AUTOSYNC_CONFIG_SCHEMA_VERSION);
+    assert.equal(raw.enabled, true);
+    assert.equal(raw.interval, '15m');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readAutosyncConfig：文件不存在 → 返回缺省值', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-default-'));
+  try {
+    const cfg = await readAutosyncConfig(dir);
+    assert.equal(cfg.enabled, false);
+    assert.equal(cfg.interval, DEFAULT_AUTOSYNC_INTERVAL);
+    assert.equal(cfg.startupMinIntervalMs, DEFAULT_STARTUP_MIN_INTERVAL_MS);
+    assert.equal(cfg.consecutiveFailures, 0);
+    assert.equal(cfg.lastRunAt, undefined);
+    assert.equal(cfg.lastRunStatus, undefined);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readAutosyncConfig：损坏 JSON → 回退缺省', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-corrupt-'));
+  try {
+    await fs.writeFile(path.join(dir, AUTOSYNC_CONFIG_FILE), '{not-json', 'utf8');
+    const cfg = await readAutosyncConfig(dir);
+    assert.equal(cfg.enabled, false);
+    assert.equal(cfg.interval, DEFAULT_AUTOSYNC_INTERVAL);
+    assert.equal(cfg.startupMinIntervalMs, DEFAULT_STARTUP_MIN_INTERVAL_MS);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readAutosyncConfig：不支持的 schemaVersion → 回退缺省', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-badver-'));
+  try {
+    await fs.writeFile(path.join(dir, AUTOSYNC_CONFIG_FILE),
+      JSON.stringify({ schemaVersion: 99, enabled: true }), 'utf8');
+    const cfg = await readAutosyncConfig(dir);
+    assert.equal(cfg.enabled, false);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('writeAutosyncConfig：原子写（自动创建目录）', async () => {
+  const base = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-mkdir-'));
+  try {
+    const dir = path.join(base, 'nested', 'sync');
+    await writeAutosyncConfig(dir, { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 });
+    const cfg = await readAutosyncConfig(dir);
+    assert.ok(cfg);
+    assert.equal(cfg.enabled, true);
+    // 确认没有残留临时文件
+    const files = await fs.readdir(dir);
+    assert.ok(files.length >= 1, '应有配置文件');
+    assert.ok(!files.some((f) => f.includes('.tmp')), '不应残留 .tmp 临时文件');
+  } finally { await fs.rm(base, { recursive: true, force: true }); }
+});

package/src/sync/autosync-config.ts

@@ -0,0 +1,137 @@
+/**
+ * m-autosync：自动同步配置持久化（sync-autosync.json）。
+ *
+ * 与 sync-config.json 并列独立文件：语义清楚、schema 演进独立。
+ * schemaVersion:1，字段 { enabled, interval, startupMinIntervalMs, consecutiveFailures,
+ * lastRunAt, lastRunStatus, lastRunMessage, lastRunHistoryId }。
+ *
+ * 原子写（临时文件 + rename），损坏/不支持 schema 回退缺省（enabled=false,
+ * interval='30m', startupMinIntervalMs=5*60*1000）。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
+
+export const AUTOSYNC_CONFIG_FILE = 'sync-autosync.json';
+export const AUTOSYNC_CONFIG_SCHEMA_VERSION = 1;
+
+/** 统一间隔类型 */
+export type AutosyncInterval = '5m' | '15m' | '30m' | '60m' | '6h' | '12h' | '24h';
+
+/** 缺省间隔 */
+export const DEFAULT_AUTOSYNC_INTERVAL: AutosyncInterval = '30m';
+
+/** 缺省启动触发最小间隔阈值（5 分钟，防频繁重启反复同步） */
+export const DEFAULT_STARTUP_MIN_INTERVAL_MS = 5 * 60 * 1000;
+
+/** 最近一次自动同步执行状态 */
+export type AutosyncRunStatus = 'success' | 'skipped' | 'failed' | 'partial';
+
+/** 自动同步配置（持久化面） */
+export interface AutosyncConfig {
+  /** 总开关（同时控制上传 + 下载） */
+  enabled: boolean;
+  /** 统一间隔 */
+  interval: AutosyncInterval;
+  /** 重启触发的「自动下载合并」最小间隔阈值（ms） */
+  startupMinIntervalMs: number;
+  /** 连续失败计数（用于通知判定） */
+  consecutiveFailures: number;
+  /** 最近一次自动同步执行时间（ISO-8601 UTC）；''/undefined = 从未执行 */
+  lastRunAt?: string;
+  /** 最近一次自动同步执行状态 */
+  lastRunStatus?: AutosyncRunStatus;
+  lastRunMessage?: string;
+  /** 最近一次自动同步触发的同步历史条目 id */
+  lastRunHistoryId?: string;
+}
+
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export function defaultAutosyncConfig(): AutosyncConfig {
+  return {
+    enabled: false,
+    interval: DEFAULT_AUTOSYNC_INTERVAL,
+    startupMinIntervalMs: DEFAULT_STARTUP_MIN_INTERVAL_MS,
+    consecutiveFailures: 0,
+  };
+}
+
+/** 读取自动同步配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export async function readAutosyncConfig(dir: string): Promise<AutosyncConfig> {
+  const file = path.join(dir, AUTOSYNC_CONFIG_FILE);
+  let raw: string;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch {
+    return defaultAutosyncConfig();
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseJsonSafe(raw);
+  } catch {
+    return defaultAutosyncConfig();
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return defaultAutosyncConfig();
+  }
+  const obj = parsed as Record<string, unknown>;
+  // schemaVersion 必须为 1（不支持其他版本）
+  if (obj['schemaVersion'] !== undefined && obj['schemaVersion'] !== AUTOSYNC_CONFIG_SCHEMA_VERSION) {
+    return defaultAutosyncConfig();
+  }
+  if (obj['schemaVersion'] === undefined) {
+    return defaultAutosyncConfig();
+  }
+  const cfg = defaultAutosyncConfig();
+  if (typeof obj['enabled'] === 'boolean') cfg.enabled = obj['enabled'];
+  if (isAutosyncInterval(obj['interval'])) cfg.interval = obj['interval'];
+  if (typeof obj['startupMinIntervalMs'] === 'number' && Number.isFinite(obj['startupMinIntervalMs']) && obj['startupMinIntervalMs'] > 0) {
+    cfg.startupMinIntervalMs = obj['startupMinIntervalMs'];
+  }
+  if (typeof obj['consecutiveFailures'] === 'number' && Number.isFinite(obj['consecutiveFailures']) && obj['consecutiveFailures'] >= 0) {
+    cfg.consecutiveFailures = obj['consecutiveFailures'];
+  }
+  if (typeof obj['lastRunAt'] === 'string' && obj['lastRunAt'] !== '') cfg.lastRunAt = obj['lastRunAt'];
+  if (typeof obj['lastRunStatus'] === 'string' && (obj['lastRunStatus'] === 'success' || obj['lastRunStatus'] === 'skipped' || obj['lastRunStatus'] === 'failed' || obj['lastRunStatus'] === 'partial')) {
+    cfg.lastRunStatus = obj['lastRunStatus'];
+  }
+  if (typeof obj['lastRunMessage'] === 'string') cfg.lastRunMessage = obj['lastRunMessage'];
+  if (typeof obj['lastRunHistoryId'] === 'string') cfg.lastRunHistoryId = obj['lastRunHistoryId'];
+  return cfg;
+}
+
+/** 写入自动同步配置（原子写：临时文件 + rename；自动创建目录）。 */
+export async function writeAutosyncConfig(dir: string, cfg: AutosyncConfig): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+  const payload: Record<string, unknown> = {
+    schemaVersion: AUTOSYNC_CONFIG_SCHEMA_VERSION,
+    enabled: cfg.enabled,
+    interval: cfg.interval,
+    startupMinIntervalMs: cfg.startupMinIntervalMs,
+    consecutiveFailures: cfg.consecutiveFailures,
+  };
+  if (cfg.lastRunAt !== undefined && cfg.lastRunAt !== '') payload['lastRunAt'] = cfg.lastRunAt;
+  if (cfg.lastRunStatus !== undefined) payload['lastRunStatus'] = cfg.lastRunStatus;
+  if (cfg.lastRunMessage !== undefined && cfg.lastRunMessage !== '') payload['lastRunMessage'] = cfg.lastRunMessage;
+  if (cfg.lastRunHistoryId !== undefined && cfg.lastRunHistoryId !== '') payload['lastRunHistoryId'] = cfg.lastRunHistoryId;
+
+  const target = path.join(dir, AUTOSYNC_CONFIG_FILE);
+  const tmp = path.join(
+    dir,
+    `.${AUTOSYNC_CONFIG_FILE}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`,
+  );
+  const data = stringifyJsonSafe(payload, { 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;
+  }
+}
+
+function isAutosyncInterval(v: unknown): v is AutosyncInterval {
+  return v === '5m' || v === '15m' || v === '30m' || v === '60m' || v === '6h' || v === '12h' || v === '24h';
+}