前言¶
DeepSeek Harness (DSH) 的 agent 在處理桌面應用任務時，需要具備“看”和“做”的能力。現有的 DSH profile 可能缺乏針對 Windows 桌面的具體交互手段。sage-guikit 是一個專爲 DSH 設計的 GUI 工具包，它將 Windows 桌面控制能力打包成 profile bundle，爲 agent 提供屏幕布局監控、截圖、鼠標/鍵盤操作、窗口管理以及基於 UI Automation 的結構化查詢與驗證功能。
核心功能¶
該插件提供 13 個模型工具，核心能力包括：
- 屏幕與截圖：獲取顯示器佈局契約，支持全屏及單窗口截圖，並附帶座標標註功能。
- 交互操作：支持點擊、拖拽、打字、按鍵及滾動。
- 窗口管理：列出窗口、獲取/激活/移動窗口。
- 定位與驗證：通過元素名或 UIA 樹定位控件，支持輪詢驗證和語義驗證。
安裝與啓用¶
安裝該插件需要手動操作，將其作爲 DSH profile bundle 引入。
- 進入 DSH profile 目錄（例如
~/.dsh/profiles/web）。 - 執行安裝命令：
pnpm add dsh-guikit
- 編輯該目錄下的
package.json，在dsh.profile.bundles數組中添加"dsh-guikit"。 - 重啓 DSH Web 服務。
本地開發時也可使用 link: 方式，但需注意裸導入可能無法解析到 profile 的 node_modules，此時需在插件目錄自行安裝 peer 依賴（@deepseek-ai/cordis、@deepseek-ai/dsh-tools）。
工具概覽¶
插件註冊了以下模型工具：
屏幕與截圖¶
gui_screen: 獲取顯示器佈局、虛擬桌面原點、DPI 縮放等信息。任何座標操作前應先調用此工具。gui_screenshot: 截取全屏或指定區域，返回圖片路徑。開啓annotate後會繪製標尺、網格座標標籤和左下角水印。gui_window_shot: 單窗口截圖（PrintWindow），不激活窗口，不遮擋。返回window-local空間座標。
交互操作¶
gui_click: 在指定座標點擊。支持window參數和space參數（window-local）。可選verify參數進行點擊後驗證。gui_drag: 模擬按住鼠標拖動，用於選文字、拖動滑塊等。gui_type: 向焦點控件打字，支持unicode（繞過 IME）和clipboard模式。gui_key: 發送系統按鍵或組合鍵（如ctrl+s）。gui_scroll: 在指定位置滾動滾輪。
定位與管理¶
gui_locate: 通過元素名或窗口標題定位。不猜測座標，僅在status="found"時返回可點擊座標。支持timeoutMs輪詢。gui_uia: 使用 Windows UI Automation 結構化查詢，支持tree、find、invoke、value等操作。gui_window: 窗口管理，支持list、rect、activate、move操作。
驗證¶
gui_wait: 輪詢驗證，支持像素變化對比或窗口出現等待。gui_verify: 語義驗證，斷言元素是否存在或屬性是否滿足條件。返回三態結果（satisfied/unsatisfied/unknown）。
座標系統與契約¶
插件定義了三套空間，工具之間不互相猜測，必須嚴格遵循返回的契約進行換算：
| 空間名稱 | 用途 | 原點 |
|---|---|---|
| virtual-desktop-physical | gui_click / gui_drag 入參；gui_screen / gui_locate 返回值 |
虛擬桌面左上 |
| image-pixels (截圖) | read_image 讀取的圖像像素 |
截取區域左上 |
| window-local | gui_window_shot 返回值；gui_click 的 space="window-local" 入參 |
窗口左上 |
換算邏輯：
* 圖內像素 → 桌面座標：絕對 = origin + 圖內像素 × scale
* 桌面座標 → 圖內像素：圖內 = (絕對 − origin) ÷ scale
注意事項：read_image 返回的圖像通常經過了降採樣（如 ×1.50），圖素間距不可信。請務必使用 annotate=true 生成的圖片中的標籤文本讀取座標，而非手動計算。
注意事項¶
- 平臺限制：僅支持 Windows 10/11。
- 依賴環境：依賴 PowerShell 7 和 .NET 的
System.Drawing/UIAutomationClient。 - 權限與安全：工具在當前 DSH 進程權限下運行，調用前應檢查源碼與許可證。
- 驗證結果：
gui_verify返回unknown並不表示成功，表示“判不出來”，絕不可作爲成功讀數。
結語¶
sage-guikit 通過提供結構化的 UI Automation 查詢和明確的座標契約，解決了 DSH agent 在 Windows 桌面自動化中定位不準、驗證困難的問題。安裝後，agent 即可獲得完整的“眼手”能力。更多細節可參考其 GitHub 倉庫：gezi-wen/sage-guikit。
