dsh-plugin-update 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 格式为 Keep-a-Changelog 子集：`Added/Fixed/Changed` 必写，`Deprecated/Removed/Security` 有则透传，`Unreleased` 面板忽略，禁止 git-log 直倒。面板缺日志时中性提示，不挡安装。
 
+## [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
+- Security 必显：`### Security` 与 `Added/Fixed/Changed` 同级展开（页面查找可命中）；单类超 200 条时前 200 条展开、其余收进该类内部折叠并标计数（64K/单条 500 字墙保留）。
+- 诚实截断计数：超限类标题下加小字“共 M 条，仅显示前 N 条”（M 该版该类原始条数、N 实际渲染数，多版本各自标；未超限不打扰）。
+- 撤回警告：目标版本标题含 `[YANKED]` 时第 02 章区间标题下方加警告横幅（`role=alert`）：“目标版本 X.Y.Z 已被作者撤回（yanked），安装不受影响，继续前请确认。”；中间版本只保留标题后缀，不挡安装、不碰快照门控。
+- 破坏标记：条目开头 `BREAKING:`/`不兼容:`（大小写不敏感，中英文冒号皆可，匹配前剥行首加粗/引用装饰）行首挂徽标（`role=img`）+ 前缀加粗，正文一字不动；正文中间散文永不误标。
+- `validateChangelog(markdown)` 纯函数（零导入、永不抛错，与 parse 共享扫描仪）：回 `{ ok, diagnostics: { line, code, hint }[] }`（line 原文件 1-based 行号，按行号排序）；码表 `E_VERSION_TITLE`/`E_CATEGORY`/`E_BULLET_ORPHAN`（Error，会丢内容）与 `W_BREAKING_MAYBE`/`W_YANKED`/`W_TRUNCATED`/`W_TRUNCATED_FILE`/`W_EMPTY`（Warning）；仅 CI/发布前用，运行时永不调用。
+- 记住语义澄清：成功与取不到（null）按版本永久记（面板内存会话级 + 宿主进程级，不落盘；显式文本永不覆盖）；传输失败不进缓存，手动查/换版/重开立即重试，轮询按退避问（`shouldFetchChangelog` 纯策略三处共用）；`autoChangelog: false` 关闭整链。
+- 文档：README §2.7/§5.8 同步必显/计数/横幅/标记/校验/记住的用户做法（只加 MUST/SHOULD，不放设计 rationale，详见 ADR-0002）。
+
 ## [0.5.1] - 2026-10-06
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 给 DSH 插件加「检查更新 / 安装更新」能力的 npm 包。宿主侧一段接线，面板侧挂一个现成组件，装不上时给用户一条可复制的手工命令。
 
-要求 Node 22 或更高，零运行时依赖。当前版本 `0.5.1`。
+要求 Node 22 或更高，零运行时依赖。当前版本 `0.5.2`。
 
 装上它你会拿到六样东西：
 
@@ -295,16 +295,18 @@ const panel = mountUpdatePanel(document.getElementById('update-slot'), {
 
 作者侧只写文件，不写代码（发布后用户自动看到）：
 
-1. 包根放 `CHANGELOG.md`（文件名全大写，小写视为没有），版本节形如 `## [1.2.0] - 2026-10-05`（最新在前），分类用 `### Added/Fixed/Changed`（面板展开；`Deprecated/Removed/Security` 折叠；`Unreleased` 与空节忽略）。
+1. 包根放 `CHANGELOG.md`（文件名全大写，小写视为没有），版本节形如 `## [1.2.0] - 2026-10-05`（最新在前），分类用 `### Added/Fixed/Changed/Security`（面板必显展开；`Deprecated/Removed` 折叠；`Unreleased` 与空节忽略）。
 2. `package.json` 的 `files` 白名单加上 `CHANGELOG.md`（否则发出去的包里没有它，面板永远读不到），发布前跑一次 `npm publish --dry-run` 核对。
 
 行为：有新版时面板按新版号自动取一次该版 tarball 里的全文（复用官方源 + `integrity` 校验，同一版本只取一次）；删了文件或取不到即中性提示，**安装永远不受影响**。想自己接管就传 `autoChangelog: false` 退回手动（备好文本后 `mountUpdatePanel({ changelogMarkdown })` 或 `setChangelogMarkdown` 传入，显式文本永不被覆盖）。入口件与批量面板同样自动：前者透传，后者展开行按行取。细节与边界见第 5.8 节。
 
+安全事项必显：`### Security` 与 `Added/Fixed/Changed` 同级展开。单类超 200 条时前 200 条展开、其余收进该类内部折叠并标计数。目标版本被撤回（标题含 `[YANKED]`）时，第 02 章顶部加一条警告横幅，安装不受影响。条目开头写 `BREAKING:` 或 `不兼容:`（大小写不敏感，中英文冒号皆可）即挂破坏标记，正文不动。同一版本日志只取一次；取不到显示中性提示，安装不受影响。
+
 ### 升级本包（已经接入过的项目）
 
 宿主种类与安装出口都由本包自己探测和选择，**升级依赖即可，宿主侧与面板侧都不用改代码**：
 
-1. 依赖版本提到 `^0.5.1`。
+1. 依赖版本提到 `^0.5.2`。
 2. 重新装 / 发一版你自己的插件，让新依赖进当前使用范围（运行时用的是 `node_modules` 里那份）。
 3. 如果你自己接过一版宿主安装出口，把它删掉——它会挡在本包的路由前面。
 
@@ -450,10 +452,15 @@ dsh plugin --profile my-web add --save-exact my-notes-plugin@1.2.3 --registry=ht
 
 ### 5.8 更新说明
 
-- 有新版时面板在横幅下方展示“更新说明（当前版 → 新版）：”，按目标包内 `CHANGELOG.md`（Keep-a-Changelog 子集）渲染：`Added/Fixed/Changed` 展开，`Deprecated/Removed/Security` 折叠，`Unreleased` 与空节不展示。
+- 有新版时面板在横幅下方展示“更新说明（当前版 → 新版）：”，按目标包内 `CHANGELOG.md`（Keep-a-Changelog 子集）渲染：`Added/Fixed/Changed/Security` 必显展开，`Deprecated/Removed` 折叠，`Unreleased` 与空节不展示。
 - 作者未提供说明时显示“作者未提供更新说明，安装不受影响。”——缺日志永不挡安装，不改变 `canInstall` 与 `blockedReason`。
 - 默认自动：面板看到有新版即按新版号调一次 `….updateChangelog`，回来自己填进第 02 章；同一版本只取一次，取不到即中性提示。作者侧只要写好包根 `CHANGELOG.md` 并随包发布，零新增代码。
 - 手动模式（老用法照旧）：传 `autoChangelog: false` 即退回手动——已装版离线读本机 `node_modules/<目标包>/CHANGELOG.md`，新版按需取新版 tarball 内同名文件（复用官方源与 `integrity` 校验，取不到即回落中性提示；参考包根导出的 `readInstalledChangelogText` / `fetchReleaseChangelogText`），经 `mountUpdatePanel({ changelogMarkdown })` 或 `setChangelogMarkdown` 交给面板；显式传过的文本自动链路永不覆盖。
+- Security 必显；超限进内折叠。截断计数按类标注“共 M 条，仅显示前 N 条”（M 原始条数、N 显示数）。
+- to 版 yanked 时 02 章顶部横幅：“目标版本 X.Y.Z 已被作者撤回（yanked），安装不受影响，继续前请确认。”；中间版本只保留标题后缀。
+- `BREAKING:`/`不兼容:` 只认条目开头，badge + 前缀加粗；疑似误写由 validate 报 warning。
+- `validateChangelog(markdown)` 为纯函数（零导入、永不抛错），回 `{ ok, diagnostics: { line, code, hint }[] }`，line 为原文件行号；仅 CI/发布前用。
+- memo：成功与取不到（null）按版本永久记；传输失败不记，手动查/换版/重开立即重试，轮询按退避问；`autoChangelog: false` 关闭整链。
 
 ## 6. 排错
 

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.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.1",
+  "version": "0.5.3",
   "description": "可复用的更新系统装成的 npm 包：任何 DSH 插件照文档能集成检查更新等功能（地图 #579）",
   "license": "MIT",
   "author": "王辰浩",