cua-bench 环境搭建完全指南以 toggle-switch 任务为例掌握 RL 训练环境的四个核心装饰器【免费下载链接】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本篇指南以 cua-bench 数据集中的 toggle-switch 任务开关切换为实战载体完整讲解 cua-bench 计算机使用computer-use强化学习环境的搭建规范包括cb.tasks_config、cb.setup_task、cb.solve_task、cb.evaluate_task四个装饰器的作用与写法、GUI 前端开发模式、可用 Action 类型、屏幕尺寸配置等。读完本文你将具备在 cua-bench 中独立编写、调试与运行一个可训练的桌面自动化任务的全部能力。背景cua-bench 与 toggle-switch 任务cua-bench 是一个面向计算机使用场景的强化学习环境框架任务以装饰器 前端 GUI的方式组织。每个任务文件夹包含四个组成部分见 cua-bench-basic/README.mdmain.py—— 任务配置、环境搭建、评估与解决方案gui/index.html—— 带 Tailwind 样式的 UI 界面pyproject.toml—— 项目元数据与依赖CLAUDE.md—— cua-bench 环境搭建文档toggle-switch 任务属于 cua-bench-basic 中控件与小组件Controls Widgets类目用于检验 Agent 点击开关控件、将指定设置切换到目标状态的基础 UI 自动化能力。其完整实现位于 toggle-switch/main.py 与 toggle-switch/gui/index.html。任务整体结构装饰器驱动分进程执行cua-bench 环境通过main.py顶部的模块级函数注册运行时由框架按每任务独立进程的方式加载。文件后半部分的代码从pid None起会在每个任务对应的独立进程中运行这意味着全局状态如窗口 pid、分数缓存可以安全地通过模块级变量保存无需担心任务间相互污染。框架在 decorators.py 中维护了一个全局环境注册表_env_registry按env_path记录每个环境的tasks_config、setup_task、solve_task、evaluate_task四个函数。每个装饰器都支持两种用法裸用cb.tasks_config或带 split 参数cb.tasks_config(train)/cb.tasks_config(splittrain)默认 split 为train。装饰后的函数会被打上_td_type与_td_split标记供Environment.make_from_module见 environment.py按 split 筛选并装配成可执行环境。cb.tasks_config定义任务清单与元数据cb.tasks_config装饰的函数每批次调用一次返回list[cb.Task]。每个cb.Task包含两部分关键信息descriptionAI Agent 实际听到的任务描述如 Turn on Notifications.应当自然、明确、可执行metadata任务参数难度、尺寸、操作系统等供求解与评估阶段读取computer计算机环境配置provider 与 setup_config。toggle-switch 任务通过笛卡尔积方式批量生成 5 个开关场景 × 操作系统列表cb.tasks_config(splittrain) def load(): os_types [linux] # [macos, win11, win10] toggle_scenarios [ {setting: notifications, label: Notifications, target_state: True, description: Turn on Notifications}, {setting: dark_mode, label: Dark Mode, target_state: True, description: Enable Dark Mode}, {setting: auto_save, label: Auto Save, target_state: False, description: Turn off Auto Save}, {setting: wifi, label: WiFi, target_state: True, description: Enable WiFi}, {setting: bluetooth, label: Bluetooth, target_state: False, description: Turn off Bluetooth}, ] return [ cb.Task( descriptionscenario[description] ., metadata{ setting: scenario[setting], label: scenario[label], target_state: scenario[target_state], }, computer{ provider: native, setup_config: { os_type: os_type, width: 1024, height: 768, background: #c0c0c0, }, }, ) for os_type in os_types for scenario in toggle_scenarios ]关键设计点metadata 是任务变体variant的载体通过setting、target_state等字段参数化变体实现一份任务代码多个难度/场景的数据生成能力computer配置自动驱动沙箱创建在 environment.py 的reset()中框架检测到Task.computer非空时会自动用其中的provider与setup_config调用create_sandbox()无需在 setup 阶段重复指定provider 可选值从 computers 目录的实现看包括nativeDocker/QEMU 真实桌面、webtop等后端。cb.setup_task最小化环境搭建cb.setup_task装饰的函数在任务开始时调用一次职责是创建沙箱并启动 webview 窗口。保持最小化——只做环境搭建不放任务逻辑。global pid env.create_sandbox(providercomputer, setup_config{os_type: linux, width: 800, height: 600}) pid env.launch_window(htmlhtml_content, titleGame, width400, height400) # 创建 webview 窗口toggle-switch 的实际 setup 实现异步版本如下cb.setup_task(splittrain) async def start(task_cfg: cb.Task, session: cb.DesktopSession): global pid pid await session.launch_window( html(Path(__file__).parent / gui/index.html).read_text(utf-8), titleToggle Switch Task, width450, height500, )launch_window是DesktopSession基类定义的接口见 computers/base.py完整签名支持url、html、folder三种内容来源以及title、x、y、width、height、icon、use_inner_size、title_bar_style等窗口参数返回窗口进程 IDpid。html可以直接读取本地gui/index.html文件传入这是任务类最常见的用法。gui/ 前端开发模式Tailwind Iconify 语义化 HTML所有游戏/任务逻辑都放在gui/index.html中。HTML 会被渲染进Tailwind Iconify 模板包裹的桌面 webview 窗口内不要使用html或body标签——根元素直接就是内容主体。关键模式语义化 HTML ARIA 描述使用规范的语义元素main、section、button、nav等并添加aria-label、aria-describedby、role属性。这既提升可访问性也让基于可访问性树的元素定位更准确。toggle-switch 的每个开关按钮都带roleswitch、aria-checked与aria-labelbutton idtoggle-notifications classtoggle-switch relative inline-flex h-6 w-11 items-center rounded-full bg-gray-300 transition-colors focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 roleswitch aria-checkedfalse aria-labelToggle notifications >响应式设计 紧凑留白使用最小 padding/marginp-1、p-2、gap-1、gap-2布局要能适配从弹出小窗300x200到全屏桌面避免固定高度/宽度用min-h-0、overflow-auto保证视口缩小时关键元素仍然可见。全局状态用window.__score保存当前得分RL 奖励采用 0.0-1.0 区间。toggle-switch 用window.__toggleStates保存各开关状态评估阶段直接读取window.__toggleStates { notifications: false, dark_mode: false, auto_save: true, // 初始开启 wifi: false, bluetooth: true, // 初始开启 };AI 基线策略在 JavaScript 中实现 AI 策略通过window.__next_move()暴露给求解端。窗口填充根元素用classflex h-full w-full填满整个窗口所有元素保持紧凑响应式HTML 通常渲染在尺寸较小的桌面 webview 窗口或移动屏幕上。图标使用iconify-icon iconprefix:name/iconify-icon。toggle-switch 界面中每个设置项都配有语义图标如mdi:bell通知、mdi:weather-night深色模式、mdi:wifi、mdi:bluetooth、mdi:content-save-auto自动保存。cb.solve_task从 GUI AI 获取动作并执行cb.solve_task装饰的函数在 setup 之后调用当run_solutionTrue时负责从 GUI 的 AI 中获取下一个动作并通过env.step或env.bot执行直到任务完成。原版文档给出的通用求解循环global pid action env.execute_javascript(pid, window.__next_move()) while action is not None and action[type] ! done: if not action or action[type] wait: env.step(WaitAction(seconds1.0)) elif action[type] click_element: env.bot.click_element(pid, f#{action[element_id]}) # 点击元素的最安全方式 elif action[type] click_absolute: env.step(ClickAction(xaction[x], yaction[y])) # x,y 必须是屏幕坐标需加上 window.screenX / window.screenY 偏移 elif action[type] type: env.step(TypeAction(textaction[text])) action env.execute_javascript(pid, window.__next_move()) env.step(DoneAction())toggle-switch 的实际求解实现则是纯execute_javascriptclick_element的组合用 metadata 精确驱动cb.solve_task(splittrain) async def solve(task_cfg: cb.Task, session: cb.DesktopSession): global pid setting task_cfg.metadata[setting] target_state task_cfg.metadata[target_state] current_state await session.execute_javascript(pid, fwindow.__toggleStates[{setting}]) if current_state ! target_state: await session.click_element(pid, f#toggle-{setting})规则约束只能通过env.step或env.bot执行解决任务的动作env.execute_javascript只能用于执行返回最优动作相关信息的辅助函数例如目标元素或实现了最优策略并暴露window.__next_move()的 AI 输出GUI 中的window.__next_move()只应在任务未解决时返回下一个动作window.__next_move()通常被cb.solve_task装饰的函数循环调用直到任务解决window.__next_move()不应执行任何动作或修改环境/状态——它只返回下一步动作真正执行交给env.step/env.bot。底层原理bot 如何把选择器变成点击Bot.click_element见 bot.py并非直接触发 DOM 事件而是通过两步完成真实桌面级点击rect self.env.get_element_rect(pid, selector, spacescreen) if not rect: raise RuntimeError(fElement not found for selector: {selector}) cx int(rect[x] rect[width] / 2) cy int(rect[y] rect[height] / 2) self.env.step(ClickAction(xcx, ycy))先用 CSS 选择器在屏幕坐标系spacescreen中取元素矩形计算中心点再派发ClickAction。这也是文档强调click_element是最安全的点击方式的原因——坐标计算、偏移处理全部由框架完成。cb.evaluate_task从 GUI 状态计算奖励cb.evaluate_task装饰的函数在任务结束时调用从 GUI 状态返回奖励列表推荐 0.0-1.0 区间global pid score env.execute_javascript(pid, window.__score) return [float(score)] # 0.0-1.0 range preferredtoggle-switch 的评估实现展示了变体级评分模式——根据metadata中指定的开关与目标状态检查对应开关是否处于目标状态正确得 1.0否则 0.0cb.evaluate_task(splittrain) async def evaluate(task_cfg: cb.Task, session: cb.DesktopSession) - list[float]: global pid toggle_states await session.execute_javascript(pid, window.__toggleStates) if toggle_states is None: return [0.0] setting task_cfg.metadata[setting] target_state task_cfg.metadata[target_state] actual_state toggle_states.get(setting) return [1.0] if actual_state target_state else [0.0]这里展示了一个重要实践评估逻辑只读 GUI 的全局状态对象不依赖 UI 视觉表现。GUI 的点击处理器会在切换开关时同步更新window.__toggleStates与按钮的aria-checked/ 颜色类保证了视觉状态 逻辑状态 评估状态三者一致见 gui/index.html 中的 click 事件处理。Action 类型env.step 的全部可用动作所有 Action 类都定义在 types.py 中env.step()支持以下动作鼠标类Action参数说明ClickAction(x, y)屏幕坐标单击RightClickAction(x, y)屏幕坐标右键单击DoubleClickAction(x, y)屏幕坐标双击DragAction(from_x, from_y, to_x, to_y, duration1.0)起止坐标 时长拖拽ScrollAction(directionup\|down, amount100)方向 幅度滚动键盘类Action参数说明TypeAction(texthello)文本键入文本KeyAction(keyEnter)按键名单键HotkeyAction(keys[ctrl, c])键列表组合键控制类Action参数说明DoneAction()—声明任务完成WaitAction(seconds1.0)秒数等待实际上 types.py 还提供了MiddleClickAction中键与MoveToAction移动鼠标两个额外动作Action联合类型由全部 12 个 dataclass 组成。动作的序列化与解析在训练数据生成与轨迹回放场景中动作需要在字符串与对象间转换。actions.py 提供了三种转换途径repr_to_action(ClickAction(x100, y200))—— 解析 repr 格式字符串snake_case_to_action(click(0.5, 0.5))—— 解析下划线风格字符串支持浮点相对坐标dict_to_action({type: click, x: 100, y: 200})—— 从字典构造type字段大小写与后缀容错如click/ClickAction均可。action_to_dict(action)则反向把 Action 对象转成带type键的字典。IconsIconify 矢量图标使用iconify-icon元素即可获得可缩放矢量图标图标会被自动处理并替换为内联 SVGiconify-icon iconeva:people-outline/iconify-icon iconify-icon iconmingcute:ad-circle-line width24 height24/iconify-icon iconify-icon iconmdi:play classtext-blue-500 stylefont-size: 2rem;/iconify-icon支持全部 iconify 图标集eva、mingcute、mdi 等。尺寸控制可以通过width/height属性、Tailwind 类或内联font-size完成让图标完美融入紧凑布局。屏幕尺寸StandardScreenSize 全量选项屏幕尺寸通过env.create_sandbox的setup_config参数指定。StandardScreenSize类型定义于 types.py覆盖了桌面、移动端与老旧分辨率StandardScreenSize Union[ # 标准桌面分辨率 tuple[Literal[1920], Literal[1080]], # Full HD当前默认 tuple[Literal[1366], Literal[768]], # HD笔记本标准 tuple[Literal[2560], Literal[1440]], # 2K/QHD tuple[Literal[3840], Literal[2160]], # 4K/UHD tuple[Literal[1280], Literal[720]], # HD Ready tuple[Literal[1600], Literal[900]], # HD tuple[Literal[1920], Literal[1200]], # WUXGA tuple[Literal[2560], Literal[1600]], # WQXGA tuple[Literal[3440], Literal[1440]], # Ultrawide QHD tuple[Literal[5120], Literal[1440]], # Super Ultrawide # 移动/平板分辨率 tuple[Literal[1024], Literal[768]], # iPad竖屏 tuple[Literal[768], Literal[1024]], # iPad横屏 tuple[Literal[360], Literal[640]], # 手机竖屏 tuple[Literal[640], Literal[360]], # 手机横屏 # 老旧分辨率 tuple[Literal[1024], Literal[600]], # Netbook tuple[Literal[800], Literal[600]], # SVGA tuple[Literal[640], Literal[480]], # VGA # 其他常见分辨率 tuple[Literal[1440], Literal[900]], # 自定义笔记本 tuple[Literal[1680], Literal[1050]], # WSXGA tuple[Literal[1920], Literal[1440]], # 自定义 4:3 tuple[Literal[2560], Literal[1080]], # Ultrawide Full HD tuple[Literal[3440], Literal[1440]], # Ultrawide QHD tuple[Literal[3840], Literal[1080]], # Super Ultrawide Full HD ]选择建议根据任务与环境选择合适的屏幕尺寸。toggle-switch 这类小窗口任务使用 1024x768 桌面环境 450x500 的 webview 窗口而全屏桌面任务则适合 1920x1080。最佳实践清单综合原版文档与 toggle-switch 的真实实现以下是编写 cua-bench 任务的核心准则保持main.py最小化——只放装饰器与基础逻辑环境搭建、任务加载等AI 策略放在gui/的 JavaScript 中通过window.__next_move()暴露用window.__score提供 RL 奖励保持 0.0-1.0 区间通过 Task metadata 参数化变体难度、尺寸、OS、轮数等一份代码生成多样任务谨慎使用WaitAction仅当任务确实需要如等待页面加载或等待下一个动作可用时才使用。env.bot的辅助函数自带可行动性actionability逻辑会自动等待元素变为可点击无需手动等待坐标语义所有x, y都是屏幕坐标0,0 位于屏幕左上角。使用window.screenX和window.screenY获取浏览器视口左上角到屏幕左上角的偏移复用框架能力Task.computer配置会自动驱动沙箱创建environment.py 的reset()session.click_element通过get_element_rectClickAction完成屏幕级点击computers/base.py这些都可以省去大量样板代码。运行任务任务可以交互式运行以调试# 交互式运行指定任务 python -m cua_bench.interact task-folder/main.py # 示例 python -m cua_bench.interact click-button/main.pymain.py底部通常还会加上if __name__ __main__: cb.interact(__file__)允许直接以脚本方式运行并进入交互模式toggle-switch 即如此。在批量训练/评测场景中框架还提供了run_benchmark、run_single_task、run_interactive等 runner见init.py。小结通过 toggle-switch 这一最小示例可以看到cua-bench 的环境搭建遵循清晰的四段式生命周期tasks_config定义任务与变体 →setup_task搭建沙箱窗口 →solve_task驱动求解循环 →evaluate_task依据 GUI 状态给出 0-1 奖励。前端 GUI 负责状态管理、AI 基线与语义化可访问的界面框架层则负责把 CSS 选择器与 JS 调用翻译成真实屏幕动作。掌握了这套骨架你就能批量产出覆盖各种基础 UI 交互点击、表单、下拉、拖拽、滑块、播放器等的可训练任务为计算机使用模型的训练、评估与数据生成提供稳定的数据源。【免费下载链接】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），仅供参考