AI Skills
Desktop Control

Desktop Control

控制滑鼠、鍵盤和螢幕，用於桌面自動化任務

1星標
0分支
更新於 2026/6/17
獲取技能源代碼

相關技能

ui-to-vue24萬brandkit9.3萬store-data-structures8.2萬
SKILL.md
唯讀
名稱
Desktop Control
描述

控制滑鼠、鍵盤和螢幕，用於桌面自動化任務

Desktop Control 技能

此技能透過 PyAutoGUI 提供完整的桌面自動化功能，讓 AI 代理能夠控制滑鼠、鍵盤、擷取螢幕畫面，並與桌面環境互動。

如何使用此技能

作為 AI 代理，您可以使用 uvx desktop-agent CLI 來呼叫桌面自動化指令。

指令結構

所有指令遵循以下模式：

uvx desktop-agent <類別> <指令> [參數] [選項]

類別：

  • mouse - 滑鼠控制
  • keyboard - 鍵盤輸入
  • screen - 螢幕擷取與分析
  • message - 使用者對話框
  • app - 應用程式控制（開啟、聚焦、列出視窗）

可用指令

🖱️ 滑鼠控制 (mouse)

控制游標移動與點擊。

# 移動游標到指定座標
uvx desktop-agent mouse move <x> <y> [--duration SECONDS]

# 在目前位置或指定座標點擊
uvx desktop-agent mouse click [x] [y] [--button left|right|middle] [--clicks N]

# 特殊點擊
uvx desktop-agent mouse double-click [x] [y]
uvx desktop-agent mouse right-click [x] [y]
uvx desktop-agent mouse middle-click [x] [y]

# 拖曳到指定座標
uvx desktop-agent mouse drag <x> <y> [--duration SECONDS] [--button BUTTON]

# 滾輪（正數=向上，負數=向下）
uvx desktop-agent mouse scroll <clicks> [x] [y]

# 取得目前滑鼠位置
uvx desktop-agent mouse position

範例：

# 移動到 1920x1080 螢幕中央
uvx desktop-agent mouse move 960 540 --duration 0.5

# 在指定位置按右鍵
uvx desktop-agent mouse right-click 500 300

# 向下滾動 5 格
uvx desktop-agent mouse scroll -5

⌨️ 鍵盤控制 (keyboard)

輸入文字與執行鍵盤快捷鍵。

# 輸入文字
uvx desktop-agent keyboard write "<text>" [--interval SECONDS]

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

# 執行組合鍵（逗號分隔）
uvx desktop-agent keyboard hotkey "<key1>,<key2>,..."

# 按住/放開按鍵
uvx desktop-agent keyboard keydown <key>
uvx desktop-agent keyboard keyup <key>

範例：

# 以自然延遲輸入文字
uvx desktop-agent keyboard write "Hello World" --interval 0.05

# 複製選取文字
uvx desktop-agent keyboard hotkey "ctrl,c"

# 開啟工作管理員
uvx desktop-agent keyboard hotkey "ctrl,shift,esc"

# 按 Enter 三次
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)

擷取螢幕畫面並分析螢幕內容。支援鎖定特定視窗。

# 擷取螢幕畫面
uvx desktop-agent screen screenshot <filename> [--region "x,y,width,height"] [--window <title>] [--active]

# 在螢幕或視窗中尋找圖片
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]

# 使用 OCR 在視窗中尋找文字座標
uvx desktop-agent screen locate-text-coordinates <text> [--window <title>] [--active]
uvx desktop-agent screen read-all-text [--window <title>] [--active]

# 工具指令
uvx desktop-agent screen pixel <x> <y>
uvx desktop-agent screen size
uvx desktop-agent screen on-screen <x> <y>

範例：

# 擷取作用中視窗
uvx desktop-agent screen screenshot active.png --active

# 擷取特定應用程式
uvx desktop-agent screen screenshot chrome.png --window "Google Chrome"

# 在記事本中尋找圖片
uvx desktop-agent screen locate-center button.png --window "Notepad"

💬 訊息對話框 (message)

顯示使用者互動對話框。

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

# 顯示確認對話框
uvx desktop-agent message confirm "<text>" [--title TITLE] [--buttons "OK,Cancel"]

# 提示輸入
uvx desktop-agent message prompt "<text>" [--title TITLE] [--default TEXT]

# 密碼輸入
uvx desktop-agent message password "<text>" [--title TITLE] [--mask CHAR]

範例：

# 簡單警示
uvx desktop-agent message alert "Task completed!"

# 取得使用者確認
uvx desktop-agent message confirm "Continue with operation?"

# 詢問使用者輸入
uvx desktop-agent message prompt "Enter your name:"

📱 應用程式控制 (app)

在 Windows、macOS 和 Linux 上控制應用程式。

# 依名稱開啟應用程式
uvx desktop-agent app open <name> [--arg ARGS...]

# 依標題/名稱聚焦視窗
uvx desktop-agent app focus <name>

# 列出所有可見視窗
uvx desktop-agent app list

範例：

# Windows：開啟記事本
uvx desktop-agent app open notepad

# Windows：開啟 Chrome 並帶入網址
uvx desktop-agent app open "chrome" --arg "https://google.com"

# macOS：開啟 Safari
uvx desktop-agent app open "Safari"

# 聚焦特定視窗
uvx desktop-agent app focus "Untitled - Notepad"

# 列出所有開啟的視窗
uvx desktop-agent app list

常見自動化工作流程

工作流程 1：開啟應用程式並輸入文字

# 直接開啟記事本（跨平台）
uvx desktop-agent app open notepad

# 等待應用程式開啟，然後聚焦
uvx desktop-agent app focus notepad

# 輸入一些文字
uvx desktop-agent keyboard write "Hello from Desktop Skill!"

工作流程 2：擷圖 + 分析

# 先取得螢幕尺寸
uvx desktop-agent screen size

# 擷取全螢幕
uvx desktop-agent screen screenshot current_screen.png

# 檢查特定 UI 元素是否可見
uvx desktop-agent screen locate save_button.png

工作流程 3：填寫表單

# 點擊第一個欄位
uvx desktop-agent mouse click 300 200

# 填寫欄位
uvx desktop-agent keyboard write "John Doe"

# Tab 到下一個欄位
uvx desktop-agent keyboard press tab

# 填寫第二個欄位
uvx desktop-agent keyboard write "john@example.com"

# 提交表單（Enter）
uvx desktop-agent keyboard press enter

工作流程 4：複製/貼上操作

# 全選文字
uvx desktop-agent keyboard hotkey "ctrl,a"

# 複製
uvx desktop-agent keyboard hotkey "ctrl,c"

# 點擊目的地
uvx desktop-agent mouse click 500 600

# 貼上
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）
  • 圖片與實際螢幕外觀相符（解析度、顏色）

取得協助

# 顯示所有可用指令
uvx desktop-agent --help

# 顯示特定類別的指令
uvx desktop-agent mouse --help
uvx desktop-agent keyboard --help
uvx desktop-agent screen --help
uvx desktop-agent message --help

# 顯示特定指令的說明
uvx desktop-agent mouse move --help

AI 代理整合技巧

  1. 使用絕對座標時，務必先檢查螢幕尺寸
  2. 盡可能使用相對定位（例如取得目前位置，計算偏移）
  3. 組合指令以完成複雜工作流程
  4. 執行前先驗證（例如檢查圖片是否存在於螢幕上）
  5. 使用訊息對話框為重要操作提供使用者回饋
  6. 優雅處理錯誤 - 若 UI 狀態變更，指令可能失敗

效能注意事項

  • 使用 --duration 的滑鼠移動會以動畫方式呈現，需要時間
  • 圖片定位（locate）在大螢幕上可能較慢 - 盡可能使用區域
  • 鍵盤指令通常很快（< 100ms）
  • 螢幕擷取取決於螢幕解析度和區域大小

輸出格式

所有指令預設輸出結構化 JSON，適合 AI 代理程式化使用：

uvx desktop-agent mouse position
# 輸出：{"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. 取得螢幕尺寸以了解工作區
uvx desktop-agent screen size
uvx desktop-agent app list
uvx desktop-agent mouse position

📋 依任務建議的指令序列

開啟並與應用程式互動
# ✅ 正確：開啟、等待、驗證、然後互動
uvx desktop-agent app open notepad              # 步驟 1：開啟應用程式
uvx desktop-agent app list
uvx desktop-agent app focus "Notepad"
uvx desktop-agent keyboard write "Hello World"  # 步驟 4：現在可以安全輸入

# ❌ 錯誤：未驗證就立即輸入
uvx desktop-agent app open notepad
uvx desktop-agent keyboard write "Hello World"  # 可能輸入到錯誤視窗！
尋找並點擊 UI 元素（基於圖片）
# ✅ 正確：先尋找，找到後再點擊
uvx desktop-agent screen locate-center button.png --confidence 0.8
# 檢查 success=true 且座標有效
uvx desktop-agent mouse click 125 215  # 使用回傳的座標

# ❌ 錯誤：未驗證元素是否存在就點擊
uvx desktop-agent mouse click 125 215  # 可能點錯區域！
尋找並點擊 UI 元素（基於文字 OCR）
# ✅ 正確：讀取螢幕文字，然後尋找特定文字
uvx desktop-agent screen read-all-text --active
uvx desktop-agent screen locate-text-coordinates "Save" --active
# 使用回傳的座標點擊

# 針對特定視窗的 OCR：
uvx desktop-agent screen locate-text-coordinates "OK" --window "Dialog Title"
填寫多欄位表單
# ✅ 正確：在輸入前明確點擊每個欄位
uvx desktop-agent mouse click 300 200           # 點擊第一個欄位
uvx desktop-agent keyboard write "John Doe"
uvx desktop-agent mouse click 300 250           # 點擊第二個欄位（更可靠）
uvx desktop-agent keyboard write "john@example.com"
uvx desktop-agent mouse click 300 300           # 點擊第三個欄位
uvx desktop-agent keyboard write "555-1234"

# 或使用 Tab 導航（若欄位順序變更則較不可靠）
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 "john@example.com"
uvx desktop-agent keyboard press tab
uvx desktop-agent keyboard write "555-1234"
uvx desktop-agent keyboard press enter          # 提交
針對分析擷取目標螢幕畫面
# ✅ 正確：擷取特定視窗以加快處理速度
uvx desktop-agent app list --json                           # 找出確切視窗標題
uvx desktop-agent screen screenshot app.png --window "Google Chrome"

# 僅作用中視窗
uvx desktop-agent screen screenshot active.png --active

# 僅在必要時擷取全螢幕（較慢、檔案較大）
uvx desktop-agent screen size
uvx desktop-agent screen screenshot full.png
安全拖放
# ✅ 正確：移動到起點，驗證位置，然後拖曳
uvx desktop-agent mouse move 100 200                 # 移動到來源
uvx desktop-agent mouse position              # 驗證位置
uvx desktop-agent mouse drag 500 400 --duration 0.5  # 拖曳到目的地

# 為求精確，使用較慢的持續時間
uvx desktop-agent mouse drag 500 400 --duration 1.0

🔄 錯誤復原模式

找不到視窗時
# 模式：列出視窗，尋找最接近的比對，重試
uvx desktop-agent app focus "Chrome"             # 失敗，回傳 window_not_found
uvx desktop-agent app list                # 查看實際視窗標題
# 輸出顯示："Google Chrome - My Page"
uvx desktop-agent app focus "Google Chrome"      # 使用正確標題
找不到圖片時
# 模式：調整信心值或重新擷圖
uvx desktop-agent screen locate button.png --confidence 0.9
uvx desktop-agent screen locate button.png --confidence 0.7
# 若仍失敗，擷取目前狀態進行分析
uvx desktop-agent screen screenshot current.png --active
點擊似乎沒命中時
# 模式：驗證座標是否在螢幕上
uvx desktop-agent screen size             # 取得螢幕邊界
uvx desktop-agent screen on-screen 1500 900      # 檢查座標是否有效
uvx desktop-agent mouse move 1500 900            # 先移動以視覺化
uvx desktop-agent mouse click                    # 然後在目前位置點擊

⚡ 效能最佳化

減少擷圖次數
# ✅ 良好：僅擷取需要的區域
uvx desktop-agent screen screenshot button_area.png --region "100,200,200,100"

# ✅ 良好：擷取特定視窗而非全螢幕
uvx desktop-agent screen screenshot chrome.png --window "Google Chrome"

# ❌ 緩慢：僅需小區域卻擷取全螢幕
uvx desktop-agent screen screenshot full.png
批次鍵盤輸入
# ✅ 較快：一次輸入完整文字
uvx desktop-agent keyboard write "This is a complete sentence with all the text."

# ❌ 較慢：多個 write 指令
uvx desktop-agent keyboard write "This is "
uvx desktop-agent keyboard write "a complete "
uvx desktop-agent keyboard write "sentence."
盡可能使用快捷鍵而非滑鼠
# ✅ 較快：使用鍵盤快捷鍵
uvx desktop-agent keyboard hotkey "ctrl,s"       # 儲存
uvx desktop-agent keyboard hotkey "ctrl,a"       # 全選
uvx desktop-agent keyboard hotkey "ctrl,shift,s" # 另存新檔

# ❌ 較慢：用滑鼠導覽選單
uvx desktop-agent mouse click 50 30              # 點擊檔案選單
uvx desktop-agent mouse click 60 80              # 點擊儲存選項

🛡️ 防禦性程式設計模式

務必驗證關鍵操作
# 在破壞性操作前，先與使用者確認
uvx desktop-agent message confirm "This will delete all files. Continue?" --title "Warning"
# 檢查輸出：若按了「取消」，則中止操作
使用 JSON 模式以可靠解析
# ✅ 可靠：解析結構化 JSON 輸出
uvx desktop-agent screen locate button.png
# 解析：{"success": true, "data": {"center_x": 125, "center_y": 215}}

# ❌ 脆弱：解析文字輸出
uvx desktop-agent screen locate button.png
# 解析："Found at: Box(left=100, top=200, width=50, height=30)"
在多步驟操作前進行驗證
# 多步驟檔案操作，含驗證
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
# 常見 Windows 快捷鍵
uvx desktop-agent keyboard hotkey "win,d"        # 顯示桌面
uvx desktop-agent keyboard hotkey "win,e"        # 開啟檔案總管
uvx desktop-agent keyboard hotkey "alt,tab"      # 切換視窗
uvx desktop-agent keyboard hotkey "win,r"        # 執行對話框

# 依名稱開啟應用程式
uvx desktop-agent app open notepad
uvx desktop-agent app open calc
uvx desktop-agent app open mspaint
macOS
# 常見 macOS 快捷鍵（使用 'command' 代表 Cmd 鍵）
uvx desktop-agent keyboard hotkey "command,space"   # Spotlight
uvx desktop-agent keyboard hotkey "command,tab"     # 應用程式切換器
uvx desktop-agent keyboard hotkey "command,q"       # 結束應用程式
uvx desktop-agent keyboard hotkey "command,shift,3" # 螢幕擷圖

# 開啟應用程式
uvx desktop-agent app open "Safari"
uvx desktop-agent app open "TextEdit"
Linux
# 開啟應用程式（使用 xdg-open 或直接指令）
uvx desktop-agent app open firefox
uvx desktop-agent app open gedit

# 常見快捷鍵可能因桌面環境而異
uvx desktop-agent keyboard hotkey "alt,f2"       # 執行對話框（許多桌面環境）

📊 決策樹：選擇正確指令

 想與應用程式互動？
├── 應用程式未執行 → `app open <name>`
├── 應用程式已執行但未聚焦 → `app focus <name>` 
└── 需要驗證視窗 → `app list`

想尋找 UI 元素？
├── 有參考圖片 → `screen locate-center <image>`
├── 知道文字標籤 → `screen locate-text-coordinates "<text>"`
└── 需要查看所有文字 → `screen read-all-text --active`

想點擊某個東西？
├── 知道確切座標 → `mouse click <x> <y>`
├── 需要先尋找 → 使用上述 locate 指令，然後點擊回傳的座標
└── 不確定是否在螢幕上 → 先使用 `screen on-screen <x> <y>`

想輸入文字？
├── 一般文字 → `keyboard write "<text>"`
├── 鍵盤快捷鍵 → `keyboard hotkey "<key1>,<key2>"`
├── 單一按鍵 → `keyboard press <key>`
└── 多次相同按鍵 → `keyboard press <key> --presses N`

AI 代理整合技巧

  1. 使用絕對座標時，務必先檢查螢幕尺寸
  2. 盡可能使用相對定位（例如取得目前位置，計算偏移）
  3. 組合指令以完成複雜工作流程
  4. 執行前先驗證（例如檢查圖片是否存在於螢幕上）
  5. 使用訊息對話框為重要操作提供使用者回饋
  6. 優雅處理錯誤 - 若 UI 狀態變更，指令可能失敗