前言¶
在使用 DeepSeek Harness (DSH) 處理任務時，任務可能會進入“需要批准”、“需要回答”或“出錯”的狀態。如果這些狀態變化沒有被及時捕捉，可能導致任務卡住或被忽略。dsh-task-notifier 插件通過應用內橫幅、合成提示音與系統通知，確保你能實時感知這些狀態變更。
該插件由 xubin0628 維護，採用 MIT 許可證，主要解決“狀態變更漏看”的問題。
核心功能¶
插件訂閱 DSH 的四個核心事件，並分發三種通知形式：
-
事件覆蓋：
agent/status：任務完成（非等待用戶輸入狀態）。approval/request：需要批准（如沙箱/權限調用）。user-questions/request：需要回答問題。agent/error：執行出錯。- 注：等待批准/回答期間的狀態變化不會再次觸發“任務完成”通知，避免重複提示。
-
通知形式：
- 應用內橫幅：使用 Shadow DOM 實現，樣式隔離，可配置停留時長。
- 提示音：使用 WebAudio 合成，無需加載外部音頻文件，支持清脆/鈴鐺/水滴等音色與音量調節。
- 系統通知：調用頁面側的 Notification API。
-
配置靈活性：
- 在設置頁提供「通知」頁面，可獨立開關四種事件、是否包含子代理、橫幅顯示時長。
- 提供試聽功能，實時生效。
安裝與啓用¶
插件以 Bundle 形式安裝。由於官方桌面端使用獨佔的 desktop profile，無法直接通過 CLI 插件管理，需在 DSH 會話內部調用內置 plugin_manager。
# 軟鏈安裝（推薦開發期使用，修改源碼即時生效）
install_bundle target = link:<插件目錄絕對路徑>
# 拷貝安裝（推薦生產環境，源碼丟失不影響運行）
install_bundle target = file:<插件目錄絕對路徑>
安裝後，新版本通常熱生效。若涉及 package.json 修改或宿主進程模塊變更，需重啓客戶端。
配置與設置¶
插件的配置分爲兩處：
-
宿主側默認值 (
cordis.patch.yml的config段)：- 控制通知開關（完成、批准、回答、錯誤）、是否包含子代理、防抖時間、音量等。
- 此處修改需重啓客戶端生效。
-
用戶側偏好（設置頁「通知」）：
- 存儲在瀏覽器的
localStorage中（鍵爲dsh-task-notifier:settings:v1）。 - 一旦用戶在設置頁修改過任何項，後續以用戶側設置爲準，不再回退到默認值。
- 存儲在瀏覽器的
自檢與排查¶
插件提供 RESTful 接口用於檢查狀態和測試鏈路。
檢查插件狀態與等待中的會話：
Invoke-RestMethod http://127.0.0.1:19387/dsh-notifier/status
查看最近的通知記錄：
Invoke-RestMethod 'http://127.0.0.1:19387/dsh-notifier/recent?limit=20'
測試通知鏈路：
Invoke-RestMethod 'http://127.0.0.1:19387/dsh-notifier/test?kind=approval'
# kind 可取: done | approval | question | error
開發與已知限制¶
在修改代碼後，生效邏輯取決於文件類型：
| 修改文件 | 生效方式 | 原因 |
|---|---|---|
assets/notifier-client.js |
刷新頁面 | 宿主按 mtime 重新讀取 |
lib/client.js |
刷新頁面 | 頁面重載即更新 |
lib/index.js |
重啓客戶端 | Node ESM 模塊緩存 |
package.json / cordis.patch.yml |
重啓客戶端 | 需要重新 apply patch |
桌面端已知限制：
* 通知限制：桌面端運行在獨立子進程，無法直接訪問 Electron 的 Notification API（會導致 WinRT 錯誤 0x80073D54），必須依賴頁面側的 Notification API。
* 注入限制：桌面端的 index 注入表在宿主啓動時收集一次，修改注入邏輯後必須重啓客戶端。
* 設置隔離：設置存儲在 localStorage，不寫入 profile 配置，換瀏覽器或清緩存會重置爲默認值。
結尾¶
dsh-task-notifier 是一個輕量級的通知增強工具，通過 SSE 事件流與 WebAudio 合成技術，爲 DSH 提供了可視與聽覺的雙重反饋。對於需要長時間運行代理或頻繁進行人機交互的場景，它能有效降低狀態遺漏的風險。
更多細節與源碼，請訪問 SkillHub 目錄 或 GitHub 倉庫。
