dsh-config-manager 0.1.71 → 0.1.73

package/src/adapters/plugin-data.test.ts

@@ -0,0 +1,225 @@
+/**
+ * PluginDataAdapter 单测（pluginData / pluginAssets 两个分区）。
+ *
+ * 覆盖四件必须成立的事：
+ *  ① 收录口径：配置 / 大资产各进各的分区；**可再生成缓存永不出现**；
+ *  ② 单元 = 区域（选择器按区域勾选；预览与导出体积同口径）；
+ *  ③ 环境变量覆盖：报码跳过、不猜新位置；「设成同一个值」不算覆盖；
+ *  ④ 导入白名单：只有本机内置来源 / 已安装插件自述声明之下的路径才允许写，
+ *     其余（含 .credentials.yaml 这类敏感文件）判 Error 且 applyItem 也拒绝。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { PluginDataAdapter } from './plugin-data.ts';
+import { makeContext, makeImportContext, sha256Hex } from './test-helpers.ts';
+import type { PluginDataSource } from '../core/plugin-data-registry.ts';
+import type { FilesSection } from '../schema/types.ts';
+
+const HOME = 'C:\\Users\\alice';
+const bytes = (s: string): Uint8Array => Buffer.from(s, 'utf8');
+
+/**
+ * 测试用的宿主上下文：**把系统 home 与 $DSH_HOME 指向同一个内存根**。
+ *
+ * 真机上两者不同（$DSH_HOME = ~/.dsh），而这两个分区的根是**系统 home** —— 单测里合并成一个根
+ * 只是让夹具短；两者不同的真机形态由 tests/e2e/plugin-data-migration.test.ts 覆盖。
+ */
+function ctxFor(home: string, profile = 'web') {
+  const ctx = makeContext('win32', home, profile);
+  ctx.osHomeDir = home;
+  ctx.homeFs = ctx.fs;
+  return ctx;
+}
+
+/** 真机形态的假数据：wallpaper-engine 的配置 + 缓存 + 上传的壁纸；mnemon 的运行时与数据库 */
+async function seedHome(ctx: ReturnType<typeof makeContext>): Promise<void> {
+  await ctx.fs.writeFile('.dsh-wallpaper-engine/config.json', bytes('{"wallpaper":"a"}'));
+  await ctx.fs.writeFile('.dsh-wallpaper-engine/cache/frame.bin', bytes('cache'));
+  await ctx.fs.writeFile('.dsh-wallpaper-engine/uploads/wall.mp4', bytes('video'));
+  await ctx.fs.writeFile('.mnemon/runtime/MEMORY.md', bytes('memory'));
+  await ctx.fs.writeFile('.mnemon/data/body.db', bytes('db'));
+}
+
+test('收录口径：配置分区只带配置，资产分区只带大资产，缓存永不出现', async () => {
+  const ctx = ctxFor(HOME);
+  await seedHome(ctx);
+
+  const config = new PluginDataAdapter('pluginData', { env: {} });
+  const configOut = await config.export(ctx, { includeSecrets: false });
+  assert.deepEqual(
+    configOut.data.files.map((f) => f.relativePath).sort(),
+    ['.dsh-wallpaper-engine/config.json', '.mnemon/runtime/MEMORY.md'],
+  );
+  assert.equal(configOut.data.files[0]?.contentHash, sha256Hex(bytes('{"wallpaper":"a"}')));
+
+  const assets = new PluginDataAdapter('pluginAssets', { env: {} });
+  const assetOut = await assets.export(ctx, { includeSecrets: false });
+  assert.deepEqual(
+    assetOut.data.files.map((f) => f.relativePath).sort(),
+    ['.dsh-wallpaper-engine/uploads/wall.mp4', '.mnemon/data/body.db'],
+  );
+
+  // 缓存绝不出现（两个分区都不许）
+  for (const out of [configOut, assetOut]) {
+    assert.ok(!out.data.files.some((f) => f.relativePath.includes('/cache/')), '缓存必须被排除');
+  }
+});
+
+test('单元 = 区域：单元 id 就是区域路径，且预览与导出的体积同口径', async () => {
+  const ctx = ctxFor(HOME);
+  await seedHome(ctx);
+  const adapter = new PluginDataAdapter('pluginData', { env: {} });
+
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  const units = adapter.listUnits(out);
+  assert.deepEqual(units.map((u) => u.id).sort(), ['pluginData:.dsh-wallpaper-engine', 'pluginData:.mnemon/runtime']);
+  assert.equal(units.find((u) => u.id === 'pluginData:.mnemon/runtime')?.fileCount, 1);
+
+  const preview = await adapter.preview(ctx, { includeSecrets: false });
+  assert.deepEqual(preview.items, units, '预览单元必须与导出单元逐项一致');
+  assert.equal(
+    preview.sizeBytes,
+    out.data.files.reduce((n, f) => n + f.data.byteLength, 0),
+  );
+
+  // 条目级选择：只勾 mnemon 运行时
+  const only = await adapter.export(ctx, { includeSecrets: false, includeItems: { pluginData: ['pluginData:.mnemon/runtime'] } });
+  assert.deepEqual(only.data.files.map((f) => f.relativePath), ['.mnemon/runtime/MEMORY.md']);
+});
+
+test('环境变量覆盖：报码跳过、不猜位置；设成与默认相同不算覆盖', async () => {
+  const ctx = ctxFor(HOME);
+  await seedHome(ctx);
+
+  const moved = new PluginDataAdapter('pluginData', { env: { DSH_WE_DATA_DIR: 'D:\\wallpapers' } });
+  const movedOut = await moved.export(ctx, { includeSecrets: false });
+  assert.deepEqual(
+    movedOut.data.files.map((f) => f.relativePath),
+    ['.mnemon/runtime/MEMORY.md'],
+    '被覆盖的区域不得被读成「默认位置」，未被覆盖的来源照常收录',
+  );
+  assert.ok(movedOut.warnings.some((w) => w.includes('DSH_WE_DATA_DIR')), '必须如实报出是哪个变量覆盖了它');
+
+  const assetsMoved = new PluginDataAdapter('pluginAssets', { env: { DSH_WE_UPLOAD_DIR: '~/pics' } });
+  const assetsOut = await assetsMoved.export(ctx, { includeSecrets: false });
+  assert.deepEqual(assetsOut.data.files.map((f) => f.relativePath), ['.mnemon/data/body.db'], '只跳过被覆盖的那一个区域');
+
+  const same = new PluginDataAdapter('pluginData', { env: { DSH_WE_DATA_DIR: '~/.dsh-wallpaper-engine' } });
+  const sameOut = await same.export(ctx, { includeSecrets: false });
+  assert.equal(sameOut.data.files.length, 2, '值等于默认位置 → 不算覆盖');
+});
+
+test('导入白名单：包外路径一律 Error，applyItem 也拒绝；包内路径正常写回', async () => {
+  const src = ctxFor(HOME);
+  await seedHome(src);
+  const adapter = new PluginDataAdapter('pluginData', { env: {} });
+  const out = await adapter.export(src, { includeSecrets: false });
+
+  const evil: FilesSection = {
+    version: 1,
+    files: [
+      ...out.data.files,
+      { relativePath: '.credentials.yaml', data: bytes('token: x'), contentHash: sha256Hex(bytes('token: x')) },
+      { relativePath: '.dsh-wallpaper-engine/uploads/wall.mp4', data: bytes('video'), contentHash: sha256Hex(bytes('video')) },
+    ],
+  };
+
+  const dst = ctxFor('/home/bob');
+  const sections = new Map<string, unknown>([['pluginData', evil]]);
+  const items = await adapter.analyzeImport(evil, makeImportContext(dst, sections));
+
+  const denied = items.filter((i) => i.kind === 'Error');
+  assert.equal(denied.length, 2, '包外路径 + 资产路径（走配置分区）都必须被拒');
+  assert.ok(denied.every((i) => i.description.includes('拒绝')), '拒绝理由必须可见');
+
+  const allowed = items.filter((i) => i.kind === 'Create');
+  assert.equal(allowed.length, 2);
+  for (const item of allowed) {
+    const r = await adapter.applyItem(item, makeImportContext(dst, sections));
+    assert.equal(r.ok, true);
+  }
+  assert.equal(Buffer.from(await dst.fs.readFile('.mnemon/runtime/MEMORY.md')).toString(), 'memory');
+
+  // 纵深防御：手工构造一个指向包外的计划项，applyItem 也必须拒绝
+  const forged = await adapter.applyItem(
+    { id: 'x', kind: 'Create', adapter: 'pluginData', description: '', severity: 'info', target: { adapter: 'pluginData', ref: 'AGENTS.md' } },
+    makeImportContext(dst, sections),
+  );
+  assert.equal(forged.ok, false);
+  assert.equal(await dst.fs.exists('AGENTS.md'), false);
+});
+
+test('自述声明（dsh.dataDirs）：已安装插件的区域可导出、可导入；未声明的插件目录仍被拒', async () => {
+  const ctx = ctxFor(HOME);
+  await ctx.fs.writeFile('profiles/web/package.json', bytes(JSON.stringify({ dependencies: { 'dsh-fake': '^1.0.0' } })));
+  await ctx.fs.writeFile(
+    'profiles/web/node_modules/dsh-fake/package.json',
+    bytes(JSON.stringify({ name: 'dsh-fake', dsh: { dataDirs: [{ path: '.fake-plugin', role: 'config', env: ['FAKE_DIR'] }] } })),
+  );
+  await ctx.fs.writeFile('.fake-plugin/state.json', bytes('{"a":1}'));
+
+  const adapter = new PluginDataAdapter('pluginData', { env: {} });
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  assert.deepEqual(out.data.files.map((f) => f.relativePath), ['.fake-plugin/state.json']);
+  assert.deepEqual(adapter.listUnits(out).map((u) => u.id), ['pluginData:.fake-plugin']);
+
+  // 目标机也装了同一个插件 → 声明可解析 → 允许写
+  const dst = ctxFor('/home/bob');
+  await dst.fs.writeFile('profiles/web/package.json', bytes(JSON.stringify({ dependencies: { 'dsh-fake': '^1.0.0' } })));
+  await dst.fs.writeFile(
+    'profiles/web/node_modules/dsh-fake/package.json',
+    bytes(JSON.stringify({ name: 'dsh-fake', dsh: { dataDirs: [{ path: '.fake-plugin', role: 'config' }] } })),
+  );
+  const sections = new Map<string, unknown>([['pluginData', out.data]]);
+  const items = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  assert.deepEqual(items.map((i) => i.kind), ['Create']);
+
+  // 换一台机器（没装该插件、也没声明）→ 同一份包必须被拒，绝不静默写到未知位置
+  const fresh = ctxFor('/home/carol');
+  const freshItems = await adapter.analyzeImport(out.data, makeImportContext(fresh, sections));
+  assert.deepEqual(freshItems.map((i) => i.kind), ['Error']);
+});
+
+test('空形态：一个区域都不存在时不报错、不加噪音文件（只有 dirEmpty 告警）', async () => {
+  const ctx = ctxFor(HOME);
+  const adapter = new PluginDataAdapter('pluginData', { env: {} });
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  assert.deepEqual(out.data.files, []);
+  assert.equal(out.counts.files, 0);
+});
+
+test('旧宿主（没有系统 home 门面）：不收集也不导入，并如实报码 —— 绝不退回 $DSH_HOME 读错位置', async () => {
+  // 注意：这里**故意**用未接线的上下文（homeFs 缺省 undefined）
+  const ctx = makeContext('win32', HOME, 'web');
+  await ctx.fs.writeFile('.dsh-wallpaper-engine/config.json', bytes('{"a":1}'));
+  const adapter = new PluginDataAdapter('pluginData', { env: {} });
+
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  assert.deepEqual(out.data.files, [], '缺门面时不得在 $DSH_HOME 下按同名相对路径去读');
+  assert.ok(out.warnings.some((w) => w.includes('系统主目录')), '必须如实说明为什么什么都没收集');
+
+  const sections = new Map<string, unknown>([['pluginData', {
+    version: 1,
+    files: [{ relativePath: '.dsh-wallpaper-engine/config.json', data: bytes('{"a":1}'), contentHash: sha256Hex(bytes('{"a":1}')) }],
+  }]]);
+  const target = makeContext('linux', '/home/bob', 'web');
+  const items = await adapter.analyzeImport(
+    { version: 1, files: [{ relativePath: '.dsh-wallpaper-engine/config.json', data: bytes('{"a":1}'), contentHash: sha256Hex(bytes('{"a":1}')) }] },
+    makeImportContext(target, sections),
+  );
+  assert.deepEqual(items.map((i) => i.kind), ['Error']);
+  assert.equal(await target.fs.exists('.dsh-wallpaper-engine/config.json'), false);
+});
+
+test('注入假来源：来源表可替换（测试与未来扩展都走同一条路）', async () => {
+  const ctx = ctxFor(HOME);
+  await ctx.fs.writeFile('.my-plugin/a.json', bytes('{}'));
+  const fake: PluginDataSource[] = [{
+    id: 'fake', packages: ['x'], evidence: 'fixture',
+    areas: [{ relPath: '.my-plugin', role: 'config' }],
+  }];
+  const adapter = new PluginDataAdapter('pluginData', { sources: fake, env: {} });
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  assert.deepEqual(out.data.files.map((f) => f.relativePath), ['.my-plugin/a.json']);
+});

package/src/adapters/plugin-data.ts

@@ -0,0 +1,351 @@
+/**
+ * pluginData / pluginAssets 分区 adapter（第三方插件数据迁移）。
+ *
+ * 数据来源 = \`src/core/plugin-data-registry.ts\` 的来源注册表：内置已取证来源 + 已安装插件在
+ * 自己 package.json 里声明的 \`dsh.dataDirs\`。每个「区域（area）」在备份里是**一个可勾选单元**，
+ * 单元 id = 区域的 home 相对 POSIX 路径（如 \`.dsh-wallpaper-engine/uploads\`）——
+ * 用户能在导出选择器里逐区域看到「几个文件 / 多大」，也能只带走配置、不带几百 MB 的上传壁纸。
+ *
+ * 为什么两个分区而不是一个：
+ *  - \`pluginData\` = 配置与轻量状态；\`pluginAssets\` = 大体积用户数据（上传的壁纸、本地数据库）；
+ *  - 「默认不勾选大资产」在既有 UI 选择模型里**只有分区级开关**这一条可靠通道（单元级只有
+ *    「默认全选 + 稀疏排除」，没有「默认排除」的概念）—— 拆成两个分区后，「可见但默认不勾选」
+ *    就是既有的 \`defaultIncluded=false\` 语义，不需要动共享选择模型，也不会与导入/市场两处选择语义打架。
+ *
+ * 实现：继承 FileCollectionAdapter（baseDir = ''，即 home 根；与 agentInstructions 同一形态），
+ * 复用它的单元分组 / 单分区字节闸门 / 预览-导出一致性 / 幂等哈希比对；只覆写三处：
+ *  ① \`listRelPaths()\` —— 清单来自来源注册表（并如实记录被环境变量覆盖而跳过的区域）；
+ *  ② \`unitIdOf()\` —— 单元 = 区域（最长前缀归属）；
+ *  ③ \`analyzeImport() / applyItem()\` —— **写入路径白名单**（见下）。
+ *
+ * 安全不变量（本分区是全仓唯一「按 home 相对路径任意写」的分区，必须自己守住）：
+ *  - **导入白名单**：只有「本机内置来源的区域」与「本机已安装插件声明的区域」之下的路径才允许写。
+ *    恶意/损坏的包想把 \`.credentials.yaml\` 或 \`AGENTS.md\` 塞进来，在这里被判 Error（计划里可见，
+ *    执行期不写）；applyItem 再查一遍（纵深防御），内层还有基类的 control-plane namespace 拒绝。
+ *  - **缓存永不收录**：role === 'cache' 的区域不属于任何分区，导出时根本不进清单。
+ *  - **环境变量覆盖即跳过**：区域声明的 env 存在且解析结果与默认位置不同 → 报码跳过，绝不猜新位置。
+ *  - **不产生用户可见散文**：告警与计划项文案一律走消息目录（i18n 铁律）。
+ */
+import { normalizePath } from '../utils/paths.ts';
+import { engineMsg } from './messages.ts';
+import { listFilesDetailed } from './link-report.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
+import { sectionMeta } from '../schema/section-registry.ts';
+import {
+  BUILTIN_PLUGIN_DATA_SOURCES, areaOfPath, areasForSection, isExcludedRel, normalizeHomeRel,
+  parseDeclaredDataDirs,
+} from '../core/plugin-data-registry.ts';
+import type { PluginDataArea, PluginDataSource, PluginDataSection } from '../core/plugin-data-registry.ts';
+import { osHomeDirOf } from '../core/backup.ts';
+import { FileCollectionAdapter } from './file-collection.ts';
+import type { FilesSection } from '../schema/types.ts';
+import type {
+  ApplyResult, ExportOptions, ExportSection, FileSystemFacade, HostContext, ImportContext, PlanItem,
+  SectionPreview,
+} from '../core/types.ts';
+
+/** 区域条目（来源 + 区域），编译期与运行期唯一的区域表示 */
+export type PluginDataEntry = { source: PluginDataSource; area: PluginDataArea };
+
+/** 声明来源缓存的 TTL（毫秒）：一次导出/导入/执行里会多次解析，逐次读 15+ 个 package.json 是净开销 */
+const DECLARED_TTL_MS = 5_000;
+
+/** 单次解析里最多读取多少个已安装插件的 manifest（防御性上限：profile 依赖数量异常时不无限读） */
+const MAX_DECLARED_PACKAGES = 300;
+
+export interface PluginDataAdapterOptions {
+  /** 内置来源（缺省 = BUILTIN_PLUGIN_DATA_SOURCES；测试注入假来源） */
+  readonly sources?: readonly PluginDataSource[];
+  /** 自述声明缓存 TTL；测试可传 0 关闭缓存 */
+  readonly declaredTtlMs?: number;
+  /**
+   * 环境变量快照（缺省 process.env）。
+   *
+   * 为什么走构造参数而不是 HostContext：HostContext 上没有 env（它是宿主门面的集合），
+   * 而「区域被环境变量搬走」这件事必须在**同一次调用**里可判定、可注入测试值 ——
+   * 直接读 process.env 会让单测无法造「被覆盖」的场景（本机若恰好设了该变量，测试还会 flaky）。
+   */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+
+export class PluginDataAdapter extends FileCollectionAdapter {
+  readonly id: PluginDataSection;
+  readonly displayName: string;
+  readonly defaultIncluded = false;
+  readonly portability = 'deviceSpecific' as const;
+  /** home 根（相对路径 = home 相对路径，与 agentInstructions 同形） */
+  readonly baseDir = '';
+
+  private readonly builtin: readonly PluginDataSource[];
+  private readonly declaredTtlMs: number;
+  private readonly env: Readonly<Record<string, string | undefined>>;
+  /**
+   * 自述声明缓存。**必须带 ctx 键**（homeDir + profile）：这台机器装了某插件，不代表另一台装了 ——
+   * 缓存若按实例共享，导入到「没装该插件」的目标机时会拿源机的声明去放行写入，
+   * 白名单就变成了「谁先导入谁说了算」。
+   */
+  private declaredMemo: { key: string; at: number; sources: PluginDataSource[] } | undefined;
+  /** 本轮清单（listRelPaths 写入；unitIdOf 是同步纯函数，只能从这里拿区域表） */
+  private active: readonly PluginDataEntry[] | undefined;
+  /** 本轮告警（环境变量覆盖跳过等；export/preview 收尾合并进返回的 warnings） */
+  private pendingWarnings: string[] = [];
+
+  constructor(section: PluginDataSection, options: PluginDataAdapterOptions = {}) {
+    super();
+    this.id = section;
+    this.displayName = sectionMeta(section).displayName;
+    this.builtin = options.sources ?? BUILTIN_PLUGIN_DATA_SOURCES;
+    this.declaredTtlMs = options.declaredTtlMs ?? DECLARED_TTL_MS;
+    this.env = options.env ?? process.env;
+  }
+
+  /** 本分区可收集区域（内置 + 自述声明） */
+  private async allowedEntries(ctx: HostContext): Promise<readonly PluginDataEntry[]> {
+    const sources = await this.allSources(ctx);
+    return areasForSection(sources, this.id);
+  }
+
+  private async allSources(ctx: HostContext): Promise<readonly PluginDataSource[]> {
+    const declared = await this.declaredSources(ctx);
+    return [...this.builtin, ...declared];
+  }
+
+  /**
+   * 已安装插件的自述声明（dsh.dataDirs）。
+   *
+   * 为什么读 profile 的 node_modules 而不是全局目录：DSH 的插件装在 \`profiles/<profile>/node_modules\`
+   * 下（pnpm 隔离布局），且同一个包在不同 profile 可以是不同版本 —— 声明必须取**本 profile 实际装的**那份。
+   *
+   * 读不到（未安装 / 无声明 / 形状非法）一律跳过：本机制是**附加**信息，绝不因为一个包读不出来
+   * 就影响内置来源或整次导出。
+   */
+  private async declaredSources(ctx: HostContext): Promise<PluginDataSource[]> {
+    const now = Date.now();
+    const profile = ctx.profile !== undefined && ctx.profile !== '' ? ctx.profile : 'web';
+    const memoKey = ctx.homeDir + '|' + profile;
+    if (
+      this.declaredMemo !== undefined
+      && this.declaredMemo.key === memoKey
+      && now - this.declaredMemo.at < this.declaredTtlMs
+    ) {
+      return this.declaredMemo.sources;
+    }
+    const base = 'profiles/' + profile;
+    const out: PluginDataSource[] = [];
+    let deps: string[] = [];
+    try {
+      const raw = await ctx.fs.readFile(base + '/package.json');
+      const parsed: unknown = JSON.parse(new TextDecoder().decode(raw));
+      const dep = (parsed as { dependencies?: unknown } | null)?.dependencies;
+      if (dep !== null && typeof dep === 'object') deps = Object.keys(dep).slice(0, MAX_DECLARED_PACKAGES);
+    } catch {
+      deps = [];
+    }
+    for (const name of deps) {
+      try {
+        const raw = await ctx.fs.readFile(base + '/node_modules/' + name + '/package.json');
+        const manifest: unknown = JSON.parse(new TextDecoder().decode(raw));
+        const source = parseDeclaredDataDirs(name, manifest);
+        if (source !== null) out.push(source);
+      } catch {
+        // 未安装 / 无 manifest → 无声明，跳过
+      }
+    }
+    this.declaredMemo = { key: memoKey, at: now, sources: out };
+    return out;
+  }
+
+  /**
+   * 区域是否被环境变量覆盖（覆盖 → 返回变量名；未覆盖 / 未声明 → null）。
+   *
+   * 判定口径：变量**存在且解析结果与默认位置不同**才算覆盖 —— 仅仅 \`DSH_WE_DATA_DIR=~/.dsh-wallpaper-engine\`
+   * 这种「设成同一个值」的写法不该让区域凭空消失（那会让用户以为「没有数据」）。
+   * 解析只做 \`~\` 展开与分隔符归一（不做 realpath：不读盘、不猜）。
+   */
+  private envOverrideOf(ctx: HostContext, area: PluginDataArea): string | null {
+    for (const name of area.envOverrides ?? []) {
+      const raw = this.env[name];
+      if (raw === undefined || raw.trim() === '') continue;
+      const normalized = raw.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+      // 默认位置以**系统 home** 为根（本分区的根；见 core/backup.ts 的 OS_HOME_FILE_SECTIONS）
+      const home = osHomeDirOf(ctx).replace(/\\/g, '/').replace(/\/+$/, '');
+      const expanded = normalized.startsWith('~/') ? home + normalized.slice(1) : normalized;
+      const defaultAbs = home + '/' + area.relPath;
+      if (expanded !== defaultAbs) return name;
+    }
+    return null;
+  }
+
+  /**
+   * 区域是否是**普通文件**（而不是目录 / 不存在）。
+   *
+   * 判据顺序为什么是这样：`statSize` 对「非普通文件」与「不存在」都返回 null，无法单独区分
+   * 目录与缺失；所以先判「是文件」，其余一律按目录走遍历 —— 目录不存在时遍历返回空，
+   * 结果同样是「没有内容」，不会把缺失误报成文件，也不会把目录误读成空内容而静默丢数据。
+   * 门面未实现 statSize（旧宿主）时退回读一次内容：读得出来就是文件。
+   */
+  private async isRegularFile(fsFacade: FileSystemFacade, rel: string): Promise<boolean> {
+    if (fsFacade.statSize !== undefined) {
+      try {
+        return (await fsFacade.statSize(rel)) !== null;
+      } catch {
+        return false;
+      }
+    }
+    try {
+      await fsFacade.readFile(rel);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private static emptyListing(): RecursiveListing {
+    return { paths: [], skippedLinks: [], skippedDepDirs: [], followedLinks: 0, unreadableDirs: [] };
+  }
+
+  /**
+   * 清单枚举 = 来源注册表的区域（覆写基类的目录递归；baseDir='' 时基类实现会递归**整个 home**）。
+   *
+   * **必须覆写**：home 根上递归会遍历 profiles/ sessions/ attachments/ 等全部内容（本机实测
+   * 4000+ 文件 / 数百 MB），既慢又会把无关目录当成该分区的「可勾选单元」。
+   */
+  protected override async listRelPaths(ctx: HostContext): Promise<RecursiveListing> {
+    // 本分区的根是**系统 home**（~/.dsh-wallpaper-engine、~/.mnemon …），不是 $DSH_HOME ——
+    // 内容 I/O 一律走 homeFs；宿主没提供就什么都不收集，并如实报码（绝不退回 $DSH_HOME 去读错位置）。
+    const homeFs = ctx.homeFs;
+    if (homeFs === undefined) {
+      this.active = [];
+      this.pendingWarnings = [engineMsg('adapter.pluginDataNoOsHome')];
+      return PluginDataAdapter.emptyListing();
+    }
+    const entries = await this.allowedEntries(ctx);
+    this.active = entries;
+    const warnings: string[] = [];
+    const paths: string[] = [];
+    const listing = PluginDataAdapter.emptyListing();
+    for (const entry of entries) {
+      const rel = entry.area.relPath;
+      const env = this.envOverrideOf(ctx, entry.area);
+      if (env !== null) {
+        warnings.push(engineMsg('adapter.pluginDataEnvOverridden', { path: rel, env }));
+        continue;
+      }
+      if (await this.isRegularFile(homeFs, rel)) {
+        paths.push(rel);
+        continue;
+      }
+      let sub: RecursiveListing;
+      try {
+        sub = await listFilesDetailed(homeFs, rel);
+      } catch {
+        // 目录不存在 / 读不到 → 视为无内容（存在的空目录与缺失在这里同义：都没有文件可带）
+        continue;
+      }
+      listing.skippedLinks.push(...sub.skippedLinks);
+      listing.skippedDepDirs.push(...sub.skippedDepDirs);
+      listing.unreadableDirs.push(...sub.unreadableDirs);
+      listing.followedLinks += sub.followedLinks;
+      for (const p of sub.paths) {
+        if (isExcludedRel(entry.area, p)) continue;
+        paths.push(p);
+      }
+    }
+    listing.paths = paths;
+    this.pendingWarnings = warnings;
+    return listing;
+  }
+
+  /**
+   * 单元 = 区域（最长前缀归属）。
+   *
+   * 用「本轮清单写入的区域表」而不是重新解析：listRelPaths 与本函数在同一次 collect 里成对调用，
+   * 重算会让两次解析结果不一致时出现「单元 id 不在清单里」（选择器勾不上）。测试/异常路径下
+   * \`active\` 可能是 undefined（例如直接调 listUnits），此时退回**内置来源**的最长前缀 —— 与清单口径同源。
+   */
+  protected override unitIdOf(relativePath: string): string {
+    const entries = this.active ?? areasForSection(this.builtin, this.id);
+    const hit = areaOfPath(entries, normalizePath(relativePath));
+    return hit === null ? normalizePath(relativePath) : hit.area.relPath;
+  }
+
+  /**
+   * 读一个成员文件：**换根到系统 home 门面**（基类的其余逻辑 —— 体积、哈希、字节闸门 —— 一字不动）。
+   *
+   * 能走到这里说明 listRelPaths 产出过条目（缺门面时它不产出任何路径），因此缺门面即**抛错**，
+   * 不再造一个「空文件」出来（那会把缺通道伪装成空内容）。
+   */
+  protected override async readMember(
+    ctx: HostContext, rel: string, mode: 'content' | 'size', statTimes?: Map<string, number>,
+  ): Promise<{ data: Uint8Array; sizeBytes: number; contentHash: string }> {
+    const homeFs = ctx.homeFs;
+    if (homeFs === undefined) throw new Error(engineMsg('adapter.pluginDataNoOsHome'));
+    return super.readMember({ ...ctx, fs: homeFs }, rel, mode, statTimes);
+  }
+
+  override async export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<FilesSection>> {
+    this.pendingWarnings = [];
+    const out = await super.export(ctx, options);
+    return { ...out, warnings: [...out.warnings, ...this.pendingWarnings] };
+  }
+
+  override async preview(ctx: HostContext, options: ExportOptions): Promise<SectionPreview<FilesSection>> {
+    this.pendingWarnings = [];
+    const out = await super.preview(ctx, options);
+    return {
+      ...out,
+      section: { ...out.section, warnings: [...out.section.warnings, ...this.pendingWarnings] },
+    };
+  }
+
+  /**
+   * 导入分析 + **写入路径白名单**（本分区唯一的越界防线）。
+   *
+   * 判据：路径必须是本机可解析的某个区域（内置来源，或已安装插件的自述声明）之下，且未被该区域
+   * 的 excludeRel 排除。不满足 → Error（计划里可见、执行期不写），绝不「尽力而为」地写出去。
+   */
+  override async analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]> {
+    // 宿主没有系统 home 门面（旧宿主）→ 白名单为空 + 目标读也换不了根：**全部拒绝**并说明原因。
+    // 绝不退回 $DSH_HOME 的 ctx.fs 去比对/写入（那会落到错误位置）。
+    const homeFs = ctx.target.homeFs;
+    const entries = homeFs === undefined ? [] : await this.allowedEntries(ctx.target);
+    const items = await super.analyzeImport(
+      data,
+      homeFs === undefined ? ctx : { ...ctx, target: { ...ctx.target, fs: homeFs } },
+    );
+    return items.map((item) => {
+      const ref = item.target?.ref;
+      if (ref === undefined) return item;
+      const rel = normalizeHomeRel(ref);
+      if (rel !== null && areaOfPath(entries, rel) !== null) return item;
+      return {
+        id: item.id,
+        ...(item.unitId !== undefined ? { unitId: item.unitId } : {}),
+        kind: 'Error',
+        adapter: this.id,
+        description: engineMsg(
+          homeFs === undefined ? 'adapter.pluginDataNoOsHome' : 'adapter.pluginDataPathNotAllowed',
+          { path: ref },
+        ),
+        severity: 'error',
+      };
+    });
+  }
+
+  /** 应用前再查一遍白名单（纵深防御：plan 可能来自消费者手工构造/缓存反序列化） */
+  override async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    const homeFs = ctx.target.homeFs;
+    if (homeFs === undefined) {
+      return { ok: false, message: engineMsg('adapter.pluginDataNoOsHome') };
+    }
+    const ref = item.target?.ref;
+    if (ref !== undefined) {
+      const rel = normalizeHomeRel(ref);
+      const entries = await this.allowedEntries(ctx.target);
+      if (rel === null || areaOfPath(entries, rel) === null) {
+        return { ok: false, message: engineMsg('adapter.pluginDataPathNotAllowed', { path: ref }) };
+      }
+    }
+    return super.applyItem(item, { ...ctx, target: { ...ctx.target, fs: homeFs } });
+  }
+}

package/src/adapters/plugin-files.ts

@@ -8,6 +8,7 @@
  */
 import { sha256Hex } from '../utils/hashing.ts';
 import { msgOf, zhMsg } from '../core/messages.ts';
+import { engineMsg } from './messages.ts';
 import { linkWarnings, listFilesDetailed } from './link-report.ts';
 import type { RecursiveListing } from '../utils/recursive-walk.ts';
 import { isPathSafe, isReservedInternalRel } from '../utils/paths.ts';
@@ -36,7 +37,7 @@ export class PluginFilesAdapter implements ConfigAdapter<FilesSection> {
   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}`);
+      throw new Error(engineMsg('adapter.pluginFilesCollectDirInvalid', { dir: collectDir }));
     }
     this.collectDir = collectDir === '' ? undefined : collectDir;
   }
@@ -63,7 +64,7 @@ export class PluginFilesAdapter implements ConfigAdapter<FilesSection> {
     }
     // 2) 约定配置目录递归收集（相对 ~/.dsh 根的完整路径；与白名单文件去重）
     // issue #37：与 skills 等同一条遍历（跟随 junction/符号链接 + 跳过留痕）
-    let listing: RecursiveListing = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
+    let listing: RecursiveListing = { paths: [], skippedLinks: [], skippedDepDirs: [], followedLinks: 0, unreadableDirs: [] };
     if (this.collectDir !== undefined) {
       try {
         listing = await listFilesDetailed(ctx.fs, this.collectDir);

package/src/adapters/plugins.ts

@@ -18,6 +18,7 @@ import { classifyPluginSpec, LOCAL_PLUGIN_DIR, resolveLocalPluginPath } from '..
 import type { PackLocalPluginsResult } from '../core/local-plugin-pack.ts';
 import { msgOf, zhMsg } from '../core/messages.ts';
 import type { MsgFunc } from '../core/messages.ts';
+import { engineMsg } from './messages.ts';
 import { stringifyJsonSafe } from '../utils/json.ts';
 import { isPathSafe, normalizePath } from '../utils/paths.ts';
 import { isENOENT } from '../utils/guards.ts';
@@ -77,7 +78,7 @@ function tarballOf(data: PluginsSection, pkgName: string): LocalPluginTarball |
 export function localTarballCacheName(relativePath: string): string {
   const base = relativePath.split('/').pop() ?? '';
   if (base === '' || base.includes('\\') || base === '.' || base === '..') {
-    throw new Error(`非法 tarball 相对路径: ${relativePath}`);
+    throw new Error(engineMsg('adapter.tarballRelPathInvalid', { path: relativePath }));
   }
   return base;
 }
@@ -697,7 +698,7 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
             names: clean.dropped.map((d) => d.name).join(', '),
           }));
         }
-        return { ok: true, needsRestart: true, message: notes.join('；') };
+        return { ok: true, needsRestart: true, message: notes.join(msg('adapter.listSeparator')) };
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
         return {
@@ -730,7 +731,7 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
             spec = `file:${abs}`;
           } catch (err) {
             // 解包失败不阻断安装尝试：退回原 spec（可能失败，但会如实报错而非静默丢失）
-            ctx.onLog?.(`本地插件 ${name} 的 tarball 解包失败，回退原始 spec：${err instanceof Error ? err.message : String(err)}`);
+            ctx.onLog?.(msg('adapter.localTarballUnpackFailed', { name, err: err instanceof Error ? err.message : String(err) }));
           }
         }
         // 执行日志：记录实际将发起的子进程命令行（与宿主 DshPluginsFacade 的

package/src/adapters/prompts.ts

@@ -14,6 +14,8 @@
  */
 import { msgOf, zhMsg } from '../core/messages.ts';
 import type { MsgFunc } from '../core/messages.ts';
+// t6：注册 adapters 域追加目录（本模块只消费注入的 msg，故只引它的注册副作用）。
+import './messages.ts';
 import type { PromptEntry } from '../schema/types.ts';
 import type {
   ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
@@ -159,7 +161,11 @@ export class PromptsAdapter implements ConfigAdapter<PromptsExportSection> {
           items.push({
             id, kind: 'Conflict', adapter: 'prompts',
             description: msg('adapter.promptDiff', { name: p.name }),
-            detail: `行 ${p.sourceLineId} current=${JSON.stringify(sameName.text).slice(0, 80)} imported=${JSON.stringify(p.text).slice(0, 80)}`,
+            detail: msg('adapter.promptDiffDetail', {
+              line: String(p.sourceLineId),
+              current: JSON.stringify(sameName.text).slice(0, 80),
+              imported: JSON.stringify(p.text).slice(0, 80),
+            }),
             severity: 'warning',
             // 层身份随计划项走：快照按这一层记原行、回滚才能写回原文件（issue #71）
             target: { adapter: 'prompts', ref: p.sourceLineId ?? '', file: targetLine.file },