[Python] Cua 全栈拆解：15k Star 开源 Computer-Use Agent 从沙箱到评测的落地指南

项目卡片

• 项目：Cua
• 状态：14.4k Star / MIT 协议 / 活跃迭代中（2026-01 至今）
• 一句话判断：目前最完整的开源 Computer-Use Agent 基础设施，从沙箱到评测到桌面虚拟化全覆盖

Anthropic 的 Computer Use API 让 LLM 能看屏幕、点鼠标、敲键盘。但拿到 API 之后你会发现，落地的硬活才刚开始：隔离环境怎么建？跨平台截图怎么统一？评测怎么跑？

Cua 要做的事情很简单粗暴——把这整条链路全部开源。沙箱环境、SDK、评测基准、macOS 虚拟化，甚至还能让你的编码 Agent 直接操控桌面应用。GitHub 上 14.4k Star，MIT 协议，三个月迭代到现在这个体量。

Cua 的整体架构：从底层虚拟化到上层 Agent，组件之间通过统一 API 连接

五个组件，各管一块

拆开 monorepo 看内部结构，Swift、Python、TypeScript 三种语言并存，各自负责不同层面：

Cua SDK（Python）—— 沙箱 + Agent 的核心抽象层。一行代码创建任意 OS 的沙箱环境：

from cua import Sandbox, Image

async with Sandbox.ephemeral(Image.linux()) as sb:
    await sb.shell.run("echo hello")
    await sb.mouse.click(100, 200)
    await sb.keyboard.type("Hello from Cua!")

切换 OS 只需改 Image 参数：.linux()、.macos()、.windows()、.android()，底层会自动选择对应的运行时（Docker / QEMU / Lume / 模拟器）。

Cua Driver（Swift，仅 macOS）—— 这个组件让我觉得整个项目不只是在做 SDK 封装。它解决了一个很具体的问题：不抢焦点、不抢光标地操控任意 macOS 原生应用。基于 Accessibility API + ScreenCaptureKit，30+ MCP 工具直接暴露给 Claude Code / Cursor 调用。

CuaBot（TypeScript）—— 让任意编码 Agent 获得桌面操作能力。cuabot claude 一条命令把 Claude Code 扔进 Docker 沙箱，里面跑的是完整 Ubuntu 22.04 桌面。

Cua-Bench（Python）—— 评测框架，支持 OSWorld、ScreenSpot、Windows Arena。Gym-like API（reset() → step() → evaluate()），还能导出轨迹做 RL 训练。

Lume（Swift，仅 Apple Silicon）—— 基于 Apple Virtualization.Framework 的 VM 管理工具。IPSW 直装 macOS，支持 Rosetta 二进制翻译和 VirtioFS 文件共享。

Transport 抽象：同一套 API，不同后端

Cua SDK 最关键的设计决策就在这里。Sandbox 类暴露统一的 .mouse、.keyboard、.shell、.screen 接口，底层靠不同的 Transport 实现与各类后端通信：

Transport 抽象层结构：上层 API 统一，下层对接 Docker / QEMU / Lume / Cloud / Android 等不同运行时

这意味着你的 Agent 代码不用关心跑在 Docker 容器、云 VM 还是本地 macOS 虚拟机——API 层完全一致。对只想快速上手的用户，我建议直接用 Cloud 模式或 Docker 单一后端，别上来就搞多 Transport 切换。

Cua Driver：后台操控的技术深水区

这是整个项目技术含量最高的部分。macOS 上“不抢焦点地操控后台应用”要同时解决几个棘手问题：

焦点欺骗。SyntheticAppFocusEnforcer 在执行操作前临时给目标窗口写入 AXFocused=true 和 AXMain=true，让 AppKit 内部状态机以为“我有焦点”。操作完立即恢复原始值。巧妙地绕开了 NSRunningApplication.activate() 会把窗口顶到前台的问题。

像素级输入路由。键盘事件走 CGEvent.postToPid 直接发到目标 PID，不经过前台路由。鼠标点击用的是 yabai 的 SLEventPostToPid（SLPS 事件）——目标 App 变成 AppKit-active 但窗口不会升起。

智能 AX 元素定位。AXInput 的 screenCenter(of:) 在 AX 报告的元素中心落在可见区域外时，会对元素做 5×5 网格探测，以找到真正可点击的位置。这类边界 case（比如 IINA 播放器的播放按钮 AX 坐标偏移）通常是自动化工具翻车的地方，Cua 做了针对性处理。

截图方案。用 ScreenCaptureKit（而不是已废弃的 CGWindowListCreateImage），输出分辨率上限 1568px——恰好匹配 Anthropic 的多模态输入限制。

CuaBot：给编码 Agent 加上眼睛和手

CuaBot 运行效果：编码 Agent 在 Docker 沙箱中操作完整桌面环境

CuaBot 的实现路径有点意思。它没有自己造桌面渲染，而是：

1. 拉起一个预装桌面环境的 Docker 容器（Xpra，X11 over HTML5）
2. 用 Playwright（无头 Chromium）连到 Xpra 的 HTML5 界面
3. 在这上面暴露 bash、screenshot、click、type 等 HTTP API
4. 通过 node-pty + docker exec 提供 WebSocket 交互式 shell

光标遮挡也做了——计算 AABB 遮罩区域，Xpra 窗口上隐藏 Agent 光标，非 Xpra 窗口上正常显示。这种“套娃”方案虽然多了一层 Chromium 中间层，但复用了成熟的渲染引擎，工程复杂度反而比直接操作 VNC/帧缓冲要低。

评测到 RL 训练的闭环

Cua-Bench 用装饰器定义评测任务：

@cb.tasks_config(dataset="my-tasks")
@cb.setup_task(lambda: sb.shell.run("apt install -y firefox"))
@cb.evaluate_task(lambda actual, expected: actual == expected)
def my_task(env):
    # 定义评测任务

每个 step 都会记录截图、操作数据和窗口快照，可以导出为 RL 训练数据。目前开源社区里做 Computer-Use Agent 评测的项目不少，但从评测到训练数据导出形成闭环的，Cua-Bench 是少有的。

几个要注意的点

三语言并存有代价。系统级能力用 Swift，Agent/沙箱 SDK 用 Python，CLI/Bot 用 TypeScript——各自选了最趁手的工具，但维护成本不低。不过至少没为了“统一技术栈”而做出妥协。

Lume 仅限 Apple Silicon。Apple Virtualization.Framework 只在 M 系列芯片上可用，Intel Mac 只能走 QEMU，性能差距明显。

Agent 模型支持面广但质量参差。Claude 和 GPT computer-use-preview 是主要生产路径，UI-TARS、OmniParser、Ollama 等更多是实验性质。如果你要上生产，先把这两个跑通再说。

适合谁用

• 在做 Computer-Use Agent 产品，需要隔离执行环境的团队
• 想在 macOS 上实现后台自动化测试的开发者
• 需要评测/训练 Computer-Use 模型的研究团队
• 想给自己的编码 Agent 加桌面操作能力的个人开发者

如果你只是想让 LLM 帮你操作浏览器，browser-use 或 Playwright MCP 更轻量。Cua 的价值在于它想覆盖 Computer-Use Agent 落地的每一个环节——从底层虚拟化到上层评测，而且确实都开源了。

---

引用链接

[1] Cua: https://github.com/trycua/cua