权限提示音 rongqingwen/dsh-approval-sound

dsh-approval-sound — 权限提示音

给 dsh 的提示音插件：有对话框在等你点的时候响一声，不用一直盯着屏幕——切到别的窗口时尤其有用。

这两种弹窗出现时都会提醒：

- 审批面板——某个工具请求越权执行（「允许一次 / 拒绝」）
- 提问面板——助手在问你问题，计划审核也走这条（选项按钮、跳过 / 提交）

声音由浏览器实时合成，不打包音频文件、不联网；也可以换成你自己的音频。

环境要求

- DSH 0.1.5 或更高，且运行在 Web 端或桌面端。无头（headless）、ACP、SDK 这类没有 Web 层的 profile 用不了——提示音需要页面来播放。
- 支持 Web Audio 的浏览器（现代浏览器都支持）。

安装

四种方式任选。装完必须重启 dsh web / 桌面端（原因见下）。

方式一：下载安装包（最省事）

到 Releases 下载 dsh-approval-sound-<版本>.tgz，然后在桌面端 设置 → 插件 → 安装 里选中它。

方式二：从 GitHub 仓库直接安装

桌面端（带 tag 可锁定版本，推荐）
dsh plugin --profile desktop add github:rongqingwen/dsh-approval-sound#v0.4.1

不带 tag 则跟随 main 的最新代码
dsh plugin --profile desktop add github:rongqingwen/dsh-approval-sound

用 CLI 的 web profile 时，把 desktop 换成 web
dsh plugin --profile web add github:rongqingwen/dsh-approval-sound#v0.4.1

这条路径要求本机能访问 github.com，网络受限的环境需要代理。不带 tag 会跟随 main，所以建议带 tag 锁定版本。

方式三：安装本地目录或本地包

dsh plugin --profile desktop add link:<插件目录>
dsh plugin --profile desktop add <dsh-approval-sound-版本.tgz 的路径>

本地目录要用 link: 前缀，否则会被当成要去 npm 上找的包名。

方式四：手工

1. 把插件目录整个拷进 profile 的 node_modules/dsh-approval-sound/；
2. 在 ~/.dsh/profiles/<profile>/package.json 的 dsh.profile.bundles 里加上 dsh-approval-sound；
3. 重启。

为什么必须重启：宿主半区只在启动时加载一次。刚装好或改过插件之后，运行中的进程里还是旧代码，刷新页面不管用，只有重启能换掉。

本插件零构建、零运行时依赖：host.js 与 client.js 就是可直接加载的产物，不需要 pnpm build，也不会去装任何第三方包。

配置

设置 → 权限提示音，改动即时生效并保存。

| 项 | 默认 | 说明 |
| 审批弹窗出现时播放提示音 | 开 | 总开关 |
| 音色 | 急促双响 | 急促双响 / 清脆铃声 / 钟声 / 水滴 / 自定义音频 / 静音 |
| 音量 | 100% | 0–150%，见下 |
| 重复次数 | 1 | 1 只响一次，2 连响两次……最多 6 |
| 重复间隔 | 900ms | 重复之间的间隔 |
| 最短间隔 | 600ms | 两次提醒之间的强制静默，避免连续弹窗叠成噪音 |
| 仅在窗口不在前台时提醒 | 关 | 见下方提醒 |

设置页还有 试听 按钮：用它确认声音和音量，顺带解除浏览器的自动播放限制。

⚠️ 「仅在窗口不在前台时提醒」打开时，你盯着窗口等弹窗是不会响的（因为你就在前台）。想边看边测，把它关掉。

音色对应哪些情况

不同来源的弹窗音高不同，不看屏幕也能听出是哪一类（下表从低到高）：

| 音色 | 触发 |
| 提问面板 / 计划审核 | 助手在问你问题——最低、最温和 |
| 命令行升级 | bash、pwsh、cmd、shell、terminal_*、run_code |
| 文件写入 | write、edit、read、glob、grep、present |
| 网络请求 | web_search、web_fetch |
| 子代理 / 团队 | subagent、subagent_fork、send_message、workflow |
| 其它工具 | 其余一切 |

音量

上限 150%。输出经过一个限幅器，所以调大得到的是响度而不是破音。还嫌不够醒目，可以把「重复次数」设成 2。

关于"音频被浏览器拦截"

浏览器不允许页面在用户有任何交互之前出声。插件会在你首次点击或按键时自动解锁；如果设置页提示被拦截，点一下「试听」即可。

自定义音频

设置页的 自定义音频 卡片可以上传 / 更换 / 移除自己的提示音：

- 支持 wav、mp3、ogg、m4a、aac、flac、webm，最大 8 MiB；
- 上传后自动切换到它；
- 文件只保存在本机，不会上传到任何地方；
- 上传时会校验扩展名与文件头是否一致，只是改名的文件会被拒绝（否则结果就是"怎么没声音"）；
- 播放时按自身峰值归一化，所以导出音量偏小的音频也能当警报用；
- 如果浏览器解不了这个格式，会回落到内置音色并在设置页给出原因，而不是静默。

排查

| 现象 | 先检查 |
| 完全没声音 | 「仅在窗口不在前台时提醒」是否勾着；音量是否为 0 |
| 试听有声音、弹窗没声音 | 是否在设置里点过 试听（解锁音频）；仍不行就刷新页面，再不行重启 |
| 改了设置没生效 | 刷新页面 |
| 自定义音频没声音 | 设置页是否给出了格式不支持的原因；把音色切回内置验证 |

数据

- 配置：~/.dsh/dsh-approval-sound/config.json
- 自定义音频：同一目录下的 custom.<扩展名> 插件只读取弹窗的工具名或短标签用于选择音色。你提问的正文不会送到浏览器，也不写任何会话数据、不改变任何弹窗的判定结果。

许可证

MIT