dsh-plugin 1.1.1 → 1.2.0

package/lib/services/install/npm-check.js

@@ -0,0 +1,55 @@
+/**
+ * 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) {
+    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) {
+    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, env) {
+    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/lib/services/{npm-resolve.js → install/npm-resolve.js}

@@ -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';
@@ -16,21 +20,23 @@ const REQUEST_TIMEOUT_MS = 8000;
  * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
  * 返回 null 不代表仓库一定没有 npm 包，只代表本次未能确认 —— 调用方应保留
  * 原有错误路径，反查只是额外的一次尝试。
+ * @param registry - npm 镜像源地址（空串 = 官方 https://registry.npmjs.org）
  */
-export function resolveNpmPackage(repo) {
+export function resolveNpmPackage(repo, registry = '') {
     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) {
+function searchRepo(repo, registry) {
     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/lib/services/{preflight.js → install/preflight.js}

@@ -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,15 +17,22 @@ 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.js';
 const execFileAsync = promisify(execFile);
+/** 单次网络操作超时（ms）：git ls-remote / codeload 下载。网络不可达时不能无限挂起，
+ *  否则 `/install` 请求永远不返回、任务不入队、前端进度卡 0%。超时后放行（交给装后校验）。 */
+const PREFLIGHT_TIMEOUT_MS = 15_000;
 export async function preflightTarget(target) {
-    const m = /^github:([^/]+)\/([^/]+)$/.exec(target);
-    if (m === null)
+    const source = githubRepoOf(target);
+    if (source === null)
         return { ok: true, missing: null };
-    const [, owner, repo] = m;
+    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 {
@@ -55,13 +66,15 @@ export async function preflightTarget(target) {
 }
 function download(url, dest) {
     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();
@@ -69,7 +82,10 @@ function download(url, dest) {
                 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);
     });
 }
 /** 从 tarball 提取并解析一个 JSON 文件；文件不存在或解析失败返回 null。 */

package/lib/services/{task-queue.js → install/task-queue.js}

@@ -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）。
@@ -7,10 +11,12 @@ import { spawn } from 'node:child_process';
 import { readFileSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.js';
-import { cleanLine, estimateProgress } from './progress.js';
-import { removeLoadedEntry } from './loader.js';
-import { addPendingRestart, clearPendingRestart } from './pending-restart.js';
-import { addAllowBuildsKey, parseAllowBuildsKey, profileDirectory } from './profile.js';
+import { npmTooLowMarker } from './npm-check.js';
+import { cleanLine, estimateProgress } from '../profile/progress.js';
+import { removeLoadedEntry } from '../loader.js';
+import { addPendingRestart, clearPendingRestart } from '../profile/pending-restart.js';
+import { addAllowBuildsKey, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.js';
+import { appendLog } from '../log.js';
 /** In-memory task registry, keyed by task id. */
 const tasks = new Map();
 let nextTaskId = 1;
@@ -142,7 +148,7 @@ function stopChild(child) {
  * Progress is visible through `getTask(id)` / `activeTask()` until done.
  */
 export function startPluginMutation(options) {
-    const task = { 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 = { 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) {
@@ -155,6 +161,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;
 }
@@ -169,6 +184,36 @@ function pumpQueue() {
     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)
@@ -182,23 +227,34 @@ function pumpQueue() {
  * Never rejects; failures surface through the result / task state.
  */
 function spawnMutation(options) {
-    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) => new Promise((resolveOnce) => {
         let stdout = '';
         let stderr = '';
         let timedOut = false;
         let settled = false;
         let child;
         try {
-            child = spawn(invocation.file, args, {
+            child = spawn(invocation.file, attemptArgs, {
                 cwd: invocation.cwd,
                 env,
                 shell: invocation.useShell,
@@ -214,7 +270,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),
@@ -230,9 +286,8 @@ function spawnMutation(options) {
         let progressTimer;
         let exitWatch;
         let forceSettle;
-        // 唯一收尾入口：close / error / 兜底超时 三者只放行一次，
-        // 保证 runPluginMutation 必然 resolve、队列 worker 必然继续推进
-        const settle = (result) => {
+        // 唯一收尾入口：close / error / 兜底超时 三者只放行一次，确保任务持续推进
+        const settleOnce = (result) => {
             if (settled)
                 return;
             settled = true;
@@ -246,7 +301,7 @@ function spawnMutation(options) {
                 clearTimeout(forceSettle);
             if (task)
                 runningChildren.delete(task.id);
-            resolvePromise(result);
+            resolveOnce(result);
         };
         timer = setTimeout(() => {
             timedOut = true;
@@ -264,7 +319,7 @@ function spawnMutation(options) {
             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());
@@ -275,9 +330,8 @@ function spawnMutation(options) {
         child.stderr?.on('data', (chunk) => collect('stderr', chunk));
         child.once('exit', () => {
             // dsh 内部会 fork pnpm：pnpm 退出后仍攥着 stdout/stderr 管道时，
-            // close 事件永不到来（历史队列卡死根因——取消路径曾因此卡死，用整组 SIGKILL 解决；
-            // 自然失败路径没有兜底）。exit 后给 close 一段宽限，未按时触发则整组清理强制结束，
-            // 保证任务必然进入终态、后续排队任务自动启动。
+            // close 事件不会到来。exit 后给 close 一段宽限，未按时触发则整组清理强制结束，
+            // 确保任务进入终态、后续排队任务自动启动。
             exitWatch = setTimeout(() => {
                 if (settled)
                     return;
@@ -294,7 +348,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);
         });
@@ -304,46 +358,66 @@ 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');
                     }
                 }
+                pushLine(task, result.timedOut ? '[timed out]' : `[exit ${result.exitCode ?? '?'}]`);
             }
-            finally {
-                settle({ exitCode: code, timedOut, error: null, stdout, stderr });
-            }
-        });
-    });
+        }
+        return result;
+    })();
 }
 /**
  * 安装后校验已装包的入口文件（package.json 的 main / exports["."].default）是否真实存在。
@@ -360,8 +434,11 @@ export function verifyInstalledEntry(profile, target) {
         return { name: null, missing: null };
     }
     const deps = (profilePkg?.dependencies ?? {});
-    // 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);
@@ -395,6 +472,19 @@ function ignoredBuildKeys(output) {
         .map((s) => s.trim())
         .filter((s) => s !== '');
 }
+/** npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 把 [npm-too-low] 标记追加到任务输出，
+ *  前端据此展示「本机 npm 版本过低」的准确原因 —— 避免该报错被外层 ERR_PNPM_PREPARE_PACKAGE
+ *  误判成插件打包/分发问题、误导用户提 Issue。检测逻辑在独立的 npm-check.ts（本机 npm 环境职责）。 */
+function annotateNpmTooLow(result, options) {
+    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
@@ -405,8 +495,10 @@ function ignoredBuildKeys(output) {
  * Other failures fall through to the single-spawn result.
  */
 export async function runPluginMutation(options) {
-    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')) {
@@ -420,15 +512,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:'))
+        // 用重试后的最终结果判断：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) {
@@ -438,13 +531,14 @@ export async function runPluginMutation(options) {
                 }
                 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);
@@ -458,5 +552,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/lib/services/loader.js

@@ -1,7 +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
+ *
  * 运行中 loader 的读取与停用：卸载成功后对匹配条目做 live-disable，
  * 使卸载立即生效（刷新页面不再加载已卸载的 client bundle，也无需重启）。
  */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { profileDirectory } from './profile/profile.js';
 /** 运行中 loader 的全部条目（id + options.name），诊断用。 */
 export function dumpLoaderEntries(loader) {
     if (!loader)
@@ -12,6 +19,20 @@ export function dumpLoaderEntries(loader) {
     }
     return entries;
 }
+/**
+ * 判断某 npm 包名是否已加载进运行中 loader（宽匹配：条目名存在别名变体）。
+ * 官方 `ctx.loader.entries()` 遍历整棵树（reference.md §1.3），条目名 == 插件作者声明的名字。
+ * 安装完成但未重启时条目不在 loader → 返回 false，UI 据此标「待重启/未加载」。
+ */
+export function isEntryLoaded(loader, name) {
+    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 条目名由插件作者/工具写入，形式不可控，常见变体：
@@ -19,7 +40,8 @@ export function dumpLoaderEntries(loader) {
  *  - 去 `@` 前缀：`scope/widget`
  *  - 去 scope 的短名：`widget`
  *  - scope 分隔符变 `-`：`scope-widget`
- * 因此归一化后比较全串与短名两个维度。profile 内包名唯一，宽松匹配不会误伤其它包。
+ *  - 包内模块路径：`widget/extensions/dsh/index.js`（bundle patch 的 name 常写成模块路径）
+ * 因此归一化后比较全串、短名、路径前缀三个维度。profile 内包名唯一，宽松匹配不会误伤其它包。
  */
 function nameMatches(entryName, target) {
     if (!entryName)
@@ -41,6 +63,13 @@ function nameMatches(entryName, target) {
     //    目标短名 `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;
 }
 /**
@@ -103,3 +132,33 @@ export async function removeLoadedEntry(loader, name) {
     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, name) {
+    // 1) profile 级 bundles 清单：包名在清单里 → 宿主启动会加载它
+    try {
+        const profilePkg = JSON.parse(readFileSync(join(profileDirectory(profile), 'package.json'), 'utf8'));
+        if (Array.isArray(profilePkg.dsh?.profile?.bundles)) {
+            if (profilePkg.dsh.profile.bundles.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'));
+        if (pkg.dsh)
+            return true;
+        if (Array.isArray(pkg.keywords)) {
+            if (pkg.keywords.some((k) => typeof k === 'string' && /^(?:dsh|dsh-plugin)$/i.test(k)))
+                return true;
+        }
+    }
+    catch { /* 包缺失 / 无 package.json → 不是 dsh 插件 */ }
+    return false;
+}