前言¶
在 DSH (DeepSeek Harness) 中開發或運行智能體時，會話可能持續很長時間，且用戶視線往往在瀏覽器其他標籤頁或應用中。若缺乏有效的通知機制，後臺任務完成、審批請求或錯誤信息可能被遺漏。
dsh-hybrid-notify 插件通過監聽窗口可見性，根據用戶當前是否在瀏覽器前臺，自動在頁面內 Toast、PWA 系統通知和瀏覽器通知之間切換，並使用 Web Audio API 合成音效，確保關鍵事件能夠被準確捕獲。
核心功能¶
該插件主要解決後臺運行時的消息觸達問題，核心能力包括：
- 三通道自動選擇：根據窗口可見性智能派發通知。
- 頁面內 Toast：窗口前臺且可見時。
- PWA 系統通知：窗口後臺且 PWA 通道可用時。
- 瀏覽器通知：窗口後臺且未註冊 Service Worker 時的兜底方案。
- 合成音效：使用 Web Audio API（振盪器 + 包絡整形）實時合成音色，無需加載任何音頻文件。音效分爲成功、錯誤、警告、信息四個級別。
- 事件級與通道級開關：支持分別控制任務完成、子代理完成、審批請求等具體事件的開關，也支持獨立啓停三種通知渠道。
- 持久化與安全：配置持久化存儲，支持 HMR（熱重載）後狀態不丟失，並遵循瀏覽器的自動播放策略合規要求。
安裝與啓用¶
通過 DSH CLI 安裝該插件：
dsh plugin --profile web add dsh-hybrid-notify
或者從 GitHub 源碼安裝：
dsh plugin --profile web add github:john-walks-slow/dsh-hybrid-notify
安裝後，插件會自動集成到 DSH Web UI 中。
配置¶
在 DSH Web UI 中打開 設置 → 通知 進行配置。所有設置通過 localStorage 持久化存儲，鍵名爲 dsh.notify.config。
事件開關¶
插件支持對以下事件進行獨立控制：
| 事件類型 | 默認狀態 | 說明 |
|---|---|---|
| 任務完成 | 開 | 會話一輪 turn 結束（running → idle） |
| 子代理完成 | 關 | subagent 會話完成 |
| 審批請求 | 開 | Agent 請求批准操作 |
| 用戶提問 | 開 | Agent 向你提問 |
| 計劃評審請求 | 開 | Plan 模式等待評審 |
| Agent 出錯 | 開 | Agent 遇到錯誤 |
| 後臺任務完成 | 關 | 後臺 bash 任務結束 |
注意：當前正在前臺查看的會話不會觸發通知。
音效設置¶
音效功能包含總開關、音量滑塊、前臺播放開關以及試聽按鈕。
注意事項¶
- 通知權限：PWA 與瀏覽器通知通道需要瀏覽器通知權限。首個後臺事件到達時會自動請求權限（僅當狀態爲 default 時）；設置頁每個通道也有手動授權按鈕。頁面內 Toast 通道無需任何權限。
- PWA / Service Worker：PWA 通道的 Service Worker 由插件宿主端在
/plugins/dsh-hybrid-notify/sw.js提供，不支持環境自動降級。 - 音效策略：受瀏覽器自動播放策略約束，AudioContext 在用戶第一次點擊或按鍵交互後解鎖。首次交互前不會有聲音。
- 零網絡訪問：插件不發起任何外部請求，不做任何上報，所有通知內容來自本地 DSH 會話快照。
- 兼容性：需要支持 Notification API 與 Web Audio API 的現代瀏覽器。部分移動瀏覽器不支持
new Notification()，會靜默降級爲頁面內 Toast。 - 構建要求：從源碼構建需 Node.js ≥ 18。
總結¶
dsh-hybrid-notify 爲 DSH 提供了一套完整的後臺消息觸達方案，通過智能渠道切換和合成音效，減少了用戶頻繁查看標籤頁的需求，適合需要在長時間會話中保持信息敏感度的開發者與用戶。
