dsh-plugin 2.1.0 → 2.2.0

package/src/client/locales.ts

@@ -374,6 +374,9 @@ export const zh = {
   failReason_buildToolchainMissing: '这个插件依赖需要在本机编译的原生模块，但找不到可用的编译器。',
   failKind_pnpmStore: 'pnpm store 版本不匹配',
   failReason_pnpmStore: 'profile 里的依赖由另一大版本的 pnpm 生成，当前 pnpm 不认。',
+  failKind_pnpmVirtualStore: 'profile 的依赖目录与当前 pnpm 配置不一致',
+  failReason_pnpmVirtualStore: 'node_modules 是用另一套 virtual-store-dir-max-length 配置创建的，pnpm 拒绝复用。',
+  failPnpmVirtualStoreHint: '安装器调用 pnpm 时报「modules 目录由另一套 virtual-store-dir-max-length 配置创建」（ERR_PNPM_VIRTUAL_STORE_DIR_MAX_LENGTH_DIFF）：profile 里的 node_modules 是在别的 pnpm 配置下生成的（常见于在 .npmrc 里改过 virtual-store-dir-max-length，或换过 pnpm 大版本），当前 pnpm 出于安全拒绝在它上面继续操作——所以这个 profile 里的安装/卸载都会失败。修复（任选其一，在 profile 目录 ~/.dsh/profiles/<profile> 下操作）：① 先执行一次 pnpm install，让它按当前配置重建 modules 目录；② 删掉该目录下的 node_modules，下次安装/卸载会自动重建；③ 如果你在 .npmrc 里设过 virtual-store-dir-max-length，把它统一成同一个值（或删掉自定义、回到默认）。这不是插件本身的问题。',
   failKind_pnpmWorkspace: 'workspace 根校验阻止了安装',
   failReason_pnpmWorkspace: 'profile 被当作 workspace 根，但没有声明根操作，pnpm 中止了安装。',
   failKind_originRejected: '本地服务的来源校验未通过',
@@ -390,6 +393,8 @@ export const zh = {
   failReason_registryVersionStale: '实际安装用的源还没同步到这个版本，或版本号写错。',
   failKind_registryAuth: 'npm 源拒绝了访问',
   failReason_registryAuth: 'registry 返回 401/403：这个源需要登录凭据，或当前网络不被允许。',
+  failKind_profileExclusive: 'profile 由桌面应用独占管理',
+  failReason_profileExclusive: '命令行 dsh 无权管理桌面应用的 profile，安装前就被宿主拒绝。',
   failKind_pnpmLinkedDirMissing: 'profile 里有失效的本地依赖',
   failReason_pnpmLinkedDirMissing: '有一条指向本机不存在目录的 link/file 依赖，pnpm 每次解析都卡住。',
   failKind_fileLocked: '文件被其他程序占用',
@@ -416,10 +421,20 @@ export const zh = {
   failReason_profileLock: '另一个 dsh 进程正在使用这个 profile。',
   failKind_hub: '出现未知错误',
   failReason_hub: '我们还没能识别这条报错，你可以一键反馈给我们。',
+  failKind_localEnv: '本机环境异常',
+  failReason_localEnv: '报错特征指向你的本机环境（系统错误码 / 证书代理 / 本地配置），没有发现插件侧原因。',
+  failKind_dshTooOld: 'DSH 版本低于插件要求',
+  failReason_dshTooOld: '插件声明的最低 DSH 版本高于你当前运行的宿主版本。',
+  failDshTooOldHint: '插件「{pkg}」声明需要 DSH {floor} 或更高，而你当前运行的是 {current} —— 版本不够时装不上（或装上后无法正常加载），这不是插件本身的问题，也不是插件市场的误判。请先把 DeepSeek Harness 升级到 {floor} 以上，再回到插件中心重试。如果升级后仍然失败，把新的报错发给我们。',
+  failLocalEnvHint: '从日志能确认的只有一点：没有插件侧的失败证据；报错特征落在本机环境（系统调用错误码、证书/代理校验、本地配置文件损坏等），但还不足以精确到某一类。这类问题装别的插件同样会失败，不是插件本身的问题。请按顺序自查：① 点下面的「运行系统诊断」看本机检查项；② 确认 profile 目录（~/.dsh/profiles/<profile>）可写、磁盘有空间、杀毒软件没拦截；③ 若在用代理或公司镜像源，先临时切回官方源 https://registry.npmjs.org 重试；④ 完全退出 DeepSeek Harness 后重试。排查后仍然失败、且你确信环境没问题，再用下面的链接反馈给我们，并附上通知中心里复制的完整日志。',
   failRegistryVersionStaleHint: '安装器调用 pnpm 时报「找不到匹配的版本」（ERR_PNPM_NO_MATCHING_VERSION）：要装的这个版本在实际执行安装的 npm 源里查不到。常见原因是你设置的 npmRegistry 与本机 ~/.npmrc 用的不是同一个源——官方源刚发布、镜像还没同步上来（快则几分钟、慢则几小时），也可能只是版本号写错了。这不是插件本身的问题。可在插件市场设置里把 npmRegistry 改成与本机 ~/.npmrc 一致（或反过来），或那一次显式走官方源（https://registry.npmjs.org）、改用离线包后重试；若该版本刚发布不久，等镜像同步后重试即可。',
   failRegistryAuthHint: '安装器访问 npm 源时被拒绝（HTTP 401/403）：这个源需要登录凭据，或不允许当前网络/IP 访问。如果你在用公司或私有源，请先配好认证（npm login，或在 ~/.npmrc 写入 //{host}/:_authToken=…）；如果不需要私有源，把 registry 换回官方源 https://registry.npmjs.org，或在插件市场设置里切换到公共镜像后重试。这不是插件本身的问题。',
   failRegistryAuthHintNoHost: '安装器访问 npm 源时被拒绝（HTTP 401/403）：这个源需要登录凭据，或不允许当前网络/IP 访问。如果你在用公司或私有源，请先配好认证（npm login，或在 ~/.npmrc 写入 //<registry>/:_authToken=…）；如果不需要私有源，把 registry 换回官方源 https://registry.npmjs.org，或在插件市场设置里切换到公共镜像后重试。这不是插件本身的问题。',
+  failProfileExclusiveHint: 'profile「{profile}」由桌面应用独占管理，命令行 dsh 无权安装 —— 这不是插件本身的问题。请在 DeepSeek Harness 桌面应用的「设置 → 插件市场」里安装；或改用非桌面独占的 profile（例如 web）后重试。如果你就是在桌面应用内看到这条错误，请到插件市场的「通知」里打开这条失败记录点「复制」，把完整日志发给我们。',
+  failProfileExclusiveHintNoProfile: '当前 profile 由桌面应用独占管理，命令行 dsh 无权安装 —— 这不是插件本身的问题。请在 DeepSeek Harness 桌面应用的「设置 → 插件市场」里安装；或改用非桌面独占的 profile（例如 web）后重试。如果你就是在桌面应用内看到这条错误，请到插件市场的「通知」里打开这条失败记录点「复制」，把完整日志发给我们。',
+  failDesktopCliFallbackHint: '这次是安装器没找到桌面应用内置的 CLI 引导脚本、退回命令行 dsh 才被拒绝 —— 属于插件中心自身的问题，不是你的环境问题。点下面的按钮把完整日志发给我们，我们会补上路径推导。',
   failPnpmLinkedDirMissingHint: '安装器调用 pnpm 时报「要安装的目录不存在」（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND）：你的 profile 里留着一条指向本机不存在目录的本地依赖（link: / file: 形式，例如用 dsh plugin add <本地路径> 装过开发中的插件，之后那个目录被删除或移动了）。pnpm 每次解析 profile 依赖都会先卡在它上面，因此任何插件都装不进来。这不是插件本身的问题——请在 profile 目录（~/.dsh/profiles/<profile>）的 package.json 里删除该本地依赖条目（同时删掉对应的 pnpm-lock.yaml 条目或整个锁文件），或把该目录恢复回原路径后重试。',
+  failLinkedDirTarget: '缺失的本地目录：{path}',
   failFileLockedHint: '安装过程中 pnpm 无法替换 profile 里的文件：有程序正占用着它（Windows 常见报错 os error 32「另一个程序正在使用此文件」）。通常是 DeepSeek Harness 自身或杀毒软件的实时扫描持有文件句柄。这不是插件本身的问题——请完全退出 DeepSeek Harness（Windows 可在任务管理器确认进程已结束，必要时临时关闭杀毒软件实时防护）后重试。',
   failAccessDeniedHint: '安装过程中 pnpm 写入 profile 里的文件被系统拒绝访问（Windows 常见报错 os error 5「拒绝访问」，英文为 Access is denied；Node 下的 EPERM / EACCES 同理）。常见原因是该文件或目录正被其他进程占用、文件带只读属性、目录权限受限，或杀毒软件实时防护拦截了写入——这与「文件正被占用」（os error 32）同属本机文件系统问题，任何插件装进该目录都会一样失败，不是插件本身的问题。请完全退出 DeepSeek Harness（Windows 可在任务管理器确认进程已结束，必要时临时关闭杀毒软件实时防护）后重试；若仍然失败，请检查 profile 目录及其文件是否被设为只读，并以管理员身份重新运行。',
   failFsUnavailableHint: '安装过程中 pnpm 无法把文件写进本机磁盘（这类报错与装哪个插件无关，任何插件装在同一目录都会失败，不是插件本身的问题）。请按报错对号入座：① 磁盘空间不足（ENOSPC / no space left on device，Windows 为 os error 112）——请清理 profile 所在磁盘的剩余空间后重试；② 磁盘或挂载点只读、带写保护（EROFS / read-only file system，Windows 为 os error 19）——请确认 profile 目录所在磁盘可写（外接盘/U 盘、带写保护的移动盘或只读挂载的分区都会触发），必要时把插件目录换到系统盘的可写位置；③ 进程可用的文件句柄被耗尽（EMFILE / ENFILE / too many open files）——请关闭占用大量文件的程序并重启 DeepSeek Harness 后重试。',
@@ -844,6 +859,9 @@ export const en = {
   failReason_buildToolchainMissing: 'A dependency of this plugin must be compiled locally, but no usable compiler was found.',
   failKind_pnpmStore: 'pnpm store version mismatch',
   failReason_pnpmStore: 'The profile dependencies were written by a different pnpm major, which the current pnpm does not accept.',
+  failKind_pnpmVirtualStore: 'profile dependency directory does not match the current pnpm config',
+  failReason_pnpmVirtualStore: 'node_modules was created with a different virtual-store-dir-max-length, so pnpm refuses to reuse it.',
+  failPnpmVirtualStoreHint: 'pnpm reported that the modules directory was created with a different virtual-store-dir-max-length value (ERR_PNPM_VIRTUAL_STORE_DIR_MAX_LENGTH_DIFF): node_modules inside the profile was built under a different pnpm config (typically after editing virtual-store-dir-max-length in .npmrc, or switching pnpm majors), so the current pnpm refuses to operate on it — installs and removals in this profile will keep failing. Fix it (any one of these, run inside the profile directory ~/.dsh/profiles/<profile>): ① run pnpm install once so it recreates the modules directory with the current config; ② delete node_modules there — the next install/removal recreates it; ③ if you set virtual-store-dir-max-length in .npmrc, make it the same value everywhere (or drop the override and go back to the default). This is not a problem with the plugin itself.',
   failKind_pnpmWorkspace: 'workspace-root check blocked the install',
   failReason_pnpmWorkspace: 'The profile is treated as a workspace root without a root operation declared, so pnpm aborted.',
   failKind_originRejected: 'request origin rejected by the local service',
@@ -860,6 +878,8 @@ export const en = {
   failReason_registryVersionStale: 'The registry that actually performs the install has not synced this version yet, or the version is mistyped.',
   failKind_registryAuth: 'the npm registry rejected access',
   failReason_registryAuth: 'The registry returned 401/403: it needs credentials, or the current network is not allowed.',
+  failKind_profileExclusive: 'the profile is managed only by the desktop app',
+  failReason_profileExclusive: 'The dsh CLI may not manage the desktop profile, so the host refused before installing.',
   failKind_pnpmLinkedDirMissing: 'dangling local dependency in the profile',
   failReason_pnpmLinkedDirMissing: 'A link/file dependency points at a directory that no longer exists, so pnpm stalls on it.',
   failKind_fileLocked: 'a file is held by another program',
@@ -886,10 +906,20 @@ export const en = {
   failReason_profileLock: 'Another dsh process is using this profile right now.',
   failKind_hub: 'unknown error',
   failReason_hub: 'We could not identify this error yet — you can report it to us in one click.',
+  failKind_localEnv: 'local environment failure',
+  failReason_localEnv: 'The error points at your local environment (system error codes, certificates/proxy, or local config), and no plugin-side cause was found.',
+  failKind_dshTooOld: 'DSH is older than the plugin requires',
+  failReason_dshTooOld: 'The plugin declares a minimum DSH version that is newer than the host you are running.',
+  failDshTooOldHint: 'The plugin "{pkg}" requires DSH {floor} or newer, but this host runs {current} — the install cannot succeed on an older host (or the plugin will not load properly). This is not a problem with the plugin itself, and not a mistake by the marketplace. Upgrade DeepSeek Harness to {floor} or newer, then retry from the Plugin Hub. If it still fails after upgrading, send us the new error.',
+  failLocalEnvHint: 'The log only tells us one thing for sure: there is no evidence of a plugin-side failure — the signals point at your local environment (system call error codes, certificate/proxy validation, a broken local config file), but not precisely enough to name one. Any plugin would fail the same way on this machine, so it is not a problem with the plugin itself. Check in order: ① press "Run diagnostics" below; ② make sure the profile directory (~/.dsh/profiles/<profile>) is writable, the disk has free space, and antivirus is not blocking it; ③ if you use a proxy or a company mirror, switch back to the official registry (https://registry.npmjs.org) for one retry; ④ fully quit DeepSeek Harness and retry. If it still fails and you are sure your environment is fine, use the link below to report it with the full log copied from the Hub notifications.',
   failRegistryVersionStaleHint: 'pnpm reported that no matching version was found (ERR_PNPM_NO_MATCHING_VERSION): the version being installed does not exist in the npm registry that actually performs the install. This usually means the npmRegistry configured in the hub differs from the source in your local ~/.npmrc — the official registry has published it but the mirror has not synced yet (it can take minutes to hours) — or the version number was simply mistyped. This is not a problem with the plugin itself. Align the hub\'s npmRegistry with your local ~/.npmrc (or the other way round), or explicitly use the official registry (https://registry.npmjs.org) for that one install, or use an offline package, then retry; if the version was published only recently, waiting for the mirror to sync is enough.',
   failRegistryAuthHint: 'The installer was denied access to the npm registry (HTTP 401/403): that registry requires credentials, or it does not allow the current network/IP. If you are using a company or private registry, configure authentication first (npm login, or write //{host}/:_authToken=… into ~/.npmrc). If you do not need a private registry, point the registry back to the official one (https://registry.npmjs.org), or switch to a public mirror in the hub settings, then retry. This is not a problem with the plugin itself.',
   failRegistryAuthHintNoHost: 'The installer was denied access to the npm registry (HTTP 401/403): that registry requires credentials, or it does not allow the current network/IP. If you are using a company or private registry, configure authentication first (npm login, or write //<registry>/:_authToken=… into ~/.npmrc). If you do not need a private registry, point the registry back to the official one (https://registry.npmjs.org), or switch to a public mirror in the hub settings, then retry. This is not a problem with the plugin itself.',
+  failProfileExclusiveHint: 'Profile "{profile}" is managed exclusively by the desktop app, and the command-line dsh is not allowed to install into it — this is not a problem with the plugin itself. Install from "Settings → Plugin Hub" inside DeepSeek Harness Desktop, or retry with a profile that is not desktop-managed (for example web). If you hit this inside the desktop app, open the Hub notifications, select the failed record and press "Copy" so you can send us the full log.',
+  failProfileExclusiveHintNoProfile: 'The current profile is managed exclusively by the desktop app, and the command-line dsh is not allowed to install into it — this is not a problem with the plugin itself. Install from "Settings → Plugin Hub" inside DeepSeek Harness Desktop, or retry with a profile that is not desktop-managed (for example web). If you hit this inside the desktop app, open the Hub notifications, select the failed record and press "Copy" so you can send us the full log.',
+  failDesktopCliFallbackHint: 'This failed because the installer could not find the desktop app\'s bundled CLI bootstrap and fell back to the command-line dsh, which is then refused — that is a bug in the plugin hub, not your environment. Use the button below to send us the full log and we will fix the path detection.',
   failPnpmLinkedDirMissingHint: 'pnpm reported that a directory it needs to install from does not exist (ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND): your profile keeps a local dependency (a link: / file: entry, e.g. from `dsh plugin add <local path>`) whose target directory has since been deleted or moved. pnpm hits it every time it resolves profile dependencies, so no plugin can be installed into that profile. This is not a problem with the plugin itself. Remove that local dependency from package.json inside the profile directory (~/.dsh/profiles/<profile>) — along with its entry in pnpm-lock.yaml, or the lockfile itself — or restore the directory to its original path, then retry.',
+  failLinkedDirTarget: 'Missing local directory: {path}',
   failFileLockedHint: 'During install, pnpm could not replace a file inside the profile because another program is holding it (on Windows this shows as os error 32, "the process cannot access the file because it is being used by another process"). Usually DeepSeek Harness itself or a real-time antivirus scan holds the handle. This is not a problem with the plugin itself — fully quit DeepSeek Harness (on Windows, confirm in Task Manager that the process has ended, and temporarily disable real-time antivirus protection if needed), then retry.',
   failAccessDeniedHint: 'During install, Windows denied pnpm access to a file inside the profile (this shows as os error 5, "Access is denied"; on Node the equivalent codes are EPERM / EACCES). Typical causes: the file or directory is held by another process, the file is marked read-only, the directory permissions are restricted, or a real-time antivirus scan blocked the write. This is the same class of local file-system problem as a locked file (os error 32) — no plugin can be installed into that directory, so it is not a problem with the plugin itself. Fully quit DeepSeek Harness (on Windows, confirm in Task Manager that the process has ended, and temporarily disable real-time antivirus protection if needed), then retry. If it still fails, check whether the profile directory or its files are read-only and run as administrator.',
   failFsUnavailableHint: 'During install, pnpm could not write files to the local disk — this has nothing to do with which plugin you are installing: any plugin installed into the same directory would fail the same way, so it is not a problem with the plugin itself. Match the error you see: ① Out of space (ENOSPC / no space left on device, os error 112 on Windows) — free up space on the drive that holds the profile and retry. ② Read-only or write-protected volume (EROFS / read-only file system, os error 19 on Windows) — make sure the drive holding the profile directory is writable (external or USB drives, write-protected media, and read-only mounts all trigger this); move the plugin directory to a writable location on the system drive if needed. ③ File handles exhausted (EMFILE / ENFILE / too many open files) — close programs that hold many files open, restart DeepSeek Harness, then retry.',

package/src/client/logic/failures.ts

@@ -148,7 +148,7 @@ export function removeNotification(id: number): NotificationRecord[] {
   return next
 }
 
-export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'pluginMissingDep' | 'registryVersionStale' | 'registryAuth' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'buildToolchainMissing' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'hostIncompatible' | 'network' | 'hostCliSpawn' | 'hubState' | 'timeout' | 'profileLock' | 'hub'
+export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmVirtualStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'pluginMissingDep' | 'registryVersionStale' | 'registryAuth' | 'profileExclusive' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'buildToolchainMissing' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'hostIncompatible' | 'network' | 'hostCliSpawn' | 'hubState' | 'timeout' | 'profileLock' | 'dshTooOld' | 'localEnv' | 'hub'
 
 /** 失败动作口径：标题、上报正文与提示文案按安装/更新/卸载取词，不写死「安装」。 */
 export type FailureAction = 'install' | 'update' | 'uninstall'
@@ -220,6 +220,9 @@ export function classifyFailure(message: string): FailureKind {
   // 宿主版本门禁：插件声明的兼容范围不含当前 dsh 版本，宿主在安装前直接拒绝。
   // 必须最先判 —— 这是宿主自己给的结论，不是 pnpm 的安装失败
   if (/installation rejected:.*incompatible with dsh/i.test(message)) return 'hostIncompatible'
+  // desktop profile 由桌面应用独占：外部 dsh CLI 无权管理，宿主在安装前直接拒绝。
+  // 属宿主/环境约束，不是插件问题；必须在所有 pnpm 分支之前判（日志里没有 pnpm 报错）。
+  if (/is managed exclusively by the Electron application|managed exclusively by the desktop app/i.test(message)) return 'profileExclusive'
   // npm 自身崩溃（edgesOut）或服务端标记的本机 npm 版本过低。必须最先判，否则会被外层
   // ERR_PNPM_PREPARE_PACKAGE 吞成「插件打包问题」
   if (/\[npm-too-low\]|edgesOut/i.test(message)) return 'npmTooOld'
@@ -231,6 +234,9 @@ export function classifyFailure(message: string): FailureKind {
   if (/\[npm-missing\]|spawn npm ENOENT|'npm' 不是内部或外部命令|"npm" 不是内部或外部命令|npm['"]?\s*is not recognized|npm: command not found/i.test(message)) return 'npmMissing'
   // 本机缺 dsh。服务端 [dsh-missing] 标记乱码免疫（Windows GBK 解码后无法匹配原文）
   if (/\[dsh-missing\]|不是内部或外部命令|is not recognized as an internal or external command|command not found|spawn dsh ENOENT/i.test(message)) return 'dshMissing'
+  // profile 的 modules 目录由另一套 virtual-store-dir-max-length 配置生成，当前 pnpm 拒绝复用。
+  // 必须在 pnpmStore 之前：两者的处置方式不同（这里只需重建 modules 目录 / 统一配置）
+  if (/ERR_PNPM_VIRTUAL_STORE_DIR_MAX_LENGTH_DIFF|virtual-store-dir-max-length/i.test(message)) return 'pnpmVirtualStore'
   // store 版本不匹配：profile 依赖由另一大版本 pnpm 生成，当前 pnpm 不认。
   // 必须在 pnpmMissing 之后（pnpm 能跑起来报错，不是找不到命令）
   if (/ERR_PNPM_UNEXPECTED_(VIRTUAL_)?STORE|Unexpected (virtual )?store location/i.test(message)) return 'pnpmStore'
@@ -256,6 +262,9 @@ export function classifyFailure(message: string): FailureKind {
   // npm 源拒绝了访问（401/403）：私有源要登录凭据，或当前网络/IP 不被源允许。
   // 必须在 network 之前判：pnpm 的 401/403 日志也常带 "fetch failed" 字样，先判网络会误报成「网络不通」
   if (/ERR_PNPM_FETCH_40[13]\b|\bE40[13]\b|(?:Unauthorized|Forbidden)\s*-\s*40[13]\b/i.test(message)) return 'registryAuth'
+  // profile 里指向已删除目录的本地依赖（file:/link:）：pnpm 直接 ENOENT（lstat），任何安装都会失败。
+  // 必须在 network 之前判 —— 同一份日志常混着 pnpm 重试产生的 UND_ERR_* 警告，先判网络会把根因盖掉。
+  if (/ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND|Could not install from .+ as it does not exist|pnpm:\s*ENOENT: no such file or directory,\s*(?:lstat|scandir|readlink)/i.test(message)) return 'pnpmLinkedDirMissing'
   // 网络/代理/源配置问题。必须在 prepare 之前判：git fetch 失败常被外层包成 "Command failed"
   // tarball 下载失败的括号里可能是数字码（pnpm 自己的）或符号码（undici 的 UND_ERR_*），两种都要认
   if (/\[network\]|ERR_PNPM_GIT_FETCH_FAILED|ETIMEDOUT|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH|UND_ERR_[A-Z0-9_]+|getaddrinfo|Could not connect|Could not resolve host|Network unreachable|Failed to connect|socket hang up|CERT_HAS_EXPIRED|SSL certificate problem|\bTLS\b|\bSSL\b|fetch failed|failed to fetch|\bGET https?:\/\/\S+\.tgz\s+error \([A-Za-z0-9_]+\)/i.test(message)) return 'network'
@@ -269,8 +278,6 @@ export function classifyFailure(message: string): FailureKind {
   if (/ERR_PNPM_FETCH_404|404 Not Found|Not Found - 404/i.test(message)) return 'pnpmMissingDep'
   // 要装的版本在实际安装源里没有（镜像滞后或版本写错）。必须在 pluginPrepare 之前判
   if (/\bERR_PNPM_NO_MATCHING_VERSION\b|\bETARGET\b|No matching version found/i.test(message)) return 'registryVersionStale'
-  // profile 残留指向不存在目录的本地依赖（link:/file:）。必须在 pluginPrepare 之前判
-  if (/\bERR_PNPM_LINKED_PKG_DIR_NOT_FOUND\b|Could not install from .+ as it does not exist/i.test(message)) return 'pnpmLinkedDirMissing'
   // 原生模块需要本机编译，缺编译器/构建工具属于用户环境，不是插件的 prepare 失败。
   // 必须排在 pluginPrepare 之前：这类日志同样带 ELIFECYCLE，否则会被推给作者。
   if (/Unable to detect compiler type|gyp ERR!|Could not find any Visual Studio|No Xcode or CLT version detected|xcode-select|python(?:3)? is (?:not set|not found)|Could not find Python|\bmake: not found\b|\bgcc: not found\b|\bg\+\+: not found\b|\bMSB\d{4}\b/i.test(message)) return 'buildToolchainMissing'
@@ -296,10 +303,26 @@ export function classifyFailure(message: string): FailureKind {
   // 宿主自身入口起不来（服务端 [host-spawn] 标记）：环境问题，给提示、不引导提 Issue。
   // 不匹配 `spawn … ENOENT` 文本 —— 那个形态任何 spawn（curl/git/taskkill…）都会产出
   if (/\[host-spawn\]/i.test(message)) return 'hostCliSpawn'
-  // 其余未知失败：引导到插件中心仓库排查
+  // 安装器读插件 npm 元数据得出的客观结论：插件声明的 DSH 下限高于本机宿主。
+  // 放在所有具体成因之后 —— 日志里有真实报错时仍以真实报错为准；但在「未分类」之前，
+  // 否则这类本来能说清的失败又会变成未知。
+  if (/\[dsh-too-old\]/i.test(message)) return 'dshTooOld'
+  // 裸 `spawn <cmd> ENOENT`（无 [host-spawn] 标记）：分不清是用户机器上缺这个可执行文件，
+  // 还是安装器解析错了路径 —— 不冒充环境问题，留给插件中心分诊
+  if (/spawn .+ ENOENT/i.test(message)) return 'hub'
+  // 未命中任何具体成因，但特征指向本机环境（系统调用错误码 / 证书代理 / 本地配置损坏）：
+  // 归「本机环境」给自助排查，而不是丢进未分类让用户等着我们分析 —— 装任何插件都会同样失败，
+  // 且这类误判代价低（用户自查重试即可）。位置必须在所有具体分支之后：能精确归因的优先精确。
+  if (LOCAL_ENV_RE.test(message)) return 'localEnv'
+  // 其余未知失败：没有任何环境/插件侧特征，可能是安装器或宿主的 bug —— 引导到插件中心仓库排查
   return 'hub'
 }
 
+/** 「特征指向本机环境但说不清具体哪一类」的兜底判据：系统调用错误码（权限/路径过长/设备异常）、
+ *  证书与代理校验失败、本地配置文件（~/.npmrc、profile 的 package.json）损坏。
+ *  只做排除用：命中它表示「不是插件侧问题」，不代表我们已经定位到原因。 */
+const LOCAL_ENV_RE = /os error \d{1,3}\b|ERROR_[A-Z_]{4,}|\bE(?:ACCES|PERM|NOENT|NAMETOOLONG|INVAL|PROTO|ISDIR|NOTDIR|EXIST|BADF|NOTEMPTY|JSONPARSE)\b|Unexpected token .{0,60}in JSON|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE|ERR_TLS_CERT_ALTNAME_INVALID|unable to verify the first certificate|self[- ]signed certificate|ERR_INVALID_URL|invalid registry|proxy authentication|407 Proxy/i
+
 /** 从服务端 `[npm-too-low]` 标记行提取本机 npm 版本（如 `[npm-too-low] npm@11.3.0` → "11.3.0"）；
  *  历史记录无标记时返回 null，前端据此决定提示文案是否带具体版本。 */
 export function npmTooLowVersion(message: string): string | null {
@@ -315,6 +338,10 @@ const CORE_LINE_RE = /ERR_[A-Z_]+|ELIFECYCLE|Command failed|prepare-guard|Failed
  *  无关 —— 抓核心错误时必须跳过，否则会被 CORE_LINE_RE 的 `missing` 分支误抓、淹没真正的
  *  错误码（如 git 源的 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED），让 issue 正文只剩一堆 peer WARN。 */
 const PEER_WARN_RE = /missing peer|issues with peer dependencies|peer dependencies that should be installed/i
+/** 安装器自己打的诊断标记行：它们本身就是「为什么没有日志 / 卡在哪一步」的证据，
+ *  不含 CORE_LINE_RE 的关键词，必须无条件保留 —— 否则上报正文会退回成只剩宿主那句摘要，
+ *  我们又拿不到任何可排查的信息（#382/#393 就是这样）。 */
+const MARKER_LINE_RE = /^\[(?:pnpm log|no-output|desktop-cli-fallback|dsh-too-old|host-spawn|npm-too-low|git-missing|npm-missing|pnpm-missing|dsh-missing|network|packaging|registry-missing|registry-mirror-lag|internal|exit\b|timed out)/i
 /** 提交 issue 时正文里错误摘要的上限字符数。GitHub 请求行上限 8192 字节，
  * 固定模板与 URL 编码开销约 1~2K，核心错误（以 ASCII 日志为主）可安全带到 ~5K；
  * 仍超长时 pluginIssueUrl 会逐档缩小核心预算，最终 URL 不会超限。 */
@@ -347,7 +374,8 @@ export function summarizeError(message: string, maxChars: number = MAX_CORE_CHAR
   const core: string[] = []
   for (const raw of message.split(/\r?\n/)) {
     const line = raw.trim()
-    if (!line || PEER_WARN_RE.test(line) || !CORE_LINE_RE.test(line)) continue
+    if (!line || PEER_WARN_RE.test(line)) continue
+    if (!MARKER_LINE_RE.test(line) && !CORE_LINE_RE.test(line)) continue
     const short = line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}…` : line
     if (!seen.has(short)) {
       seen.add(short)
@@ -438,6 +466,43 @@ export function registryHostOf(message: string): string | null {
   return PUBLIC_REGISTRY_HOSTS.has(host) ? null : host
 }
 
+/**
+ * 「本地依赖目录不存在」失败里缺失的路径：
+ * `pnpm: ENOENT: no such file or directory, lstat '<path>'`
+ * 或 `Could not install from "<path>" as it does not exist`。取不到返回 null。
+ */
+export function missingLocalDirOf(message: string): string | null {
+  const lstat = /ENOENT: no such file or directory,\s*(?:lstat|scandir|readlink)\s+'([^']+)'/i.exec(message)
+  if (lstat !== null) return lstat[1]
+  const quoted = /Could not install from\s+"([^"]+)"\s+as it does not exist/i.exec(message)
+    ?? /Could not install from\s+'([^']+)'\s+as it does not exist/i.exec(message)
+  return quoted === null ? null : quoted[1]
+}
+
+/**
+ * 「profile 由桌面应用独占」错误里的 profile 名：
+ * `error: profile "desktop" is managed exclusively by the Electron application`。
+ * 取不到返回 null（提示文案退回通用说法）。
+ */
+export function exclusiveProfileOf(message: string): string | null {
+  const m = /profile\s+"?([A-Za-z0-9_-]+)"?\s+is managed exclusively/i.exec(message)
+  return m === null ? null : m[1]
+}
+
+/**
+ * 日志里有安装器的 `[desktop-cli-fallback]` 标记：没找到桌面应用内置的 CLI 引导脚本，
+ * 退回 PATH 上的 dsh 才被「profile 独占」拒绝 —— 是我们的路径推导问题，不是用户环境问题。
+ */
+export function desktopCliFallbackOf(message: string): boolean {
+  return /\[desktop-cli-fallback\]/i.test(message)
+}
+
+/** `[dsh-too-old]` 标记里的三方信息（包名 / 插件要求的 DSH 下限 / 当前宿主版本）；取不到返回 null。 */
+export function dshTooOldInfoOf(message: string): { pkg: string; floor: string; current: string } | null {
+  const m = /\[dsh-too-old\]\s*(\S+)\s+requires DSH >= (\S+).*?runs (\S+)/i.exec(message)
+  return m === null ? null : { pkg: m[1]!, floor: m[2]!, current: m[3]! }
+}
+
 /**
  * 鉴权失败（401/403）时被拒绝的源主机名：从 `ERR_PNPM_FETCH_401 GET https://host/pkg: Unauthorized - 401`
  * 里取，取不到返回 null（提示文案退回通用说法，不拼出残缺句子）。

package/src/client/logic/urls.ts

@@ -49,6 +49,7 @@ function reasonTitleOf(kind: FailureKind, action: FailureAction): string {
     case 'dshMissing': return 'dsh command not found on the user machine'
     case 'pnpmMissing': return 'pnpm command not found on the user machine'
     case 'pnpmStore': return 'pnpm store version mismatch on the user machine'
+    case 'pnpmVirtualStore': return 'the profile modules directory was built with a different virtual-store-dir-max-length on the user machine'
     case 'pnpmWorkspace': return `pnpm workspace-root check blocked the ${word} on the user machine`
     case 'originRejected': return 'request origin rejected by the local service on the user machine'
     case 'pnpmPolicy': return `pnpm supply-chain policy blocked the ${word} on the user machine`
@@ -56,6 +57,7 @@ function reasonTitleOf(kind: FailureKind, action: FailureAction): string {
     case 'pnpmMissingDep': return 'dependency not found on the npm registry on the user machine'
     case 'registryVersionStale': return `requested version not available on the npm registry in use on the user machine`
     case 'registryAuth': return `npm registry rejected the credentials for this ${word} on the user machine`
+    case 'profileExclusive': return `the desktop profile is managed only by the Electron app, so the CLI refused the ${word}`
     case 'pnpmLinkedDirMissing': return 'dangling local (link:) dependency in the user profile'
     case 'fileLocked': return 'file locked by another process on the user machine'
     case 'accessDenied': return 'file write access denied on the user machine'
@@ -69,6 +71,8 @@ function reasonTitleOf(kind: FailureKind, action: FailureAction): string {
     case 'timeout': return `${word} timed out`
     case 'profileLock': return 'DSH profile is locked by another process'
     case 'pluginMissingDep': return 'a dependency of the plugin is not published on npm'
+    case 'dshTooOld': return 'the plugin requires a newer DSH than the host runs'
+    case 'localEnv': return `no plugin-side cause found — the failure points at the local environment for this ${word}`
     case 'hub': return `${word} failed (cause unclassified)`
     default: return `plugin ${word} failed`
   }
@@ -102,8 +106,16 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
         ? 'a dependency declared by the plugin is not published on the public npm registry (missing, removed, or never released); please publish or correct that dependency, or ship it with the plugin'
       : kind === 'network'
         ? 'network connectivity issue on the user side (DNS, proxy, firewall, or a blocked connection)'
+      : kind === 'localEnv'
+        ? 'no evidence of a plugin-side cause; the log shows local-environment signals (system error codes, certificates/proxy, or a broken local config), so this is reported for triage of the classifier only'
+      : kind === 'dshTooOld'
+        ? 'the plugin declares a minimum DSH version this host does not meet — upgrade DSH first (local environment issue)'
+      : kind === 'pnpmVirtualStore'
+        ? 'the profile node_modules was created with a different virtual-store-dir-max-length (or a different pnpm config), so pnpm refuses to reuse it (local environment issue)'
       : kind === 'registryAuth'
         ? 'the npm registry rejected the request with 401/403 — the configured registry needs credentials or blocks this network (local environment issue)'
+      : kind === 'profileExclusive'
+        ? 'the desktop profile can only be managed by the Electron app, and the install was attempted from an external CLI (local environment issue)'
         : kind === 'pluginPrepare'
           ? 'plugin prepare/build script failed during install (packaging/distribution issue)'
           : kind === 'pnpmIgnoredBuild'
@@ -166,8 +178,8 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
           `- OS: ${env.platform} ${env.arch} (${env.release})`,
           `- Profile: \`${env.profile}\``,
           `- DSH Home: \`${env.dshHome}\``,
-          // 完整安装日志所在（正文受 URL 长度限制只能带摘要，完整日志在 hub.log，可复制/附加给作者）
-          `- Full log: \`~/.dsh/profiles/${env.profile}/hub.log\` (paste or attach for the full output)`,
+          // 完整安装日志在通知中心（hub.log 只有任务开始/结束，没有 pnpm 输出，别让用户白附）
+          '- Full log: open the Hub notifications, select the failed record and press "Copy"',
         ]
         : []),
       // 该插件在插件市场的收录位置（详情页链接）
@@ -268,7 +280,7 @@ export function hubIssueUrl(
           `- OS: ${env.platform} ${env.arch} (${env.release})`,
           `- Profile: \`${env.profile}\``,
           `- DSH Home: \`${env.dshHome}\``,
-          `- Full log: \`~/.dsh/profiles/${env.profile}/hub.log\` (paste or attach for the full output)`,
+          '- Full log: open the Hub notifications, select the failed record and press "Copy"',
         ]
         : []),
       ...(repo !== 'unknown' ? [`- Catalog: [${pluginSiteUrl(repo)}](${pluginSiteUrl(repo)})`] : []),

package/src/server/http/diagnostics.ts

@@ -5,72 +5,15 @@
  *
  * 诊断路由：流式连通性自检、代理校验，以及与任务模块 /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.ts'
+import { hostDshVersion, toolVersion } from '../services/host-version.ts'
 import { gitLsRemote, probeUrl, systemProxy } from '../services/probe.ts'
 import { appendLog } from '../services/log.ts'
 import { readJsonBody, requireTrustedPost, sendJson, type WebRoute, type WebServerService } from './shared.ts'
 
-/** 宿主 dsh CLI 版本：优先直接跑 `dsh --version`（与 pnpm/npm/git 同款同步探测，1500ms 超时兜底，
- *  绝不挂起）；拿不到再退回从入口 `process.argv[1]` 向上找 package.json（dsh 不在 PATH 时兜底）。 */
-function hostDshVersion(): string | null {
-  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')) as { name?: string; version?: string }
-      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: string): string | null {
-  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: string, args: string[]): string | null {
-  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/src/server/services/host-version.ts

@@ -0,0 +1,69 @@
+/**
+ * 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: string): string | null {
+  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: string, args: string[]): string | null {
+  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: string | null = null
+
+/** 宿主 dsh 版本：优先 `dsh --version`；拿不到再从入口 `process.argv[1]` 向上找 package.json
+ *  （dsh 不在 PATH 时兜底）。探测成功即缓存，失败不缓存以便下次重试。 */
+export function hostDshVersion(): string | null {
+  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')) as { name?: string; version?: string }
+      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/src/server/services/install/dsh-compat.ts

@@ -0,0 +1,99 @@
+/**
+ * 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.ts'
+
+/** 从安装目标里取 npm 包名：`@scope/pkg@1.2.3` → `@scope/pkg`。
+ *  git / URL / 本地路径等非 npm 目标返回 null。 */
+export function npmNameOf(target: string): string | null {
+  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: string): [number, number, number] | null {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(raw)
+  return m === null ? null : [Number(m[1]), Number(m[2]), Number(m[3])]
+}
+
+function compareTriple(a: [number, number, number], b: [number, number, number]): number {
+  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: unknown): string | null {
+  const m = manifest as { engines?: Record<string, unknown>; peerDependencies?: Record<string, unknown> } | null
+  const ranges: string[] = []
+  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: string | null = null
+  let floorTriple: [number, number, number] | null = 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: string,
+  opts: { currentVersion?: string | null; fetchImpl?: typeof fetch; timeoutMs?: number; registry?: string } = {},
+): Promise<string | null> {
+  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: unknown
+  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/src/server/services/install/task-queue.ts

@@ -24,6 +24,7 @@ import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, p
 import { appendLog } from '../log.ts'
 import { commandOnPath, gitMissingDetail } from './preflight.ts'
 import { isTransportFailure, registryHost } from './registry-fallback.ts'
+import { dshTooOldMarker } from './dsh-compat.ts'
 import { OutputDecoder } from './decode-output.ts'
 
 /** 内存任务注册表，按任务 id 索引。 */
@@ -425,6 +426,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 as Record<string, string | undefined>).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 地址与全局安装不受此影响。
@@ -785,6 +792,26 @@ async function annotateRegistryMissing(result: InstallResult, options: {
   return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line }
 }
 
+/** 安装失败且插件声明的最低 DSH 版本高于当前宿主 → 注入 [dsh-too-old] 标记。
+ *  只在失败路径上发生：peer 不满足本身通常只是警告，装成功时不该冒这个提示。
+ *  超时也算失败 —— 旧宿主上插件可能卡在半兼容状态，这个信息同样有用。 */
+async function annotateDshTooOld(result: InstallResult, options: {
+  action: 'add' | 'remove' | 'update'
+  target: string
+  task?: InstallTask
+  globalNpm?: string[]
+  registries?: string[]
+}): Promise<InstallResult> {
+  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。
@@ -909,6 +936,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)
 }