介绍
# Desktop Control Skill
**适用于 OpenClaw 的最先进的桌面自动化技能。** 提供像素级精准的鼠标控制、闪电般的键盘输入、屏幕截图、窗口管理和剪贴板操作。
## 🎯 功能特性
### 鼠标控制 - ✅ **绝对定位** - 移动到精确坐标 - ✅ **相对移动** - 从当前位置移动 - ✅ **平滑移动** - 自然、拟人化的鼠标轨迹 - ✅ **点击类型** - 左键、右键、中键、双击、三击 - ✅ **拖放** - 从点 A 拖动到点 B - ✅ **滚动** - 垂直和水平滚动 - ✅ **位置追踪** - 获取当前鼠标坐标
### 键盘控制 - ✅ **文本输入** - 快速、准确的文本输入 - ✅ **快捷键** - 执行键盘快捷方式（Ctrl+C、Win+R 等） - ✅ **特殊按键** - Enter、Tab、Escape、方向键、功能键 - ✅ **组合键** - 多键按下组合 - ✅ **长按与松开** - 手动按键状态控制 - ✅ **输入速度** - 可配置 WPM（从瞬时到拟人化）
### 屏幕操作 - ✅ **屏幕截图** - 捕获整个屏幕或区域 - ✅ **图像识别** - 在屏幕上查找元素（通过 OpenCV） - ✅ **颜色检测** - 获取坐标处的像素颜色 - ✅ **多显示器** - 支持多个显示器
### 窗口管理 - ✅ **窗口列表** - 获取所有打开的窗口 - ✅ **激活窗口** - 将窗口置于前台 - ✅ **窗口信息** - 获取位置、大小、标题 - ✅ **最小化/最大化** - 控制窗口状态
### 安全功能 - ✅ **故障保护** - 将鼠标移至角落以中止 - ✅ **暂停控制** - 紧急停止机制 - ✅ **审批模式** - 操作前要求确认 - ✅ **边界检查** - 防止超出屏幕的操作 - ✅ **日志记录** - 跟踪所有自动化操作
---
## 🚀 快速开始
### 安装
首先，安装所需的依赖项：
```bash pip install pyautogui pillow opencv-python pygetwindow ```
### 基本用法
```python from skills.desktop_control import DesktopController # Initialize controller dc = DesktopController(failsafe=True) # Mouse operations dc.move_mouse(500, 300) # Move to coordinates dc.click() # Left click at current position dc.click(100, 200, button="right") # Right click at position # Keyboard operations dc.type_text("Hello from OpenClaw!") dc.hotkey("ctrl", "c") # Copy dc.press("enter") # Screen operations screenshot = dc.screenshot() position = dc.get_mouse_position() ```
---
## 📋 完整 API 参考
### 鼠标函数
#### `move_mouse(x, y, duration=0, smooth=True)` 将鼠标移动到绝对屏幕坐标。
**参数：** - `x` (int): X 坐标（距左侧的像素数） - `y` (int): Y 坐标（距顶部的像素数） - `duration` (float): 移动时间（秒）（0 = 瞬时，0.5 = 平滑） - `smooth` (bool): 使用贝塞尔曲线进行自然移动
**示例：** ```python # Instant movement dc.move_mouse(1000, 500) # Smooth 1-second movement dc.move_mouse(1000, 500, duration=1.0) ```
#### `move_relative(x_offset, y_offset, duration=0)` 相对于当前位置移动鼠标。
**参数：** - `x_offset` (int): 水平移动像素数（正数 = 向右） - `y_offset` (int): 垂直移动像素数（正数 = 向下） - `duration` (float): 移动时间（秒）
**示例：** ```python # Move 100px right, 50px down dc.move_relative(100, 50, duration=0.3) ```
#### `click(x=None, y=None, button='left', clicks=1, interval=0.1)` 执行鼠标点击。
**参数：** - `x, y` (int, 可选): 点击坐标（None = 当前位置） - `button` (str): 'left'（左键）、'right'（右键）、'middle'（中键） - `clicks` (int): 点击次数（1 = 单击，2 = 双击） - `interval` (float): 多次点击之间的延迟
**示例：** ```python # Simple left click dc.click() # Double-click at specific position dc.click(500, 300, clicks=2) # Right-click dc.click(button='right') ```
#### `drag(start_x, start_y, end_x, end_y, duration=0.5, button='left')` 拖放操作。
**参数：** - `start_x, start_y` (int): 起始坐标 - `end_x, end_y` (int): 结束坐标 - `duration` (float): 拖动持续时间 - `button` (str): 要使用的鼠标按钮
**示例：** ```python # Drag file from desktop to folder dc.drag(100, 100, 500, 500, duration=1.0) ```
#### `scroll(clicks, direction='vertical', x=None, y=None)` 滚动鼠标滚轮。
**参数：** - `clicks` (int): 滚动量（正数 = 上/左，负数 = 下/右） - `direction` (str): 'vertical'（垂直）或 'horizontal'（水平） - `x, y` (int, 可选): 滚动位置
**示例：** ```python # Scroll down 5 clicks dc.scroll(-5) # Scroll up 10 clicks dc.scroll(10) # Horizontal scroll dc.scroll(5, direction='horizontal') ```
#### `get_mouse_position()` 获取当前鼠标坐标。
**返回：** `(x, y)` 元组
**示例：** ```python x, y = dc.get_mouse_position() print(f"Mouse is at: {x}, {y}") ```
---
### 键盘函数
#### `type_text(text, interval=0, wpm=None)` 以可配置速度输入文本。
**参数：** - `text` (str): 要输入的文本 - `interval` (float): 按键之间的延迟（0 = 瞬时） - `wpm` (int, 可选): 每分钟字数（覆盖 interval）
**示例：** ```python # Instant typing dc.type_text("Hello World") # Human-like typing at 60 WPM dc.type_text("Hello World", wpm=60) # Slow typing with 0.1s between keys dc.type_text("Hello World", interval=0.1) ```
#### `press(key, presses=1, interval=0.1)` 按下并松开一个键。
**参数：** - `key` (str): 键名（参见键名部分） - `presses` (int): 按键次数 - `interval` (float): 按键之间的延迟
**示例：** ```python # Press Enter dc.press('enter') # Press Space 3 times dc.press('space', presses=3) # Press Down arrow dc.press('down') ```
#### `hotkey(*keys, interval=0.05)` 执行键盘快捷键。
**参数：** - `*keys` (str): 要同时按下的键 - `interval` (float): 按键之间的延迟
**示例：** ```python # Copy (Ctrl+C) dc.hotkey('ctrl', 'c') # Paste (Ctrl+V) dc.hotkey('ctrl', 'v') # Open Run dialog (Win+R) dc.hotkey('win', 'r') # Save (Ctrl+S) dc.hotkey('ctrl', 's') # Select All (Ctrl+A) dc.hotkey('ctrl', 'a') ```
#### `key_down(key)` / `key_up(key)` 手动控制按键状态。
**示例：** ```python # Hold Shift dc.key_down('shift') dc.type_text("hello") # Types "HELLO" dc.key_up('shift') # Hold Ctrl and click (for multi-select) dc.key_down('ctrl') dc.click(100, 100) dc.click(200, 100) dc.key_up('ctrl') ```
---
### 屏幕函数
#### `screenshot(region=None, filename=None)` 捕获屏幕或区域。
**参数：** - `region` (tuple, 可选): 部分捕获的 (left, top, width, height) - `filename` (str, 可选): 保存图像的路径
**返回：** PIL 图像对象
**示例：** ```python # Full screen img = dc.screenshot() # Save to file dc.screenshot(filename="screenshot.png") # Capture specific region img = dc.screenshot(region=(100, 100, 500, 300)) ```
#### `get_pixel_color(x, y)` 获取坐标处像素的颜色。
**返回：** RGB 元组 `(r, g, b)`
**示例：** ```python r, g, b = dc.get_pixel_color(500, 300) print(f"Color at (500, 300): RGB({r}, {g}, {b})") ```
#### `find_on_screen(image_path, confidence=0.8)` 在屏幕上查找图像（需要 OpenCV）。
**参数：** - `image_path` (str): 模板图像路径 - `confidence` (float): 匹配阈值（0-1）
**返回：** `(x, y, width, height)` 或 None
**示例：** ```python # Find button on screen location = dc.find_on_screen("button.png") if location: x, y, w, h = location # Click center of found image dc.click(x + w//2, y + h//2) ```
#### `get_screen_size()` 获取屏幕分辨率。
**返回：** `(width, height)` 元组
**示例：** ```python width, height = dc.get_screen_size() print(f"Screen: {width}x{height}") ```
---
### 窗口函数
#### `get_all_windows()` 列出所有打开的窗口。
**返回：** 窗口标题列表
**示例：** ```python windows = dc.get_all_windows() for title in windows: print(f"Window: {title}") ```
#### `activate_window(title_substring)` 通过标题将窗口置于前台。
**参数：** - `title_substring` (str): 要匹配的窗口标题的一部分
**示例：** ```python # Activate Chrome dc.activate_window("Chrome") # Activate VS Code dc.activate_window("Visual Studio Code") ```
#### `get_active_window()` 获取当前聚焦的窗口。
**返回：** 窗口标题 (str)
**示例：** ```python active = dc.get_active_window() print(f"Active window: {active}") ```
---
### 剪贴板函数
#### `copy_to_clipboard(text)` 将文本复制到剪贴板。
**示例：** ```python dc.copy_to_clipboard("Hello from OpenClaw!") ```
#### `get_from_clipboard()` 从剪贴板获取文本。
**返回：** str
**示例：** ```python text = dc.get_from_clipboard() print(f"Clipboard: {text}") ```
---
## ⌨️ 键名参考
### 字母键 `'a'` 到 `'z'`
### 数字键 `'0'` 到 `'9'`
### 功能键 `'f1'` 到 `'f24'`
### 特殊键 - `'enter'` / `'return'` - `'esc'` / `'escape'` - `'space'` / `'spacebar'` - `'tab'` - `'backspace'` - `'delete'` / `'del'` - `'insert'` - `'home'` - `'end'` - `'pageup'` / `'pgup'` - `'pagedown'` / `'pgdn'`
### 方向键 - `'up'` / `'down'` / `'left'` / `'right'`
### 修饰键 - `'ctrl'` / `'control'` - `'shift'` - `'alt'` - `'win'` / `'winleft'` / `'winright'` - `'cmd'` / `'command'` (Mac)
### 锁定键 - `'capslock'` - `'numlock'` - `'scrolllock'`
### 标点符号 - `'.'` / `','` / `'?'` / `'!'` / `';'` / `':'` - `'['` / `']'` / `'{'` / `'}'` - `'('` / `')'` - `'+'` / `'-'` / `'*'` / `'/'` / `'='`
---
## 🛡️ 安全功能
### 故障保护模式
将鼠标移动到屏幕的 **任意角落** 以中止所有自动化。
```python # Enable failsafe (enabled by default) dc = DesktopController(failsafe=True) ```
### 暂停控制
```python # Pause all automation for 2 seconds dc.pause(2.0) # Check if automation is safe to proceed if dc.is_safe(): dc.click(500, 500) ```
### 审批模式
操作前要求用户确认：
```python dc = DesktopController(require_approval=True) # This will ask for confirmation dc.click(500, 500) # Prompt: "Allow click at (500, 500)? [y/n]" ```
---
## 🎨 高级示例
### 示例 1：自动表单填写
```python dc = DesktopController() # Click name field dc.click(300, 200) dc.type_text("John Doe", wpm=80) # Tab to next field dc.press('tab') dc.type_text("[email protected]", wpm=80) # Tab to password dc.press('tab') dc.type_text("SecurePassword123", wpm=60) # Submit form dc.press('enter') ```
### 示例 2：屏幕区域截图并保存
```python # Capture specific area region = (100, 100, 800, 600) # left, top, width, height img = dc.screenshot(region=region) # Save with timestamp import datetime timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S") img.save(f"capture_{timestamp}.png") ```
### 示例 3：多文件选择
```python # Hold Ctrl and click multiple files dc.key_down('ctrl') dc.click(100, 200) # First file dc.click(100, 250) # Second file dc.click(100, 300) # Third file dc.key_up('ctrl') # Copy selected files dc.hotkey('ctrl', 'c') ```
### 示例 4：窗口自动化
```python # Activate Calculator dc.activate_window("Calculator") time.sleep(0.5) # Type calculation dc.type_text("5+3=", interval=0.2) time.sleep(0.5) # Take screenshot of result dc.screenshot(filename="calculation_result.png") ```
### 示例 5：拖放文件
```python # Drag file from source to destination dc.drag( start_x=200, start_y=300, # File location end_x=800, end_y=500, # Folder location duration=1.0 # Smooth 1-second drag ) ```
---
## ⚡ 性能提示
1. **使用瞬时移动** 以提高速度：`duration=0` 2. **批量操作** 而不是单独调用 3. **缓存屏幕位置** 而不是重新计算 4. **禁用故障保护** 以获得最大性能（请谨慎使用） 5. **使用快捷键** 而不是菜单导航
---
## ⚠️ 重要说明
- **屏幕坐标** 从左上角的 (0, 0) 开始 - **多显示器设置** 的辅助显示器可能具有负坐标 - **Windows DPI 缩放** 可能会影响坐标精度 - **故障保护角落** 为：(0,0), (width-1, 0), (0, height-1), (width-1, height-1) - **某些应用程序** 可能会阻止模拟输入（游戏、安全应用程序）
---
## 🔧 故障排除
### 鼠标未移动到正确位置 - 检查 DPI 缩放设置 - 验证屏幕分辨率是否符合预期 - 使用 `get_screen_size()` 确认尺寸
### 键盘输入无效 - 确保目标应用程序已聚焦 - 某些应用需要管理员权限 - 尝试增加 `interval` 以提高可靠性
### 故障保护意外触发 - 增加屏幕边框容差 - 正常使用期间将鼠标移离角落 - 如需要则禁用：`DesktopController(failsafe=False)`
### 权限错误 - 某些操作需要以管理员权限运行 Python - 某些安全应用程序会阻止自动化
---
## 📦 依赖项
- **PyAutoGUI** - 核心自动化引擎 - **Pillow** - 图像处理 - **OpenCV**（可选）- 图像识别 - **PyGetWindow** - 窗口管理
安装全部： ```bash pip install pyautogui pillow opencv-python pygetwindow ```
---
**为 OpenClaw 打造** - 终极桌面自动化伴侣 🦞