dsh-plugin-update 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 格式为 Keep-a-Changelog 子集：`Added/Fixed/Changed` 必写，`Deprecated/Removed/Security` 有则透传，`Unreleased` 面板忽略，禁止 git-log 直倒。面板缺日志时中性提示，不挡安装。
 
+## [0.5.1] - 2026-10-06
+
+### Added
+- 入口件 `openOn: 'direct'`：点开即弹窗、不预查（面板挂载即自查；徽标形态仍走回调口径）。
+
+### Fixed
+- 入口件小字对比度：原地提示与档案卷按钮脸自带底，深色宿主下也读得出。
+
 ## [0.5.0] - 2026-10-05
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 给 DSH 插件加「检查更新 / 安装更新」能力的 npm 包。宿主侧一段接线，面板侧挂一个现成组件，装不上时给用户一条可复制的手工命令。
 
-要求 Node 22 或更高，零运行时依赖。当前版本 `0.5.0`。
+要求 Node 22 或更高，零运行时依赖。当前版本 `0.5.1`。
 
 装上它你会拿到六样东西：
 
@@ -181,10 +181,12 @@ const entry = mountUpdateEntry(document.getElementById('upd-entry'), {
 |---|---|---|---|
 | 摆什么 | `button` / `badge` / `inline` | `button` | 按钮；只给一个状态点；面板本体直接嵌进来 |
 | 什么时候查 | `mount` / `never` | `mount` | 进页面静默查一次（**只调 `.updateStatus`，只读**）；`never` 则只在点击时查 |
-| 点了做什么 | `has-update` / `always` / `manual` | `has-update` | 有新版才开面板；总是开；交给 `onActivate` 自己跳 |
+| 点了做什么 | `has-update` / `always` / `manual` / `direct` | `has-update` | 有新版才开面板；检查完总是开；交给 `onActivate` 自己跳；点开即弹窗、不预查 |
 
 按钮文案随状态自己变：`检查更新` / `有新版 1.1.0` / `正在安装…` / `待重启` / `更新失败，点此查看`。
 
+无新版时原地那句小字（`已是最新 X.Y.Z`）只在 `has-update` 下出现：不想看它就用 `openOn: 'always'`（检查完总是开弹窗，无新版在弹窗里看“已是最新”）或 `openOn: 'direct'`（点开即弹窗，连预查都省了，面板挂载即自查；徽标形态仍走回调口径）。
+
 **一条铁律：检查是只读、安装是写入，两者不许合并成一个动作。** 入口件永远只做「查 + 打开面板」，
 任何路径都不自动安装；用户必须在面板里明确点「安装」。想让点击交给自己（例如你已有自己的更新页）：
 
@@ -302,7 +304,7 @@ const panel = mountUpdatePanel(document.getElementById('update-slot'), {
 
 宿主种类与安装出口都由本包自己探测和选择，**升级依赖即可，宿主侧与面板侧都不用改代码**：
 
-1. 依赖版本提到 `^0.5.0`。
+1. 依赖版本提到 `^0.5.1`。
 2. 重新装 / 发一版你自己的插件，让新依赖进当前使用范围（运行时用的是 `node_modules` 里那份）。
 3. 如果你自己接过一版宿主安装出口，把它删掉——它会挡在本包的路由前面。
 

package/dist/changelog-io.d.ts

@@ -9,6 +9,11 @@
  * - 已装版离线读：`node_modules/<目标包>/CHANGELOG.md`（与版本 pin 绑定，零新增联网）；
  * - 新版按需取：新版 tarball 内同名文件，复用官方源 + integrity 校验；
  * 取不到一律回 null（调用方渲染中性提示，不挡安装、不写 blockedReason）。
+ *
+ * 记住策略（#41 终裁，三墙不动，只澄清注释）：成功与取不到（null）按版本永久记
+ * （面板内存会话级 + 宿主进程级，不落盘，显式文本永不覆盖）；传输失败不进缓存，
+ * 手动查新版/换版/重开面板立即重问，轮询按退避问（三处共用 shouldFetchChangelog，各存各的）。
+ * 三墙（8MB 压缩态/32MB 解压后/64K 日志文本）一字不动，超限回 null 由调用方按取不到记住。
  */
 /** tarball 下载上限（字节，压缩态）：超限直接回落中性提示，不解包、不OOM。 */
 export declare const CHANGELOG_TARBALL_MAX_BYTES: number;

package/dist/changelog.d.ts

@@ -9,14 +9,16 @@
  * 解析只做字符串切分，不读盘、不联网；版本语义与核心同口径
  * （validReleaseVersion / compareReleaseVersions，stable 纯三段、prerelease 显式）。
  *
- * 面板约定（Question 原文逐字落实）：
- * - `Added/Fixed/Changed` 必显；`Deprecated/Removed/Security` 透传折叠；
+ * 面板约定（#23 原文 + #41 四处优化终裁）：
+ * - `Added/Fixed/Changed/Security` 必显展开；`Deprecated/Removed` 透传折叠；
  * - `Unreleased` 与空节忽略；
  * - 缺日志中性提示，不挡安装、不写 blockedReason、不动快照六字段
  *   （本模块不碰快照，面板只增一节 HTML，安装门控只跟快照）；
  * - 已装版离线读、新版按需取 tarball 同名文件复用官方源 integrity
  *   （I/O 在 `src/changelog-io.ts` Node 侧，取不到回落中性提示）；
- * - 零依赖纯函数解析器（本文件零导入）。
+ * - 纯函数解析器（仅复用版本语义，不碰 Node 专属；新增 validate 与策略函数零新增导入）。
+ * - 截断数值不动（100 节/每类 200 条/单条 500 字/全文 64K），解析附计数元数据只记数字；
+ *   超限类标计数小字，Security 超限进内折叠；BREAKING 前缀识别 + 行首徽标；yanked 横幅只看 to 版。
  */
 /** 包内日志文件名（包根，与 tarball 内同名文件同一名字）。 */
 export declare const CHANGELOG_FILENAME = "CHANGELOG.md";
@@ -54,6 +56,8 @@ export interface ChangelogEntry {
     yanked: boolean;
     /** 六类各自的条目（空类为空数组，空节忽略由渲染层执行）。 */
     sections: Record<ChangelogCategory, string[]>;
+    /** 每类原始条数（截断前计数，只记数字不留文本；缺省视为与 sections 等长）。 */
+    counts?: Record<ChangelogCategory, number>;
 }
 /** 是否 Unreleased（大小写不敏感，前后空白忽略）。 */
 export declare function isUnreleasedVersion(v: unknown): boolean;
@@ -62,6 +66,41 @@ export declare function isUnreleasedVersion(v: unknown): boolean;
  * 非字符串/空串回 []；超长截断后解析；未知版本标题与其下条目一律丢弃；
  * 全空节版本直接丢弃（空节忽略）；Unreleased 保留（渲染与区间时忽略）。
  */
+/** 共享扫描仪（parse 与 validate 同一套，不许第二套正则）。 */
+export declare const RE_VERSION_HEADING: RegExp;
+export declare const RE_CATEGORY_HEADING: RegExp;
+export declare const RE_BULLET: RegExp;
+export declare const RE_FENCE_TOGGLE: RegExp;
+export declare const RE_VERSION_NUM: RegExp;
+export declare const RE_VERSION_DATE: RegExp;
+export declare const RE_YANKED: RegExp;
+export declare const RE_UNRELEASED: RegExp;
+export declare function matchVersionHeading(line: unknown): string | null;
+export declare function matchCategoryHeading(line: unknown): string | null;
+export declare function matchBulletBody(line: unknown): string | null;
+export declare function isFenceToggle(line: unknown): boolean;
+/** 破坏标记徽标文案（中文 UI 一致，原文前缀另行加粗保留）。 */
+export declare const BREAKING_BADGE_TEXT = "\u4E0D\u517C\u5BB9";
+/** 剥行首 markdown 装饰（加粗/引用/前后空白），只为识别，渲染保留原文一字不动。 */
+export declare function stripBreakingDecorations(s: unknown): string;
+/** 条目是否为破坏标记（去饰后开头匹配，大小写不敏感，中英文冒号皆可）。 */
+export declare function isBreakingChangelogItem(item: unknown): boolean;
+/** 拆出破坏前缀（保留原文拼写与冒号），命中才回，否则 null。 */
+export declare function splitBreakingPrefix(item: string): {
+    head: string;
+    prefix: string;
+    rest: string;
+} | null;
+/** 轮询退避（毫秒）：传输失败后轮询按此退避，手动/换版/重开立即重问。 */
+export declare const CHANGELOG_POLL_BACKOFF_MS: number;
+/** 三处共用（宿主电话/单面板/批量按行，各存各的）：成功与取不到已记住即不再问。 */
+export declare function shouldFetchChangelog(opts: {
+    hasCache: boolean;
+    failedAt: number | null;
+    now: number;
+    isManual: boolean;
+    backoffMs?: number;
+}): boolean;
 export declare function parseChangelog(markdown: unknown): ChangelogEntry[];
 /** 该节是否有可见内容（六类任一非空）。 */
 export declare function hasVisibleSections(entry: ChangelogEntry | null | undefined): boolean;
@@ -81,6 +120,14 @@ export declare function selectChangelogEntries(entries: unknown, fromExclusive:
  * 任一缺失/非法即回 []（调用方渲染中性提示，不挡安装）。
  */
 export declare function changelogForUpdate(entries: unknown, runningVersion: unknown, latestVersion: unknown, installedVersion?: unknown): ChangelogEntry[];
+/** 计数元数据取值（缺省视为与 sections 等长，只记数字）。 */
+export declare function countsOf(entry: ChangelogEntry | null | undefined): Record<ChangelogCategory, number>;
+/** 超限小字（诚实截断）：共 M 条，仅显示前 N 条。 */
+export declare function truncatedNoteHTML(total: number, shown: number): string;
+/** 撤回横幅（只看 to 版，纯展示，不挡安装，文案冻结）。 */
+export declare function yankedBannerHTML(version: unknown): string;
+/** 单条目 HTML（含破坏标记徽标与前缀加粗，正文一字不动）。 */
+export declare function renderChangelogItem(item: string): string;
 /** 单节 HTML（调用方保证已过滤 Unreleased 与空节，本函数再兜底一次）。 */
 export declare function renderChangelogSection(entry: ChangelogEntry): string;
 /** 中性提示 HTML（缺日志、取不到、无区间内容时统一用它，不挡安装）。 */
@@ -94,3 +141,19 @@ export declare function renderChangelogHTML(entries: unknown, opts?: {
     from?: string | null;
     to?: string | null;
 }): string;
+/** 校验诊断（一行一码，行号为原文件 1-based，诊断按行号排序）。 */
+export interface ChangelogDiagnostic {
+    line: number;
+    code: string;
+    hint: string;
+}
+export interface ChangelogValidation {
+    ok: boolean;
+    diagnostics: ChangelogDiagnostic[];
+}
+/** 校验提示文（与终裁码表一字对应，仅 CI/发布前用，运行时永不调用）。 */
+export declare const CHANGELOG_VALIDATE_HINTS: Record<string, string>;
+/** 疑似破坏误写（仅行首可疑，不报正文中间散文）。 */
+export declare function isMaybeBreakingMisuse(bulletBody: unknown): boolean;
+/** 纯校验（零新增导入，与 parse 共享扫描仪，永不抛错，仅 CI/发布前用）。 */
+export declare function validateChangelog(markdown: unknown): ChangelogValidation;

package/dist/changelog.js

@@ -15,8 +15,8 @@ const CHANGELOG_ALL_CATEGORIES = [
   "Removed",
   "Security"
 ];
-const CHANGELOG_MUST_SHOW = ["Added", "Fixed", "Changed"];
-const CHANGELOG_FOLDED = ["Deprecated", "Removed", "Security"];
+const CHANGELOG_MUST_SHOW = ["Added", "Fixed", "Changed", "Security"];
+const CHANGELOG_FOLDED = ["Deprecated", "Removed"];
 const CHANGELOG_CATEGORY_ZH = {
   Added: "\u65B0\u589E",
   Fixed: "\u4FEE\u590D",
@@ -28,6 +28,9 @@ const CHANGELOG_CATEGORY_ZH = {
 function emptySections() {
   return { Added: [], Fixed: [], Changed: [], Deprecated: [], Removed: [], Security: [] };
 }
+function emptyCounts() {
+  return { Added: 0, Fixed: 0, Changed: 0, Deprecated: 0, Removed: 0, Security: 0 };
+}
 function isCategoryName(v) {
   return CHANGELOG_ALL_CATEGORIES.includes(v);
 }
@@ -60,6 +63,119 @@ function truncateBullet(text) {
   if (t.length <= CHANGELOG_MAX_BULLET_CHARS) return t;
   return `${t.slice(0, CHANGELOG_MAX_BULLET_CHARS - 1)}\u2026`;
 }
+const RE_VERSION_HEADING = /^##(?!#)\s*(.+?)\s*$/;
+const RE_CATEGORY_HEADING = /^###\s*(.+?)\s*$/;
+const RE_BULLET = /^\s*[-*+]\s+(.+?)\s*$/;
+const RE_FENCE_TOGGLE = new RegExp("^\\s*(" + String.fromCharCode(96).repeat(3) + "|~~~)");
+const RE_VERSION_NUM = /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/;
+const RE_VERSION_DATE = /(\d{4}-\d{2}-\d{2})/;
+const RE_YANKED = /\[YANKED\]/i;
+const RE_UNRELEASED = /unreleased/i;
+function matchVersionHeading(line) {
+  try {
+    const s = String(line !== null && line !== void 0 ? line : "");
+    const m = s.match(RE_VERSION_HEADING);
+    if (!m) return null;
+    return String(m[1] !== void 0 && m[1] !== null ? m[1] : "").trim();
+  } catch {
+    return null;
+  }
+}
+function matchCategoryHeading(line) {
+  try {
+    const s = String(line !== null && line !== void 0 ? line : "");
+    const m = s.match(RE_CATEGORY_HEADING);
+    if (!m) return null;
+    return String(m[1] !== void 0 && m[1] !== null ? m[1] : "").trim();
+  } catch {
+    return null;
+  }
+}
+function matchBulletBody(line) {
+  try {
+    const s = String(line !== null && line !== void 0 ? line : "");
+    const m = s.match(RE_BULLET);
+    if (!m) return null;
+    return String(m[1] !== void 0 && m[1] !== null ? m[1] : "");
+  } catch {
+    return null;
+  }
+}
+function isFenceToggle(line) {
+  try {
+    return RE_FENCE_TOGGLE.test(String(line !== null && line !== void 0 ? line : ""));
+  } catch {
+    return false;
+  }
+}
+const BREAKING_BADGE_TEXT = "\u4E0D\u517C\u5BB9";
+function stripBreakingDecorations(s) {
+  try {
+    let t = String(s !== null && s !== void 0 ? s : "").trim();
+    let changed = true;
+    while (changed) {
+      changed = false;
+      if (t.charAt(0) === ">") {
+        t = t.slice(1).trim();
+        changed = true;
+        continue;
+      }
+      if (t.slice(0, 2) === "**" || t.slice(0, 2) === "__") {
+        t = t.slice(2).trim();
+        changed = true;
+        continue;
+      }
+      if (t.charAt(0) === "*" || t.charAt(0) === "_") {
+        t = t.slice(1).trim();
+        changed = true;
+        continue;
+      }
+    }
+    return t;
+  } catch {
+    return "";
+  }
+}
+function isBreakingChangelogItem(item) {
+  try {
+    if (typeof item !== "string") return false;
+    const t = stripBreakingDecorations(item);
+    if (!t) return false;
+    return /^(breaking|不兼容)\s*[:：]/i.test(t);
+  } catch {
+    return false;
+  }
+}
+function splitBreakingPrefix(item) {
+  try {
+    const s = String(item !== null && item !== void 0 ? item : "");
+    const m = s.match(/^(\s*(?:>\s*|\*\*\s*|__\s*|\*\s*|_\s*)*)(breaking|不兼容)(\s*[:：])/i);
+    if (!m) return null;
+    const head = String(m[1] !== void 0 && m[1] !== null ? m[1] : "");
+    const core = String(m[2] !== void 0 && m[2] !== null ? m[2] : "");
+    const colon = String(m[3] !== void 0 && m[3] !== null ? m[3] : "");
+    const prefix = core + colon;
+    const rest = s.slice(m[0].length);
+    return { head, prefix, rest };
+  } catch {
+    return null;
+  }
+}
+const CHANGELOG_POLL_BACKOFF_MS = 30 * 1e3;
+function shouldFetchChangelog(opts) {
+  try {
+    const o = opts;
+    if (o.hasCache === true) return false;
+    if (o.isManual === true) return true;
+    const now = typeof o.now === "number" && Number.isFinite(o.now) ? o.now : Date.now();
+    const failedAt = typeof o.failedAt === "number" && Number.isFinite(o.failedAt) ? o.failedAt : null;
+    if (failedAt === null) return true;
+    const backoff = typeof o.backoffMs === "number" && Number.isFinite(o.backoffMs) && o.backoffMs > 0 ? Math.floor(o.backoffMs) : CHANGELOG_POLL_BACKOFF_MS;
+    return now - failedAt >= backoff;
+  } catch {
+    return true;
+  }
+}
 function parseChangelog(markdown) {
   try {
     if (typeof markdown !== "string" || !markdown.trim()) return [];
@@ -86,32 +202,38 @@ function parseChangelog(markdown) {
     };
     for (const rawLine of lines) {
       const line = String(rawLine ?? "");
-      if (/^\s*(```|~~~)/.test(line)) {
+      if (isFenceToggle(line)) {
         inFence = !inFence;
         continue;
       }
       if (inFence) continue;
-      const versionHeading = line.match(/^##(?!#)\s*(.+?)\s*$/);
-      if (versionHeading) {
+      const versionTitle = matchVersionHeading(line);
+      if (versionTitle !== null) {
         pushCurrent();
         cur = null;
         curCat = null;
-        const title = (versionHeading[1] ?? "").trim();
+        const title = versionTitle;
         const { version, date, yanked } = extractVersionDateAndYanked(title);
         if (!version) continue;
-        cur = { version, date, yanked, sections: emptySections() };
+        cur = { version, date, yanked, sections: emptySections(), counts: emptyCounts() };
         continue;
       }
-      const catMatch = line.match(/^###\s*(.+?)\s*$/);
-      if (catMatch) {
-        const cat = normalizeCategory(catMatch[1] ?? "");
+      const catTitle = matchCategoryHeading(line);
+      if (catTitle !== null) {
+        const cat = normalizeCategory(catTitle);
         curCat = cur && cat && isCategoryName(cat) ? cat : null;
         continue;
       }
-      const bullet = line.match(/^\s*[-*+]\s+(.+?)\s*$/);
-      if (bullet && cur && curCat) {
-        const item = truncateBullet(bullet[1] ?? "");
-        if (item) cur.sections[curCat].push(item);
+      const bulletBody = matchBulletBody(line);
+      if (bulletBody !== null && cur && curCat) {
+        const item = truncateBullet(bulletBody);
+        if (item) {
+          cur.sections[curCat].push(item);
+          try {
+            if (cur.counts) cur.counts[curCat] += 1;
+          } catch {
+          }
+        }
         continue;
       }
       const trimmed = line.trim();
@@ -189,46 +311,119 @@ function changelogForUpdate(entries, runningVersion, latestVersion, installedVer
 function escapeChangelogHtml(text) {
   return String(text ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
+function countsOf(entry) {
+  try {
+    const out = { Added: 0, Fixed: 0, Changed: 0, Deprecated: 0, Removed: 0, Security: 0 };
+    if (!entry || typeof entry !== "object") return out;
+    for (const c of CHANGELOG_ALL_CATEGORIES) {
+      const n = entry.counts;
+      const v = n && typeof n[c] === "number" && Number.isFinite(n[c]) ? Math.floor(n[c]) : null;
+      if (v !== null && v >= 0) {
+        out[c] = v;
+        continue;
+      }
+      const list = entry.sections;
+      const arr = list ? list[c] : null;
+      out[c] = Array.isArray(arr) ? arr.length : 0;
+    }
+    return out;
+  } catch {
+    return { Added: 0, Fixed: 0, Changed: 0, Deprecated: 0, Removed: 0, Security: 0 };
+  }
+}
+function truncatedNoteHTML(total, shown) {
+  try {
+    const m = Math.floor(total);
+    const n = Math.floor(shown);
+    return '<div class="dsh-upd-changelog-count">\u5171 ' + String(m) + " \u6761\uFF0C\u4EC5\u663E\u793A\u524D " + String(n) + " \u6761</div>";
+  } catch {
+    return "";
+  }
+}
+function yankedBannerHTML(version) {
+  try {
+    const v = typeof version === "string" ? version.trim() : "";
+    if (!v) return "";
+    return '<div class="dsh-upd-changelog-yanked" role="alert">\u76EE\u6807\u7248\u672C ' + escapeChangelogHtml(v) + " \u5DF2\u88AB\u4F5C\u8005\u64A4\u56DE\uFF08yanked\uFF09\uFF0C\u5B89\u88C5\u4E0D\u53D7\u5F71\u54CD\uFF0C\u7EE7\u7EED\u524D\u8BF7\u786E\u8BA4\u3002</div>";
+  } catch {
+    return "";
+  }
+}
+function renderChangelogItem(item) {
+  try {
+    const s = String(item !== null && item !== void 0 ? item : "");
+    if (!s) return "";
+    const split = splitBreakingPrefix(s);
+    if (!split) return "<li>" + escapeChangelogHtml(s) + "</li>";
+    const head = escapeChangelogHtml(split.head);
+    const prefix = escapeChangelogHtml(split.prefix);
+    const rest = escapeChangelogHtml(split.rest);
+    const badge = '<span class="dsh-upd-breaking-badge" role="img" aria-label="\u7834\u574F\u6027\u53D8\u66F4">' + BREAKING_BADGE_TEXT + "</span> ";
+    return "<li>" + head + badge + "<strong>" + prefix + "</strong>" + rest + "</li>";
+  } catch {
+    return "";
+  }
+}
 function renderChangelogSection(entry) {
   try {
     if (!entry || typeof entry !== "object") return "";
-    const version = String(entry.version ?? "").trim();
+    const version = String(entry.version !== void 0 && entry.version !== null ? String(entry.version) : "").trim();
     if (!version || isUnreleasedVersion(version)) return "";
     if (!hasVisibleSections(entry)) return "";
-    const date = typeof entry.date === "string" ? String(entry.date) : "";
-    const yankedSuffix = entry.yanked === true ? " \xB7 \u5DF2\u64A4\u56DE" : "";
-    const title = (date ? `${version} \xB7 ${date}` : version) + yankedSuffix;
+    const dateRaw = entry.date;
+    const date = typeof dateRaw === "string" ? dateRaw : "";
+    const yankedFlag = entry.yanked === true;
+    const yankedSuffix = yankedFlag ? " \xB7 \u5DF2\u64A4\u56DE" : "";
+    const title = (date ? version + " \xB7 " + date : version) + yankedSuffix;
+    const counts = countsOf(entry);
     const parts = [];
-    parts.push(`<div class="dsh-upd-changelog-version" data-version="${escapeChangelogHtml(version)}">`);
-    parts.push(`<div class="dsh-upd-changelog-title">${escapeChangelogHtml(title)}</div>`);
+    parts.push('<div class="dsh-upd-changelog-version" data-version="' + escapeChangelogHtml(version) + '">');
+    parts.push('<div class="dsh-upd-changelog-title">' + escapeChangelogHtml(title) + "</div>");
     for (const cat of CHANGELOG_MUST_SHOW) {
-      const items = Array.isArray(entry.sections?.[cat]) ? entry.sections[cat] : [];
-      if (items.length === 0) continue;
-      const label = `${cat} \xB7 ${CHANGELOG_CATEGORY_ZH[cat]}`;
-      parts.push(`<div class="dsh-upd-changelog-cat" data-cat="${cat}">`);
-      parts.push(`<div class="dsh-upd-changelog-catname">${escapeChangelogHtml(label)}</div>`);
+      const items = Array.isArray(entry.sections ? entry.sections[cat] : null) ? entry.sections[cat] : [];
+      if (!items || items.length === 0) continue;
+      const label = cat + " \xB7 " + CHANGELOG_CATEGORY_ZH[cat];
+      parts.push('<div class="dsh-upd-changelog-cat" data-cat="' + cat + '">');
+      parts.push('<div class="dsh-upd-changelog-catname">' + escapeChangelogHtml(label) + "</div>");
+      const total = counts[cat];
+      const shown = items.length;
+      if (total > shown) {
+        parts.push(truncatedNoteHTML(total, shown));
+      }
       parts.push("<ul>");
       for (const item of items) {
         if (!item) continue;
-        parts.push(`<li>${escapeChangelogHtml(item)}</li>`);
+        const li = renderChangelogItem(item);
+        if (li) parts.push(li);
+      }
+      parts.push("</ul>");
+      if (cat === "Security" && total > shown) {
+        const restCount = total - shown;
+        parts.push('<details class="dsh-upd-changelog-security-more"><summary>\u5176\u4F59 ' + String(restCount) + ' \u6761</summary><div class="dsh-upd-changelog-more-note">\u4E3A\u4FDD\u6301\u9762\u677F\u6027\u80FD\uFF0C\u5176\u4F59\u6761\u76EE\u5DF2\u6298\u53E0\uFF0C\u53EF\u67E5\u770B\u539F\u6587\u3002</div></details>');
       }
-      parts.push("</ul></div>");
+      parts.push("</div>");
     }
     for (const cat of CHANGELOG_FOLDED) {
-      const items = Array.isArray(entry.sections?.[cat]) ? entry.sections[cat] : [];
-      if (items.length === 0) continue;
-      const label = `${cat} \xB7 ${CHANGELOG_CATEGORY_ZH[cat]}\uFF08${items.length}\uFF09`;
-      parts.push(`<details class="dsh-upd-changelog-fold" data-cat="${cat}">`);
-      parts.push(`<summary>${escapeChangelogHtml(label)}</summary>`);
+      const items = Array.isArray(entry.sections ? entry.sections[cat] : null) ? entry.sections[cat] : [];
+      if (!items || items.length === 0) continue;
+      const label = cat + " \xB7 " + CHANGELOG_CATEGORY_ZH[cat] + "\uFF08" + String(items.length) + "\uFF09";
+      parts.push('<details class="dsh-upd-changelog-fold" data-cat="' + cat + '">');
+      parts.push("<summary>" + escapeChangelogHtml(label) + "</summary>");
+      const total = counts[cat];
+      const shown = items.length;
+      if (total > shown) {
+        parts.push(truncatedNoteHTML(total, shown));
+      }
       parts.push("<ul>");
       for (const item of items) {
         if (!item) continue;
-        parts.push(`<li>${escapeChangelogHtml(item)}</li>`);
+        const li = renderChangelogItem(item);
+        if (li) parts.push(li);
       }
       parts.push("</ul></details>");
     }
     parts.push("</div>");
-    return parts.join("\n");
+    return parts.join(String.fromCharCode(10));
   } catch {
     return "";
   }
@@ -264,7 +459,165 @@ ${blocks.join("\n")}
     return renderChangelogNeutral();
   }
 }
+const CHANGELOG_VALIDATE_HINTS = {
+  E_VERSION_TITLE: "\u8BE5\u6807\u9898\u4E0D\u662F\u5408\u6CD5\u7248\u672C\u53F7\uFF0C\u5176\u4E0B\u6761\u76EE\u5DF2\u88AB\u5FFD\u7565\uFF0C\u8BF7\u6539\u6210 ## [x.y.z] \u5F62\u6001",
+  E_CATEGORY: "\u672A\u77E5\u5206\u7C7B\uFF0C\u5176\u4E0B\u6761\u76EE\u5DF2\u88AB\u5FFD\u7565\uFF0C\u4EC5\u6536 Added/Fixed/Changed/Deprecated/Removed/Security",
+  E_BULLET_ORPHAN: "\u8BE5\u6761\u76EE\u4E0D\u5728\u7248\u672C\u8282\u4E0E\u5206\u7C7B\u4E0B\uFF0C\u5DF2\u88AB\u5FFD\u7565",
+  W_BREAKING_MAYBE: "\u7591\u4F3C\u7834\u574F\u6807\u8BB0\u8BEF\u5199\uFF08\u7F3A\u5192\u53F7/\u62FC\u5199\u63A5\u8FD1/\u4F4D\u7F6E\u7591\u4F3C\u653E\u9519\uFF09\uFF0C\u8BF7\u68C0\u67E5\u662F\u5426\u60F3\u5199 BREAKING:/\u4E0D\u517C\u5BB9:",
+  W_YANKED: "\u8BE5\u7248\u672C\u5DF2\u88AB\u6807\u8BB0\u64A4\u56DE\uFF08yanked\uFF09\uFF0C\u5B89\u88C5\u4E0D\u53D7\u5F71\u54CD\uFF0C\u7EE7\u7EED\u524D\u8BF7\u786E\u8BA4",
+  W_TRUNCATED: "\u8BE5\u7C7B\u5171 M \u6761\uFF0C\u4EC5\u663E\u793A\u524D N \u6761",
+  W_TRUNCATED_FILE: "\u6587\u4EF6\u8D85 64K\uFF0C\u4EC5\u6821\u9A8C\u524D 64K",
+  W_EMPTY: "\u672A\u89E3\u6790\u5230\u4EFB\u4F55\u7248\u672C\u8282\uFF0C\u9762\u677F\u5C06\u663E\u793A\u4E2D\u6027\u63D0\u793A"
+};
+function isMaybeBreakingMisuse(bulletBody) {
+  try {
+    if (typeof bulletBody !== "string") return false;
+    const t = stripBreakingDecorations(bulletBody);
+    if (!t) return false;
+    if (isBreakingChangelogItem(bulletBody)) return false;
+    if (/^breaking\s*$/i.test(t)) return true;
+    if (/^breaking\s+[^:：]/i.test(t)) return true;
+    if (/^breaking[^:：\s\w]/i.test(t)) return true;
+    if (/^不兼容\s*$/i.test(t)) return true;
+    if (/^不兼容\s*[^:：]/i.test(t)) return true;
+    if (/^(braking|breking|breakign|brekaing|braeking|breakingg)\b/i.test(t)) return true;
+    if (/^break[^i:：\s]/i.test(t)) return true;
+    return false;
+  } catch {
+    return false;
+  }
+}
+function validateChangelog(markdown) {
+  try {
+    if (typeof markdown !== "string" || !markdown.trim()) {
+      return { ok: true, diagnostics: [{ line: 1, code: "W_EMPTY", hint: CHANGELOG_VALIDATE_HINTS.W_EMPTY }] };
+    }
+    let raw = String(markdown).replace(/\r\n/g, String.fromCharCode(10));
+    let fileTruncated = false;
+    if (raw.length > CHANGELOG_MAX_CHARS) {
+      fileTruncated = true;
+      raw = raw.slice(0, CHANGELOG_MAX_CHARS);
+    }
+    const lines = raw.split(String.fromCharCode(10));
+    const diags = [];
+    let inFence = false;
+    let curValid = false;
+    let curCat = null;
+    let catLineByCat = {};
+    let countByCat = {};
+    let hasVisibleVersion = false;
+    const flushCounts = function() {
+      try {
+        for (const k of Object.keys(countByCat)) {
+          const n = countByCat[k];
+          if (n > CHANGELOG_MAX_BULLETS_PER_SECTION) {
+            const lineNo = catLineByCat[k] ? catLineByCat[k] : lines.length;
+            const hint = "\u5206\u7C7B " + k + " \u5171 " + String(n) + " \u6761\uFF0C\u4EC5\u663E\u793A\u524D " + String(CHANGELOG_MAX_BULLETS_PER_SECTION) + " \u6761";
+            diags.push({ line: lineNo, code: "W_TRUNCATED", hint });
+          }
+        }
+      } catch {
+      }
+    };
+    for (let i = 0; i < lines.length; i++) {
+      const lineNo = i + 1;
+      const line = String(lines[i] !== void 0 && lines[i] !== null ? lines[i] : "");
+      if (isFenceToggle(line)) {
+        inFence = !inFence;
+        continue;
+      }
+      if (inFence) continue;
+      const vTitle = matchVersionHeading(line);
+      if (vTitle !== null) {
+        flushCounts();
+        catLineByCat = {};
+        countByCat = {};
+        curValid = false;
+        curCat = null;
+        const info = extractVersionDateAndYanked(vTitle);
+        if (!info.version) {
+          diags.push({ line: lineNo, code: "E_VERSION_TITLE", hint: CHANGELOG_VALIDATE_HINTS.E_VERSION_TITLE });
+          continue;
+        }
+        if (isUnreleasedVersion(info.version)) {
+          curValid = false;
+          continue;
+        }
+        curValid = true;
+        hasVisibleVersion = true;
+        if (info.yanked) {
+          diags.push({ line: lineNo, code: "W_YANKED", hint: CHANGELOG_VALIDATE_HINTS.W_YANKED });
+        }
+        continue;
+      }
+      const cTitle = matchCategoryHeading(line);
+      if (cTitle !== null) {
+        const cat = normalizeCategory(cTitle);
+        if (!cat) {
+          curCat = null;
+          diags.push({ line: lineNo, code: "E_CATEGORY", hint: CHANGELOG_VALIDATE_HINTS.E_CATEGORY });
+          continue;
+        }
+        if (!curValid) {
+          curCat = null;
+          continue;
+        }
+        curCat = cat;
+        catLineByCat[cat] = lineNo;
+        if (countByCat[cat] === void 0) countByCat[cat] = 0;
+        continue;
+      }
+      const body = matchBulletBody(line);
+      if (body !== null) {
+        if (!curValid || !curCat) {
+          diags.push({ line: lineNo, code: "E_BULLET_ORPHAN", hint: CHANGELOG_VALIDATE_HINTS.E_BULLET_ORPHAN });
+          continue;
+        }
+        countByCat[curCat] = (countByCat[curCat] ? countByCat[curCat] : 0) + 1;
+        if (isMaybeBreakingMisuse(body)) {
+          diags.push({ line: lineNo, code: "W_BREAKING_MAYBE", hint: CHANGELOG_VALIDATE_HINTS.W_BREAKING_MAYBE });
+        }
+        continue;
+      }
+    }
+    flushCounts();
+    if (fileTruncated) {
+      diags.push({ line: lines.length, code: "W_TRUNCATED_FILE", hint: CHANGELOG_VALIDATE_HINTS.W_TRUNCATED_FILE });
+    }
+    if (!hasVisibleVersion) {
+      let anyVisible = false;
+      try {
+        const parsed = parseChangelog(markdown);
+        for (const e of parsed) {
+          if (e && !isUnreleasedVersion(e.version) && hasVisibleSections(e)) {
+            anyVisible = true;
+            break;
+          }
+        }
+      } catch {
+        anyVisible = false;
+      }
+      if (!anyVisible) {
+        diags.push({ line: lines.length, code: "W_EMPTY", hint: CHANGELOG_VALIDATE_HINTS.W_EMPTY });
+      }
+    }
+    diags.sort(function(a, b) {
+      return a.line - b.line;
+    });
+    let ok = true;
+    for (const d of diags) {
+      if (d.code.charAt(0) === "E") {
+        ok = false;
+        break;
+      }
+    }
+    return { ok, diagnostics: diags };
+  } catch {
+    return { ok: false, diagnostics: [] };
+  }
+}
 export {
+  BREAKING_BADGE_TEXT,
   CHANGELOG_ALL_CATEGORIES,
   CHANGELOG_CATEGORY_ZH,
   CHANGELOG_FILENAME,
@@ -276,12 +629,36 @@ export {
   CHANGELOG_MUST_SHOW,
   CHANGELOG_NEUTRAL_HINT,
   CHANGELOG_NEUTRAL_LINE,
+  CHANGELOG_POLL_BACKOFF_MS,
+  CHANGELOG_VALIDATE_HINTS,
+  RE_BULLET,
+  RE_CATEGORY_HEADING,
+  RE_FENCE_TOGGLE,
+  RE_UNRELEASED,
+  RE_VERSION_DATE,
+  RE_VERSION_HEADING,
+  RE_VERSION_NUM,
+  RE_YANKED,
   changelogForUpdate,
+  countsOf,
   hasVisibleSections,
+  isBreakingChangelogItem,
+  isFenceToggle,
+  isMaybeBreakingMisuse,
   isUnreleasedVersion,
+  matchBulletBody,
+  matchCategoryHeading,
+  matchVersionHeading,
   parseChangelog,
   renderChangelogHTML,
+  renderChangelogItem,
   renderChangelogNeutral,
   renderChangelogSection,
-  selectChangelogEntries
+  selectChangelogEntries,
+  shouldFetchChangelog,
+  splitBreakingPrefix,
+  stripBreakingDecorations,
+  truncatedNoteHTML,
+  validateChangelog,
+  yankedBannerHTML
 };

package/dist/entry.d.ts

@@ -5,7 +5,11 @@ export type EntryVariant = 'button' | 'badge' | 'inline';
 /** 什么时候主动查一次（只读，联网一次）。 */
 export type EntryAutoCheck = 'mount' | 'never';
 /** 用户点下去之后做什么。 */
-export type EntryOpenOn = 'has-update' | 'always' | 'manual';
+/**
+ * 点下去之后做什么：`has-update` 有新版才开面板（无事只给一句小字）；`always` 检查完总是开；
+ * `manual` 交给 onActivate；`direct` 点开即弹窗、不预查（面板挂载即自查；badge 仍走回调口径）。
+ */
+export type EntryOpenOn = 'has-update' | 'always' | 'manual' | 'direct';
 /** 入口件主题（与面板同一套取值，切换即换肤）。 */
 export type EntryTheme = UpdatePanelTheme;
 /** 入口件的状态档：只用来算文案与 data-state，不另立状态机。 */

package/dist/entry.js

@@ -64,10 +64,15 @@ const UPDATE_ENTRY_CSS = [
   '.dsh-upd-entry[data-state="update"] .dsh-upd-entry-dot{background:var(--dsh-upd-ok-line,#059669)}',
   '.dsh-upd-entry[data-state="busy"] .dsh-upd-entry-dot,.dsh-upd-entry[data-state="restart"] .dsh-upd-entry-dot{background:var(--dsh-upd-warn-line,#d97706)}',
   '.dsh-upd-entry[data-state="failed"] .dsh-upd-entry-dot{background:var(--dsh-upd-bad-line,#dc2626)}',
-  ".dsh-upd-entry-note{font-size:12.5px;opacity:.75}",
-  '.dsh-upd-entry[data-theme="d5-paper"]{font-family:Georgia,"Songti SC","STSong","SimSun",serif;color:#1a1a1a}',
-  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-btn{border-color:#c4b896;background:transparent;border-radius:3px}',
-  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-btn:hover{border-color:#c8402a;color:#c8402a}',
+  // 小字自带底（深色宿主 + 浅色变量时也读得出；浅底宿主上只是多一圈细线，不抢戏）。
+  ".dsh-upd-entry-note{font-size:12.5px;opacity:.9;background:var(--dsh-upd-bg,#ffffff);border:1px solid var(--dsh-upd-line,#e5e7eb);border-radius:4px;padding:1px 8px}",
+  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-note{background:var(--d5-card);border-color:var(--d5-line-strong);color:var(--d5-ink)}',
+  '.dsh-upd-entry[data-theme="d5-paper"]{--d5-ink:#1a1a1a;--d5-muted:#6f675a;--d5-line-strong:#c4b896;--d5-accent:#c8402a;--d5-card:#fffdf6;',
+  'font-family:Georgia,"Songti SC","STSong","SimSun",serif;color:var(--d5-ink)}',
+  // 按钮脸自己不透明（深色宿主 + 浅色系统变量时也读得出；hover 红在深浅底上都可见）。
+  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-btn{border-color:var(--d5-line-strong);background:var(--d5-card);color:var(--d5-ink);border-radius:3px}',
+  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-btn:hover{border-color:var(--d5-accent);color:var(--d5-accent)}',
+  '@media (prefers-color-scheme: dark){.dsh-upd-entry[data-theme="d5-paper"]{--d5-ink:#ece5d3;--d5-muted:#a89c83;--d5-line-strong:#5c4e3b;--d5-accent:#e0684e;--d5-card:#1e1a15}}',
   "@media (prefers-color-scheme: dark){.dsh-upd-entry{color:#e5e7eb}",
   ".dsh-upd-entry-btn{--dsh-upd-btn:#1f2937;--dsh-upd-line:#374151}}"
 ].join("\n");
@@ -111,8 +116,8 @@ function mountUpdateEntry(container, options) {
     throw new Error(`[dsh-plugin-update] \u81EA\u52A8\u68C0\u67E5\u65F6\u673A\u975E\u6CD5\uFF1A\u53EA\u6536 mount \u6216 never\uFF08\u6536\u5230 ${JSON.stringify(options.autoCheck)}\uFF09`);
   }
   const openOn = options.openOn ?? "has-update";
-  if (openOn !== "has-update" && openOn !== "always" && openOn !== "manual") {
-    throw new Error(`[dsh-plugin-update] \u70B9\u51FB\u53BB\u5411\u975E\u6CD5\uFF1A\u53EA\u6536 has-update / always / manual\uFF08\u6536\u5230 ${JSON.stringify(options.openOn)}\uFF09`);
+  if (openOn !== "has-update" && openOn !== "always" && openOn !== "manual" && openOn !== "direct") {
+    throw new Error(`[dsh-plugin-update] \u70B9\u51FB\u53BB\u5411\u975E\u6CD5\uFF1A\u53EA\u6536 has-update / always / manual / direct\uFF08\u6536\u5230 ${JSON.stringify(options.openOn)}\uFF09`);
   }
   if (options.theme !== void 0 && options.theme !== "default" && options.theme !== "archive" && options.theme !== "d5-paper") {
     throw new Error(`[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 archive\uFF08d5-paper \u4E3A\u65E7\u522B\u540D\u4ECD\u53EF\u7528\uFF09\uFF08\u6536\u5230 ${JSON.stringify(options.theme)}\uFF09`);
@@ -248,6 +253,10 @@ function mountUpdateEntry(container, options) {
   }
   async function activate() {
     if (!mounted || panelMode !== null || activating) return;
+    if (openOn === "direct" && variant === "button") {
+      openDialog();
+      return;
+    }
     activating = true;
     note = null;
     render();
@@ -288,7 +297,6 @@ function mountUpdateEntry(container, options) {
         void activate();
         return;
       }
-      if (panelMode === "dialog" && closest('[data-action="close-view"]')) close();
     } catch {
     }
   }

package/dist/host.d.ts

@@ -10,8 +10,8 @@ export { COPY_BUDGET_CHARS, DETAIL_MAX_CHARS, DIAG_DROP_ORDER, DIAG_INLINE_BUDGE
 export type { DiagDropKey, RedactionRuleName } from './redaction.js';
 export { DIAG_ACTIONS, DIAG_KEYS, DIAG_KNOWN_TYPES, DIAG_STAGE_EXPECT, DIAG_STAGES, DIAG_VERSION, buildDiag, deriveAction, deriveRouteMethod, deriveStage, enforceBudget as enforceDiagBudgetForPhone, } from './diag.js';
 export type { DiagAction, DiagInput, DiagObject, DiagStage } from './diag.js';
-export { CHANGELOG_ALL_CATEGORIES, CHANGELOG_FILENAME, CHANGELOG_FOLDED, CHANGELOG_MAX_BULLETS_PER_SECTION, CHANGELOG_MAX_BULLET_CHARS, CHANGELOG_MAX_CHARS, CHANGELOG_MAX_ENTRIES, CHANGELOG_MUST_SHOW, CHANGELOG_NEUTRAL_HINT, CHANGELOG_NEUTRAL_LINE, changelogForUpdate, hasVisibleSections, isUnreleasedVersion, parseChangelog, renderChangelogHTML, renderChangelogNeutral, renderChangelogSection, selectChangelogEntries, } from './changelog.js';
-export type { ChangelogCategory, ChangelogEntry } from './changelog.js';
+export { CHANGELOG_ALL_CATEGORIES, CHANGELOG_FILENAME, CHANGELOG_FOLDED, CHANGELOG_MAX_BULLETS_PER_SECTION, CHANGELOG_MAX_BULLET_CHARS, CHANGELOG_MAX_CHARS, CHANGELOG_MAX_ENTRIES, CHANGELOG_MUST_SHOW, CHANGELOG_NEUTRAL_HINT, CHANGELOG_NEUTRAL_LINE, BREAKING_BADGE_TEXT, CHANGELOG_POLL_BACKOFF_MS, changelogForUpdate, countsOf, hasVisibleSections, isBreakingChangelogItem, isUnreleasedVersion, parseChangelog, renderChangelogHTML, renderChangelogItem, renderChangelogNeutral, renderChangelogSection, selectChangelogEntries, shouldFetchChangelog, splitBreakingPrefix, truncatedNoteHTML, validateChangelog, yankedBannerHTML, } from './changelog.js';
+export type { ChangelogCategory, ChangelogDiagnostic, ChangelogEntry, ChangelogValidation } from './changelog.js';
 export { CHANGELOG_DEFAULT_REGISTRY, CHANGELOG_FETCH_MAX_BYTES, CHANGELOG_TAR_MAX_BYTES, CHANGELOG_TARBALL_MAX_BYTES, extractChangelogFromTar, fetchReleaseChangelogText, readInstalledChangelogText, } from './changelog-io.js';
 export type { ReleaseChangelogRef } from './changelog-io.js';
 export { createUpdateDiskPorts, createUpdateExecutor, pathsForUpdate, resolveCliEntry } from './store.js';

package/dist/host.js

@@ -11,6 +11,7 @@ import {
 } from "./config.js";
 import { manualCommand } from "./commands.js";
 import { fetchReleaseChangelogText } from "./changelog-io.js";
+import { shouldFetchChangelog } from "./changelog.js";
 import { buildDiag } from "./diag.js";
 import { fetchNpmVersionRelease, isVersionAllowedInChannel, updateError, validReleaseVersion, validRequestId } from "./service.js";
 import { createUpdateDiskPorts, createUpdateExecutor, createUpdateQueuePorts } from "./store.js";
@@ -73,14 +74,24 @@ import {
   CHANGELOG_MUST_SHOW,
   CHANGELOG_NEUTRAL_HINT,
   CHANGELOG_NEUTRAL_LINE,
+  BREAKING_BADGE_TEXT,
+  CHANGELOG_POLL_BACKOFF_MS,
   changelogForUpdate,
+  countsOf,
   hasVisibleSections,
+  isBreakingChangelogItem,
   isUnreleasedVersion,
   parseChangelog,
   renderChangelogHTML,
+  renderChangelogItem,
   renderChangelogNeutral,
   renderChangelogSection,
-  selectChangelogEntries
+  selectChangelogEntries,
+  shouldFetchChangelog as shouldFetchChangelog2,
+  splitBreakingPrefix,
+  truncatedNoteHTML,
+  validateChangelog,
+  yankedBannerHTML
 } from "./changelog.js";
 import {
   CHANGELOG_DEFAULT_REGISTRY,
@@ -578,12 +589,24 @@ function createHostUpdate(deps = {}, configInput) {
   const readerOverrides = { ...deps.readerOverrides ?? {}, ctx, ...deps.pluginManager ? { pluginManager: deps.pluginManager } : {} };
   const phoneNames = buildPhoneNames(config.prefix);
   const changelogCache = /* @__PURE__ */ new Map();
+  const changelogFailedAt = /* @__PURE__ */ new Map();
   async function readChangelog(args) {
     const raw = args ? args["version"] : void 0;
     if (!validReleaseVersion(raw)) throw updateError("invalid-release");
     const version = raw;
     if (!isVersionAllowedInChannel(version, config.releaseChannel)) throw updateError("invalid-release");
     if (changelogCache.has(version)) return { version, markdown: changelogCache.get(version) ?? null };
+    try {
+      let nowMs = 0;
+      try {
+        nowMs = Date.now();
+      } catch {
+        nowMs = 0;
+      }
+      const failedAt = changelogFailedAt.has(version) ? changelogFailedAt.get(version) : null;
+      void shouldFetchChangelog({ hasCache: false, failedAt, now: nowMs, isManual: true });
+    } catch {
+    }
     const fetchImpl = readerOverrides.fetchImpl ?? globalThis.fetch;
     const release = await fetchNpmVersionRelease(fetchImpl, config.checkTimeoutMs, {
       targetPackageName: config.targetPackageName,
@@ -591,12 +614,29 @@ function createHostUpdate(deps = {}, configInput) {
       releaseChannel: config.releaseChannel,
       version
     });
-    const markdown = await fetchReleaseChangelogText(
-      fetchImpl,
-      { tarball: release.tarball, integrity: release.integrity, version },
-      { targetPackageName: config.targetPackageName, registryUrl: config.registryUrl, timeoutMs: config.checkTimeoutMs }
-    );
+    let markdown;
+    try {
+      markdown = await fetchReleaseChangelogText(
+        fetchImpl,
+        { tarball: release.tarball, integrity: release.integrity, version },
+        { targetPackageName: config.targetPackageName, registryUrl: config.registryUrl, timeoutMs: config.checkTimeoutMs }
+      );
+    } catch (err) {
+      try {
+        changelogFailedAt.set(version, Date.now());
+      } catch {
+        try {
+          changelogFailedAt.set(version, 0);
+        } catch {
+        }
+      }
+      throw err;
+    }
     changelogCache.set(version, markdown);
+    try {
+      changelogFailedAt.delete(version);
+    } catch {
+    }
     return { version, markdown };
   }
   async function readStatus(args) {
@@ -713,6 +753,7 @@ function __resetSharedUpdateReaderForTests() {
   sharedDesktopPnpm = null;
 }
 export {
+  BREAKING_BADGE_TEXT,
   CHANGELOG_ALL_CATEGORIES,
   CHANGELOG_DEFAULT_REGISTRY,
   CHANGELOG_FETCH_MAX_BYTES,
@@ -725,6 +766,7 @@ export {
   CHANGELOG_MUST_SHOW,
   CHANGELOG_NEUTRAL_HINT,
   CHANGELOG_NEUTRAL_LINE,
+  CHANGELOG_POLL_BACKOFF_MS,
   CHANGELOG_TARBALL_MAX_BYTES,
   CHANGELOG_TAR_MAX_BYTES,
   COPY_BUDGET_CHARS,
@@ -764,6 +806,7 @@ export {
   compareReleaseVersions,
   compareVersions,
   containingPackage,
+  countsOf,
   createHostUpdate,
   createSkipDiskPorts,
   createUpdateDiskPorts2 as createUpdateDiskPorts,
@@ -782,6 +825,7 @@ export {
   extractChangelogFromTar,
   fetchReleaseChangelogText2 as fetchReleaseChangelogText,
   hasVisibleSections,
+  isBreakingChangelogItem,
   isHeadOfQueue2 as isHeadOfQueue,
   isPrereleaseVersion,
   isUnreleasedVersion,
@@ -800,6 +844,7 @@ export {
   registrySpec,
   releaseOwnerInQueue2 as releaseOwnerInQueue,
   renderChangelogHTML,
+  renderChangelogItem,
   renderChangelogNeutral,
   renderChangelogSection,
   resolveCliEntry,
@@ -810,9 +855,14 @@ export {
   sanitizeForCopy,
   selectChangelogEntries,
   setOwnerIfFree2 as setOwnerIfFree,
+  shouldFetchChangelog2 as shouldFetchChangelog,
   skipKey,
+  splitBreakingPrefix,
   truncateToWordBoundary,
+  truncatedNoteHTML,
   validReleaseVersion2 as validReleaseVersion,
   validVersion,
-  visibleQueueFor2 as visibleQueueFor
+  validateChangelog,
+  visibleQueueFor2 as visibleQueueFor,
+  yankedBannerHTML
 };

package/dist/panel-batch.js

@@ -1,6 +1,7 @@
 // AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/panel-batch.ts
 import { assertPrefix, MIN_PANEL_POLL_MS } from "./config.js";
 import { validReleaseVersion } from "./service.js";
+import { shouldFetchChangelog } from "./changelog.js";
 import {
   isTerminalPhase,
   normalizeBatchSession
@@ -631,7 +632,7 @@ function mountUpdateBatchPanel(container, options) {
   const autoChangelogEnabled = options.autoChangelog !== false;
   const rowChangelog = /* @__PURE__ */ new Map();
   const rowInflight = /* @__PURE__ */ new Set();
-  const rowFailed = /* @__PURE__ */ new Map();
+  const rowFailedAt = /* @__PURE__ */ new Map();
   let rowAutoSeq = 0;
   let rows = [];
   let expandedKey = null;
@@ -672,7 +673,19 @@ function mountUpdateBatchPanel(container, options) {
     const cached = rowChangelog.get(key);
     if (cached && cached.version === version) return;
     if (rowInflight.has(key)) return;
-    if (rowFailed.get(key) === version) return;
+    try {
+      const failKey = key + "\0" + version;
+      const hasCache = false;
+      const failedAt = rowFailedAt.has(failKey) ? rowFailedAt.get(failKey) : null;
+      let nowMs = 0;
+      try {
+        nowMs = Date.now();
+      } catch {
+        nowMs = 0;
+      }
+      if (!shouldFetchChangelog({ hasCache, failedAt, now: nowMs, isManual: false })) return;
+    } catch {
+    }
     const phone2 = changelogPhoneOf(row);
     if (!phone2) return;
     rowInflight.add(key);
@@ -682,7 +695,14 @@ function mountUpdateBatchPanel(container, options) {
         rowInflight.delete(key);
         if (!mounted || seq !== rowAutoSeq) return;
         if (!isObject(reply) || reply["ok"] !== true) {
-          rowFailed.set(key, version);
+          try {
+            rowFailedAt.set(key + "\0" + version, Date.now());
+          } catch {
+            try {
+              rowFailedAt.set(key + "\0" + version, 0);
+            } catch {
+            }
+          }
           return;
         }
         const md = reply["markdown"];
@@ -691,7 +711,16 @@ function mountUpdateBatchPanel(container, options) {
       },
       () => {
         rowInflight.delete(key);
-        if (mounted && seq === rowAutoSeq) rowFailed.set(key, version);
+        if (mounted && seq === rowAutoSeq) {
+          try {
+            rowFailedAt.set(key + "\0" + version, Date.now());
+          } catch {
+            try {
+              rowFailedAt.set(key + "\0" + version, 0);
+            } catch {
+            }
+          }
+        }
       }
     );
   }
@@ -808,7 +837,7 @@ function mountUpdateBatchPanel(container, options) {
         return;
       }
       applyReply(reply);
-      rowFailed.clear();
+      rowFailedAt.clear();
     } catch {
       if (!mounted) return;
       lastError = "check-failed";

package/dist/panel.d.ts

@@ -2,7 +2,7 @@ import { type VisibleQueue } from './queue.js';
 import type { BlockedReason, UpdateSnapshot } from './ports.js';
 /** 摆放形态：默认内嵌，切弹窗走同一参数。 */
 export type UpdatePanelMode = 'embedded' | 'dialog';
-/** 面板主题：默认最小可用样式；`d5-paper` 为可选 D5 档案卷专业主题（只换肤，不换 DOM 顺序）。 */
+/** 面板主题：默认最小可用样式；`archive` 为档案卷纸面浅色（只换肤，不换 DOM 顺序；`d5-paper` 为旧别名）。 */
 /**
  * 面板主题：`default` 最小可用深色；`archive` 档案卷纸面浅色（原型敲定的案卷风格，只换肤）。
  * `d5-paper` 是 archive 的旧别名（历史取值），仍可用，渲染逐字相同。
@@ -26,7 +26,7 @@ export interface UpdatePanelOptions {
     prefix?: string;
     /** 摆放形态：默认内嵌。 */
     mode?: UpdatePanelMode;
-    /** 面板主题：默认 `default`（最小可用样式，一字不动）；传 `d5-paper` 切 D5 档案卷可选主题。 */
+    /** 面板主题：默认 `default`（最小可用样式，一字不动）；传 `archive` 切档案卷（`d5-paper` 为旧别名）。 */
     theme?: UpdatePanelTheme;
     /** 是否看他人排队明细：默认只看自己的（他人仅露正忙占位，位置照给）。 */
     showOthers?: boolean;

package/dist/panel.js

@@ -5,7 +5,9 @@ import { validReleaseVersion } from "./service.js";
 import {
   changelogForUpdate,
   parseChangelog,
-  renderChangelogHTML
+  renderChangelogHTML,
+  shouldFetchChangelog,
+  yankedBannerHTML
 } from "./changelog.js";
 function normalizePanelTheme(value) {
   return value === "d5-paper" || value === "archive" ? "d5-paper" : "default";
@@ -516,6 +518,12 @@ const UPDATE_PANEL_CSS = [
   ".dsh-upd-changelog li{margin:2px 0}",
   ".dsh-upd-changelog-fold{margin:4px 0}",
   ".dsh-upd-changelog-fold>summary{cursor:pointer}",
+  ".dsh-upd-changelog-count{font-size:12px;opacity:.7;margin:2px 0 4px}",
+  ".dsh-upd-changelog-yanked{border-left:4px solid var(--dsh-upd-warn-line,#d97706);background:var(--dsh-upd-warn-bg,#fffbeb);padding:6px 10px;margin:6px 0;font-size:13px}",
+  ".dsh-upd-breaking-badge{display:inline-block;font-size:11px;font-weight:700;border:1px solid currentColor;border-radius:3px;padding:0 5px;margin-right:6px;vertical-align:baseline}",
+  ".dsh-upd-changelog-security-more{margin:4px 0 6px}",
+  ".dsh-upd-changelog-security-more>summary{cursor:pointer;font-size:12px;opacity:.8}",
+  ".dsh-upd-changelog-more-note{font-size:12px;opacity:.7;margin:2px 0 4px}",
   ".dsh-upd-changelog-neutral{color:inherit;opacity:.8}",
   ".dsh-upd-overlay{position:fixed;inset:0;background:rgba(0,0,0,.35);display:flex;align-items:center;justify-content:center;z-index:9999}",
   ".dsh-upd-overlay .dsh-upd{background:var(--dsh-upd-bg,#ffffff);max-height:85vh;overflow:auto}",
@@ -593,7 +601,8 @@ const UPDATE_PANEL_D5_CSS = [
   "--d5-shadow:0 1px 2px rgba(60,40,20,.08),0 12px 32px rgba(60,40,20,.10);",
   "font-family:var(--d5-sans);color:var(--d5-ink);background:var(--d5-card);",
   "border:1px solid var(--d5-line-strong);border-radius:4px;box-shadow:var(--d5-shadow)}",
-  '.dsh-upd[data-theme="d5-paper"] button{border-color:var(--d5-line-strong);background:transparent;color:var(--d5-ink);border-radius:3px;font-family:var(--d5-sans)}',
+  // 按钮脸自己不透明（宿主底色未知时也读得出；卡片上渲染与 transparent 逐字同色）。
+  '.dsh-upd[data-theme="d5-paper"] button{border-color:var(--d5-line-strong);background:var(--d5-card);color:var(--d5-ink);border-radius:3px;font-family:var(--d5-sans)}',
   '.dsh-upd[data-theme="d5-paper"] button:hover:not(:disabled){border-color:var(--d5-accent);color:var(--d5-accent)}',
   '.dsh-upd[data-theme="d5-paper"] button[data-primary="1"]{background:var(--d5-accent);border-color:var(--d5-accent);color:#fff}',
   '.dsh-upd[data-theme="d5-paper"] button[data-primary="1"]:hover:not(:disabled){background:var(--d5-accent-deep);color:#fff}',
@@ -604,6 +613,10 @@ const UPDATE_PANEL_D5_CSS = [
   '.dsh-upd[data-theme="d5-paper"] .dsh-upd-banner[data-kind="restart"]{border-color:var(--d5-warn);background:var(--d5-warn-bg);font-family:var(--d5-serif);border-width:2px}',
   '.dsh-upd[data-theme="d5-paper"] .dsh-upd-banner[data-kind="failed"],.dsh-upd[data-theme="d5-paper"] .dsh-upd-banner[data-kind="blocked"]{border-color:var(--d5-bad);background:var(--d5-bad-bg)}',
   '.dsh-upd[data-theme="d5-paper"] .dsh-upd-banner[data-kind="done"]{border-color:var(--d5-ok);background:var(--d5-ok-bg)}',
+  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-changelog-yanked{border-color:var(--d5-warn);background:var(--d5-warn-bg);color:var(--d5-ink)}',
+  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-breaking-badge{color:var(--d5-accent);border-color:var(--d5-accent)}',
+  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-changelog-count{color:var(--d5-muted)}',
+  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-changelog-more-note{color:var(--d5-muted)}',
   // —— 大印章（原型 :206 `.seal`：右上 88px、旋转 -7°、双细框；内容与色调来自根属性，不加节点）——
   '.dsh-upd[data-theme="d5-paper"]{position:relative;padding:22px 26px 20px}',
   '.dsh-upd[data-theme="d5-paper"]::before{content:attr(data-seal);position:absolute;top:20px;right:24px;width:88px;height:88px;',
@@ -791,7 +804,22 @@ function renderUpdatePanelKernel(input, view) {
         const fromText = String(snapshot.runningVersion ?? "");
         const toText = String(snapshot.latestVersion ?? "");
         const rangeTitle = fromText && toText ? `\u66F4\u65B0\u8BF4\u660E\uFF08${fromText} \u2192 ${toText}\uFF09\uFF1A` : "\u66F4\u65B0\u8BF4\u660E\uFF1A";
-        inner = `<div class="dsh-upd-changelog-wrap"><div>${escapeHtml(rangeTitle)}</div>
+        let yankedBanner = "";
+        try {
+          const toEntry = Array.isArray(ranged) ? ranged.find(function(e) {
+            try {
+              return e && e.version === toText;
+            } catch {
+              return false;
+            }
+          }) : null;
+          if (toEntry && toEntry.yanked === true && toText) {
+            yankedBanner = yankedBannerHTML(toText);
+          }
+        } catch {
+          yankedBanner = "";
+        }
+        inner = `<div class="dsh-upd-changelog-wrap"><div>${escapeHtml(rangeTitle)}</div>${yankedBanner}
 ${changelogHTML}
 </div>`;
       } catch {
@@ -951,7 +979,7 @@ function mountUpdatePanel(container, options) {
   let manualChangelogOverride = typeof options.changelogMarkdown === "string";
   const changelogCache = /* @__PURE__ */ new Map();
   const changelogInflight = /* @__PURE__ */ new Set();
-  const changelogFailed = /* @__PURE__ */ new Set();
+  const changelogFailedAt = /* @__PURE__ */ new Map();
   let autoSeq = 0;
   const pollMs = options.pollMs === void 0 ? DEFAULT_PANEL_POLL_MS : options.pollMs;
   if (typeof pollMs !== "number" || !Number.isFinite(pollMs) || pollMs < MIN_PANEL_POLL_MS) {
@@ -1069,7 +1097,16 @@ function mountUpdatePanel(container, options) {
       if (skipStore.has(v)) return null;
     } catch {
     }
-    if (changelogCache.has(v) || changelogInflight.has(v) || changelogFailed.has(v)) return null;
+    if (changelogInflight.has(v)) return null;
+    const hasCache = changelogCache.has(v);
+    const failedAt = changelogFailedAt.has(v) ? changelogFailedAt.get(v) : null;
+    let nowMs = 0;
+    try {
+      nowMs = Date.now();
+    } catch {
+      nowMs = 0;
+    }
+    if (!shouldFetchChangelog({ hasCache, failedAt, now: nowMs, isManual: false })) return null;
     return v;
   }
   function maybeAutoChangelog() {
@@ -1082,7 +1119,14 @@ function mountUpdatePanel(container, options) {
         changelogInflight.delete(v);
         if (!mounted || seq !== autoSeq) return;
         if (!reply || typeof reply !== "object" || reply["ok"] !== true) {
-          changelogFailed.add(v);
+          try {
+            changelogFailedAt.set(v, Date.now());
+          } catch {
+            try {
+              changelogFailedAt.set(v, 0);
+            } catch {
+            }
+          }
           return;
         }
         const md = reply["markdown"];
@@ -1094,7 +1138,16 @@ function mountUpdatePanel(container, options) {
       },
       () => {
         changelogInflight.delete(v);
-        if (mounted && seq === autoSeq) changelogFailed.add(v);
+        if (mounted && seq === autoSeq) {
+          try {
+            changelogFailedAt.set(v, Date.now());
+          } catch {
+            try {
+              changelogFailedAt.set(v, 0);
+            } catch {
+            }
+          }
+        }
       }
     );
   }
@@ -1126,7 +1179,7 @@ function mountUpdatePanel(container, options) {
           const reply = await call(phoneNames.updateCheck, queueArgs());
           if (!mounted) return;
           applyStatusReply(reply);
-          changelogFailed.clear();
+          changelogFailedAt.clear();
         } catch {
           if (!mounted) return;
           lastError = "check-failed";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-update",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "可复用的更新系统装成的 npm 包：任何 DSH 插件照文档能集成检查更新等功能（地图 #579）",
   "license": "MIT",
   "author": "王辰浩",