# Computer Use 系统

## 概述

Computer Use 功能允许 AI 模型直接控制桌面 — 截取屏幕、移动鼠标、点击、键盘输入、窗口管理等。系统由两部分组成：

1. **TypeScript API 层** (`src/server/api/computer-use.ts`) — 环境检测、Python venv 创建、依赖安装
2. **Python Runtime 辅助脚本** (`runtime/`) — 通过子进程 `spawn` 执行，通过 stdout JSON 协议通信

## Python Runtime 辅助脚本

### 架构

```
┌─────────────────────────────────────────────┐
│             CLI 进程 (Bun/TypeScript)          │
│  src/server/api/computer-use.ts                │
│      │                                         │
│      │ child_process.spawn("python3", ...)      │
│      ▼                                         │
│  ~/.claude/.runtime/                           │
│      ├── mac_helper.py  (macOS)                │
│      ├── win_helper.py  (Windows)              │
│      ├── requirements.txt                      │
│      └── venv/                                 │
│           └── pip install pyautogui mss ...    │
│      │                                         │
│      ▼ stdout (JSON)                           │
│  {"ok": true, "result": ...}                   │
└─────────────────────────────────────────────┘
```

**编译时**: 脚本通过 Bun 的 `with { type: 'text' }` 嵌入 bundle（`computer-use.ts:27-33`）。

**运行时**: 首次使用 Computer Use 时，`ensureRuntimeFiles()` 将脚本提取到 `~/.claude/.runtime/`，创建 Python venv 并安装依赖。之后每次调用通过 `child_process.spawn` 启动 `python3 mac_helper.py <command> --payload <json>`。

### 文件说明

| 文件 | 平台 | 行数 | 依赖 |
|------|------|------|------|
| `runtime/mac_helper.py` | macOS | ~775 | pyautogui, mss, Pillow, pyobjc (Quartz/AppKit) |
| `runtime/win_helper.py` | Windows | ~770 | pyautogui, mss, Pillow, pywin32, psutil, screeninfo, pyperclip |
| `runtime/test_helpers.py` | 跨平台 | ~322 | unittest (标准库) |
| `runtime/requirements.txt` | macOS | — | pip 依赖声明 |
| `runtime/requirements-win.txt` | Windows | — | pip 依赖声明 |

### 通信协议

严格的 JSON 行协议。每次调用：

```
$ python3 mac_helper.py screenshot --payload '{"displayId": null, "targetWidth": 1024, "targetHeight": 768}'
{"ok": true, "result": {"base64": "...", "width": 1024, "height": 768, ...}}
```

失败时返回：
```json
{"ok": false, "error": {"code": "runtime_error", "message": "..."}}
```

### 命令列表

两个 helper 暴露完全相同的命令集：

**屏幕捕获：**
- `list_displays` — 列举所有显示器（分辨率、缩放因子、原点坐标）
- `get_display_size` — 获取指定显示器的尺寸
- `screenshot` — 截取全屏（可选 resize）
- `resolve_prepare_capture` — 带 fallback 的屏幕捕获
- `zoom` — 截取指定区域

**窗口管理：**
- `list_windows` — 列举可见窗口（标题、位置、所属应用）
- `find_window_displays` — 查询窗口所在的显示器
- `frontmost_app` — 获取当前前台应用
- `app_under_point` — 获取屏幕坐标下的应用
- `list_installed_apps` — 列举已安装应用
- `list_running_apps` — 列举运行中的应用
- `open_app` — 打开指定应用

**鼠标控制：**
- `click` — 点击（支持修饰键、多击）
- `drag` — 拖拽
- `move_mouse` — 移动鼠标
- `scroll` — 滚动（支持水平和垂直）
- `mouse_down` / `mouse_up` — 鼠标按键按下/释放
- `cursor_position` — 获取当前光标位置

**键盘控制：**
- `key` — 按键组合（如 `cmd+v`）
- `hold_key` — 按住键指定时长
- `type` — 输入文本

**剪贴板：**
- `read_clipboard` — 读取剪贴板文本
- `write_clipboard` — 写入剪贴板
- `paste_clipboard` — 执行粘贴（cmd+v / ctrl+v）

**权限检测：**
- `check_permissions` — 检测 Accessibility / Screen Recording 权限

**空操作（桌面应用兼容）：**
- `prepare_for_action` — 返回空数组
- `preview_hide_set` — 返回空数组

### 跨平台设计

两套 helper 遵循 **同一 JSON 协议**，差异仅限平台相关底层实现：

| 能力 | macOS (`mac_helper.py`) | Windows (`win_helper.py`) |
|------|------------------------|---------------------------|
| 显示器枚举 | Quartz `CGGetActiveDisplayList` | `screeninfo.get_monitors` |
| 窗口枚举 | Quartz `CGWindowListCopyWindowInfo` | `win32gui.EnumWindows` |
| 应用管理 | `NSWorkspace` (AppKit) | `psutil` + `winreg` |
| 剪贴板 | `NSPasteboard` (AppKit) | `pyperclip` |
| 修饰键 | `command` | `win` |
| 粘贴快捷键 | osascript `cmd+v` | pyautogui `ctrl+v` |
| 权限模型 | TCC (Transparency, Consent, and Control) | 始终返回 `True` |

`test_helpers.py` 通过静态分析验证两者的 KEY_MAP 一致性、命令集完整性和辅助函数签名。

### 与桌面 HTTP API 的关系

桌面服务器通过 `/api/computer-use/status` (GET) 和 `/api/computer-use/setup` (POST) 管理 Python runtime 的安装和状态检测。实际执行 Computer Use 动作时，CLI 进程直接 `spawn` helper 脚本，不经过 HTTP 层。