computer-use

---
name: computer-use
description: >-
  构建 GUI 自动化 Agent、让 Agent 像人一样看屏幕并用鼠标键盘操作桌面或浏览器软件时使用。
  覆盖感知-思考-行动循环、动作空间（GUI/bash/文件编辑）、视觉定位 Grounding 三条路线
  （结构化元素索引、Set-of-Mark、纯坐标预测）、分辨率坐标缩放、关键帧观察接口、世界模型与移动端生态壁垒。
  触发词：Computer Use、GUI 自动化、截图、Grounding、browser-use、Set-of-Mark、视觉定位、坐标缩放、OSWorld。
---

# Computer Use：GUI 自动化 Agent

## 何时使用

- 要让 Agent 操作没有 API 的软件：填表、改系统设置、在网页上完成多步流程。
- 要评估或实现"截图 → 决策 → 执行动作"的闭环，选模型、选 grounding 方案、选框架。
- 定位不准、坐标偏移、点击错元素，需要排查 grounding 与坐标缩放链路。
- Agent 每 3–5 秒才看一眼屏幕，错过通知、视频、弹窗等"两帧之间发生的事"。
- 要把 Computer Use 扩展到移动端（Android 无障碍服务）或评估平台封禁风险。
- 设计不可逆操作（删除、购买、提交）前的确认与安全边界。
- 要减少操作步数与等待时间，让 Agent 达到"实用"而不只是"答对"（对照 OSWorld-Human 的人类基线）。
- 没有编程 API 可用、Selenium 之类脚本化方案难以维护页面的场景。
- 要在容器化虚拟桌面中跑 Agent，并隔离不可逆操作对真实环境的影响。

## 核心原则

- **核心是感知-思考-行动循环**：截图 → 多模态模型输出思考 + 一个动作 → 执行层真实执行（移动鼠标、点击、输入）→ 等界面响应再截图进入下一轮。
- **区分"看懂界面"和"完成任务"**：前者可用一次截图问答测量（多模态理解）；后者要求把理解和动作放进闭环，处理页面加载、状态变化、误操作和不可逆后果。每执行一步都要**重新确认现实是否仍符合计划**。
- **动作空间分三类**：GUI 操作（鼠标移动/点击/拖拽/滚动、键盘输入/组合键/长按、截图与等待）、持久 bash 会话（跨调用保持环境状态，用哨兵字符串判命令是否执行完）、字符串匹配的文件编辑（比整文件覆盖更精确，可撤销）。
- **动作空间不是供应商私有协议**：只要 Harness 能把同样的截图、动作约束和执行结果转换成目标模型支持的消息与结构化输出，Claude、开放权重视觉模型和自托管端点都能驱动同一个循环。
- **Grounding 优先把定位变成选择题**：先给元素编号，模型只报 ID，系统换算中心坐标。选择题比填空题容易答对——模型说"点击 [123]"而不是"点击 (350, 464)"。三条路线按界面性质选：
  - **结构化元素索引**（DOM / Accessibility Tree，browser-use 路线）：结构化信息可得时首选，最精确稳定，无分割模型的漏检误检。
  - **Set-of-Mark 视觉标注**：用分割模型切候选区域叠加编号，不需要 DOM，原生桌面软件、游戏、Canvas/WebGL 界面适用。
  - **纯坐标预测**（SeeClick、Claude computer use）：直接在 GUI 截图-坐标配对上训练的模型更直接，省去标注步骤，但小元素和密集界面精度差。
- **坐标预测必须做分辨率管理**：模型对坐标的理解依赖训练分辨率，不匹配就系统性偏移。按**宽高比**选最接近的目标分辨率做双向缩放（如 2560×1440 的 16:9 屏幕选 FWXGA 1366×768，模型返回 (683,384) 反推真实坐标约 (1280,720)）。切忌非等比拉伸把画面压扁。
- **"屏幕是静止的"是危险假设**：该重新设计的是观察接口而不是动作接口——用关键帧截图（小模型判断是否有意义的变化，变化频繁时约 1 秒一次）、音量门控的语音转写、把截图压成一句持久文字描述来压缩多模态历史。
- **世界模型带来"推测执行"**：行动前预测候选动作造成的状态差异，一致就沿计划继续，偏离才停下重规划。要预测的是**可检查的状态差异**（窗口、焦点、滚动位置、输入框内容、加载状态、权限、网络返回），不是生成逼真未来截图。
- **生态壁垒是结构性问题**：Agent 直达目标会绕过广告与推荐变现链路，平台有动机封禁；这不只是 CAPTCHA 的技术对抗，短期难以调和。
- **循环节奏与尺度**：Computer Use 的时间尺度是亚秒到秒——屏幕在两帧之间持续变化，因此"动作后重新确认现实"不是可选项而是循环的必要组成部分。这与语音（10ms–1s，可被打断）和机器人（毫秒级，动作分块可抢占）是不同的时机问题。
- **结构化索引不省 token 但省错误**：把所有可交互元素及其属性发给模型成本高，但换来定位准确稳定，且免去分割模型的漏检误检——这是值得的交换。
- **browser-use 式四步流程**：CDP 取 DOM 与无障碍信息 → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成"ID → 元素描述"文本列表；模型只输出 ID，系统用中心坐标执行。

## 实践模式

1. **搭循环**：Harness 负责截图、把动作约束转换成目标模型支持的消息与结构化输出、执行结果回传。同一套循环可换驱动模型（Claude、开放权重 VLM、自托管 vLLM/SGLang 端点），并保留实际端点与模型 ID 以便区分实验组。
2. **选 grounding 路线**：先问"这个界面有没有结构化信息可得"——Web 走 DOM/a11y 索引（CDP 取 DOM → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成 ID 到元素的文本列表）；原生桌面软件、Canvas/WebGL、游戏走视觉标注或坐标预测；模型做过 GUI 定位训练才优先坐标预测。
3. **实现坐标缩放层**：枚举目标模型支持的分辨率档位，按宽高比匹配；截图时等比缩放送入，动作坐标按比例反算回真实屏幕。
4. **每步只做一个动作**：保留每步截图与动作轨迹，便于回放和验收；页面加载用 `wait`，不要盲点。
5. **安全边界**：默认只读；不点击验证码、不登录、不提交、不购买、不改外部数据；不可逆操作先在隔离虚拟桌面预测是否出现确认框，必要时请求用户确认。凭证不落盘，最终截图要能佐证结论。
6. **恢复策略要预置**：遇到验证码、权限弹窗、页面 404 时按只读恢复指令改走可达路径（如改用公开 JSON 接口取数据），而不是反复重试或点击挑战。
6. **增强观察接口**：关键帧 + 音量门控 ASR + 文字描述三件套，让 Agent 对弹窗、视频、会议人声有感知，并让被清理出上下文的原图仍留下文字痕迹。
7. **移动端适配**：动作空间从"鼠标坐标 + 键盘"换成无障碍服务 API（如 Android AccessibilityService）读写元素、下发点击与输入；坐标语义变为手势类型（单击/长按/滑动起点）的边界。
8. **验收要测量效率**：准确率达到人类水平不等于实用——对照人类操作步数与等待时间，把"步骤数、总时长"纳入验收指标，并记录真实运行证据（截图哈希、动作轨迹）。

## 常见陷阱

- **把截图答对当成任务完成**：没有闭环、不重新确认现实，页面早已跳转还在点原来的坐标。
- **非等比缩放**：把 16:9 硬塞进 4:3，画面横向压扁，坐标判断整体偏移。
- **分辨率不匹配不换算**：直接把模型在训练分辨率下输出的坐标当真实屏幕坐标用。
- **密集界面/小元素上裸报坐标**：三条路线在此都容易出错，优先编号选择题方案。
- **分割模型漏检误检**：视觉标注路线里候选区域切错，模型只能从错的选项里选。
- **每步多个动作**：中间页面变化无法回放定位，错误无法归因。
- **假设屏幕静止**：两帧之间的通知、视频、声音全部丢失，任务在错误的世界观上推进。
- **忽视平台封禁与验证码**：消费级场景中账号可能被直接限制，比技术问题更难解。
- **只关注准确率不看效率**：步骤数和等待时间远超人类，成功也不可用。
- **把不同模型的运行混为一组**：供应商与开放权重是不同实验组，必须分别记录端点、模型 ID 与证据。

## 配套代码

- `chapter6/claude-computer-use-native/` — 实验 6-8（Anthropic 原生路径）：容器化 Ubuntu 桌面中的官方 Computer Use Demo，`computer` / `bash` / 编辑器三类原生工具的真实运行与确定性验收记录。
- `chapter6/computer-use-open-model/` — 实验 6-8/6-9（开放模型路径）：同一"截图 → 结构化动作 → 浏览器执行"循环，默认 Qwen3-VL 32B Instruct 驱动 browser-use，可接 OpenRouter 或自托管 vLLM/SGLang；含端点合格性契约（收截图、产出 Browser Use 动作 schema、每步一个动作、不静默替换模型）。
- 两个 companion 都保留了真实运行证据（截图哈希、动作轨迹、确定性验收），可作为自己实现时的证据门禁模板；其中原生路径还记录了一次撞上 Google reCAPTCHA 后按只读恢复指令改走公开天气 JSON 接口、全程未点击挑战的完整轨迹。
- 语音相关（同为"时机"扩展，可作对照）：`chapter6/end-to-end-speech/`、`chapter6/streaming-speech/`、`chapter6/controllable-tts/`、`chapter6/live-audio/`、`chapter6/phone-agent/`。
- 机器人相关（从屏幕像素到物理传感器）：`chapter6/gemini-xlerobot-navigation/`、`chapter6/rgb-sim2real-grasping/`、`chapter6/xlerobot-teleoperation/`。
- 移动端基准与评测可参考第七章 AndroidWorld 一节；本章 `chapter6/phone-agent/` 给出真实手机上的 Agent 驱动样例。

## 深度阅读

- `book/chapter6.md`「模态与触发时机的扩展」
- `book/chapter6.md`「Computer Use：GUI 自动化 Agent」
- 实验记录与证据门禁模板见 `chapter6/computer-use-open-model/` 与 `chapter6/claude-computer-use-native/` 的 README 与 `validation/` 目录。

More agent context in bojieli/ai-agent-book

21 other files this repository gives its agents.