dsh-config-manager 0.1.19 → 0.1.21

package/src/sync/merge.ts

@@ -0,0 +1,360 @@
+/**
+ * m-sync-flow：三方合并引擎（纯函数）。
+ *
+ * 输入：local / remote / ancestor 各分区的 SectionData + 分区 hash。
+ * 行为（每分区）：
+ *   - localHash == remoteHash        → skip（无变化）
+ *   - localHash != remoteHash：
+ *     - localHash == ancestorHash    → useRemote（远端独有改动）
+ *     - remoteHash == ancestorHash   → keepLocal（本地独有改动）
+ *     - 其余                          → 进入精细合并：JSON 分区按 top-level key 合并、FilesSection 按 relativePath 合并；
+ *                                       仅双侧均改且值不同的键/文件留为 conflict，其余非重叠变更自动合入。
+ *
+ * 输出：MergePlan（纯数据，不含副作用），由上层（SyncEngine.merge）返回给 UI 决策。
+ *
+ * 安全约束：ancestor 为 undefined 时退化为两方合并：local != remote 视为整分区 conflict（拒绝猜测共同祖先）。
+ */
+import type { FilesSection, SectionData, SectionId } from '../schema/types.ts';
+import { hashSection } from './sync-state.ts';
+
+export type MergeDecision = 'useRemote' | 'keepLocal' | 'skip';
+
+/** 分区内精细合并产生的单条冲突（JSON key 或 FilesSection 单文件）。 */
+export interface MergeConflict {
+  /** 冲突位置：JSON 分区是 top-level key；FilesSection 是 relativePath。 */
+  path: string;
+  kind: 'key' | 'file';
+  local?: unknown;
+  remote?: unknown;
+  ancestor?: unknown;
+}
+
+export interface MergeSectionResult {
+  id: SectionId;
+  /** 分区级决策；'skip' 时无 merged/conflicts；'conflict' 时 merged 为 null（仅 conflicts）。 */
+  decision: MergeDecision | 'conflict';
+  /** 当 decision 为 'useRemote' / 'keepLocal' 时：合并后的整分区数据（= 胜出方原值）。 */
+  merged?: SectionData;
+  /** 仅 decision === 'conflict' 时非空：分区级冲突或精细合并后剩余冲突。 */
+  conflicts: MergeConflict[];
+}
+
+export interface MergePlan {
+  /** 每分区的合并结果；仅含 local/remote/ancestor 三者任一出现的分区。 */
+  sections: MergeSectionResult[];
+}
+
+/** 内部：三态分区 hash（缺则为 undefined）。 */
+interface TripleHashes {
+  local?: string;
+  remote?: string;
+  ancestor?: string;
+}
+
+/** 收集 local/remote/ancestor 三个快照中出现过的所有分区 id。 */
+function unionSectionIds(
+  local: Record<string, SectionData>,
+  remote: Record<string, SectionData>,
+  ancestor: Record<string, SectionData> | undefined,
+): SectionId[] {
+  const ids = new Set<SectionId>();
+  for (const id of Object.keys(local)) ids.add(id as SectionId);
+  for (const id of Object.keys(remote)) ids.add(id as SectionId);
+  if (ancestor) for (const id of Object.keys(ancestor)) ids.add(id as SectionId);
+  return [...ids];
+}
+
+function computeHashes(
+  local: Record<string, SectionData>,
+  remote: Record<string, SectionData>,
+  ancestor: Record<string, SectionData> | undefined,
+  ids: SectionId[],
+): Map<SectionId, TripleHashes> {
+  const m = new Map<SectionId, TripleHashes>();
+  for (const id of ids) {
+    const lh = local[id] !== undefined ? hashSection(local[id]) : undefined;
+    const rh = remote[id] !== undefined ? hashSection(remote[id]) : undefined;
+    const ah = ancestor && ancestor[id] !== undefined ? hashSection(ancestor[id]) : undefined;
+    m.set(id, { local: lh, remote: rh, ancestor: ah });
+  }
+  return m;
+}
+
+/** 顶层 JSON 分区对象：键序无关判等（深度递归，深层数组也判等）。 */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== 'object') return a === b;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const aa = a as unknown[];
+    const bb = b as unknown[];
+    if (aa.length !== bb.length) return false;
+    for (let i = 0; i < aa.length; i++) if (!deepEqual(aa[i], bb[i])) return false;
+    return true;
+  }
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const ak = Object.keys(ao).sort();
+  const bk = Object.keys(bo).sort();
+  if (ak.length !== bk.length) return false;
+  for (let i = 0; i < ak.length; i++) if (ak[i] !== bk[i]) return false;
+  for (const k of ak) if (!deepEqual(ao[k], bo[k])) return false;
+  return true;
+}
+
+/** JSON 分区精细合并：按 top-level key 走三方合并。
+ *  - 双侧均未改 → 跳过
+ *  - 仅一侧改   → 采纳该侧
+ *  - 双侧均改   → 若 deepEqual 自动合并；否则留为冲突 */
+function mergeJsonSectionGranular(
+  local: Record<string, unknown>,
+  remote: Record<string, unknown>,
+  ancestor: Record<string, unknown> | undefined,
+): { merged: Record<string, unknown>; conflicts: MergeConflict[] } {
+  const merged: Record<string, unknown> = {};
+  const conflicts: MergeConflict[] = [];
+  const keys = new Set<string>([...Object.keys(local), ...Object.keys(remote), ...(ancestor ? Object.keys(ancestor) : [])]);
+  for (const k of keys) {
+    const lHas = Object.prototype.hasOwnProperty.call(local, k);
+    const rHas = Object.prototype.hasOwnProperty.call(remote, k);
+    const aHas = ancestor ? Object.prototype.hasOwnProperty.call(ancestor, k) : false;
+    const lv = lHas ? local[k] : undefined;
+    const rv = rHas ? remote[k] : undefined;
+    const av = aHas ? ancestor![k] : undefined;
+    if (lHas && rHas) {
+      if (deepEqual(lv, rv)) {
+        merged[k] = lv;
+        continue;
+      }
+      // 双侧都有该 key 但值不同 → 看是否都改过
+      const lChanged = !aHas || !deepEqual(lv, av);
+      const rChanged = !aHas || !deepEqual(rv, av);
+      if (lChanged && rChanged) {
+        if (deepEqual(lv, rv)) {
+          merged[k] = lv; // 两侧改后恰好相同
+        } else {
+          conflicts.push({ path: k, kind: 'key', local: lv, remote: rv, ancestor: av });
+        }
+      } else if (lChanged) {
+        merged[k] = lv;
+      } else if (rChanged) {
+        merged[k] = rv;
+      } else {
+        merged[k] = lv; // 双侧都未相对祖先改但 deepEqual 已失败——保持一致
+      }
+    } else if (lHas && !rHas) {
+      // 仅本地有：删/改/增？
+      const lChanged = !aHas || !deepEqual(lv, av);
+      if (lChanged) {
+        // 本地增/改，远程删 → 冲突
+        conflicts.push({ path: k, kind: 'key', local: lv, remote: undefined, ancestor: av });
+      } else {
+        // 本地等于祖先、远程缺：远程删 → 跟随删除
+      }
+    } else if (!lHas && rHas) {
+      const rChanged = !aHas || !deepEqual(rv, av);
+      if (rChanged) {
+        // 本地删、远程增 → 冲突
+        conflicts.push({ path: k, kind: 'key', local: undefined, remote: rv, ancestor: av });
+      } else {
+        // 远程等于祖先、本地缺：本地删 → 跟随删除
+      }
+    } else {
+      // 仅祖先有：双侧都删 → 跟随删除
+    }
+  }
+  return { merged, conflicts };
+}
+
+/** FilesSection 精细合并：按 relativePath 走三方合并（按文件字节 deepEqual）。 */
+function mergeFilesSectionGranular(
+  local: FilesSection,
+  remote: FilesSection,
+  ancestor: FilesSection | undefined,
+): { merged: FilesSection; conflicts: MergeConflict[] } {
+  const lMap = new Map<string, Uint8Array>();
+  for (const f of local.files) lMap.set(f.relativePath, f.data);
+  const rMap = new Map<string, Uint8Array>();
+  for (const f of remote.files) rMap.set(f.relativePath, f.data);
+  const aMap = new Map<string, Uint8Array>();
+  if (ancestor) for (const f of ancestor.files) aMap.set(f.relativePath, f.data);
+
+  const paths = new Set<string>([...lMap.keys(), ...rMap.keys(), ...aMap.keys()]);
+  const mergedFiles: FilesSection['files'] = [];
+  const conflicts: MergeConflict[] = [];
+  for (const p of paths) {
+    const l = lMap.get(p);
+    const r = rMap.get(p);
+    const a = aMap.get(p);
+    const eq = (x: Uint8Array | undefined, y: Uint8Array | undefined) => {
+      if (x === undefined || y === undefined) return x === y;
+      if (x.length !== y.length) return false;
+      for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return false;
+      return true;
+    };
+    if (l && r) {
+      if (eq(l, r)) {
+        mergedFiles.push({ relativePath: p, data: l, contentHash: '' });
+        continue;
+      }
+      const lChanged = !a || !eq(l, a);
+      const rChanged = !a || !eq(r, a);
+      if (lChanged && rChanged) {
+        conflicts.push({ path: p, kind: 'file', local: l, remote: r, ancestor: a });
+      } else if (lChanged) {
+        mergedFiles.push({ relativePath: p, data: l, contentHash: '' });
+      } else if (rChanged) {
+        mergedFiles.push({ relativePath: p, data: r, contentHash: '' });
+      } else {
+        mergedFiles.push({ relativePath: p, data: l, contentHash: '' });
+      }
+    } else if (l && !r) {
+      const aExists = a !== undefined;
+      const lChanged = aExists ? !eq(l, a) : true;
+      if (lChanged) {
+        if (!aExists) {
+          // 纯本地新增（祖先里也没有）→ keepLocal
+          mergedFiles.push({ relativePath: p, data: l, contentHash: '' });
+        } else {
+          // 本地改/增 vs 远程删 → 冲突
+          conflicts.push({ path: p, kind: 'file', local: l, remote: undefined, ancestor: a });
+        }
+      }
+    } else if (!l && r) {
+      const aExists = a !== undefined;
+      const rChanged = aExists ? !eq(r, a) : true;
+      if (rChanged) {
+        if (!aExists) {
+          // 纯远程新增（祖先里也没有）→ useRemote
+          mergedFiles.push({ relativePath: p, data: r, contentHash: '' });
+        } else {
+          // 本地删 vs 远程改/增 → 冲突
+          conflicts.push({ path: p, kind: 'file', local: undefined, remote: r, ancestor: a });
+        }
+      }
+    }
+  }
+  return { merged: { version: 1, files: mergedFiles }, conflicts };
+}
+
+/** 识别 JSON 分区的「键级合并」键值映射（如 settings/ui 的 namespaces、providers 的 providers）。
+ * 返回 undefined → 该分区无法做键级合并，调用方应退化为整分区冲突。 */
+function keyMapOf(data: SectionData): Record<string, unknown> | undefined {
+  const obj = data as unknown as Record<string, unknown>;
+  if (obj && typeof obj === 'object' && obj['version'] === 1) {
+    const ns = obj['namespaces'];
+    if (ns && typeof ns === 'object' && !Array.isArray(ns)) return ns as Record<string, unknown>;
+    const prov = obj['providers'];
+    if (prov && typeof prov === 'object' && !Array.isArray(prov)) return prov as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+/** 主入口：三方合并。纯函数，无副作用。 */
+export function merge(
+  local: Partial<Record<SectionId, SectionData>>,
+  remote: Partial<Record<SectionId, SectionData>>,
+  ancestor?: Partial<Record<SectionId, SectionData>>,
+): MergePlan {
+  const l = local as Record<string, SectionData>;
+  const r = remote as Record<string, SectionData>;
+  const a = ancestor as Record<string, SectionData> | undefined;
+  const ids = unionSectionIds(l, r, a);
+  const hashes = computeHashes(l, r, a, ids);
+  const results: MergeSectionResult[] = [];
+
+  for (const id of ids) {
+    const h = hashes.get(id)!;
+    const lData = l[id];
+    const rData = r[id];
+    const aData = a ? a[id] : undefined;
+
+    // 远端无 → skip（不在本轮考虑；本地有但远端没有 = 远端"删了"，视作 useRemote=删除）
+    // 本实现按远端视角：远端缺 + 本地存在 + 本地未改祖先 → skip(无变化)；否则冲突。
+    if (rData === undefined && lData !== undefined) {
+      const lChanged = h.ancestor === undefined || h.local !== h.ancestor;
+      if (!lChanged) {
+        results.push({ id, decision: 'skip', conflicts: [] });
+        continue;
+      }
+      results.push({ id, decision: 'conflict', conflicts: [{ path: '$', kind: 'key', local: lData, remote: undefined, ancestor: aData }] });
+      continue;
+    }
+    // 本地无、远端有：远端新增；本地删除过（=等于祖先空）+祖先空→skip；否则按 useRemote。
+    if (lData === undefined && rData !== undefined) {
+      const rChanged = h.ancestor === undefined || h.remote !== h.ancestor;
+      if (!rChanged) {
+        results.push({ id, decision: 'skip', conflicts: [] });
+        continue;
+      }
+      results.push({ id, decision: 'useRemote', merged: rData, conflicts: [] });
+      continue;
+    }
+    // 双方都没有 → skip
+    if (lData === undefined && rData === undefined) {
+      results.push({ id, decision: 'skip', conflicts: [] });
+      continue;
+    }
+    // 双方都有
+    if (h.local === h.remote) {
+      results.push({ id, decision: 'skip', conflicts: [] });
+      continue;
+    }
+    if (h.ancestor === undefined) {
+      // 无祖先 → 两方差异视为整分区冲突（不猜测）
+      results.push({ id, decision: 'conflict', conflicts: [{ path: '$', kind: 'key', local: lData, remote: rData, ancestor: undefined }] });
+      continue;
+    }
+    if (h.local === h.ancestor) {
+      results.push({ id, decision: 'useRemote', merged: rData, conflicts: [] });
+      continue;
+    }
+    if (h.remote === h.ancestor) {
+      results.push({ id, decision: 'keepLocal', merged: lData, conflicts: [] });
+      continue;
+    }
+    // 双侧相对祖先都改 → 进入精细合并
+    if (isFilesSectionData(lData as SectionData)) {
+      const { merged, conflicts } = mergeFilesSectionGranular(lData as FilesSection, rData as FilesSection, aData as FilesSection | undefined);
+      if (conflicts.length === 0) {
+        results.push({ id, decision: 'useRemote', merged: merged as SectionData, conflicts: [] });
+      } else {
+        results.push({ id, decision: 'conflict', conflicts, merged: undefined });
+      }
+      continue;
+    }
+    // JSON 分区：识别可键级合并的子映射（namespaces / providers）
+    const lKeyMap = keyMapOf(lData as unknown as SectionData);
+    const rKeyMap = keyMapOf(rData as unknown as SectionData);
+    const aKeyMap = aData ? keyMapOf(aData as unknown as SectionData) : undefined;
+    if (lKeyMap && rKeyMap) {
+      const { merged: mergedKeys, conflicts } = mergeJsonSectionGranular(lKeyMap, rKeyMap, aKeyMap);
+      // 重组 SectionData：用 l/r 中较新者保留非键级合并字段（version 等），键级合并字段用 mergedKeys
+      const lObj = lData as unknown as Record<string, unknown>;
+      const rObj = rData as unknown as Record<string, unknown>;
+      const base: Record<string, unknown> = { ...lObj, ...rObj };
+      // 找到键级合并字段在 base 中的键名
+      const keyFieldName = lKeyMap === lObj['namespaces'] ? 'namespaces'
+        : lKeyMap === lObj['providers'] ? 'providers' : undefined;
+      if (keyFieldName) base[keyFieldName] = mergedKeys;
+      if (conflicts.length === 0) {
+        results.push({ id, decision: 'useRemote', merged: base as unknown as SectionData, conflicts: [] });
+      } else {
+        results.push({ id, decision: 'conflict', conflicts, merged: undefined });
+      }
+      continue;
+    }
+    // 非键级合并 JSON 分区（plugins/mcp/prompts/workspaces 等）：退化为整分区冲突
+    results.push({ id, decision: 'conflict', conflicts: [{ path: '$', kind: 'key', local: lData, remote: rData, ancestor: aData }] });
+  }
+  return { sections: results };
+}
+
+/** 分区是否为文件类（FilesSection）—— 鸭子类型，复用 sync-state 的判定以保持一致。 */
+function isFilesSectionData(data: SectionData): data is FilesSection {
+  if (data === null || typeof data !== 'object') return false;
+  const obj = data as { version?: unknown; files?: unknown };
+  return obj.version === 1 && Array.isArray(obj.files);
+}

package/src/sync/review-queue.test.ts

@@ -0,0 +1,120 @@
+/**
+ * m-sync-flow：待审队列持久化测试。
+ * - readReviewQueue：文件不存在 → 空；损坏 → 抛错。
+ * - writeReviewQueue + readReviewQueue：往返一致；原子重命名。
+ * - enqueueItems：去重（同 id 不重复）；resolveItem：找到 → 设置 decision/decidedAt；找不到抛错。
+ * - 并发写两次：均成功；最终内容是后写者（原子 rename 保证）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  enqueueItems, readReviewQueue, resolveItem, REVIEW_QUEUE_FILE, tmpStateDir,
+  writeReviewQueue, EMPTY_REVIEW_QUEUE,
+} from './review-queue.ts';
+
+test('readReviewQueue：文件不存在 → 返回空队列', async () => {
+  const dir = await tmpStateDir('dsh-rq-empty-');
+  try {
+    const q = await readReviewQueue(dir);
+    assert.deepEqual(q.items, []);
+    assert.equal(q.updatedAt, '');
+  } finally { await fsRm(dir); }
+});
+
+test('writeReviewQueue + readReviewQueue：往返一致', async () => {
+  const dir = await tmpStateDir('dsh-rq-rt-');
+  try {
+    const queue = {
+      items: [{
+        id: 'a1',
+        sectionId: 'settings',
+        kind: 'key' as const,
+        description: 'general.theme conflict',
+        local: { theme: 'dark' },
+        remote: { theme: 'light' },
+        ancestor: { theme: 'dark' },
+      }],
+      updatedAt: '2026-08-17T00:00:00.000Z',
+    };
+    await writeReviewQueue(dir, queue);
+    const loaded = await readReviewQueue(dir);
+    assert.deepEqual(loaded, queue);
+    assert.ok(pathExists(path.join(dir, REVIEW_QUEUE_FILE)));
+  } finally { await fsRm(dir); }
+});
+
+test('readReviewQueue：损坏 JSON → 抛错（不静默降级）', async () => {
+  const dir = await tmpStateDir('dsh-rq-bad-');
+  try {
+    await writeText(path.join(dir, REVIEW_QUEUE_FILE), '{not-json');
+    await assert.rejects(() => readReviewQueue(dir), /JSON|损坏/);
+  } finally { await fsRm(dir); }
+});
+
+test('enqueueItems：追加新项；同 id 视为重复，不重复入队', async () => {
+  const dir = await tmpStateDir('dsh-rq-enq-');
+  try {
+    const item = {
+      sectionId: 'settings',
+      kind: 'key' as const,
+      description: 'general.theme conflict',
+      local: { theme: 'dark' },
+      remote: { theme: 'light' },
+    };
+    await enqueueItems(dir, [item, item, item]);
+    const q = await readReviewQueue(dir);
+    assert.equal(q.items.length, 1, '三次追加同 id → 仅入队一次');
+    assert.equal(q.items[0]!.sectionId, 'settings');
+    assert.equal(q.items[0]!.kind, 'key');
+    assert.ok(typeof q.items[0]!.id === 'string' && q.items[0]!.id.length === 16);
+  } finally { await fsRm(dir); }
+});
+
+test('resolveItem：找到 → 设置 decision/decidedAt；找不到抛错', async () => {
+  const dir = await tmpStateDir('dsh-rq-res-');
+  try {
+    await enqueueItems(dir, [{
+      sectionId: 'providers',
+      kind: 'key' as const,
+      description: 'openai.route conflict',
+      local: { route: 'a' },
+      remote: { route: 'b' },
+    }]);
+    const before = await readReviewQueue(dir);
+    const id = before.items[0]!.id;
+    await resolveItem(dir, id, 'useRemote');
+    const after = await readReviewQueue(dir);
+    assert.equal(after.items[0]!.decision, 'useRemote');
+    assert.ok(after.items[0]!.decidedAt && after.items[0]!.decidedAt.startsWith('2026-'));
+    await assert.rejects(() => resolveItem(dir, 'nonexistent', 'skip'), /未找到/);
+  } finally { await fsRm(dir); }
+});
+
+test('writeReviewQueue：原子提交（不残留临时文件；并发写两次均成功）', async () => {
+  const dir = await tmpStateDir('dsh-rq-atomic-');
+  try {
+    await writeReviewQueue(dir, { items: [{ id: 'a', sectionId: 's', kind: 'key', description: 'd' }], updatedAt: 't1' });
+    await writeReviewQueue(dir, { items: [{ id: 'b', sectionId: 's', kind: 'key', description: 'd' }], updatedAt: 't2' });
+    const final = await readReviewQueue(dir);
+    assert.equal(final.updatedAt, 't2', '后写者赢');
+    assert.equal(final.items[0]!.id, 'b');
+    // 无 .tmp 残留
+    const entries = await fsReaddir(dir);
+    assert.ok(!entries.some((n) => n.endsWith('.tmp')), '无 .tmp 残留');
+  } finally { await fsRm(dir); }
+});
+
+// —— 私有 fs 辅助（避免顶部 import 污染） ——
+const { promises: fsp } = await import('node:fs');
+async function fsRm(p: string): Promise<void> { await fsp.rm(p, { recursive: true, force: true }); }
+async function pathExists(p: string): Promise<boolean> {
+  try { await fsp.stat(p); return true; } catch { return false; }
+}
+async function writeText(p: string, s: string): Promise<void> { await fsp.writeFile(p, s, 'utf8'); }
+async function fsReaddir(p: string): Promise<string[]> { return await fsp.readdir(p); }
+
+void EMPTY_REVIEW_QUEUE;
+void os;

package/src/sync/review-queue.ts

@@ -0,0 +1,167 @@
+/**
+ * m-sync-flow：待审队列持久化（独立文件 sync-review-queue.json）。
+ *
+ * 与 sync-state.json 分文件存放：sync-state 是机器可读同步元数据，
+ * 待审队列是用户可见/可决策的工作队列；混在一起会让同步引擎误读。
+ *
+ * 设计：
+ *  - 只存差异摘要（items 数组），不存全量 payload——避免双写；
+ *    UI 需要完整数据时回拉远端或复用运行时 MergePlan。
+ *  - 写入用 writeFile + rename 原子提交：半成品文件不会污染读侧。
+ *  - 损坏 JSON 严格拒绝（不静默降级到空队列）。
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
+
+export const REVIEW_QUEUE_FILE = 'sync-review-queue.json';
+
+/** 单条待审项（决策前 description/local/remote/ancestor 必填；decision 可选） */
+export interface ReviewQueueItem {
+  id: string;
+  /** 分区 id（settings / providers / workspaces / plugins / mcp 等） */
+  sectionId: string;
+  /** 'key' | 'file' | 'section'：冲突粒度（来自 MergeConflict.kind 或整分区冲突） */
+  kind: 'key' | 'file' | 'section';
+  description: string;
+  local?: unknown;
+  remote?: unknown;
+  ancestor?: unknown;
+  /** 用户决策（resolve 后写入） */
+  decision?: 'useRemote' | 'keepLocal' | 'skip';
+  decidedAt?: string;
+  /** 关联的远端快照 id（追溯来源） */
+  snapshotId?: string;
+}
+
+export interface ReviewQueue {
+  items: ReviewQueueItem[];
+  updatedAt: string;
+}
+
+export const EMPTY_REVIEW_QUEUE: ReviewQueue = { items: [], updatedAt: '' };
+
+/** 读取待审队列；文件不存在 → 返回空队列；损坏 JSON 抛错。 */
+export async function readReviewQueue(
+  stateDir: string,
+  fsx: Pick<typeof fs, 'readFile' | 'writeFile' | 'rename' | 'stat' | 'mkdir'> = fs,
+): Promise<ReviewQueue> {
+  const file = path.join(stateDir, REVIEW_QUEUE_FILE);
+  try {
+    const raw = await fsx.readFile(file, 'utf8');
+    const parsed = parseJsonSafe(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('sync-review-queue.json 损坏：必须是对象');
+    }
+    const obj = parsed as Record<string, unknown>;
+    if (!Array.isArray(obj['items'])) {
+      throw new Error('sync-review-queue.json 损坏：items 必须是数组');
+    }
+    const items: ReviewQueueItem[] = [];
+    for (const it of obj['items']) {
+      if (it === null || typeof it !== 'object' || Array.isArray(it)) {
+        throw new Error('sync-review-queue.json 损坏：每个 item 必须是对象');
+      }
+      const i = it as Record<string, unknown>;
+      if (typeof i['id'] !== 'string' || typeof i['sectionId'] !== 'string'
+        || typeof i['kind'] !== 'string' || typeof i['description'] !== 'string') {
+        throw new Error('sync-review-queue.json 损坏：item 必须含字符串 id/sectionId/kind/description');
+      }
+      items.push(i as unknown as ReviewQueueItem);
+    }
+    return {
+      items,
+      updatedAt: typeof obj['updatedAt'] === 'string' ? obj['updatedAt'] : '',
+    };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { ...EMPTY_REVIEW_QUEUE };
+    throw err;
+  }
+}
+
+/**
+ * 原子写入：先写临时文件 + rename 到目标文件（POSIX/Windows 均支持 rename 原子替换）。
+ * 同一 stateDir 下并发调用不会产生半成品文件（写完临时再 rename）。
+ */
+export async function writeReviewQueue(
+  stateDir: string,
+  queue: ReviewQueue,
+  fsx: Pick<typeof fs, 'readFile' | 'writeFile' | 'rename' | 'stat' | 'mkdir'> = fs,
+): Promise<void> {
+  await fsx.mkdir(stateDir, { recursive: true });
+  const target = path.join(stateDir, REVIEW_QUEUE_FILE);
+  const tmp = path.join(
+    stateDir,
+    `.${REVIEW_QUEUE_FILE}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`,
+  );
+  const data = stringifyJsonSafe(queue, { space: 2 });
+  try {
+    await fsx.writeFile(tmp, data, 'utf8');
+    await fsx.rename(tmp, target);
+  } catch (err) {
+    // 清理可能残留的临时文件
+    try { await fsx.stat(tmp); await fsx.rename(tmp, target); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/** 生成稳定 id（基于内容的 hex；同 description → 同 id，便于去重） */
+function hashItemId(sectionId: string, kind: string, description: string, path?: string): string {
+  const h = crypto.createHash('sha256');
+  h.update(`${sectionId}\u0000${kind}\u0000${path ?? ''}\u0000${description}`);
+  return h.digest('hex').slice(0, 16);
+}
+
+/** 把多 item 追加到队列（同 id 视为同一项，不重复追加） */
+export async function enqueueItems(
+  stateDir: string,
+  items: Omit<ReviewQueueItem, 'id' | 'decidedAt' | 'decision'>[],
+  now: () => Date = () => new Date(),
+  fsx: Pick<typeof fs, 'readFile' | 'writeFile' | 'rename' | 'stat' | 'mkdir'> = fs,
+): Promise<ReviewQueue> {
+  const current = await readReviewQueue(stateDir, fsx);
+  const seen = new Set(current.items.map((i) => i.id));
+  for (const it of items) {
+    const id = hashItemId(it.sectionId, it.kind, it.description);
+    if (seen.has(id)) continue;
+    current.items.push({ ...it, id });
+    seen.add(id);
+  }
+  current.updatedAt = now().toISOString();
+  await writeReviewQueue(stateDir, current, fsx);
+  return current;
+}
+
+/** 把整组合并后的 autoApply 项（失败回滚后）入队 */
+export async function enqueueAutoAppliedOnFailure(
+  stateDir: string,
+  items: Omit<ReviewQueueItem, 'id' | 'decidedAt' | 'decision'>[],
+  fsx: Pick<typeof fs, 'readFile' | 'writeFile' | 'rename' | 'stat' | 'mkdir'> = fs,
+): Promise<ReviewQueue> {
+  return enqueueItems(stateDir, items, undefined, fsx);
+}
+
+/** 用户对某条 item 做了决策（keepLocal / useRemote / skip）；未找到抛错。 */
+export async function resolveItem(
+  stateDir: string,
+  itemId: string,
+  decision: 'useRemote' | 'keepLocal' | 'skip',
+  now: () => Date = () => new Date(),
+  fsx: Pick<typeof fs, 'readFile' | 'writeFile' | 'rename' | 'stat' | 'mkdir'> = fs,
+): Promise<ReviewQueue> {
+  const current = await readReviewQueue(stateDir, fsx);
+  const idx = current.items.findIndex((i) => i.id === itemId);
+  if (idx === -1) throw new Error(`resolveItem: 未找到 itemId ${itemId}`);
+  current.items[idx] = { ...current.items[idx]!, decision, decidedAt: now().toISOString() };
+  current.updatedAt = now().toISOString();
+  await writeReviewQueue(stateDir, current, fsx);
+  return current;
+}
+
+/** 工具：在临时目录构造 stateDir 的便捷工厂（测试用） */
+export function tmpStateDir(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}