dsh-config-manager 0.1.72 → 0.1.76

package/src/core/backup-plan.ts

@@ -69,6 +69,17 @@ export const OFFLINE_BACKUP_SECTIONS: readonly SectionId[] = [
   ...DEFAULT_BACKUP_SECTIONS, ...OPT_IN_BACKUP_SECTIONS,
 ] as const;
 
+/**
+ * 离线 CLI **明确不收集**的分区（第三方插件数据）。
+ *
+ * 为什么不做：它的收集目标不是静态路径，而是「本机内置来源注册表 + 已安装插件自述声明」推导出来的
+ * 区域（见 `core/plugin-data-registry.ts`），还要尊重环境变量覆盖判定 —— 这套判定住在 adapter 里
+ * （走 HostContext 门面），而 CLI 的硬约束是**绝不 import DSH 门面**（peer 缺失也要能跑）。
+ * 在这里手抄一份区域表会立刻与注册表漂移（正是本文件开头反复说的那类缺陷），所以选择**显式不适用**：
+ * 用户显式 `--sections pluginData` 时给一条可执行的提示（改用 GUI 导出/导入），而不是静默不收。
+ */
+export const OFFLINE_EXCLUDED_SECTIONS: readonly SectionId[] = ['pluginData', 'pluginAssets'] as const;
+
 /**
  * 离线**无法**收集的分区（需要 DSH Service 门面读值/权威脱敏）。仅用于报告与参数校验，
  * 绝不写进归档：这些分区的权威形态是 GUI 导出（经 DSH `describe({redactSecrets:true})`
@@ -81,7 +92,10 @@ export const OFFLINE_UNAVAILABLE_SECTIONS: readonly SectionId[] = [
 // 加载期自检（注册表派生，t30）：三个离线清单里的 id 必须都是**已注册分区**。
 // 「离线可收集性」是注册表未建模的另一条轴（要脱离 DSH 读盘收集），故这三份清单仍是显式声明；
 // 但拼错 id / 分区改名过去会让该分区「静默永不收集、永不报告」，现在模块加载即失败。
-for (const id of [...DEFAULT_BACKUP_SECTIONS, ...OPT_IN_BACKUP_SECTIONS, ...OFFLINE_UNAVAILABLE_SECTIONS]) {
+for (const id of [
+  ...DEFAULT_BACKUP_SECTIONS, ...OPT_IN_BACKUP_SECTIONS, ...OFFLINE_UNAVAILABLE_SECTIONS,
+  ...OFFLINE_EXCLUDED_SECTIONS,
+]) {
   requireSectionMeta(id);
 }
 
@@ -138,7 +152,7 @@ const SECTION_SPECS: Partial<Record<SectionId, SectionCollectSpec>> = {
     baseDir: '',
     files: ['dsh-ssh.json', 'pet.json'],
     dirs: ['plugin-config'],
-    label: 'Plugin Files',
+    label: "Other Plugins' Loose Files",
     get risk() { return engineMsg('core.backupPlan.pluginFilesRisk') },
   },
   // adapters/self.ts（baseDir='dsh-config-manager'，SELF_CONFIG_FILES 白名单）
@@ -153,7 +167,7 @@ const SECTION_SPECS: Partial<Record<SectionId, SectionCollectSpec>> = {
       'dsh-config-manager/market/market-config.json',
       'dsh-config-manager/exports/.backup-notes.json',
     ],
-    label: 'Plugin Self Config',
+    label: "This Plugin's Own Config",
   },
 };
 
@@ -250,6 +264,11 @@ export function parseSectionsArg(raw: string): { ok: true; sections: SectionId[]
   if (parts.length === 0) {
     return { ok: false, error: engineMsg('core.backupPlan.sectionsMissingValue') };
   }
+  // 显式请求「不支持离线」的分区 → 单独一条可执行提示（不得当成「不存在的分区」）
+  const notOffline = parts.filter((p) => (OFFLINE_EXCLUDED_SECTIONS as readonly string[]).includes(p));
+  if (notOffline.length > 0) {
+    return { ok: false, error: engineMsg('core.backupPlan.sectionNotOffline', { section: notOffline.join(', ') }) };
+  }
   const unknown = parts.filter((p) => !(OFFLINE_BACKUP_SECTIONS as readonly string[]).includes(p));
   if (unknown.length > 0) {
     return {

package/src/core/backup.ts

@@ -7,6 +7,7 @@
  */
 import { engineMsg } from './messages-core.ts';
 import fs from 'node:fs/promises';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { parseJsonSafe } from '../utils/json.ts';
@@ -17,7 +18,7 @@ import { SECTION_IDS, isFileSection } from '../schema/config.ts';
 import { isPatchLayerRel, PROFILE_PATCH_FILENAME, USER_PATCH_FILE } from './patch-layers.ts';
 import type { SectionId } from '../schema/types.ts';
 import type {
-  ConfigAdapter, HostContext, HostFileBackup, ImportPlan, PlanItem, Snapshot,
+  ConfigAdapter, FileSystemFacade, HostContext, HostFileBackup, ImportPlan, PlanItem, Snapshot,
   SnapshotEntry, SnapshotManifest, SnapshotStatus, SnapshotStore, SnapshotTarget,
 } from './types.ts';
 
@@ -139,6 +140,10 @@ const FILE_BASES: Partial<Record<SectionId, string>> = {
   agentPresets: '.agent-presets',
   agentInstructions: '', // homeDir 根（~/.dsh/AGENTS.md）
   pluginFiles: '',
+  // 第三方插件数据：baseDir '' = home 根，ref 是**完整的 home 相对路径**
+  // （.dsh-wallpaper-engine/config.json / .mnemon/data/x.db）
+  pluginData: '',
+  pluginAssets: '',
   sessions: 'sessions',
   self: 'dsh-config-manager',
 };
@@ -165,8 +170,43 @@ function profileDirOf(ctx: HostContext): string {
   return path.join(ctx.homeDir, 'profiles', profile);
 }
 
+/**
+ * 以**系统 home 为根**的文件类分区（ref 是系统 home 相对路径）。
+ *
+ * 为什么单独一组：`FileSystemFacade` 被限制在 $DSH_HOME 内，而第三方插件的数据常在 $DSH_HOME 之外
+ * （`~/.dsh-wallpaper-engine/`、`~/.mnemon/` …）。这两个分区的路径解析与 I/O 门面都换根，
+ * 其余分区一字不动 —— 单根不变量只在**这两个分区**上被显式放宽，且仍然只允许白名单区域。
+ */
+export const OS_HOME_FILE_SECTIONS: ReadonlySet<SectionId> = new Set<SectionId>(['pluginData', 'pluginAssets']);
+
+/** 该分区文件目标的根（`dsh` = $DSH_HOME；`osHome` = 系统 home） */
+export function sectionFileRoot(adapter: SectionId): 'dsh' | 'osHome' {
+  return OS_HOME_FILE_SECTIONS.has(adapter) ? 'osHome' : 'dsh';
+}
+
+/** 系统 home：宿主显式给就用它，否则进程 `homedir()`（`~` 的定义，不是猜） */
+export function osHomeDirOf(ctx: HostContext): string {
+  return ctx.osHomeDir !== undefined && ctx.osHomeDir !== '' ? ctx.osHomeDir : homedir();
+}
+
+/**
+ * 该分区文件 I/O 应使用的门面。
+ *
+ * `osHome` 分区必须用 `homeFs`：缺了它**显式抛错**，绝不退回 `ctx.fs` —— 那会把
+ * `~/.mnemon/x.db` 写成 `$DSH_HOME/.mnemon/x.db`（看起来成功、实际写错位置）。
+ */
+export function fsForSection(ctx: HostContext, adapter: SectionId): FileSystemFacade {
+  if (sectionFileRoot(adapter) === 'dsh') return ctx.fs;
+  if (ctx.homeFs === undefined) throw new Error(engineMsg('core.backup.osHomeUnavailable', { section: adapter }));
+  return ctx.homeFs;
+}
+
 /** 解析文件类目标的绝对路径（引擎通用快照与回滚共用） */
 export function resolveFileTarget(ctx: HostContext, adapter: SectionId, ref: string): string {
+  // 系统 home 根的分区：整体换根（plugins 的两个 profile 特例与它们互不相干）
+  if (sectionFileRoot(adapter) === 'osHome') {
+    return path.join(osHomeDirOf(ctx), FILE_BASES[adapter] ?? '', ref);
+  }
   // plugins 分区的 pnpm-workspace.yaml：位于 profiles/<profile>/ 下（非 FILE_BASES 静态基准）
   if (adapter === 'plugins' && ref === 'pnpm-workspace.yaml') {
     return path.join(profileDirOf(ctx), 'pnpm-workspace.yaml');
@@ -191,6 +231,8 @@ export function resolveFileTarget(ctx: HostContext, adapter: SectionId, ref: str
  * 指纹恒为 null，crash 后 reconcile 无法证明该项是否已应用（保守但可避免的精度损失）。
  */
 export function resolveFileTargetRel(adapter: SectionId, ref: string, profile?: string): string {
+  // 系统 home 根的分区：ref 本身就是「根相对路径」，原样归一即可
+  if (sectionFileRoot(adapter) === 'osHome') return normalizePath(ref);
   if (adapter === 'plugins') {
     const profileDir = `profiles/${profile !== undefined && profile !== '' ? profile : 'web'}`;
     if (ref === 'pnpm-workspace.yaml') return normalizePath(`${profileDir}/pnpm-workspace.yaml`);
@@ -301,13 +343,17 @@ async function engineSnapshotEntry(ctx: HostContext, target: SnapshotTarget): Pr
     case 'agentPresets':
     case 'agentInstructions':
     case 'pluginFiles':
+    case 'pluginData':
+    case 'pluginAssets':
     case 'sessions':
     case 'self': {
+      // 门面按分区选：pluginData / pluginAssets 在系统 home 根（见 fsForSection 的说明）
+      const fsFacade = fsForSection(ctx, target.adapter);
       const abs = resolveFileTarget(ctx, target.adapter, target.ref);
-      if (!(await ctx.fs.exists(abs))) {
+      if (!(await fsFacade.exists(abs))) {
         return { kind: 'file', adapter: target.adapter, ref: target.ref, before: null, existed: false };
       }
-      const data = await ctx.fs.readFile(abs);
+      const data = await fsFacade.readFile(abs);
       // 文件字节不放进 SnapshotEntry（契约纯净），由 createSnapshot 收集进 blobs Map 统一落盘
       return {
         kind: 'file',
@@ -415,7 +461,7 @@ export async function createSnapshot(opts: CreateSnapshotOptions): Promise<Snaps
       if (entry.kind === 'file' && entry.copiedTo && entry.existed) {
         const abs = resolveFileTarget(ctx, adapterId, target.ref);
         // 与改动前**完全相同的读调用**，只是延后到被消费时执行（路径语义与异常传播不变）
-        lazyBlobSources.push({ blobPath: entry.copiedTo, read: () => ctx.fs.readFile(abs) });
+        lazyBlobSources.push({ blobPath: entry.copiedTo, read: () => fsForSection(ctx, adapterId).readFile(abs) });
       }
       entries.push(entry);
     }

package/src/core/command-rollback.ts

@@ -10,8 +10,12 @@
  *   **绝不绕过**（命令入口没有「确认按钮」，用户敲下 id 就是那次确认；其余门照旧全量生效）。
  *
  * 纪律（与 src/core/model-tools.ts 的 registerModelTools 同口径）：
- *  · 命令服务**惰取**：一律 ctx.get('commands') 调用期读取，绝不属性访问 ctx.commands、
- *    绝不放进 inject —— 未组合该服务的部署必须照常启动（命令是可选能力，不是硬依赖）；
+ *  · 命令服务**惰取**：一律 ctx.get('commands')，绝不属性访问 ctx.commands、绝不放进 inject ——
+ *    未组合该服务的部署必须照常启动（命令是可选能力，不是硬依赖）；
+ *    **读的时机是装配期一次**（见 registerRollbackCommand）：Cordis 的 ctx.get 在 apply 期只能拿到
+ *    **已 apply** 的服务，所以 `commands` 行晚于本插件时 `/rollback` 不会注册（只 warn 一行、无重试入口）。
+ *    DSH 内置插件与本插件的实际 apply 顺序**未坐实**（asar 不可直接读、本机 profile 无相关行）；
+ *    要彻底消除这个窗口需要 `ctx.inject(['commands'])` 式的「服务就绪再注册」回调 —— 未做，如实记在这里。
  *  · 注册失败只 warn：命令挂不上不得影响其它装配（宿主启动 = blocker）；
  *  · 用户可见文案一律走宿主字典 engineMsg（key: command.rollback.*），**取文案那一刻**解析语言；
  *  · 本模块不 import @deepseek-ai/dsh-commands 的运行时值（只做结构化窄化），core 保持与 DSH 解耦。

package/src/core/messages-core.ts

@@ -241,7 +241,9 @@ export const zh = {
   'core.backupPlan.depDirSkipped': '运行时依赖目录未进备份（可重建，目标机需重新安装依赖）/ runtime dependency directory NOT in this backup (rebuildable; reinstall on the target): {path}（{files}）',
   'core.backupPlan.followedLinks': '已跟随 {count} 个链接目录收集内容 / followed {count} linked director(ies)',
   'core.backupPlan.sectionsMissingValue': '`--sections` 缺值 / missing value for `--sections`',
+  'core.backup.osHomeUnavailable': '分区 {section} 的数据在系统主目录下，但宿主未提供该目录的文件门面（旧版本宿主）；本次不读也不写 / section {section} stores data under the system home directory but the host provides no file facade for it (older host); nothing is read or written this time',
   'core.backupPlan.unknownSections': '未知分区 / unknown section(s): {unknown}（可用 / available: {available}）',
+  'core.backupPlan.sectionNotOffline': '分区 {section} 不支持离线 CLI 备份（它的收集依赖插件来源注册表与本机插件清单），请用 GUI 的导出/导入迁移它 / section {section} is not supported by the offline CLI backup (its collection depends on the plugin-data source registry and the local plugin manifests); use the GUI export/import instead',
   'core.backupPlan.unsafeEntryName': '跳过不安全条目名 / unsafe entry name skipped: {name}',
   'core.backupPlan.statFailed': '探测失败 / stat failed: {path}（{reason}）',
   'core.backupPlan.readFailed': '读取失败 / read failed: {path}（{reason}）',
@@ -551,7 +553,9 @@ export const en: Record<keyof typeof zh, string> = {
   'core.backupPlan.depDirSkipped': 'runtime dependency directory NOT in this backup (rebuildable; reinstall dependencies on the target): {path} ({files})',
   'core.backupPlan.followedLinks': 'followed {count} linked director(ies) to collect content',
   'core.backupPlan.sectionsMissingValue': 'missing value for `--sections`',
+  'core.backup.osHomeUnavailable': 'section {section} stores data under the system home directory but the host provides no file facade for it (older host); nothing is read or written this time',
   'core.backupPlan.unknownSections': 'unknown section(s): {unknown} (available: {available})',
+  'core.backupPlan.sectionNotOffline': 'section {section} is not supported by the offline CLI backup (its collection depends on the plugin-data source registry and the local plugin manifests); use the GUI export/import instead',
   'core.backupPlan.unsafeEntryName': 'unsafe entry name skipped: {name}',
   'core.backupPlan.statFailed': 'stat failed: {path} ({reason})',
   'core.backupPlan.readFailed': 'read failed: {path} ({reason})',

package/src/core/messages.ts

@@ -357,6 +357,7 @@ export const zh = {
   'sync.credentialsReadFailed': '读取凭据文件失败，本次快照不含任何凭据值: {reason}',
   'sync.credentialsEmpty': '本机凭据文件为空或无法解析，本次快照不含任何凭据值',
   'sync.credentialsItemDesc': '凭据 {ref} 随加密快照迁移（确认后写入本机凭据存储）',
+  'sync.credentialsItemSame': '凭据 {ref} 与本机一致，跳过写入（保留本机值）',
   'sync.credentialsNeedPassword': '快照 {id} 含加密凭据载荷，需要解密密码才能读取',
   'sync.encryptedNeedsPassword': '快照 {id} 已加密，需要解密密码才能读取（自动同步无法解密，请手动同步）',
   'sync.noPortableSections': '没有可同步的 portable 分区（全部导出失败）',
@@ -460,7 +461,7 @@ export const zh = {
   'command.rollback.restorableYes': '可回退',
   'command.rollback.restorableNo': '不可回退',
   'command.rollback.restorableSummary': '{parts} ⇒ {verdict}',
-  'command.rollback.rewindRestored': '已回退到 {id}。{detail}',
+  'command.rollback.rewindRestored': '已回退到 {id}。{detail}当前对话不会切换：回退出的新会话在左侧栏（未分组时排在列表末尾），打开它继续聊。',
   'command.rollback.rewindPartial': '回退只完成了一部分（会话段已 fork，工作区段见下）——{id}：{segments}。{detail}',
   'command.rollback.segmentFacts': '段：{facts}',
   'command.rollback.rewindFailed': '回退失败（{code}）：{id}。{detail}',
@@ -805,6 +806,7 @@ export const en: Record<keyof typeof zh, string> = {
   'sync.credentialsReadFailed': 'Failed to read the credentials file; this snapshot carries no credential value: {reason}',
   'sync.credentialsEmpty': 'The local credentials file is empty or unparseable; this snapshot carries no credential value',
   'sync.credentialsItemDesc': 'Credential {ref} travels with the encrypted snapshot (written to the local credential store once confirmed)',
+  'sync.credentialsItemSame': 'Credential {ref} already matches this machine; write skipped (local value kept)',
   'sync.credentialsNeedPassword': 'Snapshot {id} carries an encrypted credentials payload; a decryption password is required',
   'sync.encryptedNeedsPassword': 'Snapshot {id} is encrypted; a decryption password is required (auto sync cannot decrypt — sync manually)',
   'sync.noPortableSections': 'No portable sections to sync (all exports failed)',
@@ -907,7 +909,7 @@ export const en: Record<keyof typeof zh, string> = {
   'command.rollback.restorableYes': 'restorable',
   'command.rollback.restorableNo': 'not restorable',
   'command.rollback.restorableSummary': '{parts} => {verdict}',
-  'command.rollback.rewindRestored': 'Rewound to {id}. {detail}',
+  'command.rollback.rewindRestored': 'Rewound to {id}. {detail}This conversation is not switched: the new session is in the left sidebar (at the end of the list when ungrouped) — open it to continue.',
   'command.rollback.rewindPartial': 'The rewind only completed partially (session segment forked; see workspace segment below) - {id}: {segments}. {detail}',
   'command.rollback.segmentFacts': 'segments: {facts}',
   'command.rollback.rewindFailed': 'Rewind failed ({code}): {id}. {detail}',

package/src/core/plugin-data-registry.test.ts

@@ -0,0 +1,113 @@
+/**
+ * pluginData / pluginAssets 来源注册表的纯函数单测（零 I/O）。
+ *
+ * 这里钉的是「收录口径」的四条硬性质：
+ *  ① 区域归属（角色 → 分区）与内置来源的取证标签；
+ *  ② 最长前缀归属 —— 大资产不能被短前缀的配置区域吞掉；
+ *  ③ 排除与安全（cache 不进包；非法 home 相对路径一律拒绝）；
+ *  ④ 自述声明（dsh.dataDirs）的形状解析：不认识就整条丢弃，绝不猜。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  BUILTIN_PLUGIN_DATA_SOURCES, areaOfPath, areasForSection, isExcludedRel, normalizeHomeRel,
+  parseDeclaredDataDirs, relInArea, sectionOfRole,
+} from './plugin-data-registry.ts';
+import type { PluginDataArea, PluginDataSource } from './plugin-data-registry.ts';
+
+/** 区域条目（与 adapter 的 PluginDataEntry 同形；core 测试不反向依赖 adapters 层） */
+type AreaEntry = { source: PluginDataSource; area: PluginDataArea };
+
+const ALL: AreaEntry[] = [];
+for (const source of BUILTIN_PLUGIN_DATA_SOURCES) {
+  for (const area of source.areas) ALL.push({ source, area });
+}
+
+test('全局唯一来源：id 不重复，且每个来源都如实标注取证强度', () => {
+  const ids = BUILTIN_PLUGIN_DATA_SOURCES.map((s) => s.id);
+  assert.equal(new Set(ids).size, ids.length);
+  for (const s of BUILTIN_PLUGIN_DATA_SOURCES) {
+    assert.ok(['measured', 'fixture', 'documented'].includes(s.evidence), s.id);
+    assert.ok(s.areas.length > 0, s.id);
+  }
+  // 本机实测的两个来源必须真有 measured 证据（其余是文档取证，不得美化）
+  assert.equal(BUILTIN_PLUGIN_DATA_SOURCES.find((s) => s.id === 'mnemon')?.evidence, 'measured');
+});
+
+test('角色 → 分区：config 进 pluginData，assets 进 pluginAssets，cache 两个都不进', () => {
+  assert.equal(sectionOfRole('config'), 'pluginData');
+  assert.equal(sectionOfRole('assets'), 'pluginAssets');
+  assert.equal(sectionOfRole('cache'), null);
+
+  const config = areasForSection(BUILTIN_PLUGIN_DATA_SOURCES, 'pluginData').map((e) => e.area.relPath);
+  const assets = areasForSection(BUILTIN_PLUGIN_DATA_SOURCES, 'pluginAssets').map((e) => e.area.relPath);
+  assert.ok(config.includes('.dsh-wallpaper-engine'));
+  assert.ok(config.includes('.mnemon/runtime'));
+  assert.ok(!config.includes('.dsh-wallpaper-engine/uploads'), '大资产不得出现在配置分区');
+  assert.ok(assets.includes('.dsh-wallpaper-engine/uploads'));
+  assert.ok(assets.includes('.mnemon/data'));
+  assert.ok(![...config, ...assets].includes('.dsh-wallpaper-engine/cache'), '缓存永不进任何分区');
+});
+
+test('最长前缀归属：uploads 下的文件归 uploads 区域，不是它祖先的配置区域', () => {
+  const hit = areaOfPath(ALL, '.dsh-wallpaper-engine/uploads/a.mp4');
+  assert.equal(hit?.area.relPath, '.dsh-wallpaper-engine/uploads');
+  assert.equal(hit?.area.role, 'assets');
+
+  // 配置分区视角：upload 路径被祖先区域的 excludeRel 挡住 → 判 null（导入侧据此拒绝写）
+  const configOnly = areasForSection(BUILTIN_PLUGIN_DATA_SOURCES, 'pluginData');
+  assert.equal(areaOfPath(configOnly, '.dsh-wallpaper-engine/uploads/a.mp4'), null);
+  assert.equal(areaOfPath(configOnly, '.dsh-wallpaper-engine/config.json')?.area.relPath, '.dsh-wallpaper-engine');
+});
+
+test('relInArea / isExcludedRel：文件区域精确匹配，目录区域前缀匹配', () => {
+  const fileArea = { relPath: '.x/state.json', role: 'config' as const };
+  assert.equal(relInArea(fileArea, '.x/state.json'), true);
+  assert.equal(relInArea(fileArea, '.x/state.json.bak'), false);
+
+  const dirArea = { relPath: '.x', role: 'config' as const, excludeRel: ['cache'] };
+  assert.equal(relInArea(dirArea, '.x/a/b'), true);
+  assert.equal(isExcludedRel(dirArea, '.x/cache'), true);
+  assert.equal(isExcludedRel(dirArea, '.x/cache/deep/b'), true);
+  assert.equal(isExcludedRel(dirArea, '.x/cacheX'), false, '前缀必须是完整路径段');
+  assert.equal(isExcludedRel(dirArea, '.x/a'), false);
+});
+
+test('normalizeHomeRel：拒绝一切可能越界的写法，反斜杠归一为 POSIX', () => {
+  assert.equal(normalizeHomeRel('.a/b'), '.a/b');
+  assert.equal(normalizeHomeRel('.a\\b'), '.a/b');
+  assert.equal(normalizeHomeRel('  .a/b  '), '.a/b');
+
+  for (const bad of ['', '  ', '/abs/x', 'C:/x', 'a/../b', '..', './a', 'a/', 'a//b', 'a/\u0000b', 42, null, undefined]) {
+    assert.equal(normalizeHomeRel(bad), null, JSON.stringify(bad));
+  }
+});
+
+test('parseDeclaredDataDirs：合法声明解析成来源；形状不认识整条丢弃（不猜）', () => {
+  const source = parseDeclaredDataDirs('dsh-fake', {
+    dsh: { dataDirs: [
+      { path: '.fake-plugin', role: 'config', env: ['FAKE_DATA_DIR'] },
+      { path: '.fake-plugin/uploads', role: 'assets', exclude: ['tmp'] },
+    ] },
+  });
+  assert.ok(source);
+  assert.equal(source?.id, 'declared:dsh-fake');
+  assert.deepEqual(source?.packages, ['dsh-fake']);
+  assert.equal(source?.areas.length, 2);
+  assert.deepEqual(source?.areas[0]?.envOverrides, ['FAKE_DATA_DIR']);
+  assert.deepEqual(source?.areas[1]?.excludeRel, ['tmp']);
+  assert.equal(source?.areas[1]?.role, 'assets');
+
+  // 缺省角色 = config
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: [{ path: '.p' }] } })?.areas[0]?.role, 'config');
+
+  // 整条丢弃的形态
+  assert.equal(parseDeclaredDataDirs('p', null), null);
+  assert.equal(parseDeclaredDataDirs('p', {}), null);
+  assert.equal(parseDeclaredDataDirs('p', { dsh: {} }), null);
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: [] } }), null);
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: 'nope' } }), null);
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: [{ path: '/abs' }] } }), null, '绝对路径 → 整条丢弃');
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: [{ path: '.ok' }, { path: '../escape' }] } }), null, '任一非法 → 整条丢弃');
+});

package/src/core/plugin-data-registry.ts

@@ -0,0 +1,261 @@
+/**
+ * 第三方插件「数据目录」来源注册表（pluginData / pluginAssets 两个分区的唯一知识源）。
+ *
+ * 为什么需要它：DSH 插件的数据目录不由宿主统一提供（2026-10-14 核对 dsh-config-manager /
+ * dsh-mnemon / dsh-better-sidebar 的 package.json，均无任何「数据目录」声明字段），而现实里它们
+ * 散落在 ~/.dsh-<name>/、~/.<name>/、~/.dsh/<name>/ 三种形态 —— 既有的 pluginFiles 分区只认
+ * 「相对 ~/.dsh 根的白名单文件」，够不到其中任何一类。
+ *
+ * 本模块只做三件事，全部是纯函数 / 静态数据（零 I/O、零 node 内置依赖）：
+ *  ① 冻结来源与「区域（area）」的形状；
+ *  ② 内置已取证来源（每条如实标注取证强度，与 src/foreign/types.ts 的 ForeignEvidenceKind 同款纪律）；
+ *  ③ 提供「路径 → 区域」的最长前缀匹配与 dsh.dataDirs 自述声明的解析。
+ *
+ * 三条不变量：
+ *  - 不猜：路径一律来自插件自己的 README 明示位置或本机实测；不确定的来源宁可不收。
+ *  - 缓存永不收录：role === 'cache' 的区域只用于报告（「我知道它在那儿，但不带」），绝不进包 ——
+ *    缓存是可再生产物，带出去只会撑爆包体。
+ *  - 环境变量覆盖即跳过且不读值：区域被环境变量覆盖时，绝不去读那个变量指向的目录（目标机的
+ *    同名变量可能指向完全不同的盘符，按 home 相对路径写进包，换机后就落到「看起来对」的错误位置）。
+ */
+import type { SectionId } from '../schema/types.ts';
+
+/** 第三方插件数据分区（两个：配置类与资产类） */
+export type PluginDataSection = Extract<SectionId, 'pluginData' | 'pluginAssets'>;
+
+/**
+ * 区域角色 —— 决定它进哪个分区：
+ *  - config：配置与轻量状态（进 pluginData）；
+ *  - assets：大体积用户数据（上传的壁纸、本地数据库；进 pluginAssets）；
+ *  - cache：可再生产物，两个分区都不进，只出现在报告里。
+ */
+export type PluginDataRole = 'config' | 'assets' | 'cache';
+
+/** 取证强度（字段必填：未取证的来源不可能被悄悄列出来） */
+export type PluginDataEvidence =
+  /** 本机实测：目录确实存在，且据此实现 */
+  | 'measured'
+  /** 有可复现取证方式：夹具 + 单测端到端跑同一份布局 */
+  | 'fixture'
+  /** 只有插件自己的文档（README 明示的位置/环境变量） */
+  | 'documented';
+
+/** 一个数据区域：home 相对 POSIX 路径（文件或目录同形，按磁盘实际形态判定） */
+export interface PluginDataArea {
+  readonly relPath: string;
+  readonly role: PluginDataRole;
+  /**
+   * 会整体搬走本区域的环境变量名（任一存在即跳过本区域并报码）。
+   *
+   * 必须把「祖先区域的环境变量」也列进来：wallpaper-engine 的 DSH_WE_DATA_DIR 搬走的是整个
+   * ~/.dsh-wallpaper-engine，只列 DSH_WE_UPLOAD_DIR 会让 uploads 在数据目录已被搬走时仍被当成
+   * 「默认位置」去读（读到空目录 → 用户以为「没有上传的壁纸」）。
+   */
+  readonly envOverrides?: readonly string[];
+  /** 仅目录区域：永不收集的**区域相对**子路径（POSIX 前缀），如 cache / bin */
+  readonly excludeRel?: readonly string[];
+}
+
+/** 一个第三方插件来源 */
+export interface PluginDataSource {
+  /** 稳定机器 id（进单元 id 与报告；不随文案变化） */
+  readonly id: string;
+  /** 该来源对应的 npm 包名（自述声明的去重键） */
+  readonly packages: readonly string[];
+  readonly evidence: PluginDataEvidence;
+  readonly areas: readonly PluginDataArea[];
+}
+
+/**
+ * 内置来源 —— 只放已取证的。
+ *
+ * 收录口径（2026-10-14 调研：按 GitHub star + npm 周下载量排序后逐一核对）：
+ *  - 有自有数据目录（不在 DSH 三个核心存储里，也不在 profile 树里）；
+ *  - 目录里不含凭据（~/.commandcode/auth.json、~/.dsh/agy-accounts 这类命中即整来源不收录 ——
+ *    文件类分区的内容不进 SecretScanner 的剥离路径，带出去就是明文）；
+ *  - 位置由插件自己的 README 明示，或本机实测。
+ *
+ * 未收录但确实有数据目录的插件（如实登记，避免「没列出来 = 不存在」的误读）：
+ *  - dsh-better-sidebar（4175 star）：状态全在 DSH settings/storages，已被既有分区覆盖；
+ *  - @mars-sea/dsh-commandcode-provider（389 star）：~/.commandcode/ 含 auth.json（凭据）；
+ *  - dsh-agy-link（111 star）：~/.dsh/agy-accounts 为账号池（凭据）。
+ */
+export const BUILTIN_PLUGIN_DATA_SOURCES: readonly PluginDataSource[] = [
+  {
+    // README「配置与数据」表逐项明示：数据目录 + 缓存/上传/官方资源的覆盖变量
+    id: 'wallpaper-engine',
+    packages: ['dsh-plugin-wallpaper-engine'],
+    evidence: 'documented',
+    areas: [
+      {
+        relPath: '.dsh-wallpaper-engine',
+        role: 'config',
+        envOverrides: ['DSH_WE_DATA_DIR'],
+        // cache = 抽帧/转码/缩略图（可再生产物）；uploads 进 assets；bin 由插件管理（按需下载的运行时）
+        excludeRel: ['cache', 'uploads', 'bin'],
+      },
+      {
+        relPath: '.dsh-wallpaper-engine/uploads',
+        role: 'assets',
+        envOverrides: ['DSH_WE_DATA_DIR', 'DSH_WE_UPLOAD_DIR'],
+      },
+      {
+        relPath: '.dsh-wallpaper-engine/cache',
+        role: 'cache',
+        envOverrides: ['DSH_WE_DATA_DIR', 'DSH_WE_CACHE_DIR'],
+      },
+    ],
+  },
+  {
+    // 本机实测（~/.mnemon 下 runtime / data / documents 三个子目录）；MNEMON_DATA_DIR 覆盖整个根
+    id: 'mnemon',
+    packages: ['dsh-mnemon'],
+    evidence: 'measured',
+    areas: [
+      { relPath: '.mnemon/runtime', role: 'config', envOverrides: ['MNEMON_DATA_DIR'] },
+      { relPath: '.mnemon/data', role: 'assets', envOverrides: ['MNEMON_DATA_DIR'] },
+      { relPath: '.mnemon/documents', role: 'assets', envOverrides: ['MNEMON_DATA_DIR'] },
+    ],
+  },
+  {
+    // README 明示 ~/.fastctx/ 为持久状态（只有 --purge-fastctx 才删）
+    id: 'dsh-ops',
+    packages: ['dsh-ops'],
+    evidence: 'documented',
+    areas: [{ relPath: '.fastctx', role: 'assets' }],
+  },
+  {
+    // README 明示：所有设置落 ~/.dsh/.dsh-any-background-data/（不是 localStorage）
+    id: 'any-background',
+    packages: ['dsh-any-background'],
+    evidence: 'documented',
+    areas: [{ relPath: '.dsh/.dsh-any-background-data', role: 'config' }],
+  },
+  {
+    // README 明示 ~/.opencode2dsh/adapter-status.json
+    id: 'opencode2dsh',
+    packages: ['@opencode2dsh/dsh-plugin'],
+    evidence: 'documented',
+    areas: [{ relPath: '.opencode2dsh', role: 'config' }],
+  },
+];
+
+/** 角色 → 分区（cache 不属于任何分区） */
+export function sectionOfRole(role: PluginDataRole): PluginDataSection | null {
+  if (role === 'config') return 'pluginData';
+  if (role === 'assets') return 'pluginAssets';
+  return null;
+}
+
+/** 该分区要收集的区域清单（保序：来源顺序 → 区域内顺序） */
+export function areasForSection(
+  sources: readonly PluginDataSource[],
+  section: PluginDataSection,
+): readonly { source: PluginDataSource; area: PluginDataArea }[] {
+  const out: { source: PluginDataSource; area: PluginDataArea }[] = [];
+  for (const source of sources) {
+    for (const area of source.areas) {
+      if (sectionOfRole(area.role) === section) out.push({ source, area });
+    }
+  }
+  return out;
+}
+
+/**
+ * home 相对路径归一化 + 安全判定。
+ *
+ * 只接受 POSIX 相对路径：拒绝绝对路径（含 Windows 盘符写法 C:/x）、..、反斜杠、空段、
+ * 以 / 结尾、含 NUL 的值。
+ * 返回 null = 调用方必须报错/跳过，绝不「尽力而为」地拼一个路径出来。
+ */
+export function normalizeHomeRel(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const v = value.trim().replace(/\\/g, '/');
+  if (v === '' || v.startsWith('/') || /^[A-Za-z]:/.test(v) || v.includes('\u0000')) return null;
+  if (v.endsWith('/')) return null;
+  for (const part of v.split('/')) {
+    if (part === '' || part === '.' || part === '..') return null;
+  }
+  return v;
+}
+
+/**
+ * 目录区域的排除判定（issue：**excludeRel 是区域相对路径，rel 是 home 相对路径**）。
+ *
+ * 必须先把 rel 折成区域相对再比：`excludeRel: ['uploads']` 配 `.dsh-wallpaper-engine` 区域时，
+ * 真正的判别对象是 `uploads/a.mp4`（区域相对），不是 `.dsh-wallpaper-engine/uploads/a.mp4`（home 相对）——
+ * 直接拿 home 相对路径去 startsWith，排除项永远不命中，缓存与大资产会悄悄跟着配置分区一起进包。
+ */
+export function isExcludedRel(area: PluginDataArea, rel: string): boolean {
+  const inner = rel === area.relPath
+    ? ''
+    : rel.startsWith(area.relPath + '/') ? rel.slice(area.relPath.length + 1) : null;
+  if (inner === null || inner === '') return false;
+  for (const ex of area.excludeRel ?? []) {
+    if (inner === ex || inner.startsWith(ex + '/')) return true;
+  }
+  return false;
+}
+
+/** rel 是否属于该区域（文件区域 = 精确相等；目录区域 = 精确相等或前缀） */
+export function relInArea(area: PluginDataArea, rel: string): boolean {
+  if (rel === area.relPath) return true;
+  return rel.startsWith(area.relPath + '/');
+}
+
+/**
+ * 路径 → 区域（最长前缀优先）。
+ *
+ * 为什么必须最长优先：.dsh-wallpaper-engine 与 .dsh-wallpaper-engine/uploads 同时是区域，
+ * 短前缀先匹配会把上传的壁纸算进「配置」分区（用户取消勾选大资产也照样带走几百 MB）。
+ */
+export function areaOfPath(
+  entries: readonly { source: PluginDataSource; area: PluginDataArea }[],
+  rel: string,
+): { source: PluginDataSource; area: PluginDataArea } | null {
+  let best: { source: PluginDataSource; area: PluginDataArea } | null = null;
+  for (const entry of entries) {
+    if (!relInArea(entry.area, rel)) continue;
+    if (isExcludedRel(entry.area, rel)) continue;
+    if (best === null || entry.area.relPath.length > best.area.relPath.length) best = entry;
+  }
+  return best;
+}
+
+/**
+ * 解析一个已安装插件 package.json 里的自述声明（dsh.dataDirs）—— 「让别的插件自己适配」的钩子。
+ *
+ * 契约（对外文档见 docs/spec/plugin-data-declaration.md）：
+ *   { "dsh": { "dataDirs": [ { "path": ".my-plugin", "role": "config", "env": ["MY_PLUGIN_DIR"] } ] } }
+ *
+ * 形状不认识就整条丢弃（返回 null），绝不猜；path 非法（绝对路径 / .. / 空段）同样丢弃。
+ */
+export function parseDeclaredDataDirs(packageName: string, manifest: unknown): PluginDataSource | null {
+  if (manifest === null || typeof manifest !== 'object') return null;
+  const dsh = (manifest as { dsh?: unknown }).dsh;
+  if (dsh === null || typeof dsh !== 'object') return null;
+  const raw = (dsh as { dataDirs?: unknown }).dataDirs;
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  const areas: PluginDataArea[] = [];
+  for (const item of raw) {
+    if (item === null || typeof item !== 'object') return null;
+    const rec = item as { path?: unknown; role?: unknown; env?: unknown; exclude?: unknown };
+    const relPath = normalizeHomeRel(rec.path);
+    if (relPath === null) return null;
+    const role: PluginDataRole =
+      rec.role === 'assets' ? 'assets' : rec.role === 'cache' ? 'cache' : 'config';
+    const envOverrides = Array.isArray(rec.env)
+      ? rec.env.filter((e): e is string => typeof e === 'string' && e !== '')
+      : [];
+    const excludes = Array.isArray(rec.exclude)
+      ? rec.exclude.map((e) => normalizeHomeRel(e)).filter((e): e is string => e !== null)
+      : [];
+    areas.push({
+      relPath,
+      role,
+      ...(envOverrides.length > 0 ? { envOverrides } : {}),
+      ...(excludes.length > 0 ? { excludeRel: excludes } : {}),
+    });
+  }
+  return { id: 'declared:' + packageName, packages: [packageName], evidence: 'documented', areas };
+}