Desktop Control

デスクトップ操作スキル

このスキルでは、PyAutoGUI を通じて包括的なデスクトップ自動化機能を提供します。AI エージェントは、マウスやキーボードを操作し、スクリーンショットを撮影して、デスクトップ環境を操作できます。

このスキルの使い方

AI エージェントは、uvx desktop-agent CLI を使用してデスクトップ自動化コマンドを実行できます。

コマンドの構成

すべてのコマンドは次の形式に従います。

uvx desktop-agent <category> <command> [arguments] [options]

カテゴリ：

• mouse - マウス操作
• keyboard - キーボード入力
• screen - スクリーンショットと画面分析
• message - ユーザーダイアログ
• app - アプリケーション操作（起動、フォーカス、ウィンドウ一覧）

利用可能なコマンド

🖱️ マウス操作（mouse）

カーソルの移動とクリックを操作します。

# Move cursor to coordinates
uvx desktop-agent mouse move <x> <y> [--duration SECONDS]

# Click at current position or specific coordinates
uvx desktop-agent mouse click [x] [y] [--button left|right|middle] [--clicks N]

# Specialized clicks
uvx desktop-agent mouse double-click [x] [y]
uvx desktop-agent mouse right-click [x] [y]
uvx desktop-agent mouse middle-click [x] [y]

# Drag to coordinates
uvx desktop-agent mouse drag <x> <y> [--duration SECONDS] [--button BUTTON]

# Scroll (positive=up, negative=down)
uvx desktop-agent mouse scroll <clicks> [x] [y]

# Get current mouse position
uvx desktop-agent mouse position

例：

# Move to center of 1920x1080 screen
uvx desktop-agent mouse move 960 540 --duration 0.5

# Right-click at specific location
uvx desktop-agent mouse right-click 500 300

# Scroll down 5 clicks
uvx desktop-agent mouse scroll -5

⌨️ キーボード操作（keyboard）

テキストを入力し、キーボードショートカットを実行します。

# Type text
uvx desktop-agent keyboard write "<text>" [--interval SECONDS]

# Press keys
uvx desktop-agent keyboard press <key> [--presses N] [--interval SECONDS]

# Execute hotkey combination (comma-separated)
uvx desktop-agent keyboard hotkey "<key1>,<key2>,..."

# Hold/release keys
uvx desktop-agent keyboard keydown <key>
uvx desktop-agent keyboard keyup <key>

例：

# Type text with natural delay
uvx desktop-agent keyboard write "Hello World" --interval 0.05

# Copy selected text
uvx desktop-agent keyboard hotkey "ctrl,c"

# Open Task Manager
uvx desktop-agent keyboard hotkey "ctrl,shift,esc"

# Press Enter 3 times
uvx desktop-agent keyboard press enter --presses 3

一般的なキー名：

• 修飾キー：ctrl、shift、alt、win
• 特殊キー：enter、tab、esc、space、backspace、delete
• ファンクションキー：f1 から f12
• 矢印キー：up、down、left、right

🖼️ 画面とスクリーンショット（screen）

スクリーンショットを撮影し、画面の内容を分析します。特定のウィンドウを対象にすることもできます。

# Take screenshot
uvx desktop-agent screen screenshot <filename> [--region "x,y,width,height"] [--window <title>] [--active]

# Locate image on screen or within window
uvx desktop-agent screen locate <image_path> [--confidence 0.0-1.0] [--window <title>] [--active]
uvx desktop-agent screen locate-center <image_path> [--confidence 0.0-1.0] [--window <title>] [--active]

# Locate text using OCR within window
uvx desktop-agent screen locate-text-coordinates <text> [--window <title>] [--active]
uvx desktop-agent screen read-all-text [--window <title>] [--active]

# Utility commands
uvx desktop-agent screen pixel <x> <y>
uvx desktop-agent screen size
uvx desktop-agent screen on-screen <x> <y>

例：

# Screenshot of active window
uvx desktop-agent screen screenshot active.png --active

# Screenshot of a specific application
uvx desktop-agent screen screenshot chrome.png --window "Google Chrome"

# Locate image within Notepad
uvx desktop-agent screen locate-center button.png --window "Notepad"

💬 メッセージダイアログ（message）

ユーザーとの対話に使用するダイアログを表示します。

# Show alert
uvx desktop-agent message alert "<text>" [--title TITLE] [--button BUTTON]

# Show confirmation dialog
uvx desktop-agent message confirm "<text>" [--title TITLE] [--buttons "OK,Cancel"]

# Prompt for input
uvx desktop-agent message prompt "<text>" [--title TITLE] [--default TEXT]

# Password input
uvx desktop-agent message password "<text>" [--title TITLE] [--mask CHAR]

例：

# Simple alert
uvx desktop-agent message alert "Task completed!"

# Get user confirmation
uvx desktop-agent message confirm "Continue with operation?"

# Ask for user input
uvx desktop-agent message prompt "Enter your name:"

📱 アプリケーション操作（app）

Windows、macOS、Linux 上のアプリケーションを操作します。

# Open an application by name
uvx desktop-agent app open <name> [--arg ARGS...]

# Focus on a window by title/name
uvx desktop-agent app focus <name>

# List all visible windows
uvx desktop-agent app list

例：

# Windows: Open Notepad
uvx desktop-agent app open notepad

# Windows: Open Chrome with a URL
uvx desktop-agent app open "chrome" --arg "https://google.com"

# macOS: Open Safari
uvx desktop-agent app open "Safari"

# Focus on a specific window
uvx desktop-agent app focus "Untitled - Notepad"

# List all open windows
uvx desktop-agent app list

一般的な自動化ワークフロー

ワークフロー 1：アプリケーションを開いて入力する

# Open notepad directly (cross-platform)
uvx desktop-agent app open notepad

# Wait for app to open, then focus it
uvx desktop-agent app focus notepad

# Type some text
uvx desktop-agent keyboard write "Hello from Desktop Skill!"

ワークフロー 2：スクリーンショットと分析

# Get screen size first
uvx desktop-agent screen size

# Take full screenshot
uvx desktop-agent screen screenshot current_screen.png

# Check if specific UI element is visible
uvx desktop-agent screen locate save_button.png

ワークフロー 3：フォームへの入力

# Click first field
uvx desktop-agent mouse click 300 200

# Fill field
uvx desktop-agent keyboard write "John Doe"

# Tab to next field
uvx desktop-agent keyboard press tab

# Fill second field
uvx desktop-agent keyboard write "[email protected]"

# Submit form (Enter)
uvx desktop-agent keyboard press enter

ワークフロー 4：コピー／貼り付け操作

# Select all text
uvx desktop-agent keyboard hotkey "ctrl,a"

# Copy
uvx desktop-agent keyboard hotkey "ctrl,c"

# Click destination
uvx desktop-agent mouse click 500 600

# Paste
uvx desktop-agent keyboard hotkey "ctrl,v"

安全上の注意事項

このスキルを使用する際、AI エージェントは次の点に注意してください。

1. 座標を確認する：クリックする前に screen size と on-screen を使用します
2. 待ち時間を追加する：UI の応答性を保つため、コマンドの間に適切な待ち時間を挿入します
3. 画像を検証する：locate コマンドを使用する前に、画像ファイルが存在することを確認します
4. 失敗に対処する：ウィンドウが切り替わったり、要素が移動したりすると、コマンドが失敗することがあります
5. ユーザーの安全を守る：破壊的な操作は、必ず message confirm を使ってユーザーに確認します

トラブルシューティング

PyAutoGUI のフェイルセーフ

PyAutoGUI にはフェイルセーフ機能があります。マウスを画面の隅に移動すると、操作が中断されます。これは安全機能です。

画像が見つからない

screen locate を使用する場合は、次の点を確認してください。

• 画像ファイルが存在し、パスが正しいこと
• --confidence を調整すること（0.7～0.9 をお試しください）
• 画像が画面上の表示と正確に一致していること（解像度、色など）

ヘルプの表示

# Show all available commands
uvx desktop-agent --help

# Show commands for specific category
uvx desktop-agent mouse --help
uvx desktop-agent keyboard --help
uvx desktop-agent screen --help
uvx desktop-agent message --help

# Show help for specific command
uvx desktop-agent mouse move --help

AI エージェント向けの連携のヒント

1. 絶対座標を使用する場合は、まず画面サイズを確認します
2. 可能な場合は相対位置を使用します（例：現在位置を取得して、オフセットを計算する）
3. 複雑なワークフローではコマンドを組み合わせます
4. 実行前に検証します（例：画像が画面上に存在するかを確認する）
5. 重要な操作については、メッセージダイアログを使ってユーザーに知らせます
6. エラーに適切に対処します。UI の状態が変わると、コマンドが失敗することがあります

パフォーマンスに関する注意事項

• --duration を指定したマウス移動はアニメーション表示されるため、完了まで時間がかかります
• 大きな画面では画像の検索（locate）に時間がかかることがあります。可能な場合は範囲を指定してください
• キーボードコマンドは通常、高速です（100 ミリ秒未満）
• スクリーンショットの処理時間は、画面の解像度と範囲のサイズに左右されます

出力形式

すべてのコマンドは、AI エージェントがプログラムから利用するのに適した、構造化 JSON をデフォルトで出力します。

uvx desktop-agent mouse position
# Output: {"success": true, "command": "mouse.position", "timestamp": "2026-01-31T10:00:00Z", "duration_ms": 5, "data": {"position": {"x": 960, "y": 540}}}

レスポンススキーマ

すべての JSON レスポンスは次のスキーマに従います。

{
  "success": true,
  "command": "category.command",
  "timestamp": "2026-01-31T10:00:00Z",
  "duration_ms": 150,
  "data": { ... },
  "error": null
}

エラーレスポンススキーマ

{
  "success": false,
  "command": "category.command",
  "timestamp": "2026-01-31T10:00:00Z",
  "duration_ms": 50,
  "data": null,
  "error": {
    "code": "image_not_found",
    "message": "Image file 'button.png' not found",
    "details": {},
    "recoverable": true
  }
}

エラーコード

コード	説明
success	コマンドは成功しました
invalid_argument	コマンドの引数が無効です
coordinates_out_of_bounds	座標が画面の範囲外です
image_not_found	画像ファイルが見つからないか、画面上にありません
window_not_found	対象のウィンドウが見つかりません
ocr_failed	OCR 操作に失敗しました
application_not_found	アプリケーションが見つかりません
permission_denied	アクセスが拒否されました
platform_not_supported	プラットフォームはサポートされていません
timeout	操作がタイムアウトしました
unknown_error	不明なエラーです

マウスの移動：

uvx desktop-agent mouse move 960 540

{"success": true, "command": "mouse.move", "timestamp": "...", "duration_ms": 150, "data": {"x": 960, "y": 540, "duration": 0}, "error": null}

画面サイズ：

uvx desktop-agent screen size

{"success": true, "command": "screen.size", "timestamp": "...", "duration_ms": 5, "data": {"size": {"width": 1920, "height": 1080}}, "error": null}

画像の検索：

uvx desktop-agent screen locate button.png

{"success": true, "command": "screen.locate", "timestamp": "...", "duration_ms": 250, "data": {"image_found": true, "bounding_box": {"left": 100, "top": 200, "width": 50, "height": 30, "center_x": 125, "center_y": 215}}, "error": null}

ウィンドウの一覧表示：

uvx desktop-agent app list

{"success": true, "command": "app.list", "timestamp": "...", "duration_ms": 100, "data": {"windows": ["Untitled - Notepad", "Google Chrome", "Visual Studio Code"]}, "error": null}

エラーの例：

uvx desktop-agent screen locate missing.png

{"success": false, "command": "screen.locate", "timestamp": "...", "duration_ms": 50, "data": null, "error": {"code": "image_not_found", "message": "Image file 'missing.png' not found", "details": {}, "recoverable": true}}

AI エージェント向け効果的な使用ガイド

このセクションでは、最適なコマンドシーケンスとベストプラクティスを用いて、このスキルを効果的に使用する方法を AI エージェントに説明します。

🎯 基本戦略：まず観察し、その後に操作する

操作を実行する前に、必ず現在の状態を把握してください。これにより、間違った座標をクリックしたり、誤ったウィンドウに入力したりするのを防げます。

推奨される初期シーケンス：

# 1. Get screen dimensions to understand your workspace
uvx desktop-agent screen size
uvx desktop-agent app list
uvx desktop-agent mouse position

📋 タスク別の推奨コマンドシーケンス

アプリケーションを開いて操作する

# ✅ CORRECT: Open, wait, verify, then interact
uvx desktop-agent app open notepad              # Step 1: Open app
uvx desktop-agent app list
uvx desktop-agent app focus "Notepad"
uvx desktop-agent keyboard write "Hello World"  # Step 4: Now safe to type

# ❌ WRONG: Type immediately without verification
uvx desktop-agent app open notepad
uvx desktop-agent keyboard write "Hello World"  # May type in wrong window!

UI 要素を見つけてクリックする（画像ベース）

# ✅ CORRECT: Locate first, click if found
uvx desktop-agent screen locate-center button.png --confidence 0.8
# Check if success=true and coordinates are valid
uvx desktop-agent mouse click 125 215  # Use returned coordinates

# ❌ WRONG: Click without verifying element exists
uvx desktop-agent mouse click 125 215  # Might click wrong area!

UI 要素を見つけてクリックする（OCR によるテキストベース）

# ✅ CORRECT: Read screen text, then locate specific text
uvx desktop-agent screen read-all-text --active
uvx desktop-agent screen locate-text-coordinates "Save" --active
# Use returned coordinates to click

# For window-specific OCR:
uvx desktop-agent screen locate-text-coordinates "OK" --window "Dialog Title"

複数のフィールドがあるフォームに入力する

# ✅ CORRECT: Click each field explicitly before typing
uvx desktop-agent mouse click 300 200           # Click first field
uvx desktop-agent keyboard write "John Doe"
uvx desktop-agent mouse click 300 250           # Click second field (more reliable)
uvx desktop-agent keyboard write "[email protected]"
uvx desktop-agent mouse click 300 300           # Click third field
uvx desktop-agent keyboard write "555-1234"

# OR use Tab navigation (less reliable if field order changes)
uvx desktop-agent mouse click 300 200
uvx desktop-agent keyboard write "John Doe"
uvx desktop-agent keyboard press tab
uvx desktop-agent keyboard write "[email protected]"
uvx desktop-agent keyboard press tab
uvx desktop-agent keyboard write "555-1234"
uvx desktop-agent keyboard press enter          # Submit

分析用に対象を絞ったスクリーンショットを撮る

# ✅ CORRECT: Screenshot specific windows for faster processing
uvx desktop-agent app list --json                           # Find exact window title
uvx desktop-agent screen screenshot app.png --window "Google Chrome"

# For active window only
uvx desktop-agent screen screenshot active.png --active

# Full screen only when necessary (slower, larger file)
uvx desktop-agent screen size
uvx desktop-agent screen screenshot full.png

安全なドラッグ＆ドロップ

# ✅ CORRECT: Move to start, verify position, then drag
uvx desktop-agent mouse move 100 200                 # Move to source
uvx desktop-agent mouse position              # Verify position
uvx desktop-agent mouse drag 500 400 --duration 0.5  # Drag to destination

# For precision, use slower duration
uvx desktop-agent mouse drag 500 400 --duration 1.0

🔄 エラーからの復旧パターン

ウィンドウが見つからない場合

# Pattern: List windows, find closest match, retry
uvx desktop-agent app focus "Chrome"             # Fails with window_not_found
uvx desktop-agent app list                # See actual window titles
# Output shows: "Google Chrome - My Page"
uvx desktop-agent app focus "Google Chrome"      # Use correct title

画像が見つからない場合

# Pattern: Adjust confidence or take new screenshot
uvx desktop-agent screen locate button.png --confidence 0.9
uvx desktop-agent screen locate button.png --confidence 0.7
# If still failing, capture current state for analysis
uvx desktop-agent screen screenshot current.png --active

クリックが外れたように見える場合

# Pattern: Verify coordinates are on screen
uvx desktop-agent screen size             # Get screen bounds
uvx desktop-agent screen on-screen 1500 900      # Check if coords are valid
uvx desktop-agent mouse move 1500 900            # Move first to visualize
uvx desktop-agent mouse click                    # Then click at current position

⚡ パフォーマンスの最適化

スクリーンショットを最小限にする

# ✅ GOOD: Screenshot only the region you need
uvx desktop-agent screen screenshot button_area.png --region "100,200,200,100"

# ✅ GOOD: Screenshot specific window instead of full screen  
uvx desktop-agent screen screenshot chrome.png --window "Google Chrome"

# ❌ SLOW: Full screen capture when you only need a small area
uvx desktop-agent screen screenshot full.png

キーボード入力をまとめて行う

# ✅ FASTER: Write entire text at once
uvx desktop-agent keyboard write "This is a complete sentence with all the text."

# ❌ SLOWER: Multiple write commands
uvx desktop-agent keyboard write "This is "
uvx desktop-agent keyboard write "a complete "
uvx desktop-agent keyboard write "sentence."

可能な場合はマウスよりホットキーを使う

# ✅ FASTER: Use keyboard shortcuts
uvx desktop-agent keyboard hotkey "ctrl,s"       # Save
uvx desktop-agent keyboard hotkey "ctrl,a"       # Select all
uvx desktop-agent keyboard hotkey "ctrl,shift,s" # Save as

# ❌ SLOWER: Navigate menu with mouse
uvx desktop-agent mouse click 50 30              # Click File menu
uvx desktop-agent mouse click 60 80              # Click Save option

🛡️ 防御的プログラミングのパターン

重要な操作は必ず検証する

# Before destructive action, confirm with user
uvx desktop-agent message confirm "This will delete all files. Continue?" --title "Warning"
# Check output: if "Cancel" was clicked, abort operation

安定した解析のために JSON モードを使う

# ✅ RELIABLE: Parse structured JSON output
uvx desktop-agent screen locate button.png
# Parse: {"success": true, "data": {"center_x": 125, "center_y": 215}}

# ❌ FRAGILE: Parse text output
uvx desktop-agent screen locate button.png
# Parse: "Found at: Box(left=100, top=200, width=50, height=30)"

複数ステップの操作を行う前に検証する

# Multi-step file operation with validation
uvx desktop-agent app list
uvx desktop-agent screen locate-text-coordinates "File" --active
uvx desktop-agent mouse click <returned_x> <returned_y>
uvx desktop-agent screen locate-text-coordinates "Save As" --active
uvx desktop-agent mouse click <returned_x> <returned_y>

🎮 プラットフォーム固有の考慮事項

Windows

# Common Windows shortcuts
uvx desktop-agent keyboard hotkey "win,d"        # Show desktop
uvx desktop-agent keyboard hotkey "win,e"        # Open Explorer
uvx desktop-agent keyboard hotkey "alt,tab"      # Switch windows
uvx desktop-agent keyboard hotkey "win,r"        # Run dialog

# Open apps by name
uvx desktop-agent app open notepad
uvx desktop-agent app open calc
uvx desktop-agent app open mspaint

macOS

# Common macOS shortcuts (use 'command' for Cmd key)
uvx desktop-agent keyboard hotkey "command,space"   # Spotlight
uvx desktop-agent keyboard hotkey "command,tab"     # App switcher
uvx desktop-agent keyboard hotkey "command,q"       # Quit app
uvx desktop-agent keyboard hotkey "command,shift,3" # Screenshot

# Open apps
uvx desktop-agent app open "Safari"
uvx desktop-agent app open "TextEdit"

Linux

# Open apps (uses xdg-open or direct command)
uvx desktop-agent app open firefox
uvx desktop-agent app open gedit

# Common shortcuts may vary by DE
uvx desktop-agent keyboard hotkey "alt,f2"       # Run dialog (many DEs)

📊 適切なコマンドを選ぶための判断フロー

 Want to interact with an app?
├── App not running → `app open <name>`
├── App running but not focused → `app focus <name>` 
└── Need to verify windows → `app list`

Want to find a UI element?
├── Have reference image → `screen locate-center <image>`
├── Know the text label → `screen locate-text-coordinates "<text>"`
└── Need to see all text → `screen read-all-text --active`

Want to click something?
├── Know exact coordinates → `mouse click <x> <y>`
├── Need to find first → Use locate commands above, then click returned coords
└── Not sure if on screen → `screen on-screen <x> <y>` first

Want to type something?
├── Regular text → `keyboard write "<text>"`
├── Keyboard shortcut → `keyboard hotkey "<key1>,<key2>"`
├── Single key press → `keyboard press <key>`
└── Multiple of same key → `keyboard press <key> --presses N`

AI エージェント向け統合のヒント

1. 絶対座標を使う場合は、必ず最初に画面サイズを確認してください
2. 可能な場合は相対位置指定を使ってください（例：現在位置を取得し、オフセットを計算する）
3. 複雑なワークフローではコマンドを組み合わせてください
4. 実行前に検証してください（例：画像が画面上にあるか確認する）
5. 重要な操作ではメッセージダイアログを使ってユーザーにフィードバックを提供してください
6. エラーを適切に処理してください - UI の状態が変化すると、コマンドが失敗することがあります