前言¶
在 DeepSeek Harness（DSH）里开发客户端插件时，改完 lib/client.js 后，官方链路会通过 @deepseek-ai/dsh-client-hmr 轮询 bundle 元数据并在变化时推送 rebuilt 帧，浏览器侧再走 invalidate → prefetch → refresh。这条路径存在，但日常开发往往仍习惯整页 F5，或不清楚何时只需重载某几个 bundle。整图重载会丢掉各插件内的 React 状态，代价不小。
dsh-hot-refresh（维护者 liuhaolong16）把上述官方客户端热重载做成面板上的显式入口：能差分「变了哪几行」就只重载它们，整图重载必须二次确认或带显式参数。插件不自行实现模块替换，只触发与观测，避免与官方 HMR 机制冲突。
这是什么¶
- 名称：
dsh-hot-refresh（npm 包名同） - 分类：客户端（SkillHub 目录归类为客户端插件）
- 当前版本（资料中的
package.json）：0.4.0 - 许可证：MIT
- 定位：在宿主侧调用
clientModules.rebuilt(id)立即推帧，并提供 HTTP 自检与面板按钮；整图重载有护栏。
社区目录页：SkillHub - dsh-hot-refresh。源码与说明：GitHub - liuhaolong16/dsh-hot-refresh。
与官方热重载的关系¶
README 中根据本机 app.asar 逆向整理了官方分工，写作时以该表为准：
| 包 | 职责 |
|---|---|
@deepseek-ai/dsh-client-hmr v0.2.0-rc.2 |
宿主每 pollIntervalMs（默认 500ms）轮询各客户端 bundle 的 {mtimeMs, ctimeMs, size}；变化时 ctx.clientModules.rebuilt(id)，并经 SSE /plugins/events 推 rebuilt 帧 |
@deepseek-ai/dsh-client-modules |
浏览器侧：invalidate → prefetch → refresh；entries.sync(graph) 全量同步、entries.reload(id, rev) 单条就地重载 |
@deepseek-ai/dsh-hmr |
宿主侧热重载队列；文档写明通过 Plugin Manager 发起的操作可不等待文件事件 |
本插件在「文件已变、等轮询」之外，提供立刻触发同一条 rebuilt 路径的能力。
核心功能¶
HTTP 接口¶
-
POST /hot-refresh/reload?id=<rowId>
直接调用clientModules.rebuilt(id)，立即推帧，不必等 500ms 轮询，也不必先改文件。 -
POST /hot-refresh/reload?ids=a,b,c（v0.4.0）
精确重载一组行。客户端记住上次见过的每行rev，对照/health中的图信息差分出变更行；面板可显示「⟳ 热刷新 · N 个已变」并只重载它们。
- 含未知 id：返回 503，且一条都不重载（先校验后执行）。
-?ids=为空：返回 400need-explicit-all（空列表不能当作「全部」）。 -
POST /hot-refresh/reload?all=1
整图重载（会丢失所有插件的 React 状态）。必须显式带参；否则 400 并说明影响面（行数）。 -
GET /hot-refresh/health
只读自检：clientModules是否可用、图行数、graph:[{id,rev}]、applies重放计数、最近客户端自报。 -
POST /hot-refresh/report
客户端自报（是否按过按钮、是否成功、宿主版本等）。
面板入口¶
- 设置旁的「⟳ 热刷新」（
sidebar.footer.action）：有变化时只重载变化行；无变化时首点待确认，5 秒内再点则整图重载。 - 插件详情页头部「⟳ 就地重载」（
plugins.detail.actions）：单行即时重载。
兼容闸门（v0.4.0）¶
客户端仅在宿主版本 ≥ 0.4.0 时发送 ?ids=。旧宿主不认识该参数时会退回整图重载，可能在无提示下抹掉整页状态。旧宿主下仍走「二次确认 + ?all=1」。版本比较按数值段（例如 0.10.0 > 0.9.0）；空或未知版本视为更旧。
安装与启用¶
安装命令以 README 原文为准（示例路径为 Windows，请按本机 bundle 目录替换 link: 后的路径）：
plugin_manager install_bundle link:E:\DeepSeek\skills\hot-refresh\bundle
plugin_manager set_bundle target=dsh-hot-refresh enabled=true
升级前可执行门检（README 称 14 项检查）：
node _preflight.cjs
插件以当前 DSH 进程权限运行；安装前请自行查看仓库源码与 MIT 许可证。SkillHub 为社区目录站点，与 DeepSeek / 幻方无官方从属关系。
典型用法¶
日常改客户端代码¶
- 修改已安装插件的
lib/client.js。 - 在多数情况下，官方 500ms stat 轮询会自行触发客户端半体热更，无需刷新页面（README 本机实测，2026-10-15）。
- 若希望立即重载而不等轮询，在侧栏点「⟳ 热刷新」；若插件已检测到图上有变更行，会只重载那些行。
- 在某一插件详情页，可对单行使用「⟳ 就地重载」。
需要整图重载时¶
无检测到的变更时，侧栏按钮首点为待确认；5 秒内再次点击会走整图重载。也可通过 API 显式调用 POST /hot-refresh/reload?all=1。操作前应知晓：被重载插件内的 React 状态会丢失（官方文档所述粗粒度行为；数据层不受影响）。
观测与排错¶
访问 GET /hot-refresh/health 查看 clientModules、图规模、graph 与各 id 的 rev、applies 重放计数，便于确认宿主侧是否就绪、差分逻辑是否看到变更。
适用场景与已知边界¶
适合谁：频繁改 DSH 客户端插件 UI / 注入逻辑、希望少用 F5、又需要避免误触整图重载的开发者。
宿主半体不能靠本插件热换：README 本机实测（2026-10-15）结论——改已装插件的 lib/index.js（宿主）后仅停用+启用，仍可能是旧代码；Node ESM 按 URL 缓存，换入口文件名也未必生效。客户端半体变更可走官方热更；宿主半体变更在本机需重启 App。本插件不伪装能热换宿主。
其它官方限制（README 引用）：替换已安装包的版本仍需要重启；重载粒度粗，插件内 React 状态会丢。
与社区 dshmarket 等实现的对比（README 摘录）：社区「装完刷新页面即可用」指的是刷页面，不是宿主热重载；其 profile 热禁用/启用靠 HMR 重新组合，同样换不掉已加载的宿主模块。桌面受监督宿主上一键重启往往不可用，需用户关窗再开。
结尾¶
dsh-hot-refresh 把 DSH 官方客户端 clientModules.rebuilt 链路收敛到面板一键操作，用 ?ids= 差分与 ?all=1 护栏区分「只重载变了的几行」与「整图重载」，并用 /health 暴露图与重放计数。开发客户端插件时可优先用它减少无效全页刷新，同时牢记宿主代码变更仍需重启应用。
- 目录页：https://www.skillhub.cn/plugins/liuhaolong16/dsh-hot-refresh
- GitHub：https://github.com/liuhaolong16/dsh-hot-refresh
