授权提醒铃 zhangDSK-Xu/dsh-sound-alert

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