前言¶

DeepSeek Harness (DSH) 在 Agent 運行過程中，除了控制台日誌，缺乏對關鍵狀態的即時聽覺反饋。dsh-agent-sound-alert 插件監聽 DSH 的 Agent 生命週期事件（如完成、審批請求、異常中斷），並在對應時刻播放 macOS 系統音效，幫助用戶在多任務或靜音環境下快速捕捉 Agent 狀態。

插件介紹¶

這是一個運行在 macOS 平臺的 DSH 插件，由 moonlin1213 維護。它通過 Host session 事件 firehose 獲取 Agent 狀態，並調用本地 afplay 工具播放系統預設或自定義音效。

核心定位：macOS 聲音通知插件
許可證：MIT
分發方式：GitHub 源插件（package.json 標記爲 private: true，不發佈至 npm）

核心功能¶

1. 生命週期事件監聽：監聽 turn/end（完成、錯誤、中止、超限）和 approval/asked（審批請求）事件。
2. 系統音效播放：根據不同事件播放默認或自定義的 macOS 系統音效（如 Glass、Tink、Basso 等）。
3. 配置項：
   - enabled：總開關。
   - volume：音量範圍 0 到 1（默認 0.7）。
   - approvalDebounceMs：審批防抖時間，同一會話內防止聲音過於頻繁（默認 2500 毫秒）。
   - includeSubagents：是否包含子代理會話的通知。
   - onCompleted、onApproval、onError、onAborted、onMaxTokens：支持系統音效名稱、絕對音頻文件路徑或 none。
4. 測試命令：提供 agent_sound_alert_test 命令，可傳入 completed、approval、error、aborted 或系統音效名稱進行測試。

安裝與啓用¶

由於倉庫被標記爲 private，無法通過常規 npm 安裝，需使用 DSH 提供的插件分發命令。

1. 克隆倉庫並確保 lib/ 目錄存在（源碼倉庫已包含預編譯的 lib/ 文件夾）：

   git clone https://github.com/moonlin1213/dsh-agent-sound-alert.git
   cd dsh-agent-sound-alert
   # 如果修改了源碼，需運行 build 腳本生成 lib/
   # npm install --legacy-peer-deps
   # npm run check

2. 使用 dev_install_package 安裝插件：

   dev_install_package /absolute/path/to/dsh-agent-sound-alert

3. 在 DeepSeek Harness 中啓用：
   打開 Settings → Plugins → Plugin configuration → agent-sound-alert，開啓 enabled 開關。

開發與調試¶

如果處於開發階段，可以使用 dev_inject_plugin 進行熱加載：

dev_inject_plugin /absolute/path/to/dsh-agent-sound-alert

注意：此命令會將註冊信息寫入 ~/.dsh/super-injector/registry.json，並在重啓後持久化恢復。

若要切換爲正式安裝，需先移除開發注入，再執行正式安裝：

dev_uninject_plugin dsh-agent-sound-alert
dev_install_package /absolute/path/to/dsh-agent-sound-alert

切勿同時保留 dev_inject_plugin 註冊和 dsh.profile.bundles 註冊，否則可能導致配置衝突。

注意事項¶

• 平臺限制：僅支持 macOS，依賴系統自帶的 afplay 命令和 /System/Library/Sounds 音效庫。
• 隱私與網絡：不產生任何網絡請求，不收集遙測數據，僅讀取本地會話事件。
• 併發限制：最多支持三個併發播放進程，插件卸載時會停止所有活躍播放器。
• 事件過濾：用戶主動取消、崩潰恢復回放等特定事件默認不觸發聲音。