dsh-plugin 1.6.12 → 2.0.1

package/src/client/logic/constants.ts

@@ -3,8 +3,7 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Constants: site URLs, category metadata and sort keys. Pure data — no
- * side effects, no network — so every consumer shares one definition.
+ * 常量：站点地址、分类元数据与排序 key。纯数据、无副作用、无网络，供所有使用方共享同一份定义。
  */
 import type { LocaleId } from '../types.ts'
 

package/src/client/logic/ensure-plugin-css.ts

@@ -1,17 +1,13 @@
 /**
- * Self-heal missing plugin CSS tags.
+ * 自愈缺失的插件 CSS 标签。
  *
- * CSS injection is a one-shot side effect of the bundle factory (guarded by
- * "tag already present"). When the host restarts the page survives, but the
- * host HMR chain may remove the <style data-plugin> tags while the in-memory
- * module cache still holds the old factory — so the factory never re-runs and
- * the styles never come back until some interaction triggers a reload.
+ * CSS 注入是 bundle 工厂的一次性副作用（以「标签已存在」为守卫）。宿主重启后页面仍在，
+ * 但宿主 HMR 链可能移除 <style data-plugin> 标签，而内存模块缓存仍持有旧工厂，工厂不再
+ * 重跑，样式就一直缺失，直到某次交互触发刷新才恢复。
  *
- * The tsdown `dsh-css-modules-inline` build plugin registers every module's
- * { tagId, css } into the global list `__DSH_PLUGIN_CSS__` at factory time.
- * This helper compares that list against the live DOM and re-injects any
- * missing tags, turning the "click around to fix it" self-heal into an
- * automatic one on mount / view switch.
+ * tsdown 的 `dsh-css-modules-inline` 构建插件会在工厂执行时把每个模块的 { tagId, css }
+ * 登记进全局列表 `__DSH_PLUGIN_CSS__`。此工具随后比对列表与实时 DOM，补注入缺失的标签，
+ * 把「点一圈才自愈」变成挂载 / 切换视图时自动完成。
  */
 
 interface PluginCssEntry {
@@ -25,7 +21,7 @@ declare global {
   }
 }
 
-/** Re-inject any registered stylesheet that is missing from the DOM. Idempotent. */
+/** 补注入 DOM 中缺失的已登记样式表，幂等。 */
 export function ensurePluginCss(): void {
   if (typeof document === 'undefined') return
   const registry = window.__DSH_PLUGIN_CSS__

package/src/client/logic/failures.ts

@@ -3,13 +3,10 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Failure classification, issue-body summarization and persistent
- * install/remove notifications.
+ * 失败归类、Issue 正文摘要与持久化的安装/卸载通知。
  *
- * Every settled task is recorded two ways: the server-side system log
- * (hub.log) and a client-side localStorage record that feeds the
- * notification center — so a result is never lost even when the dialog
- * was dismissed or nobody was watching the progress strip.
+ * 每个结算后的任务都会双重留痕：服务端系统日志（hub.log）与馈送通知中心的客户端
+ * localStorage 记录 —— 即使弹窗被关闭、无人盯着进度条，结果也不会丢失。
  */
 export interface NotificationRecord {
   id: number
@@ -27,7 +24,7 @@ export interface NotificationRecord {
   version?: string
   /** 实际执行的安装/卸载命令（issue 预填时如实展示）；历史记录可能缺失 */
   command?: string
-  /** 尝试过的安装方式（npm registry 反查 + 实际执行命令，按先后顺序）：失败提 Issue 时贴给作者，便于反推正确的 npm 包名 */
+  /** 尝试过的安装方式（实际执行过的命令，按先后顺序）：失败提 Issue 时贴给作者，便于反推正确的 npm 包名 */
   attempts?: string[]
   /** 结束时间（epoch ms） */
   at: number
@@ -151,7 +148,7 @@ export function removeNotification(id: number): NotificationRecord[] {
   return next
 }
 
-export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'pluginMissingDep' | 'registryVersionStale' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'hostCliSpawn' | 'hubState' | 'timeout' | 'profileLock' | 'hub'
+export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'pluginMissingDep' | 'registryVersionStale' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'hostIncompatible' | 'network' | 'hostCliSpawn' | 'hubState' | 'timeout' | 'profileLock' | 'hub'
 
 /** 失败动作口径：标题、上报正文与提示文案按安装/更新/卸载取词，不写死「安装」。 */
 export type FailureAction = 'install' | 'update' | 'uninstall'
@@ -172,7 +169,7 @@ export function actionOfRecord(rec: { kind: NotificationRecord['kind']; action?:
   return rec.kind === 'uninstall' ? 'uninstall' : rec.kind === 'update' ? 'update' : 'install'
 }
 
-/** Match the pnpm error code, not a generic mention of checksum or integrity. */
+/** 只匹配 pnpm 的错误码，不匹配泛泛出现的 checksum / integrity 字样。 */
 function missingTarballIntegrity(message: string): boolean {
   return /\bERR_PNPM_MISSING_TARBALL_INTEGRITY\b/.test(message)
 }
@@ -187,9 +184,9 @@ export function releaseAgeRetryAfter(message: string): string | null {
 }
 
 /**
- * The same policy subtype selects recovery copy in live and saved failures.
- * minimumReleaseAge 只有在能算出可重试时刻时才走专属文案（给出确切的「何时可再试」），
- * 算不出时退回通用文案，避免出现「预计可重试时间：」后接空值的残缺句子。
+ * 同一策略子类型也用于选择实时/已保存失败的提示文案：minimumReleaseAge 只有在能算出
+ * 可重试时刻时才走专属文案（给出确切的「何时可再试」），算不出时退回通用文案，
+ * 避免出现「预计可重试时间：」后接空值的残缺句子。
  */
 export function pnpmPolicyHintOf(message: string): 'failPnpmTarballIntegrityHint' | 'failPnpmReleaseAgeHint' | 'failPnpmPolicyHint' {
   if (missingTarballIntegrity(message)) return 'failPnpmTarballIntegrityHint'
@@ -211,6 +208,9 @@ export function pnpmPolicyHintParams(message: string): Record<string, string> {
  * （只影响这个插件 → 才引导提 Issue）。各分支判定顺序有依赖，见函数内注释。
  */
 export function classifyFailure(message: string): FailureKind {
+  // 宿主版本门禁：插件声明的兼容范围不含当前 dsh 版本，宿主在安装前直接拒绝。
+  // 必须最先判 —— 这是宿主自己给的结论，不是 pnpm 的安装失败
+  if (/installation rejected:.*incompatible with dsh/i.test(message)) return 'hostIncompatible'
   // npm 自身崩溃（edgesOut）或服务端标记的本机 npm 版本过低。必须最先判，否则会被外层
   // ERR_PNPM_PREPARE_PACKAGE 吞成「插件打包问题」
   if (/\[npm-too-low\]|edgesOut/i.test(message)) return 'npmTooOld'
@@ -245,8 +245,9 @@ export function classifyFailure(message: string): FailureKind {
   // 构建脚本被 allowBuilds 拦截。必须在 network 之前判：日志尾部混重试残留的连接失败特征
   if (/ERR_PNPM_IGNORED_BUILDS|Ignored build scripts:|ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED/i.test(message)) return 'pnpmIgnoredBuild'
   // 网络/代理/源配置问题。必须在 prepare 之前判：git fetch 失败常被外层包成 "Command failed"
-  if (/\[network\]|ERR_PNPM_GIT_FETCH_FAILED|ETIMEDOUT|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH|getaddrinfo|Could not connect|Could not resolve host|Network unreachable|Failed to connect|socket hang up|CERT_HAS_EXPIRED|SSL certificate problem|\bTLS\b|\bSSL\b|fetch failed|failed to fetch|\bGET https?:\/\/\S+\.tgz\s+error \(\d+\)/i.test(message)) return 'network'
-  // 装后校验发现入口文件缺失（[packaging]）= git 分发缺构建产物
+  // tarball 下载失败的括号里可能是数字码（pnpm 自己的）或符号码（undici 的 UND_ERR_*），两种都要认
+  if (/\[network\]|ERR_PNPM_GIT_FETCH_FAILED|ETIMEDOUT|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH|UND_ERR_[A-Z0-9_]+|getaddrinfo|Could not connect|Could not resolve host|Network unreachable|Failed to connect|socket hang up|CERT_HAS_EXPIRED|SSL certificate problem|\bTLS\b|\bSSL\b|fetch failed|failed to fetch|\bGET https?:\/\/\S+\.tgz\s+error \([A-Za-z0-9_]+\)/i.test(message)) return 'network'
+  // 装后校验发现入口文件缺失（[packaging]）= 分发物缺构建产物
   if (/\[packaging\]|entry file missing/i.test(message)) return 'pluginPrepare'
   // registry 上不存在的依赖（404），profile 任何安装都会卡在这条。必须在 pluginPrepare 之前判
   // [registry-missing]（服务端官方源复核后注入）= 作者侧缺依赖，须先于 pnpmMissingDep（同样含 404 文本）
@@ -262,7 +263,7 @@ export function classifyFailure(message: string): FailureKind {
   // 安装器自身产生的状态类消息（未安装 / 不在此处卸载 / 已在队列中 / 已安装）：这几句由本服务的
   // 守卫发出，不是 CLI 输出、也不是插件问题，而是插件中心的已安装列表与实读快照不同步。
   // 单独归类，让前端给「刷新后重试」这类可行动提示，而不是当作未知失败引导去提 Issue。
-  // already installed 只认「整行就是它」的短形态（旧版本守卫留下的历史记录）；带「——」说明的
+  // already installed 只认「整行就是它」的短形态；带「——」说明的
   // 包名冲突另有处置，不能按状态不同步提示。
   if (/plugin is not installed|plugin cannot be uninstalled here|already queued:|^already installed: \S+$/im.test(message)) return 'hubState'
   // 安装器自己的超时标记（命令跑满上限被强杀）：既不是插件问题、也不是用户环境问题，而且很可能是
@@ -345,8 +346,8 @@ export function coreErrorCode(message: string): string | null {
 }
 
 /** 「包在 registry 不存在」失败的提示变体：服务端用官方源复核过（会注入 `[registry-mirror-lag]`）
- *  时，说明包在官方源上存在、是本机镜像源未同步 → 提示换源；否则沿用既有的「profile 残留依赖」
- *  提示（#73：指向从未发布包的残留条目，任何插件都装不进来）。 */
+ *  时，说明包在官方源上存在、是本机镜像源未同步 → 提示换源；否则按「profile 残留依赖」提示
+ *  （删掉 profile 里那条依赖即可）。 */
 export function registryMissingHintOf(message: string): 'failPnpmMissingDepHint' | 'failRegistryMirrorLagHint' {
   return /\[registry-mirror-lag\]/i.test(message) ? 'failRegistryMirrorLagHint' : 'failPnpmMissingDepHint'
 }
@@ -365,12 +366,12 @@ export function missingRegistryPackageOf(message: string): string | null {
 
 /**
  * 从网络类失败消息里提取「具体连不上的地址」，供弹窗精准提示（你的网络无法访问什么）。
- * 优先取服务端 [network] 预检消息括号里的探测地址（中文「（…）」/ 英文「(…)」），
+ * 优先取服务端 [network] 网络探测消息括号里的探测地址（中文「（…）」/ 英文「(…)」），
  * 否则取消息里出现的第一个 URL（git fetch 的仓库地址、registry 域名等）。
  * 提取不到返回 null —— 调用方据此跳过地址行。
  */
 export function unreachableTargetOf(message: string): string | null {
-  // [network] 预检消息：`无法连接到 GitHub（https://github.com/）` / `cannot reach the npm registry (https://registry.npmjs.org/)`
+  // [network] 网络探测消息：`无法连接到 GitHub（https://github.com/）` / `cannot reach the npm registry (https://registry.npmjs.org/)`
   const paren = message.match(/[（(](https?:\/\/[^\s'"`<>（)+]+)[)）]/)
   if (paren) return paren[1]
   // 其余网络失败（git fetch / npm 连接失败）：取第一个 URL，去掉行尾标点

package/src/client/logic/format.ts

@@ -3,7 +3,7 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Presentation formatters shared across the catalog list and the cards.
+ * 目录列表与卡片共用的展示格式化函数。
  */
 import type { Translate } from '../types.ts'
 

package/src/client/logic/install-command.ts

@@ -3,15 +3,13 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Install target/command helpers: decide the install channel (npm package
- * vs prebuilt GitHub release vs explicit-HTTPS GitHub), build the display
- * command and normalize a raw install spec back to its owner/repo identity.
+ * 安装目标/命令工具：为目录条目取 npm 包名、构造展示命令，并把原始安装 spec 归一化回 owner/repo 身份。
  */
 import type { HubPlugin } from '../types.ts'
 import { githubReleaseTarget } from '../../server/services/install/release-target.ts'
 
-/** Backend attempts are chronological; report the last executed command before a display fallback.
- * These prefixes are the task queue's recorded command shapes, never commands to execute here.
+/** 后端 attempts 按时间先后排列：取最后一次实际执行的命令，取不到再回退到展示用命令。
+ * 这里匹配的是任务队列记录的指令形态，不是要在此执行的命令。
  */
 export function executedCommandOf(command?: string, attempts?: string[]): string | undefined {
   if (attempts === undefined) return command
@@ -21,44 +19,25 @@ export function executedCommandOf(command?: string, attempts?: string[]): string
 }
 
 /**
- * 安装通道决策（用户无感知）：目录探测到 npm 包名 → 用 npm 包名安装
- * （走 npm registry tarball，更快、与 GitHub 网络无关）；其次用「同仓库」的权威
- * release 包直链（仓库 HEAD 往往是 monorepo 根、装不上，release .tgz 才是完整产物）；
- * 都没有 → git 直装。
- * 返回值 target 即传给后端 /install 的安装目标（npm 包名 / release URL / owner/repo）。
+ * 目录条目的安装目标（用户无感知）：目录条目必带 npm 包名，直接用该包名安装
+ * （走 npm registry tarball）。
+ * 返回值即传给后端 /install 的安装目标（npm 包名）。
  */
-export function installTargetOf(p: HubPlugin): { target: string; via: 'npm' | 'release' | 'github' } {
-  const pkg = (p.source?.npmPackage ?? '').trim()
-  const repo = (p.source?.repo ?? '').trim()
-  if (pkg && repo) return { target: pkg, via: 'npm' }
-  // 目录下发的权威命令若是「同仓库」的固定 release 直链，改走该预构建包；
-  // 跨仓 / 非法 release 目标不采信，退回 git 直装。
-  const release = githubReleaseTarget(p.install?.githubCommand ?? '')
-  if (release !== null && repo !== '' && release.repo.toLowerCase() === repo.toLowerCase()) {
-    return { target: release.target, via: 'release' }
-  }
-  return { target: repo, via: 'github' }
+export function installTargetOf(p: HubPlugin): string {
+  return (p.source?.npmPackage ?? '').trim()
 }
 
 /** 展示用安装命令（复制/弹窗）：目录下发的权威命令优先（CLI-only 插件如 dsh-tui
- *  需专属 profile（--profile dsh-tui），无法从 repo/npm 包名推断，必须用官方命令）；
- *  常规插件无目录命令时按通道回退生成：npm 显示包名，git 显示显式 HTTPS URL。 */
+ *  需专属 profile（--profile dsh-tui），无法从 npm 包名推断，必须用官方命令）；
+ *  常规插件无目录命令时用 npm 包名回退生成。 */
 export function installCommandOf(p: HubPlugin, withProfile = false): string {
-  const { target, via } = installTargetOf(p)
-  if (via === 'npm') {
-    const cmd = p.install?.command
-    if (cmd) return cmd
-  } else {
-    // release 与 git 通道共用目录下发的 githubCommand（git+ 显式 HTTPS 或 release 直链）
-    const cmd = p.install?.githubCommand
-    if (cmd) return cmd
-  }
+  const cmd = p.install?.command
+  if (cmd) return cmd
   const prefix = `dsh plugin${withProfile ? ' --profile web' : ''} add `
-  if (via === 'npm' || via === 'release') return `${prefix}${target}`
-  return `${prefix}git+https://github.com/${target}.git`
+  return `${prefix}${installTargetOf(p)}`
 }
 
-/** Normalize a task/install target to its owner/repo display identity. */
+/** 把任务/安装目标归一化为 owner/repo 展示身份。 */
 export function repoFromInstallTarget(value: string): string {
   const input = value.trim()
   // release 直链（预构建 .tgz）走同一条身份归一化：解析出所属仓库，已装态/更新信号才能

package/src/client/logic/installed.ts

@@ -3,13 +3,11 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Installed-plugin model (pure logic, zero React/UI dependencies).
+ * 已安装插件模型（纯逻辑，不依赖 React/UI）。
  *
- * Merges the local installed table (from the host's `/installed` route:
- * npm name → manifest spec) with the catalog projection into a single
- * `InstalledItem` view-model consumed by the Installed view. Also hosts the
- * install matching / update detection used by the market view, so both
- * views share one source of truth.
+ * 把宿主 `/installed` 路由下发的本地已装表（npm 包名 → manifest spec）与目录投影合并成
+ * 统一的 `InstalledItem` 视图模型，供「已安装」视图消费；同时承载市场视图用的安装匹配
+ * 与更新检测，让两个视图共享唯一数据源。
  */
 import type { HubPlugin } from '../types.ts'
 import { HUB_REPO } from './constants.ts'
@@ -56,7 +54,7 @@ function signalOf(repo: string | null, versions: Record<string, InstalledVersion
   return versions[repo.toLowerCase()] ?? null
 }
 
-/** 插件是否已安装：匹配 Git spec 中的 owner/repo，或 npm 通道安装的依赖包名；命中返回 npm 包名。 */
+/** 插件是否已安装：匹配 Git spec 中的 owner/repo，或 npm 安装的依赖包名；命中返回 npm 包名。 */
 export function installedNameOf(
   plugin: HubPlugin,
   installed: Record<string, string>,
@@ -68,8 +66,8 @@ export function installedNameOf(
   for (const [name, spec] of Object.entries(installed)) {
     if (repoFromInstallTarget(spec).toLowerCase() === needle) return name
   }
-  // npm 通道安装：profile 依赖 key 直接是 npm 包名。包名来源两处——目录数据（npmPackage），
-  // 或服务端 npm 优先反查持久化的映射（versions[repo].npmPackage，覆盖组织 scope 与 GitHub
+  // npm 安装：profile 依赖 key 直接是 npm 包名。包名来源两处——目录数据（npmPackage），
+  // 或服务端安装时持久化的映射（versions[repo].npmPackage，覆盖组织 scope 与 GitHub
   // 用户名不一致、目录未下发包名的场景）；命中任一并依赖 key 真实存在即视为已安装。
   // 只认 npm 安装的依赖（spec 无法解析出仓库身份）：git/本地安装的依赖身份由仓库匹配决定，
   // 包名同名不代表同仓库——否则「git 装 A 仓库」会被「npm 包名同名但仓库不同」的目录条目
@@ -91,6 +89,13 @@ export function installedVersionOf(plugin: HubPlugin, versions: Record<string, I
   return versions[repo.toLowerCase()]?.version ?? null
 }
 
+/** 该插件对应的 npm 包名（目录下发，或安装时持久化的映射）；无则 null。决定更新是否走 npm registry。 */
+export function npmPackageOf(plugin: HubPlugin, versions: Record<string, InstalledVersionSignal>): string | null {
+  const repo = plugin.source?.repo
+  const pkg = (plugin.source?.npmPackage || (repo ? versions[repo.toLowerCase()]?.npmPackage : undefined) || '').trim()
+  return pkg === '' ? null : pkg
+}
+
 /**
  * 是否有更新：仅对已安装插件有意义。
  * 双信号判定——有 release 版本的比版本；无版本（repo 不打 tag）的比仓库最近更新时间
@@ -174,7 +179,7 @@ function isHubSelf(name: string, spec: string): boolean {
   if (spec.startsWith('file:') || spec.startsWith('link:')) return true
   const repo = repoFromInstallTarget(spec)
   if (isRepoLike(repo) && repo.toLowerCase() === HUB_REPO.toLowerCase()) return true
-  // npm 通道覆盖重装 hub 自身后，file:/link: 本地链接会被替换成 registry 版本号/范围
+  // npm 覆盖重装 hub 自身后，file:/link: 本地链接会被替换成 registry 版本号/范围
   // （如 1.3.0、^1.3.0）——依赖 key `dsh-plugin` 在 npm 上唯一属于本插件（不存在第三方
   // 同名包），版本号形态与仓库身份同样视为 hub 自身：命令窗口「自己装自己」成功后，
   // 条目仍不进已安装列表（卸载接口对它的 400 拒绝是服务端最后一道防线）。

package/src/client/logic/normalize.ts

@@ -3,8 +3,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Normalizer: maps the online API's short-key payload (s/o/n/vr/c/t/f/d/r/v/u/a/sg/fk)
- * to HubPlugin so rendering only ever sees one shape.
+ * 归一化器：把在线 API 的短 key 载荷（s/o/n/vr/c/t/f/d/r/v/u/a/sg/fk）映射为
+ * HubPlugin，让渲染层只面对一种数据形态。
  */
 import type { HubPlugin } from '../types.ts'
 
@@ -30,7 +30,7 @@ export function normalize(raw: Record<string, unknown>): HubPlugin {
           : undefined,
       // 安装信息：wi 仅在 false 时下发（缺省视为 true 可一键安装）；
       // mi 仅在 true 时下发（人工干预：网页端替不了终端，只引导用户自己去终端装）；
-      // ic/igc = 目录下发的权威安装命令（npm/git 通道各一条，CLI-only 插件如 dsh-tui 必须用）
+      // ic/igc = 目录下发的权威安装命令（CLI-only 插件如 dsh-tui 必须用）
       install: raw.wi === false || raw.mi === true || typeof raw.ic === 'string' || typeof raw.igc === 'string'
         ? {
           webInstallable: raw.wi === false ? false : undefined,

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

@@ -0,0 +1,19 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 供应链门禁的时间判定（纯函数）：pnpm 会静默回退发布未满门槛的版本，
+ * 故发布太新的版本不该提示更新。Hub 自身更新与插件更新共用同一门槛。
+ */
+
+/** pnpm 供应链门禁：dsh profile 默认 minimumReleaseAge=1440（分钟）；+30 分钟缓冲抵消网络/CDN 边缘时间偏差。 */
+export const MIN_RELEASE_AGE_MS = 24 * 60 * 60 * 1000 + 30 * 60 * 1000
+
+/** 发布时间是否仍在门禁窗口内（太新 → 暂缓提示）；无值/解析不出返回 false（不拦真实更新）。 */
+export function isReleaseTooFresh(publishedAt: string | null | undefined, now: number): boolean {
+  if (typeof publishedAt !== 'string' || publishedAt === '') return false
+  const ms = Date.parse(publishedAt)
+  if (Number.isNaN(ms)) return false
+  return now - ms < MIN_RELEASE_AGE_MS
+}

package/src/client/logic/urls.ts

@@ -3,9 +3,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * URL builders: catalog detail pages, plugin site links and the pre-filled
- * GitHub issue URL used by the failure modal. Pure functions — the issue
- * URL stays within GitHub's 8192-byte request limit.
+ * URL 构造：目录详情页、插件官网链接，以及失败弹窗用的预填 GitHub Issue 链接。
+ * 均为纯函数，保证 issue URL 不超过 GitHub 8192 字节的请求上限。
  */
 import type { EnvInfo, HubPlugin, LocaleId } from '../types.ts'
 import { GITHUB_URL, HUB_REPO, PLUGIN_VERSION, SITE_URL } from './constants.ts'
@@ -62,6 +61,7 @@ function reasonTitleOf(kind: FailureKind, action: FailureAction): string {
     case 'fsUnavailable': return 'local file system unavailable on the user machine'
     case 'pnpmIgnoredBuild': return 'build scripts blocked by pnpm allowlist'
     case 'pluginPrepare': return 'plugin distribution incomplete'
+    case 'hostIncompatible': return 'plugin does not support the DSH version in use'
     case 'network': return 'network failure on the user side'
     case 'hostCliSpawn': return 'the DSH host could not be launched on the user machine'
     case 'hubState': return `stale ${word} state in the plugin hub`
@@ -79,21 +79,23 @@ function reasonTitleOf(kind: FailureKind, action: FailureAction): string {
  * 错误核心摘要（完整日志太长，塞进 URL 会被 GitHub 以「request URL too long」拒绝，
  * 故只收集重点）。错误弹窗、失败记录共用此逻辑。
  * env 取不到时为 null，链接照常生成、只是少环境段。
- * attempts（尝试过的安装方式，npm 反查 + 实际执行命令）：作者看到我们查过/试过的命令，
+ * attempts（尝试过的安装方式，实际执行过的命令）：作者看到我们试过的命令，
  * 组织 scope 与 GitHub 用户名不一致时也能直接指认正确的 npm 包名。
  */
 export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | null, command?: string, attempts?: string[], action: FailureAction = 'install'): string {
   // 原因判定：按失败类型归类，便于作者判断问题是否出在插件侧。
-  // [packaging]（预检/装后校验拦截）单独列：无论走 npm 还是 git 通道，都是分发物不完整
-  // （package.json 声明的文件在发布物里缺失），作者照此补齐即可。
+  // [packaging]（装后校验拦截）单独列：分发物不完整（package.json 声明的文件
+  // 在发布物里缺失），作者照此补齐即可。
   const kind = classifyFailure(message)
   const executed = executedCommandOf(command, attempts)
   // 动作词：标题与正文的「安装/更新/卸载」统一取自这里
   const zhWord = actionWordZh(action)
   // 标题 = 错误原因（非动作词），让 issue 列表一眼可分流
   const title = `[dsh-plugin.org | dsh-plugin-hub] ${reasonTitleOf(kind, action)}: ${repo}`
-  const reason = /\[packaging\]/i.test(message)
-    ? 'plugin distribution is incomplete — a file the package needs (its entry from main / exports, an entry a bundled patch mounts, or the patch declared by dsh.bundle.patch) is missing from the published package (github tarball or npm package); please commit build output or publish a complete package'
+  const reason = kind === 'hostIncompatible'
+    ? 'the plugin declares a dsh compatibility range that does not include the runtime in use, so the host rejects it before installing anything; please extend the supported dsh versions or publish a compatible release'
+    : /\[packaging\]/i.test(message)
+    ? 'plugin distribution is incomplete — a file the package needs (its entry from main / exports, an entry a bundled patch mounts, or the patch declared by dsh.bundle.patch) is missing from the published npm package; please publish a complete package'
       : /\[registry-missing\]/i.test(message)
         // 服务端用官方 registry 复核过：缺的包在官方源上也不存在，且不是用户 profile 的残留依赖
         ? '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'
@@ -131,17 +133,17 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
       `本错误信息由 [dsh-plugin-hub](${GITHUB_URL}) 插件市场的安装程序自动生成，随本次${zhWord}失败一并提交。`,
       `- 实际执行的${zhWord}命令：${executed ? `\`${executed}\`` : 'unknown (no executed command recorded)'}`,
       `- 执行结果：${zhWord}失败，未能${zhWord}该插件。`,
-      // 尝试过的通道（npm 反查 + 实际执行命令，按先后顺序）：作者据此指认正确的 npm 包名。
+      // 尝试过的安装方式（实际执行过的命令，按先后顺序）：作者据此指认正确的 npm 包名。
       // 不写「安装」：卸载失败也走这条正文。
       ...(attempts && attempts.length > 0
         ? ['', '## Attempted channels（已尝试的方式）', ...attempts.map((a) => `- ${a}`)]
         : []),
-      // [packaging] 场景：说明三种官方安装通道（npm 包 / git 直装 / 预构建 release .tgz），当前插件在对应通道下分发不完整
+      // [packaging] 场景：说明当前插件的 npm 分发物不完整
       ...(/\[packaging\]/i.test(message)
         ? [
           '',
           '## 安装方式说明',
-          'DSH 插件支持三种官方安装通道：`dsh plugin add <npm-package>`（npm 分发，需发布完整构建产物）、`dsh plugin add git+https://github.com/owner/repo.git`（Git 直装，仓库需提交构建产物），以及预构建 release 包 `dsh plugin add https://github.com/owner/repo/releases/download/<tag>/<asset>.tgz`（仓库不便提交构建产物时的推荐方式）。注意：pnpm ≥10 默认拦截依赖构建脚本，Git 直装不会执行包内 `prepare`，请勿依赖它生成产物。当前插件的分发物缺少它需要的文件（`main` / `exports` 声明的入口、补丁按本包名 mount 的入口，或 `dsh.bundle.patch` 声明的补丁），请提交构建产物、改用 release `.tgz` 直链，或发布完整的 npm 包。',
+          '当前插件的 npm 分发物缺少它需要的文件（`main` / `exports` 声明的入口、补丁按本包名 mount 的入口，或 `dsh.bundle.patch` 声明的补丁）。请发布包含完整构建产物的 npm 包后重试。',
         ]
         : []),
       '',
@@ -194,14 +196,14 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
 }
 
 /**
- * 插件中心自身仓库的预填 Issue 链接：用于「非插件侧」失败（无法识别的未知原因、
- * 以及 pnpm allowBuilds 拦截这类不再归到插件作者的情形）。正文带上目标插件与完整
+ * 插件中心自身仓库的预填 Issue 链接：用于「非插件侧」失败（无法识别的未知原因，
+ * 以及判定由插件中心自己产出、可能误报时的次要反馈入口）。正文带上目标插件与完整
  * 错误摘要，供插件中心维护者分诊 —— 不再把环境问题/插件中心自身问题误投给插件作者。
  */
 export type HubIssueVariant =
-  /** 缺省：安装器主动把失败送到插件中心分诊（未分类兜底 / allowBuilds 门禁） */
+  /** 缺省：安装器主动把失败送到插件中心分诊（未分类兜底） */
   | 'triage'
-  /** 从「插件打包问题」分支的次要入口提交：该判定由插件中心自己产出，用户怀疑是误报 */
+  /** 从判定由插件中心自己产出的分支（插件打包问题 / allowBuilds 拦截）的次要入口提交：用户怀疑是误报 */
   | 'misjudge'
 
 export function hubIssueUrl(
@@ -230,16 +232,17 @@ export function hubIssueUrl(
       `- Auto-classified cause: ${reasonTitleOf(kind, action)}`,
       `- Target plugin: \`${repo}\``,
       ...(code ? [`- Key error: \`${code}\``] : []),
-      // 为什么投递到这里而非插件仓库：只有确有证据是插件自身构建失败（pluginPrepare）才投插件仓库
+      // 为什么投递到这里而非插件仓库：只有确有证据是插件自身构建/分发失败（pluginPrepare、
+      // 或自动放行 allowBuilds 重试后仍失败的构建拦截）才投插件仓库
       ...(variant === 'misjudge'
-        // 这条入口的判据（[packaging] 预检/装后校验、prepare 摘要）是插件中心自己产出的，
-        // 不是 pnpm 原文 —— 一旦我们自己误报，用户就被送去作者仓库、我们永远收不到反馈。
+        // 这些分支的判据由插件中心自己产出、或掺了我们的动作（自动放行 allowBuilds）——
+        // 一旦我们自己误报，用户就被送去作者仓库、我们永远收不到反馈。
         // 正文写清它来自哪条分支、判据是谁给的，维护者才不会把它当成未分类兜底。
         ? [
-          '- Filed from: the plugin-prepare path (which 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 pre/post-install check, not by pnpm output.',
+          '- 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.',
         ]
-        : ['- Why filed here: the installer only routes a failure to the plugin repo when there is positive evidence the plugin build itself failed (pluginPrepare). This failure does not match that, so it is routed here for triage.']),
+        : ['- Why filed here: the installer only routes a failure to the plugin repo when the cause is demonstrably the plugin\'s own build/distribution (pluginPrepare, or build scripts pnpm blocks that even an auto-allow retry cannot get past). This failure does not match that, so it is routed here for triage.']),
       '',
       `## [DSH Plugin 插件市场](${SITE_URL}) · ${zhWord} Plugin 失败错误信息`,
       `本错误信息由 [dsh-plugin-hub](${GITHUB_URL}) 插件市场的安装程序自动生成，随本次${zhWord}失败一并提交。`,

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

@@ -2,11 +2,9 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Custom install view: a standalone top-level section for manually
- * installing npm packages or GitHub sources outside the catalog. The two
- * installer cards (npm / GitHub) stack one per line; each card = channel
- * label + example hint above the input + input row (input + install button)
- * + optional format-error note. Colors resolve through the --hub-* tokens.
+ * 自定义安装视图：独立一级板块，用于手动安装目录之外的 npm 包。安装卡片逐行堆叠：
+ * 渠道标签 + 输入框上方的示例提示 + 输入行（输入框 + 安装按钮）+ 可选的格式错误提示。
+ * 颜色经 --hub-* 变量解析。
  */
 
 .root {
@@ -84,31 +82,6 @@
   border-color: var(--hub-brand-border-soft);
 }
 
-/* 命令卡片标题旁的「一键插入更新命令」：右对齐小号描边按钮，弱化但可点，hover 提亮品牌色 */
-.installInsertBtn {
-  flex-shrink: 0;
-  margin-left: auto;
-  font-family: inherit;
-  font-size: 11px;
-  line-height: 16px;
-  font-weight: 500;
-  color: var(--hub-text-secondary);
-  background: transparent;
-  border: 1px solid var(--hub-border-2);
-  border-radius: 6px;
-  padding: 2px 9px;
-  cursor: pointer;
-  white-space: nowrap;
-  user-select: none;
-  transition: color 120ms ease, border-color 120ms ease, background 120ms ease;
-}
-
-.installInsertBtn:hover {
-  color: var(--hub-brand);
-  border-color: var(--hub-brand-border-soft);
-  background: var(--hub-brand-tint);
-}
-
 /* 文本框上方的示例：灰字小字，告诉用户该通道的推荐写法 */
 .installExample {
   font-size: 11px;

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

@@ -2,11 +2,9 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * System diagnostics list: every connectivity probe is one row — name,
- * target address, latency and a live status badge (200 OK / Unreachable /
- * Checking…). The list runs automatically when the page opens; each row is
- * a button — click to re-probe just that channel with a visible
- * running→result feedback loop. Colors resolve through the --hub-* tokens. */
+ * 系统诊断列表：每个连通性探测一行 —— 名称、目标地址、延迟与实时状态徽标
+ * （200 OK / 不可达 / 检测中…）。页面打开时自动跑一轮；每行都是按钮 ——
+ * 点击只重测该通道，形成「运行→结果」的可见反馈闭环。颜色经 --hub-* 变量解析。 */
 
 .panel {
   display: flex;

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

@@ -2,10 +2,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Button-style dropdown: the trigger reads as a compact toolbar button
- * (hairline border + subtle fill + current value + chevron), the panel is
- * a floating menu with hover fills and a brand-highlighted active option.
- * Colors resolve through the --hub-* design tokens. */
+ * 按钮式下拉框：触发器呈现为紧凑工具栏按钮（细边框 + 淡填充 + 当前值 + 箭头），
+ * 面板是浮层菜单，选项有 hover 填充、激活项品牌高亮。颜色经 --hub-* 设计变量解析。 */
 
 .dropdown {
   position: relative;

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

@@ -2,9 +2,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Plugin Hub section header: brand row, tagline, ad banner, search input,
- * filter toolbar (installed / not installed, failures entry) and category
- * tabs. Colors resolve through the --hub-* design tokens. */
+ * 插件中心板块头部：品牌行、副标题、广告条、搜索框、筛选工具栏
+ * （已安装/未安装、失败入口）与分类 tab。颜色经 --hub-* 设计变量解析。 */
 
 .root {
   height: 100%;
@@ -15,7 +14,7 @@
   color: var(--hub-text-primary);
 }
 
-/* —— header —— */
+/* —— 头部 —— */
 
 .header {
   display: flex;
@@ -241,7 +240,7 @@
   text-align: center;
 }
 
-/* —— result count —— */
+/* —— 筛选结果数 —— */
 
 /* 筛选结果数：弱化灰字信息「结果 N 条插件」，位于工具栏行最左侧 */
 .resultSeg {
@@ -324,7 +323,7 @@
   background: var(--hub-brand);
 }
 
-/* —— ad banner —— */
+/* —— 广告条 —— */
 
 /* 广告条：固定蓝紫渐变 + 白字，不随主题变量漂移，两种主题下都醒目。
    与 toast 相同思路：固定颜色保证可读性。 */
@@ -411,7 +410,7 @@
   border-color: var(--hub-brand);
 }
 
-/* —— category chips —— */
+/* —— 分类 chips —— */
 
 .tabs {
   display: flex;

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

@@ -2,13 +2,10 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Installed view: searchable, sortable list of installed plugins mixing
- * catalog plugins (full metadata) and custom installs (runtime info only,
- * amber custom badge). The toolbar holds a search box plus two segmented
- * radio-button groups (source filter + sort). Each row has three tidy
- * lines: title line (running-status dot + name + version/update badges +
- * fixed action buttons on the right), meta line (repo · category), and a
- * one-line description. Colors resolve through the --hub-* tokens. */
+ * 已安装视图：可搜索、可排序的已安装插件清单，混排目录插件（完整元数据）与自定义安装
+ * （仅运行时信息，琥珀色自定义徽标）。工具栏含搜索框与两组分段单选（来源筛选 + 排序）。
+ * 每行三行整洁内容：标题行（运行状态点 + 名称 + 版本/更新徽标 + 右侧固定操作按钮）、
+ * 元信息行（仓库 · 分类）与单行描述。颜色经 --hub-* 变量解析。 */
 
 .root {
   display: flex;