dsh-config-manager 0.1.0

package/src/adapters/file-collection.ts

@@ -0,0 +1,110 @@
+/**
+ * 文件类分区共享 adapter 基类（skills / agentPresets / sessions 复用）。
+ * 基准目录与 core/backup.ts 的 FILE_BASES 保持一致（skills→'skills'、agentPresets→'.agent-presets'、sessions→'sessions'），
+ * 保证引擎通用快照/回滚（resolveFileTarget）与 applyItem 的写入路径完全一致。
+ *
+ * 文件内容以真实文件进入 ZIP（custom/skills/… 等前缀由 exporter 按 SECTION_FILE_PREFIXES 处理）。
+ * 幂等：相对路径 + 内容 SHA-256 hash 比对（重复导入 → Skip）。
+ */
+import path from 'node:path';
+import { sha256Hex } from '../utils/hashing.ts';
+import type { FilesSection, SectionId } from '../schema/types.ts';
+import type {
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ImportContext, PlanItem, Portability, ValidationResult,
+} from '../core/types.ts';
+
+export abstract class FileCollectionAdapter implements ConfigAdapter<FilesSection> {
+  abstract readonly id: SectionId;
+  abstract readonly displayName: string;
+  abstract readonly defaultIncluded: boolean;
+  abstract readonly portability: Portability;
+  /** 相对 homeDir 的基准目录（与 core/backup.ts FILE_BASES 一致） */
+  abstract readonly baseDir: string;
+
+  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<FilesSection>> {
+    const files: FilesSection['files'] = [];
+    const warnings: string[] = [];
+    let rels: string[] = [];
+    try {
+      rels = await ctx.fs.listRecursive(this.baseDir);
+    } catch {
+      // 目录不存在视为空
+    }
+    for (const rel of rels) {
+      const data = await ctx.fs.readFile(rel);
+      const relPath = this.baseDir === '' ? rel : rel.replace(new RegExp(`^${escapeRegExp(this.baseDir)}[\\/]`), '');
+      files.push({ relativePath: relPath, data, contentHash: sha256Hex(data) });
+    }
+    if (rels.length === 0) warnings.push(`${this.displayName} 目录为空或不存在`);
+    return {
+      sectionId: this.id,
+      data: { version: 1, files },
+      counts: { files: files.length },
+      warnings,
+    };
+  }
+
+  async analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]> {
+    const items: PlanItem[] = [];
+    for (const file of data.files) {
+      const id = `${this.id}:${file.relativePath}`;
+      let current: Uint8Array | null = null;
+      try {
+        current = await ctx.target.fs.readFile(path.join(this.baseDir, file.relativePath));
+      } catch {
+        current = null;
+      }
+      if (current === null) {
+        items.push({
+          id, kind: 'Create', adapter: this.id,
+          description: `创建${this.displayName}文件 ${file.relativePath}`, severity: 'info',
+          target: { adapter: this.id, ref: file.relativePath },
+        });
+      } else if (sha256Hex(current) === file.contentHash) {
+        items.push({ id, kind: 'Skip', adapter: this.id, description: `文件 ${file.relativePath} 已一致`, severity: 'info' });
+      } else {
+        items.push({
+          id, kind: 'Conflict', adapter: this.id,
+          description: `文件 ${file.relativePath} 内容不同`, severity: 'warning',
+          target: { adapter: this.id, ref: file.relativePath },
+        });
+      }
+    }
+    return items;
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    const ref = item.target?.ref;
+    if (!ref) return { ok: false, message: '缺少 target.ref' };
+    const data = ctx.sections.get(this.id) as FilesSection | undefined;
+    const file = data?.files.find((f) => f.relativePath === ref);
+    if (!file) return { ok: false, message: `导入数据缺少文件 ${ref}` };
+    await ctx.target.fs.writeFile(path.join(this.baseDir, ref), file.data);
+    return { ok: true };
+  }
+
+  async validate(data: FilesSection): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: '文件分区数据必须是对象', severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: `version 必须为 1（收到 ${String(data.version)}）`, severity: 'error' });
+    }
+    if (!Array.isArray(data.files)) {
+      issues.push({ path: 'files', message: 'files 必须是数组', severity: 'error' });
+    } else {
+      for (const f of data.files) {
+        if (f === null || typeof f !== 'object' || typeof f.relativePath !== 'string' || f.relativePath === '') {
+          issues.push({ path: 'files[]', message: '文件记录必须含非空 relativePath', severity: 'error' });
+        }
+      }
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/adapters/files.test.ts

@@ -0,0 +1,113 @@
+/**
+ * 文件类分区 adapter 测试（skills / agentPresets / pluginFiles / sessions）：
+ * 导出收集文件、Create/Skip 分析、applyItem 写入、白名单与默认关闭语义。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { SkillsAdapter } from './skills.ts';
+import { AgentPresetsAdapter } from './agent-presets.ts';
+import { PluginFilesAdapter } from './plugin-files.ts';
+import { SessionsAdapter } from './sessions.ts';
+import { makeContext, makeImportContext, sha256Hex } from './test-helpers.ts';
+import type { PlanItem } from '../core/types.ts';
+
+test('skills: 导出收集文件 + 导入往返（hash 幂等）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  await src.fs.writeFile('skills/coding.md', Buffer.from('# Coding skill\n', 'utf8'));
+  await src.fs.writeFile('skills/git.md', Buffer.from('# Git skill\n', 'utf8'));
+
+  const adapter = new SkillsAdapter();
+  const out = await adapter.export(src, { includeSecrets: false });
+  assert.equal(out.data.files.length, 2);
+  assert.equal(out.data.files[0]?.relativePath, 'coding.md');
+  assert.equal(out.data.files[0]?.contentHash, sha256Hex(Buffer.from('# Coding skill\n')));
+  assert.equal(out.counts.files, 2);
+
+  const sections = new Map([['skills', out.data]]);
+  const dst = makeContext('linux', '/home/bob');
+  let items = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  assert.equal(items.length, 2);
+  assert.ok(items.every((i) => i.kind === 'Create'));
+  for (const item of items) {
+    const r = await adapter.applyItem(item, makeImportContext(dst, sections));
+    assert.equal(r.ok, true);
+  }
+  assert.equal(Buffer.from(await dst.fs.readFile('skills/coding.md')).toString(), '# Coding skill\n');
+
+  // 幂等：一致 → Skip
+  items = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  assert.ok(items.every((i) => i.kind === 'Skip'));
+
+  // 内容不同 → Conflict
+  await dst.fs.writeFile('skills/coding.md', Buffer.from('# Changed\n', 'utf8'));
+  items = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  assert.ok(items.some((i) => i.kind === 'Conflict'));
+});
+
+test('agentPresets: 目录 bundle 文件收集与写入（.agent-presets 基准目录）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  await src.fs.writeFile('.agent-presets/work/agent.cordis.yml', Buffer.from('services:\n  - name: work\n', 'utf8'));
+  await src.fs.writeFile('.agent-presets/work/preset.yml', Buffer.from('name: work\n', 'utf8'));
+
+  const adapter = new AgentPresetsAdapter();
+  const out = await adapter.export(src, { includeSecrets: false });
+  assert.equal(out.data.files.length, 2);
+  const rels = out.data.files.map((f) => f.relativePath).sort();
+  assert.deepEqual(rels, ['work/agent.cordis.yml', 'work/preset.yml']);
+
+  const sections = new Map([['agentPresets', out.data]]);
+  const dst = makeContext('linux', '/home/bob');
+  const items = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  assert.ok(items.every((i) => i.kind === 'Create'));
+  for (const item of items) {
+    await adapter.applyItem(item, makeImportContext(dst, sections));
+  }
+  assert.equal(
+    Buffer.from(await dst.fs.readFile('.agent-presets/work/agent.cordis.yml')).toString(),
+    'services:\n  - name: work\n',
+  );
+});
+
+test('pluginFiles: 白名单导出（不存在跳过）+ 默认不包含', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  await src.fs.writeFile('dsh-ssh.json', Buffer.from('{"hosts":[]}', 'utf8'));
+  await src.fs.writeFile('other-file.json', Buffer.from('{"x":1}', 'utf8'));
+
+  const adapter = new PluginFilesAdapter(['dsh-ssh.json', 'pet.json']);
+  assert.equal(adapter.defaultIncluded, false, 'pluginFiles 默认不导出');
+  const out = await adapter.export(src, { includeSecrets: false });
+  assert.equal(out.data.files.length, 1);
+  assert.equal(out.data.files[0]?.relativePath, 'dsh-ssh.json');
+  assert.ok(!out.data.files.some((f) => f.relativePath === 'other-file.json'), '白名单外文件不导出');
+
+  const sections = new Map([['pluginFiles', out.data]]);
+  const dst = makeContext('linux', '/home/bob');
+  const items = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  assert.equal(items[0]?.kind, 'Create');
+  await adapter.applyItem(items[0]!, makeImportContext(dst, sections));
+  assert.equal(Buffer.from(await dst.fs.readFile('dsh-ssh.json')).toString(), '{"hosts":[]}');
+});
+
+test('sessions: 默认关 + 文件级复制（deviceSpecific）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  await src.fs.writeFile('sessions/proj-a/s1/session.jsonl.zstd', Buffer.from('zstd-bytes', 'utf8'));
+  const adapter = new SessionsAdapter();
+  assert.equal(adapter.defaultIncluded, false, 'sessions 默认不导出');
+  assert.equal(adapter.portability, 'deviceSpecific');
+  const out = await adapter.export(src, { includeSecrets: false });
+  assert.equal(out.data.files.length, 1);
+  assert.equal(out.data.files[0]?.relativePath, 'proj-a/s1/session.jsonl.zstd');
+
+  const sections = new Map([['sessions', out.data]]);
+  const dst = makeContext('linux', '/home/bob');
+  const items = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  const r = await adapter.applyItem(items[0]!, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  assert.equal(Buffer.from(await dst.fs.readFile('sessions/proj-a/s1/session.jsonl.zstd')).toString(), 'zstd-bytes');
+});
+
+test('文件类 validate', async () => {
+  const adapter = new SkillsAdapter();
+  assert.equal((await adapter.validate({ version: 1, files: [] })).valid, true);
+  assert.equal((await adapter.validate({ version: 1, files: [{ relativePath: '' } as never] })).valid, false);
+});

package/src/adapters/index.ts

@@ -0,0 +1,69 @@
+/**
+ * 适配器 registry（设计 §12.1 / §3.3）：
+ * 组装全部 ConfigAdapter（导出顺序参考 APPLY_ORDER：settings → ui → providers → prompts
+ * → skills → agentPresets → workspaces → pluginFiles → mcp → plugins → credentialsStatus）。
+ *
+ * 明确不实现的 adapter（研究报告 §2.2 确认 DSH 无对应概念）：keybindings / workflows / commands / rules ——
+ * manifest 中不出现这些 section，产品 UI 说明「DSH 当前无此配置」。
+ */
+import type { ConfigAdapter, HostContext } from '../core/types.ts';
+import { SettingsAdapter, type NamespaceProvider } from './settings.ts';
+import { UiAdapter } from './ui.ts';
+import { ProvidersAdapter } from './providers.ts';
+import { PluginsAdapter } from './plugins.ts';
+import { McpAdapter } from './mcp.ts';
+import { PromptsAdapter } from './prompts.ts';
+import { SkillsAdapter } from './skills.ts';
+import { AgentPresetsAdapter } from './agent-presets.ts';
+import { WorkspacesAdapter } from './workspaces.ts';
+import { CredentialsAdapter, type CredentialRefsProvider } from './credentials.ts';
+import { PluginFilesAdapter } from './plugin-files.ts';
+import { SessionsAdapter } from './sessions.ts';
+
+export interface AdapterRegistryOptions {
+  /** settings namespace 清单（宿主从 settings.yaml 顶层 key 解析注入；缺省 [] → settings/ui/credentials 为空） */
+  namespaces?: string[] | NamespaceProvider;
+  /** 凭据 ref 收集器（缺省从 settings secrets 标记 + llm apiKeyEnv 推断） */
+  credentialsRefs?: CredentialRefsProvider;
+  /** pluginFiles 白名单（相对 ~/.dsh 根；缺省 dsh-ssh.json + pet.json） */
+  pluginFiles?: string[];
+  /** 是否包含 sessions 分区（默认关，研究报告 §4.9） */
+  includeSessions?: boolean;
+}
+
+/** 组装默认 adapter 列表（pluginFiles/sessions 恒挂载但 defaultIncluded=false，用户勾选才导出） */
+export function createAdapters(options: AdapterRegistryOptions = {}): ConfigAdapter[] {
+  const namespaces = options.namespaces ?? [];
+  const adapters: ConfigAdapter[] = [
+    new SettingsAdapter(namespaces),
+    new UiAdapter(namespaces),
+    new ProvidersAdapter(),
+    new PluginsAdapter(),
+    new McpAdapter(),
+    new PromptsAdapter(),
+    new SkillsAdapter(),
+    new AgentPresetsAdapter(),
+    new WorkspacesAdapter(),
+    new CredentialsAdapter({ namespaces, refs: options.credentialsRefs }),
+    new PluginFilesAdapter(options.pluginFiles),
+  ];
+  if (options.includeSessions) adapters.push(new SessionsAdapter());
+  return adapters;
+}
+
+export type { NamespaceProvider } from './settings.ts';
+export type { CredentialRefsProvider } from './credentials.ts';
+
+export { SettingsAdapter } from './settings.ts';
+export { UiAdapter, isUiNamespace, KNOWN_UI_NAMESPACE_PREFIXES, UI_MIGRATION_NOTES } from './ui.ts';
+export { ProvidersAdapter, DEFAULT_PROVIDER_NAMESPACES, type ProviderExportEntry, type ProviderExportSection } from './providers.ts';
+export { PluginsAdapter, USER_PATCH_FILE } from './plugins.ts';
+export { McpAdapter, extractMcpServers, buildMcpPatchLine, type McpExportEntry, type McpExportSection } from './mcp.ts';
+export { PromptsAdapter, extractPrompts, mergePromptIntoLine, buildPromptLine, type PromptExportEntry, type PromptsExportSection } from './prompts.ts';
+export { SkillsAdapter } from './skills.ts';
+export { AgentPresetsAdapter } from './agent-presets.ts';
+export { WorkspacesAdapter } from './workspaces.ts';
+export { CredentialsAdapter, defaultCredentialRefs } from './credentials.ts';
+export { PluginFilesAdapter, DEFAULT_PLUGIN_FILE_WHITELIST } from './plugin-files.ts';
+export { SessionsAdapter } from './sessions.ts';
+export { FileCollectionAdapter } from './file-collection.ts';

package/src/adapters/mcp.test.ts

@@ -0,0 +1,96 @@
+/**
+ * mcp adapter 测试：组合 patch 提取（单行 + insert 块）、Create/Skip/Conflict、
+ * applyItem 写 patch 行（needsRestart）、validate。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { McpAdapter, extractMcpServers, buildMcpPatchLine } from './mcp.ts';
+import { makeContext, makeImportContext } from './test-helpers.ts';
+import type { PlanItem } from '../core/types.ts';
+
+test('mcp: extractMcpServers 兼容单行与 insert 块', () => {
+  const lines = [
+    {
+      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' },
+      },
+    },
+    {
+      lineId: 'mcp-http',
+      raw: {
+        insert: [
+          { id: 'mcp-http', name: 'dsh-mcp-client', config: { serverName: 'remote', url: 'https://mcp.example.com/sse', headers: { Authorization: 'Bearer abc' } } },
+        ],
+      },
+    },
+    { lineId: 'other', raw: { id: 'other', name: '@deepseek-ai/dsh-web', config: { searchProvider: 'deepseek-official' } } },
+  ];
+  const servers = extractMcpServers(lines);
+  assert.equal(servers.length, 2);
+  const fs = servers.find((s) => s.serverName === 'filesystem');
+  assert.equal(fs?.type, 'stdio');
+  assert.equal(fs?.command, 'npx');
+  assert.equal(fs?.cwd, 'C:\\Users\\alice\\projects');
+  assert.equal(fs?.sourceLineId, 'mcp-fs');
+  const http = servers.find((s) => s.serverName === 'remote');
+  assert.equal(http?.type, 'streamable-http');
+  assert.equal(http?.url, 'https://mcp.example.com/sse');
+  assert.equal(http?.sourceLineId, 'mcp-http');
+});
+
+test('mcp: buildMcpPatchLine 构造写回行', () => {
+  const line = buildMcpPatchLine('mcp-fs', { serverName: 'filesystem', type: 'stdio', command: 'npx', args: ['-y', 'x'] });
+  assert.equal(line.id, 'mcp-fs');
+  assert.equal(line.name, 'dsh-mcp-client');
+  assert.equal((line.config as Record<string, unknown>)['command'], 'npx');
+});
+
+test('mcp: export 提取 + analyzeImport Create/Skip/Conflict + applyItem 写 patch（needsRestart）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.patchFile.lines.set('mcp-fs', {
+    lineId: 'mcp-fs',
+    raw: { id: 'mcp-fs', name: 'dsh-mcp-client', config: { serverName: 'filesystem', command: 'npx', args: ['-y', 'x'] } },
+  });
+  const adapter = new McpAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+  assert.equal(exported.data.servers.length, 1);
+  assert.equal(exported.data.servers[0]?.serverName, 'filesystem');
+  const sections = new Map([['mcp', 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]?.target?.ref, 'mcp-fs');
+  let r = await adapter.applyItem(items[0]!, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  assert.equal(r.needsRestart, true, 'MCP 写 patch 必须重启生效');
+  assert.ok(dst.patchFile.lines.has('mcp-fs'));
+  assert.equal((dst.patchFile.lines.get('mcp-fs')?.raw as Record<string, unknown>)['name'], 'dsh-mcp-client');
+
+  // 幂等：同 serverName 同内容 → Skip
+  items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items[0]?.kind, 'Skip');
+
+  // 目标同 serverName 不同内容 → Conflict（target.ref = 目标行 id）
+  dst.patchFile.lines.set('mcp-fs', {
+    lineId: 'mcp-fs',
+    raw: { id: 'mcp-fs', name: 'dsh-mcp-client', config: { serverName: 'filesystem', command: 'npx', args: ['-y', 'other'] } },
+  });
+  items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items[0]?.kind, 'Conflict');
+  const useItem: PlanItem = { ...items[0]!, kind: 'Update' };
+  r = await adapter.applyItem(useItem, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  const raw = dst.patchFile.lines.get('mcp-fs')?.raw as Record<string, unknown>;
+  assert.deepEqual((raw['config'] as Record<string, unknown>)['args'], ['-y', 'x'], 'Conflict useImported 应更新目标行');
+});
+
+test('mcp: validate 拒绝无 serverName 的条目', async () => {
+  const adapter = new McpAdapter();
+  const bad = await adapter.validate({ version: 1, servers: [{ serverName: '' } as never] });
+  assert.equal(bad.valid, false);
+});

package/src/adapters/mcp.ts

@@ -0,0 +1,181 @@
+/**
+ * mcp 分区 adapter（设计 §3.3/§1.2/§15）：
+ * 数据源 = 组合 patch 中 dsh-mcp-client 行的 config（研究报告 §2.2：MCP 无 settings 面/无管理 API）。
+ * 导入 = 写 profile cordis.patch.yml 插行（needsRestart 生效）；依赖检测（npx 等）由 analyzer 的
+ * dependencyChecker 执行（§15：缺失不阻塞，标记 Requires Attention）。
+ *
+ * patch 行 raw 支持两种形态：单行 { id, name, config } 与块 { insert: [{ id, name, config }] }。
+ */
+import { isDeepStrictEqual } from 'node:util';
+import type { McpServerEntry, McpSection } from '../schema/types.ts';
+import type {
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ImportContext, PlanItem, ValidationResult,
+} from '../core/types.ts';
+import { USER_PATCH_FILE } from './plugins.ts';
+
+/** 导出记录：McpServerEntry 之外附加来源 patch 行 id（导入写回定位用） */
+export interface McpExportEntry extends McpServerEntry {
+  sourceLineId: string;
+}
+
+export interface McpExportSection { version: 1; servers: McpExportEntry[]; }
+
+/** 从 patch 行数组中提取 MCP server 条目（以 config.serverName 存在为判定） */
+export function extractMcpServers(lines: { lineId: string; raw: unknown }[]): McpExportEntry[] {
+  const servers: McpExportEntry[] = [];
+  for (const line of lines) {
+    for (const entry of entriesOf(line.raw)) {
+      const config = entry.config;
+      if (config === null || typeof config !== 'object') continue;
+      const c = config as Record<string, unknown>;
+      const serverName = c['serverName'];
+      if (typeof serverName !== 'string' || serverName === '') continue;
+      const type = typeof c['url'] === 'string' && c['url'] !== '' ? 'streamable-http' : 'stdio';
+      servers.push({
+        serverName,
+        type,
+        command: typeof c['command'] === 'string' ? c['command'] : undefined,
+        args: Array.isArray(c['args']) ? (c['args'] as string[]) : undefined,
+        env: c['env'] !== null && typeof c['env'] === 'object' ? (c['env'] as Record<string, string>) : undefined,
+        cwd: typeof c['cwd'] === 'string' ? c['cwd'] : undefined,
+        url: typeof c['url'] === 'string' ? c['url'] : undefined,
+        headers: c['headers'] !== null && typeof c['headers'] === 'object' ? (c['headers'] as Record<string, string>) : undefined,
+        sourceLineId: line.lineId,
+      });
+    }
+  }
+  return servers;
+}
+
+/** patch 行 → 可枚举的 entry 列表（兼容单行与 insert 块） */
+function entriesOf(raw: unknown): { id?: unknown; name?: unknown; config?: unknown }[] {
+  if (raw === null || typeof raw !== 'object') return [];
+  const obj = raw as Record<string, unknown>;
+  if (Array.isArray(obj['insert'])) {
+    return obj['insert']
+      .filter((e): e is Record<string, unknown> => e !== null && typeof e === 'object')
+      .map((e) => e as { id?: unknown; name?: unknown; config?: unknown });
+  }
+  if (obj['id'] !== undefined || obj['name'] !== undefined) {
+    return [obj as { id?: unknown; name?: unknown; config?: unknown }];
+  }
+  return [];
+}
+
+/** 由导出条目构造写回 patch 行 raw（单行形态，与 dsh-mcp-client 组合 config 语义一致） */
+export function buildMcpPatchLine(lineId: string, server: McpServerEntry): Record<string, unknown> {
+  const config: Record<string, unknown> = { serverName: server.serverName };
+  if (server.type === 'streamable-http') {
+    config['url'] = server.url;
+    if (server.headers !== undefined) config['headers'] = server.headers;
+  } else {
+    config['command'] = server.command;
+    if (server.args !== undefined) config['args'] = server.args;
+    if (server.env !== undefined) config['env'] = server.env;
+    if (server.cwd !== undefined) config['cwd'] = server.cwd;
+  }
+  return { id: lineId, name: 'dsh-mcp-client', config };
+}
+
+function newLineId(serverName: string): string {
+  const slug = serverName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return `mcp-${slug || 'server'}`;
+}
+
+export class McpAdapter implements ConfigAdapter<McpExportSection> {
+  readonly id = 'mcp' as const;
+  readonly displayName = 'MCP Servers';
+  readonly defaultIncluded = true;
+  readonly portability = 'platformSpecific' as const;
+
+  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<McpExportSection>> {
+    const warnings: string[] = [];
+    let lines: { lineId: string; raw: unknown }[] = [];
+    try {
+      lines = await ctx.patchFile.readPatchLines(USER_PATCH_FILE);
+    } catch (err) {
+      warnings.push(`patch 文件读取失败，无法提取 MCP: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const servers = extractMcpServers(lines);
+    return {
+      sectionId: 'mcp',
+      data: { version: 1, servers },
+      counts: { servers: servers.length },
+      warnings,
+    };
+  }
+
+  async analyzeImport(data: McpExportSection, ctx: ImportContext): Promise<PlanItem[]> {
+    const items: PlanItem[] = [];
+    const targetLines = await ctx.target.patchFile.readPatchLines(USER_PATCH_FILE);
+    const targetServers = extractMcpServers(targetLines);
+    for (const server of data.servers) {
+      const id = `mcp:${server.serverName}`;
+      const existing = targetServers.find((s) => s.serverName === server.serverName);
+      const comparable = { ...server } as Record<string, unknown>;
+      delete comparable.sourceLineId;
+      if (!existing) {
+        const lineId = server.sourceLineId && targetLines.some((l) => l.lineId === server.sourceLineId)
+          ? `${server.sourceLineId}-imported`
+          : (server.sourceLineId ?? newLineId(server.serverName));
+        items.push({
+          id, kind: 'Create', adapter: 'mcp',
+          description: `创建 MCP server ${server.serverName}`,
+          detail: `${server.type === 'stdio' ? `${server.command} ${(server.args ?? []).join(' ')}` : server.url}`,
+          severity: 'info',
+          target: { adapter: 'mcp', ref: lineId },
+        });
+      } else {
+        const existingComparable = { ...existing } as Record<string, unknown>;
+        delete existingComparable.sourceLineId;
+        if (isDeepStrictEqual(existingComparable, comparable)) {
+          items.push({ id, kind: 'Skip', adapter: 'mcp', description: `MCP server ${server.serverName} 已一致`, severity: 'info' });
+        } else {
+          items.push({
+            id, kind: 'Conflict', adapter: 'mcp',
+            description: `MCP server ${server.serverName} 与目标不同`,
+            detail: `current=${JSON.stringify(existingComparable)} imported=${JSON.stringify(comparable)}`.slice(0, 200),
+            severity: 'warning',
+            target: { adapter: 'mcp', ref: existing.sourceLineId },
+          });
+        }
+      }
+    }
+    return items;
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    const serverName = item.id.replace(/^mcp:/, '');
+    const data = ctx.sections.get('mcp') as McpExportSection | undefined;
+    const server = data?.servers.find((s) => s.serverName === serverName);
+    if (!server) return { ok: false, message: `导入数据缺少 MCP server ${serverName}` };
+    const ref = item.target?.ref;
+    if (!ref) return { ok: false, message: '缺少 target.ref' };
+    const raw = buildMcpPatchLine(ref, server);
+    await ctx.target.patchFile.applyPatchChanges(USER_PATCH_FILE, [
+      { lineId: ref, raw, action: item.kind === 'Create' ? 'insert' : 'update' },
+    ]);
+    return { ok: true, needsRestart: true, message: `MCP server ${serverName} 已写入 patch，重启后生效` };
+  }
+
+  async validate(data: McpExportSection): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: 'mcp 数据必须是对象', severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: `version 必须为 1（收到 ${String(data.version)}）`, severity: 'error' });
+    }
+    if (!Array.isArray(data.servers)) {
+      issues.push({ path: 'servers', message: 'servers 必须是数组', severity: 'error' });
+    } else {
+      for (const s of data.servers) {
+        if (s === null || typeof s !== 'object' || typeof s.serverName !== 'string' || s.serverName === '') {
+          issues.push({ path: 'servers[]', message: 'server 记录必须含非空 serverName', severity: 'error' });
+        }
+      }
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}

package/src/adapters/plugin-files.ts

@@ -0,0 +1,96 @@
+/**
+ * pluginFiles 分区 adapter（可选，设计 §3.3/§1.2）：
+ * 数据源 = 插件自有配置文件白名单（dsh-ssh.json、pet.json 等，相对 ~/.dsh 根）。
+ * 白名单机制避免扫描整个主目录；默认关闭（defaultIncluded=false，用户显式勾选才导出）。
+ */
+import { sha256Hex } from '../utils/hashing.ts';
+import type { FilesSection } from '../schema/types.ts';
+import type {
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ImportContext, PlanItem, ValidationResult,
+} from '../core/types.ts';
+
+export const DEFAULT_PLUGIN_FILE_WHITELIST: readonly string[] = ['dsh-ssh.json', 'pet.json'];
+
+export class PluginFilesAdapter implements ConfigAdapter<FilesSection> {
+  readonly id = 'pluginFiles' as const;
+  readonly displayName = 'Plugin Files';
+  readonly defaultIncluded = false;
+  readonly portability = 'deviceSpecific' as const;
+  private readonly whitelist: string[];
+
+  constructor(whitelist: string[] = [...DEFAULT_PLUGIN_FILE_WHITELIST]) {
+    this.whitelist = whitelist;
+  }
+
+  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<FilesSection>> {
+    const files: FilesSection['files'] = [];
+    for (const rel of this.whitelist) {
+      try {
+        const data = await ctx.fs.readFile(rel);
+        files.push({ relativePath: rel, data, contentHash: sha256Hex(data) });
+      } catch {
+        // 白名单文件不存在则跳过（dsh-ssh.json 等为按需创建）
+      }
+    }
+    return {
+      sectionId: 'pluginFiles',
+      data: { version: 1, files },
+      counts: { files: files.length },
+      warnings: [],
+    };
+  }
+
+  async analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]> {
+    const items: PlanItem[] = [];
+    for (const file of data.files) {
+      const id = `pluginFile:${file.relativePath}`;
+      let current: Uint8Array | null = null;
+      try {
+        current = await ctx.target.fs.readFile(file.relativePath);
+      } catch {
+        current = null;
+      }
+      if (current === null) {
+        items.push({
+          id, kind: 'Create', adapter: 'pluginFiles',
+          description: `创建插件配置文件 ${file.relativePath}`, severity: 'info',
+          target: { adapter: 'pluginFiles', ref: file.relativePath },
+        });
+      } else if (sha256Hex(current) === file.contentHash) {
+        items.push({ id, kind: 'Skip', adapter: 'pluginFiles', description: `文件 ${file.relativePath} 已一致`, severity: 'info' });
+      } else {
+        items.push({
+          id, kind: 'Conflict', adapter: 'pluginFiles',
+          description: `文件 ${file.relativePath} 内容不同`, severity: 'warning',
+          target: { adapter: 'pluginFiles', ref: file.relativePath },
+        });
+      }
+    }
+    return items;
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    const ref = item.target?.ref;
+    if (!ref) return { ok: false, message: '缺少 target.ref' };
+    const data = ctx.sections.get('pluginFiles') as FilesSection | undefined;
+    const file = data?.files.find((f) => f.relativePath === ref);
+    if (!file) return { ok: false, message: `导入数据缺少文件 ${ref}` };
+    await ctx.target.fs.writeFile(ref, file.data);
+    return { ok: true };
+  }
+
+  async validate(data: FilesSection): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: 'pluginFiles 数据必须是对象', severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: `version 必须为 1（收到 ${String(data.version)}）`, severity: 'error' });
+    }
+    if (!Array.isArray(data.files)) {
+      issues.push({ path: 'files', message: 'files 必须是数组', severity: 'error' });
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}