dsh-config-manager 0.1.71 → 0.1.73

package/lib/adapters/index.d.ts

@@ -40,7 +40,7 @@ export declare function createAdapters(options?: AdapterRegistryOptions): Config
 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 { UiAdapter, isUiNamespace, KNOWN_UI_NAMESPACE_PREFIXES, uiMigrationNotes } 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';
@@ -54,5 +54,6 @@ 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 { PluginDataAdapter, type PluginDataAdapterOptions, type PluginDataEntry } from './plugin-data.ts';
 export { FileCollectionAdapter } from './file-collection.ts';
 export { validateJsonSection, type SectionIssues } from './json-section.ts';

package/lib/adapters/index.js

@@ -12,6 +12,7 @@ import { CredentialsAdapter } from './credentials.js';
 import { PluginFilesAdapter } from './plugin-files.js';
 import { SessionsAdapter } from './sessions.js';
 import { SelfAdapter } from './self.js';
+import { PluginDataAdapter } from './plugin-data.js';
 /** 组装默认 adapter 列表（pluginFiles/sessions 恒挂载但 defaultIncluded=false，用户勾选才导出） */
 export function createAdapters(options = {}) {
     const namespaces = options.namespaces ?? [];
@@ -28,6 +29,9 @@ export function createAdapters(options = {}) {
         new WorkspacesAdapter(),
         new CredentialsAdapter({ namespaces, refs: options.credentialsRefs }),
         new PluginFilesAdapter(options.pluginFiles, options.pluginFilesDir),
+        // 第三方插件数据（两个分区：配置类 / 大资产类；均 defaultIncluded=false，用户显式勾选）
+        new PluginDataAdapter('pluginData'),
+        new PluginDataAdapter('pluginAssets'),
     ];
     // self 分区：插件自身配置（同步/市场/偏好），portable 默认包含；'' = 不挂载
     if (options.selfDir !== '') {
@@ -38,7 +42,7 @@ export function createAdapters(options = {}) {
     return adapters;
 }
 export { SettingsAdapter } from './settings.js';
-export { UiAdapter, isUiNamespace, KNOWN_UI_NAMESPACE_PREFIXES, UI_MIGRATION_NOTES } from './ui.js';
+export { UiAdapter, isUiNamespace, KNOWN_UI_NAMESPACE_PREFIXES, uiMigrationNotes } from './ui.js';
 export { ProvidersAdapter, DEFAULT_PROVIDER_NAMESPACES } from './providers.js';
 export { PluginsAdapter, USER_PATCH_FILE } from './plugins.js';
 export { McpAdapter, extractMcpServers, buildMcpPatchLine } from './mcp.js';
@@ -51,6 +55,7 @@ export { CredentialsAdapter, defaultCredentialRefs } from './credentials.js';
 export { PluginFilesAdapter, DEFAULT_PLUGIN_FILE_WHITELIST } from './plugin-files.js';
 export { SessionsAdapter } from './sessions.js';
 export { SelfAdapter, SELF_CONFIG_FILES } from './self.js';
+export { PluginDataAdapter } from './plugin-data.js';
 export { FileCollectionAdapter } from './file-collection.js';
 /* JSON 分区共享校验骨架（本导出是其接入点）。收敛轨迹：
  *  · t31 抽出骨架，settings / ui / providers / plugins / mcp / prompts / credentials /

package/lib/adapters/link-report.d.ts

@@ -9,6 +9,7 @@
  */
 import type { FileSystemFacade } from '../core/types.ts';
 import type { MsgFunc } from '../core/messages.ts';
+import './messages.ts';
 import type { RecursiveListing } from '../utils/recursive-walk.ts';
 /** 取遍历结果：宿主未实现 listRecursiveDetailed（旧版/测试 mock）时回退，行为与旧版一致。 */
 export declare function listFilesDetailed(fs: FileSystemFacade, dir: string): Promise<RecursiveListing>;

package/lib/adapters/link-report.js

@@ -1,3 +1,5 @@
+// t6：注册 adapters 域追加目录（本模块只消费注入的 msg，故只引它的注册副作用）。
+import './messages.js';
 /** 跳过原因 → 消息 key（与 SkippedLink.reason 一一对应，穷尽映射） */
 const REASON_KEY = {
     loop: 'adapter.linkReason.loop',
@@ -8,11 +10,27 @@ const REASON_KEY = {
 };
 /** 单条原因下最多列出的路径数（其余折叠为计数，避免把报告撑爆） */
 const MAX_PATHS_PER_REASON = 5;
+/**
+ * 被跳过的依赖目录 → 详情片段（路径 + 文件数，issue #76）。
+ *
+ * 文件数是**量级说明**而非完整性判据：计数预算耗尽时如实写「未统计」，绝不猜一个数
+ * （把未知写成 0 会被读成「这个目录是空的」）。
+ */
+function depDirDetail(msg, dirs) {
+    const shown = dirs.slice(0, MAX_PATHS_PER_REASON).map((dir) => {
+        const files = dir.files === null
+            ? msg('adapter.depsDirFilesUnknown')
+            : msg('adapter.depsDirFiles', { count: String(dir.files) });
+        return msg('adapter.linkDirEntry', { path: dir.path, files });
+    });
+    const more = dirs.length - shown.length;
+    return (more > 0 ? [...shown, `(+ ${more})`] : shown).join(', ');
+}
 /** 取遍历结果：宿主未实现 listRecursiveDetailed（旧版/测试 mock）时回退，行为与旧版一致。 */
 export async function listFilesDetailed(fs, dir) {
     if (fs.listRecursiveDetailed !== undefined)
         return fs.listRecursiveDetailed(dir);
-    return { paths: await fs.listRecursive(dir), skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
+    return { paths: await fs.listRecursive(dir), skippedLinks: [], skippedDepDirs: [], followedLinks: 0, unreadableDirs: [] };
 }
 /** 把遍历结果转成告警行（无链接时返回空数组 —— 不制造噪音）。 */
 export function linkWarnings(msg, type, listing) {
@@ -30,8 +48,8 @@ export function linkWarnings(msg, type, listing) {
         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('；');
+            return msg('adapter.linkSkipLine', { reason: msg(REASON_KEY[reason]), count: paths.length, paths: shown, more });
+        }).join(msg('adapter.listSeparator'));
         out.push(msg('adapter.linksSkipped', { type, count: String(listing.skippedLinks.length), detail }));
     }
     if (listing.unreadableDirs.length > 0) {
@@ -42,6 +60,12 @@ export function linkWarnings(msg, type, listing) {
             type, count: String(listing.unreadableDirs.length), detail: `${shown}${more}`,
         }));
     }
+    // issue #76：运行时依赖目录整棵跳过（内容未进备份）——与链接/不可读目录同等对待：必须可见，绝不静默。
+    if (listing.skippedDepDirs.length > 0) {
+        out.push(msg('adapter.depsDirsSkipped', {
+            type, count: String(listing.skippedDepDirs.length), detail: depDirDetail(msg, listing.skippedDepDirs),
+        }));
+    }
     return out;
 }
 //# sourceMappingURL=link-report.js.map

package/lib/adapters/messages.d.ts

@@ -0,0 +1,21 @@
+import type { MsgFunc } from '../core/msg-types.ts';
+export declare const zh: {
+    readonly 'adapter.linkDirEntry': '{path}（{files}）';
+    readonly 'adapter.linkSkipLine': '{reason} {count} 个: {paths}{more}';
+    readonly 'adapter.listSeparator': '；';
+    readonly 'adapter.pluginFilesCollectDirInvalid': 'pluginFiles collectDir 非法（须为相对 ~/.dsh 根的安全路径）: {dir}';
+    readonly 'adapter.tarballRelPathInvalid': '非法 tarball 相对路径: {path}';
+    readonly 'adapter.localTarballUnpackFailed': '本地插件 {name} 的 tarball 解包失败，回退原始 spec：{err}';
+    readonly 'adapter.promptDiffDetail': '行 {line} current={current} imported={imported}';
+    readonly 'adapter.sessionUncoupledNote': '{id}（{reason}）';
+    readonly 'adapter.workspaceNotesParen': '（{notes}）';
+    readonly 'adapter.uiLocalStorageTaskBoard': '任务看板数据存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置';
+    readonly 'adapter.uiLocalStoragePanel': '面板宽度/折叠状态存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置';
+    readonly 'adapter.uiLocalStorageGeneric': '浏览器端 UI 状态无法经 Host API 迁移';
+    readonly 'adapter.pluginDataEnvOverridden': '{path} 的位置被环境变量 {env} 覆盖，本次已跳过（不猜它指向哪里）';
+    readonly 'adapter.pluginDataPathNotAllowed': '路径不在第三方插件数据的允许范围内，已拒绝写入: {path}';
+    readonly 'adapter.pluginDataNoOsHome': '第三方插件的数据在系统主目录下，但当前宿主没有提供该目录的文件通道（旧版本宿主）：本次不读取也不导入 / third-party plugin data lives under the system home directory, but this host offers no file channel for it (older host): nothing is read or imported this time';
+};
+export declare const en: Record<keyof typeof zh, string>;
+/** 本域活翻译器（与 core 的 engineMsg 同一实现；导入本模块即完成目录注册）。 */
+export declare const engineMsg: MsgFunc;

package/lib/adapters/messages.js

@@ -0,0 +1,57 @@
+/**
+ * adapters 域（src/adapters/**）的追加消息目录（zh 源 / en 镜像），归 t6 作用域。
+ *
+ * 为什么不在 \`src/core/messages.ts\` 追加：该文件不在本作用域的 inScope 内，且既有 372 键有冻结指纹。
+ * 本模块经 \`registerMessageCatalog\` 注册**追加目录**：engineMsg / makeMsg 的查找顺序是
+ * 「既有目录 → en 下回退既有 zh → 注册目录 → 键名」，所以本域新键只在既有目录未命中时生效，
+ * 不可能遮蔽 core 的既有 adapter.* 键。
+ *
+ * 纪律：zh 值 = 改动前的既有中文文案**逐字原样**；en 为 \`Record<keyof typeof zh, string>\`（缺键即编译错）。
+ * **导入本模块即完成注册**：本域消费面是注入的 ctx.msg（MsgFunc）与 engineMsg，两者都查注册目录。
+ */
+import { engineMsg as engineMsgOf, registerMessageCatalog } from '../core/engine-locale.js';
+export const zh = {
+    // ---------- 链接 / 依赖目录报告（issue #37 / #76）----------
+    'adapter.linkDirEntry': '{path}（{files}）',
+    'adapter.linkSkipLine': '{reason} {count} 个: {paths}{more}',
+    'adapter.listSeparator': '；',
+    // ---------- pluginFiles / tarball ----------
+    'adapter.pluginFilesCollectDirInvalid': 'pluginFiles collectDir 非法（须为相对 ~/.dsh 根的安全路径）: {dir}',
+    'adapter.tarballRelPathInvalid': '非法 tarball 相对路径: {path}',
+    'adapter.localTarballUnpackFailed': '本地插件 {name} 的 tarball 解包失败，回退原始 spec：{err}',
+    // ---------- prompts 计划项明细 ----------
+    'adapter.promptDiffDetail': '行 {line} current={current} imported={imported}',
+    // ---------- 会话连带失败明细 ----------
+    'adapter.sessionUncoupledNote': '{id}（{reason}）',
+    // ---------- 工作区告警拼接 ----------
+    'adapter.workspaceNotesParen': '（{notes}）',
+    // ---------- localStorage 等 Host 无通道的 UI 状态说明 ----------
+    'adapter.uiLocalStorageTaskBoard': '任务看板数据存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
+    'adapter.uiLocalStoragePanel': '面板宽度/折叠状态存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
+    'adapter.uiLocalStorageGeneric': '浏览器端 UI 状态无法经 Host API 迁移',
+    // ---------- pluginData / pluginAssets（第三方插件数据迁移） ----------
+    'adapter.pluginDataEnvOverridden': '{path} 的位置被环境变量 {env} 覆盖，本次已跳过（不猜它指向哪里）',
+    'adapter.pluginDataPathNotAllowed': '路径不在第三方插件数据的允许范围内，已拒绝写入: {path}',
+    'adapter.pluginDataNoOsHome': '第三方插件的数据在系统主目录下，但当前宿主没有提供该目录的文件通道（旧版本宿主）：本次不读取也不导入 / third-party plugin data lives under the system home directory, but this host offers no file channel for it (older host): nothing is read or imported this time',
+};
+export const en = {
+    'adapter.linkDirEntry': '{path} ({files})',
+    'adapter.linkSkipLine': '{reason} {count} item(s): {paths}{more}',
+    'adapter.listSeparator': '; ',
+    'adapter.pluginFilesCollectDirInvalid': 'pluginFiles collectDir is invalid (must be a safe path relative to the ~/.dsh root): {dir}',
+    'adapter.tarballRelPathInvalid': 'Invalid relative tarball path: {path}',
+    'adapter.localTarballUnpackFailed': 'Failed to unpack the tarball of local plugin {name}; falling back to the original spec: {err}',
+    'adapter.promptDiffDetail': 'line {line} current={current} imported={imported}',
+    'adapter.sessionUncoupledNote': '{id} ({reason})',
+    'adapter.workspaceNotesParen': ' ({notes})',
+    'adapter.uiLocalStorageTaskBoard': 'Task-board data lives in the browser localStorage and the host has no access path; reconfigure it on the target machine',
+    'adapter.uiLocalStoragePanel': 'Panel width/collapsed state lives in the browser localStorage and the host has no access path; reconfigure it on the target machine',
+    'adapter.uiLocalStorageGeneric': 'Browser-side UI state cannot be migrated through the host API',
+    'adapter.pluginDataEnvOverridden': "the location of {path} is overridden by the {env} environment variable; skipped this time (the new location is never guessed)",
+    'adapter.pluginDataPathNotAllowed': 'the path is outside the range allowed for third-party plugin data and was refused: {path}',
+    'adapter.pluginDataNoOsHome': 'third-party plugin data lives under the system home directory, but this host offers no file channel for it (older host): nothing is read or imported this time',
+};
+registerMessageCatalog({ id: 'adapters-domain', zh, en });
+/** 本域活翻译器（与 core 的 engineMsg 同一实现；导入本模块即完成目录注册）。 */
+export const engineMsg = engineMsgOf;
+//# sourceMappingURL=messages.js.map

package/lib/adapters/plugin-data.d.ts

@@ -0,0 +1,114 @@
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
+import type { PluginDataArea, PluginDataSource, PluginDataSection } from '../core/plugin-data-registry.ts';
+import { FileCollectionAdapter } from './file-collection.ts';
+import type { FilesSection } from '../schema/types.ts';
+import type { ApplyResult, ExportOptions, ExportSection, HostContext, ImportContext, PlanItem, SectionPreview } from '../core/types.ts';
+/** 区域条目（来源 + 区域），编译期与运行期唯一的区域表示 */
+export type PluginDataEntry = {
+    source: PluginDataSource;
+    area: PluginDataArea;
+};
+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 declare class PluginDataAdapter extends FileCollectionAdapter {
+    readonly id: PluginDataSection;
+    readonly displayName: string;
+    readonly defaultIncluded = false;
+    readonly portability: 'deviceSpecific';
+    /** home 根（相对路径 = home 相对路径，与 agentInstructions 同形） */
+    readonly baseDir = "";
+    private readonly builtin;
+    private readonly declaredTtlMs;
+    private readonly env;
+    /**
+     * 自述声明缓存。**必须带 ctx 键**（homeDir + profile）：这台机器装了某插件，不代表另一台装了 ——
+     * 缓存若按实例共享，导入到「没装该插件」的目标机时会拿源机的声明去放行写入，
+     * 白名单就变成了「谁先导入谁说了算」。
+     */
+    private declaredMemo;
+    /** 本轮清单（listRelPaths 写入；unitIdOf 是同步纯函数，只能从这里拿区域表） */
+    private active;
+    /** 本轮告警（环境变量覆盖跳过等；export/preview 收尾合并进返回的 warnings） */
+    private pendingWarnings;
+    constructor(section: PluginDataSection, options?: PluginDataAdapterOptions);
+    /** 本分区可收集区域（内置 + 自述声明） */
+    private allowedEntries;
+    private allSources;
+    /**
+     * 已安装插件的自述声明（dsh.dataDirs）。
+     *
+     * 为什么读 profile 的 node_modules 而不是全局目录：DSH 的插件装在 \`profiles/<profile>/node_modules\`
+     * 下（pnpm 隔离布局），且同一个包在不同 profile 可以是不同版本 —— 声明必须取**本 profile 实际装的**那份。
+     *
+     * 读不到（未安装 / 无声明 / 形状非法）一律跳过：本机制是**附加**信息，绝不因为一个包读不出来
+     * 就影响内置来源或整次导出。
+     */
+    private declaredSources;
+    /**
+     * 区域是否被环境变量覆盖（覆盖 → 返回变量名；未覆盖 / 未声明 → null）。
+     *
+     * 判定口径：变量**存在且解析结果与默认位置不同**才算覆盖 —— 仅仅 \`DSH_WE_DATA_DIR=~/.dsh-wallpaper-engine\`
+     * 这种「设成同一个值」的写法不该让区域凭空消失（那会让用户以为「没有数据」）。
+     * 解析只做 \`~\` 展开与分隔符归一（不做 realpath：不读盘、不猜）。
+     */
+    private envOverrideOf;
+    /**
+     * 区域是否是**普通文件**（而不是目录 / 不存在）。
+     *
+     * 判据顺序为什么是这样：`statSize` 对「非普通文件」与「不存在」都返回 null，无法单独区分
+     * 目录与缺失；所以先判「是文件」，其余一律按目录走遍历 —— 目录不存在时遍历返回空，
+     * 结果同样是「没有内容」，不会把缺失误报成文件，也不会把目录误读成空内容而静默丢数据。
+     * 门面未实现 statSize（旧宿主）时退回读一次内容：读得出来就是文件。
+     */
+    private isRegularFile;
+    private static emptyListing;
+    /**
+     * 清单枚举 = 来源注册表的区域（覆写基类的目录递归；baseDir='' 时基类实现会递归**整个 home**）。
+     *
+     * **必须覆写**：home 根上递归会遍历 profiles/ sessions/ attachments/ 等全部内容（本机实测
+     * 4000+ 文件 / 数百 MB），既慢又会把无关目录当成该分区的「可勾选单元」。
+     */
+    protected listRelPaths(ctx: HostContext): Promise<RecursiveListing>;
+    /**
+     * 单元 = 区域（最长前缀归属）。
+     *
+     * 用「本轮清单写入的区域表」而不是重新解析：listRelPaths 与本函数在同一次 collect 里成对调用，
+     * 重算会让两次解析结果不一致时出现「单元 id 不在清单里」（选择器勾不上）。测试/异常路径下
+     * \`active\` 可能是 undefined（例如直接调 listUnits），此时退回**内置来源**的最长前缀 —— 与清单口径同源。
+     */
+    protected unitIdOf(relativePath: string): string;
+    /**
+     * 读一个成员文件：**换根到系统 home 门面**（基类的其余逻辑 —— 体积、哈希、字节闸门 —— 一字不动）。
+     *
+     * 能走到这里说明 listRelPaths 产出过条目（缺门面时它不产出任何路径），因此缺门面即**抛错**，
+     * 不再造一个「空文件」出来（那会把缺通道伪装成空内容）。
+     */
+    protected readMember(ctx: HostContext, rel: string, mode: 'content' | 'size', statTimes?: Map<string, number>): Promise<{
+        data: Uint8Array;
+        sizeBytes: number;
+        contentHash: string;
+    }>;
+    export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<FilesSection>>;
+    preview(ctx: HostContext, options: ExportOptions): Promise<SectionPreview<FilesSection>>;
+    /**
+     * 导入分析 + **写入路径白名单**（本分区唯一的越界防线）。
+     *
+     * 判据：路径必须是本机可解析的某个区域（内置来源，或已安装插件的自述声明）之下，且未被该区域
+     * 的 excludeRel 排除。不满足 → Error（计划里可见、执行期不写），绝不「尽力而为」地写出去。
+     */
+    analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]>;
+    /** 应用前再查一遍白名单（纵深防御：plan 可能来自消费者手工构造/缓存反序列化） */
+    applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
+}

package/lib/adapters/plugin-data.js

@@ -0,0 +1,309 @@
+/**
+ * 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.js';
+import { engineMsg } from './messages.js';
+import { listFilesDetailed } from './link-report.js';
+import { sectionMeta } from '../schema/section-registry.js';
+import { BUILTIN_PLUGIN_DATA_SOURCES, areaOfPath, areasForSection, isExcludedRel, normalizeHomeRel, parseDeclaredDataDirs, } from '../core/plugin-data-registry.js';
+import { osHomeDirOf } from '../core/backup.js';
+import { FileCollectionAdapter } from './file-collection.js';
+/** 声明来源缓存的 TTL（毫秒）：一次导出/导入/执行里会多次解析，逐次读 15+ 个 package.json 是净开销 */
+const DECLARED_TTL_MS = 5_000;
+/** 单次解析里最多读取多少个已安装插件的 manifest（防御性上限：profile 依赖数量异常时不无限读） */
+const MAX_DECLARED_PACKAGES = 300;
+export class PluginDataAdapter extends FileCollectionAdapter {
+    id;
+    displayName;
+    defaultIncluded = false;
+    portability = 'deviceSpecific';
+    /** home 根（相对路径 = home 相对路径，与 agentInstructions 同形） */
+    baseDir = '';
+    builtin;
+    declaredTtlMs;
+    env;
+    /**
+     * 自述声明缓存。**必须带 ctx 键**（homeDir + profile）：这台机器装了某插件，不代表另一台装了 ——
+     * 缓存若按实例共享，导入到「没装该插件」的目标机时会拿源机的声明去放行写入，
+     * 白名单就变成了「谁先导入谁说了算」。
+     */
+    declaredMemo;
+    /** 本轮清单（listRelPaths 写入；unitIdOf 是同步纯函数，只能从这里拿区域表） */
+    active;
+    /** 本轮告警（环境变量覆盖跳过等；export/preview 收尾合并进返回的 warnings） */
+    pendingWarnings = [];
+    constructor(section, options = {}) {
+        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;
+    }
+    /** 本分区可收集区域（内置 + 自述声明） */
+    async allowedEntries(ctx) {
+        const sources = await this.allSources(ctx);
+        return areasForSection(sources, this.id);
+    }
+    async allSources(ctx) {
+        const declared = await this.declaredSources(ctx);
+        return [...this.builtin, ...declared];
+    }
+    /**
+     * 已安装插件的自述声明（dsh.dataDirs）。
+     *
+     * 为什么读 profile 的 node_modules 而不是全局目录：DSH 的插件装在 \`profiles/<profile>/node_modules\`
+     * 下（pnpm 隔离布局），且同一个包在不同 profile 可以是不同版本 —— 声明必须取**本 profile 实际装的**那份。
+     *
+     * 读不到（未安装 / 无声明 / 形状非法）一律跳过：本机制是**附加**信息，绝不因为一个包读不出来
+     * 就影响内置来源或整次导出。
+     */
+    async declaredSources(ctx) {
+        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 = [];
+        let deps = [];
+        try {
+            const raw = await ctx.fs.readFile(base + '/package.json');
+            const parsed = JSON.parse(new TextDecoder().decode(raw));
+            const dep = parsed?.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 = 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：不读盘、不猜）。
+     */
+    envOverrideOf(ctx, area) {
+        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（旧宿主）时退回读一次内容：读得出来就是文件。
+     */
+    async isRegularFile(fsFacade, rel) {
+        if (fsFacade.statSize !== undefined) {
+            try {
+                return (await fsFacade.statSize(rel)) !== null;
+            }
+            catch {
+                return false;
+            }
+        }
+        try {
+            await fsFacade.readFile(rel);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    static emptyListing() {
+        return { paths: [], skippedLinks: [], skippedDepDirs: [], followedLinks: 0, unreadableDirs: [] };
+    }
+    /**
+     * 清单枚举 = 来源注册表的区域（覆写基类的目录递归；baseDir='' 时基类实现会递归**整个 home**）。
+     *
+     * **必须覆写**：home 根上递归会遍历 profiles/ sessions/ attachments/ 等全部内容（本机实测
+     * 4000+ 文件 / 数百 MB），既慢又会把无关目录当成该分区的「可勾选单元」。
+     */
+    async listRelPaths(ctx) {
+        // 本分区的根是**系统 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 = [];
+        const paths = [];
+        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;
+            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），此时退回**内置来源**的最长前缀 —— 与清单口径同源。
+     */
+    unitIdOf(relativePath) {
+        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 产出过条目（缺门面时它不产出任何路径），因此缺门面即**抛错**，
+     * 不再造一个「空文件」出来（那会把缺通道伪装成空内容）。
+     */
+    async readMember(ctx, rel, mode, statTimes) {
+        const homeFs = ctx.homeFs;
+        if (homeFs === undefined)
+            throw new Error(engineMsg('adapter.pluginDataNoOsHome'));
+        return super.readMember({ ...ctx, fs: homeFs }, rel, mode, statTimes);
+    }
+    async export(ctx, options) {
+        this.pendingWarnings = [];
+        const out = await super.export(ctx, options);
+        return { ...out, warnings: [...out.warnings, ...this.pendingWarnings] };
+    }
+    async preview(ctx, options) {
+        this.pendingWarnings = [];
+        const out = await super.preview(ctx, options);
+        return {
+            ...out,
+            section: { ...out.section, warnings: [...out.section.warnings, ...this.pendingWarnings] },
+        };
+    }
+    /**
+     * 导入分析 + **写入路径白名单**（本分区唯一的越界防线）。
+     *
+     * 判据：路径必须是本机可解析的某个区域（内置来源，或已安装插件的自述声明）之下，且未被该区域
+     * 的 excludeRel 排除。不满足 → Error（计划里可见、执行期不写），绝不「尽力而为」地写出去。
+     */
+    async analyzeImport(data, ctx) {
+        // 宿主没有系统 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 可能来自消费者手工构造/缓存反序列化） */
+    async applyItem(item, ctx) {
+        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 } });
+    }
+}
+//# sourceMappingURL=plugin-data.js.map

package/lib/adapters/plugin-files.js

@@ -8,6 +8,7 @@
  */
 import { sha256Hex } from '../utils/hashing.js';
 import { msgOf, zhMsg } from '../core/messages.js';
+import { engineMsg } from './messages.js';
 import { linkWarnings, listFilesDetailed } from './link-report.js';
 import { isPathSafe, isReservedInternalRel } from '../utils/paths.js';
 import { unitAllowed, unitsFromFiles } from './units.js';
@@ -26,7 +27,7 @@ export class PluginFilesAdapter {
     constructor(whitelist = [...DEFAULT_PLUGIN_FILE_WHITELIST], collectDir) {
         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;
     }
@@ -55,7 +56,7 @@ export class PluginFilesAdapter {
         }
         // 2) 约定配置目录递归收集（相对 ~/.dsh 根的完整路径；与白名单文件去重）
         // issue #37：与 skills 等同一条遍历（跟随 junction/符号链接 + 跳过留痕）
-        let listing = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
+        let listing = { paths: [], skippedLinks: [], skippedDepDirs: [], followedLinks: 0, unreadableDirs: [] };
         if (this.collectDir !== undefined) {
             try {
                 listing = await listFilesDetailed(ctx.fs, this.collectDir);