@mzzsfy/dsh-maintain 0.8.0 → 0.10.0

package/src/index.js

@@ -12,8 +12,10 @@ import {
   TARGET_PACKAGE,
   TAG_PLACEHOLDER,
   buildUpgradeCommand,
+  extractPinnedVersion,
   classifyUpgradeFailure,
   fetchDistTags,
+  fetchReleaseNotes,
   isValidChannelName,
   isValidRegistryBase,
   isVersionPendingRestart,
@@ -22,10 +24,8 @@ import {
   resolveHostVersion,
   UPGRADE_FAIL_FILE_LOCKED,
   UPGRADE_FAIL_TRANSIENT_NETWORK,
-  VERDICT_UP_TO_DATE,
 } from './core.mjs'
 import { runUpgrade } from './upgrade.mjs'
-import { detectRuntimeEnv, RUNTIME_KINDS } from './runtime.mjs'
 
 export const name = 'dsh-maintain'
 
@@ -36,6 +36,9 @@ export const inject = ['webServer']
 const NAMESPACE = 'maintain'
 
 const CHECK_TIMEOUT_MS = 20 * 1000
+// 版本更新内容缓存上限:长期运行中通道切换持续产生新键,无上限则缓存无界;
+// 超限删最旧(Map 迭代序即插入序,命中不重插);导出仅供测试
+export const RELEASE_NOTES_CACHE_MAX = 20
 // 升级命令超时:client 浮条观察上限与此对拍(parity 锁定),强杀宽限另计
 export const UPGRADE_TIMEOUT_MS = 10 * 60 * 1000
 // 响应发出到执行退出的延迟:保证浏览器收到 200 并进入重启等待态,进程才离场;
@@ -204,16 +207,15 @@ export async function runUpgradeWithRetry({ command, timeoutMs = UPGRADE_TIMEOUT
   return { attempts, ok: false, kind: null, stillRunning: false, stdoutTail: '', stderrTail: '', error: null }
 }
 
-// 升级后自动重启守卫:四条件缺一不可——成功、非手动直跑、本次勾选 enabled、appExit 可用。
-// 手动直跑(双 TTY)进程退出后无人拉起,只标 requiresManualRestart 交面板指引,
-// 该指引是环境约束事实,不受勾选影响;enabled 由升级路由严格 boolean 校验保证
+// 升级后自动重启守卫:三条件缺一不可——成功、本次勾选 enabled、appExit 可用。
+// 宿主退出动作与面板"确认重启"完全同一调度入口,拉起责任归启动方式:
+// 托管环境由进程管理器拉起,手动直跑等同点了重启按钮后自行再启动
 // 无 stale 条件:版本复读属升级后磁盘读取,关机路径禁止;版本是否前进由重启后的启动检查呈现
-export function judgeAutoRestart({ ok, runtimeKind, hasExit, enabled }) {
-  if (ok !== true) return { schedule: false, requiresManualRestart: false }
-  if (runtimeKind === RUNTIME_KINDS.MANUAL_START) return { schedule: false, requiresManualRestart: true }
-  if (enabled !== true) return { schedule: false, requiresManualRestart: false }
-  if (hasExit !== true) return { schedule: false, requiresManualRestart: false }
-  return { schedule: true, requiresManualRestart: false }
+export function judgeAutoRestart({ ok, hasExit, enabled }) {
+  if (ok !== true) return { schedule: false }
+  if (enabled !== true) return { schedule: false }
+  if (hasExit !== true) return { schedule: false }
+  return { schedule: true }
 }
 
 // 浏览器半区调用的 API 路径清单:client.js 同名常量与之对拍(parity),防单侧改路径生产 404
@@ -226,6 +228,7 @@ export const API_PATHS = Object.freeze({
   REGISTRY_BASE: '/api/maintain/registry-base',
   UPGRADE: '/api/maintain/upgrade',
   RESTART: '/api/maintain/restart',
+  RELEASE_NOTES: '/api/maintain/release-notes',
 })
 
 // 宿主进程启动时刻:重启探测的第三代际信号(容器内 pid 恒 1 且零失联时 pid 信号失效)
@@ -381,21 +384,13 @@ export function apply(ctx) {
   const runningVersionReady = resolveCurrentHostVersion()
     .then((version) => { runningVersion = version })
     .catch(() => {})
-
-  // 运行环境:apply 时一次检测;探测异步,以 ready 链收口,异常回退 unknown(维持自动重启)
-  let runtimeEnv = { kind: RUNTIME_KINDS.UNKNOWN, declared: false }
-  const runtimeEnvReady = detectRuntimeEnv({
-    env: process.env,
-    platform: process.platform,
-    isTTY: { stdin: process.stdin.isTTY === true, stdout: process.stdout.isTTY === true },
-  })
-    .then((env) => { runtimeEnv = env })
-    .catch(() => {})
   let upgrade = { running: false, last: null }
   let checkInFlight = null
   let nextDueAt = null
   let restartScheduled = false
   let autoRestartScheduled = false
+  // 版本更新内容缓存:键为通道最新版原始值(未归一),值为 {url,publishedAt,body};仅成功结果入缓存
+  const releaseNotesCache = new Map()
 
   function runCheck() {
     if (checkInFlight) return checkInFlight
@@ -453,8 +448,8 @@ export function apply(ctx) {
   }
 
   async function currentStatus() {
-    // 等运行版本首读与运行环境检测落定:apply 即发起,此处仅吸收启动窗口的微小延迟
-    await Promise.all([runningVersionReady, runtimeEnvReady])
+    // 等运行版本首读落定:apply 即发起,此处仅吸收启动窗口的微小延迟
+    await runningVersionReady
     const config = readSettings(ctx)
     const judged = judgeNow()
     // running 即视为持锁:省一次盘读,且窗口期语义与 upgrade 路由的门闩一致
@@ -479,7 +474,6 @@ export function apply(ctx) {
       checkedAt: snapshot.checkedAt,
       checkError: snapshot.error,
       upgrade,
-      runtimeEnv,
       autoRestartScheduled,
       activeWork: collectActiveWork(ctx),
       canRestart: typeof exit === 'function',
@@ -490,8 +484,12 @@ export function apply(ctx) {
     const config = readSettings(ctx)
     // 模板校验同步失败即同步 throw,由调用方 try/catch 转 400,不走异步通道
     const command = buildUpgradeCommand({ template: config.upgradeCommandTemplate, tag: config.channel })
+    // 通道名恰为 semver 形态时 {tag} 展开产物会被误读为钉定:与通道名重合即非钉定
+    const pinnedVersion = extractPinnedVersion(command)
     const last = {
       command,
+      // 钉定版本随命令定格:落定复读按安装意图(钉定/通道)判定 stale
+      pinnedVersion: pinnedVersion === config.channel ? null : pinnedVersion,
       startedAt: Date.now(),
       ok: false,
       finishedAt: null,
@@ -581,11 +579,9 @@ export function apply(ctx) {
         + (last.stale === true ? ' stale=' + singleLine(last.reason) : ''))
       audit('upgrade', last.ok === true ? 'ok' : 'failed',
         'durationMs=' + (last.finishedAt - last.startedAt) + ' code=' + last.code + ' kind=' + singleLine(last.kind))
-      // 关机前置判定只取内存输入(启动期缓存的运行环境 + 本次会话勾选):升级命令刚
+      // 关机前置判定只取内存输入(本次会话勾选 + 启动器退出能力):升级命令刚
       // 替换过宿主磁盘文件,落定钩子发起网络请求或读取磁盘都是半写状态下的故障源
-      await runtimeEnvReady
-      const decision = judgeAutoRestart({ ok: last.ok === true, runtimeKind: runtimeEnv.kind, hasExit: typeof exit === 'function', enabled: autoRestart === true })
-      if (decision.requiresManualRestart === true) last.requiresManualRestart = true
+      const decision = judgeAutoRestart({ ok: last.ok === true, hasExit: typeof exit === 'function', enabled: autoRestart === true })
       if (decision.schedule === true) {
         // 关机路径零收尾:与确认重启同一内部动作,直接进入延迟退出
         // last 镜像调度标记:浮条终态文案按其分流(与 status.autoRestartScheduled 同值)
@@ -593,7 +589,7 @@ export function apply(ctx) {
         scheduleHostExit({ detail: 'reason=upgrade-ok', autoRestart: true, delayMs: AUTO_RESTART_DELAY_MS })
         return
       }
-      // 继续运行路径(失败/手动直跑/本次未勾选自动重启):复读磁盘版本标 stale,版本未前进提示保留
+      // 继续运行路径(失败/本次未勾选自动重启/appExit 缺失):复读磁盘版本标 stale,版本未前进提示保留
       if (settle !== null && settle.ok) {
         // 复读属磁盘消费点,拒绝不得以 unhandledRejection 形式逃逸(void 触发即崩宿主):
         // 失败时放弃 stale 判定,保留已装版本 null 由启动检查兜底呈现
@@ -604,6 +600,7 @@ export function apply(ctx) {
             previousVersion: last.previousVersion,
             installedVersion: last.installedVersion,
             channelLatest: tags !== null && Object.prototype.hasOwnProperty.call(tags, channel) ? tags[channel] : null,
+            pinnedVersion: last.pinnedVersion,
           })
           last.stale = freshness.stale
           last.reason = freshness.reason
@@ -756,14 +753,6 @@ export function apply(ctx) {
           sendJson(res, 409, { error: '存在未过期的升级锁(可能有残留升级子进程),等待锁过期或删除 ' + UPGRADE_LOCK_PATH })
           return
         }
-        // 防降级:运行版本已达通道最新时拒绝(重装旧版即降级,对齐 no-newer-version);
-        // 信息不足(verdict unknown)放行,宽松不误拒
-        const judged = judgeNow()
-        if (judged.verdict === VERDICT_UP_TO_DATE) {
-          audit('upgrade', 'rejected', 'reason=up-to-date')
-          sendJson(res, 409, { error: '当前已是通道最新版,无需升级;重装请走命令行' })
-          return
-        }
         // 活跃工作门控:升级不可越(agent 会话/job 在跑时强行升级会被中断)
         const activeWork = collectActiveWork(ctx)
         if (activeWork.total > 0) {
@@ -820,6 +809,33 @@ export function apply(ctx) {
         scheduleHostExit({ detail: 'forced=' + (requestBody.force === true), delayMs: RESTART_DELAY_MS })
       }),
     },
+    {
+      path: API_PATHS.RELEASE_NOTES,
+      handler: route('GET', {}, async (req, res) => {
+        // 关机窗口内不发上游请求:退出延迟 2 秒小于上游超时,与 refresh 同纪律
+        if (restartScheduled) {
+          sendJson(res, 409, { error: '重启已调度,禁止查询更新内容' })
+          return
+        }
+        // 缺省恒取追踪通道最新版;上游标签值非 semver 时 buildReleaseTag 抛错归一 400
+        const version = judgeNow().channelLatest
+        if (!version) {
+          sendJson(res, 400, { error: '通道最新版未知,请先检查更新' })
+          return
+        }
+        const cached = releaseNotesCache.get(version)
+        if (cached) {
+          sendJson(res, 200, { version, url: cached.url, publishedAt: cached.publishedAt, body: cached.body })
+          return
+        }
+        const notes = await fetchReleaseNotes({ version, timeoutMs: CHECK_TIMEOUT_MS })
+        releaseNotesCache.set(version, notes)
+        while (releaseNotesCache.size > RELEASE_NOTES_CACHE_MAX) {
+          releaseNotesCache.delete(releaseNotesCache.keys().next().value)
+        }
+        sendJson(res, 200, { version, url: notes.url, publishedAt: notes.publishedAt, body: notes.body })
+      }),
+    },
   ]
 
   for (const route of routes) {

package/test/client-id.test.mjs

@@ -13,4 +13,21 @@ test('client.js 注册 id 为完整包名', () => {
   const match = source.match(/__ModuleLoader__\.load\(\{\s*id:\s*'([^']+)'/)
   assert.ok(match, 'client.js 缺少 __ModuleLoader__.load 注册')
   assert.equal(match[1], name)
+})
+
+test('client.js 样式注入自带 data-plugin', () => {
+  const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+  const injections = source.split("createElement('style')").length - 1
+  assert.ok(injections > 0, 'client.js 无样式注入点')
+  const marked = source.split(`setAttribute('data-plugin', '${name}')`).length - 1
+  assert.equal(marked, injections, '每个样式注入点都必须自带 data-plugin(值=注册包名),防宿主 claimStyles 误归属后随他插件 HMR 整批误删')
+})
+
+test('client.js 样式渲染自带 data-plugin', () => {
+  const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+  // 渲染点计数用 ('style', { 精确命中 React 形态,排除 DOM 形态的 createElement('style')
+  const renders = source.split("('style', {").length - 1
+  assert.ok(renders > 0, 'client.js 无样式渲染点')
+  const marked = source.split("('style', { 'data-plugin'").length - 1
+  assert.equal(marked, renders, '每个样式渲染点都必须携带 data-plugin(值=注册包名),防宿主 claimStyles 误归属后随他插件 HMR 整批误删')
 })

package/test/core.test.mjs

@@ -6,6 +6,7 @@ import {
   gtSemver,
   judgeVersion,
   judgeUpgradeFreshness,
+  extractPinnedVersion,
   isVersionPendingRestart,
   classifyUpgradeFailure,
   buildUpgradeCommand,
@@ -263,6 +264,25 @@ test('分类:输入字段缺省容忍不抛错', () => {
   assert.ok(typeof result.reason === 'string')
 })
 
+// 钉定版本提取:取命令中最后一个合法 semver token(包说明符通常在尾部);
+// 通道名/@latest/无版本形态天然不命中;shell 粘连(&&、;、>)在 token 边界截断
+test('钉定版本:提取命令中的 @x.y.z token,取最后合法者', () => {
+  assert.equal(extractPinnedVersion('npm install -g @deepseek-ai/dsh@0.1.4'), '0.1.4')
+  assert.equal(extractPinnedVersion('npm install -g @deepseek-ai/dsh@0.1.4 --silent'), '0.1.4')
+  assert.equal(extractPinnedVersion('npm i -g @deepseek-ai/dsh@0.1.4 && echo ok'), '0.1.4')
+  assert.equal(extractPinnedVersion('@scope/pkg@1.2.3-rc.1'), '1.2.3-rc.1')
+  assert.equal(extractPinnedVersion('pkg@1.2.3+build.7'), '1.2.3+build.7')
+  assert.equal(extractPinnedVersion('a@1.0.0 b@2.0.0'), '2.0.0')
+  assert.equal(extractPinnedVersion('npm install -g @deepseek-ai/dsh@{tag}'), null)
+  assert.equal(extractPinnedVersion('npm install -g @deepseek-ai/dsh@latest'), null)
+  assert.equal(extractPinnedVersion('node -e "process.exit(0)"'), null)
+  assert.equal(extractPinnedVersion('pkg@0.1.4beta'), null)
+  assert.equal(extractPinnedVersion('pkg@01.2.3'), null)
+  assert.equal(extractPinnedVersion('@@1.0.0'), '1.0.0')
+  assert.equal(extractPinnedVersion(''), null)
+  assert.equal(extractPinnedVersion(null), null)
+})
+
 // 升级后磁盘版本复读判定:stale=版本未前进或未达通道目标;信息缺失宽松不误报。
 test('复读:版本前进且达通道目标判 fresh', () => {
   assert.deepEqual(judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: '2.0.0', channelLatest: '2.0.0' }), { stale: false, reason: null })
@@ -276,6 +296,37 @@ test('复读:磁盘版本未前进或回退判 stale', () => {
   assert.match(same.reason, /未前进/)
   const rollback = judgeUpgradeFreshness({ previousVersion: '2.0.0', installedVersion: '1.9.0', channelLatest: '2.0.0' })
   assert.equal(rollback.stale, true)
+  // 目标==来版属重装/回退意图:失败原因按"未落到通道目标"口径,不得走"未前进"文案
+  assert.match(rollback.reason, /通道目标/)
+})
+
+// 重装场景(通道目标与来版相同):版本不前进是预期结果,不得误报 stale
+test('复读:重装(目标==来版)版本不变判 fresh', () => {
+  assert.deepEqual(judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: '1.0.0', channelLatest: '1.0.0' }), { stale: false, reason: null })
+})
+
+test('复读:重装场景装出更低版本判 stale(未落到通道目标)', () => {
+  const result = judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: '0.9.0', channelLatest: '1.0.0' })
+  assert.equal(result.stale, true)
+  assert.match(result.reason, /通道目标/)
+})
+
+// 切通道回退(目标<来版):恰落到通道目标即达成;静默未动(磁盘仍是来版)必须拦下
+test('复读:回退落到通道目标判 fresh,静默未动判 stale', () => {
+  assert.deepEqual(judgeUpgradeFreshness({ previousVersion: '0.2.0-rc.1', installedVersion: '0.1.5', channelLatest: '0.1.5' }), { stale: false, reason: null })
+  const silent = judgeUpgradeFreshness({ previousVersion: '0.2.0-rc.1', installedVersion: '0.2.0-rc.1', channelLatest: '0.1.5' })
+  assert.equal(silent.stale, true)
+  assert.match(silent.reason, /通道目标/)
+})
+
+// 钉定版本(命令含 @x.y.z):意图=精确版本,装到位即达成,通道目标不参与对拍
+test('复读:钉定版本装到位判 fresh,装偏判 stale', () => {
+  assert.deepEqual(judgeUpgradeFreshness({ previousVersion: '0.1.5', installedVersion: '0.1.4', channelLatest: '0.1.5', pinnedVersion: '0.1.4' }), { stale: false, reason: null })
+  assert.deepEqual(judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: '1.0.0', channelLatest: '2.0.0', pinnedVersion: '1.0.0' }), { stale: false, reason: null })
+  const missed = judgeUpgradeFreshness({ previousVersion: '0.1.5', installedVersion: '0.1.5', channelLatest: '0.1.5', pinnedVersion: '0.1.4' })
+  assert.equal(missed.stale, true)
+  assert.match(missed.reason, /指定版本/)
+  assert.deepEqual(judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: '1.2.3-rc.1', channelLatest: '2.0.0', pinnedVersion: '1.2.3-rc.1' }), { stale: false, reason: null })
 })
 
 test('复读:前进但未达通道目标判 stale', () => {

package/test/parity.test.mjs

@@ -10,6 +10,7 @@ import { fileURLToPath } from 'node:url'
 import {
   shouldReloadAfterRestart as coreShouldReload,
   isValidRegistryBase as coreIsValidRegistryBase,
+  extractPinnedVersion as coreExtractPinnedVersion,
   VERDICT_OUTDATED,
   VERDICT_UP_TO_DATE,
   VERDICT_UNKNOWN,
@@ -40,6 +41,113 @@ function extractNumberConst(name) {
 
 const clientShouldReload = extractLogic('shouldReloadAfterRestart')
 const clientIsValidRegistryBase = extractLogic('isValidRegistryBase')
+const clientExtractPinnedVersion = extractLogic('extractPinnedVersion')
+// 弹窗文案分支依赖钉定检测:直接注 core 实现,顺带证明两侧检测可互换
+const clientBuildInstallChangeLine = extractLogic('buildInstallChangeLine', {
+  extractPinnedVersion: coreExtractPinnedVersion,
+  VERDICT_OUTDATED,
+  VERDICT_UNKNOWN,
+})
+const clientBuildInstallVersionHint = extractLogic('buildInstallVersionHint')
+
+// 命令钉定 token 提取:双实现对拍 + 语义锚(尾部取最后合法者/通道名与 @latest 不命中/shell 粘连截断)
+const PINNED_CASES = [
+  { command: 'npm install -g @deepseek-ai/dsh@0.1.4', expected: '0.1.4' },
+  { command: 'npm install -g @deepseek-ai/dsh@0.1.4 --silent', expected: '0.1.4' },
+  { command: 'npm i -g @deepseek-ai/dsh@0.1.4 && echo ok', expected: '0.1.4' },
+  { command: '@scope/pkg@1.2.3-rc.1', expected: '1.2.3-rc.1' },
+  { command: 'pkg@1.2.3+build.7', expected: '1.2.3+build.7' },
+  { command: 'a@1.0.0 b@2.0.0', expected: '2.0.0' },
+  { command: 'npm install -g @deepseek-ai/dsh@{tag}', expected: null },
+  { command: 'npm install -g @deepseek-ai/dsh@latest', expected: null },
+  { command: 'node -e "process.exit(0)"', expected: null },
+  { command: 'pkg@0.1.4beta', expected: null },
+  { command: 'pkg@01.2.3', expected: null },
+  { command: '@@1.0.0', expected: '1.0.0' },
+  { command: '', expected: null },
+  { command: null, expected: null },
+]
+
+test('parity: extractPinnedVersion 双实现全场景一致', () => {
+  for (const { command, expected } of PINNED_CASES) {
+    assert.equal(coreExtractPinnedVersion(command), expected, 'core ' + JSON.stringify(command))
+    assert.equal(clientExtractPinnedVersion(command), expected, 'client ' + JSON.stringify(command))
+  }
+})
+
+// 弹窗版本变更行:钉定优先(含改回 {tag} 指引),通道语义按 未知/重装/升级/无法判定/回退 分支
+test('parity: buildInstallChangeLine 分支行为', () => {
+  const base = { channel: 'latest', channelLatest: null, runningVersion: null, installedVersion: null, verdict: VERDICT_UNKNOWN }
+  // 钉定:模板含 @x.y.z 即按指定版本表述,并提示改回 {tag}
+  const pinned = clientBuildInstallChangeLine(
+    { ...base, channelLatest: '0.1.5', runningVersion: '0.1.5' },
+    'npm install -g @deepseek-ai/dsh@0.1.4')
+  assert.ok(pinned.includes('0.1.4'), pinned)
+  assert.ok(pinned.includes('指定版本'), pinned)
+  assert.ok(pinned.includes('{tag}'), pinned)
+  // 通道目标未知
+  assert.ok(clientBuildInstallChangeLine({ ...base }, 'npm install -g @deepseek-ai/dsh@latest').includes('未知'))
+  // 重装:目标==运行;已装领先(待生效)时提示将被替换
+  const reinstall = clientBuildInstallChangeLine(
+    { ...base, channelLatest: '0.1.5', runningVersion: '0.1.5', installedVersion: '0.2.0-rc.1', verdict: VERDICT_UP_TO_DATE },
+    'npm install -g @deepseek-ai/dsh@latest')
+  assert.ok(reinstall.includes('重装'), reinstall)
+  assert.ok(reinstall.includes('0.2.0-rc.1'), reinstall)
+  const reinstallClean = clientBuildInstallChangeLine(
+    { ...base, channelLatest: '0.1.5', runningVersion: '0.1.5', installedVersion: '0.1.5', verdict: VERDICT_UP_TO_DATE },
+    'npm install -g @deepseek-ai/dsh@latest')
+  assert.ok(!reinstallClean.includes('替换'), reinstallClean)
+  // 升级
+  const upgrade = clientBuildInstallChangeLine(
+    { ...base, channelLatest: '0.2.0', runningVersion: '0.1.5', verdict: VERDICT_OUTDATED },
+    'npm install -g @deepseek-ai/dsh@latest')
+  assert.ok(upgrade.includes('升级') && upgrade.includes('0.2.0'), upgrade)
+  // 无法判定:unknown 且目标非空,归因中性(目标非法/运行非法两种来源)
+  const undetermined = clientBuildInstallChangeLine(
+    { ...base, channelLatest: '0.2.0', runningVersion: 'dev-main', verdict: VERDICT_UNKNOWN },
+    'npm install -g @deepseek-ai/dsh@latest')
+  assert.ok(undetermined.includes('无法判定'), undetermined)
+  // 回退:up-to-date 且目标!=运行,表述不断言方向(semver 等值字面不同时同样成立)
+  const rollback = clientBuildInstallChangeLine(
+    { ...base, channelLatest: '0.1.5', runningVersion: '0.2.0-rc.1', verdict: VERDICT_UP_TO_DATE },
+    'npm install -g @deepseek-ai/dsh@latest')
+  assert.ok(rollback.includes('不高于'), rollback)
+  assert.ok(rollback.includes('0.1.5'), rollback)
+  // semver 形态通道名:命令中的 @1.0.0 是 {tag} 展开产物,按通道语义(重装)而非钉定表述
+  const semverChannel = clientBuildInstallChangeLine(
+    { ...base, channel: '1.0.0', channelLatest: '1.0.0', runningVersion: '1.0.0', installedVersion: '1.0.0', verdict: VERDICT_UP_TO_DATE },
+    'npm install -g @deepseek-ai/dsh@1.0.0')
+  assert.ok(!semverChannel.includes('指定版本'), semverChannel)
+  assert.ok(semverChannel.includes('重装'), semverChannel)
+})
+
+// 弹窗当前版本行:缺失回退"未知"(渲染级防回归——该行曾在组件内联,作用域变量删除后渲染即崩)
+test('parity: buildInstallVersionHint 缺失回退未知', () => {
+  assert.equal(clientBuildInstallVersionHint({ runningVersion: '0.1.5', installedVersion: '0.1.5' }), '版本变更:当前 运行 0.1.5 / 已装 0.1.5')
+  assert.equal(clientBuildInstallVersionHint({ installedVersion: '0.1.5' }), '版本变更:当前 运行 未知 / 已装 0.1.5')
+  assert.equal(clientBuildInstallVersionHint({}), '版本变更:当前 运行 未知 / 已装 未知')
+})
+
+// 弹窗渲染冒烟:整函数工厂化执行,自由变量全桩注入,断言不抛错且关键行在树中。
+// 动态文案(版本行/变更行)已抽 LOGIC 段,此测试兜住组件体对桩外符号的引用回归
+test('渲染冒烟: UpgradeDialog 工厂化执行不抛错且含版本变更行', () => {
+  const match = CLIENT_SOURCE.match(/function UpgradeDialog\(props\) \{[\s\S]*?\n\}/)
+  assert.ok(match, 'client.js 缺少 UpgradeDialog')
+  const calls = []
+  const h = (type, propsArg, ...children) => { calls.push(String(type)); return { type, propsArg, children } }
+  const useState = (init) => [init, () => {}]
+  const Switch = (propsArg) => h('label', propsArg)
+  const dialog = new Function('h', 'useState', 'Switch', 'DEFAULT_UPGRADE_TEMPLATE', 'AUTO_RESTART_DELAY_SEC',
+    'buildInstallChangeLine', 'buildInstallVersionHint',
+    'return (' + match[0] + ')')(
+    h, useState, Switch, 'npm install -g @deepseek-ai/dsh@{tag}', 3,
+    (status, command) => '变更:' + command, (status) => '提示:' + status.runningVersion)
+  const status = { channel: 'latest', upgradeTemplate: '', runningVersion: '0.1.5', installedVersion: '0.1.5' }
+  const tree = dialog({ status, onCancel: () => {}, onConfirm: () => {} })
+  assert.equal(tree.type, 'div', '弹窗根为遮罩 div')
+  assert.ok(calls.some((type) => type === 'pre'), '命令 pre 节点应在树中')
+  assert.deepEqual(dialog({ status, onCancel: () => {}, onConfirm: () => {} }).type, 'div', '二次渲染稳定')
+})
 
 // prev/next 为 {lost,pid,bootAt} 快照;lost 强信号优先;bootAt 双侧齐备时以其为唯一
 // 实例证据(自洽数据:不同进程 bootAt 必不同),pid 比对是 bootAt 缺失时的退化路径
@@ -92,13 +200,6 @@ test('parity: VERDICT 三常量 client 与 core 一致', () => {
   assert.equal(extractConst('VERDICT_UNKNOWN'), VERDICT_UNKNOWN)
 })
 
-// host 侧锚点直接 import runtime.mjs 实现,防测试内手抄字面量漂移假绿
-import { RUNTIME_KINDS } from '../src/runtime.mjs'
-
-test('parity: 手动直跑运行环境常量 client 与 host 一致', () => {
-  assert.equal(extractConst('RUNTIME_KIND_MANUAL'), RUNTIME_KINDS.MANUAL_START)
-})
-
 test('parity: 弹窗文案自动重启延迟秒与 host AUTO_RESTART_DELAY_MS 换算一致', () => {
   assert.equal(extractNumberConst('AUTO_RESTART_DELAY_SEC'), AUTO_RESTART_DELAY_MS / 1000)
 })
@@ -140,18 +241,20 @@ test('parity: client API 路径常量与 host 路由清单逐条一致', () => {
     REGISTRY_BASE: 'REGISTRY_BASE_URL',
     UPGRADE: 'UPGRADE_URL',
     RESTART: 'RESTART_URL',
+    RELEASE_NOTES: 'RELEASE_NOTES_URL',
   }
   for (const [hostKey, hostPath] of Object.entries(API_PATHS)) {
     assert.equal(extractConst(CLIENT_KEY_BY_HOST_KEY[hostKey]), hostPath, 'API 路径漂移: ' + hostKey)
   }
 })
 
-// 窗口关系对拍:重启等待总时长必须大于宿主退出延迟,否则宿主还在延迟退出窗口内客户端已报超时
+// 窗口关系对拍:重启等待总时长必须大于任一退出延迟,否则宿主还在延迟退出窗口内客户端已报超时
 import { RESTART_DELAY_MS } from '../src/index.js'
 
-test('parity: 重启等待总时长大于宿主退出延迟', () => {
+test('parity: 重启等待总时长大于宿主退出延迟(按钮与自动重启取大)', () => {
   const restartTimeoutMs = extractNumberConst('RESTART_TIMEOUT_MS')
-  assert.ok(restartTimeoutMs > RESTART_DELAY_MS, 'RESTART_TIMEOUT_MS 必须大于 RESTART_DELAY_MS')
+  assert.ok(restartTimeoutMs > Math.max(RESTART_DELAY_MS, AUTO_RESTART_DELAY_MS),
+    'RESTART_TIMEOUT_MS 必须大于 max(RESTART_DELAY_MS, AUTO_RESTART_DELAY_MS)')
 })
 
 test('parity: 升级观察上限覆盖宿主重试链上限(防抢跑转状态未知)', () => {
@@ -170,13 +273,19 @@ test('parity: npm 版本页链接与追踪包名同源', () => {
   assert.ok(extractConst('NPM_VERSIONS_URL').includes(TARGET_PACKAGE), 'NPM_VERSIONS_URL 应包含 TARGET_PACKAGE 字面量')
 })
 
-test('parity: 落定补查宽限覆盖宿主自动重启调度延迟', () => {
-  // 落定拍与调度置位之间存在宿主侧 await 窗口:client 补查宽限必须不小于调度延迟 + 观察裕量
+// release 更新内容事实源在 GitHub Releases:client 兜底链接与 host 拉取仓库必须同源
+import { RELEASE_REPO } from '../src/core.mjs'
+
+test('parity: GitHub releases 兜底链接与 host 拉取仓库同源', () => {
+  assert.equal(extractConst('RELEASES_PAGE_URL'), 'https://github.com/' + RELEASE_REPO + '/releases')
+})
+
+test('parity: 落定补查宽限不小于观察轮询拍间隔', () => {
+  // 关机路径调度标记与 running=false 同拍置位,宽限不再竞态调度延迟;现职责是
+  // 给继续运行路径的 stale 异步复读留余量,下限锁定为不小于轮询拍间隔(补查不早于一拍)
   const graceMs = extractNumberConst('UPGRADE_AUTO_RESTART_GRACE_MS')
-  assert.ok(
-    graceMs >= AUTO_RESTART_DELAY_MS + 1 * 1000,
-    'UPGRADE_AUTO_RESTART_GRACE_MS(' + graceMs + ') 必须不小于 AUTO_RESTART_DELAY_MS(' + AUTO_RESTART_DELAY_MS + ') 加观察裕量',
-  )
+  assert.ok(graceMs >= 2 * 1000,
+    'UPGRADE_AUTO_RESTART_GRACE_MS(' + graceMs + ') 必须不小于观察轮询拍间隔(2s)')
 })
 
 test('源码契约: 重启轮询与升级观察器不得回退 setInterval 重叠拍形态', () => {
@@ -185,3 +294,15 @@ test('源码契约: 重启轮询与升级观察器不得回退 setInterval 重
   assert.ok(CLIENT_SOURCE.includes('AbortSignal.timeout(UPGRADE_POLL_TIMEOUT_MS)'), '升级观察拍必须带请求超时')
   assert.ok(CLIENT_SOURCE.includes('upgradeWatch.generation !== generation'), '升级观察拍 settle 后必须验代际')
 })
+
+test('源码契约: 安装入口全版本状态可点,verdict 不得回归为禁用门', () => {
+  // 重装修复与回退是面板显式意图:按钮与弹窗派生门控不得含 verdict 比较;
+  // VERDICT_UP_TO_DATE 仅允许出现两次(常量声明 + 结论徽章展示)
+  const occurrences = CLIENT_SOURCE.split('VERDICT_UP_TO_DATE').length - 1
+  assert.equal(occurrences, 2, 'VERDICT_UP_TO_DATE 只允许声明与徽章展示两处,禁用门回归即超限')
+  assert.ok(CLIENT_SOURCE.includes("}, '安装'),"), '升级按钮文案必须为「安装」')
+  assert.ok(CLIENT_SOURCE.includes("'确认安装'"), '弹窗标题必须为「确认安装」')
+  assert.ok(CLIENT_SOURCE.includes("'开始安装'"), '弹窗确认按钮必须为「开始安装」')
+  assert.ok(CLIENT_SOURCE.includes('重装'), '弹窗必须说明重装(修复)场景')
+  assert.ok(CLIENT_SOURCE.includes('回退'), '弹窗必须说明回退场景')
+})

package/test/release-notes.test.mjs

@@ -0,0 +1,165 @@
+// release notes 纯逻辑测试:标签构建、发布页地址构建、页面拉取与正文提取。
+// 数据源:https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v<版本>(页面正文,规避 api.github.com 未认证限流)
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  buildReleaseTag,
+  buildReleaseNotesUrl,
+  fetchReleaseNotes,
+  extractReleaseNotesFromHtml,
+  RELEASE_REPO,
+} from '../src/core.mjs'
+
+// fetchReleaseNotes 走 response.body.getReader() 流式读取;mock 按单块提供全部字节
+function streamBody(text) {
+  const chunks = [new TextEncoder().encode(text)]
+  return {
+    getReader: () => ({
+      read: async () => (chunks.length ? { done: false, value: chunks.shift() } : { done: true, value: undefined }),
+      cancel: async () => {},
+    }),
+  }
+}
+
+function fakeFetch(body, { ok = true, status = 200 } = {}) {
+  return async (url, options) => {
+    const text = typeof body === 'function' ? body(url) : typeof body === 'string' ? body : JSON.stringify(body)
+    return { ok, status, body: streamBody(text) }
+  }
+}
+
+function makeReleaseHtml(inner, { datetime = '2026-09-10T03:09:00Z' } = {}) {
+  return '<!doctype html><html><body>'
+    + (datetime ? '<relative-time datetime="' + datetime + '"></relative-time>' : '')
+    + '<div data-test-selector="body-content" class="markdown-body">' + inner + '</div>'
+    + '</body></html>'
+}
+
+const RELEASE_INNER = '<h3 id="user-content-note">更新内容</h3>'
+  + '<ul>'
+  + '<li>新增 A 功能 &amp; B 修复</li>'
+  + '<li>支持 <code>fast</code> 模式 &#39;引号&#39; 与 &lt;标签&gt;</li>'
+  + '</ul>'
+  + '<div class="markdown-body-inner"><p>嵌套段落保持在外层容器内</p></div>'
+  + '<p>详情见发布页。</p>'
+const RELEASE_BODY = [
+  '### 更新内容',
+  '- 新增 A 功能 & B 修复',
+  '- 支持 fast 模式 \'引号\' 与 <标签>',
+  '',
+  '嵌套段落保持在外层容器内',
+  '',
+  '详情见发布页。',
+].join('\n')
+const RELEASE_HTML = makeReleaseHtml(RELEASE_INNER)
+
+test('场景:合法版本构建发布标签与发布页地址', () => {
+  assert.equal(buildReleaseTag('0.1.5-rc.1'), 'dsh-v0.1.5-rc.1')
+  assert.equal(
+    buildReleaseNotesUrl('0.1.5-rc.1'),
+    'https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1',
+  )
+  assert.equal(RELEASE_REPO, 'deepseek-ai/deepseek-harness')
+})
+
+test('场景:非法版本拒绝构建标签,空白版本归一后放行', () => {
+  assert.throws(() => buildReleaseTag(null), /semver/)
+  assert.throws(() => buildReleaseTag('not-semver'), /semver/)
+  assert.throws(() => buildReleaseTag('1;rm -rf /'), /semver/)
+  assert.equal(buildReleaseTag(' 0.1.5-rc.1 '), 'dsh-v0.1.5-rc.1', '首尾空白归一,防拼接出残缺标签')
+})
+
+test('场景:拉取成功提取正文与发布时间,请求形态与上游纪律一致', async () => {
+  let requestedUrl = null
+  let capturedOptions = null
+  const notes = await fetchReleaseNotes({
+    version: '0.1.5-rc.1',
+    fetchImpl: async (url, options) => {
+      requestedUrl = url
+      capturedOptions = options
+      return { ok: true, status: 200, body: streamBody(RELEASE_HTML) }
+    },
+    timeoutMs: 1000,
+  })
+  assert.deepEqual(notes, {
+    url: buildReleaseNotesUrl('0.1.5-rc.1'),
+    publishedAt: '2026-09-10T03:09:00Z',
+    body: RELEASE_BODY,
+  })
+  assert.equal(requestedUrl, buildReleaseNotesUrl('0.1.5-rc.1'))
+  // 选项透传断言:redirect:'error' 的实际拒跟行为由平台 fetch 保证,mock 只验证参数到达
+  assert.equal(capturedOptions.redirect, 'error')
+  assert.ok(capturedOptions.signal instanceof AbortSignal)
+  assert.match(String(capturedOptions.headers.accept), /html/)
+  assert.ok(capturedOptions.headers['user-agent'], '页面拉取须带显式 User-Agent')
+})
+
+test('场景:HTTP 404 报未找到发布说明,其余非 2xx 报状态码', async () => {
+  await assert.rejects(
+    () => fetchReleaseNotes({ version: '9.9.9', fetchImpl: fakeFetch('<html></html>', { ok: false, status: 404 }), timeoutMs: 1000 }),
+    /未找到/,
+  )
+  await assert.rejects(
+    () => fetchReleaseNotes({ version: '9.9.9', fetchImpl: fakeFetch('<html></html>', { ok: false, status: 502 }), timeoutMs: 1000 }),
+    /502/,
+  )
+})
+
+test('场景:页面缺 markdown-body 锚点或容器未闭合报结构解析失败', () => {
+  assert.throws(() => extractReleaseNotesFromHtml('<html><body><p>没有正文容器</p></body></html>'), /结构无法解析/)
+  assert.throws(() => extractReleaseNotesFromHtml('<div class="markdown-body"><p>容器未闭合</p>'), /结构无法解析/)
+  assert.throws(() => extractReleaseNotesFromHtml(null), /结构无法解析/)
+})
+
+test('场景:空正文容器返回空说明,缺发布时间为 null', async () => {
+  const notes = await fetchReleaseNotes({
+    version: '9.9.9',
+    fetchImpl: fakeFetch(makeReleaseHtml('   ', { datetime: '' })),
+    timeoutMs: 1000,
+  })
+  assert.deepEqual(notes, {
+    url: buildReleaseNotesUrl('9.9.9'),
+    publishedAt: null,
+    body: '',
+  })
+})
+
+test('场景:上游网络异常原样抛出由调用方归一', async () => {
+  await assert.rejects(
+    () => fetchReleaseNotes({ version: '9.9.9', fetchImpl: async () => { throw new Error('ECONNRESET') }, timeoutMs: 1000 }),
+    /ECONNRESET/,
+  )
+})
+
+test('场景:超限响应体中途断开,不整量入内存', async () => {
+  const chunk = 'x'.repeat(128 * 1024)
+  let cancelled = false
+  const oversized = {
+    ok: true,
+    status: 200,
+    body: {
+      getReader: () => ({
+        read: async () => ({ done: false, value: new TextEncoder().encode(chunk) }),
+        cancel: async () => { cancelled = true },
+      }),
+    },
+  }
+  await assert.rejects(
+    () => fetchReleaseNotes({ version: '9.9.9', fetchImpl: async () => oversized, timeoutMs: 1000 }),
+    /上限/,
+  )
+  assert.equal(cancelled, true, '流必须被取消')
+})
+
+test('场景:timeoutMs 缺失或非正数拒绝', async () => {
+  await assert.rejects(
+    () => fetchReleaseNotes({ version: '9.9.9', fetchImpl: fakeFetch(RELEASE_HTML) }),
+    /timeoutMs/,
+  )
+  await assert.rejects(
+    () => fetchReleaseNotes({ version: '9.9.9', fetchImpl: fakeFetch(RELEASE_HTML), timeoutMs: 0 }),
+    /timeoutMs/,
+  )
+})