QCU 2.0.0：补齐 Windows、Linux 与 GNOME Wayland

QCU 2.0.0：补齐 Windows、Linux 与 GNOME Wayland

最近，我把 QCU 的一轮跨平台更新整理到了 2.0.0：Windows 的入口兼容、UIA 控件操作、原生窗口截图和鼠标键盘后备，Linux 的 AT-SPI2 与 X11 通道，以及 GNOME Wayland 的原生截图和输入，都已经有了对应实现与测试记录。

这轮完善沿用了 QCU 的核心原则：优先读取结构化控件，使用明确的目标引用执行操作，再读回结果；需要原生输入或截图时，再显式启用对应通道。 常驻进程、精简观察、缓存查询、批量执行这些快速特性，也继续保留。

项目仓库：ergou-yu/quick-computer-use。

本文按 2.0.0 整理功能。这个版本号承接已经验证的 1.11.0 功能基线，本次版本整理没有新增运行时行为或修改动作契约。下文的跨平台功能测试和性能数据保留原始版本、日期与测量口径，方便核验。

一、QCU 的操作机制：先拿到控件，再执行动作

QCU，全称 Quick Computer Use，是给 AI Agent 使用的计算机操作 skill 和配套控制层。它把网页和桌面应用里的按钮、输入框、复选框、列表项等对象整理成结构化信息，让 Agent 根据角色、名称、值和状态定位目标。

在支持的界面上，典型流程是：

选择浏览器页面或应用窗口
    → observe：读取控件及其 ref
    → act：填写、点击、勾选或选择
    → verify：读回值、状态或结果文本

网页主要通过无障碍信息、DOM 和 CDP 操作；桌面分别对接 macOS AX、Windows UI Automation、Linux AT-SPI2。一次观察返回的 ref 是控件引用，和目标、后端生命周期、观察代次一起绑定。

例如，填写一个中文输入框时，QCU 可以直接调用控件的文本接口，然后读回完整字符串。提交表单时，可以在点击后检查结果文本是否变成 Saved 1。在这些路径上，不需要每一步先截图，再让视觉模型识别按钮位置。

截图仍然有价值：检查界面外观、保存证据，或为显式坐标操作提供依据。2.0.0 完善了这些后备能力，同时保持普通语义操作独立运行。项目目前没有实现覆盖任意图标、模板和界面的通用 OCR/VLM 定位系统；自绘界面能做到什么，需要结合目标本身验证。

二、从 Windows 到 Wayland，这轮具体补了什么

近期更新分为四步：

阶段	主要完善	对实际使用的影响
1.9.1：Windows 兼容	PowerShell/CMD 入口、UTF-8 JSON 管道、Win32 进程与端口检查	Windows 下可以稳定传递 JSON、中文和引号，复用常驻进程
1.9.2：Windows 原生后备	绑定 HWND 的 PrintWindow/GDI 截图，鼠标、键盘消息输入	UIA 之外增加明确的原生操作入口，截图和动作继续绑定同一窗口
1.10.0：Linux	AT-SPI2 控件操作，X11 截图与 XTEST 输入	Linux 桌面获得结构化观察、语义操作及 X11 后备
1.11.0 → 2.0.0 整理	GNOME 46/50 Wayland 原生桥接，统一版本与说明	Wayland 下增加窗口截图和虚拟键鼠输入，保留原有语义路径

Windows：除了能运行，还要能正确控制窗口

Windows 默认使用 UIA 暴露的 Patterns 完成点击、赋值、勾选和选择。原生后备使用已绑定的 HWND：截图返回 PNG、窗口身份、物理像素原点与尺寸；鼠标支持点击、双击、右键、悬停、滚轮和拖动，键盘支持已实现的命名按键与文字输入。

入口也做了适配。PowerShell 5.1 可以通过 act -、batch - 的标准输入传 JSON，减少引号和中文编码问题；源码入口优先使用匹配的 pythonw，避免弹出控制台影响目标窗口焦点。进程存活和 CDP 端口归属通过 Win32 API 查询，减少启动外部命令的开销。

这里有一个必须说明的区别：本轮真机验证通过的默认原生输入是 HWND 消息通道。 另一个显式可选的 SendInput 通道，曾在测试机上返回接受事件，但没有观察到预期界面结果，因此仍记为结果未知，不能写成所有物理输入都已验证成功。

Linux：语义操作、X11 和 Wayland 各有明确入口

Linux 的日常控件操作通过 AT-SPI2 完成，包括读取控件、填写文本、勾选、选择以及可用的控件动作。后端运行在常驻 worker 中，普通语义操作无需加载 X11 或 Wayland 原生适配器。

X11 后备会把 AT-SPI 目标关联到唯一的客户端窗口，使用窗口截图和 XTEST 输入。GNOME Wayland 则通过随包提供、需要用户显式安装并启用的扩展，与 GNOME Shell/Mutter 建立常驻 D-Bus 连接，获取目标窗口截图并使用虚拟输入设备。

Wayland 的一个实际难点是坐标：应用提供的 SCREEN 坐标不能直接假定为可靠的全局位置。QCU 的 GNOME 原生引用会读取窗口内的实时控件位置，再通过 Mutter 的窗口信息换算；截图也返回像素尺寸、逻辑坐标原点和缩放比例。窗口移动之后，需要更新这些信息。

当前宣布支持的原生 Wayland 环境是 GNOME 46 与 GNOME 50。KDE、Sway、Hyprland 等环境还没有对应原生适配器；其中应用暴露出来的 AT-SPI 语义能力，仍可按实际情况使用。

当前功能覆盖

场景	主要路径	使用前提或边界
网页	无障碍信息、DOM/CDP、ref 操作、条件验证、batch	使用明确的页面目标；QCU 自有浏览器 profile 不继承用户已登录的标签页
Electron/CEF	显式 desktop_cdp 桥	目标应用需要提供可连接的调试端点，并准确绑定对应页面
自有 WKWebView 应用	desktop_jsbridge	应用所有者嵌入桥接代码后使用
macOS 桌面	desktop_ax	需要对应系统权限；本轮没有重新完成 macOS 真机测试
Windows 桌面	desktop_uia，按需 HWND 截图与输入	依赖控件 provider；安全桌面等场景不在支持范围内
Linux X11	AT-SPI2，按需 X11/XTEST	需要桌面会话、系统 GI/AT-SPI 和相应依赖
GNOME Wayland	AT-SPI2，按需 GNOME 原生桥	GNOME 46/50，原生能力需显式启用扩展

这些入口的共同目标，是保留用户选择的应用、窗口或页面。目标缺失或匹配不唯一时，QCU 会返回诊断信息。

三、补齐后备通道，怎样保留快速特性

QCU 的速度主要来自减少控制过程中的重复工作。

常驻 daemon 和 worker 复用连接与状态。 浏览器、桌面后端和 GNOME D-Bus 连接可以在会话内继续使用；GNOME 虚拟键鼠首次绑定时等待设备就绪，后续复用，不为每个输入事件重新启动子进程。

精简观察和缓存查询减少重复读取。 --compact 压缩返回内容，find、inspect 可以查询已经得到的观察结果。缓存用于定位线索，引用失效后仍需重新观察。

batch 减少跨进程往返。 当前批量接口允许 1---32 个动作，主要组合是若干次填写，再接一个最终动作；也可以在结束后返回一次精简观察。遇到失败或结果未知会停止。提交按钮应提供明确的后置条件，保证批量执行的终点可验证。

语义操作和原生后备按需加载。 普通控件填写、点击不会因为增加了截图功能，就被迫增加一次截图、OCR 或固定动作等待。等待由条件和限时轮询控制；操作仍可能等待应用更新或后端响应，不能据此理解为所有动作都没有等待。

对 Agent 来说，这些设计减少了重复观察、重复传输和命令往返。最终任务耗时还包括模型推理、应用响应、网络和验证，具体收益要按场景测量。

四、测试到底验证到了哪一层

跨平台原生流程主要完成于 2026 年 10 月 15 日 ；版本调整后，又在 10 月 16 日完成了 2.0.0 的本地 Windows 回归。Windows 原生流程在实际交互桌面上执行；Linux 流程在真实桌面组件构成的虚拟环境中执行。两者需要分开理解。

测试项目	环境与结果	证据范围
Linux 完整回归，1.11.0	783 passed、10 skipped，27.21 秒	回归套件，包含多种测试类型；平台流程另列
Windows 完整回归，2.0.0，10 月 16 日	792 passed、1 skipped，60.15 秒	包含真实 Chromium/CDP 及 portable contract/mock；不等于 792 个真机界面场景
GNOME 46 Wayland	Ubuntu 24.04、GNOME 46.2、Python 3.12.3；29 条记录命令，完整流程通过	实际 Shell/Mutter、GTK3、AT-SPI2 的 headless 集成
GNOME 50 Wayland	Ubuntu 26.04、GNOME 50.1、Python 3.14.4；29 条记录命令，完整流程通过	同上；完整成功流程使用下文说明的临时桌面设置
GNOME 46 容器对照	Ubuntu 24.04；29 条记录命令，完整流程通过	补充环境对照
X11 回归	GTK、Xvfb、Openbox；25 条记录命令，完整流程通过	实际 X11 虚拟桌面流程
GNOME JS 故障边界	12 项通过	mock host，单独计数

Windows 1.9.2 的原生真机记录还包括：26 条 CLI 命令的原生流程，以及原有 UIA 的 6 项直接检查、16 条 CLI 命令回归。测试环境为 Windows 10 build 19045、Python 3.12，使用一次性 WinForms 窗口和独立 Chromium profile。

2.0.0 的版本检查确认 Python、PowerShell 和 CMD 入口均报告 qcu 2.0.0，项目声明、锁文件与 wheel 元数据一致，GNOME 扩展资源包含在 wheel 内，skill 格式校验通过。Linux 和 GNOME 的功能、性能证据沿用 1.11.0 原始记录。

这些命令数包含预期拒绝、诊断和清理。比如旧引用被拒绝，本身就是符合预期的结果；没有单独设置后置条件的 Ctrl+A、End，只能记录已发送、结果未知。不能把命令数直接当成业务成功次数，也不能把两个平台的回归数量相加后当成独立功能数。

GNOME 测试中 DISPLAY 未设置，GTK 使用 Wayland，合成器禁用 XWayland。实际经过了 GNOME Shell、Mutter、D-Bus、AT-SPI 和应用进程，不过它仍是虚拟桌面集成测试，尚未完成物理 Linux 桌面验证。

完整记录见项目测试报告、GNOME 三环境运行和Linux/X11 回归运行。

实际跑出来的效果

GTK 测试从读取控件开始，把 Linux 中文 🚀 写入输入框，并通过 AT-SPI 读回确认；随后完成勾选和列表选择。batch 一次填写两个字段并点击保存，检查结果文本变为 Saved 1。

显式启用原生操作后，测试继续完成保存按钮点击、F6、悬停、右键、双击、滚轮和拖动，并检查对应结果。实际 GNOME 50 截图中能看到 Batch 中文 追加🚀、上海、勾选状态、被选中的 Item，以及 Saved 2 等界面状态，和结构化读回结果对应。

测试还移动了窗口，重新检查截图坐标原点与后续原生引用操作；停用 GNOME 扩展后，原生请求被拒绝，AT-SPI 语义填写继续成功。重新启用扩展后，旧原生实例绑定也会失效，需要重新建立。

这说明，在这组标准 GTK 控件和受控环境中，语义操作、原生输入、截图和结果验证能够衔接起来。证据覆盖的是这些明确场景，复杂业务软件的覆盖程度还需要继续扩展。

五、速度数据：区分任务总耗时和后端耗时

1. 六字段网页表单：batch 的收益已经有量化结果

Windows 1.9.2 使用同一个六字段网页表单，分别测试静态页面和持续联网页面。每个场景、每种模式各跑 3 轮，共 12 个任务成功。统计范围为观察、填写、提交和验证的 CLI 总耗时，排除导航、冷启动和模型推理。

场景	QCU 逐条调用中位数	QCU batch 中位数	中位耗时比	CLI 调用数
静态网页	3858 ms	1231 ms	约 3.14×	9 → 3
持续联网页面	3574 ms	3091 ms	约 1.16×	9 → 3

静态页面里，减少调用往返的收益比较明显，整段操作从约 3.86 秒降到约 1.23 秒。静态页面的输出字节中位数也从 47,991 降到 17,895，减少约 63%。

持续联网页面上的改善小得多：两轮 batch 的点击/验证阶段出现约 1.9 秒等待，具体原因尚未确定。原始记录保留了这部分抖动，因此不能只取最快一次来描述效果。

3.14× 是 QCU 内部逐条调用与 batch 的小样本对比。 本轮没有与另一套常规 computer use 在相同模型、机器和任务下进行完整对照，不能写成"QCU 普遍比其他 computer use 快 3 倍"。

2. GNOME Wayland：后端动作进入几十毫秒量级

下面是 1.11.0 最终虚拟桌面流程中的单次样本，单位均为毫秒：

操作	GNOME 46 后端耗时	GNOME 50 后端耗时
语义 fill，含读回	28.06	22.74
toggle，含状态验证	8.57	17.93
select，含状态验证	6.24	8.97
batch：两次填写、一次点击及观察	66.78	50.09
原生点击，含结果读回	35.89	58.74
原生 F6，含结果读回	32.88	25.91
原生拖动，含结果读回	24.83	19.86
两次目标窗口 PNG 截图	41.20 / 24.62	39.11 / 20.07

后端耗时不包含完整 CLI 进程成本。上表 batch 的完整 CLI 耗时，GNOME 46 为 172.95 ms ，GNOME 50 为 148.46 ms；语义 fill 的完整 CLI 耗时则分别为 132.78 ms、120.78 ms。模型推理仍然不在这些数字里。

这组数据说明，在本次标准控件场景中，常驻后端能够以较低开销完成动作和读回，新增 Wayland 后备也没有要求普通填写经过截图流程。它是小样本结果，尚不能推导复杂应用的 P95 延迟、长任务成功率，或不同桌面之间的普遍性能排名。

对应原始 JSON、PNG 和日志可从 GNOME 46 测试产物、GNOME 50 测试产物核验；Actions 产物受保留期限和访问权限限制。

六、完善程度，也体现在失败时能说明发生了什么

QCU 分开报告输入派发状态 dispatch_state 和结果状态 outcome。API 接受了请求，只能说明到了某个派发阶段；指定的文本、值或选中状态满足条件，才会得到 outcome: verified。

这在批量提交时尤其重要。填写两项以后点击保存，如果结果没有确认，batch 会停止，避免继续执行依赖保存成功的后续动作。已经发送或发送情况不确定的输入，也不会自动换一个通道重发。

引用和目标绑定同样如此。重新观察、切换目标或后端重启后，旧 ref 会失效；QCU 不会把它转换成之前缓存的坐标继续点击。原生输入还会检查前台、焦点、遮挡和当前几何信息，GNOME 桥也会检查 Shell 状态与窗口身份。

这些机制带来的实际效果，是更容易区分"目标没找到""动作没有发送""动作发送了但结果不确定"和"目标状态已确认"。Agent 可以据此决定重新观察、补充验证或停止，减少把未确认的结果继续传递下去。

• 项目仓库
• 安装说明
• Linux / GNOME 配置与限制
• API 与结果验证
• 测试报告与复跑入口

QCU 2.0.0 把结构化操作扩展到了更多桌面环境，也让截图、原生输入和结果验证之间的关系更清楚了。接下来值得继续投入的是物理 Linux 桌面、多显示器与缩放组合、更多实际应用，以及相同条件下更大样本的端到端对比。这些验证会决定它能在哪些任务上稳定节省时间，也会让后续的效果描述更有依据。