dsh-plugin 1.6.12 → 2.0.1

package/src/client/hooks/useCatalog.ts

@@ -3,11 +3,10 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Catalog data + view state for the Plugin Hub section.
+ * 插件中心的数据 + 视图状态。
  *
- * Owns the online-data pipeline (live fetch from api.dsh-plugin.org), the local
- * installed-plugin table, and the filter/search/sort/install-status view
- * state, exposing the derived visible list and per-category counts.
+ * 掌管在线数据管道（从 api.dsh-plugin.org 实时拉取）、本地已装插件表，以及
+ * 筛选/搜索/排序/安装状态等视图状态，对外暴露派生出的可见列表与各分类计数。
  */
 import { useEffect, useMemo, useRef, useState } from 'react'
 import type { HubPlugin, LocaleId } from '../types.ts'
@@ -16,15 +15,19 @@ 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 } from '../data/host.ts'
+import { fetchInstalled, fetchNpmReleaseAge } from '../data/host.ts'
+import { isReleaseTooFresh } from '../logic/release-age.ts'
 import {
-  hasUpdateOf, installedItemsOf, installedNameOf, installedVersionOf,
+  hasUpdateOf, installedItemsOf, installedNameOf, installedVersionOf, npmPackageOf,
 } from '../logic/installed.ts'
 import type { InstalledItem, InstalledVersionSignal } from '../logic/installed.ts'
 
 /** 插件市场自身仓库：DSH Plugin Hub 不显示在目录里（自己不进自己的插件列表） */
 const SELF_REPO = 'dshplugin/dsh-plugin-hub'
 
+/** 共享的空门禁集合：无暂缓包时复用，避免每次渲染新建 Set。 */
+const EMPTY_PACKAGES: ReadonlySet<string> = new Set<string>()
+
 /** 市场各排序的默认方向：全部按倒序（Star/Fork 多、更新/收录近的在前） */
 const SORT_DEFAULT_DIR: Record<SortKey, 'asc' | 'desc'> = {
   sortStars: 'desc', sortForks: 'desc', sortUpdated: 'desc', sortNewest: 'desc',
@@ -75,7 +78,7 @@ export function useCatalog(lang: LocaleId) {
   /** 当前 profile 已安装插件：npm 包名 -> manifest spec（来自宿主本地路由） */
   const [installed, setInstalled] = useState<Record<string, string>>({})
   /** 安装时记录的目录信号：repo(小写) -> { version, updatedAt }（来自宿主本地路由）；
-   *  npmPackage 为 npm 优先通道反查命中的包名映射（目录数据未下发时客户端靠它把依赖 key 匹配回仓库） */
+   *  npmPackage 为安装时记录的包名映射（目录数据未下发时客户端靠它把依赖 key 匹配回仓库） */
   const [versions, setVersions] = useState<Record<string, InstalledVersionSignal>>({})
   /** 每个依赖在系统上的安装目录（profile/node_modules/<包名>），详情视图展示用 */
   const [installPaths, setInstallPaths] = useState<Record<string, string> | null>(null)
@@ -176,25 +179,83 @@ export function useCatalog(lang: LocaleId) {
     return () => { cancelled = true }
   }, [reloadKey])
 
-  /** 插件是否已安装：匹配 Git spec 中的 owner/repo，或 npm 通道安装的依赖包名；命中返回 npm 包名。 */
+  /** 插件是否已安装：匹配 Git spec 中的 owner/repo，或 npm 安装的依赖包名；命中返回 npm 包名。 */
   const installedName = (p: HubPlugin): string | null => installedNameOf(p, installed, versions)
 
   /** 该插件安装时记录的目录版本（无记录/未安装 → null）。 */
   const installedVersion = (p: HubPlugin): string | null => installedVersionOf(p, versions)
 
   /**
-   * 是否有更新：仅对已安装插件有意义。
-   * 双信号判定——有 release 版本的比版本；无版本（repo 不打 tag）的比仓库最近更新时间
-   * （repoUpdatedAt，ISO 字符串字典序 = 时间序），更新时间变新说明有新提交。
+   * 供应链门禁状态：包名集合为当前「暂缓提示」的 npm 包（最新版本发布未满门槛）。
+   * key 是这批候选包名的指纹，与已查出的 key 一致才算就绪，避免查询未回来时先显示更新。
    */
-  const hasUpdate = (p: HubPlugin): boolean => hasUpdateOf(p, installed, versions)
+  const [releaseAge, setReleaseAge] = useState<{ key: string; held: ReadonlySet<string> }>({ key: '', held: EMPTY_PACKAGES })
 
-  /** 已安装项统一列表（目录元数据 + 运行时信息合并）：驱动「已安装」tab。 */
-  const installedItems = useMemo<InstalledItem[]>(
+  /** 已安装项原始列表（未套门禁）：先算出来才能收集需要查发布时间的候选包名。 */
+  const rawInstalledItems = useMemo<InstalledItem[]>(
     () => installedItemsOf(plugins, installed, versions, installPaths, loadedNames, dshCapableNames),
     [plugins, installed, versions, installPaths, loadedNames, dshCapableNames],
   )
 
+  /** 门禁候选：有更新、且有 npm 包名（更新走 npm registry）的已安装插件包名。 */
+  const releaseAgeCandidates = useMemo(() => {
+    const names = new Set<string>()
+    for (const item of rawInstalledItems) {
+      if (!item.hasUpdate || !item.plugin) continue
+      const pkg = npmPackageOf(item.plugin, versions)
+      if (pkg !== null) names.add(pkg)
+    }
+    return [...names].sort()
+  }, [rawInstalledItems, versions])
+  const releaseAgeKey = releaseAgeCandidates.join('\n')
+
+  useEffect(() => {
+    if (releaseAgeKey === releaseAge.key) return
+    if (releaseAgeCandidates.length === 0) {
+      setReleaseAge({ key: '', held: EMPTY_PACKAGES })
+      return
+    }
+    let cancelled = false
+    // 批量一次查询；失败/返回 null 时 held 为空 → 按原逻辑照常提示，网络问题不吃掉真实更新
+    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 })
+    })
+    return () => { cancelled = true }
+  }, [releaseAgeKey, releaseAge.key])
+
+  /** 门禁结果是否已就绪（候选为空也算就绪）：未就绪时不写更新提醒，等查询回来再定。 */
+  const releaseAgeReady = releaseAgeKey === releaseAge.key
+  const heldPackages = releaseAgeReady ? releaseAge.held : EMPTY_PACKAGES
+
+  /**
+   * 是否有更新：仅对已安装插件有意义。
+   * 双信号判定——有 release 版本的比版本；无版本（repo 不打 tag）的比仓库最近更新时间
+   * （repoUpdatedAt，ISO 字符串字典序 = 时间序），更新时间变新说明有新提交。
+   * 另加供应链门禁：npm 包最新版本发布未满门槛时视为暂缓，不打更新标记。
+   */
+  const hasUpdate = (p: HubPlugin): boolean => {
+    if (!hasUpdateOf(p, installed, versions)) return false
+    const pkg = npmPackageOf(p, versions)
+    return pkg === null || !heldPackages.has(pkg)
+  }
+
+  /** 已安装项统一列表（目录元数据 + 运行时信息合并）：门禁命中的去掉更新标记，驱动「已安装」tab。 */
+  const installedItems = useMemo<InstalledItem[]>(() => {
+    if (heldPackages.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
+    })
+  }, [rawInstalledItems, heldPackages, versions])
+
   /**
    * Hub 自身更新状态：Hub 就是当前运行的应用（始终已安装，无需 installedName 命中）。
    * 以 Worker 版本控制中心返回的「最新版本」为准，与当前运行的版本号比对——
@@ -210,15 +271,8 @@ export function useCatalog(lang: LocaleId) {
   const hubUpdateState: HubUpdateState = (() => {
     if (!hubUpdateInfo) return 'none'
     if (hubCurrentVersion === '' || hubUpdateInfo.version === hubCurrentVersion) return 'latest'
-    const publishedAt = hubUpdateInfo.publishedAt
-    if (publishedAt) {
-      const publishedMs = Date.parse(publishedAt)
-      if (!Number.isNaN(publishedMs)) {
-        // 24 小时 + 30 分钟缓冲（防网络/CDN 边缘时间偏差）
-        const MIN_RELEASE_AGE_MS = 24 * 60 * 60 * 1000 + 30 * 60 * 1000
-        if (Date.now() - publishedMs < MIN_RELEASE_AGE_MS) return 'pending'
-      }
-    }
+    // 供应链门禁（24h + 30 分钟缓冲）与插件更新同一口径：发布未满门槛的版本暂缓提示
+    if (isReleaseTooFresh(hubUpdateInfo.publishedAt, Date.now())) return 'pending'
     return 'available'
   })()
   const hubHasUpdate = hubUpdateState === 'available'
@@ -252,7 +306,7 @@ export function useCatalog(lang: LocaleId) {
     })
   }, [plugins, category, query, sort, sortDir, installed])
 
-  /** Per-category plugin counts shown on the category chips. */
+  /** 分类 chip 上展示的各分类插件计数。 */
   const categoryCounts = useMemo(() => {
     const counts: Record<string, number> = {}
     for (const p of plugins ?? []) {
@@ -274,6 +328,7 @@ export function useCatalog(lang: LocaleId) {
     hasUpdate,
     hubHasUpdate,
     hubUpdateState,
+    releaseAgeReady,
     hubCurrentVersion,
     hubUpdateInfo,
     hubAboutInfo,

package/src/client/hooks/useIncrementalList.ts

@@ -3,11 +3,9 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Incremental list: renders only the first batch of a (potentially huge)
- * result set and appends the next batch whenever the end sentinel scrolls
- * into view, so the plugin market never mounts thousands of cards at once.
- * The items reference is the list identity — category / search / sort
- * changes produce a new array, which resets the window to the first batch.
+ * 增量列表：只渲染（可能很大的）结果集的第一批，末尾哨兵滚入视口时就追加下一批，
+ * 让插件市场绝不一次性挂载成千上万张卡片。
+ * items 引用即列表身份 —— 分类/搜索/排序变化会产出新数组，窗口随之重置回第一批。
  */
 import { useEffect, useRef, useState } from 'react'
 

package/src/client/hooks/useLanguage.ts

@@ -3,11 +3,9 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Language state for the section: the Hub shares the host (system) locale —
- * the header language toggle writes the host locale preference via setLocale,
- * so the host chrome (left sidebar, settings dialog) and the Hub panel switch
- * together instead of drifting apart. Exposes the localized dictionary lookup
- * `t()` plus the zh/en language flag and the /zh/ URL path prefix.
+ * 板块的语言状态：Hub 与宿主（系统）locale 共用 —— 头部语言开关通过 setLocale 写入
+ * 宿主语言偏好，让宿主界面（左侧菜单、设置弹窗）与 Hub 面板一起切换、不会各说各话。
+ * 对外暴露本地化字典查询 `t()`、zh/en 语言标记与 /zh/ URL 路径前缀。
  */
 import { useEffect, useState } from 'react'
 import type { LocaleId, SectionProps } from '../types.ts'
@@ -22,7 +20,7 @@ export function useLanguage(locale: SectionProps['locale']) {
   useEffect(() => locale.subscribe(() => setRev((r) => r + 1)), [locale])
   const lang: LocaleId = locale.getSnapshot().active
   const langKey: LocaleId = lang === 'en' ? 'en' : 'zh'
-  // dsh-plugin.org keeps zh pages under the /zh/ prefix; en is the root.
+  // dsh-plugin.org 的 zh 页面挂在 /zh/ 前缀下，en 在根路径。
   const langPath = langPathOf(lang)
 
   // 界面语言跟随宿主（系统）locale；宿主的 t() 绑定宿主 locale，

package/src/client/hooks/useSettings.ts

@@ -3,11 +3,10 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Hub settings state: loaded once from the host's local /settings route
- * (persisted at ~/.dsh/profiles/<profile>/hub-settings.json), updated
- * optimistically. Every change POSTs the patch immediately so a toggled
- * switch survives a reload; a host without the server routes falls back to
- * the defaults and keeps working (settings simply do not persist).
+ * 插件中心设置状态：从宿主本地 /settings 路由加载一次（持久化在
+ * ~/.dsh/profiles/<profile>/hub-settings.json），并按乐观方式更新。
+ * 每次改动立即 POST 补丁，切换过的开关刷新后仍在；宿主未挂服务端路由时退回默认值
+ * 继续可用（设置不持久化而已）。
  */
 import { useCallback, useEffect, useState } from 'react'
 
@@ -20,10 +19,6 @@ export interface HubSettings {
   npmRegistry: string
   /** 启用命令行安装 NPM 包（默认开） */
   enableNpmInstall: boolean
-  /** 启用命令行安装 GitHub 源码（默认开） */
-  enableGitInstall: boolean
-  /** 启用命令行粘贴 dsh plugin 命令安装（默认开） */
-  enableDshInstall: boolean
   /** 日志存放位置覆盖（空串 = 默认 ~/.dsh/profiles/<profile>/hub.log） */
   logPath: string
 }
@@ -33,8 +28,6 @@ export const DEFAULT_SETTINGS: HubSettings = {
   proxy: '',
   npmRegistry: '',
   enableNpmInstall: true,
-  enableGitInstall: true,
-  enableDshInstall: true,
   logPath: '',
 }
 

package/src/client/hooks/useTaskQueue.ts

@@ -3,19 +3,18 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Background install/remove task queue for the Plugin Hub.
+ * 插件中心的后台安装/卸载任务队列。
  *
- * Mirrors the server-side FIFO active queue by polling /active, settles
- * vanished tasks against /status, and exposes the queue actions (install,
- * uninstall, cancel) plus the modal task lookups used by the dialogs.
+ * 通过轮询 /active 镜像服务端 FIFO 活动队列，对消失的任务用 /status 收尾，并暴露
+ * 队列动作（安装、卸载、取消）以及弹窗用的任务查找。
  */
 import { useEffect, useRef, useState } from 'react'
 import type { HubPlugin, InstallChannel, LocaleId, Translate } from '../types.ts'
 import { executedCommandOf, installCommandOf, installTargetOf, repoFromInstallTarget } from '../logic/install-command.ts'
 import type { InstalledItem } from '../logic/installed.ts'
 
-/** 安装/卸载请求超时（ms）：服务端 preflight + npm 反查可能耗时（各自都有超时，合计约 20~30s），
- *  给足余量；超时主动中止，避免服务端 preflight 网络挂起时前端永久卡「安装中 0%」。 */
+/** 安装/卸载请求超时（ms）：服务端入队前要做目录包校验与网络探测（各自有超时，合计可达十几秒），
+ *  给足余量；超时主动中止，避免服务端网络挂起时前端永久卡「安装中 0%」。 */
 const REQUEST_TIMEOUT_MS = 60_000
 
 /** 客户端任务队列项：镜像服务端 active 任务（running 在前、pending 在后）。 */
@@ -28,8 +27,8 @@ export interface QueueTask {
   desc?: string
   /** 所属插件仓库（owner/repo）：失败时错误弹窗据此提供「去仓库反馈」入口；卸载为 null */
   repo: string | null
-  /** 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令三张卡片）：失败时错误/通知精准
-   *  溯源「从哪个入口发起」；目录插件安装无此字段（非自定义入口）。 */
+  /** 自定义安装入口渠道（NPM 包卡片）：失败时错误/通知精准溯源「从哪个入口发起」；
+   *  目录插件安装无此字段（非自定义入口）。 */
   channel?: InstallChannel
   /** 实际动作（add/update/remove）：成功通知据此区分「安装成功」与「更新成功」。
    *  服务端 /active 带回真实动作；本地乐观入队按 update 标记推断。 */
@@ -42,11 +41,11 @@ export interface QueueTask {
   progress: number
   lines: string[]
   /** 乐观入队条目：点击安装后立即显示「正在安装中」，等 POST 响应回来再换成真实任务 id。
-   *  服务端还没登记（preflight 中），轮询合并/消失检测都必须跳过，避免被当作已结束任务收尾。 */
+   *  服务端还没登记，轮询合并/消失检测都必须跳过，避免被当作已结束任务收尾。 */
   optimistic?: boolean
-  /** 实际执行的安装命令（npm/git 通道随插件数据决定）：失败时 issue 预填如实展示 */
+  /** 实际执行的安装命令（随插件数据决定）：失败时 issue 预填如实展示 */
   command?: string
-  /** 尝试过的安装方式（npm registry 反查 + 实际执行命令，按先后顺序）：失败时 issue 预填一并贴给作者 */
+  /** 实际执行/重试过的安装命令（按先后顺序）：失败时 issue 预填一并贴给作者 */
   attempts?: string[]
   /** 完成结果是否需要重启才生效（服务端任务终态带出）。默认 true 保底：数据缺失时不静默视为已生效。
    *  仅刷新解决不了的兜底场景（热挂载失败 / 非 dsh 插件 / 更新）为 true，结果视图给「立即重启」；
@@ -70,7 +69,7 @@ export interface PendingRestart {
 
 export interface TaskQueueOptions {
   t: Translate
-  /** 界面语言（zh/en）：随安装请求带给服务端，网络预检等错误消息按用户语言提示 */
+  /** 界面语言（zh/en）：随安装请求带给服务端，安装前网络探测等错误消息按用户语言提示 */
   langKey?: LocaleId
   refreshInstalled: () => void
   /** 任务成功完成：viaModal 表示任务对应当前打开弹窗（弹窗切结果视图），否则走 Toast；repo 供成功通知记录；
@@ -79,7 +78,7 @@ export interface TaskQueueOptions {
    *  update 表示实际执行的是更新（覆盖重装）而非首次安装：通知中心据此显示「更新成功」而非「安装成功」。 */
   onInstallDone: (viaModal: boolean, repo: string | null, needsRestart: boolean, update?: boolean, needsReload?: boolean) => void
   onUninstallDone: (viaModal: boolean, repo: string | null, needsRestart: boolean, needsReload?: boolean) => void
-  /** 任务失败：完整输出或兜底文案 + 所属插件仓库 + 操作类型（安装/卸载）+ 实际执行的安装命令（issue 预填用，可缺省）+ 尝试过的安装方式（npm 反查/执行命令，可缺省）+ 是否更新。 */
+  /** 任务失败：完整输出或兜底文案 + 所属插件仓库 + 操作类型（安装/卸载）+ 实际执行的安装命令（issue 预填用，可缺省）+ 实际执行/重试过的安装命令（可缺省）+ 是否更新。 */
   onError: (message: string, repo: string | null, kind: 'install' | 'uninstall', command?: string, attempts?: string[], update?: boolean) => void
   /** 当前打开的安装/卸载弹窗插件：用于在弹窗内匹配进行中的任务。 */
   installPlugin: HubPlugin | null
@@ -96,14 +95,10 @@ export interface TaskQueueOptions {
   resolvePending: (repo: string) => { desc?: string; version?: string } | null
 }
 
-/** 入口渠道的 i18n key：NPM 包 / GitHub 源码 / DSH 命令。 */
-const channelKeyOf = (channel: InstallChannel): string =>
-  channel === 'git' ? 'installChannelGit' : channel === 'dsh' ? 'installChannelDsh' : 'installChannelNpm'
-
 /** 失败消息的入口溯源前缀：自定义安装（带渠道）在错误正文顶部精准指出从哪张卡片发起；
  *  目录插件安装（无渠道）返回 null，错误正文保持原样。 */
 const entryLineOf = (t: Translate, channel: InstallChannel | undefined): string | null =>
-  channel ? t('installEntryLine', { c: t(channelKeyOf(channel)) }) : null
+  channel ? t('installEntryLine', { c: t('installChannelNpm') }) : null
 
 export function useTaskQueue(opts: TaskQueueOptions) {
   const {
@@ -332,13 +327,12 @@ export function useTaskQueue(opts: TaskQueueOptions) {
                 lines: Array.isArray(a.lines) ? (a.lines as string[]) : (prevTask?.lines ?? []),
                 attempts: Array.isArray(a.attempts) ? (a.attempts as string[]) : (prevTask?.attempts ?? []),
                 needsRestart: typeof a.needsRestart === 'boolean' ? a.needsRestart : (prevTask?.needsRestart ?? true),
-                // 入口渠道：本地乐观入队已带；服务端 /active 也带回（刷新恢复用），服务端优先
-                channel: (a.installChannel === 'npm' || a.installChannel === 'git' || a.installChannel === 'dsh')
-                  ? a.installChannel
-                  : prevTask?.channel,
+                // 入口渠道：本地乐观入队已带；服务端 /active 也带回（刷新恢复用），服务端优先。
+                // 旧服务端可能回传已废弃的 'git'/'dsh' 渠道，忽略即可、回退本地值。
+                channel: a.installChannel === 'npm' ? 'npm' : prevTask?.channel,
               })
             }
-            // 保留乐观条目：服务端尚未登记（preflight 中），无真实 id，不能因 active 缺它就被合并吞掉
+            // 保留乐观条目：服务端尚未登记，无真实 id，不能因 active 缺它就被合并吞掉
             const keepOpt = prev.filter((q) => q.optimistic && !next.some((x) => x.id === q.id))
             if (keepOpt.length > 0) next.push(...keepOpt)
             // 保留「已从服务端消失、但尚未收尾」的任务：收尾（settleTask）负责移除。
@@ -402,8 +396,9 @@ export function useTaskQueue(opts: TaskQueueOptions) {
               lines: Array.isArray(a.lines) ? (a.lines as string[]) : [],
               attempts: Array.isArray((a as { attempts?: unknown }).attempts) ? ((a as { attempts: string[] }).attempts) : [],
               needsRestart: typeof (a as { needsRestart?: unknown }).needsRestart === 'boolean' ? (a as { needsRestart: boolean }).needsRestart : true,
-              // 服务端登记的入口渠道：自定义安装刷新后也能精准溯源（目录安装无此字段）
-              channel: (a.installChannel === 'npm' || a.installChannel === 'git' || a.installChannel === 'dsh') ? a.installChannel : undefined,
+              // 服务端登记的入口渠道：自定义安装刷新后也能精准溯源（目录安装无此字段）。
+              // 旧服务端可能回传已废弃的 'git'/'dsh' 渠道，忽略即可。
+              channel: a.installChannel === 'npm' ? 'npm' : undefined,
             }
           })
         if (items.length > 0 || pendingRef.current.length > 0) {
@@ -411,7 +406,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
           // 刷新后恢复的任务同样保持折叠：摘要条提示进行中，点开才看明细/日志
           pollQueue()
         }
-      } catch { /* host without the plugin's server routes */ }
+      } catch { /* 宿主未挂本插件服务端路由 */ }
     }
     void restore()
     return () => { cancelled = true }
@@ -420,9 +415,9 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   /** 弹窗动作：直接安装。请求宿主本地路由，任务进入服务端队列（FIFO），弹窗内实时显示进度。 */
   /** 安装入队核心：目录插件（catalog，后端走目录白名单）与命令行安装（custom，
    *  受安全开关控制）共用。队列条目一律用仓库名（repo）展示/防重，只有发给后端的
-   *  实际安装目标（target）随通道变化（npm 包名 / github: 源）。 */
+   *  实际安装目标（target）为 npm 包名。 */
   const submitInstall = async (input: {
-    /** 发给后端的实际安装目标：npm 包名或 github: 源（服务端再决定最终通道） */
+    /** 发给后端的实际安装目标：npm 包名 */
     target: string
     /** 队列展示与防重用的仓库名 */
     repo: string
@@ -435,7 +430,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     update?: boolean
     /** 全局 npm 安装包列表（`npm install -g <pkgs>`）：非空时服务端执行全局安装，不进任何 profile */
     globalNpm?: string[]
-    /** 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：随请求上报服务端落日志，
+    /** 自定义安装入口渠道（NPM 包卡片）：随请求上报服务端落日志，
      *  失败弹窗/通知据此精准溯源「从哪个入口发起」；目录安装不传。 */
     channel?: InstallChannel
   }) => {
@@ -445,7 +440,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     if (submittingRef.current.has(input.repo)) return
     submittingRef.current.add(input.repo)
     // 乐观入队：点击安装立即显示「正在安装中」，不等 POST 响应。
-    // 服务端 /install 会先跑预检（preflight，可能耗时数秒）再入队，若等响应才入队列，
+    // 服务端 /install 会先做校验与网络探测再入队，若等响应才入队列，
     // 用户点完安装立刻去看任务会看不到 —— 只有刷新后 restore 才拉回来。
     // 用负临时 id 占位，响应回来换成真实 task id；失败/出错则移除该占位。
     tempIdRef.current -= 1
@@ -458,7 +453,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       command: input.command,
       channel: input.channel,
       action: input.update ? 'update' : 'add',
-      // 服务端登记后 /active 会带回真实尝试记录（npm 反查 + 执行命令），先占位空列表
+      // 服务端登记后 /active 会带回真实执行过的命令，先占位空列表
       attempts: [], needsRestart: true,
     }])
     setSubmitting(true)
@@ -473,9 +468,9 @@ export function useTaskQueue(opts: TaskQueueOptions) {
           display: input.repo,
           source: input.source,
           mode: input.update ? 'update' : undefined,
-          // 界面语言带给服务端：网络预检等错误消息按用户当前语言返回（中文界面给中文，英文界面给英文）
+          // 界面语言带给服务端：安装前网络探测等错误消息按用户当前语言返回（中文界面给中文，英文界面给英文）
           ...(langKey ? { lang: langKey } : {}),
-          // 自定义安装入口渠道（三张卡片之一）：服务端日志/报错提示据此溯源
+          // 安装入口渠道（只可能是 npm）：服务端日志/报错提示据此溯源
           ...(input.channel ? { installChannel: input.channel } : {}),
           ...(input.globalNpm && input.globalNpm.length > 0 ? { globalNpm: input.globalNpm } : {}),
         }),
@@ -485,7 +480,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       if (!data.ok || typeof data.task !== 'number') {
         // 请求层失败（重复安装 409 / 参数错误 / 安全开关 403 等）：移除乐观条目 + 完整错误弹窗
         applyQueue((prev) => prev.filter((x) => x.id !== tempId))
-        // 同步 400（如预检拦截）服务端会附上已尝试的安装方式，issue 预填一并展示；
+        // 同步 400（如安装前网络探测拦截）服务端会附上已尝试的安装方式，issue 预填一并展示；
         // 用 || 而非 ?? ：error 为空字符串时回退 HTTP 状态，避免复制出来是空白。
         // 自定义安装（带入口渠道）：错误正文顶部精准提示「从哪张卡片发起」
         const entry = entryLineOf(t, input.channel)
@@ -521,12 +516,12 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     }
   }
 
-  /** 目录插件安装：通道由目录数据（npmPackage）决定，走 catalog 白名单。 */
+  /** 目录插件安装：安装目标取目录数据的 npm 包名，走 catalog 白名单。 */
   const installNow = async (p: HubPlugin, opts?: { update?: boolean }) => {
     const repo = p.source?.repo ?? ''
     if (!repo) return
-    // 安装通道决策（用户无感知）：有 npm 包名 → 走 npm；否则 git 直装。
-    const { target } = installTargetOf(p)
+    // 目录条目必带 npm 包名：直接用包名安装（用户无感知）。
+    const target = installTargetOf(p)
     if (!target) return
     await submitInstall({
       target,
@@ -540,12 +535,11 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     })
   }
 
-  /** 命令行安装：用户手输 npm 包名或 GitHub 地址，走 custom 源（受安全开关控制）。
+  /** 命令行安装：用户手输 npm 包名，走 custom 源（受安全开关控制）。
    *  update=true 时对已安装目标放行覆盖重装（与目录插件「更新」同一语义）。
-   *  channel=入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：上报服务端落日志，
-   *  失败弹窗/通知据此精准溯源。
-   *  队列展示/防重一律用归一化身份（owner/repo 或 npm 包名）：与服务端 /active 合并、
-   *  弹窗目标匹配同口径，npm 包名透传不受影响。 */
+   *  channel=入口渠道（NPM 包卡片）：上报服务端落日志，失败弹窗/通知据此精准溯源。
+   *  队列展示/防重一律用归一化身份：与服务端 /active 合并、弹窗目标匹配同口径，
+   *  npm 包名透传不受影响。 */
   const installCustom = async (raw: string, opts?: { update?: boolean; channel?: InstallChannel }) => {
     const target = raw.trim()
     if (!target) return

package/src/client/index.tsx

@@ -3,9 +3,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * dsh-plugin client entry: wires the Plugin Hub into the host settings via
- * the module-loader bundle (see tsdown.config.ts). All UI logic lives in
- * PluginHubSection; this file only performs the cordis apply wiring.
+ * dsh-plugin 客户端入口：通过模块加载器 bundle（见 tsdown.config.ts）把插件中心接入宿主设置。
+ * 全部 UI 逻辑都在 PluginHubSection；本文件只做 cordis apply 接线。
  */
 import { createElement as h } from 'react'
 import type { HubClientContext } from './types.ts'