dsh-plugin 1.1.1 → 1.2.0

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

@@ -1,7 +1,11 @@
 /**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
  * Install runner 的统一出口：执行真实插件变更（spawn 官方 dsh CLI 子进程）。
  * 实现按职责拆分在同目录子模块，本文件只做公共 API 的 re-export，保持外部
- * import 面稳定（routes.ts / index.ts 仍从 `services/install.ts` 引入）。
+ * import 面稳定（routes.ts / index.ts 仍从 `services/install/install.ts` 引入）。
  *
  * 模块划分：
  *  - install-types.ts  公共类型与常量
@@ -11,8 +15,8 @@
  *  - task-queue.ts      任务注册表 + FIFO 队列 worker + 子进程生命周期
  */
 export type { InstallResult, InstallTask, Invocation, PendingRestart, QueueItem } from './install-types.ts'
-export type { LoaderHandle } from './loader.ts'
-export { addPendingRestart, clearPendingRestart, listPendingRestarts } from './pending-restart.ts'
-export { dumpLoaderEntries, removeLoadedEntry } from './loader.ts'
-export { addAllowBuildsKey, githubTarget, parseAllowBuildsKey, readProfileArg, validPackageName } from './profile.ts'
+export type { LoaderHandle } from '../loader.ts'
+export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../profile/pending-restart.ts'
+export { dumpLoaderEntries, removeLoadedEntry } from '../loader.ts'
+export { addAllowBuildsKey, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName } from '../profile/profile.ts'
 export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.ts'

package/src/server/services/install/npm-check.ts

@@ -0,0 +1,53 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 本机 npm 环境检测：判断一次安装失败是否源于「本机 npm 版本过低」。
+ *
+ * 背景：pnpm 在 git 源插件的 prepare 阶段会调 npm 装依赖，npm arborist 在解 peer 依赖时
+ * 有已知内部崩溃 —— `Cannot read properties of null (reading 'edgesOut')`（build-ideal-tree.js
+ * 的 #loadPeerSet），官方标记 Cannot Reproduce（npm/cli#8261、#9787），npm 11.6.0 起不再复现。
+ * 该报错会被 pnpm 包进 ERR_PNPM_PREPARE_PACKAGE 输出，若按插件打包问题引导提 Issue 就误导了用户。
+ *
+ * 这里的 `npmTooLowMarker` 是纯函数（输出文本 + 环境 → 标记行或 null），不触碰任务/队列，
+ * 由调用方（task-queue.ts）负责把标记追加到任务输出；spawn 读 npm 版本是唯一副作用，独立可测。
+ */
+import { spawnSync } from 'node:child_process'
+
+/** npm arborist 内部崩溃特征：`Cannot read properties of null (reading 'edgesOut')`。 */
+export const NPM_CRASH_EDGES_OUT_RE = /Cannot read properties of null \(reading 'edgesOut'\)|edgesOut/i
+/** 该缺陷在 npm 11.6.0 起不再复现；低于此版本遇到 edgesOut 崩溃即判「本机 npm 版本过低」。 */
+export const NPM_MIN_VERSION = [11, 6, 0]
+
+/** 读本机 npm 版本（major.minor.patch）；npm 不在 PATH 或执行失败/超时时返回 null（不妄下结论）。 */
+export function npmVersionOf(env: NodeJS.ProcessEnv | undefined): [number, number, number] | null {
+  try {
+    const res = spawnSync('npm', ['-v'], { env, encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    if (res.error !== undefined || res.status !== 0) return null
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(res.stdout ?? '')
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
+  } catch {
+    return null
+  }
+}
+
+function belowMin(v: [number, number, number]): boolean {
+  for (let i = 0; i < NPM_MIN_VERSION.length; i++) {
+    if (v[i] < NPM_MIN_VERSION[i]) return true
+    if (v[i] > NPM_MIN_VERSION[i]) return false
+  }
+  return false
+}
+
+/**
+ * 安装失败输出含 npm arborist edgesOut 崩溃特征，且本机 npm 版本低于阈值时，返回
+ * `[npm-too-low] npm@X.Y.Z …` 标记行；否则返回 null。前端据此展示「本机 npm 版本过低」
+ * 的准确原因，避免该报错被误判成插件打包/分发问题。
+ */
+export function npmTooLowMarker(output: string, env?: NodeJS.ProcessEnv): string | null {
+  if (!NPM_CRASH_EDGES_OUT_RE.test(output)) return null
+  const v = npmVersionOf(env)
+  if (v === null || !belowMin(v)) return null
+  return `[npm-too-low] npm@${v.join('.')} — npm arborist crashed while resolving peer deps ('edgesOut'); local npm is below ${NPM_MIN_VERSION.join('.')}; upgrade npm (npm install -g npm@latest) and retry`
+}

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

@@ -1,10 +1,14 @@
 /**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
  * npm 包反查：git 分发不完整（缺构建产物/子模块）导致安装失败时，用 npm
  * registry 的搜索接口按 repository 地址反查该仓库对应的官方 npm 包。
  *
  * 这是通用机制，不针对任何具体插件：只要作者发布了 repository 指向该
  * GitHub 仓库的 npm 包（scope 名与 GitHub 用户名是否一致无所谓），就能命中，
- * 从而把「git 直装必败」的插件切换到 npm 通道安装。命中结果带内存缓存，
+ * 从而把 git 分发不完整的插件切换到 npm 通道安装。命中结果带内存缓存，
  * 避免同一会话内重复查询 registry。
  */
 import { get } from 'node:https'
@@ -19,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}

@@ -1,5 +1,9 @@
 /**
- * 安装前预检：对 `github:` 源的插件，检查其分发（codeload tarball）里是否
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 安装前预检：对 GitHub 源的插件，检查其分发（codeload tarball）里是否
  * 真的包含 package.json 声明的入口文件（main / exports["."].default）。
  * git 分发常不提交构建产物（lib/ 等），这类残缺包装完会让宿主重启加载插件树时
  * ERR_MODULE_NOT_FOUND 直接崩溃 —— 预检在动手安装前就把它们拦下，避免白装一次。
@@ -13,9 +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/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
@@ -23,12 +32,15 @@ export interface PreflightResult {
 }
 
 export async function preflightTarget(target: string): Promise<PreflightResult> {
-  const m = /^github:([^/]+)\/([^/]+)$/.exec(target)
-  if (m === null) return { ok: true, missing: null }
-  const [, owner, repo] = m
+  const source = githubRepoOf(target)
+  if (source === null) return { ok: true, missing: null }
+  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 }
@@ -58,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()
@@ -72,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}

@@ -1,4 +1,8 @@
 /**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
  * 后台安装/卸载任务队列：内存任务注册表 + FIFO 串行 worker + 子进程生命周期管理。
  * 每个任务一次 `dsh plugin --profile <profile> <action> <target>` 子进程，
  * 输出流式收集到任务上；卸载成功时尝试从运行中 loader 即时停用（见 loader.ts）。
@@ -8,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, 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>()
@@ -163,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：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
@@ -170,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) {
@@ -183,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
 }
@@ -196,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)
@@ -219,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 通道显示 github: 源）：失败提 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,
@@ -251,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),
@@ -268,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)
@@ -278,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(() => {
@@ -294,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())
         }
@@ -305,9 +362,8 @@ function spawnMutation(options: {
 
     child.once('exit', () => {
       // dsh 内部会 fork pnpm：pnpm 退出后仍攥着 stdout/stderr 管道时，
-      // close 事件永不到来（历史队列卡死根因——取消路径曾因此卡死，用整组 SIGKILL 解决；
-      // 自然失败路径没有兜底）。exit 后给 close 一段宽限，未按时触发则整组清理强制结束，
-      // 保证任务必然进入终态、后续排队任务自动启动。
+      // close 事件不会到来。exit 后给 close 一段宽限，未按时触发则整组清理强制结束，
+      // 确保任务进入终态、后续排队任务自动启动。
       exitWatch = setTimeout(() => {
         if (settled) return
         if (task && task.status !== 'cancelled') pushLine(task, '[stale pipe] force closing child')
@@ -321,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)
     })
@@ -332,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
+  })()
 }
 
 /**
@@ -385,8 +460,11 @@ export function verifyInstalledEntry(profile: string, target: string): { name: s
     return { name: null, missing: null }
   }
   const deps = (profilePkg?.dependencies ?? {}) as Record<string, string>
-  // target 自身是依赖名（npm 包），或通过 github: specifier 反查依赖名
-  const name = deps[target] !== undefined ? target : Object.keys(deps).find((k) => deps[k] === target)
+  // target 自身是依赖名（npm 包），或通过 Git specifier 反查依赖名
+  const targetRepo = githubRepoOf(target)?.toLowerCase()
+  const name = targetRepo !== undefined
+    ? Object.keys(deps).find((k) => githubRepoOf(deps[k])?.toLowerCase() === targetRepo)
+    : deps[target] !== undefined ? target : Object.keys(deps).find((k) => deps[k] === target)
   if (!name) return { name: null, missing: null }
   const pkgDir = join(profileDirectory(profile), 'node_modules', name)
   let entry: string | null = null
@@ -421,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
@@ -441,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')) {
@@ -457,15 +554,16 @@ 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)
-      if (keys.length === 0 && !options.target.startsWith('github:')) keys.push(options.target)
+    // 用重试后的最终结果判断：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) {
           options.task.status = 'running'
@@ -473,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)
@@ -493,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)
 }