鲸鱼通知 SailingBoat-ovo/dsh-notify

dsh-notify

English · 中文

为 DeepSeek Harness (DSH) 提供系统通知：会话的 AI 轮次结束时，DSH 会弹出系统通知，带上黑鲸标记，并告诉你哪个任务完成了。

preview

工作原理（以及为什么这样设计）

宿主订阅会话日志自身的 session/event 流，对 turn/end 做出反应；浏览器通过 Server-Sent Events 接收这些完成事件，然后弹出通知。

这种拆分是有意为之。早先的版本试过在浏览器里读取客户端投影来检测完成，两次尝试都静默失败了：

| 尝试 | 为什么从未触发 |
| sessions.list.byId[].running | DSH 0.2.x 把 running 留在会话对象上，不再实时刷新列表行，所以 true → false 的边沿从未出现。 |
| sessions.binding(id).session | binding() 返回 this.scopes.get(id)?.binding —— 它只对已经保留的作用域作答，所以根级插件对每个会话都拿到 undefined。 |

两者都是私有内部实现。session/event 是文档化的接缝 —— dsh-session 包写明 "Persistence is a plugin concern (subscribe to session/event, drain on session/flush)"* —— 而 turn/end 是会话日志自身事件词汇表里的稳定类型。宿主还持有持久化的会话头，所以标题来自事实来源，而不是来自 UI 投影。

行为

- 任何会话中每个结束的轮次都会触发。
- 标题为 任务完成（轮次失败时为 任务出错）；正文写明会话名称。
- 图标：DeepSeek 鲸鱼，由宿主在 /dsh-notify/whale.svg 提供，在浏览器里栅格化为 PNG（Windows 通知偏好位图）。
- 点击通知，请求 shell 聚焦该会话。
- 一个 EventSource 自行处理重连。

安装

dsh plugin --profile web add github:SailingBoat-ovo/dsh-notify
dsh plugin --profile desktop add github:SailingBoat-ovo/dsh-notify

之后重启 DSH —— node 那一半在启动时加载，只刷新页面不够。

诊断

Settings → General 显示权限状态、"Send a test notification" 按钮，以及实时链路状态：

Link: live · 3 completion event(s) received

- 测试按钮能用但计数器一直是 0 → 宿主那一半没加载（重启 DSH）。
- 计数器增长但没有通知 → 操作系统/浏览器在压制通知。

端点

| 路径 | 用途 |
| GET /dsh-notify/stream | 完成帧的 text/event-stream |
| GET /dsh-notify/completions | 最近的完成事件 + 当前序列水位 |
| GET /dsh-notify/whale.svg | 鲸鱼标记 |

测试

npm install
npm test
tests/host-test.mjs（29 条断言）覆盖事件映射（只有 turn/end 算数；标题/cwd/id 兜底；失败信息）、feed（序号单调、历史上限、解绑），以及全部路由，包括 SSE 握手、推送一帧、断开解绑。tests/client-test.mjs（20 条断言）覆盖两个 slot 注册、流接线、通知内容、点击跳转、权限拒绝、设置行渲染。

许可

GPL-3.0-or-later，完整文本见 LICENSE；第三方说明见 NOTICE.md。

工作原理（以及为什么这样设计）

宿主订阅会话日志自身的 session/event，对 turn/end 作出反应；浏览器通过 SSE 收到完成事件后弹出通知。

这个分工是刻意的。此前两版都试图在浏览器里读客户端投影来判断「是否跑完」，两次都静默失效：

| 尝试 | 为什么从不触发 |
| sessions.list.byId[*].running | 0.2.x 把 running 放在会话对象上，列表行不再实时刷新，因此永远等不到 true → false 边沿。 |
| sessions.binding(id).session | binding() 返回的是 this.scopes.get(id)?.binding —— 它只对已被 retain 的 scope 有答案，根级插件对每个会话都拿到 undefined。 |

这些都是私有内部实现。而 session/event 是文档化的扩展点（dsh-session 包里写明「订阅 session/event」是持久化插件的做法），turn/end 是会话日志事件词汇表里的稳定类型。宿主还能读到会话的 header，所以标题取自事实来源，而不是 UI 投影。

行为

- 任何会话的每一轮结束都会通知；
- 标题 任务完成（该轮失败则 任务出错），正文带会话标题；
- 图标是 DeepSeek 鲸鱼：由宿主在 /dsh-notify/whale.svg 提供，浏览器栅格化成 PNG（Windows 通知偏好位图）；
- 点击通知让外壳聚焦该会话；
- EventSource 自带重连。

安装

dsh plugin --profile web add github:SailingBoat-ovo/dsh-notify
dsh plugin --profile desktop add github:SailingBoat-ovo/dsh-notify

装完必须重启 DSH —— 宿主半边在启动时加载，只刷新页面不够。

怎么排查

设置 → 通用 里显示权限状态、「发一条测试通知」 按钮，以及实时连接状态：

连接：已连接 · 已收到 3 条完成事件

- 测试按钮能弹、但计数一直是 0 → 宿主插件没加载（重启 DSH）；
- 计数在涨、但没弹窗 → 系统/浏览器在拦截通知。

接口

| 路径 | 用途 |
| GET /dsh-notify/stream | 完成事件的 text/event-stream |
| GET /dsh-notify/completions | 最近的完成记录 + 当前序号 |
| GET /dsh-notify/whale.svg | 鲸鱼图标 |

测试

npm install
npm test

tests/host-test.mjs（29 项）覆盖事件映射（只有 turn/end 算数；标题/cwd/id 兜底；失败信息）、feed（序号单调、历史上限、解绑），以及全部路由（含 SSE 握手、推送一帧、断开解绑）。
tests/client-test.mjs（20 项）覆盖两个 slot 注册、流接线、通知内容、点击跳转、权限拒绝、设置行渲染。

许可

GPL-3.0-or-later，完整文本见 LICENSE；第三方说明见 NOTICE.md。