跳转至

13 桌面控制器：看屏幕并操作

你能完成

  • 在你确认的前提下，让模型对桌面应用执行一步步操作：点击/双击/右击、滚动、拖拽、键盘快捷键、输入文本。
  • 用“归一化截图坐标系”稳定定位 UI 元素，避免不同分辨率/DPI 下坐标漂移。
  • 对每一次动作进行“可见提示 + 可回溯落盘”，方便审计与复盘。

原理：EVA 如何实现“看图→行动”

1) 控制器截图与归一化坐标系

  • 当你在“约定”面板勾选 桌面控制器 后，EVA 会在需要时捕获一张“控制器截图”，并随消息一起发给模型用于定位。
  • 该截图会被强制缩放到设置的 X×Y（默认 1000×1000，可在约定面板调整），并且不保持宽高比：
    目的不是还原真实比例，而是把任意屏幕映射到一个规则矩形，让坐标换算稳定、简单。
  • 模型在调用工具时输出的 bbox=[x1,y1,x2,y2]，必须使用这张“归一化截图”的像素坐标：
    原点在左上角，x 向右、y 向下，范围约为 x∈[0,X]、y∈[0,Y]。
  • EVA 执行动作时取 bbox 的中心点，再用线性比例映射回真实屏幕坐标执行点击/移动/拖拽等动作。
  • 为了避免截图被自身 UI 干扰，EVA 会在截屏前临时：
  • 隐藏桌面控制器的叠加提示层；
  • 用遮罩盖住 EVA 输出区的对话内容（保证截图更“干净”，减少误导）。

2) 一次调用 = 一个原子动作（多轮推进）

  • controller 工具的设计约束是：一次调用只做一个原子动作（例如“左键单击一次”“输入一段文字”“按一次 Ctrl+S”）。
  • 复杂任务（例如“查找→替换→保存→确认结果”）应拆成多轮调用：
    每一步执行完，EVA 会尽量提供更新后的最新截图，模型再基于最新截图继续定位下一步目标。

3) 叠加提示与落盘复盘

  • 每次执行前，EVA 会在目标位置显示一个红色叠加提示（中心点 + 80×80 目标框 + description 文案），并等待约 2 秒，让你看清将要执行的动作。
  • 执行完毕后，会显示一个绿色完成态提示并再停留约 2 秒，用于确认动作已经发生。
  • 同时，EVA 会把模型传入的 bbox/action/description/to_bbox... 等信息绘制到“模型所见截图”上，并保存到：
  • EVA_TEMP/controller_snapshots/：控制器原始截图（归一化后）
  • EVA_TEMP/overlay/：带标注的复盘截图（便于检查 bbox 是否点对了）

效果与安全边界

  • 强风险工具：它能真实操作你的桌面。仅在你信任当前驾驶员、且任务确实需要桌面操作时启用。
  • 只在你明确授权桌面操作时使用：如果只是问答/解释/翻译，不应触发桌面控制器。
  • 不要操作 EVA 自己的输入框来“替你发言”：模型应以文本回复完成回答；桌面控制器用于控制其他应用/系统界面。
  • 随时中止：执行中如发现动作不对，立即点击 重置 终止本轮推理/工具链，必要时再点一次清空会话重来。

操作流程（指挥员视角）

  1. 准备视觉能力
  2. 本地模式：在“设置”选择视觉编码模型 mmproj（否则模型看不到截图，无法定位）。
  3. 链接模式：确认远端端点支持 image_url（多模态）。
  4. 启用桌面控制器工具
  5. 打开“约定”面板，勾选 桌面控制器。
  6. （可选）设置“归一化尺寸”X×Y：元素很小/界面复杂可适当增大；尺寸越大截图越清晰，但也更占 token。
  7. 给出可执行的指令
  8. 明确目标应用与期望结果，并允许其“分步执行、每步确认”。
  9. 建议写法：
    • “请用桌面控制器把窗口 A 里的 XXX 替换成 YYY；分步进行，每一步先说明要做什么再执行。”
  10. 观察叠加提示并确认
  11. 红色提示出现时，核对 description 是否符合预期、落点是否正确；确认无误再让其继续。
  12. 绿色提示出现后，通常代表动作已完成；模型会基于最新截图继续下一步或结束。
  13. 复盘（可选）
  14. 若动作点错/定位不稳，到 EVA_TEMP/overlay/ 查看标注截图，通常能快速判断是截图缺失、目标不可见还是 bbox 不准确。

动作与参数（简表）

  • bbox（必填）：目标框 [x1,y1,x2,y2]，坐标来自最新归一化截图。
  • action（必填）：动作类型，例如 left_click / type_text / press_key / scroll_down / drag_drop 等。
  • description（必填）：会显示在屏幕叠加提示中的动作说明文本（用于你确认）。
  • key：press_key 必填，例如 "Enter"、"Ctrl+S"、"Alt+F4"。
  • text：type_text 必填，表示要输入的文本。
  • delay_ms：delay 必填，等待时长毫秒。
  • scroll_steps：滚轮步数（可选，默认 1）。
  • to_bbox：drag_drop 必填，目标落点 bbox（取中心点作为终点）。

下面是一个（示意）工具调用结构，便于理解格式（实际由模型自动生成）： 

<tool_call>{"name":"controller","arguments":{"bbox":[100,200,300,240],"action":"left_click","description":"点击搜索框"}} </tool_call>

常见问题

  • 模型总说“看不到目标”：确认目标窗口在主屏且未被遮挡；必要时先把窗口最大化；多页内容用滚轮/搜索定位。
  • 坐标点偏：优先把目标窗口移动到主屏；检查系统缩放/DPI；适当提高归一化尺寸 X×Y。
  • 输入不生效：多数场景需要先 left_click 聚焦输入框，再 type_text；必要时配合 press_key（如 Ctrl+A 清空）。
  • 替换/保存是多步任务：让模型按“一个动作一轮”的方式推进（点击→按快捷键→输入→回车→保存）。

桌面控制器页面示意

返回总览 · 上一页：机体控制