配置

所有可调参数都是配置字段（官方约定：不把可能需要按部署变化的取值写死在代码里）。默认值定义在 index.js 导出的 Config schema 中；在 profile 的 cordis.patch.yml 里按行 id 覆盖：

⚠️ patch 会整行替换 config（不是深度合并），要保留的字段请一并写上。

- id: fish-sound-notify
  config:
    approvalSound: 'Windows Notify Messaging.wav'
    cooldownMs: 1500
    notifyOnTurnEnd: false

字段	类型	默认值	说明
`enabled`	boolean	`true`	总开关；`false` 时不注册任何行为
`notifyOnQuestion`	boolean	`true`	弹出选项卡时是否响
`notifyOnApproval`	boolean	`true`	请求权限时是否响
`notifyOnTurnEnd`	boolean	`true`	一轮对话结束时是否响
`questionSound`	string	`Windows Notify.wav`	问询音
`approvalSound`	string	`Windows Ding.wav`	权限音
`endSound`	string	`Windows Notify System Generic.wav`	结束音
`cooldownMs`	number	`800`	同一种声音两次之间的最小间隔
`rootAgentsOnly`	boolean	`true`	只对"人面对的根会话"响；`false` 时子 agent 也响
`spawnTimeoutMs`	number	`15000`	播放进程的兜底存活上限，到点强杀，避免残留

音效字段只接受 C:\Windows\Media 下的纯文件名（xxx.wav；含路径分隔符或引号的值会被忽略，以防配置值被当成脚本注入）。查找顺序是「本时刻的音效 → 另外两个时刻的音效 → 系统默认通知音 → notify.wav → chimes.wav」；全都找不到时退回系统"星号"提示音。

卸载：依赖和配置层一起移除，然后重启 DSH

dsh plugin --profile web remove dsh-fish-sound-notify


## 排查（Troubleshooting）

| 现象 | 原因 / 处理 |
| 一声都不响 | 先让 AI 调 `fish_beep` 看 `ok`；若 `ok: true` 但没听到，检查**系统音量**与**声音方案**（Windows 设为「无声」时会静音）、是否远程桌面/无音频设备 |
| `fish_beep` 返回 `ok: false` | 把返回里的 `detail` 原文贴给 AI —— 它写明了失败在哪一步（找不到 PowerShell / 启动失败 / 退出码非 0 / 当前平台不是 Windows） |
| 弹选项卡或请求权限时不响 | 若是**子 agent** 发起，按设计不响（`rootAgentsOnly: true`）；或距上一次同种声音不到 `cooldownMs` |
| `--dump-config` 里没有这一层 | 检查 `package.json` 是否声明了 `dsh.bundle`、`dsh plugin` 的输出有没有报错、profile 的 `dsh.profile.bundles` 里是否列出本包 |
| 声音比画面慢约半秒 | 正常：每次响铃都要启动一个隐藏的 PowerShell 进程（0.3～0.6 秒） |

---

## 已知限制

1. **仅 Windows**（PowerShell + `C:\Windows\Media` 系统音效）。其它平台不发声，但会返回明确原因。
2. **机器级通知**：同一进程里任何"人面对的根会话"提问/请求权限/结束都会响，不区分你在看哪个会话。
3. 起播有约 0.3～0.6 秒延迟（要启动一个隐藏的 PowerShell 进程）。
4. 同一时刻的不同声音可能叠在一起（三种声音各自冷却，互不挤占）。
5. 音效只能用 `C:\Windows\Media` 下的文件名，暂不支持自定义路径。

---

## 许可与作者
MIT · 作者：玉咸鱼 (YUsaltyfish)＆蓝色大肥鱼deepseek

dsh-fish-sound-notify

安装

说明文档

配置

卸载：依赖和配置层一起移除，然后重启 DSH