前言¶
DeepSeek Harness (DSH) 採用插件化架構，允許開發者擴展功能。在運行長會話或後臺任務時，可能會錯過關鍵節點。dsh-notify 是一個插件 bundle，用於在會話完成任務、提問或需要審批，且你不在當前會話時，發送桌面通知並播放提示音。
功能¶
該插件主要提供以下能力：
- 觸發時機：支持在以下事件觸發通知
- 會話一輪對話結束（
turn/end） - 持久化目標完成（
goal/change） - Agent 調用提問接口（
tool/call） - 需要用戶審批的動作（
approval/asked）
- 會話一輪對話結束（
- 子代理過濾：只監聽頂層會話。插件通過會話頭部的
origin: 'subagent'標記過濾掉所有子代理（subagent）的事件，避免干擾中間過程。 - 在場檢測：僅在用戶離開時通知。
- 當頁面爲當前標籤頁且窗口有焦點時，視爲“在會話中”，不彈通知。
- 切換標籤頁、最小化或關閉頁面時，視爲“離開”，觸發通知。
- 標籤頁崩潰或斷連超過 45 秒（TTL），會自動視爲離開。
- 系統默認提示音：嘗試調用
canberra-gtk-play -i message或pw-play/paplay播放系統提示音，支持通過配置關閉。 - 通知後端：支持 Linux
notify-send（自動檢測）、純控制台輸出，或任意自定義命令（支持模板替換）。
安裝¶
本包是一個 DSH 規範的 bundle，包含宿主插件和瀏覽器客戶端半部。
從本地目錄安裝¶
# 1. 構建（如果尚未構建）
npm install
npm run build
# 2. 安裝到指定 profile
dsh plugin --profile web add /path/to/DSH_remind
dsh plugin 會自動檢測 dsh.bundle.patch 並追加到 profile 的 bundle 列表中，重啓 profile 即可生效。
從 GitHub 安裝¶
dsh plugin --profile web add github:you/dsh-notify#<commit-sha>
驗證配置層¶
在不啓動的情況下檢查配置是否正確加載：
dsh --profile web --patch /path/to/DSH_remind/cordis.patch.yml --dump-config
配置¶
默認零配置即可運行。在 profile 的 cordis.patch.yml 中按 id 覆蓋該行。
默認配置參數¶
| 字段 | 類型 | 默認值 | 說明 |
|---|---|---|---|
backend |
auto \| notify-send \| console \| command |
auto |
自動檢測 notify-send，否則降級爲控制台 |
command |
string | '' |
自定義命令模板，經 /bin/sh -c 執行，支持 {title} 和 {message} 佔位符 |
urgency |
low \| normal \| critical |
normal |
notify-send 的緊急度 |
onTurnComplete |
boolean | true |
一輪迴答完成時通知 |
onGoalComplete |
boolean | true |
goal 完成時通知 |
onUserQuestion |
boolean | true |
Agent 提問時通知 |
onApproval |
boolean | true |
需要審批時通知 |
onlyWhenAway |
boolean | true |
僅在離開時通知 |
playSound |
boolean | true |
播放系統提示音 |
debounceMs |
number | 0 |
同類通知的最小間隔（毫秒） |
自定義命令示例¶
在 command 後端中自定義通知行爲：
# 通知 + 自定義提示音文件
config:
backend: command
command: 'notify-send --app-name "DeepSeek Harness" --urgency critical "{title}" "{message}" && paplay "$HOME/.local/share/sounds/custom.oga"'
# 通知 + 留痕到日誌文件
config:
backend: command
command: 'notify-send "{title}" "{message}"; echo "$(date "+%F %T") {title} | {message}" >> "$HOME/.local/share/dsh-notify.log"'
工作原理¶
插件分爲瀏覽器端（客戶端半部）和宿主端（bundle 行）：
- 瀏覽器端：監聽頁面可見性變化（
visibilitychange）、焦點/失焦（focus/blur）以及心跳（15s）。將當前會話 ID 和在場狀態通過 RPC 上報給宿主。 - 宿主端：訂閱
session/event流。在處理事件前，先檢查會話是否爲頂層會話（排除subagent），再檢查presence服務中記錄的用戶是否“在場”。 - 執行：通過防抖處理，最終觸發通知和聲音播放。通知失敗不會影響會話本身的運行。
在 Headless 或 TUI 環境中，由於沒有瀏覽器端上報，presence 恆爲“離開”，所有事件均會觸發通知。
注意事項¶
- 純事件觀察者：插件不會攔截或修改任何會話行爲，通知故障不會影響 DSH 的運行。
- 權限與安全：安裝前請檢查源碼與許可證。插件以當前 DSH 進程的權限運行，自定義命令需注意安全風險。
- Headless 場景：無瀏覽器環境的場景下，所有事件均會觸發通知。
