dsh-plugin 2.0.6 → 2.1.0

package/src/server/services/install/operation-log.ts

@@ -6,36 +6,71 @@
  * 失败回捞：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.ts'
 
+/** 去掉 ANSI 颜色码：宿主的摘要行可能带终端着色，直接匹配路径会失败。 */
+function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*m/g, '')
+}
+
 /**
  * 从 DSH 输出里解析 operation 日志路径（`diagnostics: <path>`）。
- * 只认 DSH 的 operation 日志：路径含 `.plugin-manager` 且以 `pnpm.log` 结尾；
- * 不是这种路径（或压根没有该行）返回 null，调用方据此跳过回捞。
+ * 去掉首尾引号与句末标点（不同版本/语言的摘要行尾部可能带 `。`、`.`、`)`）；
+ * 相对路径原样返回，由读取方按 profile 目录解析。
  */
 export function operationLogPathOf(output: string): string | null {
   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')) continue
-    return path
+    let path = m[1]
+      .trim()
+      .replace(/[.,;:，。；、)\]}]+$/, '')
+      .trim()
+    // JSON 形态：引号包裹且反斜杠被转义过，按字符串字面量还原；普通文本里的引号直接剥掉
+    if (path.startsWith('"') && path.endsWith('"')) {
+      try {
+        const parsed: unknown = 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
+    if (path.toLowerCase().endsWith('pnpm.log')) return path
   }
   return null
 }
 
+/**
+ * 只允许读 profile 目录下的 pnpm.log（dsh 自己的操作日志）：
+ * 绝对路径必须落在该目录内，相对路径按该目录解析。
+ * 未提供 profileDir 时退回旧口径（路径须含 .plugin-manager），防止插件打印任意路径造成越权读取。
+ */
+function allowedLogPath(raw: string, profileDir?: string): string | null {
+  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: string): string | null {
-  const path = operationLogPathOf(output)
+export function backfillOperationLog(output: string, profileDir?: string): string | null {
+  const raw = operationLogPathOf(output)
+  if (raw === null) return null
+  const path = allowedLogPath(raw, profileDir)
   if (path === null) return null
   try {
     const text = readFileSync(path, 'utf8').trim()
@@ -46,6 +81,18 @@ export function backfillOperationLog(output: string): string | null {
   }
 }
 
+/**
+ * 输出里是否有 dsh 自己的内容 —— 只有 `[exit N]`、`[install-channel]`、`[timed out]`
+ * 这类本队列自己打的标记时返回 false。用于把「宿主什么都没回显」的失败显式留痕，
+ * 否则上报正文只剩退出码，无从排查。
+ */
+export function hasSubstantiveOutput(output: string): boolean {
+  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/src/server/services/install/registry-fallback.ts

@@ -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: string): string {
+  return value.trim().replace(/\/+$/, '')
+}
+
+/** 是否属于允许自动切换的公共源白名单。 */
+export function isPublicRegistry(value: string): boolean {
+  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: string, userRegistry: string, enabled: boolean): string[] {
+  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: string): string {
+  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: string): boolean {
+  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: string): string {
+  try {
+    return new URL(value).host
+  } catch {
+    return value
+  }
+}

package/src/server/services/install/task-queue.ts

@@ -15,7 +15,7 @@ import type { InstallResult, InstallTask, Invocation, QueueItem } from './instal
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.ts'
 import { npmTooLowMarker } from './npm-check.ts'
 import { registryMissingMarker } from './registry-check.ts'
-import { backfillOperationLog, createOperationLogTap, operationLogPathOf } from './operation-log.ts'
+import { backfillOperationLog, createOperationLogTap, hasSubstantiveOutput, operationLogPathOf } from './operation-log.ts'
 import { cleanLine, estimateProgress } from '../profile/progress.ts'
 import type { LoaderHandle } from '../loader.ts'
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.ts'
@@ -23,6 +23,8 @@ import { addPendingRestart, clearPendingRestart } from '../profile/pending-resta
 import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.ts'
 import { appendLog } from '../log.ts'
 import { commandOnPath, gitMissingDetail } from './preflight.ts'
+import { isTransportFailure, registryHost } from './registry-fallback.ts'
+import { OutputDecoder } from './decode-output.ts'
 
 /** 内存任务注册表，按任务 id 索引。 */
 const tasks = new Map<number, InstallTask>()
@@ -213,6 +215,16 @@ export function desktopCliBootstrap(entry: string): string | null {
   return null
 }
 
+/**
+ * 传给 CLI 的安装目标：钉住版本优先（Hub 自我更新提示的是已过供应链门禁的版本），
+ * 其次更新走 `@latest`，git 源与全局 npm 安装保持原样。
+ */
+export function npmInstallTargetOf(target: string, opts: { update: boolean; global: boolean; pinned?: string }): string {
+  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: ReturnType<typeof spawn>): void {
   if (process.platform === 'win32' && child.pid !== undefined) {
     const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore' })
@@ -272,6 +284,11 @@ export function startPluginMutation(options: {
   /** 自定义安装入口渠道（NPM 包卡片）：任务输出行与系统日志据此溯源「从哪个入口发起」；
    *  目录插件安装不传 */
   installChannel?: 'npm'
+  /** npm 源候选（首选在前）：传输层失败时按顺序换源重试，空/单个表示不降级 */
+  registries?: string[]
+  /** 精确安装 spec（如 `dsh-plugin@2.0.5`）：Hub 自我更新提示的是已过供应链门禁的版本，
+   *  必须钉住安装，不能再用 @latest 被带回门禁内的最新版 */
+  installSpec?: string
 }): InstallTask {
   // 卸载入队时先快照「该包是否带客户端 UI」：卸载完成后包已从磁盘删除，读不到 package.json，
   // 只能在此刻取；卸载成功且曾存活时据此决定是否要刷新页面摘除插件面板
@@ -397,8 +414,12 @@ function spawnMutation(options: {
   globalNpm?: string[]
   /** 更新已安装的 npm 包（mode=update）：命令显式带 @latest，让 pnpm 真正解析最新版本 */
   updateNpm?: boolean
+  /** npm 源候选（首选在前）：传输层失败时按顺序换源重试 */
+  registries?: string[]
+  /** 精确安装 spec（如 `dsh-plugin@2.0.5`）：见 startPluginMutation 同名说明 */
+  installSpec?: string
 }): Promise<InstallResult> {
-  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
@@ -411,9 +432,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]
@@ -427,9 +447,12 @@ function spawnMutation(options: {
   // 单次 spawn 并捕获结果：流式输出打日志 + 超时/取消兜底，close 后 resolve。
   // 不做任何终态后处理（exitCode/status/needsRestart 由下方统一收尾），
   // 这样全局 npm 首次失败后可以干净地换参数重试一次。
-  const spawnOnce = (attemptArgs: string[]): Promise<InstallResult> => new Promise((resolveOnce) => {
+  const spawnOnce = (attemptArgs: string[], registry?: string): Promise<InstallResult> => 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: ReturnType<typeof spawn>
@@ -463,11 +486,17 @@ function spawnMutation(options: {
           return
         }
       }
+      // invocation.env 是「必须叠加」的变量（打包桌面端的 ELECTRON_RUN_AS_NODE）：
+      // 没有它时保持 env 原样透传，有它时必须基于完整环境叠加，否则子进程会丢掉 PATH。
+      // registry 最后写入：换源重试只改这一层，pnpm/npm 都认 npm_config_registry。
+      const childEnv: NodeJS.ProcessEnv = { ...(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），
         // 且宿主进程崩溃后安装任务不会被连带误杀
@@ -522,7 +551,7 @@ function spawnMutation(options: {
       if (task && task.status === 'running' && task.progress < 85) task.progress += 1
     }, 500)
     const collect = (kind: 'stdout' | 'stderr', chunk: Buffer): void => {
-      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 stderr = (stderr + text).slice(-CAPTURE_LIMIT_BYTES)
       if (task) {
@@ -578,7 +607,21 @@ 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；二次尝试仍失败则保留其错误信息，不掩盖真正的原因。
@@ -587,7 +630,7 @@ function spawnMutation(options: {
       const retryExecuted = `npm install -g --legacy-peer-deps ${(globalNpm ?? []).join(' ')}`
       if (task && !task.attempts.includes(retryExecuted)) 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 —— 目标已在依赖里、且声明分发的入口文件都在，
@@ -644,7 +687,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
@@ -771,9 +816,14 @@ export async 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> {
   // 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，跳过这两类恢复
@@ -834,18 +884,27 @@ 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')
         for (const line of backfilled.split(/\r?\n/)) if (line.trim() !== '') pushLine(options.task, line.trimEnd())
       }
       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/src/server/services/settings.ts

@@ -15,8 +15,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 文件路径） */
@@ -27,6 +29,7 @@ export const DEFAULT_SETTINGS: HubSettings = {
   checkUpdatesOnStart: true,
   proxy: '',
   npmRegistry: '',
+  registryFallback: true,
   enableNpmInstall: true,
   logPath: '',
 }