跨平台 GUI 自动化运行时 + MCP Server。用同一套统一 API 在 macOS / Windows / Linux(X11) 上完成桌面 GUI 元素的读取、点击、输入、快捷键和截图，并通过 Playwright + DOM/ARIA 提供浏览器高速结构化控制；桌面操作提供稳定 windowId、事件式 waitFor 与结果 verify。全部能力通过 MCP（Model Context Protocol） 对外暴露，可供任意 MCP 宿主（如 AI 助手）直接驱动。
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 桥接层（ |
系统权限（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+。
Related MCP server: Touchpoint
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 buildmacOS 构建时，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，之后即插即用。
在你的 MCP 宿主配置文件（如 mcp.json / claude_desktop_config.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 个） |
|
browser.*（浏览器，11 个） |
|
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 里）：
变量 | 作用 |
| 使用内置 Mock 平台——无需真实 GUI 与系统权限，用于验证整条链路 |
| browser.* 用有头浏览器（默认无头） |
| 关闭 |
| 开启视觉 grounding（默认关闭； |
| 视觉 provider（默认 mock，纯本地）； |
| 所有远程 provider 的第二道开关：不设置则绝不会向外部端点上传截图 |
|
|
| Managed Vision 的重试上限（默认 1）和图像上限（默认 8MiB） |
| 静态工具面；默认 |
| 把 schema 字符数、Tool Result 字节数、元素数和视觉尝试写到 stderr；不会回传给模型 |
| 截图返回语义，默认 |
| 短期过渡：同 |
| 显式允许 |
| capture 字节 TTL（默认 600000，即 10 分钟） |
| 预览图最长边（默认 1568，视觉模型友好） |
模型调度规则见仓库内的
computer-mcp-execution Skill：结构化优先、
Vision 仅作 fallback、computer_click 三种定位方式严格互斥。完整对话历史、历史 reasoning、
旧图片保留和逐轮动态工具集属于 Host/Agent Runtime；MCP Server 只负责压缩单次 Tool Result
与静态工具面，不能从宿主上下文中删除历史消息。
桌面 Runtime 自带 CLI，适合手动验证权限与能力：
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 14+ 默认使用 ScreenCaptureKit。SCK 的完整异步管线由 Clang/ARC 原生桥接层执行：
getShareableContent → 选择 SCDisplay / SCWindow
→ 构建 SCContentFilter / SCStreamConfiguration
→ SCScreenshotManager → retained CGImageRef → Rust RGBA桥接层不会在 getShareableContent completion handler 内等待嵌套截图 completion，
避免占住 ScreenCaptureKit 的内部串行队列。每次原生请求有 10 秒上限；失败时自动尝试系统
/usr/sbin/screencapture，并在日志和 capability 的 backend 中诚实显示 fallback。
正常输出应类似：
{
"screen_capture": {
"permission": true,
"available": true,
"backend": "screencapturekit"
}
}如果 permission 为 true，但 backend 变成 screencapture-cli，请先确认启动 Runtime
的终端或 MCP 宿主已经获得“屏幕与系统音频录制”权限。若问题只发生在反复覆盖的
target/release/computer-runtime，把二进制复制到稳定安装路径后重新授权该宿主：
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 验收。
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(); // 回收子进程配置完成后，按顺序跑一遍即可确认链路健康：
# 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 上使用。
测试与基准（面向贡献者）
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/ 性能基准脚本与结果This server cannot be deployed
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
AI-powered web automation. Navigate websites using AI agents for one page or a thousand
