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

OCR フォールバックを使って、AT-SPI 経由で UI 要素を検索します。

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

パラメーター	種類	必須	説明
--name、-n	文字列	いいえ	検索する要素の名前／テキスト
--role、-r	文字列	いいえ	要素のロール（button、entry など）
--app、-a	文字列	いいえ	アプリケーション名のフィルター
--all	フラグ	いいえ	一致する要素をすべて検索
--clickable	フラグ	いいえ	クリック可能な要素のみを対象にする
--max-results	整数	いいえ	結果の最大数（デフォルト：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	文字列	はい	検索するテキスト
--exact	フラグ	いいえ	完全一致を必須にする
--case-sensitive	フラグ	いいえ	大文字と小文字を区別する
--all	フラグ	いいえ	一致箇所をすべて検索
--max-results	整数	いいえ	結果の最大数（デフォルト：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	文字列	いいえ	要素の名前／テキスト
--role、-r	文字列	いいえ	要素のロール
--app、-a	文字列	いいえ	アプリケーション名のフィルター
--right	フラグ	いいえ	右クリック
--double	フラグ	いいえ	ダブルクリック
--verify	フラグ	いいえ	クリック前に OCR で検証

click-element には、少なくとも 1 つのセレクター（--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	文字列	いいえ	要素名（AT-SPI と OCR）
--role、-r	文字列	いいえ	要素のロール（AT-SPI のみ）
--app、-a	文字列	いいえ	アプリケーションのフィルター
--text、-t	文字列	いいえ	検索するテキスト（OCR のみ）
--exact	フラグ	いいえ	テキストの完全一致
--gone	フラグ	いいえ	要素が消えるまで待機
--timeout	浮動小数点数	いいえ	タイムアウト（秒、デフォルト：30）

1 回の呼び出しでは、--text または要素セレクター（--name、--role、--app）のいずれかを使用し、両方は使用しないでください。 要素の待機では、--gone の有無にかかわらず、--name または --role の少なくとも 1 つを指定してください。

戻り値：

{ "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	文字列	いいえ	アプリケーション名のフィルター
--role、-r	文字列	いいえ	ロールでフィルター
--include-hidden	フラグ	いいえ	非表示の要素を含める
--max-results	整数	いいえ	結果の最大数（デフォルト：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 Wallet のインポート（セマンティック）

# 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. sleep ではなく待機する - wait-for は固定の遅延よりも信頼性が高いです
6. 重要なクリックには --verify を使う - クリック前に OCR による検証を追加します