cua-bench Windows Arena Adapter 完整指南在 Linux 上运行 Windows 桌面自动化基准测试【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cuaWindows Arena Adapter 是 cua-bench 中负责将 Windows 桌面自动化基准测试接入评测体系的适配器模块。它以 Docker 容器内嵌套 QEMU/KVM 虚拟机的方式运行 Windows 11提供173 个跨 12 个应用域的基准任务覆盖 Chrome、LibreOffice、VS Code、VLC、文件资源管理器等并通过 Copy-on-Write 快照策略实现任务间快速重置与并行评测。本文将基于 winarena_adapter/README.md 并结合仓库源码完整讲解从环境准备、镜像制备、CLI 使用、架构原理到评测与二次开发的全部环节帮助你快速在本机或云端跑通 Windows 桌面 Agent 评测。一、模块概览与适用场景Windows ArenaWAA是一个运行 AI Agent 完成 Windows 桌面任务的基准测试系统但由于原项目已不再维护cua-bench 将其中必要的代码直接嵌入仓库见 main.py 模块说明形成tasks/winarena_adapter适配器。适配器把任务数据、评测器evaluators、VM 管理逻辑infra统一收拢并通过 main.py 中的cb.tasks_config、cb.setup_task、cb.evaluate_task、cb.solve_task四个钩子接入 cua-bench 的cb run流程从而复用 cua-bench 的任务调度、会话管理与评测框架。典型使用场景包括在本地 Linux 工作站上对 GUI Agent如 Navi、Claude 等基于视觉语言模型的操作 Agent做 Windows 桌面任务评测在 Azure Batch 等云端集群上以多 worker 并行方式批量跑基准产出评测数据基于嵌入的 WAA 任务 JSON 与评测器二次开发新的 Windows 任务或调整评测逻辑。二、环境要求在开始之前请确认你的主机满足以下条件要求说明操作系统x86_64 Linux且启用 KVM嵌套虚拟化Docker已安装并处于运行状态磁盘空间至少~50GB基础镜像 Windows ISO其中 ISO 约 6GBdata.img 磁盘镜像 30GB不支持环境macOS / ARM 架构依赖 x86_64 KVMKVM 检测在源码中以/dev/kvm是否存在为依据见 cli.py 的 KVM 检查逻辑。无 KVM 时容器会以KVMN环境变量运行速度显著下降cb run的 setup 检查也会在缺少/dev/kvm时直接拒绝本地执行见 main.py 的 check_setup。三、快速开始3.1 首次制备基础镜像首次运行必须先创建 Windows 基础镜像耗时约 4560 分钟两种方式任选# 方式一自动下载 Windows 11 ISO约 6GB来自 Microsoft 官方链接 python -m tasks.winarena_adapter.cli vm setup --download-iso # 方式二使用自己准备的 ISO python -m tasks.winarena_adapter.cli vm setup --iso /path/to/windows.isovm setup的完整流程对应 cli.py 的 cmd_vm_setup检查 Docker 是否运行检查基础镜像是否已存在存在且未加--force则直接跳过确定 ISO--iso指定 → 默认目录~/.local/share/cua-bench/windows.iso→--download-iso自动下载本地无trycua/winarena:latest镜像时自动docker pull以winarena-setup容器名启动 Windows VM挂载 ISO、存储目录与 setup 目录等待 Windows 完成安装与软件初始化后优雅关机在images/windows-qemu/下生成windows.boot就绪标记文件。3.2 查看状态python -m tasks.winarena_adapter.cli vm status预期输出与 cmd_vm_status 一致Windows Arena Status Docker: ✓ Running Image: ✓ trycua/winarena:latest Windows ISO: ✓ Found Golden Image: ✓ Ready KVM: ✓ Available Container: ○ Not running3.3 运行基准任务# 列出全部可用任务--verbose 展示任务 ID 与描述 python -m tasks.winarena_adapter.cli task list --verbose # 通过 cua-bench 运行指定变体任务variant-index 对应任务序号 cb run task tasks/winarena_adapter --variant-id variant-indexcb run会先调用 check_setup() 检查金镜像与 KVM未就绪时给出引导命令如cb run tasks/winarena_adapter --setup --download-iso并可配合--setup直接触发 run_setup() 完成制备。四、CLI 命令全解析CLI 入口位于 cli.py组织为vm虚拟机管理与task基准任务两个命令组。下面按源码中的 argparse 定义逐条展开。4.1 vm 命令组vm setup制备 Windows 基础镜像python -m tasks.winarena_adapter.cli vm setup [options] Options: --iso PATH 指定 Windows 11 ISO 文件路径 --download-iso 自动从 Microsoft 下载 ISO约 6GB --detach, -d 后台运行容器以 -d 启动便于断开终端 --force 即使基础镜像已存在也强制重建 --skip-pull 本地无镜像时不自动 pull配合离线场景 --no-kvm 禁用 KVM 加速/dev/kvm 存在时默认使用 --winarena-apps 安装 Windows Arena 基准应用Chrome、LibreOffice、VLC 等 --ram SIZE VM 内存大小默认 8G --cpus NUM VM CPU 核数默认 8 --browser-port PORT noVNC 端口默认 8006 --rdp-port PORT RDP 端口默认 3390实现要点源码会向install_config.json写入INSTALL_WINARENA_APPS标志见 cli.py#L274-L288setup.ps1据此决定是否安装基准应用容器始终挂载/shared目录映射本地infra/vm/setup/因此对安装脚本的修改无需重建镜像即可生效。vm start启动 VM不含基准客户端python -m tasks.winarena_adapter.cli vm start [options] Options: --ram SIZE VM 内存大小默认 8G --cpus NUM VM CPU 核数默认 8 --browser-port PORT noVNC 端口默认 8006 --rdp-port PORT RDP 端口默认 3390 --container-name 容器名默认 winarena --skip-pull 不自动 pull 镜像 --no-kvm 禁用 KVM该命令适用于开发调试仅启动start_vm.sh拉起 QEMU 虚拟机不启动基准客户端见 cmd_vm_start可配合 noVNC/RDP 人工操作验证环境。vm stop停止 VMpython -m tasks.winarena_adapter.cli vm stop [options] Options: --container-name 容器名默认 winarena停止时先尝试优雅docker stop超时 150 秒超时则强制docker kill见 cmd_vm_stop。vm status检查状态无参数输出前面 3.2 节展示的状态面板。4.2 task 命令组task list列出基准任务python -m tasks.winarena_adapter.cli task list [--verbose]--verbose逐条显示任务 ID前 36 字符与描述。任务按域分组统计数据来源于 task_loader.py 的load_waa_tasks()。task run启动容器并运行基准客户端python -m tasks.winarena_adapter.cli task run [options] Options: --interactive, -i 以交互式 shell 进入容器entrypoint 变为 /bin/bash --no-client 不启动基准客户端只起 VM 供调试 --ram SIZE VM 内存大小默认 8G --cpus NUM VM CPU 核数默认 8 --browser-port PORT noVNC 端口默认 8006 --rdp-port PORT RDP 端口默认 3390 --container-name 容器名默认 winarena --skip-pull 不自动 pull 镜像 --no-kvm 禁用 KVM需要注意该命令会自动把宿主机的OPENAI_API_KEY或AZURE_API_KEYAZURE_ENDPOINT透传进容器环境变量见 cmd_task_run供容器内 Agent 调用模型使用。五、架构原理5.1 基础镜像与数据布局基础镜像是预先配置好的 Windows 11 VM 快照存储在 XDG 数据目录下可通过XDG_DATA_HOME覆盖默认~/.local/share/cua-bench/见 get_data_dir~/.local/share/cua-bench/ ├── images/ │ └── windows-qemu/ # Windows 基础镜像 │ ├── data.img # 30GB Windows 磁盘镜像 │ ├── windows.boot # 就绪标记文件golden image 完成的标志 │ ├── windows.vars # UEFI 变量 │ └── ... ├── workers/ # 每个 worker 的覆盖层目录Copy-on-Write │ ├── 0/ # worker 0 的变更写入区 │ ├── 1/ # worker 1 的变更写入区 │ └── ... └── windows.iso # 原始 ISO制备完成后可删除5.2 Copy-on-WriteCoW策略基准执行期间采用覆盖层快照机制这是支撑多 worker 并行与快速重置的关键基础镜像只读任务执行期间绝不修改基础镜像每个 worker 独立覆盖层所有变更写入workers/id/专属存储目录创建见 get_worker_path任务间快速重置丢弃覆盖层即可恢复干净状态无需复制 30GB 镜像并行执行多个 worker 可同时基于同一基础镜像运行不同任务。5.3 容器架构┌─────────────────────────────────────────────────────────────────┐ │ Docker Container (trycua/winarena:latest) │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Benchmark Client (Python) │ │ │ │ - Task setup and execution │ │ │ │ - AI Agent (Navi/Claude) │ │ │ │ - Evaluation metrics │ │ │ └──────────────────────┬────────────────────────────────────┘ │ │ │ HTTP (172.30.0.2:5000) │ │ ┌──────────────────────▼────────────────────────────────────┐ │ │ │ Windows 11 VM (QEMU/KVM) │ │ │ │ - CUA Computer Server (Flask API) │ │ │ │ - PyAutoGUI automation │ │ │ │ - Pre-installed apps (Chrome, LibreOffice, VLC, etc.) │ │ │ └───────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘客户端与虚拟机通过容器内网 HTTP 通信VM 内运行 Flask 实现的 CUA Computer Server监听172.30.0.2:5000提供/status健康检查与/cmd命令执行两类端点/cmd支持screenshot、click、type、get_accessibility_tree、run_command等自动化原语详见 infra/README.md。网络布局为172.30.0.1作为 Linux 容器网关172.30.0.2为 Windows VM 的 DHCP 地址。六、任务域一览173 个任务分布在 12 个应用域数据与 task_loader.py 的 DOMAINS 一一对应域任务数说明LibreOffice Calc24电子表格操作、图表、公式VS Code23IDE 设置、扩展、快捷键VLC Media Player21媒体播放、设置File Explorer19文件管理、文件夹操作LibreOffice Writer19文档编辑、格式化Chrome17浏览器标签页、书签、扩展MS Edge13浏览器设置、快捷方式Settings5Windows 系统设置Clock4闹钟、计时器Windows Calculator3计算器操作Microsoft Paint3图像编辑Notepad2文本文件操作任务 JSON 数据内嵌于data/examples/domain/正常难度与data/examples_noctxt/domain/hard 难度无上下文轨迹并附有test_all.json全部 173 任务与test_small.json子集。task_loader支持按域过滤与难度切换见 load_waa_tasks 的 difficulty 参数。七、任务定义与评测机制7.1 任务 JSON 结构每个任务是一个 JSON 文件字段含义如下结构示例见 infra/README.md 的 Task Definition Structure{ id: unique-task-id, snapshot: application-name, instruction: 自然语言任务描述, source: 任务来源或参考, config: [ { type: launch|download|open|sleep|activate_window|execute|create_folder, parameters: {...} } ], trajectory: path/to/trajectory, related_apps: [app-name], evaluator: { func: evaluation-function-name, result: {...}, expected: {...}, postconfig: [...] } }以仓库内真实任务为例Chrome 启用 Do Not Track{ id: 030eeff7-b492-4218-b312-701ec99ee0cc-wos, snapshot: chrome, instruction: Can you enable the Do Not Track feature in Chrome to enhance my online privacy?, config: [ { type: launch, parameters: { command: [google-chrome, --remote-debugging-port1337, --force-renderer-accessibility] } }, { type: launch, parameters: { command: [socat, tcp-listen:9222,fork, tcp:localhost:1337] } } ], related_apps: [chrome], evaluator: { func: exact_match, result: { type: enable_do_not_track }, expected: { type: rule, rules: { expected: true } } } }7.2 config 操作类型config数组定义任务开始前的环境准备操作由 WAASetupController 在任务启动阶段顺序执行类型用途对应实现方法launch启动应用如带远程调试端口的 Chrome_launch_setupdownload从 URL 下载测试文件带缓存与 3 次重试_download_setupupload_file上传本地文件到 VM_upload_file_setupopen用默认应用打开文件_open_setupsleep等待 UI 加载_sleep_setupactivate_window激活指定窗口PowerShell AppActivate_activate_window_setupclose_window/close_all关闭窗口_close_window_setup/_close_all_setupexecute/command执行 shell 命令支持 until 条件等待_execute_setup/_command_setupcreate_folder/create_file创建目录/文件_create_folder_setup/_create_file_setuprecycle_file移入回收站_recycle_file_setupchange_wallpaper更换桌面壁纸_change_wallpaper_setupchrome_open_tabs/edge_open_tabs打开浏览器标签页_chrome_open_tabs_setup/_edge_open_tabs_setupupdate_browse_history写入 Chrome 浏览历史基于内置 SQLite 模板生成_update_browse_history_setup每个操作通过_type_setup方法名动态映射分发见 setup_controller.py 的 setup 方法未知类型仅记录警告不阻断流程。7.3 评测流程任务结束后由 WAAEvaluator 完成评分流程如下执行postconfig收尾操作如保存文件、聚焦窗口特殊infeasible标记任务直接返回 0.0解析 metric 函数支持单个或列表通过异步 getter从 VM 提取 result 状态经SessionInterfaceWrapper调用session.run_command、read_bytes、read_file、get_accessibility_tree等见 evaluator.py#L22-L100提取 expected 值rule类型为内联规则其余走 getter调用 metric 函数比较 result 与 expected返回 0.01.0 的分数多 metric 场景支持conj聚合and取平均值并提前短路为 0or取最大值。常用评测函数覆盖通用场景exact_match、fuzzy_match、literal_match、is_in_list、check_include_exclude、check_csv、check_json、diff_text_file与各应用域专用逻辑compare_table电子表格对比、compare_docx_files文档对比、check_json_settingsVS Code 设置、compare_images图像相似度等。这些 metric 实现在 evaluators/metrics/ 目录下按域拆分对应的数据提取 getter 分同步evaluators/getters/与异步evaluators/getters_async/两套实现。八、监控与调试8.1 浏览器访问noVNC在基础镜像制备或任务执行期间通过浏览器实时查看 Windows VM 桌面http://localhost:80068.2 容器日志# 跟踪日志 docker logs -f winarena # 检查容器状态 docker ps -f namewinarena8.3 RDP 访问以 RDP 客户端连接进行交互式调试Host: localhost Port: 3390 User: Docker Password: (none)8.4 关键端口速查端口用途5000CUA Computer Server容器内网8006noVNC 浏览器访问3390RDP开发模式九、故障排查9.1 金镜像创建失败按顺序排查检查 Dockerdocker info验证 KVM 可用ls -la /dev/kvm检查磁盘空间df -h ~/.local/share/cua-bench查看日志docker logs winarena-setup9.2 CUA Server 连接失败Windows VM 启动并拉起 CUA Computer Server 需要时间请等待日志中出现就绪标志VM is up and running, and the CUA Computer Server is ready to use!9.3 VLC / 工具安装失败工具下载使用 tools_config.json 中配置的镜像列表每个工具含主镜像与多个备用镜像下载失败时安装脚本会自动尝试备用镜像。该文件覆盖 Git、7-Zip、ffmpeg、Chrome、LibreOffice、VLC、GIMP、VS Code、Thunderbird、Caddy 等工具需要更换下载源时直接编辑此文件并重新执行vm setup即可。9.4 其他已知问题来自实现文档大文件如 30GB VM 镜像经 blobfuse 挂载读取会出现 I/O 错误云端场景改用azcopy下载见 infra/README.md 的 Issue 1Azure Batch 节点临时盘较小拉取约 40GB 容器镜像前需在启动任务中将 Docker># 在远程 x86_64 VM 上执行 cd infra/scripts ./build-container-image.sh # 推送到镜像仓库 docker push trycua/winarena:latest由于镜像依赖 x86_64 KVMmacOS/ARM 上无法构建必须在远程 x86_64 VM 上完成构建相关教训见 infra/README.md 的 Issue 5。10.4 进一步阅读infra/README.md完整实现指南架构演进、Azure Batch 细节、Golden Image 策略、.env.local配置、experiments.json实验定义infra/docs/开发技巧与 Agent 开发文档Develop-Agent.md、Develop-Tasks.md、Development-Tips.md、WAA_IMPLEMENTATION.md适配器实现源码cli.py、main.py、task_loader.py、setup_controller.py、evaluator.py、controller_adapter.py。结语通过 Windows Arena Adaptercua-bench 将一套完整的 Windows 桌面自动化基准173 任务 / 12 域以可复现、可并行的方式带到了 Linux 开发环境中。无论是本地单机评测还是借助 Azure Batch 的大规模并行跑分其只读基础镜像 CoW 覆盖层的设计都保证了任务间状态隔离与快速重置。希望本文能帮助你顺利跑通首轮 Windows 桌面 Agent 评测并在此基础上扩展属于你自己的任务与评测逻辑。【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考