dsh-plugin 1.4.2 → 1.4.4

package/package.json

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

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

@@ -18,7 +18,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 { classifyFailure, npmTooLowVersion, unreachableTargetOf } from '../../logic/failures.ts'
+import { classifyFailure, npmTooLowVersion, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
 import type { PendingRestart, QueueTask } from '../../hooks/useTaskQueue.ts'
 import { pluginIssueUrl, pluginSiteUrl } from '../../logic/urls.ts'
 import { CloseIcon } from '../ui/icons.tsx'
@@ -286,6 +286,12 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 给安装指引，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failNpmMissingHint'))
                     }
+                    if (kind === 'pnpmWorkspace') {
+                      // pnpm 拒绝把依赖装到 workspace 根目录（ERR_PNPM_ADDING_TO_ROOT）：宿主在 profile
+                      // 目录调 pnpm add 未声明在根操作，任何插件都会失败，不是插件问题 ——
+                      // 给 .npmrc 豁免指引，不引导提 Issue（dsh-plugin-hub#40）
+                      return h('div', { className: styles.failPrepareHint }, t('failPnpmWorkspaceHint'))
+                    }
                     if (kind === 'pnpmStore') {
                       // pnpm 存在但 store 大版本不匹配（ERR_PNPM_UNEXPECTED_STORE）：profile 目录旧依赖是
                       // 另一大版本 pnpm 装的，当前 pnpm 不认，任何插件装进该 profile 都会失败 ——
@@ -297,6 +303,16 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 本机 pnpm 策略不放行，装任何「刚发布/新来源」插件都撞墙 —— 给豁免指引，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failPnpmPolicyHint'))
                     }
+                    if (kind === 'pnpmUnusedPatch') {
+                      // profile 里留着指向旧版本 dsh-plugin 的补丁声明（ERR_PNPM_UNUSED_PATCH）：pnpm
+                      // 发现补丁没被用上就中止安装，任何插件都装不进来 —— 不引导提 Issue（#48）
+                      return h('div', { className: styles.failPrepareHint }, t('failPnpmUnusedPatchHint'))
+                    }
+                    if (kind === 'fileLocked') {
+                      // profile 里的文件被其他进程占用（Windows os error 32）：通常是宿主或杀毒软件
+                      // 持有句柄 —— 给出完全退出宿主的指引，不引导提 Issue（#47）
+                      return h('div', { className: styles.failPrepareHint }, t('failFileLockedHint'))
+                    }
                     if (kind === 'network') {
                       // 安装前预检 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
                       // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，
@@ -304,6 +320,9 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       return h('div', null, [
                         // 「无法访问 …」醒目行：精准告诉用户具体哪个地址连不上（消息里取不到地址就跳过这行）
                         (() => { const target = unreachableTargetOf(r.message); return target ? h('div', { className: styles.failNetworkTarget }, t('failNetworkTarget', { url: target })) : null })(),
+                        // registry 被指向内网/自定义源（tarball 从非官方源下载失败）：直接给出换源指引，
+                        // 否则用户外网是通的会困惑「为什么连不上」（dsh-plugin-hub#32）
+                        (() => { const host = registryHostOf(r.message); return host ? h('div', { className: styles.failPrepareHint }, t('failNetworkRegistryHint', { host })) : null })(),
                         h('div', { className: styles.failPrepareHint }, t('failNetworkHint')),
                         onRunDiagnostics ? h('button', {
                           className: styles.failDiagBtn,

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

@@ -16,7 +16,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 } from '../../logic/urls.ts'
-import { classifyFailure, npmTooLowVersion, unreachableTargetOf } from '../../logic/failures.ts'
+import { classifyFailure, npmTooLowVersion, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
 
 /** 完成结果视图：绿色对勾 + 标题/描述；
  *  needsRestart=true（插件需重启才生效）→ 「稍后重启 / 立即重启」按钮对，点稍后重启后
@@ -403,6 +403,11 @@ export function ErrorModal({ message, repo, kind, command, attempts, t, env, onC
               // 全局 npm 安装通道 spawn 的 npm 找不到（Win「'npm' is not recognized」/ POSIX
               // 「npm: command not found」/ spawn ENOENT）：本机 npm 未安装或不在 PATH —— 给安装指引，不引导提 Issue
               ? h('div', { className: styles.failPrepareHint }, t('failNpmMissingHint'))
+              : failureKind === 'pnpmWorkspace'
+              // pnpm 拒绝把依赖装到 workspace 根目录（ERR_PNPM_ADDING_TO_ROOT）：宿主在 profile 目录
+              // 调 pnpm add 时未声明在根操作，任何插件都会失败，不是插件问题 ——
+              // 给 .npmrc 豁免指引，不引导提 Issue（dsh-plugin-hub#40）
+              ? h('div', { className: styles.failPrepareHint }, t('failPnpmWorkspaceHint'))
               : failureKind === 'pnpmStore'
               // pnpm 存在但 store 大版本不匹配（ERR_PNPM_UNEXPECTED_STORE）：profile 目录旧依赖是
               // 另一大版本 pnpm 装的，当前 pnpm 不认，任何插件装进该 profile 都会失败 ——
@@ -412,6 +417,14 @@ export function ErrorModal({ message, repo, kind, command, attempts, t, env, onC
               // pnpm 11 供应链安全策略拦截（minimumReleaseAge 拒收发布太新的包 / untrusted origin）：
               // 本机 pnpm 策略不放行，装任何「刚发布/新来源」插件都撞墙 —— 给豁免指引，不引导提 Issue
               ? h('div', { className: styles.failPrepareHint }, t('failPnpmPolicyHint'))
+              : failureKind === 'pnpmUnusedPatch'
+              // profile 里留着指向旧版本 dsh-plugin 的补丁声明（ERR_PNPM_UNUSED_PATCH）：pnpm 发现
+              // 补丁没被用上就中止整次安装，任何插件都装不进来 —— 给删除条目的指引，不引导提 Issue（#48）
+              ? h('div', { className: styles.failPrepareHint }, t('failPnpmUnusedPatchHint'))
+              : failureKind === 'fileLocked'
+              // profile 里的文件被其他进程占用（Windows os error 32）：pnpm 无法替换被占用的文件，
+              // 通常是宿主或杀毒软件持有句柄 —— 给退出宿主的指引，不引导提 Issue（#47）
+              ? h('div', { className: styles.failPrepareHint }, t('failFileLockedHint'))
               : failureKind === 'network'
               // 安装前预检 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
               // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，
@@ -419,6 +432,9 @@ export function ErrorModal({ message, repo, kind, command, attempts, t, env, onC
               ? h('div', null, [
                 // 「无法访问 …」醒目行：精准告诉用户具体哪个地址连不上（消息里取不到地址就跳过这行）
                 (() => { const target = unreachableTargetOf(message); return target ? h('div', { className: styles.failNetworkTarget }, t('failNetworkTarget', { url: target })) : null })(),
+                // registry 被指向内网/自定义源（tarball 从非官方源下载失败）：直接给出换源指引，
+                // 否则用户外网是通的会困惑「为什么连不上」（dsh-plugin-hub#32）
+                (() => { const host = registryHostOf(message); return host ? h('div', { className: styles.failPrepareHint }, t('failNetworkRegistryHint', { host })) : null })(),
                 h('div', { className: styles.failPrepareHint }, t('failNetworkHint')),
                 onRunDiagnostics ? h('button', {
                   className: styles.failDiagBtn,

package/src/client/locales.ts

@@ -308,6 +308,7 @@ export const zh = {
   // 安装前连通性预检 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：本机网络或代理问题，不是插件问题，不引导提 Issue
   failNetworkHint: '安装前检测到网络不通：无法连接到安装源（可能是断网、DNS 解析失败、被防火墙拦截，或代理配置有问题）。这不是插件本身的问题 —— 请检查网络连接，或到「设置」里确认 HTTP 代理配置，再到「系统诊断」运行一次连通性检测，然后重试。',
   // 网络失败弹窗里的「无法访问 …」醒目行：直接告诉用户具体哪个地址连不上（{url} 为提取的不可达地址）
+  failNetworkRegistryHint: '你的 npm/pnpm 源（registry）被配置为 {host}，插件包需从该源下载但失败了。这通常是内网/自定义源没有同步该包（或需要内网认证）—— 请把 npm/pnpm 的 registry 指回官方源 https://registry.npmjs.org（或确认此源可访问该包）后重试。',
   failNetworkTarget: '无法访问 {url} —— 你的网络连接不通',
   // 「去系统诊断」直达按钮：网络不通提示下方的品牌实底按钮，跳到设置 → 系统诊断跑连通性检测
   failNetworkRunDiag: '去系统诊断检测网络',
@@ -316,6 +317,9 @@ export const zh = {
   failPnpmMissingHint: '安装器找到了 dsh，但系统里没有 pnpm 命令（dsh 用它来管理 profile 插件）。请先安装 pnpm（如 npm install -g pnpm），确认 pnpm 已加入 PATH 后重试。这不是插件本身的问题。',
   failNpmMissingHint: '系统找不到 npm 命令（npm 未安装或未加入系统 PATH），无法执行全局安装。请先安装 Node.js（自带 npm），确认 npm 已加入 PATH 后重试。这不是插件本身的问题。',
   failPnpmStoreHint: '安装器调用 pnpm 时报「store 位置不匹配」（ERR_PNPM_UNEXPECTED_STORE）：你的 profile 目录里旧插件依赖是用另一个大版本的 pnpm 生成的，当前 pnpm 出于安全不认旧目录，导致任何插件装进该 profile 都会失败。请删除该 profile 目录下的 node_modules 与 pnpm-lock.yaml（可先到「系统日志」或 ~/.dsh/profiles/<profile>/hub.log 查看完整报错），再重新安装。这不是插件本身的问题。',
+  failPnpmUnusedPatchHint: '安装器调用 pnpm 时报「有些补丁没有被使用」（ERR_PNPM_UNUSED_PATCH）：你的 profile 里留着一条指向旧版本 dsh-plugin 的补丁声明（例如 dsh-plugin@1.4.2），而本次安装解析到的版本已经不是它，pnpm 出于安全直接中止整次安装，因此任何插件都装不进来。这不是插件本身的问题——请在 profile 目录（~/.dsh/profiles/<profile>）的 pnpm-workspace.yaml（pnpm 11 及以上）或 package.json 的 pnpm.patchedDependencies（pnpm 10）里删除该 dsh-plugin 补丁条目后重试。',
+  failFileLockedHint: '安装过程中 pnpm 无法替换 profile 里的文件：有程序正占用着它（Windows 常见报错 os error 32「另一个程序正在使用此文件」）。通常是 DeepSeek Harness 自身或杀毒软件的实时扫描持有文件句柄。这不是插件本身的问题——请完全退出 DeepSeek Harness（Windows 可在任务管理器确认进程已结束，必要时临时关闭杀毒软件实时防护）后重试。',
+  failPnpmWorkspaceHint: '安装器调用 pnpm 时报「不能把依赖装到 workspace 根目录」（ERR_PNPM_ADDING_TO_ROOT）：你的 profile 目录被 pnpm 视为 workspace 根目录，而本次安装命令没有声明在根目录操作，pnpm 直接拒绝执行，因此任何插件装进来都会失败。这不是插件本身的问题——可在 profile 目录（~/.dsh/profiles/<profile>）的 .npmrc 里加一行 ignore-workspace-root-check=true 后重试，或把 DeepSeek Harness 升级到最新版再试。',
   failPnpmPolicyHint: '安装器调用 pnpm 时被其供应链安全策略拦截——装任何插件都会撞墙，不是插件本身的问题。分两种情况处理：① 提示「Minimum release age」（ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION）：包发布还不满 24 小时，pnpm 11 出于安全会拒收这种刚发布的新包。可在 pnpm 配置（pnpm-workspace.yaml）里加 minimumReleaseAge: 0 豁免，或等满 24 小时后重试。② 提示「untrusted origin」（ERR_PNPM_UNTRUSTED_ORIGIN）：依赖来源不被本机 pnpm 信任，通常是该 profile 里之前用 github: 或非官方 npm 源装过插件，锁文件记录了不受信任的来源。请删除该 profile 目录下的 node_modules 与 pnpm-lock.yaml 后重新安装（可先到「系统日志」或 ~/.dsh/profiles/<profile>/hub.log 查看完整报错）。',
   // 自定义安装三卡片入口的渠道名（报错/日志溯源：本次安装从哪个入口发起）
   installChannelNpm: 'NPM 包',
@@ -667,6 +671,7 @@ export const en = {
   // Pre-install connectivity probe / connection failure in the install log ([network] / git fetch timeout / DNS / TLS): a local network or proxy issue, not a plugin issue — no issue link
   failNetworkHint: 'The network could not be reached before install: the install source is unreachable (offline, DNS failure, firewall block, or a misconfigured proxy). This is not a problem with the plugin itself — please check your connection, confirm the HTTP proxy in Settings, run a connectivity check under System Diagnostics, then retry.',
   // Prominent "cannot reach …" line in the network-failure dialog: shows the exact unreachable address ({url})
+  failNetworkRegistryHint: 'Your npm/pnpm registry is set to {host}, and the package tarball could not be downloaded from it. This usually means a private/internal mirror that has not synced the package (or requires intranet auth) — point the registry back to https://registry.npmjs.org (or make sure this source can serve the package), then retry.',
   failNetworkTarget: 'Cannot reach {url} — your network connection is down',
   // Diagnostics shortcut button under the network-down hint: jumps to Settings → System Diagnostics
   failNetworkRunDiag: 'Run a network diagnostic',
@@ -675,6 +680,9 @@ export const en = {
   failPnpmMissingHint: 'The installer found dsh, but pnpm is missing on this machine (dsh uses it to manage profile plugins). Please install pnpm first (e.g. npm install -g pnpm), make sure it is on your PATH, then retry. This is not a problem with the plugin itself.',
   failNpmMissingHint: 'The npm command could not be found (npm is not installed or not on the system PATH), so a global install cannot run. Please install Node.js (which bundles npm), make sure npm is on your PATH, then retry. This is not a problem with the plugin itself.',
   failPnpmStoreHint: 'pnpm reported an unexpected store location (ERR_PNPM_UNEXPECTED_STORE): the profile directory was previously set up with a different major version of pnpm, and the current pnpm refuses to reuse it — no plugin can be installed into that profile. Delete node_modules and pnpm-lock.yaml under the profile directory (see System Logs or ~/.dsh/profiles/<profile>/hub.log for the full output), then reinstall. This is not a problem with the plugin itself.',
+  failPnpmUnusedPatchHint: 'pnpm reported that some patches were not used (ERR_PNPM_UNUSED_PATCH): your profile still holds a patch entry for an older dsh-plugin version (for example dsh-plugin@1.4.2), while this install resolved a different version, so pnpm aborts the whole install for safety — no plugin can be installed into that profile. This is not a problem with the plugin itself. Remove that dsh-plugin patch entry from pnpm-workspace.yaml (pnpm 11+) or from pnpm.patchedDependencies in package.json (pnpm 10) inside the profile directory (~/.dsh/profiles/<profile>), then retry.',
+  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.',
+  failPnpmWorkspaceHint: 'pnpm refused to add the dependency to the workspace root (ERR_PNPM_ADDING_TO_ROOT): the profile directory is treated as a pnpm workspace root, and this install command did not declare that it operates at the root, so pnpm rejected it outright — no plugin can be installed into that profile. This is not a problem with the plugin itself. Add `ignore-workspace-root-check=true` to the `.npmrc` inside the profile directory (~/.dsh/profiles/<profile>) and retry, or upgrade DeepSeek Harness and try again.',
   failPnpmPolicyHint: 'The installer was blocked by pnpm supply-chain security policy — every plugin install would hit the same wall, so this is not a problem with the plugin itself. Two cases: ① "Minimum release age" (ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION): the package was published less than 24 hours ago, and pnpm 11 refuses freshly-published packages for safety. Add minimumReleaseAge: 0 to your pnpm config (pnpm-workspace.yaml) to opt out, or wait until the 24 hours have passed and retry. ② "untrusted origin" (ERR_PNPM_UNTRUSTED_ORIGIN): a dependency source is not trusted by this machine, usually because plugins were previously installed via github: or a non-official npm registry, so the lockfile records an untrusted source. Delete node_modules and pnpm-lock.yaml under the profile directory (see System Logs or ~/.dsh/profiles/<profile>/hub.log for the full output), then reinstall.',
   // Custom install entry channel names (the three cards) — used in error/log traceability
   installChannelNpm: 'NPM package',

package/src/client/logic/failures.ts

@@ -151,7 +151,7 @@ export function removeNotification(id: number): NotificationRecord[] {
   return next
 }
 
-export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmPolicy' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'repo'
+export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'fileLocked' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'repo'
 
 /**
  * 失败归类，七态。无论底层机制如何（pnpm 白名单拦截 / 构建脚本被忽略 / prepare 失败），
@@ -184,15 +184,32 @@ export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissi
  *   当前 pnpm 不认，任何插件装进该 profile 都会失败；不是插件问题（dsh-plugin-hub#14：macOS 下
  *   `ERR_PNPM_UNEXPECTED_STORE` 被误归插件侧失败；dsh-plugin-hub#30：`ERR_PNPM_UNEXPECTED_VIRTUAL_STORE`
  *   漏判被误归插件侧失败）→ 提示清理 profile 依赖目录重建，不引导提 Issue
+ * - pnpmWorkspace：pnpm 在 workspace 根目录下拒绝安装（`ERR_PNPM_ADDING_TO_ROOT` —— 宿主在
+ *   profile 目录里调用 `pnpm add` 时未声明在 workspace 根操作）。profile 目录含
+ *   pnpm-workspace.yaml 即被 pnpm 视为 workspace 根，缺 `-w`/`--workspace-root` 就整条命令
+ *   被拒，任何插件都装不上，不是插件问题（dsh-plugin-hub#40）→ 提示在 profile 的 .npmrc 里
+ *   加 `ignore-workspace-root-check=true` 或升级宿主，不引导提 Issue
  * - pnpmPolicy：pnpm 11 的供应链安全策略拒绝安装（`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` /
  *   `Minimum release age` —— 锁文件里包的发布时间还不满 24 小时被拒；`untrusted origin` —— 依赖来源未被
  *   本机 pnpm 信任）。拦的是「刚发布的新包」与「未被信任的来源」，装任何新插件都会撞墙，不是
  *   插件问题（dsh-plugin-hub#15/#16：用户装官方 dsh-plugin 也被这两类策略拦下并误归插件侧失败）
  *   → 提示按子场景给解法（发布未满 24 小时 → `minimumReleaseAge: 0` 豁免或等满 24 小时；untrusted
  *   origin → 删除 profile 的 node_modules + pnpm-lock.yaml 清掉不受信任来源后重装），不引导提 Issue
- * - network：安装前连通性预检拦截（服务端 `[network]` 标记）或底层连接失败
- *   （ERR_PNPM_GIT_FETCH_FAILED / ETIMEDOUT / DNS 解析 / TLS 握手 / 代理拒绝）——
- *   是本机网络不通/被墙/代理有问题，不是插件问题 → 提示检查网络，不引导提 Issue
+ * - pnpmUnusedPatch：profile 里留着指向旧版本 dsh-plugin 的 patch 声明，本次安装解析到的版本
+ *   已经不是它（`ERR_PNPM_UNUSED_PATCH` / `The following patches were not used: dsh-plugin@1.4.2`）
+ *   —— pnpm 发现补丁没被用上即中止整次安装，任何插件都装不进来，不是插件问题
+ *   （dsh-plugin-hub#48：用户升级 dsh-plugin 后旧 patch 条目失配）→ 提示删掉该条目后重试，不引导提 Issue
+ * - fileLocked：pnpm 无法替换 profile 里被其他进程占用的文件（Windows `os error 32`
+ *   「另一个程序正在使用此文件」/ `EBUSY` / `resource busy or locked`）—— 通常是宿主进程或杀毒软件
+ *   实时扫描持有句柄，不是插件问题（dsh-plugin-hub#47）→ 提示完全退出宿主后重试，不引导提 Issue
+ * - network：安装前连通性预检拦截（服务端 `[network]` 标记）、底层连接失败
+ *   （ERR_PNPM_GIT_FETCH_FAILED / ETIMEDOUT / DNS 解析 / TLS 握手 / 代理拒绝），或
+ *   registry tarball 拉取失败（`fetch failed` / `GET …/-/…tgz error (n)` —— 常见于本机
+ *   npm/pnpm 的 registry 被指向内网/自定义源，该源取不到包），或界面请求压根没送达宿主服务
+ *   （浏览器 fetch 的 `Failed to fetch` —— 宿主未就绪/正在重启，或本地代理拦了回环地址；
+ *   dsh-plugin-hub#45：该消息此前落进 repo 兜底，被误报成「插件侧安装失败」）—— 是本机网络
+ *   不通/被墙/代理有问题/源配置异常，不是插件问题 → 提示检查网络，registry 指向自定义源时
+ *   给出换源指引，不引导提 Issue
  * - pnpmIgnoredBuild：插件自身或依赖的构建脚本被 pnpm 安全白名单（allowBuilds）默认拦截
  *   （`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` / `ERR_PNPM_IGNORED_BUILDS`）。只影响带安装期
  *   构建的插件，其他插件不受影响 —— 差异在插件的依赖/打包方式，属插件依赖/打包问题
@@ -240,11 +257,27 @@ export function classifyFailure(message: string): FailureKind {
   // 提示清理依赖目录用当前 pnpm 重建，不引导提 Issue。必须在 pnpmMissing 之后 ——
   // pnpm 在（能跑起来报错），不是「找不到命令」。
   if (/ERR_PNPM_UNEXPECTED_(VIRTUAL_)?STORE|Unexpected (virtual )?store location/i.test(message)) return 'pnpmStore'
+  // pnpm 拒绝在 workspace 根目录下安装（ERR_PNPM_ADDING_TO_ROOT）:profile 目录被视为
+  // pnpm workspace 根，宿主调 pnpm add 时没声明在根操作（缺 -w/--workspace-root），
+  // pnpm 直接整条命令拒绝 —— 本机 profile/宿主调用方式问题，任何插件都装不上，不是插件问题
+  // （dsh-plugin-hub#40：Win 下装 hub 本体，ADDING_TO_ROOT 被误归插件侧失败）
+  if (/ERR_PNPM_ADDING_TO_ROOT|add the dependency to the workspace root/i.test(message)) return 'pnpmWorkspace'
   // pnpm 供应链安全策略拦截（pnpm 11：minimumReleaseAge 拒收「刚发布」的包 /
   // untrusted origin 来源不受信任）：pnpm 在、也连得上，纯粹是本机策略不放行 ——
   // 装任何「新发布/非信任来源」的插件都会同样失败，不是插件问题（dsh-plugin-hub#15/#16）。
   // 必须在 pnpmIgnoredBuild 之前 —— 该策略优先于「构建脚本被白名单拦截」，且两者都不引导提 Issue。
   if (/ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION|Minimum release age|untrusted origin/i.test(message)) return 'pnpmPolicy'
+  // profile 里留着指向旧版本 dsh-plugin 的 patch 声明（ERR_PNPM_UNUSED_PATCH /
+  // `The following patches were not used: dsh-plugin@1.4.2`）：本机 pnpm 配置与本次解析到的版本
+  // 对不上，pnpm 出于安全直接中止整次安装 —— 任何插件都装不进来，不是插件问题
+  // （dsh-plugin-hub#48：用户升级 dsh-plugin 后旧 patch 条目失配）→ 提示删条目后重试，不引导提 Issue。
+  // 必须在兜底之前，否则被归成「插件侧失败」引导去提 Issue。
+  if (/ERR_PNPM_UNUSED_PATCH|patches were not used/i.test(message)) return 'pnpmUnusedPatch'
+  // profile 里的文件被其他进程占用，pnpm 无法替换（Windows `os error 32`
+  // 「另一个程序正在使用此文件，进程无法访问」/ EBUSY / resource busy or locked）——
+  // 通常是宿主进程或杀毒软件实时扫描持有句柄；`os error 32` 用 ASCII 特征，中文原文乱码也能命中
+  // （dsh-plugin-hub#47）→ 提示完全退出宿主后重试，不引导提 Issue
+  if (/os error 32|EBUSY|resource busy or locked|being used by another process/i.test(message)) return 'fileLocked'
   // 构建脚本被 pnpm 白名单（allowBuilds）拦截：插件的 prepare 脚本或依赖里的原生模块构建
   // 被默认拒绝（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED / ERR_PNPM_IGNORED_BUILDS）。
   // 这类错误出现即说明 pnpm 已成功 fetch 到 tarball（网络是通的），主因是插件构建脚本
@@ -253,11 +286,18 @@ export function classifyFailure(message: string): FailureKind {
   // 「你的网络不通」（graph-memory issues #82-#84：PREPARE_NOT_ALLOWED + 尾随超时）。
   if (/ERR_PNPM_IGNORED_BUILDS|Ignored build scripts:|ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED/i.test(message)) return 'pnpmIgnoredBuild'
   // 网络问题（服务端 [network] 标记，或安装日志里的连接失败特征：git fetch 失败、
-  // 连接超时/拒绝/重置、DNS 解析失败、TLS/SSL 握手失败）—— 是本机网络/代理问题，
-  // 不是插件问题。必须在 prepare/Command failed 判定之前：git fetch 失败常被
+  // 连接超时/拒绝/重置、DNS 解析失败、TLS/SSL 握手失败，或 registry tarball 拉取失败
+  // —— `fetch failed` / `GET https://…/-/…tgz error (n)` 是 pnpm 下载包文件时的网络层失败，
+  // 常见于本机 npm/pnpm registry 被指向内网/自定义源而取不到包）—— 是本机网络/代理/源
+  // 配置问题，不是插件问题。必须在 prepare/Command failed 判定之前：git fetch 失败常被
   // 外层包成 "Command failed: git fetch ..."，先按网络特征归类才不会误判成插件问题。
   // 404 类「目标不存在」不含这些特征，仍归 repo（那是仓库/包的问题）。
-  if (/\[network\]|ERR_PNPM_GIT_FETCH_FAILED|ETIMEDOUT|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH|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/i.test(message)) return 'network'
+  // 注意：fetch failed 只在 pnpm 拉取阶段出现；prepare/构建已跑起来（tarball 到手）的
+  // 插件问题不带此特征，不会误伤（graph-memory #82-#84 的 allowBuilds 拦截在上一分支先判）。
+  // `Failed to fetch` 是浏览器 fetch 的 TypeError（词序与 Node 的 fetch failed 相反）：界面
+  // 请求根本没送达宿主服务（宿主未就绪/正在重启、本地代理拦了回环地址）—— 同样不是插件问题
+  // （dsh-plugin-hub#45：此前不被识别，落进 repo 兜底并自动提了「插件侧安装失败」）。
+  if (/\[network\]|ERR_PNPM_GIT_FETCH_FAILED|ETIMEDOUT|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH|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 \(\d+\)/i.test(message)) return 'network'
   // 装后校验拦截（服务端 verifyInstalledEntry 标记）：入口文件缺失 = git 分发缺构建产物，
   // 与 pluginPrepare 同类（插件打包/分发问题），引导去仓库提 Issue
   if (/\[packaging\]|entry file missing/i.test(message)) return 'pluginPrepare'
@@ -343,3 +383,28 @@ export function unreachableTargetOf(message: string): string | null {
   const url = message.match(/https?:\/\/[^\s'"`<>（）()]+/)
   return url ? url[0].replace(/[.,;:）)\]]+$/, '') : null
 }
+
+/** npm registry 的官方/常见公开镜像主机名：tarball 从这里下载属正常配置，
+ * 失败按「网络不通」提示即可，不需要额外的换源指引。 */
+const PUBLIC_REGISTRY_HOSTS = new Set([
+  'registry.npmjs.org',
+  'registry.yarnpkg.com',
+  'registry.npmmirror.com',
+  'mirrors.cloud.tencent.com',
+  'mirrors.huaweicloud.com',
+])
+
+/**
+ * 网络类失败消息里，判断是否「npm/pnpm 的 registry 被指向了内网/自定义源导致拉包失败」。
+ * pnpm 下载包文件的 URL 形如 `<registry>/<pkg>/-/<pkg>-<ver>.tgz`（路径含 `/-/`）；
+ * 若该 tarball 的主机不属于官方/常见公开镜像，说明本机 registry 被配成了私有/内网源
+ * （如公司 Artifactory）—— 常因源未同步该包、需内网认证或网络策略拦截而失败（dsh-plugin-hub#32）。
+ * 返回该主机名供前端给出「检查 registry 配置」的精准提示；官方/公开源或提取不到返回 null，
+ * 调用方按通用网络问题提示即可。
+ */
+export function registryHostOf(message: string): string | null {
+  const m = message.match(/https?:\/\/([^/\s]+)\/[^\s'"`<>]*\/-\/[^\s'"`<>]+/)
+  if (!m) return null
+  const host = m[1].replace(/:\d+$/, '')
+  return PUBLIC_REGISTRY_HOSTS.has(host) ? null : host
+}

package/src/client/logic/renderMarkdown.ts

@@ -33,11 +33,11 @@ function inline(s: string): string {
     return `\u0000${codeSpans.length - 1}\u0000`
   })
   // 图片 ![alt](url)：仅放行 http(s)，用于展示反馈群二维码等；limited by CSS
-  // 文件名为 dsh-plugin-user-group-qr- 前缀的视为用户反馈群二维码，固定 100×100 不撑破弹窗。
+  // 文件名为 dsh-plugin-user-group-qr 前缀的视为用户反馈群二维码，固定 100×100 不撑破弹窗。
   out = out.replace(/!\[([^\]]*)\]\(([^)\s]+)\)/g, (m, alt, url) => {
     const src = String(url)
     if (!/^https?:\/\//i.test(src) || /[\u0000]/.test(src)) return m
-    if (/\/dsh-plugin-user-group-qr-[^/]*$/i.test(src)) {
+    if (/\/dsh-plugin-user-group-qr[^/]*$/i.test(src)) {
       return `<img src="${src}" alt="${String(alt)}" width="100" height="100" loading="lazy">`
     }
     return `<img src="${src}" alt="${String(alt)}" loading="lazy">`

package/src/client/logic/urls.ts

@@ -49,7 +49,10 @@ function reasonTitleOf(kind: FailureKind): 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 'pnpmWorkspace': return 'pnpm workspace-root check blocked the install on the user machine'
     case 'pnpmPolicy': return 'pnpm supply-chain policy blocked the install on the user machine'
+    case 'pnpmUnusedPatch': return 'stale pnpm patch entry on the user machine'
+    case 'fileLocked': return 'file locked by another process on the user machine'
     case 'pnpmIgnoredBuild': return 'build scripts blocked by pnpm allowlist'
     case 'pluginPrepare': return 'plugin distribution incomplete'
     case 'network': return 'network failure on the user side'
@@ -82,8 +85,12 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
           : kind === 'pnpmIgnoredBuild'
             ? 'plugin depends on a native module whose build script pnpm blocks by default (use a prebuilt variant)'
             : kind === 'pnpmPolicy'
-              ? 'the pnpm supply-chain policy on the user machine blocked the install (minimum release age for freshly published packages / untrusted origin)'
-              : 'plugin-side install failure'
+                ? 'the pnpm supply-chain policy on the user machine blocked the install (minimum release age for freshly published packages / untrusted origin)'
+                : kind === 'pnpmUnusedPatch'
+                  ? 'the profile keeps a pnpm patch entry for an older dsh-plugin version, so pnpm aborted the install (local config issue)'
+                  : kind === 'fileLocked'
+                    ? 'a file in the profile is locked by another process on the user machine (local environment issue)'
+                    : 'plugin-side install failure'
   const code = coreErrorCode(message)
   // 按给定核心摘要预算构建完整预填 URL（含 URL 编码）；预算可调，供超长时逐档缩小
   const build = (coreChars: number): string => {