macOS 声音提醒 moonlin1213/dsh-agent-sound-alert

dsh-agent-sound-alert

一个用于 DeepSeek Harness 的 macOS 声音通知插件。它监听 Host 会话事件流，并在 Agent 完成一轮对话、请求审批或异常停止时播放本地系统声音。

包名：@dsh-external/dsh-agent-sound-alert

环境要求

- macOS（afplay 和 /System/Library/Sounds）
- 已安装运行时的 DeepSeek Harness
- Node.js 和 npm

该仓库是开源的，但有意在 package.json 中设置了 private: true：它以 GitHub 源码插件的形式分发，而非发布到 npm。

事件与默认值

| 事件 | 含义 | 默认声音 | 设置项 |
| turn/end completed | 回合完成；等待用户输入 | Glass | onCompleted |
| approval/asked | 请求工具审批；按会话去抖 | Tink | onApproval |
| turn/end error / blocked | 回合失败或被阻塞 | Basso | onError |
| turn/end aborted（hook / legacy） | 异常中断，例如策略钩子 | Sosumi | onAborted |
| turn/end max-tokens | 输出达到 token 上限 | Glass | onMaxTokens（默认关闭） |

默认忽略子代理会话。用户主动取消（user、parent 或 disposed）以及崩溃恢复重放（interrupted）不会播放声音。

设置

打开 设置 → 插件 → 插件配置 → agent-sound-alert。更改会实时生效。

- enabled：总开关
- volume：0 到 1，默认 0.7
- approvalDebounceMs：同一会话中审批声音之间的最小间隔，默认 2500
- includeSubagents：是否也为子代理会话发送通知，默认 false
- 声音字段接受 macOS 系统声音名称、绝对音频文件路径或 none

该插件提供 agent_sound_alert_test；传入 completed、approval、error、aborted 或某个 macOS 系统声音名称。

构建

git clone https://github.com/moonlin1213/dsh-agent-sound-alert.git
cd dsh-agent-sound-alert
npm install --legacy-peer-deps
npm run check

该仓库包含一个经过验证的 lib/ 构建产物，因此全新克隆后可直接安装。修改 src/ 的贡献者必须运行 npm run check 并提交重新生成的 lib/。构建脚本会定位最新的有效已安装 DSH 运行时；当自动发现不适用时，设置 DSH_RUNTIME=/absolute/path/to/runtime。

开发注入

仅在开发期间使用 dev_inject_plugin：

dev_inject_plugin /absolute/path/to/dsh-agent-sound-alert

这会在 ~/.dsh/super-injector/registry.json 中写入一个持久条目；DSH 会在重启后恢复它。因此，开发注入与临时的单进程加载并不相同。

正式打包安装 dev_install_package 需要 lib/，该目录已包含在此仓库中。如果你修改了源代码，请先完成构建步骤。在将开发注入转换为正式 bundle 安装之前，请先移除开发注册：

dev_uninject_plugin dsh-agent-sound-alert
dev_install_package /absolute/path/to/dsh-agent-sound-alert

切勿为同一个插件同时保留 dev_inject_plugin 注册和 dsh.profile.bundles 注册。否则 DSH 在冷启动期间可能会恢复两份副本，并失败并报错，例如：

settings namespace "agent-sound-alert" is already registered

正确的正式状态是：

- 一个 profile 依赖
- 一个 dsh.profile.bundles 条目
- ~/.dsh/super-injector/registry.json 中没有匹配的条目
- 一个活动的运行时实例
- cordis.patch.yml 中没有重复的 insert 或意外的 disabled 覆盖

冷启动验证

--dump-config 仅验证静态配置。它并不能证明运行时注入恢复和 bundle 加载不会发生冲突。

正式安装后：

1. 完全退出 DeepSeek Harness。
2. 再次启动它。
3. 确认服务保持运行，并且桌面应用能够进入 WebUI。
4. 确认插件恰好启动一次。
5. 确认日志中既不包含 already registered，也不包含 plugin tree failed to load。

隐私

该插件不发起任何网络请求，也不收集任何遥测数据。它仅读取 DSH 会话生命周期事件，并启动本地 macOS afplay 进程。自定义音频路径不会写入插件日志或工具响应。播放最多限制为三个并发进程，并且在插件卸载时会停止活动的播放器。

许可证

MIT