dsh-plugin 2.2.3 → 2.2.5

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

@@ -18,7 +18,7 @@ import { backfillOperationLog, createOperationLogTap, hasSubstantiveOutput, oper
 import { cleanLine, estimateProgress } from '../profile/progress.js';
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.js';
 import { addPendingRestart, clearPendingRestart } from '../profile/pending-restart.js';
-import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.js';
+import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory, validPackageName } from '../profile/profile.js';
 import { appendLog } from '../log.js';
 import { commandOnPath, gitMissingDetail } from './preflight.js';
 import { isTransportFailure, registryHost } from './registry-fallback.js';
@@ -200,14 +200,17 @@ export function desktopCliBootstrap(entry) {
 }
 /**
  * 传给 CLI 的安装目标：钉住版本优先（Hub 自我更新提示的是已过供应链门禁的版本），
- * 其次更新走 `@latest`，git 源与全局 npm 安装保持原样。
+ * 其次 npm 的 add/update 都显式 `@latest`；git 源、全局安装、已带版本/tag 的 spec 保持原样。
  */
 export function npmInstallTargetOf(target, opts) {
     if (opts.global || githubRepoOf(target) !== null)
         return target;
     if (opts.pinned !== undefined && opts.pinned !== '')
         return opts.pinned;
-    return opts.update ? `${target}@latest` : target;
+    // 裸包名才补 @latest：pnpm 对已存在的精确 spec 是幂等的，不显式要求就会留用旧版本
+    if (!(opts.update || opts.add) || !validPackageName(target))
+        return target;
+    return `${target}@latest`;
 }
 function stopChild(child) {
     if (process.platform === 'win32' && child.pid !== undefined) {
@@ -372,15 +375,13 @@ function spawnMutation(options) {
         && process.versions.electron !== undefined) {
         pushLine(task, '[desktop-cli-fallback] running inside Electron but no desktop CLI bootstrap was found — falling back to dsh on PATH (a desktop-managed profile will be rejected)');
     }
-    // 更新已安装的 npm 包：显式指定 @latest。pnpm add <pkg>（无版本）对已存在依赖
-    // （尤其精确 spec 如 "1.3.0"）是幂等的 —— 输出 "Already up to date" 且不改 package.json，
-    // 导致「更新成功」但实际仍停留在旧版本；git 地址与全局安装不受此影响。
-    // update 动作实际执行 `add <target>@latest`（pnpm 对已存在依赖带显式版本即原位覆盖升级），
-    // CLI 动词仍透传 add —— 不执行官方 update 动词，避免与既有覆盖重装机制分叉。
+    // 安装/更新 npm 包都显式 @latest：pnpm add <pkg>（无版本）对已存在的精确 spec 是幂等的，
+    // 会原样留用旧版本（更新不生效，普通安装也可能装回不支持当前宿主的旧包）。
+    // update 动作同样执行 `add <target>@latest`，CLI 动词透传 add，不与官方 update 动词分叉。
     const isUpdate = action === 'update' || updateNpm === true;
     const cliAction = action === 'update' ? 'add' : action;
     // 钉住版本优先于 @latest：提示的是「已过门禁」的版本，装 latest 会被 pnpm 拒绝
-    const npmUpdateTarget = npmInstallTargetOf(target, { update: isUpdate, global: isGlobalNpm, pinned: installSpec });
+    const npmUpdateTarget = npmInstallTargetOf(target, { update: isUpdate, global: isGlobalNpm, pinned: installSpec, add: cliAction === 'add' });
     const args = isGlobalNpm
         ? ['install', '-g', ...(globalNpm ?? [])]
         : [...invocation.prefixArgs, 'plugin', '--profile', profile, cliAction, npmUpdateTarget];

package/lib/types/services/install/task-queue.d.ts

@@ -40,12 +40,13 @@ export declare function cancelTask(id: number): boolean;
 export declare function desktopCliBootstrap(entry: string): string | null;
 /**
  * 传给 CLI 的安装目标：钉住版本优先（Hub 自我更新提示的是已过供应链门禁的版本），
- * 其次更新走 `@latest`，git 源与全局 npm 安装保持原样。
+ * 其次 npm 的 add/update 都显式 `@latest`；git 源、全局安装、已带版本/tag 的 spec 保持原样。
  */
 export declare function npmInstallTargetOf(target: string, opts: {
     update: boolean;
     global: boolean;
     pinned?: string;
+    add?: boolean;
 }): string;
 /**
  * 插件变更入队并返回其任务。任务严格串行：队列 worker 只在上一个结束后才启动下一个。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 10000+ human-curated community plugins without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：10000+ 人工精选社区插件，每日更新。",
   "type": "module",
   "main": "lib/index.js",

package/src/client/components/catalog/CatalogList.tsx

@@ -13,7 +13,7 @@ import { siteUrl } from '../../logic/urls.ts'
 import { useIncrementalList } from '../../hooks/useIncrementalList.ts'
 import { PluginCard } from './PluginCard.tsx'
 
-export function CatalogList({ plugins, failed, visible, total, t, langPath, reload, forceReload, category, copied, installedName, installedVersion, hasUpdate, langKey, onInstall, onUninstall, hasProxy, onOpenDiagnostics }: {
+export function CatalogList({ plugins, failed, visible, total, t, langPath, reload, forceReload, category, copied, installedName, installedVersion, hasUpdate, updatePendingUntil, langKey, onInstall, onUninstall, hasProxy, onOpenDiagnostics }: {
   plugins: HubPlugin[] | null
   failed: boolean
   visible: HubPlugin[]
@@ -28,6 +28,8 @@ export function CatalogList({ plugins, failed, visible, total, t, langPath, relo
   installedName: (p: HubPlugin) => string | null
   installedVersion: (p: HubPlugin) => string | null
   hasUpdate: (p: HubPlugin) => boolean
+  /** 更新被供应链门禁暂缓时的可重试时刻（毫秒）；无则 null */
+  updatePendingUntil: (p: HubPlugin) => number | null
   langKey: LocaleId
   onInstall: (p: HubPlugin, opts?: { update?: boolean }) => void
   onUninstall: (p: HubPlugin) => void
@@ -72,6 +74,7 @@ export function CatalogList({ plugins, failed, visible, total, t, langPath, relo
         installedName,
         installedVersion,
         hasUpdate,
+        updatePendingUntil,
         t,
         langKey,
         langPath,

package/src/client/components/catalog/PluginCard.tsx

@@ -11,16 +11,18 @@ import styles from '../../styles/List.module.css'
 import type { HubPlugin, LocaleId, Translate } from '../../types.ts'
 import { CATEGORY_LABELS, categoryLabel } from '../../logic/constants.ts'
 import { pluginDetailUrl } from '../../logic/urls.ts'
-import { fmtStars, relTime } from '../../logic/format.ts'
+import { fmtStars, clockTime, relTime } from '../../logic/format.ts'
 
-export function PluginCard({ plugin: p, copied, installedName, installedVersion, hasUpdate, t, langKey, langPath, onInstall, onUninstall }: {
+export function PluginCard({ plugin: p, copied, installedName, installedVersion, hasUpdate, updatePendingUntil, t, langKey, langPath, onInstall, onUninstall }: {
   plugin: HubPlugin
   copied: string | null
   installedName: (p: HubPlugin) => string | null
   /** 已安装版本号（安装时从目录信号记录；无 release 的仓库为空，无版本号可展示） */
   installedVersion: (p: HubPlugin) => string | null
-  /** 已安装且目录有更新（有版本比版本、无版本比仓库更新时间） */
+  /** 已安装且目录有更新（有版本比版本、无版本比仓库更新时间）；门禁复核未就绪时为 false */
   hasUpdate: (p: HubPlugin) => boolean
+  /** 更新被供应链门禁暂缓时的可重试时刻（毫秒）；无则 null */
+  updatePendingUntil: (p: HubPlugin) => number | null
   t: Translate
   langKey: LocaleId
   langPath: string
@@ -33,6 +35,8 @@ export function PluginCard({ plugin: p, copied, installedName, installedVersion,
   const pkg = installedName(p)
   const isInstalled = pkg !== null
   const update = hasUpdate(p)
+  // 门禁暂缓：更新确实存在但现在装不上，给确切时刻而不是让徽标静默消失
+  const pendingUntil = isInstalled && !update ? updatePendingUntil(p) : null
   // 版本号展示：已安装 → 当前已装版本（最能反映用户状态）；未安装 → 目录最新版本
   const versionShown = isInstalled ? installedVersion(p) : p.version
 
@@ -44,6 +48,9 @@ export function PluginCard({ plugin: p, copied, installedName, installedVersion,
         versionShown ? h('span', { className: styles.versionBadge, title: t('version') }, versionShown) : null,
         // 已安装且有更新：醒目提示（有 release 比版本号、无 release 比仓库最近更新时间）
         update ? h('span', { className: styles.updateBadge, title: t('updateAvailableHint') }, t('updateAvailable')) : null,
+        pendingUntil !== null
+          ? h('span', { className: styles.updateBadge, title: t('updatePendingHint') }, t('updatePending', { time: clockTime(pendingUntil) }))
+          : null,
         p.category ? h('span', { className: styles.categoryBadge }, categoryLabel(CATEGORY_LABELS, p.category, langKey)) : null,
         p.compatibility?.status === 'verified'
           ? h('span', { className: styles.verified }, t('verified'))

package/src/client/components/modals/InstalledDetailModal.tsx

@@ -14,7 +14,7 @@ import type { LocaleId, Translate } from '../../types.ts'
 import type { InstalledItem } from '../../logic/installed.ts'
 import { CATEGORY_LABELS, categoryLabel } from '../../logic/constants.ts'
 import { pluginDetailUrl } from '../../logic/urls.ts'
-import { fmtStars } from '../../logic/format.ts'
+import { clockTime, fmtStars } from '../../logic/format.ts'
 import { CloseIcon, CopyIcon, FolderIcon, LinkIcon } from '../ui/icons.tsx'
 
 /** ISO 安装时间 → 本地可读；非法值返回 null（行内不显示）。 */
@@ -69,7 +69,10 @@ export function InstalledDetailModal({ item, t, lang, langPath, onClose, onUpdat
             item.installedVersion && item.catalogVersion
               ? t('versionUpHint', { from: item.installedVersion, to: item.catalogVersion })
               : t('updateAvailableHint'))
-          : null,
+          : item.pendingUntil != null
+            // 门禁暂缓：给确切可重试时刻，而不是让「有更新」静默消失
+            ? h('div', { className: styles.detailUpdateHint }, t('updatePending', { time: clockTime(item.pendingUntil) }))
+            : null,
         // 详情信息网格：分类 / 状态 / 版本 / 收录入口 / 包名 / 统计 / 安装路径 / 安装时间 / 最后更新
         h('div', { className: styles.detailGrid },
           p?.category

package/src/client/components/views/InstalledView.tsx

@@ -17,6 +17,7 @@ import styles from '../../styles/InstalledView.module.css'
 import type { LocaleId, Translate } from '../../types.ts'
 import type { InstalledItem } from '../../logic/installed.ts'
 import { CATEGORY_LABELS, categoryLabel } from '../../logic/constants.ts'
+import { clockTime } from '../../logic/format.ts'
 import { SortArrowIcon } from '../ui/icons.tsx'
 
 const INSTALLED_SORTS = ['sortName', 'sortInstalledAt', 'sortStars', 'sortForks'] as const
@@ -108,7 +109,10 @@ function InstalledRow({ item, t, langKey, canReveal, revealLabel, pendingRestart
           : null,
         item.hasUpdate
           ? h('span', { className: styles.updateBadge, title: t('updateAvailableHint') }, t('updateAvailable'))
-          : null,
+          : item.pendingUntil != null
+            // 门禁暂缓：更新存在但还装不上，给确切时刻，避免看起来「已是最新」
+            ? h('span', { className: styles.updateBadge, title: t('updatePendingHint') }, t('updatePending', { time: clockTime(item.pendingUntil) }))
+            : null,
       ),
       // 来源标签列（行尾、操作按钮前，右对齐固定）：目录插件 →「插件市场」（品牌色），
       // 命令行安装 →「手动安装」（琥珀色）；两词 4 字等宽，所有条目标签同列对齐

package/src/client/components/views/MarketView.tsx

@@ -59,6 +59,7 @@ export function MarketView({ catalog, t, langPath, langKey, copied, resultText,
       installedName: catalog.installedName,
       installedVersion: catalog.installedVersion,
       hasUpdate: catalog.hasUpdate,
+      updatePendingUntil: catalog.updatePendingUntil,
       langKey,
       onInstall,
       onUninstall,

package/src/client/hooks/useCatalog.ts

@@ -16,7 +16,7 @@ import type { SortKey } from '../logic/constants.ts'
 import { fetchCatalog, fetchStats } from '../data/catalog.ts'
 import { fetchHubAbout, fetchHubUpdate } from '../data/hub.ts'
 import { fetchInstalled, fetchNpmReleaseAge, type NpmReleaseInfo } from '../data/host.ts'
-import { isReleaseTooFresh, isUpdateOffered, pickHubUpdate } from '../logic/release-age.ts'
+import { isReleaseTooFresh, pickHubUpdate, updateDecision } from '../logic/release-age.ts'
 import {
   hasUpdateOf, installedItemsOf, installedNameOf, installedVersionOf, npmPackageOf,
 } from '../logic/installed.ts'
@@ -248,16 +248,24 @@ export function useCatalog(lang: LocaleId) {
    *  - npm 上最新版并不高于已装版本 —— 更新走的是 `pkg@latest`，此时无论目录标到哪个 tag，
    *    都不可能装上（作者可能只打了 GitHub release 没发 npm），提示只会变成永远点不掉的循环。
    */
-  const updateBlocked = useMemo(() => {
-    const blocked = new Set<string>()
-    if (!releaseAgeReady) return blocked
+  const updateDecisions = useMemo(() => {
+    const map = new Map<string, { offered: boolean; pendingUntil: number | null }>()
+    if (!releaseAgeReady) return map
     const now = Date.now()
     for (const pkg of releaseAgeCandidates) {
-      if (!isUpdateOffered(releaseAge.releases[pkg] ?? null, installedByPackage.get(pkg) ?? null, now)) blocked.add(pkg)
+      map.set(pkg, updateDecision(releaseAge.releases[pkg] ?? null, installedByPackage.get(pkg) ?? null, now))
     }
-    return blocked
+    return map
   }, [releaseAgeReady, releaseAgeCandidates, releaseAge.releases, installedByPackage])
 
+  const updateBlocked = useMemo(() => {
+    const blocked = new Set<string>()
+    for (const [pkg, decision] of updateDecisions) {
+      if (!decision.offered) blocked.add(pkg)
+    }
+    return blocked
+  }, [updateDecisions])
+
   /**
    * 是否有更新：仅对已安装插件有意义。
    * 双信号判定——有 release 版本的比版本；无版本（repo 不打 tag）的比仓库最近更新时间
@@ -267,18 +275,33 @@ export function useCatalog(lang: LocaleId) {
   const hasUpdate = (p: HubPlugin): boolean => {
     if (!hasUpdateOf(p, installed, versions)) return false
     const pkg = npmPackageOf(p, versions)
-    return pkg === null || !updateBlocked.has(pkg)
+    if (pkg === null) return true
+    // 复核没回来时先不亮：否则会出现「先亮有更新、几秒后又撤掉」
+    return releaseAgeReady && !updateBlocked.has(pkg)
+  }
+
+  /** 更新被门禁暂缓时的可重试时刻（毫秒）；未安装/无更新/非门禁原因 → null。 */
+  const updatePendingUntil = (p: HubPlugin): number | null => {
+    if (!hasUpdateOf(p, installed, versions)) return null
+    const pkg = npmPackageOf(p, versions)
+    if (pkg === null) return null
+    return updateDecisions.get(pkg)?.pendingUntil ?? null
   }
 
-  /** 已安装项统一列表（目录元数据 + 运行时信息合并）：被拦下的去掉更新标记，驱动「已安装」tab。 */
+  /** 已安装项统一列表（目录元数据 + 运行时信息合并）：校验未就绪/被拦下的去掉更新标记、
+   *  门禁暂缓的带上可重试时刻，驱动「已安装」tab。 */
   const installedItems = useMemo<InstalledItem[]>(() => {
-    if (updateBlocked.size === 0) return rawInstalledItems
     return rawInstalledItems.map((item) => {
       if (!item.hasUpdate || !item.plugin) return item
       const pkg = npmPackageOf(item.plugin, versions)
-      return pkg !== null && updateBlocked.has(pkg) ? { ...item, hasUpdate: false } : item
+      if (pkg === null) return item
+      if (!releaseAgeReady) return { ...item, hasUpdate: false }
+      const decision = updateDecisions.get(pkg)
+      return decision === undefined || decision.offered
+        ? item
+        : { ...item, hasUpdate: false, pendingUntil: decision.pendingUntil }
     })
-  }, [rawInstalledItems, updateBlocked, versions])
+  }, [rawInstalledItems, releaseAgeReady, updateDecisions, versions])
 
   /**
    * Hub 自身更新状态：Hub 就是当前运行的应用（始终已安装，无需 installedName 命中）。
@@ -353,6 +376,7 @@ export function useCatalog(lang: LocaleId) {
     installedName,
     installedVersion,
     hasUpdate,
+    updatePendingUntil,
     hubHasUpdate,
     hubUpdateState,
     hubUpdateTarget,

package/src/client/locales.ts

@@ -482,6 +482,10 @@ export const zh = {
   update: '可更新',
   updateAvailable: '有更新',
   updateAvailableHint: '检测到更新：有版本号的仓库比对版本号，无版本号的仓库比对仓库最近更新时间',
+  // 门禁暂缓：新版本发布未满 24 小时，此时安装会被 pnpm 静默回退（或直接拒绝），
+  // 给出确切可重试时刻，而不是让徽标静默消失、让用户以为已经是最新
+  updatePending: '暂缓到 {time} 后可更新',
+  updatePendingHint: '新版本发布未满 24 小时，pnpm 供应链门禁会拦下；到时间后再更新即可',
   hubUpdateHint: '检测到 DSH Plugin Hub 新版本，点击查看更新内容并更新',
   hubUpdateTitle: 'DSH Plugin Hub 有新版本',
   hubUpdateDesc: 'v{version} 已发布，点击下方按钮即可更新，完成后需重启宿主生效。',
@@ -977,6 +981,8 @@ export const en = {
   update: 'Update',
   updateAvailable: 'Update available',
   updateAvailableHint: 'An update was detected: repos with a release are compared by tag, repos without one by last push time',
+  updatePending: 'Update available after {time}',
+  updatePendingHint: 'The new release is less than 24 hours old, so the pnpm supply-chain hold rejects it until then',
   hubUpdateHint: 'A new DSH Plugin Hub version is available — click to view the changelog and update',
   hubUpdateTitle: 'A new DSH Plugin Hub version is available',
   hubUpdateDesc: 'v{version} has been released — click below to update, then restart the host to apply it.',

package/src/client/logic/format.ts

@@ -24,3 +24,13 @@ export function relTime(iso: string | undefined, t: Translate): string {
   if (days < 365) return t('monthsAgo', { months: Math.floor(days / 30) })
   return t('yearsAgo', { years: Math.floor(days / 365) })
 }
+
+/** 具体时刻：当天只给「时:分」，跨天再补「月/日」，用于「暂缓到何时可更新」。 */
+export function clockTime(ms: number): string {
+  const at = new Date(ms)
+  const now = new Date()
+  const hh = String(at.getHours()).padStart(2, '0')
+  const mm = String(at.getMinutes()).padStart(2, '0')
+  const sameDay = at.getFullYear() === now.getFullYear() && at.getMonth() === now.getMonth() && at.getDate() === now.getDate()
+  return sameDay ? `${hh}:${mm}` : `${at.getMonth() + 1}/${at.getDate()} ${hh}:${mm}`
+}

package/src/client/logic/installed.ts

@@ -42,6 +42,8 @@ export interface InstalledItem {
   catalogVersion: string | null
   /** 是否有可用更新（有版本比版本，无版本比仓库更新时间） */
   hasUpdate: boolean
+  /** 更新被供应链门禁暂缓时的可重试时刻（毫秒）；无更新/非门禁原因 → null */
+  pendingUntil: number | null
   /** 是否已加载进运行中 loader（官方 ctx.loader 对账）；false = 已安装但未挂载（装完未重启） */
   loaded: boolean
   /** 是否真正的 dsh 插件（包内声明 dsh 配置 / 在 profile bundles 清单）：
@@ -230,6 +232,7 @@ export function installedItemsOf(
       installedAt: rec?.installedAt ?? null,
       catalogVersion: p.version ?? null,
       hasUpdate: hasUpdateOf(p, installed, versions),
+      pendingUntil: null,
       loaded: loadedNames?.includes(name) ?? false,
       dshCapable: dshCapableNames?.includes(name) ?? false,
     })
@@ -254,6 +257,7 @@ export function installedItemsOf(
       catalogVersion: null,
       // 目录外没有目录信号可比，无法判断是否有更新
       hasUpdate: false,
+      pendingUntil: null,
       loaded: loadedNames?.includes(name) ?? false,
       dshCapable: dshCapableNames?.includes(name) ?? false,
     })

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

@@ -61,23 +61,44 @@ export function compareVersions(a: string | null | undefined, b: string | null |
   return 0
 }
 
+/** 「可更新」判定结果：是否提示，以及被供应链门禁拦下时的到期时刻。 */
+export interface UpdateDecision {
+  offered: boolean
+  /** 发布未满门槛 → 可重试时刻（毫秒）；非门禁原因（npm 上没有更高版本）→ null */
+  pendingUntil: number | null
+}
+
 /**
  * 是否值得提示「可更新」：npm 上最新可安装版本确实比已装版本新，且已过供应链门禁。
  *
  * 更新命令执行的是 `pkg@latest`，所以「目录里标的版本」不是最终能装上的版本：
  * 作者可能只打了 GitHub release 没发 npm —— 此时提示会变成永远点不掉的循环。
- * 任一信息缺失（查不到发布信息 / 没有已装版本记录）返回 true，交回调用方原有判定：
+ * 任一信息缺失（查不到发布信息 / 没有已装版本记录）返回 offered，交回调用方原有判定：
  * 宁可提示，也不因为一次查询失败把真实更新吃掉。
  */
+export function updateDecision(
+  release: { version: string; publishedAt: string } | null,
+  installedVersion: string | null,
+  now: number,
+): UpdateDecision {
+  if (release === null) return { offered: true, pendingUntil: null }
+  if (isReleaseTooFresh(release.publishedAt, now)) {
+    const ms = Date.parse(release.publishedAt)
+    return { offered: false, pendingUntil: Number.isNaN(ms) ? null : ms + MIN_RELEASE_AGE_MS }
+  }
+  if (installedVersion !== null && compareVersions(release.version, installedVersion) <= 0) {
+    return { offered: false, pendingUntil: null }
+  }
+  return { offered: true, pendingUntil: null }
+}
+
+/** 是否提示「可更新」（只要布尔结果的场景）。 */
 export function isUpdateOffered(
   release: { version: string; publishedAt: string } | null,
   installedVersion: string | null,
   now: number,
 ): boolean {
-  if (release === null) return true
-  if (isReleaseTooFresh(release.publishedAt, now)) return false
-  if (installedVersion !== null && compareVersions(release.version, installedVersion) <= 0) return false
-  return true
+  return updateDecision(release, installedVersion, now).offered
 }
 
 /**

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

@@ -20,7 +20,7 @@ import { cleanLine, estimateProgress } from '../profile/progress.ts'
 import type { LoaderHandle } from '../loader.ts'
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.ts'
 import { addPendingRestart, clearPendingRestart } from '../profile/pending-restart.ts'
-import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.ts'
+import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory, validPackageName } from '../profile/profile.ts'
 import { appendLog } from '../log.ts'
 import { commandOnPath, gitMissingDetail } from './preflight.ts'
 import { isTransportFailure, registryHost } from './registry-fallback.ts'
@@ -218,12 +218,14 @@ export function desktopCliBootstrap(entry: string): string | null {
 
 /**
  * 传给 CLI 的安装目标：钉住版本优先（Hub 自我更新提示的是已过供应链门禁的版本），
- * 其次更新走 `@latest`，git 源与全局 npm 安装保持原样。
+ * 其次 npm 的 add/update 都显式 `@latest`；git 源、全局安装、已带版本/tag 的 spec 保持原样。
  */
-export function npmInstallTargetOf(target: string, opts: { update: boolean; global: boolean; pinned?: string }): string {
+export function npmInstallTargetOf(target: string, opts: { update: boolean; global: boolean; pinned?: string; add?: boolean }): string {
   if (opts.global || githubRepoOf(target) !== null) return target
   if (opts.pinned !== undefined && opts.pinned !== '') return opts.pinned
-  return opts.update ? `${target}@latest` : target
+  // 裸包名才补 @latest：pnpm 对已存在的精确 spec 是幂等的，不显式要求就会留用旧版本
+  if (!(opts.update || opts.add) || !validPackageName(target)) return target
+  return `${target}@latest`
 }
 
 function stopChild(child: ReturnType<typeof spawn>): void {
@@ -432,15 +434,13 @@ function spawnMutation(options: {
     && (process.versions as Record<string, string | undefined>).electron !== undefined) {
     pushLine(task, '[desktop-cli-fallback] running inside Electron but no desktop CLI bootstrap was found — falling back to dsh on PATH (a desktop-managed profile will be rejected)')
   }
-  // 更新已安装的 npm 包：显式指定 @latest。pnpm add <pkg>（无版本）对已存在依赖
-  // （尤其精确 spec 如 "1.3.0"）是幂等的 —— 输出 "Already up to date" 且不改 package.json，
-  // 导致「更新成功」但实际仍停留在旧版本；git 地址与全局安装不受此影响。
-  // update 动作实际执行 `add <target>@latest`（pnpm 对已存在依赖带显式版本即原位覆盖升级），
-  // CLI 动词仍透传 add —— 不执行官方 update 动词，避免与既有覆盖重装机制分叉。
+  // 安装/更新 npm 包都显式 @latest：pnpm add <pkg>（无版本）对已存在的精确 spec 是幂等的，
+  // 会原样留用旧版本（更新不生效，普通安装也可能装回不支持当前宿主的旧包）。
+  // update 动作同样执行 `add <target>@latest`，CLI 动词透传 add，不与官方 update 动词分叉。
   const isUpdate = action === 'update' || updateNpm === true
   const cliAction = action === 'update' ? 'add' : action
   // 钉住版本优先于 @latest：提示的是「已过门禁」的版本，装 latest 会被 pnpm 拒绝
-  const npmUpdateTarget = npmInstallTargetOf(target, { update: isUpdate, global: isGlobalNpm, pinned: installSpec })
+  const npmUpdateTarget = npmInstallTargetOf(target, { update: isUpdate, global: isGlobalNpm, pinned: installSpec, add: cliAction === 'add' })
   const args = isGlobalNpm
     ? ['install', '-g', ...(globalNpm ?? [])]
     : [...invocation.prefixArgs, 'plugin', '--profile', profile, cliAction, npmUpdateTarget]