dsh-plugin 2.3.1 → 2.3.3

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

@@ -148,7 +148,7 @@ function pushLine(task: InstallTask, line: string): void {
   if (estimate > 0) {
     task.progress = Math.max(task.progress, estimate)
   } else if (task.status === 'running' && task.progress < 85) {
-    // 兜底：行无解析格式也随输出量推进，保证进度条始终在动（不会卡在 0）
+    // 补充：行无解析格式也随输出量推进，保证进度条始终在动（不会卡在 0）
     task.progress = Math.max(task.progress, 6 + Math.min(79, task.lines.length * 2))
   }
 }
@@ -220,7 +220,7 @@ export function desktopCliBootstrap(entry: string): string | null {
 }
 
 /**
- * 传给 CLI 的安装目标：钉住版本优先（Hub 自我更新提示的是已过供应链门禁的版本），
+ * 传给 CLI 的安装目标：锁定版本优先（Hub 自我更新提示的是已过发布冷却期的版本），
  * 其次 npm 的 add/update 都显式 `@latest`；git 源、全局安装、已带版本/tag 的 spec 保持原样。
  */
 export function npmInstallTargetOf(target: string, opts: { update: boolean; global: boolean; pinned?: string; add?: boolean }): string {
@@ -231,6 +231,13 @@ export function npmInstallTargetOf(target: string, opts: { update: boolean; glob
   return `${target}@latest`
 }
 
+/** 重复卸载：目标已不在 profile 依赖里，pnpm 报「没有这个依赖」。
+ *  结果与卸载成功等价 —— 按失败上报会弹出错误并自动提一条不存在的 Issue。 */
+export function isAlreadyRemoved(action: 'add' | 'remove' | 'update', output: string): boolean {
+  if (action !== 'remove') return false
+  return /ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS|no such dependency found/i.test(output)
+}
+
 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' })
@@ -280,7 +287,7 @@ export function startPluginMutation(options: {
   globalNpm?: string[]
   /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
   displayTarget?: string
-  /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目，两类操作都尽量立即生效
+  /** 运行中 loader：安装成功后热加载新条目、卸载成功后停用旧条目，两类操作都尽量立即生效
    *  （缺失时安装/卸载仍需重启） */
   loader?: LoaderHandle
   /** 入队前已尝试的安装方式：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
@@ -290,10 +297,10 @@ export function startPluginMutation(options: {
   /** 自定义安装入口渠道（NPM 包卡片）：任务输出行与系统日志据此溯源「从哪个入口发起」；
    *  目录插件安装不传 */
   installChannel?: 'npm'
-  /** npm 源候选（首选在前）：传输层失败时按顺序换源重试，空/单个表示不降级 */
+  /** npm 源候选（首选在前）：传输层失败时按顺序换源重试，空/单个表示不换源 */
   registries?: string[]
-  /** 精确安装 spec（如 `dsh-plugin@2.0.5`）：Hub 自我更新提示的是已过供应链门禁的版本，
-   *  必须钉住安装，不能再用 @latest 被带回门禁内的最新版 */
+  /** 精确安装 spec（如 `dsh-plugin@2.0.5`）：Hub 自我更新提示的是已过发布冷却期的版本，
+   *  必须锁定安装，不能再用 @latest 被带回冷却期内的最新版 */
   installSpec?: string
 }): InstallTask {
   // 卸载入队时先快照「该包是否带客户端 UI」：卸载完成后包已从磁盘删除，读不到 package.json，
@@ -414,7 +421,7 @@ function spawnMutation(options: {
   task?: InstallTask
   /** 待重启行的展示目标（owner/repo）：与 mutation 目标解耦——卸载的 mutation 目标是 npm 包名，展示要回退到仓库名 */
   displayTarget?: string
-  /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目（缺失时仍需重启） */
+  /** 运行中 loader：安装成功后热加载新条目、卸载成功后停用旧条目（缺失时仍需重启） */
   loader?: LoaderHandle
   /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
   globalNpm?: string[]
@@ -439,10 +446,10 @@ function spawnMutation(options: {
   }
   // 安装/更新 npm 包都显式 @latest：pnpm add <pkg>（无版本）对已存在的精确 spec 是幂等的，
   // 会原样留用旧版本（更新不生效，普通安装也可能装回不支持当前宿主的旧包）。
-  // update 动作同样执行 `add <target>@latest`，CLI 动词透传 add，不与官方 update 动词分叉。
+  // update 动作同样执行 `add <target>@latest`，CLI 动词原样传递 add，不与官方 update 动词分叉。
   const isUpdate = action === 'update' || updateNpm === true
   const cliAction = action === 'update' ? 'add' : action
-  // 钉住版本优先于 @latest：提示的是「已过门禁」的版本，装 latest 会被 pnpm 拒绝
+  // 锁定版本优先于 @latest：提示的是「已过冷却期」的版本，装 latest 会被 pnpm 拒绝
   const npmUpdateTarget = npmInstallTargetOf(target, { update: isUpdate, global: isGlobalNpm, pinned: installSpec, add: cliAction === 'add' })
   const args = isGlobalNpm
     ? ['install', '-g', ...(globalNpm ?? [])]
@@ -454,7 +461,7 @@ function spawnMutation(options: {
   if (task && !task.attempts.includes(executed)) {
     task.attempts.push(executed)
   }
-  // 单次 spawn 并捕获结果：流式输出打日志 + 超时/取消兜底，close 后 resolve。
+  // 单次 spawn 并捕获结果：流式输出打日志 + 超时、取消时收尾，close 后 resolve。
   // 不做任何终态后处理（exitCode/status/needsRestart 由下方统一收尾），
   // 这样全局 npm 首次失败后可以干净地换参数重试一次。
   const spawnOnce = (attemptArgs: string[], registry?: string): Promise<InstallResult> => new Promise((resolveOnce) => {
@@ -497,7 +504,7 @@ function spawnMutation(options: {
         }
       }
       // invocation.env 是「必须叠加」的变量（打包桌面端的 ELECTRON_RUN_AS_NODE）：
-      // 没有它时保持 env 原样透传，有它时必须基于完整环境叠加，否则子进程会丢掉 PATH。
+      // 没有它时保持 env 原样传递，有它时必须基于完整环境叠加，否则子进程会丢掉 PATH。
       // registry 最后写入：换源重试只改这一层，pnpm/npm 都认 npm_config_registry。
       const childEnv: NodeJS.ProcessEnv = { ...(env ?? process.env), ...(invocation.env ?? {}) }
       if (registry !== undefined) {
@@ -534,13 +541,13 @@ function spawnMutation(options: {
     }
     if (task) runningChildren.set(task.id, child)
 
-    // 兜底定时器句柄：整段超时 / exit 后 close 宽限 / 强制收尾
+    // 最终超时定时器句柄：整段超时 / exit 后 close 宽限 / 强制收尾
     let timer: ReturnType<typeof setTimeout> | undefined
     let progressTimer: ReturnType<typeof setInterval> | undefined
     let exitWatch: ReturnType<typeof setTimeout> | undefined
     let forceSettle: ReturnType<typeof setTimeout> | undefined
 
-    // 唯一收尾入口：close / error / 兜底超时 三者只放行一次，确保任务持续推进
+    // 唯一收尾入口：close / error / 最终超时 三者只放行一次，确保任务持续推进
     const settleOnce = (result: InstallResult): void => {
       if (settled) return
       settled = true
@@ -556,7 +563,7 @@ function spawnMutation(options: {
       timedOut = true
       stopChild(child)
     }, timeoutMs)
-    // 时间兜底：即使 CLI 静默不吐进度行，进度条也单调推进，不会卡在 0
+    // 时间补充：即使 CLI 悄悄不吐进度行，进度条也单调推进，不会卡在 0
     progressTimer = setInterval(() => {
       if (task && task.status === 'running' && task.progress < 85) task.progress += 1
     }, 500)
@@ -565,7 +572,7 @@ function spawnMutation(options: {
       if (kind === 'stdout') stdout = (stdout + text).slice(-CAPTURE_LIMIT_BYTES)
       else stderr = (stderr + text).slice(-CAPTURE_LIMIT_BYTES)
       if (task) {
-        // 原生透传 pnpm/npm 输出：stdout/stderr 原样入日志，不做格式化，保证报错信息完整可见
+        // 原生原样传递 pnpm/npm 输出：stdout/stderr 原样入日志，不做格式化，保证报错信息完整可见
         for (const line of text.split(/\r?\n|\r/)) {
           if (line.trim() !== '') pushLine(task, line.trimEnd())
         }
@@ -582,7 +589,7 @@ function spawnMutation(options: {
         if (settled) return
         if (task && task.status !== 'cancelled') pushLine(task, '[stale pipe] force closing child')
         stopChild(child)
-        // 清理后极端情况下 close 仍未触发（kill 失败）：再兜底强制收尾
+        // 清理后极端情况下 close 仍未触发（kill 失败）：再强制收尾一次
         forceSettle = setTimeout(() => {
           if (settled) return
           if (task && task.status !== 'cancelled') {
@@ -642,7 +649,7 @@ function spawnMutation(options: {
       if (task) pushLine(task, '[npm] peer-set resolution crashed npm (known npm bug) — retrying with --legacy-peer-deps')
       result = await spawnOnce(retryArgs, activeRegistry)
     }
-    // 超时被强杀 ≠ 没装上：命中的安装可能已经落盘（日志里 pnpm 已打印 Done，只是 dsh 进程迟迟不退出
+    // 超时被强杀 ≠ 没装上：命中的安装可能已经写入磁盘（日志里 pnpm 已打印 Done，只是 dsh 进程迟迟不退出
     // 而被我们超时掐掉）。判失败之前先复核 profile —— 目标已在依赖里、且声明分发的入口文件都在，
     // 就按成功收尾，避免「其实装好了却报安装失败」并被自动归档成未知失败。
     if (result.timedOut && !wasInstalled && action !== 'remove' && !isGlobalNpm && task?.status !== 'cancelled') {
@@ -652,6 +659,13 @@ function spawnMutation(options: {
         if (task) pushLine(task, '[timeout] the install had already completed — treating it as a success')
       }
     }
+    // 重复卸载：依赖已经不在 profile 里，pnpm 拒绝移除并报「没有这个依赖」。
+    // 与卸载成功同义（用户要的结果已达成），按成功收尾，避免误报失败、误提 Issue。
+    if (!result.timedOut && task?.status !== 'cancelled'
+      && isAlreadyRemoved(action, `${result.stderr}\n${result.stdout}`)) {
+      result = { ...result, exitCode: 0, error: null }
+      if (task) pushLine(task, '[already removed] the package is no longer in the profile — treating it as uninstalled')
+    }
     // 统一终态后处理：exitCode/status/needsRestart 以最后一次尝试为准
     if (task) {
       task.exitCode = result.exitCode
@@ -676,17 +690,17 @@ function spawnMutation(options: {
           } else if (action === 'remove' && loader) {
             // 卸载成功 → 主动从运行中 loader 停用该包条目：
             //  - 停用成功：服务端即时卸载；带客户端 UI 的插件面板要页面刷新才摘除（无需重启宿主）
-            //  - 停用失败 / 超时：回退「待重启」兜底清理（刷新解决不了，登记常驻提醒）
+            //  - 停用失败 / 超时：回退「待重启」提醒（刷新解决不了，登记常驻提醒）
             const removal = await removeLoadedEntry(loader, target)
             task.needsRestart = !removal.ok
             task.needsReload = removal.ok && removal.live && task.hadClientUi === true
             if (task.needsRestart) addPendingRestart(displayTarget ?? target, 'uninstall')
             else clearPendingRestart(displayTarget ?? target)
           } else if (action !== 'remove' && !isUpdate && loader) {
-            // 安装成功 → 尝试把新插件热挂进运行中 loader，让插件无需重启宿主即生效。
+            // 安装成功 → 尝试把新插件热加载进运行中 loader，让插件无需重启宿主即生效。
             // 挂上了：服务端即时生效；带客户端 UI 的插件还需页面重新加载（宿主按请求现场
             //   拼装 __DSH_BOOT__ 注入清单，网页端与桌面端一致，刷新即可）。
-            // 挂不上 / 非 dsh 插件 / 无法定位包名：回退「待重启」提醒（保证不静默失效）。
+            // 挂不上 / 非 dsh 插件 / 无法定位包名：回退「待重启」提醒（保证不会无声失效）。
             const { name } = verifyInstalledEntry(profile, target)
             if (name !== null && isDshPlugin(profile, name) && await mountLoadedEntry(loader, name)) {
               task.needsReload = hasClientUi(profile, name)
@@ -696,7 +710,7 @@ function spawnMutation(options: {
               addPendingRestart(displayTarget ?? target, 'install')
             }
           } else {
-            // 更新（ESM 缓存下热挂取不到新代码）/ 无 loader 的安装或卸载 → 登记待重启：
+            // 更新（ESM 缓存下热加载取不到新代码）/ 无 loader 的安装或卸载 → 登记待重启：
             // 插件要宿主重启才会挂载/卸载干净，重启前一直提醒；展示目标用 displayTarget（owner/repo）
             task.needsRestart = true
             addPendingRestart(displayTarget ?? target, action === 'remove' ? 'uninstall' : 'install')
@@ -708,7 +722,7 @@ function spawnMutation(options: {
       }
     }
     // 带上最终生效的源：后续注解（如 [dsh-too-old]）读元数据必须与安装同源，
-    // 否则换过源之后会去另一个源查，查不到就静默漏报
+    // 否则换过源之后会去另一个源查，查不到就漏报
     return activeRegistry === undefined ? result : { ...result, registry: activeRegistry }
   })()
 }
@@ -854,7 +868,7 @@ async function annotateDshTooOld(result: InstallResult, options: {
   // 全局 npm 装的是本机 CLI 工具，不进 profile，没有宿主版本要求
   if ((options.globalNpm ?? []).length > 0) return result
   // 用安装**实际**使用的源读元数据：换源重试后候选表首位可能并不是真正生效的那个，
-  // 用错源会读不到包而静默漏报；私有源/镜像里同样能读到包声明的 engines
+  // 用错源会读不到包而漏报；私有源/镜像里同样能读到包声明的 engines
   const line = await dshTooOldMarker(options.target, { registry: result.registry ?? options.registries?.[0] })
   if (line === null) return result
   if (options.task && options.task.status !== 'cancelled') pushLine(options.task, line)
@@ -873,7 +887,7 @@ export function hostSpawnMarker(invocation: Invocation, error: unknown): string
 }
 
 /**
- * 执行插件变更，带一条恢复路径：当 `add` 因 pnpm 的 allowBuilds 门禁拦下构建脚本而失败 ——
+ * 执行插件变更，带一条恢复路径：当 `add` 因 pnpm 的 allowBuilds 限制拦下构建脚本而失败 ——
  * 或是 git 源包自己的 `prepare`（`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，key 取自打印的
  * key@url 提示），或是某依赖的原生构建（`ERR_PNPM_IGNORED_BUILDS`，key = 列出的 name@version）——
  * 就把确切的 key 写进 profile 的 pnpm-workspace.yaml 并重试一次。
@@ -888,7 +902,7 @@ export async function runPluginMutation(options: {
   task?: InstallTask
   /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
   displayTarget?: string
-  /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目（缺失时仍需重启） */
+  /** 运行中 loader：安装成功后热加载新条目、卸载成功后停用旧条目（缺失时仍需重启） */
   loader?: LoaderHandle
   /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
   globalNpm?: string[]
@@ -897,7 +911,7 @@ export async function runPluginMutation(options: {
   /** 精确安装 spec（如 `dsh-plugin@2.0.5`）：见 startPluginMutation 同名说明 */
   installSpec?: string
 }): Promise<InstallResult> {
-  // operation 日志只在运行期存在（宿主结束后可能清掉），先开抓取，退出后按路径读作兜底
+  // operation 日志只在运行期存在（宿主结束后可能清掉），先开抓取，退出后按路径读取作为后备
   const profileDir = profileDirectory(options.profile)
   const logTap = createOperationLogTap(profileDir)
   let result = await spawnMutation(options)

package/src/server/services/loader.ts

@@ -3,8 +3,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * 运行中 loader 的读取、停用与热挂载：卸载成功后对匹配条目做 live-disable、
- * 安装成功后把新插件条目热挂进运行中的 loader，让两类操作都尽量立即生效
+ * 运行中 loader 的读取、停用与热加载：卸载成功后对匹配条目做 live-disable、
+ * 安装成功后把新插件条目热加载进运行中的 loader，让两类操作都尽量立即生效
  * （刷新页面即可，无需重启宿主）。
  */
 import { readFileSync } from 'node:fs'
@@ -12,7 +12,7 @@ import { join } from 'node:path'
 import { profileDirectory } from './profile/profile.ts'
 
 /**
- * 运行中 loader 的最小接口：卸载即时停用 / 安装即时热挂载用。
+ * 运行中 loader 的最小接口：卸载即时停用 / 安装即时热加载用。
  * 对应官方 `ctx.loader`（cordis-plugin-loader 的 Loader 服务）的读取、新建与移除面。
  * 移除方式：对匹配条目 live-disable（`entry.update({ disabled: true })`），
  * 而不是 `loader.remove(id)` —— disable 走 Entry.update 的 disabled 分支，不触发
@@ -32,7 +32,7 @@ export interface LoaderHandle {
    *  `- insert: - name: <pkg>` 行；Loader.write() 为空实现，不会写盘（重启后由
    *  profile 的 bundles 清单重新挂载，不会重复挂载）。返回新条目的 id。 */
   create(options: { id?: string; name: string }): Promise<string>
-  /** 按 id 解析条目：热挂载后确认 fiber 真的起来了（import 失败时条目在、但 fiber 为空）。 */
+  /** 按 id 解析条目：热加载后确认 fiber 真的起来了（import 失败时条目在、但 fiber 为空）。 */
   resolve(id: string): { id: string; options?: { name?: string; disabled?: boolean | null }; fiber?: unknown; subgroup?: unknown }
 }
 
@@ -82,7 +82,7 @@ function nameMatches(entryName: string | undefined, target: string): boolean {
   // 2) 条目是去 scope 的短名（bundle patch 手写短名最常见）
   if (e === tShort) return true
   // 3) 反向变体：目标短名可能就是条目的完整形式（条目 `scope-widget`，
-  //    目标短名 `widget` 是它的尾段）——用「条目名以短名结尾」收口，避免误伤。
+  //    目标短名 `widget` 是它的尾段）——以「条目名以短名结尾」作为匹配条件，避免误伤。
   if (tShort.length >= 2 && e.endsWith(`-${tShort}`)) return true
   // 4) 条目名是目标包内的模块路径（`aegis/extensions/dsh/index.js` 属于包 `aegis`，
   //    `@scope/pkg/dist/x.js` 属于 `@scope/pkg`）：归一化会吞掉路径分隔符，
@@ -102,12 +102,12 @@ function nameMatches(entryName: string | undefined, target: string): boolean {
  *  - `{ ok: true, live: false }`：宿主从未加载过它（磁盘已干净），无需刷新/重启；
  *  - `{ ok: true, live: true }`：曾在 loader 中存活且已 live-disable —— 服务端即时卸载；
  *    带客户端 UI 的插件面板要页面刷新才摘除（由调用方按 `hadClientUi` 决定 needsReload）；
- *  - `{ ok: false, live: true }`：disable 失败 / 超时，需宿主重启兜底清理。
+ *  - `{ ok: false, live: true }`：disable 失败 / 超时，需宿主重启后清理。
  * 宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
  */
 export async function removeLoadedEntry(loader: LoaderHandle, name: string): Promise<{ ok: boolean; live: boolean }> {
   if (name === 'dsh-plugin' || name.startsWith('@deepseek-ai/')) return { ok: false, live: true }
-  // 5s 超时兜底：fiber dispose 卡住时不能让卸载任务（乃至整个队列）被拖死
+  // 5s 超时保护：fiber dispose 卡住时不能让卸载任务（乃至整个队列）被拖死
   const removal = (async () => {
     const entries = dumpLoaderEntries(loader)
     const match = entries.find((e) => e.name === name)
@@ -151,7 +151,7 @@ export async function removeLoadedEntry(loader: LoaderHandle, name: string): Pro
 }
 
 /**
- * 安装成功后把新插件热挂进运行中 loader（等价 profile bundle patch 的
+ * 安装成功后把新插件热加载进运行中 loader（等价 profile bundle patch 的
  * `- insert: - name: <pkg>` 行），让插件无需重启宿主即可生效。
  * 做法：在 Loader 根组新建条目并启动 —— Loader.write() 为空实现，不写盘；
  * 重启后由 profile 的 bundles 清单重新挂载，不会重复。
@@ -171,7 +171,7 @@ export async function mountLoadedEntry(loader: LoaderHandle, name: string): Prom
     console.log(`[hub-install] hot mount ${name}: entry ${id} created but not running (import failed?)`)
     return false
   })()
-  // 10s 超时兜底：import 卡住时不能让装完收尾（乃至整个队列）被拖死
+  // 10s 超时保护：import 卡住时不能让装完收尾（乃至整个队列）被拖死
   return Promise.race([
     mounting.catch((error) => {
       console.log(`[hub-install] hot mount ${name} failed: ${error instanceof Error ? error.message : String(error)}`)
@@ -183,7 +183,7 @@ export async function mountLoadedEntry(loader: LoaderHandle, name: string): Prom
 
 /**
  * 已安装包是否带客户端 UI（package.json 的 `dsh.client` 声明）：client-modules 据它把
- * 客户端 bundle 注入宿主页面。带 UI 的插件热挂载后需要页面重新加载才会渲染，
+ * 客户端 bundle 注入宿主页面。带 UI 的插件热加载后需要页面重新加载才会渲染，
  * 网页端与桌面端一致 —— `__DSH_BOOT__` 注入清单由宿主服务端按请求现场拼装，
  * 壳不缓存，所以桌面端刷新页面同样能拿到新清单，无需重开 App。
  */

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

@@ -3,9 +3,9 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * npm 包最新版本的发布时间查询：为「已安装插件是否有更新」提供供应链门禁依据。
- * pnpm 对发布不满 24h（dsh profile minimumReleaseAge=1440）的版本会静默回退到旧版本，
- * 因此发布未满门槛的版本不该提示更新（否则用户点了也装不上）。
+ * npm 包最新版本的发布时间查询：为「已安装插件是否有更新」提供发布冷却期依据。
+ * pnpm 对发布不满 24h（dsh profile minimumReleaseAge=1440）的版本会不提示地回退到旧版本，
+ * 因此发布还不满 24 小时的版本不该提示更新（否则用户点了也装不上）。
  * 结果按包名内存缓存，同一次会话内不重复请求；失败/超时/响应过大一律返回 null，绝不抛错、绝不阻塞。
  */
 import { get as httpsGet } from 'node:https'
@@ -17,6 +17,15 @@ export interface NpmRelease {
   publishedAt: string
 }
 
+/** 最新版 + 可锁定的安装版本：安装锁定后者，pnpm 才不会回退到旧版本。 */
+export interface NpmReleaseWithInstallable extends NpmRelease {
+  /** 已过发布冷却期的最高稳定版；时间表缺失或没有满足项时为 null（调用方退回不锁定版本）。 */
+  installable: NpmRelease | null
+}
+
+/** pnpm profile 默认 minimumReleaseAge=1440 分钟；+30 分钟缓冲与客户端 release-age 判定同一套规则。 */
+export const MIN_RELEASE_AGE_MS = 24 * 60 * 60 * 1000 + 30 * 60 * 1000
+
 /** 请求体包名数量上限：只为已安装插件按需查询，几十个足矣，封顶防滥用。 */
 export const MAX_RELEASE_AGE_PACKAGES = 50
 /** 单包查询超时（ms）：慢网络下失败即返回 null，不拖住整个响应。 */
@@ -27,9 +36,9 @@ export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org'
 
 /** 会话内缓存（源 + 包名 → 结果）：只存成功结果，一次网络抖动不会把判断永久粘住。
  *  必须带过期时间 —— 插件中心可能连续开着几小时，作者发了新版本后不能一直沿用旧结果；
- *  也必须把源算进键 —— 同一个包在官方源与镜像上的 latest / 发布时间不同，混用会算错门禁。 */
+ *  也必须把源算进键 —— 同一个包在官方源与镜像上的 latest / 发布时间不同，混用会算错冷却期。 */
 const CACHE_TTL_MS = 10 * 60 * 1000
-const releaseCache = new Map<string, { at: number; release: NpmRelease }>()
+const releaseCache = new Map<string, { at: number; release: NpmReleaseWithInstallable }>()
 
 /** 从完整 packument 取 dist-tags.latest 对应版本及其发布时间；缺任一字段返回 null。 */
 export function latestReleaseOf(packument: unknown): NpmRelease | null {
@@ -44,6 +53,35 @@ export function latestReleaseOf(packument: unknown): NpmRelease | null {
   return { version, publishedAt }
 }
 
+/**
+ * 已过发布冷却期的最高稳定版本：安装锁定它，pnpm 不会回退到旧版本。
+ * 只看纯 x.y.z（预发布版不参与，避免把用户带到不兼容预览版）；时间表缺失或无满足项返回 null。
+ */
+export function installableReleaseOf(packument: unknown, now = Date.now()): NpmRelease | null {
+  if (packument === null || typeof packument !== 'object') return null
+  const time = (packument as { time?: unknown }).time
+  if (time === null || typeof time !== 'object') return null
+  let best: NpmRelease | null = null
+  for (const [version, published] of Object.entries(time as Record<string, unknown>)) {
+    if (!/^\d+\.\d+\.\d+$/.test(version) || typeof published !== 'string') continue
+    const at = Date.parse(published)
+    if (Number.isNaN(at) || now - at < MIN_RELEASE_AGE_MS) continue
+    if (best === null || compareVersion(version, best.version) > 0) best = { version, publishedAt: published }
+  }
+  return best
+}
+
+/** 纯数字段版本比较（installableReleaseOf 只在 x.y.z 里用）。 */
+function compareVersion(a: string, b: string): number {
+  const pa = a.split('.')
+  const pb = b.split('.')
+  for (let i = 0; i < 3; i++) {
+    const d = Number.parseInt(pa[i] ?? '0', 10) - Number.parseInt(pb[i] ?? '0', 10)
+    if (d !== 0) return d
+  }
+  return 0
+}
+
 /** 请求体 → 去重后的合法包名列表；非数组 / 超量 / 含非法包名一律 null（拒绝非法输入）。 */
 export function parseReleaseAgeRequest(body: unknown): string[] | null {
   if (body === null || typeof body !== 'object') return null
@@ -81,7 +119,7 @@ function getJson(url: string, timeoutMs: number): Promise<string | null> {
   })
 }
 
-/** 拉取一个包的完整 packument 正文；配了代理时复用与安装/目录同一套代理口径（curl 子进程注入 proxy env）。 */
+/** 拉取一个包的完整 packument 正文；配了代理时复用与安装/目录同一套代理规则（curl 子进程注入 proxy env）。 */
 async function fetchPackument(url: string, proxy: string, timeoutMs: number): Promise<string | null> {
   if (proxy !== '') {
     const r = await fetchViaCurl(url, proxy, timeoutMs)
@@ -90,13 +128,13 @@ async function fetchPackument(url: string, proxy: string, timeoutMs: number): Pr
   return getJson(url, timeoutMs)
 }
 
-/** 查询一个包的最新版本与发布时间（成功结果按源缓存 10 分钟）；registry 为空回退官方源，失败返回 null。 */
+/** 查询一个包的最新版本、发布时间与可锁定的安装版本（成功结果按源缓存 10 分钟）；registry 为空回退官方源，失败返回 null。 */
 export async function lookupReleaseAge(
   packageName: string,
   registry: string,
   proxy: string,
   timeoutMs = RELEASE_AGE_TIMEOUT_MS,
-): Promise<NpmRelease | null> {
+): Promise<NpmReleaseWithInstallable | null> {
   const base = registry.replace(/\/+$/, '') || DEFAULT_NPM_REGISTRY
   const key = `${base}\n${packageName}`
   const cached = releaseCache.get(key)
@@ -105,7 +143,9 @@ export async function lookupReleaseAge(
   if (body === null) return null
   let parsed: unknown
   try { parsed = JSON.parse(body) } catch { return null }
-  const release = latestReleaseOf(parsed)
-  if (release !== null) releaseCache.set(key, { at: Date.now(), release })
+  const latest = latestReleaseOf(parsed)
+  if (latest === null) return null
+  const release: NpmReleaseWithInstallable = { ...latest, installable: installableReleaseOf(parsed) }
+  releaseCache.set(key, { at: Date.now(), release })
   return release
 }

package/src/server/services/probe.ts

@@ -51,7 +51,7 @@ export function curlRevokeFlagUnsupported(code: number | null, stderr: string):
   return code === 2 && /ssl-revoke-best-effort/i.test(stderr) && /unknown|unrecognized/i.test(stderr)
 }
 
-/** 彻底关闭证书吊销检查的兜底参数（curl ≥ 7.19），比降级参数覆盖更老的 Windows curl。 */
+/** 彻底关闭证书吊销检查的保底参数（curl ≥ 7.19），比降级参数覆盖更老的 Windows curl。 */
 const NO_REVOKE_ARG = '--ssl-no-revoke'
 
 /** stderr 是否指向 Schannel 取不到证书吊销信息（据此归因为环境 TLS 问题，而非网络不通）。 */
@@ -59,7 +59,7 @@ export function tlsRevocationBlocked(stderr: string): boolean {
   return /CRYPT_E_NO_REVOCATION_CHECK|CRYPT_E_REVOCATION_OFFLINE|0x80092012/i.test(stderr)
 }
 
-/** 探测/安装同一套代理口径：curl 与 git 子进程都读 HTTP(S)_PROXY 环境变量。 */
+/** 探测/安装同一套代理规则：curl 与 git 子进程都读 HTTP(S)_PROXY 环境变量。 */
 function proxyEnv(proxy: string): NodeJS.ProcessEnv {
   if (proxy === '') return { ...process.env }
   return {
@@ -156,12 +156,12 @@ function runCurl(args: string[], env: NodeJS.ProcessEnv, timeoutMs: number): Pro
     child.stderr.on('data', (c: Buffer) => { stderr += c.toString() })
     child.on('error', () => finish(null))
     child.on('close', (code) => finish(code))
-    // 超时兜底：curl --max-time 到点自行退出，此处再设一个进程级超时防止悬挂
+    // 超时保护：curl --max-time 到点自行退出，此处再设一个进程级超时防止悬挂
     const timer = setTimeout(() => { child.kill(); finish(null) }, timeoutMs + 1000)
   })
 }
 
-/** 带 TLS 兜底的 curl 调用：先按平台参数跑（Windows 带吊销检查降级），
+/** 带 TLS 重试的 curl 调用：先按平台参数跑（Windows 带吊销检查降级），
  *  若本机 curl 不认这个参数（curl < 7.70）则去掉参数重跑一次，保证老版本不因此直接失败；
  *  降级后仍被吊销检查拦死（CRYPT_E_NO_REVOCATION_CHECK）时，再用 --ssl-no-revoke
  *  彻底关掉吊销检查跑一次 —— 该参数 curl ≥ 7.19 即存在，覆盖面比降级参数更广，
@@ -175,7 +175,7 @@ async function curlWithTlsFallback(args: string[], env: NodeJS.ProcessEnv, timeo
   }
   if (tlsArgs.length > 0 && tlsRevocationBlocked(run.stderr)) {
     const retry = await runCurl([NO_REVOKE_ARG, ...args], env, timeoutMs)
-    // 只在兜底本身跑起来（非「不认识该参数」）时采用其结果，否则保留原始失败线索
+    // 只在重试本身跑起来（非「不认识该参数」）时采用其结果，否则保留原始失败线索
     if (retry.code !== null && !curlRevokeFlagUnsupported(retry.code, retry.stderr)) run = retry
   }
   return run
@@ -183,7 +183,7 @@ async function curlWithTlsFallback(args: string[], env: NodeJS.ProcessEnv, timeo
 
 /**
  * curl 子进程探测：spawn curl -s -w '%{http_code}' 并注入代理 env。
- * curl 读 HTTP_PROXY/HTTPS_PROXY 是原生行为，与 pnpm/git 安装通道同一套代理口径；
+ * curl 读 HTTP_PROXY/HTTPS_PROXY 是原生行为，与 pnpm/git 安装通道同一套代理规则；
  * 失败（curl 不存在 / 连接失败 / 超时）都归为不可达，全程不抛错。
  * 证书吊销检查受阻（Windows Schannel）另记 reason，供诊断给出对症提示。
  */
@@ -240,7 +240,7 @@ export function gitLsRemote(url: string, proxy: string, timeoutMs: number): Prom
     const child = spawn('git', ['ls-remote', '--exit-code', url, 'HEAD'], { env })
     let out = ''
     child.stdout.on('data', (c: Buffer) => { out += c.toString() })
-    // git 的报错不透传给终端：结果以退出码 + HEAD ref 是否返回为准
+    // git 的报错不原样传递给终端：结果以退出码 + HEAD ref 是否返回为准
     child.stderr.on('data', () => {})
     let done = false
     const finish = (r: ProbeResult) => {
@@ -255,7 +255,7 @@ export function gitLsRemote(url: string, proxy: string, timeoutMs: number): Prom
       // status 复用为 git 退出码（0 = 克隆握手成功）；客户端 git 行不把它显示成 HTTP 码
       finish({ ok, ms: Date.now() - started, status: code })
     })
-    // 超时兜底：与 curlProbe 同口径，防止 git 挂起
+    // 超时保护：与 curlProbe 同一套规则，防止 git 挂起
     const timer = setTimeout(() => { child.kill(); finish(probeFail()) }, timeoutMs + 1000)
   })
 }
@@ -263,7 +263,7 @@ export function gitLsRemote(url: string, proxy: string, timeoutMs: number): Prom
 /**
  * 请求一个 URL 并返回重定向后的最终地址（curl -I -L -w %{url_effective}）。
  * 供 GitHub 仓库改名解析使用：对已改名仓库 GitHub 回 301，跟随跳转后的最终地址
- * 即规范地址。与其它 GitHub 访问同口径 —— curl 子进程注入代理 env（Node 内置
+ * 即规范地址。与其它 GitHub 访问同一套规则 —— curl 子进程注入代理 env（Node 内置
  * http(s) 读不到系统代理，直连在部分网络下不可达）。
  * 未发生跳转（200/404）、网络失败或 curl 不可用都返回 null，调用方保留原始地址。
  */
@@ -279,11 +279,11 @@ export async function finalUrl(url: string, proxy: string, timeoutMs: number): P
 }
 
 /**
- * curl 子进程抓取响应体（与 probeUrl 同一套代理 env 注入与 TLS 参数兜底）。
+ * curl 子进程抓取响应体（与 probeUrl 同一套代理 env 注入与 TLS 参数重试）。
  * 供服务端 /catalog 代理路由使用：目录/统计数据经此拉到服务端再转给浏览器，
- * 使「目录数据请求走设置里的代理」与 npm / git 安装通道口径一致。
+ * 使「目录数据请求走设置里的代理」与 npm / git 安装通道规则一致。
  * 失败（curl 不存在 / 连接失败 / 超时 / 非零退出）时 ok=false，全程不抛错；
- * reason 区分「证书吊销受阻」这类环境 TLS 问题，供调用方决定兜底策略。
+ * reason 区分「证书吊销受阻」这类环境 TLS 问题，供调用方决定备用策略。
  */
 export function fetchViaCurl(
   url: string, proxy: string, timeoutMs: number,

package/src/server/services/profile/installed-versions.ts

@@ -79,7 +79,7 @@ export function recordInstalledVersion(profile: string, repo: string, version: s
 export function recordResolvedNpmPackage(profile: string, repo: string, npmPackage: string): void {
   const table = readInstalledVersions(profile)
   const key = repo.toLowerCase()
-  // 显式写全字段：这一步发生在安装开始时，版本还不知道 —— 但落盘记录必须是完整形状，
+  // 显式写全字段：这一步发生在安装开始时，版本还不知道 —— 但写入磁盘记录必须是完整形状，
   // 否则只带 npmPackage 的残缺记录会在客户端版本比较时崩掉整块界面
   table[key] = {
     version: table[key]?.version ?? '',
@@ -101,7 +101,7 @@ function writeVersions(profile: string, table: InstalledVersionTable): void {
   const file = versionsFilePath(profile)
   mkdirSync(dirname(file), { recursive: true })
   // 先写临时文件再原子替换：直接覆盖时进程被杀/磁盘满会留下截断的 JSON，
-  // 下次读取整份账本都会失效（更新检测静默停摆），而用户看不到任何报错
+  // 下次读取整份账本都会失效（更新检测随之失效），而用户看不到任何报错
   const tmp = `${file}.tmp`
   writeFileSync(tmp, JSON.stringify(table, null, 2) + '\n', 'utf8')
   renameSync(tmp, file)

package/src/server/services/profile/profile.ts

@@ -77,7 +77,7 @@ export function githubTarget(repo: string, ref?: string | null): string | null {
  * 非命令输入原样返回。兼容「直接粘贴完整命令」（防用户输错）：--profile 必填且只有长选项
  * （官方 CLI 无 -p 简写，省略即报错），支持 `--profile=<name>` 等号形式，命令大小写不敏感。
  * update = 更新已安装目标到最新；remove 不在此列（卸载走 /uninstall 路由，按已装包名直卸）。
- * 与客户端 CustomInstallView 口径一致。
+ * 与客户端 CustomInstallView 规则一致。
  */
 const DSH_PLUGIN_CMD_RE = /^dsh\s+plugin\s+--profile(?:\s+|=)\S+\s+(add|update)\s+(.+)$/i
 
@@ -90,7 +90,7 @@ export function installTargetOf(value: string): string {
 /**
  * npm 全局安装命令（官方 README 的 `npm install -g <pkgs>`，如 dsh-tui 的安装命令）——
  * 提取 -g 之后的包列表。支持 `npm install|i` 与 `-g|--global`；任一包名非法（或格式
- * 不匹配）返回 null，由调用方按「不支持的目标」处理。与客户端 CustomInstallView 同口径。
+ * 不匹配）返回 null，由调用方按「不支持的目标」处理。与客户端 CustomInstallView 同一套规则。
  */
 const NPM_GLOBAL_CMD_RE = /^npm\s+(?:install|i)\s+(?:-g|--global)\s+(.+)$/i