dsh-plugin 2.1.0 → 2.2.1

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

@@ -14,7 +14,7 @@ import type { MouseEvent } from 'react'
 import styles from '../../styles/Modal.module.css'
 import type { EnvInfo, Translate } from '../../types.ts'
 import type { NotificationRecord } from '../../logic/failures.ts'
-import { actionOfRecord, classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf, authRegistryHostOf } from '../../logic/failures.ts'
+import { actionOfRecord, classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf, authRegistryHostOf, exclusiveProfileOf, desktopCliFallbackOf, dshTooOldInfoOf, unresolvedBundleOf, missingLocalDirOf } from '../../logic/failures.ts'
 import type { PendingRestart, QueueTask } from '../../hooks/useTaskQueue.ts'
 import { pluginIssueUrl, pluginSiteUrl, hubIssueUrl } from '../../logic/urls.ts'
 import { CloseIcon } from '../ui/icons.tsx'
@@ -306,6 +306,11 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 给 .npmrc 豁免指引，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failPnpmWorkspaceHint'))
                     }
+                    if (kind === 'pnpmModulesMismatch') {
+                      // profile 的 modules 目录与当前 pnpm 配置不一致（hoist / 虚拟目录长度 / node-linker 等）：
+                      // 该 profile 内的安装/卸载都会失败 —— 重建 modules 目录或统一配置即可，不引导提 Issue
+                      return h('div', { className: styles.failPrepareHint }, t('failPnpmModulesMismatchHint'))
+                    }
                     if (kind === 'pnpmStore') {
                       // pnpm 存在但 store 大版本不匹配（ERR_PNPM_UNEXPECTED_STORE）：profile 目录的依赖是
                       // 另一大版本 pnpm 装的，当前 pnpm 不认，任何插件装进该 profile 都会失败 ——
@@ -322,6 +327,16 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 发现补丁没被用上就中止安装，任何插件都装不进来 —— 不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failPnpmUnusedPatchHint'))
                     }
+                    if (kind === 'profileState') {
+                      // profile 的 pnpm 元数据与本机不一致（lockfile 过期 / packageManager 版本不符 /
+                      // 补丁未生效）：pnpm 在真正装插件之前就中止，该 profile 内的安装都会失败 ——
+                      // 给重建指引，不引导提 Issue
+                      return h('div', { className: styles.failPrepareHint }, t('failProfileStateHint'))
+                    }
+                    if (kind === 'nodeEngine') {
+                      // 本机 Node / pnpm 版本低于包声明的下限：升级即可解决 —— 不引导提 Issue
+                      return h('div', { className: styles.failPrepareHint }, t('failNodeEngineHint'))
+                    }
                     if (kind === 'pnpmMissingDep') {
                       // profile 里留着指向 registry 上不存在（404）的包的依赖：pnpm 连得上 registry，
                       // 是被明确告知包不存在 —— 该 profile 的任何安装都会先卡在这条依赖上，与本次要装的
@@ -372,10 +387,13 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       return h('div', { className: styles.failPrepareHint }, t('failRegistryVersionStaleHint'))
                     }
                     if (kind === 'pnpmLinkedDirMissing') {
-                      // profile 里留着指向不存在目录的本地依赖（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND）：
-                      // 常见于 link:/本地路径装过开发中的插件、之后目录被删；与本次要装的插件无关
-                      // —— 给删除悬空条目的指引，不引导提 Issue
-                      return h('div', { className: styles.failPrepareHint }, t('failPnpmLinkedDirMissingHint'))
+                      // profile 里留着指向不存在目录的本地依赖（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND /
+                      // pnpm ENOENT lstat）：点名缺失目录 + 删除悬空条目，不引导提 Issue
+                      const dir = missingLocalDirOf(r.message)
+                      return h('div', null, [
+                        dir ? h('div', { className: styles.failNetworkTarget }, t('failLinkedDirTarget', { path: dir })) : null,
+                        h('div', { className: styles.failPrepareHint }, t('failPnpmLinkedDirMissingHint')),
+                      ])
                     }
                     if (kind === 'fileLocked') {
                       // profile 里的文件被其他进程占用（Windows os error 32）：通常是宿主或杀毒软件
@@ -397,6 +415,24 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 安装流程，与插件无关 —— 引导从本机地址重新打开市场，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failOriginRejectedHint', { profile: env?.profile ?? '<profile>' }))
                     }
+                    if (kind === 'profileExclusive') {
+                      // desktop profile 只能由桌面应用管理：外部 dsh CLI 被宿主拒绝，属环境约束。
+                      // 带 [desktop-cli-fallback] 则是安装器没找到应用内 CLI 引导脚本 —— 我们的问题，给反馈入口
+                      const profile = exclusiveProfileOf(r.message)
+                      const ourBug = desktopCliFallbackOf(r.message)
+                      return h('div', null, [
+                        h('div', { className: styles.failPrepareHint },
+                          t(profile ? 'failProfileExclusiveHint' : 'failProfileExclusiveHintNoProfile', profile ? { profile } : undefined)),
+                        ourBug ? h('div', { className: styles.failPrepareHint }, t('failDesktopCliFallbackHint')) : null,
+                        ourBug ? h('a', {
+                          className: styles.failBigIssue,
+                          href: hubIssueUrl(shownRepo || r.repo, r.message, env, r.command, r.attempts, 'triage', action),
+                          target: '_blank',
+                          rel: 'noopener noreferrer',
+                          title: t('failHubIssueHint'),
+                        }, t('failIssueBig')) : null,
+                      ])
+                    }
                     if (kind === 'registryAuth') {
                       // npm 源返回 401/403：私有源需要凭据，或当前网络/IP 不被允许 —— 本机环境问题，
                       // 给「配认证 / 换回官方源 / 切公共镜像」指引，不引导提 Issue
@@ -404,6 +440,38 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       return h('div', { className: styles.failPrepareHint },
                         t(host ? 'failRegistryAuthHint' : 'failRegistryAuthHintNoHost', host ? { host } : undefined))
                     }
+                    if (kind === 'dshTooOld') {
+                      // 插件要求的 DSH 下限高于本机宿主：升级 DSH 即可，不属作者、也不属插件中心
+                      const info = dshTooOldInfoOf(r.message)
+                      return h('div', { className: styles.failPrepareHint },
+                        t('failDshTooOldHint', info ?? { pkg: shownRepo || r.repo || 'plugin', floor: '?', current: '?' }))
+                    }
+                    if (kind === 'localEnv') {
+                      // 未命中具体成因、但特征指向本机环境：给通用自查清单 + 系统诊断，默认不推给我们，
+                      // 只留小字反馈入口（判据是我们自己的启发式，可能误判）
+                      return h('div', null, [
+                        h('div', { className: styles.failPrepareHint }, t('failLocalEnvHint')),
+                        onRunDiagnostics ? h('button', { className: styles.failDiagBtn, onClick: onRunDiagnostics }, t('failNetworkRunDiag')) : null,
+                        h('div', null, [
+                          h('div', { className: styles.failPrepareHint }, t('failMisjudgeHint')),
+                          h('a', {
+                            className: styles.failMisjudgeLink,
+                            href: hubIssueUrl(shownRepo || r.repo, r.message, env, r.command, r.attempts, 'triage', action),
+                            target: '_blank',
+                            rel: 'noopener noreferrer',
+                            title: t('failHubIssueHint'),
+                          }, t('failMisjudgeLink')),
+                        ]),
+                      ])
+                    }
+                    if (kind === 'tlsTrust') {
+                      // 本机证书链不被信任（公司 SSL 审计 / 杀软 / 抓包代理）：给 CA 与镜像的具体处置，
+                      // 不引导提 Issue —— 换任何插件都会一样失败
+                      return h('div', null, [
+                        h('div', { className: styles.failPrepareHint }, t('failTlsTrustHint')),
+                        onRunDiagnostics ? h('button', { className: styles.failDiagBtn, onClick: onRunDiagnostics }, t('failNetworkRunDiag')) : null,
+                      ])
+                    }
                     if (kind === 'network') {
                       // 安装前网络探测 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
                       // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，
@@ -447,6 +515,13 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                         ]) : null,
                       ])
                     }
+                    if (kind === 'profileBundleMissing') {
+                      // profile 声明的某个 bundle 没装进 node_modules：宿主在安装前就中止，
+                      // 与本次插件无关 —— 给「让宿主补装 profile 依赖 / 重装应用」指引，不引导提 Issue
+                      const info = unresolvedBundleOf(r.message)
+                      return h('div', { className: styles.failPrepareHint },
+                        t('failProfileBundleMissingHint', { pkg: info?.pkg ?? 'unknown', profile: env?.profile ?? '<profile>' }))
+                    }
                     if (kind === 'hubState') {
                       // 插件中心的列表状态已过期（安装器自身守卫消息）：非插件问题、也不是 bug，只给可行动提示，不引导提 Issue
                       return h('div', null, [

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

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

package/src/client/hooks/useCatalog.ts

@@ -15,8 +15,8 @@ import type { HubAboutInfo, HubUpdateInfo, HubUpdateState } from '../types.ts'
 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, pickHubUpdate } from '../logic/release-age.ts'
+import { fetchInstalled, fetchNpmReleaseAge, type NpmReleaseInfo } from '../data/host.ts'
+import { isReleaseTooFresh, isUpdateOffered, pickHubUpdate } from '../logic/release-age.ts'
 import {
   hasUpdateOf, installedItemsOf, installedNameOf, installedVersionOf, npmPackageOf,
 } from '../logic/installed.ts'
@@ -25,8 +25,8 @@ import type { InstalledItem, InstalledVersionSignal } from '../logic/installed.t
 /** 插件市场自身仓库：DSH Plugin Hub 不显示在目录里（自己不进自己的插件列表） */
 const SELF_REPO = 'dshplugin/dsh-plugin-hub'
 
-/** 共享的空门禁集合：无暂缓包时复用，避免每次渲染新建 Set。 */
-const EMPTY_PACKAGES: ReadonlySet<string> = new Set<string>()
+/** 共享的空发布信息表：无候选包时复用，避免每次渲染新建对象。 */
+const EMPTY_RELEASES: Record<string, NpmReleaseInfo | null> = {}
 
 /** 市场各排序的默认方向：全部按倒序（Star/Fork 多、更新/收录近的在前） */
 const SORT_DEFAULT_DIR: Record<SortKey, 'asc' | 'desc'> = {
@@ -190,18 +190,18 @@ export function useCatalog(lang: LocaleId) {
   const installedVersion = (p: HubPlugin): string | null => installedVersionOf(p, versions)
 
   /**
-   * 供应链门禁状态：包名集合为当前「暂缓提示」的 npm 包（最新版本发布未满门槛）。
+   * 更新可用性校验状态：npm registry 上每个包的最新可安装版本与发布时间。
    * key 是这批候选包名的指纹，与已查出的 key 一致才算就绪，避免查询未回来时先显示更新。
    */
-  const [releaseAge, setReleaseAge] = useState<{ key: string; held: ReadonlySet<string> }>({ key: '', held: EMPTY_PACKAGES })
+  const [releaseAge, setReleaseAge] = useState<{ key: string; releases: Record<string, NpmReleaseInfo | null> }>({ key: '', releases: EMPTY_RELEASES })
 
-  /** 已安装项原始列表（未套门禁）：先算出来才能收集需要查发布时间的候选包名。 */
+  /** 已安装项原始列表（未套校验）：先算出来才能收集需要查发布信息的候选包名。 */
   const rawInstalledItems = useMemo<InstalledItem[]>(
     () => installedItemsOf(plugins, installed, versions, installPaths, loadedNames, dshCapableNames),
     [plugins, installed, versions, installPaths, loadedNames, dshCapableNames],
   )
 
-  /** 门禁候选：有更新、且有 npm 包名（更新走 npm registry）的已安装插件包名。 */
+  /** 校验候选：有更新、且有 npm 包名（更新走 npm registry）的已安装插件包名。 */
   const releaseAgeCandidates = useMemo(() => {
     const names = new Set<string>()
     for (const item of rawInstalledItems) {
@@ -212,53 +212,73 @@ export function useCatalog(lang: LocaleId) {
     return [...names].sort()
   }, [rawInstalledItems, versions])
   const releaseAgeKey = releaseAgeCandidates.join('\n')
+  /** 包名 → 已装版本：判断 npm 上最新版是否真的比已装版本新。 */
+  const installedByPackage = useMemo(() => {
+    const map = new Map<string, string>()
+    for (const item of rawInstalledItems) {
+      if (!item.plugin) continue
+      const pkg = npmPackageOf(item.plugin, versions)
+      const version = installedVersionOf(item.plugin, versions)
+      if (pkg !== null && version !== null) map.set(pkg, version)
+    }
+    return map
+  }, [rawInstalledItems, versions])
 
   useEffect(() => {
     if (releaseAgeKey === releaseAge.key) return
     if (releaseAgeCandidates.length === 0) {
-      setReleaseAge({ key: '', held: EMPTY_PACKAGES })
+      setReleaseAge({ key: '', releases: EMPTY_RELEASES })
       return
     }
     let cancelled = false
-    // 批量一次查询；失败/返回 null 时 held 为空 → 按原逻辑照常提示，网络问题不吃掉真实更新
+    // 批量一次查询；失败/返回 null 时按原逻辑照常提示，网络问题不吃掉真实更新
     void fetchNpmReleaseAge(releaseAgeCandidates).then((result) => {
       if (cancelled) return
-      const now = Date.now()
-      const held = new Set<string>()
-      for (const name of releaseAgeCandidates) {
-        const info = result?.[name]
-        if (info && isReleaseTooFresh(info.publishedAt, now)) held.add(name)
-      }
-      setReleaseAge({ key: releaseAgeKey, held })
+      setReleaseAge({ key: releaseAgeKey, releases: result ?? EMPTY_RELEASES })
     })
     return () => { cancelled = true }
   }, [releaseAgeKey, releaseAge.key])
 
-  /** 门禁结果是否已就绪（候选为空也算就绪）：未就绪时不写更新提醒，等查询回来再定。 */
+  /** 校验结果是否已就绪（候选为空也算就绪）：未就绪时不写更新提醒，等查询回来再定。 */
   const releaseAgeReady = releaseAgeKey === releaseAge.key
-  const heldPackages = releaseAgeReady ? releaseAge.held : EMPTY_PACKAGES
+
+  /**
+   * 不能提示更新的包：
+   *  - npm 上最新版还没过供应链门禁（发布不满 24h，pnpm 会静默回退，点了也装不上）；
+   *  - npm 上最新版并不高于已装版本 —— 更新走的是 `pkg@latest`，此时无论目录标到哪个 tag，
+   *    都不可能装上（作者可能只打了 GitHub release 没发 npm），提示只会变成永远点不掉的循环。
+   */
+  const updateBlocked = useMemo(() => {
+    const blocked = new Set<string>()
+    if (!releaseAgeReady) return blocked
+    const now = Date.now()
+    for (const pkg of releaseAgeCandidates) {
+      if (!isUpdateOffered(releaseAge.releases[pkg] ?? null, installedByPackage.get(pkg) ?? null, now)) blocked.add(pkg)
+    }
+    return blocked
+  }, [releaseAgeReady, releaseAgeCandidates, releaseAge.releases, installedByPackage])
 
   /**
    * 是否有更新：仅对已安装插件有意义。
    * 双信号判定——有 release 版本的比版本；无版本（repo 不打 tag）的比仓库最近更新时间
    * （repoUpdatedAt，ISO 字符串字典序 = 时间序），更新时间变新说明有新提交。
-   * 另加供应链门禁：npm 包最新版本发布未满门槛时视为暂缓，不打更新标记。
+   * 再用 npm registry 的实际最新版本复核：装不上的（太新 / 不比已装新）不打更新标记。
    */
   const hasUpdate = (p: HubPlugin): boolean => {
     if (!hasUpdateOf(p, installed, versions)) return false
     const pkg = npmPackageOf(p, versions)
-    return pkg === null || !heldPackages.has(pkg)
+    return pkg === null || !updateBlocked.has(pkg)
   }
 
-  /** 已安装项统一列表（目录元数据 + 运行时信息合并）：门禁命中的去掉更新标记，驱动「已安装」tab。 */
+  /** 已安装项统一列表（目录元数据 + 运行时信息合并）：被拦下的去掉更新标记，驱动「已安装」tab。 */
   const installedItems = useMemo<InstalledItem[]>(() => {
-    if (heldPackages.size === 0) return rawInstalledItems
+    if (updateBlocked.size === 0) return rawInstalledItems
     return rawInstalledItems.map((item) => {
       if (!item.hasUpdate || !item.plugin) return item
       const pkg = npmPackageOf(item.plugin, versions)
-      return pkg !== null && heldPackages.has(pkg) ? { ...item, hasUpdate: false } : item
+      return pkg !== null && updateBlocked.has(pkg) ? { ...item, hasUpdate: false } : item
     })
-  }, [rawInstalledItems, heldPackages, versions])
+  }, [rawInstalledItems, updateBlocked, versions])
 
   /**
    * Hub 自身更新状态：Hub 就是当前运行的应用（始终已安装，无需 installedName 命中）。

package/src/client/hooks/useTaskQueue.ts

@@ -36,6 +36,8 @@ export interface QueueTask {
   /** 安装时的目录信号快照（版本 + 仓库更新时间）：任务成功后在本地记录，供「有更新」比对 */
   version?: string
   updatedAt?: string
+  /** 服务端在成功终态带出的**实际**安装版本（读 profile 的 node_modules）：优先于目录版本写账本 */
+  installedVersion?: string
   /** pending 排队中 / running 执行中 / cancelling 取消中（客户端乐观过渡态） */
   status: 'pending' | 'running' | 'cancelling'
   progress: number
@@ -186,20 +188,36 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     setPendingRestarts(next)
   }
 
-  /** 向宿主记录某插件的安装时目录信号（version + updatedAt）；version 为空时清除记录（卸载）。 */
+  /** 向宿主记录某插件的安装时目录信号（version + updatedAt）。
+   *  版本未知时**不写**：服务端把空版本当作「卸载清理」会删掉整条记录（连 npm 包名映射一起），
+   *  刷新页面后任务丢了快照就会走到这条路径 —— 宁可保留旧记录，也不能把账本清空。 */
   const syncInstalledVersion = async (repo: string | null, version: string | undefined, updatedAt: string | undefined) => {
-    if (!repo) return
+    if (!repo || version === undefined || version === '') return
     try {
       await fetch('/dsh-plugin-hub/installed-version', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ repo, version: version ?? null, updatedAt }),
+        body: JSON.stringify({ repo, version, updatedAt }),
       })
     } catch {
       // 宿主未挂本地路由：静默忽略，仅本机展示受影响
     }
   }
 
+  /** 清除某仓库的版本记录（卸载成功后调用）：空版本是服务端的「删除记录」语义，只在这里显式发送。 */
+  const clearInstalledVersion = async (repo: string | null) => {
+    if (!repo) return
+    try {
+      await fetch('/dsh-plugin-hub/installed-version', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ repo, version: null }),
+      })
+    } catch {
+      // 同上：清理失败不影响卸载结果
+    }
+  }
+
   /** 后台任务结束（active 中消失后查终态确认）：完成 → 刷新安装表 + 结果视图/toast；失败 → 完整错误弹窗 */
   const finishQueueTask = (ok: boolean, q: QueueTask, lines: string[]) => {
     applyQueue((prev) => prev.filter((x) => x.id !== q.id))
@@ -207,13 +225,15 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       refreshInstalled()
       if (q.kind === 'uninstall') {
         // 卸载成功：清掉本地版本记录
-        void syncInstalledVersion(q.repo, undefined, undefined)
+        void clearInstalledVersion(q.repo)
         onUninstallDone(modalTaskRef.current === q.id, q.repo, q.needsRestart, q.needsReload ?? false)
       } else {
         // 安装成功：记录安装时的目录信号（版本 + 仓库更新时间），供「有更新」比对；
         // 同时缓存展示信息，待重启列表（服务端已登记）合并时直接补齐简介/版本
-        void syncInstalledVersion(q.repo, q.version, q.updatedAt)
-        pendingInfoRef.current.set(q.target, { desc: q.desc, version: q.version })
+        // 账本记**实际装上的版本**：目录版本可能滞后，抄目录字段会让「有更新」永久失真
+        const recordedVersion = q.installedVersion ?? q.version
+        void syncInstalledVersion(q.repo, recordedVersion, q.updatedAt)
+        pendingInfoRef.current.set(q.target, { desc: q.desc, version: recordedVersion })
         onInstallDone(modalTaskRef.current === q.id, q.repo, q.needsRestart, q.action === 'update', q.needsReload ?? false, q.bundleDeselected === true)
       }
     } else {
@@ -260,21 +280,23 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     let lines: string[] = []
     let attempts: string[] | undefined
     let bundleDeselected: boolean | undefined
+    let installedVersion: string | undefined
     try {
       const res = await fetch(`/dsh-plugin-hub/status?task=${q.id}`, { cache: 'no-store' })
       if (res.ok) {
-        const data = await res.json() as { task?: { status?: string; lines?: string[]; attempts?: string[]; needsRestart?: unknown; needsReload?: unknown; bundleDeselected?: unknown } }
+        const data = await res.json() as { task?: { status?: string; lines?: string[]; attempts?: string[]; needsRestart?: unknown; needsReload?: unknown; bundleDeselected?: unknown; installedVersion?: unknown } }
         const task = data.task
         if (task !== undefined) {
           status = task.status ?? 'failed'
           lines = task.lines ?? []
           attempts = Array.isArray(task.attempts) ? task.attempts : undefined
           bundleDeselected = task.bundleDeselected === true ? true : undefined
+          installedVersion = typeof task.installedVersion === 'string' && task.installedVersion !== '' ? task.installedVersion : undefined
           // 终态带出的「是否需要重启 / 是否只需刷新」覆盖本地（服务端 done 时按 loader 热挂/即时移除情况设置）
           const needsRestart = typeof task.needsRestart === 'boolean' ? task.needsRestart : q.needsRestart
           const needsReload = typeof task.needsReload === 'boolean' ? task.needsReload : (q.needsReload ?? false)
           if (status === 'done') {
-            const settled = { ...q, needsRestart, needsReload, bundleDeselected: bundleDeselected === true ? true : q.bundleDeselected }
+            const settled = { ...q, needsRestart, needsReload, bundleDeselected: bundleDeselected === true ? true : q.bundleDeselected, installedVersion }
             // 卸载成功走进度过渡动画；安装成功直接收尾
             if (q.kind === 'uninstall') settleDone(settled, lines)
             else finishQueueTask(true, settled, lines)