DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”。在使用 DSH 进行智能体开发时，开发者需要明确的反馈来确认 Agent 是否完成了当前的任务，或者在长时间等待时收到提示。DSH 原生自带完成音效，但功能较为单一。dsh-completion-sound 插件在此基础上扩展了音效、长任务特殊音乐提醒以及桌面通知功能。
核心功能¶
该插件提供以下功能：
- 完成音效：使用 WebAudio 合成双音调（E5 → A5）提示单次交互完成。
- 长任务音乐：当任务时长超过阈值（默认 10 分钟）时，播放特殊音乐并显示一个“点击任意处停止”的模态框。
- 自定义特殊音乐：支持指定单个音频文件，或指定一个音频目录（插件会随机扫描并播放目录中的文件）。
- 预置音频资源：内置“关羽歌”音频文件（约 13.5 MB），位于
assets/guan-yu.wav。 - 可配置阈值：长任务阈值可在 1 分钟至 10080 分钟（7 天）之间调整。
- 桌面通知：提供跨平台的桌面通知支持，优先使用浏览器通知，在不可用时自动回退到系统通知（macOS 使用
osascript，Linux 使用notify-send）。 - 独立设置页面：所有配置集中在“设置 → 完成音效”页面。
- 冲突处理：该插件通过
cordis.patch.yml禁用了 DSH 内置的完成音效行（ui-completion-sound），并插入自己的配置行，避免在同时启用两者时出现双重播放。
安装与启用¶
安装该插件会将其添加到指定的 DSH 配置文件（profile）中。安装命令如下：
dsh plugin --profile web add github:jensentsts/dsh-completion-sound
请将 web 替换为你实际使用的 profile 名称。由于构建产物已提交，安装过程无需额外授权构建权限。
如果你需要固定特定的代码版本以防止后续更新引入变更，可以使用 commit hash 进行安装：
dsh plugin --profile web add github:jensentsts/dsh-completion-sound#<sha>
卸载命令：
dsh plugin --profile web remove @jensentsts/dsh-completion-sound
配置说明¶
在 DSH 界面的“设置 → 完成音效”页面中，可以进行以下配置：
- 启用：开关完成音效。
- 通知：开关桌面通知功能。
- 音量：音量大小，范围 0-1，默认 0.5。
- 长任务阈值：触发特殊音乐的分钟数，默认为 10。
- 特殊音乐：开关长任务完成时是否播放特殊音乐。
- 特殊路径：指定特殊音乐文件的路径或目录路径。留空则使用内置的“关羽歌”。
特殊路径语义：
* 空字符串：使用内置的 assets/guan-yu.wav。
* 文件路径：播放该文件。
* 目录路径：递归扫描该目录下的音频文件（支持 .aac, .flac, .m4a, .mp3, .oga, .ogg, .opus, .wav, .webm，最多 512 个），每次播放时随机选择一个。
注意事项¶
- 权限与安全：安装插件意味着在本地机器上运行第三方代码，并使用当前用户权限。在安装前，请务必审查其源码。
- 系统依赖：桌面通知的系统级回退功能需要系统环境支持。Linux 系统通常需要安装
libnotify-bin（提供notify-send），macOS 则依赖内置的osascript。 - 插件架构：这是一个 DSH Bundle，通过
package.json中的dsh.bundle.patch指向cordis.patch.yml，并在dsh.client中声明了web平台的注入逻辑。
总结¶
dsh-completion-sound 通过音效和通知机制，解决了智能体开发中“何时结束”和“长时间等待”的感知问题。它提供了从简单音报到长任务提醒的完整配置能力，适合需要精细化控制交互反馈的开发者。
