dsh-config-manager 0.1.0

package/src/adapters/providers.test.ts

@@ -0,0 +1,125 @@
+/**
+ * providers adapter 测试：llm-deepseek（单 provider）与 llm-pi-ai（多 provider）导出、
+ * Create/Skip/Conflict 分析、整体 namespace 写回（raw + 乐观锁）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ProvidersAdapter } from './providers.ts';
+import { createSecretScanner } from '../security/secret-scanner.ts';
+import { makeContext, makeImportContext } from './test-helpers.ts';
+import type { PlanItem } from '../core/types.ts';
+
+test('providers: 导出单/多 provider section（含 revision 与 raw）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  ctx.settings.ns.set('llm-deepseek', {
+    value: { apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://api.deepseek.com', model: 'deepseek-chat', apiKey: 'sk-secret' },
+    revision: 5,
+    secrets: [{ path: ['apiKey'], set: true }],
+  });
+  ctx.settings.ns.set('llm-pi-ai', {
+    value: {
+      providers: {
+        openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://api.openai.com', models: ['gpt-4o'] },
+        local: { apiKeyEnv: 'LOCAL_KEY', baseURL: 'http://127.0.0.1:11434' },
+      },
+    },
+    revision: 2,
+    secrets: [],
+  });
+
+  const adapter = new ProvidersAdapter();
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  assert.equal(out.data.version, 1);
+  const routes = Object.keys(out.data.providers).sort();
+  assert.deepEqual(routes, ['llm-deepseek', 'local', 'openai']);
+  const deepseek = out.data.providers['llm-deepseek'];
+  assert.equal(deepseek?.namespace, 'llm-deepseek');
+  assert.equal(deepseek?.revision, 5);
+  assert.equal(deepseek?.apiKeyEnv, 'DEEPSEEK_API_KEY');
+  assert.ok(deepseek?.raw, 'raw 保存完整 redacted namespace 值');
+  const openai = out.data.providers['openai'];
+  assert.equal(openai?.namespace, 'llm-pi-ai');
+  assert.equal(openai?.baseURL, 'https://api.openai.com');
+  assert.equal(out.counts.providers, 3);
+
+  const v = await adapter.validate(out.data);
+  assert.equal(v.valid, true);
+});
+
+test('providers: analyzeImport Create/Skip/Conflict + applyItem 写回整个 namespace', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.settings.ns.set('llm-pi-ai', {
+    value: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://api.openai.com' } } },
+    revision: 2,
+    secrets: [],
+  });
+  const adapter = new ProvidersAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['providers', exported.data]]);
+
+  const dst = makeContext('linux', '/home/bob');
+  let items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items.length, 1);
+  assert.equal(items[0]?.kind, 'Create');
+  assert.equal(items[0]?.id, 'provider:openai');
+  assert.equal(items[0]?.target?.ref, 'llm-pi-ai', '快照定位 namespace');
+  let r = await adapter.applyItem(items[0]!, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  assert.deepEqual(dst.settings.ns.get('llm-pi-ai')?.value, { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://api.openai.com' } } });
+
+  // 幂等：一致 → Skip
+  items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items[0]?.kind, 'Skip');
+
+  // 目标不同 → Conflict；useImported 覆盖
+  dst.settings.ns.set('llm-pi-ai', {
+    value: { providers: { openai: { apiKeyEnv: 'OTHER_KEY', baseURL: 'https://other.example.com' } } },
+    revision: 8,
+    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('llm-pi-ai')?.value, { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://api.openai.com' } } });
+});
+
+test('providers: validate 拒绝缺 namespace/revision 的记录', async () => {
+  const adapter = new ProvidersAdapter();
+  const bad = await adapter.validate({ version: 1, providers: { x: { route: 'x' } as never } });
+  assert.equal(bad.valid, false);
+});
+
+test('providers: 多 route 共享 secrets 引用不触发强化 scanner 循环误报（m4 createSecretScanner）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  ctx.settings.ns.set('llm-pi-ai', {
+    value: {
+      providers: {
+        openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://api.openai.com', models: ['gpt-4o'], apiKey: 'sk-openai-123' },
+        local: { apiKeyEnv: 'LOCAL_KEY', baseURL: 'http://127.0.0.1:11434', token: 'local-token-456' },
+      },
+    },
+    revision: 2,
+    secrets: [{ path: ['apiKey'], set: true }],
+  });
+  const adapter = new ProvidersAdapter();
+  const exported = await adapter.export(ctx, { includeSecrets: false });
+  assert.equal(Object.keys(exported.data.providers).length, 2);
+
+  // 隔离断言：route 间 secrets / raw 必须独立引用（共享引用会被 visited 循环检测误判）
+  const openai = exported.data.providers['openai'];
+  const local = exported.data.providers['local'];
+  assert.notStrictEqual(openai?.secrets, local?.secrets, 'route 间 secrets 数组必须独立');
+  assert.notStrictEqual(openai?.raw, local?.raw, 'route 间 raw 必须独立');
+
+  // m4 强化版 scanner 扫描导出数据：不得抛「检测到循环引用」，且敏感字段被剥离
+  const scanner = createSecretScanner();
+  let scanned: { sanitized: unknown; hits: import('../core/types.ts').SensitiveHit[] };
+  assert.doesNotThrow(() => { scanned = scanner.scanAndRedact(exported.data); }, '共享引用不得被误判为循环');
+  assert.ok(scanned!.hits.length >= 2, `apiKey/token 字段应被剥离（实际 ${scanned!.hits.length}）`);
+  const sanitizedProviders = (scanned!.sanitized as { providers: Record<string, Record<string, unknown>> }).providers;
+  assert.equal(sanitizedProviders['openai']?.['apiKey'], '', 'apiKey 值剥离');
+  assert.equal(sanitizedProviders['local']?.['token'], '', 'token 值剥离');
+  assert.equal(sanitizedProviders['openai']?.['apiKeyEnv'], 'OPENAI_API_KEY', '引用字段 apiKeyEnv 保留');
+  assert.equal(sanitizedProviders['openai']?.['baseURL'], 'https://api.openai.com', '非敏感字段保留');
+});

package/src/adapters/providers.ts

@@ -0,0 +1,161 @@
+/**
+ * providers 分区 adapter（设计 §3.3/§13.1）：
+ * 数据源 = settings.yaml 的 llm-deepseek / llm-pi-ai section（providers 与 models 天然同 section，不拆文件）。
+ *
+ * 导入走 settings 写通道（replace llm-* namespace + 乐观锁）：
+ * 每项携带 raw（该 namespace 的完整 redacted 值）用于整体写回，apiKey 值经 credentials 状态占位（不导出值）。
+ */
+import { isDeepStrictEqual } from 'node:util';
+import type { ProviderEntry } from '../schema/types.ts';
+import type {
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ImportContext, NamespaceInfo, PlanItem, ValidationResult,
+} from '../core/types.ts';
+import { resolveNamespaces, type NamespaceProvider } from './settings.ts';
+
+/** 导出记录：ProviderEntry 之外附加 namespace 级元数据（导入写回用），满足 ProvidersSection 形状 */
+export interface ProviderExportEntry extends ProviderEntry {
+  /** 来源 settings namespace（llm-deepseek / llm-pi-ai） */
+  namespace: string;
+  /** 乐观锁 revision（导入时检测并发修改） */
+  revision: number;
+  secrets?: { path: string[]; set: boolean }[];
+  /** 该 namespace 的完整 redacted 值（导入整体写回，避免按字段重建丢失结构） */
+  raw?: Record<string, unknown>;
+}
+
+export interface ProviderExportSection { version: 1; providers: Record<string, ProviderExportEntry>; }
+
+export const DEFAULT_PROVIDER_NAMESPACES: readonly string[] = ['llm-deepseek', 'llm-pi-ai'];
+
+/** 无 raw 时的兜底重建：只取 ProviderEntry 已知字段 */
+function stripEntry(entry: ProviderExportEntry): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of ['apiKeyEnv', 'displayName', 'baseURL', 'models', 'modelOverrides', 'reasoning', 'transport', 'retryPolicy'] as const) {
+    if (entry[key] !== undefined) out[key] = entry[key];
+  }
+  return out;
+}
+
+export class ProvidersAdapter implements ConfigAdapter<ProviderExportSection> {
+  readonly id = 'providers' as const;
+  readonly displayName = 'Providers & Models';
+  readonly defaultIncluded = true;
+  readonly portability = 'portable' as const;
+  private readonly namespaces: string[] | NamespaceProvider;
+
+  constructor(namespaces: string[] | NamespaceProvider = DEFAULT_PROVIDER_NAMESPACES as unknown as string[]) {
+    this.namespaces = namespaces;
+  }
+
+  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<ProviderExportSection>> {
+    const providers: Record<string, ProviderExportEntry> = {};
+    const warnings: string[] = [];
+    for (const ns of await resolveNamespaces(this.namespaces, ctx)) {
+      let info: NamespaceInfo;
+      try {
+        info = await ctx.settings.describe(ns, { redactSecrets: true });
+      } catch (err) {
+        warnings.push(`provider namespace ${ns} 读取失败（可能未配置）: ${err instanceof Error ? err.message : String(err)}`);
+        continue;
+      }
+      const value = (info.value ?? {}) as Record<string, unknown>;
+      // llm-pi-ai 形态：value.providers = { route: {...} }；llm-deepseek 形态：value 即单 provider 配置
+      const routes: [string, unknown][] =
+        value.providers !== null && typeof value.providers === 'object'
+          ? Object.entries(value.providers as Record<string, unknown>)
+          : [[ns, value]];
+      for (const [route, pv] of routes) {
+        // 每个 route 独立深拷贝 secrets / pv / raw：同一 namespace 的多 route 若共享引用，
+        // m4 强化版 createSecretScanner 的 visited 循环检测会误判「检测到循环引用」（见 providers.test.ts）。
+        providers[route] = {
+          route,
+          namespace: ns,
+          revision: info.revision,
+          secrets: structuredClone(info.secrets),
+          ...structuredClone(pv as Record<string, unknown>),
+          raw: structuredClone(value),
+        };
+      }
+    }
+    return {
+      sectionId: 'providers',
+      data: { version: 1, providers },
+      counts: { providers: Object.keys(providers).length },
+      warnings,
+    };
+  }
+
+  async analyzeImport(data: ProviderExportSection, ctx: ImportContext): Promise<PlanItem[]> {
+    const items: PlanItem[] = [];
+    for (const [route, entry] of Object.entries(data.providers)) {
+      const id = `provider:${route}`;
+      let current: NamespaceInfo | null = null;
+      try {
+        current = await ctx.target.settings.describe(entry.namespace, { redactSecrets: true });
+      } catch {
+        current = null;
+      }
+      if (current === null) {
+        items.push({
+          id, kind: 'Create', adapter: 'providers',
+          description: `创建 Provider ${route}（namespace ${entry.namespace}）`, severity: 'info',
+          target: { adapter: 'providers', ref: entry.namespace },
+        });
+      } else if (isDeepStrictEqual(current.value, entry.raw ?? stripEntry(entry))) {
+        items.push({ id, kind: 'Skip', adapter: 'providers', description: `Provider ${route} 已一致`, severity: 'info' });
+      } else {
+        items.push({
+          id, kind: 'Conflict', adapter: 'providers',
+          description: `Provider ${route} 与目标不同`,
+          detail: `namespace=${entry.namespace} current=${JSON.stringify(current.value)} imported=${JSON.stringify(entry.raw ?? stripEntry(entry))}`.slice(0, 200),
+          severity: 'warning', target: { adapter: 'providers', ref: entry.namespace },
+        });
+      }
+    }
+    return items;
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    const route = item.id.replace(/^provider:/, '');
+    const data = ctx.sections.get('providers') as ProviderExportSection | undefined;
+    const entry = data?.providers[route];
+    if (!entry) return { ok: false, message: `导入数据缺少 provider ${route}` };
+    const value = entry.raw ?? stripEntry(entry);
+    let expected: number | undefined;
+    try {
+      expected = (await ctx.target.settings.describe(entry.namespace, { redactSecrets: true })).revision;
+    } catch {
+      expected = undefined; // 目标 namespace 不存在（Create）
+    }
+    await ctx.target.settings.replace(entry.namespace, value, expected);
+    return { ok: true };
+  }
+
+  async validate(data: ProviderExportSection): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: 'providers 数据必须是对象', severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: `version 必须为 1（收到 ${String(data.version)}）`, severity: 'error' });
+    }
+    if (data.providers === null || typeof data.providers !== 'object') {
+      issues.push({ path: 'providers', message: '缺少 providers 对象', severity: 'error' });
+    } else {
+      for (const [route, entry] of Object.entries(data.providers)) {
+        if (entry === null || typeof entry !== 'object') {
+          issues.push({ path: `providers.${route}`, message: 'provider 记录必须是对象', severity: 'error' });
+          continue;
+        }
+        if (typeof entry.namespace !== 'string' || entry.namespace === '') {
+          issues.push({ path: `providers.${route}.namespace`, message: '缺少来源 namespace', severity: 'error' });
+        }
+        if (typeof entry.revision !== 'number') {
+          issues.push({ path: `providers.${route}.revision`, message: 'revision 必须是数字', severity: 'error' });
+        }
+      }
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}

package/src/adapters/roundtrip.test.ts

@@ -0,0 +1,188 @@
+/**
+ * 适配器集成往返测试：真实 adapter 列表（createAdapters）+ 核心引擎
+ * Exporter → ZIP → Importer（win32 → linux），验证：
+ *  - 全分区导出、Secret 值不进入 ZIP、路径映射、凭据补录报告、
+ *  - MCP/插件写 patch 的 needsRestart、重复导入幂等。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { Exporter } from '../core/exporter.ts';
+import { Importer } from '../core/importer.ts';
+import { parseZip } from '../utils/zip.ts';
+import { normalizePath } from '../utils/paths.ts';
+import { createAdapters } from './index.ts';
+import { makeContext, MemSnapshotStore, type MockHostContext } from './test-helpers.ts';
+
+const NS = ['general', 'theme', 'llm-deepseek', 'llm-pi-ai'];
+
+async function seedSource(ctx: MockHostContext): Promise<void> {
+  ctx.settings.ns.set('general', { value: { theme: 'dark', language: 'zh-CN' }, revision: 3, secrets: [] });
+  ctx.settings.ns.set('theme', { value: { mode: 'dark' }, revision: 1, secrets: [] });
+  ctx.settings.ns.set('llm-deepseek', {
+    value: { apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://api.deepseek.com', model: 'deepseek-chat', apiKey: 'sk-super-secret-value-123' },
+    revision: 5,
+    secrets: [{ path: ['apiKey'], set: true }],
+  });
+  ctx.settings.ns.set('llm-pi-ai', {
+    value: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://api.openai.com', models: ['gpt-4o'] } } },
+    revision: 2,
+    secrets: [],
+  });
+  ctx.credentials.values.set('DEEPSEEK_API_KEY', 'sk-super-secret-value-123');
+  ctx.credentials.values.set('OPENAI_API_KEY', 'sk-openai-456');
+
+  await ctx.fs.writeFile('skills/coding.md', Buffer.from('# Coding skill\nUse deepseek.\n', 'utf8'));
+  await ctx.fs.writeFile('.agent-presets/work/agent.cordis.yml', Buffer.from('services:\n  - name: work\n', 'utf8'));
+  await ctx.fs.writeFile('dsh-ssh.json', Buffer.from('{"hosts":[]}', 'utf8'));
+
+  ctx.workspace.records.set('ws-ops', {
+    id: 'ws-ops', path: 'C:\\Users\\alice\\projects\\ops', title: 'OpsFlow', sessionIds: [],
+  });
+  ctx.patchFile.lines.set('mcp-fs', {
+    lineId: 'mcp-fs',
+    raw: { id: 'mcp-fs', name: 'dsh-mcp-client', config: { serverName: 'filesystem', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem'], cwd: 'C:\\Users\\alice\\projects' } },
+  });
+  ctx.patchFile.lines.set('persona-line', {
+    lineId: 'persona-line',
+    raw: { id: 'persona-line', name: '@deepseek-ai/dsh-web', config: { systemPrompt: { persona: 'You are a helpful assistant.' } } },
+  });
+}
+
+test('集成往返：win32 → linux（路径映射 + Secret 不泄 + 补录报告 + needsRestart + 幂等）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-adapters-'));
+  try {
+    const src = makeContext('win32', 'C:\\Users\\alice');
+    await seedSource(src);
+    const adapters = createAdapters({ namespaces: NS });
+    const zipPath = path.join(tmp, 'dsh-config-roundtrip.zip');
+    const exporter = new Exporter({
+      ctx: src, adapters, exporterVersion: '0.1.0',
+      now: () => new Date('2026-08-14T12:00:00.000Z'),
+    });
+    const result = await exporter.export({ includeSecrets: false, outPath: zipPath });
+    assert.equal(result.manifest.schemaVersion, 1);
+    assert.equal(result.manifest.security.containsSecrets, false);
+    assert.equal(result.report.security.redactedHits >= 1, true, 'apiKey 字段应被 scanner 剥离计数');
+
+    // ZIP 内容检查：secret 值绝不出现；插件二进制未打包
+    const archive = parseZip(await fs.readFile(zipPath));
+    const allText = archive.names()
+      .filter((n) => n !== 'integrity/checksums.json')
+      .map((n) => Buffer.from(archive.readEntry(n)).toString('utf8'))
+      .join('\n');
+    assert.ok(!allText.includes('sk-super-secret-value-123'), 'secret 值不得写入导出');
+    assert.ok(archive.has('config/settings.json'));
+    assert.ok(archive.has('config/ui.json'));
+    assert.ok(archive.has('ai/providers.json'));
+    assert.ok(archive.has('plugins/plugins.json'));
+    assert.ok(archive.has('mcp/servers.json'));
+    assert.ok(archive.has('custom/prompts.json'));
+    assert.ok(archive.has('custom/skills/coding.md'));
+    assert.ok(archive.has('agents/presets/work/agent.cordis.yml'));
+    assert.ok(archive.has('workspaces/workspaces.json'));
+    assert.ok(archive.has('security/credentials.json'));
+
+    // —— 目标机器（linux）导入 ——
+    const dst = makeContext('linux', '/home/bob');
+    const importer = new Importer({ ctx: dst, adapters, snapshotStore: new MemSnapshotStore() });
+
+    const analysis = await importer.analyzeImport(zipPath);
+    assert.equal(analysis.valid, true);
+    assert.equal(analysis.secretCount, 2, '两个已配置凭据（DEEPSEEK/OPENAI）需补录');
+    assert.equal(analysis.compatibility, 'partial'); // 跨平台
+    assert.ok(analysis.pathIssues.some((p) => p.kind === 'platformMismatch' && p.value.includes('C:\\Users\\alice')), '跨平台路径检测');
+
+    const plan = await importer.createImportPlan(zipPath, {
+      strategy: 'merge',
+      resolutions: {},
+      pathMappings: [{ oldPrefix: 'C:\\Users\\alice', newPrefix: '/home/bob', appliesTo: ['workspaces', 'mcp', 'pluginConfig', 'skills'] }],
+    });
+    assert.ok(plan.pathMappings.length >= 1);
+    assert.equal(plan.needsRestart, true, 'MCP/patch 行写入需要重启');
+
+    // Dry Run 零写入
+    assert.equal(dst.settings.ns.size, 0);
+    assert.equal(dst.patchFile.lines.size, 0);
+
+    const r = await importer.executeImportPlan(zipPath, plan, {
+      confirm: true,
+      secretInputs: { DEEPSEEK_API_KEY: 'sk-reentered' },
+    });
+    assert.equal(r.ok, true);
+
+    // settings/ui/providers 写回
+    assert.deepEqual(dst.settings.ns.get('general')?.value, { theme: 'dark', language: 'zh-CN' });
+    assert.deepEqual(dst.settings.ns.get('theme')?.value, { mode: 'dark' });
+    const llm = dst.settings.ns.get('llm-deepseek')?.value as Record<string, unknown>;
+    assert.equal(llm.apiKeyEnv, 'DEEPSEEK_API_KEY');
+    assert.equal(llm.apiKey, '', 'secret 字段剥离为空串');
+
+    // 文件类写回
+    assert.equal(Buffer.from(await dst.fs.readFile('skills/coding.md')).toString(), '# Coding skill\nUse deepseek.\n');
+    assert.equal(Buffer.from(await dst.fs.readFile('.agent-presets/work/agent.cordis.yml')).toString(), 'services:\n  - name: work\n');
+
+    // workspaces 路径映射
+    const ws = dst.workspace.records.get('ws-ops');
+    assert.ok(ws);
+    assert.equal(normalizePath(ws.path), '/home/bob/projects/ops', '绝对路径被映射');
+
+    // MCP / prompt patch 行写入（needsRestart 语义）
+    assert.ok(dst.patchFile.lines.has('mcp-fs'), 'MCP patch 行写入');
+    const mcpLine = dst.patchFile.lines.get('mcp-fs')?.raw as Record<string, unknown>;
+    assert.equal((mcpLine['config'] as Record<string, unknown>)['cwd'], '/home/bob/projects', 'MCP cwd 被映射');
+    const persona = dst.patchFile.lines.get('persona-line')?.raw as Record<string, unknown>;
+    assert.equal(((persona['config'] as Record<string, unknown>)['systemPrompt'] as Record<string, unknown>)['persona'], 'You are a helpful assistant.');
+
+    // 凭据：补录写入 + 未补录如实报告
+    assert.equal(dst.credentials.values.get('DEEPSEEK_API_KEY'), 'sk-reentered');
+    assert.ok(r.missingSecrets.includes('OPENAI_API_KEY'), '未补录的凭据进入报告');
+    assert.ok(!dst.credentials.values.has('OPENAI_API_KEY'), '未提供值不得写入');
+
+    // 幂等：再次导入 → 无新写入项（除 MissingSecret 占位）
+    const plan2 = await importer.createImportPlan(zipPath, {
+      strategy: 'merge',
+      resolutions: {},
+      pathMappings: [{ oldPrefix: 'C:\\Users\\alice', newPrefix: '/home/bob', appliesTo: ['workspaces', 'mcp', 'pluginConfig', 'skills'] }],
+    });
+    assert.ok(
+      !plan2.items.some((i) => i.kind === 'Create' || i.kind === 'Update' || i.kind === 'Install'),
+      '重复导入不产生新写入项',
+    );
+    const r2 = await importer.executeImportPlan(zipPath, plan2, { confirm: true, secretInputs: {} });
+    assert.ok(r2.executed.every((e) => e.status !== 'failed'), '第二次导入无失败项');
+    assert.equal(dst.patchFile.lines.size, 2, 'patch 行未被重复插入');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('集成：pluginFiles 默认不导出 / sessions 默认不导出（manifest 标记 false）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-adapters-opt-'));
+  try {
+    const src = makeContext('win32', 'C:\\Users\\alice');
+    await src.fs.writeFile('dsh-ssh.json', Buffer.from('{"hosts":[]}', 'utf8'));
+    await src.fs.writeFile('sessions/p/s/s.jsonl.zstd', Buffer.from('x', 'utf8'));
+    const adapters = createAdapters({ namespaces: NS, includeSessions: true });
+    const zipPath = path.join(tmp, 'opt.zip');
+    const exporter = new Exporter({ ctx: src, adapters, exporterVersion: '0.1.0' });
+    const result = await exporter.export({ includeSecrets: false, outPath: zipPath });
+    assert.equal(result.manifest.sections.pluginFiles, false, 'pluginFiles 默认不导出');
+    assert.equal(result.manifest.sections.sessions, false, 'sessions 默认不导出');
+    const archive = parseZip(await fs.readFile(zipPath));
+    assert.ok(!archive.has('plugin-files/dsh-ssh.json'));
+    assert.ok(!archive.has('sessions/p/s/s.jsonl.zstd'));
+
+    // 显式勾选后导出
+    const zipPath2 = path.join(tmp, 'opt2.zip');
+    await exporter.export({ includeSecrets: false, only: ['pluginFiles', 'sessions'], outPath: zipPath2 });
+    const archive2 = parseZip(await fs.readFile(zipPath2));
+    assert.ok(archive2.has('plugin-files/dsh-ssh.json'));
+    assert.ok(archive2.has('sessions/p/s/s.jsonl.zstd'));
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});

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,93 @@
+/**
+ * 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 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]]);
+
+  const dst = makeContext('linux', '/home/bob');
+  // 目标无 → Create 并写入
+  let items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items.length, 1);
+  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);
+});