dsh-plugin 2.3.2 → 2.3.3

package/src/client/locales.ts

@@ -59,7 +59,7 @@ export const zh = {
   npmInstallPlaceholder: 'npm install <包名> 或直接输包名',
   npmInstallExample: '支持原生命令：npm install lodash、npm i lodash、pnpm add @scope/pkg',
   npmInstallExample2: '全局安装 CLI：npm install -g @scope/cli；或直接输入包名 lodash',
-  npmInstallInvalid: '请输入 npm 包名（如 lodash、@scope/pkg），或原生安装命令（如 npm install lodash、npm i lodash、pnpm add @scope/pkg、npm install -g @scope/cli）',
+  npmInstallInvalid: '请输入 npm 包名（如 lodash、@scope/pkg），或原生安装命令（如 npm install lodash、npm i lodash、pnpm add @scope/pkg、npm install -g @scope/cli）；不支持 GitHub 源码地址，请改用该插件的 npm 包名',
   installHelp: '帮助',
   helpModalTitle: '支持的命令格式',
   npmInstallHelp: 'lodash、@scope/pkg\t直接输入包名\nnpm install lodash\nnpm i lodash\npnpm add @scope/pkg\npnpm i @scope/pkg\nnpm install -g @scope/cli\t全局安装 CLI 工具，不进「已安装」列表',
@@ -257,14 +257,14 @@ export const zh = {
   requestTimeout: '请求超时：无法访问 GitHub 或网络不稳定，请稍后重试',
   confirmCancel: '取消',
   doneBtn: '完成',
-  // 结果视图兜底：仅当「刷新解决不了」时（热挂载失败 / 非 dsh 插件 / 更新）才出现单个「立即重启」；
+  // 结果视图补充：仅当「刷新解决不了」时（热加载失败 / 非 dsh 插件 / 更新）才出现单个「立即重启」；
   // 关闭弹窗即视为「稍后」，不再单独给「稍后重启」按钮
   restartNow: '立即重启',
   restarting: '正在重启…',
   restartHint: '重启会中断正在进行的安装/卸载任务，其进度将丢失。部分插件（如插件市场、顶层 bundle）需重启后才会生效。',
   // 桌面端宿主归应用壳管、插件重启不了它：点「立即重启」时改提示用户退出重开
   toastRestartDesktop: '桌面端的宿主由应用管理，请在应用菜单（或托盘）选择退出后重新打开，重启后生效',
-  // 装完即生效：插件已热挂进运行中 loader，结果弹窗关闭时自动刷新页面（无需用户点按钮）
+  // 装完即生效：插件已热加载进运行中 loader，结果弹窗关闭时自动刷新页面（无需用户点按钮）
   reloadHint: '插件已加载，关闭本窗口后会自动刷新页面生效。',
   toastInstalledLive: '安装成功，已立即生效',
   toastInstalledReload: '安装成功，正在自动刷新页面…',
@@ -311,7 +311,7 @@ export const zh = {
   // 非插件侧失败（未知原因）改为引导到插件中心仓库排查
   failHubIssueHint: '此失败已被判定为环境或插件中心自身问题（非插件作者问题），带着错误日志到插件中心仓库一键提交 Issue',
   failHubIssueBig: '反馈给插件中心排查',
-  // 未知失败兜底：不归到插件作者，引导到插件中心仓库排查
+  // 未知失败补充：不归到插件作者，引导到插件中心仓库排查
   failUnclassifiedHint: '{action}失败，原因未能自动识别。这通常不是插件自身的问题（可能与本机环境或插件中心有关），请将错误信息反馈给插件中心，由维护者排查。',
   // 插件中心自身状态类消息（插件未安装 / 不在此处卸载 / 已在队列中）：已安装列表与实读快照不同步，非插件问题，不引导提 Issue
   failHubStateHint: '插件列表状态已过期或与本地不一致：这次{action}的目标可能已经在列表里了（要升级请点「更新」），也可能已经不在已安装列表中，或已在队列中。这不是插件本身的问题 —— 请刷新页面后重试。',
@@ -491,10 +491,10 @@ export const zh = {
   update: '可更新',
   updateAvailable: '有更新',
   updateAvailableHint: '检测到更新：有版本号的仓库比对版本号，无版本号的仓库比对仓库最近更新时间',
-  // 门禁暂缓：新版本发布未满 24 小时，此时安装会被 pnpm 静默回退（或直接拒绝），
-  // 给出确切可重试时刻，而不是让徽标静默消失、让用户以为已经是最新
+  // 冷却期未到：新版本发布未满 24 小时，此时安装会被 pnpm 不提示地回退（或直接拒绝），
+  // 给出确切可重试时刻，而不是让徽标悄悄消失、让用户以为已经是最新
   updatePending: '暂缓到 {time} 后可更新',
-  updatePendingHint: '新版本发布未满 24 小时，pnpm 供应链门禁会拦下；到时间后再更新即可',
+  updatePendingHint: '新版本发布还不满 24 小时，pnpm 暂时不让安装；到时间后再更新即可',
   hubUpdateHint: '检测到 DSH Plugin Hub 新版本，点击查看更新内容并更新',
   hubUpdateTitle: 'DSH Plugin Hub 有新版本',
   hubUpdateDesc: '点击下方按钮即可更新，完成后需重启宿主生效。',
@@ -508,8 +508,8 @@ export const zh = {
   hubVersionStateAvailable: '可更新',
   hubVersionStatePending: '暂缓提示',
   close: '关闭',
-  // 暂缓提示：远端确有新版本，但发布未满 24 小时（pnpm 供应链安全门槛），与「已是最新」严格区分
-  hubPendingDesc: '最新版已发布，但发布尚未满 24 小时：此时更新会被 pnpm 静默回退到旧版本，因此暂不提示。稍后这里会自动出现更新入口。',
+  // 暂缓提示：远端确有新版本，但发布未满 24 小时（pnpm 发布冷却期），与「已是最新」严格区分
+  hubPendingDesc: '最新版已发布，但发布尚未满 24 小时：此时更新会被 pnpm 不提示地回退到旧版本，因此暂不提示。稍后这里会自动出现更新入口。',
   // 头部「关注我们」弹窗：平台介绍（内容由 Worker /about Markdown 推送，非写死）
   followUs: '关注我们',
   aboutTitle: '关注我们',
@@ -573,7 +573,7 @@ export const en = {
   npmInstallPlaceholder: 'npm install <pkg> or a bare package name',
   npmInstallExample: 'Native commands: npm install lodash, npm i lodash, pnpm add @scope/pkg',
   npmInstallExample2: 'Global CLI: npm install -g @scope/cli; or just type a package name like lodash',
-  npmInstallInvalid: 'Enter an npm package name (e.g. lodash, @scope/pkg), or a native install command (e.g. npm install lodash, npm i lodash, pnpm add @scope/pkg, npm install -g @scope/cli)',
+  npmInstallInvalid: 'Enter an npm package name (e.g. lodash, @scope/pkg), or a native install command (e.g. npm install lodash, npm i lodash, pnpm add @scope/pkg, npm install -g @scope/cli); GitHub source URLs are not supported — use the plugin\'s npm package name instead',
   installHelp: 'Help',
   helpModalTitle: 'Supported command formats',
   npmInstallHelp: 'lodash or @scope/pkg\tjust type the package name\nnpm install lodash\nnpm i lodash\npnpm add @scope/pkg\npnpm i @scope/pkg\nnpm install -g @scope/cli\tinstalls the CLI globally, not shown in Installed',
@@ -700,7 +700,7 @@ export const en = {
   settingsDiagFail: 'Unreachable',
   // 系统诊断通道列表：一键全检 + 每通道一行，点击重测
   diagNpm: 'npm registry',
-  // 诊断 npm 行：未配置镜像时显示的兜底文案（探测仍打官方源）
+  // 诊断 npm 行：未配置镜像时显示的备用文案（探测仍打官方源）
   diagNpmUnset: 'Unset (follow local npm config)',
   diagGithub: 'GitHub',
   diagCatalog: 'Catalog site',
@@ -771,14 +771,14 @@ export const en = {
   requestTimeout: 'Request timed out: GitHub may be unreachable or the network is unstable — try again later',
   confirmCancel: 'Cancel',
   doneBtn: 'Done',
-  // 结果视图兜底：仅刷新解决不了时（热挂载失败 / 非 dsh 插件 / 更新）才给单个「立即重启」；
+  // 结果视图补充：仅刷新解决不了时（热加载失败 / 非 dsh 插件 / 更新）才给单个「立即重启」；
   // 关闭弹窗即视为「稍后」
   restartNow: 'Restart now',
   restarting: 'Restarting…',
   restartHint: 'Restarting interrupts any in-progress install / uninstall task — its progress will be lost. Some plugins (such as plugin markets / top-level bundles) only take effect after a restart.',
   // 桌面端：宿主由应用壳托管，插件重启不了它 —— 提示用户退出后重开
   toastRestartDesktop: 'In the desktop app the host is managed by the app: quit from the app menu (or tray) and open it again — the change takes effect after that restart',
-  // 免重启即生效：安装已热挂载进运行中 loader；关闭弹窗时页面自动刷新（不给手动刷新按钮）
+  // 免重启即生效：安装已热加载进运行中 loader；关闭弹窗时页面自动刷新（不给手动刷新按钮）
   reloadHint: 'The plugin is loaded — closing this window will refresh the page automatically.',
   toastInstalledLive: 'Installed — active now',
   toastInstalledReload: 'Installed — refreshing the page automatically…',
@@ -823,7 +823,7 @@ export const en = {
   // 非插件侧失败（未分类）改为投递到插件中心仓库分诊
   failHubIssueHint: 'This failure was classified as an environment or Plugin Hub issue (not a plugin-author issue). Open a pre-filled issue on the Plugin Hub repo with this error log.',
   failHubIssueBig: 'Report to the Plugin Hub for triage',
-  // 未知失败兜底：不投插件作者，改投插件中心仓库分诊
+  // 未知失败补充：不投插件作者，改投插件中心仓库分诊
   failUnclassifiedHint: 'The {action} failed and the cause could not be identified automatically. This is usually not the plugin itself (it may relate to your local environment or the Plugin Hub). Please report the error to the Plugin Hub so the maintainers can triage it.',
   // 插件中心自身的状态守卫消息（未安装 / 不在此处卸载 / 已在队列中 / 已安装）：已装列表与实读快照不同步 —— 不是插件问题，不引导提 Issue
   failHubStateHint: 'The plugin list is out of date or out of sync: the target of this {action} may already be in the list (use "Update" to upgrade), may no longer be in the installed list, or may already be queued. This is not a plugin problem — refresh the page and retry.',
@@ -1017,7 +1017,7 @@ export const en = {
   hubVersionStateAvailable: 'Update available',
   hubVersionStatePending: 'Held for 24h',
   close: 'Close',
-  // 暂缓提示：确有新版本，但仍在 pnpm 24h 供应链门禁窗口内
+  // 暂缓提示：确有新版本，但仍在 pnpm 24h 发布冷却期内
   hubPendingDesc: 'The latest version has been released, but it is still within the 24-hour window where pnpm silently falls back to the older version, so the update is not offered yet. The update entry will appear here shortly.',
   // 头部「关注我们」弹窗：平台介绍（内容由 Worker /about 以 Markdown 推送）
   followUs: 'Follow us',

package/src/client/logic/constants.ts

@@ -33,7 +33,7 @@ declare const __PLUGIN_VERSION__: string
 /**
  * 插件当前版本号，供头部标题展示「DSH Plugin Hub v0.1.1」。
  * tsdown 构建时用 define 把 __PLUGIN_VERSION__ 替换成 package.json 的版本号；
- * node --test 直接 import 本模块时该标识符不存在，typeof 守卫兜底为空串。
+ * node --test 直接 import 本模块时该标识符不存在，typeof 守卫缺省为空串。
  */
 export const PLUGIN_VERSION: string =
   typeof __PLUGIN_VERSION__ === 'string' ? __PLUGIN_VERSION__ : ''

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

@@ -1,5 +1,5 @@
 /**
- * 自愈缺失的插件 CSS 标签。
+ * 自动补回缺失的插件 CSS 标签。
  *
  * CSS 注入是 bundle 工厂的一次性副作用（以「标签已存在」为守卫）。宿主重启后页面仍在，
  * 但宿主 HMR 链可能移除 <style data-plugin> 标签，而内存模块缓存仍持有旧工厂，工厂不再
@@ -7,7 +7,7 @@
  *
  * tsdown 的 `dsh-css-modules-inline` 构建插件会在工厂执行时把每个模块的 { tagId, css }
  * 登记进全局列表 `__DSH_PLUGIN_CSS__`。此工具随后比对列表与实时 DOM，补注入缺失的标签，
- * 把「点一圈才自愈」变成挂载 / 切换视图时自动完成。
+ * 把「点一圈才恢复」变成挂载 / 切换视图时自动完成。
  */
 
 interface PluginCssEntry {

package/src/client/logic/failures.ts

@@ -16,7 +16,7 @@ export interface NotificationRecord {
   /** owner/repo（可能为空：请求层失败但拿不到仓库时） */
   repo: string
   /** 实际动作（install/update/uninstall）：成功/失败通知据此区分「安装成功」与「更新成功」。
-   *  缺省按 kind 兜底（历史记录可能没有该字段）。更新提醒（kind='update'）不用此字段。 */
+   *  缺省按 kind 归类（历史记录可能没有该字段）。更新提醒（kind='update'）不用此字段。 */
   action?: 'install' | 'update' | 'uninstall'
   /** 失败时的完整错误日志；成功记录为空串 */
   message: string
@@ -150,7 +150,7 @@ export function removeNotification(id: number): NotificationRecord[] {
 
 export type FailureKind = 'npmTooOld' | 'nodeEngine' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmModulesMismatch' | 'profileYamlCorrupted' | 'profileLocalBuild' | 'profileState' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'pluginMissingDep' | 'registryVersionStale' | 'registryAuth' | 'profileExclusive' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'buildToolchainMissing' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'hostIncompatible' | 'tlsTrust' | 'network' | 'hostCliSpawn' | 'hubState' | 'profileBundleMissing' | 'timeout' | 'profileLock' | 'dshTooOld' | 'localEnv' | 'hub'
 
-/** 失败动作口径：标题、上报正文与提示文案按安装/更新/卸载取词，不写死「安装」。 */
+/** 失败动作规则：标题、上报正文与提示文案按安装/更新/卸载取词，不写死「安装」。 */
 export type FailureAction = 'install' | 'update' | 'uninstall'
 
 /** 动作词（英文）：名词短语，标题与句子里都成立。 */
@@ -163,7 +163,7 @@ export function actionWordZh(action: FailureAction): string {
   return action === 'uninstall' ? '卸载' : action === 'update' ? '更新' : '安装'
 }
 
-/** 记录的动作：老记录只有 kind，按 kind 兜底。 */
+/** 记录的动作：老记录只有 kind，按 kind 归类。 */
 export function actionOfRecord(rec: { kind: NotificationRecord['kind']; action?: FailureAction }): FailureAction {
   if (rec.action !== undefined) return rec.action
   return rec.kind === 'uninstall' ? 'uninstall' : rec.kind === 'update' ? 'update' : 'install'
@@ -231,7 +231,7 @@ export function pnpmPolicyHintParams(message: string): Record<string, string> {
  * （只影响这个插件 → 才引导提 Issue）。各分支判定顺序有依赖，见函数内注释。
  */
 export function classifyFailure(message: string): FailureKind {
-  // 宿主版本门禁：插件声明的兼容范围不含当前 dsh 版本，宿主在安装前直接拒绝。
+  // 宿主版本要求：插件声明的兼容范围不含当前 dsh 版本，宿主在安装前直接拒绝。
   // 必须最先判 —— 这是宿主自己给的结论，不是 pnpm 的安装失败
   if (/installation rejected:.*incompatible with dsh/i.test(message)) return 'hostIncompatible'
   // desktop profile 由桌面应用独占：外部 dsh CLI 无权管理，宿主在安装前直接拒绝。
@@ -266,7 +266,7 @@ export function classifyFailure(message: string): FailureKind {
   // pnpm 供应链策略拦截（缺 tarball integrity / 校验和不匹配 / minimumReleaseAge / untrusted origin）。
   // 必须在 pnpmIgnoredBuild 之前
   if (missingTarballIntegrity(message) || mismatchedTarballIntegrity(message) || /ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION|ERR_PNPM_NO_MATURE_MATCHING_VERSION|Minimum release age|minimumReleaseAge|untrusted origin/i.test(message)) return 'pnpmPolicy'
-  // profile 残留旧版本 patch 声明，pnpm 中止安装。必须在兜底之前
+  // profile 残留旧版本 patch 声明，pnpm 中止安装。必须排在默认归类之前
   if (/ERR_PNPM_UNUSED_PATCH|patches were not used/i.test(message)) return 'pnpmUnusedPatch'
   // profile 里的 YAML 配置解析失败（pnpm-workspace.yaml / pnpm-lock.yaml 有重复键、缩进坏了）：
   // pnpm 在依赖解析之前就退出，装任何插件都会同样失败，属本机 profile 配置问题。
@@ -334,7 +334,7 @@ export function classifyFailure(message: string): FailureKind {
   if (/git-hosted plugins build on install via their prepare script|add the exact key pnpm printed above under allowBuilds/i.test(message)) return 'pnpmIgnoredBuild'
   // 宿主启动插件管理时找不到某个 profile bundle（`cannot resolve profile bundle "<pkg>"`）：
   // 该 profile 声明的依赖没装全（node_modules 被删过 / 上次安装中断 / 桌面端更新不完整），
-  // 与本次要装的插件无关 —— 必须在 hub 兜底之前，否则又会被当成未知错误丢给我们
+  // 与本次要装的插件无关 —— 必须排在 hub 的默认归类之前，否则又会被当成未知错误丢给我们
   if (/cannot resolve profile bundle/i.test(message)) return 'profileBundleMissing'
   // 宿主自身入口起不来（服务端 [host-spawn] 标记）：环境问题，给提示、不引导提 Issue。
   // 不匹配 `spawn … ENOENT` 文本 —— 那个形态任何 spawn（curl/git/taskkill…）都会产出
@@ -354,7 +354,7 @@ export function classifyFailure(message: string): FailureKind {
   return 'hub'
 }
 
-/** 「特征指向本机环境但说不清具体哪一类」的兜底判据：系统调用错误码（权限/路径过长/设备异常）、
+/** 「特征指向本机环境但说不清具体哪一类」的最后的判断规则：系统调用错误码（权限/路径过长/设备异常）、
  *  证书与代理校验失败、本地配置文件（~/.npmrc、profile 的 package.json）损坏。
  *  只做排除用：命中它表示「不是插件侧问题」，不代表我们已经定位到原因。 */
 const LOCAL_ENV_RE = /os error \d{1,3}\b|ERROR_[A-Z_]{4,}|\bE(?:ACCES|PERM|NOENT|NAMETOOLONG|INVAL|PROTO|ISDIR|NOTDIR|EXIST|BADF|NOTEMPTY|JSONPARSE|NOMEM)\b|JavaScript heap out of memory|Unexpected token .{0,60}in JSON|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE|ERR_TLS_CERT_ALTNAME_INVALID|unable to verify the first certificate|self[- ]signed certificate|ERR_INVALID_URL|invalid registry|proxy authentication|407 Proxy/i
@@ -386,7 +386,7 @@ export const MAX_CORE_CHARS = 5000
 const MAX_LINE_CHARS = 400
 
 /**
- * 展示用格式化：宿主门禁消息里的 peerDependencies 是压缩成一行的 JSON，
+ * 展示用格式化：宿主兼容性提示里的 peerDependencies 是压缩成一行的 JSON，
  * 直接展示像一团乱码；展开成缩进格式，解析失败则原样返回。
  */
 export function formatFailureMessage(message: string): string {
@@ -420,7 +420,7 @@ export function summarizeError(message: string, maxChars: number = MAX_CORE_CHAR
   }
   let out: string
   if (core.length === 0) {
-    // 整段本来就是短消息时直接给全量：head+tail 兜底会把同一段重复两遍，正文反而更难读
+    // 整段本来就是短消息时直接给全量：head+tail 的截断方式会把同一段重复两遍，正文反而更难读
     const whole = message.trim()
     if (whole.length <= maxChars) return whole
     // 无关键行时退化为「头部 + 尾部」快照：优先保尾部完整，头部按预算压缩，总长不超上限

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

@@ -30,8 +30,7 @@ export function installTargetOf(p: HubPlugin): string {
 /** 展示用安装命令（复制/弹窗）：目录下发的权威命令优先（CLI-only 插件如 dsh-tui
  *  需专属 profile（--profile dsh-tui），无法从 npm 包名推断，必须用官方命令）；
  *  常规插件无目录命令时用 npm 包名回退生成。
- *  version 为已过供应链门禁的版本：带上它，手抄命令与原位安装的执行结果一致，
- *  不会因 pnpm 门禁静默回退到很旧的版本。 */
+ *  version 为已过发布冷却期的版本：带上它，手抄命令与一键安装的执行结果一致。 */
 export function installCommandOf(p: HubPlugin, withProfile = false, version?: string): string {
   const cmd = p.install?.command
   if (cmd) return cmd

package/src/client/logic/installed.ts

@@ -42,7 +42,7 @@ export interface InstalledItem {
   catalogVersion: string | null
   /** 是否有可用更新（有版本比版本，无版本比仓库更新时间） */
   hasUpdate: boolean
-  /** 更新被供应链门禁暂缓时的可重试时刻（毫秒）；无更新/非门禁原因 → null */
+  /** 更新暂缓（新版本还没过冷却期）的可重试时刻（毫秒）；无更新/非冷却期原因 → null */
   pendingUntil: number | null
   /** 是否已加载进运行中 loader（官方 ctx.loader 对账）；false = 已安装但未挂载（装完未重启） */
   loaded: boolean

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

@@ -17,7 +17,7 @@ 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' }
@@ -67,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,
@@ -79,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 !== '')
             : []
@@ -90,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
@@ -123,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()
             : ''
@@ -182,12 +182,12 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
             }
             ordered = [chosen, ...registries.filter((r) => r !== chosen)]
           }
-          // 新安装钉住「已过供应链门禁」的版本：pnpm 对发布未满 24h 的版本会静默回退到很旧的版本，
-          // 用户装完才发现功能缺失且没有任何提示。更新已有目标时客户端已按门禁筛选，继续走 @latest。
+          // 新安装锁定「已过发布冷却期」的最高稳定版：pnpm 对发布还不满 24 小时的版本会不提示地回退，
+          // 锁定后装到的就是预期版本。更新已有目标时客户端已按冷却期筛选，继续走 @latest。
           let installSpec = pinVersion !== '' ? `${target}@${pinVersion}` : undefined
           if (installSpec === undefined && already === null) {
-            // 解析源与安装首选源一致，钉住的版本一定存在于真正会用的那个源；解析失败则不钉，不阻断安装。
-            // 超时压到 5s：网络刚探通，慢也只在极端情况，不能为查版本把安装请求拖住 8s
+            // 解析源与安装首选源一致，锁定的版本一定存在于真正会用的那个源；解析失败则不锁定，不阻断安装。
+            // 超时 5s：网络刚探测通过，卡住时也不能把安装请求拖到默认的 8s
             const release = await lookupReleaseAge(target, ordered[0] ?? '', effectiveProxy, 5000)
             if (release !== null && release.installable !== null) installSpec = `${target}@${release.installable.version}`
           }
@@ -200,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,
@@ -208,7 +208,7 @@ 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),

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

@@ -4,7 +4,7 @@
  * 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'
@@ -27,12 +27,12 @@ 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 配置）：安装钉住的版本必须来自真正要用的那个源
+          // 查询源与安装首选源同一套规则（设置 → 本机 npm 配置）：安装锁定的版本必须来自真正要用的那个源
           const registry = settings.npmRegistry !== ''
             ? settings.npmRegistry
             : userNpmRegistry(profileDirectory(profile))

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)