音效与桌面通知 cwd514/dsh-sound-notifications

dsh-sound-notifications

给 DSH（DeepSeek Harness）的行为加上「音效」和「桌面通知」的插件。智能体答完了、卡在等你批准、抛了个问题过来——这些「你没盯着屏幕时发生的事」，都用声音和系统通知告诉你。

额外依赖包 0 个，构建步骤 0 步。声音用 Web Audio 合成，通知图标当场用 canvas 画出来，所以随包附带的媒体文件只有 1 张图标。压根不给供应链风险留余地。

内置的通知

| 类型 | 触发条件 | 默认 |
| 响应完成 | api-session/status 为 running=false | ON |
| 等待批准 | approval/request（正文带工具名和理由） | ON |
| 提问 | user-questions/request（正文带问题内容） | ON |
| 错误 | api-session/error（长文本截到 160 字） | ON |
| 重新登录 | deepseek-account/session-expired / model-sign-in-required | ON |
| 目标续跑 | goal/activation-changed（armed / disarmed） | ON |
| 开始处理 | api-session/status 为 running=true | OFF |
| 定时任务 | schedule/changed | OFF |

批准和提问用 requireInteraction: true 弹出，回答一返回就自动关闭。因为用了 tag，同类型的通知也不会堆叠。

内置的音效

开始处理（短促 2 音）／响应完成（上行 3 音）／等待批准（明亮和弦响 2 遍）／提问（发问式 2 音）／错误（低沉下行 2 音）。全部用振荡器合成，不带音频文件。

运行环境

- 已在 DSH 0.2.0-rc.2 的 Web UI（配置档 web）上验证可运行
- 通知需要 secure context。http://127.0.0.1:3080 和 https:// 都算，但用 http:// 打开局域网 IP 时通知本身就用不了（这种情况下，那一行会显示原因，只有音效会响）
- 音效用 Web Audio API，通知只用 Notifications API。两者都是浏览器标准功能，没有引入 polyfill

安装

有两种方式。先用 Plugin Manager 应该最省事。

1. 从 Plugin Manager 安装（推荐）

在 DSH 的「设置 → 插件」安装栏里，把下面这行 spec 原样填进去执行。

github:cwd514/dsh-sound-notifications

想交给智能体办，就让它在 plugin_manager 工具的 install_bundle 里，把同一个字符串作为 target 传进去。GitHub 仓库在 pnpm 之前会做一次可达性检查（git ls-remote，默认 5 秒），公开仓库直接就能过。

2. clone 下来指定路径

git clone https://github.com/cwd514/dsh-sound-notifications.git

然后用绝对路径作为 spec 安装（不接受相对路径）。

plugin_manager install_bundle target="/absolute/path/dsh-sound-notifications"

安装通过后，设置 → 通用 靠下的位置会出现「音效」和「桌面通知」两行。没生效就刷新一次页面。

没有发布到 npm（保持 private: true）。想从 npm 安装，得把 @local 作用域改成你自己的再发布。

配置

「音效」那一行

总开关、音量滑块，以及 5 种音效各自的开关和试听按钮。音效按类型独立，可以只关掉开始音、保留完成音，随你调。

「桌面通知」那一行

总开关 拨到 ON 的那一刻就是用户操作，所以此时向浏览器申请通知权限。已经授权过的话，改为弹一次测试通知。

- 未授权 → 「允许通知」按钮
- 已授权 → 显示「已授权」＋「测试通知」按钮
- 已拒绝 → 提示去站点设置里允许＋「重新检查」按钮（浏览器不接受已拒绝过的页面再次申请）
- 环境不支持通知 → 禁用总开关并显示原因

关掉「仅在标签页非活跃时通知」（默认 ON），盯着窗口时也会弹通知。关掉「同时播放系统通知音」（默认 ON），通知就静音，只响上面的音效。

通知收不到时该怀疑什么

1. 浏览器的通知权限（拒绝过的话，去站点设置里改回来）
2. 是不是 secure context（127.0.0.1 / localhost / https）
3. 「仅在标签页非活跃时通知」还开着 ON，而你一直把标签页放在前台干活
4. 系统侧的通知设置、专注模式、勿扰模式
5. 各类型通知的开关是不是被关了
6. 标签页是不是关了（见下面的「限制」）

排查时，在控制台执行 __dshSound.lastNotified() 最快。所有尝试显示过的记录都以 {kind, at, shown, reason, permission} 保留着，看 reason 是 off / kind-off / visible / permission / unsupported 里的哪一个，就知道卡在哪道关卡了。

限制（希望你提前知道）

- 关闭标签页就收不到。 这套配置用不了 Service Worker，也用不了 Push，所以通知只在页面打开期间有效
- 通知遵循每个浏览器、每个来源的许可。用 http:// 打开局域网 IP 时，通知本身就用不了
- 声音和通知的设置保存在浏览器的 localStorage 里，不会带到别的浏览器或别的电脑
- 能触发声音的事件，只限于 DSH 转发的固定事件列表。每次工具执行、子代理的进度、工作流的各个阶段都不在其中
- 通知不区分会话。同时跑多个会话时，从正文看不出是哪个完成了
- 音效第一次可能不响：受浏览器自动播放策略限制，必须「用户操作之后」才会播放

从控制台试用

在浏览器控制台里可以用 __dshSound。

| 调用 | 内容 |
| __dshSound.play('approval') | 强制播放音效（忽略设置） |
| __dshSound.lastPlayed() | 播放历史（最近 20 条） |
| __dshSound.settings() / set({...}) | 读取／写入音效设置 |
| __dshSound.notify('error', 'テスト') | 强制显示通知（需要许可） |
| __dshSound.notifyPermission() | granted / denied / default / unsupported |
| __dshSound.requestNotifyPermission() | 请求许可 |
| __dshSound.notifySettings() / setNotify({...}) | 读取／写入通知设置 |
| __dshSound.lastNotified() | 通知尝试历史（最近 20 条，带 reason） |
| __dshSound.closeNotifications() | 关闭所有正在显示的通知 |
| __dshSound.state() | 音频底层状态（supported / audioState / 实际音量） |

隐私

完全不对外通信，也不发送遥测。作为通知正文的批准理由、提问文本、错误消息，只是当场切成字符串交给操作系统，不在任何地方保存或发送。保存下来的只有设置（localStorage 的两个键）。

开发

node --check client.js # 構文
node test/smoke.mjs # ブラウザを模したサンドボックスで23項目

test/smoke.mjs 把 client.js 加载到 Node 的 vm 上，配上浏览器桩，验证这些内容：行的注册、8 个事件的订阅、通知的闸门顺序（off → kind-off → visible → permission）、批准与提问 waterfall 的直通以及回答时自动关闭、正文截断、localStorage 持久化、两行的渲染。同一套测试也会在 GitHub Actions 上跑。

结构是 4 个文件。index.js 是 Host 侧（这个插件不给 Host 加任何东西），client.js 负责 UI、声音、通知的全部，cordis.patch.yml 负责插入行，package.json 是包的声明。

许可证

MIT

DSH（DeepSeek Harness）插件，给 harness 事件加上短促的合成音和桌面通知，让你在看向别处时也能注意到发生了什么：一次运行结束、有批准在等待、有人提问、发生错误、登录过期、目标继续。

零依赖，零构建步骤，除了图标没有任何媒体文件——音调用 Web Audio 生成，通知图标在运行时画进 canvas。

安装

github:cwd514/dsh-sound-notifications

把这段 spec 粘贴到插件管理器的安装输入框（Settings → Plugins），或者作为 target 传给 plugin_manager 的 install_bundle 工具。克隆仓库再安装它的绝对路径也可以。之后，Settings → General 里会出现两行：「Sounds」和「Desktop notifications」。

覆盖范围

通知：运行结束、批准等待（正文里有工具名和理由）、有人提问（提问文本）、错误（截断到 160 个字符）、需要登录、目标继续——默认全部开启——再加上运行开始和计划变更，默认关闭。批准和提问的横幅是常驻的，答案一到就自动关闭。
提示音：运行开始、运行结束、等待审批、有人提问、出错。

设置

提示音这一行有总开关、音量滑块，以及每种提示音各自的开关和试听按钮。通知这一行里，打开总开关就是那个用户手势，用来向浏览器申请权限（如果已经授权，就弹一条测试横幅）；随后这一行会显示权限状态，允许时提供测试按钮，被拦截时指向站点设置。「仅在标签页不活跃时」（默认开启）和「同时播放系统通知音」（默认开启）控制横幅何时出现、以及横幅自己要不要发声；八个按类型划分的开关决定哪些事件会发通知。

限制

- 只有标签页打开时才会收到通知：这个包只带客户端那一半，所以没有 service worker，也没有推送。
- 通知需要安全上下文（https、localhost 或 127.0.0.1）。在局域网 IP 上用纯 http 打开界面会让通知失效；提示音照常播放。
- 权限一旦被拒绝，就无法再从页面上申请——要去浏览器的站点设置里恢复。
- 设置存在 localStorage 里，所以是按浏览器、按源分别保存。
- 通知不会说明是哪个会话触发的。
- 没有网络请求，也没有遥测。审批理由、提问内容、错误消息只会渲染进横幅，绝不存储，也不发送到任何地方。

开发

node --check client.js
node test/smoke.mjs

test/smoke.mjs 把 client.js 加载进 Node 的 vm 上下文，配上浏览器桩，验证行注册、事件订阅、通知门控顺序（off → kind-off → visible → permission）、审批与提问的瀑布式放行和自动关闭、正文截断、localStorage 持久化，以及两行的渲染。同样的检查也在 GitHub Actions 里跑。

MIT 许可。