dsh-update-notify
v0.1.0
Published
Update reminders for the DeepSeek Harness CLI and profile-installed plugins: on-demand npm-registry check (10min cache, invalidates right after an upgrade) surfaced as a row in the Settings > General page.
Maintainers
Readme
dsh-update-notify
DSH 更新提醒插件:对比 DSH CLI + profile 已装插件的 current → latest 版本, 在设置页 General 分区显示一条提醒行(蓝点 + 「有可用更新 N 项」+ 明细列表, 可逐项「忽略」)。
安装
dsh plugin --profile web add dsh-update-notify零配置。行注册会由 dsh plugin add 自动写入 cordis.patch.yml;之后
dsh web 重启即生效,打开设置页 General 分区即可看到提醒行(无更新时不显示)。
工作方式
检查时机(按需,无定时器):describe 路由收到请求时,缓存快照 <10min 直接回, 否则现场查 npm registry(共享 in-flight promise 防并发重复查)。落盘缓存 另有「安装版本失效」检查——快照里的 current 与实际安装版本不符(刚升完级) 即作废,不会把已完成的升级继续提示到 TTL 过期。
结构
当前直接维护编译产物(无 src,与案发时 DSH 生成的结构一致):
- host 半区
lib/index.js:GET /api/update-notify/describe(loopback fence, 同 tavily 自托管路由契约;10min 短缓存 + 按需 registry 检查) - client 半区
lib/client.js:settings.general.item槽注册更新提醒行 (最早版本做过顶部横幅 + 左下角方案,按用户要求改成设置页内的小提醒)
注册见 cordis.patch.yml 的 update-notify 条目,手动 cp 部署到 profile
node_modules/ 后 systemctl restart dsh-web。
踩坑记录
1. host 半区必须导出 inject,缺了崩整棵插件树(2026-08-15 事故)
host 半区用 ctx.webServer 注册路由,但没导出 inject,cordis 报
cannot get property "webServer" without inject —— 不是跳过该插件,而是整个
plugin tree 加载失败,dsh web 起不来(systemd 无限崩溃循环)。
修法(同 tavily):
const inject = ["webServer"];
export { apply, inject };2. client 半区同样要导出 inject(同日二次事故)
client.js 用 ctx.slots 但只导出了 apply,浏览器端报
cannot get property "slots" without inject(页面顶部 Failed to load plugins)。
host / client 两半各自独立声明 inject,修一半不够。
修法同 tavily client:fiber 级服务声明 + 包级依赖两处都要改——
// client.js 末尾
const inject = ["slots"];
exports.apply = apply;
exports.inject = inject;// package.json 的 dsh.client.inject 加上 "@deepseek-ai/dsh-client-ui-slots"
// (slots 服务的提供方,保证加载顺序)3. ctx.effect(cb) = 立即执行 cb + 返回值作清理,不是"销毁时回调"
cordis 的 effect 语义同 React:cb 立刻跑,cb return 的函数才是销毁清理。
错误写法(案发版本):register 放 apply 顶层,effect 回调里写清理逻辑—— effect 回调立即执行,注册路由的下一毫秒就把路由 dispose 掉:不抛错、 不崩树、服务看似正常,路由永远 404,极难排查。
正确写法(见 tavily / 本插件现版):副作用(timer、route)全部在 effect 回调里建立,return 清理函数:
ctx.effect(() => {
const timer = setInterval(refresh, MS);
const disposeRoute = ctx.webServer.register({ ... });
return () => { clearInterval(timer); disposeRoute(); };
}, "update-notify: interval + route");4. React hooks 必须全部在 early return 之前(同日三次事故)
组件先 if (entries === null) return null 再 useCallback → 首帧 null 渲染
0 个条件 hook、数据帧多出一个 → "Rendered more hooks than during the
previous render"(minified React #310),slot entry crashed,控制台只有
JSHandle@error 看不出所以然。报错栈要抓 console.error 的 args 再
getProperty("stack"),message 本身只有错误码。
规则:组件里所有 hooks 写在最前面,条件渲染只管 JSX。
5. 展示形态:横幅 → 设置页小提醒(产品层)
顶部横幅(shell.overlay 槽)用户嫌重。最终形态:settings.general.item
槽(同 ui-theme 的 AppearanceRow)注册一条「有可用更新」行——蓝点 + 数量 +
明细列表 + 逐项忽略 + 升级命令提示,藏在设置 General 分区里,手机端因设置
弹窗全屏适配自动可用。
6. 提醒时机演进:24h 定时 → 打开设置按需查 + 10min 短缓存
初版「每天定时查 + 24h 落盘缓存」有两个反直觉表现(都被用户当场抓到):
- 升完级还提示:升级发生在 TTL 窗口内时,host 吃的是旧快照,把自己刚
完成的升级继续显示成待更新。修法:
loadFreshCache加安装版本比对—— 快照里任何 entry 的current与实际安装版本不符即作废整份缓存。 - 提示不够新鲜:24h 窗口内新发布的版本看不到。改成 describe 按需检查: 快照 <10min 直接回(0.6ms 级),过期现场查 registry(~0.3s,15s 超时), 并发请求共享同一个 in-flight promise。定时器整个删掉——打开设置才是 唯一需要这份数据的时刻。
