dsh-plugin 1.0.0 → 1.1.1

package/src/client/hooks/useCatalog.ts

@@ -7,11 +7,14 @@
  */
 import { useEffect, useMemo, useState } from 'react'
 import type { HubPlugin, LocaleId } from '../types.ts'
-import { normalize } from '../lib/catalog.ts'
+import { HUB_ABOUT_URL, HUB_REPO, HUB_UPDATE_URL, normalize, PLUGIN_VERSION } from '../lib/catalog.ts'
+import type { HubAboutInfo, HubUpdateInfo } from '../lib/catalog.ts'
 import type { SortKey } from '../lib/catalog.ts'
 
 const PLUGINS_URL = (lang: LocaleId) => `https://dsh-plugin.org/api/plugins.${lang}.json`
 const STATS_URL = 'https://dsh-plugin.org/api/stats.json'
+/** 插件市场自身仓库：DSH-Plugin Hub 不显示在目录里（自己不进自己的插件列表） */
+const SELF_REPO = 'dshplugin/dsh-plugin-hub'
 
 export function useCatalog(lang: LocaleId) {
   /** 目录插件（仅保留人工验证通过的条目） */
@@ -27,8 +30,13 @@ export function useCatalog(lang: LocaleId) {
   const [installedFilter, setInstalledFilter] = useState<'all' | 'installed' | 'notInstalled'>('all')
   /** 当前 profile 已安装插件：npm 包名 -> manifest spec（来自宿主本地路由） */
   const [installed, setInstalled] = useState<Record<string, string>>({})
-  /** 安装时记录的目录信号：repo(小写) -> { version, updatedAt }（来自宿主本地路由） */
-  const [versions, setVersions] = useState<Record<string, { version: string; updatedAt: string }>>({})
+  /** 安装时记录的目录信号：repo(小写) -> { version, updatedAt }（来自宿主本地路由）；
+   *  npmPackage 为 npm 优先通道反查命中的包名映射（目录数据未下发时客户端靠它把依赖 key 匹配回仓库） */
+  const [versions, setVersions] = useState<Record<string, { version: string; updatedAt: string; npmPackage?: string }>>({})
+  /** Hub 自我更新信息：来自 CF Worker 版本控制中心（hub.dsh-plugin.org），与目录数据解耦 */
+  const [hubUpdateInfo, setHubUpdateInfo] = useState<HubUpdateInfo | null>(null)
+  /** 头部「关注我们」弹窗内容（平台介绍 + 反馈群二维码）：来自同款 Worker /about，Markdown 推送非写死 */
+  const [hubAboutInfo, setHubAboutInfo] = useState<HubAboutInfo | null>(null)
 
   // 拉取目录 + 统计。在线 API 已只返回 verified；再过滤一次，保证只展示人工验证通过的插件。
   useEffect(() => {
@@ -41,19 +49,29 @@ export function useCatalog(lang: LocaleId) {
         if (!res.ok) throw new Error(String(res.status))
         return res.json()
       })
-    fetchData(PLUGINS_URL(lang)).then((data) => {
-      if (cancelled) return
-      const list = (Array.isArray(data) ? data : []).map((item) => normalize(item as Record<string, unknown>))
-      setPlugins(list.filter((p) => p.compatibility?.status === 'verified'))
-    }).catch(() => {
-      if (!cancelled) setFailed(true)
-    })
-    fetchData(STATS_URL).then((s) => {
-      const stats = s as { total?: number; verified?: number }
-      if (!cancelled && stats && typeof stats.total === 'number' && typeof stats.verified === 'number') {
-        setStats({ total: stats.total, verified: stats.verified })
-      }
-    }).catch(() => {})
+    // 目录数据直拉：hub 自身版本由独立 Worker 版本控制中心管理，不再依赖主站版本号接口；
+    // 数据接口 CDN 缓存 1 小时，发布新数据后最长 1 小时全网生效。
+    const load = () =>
+      Promise.all([fetchData(PLUGINS_URL(lang)), fetchData(STATS_URL)])
+    load()
+      .then(([data, s]) => {
+        if (cancelled) return
+        const list = (Array.isArray(data) ? data : []).map((item) => normalize(item as Record<string, unknown>))
+        // 插件市场不显示自己：DSH-Plugin Hub 从目录里排除自身条目，
+        // 防止「自己出现在自己的插件列表里、还能自己安装自己」；统计计数同步减 1 保持与列表一致。
+        // 主站数据构建侧已同步防止（registry/API 不再含自身），此处为已发布旧数据/CDN 缓存期的兜底。
+        const hadSelf = list.some((p) => p.source?.repo === SELF_REPO)
+        setPlugins(list.filter((p) => p.compatibility?.status === 'verified' && p.source?.repo !== SELF_REPO))
+        const stats = s as { total?: number; verified?: number }
+        if (stats && typeof stats.total === 'number' && typeof stats.verified === 'number') {
+          setStats(hadSelf
+            ? { total: stats.total - 1, verified: stats.verified - 1 }
+            : { total: stats.total, verified: stats.verified })
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setFailed(true)
+      })
     return () => { cancelled = true }
     // lang 必须进依赖：切换界面语言要重新拉对应语言的数据文件，
     // 否则英文模式仍停留在 plugins.zh.json，描述/名称全是中文
@@ -64,7 +82,7 @@ export function useCatalog(lang: LocaleId) {
     try {
       const res = await fetch('/dsh-plugin-hub/installed', { cache: 'no-store' })
       if (!res.ok) return
-      const data = await res.json() as { installed?: Record<string, string>; versions?: Record<string, { version: string; updatedAt: string }> }
+      const data = await res.json() as { installed?: Record<string, string>; versions?: Record<string, { version: string; updatedAt: string; npmPackage?: string }> }
       setInstalled(data.installed ?? {})
       setVersions(data.versions ?? {})
     } catch {
@@ -75,7 +93,43 @@ export function useCatalog(lang: LocaleId) {
   // 首次进入拉取已安装表（依赖宿主 webServer 服务）
   useEffect(() => { refreshInstalled() }, [])
 
-  /** 插件是否已安装：匹配 installed spec 中的 `github:<owner>/<repo>`；命中返回 npm 包名。 */
+  // Hub 自身版本检查走独立 Worker（版本控制中心）：发新版后写一次 Worker KV，
+  // 所有已装用户立即看到「可更新」+ Markdown 变更记录，不再依赖主站目录数据管道。
+  // 失败静默降级为 null（徽标不出现，不影响目录本身加载）。
+  useEffect(() => {
+    let cancelled = false
+    fetch(HUB_UPDATE_URL, { cache: 'no-store' })
+      .then((res): Promise<HubUpdateInfo | null> => (res.ok ? res.json() : Promise.resolve(null)))
+      .then((data) => {
+        if (cancelled || !data) { if (!cancelled) setHubUpdateInfo(null); return }
+        const version = typeof data.version === 'string' && data.version.length > 0 ? data.version : null
+        setHubUpdateInfo(version === null
+          ? null
+          : { version, publishedAt: data.publishedAt ?? null, notes: data.notes ?? null })
+      })
+      .catch(() => { if (!cancelled) setHubUpdateInfo(null) })
+    return () => { cancelled = true }
+  }, [reloadKey])
+
+  // 「关注我们」内容走同一套 Worker：作者写好 Markdown（平台介绍 + 反馈群二维码）推送 /admin/about，
+  // 客户端下次进入拉 /about 即可看到最新，非写死。失败静默为 null（弹窗展示兜底文案，不阻塞）。
+  useEffect(() => {
+    let cancelled = false
+    fetch(HUB_ABOUT_URL, { cache: 'no-store' })
+      .then((res): Promise<HubAboutInfo | null> => (res.ok ? res.json() : Promise.resolve(null)))
+      .then((data) => {
+        if (cancelled) return
+        if (!data || data.content === null || data.content === undefined) { setHubAboutInfo(null); return }
+        const content = typeof data.content === 'string' || typeof data.content === 'object' ? data.content : null
+        setHubAboutInfo(content === null
+          ? null
+          : { content, updatedAt: data.updatedAt ?? null })
+      })
+      .catch(() => { if (!cancelled) setHubAboutInfo(null) })
+    return () => { cancelled = true }
+  }, [reloadKey])
+
+  /** 插件是否已安装：匹配 installed spec 中的 `github:<owner>/<repo>`，或 npm 通道安装的依赖包名；命中返回 npm 包名。 */
   const installedName = (p: HubPlugin): string | null => {
     const repo = p.source?.repo
     if (!repo) return null
@@ -83,6 +137,15 @@ export function useCatalog(lang: LocaleId) {
     for (const [name, spec] of Object.entries(installed)) {
       if (spec.toLowerCase().includes(needle)) return name
     }
+    // npm 通道安装：profile 依赖 key 直接是 npm 包名。包名来源两处——目录数据（npmPackage），
+    // 或服务端 npm 优先反查持久化的映射（versions[repo].npmPackage，覆盖组织 scope 与 GitHub
+    // 用户名不一致、目录未下发包名的场景）；命中任一并依赖 key 真实存在即视为已安装
+    const pkg = ((p.source?.npmPackage || versions[repo.toLowerCase()]?.npmPackage) ?? '').toLowerCase()
+    if (pkg) {
+      for (const name of Object.keys(installed)) {
+        if (name.toLowerCase() === pkg) return name
+      }
+    }
     return null
   }
 
@@ -109,6 +172,18 @@ export function useCatalog(lang: LocaleId) {
     return Boolean(current && rec.updatedAt && current > rec.updatedAt)
   }
 
+  /**
+   * Hub 自身是否有可用更新：Hub 就是当前运行的应用（始终已安装，无需 installedName 命中）。
+   * 以 Worker 版本控制中心返回的「最新版本」为准，与当前运行的版本号比对——
+   * 构建时注入的 PLUGIN_VERSION 是运行 bundle 的真实版本；测试/异常场景缺失时
+   * 回退到安装时记录的版本。版本号不等即新版（版本号只在发版时变更，绝无降级场景）。
+   */
+  const hubHasUpdate = (() => {
+    if (!hubUpdateInfo) return false
+    const current = PLUGIN_VERSION || versions[HUB_REPO]?.version || null
+    return current !== null && hubUpdateInfo.version !== current
+  })()
+
   /** 当前分类下的插件（「全部」时为整个目录）。 */
   const categoryPlugins = useMemo(() => {
     if (!plugins) return []
@@ -174,6 +249,9 @@ export function useCatalog(lang: LocaleId) {
     installedName,
     installedVersion,
     hasUpdate,
+    hubHasUpdate,
+    hubUpdateInfo,
+    hubAboutInfo,
     refreshInstalled,
     category,
     setCategory,

package/src/client/hooks/useTaskQueue.ts

@@ -7,6 +7,7 @@
  */
 import { useEffect, useRef, useState } from 'react'
 import type { HubPlugin, Translate } from '../types.ts'
+import { installCommandOf, installTargetOf } from '../lib/catalog.ts'
 
 /** 客户端任务队列项：镜像服务端 active 任务（running 在前、pending 在后）。 */
 export interface QueueTask {
@@ -25,6 +26,17 @@ export interface QueueTask {
   status: 'pending' | 'running' | 'cancelling'
   progress: number
   lines: string[]
+  /** 乐观入队条目：点击安装后立即显示「正在安装中」，等 POST 响应回来再换成真实任务 id。
+   *  服务端还没登记（preflight 中），轮询合并/消失检测都必须跳过，避免被当作已结束任务收尾。 */
+  optimistic?: boolean
+  /** 实际执行的安装命令（npm/git 通道随插件数据决定）：失败时 issue 预填如实展示 */
+  command?: string
+  /** 尝试过的安装方式（npm registry 反查 + 实际执行命令，按先后顺序）：失败时 issue 预填一并贴给作者 */
+  attempts?: string[]
+  /** 完成结果是否需要重启才生效（服务端任务终态带出；默认 true 保持老行为：弹窗给重启选项）。
+   *  卸载时 loader 已即时移除 → false，结果视图只显示「完成」；true 时弹窗给「稍后重启/立即重启」，
+   *  通知中心待重启条目（服务端登记）同步常驻，直到用户点「立即重启」。 */
+  needsRestart: boolean
 }
 
 /** 客户端待重启项：镜像服务端内存列表 + 本地补齐的展示信息（简介/版本）。 */
@@ -41,11 +53,12 @@ export interface PendingRestart {
 export interface TaskQueueOptions {
   t: Translate
   refreshInstalled: () => void
-  /** 任务成功完成：viaModal 表示任务对应当前打开弹窗（弹窗切结果视图），否则走 Toast；repo 供成功通知记录。 */
-  onInstallDone: (viaModal: boolean, repo: string | null) => void
-  onUninstallDone: (viaModal: boolean, repo: string | null) => void
-  /** 任务失败：完整输出或兜底文案 + 所属插件仓库 + 操作类型（安装/卸载）。 */
-  onError: (message: string, repo: string | null, kind: 'install' | 'uninstall') => void
+  /** 任务成功完成：viaModal 表示任务对应当前打开弹窗（弹窗切结果视图），否则走 Toast；repo 供成功通知记录；
+   *  needsRestart 表示该任务完成后是否仍需宿主重启（结果视图据此给「重启 / 仅完成」）。 */
+  onInstallDone: (viaModal: boolean, repo: string | null, needsRestart: boolean) => void
+  onUninstallDone: (viaModal: boolean, repo: string | null, needsRestart: boolean) => void
+  /** 任务失败：完整输出或兜底文案 + 所属插件仓库 + 操作类型（安装/卸载）+ 实际执行的安装命令（issue 预填用，可缺省）+ 尝试过的安装方式（npm 反查/执行命令，可缺省）。 */
+  onError: (message: string, repo: string | null, kind: 'install' | 'uninstall', command?: string, attempts?: string[]) => void
   /** 当前打开的安装/卸载弹窗插件：用于在弹窗内匹配进行中的任务。 */
   installPlugin: HubPlugin | null
   uninstallPlugin: HubPlugin | null
@@ -71,11 +84,15 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   resolvePendingRef.current = resolvePending
   /** 当前打开弹窗所对应的任务 id：该任务完成时弹窗切换为结果视图 */
   const modalTaskRef = useRef<number | null>(null)
+  /** 已开始收尾但尚未结束的任务 id（服务端 /active 已消失 → 查 /status 中）：并发轮询时跳过，避免重复收尾 */
+  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)
 
@@ -156,42 +173,83 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       if (q.kind === 'uninstall') {
         // 卸载成功：清掉本地版本记录
         void syncInstalledVersion(q.repo, undefined, undefined)
-        onUninstallDone(modalTaskRef.current === q.id, q.repo)
+        onUninstallDone(modalTaskRef.current === q.id, q.repo, q.needsRestart)
       } else {
         // 安装成功：记录安装时的目录信号（版本 + 仓库更新时间），供「有更新」比对；
         // 同时缓存展示信息，待重启列表（服务端已登记）合并时直接补齐简介/版本
         void syncInstalledVersion(q.repo, q.version, q.updatedAt)
         pendingInfoRef.current.set(q.target, { desc: q.desc, version: q.version })
-        onInstallDone(modalTaskRef.current === q.id, q.repo)
+        onInstallDone(modalTaskRef.current === q.id, q.repo, q.needsRestart)
       }
     } else {
       // 失败：完整展示全部输出行（最新在前，逆序为日志阅读顺序），不裁剪
       const detail = lines.length > 0
         ? [...lines].reverse().join('\n')
         : q.kind === 'uninstall' ? t('uninstallFail') : t('installFail')
-      onError(detail, q.repo, q.kind)
+      onError(detail, q.repo, q.kind, q.command, q.attempts)
     }
     maybeStopPoll()
   }
 
+  /** 卸载成功收尾前的进度过渡：任务已在服务端结束，但保留本地展示，
+   *  让进度条在 ~2.4s 内缓缓跑到 100% 再切结果/Toast，给用户一个交互过程，
+   *  而不是命令一执行进度条就一闪消失。 */
+  const settleDone = (q: QueueTask, lines: string[]) => {
+    // 收尾动画期间停止轮询：任务已从服务端 /active 消失，无需再查；
+    // 停掉可避免 pollQueue 的 gone 检测把它当「再消失一次」而重复收尾
+    stopPoll()
+    const from = Math.min(q.progress, 90) // 起点最多 90，给进度条留出跑满的缓冲空间
+    const steps = 20
+    const stepMs = 120 // 20 步 × 120ms = 2.4s
+    let step = 0
+    // 动画期间固定显示「卸载中」：任务实已结束，但进度在跑，与「排队中」文案更协调
+    applyQueue((prev) => prev.map((x) => (x.id === q.id ? { ...x, status: 'running' as const } : x)))
+    const timer = window.setInterval(() => {
+      step += 1
+      const progress = Math.round(from + (100 - from) * (step / steps))
+      applyQueue((prev) => prev.map((x) => (x.id === q.id ? { ...x, progress } : x)))
+      if (step >= steps) {
+        window.clearInterval(timer)
+        finishQueueTask(true, q, lines)
+        // 队列若还有其它已在排队/执行的任务，恢复轮询继续盯；已清空则自然停住
+        if (queueRef.current.length > 0) pollQueue()
+      }
+    }, stepMs)
+  }
+
   /** 任务在 /active 中消失 = 已结束：查 /status 拿终态并收尾（cancelled 静默移除）。 */
   const settleTask = async (q: QueueTask) => {
     let status = 'failed'
     let lines: string[] = []
+    let attempts: 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[] } }
-        status = data.task?.status ?? 'failed'
-        lines = data.task?.lines ?? []
+        const data = await res.json() as { task?: { status?: string; lines?: string[]; attempts?: string[]; needsRestart?: unknown } }
+        const task = data.task
+        if (task !== undefined) {
+          status = task.status ?? 'failed'
+          lines = task.lines ?? []
+          attempts = Array.isArray(task.attempts) ? task.attempts : undefined
+          // 终态带出的「是否需要重启」覆盖本地（服务端 done 时按 loader 即时移除情况设置）
+          const needsRestart = typeof task.needsRestart === 'boolean' ? task.needsRestart : q.needsRestart
+          if (status === 'done') {
+            const settled = { ...q, needsRestart }
+            // 卸载成功走进度过渡动画；安装成功直接收尾
+            if (q.kind === 'uninstall') settleDone(settled, lines)
+            else finishQueueTask(true, settled, lines)
+            return
+          }
+          if (status === 'failed') {
+            // 服务端终态带出的尝试记录覆盖本地：以实际执行为准
+            finishQueueTask(false, { ...q, attempts }, lines)
+            return
+          }
+        }
       }
     } catch { /* 服务端不可达：按失败处理 */ }
-    if (status === 'done') finishQueueTask(true, q, lines)
-    else if (status === 'failed') finishQueueTask(false, q, lines)
-    else {
-      applyQueue((prev) => prev.filter((x) => x.id !== q.id)) // cancelled / 未知
-      maybeStopPoll()
-    }
+    applyQueue((prev) => prev.filter((x) => x.id !== q.id)) // cancelled / 未知
+    maybeStopPoll()
   }
 
   /** 轮询整个队列：合并服务端 /active（running 在前、pending 在后），
@@ -203,7 +261,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
         const res = await fetch('/dsh-plugin-hub/active', { cache: 'no-store' })
         if (!res.ok) throw new Error(`active ${res.status}`)
         const data = await res.json() as {
-          tasks?: { id?: unknown; action?: unknown; target?: unknown; status?: unknown; progress?: unknown; lines?: unknown }[]
+          tasks?: { id?: unknown; action?: unknown; target?: unknown; status?: unknown; progress?: unknown; lines?: unknown; attempts?: unknown; needsRestart?: unknown }[]
           pendingRestarts?: unknown
         }
         const active = (data.tasks ?? []).filter((a) => typeof a.id === 'number')
@@ -213,32 +271,51 @@ export function useTaskQueue(opts: TaskQueueOptions) {
         // 待重启列表同步（服务端内存态：宿主重启后自然变空，这里随之清空 UI）
         applyPending(parsePendingRestarts(data.pendingRestarts))
         // 合并：running 在前、pending 在后（与服务端一致），新出现任务补入队列
-        applyQueue((prev) => {
-          const next: QueueTask[] = []
-          for (const a of active) {
-            const id = a.id as number
-            const prevTask = prev.find((q) => q.id === id)
-            const isRemove = a.action === 'remove'
-            next.push({
-              id,
-              kind: isRemove ? 'uninstall' : 'install',
-              target: typeof a.target === 'string' ? a.target.replace(/^github:/, '') : (prevTask?.target ?? ''),
-              desc: prevTask?.desc,
-              repo: prevTask?.repo ?? (isRemove ? null : (typeof a.target === 'string' ? a.target.replace(/^github:/, '') : null)),
-              // 安装时快照的目录信号：轮询合并时保留，任务成功后记录到本地
-              version: prevTask?.version,
-              updatedAt: prevTask?.updatedAt,
-              status: a.status === 'running' ? 'running' : 'pending',
-              progress: typeof a.progress === 'number' ? a.progress : prevTask?.progress ?? 0,
-              lines: Array.isArray(a.lines) ? (a.lines as string[]) : (prevTask?.lines ?? []),
-            })
-          }
-          return next
-        })
-        // 本地有、服务端已消失 → 已结束：逐个查终态收尾
-        // （cancelling 是客户端乐观过渡态，交给 cancelTask 的定时移除，不在轮询里提前收敛）
-        const gone = prevQueue.filter((q) => !byId.has(q.id) && q.status !== 'cancelling')
-        for (const q of gone) await settleTask(q)
+          applyQueue((prev) => {
+            const next: QueueTask[] = []
+            for (const a of active) {
+              const id = a.id as number
+              const prevTask = prev.find((q) => q.id === id)
+              const isRemove = a.action === 'remove'
+              next.push({
+                id,
+                kind: isRemove ? 'uninstall' : 'install',
+                target: typeof a.target === 'string' ? a.target.replace(/^github:/, '') : (prevTask?.target ?? ''),
+                desc: prevTask?.desc,
+                repo: prevTask?.repo ?? (isRemove ? null : (typeof a.target === 'string' ? a.target.replace(/^github:/, '') : null)),
+                // 安装时快照的目录信号：轮询合并时保留，任务成功后记录到本地
+                version: prevTask?.version,
+                updatedAt: prevTask?.updatedAt,
+                status: a.status === 'running' ? 'running' : 'pending',
+                progress: typeof a.progress === 'number' ? a.progress : prevTask?.progress ?? 0,
+                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),
+              })
+            }
+            // 保留乐观条目：服务端尚未登记（preflight 中），无真实 id，不能因 active 缺它就被合并吞掉
+            const keepOpt = prev.filter((q) => q.optimistic && !next.some((x) => x.id === q.id))
+            if (keepOpt.length > 0) next.push(...keepOpt)
+            // 保留「已从服务端消失、但尚未收尾」的任务：收尾（settleTask）负责移除。
+            // 若在这里提前摘除，卸载/安装完成的那一瞬队列会先变空，弹窗闪回「确认」态
+            // （busy=false 且未 done），表现为「卸载中 → 卸载 → 卸载完成」的中间回退。
+            const keepGone = prev.filter((q) =>
+              !byId.has(q.id) && !next.some((x) => x.id === q.id) && q.status !== 'cancelling' && !q.optimistic)
+            if (keepGone.length > 0) next.push(...keepGone)
+            return next
+          })
+          // 本地有、服务端已消失 → 已结束：逐个查终态收尾
+          // （cancelling 是客户端乐观过渡态，交给 cancelTask 的定时移除，不在轮询里提前收敛；
+          //   optimistic 是点击后尚未登记的占位，服务端 /status 查不到，跳过免误判成失败；
+          //   settling 是上一轮已开始收尾的任务，并发轮询直接跳过，避免重复收尾）
+          const gone = prevQueue.filter((q) =>
+            !byId.has(q.id) && q.status !== 'cancelling' && !q.optimistic && !settlingRef.current.has(q.id))
+        for (const q of gone) {
+          // 防御：同 id 任务可能已被上一轮收尾移除（极端时序下轮询合并出的重复条目），跳过避免重复收尾
+          if (!queueRef.current.some((x) => x.id === q.id)) continue
+          settlingRef.current.add(q.id)
+          try { await settleTask(q) } finally { settlingRef.current.delete(q.id) }
+        }
       } catch {
         // 服务端暂不可达：静默等待下一轮
       }
@@ -254,7 +331,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
         const res = await fetch('/dsh-plugin-hub/active', { cache: 'no-store' })
         if (!res.ok) return
         const data = await res.json() as {
-          tasks?: { id?: unknown; action?: unknown; target?: unknown; status?: unknown; progress?: unknown; lines?: unknown }[]
+          tasks?: { id?: unknown; action?: unknown; target?: unknown; status?: unknown; progress?: unknown; lines?: unknown; attempts?: unknown; needsRestart?: unknown }[]
           pendingRestarts?: unknown
         }
         if (cancelled) return
@@ -264,14 +341,21 @@ export function useTaskQueue(opts: TaskQueueOptions) {
           .filter((a) => typeof a.id === 'number')
           .map((a) => {
             const isRemove = a.action === 'remove'
+            // 服务端任务的 target：github:repo（git 安装）/ npm 包名（npm 安装/卸载）。
+            // 恢复展示统一用 displayTarget（owner/repo，服务端固定传）：npm 安装时 target 是包名，
+            // 直接展示会让用户看到「安装方式」的内部细节，违背无感知原则；卸载保持包名（匹配已装表）。
+            const display = typeof (a as { displayTarget?: unknown }).displayTarget === 'string' ? (a as { displayTarget: string }).displayTarget.replace(/^github:/, '') : ''
+            const fallback = typeof a.target === 'string' ? a.target.replace(/^github:/, '') : ''
             return {
               id: a.id as number,
               kind: (isRemove ? 'uninstall' : 'install') as 'install' | 'uninstall',
-              target: typeof a.target === 'string' ? a.target.replace(/^github:/, '') : '',
-              repo: isRemove ? null : (typeof a.target === 'string' ? a.target.replace(/^github:/, '') : null),
+              target: isRemove ? fallback : (display || fallback),
+              repo: isRemove ? null : (display || fallback),
               status: a.status === 'running' ? 'running' : 'pending',
               progress: typeof a.progress === 'number' ? a.progress : 0,
               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,
             }
           })
         if (items.length > 0 || pendingRef.current.length > 0) {
@@ -289,33 +373,59 @@ export function useTaskQueue(opts: TaskQueueOptions) {
   const installNow = async (p: HubPlugin, opts?: { update?: boolean }) => {
     const repo = p.source?.repo ?? ''
     if (!repo) return
+    // 安装通道决策（用户无感知）：有 npm 包名 → 走 npm；否则 git 直装。
+    // 队列条目一律用仓库名展示/防重，只有发给后端的实际安装目标随通道变化。
+    const { target } = installTargetOf(p)
+    if (!target) return
     // 防重复入队：同一目标已在排队/执行中则忽略
     if (queueRef.current.some((q) => q.kind === 'install' && q.target === repo)) return
     // 请求在途防重：任务要等响应回来才进本地队列，这之前再次点击（双击）直接忽略
     if (submittingRef.current.has(repo)) return
     submittingRef.current.add(repo)
+    // 乐观入队：点击安装立即显示「正在安装中」，不等 POST 响应。
+    // 服务端 /install 会先跑预检（preflight，可能耗时数秒）再入队，若等响应才入队列，
+    // 用户点完安装立刻去通知中心会看不到任务 —— 只有刷新后 restore 才拉回来。
+    // 用负临时 id 占位，响应回来换成真实 task id；失败/出错则移除该占位。
+    tempIdRef.current -= 1
+    const tempId = tempIdRef.current
+    modalTaskRef.current = tempId
+    applyQueue((prev) => [...prev, {
+      id: tempId, kind: 'install', target: repo, repo, desc: p.description,
+      version: p.version, updatedAt: p.dates?.repoUpdatedAt,
+      status: 'running', progress: 0, lines: [], optimistic: true,
+      command: installCommandOf(p, true),
+      // 服务端登记后 /active 会带回真实尝试记录（npm 反查 + 执行命令），先占位空列表
+      attempts: [], needsRestart: true,
+    }])
     setSubmitting(true)
     try {
       const res = await fetch('/dsh-plugin-hub/install', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ repo, mode: opts?.update ? 'update' : undefined }),
+        body: JSON.stringify({ repo: target, display: repo, mode: opts?.update ? 'update' : undefined }),
       })
-      const data = await res.json() as { ok?: boolean; task?: number; error?: string }
+      const data = await res.json() as { ok?: boolean; task?: number; error?: string; attempts?: string[] }
       if (!data.ok || typeof data.task !== 'number') {
-        // 请求层失败（重复安装 409 / 参数错误等）：完整错误弹窗
-        onError(data.error ?? `HTTP ${res.status}`, repo, 'install')
+        // 请求层失败（重复安装 409 / 参数错误等）：移除乐观条目 + 完整错误弹窗
+        applyQueue((prev) => prev.filter((x) => x.id !== tempId))
+        // 同步 400（如预检拦截）服务端会附上已尝试的安装方式，issue 预填一并展示
+        onError(data.error ?? `HTTP ${res.status}`, repo, 'install', installCommandOf(p, true), data.attempts)
         return
       }
       const taskId = data.task
       modalTaskRef.current = taskId
-      applyQueue((prev) => [...prev, { id: taskId, kind: 'install', target: repo, repo, desc: p.description, version: p.version, updatedAt: p.dates?.repoUpdatedAt, status: 'pending', progress: 0, lines: [] }])
+      // 用真实任务 id 替换乐观占位，解除 optimistic 标记（此后归正常收尾/轮询处理）
+      applyQueue((prev) => prev.map((x) => (x.id === tempId
+        ? { ...x, id: taskId, optimistic: undefined }
+        : x)))
       // 提前缓存展示信息：安装成功后服务端登记待重启，轮询合并时不用等目录解析
       pendingInfoRef.current.set(repo, { desc: p.description, version: p.version })
       // 摘要条常驻顶部（含实时进度），明细面板保持折叠，想看时再点开
       pollQueue()
     } catch {
-      onError(t('installFail'), repo, 'install')
+      // 网络异常：移除乐观条目 + 兜底错误弹窗
+      applyQueue((prev) => prev.filter((x) => x.id !== tempId))
+      onError(t('installFail'), repo, 'install', installCommandOf(p, true))
     } finally {
       submittingRef.current.delete(repo)
       setSubmitting(false)
@@ -345,7 +455,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       }
       const taskId = data.task
       modalTaskRef.current = taskId
-      applyQueue((prev) => [...prev, { id: taskId, kind: 'uninstall', target: name, desc: p.description, repo, status: 'pending', progress: 0, lines: [] }])
+      applyQueue((prev) => [...prev, { id: taskId, kind: 'uninstall', target: name, desc: p.description, repo, status: 'pending', progress: 0, lines: [], needsRestart: true }])
       // 摘要条常驻顶部（含实时进度），明细面板保持折叠，想看时再点开
       pollQueue()
     } catch {