dsh-plugin 1.0.0 → 1.1.1

package/lib/http/routes.js

@@ -9,7 +9,8 @@ import { homedir, release } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubTarget, hasQueuedTarget, listPendingRestarts, readProfileArg, startPluginMutation, validPackageName } from '../services/install.js';
-import { recordInstalledVersion, readInstalledVersions, removeInstalledVersion } from '../services/installed-versions.js';
+import { recordInstalledVersion, recordResolvedNpmPackage, readInstalledVersions, removeInstalledVersion } from '../services/installed-versions.js';
+import { resolveNpmPackage } from '../services/npm-resolve.js';
 import { preflightTarget } from '../services/preflight.js';
 const PROFILE_RE = /^[A-Za-z0-9_-]+$/;
 const BODY_LIMIT_BYTES = 4 * 1024;
@@ -158,17 +159,45 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                     const rawRepo = typeof body === 'object' && body !== null && typeof body.repo === 'string'
                         ? body.repo.trim()
                         : '';
+                    // 前端决策的展示用仓库名（owner/repo）：npm 安装时 body.repo 是包名，display 用于
+                    // 待重启行 / 任务恢复时展示仓库名，保证用户无感知（安装通道变化不改变所见目标）
+                    const displayRepo = typeof body === 'object' && body !== null && typeof body.display === 'string'
+                        ? body.display.trim()
+                        : rawRepo;
                     // 目标语法两态：owner/repo → github 源（走装前预检）；npm 包名（@scope/name 或 name）→ 信任 registry 直接安装
                     const repoTarget = githubTarget(rawRepo);
-                    const target = repoTarget ?? (repoTarget === null && validPackageName(rawRepo) ? rawRepo : null);
+                    let target = repoTarget ?? (repoTarget === null && validPackageName(rawRepo) ? rawRepo : null);
                     if (target === null) {
                         sendJson(response, 400, { error: 'unsupported install target' });
                         return;
                     }
+                    // npm 优先：git 目标先反查该仓库的官方 npm 包，命中则改走 npm 通道。
+                    // git 分发常缺构建产物/子模块导致 prepare 必败，而 npm 包是作者发布的
+                    // 完整产物，成功率高得多；未命中或查询失败保留 github 直装（不阻塞安装，
+                    // 预检仍会兜底拦截 git 分发缺入口文件的情况）。通用机制，不针对具体插件。
+                    // 反查本身计入「已尝试的安装方式」：组织 scope 与 GitHub 用户名不一致时仅凭
+                    // 仓库名猜不到包名，失败提 Issue 时作者看到我们查过的命令就能直接指认正确包名。
+                    const attempts = [];
+                    if (repoTarget !== null) {
+                        const npmName = await resolveNpmPackage(rawRepo);
+                        if (npmName !== null) {
+                            target = npmName;
+                            attempts.push(`npm registry search: \`npm search repository:${rawRepo}\` → found \`${npmName}\``);
+                            // 持久化 repo → npm 包名映射：目录数据未下发 npmPackage（组织 scope 与 GitHub
+                            // 用户名不一致）时，客户端仍能通过 /installed 的 versions 把依赖 key 匹配回仓库，
+                            // 列表立即显示「已安装」，避免安装成功后仍显示可安装
+                            recordResolvedNpmPackage(profile, rawRepo, npmName);
+                        }
+                        else {
+                            attempts.push(`npm registry search: \`npm search repository:${rawRepo}\` → no matching package found (falling back to git install)`);
+                        }
+                    }
                     // 重复安装防护：非更新请求命中已安装目标时直接拒绝，不重复跑 CLI
                     // （否则 CLI 会因「已存在」失败，且用户看到的是莫名其妙的报错）；
-                    // 更新请求（mode: 'update'）放行，CLI 的 add 对已存在依赖是 pnpm 原位覆盖重装
-                    const already = installedByRepo(readInstalled(profile), target);
+                    // 更新请求（mode: 'update'）放行，CLI 的 add 对已存在依赖是 pnpm 原位覆盖重装。
+                    // 命中判定双通道：npm 包名按 dependencies 键直接命中，github: 目标按 spec 值匹配。
+                    const installed = readInstalled(profile);
+                    const already = installedByRepo(installed, target) ?? (installed[target] !== undefined ? target : null);
                     if (already !== null && mode !== 'update') {
                         sendJson(response, 409, { error: `already installed: ${already}` });
                         return;
@@ -180,13 +209,16 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                     }
                     // 安装前预检：仅新安装走预检（github 源分发改入口文件缺失时直接拦截）。
                     // 更新是已信任目标的覆盖重装，跳过预检避免重复下载 tarball。
-                    // 只支持官方默认安装方式（dsh plugin add github:owner/repo），不做任何 npm 兜底降级；
-                    // [packaging] 前缀供客户端归类为「插件未适配官方默认安装方式」并引导去仓库提 Issue
+                    // npm 包信任 registry 直接放行；github 源拦截时标记 [packaging] 前缀，
+                    // 供客户端归类为「插件分发不完整」并引导去仓库提 Issue
                     if (already === null) {
                         const preflight = await preflightTarget(target);
                         if (!preflight.ok) {
+                            // 预检拦截（git 分发缺入口文件）：同步 400 返回，附上已尝试的安装方式，
+                            // 客户端失败弹窗提 Issue 时一并贴给作者
                             sendJson(response, 400, {
-                                error: `[packaging] ${target}: does not support the official default install method — the git distribution lacks build output (the entry file ${preflight.missing ?? '?'} declared in package.json is not in the repository). Report to the author.`,
+                                error: `[packaging] ${target}: plugin distribution is incomplete — the entry file ${preflight.missing ?? '?'} declared in package.json is not present in the git distribution (build output not committed). Report to the author.`,
+                                attempts,
                             });
                             return;
                         }
@@ -203,6 +235,10 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                         action: 'add',
                         profile,
                         target,
+                        // npm 安装时 target 是包名：displayTarget 固定展示仓库名，待重启行/前端恢复不受通道变化影响
+                        displayTarget: githubTarget(displayRepo) ?? undefined,
+                        // 已尝试的安装方式（npm 反查）：实际执行命令由 spawn 时追加，失败 issue 一并展示
+                        attempts,
                         timeoutMs: COMMAND_TIMEOUT_MS,
                         env: { ...process.env, CI: 'true' },
                     });

package/lib/services/installed-versions.js

@@ -35,7 +35,22 @@ export function readInstalledVersions(profile) {
 /** Record the catalog signals (version + repo updated time) present at install time for one repo. */
 export function recordInstalledVersion(profile, repo, version, updatedAt) {
     const table = readInstalledVersions(profile);
-    table[repo.toLowerCase()] = { version, updatedAt, installedAt: new Date().toISOString() };
+    const key = repo.toLowerCase();
+    // 合并写入：保留已记录的 npmPackage（npm 优先通道的 repo → 包名映射），
+    // 客户端同步版本信号时不能把它覆盖掉
+    table[key] = { ...table[key], version, updatedAt, installedAt: new Date().toISOString() };
+    writeVersions(profile, table);
+}
+/**
+ * Record the npm package name resolved for a repo (npm-first install channel).
+ * Called at `/install` time so the mapping exists even before the task finishes;
+ * harmless when the repo is not (yet) installed — the client only treats a repo
+ * as installed when its dependency key actually exists.
+ */
+export function recordResolvedNpmPackage(profile, repo, npmPackage) {
+    const table = readInstalledVersions(profile);
+    const key = repo.toLowerCase();
+    table[key] = { ...table[key], npmPackage };
     writeVersions(profile, table);
 }
 /** Forget the recorded version for one repo (called on uninstall). */

package/lib/services/loader.js

@@ -44,13 +44,15 @@ function nameMatches(entryName, target) {
     return false;
 }
 /**
- * 卸载成功后从运行中 loader 停用指定包的条目，使卸载立即生效（刷新页面不再
- * 加载已卸载的 client bundle，也无需重启）。做法：按 name 扫描
+ * 卸载成功后从运行中 loader 停用指定包的条目。做法：按 name 扫描
  * `loader.entries()`（含嵌套子树），对每个匹配条目
  * `entry.update({ disabled: true })` 做 live-disable —— fiber 被 dispose，
  * client-modules 对账后不再把它写进 `__DSH_BOOT__`，页面刷新即恢复。
- * 返回 true = 无需重启（条目已停用，或本就没加载过）；false = 未能停用，
- * 需登记「待重启清理」兜底。宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
+ * 返回 true = 无需重启（仅当宿主从未加载过它：磁盘已干净）；
+ * 其余一律 false = 需要重启：要么 disable 失败需「待重启清理」兜底，
+ * 要么 disable 成功但该插件曾在 loader 中存活——带 UI 的插件（侧边栏面板等
+ * 宿主启动时渲染的槽位）disable 后不会主动摘除，不重启面板一直残留。
+ * 宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
  */
 export async function removeLoadedEntry(loader, name) {
     if (name === 'dsh-plugin' || name.startsWith('@deepseek-ai/'))
@@ -83,8 +85,13 @@ export async function removeLoadedEntry(loader, name) {
         if (!found) {
             // 运行中 loader 无该条目：宿主从未加载过它（装完未重启），磁盘已干净，无需重启
             console.log(`[hub-uninstall] no live entry for ${name}; nothing to disable`);
+            return true;
         }
-        return true;
+        // 找到并停用了 live entry：逻辑层已卸载（刷新页面不再加载其 client bundle），
+        // 但带 UI 的插件（侧边栏面板等）是宿主启动时渲染的槽位，disable 不会主动摘除，
+        // 不重启面板会一直残留 → 返回「需要重启」，弹窗给出「立即重启」，面板立即消失
+        console.log(`[hub-uninstall] disabled live entry for ${name}; UI may persist until restart`);
+        return false;
     })();
     const result = await Promise.race([
         removal.catch((error) => {

package/lib/services/npm-resolve.js

@@ -0,0 +1,67 @@
+/**
+ * npm 包反查：git 分发不完整（缺构建产物/子模块）导致安装失败时，用 npm
+ * registry 的搜索接口按 repository 地址反查该仓库对应的官方 npm 包。
+ *
+ * 这是通用机制，不针对任何具体插件：只要作者发布了 repository 指向该
+ * GitHub 仓库的 npm 包（scope 名与 GitHub 用户名是否一致无所谓），就能命中，
+ * 从而把「git 直装必败」的插件切换到 npm 通道安装。命中结果带内存缓存，
+ * 避免同一会话内重复查询 registry。
+ */
+import { get } from 'node:https';
+/** 反查缓存：repo 小写 → npm 包名（null 表示已确认无对应 npm 包）。 */
+const cache = new Map();
+/** 单次 registry 查询超时（ms）：慢网络下失败返回 null，不阻塞安装流程。 */
+const REQUEST_TIMEOUT_MS = 8000;
+/**
+ * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
+ * 返回 null 不代表仓库一定没有 npm 包，只代表本次未能确认 —— 调用方应保留
+ * 原有错误路径，反查只是额外的一次尝试。
+ */
+export function resolveNpmPackage(repo) {
+    const key = repo.toLowerCase();
+    if (cache.has(key))
+        return Promise.resolve(cache.get(key) ?? null);
+    const name = searchRepo(repo);
+    name.then((found) => cache.set(key, found)).catch(() => cache.set(key, null));
+    return name;
+}
+/** 用 npm search 接口按 repository 地址反查，并做铁证校验（包元数据必须指向该仓库）。 */
+function searchRepo(repo) {
+    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`;
+    return new Promise((resolve) => {
+        const req = get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            let body = '';
+            res.on('data', (chunk) => { body += chunk.toString(); });
+            res.on('end', () => {
+                try {
+                    const data = JSON.parse(body);
+                    const needle = `github.com/${owner}/${name}`.toLowerCase();
+                    for (const obj of data.objects ?? []) {
+                        const pkg = obj.package;
+                        if (typeof pkg?.name !== 'string' || pkg.name === '')
+                            continue;
+                        const repoUrl = String(pkg.repository?.url ?? pkg.links?.repository ?? '');
+                        if (repoUrl.toLowerCase().includes(needle)) {
+                            resolve(pkg.name);
+                            return;
+                        }
+                    }
+                    resolve(null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => resolve(null));
+    });
+}

package/lib/services/task-queue.js

@@ -28,15 +28,18 @@ export function getTask(id) {
 /** All non-terminal tasks in queue order (running first, then pending). Lets the client resume a queue after a page reload. */
 export function activeTask() {
     const found = [];
+    // 展示目标用 displayTarget（owner/repo）：安装 target 可能被服务端切成 npm 包名
+    // （npm 反查命中），队列恢复/待重启展示对用户保持仓库名无感知
+    const show = (task) => task.displayTarget ?? task.target;
     for (const item of queue) {
         const task = item.task;
         if (task.status === 'pending') {
-            found.push({ id: task.id, target: task.target, action: task.action, status: 'pending', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES) });
+            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 });
         }
     }
     tasks.forEach((task) => {
         if (task.status === 'running') {
-            found.unshift({ id: task.id, target: task.target, action: task.action, status: 'running', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES) });
+            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 });
         }
     });
     return found;
@@ -139,7 +142,7 @@ function stopChild(child) {
  * Progress is visible through `getTask(id)` / `activeTask()` until done.
  */
 export function startPluginMutation(options) {
-    const task = { id: nextTaskId, target: options.target, action: options.action, status: 'pending', timedOut: false, exitCode: null, progress: 0, lines: [] };
+    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 };
     nextTaskId = nextTaskId >= Number.MAX_SAFE_INTEGER ? 1 : nextTaskId + 1;
     tasks.set(task.id, task);
     if (tasks.size > MAX_TASKS) {
@@ -182,6 +185,12 @@ 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}`;
+    if (task && !task.attempts.includes(executed)) {
+        task.attempts.push(executed);
+    }
     return new Promise((resolvePromise) => {
         let stdout = '';
         let stderr = '';
@@ -307,9 +316,13 @@ function spawnMutation(options) {
                         if (task.status === 'done') {
                             task.progress = 100;
                             if (action === 'remove' && uninstallLoader) {
-                                // 卸载成功 → 主动从运行中 loader 移除该包条目，立即生效、无需重启；
-                                // 移除失败（或从未加载过但 loader 不可用）才登记「待重启清理」兜底
+                                // 卸载成功 → 主动从运行中 loader 停用该包条目；
+                                // 仅当宿主从未加载过它（磁盘已干净）才判「无需重启」；
+                                // 只要曾在 loader 中存活（停用过 live entry）就仍要求重启——
+                                // 带 UI 的插件（侧边栏面板等宿主启动时渲染的槽位）disable 后不会
+                                // 主动消失，重启才能立即摘除面板
                                 const removed = await removeLoadedEntry(uninstallLoader, target);
+                                task.needsRestart = !removed;
                                 if (removed)
                                     clearPendingRestart(displayTarget ?? target);
                                 else
@@ -318,6 +331,7 @@ function spawnMutation(options) {
                             else {
                                 // 安装成功（或卸载但无 loader 引用）→ 登记待重启：
                                 // 插件要宿主重启才会挂载/卸载干净，重启前一直提醒；展示目标用 displayTarget（owner/repo）
+                                task.needsRestart = true;
                                 addPendingRestart(displayTarget ?? target, action === 'add' ? 'install' : 'uninstall');
                             }
                         }
@@ -371,17 +385,30 @@ export function verifyInstalledEntry(profile, target) {
         return { name, missing: entry };
     }
 }
+/** 从 pnpm `Ignored build scripts:` 提示行解析被拦截的构建脚本 key（name@version，逗号分隔）。 */
+function ignoredBuildKeys(output) {
+    const m = /Ignored build scripts:\s*(.+)/i.exec(output);
+    if (m === null)
+        return [];
+    return m[1]
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s !== '');
+}
 /**
- * Run a plugin mutation with one recovery path: when `add` fails because a
- * git-hosted package's `prepare` script is blocked by pnpm's allowBuilds
- * gate (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`), read the exact allowlist
- * key pnpm printed, write it into the profile's pnpm-workspace.yaml, and
- * retry once. Other failures fall through to the single-spawn result.
+ * Run a plugin mutation with one recovery path: when `add` fails because
+ * pnpm's allowBuilds gate blocks a build script — either the git-hosted
+ * package's own `prepare` (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`, key from
+ * the printed key@url hint) or a dependency's native build
+ * (`ERR_PNPM_IGNORED_BUILDS`, key = the listed name@version) — write the
+ * exact keys into the profile's pnpm-workspace.yaml and retry once.
+ * 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) {
         const output = `${result.stderr}\n${result.stdout}`;
+        // git 源：pnpm 打印的 key@url 提示
         if (output.includes('ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED')) {
             const key = parseAllowBuildsKey(output);
             if (key !== null) {
@@ -396,6 +423,24 @@ export async function runPluginMutation(options) {
                 return spawnMutation(options);
             }
         }
+        // 依赖原生模块/构建脚本被 pnpm v11 拦截（ERR_PNPM_IGNORED_BUILDS）：git 与 npm 源都会出现。
+        // allowBuilds 的 key 是输出里列出的 name@version（如 node-pty@1.1.0），逐个放行后重试一次；
+        // 输出解析不到时回退用目标名（插件自身构建脚本被拦的 npm 场景）。
+        if (output.includes('ERR_PNPM_IGNORED_BUILDS')) {
+            const keys = ignoredBuildKeys(output);
+            if (keys.length === 0 && !options.target.startsWith('github:'))
+                keys.push(options.target);
+            if (keys.length > 0) {
+                if (options.task) {
+                    options.task.status = 'running';
+                    options.task.exitCode = null;
+                    pushLine(options.task, `[allow build] ${keys.join(', ')}`);
+                }
+                for (const key of keys)
+                    addAllowBuildsKey(options.profile, key);
+                return spawnMutation(options);
+            }
+        }
     }
     // pnpm 安装本身成功，但目标包入口文件缺失（git 分发缺构建产物）→ 判为失败：
     // 撤销刚登记的待重启，避免用户重启时宿主加载残缺包直接崩溃

package/lib/types/services/install-types.d.ts

@@ -11,6 +11,12 @@ export interface InstallTask {
     id: number;
     /** 操作目标：`github:<owner>/<repo>`（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
     target: string;
+    /** 展示用目标（owner/repo）：npm 安装时 target 是包名，前端恢复用此字段显示仓库名，保持用户无感知 */
+    displayTarget?: string;
+    /** 尝试过的安装方式（npm registry 反查 + 实际执行的 CLI 命令，按先后顺序）：
+     *  失败提 Issue 时如实贴给作者，作者据此反推正确的 npm 包名（组织 scope 与 GitHub 用户名不一致时
+     *  仅凭仓库名猜不到，作者看到我们查过/试过的命令就能直接指认）。 */
+    attempts: string[];
     action: 'add' | 'remove';
     /** 队列语义：pending 排队中 / running 执行中 / done / failed / cancelled（用户取消） */
     status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled';
@@ -20,6 +26,8 @@ export interface InstallTask {
     progress: number;
     /** Newest output lines first (consumer shows the tail). */
     lines: string[];
+    /** 完成后是否仍需宿主重启才生效：卸载时 loader 已即时移除 → false；否则 true（弹窗据此给重启选项） */
+    needsRestart: boolean;
 }
 /** 子进程启动参数（复用宿主 dsh 入口，或回退到 PATH 上的 `dsh`）。 */
 export interface Invocation {

package/lib/types/services/installed-versions.d.ts

@@ -4,11 +4,21 @@ export interface InstalledVersionRecord {
     /** 安装时的仓库最近更新时间（ISO，GitHub pushed_at）；无 release 仓库的更新依据 */
     updatedAt: string;
     installedAt: string;
+    /** npm 优先通道反查命中的官方 npm 包名（repo → 包名映射）：目录数据可能未下发
+     *  npmPackage（组织 scope 与 GitHub 用户名不一致），客户端据此把依赖 key 匹配回仓库 */
+    npmPackage?: string;
 }
 export type InstalledVersionTable = Record<string, InstalledVersionRecord>;
 export declare function versionsFilePath(profile: string): string;
 export declare function readInstalledVersions(profile: string): InstalledVersionTable;
 /** Record the catalog signals (version + repo updated time) present at install time for one repo. */
 export declare function recordInstalledVersion(profile: string, repo: string, version: string, updatedAt: string): void;
+/**
+ * Record the npm package name resolved for a repo (npm-first install channel).
+ * Called at `/install` time so the mapping exists even before the task finishes;
+ * harmless when the repo is not (yet) installed — the client only treats a repo
+ * as installed when its dependency key actually exists.
+ */
+export declare function recordResolvedNpmPackage(profile: string, repo: string, npmPackage: string): void;
 /** Forget the recorded version for one repo (called on uninstall). */
 export declare function removeInstalledVersion(profile: string, repo: string): void;

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

@@ -32,12 +32,14 @@ export declare function dumpLoaderEntries(loader: LoaderHandle | undefined): Arr
     name?: string;
 }>;
 /**
- * 卸载成功后从运行中 loader 停用指定包的条目，使卸载立即生效（刷新页面不再
- * 加载已卸载的 client bundle，也无需重启）。做法：按 name 扫描
+ * 卸载成功后从运行中 loader 停用指定包的条目。做法：按 name 扫描
  * `loader.entries()`（含嵌套子树），对每个匹配条目
  * `entry.update({ disabled: true })` 做 live-disable —— fiber 被 dispose，
  * client-modules 对账后不再把它写进 `__DSH_BOOT__`，页面刷新即恢复。
- * 返回 true = 无需重启（条目已停用，或本就没加载过）；false = 未能停用，
- * 需登记「待重启清理」兜底。宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
+ * 返回 true = 无需重启（仅当宿主从未加载过它：磁盘已干净）；
+ * 其余一律 false = 需要重启：要么 disable 失败需「待重启清理」兜底，
+ * 要么 disable 成功但该插件曾在 loader 中存活——带 UI 的插件（侧边栏面板等
+ * 宿主启动时渲染的槽位）disable 后不会主动摘除，不重启面板一直残留。
+ * 宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
  */
 export declare function removeLoadedEntry(loader: LoaderHandle, name: string): Promise<boolean>;

package/lib/types/services/npm-resolve.d.ts

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

package/lib/types/services/task-queue.d.ts

@@ -9,6 +9,8 @@ export interface ActiveTaskInfo {
     status: 'pending' | 'running';
     progress: number;
     lines: string[];
+    /** 尝试过的安装方式（npm 反查 + 实际执行命令）：失败时前端 issue 预填需要 */
+    attempts: string[];
 }
 /** All non-terminal tasks in queue order (running first, then pending). Lets the client resume a queue after a page reload. */
 export declare function activeTask(): ActiveTaskInfo[];
@@ -44,6 +46,8 @@ export declare function startPluginMutation(options: {
     displayTarget?: string;
     /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
     uninstallLoader?: LoaderHandle;
+    /** 入队前已尝试的安装方式（npm registry 反查等）：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
+    attempts?: string[];
 }): InstallTask;
 /**
  * 安装后校验已装包的入口文件（package.json 的 main / exports["."].default）是否真实存在。
@@ -56,11 +60,13 @@ export declare function verifyInstalledEntry(profile: string, target: string): {
     missing: string | null;
 };
 /**
- * Run a plugin mutation with one recovery path: when `add` fails because a
- * git-hosted package's `prepare` script is blocked by pnpm's allowBuilds
- * gate (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`), read the exact allowlist
- * key pnpm printed, write it into the profile's pnpm-workspace.yaml, and
- * retry once. Other failures fall through to the single-spawn result.
+ * Run a plugin mutation with one recovery path: when `add` fails because
+ * pnpm's allowBuilds gate blocks a build script — either the git-hosted
+ * package's own `prepare` (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`, key from
+ * the printed key@url hint) or a dependency's native build
+ * (`ERR_PNPM_IGNORED_BUILDS`, key = the listed name@version) — write the
+ * exact keys into the profile's pnpm-workspace.yaml and retry once.
+ * Other failures fall through to the single-spawn result.
  */
 export declare function runPluginMutation(options: {
     action: 'add' | 'remove';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 4000+ human-curated community plugins without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：4000+ 人工精选社区插件，每日更新。",
   "type": "module",
   "main": "lib/index.js",

package/src/client/components/AboutModal.tsx

@@ -0,0 +1,72 @@
+/**
+ * 头部「关注我们」弹窗：介绍 DSH-Plugin Hub 是干什么的 + 用户反馈群二维码。
+ * 内容以 Markdown 形式由 dsh-update Worker 的 /about 接口下发（key = hub:about），
+ * 作者想怎么写就怎么写、随写随推，客户端只负责渲染 —— 非写死。
+ * 图片（反馈群二维码）经 renderMarkdown 的 ![](url) 语法嵌入，居中、最大高度受控。
+ */
+import { createElement as h } from 'react'
+import type { MouseEvent } from 'react'
+import styles from '../styles/Modal.module.css'
+import type { HubAboutInfo } from '../lib/catalog.ts'
+import type { LocaleId, Translate } from '../types.ts'
+import { renderMarkdown } from '../lib/renderMarkdown.ts'
+import { CloseIcon } from './icons.tsx'
+
+export function AboutModal({ info, lang, t, onClose }: {
+  info: HubAboutInfo | null
+  lang: LocaleId
+  t: Translate
+  onClose: () => void
+}) {
+  // 内容：字符串直接使用；{zh,en} 对象按界面语言取，缺哪种补哪种，全缺则展示兜底文案。
+  // Worker 未推送（info 为 null / content 为空）时弹窗仍能打开，显示「暂未发布」而非报错。
+  const contentRaw = info
+    ? typeof info.content === 'string'
+      ? info.content
+      : info.content && typeof info.content === 'object'
+        ? lang === 'en'
+          ? (info.content.en ?? info.content.zh ?? '')
+          : (info.content.zh ?? info.content.en ?? '')
+        : ''
+    : ''
+  const contentHtml = contentRaw.trim() ? renderMarkdown(contentRaw) : null
+  // 更新时间：ISO 字符串转本地可读格式；非法值静默隐藏
+  let updated: string | null = null
+  if (info?.updatedAt) {
+    const d = new Date(info.updatedAt)
+    if (!Number.isNaN(d.getTime())) {
+      updated = d.toLocaleString(lang === 'en' ? 'en-US' : 'zh-CN')
+    }
+  }
+
+  return h('div', {
+    className: styles.overlay,
+    onClick: (e: MouseEvent<HTMLDivElement>) => {
+      if (e.target === e.currentTarget) onClose()
+    },
+  },
+    h('div', { className: `${styles.modal} ${styles.aboutModal}`, role: 'dialog', 'aria-modal': 'true' },
+      h('div', { className: styles.modalHead },
+        h('div', { className: styles.modalTitle }, t('aboutTitle')),
+        h('button', {
+          className: styles.modalClose,
+          'aria-label': t('confirmCancel'),
+          onClick: () => onClose(),
+        }, h(CloseIcon)),
+      ),
+      h('div', { className: styles.modalDesc }, t('aboutDesc')),
+      contentHtml
+        ? h('div', {
+          className: styles.aboutContent,
+          dangerouslySetInnerHTML: { __html: contentHtml },
+        })
+        : h('div', { className: styles.aboutContent }, t('aboutEmpty')),
+      updated
+        ? h('div', { className: styles.aboutMeta }, `${t('aboutUpdated')} ${updated}`)
+        : null,
+      h('div', { className: styles.modalActions },
+        h('button', { className: styles.modalInstall, onClick: onClose }, t('doneBtn')),
+      ),
+    ),
+  )
+}

package/src/client/components/CatalogHeader.tsx

@@ -8,12 +8,18 @@ import type { Translate } from '../types.ts'
 import { GITHUB_URL, PLUGIN_VERSION, SITE_URL } from '../lib/catalog.ts'
 import { GitHubIcon, LogoIcon } from './icons.tsx'
 
-export function CatalogHeader({ t, langPath, statsTotal, statsVerified, onToggleLang }: {
+export function CatalogHeader({ t, langPath, statsTotal, statsVerified, onToggleLang, hubUpdate, onVersionClick, onAboutClick }: {
   t: Translate
   langPath: string
   statsTotal: number
   statsVerified: number
   onToggleLang: () => void
+  /** Hub 自身是否有可用更新：有则版本号后紧跟红色「可更新」徽标（整体一个可点入口） */
+  hubUpdate: boolean
+  /** 点击版本号（含红色徽标，同一入口）：无论有无更新都打开更新记录弹窗 */
+  onVersionClick: () => void
+  /** 点击「关注我们」：打开平台介绍 + 用户反馈群二维码弹窗 */
+  onAboutClick: () => void
 }) {
   return h(Fragment, null,
     h('div', { className: styles.header },
@@ -28,10 +34,20 @@ export function CatalogHeader({ t, langPath, statsTotal, statsVerified, onToggle
           'aria-label': t('openHint'),
         },
           h(LogoIcon),
-          h('h1', { className: styles.title },
-            t('title'),
-            h('span', { className: styles.version }, ` v${PLUGIN_VERSION}`),
-          ),
+          h('h1', { className: styles.title }, t('title')),
+        ),
+        // 版本号：紧跟标题「DSH-Plugin Hub」之后，常驻可点入口（<a> 内不能嵌套按钮，故从官网链接里移出放在旁边）。
+        // 点击打开更新记录弹窗 —— 有更新看新版本内容，无更新看当前版本内容。
+        // 有更新时版本号后直接跟一个红色「可更新」徽标（同一按钮内，不分开成两个元素），静态显示不闪烁。
+        h('button', {
+          className: styles.versionBtn,
+          type: 'button',
+          onClick: onVersionClick,
+          title: t(hubUpdate ? 'hubUpdateHint' : 'versionHint'),
+          'aria-label': t(hubUpdate ? 'hubUpdateHint' : 'versionHint'),
+        },
+          `v${PLUGIN_VERSION}`,
+          hubUpdate && h('span', { className: styles.hubUpdateBadge }, t('update')),
         ),
         // 右侧控件组：语言切换 + GitHub 源码图标（独立链接，brandTitle 是官网 <a> 不能嵌套），
         // 一起 space-between 顶到标题行最右
@@ -44,6 +60,15 @@ export function CatalogHeader({ t, langPath, statsTotal, statsVerified, onToggle
             title: t('toggleLangHint'),
             'aria-label': t('toggleLangHint'),
           }, langPath === 'zh/' ? 'EN' : '中文'),
+          // 「关注我们」：点击打开平台介绍 + 用户反馈群二维码弹窗
+          h('button', {
+            className: styles.aboutBtn,
+            type: 'button',
+            onClick: onAboutClick,
+            title: t('aboutDesc'),
+            'aria-label': t('aboutTitle'),
+          }, t('followUs')),
+          // GitHub 源码图标：独立链接（brandTitle 是官网 <a> 不能嵌套），放在控件组最后
           h('a', {
             className: styles.githubLink,
             href: GITHUB_URL,