@mzzsfy/dsh-maintain 0.7.1 → 0.9.0

package/README.md

@@ -1,14 +1,15 @@
 # @mzzsfy/dsh-maintain
 
-DeepSeek Harness 设置页插件:版本与进程运维一体化——监测 npm 新版本、一键升级、安全重启。
+DeepSeek Harness 设置页插件:版本与进程运维一体化——监测 npm 新版本、查看更新内容、一键安装(升级/重装/回退)、安全重启。
 
 ## 功能
 
 - 版本监测:host 启动即检查一次,按轮询间隔重复检查(内存快照,不持久化);当前版本与追踪通道最新版对比,落后即提示。运行版本(宿主启动时缓存)与已装版本(磁盘实时)分开统计与展示,落后判定以运行版本为准,已装版本领先运行版本时提示"重启后生效"。定时轮询为软依赖:宿主 timer 服务不可用时仅停用自动轮询,面板显示降级提示,手动检查与升级能力不受影响。
+- 版本更新内容:面板"更新内容"按钮按追踪通道最新版本拉取 GitHub Releases 发布说明(deepseek-ai/deepseek-harness,标签 `dsh-v<版本>`,npm 清单无 readme 字段故以官方 releases 为事实源;通道最新版就绪前按钮禁用)。数据源为 releases 页面而非 api.github.com(未认证 API 限流 60 次/小时/IP 且按 IP 共享,页面限流实际宽松),从 markdown-body 正文容器深度配对提取,渲染后 HTML 映射回行文本(标题→# 前缀、列表→- 前缀、块级闭合→换行、实体解码;标签剥离先于实体解码,产物只经 React 文本节点输出无 XSS 面),页面响应体上限 512KB 流式截断;页面 URL 自建,无需远端 URL 白名单。弹窗展示版本、发布时间与正文,附"在 GitHub 查看"源站链接,无发布说明时明确提示;host 进程内缓存(仅成功结果,上限 20 个版本,超限淘汰最早缓存的版本,GitHub Releases 视为不可变故不设过期),同一版本重复查看不重复请求。GitHub 不可达或该版本未发布 Release 时窗内提示错误并可重试,附 releases 页兜底链接;路由 `GET /api/maintain/release-notes` 取追踪通道最新版。
 - 追踪通道:在 npm dist-tags 间切换(latest / next / alpha 等,选项由检查结果动态生成),切换后按新通道判定。
-- 一键升级:点击升级弹出确认窗,窗内展示将执行的实际命令(`{tag}` 已替换为追踪通道)与"升级完成后自动重启宿主"勾选项(默认勾选,本次升级会话级生效,不持久化),确认后才触发;命令模板可在设置面板直接查看与编辑。升级期间串行化(含跨进程锁文件:宿主被外部重启后,残留升级子进程的锁在有效期内仍拒绝新升级),单次尝试超时 10 分钟强杀;升级后台执行,触发后可离开页面,右下角浮条持续提示进度,完成或失败时替换为结果提示,长时间无进展转提示刷新,回到页面即可重启生效;继续运行路径下升级完成后自动重新检查版本。
+- 一键安装:面板"安装"按钮全版本状态可点(升级、重装修复、回退均从面板直达,不再有"已是最新"禁用与 409 拒绝),点击弹出确认窗,窗内展示版本变更与将执行的实际命令(`{tag}` 已替换为追踪通道)及"安装完成后自动重启宿主"勾选项(默认勾选,本次安装会话级生效,不持久化),确认后才触发。版本变更按安装意图自动表述:命令模板含精确版本号(如 `@0.1.4`)即按"安装指定版本"表述并附改回 `{tag}` 的指引;否则按通道目标与运行版本分类为升级/重装/回退,信息不足(通道最新版未知或版本无法比较)时窗内明示无法判定,仍可确认安装。通道目标等于运行版本即重装(用于本体损坏或异常安装的修复);需要回退时把模板中的 `@{tag}` 改为指定版本号(如 `@0.1.4`),回退完成后改回 `{tag}` 形态,否则后续安装持续钉在该版本。安装期间串行化(含跨进程锁文件:宿主被外部重启后,残留安装子进程的锁在有效期内仍拒绝新安装),单次尝试超时 10 分钟强杀;安装后台执行,触发后可离开页面,右下角浮条持续提示进度,完成或失败时替换为结果提示,长时间无进展转提示刷新,回到页面查看结果并按提示重启生效;继续运行路径下安装完成后自动重新检查版本。
 - 失败分类与自动重试:升级命令失败按输出特征分类(文件锁 EBUSY/EPERM 等 Windows 全局目录占用、网络瞬断与 registry 5xx、命令未找到、超时强杀、其他未知),文件锁与网络类自动重试,最多 3 次尝试,退避序列文件锁 5s/15s、网络 3s/9s,重试时升级锁有效期顺延;命令未找到、超时与未知形态不重试直接落定。重试链的整体观察窗口与宿主侧重试上限同源锁定(parity),浮条不会在宿主仍在重试时抢跑转"状态未知"。
-- 升级结果校验:升级命令成功且宿主继续运行(手动直跑或本次未勾选自动重启)时复读磁盘版本对比——版本未前进(镜像滞后或静默失败)或未达通道目标版本时,面板与浮条标注 stale 提示;自动重启路径不做复读与 stale 判定(升级落定钩子禁止网络请求与磁盘读取),版本是否前进由重启后的启动检查呈现。运行版本已是通道最新时升级入口直接拒绝(409 防降级,面板按钮同步禁用),重装场景走命令行。超时强杀意味着安装可能只完成一半,重启宿主前先确认命令需否重跑。
+- 安装结果校验:安装命令成功且宿主继续运行(手动直跑、本次未勾选自动重启或宿主不具备自动退出能力)时复读磁盘版本,按安装意图判定是否达成——钉定版本(命令含精确版本号)时恰装到该版本即达成;通道语义下目标高于来版(升级)时要求版本前进且达通道目标,版本未前进(镜像滞后或静默失败)或未达目标即标注 stale;目标等于来版(重装)时版本不变属预期;目标低于来版(回退,如切通道或装旧版)时恰落到通道目标即达成,静默未动同样拦下。未达成时面板与浮条标注 stale 提示;复读失败不标 stale(版本状态由启动检查兜底),通道目标未知时仅豁免未达目标判定(版本未前进仍拦下)。自动重启路径不做复读与 stale 判定(安装落定钩子禁止网络请求与磁盘读取),版本变化由重启后的启动检查呈现。残留升级锁(宿主被外部重启后的无主锁,疑似安装子进程仍在写全局目录)在有效期内拒绝新安装(409),等待锁过期或手动删除锁文件后重试。
 - 运行环境检测与升级后自动重启:host 启动时检测运行环境(pm2 / systemd / supervisord / Kubernetes / 容器,依据进程环境变量与 POSIX 容器特征,win32 跳过容器探测;stdin+stdout 双 TTY 判定为手动直跑;环境变量 DSH_MAINTAIN_RUNTIME_ENV=managed|manual 可强制指定,最高优先)。升级确认弹窗勾选自动重启且命令成功(退出码 0)时,托管环境下延迟 3 秒自动重启宿主——与面板"确认重启"共用同一退出调度入口(同一互斥、同一审计、同一延迟退出,仅审计行不同),落定钩子零网络请求零磁盘读取(npm 刚替换过宿主文件,避免半写状态故障);浮条提示宿主将自动重启并自动进入重启等待探测,页面随宿主恢复自动刷新;手动直跑环境不自动退出,浮条提示手动重启(弹窗内同步提示该环境约束);检测为未知形态按托管处理(维持自动重启,由重启等待总超时兜底提示)。升级失败或未勾选自动重启时不调度,后者升级完成仅提示,需在面板手动重启。
 - 活跃工作门控:升级与重启前检测运行中的 agent 会话、后台 job 与终端(agents/jobs/terminals 服务全部软依赖方法面守卫;terminals 主路径逐 agent 的 realm 作用域解析,共享根探测仅兜底,无 agent 时服务面不可见属常态不计降级;降级按服务留痕限频一次)。部分降级时已实证的活跃计数仍生效(计数>0 照常拒绝);仅当完全不可用(计数为 0 且检测不可用)时放行,不因安全网缺失死锁操作。存在活跃工作时升级被拒绝(409,不可越过);重启被拒但确认态显示活跃计数,再次点击以 force 越过;概要随 status 提供给面板。
 - 审计日志:升级/重启的触发、落定与拒绝各输出一行结构化日志(`audit endpoint=… outcome=…`),动态串单行化,便于事后排查。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-maintain",
   "description": "DSH 自身的版本管理:追踪 npm dist-tag 新版本、一键升级、安全重启",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -23,9 +23,9 @@ window.__ModuleLoader__.load({
       else console.warn('[dsh-maintain] ' + text)
     }
 
-    // 导航图标声明:交给 dsh-settings-nav-icons 统一渲染(本插件分区 → wrench);
-    // 该插件未就绪时入队,由其启动时排空
-    const NAV_ICON = { '版本与运维': 'wrench' }
+    // 导航图标声明:交给 dsh-settings-nav-icons 统一渲染;双键 = 分区 label + 市场
+    // 短名(发现页收录显示形态);该插件未就绪时入队,由其启动时排空
+    const NAV_ICON = { '版本与运维': 'wrench', 'dsh-maintain': 'wrench' }
     if (window.__navicIcons !== undefined) window.__navicIcons.register(NAV_ICON)
     else if (Array.isArray(window.__navicIconQueue)) window.__navicIconQueue.push(NAV_ICON)
     else window.__navicIconQueue = [NAV_ICON]
@@ -90,6 +90,11 @@ const CSS = [
   '.dm-dialog__hint { color:var(--dsw-alias-label-secondary); font-size:12px; }',
   '.dm-dialog__section { display:flex; flex-direction:column; gap:6px; padding:8px 0; border-top:1px solid var(--dsw-alias-separator-primary, rgba(128,128,128,0.35)); }',
   '.dm-dialog__outcome { color:var(--dsw-alias-label-secondary); font-size:12px; line-height:1.6; }',
+  // ---- 更新内容弹窗:markdown+HTML 混排正文的轻量行渲染 ----
+  '.dm-notes { font-size:12px; line-height:1.7; white-space:pre-wrap; word-break:break-word; color:inherit; }',
+  '.dm-notes__h { font-weight:600; margin-top:8px; }',
+  '.dm-notes__li { padding-left:12px; }',
+  '.dm-notes__gap { height:6px; }',
 ].join('\n')
 
 const STATUS_URL = '/api/maintain/status'
@@ -100,6 +105,7 @@ const POLL_INTERVAL_URL = '/api/maintain/poll-interval'
 const REGISTRY_BASE_URL = '/api/maintain/registry-base'
 const UPGRADE_URL = '/api/maintain/upgrade'
 const RESTART_URL = '/api/maintain/restart'
+const RELEASE_NOTES_URL = '/api/maintain/release-notes'
 const UPGRADE_POLL_MS = 2 * 1000
 // 升级提示浮条挂 body,脱离 React 组件树,SPA 切页不消失
 const UPGRADE_FLOAT_ID = 'dsh-maintain-upgrade-float'
@@ -122,6 +128,8 @@ const RESTART_SETTLE_DELAY_MS = 1 * 1000
 // 页面就绪探测目标:与整页刷新后浏览器实际请求的主文档同资源
 const INDEX_URL = '/'
 const NPM_VERSIONS_URL = 'https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions'
+// 更新内容事实源(release 上游失败时的兜底入口);host 侧 RELEASE_REPO 与此同源(parity 对拍)
+const RELEASES_PAGE_URL = 'https://github.com/deepseek-ai/deepseek-harness/releases'
 
 // abort-aware 睡眠:轮询顺序循环的拍间间隔,中止即提前唤醒
 function restartSleep(ms, controller) {
@@ -151,11 +159,11 @@ function restartPostLost(error) {
 // test/parity.test.mjs 按 const 名正则提取对拍,修改任一侧必须同步。
 const VERDICT_OUTDATED = 'outdated'
 const VERDICT_UP_TO_DATE = 'up-to-date'
+const VERDICT_UNKNOWN = 'unknown'
 // 与 host runtime.mjs RUNTIME_KINDS.MANUAL_START 镜像(parity 对拍,单侧改名即测试失败)
 const RUNTIME_KIND_MANUAL = 'manual-start-likely'
 // 与 host AUTO_RESTART_DELAY_MS 镜像(parity 对拍):弹窗文案引用,勿手抄数字
 const AUTO_RESTART_DELAY_SEC = 3
-const VERDICT_UNKNOWN = 'unknown'
 
 // 非 2xx 应答抛带 status 与完整 payload 的错误对象:调用方据此区分"活宿主明确回绝"(有 status)
 // 与"网络失联"(fetch reject TypeError/abort DOMException,无 status);payload 供活跃工作
@@ -281,6 +289,8 @@ function ensureUpgradeFloatStyle() {
   if (document.getElementById(UPGRADE_FLOAT_STYLE_ID) !== null) return
   const style = document.createElement('style')
   style.id = UPGRADE_FLOAT_STYLE_ID
+  // 自带 data-plugin:缺失时宿主 claimStyles 会把它归属给后续材质化插件,其 HMR 重建即误删
+  style.setAttribute('data-plugin', '@mzzsfy/dsh-maintain')
   style.textContent = [
     '#' + UPGRADE_FLOAT_ID + ' { position:fixed; right:20px; bottom:20px; z-index:9999; display:flex; align-items:center; gap:10px;',
     '  max-width:340px; padding:10px 14px; border-radius:10px; border:1px solid rgba(128,128,128,0.35);',
@@ -295,13 +305,68 @@ function ensureUpgradeFloatStyle() {
 // 其后按宿主是否自动重启分流指引
 // LOGIC-BEGIN upgradeFinalText
 function upgradeFinalText(state) {
-  if (state.stale === true) return '升级命令执行完成,但磁盘版本未前进或未达目标,详情见版本与运维页'
+  if (state.stale === true) return '升级命令执行完成,但结果与安装意图不符,详情见版本与运维页'
   if (state.requiresManualRestart === true) return '升级完成,当前为手动直跑环境,请手动重启宿主后生效'
   if (state.autoRestartScheduled === true) return '升级完成,宿主将自动重启,页面恢复后可直接使用'
   return '升级完成,重启宿主后生效(版本与运维页可重启)'
 }
 // LOGIC-END upgradeFinalText
 
+// 从已解析安装命令提取钉定版本(@x.y.z 精确版本 token,取最后合法者)。
+// 与 core extractPinnedVersion 镜像(parity 对拍):客户端无 parseSemver,
+// token 合法性以内嵌 semver 语法判定,规则与 host SEMVER_PATTERN 同源
+// LOGIC-BEGIN extractPinnedVersion
+function extractPinnedVersion(command) {
+  const text = typeof command === 'string' ? command : ''
+  const pattern = /@([0-9A-Za-z][0-9A-Za-z.+-]*)/g
+  const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
+  let pinned = null
+  for (const match of text.matchAll(pattern)) {
+    if (semverPattern.test(match[1])) pinned = match[1]
+  }
+  return pinned
+}
+// LOGIC-END extractPinnedVersion
+
+// 安装确认弹窗的版本变更说明:钉定版本最优先(意图=精确版本,附改回 {tag} 指引);
+// 通道语义按 未知/重装(含已装将被替换提示)/升级/无法判定/回退 分支,
+// 回退表述不断言方向(semver 等值但字面不同时同样成立),判等只用字符串相等
+// LOGIC-BEGIN buildInstallChangeLine
+function buildInstallChangeLine(status, command) {
+  // 与通道名重合的 token 是 {tag} 展开产物(通道名可为 semver 形态),不属钉定
+  const detected = extractPinnedVersion(command)
+  const pinned = detected !== null && detected !== status.channel ? detected : null
+  if (pinned !== null) {
+    return '将安装指定版本 ' + pinned + '(当前运行 ' + (status.runningVersion || '未知')
+      + ');回退或修复完成后,请把命令模板改回含 {tag} 的原形态,否则后续安装持续钉在该版本。'
+  }
+  const target = status.channelLatest
+  const running = status.runningVersion
+  if (!target) {
+    return '通道最新版未知,将安装通道「' + status.channel + '」当前指向的版本。'
+  }
+  if (target === running) {
+    const pending = status.installedVersion && status.installedVersion !== running
+      ? ',磁盘已装 ' + status.installedVersion + ' 将被替换' : ''
+    return '将重装 ' + target + ':运行版本不变' + pending + ',用于修复被破坏的本体或异常安装。'
+  }
+  if (status.verdict === VERDICT_OUTDATED) {
+    return '将升级:运行 ' + (running || '未知') + ' → ' + target + '。'
+  }
+  if (status.verdict === VERDICT_UNKNOWN) {
+    return '将安装到 ' + target + '(运行/目标版本无法比较,无法判定升降级)。'
+  }
+  return '通道目标 ' + target + ' 不高于当前运行 ' + (running || '未知') + ',宿主将回退/对齐到通道版本。'
+}
+// LOGIC-END buildInstallChangeLine
+
+// 弹窗的当前版本行:运行/已装任一缺失回退"未知"
+// LOGIC-BEGIN buildInstallVersionHint
+function buildInstallVersionHint(status) {
+  return '版本变更:当前 运行 ' + (status.runningVersion || '未知') + ' / 已装 ' + (status.installedVersion || '未知')
+}
+// LOGIC-END buildInstallVersionHint
+
 // state:null=进行中;对象=升级结果(last,ok 区分成败);'unknown'=观察超限状态未知
 function showUpgradeFloat(state) {
   ensureUpgradeFloatStyle()
@@ -429,14 +494,11 @@ function VersionCard(props) {
       }, props.busy.refresh ? '检查中…' : '刷新'),
       h('button', {
         className: 'dm-btn',
-        // upgradeLockHeld 为 host 权威信号(锁文件时效化):升级进行中或残留锁未过期时禁用;
-        // 运行版本已是通道最新时同样禁用(host 侧同步 409 拒绝,防重装降级)
-        disabled: props.busy.upgrade || props.restarting || (status.upgrade && status.upgrade.running)
-          || status.upgradeLockHeld === true
-          || status.verdict === VERDICT_UP_TO_DATE,
-        title: status.verdict === VERDICT_UP_TO_DATE ? '当前已是通道最新版,无需升级;重装请走命令行' : undefined,
+        // 安装入口全版本状态可点(重装修复/回退是显式意图):仅瞬态禁用(请求在途/升级进行中/重启等待);
+        // 残留锁与互斥保护在提交时由 host 409 拒绝,原因经 toast 提示
+        disabled: props.busy.upgrade || props.restarting || (status.upgrade && status.upgrade.running),
         onClick: props.onUpgrade,
-      }, '升级'),
+      }, '安装'),
     ),
     status.restartPending === true
       ? h('div', { className: 'dm-notice dm-notice--warn' },
@@ -460,6 +522,13 @@ function VersionCard(props) {
       checked ? h('span', { className: 'dm-meta' }, '上次检查 ' + checked) : null,
       status.checkError ? h('span', { className: 'dm-error' }, status.checkError) : null,
       h('a', { className: 'dm-link', href: NPM_VERSIONS_URL, target: '_blank', rel: 'noreferrer' }, 'npm 版本页'),
+      // 更新内容入口:通道最新版未知(tags 未就绪)时禁用
+      h('button', {
+        className: 'dm-btn',
+        disabled: !status.channelLatest || props.restarting,
+        title: '查看 ' + (status.channelLatest || '') + ' 的更新内容',
+        onClick: props.onReleaseNotes,
+      }, '更新内容'),
     ),
     h(EditRow, {
       label: '升级命令',
@@ -518,7 +587,7 @@ function UpgradeCard(props) {
           // stale(执行成功但版本未前进/未达目标)时成功行降格为中性表述,不引导重启,
           // 与下方 stale 警告行自洽
           last.ok ? h('span', { className: last.stale === true ? 'dm-warn' : 'dm-ok' },
-              last.stale === true ? '升级命令执行完成,但版本未前进或未达目标' : '升级完成,重启宿主后生效')
+              last.stale === true ? '升级命令执行完成,但结果与安装意图不符' : '升级完成,重启宿主后生效')
             : h('span', { className: 'dm-error' }, '升级失败'
                 + (last.code !== null && last.code !== undefined ? '(退出码 ' + last.code + ')' : '')
                 + (Array.isArray(last.attempts) && last.attempts.length > 1 ? '(已尝试 ' + last.attempts.length + ' 次)' : '')
@@ -534,7 +603,7 @@ function UpgradeCard(props) {
       : null,
     !upgrade.running && last && last.ok === true && last.stale === true
       ? h('div', { className: 'dm-row' },
-          h('span', { className: 'dm-warn' }, '磁盘版本未前进或未达目标: ' + (last.reason || '镜像可能滞后')))
+          h('span', { className: 'dm-warn' }, '安装结果与意图不符: ' + (last.reason || '镜像可能滞后')))
       : null,
     !upgrade.running && last && !last.ok && last.stderrTail
       ? h('pre', { className: 'dm-pre' }, last.stderrTail)
@@ -569,10 +638,8 @@ function OpsCard(props) {
   )
 }
 
-// 升级确认弹窗:展示将执行的命令({tag} 已替换为追踪通道)与自动重启勾选,确认才触发。
-// 自动重启是会话级选择(不持久化),勾/不勾的后果在窗内明示:
-// 勾选=命令成功后宿主延迟 3 秒退出,由进程管理器拉起新版本,页面随宿主恢复自动刷新;
-// 不勾选=宿主继续运行旧版本,面板提示"重启宿主后生效",需手动点重启按钮
+// 安装确认弹窗:展示版本变更(从→到)、将执行的命令({tag} 已替换为追踪通道)与自动重启勾选。
+// 重装修复(目标==运行版本)与回退(目标低于运行版本)是面板显式意图,窗内分类说明
 function UpgradeDialog(props) {
   // 每次打开都重新挂载(MaintainApp 条件渲染),默认勾选随挂载重置
   const [autoRestart, setAutoRestart] = useState(true)
@@ -581,21 +648,24 @@ function UpgradeDialog(props) {
     ? status.upgradeTemplate
     : DEFAULT_UPGRADE_TEMPLATE
   const command = template.split('{tag}').join(status.channel)
+  const changeLine = buildInstallChangeLine(status, command)
   return h('div', { className: 'dm-dialog__mask', onClick: props.onCancel },
     h('div', { className: 'dm-dialog', role: 'dialog', 'aria-modal': 'true', onClick: (e) => e.stopPropagation() },
-      h('div', { className: 'dm-card__title' }, '确认升级'),
-      h('div', { className: 'dm-dialog__hint' }, '将执行以下命令(升级期间页面可离开,进度由右下角浮条提示):'),
+      h('div', { className: 'dm-card__title' }, '确认安装'),
+      h('div', { className: 'dm-dialog__hint' }, buildInstallVersionHint(status)),
+      h('div', { className: 'dm-dialog__hint dm-warn' }, changeLine),
+      h('div', { className: 'dm-dialog__hint' }, '将执行以下命令(安装期间页面可离开,进度由右下角浮条提示):'),
       h('pre', { className: 'dm-pre' }, command),
       h('div', { className: 'dm-dialog__section' },
         h(Switch, {
-          label: '升级完成后自动重启宿主',
+          label: '安装完成后自动重启宿主',
           checked: autoRestart,
           onChange: setAutoRestart,
         }),
         h('div', { className: 'dm-dialog__outcome' },
           autoRestart
-            ? '已勾选:升级命令执行成功后,宿主将在 ' + AUTO_RESTART_DELAY_SEC + ' 秒后自动退出,由你的进程管理器(docker / pm2 / systemd 等)拉起新版本,本页随宿主恢复自动刷新。升级落定后宿主不再执行任何网络请求与磁盘读取。'
-            : '未勾选:升级完成后宿主继续运行当前版本,面板提示「重启宿主后生效」,需要你手动点击重启按钮才切换到新版本。'),
+            ? '已勾选:安装命令执行成功后,宿主将在 ' + AUTO_RESTART_DELAY_SEC + ' 秒后自动退出,由你的进程管理器(docker / pm2 / systemd 等)拉起,本页随宿主恢复自动刷新。安装落定后宿主不再执行任何网络请求与磁盘读取。'
+            : '未勾选:安装完成后宿主继续运行当前版本,面板提示「重启宿主后生效」,需要你手动点击重启按钮才切换到目标版本。'),
         status.runtimeEnv && status.runtimeEnv.kind === RUNTIME_KIND_MANUAL
           ? h('div', { className: 'dm-dialog__outcome dm-warn' }, '当前为手动终端直跑环境:没有进程管理器拉起宿主,勾选自动重启也不会自动退出,完成后仍需手动重启。')
           : null,
@@ -603,7 +673,75 @@ function UpgradeDialog(props) {
       h('div', { className: 'dm-row' },
         h('span', { className: 'dm-spacer' }),
         h('button', { className: 'dm-btn', onClick: props.onCancel }, '取消'),
-        h('button', { className: 'dm-btn', onClick: () => props.onConfirm(autoRestart) }, '开始升级'),
+        h('button', { className: 'dm-btn', onClick: () => props.onConfirm(autoRestart) }, '开始安装'),
+      ),
+    ),
+  )
+}
+
+// release 正文为 markdown+HTML 混排,轻量行渲染:剥 HTML 标签,标题加粗,列表缩进。
+// 全部经 React 文本节点输出(自动转义),外部数据不进 innerHTML;key 用行序号,静态一次性渲染
+function renderNotesBody(body) {
+  const nodes = []
+  let index = 0
+  for (const rawLine of String(body || '').split('\n')) {
+    const line = rawLine.replace(/<[^>]*>/g, '').replace(/\r$/, '')
+    const base = line.trim()
+    const key = 'n' + (index++)
+    if (base.length === 0) {
+      nodes.push(h('div', { className: 'dm-notes__gap', key }))
+    } else if (/^#{1,6}\s+/.test(base)) {
+      nodes.push(h('div', { className: 'dm-notes__h', key }, base.replace(/^#{1,6}\s+/, '')))
+    } else if (/^[-*]\s+/.test(base)) {
+      nodes.push(h('div', { className: 'dm-notes__li', key }, '• ' + base.replace(/^[-*]\s+/, '')))
+    } else {
+      nodes.push(h('div', { key }, line))
+    }
+  }
+  return nodes
+}
+
+// 更新内容弹窗:按版本拉取 GitHub release 说明,展示版本、发布时间、正文与源站链接;
+// 每次打开重新挂载(MaintainApp 条件渲染),拉取失败在窗内展示错误并提供重试与 releases 页兜底
+function ReleaseNotesDialog(props) {
+  const [state, setState] = useState({ phase: 'loading', data: null, error: null })
+  const [attempt, setAttempt] = useState(0)
+  useEffect(() => {
+    let active = true
+    setState({ phase: 'loading', data: null, error: null })
+    api(RELEASE_NOTES_URL)
+      .then((data) => { if (active) setState({ phase: 'ok', data, error: null }) })
+      .catch((error) => { if (active) setState({ phase: 'error', data: null, error }) })
+    return () => { active = false }
+  }, [props.version, attempt])
+  const data = state.phase === 'ok' ? state.data : null
+  return h('div', { className: 'dm-dialog__mask', onClick: props.onClose },
+    h('div', { className: 'dm-dialog', role: 'dialog', 'aria-modal': 'true', onClick: (e) => e.stopPropagation() },
+      h('div', { className: 'dm-card__title' }, '更新内容(' + (data ? data.version : props.version) + ')'),
+      state.phase === 'loading' ? h('div', { className: 'dm-meta' }, '加载中…') : null,
+      state.phase === 'error'
+        ? h('div', { className: 'dm-notice dm-notice--error' },
+            '拉取失败:' + (state.error && state.error.message ? state.error.message : String(state.error)))
+        : null,
+      state.phase === 'error'
+        ? h('div', { className: 'dm-row' },
+            h('button', { className: 'dm-btn', onClick: () => setAttempt(attempt + 1) }, '重试'),
+            h('a', { className: 'dm-link', href: RELEASES_PAGE_URL, target: '_blank', rel: 'noreferrer' }, 'GitHub 全部版本说明'))
+        : null,
+      data
+        ? h('div', { className: 'dm-row' },
+            h('span', { className: 'dm-meta' }, '发布于 ' + (fmtTime(Date.parse(data.publishedAt)) || '未知时间')),
+            data.url ? h('a', { className: 'dm-link', href: data.url, target: '_blank', rel: 'noreferrer' }, '在 GitHub 查看') : null,
+          )
+        : null,
+      data
+        ? (data.body.length > 0
+            ? h('div', { className: 'dm-notes' }, renderNotesBody(data.body))
+            : h('div', { className: 'dm-meta' }, '该版本无发布说明'))
+        : null,
+      h('div', { className: 'dm-row' },
+        h('span', { className: 'dm-spacer' }),
+        h('button', { className: 'dm-btn', onClick: props.onClose }, '关闭'),
       ),
     ),
   )
@@ -616,6 +754,8 @@ function MaintainApp() {
   const [upgradeDialogOpen, setUpgradeDialogOpen] = useState(false)
   const [restartArmed, setRestartArmed] = useState(false)
   const [restarting, setRestarting] = useState(false)
+  // 更新内容弹窗的版本:非 null 即打开;重启等待态随 upgradeDialogOpenLive 同款派生关闭
+  const [notesVersion, setNotesVersion] = useState(null)
   // 重启探测的跨拍状态快照 {lost,pid,bootAt,readyStreak}:lost 与 readyStreak 随拍更新,
   // pid/bootAt 保持确认时刻基线不可被拍结果覆盖,否则重启判定恒 false;null=未在等待态
   const restartPrevRef = useRef(null)
@@ -906,23 +1046,23 @@ function MaintainApp() {
 
   if (status === null) {
     return h('div', { className: 'dm-panel' },
-      h('style', { dangerouslySetInnerHTML: { __html: CSS } }),
+      h('style', { 'data-plugin': '@mzzsfy/dsh-maintain', dangerouslySetInnerHTML: { __html: CSS } }),
       h('span', { className: 'dm-meta' }, error !== null ? '读取失败' : '加载中…'),
       error !== null ? h('div', { className: 'dm-notice dm-notice--error' }, error) : null)
   }
 
   // 升级入口不可用即关闭确认弹窗:渲染时派生,不引入 effect。
-  // 不可用与 VersionCard 按钮 disabled 条件同源(升级进行中/残留锁/已最新/重启中)
+  // 仅瞬态门(升级进行中/重启中);版本状态与残留锁全放行(重装/回退场景),
+  // 提交时 host 的互斥/锁/活跃工作门控照常工作,拒绝原因经 toast 提示
   const upgradeUnavailable = restarting
-    || (status !== null && ((status.upgrade && status.upgrade.running === true)
-      || status.upgradeLockHeld === true
-      || status.verdict === VERDICT_UP_TO_DATE))
+    || (status !== null && status.upgrade && status.upgrade.running === true)
   const upgradeDialogOpenLive = upgradeDialogOpen && !upgradeUnavailable
   // 活跃工作计数:重启确认态显示计数并发 force 越过门控
   const activeWorkTotal = status !== null && status.activeWork ? status.activeWork.total : 0
+  const notesOpenLive = notesVersion !== null && !restarting
 
   return h('div', { className: 'dm-panel' },
-    h('style', { dangerouslySetInnerHTML: { __html: CSS } }),
+    h('style', { 'data-plugin': '@mzzsfy/dsh-maintain', dangerouslySetInnerHTML: { __html: CSS } }),
     h('div', { className: 'dm-head' },
       h('span', { className: 'dm-head__title' }, '版本与运维'),
       h('span', { className: 'dm-head__hint' }, '追踪 npm 新版本,一键升级,安全重启'),
@@ -941,6 +1081,7 @@ function MaintainApp() {
       onChannel,
       onTemplateSave,
       onUpgrade: () => { setRestartArmed(false); setUpgradeDialogOpen(true) },
+      onReleaseNotes: () => { setRestartArmed(false); setNotesVersion(status.channelLatest) },
       onRestart,
     }),
     h(SettingsCard, {
@@ -957,6 +1098,10 @@ function MaintainApp() {
       onCancel: () => setUpgradeDialogOpen(false),
       onConfirm: onUpgrade,
     }) : null,
+    notesOpenLive ? h(ReleaseNotesDialog, {
+      version: notesVersion,
+      onClose: () => setNotesVersion(null),
+    }) : null,
   )
 }
 

package/src/core.mjs

@@ -91,12 +91,40 @@ export function isVersionPendingRestart({ runningVersion, installedVersion }) {
   return Boolean(parseSemver(runningVersion) && parseSemver(installedVersion) && gtSemver(installedVersion, runningVersion))
 }
 
-// 升级后磁盘版本复读判定:stale=版本未前进(镜像滞后/静默未升)或未达通道目标。
+// 从已解析安装命令提取钉定版本(形如 @x.y.z[-pre][+build] 的精确版本 token),
+// 取最后一个合法者(包说明符通常在命令尾部);token 只在 semver 字符集内截取,
+// shell 粘连(&&、;、>)不参与;通道名/@latest/非法形态不命中,无钉定返回 null。
+// 约束:semver 形态的通道名({tag} 展开产物)不属钉定,调用方须排除与通道名重合的 token
+const PINNED_TOKEN_PATTERN = /@([0-9A-Za-z][0-9A-Za-z.+-]*)/g
+export function extractPinnedVersion(command) {
+  const text = typeof command === 'string' ? command : ''
+  let pinned = null
+  for (const match of text.matchAll(PINNED_TOKEN_PATTERN)) {
+    if (parseSemver(match[1]) !== null) pinned = match[1]
+  }
+  return pinned
+}
+
+// 升级后磁盘版本复读判定:stale=结果与安装意图不符。意图优先级:
+// 钉定版本(命令含 @x.y.z)→ 恰装到该版本才算达成,通道目标不参与对拍;
+// 通道语义:目标>来版=升级(未前进/未达皆 stale);目标<=来版=重装或回退,
+// 恰落到通道目标即达成(重装版本不变是预期,回退方向不套"未前进"口径)。
 // previous 未知只豁免"未前进"分支;目标缺失时无法证明未达标,宽松判 fresh 不误报。
-export function judgeUpgradeFreshness({ previousVersion, installedVersion, channelLatest }) {
+export function judgeUpgradeFreshness({ previousVersion, installedVersion, channelLatest, pinnedVersion }) {
   if (!parseSemver(installedVersion)) {
     return { stale: true, reason: '升级后磁盘版本解析失败' + (installedVersion ? ': ' + installedVersion : '(读取失败)') }
   }
+  if (parseSemver(pinnedVersion)) {
+    return compareSemver(installedVersion, pinnedVersion) === 0
+      ? { stale: false, reason: null }
+      : { stale: true, reason: '未安装到指定版本: ' + installedVersion + '(命令钉定 ' + pinnedVersion + ')' }
+  }
+  if (parseSemver(previousVersion) !== null && parseSemver(channelLatest) !== null
+    && compareSemver(channelLatest, previousVersion) <= 0) {
+    return compareSemver(installedVersion, channelLatest) === 0
+      ? { stale: false, reason: null }
+      : { stale: true, reason: '未落到通道目标: ' + installedVersion + '(通道目标 ' + channelLatest + ')' }
+  }
   if (parseSemver(previousVersion) && !gtSemver(installedVersion, previousVersion)) {
     return { stale: true, reason: '磁盘版本未前进,升级可能静默失败或镜像滞后: ' + installedVersion }
   }
@@ -188,22 +216,12 @@ export function isValidRegistryBase(base) {
   }
 }
 
-// dist-tags 响应体上限:正常响应远小于此;流式累计读取,超限即断
-const DIST_TAGS_MAX_BYTES = 64 * 1024
+// 上游响应体上限:dist-tags 正常响应远小于此;流式累计读取,超限即断
+const UPSTREAM_BODY_MAX_BYTES = 64 * 1024
 
-// 拉取 dist-tags 轻量端点;fetchImpl 注入便于单测,错误一律抛出由调用方决定保留上次结果。
-// redirect 拒绝跟随:镜像 302 跳内网/他源属配置外行为,直接失败交调用方展示。
-export async function fetchDistTags({ registryBase, fetchImpl = fetch, timeoutMs }) {
-  if (!isValidRegistryBase(registryBase)) throw new Error('registry 基地址无效: ' + registryBase)
-  if (!(Number.isFinite(timeoutMs) && timeoutMs > 0)) throw new Error('timeoutMs 必须为正数')
-  const base = registryBase.trim().replace(/\/+$/, '')
-  const response = await fetchImpl(base + DIST_TAGS_PATH, {
-    headers: { accept: 'application/json' },
-    redirect: 'error',
-    signal: AbortSignal.timeout(timeoutMs),
-  })
-  if (!response.ok) throw new Error('registry HTTP ' + response.status)
-  // 流式累计限量:恶意/异常源的超大响应体在传输中途即被断开,不整量入内存
+// 上游响应体流式限量读取:恶意/异常源的超大响应体在传输中途即被断开,不整量入内存。
+// json() 对 BOM 有容忍;text 路径显式剥除保持等价;maxBytes 按数据源传入(发布页更大)
+async function readBodyTextLimited(response, maxBytes = UPSTREAM_BODY_MAX_BYTES) {
   const reader = response.body.getReader()
   const chunks = []
   let total = 0
@@ -212,7 +230,7 @@ export async function fetchDistTags({ registryBase, fetchImpl = fetch, timeoutMs
       const { done, value } = await reader.read()
       if (done) break
       total += value.byteLength
-      if (total > DIST_TAGS_MAX_BYTES) throw new Error('dist-tags 响应超过上限')
+      if (total > maxBytes) throw new Error('响应超过上限')
       chunks.push(value)
     }
   } finally {
@@ -224,8 +242,22 @@ export async function fetchDistTags({ registryBase, fetchImpl = fetch, timeoutMs
     merged.set(chunk, offset)
     offset += chunk.byteLength
   }
-  // json() 对 BOM 有容忍;text 路径显式剥除保持等价
-  const text = new TextDecoder().decode(merged).replace(/^\uFEFF/, '')
+  return new TextDecoder().decode(merged).replace(/^\uFEFF/, '')
+}
+
+// 拉取 dist-tags 轻量端点;fetchImpl 注入便于单测,错误一律抛出由调用方决定保留上次结果。
+// redirect 拒绝跟随:镜像 302 跳内网/他源属配置外行为,直接失败交调用方展示。
+export async function fetchDistTags({ registryBase, fetchImpl = fetch, timeoutMs }) {
+  if (!isValidRegistryBase(registryBase)) throw new Error('registry 基地址无效: ' + registryBase)
+  if (!(Number.isFinite(timeoutMs) && timeoutMs > 0)) throw new Error('timeoutMs 必须为正数')
+  const base = registryBase.trim().replace(/\/+$/, '')
+  const response = await fetchImpl(base + DIST_TAGS_PATH, {
+    headers: { accept: 'application/json' },
+    redirect: 'error',
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  if (!response.ok) throw new Error('registry HTTP ' + response.status)
+  const text = await readBodyTextLimited(response)
   let body
   try {
     body = JSON.parse(text)
@@ -283,3 +315,91 @@ export async function resolveHostVersion({ execPath, platform, argv1, readFileIm
   }
   return null
 }
+
+// 版本更新内容事实源:npm 清单无 readme 字段(实测),官方 GitHub Releases 承载,
+// tag 命名 dsh-v<版本> 与 TARGET_PACKAGE 同为该包的固定事实,随包常量维护。
+// 数据源为 releases 页面而非 api.github.com:未认证 API 限流 60 次/小时/IP 且按 IP 共享,
+// 页面限流实际宽松(实测同机 API 403 时页面 200);页面 URL 自建,无需远端 URL 白名单。
+export const RELEASE_SITE_BASE = 'https://github.com'
+export const RELEASE_REPO = 'deepseek-ai/deepseek-harness'
+export const RELEASE_TAG_PREFIX = 'dsh-v'
+// 发布页响应体上限:实测页面约 256KB,留余量;流式截断纪律与 dist-tags 一致
+const RELEASE_PAGE_MAX_BYTES = 512 * 1024
+
+// 发布标签构建:版本必须为合法 semver(远端数据回流 URL 前的白名单校验),首尾空白归一
+export function buildReleaseTag(version) {
+  const text = typeof version === 'string' ? version.trim() : ''
+  if (!parseSemver(text)) throw new Error('版本不是合法 semver: ' + version)
+  return RELEASE_TAG_PREFIX + text
+}
+
+export function buildReleaseNotesUrl(version) {
+  return RELEASE_SITE_BASE + '/' + RELEASE_REPO + '/releases/tag/' + encodeURIComponent(buildReleaseTag(version))
+}
+
+// 发布页正文提取:markdown-body 容器为锚点(GitHub 官方 test-selector,实测恰一处),
+// div 令牌深度配对取完整内层,渲染后 HTML 映射回行结构文本(标题→# 前缀、列表→- 前缀、
+// 块级闭合→换行、实体解码);标签剥离先于实体解码,解码产物只能是文本节点,经 React 转义无注入面
+const RELEASE_TIME_PATTERN = /<relative-time[^>]*\bdatetime="([^"]+)"/
+
+export function extractReleaseNotesFromHtml(html) {
+  const text = typeof html === 'string' ? html : ''
+  const time = RELEASE_TIME_PATTERN.exec(text)
+  const anchor = text.indexOf('markdown-body')
+  const openStart = anchor < 0 ? -1 : text.lastIndexOf('<div', anchor)
+  if (openStart < 0) throw new Error('release 页面结构无法解析')
+  const token = /<\/?div\b[^>]*>/g
+  token.lastIndex = openStart
+  let depth = 0
+  let end = -1
+  for (let m; (m = token.exec(text)) !== null;) {
+    depth += m[0][1] === '/' ? -1 : 1
+    if (depth === 0) {
+      end = m.index + m[0].length
+      break
+    }
+  }
+  if (end < 0) throw new Error('release 页面结构无法解析')
+  return { publishedAt: time ? time[1] : null, body: mapReleaseHtmlToText(text.slice(openStart, end)) }
+}
+
+function mapReleaseHtmlToText(inner) {
+  return inner
+    .replace(/>\s+</g, '><')
+    .replace(/<h([1-6])[^>]*>/g, (m, level) => '\n' + '#'.repeat(Number(level)) + ' ')
+    .replace(/<\/h[1-6]>/g, '\n')
+    .replace(/<li[^>]*>/g, '- ')
+    .replace(/<\/(p|li|ul|ol|pre|blockquote|tr|div)>/g, '\n')
+    .replace(/<br[^>]*>/g, '\n')
+    .replace(/<[^>]*>/g, '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&apos;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&#x([0-9a-fA-F]+);/g, (m, hex) => String.fromCodePoint(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (m, dec) => String.fromCodePoint(Number(dec)))
+    .replace(/&amp;/g, '&')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+// 按版本拉取 releases 页面更新内容;fetchImpl 注入便于单测,错误一律抛出由调用方归一。
+// 显式 User-Agent 与 redirect 拒绝跟随同 fetchDistTags 纪律
+export async function fetchReleaseNotes({ version, fetchImpl = fetch, timeoutMs }) {
+  if (!(Number.isFinite(timeoutMs) && timeoutMs > 0)) throw new Error('timeoutMs 必须为正数')
+  const url = buildReleaseNotesUrl(version)
+  const response = await fetchImpl(url, {
+    headers: { accept: 'text/html', 'user-agent': 'dsh-maintain' },
+    redirect: 'error',
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  if (!response.ok) {
+    throw new Error(response.status === 404
+      ? '未找到该版本的发布说明(该版本可能未发布 Release)'
+      : 'GitHub HTTP ' + response.status)
+  }
+  const text = await readBodyTextLimited(response, RELEASE_PAGE_MAX_BYTES)
+  const { publishedAt, body } = extractReleaseNotesFromHtml(text)
+  return { url, publishedAt, body }
+}