desktop-control

スキル：デスクトップ操作

使用する場面

ユーザーから次のような依頼があった場合に、このスキルを使用します。

• 画面上の場所をクリックする
• マウスを指定した位置に移動する
• アプリケーションにテキストを入力する
• キーボードショートカットやホットキーを押す
• 現在の画面に表示されている内容を読み取る（アクセシビリティツリー）
• 最前面のウィンドウに関する情報を取得する
• デスクトップ操作を自動化する
• コンピューターを操作する（マウス、キーボード、画面）
• アプリケーション内で上下にスクロールする
• 要素をドラッグ＆ドロップする

重要：このスキルを使用するには、ターミナル／IDE にアクセシビリティの権限が必要です。macOS では、「システム設定」>「プライバシーとセキュリティ」>「アクセシビリティ」を開き、実行中のアプリケーションを有効にしてください。

同梱スクリプト

スクリプト	種類	説明
scripts/mouse.py	Python	マウスの移動、クリック、ドラッグ、スクロール
scripts/keyboard.py	Python	テキスト入力、キー入力、ホットキー
scripts/screen.py	Python	画面情報、キャプチャ、アクセシビリティツリーの読み取り

すべてのスクリプトは、必要に応じて pyautogui を自動的にインストールします。

---

マウス操作

入力パラメーター

パラメーター	必須	説明	例
action	はい	move、click、doubleclick、rightclick、drag、scroll	click
x	ほとんどの場合	X 座標（左端からのピクセル数）	500
y	ほとんどの場合	Y 座標（上端からのピクセル数）	300
button	いいえ	マウスボタン：left（デフォルト）、right、middle	left
to_x	ドラッグ時	移動先の X 座標	700
to_y	ドラッグ時	移動先の Y 座標	400
amount	スクロール時	スクロール量（正の値＝上、負の値＝下）	-3

スクリプトの使用方法

# Move mouse
python3 skills/desktop-control/scripts/mouse.py move --x 500 --y 300

# Click at position
python3 skills/desktop-control/scripts/mouse.py click --x 500 --y 300

# Double click
python3 skills/desktop-control/scripts/mouse.py doubleclick --x 500 --y 300

# Right click
python3 skills/desktop-control/scripts/mouse.py rightclick --x 500 --y 300

# Drag from one position to another
python3 skills/desktop-control/scripts/mouse.py drag --x 100 --y 100 --to-x 500 --to-y 500

# Scroll down 3 clicks
python3 skills/desktop-control/scripts/mouse.py scroll --amount -3

# Scroll up 5 clicks at specific position
python3 skills/desktop-control/scripts/mouse.py scroll --x 500 --y 300 --amount 5

# Get current mouse position
python3 skills/desktop-control/scripts/mouse.py position

---

キーボード操作

入力パラメーター

パラメーター	必須	説明	例
action	はい	type、press、hotkey	type
text	type の場合	入力するテキスト	Hello World
key	press の場合	押すキー	enter
keys	hotkey の場合	プラス記号で区切ったキーの組み合わせ	command+c
interval	いいえ	キー入力間の遅延時間（秒、デフォルト：0.02）	0.05

スクリプトの使用方法

# Type text
python3 skills/desktop-control/scripts/keyboard.py type --text "Hello World"

# Type slowly
python3 skills/desktop-control/scripts/keyboard.py type --text "Hello" --interval 0.1

# Press a single key
python3 skills/desktop-control/scripts/keyboard.py press --key enter
python3 skills/desktop-control/scripts/keyboard.py press --key tab
python3 skills/desktop-control/scripts/keyboard.py press --key escape

# Keyboard shortcuts (hotkeys)
python3 skills/desktop-control/scripts/keyboard.py hotkey --keys "command+c"
python3 skills/desktop-control/scripts/keyboard.py hotkey --keys "command+shift+s"
python3 skills/desktop-control/scripts/keyboard.py hotkey --keys "alt+tab"
python3 skills/desktop-control/scripts/keyboard.py hotkey --keys "command+space"

よく使うキー名

enter、return、tab、space、backspace、delete、escape、up、down、left、right、home、end、pageup、pagedown、f1-f12、command、ctrl、alt、shift、capslock

---

画面の読み取り

入力パラメーター

パラメーター	必須	説明	例
action	はい	info、capture、read-ui	read-ui
output	capture の場合	スクリーンショットの出力先	/tmp/screen.png
x、y、width、height	キャプチャ領域の場合	キャプチャする領域

スクリプトの使用方法

# Get screen size and mouse position
python3 skills/desktop-control/scripts/screen.py info

# Take a screenshot
python3 skills/desktop-control/scripts/screen.py capture --output /tmp/screen.png

# Capture a specific region
python3 skills/desktop-control/scripts/screen.py capture --x 0 --y 0 --width 800 --height 600 --output /tmp/region.png

# Read the accessibility tree of the frontmost application (MOST USEFUL)
python3 skills/desktop-control/scripts/screen.py read-ui

# Read accessibility tree with depth limit
python3 skills/desktop-control/scripts/screen.py read-ui --depth 3

read-ui コマンドは AppleScript を使用して最前面のアプリケーションのアクセシビリティツリーを読み取り、ウィンドウタイトル、ボタン、テキストフィールド、メニュー、その他の UI 要素を返します。これは、操作する前に画面の内容を把握するための主な方法です。

---

一般的なワークフロー

1. 画面を読み取ることで、何が表示されているかを把握します。

   python3 skills/desktop-control/scripts/screen.py read-ui
   

2. アクセシビリティツリーの出力から対象を特定します。
3. マウスやキーボードを使って操作します。

   python3 skills/desktop-control/scripts/mouse.py click --x 500 --y 300
   python3 skills/desktop-control/scripts/keyboard.py type --text "search query"
   python3 skills/desktop-control/scripts/keyboard.py press --key enter
   

4. 画面をもう一度読み取って確認します。

例

click on the search bar
type "hello" into the text field
press command+s to save
what's on the screen right now
read the UI elements of the current window
move the mouse to the center of the screen
scroll down in this window