dsh-config-manager 0.1.78 → 0.1.80

package/src/adapters/settings.ts

@@ -11,12 +11,13 @@ import { msgOf, zhMsg } from '../core/messages.ts';
 import type { MsgFunc } from '../core/messages.ts';
 import type { NamespaceRecord, SettingsSection } from '../schema/types.ts';
 import type {
-  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext,
   ImportContext, NamespaceInfo, PlanItem, ValidationResult,
 } from '../core/types.ts';
 import { isUiNamespace } from './ui.ts';
 import { sectionMeta } from '../schema/section-registry.ts';
 import { validateJsonSection } from './json-section.ts';
+import { pickRecord, recordUnits } from './units.ts';
 
 /** namespace 清单提供者：宿主从 settings.yaml 顶层 key / 插件注册表获得 */
 export type NamespaceProvider = (ctx: HostContext) => Promise<string[]> | string[];
@@ -175,12 +176,14 @@ export class SettingsAdapter implements ConfigAdapter<SettingsSection> {
     this.namespaces = namespaces;
   }
 
-  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<SettingsSection>> {
+  async export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<SettingsSection>> {
     const warnings: string[] = [];
     const all = await resolveNamespaces(this.namespaces, ctx);
     const nonUi = all.filter((n) => !isUiNamespace(n));
     if (nonUi.length === 0) warnings.push(msgOf(ctx)('adapter.noSettingsNamespaces'));
-    const namespaces = await collectNamespaceRecords(ctx, nonUi, warnings);
+    // 条目级白名单：未勾选的 namespace 整条不进包（勾了却全量搬 = 选择器在撒谎）
+    const collected = await collectNamespaceRecords(ctx, nonUi, warnings);
+    const namespaces = pickRecord(collected, options.includeItems?.[this.id], (ns) => this.unitId(ns));
     return {
       sectionId: 'settings',
       data: { version: 1, namespaces },
@@ -189,6 +192,16 @@ export class SettingsAdapter implements ConfigAdapter<SettingsSection> {
     };
   }
 
+  /** 单元 id：`settings:<namespace>`（同一命名空间下的唯一键） */
+  private unitId(namespace: string): string {
+    return this.id + ':' + namespace;
+  }
+
+  /** 条目级单元清单（零 I/O：输入即 export 产物）；一个 namespace = 一个单元 */
+  listUnits(section: ExportSection<SettingsSection>): ExportUnit[] {
+    return recordUnits(this.id, section.data.namespaces ?? {});
+  }
+
   async analyzeImport(data: SettingsSection, ctx: ImportContext): Promise<PlanItem[]> {
     return planNamespaceItems(data.namespaces, 'settings', ctx);
   }

package/src/adapters/skills.test.ts

@@ -0,0 +1,141 @@
+/**
+ * skills 分区：bundled 技能不参与备份（issue #102 回归测试）。
+ *
+ * 真机现象：导出把插件 registerProvider 注册、`source === 'bundled'` 的技能也写成
+ * `<name>/SKILL.md`，但技能服务只暴露 SKILL.md 文本，脚本/资源拿不到 ⇒ 备份是**残缺影子**；
+ * 导入后影子落在 `$DSH_HOME/skills` 与插件自带的同名技能争生效顺序，且不随插件升级更新。
+ *
+ * 三条硬约束（本文件钉住）：
+ *  ① 导出：service 侧 `source === 'bundled'` 不进行，其它来源照旧；
+ *  ② 导入：旧备份里的 bundled 技能在**计划阶段**降级为 Skip（不写盘、无可执行 target）；
+ *  ③ 判不出（旧宿主没有 source / 服务抛错）时按旧行为放行 —— 绝不少导入用户真正的技能。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { SkillsAdapter, isMigratableSkillSource } from './skills.ts';
+import { makeContext, makeImportContext, sha256Hex } from './test-helpers.ts';
+import type { MockHostContext } from './test-helpers.ts';
+import type { FileEntry, FilesSection } from '../schema/types.ts';
+import type { SkillDefinitionView, SkillSummaryView } from '../core/types.ts';
+
+const HOME = '/home/me';
+
+function bytes(text: string): Uint8Array {
+  return new TextEncoder().encode(text);
+}
+
+/** 注入技能服务端口：summary 列表 + 按名取定义（get 缺省返回正文可用的定义）。 */
+function withSkills(
+  ctx: MockHostContext,
+  summaries: SkillSummaryView[],
+  get?: (name: string) => Promise<SkillDefinitionView | undefined>,
+): MockHostContext {
+  ctx.skills = {
+    list: async () => summaries,
+    get: get ?? (async (name: string) => {
+      const summary = summaries.find((s) => s.name === name);
+      return summary === undefined ? undefined : { ...summary, content: `body of ${name}` };
+    }),
+  };
+  return ctx;
+}
+
+function fileEntry(relativePath: string, text: string): FileEntry {
+  const data = bytes(text);
+  return { relativePath, data, contentHash: sha256Hex(data) };
+}
+
+function skillsSection(files: FileEntry[]): FilesSection {
+  return { version: 1, files };
+}
+
+/* ------------------------------------------------------------ 判据 */
+
+test('isMigratableSkillSource：只有 bundled 不可迁移；undefined（旧宿主）必须放行', () => {
+  assert.equal(isMigratableSkillSource('bundled'), false);
+  assert.equal(isMigratableSkillSource(undefined), true, '旧宿主不报来源 —— 判成不可迁移会让技能分区恒空');
+  assert.equal(isMigratableSkillSource('user-dsh'), true);
+  assert.equal(isMigratableSkillSource('custom'), true);
+  assert.equal(isMigratableSkillSource('project-dsh'), true);
+});
+
+/* ------------------------------------------------------ 导出侧（①） */
+
+test('导出：service 侧 bundled 技能不进备份，其它来源与磁盘技能照旧（issue #102）', async () => {
+  const ctx = makeContext('win32', HOME);
+  await ctx.fs.writeFile('skills/disk-a/SKILL.md', bytes('---\nname: disk-a\ndescription: d\n---\n\nbody'));
+
+  withSkills(ctx, [
+    { name: 'disk-a', description: 'on disk source wins', source: 'user-dsh' },
+    { name: 'legit-custom', description: 'custom dir skill', source: 'custom' },
+    { name: 'diagnose-windows-sandbox-acl', description: 'bundled by a plugin', source: 'bundled' },
+  ]);
+
+  const exported = await new SkillsAdapter().export(ctx, { includeSecrets: false });
+  const rels = exported.data.files.map((f) => f.relativePath).sort();
+
+  assert.deepEqual(rels, ['disk-a/SKILL.md', 'legit-custom/SKILL.md'], 'bundled 技能必须被排除，其余两路照旧');
+  assert.ok(rels.every((r) => !r.startsWith('diagnose-windows-sandbox-acl')), 'bundled 技能不得写出任何影子文件');
+});
+
+test('导出：service 不报 source（旧宿主形态）时照旧收录，不因判据丢技能', async () => {
+  const ctx = makeContext('win32', HOME);
+  withSkills(ctx, [{ name: 'legacy-skill', description: 'no source field' }]);
+
+  const exported = await new SkillsAdapter().export(ctx, { includeSecrets: false });
+  assert.deepEqual(exported.data.files.map((f) => f.relativePath), ['legacy-skill/SKILL.md']);
+});
+
+/* ------------------------------------------------------ 导入侧（②③） */
+
+test('导入：旧备份里的 bundled 技能降级为 Skip（无可执行 target），用户技能照常 Create', async () => {
+  const dst = makeContext('win32', HOME);
+  withSkills(dst, [
+    { name: 'diagnose-windows-sandbox-acl', description: 'bundled by a plugin', source: 'bundled' },
+  ]);
+  const section = skillsSection([
+    fileEntry('diagnose-windows-sandbox-acl/SKILL.md', '---\nname: diagnose-windows-sandbox-acl\n---\n\nbody'),
+    fileEntry('my-own-skill/SKILL.md', '---\nname: my-own-skill\n---\n\nbody'),
+  ]);
+  const sections = new Map<string, unknown>([['skills', section]]);
+  const adapter = new SkillsAdapter();
+
+  const items = await adapter.analyzeImport(section, makeImportContext(dst, sections));
+  const bundled = items.find((i) => i.target?.ref === 'diagnose-windows-sandbox-acl/SKILL.md' || i.id.includes('diagnose'));
+  assert.ok(bundled !== undefined);
+  assert.equal(bundled.kind, 'Skip', 'bundled 技能在计划阶段就跳过（不写盘）');
+  assert.equal(bundled.target, undefined, '不得留下可执行的写入 target');
+  assert.equal(bundled.severity, 'info');
+  assert.match(bundled.description, /bundled/, '说明必须点名原因（插件内置提供、副本不完整）');
+
+  const own = items.find((i) => i.id.includes('my-own-skill'));
+  assert.ok(own !== undefined);
+  assert.equal(own.kind, 'Create', '用户自己的技能仍需正常导入');
+  assert.equal(own.target?.ref, 'my-own-skill/SKILL.md');
+});
+
+test('导入：技能服务列举失败时原样放行（不因判不出而少导技能）', async () => {
+  const dst = makeContext('win32', HOME);
+  dst.skills = {
+    list: async () => { throw new Error('skill service down'); },
+    get: async () => undefined,
+  };
+  const section = skillsSection([fileEntry('diagnose-windows-sandbox-acl/SKILL.md', 'x')]);
+  const sections = new Map<string, unknown>([['skills', section]]);
+
+  const items = await new SkillsAdapter().analyzeImport(section, makeImportContext(dst, sections));
+  assert.equal(items.length, 1);
+  assert.equal(items[0]?.kind, 'Create', '服务不可用 ⇒ 退回旧行为（该写就写），绝不静默丢弃');
+  assert.equal(items[0]?.target?.ref, 'diagnose-windows-sandbox-acl/SKILL.md');
+});
+
+test('导入：目标机无技能服务（旧宿主）时行为与改造前一致', async () => {
+  const dst = makeContext('win32', HOME);
+  const section = skillsSection([fileEntry('some-skill/SKILL.md', 'x')]);
+  const sections = new Map<string, unknown>([['skills', section]]);
+
+  const items = await new SkillsAdapter().analyzeImport(section, makeImportContext(dst, sections));
+  assert.equal(items.length, 1);
+  assert.equal(items[0]?.kind, 'Create');
+});

package/src/adapters/skills.ts

@@ -24,7 +24,8 @@
  */
 import path from 'node:path';
 import { FileCollectionAdapter } from './file-collection.ts';
-import type { HostContext, SkillDefinitionView } from '../core/types.ts';
+import type { HostContext, ImportContext, PlanItem, SkillDefinitionView } from '../core/types.ts';
+import type { FilesSection } from '../schema/types.ts';
 import type { RecursiveListing } from '../utils/recursive-walk.ts';
 import { sha256Hex } from '../utils/hashing.ts';
 import { isPathSafe, normalizePath } from '../utils/paths.ts';
@@ -35,6 +36,21 @@ export function skillServiceRel(name: string): string {
   return normalizePath(path.join(name, 'SKILL.md'));
 }
 
+/**
+ * 该来源的技能能否进本分区备份（issue #102）。
+ *
+ * `bundled` = 插件包 / DSH 内置目录里随插件发行的技能（宿主的 `SkillSummaryView.source`）。
+ * 技能服务端口只暴露 **SKILL.md 文本**（`ctx.skills.get()` 返回 name/description/content），
+ * 技能的 `scripts/`、模板、资源文件一律拿不到 —— 备份出来必然是**残缺影子**；导入后它还会以
+ * 同名同 rank 落在 `$DSH_HOME/skills`，跟插件自己的版本争谁生效，且不随插件升级更新。
+ * 正确姿势是「装/升级对应的插件」，不是搬 SKILL.md。
+ *
+ * `source === undefined`（旧宿主不报来源）必须当**可迁移**：否则旧宿主上一个技能都备份不到。
+ */
+export function isMigratableSkillSource(source?: string): boolean {
+  return source !== 'bundled';
+}
+
 /**
  * YAML 标量编码（issue #71 真机验收发现的缺陷修复）。
  *
@@ -168,7 +184,7 @@ export class SkillsAdapter extends FileCollectionAdapter {
     const listing = await super.listRelPaths(ctx);
     this.serviceSkills = new Map<string, SkillDefinitionView>();
     if (ctx.skills === undefined) return listing;
-    let summaries: { name: string }[];
+    let summaries: { name: string; source?: string }[];
     try {
       summaries = await ctx.skills.list();
     } catch (err) {
@@ -182,6 +198,8 @@ export class SkillsAdapter extends FileCollectionAdapter {
     for (const summary of summaries) {
       // 名字要能当路径用：DSH 的 SKILL_NAME 是 [a-z0-9-]，这里再做一道通用安全校验（拒 `..`/绝对路径）
       if (typeof summary.name !== 'string' || !isPathSafe(summary.name) || summary.name.includes('/')) continue;
+      // issue #102：bundled 技能不进备份（残缺影子，见 isMigratableSkillSource）
+      if (!isMigratableSkillSource(summary.source)) continue;
       const rel = skillServiceRel(summary.name);
       if (onDisk.has(rel)) continue; // 文件系统优先
       let definition: SkillDefinitionView | undefined;
@@ -231,4 +249,42 @@ export class SkillsAdapter extends FileCollectionAdapter {
     }
     return { data, sizeBytes: data.byteLength, contentHash: sha256Hex(data) };
   }
+
+  /**
+   * 导入侧：备份里的 bundled 技能一律跳过（issue #102）。
+   *
+   * 旧备份（本修复之前导出的）会把插件内置技能写成残缺影子，导入后落在 `$DSH_HOME/skills`，
+   * 与插件自己的同名技能争生效顺序。这里在**计划阶段**就把它们降级成 Skip（不写盘、不进
+   * 冲突收集器），并给出可理解的说明；不是静默丢弃。
+   *
+   * 目标机技能清单只查一次（`ctx.target.skills.list()`）—— 逐文件调 `get()` 会是 O(n²)；
+   * 查不到（旧宿主 / 服务抛错）就**原样放行**，绝不因为判不出而少导入用户真正的技能。
+   */
+  override async analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]> {
+    const items = await super.analyzeImport(data, ctx);
+    if (ctx.target.skills === undefined) return items;
+    let bundled: Set<string>;
+    try {
+      const summaries = await ctx.target.skills.list();
+      bundled = new Set(summaries.filter((s) => !isMigratableSkillSource(s.source)).map((s) => s.name));
+    } catch (err) {
+      ctx.log.warn(`技能服务列举失败（无法识别 bundled 技能，按旧行为导入）: ${err instanceof Error ? err.message : String(err)}`);
+      return items;
+    }
+    if (bundled.size === 0) return items;
+    return items.map((item) => {
+      if (item.kind === 'Error') return item;
+      const ref = item.target?.ref;
+      if (ref === undefined) return item;
+      const name = this.unitIdOf(ref);
+      if (!bundled.has(name)) return item;
+      return {
+        ...item,
+        kind: 'Skip' as const,
+        severity: 'info' as const,
+        target: undefined,
+        description: ctx.msg('adapter.skillBundledSkipped', { name }),
+      };
+    });
+  }
 }

package/src/adapters/ui.ts

@@ -8,12 +8,13 @@ import { zhMsg } from '../core/messages.ts';
 import type { MsgFunc } from '../core/messages.ts';
 import { engineMsg } from './messages.ts';
 import type {
-  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext,
   ImportContext, PlanItem, ValidationResult,
 } from '../core/types.ts';
 import { collectNamespaceRecords, planNamespaceItems, applyNamespaceItem, resolveNamespaces, type NamespaceProvider } from './settings.ts';
 import { sectionMeta } from '../schema/section-registry.ts';
 import { validateJsonSection } from './json-section.ts';
+import { pickRecord, recordUnits } from './units.ts';
 
 /** UI 类 namespace 前缀名单（设计 §4.1；随新插件扩展，只影响「某一 namespace 归哪一边」，不影响数据完整性） */
 export const KNOWN_UI_NAMESPACE_PREFIXES: readonly string[] = [
@@ -71,11 +72,13 @@ export class UiAdapter implements ConfigAdapter<UiSection> {
     this.namespaces = namespaces;
   }
 
-  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<UiSection>> {
+  async export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<UiSection>> {
     const warnings: string[] = [];
     const all = await resolveNamespaces(this.namespaces, ctx);
     const uiNames = all.filter((n) => isUiNamespace(n));
-    const namespaces: Record<string, NamespaceRecord> = await collectNamespaceRecords(ctx, uiNames, warnings);
+    const collected: Record<string, NamespaceRecord> = await collectNamespaceRecords(ctx, uiNames, warnings);
+    // 条目级白名单：未勾选的 namespace 整条不带走；迁移说明（纯说明、不含值）与选择无关，始终保留
+    const namespaces = pickRecord(collected, options.includeItems?.[this.id], (ns) => this.unitId(ns));
     const notes = uiMigrationNotes(ctx.msg);
     return {
       sectionId: 'ui',
@@ -85,6 +88,16 @@ export class UiAdapter implements ConfigAdapter<UiSection> {
     };
   }
 
+  /** 单元 id：`ui:<namespace>` */
+  private unitId(namespace: string): string {
+    return this.id + ':' + namespace;
+  }
+
+  /** 条目级单元清单（零 I/O）：一个 UI namespace = 一个单元 */
+  listUnits(section: ExportSection<UiSection>): ExportUnit[] {
+    return recordUnits(this.id, section.data.namespaces ?? {});
+  }
+
   async analyzeImport(data: UiSection, ctx: ImportContext): Promise<PlanItem[]> {
     return planNamespaceItems(data.namespaces, 'ui', ctx);
   }

package/src/adapters/units-entries.test.ts

@@ -0,0 +1,190 @@
+/**
+ * 条目级导出选择（Phase 2）—— JSON / 记录型分区的「一个条目 = 一个单元」契约与回归。
+ *
+ * 背景：导出选择器能否展开某一行，取决于 /export-preview 拿到的 units 是否为空
+ * （src/ui/selection-model.ts 的 sectionExpandable = units.length > 0 || unitsUnread）。
+ * mcp / skills / plugins 等文件类分区早已实现 listUnits，而 settings / ui / providers /
+ * prompts / credentialsStatus 这五个「数据型」分区此前没有 —— 用户只能整体勾选、无法逐条取舍。
+ *
+ * 这里钉住四件事（每个分区都要成立）：
+ *  1. listUnits 与 export 的键/条目**同源**（unit id 直接能被 includeItems 接受）；
+ *  2. 部分勾选时只带走被勾的那几条；
+ *  3. 空数组 = 一条都不带（不静默产出「勾了 0 条却整分区照搬」）；
+ *  4. providers 的 raw 必须随勾选收窄 —— raw 是 namespace 级快照，导入按 namespace 整体替换，
+ *     不收窄就会把「没勾的 provider」一并写回目标机（选择器撒谎）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { SettingsAdapter } from './settings.ts';
+import { UiAdapter } from './ui.ts';
+import { ProvidersAdapter } from './providers.ts';
+import { PromptsAdapter } from './prompts.ts';
+import { CredentialsAdapter } from './credentials.ts';
+import { createAdapters } from './index.ts';
+import { makeContext } from './test-helpers.ts';
+import type { ExportOptions, HostContext } from '../core/types.ts';
+
+const HOME = 'C:\\Users\\alice';
+
+/** 单分区导出：includeItems 显式给定（undefined = 全量） */
+function opts(section: string, allow: string[] | undefined): ExportOptions {
+  return allow === undefined ? { includeSecrets: false } : { includeSecrets: false, includeItems: { [section]: allow } };
+}
+
+test('settings 条目级：一个 namespace = 一个单元，勾哪条带哪条', async () => {
+  const ctx = makeContext('win32', HOME);
+  ctx.settings.ns.set('llm-pi-ai', { value: { a: 1 }, revision: 1, secrets: [] });
+  ctx.settings.ns.set('dsh-ops', { value: { b: 2 }, revision: 1, secrets: [] });
+  const adapter = new SettingsAdapter(['llm-pi-ai', 'dsh-ops']);
+
+  const full = await adapter.export(ctx, opts('settings', undefined));
+  const units = adapter.listUnits(full);
+  assert.deepEqual(units.map((u) => u.id).sort(), ['settings:dsh-ops', 'settings:llm-pi-ai']);
+  assert.deepEqual(units.map((u) => u.label).sort(), ['dsh-ops', 'llm-pi-ai']);
+  assert.ok(units.every((u) => u.sizeBytes > 0), '单元体积必须非零（选择器要显示真实体积）');
+
+  const part = await adapter.export(ctx, opts('settings', ['settings:llm-pi-ai']));
+  assert.deepEqual(Object.keys(part.data.namespaces), ['llm-pi-ai']);
+  assert.equal(part.counts?.namespaces, 1);
+
+  const none = await adapter.export(ctx, opts('settings', []));
+  assert.deepEqual(Object.keys(none.data.namespaces), [], '空数组 = 一条都不带');
+  assert.equal(none.counts?.namespaces, 0);
+});
+
+test('ui 条目级：勾选只作用于 namespace，迁移说明（纯说明）恒在', async () => {
+  const ctx = makeContext('win32', HOME);
+  ctx.settings.ns.set('pet', { value: { on: true }, revision: 1, secrets: [] });
+  ctx.settings.ns.set('theme', { value: { dark: true }, revision: 1, secrets: [] });
+  const adapter = new UiAdapter(['pet', 'theme']);
+
+  const full = await adapter.export(ctx, opts('ui', undefined));
+  assert.deepEqual(adapter.listUnits(full).map((u) => u.id).sort(), ['ui:pet', 'ui:theme']);
+
+  const none = await adapter.export(ctx, opts('ui', []));
+  assert.deepEqual(Object.keys(none.data.namespaces), []);
+  assert.ok((none.data.uiMigrationNotes?.length ?? 0) > 0, '迁移说明是提示信息，不随勾选消失');
+});
+
+test('providers 条目级：一台 provider = 一个单元，且 raw.providers 按勾选收窄', async () => {
+  const ctx = makeContext('win32', HOME);
+  ctx.settings.ns.set('llm-pi-ai', {
+    value: { providers: { p1: { baseUrl: 'u1' }, p2: { baseUrl: 'u2' } } },
+    revision: 1,
+    secrets: [],
+  });
+  const adapter = new ProvidersAdapter(['llm-pi-ai']);
+
+  const full = await adapter.export(ctx, opts('providers', undefined));
+  const units = adapter.listUnits(full);
+  assert.deepEqual(units.map((u) => u.id).sort(), ['providers:p1', 'providers:p2']);
+  assert.equal(units.find((u) => u.id === 'providers:p1')?.detail, 'llm-pi-ai', 'detail = 来源 namespace');
+  // 全量导出不得改动 raw（旧备份逐字节兼容）
+  assert.deepEqual(Object.keys(full.data.providers['p1']!.raw as Record<string, unknown>), ['providers']);
+  assert.deepEqual(Object.keys((full.data.providers['p1']!.raw as { providers: Record<string, unknown> }).providers), ['p1', 'p2']);
+
+  const part = await adapter.export(ctx, opts('providers', ['providers:p1']));
+  assert.deepEqual(Object.keys(part.data.providers), ['p1']);
+  assert.equal(part.counts?.providers, 1);
+  // 关键：未勾的 p2 不能借 raw 混进包（导入按 namespace 整体替换）
+  assert.deepEqual(
+    Object.keys((part.data.providers['p1']!.raw as { providers: Record<string, unknown> }).providers),
+    ['p1'],
+    'raw.providers 必须收窄到被勾选的 route，否则未勾的 provider 会被写回目标机',
+  );
+
+  const none = await adapter.export(ctx, opts('providers', []));
+  assert.deepEqual(part.data.providers, part.data.providers, 'sanity');
+  assert.deepEqual(Object.keys(none.data.providers), []);
+  assert.equal(none.counts?.providers, 0);
+});
+
+test('prompts 条目级：一条 persona / plan-mode 段 = 一个单元', async () => {
+  const ctx = makeContext('win32', HOME, 'desktop');
+  ctx.patchFile.lines.set('p1', {
+    lineId: 'p1',
+    raw: { id: 'p1', name: 'agent-x', config: { systemPrompt: { persona: 'be brief' } } },
+  });
+  ctx.patchFile.lines.set('p2', {
+    lineId: 'p2',
+    raw: { id: 'p2', name: 'agent-y', config: { systemPrompt: 'be verbose' } },
+  });
+  const adapter = new PromptsAdapter();
+
+  const full = await adapter.export(ctx, opts('prompts', undefined));
+  const units = adapter.listUnits(full);
+  assert.deepEqual(units.map((u) => u.id).sort(), ['prompts:prompt:p1:persona', 'prompts:prompt:p2:persona']);
+  assert.deepEqual(units.map((u) => u.detail).sort(), ['systemPrompt', 'systemPrompt']);
+
+  const part = await adapter.export(ctx, opts('prompts', ['prompts:prompt:p2:persona']));
+  assert.deepEqual(part.data.prompts.map((p) => p.id), ['prompt:p2:persona']);
+
+  const none = await adapter.export(ctx, opts('prompts', []));
+  assert.deepEqual(none.data.prompts, [], '空数组 = 一条都不带');
+});
+
+test('credentialsStatus 条目级：勾掉一条 = 少一个「需补录」项', async () => {
+  const ctx = makeContext('win32', HOME);
+  ctx.credentials.values.set('TOKEN_A', 'secret-a');
+  const adapter = new CredentialsAdapter({ refs: async () => ['TOKEN_A', 'TOKEN_B'] });
+
+  const full = await adapter.export(ctx, opts('credentialsStatus', undefined));
+  const units = adapter.listUnits(full);
+  assert.deepEqual(units.map((u) => u.id).sort(), ['credentialsStatus:TOKEN_A', 'credentialsStatus:TOKEN_B']);
+  assert.equal(units.find((u) => u.id === 'credentialsStatus:TOKEN_A')?.detail, 'configured');
+  assert.equal(units.find((u) => u.id === 'credentialsStatus:TOKEN_B')?.detail, 'missing');
+  assert.ok(units.every((u) => !JSON.stringify(u).includes('secret-a')), '单元里绝不能出现凭据值');
+
+  const part = await adapter.export(ctx, opts('credentialsStatus', ['credentialsStatus:TOKEN_B']));
+  assert.deepEqual(part.data.credentials.map((c) => c.ref), ['TOKEN_B']);
+  assert.equal(part.counts?.credentials, 1);
+
+  const none = await adapter.export(ctx, opts('credentialsStatus', []));
+  assert.deepEqual(none.data.credentials, []);
+});
+
+test('自洽性守卫：每个分区的 listUnits 所报 id 都能被自己的 export 接受', async () => {
+  const ctx = makeContext('win32', HOME);
+  ctx.settings.ns.set('llm-pi-ai', { value: { providers: { p1: {}, p2: {} } }, revision: 1, secrets: [] });
+  ctx.settings.ns.set('pet', { value: { on: true }, revision: 1, secrets: [] });
+  ctx.credentials.values.set('TOKEN_A', 'x');
+
+  // 四种 adapter 的 data 形态互不相同，统一收窄成本地结构类型（只用到 export / listUnits 两件事）
+  type UnitCase = {
+    section: string;
+    picked: (data: unknown) => number;
+    adapter: {
+      export: (c: HostContext, o: ExportOptions) => Promise<{ data: unknown }>;
+      listUnits: (s: never) => { id: string }[];
+    };
+  };
+  const cases: UnitCase[] = [
+    { adapter: new SettingsAdapter(['llm-pi-ai']), section: 'settings', picked: (d) => Object.keys((d as { namespaces: object }).namespaces).length },
+    { adapter: new UiAdapter(['pet']), section: 'ui', picked: (d) => Object.keys((d as { namespaces: object }).namespaces).length },
+    { adapter: new ProvidersAdapter(['llm-pi-ai']), section: 'providers', picked: (d) => Object.keys((d as { providers: object }).providers).length },
+    { adapter: new CredentialsAdapter({ refs: async () => ['TOKEN_A'] }), section: 'credentialsStatus', picked: (d) => (d as { credentials: unknown[] }).credentials.length },
+  ];
+  for (const c of cases) {
+    const full = await c.adapter.export(ctx, { includeSecrets: false });
+    const units = c.adapter.listUnits(full as never);
+    assert.ok(units.length > 0, c.section + ' 必须有可展开的单元');
+    for (const unit of units) {
+      const only = await c.adapter.export(ctx, { includeSecrets: false, includeItems: { [c.section]: [unit.id] } });
+      assert.equal(c.picked(only.data), 1, '勾选单元 ' + unit.id + ' 后必须恰好带出它自己');
+    }
+  }
+});
+test('全集守卫：createAdapters() 里每个分区都实现了 listUnits，且空分区返回空数组而非抛错', () => {
+  // 为什么要有这条：选择器是否可展开只看 units 是否为空。任何 adapter 漏实现 listUnits，
+  // 那个分区就退化成「只能整体勾选」—— 用户报的现象（MCP 服务器不能展开）就是这么来的。
+  const adapters = createAdapters({ includeSessions: true });
+  assert.ok(adapters.length >= 14, 'registry 至少 14 个分区，实际 ' + adapters.length);
+  for (const adapter of adapters) {
+    assert.equal(typeof adapter.listUnits, 'function', adapter.id + ' 未实现 listUnits，该分区将无法展开');
+    const empty = { sectionId: adapter.id, data: {}, counts: {}, warnings: [] } as never;
+    // 必须 call(adapter)：listUnits 内部要用 this.id，裸取方法会丢接收者（真机曾因此抛错）
+    const listUnits = adapter.listUnits as (s: never) => { id: string }[];
+    assert.deepEqual(listUnits.call(adapter, empty), [], adapter.id + ' 的空分区必须返回空数组');
+  }
+});

package/src/adapters/units.ts

@@ -76,3 +76,53 @@ export function unitsFromEntries(
     sizeBytes: agg.size,
   }));
 }
+/**
+ * JSON / 记录型分区的单元体积 = 该条目在包里的 UTF-8 字节数。
+ *
+ * 与文件类不同，这里不需要读盘：条目本身就是 export() 的产物，直接量它的序列化长度，
+ * 预览与导出因此天然同口径（同一个函数量同一个对象）。
+ */
+export function entryByteSize(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value) ?? '').byteLength;
+}
+
+/**
+ * 按单元白名单过滤条目（JSON / 记录型分区共用）。
+ *
+ * allow === undefined = 未指定 → 全量（旧调用方 / 旧备份零改动）；空数组 = 一条都不留。
+ * 与 unitAllowed 同一判据，只是作用在整批条目上。
+ */
+export function filterByUnits<T>(
+  items: readonly T[],
+  allow: readonly string[] | undefined,
+  idOf: (item: T) => string,
+): T[] {
+  if (allow === undefined) return [...items];
+  return items.filter((item) => allow.includes(idOf(item)));
+}
+/** 记录型分区的单元清单：一个顶层键 = 一个单元（零 I/O；体积 = 条目序列化长度）。 */
+export function recordUnits<V>(
+  sectionId: string,
+  record: Record<string, V>,
+  detailOf?: (value: V, key: string) => string | undefined,
+): ExportUnit[] {
+  return Object.entries(record).map(([key, value]) => {
+    const unit: ExportUnit = { id: sectionId + ':' + key, label: key, sizeBytes: entryByteSize(value) };
+    const detail = detailOf?.(value, key);
+    if (detail !== undefined && detail !== '') unit.detail = detail;
+    return unit;
+  });
+}
+
+/** 记录型分区的白名单过滤（键 → 单元 id 由 idOf 决定，与 recordUnits 同一规则）。 */
+export function pickRecord<V>(
+  record: Record<string, V>,
+  allow: readonly string[] | undefined,
+  idOf: (key: string) => string,
+): Record<string, V> {
+  const out: Record<string, V> = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (unitAllowed(allow, idOf(key))) out[key] = value;
+  }
+  return out;
+}

package/src/adapters/workspaces.ts

@@ -104,7 +104,8 @@ export class WorkspacesAdapter implements ConfigAdapter<WorkspacesSection> {
 
   /** 单元清单（零 I/O）：一条工作区记录 = 一个单元；标题缺失时退回 id。 */
   listUnits(section: ExportSection<WorkspacesSection>): ExportUnit[] {
-    return section.data.workspaces.map((rec) => ({
+    // workspaces 可能缺省（空分区 / 手写 section）：按空表处理，不抛错 —— 选择器对任何分区都会调 listUnits
+    return (section.data.workspaces ?? []).map((rec) => ({
       id: `workspace:${rec.id}`,
       label: rec.title !== undefined && rec.title !== '' ? rec.title : rec.id,
       detail: rec.path,

package/src/client/about/PluginUpdateDialog.tsx

@@ -15,7 +15,8 @@
 import { useCallback, useEffect, useState } from 'react'
 import type { TranslateNS } from '../client-types.ts'
 import type { ConfigManagerApi } from '../api.ts'
-import { Banner, Button, Spinner } from '../common/ui.tsx'
+import { Banner, Button } from '../common/ui.tsx'
+import { Skeleton } from '../common/Skeleton.tsx'
 import { Modal } from '../common/Modal.tsx'
 import { redact } from '../../security/redaction.ts'
 import { ABOUT_META } from './about-view.ts'
@@ -130,7 +131,8 @@ export function PluginUpdateDialog({
 
         {notes.kind === 'loading' && (
           <div className={css.updateNotesLoading}>
-            <Spinner label={t('about.update.dialog.loadingNotes')} />
+            {/* 更新说明是**正文块**（多段文字）：按行铺骨架，读完再决定要不要装 */}
+            <Skeleton shape="line" count={6} label={t('about.update.dialog.loadingNotes')} />
           </div>
         )}
 

package/src/client/about/ReleaseNotesDialog.tsx

@@ -12,6 +12,7 @@ import { useCallback, useEffect, useRef, useState } from 'react'
 import type { TranslateNS } from '../client-types.ts'
 import { redact } from '../../security/redaction.ts'
 import { Badge, Banner, Button, Spinner } from '../common/ui.tsx'
+import { SkeletonList } from '../common/Skeleton.tsx'
 import { Modal } from '../common/Modal.tsx'
 import { ABOUT_META } from './about-view.ts'
 import {
@@ -238,8 +239,9 @@ export function ReleaseNotesDialog({
         style={{ maxHeight: '65vh', gap: '12px' }}
       >
         {loading && (
-          <div style={{ padding: '24px 0', display: 'flex', justifyContent: 'center' }}>
-            <Spinner label={t('about.releaseNotes.loading')} />
+          <div>
+            {/* 发布说明是卡片流：按卡片铺骨架（下一屏是否还有内容，看形状就知道） */}
+            <SkeletonList count={2} label={t('about.releaseNotes.loading')} />
           </div>
         )}
 

package/src/client/chat/RollbackReviewDialog.tsx

@@ -40,7 +40,8 @@ import type {
   RollbackPreviewResult,
   RollbackRewindResult,
 } from '../../ui/rollback-view.ts'
-import { Badge, Banner, Button, Checkbox, Empty, Spinner } from '../common/ui.tsx'
+import { Badge, Banner, Button, Checkbox, Empty } from '../common/ui.tsx'
+import { SkeletonList } from '../common/Skeleton.tsx'
 import type { RollbackFileIconRenderer } from './RollbackFileIcon.tsx'
 import { RollbackDiffPane, type RollbackDiffState } from '../recovery/RollbackDiffPane.tsx'
 import { RollbackFileChanges } from '../recovery/RollbackFileChanges.tsx'
@@ -379,7 +380,7 @@ export function RollbackReviewDialog({ sessionId, turn, port, rt, t, openChildSe
           </div>
 
           <div className={`${css.dialogBody} ${css.dialogBodyScroll}`}>
-            {state === 'loading' && <Spinner label={t('chat.entry.loading')} />}
+            {state === 'loading' && <SkeletonList count={3} label={t('chat.entry.loading')} />}
 
             {state === 'nopoint' && <Empty>{t('chat.entry.noPoint')}</Empty>}