MCP Computer Use
by FloraAurella
README.md
# MCP Computer Use
当前开发版本：**v0.4.1**
最新预发布版本：**[v0.4.1-rc2](https://github.com/FloraAurella/mcp-computer-use/releases/tag/v0.4.1-rc2)**
MCP Computer Use 是一套面向 AI Agent 的本地计算机操作运行时。它把桌面无障碍树、物理输入、截图、浏览器 DOM/ARIA、视觉定位、等待与结果验证统一成 MCP 工具，让支持 Model Context Protocol 的宿主可以用一套稳定接口控制 macOS、Windows、Linux X11 和 Chromium 系浏览器。
项目不仅提供底层 MCP Server，还包含一个有界上下文的 Reference Agent Runtime、一套原生 Electron Agent Client，以及用于约束模型调度行为的 `computer-mcp-execution` Skill。
> 这是本地 GUI 自动化项目，不是云端网页爬虫，也不是适合部署到无桌面容器里的常驻服务。桌面工具必须运行在拥有真实登录会话、系统无障碍权限和屏幕录制权限的机器上；纯浏览器工具可以在无头模式运行。
---
## 目录
- [项目解决什么问题](#项目解决什么问题)
- [核心能力](#核心能力)
- [架构与运行方式](#架构与运行方式)
- [工具面与引用模型](#工具面与引用模型)
- [环境要求](#环境要求)
- [从源码构建](#从源码构建)
- [部署方式一：接入现有 MCP 宿主](#部署方式一接入现有-mcp-宿主)
- [部署方式二：运行原生 Electron Agent Client](#部署方式二运行原生-electron-agent-client)
- [部署方式三：运行 Reference Agent CLI](#部署方式三运行-reference-agent-cli)
- [视觉定位配置](#视觉定位配置)
- [平台权限与系统准备](#平台权限与系统准备)
- [部署后验证](#部署后验证)
- [升级与回滚](#升级与回滚)
- [安全建议](#安全建议)
- [常见错误与排障](#常见错误与排障)
- [开发与测试](#开发与测试)
- [目录结构](#目录结构)
- [当前限制](#当前限制)
---
## 项目解决什么问题
传统 GUI Agent 往往把每一步都交给截图和坐标：模型反复看整屏、猜位置、点击，再用下一张整屏截图确认。这样容易出现四类问题：
1. **不稳定**：窗口移动、缩放、主题变化后坐标立即失效。
2. **昂贵**：完整截图、无障碍树和历史 reasoning 被反复回灌，几轮就可能消耗大量上下文。
3. **难恢复**：元素过期、页面跳转、视觉目标失效时，模型不知道应该重新观察还是重试动作。
4. **难验收**：动作执行成功不等于任务完成，缺少明确的 post-condition 和新鲜证据。
本项目采用“结构化优先、视觉兜底、动作后验证”的执行模型：
```text
已有有效 ui_N / web_N / visual_N
│
▼
直接执行动作
│
▼
wait / verify / expect
│
▼
fresh evidence_N
│
▼
完成任务
没有有效目标
│
├─ 桌面：computer_observe → computer_resolve → Vision fallback
└─ 浏览器：browser_observe → DOM/ARIA locator
```
视觉不是默认路径，裸坐标是最后兜底。模型看到的是紧凑的语义元素、引用 ID 和结构化错误，而不是无限增长的原始 UI 历史。
---
## 核心能力
### 桌面自动化
- 跨平台窗口枚举和稳定 `window_N` 引用。
- 通过 macOS AX、Windows UIA、Linux AT-SPI 读取结构化元素树。
- 语义点击、输入、快捷键与窗口激活。
- 必要时使用 CGEvent、SendInput 或 XTest 执行物理输入。
- 全屏或指定窗口截图。
- 基于条件的事件式 `wait` 和结果 `verify`，主路径不使用固定 sleep。
- 元素代际和过期检测，拒绝把陈旧 `ui_N` 当成当前元素继续操作。
### 浏览器 Fast Path
- 使用 `playwright-core` 启动 Chrome、Edge 或可用 Chromium。
- 通过 DOM/ARIA 读取可交互元素，而不是把完整 HTML 交给模型。
- 会话级全局 `web_N`、页面级 `page_N` 和代际过期保护。
- 区分 `STALE_ELEMENT`、`ELEMENT_PAGE_MISMATCH`、`ELEMENT_NOT_FOUND` 与真实 `LOCATOR_FAILED`。
- 支持导航、点击、输入、快捷键、截图、事件等待和验证。
- `browser_evaluate` 属于高能力调试工具，可以通过环境变量彻底关闭。
### 截图和视觉
- 截图默认返回小型 `capture_N` 元数据引用，不把 base64 塞进模型上下文。
- 像素保存在 MCP Server 的短期 Capture Store 中，默认 TTL 10 分钟，并受 LRU 和总字节上限约束。
- 需要图片时通过 MCP resource `computer://capture/{capture_N}` 显式读取。
- 支持区域裁剪、视觉 grounding 和带 provenance 的 `visual_N`。
- 远程视觉上传默认关闭，需要两个独立开关同时启用。
- Context Firewall 会阻止 base64 或二进制内容意外进入文本 Tool Result。
### Reference Agent Runtime
- 每轮从紧凑 TaskState 重建 Working Context，不保存逐字 reasoning 或旧图片。
- 按 `discover / act / settle / recover` 阶段动态暴露少量工具。
- 本地拒绝互斥参数冲突、重复失败调用和危险的未知结果重试。
- 对模型超时、用户取消、视觉格式错误、过期元素和完成证据失败提供有界恢复。
- 完成时必须提交动作后的新鲜成功证据，避免“点完就宣布成功”。
### 原生 Electron Client
- 在 Electron 主进程中管理模型 Provider、MCP stdio、Rust Runtime 和 Capture 生命周期。
- API Key 使用系统 `safeStorage` 加密，不返回 Renderer。
- 按任务选择 `desktop-vision` 或 `browser` 最小工具面。
- 浏览器任务在同一 MCP 会话中确定性预启动 Browser Runtime，避免首步直接导航时出现 `BROWSER_NOT_RUNNING`。
- UI 展示任务预算、路由阶段、工具结果、恢复原因和完成证据。
---
## 架构与运行方式
```text
┌──────────────────────────────┐
│ MCP Host / Electron Client │
│ Reference Agent / other LLM │
└──────────────┬───────────────┘
│ MCP over stdio
┌────────▼────────┐
│ MCP Server │
│ schema / policy │
│ capture store │
└───────┬─────────┘
┌───────────────┴────────────────┐
│ │
┌─────────▼──────────┐ ┌──────────▼──────────┐
│ Desktop Runtime │ │ Browser Runtime │
│ Rust stdio JSON-RPC │ │ TypeScript │
└─────────┬──────────┘ │ Playwright + ARIA │
│ └──────────┬──────────┘
┌──────────┼───────────┐ │
▼ ▼ ▼ ▼
macOS Windows Linux X11 Chrome / Edge / Chromium
AX/SCK UIA AT-SPI/XTest
```
各层职责：
| 层 | 职责 | 是否依赖模型 |
| --- | --- | --- |
| Rust Desktop Runtime | 平台 API、窗口和元素注册、输入、截图、wait/verify | 否 |
| Browser Runtime | 页面生命周期、DOM/ARIA 压缩、Playwright locator | 否 |
| MCP Server | 工具 Schema、Capture Store、Context Firewall、静态工具面 | 否 |
| Reference Agent Runtime | 上下文、路由、决策、恢复、完成证据 | 是，可选 |
| Electron Agent Client | 本地配置、Provider、任务 UI、进程生命周期 | 是，可选 |
| Execution Skill | 约束模型何时 observe、resolve、vision、action、verify | 由 Host 选择 |
MCP Server 不是常驻守护进程。通常由 MCP Host 为一个会话启动 Server；Server 再启动桌面 Runtime，并在会话结束时回收自己拥有的进程。Browser Runtime 同样是 MCP 会话内状态，不等同于系统里已经打开的普通 Chrome 窗口。
---
## 工具面与引用模型
项目完整注册 25 个工具，但生产环境通常应通过 `COMPUTER_TOOL_PROFILE` 只暴露当前场景需要的子集：
| Profile | 数量 | 适用场景 |
| --- | ---: | --- |
| `desktop-core` | 9 | 纯结构化桌面操作，不需要截图或视觉 |
| `desktop-vision` | 13 | 桌面结构化操作 + Capture/Vision fallback |
| `browser` | 10 | 浏览器导航和 DOM/ARIA 操作，不开放 evaluate |
| `full` | 25 | 兼容旧 Host；同时开放桌面、浏览器和调试能力 |
| `debug` | 25 | 与 full 同工具面，并开启额外上下文指标 |
完整工具分类：
| 分类 | 工具 |
| --- | --- |
| Desktop | `computer_capabilities` `computer_windows` `computer_observe` `computer_resolve` `computer_click` `computer_type` `computer_key` `computer_screenshot` `computer_wait` `computer_verify` `computer_visual_observe` `computer_screenshot_image` `computer_capture_region` `computer_register_visual_target` |
| Browser | `browser_launch` `browser_pages` `browser_observe` `browser_navigate` `browser_click` `browser_type` `browser_key` `browser_screenshot` `browser_wait` `browser_verify` `browser_evaluate` |
常见引用：
| 引用 | 来源 | 生命周期 |
| --- | --- | --- |
| `window_N` | `computer_windows` | 绑定当前 Runtime 的窗口注册表 |
| `ui_N` | `computer_observe` / `computer_resolve` | 绑定窗口和观察代际；界面变化后可能过期 |
| `page_N` | `browser_launch` / `browser_pages` | 绑定当前 Browser Runtime 会话 |
| `web_N` | `browser_observe` | 绑定页面和 DOM 代际；导航或重新观察后可能过期 |
| `capture_N` | screenshot / region capture | 服务端短期引用，默认 10 分钟 |
| `visual_N` | visual observe / register target | 绑定 capture、窗口位置和 TTL |
| `evidence_N` | wait / verify / click expect | Agent Runtime 的完成证据，必须新鲜且成功 |
`computer_click` 的三种定位方式严格互斥：只传 `target`，或只传 `query`，或只传 `x + y`。不要为了“保险”同时传多个定位方式。
模型调度规范见 [`skills/computer-mcp-execution/SKILL.md`](skills/computer-mcp-execution/SKILL.md)。
---
## 环境要求
### 通用依赖
| 依赖 | 最低要求 | 推荐 | 用途 |
| --- | --- | --- | --- |
| Node.js | 20.19 | 当前 Node 22 LTS | MCP Server、Browser Runtime、Agent、Electron 构建 |
| npm | 随 Node 安装 | 与 lockfile 兼容的当前版本 | 安装 Workspace 依赖 |
| Rust | stable | 最新 stable | 编译桌面 Runtime |
| Git | 2.x | 当前稳定版 | 克隆和升级 |
| Chrome / Edge | 可选但强烈推荐 | 当前稳定版 | Browser Runtime 首选浏览器 |
`playwright-core` 不保证为每台机器下载浏览器。服务器会依次尝试 Chrome、Edge 和 Playwright 可解析的 Chromium；部署机器上安装 Chrome 或 Edge 是最稳妥的选择。
### 平台要求
| 平台 | 要求 | 当前状态 |
| --- | --- | --- |
| macOS | 建议 macOS 14+；需要 Xcode Command Line Tools、辅助功能和屏幕录制权限 | 主要验证平台 |
| Windows | Windows 10 1809+；使用 UIA、Win32、SendInput、GDI | 构建和单测覆盖，真机 GUI 仍需环境验收 |
| Linux | X11 会话、AT-SPI、XTest；Wayland 当前不支持 | 构建和单测覆盖，建议先在 Xvfb/测试桌面验证 |
---
## 从源码构建
### 1. 克隆固定版本
生产部署建议固定到 release tag，不要直接跟随开发分支：
```bash
git clone --branch v0.4.1-rc2 --depth 1 https://github.com/FloraAurella/mcp-computer-use.git
cd mcp-computer-use
```
需要完整历史时去掉 `--depth 1`。
### 2. 安装 Node 依赖
```bash
npm ci
```
仓库包含 `package-lock.json`，部署和 CI 应使用 `npm ci` 获得可复现依赖；只有修改依赖时才使用 `npm install`。
### 3. 编译 TypeScript 工作区
```bash
npm run build
```
关键产物：
```text
packages/mcp-server/dist/index.js
packages/agent-runtime/dist/index.js
apps/reference-agent/dist/cli.js
```
### 4. 编译桌面 Runtime
```bash
cargo build --release -p computer-runtime-ipc
```
产物位置：
```text
macOS / Linux: target/release/computer-runtime
Windows: target/release/computer-runtime.exe
```
### 5. 可选：构建 Electron Client
```bash
npm run client:build
```
### macOS 编译准备
先安装 Xcode Command Line Tools：
```bash
xcode-select --install
```
`runtime/platform/macos/build.rs` 会调用 `xcrun clang` 编译一个 Objective-C/ARC ScreenCaptureKit 桥接层，不需要额外下载第三方原生库。
### Linux X11 准备
Ubuntu/Debian 可安装运行和 Electron 测试所需组件：
```bash
sudo apt-get update
sudo apt-get install -y at-spi2-core xvfb libgtk-3-0 libnss3 libasound2 libgbm1 x11-utils wmctrl
```
确认当前不是纯 Wayland 会话，并且 GUI 进程能访问 `DISPLAY` 和 AT-SPI accessibility bus。无交互桌面的普通 Docker 容器无法直接控制宿主桌面。
### Windows 准备
在 PowerShell 中安装 Rust、Node.js 和 Git 后执行：
```powershell
npm ci
npm run build
cargo build --release -p computer-runtime-ipc
```
Windows 不需要 macOS 的 TCC 授权，但目标应用必须运行在与 Runtime 相同的交互式用户会话中。以 Windows Service、Session 0 或无桌面 CI 运行时无法控制普通用户桌面。
---
## 部署方式一：接入现有 MCP 宿主
这是最轻量的部署方式：保留你现有的 AI Host，只把本仓库的 MCP Server 注册进去。
### 1. 选择稳定安装目录
构建完成后可以直接使用仓库内产物。macOS 上长期部署更建议把 `computer-runtime` 复制到不会被 Cargo 反复覆盖的稳定绝对路径，再对启动 Host 授权一次。无论采用哪种方式，MCP 配置都应使用绝对路径。
### 2. macOS / Linux 配置示例
将下面内容合并到宿主的 MCP JSON 配置中，并替换 `/absolute/path/to/mcp-computer-use`：
```json
{
"mcpServers": {
"computer": {
"command": "/absolute/path/to/node",
"args": [
"/absolute/path/to/mcp-computer-use/packages/mcp-server/dist/index.js"
],
"env": {
"COMPUTER_RUNTIME_BIN": "/absolute/path/to/mcp-computer-use/target/release/computer-runtime",
"COMPUTER_TOOL_PROFILE": "desktop-vision",
"COMPUTER_SCREENSHOT_MODE": "reference",
"COMPUTER_ENABLE_EVALUATE": "0"
}
}
}
}
```
如果 Host 能从 PATH 正确找到 Node，`command` 可以写成 `node`；图形应用从 Finder/Dock 启动时 PATH 往往不完整，因此生产配置推荐写 Node 的绝对路径。
### 3. Windows 配置示例
JSON 中的反斜杠必须写成双反斜杠：
```json
{
"mcpServers": {
"computer": {
"command": "C:\\Program Files\\nodejs\\node.exe",
"args": [
"C:\\mcp-computer-use\\packages\\mcp-server\\dist\\index.js"
],
"env": {
"COMPUTER_RUNTIME_BIN": "C:\\mcp-computer-use\\target\\release\\computer-runtime.exe",
"COMPUTER_TOOL_PROFILE": "desktop-core",
"COMPUTER_SCREENSHOT_MODE": "reference",
"COMPUTER_ENABLE_EVALUATE": "0"
}
}
}
}
```
### 4. 按场景选择工具面
- 只操作桌面结构化 UI：`desktop-core`
- 桌面需要截图和视觉兜底：`desktop-vision`
- 只操作网站：`browser`
- Host 需要同时动态切换桌面和浏览器：`full`
- 排查 Schema 和 Tool Result 大小：`debug`
工具面是在 MCP Server 启动时确定的。修改配置后需要让 Host 重新启动该 MCP 会话。
### 5. 浏览器模式注意事项
外部 MCP Host 应先调用一次 `browser_launch`，再使用 `browser_navigate`、`browser_pages` 或 `browser_observe`。原生 Electron Client 会自动完成预启动；普通 Host 如果跳过 launch，会收到 `BROWSER_NOT_RUNNING`。
默认浏览器是无头模式。需要观察实际窗口时设置：
```json
{
"COMPUTER_BROWSER_HEADED": "1"
}
```
### 6. 常用 MCP Server 环境变量
| 变量 | 默认值 | 作用 |
| --- | --- | --- |
| `COMPUTER_RUNTIME_BIN` | 仓库默认路径或 SDK 配置 | Rust Runtime 绝对路径 |
| `COMPUTER_RUNTIME_ARGS` | 空 | 传给 Runtime `serve` 的参数；`--mock` 可启用 Mock 平台 |
| `COMPUTER_TOOL_PROFILE` | `full` | 静态工具面 |
| `COMPUTER_BROWSER_HEADED` | `0` | `1` 时显示浏览器窗口 |
| `COMPUTER_ENABLE_EVALUATE` | `1` | `0` 时禁用 `browser_evaluate` |
| `COMPUTER_SCREENSHOT_MODE` | `reference` | `reference`、`image` 或 `auto`；生产建议 reference |
| `COMPUTER_ALLOW_RAW_IMAGE_CONTENT` | `0` | 显式允许 raw ImageContent；仅用于已验证安全的 Host |
| `COMPUTER_CAPTURE_TTL_MS` | `600000` | Capture 字节 TTL |
| `COMPUTER_CAPTURE_MAX_EDGE` | `1568` | 视觉预览最长边 |
| `COMPUTER_CONTEXT_METRICS` | `0` | `1` 时把紧凑指标写入 stderr |
| `COMPUTER_RPC_STRICT` | `0` | `1` 时 Runtime 对畸形 JSON-RPC fail-closed |
`COMPUTER_LEGACY_SCREENSHOT=1` 仅用于迁移旧 Host，会恢复原始图片行为并产生弃用警告，不建议新部署使用。
---
## 部署方式二：运行原生 Electron Agent Client
Electron Client 适合希望直接获得完整任务执行 UI、模型配置、预算、轨迹和恢复提示的用户。
### 启动
```bash
npm ci
npm run build
cargo build --release -p computer-runtime-ipc
npm run client:start
```
首次启动后：
1. 打开左下角“设置”。
2. 填写 OpenAI-compatible 模型端点、模型名和 API Key。
3. 选择 `desktop` 或 `browser` surface。
4. 确认 Runtime 和 MCP Server 路径指向本次构建产物。
5. 先执行“测试 MCP”；该操作只测试本地工具握手，不调用外部模型。
6. 再执行“测试模型”；该操作会产生一次很小的纯文本模型请求。
7. 保存后回到执行台运行任务。
远程模型地址必须使用 HTTPS；只有 `127.0.0.1`、`localhost` 或 `::1` 可以使用 HTTP。API Key 由 Electron `safeStorage` 加密保存在用户应用数据目录，不会写进仓库或传回 Renderer。
可通过环境变量提供初始默认值：
| 变量 | 作用 |
| --- | --- |
| `AGENT_MODEL_BASE_URL` | OpenAI-compatible API 根地址，例如 `https://provider.example/v1` |
| `AGENT_MODEL_API_KEY` | 模型 API Key；优先于本地加密设置 |
| `AGENT_MODEL_NAME` | 模型名 |
| `AGENT_MODEL_SUPPORTS_VISION` | `0` 表示模型不支持原生图片输入 |
| `AGENT_ALLOW_REMOTE_IMAGES` | `1` 明确允许把临时图片发送给模型；默认关闭 |
| `AGENT_STRUCTURED_OUTPUT_MODE` | `json_object`、`json_schema` 或 `prompt` |
| `AGENT_CONTEXT_WINDOW_TOKENS` | 模型上下文窗口，默认 131072 |
| `AGENT_MODEL_TIMEOUT_MS` | 单次模型调用超时，客户端默认 60000 |
| `AGENT_MODEL_RETRIES` | Provider 总尝试次数，范围 1–4 |
| `AGENT_SURFACE` | `desktop` 或 `browser` |
| `COMPUTER_RUNTIME_BIN` | 自定义 Rust Runtime 路径 |
| `COMPUTER_MCP_SERVER_ENTRY` | 自定义 MCP Server JS 入口 |
不要把真实 API Key 写入 shell history、README、Git 配置或 MCP JSON。优先在客户端设置页使用系统加密存储，或通过受控的进程环境注入。
---
## 部署方式三：运行 Reference Agent CLI
Reference Agent CLI 适合调试 Agent Runtime、接入自动化流水线或自行开发上层 UI。
### macOS / Linux
```bash
export AGENT_MODEL_BASE_URL="https://provider.example/v1"
export AGENT_MODEL_API_KEY="replace-with-a-secret-from-your-secret-manager"
export AGENT_MODEL_NAME="multimodal-model"
export AGENT_MODEL_SUPPORTS_VISION=1
export AGENT_CONTEXT_WINDOW_TOKENS=131072
export COMPUTER_RUNTIME_BIN="/absolute/path/to/mcp-computer-use/target/release/computer-runtime"
# desktop 是默认 surface
npm run agent:run -- "打开目标窗口，完成操作并验证结果"
# 浏览器任务
AGENT_SURFACE=browser npm run agent:run -- "打开目标网页并验证页面状态"
```
### Windows PowerShell
```powershell
$env:AGENT_MODEL_BASE_URL = "https://provider.example/v1"
$env:AGENT_MODEL_API_KEY = "replace-with-a-secret-from-your-secret-manager"
$env:AGENT_MODEL_NAME = "multimodal-model"
$env:COMPUTER_RUNTIME_BIN = "C:\mcp-computer-use\target\release\computer-runtime.exe"
$env:AGENT_SURFACE = "desktop"
npm run agent:run -- "打开目标窗口，完成操作并验证结果"
```
其他 Agent 变量：
| 变量 | 默认值 | 作用 |
| --- | --- | --- |
| `AGENT_MODEL_TIMEOUT_MS` | `30000` | CLI 单次模型调用超时 |
| `AGENT_MODEL_RETRIES` | `1` | Provider 总尝试次数 |
| `AGENT_INPUT_COST_PER_MILLION` | `0` | 可选输入成本估算 |
| `AGENT_OUTPUT_COST_PER_MILLION` | `0` | 可选输出成本估算 |
| `COMPUTER_MCP_BIN` | 内置 JS 入口 | 自定义 MCP Server executable |
| `COMPUTER_RUNTIME_ARGS` | 空 | 可设置 `--mock` 做无副作用测试 |
CLI 最终输出 compact task state、context profile 和脱敏 telemetry，不输出 Authorization、原始 Provider payload、base64 图片或逐字 reasoning。
---
## 视觉定位配置
视觉 grounding 默认关闭。结构化无障碍树能解决的问题不需要启用视觉。
### 本地 Mock Vision
用于测试协议和恢复链路，不上传截图：
```json
{
"COMPUTER_VISION_ENABLED": "1",
"COMPUTER_VISION_PROVIDER": "mock"
}
```
### OpenAI-compatible Vision Provider
远程图片上传必须同时开启 Vision 和 Remote Upload：
```json
{
"COMPUTER_VISION_ENABLED": "1",
"COMPUTER_VISION_PROVIDER": "openai-compatible",
"COMPUTER_VISION_REMOTE_UPLOAD": "1",
"COMPUTER_VISION_BASE_URL": "https://provider.example/v1",
"COMPUTER_VISION_MODEL": "multimodal-model",
"COMPUTER_VISION_API_KEY": "inject-from-a-secret-manager"
}
```
可调参数：
| 变量 | 默认值 | 作用 |
| --- | --- | --- |
| `COMPUTER_VISION_TIMEOUT_MS` | `20000` | 单次 Provider 超时 |
| `COMPUTER_VISION_MAX_RETRIES` | `1` | Managed Vision 重试上限 |
| `COMPUTER_VISION_MAX_IMAGE_BYTES` | `8388608` | 单张图片最大字节数 |
| `COMPUTER_VISION_MIN_CONFIDENCE` | `0` | 最低接受置信度 |
| `COMPUTER_VISION_TTL_MS` | `2000` | `visual_N` 默认有效期 |
远程视觉会把目标窗口或裁剪区域的像素传给你配置的第三方模型服务。启用前应确认数据分类、隐私要求、服务端保留政策和网络边界。
---
## 平台权限与系统准备
### macOS
在“系统设置 → 隐私与安全性”中，为真正启动 MCP Server/Runtime 的终端或 Host App 开启：
- **辅助功能**：读取 AX 树、语义动作、窗口激活和物理输入。
- **屏幕与系统音频录制**：ScreenCaptureKit 全屏和指定窗口截图。
权限属于启动实体。若从 Terminal 测试正常、从某个 MCP Host 运行失败，应给该 Host 本身授权，而不是只给 Terminal 授权。
macOS 截图能力会分别报告：
- `permission`：TCC 预检结果。
- `available`：真实小尺寸截图探测结果。
- `backend`：`screencapturekit`、`screencapture-cli` 或 `none`。
建议把 release Runtime 放到稳定路径。Cargo 反复替换 `target/release/computer-runtime` 后，系统可能继续关联旧的执行身份。稳定路径只需要重新授权一次。
### Windows
- Runtime 和目标应用必须位于同一登录用户、同一交互式桌面会话。
- 如果目标应用以管理员权限运行，普通权限 Runtime 可能无法操作它；应尽量保持相同完整性级别。
- Windows Service、Session 0 和锁屏状态不是受支持的交互环境。
### Linux X11
- 必须有可访问的 `DISPLAY`。
- 必须有 AT-SPI accessibility bus；缺少时会提示安装 `at-spi2-core`。
- XTest 用于物理输入，当前 X11 文本兜底主要支持 ASCII。
- Wayland 会显式返回 `UNSUPPORTED`，不会静默猜测坐标。
---
## 部署后验证
建议按从底层到上层的顺序验证，便于快速定位问题。
### 1. 验证 Runtime 二进制
```bash
target/release/computer-runtime capabilities
target/release/computer-runtime windows
target/release/computer-runtime observe
```
macOS 正常截图能力示例：
```json
{
"screen_capture": {
"permission": true,
"available": true,
"backend": "screencapturekit"
}
}
```
### 2. 验证无副作用 Mock Runtime
```bash
target/release/computer-runtime --mock observe
```
### 3. 验证 TypeScript 和 MCP
```bash
npm run build
npm run test:profiles
npm run test:mcp
```
### 4. 验证浏览器链路
```bash
node tests/browser/run.mjs
```
### 5. 验证 Agent 和客户端
```bash
npm run test:agent
npm run client:test
npm run client:build
```
### 6. 直接调试 Runtime CLI
```bash
target/release/computer-runtime screenshot runtime-check.png
target/release/computer-runtime click 655,544
target/release/computer-runtime key cmd+a
target/release/computer-runtime --mock observe
```
Windows 将路径替换为 `target\release\computer-runtime.exe`，macOS 快捷键使用 `cmd`，Windows/Linux 通常使用 `ctrl`。
---
## 升级与回滚
### 升级到指定版本
```bash
git fetch --tags origin
git checkout v0.4.1-rc2
npm ci
npm run build
cargo build --release -p computer-runtime-ipc
```
完成后重启 MCP Host 或 Electron Client。正在运行的 MCP 会话不会自动切换到新构建产物。
### 回滚
1. 停止当前 MCP 会话或 Electron Client。
2. 切换到之前验证过的 tag/commit。
3. 重新执行 `npm ci`、TypeScript build 和 Rust release build。
4. 确认 MCP 配置仍指向对应工作目录的绝对路径。
5. 重新启动 Host 并运行 `computer_capabilities`。
不要混用不同版本的 `packages/mcp-server/dist` 和 `computer-runtime` 二进制；协议和错误模型可能不一致。
---
## 安全建议
- 生产环境优先使用最小 `COMPUTER_TOOL_PROFILE`。
- 不需要任意页面脚本时设置 `COMPUTER_ENABLE_EVALUATE=0`。
- 保持 `COMPUTER_SCREENSHOT_MODE=reference`，不要默认开放 raw ImageContent。
- 只有在理解数据去向后才启用 `COMPUTER_VISION_REMOTE_UPLOAD=1`。
- API Key、Cookie 和用户脚本不要提交到 Git；使用系统密钥存储或 Secret Manager。
- MCP Server 和 Runtime 使用普通用户权限运行，避免不必要的管理员/root 权限。
- 对高风险目标应用使用 Host 的 allowlist 或任务 scope。
- 将 stderr 日志视为运行诊断信息；不要在自定义代码里记录 Authorization 或模型原始请求。
- Browser Runtime 只清理自己启动并标记的浏览器进程，不应对系统中其他 Chrome 进程做广泛终止。
本仓库根目录的 `scripts/` 被明确列入 `.gitignore`，用于保留本机私有自动化脚本，不属于发布内容。
---
## 常见错误与排障
| 错误 | 含义 | 推荐处理 |
| --- | --- | --- |
| `BROWSER_NOT_RUNNING` | 当前 MCP 会话还没有 Browser Runtime | 先调用 `browser_launch`；Electron Client 会自动预启动 |
| `STALE_ELEMENT` | `ui_N` 或 `web_N` 来自旧代际 | 重新 observe/resolve，不要重复旧动作 |
| `ELEMENT_PAGE_MISMATCH` | `web_N` 属于另一个页面 | 在正确 `page_N` 上重新 observe |
| `ELEMENT_NOT_FOUND` | ID 从未签发或已无法解析 | 检查 ID 来源并重新观察 |
| `LOCATOR_FAILED` | Playwright 找到引用记录但真实动作失败 | 检查页面状态、遮挡、disabled 状态和 locator |
| `VISION_INVALID_GROUNDING` | 视觉模型输出不符合 grounding Schema | 检查 structured output 模式；Runtime 只做一次同帧格式修复 |
| `VISION_NO_TARGET` | 当前画面没有可靠目标 | 回到 structured observe，或把 query 写得更具体；不要无限改写重试 |
| `STALE_VISUAL_TARGET` | `visual_N` 的 capture、窗口位置或 TTL 已变化 | 重新截图并 grounding |
| `SCREEN_CAPTURE_PERMISSION_DENIED` | 系统明确拒绝截图权限 | 给实际 Host/终端开启屏幕录制权限后重启 |
| `SCREEN_CAPTURE_BACKEND_UNAVAILABLE` | 找不到可用截图后端 | 检查系统版本、会话类型和 Xcode/系统组件 |
| `SCREEN_CAPTURE_BACKEND_FAILED` | 后端存在但执行失败 | 查看 capability backend 和 stderr，尝试稳定 Runtime 路径 |
| `MODEL_DECISION_INVALID` | 模型决策 JSON 不符合严格协议 | 选择兼容 structured output 模式，查看字段级诊断 |
| `MODEL_TIMEOUT` | 模型 Provider 超时 | 检查网络/端点，适当增加 `AGENT_MODEL_TIMEOUT_MS` |
| `MODEL_ABORTED` / `This operation was aborted` | 用户取消或 AbortSignal 中断 | 如果不是主动取消，检查 UI 是否重启/任务是否被替换 |
| `evidenceIds: Array must contain at least 1 element(s)` | complete 没有提交证据 | 先 wait/verify，再复制返回的 `evidence_N` |
| `no fresh successful evidence after the last mutation` | 最后一次动作后没有新成功证据 | 不要重复动作；验证当前 post-action 状态后再 complete |
| `BINARY_PAYLOAD_IN_TEXT` | Context Firewall 检测到图片/base64 进入文本 | 改用 CaptureReference resource，不要 stringify 图片 |
### macOS permission=true 但截图仍失败
1. 确认获得授权的是实际启动 Runtime 的 App。
2. 运行 `computer-runtime capabilities` 查看真实 backend。
3. 把二进制复制到稳定路径并重新授权。
4. 重启 Host；TCC 变化通常不会对已运行进程即时生效。
5. 不要通过长期降低 Rust release 优化级别规避问题。
### 浏览器无法启动
1. 安装当前稳定版 Chrome 或 Edge。
2. 确认当前用户有权限执行浏览器。
3. 无头 Linux 检查 Chromium 运行依赖和沙箱限制。
4. 设置 `COMPUTER_BROWSER_HEADED=1` 观察真实启动错误。
5. 查看 MCP stderr 中的 `could not launch Chromium/Chrome/Edge` 具体原因。
---
## 开发与测试
### 常用命令
```bash
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
npm run build
npm run test:unit
npm run test:agent
npm run client:test
npm run test:profiles
npm run test:mcp
node tests/integration/run.mjs --mock
node tests/integration/run.mjs
node tests/browser/run.mjs
```
### 测试分层
| 测试 | 目的 | 是否需要真实 GUI |
| --- | --- | --- |
| Rust unit / Mock | 核心状态、协议、wait/verify | 否 |
| TS unit | Browser Registry、Capture、Vision、Firewall | 否 |
| Agent tests | Context、路由、恢复、证据、MCP boundary | 否 |
| MCP E2E | 完整工具 Schema 和 Capture transport | 使用 Mock/本地站点 |
| Browser E2E | launch/navigate/observe/action/wait/verify | 需要可启动浏览器 |
| Desktop integration | 窗口、输入、截图、焦点独立性 | 是 |
测试不依赖公网或真实 LLM。涉及模型的 Agent 测试使用 scripted/mock provider。
---
## 目录结构
```text
runtime/core 平台无关核心：Registry、wait/verify、事件、Mock
runtime/platform/macos AX、CGEvent、ScreenCaptureKit Clang/ARC bridge
runtime/platform/windows UIA、Win32、SendInput、GDI
runtime/platform/linux AT-SPI、X11、XTest、XGetImage
runtime/ipc computer-runtime CLI 与 stdio JSON-RPC
packages/protocol 共享协议类型和版本
packages/client-sdk Runtime 类型化客户端和生命周期
packages/browser-runtime Browser Fast Path、page_N/web_N Registry
packages/vision-runtime Vision Provider、grounding、visual_N
packages/mcp-server MCP tools、Capture Store、Context Firewall
packages/agent-runtime TaskState、Context、Router、Recovery、Completion
apps/reference-agent Reference Agent CLI
apps/agent-client Electron Agent Client
apps/test-gui 桌面集成测试 GUI
apps/test-web Browser E2E 本地站点
skills/computer-mcp-execution 模型工具调度 Skill
tests/ 单元、Agent、MCP、桌面和浏览器测试
benchmarks/ 性能基准
```
---
## 当前限制
- macOS 是当前主要真机验证平台；Windows 和 Linux 的代码、编译与单测已覆盖，但生产部署前仍应在目标机器做 GUI 验收。
- Linux 只支持 X11，不支持 Wayland。
- Linux 物理文本输入兜底主要支持 ASCII；优先使用 AT-SPI 语义输入。
- Browser Runtime 是会话内新浏览器，不接管用户现有浏览器个人资料或登录态。
- `playwright-core` 不保证自动下载浏览器，部署机器建议预装 Chrome 或 Edge。
- 无真实桌面、无权限或被锁定的会话无法执行桌面 GUI 自动化。
- 视觉 grounding 受截图质量、目标描述和 Provider 输出约束；低置信度或歧义目标会 fail-closed。
- Reference Agent 是参考实现，不替代 Host 自身的审批、权限、数据治理和高风险操作确认机制。
---
仓库地址：<https://github.com/FloraAurella/mcp-computer-use>
问题反馈：<https://github.com/FloraAurella/mcp-computer-use/issues>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues