前言¶
用 DSH Web GUI 跑長任務時，人通常不會一直盯着頁面：切去別的標籤頁寫代碼、看文檔，讓任務在後臺推進。問題出在會話需要人介入的時刻——待審批、計劃審批、模型提問到達時，頁面本身是靜默的，任務就停在原地，直到有人切回去才發現。
dsh-web-notify 解決的就是這個注意力斷層。它是掛在 web profile 上的客戶端插件：待處理交互到達時，通過提示音、標籤頁標題與 Favicon 徽標、OS 通知、PWA 任務欄徽標、通知中心 Dock 多通道提醒；會話完成、任務失敗、掉線重連、模型/工具運行異常（429 配額等）也有對應提醒。DeepSeek Harness 的理念是「一切皆插件」，dsh-web-notify 就是這種形態下的一個典型實現。下面按功能、安裝、配置、調試的順序介紹。
這是什麼¶
先交代基本信息。dsh-web-notify 由 renpengfei1027 維護，MIT 許可證，當前版本 0.1.5。純插件形態：host 半（lib/index.js）+ client 半（lib/client.js，loader 格式），通過 profile patch 掛載進 dsh web。依賴方面，運行時依賴 @deepseek-ai/schemastery ^3.18.1，peer 依賴 @deepseek-ai/cordis、@deepseek-ai/dsh-api-remotes、@deepseek-ai/dsh-settings 與 react。
待審批 / 計劃審批 / 提問到達¶
這是插件的主場景。任意會話出現 pendingInteraction 即觸發，共六個通道：
1、提示音：WebAudio 合成的 E5-G5-B5 三連音；
2、標籤頁標題徽標：用 MutationObserver 對抗 shell 的標題寫入，保證徽標不被沖掉；
3、標籤頁 Favicon：32×32 徽章；
4、OS 通知：按會話 tag 去重，點擊跳轉對應會話並聚焦窗口，approval 類型用 requireInteraction 持久顯示；
5、PWA 任務欄徽標：通過 navigator.setAppBadge 在任務欄/應用圖標上顯示數字；
6、通知中心 Dock：右下角 FAB 即時計數，展開面板列出全部待處理項。
兩個設計細節值得單獨說明。
一是當前會話降級：頁面可見且新審批屬於當前打開的會話時，提示音與 OS 通知靜默，只保留視覺通道——眼睛就在這個會話上，聲音反而多餘；其餘情況全通道照常。
二是去重：同一 (會話, kind) 在冷卻期內不重複報警，冷卻時長由 cooldownMs 控制，默認 5s。
完成、失敗與運行異常提醒¶
除審批外，插件還覆蓋四類事件：
1、會話/子代理完成：完成 toast 卡片 + 輕單音 + 可選 OS 通知；頁面隱藏時看不到 toast，改用標籤頁標題脈衝 + PWA 角標 + 提示音 + OS 通知。
2、任務失敗：job 狀態爲 failed / killed，或 completed 但 detail 非空且非 exit code: 0 時，彈 error 變體 toast + 提示音 + 可選 OS 通知；按 job 註冊號只報一次。
3、模型/工具運行異常：捕獲 llm/retry（429 配額/限流）、turn/end 的 error / max-tokens / interrupted、tool/result 的 error / isError，彈 error 變體 toast（錯誤原文截 240 字符）+ 提示音 + 可選 OS 通知。
4、掉線/重連：斷線持續超過 connectionAlertAfterMs（默認 10s）時報 warning toast + 提示音，恢復時報輕 toast + 完成單音；快速閃斷不報。
子代理的覆蓋與邊界¶
檢測管道覆蓋全部會話行，含子代理。邊界需要說清楚：按當前 DSH 的委派語義，被委派的子代理不會產生待審批/提問，因此不會有子代理的待處理條目出現；但子代理的完成、失敗、異常提醒照常生效，不會漏。
安裝與啓用¶
前提條件¶
- Node.js >= 22；
- pnpm：
dsh plugin內部用 pnpm 裝依賴，先執行npm install -g pnpm； - dsh CLI：未全局安裝時，所有
dsh命令加前綴npx @deepseek-ai/dsh，例如npx @deepseek-ai/dsh plugin --profile web add dsh-web-notify。
兩種安裝方式¶
npm 一鍵掛載：
dsh plugin --profile web add dsh-web-notify
DeepSeek Harness 當前處於開發預覽快速迭代期，README 推薦以 link: 開發調試模式掛載本地倉庫：
git clone https://github.com/renpengfei1027/dsh-web-notify.git
cd dsh-web-notify
npm install
npm run build
dsh plugin --profile web add link:$(pwd)
# Windows PowerShell: dsh plugin --profile web add link:$PWD.Path
安裝完成後重啓 dsh web，設置頁「插件配置」下會出現「通知」卡片。
放行設置命名空間¶
DSH 官方把 settings 白名單（WEB_SETTINGS_NAMESPACES）硬編碼在包裏，暫不開放插件注入，所以需要運行倉庫自帶的 patch 腳本，把 notifications 注入白名單：
node scripts/patch-apiproxy.mjs
腳本冪等，重跑安全；dsh 升級後需重跑一次。
沙箱環境注意事項¶
1、TRAE、Cursor 等 AI 編碼工具的沙箱通常阻止寫入 ~/.dsh/，而 dsh plugin 和 dsh web 都要寫 profile 文件，這兩類命令必須在 AI 工具外部的普通終端執行；
2、切勿手動 npm install 到 ~/.dsh/profiles/web/node_modules/：這會繞過 dsh plugin 的依賴鏈接邏輯，導致 settings 服務不可達、命名空間註冊靜默失敗。安裝一律走 dsh plugin --profile web add。
配置與常用調法¶
經過上面的步驟，插件已經掛進 web profile 並隨 dsh web 重啓生效。設置卡片位於 DSH Web 設置頁「插件配置」→「通知」，120ms debounce 熱重配，改完即生效，不需要重啓。OS 通知權限在首次觸發後的下一個用戶手勢時請求 Notification 權限。
幾個常用的調法：
- 只要審批提醒，其餘關掉：
completion=false、connection=false、jobFailure=false、agentError=false； - 夜間免打擾：
quiet.enabled=true、quiet.start=22:00、quiet.end=09:00，免打擾只靜音，視覺通道照常； - 嫌系統通知彈窗吵：
notify=false，保留badge=true、dock=true。
調試與診斷¶
插件提供 on-device diagnostics。在 DSH Web 頁面打開 DevTools 控制檯，觀察 window.__NOTIFICATIONS__：
__NOTIFICATIONS__.applied
__NOTIFICATIONS__.cardRegistered
__NOTIFICATIONS__.feedCounters
__NOTIFICATIONS__.hostStatuses
__NOTIFICATIONS__.jobSamples
其中 applied、cardRegistered 反映插件與設置卡片的掛載狀態，feedCounters 是各類事件的計數。不想真等一次審批來驗證效果，可以調 demo() / demoSound() 一鍵測試 UI 與音頻。
適用場景與注意事項¶
適合的人：把 DSH 會話掛後臺跑、需要及時響應審批與提問的人；多會話並行、希望在一個面板裏統一看待辦的人；裝了 PWA、想在任務欄直接看到待辦數的人。
注意事項：
1、插件以當前 dsh 進程的權限運行，安裝前建議先讀一遍源碼與許可證（MIT）再決定；
2、DSH 處於開發預覽快速迭代期，dsh 升級後記得重跑 node scripts/patch-apiproxy.mjs；
3、安裝與重啓命令在普通終端執行，不要在 AI 工具沙箱裏跑。
結尾¶
回顧一下：dsh-web-notify 把 DSH Web GUI 的「等人回來看」變成「主動來叫人」——審批、提問、完成、失敗、掉線、429 都在該出現的位置提醒，通道、音量、免打擾都能按需開關，配置熱重配、診斷內置，裝起來成本不高。
- 社區插件目錄頁：https://www.skillhub.cn/plugins/renpengfei1027/dsh-web-notify
- GitHub 倉庫：https://github.com/renpengfei1027/dsh-web-notify
