qwen-code cua-driver Linux 后端全解析：X11 后台免焦点输入、AT-SPI 无障碍树与 Wayland 能力边界

qwen-code cua-driver Linux 后端全解析X11 后台免焦点输入、AT-SPI 无障碍树与 Wayland 能力边界【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-codecua-driver 是 qwen-code 仓库中驱动原生 GUI 应用的核心组件其 Linux 后端packages/cua-driver/rust/crates/platform-linux在不抢焦点、不激活、不移动真实指针的前提下完成点击、键入、滚动、截图与录制等全量工具面。本文以官方技能文档 LINUX.md 为骨架结合 Rust 源码逐层讲解 X11 后台输入的三条注入路径、delivery_mode后台/前台升降级阶梯、AT-SPI 会话总线自动发现机制、原生 Wayland 支持的能力边界以及一套可复用的故障排查流程。读完你将掌握在 X11/Openbox、Sway/wlroots、GNOME/Mutter、KDE/KWin 等环境下的选路原则与验证方法。一、Linux 后端的整体契约无前台no-foreground与 macOS、Windows 后端保持同一承诺Linux 后端在后台驱动 X11 应用——点击与按键被注入到目标窗口但不会将该窗口置顶、激活也不会移动真实指针。完整工具面均被支持click、type_text、滚动、press_key、screenshot、launch_app、list_apps、list_windows、get_window_state与会话录制。窗口几何控制走 EWMH 协议而非直接配置客户端set_window_frame({pid, window_id, x, y, width, height})通过_NET_MOVERESIZE_WINDOW客户端消息向窗口管理器发出请求随后在list_windows返回的几何信息上确认结果。对应实现见 platform-linux/src/x11/mod.rs发送请求后会以 40ms 间隔最多轮询 8 次list_windows只有读回的(x, y, width, height)与请求一致时才返回confirmed——这正对应SKILL.md中set_window_frame 仅在几何读回后返回 confirmed的跨平台约定。而 Wayland 没有可移植的设置其他应用顶层窗口几何协议因此该工具在 Wayland 下会拒绝执行除非未来出现由合成器持有的适配器能提供精确寻址与读回。AT-SPI无障碍树背后的机制通过 D-Bus原生访问atspi/zbus crate运行时不需要pyatspi或 GObject-introspection typelibs。这从源码可得到印证platform-linux/src/atspi/native.rs 明确记载它取代了旧的python3 -c import pyatspi; ...子进程桥接方案。二、输入如何投递三条后台路径Linux 后台输入不是单一机制而是按目标类型分派的三条路径全部在 platform-linux/src/input/ 下实现像素点击pixel click向解析出的目标窗口发送XSendEvent(ButtonPress/Release)。不置顶、不激活、不真实指针跳变。刻意不使用XTestFakeButtonEvent——那会经由当前聚焦窗口路由违背无前台契约。元素点击element click携带element_token或element_indexsnapshot_id时走 AT-SPIdo_action是 toolkit 原生、免焦点的路径。type_text优先走 AT-SPIEditableText接口免焦点可落进未聚焦窗口的 Qt6/GTK4 可编辑控件当非可编辑控件持有焦点时如电子表格单元格、终端、画布则通过 XTest 向聚焦控件合成键入终端走一条独立的免焦点 PTY 注入路径。因此后台向可编辑控件键入不需要焦点XTest 路径对应的是点哪打哪的前台场景。其中终端 PTY 注入路径的实现尤其值得关注platform-linux/src/tty.rs 通过pidfd_open(2)pidfd_getfd(2)借用终端模拟器持有的 PTY master fd直接向 slaveshell 的 stdin写入字节效果与真实键入一致——无 X 焦点切换且不受dev.tty.legacy_tiocsti影响替代了旧版TIOCSTIioctl。在默认kernel.yama.ptrace_scope1下pidfd_getfd只对调用者的自有后代即驱动自己启动的终端放行无需 root 与特殊能力对非自启终端则返回Ok(false)交给上层回退。Agent 光标是合成覆盖层展示运行正在作用的位置从不移动真实指针与 macOS/Windows 同一模型。它在点击与move_cursor时平滑滑动在键入推进焦点跨单元格时可用move_cursor让光标跟踪某个字段。三、delivery_mode后台/前台的升降级阶梯每个输入工具click、type_text、press_key、hotkey、double_click、right_click、scroll都接受可选参数delivery_mode——best-effort-background 阶梯的单次调用档位与 macOS、Windows 表面一致background默认注入时不激活、不置顶目标。X11 上走前述无焦点窃取路径AT-SPI /XSendEvent/ XInput2 MPX 指针。这是 cua-driver 的差异化能力也是正确默认值。foreground先激活目标X11 EWMH_NET_ACTIVE_WINDOW带正确的时间戳处理以对抗窗口管理器的焦点窃取防护注入然后恢复之前的活动窗口。这是后台注入未落定时的显式升级——例如 GTK 对话框按钮、或仅在聚焦时才读取输入的控件。除非目标本就处于活动状态否则会带来一次短暂的焦点交换。源码层面的印证位于 platform-linux/src/input/delivery.rsDeliveryMode::parse对任何非显式foreground大小写不敏感的值一律解析为Background保证缺省/垃圾值永远不会悄悄前置。该文件同时说明 Wayland 的语义差异Wayland 安全模型没有任意逐窗口后台寻址libei 只能注入到合成器的输入焦点因此background无法像 X11/macOS/Windows 那样瞄准特定未聚焦窗口——当没有 libei 后端时工具返回结构化background_unavailable错误代码、detail、escalation.recommended: foreground一应俱全见 delivery.rs让调用方据此升级。持久的焦点代理例外bring_to_frontbring_to_front不属于常规输入阶梯。对普通background_unavailable响应只需用delivery_mode:foreground重试被拒绝的那一个动作cua-driver 激活目标、执行动作、恢复之前的活动窗口。仅在焦点代理表面必须跨多次调用保持前台时例如远程桌面会话或重复的动作级激活导致远程表面无法接受输入时才使用bring_to_front。X11 上它使用持久的_NET_ACTIVE_WINDOW激活相当于wmctrl -a。读回与动作效果AT-SPIEditableText.insertText可在无障碍层从控件模型中读回插入值时返回effect:confirmed并附evidence:[{kind:value_readback}]。Keystroke / XSendEvent / XTest / foreground 各档若无其他可发布读回则返回effect:unverifiable——通过verify_state或多模态读取确认。动作响应使用跨平台封闭式escalation:{target, reason}形状完整行为矩阵见 SKILL.md。在标准 Wayland 合成器上Linux 特有的升级目标是foreground原始后台像素无法瞄准未聚焦窗口在 X11 上则用pixel基于快照中已有的截图通过 AT-SPIdo_action-at-point 落地的元素像素动作。四、感知get_window_state同时返回树与截图get_window_state与感知模式无关——默认在一次调用中同时返回 AT-SPI 树和截图。你同时以两者为锚并交叉校验因为树在某些表面会撒谎Electron 对setValue回声确认、虚拟化/视口外行上报虚假h:1帧所以默认总是附带一张接地截图。没有需要选择的捕获模式。性能开关include_screenshot布尔默认true传include_screenshot:false可跳过截屏、只返回树——这是元素 ax 动作前重新索引时的廉价路径。它是性能旋钮不是模态选择。capture_mode已废弃且被忽略仍被接受避免旧调用方报错但不再生效——无论传什么ax/vision/som都会同时返回树与截图。不再有 ax/vision/som 捕获选择请丢弃这套词汇。模态在动作时刻通过寻址方式选择元素 ax 动作传element_token首选或匹配的element_indexsnapshot_id对 → AT-SPIdo_action。可后台化、驱动可验证。元素 px 动作传x,y→ 像素档位直接读取get_window_state响应中已有的截图坐标。best-effort由调用方确认。get_window_state返回degraded:true空 AT-SPI 遍历即提示在 X11 上基于同一截图做元素 px 动作或在标准 Wayland 上升级到delivery_mode:foreground原始后台像素无法瞄准未聚焦窗口。五、跨平台 schema 残留Linux 视角捕获/分派/寻址参数是共享跨平台契约详见 SKILL.md 的Cross-platform parameter contract一节session、delivery_mode、capture_mode、scope、modifier、element_index/snapshot_id/element_token与 macOS、Windows 形状一致并由 CI 门禁保证三端不漂移。Linux 相关要点session现已在每个动作/光标工具上被接受早期 Linux 构建通过additionalProperties:false拒绝它当时实际仅 macOS 可用现已统一在 schema 中接受——Linux 在覆盖层可用的 X11 上为每个会话滑动独立光标。无窗口的屏幕绝对动作使用target:{kind:desktop,display_id:primary}与 macOS/Windows 一致精确窗口动作使用target:{kind:window,pid:PID,window_id:WINDOW_ID}。旧式扁平scope、pid、window_id字段仍是兼容输入但不要与target混用。六、原生应用菜单invoke_menu对已知的 GTK/Qt 应用菜单命令使用invoke_menu({pid, window_id, path:[...]})。它仅在操作期间激活精确目标每级菜单展开后重新解析带标签的 AT-SPI 菜单后代并拒绝缺失、重复、禁用或不可动作的段。它通过 AT-SPI 在 X11 与 Wayland 上均可用从不回退到坐标。注意do_action的原生确认本身不等于任务完成必须从新状态验证命令的语义效果。七、AT-SPI 需要会话总线headless / 容器 /runuser场景AT-SPI——get_window_state、元素索引点击、免焦点type_text背后的无障碍树——完全位于桌面会话的 D-Bus 上。cua-driver 通过DBUS_SESSION_BUS_ADDRESS访问它守护进程在正常桌面登录内部启动时该变量已导出一切正常。在会话外部启动时——容器入口点、无头机器、runuser/su进入桌面用户、systemdsystem单元、或运行自建临时总线的 VNC 会话——该变量未设置AT-SPI registry 遍历为空get_window_state会报告每个窗口都没有元素。qwen-cua-driver 现在在启动时自动发现会话总线与XAUTHORITY恢复机制对应若DBUS_SESSION_BUS_ADDRESS未设置则采用/run/user/uid/bus或从运行中的桌面会话进程xfce4-session、gnome-session等的/proc/pid/environ读取地址。实现位于 platform-linux/src/session_bus.rs优先探测 systemd 用户总线套接字unix:path/run/user/uid/bus否则扫描/proc中SESSION_PROCESS_COMMS列表含 xfce4-session、gnome-session-binary、mate-session、cinnamon-session、plasma_session、sway、labwc 等双向前缀匹配以容忍内核 15 字符 comm 截断从匹配进程的 environ 中解析地址。整个过程幂等OnceLock保证只跑一次、且只在变量缺失时生效。仍需满足的两个条件该会话中必须运行无障碍总线且toolkit-accessibility必须开启——cua-driver 在启动时会向会话广告一个屏幕阅读器以翻转该开关但一个完全没有 a11y 总线的会话缺少/usr/libexec/at-spi-bus-launcher无法暴露树。qwen-cua-driver doctor现在会真实探测org.a11y.Bus不只是有没有总线并告诉你两者缺了哪个。守护进程必须以桌面用户身份运行才能读取该用户的会话进程 environ 与/run/user/uid/bus套接字。以 root 运行守护进程去驱动用户会话是 Windows Session 0 隔离问题在 Linux 上的对应物。空 AT-SPI 遍历现在被如实呈现get_window_state设置degraded: truedegraded_reason而非裸elements: []调用方可以区分此窗口确实没有控件与a11y 桥没起来 / 守护进程不在会话总线上。配套的无障碍广告机制见 platform-linux/src/a11y.rsChromium/Electron 默认关闭无障碍树仅在观察到org.a11y.Status的ScreenReaderEnabled属性为真时才构建 AT-SPI 树。驱动在 GNOME/COSMIC 上只广告IsEnabled避免触发 Orca 启动在 Cinnamon 上不广告任何信号避免设置守护进程高频写循环其他桌面保留 Chromium 信号并可用CUA_DRIVER_RS_A11Y_ADVERTISE_MODEall/is_enabled_only/none显式覆盖。八、已验证模态矩阵X11 / XFCE各输入档位及其稳定的公开路由Modalitydelivery_moderoute后置条件证明元素点击element_indexbackgroundaccessibility使用verify_state仅调用成功不算确认元素 px 动作x,ybackgroundAT-SPI-at-point 命中时accessibility否则global_input使用verify_state或多模态读取像素px点击已升级foregroundglobal_input使用verify_state或多模态读取向可编辑控件type_textbackgroundaccessibility仅带value_readback证据时才confirmedtype_text非可编辑焦点background/foregroundsynthetic_events或global_input使用verify_state或多模态读取后台元素 px 动作确实能在 X11 落地对暴露 AX 的应用它走免焦点的 AT-SPIdo_action-at-point 路径x11_atspi与 macOS/Windows 的后台像素点击完全一致仅对非 AX 表面回退到 MPX 虚拟指针路径x11_pixel而该路径需要真实 Xorg /dev/uinput——在 Xvnc / 缺少 uinput 的最小容器下请升级到delivery_mode:foreground。background档的type_text对非可编辑控件依赖焦点这是唯一真正的后台限制foreground是文档化的升级路径。九、Wayland按合成器能力选择后端设置CUA_DRIVER_RS_ENABLE_WAYLAND1启用原生 Wayland 支持源码见 platform-linux/src/wayland/mod.rs任何非空/非0/非false的值都视为启用。驱动按合成器能力选择后端Sway 及其他 wlroots 合成器使用 foreign-toplevel 发现、wlr-screencopy、虚拟指针与虚拟键盘协议。GNOME/Mutter使用内置的 WinRects Shell helper 提供目标几何与激活配合 portal/libei 提供前台原始输入。KDE/KWin在可用处使用 AT-SPI 与 portal 设施目标特定的前台激活仍属实验性因此不安全的原始输入会被拒绝。可选的cua-compositor是独立的嵌套会话需显式启用用于受控自动化GNOME 与 KDE 永不会切入它。Sway 录制经 wlroots recorder 路径工作并由规范 harness runner 覆盖portal 支撑的 GNOME 录制仍是证据缺口。因此捕获与录制可用性取决于合成器、已安装 helper 与 portal 授权。标准 Wayland 没有面向任意被遮挡表面的原始输入通用客户端协议。后台 AX 动作仍可经 AT-SPI 投递当命中测试解析到可动作的 AT-SPI 控件时PX 左键点击也可投递。其他焦点绑定的后台指针与键盘形态返回精确的background_unavailable结果不会在静默丢弃后谎报成功。Wayland 原始输入请使用delivery_mode:foreground驱动在分派前通过已验证的合成器适配器激活所选目标若合成器没有可寻址目标的激活或输入后端调用会在发送输入前拒绝。仅靠重建坐标无法让原始后台 PX 在标准合成器上变得可行。十、快速排查Quick TriageLinux 上工具调用行为异常时qwen-cua-driver doctor——报告显示服务器X11/Wayland、org.a11y.Bus是否真的在会话总线上应答不只是有没有总线、发现的DBUS_SESSION_BUS_ADDRESS、以及ffmpeg可用性用于录制。其实现见 crates/cua-driver/src/doctor.rsLinux 探针按WAYLAND_DISPLAY优先于DISPLAY判断显示服务器XWayland 仍会把DISPLAY指向其暴露的 X server再以AT_SPI_BUS环境变量或gdbus introspect --session --dest org.a11y.Bus3 秒有界等待探测 AT-SPI 可达性。检查XDG_SESSION_TYPE——x11完全支持wayland需要CUA_DRIVER_RS_ENABLE_WAYLAND1启用原生后端否则回退 XWayland。空 AT-SPI 树get_window_state返回degraded:true——按可能性排序(a) 守护进程不在桌面会话总线上headless / 容器 /runuser/ root 驱动用户会话见上文AT-SPI 需要会话总线doctor 会提示DBUS_SESSION_BUS_ADDRESS unset(b) a11y 桥关闭gsettings set org.gnome.desktop.interface toolkit-accessibility true(c) GTK4 / Qt6 / Chromium 惰性填充——在一次交互或 AX 启用稳定后再重新快照。十一、禁止向量Forbidden Vectors与 macOS/Windows 同一思路——不要 shell 调用任何会把目标前置的命令wmctrl -a window/wmctrl -R window——激活 / 置顶。xdotool windowactivate wid——激活。xdotool key --window wid altTab——焦点抖动。优先使用带显式window_id的 cua-driver 工具。拿不准时询问用户。十二、各环境基线What to Expect环境已验证基线主要限制X11/OpenboxAT-SPI 树与动作、前台指针与键盘输入、窗口与桌面捕获、视频原始后台投递仍依赖 toolkit不支持的形态会拒绝Sway/wlrootsAT-SPI、原生发现、全屏与裁剪窗口 screencopy、前台输入、语义后台动作、视频原始后台指针与键盘输入仍绑定焦点GNOME/MutterAT-SPI、WinRects 几何与激活、捕获、portal/libei 前台输入需要 helper 与 portal 授权portal 视频对齐仍未完成KDE/KWinAT-SPI 与通用发现在暴露处目标特定激活与行为覆盖仍属实验性嵌套cua-compositor版本化直接逐表面输入、原生 GTK 31/31、捕获/范围 5/5、部分 Electron 覆盖完整共享矩阵仍属实验性不要据此推断标准 Wayland 支持十三、实践要点与延伸阅读无论哪个平台都要遵守核心不变式动作前快照、动作后验证get_window_state→ 动作 →verify_state完整跨平台循环、像素点击契约与失败模式见 SKILL.md会话录制见 RECORDING.md。安装后先跑qwen-cua-driver doctor确认平台与正确的入口点Linux 上守护进程必须与图形会话共享 AT-SPI 会话总线参见 README.md 的安装与验证说明。从源码探索 Linux 后端的读者建议按此顺序阅读platform-linux/src/lib.rs模块总览→ input/delivery.rsdelivery_mode 阶梯→ atspi/native.rsAT-SPI 原生走树→ session_bus.rs总线自动发现→ x11/mod.rsX11 窗口枚举与几何设置→ tty.rsPTY 注入→ wayland/mod.rsWayland 后端。跨平台契约的 CI 一致性由 schema_consistency_test.rs 类测试守护。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考