dsh-plugin-update

第 2.5 节：更新入口件（配置页上那一颗按钮）

目标只有一句：让用户不用点开就知道有没有事。 一行挂上：

import { mountUpdateEntry } from 'dsh-plugin-update/entry'

const entry = mountUpdateEntry(document.getElementById('upd-entry'), {
  pluginId: 'my-notes-plugin',
  prefix: 'notes',
  call: (name, args) => host.call(name, args),
})

三个自由度，默认值都选好了：

自由度	取值	默认	说明
摆什么	button / badge / inline	button	按钮；只给一个状态点；面板本体直接嵌进来
什么时候查	mount / never	mount	进页面静默查一次（只调 .updateStatus，只读）；never 则只在点击时查
点了做什么	has-update / always / manual / direct	has-update	有新版本才开面板；检查完总是开；交给 onActivate 自己跳；点开即弹窗、不预查
无新版本摆哪	button / tooltip / note	button	版本即按钮本身；收进悬停；回右侧小字旧样子

按钮文案随状态自己变（按宿主语言单语渲染：中文界面纯中文、英文界面纯英文，一次只出现一种语言）：检查更新（尚未查询）/ 已是最新 X.Y.Z（无新版本，默认即按钮本身）/ 有新版本 1.1.0 / 正在安装… / 待重启 / 更新失败，请查看详情（英文见集中字典同 key）。

语言跟随（单语）：入口件默认跟随 document.documentElement.lang > navigator.languages > 中文兜底；显式覆盖传 locale: 'zh' | 'en' | { getActive(): string; subscribe?(cb): () => void }（对象形态可接宿主语言服务，切换即时重绘，unmount 后停订；无 DOM 环境不抛，落中文）。

无新版本时版本号摆哪（upToDateDisplay，缺省 'button'）：button 即按钮本身就是已是最新 X.Y.Z（单按钮不占宽，可点再查，hover 回检查更新暗示动作；无新版本中性弱边，hover 才走主色）；tooltip 按钮还是检查更新、版本收进悬停；note 回旧样子（按钮旁右侧小字，只在 openOn: 'has-update' 下点击确认无新版本后出现）。旧版默认即 note 的样子，要回去就显式传 upToDateDisplay: 'note'。想连按钮都不留痕，就用 openOn: 'always'（检查完总是开弹窗，无新版本在弹窗里看“已是最新”）或 openOn: 'direct'（点开即弹窗，连预查都省了，面板挂载即自查；徽标形态仍走回调口径）。

按钮尺寸（跟头行其他控件同高/整体缩放）：传 sizing 只改按钮本体，不碰面板；不传即默认外观。scale 是整体缩放（默认 1，如 1.2 放大、0.9 缩小），原来写在容器上的 zoom 可整体搬进来：

mountUpdateEntry(el, { pluginId: 'p', prefix: 'notes', call,
  sizing: { fontSize: '12px', padding: '2px 8px', borderRadius: '8px', scale: 1 },
})

等价的手写 CSS 变量（与现有 --dsh-update-* 颜色变量同口径，写在容器或祖先元素上即可）：--dsh-update-entry-font-size（默认 13px）、--dsh-update-entry-padding（默认 4px 12px）、--dsh-update-entry-border-radius（默认 6px，archive 主题下 3px）、--dsh-update-entry-scale（默认 1）。badge 圆点与 inline 内嵌不受影响。一点约束：sizing 与手写变量都不接 !important（变量本身已赢特异性）；确需 !important 请手写 CSS 覆盖。

一条铁律：检查是只读、安装是写入，两者不许合并成一个动作。 入口件永远只做「查 + 打开面板」， 任何路径都不自动安装；用户必须在面板里明确点「安装」。想让点击交给自己（例如你已有自己的更新页）：

mountUpdateEntry(el, { pluginId: 'p', prefix: 'notes', call, variant: 'badge',
  onActivate: ({ hasUpdate, latestVersion }) => { /* 自己跳自己的页面 */ } })

批量感知的入口件（一颗按钮看 N 家，点开即批量面板）

一个总管替 N 家管更新时，别再用单入口的 manual 桥接批量面板——徽标只反映总管自己一行，不是七家聚合。换这一颗：

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` 桥接即跑，总管单行不再当状态源。

聚合口径与批量面板总账同一份数法（含「忙失败占位翻回可更新」）：忙 > 失败 > 待重启 > 可更新 > 待查， 文案按宿主语言单语渲染（中文如左，英文见字典 batch-entry.* 同 key），locale 选项与单入口同形态，切换即时重绘。 三自由度与单入口同取值，缺省不同：openOn 缺省 'always'（查完总是开批量面板；has-update 下有事才开，否则原地给总账一句）。 autoCheck 缺省 'mount'（只调 .batchStatus，只读）；铁律同单入口：任何路径都不自动安装。

窗口期说明（必读）：mountUpdatePanel 与 mountUpdateBatchPanel 已接受 locale 选项（与入口件同形态），但本版本暂不消费——传了不生效，面板内容仍按既有中文渲染；语言跟随的按面迁移在后续版本逐面落地，入口件两条链已先生效。

3. 配置

const update = createHostUpdate(
  { ctx, logCtx },
  {
    pluginId: 'my-notes-plugin',
    prefix: 'notes',
    targetPackageName: 'my-notes-plugin',
    confirmationTtlMs: 20 * 60_000,   // 只调这两项，其余走默认
    panelPollMs: 2000,
  }
)

配置键	默认	说明
pluginId	必填，无默认	非空字符串，不含路径分隔符
prefix	wf	电话名前缀；电话名 = 前缀 + 点 + 动作名
targetPackageName	dsh-mattpocock-skills-deck	要检查更新的那个包是谁
registryUrl	https://registry.npmjs.org/	官方源
homeDir	现推导	环境变量 DSH_HOME 优先，否则家目录下 .dsh
checkTimeoutMs	10000	联网超时，须为有限大于 0 的数
confirmationTtlMs	600000	凭证有效期，须为有限大于 0 的数
installTimeoutMs	900000	安装时限，须为有限大于 0 的数
panelPollMs	1000	面板轮询间隔，不得小于 250 毫秒
releaseChannel	stable	版本通道：默认只推稳定版；显式传 prerelease 才收预发布版（如 0.2.0-rc.2），安装仍只装精确版

配置只经函数入参注入，不读配置文件。越界直接抛错，不静默取整。

落盘目录按标识派生：家目录下 updates 加插件标识加使用范围短指纹，三个文件名是 state.json、install.lock、before.json。读走双读（先新后旧），写只写新。 标识取历史值 dsh-mattpocock-skills-deck 时，路径与旧版一字不差（升级不丢状态）。