dsh-config-manager 0.1.76 → 0.1.78

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

@@ -0,0 +1,12 @@
+import type { PluginDataSource } from '../core/plugin-data-registry.ts';
+import type { HostContext } from '../core/types.ts';
+/** 单次扫描最多读取多少个已安装插件的 manifest（防御性上限：profile 依赖数量异常时不无限读） */
+export declare const MAX_DECLARED_PACKAGES = 300;
+/**
+ * 解析声明时用的 profile 目录名。
+ *
+ * 与 DSH 的 profile 解析同口径：空 / undefined = \`web\`（与改造前的私有实现一致）。
+ */
+export declare function declaredProfileName(profile: string | undefined): string;
+/** 扫描本机已安装插件自述的数据目录声明（零副作用；读不到的一律跳过）。 */
+export declare function scanDeclaredDataSources(ctx: HostContext, maxPackages?: number): Promise<PluginDataSource[]>;

package/lib/adapters/plugin-data-declared.js

@@ -0,0 +1,57 @@
+/**
+ * 「已安装插件自述数据目录（dsh.dataDirs）」的**单一扫描实现**。
+ *
+ * 为什么单独一个模块：这份扫描有两个消费者 ——
+ *  - \`pluginData\` / \`pluginAssets\` adapter（决定要收集哪些区域）；
+ *  - \`plugins\` adapter（导出选择器「按插件看」需要知道**每个插件自己声明的数据区域**，
+ *    才能在不读任何数据目录的前提下画出树骨架）。
+ * 两处各写一份必然漂移（同一条铁律：同一事实只有一份实现）。
+ *
+ * 语义（与改造前 plugin-data.ts 的私有实现逐字一致）：
+ *  - 读的是 **profile 实际安装**的那份 manifest（\`profiles/<profile>/node_modules/<pkg>/package.json\`），
+ *    不是全局目录 —— 同一个包在不同 profile 可以是不同版本，声明必须取本 profile 装的；
+ *  - 读不到（未安装 / 无声明 / 形状非法）一律跳过：本机制是**附加**信息，绝不因为一个包读不出来
+ *    就影响内置来源或整次导出；
+ *  - 本函数**不缓存**（缓存策略由调用方决定：pluginData 有实例级 TTL 缓存，plugins 有模块级缓存）。
+ */
+import { parseDeclaredDataDirs } from '../core/plugin-data-registry.js';
+/** 单次扫描最多读取多少个已安装插件的 manifest（防御性上限：profile 依赖数量异常时不无限读） */
+export const MAX_DECLARED_PACKAGES = 300;
+/**
+ * 解析声明时用的 profile 目录名。
+ *
+ * 与 DSH 的 profile 解析同口径：空 / undefined = \`web\`（与改造前的私有实现一致）。
+ */
+export function declaredProfileName(profile) {
+    return profile !== undefined && profile !== '' ? profile : 'web';
+}
+/** 扫描本机已安装插件自述的数据目录声明（零副作用；读不到的一律跳过）。 */
+export async function scanDeclaredDataSources(ctx, maxPackages = MAX_DECLARED_PACKAGES) {
+    const base = 'profiles/' + declaredProfileName(ctx.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, maxPackages);
+    }
+    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 → 无声明，跳过
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=plugin-data-declared.js.map

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

@@ -47,13 +47,11 @@ export declare class PluginDataAdapter extends FileCollectionAdapter {
     private allowedEntries;
     private allSources;
     /**
-     * 已安装插件的自述声明（dsh.dataDirs）。
+     * 已安装插件的自述声明（dsh.dataDirs）—— 本方法只做**缓存**，扫描实现见 plugin-data-declared.ts。
      *
-     * 为什么读 profile 的 node_modules 而不是全局目录：DSH 的插件装在 \`profiles/<profile>/node_modules\`
-     * 下（pnpm 隔离布局），且同一个包在不同 profile 可以是不同版本 —— 声明必须取**本 profile 实际装的**那份。
-     *
-     * 读不到（未安装 / 无声明 / 形状非法）一律跳过：本机制是**附加**信息，绝不因为一个包读不出来
-     * 就影响内置来源或整次导出。
+     * 为什么缓存必须带 ctx 键（homeDir + profile）：DSH 的插件装在 \`profiles/<profile>/node_modules\`
+     * 下（pnpm 隔离布局），而「这台机器装了某插件」不代表另一台装了 —— 缓存若按实例共享，
+     * 导入到「没装该插件」的目标机时会拿源机的声明去放行写入，白名单就变成「谁先导入谁说了算」。
      */
     private declaredSources;
     /**

package/lib/adapters/plugin-data.js

@@ -30,13 +30,12 @@ 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 { BUILTIN_PLUGIN_DATA_SOURCES, areaOfPath, areasForSection, isExcludedRel, normalizeHomeRel, } from '../core/plugin-data-registry.js';
+import { declaredProfileName, scanDeclaredDataSources } from './plugin-data-declared.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;
@@ -75,48 +74,21 @@ export class PluginDataAdapter extends FileCollectionAdapter {
         return [...this.builtin, ...declared];
     }
     /**
-     * 已安装插件的自述声明（dsh.dataDirs）。
+     * 已安装插件的自述声明（dsh.dataDirs）—— 本方法只做**缓存**，扫描实现见 plugin-data-declared.ts。
      *
-     * 为什么读 profile 的 node_modules 而不是全局目录：DSH 的插件装在 \`profiles/<profile>/node_modules\`
-     * 下（pnpm 隔离布局），且同一个包在不同 profile 可以是不同版本 —— 声明必须取**本 profile 实际装的**那份。
-     *
-     * 读不到（未安装 / 无声明 / 形状非法）一律跳过：本机制是**附加**信息，绝不因为一个包读不出来
-     * 就影响内置来源或整次导出。
+     * 为什么缓存必须带 ctx 键（homeDir + profile）：DSH 的插件装在 \`profiles/<profile>/node_modules\`
+     * 下（pnpm 隔离布局），而「这台机器装了某插件」不代表另一台装了 —— 缓存若按实例共享，
+     * 导入到「没装该插件」的目标机时会拿源机的声明去放行写入，白名单就变成「谁先导入谁说了算」。
      */
     async declaredSources(ctx) {
         const now = Date.now();
-        const profile = ctx.profile !== undefined && ctx.profile !== '' ? ctx.profile : 'web';
-        const memoKey = ctx.homeDir + '|' + profile;
+        const memoKey = ctx.homeDir + '|' + declaredProfileName(ctx.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 → 无声明，跳过
-            }
-        }
+        const out = await scanDeclaredDataSources(ctx);
         this.declaredMemo = { key: memoKey, at: now, sources: out };
         return out;
     }

package/lib/adapters/plugins.d.ts

@@ -72,6 +72,22 @@ export declare class PluginsAdapter implements ConfigAdapter<PluginsSection> {
      * 不做任何写入（写入在 applyItem 内、且先于 pnpm-workspace.yaml）。
      */
     private patchAvailability;
+    /**
+     * 读目标机 profile 的 `dsh.profile.bundles`（issue #95）。
+     *
+     * 相对路径与写入目标同源（`profiles/<profile>/package.json`），走 `ctx.target.fs` 而不是
+     * 宿主私有通道：与 pnpm-workspace.yaml / patch 文件同一条 I/O 纪律（受限、可被 MemFs 测试）。
+     */
+    private targetBundles;
+    /**
+     * 把 host 自带的层声明进目标机 profile 的 `dsh.profile.bundles`（issue #95）。
+     *
+     * 为什么**不走安装通道**：这类层的包由 DSH 从自己的安装位置解析；按裸包名 `dsh plugin add`
+     * 会把 npm `dist-tags.latest` 的副本装进 profile，与 host 的版本线脱节 —— 真机故障：
+     * host 0.2.1-rc.2 + 包 0.2.1-alpha.2 的隔离组契约对不上 → `session-controller` 一直 pending
+     * → 新建会话 service-unavailable。声明不了时只报非致命 warning（§34.17），不拖垮其余配置。
+     */
+    private declareHostBundle;
     analyzeImport(data: PluginsSection, ctx: ImportContext): Promise<PlanItem[]>;
     applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
     validate(data: PluginsSection, msg?: MsgFunc): Promise<ValidationResult>;

package/lib/adapters/plugins.js

@@ -13,16 +13,18 @@
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { sha256Hex } from '../utils/hashing.js';
-import { installSpecFor, resolveProcessProfileName } from '../core/plugin-cli.js';
+import { installSpecFor, isBundlesOnlyEntry, mergeBundleDeclaration, resolveProcessProfileName } from '../core/plugin-cli.js';
 import { classifyPluginSpec, LOCAL_PLUGIN_DIR, resolveLocalPluginPath } from '../core/local-plugin-pack.js';
 import { msgOf, zhMsg } from '../core/messages.js';
 import { engineMsg } from './messages.js';
 import { stringifyJsonSafe } from '../utils/json.js';
 import { isPathSafe, normalizePath } from '../utils/paths.js';
 import { isENOENT } from '../utils/guards.js';
-import { PLUGIN_PATCH_REF_PREFIX } from '../core/backup.js';
+import { PLUGIN_PATCH_REF_PREFIX, PLUGIN_PROFILE_MANIFEST_REF } from '../core/backup.js';
 import { readEffectivePatchLines, resolveWriteLayer, USER_PATCH_FILE } from '../core/patch-layers.js';
 import { parsePnpmPatchedDependencies, sanitizePnpmWorkspacePatches } from './pnpm-workspace.js';
+import { BUILTIN_PLUGIN_DATA_SOURCES, areasForSection } from '../core/plugin-data-registry.js';
+import { declaredProfileName, scanDeclaredDataSources } from './plugin-data-declared.js';
 import { sectionMeta } from '../schema/section-registry.js';
 import { validateJsonSection } from './json-section.js';
 /**
@@ -126,6 +128,66 @@ function entriesOfRaw(raw) {
  * 导出产物（真实 base64）走另一条分支，行为逐字不变。
  */
 const previewTarballBytes = new WeakMap();
+/**
+ * 「插件包名 → 它声明的数据区域」映射（只有 \`plugin:<包名>\` 单元用；导出选择器「按插件看」的树骨架）。
+ *
+ * 为什么挂 WeakMap 而不是给 PluginsSection 加字段：这是**展示用旁路信息** —— 既不是备份格式的
+ * 一部分（schema 校验与市场防线都不该看见它），也与「导出真的带什么」无关；挂在载荷对象上随对象
+ * 一起回收，载荷本身逐字节不变（与 previewTarballBytes 同一套理由）。
+ */
+const relatedAreasByData = new WeakMap();
+/** 内置来源 + 自述声明的扫描缓存（TTL 内的同一 home/profile 只扫一次；/export-preview 一趟会问两次） */
+const declaredSourcesMemo = { key: '', at: 0, sources: [] };
+const DECLARED_MEMO_TTL_MS = 5_000;
+/**
+ * 本机可归属的插件数据来源 = 内置来源表 + 已安装插件自述声明。
+ *
+ * 缓存键必须带 homeDir + profile：同一台机器换 profile 就是另一批已安装插件，拿旧声明画树
+ * 会让用户看到不属于当前 profile 的数据区域。
+ */
+async function pluginDataSources(ctx) {
+    const key = ctx.homeDir + '|' + declaredProfileName(ctx.profile);
+    const now = Date.now();
+    if (declaredSourcesMemo.key === key && now - declaredSourcesMemo.at < DECLARED_MEMO_TTL_MS) {
+        return declaredSourcesMemo.sources;
+    }
+    const sources = [...BUILTIN_PLUGIN_DATA_SOURCES, ...await scanDeclaredDataSources(ctx)];
+    declaredSourcesMemo.key = key;
+    declaredSourcesMemo.at = now;
+    declaredSourcesMemo.sources = sources;
+    return sources;
+}
+/**
+ * 包名 → 该插件的数据区域引用。
+ *
+ * 口径与 pluginData / pluginAssets 的收集面**同源**（同一个 areasForSection）：role=config 进
+ * pluginData、role=assets 进 pluginAssets；role=cache 的区域不属于任何分区，因此**绝不进树**
+ * （缓存是可再生产物，列出来只会诱导用户把它带走）。
+ *
+ * 只产出「注册表说它应该在哪儿」，不代表磁盘上真有 —— 界面必须把两者分开渲染。
+ */
+async function relatedAreasOf(ctx) {
+    const sources = await pluginDataSources(ctx);
+    const map = new Map();
+    for (const source of sources) {
+        const refs = [];
+        for (const section of ['pluginData', 'pluginAssets']) {
+            for (const entry of areasForSection([source], section)) {
+                refs.push({ section, relPath: entry.area.relPath, role: entry.area.role === 'assets' ? 'assets' : 'config' });
+            }
+        }
+        if (refs.length === 0)
+            continue;
+        for (const pkg of source.packages) {
+            const cur = map.get(pkg);
+            if (cur === undefined)
+                map.set(pkg, [...refs]);
+            else
+                cur.push(...refs);
+        }
+    }
+    return map;
+}
 /**
  * 零 spawn 推导本地源插件的体积（预览专用）。
  *
@@ -179,7 +241,7 @@ async function measureLocalSources(plugins, ctx) {
  * `tarballBytes` = 预览路径登记到的本地源体积（见 measureLocalSources，0 = 体积未知但仍随包携带）；
  * 缺省时体积与文件数完全按导出产物里的 base64 计算 —— 与改造前逐字一致。
  */
-function unitsOf(data, tarballBytes) {
+function unitsOf(data, tarballBytes, related) {
     const wsId = 'plugins:pnpm-workspace';
     const patchFileIds = (data.patchFiles ?? []).map((pf) => `plugins:patch:${normalizePath(pf.relativePath)}`);
     const group = [wsId, ...patchFileIds];
@@ -187,6 +249,7 @@ function unitsOf(data, tarballBytes) {
     for (const pl of data.plugins) {
         const tarball = tarballOf(data, pl.name);
         const measured = tarballBytes?.get(pl.name);
+        const areas = related?.get(pl.name);
         units.push({
             id: `plugin:${pl.name}`,
             label: pl.name,
@@ -194,6 +257,8 @@ function unitsOf(data, tarballBytes) {
             // base64 长度 → 原始字节数（仅用于展示体积，不求精确）；预览路径没有字节，用 stat 量到的源体积
             sizeBytes: tarball !== undefined ? Math.floor((tarball.base64.length * 3) / 4) : measured ?? 0,
             ...(tarball !== undefined || measured !== undefined ? { fileCount: 1 } : {}),
+            // 「按插件看」的树骨架：该插件声明的数据区域（零数据目录 I/O）
+            ...(areas !== undefined && areas.length > 0 ? { relatedAreas: areas } : {}),
         });
     }
     for (const line of data.patch) {
@@ -260,7 +325,7 @@ export class PluginsAdapter {
             section: collected,
             // 与 src/index.ts 对 JSON 分区现算体积的口径一致（utf8 字节数）
             sizeBytes: new TextEncoder().encode(stringifyJsonSafe(data)).length,
-            items: unitsOf(data, tarballBytes),
+            items: unitsOf(data, tarballBytes, relatedAreasByData.get(data)),
         };
     }
     /**
@@ -286,6 +351,9 @@ export class PluginsAdapter {
                     isBundle: p.isBundle ?? false,
                     inBundles: p.inBundles ?? [],
                     enabled: p.enabled,
+                    // issue #95：只在 dsh.profile.bundles 里声明的层（源机无依赖声明）必须带上这个标记，
+                    // 导入端据此走「只声明」而不是 npm 安装。缺省不写，普通依赖的字节与改造前逐字一致。
+                    ...(p.bundlesOnly === true ? { bundlesOnly: true } : {}),
                 });
             }
         }
@@ -401,16 +469,30 @@ export class PluginsAdapter {
             const alive = new Set(keptPlugins.map((pl) => pl.name));
             keptTarballs = localTarballs?.filter((t) => alive.has(t.packageName));
         }
+        const data = {
+            version: 1,
+            plugins: keptPlugins,
+            patch: keptPatch,
+            pnpmWorkspace: keptWorkspace,
+            ...(keptTarballs !== undefined ? { localTarballs: keptTarballs } : {}),
+            ...(keptPatchFiles !== undefined ? { patchFiles: keptPatchFiles } : {}),
+        };
+        /**
+         * 「按插件看」的树骨架（导出选择器）：登记每个插件声明的数据区域。
+         * 只登记「至少有一个区域」的插件 —— 其余插件单元保持无该字段，界面据此不显示空壳节点。
+         * 归属信息是**附加**信息：扫描失败不得影响导出/预览本身（与 pluginData 同一纪律）。
+         */
+        try {
+            const related = await relatedAreasOf(ctx);
+            if (related.size > 0)
+                relatedAreasByData.set(data, related);
+        }
+        catch {
+            // 读不到声明就不登记（界面按「没有已知关联」渲染，绝不猜）
+        }
         return {
             sectionId: 'plugins',
-            data: {
-                version: 1,
-                plugins: keptPlugins,
-                patch: keptPatch,
-                pnpmWorkspace: keptWorkspace,
-                ...(keptTarballs !== undefined ? { localTarballs: keptTarballs } : {}),
-                ...(keptPatchFiles !== undefined ? { patchFiles: keptPatchFiles } : {}),
-            },
+            data,
             counts: {
                 plugins: keptPlugins.length,
                 patchLines: keptPatch.length,
@@ -429,8 +511,9 @@ export class PluginsAdapter {
      * 由选择模型保证勾选/取消同步。
      */
     listUnits(section) {
-        // 预览产物没有 tarball 字节，体积来自 measureLocalSources 挂上的统计（导出产物走 base64 分支）
-        return unitsOf(section.data, previewTarballBytes.get(section.data));
+        // 预览产物没有 tarball 字节，体积来自 measureLocalSources 挂上的统计（导出产物走 base64 分支）；
+        // 「按插件看」的数据区域骨架同样由 collect() 登记在载荷对象上（两条路径逐字一致，units.test 钉住）
+        return unitsOf(section.data, previewTarballBytes.get(section.data), relatedAreasByData.get(section.data));
     }
     /**
      * 导入后目标机**可能**存在的 patch 文件集合（相对 profile 目录）——issue #35。
@@ -463,6 +546,83 @@ export class PluginsAdapter {
         }
         return set;
     }
+    /**
+     * 读目标机 profile 的 `dsh.profile.bundles`（issue #95）。
+     *
+     * 相对路径与写入目标同源（`profiles/<profile>/package.json`），走 `ctx.target.fs` 而不是
+     * 宿主私有通道：与 pnpm-workspace.yaml / patch 文件同一条 I/O 纪律（受限、可被 MemFs 测试）。
+     */
+    async targetBundles(ctx) {
+        const rel = `${PNPM_PROFILE_DIR(ctx.target.profile)}/package.json`;
+        try {
+            if (!(await ctx.target.fs.exists(rel)))
+                return { state: 'absent' };
+            const text = new TextDecoder().decode(await ctx.target.fs.readFile(rel));
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                return { state: 'unreadable', reason: ctx.msg('adapter.pluginHostBundleBadJson') };
+            }
+            const bundles = parsed?.dsh?.profile?.bundles;
+            if (!Array.isArray(bundles) || bundles.some((entry) => typeof entry !== 'string')) {
+                return { state: 'unreadable', reason: ctx.msg('adapter.pluginHostBundleBadShape') };
+            }
+            return { state: 'ok', names: new Set(bundles), text };
+        }
+        catch (err) {
+            return { state: 'unreadable', reason: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    /**
+     * 把 host 自带的层声明进目标机 profile 的 `dsh.profile.bundles`（issue #95）。
+     *
+     * 为什么**不走安装通道**：这类层的包由 DSH 从自己的安装位置解析；按裸包名 `dsh plugin add`
+     * 会把 npm `dist-tags.latest` 的副本装进 profile，与 host 的版本线脱节 —— 真机故障：
+     * host 0.2.1-rc.2 + 包 0.2.1-alpha.2 的隔离组契约对不上 → `session-controller` 一直 pending
+     * → 新建会话 service-unavailable。声明不了时只报非致命 warning（§34.17），不拖垮其余配置。
+     */
+    async declareHostBundle(name, ctx) {
+        const msg = ctx.msg;
+        const rel = `${PNPM_PROFILE_DIR(ctx.target.profile)}/package.json`;
+        const view = await this.targetBundles(ctx);
+        if (view.state === 'absent') {
+            return { ok: false, warning: true, message: msg('adapter.pluginHostBundleNoManifest', { name }) };
+        }
+        if (view.state === 'unreadable') {
+            return {
+                ok: false,
+                warning: true,
+                message: msg('adapter.pluginHostBundleManifestUnreadable', { name, reason: view.reason }),
+            };
+        }
+        if (view.names.has(name)) {
+            return { ok: true, needsRestart: false, message: msg('adapter.pluginHostBundleSame', { name }) };
+        }
+        const merged = mergeBundleDeclaration(view.text, name);
+        if (merged === null) {
+            return {
+                ok: false,
+                warning: true,
+                message: msg('adapter.pluginHostBundleManifestUnreadable', {
+                    name,
+                    reason: msg('adapter.pluginHostBundleBadShape'),
+                }),
+            };
+        }
+        try {
+            await ctx.target.fs.writeFile(rel, new TextEncoder().encode(merged.text));
+        }
+        catch (err) {
+            return {
+                ok: false,
+                warning: true,
+                message: msg('adapter.pluginHostBundleWriteFailed', { name, reason: err instanceof Error ? err.message : String(err) }),
+            };
+        }
+        return { ok: true, needsRestart: true, message: msg('adapter.pluginHostBundleDeclared', { name }) };
+    }
     async analyzeImport(data, ctx) {
         const msg = ctx.msg;
         const items = [];
@@ -554,8 +714,44 @@ export class PluginsAdapter {
         }
         // 插件：包名唯一键；同版本 Skip / 未装 Install / 版本不同 Conflict
         const targetInstalled = await ctx.target.plugins.listInstalled();
+        // issue #95：只在 dsh.profile.bundles 里声明的层（源机没有依赖声明）**不装 npm 包** ——
+        // 它的名字只声明进目标机的 bundles，由 DSH 从自己的安装位置解析。只在真出现这类条目时才读
+        // 目标清单（其余场景零额外 I/O，行为与改造前逐字一致）。
+        const bundleView = data.plugins.some((p) => isBundlesOnlyEntry(p)) ? await this.targetBundles(ctx) : null;
         for (const p of data.plugins) {
             const id = `plugin:${p.name}`;
+            if (isBundlesOnlyEntry(p)) {
+                if (bundleView !== null && bundleView.state === 'ok' && bundleView.names.has(p.name)) {
+                    items.push({
+                        id, kind: 'Skip', adapter: 'plugins',
+                        description: msg('adapter.pluginHostBundleSame', { name: p.name }),
+                        detail: msg('adapter.pluginHostBundleDetail'),
+                        severity: 'info',
+                    });
+                }
+                else if (bundleView !== null && bundleView.state === 'ok') {
+                    items.push({
+                        id, kind: 'Create', adapter: 'plugins',
+                        description: msg('adapter.pluginHostBundleDeclare', { name: p.name }),
+                        detail: msg('adapter.pluginHostBundleDetail'),
+                        severity: 'info',
+                        target: { adapter: 'plugins', ref: PLUGIN_PROFILE_MANIFEST_REF },
+                    });
+                }
+                else {
+                    // 清单缺 / 读不到 / 形态不符：**不猜也不重建**，如实告警（非致命，其余分区照常导入）
+                    items.push({
+                        id,
+                        kind: 'Warning',
+                        adapter: 'plugins',
+                        description: bundleView === null || bundleView.state === 'absent'
+                            ? msg('adapter.pluginHostBundleNoManifest', { name: p.name })
+                            : msg('adapter.pluginHostBundleManifestUnreadable', { name: p.name, reason: bundleView.reason }),
+                        severity: 'warning',
+                    });
+                }
+                continue;
+            }
             const tp = targetInstalled.find((t) => t.name === p.name);
             // T1：该插件在备份内自带 tarball（本地源 link:/file:）→ 目标机无需原始路径即可安装。
             const hasTarball = tarballOf(data, p.name) !== undefined;
@@ -697,10 +893,16 @@ export class PluginsAdapter {
         // 拖垮已成功导入的其余配置——与 workspaces 的「目标不可达 → warning」同款语义。
         if (item.id.startsWith('plugin:')) {
             const name = item.id.replace(/^plugin:/, '');
+            const data = ctx.sections.get('plugins');
+            // issue #95：host 自带的层（源机只在 dsh.profile.bundles 声明、没有依赖声明）走「只声明」，
+            // 绝不进 npm 安装通道（按裸包名装 = 把 dist-tag latest 的副本塞进 profile）。
+            const entry = data?.plugins.find((p) => p.name === name);
+            if (entry !== undefined && isBundlesOnlyEntry(entry)) {
+                return await this.declareHostBundle(name, ctx);
+            }
             try {
                 // 非 registry 来源（github:/file: 等）按来源 spec 安装，registry 包按裸包名装 npm 最新版
-                const data = ctx.sections.get('plugins');
-                let spec = data?.plugins.find((p) => p.name === name)?.spec;
+                let spec = entry?.spec;
                 // T1：备份内自带 tarball → 解包到 homeDir 内的本地插件缓存目录，把 spec 重写为绝对路径。
                 // 这是「换机后本地插件不再丢失」的关键：原始绝对路径在目标机不存在，解包出的 tgz 一定存在。
                 const tarball = data !== undefined ? tarballOf(data, name) : undefined;
@@ -780,6 +982,11 @@ export class PluginsAdapter {
                     if (typeof name !== 'string' || name === '') {
                         issues.push({ path: `plugins[${i}].name`, message: msg('adapter.validate.requiredField', { subject: 'plugins[].name' }), severity: 'error' });
                     }
+                    // issue #95：`bundlesOnly` 决定走不走 npm 安装通道，写错类型必须拦下（缺省合法）
+                    const bundlesOnly = p.bundlesOnly;
+                    if (bundlesOnly !== undefined && typeof bundlesOnly !== 'boolean') {
+                        issues.push({ path: `plugins[${i}].bundlesOnly`, message: msg('adapter.validate.boolean', { subject: 'plugins[].bundlesOnly' }), severity: 'error' });
+                    }
                 }
             }
             if (section.patch !== undefined && !Array.isArray(section.patch)) {