Linux 代表性桌面验证：cua-driver 在 GNOME、KDE 与真实 Xorg 上的端到端验收体系

Linux 代表性桌面验证：cua-driver 在 GNOME、KDE 与真实 Xorg 上的端到端验收体系

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua

CUA Driver 的 Linux 端到端（E2E）测试在两种桌面语境下运行：托管 CI 拥有规范化的 Xvfb/Openbox 与 headless Sway 环境，而部分"契约"——例如 WinRects 几何与激活、portal/libei 输入、真实 Xorg 的 MPX/uinput 行为、WebKitGTK/Tauri 的可访问性树——只有在真实用户桌面上才能被证明。本文以 linux-desktop-validation.md 为主体，结合 run-rust-e2e-desktop.sh、sync-vm-worktree.sh 与 action-support.md 等仓库源码，系统讲解这套"代表性桌面验证"的环境矩阵、预检门槛、源所有权模型、运行方式与证据验收标准。读完本文，你将掌握如何在 GNOME/Mutter、KDE/KWin 与真实 Xorg 桌面上复现 cua-driver 的规范 Linux 矩阵，并理解为什么"setup failure 是环境错误，而不是更小的绿色矩阵"。

为什么需要代表性桌面验证

托管 CI 提供的 Xvfb/Openbox 与 headless Sway 会话可以覆盖大部分可脚本化的窗口管理路径，但它们无法回答三类问题：

• 合成器与窗口管理器行为：Wayland 协议是"能力集"而非统一 API，Mutter 与 KWin 对激活、堆叠、焦点和 portal 输入的处理各不相同；
• 真实硬件路径：Xvfb 无法提供 MPX/uinput 后台指针路由，软件渲染无法替代/dev/dri/renderD128上的 WebKitGTK 加速合成；
• 桌面级副作用：portal 授权、AT-SPI 注册表、Secret Service、用户会话中的权限弹窗，只在登录后的真实桌面会话中才存在。

因此仓库维护了一套"代表性桌面验证"体系：只有维护者显式配置了对应环境，这些契约才会运行（见 linux-desktop-validation.md 开篇）。

验证环境矩阵与当前状态

原文档用一张表格定义了四类代表性环境，每类环境都有三列约束：必需的证据、当前状态、预检条件。

状态证据：action-support.md 中的已接受基线

各环境的"当前状态"并非空泛描述，在 action-support.md 的"Accepted baselines"中记录了带精确 source SHA 与运行号的行为基线：

• Linux/X11（268a6ab1，Run29254936043）：116/116 行，75 个交付 + 41 个精确拒绝；
• Linux/Sway（268a6ab1与64e82449）：Run29255208927通过 native 与 capture 36/36，Run29257961614通过 shared 80/80，合并为有效的 116/116 覆盖。

在"Native Linux"小节中，GNOME/Mutter 记录了一次真实 GNOME 46 Wayland 运行通过完整 GTK3 矩阵 31/31；KDE/KWin 记录了 Plasma 6 会话的 live 验证——Cua 自有的原生 KWin identity 适配器提供了受信进程内 helper、不透明 KWin 生命周期令牌、PID/几何关联、active/minimized 元数据与实时窗口令牌修剪——但原始的目标寻址键盘与指针动作被有意拒绝（portal/libei 交付受焦点绑定，激活加回读无法阻止焦点在合成器 EIS 处理前改变）。这些记录解释了表格中"行为矩阵尚未被接受"的原因：KWin 需要先把输入变更本身绑定到目标令牌/窗口上，才会启用交付。

预检门槛：run-rust-e2e-desktop.sh 的三条分支

代表性桌面验证的入口是 run-rust-e2e-desktop.sh。该脚本"在构建 fixtures 之前就拒绝错误的桌面世代"，每种环境都做了显式的环境断言：

GNOME（gnome）分支：

[[ "${XDG_SESSION_TYPE:-}" == wayland ]] || { echo "GNOME validation requires an active Wayland user session" >&2; exit 2; } [[ "${XDG_CURRENT_DESKTOP:-}" == *GNOME* ]] || { ... exit 2; } gdbus call --session --dest org.cua.WinRects \ --object-path /org/cua/WinRects --method org.cua.WinRects.GetRects >/dev/null

随后导出CUA_E2E_COMPOSITOR=gnome-mutter、CUA_E2E_INPUT_BACKENDS=atspi,libei-portal、CUA_DRIVER_RS_ENABLE_WAYLAND=1。

KDE（kde）分支：除 Wayland 会话与XDG_CURRENT_DESKTOP含 KDE 外，还解析kwin_wayland --version并要求主版本 ≥ 6：

kwin_version="$(kwin_wayland --version 2>/dev/null | sed -n 's/^kwin \([0-9][0-9]*\).*/\1/p')" [[ "${kwin_version:-0}" -ge 6 ]] || { echo "Representative KDE validation requires Plasma/KWin 6; ..." >&2; exit 2; }

这实现了原文档中"Plasma 5.27 被拒绝"的约束。随后导出CUA_E2E_COMPOSITOR=kwin、CUA_E2E_INPUT_BACKENDS=atspi,libei-portal。

Xorg（xorg）分支：要求存在DISPLAY且会话类型不是 Wayland，导出CUA_E2E_COMPOSITOR=real-xorg、CUA_E2E_INPUT_BACKENDS=atspi,xsend-event,xtest,mpx-uinput。

跨分支的 DRM 门槛：默认 harness 过滤器为electron,tauri，若过滤器中包含tauri（WebKitGTK 路径）而系统没有/dev/dri/renderD128，则直接拒绝运行：

effective_harness_filter="${CUA_E2E_HARNESS_FILTER:-electron,tauri}" if [[ ",${effective_harness_filter}," == *,tauri,* && ! -e /dev/dri/renderD128 ]]; then echo "Tauri/WebKitGTK validation requires a representative DRM render node" >&2 exit 2 fi

这正是原文档中"软件无头渲染被拒绝"的实现。脚本最后exec "${SCRIPT_DIR}/run-rust-e2e.sh" "$@"，把剩余参数（如--no-build）透传给底层 runner。

对比可参照托管 CI 的 headless 会话脚本 run-rust-e2e-wayland.sh：它用WLR_BACKENDS=headless、WLR_RENDERER=pixman启动 Sway，并显式设置WEBKIT_DISABLE_COMPOSITING_MODE=1、WEBKIT_DISABLE_DMABUF_RENDERER=1等软件渲染降级变量——这与代表性桌面"必须有真实 DRM render node"的要求形成互补分工。

源所有权：只有主机 checkout 能提交与推送

代表性桌面验证通常跑在维护者或验证 VM 上，因此仓库定义了严格的源所有权模型：主机 checkout 是唯一允许提交或推送的 checkout。同步由 sync-vm-worktree.sh 承担：

libs/cua-driver/scripts/sync-vm-worktree.sh push user@host '~/cua'

脚本支持三种模式：

• push：把主机 checkout 同步到验证 VM，是更新 Linux/Windows 验证机器的常规方式；
• pull-artifacts：把 VM 上<remote-dir>/vm-out（REMOTE_ARTIFACT_DIR可改，默认vm-out）中的日志/工件拉回主机的artifacts/cua-driver/vm/<target>/<timestamp>；
• pull-code：把 VM 上的源码改动拉回主机，必须设置ALLOW_PULL_CODE=1才能执行——因为主机是唯一提交/推送方，这个模式仅用于恢复 VM 侧的有意编辑。

几个关键约束值得注意：

• 脏工作树防护：push 前脚本用git status --porcelain检查主机工作树。若存在未提交改动且未设置ALLOW_DIRTY_SYNC=1，直接拒绝并报错；诊断性 push 会接受，但 source marker 会写成<sha>-dirty，从而变得"非 canonical"，E2E 会拒绝它；
• 凭据与构建物排除：同步会排除.git、.env/.env.local/.netrc/.npmrc/.pypirc、*.key/*.p12/*.pem、credentials/、secrets/、target/、node_modules/、.venv/、__pycache__/、dist/、artifacts/与vm-out/——避免把主机侧凭据和已拉回的 VM 证据再次送进 guest；
• 传输方式：默认rsync（SYNC_TRANSPORT可切到tar，RSYNC_SSH支持ssh -o BatchMode=yes这类完整命令串）；
• source marker：push 完成后写入.cua-e2e-source-sha。即使 VM 刻意没有.git目录，canonical 预检也会校验该标记，从而让报告仍然指向精确的主机 commit。

这套机制直接支撑了原文档的核心主张：行为验收要求"精确的 source SHA"——证据必须可回溯到某个确定 commit，而不是"当前工作树里碰巧是什么"。

运行方式与底层执行流程

启动命令必须从图形用户的 systemd user manager（或该用户会话内的等价终端）发起，因为脚本依赖真实会话的环境变量与 D-Bus：

scripts/ci/linux/run-rust-e2e-desktop.sh gnome scripts/ci/linux/run-rust-e2e-desktop.sh kde scripts/ci/linux/run-rust-e2e-desktop.sh xorg

不带参数时默认运行"完整的 canonical 矩阵"（即all套件）。CUA_E2E_INTERNAL_LANE与CUA_E2E_HARNESS_FILTER是诊断/维护控制项：前者选择shared|native|capture|all内部轨道，后者选择要构建的 harness（如electron,tauri）；它们只是过滤视角，不定义第二个 catalog。

底层 runner 的关键行为

透传到的 run-rust-e2e.sh 负责真正的矩阵执行：

• 产物布局：在artifacts/cua-driver/linux/下创建cases.jsonl（声明）、environment.jsonl（环境）、results.jsonl（结果）、summary.md（摘要）与recordings/（逐格视频）；
• 环境变量契约：CUA_TEST_REQUIRE_FIXTURES=1、CUA_E2E_FORBID_SKIPS=1（禁止跳过）、CUA_REQUIRE_GUI=1（GUI 生命周期证据失败而非静默返回）、CUA_E2E_UNRESTRICTED_GUI=1（仅 testkit 用，授权其派生的行为 daemon 执行受保护 GUI 操作，不泄漏到 SDK/运行时测试）。shared/all 且未过滤时强制CUA_E2E_EXPECTED_MIN_CELLS=80——少于 80 个行为格即失败；
• source marker 链路：若.cua-e2e-source-sha存在，读取为CUA_E2E_SOURCE_SHA，再导出为CUA_DRIVER_SOURCE_SHA注入被测 driver——这就是"报告仍识别精确主机 commit"的落点；
• portal-input 特性门：当输入后端包含libei-portal时（即 GNOME/KDE 代表桌面），所有 cua-driver 构建/测试都加--features portal-input，保证与发布版本使用同一套 RemoteDesktop/libei 适配器而非回退到 wtype；
• fixtures 构建：cargo build --release -p cua-driver后按套件构建 harness（--only electron,tauri,gtk3[,gtk4]），随后逐一检查必需 fixture 二进制是否存在；
• 环境预检：运行canonical_e2e_environment_is_ready（e2e_environment_preflight_test，--ignored精确匹配），失败即整轮终止并生成报告；
• 视频校验闭环：对每条recording.mp4用ffprobe验证可播放；检查每条视频都有对应的 typed result 行（孤儿视频判失败）；存在recording-error.txt判失败；最终视频数为 0 判失败。全部通过后由cua-e2e-report（--require-video）生成summary.md。

值得注意的是，runner 还声明"Wayland 原生会话的 GTK4 选择 fixture 是 X11-only"——当运行在无 DRM 的 headless Sway 上时，它会写一条cua-e2e-limitation-v1类型的 typed 限制记录（not_applicable）而不是伪造一个通过/失败。这与代表性桌面验证中"setup failure 是环境错误，绝不是更小的绿色矩阵"的精神一脉相承。

证据验收：什么才算"被接受"

原文档定义了行为验收的硬性门槛，这也是与普通"测试跑绿"最关键的区别：

1. typed rows：每个结果都是类型化行（声明/环境/结果三份 JSONL），不是"driver 返回成功"一句话；
2. 精确的 source SHA：通过.cua-e2e-source-sha标记锚定主机 commit；
3. 独立的 fixture 状态或拒绝证据：交付必须观察到 fixture 拥有的状态变更；拒绝必须返回精确的结构化拒绝码，并通过所有要求的桌面副作用 oracle（焦点、z-order、无输入泄漏，Windows/macOS/X11 还要求光标保持）；
4. 每个 action 的桌面 oracle：行为由外部应用/桌面状态验证，而不是由 driver 的自报成功验证（见 test-matrix.md 的 Matrix Dimensions 与 Oracle 维度）。

若某行为只有"代表性的结果"而没有 reporter 自有的逐格视频，可以记录该行为已建立，但必须标注为缺乏完整证据对等（evidence parity）。完整的托管对等还要求 reporter 提交 Markdown 摘要、截图、轨迹与逐格视频；已接受的每个行为以及任何证据对等缺口，都要记录到 action-support.md。

一个常被误解的点是：setup failure 是环境错误，绝不等于更小的绿色矩阵。当预检失败（例如 KWin 版本过低、缺少 WinRects helper、没有 DRM render node、portal 未授权）时，正确的结果是环境错误退出，而不是跳过部分行为格继续跑完、对外展示一个"缩水但全绿"的矩阵。

行为记录的两类状态语义

action-support.md 对每个单元格只承认三种状态：

• Delivered：观察到 fixture 拥有的状态变更；
• Refused：精确的结构化拒绝码 + 全部要求的桌面副作用 oracle 通过（拒绝在契约要求交付的单元格上算失败）；
• Gap：未支持或尚未证明——"缺少某一行从来不是该动作不可能的证据"。

维护规则同样严格：只有 typed row 增删/契约变更且经验证运行支持时才能更新该文档；当 OS API 报告成功却无法回读效果时，宁可保留可见的 gap，也不要在生产代码里捏造 fixture 特定的拒绝。

代表性环境的配套组件

为了满足各环境的预检，仓库内还有两个配套组件，理解它们能帮助排查"预检为什么拒绝"：

• GNOME WinRects helper（wayland-helper/README.md）：一个 GNOME Shell 扩展，在会话总线上暴露org.cua.WinRects，提供GetVersion、GetRects（每窗口帧几何与 surface-buffer 原点）、Activate(id)、Capture()、MoveCursor/ClickPulse/HideCursor与SetCursorState。它运行在 shell 特权上下文，因此不需要xdg-desktop-portal 授权。安装后需注销/登录一次（GNOME 仅在会话启动时加载扩展），然后用gnome-extensions info winrects@cua确认State: ACTIVE。预检中gdbus调用GetRects失败即拒绝——这正对应原文档表格里 GNOME 的"启用的 WinRects helper"预检；
• KWin target helper（kwin-target-helper/README.md）：可选的 KDE Plasma/KWin 6 Wayland 集成，需针对用户已安装的 KWin/Qt/KF6 开发文件构建（CMake ≥ 3.21），以 effect plugin 方式装入kwin/effects/plugins/cua_kwin_target_helper.so，并通过qdbus6 org.kde.KWin /Effects loadEffect cua_kwin_target_helper加载。它只读地暴露org.cua.KWinTarget的GetVersion与GetWindows（稳定不透明令牌、PID、几何、active/minimized、堆叠顺序），不提供激活或输入变更方法——这与 action-support.md 中"KWin raw 目标寻址输入被有意拒绝"的现状直接对应。

从托管 CI 到代表性桌面的完整验证阶梯

综合来看，cua-driver 的 Linux 验证是一条分层阶梯，代表性桌面验证位于最外层：

1. 单元与确定性协议测试：不依赖桌面（见 test-matrix.md）；
2. 托管 CI 的 Xvfb/Openbox 与 headless Sway：覆盖 Electron/Tauri/GTK3 的共享行为矩阵、capture 契约、desktop scope（run-rust-e2e.sh 与 run-rust-e2e-wayland.sh）；
3. 代表性桌面：GNOME/Mutter（WinRects 几何/激活、portal/libei 前台输入、stage 捕获）、KDE/KWin（identity 适配器与 Plasma 6 会话验证）、真实 Xorg（MPX/uinput 后台指针）、带 DRM render node 的 Tauri/WebKitGTK 可访问性树——只有这些环境能证明"托管 CI 证明不了"的桌面级契约。

真实 Xorg 的 MPX/uinput 路径目前标记为"尚未验证"，但其聚焦复现方法已写入 linux-mpx-recovery.md：在带 libinput、可读写/dev/uinput、xinput、Python GTK3 绑定与 session bus 的一次性真实 Xorg 桌面上，构建cua-driver后运行libs/cua-driver/tests/linux-mpx-recovery.py（--driver、--output、--source-sha参数），harness 会记录原生快照、fixture 事件、XInput 清单与最终proof.json，覆盖正常输入、干净退出、SIGTERM/SIGKILL、重启恢复、暂停的 live peer 保持与既有无主设备保持；随后再在最终候选上单独运行 canonical Linux harness。这正是"代表性桌面验证补足托管 CI 能力边界"的具体写照。

小结

Linux 代表性桌面验证是 cua-driver 在"headless 可脚本化"与"真实桌面契约"之间划出的一条严谨边界。它通过 run-rust-e2e-desktop.sh 的三分支预检（Wayland 会话 +XDG_CURRENT_DESKTOP+ WinRects/KWin 版本 + DRM render node）保证只在实际有能力的桌面上运行对应契约；通过 sync-vm-worktree.sh 的源所有权模型与.cua-e2e-source-sha标记让每份证据锚定精确 commit；再以 typed rows、独立 oracles、逐格视频与 action-support.md 账本构成"缺一不可"的验收闭环。对维护者与贡献者而言，这套体系的启示很明确：环境不满足就明确失败、证据不完整就标注 gap、契约未证明就保留精确拒绝——环境错误绝不缩水成绿色矩阵，未证实的交付绝不冒充已接受的行为。

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua