dsh-sound-alert —— DSH 授权 / 选择 声音提醒
DSH 需要你授权（工具调用审批）或让你做选择（ask_user_question、计划复核）时，
在页面播放提示音并弹出提醒卡片，不用一直盯着界面等。
┌──────────────────────────────┐ 🔔 铃铛（常驻、半透明、默认右下角）
│ 授权 需要你授权 │ 点一下 = 开关声音
│ 工具：pwsh │ 点 ▾ / 右键 = 打开设置面板
│ 原因：需要写入工作区外的文件… │ 按住可拖到任意角落
│ [知道了] 12:30:05 │
└──────────────────────────────┘ ← 提醒卡片（最多同时 3 张）
功能
| 什么时候会响 | 对应你的操作 |
|---|---|
某个工具调用需要授权（审批策略 = ask） |
点「允许 / 拒绝」 |
ask_user_question、计划复核（plan-review）等需要选择 |
选选项或填写回答 |
- 只有确实在等人才响：请求发出 500ms 内若已被机器应答（auto-review、fail-closed 的
unavailable等）不会响铃；请求一被应答就立刻停止重复提醒。 - 完全透明：插件只是旁听，不改变任何授权结果；卸载后行为与安装前完全一致。
- 提示音：Web Audio 合成，无需音频文件。5 种音色：叮、叮咚（默认）、三连升调、铃铛、急促警报。
- 提醒卡片：显示授权工具名、或问题正文与选项、以及时间；点「知道了」关闭。 同一时刻最多 3 张，30 秒自动淡出。
- 重复提醒：未处理时按间隔重复（默认每 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:19387。
只要保持一个刷新过的页面开着，多个实例的提醒都能听到。端口不同就在设置面板里改。
安装
前提：已装好 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。
装好后插件会出现在设置 → 插件的清单里（带图标与显示名），可以直接从界面禁用或卸载。
网络：如果你的环境需要代理才能访问 GitHub，先给当前终端设上代理再执行安装，例如
$env:HTTPS_PROXY = 'http://127.0.0.1:7897'（端口换成你自己的）。
其它装法
从本地目录装 —— 适合自己改插件代码的时候，改完不用重装：
dsh plugin --profile web add link:D:/path/to/dsh-sound-alert
profile 补丁层挂载 —— 只用于 CLI 无法操作的 profile（例如被 Electron 独占的 desktop）。
在 $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。
浏览器自动播放限制：页面必须先有一次用户交互才允许出声。插件会在你第一次 点击或按键后补响这一次提醒；即使没出声，提醒卡片与标题闪烁也一定会出现。
注意事项
- 必须至少有一个加载过插件的页面开着才会响；页面关掉就没有监听者了。
- 多个浏览器标签页各自会响一次（同一实例内按「来源#seq」去重）。
- 「额外监听地址」默认是
3080/19387，换端口请在设置面板里改。 - 插件热重载或服务器重启的那一瞬间，页面的 SSE 会收到不可恢复错误，插件会在 3 秒后 手动重连；重连完成前仍有 4 秒轮询在跑，不会漏提醒。
- 页面脚本不感知 DSH 的会话切换：卡片只展示提醒内容，不会跳到对应会话。
- 提示音用 Web Audio 合成；Safari 上首次交互前同样无声（交互后会补响）。
自检
# 插件是否在线：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 换成你实际使用的端口。）
No comments yet. Be the first to write one.