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