前言¶
用 DeepSeek Harness（DSH）跑长任务时，浏览器标签不一定在前台：任务跑完、上下文被压缩、或智能体在等你回答澄清问题时，单靠页面状态很容易漏掉。@zaykoff/dsh-sound-alerts 在 Host 进程所在机器 上播放短音频提示（本地 Web GUI 场景即你的 PC），与浏览器标签是否获得焦点无关。下面按插件定位、触发条件、安装与配置说明用法。
这是什么¶
@zaykoff/dsh-sound-alerts 是 DSH 的 bundle 插件，维护者为 ZaykoFF（Alexander Zaykov），在社区目录中归类为客户端。它在三种智能体状态下发出可配置的短音效：任务完成、上下文溢出开始压缩、以及智能体提问后等待你的回答。
三种提示与触发来源¶
插件监听 DSH 会话 API / 事件，对应关系如下（默认音效路径见表）。
| 情况 | 触发 | 默认声音 |
|---|---|---|
智能体任务完成（running → idle） |
api-session/status |
sounds/task_done.wav（三下轻敲，dong-ding-ding） |
上下文溢出：历史压缩开始（token 压力自动化、上下文窗错误恢复、/compact） |
session/event，type 为 compaction/start |
sounds/cache_overflow.wav（两下低沉闷响） |
| 智能体提出澄清问题并等待回答 | session/event，type 为 tool/call（ask_user_question；备用：user-questions/request 瀑布流处理审批类问题） |
sounds/question.wav（两声短促轻 tick） |
内置音效由 scripts/make_sounds.py 生成：短鼓点式敲击，单次时长约 1 秒内，峰值约 -12 dBFS，意在低调、无长残响。同一类提示在 minIntervalMs 内不会重复播放。子智能体会话默认不发声（includeSubagents: false）。
各平台播放行为¶
- Windows：优先用 PowerShell
SoundPlayer播放.wav；文件不可用或非.wav路径时，用[console]::beep按相同节奏播放静音替代敲击。 - macOS：
afplay。 - Linux：依次尝试
paplay、aplay；文件缺失时不发声（无 beep 回退）。
环境与版本要求¶
- DSH：
>=0.2.2-rc.1且<0.3.0（与package.json中engines.dsh一致）。 - Host 操作系统：Windows、macOS 或 Linux（见上节播放方式）。
安装前请自行查看 GitHub 仓库 源码与 MIT 许可证；插件随 DSH Host 进程运行，权限与当前 dsh 一致。
安装与启用¶
任选其一（版本以资料为准：@zaykoff/dsh-sound-alerts@1.4.2）：
- 让 Harness 智能体通过
plugin_manager工具的install_bundle，目标设为@zaykoff/dsh-sound-alerts@1.4.2。 - 在终端执行（需
pnpm在PATH上）：
dsh plugin --profile <profile-name> install @zaykoff/dsh-sound-alerts@1.4.2
安装后 bundle 会插入 agent-sound-alerts 插件项并默认启用；在 profile 的 cordis.patch.yml 里改该项的 config 即可。若要用本地开发目录而非发布包，可通过 plugin_manager → install_bundle 指定目录绝对路径（以 link: 安装，改磁盘文件后可在下次 profile 重组时生效，无需重启）。
配置说明¶
在 profile 的 cordis.patch.yml 中配置 agent-sound-alerts 条目。profile 层会整体替换该条目的 config（不按字段合并 bundle 默认值）；未写的键会回退到插件内置默认，因此可以只写部分字段：
- id: agent-sound-alerts
config:
enabled: true # 总开关
includeSubagents: false # 是否为子智能体会话也播放
minIntervalMs: 1000 # 同一类提示的最小重复间隔
testOnStart: false # true 时插件激活后依次播放三种提示
testGapMs: 2500 # 自检时各提示之间的间隔
debugLogFile: false # true 时写诊断到 debug.log（或自定义路径）
# sounds 可整段省略，使用内置鼓点；也可用绝对路径覆盖单个 .wav，或 false 关闭某类提示：
# sounds:
# taskDone: 'D:\Sounds\done.wav'
# cacheOverflow: false
# question: 'D:\Sounds\question.wav'
调试时可设 testOnStart: true，确认 Host 上三种节奏是否都能听到；Windows 上若要自定义音效，路径需为 .wav 才走文件播放。
适用场景与注意¶
适合长时间开着 DSH、需要离开键盘或切换窗口、但仍想感知「跑完了 / 要压缩了 / 在等你答」的开发者。不适合期望在远程纯浏览器端（无 Host 音频）听到提示的场景——声音只在 Host 机器上播出。
子会话默认静音，若你依赖子智能体同样提醒，需显式设 includeSubagents: true。Linux 下缺少音频文件时不会回退 beep，需保证 sounds/*.wav 存在且 paplay/aplay 可用。
参考链接¶
- 社区目录：https://www.skillhub.cn/plugins/ZaykoFF/dsh-sound-alerts
- 源码与 README：https://github.com/ZaykoFF/dsh-sound-alerts
DSH 生态强调「一切皆插件」；社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。若你的 profile 已有多项 patch，记得在 agent-sound-alerts 的 config 里保留所需字段，避免误关 enabled 或把自定义 sounds 写漏。
