前言¶
在 DSH (DeepSeek Harness) 中开发或运行智能体时，会话可能持续很长时间，且用户视线往往在浏览器其他标签页或应用中。若缺乏有效的通知机制，后台任务完成、审批请求或错误信息可能被遗漏。
dsh-hybrid-notify 插件通过监听窗口可见性，根据用户当前是否在浏览器前台，自动在页面内 Toast、PWA 系统通知和浏览器通知之间切换，并使用 Web Audio API 合成音效，确保关键事件能够被准确捕获。
核心功能¶
该插件主要解决后台运行时的消息触达问题，核心能力包括：
- 三通道自动选择：根据窗口可见性智能派发通知。
- 页面内 Toast：窗口前台且可见时。
- PWA 系统通知：窗口后台且 PWA 通道可用时。
- 浏览器通知：窗口后台且未注册 Service Worker 时的兜底方案。
- 合成音效：使用 Web Audio API（振荡器 + 包络整形）实时合成音色，无需加载任何音频文件。音效分为成功、错误、警告、信息四个级别。
- 事件级与通道级开关：支持分别控制任务完成、子代理完成、审批请求等具体事件的开关，也支持独立启停三种通知渠道。
- 持久化与安全：配置持久化存储，支持 HMR（热重载）后状态不丢失，并遵循浏览器的自动播放策略合规要求。
安装与启用¶
通过 DSH CLI 安装该插件：
dsh plugin --profile web add dsh-hybrid-notify
或者从 GitHub 源码安装：
dsh plugin --profile web add github:john-walks-slow/dsh-hybrid-notify
安装后，插件会自动集成到 DSH Web UI 中。
配置¶
在 DSH Web UI 中打开 设置 → 通知 进行配置。所有设置通过 localStorage 持久化存储，键名为 dsh.notify.config。
事件开关¶
插件支持对以下事件进行独立控制：
| 事件类型 | 默认状态 | 说明 |
|---|---|---|
| 任务完成 | 开 | 会话一轮 turn 结束（running → idle） |
| 子代理完成 | 关 | subagent 会话完成 |
| 审批请求 | 开 | Agent 请求批准操作 |
| 用户提问 | 开 | Agent 向你提问 |
| 计划评审请求 | 开 | Plan 模式等待评审 |
| Agent 出错 | 开 | Agent 遇到错误 |
| 后台任务完成 | 关 | 后台 bash 任务结束 |
注意：当前正在前台查看的会话不会触发通知。
音效设置¶
音效功能包含总开关、音量滑块、前台播放开关以及试听按钮。
注意事项¶
- 通知权限：PWA 与浏览器通知通道需要浏览器通知权限。首个后台事件到达时会自动请求权限（仅当状态为 default 时）；设置页每个通道也有手动授权按钮。页面内 Toast 通道无需任何权限。
- PWA / Service Worker：PWA 通道的 Service Worker 由插件宿主端在
/plugins/dsh-hybrid-notify/sw.js提供，不支持环境自动降级。 - 音效策略：受浏览器自动播放策略约束，AudioContext 在用户第一次点击或按键交互后解锁。首次交互前不会有声音。
- 零网络访问：插件不发起任何外部请求，不做任何上报，所有通知内容来自本地 DSH 会话快照。
- 兼容性：需要支持 Notification API 与 Web Audio API 的现代浏览器。部分移动浏览器不支持
new Notification()，会静默降级为页面内 Toast。 - 构建要求：从源码构建需 Node.js ≥ 18。
总结¶
dsh-hybrid-notify 为 DSH 提供了一套完整的后台消息触达方案，通过智能渠道切换和合成音效，减少了用户频繁查看标签页的需求，适合需要在长时间会话中保持信息敏感度的开发者与用户。
