desktop-control

技能：desktop-control

适用场景

用户提出以下需求时，请使用此技能：

• 点击屏幕上的某处
• 将鼠标移动到某个位置
• 在应用程序中输入文本
• 按键盘快捷键或热键
• 读取当前屏幕上的内容（辅助功能树）
• 获取最前端窗口的信息
• 自动执行桌面交互
• 控制计算机（鼠标、键盘、屏幕）
• 在应用程序中向上／向下滚动
• 拖放元素

重要：此技能需要为终端／IDE 授予辅助功能权限。在 macOS 上，前往 System Settings > Privacy & Security > Accessibility，并启用正在运行的应用程序。

捆绑脚本

脚本	类型	描述
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	输入文本时	要输入的文本	Hello World
key	按键时	要按下的按键名称	enter
keys	热键时	按键组合，按加号分隔	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	截取屏幕时需要	截图输出路径	/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