前言¶
在 DeepSeek Harness (DSH) 的開發與調試過程中，Agent 的思考過程與工具執行狀態往往只能通過日誌體現，缺乏直觀的聽覺反饋。這可能導致開發者難以通過環境音判斷 Agent 的運行狀態或工具調用的成功與否。dsh-soundscape 通過監聽 Agent 狀態與工具生命週期，在本地提供即時的聲音反饋。
這是什麼¶
dsh-soundscape 是一個 DSH 本機音效插件，由 berserk0501 維護。它通過常駐 PowerShell 雙 MediaPlayer 守護進程（$think 思考循環 + $fx 一次性音效）來播放思考、工具、錯誤和情緒提示音。
核心功能¶
- Agent 狀態監聽：監聽
agent/status事件。進入running狀態時循環播放思考音，回到idle狀態時停止思考音並播放結束音。 - 工具音閃避：播放工具音效時，會將思考循環降低至 20%，結束後自動恢復。這實現了無縫混音，避免音效打斷思考循環。
- 情緒感知音效：根據 Agent 的表現播放不同的氛圍音。連續成功觸發上行和絃，連續失敗觸發下行不協和音，長時間運行觸發低頻無人機氛圍音。
- 工具管理：支持對工具音效進行獨立開關與節流保護。
- 音頻資源：內置 15 種零素材 PCM WAV（驗證日誌顯示 12 個），支持用戶在
assets/sounds/目錄下放置<工具名>.wav或<工具名>.mp3進行覆蓋。插件內部會將 MP3 自動轉換爲 WAV。 - 設置面板：提供開關、音量、思考音、工具映射、試聽、重新掃描和打開音效目錄等功能。
- 工具映射：面板展示全部 51 個 DSH 標準工具，支持搜索過濾和逐工具自定義音效。
- 可靠性設計：支持深色模式。配置寫入採用臨時文件替換，卸載時自動清理。守護進程採用滑動窗口重啓策略（30 秒內最多 3 次）。
安裝與啓用¶
在項目目錄下執行以下命令安裝依賴：
npm install --ignore-scripts --legacy-peer-deps
典型用法¶
- 自定義音效：在
assets/sounds/目錄下創建<工具名>.wav或<工具名>.mp3文件，即可覆蓋默認音效。 - 配置映射：通過設置面板自定義工具音效映射和音量，或使用 API 進行配置。
- 掃描更新：如果添加了新的音效文件，點擊設置面板的“重新掃描”功能更新音效列表。
- 測試：使用設置面板的試聽功能或調用
/api/dsh-soundscape/play-test接口進行測試。
適用場景與注意¶
- 適用場景：適合需要在開發過程中通過聽覺反饋監控 Agent 狀態和工具調用的開發者。
- 注意：插件以當前 DSH 進程的權限運行。安裝前應檢查源碼與許可證（MIT）。MP3 轉換緩存由插件管理，不應手工寫入配置。驗證日誌提到 12 個內置音效清單，實際揚聲器聽感、最終代碼完整重啓、真實自定義文件命中和卸載淨驗證仍需人工驗收，不能僅憑日誌推斷通過。
結尾¶
dsh-soundscape 通過雙 MediaPlayer 守護進程和情緒感知機制，爲 DSH Agent 提供了即時的聽覺反饋。開發者可以通過設置面板或 API 快速配置工具音效。更多信息請參考 GitHub 倉庫 或 SkillHub 目錄頁。
