dsh-plugin 1.6.5 → 1.6.6

package/lib/http/settings.js

@@ -0,0 +1,77 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Settings routes: read/write the hub settings and reset them to defaults.
+ */
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadSettings, saveSettings, resetSettings } from '../services/settings.js';
+import { appendLog, customLogFile } from '../services/log.js';
+import { readJsonBody, requireTrustedPost, sendJson } from './shared.js';
+export function registerSettingsRoutes(webServer, profile) {
+    return [
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/settings',
+            // GET 读 / POST 写：webServer.register 按 (kind, path) 唯一，多方法必须合并到同一个 handler 按 method 分派
+            handler: async (request, response) => {
+                if (request.method === 'GET') {
+                    sendJson(response, 200, loadSettings(profile));
+                    return;
+                }
+                if (!requireTrustedPost(request, response))
+                    return;
+                try {
+                    const body = await readJsonBody(request);
+                    // 白名单字段：只接受已知设置项，防客户端把任意键写进文件
+                    const patch = {};
+                    const source = typeof body === 'object' && body !== null ? body : {};
+                    for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'enableGitInstall', 'enableDshInstall', 'npmRegistry', 'proxy', 'logPath']) {
+                        if (source[key] !== undefined)
+                            patch[key] = source[key];
+                    }
+                    // 日志位置：非空时预建目录验证可写，失败直接 400 拦截（默认位置永远合法，空串 = 回默认）
+                    if (typeof patch.logPath === 'string' && patch.logPath.trim() !== '') {
+                        try {
+                            mkdirSync(dirname(customLogFile(patch.logPath)), { recursive: true });
+                        }
+                        catch {
+                            sendJson(response, 400, { error: 'log path is not writable' });
+                            return;
+                        }
+                    }
+                    sendJson(response, 200, saveSettings(profile, patch));
+                    // 系统日志：设置项变更
+                    appendLog(profile, {
+                        at: Date.now(),
+                        level: 'info',
+                        category: 'settings',
+                        event: 'settings.update',
+                        message: `更新设置：${Object.keys(patch).join(', ')}`,
+                    });
+                }
+                catch (error) {
+                    sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/settings/reset',
+            handler: async (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                sendJson(response, 200, resetSettings(profile));
+                appendLog(profile, {
+                    at: Date.now(),
+                    level: 'warn',
+                    category: 'settings',
+                    event: 'settings.reset',
+                    message: '恢复全部默认设置',
+                });
+            },
+        },
+    ];
+}

package/lib/http/shared.js

@@ -0,0 +1,169 @@
+/**
+ * 跨平台宿主重启脚本（以 `node -e` 运行，独立于宿主进程）。
+ * 不用 `/bin/sh -c`：Windows 无 /bin/sh，且 lsof/nohup 仅 POSIX 存在。
+ * 由 `spawn(process.execPath, ['-e', SCRIPT, port], { detached, stdio:'ignore' })` 孵化，
+ * 宿主进程被 kill 后仍能完成「停旧 → 等端口释放 → 拉起新 dsh web」。
+ * 端口探测不到监听进程时不再假装重启（记一行日志后退出，见脚本内注释）。
+ */
+export const HOST_RESTART_SCRIPT = String.raw `const C = require('node:child_process')
+const F = require('node:fs')
+const P = require('node:path')
+const O = require('node:os')
+const win = process.platform === 'win32'
+const port = Number(process.argv[1])
+
+function findPids() {
+  if (win) {
+    const out = C.spawnSync('netstat', ['-ano', '-p', 'tcp'], { encoding: 'utf8' })
+    const found = []
+    for (const line of String(out.stdout || '').split(/\r?\n/)) {
+      if (!/LISTENING/i.test(line)) continue
+      const parts = line.trim().split(/\s+/)
+      const addr = parts[1] || ''
+      if (!addr.endsWith(':' + port)) continue
+      const pid = parts[parts.length - 1]
+      if (pid && /\d+/.test(pid)) found.push(pid)
+    }
+    return found
+  }
+  const out = C.spawnSync('lsof', ['-ti', 'tcp:' + port, '-sTCP:LISTEN'], { encoding: 'utf8' })
+  return String(out.stdout || '').split(/\s+/).filter(Boolean)
+}
+
+const targets = findPids()
+// 一个监听进程都没找到 = 端口探测本身就失败了（netstat 输出格式 / 本地化差异），
+// 旧宿主仍占着端口。此时再拉一个 dsh web 只会在日志里以 EADDRINUSE 静默退出，
+// 用户却看到「重启完成」——不制造这种假象，留一行可诊断的记录后退出。
+if (targets.length === 0) {
+  logLine('restart aborted: no listener found on port ' + port)
+  process.exit(0)
+}
+
+for (const pid of targets) {
+  try {
+    if (win) C.spawnSync('taskkill', ['/pid', pid, '/t', '/f'])
+    else process.kill(Number(pid), 'SIGTERM')
+  } catch {}
+}
+
+let tries = 0
+;(function waitForStop() {
+  if (findPids().length === 0 || ++tries > 20) return startHost()
+  setTimeout(waitForStop, 250)
+})()
+
+function logLine(msg) {
+  try {
+    const dir = P.join(O.homedir(), '.dsh', 'logs')
+    F.mkdirSync(dir, { recursive: true })
+    F.appendFileSync(P.join(dir, 'dsh-web-' + port + '.log'), '[' + new Date().toISOString() + '] ' + msg + '\n')
+  } catch {}
+}
+
+function startHost() {
+  const dir = P.join(O.homedir(), '.dsh', 'logs')
+  F.mkdirSync(dir, { recursive: true })
+  const fd = F.openSync(P.join(dir, 'dsh-web-' + port + '.log'), 'a')
+  const child = C.spawn('dsh', ['web', '--port', String(port)], {
+    detached: true,
+    shell: win,
+    stdio: ['ignore', fd, fd],
+  })
+  child.unref()
+}`;
+/**
+ * 宿主是否由桌面应用壳托管（`ELECTRON_RUN_AS_NODE=1`：壳用 Electron 二进制以 Node 模式跑宿主）。
+ * 桌面端的宿主归应用壳管，插件重启不了它，也不该去 kill —— 详见 /restart 路由。
+ */
+export function isDesktopHost() {
+    return process.env.ELECTRON_RUN_AS_NODE === '1';
+}
+export const PROFILE_RE = /^[A-Za-z0-9_-]+$/;
+const BODY_LIMIT_BYTES = 4 * 1024;
+export const COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
+/** 目录/统计数据代理的本地缓存时长：1 小时内重复打开插件市场直接读盘，
+ *  不重复走 curl 拉远程 —— 重启宿主后首次打开同样秒开（缓存跨重启存活）。 */
+export const CATALOG_CACHE_TTL_MS = 60 * 60 * 1000;
+export function sendJson(response, status, value) {
+    response.writeHead(status, {
+        'cache-control': 'no-store',
+        'content-type': 'application/json; charset=utf-8',
+    });
+    response.end(JSON.stringify(value));
+}
+/** 本机回环主机名：`localhost` / `127.0.0.1` / `[::1]` 指向同一台机器的同一个端口，
+ *  字符串不同但同源，必须按同一来源比较。 */
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** 把 `host[:port]` 形式的 authority 归一化成 `loopback:端口` —— 三个回环别名
+ *  映射成同一个身份，端口缺省按 http 的 80 补齐；非回环主机名、以及解析不出来的值
+ *  都返回 null。 */
+function loopbackAuthority(authority) {
+    try {
+        const parsed = new URL(`http://${authority}`);
+        if (!LOOPBACK_HOSTNAMES.has(parsed.hostname.toLowerCase()))
+            return null;
+        return `loopback:${parsed.port === '' ? '80' : parsed.port}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** POST mutations are only accepted from the local web server origin or the desktop host page.
+ *  Exported for tests (tests/routes.test.ts) — the origin check is the whole CSRF defence. */
+export function isSameOrigin(request) {
+    // 服务只绑定本机回环地址：Host 不是回环（局域网 IP、被改写的域名）一律拒绝，
+    // 顺带挡掉 DNS rebinding（Host 是攻击者域名，即便解析到 127.0.0.1）。
+    const host = request.headers.host;
+    const hostKey = host === undefined ? null : loopbackAuthority(host);
+    if (hostKey === null)
+        return false;
+    const origin = request.headers.origin;
+    // 桌面端宿主把 `/dsh-plugin-hub/*` 转发给本地 http server 时可能不带 Origin 头，
+    // 此时所有 POST 都会被判成 untrusted origin。浏览器对 POST 请求
+    // 必定携带 Origin（含同源 POST 与跨站表单），能省略该头的只有本机原生客户端，
+    // 而它们本来就能伪造任意 Origin，因此放行不扩大 CSRF 面。
+    if (origin === undefined || origin === '')
+        return true;
+    try {
+        const url = new URL(origin);
+        // 桌面端（Electron 宿主）的页面跑在宿主自定义协议下，origin 形如 `dsh-app://app`，
+        // 与 Host（如 localhost:3081）必然不等，因此必须显式放行该协议，否则桌面端全部 POST
+        // 都会被判成 untrusted origin。该协议只有宿主自身能产生，外部网页无法把 Origin
+        // 伪造成 `dsh-app://…`，放行不扩大 CSRF 面。
+        if (url.protocol === 'dsh-app:')
+            return true;
+        // 按归一化后的「主机名:端口」比较：`localhost` / `127.0.0.1` / `[::1]` 不再互相拒绝，
+        // 端口仍然必须一致（另一个本机进程不能被当成同一来源）。
+        return loopbackAuthority(url.host) === hostKey;
+    }
+    catch {
+        return false;
+    }
+}
+export function requireMethod(request, response, method) {
+    if (request.method === method)
+        return true;
+    response.writeHead(405, { allow: method });
+    response.end();
+    return false;
+}
+export function requireTrustedPost(request, response) {
+    if (!requireMethod(request, response, 'POST'))
+        return false;
+    if (isSameOrigin(request))
+        return true;
+    sendJson(response, 403, { error: 'untrusted origin' });
+    return false;
+}
+export async function readJsonBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > BODY_LIMIT_BYTES)
+            throw new Error('request body too large');
+        chunks.push(buffer);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}

package/lib/http/task.js

@@ -0,0 +1,208 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Task/misc routes: task polling, host restart, loader-entry debugging, and
+ * the installed-plugin inventory the client uses to reconcile its list.
+ */
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubTarget, listPendingRestarts, validPackageName } from '../services/install/install.js';
+import { readInstalledVersions, recordInstalledVersion, removeInstalledVersion } from '../services/profile/installed-versions.js';
+import { isDshPlugin, isEntryLoaded } from '../services/loader.js';
+import { profileDirectory, readInstalled } from './catalog.js';
+import { hostEnv } from './diagnostics.js';
+import { HOST_RESTART_SCRIPT, isDesktopHost, readJsonBody, requireMethod, requireTrustedPost, sendJson } from './shared.js';
+export function registerTaskRoutes(webServer, profile, loader) {
+    return [
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/debug/loader-entries',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                sendJson(response, 200, { entries: dumpLoaderEntries(loader) });
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/status',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                const url = new URL(request.url ?? '/', 'http://localhost');
+                const id = Number(url.searchParams.get('task'));
+                const task = Number.isInteger(id) ? getTask(id) : undefined;
+                if (!task) {
+                    sendJson(response, 404, { error: 'task not found' });
+                    return;
+                }
+                sendJson(response, 200, { task });
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/active',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                // 整个任务队列（running 在前、pending 在后）+ 待重启列表：客户端刷新后据此恢复
+                // 进行中/排队任务与「装完没重启」的持久提醒
+                sendJson(response, 200, { tasks: activeTask(), pendingRestarts: listPendingRestarts() });
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/env',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                // 宿主机器环境快照：提交 bug 的 issue 正文会带上，便于作者复现
+                sendJson(response, 200, hostEnv(profile));
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/cancel',
+            handler: async (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                try {
+                    const body = await readJsonBody(request);
+                    const id = typeof body === 'object' && body !== null && typeof body.id === 'number'
+                        ? body.id
+                        : NaN;
+                    const ok = Number.isInteger(id) && cancelTask(id);
+                    sendJson(response, 200, { ok });
+                }
+                catch (error) {
+                    sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/restart',
+            handler: (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                // 桌面端：宿主由应用壳托管，插件重启不了它。Windows 上 `taskkill /T` 会把发起
+                // 重启的助手一起结束（助手是宿主的子进程），壳再把这次外部 kill 判成宿主崩溃
+                // 弹「应用无法启动或已意外停止」；退一步说，脱离壳拉起的 `dsh web` 也服务不了
+                // 桌面 UI（缺壳注入的 desktop:boot）。故不 kill、不拉新宿主，由客户端改提示
+                // 用户从菜单/托盘退出后重新打开。
+                if (isDesktopHost()) {
+                    sendJson(response, 200, { ok: false, desktop: true });
+                    return;
+                }
+                // 当前宿主监听端口来自请求 Host 头（localhost:7923），解析失败回退 7923
+                const host = request.headers.host ?? '';
+                const portMatch = host.match(/:(\d+)$/);
+                const port = portMatch ? Number(portMatch[1]) : 7923;
+                // detached 子进程完成「停旧进程 → 等端口释放 → 后台拉起 dsh web」，
+                // 即使当前宿主（即本插件所在进程）被 kill，重启仍会继续执行。
+                // 不用 /bin/sh：Windows 无此路径，且 lsof/nohup 等仅 POSIX 存在，
+                // 故孵化 node(process.execPath) 跑跨平台脚本 —— Windows 用
+                // netstat + taskkill + shell:true 解析 dsh.cmd，POSIX 用 lsof + SIGTERM。
+                spawn(process.execPath, ['-e', HOST_RESTART_SCRIPT, String(port)], { detached: true, stdio: 'ignore' }).unref();
+                sendJson(response, 200, { ok: true, port });
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/installed-version',
+            handler: async (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                try {
+                    const body = await readJsonBody(request);
+                    const repo = typeof body === 'object' && body !== null && typeof body.repo === 'string'
+                        ? body.repo
+                        : '';
+                    if (githubTarget(repo) === null) {
+                        sendJson(response, 400, { error: 'invalid install target' });
+                        return;
+                    }
+                    // version 为空 = 卸载清理记录；否则记录安装时的目录信号（最新版本 + 仓库更新时间），
+                    // 供「有更新」比对：有版本比版本，无版本比更新时间
+                    const version = body !== null && typeof body.version === 'string'
+                        ? body.version
+                        : null;
+                    if (version === null) {
+                        removeInstalledVersion(profile, repo);
+                    }
+                    else {
+                        const updatedAt = body !== null && typeof body.updatedAt === 'string'
+                            ? body.updatedAt
+                            : '';
+                        recordInstalledVersion(profile, repo, version, updatedAt);
+                    }
+                    sendJson(response, 200, { ok: true });
+                }
+                catch (error) {
+                    sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/open-path',
+            handler: async (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                // 在系统文件管理器里定位并打开已安装插件目录（详情视图「在文件夹中显示」）。
+                // 只接受已安装依赖的包名、服务端自行拼接路径——杜绝任意路径注入
+                try {
+                    const body = await readJsonBody(request);
+                    const name = typeof body === 'object' && body !== null && typeof body.name === 'string'
+                        ? body.name
+                        : '';
+                    if (!validPackageName(name) || readInstalled(profile)[name] === undefined) {
+                        sendJson(response, 400, { error: 'plugin is not installed' });
+                        return;
+                    }
+                    const dir = join(profileDirectory(profile), 'node_modules', name);
+                    // macOS Finder 用 -R 定位选中；Windows explorer 用 /select,；Linux 打开目录（xdg-open）
+                    const bin = process.platform === 'darwin' ? 'open'
+                        : process.platform === 'win32' ? 'explorer'
+                            : 'xdg-open';
+                    const args = process.platform === 'darwin' ? ['-R', dir]
+                        : process.platform === 'win32' ? ['/select,', dir]
+                            : [dir];
+                    spawn(bin, args, { detached: true, stdio: 'ignore' }).unref();
+                    sendJson(response, 200, { ok: true });
+                }
+                catch (error) {
+                    sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/installed',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                // installed：依赖表（包名 → spec）；versions：安装时记录的目录版本（repo → 版本）；
+                // paths：每个依赖在系统上的安装目录（profile/node_modules/<包名>），详情视图展示用；
+                // loaded：已加载进运行中 loader 的包名（官方 ctx.loader.entries()，未重启装的新插件不在其中）；
+                // dshCapable：真正的 dsh 插件（包内声明 dsh 配置 / 在 profile bundles 清单）——
+                //   非 dsh 插件（如 GitHub 官方示例仓库）装上也不会被宿主加载，客户端据此不再提示「待重启」。
+                // 客户端合并这些判断「是否有更新」「运行状态」并展示安装路径/时间等运行时信息。
+                const installed = readInstalled(profile);
+                const paths = {};
+                const loaded = [];
+                const dshCapable = [];
+                for (const name of Object.keys(installed)) {
+                    paths[name] = join(profileDirectory(profile), 'node_modules', name);
+                    if (isEntryLoaded(loader, name))
+                        loaded.push(name);
+                    if (isDshPlugin(profile, name))
+                        dshCapable.push(name);
+                }
+                sendJson(response, 200, { profile, installed, versions: readInstalledVersions(profile), paths, loaded, dshCapable });
+            },
+        },
+    ];
+}

package/lib/services/install/install.js

@@ -1,4 +1,4 @@
 export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../profile/pending-restart.js';
 export { dumpLoaderEntries, removeLoadedEntry } from '../loader.js';
-export { addAllowBuildsKey, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName } from '../profile/profile.js';
+export { addAllowBuildsKey, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName, } from '../profile/profile.js';
 export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.js';

package/lib/services/install/task-queue.js

@@ -41,12 +41,30 @@ export function activeTask() {
     for (const item of queue) {
         const task = item.task;
         if (task.status === 'pending') {
-            found.push({ id: task.id, target: show(task), action: task.action, status: 'pending', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES), attempts: task.attempts, installChannel: task.installChannel });
+            found.push({
+                id: task.id,
+                target: show(task),
+                action: task.action,
+                status: 'pending',
+                progress: task.progress,
+                lines: task.lines.slice(0, MAX_TASK_LINES),
+                attempts: task.attempts,
+                installChannel: task.installChannel,
+            });
         }
     }
     tasks.forEach((task) => {
         if (task.status === 'running') {
-            found.unshift({ id: task.id, target: show(task), action: task.action, status: 'running', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES), attempts: task.attempts, installChannel: task.installChannel });
+            found.unshift({
+                id: task.id,
+                target: show(task),
+                action: task.action,
+                status: 'running',
+                progress: task.progress,
+                lines: task.lines.slice(0, MAX_TASK_LINES),
+                attempts: task.attempts,
+                installChannel: task.installChannel,
+            });
         }
     });
     return found;
@@ -117,7 +135,7 @@ function cliInvocation(profile) {
     if (entry !== undefined) {
         // 打包桌面端（Electron）：宿主入口在 app.asar 内，机器上根本没有 `dsh` 可执行文件
         //（Windows 那条 dsh.cmd shim 只存在于宿主进程自己的 PATH 里），直接回退 PATH 必然
-        // 报 [dsh-missing]（见 issue #71）。这里改用应用自己的 CLI 引导脚本调起同一份打包
+        // 报 [dsh-missing]。这里改用应用自己的 CLI 引导脚本调起同一份打包
         // CLI：Electron 可执行文件 + --expose-internals + desktop-cli.js，与内置终端、
         // 官方插件页安装完全同一条路径 —— desktop profile 由应用独占管理的授权也在其中。
         const bootstrap = desktopCliBootstrap(entry);
@@ -172,9 +190,8 @@ export function desktopCliBootstrap(entry) {
 }
 /**
  * dsh 命令存在性探测：which/where 找 PATH 里的 dsh。
- * Windows shell 模式命令缺失时 cmd 只输出 GBK 乱码「不是内部或外部命令」（UTF-8 解码后
- * 无法匹配），POSIX 非 shell 模式才会抛 spawn dsh ENOENT —— 两种形态都不可靠，统一在
- * spawn 前用 which/where 探测，命令不存在则直接失败并打 ASCII 标记 [dsh-missing]（乱码免疫）。
+ * 命令缺失时各平台报错形态不同（Windows shell 只回 GBK 乱码、POSIX 才抛 spawn ENOENT），
+ * 统一在 spawn 前用 which/where 探测，命令不存在则直接失败并打 ASCII 标记 [dsh-missing]（乱码免疫）。
  * 探测自身异常（which/where 不可用等）不拦截安装，交给装后校验兜底。
  */
 function dshOnPath(env) {
@@ -233,7 +250,22 @@ export function startPluginMutation(options) {
     // 卸载入队时先快照「该包是否带客户端 UI」：卸载完成后包已从磁盘删除，读不到 package.json，
     // 只能在此刻取；卸载成功且曾存活时据此决定是否要刷新页面摘除插件面板
     const hadClientUi = options.action === 'remove' ? hasClientUi(options.profile, options.target) : undefined;
-    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, hadClientUi, installChannel: options.installChannel };
+    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,
+        hadClientUi,
+        installChannel: options.installChannel,
+    };
     nextTaskId = nextTaskId >= Number.MAX_SAFE_INTEGER ? 1 : nextTaskId + 1;
     tasks.set(task.id, task);
     if (tasks.size > MAX_TASKS) {
@@ -367,8 +399,8 @@ function spawnMutation(options) {
         let child;
         try {
             // 独立 CLI 场景（file: 'dsh'，宿主加载器走 node bin 不经过这里）：先探测 dsh 是否在 PATH。
-            // 命令不存在时 Windows shell 模式只回传 GBK 乱码、POSIX 才抛 spawn dsh ENOENT —— 统一前置
-            // 拦截并打 ASCII 标记 [dsh-missing]，前端据此精准提示「dsh 未加入 PATH」而不是笼统的插件失败。
+            // 命令缺失时各平台报错形态不同（GBK 乱码 / spawn ENOENT），统一前置拦截并打 ASCII 标记
+            // [dsh-missing]，前端据此精准提示「dsh 未加入 PATH」而不是笼统的插件失败。
             if (invocation.file === 'dsh' && !dshOnPath(env)) {
                 const detail = '[dsh-missing] the dsh CLI was not found on this machine (DeepSeek Harness not installed, or dsh not on the PATH)';
                 if (task) {
@@ -494,12 +526,9 @@ function spawnMutation(options) {
     });
     return (async () => {
         let result = await spawnOnce(args);
-        // npm 11 的 arborist peer-set bug（`Cannot read properties of null (reading 'children')`）：
-        // 某些包的 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 依赖树天然提供）。
-        // 二次尝试仍失败则保留其错误信息，不掩盖真正的原因。
+        // npm 11 的 arborist peer-set bug（`Cannot read properties of null (reading 'children')`）
+        // 会让 `npm install -g` 在解析阶段直接崩溃。首次失败后自动带 `--legacy-peer-deps` 重试一次：
+        // 跳过 peer 自动解析即可绕过该 bug；二次尝试仍失败则保留其错误信息，不掩盖真正的原因。
         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(' ')}`;
@@ -611,7 +640,7 @@ function ignoredBuildKeys(output) {
 }
 /** npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 把 [npm-too-low] 标记追加到任务输出，
  *  前端据此展示「本机 npm 版本过低」的准确原因 —— 避免该报错被外层 ERR_PNPM_PREPARE_PACKAGE
- *  误判成插件打包/分发问题、误导用户提 Issue。检测逻辑在独立的 npm-check.ts（本机 npm 环境职责）。 */
+ *  误判成插件打包/分发问题。检测逻辑在独立的 npm-check.ts（本机 npm 环境职责）。 */
 function annotateNpmTooLow(result, options) {
     if (options.action === 'remove' || result.exitCode === 0 || result.timedOut)
         return result;

package/lib/services/probe.js

@@ -140,7 +140,7 @@ function runCurl(args, env, timeoutMs) {
  *  若本机 curl 不认这个参数（curl < 7.70）则去掉参数重跑一次，保证老版本不因此直接失败；
  *  降级后仍被吊销检查拦死（CRYPT_E_NO_REVOCATION_CHECK）时，再用 --ssl-no-revoke
  *  彻底关掉吊销检查跑一次 —— 该参数 curl ≥ 7.19 即存在，覆盖面比降级参数更广，
- *  否则「能上网但取不到 CRL」的 Windows 机器会把所有通道误报成不可达（见 issue #71）。
+ *  否则「能上网但取不到 CRL」的 Windows 机器会把所有通道误报成不可达。
  *  吊销检查只影响本次探测自身的信任判断，不改变系统 TLS 配置。 */
 async function curlWithTlsFallback(args, env, timeoutMs) {
     const tlsArgs = curlTlsArgs();

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

@@ -0,0 +1,10 @@
+import { type WebRoute, type WebServerService } from './shared.ts';
+export declare function profileDirectory(profile: string): string;
+/** Read non-official dependencies installed into one profile. */
+export declare function readInstalled(profile: string): Record<string, string>;
+/** 读已装依赖实际落在磁盘上的仓库身份（`owner/repo`）：解析 node_modules/<name>/package.json
+ *  的 repository 字段。已装 spec 可能是纯版本号（丢了仓库身份），但真实包元数据仍指向来源仓库，
+ *  据此可区分「同名依赖其实是同一仓库的残留（应转 update）」还是「跨仓库包名冲突（应报错）」。
+ *  读不到 / 解析不出返回 null（交给调用方按冲突处理）。 */
+export declare function installedRepoOf(profile: string, name: string): string | null;
+export declare function registerCatalogRoutes(webServer: WebServerService, profile: string): WebRoute[];

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

@@ -0,0 +1,4 @@
+import { type WebRoute, type WebServerService } from './shared.ts';
+/** 宿主环境快照：提交 bug 时随 issue 附上，便于作者复现（前端 /env 端点返回）。 */
+export declare function hostEnv(profile: string): Record<string, string | null>;
+export declare function registerDiagnosticsRoutes(webServer: WebServerService, profile: string): WebRoute[];

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

@@ -0,0 +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/uninstall routes: validate the target and spawn the official dsh CLI
+ * (see services/install/install.ts), reporting the captured result back.
+ */
+import { type LoaderHandle } from '../services/install/install.ts';
+import { type WebRoute, type WebServerService } from './shared.ts';
+export declare function registerInstallRoutes(webServer: WebServerService, profile: string, loader: LoaderHandle | undefined): WebRoute[];

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

@@ -0,0 +1,2 @@
+import { type WebRoute, type WebServerService } from './shared.ts';
+export declare function registerLogsRoutes(webServer: WebServerService, profile: string): WebRoute[];