dsh-plugin 2.3.1 → 2.3.3

package/src/client/hooks/useCatalog.ts

@@ -52,7 +52,7 @@ export function useCatalog(lang: LocaleId) {
    *  界面停在「正在加载插件数据…」假死 —— 超时自动重拉，最多自动重试 2 次后转失败态；
    *  用户手动刷新（reload）时清零重新计数。 */
   const loadRetriesRef = useRef(0)
-  /** 目录加载超时阈值：超过即判定挂起，强制刷新一次（服务端代理 curl 上限 60s，客户端 30s 先兜底） */
+  /** 目录加载超时阈值：超过即判定挂起，强制刷新一次（服务端代理 curl 上限 60s，客户端 30s 先超时） */
   const LOAD_TIMEOUT_MS = 30000
   /** 挂起后最多自动重试次数：避免代理持续不通时无限循环刷新（每次重试仍 30s，2 次后转失败界面可手动重试） */
   const MAX_LOAD_RETRIES = 2
@@ -68,7 +68,7 @@ export function useCatalog(lang: LocaleId) {
    * 强制刷新 Hub 版本与「关注我们」信息：点击头部版本号/徽标时触发。
    * 挂载期的 useEffect 只在进入/reload 时拉一次，发版后已打开的界面点版本号
    * 仍显示旧数据；此处重新拉接口中心，最新版本与变更记录点击即见。
-   * 失败静默为 null（弹窗兜底展示当前版本号），与挂载期拉取口径一致。
+   * 失败时返回 null（弹窗退回展示当前版本号），与挂载期拉取规则一致。
    */
   const refreshHub = async () => {
     // 版本接口已恒带时间戳绕过 CDN，手动/自动拉取都能拿到最新公告
@@ -115,7 +115,7 @@ export function useCatalog(lang: LocaleId) {
         settled = true
         // 插件市场不显示自己：DSH Plugin Hub 从目录里排除自身条目，
         // 防止「自己出现在自己的插件列表里、还能自己安装自己」；统计计数同步减 1 保持与列表一致。
-        // 目录数据已排除自身，此处再兜底过滤一次，防旧快照仍含自身条目。
+        // 目录数据已排除自身，此处再过滤一次，防旧快照仍含自身条目。
         const hadSelf = list.some((p) => p.source?.repo === SELF_REPO)
         // 过滤前单独保留 hub 自身条目：它不进目录列表，但「可更新」徽标的直接更新需要它作为重装目标
         setHubPlugin(list.find((p) => p.source?.repo === SELF_REPO) ?? null)
@@ -131,7 +131,7 @@ export function useCatalog(lang: LocaleId) {
         settled = true
         setFailed(true)
       })
-    // 加载超时兜底：宿主刚重启/代理未就绪时目录请求可能长时间挂起，界面停在「正在加载插件数据…」
+    // 加载超时保护：宿主刚重启/代理未就绪时目录请求可能长时间挂起，界面停在「正在加载插件数据…」
     // 像假死。超过阈值未收尾 → 强制刷新列表（重拉一次，最多 MAX_LOAD_RETRIES 次自动重试），
     // 重试仍失败 → 转失败界面（显示「重试」按钮，手动刷新时计数清零重新开始）。
     const timer = window.setTimeout(() => {
@@ -152,7 +152,7 @@ export function useCatalog(lang: LocaleId) {
     // 否则英文模式仍停留在 plugins.zh.json，描述/名称全是中文
   }, [reloadKey, lang])
 
-  /** 刷新当前 profile 已安装插件表；宿主未挂本地路由时静默降级为空表。 */
+  /** 刷新当前 profile 已安装插件表；宿主未挂本地路由时降级为空表。 */
   const refreshInstalled = async () => {
     const data = await fetchInstalled()
     if (data === null) return
@@ -168,7 +168,7 @@ export function useCatalog(lang: LocaleId) {
 
   // Hub 自身版本检查走独立 Worker（版本控制中心）：发新版后写一次 Worker KV，
   // 所有已装用户立即看到「可更新」+ Markdown 变更记录，不经过主站目录数据管道。
-  // 失败静默降级为 null（徽标不出现，不影响目录本身加载）。
+  // 失败时降级为 null（徽标不出现，不影响目录本身加载）。
   useEffect(() => {
     let cancelled = false
     void fetchHubUpdate().then((info) => { if (!cancelled) setHubUpdateInfo(info) })
@@ -176,7 +176,7 @@ export function useCatalog(lang: LocaleId) {
   }, [reloadKey])
 
   // 「关注我们」内容走同一套 Worker：作者写好 Markdown（平台介绍 + 反馈群二维码）推送 /admin/about，
-  // 客户端下次进入拉 /about 即可看到最新，非写死。失败静默为 null（弹窗展示兜底文案，不阻塞）。
+  // 客户端下次进入拉 /about 即可看到最新，非写死。失败时返回 null（弹窗展示备用文案，不阻塞）。
   useEffect(() => {
     let cancelled = false
     void fetchHubAbout().then((info) => { if (!cancelled) setHubAboutInfo(info) })
@@ -231,7 +231,7 @@ export function useCatalog(lang: LocaleId) {
       return
     }
     let cancelled = false
-    // 批量一次查询；失败/返回 null 时按原逻辑照常提示，网络问题不吃掉真实更新
+    // 批量一次查询；失败/返回 null 时按原逻辑照常提示，网络问题不会漏掉真实更新
     void fetchNpmReleaseAge(releaseAgeCandidates).then((result) => {
       if (cancelled) return
       setReleaseAge({ key: releaseAgeKey, releases: result ?? EMPTY_RELEASES })
@@ -244,7 +244,7 @@ export function useCatalog(lang: LocaleId) {
 
   /**
    * 不能提示更新的包：
-   *  - npm 上最新版还没过供应链门禁（发布不满 24h，pnpm 会静默回退，点了也装不上）；
+   *  - npm 上最新版还没过发布冷却期（发布不满 24h，pnpm 会不提示地回退，点了也装不上）；
    *  - npm 上最新版并不高于已装版本 —— 更新走的是 `pkg@latest`，此时无论目录标到哪个 tag，
    *    都不可能装上（作者可能只打了 GitHub release 没发 npm），提示只会变成永远点不掉的循环。
    */
@@ -280,7 +280,7 @@ export function useCatalog(lang: LocaleId) {
     return releaseAgeReady && !updateBlocked.has(pkg)
   }
 
-  /** 更新被门禁暂缓时的可重试时刻（毫秒）；未安装/无更新/非门禁原因 → null。 */
+  /** 更新被冷却期未到时的可重试时刻（毫秒）；未安装/无更新/非冷却期原因 → null。 */
   const updatePendingUntil = (p: HubPlugin): number | null => {
     if (!hasUpdateOf(p, installed, versions)) return null
     const pkg = npmPackageOf(p, versions)
@@ -289,7 +289,7 @@ export function useCatalog(lang: LocaleId) {
   }
 
   /** 已安装项统一列表（目录元数据 + 运行时信息合并）：校验未就绪/被拦下的去掉更新标记、
-   *  门禁暂缓的带上可重试时刻，驱动「已安装」tab。 */
+   *  冷却期未到的带上可重试时刻，驱动「已安装」tab。 */
   const installedItems = useMemo<InstalledItem[]>(() => {
     return rawInstalledItems.map((item) => {
       if (!item.hasUpdate || !item.plugin) return item
@@ -309,13 +309,13 @@ export function useCatalog(lang: LocaleId) {
    * 构建时注入的 PLUGIN_VERSION 是运行 bundle 的真实版本；测试/异常场景缺失时
    * 回退到安装时记录的版本。版本号不等即新版（版本号只在发版时变更，绝无降级场景）。
    *
-   * 另加 pnpm 供应链安全门槛：新版本发布还不满 24 小时（+30 分钟缓冲）时，pnpm 会静默
+   * 另加 pnpm 发布冷却期：新版本发布还不满 24 小时（+30 分钟缓冲）时，pnpm 会不提示地
    * 回退到旧版本，此时若提示「可更新」用户点了也更新不到。publishedAt 由接口中心按 npm
-   * registry 真实发布时间下发（同源），据此判断最准。门槛命中要单列成 `pending` 而不是
+   * registry 真实发布时间下发（同源），据此判断最准。冷却期命中要单列成 `pending` 而不是
    * 落回「无更新」——回落会让弹窗在本机版本落后时谎称「已是最新」。
    */
   const hubCurrentVersion = PLUGIN_VERSION || versions[HUB_REPO]?.version || ''
-  // 候选含 recentVersions：最新版还在门禁内时回退到「更早、但已过门禁」的版本，
+  // 候选含 recentVersions：最新版还在冷却期内时回退到「更早、但已过冷却期」的版本，
   // 避免连续快速发版把所有提示窗口都吞掉（见 pickHubUpdate）。
   const hubUpdateResult = hubUpdateInfo === null
     ? { state: 'none' as HubUpdateState, target: null }

package/src/client/hooks/useSettings.ts

@@ -60,7 +60,7 @@ export function useSettings() {
     return () => { alive = false }
   }, [])
 
-  /** 部分更新：本地立即生效（乐观），同时 POST 持久化；持久化失败静默（本次会话仍生效）。 */
+  /** 部分更新：本地立即生效（乐观），同时 POST 持久化；持久化失败不影响本次会话。 */
   const update = useCallback((patch: Partial<HubSettings>) => {
     setSettings((prev) => ({ ...prev, ...patch }))
     void fetch('/dsh-plugin-hub/settings', {
@@ -71,7 +71,7 @@ export function useSettings() {
     }).catch(() => { /* 宿主未挂路由：仅本次会话生效 */ })
   }, [])
 
-  /** 重置为默认设置：本地立即回默认，同时通知服务端删除设置文件；失败静默。 */
+  /** 重置为默认设置：本地立即回默认，同时通知服务端删除设置文件；失败不影响本地已重置的设置。 */
   const reset = useCallback(() => {
     setSettings({ ...DEFAULT_SETTINGS })
     void fetch('/dsh-plugin-hub/settings/reset', {

package/src/client/hooks/useTaskQueue.ts

@@ -49,11 +49,11 @@ export interface QueueTask {
   command?: string
   /** 实际执行/重试过的安装命令（按先后顺序）：失败时 issue 预填一并贴给作者 */
   attempts?: string[]
-  /** 完成结果是否需要重启才生效（服务端任务终态带出）。默认 true 保底：数据缺失时不静默视为已生效。
-   *  仅刷新解决不了的兜底场景（热挂载失败 / 非 dsh 插件 / 更新）为 true，结果视图给「立即重启」；
-   *  其余（热挂载成功、卸载已即时停用、全局安装）为 false，结果视图仅「完成」。 */
+  /** 完成结果是否需要重启才生效（服务端任务终态带出）。默认 true：数据缺失时不视为已生效。
+   *  仅刷新解决不了的例外场景（热加载失败 / 非 dsh 插件 / 更新）为 true，结果视图给「立即重启」；
+   *  其余（热加载成功、卸载已即时停用、全局安装）为 false，结果视图仅「完成」。 */
   needsRestart: boolean
-  /** 完成结果是否只需刷新页面即生效（插件已热挂进运行中 loader，或卸载后插件面板仍残留在当前页面）：
+  /** 完成结果是否只需刷新页面即生效（插件已热加载进运行中 loader，或卸载后插件面板仍残留在当前页面）：
    *  true 时关闭结果弹窗 / Toast 消失后由上层自动刷新页面，不给手动刷新按钮。 */
   needsReload?: boolean
   /** 市场自更新成功、但 profile 的 bundle 列表里已不含 dsh-plugin：重启后市场不会出现 */
@@ -78,11 +78,11 @@ export interface TaskQueueOptions {
   refreshInstalled: () => void
   /** 任务成功完成：viaModal 表示任务对应当前打开弹窗（弹窗切结果视图），否则走 Toast；repo 供成功通知记录；
    *  needsRestart 表示该任务完成后是否仍需宿主重启（结果视图据此给「重启 / 仅完成」）；
-   *  needsReload 表示是否只需刷新页面即生效（热挂载成功、或卸载后插件面板仍残留）。
+   *  needsReload 表示是否只需刷新页面即生效（热加载成功、或卸载后插件面板仍残留）。
    *  update 表示实际执行的是更新（覆盖重装）而非首次安装：通知中心据此显示「更新成功」而非「安装成功」。 */
   onInstallDone: (viaModal: boolean, repo: string | null, needsRestart: boolean, update?: boolean, needsReload?: boolean, bundleDeselected?: boolean) => void
   onUninstallDone: (viaModal: boolean, repo: string | null, needsRestart: boolean, needsReload?: boolean) => void
-  /** 任务失败：完整输出或兜底文案 + 所属插件仓库 + 操作类型（安装/卸载）+ 实际执行的安装命令（issue 预填用，可缺省）+ 实际执行/重试过的安装命令（可缺省）+ 是否更新。 */
+  /** 任务失败：完整输出或备用文案 + 所属插件仓库 + 操作类型（安装/卸载）+ 实际执行的安装命令（issue 预填用，可缺省）+ 实际执行/重试过的安装命令（可缺省）+ 是否更新。 */
   onError: (message: string, repo: string | null, kind: 'install' | 'uninstall', command?: string, attempts?: string[], update?: boolean) => void
   /** 当前打开的安装/卸载弹窗插件：用于在弹窗内匹配进行中的任务。 */
   installPlugin: HubPlugin | null
@@ -114,7 +114,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   /** 待重启列表（服务端内存态 + 本地展示信息补齐）；与 queue 一样以 ref 为唯一事实来源。 */
   const [pendingRestarts, setPendingRestarts] = useState<PendingRestart[]>([])
   const pendingRef = useRef<PendingRestart[]>([])
-  /** 本次会话内安装成功插件的展示信息（目标 → 简介/版本）：轮询合并待重启列表时补齐，刷新后由 resolvePending 兜底。 */
+  /** 本次会话内安装成功插件的展示信息（目标 → 简介/版本）：轮询合并待重启列表时补齐，刷新后由 resolvePending 补上。 */
   const pendingInfoRef = useRef<Map<string, { desc?: string; version?: string }>>(new Map())
   /** 保持最新的 resolvePending：轮询闭包捕获的是调用那一刻的目录状态，目录晚加载时也能补齐。 */
   const resolvePendingRef = useRef(resolvePending)
@@ -125,12 +125,12 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   const settlingRef = useRef<Set<number>>(new Set())
   /** 轮询定时器句柄（队列清空/组件卸载时清理） */
   const pollRef = useRef<number | null>(null)
-  /** 请求在途的目标集合（同步防重）：双击安装/卸载时第二击直接忽略。
+  /** 请求还没返回的目标集合（同步防重）：双击安装/卸载时第二击直接忽略。
    *  本地队列任务要等 fetch 返回后才入队，仅靠 queueRef 检查拦不住请求窗口内的重复点击。 */
   const submittingRef = useRef<Set<string>>(new Set())
   /** 乐观入队临时 id 计数器：递减产生唯一负数，与服务端自增正数 id 永不冲突。 */
   const tempIdRef = useRef(0)
-  /** 请求在途标记：弹窗据此禁用确认按钮，避免等待响应期间被再次点击。 */
+  /** 请求进行中标记：弹窗据此禁用确认按钮，避免等待响应期间被再次点击。 */
   const [submitting, setSubmitting] = useState(false)
 
   /** 停止后台任务轮询（任务结束或组件卸载时清理）。 */
@@ -146,7 +146,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     if (queueRef.current.length === 0 && pendingRef.current.length === 0) stopPoll()
   }
 
-  // 组件卸载时兜底清理轮询定时器
+  // 组件卸载时清理轮询定时器
   useEffect(() => stopPoll, [])
 
   /** 更新队列（同步镜像到 ref：queueRef 是唯一事实来源，state 只负责触发渲染，
@@ -200,7 +200,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
         body: JSON.stringify({ repo, version, updatedAt }),
       })
     } catch {
-      // 宿主未挂本地路由：静默忽略，仅本机展示受影响
+      // 宿主未挂本地路由：直接忽略，仅本机展示受影响
     }
   }
 
@@ -274,7 +274,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     }, stepMs)
   }
 
-  /** 任务在 /active 中消失 = 已结束：查 /status 拿终态并收尾（cancelled 静默移除）。 */
+  /** 任务在 /active 中消失 = 已结束：查 /status 拿终态并收尾（cancelled 直接移除）。 */
   const settleTask = async (q: QueueTask) => {
     let status = 'failed'
     let lines: string[] = []
@@ -292,7 +292,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
           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 热挂/即时移除情况设置）
+          // 终态带出的「是否需要重启 / 是否只需刷新」覆盖本地（服务端 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') {
@@ -383,7 +383,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
           try { await settleTask(q) } finally { settlingRef.current.delete(q.id) }
         }
       } catch {
-        // 服务端暂不可达：静默等待下一轮
+        // 服务端暂不可达：等下一轮再试
       }
     }, 600)
   }
@@ -455,8 +455,8 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     source: 'catalog' | 'custom'
     /** 更新已安装目标（放行 add 覆盖重装） */
     update?: boolean
-    /** 钉住精确版本（Hub 自我更新用）：最新版可能仍在 pnpm 供应链门禁内，
-     *  必须安装「已过门禁」的那个版本，不能再用 @latest。 */
+    /** 锁定精确版本（Hub 自我更新用）：最新版可能仍在 pnpm 发布冷却期内，
+     *  必须安装「已过冷却期」的那个版本，不能再用 @latest。 */
     pinVersion?: string
     /** 全局 npm 安装包列表（`npm install -g <pkgs>`）：非空时服务端执行全局安装，不进任何 profile */
     globalNpm?: string[]
@@ -466,7 +466,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   }) => {
     // 防重复入队：同一目标已在排队/执行中则忽略
     if (queueRef.current.some((q) => q.kind === 'install' && q.target === input.repo)) return
-    // 请求在途防重：任务要等响应回来才进本地队列，这之前再次点击（双击）直接忽略
+    // 请求进行中防重：任务要等响应回来才进本地队列，这之前再次点击（双击）直接忽略
     if (submittingRef.current.has(input.repo)) return
     submittingRef.current.add(input.repo)
     // 乐观入队：点击安装立即显示「正在安装中」，不等 POST 响应。
@@ -498,7 +498,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
           display: input.repo,
           source: input.source,
           mode: input.update ? 'update' : undefined,
-          // 钉住版本（Hub 自我更新）：服务端据此执行 `add <pkg>@<version>` 而不是 @latest
+          // 锁定版本（Hub 自我更新）：服务端据此执行 `add <pkg>@<version>` 而不是 @latest
           ...(input.pinVersion ? { version: input.pinVersion } : {}),
           // 界面语言带给服务端：安装前网络探测等错误消息按用户当前语言返回（中文界面给中文，英文界面给英文）
           ...(langKey ? { lang: langKey } : {}),
@@ -531,7 +531,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       // 摘要条常驻顶部（含实时进度），明细面板保持折叠，想看时再点开
       pollQueue()
     } catch (err) {
-      // 网络异常：移除乐观条目 + 兜底错误弹窗（附上底层原因，避免只剩一句笼统的「安装失败」）
+      // 网络异常：移除乐观条目，并以错误弹窗提示（附上底层原因，避免只剩一句笼统的「安装失败」）
       applyQueue((prev) => prev.filter((x) => x.id !== tempId))
       const aborted = (err as { name?: string } | null)?.name === 'AbortError'
       // [request-timeout]：给分类器一个与界面语言无关的超时标记
@@ -562,7 +562,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       desc: p.description,
       version: p.version,
       updatedAt: p.dates?.repoUpdatedAt,
-      command: installCommandOf(p, true),
+      command: installCommandOf(p, true, opts?.pinVersion),
       source: 'catalog',
       update: opts?.update,
       pinVersion: opts?.pinVersion,
@@ -572,8 +572,8 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   /** 命令行安装：用户手输 npm 包名，走 custom 源（受安全开关控制）。
    *  update=true 时对已安装目标放行覆盖重装（与目录插件「更新」同一语义）。
    *  channel=入口渠道（NPM 包卡片）：上报服务端落日志，失败弹窗/通知据此精准溯源。
-   *  队列展示/防重一律用归一化身份：与服务端 /active 合并、弹窗目标匹配同口径，
-   *  npm 包名透传不受影响。 */
+   *  队列展示/防重一律用归一化身份：与服务端 /active 合并、弹窗目标匹配同一套规则，
+   *  npm 包名原样传递不受影响。 */
   const installCustom = async (raw: string, opts?: { update?: boolean; channel?: InstallChannel }) => {
     const target = raw.trim()
     if (!target) return
@@ -589,7 +589,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   }
 
   /** 全局 npm 安装（官方 README 的 `npm install -g <pkgs>`）：不进任何 profile、无需宿主重启。
-   *  队列展示/防重用包列表空格拼接的身份（与服务端 target 同口径）；入口渠道固定为 npm（NPM 包卡片）。 */
+   *  队列展示/防重用包列表空格拼接的身份（与服务端 target 同一套规则）；入口渠道固定为 npm（NPM 包卡片）。 */
   const installGlobalNpm = async (pkgs: string[], opts?: { update?: boolean; channel?: InstallChannel }) => {
     const list = (pkgs ?? []).map((p) => p.trim()).filter((p) => p !== '')
     if (list.length === 0) return
@@ -609,7 +609,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   const enqueueUninstall = async (name: string, repo: string | null, desc?: string) => {
     if (!name) return
     if (queueRef.current.some((q) => q.kind === 'uninstall' && q.target === name)) return
-    // 请求在途防重：与安装一致，响应回来前再次点击直接忽略
+    // 请求进行中防重：与安装一致，响应回来前再次点击直接忽略
     if (submittingRef.current.has(name)) return
     submittingRef.current.add(name)
     setSubmitting(true)
@@ -624,6 +624,13 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       })
       const data = await res.json() as { ok?: boolean; task?: number; error?: string }
       if (!data.ok || typeof data.task !== 'number') {
+        // 依赖已经不在了（列表还没刷新时重复点击）：按已卸载收尾，刷新列表，不弹失败
+        if (res.status === 400 && data.error === 'plugin is not installed') {
+          refreshInstalled()
+          void clearInstalledVersion(repo)
+          onUninstallDone(false, repo, false, false)
+          return
+        }
         onError(data.error || `HTTP ${res.status}`, repo, 'uninstall')
         return
       }

package/src/client/locales.ts

@@ -59,7 +59,7 @@ export const zh = {
   npmInstallPlaceholder: 'npm install <包名> 或直接输包名',
   npmInstallExample: '支持原生命令：npm install lodash、npm i lodash、pnpm add @scope/pkg',
   npmInstallExample2: '全局安装 CLI：npm install -g @scope/cli；或直接输入包名 lodash',
-  npmInstallInvalid: '请输入 npm 包名（如 lodash、@scope/pkg），或原生安装命令（如 npm install lodash、npm i lodash、pnpm add @scope/pkg、npm install -g @scope/cli）',
+  npmInstallInvalid: '请输入 npm 包名（如 lodash、@scope/pkg），或原生安装命令（如 npm install lodash、npm i lodash、pnpm add @scope/pkg、npm install -g @scope/cli）；不支持 GitHub 源码地址，请改用该插件的 npm 包名',
   installHelp: '帮助',
   helpModalTitle: '支持的命令格式',
   npmInstallHelp: 'lodash、@scope/pkg\t直接输入包名\nnpm install lodash\nnpm i lodash\npnpm add @scope/pkg\npnpm i @scope/pkg\nnpm install -g @scope/cli\t全局安装 CLI 工具，不进「已安装」列表',
@@ -257,14 +257,14 @@ export const zh = {
   requestTimeout: '请求超时：无法访问 GitHub 或网络不稳定，请稍后重试',
   confirmCancel: '取消',
   doneBtn: '完成',
-  // 结果视图兜底：仅当「刷新解决不了」时（热挂载失败 / 非 dsh 插件 / 更新）才出现单个「立即重启」；
+  // 结果视图补充：仅当「刷新解决不了」时（热加载失败 / 非 dsh 插件 / 更新）才出现单个「立即重启」；
   // 关闭弹窗即视为「稍后」，不再单独给「稍后重启」按钮
   restartNow: '立即重启',
   restarting: '正在重启…',
   restartHint: '重启会中断正在进行的安装/卸载任务，其进度将丢失。部分插件（如插件市场、顶层 bundle）需重启后才会生效。',
   // 桌面端宿主归应用壳管、插件重启不了它：点「立即重启」时改提示用户退出重开
   toastRestartDesktop: '桌面端的宿主由应用管理，请在应用菜单（或托盘）选择退出后重新打开，重启后生效',
-  // 装完即生效：插件已热挂进运行中 loader，结果弹窗关闭时自动刷新页面（无需用户点按钮）
+  // 装完即生效：插件已热加载进运行中 loader，结果弹窗关闭时自动刷新页面（无需用户点按钮）
   reloadHint: '插件已加载，关闭本窗口后会自动刷新页面生效。',
   toastInstalledLive: '安装成功，已立即生效',
   toastInstalledReload: '安装成功，正在自动刷新页面…',
@@ -311,7 +311,7 @@ export const zh = {
   // 非插件侧失败（未知原因）改为引导到插件中心仓库排查
   failHubIssueHint: '此失败已被判定为环境或插件中心自身问题（非插件作者问题），带着错误日志到插件中心仓库一键提交 Issue',
   failHubIssueBig: '反馈给插件中心排查',
-  // 未知失败兜底：不归到插件作者，引导到插件中心仓库排查
+  // 未知失败补充：不归到插件作者，引导到插件中心仓库排查
   failUnclassifiedHint: '{action}失败，原因未能自动识别。这通常不是插件自身的问题（可能与本机环境或插件中心有关），请将错误信息反馈给插件中心，由维护者排查。',
   // 插件中心自身状态类消息（插件未安装 / 不在此处卸载 / 已在队列中）：已安装列表与实读快照不同步，非插件问题，不引导提 Issue
   failHubStateHint: '插件列表状态已过期或与本地不一致：这次{action}的目标可能已经在列表里了（要升级请点「更新」），也可能已经不在已安装列表中，或已在队列中。这不是插件本身的问题 —— 请刷新页面后重试。',
@@ -404,7 +404,7 @@ export const zh = {
   failKind_pluginMissingDep: '插件依赖未发布',
   failReason_pluginMissingDep: '插件声明依赖的包在官方 npm 源上不存在（已删除或从未发布）。',
   failKind_registryVersionStale: '该版本在所用源上不存在',
-  failReason_registryVersionStale: '实际安装用的源还没同步到这个版本，或版本号写错。',
+  failReason_registryVersionStale: '实际安装用的源还没同步到这个版本。可稍后重试，或到「设置 → npm 镜像源」换成官方源；也可先安装上一个可用版本。',
   failKind_registryAuth: 'npm 源拒绝了访问',
   failReason_registryAuth: 'registry 返回 401/403：这个源需要登录凭据，或当前网络不被允许。',
   failKind_profileExclusive: 'profile 由桌面应用独占管理',
@@ -491,10 +491,10 @@ export const zh = {
   update: '可更新',
   updateAvailable: '有更新',
   updateAvailableHint: '检测到更新：有版本号的仓库比对版本号，无版本号的仓库比对仓库最近更新时间',
-  // 门禁暂缓：新版本发布未满 24 小时，此时安装会被 pnpm 静默回退（或直接拒绝），
-  // 给出确切可重试时刻，而不是让徽标静默消失、让用户以为已经是最新
+  // 冷却期未到：新版本发布未满 24 小时，此时安装会被 pnpm 不提示地回退（或直接拒绝），
+  // 给出确切可重试时刻，而不是让徽标悄悄消失、让用户以为已经是最新
   updatePending: '暂缓到 {time} 后可更新',
-  updatePendingHint: '新版本发布未满 24 小时，pnpm 供应链门禁会拦下；到时间后再更新即可',
+  updatePendingHint: '新版本发布还不满 24 小时，pnpm 暂时不让安装；到时间后再更新即可',
   hubUpdateHint: '检测到 DSH Plugin Hub 新版本，点击查看更新内容并更新',
   hubUpdateTitle: 'DSH Plugin Hub 有新版本',
   hubUpdateDesc: '点击下方按钮即可更新，完成后需重启宿主生效。',
@@ -508,12 +508,12 @@ export const zh = {
   hubVersionStateAvailable: '可更新',
   hubVersionStatePending: '暂缓提示',
   close: '关闭',
-  // 暂缓提示：远端确有新版本，但发布未满 24 小时（pnpm 供应链安全门槛），与「已是最新」严格区分
-  hubPendingDesc: '最新版已发布，但发布尚未满 24 小时：此时更新会被 pnpm 静默回退到旧版本，因此暂不提示。稍后这里会自动出现更新入口。',
-  // 头部「关注我们」弹窗：平台介绍 + 用户反馈群二维码（内容由 Worker /about Markdown 推送，非写死）
+  // 暂缓提示：远端确有新版本，但发布未满 24 小时（pnpm 发布冷却期），与「已是最新」严格区分
+  hubPendingDesc: '最新版已发布，但发布尚未满 24 小时：此时更新会被 pnpm 不提示地回退到旧版本，因此暂不提示。稍后这里会自动出现更新入口。',
+  // 头部「关注我们」弹窗：平台介绍（内容由 Worker /about Markdown 推送，非写死）
   followUs: '关注我们',
   aboutTitle: '关注我们',
-  aboutDesc: '了解 DSH Plugin Hub 是做什么的，加入用户反馈群随时交流。',
+  aboutDesc: '了解 DSH Plugin Hub 是做什么的，访问主站浏览插件，或到 GitHub 提交 Issue。',
   aboutEmpty: '内容暂未发布，敬请期待。',
   aboutUpdated: '更新于',
   empty: '该分类暂无插件',
@@ -573,7 +573,7 @@ export const en = {
   npmInstallPlaceholder: 'npm install <pkg> or a bare package name',
   npmInstallExample: 'Native commands: npm install lodash, npm i lodash, pnpm add @scope/pkg',
   npmInstallExample2: 'Global CLI: npm install -g @scope/cli; or just type a package name like lodash',
-  npmInstallInvalid: 'Enter an npm package name (e.g. lodash, @scope/pkg), or a native install command (e.g. npm install lodash, npm i lodash, pnpm add @scope/pkg, npm install -g @scope/cli)',
+  npmInstallInvalid: 'Enter an npm package name (e.g. lodash, @scope/pkg), or a native install command (e.g. npm install lodash, npm i lodash, pnpm add @scope/pkg, npm install -g @scope/cli); GitHub source URLs are not supported — use the plugin\'s npm package name instead',
   installHelp: 'Help',
   helpModalTitle: 'Supported command formats',
   npmInstallHelp: 'lodash or @scope/pkg\tjust type the package name\nnpm install lodash\nnpm i lodash\npnpm add @scope/pkg\npnpm i @scope/pkg\nnpm install -g @scope/cli\tinstalls the CLI globally, not shown in Installed',
@@ -700,7 +700,7 @@ export const en = {
   settingsDiagFail: 'Unreachable',
   // 系统诊断通道列表：一键全检 + 每通道一行，点击重测
   diagNpm: 'npm registry',
-  // 诊断 npm 行：未配置镜像时显示的兜底文案（探测仍打官方源）
+  // 诊断 npm 行：未配置镜像时显示的备用文案（探测仍打官方源）
   diagNpmUnset: 'Unset (follow local npm config)',
   diagGithub: 'GitHub',
   diagCatalog: 'Catalog site',
@@ -771,14 +771,14 @@ export const en = {
   requestTimeout: 'Request timed out: GitHub may be unreachable or the network is unstable — try again later',
   confirmCancel: 'Cancel',
   doneBtn: 'Done',
-  // 结果视图兜底：仅刷新解决不了时（热挂载失败 / 非 dsh 插件 / 更新）才给单个「立即重启」；
+  // 结果视图补充：仅刷新解决不了时（热加载失败 / 非 dsh 插件 / 更新）才给单个「立即重启」；
   // 关闭弹窗即视为「稍后」
   restartNow: 'Restart now',
   restarting: 'Restarting…',
   restartHint: 'Restarting interrupts any in-progress install / uninstall task — its progress will be lost. Some plugins (such as plugin markets / top-level bundles) only take effect after a restart.',
   // 桌面端：宿主由应用壳托管，插件重启不了它 —— 提示用户退出后重开
   toastRestartDesktop: 'In the desktop app the host is managed by the app: quit from the app menu (or tray) and open it again — the change takes effect after that restart',
-  // 免重启即生效：安装已热挂载进运行中 loader；关闭弹窗时页面自动刷新（不给手动刷新按钮）
+  // 免重启即生效：安装已热加载进运行中 loader；关闭弹窗时页面自动刷新（不给手动刷新按钮）
   reloadHint: 'The plugin is loaded — closing this window will refresh the page automatically.',
   toastInstalledLive: 'Installed — active now',
   toastInstalledReload: 'Installed — refreshing the page automatically…',
@@ -823,7 +823,7 @@ export const en = {
   // 非插件侧失败（未分类）改为投递到插件中心仓库分诊
   failHubIssueHint: 'This failure was classified as an environment or Plugin Hub issue (not a plugin-author issue). Open a pre-filled issue on the Plugin Hub repo with this error log.',
   failHubIssueBig: 'Report to the Plugin Hub for triage',
-  // 未知失败兜底：不投插件作者，改投插件中心仓库分诊
+  // 未知失败补充：不投插件作者，改投插件中心仓库分诊
   failUnclassifiedHint: 'The {action} failed and the cause could not be identified automatically. This is usually not the plugin itself (it may relate to your local environment or the Plugin Hub). Please report the error to the Plugin Hub so the maintainers can triage it.',
   // 插件中心自身的状态守卫消息（未安装 / 不在此处卸载 / 已在队列中 / 已安装）：已装列表与实读快照不同步 —— 不是插件问题，不引导提 Issue
   failHubStateHint: 'The plugin list is out of date or out of sync: the target of this {action} may already be in the list (use "Update" to upgrade), may no longer be in the installed list, or may already be queued. This is not a plugin problem — refresh the page and retry.',
@@ -915,7 +915,7 @@ export const en = {
   failKind_pluginMissingDep: 'plugin dependency is not published',
   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.',
+  failReason_registryVersionStale: 'The registry that actually performs the install has not synced this version yet. Retry later, switch to the official registry under Settings → npm mirror, or install a previous version for now.',
   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_profileExclusive: 'the profile is managed only by the desktop app',
@@ -1017,12 +1017,12 @@ export const en = {
   hubVersionStateAvailable: 'Update available',
   hubVersionStatePending: 'Held for 24h',
   close: 'Close',
-  // 暂缓提示：确有新版本，但仍在 pnpm 24h 供应链门禁窗口内
+  // 暂缓提示：确有新版本，但仍在 pnpm 24h 发布冷却期内
   hubPendingDesc: 'The latest version has been released, but it is still within the 24-hour window where pnpm silently falls back to the older version, so the update is not offered yet. The update entry will appear here shortly.',
-  // 头部「关注我们」弹窗：平台介绍 + 用户反馈群二维码（内容由 Worker /about 以 Markdown 推送）
+  // 头部「关注我们」弹窗：平台介绍（内容由 Worker /about 以 Markdown 推送）
   followUs: 'Follow us',
   aboutTitle: 'Follow us',
-  aboutDesc: 'Learn what DSH Plugin Hub does and join our user feedback group.',
+  aboutDesc: 'Learn what DSH Plugin Hub does — browse plugins on the website, or open an Issue on GitHub.',
   aboutEmpty: 'Content not published yet — stay tuned.',
   aboutUpdated: 'Updated',
   empty: 'No plugins in this category yet',

package/src/client/logic/constants.ts

@@ -33,7 +33,7 @@ declare const __PLUGIN_VERSION__: string
 /**
  * 插件当前版本号，供头部标题展示「DSH Plugin Hub v0.1.1」。
  * tsdown 构建时用 define 把 __PLUGIN_VERSION__ 替换成 package.json 的版本号；
- * node --test 直接 import 本模块时该标识符不存在，typeof 守卫兜底为空串。
+ * node --test 直接 import 本模块时该标识符不存在，typeof 守卫缺省为空串。
  */
 export const PLUGIN_VERSION: string =
   typeof __PLUGIN_VERSION__ === 'string' ? __PLUGIN_VERSION__ : ''

package/src/client/logic/ensure-plugin-css.ts

@@ -1,5 +1,5 @@
 /**
- * 自愈缺失的插件 CSS 标签。
+ * 自动补回缺失的插件 CSS 标签。
  *
  * CSS 注入是 bundle 工厂的一次性副作用（以「标签已存在」为守卫）。宿主重启后页面仍在，
  * 但宿主 HMR 链可能移除 <style data-plugin> 标签，而内存模块缓存仍持有旧工厂，工厂不再
@@ -7,7 +7,7 @@
  *
  * tsdown 的 `dsh-css-modules-inline` 构建插件会在工厂执行时把每个模块的 { tagId, css }
  * 登记进全局列表 `__DSH_PLUGIN_CSS__`。此工具随后比对列表与实时 DOM，补注入缺失的标签，
- * 把「点一圈才自愈」变成挂载 / 切换视图时自动完成。
+ * 把「点一圈才恢复」变成挂载 / 切换视图时自动完成。
  */
 
 interface PluginCssEntry {

package/src/client/logic/failures.ts

@@ -16,7 +16,7 @@ export interface NotificationRecord {
   /** owner/repo（可能为空：请求层失败但拿不到仓库时） */
   repo: string
   /** 实际动作（install/update/uninstall）：成功/失败通知据此区分「安装成功」与「更新成功」。
-   *  缺省按 kind 兜底（历史记录可能没有该字段）。更新提醒（kind='update'）不用此字段。 */
+   *  缺省按 kind 归类（历史记录可能没有该字段）。更新提醒（kind='update'）不用此字段。 */
   action?: 'install' | 'update' | 'uninstall'
   /** 失败时的完整错误日志；成功记录为空串 */
   message: string
@@ -150,7 +150,7 @@ export function removeNotification(id: number): NotificationRecord[] {
 
 export type FailureKind = 'npmTooOld' | 'nodeEngine' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmModulesMismatch' | 'profileYamlCorrupted' | 'profileLocalBuild' | 'profileState' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'pluginMissingDep' | 'registryVersionStale' | 'registryAuth' | 'profileExclusive' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'buildToolchainMissing' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'hostIncompatible' | 'tlsTrust' | 'network' | 'hostCliSpawn' | 'hubState' | 'profileBundleMissing' | 'timeout' | 'profileLock' | 'dshTooOld' | 'localEnv' | 'hub'
 
-/** 失败动作口径：标题、上报正文与提示文案按安装/更新/卸载取词，不写死「安装」。 */
+/** 失败动作规则：标题、上报正文与提示文案按安装/更新/卸载取词，不写死「安装」。 */
 export type FailureAction = 'install' | 'update' | 'uninstall'
 
 /** 动作词（英文）：名词短语，标题与句子里都成立。 */
@@ -163,7 +163,7 @@ export function actionWordZh(action: FailureAction): string {
   return action === 'uninstall' ? '卸载' : action === 'update' ? '更新' : '安装'
 }
 
-/** 记录的动作：老记录只有 kind，按 kind 兜底。 */
+/** 记录的动作：老记录只有 kind，按 kind 归类。 */
 export function actionOfRecord(rec: { kind: NotificationRecord['kind']; action?: FailureAction }): FailureAction {
   if (rec.action !== undefined) return rec.action
   return rec.kind === 'uninstall' ? 'uninstall' : rec.kind === 'update' ? 'update' : 'install'
@@ -231,7 +231,7 @@ export function pnpmPolicyHintParams(message: string): Record<string, string> {
  * （只影响这个插件 → 才引导提 Issue）。各分支判定顺序有依赖，见函数内注释。
  */
 export function classifyFailure(message: string): FailureKind {
-  // 宿主版本门禁：插件声明的兼容范围不含当前 dsh 版本，宿主在安装前直接拒绝。
+  // 宿主版本要求：插件声明的兼容范围不含当前 dsh 版本，宿主在安装前直接拒绝。
   // 必须最先判 —— 这是宿主自己给的结论，不是 pnpm 的安装失败
   if (/installation rejected:.*incompatible with dsh/i.test(message)) return 'hostIncompatible'
   // desktop profile 由桌面应用独占：外部 dsh CLI 无权管理，宿主在安装前直接拒绝。
@@ -266,7 +266,7 @@ export function classifyFailure(message: string): FailureKind {
   // pnpm 供应链策略拦截（缺 tarball integrity / 校验和不匹配 / minimumReleaseAge / untrusted origin）。
   // 必须在 pnpmIgnoredBuild 之前
   if (missingTarballIntegrity(message) || mismatchedTarballIntegrity(message) || /ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION|ERR_PNPM_NO_MATURE_MATCHING_VERSION|Minimum release age|minimumReleaseAge|untrusted origin/i.test(message)) return 'pnpmPolicy'
-  // profile 残留旧版本 patch 声明，pnpm 中止安装。必须在兜底之前
+  // profile 残留旧版本 patch 声明，pnpm 中止安装。必须排在默认归类之前
   if (/ERR_PNPM_UNUSED_PATCH|patches were not used/i.test(message)) return 'pnpmUnusedPatch'
   // profile 里的 YAML 配置解析失败（pnpm-workspace.yaml / pnpm-lock.yaml 有重复键、缩进坏了）：
   // pnpm 在依赖解析之前就退出，装任何插件都会同样失败，属本机 profile 配置问题。
@@ -334,7 +334,7 @@ export function classifyFailure(message: string): FailureKind {
   if (/git-hosted plugins build on install via their prepare script|add the exact key pnpm printed above under allowBuilds/i.test(message)) return 'pnpmIgnoredBuild'
   // 宿主启动插件管理时找不到某个 profile bundle（`cannot resolve profile bundle "<pkg>"`）：
   // 该 profile 声明的依赖没装全（node_modules 被删过 / 上次安装中断 / 桌面端更新不完整），
-  // 与本次要装的插件无关 —— 必须在 hub 兜底之前，否则又会被当成未知错误丢给我们
+  // 与本次要装的插件无关 —— 必须排在 hub 的默认归类之前，否则又会被当成未知错误丢给我们
   if (/cannot resolve profile bundle/i.test(message)) return 'profileBundleMissing'
   // 宿主自身入口起不来（服务端 [host-spawn] 标记）：环境问题，给提示、不引导提 Issue。
   // 不匹配 `spawn … ENOENT` 文本 —— 那个形态任何 spawn（curl/git/taskkill…）都会产出
@@ -354,7 +354,7 @@ export function classifyFailure(message: string): FailureKind {
   return 'hub'
 }
 
-/** 「特征指向本机环境但说不清具体哪一类」的兜底判据：系统调用错误码（权限/路径过长/设备异常）、
+/** 「特征指向本机环境但说不清具体哪一类」的最后的判断规则：系统调用错误码（权限/路径过长/设备异常）、
  *  证书与代理校验失败、本地配置文件（~/.npmrc、profile 的 package.json）损坏。
  *  只做排除用：命中它表示「不是插件侧问题」，不代表我们已经定位到原因。 */
 const LOCAL_ENV_RE = /os error \d{1,3}\b|ERROR_[A-Z_]{4,}|\bE(?:ACCES|PERM|NOENT|NAMETOOLONG|INVAL|PROTO|ISDIR|NOTDIR|EXIST|BADF|NOTEMPTY|JSONPARSE|NOMEM)\b|JavaScript heap out of memory|Unexpected token .{0,60}in JSON|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE|ERR_TLS_CERT_ALTNAME_INVALID|unable to verify the first certificate|self[- ]signed certificate|ERR_INVALID_URL|invalid registry|proxy authentication|407 Proxy/i
@@ -386,7 +386,7 @@ export const MAX_CORE_CHARS = 5000
 const MAX_LINE_CHARS = 400
 
 /**
- * 展示用格式化：宿主门禁消息里的 peerDependencies 是压缩成一行的 JSON，
+ * 展示用格式化：宿主兼容性提示里的 peerDependencies 是压缩成一行的 JSON，
  * 直接展示像一团乱码；展开成缩进格式，解析失败则原样返回。
  */
 export function formatFailureMessage(message: string): string {
@@ -420,7 +420,7 @@ export function summarizeError(message: string, maxChars: number = MAX_CORE_CHAR
   }
   let out: string
   if (core.length === 0) {
-    // 整段本来就是短消息时直接给全量：head+tail 兜底会把同一段重复两遍，正文反而更难读
+    // 整段本来就是短消息时直接给全量：head+tail 的截断方式会把同一段重复两遍，正文反而更难读
     const whole = message.trim()
     if (whole.length <= maxChars) return whole
     // 无关键行时退化为「头部 + 尾部」快照：优先保尾部完整，头部按预算压缩，总长不超上限

package/src/client/logic/install-command.ts

@@ -29,12 +29,14 @@ export function installTargetOf(p: HubPlugin): string {
 
 /** 展示用安装命令（复制/弹窗）：目录下发的权威命令优先（CLI-only 插件如 dsh-tui
  *  需专属 profile（--profile dsh-tui），无法从 npm 包名推断，必须用官方命令）；
- *  常规插件无目录命令时用 npm 包名回退生成。 */
-export function installCommandOf(p: HubPlugin, withProfile = false): string {
+ *  常规插件无目录命令时用 npm 包名回退生成。
+ *  version 为已过发布冷却期的版本：带上它，手抄命令与一键安装的执行结果一致。 */
+export function installCommandOf(p: HubPlugin, withProfile = false, version?: string): string {
   const cmd = p.install?.command
   if (cmd) return cmd
   const prefix = `dsh plugin${withProfile ? ' --profile web' : ''} add `
-  return `${prefix}${installTargetOf(p)}`
+  const target = installTargetOf(p)
+  return `${prefix}${version === undefined || version === '' ? target : `${target}@${version}`}`
 }
 
 /** 把任务/安装目标归一化为 owner/repo 展示身份。 */

package/src/client/logic/installed.ts

@@ -42,7 +42,7 @@ export interface InstalledItem {
   catalogVersion: string | null
   /** 是否有可用更新（有版本比版本，无版本比仓库更新时间） */
   hasUpdate: boolean
-  /** 更新被供应链门禁暂缓时的可重试时刻（毫秒）；无更新/非门禁原因 → null */
+  /** 更新暂缓（新版本还没过冷却期）的可重试时刻（毫秒）；无更新/非冷却期原因 → null */
   pendingUntil: number | null
   /** 是否已加载进运行中 loader（官方 ctx.loader 对账）；false = 已安装但未挂载（装完未重启） */
   loaded: boolean