基于 cua-bench 搭建 Computer-Use RL 环境从脚手架指南到 spreadsheet-cell 任务实战【免费下载链接】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本篇技术指南以libs/cua-bench/datasets/cua-bench-basic/spreadsheet-cell/CLAUDE.mdcua-bench 环境脚手架指南为骨架结合该任务目录下的真实源码展开系统讲解如何利用 cua-bench 的四个核心装饰器tasks_config/setup_task/solve_task/evaluate_task构建可供训练、评估与数据生成使用的 Computer-Use 强化学习环境。读完本文你将掌握 cua-bench 任务环境的完整编写范式如何定义任务参数、启动沙箱与 WebView、编写带 AI 基线的 GUI、通过env.step/env.bot执行动作闭环以及如何用window.__score与window.__cellData类全局状态完成 RL 奖励反馈。cua-bench 环境结构总览cua-bench位于 libs/cua-bench是一个面向 Computer-Use 的 RL 环境与评测框架每个任务环境的标准结构如下main.pyPython 装饰器定义任务逻辑加载任务、环境搭建、求解、评估gui/HTML/CSS/JS 实现的界面自动引入 Tailwind 与 Iconify 图标pyproject.toml项目元数据与依赖声明CLAUDE.md本任务目录内的 cua-bench 脚手架文档即本指南的源文档。以spreadsheet-cell任务向电子表格单元格输入数据为例其目录结构为libs/cua-bench/datasets/cua-bench-basic/spreadsheet-cell/ ├── gui/ │ └── index.html # 电子表格界面Tailwind 语义 HTML 全局状态 ├── CLAUDE.md # 环境脚手架指南 ├── main.py # 四个装饰器定义的任务生命周期 └── pyproject.toml # 项目元数据与依赖该任务所属的cua-bench-basic数据集libs/cua-bench/datasets/cua-bench-basic/README.md覆盖了按钮点击、表单填写、下拉选择、拖拽、滑块、日期选择等 13 类基础 UI 交互基准任务spreadsheet-cell对应其中Text Input类别用于评估智能体将文本精准输入到指定单元格的 grounding 能力。四个核心装饰器任务生命周期的骨架main.py通过四个装饰器定义任务的完整生命周期。它们的底层实现位于 libs/cua-bench/cua_bench/decorators.py每个装饰器都会将包装后的函数注册进按环境路径索引的_env_registry键为tasks_config/setup_task/solve_task/evaluate_task并通过_td_type与_td_split属性标注函数类型与数据划分。装饰器支持两种用法裸用cb.tasks_config或参数化cb.tasks_config(train)/cb.tasks_config(splittrain)默认 split 为train。cb.tasks_config声明任务与参数化变体tasks_config装饰的函数返回list[cb.Task]。其中description是 AI 智能体听到的任务指令如 Play 2048、Book a hotelmetadata存放任务参数难度、游戏尺寸、操作系统等供 setup / solve / evaluate 三个阶段读取。spreadsheet-cell的 main.py 演示了用场景列表参数化生成多个任务变体的写法cb.tasks_config(splittrain) def load(): os_types [linux] # [macos, win11, win10] # Different spreadsheet cell entry scenarios cell_scenarios [ {cell: A1, value: Product, description: Enter Product into cell A1}, {cell: B2, value: 150, description: Enter 150 into cell B2}, {cell: C3, value: SUM(A1:A10), description: Enter SUM(A1:A10) into cell C3}, { cell: D4, value: Total Revenue, description: Enter Total Revenue into cell D4, }, {cell: A5, value: 42.50, description: Enter 42.50 into cell A5}, ] return [ cb.Task( descriptionscenario[description] ., metadata{ cell: scenario[cell], value: scenario[value], }, computer{ provider: native, setup_config: { os_type: os_type, width: 1024, height: 768, background: #c0c0c0, }, }, ) for os_type in os_types for scenario in cell_scenarios ]值得注意的实战要点通过for os_type in os_types for scenario in cell_scenarios的双重循环一条任务定义即可批量生成 1×55 个变体扩展os_types即可横向覆盖多操作系统。metadata中的cell与value是后续求解与评估阶段的答案参照体现了参数化变体的最佳实践。computer字段配置运行环境provider: native指定原生桌面驱动setup_config中的os_type、width、height、background此处为灰色桌面背景#c0c0c0共同决定沙箱外观。任务元数据在pyproject.toml的[tool.cua-bench]中声明description basic spreadsheet cell entry task、difficulty easy、category grounding与代码注释中的类别划分一致。cb.setup_task搭建沙箱与启动 WebViewsetup_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) # create webview windowspreadsheet-cell的真实实现main.py使用异步DesktopSessionAPI直接读取同目录gui/index.html的内容渲染窗口pid None 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), titleSpreadsheet Task, width700, height500, )关键点launch_window的width/height700×500是 webview 窗口尺寸与沙箱屏幕尺寸1024×768相互独立二者共同决定了智能体看到的界面。代码注释明确标注了All code below will be running in a separate process per task即每个任务实例在独立进程中运行pid作为模块级全局变量在阶段间传递窗口句柄。cb.solve_task执行动作闭环solve_task从 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]}) # safest way to click an element elif action[type] click_absolute: env.step(ClickAction(xaction[x], yaction[y])) # x,y must be in screen coordinates (requires offsetting by window.screenX and window.screenY) elif action[type] type: env.step(TypeAction(textaction[text])) action env.execute_javascript(pid, window.__next_move()) env.step(DoneAction())spreadsheet-cell的求解实现main.py展示了无 AI 基线的硬编码参考解写法三步完成点击单元格 → 输入值 → 回车确认cb.solve_task(splittrain) async def solve(task_cfg: cb.Task, session: cb.DesktopSession): global pid target_cell task_cfg.metadata[cell] await session.click_element(pid, f#cell-{target_cell}) await session.execute_action(cb.TypeAction(texttask_cfg.metadata[value])) await session.execute_action(cb.KeyAction(keyReturn))这里#cell-{target_cell}直接对应gui/index.html中每个输入框的idcell-A1这类元素标识。三种解法路径对比env.bot.click_element(pid, selector)最安全的元素点击方式内部带 actionability 逻辑自动等待元素可点击适合带语义 id 的页面元素env.step(ClickAction(x, y))绝对屏幕坐标点击坐标原点在屏幕左上角浏览器视口内需用window.screenX/window.screenY换算偏移session.execute_action(...)spreadsheet-cell 采用的会话级动作执行入口配合TypeAction与KeyAction完成文本输入与回车确认。cb.evaluate_task从 GUI 状态提取奖励evaluate_task返回奖励列表RL 场景优先使用 0.0–1.0 区间。指南原型global pid score env.execute_javascript(pid, window.__score) return [float(score)] # 0.0-1.0 range preferredspreadsheet-cell的评估实现main.py不依赖window.__score标量而是从全局状态window.__cellData精确比对目标单元格cb.evaluate_task(splittrain) async def evaluate(task_cfg: cb.Task, session: cb.DesktopSession) - list[float]: global pid cell_data await session.execute_javascript(pid, window.__cellData) if cell_data is None: return [0.0] target_cell task_cfg.metadata[cell] expected_value task_cfg.metadata[value] actual_value cell_data.get(target_cell) return [1.0] if actual_value expected_value else [0.0]该实现的评估语义window.__cellData为空返回 0.0未产生任何输入metadata[cell]指定格的值与期望值精确相等才给 1.0否则 0.0。这种二进制奖励是 grounding 类任务单元格定位 文本输入的典型度量方式——比宽松的部分匹配更能暴露定位与输入的精确性问题。GUI 编写规范语义化、响应式与全局状态gui/目录承载全部任务逻辑。HTML 会在 Tailwind Iconify 模板中渲染到桌面 webview 窗口内不要使用html或body标签根元素直接使用语义标签。spreadsheet-cell的 gui/index.html 是这份规范的完整范例。语义 HTML 与 ARIA指南要求使用main、section、button、nav等语义元素并添加aria-label、aria-describedby、role属性既保证可访问性也帮助视觉模型/Agent 更好地识别元素。范例实现main classflex flex-col h-full w-full p-4 overflow-auto rolemain aria-labelSpreadsheet interface 每个单元格输入框都带有可定位的语义标识cellInput.type text; cellInput.id cell- cellId; cellInput.setAttribute(aria-label, Cell cellId); cellInput.setAttribute(data-cell, cellId);idcell-A1正是solve_task中session.click_element(pid, #cell-A1)的选择器来源aria-labelCell A1则服务于基于语义标签的 Agent 定位。响应式与紧凑布局指南强调使用紧凑 padding/marginp-1、p-2、gap-1、gap-2布局需从弹窗尺寸300×200到全桌面均可工作避免固定宽高使用min-h-0、overflow-auto保证视口缩小时关键元素仍可见根元素用classflex h-full w-full填满整个窗口。范例中根容器使用flex flex-col h-full w-full p-4 overflow-auto表格行由 JavaScript 按grid grid-cols-5生成天然适配不同宽度。全局状态RL 奖励的桥接通道指南约定window.__score保存当前得分RL 奖励使用 0.0–1.0 区间window.__next_move()在 JavaScript 中实现的 AI 策略暴露给solve_task循环调用只返回下一个动作、绝不执行动作或修改环境状态二者以及任意自定义全局状态由env.execute_javascript在 Python 与 GUI 之间桥接。spreadsheet-cell用window.__cellData字典替代标量分数作为评估状态blur、Enter、input 三个事件统一维护window.__cellData {}; // focus: 高亮父容器ring-2 ring-blue-500 // blur: 保存 this.value.trim() 到 __cellData[cellId]空值则 delete // Enter: 保存值并 this.blur() // input: 实时同步 __cellData图标与界面提示图标统一使用iconify-icon元素渲染时自动替换为内联 SVG支持全部 iconify 图标集eva、mingcute、mdi 等。spreadsheet-cell在操作提示条中使用了mdi:information图标并配以text-blue-600颜色类iconify-icon iconmdi:information classtext-blue-600/iconify-icon同时界面底部给出了面向智能体的明确操作引导文案Click a cell to select it, then type to enter data. Press Enter to confirm.——这类内嵌提示能显著提升 Agent 对任务完成条件的理解。动作类型参考env.step()支持的动作类定义于 libs/cua-bench/cua_bench/actions.py 并由 libs/cua-bench/cua_bench/types.py 导出分为三类鼠标动作ClickAction(x, y)— 左键单击RightClickAction(x, y)— 右键单击DoubleClickAction(x, y)— 双击DragAction(from_x, from_y, to_x, to_y, duration1.0)— 拖拽ScrollAction(directionup|down, amount100)— 滚动键盘动作TypeAction(texthello)— 输入文本KeyAction(keyEnter)— 按键HotkeyAction(keys[ctrl, c])— 组合键控制动作DoneAction()— 宣告任务完成WaitAction(seconds1.0)— 等待源码细节actions.py还提供了两套文本解析器——repr_to_action解析ClickAction(x100, y200)形式的 repr 字符串snake_case_to_action解析click(0.5, 0.5)、type(hello)形式的指令文本坐标支持整数与浮点数整数值自动转 int。这意味着除直接构造动作对象外Agent 也可输出动作描述字符串交由框架解析动作类型还额外支持MiddleClickAction、MoveToAction等。屏幕尺寸setup_config 的关键参数屏幕尺寸在env.create_sandbox的setup_config参数中指定。spreadsheet-cell使用 1024×768而指南完整列出了 cua-bench 支持的全部标准分辨率当前默认 1920×1080分类分辨率说明桌面标准1920×1080Full HD当前默认桌面标准1366×768HD笔记本标准桌面标准2560×14402K/QHD桌面标准3840×21604K/UHD桌面标准1280×720HD Ready桌面标准1600×900HD桌面标准1920×1200WUXGA桌面标准2560×1600WQXGA桌面标准3440×1440Ultrawide QHD桌面标准5120×1440Super Ultrawide移动/平板1024×768iPad竖屏移动/平板768×1024iPad横屏移动/平板360×640手机竖屏移动/平板640×360手机横屏传统1024×600Netbook传统800×600SVGA传统640×480VGA其他常见1440×900 / 1680×1050 / 1920×1440 / 2560×1080 / 3440×1440 / 3840×1080定制笔记本、WSXGA、4:3 及超宽屏实战建议选择与任务真实场景匹配的屏幕尺寸——桌面办公类任务用 1920×1080 或 1366×768移动端任务用 360×640 系列窗口内布局需保证在目标尺寸下无溢出。注意setup_config中同时存在width/height沙箱屏幕与launch_window的width/heightwebview 窗口两套尺寸需分别设置。最佳实践与常见陷阱综合指南与源码编写 cua-bench 任务环境时应遵循保持main.py最小化只写装饰器与基础逻辑环境搭建、任务加载游戏/任务逻辑全部放入gui/的 JavaScript 中。AI 策略放 GUI 侧通过window.__next_move()暴露该函数只返回下一个动作不执行任何动作、不修改环境状态实际执行一律交给env.step/env.bot在solve_task中循环调用直至任务解决。奖励走全局状态用window.__score0.0–1.0 区间或自定义状态如window.__cellData承载 RL 奖励所需数据。参数化变体用 Task metadata 参数化难度、尺寸、OS、轮数等一次声明批量生成变体。慎用WaitAction除非任务确实需要如等待页面加载、等待下一个动作可用否则优先依赖env.bot内置的 actionability 逻辑自动等待元素可点击减少无谓等待。坐标换算所有x,y均为屏幕坐标原点在屏幕左上角浏览器视口坐标需用window.screenX/window.screenY换算偏移。按需选择屏幕尺寸选择与任务和环境匹配的分辨率桌面任务避免过小窗口移动任务避免桌面分辨率。GUI 可访问性语义标签 aria-label 明确的提示文案如界面中的操作说明条既能提升真实可用性也显著改善视觉模型与 Agent 的元素识别成功率。运行与验证单个任务可交互式运行libs/cua-bench/datasets/cua-bench-basic/README.md# 运行 cua-bench 基础任务交互式 python -m cua_bench.interact spreadsheet-cell/main.pymain.py末尾的if __name__ __main__: cb.interact(__file__)提供了同一入口。cua-bench 框架的完整入口、批处理与训练管线可继续查看 libs/cua-bench/cua_bench 下的cli/、runner/、trainer/等子模块以及基准任务数据集 libs/cua-bench/datasets/cua-bench-basic含 click-button、fill-form、drag-drop 等 13 类任务与其他任务库 libs/cua-bench/datasets/cua-bench-kicad、libs/cua-bench/datasets/cua-bench-workflows均遵循本文所述的同一脚手架规范。小结spreadsheet-cell是理解 cua-bench 任务环境脚手架的最小完整样本——tasks_config用双重循环参数化 5 个变体setup_task启动 700×500 的 WebViewsolve_task以点击#cell-{cell}→ 输入值 → 回车三步参考解执行evaluate_task通过window.__cellData精确比对给出 0/1 奖励。掌握这四个装饰器与 GUI 全局状态约定即可按同一模式为任意 Computer-Use 交互场景表单、表格、编辑器、多媒体控制等搭建可用于 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 cua-bench 搭建 Computer-Use RL 环境：从脚手架指南到 spreadsheet-cell 任务实战
基于 cua-bench 搭建 Computer-Use RL 环境从脚手架指南到 spreadsheet-cell 任务实战【免费下载链接】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本篇技术指南以libs/cua-bench/datasets/cua-bench-basic/spreadsheet-cell/CLAUDE.mdcua-bench 环境脚手架指南为骨架结合该任务目录下的真实源码展开系统讲解如何利用 cua-bench 的四个核心装饰器tasks_config/setup_task/solve_task/evaluate_task构建可供训练、评估与数据生成使用的 Computer-Use 强化学习环境。读完本文你将掌握 cua-bench 任务环境的完整编写范式如何定义任务参数、启动沙箱与 WebView、编写带 AI 基线的 GUI、通过env.step/env.bot执行动作闭环以及如何用window.__score与window.__cellData类全局状态完成 RL 奖励反馈。cua-bench 环境结构总览cua-bench位于 libs/cua-bench是一个面向 Computer-Use 的 RL 环境与评测框架每个任务环境的标准结构如下main.pyPython 装饰器定义任务逻辑加载任务、环境搭建、求解、评估gui/HTML/CSS/JS 实现的界面自动引入 Tailwind 与 Iconify 图标pyproject.toml项目元数据与依赖声明CLAUDE.md本任务目录内的 cua-bench 脚手架文档即本指南的源文档。以spreadsheet-cell任务向电子表格单元格输入数据为例其目录结构为libs/cua-bench/datasets/cua-bench-basic/spreadsheet-cell/ ├── gui/ │ └── index.html # 电子表格界面Tailwind 语义 HTML 全局状态 ├── CLAUDE.md # 环境脚手架指南 ├── main.py # 四个装饰器定义的任务生命周期 └── pyproject.toml # 项目元数据与依赖该任务所属的cua-bench-basic数据集libs/cua-bench/datasets/cua-bench-basic/README.md覆盖了按钮点击、表单填写、下拉选择、拖拽、滑块、日期选择等 13 类基础 UI 交互基准任务spreadsheet-cell对应其中Text Input类别用于评估智能体将文本精准输入到指定单元格的 grounding 能力。四个核心装饰器任务生命周期的骨架main.py通过四个装饰器定义任务的完整生命周期。它们的底层实现位于 libs/cua-bench/cua_bench/decorators.py每个装饰器都会将包装后的函数注册进按环境路径索引的_env_registry键为tasks_config/setup_task/solve_task/evaluate_task并通过_td_type与_td_split属性标注函数类型与数据划分。装饰器支持两种用法裸用cb.tasks_config或参数化cb.tasks_config(train)/cb.tasks_config(splittrain)默认 split 为train。cb.tasks_config声明任务与参数化变体tasks_config装饰的函数返回list[cb.Task]。其中description是 AI 智能体听到的任务指令如 Play 2048、Book a hotelmetadata存放任务参数难度、游戏尺寸、操作系统等供 setup / solve / evaluate 三个阶段读取。spreadsheet-cell的 main.py 演示了用场景列表参数化生成多个任务变体的写法cb.tasks_config(splittrain) def load(): os_types [linux] # [macos, win11, win10] # Different spreadsheet cell entry scenarios cell_scenarios [ {cell: A1, value: Product, description: Enter Product into cell A1}, {cell: B2, value: 150, description: Enter 150 into cell B2}, {cell: C3, value: SUM(A1:A10), description: Enter SUM(A1:A10) into cell C3}, { cell: D4, value: Total Revenue, description: Enter Total Revenue into cell D4, }, {cell: A5, value: 42.50, description: Enter 42.50 into cell A5}, ] return [ cb.Task( descriptionscenario[description] ., metadata{ cell: scenario[cell], value: scenario[value], }, computer{ provider: native, setup_config: { os_type: os_type, width: 1024, height: 768, background: #c0c0c0, }, }, ) for os_type in os_types for scenario in cell_scenarios ]值得注意的实战要点通过for os_type in os_types for scenario in cell_scenarios的双重循环一条任务定义即可批量生成 1×55 个变体扩展os_types即可横向覆盖多操作系统。metadata中的cell与value是后续求解与评估阶段的答案参照体现了参数化变体的最佳实践。computer字段配置运行环境provider: native指定原生桌面驱动setup_config中的os_type、width、height、background此处为灰色桌面背景#c0c0c0共同决定沙箱外观。任务元数据在pyproject.toml的[tool.cua-bench]中声明description basic spreadsheet cell entry task、difficulty easy、category grounding与代码注释中的类别划分一致。cb.setup_task搭建沙箱与启动 WebViewsetup_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) # create webview windowspreadsheet-cell的真实实现main.py使用异步DesktopSessionAPI直接读取同目录gui/index.html的内容渲染窗口pid None 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), titleSpreadsheet Task, width700, height500, )关键点launch_window的width/height700×500是 webview 窗口尺寸与沙箱屏幕尺寸1024×768相互独立二者共同决定了智能体看到的界面。代码注释明确标注了All code below will be running in a separate process per task即每个任务实例在独立进程中运行pid作为模块级全局变量在阶段间传递窗口句柄。cb.solve_task执行动作闭环solve_task从 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]}) # safest way to click an element elif action[type] click_absolute: env.step(ClickAction(xaction[x], yaction[y])) # x,y must be in screen coordinates (requires offsetting by window.screenX and window.screenY) elif action[type] type: env.step(TypeAction(textaction[text])) action env.execute_javascript(pid, window.__next_move()) env.step(DoneAction())spreadsheet-cell的求解实现main.py展示了无 AI 基线的硬编码参考解写法三步完成点击单元格 → 输入值 → 回车确认cb.solve_task(splittrain) async def solve(task_cfg: cb.Task, session: cb.DesktopSession): global pid target_cell task_cfg.metadata[cell] await session.click_element(pid, f#cell-{target_cell}) await session.execute_action(cb.TypeAction(texttask_cfg.metadata[value])) await session.execute_action(cb.KeyAction(keyReturn))这里#cell-{target_cell}直接对应gui/index.html中每个输入框的idcell-A1这类元素标识。三种解法路径对比env.bot.click_element(pid, selector)最安全的元素点击方式内部带 actionability 逻辑自动等待元素可点击适合带语义 id 的页面元素env.step(ClickAction(x, y))绝对屏幕坐标点击坐标原点在屏幕左上角浏览器视口内需用window.screenX/window.screenY换算偏移session.execute_action(...)spreadsheet-cell 采用的会话级动作执行入口配合TypeAction与KeyAction完成文本输入与回车确认。cb.evaluate_task从 GUI 状态提取奖励evaluate_task返回奖励列表RL 场景优先使用 0.0–1.0 区间。指南原型global pid score env.execute_javascript(pid, window.__score) return [float(score)] # 0.0-1.0 range preferredspreadsheet-cell的评估实现main.py不依赖window.__score标量而是从全局状态window.__cellData精确比对目标单元格cb.evaluate_task(splittrain) async def evaluate(task_cfg: cb.Task, session: cb.DesktopSession) - list[float]: global pid cell_data await session.execute_javascript(pid, window.__cellData) if cell_data is None: return [0.0] target_cell task_cfg.metadata[cell] expected_value task_cfg.metadata[value] actual_value cell_data.get(target_cell) return [1.0] if actual_value expected_value else [0.0]该实现的评估语义window.__cellData为空返回 0.0未产生任何输入metadata[cell]指定格的值与期望值精确相等才给 1.0否则 0.0。这种二进制奖励是 grounding 类任务单元格定位 文本输入的典型度量方式——比宽松的部分匹配更能暴露定位与输入的精确性问题。GUI 编写规范语义化、响应式与全局状态gui/目录承载全部任务逻辑。HTML 会在 Tailwind Iconify 模板中渲染到桌面 webview 窗口内不要使用html或body标签根元素直接使用语义标签。spreadsheet-cell的 gui/index.html 是这份规范的完整范例。语义 HTML 与 ARIA指南要求使用main、section、button、nav等语义元素并添加aria-label、aria-describedby、role属性既保证可访问性也帮助视觉模型/Agent 更好地识别元素。范例实现main classflex flex-col h-full w-full p-4 overflow-auto rolemain aria-labelSpreadsheet interface 每个单元格输入框都带有可定位的语义标识cellInput.type text; cellInput.id cell- cellId; cellInput.setAttribute(aria-label, Cell cellId); cellInput.setAttribute(data-cell, cellId);idcell-A1正是solve_task中session.click_element(pid, #cell-A1)的选择器来源aria-labelCell A1则服务于基于语义标签的 Agent 定位。响应式与紧凑布局指南强调使用紧凑 padding/marginp-1、p-2、gap-1、gap-2布局需从弹窗尺寸300×200到全桌面均可工作避免固定宽高使用min-h-0、overflow-auto保证视口缩小时关键元素仍可见根元素用classflex h-full w-full填满整个窗口。范例中根容器使用flex flex-col h-full w-full p-4 overflow-auto表格行由 JavaScript 按grid grid-cols-5生成天然适配不同宽度。全局状态RL 奖励的桥接通道指南约定window.__score保存当前得分RL 奖励使用 0.0–1.0 区间window.__next_move()在 JavaScript 中实现的 AI 策略暴露给solve_task循环调用只返回下一个动作、绝不执行动作或修改环境状态二者以及任意自定义全局状态由env.execute_javascript在 Python 与 GUI 之间桥接。spreadsheet-cell用window.__cellData字典替代标量分数作为评估状态blur、Enter、input 三个事件统一维护window.__cellData {}; // focus: 高亮父容器ring-2 ring-blue-500 // blur: 保存 this.value.trim() 到 __cellData[cellId]空值则 delete // Enter: 保存值并 this.blur() // input: 实时同步 __cellData图标与界面提示图标统一使用iconify-icon元素渲染时自动替换为内联 SVG支持全部 iconify 图标集eva、mingcute、mdi 等。spreadsheet-cell在操作提示条中使用了mdi:information图标并配以text-blue-600颜色类iconify-icon iconmdi:information classtext-blue-600/iconify-icon同时界面底部给出了面向智能体的明确操作引导文案Click a cell to select it, then type to enter data. Press Enter to confirm.——这类内嵌提示能显著提升 Agent 对任务完成条件的理解。动作类型参考env.step()支持的动作类定义于 libs/cua-bench/cua_bench/actions.py 并由 libs/cua-bench/cua_bench/types.py 导出分为三类鼠标动作ClickAction(x, y)— 左键单击RightClickAction(x, y)— 右键单击DoubleClickAction(x, y)— 双击DragAction(from_x, from_y, to_x, to_y, duration1.0)— 拖拽ScrollAction(directionup|down, amount100)— 滚动键盘动作TypeAction(texthello)— 输入文本KeyAction(keyEnter)— 按键HotkeyAction(keys[ctrl, c])— 组合键控制动作DoneAction()— 宣告任务完成WaitAction(seconds1.0)— 等待源码细节actions.py还提供了两套文本解析器——repr_to_action解析ClickAction(x100, y200)形式的 repr 字符串snake_case_to_action解析click(0.5, 0.5)、type(hello)形式的指令文本坐标支持整数与浮点数整数值自动转 int。这意味着除直接构造动作对象外Agent 也可输出动作描述字符串交由框架解析动作类型还额外支持MiddleClickAction、MoveToAction等。屏幕尺寸setup_config 的关键参数屏幕尺寸在env.create_sandbox的setup_config参数中指定。spreadsheet-cell使用 1024×768而指南完整列出了 cua-bench 支持的全部标准分辨率当前默认 1920×1080分类分辨率说明桌面标准1920×1080Full HD当前默认桌面标准1366×768HD笔记本标准桌面标准2560×14402K/QHD桌面标准3840×21604K/UHD桌面标准1280×720HD Ready桌面标准1600×900HD桌面标准1920×1200WUXGA桌面标准2560×1600WQXGA桌面标准3440×1440Ultrawide QHD桌面标准5120×1440Super Ultrawide移动/平板1024×768iPad竖屏移动/平板768×1024iPad横屏移动/平板360×640手机竖屏移动/平板640×360手机横屏传统1024×600Netbook传统800×600SVGA传统640×480VGA其他常见1440×900 / 1680×1050 / 1920×1440 / 2560×1080 / 3440×1440 / 3840×1080定制笔记本、WSXGA、4:3 及超宽屏实战建议选择与任务真实场景匹配的屏幕尺寸——桌面办公类任务用 1920×1080 或 1366×768移动端任务用 360×640 系列窗口内布局需保证在目标尺寸下无溢出。注意setup_config中同时存在width/height沙箱屏幕与launch_window的width/heightwebview 窗口两套尺寸需分别设置。最佳实践与常见陷阱综合指南与源码编写 cua-bench 任务环境时应遵循保持main.py最小化只写装饰器与基础逻辑环境搭建、任务加载游戏/任务逻辑全部放入gui/的 JavaScript 中。AI 策略放 GUI 侧通过window.__next_move()暴露该函数只返回下一个动作不执行任何动作、不修改环境状态实际执行一律交给env.step/env.bot在solve_task中循环调用直至任务解决。奖励走全局状态用window.__score0.0–1.0 区间或自定义状态如window.__cellData承载 RL 奖励所需数据。参数化变体用 Task metadata 参数化难度、尺寸、OS、轮数等一次声明批量生成变体。慎用WaitAction除非任务确实需要如等待页面加载、等待下一个动作可用否则优先依赖env.bot内置的 actionability 逻辑自动等待元素可点击减少无谓等待。坐标换算所有x,y均为屏幕坐标原点在屏幕左上角浏览器视口坐标需用window.screenX/window.screenY换算偏移。按需选择屏幕尺寸选择与任务和环境匹配的分辨率桌面任务避免过小窗口移动任务避免桌面分辨率。GUI 可访问性语义标签 aria-label 明确的提示文案如界面中的操作说明条既能提升真实可用性也显著改善视觉模型与 Agent 的元素识别成功率。运行与验证单个任务可交互式运行libs/cua-bench/datasets/cua-bench-basic/README.md# 运行 cua-bench 基础任务交互式 python -m cua_bench.interact spreadsheet-cell/main.pymain.py末尾的if __name__ __main__: cb.interact(__file__)提供了同一入口。cua-bench 框架的完整入口、批处理与训练管线可继续查看 libs/cua-bench/cua_bench 下的cli/、runner/、trainer/等子模块以及基准任务数据集 libs/cua-bench/datasets/cua-bench-basic含 click-button、fill-form、drag-drop 等 13 类任务与其他任务库 libs/cua-bench/datasets/cua-bench-kicad、libs/cua-bench/datasets/cua-bench-workflows均遵循本文所述的同一脚手架规范。小结spreadsheet-cell是理解 cua-bench 任务环境脚手架的最小完整样本——tasks_config用双重循环参数化 5 个变体setup_task启动 700×500 的 WebViewsolve_task以点击#cell-{cell}→ 输入值 → 回车三步参考解执行evaluate_task通过window.__cellData精确比对给出 0/1 奖励。掌握这四个装饰器与 GUI 全局状态约定即可按同一模式为任意 Computer-Use 交互场景表单、表格、编辑器、多媒体控制等搭建可用于 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考