@logictan/dsh-config-manager 0.1.60

package/src/adapters/index.ts

@@ -0,0 +1,94 @@
+/**
+ * 适配器 registry（设计 §12.1 / §3.3）：
+ * 组装全部 ConfigAdapter（导出顺序参考 APPLY_ORDER：settings → ui → providers → prompts
+ * → skills → agentPresets → agentInstructions → workspaces → pluginFiles → mcp → plugins → credentialsStatus）。
+ *
+ * 明确不实现的 adapter（研究报告 §2.2 确认 DSH 无对应概念）：keybindings / workflows / commands ——
+ * manifest 中不出现这些 section，产品 UI 说明「DSH 当前无此配置」；
+ * rules 概念已由 agentInstructions（~/.dsh/AGENTS.md）承接。
+ */
+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, type LocalPluginPackHook } 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 { AgentInstructionsAdapter } from './agent-instructions.ts';
+import { WorkspacesAdapter } from './workspaces.ts';
+import { CredentialsAdapter, type CredentialRefsProvider } from './credentials.ts';
+import { PluginFilesAdapter } from './plugin-files.ts';
+import { SessionsAdapter } from './sessions.ts';
+import { SelfAdapter } from './self.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[];
+  /** pluginFiles 约定的配置目录（相对 ~/.dsh 根），递归收集其下所有插件配置文件 */
+  pluginFilesDir?: string;
+  /** 是否包含 sessions 分区（默认关，研究报告 §4.9） */
+  includeSessions?: boolean;
+  /** 插件自身包名：导出 plugins 分区时不列自己（避免自引用；缺省 dsh-config-manager） */
+  selfPluginName?: string;
+  /**
+   * T1：本地源（link:/file:）插件打包钩子。注入后，导出 plugins 分区时会为这类插件
+   * 执行 `npm pack` 并把 tarball 随备份带走；不注入 = 保持改造前行为（本地插件换机丢失）。
+   */
+  localPluginPack?: LocalPluginPackHook;
+  /**
+   * self 分区：插件自身配置目录（相对 ~/.dsh 根，如 'dsh-config-manager'）。
+   * 缺省 'dsh-config-manager'；传入 '' 表示不挂载（宿主自定义 dataDir 在 homeDir 外时）。
+   */
+  selfDir?: string;
+}
+
+/** 组装默认 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(options.selfPluginName, options.localPluginPack),
+    new McpAdapter(),
+    new PromptsAdapter(),
+    new SkillsAdapter(),
+    new AgentPresetsAdapter(),
+    new AgentInstructionsAdapter(),
+    new WorkspacesAdapter(),
+    new CredentialsAdapter({ namespaces, refs: options.credentialsRefs }),
+    new PluginFilesAdapter(options.pluginFiles, options.pluginFilesDir),
+  ];
+  // self 分区：插件自身配置（同步/市场/偏好），portable 默认包含；'' = 不挂载
+  if (options.selfDir !== '') {
+    adapters.push(new SelfAdapter(options.selfDir ?? 'dsh-config-manager'));
+  }
+  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 type { LocalPluginPackHook } 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 { AgentInstructionsAdapter } from './agent-instructions.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 { SelfAdapter, SELF_CONFIG_FILES } from './self.ts';
+export { FileCollectionAdapter } from './file-collection.ts';

package/src/adapters/link-report.test.ts

@@ -0,0 +1,65 @@
+/**
+ * issue #37：链接目录的告警构造（备份必须能说明「跟随了什么 / 跳过了什么」）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { linkWarnings, listFilesDetailed } from './link-report.ts';
+import { zhMsg } from '../core/messages.ts';
+import type { FileSystemFacade } from '../core/types.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
+
+const clean: RecursiveListing = { paths: ['skills/a.md'], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
+
+test('linkWarnings：无链接 → 零告警（不制造噪音）', () => {
+  assert.deepEqual(linkWarnings(zhMsg, 'Skills', clean), []);
+});
+
+test('linkWarnings：跟随的链接必须提示「结构不会重建」', () => {
+  const out = linkWarnings(zhMsg, 'Skills', { ...clean, followedLinks: 3 });
+  assert.equal(out.length, 1);
+  assert.match(out[0]!, /3/);
+  assert.match(out[0]!, /链接目录/);
+  assert.match(out[0]!, /链接结构不会重建/);
+});
+
+test('linkWarnings：跳过项按原因归并，给出数量、原因与路径', () => {
+  const out = linkWarnings(zhMsg, 'Skills', {
+    paths: [],
+    followedLinks: 1,
+    unreadableDirs: [],
+    skippedLinks: [
+      { path: 'skills/self', reason: 'loop' },
+      { path: 'skills/broken', reason: 'broken' },
+      { path: 'skills/outside', reason: 'outside-home' },
+      { path: 'skills/fifo', reason: 'unreadable' },
+      { path: 'skills/deep', reason: 'too-deep' },
+    ],
+  });
+  assert.equal(out.length, 2, '跟随 + 跳过各一条');
+  const skipped = out[1]!;
+  assert.match(skipped, /5 个链接被跳过/);
+  assert.match(skipped, /自引用\/重复链接/);
+  assert.match(skipped, /断链/);
+  assert.match(skipped, /目标在 DSH home 之外/);
+  assert.match(skipped, /skills\/self/);
+  // 未进备份必须说清楚，而不是「已跳过」这类中性的措辞
+  assert.match(skipped, /未进备份/);
+});
+
+test('linkWarnings：目录读取失败也必须告警（其内容同样未进备份）', () => {
+  const out = linkWarnings(zhMsg, 'Skills', {
+    paths: [], followedLinks: 0, skippedLinks: [], unreadableDirs: ['skills/locked', 'skills/denied'],
+  });
+  assert.equal(out.length, 1);
+  assert.match(out[0]!, /2 个目录读取失败/);
+  assert.match(out[0]!, /未进备份/);
+  assert.match(out[0]!, /skills\/locked/);
+});
+
+test('listFilesDetailed：宿主未实现 detailed 时回退到 listRecursive（旧行为不变）', async () => {
+  const fs = { listRecursive: async () => ['skills/x.md'] } as unknown as FileSystemFacade;
+  const listing = await listFilesDetailed(fs, 'skills');
+  assert.deepEqual(listing.paths, ['skills/x.md']);
+  assert.deepEqual(listing.skippedLinks, []);
+  assert.equal(listing.followedLinks, 0);
+});

package/src/adapters/link-report.ts

@@ -0,0 +1,61 @@
+/**
+ * 文件类分区的「链接目录」报告（issue #37）。
+ *
+ * 背景：备份静默跳过 junction/符号链接，用户拿到的仍是「成功」，却少了整块内容。
+ * 修复分两步：① `utils/recursive-walk.ts` 跟随链接收集内容；② 本模块把「跟随了什么、
+ * 跳过了什么、为什么跳过」变成备份报告里可见的告警 —— 缺了 ②，用户依然无从察觉缺失。
+ *
+ * 纯函数（除 listFilesDetailed 的 IO 委托外），两个 adapter 共用，避免文案再次漂移。
+ */
+import type { FileSystemFacade } from '../core/types.ts';
+import type { MsgFunc } from '../core/messages.ts';
+import type { RecursiveListing, SkippedLink } from '../utils/recursive-walk.ts';
+
+/** 跳过原因 → 消息 key（与 SkippedLink.reason 一一对应，穷尽映射） */
+const REASON_KEY: Record<SkippedLink['reason'], string> = {
+  loop: 'adapter.linkReason.loop',
+  'outside-home': 'adapter.linkReason.outsideHome',
+  broken: 'adapter.linkReason.broken',
+  unreadable: 'adapter.linkReason.unreadable',
+  'too-deep': 'adapter.linkReason.tooDeep',
+}
+
+/** 单条原因下最多列出的路径数（其余折叠为计数，避免把报告撑爆） */
+const MAX_PATHS_PER_REASON = 5
+
+/** 取遍历结果：宿主未实现 listRecursiveDetailed（旧版/测试 mock）时回退，行为与旧版一致。 */
+export async function listFilesDetailed(fs: FileSystemFacade, dir: string): Promise<RecursiveListing> {
+  if (fs.listRecursiveDetailed !== undefined) return fs.listRecursiveDetailed(dir)
+  return { paths: await fs.listRecursive(dir), skippedLinks: [], followedLinks: 0, unreadableDirs: [] }
+}
+
+/** 把遍历结果转成告警行（无链接时返回空数组 —— 不制造噪音）。 */
+export function linkWarnings(msg: MsgFunc, type: string, listing: RecursiveListing): string[] {
+  const out: string[] = []
+  if (listing.followedLinks > 0) {
+    out.push(msg('adapter.linksFollowed', { type, count: String(listing.followedLinks) }))
+  }
+  if (listing.skippedLinks.length > 0) {
+    const byReason = new Map<SkippedLink['reason'], string[]>()
+    for (const s of listing.skippedLinks) {
+      const arr = byReason.get(s.reason) ?? []
+      arr.push(s.path)
+      byReason.set(s.reason, arr)
+    }
+    const detail = [...byReason.entries()].map(([reason, paths]) => {
+      const shown = paths.slice(0, MAX_PATHS_PER_REASON).join(', ')
+      const more = paths.length > MAX_PATHS_PER_REASON ? ` (+ ${paths.length - MAX_PATHS_PER_REASON})` : ''
+      return `${msg(REASON_KEY[reason])} ${paths.length} 个: ${shown}${more}`
+    }).join('；')
+    out.push(msg('adapter.linksSkipped', { type, count: String(listing.skippedLinks.length), detail }))
+  }
+  if (listing.unreadableDirs.length > 0) {
+    const shown = listing.unreadableDirs.slice(0, MAX_PATHS_PER_REASON).join(', ')
+    const more = listing.unreadableDirs.length > MAX_PATHS_PER_REASON
+      ? ` (+ ${listing.unreadableDirs.length - MAX_PATHS_PER_REASON})` : ''
+    out.push(msg('adapter.dirsUnreadable', {
+      type, count: String(listing.unreadableDirs.length), detail: `${shown}${more}`,
+    }))
+  }
+  return out
+}

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,185 @@
+/**
+ * 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 { msgOf, zhMsg } from '../core/messages.ts';
+import type { MsgFunc } from '../core/messages.ts';
+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(msgOf(ctx)('adapter.patchReadFailedMCP', { reason: 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 msg = ctx.msg;
+    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: msg('adapter.mcpCreate', { serverName: 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: msg('adapter.mcpSame', { serverName: server.serverName }), severity: 'info' });
+        } else {
+          items.push({
+            id, kind: 'Conflict', adapter: 'mcp',
+            description: msg('adapter.mcpDiff', { serverName: 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 msg = ctx.msg;
+    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: msg('adapter.mcpMissing', { serverName }) };
+    const ref = item.target?.ref;
+    if (!ref) return { ok: false, message: msg('adapter.missingTargetRef') };
+    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: msg('adapter.mcpWritten', { serverName }) };
+  }
+
+  async validate(data: McpExportSection, 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: 'mcp' }), severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
+    }
+    if (!Array.isArray(data.servers)) {
+      issues.push({ path: 'servers', message: msg('adapter.validate.array', { subject: '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: msg('adapter.validate.serverName'), severity: 'error' });
+        }
+      }
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}

package/src/adapters/plugin-files.ts

@@ -0,0 +1,146 @@
+/**
+ * pluginFiles 分区 adapter（可选，设计 §3.3/§1.2）：
+ * 数据源 = 插件自有配置文件（相对 ~/.dsh 根）：
+ *   1. 白名单固定文件（dsh-ssh.json、pet.json 等，避免扫描整个主目录）；
+ *   2. 约定的插件配置目录（collectDir，如 plugin-config/）递归收集其下所有文件。
+ * relativePath 一律是「相对 ~/.dsh 根」的完整路径（与白名单文件一致），
+ * 导入时按同一相对路径写回原位置。默认关闭（defaultIncluded=false，用户显式勾选才导出）。
+ */
+import { sha256Hex } from '../utils/hashing.ts';
+import { msgOf, zhMsg } from '../core/messages.ts';
+import { linkWarnings, listFilesDetailed } from './link-report.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
+import { isPathSafe, isReservedInternalRel } from '../utils/paths.ts';
+import type { MsgFunc } from '../core/messages.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[];
+  /** 约定配置目录（相对 ~/.dsh 根，如 'plugin-config'）；递归收集其下所有文件。undefined = 不收集。 */
+  private readonly collectDir?: string;
+
+  constructor(whitelist: string[] = [...DEFAULT_PLUGIN_FILE_WHITELIST], collectDir?: string) {
+    this.whitelist = whitelist;
+    if (collectDir !== undefined && collectDir !== '' && !isPathSafe(collectDir)) {
+      throw new Error(`pluginFiles collectDir 非法（须为相对 ~/.dsh 根的安全路径）: ${collectDir}`);
+    }
+    this.collectDir = collectDir === '' ? undefined : collectDir;
+  }
+
+  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<FilesSection>> {
+    const files: FilesSection['files'] = [];
+    const seen = new Set<string>();
+    // 1) 白名单固定文件（不存在则跳过，dsh-ssh.json 等为按需创建）
+    for (const rel of this.whitelist) {
+      try {
+        const data = await ctx.fs.readFile(rel);
+        files.push({ relativePath: rel, data, contentHash: sha256Hex(data) });
+        seen.add(rel);
+      } catch {
+        /* 白名单文件不存在则跳过 */
+      }
+    }
+    // 2) 约定配置目录递归收集（相对 ~/.dsh 根的完整路径；与白名单文件去重）
+    // issue #37：与 skills 等同一条遍历（跟随 junction/符号链接 + 跳过留痕）
+    let listing: RecursiveListing = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
+    if (this.collectDir !== undefined) {
+      try {
+        listing = await listFilesDetailed(ctx.fs, this.collectDir);
+      } catch {
+        // 目录不存在视为空
+      }
+      const rels = listing.paths;
+      for (const rel of rels) {
+        if (seen.has(rel)) continue;
+        try {
+          const data = await ctx.fs.readFile(rel);
+          files.push({ relativePath: rel, data, contentHash: sha256Hex(data) });
+        } catch {
+          continue;
+        }
+      }
+    }
+    return {
+      sectionId: 'pluginFiles',
+      data: { version: 1, files },
+      counts: { files: files.length },
+      warnings: linkWarnings(msgOf(ctx), this.displayName, listing),
+    };
+  }
+
+  async analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]> {
+    const msg = ctx.msg;
+    const items: PlanItem[] = [];
+    for (const file of data.files) {
+      const id = `pluginFile:${file.relativePath}`;
+      // F23 修复：不可信 import 不得写内部 control-plane namespace（snapshots/transactions/locks/safe-mode）
+      if (isReservedInternalRel(file.relativePath)) {
+        items.push({
+          id, kind: 'Error', adapter: 'pluginFiles',
+          description: msg('adapter.pluginFileReserved', { path: file.relativePath }), severity: 'error',
+        });
+        continue;
+      }
+      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: msg('adapter.pluginFileCreate', { path: file.relativePath }), severity: 'info',
+          target: { adapter: 'pluginFiles', ref: file.relativePath },
+        });
+      } else if (sha256Hex(current) === file.contentHash) {
+        items.push({ id, kind: 'Skip', adapter: 'pluginFiles', description: msg('adapter.fileSame', { path: file.relativePath }), severity: 'info' });
+      } else {
+        items.push({
+          id, kind: 'Conflict', adapter: 'pluginFiles',
+          description: msg('adapter.fileDiff', { path: 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: ctx.msg('adapter.missingTargetRef') };
+    // F23 修复：apply 前拒绝写内部 control-plane namespace（纵深防御，analyzeImport 已标 Error）
+    if (isReservedInternalRel(ref)) {
+      return { ok: false, message: ctx.msg('adapter.pluginFileReserved', { path: 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: ctx.msg('adapter.dataMissingFile', { ref }) };
+    await ctx.target.fs.writeFile(ref, file.data);
+    return { ok: true };
+  }
+
+  async validate(data: FilesSection, 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: 'pluginFiles' }), severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
+    }
+    if (!Array.isArray(data.files)) {
+      issues.push({ path: 'files', message: msg('adapter.validate.array', { subject: 'files' }), severity: 'error' });
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}