设备与 UI 实战

这页聚焦设备与 UI 执行的边界、分层和稳定执行建议。

先判断是不是设备与 UI 问题

• 你要真的对设备做动作：比如启动应用、切页面、点击输入、滚动、截图、导日志，看这里
• 你要做端侧收敛、等待、诊断修复、多设备广播执行，看这里
• 你主要在处理接口协议、媒体转码或安全签名，不要先从这份文档开始
• 你只是想确认主入口和最小命令，先回入口页，不必先读完整设备文档

怎么读这页

• 先看“这页解决什么问题”和“设计定位”，确认设备与 UI 执行的职责边界
• 再看“执行模型”和“能力分层”，判断当前动作应该落在哪一层
• 最后看定位方式、前台收敛和 system/ui 边界，把稳定性思路建立起来
• 如果你要把设备动作真正写进 --code，结构层先配合星图协议页，执行语义再配合星图深入说明

这页解决什么问题

• 设备与 UI 执行到底能做什么
• 设备能力应该按什么边界理解，而不是死记工具名
• 哪些动作应该走应用级、页面级、系统级、证据级能力
• 多设备执行、前台收敛、诊断修复和等待应该怎么理解

设计定位

设备与 UI 执行是端侧动作能力。

它的重点不是“回答页面上有什么”，而是：

• 真的对设备做动作
• 把动作结果按 agent 回收
• 让应用、页面、系统和证据链动作有清晰边界
• 适合放进巡检、回归和批跑链路，而不是只做临时演示

一句话理解：

• 这类能力负责端侧动作和动作收束
• 它不是接口域，也不是单纯的页面说明层

执行模型

大多数设备执行能力都走同一套广播模型：

• 默认对当前在线设备列表广播执行
• matrix 可按 serial -> args 做逐设备覆盖
• 多设备场景下返回的是 per-agent 结果，不是单一设备结果

这意味着：

• 你不写 matrix，通常就是对所有在线设备一起执行
• 你写了 matrix，可以对不同设备传不同参数
• 多设备 pull、截图、logcat 这类能力会避免本地文件冲突

能力分层

1. 设备发现与执行入口

这一层负责：

• 刷新在线设备列表
• 在执行前收敛可用设备
• 以广播模型把动作分发到多个设备

适合：

• 执行前做设备就绪检查
• 多设备批跑前先确认在线设备集合

2. 应用生命周期能力

这一层负责：

• 启动、停止、清数据、安装、卸载
• Deep Link 跳转
• 前台收敛和应用状态切换

边界：

• 以包名、Activity、Deep Link 为核心输入
• 目标是让应用状态正确，不是点页面控件
• “确保应用真的来到前台”属于这一层，不属于页面点击层

适合：

• 启动应用
• 重置应用状态
• 直接拉起到目标页面

3. 页面交互能力

这一层负责四类事情：

• 手势与滚动
• 页面内点击与选择
• 输入与焦点控制
• 页面感知、等待和诊断修复

边界：

• 坐标手势属于绝对动作
• 控件查找、等待、点击属于页面语义动作
• “滚到目标出现”为止和“等待目标状态变化”都属于这一层
• 诊断修复属于处理页面定位漂移的专门能力，不是普通点击替代品

适合：

• 页面内滚动、点击、输入
• 等待页面状态变化
• 页面结构诊断和定位漂移修复

4. 观察与取证能力

这一层负责：

• 设备快照
• 页面截图
• 安装包与环境观察
• 文件与日志导出

边界：

• 以观察、留证、导出为主
• 不负责改变应用或系统状态

适合：

• 拉设备快照
• 截图留证
• 动作后导出日志
• 判断包或环境是否就绪

5. 系统控制能力

这一层负责：

• 通知栏、快捷页、系统级界面入口
• 屏幕、电源、网络、输入法等状态切换
• 重启、解锁、组合键等强系统语义动作

边界：

• 系统级入口不要用页面点击模拟
• 电源、网络、锁屏这类动作优先走系统语义能力

适合：

• 系统级页面和开关控制
• 需要更稳、更接近系统语义的动作

6. 按键与导航能力

这一层负责：

• Home / Back / Recents 一类系统导航键
• Enter / Tab / Delete 一类物理键语义输入
• 音量、媒体控制等硬件键语义

适合：

• 需要真实导航键语义的场景
• 不适合用页面点击替代的系统交互

7. 扰动与稳定性能力

这一层负责：

• 随机事件注入
• 稳定性扰动
• 压测式探索
• 与日志留证配套的异常发现

特点：

• 不是普通点击脚本
• 会触发系统随机事件注入
• 同时抓取 logcat 证据

适合：

• 稳定性扰动
• 随机事件压测
• 崩溃、ANR、异常日志探测

定位方式和稳定性

ui 当前支持的典型定位方式：

• id
• desc
• text
• bbox
• xpath

但要注意：

• xpath 在 find_element 这类场景并不稳定，代码里已经明确写了 Android dump 不是标准 XPath
• match / ignore_case 只对字符串类定位生效
• bbox 更偏硬坐标，适合临时兜底，不适合长期维护

更稳的优先级通常是：

1. id
2. desc
3. text
4. bbox

前台收敛、等待和诊断修复

设备与 UI 链路里真正提高稳定性的，不是多点几次，而是这些能力：

• 前台收敛
• 负责把应用真正收敛到前台
• 显式等待
• 负责把页面变化显式等待出来
• 目标滚动到可见
• 负责把目标滚进可见区域，而不是盲滚
• 诊断与修复
• 负责定位漂移后的诊断和修正
• 焦点与页面上下文检查
• 负责在动作前确认当前页面和焦点是否对

推荐思路：

1. 先确保应用或页面状态对
2. 再找控件
3. 再点击或输入
4. 再等待结果出现或消失

不要把所有问题都堆给 click。

什么时候用 system，什么时候用 ui

优先用系统控制能力：

• 打开通知栏
• 打开系统设置
• 屏幕开关
• Wi-Fi、蓝牙、数据开关
• 重启、解锁、组合键

优先用页面交互能力：

• 页面内部控件查找
• 滚动、点击、输入
• 等待页面元素出现或消失

优先用按键与导航能力：

• Home / Back / Recents / Menu
• Enter / Tab / Delete / Space
• 音量、媒体控制

不要用 tap 去模拟系统栏入口，也不要用 click 去替代真实系统按键。

模式建议

• chat
• 适合探索式设备操作、边看边调
• fast
• 不适合重型设备主路径，设备相关能力会更受限
• plan
• 最适合固定流程、巡检、页面跳转和回归链路

如果任务是：

• 多步设备巡检
• 固定 UI 路径
• 需要前后台收敛和等待

优先考虑 plan。

常见写法建议

更稳的链路通常长这样：

1. 刷新设备可用性
2. 收敛应用到前台
3. 显式等待页面状态
4. 执行页面查找、点击或滚动到可见
5. 输入文本或执行系统导航
6. 再次等待目标状态变化
7. 截图或导出日志留证

而不是：

1. 连续 tap
2. 猜页面已经到了
3. 再继续 tap

自然语言样例

首页进入并留证

打开 `com.example.app`。
确认页面上已经出现“首页”标题和底部导航栏。
截图。

这条链体现的是： - 先让应用状态对，再做页面确认，最后再留证 - 重点是“前台收敛 -> 显式等待 -> 截图”，不是连续盲点

滚动到目标并进入详情

打开 `com.example.app`。
向下滚动，直到文本“订单详情”出现在可见区域。
点击“订单详情”。
确认详情页上已经出现“订单号”和“支付状态”这两个字段。

这条链体现的是： - 不靠盲滚，而是先把目标滚进可见区域 - 进入详情和等待稳定是两件事，别混成一次点击

约束和风险

• 多设备默认广播执行，别忽略这一点
• 文本输入依赖输入焦点和输入法环境
• 兜底式输入方案对中文、emoji、特殊字符兼容性有限
• xpath 不适合当成长期稳定定位策略
• 坐标点击容易随分辨率、布局和状态变化漂移
• reboot、网络开关、安装卸载这类动作有明显副作用，别在探索场景乱用

和其它域的关系

设备与 UI 执行负责真的操作设备；多媒体处理负责截图、录屏、音视频和证据加工；协议与校验、性能采样负责接口与报告链路；--code 负责把动作组织成可批跑、可回归的星图。

设备与 UI 执行不是孤立的，常见组合是：

• device + media
• 执行后截图、录屏、抽帧
• device + file
• 动作后拉日志
• device + --code
• 固定流程批跑

什么时候优先看这页

• 你要做端侧设备 / UI 执行
• 你要理解 device 和 media / bench 的边界
• 你在排查为什么点击不稳、输入没生效、页面没收敛
• 你要把设备动作写进 plan 或 --code

相关文档

• 交互模式
• 星图协议
• 星图深入说明
• 多媒体链路
• 正文目录