macOS 通知插件：dsh-plugin-mac-notify

前言¶

DSH 的會話經常在後臺長時間運行。當任務完成、需要人工輸入或發生錯誤時，直接在終端裏翻日誌不夠直觀，容易錯過關鍵信息。這個插件通過 macOS 通知中心提醒你，點擊通知即可回到 DSH 頁面，適合在無人值守或遠程服務器上運行 DSH。

這是什麼¶

這是一個非官方的 DSH 客戶端插件，由 AK-blank 維護。它是一個 Host 側的 bundle，專注於監聽 Host 事件並通過 terminal-notifier 或系統自帶的 osascript 將警報推送到 macOS 通知中心。它不包含瀏覽器端的渲染代碼。

核心功能¶

插件監聽以下 4 種 Host 事件併發送通知：

任務完成：當 agent/status 狀態從 running 變爲 idle 時。
需要回答：當代理調用 ask_user_question 被阻塞時。
需要批准：當代理等待審批決策時。
執行出錯：當某一步驟或回合發生錯誤時。

默認情況下，子代理靜默，且非緊急通知在 5 秒內會合並顯示，避免通知刷屏。

安裝與啓用¶

使用官方 CLI 安裝，安裝後必須重啓 dsh web 或 dsh tui 進程才能生效。

dsh plugin --profile web add github:AK-blank/dsh-plugin-mac-notify

安裝完成後，插件會在 DSH 的 Plugins 頁面出現，可以手動開關。

配置¶

插件本身不攜帶配置項，所有設置需在 cordis.patch.yml 中覆蓋（在 bundle 層之後應用）：

- id: mac-notify
  name: 'dsh-plugin-mac-notify'
  config:
    enabled: true
    sound: Ping
    notifyOnApproval: false
    url: 'http://127.0.0.1:3080'

主要配置項包括：
* enabled：總開關。
* sound：音效名稱（如 Ping、Glass）或 off。
* onClick：點擊行爲，focus（聚焦現有標籤頁）、open（打開新標籤頁）、none。
* notifier：選擇 auto（推薦）或強制使用 osascript。
* minIntervalMs：非緊急通知的最小間隔（默認 1500ms）。

典型用法¶

安裝後，可以通過以下命令進行自檢，確保 57 項斷言全部通過：

node selftest.mjs

如果需要調試而不實際發送通知，可以使用環境變量：

DSH_MAC_NOTIFY_DRY_RUN=1 dsh web

注意事項¶

平臺限制：僅支持 macOS。其他平臺插件會激活並記錄日誌，但不會發送通知。
依賴項：點擊跳轉功能依賴 terminal-notifier。如果沒有安裝，插件會回退到 osascript，但無法執行點擊動作。
- 安裝命令：brew install terminal-notifier
系統權限：需要授予插件通知權限和 macOS Automation 權限（首次點擊時系統會彈窗）。
重啓生效：插件更新後，必須重啓 dsh web 或 dsh tui 進程才能加載新代碼。

結尾¶

該插件通過原生通知解決了 DSH 後臺運行時的狀態同步問題。通過查看 GitHub 倉庫，你可以獲取源碼和更多調試信息。