dsh-plugin 2.1.0 → 2.2.0

package/lib/http/diagnostics.js

@@ -5,75 +5,14 @@
  *
  * 诊断路由：流式连通性自检、代理校验，以及与任务模块 /env 路由共享的宿主环境快照。
  */
-import { readFileSync } from 'node:fs';
 import { homedir, release } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { loadSettings } from '../services/settings.js';
+import { hostDshVersion, toolVersion } from '../services/host-version.js';
 import { gitLsRemote, probeUrl, systemProxy } from '../services/probe.js';
 import { appendLog } from '../services/log.js';
 import { readJsonBody, requireTrustedPost, sendJson } from './shared.js';
-/** 宿主 dsh CLI 版本：优先直接跑 `dsh --version`（与 pnpm/npm/git 同款同步探测，1500ms 超时兜底，
- *  绝不挂起）；拿不到再退回从入口 `process.argv[1]` 向上找 package.json（dsh 不在 PATH 时兜底）。 */
-function hostDshVersion() {
-    const viaCli = toolVersion('dsh', ['--version']);
-    if (viaCli)
-        return viaCli;
-    const entry = process.argv[1];
-    if (entry === undefined)
-        return null;
-    let dir = dirname(resolve(entry));
-    for (let depth = 0; depth < 4; depth++) {
-        try {
-            const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
-            const name = manifest.name ?? '';
-            if (typeof manifest.version === 'string' && (name === 'dsh' || name.includes('dsh') || name.includes('harness'))) {
-                return manifest.version;
-            }
-        }
-        catch {
-            /* 不是包根，继续向上查找 */
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return null;
-}
-/** 从命令输出里抽出版本号本体：pnpm/npm 直接打印 `11.7.0`，而 `git --version` 打印
- *  `git version 2.55.0.windows.5` —— 原样取首行会让 issue 正文（统一再加 `v` 前缀）拼成
- *  `vgit version 2.55.0.windows.5`。只取版本号，顺带兼容 `v1.2.3` 这类自带前缀的输出。 */
-function versionOf(output) {
-    const first = output.trim().split(/\r?\n/)[0]?.trim() ?? '';
-    if (!first)
-        return null;
-    const match = /\d+\.\d+[0-9A-Za-z.\-+]*/.exec(first);
-    return match === null ? null : match[0];
-}
-/** 探测命令行工具的版本号（pnpm --version / npm --version / git --version）：
- *  未安装 / 不在 PATH / 超时一律返回 null —— issue 环境快照如实写 unknown，绝不挂起。
- *  （同步探测仅用于启动期/请求期的低频率 /env 快照，安装通道不经过这里。）
- *
- *  Windows 上 pnpm/npm 是 .cmd shim，不带 shell 的 spawnSync 起不来 —— 上报的 issue 里
- *  因此长期是 `pnpm: unknown` / `npm: unknown`，而 pnpm 版本恰恰是 allowBuilds 那类问题的
- *  关键信息（门禁行为随版本变）。故 win32 走 shell 让 cmd 解析 shim；参数是固定的
- *  `--version`，没有注入面。 */
-function toolVersion(cmd, args) {
-    try {
-        const r = spawnSync(cmd, args, {
-            timeout: 1500,
-            encoding: 'utf8',
-            shell: process.platform === 'win32',
-        });
-        if (r.error || r.status !== 0)
-            return null;
-        return versionOf(r.stdout ?? '');
-    }
-    catch {
-        return null;
-    }
-}
 /** 本机实际生效的 npm registry：诊断与安装同口径 —— 设置里留空时读用户 npm 配置
  *  （含 profile 目录的 .npmrc），而不是硬探官方源，避免「能装但诊断说源不通」。
  *  读不到（npm 缺失/超时/输出异常）时回退官方源。 */

package/lib/services/host-version.js

@@ -0,0 +1,72 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 宿主与命令行工具的版本探测：dsh 版本同时用于诊断快照和「插件要求更高 DSH」判定，
+ * pnpm/npm/git 只用于诊断快照。同步探测 + 1500ms 超时兜底，拿不到一律 null，绝不挂起。
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+/** 从命令输出里抽出版本号本体：pnpm/npm 直接打印 `11.7.0`，而 `git --version` 打印
+ *  `git version 2.55.0.windows.5` —— 原样取首行会让 issue 正文拼成 `vgit version …`。
+ *  只取版本号，顺带兼容 `v1.2.3` 这类自带前缀的输出。 */
+export function versionOf(output) {
+    const first = output.trim().split(/\r?\n/)[0]?.trim() ?? '';
+    if (!first)
+        return null;
+    const match = /\d+\.\d+[0-9A-Za-z.\-+]*/.exec(first);
+    return match === null ? null : match[0];
+}
+/** 探测命令行工具版本：未安装 / 不在 PATH / 超时一律 null。
+ *  Windows 上 pnpm/npm 是 .cmd shim，不走 shell 起不来；参数是固定的 `--version`，没有注入面。 */
+export function toolVersion(cmd, args) {
+    try {
+        const r = spawnSync(cmd, args, {
+            timeout: 1500,
+            encoding: 'utf8',
+            shell: process.platform === 'win32',
+        });
+        if (r.error || r.status !== 0)
+            return null;
+        return versionOf(r.stdout ?? '');
+    }
+    catch {
+        return null;
+    }
+}
+let cachedDshVersion = null;
+/** 宿主 dsh 版本：优先 `dsh --version`；拿不到再从入口 `process.argv[1]` 向上找 package.json
+ *  （dsh 不在 PATH 时兜底）。探测成功即缓存，失败不缓存以便下次重试。 */
+export function hostDshVersion() {
+    if (cachedDshVersion !== null)
+        return cachedDshVersion;
+    const viaCli = toolVersion('dsh', ['--version']);
+    if (viaCli !== null) {
+        cachedDshVersion = viaCli;
+        return viaCli;
+    }
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return null;
+    let dir = dirname(resolve(entry));
+    for (let depth = 0; depth < 4; depth++) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            const name = manifest.name ?? '';
+            if (typeof manifest.version === 'string' && (name === 'dsh' || name.includes('dsh') || name.includes('harness'))) {
+                cachedDshVersion = manifest.version;
+                return cachedDshVersion;
+            }
+        }
+        catch {
+            /* 不是包根，继续向上查找 */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}

package/lib/services/install/dsh-compat.js

@@ -0,0 +1,105 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 「插件要求的 DSH 版本高于当前宿主」判定：安装失败后读一次 npm 元数据，取
+ * peerDependencies（@deepseek-ai/dsh-*）与 engines.dsh 声明的最低版本里最高的那个，
+ * 与宿主版本比较；宿主更低就产出 [dsh-too-old] 标记 —— 前端据此提示「先升级 DSH」，
+ * 不再把这类失败归成「未分类」丢给用户或插件作者。
+ *
+ * 只在失败路径调用：peer 不满足本身通常只是警告，成功安装时不该出现这个提示；
+ * 任何网络/解析异常都静默返回 null，不改变原有失败处理。
+ */
+import { hostDshVersion } from '../host-version.js';
+/** 从安装目标里取 npm 包名：`@scope/pkg@1.2.3` → `@scope/pkg`。
+ *  git / URL / 本地路径等非 npm 目标返回 null。 */
+export function npmNameOf(target) {
+    const raw = target.trim();
+    if (raw === '')
+        return null;
+    if (/^(?:github:|git\+|https?:|file:|link:|\.{0,2}[\\/])/i.test(raw))
+        return null;
+    // owner/repo（非 scope）：git 目标的另一种写法，不是包名
+    if (!raw.startsWith('@') && /^[^\s@]+\/[^\s]+$/.test(raw))
+        return null;
+    const at = raw.lastIndexOf('@');
+    const name = at > 0 ? raw.slice(0, at) : raw;
+    return /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(name) ? name : null;
+}
+/** `0.2.1-rc.1` / `^0.2.1` / `>=0.2.0 <0.3.0` → [0,2,1]；解析不出返回 null。
+ *  只取版本三段：DSH 的 prerelease 序号（rc.1）不参与「太低」判断，避免比较误差。 */
+export function versionTriple(raw) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(raw);
+    return m === null ? null : [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function compareTriple(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    }
+    return 0;
+}
+/** 插件声明的最低 DSH 版本：engines.dsh 与 peerDependencies 里 @deepseek-ai/dsh-* 的下限取最大。
+ *  返回原始声明文本（如 `^0.2.1-rc.1`）供提示直接展示；没有声明返回 null。 */
+export function dshFloorOf(manifest) {
+    const m = manifest;
+    const ranges = [];
+    const engineDsh = m?.engines?.dsh;
+    if (typeof engineDsh === 'string')
+        ranges.push(engineDsh);
+    for (const [name, range] of Object.entries(m?.peerDependencies ?? {})) {
+        if (/^@deepseek-ai\/dsh(?:-|$)/.test(name) && typeof range === 'string')
+            ranges.push(range);
+    }
+    let floor = null;
+    let floorTriple = null;
+    for (const range of ranges) {
+        const triple = versionTriple(range);
+        if (triple === null)
+            continue;
+        if (floorTriple === null || compareTriple(triple, floorTriple) > 0) {
+            floor = range;
+            floorTriple = triple;
+        }
+    }
+    return floor;
+}
+/**
+ * 产出「插件要求更高的 DSH」标记行；没有声明、读不到元数据、宿主版本未知或已满足时返回 null。
+ * 用版本级 manifest（`/<pkg>/latest`）：packument 的精简形态不带 peerDependencies。
+ */
+export async function dshTooOldMarker(target, opts = {}) {
+    const name = npmNameOf(target);
+    if (name === null)
+        return null;
+    const current = opts.currentVersion ?? hostDshVersion();
+    if (current === null)
+        return null;
+    const currentTriple = versionTriple(current);
+    if (currentTriple === null)
+        return null;
+    const base = (opts.registry ?? 'https://registry.npmjs.org').replace(/\/+$/, '');
+    // scope 包的路径要编码：`@scope/name` → `%40scope%2Fname`
+    const url = `${base}/${name.replace('@', '%40').replace('/', '%2F')}/latest`;
+    let manifest;
+    try {
+        const res = await (opts.fetchImpl ?? fetch)(url, {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 4000),
+        });
+        if (!res.ok)
+            return null;
+        manifest = await res.json();
+    }
+    catch {
+        return null;
+    }
+    const floor = dshFloorOf(manifest);
+    const floorTriple = floor === null ? null : versionTriple(floor);
+    if (floor === null || floorTriple === null)
+        return null;
+    if (compareTriple(currentTriple, floorTriple) >= 0)
+        return null;
+    return `[dsh-too-old] ${name} requires DSH >= ${floor} (declared in engines / peerDependencies), but this host runs ${current} — upgrade DSH before installing`;
+}

package/lib/services/install/task-queue.js

@@ -22,6 +22,7 @@ import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, p
 import { appendLog } from '../log.js';
 import { commandOnPath, gitMissingDetail } from './preflight.js';
 import { isTransportFailure, registryHost } from './registry-fallback.js';
+import { dshTooOldMarker } from './dsh-compat.js';
 import { OutputDecoder } from './decode-output.js';
 /** 内存任务注册表，按任务 id 索引。 */
 const tasks = new Map();
@@ -365,6 +366,12 @@ function spawnMutation(options) {
     const invocation = isGlobalNpm
         ? { file: 'npm', prefixArgs: [], cwd: process.cwd(), useShell: process.platform === 'win32' }
         : cliInvocation(profile);
+    // 打包桌面端却回退到 PATH 上的 dsh：说明 desktop CLI 引导路径没命中，desktop profile 必被宿主拒绝。
+    // 留一行 ASCII 标记，后续同类上报可直接区分「用户自起 CLI」与「我们没走对引导路径」。
+    if (task && task.status !== 'cancelled' && invocation.file === 'dsh'
+        && process.versions.electron !== undefined) {
+        pushLine(task, '[desktop-cli-fallback] running inside Electron but no desktop CLI bootstrap was found — falling back to dsh on PATH (a desktop-managed profile will be rejected)');
+    }
     // 更新已安装的 npm 包：显式指定 @latest。pnpm add <pkg>（无版本）对已存在依赖
     // （尤其精确 spec 如 "1.3.0"）是幂等的 —— 输出 "Already up to date" 且不改 package.json，
     // 导致「更新成功」但实际仍停留在旧版本；git 地址与全局安装不受此影响。
@@ -746,6 +753,23 @@ async function annotateRegistryMissing(result, options) {
         pushLine(options.task, line);
     return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
 }
+/** 安装失败且插件声明的最低 DSH 版本高于当前宿主 → 注入 [dsh-too-old] 标记。
+ *  只在失败路径上发生：peer 不满足本身通常只是警告，装成功时不该冒这个提示。
+ *  超时也算失败 —— 旧宿主上插件可能卡在半兼容状态，这个信息同样有用。 */
+async function annotateDshTooOld(result, options) {
+    if (options.action === 'remove' || result.exitCode === 0)
+        return result;
+    // 全局 npm 装的是本机 CLI 工具，不进 profile，没有宿主版本要求
+    if ((options.globalNpm ?? []).length > 0)
+        return result;
+    // 用安装实际使用的源读元数据：私有源/镜像里也能读到同一个包的声明
+    const line = await dshTooOldMarker(options.target, { registry: options.registries?.[0] });
+    if (line === null)
+        return result;
+    if (options.task && options.task.status !== 'cancelled')
+        pushLine(options.task, line);
+    return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
+}
 /**
  * 宿主自身 CLI 调不起来时的 ASCII 标记行：spawn 我们解析出的宿主入口报 ENOENT 时返回
  * `[host-spawn]`，供前端单独归因、不引导提 Issue。PATH 上的 dsh/npm 各有自己的标记，返回 null。
@@ -860,6 +884,8 @@ export async function runPluginMutation(options) {
     }
     // 包在 registry 不存在（404）→ 官方源复查，区分「作者的依赖缺失/包被删」与「本机镜像源滞后」
     result = await annotateRegistryMissing(result, options);
+    // 插件声明的最低 DSH 版本高于当前宿主 → 追加 [dsh-too-old] 标记，前端提示先升级 DSH
+    result = await annotateDshTooOld(result, options);
     // npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 追加 [npm-too-low] 标记，前端据此给准确原因
     return annotateNpmTooLow(result, options);
 }

package/lib/types/services/host-version.d.ts

@@ -0,0 +1,10 @@
+/** 从命令输出里抽出版本号本体：pnpm/npm 直接打印 `11.7.0`，而 `git --version` 打印
+ *  `git version 2.55.0.windows.5` —— 原样取首行会让 issue 正文拼成 `vgit version …`。
+ *  只取版本号，顺带兼容 `v1.2.3` 这类自带前缀的输出。 */
+export declare function versionOf(output: string): string | null;
+/** 探测命令行工具版本：未安装 / 不在 PATH / 超时一律 null。
+ *  Windows 上 pnpm/npm 是 .cmd shim，不走 shell 起不来；参数是固定的 `--version`，没有注入面。 */
+export declare function toolVersion(cmd: string, args: string[]): string | null;
+/** 宿主 dsh 版本：优先 `dsh --version`；拿不到再从入口 `process.argv[1]` 向上找 package.json
+ *  （dsh 不在 PATH 时兜底）。探测成功即缓存，失败不缓存以便下次重试。 */
+export declare function hostDshVersion(): string | null;

package/lib/types/services/install/dsh-compat.d.ts

@@ -0,0 +1,19 @@
+/** 从安装目标里取 npm 包名：`@scope/pkg@1.2.3` → `@scope/pkg`。
+ *  git / URL / 本地路径等非 npm 目标返回 null。 */
+export declare function npmNameOf(target: string): string | null;
+/** `0.2.1-rc.1` / `^0.2.1` / `>=0.2.0 <0.3.0` → [0,2,1]；解析不出返回 null。
+ *  只取版本三段：DSH 的 prerelease 序号（rc.1）不参与「太低」判断，避免比较误差。 */
+export declare function versionTriple(raw: string): [number, number, number] | null;
+/** 插件声明的最低 DSH 版本：engines.dsh 与 peerDependencies 里 @deepseek-ai/dsh-* 的下限取最大。
+ *  返回原始声明文本（如 `^0.2.1-rc.1`）供提示直接展示；没有声明返回 null。 */
+export declare function dshFloorOf(manifest: unknown): string | null;
+/**
+ * 产出「插件要求更高的 DSH」标记行；没有声明、读不到元数据、宿主版本未知或已满足时返回 null。
+ * 用版本级 manifest（`/<pkg>/latest`）：packument 的精简形态不带 peerDependencies。
+ */
+export declare function dshTooOldMarker(target: string, opts?: {
+    currentVersion?: string | null;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    registry?: string;
+}): Promise<string | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 10000+ human-curated community plugins without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：10000+ 人工精选社区插件，每日更新。",
   "type": "module",
   "main": "lib/index.js",

package/src/client/components/modals/NotificationsModal.tsx

@@ -14,7 +14,7 @@ import type { MouseEvent } from 'react'
 import styles from '../../styles/Modal.module.css'
 import type { EnvInfo, Translate } from '../../types.ts'
 import type { NotificationRecord } from '../../logic/failures.ts'
-import { actionOfRecord, classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf, authRegistryHostOf } from '../../logic/failures.ts'
+import { actionOfRecord, classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf, authRegistryHostOf, exclusiveProfileOf, desktopCliFallbackOf, dshTooOldInfoOf, missingLocalDirOf } from '../../logic/failures.ts'
 import type { PendingRestart, QueueTask } from '../../hooks/useTaskQueue.ts'
 import { pluginIssueUrl, pluginSiteUrl, hubIssueUrl } from '../../logic/urls.ts'
 import { CloseIcon } from '../ui/icons.tsx'
@@ -306,6 +306,11 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 给 .npmrc 豁免指引，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failPnpmWorkspaceHint'))
                     }
+                    if (kind === 'pnpmVirtualStore') {
+                      // profile 的 modules 目录与当前 pnpm 的 virtual-store-dir-max-length 不一致：
+                      // 该 profile 内的安装/卸载都会失败 —— 重建 modules 目录或统一配置即可，不引导提 Issue
+                      return h('div', { className: styles.failPrepareHint }, t('failPnpmVirtualStoreHint'))
+                    }
                     if (kind === 'pnpmStore') {
                       // pnpm 存在但 store 大版本不匹配（ERR_PNPM_UNEXPECTED_STORE）：profile 目录的依赖是
                       // 另一大版本 pnpm 装的，当前 pnpm 不认，任何插件装进该 profile 都会失败 ——
@@ -372,10 +377,13 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       return h('div', { className: styles.failPrepareHint }, t('failRegistryVersionStaleHint'))
                     }
                     if (kind === 'pnpmLinkedDirMissing') {
-                      // profile 里留着指向不存在目录的本地依赖（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND）：
-                      // 常见于 link:/本地路径装过开发中的插件、之后目录被删；与本次要装的插件无关
-                      // —— 给删除悬空条目的指引，不引导提 Issue
-                      return h('div', { className: styles.failPrepareHint }, t('failPnpmLinkedDirMissingHint'))
+                      // profile 里留着指向不存在目录的本地依赖（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND /
+                      // pnpm ENOENT lstat）：点名缺失目录 + 删除悬空条目，不引导提 Issue
+                      const dir = missingLocalDirOf(r.message)
+                      return h('div', null, [
+                        dir ? h('div', { className: styles.failNetworkTarget }, t('failLinkedDirTarget', { path: dir })) : null,
+                        h('div', { className: styles.failPrepareHint }, t('failPnpmLinkedDirMissingHint')),
+                      ])
                     }
                     if (kind === 'fileLocked') {
                       // profile 里的文件被其他进程占用（Windows os error 32）：通常是宿主或杀毒软件
@@ -397,6 +405,24 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 安装流程，与插件无关 —— 引导从本机地址重新打开市场，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failOriginRejectedHint', { profile: env?.profile ?? '<profile>' }))
                     }
+                    if (kind === 'profileExclusive') {
+                      // desktop profile 只能由桌面应用管理：外部 dsh CLI 被宿主拒绝，属环境约束。
+                      // 带 [desktop-cli-fallback] 则是安装器没找到应用内 CLI 引导脚本 —— 我们的问题，给反馈入口
+                      const profile = exclusiveProfileOf(r.message)
+                      const ourBug = desktopCliFallbackOf(r.message)
+                      return h('div', null, [
+                        h('div', { className: styles.failPrepareHint },
+                          t(profile ? 'failProfileExclusiveHint' : 'failProfileExclusiveHintNoProfile', profile ? { profile } : undefined)),
+                        ourBug ? h('div', { className: styles.failPrepareHint }, t('failDesktopCliFallbackHint')) : null,
+                        ourBug ? h('a', {
+                          className: styles.failBigIssue,
+                          href: hubIssueUrl(shownRepo || r.repo, r.message, env, r.command, r.attempts, 'triage', action),
+                          target: '_blank',
+                          rel: 'noopener noreferrer',
+                          title: t('failHubIssueHint'),
+                        }, t('failIssueBig')) : null,
+                      ])
+                    }
                     if (kind === 'registryAuth') {
                       // npm 源返回 401/403：私有源需要凭据，或当前网络/IP 不被允许 —— 本机环境问题，
                       // 给「配认证 / 换回官方源 / 切公共镜像」指引，不引导提 Issue
@@ -404,6 +430,30 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       return h('div', { className: styles.failPrepareHint },
                         t(host ? 'failRegistryAuthHint' : 'failRegistryAuthHintNoHost', host ? { host } : undefined))
                     }
+                    if (kind === 'dshTooOld') {
+                      // 插件要求的 DSH 下限高于本机宿主：升级 DSH 即可，不属作者、也不属插件中心
+                      const info = dshTooOldInfoOf(r.message)
+                      return h('div', { className: styles.failPrepareHint },
+                        t('failDshTooOldHint', info ?? { pkg: shownRepo || r.repo || 'plugin', floor: '?', current: '?' }))
+                    }
+                    if (kind === 'localEnv') {
+                      // 未命中具体成因、但特征指向本机环境：给通用自查清单 + 系统诊断，默认不推给我们，
+                      // 只留小字反馈入口（判据是我们自己的启发式，可能误判）
+                      return h('div', null, [
+                        h('div', { className: styles.failPrepareHint }, t('failLocalEnvHint')),
+                        onRunDiagnostics ? h('button', { className: styles.failDiagBtn, onClick: onRunDiagnostics }, t('failNetworkRunDiag')) : null,
+                        h('div', null, [
+                          h('div', { className: styles.failPrepareHint }, t('failMisjudgeHint')),
+                          h('a', {
+                            className: styles.failMisjudgeLink,
+                            href: hubIssueUrl(shownRepo || r.repo, r.message, env, r.command, r.attempts, 'triage', action),
+                            target: '_blank',
+                            rel: 'noopener noreferrer',
+                            title: t('failHubIssueHint'),
+                          }, t('failMisjudgeLink')),
+                        ]),
+                      ])
+                    }
                     if (kind === 'network') {
                       // 安装前网络探测 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
                       // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，

package/src/client/components/modals/modals.tsx

@@ -15,7 +15,7 @@ import { CloseIcon, ConfirmIcon, CopyIcon, LinkIcon } from '../ui/icons.tsx'
 import { ProgressView } from './ProgressView.tsx'
 import { installCommandOf } from '../../logic/install-command.ts'
 import { pluginDetailUrl, pluginIssueUrl, pluginSiteUrl, hubIssueUrl } from '../../logic/urls.ts'
-import { classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf, authRegistryHostOf } from '../../logic/failures.ts'
+import { classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf, authRegistryHostOf, exclusiveProfileOf, desktopCliFallbackOf, dshTooOldInfoOf, missingLocalDirOf } from '../../logic/failures.ts'
 import type { FailureAction } from '../../logic/failures.ts'
 
 /** 完成结果视图：绿色对勾 + 标题/描述；
@@ -445,6 +445,10 @@ export function ErrorModal({ message, repo, action, command, attempts, t, env, o
               // 调 pnpm add 时未声明在根操作，任何插件都会失败，不是插件问题 ——
               // 给 .npmrc 豁免指引，不引导提 Issue
               ? h('div', { className: styles.failPrepareHint }, t('failPnpmWorkspaceHint'))
+              : failureKind === 'pnpmVirtualStore'
+              // profile 的 modules 目录与当前 pnpm 的 virtual-store-dir-max-length 不一致：
+              // 该 profile 内的安装/卸载都会失败 —— 重建 modules 目录或统一配置即可，不引导提 Issue
+              ? h('div', { className: styles.failPrepareHint }, t('failPnpmVirtualStoreHint'))
               : failureKind === 'pnpmStore'
               // pnpm 存在但 store 大版本不匹配（ERR_PNPM_UNEXPECTED_STORE）：profile 目录的依赖是
               // 另一大版本 pnpm 装的，当前 pnpm 不认，任何插件装进该 profile 都会失败 ——
@@ -513,10 +517,16 @@ export function ErrorModal({ message, repo, action, command, attempts, t, env, o
               // 给「对齐源 / 那一次显式走官方源 / 用离线包」的指引，不引导提 Issue
               ? h('div', { className: styles.failPrepareHint }, t('failRegistryVersionStaleHint'))
               : failureKind === 'pnpmLinkedDirMissing'
-              // profile 里留着指向不存在目录的本地依赖（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND）：常见于
-              // link:/本地路径装过开发中的插件、之后目录被删；pnpm 每次解析 profile 依赖都先卡在它上面，
-              // 与本次要装的插件无关 —— 给删除悬空条目的指引，不引导提 Issue
-              ? h('div', { className: styles.failPrepareHint }, t('failPnpmLinkedDirMissingHint'))
+              // profile 里留着指向不存在目录的本地依赖（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND / pnpm ENOENT lstat）：
+              // 常见于 link:/本地路径装过开发中的插件、之后目录被删；pnpm 每次解析 profile 依赖都先卡在它上面，
+              // 与本次要装的插件无关 —— 点名缺失目录 + 删除悬空条目的指引，不引导提 Issue
+              ? h('div', null, [
+                (() => {
+                  const dir = missingLocalDirOf(message)
+                  return dir ? h('div', { className: styles.failNetworkTarget }, t('failLinkedDirTarget', { path: dir })) : null
+                })(),
+                h('div', { className: styles.failPrepareHint }, t('failPnpmLinkedDirMissingHint')),
+              ])
               : failureKind === 'fileLocked'
               // profile 文件被其他进程占用
               ? h('div', { className: styles.failPrepareHint }, t('failFileLockedHint'))
@@ -530,6 +540,26 @@ export function ErrorModal({ message, repo, action, command, attempts, t, env, o
               // 请求来源没通过本地 hub 服务的校验（服务端 403 untrusted origin）：请求根本没进
               // 安装流程，与插件无关 —— 引导从本机地址重新打开市场，不引导提 Issue
               ? h('div', { className: styles.failPrepareHint }, t('failOriginRejectedHint', { profile: env?.profile ?? '<profile>' }))
+              : failureKind === 'profileExclusive'
+              // desktop profile 只能由桌面应用管理：外部 dsh CLI 被宿主拒绝，属环境约束。
+              // 但日志里有 [desktop-cli-fallback] 时是我们没找到应用内 CLI 引导脚本才退回 PATH
+              // —— 那是安装器自身的问题，必须留一条回到插件中心的通道
+              ? (() => {
+                const profile = exclusiveProfileOf(message)
+                const ourBug = desktopCliFallbackOf(message)
+                return h('div', null, [
+                  h('div', { className: styles.failPrepareHint },
+                    t(profile ? 'failProfileExclusiveHint' : 'failProfileExclusiveHintNoProfile', profile ? { profile } : undefined)),
+                  ourBug ? h('div', { className: styles.failPrepareHint }, t('failDesktopCliFallbackHint')) : null,
+                  ourBug ? h('a', {
+                    className: styles.failBigIssue,
+                    href: hubIssueUrl(repo, message, env, command, attempts, 'triage', action),
+                    target: '_blank',
+                    rel: 'noopener noreferrer',
+                    title: t('failHubIssueHint'),
+                  }, t('failIssueBig')) : null,
+                ])
+              })()
               : failureKind === 'registryAuth'
               // npm 源返回 401/403：私有源需要凭据，或当前网络/IP 不被允许 —— 本机环境问题，
               // 给「配认证 / 换回官方源 / 切公共镜像」指引，不引导提 Issue
@@ -538,6 +568,31 @@ export function ErrorModal({ message, repo, action, command, attempts, t, env, o
                 return h('div', { className: styles.failPrepareHint },
                   t(host ? 'failRegistryAuthHint' : 'failRegistryAuthHintNoHost', host ? { host } : undefined))
               })()
+              : failureKind === 'dshTooOld'
+              // 安装器读插件 npm 元数据得出的结论：插件要求的 DSH 下限高于本机宿主。
+              // 用户升级 DSH 即可解决，不属插件作者、也不属插件中心 —— 不引导提 Issue
+              ? (() => {
+                const info = dshTooOldInfoOf(message)
+                return h('div', { className: styles.failPrepareHint },
+                  t('failDshTooOldHint', info ?? { pkg: repo ?? 'plugin', floor: '?', current: '?' }))
+              })()
+              : failureKind === 'localEnv'
+              // 未命中具体成因、但特征指向本机环境：给通用自查清单 + 直达系统诊断，不推给作者，
+              // 也默认不推给我们 —— 只留小字反馈入口，防环境问题堆进插件中心的 issue 列表
+              ? h('div', null, [
+                h('div', { className: styles.failPrepareHint }, t('failLocalEnvHint')),
+                onRunDiagnostics ? h('button', { className: styles.failDiagBtn, onClick: onRunDiagnostics }, t('failNetworkRunDiag')) : null,
+                h('div', null, [
+                  h('div', { className: styles.failPrepareHint }, t('failMisjudgeHint')),
+                  h('a', {
+                    className: styles.failMisjudgeLink,
+                    href: hubIssueUrl(repo, message, env, command, attempts, 'triage', action),
+                    target: '_blank',
+                    rel: 'noopener noreferrer',
+                    title: t('failHubIssueHint'),
+                  }, t('failMisjudgeLink')),
+                ]),
+              ])
               : failureKind === 'network'
               // 安装前网络探测 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
               // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，