音乐提醒 67-68/dsh-music-alert

dsh-music-alert

DSH 任务完成 / 模型提问播放提示音 + 按需音乐播放插件。

长任务完成时自动播放一段完成音；模型调用 ask_user_question 提问时自动播放一段提问音；智能体也可通过 play_music 工具主动播放。Web 设置页提供「音乐提醒」面板：上传 / 试听 / 完成播报&提问播报下拉多选 / 删除 / 启停开关。

Overview

- 解决什么问题：DSH 长任务（构建、批量生成、耗时等待）完成后、或模型通过 ask_user_question 提出结构化提问时，用户往往不在屏幕前。本插件在每轮 turn 结束（agent/status → idle）时播放完成音，在模型提问（session/event → tool/call name=ask_user_question）时播放提问音，把用户叫回来看结果。
- 适合谁：本地运行 DSH（macOS / Linux）且希望有声音提醒的用户。
- 能力：
- Host 半（lib/index.js）：完成播报 + 提问播报 + play_music 工具 + play-music skill 引导 + musicAlert Remote 服务（音乐库读写）。
- Web 半（lib/client.js）：设置页「音乐提醒」tab（上传 / 列表 / 播放 / 完成播报&提问播报下拉多选 / 删除 / 启用开关），通过 dsh.client 双面声明加载。

Compatibility

- 面向 DeepSeek Harness（DSH）Web profile。
- peer 依赖：@deepseek-ai/* ^0.1.0-rc.6、@deepseek-ai/cordis ^4.0.1、react ^18.2.0。
- 平台：Host 半调用系统命令行播放器（macOS afplay；Linux aplay / paplay / ffplay / mpg123）；Web 半渲染于 Web profile 设置页。
- 最后验证：本地 dsh web（当前 mainline）实测通过（自动播报 + 工具 + Web tab），验证日期见仓库最近提交。

Install / Uninstall

安装（npm，发布后）：

npx @deepseek-ai/dsh plugin add dsh-music-alert

或从 git 安装（插件市场走的也是 git 克隆 + 质量门禁）：

npx @deepseek-ai/dsh plugin add github:67-68/dsh-music-alert

若 web 不是默认 profile，需追加 --profile web。

升级（重装到新版本）：

npx @deepseek-ai/dsh plugin add dsh-music-alert@latest

卸载：

npx @deepseek-ai/dsh plugin remove dsh-music-alert

卸载只会移除依赖与挂载行；音乐文件保留在 ~/.dsh/music/，不会被删除。

Quick start

1. 安装后重启 dsh web。
2. 放任意受支持音频到 ~/.dsh/music/，然后在设置页「音乐提醒」tab 展开「完成播报」「提问播报」两个下拉，分别勾选要响的音乐（可多选，触发时随机播其中一首）。
3. 完成一个任务 → 自动播放完成音；模型提问 → 自动播放提问音；智能体也可主动调用 play_music 工具。

智能体工具调用示例：

play_music # 播放随机一首完成音 play_music file=ding.wav # 播放指定文件

Configuration

| 配置项 | 默认值 | 说明 |
| musicDir | ~/.dsh/music | 音乐库目录，支持前导 ~ 展开 |
| enabled | true | 是否启用声音提醒（完成音 + 提问音的总开关） |
| player | 自动探测 | 播放器命令；未指定时按 afplay → ffplay → mpg123 → aplay → paplay 顺序探测 |
| minGapSeconds | 0 | 两次自动播报之间的最小间隔（秒） |

运行状态持久化于 ~/.dsh/music/.state.json（enabled / events）：

{ "enabled": true, "events": { "completion": ["complete.mp3"], "question": [] } }

- events.completion：完成播报使用的音乐文件名列表（触发时随机播其中一首）。
- events.question：提问播报使用的音乐文件名列表（触发时随机播其中一首）。
- 旧版单值 defaultFile 会在加载时自动迁移为 events.completion = [defaultFile]。

支持音频扩展名：.mp3 .wav .m4a .ogg .flac .aac .aiff .caf。

Permissions & data

- 文件：仅读写 ~/.dsh/music/（音乐文件 + .state.json）。文件名经 basename + 扩展名白名单 + .. 路径穿越校验，不会触碰目录之外的路径。
- 网络：无。本插件不发任何网络请求。
- 进程：通过 spawn 调用本地命令行播放器（detached / unref），不读取任何凭据或环境密钥。
- 上传：设置页上传的文件以 base64 写入音乐库目录，仅本地保存。

Troubleshooting

- 不播报：确认 ~/.dsh/music/ 下存在音乐，且设置页「启用声音提醒」已开启、对应事件（完成播报 / 提问播报）已勾选至少一首。
- macOS 无声音：确认 afplay 可用（which afplay）。
- Linux 无声音：安装 ffplay / mpg123 / aplay / paplay 之一。
- 当前播放器：设置页「音乐提醒」tab 顶部会显示探测到的 player。
- 日志：Host 侧失败会打印 [dsh-music-alert] ... 到 DSH 进程输出。

开发

- 结构：
- lib/index.js — Host 半：默认导出 Cordis 插件，注册 play_music 工具、play-music skill、musicAlert Remote 服务；监听 agent/status（完成播报）与 session/event 的 tool/call（提问播报），共用 enabled + minGapSeconds 节流。
- lib/client.js — Web 半：dsh.client 双面，手写 Typert Remote face，渲染设置页「音乐提醒」tab（上传 / 列表 / 播放 / 完成播报&提问播报下拉多选 / 删除）。
- 发布前校验：npm pack --dry-run 检查产物；keywords 必须含 dsh-plugin，入口文件 export default 一个 Cordis 插件。
- 贡献：欢迎 issue / PR。

许可证与安全

- 许可证：MIT（见 LICENSE）。
- 安全问题：请私下通过 GitHub issue 或仓库维护者邮箱报告，勿公开披露。