dsh-config-manager 0.1.77 → 0.1.78

package/src/adapters/plugins.ts

@@ -13,7 +13,7 @@
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { sha256Hex } from '../utils/hashing.ts';
-import { installSpecFor, resolveProcessProfileName } from '../core/plugin-cli.ts';
+import { installSpecFor, isBundlesOnlyEntry, mergeBundleDeclaration, resolveProcessProfileName } from '../core/plugin-cli.ts';
 import { classifyPluginSpec, LOCAL_PLUGIN_DIR, resolveLocalPluginPath } from '../core/local-plugin-pack.ts';
 import type { PackLocalPluginsResult } from '../core/local-plugin-pack.ts';
 import { msgOf, zhMsg } from '../core/messages.ts';
@@ -22,7 +22,7 @@ import { engineMsg } from './messages.ts';
 import { stringifyJsonSafe } from '../utils/json.ts';
 import { isPathSafe, normalizePath } from '../utils/paths.ts';
 import { isENOENT } from '../utils/guards.ts';
-import { PLUGIN_PATCH_REF_PREFIX } from '../core/backup.ts';
+import { PLUGIN_PATCH_REF_PREFIX, PLUGIN_PROFILE_MANIFEST_REF } from '../core/backup.ts';
 import { readEffectivePatchLines, resolveWriteLayer, USER_PATCH_FILE } from '../core/patch-layers.ts';
 import { parsePnpmPatchedDependencies, sanitizePnpmWorkspacePatches } from './pnpm-workspace.ts';
 import type { LocalPluginTarball, PatchLine, PluginEntry, PluginsSection, PnpmPatchFile } from '../schema/types.ts';
@@ -321,6 +321,17 @@ function unitsOf(
   return units;
 }
 
+/**
+ * 目标机 profile 的 `dsh.profile.bundles` 视图（issue #95）。
+ *
+ * 三态**必须分开**：`absent`（没有 package.json）、`unreadable`（读失败 / JSON 坏 / 形状不符）、
+ * `ok`。把后两者当成「没有」会直接去写一份清单，抹掉 profile 的其它字段。
+ */
+type TargetBundleView =
+  | { state: 'ok'; names: Set<string>; text: string }
+  | { state: 'absent' }
+  | { state: 'unreadable'; reason: string };
+
 export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
   readonly id = 'plugins' as const;
   // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
@@ -389,6 +400,9 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
           isBundle: p.isBundle ?? false,
           inBundles: p.inBundles ?? [],
           enabled: p.enabled,
+          // issue #95：只在 dsh.profile.bundles 里声明的层（源机无依赖声明）必须带上这个标记，
+          // 导入端据此走「只声明」而不是 npm 安装。缺省不写，普通依赖的字节与改造前逐字一致。
+          ...(p.bundlesOnly === true ? { bundlesOnly: true } : {}),
         });
       }
     } catch (err) {
@@ -577,6 +591,81 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
     return set;
   }
 
+  /**
+   * 读目标机 profile 的 `dsh.profile.bundles`（issue #95）。
+   *
+   * 相对路径与写入目标同源（`profiles/<profile>/package.json`），走 `ctx.target.fs` 而不是
+   * 宿主私有通道：与 pnpm-workspace.yaml / patch 文件同一条 I/O 纪律（受限、可被 MemFs 测试）。
+   */
+  private async targetBundles(ctx: ImportContext): Promise<TargetBundleView> {
+    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: unknown;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        return { state: 'unreadable', reason: ctx.msg('adapter.pluginHostBundleBadJson') };
+      }
+      const bundles = (parsed as { dsh?: { profile?: { bundles?: unknown } } } | null)?.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 as string[]), 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），不拖垮其余配置。
+   */
+  private async declareHostBundle(name: string, ctx: ImportContext): Promise<ApplyResult> {
+    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: PluginsSection, ctx: ImportContext): Promise<PlanItem[]> {
     const msg = ctx.msg;
     const items: PlanItem[] = [];
@@ -667,8 +756,42 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
 
     // 插件：包名唯一键；同版本 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;
@@ -802,10 +925,16 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
     // 拖垮已成功导入的其余配置——与 workspaces 的「目标不可达 → warning」同款语义。
     if (item.id.startsWith('plugin:')) {
       const name = item.id.replace(/^plugin:/, '');
+      const data = ctx.sections.get('plugins') as PluginsSection | undefined;
+      // 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') as PluginsSection | undefined;
-        let spec = data?.plugins.find((p) => p.name === name)?.spec;
+        let spec = entry?.spec;
 
         // T1：备份内自带 tarball → 解包到 homeDir 内的本地插件缓存目录，把 spec 重写为绝对路径。
         // 这是「换机后本地插件不再丢失」的关键：原始绝对路径在目标机不存在，解包出的 tgz 一定存在。
@@ -881,6 +1010,11 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
           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 as { bundlesOnly?: unknown }).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)) {

package/src/core/analyzer.ts

@@ -1806,9 +1806,11 @@ function applyTombstoneFilter(
 /** PlanItem → 墓碑键（{kind,id}）映射；非「将写入」的条目（Skip 等）与配置类项返回 null 不过滤 */
 function tombstoneKeyForItem(item: PlanItem): { kind: TombstoneKind; id: string } | null {
   // 插件本体（plugin:<pkg>）：Install / Update / Conflict 均视为「将写入该插件」→ 命中墓碑剔除；
+  // issue #95 的 Create = 「把 host 自带的层声明进 dsh.profile.bundles」，同样是写入该插件，
+  // 必须一起被墓碑剔除（用户删过的插件不得被一份旧备份重新声明回来）。
   // patch: 行与 plugins:pnpm-workspace 是配置类项，不按插件墓碑过滤（分区级墓碑可覆盖）。
   if (item.adapter === 'plugins' && item.id.startsWith('plugin:')) {
-    if (item.kind !== 'Install' && item.kind !== 'Update' && item.kind !== 'Conflict') return null;
+    if (item.kind !== 'Install' && item.kind !== 'Update' && item.kind !== 'Conflict' && item.kind !== 'Create') return null;
     return { kind: 'plugin', id: item.id.slice('plugin:'.length) };
   }
   // 文件类分区条目（id = <分区>:<相对路径>）：skills → skill 墓碑；其余文件类（agentPresets/

package/src/core/backup.ts

@@ -164,6 +164,16 @@ for (const id of SECTION_IDS) {
  */
 export const PLUGIN_PATCH_REF_PREFIX = 'patchFile:'
 
+/**
+ * plugins 分区中「profile 的 package.json」这一文件目标的 ref（issue #95）。
+ *
+ * 声明 host 自带的 bundle 层（`dsh.profile.bundles`）就是写这个文件，因此它必须与
+ * `pnpm-workspace.yaml` 同级：进导入前快照 → 回滚能整文件还原，否则一次导入留下的声明
+ * 撤不掉（照抄 \`patchFile:\` 的做法，用一个符号 ref 而不是真实文件名——ref 空间里还有
+ * 任意 patch 行 id，靠形状判断会撞车）。
+ */
+export const PLUGIN_PROFILE_MANIFEST_REF = 'profileManifest'
+
 /** profile 目录绝对路径（plugins 分区内文件类目标的基准） */
 function profileDirOf(ctx: HostContext): string {
   const profile = ctx.profile !== undefined && ctx.profile !== '' ? ctx.profile : 'web';
@@ -216,6 +226,10 @@ export function resolveFileTarget(ctx: HostContext, adapter: SectionId, ref: str
   if (adapter === 'plugins' && ref.startsWith(PLUGIN_PATCH_REF_PREFIX)) {
     return path.join(profileDirOf(ctx), ref.slice(PLUGIN_PATCH_REF_PREFIX.length));
   }
+  // issue #95：声明 host 自带 bundle 层 = 写 profile 的 package.json（快照/回滚必须覆盖它）
+  if (adapter === 'plugins' && ref === PLUGIN_PROFILE_MANIFEST_REF) {
+    return path.join(profileDirOf(ctx), 'package.json');
+  }
   const base = FILE_BASES[adapter] ?? '';
   return path.join(ctx.homeDir, base, ref);
 }
@@ -236,6 +250,7 @@ export function resolveFileTargetRel(adapter: SectionId, ref: string, profile?:
   if (adapter === 'plugins') {
     const profileDir = `profiles/${profile !== undefined && profile !== '' ? profile : 'web'}`;
     if (ref === 'pnpm-workspace.yaml') return normalizePath(`${profileDir}/pnpm-workspace.yaml`);
+    if (ref === PLUGIN_PROFILE_MANIFEST_REF) return normalizePath(`${profileDir}/package.json`);
     if (ref.startsWith(PLUGIN_PATCH_REF_PREFIX)) {
       return normalizePath(`${profileDir}/${ref.slice(PLUGIN_PATCH_REF_PREFIX.length)}`);
     }
@@ -316,7 +331,7 @@ async function engineSnapshotEntry(ctx: HostContext, target: SnapshotTarget): Pr
     case 'plugins':
     case 'prompts': {
       // plugins 分区的 pnpm-workspace.yaml / patch 文件 → 整文件快照（file 类，回滚可整文件还原）
-      if (target.adapter === 'plugins' && (target.ref === 'pnpm-workspace.yaml' || target.ref.startsWith(PLUGIN_PATCH_REF_PREFIX))) {
+      if (target.adapter === 'plugins' && (target.ref === 'pnpm-workspace.yaml' || target.ref === PLUGIN_PROFILE_MANIFEST_REF || target.ref.startsWith(PLUGIN_PATCH_REF_PREFIX))) {
         const abs = resolveFileTarget(ctx, target.adapter, target.ref);
         if (!(await ctx.fs.exists(abs))) {
           return { kind: 'file', adapter: target.adapter, ref: target.ref, before: null, existed: false };

package/src/core/messages.ts

@@ -265,6 +265,15 @@ export const zh = {
   'adapter.pluginInstallOk': '插件 {name} 已安装{suffix}',
   'adapter.pluginUpdateTriggered': '插件 {name} 已触发更新（npm 最新版）{suffix}',
   'adapter.pluginRestartSuffix': '，重启 dsh 后生效',
+  'adapter.pluginHostBundleDeclare': '声明插件层 {name}（由 DSH 自带提供，不安装）',
+  'adapter.pluginHostBundleSame': '插件层 {name} 已在目标机声明（由 DSH 自带提供）',
+  'adapter.pluginHostBundleDeclared': '已声明插件层 {name}，重启 dsh 后生效',
+  'adapter.pluginHostBundleDetail': '该层在源机只出现在 dsh.profile.bundles、dependencies 里没有它，由 DSH 从自己的安装位置解析；导入只声明，不装 npm 版本',
+  'adapter.pluginHostBundleNoManifest': '无法声明插件层 {name}：目标机 profile 缺少 package.json',
+  'adapter.pluginHostBundleManifestUnreadable': '无法声明插件层 {name}：profile 清单读不到或形态不符（{reason}）',
+  'adapter.pluginHostBundleWriteFailed': '声明插件层 {name} 失败：{reason}',
+  'adapter.pluginHostBundleBadJson': 'package.json 不是合法 JSON',
+  'adapter.pluginHostBundleBadShape': 'dsh.profile.bundles 不是字符串数组',
   'adapter.pwMissing': '导入数据缺少 pnpm-workspace.yaml 内容',
   'adapter.pluginInstallFailed': '插件 {name} 安装失败：{msg}。可手动安装：dsh plugin --profile {profile} add {name}（其余配置已导入；可修复依赖后在设置页重试或手动安装）',
   'adapter.pluginUpdateFailed': '插件 {name} 更新失败：{msg}。可手动安装：dsh plugin --profile {profile} add {name}（其余配置已导入；可修复依赖后在设置页重试或手动安装）',
@@ -340,6 +349,7 @@ export const zh = {
   'adapter.validate.requiredField': '缺少 {subject}',
   'adapter.validate.sourceNamespace': '缺少来源 namespace',
   'adapter.validate.number': '{subject} 必须是数字',
+  'adapter.validate.boolean': '{subject} 必须是布尔值',
   'adapter.validate.nonEmptyRef': '{subject} 记录必须含非空 ref',
   'adapter.validate.credentialRef': '凭据记录必须含非空 ref',
   'adapter.validate.fileRelativePath': '文件记录必须含非空 relativePath',
@@ -715,6 +725,15 @@ export const en: Record<keyof typeof zh, string> = {
   'adapter.pluginInstallOk': 'Plugin {name} installed{suffix}',
   'adapter.pluginUpdateTriggered': 'Plugin {name} update triggered (npm latest){suffix}',
   'adapter.pluginRestartSuffix': '; takes effect after restarting dsh',
+  'adapter.pluginHostBundleDeclare': 'Declare plugin layer {name} (provided by DSH itself; not installed)',
+  'adapter.pluginHostBundleSame': 'Plugin layer {name} is already declared on the target (provided by DSH itself)',
+  'adapter.pluginHostBundleDeclared': 'Plugin layer {name} declared; takes effect after restarting dsh',
+  'adapter.pluginHostBundleDetail': 'On the source this layer only appears in dsh.profile.bundles (no dependency declaration) and is resolved by DSH from its own installation; the import only declares it and installs no npm version',
+  'adapter.pluginHostBundleNoManifest': 'Cannot declare plugin layer {name}: the target profile has no package.json',
+  'adapter.pluginHostBundleManifestUnreadable': 'Cannot declare plugin layer {name}: the profile manifest is unreadable or has an unexpected shape ({reason})',
+  'adapter.pluginHostBundleWriteFailed': 'Failed to declare plugin layer {name}: {reason}',
+  'adapter.pluginHostBundleBadJson': 'package.json is not valid JSON',
+  'adapter.pluginHostBundleBadShape': 'dsh.profile.bundles is not an array of strings',
   'adapter.pwMissing': 'Import data is missing pnpm-workspace.yaml content',
   'adapter.pluginInstallFailed': 'Plugin {name} install failed: {msg}. You can install it manually: dsh plugin --profile {profile} add {name} (the rest of the config was imported; fix dependencies and retry from the settings page, or install by hand)',
   'adapter.pluginUpdateFailed': 'Plugin {name} update failed: {msg}. You can install it manually: dsh plugin --profile {profile} add {name} (the rest of the config was imported; fix dependencies and retry from the settings page, or install by hand)',
@@ -790,6 +809,7 @@ export const en: Record<keyof typeof zh, string> = {
   'adapter.validate.requiredField': 'Missing {subject}',
   'adapter.validate.sourceNamespace': 'Missing source namespace',
   'adapter.validate.number': '{subject} must be a number',
+  'adapter.validate.boolean': '{subject} must be a boolean',
   'adapter.validate.nonEmptyRef': '{subject} records must have a non-empty ref',
   'adapter.validate.credentialRef': 'Credential records must have a non-empty ref',
   'adapter.validate.fileRelativePath': 'File records must have a non-empty relativePath',

package/src/core/plugin-cli.fs.test.ts

@@ -13,8 +13,8 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import {
-  listInstalledPlugins, readInstalled, readInstalledVersion, reconcileBundles,
-  resolveProfileDir,
+  isBundlesOnlyEntry, listInstalledPlugins, mergeBundleDeclaration, readInstalled, readInstalledVersion,
+  reconcileBundles, resolveProfileDir,
 } from './plugin-cli.ts';
 import { enterRescueMode } from './boot-rescue.ts';
 import type { PluginInfo } from './types.ts';
@@ -146,7 +146,9 @@ test('issue #28: 仅由 dsh.profile.bundles 声明的层必须出现在已装清
     assert.equal(bundleOnly?.version, '0.3.1', '版本取 node_modules 落盘版本');
     assert.equal(bundleOnly?.isBundle, true);
     assert.deepEqual(bundleOnly?.inBundles, ['@linxin666/dsh-web-ui-all']);
-    assert.equal(bundleOnly?.spec, undefined, '无依赖声明 → 无 spec（导入按裸包名装最新版）');
+    assert.equal(bundleOnly?.spec, undefined, '无依赖声明 → 无 spec');
+    // issue #95：本机**有**落盘副本的手工层不是「host 自带层」，标记不得出现（保持安装通道行为）
+    assert.equal(bundleOnly?.bundlesOnly, undefined, '本机有副本 → 不标记 bundlesOnly');
     // 从未落盘的 bundles 条目：仍列出（它确实是启动时会挂载的层），版本空串不抛
     assert.equal(list.find((p) => p.name === 'stale-pkg')?.version, '');
     // in-box bundle 依然不出现（无论来自 dependencies 还是 bundles）
@@ -234,3 +236,63 @@ test('reconcileBundles：救援模式下必须停手（不得把收窄掉的用
     cleanup();
   }
 });
+
+test('issue #95: 只在 bundles 里声明、且本机没有落盘副本的层必须标记 bundlesOnly', () => {
+  const { homeDir, profileDir, cleanup } = makeTempProfile(
+    { 'pkg-a': '1.0.0' },
+    ['@deepseek-ai/dsh-experimental-session-search', '@linxin666/dsh-web-ui-all'],
+  );
+  try {
+    writeInstalledPkg(profileDir, 'pkg-a', '1.0.0');
+    writeInstalledPkg(profileDir, '@linxin666/dsh-web-ui-all', '0.3.1', 'patch.yml');
+
+    const list = listInstalledPlugins(homeDir, 'web');
+    const hostLayer = list.find((p) => p.name === '@deepseek-ai/dsh-experimental-session-search');
+    assert.equal(hostLayer?.version, '', '本 profile 没装它 → 版本空串');
+    assert.equal(hostLayer?.bundlesOnly, true, '无依赖 + 无落盘副本 ⇒ 只能由 DSH 自己提供');
+    assert.equal(list.find((p) => p.name === '@linxin666/dsh-web-ui-all')?.bundlesOnly, undefined, '有落盘副本 → 保持旧行为');
+    assert.equal(list.find((p) => p.name === 'pkg-a')?.bundlesOnly, undefined, '普通依赖不得带标记');
+  } finally {
+    cleanup();
+  }
+});
+
+test('issue #95: isBundlesOnlyEntry —— 显式字段优先，旧备份按形状推断', () => {
+  assert.equal(isBundlesOnlyEntry({ bundlesOnly: true, spec: '^1.0.0', version: '1.0.0' }), true, '显式字段优先');
+  assert.equal(isBundlesOnlyEntry({ bundlesOnly: false, version: '' }), false, '显式 false 不得被形状覆盖');
+  assert.equal(isBundlesOnlyEntry({ version: '' }), true, '旧备份：无 spec 且无已装版本');
+  assert.equal(isBundlesOnlyEntry({ spec: '^1.0.0', version: '' }), false, '有依赖声明 → 普通依赖（哪怕本机没装全）');
+  assert.equal(isBundlesOnlyEntry({ version: '0.3.1' }), false, '本机有落盘副本 → 手工层');
+});
+
+test('issue #95: mergeBundleDeclaration 只追加一个名字；形状不符一律拒绝', () => {
+  const base = `${JSON.stringify({ name: 'dsh-profile-web', dependencies: { a: '1.0.0' }, dsh: { profile: { bundles: ['x'] } } }, null, 2)}\n`;
+  const merged = mergeBundleDeclaration(base, 'y');
+  assert.equal(merged?.changed, true);
+  const parsed = JSON.parse(merged!.text) as {
+    dependencies: Record<string, string>;
+    dsh: { profile: { bundles: string[] } };
+  };
+  assert.deepEqual(parsed.dsh.profile.bundles, ['x', 'y'], '名字追加在尾部');
+  assert.deepEqual(parsed.dependencies, { a: '1.0.0' }, '其余字段逐字保留');
+  assert.equal(mergeBundleDeclaration(merged!.text, 'y')?.changed, false, '幂等：重复声明不空写');
+
+  assert.equal(mergeBundleDeclaration('{', 'y'), null, 'JSON 坏 → null（绝不重建清单）');
+  assert.equal(mergeBundleDeclaration('[]', 'y'), null, '顶层非对象 → null');
+  assert.equal(mergeBundleDeclaration(JSON.stringify({ name: 'p' }), 'y'), null, '缺 dsh.profile → null');
+  assert.equal(
+    mergeBundleDeclaration(JSON.stringify({ dsh: { profile: { bundles: 'x' } } }), 'y'),
+    null,
+    'bundles 非数组 → null',
+  );
+  assert.equal(
+    mergeBundleDeclaration(JSON.stringify({ dsh: { profile: { bundles: ['x', 1] } } }), 'y'),
+    null,
+    'bundles 含非字符串 → null',
+  );
+  assert.equal(
+    mergeBundleDeclaration(JSON.stringify({ dsh: { profile: {} } }), 'y'),
+    null,
+    'bundles 字段缺省 → null（非空 bundles 会替换默认插件栈，绝不凭空造）',
+  );
+});

package/src/core/plugin-cli.ts

@@ -340,19 +340,72 @@ export function listInstalledPlugins(homeDir: string, profile: string): PluginIn
   for (const name of Array.isArray(declaredBundles) ? declaredBundles : []) {
     if (INBOX_BUNDLES.has(name)) continue
     if (Object.prototype.hasOwnProperty.call(installed, name)) continue // 已在依赖清单里
+    const installedVersion = readInstalledVersion(dir, name) ?? ''
     out.push({
       name,
-      version: readInstalledVersion(dir, name) ?? '',
+      version: installedVersion,
       enabled: true,
       isBundle: true,
       // 直接声明的层自己就是 profile 层
       inBundles: [name],
-      // 无依赖声明 → 无 spec：导入时按裸包名安装（与 registry 依赖同语义）
+      // issue #95：无依赖声明 + **本 profile 也没有它的落盘副本** ⇒ 这个包只可能由 DSH 从自己的
+      // 安装位置解析。导入端只能把它声明进目标机的 bundles，绝不按裸包名走 npm（那会把
+      // dist-tag latest 的副本装进 profile，与 host 版本线脱节）。
+      // 本地**有**落盘副本的手工层不在此列：那种层得靠安装通道才能在目标机上存在，保持旧行为。
+      ...(installedVersion === '' ? { bundlesOnly: true } : {}),
     })
   }
   return out
 }
 
+/**
+ * 「只在 `dsh.profile.bundles` 里声明、`dependencies` 里没有该包」的条目判定（issue #95）。
+ *
+ * 为什么要一个共享判据：导出端的显式字段（`bundlesOnly`）只存在于新备份；旧备份只能按形状
+ * 推断——**有依赖 spec 的绝不是**（那是普通依赖，哪怕本机没装全）；**没有 spec 且读不到已装版本**
+ * 的才是（本 profile 里没有任何东西提供它，DSH 只能从自己的安装位置解析，issue #95）。
+ */
+export function isBundlesOnlyEntry(entry: { bundlesOnly?: unknown; spec?: unknown; version?: unknown }): boolean {
+  if (entry.bundlesOnly === true) return true
+  if (entry.bundlesOnly !== undefined) return false
+  const spec = typeof entry.spec === 'string' ? entry.spec : ''
+  const version = typeof entry.version === 'string' ? entry.version : ''
+  return spec === '' && version === ''
+}
+
+/**
+ * 把 `name` 声明进 profile package.json 的 `dsh.profile.bundles`（issue #95）。
+ *
+ * 只做「追加一个名字」：其余字段逐字保留，重复声明返回 `changed: false`（幂等，不空写文件）。
+ * 形状不可认（JSON 坏 / `dsh.profile` 非对象 / `bundles` 非字符串数组）→ 返回 null：
+ * 调用方必须**如实报告**并放弃这次声明，绝不重建一份清单出来（那会抹掉 profile 的其它字段）。
+ *
+ * `bundles` 字段**缺省也拒绝**：DSH 的语义是「bundles 非空即替换默认插件栈」，凭空造一个只含
+ * 一个名字的数组 = 悄悄改掉目标机的装配语义（应当由 DSH 自己写这个字段）。
+ */
+export function mergeBundleDeclaration(pkgText: string, name: string): { text: string; changed: boolean } | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(pkgText)
+  } catch {
+    return null
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+  const pkg = parsed as Record<string, unknown>
+  const dsh = pkg.dsh
+  if (dsh === null || typeof dsh !== 'object' || Array.isArray(dsh)) return null
+  const profile = (dsh as Record<string, unknown>).profile
+  if (profile === null || typeof profile !== 'object' || Array.isArray(profile)) return null
+  const raw = (profile as Record<string, unknown>).bundles
+  if (raw === undefined) return null
+  if (!Array.isArray(raw) || raw.some((entry) => typeof entry !== 'string')) return null
+  const bundles = raw as string[]
+  if (bundles.includes(name)) return { text: pkgText, changed: false }
+  bundles.push(name)
+  ;(profile as Record<string, unknown>).bundles = bundles
+  return { text: `${JSON.stringify(pkg, null, 2)}\n`, changed: true }
+}
+
 /* --------------------------------------------------------------- CLI 通道 */
 
 /** 15 分钟默认上限（慢网络 + git 安装），可用环境变量覆盖（CI/测试）。 */

package/src/core/types.ts

@@ -234,6 +234,16 @@ export interface PluginInfo {
   inBundles?: string[];
   /** 声明依赖 spec（profile package.json dependencies 原样）；文件视图来自 readInstalled */
   spec?: string;
+  /**
+   * 只在 `dsh.profile.bundles` 里声明、`dependencies` 里没有该包，且本 profile 的
+   * `node_modules` 里也没有它的落盘副本（issue #95）。
+   *
+   * DSH 对这类层从**自己的安装位置**解析（`boot-safety.ts` 的「@deepseek-ai/* 由 DSH 从它自己的
+   * 安装位置解析」与 `RESCUE_KEEP_BUNDLE_PREFIXES` 同一口径），因此导入端**不得**把它当
+   * registry 依赖去 `dsh plugin add`：那会把 npm dist-tag `latest` 的副本装进目标 profile，
+   * 与 host 的版本线脱节（issue #95 的真机故障）。只能把名字声明进目标机的 bundles。
+   */
+  bundlesOnly?: boolean;
 }
 
 export interface PluginsFacade {

package/src/index.ts

@@ -181,7 +181,7 @@ export const name = 'config-manager'
 export const inject = ['settings', 'credentials']
 
 /** Plugin version, kept in sync with package.json ("version"). */
-export const PLUGIN_VERSION = '0.1.77'
+export const PLUGIN_VERSION = '0.1.78'
 
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager'

package/src/schema/types.ts

@@ -113,6 +113,20 @@ export interface PluginEntry {
    * 否则按裸包名走 npm 最新版（官方机制）。
    */
   spec?: string;
+  /**
+   * 该层只在 profile 的 `dsh.profile.bundles` 里声明、`dependencies` 里没有它，且该 profile 的
+   * `node_modules` 里也**没有**它的落盘副本（issue #95，导出侧写入）。
+   *
+   * 语义：这不是一个「装在本 profile 里的包」，而是由 DSH 从**自己的安装位置**解析的层
+   * （与 `boot-safety.ts` / `RESCUE_KEEP_BUNDLE_PREFIXES` 同口径）。导入端对这类条目
+   * **只把名字声明进目标机的 `dsh.profile.bundles`，绝不走 npm 安装通道**——按裸包名安装会让
+   * 目标机拿到 `dist-tags.latest` 的副本（2026-10 真机：host 0.2.1-rc.2 + 包 0.2.1-alpha.2
+   * → session-controller 一直 pending → 新建会话 service-unavailable）。
+   *
+   * 缺省（旧备份没有该字段）= 由 `spec` / `version` 形状推断，见
+   * `src/core/plugin-cli.ts` 的 `isBundlesOnlyEntry`。
+   */
+  bundlesOnly?: boolean;
   isBundle: boolean;
   inBundles: string[];
   enabled: boolean;