无障碍树+屏幕像素双通道感知：让手机GUI Agent精准点击

做手机 GUI Agent 最难的从来不是“把点击发出去”，而是“让 Agent 知道自己该点哪里”。过去一年我在折腾这件事时，把无障碍树和屏幕投屏像素两条通道都试了个遍，最终沉淀出一套以无障碍树为主、投屏像素兜底的感知方案。这篇文章就是完整复盘，包括为什么这么选、每一步怎么落地，以及那些文档里不会告诉你的坑。

先说结论：如果你也准备做手机端 GUI Agent，无障碍树绝对是性价比最高的感知主通道，它结构化、低成本、易解释；但树不是万能的，遇到自定义绘制控件、WebView、动效刷新混乱的时候，树会瞎报、漏报甚至直接超时。这时候屏幕像素流就成了最可靠的兜底——虽然它慢、笨、语义弱，但它永远贴近“用户真正看到的东西”。两条通道配合起来，Agent 的感知才谈得上可信。

1. 为什么是“树+像素”，而不是二选一

1.1 只靠无障碍树踩过的坑

我最早做的版本是纯无障碍树方案：通过系统无障碍服务拿到当前页面的节点快照，把文本、坐标、可点击属性整理成一个结构化的界面描述，然后交给决策模型去选目标节点。听起来很顺，原生 Android 应用也确实跑得不错，但一到真实场景就露馅了。

第一类是“树里根本没有节点”。小程序框架、Flutter 的某些渲染引擎、游戏引擎、以及部分自定义重度绘制的 View，要么不暴露无障碍节点，要么暴露出来的节点缺少文本和语义信息。我印象很深的一次，某自绘图表页面的整块内容只有一个根节点，文本全是 null，坐标是整个屏幕，决策模型看到这样的数据基本等同于盲操作。

第二类是“树有节点但内容是错的”。列表快速滑动时，Android 的虚拟化机制经常让树里的文本和屏幕实际显示不一致。列表项还没来得及绑定新数据，树里还是上一个位置的旧文案，但截图里已经滚到下一屏了。Agent 信了树的结果，按旧文案去匹配意图，匹配率直接崩。

第三类是性能问题。纯无障碍树的 Dump 动作非常昂贵，最坏情况下一次要 500 毫秒到 1 秒。对响应式决策来说，这个延迟已经大到没法忽略，尤其是连续多步操作时，界面状态早就在变化，树引用的节点可能已经销毁或移出屏幕。用一个过期的树去做决策，等于用上周的导航地图开今天的车。

这三类问题单靠树通道是无解的。要么接受结构信息的残缺，要么想别的办法补充真实视觉状态。

1.2 只靠像素感知的更残酷现实

于是我把主通道换成了投屏像素方案：用 scrcpy 或 minicap 拿到实时屏幕帧，对画面做目标检测和 OCR 识别，反推出可交互控件的位置。思路没错，但代价也非常直观。

逐帧跑视觉模型对算力的消耗是树方案的几十倍不止。普通 OCR 加目标检测的组合，在手机上做一次完整的界面理解轻松超过两秒，这在交互 Agent 里基本不可用。而且像素坐标映射天然带误差，物理分辨率到显示分辨率的换算、设备边框、投屏裁切、输入法弹窗引起的尺寸变化，每一样都能让你的点击偏差几个像素。细小按钮和紧凑列表里的缝隙更是重灾区。

更麻烦的是语义识别质量。OCR 只解决“文字是什么”，不解决“文字能不能点”。一张截图里密密麻麻的文本，哪些是可点击入口，哪些是纯展示说明，纯视觉方案很难判断准确。我试过用视觉模型硬训可点击区域识别，小规模标注还行，一换应用类型，泛化能力立刻下降，维护了个寂寞。

所以我的结论很明确：树和像素各有不可替代的价值。树提供准确的结构和语义，像素提供真实的视觉快照。双通道组合不是锦上添花，而是刚需。

2. 无障碍树通道：从主通道到可信通道

2.1 获取树的几种路径与我的选择

Android 阵营获取无障碍树的常用路径有三条：自己写 AccessibilityService、调三方库的 Dump 接口、用 ADB 命令拉取。我最终采用的是以uiautomator2的 Dump 接口为基础、再包一层自己写的加工管线的路子。理由不复杂：自己写 AccessibilityService 权限太敏感且要处理大量事件回调，适合做系统级自动化框架，不适合快速迭代的 Agent 项目；ADB 命令方式延迟太高；三方库的 Dump 接口已经在真实设备上被广泛验证过，稳定性有保障。

拿到底层 XML 之后，我先做三件事：解析、过滤、标准化。解析自然不必说，过滤是把不可见节点、零尺寸节点、纯布局容器节点全部剔除。标准化则是把每个节点抽成一个统一结构体，核心字段包括node_id、type、text、content_desc、bounds、clickable、visible、enabled、child_count。

这里有个容易忽略的细节：优先把content-desc作为语义文本的最大来源，它常常比text更干净；text兜底；两者都没有的叶子节点，再用可见子节点的文本做拼接。这样处理的好处是，很多图片按钮和图标类控件的语义一下就补全了。

2.2 把原始节点加工成 Agent 可用状态

原始树并不能直接交给 Agent 决策，因为信息太杂、太底层、太容易被噪音干扰。我做了三层加工。

第一层是坐标归一化。原始bounds是基于设备物理分辨率的，但同一套 Agent 要跑在不同分辨率的设备上，所以我统一把坐标缩放到 0-1000 的相对坐标系，决策模型只认这个相对坐标。投放执行时再乘回设备分辨率。这一步看起来简单，实际救了我无数次：换了台新设备，Agent 完全不需要重新训练策略。

第二层是候选节点筛选。屏幕上的可点击元素往往只有几十个，但原始树里有几百个节点。我针对“当前任务可能操作的目标”做过滤，保留clickable=true的控件，同时把它们的可点击区域放大 6% 到 8% 做容差，抵消手指点击的物理误差。对非可点击但有明确语义的文本节点，也会单独留一份做参考上下文。

第三层是语义压缩。决策模型不可能读懂 500 个节点的完整 JSON，我会把整理后的节点压缩成一行一行的文本表示，类似一个排版好的列表：每个候选者一行，包含编号、文本、坐标范围。实验下来，这种紧凑格式对 LLM 的提示和理解效率都远优于原始 XML。

2.3 树通道的三个高频翻车点

这个通道踩坑极多，我挑影响最大的三个来讲。

第一个是 Dump 超时。某些页面存在持续动画，无障碍树的生成逻辑会一直处于忙碌状态，Dump 请求迟迟得不到响应。处理办法是设超时阈值，通常 3 到 5 秒还没返回就强制用像素通道接管。同时我自己做了一个缓存机制，同页面的树在 0.5 秒内的重复请求直接复用缓存，避免不必要的性能浪费。

第二个是动态刷新导致的节点引用失效。比如 Swipe 列表滑动时，列表项的节点 id 在树刷新后全部变化，之前选中的节点瞬间变成空引用。我的做法是不只用 id 定位，同时记录节点的语义特征和相对位置索引，刷新后先在相邻帧里去匹配“相同文本+相似位置”的节点，匹配到了就复用原计划，匹配不到才重新规划。

第三个是动态小部件和弹窗的树污染。系统的悬浮球、Toast、底部弹窗有时候不会立刻出现在树里，导致 Agent 以为界面还是旧的。这时候不能只信树，必须用像素去做一次“画面变化检测”，强制触发重试 Dump。后面讲融合策略时会展开说。

3. 投屏像素通道：不是截图，是动态视觉巡检

3.1 像素流怎么拿：延迟比清晰度重要

投屏像素方案的选型要优先考虑延迟，而不是清晰度。Agent 是交互系统，画面延迟每多 100 毫秒，整个任务链路的误差就放大一倍。可选方案里，scrcpy协议的综合表现最好，它既能拿低延迟视频流，又能反向注入触摸事件，一举两得。minicap也能用，但要额外解决触控注入问题。

我建议的分辨率策略是：默认请求 720p 的竖屏流，必要时再升级到 1080p，不建议直接上原生分辨率。原因有两个：一是视频解码开销小、帧率高，Agent 对画面的处理目标更多是“判断变化、确定区域、验证状态”，不是做高清图片存档；二是很多状态验证只需要看清局部区域，全图高清纯属浪费算力。

拿到视频流后，我并不是把每一帧都送进模型，而是做抽帧处理。正常情况下每 300 到 500 毫秒抽一帧作为感知输入，在检测到界面剧烈变化或者 Agent 刚执行完点击操作时，临时加速到每 100 毫秒一帧，持续 1 秒左右。这种动态抽帧策略让像素通道的成本降到纯逐帧方案的 1/5。

3.2 坐标映射与 ROI 裁剪模型

像素流最关键的工程问题是坐标映射。视频流里的坐标和设备原始坐标之间是缩放关系，缩放系数很容易算，但坑在于很多设备有圆角、刘海、状态栏和底部手势条。如果不裁剪，Agent 会误以为屏幕下方有可用空间，把一个“半截按钮”当成完整按钮。

我的做法是建立一份设备配置档：包括屏幕原始尺寸、视频流尺寸、顶部刘海高度、底部安全区高度、左右黑边宽度。所有从像素通道得到的目标坐标，都要经过这套配置投影回真实屏幕坐标。

更实用的是 ROI 裁剪模型。界面理解不需要分析整张图，只需要围绕目标节点或疑似变化区域做局部裁剪。比如树通道说某个弹窗按钮在坐标 (320, 600)，像素通道只需要把 (300, 580) 到 (340, 620) 这个小区域裁出来做 OCR 验证，既快又准。我给这个机制起了个内部代号叫“验证切片”，后面融合策略里还会提到。

3.3 像素通道到底“兜底”了什么

像素通道不是做全页面的视觉理解，它只负责四类任务。

第一类是状态确认。点击操作发出后，Agent 需要确认画面变化了没有。这时候截图对比上一个画面的差值区域，就能快速判断是跳转新页面、弹出弹窗还是原地没响应。这比重新取树快得多。

第二类是树缺失时的视觉入口发现。当树通道返回“无可点击节点”时，像素通道会对整个画面做一次轻量目标检测，识别明显的按钮外观区域，把这些区域作为候选，再配合 OCR 提取文案，反哺给决策层。

第三类是遮挡检测。某些悬浮窗、系统弹窗、Toast 会遮住目标区域，树里不一定看得到，但像素对比能发现前景覆盖。我会用“画面静止期多帧对比”的方法，找出从无到有出现的前景区域。

第四类是文本兜底验证。树节点的文本和像素 OCR 出来的文本不一致时，以 OCR 为准。比如某些 WebView 里节点文本是对的，但实际渲染被 CSS 截断或隐藏，OCR 能暴露真相。

4. 双通道融合策略：互相纠错，而不是简单拼接

4.1 主从分工与触发切换条件

双通道不能做成“两个结果同时上屏让决策模型二选一”，那样信息冲突太多，模型会犯迷糊。我的设计是严格的主从结构：默认以树通道为唯一决策依据，像素通道只做验证和兜底，但在特定条件下允许像素通道“夺权”。

触发切换的三大条件是硬编码规则：树 Dump 超时、树节点全空或全不可点击、以及 Agent 刚做完一次点击后像素验证发现画面纹丝不动。这几种情况本身就是树通道不可信的强信号，此时直接进入像素主导模式，Agent 所有的决策输入都来自视觉结果，直到下一个稳定页面被成功构建出树。

我一开始也想过用置信度分数来决定由哪个通道主导，实现后发现太复杂，而且置信度本身不可靠。后来改成条件触发加超时熔断，简单粗暴但稳定得多。Agent 系统的第一要务从来不是高深算法，而是确定性。

4.2 跨通道对齐打分机制

当树和像素同时可用时，我会对每个候选节点做一次对齐打分，分数由四个维度组成：文本匹配度、坐标重合度、尺寸接近度、时间新鲜度。

文本匹配度用编辑距离的归一化值，1.0 表示树文本和像素 OCR 完全一致。坐标重合度用两个通道给出的目标框的 IoU（交并比）来衡量，重合越高分越高。尺寸接近度看目标框长宽比例是否相似，防止树里的 clickable 区域和实际按钮视觉面积差太远。时间新鲜度则惩罚过期数据，树的 Dump 时间离现在越近分越高。

只有当对齐分数超过阈值时，节点才会被正式加入候选集；未达到阈值的节点进入“待观察区”，由像素通道继续跟踪两帧再做决定。这套评分的最大价值是减少决策模型被脏数据误导的概率。分数低于 0.7 的节点，决策模型看了也会犹豫，不如直接过滤掉。

4.3 一个实际执行流程的走读

我拿“点击设置页的 WLAN 入口”这个动作来走一遍流程。Agent 先向树通道请求当前页面结构，拿到一个包含多个候选节点的列表，其中 WLAN 节点的文本是“WLAN”，坐标在屏幕约 28% 高度处。这不是最终答案。

像素通道立刻裁出以该坐标为中心的一小块验证切片，对切片做 OCR，识别出文字确实是“WLAN”，且按钮轮廓可见。对齐评分通过，节点被采纳。Agent 发送点击。300 毫秒后像素抽帧对比发现画面变化明显，确认点击已生效。整套流程下来，树负责给我答案，像素负责给我底气。

如果切片 OCR 识别结果不是“WLAN”而是“Wi-Fi”？评分不达标，节点不会进入候选集。Agent 转而检查树里有没有其他语义相近的节点，同时像素通道扩大扫描范围，寻找名称相近的其他入口。这种互相纠错的模式，单靠任何一个通道都实现不了。

5. 落地实战：问题清单与参数调优

5.1 我踩过的十个典型坑

双通道系统在真实设备上跑稳定，需要跨过不少暗礁。我把高频问题整理成一张速查表。

这些问题没有一个能让系统完全瘫痪，但积累多了，Agent 的成功率会从 98% 一路掉到 70% 以下。排查的顺序我建议是：先看树是否新鲜，再看坐标是否对齐，最后查像素流是否退化。按这个顺序能省一半时间。

5.2 可复用的参数与调优建议

参数调优这块，我不给死数字，只给每个参数的调节思路。超时阈值建议设置成动态的，不同设备性能差异很大，中端机能跑进 3 秒的 Dump 重型机可能要 6 秒。我的做法是记录最近十次 Dump 耗时，取 90 分位数再乘 1.2 作为当前超时阈值。

像素抽帧间隔默认 400 毫秒是最稳的，既能及时发现页面变化，又不会给解码器和 CPU 带来持续高压。如果 Agent 运行设备性能较好，可以缩到 250 毫秒；性能较差的旧设备宁可放大到 600 毫秒，也不能让系统发热降频，否则整个任务都会卡死。

坐标容差按目标控件尺寸的 8% 到 12% 来设置。小按钮取偏大值，大按钮取偏小值，避免把小按钮的点按误判成相邻按钮。还有一个容易被忽略的参数是“稳定判定帧数”：像素画面连续两帧差异低于阈值才算静止，动画比较重的应用建议三帧，否则会在动画中间误判为静止。

更重要的是一条元原则：优先级永远是树优先，但树的权威性来自它的新鲜度和校准质量。每次新页面构建完成后，我都会用像素通道快速做一次“树校检”——随机抽 3 到 5 个候选节点加验证切片，确认树和画面一致才标记为可信状态。这个过程耗时约 50 毫秒，对决策质量影响却是决定性的。

最后分享一个小技巧。给 Agent 配感知日志时，一定要同时记录树通道的原始节点数和像素通道的状态确认结果。出问题复盘时，联合这两份日志能很快定位到是感知层的责任还是决策层的责任。我见过太多人日志只记决策层的思考过程，感知层出了问题全是一团黑，复盘效率极低。

这个双通道方案后续还可以继续扩展。目前我这边已经有人在尝试加入音频事件的感知通道，用来判断语音助手、视频播放的状态。不过我个人觉得，先把手头的树和像素融合做到极致，比急着加第三通道更有价值。感知是地基，地基稳了，上层决策才有发挥空间。