DSH 桌面通知

前言¶

DeepSeek Harness (DSH) 是一個基於插件化的智能體開發框架。DSH 的運行通常依賴 dsh web 服務，這意味着智能體的任務狀態、審批請求或定時觸發事件主要展示在瀏覽器頁面中。

當智能體在後臺執行任務，或需要你進行審批時，如果視線離開頁面，這些關鍵信息容易被遺漏。dsh-desktop-notify 插件的作用是將 DSH 內部的關鍵事件直接橋接到操作系統的桌面通知中，確保你不會錯過任何重要的狀態變化。

功能說明¶

該插件隨 dsh web 啓動自動加載，支持 Windows 和 Linux 系統。核心能力包括：

任務狀態監控：當 Agent 從運行狀態變爲空閒時，通知任務完成。
等待交互提醒：當智能體調用 ask_user_question 等工具發起提問時，提醒返回頁面輸入。
審批與拒絕通知：當審批策略爲 never 導致操作被靜默拒絕時，發出明確通知。
後臺任務追蹤：後臺子代理、目標或命令任務結束時逐一提醒。
定時任務觸發：僅在定時任務真正被投遞（觸發）時通知，而非僅創建時。
啓動與掛載播報：每次 dsh web 啓動後，推送插件掛載狀態（正常/降級）。
點擊跳轉支持：支持點擊通知跳轉回對應的會話、內置頁面或外部 URL。
雙渠道通知：優先使用 Web Notification（點擊精確激活標籤頁），在無權限或不可用時自動降級爲原生 Toast（Windows 使用 koffi，Linux 使用 D-Bus）。
權限變更即時反饋：當瀏覽器通知權限被更改時，立即通知當前運行模式。

安裝與啓用¶

前置條件¶

DSH 版本：必須滿足 >= 0.1.7-rc.2 且 <= 0.2.0-rc.2。
Web 啓動：必須已經啓動過一次 dsh web（需已生成 web profile）。
運行環境：Windows 需要安裝 koffi（插件會自動處理），Linux 無額外依賴。

安裝步驟¶

在 DSH 的插件管理頁面選擇添加插件，安裝目標填入以下任一內容：

包名：@mvyvn/dsh-desktop-notify
倉庫地址：https://github.com/Mvyvn/dsh-desktop-notify

安裝完成後，完全重啓 dsh web 進程並刷新 DSH 頁面。

首次授權¶

如果需要使用 Web Notification 渠道，瀏覽器要求用戶手勢才能觸發授權彈窗。插件會在 DSH 頁面顯示一個居中卡片，點擊“設置”按鈕即可授權。授權後通知由瀏覽器直接顯示；如果拒絕或未授權，插件會自動降級爲原生 Toast 模式。

使用方法¶

插件註冊爲 Cordis 服務 desktopNotify。其他插件可以通過 ctx.get('desktopNotify') 調用。

基礎推送¶

使用 push 方法推送通知，默認遵循“聚焦門控”規則（即當你正在查看該會話時不會打擾你）。

// 在你的插件代碼中
const desktopNotify = ctx.get('desktopNotify');
if (!desktopNotify) return;

// 普通推送，受聚焦門控影響
desktopNotify.push({
  title: '構建完成',
  message: '工作區/會話:全部通過',
  urgency: 'normal', // 'low' | 'normal' | 'critical'
  sessionId: agent.session
});

強制推送¶

使用 pushAlways 繞過所有門控，強制彈窗。

desktopNotify.pushAlways({
  title: '磁盤告急',
  message: '剩餘 1GB',
  urgency: 'critical'
});

結果查詢¶

使用 notify 方法獲取詳細的推送結果（是否入隊、是否被靜默等）。

const result = desktopNotify.notify({
  title: '構建完成',
  sessionId: agent.session
});
// 返回: { ok: true, queued: false, silenced: true, reason: 'silenced', ... }

點擊跳轉配置¶

通過 click 字段配置點擊後的行爲。不傳 click 則通知不可點擊。

// 跳轉回指定會話
desktopNotify.push({
  title: '打開文檔',
  click: {
    type: 'session',
    sessionId: agent.session
  }
});

// 跳轉外部 URL
desktopNotify.push({
  title: '查看詳情',
  click: {
    type: 'url',
    url: 'https://example.com'
  }
});

靜默模式配置¶

在插件設置頁，可以爲不同類型的通知配置靜默模式（session / tab / never），決定在何種情況下不發送通知。

注意事項¶

版本兼容性：插件依賴 DSH 的 connection、webServer 等服務，嚴格限定版本範圍。版本範圍外的行爲未做兼容性保證。
許可證：插件採用 GPL-3.0-or-later 許可證。安裝前請確認源碼合規性。
權限限制：瀏覽器通知權限需要在頁面內通過用戶操作觸發授權，無法自動彈窗。
圖標：原生 Toast 使用 DSH Logo（透明底 PNG/ICO），隨系統主題自動切換深淺色。

總結¶

dsh-desktop-notify 爲 DSH 提供了系統級的監控能力，將複雜的智能體後臺狀態轉化爲直觀的桌面提醒。通過其提供的 desktopNotify 服務接口，開發者可以輕鬆集成通知功能，增強用戶體驗。

目錄頁：DSH 插件目錄
源碼倉庫：GitHub - mvyvn/dsh-desktop-notify