前言¶
DeepSeek Harness（DSH）里的智能体会长时间占用一轮会话：写代码、调工具、等 API。浏览器标签页在后台时，你只能靠切回窗口看状态是否从运行中变成空闲。社区插件按「一切皆插件」的方式扩展 DSH；dsh-sound-notify 属于客户端类插件，在运行 DSH 的本机上用系统音频播放器播短音，并在设置里为三类事件各留一个开关。
下面介绍插件做什么、如何安装，以及使用时需要注意的平台与版本差异。
这是什么¶
- 仓库：hifengzy/dsh-sound-notify
- 维护者：hifengzy（package.json 作者 fengzhuoyu）
- 许可证：MIT
- 当前包版本（package.json）：0.1.0
- 分类：客户端（SkillHub 目录归类）
插件在 DSH 宿主进程里监听会话与代理状态，在任务结束、失败或需要你介入时播放仓库内自带的 AAC 音效；播放不依赖浏览器标签是否前台，标签最小化或关闭后，只要本机 DSH 进程还在跑，仍可能听到提示音。
核心功能¶
三类事件与对应音效¶
| 事件 | 触发条件 | 音效文件 |
|---|---|---|
| 任务完成 | turn 以 completed 结束 |
sounds/success.aac |
| 任务失败 | turn 以 error / max-tokens 结束，或 API 失败并调度重试（llm/retry） |
sounds/fail.aac |
| 等待你操作 | 审批提示（approval/asked）、ask_user_question、turn 被中止 / 阻塞 / 中断 |
sounds/stop.aac |
三个独立开关¶
默认全部开启，写入 DSH 设置并即时生效，无需重启进程即可按配置静音某一类：
| 开关（UI） | 关闭时配置 | 效果 |
|---|---|---|
| Task completed | success: false |
不播完成音 |
| Task failed | failure: false |
不播失败 / API 错误音 |
| Waiting for you | waiting: false |
不播审批 / 提问 / 中止音 |
降噪与并发行为¶
README 中说明的实现策略包括：
- 子 agent 会话不发声，避免父任务委派后每个子 turn 都响一次。
- 进入
idle后 500 ms 宽限期：若队列输入或自动续跑立刻开始，则取消本次提醒。 - 同一 turn 内自动重试只播一次失败音。
- 同一类别两次播放之间 700 ms 冷却。
宿主侧只订阅事件总线（如 session/event、agent/status、user-questions/request），不改写会话日志，也不影响审批结论（提问瀑布流监听器会调用 next()）。
平台与播放器¶
| 平台 | 播放器 | 说明 |
|---|---|---|
| macOS | afplay |
README 标注为已验证 |
| Linux | paplay（PulseAudio / PipeWire） |
需系统提供 paplay |
| Windows | — | 无 AAC 命令行播放器；记录诊断日志并保持静音 |
与 DSH 版本的设置入口¶
| DSH | 设置界面 |
|---|---|
| 0.2.x（含 desktop 0.2.1-rc.2） | 侧栏 Plugins → Sound notifications（插件页卡片；配置在 profile 的 cordis.patch.yml 插件条目的 config 中，每次通知时读取） |
| 0.1.x | Settings → Sound notifications（sound-notify 命名空间，位于 $DSH_HOME/settings.yaml） |
安装与启用¶
安装方式因 profile 类型不同。插件以当前 DSH 进程权限运行，安装前建议阅读仓库源码与 MIT 许可证；音效文件随仓库分发，许可与代码相同。
CLI 管理的 profile（web、headless 或自定义 profile）¶
任选 README 列出的一种来源（包内容相同）。将 web 换成你的 profile 名即可。
# 从 GitHub 安装
dsh plugin --profile web add github:hifengzy/dsh-sound-notify
# 从 GitHub Release 附带的预构建 tarball 安装
dsh plugin --profile web add https://github.com/hifengzy/dsh-sound-notify/releases/latest/download/dsh-sound-notify.tgz
# npm（包发布后可用；见仓库 docs/PUBLISHING.md）
dsh plugin --profile web add dsh-sound-notify
dsh plugin add 会把包装进 profile，并把 dsh-sound-notify 写入 dsh.profile.bundles；包内 cordis.patch.yml 负责挂载插件行。安装后需重启该 profile 对应的应用。
确认是否编入配置树：
dsh --profile web --dump-config | grep -A2 sound-notify
Desktop app（Electron 的 desktop profile）¶
dsh CLI 不能管理保留的 desktop profile。官方提供幂等脚本（会备份 patch 文件）：
git clone https://github.com/hifengzy/dsh-sound-notify.git
cd dsh-sound-notify
./scripts/install-desktop.sh
然后重启 DSH 桌面应用。桌面宿主不会热挂载新加的 profile 插件，首次启用必须重启。重启后在 Plugins → Sound notifications 可见三个开关；完成任意任务应能听到 success.aac。
脚本实质是把 lib、sounds、package.json、cordis.patch.yml 等复制到 $DSH_HOME/profiles/desktop/node_modules/dsh-sound-notify，并在 cordis.patch.yml 中插入 id: sound-notify 条目；细节见 README 中 Manual desktop install 折叠段。
典型用法¶
- 按上一节完成安装并重启对应 app / profile。
- 打开 Plugins → Sound notifications（0.2.x）或 Settings → Sound notifications（0.1.x），按需关闭某一类声音。
- 发起一轮会正常结束的 DSH 任务，在本机（非浏览器）应听到完成音；若需验证「等待你」类，可触发审批或
ask_user_question流程。
调试时可在启动 DSH 之前设置环境变量（桌面宿主无终端时尤其有用）：
DSH_SOUND_NOTIFY_LOG=/tmp/dsh-sound-notify.log dsh web
日志示例：
2026-10-19T17:21:05.071Z [sound-notify] notifyIdle reason=completed kind=success
2026-10-19T17:21:05.071Z [sound-notify] enabled success = false (config)
2026-10-19T17:21:05.071Z [sound-notify] muted success
缺文件或找不到音频播放器时也会写入日志，而不是静默失败。
适用场景与注意¶
适合：本机长期跑 DSH（web、headless 或 desktop），希望离开窗口时仍能靠声音感知「跑完了」「错了」或「要你点批准 / 回答问题」的开发者。
注意：
- 声音在运行 DSH 的那台机器上播放；远程 SSH 里跑 headless 时，响的是服务器侧音频环境（若存在），不是你家笔记本扬声器，除非你另有转发方案。
- Windows 当前无播放实现；Linux 需
paplay。 - Node 引擎要求
>=20（package.jsonengines）。 - 社区目录 awesome-dsh-plugin（
category: notify）与 SkillHub 等站点是生态收录渠道，与 DeepSeek / 幻方无官方从属关系；仓库已准备awesome-dsh-plugin.yml与scripts/submit-to-catalog.sh供收录使用。
结尾¶
dsh-sound-notify 用三类可关的声音，把 DSH 长跑会话里的完成、失败和待你介入从「必须盯窗口」变成「本机可听」。需要安装命令、开关含义与平台限制时，以 GitHub README 为准。
- 目录页：https://www.skillhub.cn/plugins/hifengzy/dsh-sound-notify
- GitHub：https://github.com/hifengzy/dsh-sound-notify
