dsh-plugin 1.1.2 → 1.2.1

package/src/server/services/{npm-resolve.ts → install/npm-resolve.ts}

@@ -8,7 +8,7 @@
  *
  * 这是通用机制，不针对任何具体插件：只要作者发布了 repository 指向该
  * GitHub 仓库的 npm 包（scope 名与 GitHub 用户名是否一致无所谓），就能命中，
- * 从而把「git 直装必败」的插件切换到 npm 通道安装。命中结果带内存缓存，
+ * 从而把 git 分发不完整的插件切换到 npm 通道安装。命中结果带内存缓存，
  * 避免同一会话内重复查询 registry。
  */
 import { get } from 'node:https'
@@ -23,20 +23,22 @@ const REQUEST_TIMEOUT_MS = 8000
  * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
  * 返回 null 不代表仓库一定没有 npm 包，只代表本次未能确认 —— 调用方应保留
  * 原有错误路径，反查只是额外的一次尝试。
+ * @param registry - npm 镜像源地址（空串 = 官方 https://registry.npmjs.org）
  */
-export function resolveNpmPackage(repo: string): Promise<string | null> {
+export function resolveNpmPackage(repo: string, registry = ''): Promise<string | null> {
   const key = repo.toLowerCase()
   if (cache.has(key)) return Promise.resolve(cache.get(key) ?? null)
-  const name = searchRepo(repo)
+  const name = searchRepo(repo, registry)
   name.then((found) => cache.set(key, found)).catch(() => cache.set(key, null))
   return name
 }
 
 /** 用 npm search 接口按 repository 地址反查，并做铁证校验（包元数据必须指向该仓库）。 */
-function searchRepo(repo: string): Promise<string | null> {
+function searchRepo(repo: string, registry: string): Promise<string | null> {
   const [owner, name] = repo.split('/')
   if (owner === undefined || name === undefined || name === '') return Promise.resolve(null)
-  const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(`repository:${owner}/${name}`)}&size=10`
+  const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '')
+  const url = `${base}/-/v1/search?text=${encodeURIComponent(`repository:${owner}/${name}`)}&size=10`
   return new Promise((resolve) => {
     const req = get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
       if (res.statusCode !== 200) {

package/src/server/services/{preflight.ts → install/preflight.ts}

@@ -17,10 +17,14 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
 import { promisify } from 'node:util'
-import { githubRepoOf } from './profile.ts'
+import { githubRepoOf } from '../profile/profile.ts'
 
 const execFileAsync = promisify(execFile)
 
+/** 单次网络操作超时（ms）：git ls-remote / codeload 下载。网络不可达时不能无限挂起，
+ *  否则 `/install` 请求永远不返回、任务不入队、前端进度卡 0%。超时后放行（交给装后校验）。 */
+const PREFLIGHT_TIMEOUT_MS = 15_000
+
 /** 预检结果：ok=false 表示分发改入口文件缺失，missing 为该文件在包内的相对路径。 */
 export interface PreflightResult {
   ok: boolean
@@ -33,7 +37,10 @@ export async function preflightTarget(target: string): Promise<PreflightResult>
   const [owner, repo] = source.split('/')
   let commit = ''
   try {
-    const { stdout } = await execFileAsync('git', ['ls-remote', `https://github.com/${owner}/${repo}.git`, 'HEAD'])
+    const { stdout } = await execFileAsync('git', ['ls-remote', `https://github.com/${owner}/${repo}.git`, 'HEAD'], {
+      timeout: PREFLIGHT_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024,
+    })
     commit = stdout.split(/\s+/)[0] ?? ''
   } catch {
     return { ok: true, missing: null }
@@ -63,13 +70,15 @@ export async function preflightTarget(target: string): Promise<PreflightResult>
 
 function download(url: string, dest: string): Promise<void> {
   return new Promise((resolve, reject) => {
-    get(url, (res) => {
+    const req = get(url, { timeout: PREFLIGHT_TIMEOUT_MS }, (res) => {
       if (res.statusCode === 301 || res.statusCode === 302 || res.statusCode === 303) {
         res.resume()
         if (res.headers.location) {
           void download(res.headers.location, dest).then(resolve, reject)
           return
         }
+        reject(new Error('download failed: redirect without location'))
+        return
       }
       if (res.statusCode !== 200) {
         res.resume()
@@ -77,7 +86,10 @@ function download(url: string, dest: string): Promise<void> {
         return
       }
       void pipeline(res, createWriteStream(dest)).then(resolve, reject)
-    }).on('error', reject)
+    })
+    // 网络不可达时 connect/响应可能无限挂起：超时销毁，避免预检卡死（放行交给装后校验）
+    req.on('timeout', () => req.destroy(new Error(`download timeout after ${PREFLIGHT_TIMEOUT_MS}ms`)))
+    req.on('error', reject)
   })
 }
 

package/src/server/services/{task-queue.ts → install/task-queue.ts}

@@ -12,11 +12,13 @@ import { readFileSync, statSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import type { InstallResult, InstallTask, Invocation, QueueItem } from './install-types.ts'
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.ts'
-import { cleanLine, estimateProgress } from './progress.ts'
-import type { LoaderHandle } from './loader.ts'
-import { removeLoadedEntry } from './loader.ts'
-import { addPendingRestart, clearPendingRestart } from './pending-restart.ts'
-import { addAllowBuildsKey, githubRepoOf, parseAllowBuildsKey, profileDirectory } from './profile.ts'
+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 { addPendingRestart, clearPendingRestart } from '../profile/pending-restart.ts'
+import { addAllowBuildsKey, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.ts'
+import { appendLog } from '../log.ts'
 
 /** In-memory task registry, keyed by task id. */
 const tasks = new Map<number, InstallTask>()
@@ -167,6 +169,8 @@ export function startPluginMutation(options: {
   target: string
   timeoutMs?: number
   env?: NodeJS.ProcessEnv
+  /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
+  globalNpm?: string[]
   /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
   displayTarget?: string
   /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
@@ -174,7 +178,7 @@ export function startPluginMutation(options: {
   /** 入队前已尝试的安装方式（npm registry 反查等）：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
   attempts?: string[]
 }): InstallTask {
-  const task: InstallTask = { id: nextTaskId, target: options.target, displayTarget: options.displayTarget, action: options.action, status: 'pending', timedOut: false, exitCode: null, progress: 0, lines: [], attempts: options.attempts ?? [], needsRestart: false }
+  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 }
   nextTaskId = nextTaskId >= Number.MAX_SAFE_INTEGER ? 1 : nextTaskId + 1
   tasks.set(task.id, task)
   if (tasks.size > MAX_TASKS) {
@@ -187,6 +191,15 @@ export function startPluginMutation(options: {
     })
   }
   queue.push({ task, options: { ...options } })
+  // 系统日志：记录任务入队（安装/卸载开始）
+  const category = options.action === 'add' ? 'install' : 'uninstall'
+  appendLog(options.profile, {
+    at: Date.now(),
+    level: 'info',
+    category,
+    event: `${category}.start`,
+    message: `${options.action === 'add' ? '开始安装' : '开始卸载'} ${options.displayTarget ?? options.target}`,
+  })
   pumpQueue()
   return task
 }
@@ -200,6 +213,34 @@ function pumpQueue(): void {
   task.status = 'running'
   void runPluginMutation({ ...options, task }).finally(() => {
     runningChildren.delete(task.id)
+    // 系统日志：任务终态（成功/失败/取消），按动作归类安装/卸载日志
+    const show = task.displayTarget ?? task.target
+    const category = task.action === 'add' ? 'install' : 'uninstall'
+    if (task.status === 'done') {
+      appendLog(options.profile, {
+        at: Date.now(),
+        level: 'success',
+        category,
+        event: `${category}.done`,
+        message: `${task.action === 'add' ? '安装成功' : '卸载成功'} ${show}${task.needsRestart ? '（待重启生效）' : ''}`,
+      })
+    } else if (task.status === 'failed') {
+      appendLog(options.profile, {
+        at: Date.now(),
+        level: 'error',
+        category,
+        event: `${category}.fail`,
+        message: `${task.action === 'add' ? '安装失败' : '卸载失败'} ${show}`,
+      })
+    } else if (task.status === 'cancelled') {
+      appendLog(options.profile, {
+        at: Date.now(),
+        level: 'warn',
+        category,
+        event: 'task.cancel',
+        message: `已取消 ${show}`,
+      })
+    }
     // 已终态的任务移出队列：既防 queue 数组无限增长（内存泄漏），也让下一轮 pump 干净
     const idx = queue.findIndex((it) => it.task === task)
     if (idx >= 0) queue.splice(idx, 1)
@@ -223,24 +264,37 @@ function spawnMutation(options: {
   displayTarget?: string
   /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
   uninstallLoader?: LoaderHandle
+  /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
+  globalNpm?: string[]
 }): Promise<InstallResult> {
-  const { action, profile, target, timeoutMs = 5 * 60 * 1000, env, task, displayTarget, uninstallLoader } = options
-  const invocation = cliInvocation()
-  const args = [...invocation.prefixArgs, 'plugin', '--profile', profile, action, target]
-  // 记录实际执行的命令（npm 通道显示包名，git 通道显示 HTTPS 源）：失败提 Issue 时
-  // 「已尝试的安装方式」如实展示完整命令链，作者一眼看清我们跑过什么
-  const executed = `dsh plugin --profile ${profile} ${action} ${target}`
+  const { action, profile, target, timeoutMs = 5 * 60 * 1000, env, task, displayTarget, uninstallLoader, globalNpm } = options
+  // 全局 npm 安装：直接 spawn 本机 npm（`npm install -g <pkgs>`），不是 dsh plugin 命令
+  const isGlobalNpm = (globalNpm ?? []).length > 0
+  const invocation = isGlobalNpm
+    ? { file: 'npm', prefixArgs: [], cwd: process.cwd(), useShell: process.platform === 'win32' }
+    : cliInvocation()
+  const args = isGlobalNpm
+    ? ['install', '-g', ...(globalNpm ?? [])]
+    : [...invocation.prefixArgs, 'plugin', '--profile', profile, action, target]
+  // 记录实际执行的命令（npm 通道显示包名，git 通道显示 HTTPS 源），
+  // 失败提 Issue 时作为「已尝试的安装方式」随附
+  const executed = isGlobalNpm
+    ? `npm install -g ${(globalNpm ?? []).join(' ')}`
+    : `dsh plugin --profile ${profile} ${action} ${target}`
   if (task && !task.attempts.includes(executed)) {
     task.attempts.push(executed)
   }
-  return new Promise((resolvePromise) => {
+  // 单次 spawn 并捕获结果：流式输出打日志 + 超时/取消兜底，close 后 resolve。
+  // 不做任何终态后处理（exitCode/status/needsRestart 由下方统一收尾），
+  // 这样全局 npm 首次失败后可以干净地换参数重试一次。
+  const spawnOnce = (attemptArgs: string[]): Promise<InstallResult> => new Promise((resolveOnce) => {
     let stdout = ''
     let stderr = ''
     let timedOut = false
     let settled = false
     let child: ReturnType<typeof spawn>
     try {
-      child = spawn(invocation.file, args, {
+      child = spawn(invocation.file, attemptArgs, {
         cwd: invocation.cwd,
         env,
         shell: invocation.useShell,
@@ -255,7 +309,7 @@ function spawnMutation(options: {
         task.exitCode = null
         pushLine(task, `[error] ${error instanceof Error ? error.message : String(error)}`)
       }
-      resolvePromise({
+      resolveOnce({
         exitCode: null,
         timedOut: false,
         error: error instanceof Error ? error.message : String(error),
@@ -272,9 +326,8 @@ function spawnMutation(options: {
     let exitWatch: ReturnType<typeof setTimeout> | undefined
     let forceSettle: ReturnType<typeof setTimeout> | undefined
 
-    // 唯一收尾入口：close / error / 兜底超时 三者只放行一次，
-    // 保证 runPluginMutation 必然 resolve、队列 worker 必然继续推进
-    const settle = (result: InstallResult): void => {
+    // 唯一收尾入口：close / error / 兜底超时 三者只放行一次，确保任务持续推进
+    const settleOnce = (result: InstallResult): void => {
       if (settled) return
       settled = true
       if (timer !== undefined) clearTimeout(timer)
@@ -282,7 +335,7 @@ function spawnMutation(options: {
       if (exitWatch !== undefined) clearTimeout(exitWatch)
       if (forceSettle !== undefined) clearTimeout(forceSettle)
       if (task) runningChildren.delete(task.id)
-      resolvePromise(result)
+      resolveOnce(result)
     }
 
     timer = setTimeout(() => {
@@ -298,7 +351,7 @@ function spawnMutation(options: {
       if (kind === 'stdout') stdout = (stdout + text).slice(-CAPTURE_LIMIT_BYTES)
       else stderr = (stderr + text).slice(-CAPTURE_LIMIT_BYTES)
       if (task) {
-        // 原生透传 pnpm 输出：stdout/stderr 原样入日志，不做格式化，保证报错信息完整可见
+        // 原生透传 pnpm/npm 输出：stdout/stderr 原样入日志，不做格式化，保证报错信息完整可见
         for (const line of text.split(/\r?\n|\r/)) {
           if (line.trim() !== '') pushLine(task, line.trimEnd())
         }
@@ -310,7 +363,7 @@ function spawnMutation(options: {
     child.once('exit', () => {
       // dsh 内部会 fork pnpm：pnpm 退出后仍攥着 stdout/stderr 管道时，
       // close 事件不会到来。exit 后给 close 一段宽限，未按时触发则整组清理强制结束，
-      // 保证任务必然进入终态、后续排队任务自动启动。
+      // 确保任务进入终态、后续排队任务自动启动。
       exitWatch = setTimeout(() => {
         if (settled) return
         if (task && task.status !== 'cancelled') pushLine(task, '[stale pipe] force closing child')
@@ -324,7 +377,7 @@ function spawnMutation(options: {
             task.timedOut = true
             pushLine(task, '[timed out]')
           }
-          settle({ exitCode: null, timedOut: true, error: 'child failed to close', stdout, stderr })
+          settleOnce({ exitCode: null, timedOut: true, error: 'child failed to close', stdout, stderr })
         }, 5_000)
       }, 3_000)
     })
@@ -335,43 +388,62 @@ function spawnMutation(options: {
         task.exitCode = null
         pushLine(task, `[error] ${error.message}`)
       }
-      settle({ exitCode: null, timedOut: false, error: error.message, stdout, stderr })
+      settleOnce({ exitCode: null, timedOut: false, error: error.message, stdout, stderr })
     })
 
-    child.once('close', async (code) => {
-      try {
-        if (task) {
-          task.exitCode = code
-          task.timedOut = timedOut
-          if (task.status !== 'cancelled') {
-            task.status = timedOut || code !== 0 ? 'failed' : 'done'
-            if (task.status === 'done') {
-              task.progress = 100
-              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 {
-                // 安装成功（或卸载但无 loader 引用）→ 登记待重启：
-                // 插件要宿主重启才会挂载/卸载干净，重启前一直提醒；展示目标用 displayTarget（owner/repo）
-                task.needsRestart = true
-                addPendingRestart(displayTarget ?? target, action === 'add' ? 'install' : 'uninstall')
-              }
-            }
-            pushLine(task, timedOut ? '[timed out]' : `[exit ${code ?? '?'}]`)
+    child.once('close', (code) => {
+      settleOnce({ exitCode: code, timedOut, error: null, stdout, stderr })
+    })
+  })
+
+  return (async () => {
+    let result = await spawnOnce(args)
+    // npm 11 的 arborist peer-set bug（`Cannot read properties of null (reading 'children')`，npm/cli#9911）：
+    // 某些包的 peerDependencies 用「双段 prerelease 范围」（如 dsh-tui@0.9.0 的 `^0.1.0-rc.6 || ^0.1.1-rc.1`，
+    // 26 个必需 peer 全是这种形状）会让 `npm install -g` 在解析阶段直接崩溃 —— 退出码 1、什么都没装，
+    // 与是不是从我们界面发起无关（终端里同样复现）。首次失败后自动带 `--legacy-peer-deps` 重试一次：
+    // 跳过 peer 自动解析即可绕过该 bug（peer 通常由同装的 @deepseek-ai/dsh 依赖树天然提供）。
+    // 二次尝试仍失败则保留其错误信息，不掩盖真正的原因。
+    if (isGlobalNpm && result.exitCode !== 0 && !result.timedOut && task?.status !== 'cancelled') {
+      const retryArgs = ['install', '-g', '--legacy-peer-deps', ...(globalNpm ?? [])]
+      const retryExecuted = `npm install -g --legacy-peer-deps ${(globalNpm ?? []).join(' ')}`
+      if (task && !task.attempts.includes(retryExecuted)) task.attempts.push(retryExecuted)
+      if (task) pushLine(task, '[npm] peer-set resolution crashed npm (known npm bug) — retrying with --legacy-peer-deps')
+      result = await spawnOnce(retryArgs)
+    }
+    // 统一终态后处理：exitCode/status/needsRestart 以最后一次尝试为准
+    if (task) {
+      task.exitCode = result.exitCode
+      task.timedOut = result.timedOut
+      if (task.status !== 'cancelled') {
+        task.status = result.timedOut || result.exitCode !== 0 ? 'failed' : 'done'
+        if (task.status === 'done') {
+          task.progress = 100
+          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 {
+            // 安装成功（或卸载但无 loader 引用）→ 登记待重启：
+            // 插件要宿主重启才会挂载/卸载干净，重启前一直提醒；展示目标用 displayTarget（owner/repo）
+            task.needsRestart = true
+            addPendingRestart(displayTarget ?? target, action === 'add' ? 'install' : 'uninstall')
           }
         }
-      } finally {
-        settle({ exitCode: code, timedOut, error: null, stdout, stderr })
+        pushLine(task, result.timedOut ? '[timed out]' : `[exit ${result.exitCode ?? '?'}]`)
       }
-    })
-  })
+    }
+    return result
+  })()
 }
 
 /**
@@ -427,6 +499,21 @@ function ignoredBuildKeys(output: string): string[] {
     .filter((s) => s !== '')
 }
 
+/** npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 把 [npm-too-low] 标记追加到任务输出，
+ *  前端据此展示「本机 npm 版本过低」的准确原因 —— 避免该报错被外层 ERR_PNPM_PREPARE_PACKAGE
+ *  误判成插件打包/分发问题、误导用户提 Issue。检测逻辑在独立的 npm-check.ts（本机 npm 环境职责）。 */
+function annotateNpmTooLow(result: InstallResult, options: {
+  action: 'add' | 'remove'
+  task?: InstallTask
+  env?: NodeJS.ProcessEnv
+}): InstallResult {
+  if (options.action !== 'add' || result.exitCode === 0 || result.timedOut) return result
+  const line = npmTooLowMarker(`${result.stderr}\n${result.stdout}`, options.env)
+  if (line === null) return result
+  if (options.task && options.task.status !== 'cancelled') pushLine(options.task, line)
+  return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line }
+}
+
 /**
  * Run a plugin mutation with one recovery path: when `add` fails because
  * pnpm's allowBuilds gate blocks a build script — either the git-hosted
@@ -447,9 +534,13 @@ export async function runPluginMutation(options: {
   displayTarget?: string
   /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
   uninstallLoader?: LoaderHandle
+  /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
+  globalNpm?: string[]
 }): Promise<InstallResult> {
-  const result = await spawnMutation(options)
-  if (options.action === 'add' && result.exitCode !== 0 && !result.timedOut) {
+  let result = await spawnMutation(options)
+  // allowBuilds 放行 / 装后入口校验都是 profile 专属（pnpm 装进 profile 的场景）；
+  // 全局 npm 安装直接走 npm，无 pnpm allowBuilds 拦截、也不进 profile，跳过这两类恢复
+  if (options.action === 'add' && result.exitCode !== 0 && !result.timedOut && (options.globalNpm ?? []).length === 0) {
     const output = `${result.stderr}\n${result.stdout}`
     // git 源：pnpm 打印的 key@url 提示
     if (output.includes('ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED')) {
@@ -463,14 +554,15 @@ export async function runPluginMutation(options: {
           pushLine(options.task, `[allow build] ${key}`)
         }
         addAllowBuildsKey(options.profile, key)
-        return spawnMutation(options)
+        result = await spawnMutation(options)
       }
     }
     // 依赖原生模块/构建脚本被 pnpm v11 拦截（ERR_PNPM_IGNORED_BUILDS）：git 与 npm 源都会出现。
     // allowBuilds 的 key 是输出里列出的 name@version（如 node-pty@1.1.0），逐个放行后重试一次；
     // 输出解析不到时回退用目标名（插件自身构建脚本被拦的 npm 场景）。
-    if (output.includes('ERR_PNPM_IGNORED_BUILDS')) {
-      const keys = ignoredBuildKeys(output)
+    // 用重试后的最终结果判断：git 源放行 prepare 后可能又在依赖层撞上原生构建拦截。
+    if (result.exitCode !== 0 && !result.timedOut && `${result.stderr}\n${result.stdout}`.includes('ERR_PNPM_IGNORED_BUILDS')) {
+      const keys = ignoredBuildKeys(`${result.stderr}\n${result.stdout}`)
       if (keys.length === 0 && githubRepoOf(options.target) === null) keys.push(options.target)
       if (keys.length > 0) {
         if (options.task) {
@@ -479,13 +571,14 @@ export async function runPluginMutation(options: {
           pushLine(options.task, `[allow build] ${keys.join(', ')}`)
         }
         for (const key of keys) addAllowBuildsKey(options.profile, key)
-        return spawnMutation(options)
+        result = await spawnMutation(options)
       }
     }
   }
   // pnpm 安装本身成功，但目标包入口文件缺失（git 分发缺构建产物）→ 判为失败：
-  // 撤销刚登记的待重启，避免用户重启时宿主加载残缺包直接崩溃
-  if (options.action === 'add' && result.exitCode === 0 && !result.timedOut) {
+  // 撤销刚登记的待重启，避免用户重启时宿主加载残缺包直接崩溃。
+  // 全局 npm 安装不进 profile（profile deps 里没有这些包），跳过入口校验
+  if (options.action === 'add' && result.exitCode === 0 && !result.timedOut && (options.globalNpm ?? []).length === 0) {
     const verified = verifyInstalledEntry(options.profile, options.target)
     if (verified.name !== null && verified.missing !== null) {
       clearPendingRestart(options.displayTarget ?? options.target)
@@ -499,5 +592,6 @@ export async function runPluginMutation(options: {
       return { exitCode: 1, timedOut: false, error: `entry file missing: ${verified.missing}`, stdout: result.stdout, stderr: `${result.stderr}\n${detail}` }
     }
   }
-  return result
+  // npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 追加 [npm-too-low] 标记，前端据此给准确原因
+  return annotateNpmTooLow(result, options)
 }

package/src/server/services/loader.ts

@@ -6,6 +6,9 @@
  * 运行中 loader 的读取与停用：卸载成功后对匹配条目做 live-disable，
  * 使卸载立即生效（刷新页面不再加载已卸载的 client bundle，也无需重启）。
  */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { profileDirectory } from './profile/profile.ts'
 
 /**
  * 运行中 loader 的最小接口：卸载成功后即时移除条目用。
@@ -36,6 +39,19 @@ export function dumpLoaderEntries(loader: LoaderHandle | undefined): Array<{ id:
   return entries
 }
 
+/**
+ * 判断某 npm 包名是否已加载进运行中 loader（宽匹配：条目名存在别名变体）。
+ * 官方 `ctx.loader.entries()` 遍历整棵树（reference.md §1.3），条目名 == 插件作者声明的名字。
+ * 安装完成但未重启时条目不在 loader → 返回 false，UI 据此标「待重启/未加载」。
+ */
+export function isEntryLoaded(loader: LoaderHandle | undefined, name: string): boolean {
+  if (!loader) return false
+  for (const entry of Array.from(loader.entries())) {
+    if (nameMatches(entry.options?.name, name)) return true
+  }
+  return false
+}
+
 /**
  * 卸载目标（npm 包名，如 `@scope/widget`）与 loader 条目名的匹配。
  * loader 条目名由插件作者/工具写入，形式不可控，常见变体：
@@ -43,7 +59,8 @@ export function dumpLoaderEntries(loader: LoaderHandle | undefined): Array<{ id:
  *  - 去 `@` 前缀：`scope/widget`
  *  - 去 scope 的短名：`widget`
  *  - scope 分隔符变 `-`：`scope-widget`
- * 因此归一化后比较全串与短名两个维度。profile 内包名唯一，宽松匹配不会误伤其它包。
+ *  - 包内模块路径：`widget/extensions/dsh/index.js`（bundle patch 的 name 常写成模块路径）
+ * 因此归一化后比较全串、短名、路径前缀三个维度。profile 内包名唯一，宽松匹配不会误伤其它包。
  */
 function nameMatches(entryName: string | undefined, target: string): boolean {
   if (!entryName) return false
@@ -60,6 +77,12 @@ function nameMatches(entryName: string | undefined, target: string): boolean {
   // 3) 反向变体：目标短名可能就是条目的完整形式（条目 `scope-widget`，
   //    目标短名 `widget` 是它的尾段）——用「条目名以短名结尾」收口，避免误伤。
   if (tShort.length >= 2 && e.endsWith(`-${tShort}`)) return true
+  // 4) 条目名是目标包内的模块路径（`aegis/extensions/dsh/index.js` 属于包 `aegis`，
+  //    `@scope/pkg/dist/x.js` 属于 `@scope/pkg`）：归一化会吞掉路径分隔符，
+  //    必须在归一化前用原始形态做「target/」前缀判断（大小写不敏感）。
+  const rawE = entryName.trim().toLowerCase()
+  const rawT = target.trim().toLowerCase()
+  if (rawE === rawT || rawE.startsWith(`${rawT}/`)) return true
   return false
 }
 
@@ -119,3 +142,34 @@ export async function removeLoadedEntry(loader: LoaderHandle, name: string): Pro
   console.log(`[hub-uninstall] disable ${name} -> ${result ? 'ok/clean' : 'timed out or failed'}`)
   return result
 }
+
+/**
+ * 判断某已安装包是否是真正的 dsh 插件（宿主会加载 / 值得提示「待重启」）：
+ *  1) 包名已写进 profile 的 `dsh.profile.bundles`（宿主启动时按清单加载）；
+ *  2) 或包内 package.json 声明了 dsh 配置（`dsh.bundle` / `dsh.profile` 等）或 dsh 相关 keywords。
+ * 两者都满足不了（如 GitHub 官方示例仓库 octocat/Hello-World）说明它不是 dsh 插件，
+ * 装上也不会被宿主加载——UI 据此不再提示「待重启」，避免误导用户反复重启一个不会生效的东西。
+ */
+export function isDshPlugin(profile: string, name: string): boolean {
+  // 1) profile 级 bundles 清单：包名在清单里 → 宿主启动会加载它
+  try {
+    const profilePkg = JSON.parse(readFileSync(join(profileDirectory(profile), 'package.json'), 'utf8')) as {
+      dsh?: { profile?: { bundles?: unknown } }
+    }
+    if (Array.isArray(profilePkg.dsh?.profile?.bundles)) {
+      if ((profilePkg.dsh.profile.bundles as unknown[]).includes(name)) return true
+    }
+  } catch { /* profile 读取失败按无 bundles 处理 */ }
+  // 2) 包内声明：dsh 字段（bundle patch / profile 配置）或 dsh 关键字
+  try {
+    const pkg = JSON.parse(readFileSync(join(profileDirectory(profile), 'node_modules', name, 'package.json'), 'utf8')) as {
+      dsh?: unknown
+      keywords?: unknown
+    }
+    if (pkg.dsh) return true
+    if (Array.isArray(pkg.keywords)) {
+      if ((pkg.keywords as unknown[]).some((k) => typeof k === 'string' && /^(?:dsh|dsh-plugin)$/i.test(k))) return true
+    }
+  } catch { /* 包缺失 / 无 package.json → 不是 dsh 插件 */ }
+  return false
+}