LaoQianwocao/dsh-sound-player

dsh-sound-player — DSH Web 音效播放器

为 DeepSeek Harness Web GUI 开发的音效播放器插件，
所有操作都集成在设置菜单中（设置 → 音效播放器）。发布为 DSH 客户端插件（dsh.client），支持 GitHub / npm / tarball 分发。

本插件是「音效播放器」，在用户进行对话时，可以在各种阶段（对话终止，请求权限，子代理完成等）发出提示音，提醒用户处理相应状况。

功能

1. 设置页音效播放器（设置 → 音效播放器）
- 总开关、音量、仅当前会话响铃等全局选项；
- 为每种「情况」绑定音效并开关，显示格式如 【√】发送消息时播放【提示音1】；
- 导入音频：选择文件 / 选择文件夹 / 拖拽音频到设置页。

2. 内置默认音效（开箱即用，七种默认情况已预绑定）
- 合成音效（免费、无版权，Web Audio 实时生成）：提示音1（叮）、提示音2（双叮）、完成音（上扬）、通知音（钟声）、询问音、成功音（和弦）、警告音、停止音（下行）；
- 内嵌 Windows 系统提示音：系统提示音·叮（ding.wav）、系统提示音·启动（Windows Startup.wav）、系统提示音·默认（Windows Default.wav）；
- 内置音效标记为 [合成] / [系统]，不可删除，随时可重新绑定。

3. 内置情况
- 对话完成提示（turn-end）
- 发送消息时提示（你发送消息，user-message）
- 权限请求时提示（approval-requested）
- 被提问时提示（AI 弹 ask_user_question，question-requested）
- 服务终止时提示（mux 流断开 / stream-error）
- 子代理运行完成（subagent-complete，任意子代理跑完）
- 最后一个子代理运行完成（last-subagent-complete，当前会话树内所有运行中的子代理全部完成）

4. 供其他插件使用的 API（ctx.get("soundPlayer") 或 window.__dshSoundPlayer__）
- 导入音频：importAudioFile(file) / importAudioFiles(files) / importAudioDir(files)
- 增添情况：addSituation({ label, trigger, audioId?, enabled? }) → 返回 id
- 触发情况并播放音效：triggerSituation(id) / trigger(id)
- 修改情况：setSituation(id, patch)、setSituationEnabled(id, b)、setSituationAudio(id, audioId)、removeSituation(id)
- 其他：listSounds() / listSoundsMeta() / deleteSound(id) / listSituations() / getState() / setEnabled / setVolume / setOnlyCurrentSession / subscribe(fn) / stopAll()

触发方式（trigger）取值

| trigger | 含义 |
| --- | --- |
| turn-end | 对话完成（AI 结束一轮回答） |
| user-message | 发送消息时 |
| approval-requested | 权限请求时 |
| question-requested | 被提问时 |
| stream-end | 服务终止时 |
| subagent-complete | 子代理运行完成 |
| last-subagent-complete | 最后一个子代理运行完成 |
| manual | 手动触发（由插件调用 triggerSituation(id)） |

插件可通过 addSituation 注册自己的情况，并用 triggerSituation(id) 触发；把
自定义 trigger 值传给 addSituation 后，需由插件自己在合适的时机调用
triggerSituation(id) 播放（框架只识别上面列出的内置 trigger 事件）。

安装

要求已安装 dsh CLI（dsh --help 存在）。

从 GitHub 安装（推荐）

dsh plugin add github:LaoQianwocao/dsh-sound-player

第一次安装若 pnpm 提示需要允许构建脚本，把打印出的包 key 填入
profile 的 pnpm-workspace.yaml 的 allowBuilds，然后重跑 add。

从本地 tarball 安装

pnpm pack
dsh plugin add ./dsh-sound-player-0.2.0.tgz

手动注册（无 bundle 时的兜底）

在 profile 的 cordis.patch.yml 中插入：

- insert:
- id: sound-player
name: dsh-sound-player

之后无需改动任何官方文件，重启 dsh web 服务并刷新浏览器页面，即可在设置菜单看到「音效播放器」。

在 dshfind.com 上被发现

本仓库打上 GitHub topic：dsh-plugin（在仓库 Settings → Topics 添加），即可被
dshfind.com 收录 —— 它索引 topic 为 dsh-plugin 的公开仓库。

结构

- package.json — 声明 dsh.client（platform: web）与 dsh.bundle（自注册行）
- cordis.patch.yml — 注册本插件的宿主端行（plugin row）
- lib/index.js — 宿主端（Node half）占位
- client.js — 浏览器端全部功能（存储 / 音效引擎 / 事件监听 / API / 设置页 UI）
客户端前置（inject）

dsh.client.inject 声明的包级依赖为：
@deepseek-ai/dsh-client-connection、@deepseek-ai/dsh-client-runtime。
运行时服务依赖（exports.inject）：connection、sessions、slots。

注意事项

- 浏览器自动播放策略：需要页面有过一次鼠标/键盘交互后音效才会出声（插件会在
首次交互时自动恢复 AudioContext）。
- 音频数据保存在浏览器 IndexedDB（dsh-sound-player 库），配置保存在 localStorage，
均只对本浏览器生效；清浏览器数据会清掉音效库。
- 「服务终止」音效在连接断开约数秒内播放一次（带防抖），避免重连抖动重复响。
- 「子代理运行完成」通过监听 sessions 列表中 origin=subagent 会话的
running 状态翻转检测；「最后一个子代理运行完成」在当前会话树内运行中的
子代理数量从 ≥1 降到 0 时触发。

已知问题

- 设置右上角功能按钮样式偶发错乱：可能导致设置右上角的功能按钮（导出诊断信息 / 打开 DSH 终端 / 重启 / 标准模式）样式混乱，重载后会正常加载。