dsh-ui-chime — DSH 消息提示音插件

当智能体工作"停下来"等待你时，用提示音提醒你：权限审批确认、问题确认、智能体回合结束、目标达成 四类事件，各自可独立配置提示音（10 个内置音可选），支持总开关、音量、单事件开关。设置界面在 设置 → 提示音。

声音由宿主进程在本机扬声器播放（不经浏览器音频），因此不受浏览器自动播放策略、标签页隐藏等限制。

npm 包名：dsh-ui-chime

安装

# 方式一：从 npm 安装（正式包）
dsh plugin --profile web add dsh-ui-chime

# 方式二：本地链接安装（开发）
dsh plugin --profile web add D:\outProject\.tmp\dsh-chime

# 重启 dsh web 后生效；浏览器打开 设置 → 提示音 进行配置

卸载：

dsh plugin --profile web remove dsh-ui-chime
# 重启 dsh web 生效；配置保留在 $DSH_HOME/settings.yaml 的 chime: 段（可手动删除）

事件与默认音

| 事件 | 触发时机 | 默认音 | |---|---|---| | 权限审批确认 | 工具调用需要你批准时 | 04-确认音 | | 问题确认 | 智能体提问等待回答时 | 03-消息弹出 | | 智能体回合结束 | 一轮回复完成时 | 06-快速叮咚 | | 目标达成 | goal 进入 complete 时 | 10-游戏成功 |

全部内置音：01-欢快铃声、02-双声蜂鸣、03-消息弹出、04-确认音、05-数字短音、06-快速叮咚、07-气泡通知、08-清亮提示音、09-吉他通知、10-游戏成功。

工作原理

• 事件检测（浏览器端）：监听 sessions 服务的会话状态——pending 等待（审批/提问）、回合时间线（turn/end）、goal 投影（phase 转为 complete）。首次观测为基线（历史重放不发声），只对加载后新到的事件发声；同一事件在多标签页只响一次（宿主按 dedupKey 去重）。
• 播放（宿主端）：POST /chime/play → mpg123-decoder（纯 WASM，不依赖系统解码器）解码 mp3 → 按音量软件衰减 → 进程内 winmm PlaySoundW（经 koffi，内存直接播放，无进程派生、无临时文件，约 30ms 出音）；koffi 不可用时自动降级为 PowerShell + MCI waveaudio 兜底。新声音抢占旧声音。
• 配置：settings 命名空间 chime，持久化于 $DSH_HOME/settings.yaml。

限制

• 发声位置 = 宿主所在机器的扬声器；宿主进程与浏览器均需运行。
• 播放后端 v1 仅支持 Windows（winmm 系统自带）。
• 浏览器标签页关闭时无事件检测（检测在浏览器端）。
• 若浏览器曾阻止过有声播放，与插件无关（插件不经过浏览器音频）。

故障排查

• 宿主控制台出现 [dsh-chime] play failed: ... → 声音文件缺失/解码失败，检查插件包 sounds/ 目录。
• 设置页「提示音」区块不出现 → 插件未安装成功（dsh plugin --profile web add 后需重启）。
• 提示音不响但配置正常 → 检查总开关、音量、该事件启用开关；确认宿主机器有可用音频输出。

开发

• 源码结构：lib/index.js（宿主半）、lib/client.js（浏览器半，由 scripts/inline-detect.mjs 从 lib/detect.js 内联生成）、sounds/*.mp3（内置音）。
• 修改 lib/detect.js 后运行 node scripts/inline-detect.mjs 重新生成 lib/client.js（有漂移守卫测试 test/inline.test.mjs 把关）。
• 测试：node test/decode.test.mjs、node test/playback.test.mjs、node test/host.test.mjs、node test/detect.test.mjs、node test/inline.test.mjs（沙箱环境请用进程内运行，勿用 node --test）。
• 隔离测试：可用独立 DSH_HOME + dsh --profile web --port 3090 起测试实例，避免触碰生产 profile。