@logictan/dsh-config-manager 0.1.60

package/src/adapters/sessions.ts

@@ -0,0 +1,15 @@
+/**
+ * sessions 分区 adapter（默认关，设计 §3.3/§15）：
+ * 数据源 = ~/.dsh/sessions/<projectKey>/<sessionId>/…（zstd jsonl，含敏感信息）。
+ * defaultIncluded=false：Quick Export 不包含，用户显式勾选才导出（v1 文件级复制）。
+ * 研究报告 §4.9：DSH 无会话批量导出 API，逐会话文件复制是唯一通道。
+ */
+import { FileCollectionAdapter } from './file-collection.ts';
+
+export class SessionsAdapter extends FileCollectionAdapter {
+  readonly id = 'sessions' as const;
+  readonly displayName = 'Sessions';
+  readonly defaultIncluded = false;
+  readonly portability = 'deviceSpecific' as const;
+  readonly baseDir = 'sessions';
+}

package/src/adapters/settings.test.ts

@@ -0,0 +1,100 @@
+/**
+ * settings adapter 测试：非 UI namespace 导出（redact+revision）/ Create·Skip·Conflict 分析 /
+ * applyItem 乐观锁写回 / validate。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { SettingsAdapter } from './settings.ts';
+import { makeContext, makeImportContext } from './test-helpers.ts';
+import type { PlanItem } from '../core/types.ts';
+
+const NS = ['general', 'theme', 'llm-deepseek'];
+
+test('settings: 导出只含非 UI namespace（redacted + revision + secrets 标记）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  ctx.settings.ns.set('general', { value: { theme: 'dark' }, revision: 3, secrets: [] });
+  ctx.settings.ns.set('theme', { value: { mode: 'dark' }, revision: 1, secrets: [] }); // UI 类 → 排除
+  ctx.settings.ns.set('llm-deepseek', {
+    value: { apiKeyEnv: 'DEEPSEEK_API_KEY' },
+    revision: 5,
+    secrets: [{ path: ['apiKey'], set: true }],
+  });
+
+  const adapter = new SettingsAdapter(NS);
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  assert.equal(out.data.version, 1);
+  assert.ok(out.data.namespaces['general']);
+  assert.ok(out.data.namespaces['llm-deepseek']);
+  assert.ok(!out.data.namespaces['theme'], 'theme 属 UI 类，应被 settings 排除');
+  assert.equal(out.data.namespaces['llm-deepseek']?.revision, 5);
+  assert.deepEqual(out.data.namespaces['llm-deepseek']?.secrets, [{ path: ['apiKey'], set: true }]);
+  assert.equal(out.counts.namespaces, 2);
+
+  const v = await adapter.validate(out.data);
+  assert.equal(v.valid, true);
+});
+
+test('settings: analyzeImport 未注册→MissingDependency / 空→Create / 一致→Skip / 不同→Conflict + applyItem 写回（幂等）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.settings.ns.set('general', { value: { theme: 'dark' }, revision: 3, secrets: [] });
+  const adapter = new SettingsAdapter(NS);
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['settings', exported.data]]);
+
+  // 场景 A：目标命名空间未注册（缺少提供插件）→ MissingDependency（不是 Create，写入必失败）
+  const dstA = makeContext('linux', '/home/bob');
+  let items = await adapter.analyzeImport(exported.data, makeImportContext(dstA, sections));
+  assert.equal(items.length, 1);
+  assert.equal(items[0]?.kind, 'MissingDependency');
+  assert.equal(items[0]?.target?.ref, 'general');
+
+  // 场景 B：目标已注册但为空 → Create 并写入（初始化）
+  const dst = makeContext('linux', '/home/bob');
+  dst.settings.registered.add('general'); // 注册但无值
+  items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items[0]?.kind, 'Create');
+  assert.equal(items[0]?.target?.ref, 'general');
+  const r = await adapter.applyItem(items[0]!, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  assert.deepEqual(dst.settings.ns.get('general')?.value, { theme: 'dark' });
+
+  // 重复导入 → Skip（幂等）
+  items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items[0]?.kind, 'Skip');
+
+  // 目标不同 → Conflict；useImported（Update）后覆盖
+  dst.settings.ns.set('general', { value: { theme: 'light' }, revision: 9, secrets: [] });
+  items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items[0]?.kind, 'Conflict');
+  const useItem: PlanItem = { ...items[0]!, kind: 'Update' };
+  await adapter.applyItem(useItem, makeImportContext(dst, sections));
+  assert.deepEqual(dst.settings.ns.get('general')?.value, { theme: 'dark' });
+});
+
+test('settings: applyItem 读时锁 — 目标 revision 不同时仍按当前值提交（不覆盖并发修改）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.settings.ns.set('general', { value: { theme: 'dark' }, revision: 3, secrets: [] });
+  const adapter = new SettingsAdapter(NS);
+  const exported = await adapter.export(src, { includeSecrets: false });
+
+  const dst = makeContext('linux', '/home/bob');
+  dst.settings.ns.set('general', { value: { theme: 'light' }, revision: 9, secrets: [] });
+  const sections = new Map([['settings', exported.data]]);
+  const item: PlanItem = {
+    id: 'settings:general', kind: 'Update', adapter: 'settings',
+    description: '更新 general', severity: 'info',
+    target: { adapter: 'settings', ref: 'general' },
+  };
+  const r = await adapter.applyItem(item, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  assert.deepEqual(dst.settings.ns.get('general')?.value, { theme: 'dark' }, 'useImported 应覆盖目标');
+  assert.equal(dst.settings.ns.get('general')?.revision, 10, '提交后 revision 递增');
+});
+
+test('settings: validate 拒绝非法结构', async () => {
+  const adapter = new SettingsAdapter(NS);
+  const bad = await adapter.validate({ version: 2, namespaces: {} } as never);
+  assert.equal(bad.valid, false);
+  const noNs = await adapter.validate({ version: 1, namespaces: null as never });
+  assert.equal(noNs.valid, false);
+});

package/src/adapters/settings.ts

@@ -0,0 +1,187 @@
+/**
+ * settings 分区 adapter（设计 §3.3/§4.1/§4.2）：
+ * 数据源 = ~/.dsh/settings.yaml 中「非 UI 类」namespace（经 ctx.settings.describe({redactSecrets:true})）。
+ *
+ * 说明：DSH settings 服务没有「枚举全部 namespace」的 API（研究报告 §3.2），
+ * 因此 namespace 清单由宿主注入（真实实现可从 settings.yaml 顶层 key 解析）。
+ * 默认只导出名单内且不属于 UI 类（isUiNamespace）的 namespace，与 ui adapter 互斥并集 = 全部设置。
+ */
+import { isDeepStrictEqual } from 'node:util';
+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,
+  ImportContext, NamespaceInfo, PlanItem, ValidationResult,
+} from '../core/types.ts';
+import { isUiNamespace } from './ui.ts';
+
+/** namespace 清单提供者：宿主从 settings.yaml 顶层 key / 插件注册表获得 */
+export type NamespaceProvider = (ctx: HostContext) => Promise<string[]> | string[];
+
+export async function resolveNamespaces(
+  namespaces: string[] | NamespaceProvider,
+  ctx: HostContext,
+): Promise<string[]> {
+  return typeof namespaces === 'function' ? namespaces(ctx) : namespaces;
+}
+
+/** 批量读取 namespace 的 redacted 记录（settings/ui 共用；单项失败跳过并告警） */
+export async function collectNamespaceRecords(
+  ctx: HostContext,
+  names: string[],
+  warnings: string[],
+): Promise<Record<string, NamespaceRecord>> {
+  const namespaces: Record<string, NamespaceRecord> = {};
+  for (const name of names) {
+    try {
+      const info = await ctx.settings.describe(name, { redactSecrets: true });
+      namespaces[name] = {
+        value: info.value,
+        base: info.base,
+        revision: info.revision,
+        applies: info.applies,
+        secrets: info.secrets,
+      };
+    } catch (err) {
+      warnings.push(msgOf(ctx)('adapter.settingsNsReadFailed', { name, reason: err instanceof Error ? err.message : String(err) }));
+    }
+  }
+  return namespaces;
+}
+
+/** 值是否“空”（目标已注册但从未配置 → 视为待初始化，Create 而非 Conflict） */
+export function isEmptyValue(v: unknown): boolean {
+  if (v === undefined || v === null) return true;
+  if (typeof v === 'object') return Object.keys(v as Record<string, unknown>).length === 0;
+  return false;
+}
+
+/** 对比导入记录与目标当前值：不存在 → Create；一致 → Skip；不同 → Conflict；
+ * 目标端 describe 抛错（命名空间未注册：提供它的插件在目标未激活/未安装）→ MissingDependency（§15 依赖检测），
+ * 此时 Create/Update 必然失败，标记为“需注意”让导入继续，而不是整体失败。纯计算，零写入。 */
+export async function planNamespaceItems(
+  data: Record<string, NamespaceRecord>,
+  adapter: 'settings' | 'ui',
+  ctx: ImportContext,
+): Promise<PlanItem[]> {
+  const msg = ctx.msg;
+  const items: PlanItem[] = [];
+  for (const [name, rec] of Object.entries(data)) {
+    let current: NamespaceInfo | null = null;
+    let targetUnavailable = false;
+    try {
+      current = await ctx.target.settings.describe(name, { redactSecrets: true });
+    } catch {
+      // 目标连 describe 都失败 → 命名空间未注册（缺少提供插件）或目标不可读：
+      // 不能假定“不存在就创建”（replace 会同样失败），按依赖缺失处理。
+      targetUnavailable = true;
+    }
+    const id = `${adapter}:${name}`;
+    if (targetUnavailable) {
+      items.push({
+        id, kind: 'MissingDependency', adapter,
+        description: msg('adapter.settingsUnregistered', { ns: name }),
+        severity: 'warning', target: { adapter, ref: name },
+      });
+    } else if (current === null || isEmptyValue(current.value)) {
+      // 目标已注册但从未配置（空值）→ 初始化（Create）
+      items.push({
+        id, kind: 'Create', adapter, description: msg('adapter.settingsCreate', { name }), severity: 'info',
+        target: { adapter, ref: name },
+      });
+    } else if (isDeepStrictEqual(current.value, rec.value)) {
+      items.push({ id, kind: 'Skip', adapter, description: msg('adapter.settingsSame', { name }), severity: 'info' });
+    } else {
+      items.push({
+        id, kind: 'Conflict', adapter, description: msg('adapter.settingsDiff', { name }),
+        detail: `current=${JSON.stringify(current.value)} imported=${JSON.stringify(rec.value)}`.slice(0, 200),
+        severity: 'warning', target: { adapter, ref: name },
+      });
+    }
+  }
+  return items;
+}
+
+/** 写入单个 namespace（settings/ui 共用）：读时锁 + expectedRevision 乐观锁，防覆盖并发修改 */
+export async function applyNamespaceItem(
+  item: PlanItem,
+  sectionId: 'settings' | 'ui',
+  ctx: ImportContext,
+): Promise<ApplyResult> {
+  const ref = item.target?.ref;
+  if (!ref) return { ok: false, message: ctx.msg('adapter.missingTargetRef') };
+  const data = ctx.sections.get(sectionId) as { namespaces?: Record<string, NamespaceRecord> } | undefined;
+  const rec = data?.namespaces?.[ref];
+  if (!rec) return { ok: false, message: ctx.msg('adapter.namespaceMissing', { ref }) };
+  // 写入前读当前 revision 作为 expectedRevision（读时锁）：目标不存在（Create）则不带锁提交
+  let expected: number | undefined;
+  try {
+    expected = (await ctx.target.settings.describe(ref, { redactSecrets: true })).revision;
+  } catch {
+    expected = undefined;
+  }
+  await ctx.target.settings.replace(ref, rec.value, expected);
+  return { ok: true };
+}
+
+export class SettingsAdapter implements ConfigAdapter<SettingsSection> {
+  readonly id = 'settings' as const;
+  readonly displayName = 'Settings';
+  readonly defaultIncluded = true;
+  readonly portability = 'portable' as const;
+  private readonly namespaces: string[] | NamespaceProvider;
+
+  constructor(namespaces: string[] | NamespaceProvider = []) {
+    this.namespaces = namespaces;
+  }
+
+  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);
+    return {
+      sectionId: 'settings',
+      data: { version: 1, namespaces },
+      counts: { namespaces: Object.keys(namespaces).length },
+      warnings,
+    };
+  }
+
+  async analyzeImport(data: SettingsSection, ctx: ImportContext): Promise<PlanItem[]> {
+    return planNamespaceItems(data.namespaces, 'settings', ctx);
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    return applyNamespaceItem(item, 'settings', ctx);
+  }
+
+  async validate(data: SettingsSection, 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: 'settings' }), severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
+    }
+    if (data.namespaces === null || typeof data.namespaces !== 'object') {
+      issues.push({ path: 'namespaces', message: msg('adapter.validate.missingObject', { subject: 'namespaces' }), severity: 'error' });
+    } else {
+      for (const [name, rec] of Object.entries(data.namespaces)) {
+        if (rec === null || typeof rec !== 'object') {
+          issues.push({ path: `namespaces.${name}`, message: msg('adapter.validate.recordObject', { subject: 'namespace' }), severity: 'error' });
+          continue;
+        }
+        if (typeof rec.revision !== 'number') {
+          issues.push({ path: `namespaces.${name}.revision`, message: msg('adapter.validate.number', { subject: 'revision' }), severity: 'error' });
+        }
+        if (!('value' in rec)) {
+          issues.push({ path: `namespaces.${name}.value`, message: msg('adapter.validate.missingValue'), severity: 'error' });
+        }
+      }
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}

package/src/adapters/skills.ts

@@ -0,0 +1,14 @@
+/**
+ * skills 分区 adapter（设计 §3.3）：
+ * 数据源 = ~/.dsh/skills/（flat .md + 目录 bundle；dsh-skill-filesystem 发现）。
+ * 仅迁移用户主目录技能；~/.agents/skills、项目级技能默认不迁（研究报告 §2.2）。
+ */
+import { FileCollectionAdapter } from './file-collection.ts';
+
+export class SkillsAdapter extends FileCollectionAdapter {
+  readonly id = 'skills' as const;
+  readonly displayName = 'Skills';
+  readonly defaultIncluded = true;
+  readonly portability = 'portable' as const;
+  readonly baseDir = 'skills';
+}

package/src/adapters/test-helpers.ts

@@ -0,0 +1,248 @@
+/**
+ * 适配器测试基础设施（仿 src/core/smoke.test.ts 的内存 mock 门面）。
+ * 仅供 src/adapters/*.test.ts 使用，不参与生产构建语义。
+ */
+import { normalizePath } from '../utils/paths.ts';
+import { createLogger, type Logger } from '../utils/logger.ts';
+import { sha256Hex } from '../utils/hashing.ts';
+import { zhMsg } from '../core/messages.ts';
+import type {
+  CredentialsFacade, FileSystemFacade, HostContext, ImportContext, NamespaceInfo,
+  PatchFileFacade, PluginInfo, PluginsFacade, SettingsFacade, Snapshot,
+  SnapshotStore, WorkspaceFacade,
+} from '../core/types.ts';
+import type { Manifest, SectionId, WorkspaceRecord } from '../schema/types.ts';
+
+export class MemFs implements FileSystemFacade {
+  files = new Map<string, Uint8Array>();
+  /** 可选（issue #37）：详细的链接遍历。测试按需注入；缺省走 listRecursive 回退路径。 */
+  listRecursiveDetailed?: FileSystemFacade['listRecursiveDetailed'];
+  private readonly homeDir: string;
+  constructor(homeDir: string) {
+    this.homeDir = homeDir;
+  }
+  private key(p: string): string {
+    return normalizePath(p.startsWith(this.homeDir) ? p : `${this.homeDir}/${p}`);
+  }
+  async readFile(relPath: string): Promise<Uint8Array> {
+    const v = this.files.get(this.key(relPath));
+    if (v === undefined) throw new Error(`ENOENT: ${relPath}`);
+    return v;
+  }
+  async writeFile(relPath: string, data: Uint8Array): Promise<void> {
+    this.files.set(this.key(relPath), data);
+  }
+  async exists(relPath: string): Promise<boolean> {
+    return this.files.has(this.key(relPath));
+  }
+  async copy(from: string, to: string): Promise<void> {
+    const v = this.files.get(this.key(from));
+    if (v === undefined) throw new Error(`ENOENT: ${from}`);
+    this.files.set(this.key(to), v);
+  }
+  async remove(relPath: string): Promise<void> {
+    this.files.delete(this.key(relPath));
+  }
+  async listRecursive(dir: string): Promise<string[]> {
+    const base = normalizePath(this.homeDir);
+    const prefix = normalizePath(dir) === '' ? base : `${base}/${normalizePath(dir)}`;
+    const out: string[] = [];
+    for (const k of this.files.keys()) {
+      if (k === prefix || k.startsWith(prefix + '/')) {
+        out.push(k.slice(base.length).replace(/^[\\/]+/, ''));
+      }
+    }
+    return out.sort();
+  }
+  async mkdir(): Promise<void> { /* 内存实现无需建目录 */ }
+}
+
+/** ns.set 时自动注册（有值即视为对应插件已激活；对齐真实 dsh-settings 的注册语义） */
+class AutoRegisterMap extends Map<string, { value: unknown; base?: unknown; revision: number; applies?: string[]; secrets: { path: string[]; set: boolean }[] }> {
+  private readonly registered: Set<string>;
+  constructor(registered: Set<string>) {
+    super();
+    this.registered = registered;
+  }
+  override set(key: string, value: { value: unknown; base?: unknown; revision: number; applies?: string[]; secrets: { path: string[]; set: boolean }[] }): this {
+    this.registered.add(key);
+    return super.set(key, value);
+  }
+}
+
+export class MemSettings implements SettingsFacade {
+  /** 已注册命名空间（对齐真实 dsh-settings：插件激活时注册；未注册的 describe/replace 抛错） */
+  registered = new Set<string>();
+  /** 有值的命名空间自动视为已注册 */
+  ns = new AutoRegisterMap(this.registered);
+  async describe(namespace: string, _opts?: { redactSecrets?: boolean }): Promise<NamespaceInfo> {
+    if (!this.registered.has(namespace)) throw new Error(`settings namespace "${namespace}" is not registered`);
+    const rec = this.ns.get(namespace);
+    return {
+      value: rec?.value,
+      base: rec?.base,
+      revision: rec?.revision ?? 0,
+      applies: rec?.applies,
+      secrets: rec?.secrets ?? [],
+    };
+  }
+  async replace(namespace: string, value: unknown, expectedRevision?: number): Promise<void> {
+    if (!this.registered.has(namespace)) throw new Error(`settings namespace "${namespace}" is not registered`);
+    const rec = this.ns.get(namespace);
+    if (expectedRevision !== undefined && rec && rec.revision !== expectedRevision) {
+      throw new Error(`SETTINGS_CONFLICT: ${namespace} revision ${rec.revision} !== ${expectedRevision}`);
+    }
+    this.ns.set(namespace, {
+      value, revision: (rec?.revision ?? 0) + 1, secrets: rec?.secrets ?? [], base: rec?.base, applies: rec?.applies,
+    });
+  }
+  async update?(namespace: string, patch: unknown, expectedRevision?: number): Promise<void> {
+    if (!this.registered.has(namespace)) throw new Error(`settings namespace "${namespace}" is not registered`);
+    const rec = this.ns.get(namespace);
+    if (expectedRevision !== undefined && rec && rec.revision !== expectedRevision) {
+      throw new Error(`SETTINGS_CONFLICT: ${namespace} revision ${rec.revision} !== ${expectedRevision}`);
+    }
+    const merged = { ...(rec?.value as Record<string, unknown> | undefined), ...(patch as Record<string, unknown>) };
+    this.ns.set(namespace, { value: merged, revision: (rec?.revision ?? 0) + 1, secrets: rec?.secrets ?? [] });
+  }
+}
+
+export class MemCredentials implements CredentialsFacade {
+  values = new Map<string, string>();
+  async describe(ref: string): Promise<{ configured: boolean; source?: string; writable?: boolean }> {
+    const v = this.values.get(ref);
+    return { configured: v !== undefined, source: v !== undefined ? 'file' : 'env', writable: true };
+  }
+  async set(ref: string, value: string): Promise<void> { this.values.set(ref, value); }
+  async unset(ref: string): Promise<void> { this.values.delete(ref); }
+}
+
+export class MemPlugins implements PluginsFacade {
+  installed = new Map<string, PluginInfo>();
+  /** 测试钩子：install 抛错（模拟 npm ERESOLVE / 网络失败） */
+  failInstall = false;
+  /** 测试钩子：记录最近一次 install 收到的 spec（验证非 registry spec 透传） */
+  lastSpec: string | undefined;
+  async listInstalled(): Promise<PluginInfo[]> {
+    return [...this.installed.values()];
+  }
+  async install(pkg: string, spec?: string): Promise<{ needsRestart: boolean }> {
+    if (this.failInstall) throw new Error(`npm error code ERESOLVE: could not resolve ${pkg}`);
+    if (this.installed.has(pkg)) return { needsRestart: false };
+    this.lastSpec = spec;
+    this.installed.set(pkg, { name: pkg, version: '1.0.0', enabled: true, spec });
+    return { needsRestart: true };
+  }
+}
+
+export class MemWorkspace implements WorkspaceFacade {
+  records = new Map<string, WorkspaceRecord>();
+  async listRecords(): Promise<WorkspaceRecord[]> { return [...this.records.values()]; }
+  async writeRecord(r: WorkspaceRecord): Promise<void> { this.records.set(r.id, r); }
+  async removeRecord(id: string): Promise<void> { this.records.delete(id); }
+}
+
+export class MemPatch implements PatchFileFacade {
+  lines = new Map<string, { lineId: string; raw: unknown }>();
+  async readPatchLines(_file: string): Promise<{ lineId: string; raw: unknown }[]> {
+    return [...this.lines.values()];
+  }
+  async applyPatchChanges(
+    _file: string,
+    changes: { lineId: string; raw: unknown; action: 'insert' | 'update' | 'remove' }[],
+  ): Promise<void> {
+    for (const c of changes) {
+      if (c.action === 'remove') this.lines.delete(c.lineId);
+      else this.lines.set(c.lineId, { lineId: c.lineId, raw: c.raw });
+    }
+  }
+}
+
+export class MemSnapshotStore implements SnapshotStore {
+  snapshots = new Map<string, Snapshot>();
+  blobs = new Map<string, Uint8Array>();
+  async save(snapshot: Snapshot, blobs: Map<string, Uint8Array> = new Map()): Promise<string> {
+    this.snapshots.set(snapshot.id, snapshot);
+    for (const [k, v] of blobs) this.blobs.set(`${snapshot.id}/${k}`, v);
+    return snapshot.id;
+  }
+  async load(id: string): Promise<Snapshot> {
+    const s = this.snapshots.get(id);
+    if (!s) throw new Error(`snapshot not found: ${id}`);
+    return s;
+  }
+  async readBlob(id: string, blobPath: string): Promise<Uint8Array> {
+    const v = this.blobs.get(`${id}/${blobPath}`);
+    if (!v) throw new Error(`blob not found: ${id}/${blobPath}`);
+    return v;
+  }
+  async updateStatus(id: string, status: Snapshot['status']): Promise<void> {
+    const s = this.snapshots.get(id);
+    if (!s) throw new Error(`snapshot not found: ${id}`);
+    s.status = status;
+  }
+}
+
+export class MockHostContext implements HostContext {
+  platform: string;
+  arch = 'x64';
+  homeDir: string;
+  dshVersion = '0.1.0-rc.6';
+  log: Logger;
+  profile?: string;
+  settings = new MemSettings();
+  credentials = new MemCredentials();
+  plugins = new MemPlugins();
+  workspace = new MemWorkspace();
+  patchFile = new MemPatch();
+  fs: MemFs;
+  constructor(platform: string, homeDir: string, profile?: string) {
+    this.platform = platform;
+    this.homeDir = homeDir;
+    this.profile = profile;
+    this.fs = new MemFs(homeDir);
+    this.log = createLogger({ level: 'error', sink: () => {} });
+  }
+}
+
+export function makeContext(platform: string, homeDir: string, profile?: string): MockHostContext {
+  return new MockHostContext(platform, homeDir, profile);
+}
+
+/** 构造最小合法 manifest（adapter 单测用；真实 manifest 由 exporter 生成） */
+export function makeManifest(platform = 'win32'): Manifest {
+  return {
+    schemaVersion: 1,
+    exporter: { name: 'dsh-config-manager-test', version: '0.0.0' },
+    source: { dshVersion: '0.1.0-rc.6', platform: platform as Manifest['source']['platform'], arch: 'x64' },
+    exportedAt: new Date('2026-08-14T12:00:00.000Z').toISOString(),
+    sections: {
+      settings: false, ui: false, providers: false, plugins: false, mcp: false, prompts: false,
+      skills: false, agentPresets: false, agentInstructions: false, workspaces: false, pluginFiles: false,
+      credentialsStatus: false, secrets: false, sessions: false, self: false,
+    },
+    security: { containsSecrets: false, encrypted: false, encryption: null },
+  };
+}
+
+/** 构造 ImportContext（adapter 单测用；sections 键运行时即 SectionId 字符串） */
+export function makeImportContext(
+  target: HostContext,
+  sections: ReadonlyMap<string, unknown>,
+  overrides: Partial<ImportContext> = {},
+): ImportContext {
+  return {
+    manifest: makeManifest(target.platform),
+    targetPlatform: target.platform,
+    target,
+    sections: sections as Map<SectionId, unknown>,
+    pathMappings: [],
+    resolutions: {},
+    secretInputs: {},
+    log: target.log,
+    msg: zhMsg,
+    ...overrides,
+  };
+}
+
+export { sha256Hex };

package/src/adapters/ui.test.ts

@@ -0,0 +1,57 @@
+/**
+ * ui adapter 测试：UI namespace 名单切分（与 settings 互斥）、uiMigrationNotes 说明导出、写回。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { UiAdapter, isUiNamespace, UI_MIGRATION_NOTES } from './ui.ts';
+import { makeContext, makeImportContext } from './test-helpers.ts';
+
+const NS = ['general', 'theme', 'pet', 'dsh-better-sidebar', 'llm-deepseek'];
+
+test('ui: 名单识别与 settings 互斥切分', () => {
+  assert.equal(isUiNamespace('theme'), true);
+  assert.equal(isUiNamespace('pet'), true);
+  assert.equal(isUiNamespace('dsh-better-sidebar'), true);
+  assert.equal(isUiNamespace('ui-onboarding'), true);
+  assert.equal(isUiNamespace('general'), false);
+  assert.equal(isUiNamespace('llm-deepseek'), false);
+});
+
+test('ui: 导出只含 UI namespace + uiMigrationNotes（纯说明）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  ctx.settings.ns.set('general', { value: { theme: 'dark' }, revision: 3, secrets: [] });
+  ctx.settings.ns.set('theme', { value: { mode: 'dark' }, revision: 1, secrets: [] });
+  ctx.settings.ns.set('pet', { value: { position: 'bottom-right' }, revision: 2, secrets: [] });
+
+  const adapter = new UiAdapter(NS);
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  assert.equal(out.data.version, 1);
+  assert.ok(out.data.namespaces['theme']);
+  assert.ok(out.data.namespaces['pet']);
+  assert.ok(!out.data.namespaces['general'], 'general 非 UI 类，应被 ui 排除');
+  assert.equal(out.counts.namespaces, 2);
+  assert.ok(out.data.uiMigrationNotes.length >= 1);
+  assert.equal(out.data.uiMigrationNotes[0]?.migratable, false);
+  assert.equal(UI_MIGRATION_NOTES.length, out.data.uiMigrationNotes.length);
+
+  const v = await adapter.validate(out.data);
+  assert.equal(v.valid, true);
+});
+
+test('ui: analyzeImport 与 applyItem 写回', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.settings.ns.set('theme', { value: { mode: 'dark' }, revision: 1, secrets: [] });
+  const adapter = new UiAdapter(NS);
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['ui', exported.data]]);
+
+  const dst = makeContext('linux', '/home/bob');
+  dst.settings.registered.add('theme'); // 目标已注册该 UI 命名空间（空值 → Create）
+  const items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items.length, 1);
+  assert.equal(items[0]?.kind, 'Create');
+  assert.equal(items[0]?.adapter, 'ui');
+  const r = await adapter.applyItem(items[0]!, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  assert.deepEqual(dst.settings.ns.get('theme')?.value, { mode: 'dark' });
+});