# https://github.com/xlang-ai/OSWorld 项目说明书 生成时间：2026-06-13 15:39:15 UTC ## 目录 - [Overview and System Architecture](#page-1) - [Environment Providers and Deployment](#page-2) - [Agent Framework and Baselines](#page-3) - [Evaluators, Benchmark Tasks, and Known Issues](#page-4) ## Overview and System Architecture ### 相关页面 相关主题：[Environment Providers and Deployment](#page-2), [Agent Framework and Baselines](#page-3), [Evaluators, Benchmark Tasks, and Known Issues](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/xlang-ai/OSWorld/blob/main/README.md) - [desktop_env/server/main.py](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/server/main.py) - [desktop_env/evaluators/README.md](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/evaluators/README.md) - [monitor/README.md](https://github.com/xlang-ai/OSWorld/blob/main/monitor/README.md) - [mm_agents/os_symphony/agents/worker.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/worker.py) - [mm_agents/os_symphony/agents/os_aci.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/os_aci.py) - [mm_agents/os_symphony/agents/searcher_agent.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/searcher_agent.py) - [mm_agents/os_symphony/agents/coder_agent.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/coder_agent.py) - [mm_agents/vlaa_gui/agents/worker.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/agents/worker.py) - [mm_agents/coact/autogen/agentchat/contrib/capabilities/transforms.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/coact/autogen/agentchat/contrib/capabilities/transforms.py)
# 总览与系统架构 ## 项目定位与目标 OSWorld 是一个面向计算机使用代理（computer-use agents）的可扩展真实操作系统环境基准测试平台，旨在评估多模态代理在真实桌面任务中的表现。平台支持 VMware、VirtualBox、Docker 与 AWS 等多种执行环境，并通过统一的接口对外提供任务执行与观测能力（资料来源：[README.md]()）。 最新版本 v0.1.16 引入了 VirtualBox 快照支持、AWS 云环境适配，以及针对 Gemini 1.5-Pro、Llama-3、Qwen 等模型的优化配置（资料来源：[GitHub Releases v0.1.16]()）。项目同时维护一个公开排行榜与数据集浏览器，供研究者比较不同代理在测试集（test_all / test_small）上的成功率。 ## 核心架构 OSWorld 的整体架构由三层组成：环境层、代理层与监控层。环境层负责提供可复现的桌面虚拟机实例；代理层通过统一接口与 VM 交互并产出动作；监控层则以 Web 仪表盘形式实时跟踪任务状态。 ```mermaid graph TB A[Agent 代理层
mm_agents/] --> B[Environment 环境层
desktop_env/] B --> C[VMware / VirtualBox / Docker / AWS] B --> D[Server 服务端
desktop_env/server/] D --> E[Accessibility Tree 无障碍树] A --> F[Monitor 监控层
monitor/] F --> G[Web Dashboard
Flask] H[Evaluator 评估器
desktop_env/evaluators/] --> B ``` 环境层通过 `desktop_env/server/main.py` 中的服务端模块对外暴露屏幕截图、无障碍树与多种操作系统（Ubuntu、Windows、macOS）的语义映射，使代理可以以结构化方式获取 UI 状态（资料来源：[desktop_env/server/main.py]()）。代理层在每一步接收观察值（截图或 a11y tree），经由 LLM 推理后产出动作（点击、键入、代码执行等），并通过 worker 模块循环推进任务（资料来源：[mm_agents/os_symphony/agents/worker.py]()）。 ## 代理实现与变体 `mm_agents/` 目录包含多个并行的代理实现，每个实现针对不同模型与交互策略进行了优化： | 代理模块 | 主要职责 | 关键特性 | |---------|---------|---------| | `os_symphony` | 编排多步骤桌面任务 | 集成 Search Agent（教程检索）、Coder Agent（代码生成）与 Orchestrator（行动调度） | | `vlaa_gui` | 视觉-语言-动作代理 | 支持 Gate Agent（完成门控）、Reflection（反思）、Procedural Memory（程序性记忆） | | `coact` | 多代理协作 | 基于 AutoGen 框架，支持 `TransformMessages`、`VisionCapability`、`ToolsCapability` 等能力组合 | `Worker` 类负责驱动代理的主循环，包括加载任务到系统提示、注入侦察上下文（recon_context）、调用搜索代理结果以及在终末步骤强制做出 `agent.done()` 或 `agent.fail()` 决策（资料来源：[mm_agents/vlaa_gui/agents/worker.py]()）。`os_aci.py` 中的 ACI（Action）模块封装了原子动作，并通过严格的搜索查询规则（必须以 "How to" 开头、聚焦单一意图）确保检索质量（资料来源：[mm_agents/os_symphony/agents/os_aci.py]()）。 `coact` 实现继承自 AG2ai 的 AutoGen 项目，提供消息变换、视觉能力与工具能力等可组合插件，例如 `TransformMessages` 限制历史消息数量或 token 长度，`VisionCapability` 为非多模态模型注入图像描述（资料来源：[mm_agents/coact/autogen/agentchat/contrib/capabilities/transforms.py]()）。 ## 评估与监控 评估层在代理完成任务后对最终状态进行评分，包含可行任务与不可行任务两类。可行任务的评估器通过文件系统、剪贴板、应用 API 等方式验证任务目标是否达成（资料来源：[desktop_env/evaluators/README.md]()）。不可行任务则要求代理正确识别任务无法完成并调用 `agent.fail()`。 监控层由 `monitor/` 提供，基于 Flask 的 Web 仪表盘支持任务分组、实时状态、截图/视频回放以及模型配置管理。可通过 `.env` 文件自定义任务路径、结果路径、模型名称与端口等参数（资料来源：[monitor/README.md]()）。 ## 常见故障模式与社区关注 根据社区反馈，OSWorld 在实际使用中存在若干已知问题： - **评估器过于宽松**：部分可行任务评估器仅做最终状态的松散子串匹配，未验证因果与状态变化，可能导致 `reward=1` 但任务实际未完成（资料来源：[GitHub Issue #518]()）。 - **VM 启动弹窗干扰**：从 `Ubuntu.qcow2` 快照恢复后，Snap Store 软件更新弹窗会在首次截图时出现，干扰基于视觉的代理（资料来源：[GitHub Issue #515]()）。 - **代理基线差异**：Pixel-blind CLI 代理在 `test_all` 上得分达到 77.9%，显著高于视觉代理的 64.3%，提示界面形式对评估结果影响重大（资料来源：[GitHub Issue #517]()）。 - **Docker DevTools 端口异常**：在使用 `happysixd/osworld-docker` 镜像时，Chrome DevTools 端口可能返回 400，即使代理配置已验证（资料来源：[GitHub Issue #495]()）。 - **任务标注缺陷**：少数任务目标页不存在却被列为可行任务，影响基准可信度（资料来源：[GitHub Issue #430]()）。 ## See Also - [Setup Guideline - Proxy Configuration](SETUP_GUIDELINE.md) - [Evaluation Examples 数据集](../evaluation_examples/) - [Monitor Dashboard 使用指南](../monitor/README.md) --- ## Environment Providers and Deployment ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Evaluators, Benchmark Tasks, and Known Issues](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [desktop_env/providers/base.py](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/providers/base.py) - [desktop_env/providers/vmware/provider.py](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/providers/vmware/provider.py) - [desktop_env/providers/vmware/manager.py](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/providers/vmware/manager.py) - [desktop_env/providers/virtualbox/provider.py](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/providers/virtualbox/provider.py) - [desktop_env/providers/docker/provider.py](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/providers/docker/provider.py) - [desktop_env/providers/docker/manager.py](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/providers/docker/manager.py) - [desktop_env/providers/aws/provider.py](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/providers/aws/provider.py) - [desktop_env/evaluators/README.md](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/evaluators/README.md) - [desktop_env/server/README.md](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/server/README.md) - [README.md](https://github.com/xlang-ai/OSWorld/blob/main/README.md)
# Environment Providers and Deployment ## 概述 OSWorld 是一个面向计算机使用代理（Computer-Use Agents）的多模态真实操作系统基准测试平台，其核心特征之一是支持多种虚拟化与云端部署方式。环境提供器（Environment Provider）模块负责将不同基础设施（VMware、VirtualBox、Docker、AWS）抽象为统一的接口，使得代理与任务评估代码能够以一致的方式启动、重置、截图与关闭虚拟桌面。资料来源：[README.md:1-15]() 根据 v0.1.16 发布说明，OSWorld 已经将 "VM + Cloud support" 作为重要里程碑纳入版本，包括 VirtualBox 快照支持、AWS 优化接口映射以及针对代理模型的扩展配置。资料来源：[v0.1.16 release notes](https://github.com/xlang-ai/OSWorld/releases/tag/v0.1.16) ## 提供器架构 OSWorld 的环境提供器采用经典的 "基类 + 工厂 + 具体实现" 模式。`desktop_env/providers/base.py` 定义了所有提供器必须实现的抽象方法，包括启动（`start_env`）、停止（`stop_env`）、获取屏幕信息（`get_screen_size`）、获取截图（`get_screenshot`）、执行命令（`execute_command`）与文件传输（`upload_file`/`download_file`）等。资料来源：[desktop_env/providers/base.py]() 每一类具体提供器都包含两个核心组件： | 组件 | 职责 | 典型文件 | |------|------|----------| | Provider | 单实例虚拟机的生命周期管理 | `vmware/provider.py`、`virtualbox/provider.py`、`docker/provider.py` | | Manager | 多实例并行环境调度与快照恢复 | `vmware/manager.py`、`docker/manager.py` | 下面展示提供器与上层 DesktopEnv 之间的协作流程： ```mermaid flowchart LR A[Agent/评估脚本] --> B[DesktopEnv] B --> C{Provider 选择} C --> D[VMware Provider] C --> E[VirtualBox Provider] C --> F[Docker Provider] C --> G[AWS Provider] D --> H[VMware Manager] E --> I[VirtualBox Manager] F --> J[Docker Manager] G --> K[AWS EC2] H --> L[Ubuntu.qcow2 / .vmx] I --> M[Ubuntu.vdi] J --> N[osworld-docker image] K --> O[AMI Snapshot] ``` 资料来源：[desktop_env/providers/vmware/provider.py]()、[desktop_env/providers/docker/provider.py]() ## 主要提供器详解 ### VMware 提供器 VMware 提供器支持在本地主机上加载 `.vmx` 虚拟机文件，并通过 `vmrun` 命令控制 VM 生命周期。其管理器支持从快照恢复、为不同任务克隆独立环境以实现并行评估。资料来源：[desktop_env/providers/vmware/manager.py]() 社区用户在使用 VMware Fusion 时曾遇到启动失败问题，例如在 Mac M4 上执行 `python quickstart.py --provider_name vmware --path_to_vm .../Ubuntu.vmx` 时虚拟机未能正确挂载。资料来源：[Issue #407](https://github.com/xlang-ai/OSWorld/issues/407) ### VirtualBox 提供器 自 v0.1.16 起引入 VirtualBox 支持，目标是提供 "free VM snapshots"，降低本地部署成本。VirtualBox 提供器复用相同的 Provider 接口，底层通过 `VBoxManage` 命令操作 `.vdi` 镜像。资料来源：[desktop_env/providers/virtualbox/provider.py]()、[v0.1.16 release notes]() ### Docker 提供器 Docker 提供器将完整的图形化 Ubuntu 桌面打包进容器，通过 X11/VNC 暴露给宿主机，再由宿主机侧的 `xdotool`、`scrot` 等工具捕获截图与执行交互。资料来源：[desktop_env/providers/docker/provider.py]() 社区曾报告 Docker 容器启动后 Chrome DevTools 端口返回 400 错误，即便使用官方镜像并配置代理，问题仍出现在网络栈或容器初始化阶段。资料来源：[Issue #495](https://github.com/xlang-ai/OSWorld/issues/495) 此外，从 `Ubuntu.qcow2` 快照重置客户机时，Snap Store 的 "software updates available" 弹窗会出现在第一帧截图中，对基于截图的代理造成干扰。建议在镜像制备阶段禁用自动更新通知。资料来源：[Issue #515](https://github.com/xlang-ai/OSWorld/issues/515) ### AWS 提供器 v0.1.16 引入了 AWS 提供器，使用 EC2 实例运行 Ubuntu AMI。该提供器优化了接口端口映射与实例类型选择，可用于大规模并行评估。资料来源：[desktop_env/providers/aws/provider.py]()、[v0.1.16 release notes]() ## 部署最佳实践与常见陷阱 1. **账号与凭证一致性**：本地提供器（vmware/virtualbox/docker）的 Ubuntu 用户名密码为 `user` / `password`，而 AWS 因安全策略默认使用 `osworld-public-evaluation`。修改后必须同步更新 `DesktopEnv` 与 `Agent` 的 `client_password` 参数。资料来源：[README.md:32-40]() 2. **代理与网络**：当处于 GFW 环境或希望避免被识别为机器人时，需按 [SETUP_GUIDELINE.md](SETUP_GUIDELINE.md) 配置代理。某些任务依赖 sudo 权限，因此客户机端也需配置代理。资料来源：[README.md:44-48]() 3. **评估器副作用**：部分可行任务（feasible task）的 `evaluate()` 仅检查最终状态，使用宽松的子串匹配，可能在没有真正完成动作的情况下返回 `reward=1`。建议在自定义任务时记录前后状态差。资料来源：[Issue #518](https://github.com/xlang-ai/OSWorld/issues/518) 4. **服务自启动**：环境依赖开机自启的 daemon 服务（截图、a11y 树读取、剪贴板桥接等）。镜像必须保证这些服务处于 `enabled` 状态。资料来源：[desktop_env/server/README.md:14-26]() 5. **辅助功能（Accessibility Tree）**：评估代码依赖 a11y 树读取控件属性，必须在镜像中安装对应的 AT-SPI 支持包。资料来源：[desktop_env/server/README.md:18-22]() ## See Also - [Agent 接入指南](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/README.md) - [DesktopEnv 接口说明](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/README.md) - [评估器配置详解](desktop_env/evaluators/README.md) - [快速开始与故障排查](https://github.com/xlang-ai/OSWorld/blob/main/SETUP_GUIDELINE.md) --- ## Agent Framework and Baselines ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Evaluators, Benchmark Tasks, and Known Issues](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [mm_agents/README.md](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/README.md) - [mm_agents/vlaa_gui/agents/worker.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/agents/worker.py) - [mm_agents/vlaa_gui/agents/grounding.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/agents/grounding.py) - [mm_agents/os_symphony/agents/worker.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/worker.py) - [mm_agents/os_symphony/agents/os_aci.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/os_aci.py) - [mm_agents/os_symphony/agents/coder_agent.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/coder_agent.py) - [mm_agents/os_symphony/agents/searcher_agent.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/searcher_agent.py) - [mm_agents/os_symphony/utils/formatters.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/utils/formatters.py) - [mm_agents/vlaa_gui/utils/formatters.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/utils/formatters.py) - [mm_agents/coact/autogen/agentchat/contrib/capabilities/agent_capability.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/coact/autogen/agentchat/contrib/capabilities/agent_capability.py) - [mm_agents/coact/autogen/agentchat/contrib/capabilities/tools_capability.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/coact/autogen/agentchat/contrib/capabilities/tools_capability.py) - [mm_agents/pointer/README.md](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/pointer/README.md) - [README.md](https://github.com/xlang-ai/OSWorld/blob/main/README.md) - [evaluation_examples/README.md](https://github.com/xlang-ai/OSWorld/blob/main/evaluation_examples/README.md)
# Agent Framework and Baselines ## 概述 OSWorld 是一个面向真实操作系统环境的多模态智能体基准测试平台，其核心目标是为研究社区提供一个统一、可复现的桌面代理评估框架。[README.md](https://github.com/xlang-ai/OSWorld/blob/main/README.md) 指出，项目支持 VMware、VirtualBox、Docker、AWS 等多种 Provider，使代理能够在真实 Ubuntu/Windows/macOS 桌面中执行任务。 `mm_agents` 目录是 Agent Framework 的核心载体，集中了多种 Baseline 实现。根据 [mm_agents/README.md](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/README.md) 描述，框架已支持 GPT-3.5/4/4V、Gemini-Pro/Vision、Claude-3、Mixtral 8x7B、QWEN、QWEN-VL、CogAgent、Llama3 等多种基础模型，并通过统一的 `PromptAgent` 接口对外暴露 `predict(instruction, obs)` 调用。开发者可通过 [evaluation_examples/README.md](https://github.com/xlang-ai/OSWorld/blob/main/evaluation_examples/README.md) 中描述的 JSON Schema 自由扩展任务，并通过 `evaluator` 目录为每个任务编写可执行评估脚本。 ## 核心架构 Agent Framework 在抽象层面遵循"观察 → 推理 → 动作 → 执行 → 反馈"的闭环，框架在 `mm_agents` 中通过多套基线实现了不同的具体策略。 ```mermaid flowchart LR A[任务指令] --> B[Worker/Orchestrator] B --> C{观察空间} C -->|screenshot| D[Grounding Agent] C -->|a11y_tree| E[ACI] D --> F[代码生成] E --> F F --> G[Formatter 校验] G --> H[OS/VM 执行] H --> I[下一轮观察] I --> B ``` `Worker` 是整个循环的中枢调度器。在 [mm_agents/vlaa_gui/agents/worker.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/agents/worker.py) 中可见，Worker 在每一轮接收 `obs`（包含截图与可选的 `recon_context`），通过 `gate_agent.propose_criteria` 提议完成门控条件，并将生成的 `agent.click(...)` 等单行代码交给 Grounding Agent 解析坐标；同样地，[mm_agents/os_symphony/agents/worker.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/worker.py) 中的 OS-Symphony Worker 在每轮中会调用 `call_llm_formatted` 并配合 `SINGLE_ACTION_FORMATTER` 和 `CODE_VALID_FORMATTER` 强制保证输出为单一合法 `agent.(...)` 调用。 Grounding Agent 由 [mm_agents/vlaa_gui/agents/grounding.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/agents/grounding.py) 中的 `ACI` 类实现，其核心职责是"自然语言描述 → 屏幕坐标"以及具体原子动作（如 `drag_and_drop`、`save_to_knowledge`、`type`）。该类通过 `agent_action` 装饰器将语义化动作注册到 Agent 上，最终翻译为 `pyautogui` 指令在宿主机执行。 ## 主要 Baseline 实现 `mm_agents` 子目录下沉淀了多套可独立运行的 Baseline，每套都对 `Worker`/Action 协议做了不同的工程化扩展： | Baseline | 入口目录 | 核心特性 | 来源 | | --- | --- | --- | --- | | Prompt Agent | `mm_agents/agent.py` | 最简化的多模态 Prompt 循环，统一暴露 `predict()` | [mm_agents/README.md](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/README.md) | | VLAA-GUI | `mm_agents/vlaa_gui/` | 提供 Gate/Code/Search 多 Agent 协作，内置知识库与程序性记忆 | [mm_agents/vlaa_gui/agents/worker.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/agents/worker.py) | | OS-Symphony | `mm_agents/os_symphony/` | 将 Searcher/Coder 拆为独立子 Agent，支持多步代码执行与教程检索 | [mm_agents/os_symphony/agents/searcher_agent.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/searcher_agent.py) | | CoAct | `mm_agents/coact/` | 基于 AutoGen 改造的 `AgentCapability` / `ToolsCapability` 能力组合 | [mm_agents/coact/autogen/agentchat/contrib/capabilities/agent_capability.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/coact/autogen/agentchat/contrib/capabilities/agent_capability.py) | | Pointer | `mm_agents/pointer/` | 通过 AWS Bedrock 调用，并行环境批量评估 | [mm_agents/pointer/README.md](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/pointer/README.md) | 各 Baseline 都遵循共同的接口约定：以 `agent.(...)` 作为原子动作，由 [mm_agents/vlaa_gui/utils/formatters.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/utils/formatters.py) 中的 `_CODE_VALIDATION_BYPASS_ACTIONS` 集合与 `_is_single_agent_call()` 在静态解析阶段进行校验；OS-Symphony 则在 [mm_agents/os_symphony/utils/formatters.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/utils/formatters.py) 中基于 `tool_config` YAML 进一步约束允许的 `method` 集合。 ## 观察空间、动作空间与扩展指南 框架在 [mm_agents/README.md](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/README.md) 中明确列出两种观察空间：`screenshot`（截图）与 `a11y_tree`（无障碍树）。动作通过 Python 装饰器 `agent_action` 注入，开发者只需在 ACI 子类上定义新方法即可新增原子动作。 新增 Baseline 的标准流程是：(1) 在 `mm_agents//` 下实现 `predict()`；(2) 通过 `call_llm_safe_with_thinking` 等工具函数调用 LLM；(3) 用统一的 `sanitize_code` + `parse_single_code_from_string` 解析输出；(4) 在 `desktop_env` 中执行截图-动作循环。 ## 已知问题与社区反馈 社区在适配 Baseline 时已暴露出若干共性风险，引用如下以供新接入者参考： - **基线分数的对比问题**：Issue #517 报告称，纯 CLI（无视觉）Agent 在 `test_all` 上达到 77.9%，高于传统视觉 Agent 的 64.3%。这表明"基于截图"未必是最优基线，扩展新 Baseline 时应同时关注 a11y tree / 结构化输出。 - **多模态模型调参**：Issue #441 反馈 Qwen3.5-VL 在 `qwen3vl` 流水线下成功率极低，提示在选择 VL Backbone 时需校准 Prompt 与截图分辨率。 - **评估器可靠性**：Issue #518 指出多个 *feasible* 任务的 `evaluate()` 仅做"最终状态子串匹配"便返回 `reward=1`，缺乏对执行过程的因果校验，自定义 Baseline 时应同时复审评估脚本。 - **环境噪声**：Issue #515 报告首次截图常被 Snap Store 更新弹窗污染，可在自定义 Baseline 的预处理阶段增加 `obs["recon_context"]` 清洗步骤（参考 `worker.py` 中对 `recon_context` 的注入逻辑）。 - **Docker 代理配置**：Issue #495 显示 Chrome DevTools 端口返回 400，多与宿主机代理（如 Clash）有关，可参考 [README.md](https://github.com/xlang-ai/OSWorld/blob/main/README.md) 的 Proxy Configuration 章节修正 `HTTP_PROXY` 环境变量。 ## See Also - [Desktop Environment Providers](README.md) - [Evaluation Examples Schema](evaluation_examples/README.md) - [Pointer Agent Setup Guide](mm_agents/pointer/README.md) - [OS-Symphony Coder Agent](mm_agents/os_symphony/agents/coder_agent.py) - [CoAct Capabilities](mm_agents/coact/autogen/agentchat/contrib/capabilities/transforms.py) --- ## Evaluators, Benchmark Tasks, and Known Issues ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Environment Providers and Deployment](#page-2), [Agent Framework and Baselines](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [desktop_env/evaluators/README.md](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/evaluators/README.md) - [evaluation_examples/README.md](https://github.com/xlang-ai/OSWorld/blob/main/evaluation_examples/README.md) - [README.md](https://github.com/xlang-ai/OSWorld/blob/main/README.md) - [scripts/README.md](https://github.com/xlang-ai/OSWorld/blob/main/scripts/README.md) - [mm_agents/vlaa_gui/agents/verifier_agent.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/agents/verifier_agent.py) - [mm_agents/vlaa_gui/agents/worker.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/vlaa_gui/agents/worker.py) - [mm_agents/os_symphony/agents/worker.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/worker.py) - [mm_agents/os_symphony/agents/coder_agent.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/coder_agent.py) - [mm_agents/os_symphony/agents/searcher_agent.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/searcher_agent.py) - [mm_agents/os_symphony/agents/memoryer_agent.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/memoryer_agent.py) - [mm_agents/os_symphony/agents/os_aci.py](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/os_symphony/agents/os_aci.py)
# Evaluators, Benchmark Tasks, and Known Issues ## 1. 概述与设计目标 OSWorld 是一个用于评估计算机使用代理 (computer-use agent) 在真实操作系统任务中表现的基准测试框架。其核心由两个紧密耦合的部分组成：**任务定义** (`evaluation_examples/examples/*.json`) 和 **评估器 (Evaluator)** (`desktop_env/evaluators/`)。评估器决定代理的某个回合是否真正完成了任务，并返回 `reward=1` 或 `reward=0` 用于计算最终成功率 ([README.md](https://github.com/xlang-ai/OSWorld/blob/main/README.md))。 官方在 v0.1.16 中明确指出：任务注释 (annotation) 中存在已知缺陷，并修复了若干报告的问题 ([v0.1.16 release notes](https://github.com/xlang-ai/OSWorld/releases/tag/v0.1.16))。这意味着评估器并非无懈可击，使用者在解读基准分数时需要理解其内部工作方式与已知盲点。 ## 2. 评估器架构与运行环境配置 ### 2.1 评估器接口与目录组织 `desktop_env/evaluators/` 目录下按照应用域（Chrome、GIMP、VLC、VSCode、LibreOffice 等）组织，每个评估器都是一段 Python 代码，运行在客户机 (guest VM) 内部，读取应用状态（文件、注册表、DOM、a11y 树等）并返回布尔奖励。`desktop_env/evaluators/README.md` 详细说明了运行评估器前必须在客户机内完成的设置： ```bash sudo vim /etc/default/apport # 将 enabled 修改为 0，禁用系统崩溃报告 ``` 资料来源：[desktop_env/evaluators/README.md:3-8]() ### 2.2 应用域的额外依赖 不同应用要求客户机内安装特定的 Python 库，评估器才能正确读取文件状态： | 应用 | 所需库 | 关键评估手段 | |------|--------|--------------| | LibreOffice Impress | `python-pptx` | 解析 `.pptx` XML 结构 | | LibreOffice Writer | `python-docx`, `odfpy` | 解析 `.docx`/`.odt` 内容 | | LibreOffice Calc | `openpyxl`, `pandas`, `lxml`, `xmltodict` | 解析 `.xlsx`/`.csv` | | Chrome | DevTools Protocol | DOM 查询、历史记录、Cookie | 资料来源：[desktop_env/evaluators/README.md:10-50]() ### 2.3 评测人员（评测代理）的角色 `mm_agents/vlaa_gui/agents/verifier_agent.py` 中定义了一个 `Verifier Agent`，用于在每一步之后判断任务的不可行性。它通过 `_INFEASIBILITY_SIGNALS` 列表匹配指令或轨迹中的关键短语（如 `"not possible"`、`"there is no"`、`"virtual adapter"` 等），从而识别代理是否发现了任务本身不可行的情况。资料来源：[mm_agents/vlaa_gui/agents/verifier_agent.py]() ```mermaid flowchart LR A[Agent 行动] --> B[环境状态更新] B --> C[Evaluator.get_reward] C --> D{应用域状态匹配?} D -- 是 --> E[reward=1] D -- 否 --> F[Verifier 检查不可行信号] F -- 命中 --> G[标记 infeasible] F -- 未命中 --> H[reward=0] ``` ## 3. 基准任务结构 每个任务定义遵循统一的 JSON schema，记录于 `evaluation_examples/README.md`： | 字段 | 含义 | |------|------| | `id` | 任务的唯一标识符 | | `snapshot` | 关联的 VM 快照 ID（含初始文件与应用窗口） | | `instruction` | 自然语言指令 | | `source` | 任务来源（论坛、论文等） | | `config` | 启动时下载/打开文件的配置脚本 | | `related_apps` | 任务相关的应用列表 | | `evaluator` | 评估器目录，包含该任务的评估脚本 | 资料来源：[evaluation_examples/README.md:5-20]() 评估器调用流程如下： 1. `lib_run_single` 加载任务 JSON； 2. `DesktopEnv` 根据 `snapshot` 恢复客户机状态； 3. Agent 与环境交互执行指令； 4. 最后调用 `evaluator` 目录中的脚本读取应用状态，返回奖励。 `scripts/README.md` 提示用户：所有 Python 脚本均从项目根目录运行，并自动将根目录加入 `sys.path`，以正确导入 `lib_run_single`、`desktop_env`、`mm_agents` 等模块。资料来源：[scripts/README.md]() ## 4. 已知问题与社区反馈 ### 4.1 可行任务评估过松 (Issue #518) 社区报告：多个**可行**任务 (feasible task) 的评估器仅基于最终状态做宽松的子串匹配，可能在代理未真正完成任务时也返回 `reward=1`。根源是 `evaluate()` 只检查终点状态，没有验证因果关系或状态变化 (delta check)。这意味着代理可能"碰巧"得到奖励，或者任务实际未完成却被计为成功 ([issue #518](https://github.com/xlang-ai/OSWorld/issues/518))。这是 OSWorld 评测中最重要的已知偏差之一。 ### 4.2 VM 重置时出现 Snap Store 弹窗 (Issue #515) 当客户机从 `Ubuntu.qcow2` 快照恢复时，桌面经常弹出 "Snap Store / software updates available" 窗口。由于该窗口出现在代理的第一帧观察 (observation) 中，基于截图的代理可能被误导 ([issue #515](https://github.com/xlang-ai/OSWorld/issues/515))。建议在快照准备阶段禁用自动更新通知。 ### 4.3 任务注释缺陷 (Issue #430) 用户报告某些任务 JSON（例如 `chrome/f3b19d1e-2d48-44e9-b4e1-defcae1a0197.json`）目标页面并不存在，但被标记为可行任务 ([issue #430](https://github.com/xlang-ai/OSWorld/issues/430))。建议在提交自定义任务前验证目标状态可达到。 ### 4.4 Chrome DevTools 端口返回 400 (Issue #495) 在使用 Docker 镜像 `happysixd/osworld-docker` 并配置 Clash 代理时，Chrome DevTools 端口返回 400，即使代理已经通过 `curl --proxy` 验证可用 ([issue #495](https://github.com/xlang-ai/OSWorld/issues/495))。这通常与容器网络命名空间配置或 DevTools 协议版本不兼容有关。 ### 4.5 模型配置差异显著 (Issue #441) 使用 `qwen3vl` 流水线评估 Qwen3.5-VL 时成功率显著偏低，社区询问是否有官方推荐配置 ([issue #441](https://github.com/xlang-ai/OSWorld/issues/441))。这提示了**视觉模型与 CLI 模型之间的系统性差异**：issue #517 报告了一个无视觉的 CLI 代理在 `test_all` 上达到 77.9%，而对应的视觉版本仅 64.3% ([issue #517](https://github.com/xlang-ai/OSWorld/issues/517))。 ### 4.6 阿里云无头配置问题 (Issue #480) 社区讨论：在阿里云环境使用 X11 `DummyScreen` 配置时容易破坏图形界面，需要额外的 `xorg.conf` 配置 ([issue #480](https://github.com/xlang-ai/OSWorld/issues/480))。 ## 5. 最佳实践与故障排除 1. **运行评估器前禁用崩溃报告**：修改 `/etc/default/apport` 中的 `enabled=0`，避免评估过程中弹出对话框污染状态 ([desktop_env/evaluators/README.md:5-8]())。 2. **依赖库必须在客户机内安装**：`pip install python-pptx` 等命令应在 VM 内执行，而非主机。 3. **从快照恢复后立即关闭弹窗**：参考 #515，可在快照制作阶段运行 `sudo apt autoremove snapd` 或禁用更新通知守护进程。 4. **脚本必须从项目根目录运行**：`scripts/README.md` 明确警告路径解析依赖根目录导入 ([scripts/README.md]())。 5. **解读奖励值时考虑评估偏差**：参考 #518，对于结果反常的任务，应手动审查轨迹而非仅依赖 `reward`。 6. **复杂任务交给 Search Agent**：当主代理遇到应用层困难时，`mm_agents/os_symphony/agents/searcher_agent.py` 和 `coder_agent.py` 提供教程搜索与代码生成能力，结果通过 `os_aci.py` 注入到系统提示 ([mm_agents/os_symphony/agents/worker.py]())。 7. **在最终步骤强制终端决策**：`Worker` 在 `is_last_step=True` 时显式注入提示，要求代理在 `agent.done()` 或 `agent.fail()` 之间选择 ([mm_agents/vlaa_gui/agents/worker.py]())。 ## See Also - [README.md](https://github.com/xlang-ai/OSWorld/blob/main/README.md) — 项目总览与评测入口 - [SETUP_GUIDELINE.md](https://github.com/xlang-ai/OSWorld/blob/main/SETUP_GUIDELINE.md) — 代理配置、代理与 Google 账号设置 - [desktop_env/README.md](https://github.com/xlang-ai/OSWorld/blob/main/desktop_env/README.md) — 环境接口 - [mm_agents/README.md](https://github.com/xlang-ai/OSWorld/blob/main/mm_agents/README.md) — 代理接口 - [v0.1.16 Release Notes](https://github.com/xlang-ai/OSWorld/releases/tag/v0.1.16) — 最新发布说明 --- --- ## Doramagic 踩坑日志 项目：xlang-ai/OSWorld 摘要：发现 11 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：Guest VM shows a Snap Store "software updates available" popup on reset, derailing screenshot agents。 ## 1. 安装坑 · 来源证据：Guest VM shows a Snap Store "software updates available" popup on reset, derailing screenshot agents - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Guest VM shows a Snap Store "software updates available" popup on reset, derailing screenshot agents - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/xlang-ai/OSWorld/issues/515 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 2. 维护坑 · 来源证据：Proposal: trace diagnostics for computer-use agent failures - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Proposal: trace diagnostics for computer-use agent failures - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/xlang-ai/OSWorld/issues/514 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 安全/权限坑 · 来源证据：Container starts but Chrome DevTools port returns 400, even with clean happysixd/osworld-docker image and verified proxy - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Container starts but Chrome DevTools port returns 400, even with clean happysixd/osworld-docker image and verified proxy - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/xlang-ai/OSWorld/issues/495 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 安全/权限坑 · 来源证据：Feasible-task evaluators return reward=1 without verifying the task was done (loose substring matching, no causation/de… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feasible-task evaluators return reward=1 without verifying the task was done (loose substring matching, no causation/delta check) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/xlang-ai/OSWorld/issues/518 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 安全/权限坑 · 来源证据：Pixel-blind CLI agent scores 77.9% on OSWorld test_all (vs 64.3% vision) — sharing a CLI baseline + intent-aware judge - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Pixel-blind CLI agent scores 77.9% on OSWorld test_all (vs 64.3% vision) — sharing a CLI baseline + intent-aware judge - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/xlang-ai/OSWorld/issues/517 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 6. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | github_repo:705433049 | https://github.com/xlang-ai/OSWorld | README/documentation is current enough for a first validation pass. ## 7. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | github_repo:705433049 | https://github.com/xlang-ai/OSWorld | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | github_repo:705433049 | https://github.com/xlang-ai/OSWorld | no_demo; severity=medium ## 9. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | github_repo:705433049 | https://github.com/xlang-ai/OSWorld | no_demo; severity=medium ## 10. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | github_repo:705433049 | https://github.com/xlang-ai/OSWorld | issue_or_pr_quality=unknown ## 11. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | github_repo:705433049 | https://github.com/xlang-ai/OSWorld | release_recency=unknown