前言¶

使用 DeepSeek Harness（dsh）跑代理任務時，常見的問題是：任務在後臺繼續執行，而開發者已經切走窗口，不知道頂層任務何時完成、何時出錯，也不知道是否正在等待沙箱審批或代理提問。手動盯日誌不是長久之計。

下面介紹一個 DSH 插件：dsh-win-notify。它在 Windows 上彈出帶聲音的 Toast 通知，並在點擊通知時儘量把現有 DSH GUI 會話切到前臺，而不是反覆打開新的臨時瀏覽器標籤。

這是什麼¶

dsh-win-notify 是一個 DeepSeek Harness（dsh）插件，由 MuziIsabel 維護，許可證爲 MIT。

它解決的問題是：當代理任務完成、出錯、等待審批或等待回覆時，在 Windows 10/11 上給出帶聲音的通知；點擊通知後，優先切換並顯示已有的 GUI 標籤。

插件顯示應用名爲 DeepSeek，並使用官方鯨魚圖標；通知能力僅依賴 Windows 自帶的 PowerShell 5.1，不要求額外安裝運行時。

核心功能¶

• 頂層代理回合完成時通知：會話代理狀態由 running 變爲 idle 時觸發。
• 子代理回合保持靜默，避免子任務過程頻繁打擾。
• 通知正文顯示最近一條用戶提示詞。
• 任務出錯時可配置爲通知。
• 等待沙箱 / 權限審批時可配置爲通知。
• 代理通過 ask_user_question 提問並等待回覆時可配置爲通知。
• 聚焦感知：如果 GUI 頁面處於前臺，並且當前正顯示觸發事件的會話，則抑制該會話的通知。
• 手動停止的任務不算完成，不彈通知。
• 點擊通知時優先切換並前臺顯示現有 GUI 標籤；不產生臨時瀏覽器標籤；僅當沒有存活 GUI 時才新開標籤。
• 身份註冊失敗時，回退到 NotifyIcon 氣泡。
• 僅依賴 Windows 自帶的 PowerShell 5.1。

安裝與啓用¶

先在目標 profile 安裝插件。以 web profile 爲例：

dsh plugin --profile web add github:MuziIsabel/dsh-win-notify

執行後，dsh plugin 會在 profile 目錄內轉發給 pnpm，bundle 會把自身合併進該 profile 的 dsh.profile.bundles 列表。

安裝完成後，重啓 profile，或讓該 profile 的 HMR 生效，即可激活插件。

如果你希望在其他 profile 收到通知，可以按同樣方式安裝到 headless 等 profile。

卸載命令：

dsh plugin --profile web remove dsh-win-notify

典型用法¶

插件會在 profile 中插入加載行 win-notify。你可以在 profile 的 cordis.patch.yml 中覆蓋配置。

下面是 README 中給出的完整配置示例：

- id: win-notify
  config:
    enabled: true          # 啓用插件（默認 true）
    sound: default         # default | reminder | sms | alarm | silent
    onError: true          # 任務出錯時也通知（默認 true）
    openOnClick: true      # 點擊通知打開/切換 GUI 會話（默認 true）
    directActivate: true   # 優先投遞給存活的本機迴環 GUI 標籤；否則走瀏覽器深鏈
    baseUrl: ''            # 自定義 GUI 根地址（默認自動取 webServer 端口）
    approval: true         # 等待用戶審批時通知（默認 true）
    approvalWaitMs: 3000   # 審批等待多久後彈通知
    question: true         # 等待用戶回覆時通知（默認 true）
    questionWaitMs: 3000   # 提問等待多久後彈通知
    suppressWhenVisible: true  # 正查看的會話抑制通知（默認 true）
    visibilityTtlMs: 25000      # 前臺狀態新鮮度窗口（客戶端約每 10 秒心跳）
    title: 'DeepSeek Harness'
    body: '任務已完成'
    bodyError: '任務出錯'
    maxPromptChars: 64

如果只是臨時關閉通知，可以只覆蓋 enabled：

- id: win-notify
  config:
    enabled: false

如果需要修改提示詞長度或文案，可以覆蓋：

- id: win-notify
  config:
    maxPromptChars: 80
    title: 'DeepSeek'
    body: '任務已完成'
    bodyError: '任務出錯'

點擊通知如何工作¶

對本機迴環 GUI 地址，插件會註冊 dsh-win-notify:// 協議。點擊通知後，它啓動本地微型 DeepSeek.exe 助手，而不是直接打開瀏覽器。

該助手請求本機 DSH 服務向最近聚焦的存活 GUI 標籤投遞 open-session 命令；對應標籤在原地調用 sessions.open(id)。這樣不會整頁刷新，也不會新開瀏覽器標籤。

如果成功確認，助手還會盡力用 Windows UI Automation 選中標題匹配的 Chrome / Edge 標籤，方便你在其他標籤瀏覽時把 DSH 標籤帶到前臺。瀏覽器窗口最大化或普通大小時保持原狀；僅最小化的窗口會被恢復。

需要注意：瀏覽器輔助功能、權限級別、虛擬桌面與焦點搶佔策略仍可能阻止前臺切換；此時會話也已在後臺選中。

如果沒有存活 GUI 及時確認，或協議註冊不可用，助手會安全回退到常規 <gui>/?session=<id> 深鏈；該深鏈的 BroadcastChannel 交接作爲第二重回退。

首次自定義協議點擊可能需要一次性瀏覽器 / Windows 確認。非迴環的自定義 baseUrl 出於安全考慮保持常規 HTTP 深鏈。

身份註冊與診斷日誌¶

Windows 只展示來自已註冊身份的 toast。插件激活時會自動做一次性身份註冊：

1. 向 %LOCALAPPDATA%\DeepSeek 編譯一個微型 DeepSeek.exe 佔位程序。
2. 創建指向它的開始菜單快捷方式 DeepSeek.lnk，圖標爲多尺寸 DeepSeek.ico。
3. 通過 IPropertyStore P/Invoke 把 AppUserModelID（DSH.WinNotify）寫入快捷方式。

註冊完成後，通知會以 DeepSeek 名稱和鯨魚圖標顯示。

DeepSeek.lnk 是通知身份載體，請勿刪除。如果缺失，插件會自動重建。

插件會把每次註冊嘗試與通知追加記錄到：

$DSH_HOME/dsh-win-notify.log

適用場景與注意¶

適合在 Windows 10/11 上使用 DSH 的開發者，尤其是以下情況：

• 代理任務經常運行較長時間，完成後需要被提醒。
• 任務出錯時也需要及時收到通知。
• 任務等待沙箱審批或 ask_user_question 回覆時，需要被提醒回來處理。
• 希望點擊通知後回到現有 DSH GUI 會話，而不是不斷打開新標籤。

注意事項：

• 環境要求爲 Windows 10/11，以及 dsh 的任意 profile（web、headless、tui）。
• 插件以當前 dsh 進程權限運行，因此安裝前建議檢查源碼與許可證。
• 通知身份依賴開始菜單快捷方式 DeepSeek.lnk，缺失時插件會重建，但不要手動刪除。
• 如果沒有收到通知，先檢查 Windows 通知設置中 DSH.WinNotify 是否啓用，並確認 DeepSeek.lnk 是否存在。
• 圖標源自 DeepSeek Harness favicon（@deepseek-ai/dsh-web-frontend，MIT © DeepSeek）。

鏈接¶

• GitHub：https://github.com/MuziIsabel/dsh-win-notify
• 可在 DSH 插件 / 社區目錄中搜索插件名 dsh-win-notify。