# computer-runtime

跨平台 GUI 自动化运行时 + MCP Server。用同一套统一 API 在 **macOS / Windows / Linux(X11)** 上完成桌面 GUI 元素的**读取、点击、输入、快捷键和截图**，并通过 Playwright + DOM/ARIA 提供浏览器高速结构化控制；桌面操作提供稳定 windowId、事件式 waitFor 与结果 verify。全部能力通过 **MCP（Model Context Protocol）** 对外暴露，可供任意 MCP 宿主（如 AI 助手）直接驱动。

```text
                 MCP Client / AI Host
                          │
                  ┌──────────────┐
                  │  MCP Server  │ 25 tools: computer.* + browser.*
                  └──────┬───────┘
          ┌──────────────┴──────────────┐
          ▼                             ▼
   computer.* (stdio JSON-RPC)     browser.* (in-process)
          ▼                             ▼
 Computer Runtime (Rust)         Browser Runtime (TS)
          │                        Playwright + DOM/ARIA + CDP
 ┌────────┼────────┐                     │
Win     macOS     Linux                ▼
UIA      AX      AT-SPI/XTest     Chromium/Chrome/Edge
```

核心设计原则：**语义动作优先于物理动作**（优先走系统无障碍 API 的语义操作，物理点击/键入只作兜底）、上层永不接触平台原生句柄、主同步路径禁止固定 sleep、测试不依赖 LLM 与公网。

---

## 一、环境要求

| 依赖 | 版本要求 | 用途 |
| --- | --- | --- |
| Rust (cargo) | stable | 编译桌面 Runtime |
| Node.js | 18+（20+ 推荐） | MCP Server / Browser Runtime / 测试 |
| npm | 9+ | TS 工作区构建 |
| Chrome / Edge（可选） | 本机已安装即可 | browser.* 自动探测，无需另装 Playwright 浏览器 |
| Xcode Command Line Tools（仅 macOS） | 与当前 macOS SDK 匹配 | 编译 ScreenCaptureKit 的 Objective-C/ARC 桥接层（`xcrun clang`） |

**系统权限（macOS 必须，首次运行时授权一次即可）**

在 系统设置 → 隐私与安全性 中，给你的终端 / MCP 宿主 App 开启：

- **辅助功能（Accessibility）** —— 读取窗口元素树、语义点击、窗口聚焦
- **屏幕与系统音频录制（Screen & System Audio Recording）** —— ScreenCaptureKit 全屏/指定窗口截图

截图状态可通过 `computer_capabilities` 或 Runtime CLI 的 `capabilities` 查看。macOS 会分别报告：

- `screen_capture.permission`：TCC 预检是否通过；
- `screen_capture.available`：真实小尺寸截图探测是否成功；
- `screen_capture.backend`：实际服务截图的 `screencapturekit`、`screencapture-cli` 或 `none`。

权限、后端缺失和后端执行失败分别返回 `SCREEN_CAPTURE_PERMISSION_DENIED`、
`SCREEN_CAPTURE_BACKEND_UNAVAILABLE` 和 `SCREEN_CAPTURE_BACKEND_FAILED`，不会再把所有失败都猜成权限问题。

**Linux 仅支持 X11 会话**（Wayland 显式返回 `UNSUPPORTED`）；Windows 需要 Windows 10 1809+。

---

## 二、安装（构建）

```bash
git clone <repo-url> computer-use-mcp
cd computer-use-mcp

# 1. 桌面 Runtime（Rust）→ 产物 target/release/computer-runtime
cargo build --release -p computer-runtime-ipc

# 2. MCP Server + SDK + Browser Runtime（TypeScript 工作区）
npm install
npm run build
```

macOS 构建时，`runtime/platform/macos/build.rs` 会通过 `xcrun clang` 编译一个很小的
Objective-C/ARC 桥接层。它负责 ScreenCaptureKit completion block 的创建与生命周期，
因此需要已安装 Xcode Command Line Tools；不需要额外下载第三方原生依赖。

构建完成后的关键产物：

```
target/release/computer-runtime                    # 桌面 Runtime 二进制（含 CLI 与 stdio 服务）
packages/mcp-server/dist/index.js                  # MCP Server 入口（bin 名 computer-mcp）
```

> 仅运行测试时才需要：`cd apps/test-gui && npm install && npm run build`（Electron 测试 GUI）。

---

## 三、运行

本项目**没有常驻守护进程**：MCP 宿主负责拉起 MCP Server，Server 再按会话启动桌面 Runtime。你只需要配置一次 MCP，之后即插即用。

### 方式 1：接入 MCP 宿主（推荐）

在你的 MCP 宿主配置文件（如 `mcp.json` / `claude_desktop_config.json` 等）中加入：

```json
{
  "mcpServers": {
    "computer": {
      "command": "node",
      "args": ["/absolute/path/to/computer-use-mcp/packages/mcp-server/dist/index.js"],
      "env": {
        "COMPUTER_RUNTIME_BIN": "/absolute/path/to/computer-use-mcp/target/release/computer-runtime"
      }
    }
  }
}
```

> 注意：`args` 与 `COMPUTER_RUNTIME_BIN` 必须写成**绝对路径**（换成你自己的克隆目录）。

> macOS 建议把 release 二进制复制/安装到一个稳定路径，并让
> `COMPUTER_RUNTIME_BIN` 指向该路径。Cargo 会反复替换 `target/release` 下的构建产物，
> macOS TCC 可能继续关联旧的执行身份，表现为“预检允许，但 ScreenCaptureKit completion
> 超时”。稳定安装路径只需在系统设置中授权一次。

默认 `COMPUTER_TOOL_PROFILE=full` 时会得到 **25 个工具**：

| 分类 | 工具 |
| --- | --- |
| computer.*（桌面，14 个） | `computer_capabilities` `computer_windows` `computer_observe` `computer_click` `computer_type` `computer_key` `computer_screenshot` `computer_wait` `computer_verify` `computer_visual_observe` `computer_resolve` `computer_screenshot_image` `computer_capture_region` `computer_register_visual_target` |
| browser.*（浏览器，11 个） | `browser_launch` `browser_pages` `browser_observe` `browser_navigate` `browser_click` `browser_type` `browser_key` `browser_screenshot` `browser_evaluate` `browser_wait` `browser_verify` |

`computer_click` 还支持 `visual_N` 目标（来自 `computer_visual_observe` 或
`computer_register_visual_target`）以及 `query` + `expect` 混合解析与点击后验证
（协议 0.4.0，见 `docs/protocol-v3.md` 与 `docs/migration-0.3-to-0.4.md`）。

**截图不再返回大块 base64**（协议 0.4.0）：`computer_screenshot` /
`browser_screenshot` 默认返回 <2KB 的 `capture_N` 元数据引用（CaptureReference），
像素只留在服务端（TTL 10min / LRU 64 条 / 128MB）。需要真正看图时走三条显式通道：
MCP resource `computer://capture/{id}`（Host 原生图片桥）、
`computer_screenshot_image`（危险的 raw escape hatch，默认禁用）、
`computer_capture_region`（高清 ROI 裁剪）。这防止了部分宿主把
`{type:"image"}` 结果 stringify 成文本、单张截图吃掉上百万 token 的事故。

**可选环境变量**（加在上面配置的 `env` 里）：

| 变量 | 作用 |
| --- | --- |
| `COMPUTER_RUNTIME_ARGS=--mock` | 使用内置 Mock 平台——无需真实 GUI 与系统权限，用于验证整条链路 |
| `COMPUTER_BROWSER_HEADED=1` | browser.* 用有头浏览器（默认无头） |
| `COMPUTER_ENABLE_EVALUATE=0` | 关闭 `browser_evaluate`（安全收紧） |
| `COMPUTER_VISION_ENABLED=1` | 开启视觉 grounding（**默认关闭**；`computer_visual_observe`/`computer_resolve` 视觉回退需要） |
| `COMPUTER_VISION_PROVIDER=mock\|remote\|openai-compatible` | 视觉 provider（默认 mock，纯本地）；`openai-compatible` 调用多模态 `/chat/completions` |
| `COMPUTER_VISION_REMOTE_UPLOAD=1` | 所有远程 provider 的第二道开关：不设置则绝不会向外部端点上传截图 |
| `COMPUTER_VISION_BASE_URL` / `COMPUTER_VISION_MODEL` / `COMPUTER_VISION_API_KEY` | `openai-compatible` 的 API 根地址、模型和可选密钥 |
| `COMPUTER_VISION_MAX_RETRIES` / `COMPUTER_VISION_MAX_IMAGE_BYTES` | Managed Vision 的重试上限（默认 1）和图像上限（默认 8MiB） |
| `COMPUTER_TOOL_PROFILE=desktop-core\|desktop-vision\|browser\|full\|debug` | 静态工具面；默认 `full` 兼容旧 Host，日常建议按场景缩到 9–13 个工具 |
| `COMPUTER_CONTEXT_METRICS=1` | 把 schema 字符数、Tool Result 字节数、元素数和视觉尝试写到 stderr；不会回传给模型 |
| `COMPUTER_SCREENSHOT_MODE=reference\|image\|auto` | 截图返回语义，默认 `reference`（如上）；`image` 恢复 0.3 的原始图片行为 |
| `COMPUTER_LEGACY_SCREENSHOT=1` | 短期过渡：同 `image`，带弃用警告 |
| `COMPUTER_ALLOW_RAW_IMAGE_CONTENT=1` | 显式允许 `computer_screenshot_image` 返回 ImageContent；仅用于确认不会把图片 stringify 进历史记录的 Host，默认禁用 |
| `COMPUTER_CAPTURE_TTL_MS` | capture 字节 TTL（默认 600000，即 10 分钟） |
| `COMPUTER_CAPTURE_MAX_EDGE` | 预览图最长边（默认 1568，视觉模型友好） |

模型调度规则见仓库内的
[`computer-mcp-execution` Skill](skills/computer-mcp-execution/SKILL.md)：结构化优先、
Vision 仅作 fallback、`computer_click` 三种定位方式严格互斥。完整对话历史、历史 reasoning、
旧图片保留和逐轮动态工具集属于 Host/Agent Runtime；MCP Server 只负责压缩单次 Tool Result
与静态工具面，不能从宿主上下文中删除历史消息。

### 方式 2：CLI 直接调试（不经过 MCP）

桌面 Runtime 自带 CLI，适合手动验证权限与能力：

```bash
target/release/computer-runtime capabilities        # 查看当前平台能力与权限状态
target/release/computer-runtime windows             # 枚举窗口（稳定 windowId）
target/release/computer-runtime observe             # 观察活动窗口元素树
target/release/computer-runtime screenshot out.png  # 全屏截图
target/release/computer-runtime click 655,544       # 物理点击（自动激活窗口）
target/release/computer-runtime key cmd+a           # 快捷键（cmd+a / enter / esc 等）
target/release/computer-runtime --mock observe      # Mock 平台，无需 GUI/权限
```

### macOS 截图后端与排障

macOS 14+ 默认使用 ScreenCaptureKit。SCK 的完整异步管线由 Clang/ARC 原生桥接层执行：

```text
getShareableContent → 选择 SCDisplay / SCWindow
                    → 构建 SCContentFilter / SCStreamConfiguration
                    → SCScreenshotManager → retained CGImageRef → Rust RGBA
```

桥接层不会在 `getShareableContent` completion handler 内等待嵌套截图 completion，
避免占住 ScreenCaptureKit 的内部串行队列。每次原生请求有 10 秒上限；失败时自动尝试系统
`/usr/sbin/screencapture`，并在日志和 capability 的 `backend` 中诚实显示 fallback。

正常输出应类似：

```json
{
  "screen_capture": {
    "permission": true,
    "available": true,
    "backend": "screencapturekit"
  }
}
```

如果 `permission` 为 `true`，但 backend 变成 `screencapture-cli`，请先确认启动 Runtime
的终端或 MCP 宿主已经获得“屏幕与系统音频录制”权限。若问题只发生在反复覆盖的
`target/release/computer-runtime`，把二进制复制到稳定安装路径后重新授权该宿主：

```bash
cargo build --release -p computer-runtime-ipc
cp target/release/computer-runtime /absolute/stable/path/computer-runtime
/absolute/stable/path/computer-runtime capabilities
/absolute/stable/path/computer-runtime screenshot /tmp/computer-runtime-check.png
```

不要通过长期降低 Rust release 优化级别规避该问题；当前实现使用默认 opt3，并已在同一
release 执行实体上完成全屏截图 200/200、指定窗口截图 200/200 的零 fallback 验收。

### 方式 3：SDK 编程调用（TypeScript）

```ts
import { RuntimeClient } from "computer-runtime-client-sdk";

const client = new RuntimeClient({
  binaryPath: "/absolute/path/to/computer-use-mcp/target/release/computer-runtime",
});
const wins = await client.listWindows();
const obs = await client.observe({ window: wins[0].id });   // 定向观察，不抢焦点
await client.click({ elementId: "ui_5" });                  // 语义点击
await client.stop();                                        // 回收子进程
```

---

## 四、快速自检

配置完成后，按顺序跑一遍即可确认链路健康：

```bash
# 1. 权限与能力（macOS 上应看到 screen_capture.backend = "screencapturekit"）
target/release/computer-runtime capabilities

# 2. 无 GUI 依赖的 Mock 链路
target/release/computer-runtime --mock observe

# 3.（可选）跑自动化测试验证完整安装
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
node tests/integration/run.mjs --mock   # Mock 桌面集成
node tests/integration/run.mjs          # 真机桌面集成（自动拉起测试 GUI）
node tests/browser/run.mjs              # 浏览器 Fast Path 集成（本地测试站点）
```

---

## 五、平台支持状态

| 能力 | macOS | Windows | Linux X11 | Browser |
| --- | --- | --- | --- | --- |
| 窗口枚举 + 稳定 windowId | ✅ 已验证 | ✅* | ✅* | page_N ✅ |
| observe(windowId) 定向观察 | ✅ 已验证 | ✅* | ✅* | ✅ |
| 窗口激活（autoActivate） | ✅ 已验证 | ✅* | ✅* | n/a |
| 语义动作（AX / UIA / AT-SPI / locator） | ✅ 已验证 | ✅* | ✅* | ✅ |
| 物理输入（CGEvent / SendInput / XTest） | ✅ 已验证 | ✅* | ✅*（ASCII） | ✅ |
| 截图（全屏 / 指定窗口） | ✅ 已验证 | ✅* | 仅全屏 | ✅ |
| waitFor / verify | ✅ 已验证 | ✅ | ✅ | ✅ 事件驱动 |

\* 代码完成并在对应平台目标上通过编译 + 单测（CI 三平台覆盖），真机 GUI 集成验收待对应平台环境。当前版本推荐在 **macOS** 上使用。

---

**测试与基准（面向贡献者）**

```bash
cargo test --workspace                  # Rust 单元测试 + Mock 全流程
npm run test:unit                       # TS 单元测试
node tests/integration/mcp_verify.mjs   # MCP 20 工具面端到端
node tests/soak.mjs                     # 稳定性压测（mock 1000 轮 / --real 300 轮）
node benchmarks/bench.mjs               # 性能基准（截图/observe p50/p95/max）
node benchmarks/bench.mjs --browser     # 浏览器链路基准
```

---

## 六、目录结构

```
runtime/core             平台无关核心（Window Registry、Element Registry、wait/verify、事件抽象、Mock）
runtime/platform/macos   AX + CGEvent + CGWindowList + ScreenCaptureKit（Clang/ARC bridge）
runtime/platform/windows UIA COM + Win32 + SendInput + GDI
runtime/platform/linux   AT-SPI (D-Bus) + x11rb + XTest + XGetImage
runtime/ipc              computer-runtime 二进制（stdio JSON-RPC + CLI）
packages/protocol        冻结协议类型（v0.2.0）
packages/client-sdk      类型化客户端（参数校验 + 生命周期管理）
packages/browser-runtime 浏览器运行时（playwright-core，自动探测本机浏览器）
packages/mcp-server      MCP Server（20 tools）
apps/test-gui            Electron 测试 GUI（双窗口 / 延迟状态 / disabled 控件）
apps/test-web            本地测试站点（login/search/modal/tabs/dynamic/navigation）
tests/                   桌面集成 + 浏览器集成 + MCP E2E + soak
benchmarks/              性能基准脚本与结果
```