dsh-plugin-update 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 格式为 Keep-a-Changelog 子集：`Added/Fixed/Changed` 必写，`Deprecated/Removed/Security` 有则透传，`Unreleased` 面板忽略，禁止 git-log 直倒。面板缺日志时中性提示，不挡安装。
 
+## [0.5.5] - 2026-10-06
+
+### Added
+- 档案卷主题收敛 archive 与面板紧凑化：运行时 data-theme 统一为 archive（d5-paper 仅作输入旧别名归一），entry/entry-batch/panel-batch 输出与 CSS 选择器同步，panel-batch setTheme 补 archive 并归一存储；根／卷头／横幅／版本条／章节／章头／队列行／footer 间距收紧；删 changelog-wrap 与章节线重影内边框；页脚去技术词，批量关闭 title 同步。
+- 双语底座 #54（先行）：bilingual 字典模块、entry key 映射链、noteVersion 运行时值；research/52-inventory 双语盘点与原型矩阵随附。
+
+### Fixed
+- 安装/查失败常驻与复制诊断锁定（#58）：失败横幅保留到下一次用户主动查/装的新结论、任务态或版本变化，只读轮询不再洗回可装页；「复制诊断」锁定致命那次回包（稳定码、摘要、版本、宿主、请求与检查编号冻结在失败时刻）；失败旁新增「知道了」可显式确认回到可装页；健康无失败时复制改为当前状态快照，不再伪造失败码；04 章失败时变为卷宗（真实稳定码、本次查询键与失败时刻、证据冻结声明、凭编号对日志的现成查询，平时为路牌＋中性行，可用 `showLogHint: false` 藏路牌）；日志事件名收归 `log-events.ts` 单源（宿主发射与面板路牌同源）；对抗审查补强：瞬态读失败不跨重挂、查锁存不再错配旧安装编号、瞬态失败换诚实文案、跨挂载表有界 100 家；`update-busy` 仍为瞬态不锁存；四电话形状与快照六字段零变更。
+
+## [0.5.4] - 2026-10-06
+
+### Added
+- 批量感知入口件（#49）：新子路径 `dsh-plugin-update/entry-batch`，一颗按钮看 N 家聚合（button/badge/inline；openOn 缺省 always，autoCheck 缺省 mount；只调 batchStatus/batchCheck，绝不自动装；聚合与批量总账同一份数法，忙失败占位翻回可更新）。
+- 批量 dialog 关闭落地与单面板同口径（#50）：`BatchPanelOptions` 新增可选 `onCloseRequested`，点关闭/Esc 先交调用方撤 DOM 再停轮询；入口件打开的 dialog 已内置；不传回退只停轮询；HTTP 直挂透传。
+
 ## [0.5.3] - 2026-10-06
 
 ### Added

package/README.md

@@ -131,7 +131,7 @@ const panel = mountUpdatePanel(document.getElementById('update-slot'), {
 // 弹窗版想让「关闭」按钮真把弹窗撤掉：传 onCloseRequested（面板点关闭/Esc 时先调它撤 DOM，再停轮询；入口件打开的 dialog 已内置）。
 ```
 
-组件内部消化的事（调用者不再写）：按 `panelPollMs` 轮询查状态（下限 250 毫秒）；安装按钮状态跟随快照的 `canInstall`，不另写门控规则；装不了的原因按第 5.2 节展示中文一句话；`pending-restart` 单独横幅加重启指引，不再给安装按钮；手工命令展示与复制；排队位置展示与 `showOthers` 开关；跳过按版本记（“已跳过 X.Y.Z · 恢复”在同一行，不藏进设置页）；失败时旁边的“复制诊断”一键给出脱敏后的自包含文本（稳定码、版本、宿主、队列位置），深挖仍看日志（组件里留着第 6 节第 11 条的过滤口径）。
+组件内部消化的事（调用者不再写）：按 `panelPollMs` 轮询查状态（下限 250 毫秒）；安装按钮状态跟随快照的 `canInstall`，不另写门控规则；装不了的原因按第 5.2 节展示中文一句话；`pending-restart` 单独横幅加重启指引，不再给安装按钮；手工命令展示与复制；排队位置展示与 `showOthers` 开关；跳过按版本记（“已跳过 X.Y.Z · 恢复”在同一行，不藏进设置页）；失败时旁边的“复制诊断”一键给出脱敏后的自包含文本（稳定码、版本、宿主、队列位置），深挖仍看日志（组件里留着第 6 节第 11 条的过滤口径）。失败横幅常驻：查/装失败后保留到下一次用户主动查/装的新结论、任务态或版本变化，只读轮询不再洗掉；复制诊断锁定致命那次回包的证据（码、摘要、版本、宿主、编号冻结在失败时刻）；失败旁有「知道了」可显式确认回到可装页（只清面板提示，不调电话）。无失败时复制诊断给当前状态快照（版本、宿主、范围、队列），不伪造失败码。04 章平时是路牌（中性行＋日志过滤口径，可用 `showLogHint: false` 隐藏）；失败时变为卷宗：真实稳定码、本次查询键（请求／检查编号＋失败时刻）、证据冻结声明、凭编号对日志的现成查询。日志事件名（`host.call`／`host.call.fail`／`update.install.exec`）由宿主与面板共用单源，改名即全改。
 
 待重启横幅上有个「重启宿主」入口。宿主没有“重启自己”的电话，所以默认点击只如实提示「请手动重启宿主」；想把重启流程接进来就传 `onRestartRequested`（面板调它，成败都回执）：
 
@@ -195,6 +195,27 @@ mountUpdateEntry(el, { pluginId: 'p', prefix: 'notes', call, variant: 'badge',
   onActivate: ({ hasUpdate, latestVersion }) => { /* 自己跳自己的页面 */ } })
 ```
 
+#### 批量感知的入口件（一颗按钮看 N 家，点开即批量面板）
+
+一个总管替 N 家管更新时，别再用单入口的 `manual` 桥接批量面板——徽标只反映总管自己一行，不是七家聚合。换这一颗：
+
+```js
+import { mountUpdateBatchEntry } from 'dsh-plugin-update/entry-batch'
+
+const entry = mountUpdateBatchEntry(document.getElementById('upd-entry'), {
+  prefix: 'life',                              // 批量电话前缀（五个批量电话从它派生）
+  call: (name, args) => host.call(name, args),
+  theme: 'archive',                            // 与单入口/面板同一套皮肤
+})
+// 点击先调 `life.batchCheck` 查一次 N 家，再以 dialog 形态开批量面板；徽标即七家聚合。
+// 下游删掉 `openOn: 'manual' + onActivate` 桥接即跑，总管单行不再当状态源。
+```
+
+聚合口径与批量面板总账同一份数法（含「忙失败占位翻回可更新」）：`忙 > 失败 > 待重启 > 可更新 > 待查`，
+文案为 `检查更新` / `N 家可更新` / `正在安装…` / `N 家待重启` / `N 家失败，点此查看`。
+三自由度与单入口同取值，缺省不同：`openOn` 缺省 `'always'`（查完总是开批量面板；`has-update` 下有事才开，否则原地给总账一句）。
+`autoCheck` 缺省 `'mount'`（只调 `.batchStatus`，只读）；铁律同单入口：任何路径都不自动安装。
+
 ### 第 2.6 节：多目标批量更新（一个插件管 N 个插件的更新）
 
 一个插件替自己**和另外几个插件**管更新时，别把 N 个面板并排——用户在那块界面上只问三件事：
@@ -239,6 +260,7 @@ const panel = mountUpdateBatchPanel(el, {
   theme: 'archive',          // 与单插件面板同一套皮肤（archive = 档案卷，旧值 d5-paper 仍可用）
 })
 ```
+// 弹窗版与单面板同口径：传 `onCloseRequested`（点关闭/Esc 时先调它撤 DOM，再停轮询；入口件打开的 dialog 已内置；不传即只停轮询）。
 
 批量面板 HTTP 版（无 `host.call` 环境即跑：同一传输内核，五电话走同一映射，取消走 `batchCancel`）：
 

package/dist/bilingual.d.ts

@@ -0,0 +1,39 @@
+/** 字典版本钉（#53 Q3 解耦）：key 冻即解阻塞 #54，文案按词标 draft/locked；开发钉此版本，转正只换文案不换 key。 */
+export declare const BILINGUAL_DICT_VERSION = "2026-10-06-pin53";
+/** 首批 key 全集（entry 7 键，命名沿 #52 §1 key 提案，area.group.name）。 */
+export type BilingualKey = 'entry.label.idle' | 'entry.label.failed' | 'entry.label.busy' | 'entry.label.restart' | 'entry.label.has-update' | 'entry.action.checking' | 'entry.note.up-to-date';
+/** 一条双语：en/zh 模板 + 成熟度。模板内具名槽如 {version}，运行时值填入（值永不翻译）。 */
+export interface BilingualEntry {
+    en: string;
+    zh: string;
+    /** true=待母语+域内双签（#53 Q3），false=已双签转正。首批全 draft（无评审不假锁）。 */
+    draft: boolean;
+}
+/**
+ * 集中字典（机器源，类型锁死：Record<BilingualKey, BilingualEntry> 缺键即 tsc 报错）。
+ * 人读源为 #57 规格 + #53 结论英文定调；英文终稿待母语评审，故全标 draft。
+ * zh 逐字等于 entry.ts 现有散落文案（兼容既有测试与接入方 label() 口径）。
+ */
+export declare const BILINGUAL_STRINGS: Record<BilingualKey, BilingualEntry>;
+/** 取一条双语原文（类型锁死：未知 key 在 tsc 即拦；运行时未知亦抛，不静默回退）。 */
+export declare function bilingualEntry(key: BilingualKey): BilingualEntry;
+/**
+ * 纯文本双语（一行，英文在前中文在后，空白分隔）：用于 title / aria-label 等放不下 HTML 的属性位。
+ * 返回原文（未转义），调用方按上下文转义后再拼入属性。
+ */
+export declare function bilingualText(key: BilingualKey, values?: Record<string, unknown>): string;
+/**
+ * 双语语义块 HTML（唯一渲染出口）：英文在前中文在后，空白分隔，lang 属性齐全。
+ * 返回已转义可直接拼入 innerHTML 的片段；调用方不得再对整体转义，不得拆 span 重组。
+ */
+export declare function bilingualHTML(key: BilingualKey, values?: Record<string, unknown>): string;
+/** 是否 draft（供 #56 门禁读零 draft 放行条件；#54 自身不断言零 draft）。 */
+export declare function isDraft(key: BilingualKey): boolean;
+/** 全表 draft key 一览（#56 门禁：空数组才放行合入主分支）。 */
+export declare function draftKeys(): BilingualKey[];
+/**
+ * 双语块最小样式（与 UPDATE_ENTRY_CSS 同缝注入）：
+ * 平时行内双语（英文前中文后，空白分隔），窄处竖排不断行（@media 360px 以下 column）。
+ * 只管排版，不管字重字号（字重间距留给 #55 视觉矩阵验收）。
+ */
+export declare const BILINGUAL_CSS: string;

package/dist/bilingual.js

@@ -0,0 +1,58 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/bilingual.ts
+const BILINGUAL_DICT_VERSION = "2026-10-06-pin53";
+const BILINGUAL_STRINGS = {
+  "entry.label.idle": { en: "Check for updates", zh: "\u68C0\u67E5\u66F4\u65B0", draft: true },
+  "entry.label.failed": { en: "Update failed \u2014 View details", zh: "\u66F4\u65B0\u5931\u8D25\uFF0C\u70B9\u6B64\u67E5\u770B", draft: true },
+  "entry.label.busy": { en: "Installing\u2026", zh: "\u6B63\u5728\u5B89\u88C5\u2026", draft: true },
+  "entry.label.restart": { en: "Restart required", zh: "\u5F85\u91CD\u542F", draft: true },
+  "entry.label.has-update": { en: "Update available {version}", zh: "\u6709\u65B0\u7248 {version}", draft: true },
+  "entry.action.checking": { en: "Checking for updates\u2026", zh: "\u6B63\u5728\u67E5\u65B0\u7248\u2026", draft: true },
+  "entry.note.up-to-date": { en: "Up to date {version}", zh: "\u5DF2\u662F\u6700\u65B0 {version}", draft: true }
+};
+function escapeHtml(value) {
+  return String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function formatTemplate(template, values) {
+  const vals = values ?? {};
+  return String(template).replace(/\{([A-Za-z0-9_]+)\}/g, (_, name) => {
+    const v = vals[name];
+    if (v === null || v === void 0) return "";
+    return String(v).trim();
+  });
+}
+function bilingualEntry(key) {
+  const hit = BILINGUAL_STRINGS[key];
+  if (!hit) throw new Error("[dsh-plugin-update] \u672A\u77E5\u6587\u6848 key\uFF1A" + String(key));
+  return hit;
+}
+function bilingualText(key, values) {
+  const e = bilingualEntry(key);
+  return formatTemplate(e.en, values) + " " + formatTemplate(e.zh, values);
+}
+function bilingualHTML(key, values) {
+  const e = bilingualEntry(key);
+  const en = escapeHtml(formatTemplate(e.en, values));
+  const zh = escapeHtml(formatTemplate(e.zh, values));
+  return '<span class="dsh-upd-bi"><span lang="en">' + en + '</span> <span lang="zh">' + zh + "</span></span>";
+}
+function isDraft(key) {
+  return bilingualEntry(key).draft;
+}
+function draftKeys() {
+  return Object.keys(BILINGUAL_STRINGS).filter((k) => BILINGUAL_STRINGS[k].draft);
+}
+const BILINGUAL_CSS = [
+  ".dsh-upd-bi{display:inline-flex;align-items:baseline;gap:.5em;max-width:100%}",
+  '.dsh-upd-bi [lang="en"],.dsh-upd-bi [lang="zh"]{overflow-wrap:anywhere}',
+  "@media (max-width:360px){.dsh-upd-bi{flex-direction:column;gap:0}}"
+].join("\n");
+export {
+  BILINGUAL_CSS,
+  BILINGUAL_DICT_VERSION,
+  BILINGUAL_STRINGS,
+  bilingualEntry,
+  bilingualHTML,
+  bilingualText,
+  draftKeys,
+  isDraft
+};

package/dist/entry-batch.d.ts

@@ -0,0 +1,92 @@
+import { type BatchRowView } from './panel-batch.js';
+import { type UpdatePanelTheme } from './panel.js';
+/** 批量入口件的形态（与单入口同一套取值）。 */
+export type BatchEntryVariant = 'button' | 'badge' | 'inline';
+/** 什么时候主动查一次（只读；与单入口同一口径）。 */
+export type BatchEntryAutoCheck = 'mount' | 'never';
+/**
+ * 用户点下去之后做什么（与单入口同一套取值，缺省不同：批量缺省 'always'）。
+ * 单入口缺省 'has-update'（有新版才开单面板）；批量入口缺省 'always'（查完总是开批量面板——
+ * 批量面板的总账本身就是答案，空着也值得看一眼；下游删 manual 桥接即按此缺省跑）。
+ * 'has-update' 下只有聚合档非 idle 才开面板（忙/失败/待重启/可更新都算有事），否则原地给总账一句。
+ */
+export type BatchEntryOpenOn = 'has-update' | 'always' | 'manual' | 'direct';
+/** 批量入口件的状态档：只用来算文案与 data-state，不另立状态机。 */
+export type BatchEntryStateKind = 'idle' | 'update' | 'busy' | 'restart' | 'failed';
+/** 算文案要的全部输入：批量七行 + 最近一次批量电话的失败稳定码（没查过、没失败为 null）。 */
+export interface UpdateBatchEntryState {
+    rows: readonly BatchRowView[] | null;
+    error: string | null;
+}
+/** 聚合后的读数（onActivate 与测试共用同一份，不各算一份）。 */
+export interface BatchEntrySummary {
+    kind: BatchEntryStateKind;
+    label: string;
+    updatable: number;
+    installing: number;
+    pending: number;
+    restart: number;
+    failed: number;
+    skipped: number;
+    settled: number;
+    total: number;
+    hasUpdate: boolean;
+}
+export interface UpdateBatchEntryOptions {
+    /** 批量电话前缀（与宿主侧一致，例 'life'）。 */
+    prefix: string;
+    /** 调宿主电话：(phoneName, args) => Promise<reply>。 */
+    call: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    variant?: BatchEntryVariant;
+    /** 主题：与单入口/面板同一套（default/archive，d5-paper 为旧别名仍可用）。 */
+    theme?: UpdatePanelTheme;
+    /** 缺省 'mount'：进页面静默查一次（只调 .batchStatus，只读）。'never' 则只在用户点击时查。 */
+    autoCheck?: BatchEntryAutoCheck;
+    /** 缺省 'always'：查完总是开批量面板（见本类型说明）。 */
+    openOn?: BatchEntryOpenOn;
+    /** 覆盖默认按钮文案（不传就用聚合文案）。 */
+    label?: string;
+    /** 可选：键 -> 中文名覆盖（透传给批量面板）。 */
+    titles?: Record<string, string>;
+    /** 轮询间隔（毫秒，透传给批量面板；缺省 1500，下限 250）。 */
+    pollMs?: number;
+    /**
+     * 详情行自动取日志（透传给批量面板，缺省开）。
+     * 展开行有新版时调该行自己的更新日志电话按需取；false 关闭。
+     */
+    autoChangelog?: boolean;
+    /** 「重启宿主」的落地（透传给批量面板）：不传就只提示手动重启，不假装能重启。 */
+    onRestartRequested?: () => void | Promise<void>;
+    /** 复制文本的出口（透传给批量面板）：不传即试浏览器剪贴板，都没有也不抛错。 */
+    copyText?: (text: string) => void | Promise<void>;
+    /** variant='badge' 或 openOn='manual' 时，点击交给接入方（自己跳自己的页面）。 */
+    onActivate?: (state: BatchEntrySummary) => void;
+}
+export interface UpdateBatchEntryController {
+    /** 立刻查一次并把状态刷到界面上（只读：调 .batchStatus）。 */
+    refresh(): Promise<void>;
+    /** 打开批量面板（dialog 形态）。 */
+    open(): void;
+    /** 关掉批量面板。 */
+    close(): void;
+    /** 当前按钮上的聚合文案（接入方做自定义排版时读它）。 */
+    label(): string;
+    /** 当前聚合读数（含七档计数，接入方排版与 onActivate 共用）。 */
+    summary(): BatchEntrySummary;
+    setTheme(theme: UpdatePanelTheme): void;
+    unmount(): void;
+}
+/**
+ * 聚合读数：计数唯一出处 batchLedgerCounts（与面板总账同一份，忙失败占位翻回可更新）。
+ * hasUpdate = 忙/失败/待重启/可更新任一非零（openOn has-update 按它开面板；全 settled/待查/跳过即 idle）。
+ */
+export declare function batchEntrySummary(state: UpdateBatchEntryState | null | undefined): BatchEntrySummary;
+/** 状态档（唯一出处：batchEntrySummary，不各写一份）。 */
+export declare function batchEntryStateKind(state: UpdateBatchEntryState | null | undefined): BatchEntryStateKind;
+/** 批量入口件文案（唯一出处：测试与接入方都读它，不各写一份）。 */
+export declare function batchEntryLabelFor(state: UpdateBatchEntryState | null | undefined): string;
+export declare function mountUpdateBatchEntry(container: {
+    innerHTML: string;
+    addEventListener?: (type: string, listener: (ev: unknown) => void) => void;
+    removeEventListener?: (type: string, listener: (ev: unknown) => void) => void;
+}, options: UpdateBatchEntryOptions): UpdateBatchEntryController;

package/dist/entry-batch.js

@@ -0,0 +1,355 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/entry-batch.ts
+import { MIN_PANEL_POLL_MS } from "./config.js";
+import { UPDATE_ENTRY_CSS } from "./entry.js";
+import {
+  batchLedgerCounts,
+  batchLedgerText,
+  buildBatchPhoneNames,
+  mountUpdateBatchPanel
+} from "./panel-batch.js";
+import {
+  failureCodeOf,
+  normalizePanelTheme
+} from "./panel.js";
+const LABEL_IDLE = "\u68C0\u67E5\u66F4\u65B0";
+const LABEL_BUSY = "\u6B63\u5728\u5B89\u88C5\u2026";
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function asRows(value) {
+  if (!Array.isArray(value)) return null;
+  return value;
+}
+function escapeHtml(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function batchEntrySummary(state) {
+  const rows = state?.rows ?? null;
+  const counts = batchLedgerCounts(Array.isArray(rows) ? rows : []);
+  const total = Array.isArray(rows) ? rows.length : 0;
+  let kind;
+  if (!Array.isArray(rows) || rows.length === 0) {
+    kind = state?.error ? "failed" : "idle";
+  } else if (counts.installing > 0) {
+    kind = "busy";
+  } else if (counts.failed > 0) {
+    kind = "failed";
+  } else if (counts.restart > 0) {
+    kind = "restart";
+  } else if (counts.updatable > 0) {
+    kind = "update";
+  } else {
+    kind = "idle";
+  }
+  if (kind !== "busy" && state?.error) {
+    if (Array.isArray(rows) && rows.length > 0 && counts.failed === 0 && counts.installing === 0) {
+      kind = "failed";
+    }
+  }
+  const hasUpdate = counts.installing > 0 || counts.failed > 0 || counts.restart > 0 || counts.updatable > 0;
+  let label;
+  switch (kind) {
+    case "busy":
+      label = LABEL_BUSY;
+      break;
+    case "failed":
+      label = counts.failed > 0 ? counts.failed + " \u5BB6\u5931\u8D25\uFF0C\u70B9\u6B64\u67E5\u770B" : "\u66F4\u65B0\u5931\u8D25\uFF0C\u70B9\u6B64\u67E5\u770B";
+      break;
+    case "restart":
+      label = counts.restart + " \u5BB6\u5F85\u91CD\u542F";
+      break;
+    case "update":
+      label = counts.updatable + " \u5BB6\u53EF\u66F4\u65B0";
+      break;
+    default:
+      label = LABEL_IDLE;
+      break;
+  }
+  return {
+    kind,
+    label,
+    updatable: counts.updatable,
+    installing: counts.installing,
+    pending: counts.pending,
+    restart: counts.restart,
+    failed: counts.failed,
+    skipped: counts.skipped,
+    settled: counts.settled,
+    total,
+    hasUpdate
+  };
+}
+function batchEntryStateKind(state) {
+  return batchEntrySummary(state).kind;
+}
+function batchEntryLabelFor(state) {
+  return batchEntrySummary(state).label;
+}
+function mountUpdateBatchEntry(container, options) {
+  if (!container || typeof container.innerHTML !== "string") {
+    throw new Error("[dsh-plugin-update] \u6302\u6279\u91CF\u5165\u53E3\u4EF6\u9700\u8981\u4E00\u4E2A\u6709 innerHTML \u7684\u5BB9\u5668");
+  }
+  if (!options || typeof options !== "object") {
+    throw new Error("[dsh-plugin-update] \u6302\u6279\u91CF\u5165\u53E3\u4EF6\u7F3A\u5C11\u914D\u7F6E\uFF1A\u6279\u91CF\u7535\u8BDD\u524D\u7F00 prefix \u5FC5\u586B");
+  }
+  if (typeof options.call !== "function") {
+    throw new Error("[dsh-plugin-update] \u6302\u6279\u91CF\u5165\u53E3\u4EF6\u9700\u8981\u4F20\u8F93\u51FD\u6570 call\uFF08\u5165\u53E3\u4EF6\u8C03\u5BBF\u4E3B\u7535\u8BDD\u7684\u552F\u4E00\u63A5\u89E6\u9762\uFF09");
+  }
+  const phones = buildBatchPhoneNames(options.prefix);
+  const variant = options.variant ?? "button";
+  if (variant !== "button" && variant !== "badge" && variant !== "inline") {
+    throw new Error("[dsh-plugin-update] \u5165\u53E3\u4EF6\u5F62\u6001\u975E\u6CD5\uFF1A\u53EA\u6536 button / badge / inline\uFF08\u6536\u5230 " + JSON.stringify(options.variant) + "\uFF09");
+  }
+  const autoCheck = options.autoCheck ?? "mount";
+  if (autoCheck !== "mount" && autoCheck !== "never") {
+    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 ?? "always";
+  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");
+  }
+  let theme = normalizePanelTheme(options.theme ?? "default");
+  const pollMs = options.pollMs;
+  if (pollMs !== void 0 && (typeof pollMs !== "number" || !Number.isFinite(pollMs) || pollMs < MIN_PANEL_POLL_MS)) {
+    throw new Error("[dsh-plugin-update] \u9762\u677F\u8F6E\u8BE2\u95F4\u9694\u975E\u6CD5\uFF1A\u4E0D\u5F97\u5C0F\u4E8E 250 \u6BEB\u79D2\uFF08\u6536\u5230 " + JSON.stringify(options.pollMs) + "\uFF09");
+  }
+  const labelOverride = typeof options.label === "string" && options.label ? options.label : null;
+  const titles = options.titles && typeof options.titles === "object" ? options.titles : {};
+  const onActivate = typeof options.onActivate === "function" ? options.onActivate : null;
+  const call = options.call;
+  const ENTRY_ATTR = "data-dsh-upd-entry";
+  const ENTRY_SELECTOR = "[data-dsh-upd-entry]";
+  let rows = null;
+  let error = null;
+  let note = null;
+  let loaded = false;
+  let activating = false;
+  let mounted = true;
+  let panel = null;
+  let panelMode = null;
+  const panelHost = {
+    get innerHTML() {
+      return container.innerHTML;
+    },
+    set innerHTML(value) {
+      container.innerHTML = value;
+    },
+    addEventListener(type, listener) {
+      ;
+      container.addEventListener?.(type, listener);
+    },
+    removeEventListener(type, listener) {
+      ;
+      container.removeEventListener?.(type, listener);
+    }
+  };
+  async function panelCall(name, args) {
+    const reply = await call(name, args);
+    return isObject(reply) ? reply : {};
+  }
+  function stateOf() {
+    return { rows, error };
+  }
+  function summaryOf() {
+    return batchEntrySummary(stateOf());
+  }
+  function currentLabel() {
+    return labelOverride ?? summaryOf().label;
+  }
+  function phoneArgs() {
+    return {};
+  }
+  function entryHTML() {
+    const summary = summaryOf();
+    const text = activating ? "\u6B63\u5728\u67E5\u65B0\u7248\u2026" : currentLabel();
+    const busyAttr = activating ? ' disabled aria-busy="true"' : "";
+    const themeAttr = theme === "archive" ? ' data-theme="archive"' : "";
+    const control = variant === "badge" ? '<button type="button" class="dsh-upd-entry-dot" ' + ENTRY_ATTR + '="activate" title="' + escapeHtml(text) + '" aria-label="' + escapeHtml(text) + '"' + busyAttr + "></button>" : '<button type="button" class="dsh-upd-entry-btn" ' + ENTRY_ATTR + '="activate"' + busyAttr + ">" + escapeHtml(text) + "</button>";
+    const noteHTML = note ? '<span class="dsh-upd-entry-note" data-dsh-upd-note="1">' + escapeHtml(note) + "</span>" : "";
+    return "<style>" + UPDATE_ENTRY_CSS + '</style>\n<span class="dsh-upd-entry" data-variant="' + variant + '" data-state="' + summary.kind + '"' + themeAttr + ">" + control + noteHTML + "</span>";
+  }
+  function render() {
+    if (!mounted) return;
+    if (panelMode !== null) return;
+    container.innerHTML = entryHTML();
+  }
+  function applyReply(reply) {
+    if (!isObject(reply) || reply["ok"] !== true) {
+      error = failureCodeOf(isObject(reply) ? reply : null, "check-failed");
+      return;
+    }
+    const next = asRows(reply["rows"]);
+    if (next) rows = next;
+    error = null;
+    loaded = true;
+  }
+  async function refresh() {
+    if (!mounted) return;
+    try {
+      const reply = await call(phones.status, phoneArgs());
+      if (!mounted) return;
+      applyReply(reply);
+    } catch {
+      if (!mounted) return;
+      error = "check-failed";
+    }
+    render();
+  }
+  async function checkNow() {
+    try {
+      const reply = await call(phones.check, phoneArgs());
+      if (!mounted) return;
+      applyReply(reply);
+    } catch {
+      if (!mounted) return;
+      error = "check-failed";
+    }
+  }
+  function mountPanel(mode) {
+    if (!mounted || panelMode !== null) return;
+    panel = mountUpdateBatchPanel(panelHost, {
+      prefix: options.prefix,
+      mode,
+      theme,
+      pollMs,
+      titles,
+      onRestartRequested: options.onRestartRequested,
+      copyText: options.copyText,
+      autoChangelog: options.autoChangelog,
+      // 面板点「关闭」即走入口件的完整关闭（收 dialog + 还原按钮 + 重查一次），不再是面板自己停轮询。
+      onCloseRequested: () => close(),
+      call: panelCall
+    });
+    panelMode = mode;
+  }
+  function openDialog() {
+    mountPanel("dialog");
+  }
+  function open() {
+    if (!mounted || panelMode !== null) return;
+    if (variant === "inline") return;
+    openDialog();
+  }
+  function close() {
+    if (!mounted || panelMode !== "dialog" || !panel) return;
+    const opened = panel;
+    panel = null;
+    panelMode = null;
+    try {
+      opened.unmount();
+    } catch {
+    }
+    render();
+    void refresh();
+  }
+  async function activate() {
+    if (!mounted || panelMode !== null || activating) return;
+    if (openOn === "direct" && variant === "button") {
+      openDialog();
+      return;
+    }
+    activating = true;
+    note = null;
+    render();
+    try {
+      await checkNow();
+    } finally {
+      activating = false;
+    }
+    if (!mounted) return;
+    if (variant === "badge" || openOn === "manual") {
+      if (onActivate) onActivate(summaryOf());
+      else openDialog();
+      render();
+      return;
+    }
+    const summary = summaryOf();
+    if (openOn === "always" || summary.hasUpdate || !loaded || error) {
+      openDialog();
+      return;
+    }
+    note = batchLedgerText({
+      updatable: summary.updatable,
+      installing: summary.installing,
+      pending: summary.pending,
+      restart: summary.restart,
+      failed: summary.failed,
+      skipped: summary.skipped,
+      settled: summary.settled
+    });
+    render();
+  }
+  function setTheme(next) {
+    if (next !== "default" && next !== "archive" && next !== "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(next) + "\uFF09");
+    }
+    theme = normalizePanelTheme(next);
+    if (panel) void panel.setTheme(theme);
+    else render();
+  }
+  function onClick(ev) {
+    if (!mounted) return;
+    try {
+      const target = ev?.target;
+      const closest = target && typeof target.closest === "function" ? target.closest.bind(target) : null;
+      if (!closest) return;
+      if (closest(ENTRY_SELECTOR)) {
+        void activate();
+        return;
+      }
+    } catch {
+    }
+  }
+  function onKeyDown(ev) {
+    try {
+      const e = ev;
+      if (!mounted || panelMode !== "dialog" || !e || e.key !== "Escape") return;
+      close();
+    } catch {
+    }
+  }
+  function unmount() {
+    if (!mounted) return;
+    mounted = false;
+    const opened = panel;
+    panel = null;
+    panelMode = null;
+    try {
+      opened?.unmount();
+    } catch {
+    }
+    try {
+      ;
+      container.removeEventListener?.("click", onClick);
+    } catch {
+    }
+    try {
+      ;
+      container.removeEventListener?.("keydown", onKeyDown);
+    } catch {
+    }
+  }
+  try {
+    ;
+    container.addEventListener?.("click", onClick);
+  } catch {
+  }
+  try {
+    ;
+    container.addEventListener?.("keydown", onKeyDown);
+  } catch {
+  }
+  if (variant === "inline") mountPanel("embedded");
+  else render();
+  if (autoCheck === "mount") void refresh();
+  return { refresh, open, close, label: currentLabel, summary: summaryOf, setTheme, unmount };
+}
+export {
+  batchEntryLabelFor,
+  batchEntryStateKind,
+  batchEntrySummary,
+  mountUpdateBatchEntry
+};

package/dist/entry.d.ts

@@ -1,5 +1,6 @@
 import { type UpdatePanelContainer, type UpdatePanelTheme } from './panel.js';
 import type { UpdateSnapshot } from './ports.js';
+import { type BilingualKey } from './bilingual.js';
 /** 入口件的形态。 */
 export type EntryVariant = 'button' | 'badge' | 'inline';
 /** 什么时候主动查一次（只读，联网一次）。 */
@@ -65,6 +66,17 @@ export interface UpdateEntryController {
  * 待重启是正常终态（不是失败），所以排在失败前面；正在装的任务比一条陈旧的失败码更可信。
  */
 export declare function entryStateKind(state: UpdateEntryState | null | undefined): EntryStateKind;
+/**
+ * 入口件双语 key（#54 底座调用链）：与 entryStateKind 同一输入（快照 + 失败码），分支只认稳定码，永不读文案。
+ * 数据层只传 key + {version} 运行时值，表现层经 bilingualHTML 拼语义块。
+ */
+export declare function entryBilingualKeyFor(state: UpdateEntryState | null | undefined): BilingualKey;
+/** 双语插值（运行时值永不翻译：同一 version 在中英两 span 各出现一次）。 */
+export declare function entryBilingualValuesFor(state: UpdateEntryState | null | undefined): Record<string, string>;
+/** 一路调用链的语义块 HTML（entryHTML 按钮正文唯一来源，无覆盖时必走此函数）。 */
+export declare function entryBilingualHTMLFor(state: UpdateEntryState | null | undefined): string;
+/** 属性位纯文本双语（title / aria-label 用，放不下 HTML 时的同内容平面版）。 */
+export declare function entryBilingualTextFor(state: UpdateEntryState | null | undefined): string;
 /** 入口件文案（唯一出处：测试与接入方都读它，不各写一份）。 */
 export declare function entryLabelFor(state: UpdateEntryState | null | undefined): string;
 export declare const UPDATE_ENTRY_CSS: string;