dsh-config-manager 0.1.0

package/src/adapters/settings.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 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(`设置 namespace ${name} 读取失败: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return namespaces;
+}
+
+/** 对比导入记录与目标当前值：不存在 → Create；一致 → Skip；不同 → Conflict（纯计算，零写入） */
+export async function planNamespaceItems(
+  data: Record<string, NamespaceRecord>,
+  adapter: 'settings' | 'ui',
+  ctx: ImportContext,
+): Promise<PlanItem[]> {
+  const items: PlanItem[] = [];
+  for (const [name, rec] of Object.entries(data)) {
+    let current: NamespaceInfo | null = null;
+    try {
+      current = await ctx.target.settings.describe(name, { redactSecrets: true });
+    } catch {
+      current = null;
+    }
+    const id = `${adapter}:${name}`;
+    if (current === null) {
+      items.push({
+        id, kind: 'Create', adapter, description: `创建设置 ${name}`, severity: 'info',
+        target: { adapter, ref: name },
+      });
+    } else if (isDeepStrictEqual(current.value, rec.value)) {
+      items.push({ id, kind: 'Skip', adapter, description: `设置 ${name} 已一致`, severity: 'info' });
+    } else {
+      items.push({
+        id, kind: 'Conflict', adapter, description: `设置 ${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: '缺少 target.ref' };
+  const data = ctx.sections.get(sectionId) as { namespaces?: Record<string, NamespaceRecord> } | undefined;
+  const rec = data?.namespaces?.[ref];
+  if (!rec) return { ok: false, message: `导入数据缺少 namespace ${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('未配置 settings namespace 清单，settings 分区为空');
+    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): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: 'settings 数据必须是对象', severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: `version 必须为 1（收到 ${String(data.version)}）`, severity: 'error' });
+    }
+    if (data.namespaces === null || typeof data.namespaces !== 'object') {
+      issues.push({ path: 'namespaces', message: '缺少 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: 'namespace 记录必须是对象', severity: 'error' });
+          continue;
+        }
+        if (typeof rec.revision !== 'number') {
+          issues.push({ path: `namespaces.${name}.revision`, message: 'revision 必须是数字', severity: 'error' });
+        }
+        if (!('value' in rec)) {
+          issues.push({ path: `namespaces.${name}.value`, message: '缺少 value', 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,207 @@
+/**
+ * 适配器测试基础设施（仿 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 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>();
+  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> { /* 内存实现无需建目录 */ }
+}
+
+export class MemSettings implements SettingsFacade {
+  ns = new Map<string, { value: unknown; base?: unknown; revision: number; applies?: string[]; secrets: { path: string[]; set: boolean }[] }>();
+  async describe(namespace: string, _opts?: { redactSecrets?: boolean }): Promise<NamespaceInfo> {
+    const rec = this.ns.get(namespace);
+    if (!rec) throw new Error(`namespace not found: ${namespace}`);
+    return { value: rec.value, base: rec.base, revision: rec.revision, applies: rec.applies, secrets: rec.secrets };
+  }
+  async replace(namespace: string, value: unknown, expectedRevision?: number): Promise<void> {
+    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> {
+    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>();
+  async listInstalled(): Promise<PluginInfo[]> {
+    return [...this.installed.values()];
+  }
+  async install(pkg: string): Promise<{ needsRestart: boolean }> {
+    if (this.installed.has(pkg)) return { needsRestart: false };
+    this.installed.set(pkg, { name: pkg, version: '1.0.0', enabled: true });
+    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;
+  }
+}
+
+export class MockHostContext implements HostContext {
+  platform: string;
+  arch = 'x64';
+  homeDir: string;
+  dshVersion = '0.1.0-rc.6';
+  log: Logger;
+  settings = new MemSettings();
+  credentials = new MemCredentials();
+  plugins = new MemPlugins();
+  workspace = new MemWorkspace();
+  patchFile = new MemPatch();
+  fs: MemFs;
+  constructor(platform: string, homeDir: string) {
+    this.platform = platform;
+    this.homeDir = homeDir;
+    this.fs = new MemFs(homeDir);
+    this.log = createLogger({ level: 'error', sink: () => {} });
+  }
+}
+
+export function makeContext(platform: string, homeDir: string): MockHostContext {
+  return new MockHostContext(platform, homeDir);
+}
+
+/** 构造最小合法 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, workspaces: false, pluginFiles: false,
+      credentialsStatus: false, secrets: false, sessions: 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,
+    ...overrides,
+  };
+}
+
+export { sha256Hex };

package/src/adapters/ui.test.ts

@@ -0,0 +1,56 @@
+/**
+ * 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');
+  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' });
+});

package/src/adapters/ui.ts

@@ -0,0 +1,106 @@
+/**
+ * ui 分区 adapter（设计 §3.3/§4.1/§4.3）：
+ * 数据源 = settings.yaml 中「UI 类」namespace（pet / dsh-better-sidebar / remote-web-ui / ui-onboarding / skin 等）。
+ * localStorage 等 Host 不可迁移的 UI 状态以 uiMigrationNotes 纯说明形式导出（不含任何值）。
+ */
+import type { NamespaceRecord, UiSection } from '../schema/types.ts';
+import type {
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ImportContext, PlanItem, ValidationResult,
+} from '../core/types.ts';
+import { collectNamespaceRecords, planNamespaceItems, applyNamespaceItem, resolveNamespaces, type NamespaceProvider } from './settings.ts';
+
+/** UI 类 namespace 前缀名单（设计 §4.1；随新插件扩展，只影响「某一 namespace 归哪一边」，不影响数据完整性） */
+export const KNOWN_UI_NAMESPACE_PREFIXES: readonly string[] = [
+  'pet',
+  'dsh-better-sidebar',
+  'remote-web-ui',
+  'ui-onboarding',
+  'dsh-client-ui',
+  'skin',
+  'theme',
+  'layout',
+  'sidebar',
+  'appearance',
+];
+
+/** namespace 名是否属于 UI 类（大小写不敏感前缀匹配） */
+export function isUiNamespace(name: string): boolean {
+  const lower = name.toLowerCase();
+  return KNOWN_UI_NAMESPACE_PREFIXES.some((p) => lower.startsWith(p.toLowerCase()));
+}
+
+/** localStorage 等 Host 无通道的 UI 状态说明（纯说明，不含值；研究报告 §2.2/§4.4） */
+export const UI_MIGRATION_NOTES: UiSection['uiMigrationNotes'] = [
+  {
+    plugin: 'dsh-task-board',
+    storage: 'localStorage',
+    key: 'dsh.taskBoard.v1',
+    migratable: false,
+    reason: '任务看板数据存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
+  },
+  {
+    plugin: 'dsh-aionui-panel',
+    storage: 'localStorage',
+    key: 'aionui-panel.*',
+    migratable: false,
+    reason: '面板宽度/折叠状态存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
+  },
+  {
+    plugin: 'dsh-client-ui-*',
+    storage: 'localStorage',
+    key: '*',
+    migratable: false,
+    reason: '浏览器端 UI 状态无法经 Host API 迁移',
+  },
+];
+
+export class UiAdapter implements ConfigAdapter<UiSection> {
+  readonly id = 'ui' as const;
+  readonly displayName = 'UI Preferences';
+  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<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);
+    return {
+      sectionId: 'ui',
+      data: { version: 1, namespaces, uiMigrationNotes: UI_MIGRATION_NOTES },
+      counts: { namespaces: Object.keys(namespaces).length, notes: UI_MIGRATION_NOTES.length },
+      warnings,
+    };
+  }
+
+  async analyzeImport(data: UiSection, ctx: ImportContext): Promise<PlanItem[]> {
+    return planNamespaceItems(data.namespaces, 'ui', ctx);
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    return applyNamespaceItem(item, 'ui', ctx);
+  }
+
+  async validate(data: UiSection): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: 'ui 数据必须是对象', severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: `version 必须为 1（收到 ${String(data.version)}）`, severity: 'error' });
+    }
+    if (data.namespaces === null || typeof data.namespaces !== 'object') {
+      issues.push({ path: 'namespaces', message: '缺少 namespaces 对象', severity: 'error' });
+    }
+    if (data.uiMigrationNotes !== undefined && !Array.isArray(data.uiMigrationNotes)) {
+      issues.push({ path: 'uiMigrationNotes', message: 'uiMigrationNotes 必须是数组', severity: 'error' });
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}

package/src/adapters/workspaces.test.ts

@@ -0,0 +1,79 @@
+/**
+ * workspaces adapter 测试：绝对路径导出、Create/Skip/Conflict + PathMapping 项、
+ * applyItem 写 record（PathMapper 先行后的映射数据）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { WorkspacesAdapter } from './workspaces.ts';
+import { makeContext, makeImportContext } from './test-helpers.ts';
+import { applyPrefixMappings } from '../utils/paths.ts';
+import type { WorkspacesSection } from '../schema/types.ts';
+import type { PlanItem } from '../core/types.ts';
+
+test('workspaces: 导出 records（含绝对路径）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  ctx.workspace.records.set('ws-ops', {
+    id: 'ws-ops', path: 'C:\\Users\\alice\\projects\\ops', title: 'OpsFlow', sessionIds: [],
+  });
+  const adapter = new WorkspacesAdapter();
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  assert.equal(out.data.workspaces.length, 1);
+  assert.equal(out.data.workspaces[0]?.path, 'C:\\Users\\alice\\projects\\ops');
+  assert.equal(out.counts.workspaces, 1);
+  const v = await adapter.validate(out.data);
+  assert.equal(v.valid, true);
+});
+
+test('workspaces: analyzeImport 生成 Create + PathMapping（绝对路径）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.workspace.records.set('ws-ops', {
+    id: 'ws-ops', path: 'C:\\Users\\alice\\projects\\ops', title: 'OpsFlow', sessionIds: [],
+  });
+  const adapter = new WorkspacesAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['workspaces', exported.data]]);
+
+  const dst = makeContext('linux', '/home/bob');
+  const items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items.length, 2);
+  const create = items.find((i) => i.id === 'workspace:ws-ops');
+  const pathItem = items.find((i) => i.id === 'workspace:ws-ops:path');
+  assert.equal(create?.kind, 'Create');
+  assert.equal(pathItem?.kind, 'PathMapping');
+  assert.deepEqual(pathItem?.pathMapping?.appliesTo, ['workspaces']);
+  assert.equal(pathItem?.pathMapping?.oldPrefix, 'C:\\Users\\alice\\projects\\ops');
+});
+
+test('workspaces: applyItem 写入映射后数据（PathMapper 先行）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.workspace.records.set('ws-ops', {
+    id: 'ws-ops', path: 'C:\\Users\\alice\\projects\\ops', title: 'OpsFlow', sessionIds: [],
+  });
+  const adapter = new WorkspacesAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+
+  // 模拟 PathMapper：把映射应用到 sections
+  const mappedData = applyPrefixMappings(exported.data, [
+    { oldPrefix: 'C:\\Users\\alice', newPrefix: '/home/bob', appliesTo: ['workspaces'] },
+  ]) as WorkspacesSection;
+  assert.equal(mappedData.workspaces[0]?.path, '/home/bob/projects/ops');
+
+  const sections = new Map([['workspaces', mappedData]]);
+  const dst = makeContext('linux', '/home/bob');
+  const items = await adapter.analyzeImport(mappedData, makeImportContext(dst, sections));
+  const create = items.find((i) => i.id === 'workspace:ws-ops') as PlanItem;
+  const r = await adapter.applyItem(create, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  const rec = dst.workspace.records.get('ws-ops');
+  assert.ok(rec);
+  assert.equal(rec.path, '/home/bob/projects/ops', '写入的是映射后路径');
+
+  // PathMapping 项 applyItem 无副作用
+  const pathItem = items.find((i) => i.id === 'workspace:ws-ops:path') as PlanItem;
+  const r2 = await adapter.applyItem(pathItem, makeImportContext(dst, sections));
+  assert.equal(r2.ok, true);
+
+  // 幂等
+  const items2 = await adapter.analyzeImport(mappedData, makeImportContext(dst, sections));
+  assert.equal(items2.find((i) => i.id === 'workspace:ws-ops')?.kind, 'Skip');
+});