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 通過音效和通知機制，解決了智能體開發中“何時結束”和“長時間等待”的感知問題。它提供了從簡單音報到長任務提醒的完整配置能力，適合需要精細化控制交互反饋的開發者。
