dsh-plugin-update 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 格式为 Keep-a-Changelog 子集：`Added/Fixed/Changed` 必写，`Deprecated/Removed/Security` 有则透传，`Unreleased` 面板忽略，禁止 git-log 直倒。面板缺日志时中性提示，不挡安装。
 
+## [0.5.0] - 2026-10-05
+
+### Added
+- 主题首选名 `archive`（档案卷纸面浅色）：`d5-paper` 为旧别名仍可用，渲染逐字相同；入口件与批量面板同一套取值。
+- 弹窗关闭落地 `onCloseRequested`：dialog 下点「关闭」/按 Esc 先交调用方撤 DOM 再停轮询；入口件打开的 dialog 已内置（收 dialog + 还原按钮 + 重查一次）。
+
+### Fixed
+- 弹窗点「关闭」没反应：此前只停轮询不撤 DOM（入口件打开的 dialog 还会卡死），现走关闭落地。
+- 悬停/聚焦闪烁：轮询每秒整树重写 innerHTML 打断 hover/focus，现输出逐字相同时不碰 DOM（状态变化仍即时重绘；单面板与批量面板同口径）。
+
+## [0.4.0] - 2026-10-05
+
+### Added
+- 更新日志无脑接入（#38）：宿主新增 `updateChangelog` 电话（入参版本号，回该版 tarball 内全文，取不到回空；同源 + 精确路径 + `integrity` + 三墙复用，按版本记住结果）；面板 `autoChangelog` 默认自动展示（有新版调一次，显式文本仍赢，`false` 退回手动）；入口件透传跟上；批量详情行按行自动取（无新增批量电话，单行失败只影响该行）；HTTP 版白名单放行，老三电话形状不变。
+- 按钮交互反馈：查新版/安装在途置忙（禁用 + 文案 + `aria-busy` + 纯 CSS 转圈，并发连点只认第一次）；默认主题补 hover / 按下下沉 / 过渡；busy 脉冲与 `prefers-reduced-motion` 关闭。
+- 原生 `title` 说明：单面板全部动作按钮、批量宏按钮带悬停一句话（零成本 tooltip，不引入浮层组件）。
+- Toast 语义：复制/重启类回执 5 秒后自动过期，不靠下次点击才消失。
+- 首帧骨架：快照没到之前版本条画微光占位（`aria-hidden`，不进语义）。
+- 批量「取消这一批」鼠标两步确认（第一次上膛红框，点别的自动卸膛；程序调 `act('cancel')` 仍一次即执行）。
+- Esc 关弹窗：单面板 / 批量面板 dialog 与入口件 dialog 均支持（容器契约内，只用 innerHTML + 事件）。
+
 ## [0.3.1] - 2026-10-05
 
 ### Added

package/README.md

@@ -2,14 +2,14 @@
 
 给 DSH 插件加「检查更新 / 安装更新」能力的 npm 包。宿主侧一段接线，面板侧挂一个现成组件，装不上时给用户一条可复制的手工命令。
 
-要求 Node 22 或更高，零运行时依赖。当前版本 `0.3.1`。
+要求 Node 22 或更高，零运行时依赖。当前版本 `0.5.0`。
 
 装上它你会拿到六样东西：
 
-- **三个电话**：查状态（只读本地）、查新版（用户点了才联网一次）、装更新（拿凭证提交）。电话指宿主对外提供的方法。
+- **四个电话**：查状态（只读本地）、查新版（用户点了才联网一次）、装更新（拿凭证提交）、取日志（按版取更新日志，全文或空）。电话指宿主对外提供的方法。
 - **一套落盘**：任务状态、安装锁、回滚凭据，按「插件标识 + 使用范围」隔离，多插件互不干扰。
 - **面板要的派生取值**：电话名与轮询间隔，构建期从本包生成，面板里不写死。
-- **一个现成整组件**：默认内嵌、可切弹窗，调用者传参指定；轮询、安装门控、中文一句话、待重启横幅、手工命令展示与复制、排队可见开关、跳过与恢复、诊断一键复制全在组件内部消化。
+- **一个现成整组件**：默认内嵌、可切弹窗，调用者传参指定；轮询、安装门控、中文一句话、待重启横幅、手工命令展示与复制、排队可见开关、跳过与恢复、诊断一键复制、**更新日志自动展示**全在组件内部消化。
 - **一个更新入口件**：配置页一行挂上就是「检查更新」按钮（或只给状态点的徽标、或整块内嵌），按钮文案随状态自己变；见第 2.5 节。
 - **一套多目标批量更新**：一个插件管 N 个插件的更新（总账 + 明细 + 动作，一家收尾才起下一家，会话落盘可断点续跑）；见第 2.6 节。
 
@@ -52,7 +52,7 @@ for (const [name, handler] of Object.entries(update.handlers)) {
 }
 ```
 
-这一步得到三个电话名：`notes.updateStatus`、`notes.updateCheck`、`notes.updateInstall`。
+这一步得到四个电话名：`notes.updateStatus`、`notes.updateCheck`、`notes.updateInstall`、`notes.updateChangelog`（取日志：给版本号，回该版 tarball 里的更新日志全文，取不到回空）。
 
 `pluginId` 必填（非空字符串，不含路径分隔符）。单例复用键强制含插件标识，多插件不串内存状态与锁。
 除 `pluginId` 之外的配置都可选并带默认值，不传即走默认（见第 3 节）。
@@ -69,7 +69,7 @@ createHostUpdate(
 
 本包是 ESM（`"type": "module"`）：ESM 插件直接 `import`；CJS 插件用 `await import('dsh-plugin-update')`。
 
-### 三个电话的入参与回参
+### 四个电话的入参与回参
 
 面板与宿主两侧共用这一份契约（`…` 是你的前缀）：
 
@@ -78,6 +78,7 @@ createHostUpdate(
 | `….updateStatus` | `{}` | `{ ok: true, snapshot, manual, receipt: null }` | `{ ok: false, error, errorKind, diag? }` |
 | `….updateCheck` | `{}` | `{ ok: true, snapshot, manual, receipt }` | 同上 |
 | `….updateInstall` | `{ checkId, requestId }` | `{ ok: true, snapshot, manual, receipt: null }` | 同上 |
+| `….updateChangelog` | `{ version }` | `{ ok: true, version, markdown: string \| null }` | 同上 |
 
 - `snapshot` 恒为第 5.1 节那六个字段；`manual` 是第 5.3 节那条手工命令（能给则给，不能给为 `null`）。
 - `receipt` 只有查新版给（`{ checkId, checkedAt, expiresAt }`）；装更新时把 `checkId` 原样带回来，`requestId` 由面板自己生成（同一个编号重复提交直接返回旧结果）。
@@ -127,6 +128,7 @@ const panel = mountUpdatePanel(document.getElementById('update-slot'), {
   call: (name, args) => host.call(name, args),
 })
 // 离开时 panel.unmount()：只停轮询，安装在宿主侧继续跑；重开面板立刻重查，1 秒内恢复显示。
+// 弹窗版想让「关闭」按钮真把弹窗撤掉：传 onCloseRequested（面板点关闭/Esc 时先调它撤 DOM，再停轮询；入口件打开的 dialog 已内置）。
 ```
 
 组件内部消化的事（调用者不再写）：按 `panelPollMs` 轮询查状态（下限 250 毫秒）；安装按钮状态跟随快照的 `canInstall`，不另写门控规则；装不了的原因按第 5.2 节展示中文一句话；`pending-restart` 单独横幅加重启指引，不再给安装按钮；手工命令展示与复制；排队位置展示与 `showOthers` 开关；跳过按版本记（“已跳过 X.Y.Z · 恢复”在同一行，不藏进设置页）；失败时旁边的“复制诊断”一键给出脱敏后的自包含文本（稳定码、版本、宿主、队列位置），深挖仍看日志（组件里留着第 6 节第 11 条的过滤口径）。
@@ -140,7 +142,7 @@ mountUpdatePanel(slot, { pluginId: 'my-notes-plugin', prefix: 'notes', call: hos
 
 面板画成档案五章：**01 检查与安装、02 更新日志、03 更新队列、04 错误信息、05 手工命令**（五章恒在，缺内容给中性提示，不跳号）。档案头一行是「插件名 + 使用范围 + `profile` 牌」：使用范围由面板自动向宿主索取（电话入参 `includeEnv`，宿主只回**范围名与宿主种类**、不回任何路径），显示的就是更新要落到的那个 profile——`web` 与 `desktop` 各装一份，装错范围是严重故障，所以这一栏宁可显示“未知”也不猜。调用方知道得更准时可以用 `profileName` 显式覆盖。
 
-可选专业主题（D5 档案卷，不替换默认）：挂载时加 `theme: 'd5-paper'` 即换肤（右上大印章「待查/可装/安装中/待重启/受阻/已最新」+ 横幅小印章一字 + profile 牌 + 待重启衬线横幅配手绘 SVG 标 + 窄屏印章固定 + 省略号逐字折叠 + 浅深双主题跟随系统），内核 DOM 顺序不动、复制诊断常在；不传即最小可用默认样式。运行时用 `panel.setTheme('d5-paper' | 'default')` 可切。
+可选档案卷主题（纸面浅色案卷风，不替换默认）：挂载时加 `theme: 'archive'` 即换肤（右上大印章「待查/可装/安装中/待重启/受阻/已最新」+ 横幅小印章一字 + profile 牌 + 待重启衬线横幅配手绘 SVG 标 + 窄屏印章固定 + 省略号逐字折叠 + 浅深双主题跟随系统），内核 DOM 顺序不动、复制诊断常在；不传即最小可用默认深色样式。运行时用 `panel.setTheme('archive' | 'default')` 可切。旧值 `theme: 'd5-paper'` 仍可用（同一套渲染）。入口件与批量面板是同一个 `theme` 参数，取值同一套。
 
 类型定义随包分发（`dsh-plugin-update/panel` 的 `.d.ts`），不用自编译；面板离线可读，与包版本绑定。
 
@@ -215,7 +217,7 @@ for (const [name, handler] of Object.entries(multi.handlers)) registry.set(name,
 ```
 
 五个批量电话（`<prefix>` 即上面的 `life`）：`batchStatus` / `batchCheck` / `batchInstall` / `batchResume` / `batchCancel`；
-每个目标的三个单插件电话照旧以**各自前缀**暴露（`ilife-bill.updateStatus` 等）。
+每个目标的四个单插件电话照旧以**各自前缀**暴露（`ilife-bill.updateStatus` 等）。
 
 回包形状（成功恰好四项，失败只有三项）：
 
@@ -232,7 +234,7 @@ import { mountUpdateBatchPanel } from 'dsh-plugin-update/panel-batch'
 const panel = mountUpdateBatchPanel(el, {
   prefix: 'life',
   call: (name, args) => host.call(name, args),
-  theme: 'd5-paper',       // 与单插件面板同一套皮肤
+  theme: 'archive',          // 与单插件面板同一套皮肤（archive = 档案卷，旧值 d5-paper 仍可用）
 })
 ```
 
@@ -252,7 +254,7 @@ mountUpdateBatchPanelHttp(document.querySelector('#batch'), {
 三条硬约束（都在实现里）：**一行只回答一个问题**（这家的下一步是什么，状态词全中文可执行）；
 **行内动作只作用于该行**，「全部更新」是宏而不是第二个状态机；**待重启与失败常驻横幅**，不藏进展开里。
 
-点任意一行展开该家详情：**内容是单插件那套五章内核的只读渲染，动作由批量面板自己提供**。
+点任意一行展开该家详情：**内容是单插件那套五章内核的只读渲染，动作由批量面板自己提供**。第 02 章日志由批量面板按行自动取该行自己的 `updateChangelog` 电话（按行+版本记住结果，取不到即中性提示，不挡安装；`autoChangelog: false` 可关）。
 内核渲染时传 `actions: 'none'`——五章内容、进度条、「已跳过」提示一字不减，**动作按钮一个都不画**
 （内核里那些按钮带的是 `data-action`，批量面板只认 `data-act`；照搬 markup 而不接管行为，
 就会得到「可点却没反应」的死按钮——这条缝现在由渲染开关焊死）。详情里的动作行是批量面板自己的：
@@ -274,11 +276,33 @@ mountUpdateBatchPanelHttp(document.querySelector('#batch'), {
 **跨使用范围如实拒绝**：`web` 与 `desktop` 各自排队（装的是不同落点），混在一起的目标会回
 `cross-scope`，本包不会替你跨范围抢锁。
 
+### 第 2.7 节：更新日志自动展示（告诉用户更新了什么）
+
+任何插件的升级能力都是两件事：**① 给一套面板**（上面第 4 步 / 2.5 / 2.6，挂载一行即跑）；**② 告诉用户这次更新了什么**（本节，写 md 即显示，零新增代码）。
+
+```js
+import { mountUpdatePanel } from 'dsh-plugin-update/panel'
+
+// 与第 4 步同一行，不用加任何参数：有新版时第 02 章“更新日志”自动出现
+const panel = mountUpdatePanel(document.getElementById('update-slot'), {
+  pluginId: 'my-notes-plugin',
+  prefix: 'notes',
+  call: (name, args) => host.call(name, args),
+})
+```
+
+作者侧只写文件，不写代码（发布后用户自动看到）：
+
+1. 包根放 `CHANGELOG.md`（文件名全大写，小写视为没有），版本节形如 `## [1.2.0] - 2026-10-05`（最新在前），分类用 `### Added/Fixed/Changed`（面板展开；`Deprecated/Removed/Security` 折叠；`Unreleased` 与空节忽略）。
+2. `package.json` 的 `files` 白名单加上 `CHANGELOG.md`（否则发出去的包里没有它，面板永远读不到），发布前跑一次 `npm publish --dry-run` 核对。
+
+行为：有新版时面板按新版号自动取一次该版 tarball 里的全文（复用官方源 + `integrity` 校验，同一版本只取一次）；删了文件或取不到即中性提示，**安装永远不受影响**。想自己接管就传 `autoChangelog: false` 退回手动（备好文本后 `mountUpdatePanel({ changelogMarkdown })` 或 `setChangelogMarkdown` 传入，显式文本永不被覆盖）。入口件与批量面板同样自动：前者透传，后者展开行按行取。细节与边界见第 5.8 节。
+
 ### 升级本包（已经接入过的项目）
 
 宿主种类与安装出口都由本包自己探测和选择，**升级依赖即可，宿主侧与面板侧都不用改代码**：
 
-1. 依赖版本提到 `^0.3.1`。
+1. 依赖版本提到 `^0.5.0`。
 2. 重新装 / 发一版你自己的插件，让新依赖进当前使用范围（运行时用的是 `node_modules` 里那份）。
 3. 如果你自己接过一版宿主安装出口，把它删掉——它会挡在本包的路由前面。
 
@@ -426,7 +450,8 @@ dsh plugin --profile my-web add --save-exact my-notes-plugin@1.2.3 --registry=ht
 
 - 有新版时面板在横幅下方展示“更新说明（当前版 → 新版）：”，按目标包内 `CHANGELOG.md`（Keep-a-Changelog 子集）渲染：`Added/Fixed/Changed` 展开，`Deprecated/Removed/Security` 折叠，`Unreleased` 与空节不展示。
 - 作者未提供说明时显示“作者未提供更新说明，安装不受影响。”——缺日志永不挡安装，不改变 `canInstall` 与 `blockedReason`。
-- 说明文本由集成方备好后传入：已装版离线读本机 `node_modules/<目标包>/CHANGELOG.md`，新版按需取新版 tarball 内同名文件（复用官方源与 `integrity` 校验，取不到即回落中性提示；参考包根导出的 `readInstalledChangelogText` / `fetchReleaseChangelogText`），经 `mountUpdatePanel({ changelogMarkdown })` 或 `setChangelogMarkdown` 交给面板。
+- 默认自动：面板看到有新版即按新版号调一次 `….updateChangelog`，回来自己填进第 02 章；同一版本只取一次，取不到即中性提示。作者侧只要写好包根 `CHANGELOG.md` 并随包发布，零新增代码。
+- 手动模式（老用法照旧）：传 `autoChangelog: false` 即退回手动——已装版离线读本机 `node_modules/<目标包>/CHANGELOG.md`，新版按需取新版 tarball 内同名文件（复用官方源与 `integrity` 校验，取不到即回落中性提示；参考包根导出的 `readInstalledChangelogText` / `fetchReleaseChangelogText`），经 `mountUpdatePanel({ changelogMarkdown })` 或 `setChangelogMarkdown` 交给面板；显式传过的文本自动链路永不覆盖。
 
 ## 6. 排错
 
@@ -450,7 +475,7 @@ dsh plugin --profile my-web add --save-exact my-notes-plugin@1.2.3 --registry=ht
 
 照第 2 节把名字换成自己的之后，逐条打勾：
 
-1. 宿主启动不报错，`update.phoneNames` 读到自家前缀的三个电话名，查状态返回六字段快照。
+1. 宿主启动不报错，`update.phoneNames` 读到自家前缀的四个电话名，查状态返回六字段快照。
 2. 面板按间隔轮询到快照，能展示第 5.2 节的原因文案；有新版时安装按钮可用，无新版与待重启时按钮状态正确。
 3. 模拟一次 `pending-restart` 能看到第 5.4 节的横幅，模拟一次自动装失败能看到第 5.3 节的命令可复制执行。
 4. 第二家同机隔离与串行：两家各传自己的插件标识与电话名前缀，电话名、落盘目录、锁文件逐个不同；安装执行跨插件串行——同范围撞上时后到者报 `update-busy`，凭队列位置（第 5.7 节）重试。
@@ -466,6 +491,25 @@ import { mountUpdatePanel } from 'dsh-plugin-update/panel'
 mountUpdatePanel(slot, { pluginId: 'notes', prefix: 'notes', call: host.call })
 ```
 
+**更新日志自动**（#38：写 md 即显示，零新增代码）：
+
+```js
+// 宿主侧：createHostUpdate 顺手注册第 4 个电话，无新增配置
+//   入参 { version }（发行版号，先验 validReleaseVersion + 通道门禁）
+//   成功 { ok: true, version, markdown: string | null }（取不到即 null，中性提示）
+//   失败复用 error / errorKind 体系；回包无路径、无快照；按版本记住结果
+import { buildChangelogPhoneName } from 'dsh-plugin-update'
+
+buildChangelogPhoneName('notes')  // 'notes.updateChangelog'，与宿主侧同一套拼法
+
+// 面板侧：默认自动，有新版调一次；显式文本仍赢，false 退回手动
+mountUpdatePanel(slot, { pluginId: 'my-notes-plugin', prefix: 'notes', call: host.call })
+// mountUpdatePanel(slot, { pluginId, prefix, call, autoChangelog: false })
+// mountUpdatePanel(slot, { pluginId, prefix, call, changelogMarkdown })  // 手动模式
+```
+
+- 入口件（`dsh-plugin-update/entry`）把 `autoChangelog / changelogMarkdown` 透传给面板 dialog/inline；批量面板（`dsh-plugin-update/panel-batch`）展开行自动调该行自己的 `updateChangelog`（无新增批量电话，`autoChangelog: false` 可关整批）；HTTP 版（`dsh-plugin-update/http`）白名单已放行，默认路径即达。
+
 **客户端入口**（`dist/client.js`，构建期打包用）：
 
 ```js
@@ -506,6 +550,6 @@ queuePositionOf(queueState, 'my-plugin', requestId)  // 0 = 在装，1..n = 顺
 
 ## 9. 兼容与稳定性
 
-这些形状稳定，可以放心依赖：三个电话名与入参回参、快照六字段、任务公开形状、配置只经函数入参注入、安装配方五键、日志事件字段基线（三个事件各带必填 `pluginId`）、历史落盘路径。
+这些形状稳定，可以放心依赖：四个电话名与入参回参（老三电话一字不动，`updateChangelog` 是新增）、快照六字段、任务公开形状、配置只经函数入参注入、安装配方五键、日志事件字段基线（三个事件各带必填 `pluginId`）、历史落盘路径。
 
 向后兼容的扩展：新增可选配置键、新增可选 `readerOverrides`（如 `targetPackageDir`）、新增宿主种类与路由取值。调用方不认新取值时按普通宿主处理即可，不会因此报错。

package/dist/client.d.ts

@@ -1,6 +1,6 @@
-import { type PhoneAction } from './config.js';
-export { buildPhoneName, buildPhoneNames } from './config.js';
-export type { PhoneAction } from './config.js';
+import { type ChangelogPhoneAction, type PhoneAction } from './config.js';
+export { buildChangelogPhoneName, buildPhoneName, buildPhoneNames } from './config.js';
+export type { ChangelogPhoneAction, PhoneAction } from './config.js';
 export { manualCommand } from './commands.js';
 export { QUEUE_INTENT_TTL_MS, cancelEnqueuedInQueue, emptyQueueState, enqueueInQueue, isHeadOfQueue, isQueueBusy, normalizeQueueState, pruneExpiredIntents, queuePositionOf, releaseOwnerInQueue, setOwnerIfFree, visibleQueueFor, } from './queue.js';
 export type { QueuedEntry, QueueOwner, UpdateQueueState, VisibleQueue, VisibleQueueOwner } from './queue.js';
@@ -12,5 +12,5 @@ export declare const CLIENT_POLL: {
     readonly defaultMs: 1000;
     readonly minMs: 250;
 };
-export declare function buildClientPhoneNames(prefix: string): Record<PhoneAction, string>;
+export declare function buildClientPhoneNames(prefix: string): Record<PhoneAction, string> & Record<ChangelogPhoneAction, string>;
 export declare function assertPollInterval(ms: unknown): number;

package/dist/client.js

@@ -1,6 +1,6 @@
 // AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/client.ts
 import { buildPhoneNames, DEFAULT_PANEL_POLL_MS, MIN_PANEL_POLL_MS } from "./config.js";
-import { buildPhoneName, buildPhoneNames as buildPhoneNames2 } from "./config.js";
+import { buildChangelogPhoneName, buildPhoneName, buildPhoneNames as buildPhoneNames2 } from "./config.js";
 import { manualCommand as manualCommand2 } from "./commands.js";
 import {
   QUEUE_INTENT_TTL_MS,
@@ -66,6 +66,7 @@ export {
   batchEntryOf,
   batchProgress,
   batchRequestId,
+  buildChangelogPhoneName,
   buildClientPhoneNames,
   buildPhoneName,
   buildPhoneNames2 as buildPhoneNames,

package/dist/config.d.ts

@@ -1,6 +1,8 @@
 export declare const DEFAULT_PREFIX = "wf";
 export declare const PHONE_ACTIONS: readonly ["updateStatus", "updateCheck", "updateInstall"];
 export type PhoneAction = (typeof PHONE_ACTIONS)[number];
+export declare const CHANGELOG_PHONE_ACTION: "updateChangelog";
+export type ChangelogPhoneAction = typeof CHANGELOG_PHONE_ACTION;
 export declare const DEFAULT_TARGET_PACKAGE = "dsh-mattpocock-skills-deck";
 export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
 export declare const LEGACY_PLUGIN_ID = "dsh-mattpocock-skills-deck";
@@ -44,5 +46,6 @@ export interface ResolvedUpdateConfig {
 export declare function assertPluginId(value: unknown): string;
 export declare function assertPrefix(value: unknown, role: string): string;
 export declare function resolveUpdateConfig(input: UpdateConfigInput): ResolvedUpdateConfig;
-export declare function buildPhoneNames(prefix: string): Record<PhoneAction, string>;
+export declare function buildPhoneNames(prefix: string): Record<PhoneAction, string> & Record<ChangelogPhoneAction, string>;
+export declare function buildChangelogPhoneName(prefix: string): string;
 export declare function buildPhoneName(prefix: string, action: PhoneAction): string;

package/dist/config.js

@@ -1,6 +1,7 @@
 // AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/config.ts
 const DEFAULT_PREFIX = "wf";
 const PHONE_ACTIONS = ["updateStatus", "updateCheck", "updateInstall"];
+const CHANGELOG_PHONE_ACTION = "updateChangelog";
 const DEFAULT_TARGET_PACKAGE = "dsh-mattpocock-skills-deck";
 const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
 const LEGACY_PLUGIN_ID = "dsh-mattpocock-skills-deck";
@@ -73,14 +74,19 @@ function buildPhoneNames(prefix) {
   return {
     updateStatus: checked + ".updateStatus",
     updateCheck: checked + ".updateCheck",
-    updateInstall: checked + ".updateInstall"
+    updateInstall: checked + ".updateInstall",
+    updateChangelog: checked + ".updateChangelog"
   };
 }
+function buildChangelogPhoneName(prefix) {
+  return buildPhoneNames(prefix).updateChangelog;
+}
 function buildPhoneName(prefix, action) {
   return buildPhoneNames(prefix)[action];
 }
 export {
   BACKUP_FILE,
+  CHANGELOG_PHONE_ACTION,
   DEFAULT_CHECK_TIMEOUT_MS,
   DEFAULT_CONFIRMATION_TTL_MS,
   DEFAULT_INSTALL_TIMEOUT_MS,
@@ -99,6 +105,7 @@ export {
   STATE_FILE,
   assertPluginId,
   assertPrefix,
+  buildChangelogPhoneName,
   buildPhoneName,
   buildPhoneNames,
   resolveUpdateConfig

package/dist/entry.d.ts

@@ -22,7 +22,8 @@ export interface UpdateEntryOptions {
     /** 调宿主电话：(phoneName, args) => Promise<reply>。 */
     call: (name: string, args: Record<string, unknown>) => Promise<unknown>;
     variant?: EntryVariant;
-    theme?: 'default' | 'd5-paper';
+    /** 主题：`default` 最小可用深色，`archive` 档案卷纸面浅色（`d5-paper` 为旧别名仍可用）。 */
+    theme?: UpdatePanelTheme;
     /** 缺省 'mount'：进页面静默查一次（只读）。'never' 则只在用户点击时查。 */
     autoCheck?: EntryAutoCheck;
     /** 缺省 'has-update'：有新版才开面板，没有就只在原地给一句提示。 */
@@ -31,6 +32,12 @@ export interface UpdateEntryOptions {
     label?: string;
     profileName?: string;
     pollMs?: number;
+    /**
+     * 更新日志自动/手动（#38）：透传给面板（dialog 与 inline 同走 mountPanel），默认自动；
+     * 显式文本仍赢，false 退回手动。入口件自己不取数。
+     */
+    autoChangelog?: boolean;
+    changelogMarkdown?: string | null;
     /** variant='badge' 或 openOn='manual' 时，点击交给接入方（自己跳自己的页面）。 */
     onActivate?: (state: {
         hasUpdate: boolean;
@@ -46,7 +53,7 @@ export interface UpdateEntryController {
     close(): void;
     /** 当前按钮上的状态文案（接入方做自定义排版时读它）。 */
     label(): string;
-    setTheme(theme: 'default' | 'd5-paper'): void;
+    setTheme(theme: UpdatePanelTheme): void;
     unmount(): void;
 }
 /**

package/dist/entry.js

@@ -2,7 +2,8 @@
 import { DEFAULT_PREFIX, MIN_PANEL_POLL_MS, buildPhoneNames } from "./config.js";
 import {
   failureCodeOf,
-  mountUpdatePanel
+  mountUpdatePanel,
+  normalizePanelTheme
 } from "./panel.js";
 const LABEL_IDLE = "\u68C0\u67E5\u66F4\u65B0";
 const LABEL_FAILED = "\u66F4\u65B0\u5931\u8D25\uFF0C\u70B9\u6B64\u67E5\u770B";
@@ -48,6 +49,13 @@ const UPDATE_ENTRY_CSS = [
   ".dsh-upd-entry-btn{font:inherit;border:1px solid var(--dsh-upd-line,#d1d5db);border-radius:6px;",
   "background:var(--dsh-upd-btn,#f9fafb);color:inherit;padding:4px 12px;cursor:pointer}",
   ".dsh-upd-entry-btn:hover{border-color:var(--dsh-upd-primary,#2563eb)}",
+  ".dsh-upd-entry-btn,.dsh-upd-entry-dot{transition:background-color .15s ease,border-color .15s ease,color .15s ease,transform .06s ease}",
+  ".dsh-upd-entry-btn:active:not(:disabled){transform:translateY(1px)}",
+  ".dsh-upd-entry-btn:disabled,.dsh-upd-entry-dot:disabled{opacity:.55;cursor:wait}",
+  '.dsh-upd-entry-btn[aria-busy="true"]::after{content:"";display:inline-block;width:10px;height:10px;margin-left:7px;vertical-align:-1px;',
+  "border:2px solid currentColor;border-top-color:transparent;border-radius:50%;animation:dsh-upd-entry-spin .8s linear infinite}",
+  "@keyframes dsh-upd-entry-spin{to{transform:rotate(360deg)}}",
+  '@media (prefers-reduced-motion: reduce){.dsh-upd-entry-btn,.dsh-upd-entry-dot{transition:none}.dsh-upd-entry-btn[aria-busy="true"]::after{animation:none}}',
   ".dsh-upd-entry-btn:focus-visible,.dsh-upd-entry-dot:focus-visible{outline:2px solid var(--dsh-upd-focus,#2563eb);outline-offset:1px}",
   '.dsh-upd-entry[data-state="update"] .dsh-upd-entry-btn{border-color:var(--dsh-upd-ok-line,#059669);color:var(--dsh-upd-ok-line,#059669)}',
   '.dsh-upd-entry[data-state="restart"] .dsh-upd-entry-btn{border-color:var(--dsh-upd-warn-line,#d97706);color:var(--dsh-upd-warn-line,#d97706)}',
@@ -106,10 +114,10 @@ function mountUpdateEntry(container, options) {
   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`);
   }
-  let theme = options.theme ?? "default";
-  if (theme !== "default" && theme !== "d5-paper") {
-    throw new Error(`[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 d5-paper\uFF08\u6536\u5230 ${JSON.stringify(options.theme)}\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`);
@@ -121,6 +129,7 @@ function mountUpdateEntry(container, options) {
   let snapshot = null;
   let error = null;
   let note = null;
+  let activating = false;
   let mounted = true;
   let panel = null;
   let panelMode = null;
@@ -156,9 +165,10 @@ function mountUpdateEntry(container, options) {
   }
   function entryHTML() {
     const kind = entryStateKind(stateOf());
-    const text = currentLabel();
+    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)}"></button>` : `<button type="button" class="dsh-upd-entry-btn" ${ENTRY_ATTR}="activate">${escapeHtml(text)}</button>`;
+    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>
 <span class="dsh-upd-entry" data-variant="${variant}" data-state="${kind}"${themeAttr}>${control}${noteHTML}</span>`;
@@ -208,6 +218,10 @@ function mountUpdateEntry(container, options) {
       theme,
       pollMs,
       profileName,
+      autoChangelog: options.autoChangelog,
+      changelogMarkdown: options.changelogMarkdown ?? null,
+      // 面板点「关闭」即走入口件的完整关闭（收 dialog + 还原按钮 + 重查一次），不再是面板自己停轮询。
+      onCloseRequested: () => close(),
       call: panelCall
     });
     panelMode = mode;
@@ -233,10 +247,15 @@ function mountUpdateEntry(container, options) {
     void refresh();
   }
   async function activate() {
-    if (!mounted || panelMode !== null) return;
+    if (!mounted || panelMode !== null || activating) return;
+    activating = true;
     note = null;
     render();
-    await checkNow();
+    try {
+      await checkNow();
+    } finally {
+      activating = false;
+    }
     if (!mounted) return;
     if (variant === "badge" || openOn === "manual") {
       if (onActivate) onActivate({ hasUpdate: hasUpdate(), latestVersion: snapshot?.latestVersion ?? null });
@@ -252,11 +271,11 @@ function mountUpdateEntry(container, options) {
     render();
   }
   function setTheme(next) {
-    if (next !== "default" && next !== "d5-paper") {
-      throw new Error(`[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 d5-paper\uFF08\u6536\u5230 ${JSON.stringify(next)}\uFF09`);
+    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 = next;
-    if (panel) void panel.setTheme(next);
+    theme = normalizePanelTheme(next);
+    if (panel) void panel.setTheme(theme);
     else render();
   }
   function onClick(ev) {
@@ -273,6 +292,14 @@ function mountUpdateEntry(container, options) {
     } 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;
@@ -287,11 +314,19 @@ function mountUpdateEntry(container, options) {
       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();

package/dist/host.d.ts

@@ -1,8 +1,8 @@
-import { type PhoneAction, type UpdateConfigInput } from './config.js';
+import { type ChangelogPhoneAction, type PhoneAction, type UpdateConfigInput } from './config.js';
 import type { EnvironmentKind, ReleaseChannel } from './ports.js';
 import { type UpdateQueueState } from './queue.js';
-export { buildPhoneName, buildPhoneNames, resolveUpdateConfig } from './config.js';
-export type { PhoneAction, UpdateConfigInput } from './config.js';
+export { buildChangelogPhoneName, buildPhoneName, buildPhoneNames, resolveUpdateConfig } from './config.js';
+export type { ChangelogPhoneAction, PhoneAction, UpdateConfigInput } from './config.js';
 export { parseEventListManifest, checkEventFields, checkEventCounts } from './gate.js';
 export type { GateEventLevel, GateEventKind, GateEventEntry, GateEventCounts, GateEventList, GateFieldCheck, GateCountCheck } from './gate.js';
 export { containingPackage, defaultHomeDir, profileNameValid, registrySpec, resolveTargetPackage } from './reader.js';
@@ -111,7 +111,7 @@ type LogCtx = {
     fire: (level: string, event: string, fields: Record<string, unknown>) => void;
 } | null;
 export interface HostUpdate {
-    phoneNames: Record<PhoneAction, string>;
+    phoneNames: Record<PhoneAction, string> & Record<ChangelogPhoneAction, string>;
     handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>>;
 }
 /**

package/dist/host.js

@@ -10,8 +10,9 @@ import {
   resolveUpdateConfig
 } from "./config.js";
 import { manualCommand } from "./commands.js";
+import { fetchReleaseChangelogText } from "./changelog-io.js";
 import { buildDiag } from "./diag.js";
-import { isVersionAllowedInChannel, validRequestId } from "./service.js";
+import { fetchNpmVersionRelease, isVersionAllowedInChannel, updateError, validReleaseVersion, validRequestId } from "./service.js";
 import { createUpdateDiskPorts, createUpdateExecutor, createUpdateQueuePorts } from "./store.js";
 import { createUpdateReader, defaultHomeDir, resolveProfileName, resolveTargetPackage } from "./reader.js";
 import {
@@ -27,7 +28,7 @@ import {
   setOwnerIfFree,
   visibleQueueFor
 } from "./queue.js";
-import { buildPhoneName, buildPhoneNames as buildPhoneNames2, resolveUpdateConfig as resolveUpdateConfig2 } from "./config.js";
+import { buildChangelogPhoneName, buildPhoneName, buildPhoneNames as buildPhoneNames2, resolveUpdateConfig as resolveUpdateConfig2 } from "./config.js";
 import { parseEventListManifest, checkEventFields, checkEventCounts } from "./gate.js";
 import { containingPackage, defaultHomeDir as defaultHomeDir2, profileNameValid, registrySpec, resolveTargetPackage as resolveTargetPackage2 } from "./reader.js";
 import {
@@ -87,7 +88,7 @@ import {
   CHANGELOG_TAR_MAX_BYTES,
   CHANGELOG_TARBALL_MAX_BYTES,
   extractChangelogFromTar,
-  fetchReleaseChangelogText,
+  fetchReleaseChangelogText as fetchReleaseChangelogText2,
   readInstalledChangelogText
 } from "./changelog-io.js";
 import { createUpdateDiskPorts as createUpdateDiskPorts2, createUpdateExecutor as createUpdateExecutor2, pathsForUpdate, resolveCliEntry } from "./store.js";
@@ -105,7 +106,7 @@ import {
   compareReleaseVersions,
   isPrereleaseVersion,
   isVersionAllowedInChannel as isVersionAllowedInChannel2,
-  validReleaseVersion,
+  validReleaseVersion as validReleaseVersion2,
   validVersion,
   compareVersions
 } from "./service.js";
@@ -524,6 +525,49 @@ function loggedPhone(method, kind, pluginId, fn, diagCtx) {
     }
   };
 }
+function loggedChangelogPhone(method, pluginId, fn, diagCtx) {
+  return async function(args) {
+    const t0 = Date.now();
+    const emit = (level, event, fields) => {
+      try {
+        if (phoneLogCtx && typeof phoneLogCtx.fire === "function") phoneLogCtx.fire(level, event, fields);
+      } catch {
+      }
+    };
+    const safeArgs = args && typeof args === "object" ? args : {};
+    try {
+      const out = await fn(safeArgs);
+      emit("info", "host.call", { method, latencyMs: Date.now() - t0, ok: true, kind: "update-changelog", pluginId });
+      return { ok: true, version: out.version, markdown: out.markdown };
+    } catch (error) {
+      const payload = toUpdateErrorPayload(error);
+      emit("warn", "host.call.fail", { method, kind: "update-changelog", errorHash: hash8(String(error?.message || payload.error)), pluginId });
+      let diag;
+      try {
+        const cfg = diagCtx?.config;
+        const overrides = diagCtx?.readerOverrides ?? {};
+        const envRaw = overrides?.environmentKind;
+        const runningRaw = overrides?.runningVersion;
+        const built = buildDiag({
+          errorCode: payload.error,
+          phoneKind: "update-changelog",
+          error,
+          args: safeArgs,
+          targetPackageName: cfg?.targetPackageName,
+          registryUrl: cfg?.registryUrl,
+          runningVersion: typeof runningRaw === "string" ? runningRaw : void 0,
+          latestVersion: void 0,
+          environmentKind: typeof envRaw === "string" ? envRaw : void 0,
+          latencyMs: Date.now() - t0
+        });
+        if (built && typeof built === "object") diag = built;
+      } catch {
+        diag = void 0;
+      }
+      return { ok: false, ...payload, ...diag ? { diag } : {} };
+    }
+  };
+}
 function createHostUpdate(deps = {}, configInput) {
   const config = resolveUpdateConfig(configInput);
   const pluginId = config.pluginId;
@@ -533,6 +577,28 @@ function createHostUpdate(deps = {}, configInput) {
   else watchDesktopPnpm(ctx);
   const readerOverrides = { ...deps.readerOverrides ?? {}, ctx, ...deps.pluginManager ? { pluginManager: deps.pluginManager } : {} };
   const phoneNames = buildPhoneNames(config.prefix);
+  const changelogCache = /* @__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 };
+    const fetchImpl = readerOverrides.fetchImpl ?? globalThis.fetch;
+    const release = await fetchNpmVersionRelease(fetchImpl, config.checkTimeoutMs, {
+      targetPackageName: config.targetPackageName,
+      registryUrl: config.registryUrl,
+      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 }
+    );
+    changelogCache.set(version, markdown);
+    return { version, markdown };
+  }
   async function readStatus(args) {
     const reader = await getSharedReader(pluginId, config, {
       ...readerOverrides,
@@ -630,6 +696,10 @@ function createHostUpdate(deps = {}, configInput) {
     [phoneNames.updateInstall]: loggedPhone(phoneNames.updateInstall, "update-install", pluginId, runInstall, {
       config,
       readerOverrides
+    }),
+    [phoneNames.updateChangelog]: loggedChangelogPhone(phoneNames.updateChangelog, pluginId, readChangelog, {
+      config,
+      readerOverrides
     })
   };
   return { phoneNames, handlers };
@@ -682,6 +752,7 @@ export {
   SKIPPED_FILE,
   __resetSharedUpdateReaderForTests,
   addSkipped,
+  buildChangelogPhoneName,
   buildDiag2 as buildDiag,
   buildPhoneName,
   buildPhoneNames2 as buildPhoneNames,
@@ -709,7 +780,7 @@ export {
   enforceBudget as enforceDiagBudgetForPhone,
   enqueueInQueue2 as enqueueInQueue,
   extractChangelogFromTar,
-  fetchReleaseChangelogText,
+  fetchReleaseChangelogText2 as fetchReleaseChangelogText,
   hasVisibleSections,
   isHeadOfQueue2 as isHeadOfQueue,
   isPrereleaseVersion,
@@ -741,7 +812,7 @@ export {
   setOwnerIfFree2 as setOwnerIfFree,
   skipKey,
   truncateToWordBoundary,
-  validReleaseVersion,
+  validReleaseVersion2 as validReleaseVersion,
   validVersion,
   visibleQueueFor2 as visibleQueueFor
 };