dsh-config-manager 0.1.63 → 0.1.64

package/src/adapters/file-collection.test.ts

@@ -0,0 +1,256 @@
+/**
+ * 文件类分区导出的**字节闸门**（审计 core-flow F-12 / sync#F-12）测试。
+ *
+ * 覆盖：
+ *  ① 超限 → 单元**整块**剔除，且被剔除的单元写进 warnings（报告可见，绝不静默）；
+ *  ② 未超限 → 与「改造前」的收集逻辑**逐项一致**（自包含对照：legacy 循环逐字内联，不依赖 git 回退）；
+ *  ③ 单元不可拆分：只放得下一半时一个文件都不留（宁可少带，不可半带）；
+ *  ④ 单元成员在遍历结果里**不连续**也不会被劈开（分组在闸门之前完成）；
+ *  ⑤ 放不下的单元跳过后**继续尝试后面的单元**（后面的小单元仍可能入选）；
+ *  ⑥ 告警列表有上限（大分区不刷屏），被折叠的数量的确进了文案。
+ *  ⑦ validate 的样板收敛：object 守卫并入共享骨架 validateJsonSection（走可选 objectMessageKey）后，
+ *     5 个文件类分区的用户可见报错文案与改造前逐字相同（zh / en / 缺省三条路径）。
+ *
+ * 阈值：测试用探针把闸门降到几十~几百字节 —— 真实阈值 MAX_FILE_SECTION_BYTES = 256 MiB
+ * 无法在单测里构造而不吃掉 256 MiB 内存（这正是闸门要防的东西）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { FileCollectionAdapter, MAX_FILE_SECTION_BYTES } from './file-collection.ts';
+import { SkillsAdapter } from './skills.ts';
+import { listFilesDetailed } from './link-report.ts';
+import { makeContext, sha256Hex } from './test-helpers.ts';
+import { AgentPresetsAdapter } from './agent-presets.ts';
+import { AgentInstructionsAdapter } from './agent-instructions.ts';
+import { SessionsAdapter } from './sessions.ts';
+import { SelfAdapter } from './self.ts';
+import { makeMsg, zhMsg } from '../core/messages.ts';
+import { validateJsonSection } from './json-section.ts';
+import type { FileEntry } from '../schema/types.ts';
+import type { MockHostContext } from './test-helpers.ts';
+
+/** 探针：与 skills 同构，但把闸门降到 `limit` 字节（生产代码不覆写 sectionByteLimit） */
+class ProbeAdapter extends FileCollectionAdapter {
+  readonly id = 'skills' as const;
+  readonly displayName = 'Skills';
+  readonly defaultIncluded = true;
+  readonly portability = 'portable' as const;
+  readonly baseDir = 'skills';
+  private readonly limit: number;
+  constructor(limit: number) {
+    super();
+    this.limit = limit;
+  }
+  protected override sectionByteLimit(): number {
+    return this.limit;
+  }
+}
+
+/** 写入 n 字节的零内容文件（内容无所谓，闸门只看 byteLength） */
+async function writeSized(ctx: MockHostContext, rel: string, n: number): Promise<void> {
+  await ctx.fs.writeFile(rel, new Uint8Array(n));
+}
+
+function paths(section: { data: { files: { relativePath: string }[] } }): string[] {
+  return section.data.files.map((f) => f.relativePath);
+}
+
+/* ---------------- ② 未超限：与改造前逐项一致（自包含对照） ---------------- */
+
+/**
+ * 「改造前」的收集循环（逐字复刻 Gate 落地前的实现）：
+ * listFilesDetailed → relPathOf → unitIdOf 白名单 → readFile → push。
+ * 用它当参照，验证闸门在**未触发**时不改变任何一项（顺序 / 路径 / 字节 / hash）。
+ */
+async function legacyCollect(ctx: MockHostContext, baseDir: string, allow: readonly string[] | undefined): Promise<FileEntry[]> {
+  const listing = await listFilesDetailed(ctx.fs, baseDir);
+  const out: FileEntry[] = [];
+  for (const rel of listing.paths) {
+    const relPath = rel.replace(new RegExp('^' + baseDir + '[\\\\/]'), '');
+    const unit = relPath.includes('/') ? relPath.slice(0, relPath.indexOf('/')) : relPath;
+    if (allow !== undefined && !allow.includes('skills:' + unit)) continue;
+    const data = await ctx.fs.readFile(rel);
+    out.push({ relativePath: relPath, data, contentHash: sha256Hex(data) });
+  }
+  return out;
+}
+
+test('字节闸门：未超限时与改造前的收集逻辑逐项一致（顺序/路径/字节/hash + 零告警）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  await writeSized(ctx, 'skills/alpha/a.md', 100);
+  await writeSized(ctx, 'skills/alpha/b.md', 50);
+  await writeSized(ctx, 'skills/beta/c.md', 70);
+  await writeSized(ctx, 'skills/loose.md', 10);
+
+  // 闸门远大于总字节（190）→ 一次都不该触发
+  const section = await new ProbeAdapter(10_000).export(ctx, { includeSecrets: false });
+  const legacy = await legacyCollect(ctx, 'skills', undefined);
+
+  assert.deepEqual(section.warnings, [], '未超限不得产出任何告警');
+  assert.deepEqual(
+    section.data.files.map((f) => ({ relativePath: f.relativePath, bytes: f.data.byteLength, contentHash: f.contentHash })),
+    legacy.map((f) => ({ relativePath: f.relativePath, bytes: f.data.byteLength, contentHash: f.contentHash })),
+    '逐项一致：顺序 + 相对路径 + 字节数 + SHA-256',
+  );
+  assert.deepEqual(paths(section), ['alpha/a.md', 'alpha/b.md', 'beta/c.md', 'loose.md']);
+  assert.equal(section.counts.files, 4);
+
+  // 白名单路径同样逐项一致（闸门不改变 includeItems 语义）
+  const allow = ['skills:alpha'];
+  const filtered = await new ProbeAdapter(10_000).export(ctx, { includeSecrets: false, includeItems: { skills: allow } });
+  const filteredLegacy = await legacyCollect(ctx, 'skills', allow);
+  assert.deepEqual(paths(filtered), filteredLegacy.map((f) => f.relativePath));
+  assert.deepEqual(filtered.warnings, []);
+});
+
+/* ---------------- ① 超限：整块剔除 + 告警可见 ---------------- */
+
+test('字节闸门：超限时按单元整块剔除，并把该单元写进告警（绝不静默）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  await writeSized(ctx, 'skills/alpha/a.md', 120);
+  await writeSized(ctx, 'skills/alpha/b.md', 80);   // alpha = 200
+  await writeSized(ctx, 'skills/beta/c.md', 200);   // beta = 200，room 只剩 100 → 放不下
+
+  const section = await new ProbeAdapter(300).export(ctx, { includeSecrets: false });
+
+  assert.deepEqual(paths(section), ['alpha/a.md', 'alpha/b.md'], 'beta 整块不进备份');
+  assert.equal(section.counts.files, 2, 'counts 反映实际带走的文件数');
+  const gate = section.warnings.filter((w) => w.includes('单分区上限'));
+  assert.equal(gate.length, 1, `应恰有一条闸门告警，实际: ${section.warnings.join(' | ')}`);
+  const line = gate[0] ?? '';
+  assert.match(line, /1 个单元/, '告警给出被剔除的单元数');
+  assert.match(line, /300 B/, '告警给出上限值');
+  assert.match(line, /200\.0 B|200 B/, '告警给出实际保留量');
+  assert.match(line, /—— beta$/, '告警列出被剔除的单元 id（无折叠后缀）');
+
+  // 内容确实不在产物里（不是「报了警但其实还在」）
+  assert.equal(section.data.files.some((f) => f.relativePath.startsWith('beta/')), false);
+});
+
+test('字节闸门：单元不可拆分 —— 只放得下一半时，该单元一个文件都不留', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  await writeSized(ctx, 'skills/skill-a/one.md', 60);
+  await writeSized(ctx, 'skills/skill-a/two.md', 60);   // 单元合计 120 > 上限 100
+
+  const section = await new ProbeAdapter(100).export(ctx, { includeSecrets: false });
+
+  assert.deepEqual(section.data.files, [], '整块剔除：不能只留 60 字节的那一半');
+  assert.equal(section.counts.files, 0);
+  assert.match(section.warnings.find((w) => w.includes('单分区上限')) ?? '', /—— skill-a$/);
+});
+
+/* ---------------- ④ 成员不连续也不会被劈开 ---------------- */
+
+test('字节闸门：单元的成员在遍历结果里不连续时同样整块判定（不会被劈成两半）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  await ctx.fs.writeFile('skills/a/1.md', new Uint8Array(60));
+  await ctx.fs.writeFile('skills/b/1.md', new Uint8Array(60));
+  await ctx.fs.writeFile('skills/a/2.md', new Uint8Array(60));
+  // 故意让遍历结果按 a、b、a 交错返回（真实 walk 不保证顺序，mock 直接钉住这条边界）
+  ctx.fs.listRecursiveDetailed = async () => ({
+    paths: ['skills/a/1.md', 'skills/b/1.md', 'skills/a/2.md'],
+    skippedLinks: [],
+    followedLinks: 0,
+    unreadableDirs: [],
+  });
+
+  const section = await new ProbeAdapter(150).export(ctx, { includeSecrets: false });
+
+  // a = 120（两段合计）→ 入选；b = 60（room 只剩 30）→ 整块剔除
+  assert.deepEqual(paths(section), ['a/1.md', 'a/2.md'], 'a 的两段一起入选（未按段拆开），b 整体剔除');
+  assert.match(section.warnings.find((w) => w.includes('单分区上限')) ?? '', /—— b$/);
+});
+
+/* ---------------- ⑤ 跳过后继续尝试后面的单元 ---------------- */
+
+test('字节闸门：一个巨型单元被剔除后，后面的小单元仍可能入选（尽量多带）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  // 遍历顺序是字典序：big < huge < small —— 前 200 入选，huge（200）放不下被整块剔除，
+  // 后面 room 仍是 100 的 small 不受牵连（硬停会把 small 一起丢掉）。
+  await writeSized(ctx, 'skills/big/a.md', 200);
+  await writeSized(ctx, 'skills/huge/a.md', 200);
+  await writeSized(ctx, 'skills/small/a.md', 50);
+
+  const section = await new ProbeAdapter(300).export(ctx, { includeSecrets: false });
+
+  assert.deepEqual(paths(section), ['big/a.md', 'small/a.md'], '一个巨型单元不该把它之后的内容一起带走');
+  assert.match(section.warnings.find((w) => w.includes('单分区上限')) ?? '', /—— huge$/);
+});
+
+/* ---------------- ⑥ 告警列表有上限，折叠数量不丢 ---------------- */
+
+test('字节闸门：被剔除单元很多时告警只列前 5 个，剩余折叠为 (+ N)（不刷屏也不静默）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  await writeSized(ctx, 'skills/first/a.md', 100);
+  for (let i = 0; i < 7; i += 1) await writeSized(ctx, `skills/u${i}/a.md`, 100);  // 每个 100，room 只剩 0 → 全部剔除
+
+  const section = await new ProbeAdapter(100).export(ctx, { includeSecrets: false });
+
+  const line = section.warnings.find((w) => w.includes('单分区上限')) ?? '';
+  assert.deepEqual(paths(section), ['first/a.md']);
+  assert.match(line, /7 个单元/);
+  assert.match(line, /\(\+ 2\)/, '折叠数量必须出现在文案里（否则截断本身又成了静默丢失）');
+  for (const name of ['u0', 'u1', 'u2', 'u3', 'u4']) assert.match(line, new RegExp('\\b' + name + '\\b'));
+  assert.equal(line.includes('u5'), false, '第 6 个起折叠');
+});
+
+/* ---------------- 默认阈值 ---------------- */
+
+test('字节闸门：默认阈值 = 256 MiB（与导入侧上传硬上限对齐），且普通内容不触发', async () => {
+  assert.equal(MAX_FILE_SECTION_BYTES, 256 * 1024 * 1024);
+  assert.equal(MAX_FILE_SECTION_BYTES, 268435456);
+
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  await writeSized(ctx, 'skills/big/a.md', 2 * 1024 * 1024);   // 2 MiB：远低于阈值
+  const section = await new SkillsAdapter().export(ctx, { includeSecrets: false });
+  assert.deepEqual(paths(section), ['big/a.md'], '真实适配器在默认阈值下不做任何剔除');
+  assert.deepEqual(section.warnings, []);
+});
+
+/* ---------------- ⑦ validate：object 守卫并入共享骨架后文案逐字不变 ---------------- */
+
+test('validateJsonSection：objectMessageKey 可选，缺省即 adapter.validate.object，且不改变其余语义', () => {
+  // ① 不传第 6 参 = 既有 9 个调用点的行为（缺省键 + subject 插值）
+  assert.deepEqual(validateJsonSection<{ version?: unknown }>('skills', null, zhMsg), {
+    valid: false,
+    issues: [{ path: '$', message: 'skills 数据必须是对象', severity: 'error' }],
+  });
+  // ② 自定义键：文案取自该键；文件类分区的专用键不含 {subject}，故第 5 参取值不影响输出
+  assert.deepEqual(validateJsonSection<{ version?: unknown }>('skills', null, zhMsg, undefined, 'skills', 'adapter.validate.fileSection'), {
+    valid: false,
+    issues: [{ path: '$', message: '文件分区数据必须是对象', severity: 'error' }],
+  });
+  assert.deepEqual(validateJsonSection<{ version?: unknown }>('skills', null, zhMsg, undefined, '别名', 'adapter.validate.fileSection'), {
+    valid: false,
+    issues: [{ path: '$', message: '文件分区数据必须是对象', severity: 'error' }],
+  });
+  // ③ en 目录同样走自定义键
+  assert.deepEqual(validateJsonSection<{ version?: unknown }>('skills', null, makeMsg('en'), undefined, 'skills', 'adapter.validate.fileSection'), {
+    valid: false,
+    issues: [{ path: '$', message: 'File-section data must be an object', severity: 'error' }],
+  });
+  // ④ object 守卫之外的语义与新增参数无关（version 不匹配仍继续做形状检查）
+  assert.deepEqual(validateJsonSection<{ version?: unknown }>('skills', { version: 2 }, zhMsg), {
+    valid: false,
+    issues: [{ path: 'version', message: 'version 必须为 1（收到 2）', severity: 'error' }],
+  });
+});
+
+test('validate：5 个文件类分区的 object 守卫并入骨架后，用户可见文案与改造前逐字相同', async () => {
+  const fileAdapters = [
+    new SkillsAdapter(), new AgentPresetsAdapter(), new AgentInstructionsAdapter(),
+    new SessionsAdapter(), new SelfAdapter(),
+  ];
+  const zhExpected = { valid: false, issues: [{ path: '$', message: '文件分区数据必须是对象', severity: 'error' }] };
+  const enExpected = { valid: false, issues: [{ path: '$', message: 'File-section data must be an object', severity: 'error' }] };
+  for (const adapter of fileAdapters) {
+    assert.deepEqual(await adapter.validate(null as never), zhExpected, adapter.id + '：缺省（zh）文案');
+    assert.deepEqual(await adapter.validate('x' as never, makeMsg('en')), enExpected, adapter.id + '：en 文案');
+    assert.deepEqual(await adapter.validate(42 as never, makeMsg('zh')), zhExpected, adapter.id + '：任何非对象都是同一条');
+    // 专用键不含 {subject}：并入骨架后若误用缺省键，文案会变成「<分区 id> 数据必须是对象」
+    const message = (await adapter.validate(null as never)).issues[0]?.message ?? '';
+    assert.equal(message.includes(adapter.id), false, adapter.id + '：文案不得退化成 <subject> 数据必须是对象');
+  }
+});
+

package/src/adapters/file-collection.ts

@@ -6,6 +6,10 @@
  *
  * 文件内容以真实文件进入 ZIP（custom/skills/… 等前缀由 exporter 按 SECTION_FILE_PREFIXES 处理）。
  * 幂等：相对路径 + 内容 SHA-256 hash 比对（重复导入 → Skip）。
+ *
+ * 导出的**单分区字节闸门**（审计 core-flow F-12 / sync#F-12）：累计到 MAX_FILE_SECTION_BYTES 后，
+ * 放不下的单元**整块**剔除并写进告警（见 export()）。覆盖 skills / agentPresets / sessions；
+ * agentInstructions（单文件 AGENTS.md）与 self（白名单配置小文件）各自覆写 export，不在本闸门射程内。
  */
 import path from 'node:path';
 import { sha256Hex } from '../utils/hashing.ts';
@@ -20,8 +24,42 @@ import type {
   ImportContext, PlanItem, Portability, ValidationResult,
 } from '../core/types.ts';
 import { defaultUnitId, unitAllowed, unitsFromFiles } from './units.ts';
+import { validateJsonSection } from './json-section.ts';
+
+/**
+ * 文件类分区导出的**单分区累计字节闸门**：分区内文件内容合计放不下的单元整块剔除（见 export()）。
+ *
+ * 取值依据（不是随手拍的数）：
+ *  1) **对称性** —— 导入侧对上传的备份包有硬上限 256 MiB（MAX_UPLOAD_BYTES，src/index.ts 与
+ *     src/routes/kit.ts 的上传路径）；导出侧此前**没有任何体积约束**，于是会出现「导出成功、
+ *     传不回来」（审计 core-flow F-12 / sync#F-12）。取同一个 256 MiB 作**单分区**上限：
+ *     任何单个分区都落在导入侧上传路径能收的范围内。
+ *  2) **内存峰值** —— 导出时文件内容以完整 Uint8Array 驻留内存（ZIP 组装前全量在内存里），同步通道
+ *     还要再写一份。闸门把「单分区常驻」钳在 256 MiB 以内（峰值 ≈ 上限 + 正在读的那个单元），
+ *     不再是「会话附件多大就多吃多少」。
+ *  3) **与既有同类上限同量级** —— MAX_MARKET_ZIP_BYTES = 64 MiB、DEFAULT_MAX_JSON_BYTES = 64 MiB、
+ *     MAX_LOCAL_TARBALL_BYTES = 100 MiB、MAX_PATCH_FILE_BYTES = 2 MiB。文件类分区装的是**用户真实
+ *     文件**，所以取「导入侧能收」的 256 MiB，而不是为省内存随意调小（那会平白少带用户数据）。
+ *  4) **为什么按分区而不是按整包** —— 整包体积由用户勾选跨分区决定；闸门要能给出「哪些分区、哪些
+ *     单元没进去」的可执行信息，落在分区/单元层才可解释。
+ *
+ * 超限时**绝不静默**：被整块剔除的单元清单进 ExportSection.warnings（导出报告可见）。
+ */
+export const MAX_FILE_SECTION_BYTES = 256 * 1024 * 1024;
+
+/** 字节闸门告警里最多列出的单元数（其余折叠成 "(+ N)"，避免大分区把报告撑爆；与 link-report 同口径） */
+const MAX_UNITS_PER_GATE_WARNING = 5;
+
+/** 告警文案里的体积（人类可读；纯数值格式化，不含用户可见散文） */
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
 
 export abstract class FileCollectionAdapter implements ConfigAdapter<FilesSection> {
+  /** 文件集合：`relativePath` 是身份而非配置 → 永不被导入时的前缀映射改写（见 ConfigAdapter.fileCollection） */
+  readonly fileCollection = true;
   abstract readonly id: SectionId;
   abstract readonly displayName: string;
   abstract readonly defaultIncluded: boolean;
@@ -47,6 +85,17 @@ export abstract class FileCollectionAdapter implements ConfigAdapter<FilesSectio
     return rel.replace(new RegExp('^' + prefix + '[\\\\/]'), '');
   }
 
+  /**
+   * 单分区累计字节上限（缺省 MAX_FILE_SECTION_BYTES = 256 MiB，见该常量注释）。
+   *
+   * 生产代码不覆写；留成受保护方法只为让测试能构造「超限」场景（真实阈值 256 MiB 无法在单测里
+   * 造出来而不吃掉 256 MiB 内存）。若要给用户配置入口，应走 ExportOptions（src/core/types.ts），
+   * 而不是在子类里飘一个隐式默认值。
+   */
+  protected sectionByteLimit(): number {
+    return MAX_FILE_SECTION_BYTES;
+  }
+
   /**
    * 条目级选择（Phase 1）：只导出白名单命中的单元。
    *
@@ -85,13 +134,68 @@ export abstract class FileCollectionAdapter implements ConfigAdapter<FilesSectio
     const restricted = await this.restrictUnits(ctx, rels, options);
     if (restricted !== null) warnings.push(...restricted.warnings);
     const keep = restricted?.keep ?? null;
+    // ① 先按「单元」分组（零 I/O：只看路径）。单元的成员文件**不保证**在遍历结果里连续，
+    //    必须整组一起判定，否则同一单元会被拦腰劈开（半个技能目录 / 半个会话目录）。
+    //    `considered` 保序记录，收尾按它还原改造前的文件顺序（未触发闸门时逐项一致）。
+    const considered: string[] = [];
+    const unitOrder: string[] = [];
+    const unitEntries = new Map<string, { rel: string; relPath: string }[]>();
     for (const rel of rels) {
       const relPath = this.relPathOf(rel);
       const unitId = this.unitIdOf(relPath);
       if (keep !== null && !keep.has(unitId)) continue;
       if (!unitAllowed(allow, `${this.id}:${unitId}`)) continue;
-      const data = await ctx.fs.readFile(rel);
-      files.push({ relativePath: relPath, data, contentHash: sha256Hex(data) });
+      let members = unitEntries.get(unitId);
+      if (members === undefined) {
+        members = [];
+        unitEntries.set(unitId, members);
+        unitOrder.push(unitId);
+      }
+      members.push({ rel, relPath });
+      considered.push(rel);
+    }
+
+    // ② 逐单元读取 + 累计字节闸门（审计 core-flow F-12 / sync#F-12）。超出 sectionByteLimit() 的
+    //    单元**整块**不进备份（仓库语义：单元不可拆分 —— 宁可少带，不可半带）；一旦判定该单元放不下，
+    //    它的剩余文件不再读盘（省 I/O，也不为「统计精确」多吃内存）。放不下的单元跳过后**继续尝试
+    //    后面的单元**：一个巨型会话不该把它之后的所有内容一起带走（后面的小单元仍可能入选）。
+    const limit = this.sectionByteLimit();
+    let usedBytes = 0;
+    const droppedUnits: string[] = [];
+    const keptByRel = new Map<string, FilesSection['files'][number]>();
+    for (const unitId of unitOrder) {
+      const room = limit - usedBytes;
+      const pending: { rel: string; file: FilesSection['files'][number] }[] = [];
+      let unitBytes = 0;
+      for (const member of unitEntries.get(unitId) ?? []) {
+        const data = await ctx.fs.readFile(member.rel);
+        unitBytes += data.byteLength;
+        if (unitBytes > room) break;
+        pending.push({ rel: member.rel, file: { relativePath: member.relPath, data, contentHash: sha256Hex(data) } });
+      }
+      if (unitBytes > room) {
+        droppedUnits.push(unitId);
+        continue;
+      }
+      usedBytes += unitBytes;
+      for (const p of pending) keptByRel.set(p.rel, p.file);
+    }
+    // ③ 按 ① 的顺序落盘（未触发闸门时与改造前的文件顺序逐项一致）
+    for (const rel of considered) {
+      const file = keptByRel.get(rel);
+      if (file !== undefined) files.push(file);
+    }
+    // 绝不静默：被整块剔除的单元写进告警（导出报告可见），并给出上限与实际保留量
+    if (droppedUnits.length > 0) {
+      const shown = droppedUnits.slice(0, MAX_UNITS_PER_GATE_WARNING);
+      const rest = droppedUnits.length - shown.length;
+      warnings.push(msgOf(ctx)('adapter.fileSectionByteLimit', {
+        type: this.displayName,
+        limit: formatBytes(limit),
+        kept: formatBytes(usedBytes),
+        count: String(droppedUnits.length),
+        detail: (rest > 0 ? [...shown, `(+ ${rest})`] : shown).join(', '),
+      }));
     }
     if (rels.length === 0) warnings.push(msgOf(ctx)('adapter.dirEmpty', { type: this.displayName }));
     warnings.push(...linkWarnings(msgOf(ctx), this.displayName, listing));
@@ -167,24 +271,32 @@ export abstract class FileCollectionAdapter implements ConfigAdapter<FilesSectio
     return { ok: true };
   }
 
+  /**
+   * 结构校验（5 个文件类分区共用：skills / agentPresets / agentInstructions / sessions / self）。
+   *
+   * **整段样板都接入共享骨架 `validateJsonSection`** —— t7 接入 version 守卫与形状检查收尾，t11 接入
+   * object 守卫；dataVersion 由注册表按 `this.id` 派生，等价于此前的字面量 `!== 1`
+   * （SECTION_DATA_VERSION = 1）。本类里已无手写样板。
+   *
+   * object 守卫的**文案**为什么还要参数：文件类分区历史上用的是**专用消息键**
+   * `adapter.validate.fileSection`（'文件分区数据必须是对象'，不含 `{subject}` 占位符），与骨架缺省的
+   * `adapter.validate.object` + `{subject}` 是**键**级差异 —— 第 5 参 subject 补不了它。t11 给骨架加了
+   * 可选第 6 参 `objectMessageKey`，这里传专用键：5 个分区的用户可见报错文案与改造前**逐字相同**，
+   * 同时不放任何手写样板。等价由 src/adapters/file-collection.test.ts 与 outputs/t7-equiv/ 的差分脚本钉住。
+   */
   async validate(data: FilesSection, msg: MsgFunc = zhMsg): Promise<ValidationResult> {
-    const issues: ValidationResult['issues'] = [];
-    if (data === null || typeof data !== 'object') {
-      return { valid: false, issues: [{ path: '$', message: msg('adapter.validate.fileSection'), severity: 'error' }] };
-    }
-    if (data.version !== 1) {
-      issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
-    }
-    if (!Array.isArray(data.files)) {
-      issues.push({ path: 'files', message: msg('adapter.validate.array', { subject: 'files' }), severity: 'error' });
-    } else {
-      for (const f of data.files) {
-        if (f === null || typeof f !== 'object' || typeof f.relativePath !== 'string' || f.relativePath === '') {
-          issues.push({ path: 'files[]', message: msg('adapter.validate.fileRelativePath'), severity: 'error' });
+    // 第 5 参 subject 传 this.id 即骨架缺省语义（专用键不含 {subject}，取值不影响输出）
+    return validateJsonSection<FilesSection>(this.id, data, msg, (section, issues) => {
+      if (!Array.isArray(section.files)) {
+        issues.push({ path: 'files', message: msg('adapter.validate.array', { subject: 'files' }), severity: 'error' });
+      } else {
+        for (const f of section.files) {
+          if (f === null || typeof f !== 'object' || typeof f.relativePath !== 'string' || f.relativePath === '') {
+            issues.push({ path: 'files[]', message: msg('adapter.validate.fileRelativePath'), severity: 'error' });
+          }
         }
       }
-    }
-    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+    }, this.id, 'adapter.validate.fileSection');
   }
 }
 

package/src/adapters/index.ts

@@ -7,7 +7,7 @@
  * manifest 中不出现这些 section，产品 UI 说明「DSH 当前无此配置」；
  * rules 概念已由 agentInstructions（~/.dsh/AGENTS.md）承接。
  */
-import type { ConfigAdapter, HostContext } from '../core/types.ts';
+import type { ConfigAdapter } from '../core/types.ts';
 import { SettingsAdapter, type NamespaceProvider } from './settings.ts';
 import { UiAdapter } from './ui.ts';
 import { ProvidersAdapter } from './providers.ts';
@@ -92,3 +92,14 @@ export { PluginFilesAdapter, DEFAULT_PLUGIN_FILE_WHITELIST } from './plugin-file
 export { SessionsAdapter } from './sessions.ts';
 export { SelfAdapter, SELF_CONFIG_FILES } from './self.ts';
 export { FileCollectionAdapter } from './file-collection.ts';
+/* JSON 分区共享校验骨架（本导出是其接入点）。收敛轨迹：
+ *  · t31 抽出骨架，settings / ui / providers / plugins / mcp / prompts / credentials /
+ *    pluginFiles 八个分区的样板并入；
+ *  · t7 接上 workspaces.ts 与 file-collection.ts 基类的 version 守卫 + 形状检查收尾；
+ *  · t11 给骨架加了可选第 6 参 `objectMessageKey`（object 错误的文案键，缺省
+ *    `adapter.validate.object`），file-collection 的 object 守卫也并入并沿用文件类分区原专用键
+ *    `adapter.validate.fileSection`，故 5 个文件类分区的用户可见报错文案逐字不变。
+ * 现状：**9 个分区全部走共享骨架**（settings / ui / providers / plugins / mcp / prompts /
+ * credentialsStatus / pluginFiles / workspaces），文件类基类（skills / agentPresets /
+ * agentInstructions / sessions / self）同样走它 —— src/adapters 下不再有任何手写 validate 样板。 */
+export { validateJsonSection, type SectionIssues } from './json-section.ts';

package/src/adapters/json-section.ts

@@ -0,0 +1,73 @@
+/**
+ * JSON 分区 adapter 的共享骨架（t31，批次 4）。
+ *
+ * 为什么存在：改动前 9 个「有 JSON 载荷」的分区的 `validate()` 都以**同一段样板**开头 ——
+ * 先是 object 守卫，再是 `data.version !== 1` 守卫，最后才是各分区自己的载荷形状检查；
+ * 这段样板在每个文件里逐字抄了一遍（审计 sync#F-08 / infra#C1）。本模块把它收敛为一份，
+ * 并让「期望版本」直接取自注册表 `dataVersion`（不再各写 `!== 1` 字面量）。
+ *
+ * 与注册表的分工：结构校验的**描述符**（zipPath / 载荷形态 / dataVersion）在
+ * `src/schema/section-registry.ts`；本模块只提供「按该描述符执行校验」的通用算法，
+ * 各 adapter 仍负责自己特有的形状检查（用 `shape` 回调注入）。
+ *
+ * 分层：只 import schema 与 core 的类型 —— 不 import node 内置模块（client bundle 自包含铁律）。
+ */
+import { sectionMeta } from '../schema/section-registry.ts';
+import type { SectionId } from '../schema/types.ts';
+import type { MsgFunc, zh } from '../core/messages.ts';
+import type { ValidationResult } from '../core/types.ts';
+
+/** 校验问题列表（各 adapter 的形状检查直接 push 到这里，与历史 `issues` 数组同一形状）。 */
+export type SectionIssues = ValidationResult['issues'];
+
+/**
+ * JSON 分区通用结构校验骨架。
+ *
+ * 执行顺序（与改造前逐字一致，保证行为等价）：
+ *  1. object 守卫：非对象 → **直接返回**单条 `objectMessageKey` 错误（缺省 `adapter.validate.object`；后续检查不再执行）；
+ *  2. version 守卫：`version !== sectionMeta(sectionId).dataVersion` → push 一条 `version` 错误，
+ *     **不提前返回**（继续做形状检查，与历史实现一致）；
+ *  3. `shape` 回调：分区特有的载荷形状检查（可选）。
+ *
+ * @param sectionId 分区 id —— 同时是 object 错误的默认 subject 与 dataVersion 的查表键
+ * @param data 反序列化后的分区载荷（来自不可信备份 → 必须按 unknown 处理）
+ * @param msg 文案翻译器（adapter 的 `validate(data, msg = zhMsg)` 原样传入）
+ * @param shape 分区特有的形状检查（在 version 守卫之后调用）
+ * @param subject object 错误里的显示名；缺省 = sectionId。历史上 credentials 用的是
+ *   `'credentials'`（而非分区 id `credentialsStatus`），此参数为保留该原文案而存在 ——
+ *   改文案属独立的行为变更，不在本任务射程内。
+ * @param objectMessageKey object 错误的**消息键**（t11 新增，可选）；缺省 `adapter.validate.object`
+ *   （`'{subject} 数据必须是对象'`）。为什么需要它：文件类分区历史上用的是专用键
+ *   `adapter.validate.fileSection`（`'文件分区数据必须是对象'`，**不含** `{subject}` 占位符），
+ *   那是**键**级差异 —— `subject` 参数补不了它（把 subject 拼成"文件分区"后中文模板仍多一个空格），
+ *   而硬换键会让 skills / agentPresets / agentInstructions / sessions / self 五个分区的用户可见
+ *   报错文案一起变。有了这个可选键，那处也能并入骨架而文案逐字不变。
+ *   键必须存在于 `src/core/messages.ts` 目录（`MsgFunc` 形参是 string，编译器只能校验到键名集合）。
+ */
+export function validateJsonSection<S extends { version?: unknown }>(
+  sectionId: SectionId,
+  data: unknown,
+  msg: MsgFunc,
+  shape?: (section: S, issues: SectionIssues) => void,
+  subject: string = sectionId,
+  objectMessageKey: keyof typeof zh = 'adapter.validate.object',
+): ValidationResult {
+  if (data === null || typeof data !== 'object') {
+    return {
+      valid: false,
+      issues: [{ path: '$', message: msg(objectMessageKey, { subject }), severity: 'error' }],
+    };
+  }
+  const section = data as S;
+  const issues: SectionIssues = [];
+  const expectedVersion: unknown = sectionMeta(sectionId).dataVersion;
+  if (section.version !== expectedVersion) {
+    issues.push({
+      path: 'version',
+      message: msg('adapter.validate.version', { value: String(section.version) }),
+      severity: 'error',
+    });
+  }
+  if (shape !== undefined) shape(section, issues);
+  return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+}

package/src/adapters/mcp.ts

@@ -9,7 +9,9 @@
 import { isDeepStrictEqual } from 'node:util';
 import { msgOf, zhMsg } from '../core/messages.ts';
 import type { MsgFunc } from '../core/messages.ts';
-import type { McpServerEntry, McpSection } from '../schema/types.ts';
+import type { McpServerEntry } from '../schema/types.ts';
+import { sectionMeta } from '../schema/section-registry.ts';
+import { validateJsonSection } from './json-section.ts';
 import type {
   ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
   ImportContext, PlanItem, ValidationResult,
@@ -87,9 +89,10 @@ function newLineId(serverName: string): string {
 
 export class McpAdapter implements ConfigAdapter<McpExportSection> {
   readonly id = 'mcp' as const;
-  readonly displayName = 'MCP Servers';
-  readonly defaultIncluded = true;
-  readonly portability = 'platformSpecific' as const;
+  // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
+  readonly displayName = sectionMeta('mcp').displayName;
+  readonly defaultIncluded = sectionMeta('mcp').defaultIncluded;
+  readonly portability = sectionMeta('mcp').portability;
 
   async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<McpExportSection>> {
     const warnings: string[] = [];
@@ -164,22 +167,16 @@ export class McpAdapter implements ConfigAdapter<McpExportSection> {
   }
 
   async validate(data: McpExportSection, msg: MsgFunc = zhMsg): Promise<ValidationResult> {
-    const issues: ValidationResult['issues'] = [];
-    if (data === null || typeof data !== 'object') {
-      return { valid: false, issues: [{ path: '$', message: msg('adapter.validate.object', { subject: 'mcp' }), severity: 'error' }] };
-    }
-    if (data.version !== 1) {
-      issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
-    }
-    if (!Array.isArray(data.servers)) {
-      issues.push({ path: 'servers', message: msg('adapter.validate.array', { subject: 'servers' }), severity: 'error' });
-    } else {
-      for (const s of data.servers) {
-        if (s === null || typeof s !== 'object' || typeof s.serverName !== 'string' || s.serverName === '') {
-          issues.push({ path: 'servers[]', message: msg('adapter.validate.serverName'), severity: 'error' });
+    return validateJsonSection<McpExportSection>('mcp', data, msg, (section, issues) => {
+      if (!Array.isArray(section.servers)) {
+        issues.push({ path: 'servers', message: msg('adapter.validate.array', { subject: 'servers' }), severity: 'error' });
+      } else {
+        for (const s of section.servers) {
+          if (s === null || typeof s !== 'object' || typeof s.serverName !== 'string' || s.serverName === '') {
+            issues.push({ path: 'servers[]', message: msg('adapter.validate.serverName'), severity: 'error' });
+          }
         }
       }
-    }
-    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+    });
   }
 }

package/src/adapters/plugin-files.ts

@@ -18,14 +18,17 @@ import type {
   ImportContext, PlanItem, ValidationResult,
 } from '../core/types.ts';
 import { unitAllowed, unitsFromFiles } from './units.ts';
+import { sectionMeta } from '../schema/section-registry.ts';
+import { validateJsonSection } from './json-section.ts';
 
 export const DEFAULT_PLUGIN_FILE_WHITELIST: readonly string[] = ['dsh-ssh.json', 'pet.json'];
 
 export class PluginFilesAdapter implements ConfigAdapter<FilesSection> {
   readonly id = 'pluginFiles' as const;
-  readonly displayName = 'Plugin Files';
-  readonly defaultIncluded = false;
-  readonly portability = 'deviceSpecific' as const;
+  // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
+  readonly displayName = sectionMeta('pluginFiles').displayName;
+  readonly defaultIncluded = sectionMeta('pluginFiles').defaultIncluded;
+  readonly portability = sectionMeta('pluginFiles').portability;
   private readonly whitelist: string[];
   /** 约定配置目录（相对 ~/.dsh 根，如 'plugin-config'）；递归收集其下所有文件。undefined = 不收集。 */
   private readonly collectDir?: string;
@@ -142,16 +145,10 @@ export class PluginFilesAdapter implements ConfigAdapter<FilesSection> {
   }
 
   async validate(data: FilesSection, msg: MsgFunc = zhMsg): Promise<ValidationResult> {
-    const issues: ValidationResult['issues'] = [];
-    if (data === null || typeof data !== 'object') {
-      return { valid: false, issues: [{ path: '$', message: msg('adapter.validate.object', { subject: 'pluginFiles' }), severity: 'error' }] };
-    }
-    if (data.version !== 1) {
-      issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
-    }
-    if (!Array.isArray(data.files)) {
-      issues.push({ path: 'files', message: msg('adapter.validate.array', { subject: 'files' }), severity: 'error' });
-    }
-    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+    return validateJsonSection<FilesSection>('pluginFiles', data, msg, (section, issues) => {
+      if (!Array.isArray(section.files)) {
+        issues.push({ path: 'files', message: msg('adapter.validate.array', { subject: 'files' }), severity: 'error' });
+      }
+    });
   }
 }