前言¶
用 DeepSeek Harness（DSH）跑長回合時，客戶端一最小化，或被瀏覽器、ComfyUI 等窗口蓋住，界面裏的審批卡片和「回合已結束」往往看不見。官方桌面客戶端在通知能力上並不完整，社區裏也有若干只做「完成提醒」或「前臺不打擾」的同類插件。下面介紹 LeeRolling 維護的 dsh-plugin-desktop-notify：在 desktop profile 下訂閱客戶端事件，在需要授權、需要回答或回合結束時彈出系統 Toast，正文帶任務摘要；窗口在前臺時一律不彈，避免重複打擾。
這是什麼¶
dsh-plugin-desktop-notify 是 DSH 的桌面通知插件，倉庫 LeeRolling/dsh-plugin-desktop-notify，許可證 MIT，當前 package 版本 0.1.0。它通過 dsh.bundle.patch 與 dsh.client（platform 爲 web）注入宿主半與瀏覽器半，在 dsh-app://app/ 安全上下文中調用 new Notification()，在已驗證環境 DSH Desktop 0.2.0-rc.2（Electron 44）、Windows 11、desktop profile 下，通知顯示名爲 DeepSeek Harness，使用 Windows 通知中心 Toast 與系統默認提示音。
插件以「一切皆插件」的方式擴展 DSH，與 SkillHub 插件目錄 上的條目對應；該目錄爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
核心功能¶
會彈通知的情況¶
瀏覽器半監聽三類客戶端事件（只觀察、不消費，原樣 return next()）：
| 事件 | 用途 |
|---|---|
approval/request |
審批瀑布 |
user-questions/request |
模型提問 |
api-session/status |
會話 running 狀態，檢測 true → false 邊沿表示回合結束 |
按場景分類後，通知標題與正文如下（資料中的表格）：
| 情況 | 通知標題 | 正文 |
|---|---|---|
需要授權執行命令（pwsh / bash 等） |
有任務需要授權 |
工具名 + 操作用途（審批理由；會剝掉 escalate sandbox to <mode>: 前綴） |
需要授權改文件（write / edit 等） |
有文件需要修改 |
工具名 + 操作用途 |
| 其它工具需要確認 | 有任務需要你確認 |
工具名 + 審批理由 |
| 模型提問等你回答 | 有問題需要你回答 |
問題原文 |
| 回合結束 | 任務已完成 |
會話名 + 提示回客戶端看結果 |
什麼時候不打擾¶
- 客戶端在前臺（窗口有焦點、頁面可見）：不彈，只在 UI 裏顯示；
- 子代理（subagent）會話回合結束：不彈，僅主會話完成才提醒；
- 冷啓動時本就 idle 的會話：不彈，只有觀測到
running: true → false才提醒； - 同一事件 1.5 秒內重複：去重，只彈一次。
用法上：先在客戶端發消息，再立刻切走。回合從按下發送開始；若先切走再回來打字，窗口回到前臺，按設計不會彈通知。
診斷與自檢（長期保留）¶
瀏覽器側行爲外部不可見，插件提供常駐診斷通道，便於排查「裝着但不響」：
| 端點 | 方向 | 作用 |
|---|---|---|
POST /api/desktop-notify/report |
瀏覽器 → 宿主 | 上報決策：事件是否到達、被哪道閘攔下、new Notification() 是否異常、環境快照 |
GET /api/desktop-notify/selftest |
瀏覽器 → 宿主 | 返回自檢開關狀態、trace 與開關路徑 |
默認 trace 寫在 <DSH_HOME|~/.dsh>/desktop-notify/trace.jsonl；環境變量 DSH_DESKTOP_NOTIFY_TRACE 可改路徑，設爲 off / 0 / false / none / no 則關閉寫入（端點與自檢仍可用）。trace 超過 512 KB 會按行邊界輪轉，保留最近約 256 KB。
在同目錄放置 selftest.flag，下次頁面加載約 2 秒後會無視前後臺強制彈出標題「通知自檢」的 Toast，用於區分「代碼未跑」與「系統不顯示」；自檢後應刪除該文件。
讀 trace 摘要：
node tools/trace.mjs # 統計 + 最近 15 條
node tools/trace.mjs --all # 全量
安裝與啓用¶
在 desktop profile 下安裝（命令來自倉庫 README）：
dsh plugin --profile desktop add link:<本目錄>
# 或從倉庫裝：
dsh plugin --profile desktop add github:LeeRolling/dsh-plugin-desktop-notify
安裝後重啓 DSH 客戶端生效。若用 link: 本地鏈入，改 lib/client.js 後重啓即可，無需重裝。
卸載：
dsh plugin --profile desktop remove dsh-plugin-desktop-notify
典型用法與驗收思路¶
- 安裝並重啓客戶端後，發一條會觸發長回合的消息，立即切換到其他窗口。
- 等待需要授權、模型提問或回合結束，應在 Windows 通知中心看到對應標題與摘要。
- 若始終無通知：在 trace 目錄放
selftest.flag做強制彈窗；或運行node tools/trace.mjs查看suppressed（如window-in-front）、threw、apply-failed等 kind。
倉庫提供不依賴啓動 DSH 的冒煙測試：
npm test
（假 DOM + 假 Notification，覆蓋三事件、分類、前臺抑制、去重、子代理靜默、冷啓動邊沿等。）
適用場景與注意¶
適合誰：主要在 Windows 上使用 DSH Desktop、且經常把客戶端最小化或蓋在其它窗口後面的開發者；需要「授權 / 改文件 / 提問 / 完成」四類情境下帶摘要的系統提醒，而不是隻有單一「任務完成」鈴。
權限與安全：插件隨當前 DSH 桌面進程運行，安裝前請閱讀源碼與 MIT 許可證，確認事件訂閱與 HTTP 診斷端點符合你的環境策略。
已知限制（README 原文）：
- 點擊通知切回客戶端依賴
window.focus()，Electron 不保證窗口置頂；preload 未暴露 focus/flash，要完全保證需改主進程，易被客戶端更新覆蓋。 - 客戶端進程完全退出後無法收到通知。
同類思路在社區已有多個插件（如回合結束 + 前臺抑制、審批 + 提問等）；本插件側重按情境分類摘要、常駐 trace/自檢與可離線跑的瀏覽器半測試。文件類授權（write / edit）在 README 驗收表中標記爲待真實事件觸發，邏輯與命令類共用同一段分類代碼。
結尾¶
dsh-plugin-desktop-notify 爲 DSH 官方桌面客戶端補上上下文感知的系統通知：後臺時才提醒，正文說明「要授權什麼、要問什麼、哪條會話跑完了」，並自帶 trace 與自檢便於排錯。安裝使用 desktop profile 與 README 中的 dsh plugin 命令即可。
