Computer Use 系统

概述

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

TypeScript API 层 (src/server/api/computer-use.ts) — 环境检测、Python venv 创建、依赖安装
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, ...}}

失败时返回：

{"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 层。