dsh-sound-alert —— DSH 授权 / 选择 声音提醒
DSH 需要你授权（工具调用审批）或让你做选择（ask_user_question、计划复核）时，
响一声提示音并弹一条系统通知，不用一直盯着界面等。
🔔 铃铛（常驻、半透明、默认右下角）
点一下 = 开关声音 点 ▾ / 右键 = 打开设置面板
按住可拖到任意角落，松手自动吸附
提醒到达 → 提示音 + 系统通知（带工具名与原因，或问题与选项）+ 标题前加 🔔
功能
| 什么时候会响 | 对应你的操作 |
|---|
某个工具调用需要授权（审批策略 = ask） | 点「允许 / 拒绝」 |
ask_user_question、计划复核（plan-review）等需要选择 | 选选项或填写回答 |
- 只有确实在等人才响：请求发出 500ms 内若已被机器应答（auto-review、fail-closed 的
unavailable 等）不会响铃；请求一被应答就立刻停止重复提醒。
- 完全透明：插件只是旁听，不改变任何授权结果；卸载后行为与安装前完全一致。
- 提示音：Web Audio 合成，无需音频文件。5 种音色：叮、叮咚（默认）、三连升调、铃铛、急促警报。
- 系统通知：收到提醒时弹一条系统通知 —— 桌面端是 Windows 通知（最小化也看得见），
web 端是浏览器通知（首次需要点一下「授权系统通知」或在页面上点一下以通过授权询问）。
通知统一设为
silent，声音交给插件自己的提示音，不会响两次。
- 重复提醒：未处理时按间隔重复（默认每 5 秒，最多 10 次）。以下任一情况立即停止：
请求被应答 / 你在页面上点了任何地方或按了任意键 / 达到次数上限。
- 标题闪烁：未处理时页面标题前面加
🔔 。
- 实时通道：SSE 为主 + 4 秒轮询兜底，所以就算切到别的标签页（浏览器会把定时器节流）
也一样能及时响。
同时监听本机多个 DSH 实例
本机可能同时跑多个 DSH 实例（例如 dsh web 占一个端口、Electron 桌面端占另一个），
而「需要你授权 / 选择」的事件只由真正跑着那个会话的实例发出。
插件默认同时监听本页实例加 http://127.0.0.1:3080、http://127.0.0.1:19387
（列表可在设置面板里增删）；来自其它实例的通知会在正文末尾标出来源，例如 来自 127.0.0.1:3080。
只要保持一个刷新过的页面开着，多个实例的提醒都能听到。端口不同就在设置面板里改。
安装
前提：已装好 DSH（Harness）。
最简单的装法
在 DSH 里打开 设置 → 插件，把下面这行填进安装输入框：
github:zhangDSK-Xu/dsh-sound-alert
或者用命令行一步装好（web 是默认 Web 界面的 profile 名，换成你要装的那个即可）：
dsh plugin --profile web add github:zhangDSK-Xu/dsh-sound-alert
完整的仓库地址也一样能装：https://github.com/zhangDSK-Xu/dsh-sound-alert。
同一行也能装到桌面端（Electron 应用）：打开它的 设置 → 插件，把同一行填进安装输入框
即可 —— 桌面端那个 profile 被 Electron 独占、dsh plugin 命令不允许操作它，但插件页可以。
两端装的是同一份代码，功能一致（区别只在通知由谁发出：桌面端是 Windows 通知，web 是浏览器通知）。
装好后插件会出现在设置 → 插件的清单里（带图标与显示名），可以直接从界面禁用或卸载。
网络：如果你的环境需要代理才能访问 GitHub，先给当前终端设上代理再执行安装，例如
$env:HTTPS_PROXY = 'http://127.0.0.1:7897'（端口换成你自己的）。
其它装法
从本地目录装 —— 适合自己改插件代码的时候，改完不用重装：
dsh plugin --profile web add link:D:/path/to/dsh-sound-alert
profile 补丁层挂载 —— 兜底手段：当某个 profile 既不能用 dsh plugin、也无法从插件页安装时，
在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 末尾追加：
- insert:
- id: dsh-sound-alert
name: '<本仓库绝对路径>/lib/entry.mjs'
该文件被 HMR 监视，保存后约 10 秒生效，不需要重启。
注意这种方式不会出现在插件的包清单里 —— 它只是一行配置，不算「已安装的包」。
卸载
dsh plugin --profile web remove dsh-sound-alert
补丁层方式装的，删掉 cordis.patch.yml 里那条 - insert: 条目即可。
使用
- 铃铛（默认右下角）：点一下开关声音；点旁边的 ▾ 或右键铃铛打开设置面板。
- 拖动：按住铃铛拖到任意位置，松手自动吸附到最近的一角（右下 / 左下 / 右上 / 左上），
位置会被记住；设置面板会跟着铃铛所在的角走。
- 设置面板：启用开关、提示音、铃铛位置、音量、未处理时重复间隔、重复上限、
标题闪烁、系统通知（窗口外也能看见）、额外监听的 DSH 地址，底部是「恢复默认」
（桌面端另有「重载页面」，用于让插件更新后的页面脚本重新加载）。
设置保存在浏览器
localStorage。
浏览器自动播放限制：页面必须先有一次用户交互才允许出声。插件会在你第一次
点击或按键后补响这一次提醒；即使没出声，系统通知与标题闪烁仍会出现。
装完之后没看到铃铛？
按下面的规则刷新或重启，然后刷新页面即可看到：
| 你做了什么 | web 端 | 桌面端 |
|---|
| 新装 / 卸载插件 | 刷新页面（宿主侧会自动装载；刷新后仍没有就重启 dsh web） | 重启应用 |
| 更新插件到新版本 | 重装后重启 dsh web | 重装后重启应用 |
| 只改了页面脚本 | 刷新页面 | 面板里点「重载页面」 |
| 改设置项 | 即时生效 | 即时生效 |
桌面端的页面注入表是应用启动时采集一次的启动载荷，所以增删插件必须重启；
而页面脚本本身每次请求都会重新读盘，所以只改脚本时刷新页面就够。
注意事项
- 必须至少有一个加载过插件的页面开着才会响；页面关掉就没有监听者了。
- 多个浏览器标签页各自会响一次。
- 「额外监听地址」默认是
3080 / 19387，换端口请在设置面板里改。
- 页面脚本不感知 DSH 的会话切换：通知只展示提醒内容，不会跳到对应会话。
- 提示音用 Web Audio 合成；Safari 上首次交互前同样无声（交互后会补响）。
- Windows 的专注助手 / 勿扰模式会静音系统通知（不弹横幅，但仍会进通知中心
Win+N）；
想更稳妥可以同时保留声音。
自检
# 插件是否在线：streams >= 1 表示浏览器里的页面脚本已经连上
Invoke-WebRequest http://127.0.0.1:3080/dsh-sound-alert/health.json -UseBasicParsing
# 手动发一条测试提醒
Invoke-WebRequest http://127.0.0.1:3080/dsh-sound-alert/test.json -Method POST -UseBasicParsing
（把 3080 换成你实际使用的端口。）
health.json 里的 client 字段是页面侧自报的诊断信息（脚本版本、通知权限、最近一次
通知结果），排查「通知没弹出来」时很有用。
许可
MIT
