前言¶
在 DeepSeek Harness 裏接桌面能力，常見路徑是截圖後讓模型猜座標、一步一步點。每步都要回模型，鏈路長；點沒點上往往只能再截一張圖猜。若同一條流程要反覆跑，成本更高，失敗後的重試也缺少統一語義。
dsh-gui-control（維護者 seetown，npm 包名 dsh-gui-control，當前版本 0.1.3，MIT 許可證）面向 Windows：優先讀無障礙樹、按控件名操作，並支持聲明式任務文件與投遞判定。社區目錄歸類爲工作流，見 SkillHub 目錄頁；源碼與說明見 GitHub。DSH 生態是「一切皆插件」；社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
這是什麼¶
一句話：給 DeepSeek Harness 用的 Windows 桌面操控插件——不是單次「幫我點一下」，而是把一串動作寫成任務文件，一次工具調用跑完，跑任務文件時模型可不參與循環。
平臺與依賴（README 原文）：
- 僅 Windows（Win32 + UI Automation）
- Windows 10 1809+、PowerShell 5.1
- DeepSeek Harness 0.1.5-rc.2 ~ 0.2.x
- Node（package.json）：
^22.19.0 || >=24.0.0
和常見桌面 Agent 的差異¶
| 常見做法 | dsh-gui-control | |
|---|---|---|
| 感知 | 截圖 → 模型猜座標 | 無障礙樹優先，按控件名定位；樹不可用時才截圖 |
| 一次任務的往返 | 每步一次模型調用 | 一次調用跑完整個任務文件 |
| 失敗之後 | 不知道點沒點上 | 投遞判定：沒發出去 / 可能發出去了 / 已驗證 |
| 重複執行 | 每次重跑一遍 | 任務文件可複用，帶條件等待與重試 |
README 中的演示方向包括：打開 B 站搜番並選集、通過 UI Automation Invoke 做「零像素位移」語義點擊、在表格類場景用多步任務一次填完（文檔示例爲 17 步 / 0.9 秒 / 一次調用）。
核心功能：三個工具¶
插件向 Harness 暴露三個工具，分工如下。
| 工具 | 作用 |
|---|---|
gui_snapshot |
讀窗口的無障礙樹（文本），或帶屏幕座標刻度尺的截圖 |
gui_act |
執行單個動作，帶身份校驗和投遞判定 |
gui_task |
跑聲明式任務文件：一次調用多步，帶條件、重試、風險閘門 |
下面先讀樹，再按文本點控件，是 README 推薦的路徑。
讀記事本窗口的無障礙樹：
gui_snapshot { window: "Notepad", mode: "tree" }
→ Butto 關閉標籤頁 / Docum 文本編輯器 / MenuI 文件 ...
按控件名點擊（優先於座標；可走 Invoke，鼠標可不動）：
gui_act { action: "click_text", window: "Notepad", text: "最大化" }
→ click ok via InvokePattern | verified: text appeared
投遞語義¶
每個動作返回三選一，決定是否可安全重試：
| 判定 | 含義 | 能否重試 |
|---|---|---|
not_delivered |
什麼都沒發出去（派發前就被拒） | 安全可重試 |
delivered_unverified |
發出去了，效果未確認 | 不能盲目重放 |
delivered_verified |
發出去了，且後置條件驗證通過 | 不宜盲目重放 |
文檔指出，這一條直接影響「發消息 / 刪文件 / 提交表單」等不可逆操作能否穩妥自動化；結果不明時絕不自動重試。
任務文件¶
任務用 JSON 描述步驟。示例（摘自 README）：
{
"name": "fill-sheet",
"steps": [
{ "do": "activate", "win": "工作簿1" },
{ "do": "type", "text": "項目" },
{ "do": "key", "key": "tab" },
{ "do": "type", "text": "金額" },
{ "do": "key", "key": "enter",
"until": { "op": "pathexists", "text": "C:\\out\\report.xlsx" }, "untilTimeout": 10 }
]
}
每步除 do 與動作參數外，還可帶 until（輪詢到條件成立纔算過）、untilTimeout、retry、risk。
risk: "high"的步驟默認拒絕執行，須顯式confirm: truedryRun: true只返回計劃，不碰桌面
安裝與啓用¶
在已滿足 Windows 與 Harness 版本的前提下，在 Harness 環境中執行官方安裝命令：
dsh plugin add dsh-gui-control
也可按倉庫路徑安裝（README 原文）：
dsh plugin add seetown/dsh-gui-control
裝完不需要重啓 Harness。首次調用會預熱常駐進程（文檔約 1 秒），之後動作爲本機 loopback 往返；服務只監聽 127.0.0.1:38471，不對外暴露。
性能與限制（README 實測與說明）¶
文檔給出的部分耗時參考（環境以作者實測爲準，非性能承諾）：
| 操作 | 耗時 |
|---|---|
| 單步動作（常駐進程） | 10.8 ms |
| 語義點擊（UIA 樹） | 26–34 ms |
| 緊湊樹讀取 | 86 ms，865 字符 |
| 7 步任務（含啓動計算器） | 680 ms，一次調用 |
| WPS 填 2×3 表格 | 0.9 s，17 步 |
已知限制：
- 畫布類應用（WPS 表格、遊戲、自繪列表）常無完整無障礙樹，只能截圖 + OCR，準確率下降
- 網頁任務目前基於截圖；CDP 通道已實現但尚未接入工具
- Roadmap 含 Set-of-Marks 截圖、CDP 網頁選擇器、任務庫與意圖路由、macOS / Linux 適配（均未在文中標明完成）
安全與適用注意¶
插件能操控本機真實鼠標鍵盤，以當前 DSH 進程權限運行。安裝與啓用前建議閱讀 源碼 與 MIT 許可證，僅在可信環境使用。
README 列出的安全措施包括：loopback 監聽、密碼字段輸出 <redacted>、高風險步驟需顯式確認、投遞未驗證時不自動重試。
適合：需要在 Windows 上把重複 GUI 流程交給 Harness、且希望少依賴座標猜測與逐步模型調用的工作流場景。不適合：非 Windows、或強依賴無無障礙樹畫布且不能接受 OCR 降級的場景。
結尾¶
dsh-gui-control 把「看樹 → 按名操作 → 判定是否投遞成功 → 任務文件一次跑完」收成一套 DSH 工具面，定位是工作流型桌面控制而非單次救火。
- 目錄頁：https://www.skillhub.cn/plugins/seetown/dsh-gui-control
- GitHub：https://github.com/seetown/dsh-gui-control
