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。风铃声音由本仓库脚本程序化合成，无第三方素材版权问题。