dsh-audio-cue：DeepSeek Harness 音頻提示插件

前言¶

DeepSeek Harness（DSH）允許開發者以插件形式擴展功能。在長時間運行智能體任務時，屏幕上的終端輸出可能無法直觀反映當前是處於“思考/工作中”還是“等待決策”的狀態。dsh-audio-cue 插件通過音頻反饋解決這一問題：在工作時播放背景音，在需要用戶介入時發出提示音。

插件簡介¶

dsh-audio-cue 是一個運行在 DeepSeek Harness 環境下的音頻插件，由 Goothe13-gugu 維護，採用 MIT 許可證。

它的核心作用是在智能體工作時提供聽覺反饋，幫助開發者通過聲音判斷當前狀態。

核心功能¶

• 工作環境音：當會話處於開啓狀態（思考或執行任務）時，播放背景音頻。
• 提示音：當智能體請求審批或提問時，停止背景音並播放提示音。
• 閒置淡出：當工作停止時，背景音自動淡出。
• Web 設置面板：提供可視化的設置界面，無需手動編輯配置文件。
• 控制台 API：支持通過 JavaScript 腳本控制插件狀態。
• 子代理支持：子代理的開放回合會被計入“工作”狀態，繼續播放背景音。
• 持久化配置：設置保存在宿主機而非瀏覽器端。

安裝與啓用¶

安裝命令如下：

dsh plugin --profile web add github:Goothe13-gugu/dsh-audio-cue

如果需要固定版本，可以使用標籤：

dsh plugin --profile web add github:Goothe13-gugu/dsh-audio-cue#v0.1.0

安裝完成後，必須重啓 Harness 配置文件才能掛載該插件。

使用方法¶

檢查狀態¶

通過瀏覽器控制台或腳本，可以查詢插件當前狀態：

__DSH_AUDIO_CUE__.state()

控制台 API¶

插件提供了以下 API 供腳本調用：

__DSH_AUDIO_CUE__.state()                       // 獲取狀態
__DSH_AUDIO_CUE__.toggle()                      // 開關切換
__DSH_AUDIO_CUE__.setVolume(0.4)                // 設置音量
__DSH_AUDIO_CUE__.setEnabled(false)             // 啓用/靜音
__DSH_AUDIO_CUE__.open()                        // 打開設置面板
__DSH_AUDIO_CUE__.settings()                    // 獲取設置
__DSH_AUDIO_CUE__.refresh()                     // 刷新配置
__DSH_AUDIO_CUE__.history()                     // 獲取狀態變更歷史
__DSH_AUDIO_CUE__.setPosition(520)              // 調整按鈕位置

配置與存儲¶

設置文件位置¶

配置存儲在宿主機的 DSH 目錄下，而非瀏覽器緩存中。目錄結構如下：

$DSH_HOME/dsh-audio-cue/
  ├── settings.json      # 存儲靜音、音量、播放模式及音效選擇
  └── uploads/           # 導入的音頻文件

數據安全¶

設置文件通過“臨時文件 + 重命名”的方式寫入，防止崩潰導致配置損壞。如果配置文件損壞或不可讀，插件會使用默認值。如果導入的音效文件丟失，會自動回退到默認音效。

狀態判斷邏輯¶

插件訂閱會話事件日誌，根據以下規則判斷當前狀態：

狀態變化通過 Server-Sent Events 流 (/dsh-audio-cue/events) 發佈。

注意事項¶

• Node.js 版本：插件運行需要 Node.js 版本大於等於 22。
• 子代理處理：任何開啓回合的會話（包括子代理）都會被視爲“工作”，背景音不會中斷。
• 權限範圍：插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證。

總結¶

dsh-audio-cue 通過環境音和提示音，爲 DSH 用戶提供了直觀的狀態反饋。其 Web 面板和 Console API 設計，兼顧了易用性與可編程性。

• GitHub 倉庫
• 插件目錄