dsh-plugin 1.0.0 → 1.1.0

package/src/client/components/modals.tsx

@@ -10,7 +10,7 @@ import styles from '../styles/Modal.module.css'
 import type { EnvInfo, HubPlugin, TaskState, ToastState, Translate } from '../types.ts'
 import { CloseIcon, CopyIcon, LinkIcon } from './icons.tsx'
 import { ProgressView } from './ProgressView.tsx'
-import { pluginDetailUrl, pluginIssueUrl, pluginSiteUrl } from '../lib/catalog.ts'
+import { installCommandOf, pluginDetailUrl, pluginIssueUrl, pluginSiteUrl } from '../lib/catalog.ts'
 import { classifyFailure } from '../lib/failures.ts'
 
 /** 完成结果视图：绿色对勾 + 标题/描述 + 「稍后重启 / 立即重启」按钮对（部分插件需重启后才会挂载） */
@@ -42,7 +42,7 @@ function ResultView({
       })),
     ),
     h('div', { className: styles.resultTitle }, title),
-    h('div', { className: styles.resultDesc }, desc),
+    desc ? h('div', { className: styles.resultDesc }, desc) : null,
     h('div', { className: styles.resultRestarting }, restarting ? t('restarting') : t('restartHint')),
     h('div', { className: styles.modalActions },
       h('button', { className: styles.restartLater, onClick: onClose, disabled: restarting }, t('restartLater')),
@@ -142,7 +142,7 @@ export function InstallModal(props: InstallModalProps) {
             role: 'button',
             tabIndex: 0,
           },
-            h('span', { className: styles.modalCmdText }, `dsh plugin add github:${plugin.source?.repo ?? ''}`),
+            h('span', { className: styles.modalCmdText }, installCommandOf(plugin)),
             h('span', { className: styles.modalCmdCopy }, h(CopyIcon), t('copyCmdLabel')),
           ),
           task && task.status === 'pending' ? h('div', { className: styles.queuedHint }, t('queuedHint')) : null,
@@ -270,16 +270,19 @@ export function UninstallModal(props: UninstallModalProps) {
 
 /** 预填插件仓库的 GitHub Issue 链接：标题带插件名，正文附完整错误信息，方便用户一键反馈。 */
 /** 安装/卸载失败弹窗：布局与失败记录一致（类型徽标 + 仓库超链接 + 隐蔽复制按钮），报错完整展示，底部一键提交 Issue。 */
-export function ErrorModal({ message, repo, kind, t, env, onCopy, onClose }: {
+export function ErrorModal({ message, repo, kind, command, attempts, t, env, onCopy, onClose }: {
   message: string
   repo: string | null
   kind: 'install' | 'uninstall'
+  command?: string
+  /** 尝试过的安装方式（npm 反查 + 实际执行命令）：issue 预填一并贴给作者，便于反推正确的 npm 包名 */
+  attempts?: string[]
   t: Translate
   env: EnvInfo | null
   onCopy: (text: string) => void
   onClose: () => void
 }) {
-  // 失败归类：用官方默认安装方式装不上 = 插件仓库的问题，一律引导提 Issue
+  // 失败归类：当前安装通道（npm/git）装不上 = 插件分发/依赖的问题，一律引导提 Issue
   const failureKind = classifyFailure(message)
   return h('div', {
     className: styles.overlay,
@@ -320,14 +323,14 @@ export function ErrorModal({ message, repo, kind, t, env, onCopy, onClose }: {
           // 插件问题（prepare 构建失败 / 原生依赖构建被拦截 / git 分发缺产物）：都是插件打包分发问题 —— 先说明原因，按钮在下方引导提 Issue
           failureKind === 'pluginPrepare' || failureKind === 'pnpmIgnoredBuild'
             ? h('div', null, [
-              // [packaging]（预检/装后校验拦截：git 分发缺产物，不支持官方默认安装方式）与
+              // [packaging]（预检/装后校验拦截：git 分发缺产物）与
               // prepare 构建脚本实际执行失败 / 原生依赖构建被 pnpm 拦截：都是插件打包分发问题 —— 先说明原因，按钮在下方提交
               h('div', { className: styles.failPrepareHint }, failureKind === 'pnpmIgnoredBuild'
                 ? t('failIgnoredBuild')
                 : /\[packaging\]/i.test(message) ? t('failPackagingHint') : t('failPrepareHint')),
               repo ? h('a', {
                 className: styles.failBigIssue,
-                href: pluginIssueUrl(repo, message, env),
+                href: pluginIssueUrl(repo, message, env, command, attempts),
                 target: '_blank',
                 rel: 'noopener noreferrer',
                 title: t('failIssueHint'),
@@ -335,7 +338,7 @@ export function ErrorModal({ message, repo, kind, t, env, onCopy, onClose }: {
             ])
             : repo ? h('a', {
               className: styles.failBigIssue,
-              href: pluginIssueUrl(repo, message, env),
+              href: pluginIssueUrl(repo, message, env, command, attempts),
               target: '_blank',
               rel: 'noopener noreferrer',
               title: t('failIssueHint'),

package/src/client/hooks/useCatalog.ts

@@ -27,8 +27,9 @@ 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 }>>({})
 
   // 拉取目录 + 统计。在线 API 已只返回 verified；再过滤一次，保证只展示人工验证通过的插件。
   useEffect(() => {
@@ -64,7 +65,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 +76,7 @@ export function useCatalog(lang: LocaleId) {
   // 首次进入拉取已安装表（依赖宿主 webServer 服务）
   useEffect(() => { refreshInstalled() }, [])
 
-  /** 插件是否已安装：匹配 installed spec 中的 `github:<owner>/<repo>`；命中返回 npm 包名。 */
+  /** 插件是否已安装：匹配 installed spec 中的 `github:<owner>/<repo>`，或 npm 通道安装的依赖包名；命中返回 npm 包名。 */
   const installedName = (p: HubPlugin): string | null => {
     const repo = p.source?.repo
     if (!repo) return null
@@ -83,6 +84,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
   }
 

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,13 @@ 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[]
 }
 
 /** 客户端待重启项：镜像服务端内存列表 + 本地补齐的展示信息（简介/版本）。 */
@@ -44,8 +52,8 @@ export interface TaskQueueOptions {
   /** 任务成功完成：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
+  /** 任务失败：完整输出或兜底文案 + 所属插件仓库 + 操作类型（安装/卸载）+ 实际执行的安装命令（issue 预填用，可缺省）+ 尝试过的安装方式（npm 反查/执行命令，可缺省）。 */
+  onError: (message: string, repo: string | null, kind: 'install' | 'uninstall', command?: string, attempts?: string[]) => void
   /** 当前打开的安装/卸载弹窗插件：用于在弹窗内匹配进行中的任务。 */
   installPlugin: HubPlugin | null
   uninstallPlugin: HubPlugin | null
@@ -71,11 +79,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)
 
@@ -169,25 +181,60 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       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[] } }
+        const data = await res.json() as { task?: { status?: string; lines?: string[]; attempts?: string[] } }
         status = data.task?.status ?? 'failed'
         lines = data.task?.lines ?? []
+        attempts = Array.isArray(data.task?.attempts) ? data.task.attempts : undefined
       }
     } catch { /* 服务端不可达：按失败处理 */ }
-    if (status === 'done') finishQueueTask(true, q, lines)
-    else if (status === 'failed') finishQueueTask(false, q, lines)
+    if (status === 'done') {
+      // 卸载成功走进度过渡动画；安装成功直接收尾
+      if (q.kind === 'uninstall') settleDone(q, lines)
+      else finishQueueTask(true, q, lines)
+    }
+    else if (status === 'failed') {
+      // 服务端终态带出的尝试记录覆盖本地：以实际执行为准
+      finishQueueTask(false, { ...q, attempts }, lines)
+    }
     else {
       applyQueue((prev) => prev.filter((x) => x.id !== q.id)) // cancelled / 未知
       maybeStopPoll()
@@ -203,7 +250,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 }[]
           pendingRestarts?: unknown
         }
         const active = (data.tasks ?? []).filter((a) => typeof a.id === 'number')
@@ -213,32 +260,50 @@ 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 ?? []),
+              })
+            }
+            // 保留乐观条目：服务端尚未登记（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 +319,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 }[]
           pendingRestarts?: unknown
         }
         if (cancelled) return
@@ -264,14 +329,20 @@ 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) : [],
             }
           })
         if (items.length > 0 || pendingRef.current.length > 0) {
@@ -289,33 +360,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: [],
+    }])
     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)

package/src/client/lib/catalog.ts

@@ -46,19 +46,21 @@ export function pluginSiteUrl(repo: string): string {
 
 /**
  * 一键反馈 GitHub Issue 的预填链接：标题带「来自 dsh-plugin.org」标识，正文只带
- * 核心信息 —— 原因判定 + 关键错误代码 + 宿主机器环境快照 + 错误核心摘要（完整日志
- * 太长，塞进 URL 会被 GitHub 以「request URL too long」拒绝，故只收集重点）。
- * 错误弹窗、失败记录共用此逻辑。
+ * 核心信息 —— 原因判定 + 关键错误代码 + 尝试过的安装方式 + 宿主机器环境快照 +
+ * 错误核心摘要（完整日志太长，塞进 URL 会被 GitHub 以「request URL too long」拒绝，
+ * 故只收集重点）。错误弹窗、失败记录共用此逻辑。
  * env 取不到时为 null，链接照常生成、只是少环境段。
+ * attempts（尝试过的安装方式，npm 反查 + 实际执行命令）：作者看到我们查过/试过的命令，
+ * 组织 scope 与 GitHub 用户名不一致时也能直接指认正确的 npm 包名。
  */
-export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | null): string {
+export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | null, command?: string, attempts?: string[]): string {
   const title = `[dsh-plugin.org | dsh-plugin-hub] Install/Remove failed: ${repo}`
   // 原因判定：让作者一眼知道这是不是自己插件的问题。
-  // [packaging]（预检/装后校验拦截）单独列：点明「不支持官方默认安装方式」，并写清官方默认方式
-  // 是什么（git 直装要求仓库提交构建产物或提供 prepare 脚本），作者照此适配即可。
+  // [packaging]（预检/装后校验拦截）单独列：无论走 npm 还是 git 通道，都是分发物不完整
+  // （package.json 声明的入口文件在发布物里缺失），作者照此补齐即可。
   const kind = classifyFailure(message)
   const reason = /\[packaging\]/i.test(message)
-    ? 'plugin does NOT support the official default install method (dsh plugin add github:owner/repo — requires build output committed to the repo or a prepare script); its git distribution lacks the entry file declared in package.json'
+    ? 'plugin distribution is incomplete — the entry file declared in package.json is missing from the published package (github tarball or npm package); please commit build output or publish a complete package'
       : kind === 'pluginPrepare'
         ? 'plugin prepare/build script failed during install (packaging/distribution issue)'
         : kind === 'pnpmIgnoredBuild'
@@ -72,17 +74,23 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
       `- Cause: ${reason}`,
       ...(code ? [`- Key error: \`${code}\``] : []),
       '',
-      // 来源说明：标题（链官网）+ 一句来源（链仓库）+ 实际执行的官方安装命令（含 --profile）与执行结果，链接由常量动态拼接
+      // 来源说明：标题（链官网）+ 一句来源（链仓库）+ 实际执行的安装命令（含 --profile）与执行结果，链接由常量动态拼接
       `## [DSH-Plugin 插件中心](${SITE_URL}) · 安装 Plugin 失败错误信息`,
       `本错误信息由 [dsh-plugin-hub](${GITHUB_URL}) 插件中心的安装程序自动生成，随本次安装失败一并提交。`,
-      `- 使用的安装命令（官方默认安装方式）：\`dsh plugin${env?.profile ? ` --profile ${env.profile}` : ''} add github:${repo}\``,
+      `- 实际执行的安装命令：\`${command ?? `dsh plugin${env?.profile ? ` --profile ${env.profile}` : ''} add github:${repo}`}\``,
       `- 执行结果：安装失败，未能安装该插件。`,
-      // [packaging] 场景：向作者说明官方默认安装方式具体是什么，请其按该方式适配（提交构建产物或提供 prepare 脚本）
+      // 尝试过的安装方式（npm 反查 + 实际执行命令，按先后顺序）：作者据此反推正确的
+      // npm 包名 —— 组织 scope 与 GitHub 用户名不一致时仅凭仓库名猜不到，作者看到我们
+      // 查过/试过的命令就能直接指认
+      ...(attempts && attempts.length > 0
+        ? ['', '## Attempted install channels（已尝试的安装方式）', ...attempts.map((a) => `- ${a}`)]
+        : []),
+      // [packaging] 场景：说明两种官方安装通道（npm 包 / git 直装），当前插件在对应通道下分发不完整
       ...(/\[packaging\]/i.test(message)
         ? [
           '',
-          '## 官方默认安装方式',
-          'DSH 生态的官方默认安装方式是 `dsh plugin add github:owner/repo`（git 直装）：插件仓库需提交构建产物，或在 package.json 提供 `prepare` 脚本让 pnpm 安装时自动构建。当前插件两者皆不具备，因此无法按官方方式安装。',
+          '## 安装方式说明',
+          'DSH 插件支持两种官方安装通道：`dsh plugin add <npm-package>`（npm 分发，需发布完整构建产物）与 `dsh plugin add github:owner/repo`（git 直装，仓库需提交构建产物或在 package.json 提供 `prepare` 脚本）。当前插件的分发物缺少 package.json 声明的入口文件，请按所用通道补齐后重新发布。',
         ]
         : []),
       '',
@@ -156,7 +164,15 @@ export function normalize(raw: Record<string, unknown>): HubPlugin {
       topics: Array.isArray(raw.t) ? (raw.t as string[]) : undefined,
       features: Array.isArray(raw.f) ? (raw.f as string[]) : undefined,
       description: typeof raw.d === 'string' ? raw.d : undefined,
-      source: typeof raw.r === 'string' ? { repo: raw.r } : undefined,
+      // 投影输出两种形态：老数据 source 是 repo 字符串；新数据是 { repo, npmPackage }
+      source: typeof raw.r === 'string'
+        ? { repo: raw.r }
+        : raw.r !== null && typeof raw.r === 'object'
+          ? {
+            repo: typeof (raw.r as { repo?: unknown }).repo === 'string' ? (raw.r as { repo: string }).repo : undefined,
+            npmPackage: typeof (raw.r as { npmPackage?: unknown }).npmPackage === 'string' ? (raw.r as { npmPackage: string }).npmPackage : undefined,
+          }
+          : undefined,
       compatibility: typeof raw.v === 'string' ? { status: raw.v } : undefined,
       dates: {
         repoUpdatedAt: typeof raw.u === 'string' ? raw.u : undefined,
@@ -171,6 +187,26 @@ export function normalize(raw: Record<string, unknown>): HubPlugin {
   return raw as unknown as HubPlugin
 }
 
+/**
+ * 安装通道决策（用户无感知）：目录探测到 npm 包名 → 用 npm 包名安装
+ * （走 npm registry tarball，更快、与 GitHub 网络无关）；无 npm 包名 → git 直装。
+ * 返回值 target 即传给后端 /install 的安装目标（npm 包名 或 owner/repo）。
+ */
+export function installTargetOf(p: HubPlugin): { target: string; via: 'npm' | 'github' } {
+  const pkg = (p.source?.npmPackage ?? '').trim()
+  const repo = (p.source?.repo ?? '').trim()
+  if (pkg && repo) return { target: pkg, via: 'npm' }
+  return { target: repo, via: 'github' }
+}
+
+/** 展示用安装命令（复制/弹窗）：npm 通道显示包名，git 通道显示 github: 源。 */
+export function installCommandOf(p: HubPlugin, withProfile = false): string {
+  const { target, via } = installTargetOf(p)
+  return via === 'npm'
+    ? `dsh plugin${withProfile ? ' --profile web' : ''} add ${target}`
+    : `dsh plugin${withProfile ? ' --profile web' : ''} add github:${target}`
+}
+
 export const CATEGORY_LABELS: Record<string, { zh: string; en: string }> = {
   interface: { zh: '界面与体验', en: 'UI & Experience' },
   session: { zh: '会话与消息', en: 'Sessions & Messages' },

package/src/client/lib/failures.ts

@@ -16,6 +16,10 @@ export interface NotificationRecord {
   repo: string
   /** 失败时的完整错误日志；成功记录为空串 */
   message: string
+  /** 实际执行的安装/卸载命令（issue 预填时如实展示）；历史记录可能缺失 */
+  command?: string
+  /** 尝试过的安装方式（npm registry 反查 + 实际执行命令，按先后顺序）：失败提 Issue 时贴给作者，便于反推正确的 npm 包名 */
+  attempts?: string[]
   /** 结束时间（epoch ms） */
   at: number
 }
@@ -27,7 +31,8 @@ export type FailureKind = 'pnpmIgnoredBuild' | 'pluginPrepare' | 'repo'
 
 /**
  * 失败归类，三态。无论底层机制如何（pnpm 白名单拦截 / 构建脚本被忽略 / prepare 失败），
- * 对用户而言结果都一样 —— 用官方默认安装方式装不上，就是插件仓库的问题，一律引导提 Issue：
+ * 对用户而言结果都一样 —— 当前安装通道（npm 或 git）装不上，就是插件分发/依赖的问题，
+ * 一律引导提 Issue：
  * - pnpmIgnoredBuild：插件依赖里的原生模块构建脚本被 pnpm 默认拦截（如 node-pty，
  *   `ERR_PNPM_IGNORED_BUILDS`）。只影响带原生模块的插件，其他插件不受影响 —— 差异在
  *   插件的依赖选择，属插件依赖/打包问题 → 引导去仓库提 Issue（建议改用预编译版本）
@@ -44,7 +49,7 @@ export function classifyFailure(message: string): FailureKind {
   if (/ERR_PNPM_IGNORED_BUILDS|Ignored build scripts:/i.test(message)) return 'pnpmIgnoredBuild'
   // 再判 prepare 实际执行失败：只有构建脚本真的跑挂了才是插件问题
   if (/ERR_PNPM_PREPARE_PACKAGE|ELIFECYCLE|Command failed|prepare-guard/i.test(message)) return 'pluginPrepare'
-  // 其余失败（含 git prepare 被 pnpm 白名单拦截）：官方方式装不上 = 插件仓库的问题，一律提 Issue
+  // 其余失败（含 git prepare 被 pnpm 白名单拦截）：当前通道装不上 = 插件分发/依赖的问题，一律提 Issue
   return 'repo'
 }
 
@@ -151,3 +156,10 @@ export function clearNotifications(): NotificationRecord[] {
   save([])
   return []
 }
+
+/** 按 id 删除单条通知记录，返回更新后的列表（仅移除该条，不影响其余记录）。 */
+export function removeNotification(id: number): NotificationRecord[] {
+  const next = loadNotifications().filter((r) => r.id !== id)
+  save(next)
+  return next
+}

package/src/client/locales.ts

@@ -48,8 +48,8 @@ export const zh = {
   installNow: '直接安装',
   installing: '安装中…',
   installDone: '安装成功',
-  installResultTitle: '安装完成',
-  installResultDesc: '插件已安装。',
+  installResultTitle: '插件安装成功',
+  installResultDesc: '',
   // 更新语义：已安装插件点「更新」走同一条 add 命令原位覆盖重装，弹窗文案区分安装/更新
   confirmUpdateTitle: '确认更新',
   updateNow: '直接更新',
@@ -91,6 +91,7 @@ export const zh = {
   notificationsDesc: '安装、卸载任务的成败都会记录在这里，即使错过提示也能随时回来查看。',
   notificationsEmpty: '暂无通知记录',
   notificationsClear: '清空通知',
+  removeNotification: '删除这条通知',
   failCopy: '复制完整错误信息',
   failIssueHint: '带着错误日志去作者仓库一键提交 Issue（正文含官网收录链接）',
   failIssueBig: '一键提交 BUG 到 GitHub Issue 为开源作贡献',
@@ -172,8 +173,8 @@ export const en = {
   installNow: 'Install',
   installing: 'Installing…',
   installDone: 'Installed',
-  installResultTitle: 'Installed',
-  installResultDesc: 'The plugin has been installed.',
+  installResultTitle: 'Plugin installed successfully',
+  installResultDesc: '',
   // Update semantics: the "update" action re-runs add in place — copy differentiates install vs update
   confirmUpdateTitle: 'Confirm update',
   updateNow: 'Update',
@@ -213,6 +214,7 @@ export const en = {
   notificationsDesc: 'Every install and remove result is logged here — even if you missed the prompt, you can always check back.',
   notificationsEmpty: 'No notifications yet',
   notificationsClear: 'Clear notifications',
+  removeNotification: 'Remove this notification',
   failCopy: 'Copy full log',
   failIssueHint: 'Open a pre-filled issue on the author repo with this error log (includes catalog links)',
   failIssueBig: 'Report this bug to GitHub — contribute to open source',

package/src/client/styles/List.module.css

@@ -184,7 +184,7 @@
   user-select: none;
 }
 
-/* 可更新：琥珀警示色实底按钮（与 star / 有更新徽标同族），点击直接覆盖安装更新 */
+/* 可更新：琥珀警示色实底按钮（与 star / 有更新徽标同族，与安装绿、卸载红区分），点击直接覆盖安装更新 */
 .installBtnUpdate {
   color: #fff;
   background: var(--hub-warn);
@@ -197,17 +197,17 @@
   background: var(--hub-warn-strong);
 }
 
-/* 卸载：危险色文字按钮，默认无底，悬浮转鲜红实底白字 */
+/* 卸载：危险色按钮 —— 默认浅红底红字（危险但克制），悬浮转深红实底白字 */
 .uninstallBtn {
   color: var(--hub-danger);
-  background: transparent;
+  background: var(--hub-danger-tint);
   border: none;
   user-select: none;
 }
 
 .uninstallBtn:hover {
   color: #ffffff;
-  background: var(--hub-danger);
+  background: var(--hub-danger-hover);
 }
 
 .installBtn {