dsh-plugin 2.3.1 → 2.3.3

package/src/client/components/PluginHubSection.tsx

@@ -11,10 +11,10 @@ import type { MouseEvent } from 'react'
 import styles from '../styles/Header.module.css'
 import modalStyles from '../styles/Modal.module.css'
 import type { EnvInfo, HubPlugin, InstallChannel, SectionProps, ToastState } from '../types.ts'
-import { installCommandOf, repoFromInstallTarget } from '../logic/install-command.ts'
+import { installCommandOf, installTargetOf, repoFromInstallTarget } from '../logic/install-command.ts'
 import { PLUGIN_VERSION } from '../logic/constants.ts'
 import { ensurePluginCss } from '../logic/ensure-plugin-css.ts'
-import { getEnv, revealInstallFolder } from '../data/host.ts'
+import { fetchNpmReleaseAge, getEnv, revealInstallFolder } from '../data/host.ts'
 import { useCatalog } from '../hooks/useCatalog.ts'
 import { useLanguage } from '../hooks/useLanguage.ts'
 import { useSettings } from '../hooks/useSettings.ts'
@@ -76,9 +76,11 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
   const [confirmPlugin, setConfirmPlugin] = useState<HubPlugin | null>(null)
   /** 弹窗动作是否为「更新」：已安装插件点「更新」→ 走同一条 add 命令原位覆盖重装，文案区分安装/更新 */
   const [confirmIsUpdate, setConfirmIsUpdate] = useState(false)
-  /** Hub 自我更新指定的精确版本：连续发版时提示的是「已过供应链门禁」的旧一版，
-   *  安装必须钉在该版本上，否则又会被 @latest 带回门禁内的最新版。 */
+  /** 安装要锁定的精确版本：自我更新提示的版本、新安装的已过冷却期版本都要锁定，
+   *  否则 @latest 会被 pnpm 带回冷却期内的旧版。 */
   const [confirmPinVersion, setConfirmPinVersion] = useState<string | null>(null)
+  /** 冷却期查询的进行中序号：只采用最后一次弹窗的查询结果，避免切换插件后旧结果覆盖 */
+  const installPinSeq = useRef(0)
   /** 命令行安装确认弹窗：记录待安装的裸目标（npm 包名）——
    *  与应用商店同一套确认/进度/结果弹窗，提供时 plugin 传 null 走 customTarget 模式 */
   const [confirmCustomTarget, setConfirmCustomTarget] = useState<string | null>(null)
@@ -104,12 +106,12 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
   /** 安装/卸载完成后的结果视图：停留弹窗内，点「完成」关闭 */
   const [installDone, setInstallDone] = useState(false)
   const [uninstallDone, setUninstallDone] = useState(false)
-  /** 结果视图是否给「立即重启」：服务端任务终态带出。仅刷新解决不了的兜底场景
-   *  （热挂载失败 / 非 dsh 插件 / 更新）为 true；其余（热挂载成功、卸载已即时停用）为 false，
+  /** 结果视图是否给「立即重启」：服务端任务终态带出。仅刷新解决不了的例外场景
+   *  （热加载失败 / 非 dsh 插件 / 更新）为 true；其余（热加载成功、卸载已即时停用）为 false，
    *  结果视图只给「完成」，关闭时自动刷新页面生效 */
   const [installNeedsRestart, setInstallNeedsRestart] = useState(false)
   const [uninstallNeedsRestart, setUninstallNeedsRestart] = useState(false)
-  /** 结果视图是否显示「关闭后自动刷新」说明：插件已热挂进运行中 loader（安装）、或卸载后
+  /** 结果视图是否显示「关闭后自动刷新」说明：插件已热加载进运行中 loader（安装）、或卸载后
    *  插件面板仍残留在当前页面（卸载）。关闭弹窗即整页刷新，不给手动刷新按钮。 */
   const [installNeedsReload, setInstallNeedsReload] = useState(false)
   /** 市场自更新成功、但 profile 的 bundle 列表里已不含 dsh-plugin：结果页提示重新勾选 */
@@ -133,7 +135,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
     return () => { alive = false }
   }, [])
 
-  // 样式自愈：宿主重启/热更可能移除 <style> 标签而模块缓存未失效（factory 不重跑、CSS 不回来）。
+  // 样式自动恢复：宿主重启/热更可能移除 <style> 标签而模块缓存未失效（factory 不重跑、CSS 不回来）。
   // 挂载与每次切换视图时比对全局 CSS 清单，把缺失的样式补注入回去 —— 用户无需再手动点击恢复。
   useEffect(() => { ensurePluginCss() }, [view])
 
@@ -154,7 +156,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
       setInstallNeedsReload(reload)
       setInstallBundleDeselected(bundleDeselected === true)
       if (viaModal) setInstallDone(true)
-      // 弹窗外的后台安装：给结果 toast；需要页面重载时（热挂载的客户端 UI）读完后自动刷新
+      // 弹窗外的后台安装：给结果 toast；需要页面重载时（热加载的客户端 UI）读完后自动刷新
       else setToast({
         id: Date.now(),
         kind: reload ? 'installedReload' : needsRestart ? 'done' : 'installedLive',
@@ -191,8 +193,8 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
       // 失败自动写入通知记录：任务在后台结束时没人盯着也能留痕。
       // 存原始 repo（可能只是裸包名）而非反查结果 —— 反查只服务于提 Issue，
       // 通知中心的展示反查由 NotificationsModal 做、查不到会回退显示原始值，
-      // 若这里就丢掉原始值，通知里会连名字都看不到；action 区分「安装失败/更新失败」
-      setNotifications(addFailure({ kind, action: update ? 'update' : 'install', repo: repo ?? '', message, command, attempts }))
+      // 若这里就丢掉原始值，通知里会连名字都看不到；action 按任务类型区分「安装/更新/卸载失败」
+      setNotifications(addFailure({ kind, action: update ? 'update' : kind === 'uninstall' ? 'uninstall' : 'install', repo: repo ?? '', message, command, attempts }))
     },
     installPlugin: confirmPlugin,
     installCustomTarget: confirmCustomTarget,
@@ -237,7 +239,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
   useEffect(() => {
     if (startupCheckedRef.current) return
     if (!settingsReady || catalog.plugins === null || catalog.failed) return
-    // 供应链门禁结果未就绪时先等：否则刚发布的插件会先写进通知中心，冒出装不上的更新提醒
+    // 发布冷却期结果未就绪时先等：否则刚发布的插件会先写进通知中心，冒出装不上的更新提醒
     if (!catalog.releaseAgeReady) return
     startupCheckedRef.current = true
     if (!hubSettings.checkUpdatesOnStart) return
@@ -274,7 +276,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
     return () => window.clearTimeout(timer)
   }, [toast])
 
-  /** 复制文本到剪贴板，返回是否成功（Clipboard API + 隐藏 textarea 兜底）。 */
+  /** 复制文本到剪贴板，返回是否成功（Clipboard API + 隐藏 textarea 作为后备）。 */
   const doCopy = async (text: string): Promise<boolean> => {
     try {
       await navigator.clipboard.writeText(text)
@@ -298,7 +300,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
     }
   }
 
-  /** 命令行安装目标是否已安装（与服务端 already 判定同口径）：GitHub 地址按仓库身份匹配
+  /** 命令行安装目标是否已安装（与服务端 already 判定同一套规则）：GitHub 地址按仓库身份匹配
    *  （归一化后比对已装项的 repo/spec），npm 包名按依赖 key 直查。命中 → 弹窗转「更新」语义
    *  （mode=update 放行覆盖重装），避免重复点击撞 409 报错。 */
   const customTargetInstalled = (raw: string): boolean => {
@@ -321,9 +323,9 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
   }
 
   /** 弹窗动作一：复制安装命令到剪贴板，引导去终端粘贴执行（npm 安装显示包名命令）。 */
-  const copyCommand = async (p: HubPlugin) => {
+  const copyCommand = async (p: HubPlugin, version?: string) => {
     const repo = p.source?.repo ?? ''
-    const ok = await doCopy(installCommandOf(p))
+    const ok = await doCopy(installCommandOf(p, false, version))
     if (ok) {
       setCopied(repo)
       setToast({ id: Date.now(), kind: 'copied' })
@@ -332,6 +334,21 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
     setConfirmPlugin(null)
   }
 
+  /** 新安装先查「已过 pnpm 发布冷却期」的版本：命令条与执行都锁定它，
+   *  否则 pnpm 会把发布未满 24h 的最新版不提示地回退成很旧的版本。查不到则不锁定，由服务端再解析一次。 */
+  const resolveInstallPin = (p: HubPlugin) => {
+    // 目录下发了官方安装命令的条目（CLI-only / 人工干预）只展示该命令，追加版本会改坏它
+    if (p.install?.command !== undefined && p.install.command !== '') return
+    const pkg = installTargetOf(p)
+    if (!pkg) return
+    const seq = ++installPinSeq.current
+    void fetchNpmReleaseAge([pkg]).then((res) => {
+      if (installPinSeq.current !== seq) return
+      const version = res?.[pkg]?.installable?.version
+      if (version !== undefined && version !== '') setConfirmPinVersion(version)
+    })
+  }
+
   /** 卸载弹窗动作：复制卸载命令，万一直接卸载失败可去终端手动执行。
    *  自定义安装（无目录数据）按已安装项包名直卸，同样给复制通道。 */
   const copyUninstallCommand = async () => {
@@ -348,7 +365,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
   }
 
   /** 「立即重启」：POST 同源 /restart，宿主进程自杀重启；随后轮询服务恢复后整页刷新。
-   *  只在刷新解决不了的兜底场景（热挂载失败 / 非 dsh 插件 / 更新）出现。
+   *  只在刷新解决不了的例外场景（热加载失败 / 非 dsh 插件 / 更新）出现。
    *  桌面端宿主归应用壳管（服务端回 `desktop: true` 且不重启）：不轮询，改提示退出重开。 */
   const requestRestart = async () => {
     if (restarting) return
@@ -363,7 +380,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
       /* 服务已终止，无需处理 */
     }
     if (desktop) {
-      // 宿主不会重启，轮询等不到新服务：直接给出正确口径
+      // 宿主不会重启，轮询等不到新服务：直接给出正确规则
       setRestarting(false)
       setToast({ id: Date.now(), kind: 'restartDesktop' })
       return
@@ -392,7 +409,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
   }
 
   const { total, installedName, installedVersion, hasUpdate } = catalog
-  // 统计数字：官网 /api/stats.json 优先；拉取失败时用已加载列表兜底，避免展示 undefined。
+  // 统计数字：官网 /api/stats.json 优先；拉取失败时改用已加载列表，避免展示 undefined。
   const statsTotal = catalog.stats?.total ?? total
   const statsVerified = catalog.stats?.verified ?? 0
 
@@ -431,7 +448,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
         noticeCount: notifications.length + queue.queue.length + queue.pendingRestarts.length,
         onOpenNotifications: () => {
           // 打开弹窗时补齐更新提醒（受「启动时检查更新」开关约束）：同一版本只一条，
-          // 清空/删除后重开仍恢复，直到插件更新完成才消失；门禁结果未就绪时先不写，避免提示装不上的更新
+          // 清空/删除后重开仍恢复，直到插件更新完成才消失；冷却期查询结果未就绪时先不写，避免提示装不上的更新
           if (hubSettings.checkUpdatesOnStart && catalog.releaseAgeReady) syncUpdateNotices()
           setShowNotifications(true)
         },
@@ -451,12 +468,17 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
               ? t('pluginsTotal', { n: count })
               : t('filterResults', { n: count }),
           onInstall: (p, opts) => {
+            const update = opts?.update ?? false
             setInstallDone(false)
-            setConfirmIsUpdate(opts?.update ?? false)
+            setConfirmIsUpdate(update)
             setConfirmPinVersion(null)
+            // 本次弹窗重新开始：作废上一次还没返回的冷却期查询
+            ++installPinSeq.current
             // 与卸载一致：重置弹窗关联任务，避免新弹窗误匹配到进行中的任务而禁用安装按钮
             queue.clearModalTask()
             setConfirmPlugin(p)
+            // 更新走 @latest 语义（客户端已按冷却期筛选），只有新安装需要锁定冷却期内可用的版本
+            if (!update) resolveInstallPin(p)
           },
           onUninstall: (p) => {
             setUninstallDone(false)
@@ -489,6 +511,8 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
               setInstallDone(false)
               setConfirmIsUpdate(true)
               setConfirmPinVersion(null)
+              // 更新不锁定版本：作废可能还没返回的新安装冷却期查询
+              ++installPinSeq.current
               queue.clearModalTask()
               setConfirmPlugin(item.plugin)
             },
@@ -552,7 +576,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
     // 暂缓提示显示同一标题但只给「稍后再说」，无更新显示当前版本 + 记录 + 「已是最新」。
     // 版本号与本机版本一律由 hubUpdateState / hubCurrentVersion 决定，不用远端版号冒充本机。
     showHubUpdate && h(HubUpdateModal, {
-      // 提示目标是「已过供应链门禁」的版本，可能不是 latest —— 展示它与它的变更记录
+      // 提示目标是「已过发布冷却期」的版本，可能不是 latest —— 展示它与它的变更记录
       info: catalog.hubUpdateTarget ?? catalog.hubUpdateInfo ?? { version: PLUGIN_VERSION },
       state: catalog.hubUpdateState,
       currentVersion: catalog.hubCurrentVersion,
@@ -565,8 +589,10 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
         if (hubEntry) {
           setInstallDone(false)
           setConfirmIsUpdate(true)
-          // 钉住本次提示的版本：最新版可能仍在门禁内，@latest 会被 pnpm 拒绝
+          // 锁定本次提示的版本：最新版可能仍在冷却期内，@latest 会被 pnpm 拒绝
           setConfirmPinVersion(catalog.hubUpdateTarget?.version ?? null)
+          // 作废可能还没返回的新安装冷却期查询，避免它覆盖本次锁定的版本
+          ++installPinSeq.current
           queue.clearModalTask()
           setConfirmPlugin(hubEntry)
         }
@@ -574,7 +600,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
     }),
     // 「关注我们」弹窗：GitHub 图标后按钮点击打开 —— 平台介绍 + 用户反馈群二维码，
     // 内容由 dsh-update Worker 的 /about 接口以 Markdown 形式推送，作者随时可改，非写死。
-    // Worker 未推送（info 为 null）时弹窗仍能打开并展示兜底文案，不影响其他功能。
+    // Worker 未推送（info 为 null）时弹窗仍能打开并展示备用文案，不影响其他功能。
     showAbout && h(AboutModal, {
       info: catalog.hubAboutInfo ?? null,
       lang,
@@ -668,21 +694,26 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
       langPath,
       restarting,
       update: confirmIsUpdate,
+      pinVersion: confirmPinVersion ?? undefined,
       // 仅命令行插件（webInstallable=false / 人工干预 manualInstall）：弹窗只展示命令供复制，不提供一键安装
       cliOnly: confirmPlugin.install?.webInstallable === false || confirmPlugin.install?.manualInstall === true,
       submitting: queue.submitting,
       needsRestart: installNeedsRestart,
       needsReload: installNeedsReload,
       bundleDeselected: installBundleDeselected,
-      // 结果弹窗关闭即生效：安装热挂载的插件要页面重载才渲染客户端 UI → 自动刷新，无需用户点按钮
+      // 结果弹窗关闭即生效：安装热加载的插件要页面重载才渲染客户端 UI → 自动刷新，无需用户点按钮
       onClose: () => {
         const reload = installDone && installNeedsReload
         setConfirmPlugin(null)
         setInstallBundleDeselected(false)
         if (reload) window.location.reload()
       },
-      onCopy: () => copyCommand(confirmPlugin),
-      onInstall: () => queue.installNow(confirmPlugin, confirmIsUpdate ? { update: true, pinVersion: confirmPinVersion ?? undefined } : undefined),
+      onCopy: () => copyCommand(confirmPlugin, confirmPinVersion ?? undefined),
+      onInstall: () => queue.installNow(confirmPlugin, {
+        update: confirmIsUpdate,
+        // 新安装锁定已过冷却期的版本：查询尚未回来时为空，服务端会自行解析
+        pinVersion: confirmPinVersion ?? undefined,
+      }),
       // 重启：结果视图「立即重启」也会中断进行中的任务 → 先弹重启确认弹窗
       onRestart: () => setShowRestartConfirm(true),
     }),
@@ -825,7 +856,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
       onRunDiagnostics: openDiagnostics,
       onClose: () => setErrorMsg(null),
     }),
-    // 待重启确认弹窗：已安装列表行内「重启」按钮点击后弹出（兜底场景），单个「立即重启」，关闭即视为稍后
+    // 待重启确认弹窗：已安装列表行内「重启」按钮点击后弹出（例外场景），单个「立即重启」，关闭即视为稍后
     showRestartConfirm && h(RestartConfirmModal, {
       t,
       restarting,

package/src/client/components/catalog/CatalogList.tsx

@@ -28,7 +28,7 @@ export function CatalogList({ plugins, failed, visible, total, t, langPath, relo
   installedName: (p: HubPlugin) => string | null
   installedVersion: (p: HubPlugin) => string | null
   hasUpdate: (p: HubPlugin) => boolean
-  /** 更新被供应链门禁暂缓时的可重试时刻（毫秒）；无则 null */
+  /** 更新暂缓（新版本还没过冷却期）的可重试时刻（毫秒）；无则 null */
   updatePendingUntil: (p: HubPlugin) => number | null
   langKey: LocaleId
   onInstall: (p: HubPlugin, opts?: { update?: boolean }) => void

package/src/client/components/catalog/PluginCard.tsx

@@ -19,9 +19,9 @@ export function PluginCard({ plugin: p, copied, installedName, installedVersion,
   installedName: (p: HubPlugin) => string | null
   /** 已安装版本号（安装时从目录信号记录；无 release 的仓库为空，无版本号可展示） */
   installedVersion: (p: HubPlugin) => string | null
-  /** 已安装且目录有更新（有版本比版本、无版本比仓库更新时间）；门禁复核未就绪时为 false */
+  /** 已安装且目录有更新（有版本比版本、无版本比仓库更新时间）；冷却期复核未就绪时为 false */
   hasUpdate: (p: HubPlugin) => boolean
-  /** 更新被供应链门禁暂缓时的可重试时刻（毫秒）；无则 null */
+  /** 更新暂缓（新版本还没过冷却期）的可重试时刻（毫秒）；无则 null */
   updatePendingUntil: (p: HubPlugin) => number | null
   t: Translate
   langKey: LocaleId
@@ -35,7 +35,7 @@ export function PluginCard({ plugin: p, copied, installedName, installedVersion,
   const pkg = installedName(p)
   const isInstalled = pkg !== null
   const update = hasUpdate(p)
-  // 门禁暂缓：更新确实存在但现在装不上，给确切时刻而不是让徽标静默消失
+  // 冷却期未到：更新确实存在但现在装不上，给确切时刻而不是让徽标悄悄消失
   const pendingUntil = isInstalled && !update ? updatePendingUntil(p) : null
   // 版本号展示：已安装 → 当前已装版本（最能反映用户状态）；未安装 → 目录最新版本
   const versionShown = isInstalled ? installedVersion(p) : p.version

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

@@ -35,7 +35,7 @@ export function AboutModal({ info, lang, t, onClose }: {
   t: Translate
   onClose: () => void
 }) {
-  // 内容：字符串直接使用；{zh,en} 对象按界面语言取，缺哪种补哪种，全缺则展示兜底文案。
+  // 内容：字符串直接使用；{zh,en} 对象按界面语言取，缺哪种补哪种，全缺则展示备用文案。
   // Worker 未推送（info 为 null / content 为空）时弹窗仍能打开，显示「暂未发布」而非报错。
   const contentRaw = info
     ? typeof info.content === 'string'
@@ -50,7 +50,7 @@ export function AboutModal({ info, lang, t, onClose }: {
   // 同一次打开内保持稳定，避免父组件重渲染导致图片被反复重载。
   const qrTs = useMemo(() => Date.now(), [])
   const contentHtml = contentRaw.trim() ? renderMarkdown(bustQrCache(contentRaw, qrTs)) : null
-  // 更新时间：ISO 字符串转本地可读格式；非法值静默隐藏
+  // 更新时间：ISO 字符串转本地可读格式；非法值直接隐藏
   let updated: string | null = null
   if (info?.updatedAt) {
     const d = new Date(info.updatedAt)

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

@@ -23,9 +23,9 @@ export function ConfirmDialog({ type, title, desc, confirmLabel, cancelLabel, bu
   desc?: string
   confirmLabel: string
   cancelLabel?: string
-  /** 确认动作在途：禁用按钮防止二次点击 */
+  /** 确认动作进行中：禁用按钮防止二次点击 */
   busy?: boolean
-  /** 在途时确认按钮文案（如「清空中…」）；缺省沿用 confirmLabel */
+  /** 进行中时确认按钮文案（如「清空中…」）；缺省沿用 confirmLabel */
   busyLabel?: string
   t: Translate
   onConfirm: () => void

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

@@ -7,8 +7,8 @@
  *  - 有更新（state='available'）：标题「有新版本」，展示新版本号、发布时间与 Worker 下发的
  *    Markdown 变更记录（renderMarkdown 渲染，双语言按界面语言取 {zh,en} 对象），
  *    按钮「稍后再说 / 直接更新」，确认后进入安装弹窗执行覆盖重装。
- *  - 暂缓提示（state='pending'）：远端确有新版本，但发布未满供应链安全门槛，pnpm 此时会
- *    静默回退到旧版本 —— 仍按「有新版本」展示，只给「稍后再说」，并说明稍后会自动提示。
+ *  - 暂缓提示（state='pending'）：远端确有新版本，但发布还不满冷却期，pnpm 此时会
+ *    不提示地回退到旧版本 —— 仍按「有新版本」展示，只给「稍后再说」，并说明稍后会自动提示。
  *  - 无更新 / 信息缺失（state='latest' / 'none'）：标题「当前版本」，版本号与本机版本取自
  *    currentVersion（构建注入的 PLUGIN_VERSION），**不得**用远端最新版号冒充本机版本。
  * 点击头部版本号（或「可更新」徽标）打开 —— 无论有无更新都能看到更新内容。
@@ -59,7 +59,7 @@ export function HubUpdateModal({ info, state, currentVersion, lang, t, onProceed
   const notesHtml = notesBody.trim() ? renderMarkdown(notesBody) : null
   // 说明只在需要动作或需要解释时出现：已是最新时胶囊已说明状态，不再重复一句话
   const desc = hasUpdate ? t('hubUpdateDesc') : pending ? t('hubPendingDesc') : null
-  // 发布时间：ISO 字符串转本地可读格式；非法值静默隐藏
+  // 发布时间：ISO 字符串转本地可读格式；非法值直接隐藏
   let published: string | null = null
   if (info.publishedAt) {
     const d = new Date(info.publishedAt)

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

@@ -70,7 +70,7 @@ export function InstalledDetailModal({ item, t, lang, langPath, onClose, onUpdat
               ? t('versionUpHint', { from: item.installedVersion, to: item.catalogVersion })
               : t('updateAvailableHint'))
           : item.pendingUntil != null
-            // 门禁暂缓：给确切可重试时刻，而不是让「有更新」静默消失
+            // 冷却期未到：给确切可重试时刻，而不是让「有更新」悄悄消失
             ? h('div', { className: styles.detailUpdateHint }, t('updatePending', { time: clockTime(item.pendingUntil) }))
             : null,
         // 详情信息网格：分类 / 状态 / 版本 / 收录入口 / 包名 / 统计 / 安装路径 / 安装时间 / 最后更新

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

@@ -70,7 +70,7 @@ export function LogsPathModal({ t, defaultPath, currentPath, onSaved, onClose }:
     }
   }
 
-  /** 选择目录：系统对话框从默认位置打开，选中路径回填输入框（仍可手改）。 */
+  /** 选择目录：系统对话框从默认位置打开，选中路径填入输入框（仍可手改）。 */
   const browse = async () => {
     if (browsing) return
     setBrowsing(true)

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

@@ -118,7 +118,7 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                     h('span', { className: styles.pendingRowStatus },
                       p.kind === 'uninstall' ? t('restartPendingHintUninstall') : t('restartPendingHint')),
                     h('span', { className: styles.pendingRowActions },
-                      // 兜底项：刷新解决不了（热挂载失败 / 非 dsh 插件 / 更新）才登记待重启；
+                      // 例外项：刷新解决不了（热加载失败 / 非 dsh 插件 / 更新）才登记待重启；
                       // 关闭本弹窗即视为「稍后」，只在真正需要时给单个「立即重启」
                       h('button', {
                         className: styles.restartNow,
@@ -376,7 +376,7 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       ])
                     }
                     if (kind === 'hostIncompatible') {
-                      // 宿主版本门禁：插件声明的兼容范围不含当前 dsh 版本，安装前就被拒绝。
+                      // 宿主版本要求：插件声明的兼容范围不含当前 dsh 版本，安装前就被拒绝。
                       // 作者能修（把该版本加进兼容清单），故引导到作者仓库；同时说明本地可临时授权
                       const version = /incompatible with dsh\s+([^\s:;,]+)/i.exec(r.message ?? '')?.[1] ?? ''
                       return h('div', null, [

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

@@ -20,9 +20,9 @@ import type { FailureAction } from '../../logic/failures.ts'
 
 /** 完成结果视图：绿色对勾 + 标题/描述；
  *  终态只有两种：
- *  - needsRestart=true（刷新解决不了：热挂载失败 / 非 dsh 插件 / 更新）→ 仅一个「立即重启」
+ *  - needsRestart=true（刷新解决不了：热加载失败 / 非 dsh 插件 / 更新）→ 仅一个「立即重启」
  *    按钮（重启会中断进行中的任务，故仍需用户确认），关闭即放弃；
- *  - 其余（含 needsReload=true 的「已热挂载、仅剩客户端 UI」）→ 仅「完成」按钮：关闭结果弹窗时
+ *  - 其余（含 needsReload=true 的「已热加载、仅剩客户端 UI」）→ 仅「完成」按钮：关闭结果弹窗时
  *    上层自动刷新页面让插件生效，不再给「稍后/立即刷新」手动选择。 */
 function ResultView({
   title, desc, t, restarting, needsRestart, needsReload, bundleDeselected, onRestart, onClose,
@@ -32,7 +32,7 @@ function ResultView({
   t: Translate
   restarting: boolean
   needsRestart: boolean
-  /** 仅刷新页面即生效（插件已热挂载）：给一句自动刷新说明，按钮仍是「完成」 */
+  /** 仅刷新页面即生效（插件已热加载）：给一句自动刷新说明，按钮仍是「完成」 */
   needsReload?: boolean
   /** 市场自更新成功、但 bundle 被取消勾选：重启后市场不会出现，提示重新勾选 */
   bundleDeselected?: boolean
@@ -90,13 +90,15 @@ export interface InstallModalProps {
   restarting: boolean
   /** 已安装插件的覆盖更新（走同一条 add 命令原位重装，文案区分安装/更新） */
   update: boolean
+  /** 已过发布冷却期的安装版本：命令条带上它，手抄执行与一键安装结果一致（未查到时不传） */
+  pinVersion?: string
   /** 仅命令行插件（webInstallable=false）：不提供一键安装，只展示命令供复制到 dsh 终端 */
   cliOnly: boolean
-  /** 安装请求在途（fetch 等待响应）：此时任务尚未入队，需禁用确认按钮防止二次点击 */
+  /** 安装请求进行中（fetch 等待响应）：此时任务尚未入队，需禁用确认按钮防止二次点击 */
   submitting: boolean
   /** 完成结果是否需重启才生效：true → 仅给「立即重启」；false → 仅「完成」（关闭即自动刷新） */
   needsRestart: boolean
-  /** 完成结果是否只需刷新页面即生效（插件已热挂载）：true → 结果视图显示自动刷新说明 */
+  /** 完成结果是否只需刷新页面即生效（插件已热加载）：true → 结果视图显示自动刷新说明 */
   needsReload: boolean
   /** 市场自更新成功、但 profile 的 bundle 列表已不含 dsh-plugin：结果页提示重新勾选 */
   bundleDeselected?: boolean
@@ -112,7 +114,7 @@ export interface InstallModalProps {
  * 目录插件与命令行安装（customTarget 模式）共用同一套确认/进度/结果流程。
  */
 export function InstallModal(props: InstallModalProps) {
-  const { plugin, customTarget, globalNpm, done, task, t, langPath, restarting, submitting, update, cliOnly, needsRestart, needsReload, bundleDeselected, onClose, onCopy, onInstall, onRestart } = props
+  const { plugin, customTarget, globalNpm, done, task, t, langPath, restarting, submitting, update, pinVersion, cliOnly, needsRestart, needsReload, bundleDeselected, onClose, onCopy, onInstall, onRestart } = props
   const busy = submitting || (task !== null && (task.status === 'pending' || task.status === 'running'))
   // 进行中标题带上插件名（中文「XX 插件安装中」；英文状态词在前更自然），并用状态色区分；
   // 命令行安装无插件元数据 → 直接用输入的目标展示；全局 npm 安装 → 包列表空格拼接
@@ -191,7 +193,7 @@ export function InstallModal(props: InstallModalProps) {
             h('span', { className: styles.modalCmdText },
               globalNpm !== undefined && globalNpm.length > 0
                 ? `npm install -g ${globalNpm.join(' ')}`
-                : customTarget ? `pnpm add ${customTarget}` : installCommandOf(plugin!)),
+                : customTarget ? `pnpm add ${customTarget}` : installCommandOf(plugin!, false, pinVersion)),
             h('span', { className: styles.modalCmdCopy }, h(CopyIcon), t('copyCmdLabel')),
           ),
           // 全局 npm 安装说明：装的是系统级 CLI 工具，不进插件列表、无需重启宿主
@@ -236,7 +238,7 @@ export interface UninstallModalProps {
   t: Translate
   langPath: string
   restarting: boolean
-  /** 卸载请求在途（fetch 等待响应）：此时任务尚未入队，需禁用确认按钮防止二次点击 */
+  /** 卸载请求进行中（fetch 等待响应）：此时任务尚未入队，需禁用确认按钮防止二次点击 */
   submitting: boolean
   /** 完成结果是否需重启才生效：true（停用失败等刷新解决不了的场景）→ 仅给「立即重启」；
    *  false（loader 已即时停用）→ 仅「完成」，关闭即自动刷新页面摘除插件面板 */
@@ -270,7 +272,7 @@ export function UninstallModal(props: UninstallModalProps) {
       h('div', { className: styles.modalHead },
         h('div', {
           className: busy
-            // 注意 task 判空：submitting（请求在途）时任务尚未入队，task 为 null，不能直接解引用
+            // 注意 task 判空：submitting（请求进行中）时任务尚未入队，task 为 null，不能直接解引用
             ? `${styles.modalTitle} ${task !== null && task.status === 'pending' ? styles.modalTitleQueued : styles.modalTitleBusy}`
             : styles.modalTitle,
         }, title),
@@ -365,7 +367,7 @@ export function ErrorModal({ message, repo, action, command, attempts, t, env, o
   // 复制完整错误：实际执行/尝试过的安装命令（如有）+ 完整错误正文。
   // 只复制 message 会丢上下文 —— 命令行安装输入的目标、执行过的命令都在 command/attempts 里，
   // 光拷一句「unsupported install target」出去没人看得懂
-  // 展示与复制都用展开后的文本：宿主门禁消息里的 peerDependencies 是压缩 JSON，
+  // 展示与复制都用展开后的文本：宿主兼容性提示里的 peerDependencies 是压缩 JSON，
   // 原样展示会挤成一整行；格式化只影响可读性，不改变归类与上报逻辑
   const displayMessage = formatFailureMessage(message)
   const copyText = [
@@ -509,7 +511,7 @@ export function ErrorModal({ message, repo, action, command, attempts, t, env, o
                 }, t('failIssueBig')) : null,
               ])
               : failureKind === 'hostIncompatible'
-              // 宿主版本门禁：插件声明的兼容范围不含当前 dsh 版本，安装前就被宿主拒绝。
+              // 宿主版本要求：插件声明的兼容范围不含当前 dsh 版本，安装前就被宿主拒绝。
               // 这是作者能修的（把该版本加进兼容清单），故直接引导到作者仓库；同时说明本地可临时授权
               ? h('div', null, [
                 (() => {

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

@@ -26,7 +26,7 @@ import { CloseIcon, HelpIcon } from '../ui/icons.tsx'
 const NPM_PACKAGE_RE = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/
 
 /** npm 全局安装命令（官方 README 格式，如 `npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui`）——
- * 提取 -g 之后的包列表；任一包名非法返回 null（交给格式错误提示）。与 server 端 globalNpmPackagesOf 口径一致。 */
+ * 提取 -g 之后的包列表；任一包名非法返回 null（交给格式错误提示）。与 server 端 globalNpmPackagesOf 规则一致。 */
 const NPM_GLOBAL_CMD_RE = /^npm\s+(?:install|i)\s+(?:-g|--global)\s+(.+)$/i
 
 /** 常规 npm/pnpm 安装命令（装进当前 profile，如 `npm install lodash`、`pnpm add @scope/pkg`）——
@@ -34,7 +34,7 @@ const NPM_GLOBAL_CMD_RE = /^npm\s+(?:install|i)\s+(?:-g|--global)\s+(.+)$/i
 const NPM_INSTALL_CMD_RE = /^(?:npm\s+(?:install|i)|pnpm\s+(?:add|i|install))\s+(.+)$/i
 
 /** 空格分隔的包列表：逐个按 npm 包名语法校验 + 拒绝以 - 开头的 token（npm 会把 --xxx 当参数而非包名），
- * 任一非法返回 null（交给格式错误提示）。与 server 端 globalNpmPackagesOf 同口径。 */
+ * 任一非法返回 null（交给格式错误提示）。与 server 端 globalNpmPackagesOf 同一套规则。 */
 function splitPackages(raw: string): string[] | null {
   const packages = raw.trim().split(/\s+/).filter((p) => p !== '')
   if (packages.length === 0 || packages.some((p) => !NPM_PACKAGE_RE.test(p) || p.startsWith('-'))) return null

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

@@ -122,11 +122,11 @@ function InstalledRow({ item, t, langKey, canReveal, revealLabel, pendingRestart
         item.hasUpdate
           ? h('span', { className: styles.updateBadge, title: t('updateAvailableHint') }, t('updateAvailable'))
           : item.pendingUntil != null
-            // 门禁暂缓：更新存在但还装不上，给确切时刻，避免看起来「已是最新」
+            // 冷却期未到：更新存在但还装不上，给确切时刻，避免看起来「已是最新」
             ? h('span', { className: styles.updateBadge, title: t('updatePendingHint') }, t('updatePending', { time: clockTime(item.pendingUntil) }))
             : null,
       ),
-      // 右上角 Star / Fork：与插件市场列表同一口径，装之前看过的热度在已安装里也能对照。
+      // 右上角 Star / Fork：与插件市场列表同一规则，装之前看过的热度在已安装里也能对照。
       // 自定义安装没有目录元数据（plugin === null），没有可展示的统计
       item.plugin
         ? h('div', { className: styles.rowStats },

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

@@ -8,7 +8,7 @@
  *
  * 各分组对应本地服务端实际强制的行为：
  *   更新与源 —— 启动检查更新 / npm 镜像 / HTTP 代理（都接进安装命令链路）
- *   安全与信任 —— 受限的自定义安装（服务端 403 门禁）
+ *   安全与信任 —— 受限的自定义安装（服务端 403 拦截）
  *   诊断 —— 实时连通性探测 + 环境快照
  *   日志 —— 系统日志查看器 + 存放位置
  */
@@ -176,7 +176,7 @@ export function SettingsView({ t, settings, update, reset, env, onCopy, openSect
         className: `${styles.controlDropdown} ${dropdownStyles.dropdownFill}`,
       }),
     }),
-    // 自动换源：只在公共源之间切换；自定义/内网源不降级，避免私有包名泄露
+    // 自动换源：只在公共源之间切换；自定义/内网源不换源，避免私有包名泄露
     h(SettingRow, {
       title: t('settingsRegistryFallback'),
       desc: t('settingsRegistryFallbackDesc'),
@@ -214,7 +214,7 @@ export function SettingsView({ t, settings, update, reset, env, onCopy, openSect
   )
 
   const securityCard = h('div', { className: styles.card },
-    // 安全与信任：命令行安装的开关（仅 NPM 包）—— 服务端按通道门禁 403 拦截
+    // 安全与信任：命令行安装的开关（仅 NPM 包）—— 服务端按通道校验 403 拦截
     //（npm 目标吃 enableNpmInstall）；目录内收录的插件安装不受影响（默认开启）
     h(SettingRow, {
       title: t('settingsEnableNpm'),

package/src/client/data/catalog.ts

@@ -10,7 +10,7 @@ import type { HubPlugin, LocaleId } from '../types.ts'
 import { normalize } from '../logic/normalize.ts'
 
 // 目录/统计数据经服务端 /catalog 代理路由获取（curl 子进程注入设置里的代理），
-// 与 npm / git 安装通道同一代理口径 —— 浏览器不直连 api.dsh-plugin.org。
+// 与 npm / git 安装通道同一代理规则 —— 浏览器不直连 api.dsh-plugin.org。
 const PROXY_BASE = '/dsh-plugin-hub/catalog'
 // refresh=1：跳过服务端 1 小时缓存直接回源（失败仍回退旧缓存），供「强制刷新」使用
 const PLUGINS_URL = (lang: LocaleId, refresh: boolean) => `${PROXY_BASE}?lang=${lang}${refresh ? '&refresh=1' : ''}`

package/src/client/data/host.ts

@@ -48,9 +48,11 @@ export async function fetchInstalled(): Promise<HostInstalled | null> {
 export interface NpmReleaseInfo {
   version: string
   publishedAt: string
+  /** 已过 pnpm 发布冷却期的最高稳定版：安装/展示命令锁定它；无可锁定版本时为 null。 */
+  installable?: NpmReleaseInfo | null
 }
 
-/** 批量查询已安装插件 npm 包的最新版本发布时间（供应链门禁用）；失败返回 null（调用方按原逻辑照常提示）。 */
+/** 批量查询已安装插件 npm 包的最新版本发布时间（发布冷却期用）；失败返回 null（调用方按原逻辑照常提示）。 */
 export async function fetchNpmReleaseAge(packages: string[]): Promise<Record<string, NpmReleaseInfo | null> | null> {
   if (packages.length === 0) return {}
   try {

package/src/client/data/hub.ts

@@ -4,7 +4,7 @@
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
  * Hub 元数据仓库：自我更新检查与「关注我们」内容背后的 Cloudflare Worker 接口。
- * 失败降级为 null —— 由调用方决定如何兜底（不显示徽标、占位文案），绝不抛错。
+ * 失败降级为 null —— 由调用方决定失败时如何显示（不显示徽标、占位文案），绝不抛错。
  */
 import type { HubAboutInfo, HubUpdateInfo, HubUpdateVersion } from '../types.ts'
 import { HUB_ABOUT_URL, HUB_UPDATE_URL } from '../logic/constants.ts'
@@ -19,7 +19,7 @@ function busted(url: string): string {
 }
 
 /** 归一化接口下发的 recentVersions：只保留带版本号的条目，其余字段按类型补。
- *  这条数据是「最新版还在 24.5h 门禁内时回退到更早的已过门槛版本」的唯一依据；
+ *  这条数据是「最新版还在 24.5h 冷却期内时回退到更早的已过冷却期版本」的唯一依据；
  *  入口处漏传会让候选只剩最新版，整体变成 pending —— 用户就永远看不到更新入口。 */
 function recentVersionsOf(value: unknown): HubUpdateVersion[] {
   if (!Array.isArray(value)) return []
@@ -37,7 +37,7 @@ function recentVersionsOf(value: unknown): HubUpdateVersion[] {
   return list
 }
 
-/** 版本控制中心：最新版本 + Markdown 变更记录 + 最近发版（门禁回退用）；不可用返回 null。 */
+/** 版本控制中心：最新版本 + Markdown 变更记录 + 最近发版（冷却期回退用）；不可用返回 null。 */
 export async function fetchHubUpdate(): Promise<HubUpdateInfo | null> {
   try {
     const res = await fetch(busted(HUB_UPDATE_URL), { cache: 'no-store' })