@logictan/dsh-config-manager 0.1.60

package/src/adapters/credentials.ts

@@ -0,0 +1,143 @@
+/**
+ * credentialsStatus 分区 adapter（设计 §3.3/§7.1）：
+ * 数据源 = ctx.credentials.describe(ref) 的状态（configured/source/writable），
+ * 以及 settings secrets 标记 / llm apiKeyEnv 中引用的凭据 ref 名。
+ *
+ * 安全不变量：永不导出值（hasValue 恒 false）；导入生成 MissingSecret 清单，
+ * 用户补录值经 ctx.secretInputs / decryptedCredentials（仅内存）→ credentials.set()。
+ * .credentials.yaml 文件字节交由 m4 加密层处理，本 adapter 不触碰。
+ */
+import type { CredentialStatus, CredentialsSection } from '../schema/types.ts';
+import { msgOf, zhMsg } from '../core/messages.ts';
+import type { MsgFunc } from '../core/messages.ts';
+import type {
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ImportContext, PlanItem, ValidationResult,
+} from '../core/types.ts';
+import { resolveNamespaces, type NamespaceProvider } from './settings.ts';
+
+export type CredentialRefsProvider = (ctx: HostContext) => Promise<string[]>;
+
+/** 缺省 ref 收集：遍历 settings namespace，收集 llm apiKeyEnv / providers[].apiKeyEnv，
+ * 以及 secrets 标记中「引用类字段」（apiKeyEnv/tokenEnv…）的字段值。
+ * 注意 secrets[].path[0] 是 settings 文档内的字段路径（如 ['apiKey']），本身不是凭据 ref（设计 §4.2），
+ * 只有指向 env 名的引用字段才值得收集。 */
+export function defaultCredentialRefs(namespaces: string[] | NamespaceProvider): CredentialRefsProvider {
+  return async (ctx: HostContext): Promise<string[]> => {
+    const refs = new Set<string>();
+    for (const ns of await resolveNamespaces(namespaces, ctx)) {
+      try {
+        const info = await ctx.settings.describe(ns, { redactSecrets: true });
+        const value = (info.value ?? {}) as Record<string, unknown>;
+        // 引用类字段名（值 = env/凭据引用名，非秘密本身）
+        const REFERENCE_REF_FIELDS = new Set([
+          'apikeyenv', 'api_key_env', 'apikeyname', 'tokenenv', 'accesstokenenv',
+          'refreshtokenenv', 'clientsecretenv', 'passwordenv',
+        ]);
+        for (const s of info.secrets) {
+          const first = s.path?.[0];
+          if (typeof first !== 'string' || first === '') continue;
+          const norm = first.toLowerCase().replace(/[^a-z0-9]/g, '');
+          if (!REFERENCE_REF_FIELDS.has(norm)) continue;
+          const val = value[first];
+          if (typeof val === 'string' && val !== '') refs.add(val);
+        }
+        if (typeof value['apiKeyEnv'] === 'string' && value['apiKeyEnv'] !== '') refs.add(value['apiKeyEnv'] as string);
+        const providers = value['providers'];
+        if (providers !== null && typeof providers === 'object') {
+          for (const pv of Object.values(providers as Record<string, { apiKeyEnv?: unknown }>)) {
+            if (pv !== null && typeof pv === 'object' && typeof pv.apiKeyEnv === 'string' && pv.apiKeyEnv !== '') {
+              refs.add(pv.apiKeyEnv);
+            }
+          }
+        }
+      } catch {
+        // namespace 不存在则跳过
+      }
+    }
+    return [...refs];
+  };
+}
+
+export interface CredentialsAdapterOptions {
+  /** 凭据 ref 名收集器（缺省从 settings 推断） */
+  refs?: CredentialRefsProvider;
+  /** 供缺省 refs 使用的 namespace 清单 */
+  namespaces?: string[] | NamespaceProvider;
+}
+
+export class CredentialsAdapter implements ConfigAdapter<CredentialsSection> {
+  readonly id = 'credentialsStatus' as const;
+  readonly displayName = 'Credentials';
+  readonly defaultIncluded = true;
+  readonly portability = 'deviceSpecific' as const;
+  private readonly refs: CredentialRefsProvider;
+
+  constructor(options: CredentialsAdapterOptions = {}) {
+    this.refs = options.refs ?? defaultCredentialRefs(options.namespaces ?? []);
+  }
+
+  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<CredentialsSection>> {
+    const credentials: CredentialStatus[] = [];
+    const warnings: string[] = [];
+    for (const ref of await this.refs(ctx)) {
+      try {
+        const status = await ctx.credentials.describe(ref);
+        credentials.push({
+          ref,
+          required: true,
+          configured: status.configured,
+          source: (status.source as CredentialStatus['source']) ?? 'file',
+          hasValue: false, // 值未导出（安全不变量）
+        });
+      } catch (err) {
+        warnings.push(msgOf(ctx)('adapter.credStatusReadFailed', { ref, reason: err instanceof Error ? err.message : String(err) }));
+      }
+    }
+    return {
+      sectionId: 'credentialsStatus',
+      data: { version: 1, credentials },
+      counts: { credentials: credentials.length },
+      warnings,
+    };
+  }
+
+  async analyzeImport(_data: CredentialsSection, _ctx: ImportContext): Promise<PlanItem[]> {
+    // MissingSecret 计划项由引擎在 createImportPlan 兜底生成（analyzer.ensureMissingSecrets），
+    // 依据 = 本分区里 configured=true 的凭据 → 用户补录清单。这里保持零写入纯计算。
+    return [];
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    const ref = item.target?.ref;
+    if (!ref) return { ok: false, message: ctx.msg('adapter.missingTargetRef') };
+    const value = ctx.secretInputs[ref] ?? ctx.decryptedCredentials?.get(ref);
+    if (value === undefined || value === '') return { ok: false, message: ctx.msg('adapter.credentialValueMissing') };
+    await ctx.target.credentials.set(ref, value);
+    return { ok: true };
+  }
+
+  async validate(data: CredentialsSection, 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: 'credentials' }), 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.credentials)) {
+      issues.push({ path: 'credentials', message: msg('adapter.validate.array', { subject: 'credentials' }), severity: 'error' });
+    } else {
+      for (const c of data.credentials) {
+        if (c === null || typeof c !== 'object' || typeof c.ref !== 'string' || c.ref === '') {
+          issues.push({ path: 'credentials[]', message: msg('adapter.validate.credentialRef'), severity: 'error' });
+        }
+        if (c.hasValue === true) {
+          // 安全不变量：普通导出恒不携带值；若备份声称有值，视为结构异常
+          issues.push({ path: `credentials.${c.ref}.hasValue`, message: msg('adapter.validate.hasValueFalse'), severity: 'error' });
+        }
+      }
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}

package/src/adapters/file-collection.ts

@@ -0,0 +1,137 @@
+/**
+ * 文件类分区共享 adapter 基类（skills / agentPresets / sessions 复用；
+ * agentInstructions 因位于 homeDir 根、只能白名单收集，覆写 export 后复用本类其余逻辑）。
+ * 基准目录与 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 { isReservedInternalRel, normalizePath } from '../utils/paths.ts';
+import { msgOf, zhMsg } from '../core/messages.ts';
+import type { MsgFunc } from '../core/messages.ts';
+import { linkWarnings, listFilesDetailed } from './link-report.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.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[] = [];
+    // issue #37：用「跟随 junction/符号链接」的遍历，并把跟随/跳过的链接写进告警——
+    // 此前链接目录及其全部内容被静默排除，备份仍报成功。
+    let listing: RecursiveListing = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
+    try {
+      listing = await listFilesDetailed(ctx.fs, this.baseDir);
+    } catch {
+      // 目录不存在视为空
+    }
+    const rels = listing.paths;
+    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(msgOf(ctx)('adapter.dirEmpty', { type: this.displayName }));
+    warnings.push(...linkWarnings(msgOf(ctx), this.displayName, listing));
+    return {
+      sectionId: this.id,
+      data: { version: 1, files },
+      counts: { files: files.length },
+      warnings,
+    };
+  }
+
+  async analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]> {
+    const msg = ctx.msg;
+    const items: PlanItem[] = [];
+    for (const file of data.files) {
+      const id = `${this.id}:${file.relativePath}`;
+      // F23 修复：不可信 import 不得写内部 control-plane namespace。
+      // 检查 baseDir+ref 解析后的 homeDir 相对路径（self 适配器 baseDir='dsh-config-manager' 是主投毒向量）。
+      const resolvedRel = normalizePath(path.join(this.baseDir, file.relativePath));
+      if (isReservedInternalRel(resolvedRel)) {
+        items.push({
+          id, kind: 'Error', adapter: this.id,
+          description: msg('adapter.fileReserved', { path: file.relativePath }), severity: 'error',
+        });
+        continue;
+      }
+      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: msg('adapter.fileCreate', { type: this.displayName, path: 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: msg('adapter.fileSame', { path: file.relativePath }), severity: 'info' });
+      } else {
+        items.push({
+          id, kind: 'Conflict', adapter: this.id,
+          description: msg('adapter.fileDiff', { path: file.relativePath }), severity: 'warning',
+          target: { adapter: this.id, ref: file.relativePath },
+        });
+      }
+    }
+    return items;
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    const msg = ctx.msg;
+    const ref = item.target?.ref;
+    if (!ref) return { ok: false, message: msg('adapter.missingTargetRef') };
+    // F23 修复：apply 前拒绝写内部 control-plane namespace（纵深防御，analyzeImport 已标 Error）
+    const resolvedRel = normalizePath(path.join(this.baseDir, ref));
+    if (isReservedInternalRel(resolvedRel)) {
+      return { ok: false, message: msg('adapter.fileReserved', { path: 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: msg('adapter.dataMissingFile', { ref }) };
+    await ctx.target.fs.writeFile(path.join(this.baseDir, 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.fileSection'), 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' });
+    } else {
+      for (const f of data.files) {
+        if (f === null || typeof f !== 'object' || typeof f.relativePath !== 'string' || f.relativePath === '') {
+          issues.push({ path: 'files[]', message: msg('adapter.validate.fileRelativePath'), 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,353 @@
+/**
+ * 文件类分区 adapter 测试（skills / agentPresets / agentInstructions / 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 { AgentInstructionsAdapter } from './agent-instructions.ts';
+import { PluginFilesAdapter } from './plugin-files.ts';
+import { SessionsAdapter } from './sessions.ts';
+import { SelfAdapter } from './self.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('issue #37: skills 导出把「跟随/跳过的链接」写进 warnings（不再静默缺失）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  await src.fs.writeFile('skills/coding.md', Buffer.from('# Coding\n', 'utf8'));
+  // 链接目录下的真实内容（链接已跟随 → 内容确实可读）
+  await src.fs.writeFile('skills/shared/inner.md', Buffer.from('# Shared\n', 'utf8'));
+  // 宿主实现 listRecursiveDetailed（真实 FileSystemFacade 的形态）：链接内容已收集，且带诊断
+  src.fs.listRecursiveDetailed = async () => ({
+    paths: ['skills/coding.md', 'skills/shared/inner.md'],
+    skippedLinks: [{ path: 'skills/broken', reason: 'broken' }],
+    followedLinks: 1,
+    unreadableDirs: [],
+  });
+  const out = await new SkillsAdapter().export(src, { includeSecrets: false });
+  assert.deepEqual(out.data.files.map((f) => f.relativePath).sort(), ['coding.md', 'shared/inner.md']);
+  assert.equal(out.warnings.some((w) => w.includes('链接目录')), true, `缺「已跟随链接」告警: ${out.warnings.join(' | ')}`);
+  assert.equal(out.warnings.some((w) => w.includes('未进备份')), true, `缺「跳过链接」告警: ${out.warnings.join(' | ')}`);
+  assert.equal(out.warnings.some((w) => w.includes('skills/broken')), true, '必须点名被跳过的链接');
+});
+
+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('agentInstructions: 只收集 homeDir 根 AGENTS.md（白名单）+ 导入往返', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  await src.fs.writeFile('AGENTS.md', Buffer.from('# Global rules\nAlways reply in Chinese.\n', 'utf8'));
+  // 根目录其他文件不得被收集（不能整目录递归）
+  await src.fs.writeFile('settings.yaml', Buffer.from('foo: bar\n', 'utf8'));
+
+  const adapter = new AgentInstructionsAdapter();
+  assert.equal(adapter.defaultIncluded, true, 'agentInstructions 默认导出');
+  assert.equal(adapter.portability, 'portable');
+  const out = await adapter.export(src, { includeSecrets: false });
+  assert.equal(out.data.files.length, 1);
+  assert.equal(out.data.files[0]?.relativePath, 'AGENTS.md');
+  assert.equal(out.data.files[0]?.contentHash, sha256Hex(Buffer.from('# Global rules\nAlways reply in Chinese.\n')));
+  assert.equal(out.warnings.length, 0, '存在文件时不告警');
+
+  const sections = new Map([['agentInstructions', out.data]]);
+  const dst = makeContext('linux', '/home/bob');
+  const items = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  assert.equal(items.length, 1);
+  assert.equal(items[0]?.kind, 'Create');
+  const r = await adapter.applyItem(items[0]!, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  assert.equal(
+    Buffer.from(await dst.fs.readFile('AGENTS.md')).toString(),
+    '# Global rules\nAlways reply in Chinese.\n',
+    '导入写回 $DSH_HOME/AGENTS.md（homeDir 根）',
+  );
+
+  // 幂等：一致 → Skip；内容不同 → Conflict
+  let items2 = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  assert.equal(items2[0]?.kind, 'Skip');
+  await dst.fs.writeFile('AGENTS.md', Buffer.from('# Changed\n', 'utf8'));
+  items2 = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  assert.equal(items2[0]?.kind, 'Conflict');
+});
+
+test('agentInstructions: 文件缺失 → 空分区 + dirEmpty 警告', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  const adapter = new AgentInstructionsAdapter();
+  const out = await adapter.export(src, { includeSecrets: false });
+  assert.equal(out.data.files.length, 0);
+  assert.ok(out.warnings.length > 0, '缺失时给出提示（与 skills 目录为空一致）');
+});
+
+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('pluginFiles: 约定配置目录递归收集 + 与白名单去重 + 导入映射写回', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  // 约定目录下的文件（含嵌套子目录）
+  await src.fs.writeFile('plugin-config/pluginA/a.json', Buffer.from('{"a":1}', 'utf8'));
+  await src.fs.writeFile('plugin-config/pluginA/sub/b.toml', Buffer.from('b=2', 'utf8'));
+  // 白名单文件
+  await src.fs.writeFile('dsh-ssh.json', Buffer.from('{"hosts":[]}', 'utf8'));
+  // 白名单里显式点到的文件同时位于约定目录内 → 应去重，只收集一次
+  //（whitelist 用与 collectDir 相同的相对路径 plugin-config/pluginA/a.json）
+
+  // whitelist 命中约定目录内同路径文件：a.json 同时由白名单与目录收集 → 去重
+  const whitelist = ['dsh-ssh.json', 'plugin-config/pluginA/a.json'];
+  const adapter = new PluginFilesAdapter(whitelist, 'plugin-config');
+  const out = await adapter.export(src, { includeSecrets: false });
+  const rels = out.data.files.map((f) => f.relativePath).sort();
+  // 白名单 dsh-ssh.json + 目录 a.json、sub/b.toml（a.json 白名单/目录交叉去重，只出现一次）
+  assert.deepEqual(rels, ['dsh-ssh.json', 'plugin-config/pluginA/a.json', 'plugin-config/pluginA/sub/b.toml']);
+
+  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.length, 3);
+  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('dsh-ssh.json')).toString(), '{"hosts":[]}');
+  assert.equal(Buffer.from(await dst.fs.readFile('plugin-config/pluginA/sub/b.toml')).toString(), 'b=2');
+  assert.equal(Buffer.from(await dst.fs.readFile('plugin-config/pluginA/a.json')).toString(), '{"a":1}');
+});
+
+test('pluginFiles: 非法 collectDir（绝对路径/越界）构造即抛错', () => {
+  assert.throws(() => new PluginFilesAdapter(undefined, 'C:\\evil'), /collectDir 非法/);
+  assert.throws(() => new PluginFilesAdapter(undefined, '../escape'), /collectDir 非法/);
+});
+
+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('F23: pluginFiles 拒绝 `..` 路径穿越变体写入保留区（Reviewer B P0）', async () => {
+  const adapter = new PluginFilesAdapter();
+  const dst = makeContext('linux', '/home/bob');
+  // 宿主 fs 会 resolve/join 折叠 `..` → 这些路径落到保留区，必须在 adapter 层拒绝
+  const malicious = [
+    'dsh-config-manager/../dsh-config-manager/snapshots/fake/snapshot.json',
+    'dsh-config-manager/../dsh-config-manager/transactions/active/x.json',
+    'x/../../dsh-config-manager/locks/environment.lock',
+    'dsh-config-manager/./snapshots/fake/blob-1',
+  ];
+  const data = {
+    version: 1 as const,
+    files: malicious.map((relativePath) => ({
+      relativePath,
+      data: Buffer.from('{}', 'utf8'),
+      contentHash: sha256Hex(Buffer.from('{}')),
+    })),
+  };
+  const ctx = makeImportContext(dst, new Map([['pluginFiles', data]]));
+  const items = await adapter.analyzeImport(data, ctx);
+  for (const item of items) {
+    assert.equal(item.kind, 'Error', `analyzeImport 应拒绝 ${item.target?.ref ?? item.description}`);
+    const r = await adapter.applyItem(item, ctx);
+    assert.equal(r.ok, false);
+  }
+  // 纵深防御：apply 阶段直接命中也必须拒绝
+  for (const rel of malicious) {
+    const r = await adapter.applyItem(
+      { id: `x:${rel}`, kind: 'Create', adapter: 'pluginFiles', description: rel, severity: 'info', target: { adapter: 'pluginFiles', ref: rel } } as PlanItem,
+      ctx,
+    );
+    assert.equal(r.ok, false, `applyItem 拒绝 .. 变体 ${rel}`);
+  }
+});
+
+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);
+});
+
+// ---------- F23：不可信 import 不得写内部 control-plane namespace ----------
+
+test('F23: pluginFiles 拒绝写内部 recovery/control-plane 保留区（快照/事务/锁）', async () => {
+  const adapter = new PluginFilesAdapter();
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  const malicious = [
+    'dsh-config-manager/snapshots/fake/snapshot.json',
+    'dsh-config-manager/snapshots/fake/blob-1',
+    'dsh-config-manager/transactions/active/x.json',
+    'dsh-config-manager/transactions/safe-mode',
+    'dsh-config-manager/locks/environment.lock',
+    'dsh-config-manager/environment-fingerprint.token',
+  ];
+  // 攻击者构造 ZIP 数据：把普通插件文件条目映射到内部 recovery 存储
+  const data = {
+    version: 1 as const,
+    files: malicious.map((relativePath) => ({
+      relativePath,
+      data: Buffer.from('{}', 'utf8'),
+      contentHash: sha256Hex(Buffer.from('{}')),
+    })),
+  };
+  const sections = new Map([['pluginFiles', data]]);
+  const ctx = makeImportContext(src, sections);
+  const items = await adapter.analyzeImport(data, ctx);
+  for (const item of items) {
+    assert.equal(item.kind, 'Error', `analyzeImport 应拒绝 ${item.target?.ref ?? item.description}`);
+    const r = await adapter.applyItem(item, ctx);
+    assert.equal(r.ok, false, `applyItem 应拒绝 ${item.target?.ref ?? item.description}`);
+  }
+  // 纵深防御：应用阶段直接命中保留区也必须拒绝（即使 analyzeImport 被绕过）
+  for (const rel of malicious) {
+    const r = await adapter.applyItem(
+      { id: `x:${rel}`, kind: 'Create', adapter: 'pluginFiles', description: rel, severity: 'info', target: { adapter: 'pluginFiles', ref: rel } } as PlanItem,
+      ctx,
+    );
+    assert.equal(r.ok, false, `applyItem 直接命中 ${rel} 应拒绝`);
+  }
+  // 关键：不得真正写入 control-plane 存储
+  for (const rel of malicious) {
+    assert.equal(await src.fs.exists(rel), false, `不得写入保留路径 ${rel}`);
+  }
+});
+
+test('F23: self adapter 拒绝写内部 recovery/control-plane 保留区（但放行合法配置）', async () => {
+  const adapter = new SelfAdapter('dsh-config-manager');
+  const dst = makeContext('linux', '/home/bob');
+  // 合法：sync-config.json 是 self 白名单配置，必须放行
+  const legitFiles = [
+    'sync/sync-config.json',
+    'sync/sync-selection.json',
+    'sync/ui-prefs.json',
+    'sync/backup-schedule.json',
+    'market/market-config.json',
+    'exports/.backup-notes.json',
+  ];
+  const legitData = {
+    version: 1 as const,
+    files: legitFiles.map((relativePath) => ({
+      relativePath,
+      data: Buffer.from('{}', 'utf8'),
+      contentHash: sha256Hex(Buffer.from('{}')),
+    })),
+  };
+  const legitSections = new Map([['self', legitData]]);
+  const legitCtx = makeImportContext(dst, legitSections);
+  const legitItems = await adapter.analyzeImport(legitData, legitCtx);
+  assert.ok(legitItems.every((i) => i.kind !== 'Error'), '合法 self 配置不得被保留区误伤');
+  for (const item of legitItems) {
+    const r = await adapter.applyItem(item, legitCtx);
+    if (r.ok === false) continue; // 同名冲突等非 F23 因素允许
+  }
+
+  // 恶意：把条目映射到内部 recovery 存储
+  const malicious = [
+    'snapshots/fake/snapshot.json',
+    'transactions/active/x.json',
+    'locks/environment.lock',
+    'sync/snapshots/fake/manifest.json', // sync rollback snapshot store
+    'sync/work/tmp.zip',
+  ];
+  const evilData = {
+    version: 1 as const,
+    files: malicious.map((relativePath) => ({
+      relativePath,
+      data: Buffer.from('{}', 'utf8'),
+      contentHash: sha256Hex(Buffer.from('{}')),
+    })),
+  };
+  const evilSections = new Map([['self', evilData]]);
+  const evilCtx = makeImportContext(dst, evilSections);
+  const evilItems = await adapter.analyzeImport(evilData, evilCtx);
+  assert.equal(evilItems.length, malicious.length);
+  for (const item of evilItems) {
+    assert.equal(item.kind, 'Error', `self analyzeImport 应拒绝 ${item.target?.ref ?? item.description}`);
+    const r = await adapter.applyItem(item, evilCtx);
+    assert.equal(r.ok, false);
+  }
+  const resolved = malicious.map((rel) => `dsh-config-manager/${rel}`);
+  for (const rel of resolved) {
+    assert.equal(await dst.fs.exists(rel), false, `不得写入保留路径 ${rel}`);
+  }
+});