dsh-plugin 2.3.1 → 2.3.3

package/src/client/logic/release-age.ts

@@ -3,15 +3,15 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * 供应链门禁的时间判定（纯函数）：pnpm 会静默回退发布未满门槛的版本，
- * 故发布太新的版本不该提示更新。Hub 自身更新与插件更新共用同一门槛。
+ * 发布冷却期的时间判定（纯函数）：pnpm 会不提示地回退发布还不满 24 小时的版本，
+ * 故发布太新的版本不该提示更新。Hub 自身更新与插件更新共用同一规则。
  */
 import type { HubUpdateInfo, HubUpdateState, HubUpdateVersion } from '../types.ts'
 
-/** pnpm 供应链门禁：dsh profile 默认 minimumReleaseAge=1440（分钟）；+30 分钟缓冲抵消网络/CDN 边缘时间偏差。 */
+/** pnpm 发布冷却期：dsh profile 默认 minimumReleaseAge=1440（分钟）；+30 分钟缓冲抵消网络/CDN 边缘时间偏差。 */
 export const MIN_RELEASE_AGE_MS = 24 * 60 * 60 * 1000 + 30 * 60 * 1000
 
-/** 发布时间是否仍在门禁窗口内（太新 → 暂缓提示）；无值/解析不出返回 false（不拦真实更新）。 */
+/** 发布时间是否仍在冷却期内（太新 → 暂缓提示）；无值/解析不出返回 false（不拦真实更新）。 */
 export function isReleaseTooFresh(publishedAt: string | null | undefined, now: number): boolean {
   if (typeof publishedAt !== 'string' || publishedAt === '') return false
   const ms = Date.parse(publishedAt)
@@ -61,20 +61,20 @@ export function compareVersions(a: string | null | undefined, b: string | null |
   return 0
 }
 
-/** 「可更新」判定结果：是否提示，以及被供应链门禁拦下时的到期时刻。 */
+/** 「可更新」判定结果：是否提示，以及还没过冷却期时的可重试时刻。 */
 export interface UpdateDecision {
   offered: boolean
-  /** 发布未满门槛 → 可重试时刻（毫秒）；非门禁原因（npm 上没有更高版本）→ null */
+  /** 发布还不满冷却期 → 可重试时刻（毫秒）；非冷却期原因（npm 上没有更高版本）→ null */
   pendingUntil: number | null
 }
 
 /**
- * 是否值得提示「可更新」：npm 上最新可安装版本确实比已装版本新，且已过供应链门禁。
+ * 是否值得提示「可更新」：npm 上最新可安装版本确实比已装版本新，且已过发布冷却期。
  *
  * 更新命令执行的是 `pkg@latest`，所以「目录里标的版本」不是最终能装上的版本：
  * 作者可能只打了 GitHub release 没发 npm —— 此时提示会变成永远点不掉的循环。
  * 任一信息缺失（查不到发布信息 / 没有已装版本记录）返回 offered，交回调用方原有判定：
- * 宁可提示，也不因为一次查询失败把真实更新吃掉。
+ * 宁可提示，也不因为一次查询失败漏掉真实更新。
  */
 export function updateDecision(
   release: { version: string; publishedAt: string } | null,
@@ -104,8 +104,8 @@ export function isUpdateOffered(
 /**
  * 选出本次真正该提示的更新版本。
  *
- * 只看最新版会漏更新：连续发版时间隔小于供应链门禁时，最新版永远「太新」，
- * 提示被整体跳过。这里把最新版与 recentVersions 一起当候选，取「高于当前版本且已过门禁」
+ * 只看最新版会漏更新：连续发版时间隔小于发布冷却期时，最新版永远「太新」，
+ * 提示被整体跳过。这里把最新版与 recentVersions 一起当候选，取「高于当前版本且已过冷却期」
  * 的最高版本；一个都没有但仍存在更高版本 → pending（暂缓，不谎称已是最新）。
  */
 export function pickHubUpdate(info: HubUpdateInfo, currentVersion: string, now: number): { state: HubUpdateState; target: HubUpdateVersion | null } {

package/src/client/logic/urls.ts

@@ -228,7 +228,7 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
  * 错误摘要，供插件中心维护者分诊 —— 不再把环境问题/插件中心自身问题误投给插件作者。
  */
 export type HubIssueVariant =
-  /** 缺省：安装器主动把失败送到插件中心分诊（未分类兜底） */
+  /** 缺省：安装器主动把失败送到插件中心分诊（未分类时的默认去向） */
   | 'triage'
   /** 从判定由插件中心自己产出的分支（插件打包问题 / allowBuilds 拦截）的次要入口提交：用户怀疑是误报 */
   | 'misjudge'
@@ -249,7 +249,7 @@ export function hubIssueUrl(
   const zhWord = actionWordZh(action)
   const repo = pluginRepo && pluginRepo.trim() !== '' ? pluginRepo.trim() : 'unknown'
   const title = variant === 'misjudge'
-    // 标题就点明「可能是误判」，维护者一眼能区分它和未分类兜底
+    // 标题就点明「可能是误判」，维护者一眼能区分它和未分类时的默认去向
     ? `[dsh-plugin-hub] possible misjudgment: ${repo}`
     : `[dsh-plugin-hub] ${reasonTitleOf(kind, action)}: ${repo}`
   const code = coreErrorCode(message)
@@ -264,7 +264,7 @@ export function hubIssueUrl(
       ...(variant === 'misjudge'
         // 这些分支的判据由插件中心自己产出、或掺了我们的动作（自动放行 allowBuilds）——
         // 一旦我们自己误报，用户就被送去作者仓库、我们永远收不到反馈。
-        // 正文写清它来自哪条分支、判据是谁给的，维护者才不会把它当成未分类兜底。
+        // 正文写清它来自哪条分支、判据是谁给的，维护者才不会把它当成未分类时的默认去向。
         ? [
           '- Filed from: a branch that normally routes to the plugin repo — filed here because that verdict may be our own misjudgment.',
           '- Source of that verdict: produced by dsh-plugin-hub\'s own check or its auto-allow retry, not by plain pnpm output.',

package/src/client/styles/Header.module.css

@@ -216,7 +216,7 @@
   line-height: 18px;
   color: var(--hub-text-tertiary);
   margin: 0;
-  /* 品牌副标题强制单行：中文/英文都不换行，超宽时省略号截断兜底 */
+  /* 品牌副标题强制单行：中文/英文都不换行，超宽时用省略号截断 */
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;

package/src/client/styles/Modal.module.css

@@ -876,7 +876,7 @@
 
 /* —— 安装失败记录 —— */
 
-/* 失败记录列表：纵向排列，高度随记录数自适应 —— 记录少时贴合内容，记录多时由窗体 max-height 兜底滚动 */
+/* 失败记录列表：纵向排列，高度随记录数自适应 —— 记录少时贴合内容，记录多时由窗体 max-height 限制滚动 */
 .failList {
   display: flex;
   flex-direction: column;
@@ -904,7 +904,7 @@
 
 /* —— 任务通知中心（成功 + 失败） —— */
 
-/* 通知列表：纵向排列，高度随记录数自适应 —— 记录少时贴合内容，记录多时由窗体 max-height 兜底滚动 */
+/* 通知列表：纵向排列，高度随记录数自适应 —— 记录少时贴合内容，记录多时由窗体 max-height 限制滚动 */
 .noticeList {
   display: flex;
   flex-direction: column;

package/src/client/styles/SectionTabs.module.css

@@ -105,7 +105,7 @@
 
 /* —— 通知中心入口 —— */
 
-/* 通知铃铛按钮：位于「设置」tab 后边、靠右对齐（margin-left:auto 吃掉 tab 剩余空间），
+/* 通知铃铛按钮：位于「设置」tab 后边、靠右对齐（margin-left:auto 占满 tab 剩余空间），
    在 38px tab 栏里垂直居中；常态透明底只显铃铛轮廓，hover 浅灰，不抢 tab 视觉层级 */
 .noticeBtn {
   position: relative;

package/src/client/styles/tokens.module.css

@@ -4,7 +4,7 @@
  *
  * 插件中心设计变量。
  *
- * 对宿主 --dsw-alias-* 主题变量的语义别名，各带原始浅色字面量，供未定义底层变量的宿主兜底。
+ * 对宿主 --dsw-alias-* 主题变量的语义别名，各带原始浅色字面量，供未定义底层变量的宿主使用。
  * 声明在 :root 与暗色 body 上，让每种主题都按自己的变量集重新解析别名，再由所有板块元素继承。
  *
  * 各区域样式表不要写颜色字面量：在此引用 --hub-*，新样式即可自动跟随主题。 */

package/src/client/types.ts

@@ -110,8 +110,8 @@ export interface HubUpdateInfo {
   notes?: string | Record<string, string> | null
   /**
    * 最近若干发版（含最新版），按版本号降序无关、由客户端自行排序。
-   * 用途：连续快速发版时，最新版往往还在 pnpm 的 24h 供应链门禁内；
-   * 客户端据此回退到「更早、但已过门禁」的版本提示更新，而不是整体跳过。
+   * 用途：连续快速发版时，最新版往往还在 pnpm 的 24h 发布冷却期内；
+   * 客户端据此回退到「更早、但已过冷却期」的版本提示更新，而不是整体跳过。
    */
   recentVersions?: HubUpdateVersion[]
 }
@@ -126,8 +126,8 @@ export interface HubUpdateVersion {
 /**
  * Hub 自我更新状态 —— 供版本弹窗选文案与按钮，四态互斥：
  *  - `none`      未取到接口中心信息（拉取失败）→ 只说当前版本，不提示更新
- *  - `available` 远端有更新且已过供应链安全门槛 → 提示更新
- *  - `pending`   远端有更新但发布未满门槛（见 useCatalog）→ 暂缓提示并说明原因
+ *  - `available` 远端有更新且已过发布冷却期 → 提示更新
+ *  - `pending`   远端有更新但发布还不满冷却期（见 useCatalog）→ 暂缓提示并说明原因
  *  - `latest`    与远端最新版一致 → 确已最新
  * 「有新版但暂缓提示」必须与「确已最新」分开：两者若共用文案，弹窗会在本机版本落后时
  * 谎称「你正在使用 v{远端最新版}，已是最新」。

package/src/server/http/catalog.ts

@@ -42,7 +42,7 @@ function fetchCatalogOnce(target: string, proxy: string): ReturnType<typeof fetc
 }
 
 /** 读缓存：文件存在、JSON 合法、未超过 maxAgeMs → 返回原始响应字符串；否则 null（视为 miss）。
- *  maxAgeMs 传 Infinity 即「任意年龄的缓存」，供实时拉取失败时兜底使用。 */
+ *  maxAgeMs 传 Infinity 即「任意年龄的缓存」，供实时拉取失败时使用。 */
 function readCatalogCache(file: string, maxAgeMs: number): string | null {
   try {
     const entry = JSON.parse(readFileSync(file, 'utf8')) as CatalogCacheEntry
@@ -56,7 +56,7 @@ function readCatalogCache(file: string, maxAgeMs: number): string | null {
   return null
 }
 
-/** 写缓存：目录不存在则创建；写失败静默忽略（缓存只是加速，不影响功能）。 */
+/** 写缓存：目录不存在则创建；写失败直接忽略（缓存只是加速，不影响功能）。 */
 function writeCatalogCache(file: string, body: string): void {
   try {
     mkdirSync(dirname(file), { recursive: true })
@@ -108,7 +108,7 @@ export function registerCatalogRoutes(webServer: WebServerService, profile: stri
       handler: async (request, response) => {
         if (!requireMethod(request, response, 'GET')) return
         // 目录/统计数据服务端代理：浏览器不直连 dsh-plugin.org，统一经此路由
-        // 转发（curl 子进程注入代理 env），与 npm / git 安装通道走同一代理口径，
+        // 转发（curl 子进程注入代理 env），与 npm / git 安装通道走同一代理规则，
         // 「npm / git / 目录数据请求统一走该代理」的设置文案因此真实生效。
         const url = new URL(request.url ?? '/', 'http://localhost')
         const settings = loadSettings(profile)
@@ -145,7 +145,7 @@ export function registerCatalogRoutes(webServer: WebServerService, profile: stri
               sendJson(response, 200, JSON.parse(stale))
               return
             } catch {
-              // 兜底缓存也损坏：落到下面的 502
+              // 备用缓存也损坏：落到下面的 502
             }
           }
           // 带上 curl 退出码与 stderr 末行：只回 error 字段时，用户贴出来的响应里

package/src/server/http/diagnostics.ts

@@ -14,7 +14,7 @@ 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'
 
-/** 本机实际生效的 npm registry：诊断与安装同口径 —— 设置里留空时读用户 npm 配置
+/** 本机实际生效的 npm registry：诊断与安装同一套规则 —— 设置里留空时读用户 npm 配置
  *  （含 profile 目录的 .npmrc），而不是硬探官方源，避免「能装但诊断说源不通」。
  *  读不到（npm 缺失/超时/输出异常）时回退官方源。 */
 function configuredNpmRegistry(profile: string): string {
@@ -75,7 +75,7 @@ export function registerDiagnosticsRoutes(webServer: WebServerService, profile:
         }
         const settings = loadSettings(profile)
         // npm 通道：设置里配置了镜像源就探测该镜像（安装通道吃同一个 registry）；
-        // 未配置（空串）时探测本机 npm 配置里实际生效的源 —— 与安装同口径。
+        // 未配置（空串）时探测本机 npm 配置里实际生效的源 —— 与安装同一套规则。
         const registry = settings.npmRegistry.replace(/\/+$/, '') || configuredNpmRegistry(profile)
         // 连通性自检打各通道的轻量资源：npm 源拉包元数据、GitHub 行探小仓库、
         // 目录站按 Range 取 1KB（探市场真实下载的 plugins.zh.json，但不整份下载）。
@@ -91,7 +91,7 @@ export function registerDiagnosticsRoutes(webServer: WebServerService, profile:
           { key: 'catalog', url: 'https://api.dsh-plugin.org/plugins.zh.json', display: '', cmd: 'curl -r 0-1023 https://api.dsh-plugin.org/plugins.zh.json', range: '0-1023' },
         ]
         // 配置了 HTTP 代理：追加一行代理诊断 —— 用该代理打 github.com（安装通道真实访问的地址），
-        // 验证「代理能不能把请求带出去」。与安装同口径：curl 子进程注入该代理 env。
+        // 验证「代理能不能把请求带出去」。与安装同一套规则：curl 子进程注入该代理 env。
         // 设置里未配置代理时不显示该行（跟随系统代理/直连，无「代理本身」可验证）。
         if (settings.proxy !== '') {
           allChecks.push({ key: 'proxy', url: 'https://github.com', display: settings.proxy, cmd: `curl -s -o /dev/null -x ${settings.proxy} https://github.com`, proxy: settings.proxy })
@@ -114,7 +114,7 @@ export function registerDiagnosticsRoutes(webServer: WebServerService, profile:
         const results: Array<{ key: string; ok: boolean }> = []
         for (const c of checks) {
           send({ type: 'probe', key: c.key, cmd: c.cmd, display: c.display })
-          // git 行走真实克隆握手（gitLsRemote），其余走 curl 探测，两路都带超时兜底
+          // git 行走真实克隆握手（gitLsRemote），其余走 curl 探测，两路都带超时保护
           const r = c.git
             ? await gitLsRemote(c.url, c.proxy ?? effectiveProxy, 6000)
             : await probe(c.url, c.proxy, c.range)

package/src/server/http/install.ts

@@ -12,11 +12,12 @@ 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 { lookupReleaseAge } from '../services/npm-release-age.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) 代理，
+/** 安装/卸载 CLI 的子进程环境：原样传递宿主环境并注入 HTTP(S) 代理，
  *  代理来源与诊断一致（设置代理 → 系统代理 → 宿主 env）；registry 由任务队列按候选源逐次注入。 */
 function mutationEnv(settings: HubSettings): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { ...process.env, CI: 'true' }
@@ -66,11 +67,11 @@ 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 配置（与诊断同口径）。
+          // 安装用的 npm 源：设置里显式选择优先；未配置时读本机 npm 配置（与诊断同一套规则）。
           // 只有公共源允许失败后换源；自定义/内网源保持单一候选，避免私有包名泄露给公共源。
           const registries = registryCandidates(
             settings.npmRegistry,
@@ -78,7 +79,7 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             settings.registryFallback,
           )
           // 全局 npm 安装（`npm install -g <pkgs>`）：不进任何 profile、无需宿主重启。
-          // 包列表优先取 body.globalNpm，兜底从 rawRepo 解析，保证直接调 API 传完整命令也能识别。
+          // 包列表优先取 body.globalNpm，取不到时再从 rawRepo 解析，保证直接调 API 传完整命令也能识别。
           const bodyGlobalNpm = Array.isArray((body as { globalNpm?: unknown }).globalNpm)
             ? (body as { globalNpm: unknown[] }).globalNpm.filter((x): x is string => typeof x === 'string' && x !== '')
             : []
@@ -89,7 +90,7 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
               sendJson(response, 400, { error: 'unsupported install target' })
               return
             }
-            // 通道门禁与安装通道同构：全局安装本质是 npm 操作，吃「启用 NPM 安装」开关
+            // 通道校验与安装通道同构：全局安装本质是 npm 操作，吃「启用 NPM 安装」开关
             if (source !== 'catalog' && !settings.enableNpmInstall) {
               sendJson(response, 403, { error: 'npm installs are disabled by the security settings' })
               return
@@ -122,8 +123,8 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             return
           }
           const target = rawRepo
-          // 钉住精确版本（Hub 自我更新）：最新版可能仍在 pnpm 供应链门禁内，
-          // 客户端提示的是「已过门禁」的版本，服务端必须按该版本安装而不是 @latest。
+          // 锁定精确版本（Hub 自我更新）：最新版可能仍在 pnpm 发布冷却期内，
+          // 客户端提示的是「已过冷却期」的版本，服务端必须按该版本安装而不是 @latest。
           const pinVersion = typeof (body as { version?: unknown }).version === 'string'
             ? (body as { version: string }).version.trim()
             : ''
@@ -181,6 +182,15 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             }
             ordered = [chosen, ...registries.filter((r) => r !== chosen)]
           }
+          // 新安装锁定「已过发布冷却期」的最高稳定版：pnpm 对发布还不满 24 小时的版本会不提示地回退，
+          // 锁定后装到的就是预期版本。更新已有目标时客户端已按冷却期筛选，继续走 @latest。
+          let installSpec = pinVersion !== '' ? `${target}@${pinVersion}` : undefined
+          if (installSpec === undefined && already === null) {
+            // 解析源与安装首选源一致，锁定的版本一定存在于真正会用的那个源；解析失败则不锁定，不阻断安装。
+            // 超时 5s：网络刚探测通过，卡住时也不能把安装请求拖到默认的 8s
+            const release = await lookupReleaseAge(target, ordered[0] ?? '', effectiveProxy, 5000)
+            if (release !== null && release.installable !== null) installSpec = `${target}@${release.installable.version}`
+          }
           // 入队前复检：网络探测的 await 期间并发请求可能已通过上方检查，而此处到 startPluginMutation
           // 之间无 await，JS 单线程保证同一目标至多一个任务，杜绝双击/并发双任务。
           if (hasQueuedTarget(target)) {
@@ -190,7 +200,7 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
           // 后台启动 CLI；客户端轮询 /status 获取进度
           const task = startPluginMutation({
             // mode=update（已安装目标的覆盖更新）以 update 动作入队：
-            // 日志按 update 类别落盘（update.start/done/fail），实际 CLI 执行仍是 add <target>@latest
+            // 日志按 update 类别写入磁盘（update.start/done/fail），实际 CLI 执行仍是 add <target>@latest
             action: mode === 'update' ? 'update' : 'add',
             profile,
             target,
@@ -198,13 +208,13 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             displayTarget: githubRepoOf(displayRepo) ?? undefined,
             // 覆盖更新：npm 命令显式 @latest（pnpm add 无版本对已存在依赖是幂等的，不加版本不会真更新）
             updateNpm: mode === 'update',
-            // 运行中 loader：安装成功后把新插件热挂进 loader，非桌面端 + 纯服务端插件无需重启即生效
+            // 运行中 loader：安装成功后把新插件热加载进 loader，非桌面端 + 纯服务端插件无需重启即生效
             loader,
             timeoutMs: COMMAND_TIMEOUT_MS,
             env: mutationEnv(settings),
             // 候选源（首选在前）：任务内遇到传输层失败时按顺序换源重试
             registries: ordered,
-            installSpec: pinVersion !== '' ? `${target}@${pinVersion}` : undefined,
+            installSpec,
             // 自定义安装入口渠道：日志/报错据此溯源
             installChannel,
           })

package/src/server/http/npm-release-age.ts

@@ -4,10 +4,12 @@
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
  * npm 包发布时间查询路由：按已安装插件的 npm 包名按需查询最新版本的发布时间，
- * 供客户端判定 pnpm 24h 供应链门禁（发布未满门槛的版本不提示更新）。
+ * 供客户端判定 pnpm 24h 发布冷却期（发布还不满 24 小时的版本不提示更新）。
  */
 import { systemProxy } from '../services/probe.ts'
 import { lookupReleaseAge, parseReleaseAgeRequest } from '../services/npm-release-age.ts'
+import { userNpmRegistry } from '../services/install/registry-fallback.ts'
+import { profileDirectory } from '../services/profile/profile.ts'
 import { loadSettings } from '../services/settings.ts'
 import { readJsonBody, requireTrustedPost, sendJson, type WebRoute, type WebServerService } from './shared.ts'
 
@@ -25,13 +27,17 @@ export function registerNpmReleaseAgeRoutes(webServer: WebServerService, profile
             return
           }
           const settings = loadSettings(profile)
-          // 代理口径与安装/目录一致：设置里的代理 → 系统代理 → 环境变量 → 直连
+          // 代理规则与安装/目录一致：设置里的代理 → 系统代理 → 环境变量 → 直连
           const proxy = settings.proxy !== ''
             ? settings.proxy
             : (systemProxy() ?? process.env.HTTPS_PROXY ?? process.env.https_proxy ?? '')
           // 并发查询：单包各自带超时且失败即 null，整体不因任一包失败而失败
+          // 查询源与安装首选源同一套规则（设置 → 本机 npm 配置）：安装锁定的版本必须来自真正要用的那个源
+          const registry = settings.npmRegistry !== ''
+            ? settings.npmRegistry
+            : userNpmRegistry(profileDirectory(profile))
           const results = await Promise.all(packages.map(async (name) =>
-            [name, await lookupReleaseAge(name, settings.npmRegistry, proxy)] as const))
+            [name, await lookupReleaseAge(name, registry, proxy)] as const))
           sendJson(response, 200, { packages: Object.fromEntries(results) })
         } catch (error) {
           sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) })

package/src/server/http/shared.ts

@@ -42,7 +42,7 @@ function findPids() {
 
 const targets = findPids()
 // 一个监听进程都没找到 = 端口探测本身就失败了（netstat 输出格式 / 本地化差异），
-// 旧宿主仍占着端口。此时再拉一个 dsh web 只会在日志里以 EADDRINUSE 静默退出，
+// 旧宿主仍占着端口。此时再拉一个 dsh web 只会在日志里以 EADDRINUSE 无提示地退出，
 // 用户却看到「重启完成」——不制造这种假象，留一行可诊断的记录后退出。
 if (targets.length === 0) {
   logLine('restart aborted: no listener found on port ' + port)

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

@@ -4,7 +4,7 @@
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
  * 宿主与命令行工具的版本探测：dsh 版本同时用于诊断快照和「插件要求更高 DSH」判定，
- * pnpm/npm/git 只用于诊断快照。同步探测 + 1500ms 超时兜底，拿不到一律 null，绝不挂起。
+ * pnpm/npm/git 只用于诊断快照。同步探测 + 1500ms 超时保护，拿不到一律 null，绝不挂起。
  */
 import { readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
@@ -39,7 +39,7 @@ export function toolVersion(cmd: string, args: string[]): string | null {
 let cachedDshVersion: string | null = null
 
 /** 宿主 dsh 版本：优先 `dsh --version`；拿不到再从入口 `process.argv[1]` 向上找 package.json
- *  （dsh 不在 PATH 时兜底）。探测成功即缓存，失败不缓存以便下次重试。 */
+ *  （dsh 不在 PATH 时使用）。探测成功即缓存，失败不缓存以便下次重试。 */
 export function hostDshVersion(): string | null {
   if (cachedDshVersion !== null) return cachedDshVersion
   const viaCli = toolVersion('dsh', ['--version'])

package/src/server/services/install/dsh-compat.ts

@@ -9,7 +9,7 @@
  * 不再把这类失败归成「未分类」丢给用户或插件作者。
  *
  * 只在失败路径调用：peer 不满足本身通常只是警告，成功安装时不该出现这个提示；
- * 任何网络/解析异常都静默返回 null，不改变原有失败处理。
+ * 任何网络/解析异常都悄悄返回 null，不改变原有失败处理。
  */
 import { hostDshVersion } from '../host-version.ts'
 

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

@@ -36,14 +36,14 @@ export interface InstallTask {
   status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled'
   timedOut: boolean
   exitCode: number | null
-  /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出，阶段行兜底 */
+  /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出；没有进度行时按阶段行估算 */
   progress: number
   /** 输出行最新在前（消费方展示尾部）。 */
   lines: string[]
-  /** 完成后是否仍需宿主重启才生效：仅「热挂载失败 / 非 dsh 插件 / 更新（ESM 缓存取不到新代码）/
-   *  无 loader」等刷新解决不了的兜底场景为 true（弹窗给「立即重启」）；其余一律 false。 */
+  /** 完成后是否仍需宿主重启才生效：仅「热加载失败 / 非 dsh 插件 / 更新（ESM 缓存取不到新代码）/
+   *  无 loader」等刷新解决不了的例外场景为 true（弹窗给「立即重启」）；其余一律 false。 */
   needsRestart: boolean
-  /** 完成结果是否只需刷新页面即生效（插件已热挂进运行中 loader，仅剩客户端 UI 待页面重新加载，
+  /** 完成结果是否只需刷新页面即生效（插件已热加载进运行中 loader，仅剩客户端 UI 待页面重新加载，
    *  网页端与桌面端一致）：true 时关闭结果弹窗即自动刷新页面，不给手动刷新按钮。 */
   needsReload?: boolean
   /** 自更新成功、但该 profile 的 dsh.profile.bundles 已不含 dsh-plugin：重启后市场不会出现 */
@@ -79,7 +79,7 @@ export interface QueueItem {
     installChannel?: 'npm'
     /** npm 源候选（首选在前）：传输层失败时按顺序换源重试 */
     registries?: string[]
-    /** 精确安装 spec（Hub 自我更新钉版本） */
+    /** 精确安装 spec（Hub 自我更新时锁定版本） */
     installSpec?: string
   }
 }

package/src/server/services/install/npm-resolve.ts

@@ -83,7 +83,7 @@ export function isDshNpmPackageForRepo(packageName: string, repo: string, regist
 
 /**
  * 解析仓库改名后的规范 `owner/repo`：GitHub 对已改名仓库返回 301，跟随跳转取最终地址。
- * 与其它 GitHub 访问同口径走 curl + 代理 env（Node 内置 https 读不到系统代理）。
+ * 与其它 GitHub 访问同一套规则走 curl + 代理 env（Node 内置 https 读不到系统代理）。
  * 未改名、仓库不存在、网络失败或 curl 不可用都返回 ''，调用方按原名继续。
  */
 async function canonicalRepo(repo: string, proxy: string): Promise<string> {

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

@@ -7,7 +7,7 @@
  * 回显到控制台，真正的 pnpm 报错写进该路径的 operation 日志。这里从输出里解析出该路径
  * 并读取其尾部，补进失败信息 —— 否则前端拿不到任何错误特征，只能把失败归为「未知」。
  * 只允许读 profile 目录下的 pnpm.log（dsh 自己的 operation 日志），
- * 防止插件把任意路径打印进日志造成越权读取；任何异常都静默降级（返回 null），
+ * 防止插件把任意路径打印进日志造成越权读取；任何异常都降级为 null，
  * 不改变原有失败处理。
  */
 import { readFileSync, readdirSync, statSync } from 'node:fs'
@@ -53,7 +53,7 @@ export function operationLogPathOf(output: string): string | null {
 /**
  * 只允许读 profile 目录下的 pnpm.log（dsh 自己的操作日志）：
  * 绝对路径必须落在该目录内，相对路径按该目录解析。
- * 未提供 profileDir 时退回旧口径（路径须含 .plugin-manager），防止插件打印任意路径造成越权读取。
+ * 未提供 profileDir 时退回旧规则（路径须含 .plugin-manager），防止插件打印任意路径造成越权读取。
  */
 function allowedLogPath(raw: string, profileDir?: string): string | null {
   const path = resolve(profileDir ?? '', raw)
@@ -96,7 +96,7 @@ export function hasSubstantiveOutput(output: string): boolean {
 /**
  * 运行期抓取：宿主的 operation 日志只在命令运行期间存在，结束后可能被清理，
  * 退出后再按路径读往往已经拿不到。这里在安装过程中轮询 profile 下最新的
- * `.plugin-manager/logs/<operation>/pnpm.log`，用抓到的内容兜底。
+ * `.plugin-manager/logs/<operation>/pnpm.log`，用抓到的内容补全。
  * 只认本次运行产生的新文件（mtime 晚于启动基线），避免复述上一次安装的日志。
  */
 export function createOperationLogTap(profileDir: string): { stop: () => string } {

package/src/server/services/install/preflight.ts

@@ -10,7 +10,7 @@ import { spawnSync } from 'node:child_process'
 export const GIT_MISSING_DETAIL = '[git-missing] the git CLI was not found on this machine (install git and add it to the PATH, then retry)'
 
 /** 命令存在性探测：which/where 找 PATH 里的命令。
- *  探测自身异常（which/where 不可用等）返回 true，不拦截安装，交给装后校验兜底。 */
+ *  探测自身异常（which/where 不可用等）返回 true，不拦截安装，交给装后校验处理。 */
 export function commandOnPath(cmd: string, env?: NodeJS.ProcessEnv): boolean {
   try {
     const probe = process.platform === 'win32' ? 'where' : 'which'

package/src/server/services/install/registry-fallback.ts

@@ -1,6 +1,6 @@
 /**
- * npm 源降级：当前源是公共镜像时，传输层失败后按「当前源 → 官方 → npmmirror」
- * 自动换源重试；自定义/内网源不降级，避免私有包名泄露给公共源。
+ * npm 换源：当前源是公共镜像时，传输层失败后按「当前源 → 官方 → npmmirror」
+ * 自动换源重试；自定义/内网源不换源，避免私有包名泄露给公共源。
  */
 import { spawnSync } from 'node:child_process'
 
@@ -37,7 +37,7 @@ export function isPublicRegistry(value: string): boolean {
 
 /**
  * 依次尝试的源：显式配置 → 本机 npm 配置 → 官方源。
- * 只有公共源才追加后备（最多 3 个）；关闭降级或源不在白名单时只返回它自己。
+ * 只有公共源才追加后备（最多 3 个）；关闭换源或源不在白名单时只返回它自己。
  */
 export function registryCandidates(configured: string, userRegistry: string, enabled: boolean): string[] {
   const base = normalizeRegistry(configured) || normalizeRegistry(userRegistry) || PUBLIC_REGISTRIES[0]!

package/src/server/services/install/release-target.ts

@@ -6,7 +6,7 @@
  * 预构建 release 直链的仓库身份解析。部分插件（如 loopx）当初以 GitHub release 的 .tgz
  * 安装过，仓库 HEAD 反而是 monorepo 根、走 git 直装会因缺入口文件失败；老安装记录里留的
  * 就是这种 release 直链。这里把「历史安装目标」还原成所属仓库身份，供已装态读回、队列
- * 去重与展示复用（单一事实来源，避免两端口径漂移）。
+ * 去重与展示复用（单一事实来源，避免两端规则漂移）。
  *
  * 只接受固定形态的 HTTPS `github.com/<owner>/<repo>/releases/download/<tag>/<asset>.tgz`：
  * 输入是记录/展示数据、绝非 shell 代码，绝不执行其文本；跨仓跳转、外部主机、凭据、
@@ -21,7 +21,7 @@ export interface GithubReleaseTarget {
   repo: string
 }
 
-/** 完整命令前缀：`dsh plugin --profile <p> add|update <target>`（与 profile.ts installTargetOf 同口径）。 */
+/** 完整命令前缀：`dsh plugin --profile <p> add|update <target>`（与 profile.ts installTargetOf 同一套规则）。 */
 const DSH_PLUGIN_CMD_RE = /^dsh[ \t]+plugin[ \t]+--profile(?:[ \t]+|=)[A-Za-z0-9_-]+[ \t]+(?:add|update)[ \t]+(.+)$/i
 
 /** 固定形态的 release .tgz 直链：主机、路径段与扩展名全部锁死。 */