dsh-config-manager 0.1.68 → 0.1.70

package/lib/adapters/credentials.js

@@ -1,5 +1,5 @@
 import { msgOf, zhMsg } from '../core/messages.js';
-import { resolveNamespaces } from './settings.js';
+import { namespaceFromMap, readNamespaceMap, resolveNamespaces } from './settings.js';
 import { sectionMeta } from '../schema/section-registry.js';
 import { validateJsonSection } from './json-section.js';
 /** 缺省 ref 收集：遍历 settings namespace，收集 llm apiKeyEnv / providers[].apiKeyEnv，
@@ -9,9 +9,12 @@ import { validateJsonSection } from './json-section.js';
 export function defaultCredentialRefs(namespaces) {
     return async (ctx) => {
         const refs = new Set();
-        for (const ns of await resolveNamespaces(namespaces, ctx)) {
+        const names = await resolveNamespaces(namespaces, ctx);
+        // 快路径：宿主能一次读回全部 namespace 时只读一趟（理由见 settings.ts readNamespaceMap）
+        const all = names.length > 0 ? await readNamespaceMap(ctx) : null;
+        for (const ns of names) {
             try {
-                const info = await ctx.settings.describe(ns, { redactSecrets: true });
+                const info = all !== null ? namespaceFromMap(all, ns) : await ctx.settings.describe(ns, { redactSecrets: true });
                 const value = (info.value ?? {});
                 // 引用类字段名（值 = env/凭据引用名，非秘密本身）
                 const REFERENCE_REF_FIELDS = new Set([

package/lib/adapters/file-collection.d.ts

@@ -1,4 +1,5 @@
 import type { MsgFunc } from '../core/messages.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
 import type { FilesSection, SectionId } from '../schema/types.ts';
 import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, Portability, SectionPreview, ValidationResult } from '../core/types.ts';
 /**
@@ -87,6 +88,14 @@ export declare abstract class FileCollectionAdapter implements ConfigAdapter<Fil
      * `FilesSection` 是备份格式的一部分，多带内部字段会被序列化出去；体积走旁路 `sizes`。
      */
     private collect;
+    /**
+     * 分区清单枚举（`export` / `preview` 共用；两者必须走同一份清单，否则预览与导出分叉）。
+     *
+     * **单文件分区必须覆写它**：`AgentInstructionsAdapter` 的 `baseDir` 是 ''（AGENTS.md 就放在
+     * `$DSH_HOME` 根），走缺省实现会递归**整个 home** —— 实测 4016 个文件 / 242 MB / 4.8 s，而且
+     * 选择器会把 `profiles/`、`sessions/`、`attachments/` 这些无关目录当成该分区的「单元」。
+     */
+    protected listRelPaths(ctx: HostContext): Promise<RecursiveListing>;
     /**
      * 读一个成员文件。
      *
@@ -94,10 +103,30 @@ export declare abstract class FileCollectionAdapter implements ConfigAdapter<Fil
      * - `size`：优先 `ctx.fs.statSize`（只 stat，不读内容）；门面未实现或返回 null（文件消失 /
      *   读不到）时**退回 readFile** —— 与改造前把「读不到」暴露成同一个错误，绝不把未知体积
      *   当成 0（0 会让字节闸门少算，把本该剔除的单元放进预览，预览与导出就分叉了）。
+     *
+     * 受保护而非私有（issue #71）：`SkillsAdapter` 的成员有一部分**不在磁盘上**
+     * （来自 `ctx.skills` 技能服务的技能被重建成 `<name>/SKILL.md` 虚拟路径），
+     * 需要在这里按路径分流 —— 覆写后基类的单元分组 / 字节闸门 / 告警 / 预览-导出一致性全部照旧。
      */
-    private readMember;
+    protected readMember(ctx: HostContext, rel: string, mode: 'content' | 'size', statTimes?: Map<string, number>): Promise<{
+        data: Uint8Array;
+        sizeBytes: number;
+        contentHash: string;
+    }>;
     /** 单元清单（零 I/O：直接由 export 产物归并）。 */
     listUnits(section: ExportSection<FilesSection>): ExportUnit[];
+    /**
+     * 幂等比对用的内容（相对 baseDir 路径 + 盘上/包内字节 → 参与哈希比对的字节）。
+     *
+     * 缺省 = **原字节**：对文件类分区来说「相对路径 + 内容哈希」就是身份语义，不得改动。
+     * 覆写者只应用于剔除**不属于「配置身份」的易变字段**（见 SelfAdapter 的两个调度配置：
+     * 运行态每轮都被改写，整文件哈希会恒判 Conflict —— issue #73）。两条契约：
+     *   1. **必须收敛**：applyItem 写盘后再分析一次必须判 Skip，否则同步永不收敛；
+     *   2. **未改写时返回同一引用** —— 调用方据此复用导入侧已算好的 contentHash，
+     *      不给 sessions 这类大分区白算一遍哈希。
+     * 判不出可比形态（解析失败等）时必须**原样返回**：绝不把「判不出来」当成「相同」或「不同」。
+     */
+    protected comparableContent(_relativePath: string, data: Uint8Array): Uint8Array;
     analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]>;
     applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
     /**

package/lib/adapters/file-collection.js

@@ -129,6 +129,8 @@ export class FileCollectionAdapter {
             },
             sizeBytes: collected.totalBytes,
             items: unitsFromEntries(this.id, collected.sizes, (rel) => this.unitIdOf(rel)),
+            // 本趟 stat 顺带取到的时间（宿主有 statInfo 时才有）：调用方据此省掉第二趟逐文件 stat。
+            ...(collected.statTimes.size > 0 ? { statTimes: collected.statTimes } : {}),
         };
     }
     /**
@@ -145,14 +147,16 @@ export class FileCollectionAdapter {
      */
     async collect(ctx, options, mode) {
         const files = [];
+        const statTimes = new Map();
         const sizes = [];
         const warnings = [];
         const allow = options.includeItems?.[this.id];
         // issue #37：用「跟随 junction/符号链接」的遍历，并把跟随/跳过的链接写进告警——
         // 此前链接目录及其全部内容被静默排除，备份仍报成功。
+        // 枚举走 listRelPaths 钩子（单文件分区覆写它，避免对 home 根整目录递归）。
         let listing = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
         try {
-            listing = await listFilesDetailed(ctx.fs, this.baseDir);
+            listing = await this.listRelPaths(ctx);
         }
         catch {
             // 目录不存在视为空
@@ -198,7 +202,7 @@ export class FileCollectionAdapter {
             const pending = [];
             let unitBytes = 0;
             for (const member of unitEntries.get(unitId) ?? []) {
-                const read = await this.readMember(ctx, member.rel, mode);
+                const read = await this.readMember(ctx, member.rel, mode, statTimes);
                 unitBytes += read.sizeBytes;
                 if (unitBytes > room)
                     break;
@@ -239,7 +243,17 @@ export class FileCollectionAdapter {
         if (rels.length === 0)
             warnings.push(msgOf(ctx)('adapter.dirEmpty', { type: this.displayName }));
         warnings.push(...linkWarnings(msgOf(ctx), this.displayName, listing));
-        return { entries: files, sizes, totalBytes: usedBytes, warnings };
+        return { entries: files, sizes, totalBytes: usedBytes, warnings, statTimes };
+    }
+    /**
+     * 分区清单枚举（`export` / `preview` 共用；两者必须走同一份清单，否则预览与导出分叉）。
+     *
+     * **单文件分区必须覆写它**：`AgentInstructionsAdapter` 的 `baseDir` 是 ''（AGENTS.md 就放在
+     * `$DSH_HOME` 根），走缺省实现会递归**整个 home** —— 实测 4016 个文件 / 242 MB / 4.8 s，而且
+     * 选择器会把 `profiles/`、`sessions/`、`attachments/` 这些无关目录当成该分区的「单元」。
+     */
+    async listRelPaths(ctx) {
+        return listFilesDetailed(ctx.fs, this.baseDir);
     }
     /**
      * 读一个成员文件。
@@ -248,9 +262,22 @@ export class FileCollectionAdapter {
      * - `size`：优先 `ctx.fs.statSize`（只 stat，不读内容）；门面未实现或返回 null（文件消失 /
      *   读不到）时**退回 readFile** —— 与改造前把「读不到」暴露成同一个错误，绝不把未知体积
      *   当成 0（0 会让字节闸门少算，把本该剔除的单元放进预览，预览与导出就分叉了）。
+     *
+     * 受保护而非私有（issue #71）：`SkillsAdapter` 的成员有一部分**不在磁盘上**
+     * （来自 `ctx.skills` 技能服务的技能被重建成 `<name>/SKILL.md` 虚拟路径），
+     * 需要在这里按路径分流 —— 覆写后基类的单元分组 / 字节闸门 / 告警 / 预览-导出一致性全部照旧。
      */
-    async readMember(ctx, rel, mode) {
+    async readMember(ctx, rel, mode, statTimes) {
         if (mode === 'size') {
+            // 优先 statInfo：一次 stat 同时拿体积与 mtime（sessions 的排序时间顺带就有了，
+            // 省掉 unitActivityTimes 的第二趟逐文件 stat —— 实测会话树 983 个文件）。
+            if (ctx.fs.statInfo !== undefined) {
+                const info = await ctx.fs.statInfo(rel);
+                if (info !== null) {
+                    statTimes?.set(rel, info.mtimeMs);
+                    return { data: EMPTY_DATA, sizeBytes: info.size, contentHash: '' };
+                }
+            }
             const size = (await ctx.fs.statSize?.(rel)) ?? null;
             if (size !== null)
                 return { data: EMPTY_DATA, sizeBytes: size, contentHash: '' };
@@ -262,6 +289,20 @@ export class FileCollectionAdapter {
     listUnits(section) {
         return unitsFromFiles(this.id, section.data.files, (rel) => this.unitIdOf(rel));
     }
+    /**
+     * 幂等比对用的内容（相对 baseDir 路径 + 盘上/包内字节 → 参与哈希比对的字节）。
+     *
+     * 缺省 = **原字节**：对文件类分区来说「相对路径 + 内容哈希」就是身份语义，不得改动。
+     * 覆写者只应用于剔除**不属于「配置身份」的易变字段**（见 SelfAdapter 的两个调度配置：
+     * 运行态每轮都被改写，整文件哈希会恒判 Conflict —— issue #73）。两条契约：
+     *   1. **必须收敛**：applyItem 写盘后再分析一次必须判 Skip，否则同步永不收敛；
+     *   2. **未改写时返回同一引用** —— 调用方据此复用导入侧已算好的 contentHash，
+     *      不给 sessions 这类大分区白算一遍哈希。
+     * 判不出可比形态（解析失败等）时必须**原样返回**：绝不把「判不出来」当成「相同」或「不同」。
+     */
+    comparableContent(_relativePath, data) {
+        return data;
+    }
     async analyzeImport(data, ctx) {
         const msg = ctx.msg;
         const items = [];
@@ -294,15 +335,21 @@ export class FileCollectionAdapter {
                     target: { adapter: this.id, ref: file.relativePath },
                 });
             }
-            else if (sha256Hex(current) === file.contentHash) {
-                items.push({ id, unitId, kind: 'Skip', adapter: this.id, description: msg('adapter.fileSame', { path: file.relativePath }), severity: 'info' });
-            }
             else {
-                items.push({
-                    id, unitId, kind: 'Conflict', adapter: this.id,
-                    description: msg('adapter.fileDiff', { path: file.relativePath }), severity: 'warning',
-                    target: { adapter: this.id, ref: file.relativePath },
-                });
+                // 幂等判定统一走 comparableContent（缺省 = 原字节）；包内文件未被改写时复用已算好的
+                // contentHash，不给 sessions 这类大分区白算一遍哈希（盘上文件本来就要现算）。
+                const importedComparable = this.comparableContent(file.relativePath, file.data);
+                const importedHash = importedComparable === file.data ? file.contentHash : sha256Hex(importedComparable);
+                if (sha256Hex(this.comparableContent(file.relativePath, current)) === importedHash) {
+                    items.push({ id, unitId, kind: 'Skip', adapter: this.id, description: msg('adapter.fileSame', { path: file.relativePath }), severity: 'info' });
+                }
+                else {
+                    items.push({
+                        id, unitId, kind: 'Conflict', adapter: this.id,
+                        description: msg('adapter.fileDiff', { path: file.relativePath }), severity: 'warning',
+                        target: { adapter: this.id, ref: file.relativePath },
+                    });
+                }
             }
         }
         return items;

package/lib/adapters/mcp.d.ts

@@ -1,18 +1,28 @@
 import type { MsgFunc } from '../core/messages.ts';
 import type { McpServerEntry } from '../schema/types.ts';
 import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
-/** 导出记录：McpServerEntry 之外附加来源 patch 行 id（导入写回定位用） */
+/** 导出记录：McpServerEntry 之外附加来源 patch 行 id 与所在层（导入写回定位用） */
 export interface McpExportEntry extends McpServerEntry {
     sourceLineId: string;
+    /**
+     * 来源 patch 层（相对 homeDir 的 POSIX 路径；见 core/patch-layers.ts）。
+     * 缺省 = 用户层（旧备份包没有该字段 → 按旧行为写回 home 层）。
+     */
+    sourceFile?: string;
 }
 export interface McpExportSection {
     version: 1;
     servers: McpExportEntry[];
 }
-/** 从 patch 行数组中提取 MCP server 条目（以 config.serverName 存在为判定） */
+/**
+ * 从 patch 行数组中提取 MCP server 条目（以 config.serverName 存在为判定）。
+ *
+ * 行对象可带 `file`（层身份）：带上时逐条目记录 `sourceFile`，导入写回落回原层。
+ */
 export declare function extractMcpServers(lines: {
     lineId: string;
     raw: unknown;
+    file?: string;
 }[]): McpExportEntry[];
 /** 由导出条目构造写回 patch 行 raw（单行形态，与 dsh-mcp-client 组合 config 语义一致） */
 export declare function buildMcpPatchLine(lineId: string, server: McpServerEntry): Record<string, unknown>;

package/lib/adapters/mcp.js

@@ -5,13 +5,22 @@
  * dependencyChecker 执行（§15：缺失不阻塞，标记 Requires Attention）。
  *
  * patch 行 raw 支持两种形态：单行 { id, name, config } 与块 { insert: [{ id, name, config }] }。
+ *
+ * issue #71（真机报告「备份不到外壳 mcp」）：数据源是**两层** patch —— home 层
+ * （$DSH_HOME/cordis.patch.yml）与 profile 层（$DSH_HOME/profiles/<p>/cordis.patch.yml）。
+ * 此前只读 home 层，而 DSH 自己的 MCP 配置工具把 server 写进 profile 层，于是备份里
+ * servers 恒为空数组。现在两层都读，每行记住自己来自哪个文件，写回时落回原层。
  */
 import { isDeepStrictEqual } from 'node:util';
 import { msgOf, zhMsg } from '../core/messages.js';
 import { sectionMeta } from '../schema/section-registry.js';
 import { validateJsonSection } from './json-section.js';
-import { USER_PATCH_FILE } from './plugins.js';
-/** 从 patch 行数组中提取 MCP server 条目（以 config.serverName 存在为判定） */
+import { locatePatchLineLayer, readEffectivePatchLines, resolveWriteLayer } from '../core/patch-layers.js';
+/**
+ * 从 patch 行数组中提取 MCP server 条目（以 config.serverName 存在为判定）。
+ *
+ * 行对象可带 `file`（层身份）：带上时逐条目记录 `sourceFile`，导入写回落回原层。
+ */
 export function extractMcpServers(lines) {
     const servers = [];
     for (const line of lines) {
@@ -34,6 +43,7 @@ export function extractMcpServers(lines) {
                 url: typeof c['url'] === 'string' ? c['url'] : undefined,
                 headers: c['headers'] !== null && typeof c['headers'] === 'object' ? c['headers'] : undefined,
                 sourceLineId: line.lineId,
+                ...(line.file !== undefined ? { sourceFile: line.file } : {}),
             });
         }
     }
@@ -85,14 +95,12 @@ export class McpAdapter {
     portability = sectionMeta('mcp').portability;
     async export(ctx, _options) {
         const warnings = [];
-        let lines = [];
-        try {
-            lines = await ctx.patchFile.readPatchLines(USER_PATCH_FILE);
-        }
-        catch (err) {
-            warnings.push(msgOf(ctx)('adapter.patchReadFailedMCP', { reason: err instanceof Error ? err.message : String(err) }));
+        // issue #71：两层都读（home 层优先），否则 profile 层里的 server 全部丢失
+        const read = await readEffectivePatchLines(ctx.patchFile, ctx.profile);
+        for (const f of read.failures) {
+            warnings.push(msgOf(ctx)('adapter.patchReadFailedMCP', { reason: `${f.file}: ${f.reason}` }));
         }
-        const servers = extractMcpServers(lines);
+        const servers = extractMcpServers(read.lines);
         return {
             sectionId: 'mcp',
             data: { version: 1, servers },
@@ -103,13 +111,15 @@ export class McpAdapter {
     async analyzeImport(data, ctx) {
         const msg = ctx.msg;
         const items = [];
-        const targetLines = await ctx.target.patchFile.readPatchLines(USER_PATCH_FILE);
+        // issue #71：目标行跨两层；同一 lineId 只保留优先级最高的一层（与 DSH 合并序一致）
+        const targetLines = (await readEffectivePatchLines(ctx.target.patchFile, ctx.target.profile)).lines;
         const targetServers = extractMcpServers(targetLines);
         for (const server of data.servers) {
             const id = `mcp:${server.serverName}`;
             const existing = targetServers.find((s) => s.serverName === server.serverName);
             const comparable = { ...server };
             delete comparable.sourceLineId;
+            delete comparable.sourceFile;
             if (!existing) {
                 const lineId = server.sourceLineId && targetLines.some((l) => l.lineId === server.sourceLineId)
                     ? `${server.sourceLineId}-imported`
@@ -119,12 +129,14 @@ export class McpAdapter {
                     description: msg('adapter.mcpCreate', { serverName: server.serverName }),
                     detail: `${server.type === 'stdio' ? `${server.command} ${(server.args ?? []).join(' ')}` : server.url}`,
                     severity: 'info',
-                    target: { adapter: 'mcp', ref: lineId },
+                    // 目标层随计划项一起走：导入前快照要按**这一层**记原行，回滚才能写回原文件
+                    target: { adapter: 'mcp', ref: lineId, file: resolveWriteLayer(server.sourceFile, ctx.target.profile) },
                 });
             }
             else {
                 const existingComparable = { ...existing };
                 delete existingComparable.sourceLineId;
+                delete existingComparable.sourceFile;
                 if (isDeepStrictEqual(existingComparable, comparable)) {
                     items.push({ id, kind: 'Skip', adapter: 'mcp', description: msg('adapter.mcpSame', { serverName: server.serverName }), severity: 'info' });
                 }
@@ -134,7 +146,7 @@ export class McpAdapter {
                         description: msg('adapter.mcpDiff', { serverName: server.serverName }),
                         detail: `current=${JSON.stringify(existingComparable)} imported=${JSON.stringify(comparable)}`.slice(0, 200),
                         severity: 'warning',
-                        target: { adapter: 'mcp', ref: existing.sourceLineId },
+                        target: { adapter: 'mcp', ref: existing.sourceLineId, file: existing.sourceFile },
                     });
                 }
             }
@@ -152,7 +164,12 @@ export class McpAdapter {
         if (!ref)
             return { ok: false, message: msg('adapter.missingTargetRef') };
         const raw = buildMcpPatchLine(ref, server);
-        await ctx.target.patchFile.applyPatchChanges(USER_PATCH_FILE, [
+        // issue #71：Create 落「来源层的同语义层」（来源是 profile 层 → 目标机当前 profile 层），
+        // Update 落「该行当前所在层」—— 两种情况都不把行搬到另一层去（否则同一 lineId 两层各一份）
+        const file = item.kind === 'Create'
+            ? resolveWriteLayer(server.sourceFile, ctx.target.profile)
+            : await locatePatchLineLayer(ctx.target.patchFile, ctx.target.profile, ref);
+        await ctx.target.patchFile.applyPatchChanges(file, [
             { lineId: ref, raw, action: item.kind === 'Create' ? 'insert' : 'update' },
         ]);
         return { ok: true, needsRestart: true, message: msg('adapter.mcpWritten', { serverName }) };

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

@@ -12,6 +12,14 @@ export declare class PluginFilesAdapter implements ConfigAdapter<FilesSection> {
     private readonly collectDir?;
     constructor(whitelist?: string[], collectDir?: string);
     export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<FilesSection>>;
+    /**
+     * 读失败之后判定「这个路径本来就不存在」还是「存在但读不到」（ui-F2）。
+     *
+     * 为什么不用错误码：门面错误的形状并不统一（内存 mock 与各平台 EACCES 文案不同），
+     * 而 `exists()` 是 FileSystemFacade 契约里唯一稳定的存在性判据。`exists()` 自己也失败时
+     * 按「存在」处理（保守：宁可让这次导出显式失败，也不静默丢一个文件）。
+     */
+    private absentOnDisk;
     /** 单元清单（零 I/O）：逐文件单元，id 与导入侧 `pluginFiles:<relPath>` 一致。 */
     listUnits(section: ExportSection<FilesSection>): ExportUnit[];
     analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]>;

package/lib/adapters/plugin-files.js

@@ -45,8 +45,12 @@ export class PluginFilesAdapter {
                 files.push({ relativePath: rel, data, contentHash: sha256Hex(data) });
                 seen.add(rel);
             }
-            catch {
-                /* 白名单文件不存在则跳过 */
+            catch (err) {
+                // ui-F2：白名单文件**不存在**是正常形态（按需创建 → 跳过）；**读不到**（权限/竞态/断链）
+                // 绝不能静默丢内容 —— 与文件集合基类同一语义：整分区显式失败，导出报告可见。
+                if (await this.absentOnDisk(ctx, rel))
+                    continue;
+                throw err;
             }
         }
         // 2) 约定配置目录递归收集（相对 ~/.dsh 根的完整路径；与白名单文件去重）
@@ -69,8 +73,11 @@ export class PluginFilesAdapter {
                     const data = await ctx.fs.readFile(rel);
                     files.push({ relativePath: rel, data, contentHash: sha256Hex(data) });
                 }
-                catch {
-                    continue;
+                catch (err) {
+                    // ui-F2：同上 —— 目录遍历刚点到的文件却读不到，是真实的读取失败，不是「不存在」。
+                    if (await this.absentOnDisk(ctx, rel))
+                        continue;
+                    throw err;
                 }
             }
         }
@@ -81,6 +88,21 @@ export class PluginFilesAdapter {
             warnings: linkWarnings(msgOf(ctx), this.displayName, listing),
         };
     }
+    /**
+     * 读失败之后判定「这个路径本来就不存在」还是「存在但读不到」（ui-F2）。
+     *
+     * 为什么不用错误码：门面错误的形状并不统一（内存 mock 与各平台 EACCES 文案不同），
+     * 而 `exists()` 是 FileSystemFacade 契约里唯一稳定的存在性判据。`exists()` 自己也失败时
+     * 按「存在」处理（保守：宁可让这次导出显式失败，也不静默丢一个文件）。
+     */
+    async absentOnDisk(ctx, rel) {
+        try {
+            return (await ctx.fs.exists(rel)) === false;
+        }
+        catch {
+            return false;
+        }
+    }
     /** 单元清单（零 I/O）：逐文件单元，id 与导入侧 `pluginFiles:<relPath>` 一致。 */
     listUnits(section) {
         return unitsFromFiles(this.id, section.data.files, (rel) => rel);
@@ -144,6 +166,16 @@ export class PluginFilesAdapter {
         return validateJsonSection('pluginFiles', data, msg, (section, issues) => {
             if (!Array.isArray(section.files)) {
                 issues.push({ path: 'files', message: msg('adapter.validate.array', { subject: 'files' }), severity: 'error' });
+                return;
+            }
+            // ui-F3：条目级形状校验必须与 analyzeImport 的假设对齐（它直接读 file.relativePath）。
+            // 只校验「是数组」会放过 files:[null] / relativePath:42 这类畸形，analyzeImport 抛内部
+            // TypeError → ImportAnalysis.valid=false → 整包被拦下，用户看到的是内部异常文本。
+            for (const [i, f] of section.files.entries()) {
+                const entry = f;
+                if (entry === null || typeof entry !== 'object' || typeof entry.relativePath !== 'string' || entry.relativePath === '') {
+                    issues.push({ path: `files[${i}]`, message: msg('adapter.validate.fileRelativePath'), severity: 'error' });
+                }
             }
         });
     }

package/lib/adapters/plugins.d.ts

@@ -1,13 +1,20 @@
 import type { PackLocalPluginsResult } from '../core/local-plugin-pack.ts';
 import type { MsgFunc } from '../core/messages.ts';
+import { USER_PATCH_FILE } from '../core/patch-layers.ts';
 import type { PluginEntry, PluginsSection } from '../schema/types.ts';
-import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
-export declare const USER_PATCH_FILE = "cordis.patch.yml";
+import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, SectionPreview, ValidationResult } from '../core/types.ts';
+/**
+ * 用户（home）patch 层路径 —— 定义已移到 `core/patch-layers.ts`（issue #71：patch 有 home /
+ * profile 两层，层身份属于引擎知识，不属于某个 adapter）。此处 re-export 保持既有 import 面。
+ */
+export { USER_PATCH_FILE };
 /**
  * 本地源插件打包钩子（由宿主注入，见 src/index.ts createAdapters）。
  * 返回打包结果（含字节与重写后的 spec）；不注入 = 不做本地源打包（保持旧行为）。
  */
-export type LocalPluginPackHook = (plugins: PluginEntry[], ctx: HostContext) => Promise<PackLocalPluginsResult>;
+export type LocalPluginPackHook = (plugins: PluginEntry[], 
+/** 结构化类型：HostContext 满足它（core 侧刻意不 import adapters 的 HostContext 类型） */
+ctx: Pick<HostContext, 'profile' | 'profileDir'>) => Promise<PackLocalPluginsResult>;
 /** 本地插件 tarball 解包到 homeDir 内的固定缓存目录（相对 $DSH_HOME）。 */
 export declare const LOCAL_TARBALL_CACHE_REL = "dsh-config-manager/local-plugins";
 /** 归档内相对路径 → 缓存目录下的安全文件名（拒绝任何路径穿越）。 */
@@ -29,6 +36,27 @@ export declare class PluginsAdapter implements ConfigAdapter<PluginsSection> {
     private readonly localPack;
     constructor(selfName?: string, localPack?: LocalPluginPackHook);
     export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<PluginsSection>>;
+    /**
+     * 只读预览（`/export-preview` 用）：与 `export()` **同口径**，但不做任何本地源打包。
+     *
+     * 为什么必须覆写：基类缺省会让调用方退回 `export()`，而 `export()` 会为每个 `link:`/`file:`
+     * 插件 spawn 一次 `npm pack`（真机 12 个本地源插件 ≈12 s）。「总览」页只想知道条目数与体积，
+     * 却因此每次都要打包一遍全部本地插件 —— 预览是纯只读路径，不该有任何进程副作用。
+     *
+     * 与 `export()` 的**唯一**差异：
+     * - 不注入 `localTarballs`（没有字节），故清单 spec 保持原样（不做 `file:<tarball>` 改写）；
+     * - 插件单元体积改为 `file:` 源的一次 stat（`measureLocalSources`），`link:` 目录按 0；
+     * - 体积用一次 `stringify` 算 UTF-8 字节数（与 /export-preview 对 JSON 分区的口径一致）。
+     * 其余（清单过滤、patch 行、pnpm-workspace、patchFiles、条目级白名单、告警文案、单元分组）逐字相同。
+     */
+    preview(ctx: HostContext, options: ExportOptions): Promise<SectionPreview<PluginsSection>>;
+    /**
+     * 导出与预览的共同内核。
+     *
+     * `pack=false` 时跳过本地源打包（预览路径）—— 除该段外两条路径逐字共用，
+     * 避免「预览说会带什么」与「导出真的带什么」分叉。
+     */
+    private collect;
     /**
      * 单元清单（Phase 1；零 I/O：直接由 export 产物派生）。
      *