AI Skills
Desktop Control

Desktop Control

控制鼠标、键盘和屏幕，用于桌面自动化任务

1Star
0Fork
更新于 2026/6/17
获取 Skill源代码

相关 Skills

design11万algorithmic-art15万frontend-ui-engineering7.7万
SKILL.md
readonly只读
name
Desktop Control
description

控制鼠标、键盘和屏幕，用于桌面自动化任务

桌面控制技能

该技能通过 PyAutoGUI 提供全面的桌面自动化能力，使 AI 代理能够控制鼠标、键盘、截取屏幕截图并与桌面环境交互。

如何使用此技能

作为 AI 代理，您可以使用 uvx desktop-agent CLI 调用桌面自动化命令。

命令结构

所有命令遵循以下模式：

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

类别：

  • 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 键 3 次
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 "任务完成！"

# 获取用户确认
uvx desktop-agent message confirm "继续操作？"

# 询问用户输入
uvx desktop-agent message prompt "请输入您的姓名："

📱 应用程序控制 (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：使用 URL 打开 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."

# ❌ 较慢：多个写入命令
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 "这将删除所有文件。是否继续？" --title "警告"
# 检查输出：如果点击了“取消”，则中止操作
使用 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

# 常用快捷键可能因 DE 而异
uvx desktop-agent keyboard hotkey "alt,f2"       # 运行对话框（许多 DE）

📊 决策树：选择正确的命令

 想与应用程序交互？
├── 应用未运行 → `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>`
├── 需要先查找 → 使用上面的定位命令，然后点击返回的坐标
└── 不确定是否在屏幕上 → 先使用 `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 状态变化，命令可能失败