审批风铃提醒 jyd1230/dsh-approval-chime

dsh-approval-chime 🐋🔔

给 DeepSeek Harness 加一个「审批弹窗风铃提醒」：每次需要人工确认的审批弹窗出现时，播放一声约 3 秒的清脆风铃声。

人不在屏幕前、或在房间另一头时，不会再错过「确认修改文件」之类的弹窗。

- ✅ 零外部依赖：纯 Node 实现，声音由插件内置脚本现场合成（五声音阶风铃）
- ✅ 只响给「真弹窗」：监听宿主 approval/request 事件，自动放行、不阻塞审批链
- ✅ 宿主侧播放：声音由 DSH 进程播放，浏览器最小化/在后台也照常响
- ✅ 防抖动：1.5 秒内连续多个弹窗只响一次（可配置）
- ✅ 一键安装 / 一键卸载，幂等可重复执行

已在 DSH 0.1.0-rc.6（web profile）/ Windows 10/11 实测通过。

一、安装

需要：Windows + Node.js 18+（DSH 自带即可）。约 1 分钟。

1. 下载本仓库并解压（或 git clone）
git clone https://github.com/<你的用户名>/dsh-approval-chime.git
cd dsh-approval-chime

2. 一键安装（默认安装到 web profile）
node install.mjs

指定其它 profile：
node install.mjs --profile <profile名>

安装脚本会自动完成：

1. 合成风铃并保存到 $DSH_HOME/assets/approval-chime.wav
2. 把插件包复制到 profile 的 node_modules（含扁平回退目录）
3. 往 $DSH_HOME/profiles/<profile>/cordis.patch.yml 追加挂载行（幂等）
4. 输出重启提示

最后一步：完全重启 DSH（关闭控制台窗口后重新运行 dsh web），否则补丁层不会加载。

验证是否成功

触发一次需要确认的操作，例如让 AI 修改工作区之外的文件、或执行一条沙箱授权命令。审批弹窗出现时应响起风铃（约 3 秒）。

二、使用说明

装好之后不需要任何操作——只要出现需要人工确认的界面，就自动响铃：

- 文件修改/写工作区外文件等需要「允许/拒绝」的审批弹窗 → 响铃
- 选项式提问卡片（ask_user_question）和计划审批卡片（exit_plan_mode）→ 响铃
- 已经被「总是允许」授权的操作（不再弹窗）→ 不响铃（符合直觉：没弹窗就不提醒）

两条通道（审批 / 提问）走的是宿主里不同的机制，插件各挂了一个监听器；监听器在宿主级，因此对这台 DSH 上的所有会话、所有浏览器标签页生效——确认框出现在哪个网页都会响。

配置项（可选）

打开 $DSH_HOME/profiles/<profile>/cordis.patch.yml，找到 id: approval-chime 的行，修改 config：

| 字段 | 默认值 | 说明 |
| chimeWav | 安装时写入 | 风铃 WAV 绝对路径；改为空串 '' 可临时静音 |
| powershell | C:/Windows/System32/WindowsPowerShell/v1.0/powershell.exe | 播放器宿主，一般不用改 |
| throttleMs | 1500 | 连续弹窗的节流间隔（毫秒） |
| enableLog | false | 是否写调试日志 |
| logPath | '' | 日志绝对路径（enableLog: true 时必填，需可写） |

修改后重启 DSH 生效（补丁层在启动时加载）。

换声音

node scripts/generate-chime.mjs 我的新风铃.wav

然后把行配置里的 chimeWav 改成新路径即可。想调音色/时长/音量，编辑 scripts/generate-chime.mjs 顶部的常量（音高 NOTES、错落时间 STARTS、衰减 DECAY_TAU、总时长 DURATION、音量 MASTER），重新生成。

卸载

node uninstall.mjs # 保留风铃 WAV
node uninstall.mjs --remove-wav # 连声音文件一起删

然后重启 DSH。也可以手动操作：删掉 cordis.patch.yml 里 id: approval-chime 的 insert 块、删掉两个 node_modules/dsh-approval-chime 目录。

三、工作原理

审批弹窗出现 │ ▼ 宿主 approval/request 瀑布事件 │ （本插件 prepend 在链头） ▼ fire-and-forget 启动 powershell │ SoundPlayer.PlaySync(风铃.wav) ← 约 3 秒 ▼ 立即 next() 放行审批链 → 弹窗正常显示/应答

弹窗应答和响铃完全并行，互不阻塞。

四、注意事项 ⚠️

1. 仅支持 Windows。播放依赖 PowerShell 5.1 的 Media.SoundPlayer。macOS/Linux 需要换播放机制（PR 欢迎）。
2. 必须重启 DSH 才生效。补丁层（cordis.patch.yml）只在启动时加载；改任何配置后都要重启。
3. 声音由系统默认输出设备播放，音量跟随系统音量；如果听不到，先检查扬声器/音量，再用「验证是否成功」一节的方法排查。
4. 插件本体是宿主级代码，具备该 profile 的全部能力——安装前建议过目 lib/index.js（全文 150 行左右，无网络请求、无文件读写，只 spawn 播放命令）。
5. 调试日志默认关闭。开 enableLog 后每次弹窗会 spawn 一个 powershell 写一行日志，属正常开销；排查完建议关掉。
6. 已知坑位（开发者必读）：
- export const inject = ['subprocess'] 不能去掉。补丁层行在启动早期初始化，此时 ctx.get('subprocess') 会拿到 undefined，导致静默早退；必须声明注入，让 Cordis 等服务就绪。
- { prepend: true } 不能去掉。approval/request 是瀑布链，apiproxy（网页弹窗应答者）注册更早，回答时不调用 next()，排在后面的监听器永远执行不到。
- 播放必须 fire-and-forget，监听器里绝不能 await 播放完成，否则每次审批都会被拖慢约 3 秒。
7. 升级/回滚：本插件无运行时状态，直接覆盖包目录 + 重启即可。

五、目录结构

dsh-approval-chime/
├── install.mjs # 一键安装（幂等） ├── uninstall.mjs # 一键卸载 ├── lib/ │ └── index.js # 插件本体（宿主侧，~150 行） ├── scripts/ │ └── generate-chime.mjs # 风铃 WAV 合成器（纯 Node，零依赖） ├── package.json ├── LICENSE # MIT └── README.md

六、许可证

MIT。风铃声音由本仓库脚本程序化合成，无第三方素材版权问题。