前言¶
在 DeepSeek Harness（DSH）裏做自動化，常見做法是寫腳本或調 API；一旦任務落在本機 GUI——對話框、資源管理器、沒有穩定接口的桌面軟件——模型往往只能「猜界面」，你還得自己點鼠標。社區插件 dsh-gui-control（維護者 Macocin，GitHub：Macocin/dsh-gui-control）把截圖、讀屏和鼠標鍵盤控制收成一組 desktop_* 工具，讓模型按「看 → 點 → 打字 → 再看」閉環操作 Windows 桌面。下面介紹它是什麼、能做什麼、怎麼裝，以及使用前必須知道的邊界與安全點。
這是什麼¶
dsh-gui-control 是 DSH 的客戶端類插件：類似人類操作的桌面控制——查看截圖、控制鼠標鍵盤，並附帶低成本讀屏（無障礙樹、OCR、找色/網格、截圖分級）。當前資料版本爲 0.1.0，僅支持 Windows，要求 Node ≥ 18，零 npm 依賴（Node 內置模塊 + 系統自帶 PowerShell 5.1），許可證 MIT。
插件同時註冊 gui-control skill，把座標換算、省 token 的讀屏策略和常見坑寫進模型上下文。社區目錄頁：https://www.skillhub.cn/plugins/Macocin/dsh-gui-control ；源碼與說明：https://github.com/Macocin/dsh-gui-control 。目錄站點與 DeepSeek / 幻方無官方從屬關係，屬於 DSH「一切皆插件」生態裏的第三方條目。
核心功能¶
讀屏：L0 → L4，先便宜後貴¶
同一畫面，讀屏手段不同，token 代價可差約 5～20 倍。README 要求永遠從 L0 往 L4 試，第一級成功就停，並在本會話內記住該應用適合哪一級。
| 層級 | 工具 | 作用概要 |
|---|---|---|
| L0 | desktop_a11y |
Windows UI Automation 控件樹（名稱 + 座標） |
| L1 | desktop_ocr |
屏幕文字 JSON（文本 + 座標，無圖） |
| L2 | desktop_find |
找色 / 網格 / 校驗某點顏色 |
| L3 / L4 | desktop_screenshot |
截圖回傳圖像（可限窗口、區域、灰度、變更檢測等） |
輔助工具 desktop_info 返回顯示器、DPI、光標、前臺窗口、窗口列表等純文本，不消耗圖像 token。
操作：類人軌跡與一步多動¶
desktop_mouse：move/click/right/double/drag/scroll；默認鼠標走三次貝塞爾曲線 + 緩動 + 抖動，而非瞬移。desktop_keyboard：type（逐字符 Unicode）、paste（剪貼板）、press/hold。desktop_act：一串步驟 + 末尾截圖，一次調用完成多步；含waitChange等。desktop_click_text：按文字找座標並點擊，支持dryRun。
座標默認綁定最近一張截圖的像素：
screenX = region.left + imageX / scale.x。需要物理屏幕座標時傳 space: "screen"。
緊急停止（使用前必讀）¶
| 熱鍵 | 效果 |
|---|---|
| Ctrl+Shift+C | 所有桌面控制立刻失效 |
| Ctrl+Shift+C+V | 急停 + 要求 AI 結束對話 |
| Ctrl+Shift+X | 解除（僅用戶按鍵，無工具可代解） |
急停後工具返回 HALTED，狀態寫入 %TEMP%\dsh-gui-control\halt-<pid>.json，Node 每次調用前讀取。README 強調：務必閱讀急停章節；不要給 DeepSeek 改這個插件，以免急停邏輯被改壞；代碼經 AI 覈查，可能存在未發現問題。敏感界面上不要讓插件看屏——截圖、OCR、無障礙樹會把屏幕內容（含可見信息）送入模型上下文；paste 會臨時讀寫剪貼板。
急停生效後，desktop_guard 仍可查看狀態，是被攔截時唯一還能調通的工具。
實現要點（便於評估信任邊界）¶
- 持久 helper 進程：
helper/win-helper.ps1，JSON 行協議，約 50–90ms/次調用。 - 截圖走 GDI，輸入走
SendInput；不執行 shell（無Invoke-Expression/cmd.exe等拼用戶輸入進腳本的路徑）。 - 區域在 Node 側
clampRegion()與 C# 側均有像素上限，避免巨圖拖垮 GDI。
安裝與啓用¶
在 DSH 內通過 plugin_manager 安裝本地 bundle（路徑換成你本機目錄；資料未給出 dsh plugin add github:... 一類命令，勿自行拼接）：
plugin_manager install_bundle target=file:<你的路徑>/dsh-gui-control
示例：
plugin_manager install_bundle target=file:D:/code/dsh-gui-control
裝好後重啓 DSH，會出現十個 desktop_* 工具與 gui-control skill。改代碼後需重新 install_bundle 或覆蓋 profile 下 node_modules/dsh-gui-control/（非軟鏈）；僅改 helper/win-helper.ps1 時可殺掉 helper 進程，下次調用自動拉起新腳本。
配置項（package 默認）¶
| 項 | 默認 | 說明 |
|---|---|---|
helperPath |
包內 helper/win-helper.ps1 |
helper 腳本 |
powershell |
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe |
PowerShell 可執行文件 |
timeoutMs |
60000 | 單條 helper 命令超時 |
環境變量 DSH_GUI_CONTROL_KEEP_DIR：設置後每張截圖另存一份（調試用）。
典型用法與本地測試¶
脫離 DSH 時，可在插件目錄用 Node 跑冒煙腳本（README 所列）：
node test/smoke.mjs # 工具註冊 + info/截圖/移動/批量
node test/input.mjs # 打開記事本, 聚焦, 打字(中文), 截圖, 關閉
node test/click.mjs # 按截圖座標點擊 + 長文本粘貼
node test/framing.mjs # act 步驟座標跟隨本次取景目標
node test/halt.mjs # 真按急停熱鍵，斷言攔截與恢復
node test/halt-midflight.mjs # 打字中途急停，斷言約 1.5s 內中斷
在 DSH 會話裏，模型應優先 desktop_a11y / desktop_ocr / desktop_find，再必要時 desktop_screenshot；Electron/Chromium 類應用控件樹常只有少量節點，資料建議直接走 L1。遊戲或自繪界面可優先 L2 找色。
適用場景與注意¶
適合：需要在 Windows 上讓 DSH 模型操作本機 GUI、又不想單獨維護 RPA 框架的開發者；強調 token 成本的讀屏分級與類人輸入的場景。
不適合或需人工介入：UAC / 安全桌面（截圖黑、輸入無效）、最小化窗口（需先還原）、鎖屏、被其他窗口遮擋的「窗口區域截圖」、目標窗口以管理員權限運行而當前用戶權限不足時 SendInput 被拒絕。
插件以當前 DSH 進程用戶權限運行，不會自行提權。安裝前應閱讀源碼與 MIT 許可證，並理解 README「安全模型」：超時後 Node 放棄等待但 helper 內命令可能仍在跑；屏幕與 OCR 結果會進入模型服務商上下文。
結尾¶
dsh-gui-control 把 Windows 桌面的看與控封裝成 DSH 工具，並用 L0–L4 讀屏策略和全局急停控制自動化風險。若要進一步瞭解參數與邊界，以倉庫 README 爲準。
- 社區目錄：https://www.skillhub.cn/plugins/Macocin/dsh-gui-control
- GitHub：https://github.com/Macocin/dsh-gui-control
