dsh-plugin 2.0.6 → 2.2.0

package/src/client/logic/urls.ts

@@ -49,12 +49,15 @@ function reasonTitleOf(kind: FailureKind, action: FailureAction): string {
     case 'dshMissing': return 'dsh command not found on the user machine'
     case 'pnpmMissing': return 'pnpm command not found on the user machine'
     case 'pnpmStore': return 'pnpm store version mismatch on the user machine'
+    case 'pnpmVirtualStore': return 'the profile modules directory was built with a different virtual-store-dir-max-length on the user machine'
     case 'pnpmWorkspace': return `pnpm workspace-root check blocked the ${word} on the user machine`
     case 'originRejected': return 'request origin rejected by the local service on the user machine'
     case 'pnpmPolicy': return `pnpm supply-chain policy blocked the ${word} on the user machine`
     case 'pnpmUnusedPatch': return 'stale pnpm patch entry on the user machine'
     case 'pnpmMissingDep': return 'dependency not found on the npm registry on the user machine'
-    case 'registryVersionStale': return 'requested version not available on the npm registry in use on the user machine'
+    case 'registryVersionStale': return `requested version not available on the npm registry in use on the user machine`
+    case 'registryAuth': return `npm registry rejected the credentials for this ${word} on the user machine`
+    case 'profileExclusive': return `the desktop profile is managed only by the Electron app, so the CLI refused the ${word}`
     case 'pnpmLinkedDirMissing': return 'dangling local (link:) dependency in the user profile'
     case 'fileLocked': return 'file locked by another process on the user machine'
     case 'accessDenied': return 'file write access denied on the user machine'
@@ -68,6 +71,8 @@ function reasonTitleOf(kind: FailureKind, action: FailureAction): string {
     case 'timeout': return `${word} timed out`
     case 'profileLock': return 'DSH profile is locked by another process'
     case 'pluginMissingDep': return 'a dependency of the plugin is not published on npm'
+    case 'dshTooOld': return 'the plugin requires a newer DSH than the host runs'
+    case 'localEnv': return `no plugin-side cause found — the failure points at the local environment for this ${word}`
     case 'hub': return `${word} failed (cause unclassified)`
     default: return `plugin ${word} failed`
   }
@@ -101,6 +106,16 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
         ? 'a dependency declared by the plugin is not published on the public npm registry (missing, removed, or never released); please publish or correct that dependency, or ship it with the plugin'
       : kind === 'network'
         ? 'network connectivity issue on the user side (DNS, proxy, firewall, or a blocked connection)'
+      : kind === 'localEnv'
+        ? 'no evidence of a plugin-side cause; the log shows local-environment signals (system error codes, certificates/proxy, or a broken local config), so this is reported for triage of the classifier only'
+      : kind === 'dshTooOld'
+        ? 'the plugin declares a minimum DSH version this host does not meet — upgrade DSH first (local environment issue)'
+      : kind === 'pnpmVirtualStore'
+        ? 'the profile node_modules was created with a different virtual-store-dir-max-length (or a different pnpm config), so pnpm refuses to reuse it (local environment issue)'
+      : kind === 'registryAuth'
+        ? 'the npm registry rejected the request with 401/403 — the configured registry needs credentials or blocks this network (local environment issue)'
+      : kind === 'profileExclusive'
+        ? 'the desktop profile can only be managed by the Electron app, and the install was attempted from an external CLI (local environment issue)'
         : kind === 'pluginPrepare'
           ? 'plugin prepare/build script failed during install (packaging/distribution issue)'
           : kind === 'pnpmIgnoredBuild'
@@ -163,8 +178,8 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
           `- OS: ${env.platform} ${env.arch} (${env.release})`,
           `- Profile: \`${env.profile}\``,
           `- DSH Home: \`${env.dshHome}\``,
-          // 完整安装日志所在（正文受 URL 长度限制只能带摘要，完整日志在 hub.log，可复制/附加给作者）
-          `- Full log: \`~/.dsh/profiles/${env.profile}/hub.log\` (paste or attach for the full output)`,
+          // 完整安装日志在通知中心（hub.log 只有任务开始/结束，没有 pnpm 输出，别让用户白附）
+          '- Full log: open the Hub notifications, select the failed record and press "Copy"',
         ]
         : []),
       // 该插件在插件市场的收录位置（详情页链接）
@@ -265,7 +280,7 @@ export function hubIssueUrl(
           `- OS: ${env.platform} ${env.arch} (${env.release})`,
           `- Profile: \`${env.profile}\``,
           `- DSH Home: \`${env.dshHome}\``,
-          `- Full log: \`~/.dsh/profiles/${env.profile}/hub.log\` (paste or attach for the full output)`,
+          '- Full log: open the Hub notifications, select the failed record and press "Copy"',
         ]
         : []),
       ...(repo !== 'unknown' ? [`- Catalog: [${pluginSiteUrl(repo)}](${pluginSiteUrl(repo)})`] : []),

package/src/client/types.ts

@@ -108,6 +108,19 @@ export interface HubUpdateInfo {
   publishedAt?: string | null
   /** Markdown 变更记录；可传字符串，或 { zh, en } 双语言对象按界面语言取 */
   notes?: string | Record<string, string> | null
+  /**
+   * 最近若干发版（含最新版），按版本号降序无关、由客户端自行排序。
+   * 用途：连续快速发版时，最新版往往还在 pnpm 的 24h 供应链门禁内；
+   * 客户端据此回退到「更早、但已过门禁」的版本提示更新，而不是整体跳过。
+   */
+  recentVersions?: HubUpdateVersion[]
+}
+
+/** 单个发版记录：版本号 + 与 npm registry 同源的发布时间 + 该版本变更记录。 */
+export interface HubUpdateVersion {
+  version: string
+  publishedAt?: string | null
+  notes?: string | Record<string, string> | null
 }
 
 /**

package/src/server/http/diagnostics.ts

@@ -5,72 +5,15 @@
  *
  * 诊断路由：流式连通性自检、代理校验，以及与任务模块 /env 路由共享的宿主环境快照。
  */
-import { readFileSync } from 'node:fs'
 import { homedir, release } from 'node:os'
-import { dirname, join, resolve } from 'node:path'
+import { join } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { loadSettings } from '../services/settings.ts'
+import { hostDshVersion, toolVersion } from '../services/host-version.ts'
 import { gitLsRemote, probeUrl, systemProxy } from '../services/probe.ts'
 import { appendLog } from '../services/log.ts'
 import { readJsonBody, requireTrustedPost, sendJson, type WebRoute, type WebServerService } from './shared.ts'
 
-/** 宿主 dsh CLI 版本：优先直接跑 `dsh --version`（与 pnpm/npm/git 同款同步探测，1500ms 超时兜底，
- *  绝不挂起）；拿不到再退回从入口 `process.argv[1]` 向上找 package.json（dsh 不在 PATH 时兜底）。 */
-function hostDshVersion(): string | null {
-  const viaCli = toolVersion('dsh', ['--version'])
-  if (viaCli) return viaCli
-  const entry = process.argv[1]
-  if (entry === undefined) return null
-  let dir = dirname(resolve(entry))
-  for (let depth = 0; depth < 4; depth++) {
-    try {
-      const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { name?: string; version?: string }
-      const name = manifest.name ?? ''
-      if (typeof manifest.version === 'string' && (name === 'dsh' || name.includes('dsh') || name.includes('harness'))) {
-        return manifest.version
-      }
-    } catch {
-      /* 不是包根，继续向上查找 */
-    }
-    const parent = dirname(dir)
-    if (parent === dir) break
-    dir = parent
-  }
-  return null
-}
-
-/** 从命令输出里抽出版本号本体：pnpm/npm 直接打印 `11.7.0`，而 `git --version` 打印
- *  `git version 2.55.0.windows.5` —— 原样取首行会让 issue 正文（统一再加 `v` 前缀）拼成
- *  `vgit version 2.55.0.windows.5`。只取版本号，顺带兼容 `v1.2.3` 这类自带前缀的输出。 */
-function versionOf(output: string): string | null {
-  const first = output.trim().split(/\r?\n/)[0]?.trim() ?? ''
-  if (!first) return null
-  const match = /\d+\.\d+[0-9A-Za-z.\-+]*/.exec(first)
-  return match === null ? null : match[0]
-}
-
-/** 探测命令行工具的版本号（pnpm --version / npm --version / git --version）：
- *  未安装 / 不在 PATH / 超时一律返回 null —— issue 环境快照如实写 unknown，绝不挂起。
- *  （同步探测仅用于启动期/请求期的低频率 /env 快照，安装通道不经过这里。）
- *
- *  Windows 上 pnpm/npm 是 .cmd shim，不带 shell 的 spawnSync 起不来 —— 上报的 issue 里
- *  因此长期是 `pnpm: unknown` / `npm: unknown`，而 pnpm 版本恰恰是 allowBuilds 那类问题的
- *  关键信息（门禁行为随版本变）。故 win32 走 shell 让 cmd 解析 shim；参数是固定的
- *  `--version`，没有注入面。 */
-function toolVersion(cmd: string, args: string[]): string | null {
-  try {
-    const r = spawnSync(cmd, args, {
-      timeout: 1500,
-      encoding: 'utf8',
-      shell: process.platform === 'win32',
-    })
-    if (r.error || r.status !== 0) return null
-    return versionOf(r.stdout ?? '')
-  } catch {
-    return null
-  }
-}
-
 /** 本机实际生效的 npm registry：诊断与安装同口径 —— 设置里留空时读用户 npm 配置
  *  （含 profile 目录的 .npmrc），而不是硬探官方源，避免「能装但诊断说源不通」。
  *  读不到（npm 缺失/超时/输出异常）时回退官方源。 */

package/src/server/http/install.ts

@@ -11,11 +11,13 @@ import { recordResolvedNpmPackage } from '../services/profile/installed-versions
 import { isDshNpmPackageForRepo } from '../services/install/npm-resolve.ts'
 import { probeUrl, systemProxy } from '../services/probe.ts'
 import { loadSettings, type HubSettings } from '../services/settings.ts'
+import { registryCandidates, registryHost, userNpmRegistry } from '../services/install/registry-fallback.ts'
+import { profileDirectory } from '../services/profile/profile.ts'
 import { readInstalled } from './catalog.ts'
 import { COMMAND_TIMEOUT_MS, readJsonBody, requireTrustedPost, sendJson, type WebRoute, type WebServerService } from './shared.ts'
 
 /** 安装/卸载 CLI 的子进程环境：透传宿主环境并注入 HTTP(S) 代理，
- *  代理来源与诊断一致（设置代理 → 系统代理 → 宿主 env）；不注入 npm registry，沿用用户本机 npm 配置。 */
+ *  代理来源与诊断一致（设置代理 → 系统代理 → 宿主 env）；registry 由任务队列按候选源逐次注入。 */
 function mutationEnv(settings: HubSettings): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { ...process.env, CI: 'true' }
   const proxy = settings.proxy !== '' ? settings.proxy : (systemProxy() ?? '')
@@ -64,6 +66,17 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
           const lang = typeof body === 'object' && body !== null && (body as { lang?: unknown }).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 as { globalNpm?: unknown }).globalNpm)
@@ -95,6 +108,8 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
               globalNpm,
               timeoutMs: COMMAND_TIMEOUT_MS,
               env: mutationEnv(settings),
+              // 候选源（首选在前）：任务内遇到传输层失败时按顺序换源重试
+              registries,
               // 全局 npm 安装由 NPM 包卡片/官方命令发起：日志体现入口渠道
               installChannel: installChannel ?? 'npm',
             })
@@ -107,12 +122,17 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             return
           }
           const target = rawRepo
+          // 钉住精确版本（Hub 自我更新）：最新版可能仍在 pnpm 供应链门禁内，
+          // 客户端提示的是「已过门禁」的版本，服务端必须按该版本安装而不是 @latest。
+          const pinVersion = typeof (body as { version?: unknown }).version === 'string'
+            ? (body as { version: string }).version.trim()
+            : ''
+          if (pinVersion !== '' && !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/.test(pinVersion)) {
+            sendJson(response, 400, { error: 'invalid version' })
+            return
+          }
           // 已尝试的安装方式（供失败提 Issue 预填）：保持为空
           const attempts: string[] = []
-          // 代理口径与诊断/安装通道一致：设置里的代理 → 系统代理 → 环境变量 → 直连。
-          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
@@ -136,18 +156,30 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             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: string[] = []
+            let chosen: string | null = 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 单线程保证同一目标至多一个任务，杜绝双击/并发双任务。
@@ -170,6 +202,9 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             loader,
             timeoutMs: COMMAND_TIMEOUT_MS,
             env: mutationEnv(settings),
+            // 候选源（首选在前）：任务内遇到传输层失败时按顺序换源重试
+            registries: ordered,
+            installSpec: pinVersion !== '' ? `${target}@${pinVersion}` : undefined,
             // 自定义安装入口渠道：日志/报错据此溯源
             installChannel,
           })

package/src/server/http/settings.ts

@@ -28,7 +28,7 @@ export function registerSettingsRoutes(webServer: WebServerService, profile: str
           // 白名单字段：只接受已知设置项，防客户端把任意键写进文件
           const patch: Record<string, unknown> = {}
           const source = typeof body === 'object' && body !== null ? body as Record<string, unknown> : {}
-          for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'npmRegistry', 'proxy', 'logPath'] as const) {
+          for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'npmRegistry', 'registryFallback', 'proxy', 'logPath'] as const) {
             if (source[key] !== undefined) patch[key] = source[key]
           }
           // 日志位置：非空时预建目录验证可写，失败直接 400 拦截（默认位置永远合法，空串 = 回默认）

package/src/server/services/host-version.ts

@@ -0,0 +1,69 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 宿主与命令行工具的版本探测：dsh 版本同时用于诊断快照和「插件要求更高 DSH」判定，
+ * pnpm/npm/git 只用于诊断快照。同步探测 + 1500ms 超时兜底，拿不到一律 null，绝不挂起。
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+/** 从命令输出里抽出版本号本体：pnpm/npm 直接打印 `11.7.0`，而 `git --version` 打印
+ *  `git version 2.55.0.windows.5` —— 原样取首行会让 issue 正文拼成 `vgit version …`。
+ *  只取版本号，顺带兼容 `v1.2.3` 这类自带前缀的输出。 */
+export function versionOf(output: string): string | null {
+  const first = output.trim().split(/\r?\n/)[0]?.trim() ?? ''
+  if (!first) return null
+  const match = /\d+\.\d+[0-9A-Za-z.\-+]*/.exec(first)
+  return match === null ? null : match[0]
+}
+
+/** 探测命令行工具版本：未安装 / 不在 PATH / 超时一律 null。
+ *  Windows 上 pnpm/npm 是 .cmd shim，不走 shell 起不来；参数是固定的 `--version`，没有注入面。 */
+export function toolVersion(cmd: string, args: string[]): string | null {
+  try {
+    const r = spawnSync(cmd, args, {
+      timeout: 1500,
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+    })
+    if (r.error || r.status !== 0) return null
+    return versionOf(r.stdout ?? '')
+  } catch {
+    return null
+  }
+}
+
+let cachedDshVersion: string | null = null
+
+/** 宿主 dsh 版本：优先 `dsh --version`；拿不到再从入口 `process.argv[1]` 向上找 package.json
+ *  （dsh 不在 PATH 时兜底）。探测成功即缓存，失败不缓存以便下次重试。 */
+export function hostDshVersion(): string | null {
+  if (cachedDshVersion !== null) return cachedDshVersion
+  const viaCli = toolVersion('dsh', ['--version'])
+  if (viaCli !== null) {
+    cachedDshVersion = viaCli
+    return viaCli
+  }
+  const entry = process.argv[1]
+  if (entry === undefined) return null
+  let dir = dirname(resolve(entry))
+  for (let depth = 0; depth < 4; depth++) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { name?: string; version?: string }
+      const name = manifest.name ?? ''
+      if (typeof manifest.version === 'string' && (name === 'dsh' || name.includes('dsh') || name.includes('harness'))) {
+        cachedDshVersion = manifest.version
+        return cachedDshVersion
+      }
+    } catch {
+      /* 不是包根，继续向上查找 */
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}

package/src/server/services/install/decode-output.ts

@@ -0,0 +1,22 @@
+/**
+ * 子进程输出解码：默认 UTF-8；出现替换字符（中文 Windows 的 GBK 输出）时改用 GBK 重解。
+ * 用 StringDecoder 跨 chunk 缓冲，避免 UTF-8 多字节字符被 chunk 边界切断后误判为 GBK。
+ */
+import { StringDecoder } from 'node:string_decoder'
+
+export class OutputDecoder {
+  private readonly utf8 = new StringDecoder('utf8')
+
+  push(chunk: Buffer): string {
+    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/src/server/services/install/dsh-compat.ts

@@ -0,0 +1,99 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 「插件要求的 DSH 版本高于当前宿主」判定：安装失败后读一次 npm 元数据，取
+ * peerDependencies（@deepseek-ai/dsh-*）与 engines.dsh 声明的最低版本里最高的那个，
+ * 与宿主版本比较；宿主更低就产出 [dsh-too-old] 标记 —— 前端据此提示「先升级 DSH」，
+ * 不再把这类失败归成「未分类」丢给用户或插件作者。
+ *
+ * 只在失败路径调用：peer 不满足本身通常只是警告，成功安装时不该出现这个提示；
+ * 任何网络/解析异常都静默返回 null，不改变原有失败处理。
+ */
+import { hostDshVersion } from '../host-version.ts'
+
+/** 从安装目标里取 npm 包名：`@scope/pkg@1.2.3` → `@scope/pkg`。
+ *  git / URL / 本地路径等非 npm 目标返回 null。 */
+export function npmNameOf(target: string): string | null {
+  const raw = target.trim()
+  if (raw === '') return null
+  if (/^(?:github:|git\+|https?:|file:|link:|\.{0,2}[\\/])/i.test(raw)) return null
+  // owner/repo（非 scope）：git 目标的另一种写法，不是包名
+  if (!raw.startsWith('@') && /^[^\s@]+\/[^\s]+$/.test(raw)) return null
+  const at = raw.lastIndexOf('@')
+  const name = at > 0 ? raw.slice(0, at) : raw
+  return /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(name) ? name : null
+}
+
+/** `0.2.1-rc.1` / `^0.2.1` / `>=0.2.0 <0.3.0` → [0,2,1]；解析不出返回 null。
+ *  只取版本三段：DSH 的 prerelease 序号（rc.1）不参与「太低」判断，避免比较误差。 */
+export function versionTriple(raw: string): [number, number, number] | null {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(raw)
+  return m === null ? null : [Number(m[1]), Number(m[2]), Number(m[3])]
+}
+
+function compareTriple(a: [number, number, number], b: [number, number, number]): number {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i]! - b[i]!
+  }
+  return 0
+}
+
+/** 插件声明的最低 DSH 版本：engines.dsh 与 peerDependencies 里 @deepseek-ai/dsh-* 的下限取最大。
+ *  返回原始声明文本（如 `^0.2.1-rc.1`）供提示直接展示；没有声明返回 null。 */
+export function dshFloorOf(manifest: unknown): string | null {
+  const m = manifest as { engines?: Record<string, unknown>; peerDependencies?: Record<string, unknown> } | null
+  const ranges: string[] = []
+  const engineDsh = m?.engines?.dsh
+  if (typeof engineDsh === 'string') ranges.push(engineDsh)
+  for (const [name, range] of Object.entries(m?.peerDependencies ?? {})) {
+    if (/^@deepseek-ai\/dsh(?:-|$)/.test(name) && typeof range === 'string') ranges.push(range)
+  }
+  let floor: string | null = null
+  let floorTriple: [number, number, number] | null = null
+  for (const range of ranges) {
+    const triple = versionTriple(range)
+    if (triple === null) continue
+    if (floorTriple === null || compareTriple(triple, floorTriple) > 0) {
+      floor = range
+      floorTriple = triple
+    }
+  }
+  return floor
+}
+
+/**
+ * 产出「插件要求更高的 DSH」标记行；没有声明、读不到元数据、宿主版本未知或已满足时返回 null。
+ * 用版本级 manifest（`/<pkg>/latest`）：packument 的精简形态不带 peerDependencies。
+ */
+export async function dshTooOldMarker(
+  target: string,
+  opts: { currentVersion?: string | null; fetchImpl?: typeof fetch; timeoutMs?: number; registry?: string } = {},
+): Promise<string | null> {
+  const name = npmNameOf(target)
+  if (name === null) return null
+  const current = opts.currentVersion ?? hostDshVersion()
+  if (current === null) return null
+  const currentTriple = versionTriple(current)
+  if (currentTriple === null) return null
+  const base = (opts.registry ?? 'https://registry.npmjs.org').replace(/\/+$/, '')
+  // scope 包的路径要编码：`@scope/name` → `%40scope%2Fname`
+  const url = `${base}/${name.replace('@', '%40').replace('/', '%2F')}/latest`
+  let manifest: unknown
+  try {
+    const res = await (opts.fetchImpl ?? fetch)(url, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 4000),
+    })
+    if (!res.ok) return null
+    manifest = await res.json()
+  } catch {
+    return null
+  }
+  const floor = dshFloorOf(manifest)
+  const floorTriple = floor === null ? null : versionTriple(floor)
+  if (floor === null || floorTriple === null) return null
+  if (compareTriple(currentTriple, floorTriple) >= 0) return null
+  return `[dsh-too-old] ${name} requires DSH >= ${floor} (declared in engines / peerDependencies), but this host runs ${current} — upgrade DSH before installing`
+}

package/src/server/services/install/install-types.ts

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

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 下最新的