dsh-plugin 2.0.6 → 2.1.0

package/lib/http/install.js

@@ -11,10 +11,12 @@ import { recordResolvedNpmPackage } from '../services/profile/installed-versions
 import { isDshNpmPackageForRepo } from '../services/install/npm-resolve.js';
 import { probeUrl, systemProxy } from '../services/probe.js';
 import { loadSettings } from '../services/settings.js';
+import { registryCandidates, registryHost, userNpmRegistry } from '../services/install/registry-fallback.js';
+import { profileDirectory } from '../services/profile/profile.js';
 import { readInstalled } from './catalog.js';
 import { COMMAND_TIMEOUT_MS, readJsonBody, requireTrustedPost, sendJson } from './shared.js';
 /** 安装/卸载 CLI 的子进程环境：透传宿主环境并注入 HTTP(S) 代理，
- *  代理来源与诊断一致（设置代理 → 系统代理 → 宿主 env）；不注入 npm registry，沿用用户本机 npm 配置。 */
+ *  代理来源与诊断一致（设置代理 → 系统代理 → 宿主 env）；registry 由任务队列按候选源逐次注入。 */
 function mutationEnv(settings) {
     const env = { ...process.env, CI: 'true' };
     const proxy = settings.proxy !== '' ? settings.proxy : (systemProxy() ?? '');
@@ -63,6 +65,13 @@ export function registerInstallRoutes(webServer, profile, loader) {
                     const lang = typeof body === 'object' && body !== null && body.lang === 'en'
                         ? 'en'
                         : 'zh';
+                    // 代理口径与诊断/安装通道一致：设置里的代理 → 系统代理 → 环境变量 → 直连。
+                    const effectiveProxy = settings.proxy !== ''
+                        ? settings.proxy
+                        : (systemProxy() ?? process.env.HTTPS_PROXY ?? process.env.https_proxy ?? '');
+                    // 安装用的 npm 源：设置里显式选择优先；未配置时读本机 npm 配置（与诊断同口径）。
+                    // 只有公共源允许失败后换源；自定义/内网源保持单一候选，避免私有包名泄露给公共源。
+                    const registries = registryCandidates(settings.npmRegistry, settings.npmRegistry === '' ? userNpmRegistry(profileDirectory(profile)) : '', settings.registryFallback);
                     // 全局 npm 安装（`npm install -g <pkgs>`）：不进任何 profile、无需宿主重启。
                     // 包列表优先取 body.globalNpm，兜底从 rawRepo 解析，保证直接调 API 传完整命令也能识别。
                     const bodyGlobalNpm = Array.isArray(body.globalNpm)
@@ -94,6 +103,8 @@ export function registerInstallRoutes(webServer, profile, loader) {
                             globalNpm,
                             timeoutMs: COMMAND_TIMEOUT_MS,
                             env: mutationEnv(settings),
+                            // 候选源（首选在前）：任务内遇到传输层失败时按顺序换源重试
+                            registries,
                             // 全局 npm 安装由 NPM 包卡片/官方命令发起：日志体现入口渠道
                             installChannel: installChannel ?? 'npm',
                         });
@@ -106,12 +117,17 @@ export function registerInstallRoutes(webServer, profile, loader) {
                         return;
                     }
                     const target = rawRepo;
+                    // 钉住精确版本（Hub 自我更新）：最新版可能仍在 pnpm 供应链门禁内，
+                    // 客户端提示的是「已过门禁」的版本，服务端必须按该版本安装而不是 @latest。
+                    const pinVersion = typeof body.version === 'string'
+                        ? body.version.trim()
+                        : '';
+                    if (pinVersion !== '' && !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/.test(pinVersion)) {
+                        sendJson(response, 400, { error: 'invalid version' });
+                        return;
+                    }
                     // 已尝试的安装方式（供失败提 Issue 预填）：保持为空
                     const attempts = [];
-                    // 代理口径与诊断/安装通道一致：设置里的代理 → 系统代理 → 环境变量 → 直连。
-                    const effectiveProxy = settings.proxy !== ''
-                        ? settings.proxy
-                        : (systemProxy() ?? process.env.HTTPS_PROXY ?? process.env.https_proxy ?? '');
                     // 目录插件安装：目录数据可能滞后于打包拆分，确认目录下发的 npm 目标确为该仓库的 DSH 包，
                     // 命中则记录 repo → 包名映射，客户端据此把依赖 key 匹配回仓库、列表立即显示「已安装」。
                     const catalogRepo = source === 'catalog' ? githubRepoOf(displayRepo) : null;
@@ -137,18 +153,30 @@ export function registerInstallRoutes(webServer, profile, loader) {
                         return;
                     }
                     // 安装前网络探测：探 registry 根而非具体包（404 是「包不存在」而非网络不通）；仅新安装执行，更新跳过。
-                    // 不通则 400 拦下并打 [network] 标记，客户端据此提示网络问题，而非插件问题。
+                    // 首选源不通时按候选顺序继续探下一个，能通的那个提到首位供实际安装使用。
+                    // 全部不通则 400 拦下并打 [network] 标记，客户端据此提示网络问题，而非插件问题。
+                    let ordered = registries;
                     if (already === null) {
-                        const probeTarget = `${(settings.npmRegistry.replace(/\/+$/, '') || 'https://registry.npmjs.org')}/`;
-                        const net = await probeUrl(probeTarget, effectiveProxy, 6000);
-                        if (!net.ok) {
+                        const tried = [];
+                        let chosen = null;
+                        for (const candidate of registries) {
+                            tried.push(candidate);
+                            const net = await probeUrl(`${candidate}/`, effectiveProxy, 6000);
+                            if (net.ok) {
+                                chosen = candidate;
+                                break;
+                            }
+                        }
+                        if (chosen === null) {
                             // 错误消息按界面语言输出，让用户看清是网络问题而非插件问题
+                            const hosts = tried.map(registryHost).join(' → ');
                             const error = lang === 'zh'
-                                ? `[network] 安装已中止：安装前无法连接到 npm 源（${probeTarget}）—— 您的网络似乎不通或被拦截（断网 / DNS 解析失败 / 防火墙 / 代理配置问题）。这不是插件本身的问题，请检查网络连接或代理设置，运行「系统诊断」检测各通道连通性后重试。`
-                                : `[network] install aborted: cannot reach the npm registry (${probeTarget}) before install — your network connection appears to be down or blocked (DNS / proxy / firewall). This is not a problem with the plugin itself. Check your connection or proxy settings, run the connectivity diagnostic, then retry.`;
+                                ? `[network] 安装已中止：安装前无法连接到 npm 源（${hosts}）—— 您的网络似乎不通或被拦截（断网 / DNS 解析失败 / 防火墙 / 代理配置问题）。这不是插件本身的问题，请检查网络连接或代理设置，运行「系统诊断」检测各通道连通性后重试。`
+                                : `[network] install aborted: cannot reach the npm registry (${hosts}) before install — your network connection appears to be down or blocked (DNS / proxy / firewall). This is not a problem with the plugin itself. Check your connection or proxy settings, run the connectivity diagnostic, then retry.`;
                             sendJson(response, 400, { error, attempts });
                             return;
                         }
+                        ordered = [chosen, ...registries.filter((r) => r !== chosen)];
                     }
                     // 入队前复检：网络探测的 await 期间并发请求可能已通过上方检查，而此处到 startPluginMutation
                     // 之间无 await，JS 单线程保证同一目标至多一个任务，杜绝双击/并发双任务。
@@ -171,6 +199,9 @@ export function registerInstallRoutes(webServer, profile, loader) {
                         loader,
                         timeoutMs: COMMAND_TIMEOUT_MS,
                         env: mutationEnv(settings),
+                        // 候选源（首选在前）：任务内遇到传输层失败时按顺序换源重试
+                        registries: ordered,
+                        installSpec: pinVersion !== '' ? `${target}@${pinVersion}` : undefined,
                         // 自定义安装入口渠道：日志/报错据此溯源
                         installChannel,
                     });

package/lib/http/settings.js

@@ -28,7 +28,7 @@ export function registerSettingsRoutes(webServer, profile) {
                     // 白名单字段：只接受已知设置项，防客户端把任意键写进文件
                     const patch = {};
                     const source = typeof body === 'object' && body !== null ? body : {};
-                    for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'npmRegistry', 'proxy', 'logPath']) {
+                    for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'npmRegistry', 'registryFallback', 'proxy', 'logPath']) {
                         if (source[key] !== undefined)
                             patch[key] = source[key];
                     }

package/lib/services/install/decode-output.js

@@ -0,0 +1,23 @@
+/**
+ * 子进程输出解码：默认 UTF-8；出现替换字符（中文 Windows 的 GBK 输出）时改用 GBK 重解。
+ * 用 StringDecoder 跨 chunk 缓冲，避免 UTF-8 多字节字符被 chunk 边界切断后误判为 GBK。
+ */
+import { StringDecoder } from 'node:string_decoder';
+export class OutputDecoder {
+    utf8 = new StringDecoder('utf8');
+    push(chunk) {
+        const text = this.utf8.write(chunk);
+        if (!text.includes('\uFFFD'))
+            return text;
+        try {
+            const gbk = new TextDecoder('gbk').decode(chunk);
+            // GBK 能完整解出且含中文才采用：纯 ASCII 或仍有替换字符时保持 UTF-8 结果
+            if (!gbk.includes('\uFFFD') && /[\u4e00-\u9fff]/.test(gbk))
+                return gbk;
+        }
+        catch {
+            // 无完整 ICU（TextDecoder 不支持 gbk）时退回 UTF-8 结果
+        }
+        return text;
+    }
+}

package/lib/services/install/operation-log.js

@@ -6,36 +6,75 @@
  * 失败回捞：DSH 有时只把一行摘要（`dsh: plugin command failed; diagnostics: <path>`）
  * 回显到控制台，真正的 pnpm 报错写进该路径的 operation 日志。这里从输出里解析出该路径
  * 并读取其尾部，补进失败信息 —— 否则前端拿不到任何错误特征，只能把失败归为「未知」。
- * 只允许读 DSH 自己的 operation 日志（路径含 .plugin-manager 且以 pnpm.log 结尾），
+ * 只允许读 profile 目录下的 pnpm.log（dsh 自己的 operation 日志），
  * 防止插件把任意路径打印进日志造成越权读取；任何异常都静默降级（返回 null），
  * 不改变原有失败处理。
  */
 import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join, resolve, sep } from 'node:path';
 import { CAPTURE_LIMIT_BYTES } from './install-types.js';
+/** 去掉 ANSI 颜色码：宿主的摘要行可能带终端着色，直接匹配路径会失败。 */
+function stripAnsi(text) {
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
 /**
  * 从 DSH 输出里解析 operation 日志路径（`diagnostics: <path>`）。
- * 只认 DSH 的 operation 日志：路径含 `.plugin-manager` 且以 `pnpm.log` 结尾；
- * 不是这种路径（或压根没有该行）返回 null，调用方据此跳过回捞。
+ * 去掉首尾引号与句末标点（不同版本/语言的摘要行尾部可能带 `。`、`.`、`)`）；
+ * 相对路径原样返回，由读取方按 profile 目录解析。
  */
 export function operationLogPathOf(output) {
     for (const raw of output.split(/\r?\n/)) {
-        const m = /diagnostics:\s*"?(.+?)"?\s*$/i.exec(raw.trim());
+        // 兼容纯文本与 JSON 包裹两种形态：`diagnostics: <path>` / `"diagnostics": "<path>"}`
+        const m = /"?diagnostics"?\s*:\s*(.+)$/i.exec(stripAnsi(raw).trim());
         if (m === null)
             continue;
-        const path = m[1].trim();
-        if (!path.includes('.plugin-manager') || !path.toLowerCase().endsWith('pnpm.log'))
+        let path = m[1]
+            .trim()
+            .replace(/[.,;:，。；、)\]}]+$/, '')
+            .trim();
+        // JSON 形态：引号包裹且反斜杠被转义过，按字符串字面量还原；普通文本里的引号直接剥掉
+        if (path.startsWith('"') && path.endsWith('"')) {
+            try {
+                const parsed = JSON.parse(path);
+                if (typeof parsed === 'string')
+                    path = parsed;
+            }
+            catch {
+                path = path.slice(1, -1);
+            }
+        }
+        path = path.trim();
+        // URL 不是本地日志：避免把网络地址当文件读
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path))
             continue;
-        return path;
+        if (path.toLowerCase().endsWith('pnpm.log'))
+            return path;
     }
     return null;
 }
+/**
+ * 只允许读 profile 目录下的 pnpm.log（dsh 自己的操作日志）：
+ * 绝对路径必须落在该目录内，相对路径按该目录解析。
+ * 未提供 profileDir 时退回旧口径（路径须含 .plugin-manager），防止插件打印任意路径造成越权读取。
+ */
+function allowedLogPath(raw, profileDir) {
+    const path = resolve(profileDir ?? '', raw);
+    if (basename(path).toLowerCase() !== 'pnpm.log')
+        return null;
+    if (profileDir === undefined)
+        return path.includes('.plugin-manager') ? path : null;
+    const root = resolve(profileDir);
+    return path.startsWith(`${root}${sep}`) ? path : null;
+}
 /**
  * 回捞 operation 日志尾部，作为失败详情返回；拿不到（无路径 / 文件不存在 / 读失败 /
- * 内容为空）返回 null。尾部截到与子进程输出相同的上限，避免超大日志撑爆内存与消息。
+ * 内容为空 / 路径越界）返回 null。尾部截到与子进程输出相同的上限。
  */
-export function backfillOperationLog(output) {
-    const path = operationLogPathOf(output);
+export function backfillOperationLog(output, profileDir) {
+    const raw = operationLogPathOf(output);
+    if (raw === null)
+        return null;
+    const path = allowedLogPath(raw, profileDir);
     if (path === null)
         return null;
     try {
@@ -48,6 +87,17 @@ export function backfillOperationLog(output) {
         return null;
     }
 }
+/**
+ * 输出里是否有 dsh 自己的内容 —— 只有 `[exit N]`、`[install-channel]`、`[timed out]`
+ * 这类本队列自己打的标记时返回 false。用于把「宿主什么都没回显」的失败显式留痕，
+ * 否则上报正文只剩退出码，无从排查。
+ */
+export function hasSubstantiveOutput(output) {
+    return output.split(/\r?\n/).some((raw) => {
+        const line = raw.trim();
+        return line !== '' && !/^\[(?:exit\b|timed out\]|install-channel\]|stale pipe\]|error\]|pnpm log\])/.test(line);
+    });
+}
 /**
  * 运行期抓取：宿主的 operation 日志只在命令运行期间存在，结束后可能被清理，
  * 退出后再按路径读往往已经拿不到。这里在安装过程中轮询 profile 下最新的

package/lib/services/install/registry-fallback.js

@@ -0,0 +1,89 @@
+/**
+ * npm 源降级：当前源是公共镜像时，传输层失败后按「当前源 → 官方 → npmmirror」
+ * 自动换源重试；自定义/内网源不降级，避免私有包名泄露给公共源。
+ */
+import { spawnSync } from 'node:child_process';
+/** 允许自动切换的公共源：只放官方与大厂/高校镜像。 */
+const PUBLIC_REGISTRIES = [
+    'https://registry.npmjs.org',
+    'https://registry.npmmirror.com',
+    'https://mirrors.cloud.tencent.com/npm',
+    'https://mirrors.tuna.tsinghua.edu.cn/npm',
+];
+const PUBLIC_HOSTS = new Set([
+    'registry.npmjs.org',
+    'registry.npmmirror.com',
+    'mirrors.cloud.tencent.com',
+    'mirrors.tuna.tsinghua.edu.cn',
+]);
+/** 去掉尾部斜杠，避免同一源因写法不同被当成两个候选。 */
+export function normalizeRegistry(value) {
+    return value.trim().replace(/\/+$/, '');
+}
+/** 是否属于允许自动切换的公共源白名单。 */
+export function isPublicRegistry(value) {
+    const v = normalizeRegistry(value);
+    if (!/^https?:\/\//i.test(v))
+        return false;
+    try {
+        return PUBLIC_HOSTS.has(new URL(v).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 依次尝试的源：显式配置 → 本机 npm 配置 → 官方源。
+ * 只有公共源才追加后备（最多 3 个）；关闭降级或源不在白名单时只返回它自己。
+ */
+export function registryCandidates(configured, userRegistry, enabled) {
+    const base = normalizeRegistry(configured) || normalizeRegistry(userRegistry) || PUBLIC_REGISTRIES[0];
+    if (!enabled || !isPublicRegistry(base))
+        return [base];
+    const out = [base];
+    for (const candidate of PUBLIC_REGISTRIES) {
+        if (out.length >= 3)
+            break;
+        if (!out.includes(candidate))
+            out.push(candidate);
+    }
+    return out;
+}
+/** 本机 npm 实际生效的源（含 profile 目录的 .npmrc）；读不到返回空串。 */
+export function userNpmRegistry(cwd) {
+    try {
+        const res = spawnSync('npm', ['config', 'get', 'registry'], {
+            cwd,
+            encoding: 'utf8',
+            timeout: 3000,
+            shell: process.platform === 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (res.status !== 0)
+            return '';
+        const value = (res.stdout ?? '').trim();
+        return /^https?:\/\//i.test(value) ? normalizeRegistry(value) : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 传输层失败才值得换源：超时、连接重置、DNS、5xx。
+ * 404 / 版本不存在 / 鉴权失败必须保持原样 —— 换源只会掩盖作者侧问题或装到滞后版本。
+ */
+export function isTransportFailure(text) {
+    if (/\b(?:ERR_PNPM_FETCH_404|E404|ERR_PNPM_NO_MATCHING_VERSION|ETARGET|ERR_PNPM_FETCH_401|ERR_PNPM_FETCH_403|E401|E403)\b/i.test(text)) {
+        return false;
+    }
+    return /\b(?:ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|EPIPE)\b|socket hang up|getaddrinfo|network request failed|connect timeout|request to .+ failed|FetchError|ERR_PNPM_FETCH_5\d\d|ERR_PNPM_META_FETCH_FAIL/i.test(text);
+}
+/** 日志里展示用的源主机名（不打印可能带凭据的完整 URL）。 */
+export function registryHost(value) {
+    try {
+        return new URL(value).host;
+    }
+    catch {
+        return value;
+    }
+}

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

@@ -14,13 +14,15 @@ 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 { OutputDecoder } from './decode-output.js';
 /** 内存任务注册表，按任务 id 索引。 */
 const tasks = new Map();
 let nextTaskId = 1;
@@ -195,6 +197,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,7 +359,7 @@ 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
@@ -359,9 +372,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 +387,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 +426,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 +498,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 +557,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 +584,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 +648,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;
@@ -728,7 +767,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 +831,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,9 +844,18 @@ 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）→ 官方源复查，区分「作者的依赖缺失/包被删」与「本机镜像源滞后」

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/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/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>;