dsh-plugin 1.1.2 → 1.2.1

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/{profile.js → profile/profile.js}

@@ -9,7 +9,7 @@
 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');
@@ -26,6 +26,34 @@ export function githubTarget(repo) {
         return null;
     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')

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

@@ -7,7 +7,7 @@
  * 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}

@@ -23,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';
@@ -51,6 +53,7 @@ export interface QueueItem {
         target: string;
         timeoutMs?: number;
         env?: NodeJS.ProcessEnv;
+        globalNpm?: string[];
     };
 }
 /**

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

@@ -5,7 +5,7 @@
  *
  * 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  公共类型与常量
@@ -15,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, githubRepoOf, 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>;

package/lib/types/services/loader.d.ts

@@ -1,11 +1,3 @@
-/**
- * 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，也无需重启）。
- */
 /**
  * 运行中 loader 的最小接口：卸载成功后即时移除条目用。
  * 对应官方 `ctx.loader`（cordis-plugin-loader 的 Loader 服务）的读取面与移除面。
@@ -35,6 +27,12 @@ export declare function dumpLoaderEntries(loader: LoaderHandle | undefined): Arr
     id: string;
     name?: string;
 }>;
+/**
+ * 判断某 npm 包名是否已加载进运行中 loader（宽匹配：条目名存在别名变体）。
+ * 官方 `ctx.loader.entries()` 遍历整棵树（reference.md §1.3），条目名 == 插件作者声明的名字。
+ * 安装完成但未重启时条目不在 loader → 返回 false，UI 据此标「待重启/未加载」。
+ */
+export declare function isEntryLoaded(loader: LoaderHandle | undefined, name: string): boolean;
 /**
  * 卸载成功后从运行中 loader 停用指定包的条目。做法：按 name 扫描
  * `loader.entries()`（含嵌套子树），对每个匹配条目
@@ -47,3 +45,11 @@ export declare function dumpLoaderEntries(loader: LoaderHandle | undefined): Arr
  * 宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
  */
 export declare function removeLoadedEntry(loader: LoaderHandle, name: string): Promise<boolean>;
+/**
+ * 判断某已安装包是否是真正的 dsh 插件（宿主会加载 / 值得提示「待重启」）：
+ *  1) 包名已写进 profile 的 `dsh.profile.bundles`（宿主启动时按清单加载）；
+ *  2) 或包内 package.json 声明了 dsh 配置（`dsh.bundle` / `dsh.profile` 等）或 dsh 相关 keywords。
+ * 两者都满足不了（如 GitHub 官方示例仓库 octocat/Hello-World）说明它不是 dsh 插件，
+ * 装上也不会被宿主加载——UI 据此不再提示「待重启」，避免误导用户反复重启一个不会生效的东西。
+ */
+export declare function isDshPlugin(profile: string, name: string): boolean;

package/lib/types/services/log.d.ts

@@ -0,0 +1,49 @@
+export type LogCategory = 'install' | 'uninstall' | 'update' | 'diagnostics' | 'settings' | 'system';
+export type LogLevel = 'debug' | 'info' | 'success' | 'warn' | 'error';
+export interface LogEntry {
+    /** 毫秒时间戳 */
+    at: number;
+    level: LogLevel;
+    category: LogCategory;
+    /** 机器可读事件码，如 install.start / settings.update */
+    event: string;
+    /** 人类可读描述 */
+    message: string;
+}
+/** 日志保留上限：超过后在读取时裁剪为最近 MAX_LOG_LINES 条 */
+export declare const MAX_LOG_LINES = 2000;
+export interface ReadLogOptions {
+    /** 分页偏移（过滤后倒序） */
+    offset?: number;
+    limit?: number;
+    category?: LogCategory | 'all';
+    level?: LogLevel | 'all';
+    /** 关键词：大小写不敏感，匹配事件码或描述 */
+    query?: string;
+}
+export interface ReadLogResult {
+    /** 倒序（最新在前） */
+    entries: LogEntry[];
+    /** 过滤后的总条数（分页前） */
+    total: number;
+}
+/**
+ * 把用户填写的日志位置覆盖解析成实际文件路径：
+ * 以 .log 结尾视为文件本身，否则视为目录并在其中写 hub.log；相对路径按当前目录归一化。
+ */
+export declare function customLogFile(override: string): string;
+/**
+ * 真正默认的日志文件路径：`~/.dsh/profiles/<profile>/hub.log`（不受设置覆盖影响）。
+ * 弹窗「恢复默认」、目录选择器起点等需要「未自定义时的位置」都从这里取 ——
+ * 不同机器/平台（用户主目录不同）这个值都不同，必须动态计算而非写死。
+ */
+export declare function defaultLogFilePath(profile: string): string;
+/**
+ * 当前生效的日志文件路径：设置里填了 logPath 用自定义位置（目录或文件），
+ * 否则默认 `~/.dsh/profiles/<profile>/hub.log`。默认位置永远合法可用，无需用户干预。
+ */
+export declare function logFilePath(profile: string): string;
+/** 追加一条系统日志（JSONL 一行一条）。 */
+export declare function appendLog(profile: string, entry: LogEntry): void;
+/** 读取系统日志（按时间正序，最新在末尾），超上限就地裁剪；支持过滤与分页。 */
+export declare function readLog(profile: string, opts?: ReadLogOptions): ReadLogResult;

package/lib/types/services/probe.d.ts

@@ -0,0 +1,30 @@
+export interface ProbeResult {
+    /** 是否可达（HTTP 状态码 100–399） */
+    ok: boolean;
+    /** 毫秒耗时；失败为 null */
+    ms: number | null;
+    /** HTTP 状态码；失败为 null */
+    status: number | null;
+}
+/**
+ * 操作系统级代理（macOS 系统网络设置 / Windows Internet 设置）。
+ * Node 内置 http(s) 不读系统代理，浏览器挂的代理 Node 看不见 —— 这里读出来
+ * 作为默认代理，保证「浏览器能开、安装/诊断就能通」。
+ * Linux 没有统一的系统代理入口，返回 null（交给环境变量 / 设置里的代理）。
+ */
+export declare function systemProxy(): string | null;
+/**
+ * 探测一个 HTTPS 目标：proxy 非空注入给 curl 子进程走代理，否则直连。
+ * 供系统诊断 /diagnostics 使用；目标 URL 非法返回不可达。
+ */
+export declare function probeUrl(url: string, proxy: string, timeoutMs: number): Promise<ProbeResult>;
+/**
+ * curl 子进程抓取响应体（与 probeUrl 同一套代理 env 注入）。
+ * 供服务端 /catalog 代理路由使用：目录/统计数据经此拉到服务端再转给浏览器，
+ * 使「目录数据请求走设置里的代理」与 npm / git 安装通道口径一致。
+ * 失败（curl 不存在 / 连接失败 / 超时 / 非零退出）时 ok=false，全程不抛错。
+ */
+export declare function fetchViaCurl(url: string, proxy: string, timeoutMs: number): Promise<{
+    ok: boolean;
+    body: string;
+}>;

package/lib/types/services/{pending-restart.d.ts → profile/pending-restart.d.ts}

@@ -5,7 +5,7 @@
  *
  * 待重启列表的内存态管理（宿主进程一重启自然清空）。
  */
-import type { PendingRestart } from './install-types.ts';
+import type { PendingRestart } from '../install/install-types.ts';
 /**
  * 登记一条待重启记录（同一目标去重）。
  * - 卸载：目标刚装完未重启（已有待重启记录）→ 宿主从未加载过它，卸完磁盘已干净、

package/lib/types/services/{profile.d.ts → profile/profile.d.ts}

@@ -4,6 +4,8 @@ export declare function readProfileArg(fallback?: string): string;
 export declare function profileDirectory(profile: string): string;
 /** Build a safe explicit HTTPS Git target, or null when the repo is unsafe. */
 export declare function githubTarget(repo: string): string | null;
+export declare function installTargetOf(value: string): string;
+export declare function globalNpmPackagesOf(value: string): string[] | null;
 /** Extract an owner/repo identity from a catalog value or an installed Git spec. */
 export declare function githubRepoOf(value: string): string | null;
 /** Validate an npm package name (uninstall target grammar). */