dsh-plugin 1.6.1 → 1.6.3

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

@@ -5,8 +5,9 @@
  *
  * Dialog layer for the Plugin Hub: the install-confirm dialog, the uninstall
  * dialog and the global toast. Both dialogs lock themselves while a mutation
- * or restart is running, then switch to a result view offering an immediate
- * restart or a "later" deferral.
+ * is running, then switch to a result view with a single action — "done" for
+ * the common case (the page refreshes on close so the change applies), or a
+ * single "restart now" for the rare changes a refresh cannot pick up.
  */
 import { createElement as h } from 'react'
 import type { MouseEvent } from 'react'
@@ -19,17 +20,21 @@ import { pluginDetailUrl, pluginIssueUrl, pluginSiteUrl } from '../../logic/urls
 import { classifyFailure, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
 
 /** 完成结果视图：绿色对勾 + 标题/描述；
- *  needsRestart=true（插件需重启才生效）→ 「稍后重启 / 立即重启」按钮对，点稍后重启后
- *  通知中心待重启条目常驻（服务端登记，内存态），直到用户点「立即重启」真正重启后才消失；
- *  needsRestart=false（卸载已即时生效）→ 仅「完成」关闭。 */
+ *  终态只有两种：
+ *  - needsRestart=true（刷新解决不了：热挂载失败 / 非 dsh 插件 / 更新）→ 仅一个「立即重启」
+ *    按钮（重启会中断进行中的任务，故仍需用户确认），关闭即放弃；
+ *  - 其余（含 needsReload=true 的「已热挂载、仅剩客户端 UI」）→ 仅「完成」按钮：关闭结果弹窗时
+ *    上层自动刷新页面让插件生效，不再给「稍后/立即刷新」手动选择。 */
 function ResultView({
-  title, desc, t, restarting, needsRestart, onRestart, onClose,
+  title, desc, t, restarting, needsRestart, needsReload, onRestart, onClose,
 }: {
   title: string
   desc: string
   t: Translate
   restarting: boolean
   needsRestart: boolean
+  /** 仅刷新页面即生效（插件已热挂载）：给一句自动刷新说明，按钮仍是「完成」 */
+  needsReload?: boolean
   onRestart: () => void
   onClose: () => void
 }) {
@@ -56,13 +61,15 @@ function ResultView({
       ? h('div', 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')),
           h('button', { className: styles.restartNowWarning, onClick: onRestart, disabled: restarting },
             restarting ? t('restarting') : t('restartNow')),
         ),
       ])
-      : h('div', { className: styles.modalActions },
-        h('button', { className: styles.restartNow, onClick: onClose }, t('done'))),
+      : h('div', null, [
+        needsReload ? h('div', { className: styles.resultRestarting }, t('reloadHint')) : null,
+        h('div', { className: styles.modalActions },
+          h('button', { className: styles.restartNow, onClick: onClose }, t('done'))),
+      ]),
   )
 }
 
@@ -85,8 +92,10 @@ export interface InstallModalProps {
   cliOnly: boolean
   /** 安装请求在途（fetch 等待响应）：此时任务尚未入队，需禁用确认按钮防止二次点击 */
   submitting: boolean
-  /** 完成结果是否需重启才生效：true → 「稍后重启 / 立即重启」；false → 仅「完成」 */
+  /** 完成结果是否需重启才生效：true → 仅给「立即重启」；false → 仅「完成」（关闭即自动刷新） */
   needsRestart: boolean
+  /** 完成结果是否只需刷新页面即生效（插件已热挂载）：true → 结果视图显示自动刷新说明 */
+  needsReload: boolean
   onClose: () => void
   onCopy: () => void
   onInstall: () => void
@@ -99,7 +108,7 @@ export interface InstallModalProps {
  * 目录插件与命令行安装（customTarget 模式）共用同一套确认/进度/结果流程。
  */
 export function InstallModal(props: InstallModalProps) {
-  const { plugin, customTarget, globalNpm, done, task, t, langPath, restarting, submitting, update, cliOnly, needsRestart, onClose, onCopy, onInstall, onRestart } = props
+  const { plugin, customTarget, globalNpm, done, task, t, langPath, restarting, submitting, update, cliOnly, needsRestart, needsReload, onClose, onCopy, onInstall, onRestart } = props
   const busy = submitting || (task !== null && (task.status === 'pending' || task.status === 'running'))
   // 进行中标题带上插件名（中文「XX 插件安装中」；英文状态词在前更自然），并用状态色区分；
   // 命令行安装无插件元数据 → 直接用输入的目标展示；全局 npm 安装 → 包列表空格拼接
@@ -139,6 +148,7 @@ export function InstallModal(props: InstallModalProps) {
           t,
           restarting,
           needsRestart,
+          needsReload,
           onRestart,
           onClose,
         })
@@ -219,8 +229,11 @@ export interface UninstallModalProps {
   restarting: boolean
   /** 卸载请求在途（fetch 等待响应）：此时任务尚未入队，需禁用确认按钮防止二次点击 */
   submitting: boolean
-  /** 完成结果是否需重启才生效：true → 「稍后重启 / 立即重启」；false（loader 已即时移除）→ 仅「完成」 */
+  /** 完成结果是否需重启才生效：true（停用失败等刷新解决不了的场景）→ 仅给「立即重启」；
+   *  false（loader 已即时停用）→ 仅「完成」，关闭即自动刷新页面摘除插件面板 */
   needsRestart: boolean
+  /** 卸载的插件带客户端 UI 且已即时停用：面板要刷新页面才摘除 → 结果视图给自动刷新说明 */
+  needsReload?: boolean
   onClose: () => void
   onCancel: () => void
   onCopyCommand: () => void
@@ -230,7 +243,7 @@ export interface UninstallModalProps {
 
 /** 卸载确认弹窗：确认/进行中（后台队列，可关闭）；完成后切换为结果视图（成功即生效，仅「完成」关闭）。 */
 export function UninstallModal(props: UninstallModalProps) {
-  const { plugin, done, task, t, langPath, restarting, submitting, needsRestart, onClose, onCancel, onCopyCommand, onConfirm, onRestart } = props
+  const { plugin, done, task, t, langPath, restarting, submitting, needsRestart, needsReload, onClose, onCancel, onCopyCommand, onConfirm, onRestart } = props
   const busy = submitting || (task !== null && (task.status === 'pending' || task.status === 'running'))
   // 进行中标题带上插件名，与安装弹窗一致，并用状态色区分
   const name = plugin.displayName ?? plugin.slug
@@ -266,6 +279,7 @@ export function UninstallModal(props: UninstallModalProps) {
           t,
           restarting,
           needsRestart,
+          needsReload,
           onRestart,
           onClose,
         })
@@ -503,8 +517,11 @@ export function Toast({ toast, t }: { toast: ToastState; t: Translate }) {
         : toast.kind === 'fail' ? t('installFail')
           : toast.kind === 'removed' ? t('uninstallDone')
             : toast.kind === 'revealFail' ? t('openFolderFail')
-              : t('uninstallFail')
-  const fail = toast.kind === 'fail' || toast.kind === 'removeFail' || toast.kind === 'revealFail'
+              : toast.kind === 'restartDesktop' ? t('toastRestartDesktop')
+                : toast.kind === 'installedLive' ? t('toastInstalledLive')
+                  : toast.kind === 'installedReload' ? t('toastInstalledReload')
+                    : t('uninstallFail')
+  const fail = toast.kind === 'fail' || toast.kind === 'removeFail' || toast.kind === 'revealFail' || toast.kind === 'restartDesktop'
   return h('div', {
     key: toast.id,
     className: fail ? `${styles.toast} ${styles.toastFail}` : styles.toast,
@@ -512,7 +529,7 @@ export function Toast({ toast, t }: { toast: ToastState; t: Translate }) {
 }
 
 /** 待重启确认弹窗：已安装列表行内「重启」按钮点击后弹出，
- *  与通知中心待重启条目同一交互（说明 + 稍后重启 / 立即重启），
+ *  与通知中心待重启条目同一交互（红色警告说明 + 单个「立即重启」），
  *  避免行内按钮误触直接触发宿主重启。 */
 export function RestartConfirmModal({ t, restarting, onClose, onRestartNow }: {
   t: Translate
@@ -541,12 +558,7 @@ export function RestartConfirmModal({ t, restarting, onClose, onRestartNow }: {
         ),
         h('div', { className: styles.failPrepareHint }, t('restartHint')),
         h('div', { className: styles.modalActions },
-          h('button', {
-            className: styles.restartLater,
-            type: 'button',
-            disabled: restarting,
-            onClick: onClose,
-          }, t('restartLater')),
+          // 关闭本弹窗即视为「稍后」，只保留单个「立即重启」
           h('button', {
             className: styles.restartNowWarning,
             type: 'button',

package/src/client/hooks/useTaskQueue.ts

@@ -48,10 +48,13 @@ export interface QueueTask {
   command?: string
   /** 尝试过的安装方式（npm registry 反查 + 实际执行命令，按先后顺序）：失败时 issue 预填一并贴给作者 */
   attempts?: string[]
-  /** 完成结果是否需要重启才生效（服务端任务终态带出；默认 true 保持老行为：弹窗给重启选项）。
-   *  卸载时 loader 已即时移除 → false，结果视图只显示「完成」；true 时弹窗给「稍后重启/立即重启」，
-   *  通知中心待重启条目（服务端登记）同步常驻，直到用户点「立即重启」。 */
+  /** 完成结果是否需要重启才生效（服务端任务终态带出）。默认 true 保底：数据缺失时不静默视为已生效。
+   *  仅刷新解决不了的兜底场景（热挂载失败 / 非 dsh 插件 / 更新）为 true，结果视图给「立即重启」；
+   *  其余（热挂载成功、卸载已即时停用、全局安装）为 false，结果视图仅「完成」。 */
   needsRestart: boolean
+  /** 完成结果是否只需刷新页面即生效（插件已热挂进运行中 loader，或卸载后插件面板仍残留在当前页面）：
+   *  true 时关闭结果弹窗 / Toast 消失后由上层自动刷新页面，不给手动刷新按钮。 */
+  needsReload?: boolean
 }
 
 /** 客户端待重启项：镜像服务端内存列表 + 本地补齐的展示信息（简介/版本）。 */
@@ -71,10 +74,11 @@ export interface TaskQueueOptions {
   langKey?: LocaleId
   refreshInstalled: () => void
   /** 任务成功完成：viaModal 表示任务对应当前打开弹窗（弹窗切结果视图），否则走 Toast；repo 供成功通知记录；
-   *  needsRestart 表示该任务完成后是否仍需宿主重启（结果视图据此给「重启 / 仅完成」）。
+   *  needsRestart 表示该任务完成后是否仍需宿主重启（结果视图据此给「重启 / 仅完成」）；
+   *  needsReload 表示是否只需刷新页面即生效（热挂载成功、或卸载后插件面板仍残留）。
    *  update 表示实际执行的是更新（覆盖重装）而非首次安装：通知中心据此显示「更新成功」而非「安装成功」。 */
-  onInstallDone: (viaModal: boolean, repo: string | null, needsRestart: boolean, update?: boolean) => void
-  onUninstallDone: (viaModal: boolean, repo: string | null, needsRestart: boolean) => void
+  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 反查/执行命令，可缺省）+ 是否更新。 */
   onError: (message: string, repo: string | null, kind: 'install' | 'uninstall', command?: string, attempts?: string[], update?: boolean) => void
   /** 当前打开的安装/卸载弹窗插件：用于在弹窗内匹配进行中的任务。 */
@@ -207,13 +211,13 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       if (q.kind === 'uninstall') {
         // 卸载成功：清掉本地版本记录
         void syncInstalledVersion(q.repo, undefined, undefined)
-        onUninstallDone(modalTaskRef.current === q.id, q.repo, q.needsRestart)
+        onUninstallDone(modalTaskRef.current === q.id, q.repo, q.needsRestart, q.needsReload ?? false)
       } 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, q.needsRestart, q.action === 'update')
+        onInstallDone(modalTaskRef.current === q.id, q.repo, q.needsRestart, q.action === 'update', q.needsReload ?? false)
       }
     } else {
       // 失败：完整展示全部输出行（最新在前，逆序为日志阅读顺序），不裁剪
@@ -261,16 +265,17 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     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[]; attempts?: string[]; needsRestart?: unknown } }
+        const data = await res.json() as { task?: { status?: string; lines?: string[]; attempts?: string[]; needsRestart?: unknown; needsReload?: 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 即时移除情况设置）
+          // 终态带出的「是否需要重启 / 是否只需刷新」覆盖本地（服务端 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') {
-            const settled = { ...q, needsRestart }
+            const settled = { ...q, needsRestart, needsReload }
             // 卸载成功走进度过渡动画；安装成功直接收尾
             if (q.kind === 'uninstall') settleDone(settled, lines)
             else finishQueueTask(true, settled, lines)

package/src/client/locales.ts

@@ -263,11 +263,17 @@ export const zh = {
   requestTimeout: '请求超时：无法访问 GitHub 或网络不稳定，请稍后重试',
   confirmCancel: '取消',
   doneBtn: '完成',
-  // 结果视图：部分插件需重启后才挂载，提供「立即重启 / 稍后重启」选择
+  // 结果视图兜底：仅当「刷新解决不了」时（热挂载失败 / 非 dsh 插件 / 更新）才出现单个「立即重启」；
+  // 关闭弹窗即视为「稍后」，不再单独给「稍后重启」按钮
   restartNow: '立即重启',
-  restartLater: '稍后重启',
   restarting: '正在重启…',
   restartHint: '重启会中断正在进行的安装/卸载任务，其进度将丢失。部分插件（如插件市场、顶层 bundle）需重启后才会生效。',
+  // 桌面端宿主归应用壳管、插件重启不了它：点「立即重启」时改提示用户退出重开
+  toastRestartDesktop: '桌面端的宿主由应用管理，请在应用菜单（或托盘）选择退出后重新打开，重启后生效',
+  // 装完即生效：插件已热挂进运行中 loader，结果弹窗关闭时自动刷新页面（无需用户点按钮）
+  reloadHint: '插件已加载，关闭本窗口后会自动刷新页面生效。',
+  toastInstalledLive: '安装成功，已立即生效',
+  toastInstalledReload: '安装成功，正在自动刷新页面…',
   done: '完成',
   // 待重启：装完没重启的插件常驻提醒，直到宿主真正重启
   restartPendingHint: '安装成功，重启后生效',
@@ -645,11 +651,18 @@ export const en = {
   requestTimeout: 'Request timed out: GitHub may be unreachable or the network is unstable — try again later',
   confirmCancel: 'Cancel',
   doneBtn: 'Done',
-  // Result view: some plugins need a restart to mount — offer restart now / later
+  // Result-view fallback: the single "Restart now" only appears when a refresh cannot help
+  // (hot-mount failure / non-dsh plugin / update); closing the modal means "later"
   restartNow: 'Restart now',
-  restartLater: 'Later',
   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.',
+  // Desktop: the app shell owns the host, so plugins cannot restart it — tell the user to quit and reopen
+  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',
+  // Applied without a restart: the install was hot-mounted into the running loader;
+  // the page auto-refreshes on close (no manual refresh button)
+  reloadHint: 'The plugin is loaded — closing this window will refresh the page automatically.',
+  toastInstalledLive: 'Installed — active now',
+  toastInstalledReload: 'Installed — refreshing the page automatically…',
   done: 'Done',
   restartPendingHint: 'Installed — takes effect after restart',
   restartPendingHintUninstall: 'Removed — cleaned up after restart',

package/src/client/types.ts

@@ -77,7 +77,7 @@ export interface TaskState {
   lines: string[]
 }
 
-export type ToastKind = 'copied' | 'errCopied' | 'done' | 'fail' | 'removed' | 'removeFail' | 'revealFail'
+export type ToastKind = 'copied' | 'errCopied' | 'done' | 'fail' | 'removed' | 'removeFail' | 'revealFail' | 'restartDesktop' | 'installedLive' | 'installedReload'
 
 export interface ToastState {
   id: number

package/src/server/http/routes.ts

@@ -28,6 +28,7 @@ import { appendLog, clearLog, readLog, logFilePath, defaultLogFilePath, customLo
  * 不用 `/bin/sh -c`：Windows 无 /bin/sh，且 lsof/nohup 仅 POSIX 存在。
  * 由 `spawn(process.execPath, ['-e', SCRIPT, port], { detached, stdio:'ignore' })` 孵化，
  * 宿主进程被 kill 后仍能完成「停旧 → 等端口释放 → 拉起新 dsh web」。
+ * 端口探测不到监听进程时不再假装重启（记一行日志后退出，见脚本内注释）。
  */
 const HOST_RESTART_SCRIPT = String.raw`const C = require('node:child_process')
 const F = require('node:fs')
@@ -54,7 +55,16 @@ function findPids() {
   return String(out.stdout || '').split(/\s+/).filter(Boolean)
 }
 
-for (const pid of findPids()) {
+const targets = findPids()
+// 一个监听进程都没找到 = 端口探测本身就失败了（netstat 输出格式 / 本地化差异），
+// 旧宿主仍占着端口。此时再拉一个 dsh web 只会在日志里以 EADDRINUSE 静默退出，
+// 用户却看到「重启完成」——不制造这种假象，留一行可诊断的记录后退出。
+if (targets.length === 0) {
+  logLine('restart aborted: no listener found on port ' + port)
+  process.exit(0)
+}
+
+for (const pid of targets) {
   try {
     if (win) C.spawnSync('taskkill', ['/pid', pid, '/t', '/f'])
     else process.kill(Number(pid), 'SIGTERM')
@@ -67,6 +77,14 @@ let tries = 0
   setTimeout(waitForStop, 250)
 })()
 
+function logLine(msg) {
+  try {
+    const dir = P.join(O.homedir(), '.dsh', 'logs')
+    F.mkdirSync(dir, { recursive: true })
+    F.appendFileSync(P.join(dir, 'dsh-web-' + port + '.log'), '[' + new Date().toISOString() + '] ' + msg + '\n')
+  } catch {}
+}
+
 function startHost() {
   const dir = P.join(O.homedir(), '.dsh', 'logs')
   F.mkdirSync(dir, { recursive: true })
@@ -79,6 +97,14 @@ function startHost() {
   child.unref()
 }`
 
+/**
+ * 宿主是否由桌面应用壳托管（`ELECTRON_RUN_AS_NODE=1`：壳用 Electron 二进制以 Node 模式跑宿主）。
+ * 桌面端的宿主归应用壳管，插件重启不了它，也不该去 kill —— 详见 /restart 路由。
+ */
+export function isDesktopHost(): boolean {
+  return process.env.ELECTRON_RUN_AS_NODE === '1'
+}
+
 export interface WebRoute {
   kind: 'exact'
   path: string
@@ -999,6 +1025,8 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
             env: mutationEnv(settings),
             // 覆盖更新：npm 通道命令显式 @latest（pnpm add 无版本对已存在依赖是幂等的，不加版本不会真更新）
             updateNpm: mode === 'update',
+            // 运行中 loader：安装成功后把新插件热挂进 loader，非桌面端 + 纯服务端插件无需重启即生效
+            loader,
             // 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：日志/报错据此溯源
             installChannel,
           })
@@ -1043,7 +1071,7 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
             // 卸载的 mutation 目标是 npm 包名；待重启行要显示 owner/repo（与安装行一致），非法/缺失时回退包名
             displayTarget: githubRepoOf(repo) ?? undefined,
             // 运行中 loader：卸载成功后主动移除条目，立即生效、无需重启
-            uninstallLoader: loader,
+            loader,
             timeoutMs: COMMAND_TIMEOUT_MS,
             env: mutationEnv(loadSettings(profile)),
           })
@@ -1109,6 +1137,15 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
       path: '/dsh-plugin-hub/restart',
       handler: (request, response) => {
         if (!requireTrustedPost(request, response)) return
+        // 桌面端：宿主由应用壳托管，插件重启不了它。Windows 上 `taskkill /T` 会把发起
+        // 重启的助手一起结束（助手是宿主的子进程），壳再把这次外部 kill 判成宿主崩溃
+        // 弹「应用无法启动或已意外停止」；退一步说，脱离壳拉起的 `dsh web` 也服务不了
+        // 桌面 UI（缺壳注入的 desktop:boot）。故不 kill、不拉新宿主，由客户端改提示
+        // 用户从菜单/托盘退出后重新打开。
+        if (isDesktopHost()) {
+          sendJson(response, 200, { ok: false, desktop: true })
+          return
+        }
         // 当前宿主监听端口来自请求 Host 头（localhost:7923），解析失败回退 7923
         const host = request.headers.host ?? ''
         const portMatch = host.match(/:(\d+)$/)

package/src/server/services/install/install-types.ts

@@ -39,8 +39,15 @@ export interface InstallTask {
   progress: number
   /** Newest output lines first (consumer shows the tail). */
   lines: string[]
-  /** 完成后是否仍需宿主重启才生效：卸载时 loader 已即时移除 → false；否则 true（弹窗据此给重启选项） */
+  /** 完成后是否仍需宿主重启才生效：仅「热挂载失败 / 非 dsh 插件 / 更新（ESM 缓存取不到新代码）/
+   *  无 loader」等刷新解决不了的兜底场景为 true（弹窗给「立即重启」）；其余一律 false。 */
   needsRestart: boolean
+  /** 完成后是否只需刷新页面即生效（插件已热挂进运行中 loader，仅剩客户端 UI 待页面重新加载，
+   *  网页端与桌面端一致）：true 时关闭结果弹窗即自动刷新页面，不给手动刷新按钮。 */
+  needsReload?: boolean
+  /** 卸载入队时该包是否带客户端 UI（`dsh.client`）：卸载后包已从磁盘删除，只能入队前快照，
+   *  卸载成功且曾存活时据此决定是否需要刷新页面摘除插件面板。 */
+  hadClientUi?: boolean
 }
 
 /** 子进程启动参数（复用宿主 dsh 入口，或回退到 PATH 上的 `dsh`）。 */

package/src/server/services/install/task-queue.ts

@@ -16,7 +16,7 @@ import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.
 import { npmTooLowMarker } from './npm-check.ts'
 import { cleanLine, estimateProgress } from '../profile/progress.ts'
 import type { LoaderHandle } from '../loader.ts'
-import { removeLoadedEntry } from '../loader.ts'
+import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.ts'
 import { addPendingRestart, clearPendingRestart } from '../profile/pending-restart.ts'
 import { addAllowBuildsKey, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.ts'
 import { appendLog } from '../log.ts'
@@ -256,8 +256,9 @@ export function startPluginMutation(options: {
   globalNpm?: string[]
   /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
   displayTarget?: string
-  /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
-  uninstallLoader?: LoaderHandle
+  /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目，两类操作都尽量立即生效
+   *  （缺失时安装/卸载仍需重启） */
+  loader?: LoaderHandle
   /** 入队前已尝试的安装方式（npm registry 反查等）：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
   attempts?: string[]
   /** 更新已安装的 npm 包（mode=update）：命令显式带 @latest，让 pnpm 真正解析最新版本 */
@@ -266,7 +267,10 @@ export function startPluginMutation(options: {
    *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装不传 */
   installChannel?: 'npm' | 'git' | 'dsh'
 }): InstallTask {
-  const task: InstallTask = { id: nextTaskId, target: options.target, displayTarget: options.displayTarget, globalNpm: options.globalNpm, action: options.action, status: 'pending', timedOut: false, exitCode: null, progress: 0, lines: [], attempts: options.attempts ?? [], needsRestart: false, installChannel: options.installChannel }
+  // 卸载入队时先快照「该包是否带客户端 UI」：卸载完成后包已从磁盘删除，读不到 package.json，
+  // 只能在此刻取；卸载成功且曾存活时据此决定是否要刷新页面摘除插件面板
+  const hadClientUi = options.action === 'remove' ? hasClientUi(options.profile, options.target) : undefined
+  const task: InstallTask = { id: nextTaskId, target: options.target, displayTarget: options.displayTarget, globalNpm: options.globalNpm, action: options.action, status: 'pending', timedOut: false, exitCode: null, progress: 0, lines: [], attempts: options.attempts ?? [], needsRestart: false, hadClientUi, installChannel: options.installChannel }
   nextTaskId = nextTaskId >= Number.MAX_SAFE_INTEGER ? 1 : nextTaskId + 1
   tasks.set(task.id, task)
   if (tasks.size > MAX_TASKS) {
@@ -367,14 +371,14 @@ function spawnMutation(options: {
   task?: InstallTask
   /** 待重启行的展示目标（owner/repo）：与 mutation 目标解耦——卸载的 mutation 目标是 npm 包名，展示要回退到仓库名 */
   displayTarget?: string
-  /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
-  uninstallLoader?: LoaderHandle
+  /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目（缺失时仍需重启） */
+  loader?: LoaderHandle
   /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
   globalNpm?: string[]
   /** 更新已安装的 npm 包（mode=update）：命令显式带 @latest，让 pnpm 真正解析最新版本 */
   updateNpm?: boolean
 }): Promise<InstallResult> {
-  const { action, profile, target, timeoutMs = 5 * 60 * 1000, env, task, displayTarget, uninstallLoader, globalNpm, updateNpm } = options
+  const { action, profile, target, timeoutMs = 5 * 60 * 1000, env, task, displayTarget, loader, globalNpm, updateNpm } = options
   // 全局 npm 安装：直接 spawn 本机 npm（`npm install -g <pkgs>`），不是 dsh plugin 命令
   const isGlobalNpm = (globalNpm ?? []).length > 0
   const invocation = isGlobalNpm
@@ -555,18 +559,30 @@ function spawnMutation(options: {
           if (isGlobalNpm) {
             // 全局 npm 安装：装的是本机 CLI 工具（如 dsh-tui），不进任何 profile，无需宿主重启
             task.needsRestart = false
-          } else if (action === 'remove' && uninstallLoader) {
-            // 卸载成功 → 主动从运行中 loader 停用该包条目；
-            // 仅当宿主从未加载过它（磁盘已干净）才判「无需重启」；
-            // 只要曾在 loader 中存活（停用过 live entry）就仍要求重启——
-            // 带 UI 的插件（侧边栏面板等宿主启动时渲染的槽位）disable 后不会
-            // 主动消失，重启才能立即摘除面板
-            const removed = await removeLoadedEntry(uninstallLoader, target)
-            task.needsRestart = !removed
-            if (removed) clearPendingRestart(displayTarget ?? target)
-            else addPendingRestart(displayTarget ?? target, 'uninstall')
+          } else if (action === 'remove' && loader) {
+            // 卸载成功 → 主动从运行中 loader 停用该包条目：
+            //  - 停用成功：服务端即时卸载；带客户端 UI 的插件面板要页面刷新才摘除（无需重启宿主）
+            //  - 停用失败 / 超时：回退「待重启」兜底清理（刷新解决不了，登记常驻提醒）
+            const removal = await removeLoadedEntry(loader, target)
+            task.needsRestart = !removal.ok
+            task.needsReload = removal.ok && removal.live && task.hadClientUi === true
+            if (task.needsRestart) addPendingRestart(displayTarget ?? target, 'uninstall')
+            else clearPendingRestart(displayTarget ?? target)
+          } else if (action !== 'remove' && !isUpdate && loader) {
+            // 安装成功 → 尝试把新插件热挂进运行中 loader，让插件无需重启宿主即生效。
+            // 挂上了：服务端即时生效；带客户端 UI 的插件还需页面重新加载（宿主按请求现场
+            //   拼装 __DSH_BOOT__ 注入清单，网页端与桌面端一致，刷新即可）。
+            // 挂不上 / 非 dsh 插件 / 无法定位包名：回退「待重启」提醒（保证不静默失效）。
+            const { name } = verifyInstalledEntry(profile, target)
+            if (name !== null && isDshPlugin(profile, name) && await mountLoadedEntry(loader, name)) {
+              task.needsReload = hasClientUi(profile, name)
+              task.needsRestart = false
+            } else {
+              task.needsRestart = true
+              addPendingRestart(displayTarget ?? target, 'install')
+            }
           } else {
-            // 安装/更新成功（或卸载但无 loader 引用）→ 登记待重启：
+            // 更新（ESM 缓存下热挂取不到新代码）/ 无 loader 的安装或卸载 → 登记待重启：
             // 插件要宿主重启才会挂载/卸载干净，重启前一直提醒；展示目标用 displayTarget（owner/repo）
             task.needsRestart = true
             addPendingRestart(displayTarget ?? target, action === 'remove' ? 'uninstall' : 'install')
@@ -660,8 +676,8 @@ export async function runPluginMutation(options: {
   task?: InstallTask
   /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
   displayTarget?: string
-  /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
-  uninstallLoader?: LoaderHandle
+  /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目（缺失时仍需重启） */
+  loader?: LoaderHandle
   /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
   globalNpm?: string[]
 }): Promise<InstallResult> {