ubuntu-desktop-control

桌面控制技能

使用语义化元素定位来控制桌面 GUI。按名称查找并点击 UI 元素，而不是使用坐标。

主要功能：

• AT-SPI - 使用无障碍树的主要方法（可识别元素角色、状态和操作）
• OCR 回退 - 当 AT-SPI 找不到元素时，使用基于 Tesseract 的文本查找
• 等待实用工具 - 使用指数退避轮询，等待元素出现
• 点击验证 - 可选的点击前截图验证

先决条件

安装依赖项：

bash install.sh

或手动安装：

# System packages
sudo apt-get install -y xdotool scrot imagemagick \
    at-spi2-core libatk-adaptor python3-gi gir1.2-atspi-2.0 \
    tesseract-ocr tesseract-ocr-eng python3-pip

# Python packages
pip3 install -r requirements.txt

对于无头 Xvfb 会话：

export GTK_MODULES=gail:atk-bridge
export QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1
/usr/lib/at-spi2-core/at-spi-bus-launcher &

命令

所有命令默认使用 DISPLAY=:10.0。使用 --display 标志覆盖。

---

find-element

通过 AT-SPI 查找 UI 元素，失败时回退到 OCR。

python3 scripts/desktop.py find-element --name "Confirm" [--role button] [--app Firefox]

参数	类型	必填	描述
--name、-n	string	否	要查找的元素名称/文本
--role、-r	string	否	元素角色（button、entry 等）
--app、-a	string	否	按应用名称筛选
--all	flag	否	查找所有匹配项
--clickable	flag	否	仅查找可点击元素
--max-results	int	否	最大结果数（默认：50）

返回：

{
  "element": {
    "name": "Confirm",
    "bounds": { "x": 400, "y": 300, "width": 100, "height": 30 },
    "center": { "x": 450, "y": 315 },
    "role": "push button",
    "source": "atspi",
    "visible": true,
    "enabled": true,
    "clickable": true
  }
}

---

find-text

仅通过 OCR 查找屏幕上的文本。

python3 scripts/desktop.py find-text "I have an existing wallet" [--exact] [--all]

参数	类型	必填	描述
text	string	是	要查找的文本
--exact	flag	否	要求完全匹配
--case-sensitive	flag	否	区分大小写匹配
--all	flag	否	查找所有匹配项
--max-results	int	否	最大结果数（默认：50）

返回：

{
  "match": {
    "name": "I have an existing wallet",
    "bounds": { "x": 200, "y": 400, "width": 180, "height": 20 },
    "center": { "x": 290, "y": 410 },
    "source": "ocr",
    "confidence": 95.2
  }
}

---

click-element

按名称/角色点击元素（先查找元素，再点击其中心位置）。

python3 scripts/desktop.py click-element --name "Next" [--role button] [--verify]

参数	类型	必填	描述
--name、-n	string	否	元素名称/文本
--role、-r	string	否	元素角色
--app、-a	string	否	按应用名称筛选
--right	flag	否	右键点击
--double	flag	否	双击
--verify	flag	否	点击前通过 OCR 验证

click-element 至少需要一个选择器：--name 或 --role。 使用 --verify 时，必须能够使用 OCR，并且必须提供文本（通常通过 --name 提供）。

返回：

{
  "clicked": {
    "element": { "name": "Next", "..." },
    "x": 450,
    "y": 315,
    "button": "left",
    "double": false
  }
}

---

wait-for

等待元素或文本出现（带超时和指数退避）。

python3 scripts/desktop.py wait-for --name "Success" --timeout 30
python3 scripts/desktop.py wait-for --text "Transaction complete" --timeout 60
python3 scripts/desktop.py wait-for --name "Loading" --gone --timeout 30

参数	类型	必填	描述
--name、-n	string	否	元素名称（AT-SPI + OCR）
--role、-r	string	否	元素角色（仅 AT-SPI）
--app、-a	string	否	应用筛选条件
--text、-t	string	否	要查找的文本（仅 OCR）
--exact	flag	否	文本完全匹配
--gone	flag	否	等待元素消失
--timeout	float	否	超时时间，单位为秒（默认：30）

单次调用请使用 --text 或元素选择器（--name、--role、--app）之一，不要同时使用两者。 等待元素时（无论是否使用 --gone），至少提供 --name 或 --role 之一。

返回：

{ "found": { "name": "Success", "..." } }
// or
{ "gone": true, "name": "Loading" }
// or
{ "error": "Element not found within 30s", "timeout": true }

---

list-elements

列出所有交互式元素（按钮、输入框、链接等）。

python3 scripts/desktop.py list-elements [--app Firefox] [--role button]

参数	类型	必填	描述
--app、-a	string	否	按应用名称筛选
--role、-r	string	否	按角色筛选
--include-hidden	flag	否	包含隐藏元素
--max-results	int	否	最大结果数（默认：100）

返回：

{
  "elements": [
    { "name": "Sign In", "role": "push button", "..." },
    { "name": "Email", "role": "entry", "..." }
  ],
  "count": 2
}

---

status

检查 AT-SPI 和 OCR 是否可用。

python3 scripts/desktop.py status

返回：

{
  "atspi": {
    "available": true,
    "applications": ["Firefox", "gnome-calculator"]
  },
  "ocr": { "available": true },
  "display": ":10.0"
}

---

原始命令

这些基于坐标的命令仍然可用：

命令	描述
screenshot [--output PATH]	截取屏幕截图
click X Y [--right] [--double]	点击指定坐标
type "TEXT" [--type-delay MS]	输入文本
key "KEYS"	按下组合键
move X Y	移动鼠标
active	获取活动窗口信息
find-window "NAME"	按名称查找窗口
focus "NAME"	按名称聚焦窗口
position	获取鼠标位置
windows	列出所有窗口

---

工作流示例

MetaMask 交易（语义操作）

# Wait for and click Confirm button
python3 scripts/desktop.py wait-for --name "Confirm" --role button --timeout 30
python3 scripts/desktop.py click-element --name "Confirm" --role button

# Wait for success message
python3 scripts/desktop.py wait-for --text "Transaction submitted" --timeout 60

Phantom 钱包导入（语义操作）

# Click "I have an existing wallet"
python3 scripts/desktop.py click-element --name "I already have a wallet"

# Wait for seed phrase input
python3 scripts/desktop.py wait-for --role entry --timeout 10

# Type seed phrase
python3 scripts/desktop.py type "word1 word2 word3..."

# Click Import
python3 scripts/desktop.py click-element --name "Import"

混合方式（语义操作 + 坐标）

# Use semantic for known buttons
python3 scripts/desktop.py click-element --name "Settings"

# Fall back to coordinates for unlabeled icons
python3 scripts/desktop.py screenshot --output /tmp/screen.png
# (analyze screenshot to get coordinates)
python3 scripts/desktop.py click 850 120

---

提示

1. 优先使用语义命令——click-element 和 wait-for 比基于坐标的命令更可靠
2. 先检查状态——运行 status，确认 AT-SPI 和 OCR 可用
3. 使用 --role 提高精确度——区分名称相同的按钮和文本
4. 回退到 OCR——如果 AT-SPI 未提供某个元素，find-text 会使用 OCR
5. 等待而不是休眠——wait-for 比固定延迟更可靠
6. 对关键点击使用 --verify——点击前添加 OCR 验证