dsh-plugin 1.1.1 → 1.2.0

package/lib/services/log.js

@@ -0,0 +1,138 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 系统日志：把关键操作以 JSONL 追加到 `~/.dsh/profiles/<profile>/hub.log`。
+ *
+ * 每一条日志 = 级别（严重程度）× 类别（功能域）：
+ *   level    debug / info / success / warn / error —— 区分报错与正常
+ *   category install（安装）/ uninstall（卸载）/ update（更新，预留）/
+ *            diagnostics（诊断）/ settings（设置）/ system（系统）
+ * 查看器按级别与类别过滤，就能针对性排查「安装时哪步不兼容」还是
+ * 「卸载时哪步不兼容」。读取时超行数上限就地裁剪，防文件无限膨胀；
+ * 写入失败绝不影响主流程（日志是辅助设施）。
+ */
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { loadSettings } from './settings.js';
+/** 日志保留上限：超过后在读取时裁剪为最近 MAX_LOG_LINES 条 */
+export const MAX_LOG_LINES = 2000;
+const CATEGORIES = ['install', 'uninstall', 'update', 'diagnostics', 'settings', 'system'];
+function profileDirectory(profile) {
+    return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', profile);
+}
+/** `~` 开头路径展开为用户主目录（Node 不自动展开）。 */
+function expandHome(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\'))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+/**
+ * 把用户填写的日志位置覆盖解析成实际文件路径：
+ * 以 .log 结尾视为文件本身，否则视为目录并在其中写 hub.log；相对路径按当前目录归一化。
+ */
+export function customLogFile(override) {
+    const trimmed = override.trim();
+    const expanded = expandHome(trimmed);
+    const file = /\.log$/i.test(expanded) ? expanded : join(expanded, 'hub.log');
+    return resolve(file);
+}
+/**
+ * 真正默认的日志文件路径：`~/.dsh/profiles/<profile>/hub.log`（不受设置覆盖影响）。
+ * 弹窗「恢复默认」、目录选择器起点等需要「未自定义时的位置」都从这里取 ——
+ * 不同机器/平台（用户主目录不同）这个值都不同，必须动态计算而非写死。
+ */
+export function defaultLogFilePath(profile) {
+    return join(profileDirectory(profile), 'hub.log');
+}
+/**
+ * 当前生效的日志文件路径：设置里填了 logPath 用自定义位置（目录或文件），
+ * 否则默认 `~/.dsh/profiles/<profile>/hub.log`。默认位置永远合法可用，无需用户干预。
+ */
+export function logFilePath(profile) {
+    const custom = loadSettings(profile).logPath?.trim() ?? '';
+    return custom === '' ? defaultLogFilePath(profile) : customLogFile(custom);
+}
+/** 追加一条系统日志（JSONL 一行一条）。 */
+export function appendLog(profile, entry) {
+    try {
+        const file = logFilePath(profile);
+        mkdirSync(dirname(file), { recursive: true });
+        appendFileSync(file, `${JSON.stringify(entry)}\n`);
+    }
+    catch {
+        // 日志失败不阻断主流程
+    }
+}
+/** 兼容旧格式：早期无 category（level 用 info/ok/fail/warn），归一化到新版。 */
+function normalize(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const e = raw;
+    if (typeof e.at !== 'number')
+        return null;
+    let level = 'info';
+    if (e.level === 'ok' || e.level === 'success')
+        level = 'success';
+    else if (e.level === 'fail' || e.level === 'error')
+        level = 'error';
+    else if (e.level === 'warn')
+        level = 'warn';
+    else if (e.level === 'debug')
+        level = 'debug';
+    const category = CATEGORIES.includes(e.category) ? e.category : 'system';
+    return {
+        at: e.at,
+        level,
+        category,
+        event: typeof e.event === 'string' ? e.event : '',
+        message: typeof e.message === 'string' ? e.message : '',
+    };
+}
+/** 读取系统日志（按时间正序，最新在末尾），超上限就地裁剪；支持过滤与分页。 */
+export function readLog(profile, opts = {}) {
+    const { offset = 0, limit = 200 } = opts;
+    try {
+        const file = logFilePath(profile);
+        const raw = readFileSync(file, 'utf8');
+        let lines = raw.split('\n').filter((l) => l.trim() !== '');
+        if (lines.length > MAX_LOG_LINES) {
+            lines = lines.slice(-MAX_LOG_LINES);
+            writeFileSync(file, `${lines.join('\n')}\n`);
+        }
+        // 正序解析后倒序（最新在前）再过滤分页
+        let entries = [];
+        for (const line of lines) {
+            let parsed = null;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const entry = normalize(parsed);
+            if (entry !== null)
+                entries.push(entry);
+        }
+        entries.reverse();
+        const needle = opts.query?.trim().toLowerCase() ?? '';
+        if (opts.category !== undefined && opts.category !== 'all') {
+            entries = entries.filter((e) => e.category === opts.category);
+        }
+        if (opts.level !== undefined && opts.level !== 'all') {
+            entries = entries.filter((e) => e.level === opts.level);
+        }
+        if (needle !== '') {
+            entries = entries.filter((e) => e.event.toLowerCase().includes(needle) || e.message.toLowerCase().includes(needle));
+        }
+        const total = entries.length;
+        return { entries: entries.slice(offset, offset + limit), total };
+    }
+    catch {
+        return { entries: [], total: 0 };
+    }
+}

package/lib/services/probe.js

@@ -0,0 +1,157 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 连通性探测：对单个 HTTPS 目标发 GET，测速并返回 HTTP 状态码。
+ *
+ * 实现方式：spawn 系统 curl 子进程并注入代理环境变量（HTTP_PROXY/HTTPS_PROXY），
+ * 与安装通道（pnpm/git 子进程）使用同一套代理环境。
+ *
+ * 代理来源由调用方决定（routes.ts）：设置里的代理 → 系统代理 → 环境变量 → 直连。
+ * systemProxy() 读取操作系统级代理（macOS scutil / Windows 注册表），
+ * 使系统代理对 Node 进程可见。
+ */
+import { spawn, spawnSync } from 'node:child_process';
+const probeFail = () => ({ ok: false, ms: null, status: null });
+/** macOS 系统代理：scutil --proxy 输出里的 HTTP(S) 代理；未开启返回 null。 */
+function macSystemProxy() {
+    try {
+        const out = spawnSync('scutil', ['--proxy'], { encoding: 'utf8', timeout: 1500 });
+        if (out.status !== 0)
+            return null;
+        const txt = out.stdout ?? '';
+        const val = (key) => {
+            const m = new RegExp(`^\\s*${key}\\s*:\\s*(.+)$`, 'm').exec(txt);
+            const v = m?.[1]?.trim();
+            return v !== undefined && v !== '' ? v : undefined;
+        };
+        const enabled = (val('HTTPSEnable') ?? val('HTTPEnable')) === '1';
+        const host = val('HTTPSProxy') ?? val('HTTPProxy');
+        if (!enabled || host === undefined)
+            return null;
+        const port = val('HTTPSPort') ?? val('HTTPPort') ?? '80';
+        if (!/^\d+$/.test(port))
+            return null;
+        return `http://${host}:${port}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Windows 系统代理：WinINET Internet 设置注册表；未开启返回 null。 */
+function winSystemProxy() {
+    try {
+        const key = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings';
+        const enable = spawnSync('reg', ['query', key, '/v', 'ProxyEnable'], { encoding: 'utf8', timeout: 1500 });
+        const server = spawnSync('reg', ['query', key, '/v', 'ProxyServer'], { encoding: 'utf8', timeout: 1500 });
+        if (!/0x1/i.test(enable.stdout ?? ''))
+            return null;
+        const m = /([^:\s=]+):(\d+)/.exec(server.stdout ?? '');
+        if (m === null)
+            return null;
+        return `http://${m[1]}:${m[2]}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 操作系统级代理（macOS 系统网络设置 / Windows Internet 设置）。
+ * Node 内置 http(s) 不读系统代理，浏览器挂的代理 Node 看不见 —— 这里读出来
+ * 作为默认代理，保证「浏览器能开、安装/诊断就能通」。
+ * Linux 没有统一的系统代理入口，返回 null（交给环境变量 / 设置里的代理）。
+ */
+export function systemProxy() {
+    if (process.platform === 'darwin')
+        return macSystemProxy();
+    if (process.platform === 'win32')
+        return winSystemProxy();
+    return null;
+}
+/**
+ * curl 子进程探测：spawn curl -s -w '%{http_code}' 并注入代理 env。
+ * curl 读 HTTP_PROXY/HTTPS_PROXY 是原生行为，与 pnpm/git 安装通道同一套代理口径；
+ * 失败（curl 不存在 / 连接失败 / 超时）都归为不可达，全程不抛错。
+ */
+function curlProbe(url, proxy, timeoutMs) {
+    return new Promise((resolve) => {
+        const started = Date.now();
+        const env = { ...process.env };
+        if (proxy !== '') {
+            env.HTTP_PROXY = proxy;
+            env.HTTPS_PROXY = proxy;
+            env.http_proxy = proxy;
+            env.https_proxy = proxy;
+        }
+        const discard = process.platform === 'win32' ? 'NUL' : '/dev/null';
+        const child = spawn('curl', [
+            '-s', '-o', discard, '-w', '%{http_code}',
+            '--max-time', String(Math.max(1, Math.round(timeoutMs / 1000))),
+            url,
+        ], { env });
+        let code = '';
+        child.stdout.on('data', (c) => { code += c.toString(); });
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        child.on('error', () => finish(probeFail()));
+        child.on('close', () => {
+            const status = /^\d+$/.test(code.trim()) ? Number(code.trim()) : null;
+            finish({ ok: status !== null && status >= 100 && status < 400, ms: Date.now() - started, status });
+        });
+        // 超时兜底：curl --max-time 到点自行退出，此处再设一个进程级超时防止悬挂
+        const timer = setTimeout(() => { child.kill(); finish(probeFail()); }, timeoutMs + 1000);
+    });
+}
+/**
+ * 探测一个 HTTPS 目标：proxy 非空注入给 curl 子进程走代理，否则直连。
+ * 供系统诊断 /diagnostics 使用；目标 URL 非法返回不可达。
+ */
+export function probeUrl(url, proxy, timeoutMs) {
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return Promise.resolve(probeFail());
+    }
+    return curlProbe(target.href, proxy, timeoutMs);
+}
+/**
+ * curl 子进程抓取响应体（与 probeUrl 同一套代理 env 注入）。
+ * 供服务端 /catalog 代理路由使用：目录/统计数据经此拉到服务端再转给浏览器，
+ * 使「目录数据请求走设置里的代理」与 npm / git 安装通道口径一致。
+ * 失败（curl 不存在 / 连接失败 / 超时 / 非零退出）时 ok=false，全程不抛错。
+ */
+export function fetchViaCurl(url, proxy, timeoutMs) {
+    return new Promise((resolve) => {
+        const env = { ...process.env };
+        if (proxy !== '') {
+            env.HTTP_PROXY = proxy;
+            env.HTTPS_PROXY = proxy;
+            env.http_proxy = proxy;
+            env.https_proxy = proxy;
+        }
+        const child = spawn('curl', ['-s', '--max-time', String(Math.max(1, Math.round(timeoutMs / 1000))), url], { env });
+        let body = '';
+        child.stdout.on('data', (c) => { body += c.toString(); });
+        let done = false;
+        const finish = (ok) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve({ ok, body });
+        };
+        child.on('error', () => finish(false));
+        child.on('close', (code) => finish(code === 0));
+        // 超时兜底：curl --max-time 到点自行退出，此处再设一个进程级超时防止悬挂
+        const timer = setTimeout(() => { child.kill(); finish(false); }, timeoutMs + 1000);
+    });
+}

package/lib/services/{installed-versions.js → profile/installed-versions.js}

@@ -1,8 +1,12 @@
 /**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
  * Installed-plugin version tracking.
  *
  * The installed table (`readInstalled` in routes.ts) only knows the manifest
- * spec of each dependency (`github:<owner>/<repo>`), which carries no version.
+ * spec of each Git dependency, which carries no version.
  * To let the Plugin Hub tell "an update is available", we record the catalog
  * signal present at install time into a small per-profile JSON file, then
  * compare it against the catalog's current signal later.

package/lib/services/{pending-restart.js → profile/pending-restart.js}

@@ -2,7 +2,7 @@ const pendingRestarts = [];
 /**
  * 登记一条待重启记录（同一目标去重）。
  * - 卸载：目标刚装完未重启（已有待重启记录）→ 宿主从未加载过它，卸完磁盘已干净、
- *   loader 无残留，无需再提醒重启，直接移除该条；否则（此前已被宿主加载过）登记「卸载后待重启清理」。
+ *   loader 无残留，无需再提醒重启，直接移除该条；否则（已被宿主加载过）登记「卸载后待重启清理」。
  * - 安装：已有记录则刷新为安装语义（如卸载后未重启又重装），否则新登记。
  */
 export function addPendingRestart(target, kind) {

package/lib/services/{profile.js → profile/profile.js}

@@ -1,11 +1,15 @@
 /**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
  * 宿主 profile 与目标校验工具：解析当前 profile、目录定位、安装目标语法校验，
  * 以及 pnpm allowBuilds 白名单的写入（失败恢复路径）。
  */
 import { readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { PACKAGE_RE, REPO_RE } from './install-types.js';
+import { PACKAGE_RE, REPO_RE } from '../install/install-types.js';
 /** Resolve the active profile from the booted CLI args, falling back to `web`. */
 export function readProfileArg(fallback = 'web') {
     const index = process.argv.indexOf('--profile');
@@ -16,11 +20,62 @@ export function readProfileArg(fallback = 'web') {
 export function profileDirectory(profile) {
     return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', profile);
 }
-/** Build a safe `github:<owner>/<repo>` target, or null when the repo is unsafe. */
+/** Build a safe explicit HTTPS Git target, or null when the repo is unsafe. */
 export function githubTarget(repo) {
     if (typeof repo !== 'string' || !REPO_RE.test(repo))
         return null;
-    return `github:${repo}`;
+    return `git+https://github.com/${repo}.git`;
+}
+/**
+ * DSH 命令行前缀（`dsh plugin [--profile|-p <p>] add <target>`）—— 提取其中的安装目标；
+ * 非命令输入原样返回。兼容「直接粘贴完整命令」（防用户输错）：--profile 段可选，
+ * 支持 `-p` 简写与 `--profile=web` 等号形式，命令大小写不敏感。
+ */
+const DSH_PLUGIN_CMD_RE = /^dsh\s+plugin\s+(?:(?:--profile|-p)(?:=|\s+)\S+\s*)?add\s+(.+)$/i;
+export function installTargetOf(value) {
+    const input = typeof value === 'string' ? value.trim() : '';
+    const match = DSH_PLUGIN_CMD_RE.exec(input);
+    return match !== null ? match[1].trim() : input;
+}
+/**
+ * npm 全局安装命令（官方 README 的 `npm install -g <pkgs>`，如 dsh-tui 的安装命令）——
+ * 提取 -g 之后的包列表。支持 `npm install|i` 与 `-g|--global`；任一包名非法（或格式
+ * 不匹配）返回 null，由调用方按「不支持的目标」处理。与客户端 CustomInstallView 同口径。
+ */
+const NPM_GLOBAL_CMD_RE = /^npm\s+(?:install|i)\s+(?:-g|--global)\s+(.+)$/i;
+export function globalNpmPackagesOf(value) {
+    const input = typeof value === 'string' ? value.trim() : '';
+    const match = NPM_GLOBAL_CMD_RE.exec(input);
+    if (match === null)
+        return null;
+    const packages = match[1].trim().split(/\s+/).filter((p) => p !== '');
+    // 包名逐个校验 + 拒绝以 - 开头的 token（npm 会把 --xxx 当参数而非包名，防注入任意 CLI 参数）
+    if (packages.length === 0 || packages.some((p) => !validPackageName(p) || p.startsWith('-')))
+        return null;
+    return packages;
+}
+/** Extract an owner/repo identity from a catalog value or an installed Git spec. */
+export function githubRepoOf(value) {
+    if (typeof value !== 'string')
+        return null;
+    const input = value.trim();
+    if (REPO_RE.test(input))
+        return input;
+    const patterns = [
+        /^github:([^/]+)\/([^/]+)$/i,
+        /^(?:git\+)?https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:[?#].*)?$/i,
+        /^(?:git\+)?ssh:\/\/(?:git@)?github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:[?#].*)?$/i,
+        /^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?(?:[?#].*)?$/i,
+    ];
+    for (const pattern of patterns) {
+        const match = pattern.exec(input);
+        if (match === null)
+            continue;
+        const repo = `${match[1]}/${match[2]}`;
+        if (REPO_RE.test(repo))
+            return repo;
+    }
+    return null;
 }
 /** Validate an npm package name (uninstall target grammar). */
 export function validPackageName(name) {
@@ -28,7 +83,7 @@ export function validPackageName(name) {
 }
 /**
  * The exact `allowBuilds` key pnpm printed in its
- * `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` hint. For `github:` installs pnpm
+ * `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` hint. For Git installs pnpm
  * matches against `name@<resolved fetch URL>` — the URL it actually fetches,
  * e.g. `https://codeload.github.com/<owner>/<repo>/tar.gz/<commit>` — not the
  * `git+ssh://`/branch spec. A bare name or a `git+` spec does not match, so

package/lib/services/{progress.js → profile/progress.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
+ *
  * Pure progress-estimation helpers shared by the install runner.
  *
  * The dsh CLI wraps pnpm, which refreshes its `Progress: …` line in place

package/lib/services/settings.js

@@ -0,0 +1,60 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Hub settings persistence: one `hub-settings.json` per active profile
+ * (next to pnpm-workspace.yaml). All fields optional; missing keys fall
+ * back to DEFAULT_SETTINGS so old files stay readable as new options land.
+ */
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { profileDirectory } from './profile/profile.js';
+export const DEFAULT_SETTINGS = {
+    checkUpdatesOnStart: true,
+    npmRegistry: '',
+    proxy: '',
+    enableNpmInstall: true,
+    enableGitInstall: true,
+    enableDshInstall: true,
+    logPath: '',
+};
+export function settingsFile(profile) {
+    return join(profileDirectory(profile), 'hub-settings.json');
+}
+/** 读取当前 profile 的设置；文件缺失/损坏时回退默认值（只读路径绝不抛错）。 */
+export function loadSettings(profile) {
+    try {
+        const raw = JSON.parse(readFileSync(settingsFile(profile), 'utf8'));
+        return {
+            ...DEFAULT_SETTINGS,
+            ...(typeof raw === 'object' && raw !== null ? raw : {}),
+        };
+    }
+    catch {
+        return { ...DEFAULT_SETTINGS };
+    }
+}
+/** 合并并持久化设置（部分更新），返回合并后的完整设置。 */
+export function saveSettings(profile, patch) {
+    const next = { ...loadSettings(profile), ...patch };
+    const file = settingsFile(profile);
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`);
+    }
+    catch {
+        // 持久化失败不阻断本次会话：内存值仍生效，下次写入再试
+    }
+    return next;
+}
+/** 重置为默认设置：删除设置文件，下次读取全部回退默认值（陈旧/白名单外键一并清除）。 */
+export function resetSettings(profile) {
+    try {
+        rmSync(settingsFile(profile), { force: true });
+    }
+    catch {
+        // 删除失败不阻断：loadSettings 仍回退默认值
+    }
+    return { ...DEFAULT_SETTINGS };
+}

package/lib/types/http/routes.d.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { readProfileArg, type LoaderHandle } from '../services/install.ts';
+import { readProfileArg, type LoaderHandle } from '../services/install/install.ts';
 export interface WebRoute {
     kind: 'exact';
     path: string;

package/lib/types/index.d.ts

@@ -1,9 +1,13 @@
 /**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
  * dsh-plugin host entry: mounts the Plugin Hub HTTP routes once the host
  * web server service is available. The browser bundle (src/client) talks to
  * these same-origin routes to perform real installs from inside the app.
  */
-import { type LoaderHandle } from './services/install.ts';
+import { type LoaderHandle } from './services/install/install.ts';
 import { type WebServerService } from './http/routes.ts';
 export declare const name = "dsh-plugin";
 export interface Config {

package/lib/types/services/{install-types.d.ts → install/install-types.d.ts}

@@ -1,4 +1,10 @@
-/** 安装/卸载运行时的公共类型与常量（无依赖，供各服务模块复用）。 */
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 安装/卸载运行时的公共类型与常量（无依赖，供各服务模块复用）。
+ */
 /** 一个 pnpm 安装子进程的结果快照。 */
 export interface InstallResult {
     exitCode: number | null;
@@ -9,7 +15,7 @@ export interface InstallResult {
 }
 export interface InstallTask {
     id: number;
-    /** 操作目标：`github:<owner>/<repo>`（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
+    /** 操作目标：显式 HTTPS Git URL（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
     target: string;
     /** 展示用目标（owner/repo）：npm 安装时 target 是包名，前端恢复用此字段显示仓库名，保持用户无感知 */
     displayTarget?: string;
@@ -17,6 +23,8 @@ export interface InstallTask {
      *  失败提 Issue 时如实贴给作者，作者据此反推正确的 npm 包名（组织 scope 与 GitHub 用户名不一致时
      *  仅凭仓库名猜不到，作者看到我们查过/试过的命令就能直接指认）。 */
     attempts: string[];
+    /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时任务执行全局 npm 安装，不进任何 profile */
+    globalNpm?: string[];
     action: 'add' | 'remove';
     /** 队列语义：pending 排队中 / running 执行中 / done / failed / cancelled（用户取消） */
     status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled';
@@ -45,6 +53,7 @@ export interface QueueItem {
         target: string;
         timeoutMs?: number;
         env?: NodeJS.ProcessEnv;
+        globalNpm?: string[];
     };
 }
 /**
@@ -52,14 +61,14 @@ export interface QueueItem {
  * 它自然清空，正好等于「重启后提醒消失」的语义，无需任何重启探测。
  */
 export interface PendingRestart {
-    /** `github:<owner>/<repo>` 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
+    /** Git 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
     target: string;
     /** 待重启语义：install 装完等挂载生效 / uninstall 卸完等清理 loader 残留 */
     kind: 'install' | 'uninstall';
     /** 任务完成时刻（epoch ms） */
     at: number;
 }
-/** Grammar of an accepted `github:<owner>/<repo>` install target. */
+/** Grammar of a catalog GitHub repository identity (`owner/repo`). */
 export declare const REPO_RE: RegExp;
 /** Grammar of an npm package name (used for uninstall targets). */
 export declare const PACKAGE_RE: RegExp;

package/lib/types/services/{install.d.ts → install/install.d.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/lib/types/services/install/npm-check.d.ts

@@ -0,0 +1,12 @@
+/** npm arborist 内部崩溃特征：`Cannot read properties of null (reading 'edgesOut')`。 */
+export declare const NPM_CRASH_EDGES_OUT_RE: RegExp;
+/** 该缺陷在 npm 11.6.0 起不再复现；低于此版本遇到 edgesOut 崩溃即判「本机 npm 版本过低」。 */
+export declare const NPM_MIN_VERSION: number[];
+/** 读本机 npm 版本（major.minor.patch）；npm 不在 PATH 或执行失败/超时时返回 null（不妄下结论）。 */
+export declare function npmVersionOf(env: NodeJS.ProcessEnv | undefined): [number, number, number] | null;
+/**
+ * 安装失败输出含 npm arborist edgesOut 崩溃特征，且本机 npm 版本低于阈值时，返回
+ * `[npm-too-low] npm@X.Y.Z …` 标记行；否则返回 null。前端据此展示「本机 npm 版本过低」
+ * 的准确原因，避免该报错被误判成插件打包/分发问题。
+ */
+export declare function npmTooLowMarker(output: string, env?: NodeJS.ProcessEnv): string | null;

package/lib/types/services/{npm-resolve.d.ts → install/npm-resolve.d.ts}

@@ -2,5 +2,6 @@
  * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
  * 返回 null 不代表仓库一定没有 npm 包，只代表本次未能确认 —— 调用方应保留
  * 原有错误路径，反查只是额外的一次尝试。
+ * @param registry - npm 镜像源地址（空串 = 官方 https://registry.npmjs.org）
  */
-export declare function resolveNpmPackage(repo: string): Promise<string | null>;
+export declare function resolveNpmPackage(repo: string, registry?: string): Promise<string | null>;

package/lib/types/services/{task-queue.d.ts → install/task-queue.d.ts}

@@ -1,5 +1,5 @@
 import type { InstallResult, InstallTask } from './install-types.ts';
-import type { LoaderHandle } from './loader.ts';
+import type { LoaderHandle } from '../loader.ts';
 /** Snapshot of a task (keeps the live object untouched by consumers). */
 export declare function getTask(id: number): InstallTask | undefined;
 export interface ActiveTaskInfo {
@@ -42,6 +42,8 @@ export declare function startPluginMutation(options: {
     target: string;
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
+    /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
+    globalNpm?: string[];
     /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
     displayTarget?: string;
     /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
@@ -79,4 +81,6 @@ export declare function runPluginMutation(options: {
     displayTarget?: string;
     /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
     uninstallLoader?: LoaderHandle;
+    /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
+    globalNpm?: string[];
 }): Promise<InstallResult>;