dsh-plugin 2.0.6 → 2.1.0

package/lib/types/services/settings.d.ts

@@ -3,8 +3,10 @@ export interface HubSettings {
     checkUpdatesOnStart: boolean;
     /** HTTP(S) 代理地址，用于 npm / git / 目录请求（空串 = 直连） */
     proxy: string;
-    /** npm 镜像源 registry 地址（空串 = 未配置，跟随用户本机 npm 配置，本插件不注入任何 registry） */
+    /** npm 镜像源 registry 地址（空串 = 未配置，跟随用户本机 npm 配置） */
     npmRegistry: string;
+    /** 公共源传输失败时自动换下一个镜像重试（自定义/内网源不切换） */
+    registryFallback: boolean;
     /** 启用命令行安装 NPM 包（默认开；关掉后输入 npm 包名安装被拦截） */
     enableNpmInstall: boolean;
     /** 日志存放位置覆盖（空串 = 默认 ~/.dsh/profiles/<profile>/hub.log；可填目录或 .log 文件路径） */

package/package.json

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

package/src/client/components/PluginHubSection.tsx

@@ -76,6 +76,9 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
   const [confirmPlugin, setConfirmPlugin] = useState<HubPlugin | null>(null)
   /** 弹窗动作是否为「更新」：已安装插件点「更新」→ 走同一条 add 命令原位覆盖重装，文案区分安装/更新 */
   const [confirmIsUpdate, setConfirmIsUpdate] = useState(false)
+  /** Hub 自我更新指定的精确版本：连续发版时提示的是「已过供应链门禁」的旧一版，
+   *  安装必须钉在该版本上，否则又会被 @latest 带回门禁内的最新版。 */
+  const [confirmPinVersion, setConfirmPinVersion] = useState<string | null>(null)
   /** 命令行安装确认弹窗：记录待安装的裸目标（npm 包名）——
    *  与应用商店同一套确认/进度/结果弹窗，提供时 plugin 传 null 走 customTarget 模式 */
   const [confirmCustomTarget, setConfirmCustomTarget] = useState<string | null>(null)
@@ -450,6 +453,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
           onInstall: (p, opts) => {
             setInstallDone(false)
             setConfirmIsUpdate(opts?.update ?? false)
+            setConfirmPinVersion(null)
             // 与卸载一致：重置弹窗关联任务，避免新弹窗误匹配到进行中的任务而禁用安装按钮
             queue.clearModalTask()
             setConfirmPlugin(p)
@@ -484,6 +488,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
               setDetailItem(null)
               setInstallDone(false)
               setConfirmIsUpdate(true)
+              setConfirmPinVersion(null)
               queue.clearModalTask()
               setConfirmPlugin(item.plugin)
             },
@@ -547,7 +552,8 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
     // 暂缓提示显示同一标题但只给「稍后再说」，无更新显示当前版本 + 记录 + 「已是最新」。
     // 版本号与本机版本一律由 hubUpdateState / hubCurrentVersion 决定，不用远端版号冒充本机。
     showHubUpdate && h(HubUpdateModal, {
-      info: catalog.hubUpdateInfo ?? { version: PLUGIN_VERSION },
+      // 提示目标是「已过供应链门禁」的版本，可能不是 latest —— 展示它与它的变更记录
+      info: catalog.hubUpdateTarget ?? catalog.hubUpdateInfo ?? { version: PLUGIN_VERSION },
       state: catalog.hubUpdateState,
       currentVersion: catalog.hubCurrentVersion,
       lang,
@@ -559,6 +565,8 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
         if (hubEntry) {
           setInstallDone(false)
           setConfirmIsUpdate(true)
+          // 钉住本次提示的版本：最新版可能仍在门禁内，@latest 会被 pnpm 拒绝
+          setConfirmPinVersion(catalog.hubUpdateTarget?.version ?? null)
           queue.clearModalTask()
           setConfirmPlugin(hubEntry)
         }
@@ -595,6 +603,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
         setShowNotifications(false)
         setInstallDone(false)
         setConfirmIsUpdate(true)
+        setConfirmPinVersion(null)
         queue.clearModalTask()
         setConfirmPlugin(plugin)
       },
@@ -673,7 +682,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
         if (reload) window.location.reload()
       },
       onCopy: () => copyCommand(confirmPlugin),
-      onInstall: () => queue.installNow(confirmPlugin, confirmIsUpdate ? { update: true } : undefined),
+      onInstall: () => queue.installNow(confirmPlugin, confirmIsUpdate ? { update: true, pinVersion: confirmPinVersion ?? undefined } : undefined),
       // 重启：结果视图「立即重启」也会中断进行中的任务 → 先弹重启确认弹窗
       onRestart: () => setShowRestartConfirm(true),
     }),

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

@@ -14,7 +14,7 @@ import type { MouseEvent } from 'react'
 import styles from '../../styles/Modal.module.css'
 import type { EnvInfo, Translate } from '../../types.ts'
 import type { NotificationRecord } from '../../logic/failures.ts'
-import { actionOfRecord, classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
+import { actionOfRecord, classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf, authRegistryHostOf } from '../../logic/failures.ts'
 import type { PendingRestart, QueueTask } from '../../hooks/useTaskQueue.ts'
 import { pluginIssueUrl, pluginSiteUrl, hubIssueUrl } from '../../logic/urls.ts'
 import { CloseIcon } from '../ui/icons.tsx'
@@ -397,6 +397,13 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 安装流程，与插件无关 —— 引导从本机地址重新打开市场，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failOriginRejectedHint', { profile: env?.profile ?? '<profile>' }))
                     }
+                    if (kind === 'registryAuth') {
+                      // npm 源返回 401/403：私有源需要凭据，或当前网络/IP 不被允许 —— 本机环境问题，
+                      // 给「配认证 / 换回官方源 / 切公共镜像」指引，不引导提 Issue
+                      const host = authRegistryHostOf(r.message)
+                      return h('div', { className: styles.failPrepareHint },
+                        t(host ? 'failRegistryAuthHint' : 'failRegistryAuthHintNoHost', host ? { host } : undefined))
+                    }
                     if (kind === 'network') {
                       // 安装前网络探测 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
                       // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，

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

@@ -15,7 +15,7 @@ import { CloseIcon, ConfirmIcon, CopyIcon, LinkIcon } from '../ui/icons.tsx'
 import { ProgressView } from './ProgressView.tsx'
 import { installCommandOf } from '../../logic/install-command.ts'
 import { pluginDetailUrl, pluginIssueUrl, pluginSiteUrl, hubIssueUrl } from '../../logic/urls.ts'
-import { classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
+import { classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf, authRegistryHostOf } from '../../logic/failures.ts'
 import type { FailureAction } from '../../logic/failures.ts'
 
 /** 完成结果视图：绿色对勾 + 标题/描述；
@@ -530,6 +530,14 @@ export function ErrorModal({ message, repo, action, command, attempts, t, env, o
               // 请求来源没通过本地 hub 服务的校验（服务端 403 untrusted origin）：请求根本没进
               // 安装流程，与插件无关 —— 引导从本机地址重新打开市场，不引导提 Issue
               ? h('div', { className: styles.failPrepareHint }, t('failOriginRejectedHint', { profile: env?.profile ?? '<profile>' }))
+              : failureKind === 'registryAuth'
+              // npm 源返回 401/403：私有源需要凭据，或当前网络/IP 不被允许 —— 本机环境问题，
+              // 给「配认证 / 换回官方源 / 切公共镜像」指引，不引导提 Issue
+              ? (() => {
+                const host = authRegistryHostOf(message)
+                return h('div', { className: styles.failPrepareHint },
+                  t(host ? 'failRegistryAuthHint' : 'failRegistryAuthHintNoHost', host ? { host } : undefined))
+              })()
               : failureKind === 'network'
               // 安装前网络探测 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
               // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，

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

@@ -176,6 +176,16 @@ export function SettingsView({ t, settings, update, reset, env, onCopy, openSect
         className: `${styles.controlDropdown} ${dropdownStyles.dropdownFill}`,
       }),
     }),
+    // 自动换源：只在公共源之间切换；自定义/内网源不降级，避免私有包名泄露
+    h(SettingRow, {
+      title: t('settingsRegistryFallback'),
+      desc: t('settingsRegistryFallbackDesc'),
+      children: h(Toggle, {
+        checked: settings.registryFallback,
+        onChange: (v) => update({ registryFallback: v }),
+        title: t('settingsRegistryFallback'),
+      }),
+    }),
     // 代理地址：文本框独占一行，整行输入，便于粘贴长代理地址；停笔后实时探测连通性，
     // 不通仅提示（可保存）—— 用户可能先填地址后开代理
     h(SettingRow, {

package/src/client/hooks/useCatalog.ts

@@ -16,7 +16,7 @@ import type { SortKey } from '../logic/constants.ts'
 import { fetchCatalog, fetchStats } from '../data/catalog.ts'
 import { fetchHubAbout, fetchHubUpdate } from '../data/hub.ts'
 import { fetchInstalled, fetchNpmReleaseAge } from '../data/host.ts'
-import { isReleaseTooFresh } from '../logic/release-age.ts'
+import { isReleaseTooFresh, pickHubUpdate } from '../logic/release-age.ts'
 import {
   hasUpdateOf, installedItemsOf, installedNameOf, installedVersionOf, npmPackageOf,
 } from '../logic/installed.ts'
@@ -272,13 +272,14 @@ export function useCatalog(lang: LocaleId) {
    * 落回「无更新」——回落会让弹窗在本机版本落后时谎称「已是最新」。
    */
   const hubCurrentVersion = PLUGIN_VERSION || versions[HUB_REPO]?.version || ''
-  const hubUpdateState: HubUpdateState = (() => {
-    if (!hubUpdateInfo) return 'none'
-    if (hubCurrentVersion === '' || hubUpdateInfo.version === hubCurrentVersion) return 'latest'
-    // 供应链门禁（24h + 30 分钟缓冲）与插件更新同一口径：发布未满门槛的版本暂缓提示
-    if (isReleaseTooFresh(hubUpdateInfo.publishedAt, Date.now())) return 'pending'
-    return 'available'
-  })()
+  // 候选含 recentVersions：最新版还在门禁内时回退到「更早、但已过门禁」的版本，
+  // 避免连续快速发版把所有提示窗口都吞掉（见 pickHubUpdate）。
+  const hubUpdateResult = hubUpdateInfo === null
+    ? { state: 'none' as HubUpdateState, target: null }
+    : pickHubUpdate(hubUpdateInfo, hubCurrentVersion, Date.now())
+  const hubUpdateState: HubUpdateState = hubUpdateResult.state
+  /** 本次提示的目标版本（available 时有值；pending 时是暂缓中的最高版本） */
+  const hubUpdateTarget = hubUpdateResult.target
   const hubHasUpdate = hubUpdateState === 'available'
 
   /** 当前分类下的插件（「全部」时为整个目录）。 */
@@ -334,6 +335,7 @@ export function useCatalog(lang: LocaleId) {
     hasUpdate,
     hubHasUpdate,
     hubUpdateState,
+    hubUpdateTarget,
     releaseAgeReady,
     hubCurrentVersion,
     hubUpdateInfo,

package/src/client/hooks/useSettings.ts

@@ -15,8 +15,10 @@ export interface HubSettings {
   checkUpdatesOnStart: boolean
   /** HTTP(S) 代理地址，用于 npm / git / 目录请求（空串 = 直连） */
   proxy: string
-  /** npm 镜像源 registry 地址（空串 = 未配置，跟随用户本机 npm 配置，不注入任何 registry） */
+  /** npm 镜像源 registry 地址（空串 = 未配置，跟随用户本机 npm 配置） */
   npmRegistry: string
+  /** 公共源传输失败时自动换下一个镜像重试（自定义/内网源不切换） */
+  registryFallback: boolean
   /** 启用命令行安装 NPM 包（默认开） */
   enableNpmInstall: boolean
   /** 日志存放位置覆盖（空串 = 默认 ~/.dsh/profiles/<profile>/hub.log） */
@@ -27,6 +29,7 @@ export const DEFAULT_SETTINGS: HubSettings = {
   checkUpdatesOnStart: true,
   proxy: '',
   npmRegistry: '',
+  registryFallback: true,
   enableNpmInstall: true,
   logPath: '',
 }

package/src/client/hooks/useTaskQueue.ts

@@ -433,6 +433,9 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     source: 'catalog' | 'custom'
     /** 更新已安装目标（放行 add 覆盖重装） */
     update?: boolean
+    /** 钉住精确版本（Hub 自我更新用）：最新版可能仍在 pnpm 供应链门禁内，
+     *  必须安装「已过门禁」的那个版本，不能再用 @latest。 */
+    pinVersion?: string
     /** 全局 npm 安装包列表（`npm install -g <pkgs>`）：非空时服务端执行全局安装，不进任何 profile */
     globalNpm?: string[]
     /** 自定义安装入口渠道（NPM 包卡片）：随请求上报服务端落日志，
@@ -473,6 +476,8 @@ export function useTaskQueue(opts: TaskQueueOptions) {
           display: input.repo,
           source: input.source,
           mode: input.update ? 'update' : undefined,
+          // 钉住版本（Hub 自我更新）：服务端据此执行 `add <pkg>@<version>` 而不是 @latest
+          ...(input.pinVersion ? { version: input.pinVersion } : {}),
           // 界面语言带给服务端：安装前网络探测等错误消息按用户当前语言返回（中文界面给中文，英文界面给英文）
           ...(langKey ? { lang: langKey } : {}),
           // 安装入口渠道（只可能是 npm）：服务端日志/报错提示据此溯源
@@ -523,7 +528,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   }
 
   /** 目录插件安装：安装目标取目录数据的 npm 包名，走 catalog 白名单。 */
-  const installNow = async (p: HubPlugin, opts?: { update?: boolean }) => {
+  const installNow = async (p: HubPlugin, opts?: { update?: boolean; pinVersion?: string }) => {
     const repo = p.source?.repo ?? ''
     if (!repo) return
     // 目录条目必带 npm 包名：直接用包名安装（用户无感知）。
@@ -538,6 +543,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       command: installCommandOf(p, true),
       source: 'catalog',
       update: opts?.update,
+      pinVersion: opts?.pinVersion,
     })
   }
 

package/src/client/locales.ts

@@ -117,6 +117,8 @@ export const zh = {
   proxyCheckRevocation: '证书吊销检查受阻（Windows Schannel 取不到 CRL/OCSP），握手被中断；属本机 TLS 环境问题，非代理地址不通',
   settingsMirror: 'npm 镜像源',
   settingsMirrorDesc: '默认跟随本机 npm 配置；官方源慢可换国内镜像',
+  settingsRegistryFallback: '连不上时自动换源',
+  settingsRegistryFallbackDesc: '公共源超时或被拦截时，自动改用下一个镜像重试（最多 3 个）；自定义/内网源不会切换，避免私有包名外泄',
   mirrorNone: '未配置（跟随本机 npm 配置）',
   mirrorOfficial: '官方源 registry.npmjs.org',
   mirrorNpmmirror: '阿里云 npmmirror',
@@ -386,6 +388,8 @@ export const zh = {
   failReason_pluginMissingDep: '插件声明依赖的包在官方 npm 源上不存在（已删除或从未发布）。',
   failKind_registryVersionStale: '该版本在所用源上不存在',
   failReason_registryVersionStale: '实际安装用的源还没同步到这个版本，或版本号写错。',
+  failKind_registryAuth: 'npm 源拒绝了访问',
+  failReason_registryAuth: 'registry 返回 401/403：这个源需要登录凭据，或当前网络不被允许。',
   failKind_pnpmLinkedDirMissing: 'profile 里有失效的本地依赖',
   failReason_pnpmLinkedDirMissing: '有一条指向本机不存在目录的 link/file 依赖，pnpm 每次解析都卡住。',
   failKind_fileLocked: '文件被其他程序占用',
@@ -413,6 +417,8 @@ export const zh = {
   failKind_hub: '出现未知错误',
   failReason_hub: '我们还没能识别这条报错，你可以一键反馈给我们。',
   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，或在插件市场设置里切换到公共镜像后重试。这不是插件本身的问题。',
   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 条目或整个锁文件），或把该目录恢复回原路径后重试。',
   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 目录及其文件是否被设为只读，并以管理员身份重新运行。',
@@ -583,6 +589,8 @@ export const en = {
   proxyCheckRevocation: 'Certificate revocation check blocked (Windows Schannel could not fetch CRL/OCSP), so the handshake was aborted — a local TLS issue, not a bad proxy address',
   settingsMirror: 'npm mirror',
   settingsMirrorDesc: 'Unset by default — follows local npm config; pick a domestic mirror if slow',
+  settingsRegistryFallback: 'Switch mirrors on failure',
+  settingsRegistryFallbackDesc: 'When a public registry times out or is blocked, retry with the next mirror (up to 3). Custom/intranet registries are never switched, so private package names do not leak.',
   mirrorNone: 'Unset (follow local npm config)',
   mirrorOfficial: 'Official registry.npmjs.org',
   mirrorNpmmirror: 'Alibaba npmmirror',
@@ -850,6 +858,8 @@ export const en = {
   failReason_pluginMissingDep: 'A package the plugin depends on does not exist on the official npm registry.',
   failKind_registryVersionStale: 'this version is not available on the registry in use',
   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_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',
@@ -877,6 +887,8 @@ export const en = {
   failKind_hub: 'unknown error',
   failReason_hub: 'We could not identify this error yet — you can report it to us in one click.',
   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.',
   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.',
   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.',

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' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'buildToolchainMissing' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'hostIncompatible' | 'network' | 'hostCliSpawn' | 'hubState' | 'timeout' | 'profileLock' | 'hub'
+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 FailureAction = 'install' | 'update' | 'uninstall'
@@ -253,6 +253,9 @@ export function classifyFailure(message: string): FailureKind {
   if (/os error 112\b|os error 19\b|ERROR_DISK_FULL|ERROR_WRITE_PROTECT|\bENOSPC\b|\bEROFS\b|\bEMFILE\b|\bENFILE\b|no space left on device|read-only file system|too many open files/i.test(message)) return 'fsUnavailable'
   // 构建脚本被 allowBuilds 拦截。必须在 network 之前判：日志尾部混重试残留的连接失败特征
   if (/ERR_PNPM_IGNORED_BUILDS|Ignored build scripts:|ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED/i.test(message)) return 'pnpmIgnoredBuild'
+  // 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'
   // 网络/代理/源配置问题。必须在 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'
@@ -353,6 +356,9 @@ export function summarizeError(message: string, maxChars: number = MAX_CORE_CHAR
   }
   let out: string
   if (core.length === 0) {
+    // 整段本来就是短消息时直接给全量：head+tail 兜底会把同一段重复两遍，正文反而更难读
+    const whole = message.trim()
+    if (whole.length <= maxChars) return whole
     // 无关键行时退化为「头部 + 尾部」快照：优先保尾部完整，头部按预算压缩，总长不超上限
     const tail = message.trimEnd().slice(-1000)
     const sep = '\n…\n'
@@ -431,3 +437,13 @@ export function registryHostOf(message: string): string | null {
   const host = m[1].replace(/:\d+$/, '')
   return PUBLIC_REGISTRY_HOSTS.has(host) ? null : host
 }
+
+/**
+ * 鉴权失败（401/403）时被拒绝的源主机名：从 `ERR_PNPM_FETCH_401 GET https://host/pkg: Unauthorized - 401`
+ * 里取，取不到返回 null（提示文案退回通用说法，不拼出残缺句子）。
+ */
+export function authRegistryHostOf(message: string): string | null {
+  const m = /ERR_PNPM_FETCH_40[13]\s+GET\s+https?:\/\/([^\s/:]+)/i.exec(message)
+    ?? /GET\s+https?:\/\/([^\s/:]+)\S*\s*:?\s*(?:Unauthorized|Forbidden)\s*-\s*40[13]/i.exec(message)
+  return m === null ? null : m[1]
+}

package/src/client/logic/release-age.ts

@@ -6,6 +6,7 @@
  * 供应链门禁的时间判定（纯函数）：pnpm 会静默回退发布未满门槛的版本，
  * 故发布太新的版本不该提示更新。Hub 自身更新与插件更新共用同一门槛。
  */
+import type { HubUpdateInfo, HubUpdateState, HubUpdateVersion } from '../types.ts'
 
 /** pnpm 供应链门禁：dsh profile 默认 minimumReleaseAge=1440（分钟）；+30 分钟缓冲抵消网络/CDN 边缘时间偏差。 */
 export const MIN_RELEASE_AGE_MS = 24 * 60 * 60 * 1000 + 30 * 60 * 1000
@@ -17,3 +18,42 @@ export function isReleaseTooFresh(publishedAt: string | null | undefined, now: n
   if (Number.isNaN(ms)) return false
   return now - ms < MIN_RELEASE_AGE_MS
 }
+
+/** 版本号比较（逐段数字；缺失段按 0）。返回负数/0/正数，非法输入按相等处理。 */
+export function compareVersions(a: string, b: string): number {
+  const parse = (v: string): number[] => v.split(/[.+-]/).map((part) => Number.parseInt(part, 10)).filter((n) => !Number.isNaN(n))
+  const va = parse(a)
+  const vb = parse(b)
+  const len = Math.max(va.length, vb.length)
+  for (let i = 0; i < len; i++) {
+    const d = (va[i] ?? 0) - (vb[i] ?? 0)
+    if (d !== 0) return d
+  }
+  return 0
+}
+
+/**
+ * 选出本次真正该提示的更新版本。
+ *
+ * 只看最新版会漏更新：连续发版时间隔小于供应链门禁时，最新版永远「太新」，
+ * 提示被整体跳过。这里把最新版与 recentVersions 一起当候选，取「高于当前版本且已过门禁」
+ * 的最高版本；一个都没有但仍存在更高版本 → pending（暂缓，不谎称已是最新）。
+ */
+export function pickHubUpdate(info: HubUpdateInfo, currentVersion: string, now: number): { state: HubUpdateState; target: HubUpdateVersion | null } {
+  if (currentVersion === '') return { state: 'latest', target: null }
+  const seen = new Set<string>()
+  const candidates: HubUpdateVersion[] = []
+  for (const entry of [{ version: info.version, publishedAt: info.publishedAt, notes: info.notes }, ...(info.recentVersions ?? [])]) {
+    if (typeof entry.version !== 'string' || entry.version === '' || seen.has(entry.version)) continue
+    seen.add(entry.version)
+    candidates.push(entry)
+  }
+  const higher = candidates
+    .filter((c) => compareVersions(c.version, currentVersion) > 0)
+    .sort((a, b) => compareVersions(b.version, a.version))
+  if (higher.length === 0) return { state: 'latest', target: null }
+  const ready = higher.find((c) => !isReleaseTooFresh(c.publishedAt, now))
+  return ready !== undefined
+    ? { state: 'available', target: ready }
+    : { state: 'pending', target: higher[0]! }
+}

package/src/client/logic/urls.ts

@@ -54,7 +54,8 @@ function reasonTitleOf(kind: FailureKind, action: FailureAction): string {
     case 'pnpmPolicy': return `pnpm supply-chain policy blocked the ${word} on the user machine`
     case 'pnpmUnusedPatch': return 'stale pnpm patch entry on the user machine'
     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 '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 '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'
@@ -101,6 +102,8 @@ 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 === 'registryAuth'
+        ? 'the npm registry rejected the request with 401/403 — the configured registry needs credentials or blocks this network (local environment issue)'
         : kind === 'pluginPrepare'
           ? 'plugin prepare/build script failed during install (packaging/distribution issue)'
           : kind === 'pnpmIgnoredBuild'

package/src/client/types.ts

@@ -108,6 +108,19 @@ export interface HubUpdateInfo {
   publishedAt?: string | null
   /** Markdown 变更记录；可传字符串，或 { zh, en } 双语言对象按界面语言取 */
   notes?: string | Record<string, string> | null
+  /**
+   * 最近若干发版（含最新版），按版本号降序无关、由客户端自行排序。
+   * 用途：连续快速发版时，最新版往往还在 pnpm 的 24h 供应链门禁内；
+   * 客户端据此回退到「更早、但已过门禁」的版本提示更新，而不是整体跳过。
+   */
+  recentVersions?: HubUpdateVersion[]
+}
+
+/** 单个发版记录：版本号 + 与 npm registry 同源的发布时间 + 该版本变更记录。 */
+export interface HubUpdateVersion {
+  version: string
+  publishedAt?: string | null
+  notes?: string | Record<string, string> | null
 }
 
 /**

package/src/server/http/install.ts

@@ -11,11 +11,13 @@ import { recordResolvedNpmPackage } from '../services/profile/installed-versions
 import { isDshNpmPackageForRepo } from '../services/install/npm-resolve.ts'
 import { probeUrl, systemProxy } from '../services/probe.ts'
 import { loadSettings, type HubSettings } from '../services/settings.ts'
+import { registryCandidates, registryHost, userNpmRegistry } from '../services/install/registry-fallback.ts'
+import { profileDirectory } from '../services/profile/profile.ts'
 import { readInstalled } from './catalog.ts'
 import { COMMAND_TIMEOUT_MS, readJsonBody, requireTrustedPost, sendJson, type WebRoute, type WebServerService } from './shared.ts'
 
 /** 安装/卸载 CLI 的子进程环境：透传宿主环境并注入 HTTP(S) 代理，
- *  代理来源与诊断一致（设置代理 → 系统代理 → 宿主 env）；不注入 npm registry，沿用用户本机 npm 配置。 */
+ *  代理来源与诊断一致（设置代理 → 系统代理 → 宿主 env）；registry 由任务队列按候选源逐次注入。 */
 function mutationEnv(settings: HubSettings): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { ...process.env, CI: 'true' }
   const proxy = settings.proxy !== '' ? settings.proxy : (systemProxy() ?? '')
@@ -64,6 +66,17 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
           const lang = typeof body === 'object' && body !== null && (body as { lang?: unknown }).lang === 'en'
             ? 'en'
             : 'zh'
+          // 代理口径与诊断/安装通道一致：设置里的代理 → 系统代理 → 环境变量 → 直连。
+          const effectiveProxy = settings.proxy !== ''
+            ? settings.proxy
+            : (systemProxy() ?? process.env.HTTPS_PROXY ?? process.env.https_proxy ?? '')
+          // 安装用的 npm 源：设置里显式选择优先；未配置时读本机 npm 配置（与诊断同口径）。
+          // 只有公共源允许失败后换源；自定义/内网源保持单一候选，避免私有包名泄露给公共源。
+          const registries = registryCandidates(
+            settings.npmRegistry,
+            settings.npmRegistry === '' ? userNpmRegistry(profileDirectory(profile)) : '',
+            settings.registryFallback,
+          )
           // 全局 npm 安装（`npm install -g <pkgs>`）：不进任何 profile、无需宿主重启。
           // 包列表优先取 body.globalNpm，兜底从 rawRepo 解析，保证直接调 API 传完整命令也能识别。
           const bodyGlobalNpm = Array.isArray((body as { globalNpm?: unknown }).globalNpm)
@@ -95,6 +108,8 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
               globalNpm,
               timeoutMs: COMMAND_TIMEOUT_MS,
               env: mutationEnv(settings),
+              // 候选源（首选在前）：任务内遇到传输层失败时按顺序换源重试
+              registries,
               // 全局 npm 安装由 NPM 包卡片/官方命令发起：日志体现入口渠道
               installChannel: installChannel ?? 'npm',
             })
@@ -107,12 +122,17 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             return
           }
           const target = rawRepo
+          // 钉住精确版本（Hub 自我更新）：最新版可能仍在 pnpm 供应链门禁内，
+          // 客户端提示的是「已过门禁」的版本，服务端必须按该版本安装而不是 @latest。
+          const pinVersion = typeof (body as { version?: unknown }).version === 'string'
+            ? (body as { version: string }).version.trim()
+            : ''
+          if (pinVersion !== '' && !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/.test(pinVersion)) {
+            sendJson(response, 400, { error: 'invalid version' })
+            return
+          }
           // 已尝试的安装方式（供失败提 Issue 预填）：保持为空
           const attempts: string[] = []
-          // 代理口径与诊断/安装通道一致：设置里的代理 → 系统代理 → 环境变量 → 直连。
-          const effectiveProxy = settings.proxy !== ''
-            ? settings.proxy
-            : (systemProxy() ?? process.env.HTTPS_PROXY ?? process.env.https_proxy ?? '')
           // 目录插件安装：目录数据可能滞后于打包拆分，确认目录下发的 npm 目标确为该仓库的 DSH 包，
           // 命中则记录 repo → 包名映射，客户端据此把依赖 key 匹配回仓库、列表立即显示「已安装」。
           const catalogRepo = source === 'catalog' ? githubRepoOf(displayRepo) : null
@@ -136,18 +156,30 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             return
           }
           // 安装前网络探测：探 registry 根而非具体包（404 是「包不存在」而非网络不通）；仅新安装执行，更新跳过。
-          // 不通则 400 拦下并打 [network] 标记，客户端据此提示网络问题，而非插件问题。
+          // 首选源不通时按候选顺序继续探下一个，能通的那个提到首位供实际安装使用。
+          // 全部不通则 400 拦下并打 [network] 标记，客户端据此提示网络问题，而非插件问题。
+          let ordered = registries
           if (already === null) {
-            const probeTarget = `${(settings.npmRegistry.replace(/\/+$/, '') || 'https://registry.npmjs.org')}/`
-            const net = await probeUrl(probeTarget, effectiveProxy, 6000)
-            if (!net.ok) {
+            const tried: string[] = []
+            let chosen: string | null = null
+            for (const candidate of registries) {
+              tried.push(candidate)
+              const net = await probeUrl(`${candidate}/`, effectiveProxy, 6000)
+              if (net.ok) {
+                chosen = candidate
+                break
+              }
+            }
+            if (chosen === null) {
               // 错误消息按界面语言输出，让用户看清是网络问题而非插件问题
+              const hosts = tried.map(registryHost).join(' → ')
               const error = lang === 'zh'
-                ? `[network] 安装已中止：安装前无法连接到 npm 源（${probeTarget}）—— 您的网络似乎不通或被拦截（断网 / DNS 解析失败 / 防火墙 / 代理配置问题）。这不是插件本身的问题，请检查网络连接或代理设置，运行「系统诊断」检测各通道连通性后重试。`
-                : `[network] install aborted: cannot reach the npm registry (${probeTarget}) before install — your network connection appears to be down or blocked (DNS / proxy / firewall). This is not a problem with the plugin itself. Check your connection or proxy settings, run the connectivity diagnostic, then retry.`
+                ? `[network] 安装已中止：安装前无法连接到 npm 源（${hosts}）—— 您的网络似乎不通或被拦截（断网 / DNS 解析失败 / 防火墙 / 代理配置问题）。这不是插件本身的问题，请检查网络连接或代理设置，运行「系统诊断」检测各通道连通性后重试。`
+                : `[network] install aborted: cannot reach the npm registry (${hosts}) before install — your network connection appears to be down or blocked (DNS / proxy / firewall). This is not a problem with the plugin itself. Check your connection or proxy settings, run the connectivity diagnostic, then retry.`
               sendJson(response, 400, { error, attempts })
               return
             }
+            ordered = [chosen, ...registries.filter((r) => r !== chosen)]
           }
           // 入队前复检：网络探测的 await 期间并发请求可能已通过上方检查，而此处到 startPluginMutation
           // 之间无 await，JS 单线程保证同一目标至多一个任务，杜绝双击/并发双任务。
@@ -170,6 +202,9 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             loader,
             timeoutMs: COMMAND_TIMEOUT_MS,
             env: mutationEnv(settings),
+            // 候选源（首选在前）：任务内遇到传输层失败时按顺序换源重试
+            registries: ordered,
+            installSpec: pinVersion !== '' ? `${target}@${pinVersion}` : undefined,
             // 自定义安装入口渠道：日志/报错据此溯源
             installChannel,
           })

package/src/server/http/settings.ts

@@ -28,7 +28,7 @@ export function registerSettingsRoutes(webServer: WebServerService, profile: str
           // 白名单字段：只接受已知设置项，防客户端把任意键写进文件
           const patch: Record<string, unknown> = {}
           const source = typeof body === 'object' && body !== null ? body as Record<string, unknown> : {}
-          for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'npmRegistry', 'proxy', 'logPath'] as const) {
+          for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'npmRegistry', 'registryFallback', 'proxy', 'logPath'] as const) {
             if (source[key] !== undefined) patch[key] = source[key]
           }
           // 日志位置：非空时预建目录验证可写，失败直接 400 拦截（默认位置永远合法，空串 = 回默认）

package/src/server/services/install/decode-output.ts

@@ -0,0 +1,22 @@
+/**
+ * 子进程输出解码：默认 UTF-8；出现替换字符（中文 Windows 的 GBK 输出）时改用 GBK 重解。
+ * 用 StringDecoder 跨 chunk 缓冲，避免 UTF-8 多字节字符被 chunk 边界切断后误判为 GBK。
+ */
+import { StringDecoder } from 'node:string_decoder'
+
+export class OutputDecoder {
+  private readonly utf8 = new StringDecoder('utf8')
+
+  push(chunk: Buffer): string {
+    const text = this.utf8.write(chunk)
+    if (!text.includes('\uFFFD')) return text
+    try {
+      const gbk = new TextDecoder('gbk').decode(chunk)
+      // GBK 能完整解出且含中文才采用：纯 ASCII 或仍有替换字符时保持 UTF-8 结果
+      if (!gbk.includes('\uFFFD') && /[\u4e00-\u9fff]/.test(gbk)) return gbk
+    } catch {
+      // 无完整 ICU（TextDecoder 不支持 gbk）时退回 UTF-8 结果
+    }
+    return text
+  }
+}

package/src/server/services/install/install-types.ts

@@ -72,6 +72,10 @@ export interface QueueItem {
     env?: NodeJS.ProcessEnv
     globalNpm?: string[]
     installChannel?: 'npm'
+    /** npm 源候选（首选在前）：传输层失败时按顺序换源重试 */
+    registries?: string[]
+    /** 精确安装 spec（Hub 自我更新钉版本） */
+    installSpec?: string
   }
 }