dsh-plugin 1.3.6 → 1.3.8

package/src/client/components/views/SettingsView.tsx

@@ -15,7 +15,7 @@
  *   Diagnostics       — live connectivity probe + environment snapshot
  *   Logs              — system log viewer + storage location
  */
-import { createElement as h, useState } from 'react'
+import { createElement as h, useEffect, useRef, useState } from 'react'
 import type { ChangeEvent, MouseEvent, ReactNode } from 'react'
 import styles from '../../styles/SettingsView.module.css'
 import dropdownStyles from '../../styles/Dropdown.module.css'
@@ -30,7 +30,8 @@ import {
 import type { EnvInfo, Translate } from '../../types.ts'
 import type { HubSettings } from '../../hooks/useSettings.ts'
 
-type SettingsSection = 'updates' | 'security' | 'diagnostics' | 'logs' | 'reset'
+/** 设置分组导航 key：顺序即展示顺序。导出供外部（如错误弹窗「去系统诊断」）跳转指定分组。 */
+export type SettingsSection = 'updates' | 'security' | 'diagnostics' | 'logs' | 'reset'
 
 /** npm 镜像源预设：空串 = 未配置（跟随用户本机 npm 配置，本插件不注入任何 registry）。
  *  只提供常见国内顶级镜像下拉，不做自定义输入 —— 想用其它镜像直接在 ~/.npmrc 配置即可。 */
@@ -67,20 +68,70 @@ function SettingRow({ title, desc, children, stack = false }: {
   )
 }
 
-export function SettingsView({ t, settings, update, reset, env, onCopy }: {
+export function SettingsView({ t, settings, update, reset, env, onCopy, openSection, onConsumedOpenSection }: {
   t: Translate
   settings: HubSettings
   update: (patch: Partial<HubSettings>) => void
   reset: () => void
   env: EnvInfo | null
   onCopy: (text: string) => void
+  /** 外部跳转信号（如错误弹窗「去系统诊断」）：非空时切到对应分组，消费后通过 onConsumedOpenSection 清空 */
+  openSection?: SettingsSection | null
+  onConsumedOpenSection?: () => void
 }) {
   /** 当前激活的分组：左侧导航点击切换，右侧只渲染这一组 */
   const [section, setSection] = useState<SettingsSection>('updates')
   /** 恢复默认确认弹窗：点按钮先弹窗询问，确认后才真正 reset（不做两段式按钮） */
   const [resetConfirm, setResetConfirm] = useState(false)
 
-  const onProxyChange = (e: ChangeEvent<HTMLInputElement>) => update({ proxy: e.target.value })
+  // 外部跳转（错误弹窗「去系统诊断」→ 设置 → 系统诊断）：切到对应分组并清空信号，避免下次进入设置被强制带跳
+  useEffect(() => {
+    if (!openSection) return
+    setSection(openSection)
+    onConsumedOpenSection?.()
+  }, [openSection, onConsumedOpenSection])
+
+  // —— HTTP 代理连通性：输入停笔后防抖实时探测（服务端 /proxy-check 用该代理打 github.com）。
+  // 结果只作提示、绝不阻断保存 —— 用户可能是先填地址后开代理，保存后再去开代理完全合法。
+  const [proxyProbe, setProxyProbe] = useState<'idle' | 'checking' | 'ok' | 'fail'>('idle')
+  const proxyProbeTimer = useRef<number | null>(null)
+  const proxyProbeSeq = useRef(0)
+  // 卸载时清掉未触发的防抖计时器，避免卸载后 setState
+  useEffect(() => () => {
+    if (proxyProbeTimer.current !== null) window.clearTimeout(proxyProbeTimer.current)
+    proxyProbeSeq.current += 1
+  }, [])
+  // 设置被外部重置（恢复默认/清空代理）时同步清掉探测状态，避免残留过期的「不通」提示
+  useEffect(() => {
+    if (settings.proxy === '') setProxyProbe('idle')
+  }, [settings.proxy])
+
+  const probeProxyNow = (value: string) => {
+    const v = value.trim()
+    if (v === '') { setProxyProbe('idle'); return }
+    const seq = ++proxyProbeSeq.current
+    setProxyProbe('checking')
+    void fetch('/dsh-plugin-hub/proxy-check', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ proxy: v }),
+      cache: 'no-store',
+    }).then((res) => res.json())
+      .then((data: { ok?: boolean }) => {
+        if (seq !== proxyProbeSeq.current) return
+        setProxyProbe(data.ok ? 'ok' : 'fail')
+      })
+      .catch(() => { if (seq === proxyProbeSeq.current) setProxyProbe('fail') })
+  }
+
+  const onProxyChange = (e: ChangeEvent<HTMLInputElement>) => {
+    const value = e.target.value
+    // 保存照常：留空直连、填了就走该代理（先填后开代理也允许，仅提示不通）
+    update({ proxy: value })
+    if (proxyProbeTimer.current !== null) window.clearTimeout(proxyProbeTimer.current)
+    // 停笔 700ms 再探测，避免每敲一个字符都发请求
+    proxyProbeTimer.current = window.setTimeout(() => probeProxyNow(value), 700)
+  }
   const onMirrorChange = (value: string) => update({ npmRegistry: value })
 
   /** 每个分组的页面副标题（导航标题之上再补一句说明，保持桌面设置质感） */
@@ -120,19 +171,29 @@ export function SettingsView({ t, settings, update, reset, env, onCopy }: {
         className: `${styles.controlDropdown} ${dropdownStyles.dropdownFill}`,
       }),
     }),
-    // 代理地址：文本框独占一行，整行输入，便于粘贴长代理地址
+    // 代理地址：文本框独占一行，整行输入，便于粘贴长代理地址；停笔后实时探测连通性，
+    // 不通仅提示（可保存）—— 用户可能先填地址后开代理
     h(SettingRow, {
       title: t('settingsProxy'),
       desc: t('settingsProxyDesc'),
       stack: true,
-      children: h('input', {
-        className: styles.textInput,
-        type: 'text',
-        value: settings.proxy,
-        placeholder: 'http://127.0.0.1:7890',
-        spellCheck: false,
-        onChange: onProxyChange,
-      }),
+      children: h('div', { className: styles.proxyControl },
+        h('input', {
+          className: styles.textInput,
+          type: 'text',
+          value: settings.proxy,
+          placeholder: 'http://127.0.0.1:7890',
+          spellCheck: false,
+          onChange: onProxyChange,
+        }),
+        proxyProbe === 'checking'
+          ? h('div', { className: styles.proxyHint }, t('proxyCheckChecking'))
+          : proxyProbe === 'ok'
+            ? h('div', { className: `${styles.proxyHint} ${styles.proxyHintOk}` }, t('proxyCheckOk'))
+            : proxyProbe === 'fail'
+              ? h('div', { className: `${styles.proxyHint} ${styles.proxyHintFail}` }, t('proxyCheckFail'))
+              : null,
+      ),
     }),
   )
 
@@ -172,7 +233,7 @@ export function SettingsView({ t, settings, update, reset, env, onCopy }: {
 
   const diagnosticsCard = h('div', { className: styles.card },
     // 系统版本（最顶部）+ 通道状态列表：进入页面自动探测一轮，整行可点击重测单项，实时反馈
-    h(DiagnosticsView, { t, env, onCopy }),
+    h(DiagnosticsView, { t, env, proxy: settings.proxy, onCopy }),
   )
 
   const logsCard = h('div', { className: styles.card },

package/src/client/hooks/useTaskQueue.ts

@@ -10,7 +10,7 @@
  * uninstall, cancel) plus the modal task lookups used by the dialogs.
  */
 import { useEffect, useRef, useState } from 'react'
-import type { HubPlugin, Translate } from '../types.ts'
+import type { HubPlugin, LocaleId, Translate } from '../types.ts'
 import { installCommandOf, installTargetOf, repoFromInstallTarget } from '../logic/install-command.ts'
 import type { InstalledItem } from '../logic/installed.ts'
 
@@ -64,6 +64,8 @@ export interface PendingRestart {
 
 export interface TaskQueueOptions {
   t: Translate
+  /** 界面语言（zh/en）：随安装请求带给服务端，网络预检等错误消息按用户语言提示 */
+  langKey?: LocaleId
   refreshInstalled: () => void
   /** 任务成功完成：viaModal 表示任务对应当前打开弹窗（弹窗切结果视图），否则走 Toast；repo 供成功通知记录；
    *  needsRestart 表示该任务完成后是否仍需宿主重启（结果视图据此给「重启 / 仅完成」）。
@@ -89,7 +91,7 @@ export interface TaskQueueOptions {
 
 export function useTaskQueue(opts: TaskQueueOptions) {
   const {
-    t, refreshInstalled, onInstallDone, onUninstallDone, onError,
+    t, langKey, refreshInstalled, onInstallDone, onUninstallDone, onError,
     installPlugin, installCustomTarget, installGlobalTarget, uninstallPlugin, uninstallName, installedName, resolvePending,
   } = opts
   const [queue, setQueue] = useState<QueueTask[]>([])
@@ -442,6 +444,8 @@ export function useTaskQueue(opts: TaskQueueOptions) {
           display: input.repo,
           source: input.source,
           mode: input.update ? 'update' : undefined,
+          // 界面语言带给服务端：网络预检等错误消息按用户当前语言返回（中文界面给中文，英文界面给英文）
+          ...(langKey ? { lang: langKey } : {}),
           ...(input.globalNpm && input.globalNpm.length > 0 ? { globalNpm: input.globalNpm } : {}),
         }),
         signal: controller.signal,

package/src/client/locales.ts

@@ -25,7 +25,9 @@ export const zh = {
   fork: 'Fork',
   loading: '正在加载插件数据…',
   failed: '插件数据加载失败',
-  failedDesc: '请稍后重试，或点击右上角按钮在浏览器中打开插件中心。',
+  // 目录拉不出来时的精准提示：按「是否配置了代理」区分，引导排查网络 / 代理
+  failedDescNoProxy: '你的网络似乎不通，无法获取插件目录数据。请检查网络连接后重试；或点击右上角按钮在浏览器中打开插件中心。',
+  failedDescProxy: '你的网络似乎不通，或设置里的 HTTP 代理地址不可达，无法获取插件目录数据。请检查代理设置与网络连接后重试；或点击右上角按钮在浏览器中打开插件中心。',
   retry: '重试',
   install: '安装',
   // AI 识别可能需要命令行辅助的插件（webInstallable=false）：仍可尝试一键安装，失败时复制命令去 dsh 终端
@@ -110,6 +112,10 @@ export const zh = {
   settingsCheckOnStartDesc: '打开插件中心时检查已安装插件是否有新版，发现更新会提示',
   settingsProxy: 'HTTP 代理',
   settingsProxyDesc: 'npm / git / 目录数据请求统一走该代理；留空直连',
+  // 代理连通性实时探测：输入停笔后提示检测结果（不通仍可保存，先填地址后开代理也合法）
+  proxyCheckChecking: '正在测试该代理地址…',
+  proxyCheckOk: '测试可达，安装与目录请求将统一走该代理',
+  proxyCheckFail: '此地址测试不通，仍可保存；请确认代理已开启、地址与端口无误',
   settingsMirror: 'npm 镜像源',
   settingsMirrorDesc: '默认跟随本机 npm 配置；官方源慢可换国内镜像',
   mirrorNone: '未配置（跟随本机 npm 配置）',
@@ -186,6 +192,7 @@ export const zh = {
   diagNpmUnset: '未配置（跟随本机 npm 配置）',
   diagGithub: 'GitHub',
   diagCatalog: '目录站点',
+  diagProxy: 'HTTP 代理',
   diagOk: 'OK',
   diagChecking: '检测中…',
   diagIdle: '未检测',
@@ -294,10 +301,16 @@ export const zh = {
   // 安装前预检 / 装后校验拦截（[packaging]）：git 分发缺构建产物、入口文件不存在 = 插件未适配官方默认安装方式
   failPackagingHint: '该插件不支持官方默认安装方式：其 git 分发缺少构建产物（package.json 声明的入口文件在仓库中不存在），说明作者未适配官方安装流程。请到作者仓库提交 Issue 反馈，请其提交构建产物或发布 npm 版。',
   // 原生依赖构建脚本被 pnpm 默认拦截（如 node-pty 的 ERR_PNPM_IGNORED_BUILDS）：只影响带原生模块的插件，属插件依赖打包问题，应提 Issue
-  failIgnoredBuild: '该插件依赖了需要编译的原生模块（如 node-pty），pnpm 默认拦截这类构建脚本导致安装失败 —— 其他插件不受影响，属该插件的依赖/打包问题。建议向作者仓库一键反馈，请作者改用预编译版本（如 node-pty-prebuilt-multiarch）。',
+  failIgnoredBuild: '该插件或其依赖需要执行构建脚本，被 pnpm 的安全白名单（allowBuilds）默认拦截导致安装失败（如原生模块 node-pty、或 git 安装时插件的 prepare 脚本）—— 其他插件不受影响，属该插件的依赖/打包问题。建议向作者仓库一键反馈，请作者改用预编译版本（如 node-pty-prebuilt-multiarch）或移除安装期构建。',
   // npm arborist 内部崩溃（edgesOut）＋ 本机 npm 版本过低：npm 自身已知缺陷，不是插件问题，升级 npm 即可
   failNpmTooLow: '怀疑本机 npm 版本过低：npm 解析插件依赖时内部崩溃（这是 npm 自身的已知缺陷，不是插件问题）。请升级 npm 后重试：npm install -g npm@latest',
   failNpmTooLowV: '本机 npm 版本过低（当前 v{v}）：npm 解析插件依赖时内部崩溃（这是 npm 自身的已知缺陷，不是插件问题）。请升级 npm 后重试：npm install -g npm@latest',
+  // 安装前连通性预检 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：本机网络或代理问题，不是插件问题，不引导提 Issue
+  failNetworkHint: '安装前检测到网络不通：无法连接到安装源（可能是断网、DNS 解析失败、被防火墙拦截，或代理配置有问题）。这不是插件本身的问题 —— 请检查网络连接，或到「设置」里确认 HTTP 代理配置，再到「系统诊断」运行一次连通性检测，然后重试。',
+  // 网络失败弹窗里的「无法访问 …」醒目行：直接告诉用户具体哪个地址连不上（{url} 为提取的不可达地址）
+  failNetworkTarget: '无法访问 {url} —— 你的网络连接不通',
+  // 「去系统诊断」直达按钮：网络不通提示下方的品牌实底按钮，跳到设置 → 系统诊断跑连通性检测
+  failNetworkRunDiag: '去系统诊断检测网络',
   reportIssue: '去插件仓库提交 Issue',
   detail: '打开详情',
   noResult: '没有找到匹配的插件',
@@ -357,7 +370,9 @@ export const en = {
   fork: 'Fork',
   loading: 'Loading plugin data…',
   failed: 'Failed to load plugin data',
-  failedDesc: 'Please retry, or open the hub in your browser with the button above.',
+  // Precise hints when the catalog cannot load: distinguished by whether a proxy is configured
+  failedDescNoProxy: 'Your network seems unreachable, so the plugin catalog could not be loaded. Please check your connection and retry; or open the hub in your browser with the button above.',
+  failedDescProxy: 'Your network seems unreachable, or the HTTP proxy in Settings is unreachable, so the plugin catalog could not be loaded. Please check the proxy address and your connection, then retry; or open the hub in your browser with the button above.',
   retry: 'Retry',
   install: 'Install',
   // AI-flagged plugins that may need command-line help (webInstallable=false): one-click install still allowed,
@@ -445,6 +460,11 @@ export const en = {
   settingsAutoInstallDesc: 'Install detected updates in the background without asking (a host restart applies them)',
   settingsProxy: 'HTTP proxy',
   settingsProxyDesc: 'Route npm, git and catalog requests through this proxy; leave empty to connect directly',
+  // Live proxy reachability probe: reported after the user stops typing (an unreachable
+  // address can still be saved — users may fill it in before actually starting the proxy)
+  proxyCheckChecking: 'Testing this proxy address…',
+  proxyCheckOk: 'Reachable — installs and catalog requests will route through it',
+  proxyCheckFail: 'Unreachable, but you can still save it; make sure the proxy is running and the address and port are correct',
   settingsMirror: 'npm mirror',
   settingsMirrorDesc: 'Unset by default — follows local npm config; pick a domestic mirror if slow',
   mirrorNone: 'Unset (follow local npm config)',
@@ -521,6 +541,7 @@ export const en = {
   diagNpmUnset: 'Unset (follow local npm config)',
   diagGithub: 'GitHub',
   diagCatalog: 'Catalog site',
+  diagProxy: 'HTTP proxy',
   diagOk: 'OK',
   diagChecking: 'Checking…',
   diagIdle: 'Not checked',
@@ -628,9 +649,15 @@ export const en = {
   // Pre-install / post-install guard hit ([packaging]): git distribution lacks build output, entry file missing = not adapted to the official default install method
   failPackagingHint: 'This plugin does not support the official default install method: its git distribution lacks the build output (the entry file declared in package.json is not in the repository), so it has not been adapted to the official install flow. Please file an Issue on the author\'s repo asking for committed build output or an npm release.',
   // native-module build scripts ignored by pnpm by default (e.g. node-pty, ERR_PNPM_IGNORED_BUILDS): only affects plugins with native deps — a dependency/packaging issue of the plugin itself, file an issue
-  failIgnoredBuild: 'This plugin depends on a native module (e.g. node-pty) whose build script pnpm blocks by default, so the install fails — other plugins are unaffected. This is a dependency/packaging issue of the plugin itself. Please report it to the author repository and ask the author to switch to a prebuilt variant (e.g. node-pty-prebuilt-multiarch).',
+  failIgnoredBuild: 'This plugin (or its dependencies) needs to run build scripts, which pnpm blocks by default via its allowBuilds allowlist, so the install fails (e.g. native modules like node-pty, or the plugin\'s own prepare script on git installs) — other plugins are unaffected. This is a dependency/packaging issue of the plugin itself. Please report it to the author repository and ask the author to ship a prebuilt variant (e.g. node-pty-prebuilt-multiarch) or drop install-time builds.',
   failNpmTooLow: 'Your local npm may be too old: npm crashed internally while resolving the plugin\'s dependencies (a known npm bug — not a plugin issue). Please upgrade npm and retry: npm install -g npm@latest',
   failNpmTooLowV: 'Your local npm is too old (v{v}): npm crashed internally while resolving the plugin\'s dependencies (a known npm bug — not a plugin issue). Please upgrade npm and retry: npm install -g npm@latest',
+  // 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})
+  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',
   reportIssue: 'Report an Issue to the plugin repo',
   detail: 'Open details',
   noResult: 'No plugins match your search',

package/src/client/logic/failures.ts

@@ -151,18 +151,22 @@ export function removeNotification(id: number): NotificationRecord[] {
   return next
 }
 
-export type FailureKind = 'npmTooOld' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'repo'
+export type FailureKind = 'npmTooOld' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'repo'
 
 /**
- * 失败归类，四态。无论底层机制如何（pnpm 白名单拦截 / 构建脚本被忽略 / prepare 失败），
+ * 失败归类，五态。无论底层机制如何（pnpm 白名单拦截 / 构建脚本被忽略 / prepare 失败），
  * 对用户而言结果都一样 —— 当前安装通道（npm 或 git）装不上，就是插件分发/依赖的问题，
- * 一律引导提 Issue；唯一例外是本机 npm 自身版本过低导致的内部崩溃（见 npmTooOld）：
+ * 一律引导提 Issue；唯一的两个例外是本机环境问题（npm 版本过低 / 网络不通）：
  * - npmTooOld：失败输出含 npm arborist 的 `edgesOut` 崩溃特征（build-ideal-tree.js 解 peer 依赖时
  *   内部抛错，npm 11.6.0 前必现的已知缺陷，npm/cli#8261、#9787），或服务端已核实本机版本低于
  *   阈值并打了 `[npm-too-low]` 标记 —— 是本机 npm 版本过低/自身缺陷，不是插件问题 → 引导升级 npm
- * - pnpmIgnoredBuild：插件依赖里的原生模块构建脚本被 pnpm 默认拦截（如 node-pty，
- *   `ERR_PNPM_IGNORED_BUILDS`）。只影响带原生模块的插件，其他插件不受影响 —— 差异在
- *   插件的依赖选择，属插件依赖/打包问题 → 引导去仓库提 Issue（建议改用预编译版本）
+ * - network：安装前连通性预检拦截（服务端 `[network]` 标记）或底层连接失败
+ *   （ERR_PNPM_GIT_FETCH_FAILED / ETIMEDOUT / DNS 解析 / TLS 握手 / 代理拒绝）——
+ *   是本机网络不通/被墙/代理有问题，不是插件问题 → 提示检查网络，不引导提 Issue
+ * - pnpmIgnoredBuild：插件自身或依赖的构建脚本被 pnpm 安全白名单（allowBuilds）默认拦截
+ *   （`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` / `ERR_PNPM_IGNORED_BUILDS`）。只影响带安装期
+ *   构建的插件，其他插件不受影响 —— 差异在插件的依赖/打包方式，属插件依赖/打包问题
+ *   → 引导去仓库提 Issue（建议改用预编译版本或关闭安装期构建）
  * - pluginPrepare：插件的 prepare/构建脚本实际执行失败（git tarball 常因缺失子模块或
  *   构建产物导致）—— 属插件打包/分发问题，应引导去仓库提 Issue
  * - repo：其余失败（含 git prepare 被 pnpm 白名单拦截等），默认按插件仓库问题引导提 Issue
@@ -172,12 +176,22 @@ export function classifyFailure(message: string): FailureKind {
   // 不是插件问题 —— 必须最先判，否则该报错会被外层 ERR_PNPM_PREPARE_PACKAGE 吞成
   // 「插件打包分发问题」，误导用户去提 Issue
   if (/\[npm-too-low\]|edgesOut/i.test(message)) return 'npmTooOld'
+  // 构建脚本被 pnpm 白名单（allowBuilds）拦截：插件的 prepare 脚本或依赖里的原生模块构建
+  // 被默认拒绝（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED / ERR_PNPM_IGNORED_BUILDS）。
+  // 这类错误出现即说明 pnpm 已成功 fetch 到 tarball（网络是通的），主因是插件构建脚本
+  // 被拦 —— 必须在 network 判定之前：日志尾部常混着重试残留的连接失败特征
+  // （ETIMEDOUT / Failed to connect 等），若先判网络会把「插件分发问题」误报成
+  // 「你的网络不通」（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 失败常被
+  // 外层包成 "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'
   // 装后校验拦截（服务端 verifyInstalledEntry 标记）：入口文件缺失 = git 分发缺构建产物，
   // 与 pluginPrepare 同类（插件打包/分发问题），引导去仓库提 Issue
   if (/\[packaging\]|entry file missing/i.test(message)) return 'pluginPrepare'
-  // 原生模块构建被忽略（IGNORED_BUILDS）要在 prepare 判定之前：dsh 尾部固定提示语带
-  // allowBuilds/pnpm-workspace.yaml，不能据此把插件自身问题误判成通用失败
-  if (/ERR_PNPM_IGNORED_BUILDS|Ignored build scripts:/i.test(message)) return 'pnpmIgnoredBuild'
   // 再判 prepare 实际执行失败：只有构建脚本真的跑挂了才是插件问题
   if (/ERR_PNPM_PREPARE_PACKAGE|ELIFECYCLE|Command failed|prepare-guard/i.test(message)) return 'pluginPrepare'
   // 其余失败（含 git prepare 被 pnpm 白名单拦截）：当前通道装不上 = 插件分发/依赖的问题，一律提 Issue
@@ -237,3 +251,18 @@ export function coreErrorCode(message: string): string | null {
   const m = message.match(/\[?ERR_[A-Z_]+\]?/)
   return m ? m[0].replace(/^\[|\]$/g, '') : null
 }
+
+/**
+ * 从网络类失败消息里提取「具体连不上的地址」，供弹窗精准提示（你的网络无法访问什么）。
+ * 优先取服务端 [network] 预检消息括号里的探测地址（中文「（…）」/ 英文「(…)」），
+ * 否则取消息里出现的第一个 URL（git fetch 的仓库地址、registry 域名等）。
+ * 提取不到返回 null —— 调用方据此跳过地址行。
+ */
+export function unreachableTargetOf(message: string): string | null {
+  // [network] 预检消息：`无法连接到 GitHub（https://github.com/）` / `cannot reach the npm registry (https://registry.npmjs.org/)`
+  const paren = message.match(/[（(](https?:\/\/[^\s'"`<>（)+]+)[)）]/)
+  if (paren) return paren[1]
+  // 其余网络失败（git fetch / npm 连接失败）：取第一个 URL，去掉行尾标点
+  const url = message.match(/https?:\/\/[^\s'"`<>（）()]+/)
+  return url ? url[0].replace(/[.,;:）)\]]+$/, '') : null
+}

package/src/client/logic/renderMarkdown.ts

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

@@ -10,6 +10,7 @@
 import type { EnvInfo, HubPlugin, LocaleId } from '../types.ts'
 import { GITHUB_URL, PLUGIN_VERSION, SITE_URL } from './constants.ts'
 import { MAX_CORE_CHARS, classifyFailure, coreErrorCode, summarizeError } from './failures.ts'
+import type { FailureKind } from './failures.ts'
 
 /** dsh-plugin.org 中文页挂在 /zh/ 前缀下，英文在根路径。 */
 export function langPathOf(lang: LocaleId): string {
@@ -33,18 +34,22 @@ export function pluginSiteUrl(repo: string): string {
   return `${SITE_URL}plugins/${repo}`
 }
 
-/** 根据实际执行的命令判定失败动作标签（安装/更新/卸载）：
- *  命令形如 `dsh plugin --profile web add|update|remove <target>`，
- *  出现 remove/update 动词即对应归类，其余（add、全局 npm 命令、未知）一律算安装。 */
-function actionLabelOf(command: string | undefined): string {
-  if (command && /\s+remove\s+/i.test(command)) return 'Remove'
-  if (command && /\s+update\s+/i.test(command)) return 'Update'
-  return 'Install'
+/** 按失败类型给出简洁的错误原因标题（对外用英文）：
+ *  标题直接点明问题出在哪一侧（构建白名单/分发物/本机 npm/网络/插件侧），
+ *  作者与用户扫一眼列表就能分流 —— 不再用含糊的 Install/Remove 动作词。 */
+function reasonTitleOf(kind: FailureKind): string {
+  switch (kind) {
+    case 'npmTooOld': return 'npm too old to install'
+    case 'pnpmIgnoredBuild': return 'build scripts blocked by pnpm allowlist'
+    case 'pluginPrepare': return 'plugin distribution incomplete'
+    case 'network': return 'network failure on the user side'
+    default: return 'plugin install failed'
+  }
 }
 
 /**
- * 一键反馈 GitHub Issue 的预填链接：标题带「来自 dsh-plugin.org」标识，正文只带
- * 核心信息 —— 原因判定 + 关键错误代码 + 尝试过的安装方式 + 宿主机器环境快照 +
+ * 一键反馈 GitHub Issue 的预填链接：标题带「来自 dsh-plugin.org」标识 + 错误原因，
+ * 正文只带核心信息 —— 原因判定 + 关键错误代码 + 尝试过的安装方式 + 宿主机器环境快照 +
  * 错误核心摘要（完整日志太长，塞进 URL 会被 GitHub 以「request URL too long」拒绝，
  * 故只收集重点）。错误弹窗、失败记录共用此逻辑。
  * env 取不到时为 null，链接照常生成、只是少环境段。
@@ -52,20 +57,21 @@ function actionLabelOf(command: string | undefined): string {
  * 组织 scope 与 GitHub 用户名不一致时也能直接指认正确的 npm 包名。
  */
 export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | null, command?: string, attempts?: string[]): string {
-  // 标题按实际执行的动作区分（安装/更新/卸载），避免作者误读 —— 旧版固定写死
-  // 「Install/Remove」会让更新失败被当成删除失败。
-  const title = `[dsh-plugin.org | dsh-plugin-hub] ${actionLabelOf(command)} failed: ${repo}`
   // 原因判定：按失败类型归类，便于作者判断问题是否出在插件侧。
   // [packaging]（预检/装后校验拦截）单独列：无论走 npm 还是 git 通道，都是分发物不完整
   // （package.json 声明的入口文件在发布物里缺失），作者照此补齐即可。
   const kind = classifyFailure(message)
+  // 标题 = 错误原因（非动作词），让 issue 列表一眼可分流
+  const title = `[dsh-plugin.org | dsh-plugin-hub] ${reasonTitleOf(kind)}: ${repo}`
   const reason = /\[packaging\]/i.test(message)
     ? 'plugin distribution is incomplete — the entry file declared in package.json is missing from the published package (github tarball or npm package); please commit build output or publish a complete package'
-      : kind === 'pluginPrepare'
-        ? 'plugin prepare/build script failed during install (packaging/distribution issue)'
-        : kind === 'pnpmIgnoredBuild'
-          ? 'plugin depends on a native module whose build script pnpm blocks by default (use a prebuilt variant)'
-          : 'plugin-side install failure'
+      : kind === 'network'
+        ? 'network connectivity issue on the user side (DNS, proxy, firewall, or a blocked connection)'
+        : kind === 'pluginPrepare'
+          ? 'plugin prepare/build script failed during install (packaging/distribution issue)'
+          : kind === 'pnpmIgnoredBuild'
+            ? 'plugin depends on a native module whose build script pnpm blocks by default (use a prebuilt variant)'
+            : 'plugin-side install failure'
   const code = coreErrorCode(message)
   // 按给定核心摘要预算构建完整预填 URL（含 URL 编码）；预算可调，供超长时逐档缩小
   const build = (coreChars: number): string => {
@@ -134,3 +140,4 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
   }
   return url
 }
+

package/src/client/styles/List.module.css

@@ -301,7 +301,6 @@ body[data-ds-dark-theme] .uninstallBtn:hover {
 }
 
 .retryBtn {
-  margin-top: 4px;
   font-size: 12px;
   line-height: 18px;
   color: var(--hub-text-secondary);
@@ -318,6 +317,30 @@ body[data-ds-dark-theme] .uninstallBtn:hover {
   background: var(--hub-bg-hover);
 }
 
+/* 失败态按钮行：重试 + 「去系统诊断检测网络」并排 */
+.stateActions {
+  margin-top: 4px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.diagBtn {
+  font-size: 12px;
+  line-height: 18px;
+  color: #fff;
+  border: none;
+  border-radius: 6px;
+  padding: 4px 12px;
+  background: var(--hub-brand);
+  cursor: pointer;
+  user-select: none;
+}
+
+.diagBtn:hover {
+  background: var(--hub-brand-hover);
+}
+
 /* —— footer —— */
 
 .footer {

package/src/client/styles/Modal.module.css

@@ -1239,6 +1239,47 @@
   border-radius: 6px;
 }
 
+/* 网络不通提示下的「去系统诊断」操作按钮：品牌实底小按钮（区别于红色提 Issue 大按钮） */
+.failDiagBtn {
+  display: block;
+  width: 100%;
+  box-sizing: border-box;
+  margin-top: 8px;
+  padding: 5px 16px;
+  font-size: 13px;
+  line-height: 18px;
+  font-weight: 600;
+  text-align: center;
+  color: var(--hub-text-on-fill);
+  background: var(--hub-btn-fill);
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  user-select: none;
+  transition: background 120ms ease, box-shadow 120ms ease;
+}
+
+.failDiagBtn:hover {
+  background: var(--hub-btn-hover);
+  box-shadow: 0 3px 10px rgba(0, 0, 0, 0.12);
+}
+
+/* 网络类失败弹窗的「无法访问 …」醒目行：红色加粗，直接告诉用户具体哪个地址连不上
+   （URL 较长允许换行断词），与下方琥珀色说明区分主次 */
+.failNetworkTarget {
+  margin-top: 6px;
+  padding: 8px 12px;
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 700;
+  word-break: break-all;
+  color: var(--hub-danger);
+  background: var(--hub-danger-tint);
+  border: 1px solid var(--hub-danger-border);
+  border-radius: 6px;
+}
+
+
 /* —— 「关注我们」弹窗 —— */
 
 /* 关注弹窗：比普通弹窗略宽，给 Markdown 介绍 + 反馈群二维码留出阅读空间；
@@ -1356,13 +1397,13 @@
 }
 
 /* 用户反馈群二维码（renderMarkdown 对 dsh-plugin-user-group-qr- 前缀图片加了
-   width/height="250"）：固定 250×250 正方形。必须显式覆盖通用 max-height 上限 ——
-   CSS max-height 对 height 有最终裁决权，不覆盖的话高度被压成 220 而宽度保持 250，
-   图片就会变成非正方形（看起来像「250×250 没生效」） */
-.aboutContent img[width="250"] {
-  width: 250px;
-  height: 250px;
-  max-height: 250px;
+   width/height="100"）：固定 100×100 正方形。必须显式覆盖通用 max-height 上限 ——
+   CSS max-height 对 height 有最终裁决权，不覆盖的话高度被 max-height 规则压掉，
+   图片就会变成非正方形（看起来像「尺寸没生效」） */
+.aboutContent img[width="100"] {
+  width: 100px;
+  height: 100px;
+  max-height: 100px;
   object-fit: contain;
 }
 

package/src/client/styles/SettingsView.module.css

@@ -178,6 +178,30 @@
   width: 100%;
 }
 
+/* 代理输入框列布局：输入框 + 连通性探测提示上下排列，整行展开 */
+.proxyControl {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 5px;
+}
+
+/* 代理连通性提示：检测中灰字 / 可达绿字 / 不通琥珀字（仍可保存，不阻断输入） */
+.proxyHint {
+  font-size: 11px;
+  line-height: 1.4;
+  color: var(--hub-text-disabled);
+}
+
+.proxyHintOk {
+  color: var(--hub-success);
+}
+
+.proxyHintFail {
+  color: var(--hub-warning);
+}
+
 /* 下拉控件：行内固定宽度，与输入框等高 */
 .controlDropdown {
   min-width: 180px;