dsh-plugin 2.0.6 → 2.2.0

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

@@ -14,13 +14,16 @@ import { dirname, join, resolve } from 'node:path';
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.js';
 import { npmTooLowMarker } from './npm-check.js';
 import { registryMissingMarker } from './registry-check.js';
-import { backfillOperationLog, createOperationLogTap, operationLogPathOf } from './operation-log.js';
+import { backfillOperationLog, createOperationLogTap, hasSubstantiveOutput, operationLogPathOf } from './operation-log.js';
 import { cleanLine, estimateProgress } from '../profile/progress.js';
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.js';
 import { addPendingRestart, clearPendingRestart } from '../profile/pending-restart.js';
 import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.js';
 import { appendLog } from '../log.js';
 import { commandOnPath, gitMissingDetail } from './preflight.js';
+import { isTransportFailure, registryHost } from './registry-fallback.js';
+import { dshTooOldMarker } from './dsh-compat.js';
+import { OutputDecoder } from './decode-output.js';
 /** 内存任务注册表，按任务 id 索引。 */
 const tasks = new Map();
 let nextTaskId = 1;
@@ -195,6 +198,17 @@ export function desktopCliBootstrap(entry) {
     }
     return null;
 }
+/**
+ * 传给 CLI 的安装目标：钉住版本优先（Hub 自我更新提示的是已过供应链门禁的版本），
+ * 其次更新走 `@latest`，git 源与全局 npm 安装保持原样。
+ */
+export function npmInstallTargetOf(target, opts) {
+    if (opts.global || githubRepoOf(target) !== null)
+        return target;
+    if (opts.pinned !== undefined && opts.pinned !== '')
+        return opts.pinned;
+    return opts.update ? `${target}@latest` : target;
+}
 function stopChild(child) {
     if (process.platform === 'win32' && child.pid !== undefined) {
         const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore' });
@@ -346,12 +360,18 @@ function pumpQueue() {
  * 跟踪的任务上，并以捕获结果 resolve。绝不 reject；失败通过结果/任务状态体现。
  */
 function spawnMutation(options) {
-    const { action, profile, target, timeoutMs = 5 * 60 * 1000, env, task, displayTarget, loader, globalNpm, updateNpm } = options;
+    const { action, profile, target, timeoutMs = 5 * 60 * 1000, env, task, displayTarget, loader, globalNpm, updateNpm, registries, installSpec } = options;
     // 全局 npm 安装：直接 spawn 本机 npm（`npm install -g <pkgs>`），不是 dsh plugin 命令
     const isGlobalNpm = (globalNpm ?? []).length > 0;
     const invocation = isGlobalNpm
         ? { file: 'npm', prefixArgs: [], cwd: process.cwd(), useShell: process.platform === 'win32' }
         : cliInvocation(profile);
+    // 打包桌面端却回退到 PATH 上的 dsh：说明 desktop CLI 引导路径没命中，desktop profile 必被宿主拒绝。
+    // 留一行 ASCII 标记，后续同类上报可直接区分「用户自起 CLI」与「我们没走对引导路径」。
+    if (task && task.status !== 'cancelled' && invocation.file === 'dsh'
+        && process.versions.electron !== undefined) {
+        pushLine(task, '[desktop-cli-fallback] running inside Electron but no desktop CLI bootstrap was found — falling back to dsh on PATH (a desktop-managed profile will be rejected)');
+    }
     // 更新已安装的 npm 包：显式指定 @latest。pnpm add <pkg>（无版本）对已存在依赖
     // （尤其精确 spec 如 "1.3.0"）是幂等的 —— 输出 "Already up to date" 且不改 package.json，
     // 导致「更新成功」但实际仍停留在旧版本；git 地址与全局安装不受此影响。
@@ -359,9 +379,8 @@ function spawnMutation(options) {
     // CLI 动词仍透传 add —— 不执行官方 update 动词，避免与既有覆盖重装机制分叉。
     const isUpdate = action === 'update' || updateNpm === true;
     const cliAction = action === 'update' ? 'add' : action;
-    const npmUpdateTarget = isUpdate && !isGlobalNpm && githubRepoOf(target) === null
-        ? `${target}@latest`
-        : target;
+    // 钉住版本优先于 @latest：提示的是「已过门禁」的版本，装 latest 会被 pnpm 拒绝
+    const npmUpdateTarget = npmInstallTargetOf(target, { update: isUpdate, global: isGlobalNpm, pinned: installSpec });
     const args = isGlobalNpm
         ? ['install', '-g', ...(globalNpm ?? [])]
         : [...invocation.prefixArgs, 'plugin', '--profile', profile, cliAction, npmUpdateTarget];
@@ -375,9 +394,12 @@ function spawnMutation(options) {
     // 单次 spawn 并捕获结果：流式输出打日志 + 超时/取消兜底，close 后 resolve。
     // 不做任何终态后处理（exitCode/status/needsRestart 由下方统一收尾），
     // 这样全局 npm 首次失败后可以干净地换参数重试一次。
-    const spawnOnce = (attemptArgs) => new Promise((resolveOnce) => {
+    const spawnOnce = (attemptArgs, registry) => new Promise((resolveOnce) => {
         let stdout = '';
         let stderr = '';
+        // 每次 spawn 独立解码器：中文 Windows 下 dsh/pnpm 可能输出 GBK，需按流判定编码
+        const stdoutDecoder = new OutputDecoder();
+        const stderrDecoder = new OutputDecoder();
         let timedOut = false;
         let settled = false;
         let child;
@@ -411,11 +433,17 @@ function spawnMutation(options) {
                     return;
                 }
             }
+            // invocation.env 是「必须叠加」的变量（打包桌面端的 ELECTRON_RUN_AS_NODE）：
+            // 没有它时保持 env 原样透传，有它时必须基于完整环境叠加，否则子进程会丢掉 PATH。
+            // registry 最后写入：换源重试只改这一层，pnpm/npm 都认 npm_config_registry。
+            const childEnv = { ...(env ?? process.env), ...(invocation.env ?? {}) };
+            if (registry !== undefined) {
+                childEnv.npm_config_registry = registry;
+                childEnv.NPM_CONFIG_REGISTRY = registry;
+            }
             child = spawn(invocation.file, attemptArgs, {
                 cwd: invocation.cwd,
-                // invocation.env 是「必须叠加」的变量（打包桌面端的 ELECTRON_RUN_AS_NODE）：
-                // 没有它时保持 env 原样透传，有它时必须基于完整环境叠加，否则子进程会丢掉 PATH。
-                env: invocation.env === undefined ? env : { ...(env ?? process.env), ...invocation.env },
+                env: childEnv,
                 shell: invocation.useShell,
                 // detached 使子进程成为独立进程组组长：取消时能整组清理（见 stopChild），
                 // 且宿主进程崩溃后安装任务不会被连带误杀
@@ -477,7 +505,7 @@ function spawnMutation(options) {
                 task.progress += 1;
         }, 500);
         const collect = (kind, chunk) => {
-            const text = chunk.toString();
+            const text = kind === 'stdout' ? stdoutDecoder.push(chunk) : stderrDecoder.push(chunk);
             if (kind === 'stdout')
                 stdout = (stdout + text).slice(-CAPTURE_LIMIT_BYTES);
             else
@@ -536,7 +564,23 @@ function spawnMutation(options) {
         // 超时复核用基线：本次任务开始前目标是否已在 profile 里。已安装的话，超时后核对无法区分
         // 「旧版本还在」与「刚装上」，那种情形（更新超时）不冒认成功。
         const wasInstalled = action !== 'remove' && !isGlobalNpm && verifyInstalledEntry(profile, target).name !== null;
-        let result = await spawnOnce(args);
+        // 候选源：卸载不拉包、git 源装的是仓库快照，都不受 npm 镜像影响，不参与换源
+        const candidates = action === 'remove' || githubRepoOf(target) !== null ? [] : (registries ?? []);
+        let activeRegistry = candidates[0];
+        let result = await spawnOnce(args, activeRegistry);
+        // 传输层失败（超时 / 连接重置 / DNS / 5xx）才换下一个公共镜像；404、版本不存在、鉴权错误
+        // 保持原样，否则会掩盖作者侧问题或装到滞后版本。整段超时也不再换源，避免耗时翻倍。
+        for (const candidate of candidates.slice(1)) {
+            if (task?.status === 'cancelled' || result.exitCode === 0 || result.timedOut)
+                break;
+            if (!isTransportFailure(`${result.stderr}\n${result.stdout}`))
+                break;
+            if (task) {
+                pushLine(task, `[registry-fallback] ${registryHost(activeRegistry ?? '')} unreachable — retrying with ${registryHost(candidate)}`);
+            }
+            activeRegistry = candidate;
+            result = await spawnOnce(args, candidate);
+        }
         // npm 11 的 arborist peer-set bug（`Cannot read properties of null (reading 'children')`）
         // 会让 `npm install -g` 在解析阶段直接崩溃。首次失败后自动带 `--legacy-peer-deps` 重试一次：
         // 跳过 peer 自动解析即可绕过该 bug；二次尝试仍失败则保留其错误信息，不掩盖真正的原因。
@@ -547,7 +591,7 @@ function spawnMutation(options) {
                 task.attempts.push(retryExecuted);
             if (task)
                 pushLine(task, '[npm] peer-set resolution crashed npm (known npm bug) — retrying with --legacy-peer-deps');
-            result = await spawnOnce(retryArgs);
+            result = await spawnOnce(retryArgs, activeRegistry);
         }
         // 超时被强杀 ≠ 没装上：命中的安装可能已经落盘（日志里 pnpm 已打印 Done，只是 dsh 进程迟迟不退出
         // 而被我们超时掐掉）。判失败之前先复核 profile —— 目标已在依赖里、且声明分发的入口文件都在，
@@ -611,7 +655,9 @@ function spawnMutation(options) {
                         addPendingRestart(displayTarget ?? target, action === 'remove' ? 'uninstall' : 'install');
                     }
                 }
-                pushLine(task, result.timedOut ? '[timed out]' : `[exit ${result.exitCode ?? '?'}]`);
+                // 子进程一个字节都没吐时在退出行上标注：日志面板与失败上报都能看出「没有输出可排查」
+                const printedNothing = `${result.stdout}${result.stderr}`.trim() === '';
+                pushLine(task, result.timedOut ? '[timed out]' : `[exit ${result.exitCode ?? '?'}]${printedNothing ? ' (no output captured)' : ''}`);
             }
         }
         return result;
@@ -707,6 +753,23 @@ async function annotateRegistryMissing(result, options) {
         pushLine(options.task, line);
     return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
 }
+/** 安装失败且插件声明的最低 DSH 版本高于当前宿主 → 注入 [dsh-too-old] 标记。
+ *  只在失败路径上发生：peer 不满足本身通常只是警告，装成功时不该冒这个提示。
+ *  超时也算失败 —— 旧宿主上插件可能卡在半兼容状态，这个信息同样有用。 */
+async function annotateDshTooOld(result, options) {
+    if (options.action === 'remove' || result.exitCode === 0)
+        return result;
+    // 全局 npm 装的是本机 CLI 工具，不进 profile，没有宿主版本要求
+    if ((options.globalNpm ?? []).length > 0)
+        return result;
+    // 用安装实际使用的源读元数据：私有源/镜像里也能读到同一个包的声明
+    const line = await dshTooOldMarker(options.target, { registry: options.registries?.[0] });
+    if (line === null)
+        return result;
+    if (options.task && options.task.status !== 'cancelled')
+        pushLine(options.task, line);
+    return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
+}
 /**
  * 宿主自身 CLI 调不起来时的 ASCII 标记行：spawn 我们解析出的宿主入口报 ENOENT 时返回
  * `[host-spawn]`，供前端单独归因、不引导提 Issue。PATH 上的 dsh/npm 各有自己的标记，返回 null。
@@ -728,7 +791,8 @@ export function hostSpawnMarker(invocation, error) {
  */
 export async function runPluginMutation(options) {
     // operation 日志只在运行期存在（宿主结束后可能清掉），先开抓取，退出后按路径读作兜底
-    const logTap = createOperationLogTap(profileDirectory(options.profile));
+    const profileDir = profileDirectory(options.profile);
+    const logTap = createOperationLogTap(profileDir);
     let result = await spawnMutation(options);
     // allowBuilds 放行 / 装后入口校验都是 profile 专属（pnpm 装进 profile 的场景）；
     // 全局 npm 安装直接走 npm，无 pnpm allowBuilds 拦截、也不进 profile，跳过这两类恢复
@@ -791,9 +855,10 @@ export async function runPluginMutation(options) {
     // 宿主只把一行摘要（`dsh: plugin command failed; diagnostics: <path>`）回显到控制台、真正的报错
     // 写进该日志文件时，前端拿不到任何错误特征、只能归为「未知」。按该路径回捞日志尾部补进失败信息。
     // 只在输出本就不含错误码时回捞 —— pnpm 已回显报错时无需多读一次文件。
-    if (result.exitCode !== 0 && !result.timedOut && !/\bERR_[A-Z0-9_]+\b/.test(`${result.stderr}\n${result.stdout}`)) {
+    // 超时同样回捞：被强杀前 pnpm 往往已经把真实原因写进 operation 日志。
+    if ((result.exitCode !== 0 || result.timedOut) && !/\bERR_[A-Z0-9_]+\b/.test(`${result.stderr}\n${result.stdout}`)) {
         const output = `${result.stderr}\n${result.stdout}`;
-        const backfilled = tappedLog !== '' ? tappedLog : backfillOperationLog(output);
+        const backfilled = tappedLog !== '' ? tappedLog : backfillOperationLog(output, profileDir);
         if (backfilled !== null) {
             if (options.task && options.task.status !== 'cancelled') {
                 pushLine(options.task, '[pnpm log] DSH did not echo pnpm output — recovered the operation log from disk');
@@ -803,13 +868,24 @@ export async function runPluginMutation(options) {
             }
             result = { ...result, stderr: `${result.stderr}\n${backfilled}` };
         }
-        else if (options.task && options.task.status !== 'cancelled' && operationLogPathOf(output) !== null) {
-            // 诊断路径在、日志却取不到：留一行证据，否则下一次同类上报又只剩宿主那句摘要、看不出根因
-            pushLine(options.task, '[pnpm log] the host-reported diagnostics log could not be read from disk (missing, empty, or unreadable)');
+        else if (options.task && options.task.status !== 'cancelled') {
+            if (operationLogPathOf(output) !== null) {
+                // 诊断路径在、日志却取不到：留一行证据，否则下一次同类上报又只剩宿主那句摘要、看不出根因
+                pushLine(options.task, '[pnpm log] the host-reported diagnostics log could not be read from disk (missing, empty, or unreadable)');
+            }
+            else if (!hasSubstantiveOutput(output)) {
+                // 宿主连 diagnostics 路径都没回显：显式留痕，避免上报正文只剩一个退出码
+                const what = result.timedOut
+                    ? 'printed nothing before the timeout'
+                    : `exited with code ${result.exitCode ?? '?'} without printing anything`;
+                pushLine(options.task, `[no-output] the dsh CLI ${what}, and no pnpm log was written under .plugin-manager/logs — attach ~/.dsh/profiles/${options.profile}/hub.log when reporting this`);
+            }
         }
     }
     // 包在 registry 不存在（404）→ 官方源复查，区分「作者的依赖缺失/包被删」与「本机镜像源滞后」
     result = await annotateRegistryMissing(result, options);
+    // 插件声明的最低 DSH 版本高于当前宿主 → 追加 [dsh-too-old] 标记，前端提示先升级 DSH
+    result = await annotateDshTooOld(result, options);
     // npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 追加 [npm-too-low] 标记，前端据此给准确原因
     return annotateNpmTooLow(result, options);
 }

package/lib/services/settings.js

@@ -13,6 +13,7 @@ export const DEFAULT_SETTINGS = {
     checkUpdatesOnStart: true,
     proxy: '',
     npmRegistry: '',
+    registryFallback: true,
     enableNpmInstall: true,
     logPath: '',
 };

package/lib/types/services/host-version.d.ts

@@ -0,0 +1,10 @@
+/** 从命令输出里抽出版本号本体：pnpm/npm 直接打印 `11.7.0`，而 `git --version` 打印
+ *  `git version 2.55.0.windows.5` —— 原样取首行会让 issue 正文拼成 `vgit version …`。
+ *  只取版本号，顺带兼容 `v1.2.3` 这类自带前缀的输出。 */
+export declare function versionOf(output: string): string | null;
+/** 探测命令行工具版本：未安装 / 不在 PATH / 超时一律 null。
+ *  Windows 上 pnpm/npm 是 .cmd shim，不走 shell 起不来；参数是固定的 `--version`，没有注入面。 */
+export declare function toolVersion(cmd: string, args: string[]): string | null;
+/** 宿主 dsh 版本：优先 `dsh --version`；拿不到再从入口 `process.argv[1]` 向上找 package.json
+ *  （dsh 不在 PATH 时兜底）。探测成功即缓存，失败不缓存以便下次重试。 */
+export declare function hostDshVersion(): string | null;

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

@@ -0,0 +1,4 @@
+export declare class OutputDecoder {
+    private readonly utf8;
+    push(chunk: Buffer): string;
+}

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

@@ -0,0 +1,19 @@
+/** 从安装目标里取 npm 包名：`@scope/pkg@1.2.3` → `@scope/pkg`。
+ *  git / URL / 本地路径等非 npm 目标返回 null。 */
+export declare function npmNameOf(target: string): string | null;
+/** `0.2.1-rc.1` / `^0.2.1` / `>=0.2.0 <0.3.0` → [0,2,1]；解析不出返回 null。
+ *  只取版本三段：DSH 的 prerelease 序号（rc.1）不参与「太低」判断，避免比较误差。 */
+export declare function versionTriple(raw: string): [number, number, number] | null;
+/** 插件声明的最低 DSH 版本：engines.dsh 与 peerDependencies 里 @deepseek-ai/dsh-* 的下限取最大。
+ *  返回原始声明文本（如 `^0.2.1-rc.1`）供提示直接展示；没有声明返回 null。 */
+export declare function dshFloorOf(manifest: unknown): string | null;
+/**
+ * 产出「插件要求更高的 DSH」标记行；没有声明、读不到元数据、宿主版本未知或已满足时返回 null。
+ * 用版本级 manifest（`/<pkg>/latest`）：packument 的精简形态不带 peerDependencies。
+ */
+export declare function dshTooOldMarker(target: string, opts?: {
+    currentVersion?: string | null;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    registry?: string;
+}): Promise<string | null>;

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

@@ -68,6 +68,10 @@ export interface QueueItem {
         env?: NodeJS.ProcessEnv;
         globalNpm?: string[];
         installChannel?: 'npm';
+        /** npm 源候选（首选在前）：传输层失败时按顺序换源重试 */
+        registries?: string[];
+        /** 精确安装 spec（Hub 自我更新钉版本） */
+        installSpec?: string;
     };
 }
 /**

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

@@ -1,14 +1,20 @@
 /**
  * 从 DSH 输出里解析 operation 日志路径（`diagnostics: <path>`）。
- * 只认 DSH 的 operation 日志：路径含 `.plugin-manager` 且以 `pnpm.log` 结尾；
- * 不是这种路径（或压根没有该行）返回 null，调用方据此跳过回捞。
+ * 去掉首尾引号与句末标点（不同版本/语言的摘要行尾部可能带 `。`、`.`、`)`）；
+ * 相对路径原样返回，由读取方按 profile 目录解析。
  */
 export declare function operationLogPathOf(output: string): string | null;
 /**
  * 回捞 operation 日志尾部，作为失败详情返回；拿不到（无路径 / 文件不存在 / 读失败 /
- * 内容为空）返回 null。尾部截到与子进程输出相同的上限，避免超大日志撑爆内存与消息。
+ * 内容为空 / 路径越界）返回 null。尾部截到与子进程输出相同的上限。
  */
-export declare function backfillOperationLog(output: string): string | null;
+export declare function backfillOperationLog(output: string, profileDir?: string): string | null;
+/**
+ * 输出里是否有 dsh 自己的内容 —— 只有 `[exit N]`、`[install-channel]`、`[timed out]`
+ * 这类本队列自己打的标记时返回 false。用于把「宿主什么都没回显」的失败显式留痕，
+ * 否则上报正文只剩退出码，无从排查。
+ */
+export declare function hasSubstantiveOutput(output: string): boolean;
 /**
  * 运行期抓取：宿主的 operation 日志只在命令运行期间存在，结束后可能被清理，
  * 退出后再按路径读往往已经拿不到。这里在安装过程中轮询 profile 下最新的

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

@@ -0,0 +1,18 @@
+/** 去掉尾部斜杠，避免同一源因写法不同被当成两个候选。 */
+export declare function normalizeRegistry(value: string): string;
+/** 是否属于允许自动切换的公共源白名单。 */
+export declare function isPublicRegistry(value: string): boolean;
+/**
+ * 依次尝试的源：显式配置 → 本机 npm 配置 → 官方源。
+ * 只有公共源才追加后备（最多 3 个）；关闭降级或源不在白名单时只返回它自己。
+ */
+export declare function registryCandidates(configured: string, userRegistry: string, enabled: boolean): string[];
+/** 本机 npm 实际生效的源（含 profile 目录的 .npmrc）；读不到返回空串。 */
+export declare function userNpmRegistry(cwd: string): string;
+/**
+ * 传输层失败才值得换源：超时、连接重置、DNS、5xx。
+ * 404 / 版本不存在 / 鉴权失败必须保持原样 —— 换源只会掩盖作者侧问题或装到滞后版本。
+ */
+export declare function isTransportFailure(text: string): boolean;
+/** 日志里展示用的源主机名（不打印可能带凭据的完整 URL）。 */
+export declare function registryHost(value: string): string;

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

@@ -38,6 +38,15 @@ export declare function cancelTask(id: number): boolean;
  * 导出供单测覆盖路径推导。
  */
 export declare function desktopCliBootstrap(entry: string): string | null;
+/**
+ * 传给 CLI 的安装目标：钉住版本优先（Hub 自我更新提示的是已过供应链门禁的版本），
+ * 其次更新走 `@latest`，git 源与全局 npm 安装保持原样。
+ */
+export declare function npmInstallTargetOf(target: string, opts: {
+    update: boolean;
+    global: boolean;
+    pinned?: string;
+}): string;
 /**
  * 插件变更入队并返回其任务。任务严格串行：队列 worker 只在上一个结束后才启动下一个。
  * 完成前可通过 `getTask(id)` / `activeTask()` 查看进度。
@@ -62,6 +71,11 @@ export declare function startPluginMutation(options: {
     /** 自定义安装入口渠道（NPM 包卡片）：任务输出行与系统日志据此溯源「从哪个入口发起」；
      *  目录插件安装不传 */
     installChannel?: 'npm';
+    /** npm 源候选（首选在前）：传输层失败时按顺序换源重试，空/单个表示不降级 */
+    registries?: string[];
+    /** 精确安装 spec（如 `dsh-plugin@2.0.5`）：Hub 自我更新提示的是已过供应链门禁的版本，
+     *  必须钉住安装，不能再用 @latest 被带回门禁内的最新版 */
+    installSpec?: string;
 }): InstallTask;
 /**
  * 安装后校验已装包里 package.json 声明的文件（main / exports["."].default 与
@@ -101,4 +115,8 @@ export declare function runPluginMutation(options: {
     loader?: LoaderHandle;
     /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
     globalNpm?: string[];
+    /** npm 源候选（首选在前）：传输层失败时按顺序换源重试 */
+    registries?: string[];
+    /** 精确安装 spec（如 `dsh-plugin@2.0.5`）：见 startPluginMutation 同名说明 */
+    installSpec?: string;
 }): Promise<InstallResult>;

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

@@ -3,8 +3,10 @@ export interface HubSettings {
     checkUpdatesOnStart: boolean;
     /** HTTP(S) 代理地址，用于 npm / git / 目录请求（空串 = 直连） */
     proxy: string;
-    /** npm 镜像源 registry 地址（空串 = 未配置，跟随用户本机 npm 配置，本插件不注入任何 registry） */
+    /** npm 镜像源 registry 地址（空串 = 未配置，跟随用户本机 npm 配置） */
     npmRegistry: string;
+    /** 公共源传输失败时自动换下一个镜像重试（自定义/内网源不切换） */
+    registryFallback: boolean;
     /** 启用命令行安装 NPM 包（默认开；关掉后输入 npm 包名安装被拦截） */
     enableNpmInstall: boolean;
     /** 日志存放位置覆盖（空串 = 默认 ~/.dsh/profiles/<profile>/hub.log；可填目录或 .log 文件路径） */

package/package.json

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

package/src/client/components/PluginHubSection.tsx

@@ -76,6 +76,9 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
   const [confirmPlugin, setConfirmPlugin] = useState<HubPlugin | null>(null)
   /** 弹窗动作是否为「更新」：已安装插件点「更新」→ 走同一条 add 命令原位覆盖重装，文案区分安装/更新 */
   const [confirmIsUpdate, setConfirmIsUpdate] = useState(false)
+  /** Hub 自我更新指定的精确版本：连续发版时提示的是「已过供应链门禁」的旧一版，
+   *  安装必须钉在该版本上，否则又会被 @latest 带回门禁内的最新版。 */
+  const [confirmPinVersion, setConfirmPinVersion] = useState<string | null>(null)
   /** 命令行安装确认弹窗：记录待安装的裸目标（npm 包名）——
    *  与应用商店同一套确认/进度/结果弹窗，提供时 plugin 传 null 走 customTarget 模式 */
   const [confirmCustomTarget, setConfirmCustomTarget] = useState<string | null>(null)
@@ -450,6 +453,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
           onInstall: (p, opts) => {
             setInstallDone(false)
             setConfirmIsUpdate(opts?.update ?? false)
+            setConfirmPinVersion(null)
             // 与卸载一致：重置弹窗关联任务，避免新弹窗误匹配到进行中的任务而禁用安装按钮
             queue.clearModalTask()
             setConfirmPlugin(p)
@@ -484,6 +488,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
               setDetailItem(null)
               setInstallDone(false)
               setConfirmIsUpdate(true)
+              setConfirmPinVersion(null)
               queue.clearModalTask()
               setConfirmPlugin(item.plugin)
             },
@@ -547,7 +552,8 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
     // 暂缓提示显示同一标题但只给「稍后再说」，无更新显示当前版本 + 记录 + 「已是最新」。
     // 版本号与本机版本一律由 hubUpdateState / hubCurrentVersion 决定，不用远端版号冒充本机。
     showHubUpdate && h(HubUpdateModal, {
-      info: catalog.hubUpdateInfo ?? { version: PLUGIN_VERSION },
+      // 提示目标是「已过供应链门禁」的版本，可能不是 latest —— 展示它与它的变更记录
+      info: catalog.hubUpdateTarget ?? catalog.hubUpdateInfo ?? { version: PLUGIN_VERSION },
       state: catalog.hubUpdateState,
       currentVersion: catalog.hubCurrentVersion,
       lang,
@@ -559,6 +565,8 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
         if (hubEntry) {
           setInstallDone(false)
           setConfirmIsUpdate(true)
+          // 钉住本次提示的版本：最新版可能仍在门禁内，@latest 会被 pnpm 拒绝
+          setConfirmPinVersion(catalog.hubUpdateTarget?.version ?? null)
           queue.clearModalTask()
           setConfirmPlugin(hubEntry)
         }
@@ -595,6 +603,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
         setShowNotifications(false)
         setInstallDone(false)
         setConfirmIsUpdate(true)
+        setConfirmPinVersion(null)
         queue.clearModalTask()
         setConfirmPlugin(plugin)
       },
@@ -673,7 +682,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
         if (reload) window.location.reload()
       },
       onCopy: () => copyCommand(confirmPlugin),
-      onInstall: () => queue.installNow(confirmPlugin, confirmIsUpdate ? { update: true } : undefined),
+      onInstall: () => queue.installNow(confirmPlugin, confirmIsUpdate ? { update: true, pinVersion: confirmPinVersion ?? undefined } : undefined),
       // 重启：结果视图「立即重启」也会中断进行中的任务 → 先弹重启确认弹窗
       onRestart: () => setShowRestartConfirm(true),
     }),

package/src/client/components/modals/NotificationsModal.tsx

@@ -14,7 +14,7 @@ import type { MouseEvent } from 'react'
 import styles from '../../styles/Modal.module.css'
 import type { EnvInfo, Translate } from '../../types.ts'
 import type { NotificationRecord } from '../../logic/failures.ts'
-import { actionOfRecord, classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
+import { actionOfRecord, classifyFailure, formatFailureMessage, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf, authRegistryHostOf, exclusiveProfileOf, desktopCliFallbackOf, dshTooOldInfoOf, missingLocalDirOf } from '../../logic/failures.ts'
 import type { PendingRestart, QueueTask } from '../../hooks/useTaskQueue.ts'
 import { pluginIssueUrl, pluginSiteUrl, hubIssueUrl } from '../../logic/urls.ts'
 import { CloseIcon } from '../ui/icons.tsx'
@@ -306,6 +306,11 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 给 .npmrc 豁免指引，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failPnpmWorkspaceHint'))
                     }
+                    if (kind === 'pnpmVirtualStore') {
+                      // profile 的 modules 目录与当前 pnpm 的 virtual-store-dir-max-length 不一致：
+                      // 该 profile 内的安装/卸载都会失败 —— 重建 modules 目录或统一配置即可，不引导提 Issue
+                      return h('div', { className: styles.failPrepareHint }, t('failPnpmVirtualStoreHint'))
+                    }
                     if (kind === 'pnpmStore') {
                       // pnpm 存在但 store 大版本不匹配（ERR_PNPM_UNEXPECTED_STORE）：profile 目录的依赖是
                       // 另一大版本 pnpm 装的，当前 pnpm 不认，任何插件装进该 profile 都会失败 ——
@@ -372,10 +377,13 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       return h('div', { className: styles.failPrepareHint }, t('failRegistryVersionStaleHint'))
                     }
                     if (kind === 'pnpmLinkedDirMissing') {
-                      // profile 里留着指向不存在目录的本地依赖（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND）：
-                      // 常见于 link:/本地路径装过开发中的插件、之后目录被删；与本次要装的插件无关
-                      // —— 给删除悬空条目的指引，不引导提 Issue
-                      return h('div', { className: styles.failPrepareHint }, t('failPnpmLinkedDirMissingHint'))
+                      // profile 里留着指向不存在目录的本地依赖（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND /
+                      // pnpm ENOENT lstat）：点名缺失目录 + 删除悬空条目，不引导提 Issue
+                      const dir = missingLocalDirOf(r.message)
+                      return h('div', null, [
+                        dir ? h('div', { className: styles.failNetworkTarget }, t('failLinkedDirTarget', { path: dir })) : null,
+                        h('div', { className: styles.failPrepareHint }, t('failPnpmLinkedDirMissingHint')),
+                      ])
                     }
                     if (kind === 'fileLocked') {
                       // profile 里的文件被其他进程占用（Windows os error 32）：通常是宿主或杀毒软件
@@ -397,6 +405,55 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 安装流程，与插件无关 —— 引导从本机地址重新打开市场，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failOriginRejectedHint', { profile: env?.profile ?? '<profile>' }))
                     }
+                    if (kind === 'profileExclusive') {
+                      // desktop profile 只能由桌面应用管理：外部 dsh CLI 被宿主拒绝，属环境约束。
+                      // 带 [desktop-cli-fallback] 则是安装器没找到应用内 CLI 引导脚本 —— 我们的问题，给反馈入口
+                      const profile = exclusiveProfileOf(r.message)
+                      const ourBug = desktopCliFallbackOf(r.message)
+                      return h('div', null, [
+                        h('div', { className: styles.failPrepareHint },
+                          t(profile ? 'failProfileExclusiveHint' : 'failProfileExclusiveHintNoProfile', profile ? { profile } : undefined)),
+                        ourBug ? h('div', { className: styles.failPrepareHint }, t('failDesktopCliFallbackHint')) : null,
+                        ourBug ? h('a', {
+                          className: styles.failBigIssue,
+                          href: hubIssueUrl(shownRepo || r.repo, r.message, env, r.command, r.attempts, 'triage', action),
+                          target: '_blank',
+                          rel: 'noopener noreferrer',
+                          title: t('failHubIssueHint'),
+                        }, t('failIssueBig')) : null,
+                      ])
+                    }
+                    if (kind === 'registryAuth') {
+                      // npm 源返回 401/403：私有源需要凭据，或当前网络/IP 不被允许 —— 本机环境问题，
+                      // 给「配认证 / 换回官方源 / 切公共镜像」指引，不引导提 Issue
+                      const host = authRegistryHostOf(r.message)
+                      return h('div', { className: styles.failPrepareHint },
+                        t(host ? 'failRegistryAuthHint' : 'failRegistryAuthHintNoHost', host ? { host } : undefined))
+                    }
+                    if (kind === 'dshTooOld') {
+                      // 插件要求的 DSH 下限高于本机宿主：升级 DSH 即可，不属作者、也不属插件中心
+                      const info = dshTooOldInfoOf(r.message)
+                      return h('div', { className: styles.failPrepareHint },
+                        t('failDshTooOldHint', info ?? { pkg: shownRepo || r.repo || 'plugin', floor: '?', current: '?' }))
+                    }
+                    if (kind === 'localEnv') {
+                      // 未命中具体成因、但特征指向本机环境：给通用自查清单 + 系统诊断，默认不推给我们，
+                      // 只留小字反馈入口（判据是我们自己的启发式，可能误判）
+                      return h('div', null, [
+                        h('div', { className: styles.failPrepareHint }, t('failLocalEnvHint')),
+                        onRunDiagnostics ? h('button', { className: styles.failDiagBtn, onClick: onRunDiagnostics }, t('failNetworkRunDiag')) : null,
+                        h('div', null, [
+                          h('div', { className: styles.failPrepareHint }, t('failMisjudgeHint')),
+                          h('a', {
+                            className: styles.failMisjudgeLink,
+                            href: hubIssueUrl(shownRepo || r.repo, r.message, env, r.command, r.attempts, 'triage', action),
+                            target: '_blank',
+                            rel: 'noopener noreferrer',
+                            title: t('failHubIssueHint'),
+                          }, t('failMisjudgeLink')),
+                        ]),
+                      ])
+                    }
                     if (kind === 'network') {
                       // 安装前网络探测 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
                       // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，