前言¶
DeepSeek Harness (DSH) 在 Agent 运行过程中，除了控制台日志，缺乏对关键状态的即时听觉反馈。dsh-agent-sound-alert 插件监听 DSH 的 Agent 生命周期事件（如完成、审批请求、异常中断），并在对应时刻播放 macOS 系统音效，帮助用户在多任务或静音环境下快速捕捉 Agent 状态。
插件介绍¶
这是一个运行在 macOS 平台的 DSH 插件，由 moonlin1213 维护。它通过 Host session 事件 firehose 获取 Agent 状态，并调用本地 afplay 工具播放系统预设或自定义音效。
核心定位：macOS 声音通知插件
许可证：MIT
分发方式：GitHub 源插件（package.json 标记为 private: true，不发布至 npm）
核心功能¶
- 生命周期事件监听：监听
turn/end（完成、错误、中止、超限）和approval/asked（审批请求）事件。 - 系统音效播放：根据不同事件播放默认或自定义的 macOS 系统音效（如 Glass、Tink、Basso 等）。
- 配置项：
-enabled：总开关。
-volume：音量范围0到1（默认0.7）。
-approvalDebounceMs：审批防抖时间，同一会话内防止声音过于频繁（默认2500毫秒）。
-includeSubagents：是否包含子代理会话的通知。
-onCompleted、onApproval、onError、onAborted、onMaxTokens：支持系统音效名称、绝对音频文件路径或none。 - 测试命令：提供
agent_sound_alert_test命令，可传入completed、approval、error、aborted或系统音效名称进行测试。
安装与启用¶
由于仓库被标记为 private，无法通过常规 npm 安装，需使用 DSH 提供的插件分发命令。
- 克隆仓库并确保
lib/目录存在（源码仓库已包含预编译的lib/文件夹）：
git clone https://github.com/moonlin1213/dsh-agent-sound-alert.git
cd dsh-agent-sound-alert
# 如果修改了源码，需运行 build 脚本生成 lib/
# npm install --legacy-peer-deps
# npm run check
- 使用
dev_install_package安装插件：
dev_install_package /absolute/path/to/dsh-agent-sound-alert
- 在 DeepSeek Harness 中启用：
打开 Settings → Plugins → Plugin configuration → agent-sound-alert，开启enabled开关。
开发与调试¶
如果处于开发阶段，可以使用 dev_inject_plugin 进行热加载：
dev_inject_plugin /absolute/path/to/dsh-agent-sound-alert
注意：此命令会将注册信息写入 ~/.dsh/super-injector/registry.json，并在重启后持久化恢复。
若要切换为正式安装，需先移除开发注入，再执行正式安装：
dev_uninject_plugin dsh-agent-sound-alert
dev_install_package /absolute/path/to/dsh-agent-sound-alert
切勿同时保留 dev_inject_plugin 注册和 dsh.profile.bundles 注册，否则可能导致配置冲突。
注意事项¶
- 平台限制：仅支持 macOS，依赖系统自带的
afplay命令和/System/Library/Sounds音效库。 - 隐私与网络：不产生任何网络请求，不收集遥测数据，仅读取本地会话事件。
- 并发限制：最多支持三个并发播放进程，插件卸载时会停止所有活跃播放器。
- 事件过滤：用户主动取消、崩溃恢复回放等特定事件默认不触发声音。
