potterlee369-prog/dsh-sound-notifier

dsh-sound-notifier

DSH Web 插件：任务完成时在浏览器中播放音效提示，并且区分“自然完成”与“中途中断”两种音效；当弹出需要用户选择的选项时也会播放提示音。会话一轮任务结束（agent 从运行转为空闲）的瞬间，页面会播放对应提示音——即使你正切在别的标签页也能听到。

本项目依赖 DSH Web 宿主环境的插件运行时，不能脱离宿主单独运行。

- 自然完成 vs 中断：任务正常收尾播放“完成提示音”（默认清脆铃声）；被用户停止、模型请求出错、输出截断等中断播放“中断提示音”（默认短促提示音）。
- 用户选择提醒：ask_user_question 弹出选项、计划审批（plan review）等需要用户选择/确认的弹窗出现时，播放独立的“选择提示音”（默认叮咚）。权限审批弹窗默认关闭，可在设置中开启。
- 四种内置提示音：清脆铃声、叮咚、成功和弦、短促提示音。全部用 Web Audio API 实时合成，零音频资源文件；完成音、中断音与选择提示音可各自独立选择。
- 设置面板：在 设置 → 音效提示 中可开关提示、分别选择音效并行内试听、调节音量。
- 多标签去重：同一完成/中断/选择提示事件即使开了多个 dsh 标签页也只响一声（BroadcastChannel 抢占协议）。
- 子任务控制：默认只在主会话完成时提醒，可开启“包含子任务”让子代理完成也响。

工作原理

- 完成检测：订阅客户端 sessions.list 状态存储，跟踪每个会话 running: true → false 边沿——与侧边栏的完成状态使用同一条宿主状态流，信号权威可靠。首次观测只记录状态（页面加载时已完成的会话不会补响）。
- 完成/中断分类：当前选中（打开中）的会话有实时事件窗口（Session.events，与状态帧同一条有序连接），边沿时刻读取最后一个 turn/end 的 reason.kind 分类：
| reason.kind | 含义 | 音效 |
|---|---|---|
| completed | 自然完成 | 完成提示音 |
| aborted | 用户点击停止 | 中断提示音 |
| error | 模型请求出错 | 中断提示音 |
| max-tokens | 输出达到上限被截断 | 中断提示音 |
| blocked | 输入被拒绝（预步否决） | 中断提示音 |
| interrupted | 日志中断（崩溃恢复） | 中断提示音 |
- 后台会话（未选中、无事件窗口）无法读到 reason，统一按自然完成播放。
- 选择检测：订阅客户端 sessions.list 状态存储，跟踪每个会话 pendingInteraction 从无到有的边沿——question 和 plan-review 对应 ask_user_question/计划审批弹窗，播放“选择提示音”；approval 权限审批默认不提醒，可手动开启。首次观测只记录状态（页面加载时已挂起的弹窗不会补响）。
- 播放引擎：振荡器 + 增益包络合成；浏览器自动播放策略通过首次用户手势（点击/按键）解锁 AudioContext，由于任务必然由交互发起，播放时上下文已处于可播放状态。
- 配置存储：选项保存在 localStorage（dsh.sound-notifier.v1），对每个浏览器独立生效。当前宿主设置接口不提供第三方插件的配置命名空间，因此本插件不自带宿主侧配置。

安装

1. 安装到 web profile（link: 方式，源码改动即时生效，无需重新 add）
将下面的路径替换为本地 checkout 路径。
dsh plugin --profile web add "C:\path\to\dsh-sound-notifier"

2. 在 web profile 的插件挂载配置中加入：
- insert:
- id: sound-notifier
name: dsh-sound-notifier

3. 重启 dsh web

重启后打开页面右上角 设置 → 音效提示，点“试听”确认声音正常，然后正常发起任务，完成后听到完成音；点停止按钮即可听到中断音。

配置（浏览器设置面板）

| 选项 | 默认值 | 说明 |
|---|---|---|
| 启用完成音效 | ✅ 开 | 完成/中断音效总开关 |
| 完成提示音 | 清脆铃声 | chime / ding / success / ping，行内可试听 |
| 中断提示音 | 短促提示音 | 同上，独立选择 |
| 启用选择提示音 | ✅ 开 | 弹出需要用户选择的选项（ask_user_question / plan review）时播放 |
| 选择提示音（音色） | 叮咚 | 同上，独立选择 |
| 权限请求也提醒 | ❌ 关 | 权限审批弹窗也播放选择提示音 |
| 音量 | 60% | 0–100%，实时生效 |
| 仅当前会话 | ❌ 关 | 只在本标签页当前选中的会话完成时提醒 |
| 包含子任务 | ❌ 关 | 子代理（subagent）会话完成时也提醒 |

开发循环

cd C:\path\to\dsh-sound-notifier
npm ci              # 首次安装依赖
npm test            # 构建并运行两个冒烟测试

如果只需要生成 bundle，可单独运行 npm run build。

改完代码后 node build.mjs，然后重启 dsh web（客户端插件清单在启动时扫描，/plugins/... 的 hash 也取启动时快照；link: 安装意味着无需重新 pnpm add）。

注意事项

- 仅 web profile 验证过（声音来自浏览器）；headless 下无声。
- 后台会话无法区分完成/中断：未选中的会话没有事件窗口，统一按自然完成播放；若需要精确区分，请保持会话处于选中状态。
- 两个标签页同开时由抢占协议保证只响一声；若两个标签页因系统时间差异极小概率同时响，属预期内行为。
- 局域网远端浏览器访问时声音在远端浏览器播放（音频在浏览器端），设置也按远端浏览器独立保存。