dsh-session-notifier：爲 DSH Web 會話添加桌面通知

前言¶

在使用 DeepSeek Harness（DSH）進行智能體開發時，Web 會話通常在後臺運行，執行結果、錯誤、審批請求或問題往往需要開發者主動去檢查。這就容易漏掉重要事件，尤其是在多會話並行或長時間運行的場景下。dsh-session-notifier 專門解決這一問題，通過瀏覽器通知和 Windows Toast 兩種方式，在關鍵事件發生時主動提醒開發者。

這是什麼¶

dsh-session-notifier 是一個 DSH 插件，給 DSH Web 會話提供桌面通知能力：會話完成、執行失敗、需要審批、需要回答時彈出通知。插件由 CoCoCoDeDeDe 維護，通過 SSE 通道向客戶端推送事件，支持 Chrome/Edge 瀏覽器的原生通知，以及 Windows/WSL 下的 Windows Toast。

核心功能¶

兩種通知渠道¶

• 瀏覽器通知：頁面打開時由瀏覽器客戶端彈出；點擊通知後，如果已有標籤頁打開該會話則聚焦該標籤頁（不刷新），沒有則新開一個標籤頁並定位到對應會話。
• Windows Toast：在 WSL/Windows 下由 Host 調用 PowerShell 彈出；頁面關閉也能收到；點擊會新開一個瀏覽器標籤頁並定位到會話（平臺限制：無法聚焦已打開的標籤頁）。

觸發事件¶

插件監聽以下事件並生成通知：

通知標題使用會話標題（sessionTitle），無標題時回退到工作目錄名或會話 ID 前 8 位。子代理會話默認不通知。

關注會話與抑制規則¶

插件通過 SSE 接收事件，並上報當前正在瀏覽的會話。Host 的 windowsToast.enabled 決定是否同時彈 Windows Toast：

• auto（默認）：有頁面已授予通知權限時只發瀏覽器通知，避免重複；沒有可用頁面時回退到 Windows Toast。關閉瀏覽器通道時視同 always，只彈 Toast。
• always：每條未被關注會話抑制的通知同時彈 Windows Toast。
• never：從不彈 Toast。

被關注會話：同時只看一個頁面、一個會話。聚焦且可見的頁面上報的當前會話即被關注會話。

• 被關注會話的完成通知會被抑制（頁面本身已經能看到結果）。
• 其他會話的完成都會通知。
• 失敗、審批、提問即使發生在被關注會話也會通知。
• 頁面失焦、最小化或關閉時，所有完成都會通知；沒有頁面連接時由 Windows Toast 接管。

安裝與啓用¶

使用官方安裝命令：

dsh plugin --profile web add dsh-session-notifier

安裝後需要執行以下步驟：

1. 重啓 dsh web（profile 的 bundle 列表只在啓動時讀取）；
2. 瀏覽器硬刷新（Ctrl+Shift+R）；
3. 首次點擊 DSH 頁面任意位置，允許瀏覽器通知權限。

也可以在 設置 → 通用 → 桌面通知 中查看權限狀態、啓用通知或發送測試通知。

從源碼安裝（本地開發）：

cd /path/to/dsh-session-notifier
dsh plugin --profile web add "link:$PWD"

配置¶

默認配置在包內的 cordis.patch.yml。要覆蓋，在本 profile 的用戶 patch 層（~/.dsh/profiles/web/cordis.patch.yml）加一條同 id 的配置；匹配的覆蓋會替換整個 config：

- id: dsh-notifier
  name: dsh-session-notifier
  config:
    events:
      completed: true
      error: true
      approval: true
      question: true
    windowsToast:
      enabled: auto          # auto | always | never（也接受 true/false）
      sound: true
      appId: DSH.Web
      launchUrl: http://127.0.0.1:3080/
    browser:
      enabled: true
    allowedHosts: []
    debounceMs: 4000
    includeSubagents: false   # true 時子代理/子會話也通知

改完後由 HMR 重載配置；如果沒生效，刷新頁面或重啓 DSH。

驗證與測試¶

插件提供以下端點用於驗證和調試：

# 通道狀態（客戶端數、瀏覽器通道是否可用、Toast 模式、被關注會話）
curl -s http://127.0.0.1:3080/dsh-notifier/state

# 發送一條測試通知：瀏覽器通知 + Windows Toast
curl -s -X POST http://127.0.0.1:3080/dsh-notifier/test -H 'content-type: application/json' -d '{}'

# 模擬某個會話的事件（用於驗證關注會話抑制）
curl -s -X POST http://127.0.0.1:3080/dsh-notifier/test \
  -H 'content-type: application/json' \
  -d '{"kind":"completed","sessionId":"session-other"}'

# 觀察 SSE 廣播
curl -sN 'http://127.0.0.1:3080/dsh-notifier/events?client=probe'

kind 可爲 completed / error / approval / question / test。

點擊通知的行爲¶

新標籤頁定位完成後會把 dsh-session 參數從地址欄移除，之後刷新不會重複跳轉。Toast 的打開地址可以用配置裏的 windowsToast.launchUrl 覆蓋。

適用場景與注意¶

適用場景¶

• 需要同時運行多個 DSH 會話，不希望錯過關鍵事件；
• 在後臺長時間運行智能體任務，需要實時反饋；
• 在遠程開發環境（如 SSH/WSL）中使用 DSH，無法頻繁檢查頁面；
• 使用反向代理部署 DSH，需要通過域名訪問。

注意事項¶

• 環境要求：DSH 版本需滿足 >=0.2.1-rc.2 <0.3.0-0，Node.js 版本需 >=20；
• 瀏覽器要求：支持 Chrome/Edge，通知授權依賴用戶手勢；
• Windows Toast 限制：僅 Windows 或 WSL 可用，需要 PATH 中有 powershell.exe；
• 權限與安全：通知路由只接受本機地址、dsh web 綁定地址以及 allowedHosts 裏顯式列出的主機；經 --public-url 反向代理訪問時，要把代理域名加入 allowedHosts；路由沒有額外鑑權，不要把端點暴露到不受信任的網絡；
• 子代理會話：默認被過濾，主會話完成時會統一通知；如需爲子代理也啓用通知，將 includeSubagents 設爲 true；
• 需要瀏覽器進程在運行才能收到瀏覽器通知；頁面全部關掉後由 Windows Toast 接管。

結語¶

dsh-session-notifier 通過瀏覽器通知和 Windows Toast 兩種方式，讓 DSH Web 會話的關鍵事件不再被遺漏。開發者可以根據實際場景選擇合適的通知渠道和配置策略，在多會話並行、後臺運行或遠程開發時保持對任務狀態的掌控。插件代碼開源，遵循 MIT 許可證，適合在本地開發或生產環境中使用。

• 插件目錄：https://www.skillhub.cn/plugins/CoCoCoCoDeDeDe/dsh-session-notifier
• GitHub：https://github.com/CoCoCoDeDeDe/dsh-session-notifier