通知音兼容补丁 wangpy886/dsh-agent-notify-kit

DeepSeek Harness 通知音：项目调研与兼容补丁

给 DeepSeek Harness (DSH) 加「回合完成 / 审批 / 提问」提示音时，GitHub 上能用的现成项目其实不多。
这个仓库做了三件事：

1. 把找到的相关项目列清楚、横向对比，说明各自适合什么场景；
2. 记录为什么开箱即用的插件在 DSH 0.2.1-rc.2 上会失灵，以及字段是怎么迁移的；
3. 提供一份已实测可用的补丁（patches/client.js），打上就能全事件响铃。

适用：DSH 0.2.x 桌面版，Windows / macOS / Linux 均可（浏览器插件按 Web Audio 播放）。

一、结论先说

| 需求 | 选择 |
| 只想装一个能用的 | ldchaowin/dsh-plugin-notify-sound + 本仓库补丁 |
| 想要应用内横幅 + 音效 | kjx-talesofai/dsh-plugin-agent-alerts |
| 只想要系统托盘通知、不在乎声音 | chidaic/dsh-agent-notify |

选第一个的理由：事件覆盖最全（完成 / 审批 / 提问 / 计划评审 / 目标受阻 / 失败），配置面板完整， Web Audio 合成音不依赖外部文件，跨平台一致。

二、DSH 专用插件对比

| 项目 | 类型 | 事件覆盖 | 声音 | 配置 | 备注 |
| dsh-plugin-notify-sound | npm 包 dsh-plugin-notify-sound@1.0.0 | 回合完成、后台任务结束、审批、提问、计划评审、目标受阻、失败 | 6 种内置合成音 + 浏览器 TTS 中文播报 + 上传自定义 MP3/WAV | 设置 → 通知铃声，支持逐工作区、逐事件试听 | 需打本仓库补丁才能响应「待确认」事件 |
| dsh-plugin-agent-alerts | bundle 插件 | 完成、提问、审批 | 自带音效 + 自定义音频绝对路径 | 配置文件里填路径，无文件选择器 | 系统级通知回退仅 macOS；Windows 只有应用内横幅 |
| dsh-agent-notify | bundle 插件 | 完成 / 需介入 | 非重点（浏览器 Notification API） | 轻量 | 偏 Windows 系统通知场景 |

三、为什么原版插件在新版 DSH 上只响「完成音」

插件 1.0.0 读的是 sessions.list 返回的行字段：

pendingInteraction // 旧：待确认状态挂在会话列表行上 jobsBySession // 旧：后台任务挂在会话列表行上

DSH 0.2.1-rc.2 把「待确认」整体挪进了 UI 会话状态：

ctx.uiSession.sessionStatus: Map<SessionId, {
running: boolean
pendingInteraction?: { key: string, ... }
completionUnread: boolean
}>

于是：

- 回合完成（running: true → false）—— 旧字段仍能兜到，声音正常 ✅
- 审批 / 提问 / 计划评审（pendingInteraction）—— 旧字段永远是 undefined，不响 ❌

这就是「装了插件但只有干完活才响」的原因。

四、补丁做了什么

patches/client.js 在原插件基础上改了五处：

1. 订阅 ctx.uiSession.sessionStatus
- running: true → false → 播完成音
- pendingInteraction 出现、或换成新的 key → 播注意音
2. 保留旧字段作为回退，兼容更早的 DSH 版本
3. 目标受阻改读 sessions.list 的 projectionsBySession[id].values.goal.phase
4. 子代理回合完成不响铃 —— 工作流里几十个子代理会刷屏；子代理的审批/提问仍然响
5. inject 增加 uiSession

默认声音

| 事件 | 默认音 |
| 一次回答结束 | 风铃 Chime |
| 审批请求 / 提问 / 计划评审 | 叮咚 Ding |
| 目标受阻 | 注意音 |
| 子代理回合结束 | 静音 |

实测

- 模拟当前 sessionStatus：完成、审批、提问、目标受阻均触发；重复广播不重复响 ✅
- 真实链路：应用进程 23:00 启动、补丁文件 23:01 写入，提示音未重启即生效 —— 客户端插件被 HMR 热加载 ✅
- 补丁文件 SHA256：03A748AF4F36EC61F2C204F7E8E0E74FAB1A43B0D9CFA48D370512A1534C5AB6

五、安装

1. 装插件（写入 desktop profile 的 bundles 层）
dsh plugin --profile desktop add dsh-plugin-notify-sound

2. 覆盖补丁 Copy-Item -Force .\patches\client.js "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-plugin-notify-sound\lib\client.js"

3. 生效：客户端插件走 HMR，保存后几秒自动加载；没反应就 Ctrl+R 刷新页面，或重启应用

升级插件后

dsh plugin add / pnpm add 会覆盖 lib/client.js，按上面的第 2 步覆盖回来即可。
仓库里的 patches/client.js 就是可直接覆盖的成品。

六、同需求的其他实现（Claude Code 生态，可参考）

DSH 的插件生态还很小，同类需求在 Claude Code 那边成熟得多，实现思路可以直接借鉴：

| 项目 | 特点 |
| EryouHao/claude-code-sound-notification | 回合结束提示音 |
| jimmyclchu/ccsound | 声音通知工具 |
| jamstop/claude-code-nostalgia-sounds | 怀旧音效包 |
| sergdort/dota2-hero-sounds | Dota2 英雄语音 |
| rubenflamshepherd/claude-code-notif-manager | 通知管理器 |
| mayerwin/AI-Agent-Sound-Notification | 通用智能体声音通知 |
| 777genius/agent-notifications | 智能体通知 |
| alonw0/claude-monitor-esp32 | ESP32 硬件灯/音提示 |
| claudes-world/cctoast-wsl | WSL 下的 toast 通知 |
| pascalporedda/awesome-claude-code | 生态清单，找插件入口 |

这批只从需求角度筛选过，未逐个在 DSH 上验证可用性；兼容性以第二节的三个 DSH 插件为准。

七、许可

本仓库的补丁与文档：MIT。
patches/client.js 是 ldchaowin/dsh-plugin-notify-sound（MIT）的修改版，保留上游版权声明；分发时请同时遵守上游许可。