dsh_update_check

English · 中文 README

dsh_update_check

dsh_update_check 是一个 dsh 插件，能自动检查 dsharness 官方上游仓库比对差异并提示更新。

功能特性

1. 打开即检（可开关）：页面加载 3 秒后自动检查一次（connection/reset 时补触发）；DSH 更新检查与插件自身检查是两个独立开关。
2. 基于官方 GitHub：按序尝试 releases/latest API → releases 列表 → tags API，10 秒超时，dsh-v* 前缀的 tag 也能正确解析（semver 风格比较，含 rc/beta 预发布）。
3. 上游改动结构化：解析发布说明为分节条目——新增功能 / 问题修复 / 体验优化 / 其他变更 / SDK；优先中文块；每条保留完整原文；命中破坏性关键词的条目按强/弱信号高亮。
4. 插件自身更新检查：本地 package.json 版本与仓库 plugin/package.json 比对（DSH 本身的更新始终由你手动执行，插件只做提示）。
5. 可持续热更新框架（针对本插件自身）：host 半区拆成稳定监督者 + 可热插拔实现两层，检测/解析逻辑换版本无需重启 DSH；设置页提供手动「热更新插件」按钮（绝不静默、绝不自动）。详见热更新。
6. 顶部横幅两态：简略（一行「发现更新：DSH X → Y」+「详情 / 稍后」）或详细（直接展开详情），由开关控制；无自动消失计时器；点「稍后」后同版本不再弹出，直到出现更新版本。
7. 独立设置页：设置区独立的「↑ 检查更新」页（与「通用设置 / 模型 / 插件」同级），三个卡片：
   • DSH 更新：当前/最新版本、发布时间、上次检查、状态、「立即检查」、发布说明链接、完整破坏性命中描述（关键词 + 完整条目原文）、改动分类列表，以及一行淡色诊断文字（本机版本是从哪条渠道读出来的：模块解析 + 路径，或 npm 全局探测）；
   • 插件自身更新：当前/最新插件版本、状态与热更新按钮；
   • 设置：下列三个开关。
8. 三个持久化开关：每次启动检查 DSH 更新 / 每次启动检查插件自身更新 / 顶部窗口显示描述细节（详细或简略），存于 $DSH_HOME/update-check.json。
9. 破坏性更新分级：语义版本（major 变化，或 0.x 阶段 minor 变化）+ 发布说明关键词：
   • 强信号（breaking change / 破坏性更新 / 破坏…兼容 等）→ 黄色预警「含破坏性变更」；
   • 弱信号（不兼容 / incompatible / 迁移 / 移除 / deprecated 等）→ 黄色预警「可能破坏性」，并展示完整命中条目由你判断；
   • 纯信息展示：DSH 本身的更新始终由你手动执行，插件不提供 DSH 安装流程。
10. 网络不佳有提示：连不上 GitHub 时，顶部横幅显示「无法连接 GitHub，检查失败」+ 「重试 / 关闭」。
11. 中英双语界面：通过 DSH client locale 服务注册 zh / en 字典，界面跟随当前语言实时切换（横幅、设置页与导航标签）；locale 服务不可用时回退内置中文字典。

安装方式

静态插件

插件以 npm 包 dsh-update-check 提供（plugin/ 目录），挂进宿主 composition，随 DSH 启动自动加载：

1. 安装包：把 plugin/ 目录放入 profile 的 node_modules（Windows 默认 C:\Users\<你>\.dsh\profiles\<profile>\node_modules\dsh-update-check\，含 package.json + lib/）；

2. 挂载：编辑该 profile 的 cordis.patch.yml，追加：

   - insert:
       - id: upd-check
         name: 'dsh-update-check'
   

3. 重启 DSH：生效后无需任何手动加载，插件常驻（更新 DSH 后也不用重装）。

说明：Host 通过宿主 webServer 暴露 GET /upd-check/api/check（Host 以 inject: ['webServer'] 声明硬依赖，等服务就绪后再注册路由）；浏览器端 client bundle（ModuleLoader 格式）经 exports["./client"] + package.json dsh.client 声明被 dsh 的 client-modules 自动扫描打包，挂载 shell.overlay 横幅，并在设置区注册独立的「↑ 检查更新」页（settings.section，与「通用设置 / 模型 / 插件」同级，排最后）。

工作原理

网络传输三级容错：

1. web.fetch（若部署挂载了 fetch provider）；
2. subprocess 跑 node -（stdin 喂脚本）标准 fetch（自动跟随重定向）；
3. 前两者失败（典型场景：hosts 被第三方工具劫持，如 Steamcommunity302 把 github.com 指向 127.0.0.1 并返回自签证书）→ 脚本内用 dns.resolve4 取真实 IP，以 servername/Host 头直连，手动跟随重定向、逐个 IP 重试。

热更新

插件可以从自己的 GitHub Release 更新自身，且大部分改动无需重启 DSH。

分层与生效边界

监督者刻意不在运行期自我改写：它就是执行更新的那段代码，运行时替换自己等于把脚下地板抽掉。它的改动会落盘并在响应中标注 restartRequired。

更新流程（POST /upd-check/api/self-update，仅手动触发）

1. 从 releases/latest 取目标 tag（仓库还没有 Release 时回落 contents/plugin/package.json）；
2. 用 contents API 从该 tag 拉取四个文件（lib/client.js、lib/impl.js、lib/index.js、package.json）；
3. 判定变化：把每个下载内容的 git blob SHA 与本地文件比对，同时用 API 给出的 SHA 做下载完整性校验；
4. 先校验，后落地：候选文件写入 lib/.stage/ —— package.json 形状、client.js 走 node --check 真解析、impl.js 真 import() 并校验契约、index.js 校验关键标记；
5. 备份被替换文件到 lib/.bak/<旧版本>_<时间戳>/；
6. 同目录 rename 原子替换每个文件；
7. 热换入新引擎（失败则从备份还原 impl.js/client.js，继续用内存中的旧引擎）；
8. 把本次尝试追加进 $DSH_HOME/update-check-history.json（成功与失败都记，保留最近 20 条）。

第 6 步之前或之中的任何失败都不会动磁盘；第 7 步失败会回滚。响应返回 from/to、hot、clientReloaded、restartRequired、逐文件 changed 标记与备份路径。

接口

发布（热更新的内容来源）

pwsh -NoProfile -File scripts/release.ps1 -Final

以两套契约测试为门禁，抽取 CHANGELOG 中该版本段落作为 Release 说明，然后提交、推送、打 tag，并建立 GitHub Release（全部幂等）。

发布策略：每个版本都打 tag（tag 是自更新抓取内容的锚点），但只有系列最终版本才建 GitHub Release —— 中间版本发 Release 只会让人一头雾水。所以系列开发过程中执行 scripts/release.ps1（只打 tag），定稿时加一次 -Final。插件自更新消费的是 releases/latest，也就是那个最终发布版。

本机 github.com 的 git 直连不可用（连接超时 / SSL 校验失败），推送走 Git Data API（scripts/push-via-api.ps1），因此本地与远端的 ref 会内容一致、SHA 分叉，这是预期行为。

兼容性与已知限制

疑难解答

• 一直显示「无法连接 GitHub」：先检查 hosts（C:\Windows\System32\drivers\etc\hosts）是否有 github.com / api.github.com → 127.0.0.1 的劫持行（常见于 Steamcommunity302 等加速工具）；有则删除这些行（需管理员），或直接依赖插件内置的 DNS 绕过。也可尝试点「重试」。
• 插件未生效：确认 node_modules/dsh-update-check 存在、cordis.patch.yml 已插入行、重启 DSH；检查 GET /upd-check/api/check 是否返回 JSON。
• 热更新返回 restartRequired：这次发布同时改了 lib/index.js（监督者）。新文件已经落盘，下次 DSH 启动生效；GET /upd-check/api/self-update 可查看运行中的引擎版本。
• 热更新失败：不会留下改到一半的状态——响应给出原因（如 impl-contract-mismatch、remote-client-syntax、http-404），本次尝试记入 $DSH_HOME/update-check-history.json，旧版本备份在 plugin/lib/.bak/ 下。
• 设置区没有「↑ 检查更新」页：确认 client bundle 被扫描（重启后刷新页面）；「检查更新」位于设置区的顶级页（与通用设置/模型/插件同级，排最后）。
• 「无法读取本地版本」：DSH 不是通过 npm 全局安装的；远端版本仍会正常显示。
• 点「稍后」后横幅又出现：客户端记住了忽略的版本；同一版本在连接重置、页面刷新、设置页手动检查后都不会再弹，只有发布新版本（latest 变化）才会再次提醒。
• 设置页「立即检查」会弹顶部横幅：手动检查只更新设置页状态，不再弹顶部横幅；顶部横幅保留给自动检查与横幅操作（重试）。
• 提示「GitHub 拒绝请求 / 匿名 API 限流已用尽」：GitHub 未认证配额为 60 次/小时/IP。插件已把这种情况与真正的网络故障区分开（HTTP 403/429 → rate-limit），不再说成「无法连接 GitHub」；插件自身检测走的是另一个仓库，不受影响。按提示稍后重试即可（/rate_limit 可查重置时间）。
• 黄色预警误报/漏报：破坏性判定以语义版本为主（确定性），发布说明关键词为辅；弱信号只提示「可能」并展示原文片段，由你核实；若官方发布说明措辞不含关键词，可能漏报 release-notes 信号，但版本信号仍会兜底。

开发与贡献

• 插件本体：plugin/ 目录 = npm 包 dsh-update-check（lib/index.js 监督者 + lib/impl.js 可热插拔实现 + lib/client.js 浏览器 bundle）。
• 本地校验：
  • node scripts/check-src.js —— 语法与源码契约检查（102 条断言，CI 同样执行）；
  • node scripts/check-runtime.mjs —— 运行期契约检查：在临时沙箱里用桩 ctx 装载真实 host 半区并驱动其真实 HTTP handler，覆盖检测载荷、设置读写、引擎契约与热更新全链路（含失败零损伤回滚与两条版本检测渠道），62 条断言，CI 同样执行；
  • node scripts/verify-real-selfupdate.mjs [包目录] —— 可选，需联网：把包复制到临时目录、降到 0.0.1 并制造内容漂移，然后真的从已发布的 GitHub Release 自我更新一次，再断言文件、运行中引擎版本与备份。全程不动源目录；GitHub 不可达时输出 SKIPPED 并以 0 退出。
• 发布：先 bump plugin/package.json 并写好 CHANGELOG 段落，然后 pwsh -NoProfile -File scripts/release.ps1（迭代期只打 tag），定稿时加 -Final 发布 Release。
• 改动「监督者 ↔ 实现」契约时，需同步 bump lib/index.js 的 IMPL_CONTRACT 与 lib/impl.js 的 API_VERSION；CI 会比对两者是否一致。
• 欢迎提交 Issue / PR。

License

MIT © nmbzth