@lium7768/dsh-sound-notifier
v0.2.1
Published
DeepSeek Harness profile bundle with tiered turn-end sounds: plan produced, task done, input needed, or turn failed.
Maintainers
Readme
DSH Sound Notifier Plugin
@lium7768/dsh-sound-notifier 是独立的 DeepSeek Harness Profile Bundle。它安装到 DSH Profile,不修改 deepseek-harness 主仓库,并在每轮对话结束时按语义分级播放提示音 —— 出方案、干完活、要你回应、出错各用一种声音,窗口在后台时也能听见。
设计参考了社区插件 dsh-perlica-ding 的分级逻辑(普通问答静音、四档语义、按 agent 防抖),但不使用 TTS 人声:所有音效由本项目的 tools/make-sounds.py 用代码合成,无第三方音频、无版权负担。
触发规则
| 音位 | 触发条件 | 判断依据 |
|---|---|---|
| plan 出方案 | 回合结束时仍处于计划模式 | agent/turn-stopping 时 planMode 服务为 active;服务不可用时回退到实时折叠 plan/mode 事件 |
| done 干完活 | 回合结束,且本回合调用过执行类工具 | tools/result 的工具名命中 execTools 白名单,且时间戳晚于本回合开始 |
| ask 要你回应 | agent 向你提问,或发起审批请求 | tools/execute 调用 ask_user_question;approval/request |
| fail 出错 | 回合报错 | agent/error |
| 静音 | 普通问答、只用了只读工具(读文件/搜索网页等) | 本回合没有任何执行类工具 |
"干完活"而不是"每轮都响" 是关键:你随口问一句话,即使它读了个文件、搜了个网页,回合结束也是安静的 —— 只有真正改了文件、跑了命令、派了子代理才算任务完成。
其他行为:
- 只响主对话:子代理(subagent)完成时不单独响,由派它的那个主回合统一收尾
- 按档独立防抖:每种声音默认 2.5 秒内不重复,不会连响
- 声音可覆盖:查找顺序
soundDir→ 进程工作目录 → 包内自带 → 系统音效,放个同名wav即可替换,无需改代码
声音
四个音效由代码合成(sounds/*.wav,44.1kHz 单声道 16-bit PCM),没有任何人声:
| 音位 | 时长 | 设计 |
|---|---|---|
| done.wav | 0.62s | E6→A6 上行两音,轻敲音色 —— "做完了" |
| plan.wav | 0.34s | A5 同音双击 —— "有东西等你看" |
| ask.wav | 0.40s | F#5 单音上行滑音 —— "需要你决定" |
| fail.wav | 0.60s | F3+E3 小二度低音双击 —— "出错了" |
统一特征:8ms 淡入、指数衰减、2% 音高下滑(避免机械感)、全部 0.6 秒内、峰值归一化到同一响度。
想调整音色就改 tools/make-sounds.py 里的音高/衰减参数重新生成:
npm run sounds # 需要 python3配置
| 字段 | 默认值 | 含义 |
|---|---|---|
| enabled | true | 总开关 |
| debounceMs | 2500 | 同一音位的最小间隔(毫秒) |
| volume | 1 | 音量,0 到 1(0 等于静音) |
| soundDir | '' | 自定义音效目录,空则用包内自带的 |
| execTools | 16 个执行类工具 | 算作"干完活"的工具名白名单;空数组表示任何工具都算 |
| rootOnly | true | 子代理会话静音 |
| player | 按平台自动 | afplay(macOS)、paplay / aplay(Linux) |
默认 execTools:bash、pwsh、write、edit、subagent、subagent_fork、workflow、ralph、job_kill、create_goal、update_goal、todo_write、cordis_define、cordis_run、cordis_stop、cordis_undefine。
配置错误在插件加载时直接报错,不会静默降级:未知字段、非布尔开关、越界音量、非法 debounceMs、非字符串 soundDir、非法 execTools、不支持的 player 都会让装载失败。
安装
从 npm 安装(推荐)
npm install @lium7768/dsh-sound-notifier把包加进目标 Profile 的 package.json,并在 dsh.profile.bundles 中登记(两处都要,缺一不可:依赖决定包能否被解析,bundle 决定插件是否被挂载):
{
"dependencies": {
"@lium7768/dsh-sound-notifier": "^0.2.1"
},
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@lium7768/dsh-sound-notifier"]
}
}
}然后在 Profile 目录安装并重启:
cd ~/.dsh/profiles/web
pnpm install升级到新版本时改 dependencies 里的版本号(或用 pnpm up @lium7768/dsh-sound-notifier),再 pnpm install 并重启会话。
从 GitHub 安装
dsh plugin --profile web add https://github.com/Lium-7768/dsh-sound-notifier安装后重启对应 profile 生效。
从源码安装(开发)
git clone https://github.com/Lium-7768/dsh-sound-notifier
cd dsh-sound-notifier
npm run verify # 语法检查 + 单元测试 + 打包预检
npm run pack # 产出 dist/lium7768-dsh-sound-notifier-<version>.tgz开发时可在 Profile 的 dependencies 里用 link: 指向本地源码目录,但正式使用请改用上面的 npm 版本。
安装到桌面应用
桌面 Profile(~/.dsh/profiles/desktop)由 Electron 应用独占管理,dsh CLI 会拒绝操作它,需要手工改 package.json 并用应用自带的 pnpm 安装(版本不符会试图重建整个 node_modules):
cd ~/.dsh/profiles/desktop
~/Library/pnpm/.tools/pnpm/11.7.0/bin/pnpm install --store-dir ~/.dsh/desktop/pnpm/store/v11桌面版要求 bundle 解析到 Profile 或运行时目录之内,因此必须用 file: 装进 node_modules,不能用 link: 链到 Profile 之外的目录。
工作原理
| 文件 | 职责 |
|---|---|
| lib/index.js | Cordis 插件入口:接线 6 个事件到播放 |
| lib/handler.js | 每 agent 的回合状态跟踪与结束判定(含"无执行工具则静音") |
| lib/kinds.js | 四个音位定义、执行类工具白名单、计划模式状态跟踪(订阅实时事件,不用已废弃的同步日志读取) |
| lib/config.js | 配置校验,非法值 fail loud |
| lib/player.js | 音效查找(四级回退)与异步播放 |
| tools/make-sounds.py | 音效合成脚本 |
播放用 child_process.spawn + detached + unref:音频不阻塞、不延迟那一轮对话;播放器缺失或退出非零只写一条 warn 日志,绝不影响会话本身。
测试
npm run check # 语法检查
npm test # 33 个测试:音位分类、配置校验、回合判定、音效查找、播放器参数