QCU 最新修复与实测：Windows 输入保护、图标定位与 Linux 桌面验证
这一轮 QCU 更新，处理了几类直接影响桌面操作可靠性的问题：输入部分发送失败后的按键清理、用户正在按键时的保护、中文 Windows 的文件编码，以及没有可访问控件的画布图标定位。
新增能力仍然沿用 QCU 的基本设计：普通操作优先通过结构化控件完成，需要图像定位时才启用后备。语义操作、缓存、compact 输出、驻留进程和 batch 都保留了下来。
项目仓库：ergou-yu/quick-computer-use
本文记录的是 2026 年 10 月 26 日的修复与测试，对应main上的提交8bbaed7。这些改动已合入仓库，CHANGELOG 记为Unreleased；现有发行标签仍为v2.0.1。
快速路径继续保留，截图只在需要时介入
QCU 会优先使用目标应用已经提供的信息和操作接口。浏览器主要使用 DOM 与可访问性信息；Windows 使用 UIA；Linux 使用 AT-SPI；macOS 使用 AX。能够拿到有效控件引用时，填写、点击和状态读取可以直接围绕控件进行。
这使普通表单操作可以省去反复截图、从图片中找按钮、再把位置换算成鼠标坐标的步骤。驻留进程减少重复初始化，缓存和 compact 输出减少重复读取与输出，batch 则把已知的多个操作放进一次受约束的调用中。
本轮新增的图标匹配是显式启用的可选后备。普通语义操作不会因此增加截图，也不会加载 OpenCV 或 NumPy。需要原生坐标输入时，也不必先经过图像识别。
Windows：修复输入失败后的清理行为
这次修复了一个可以明确定位的错误：当 SendInput 只接受了部分事件时，旧逻辑可能向尚未发送的键发送松开事件。
例如，一次Ctrl+A操作包含 Ctrl 按下、A 按下、A 松开、Ctrl 松开。如果系统只接受了第一个事件，清理时应当松开 Ctrl。此时发送 A 的松开事件没有必要，还可能干扰其他输入。
现在，QCU 根据已接受的事件前缀，只清理其中仍未配对松开的键和按钮。已经完成按下、松开的事件对不再重复清理，业务输入也不会被重放。
另一个补充是检查目标按键是否正被用户按住。用户已经按着某个键时，QCU 会在发送自己的按键事件前拒绝操作，避免自己的松开事件影响用户输入。原有的前台窗口、焦点、遮挡和目标身份检查继续保留。
这些修改修复了输入保护和失败清理中的确定问题，但SendInput 的间歇丢键根因尚未解决，后文会单独说明。
中文 Windows：明确使用 UTF-8
本轮还修复了 CLI 读取 features JSON 文件时依赖系统默认编码的问题，并为相关测试中的源码、配置和子进程输出读取明确指定 UTF-8。
此前，在默认使用中文代码页的 Windows 环境里，部分测试可能因文件解码错误失败，进而影响结果判断。修复后，完整 Windows 回归无需额外设置PYTHONUTF8环境变量即可通过。
这一项针对实际文件和测试读取路径进行了修改，没有要求用户修改系统全局代码页。
画布图标：增加按需加载的本地模板定位
有些应用会把图标直接画在面板或画布里。可访问性树能看到面板，却没有单独的图标控件。这轮新增的本地 PNG 模板匹配，主要用于这类已知图案。
使用时，先观察并绑定目标应用或页面，再从该目标截图中准备一张带有独特细节的不透明 PNG 裁剪图。显式选择grounding:"template"后，QCU 会在目标截图中寻找匹配位置。
它的处理顺序是：
- 截取当前绑定目标，查找模板候选。
- 检查匹配分数和候选数量，拒绝低分或有歧义的结果。
- 再次截取同一目标，确认匹配矩形、坐标原点和缩放没有变化。
- 通过原有后端执行操作，并根据应用文本或值检查结果。
默认匹配阈值为 0.94；多个候选达到阈值，或其他候选与最佳分数过于接近时，操作会被拒绝。这个分数是图像相关性指标，不能解释为操作成功的概率。
下面是一个动作示例。假设目标已经绑定，保存图标的模板位于指定路径，保存成功后应用会显示Saved：
{"type":"click","params":{"grounding":"template","template_path":"C:/temp/save-icon.png","verify":{"kind":"text","equals":"Saved","timeout_ms":1500}}}将动作交给qcu act - --layer screenshot_fallback，并安装可选的vision依赖即可使用。从当前源码安装时，可以运行python -m pip install -e ".[vision]"。
实际效果如何验证
Windows 测试使用了一个真实 WinForms 窗口，在面板上绘制图案，没有为图案创建独立的 UIA 子控件。QCU 通过模板找到图案并点击后，应用中的计数正确增加。
随后，测试在同一窗口里绘制了第二个相同图案。此时 QCU 在发送点击前返回歧义错误，没有随意选择其中一个。Linux GTK 的虚拟桌面测试也执行了对应场景。
因此，本轮验证覆盖了“定位后确实产生应用结果”和“重复目标出现时正确拒绝”两种情况。模板匹配适合外观相对稳定的已知图案；主题、缩放、悬停效果或图案本身变化，仍可能导致定位失败。它也没有赋予 QCU 理解任意图标含义的能力。
GNOME：兼容带透明圆角的窗口截图
跨平台测试还找到了一个 Windows 测试中没有暴露的问题：GNOME 窗口截图可能包含透明的圆角或边框。最初的模板实现把这类截图整体拒绝了。
修复后，QCU 允许截图保留透明边缘，但会排除任何碰到透明像素的候选矩形。这样既能定位窗口内部可见的图案，也不会把透明区域里不可见的 RGB 数据当成可点击目标。不透明模板的要求仍然保留。
更新后的图标流程已经在 GNOME 46、47、48、49、50 的虚拟桌面中通过验证。既有的热角处理、目标绑定、原生截图和输入检查也继续运行。GNOME 50 还验证了虚拟双显示器下，窗口移动到第二屏后的原生 ref 点击和目标截图。
本轮测试数据
| 验证项目 | 结果 | 测试范围 |
|---|---|---|
| Windows 完整回归 | 821 通过，1 跳过；65.35 秒 | 含真实 Chromium/CDP 集成，以及 mock 和跨平台契约测试 |
| Linux 完整回归 | 812 通过，10 跳过；21.14 秒 | Ubuntu CI，跳过不可运行的平台相关项 |
| Windows 真机最终原生流程 | 77 条 CLI 记录，40 项物理输入结果检查通过 | 10 轮按键、组合键、中文/Emoji 和鼠标点击检查 |
| Windows 画布图标 | 通过 | 点击后的计数回读，以及重复图标拒绝 |
| Linux X11 原生流程 | 通过，27 条 CLI 记录 | GTK、AT-SPI、XTEST、截图与图标后备 |
| GNOME Wayland | 46–50 全部通过，每环境 31 条 CLI 记录 | 五个 Ubuntu 容器，加一个 GNOME 46 宿主虚拟会话 |
| GNOME 50 双显示器 | 通过 | 虚拟双屏中的窗口移动、原生 ref 点击和截图 |
Windows 的 40 项物理输入检查，每轮分别确认 F7、Ctrl+F8、中文与 Emoji 文本值、鼠标点击计数。每轮使用新的计数或文本结果，避免同一个旧标签造成假通过。
表中的 CLI 记录包含预期拒绝和会话清理，不能当作相互独立的成功任务数。两套回归也包含重复的公共测试，不应直接相加后宣传成独立能力数量。Linux 本轮采用虚拟桌面方案，没有把它计为物理 Linux 电脑验证。
对应提交在main上的两组公开 CI 均已通过：Linux AT-SPI/X11、GNOME Wayland。
batch 的速度收益有多大
为了检查快速路径的实际表现，本轮在同一台 Windows 电脑、同一份代码上，串行测试了分步模式和 batch 模式。
每种模式分别运行静态页面 15 轮、持续后台请求页面 15 轮。每轮填写六个字段并保存，再检查全部字段值和结果文本。两种模式共60 个表单流程全部通过。
| 页面场景 | 分步模式中位耗时 | batch 中位耗时 | 每轮 CLI 调用 | batch 耗时下降 |
|---|---|---|---|---|
| 静态页面 | 2808.41 ms | 1139.38 ms | 9 → 3 | 59.43% |
| 持续后台请求 | 2783.00 ms | 1135.89 ms | 9 → 3 | 59.18% |
这组测试里，分步模式的耗时约为 batch 的2.45–2.46 倍。batch 输出字节数的中位数还减少了约62.7%；这里统计的是字节数，没有将其换算成模型 token 节省比例。
时间统计包含 CLI、进程间通信、浏览器操作、结果验证和前后读取，导航准备另计，也不包含模型推理或用户交互。它说明了当前 QCU 内部两种调用方式的差异，不能据此得出 QCU 对所有 computer-use 产品都有相同速度优势的结论。
对已经知道控件和操作顺序的表单任务，batch 可以减少重复调用，同时继续检查最终结果。需要临场判断、界面持续变化或控件无法访问的任务，实际收益还要按场景测量。
仍然存在的问题
最需要继续排查的是SendInput 间歇失效。
本轮早期严格测试中，F7 曾出现这样的情况：SendInput 返回接受了两个事件，低层键盘钩子也看到了事件，后续低层钩子没有报告拦截，但应用没有对应的按键消息。这些失败记录已保留。
绕过 CLI 和驻留进程的直接原生探针也曾复现问题。另一个 C# 同线程探针和后续交替对照则成功；加入WM_NULL检查的组与未加入的组，在交替对照中都通过。因此，现有证据还不足以确认根因，也没有把更改扫描码、增加固定等待或WM_NULL宣称为修复。
最终真机流程连续 10 轮、40 项结果检查通过，但这些成功不能抹去早期失败。当前仍然需要独立的结果回读；结果未知时，不自动重试或切换通道，避免一次未确认的操作被重复执行。
其他覆盖边界也需要保留：物理 Linux、物理混合 DPI、当前 macOS 硬件及特殊键盘布局的验证仍有限；KDE、Sway、Hyprland 的原生 Wayland 后备尚未实现；通用 VLM 定位、受保护桌面和任意游戏输入也不在本次新增能力之内。
后续排查的重点，是把间歇丢键变成稳定、可归因的复现案例，并补齐尚未覆盖的桌面和硬件环境。本轮已合入的输入保护、UTF-8 修复和可选图标定位，都可以在仓库的当前main中查看。
