@logictan/dsh-config-manager 0.1.60

package/src/sync/layout.test.ts

@@ -0,0 +1,270 @@
+/**
+ * m-sync-transport：散文件目录布局测试。
+ * - writeSnapshotToDir / readSnapshotFromDir 往返（JSON 分区平铺 + 文件类分区目录）
+ * - manifest.json 内容正确性
+ * - 安全：路径穿越拒绝、不支持分区拒绝、缺 manifest 拒绝、缺文件拒绝
+ * - 注入验证：内存 SnapshotFs 驱动同一逻辑
+ */
+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 { readSnapshotFromDir, writeSnapshotToDir, SNAPSHOT_KEEP_CONTENT, SNAPSHOT_KEEP_FILE, SNAPSHOT_MANIFEST_FILE, isSafeRelPath, listSnapshotFiles } from './layout.ts';
+import { createSnapshotFs } from './fs.ts';
+import { hashSection } from './sync-state.ts';
+import type { SnapshotFs } from './fs.ts';
+import type { SectionData, SectionId } from '../schema/types.ts';
+import type { SyncSnapshot } from './transport.ts';
+
+/** 测试用「明文快照」类型：sections 恒为普通分区 Record（layout 测试不涉及加密载荷）。 */
+type PlainSnapshot = SyncSnapshot & { sections: Record<string, SectionData> };
+
+function sampleSnapshot(): PlainSnapshot {
+  return {
+    id: 'snap-001',
+    createdAt: '2026-08-16T12:00:00.000Z',
+    manifest: {
+      schemaVersion: 1,
+      dshVersion: '1.2.3',
+      platform: 'win32',
+      sectionIds: ['settings', 'providers', 'skills', 'pluginFiles'],
+      containsSecrets: false,
+    },
+    sections: {
+      settings: { version: 1, namespaces: { general: { value: { theme: 'dark' }, revision: 1, secrets: [] } } },
+      providers: { version: 1, providers: { deepseek: { route: '/v1' } } },
+      skills: {
+        version: 1,
+        files: [
+          { relativePath: 'coding.md', data: new TextEncoder().encode('# Coding\n'), contentHash: 'x' },
+          { relativePath: 'nested/tool.md', data: new TextEncoder().encode('# Tool\n'), contentHash: 'y' },
+        ],
+      },
+      pluginFiles: { version: 1, files: [{ relativePath: 'dsh-ssh/main.js', data: new TextEncoder().encode('module.exports = 1\n'), contentHash: 'z' }] },
+    },
+  };
+}
+
+function assertBytesEqual(actual: Uint8Array, expected: Uint8Array, msg?: string) {
+  assert.equal(Buffer.from(actual).equals(Buffer.from(expected)), true, msg ?? `字节不一致: ${Buffer.from(expected).toString('utf8')}`);
+}
+
+test('isSafeRelPath: 拒绝穿越/绝对路径/反斜杠，接受常规相对路径', () => {
+  assert.equal(isSafeRelPath('a/b/c.md'), true);
+  assert.equal(isSafeRelPath('编码.md'), true);
+  assert.equal(isSafeRelPath('../evil.md'), false);
+  assert.equal(isSafeRelPath('a/../../evil.md'), false);
+  assert.equal(isSafeRelPath('/abs/path.md'), false);
+  assert.equal(isSafeRelPath('C:\\evil.md'), false);
+  assert.equal(isSafeRelPath('a\\b.md'), false);
+  assert.equal(isSafeRelPath(''), false);
+  assert.equal(isSafeRelPath('.'), false);
+});
+
+test('writeSnapshotToDir + readSnapshotFromDir: 完整往返（JSON 平铺 + 文件目录）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-'));
+  try {
+    const snap = sampleSnapshot();
+    const manifest = await writeSnapshotToDir(snap, tmp);
+
+    // 布局：manifest.json + config/settings.json + ai/providers.json + custom/skills/… + plugin-files/…
+    assert.equal(manifest.id, snap.id);
+    assert.ok((await fs.stat(path.join(tmp, SNAPSHOT_MANIFEST_FILE))).isFile());
+    assert.ok((await fs.stat(path.join(tmp, 'config', 'settings.json'))).isFile());
+    assert.ok((await fs.stat(path.join(tmp, 'ai', 'providers.json'))).isFile());
+    assert.equal((await fs.readFile(path.join(tmp, 'custom', 'skills', 'coding.md'), 'utf8')), '# Coding\n');
+    assert.equal((await fs.readFile(path.join(tmp, 'custom', 'skills', 'nested', 'tool.md'), 'utf8')), '# Tool\n');
+    assert.equal((await fs.readFile(path.join(tmp, 'plugin-files', 'dsh-ssh', 'main.js'), 'utf8')), 'module.exports = 1\n');
+
+    const back = (await readSnapshotFromDir(tmp)) as unknown as PlainSnapshot;
+    assert.equal(back.id, snap.id);
+    assert.equal(back.createdAt, snap.createdAt);
+    assert.deepEqual(back.manifest, snap.manifest);
+    assert.deepEqual(back.sections['settings'], snap.sections['settings']);
+    assert.deepEqual(back.sections['providers'], snap.sections['providers']);
+    const skills = back.sections['skills'] as { files: { relativePath: string; data: Uint8Array; contentHash: string }[] };
+    const skillsOrig = snap.sections['skills'] as { files: { relativePath: string; data: Uint8Array; contentHash: string }[] };
+    assert.equal(skills.files.length, 2);
+    assert.deepEqual(skills.files.map((f) => f.relativePath).sort(), ['coding.md', 'nested/tool.md']);
+    assertBytesEqual(skills.files.find((f) => f.relativePath === 'coding.md')!.data, skillsOrig.files[0]!.data);
+    // 读回内容 hash 与写入时 manifest 记录一致（完整性自洽）
+    assert.equal(hashSection(back.sections['skills']!), manifest.sectionHashes['skills']);
+    assert.equal(hashSection(back.sections['settings']!), manifest.sectionHashes['settings']);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('writeSnapshotToDir: manifest.sectionHashes 覆盖全部包含分区', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-hash-'));
+  try {
+    const snap = sampleSnapshot();
+    const manifest = await writeSnapshotToDir(snap, tmp);
+    assert.deepEqual(Object.keys(manifest.sectionHashes).sort(), ['pluginFiles', 'providers', 'settings', 'skills']);
+    for (const [id, data] of Object.entries(snap.sections)) {
+      assert.equal(manifest.sectionHashes[id as SectionId], hashSection(data));
+    }
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('writeSnapshotToDir: 空文件类分区也保留（目录存在 → 读回含空 files）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-empty-'));
+  try {
+    const snap = sampleSnapshot();
+    snap.sections['skills'] = { version: 1, files: [] };
+    await writeSnapshotToDir(snap, tmp);
+    const back = (await readSnapshotFromDir(tmp)) as unknown as PlainSnapshot;
+    assert.deepEqual(back.sections['skills'], { version: 1, files: [] });
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('writeSnapshotToDir: 拒绝路径穿越的文件相对路径', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-evil-'));
+  try {
+    const snap = sampleSnapshot();
+    snap.sections['skills'] = { version: 1, files: [{ relativePath: '../../evil.md', data: new TextEncoder().encode('x'), contentHash: '' }] };
+    await assert.rejects(() => writeSnapshotToDir(snap, tmp), /非法路径|relativePath|路径/);
+    // 绝对路径同样拒绝
+    snap.sections['skills'] = { version: 1, files: [{ relativePath: 'C:\\evil.md', data: new TextEncoder().encode('x'), contentHash: '' }] };
+    await assert.rejects(() => writeSnapshotToDir(snap, tmp));
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('writeSnapshotToDir: 拒绝布局不支持的子分区（如 secrets）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-nosec-'));
+  try {
+    const snap = sampleSnapshot();
+    (snap.sections as Record<string, unknown>)['secrets'] = { version: 1, values: [] };
+    await assert.rejects(() => writeSnapshotToDir(snap, tmp), /不支持|secrets|布局/);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('readSnapshotFromDir: 目录缺 manifest.json → 拒绝', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-nomani-'));
+  try {
+    await assert.rejects(() => readSnapshotFromDir(tmp), /manifest/);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('readSnapshotFromDir: manifest 声明了分区但文件缺失 → 拒绝（不静默降级）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-missing-'));
+  try {
+    await writeSnapshotToDir(sampleSnapshot(), tmp);
+    await fs.rm(path.join(tmp, 'config', 'settings.json'));
+    await assert.rejects(() => readSnapshotFromDir(tmp), /settings/);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('readSnapshotFromDir: 过滤 git 占位文件（名+内容匹配），保留真实同名文件', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-keep-'));
+  try {
+    await writeSnapshotToDir(sampleSnapshot(), tmp);
+    // 模拟 GitTransport.upload 的空分区占位：custom/skills/.gitkeep（占位内容）
+    await fs.writeFile(path.join(tmp, 'custom', 'skills', SNAPSHOT_KEEP_FILE), SNAPSHOT_KEEP_CONTENT, 'utf8');
+    // 真实同名文件（非占位内容）不得被吞：plugin-files/.gitkeep
+    await fs.writeFile(path.join(tmp, 'plugin-files', SNAPSHOT_KEEP_FILE), 'real user file\n', 'utf8');
+
+    const back = (await readSnapshotFromDir(tmp)) as unknown as PlainSnapshot;
+    const skills = back.sections['skills'] as { files: { relativePath: string; data: Uint8Array }[] };
+    assert.deepEqual(skills.files.map((f) => f.relativePath), ['coding.md', 'nested/tool.md'], '占位文件应从 files 中过滤');
+    const pluginFiles = back.sections['pluginFiles'] as { files: { relativePath: string; data: Uint8Array }[] };
+    assert.deepEqual(pluginFiles.files.map((f) => f.relativePath), [SNAPSHOT_KEEP_FILE, 'dsh-ssh/main.js'], '真实 .gitkeep（非占位内容）应保留');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('readSnapshotFromDir: missingFileDir=empty → 文件分区目录缺失降级为空分区；默认仍抛错', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-empty-dir-'));
+  try {
+    const snap = sampleSnapshot();
+    snap.sections['skills'] = { version: 1, files: [] };
+    await writeSnapshotToDir(snap, tmp);
+    // 模拟 git 远端：空目录未被跟踪 → 目录不存在（manifest 仍声明 skills）
+    await fs.rm(path.join(tmp, 'custom', 'skills'), { recursive: true, force: true });
+
+    // 默认（throw）：目录缺失 → 抛错（不静默降级）
+    await assert.rejects(() => readSnapshotFromDir(tmp), /快照缺少文件分区目录 custom\/skills\/（skills）/);
+    // git 通道语义（empty）：目录缺失 = 空文件分区
+    const back = (await readSnapshotFromDir(tmp, createSnapshotFs(), { missingFileDir: 'empty' })) as unknown as PlainSnapshot;
+    assert.deepEqual(back.sections['skills'], { version: 1, files: [] });
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('注入验证：内存 SnapshotFs 驱动同一往返逻辑', async () => {
+  const mem: Map<string, Uint8Array> = new Map();
+  const snap = sampleSnapshot();
+  const memFs: SnapshotFs = {
+    async readFile(p) {
+      const v = mem.get(p);
+      if (!v) throw new Error(`ENOENT: ${p}`);
+      return v;
+    },
+    async writeFile(p, d) { mem.set(p, new Uint8Array(d)); },
+    async mkdir(p) { mem.set(p + '/.dir', new Uint8Array()); }, // 目录哨兵
+    async readdir(p) {
+      const prefix = p.endsWith('/') ? p : p + '/';
+      const out = new Set<string>();
+      for (const k of mem.keys()) {
+        if (!k.startsWith(prefix)) continue;
+        const rest = k.slice(prefix.length);
+        if (rest === '' || rest === '.dir') continue;
+        out.add(rest.split('/')[0]!);
+      }
+      return [...out];
+    },
+    async isDir(p) {
+      if (mem.has(p + '/.dir')) return true;
+      for (const k of mem.keys()) if (k.startsWith(p + '/')) return true;
+      return false;
+    },
+    async exists(p) { return mem.has(p) || mem.has(p + '/.dir'); },
+    async remove(p) {
+      const prefix = p.endsWith('/') ? p : p + '/';
+      for (const k of [...mem.keys()]) if (k === p || k.startsWith(prefix)) mem.delete(k);
+    },
+  };
+  const manifest = await writeSnapshotToDir(snap, 'snap/001', memFs);
+  const back = await readSnapshotFromDir('snap/001', memFs);
+  assert.equal(back.id, snap.id);
+  const backPlain = back.sections as Partial<Record<SectionId, SectionData>>;
+  const snapPlain = snap.sections as Partial<Record<SectionId, SectionData>>;
+  assert.deepEqual(backPlain['settings'], snapPlain['settings']);
+  const skills = backPlain['skills'] as { files: { relativePath: string; data: Uint8Array; contentHash: string }[] };
+  assert.equal(skills.files.length, 2);
+  assert.equal(hashSection(backPlain['skills']!), manifest.sectionHashes['skills']);
+});
+
+test('createSnapshotFs: 默认 node:fs 适配器可用（真实临时目录）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-layout-adapter-'));
+  try {
+    const fsx = createSnapshotFs();
+    await fsx.mkdir(path.join(tmp, 'a/b'));
+    await fsx.writeFile(path.join(tmp, 'a/b/x.md'), new TextEncoder().encode('hi'));
+    assert.equal(await fsx.exists(path.join(tmp, 'a/b/x.md')), true);
+    assert.equal(await fsx.isDir(path.join(tmp, 'a/b')), true);
+    assert.deepEqual(await fsx.readdir(path.join(tmp, 'a')), ['b']);
+    assert.equal(new TextDecoder().decode(await fsx.readFile(path.join(tmp, 'a/b/x.md'))), 'hi');
+    assert.deepEqual(await listSnapshotFiles(fsx, path.join(tmp, 'a')), ['b/x.md']);
+    await fsx.remove(path.join(tmp, 'a'));
+    assert.equal(await fsx.exists(path.join(tmp, 'a')), false);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});

package/src/sync/layout.ts

@@ -0,0 +1,222 @@
+/**
+ * m-sync-transport：散文件目录布局。
+ * 快照根目录 = manifest.json + 按 SECTION_JSON_PATHS 平铺的 JSON 分区
+ *            + 按 SECTION_FILE_PREFIXES 的文件类分区目录（skills 等真实文件）。
+ * 复用 src/schema/config.ts 的路径表；核心逻辑经 SnapshotFs 注入（默认 node:fs/promises）。
+ */
+import path from 'node:path';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
+import { sha256Hex } from '../utils/hashing.ts';
+import { SECTION_FILE_PREFIXES, SECTION_JSON_PATHS } from '../schema/config.ts';
+import type { FilesSection, SectionData, SectionId } from '../schema/types.ts';
+import { createSnapshotFs, joinFs } from './fs.ts';
+import type { SnapshotFs } from './fs.ts';
+import { hashSection } from './sync-state.ts';
+import type { SyncSnapshot } from './transport.ts';
+import { isEncryptedSections } from './transport.ts';
+
+export const SNAPSHOT_MANIFEST_FILE = 'manifest.json';
+
+/**
+ * 空文件类分区的 git 占位文件（git 不跟踪空目录）：
+ * 上传方（GitTransport.upload）给 files 为空的文件类分区目录写入本占位文件，
+ * 保证远端仓库保留该目录；读回时仅当「文件名 + 内容」同时匹配才过滤，
+ * 避免吞掉用户真实同名文件。占位文件不参与 sectionHashes（基于传入数据计算）。
+ * 注意：占位内容不得含换行 —— Windows core.autocrlf 会把 LF 转 CRLF，内容校验会失败。
+ */
+export const SNAPSHOT_KEEP_FILE = '.gitkeep';
+export const SNAPSHOT_KEEP_CONTENT = 'DSH Config Manager sync placeholder (keep empty section dir)';
+const SNAPSHOT_KEEP_BYTES = new TextEncoder().encode(SNAPSHOT_KEEP_CONTENT);
+
+function isKeepFile(rel: string, data: Uint8Array): boolean {
+  if (rel !== SNAPSHOT_KEEP_FILE) return false;
+  if (data.length !== SNAPSHOT_KEEP_BYTES.length) return false;
+  for (let i = 0; i < data.length; i++) {
+    if (data[i] !== SNAPSHOT_KEEP_BYTES[i]) return false;
+  }
+  return true;
+}
+
+/** 快照根目录下的 manifest.json 结构 */
+export interface SnapshotDirManifest {
+  id: string;
+  createdAt: string; // ISO-8601 UTC
+  manifest: SyncSnapshot['manifest'];
+  /** 各分区内容 hash（写入时由 hashSection 计算） */
+  sectionHashes: Partial<Record<SectionId, string>>;
+}
+
+/** 布局支持的分区 = SECTION_JSON_PATHS ∪ SECTION_FILE_PREFIXES（secrets 等不在内） */
+const LAYOUT_SECTION_IDS: readonly SectionId[] = [
+  ...Object.keys(SECTION_JSON_PATHS),
+  ...Object.keys(SECTION_FILE_PREFIXES),
+] as SectionId[];
+
+/**
+ * 文件相对路径安全检查：拒绝空/'.'/'..'、绝对路径、Windows 盘符、反斜杠、
+ * 含 '..' 或 '.' 片段（防穿越快照根目录）。
+ */
+export function isSafeRelPath(rel: string): boolean {
+  if (rel === '' || rel === '.' || rel === '..') return false;
+  if (rel.startsWith('/') || /^[A-Za-z]:[\\/]/.test(rel)) return false;
+  if (rel.includes('\\')) return false;
+  const parts = rel.split('/');
+  if (parts.some((p) => p === '' || p === '.' || p === '..')) return false;
+  return true;
+}
+
+/** 递归列出 dir 下的全部文件（相对 dir 的正斜杠路径，字典序）；目录不存在 → [] */
+export async function listSnapshotFiles(fsx: SnapshotFs, dir: string): Promise<string[]> {
+  const out: string[] = [];
+  const walk = async (abs: string, rel: string): Promise<void> => {
+    const names = await fsx.readdir(abs);
+    for (const name of names) {
+      if (name === '' || name === '.' || name === '..') continue; // 防御异常/恶意 fs
+      const childAbs = joinFs(abs, name);
+      const childRel = rel === '' ? name : `${rel}/${name}`;
+      if (await fsx.isDir(childAbs)) {
+        await walk(childAbs, childRel);
+      } else {
+        out.push(childRel);
+      }
+    }
+  };
+  await walk(dir, '');
+  return out.sort();
+}
+
+/**
+ * 将快照写入散文件目录。
+ * 非法输入（不支持的子分区 / 穿越路径）在任何写入发生前抛错，不留半成品目录。
+ */
+export async function writeSnapshotToDir(
+  snapshot: SyncSnapshot,
+  dir: string,
+  fsx: SnapshotFs = createSnapshotFs(),
+): Promise<SnapshotDirManifest> {
+  // 加密快照不写散文件目录（本地不落盘：密文/明文都不落；远端已存密文）
+  if (isEncryptedSections(snapshot.sections)) {
+    throw new Error('加密快照不写散文件目录（本地不落盘；请直接使用密文传输）');
+  }
+  const sectionHashes: SnapshotDirManifest['sectionHashes'] = {};
+  for (const [id, data] of Object.entries(snapshot.sections)) {
+    const sid = id as SectionId;
+    if (!LAYOUT_SECTION_IDS.includes(sid)) {
+      throw new Error(`分区 ${sid} 不在散文件布局支持范围（SECTION_JSON_PATHS / SECTION_FILE_PREFIXES）`);
+    }
+    sectionHashes[sid] = hashSection(data as SectionData);
+  }
+  // 预校验全部文件相对路径（不合法 → 抛错且零写入）
+  for (const [sid, data] of Object.entries(snapshot.sections)) {
+    if (!(sid in SECTION_FILE_PREFIXES)) continue;
+    for (const file of (data as FilesSection).files) {
+      if (!isSafeRelPath(file.relativePath)) {
+        throw new Error(`非法文件相对路径: ${file.relativePath}（分区 ${sid}）`);
+      }
+    }
+  }
+
+  await fsx.mkdir(dir);
+  const manifest: SnapshotDirManifest = {
+    id: snapshot.id,
+    createdAt: snapshot.createdAt,
+    manifest: snapshot.manifest,
+    sectionHashes,
+  };
+  await fsx.writeFile(joinFs(dir, SNAPSHOT_MANIFEST_FILE), new TextEncoder().encode(stringifyJsonSafe(manifest, { space: 2 })));
+
+  // JSON 分区：按 SECTION_JSON_PATHS 平铺
+  for (const [sid, rel] of Object.entries(SECTION_JSON_PATHS)) {
+    const data = snapshot.sections[sid as SectionId];
+    if (data === undefined) continue;
+    const abs = joinFs(dir, rel);
+    await fsx.mkdir(path.dirname(abs));
+    await fsx.writeFile(abs, new TextEncoder().encode(stringifyJsonSafe(data, { space: 2 })));
+  }
+
+  // 文件类分区：目录前缀 + 真实文件
+  for (const [sid, prefix] of Object.entries(SECTION_FILE_PREFIXES)) {
+    const data = snapshot.sections[sid as SectionId] as FilesSection | undefined;
+    if (data === undefined) continue;
+    const baseAbs = joinFs(dir, prefix);
+    await fsx.mkdir(baseAbs); // 空文件类分区也保留目录（读回可还原空 files）
+    for (const file of data.files) {
+      const abs = joinFs(baseAbs, file.relativePath);
+      await fsx.mkdir(path.dirname(abs));
+      await fsx.writeFile(abs, file.data);
+    }
+  }
+  return manifest;
+}
+
+/**
+ * 从散文件目录读回快照。
+ * manifest 声明的分区必须可解析：JSON 分区文件缺失 / 文件分区目录缺失 → 抛错（不静默降级），
+ * 但 opts.missingFileDir='empty' 时文件分区目录缺失降级为空分区
+ * （git 通道专用：git 不跟踪空目录，目录缺失 = 空文件分区；提交原子性保证非空目录不会缺失）。
+ * 读回时过滤 git 占位文件（SNAPSHOT_KEEP_FILE），使 files 与上传方数据一致。
+ */
+export async function readSnapshotFromDir(
+  dir: string,
+  fsx: SnapshotFs = createSnapshotFs(),
+  opts: { missingFileDir?: 'throw' | 'empty' } = {},
+): Promise<SyncSnapshot> {
+  const manifestAbs = joinFs(dir, SNAPSHOT_MANIFEST_FILE);
+  if (!(await fsx.exists(manifestAbs))) {
+    throw new Error(`快照目录缺少 ${SNAPSHOT_MANIFEST_FILE}: ${dir}`);
+  }
+  const parsed = parseJsonSafe(Buffer.from(await fsx.readFile(manifestAbs)).toString('utf8'));
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('manifest.json 损坏：必须是对象');
+  }
+  const m = parsed as Record<string, unknown>;
+  if (typeof m['id'] !== 'string' || typeof m['createdAt'] !== 'string'
+    || m['manifest'] === null || typeof m['manifest'] !== 'object'
+    || m['sectionHashes'] === null || typeof m['sectionHashes'] !== 'object') {
+    throw new Error('manifest.json 损坏：缺少 id/createdAt/manifest/sectionHashes');
+  }
+  const manifest = parsed as SnapshotDirManifest;
+
+  const sections: SyncSnapshot['sections'] = {};
+  const declared = Object.keys(manifest.sectionHashes) as SectionId[];
+  for (const sid of declared) {
+    if (!LAYOUT_SECTION_IDS.includes(sid)) {
+      throw new Error(`manifest 声明了布局不支持的分区 ${sid}`);
+    }
+  }
+
+  // JSON 分区
+  for (const [sid, rel] of Object.entries(SECTION_JSON_PATHS)) {
+    if (!(sid in manifest.sectionHashes)) continue;
+    const abs = joinFs(dir, rel);
+    if (!(await fsx.exists(abs))) {
+      throw new Error(`快照缺少 JSON 分区文件 ${rel}（${sid}）`);
+    }
+    sections[sid as SectionId] = parseJsonSafe(Buffer.from(await fsx.readFile(abs)).toString('utf8')) as SectionData;
+  }
+
+  // 文件类分区
+  for (const [sid, prefix] of Object.entries(SECTION_FILE_PREFIXES)) {
+    if (!(sid in manifest.sectionHashes)) continue;
+    const baseAbs = joinFs(dir, prefix);
+    if (!(await fsx.isDir(baseAbs))) {
+      if (opts.missingFileDir === 'empty') {
+        // git 通道降级：目录缺失 = 空文件分区（git 不跟踪空目录，详见函数注释）
+        sections[sid as SectionId] = { version: 1, files: [] };
+        continue;
+      }
+      throw new Error(`快照缺少文件分区目录 ${prefix}（${sid}）`);
+    }
+    const rels = await listSnapshotFiles(fsx, baseAbs);
+    const files: FilesSection['files'] = [];
+    for (const rel of rels) {
+      const data = await fsx.readFile(joinFs(baseAbs, rel));
+      // 过滤 git 占位文件（名 + 内容同时匹配才过滤，避免吞用户真实同名文件）
+      if (isKeepFile(rel, data)) continue;
+      files.push({ relativePath: rel, data, contentHash: sha256Hex(data) });
+    }
+    sections[sid as SectionId] = { version: 1, files };
+  }
+
+  return { id: manifest.id, createdAt: manifest.createdAt, manifest: manifest.manifest, sections };
+}

package/src/sync/snapshot-json.test.ts

@@ -0,0 +1,119 @@
+/**
+ * m-sync-json：SyncSnapshot JSON 安全序列化测试。
+ * 核心回归：文件类分区（Uint8Array）经 JSON 往返必须还原成 Uint8Array
+ * （此前 JSON.stringify 把 TypedArray 变成数字索引对象，导致
+ * 「The "data" argument must be of type string or an instance of Buffer…」）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  deserializeSnapshot, sectionsFromJsonSafe, sectionsToJsonSafe, serializeSnapshot,
+} from './snapshot-json.ts';
+import { encryptSectionsPayload, decryptSectionsPayload } from '../../tests/fixtures/legacy-snapshot-crypto.ts';
+import type { SyncSnapshot } from './transport.ts';
+import { isEncryptedSections } from './transport.ts';
+import type { SectionId } from '../schema/types.ts';
+
+function fileSnapshot(overrides: Partial<SyncSnapshot> = {}): SyncSnapshot {
+  return {
+    id: 'snap-files',
+    createdAt: '2026-08-16T12:00:00.000Z',
+    manifest: {
+      schemaVersion: 1,
+      dshVersion: '1.2.3',
+      platform: 'win32',
+      sectionIds: ['settings', 'skills'],
+      containsSecrets: false,
+    },
+    sections: {
+      settings: { version: 1, namespaces: { general: { value: { theme: 'dark' }, revision: 1, secrets: [] } } },
+      skills: {
+        version: 1,
+        files: [
+          { relativePath: 'coding.md', data: new Uint8Array(Buffer.from('# Coding\n', 'utf8')), contentHash: 'h1' },
+          { relativePath: 'sub/notes.txt', data: new Uint8Array(Buffer.from('hello world', 'utf8')), contentHash: 'h2' },
+        ],
+      },
+    },
+    ...overrides,
+  } as SyncSnapshot;
+}
+
+test('serializeSnapshot：文件分区 data 以 base64 形传输（JSON 往返无损还原 Uint8Array）', () => {
+  const raw = serializeSnapshot(fileSnapshot());
+  const parsed = JSON.parse(raw) as SyncSnapshot;
+  // 传输形态：不是数字索引对象，而是 {$bin: base64}
+  const files = (parsed.sections as { skills: { files: Array<{ data: unknown }> } }).skills.files;
+  for (const f of files) {
+    const d = f.data as { $bin?: string };
+    assert.equal(typeof d.$bin, 'string', '文件 data 应为 { $bin: base64 }');
+    assert.equal(d.$bin!.length > 0, true);
+  }
+  // 往返还原：字节必须分毫不差
+  const roundtrip = deserializeSnapshot(raw);
+  const rfiles = (roundtrip.sections as { skills: { files: Array<{ data: Uint8Array; relativePath: string }> } }).skills.files;
+  assert.equal(rfiles.length, 2);
+  assert.ok(rfiles[0]!.data instanceof Uint8Array, '还原后 data 必须是 Uint8Array');
+  assert.equal(Buffer.from(rfiles[0]!.data).toString('utf8'), '# Coding\n');
+  assert.equal(rfiles[1]!.relativePath, 'sub/notes.txt');
+  assert.equal(Buffer.from(rfiles[1]!.data).toString('utf8'), 'hello world');
+  // JSON 分区原样保留
+  const settings = (roundtrip.sections as { settings: { namespaces: Record<string, unknown> } }).settings;
+  assert.deepEqual(settings.namespaces['general'], { value: { theme: 'dark' }, revision: 1, secrets: [] });
+});
+
+test('serializeSnapshot：加密快照（EncryptedSections）原样透传不破坏', () => {
+  const encrypted: SyncSnapshot = {
+    id: 'snap-enc',
+    createdAt: '2026-08-16T12:00:00.000Z',
+    manifest: { schemaVersion: 1, dshVersion: '1.2.3', platform: 'win32', sectionIds: ['settings'], containsSecrets: true, encrypted: true },
+    sections: { encrypted: { info: { algo: 'aes-256-gcm', kdf: 'scrypt' } as never, data: 'c2VjcmV0IGNpcGhlcnRleHQ=' } },
+  };
+  const raw = serializeSnapshot(encrypted);
+  const roundtrip = deserializeSnapshot(raw);
+  assert.ok(isEncryptedSections(roundtrip.sections), '加密载荷必须保持 EncryptedSections 形态');
+  assert.deepEqual(roundtrip.sections, encrypted.sections);
+  assert.equal(roundtrip.manifest.encrypted, true);
+});
+
+test('sectionsToJsonSafe / sectionsFromJsonSafe：明文 sections 往返等价', () => {
+  const snap = fileSnapshot();
+  const safe = sectionsToJsonSafe(snap.sections);
+  const back = sectionsFromJsonSafe(safe);
+  assert.deepEqual(back, snap.sections, '明文 sections 往返应深等价（data 还原为 Uint8Array）');
+});
+
+test('deserializeSnapshot：形状非法 → 抛错', () => {
+  assert.throws(() => deserializeSnapshot('{"not":"snapshot"}'), /形状非法/);
+  assert.throws(() => deserializeSnapshot('not-json'), /JSON/);
+});
+
+test('加密载荷：含文件分区加密 → 解密还原 Uint8Array（字节无损）', async () => {
+  const snap = fileSnapshot();
+  const enc = await encryptSectionsPayload(snap.sections as Parameters<typeof encryptSectionsPayload>[0], 'pw-12345678');
+  assert.ok(isEncryptedSections({ encrypted: enc.encrypted }));
+  const decrypted = await decryptSectionsPayload(enc.encrypted, 'pw-12345678');
+  const files = (decrypted as { skills: { files: Array<{ data: Uint8Array; relativePath: string }> } }).skills.files;
+  assert.ok(files[0]!.data instanceof Uint8Array, '解密后文件 data 必须是 Uint8Array');
+  assert.equal(Buffer.from(files[0]!.data).toString('utf8'), '# Coding\n');
+  assert.equal(Buffer.from(files[1]!.data).toString('utf8'), 'hello world');
+});
+
+test('回归：webdav 序列化快照含文件分区 → JSON 中无数字索引对象（{0:..,1:..}）', () => {
+  const snap = fileSnapshot();
+  const raw = serializeSnapshot(snap);
+  assert.ok(!/\"0\"\s*:/.test(raw), '序列化不得出现数字索引对象形态');
+  // 空 data（零字节文件）也可往返
+  const empty = fileSnapshot();
+  (empty.sections as unknown as { skills: { files: Array<{ relativePath: string; data: Uint8Array }> } }).skills.files = [
+    { relativePath: 'empty.bin', data: new Uint8Array(0) },
+  ];
+  const rt = deserializeSnapshot(serializeSnapshot(empty));
+  const files = (rt.sections as { skills: { files: Array<{ data: Uint8Array }> } }).skills.files;
+  assert.equal(files[0]!.data.length, 0);
+  assert.ok(files[0]!.data instanceof Uint8Array);
+});
+
+// 类型辅助（避免未使用告警）
+void ([] as SectionId[]);