dsh-desktop-uia：基於 UI Automation 的 Windows 桌面控制插件

前言¶

DeepSeek Harness (DSH) 採用插件化架構，旨在通過配置文件管理工具生態。在開發需要控制桌面應用的智能體時，傳統方案通常依賴截圖識別或座標猜測，這種方式不僅脆弱，且難以應對窗口布局變化。dsh-desktop-uia 插件通過 Windows UI Automation (UIA) 接口讀取窗口的控制樹，利用穩定的自動化 ID 驅動元素。它不依賴截圖，所有寫入操作需經批准，所有動作均可審計。

安裝與啓用¶

該插件通過 npm 發佈，也可以直接下載編譯好的包安裝。安裝前需確保環境滿足要求。

安裝命令¶

使用官方提供的安裝命令添加插件：

dsh plugin --profile web add dsh-desktop-uia

環境要求¶

操作系統：僅支持 Windows 10 或 11 (x64)。
DSH 版本：需使用基於配置文件的安裝方式，且已驗證對 0.1.2‑rc.1 / 0.1.5‑rc.1 插件契約的兼容性。
依賴工具鏈：無需額外安裝 .NET SDK、NuGet 或 MSVC。插件自帶 Sidecar，安裝腳本會使用系統自帶的編譯器進行構建。

手動安裝（可選）¶

從 Releases 下載 zip 包，解壓後雙擊 install.cmd 即可完成安裝。安裝腳本會將插件放入 DSH 配置文件的 node_modules 中。

核心功能¶

插件提供了一套 desktop_* 工具集，用於管理窗口、讀取控制樹、執行動作以及等待狀態變化。根據功能性質，部分操作免費，部分操作需要批准。

窗口管理¶

desktop_windows：列出頂層窗口（包含句柄、PID、標題、狀態等）並管理窗口。list 和 focus 操作免費，其他操作（最小化、最大化、移動、關閉等）需要批准。
desktop_launch：啓動程序、文檔或 URI（如 notepad 或 ms-settings:）。
desktop_wait：等待窗口出現、元素出現、值變化或元素消失，避免無效睡眠。

探索與檢查¶

desktop_snapshot：讀取窗口控制樹。可通過 query 按名稱、類型或自動化 ID 查找元素。默認爲 auto 模式（有預算探測），也可選 all 或 none（最快）。
desktop_inspect：檢查單個元素的詳細信息，包括框架、類名、啓用/聚焦狀態、支持的模式（Patterns）以及當前值。

動作與輸入¶

desktop_act：執行點擊、右鍵、雙擊、懸停、聚焦、調用、設置值、選擇、拖動等操作。所有此類操作需要批准。
desktop_input：輸入 Unicode 文本（支持 CJK 字符）或發送鍵組合（如 ctrl+s）。
desktop_clipboard：讀取或替換剪貼板文本。寫入操作需要批准。

輔助能力¶

desktop_screenshot：捕獲窗口或整個桌面爲 PNG 圖片。
desktop_clipboard：讀取或替換剪貼板文本。

典型用法¶

以下命令展示瞭如何啓動程序、查找元素並執行操作：

# 啓動記事本
desktop_launch notepad

# 在當前窗口輸入文本
desktop_input "Hello World"

# 查找名爲 "Save" 的元素（快照）
desktop_snapshot query {name: "Save"}

# 點擊 ID 爲 el_12 的元素
desktop_act click el_12

# 等待名爲 "Calculator" 的窗口出現
desktop_wait window "Calculator"

注意事項¶

權限與批准：由於插件以 DSH 進程權限運行，涉及修改 UI 的操作（如 desktop_act、desktop_input）和剪貼板寫入均需批准。只有 desktop_windows 的 list 和 focus 是免費的。
性能限制：對於響應較慢的窗口（如 Chromium、Java 應用），插件會自動限制讀取的節點數（maxNodes 300）和深度（maxDepth 5），以避免阻塞。
元素穩定性：元素 ID 基於 UIA 運行時 ID 生成。如果窗口重建，ID 會失效並報告 STALE_ELEMENT，需重新快照。
操作反饋：系統會檢測並反饋“新窗口出現”、“慢提供者”以及“重複無操作點擊”（連續兩次相同操作後，第三次相同操作會被拒絕，提示檢查元素狀態）。

總結¶

dsh-desktop-uia 爲 DSH 提供了基於 UIA 的穩定桌面控制能力，通過 ID 驅動替代了脆弱的座標猜測，並配合批准機制保證了操作的安全性。它適合需要在 Windows 環境下構建自動化代理的場景。更多細節與源碼可參考插件目錄或GitHub 倉庫。