@mzzsfy/dsh-maintain 0.8.0 → 0.9.0

package/src/index.js

@@ -12,8 +12,10 @@ import {
   TARGET_PACKAGE,
   TAG_PLACEHOLDER,
   buildUpgradeCommand,
+  extractPinnedVersion,
   classifyUpgradeFailure,
   fetchDistTags,
+  fetchReleaseNotes,
   isValidChannelName,
   isValidRegistryBase,
   isVersionPendingRestart,
@@ -22,7 +24,6 @@ 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'
@@ -36,6 +37,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 并进入重启等待态,进程才离场;
@@ -226,6 +230,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 信号失效)
@@ -396,6 +401,8 @@ export function apply(ctx) {
   let nextDueAt = null
   let restartScheduled = false
   let autoRestartScheduled = false
+  // 版本更新内容缓存:键为通道最新版原始值(未归一),值为 {url,publishedAt,body};仅成功结果入缓存
+  const releaseNotesCache = new Map()
 
   function runCheck() {
     if (checkInFlight) return checkInFlight
@@ -490,8 +497,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,
@@ -604,6 +615,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 +768,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 +824,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',
+    'RUNTIME_KIND_MANUAL', 'buildInstallChangeLine', 'buildInstallVersionHint',
+    'return (' + match[0] + ')')(
+    h, useState, Switch, 'npm install -g @deepseek-ai/dsh@{tag}', 3, 'manual-start-likely',
+    (status, command) => '变更:' + command, (status) => '提示:' + status.runningVersion)
+  const status = { channel: 'latest', upgradeTemplate: '', runningVersion: '0.1.5', installedVersion: '0.1.5', runtimeEnv: null }
+  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 缺失时的退化路径
@@ -140,6 +248,7 @@ 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)
@@ -170,6 +279,13 @@ test('parity: npm 版本页链接与追踪包名同源', () => {
   assert.ok(extractConst('NPM_VERSIONS_URL').includes(TARGET_PACKAGE), 'NPM_VERSIONS_URL 应包含 TARGET_PACKAGE 字面量')
 })
 
+// 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: 落定补查宽限覆盖宿主自动重启调度延迟', () => {
   // 落定拍与调度置位之间存在宿主侧 await 窗口:client 补查宽限必须不小于调度延迟 + 观察裕量
   const graceMs = extractNumberConst('UPGRADE_AUTO_RESTART_GRACE_MS')
@@ -185,3 +301,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/,
+  )
+})

package/test/restart-ready.test.mjs

@@ -205,7 +205,8 @@ const clientRestartConfirmLabel = extractLogic('restartConfirmLabel')
 
 test('upgradeFinalText: stale 优先于两种重启指引,不得引导重启', () => {
   const text = clientUpgradeFinalText({ ok: true, stale: true, requiresManualRestart: true, autoRestartScheduled: true })
-  assert.match(text, /未前进|未达目标/)
+  // stale 口径泛化:未前进/未达目标/未落到目标/未装到指定版本统称与安装意图不符
+  assert.match(text, /意图不符/)
   assert.doesNotMatch(text, /重启/)
 })