dsh-plugin-update 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 格式为 Keep-a-Changelog 子集：`Added/Fixed/Changed` 必写，`Deprecated/Removed/Security` 有则透传，`Unreleased` 面板忽略，禁止 git-log 直倒。面板缺日志时中性提示，不挡安装。
 
+## [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
+- 进入面板自动查一次新版（#46 结论固化 #48）：首绘 loading 后先只读本地刷新，拿到活体快照后条件自动查一次；轮询心跳永远只读本地、不触发查新版；抑制谓词 `pendingAutoCheck` 为纯函数，仅快照任务态 installing/verifying 或已有查/装在途时不发起，同范围忙/凭证过期/各类阻拦一律不抑制，无活体快照不发起；复用手动查同一通路与“正在查新版…”提示；并发只信服务端真相源（面板 busyAct 互斥 + checking 在途复用 + 2s 复用窗口），卸载靠 mounted 丢弃；失败无退避，只渲染既有失败文案与复制诊断，手动查清日志退避、关闭重开立即重问；embedded/dialog 一致；pollMs 不影响时机；四电话形状与快照六字段零变更。
+- 关闭按钮住右下角独立 footer 区（#47 定案 A）：第一章 actions 不再画 close-view，内核末尾 05 章之后新增 `.dsh-upd-footer`（dialog + 非只读渲染才有），按钮原 title/data-action 原样搬入；embedded 无面板自带关闭（宿主框架自带关）；默认 + D5 只换肤、DOM 同序；act/Esc/onCloseRequested 语义一字未动。
+
+### Changed
+- 入口件 direct 断言收紧：区分入口自身空参预查与面板挂载带 includeQueue 自查（面板挂载即自查归面板）。
+- 面板安装复用断言更新：mount 自动查已拿凭证时安装直接复用，不另查（无 receipt 回退见 panel-auto-check 用例）。
+- 测试：新增 tests/panel-auto-check.test.mjs 11 项（纯函数、正常/抑制/阻拦仍查、慢网单发、卸载丢弃、手动重问、轮询不查、失败无退避、安装复用凭证），tests/panel-close-footer-47.test.mjs 5 项随前一提交；全量 637 计、636 过、0 败、1 跳（既有 derive-client 跳过）。
+
 ## [0.5.2] - 2026-10-06
 
 ### Added

package/README.md

@@ -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/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 === "d5-paper" ? ' data-theme="d5-paper"' : "";
+    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/host.js

@@ -532,7 +532,40 @@ function loggedPhone(method, kind, pluginId, fn, diagCtx) {
       } catch {
         diag = void 0;
       }
-      return { ok: false, ...payload, ...diag ? { diag } : {} };
+      let failReader = null;
+      try {
+        const failConfig = diagCtx?.config;
+        const failOverrides = diagCtx?.readerOverrides ?? {};
+        if (failConfig && (wantsEnv(safeArgs) || queueArgsOf(safeArgs).includeQueue)) {
+          failReader = await getSharedReader(pluginId, failConfig, {
+            ...failOverrides,
+            profileDir: safeArgs && safeArgs.profileDir ? String(safeArgs.profileDir) : failOverrides.profileDir
+          });
+        }
+      } catch {
+        failReader = null;
+      }
+      let envPatch = {};
+      try {
+        if (failReader && wantsEnv(safeArgs)) {
+          const env = await readEnvForPanel(failReader);
+          if (env) envPatch = { env };
+        }
+      } catch {
+        envPatch = {};
+      }
+      let queuePatch = {};
+      try {
+        const { includeQueue, showOthers } = queueArgsOf(safeArgs);
+        if (failReader && includeQueue) {
+          const requestIdForQueue = safeArgs && typeof safeArgs.requestId === "string" ? String(safeArgs.requestId) : void 0;
+          const q = visibleQueueFor(await failReader.readQueuePruned(), pluginId, showOthers, requestIdForQueue);
+          if (q) queuePatch = { queue: q };
+        }
+      } catch {
+        queuePatch = {};
+      }
+      return { ok: false, ...payload, ...diag ? { diag } : {}, ...envPatch, ...queuePatch };
     }
   };
 }

package/dist/panel-batch.d.ts

@@ -49,6 +49,11 @@ export interface BatchPanelOptions {
      * 老宿主没给行电话名即回中性提示；false 关闭。
      */
     autoChangelog?: boolean;
+    /**
+     * 弹窗关闭的落地（与单插件面板同一口径）：只在 dialog 下点「关闭」/按 Esc 时调用；调用方在此撤掉弹窗 DOM。
+     * 不传则回退为只停轮询（unmount），DOM 留给调用方处理。入口件打开的 dialog 已内置（收 dialog + 还原按钮）。
+     */
+    onCloseRequested?: () => void | Promise<void>;
 }
 /** 面板可点的动作（HTML 上 data-act 一一对应；测试走同一条路）。 */
 export type BatchPanelActionKind = 'check' | 'install' | 'resume' | 'cancel' | 'row-install' | 'row-skip' | 'row-resume-skip' | 'row-cancel-queue' | 'row-copy-manual' | 'row-copy-diag' | 'toggle-details' | 'restart' | 'close';

package/dist/panel-batch.js

@@ -627,6 +627,7 @@ function mountUpdateBatchPanel(container, options) {
   const call = options.call;
   const titles = options.titles && typeof options.titles === "object" ? options.titles : {};
   const onRestartRequested = options.onRestartRequested;
+  const onCloseRequested = typeof options.onCloseRequested === "function" ? options.onCloseRequested : null;
   const copyText = options.copyText ?? defaultCopyText;
   const skipStores = /* @__PURE__ */ new Map();
   const autoChangelogEnabled = options.autoChangelog !== false;
@@ -968,18 +969,28 @@ function mountUpdateBatchPanel(container, options) {
         return;
       }
       case "close": {
-        if (mode === "dialog") unmount();
+        await requestDialogClose();
         return;
       }
       default:
         return;
     }
   }
+  async function requestDialogClose() {
+    if (!mounted || mode !== "dialog") return;
+    if (onCloseRequested) {
+      try {
+        await onCloseRequested();
+      } catch {
+      }
+    }
+    unmount();
+  }
   function onKeyDown(ev) {
     try {
       const e = ev;
       if (!mounted || mode !== "dialog" || !e || e.key !== "Escape") return;
-      unmount();
+      void requestDialogClose();
     } catch {
     }
   }

package/dist/panel.d.ts

@@ -139,7 +139,7 @@ export interface PanelDiagnosticInput {
     installedVersion?: string | null;
     latestVersion?: string | null;
     hostKind?: string | null;
-    /** 使用范围名：装到哪个 profile 是排错第一信息；不传则那一段不出现（输出与旧版一字不差）。 */
+    /** 使用范围名：装到哪个 profile 是排错第一信息；旧复制不传则该段不出现，新复制块恒显（缺省为未知）。 */
     profileName?: string | null;
     queuePosition?: number | null;
     requestId?: string | null;
@@ -182,7 +182,7 @@ export interface UpdateDiagCopyInput extends PanelDiagnosticInput {
  * 组出 [update-diag] 复制块（双形态同序；调用方直接拿去粘工单/issue，已脱敏）。
  * 第一性：顺序码→摘要→来源（#18 定），怎么办是面板页脚放最后，不插断三元组；
  * 缺省即省略（#18）：路由/请求/检查/阶段等缺失即不出现，不占位“未知”；
- * 插件/版本/宿主/队列恒显（面板侧显式值兜底），摘要缺省给人话，源缺省给人话（省略本身即信息，人读不懂所以必须说）。
+ * 插件/版本/宿主/使用范围/队列恒显（面板侧显式值兜底），摘要缺省给人话，源缺省给人话（省略本身即信息，人读不懂所以必须说）。
  */
 export declare function buildUpdateDiagCopy(input: UpdateDiagCopyInput): string;
 export declare function createMemorySkipStore(now?: () => number): PanelSkipStore;
@@ -257,6 +257,13 @@ export interface PanelRenderInput extends PanelViewInput {
 export declare function renderUpdatePanelKernel(input: PanelRenderInput, view: PanelView): string;
 /** 整面板 HTML（含样式；重绘即整体替换 innerHTML，故每次都带 style 也只留一份）。 */
 export declare function renderUpdatePanelHTML(input: PanelRenderInput): string;
+/**
+ * mount 自动查抑制谓词（#48：#46 结论固化，纯函数）：
+ * 仅当快照任务态为 installing/verifying，或已有查/装在途动作时不发起；
+ * 同范围忙、凭证过期、各类阻拦一律不抑制（前两者正是要刷新/重建凭证时）。
+ * 无活体快照（null）也不发起：首个只读刷新没拿到快照时不猜。
+ */
+export declare function pendingAutoCheck(snapshot: UpdateSnapshot | null, busyAct: 'check' | 'install' | null): boolean;
 /**
  * 挂载整组件（面板侧一行即跑）：
  * ```js

package/dist/panel.js

@@ -206,6 +206,7 @@ function buildUpdateDiagCopy(input) {
   const checkRaw = diag.checkId ?? input.checkId;
   const queue = queueTextOf(input.queuePosition ?? null);
   const prov = [`\u63D2\u4EF6=${pluginName}`, `\u7248\u672C=${runVer}\u2192${instVer}`, `\u5BBF\u4E3B=${host}`];
+  prov.push(`\u4F7F\u7528\u8303\u56F4=${pickText(input.profileName, "\u672A\u77E5")}`);
   if (typeof routeRaw === "string" && routeRaw.trim()) prov.push(`\u8DEF\u7531=${routeRaw.trim()}`);
   if (diag.stage) prov.push(`\u9636\u6BB5=${diag.stage}`);
   if (diag.method) prov.push(`\u65B9\u6CD5=${diag.method}`);
@@ -541,6 +542,10 @@ const UPDATE_PANEL_CSS = [
   ".dsh-upd-strip-k{display:block;font-size:11px;letter-spacing:.14em;opacity:.7}",
   ".dsh-upd-strip-v{font-family:Consolas,Menlo,monospace;font-size:12.5px}",
   ".dsh-upd-chapter{margin-top:14px;padding-top:10px;border-top:1px solid var(--dsh-upd-line,#e5e7eb)}",
+  // 右下角独立 footer 区（#47 定案 A）：与第一章 actions 脱钩，右对齐，一次找到。
+  ".dsh-upd-footer{display:flex;align-items:center;justify-content:flex-end;gap:10px;margin-top:14px;padding-top:10px;border-top:1px solid var(--dsh-upd-line,#e5e7eb)}",
+  ".dsh-upd-foot-note{margin-right:auto;font-size:12px;opacity:.7}",
+  ".dsh-upd-footer button{margin:0}",
   ".dsh-upd-chap-head{display:flex;align-items:baseline;gap:10px;margin-bottom:6px}",
   ".dsh-upd-chap-no{font-size:13px;font-style:italic;opacity:.6}",
   ".dsh-upd-chap-title{font-size:14px;margin:0}",
@@ -665,6 +670,9 @@ const UPDATE_PANEL_D5_CSS = [
   'background:url("data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27 width=%2720%27 height=%2720%27 viewBox=%270 0 24 24%27 fill=%27none%27 stroke=%27%238a5a00%27 stroke-width=%272%27 stroke-linecap=%27round%27 stroke-linejoin=%27round%27%3E%3Cpath d=%27M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0z%27/%3E%3Cline x1=%2712%27 y1=%279%27 x2=%2712%27 y2=%2713%27/%3E%3Cline x1=%2712%27 y1=%2717%27 x2=%2712.01%27 y2=%2717%27/%3E%3C/svg%3E") no-repeat center/20px 20px}',
   '.dsh-upd[data-theme="d5-paper"] .dsh-upd-banner>div:first-child{overflow:hidden;text-overflow:ellipsis}',
   '.dsh-upd[data-theme="d5-paper"] .dsh-upd-actions{flex-wrap:wrap}',
+  // footer 只换肤（#47 定案 A + D5 约束：不换 DOM 顺序；复制诊断永不隐藏，本串不动它）。
+  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-footer{margin-top:26px;padding-top:16px;border-top:1px solid var(--d5-line)}',
+  '.dsh-upd[data-theme="d5-paper"] .dsh-upd-foot-note{color:var(--d5-muted)}',
   // —— 档案头（原型 :208-211 `.filehead`：serif 插件名 22px + 使用范围 + profile 牌；右侧留章位）——
   '.dsh-upd[data-theme="d5-paper"] .dsh-upd-head{display:flex;gap:16px;align-items:baseline;flex-wrap:wrap;padding-right:120px}',
   '.dsh-upd[data-theme="d5-paper"] .dsh-upd-name{font-family:var(--d5-serif);font-size:22px;font-weight:700}',
@@ -776,9 +784,6 @@ function renderUpdatePanelKernel(input, view) {
     if (snapshot) {
       actions.push(`<button type="button" data-action="copy-diag" title="\u590D\u5236\u5DF2\u8131\u654F\u8BCA\u65AD\uFF0C\u76F4\u63A5\u7C98\u7ED9\u63D2\u4EF6\u4F5C\u8005">\u590D\u5236\u8BCA\u65AD</button>`);
     }
-    if (mode === "dialog") {
-      actions.push(`<button type="button" data-action="close-view" title="\u5173\u95ED\u9762\u677F\uFF08\u5B89\u88C5\u5728\u5BBF\u4E3B\u4FA7\u7EE7\u7EED\u8DD1\uFF0C\u53EF\u91CD\u5F00\u6062\u590D\u663E\u793A\uFF09">\u5173\u95ED</button>`);
-    }
     actions.push("</div>");
   }
   actions.push(progressBar(snapshot));
@@ -889,6 +894,11 @@ ${changelogHTML}
       view.showManual && manual ? `<div class="dsh-upd-manual"><div>\u624B\u5DE5\u515C\u5E95\u547D\u4EE4\uFF08\u590D\u5236\u6574\u884C\u6267\u884C\uFF09\uFF1A</div><code>${escapeHtml(manual)}</code></div>` : `<div class="dsh-upd-manual"><div class="dsh-upd-changelog-neutral">\u5F53\u524D\u6CA1\u6709\u53EF\u7528\u7684\u624B\u5DE5\u547D\u4EE4\uFF08\u8BA4\u4E0D\u51FA\u4F7F\u7528\u8303\u56F4\u6216\u5C5E\u6E90\u7801\u5B89\u88C5\u65F6\u4E0D\u7ED9\uFF09\u3002</div></div>`
     )
   );
+  if (showActions && mode === "dialog") {
+    parts.push(
+      `<div class="dsh-upd-footer"><span class="dsh-upd-foot-note">\u5B89\u88C5\u5728\u5BBF\u4E3B\u4FA7\u7EE7\u7EED\u8DD1\uFF0C\u91CD\u5F00\u6062\u590D\u663E\u793A</span><button type="button" data-action="close-view" title="\u5173\u95ED\u9762\u677F\uFF08\u5B89\u88C5\u5728\u5BBF\u4E3B\u4FA7\u7EE7\u7EED\u8DD1\uFF0C\u53EF\u91CD\u5F00\u6062\u590D\u663E\u793A\uFF09">\u5173\u95ED</button></div>`
+    );
+  }
   return parts.join("\n");
 }
 function renderUpdatePanelHTML(input) {
@@ -958,6 +968,13 @@ async function defaultCopyText(text) {
   } catch {
   }
 }
+function pendingAutoCheck(snapshot, busyAct) {
+  if (busyAct === "check" || busyAct === "install") return false;
+  if (!snapshot) return false;
+  const st = snapshot?.job?.state;
+  if (st === "installing" || st === "verifying") return false;
+  return true;
+}
 function mountUpdatePanel(container, options) {
   if (!container || typeof container.innerHTML !== "string") {
     throw new Error("[dsh-plugin-update] \u6302\u8F7D\u9762\u677F\u9700\u8981\u4E00\u4E2A\u6709 innerHTML \u7684\u5BB9\u5668");
@@ -1076,8 +1093,8 @@ function mountUpdatePanel(container, options) {
       if (isObject(env)) {
         const pn = env["profileName"];
         const hk = env["environmentKind"];
-        if (typeof pn === "string" && pn) envProfileName = pn;
-        if (typeof hk === "string" && hk) envHostKind = hk;
+        if (typeof pn === "string" && pn.trim()) envProfileName = pn.trim();
+        if (typeof hk === "string" && hk.trim()) envHostKind = hk.trim();
       }
       lastError = null;
       lastErrorKind = null;
@@ -1086,6 +1103,21 @@ function mountUpdatePanel(container, options) {
       lastError = typeof reply["error"] === "string" ? reply["error"] : "check-failed";
       lastErrorKind = typeof reply["errorKind"] === "string" && reply["errorKind"].trim() ? reply["errorKind"].trim() : null;
       lastDiag = Object.prototype.hasOwnProperty.call(reply, "diag") ? reply["diag"] : null;
+      try {
+        const env = reply["env"];
+        if (isObject(env)) {
+          const pn = env["profileName"];
+          const hk = env["environmentKind"];
+          if (typeof pn === "string" && pn.trim()) envProfileName = pn.trim();
+          if (typeof hk === "string" && hk.trim()) envHostKind = hk.trim();
+        }
+      } catch {
+      }
+      try {
+        const q = asQueue(reply["queue"]);
+        if (q) queue = q;
+      } catch {
+      }
     }
   }
   function pendingAutoChangelogVersion() {
@@ -1278,7 +1310,8 @@ function mountUpdatePanel(container, options) {
           runningVersion: snapshot?.runningVersion ?? null,
           installedVersion: snapshot?.installedVersion ?? null,
           latestVersion: snapshot?.latestVersion ?? null,
-          hostKind,
+          hostKind: hostKind ?? envHostKind,
+          profileName: profileNameOption ?? envProfileName,
           queuePosition: queue?.position ?? null,
           requestId,
           checkId: receipt?.checkId ?? null,
@@ -1410,7 +1443,13 @@ function mountUpdatePanel(container, options) {
     if (h && typeof h.unref === "function") h.unref();
   } catch {
   }
-  void refresh();
+  void (async () => {
+    await refresh();
+    try {
+      if (pendingAutoCheck(snapshot, busyAct)) void act("check");
+    } catch {
+    }
+  })();
   return { refresh, act, setMode, setTheme, setShowOthers, setChangelogMarkdown, unmount };
 }
 import { buildPhoneNames as buildPhoneNames2 } from "./config.js";
@@ -1485,6 +1524,7 @@ export {
   normalizeQueueState,
   panelViewModel,
   parseChangelog2 as parseChangelog,
+  pendingAutoCheck,
   queuePositionOf,
   readDiagTolerant,
   redactForCopy,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-update",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "可复用的更新系统装成的 npm 包：任何 DSH 插件照文档能集成检查更新等功能（地图 #579）",
   "license": "MIT",
   "author": "王辰浩",
@@ -38,6 +38,10 @@
       "types": "./dist/entry.d.ts",
       "default": "./dist/entry.js"
     },
+    "./entry-batch": {
+      "types": "./dist/entry-batch.d.ts",
+      "default": "./dist/entry-batch.js"
+    },
     "./http": {
       "types": "./dist/http.d.ts",
       "default": "./dist/http.js"