gui-automation

name	gui-automation
description	Windows GUI automation via UI Automation API and screenshot-based reasoning loop. Use when controlling desktop applications that have no PowerShell or COM API. Integrates Windows-Use (UIA) and microsoft/cua_skill (perceive-reason-act loop).
version	1.0.0
sources	["https://github.com/CursorTouch/Windows-Use","https://github.com/microsoft/cua_skill"]

GUI Automation Skill

適用場景

• 需要點擊按鈕、填寫表單、選擇選單
• 目標程式無 API 或 COM 介面
• 需要讀取螢幕內容（截圖 + OCR）

不適用： Office 程式（改用 com-automation）、系統設定（改用 powershell-patterns）

核心能力（來自 Windows-Use）

UIA 元素操作

# engines/uia-python/
from windows_agent.perceive import get_uia_tree, find_element
from windows_agent.act import click, type_text, scroll

# 找到並點擊元素
element = find_element(name="確定", control_type="Button")
click(element)

# 鍵入文字
field = find_element(name="搜尋", control_type="Edit")
type_text(field, "查詢內容")

截圖推理迴圈（來自 cua_skill）

# engines/cua-loop/
from cua_loop import perceive, reason, act

# 感知目前畫面
state = perceive()          # 截圖 + UIA 樹快照

# 推理下一步動作
action = reason(state, goal="點擊登入按鈕")

# 執行
result = act(action, dry_run=False)

腳本

• scripts/capture.py — 截圖並儲存
• scripts/click_by_name.py — 依元素名稱點擊
• scripts/inspect_tree.py — 列印 UIA 元素樹

使用指引

1. 先用 inspect_tree.py 找出目標元素
2. 若元素有 Name 屬性，用 find_element(name=...)
3. 若需視覺推理，啟動截圖迴圈
4. 操作後截圖確認結果

安全注意

• 操作前記錄初始截圖
• 等待元素可見後再點擊（避免時序錯誤）
• 破壞性操作（關閉程式、刪除檔案對話框）需確認

參考資料

• references/uia-patterns.md — UIA 常用模式
• references/screenshot-loop.md — 截圖推理迴圈
• references/element-locators.md — 元素定位策略
• engines/uia-python/ — Windows-Use Fork
• engines/cua-loop/ — cua_skill Fork