> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Computer Use

> computer(action=...) — 像素级桌面/沙箱操控工具

# Computer Use

`computer(action=...)` 提供像素级的屏幕操控能力，适用于操作任何 GUI 应用程序。

## 概述

Computer Use 是最底层的交互工具——它通过截图观察屏幕、通过坐标点击和键盘输入来操作。适用于没有 DOM 结构的原生应用、游戏、和任何 GUI 界面。

## 可用 Actions

| Action             | 说明        | 必需参数                                   |
| ------------------ | --------- | -------------------------------------- |
| `screenshot`       | 截取屏幕/窗口   | `window_id`(可选)                        |
| `click`            | 点击坐标      | `x`, `y` 或 `element_index`             |
| `double_click`     | 双击坐标      | `x`, `y`                               |
| `type`             | 在光标位置输入文本 | `text`                                 |
| `scroll`           | 滚动        | `direction`, `amount`                  |
| `drag`             | 拖拽        | `start_x`, `start_y`, `end_x`, `end_y` |
| `keypress`         | 按键组合      | `keys` (数组)                            |
| `move`             | 移动光标      | `x`, `y`                               |
| `cursor_position`  | 获取光标位置    | —                                      |
| `list_windows`     | 列出所有窗口    | —                                      |
| `get_window_state` | 获取窗口无障碍树  | `window_id` 或 `pid`                    |

## 使用示例

### 截图并分析

```python theme={null}
computer(action="screenshot")
```

### 点击指定坐标

```python theme={null}
computer(action="click", x=500, y=300)
```

### 输入文本

```python theme={null}
computer(action="type", text="Hello World")
```

### 键盘快捷键

```python theme={null}
computer(action="keypress", keys=["cmd", "c"])  # 复制
computer(action="keypress", keys=["cmd", "v"])  # 粘贴
```

### 拖拽操作

```python theme={null}
computer(action="drag", start_x=100, start_y=200, end_x=400, end_y=200)
```

### 窗口管理

```python theme={null}
computer(action="list_windows")
computer(action="get_window_state", window_id=12345)
computer(action="click", element_index=3, window_id=12345)
```

## 执行后端

| 环境            | 后端             | 说明                   |
| ------------- | -------------- | -------------------- |
| Cloud Sandbox | noVNC 像素流      | 通过 VNC 协议截图和控制       |
| Desktop       | macOS CUA 守护进程 | 原生 Accessibility API |

## 最佳实践

1. **先截图再操作**：每次操作前先 `screenshot` 确认界面状态
2. **用 element\_index 优于坐标**：`get_window_state` 返回的无障碍元素索引比坐标更可靠
3. **等待响应**：复杂操作后等待 UI 更新再截图验证
4. **窗口聚焦**：操作前确认目标窗口在前台

## 与 browser 的区别

| 维度   | computer  | browser                  |
| ---- | --------- | ------------------------ |
| 感知方式 | 像素截图      | DOM / Accessibility Tree |
| 定位方式 | 坐标 (x, y) | CSS 选择器 / ref            |
| 精度   | 像素级       | 元素级                      |
| 适用场景 | 原生应用、游戏   | 网页                       |
| 可靠性  | 依赖分辨率     | 不受分辨率影响                  |

## 激活条件

`computer` 工具仅在 Desktop 模式下（`desktop_connected=true`）自动可用。Cloud Sandbox 中的像素级操控通过 Browser 面板（noVNC）实现。