前言¶
DeepSeek Harness（DSH）採用插件化架構。在 Windows 端開發或運行 DSH 時，直接通過瀏覽器訪問界面可能不夠便捷。此時，一個系統托盤程序可以提供常駐入口，方便隨時打開界面、查看狀態或退出。
dsh-tray 插件旨在解決這一問題。它通過 Windows 任務欄提供托盤圖標、下拉菜單和氣泡通知，併兼容 Headless 運行模式。
插件定位¶
- 名稱：dsh-tray
- 維護者：qing3a
- 分類：客戶端
- 協議：MIT
- 核心價值：爲 DSH 提供 Windows 系統托盤支持，替代手動打開瀏覽器或命令行窗口進行管理。
核心功能¶
- 系統托盤圖標
默認使用default.ico，可通過配置項iconPath自定義圖標（支持.ico或.pngBuffer）。 - 托盤菜單
包含三個操作：- 打開界面：動態讀取
webServer.port並拼接 URL 打開瀏覽器。 - 狀態：顯示當前狀態。
- 退出：關閉托盤程序。
- 打開界面：動態讀取
- 氣泡通知
支持彈出info風格的通知消息。 - Headless 兼容
當環境中沒有webServer時，插件會自動降級，不會導致程序崩潰或阻塞加載。
安裝與啓用¶
安裝時需要使用 --profile web 參數。
pnpm dsh plugin --profile web add @qing3a/dsh-tray
pnpm dsh --profile web
安裝完成後，Windows 任務欄應會出現 DSH 托盤圖標。
配置¶
插件支持以下配置項（通常在 DSH 的配置文件中設置）：
| 鍵 | 默認值 | 說明 |
|---|---|---|
enabled |
true |
總開關，控制插件是否啓用 |
title |
DSH |
托盤標題，決定臨時文件的命名 |
iconPath |
空 | 自定義圖標路徑，留空則使用包內的 default.ico |
實現細節¶
該插件基於 trayicon@1.2.2 開發，是一個 win32-only 的插件（無 native 編譯依賴）。
- 避免文件句柄衝突：代碼中直接
spawn包內的 exe，沒有使用useTempDir複製文件到臨時目錄，從而避免了 Windows 下常見的spawn EBUSY錯誤。 - 併發控制：
start()方法設計爲冪等，通過共享pending promise來去重，防止併發調用導致出現兩個托盤實例。 - 平臺兼容：在非 win32 平臺（如 Linux 或 macOS），插件會自動跳過加載。
- Headless 支持：通過
ctx.inject動態獲取webServer，確保在無 webServer 環境下不會報錯阻塞。
卸載¶
如需移除插件，執行以下命令：
pnpm dsh plugin --profile web remove @qing3a/dsh-tray
總結¶
dsh-tray 通過封裝 trayicon 庫，爲 DSH 在 Windows 環境下提供了標準化的托盤交互能力。它解決了 Headless 模式下的兼容性問題，並優化了進程啓動和併發邏輯。
