dsh-sound-alert

dsh-sound-alert —— DSH 授权 / 选择 声音提醒

DSH 需要你授权（工具调用审批）或让你做选择（ask_user_question、计划复核）时， 响一声提示音并弹一条系统通知，不用一直盯着界面等。

🔔 铃铛（常驻、半透明、默认右下角）
     点一下 = 开关声音        点 ▾ / 右键 = 打开设置面板
     按住可拖到任意角落，松手自动吸附

提醒到达 → 提示音 + 系统通知（带工具名与原因，或问题与选项）+ 标题前加 🔔

---

功能

• 只有确实在等人才响：请求发出 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。

浏览器自动播放限制：页面必须先有一次用户交互才允许出声。插件会在你第一次 点击或按键后补响这一次提醒；即使没出声，系统通知与标题闪烁仍会出现。

装完之后没看到铃铛？

按下面的规则刷新或重启，然后刷新页面即可看到：

桌面端的页面注入表是应用启动时采集一次的启动载荷，所以增删插件必须重启； 而页面脚本本身每次请求都会重新读盘，所以只改脚本时刷新页面就够。

---

注意事项

• 必须至少有一个加载过插件的页面开着才会响；页面关掉就没有监听者了。
• 多个浏览器标签页各自会响一次。
• 「额外监听地址」默认是 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