47 lines
6.8 KiB
Markdown
47 lines
6.8 KiB
Markdown
# 安卓原生控件与多指动作
|
||
|
||
Flash、普通 Pro 和探索共用同一套动作参数、助手执行入口与设备锁。外层 `mobile_run_task` 等 MCP 提交接口保持不变；这些是任务内供模型组合的通用工具，不绑定某个 APP 或时间轴。
|
||
|
||
| 工具 | 用途 | 主要边界 |
|
||
| --- | --- | --- |
|
||
| `read_control` | 读取范围、当前值、支持动作、选区、状态及身份 token | 只读；精确选择器必须唯一 |
|
||
| `control_action` | 原生点击、长按、聚焦、显示、设进度、滚动、编辑与 IME 提交 | 仅执行控件实际支持的动作；不回退坐标 |
|
||
| `wait_until` | 等待出现、消失、可用、选中、精确文本/数值或持续稳定 | 只读；最多 30 秒；读取失败不能证明消失 |
|
||
| `scroll_to` | 在指定唯一容器内滚动到目标 | 最多 20 次/30 秒；无进展、边界、失败或取消即停止 |
|
||
| `pinch` | 同步双指缩放，并可旋转 | 两指间距与角度可配置；最长 10 秒 |
|
||
| `touch_gesture` | 1～5 指同时按住、停留及多段连续移动 | 2～32 个关键帧；跨段保持同一次接触；最长 10 秒 |
|
||
|
||
## 控件选择与精确编辑
|
||
|
||
`selector` 中提供的属性全部按精确 AND 匹配：`resource_id`、`text`、`content_desc`、`class_name`、`package_name`、`bounds`。至少提供一项观察到的资源 ID、文本、描述或类名；包名和坐标不能单独充当语义目标。原样复制观察结果，不猜包名或省略 ID。未找到、多个匹配、不可读及不支持分别返回明确回执。
|
||
|
||
原生查询在当前窗口及同一前台 APP 不低于当前窗口的应用窗口中共同解析，跨窗口仍须唯一，不扩大到后台 APP。窗口枚举或所属窗口信息不完整时返回不可用，不能据此证明控件消失。原生写入前再次检查可见性及窗口层级：将目标裁切到所属窗口的可触区域，并扣除所有同屏更高窗口的可触区域，必须仍有可见区域；完全遮挡则返回 OCCLUDED。部分露出的编辑框可继续原生编辑，不会因 Android 选区工具栏或手柄的小幅覆盖就一律拒绝。Android 11/API 30 及以上使用系统提供的精确区域；更旧系统只能用矩形边界近似，非矩形窗口可能有偏差。透明或不可触摸的窗口也可能保守拒绝，应重新观察或关闭遮挡，不自动回退坐标。
|
||
|
||
先 `read_control`，再按实际 `actions` 操作。范围设值使用 `action="set_progress", value=...`，严格检查实际 min/max；自绘时间轴没有 range 时不能直接设置秒数。`expected_token` 可绑定之前的读数；目标文本、位置或身份变化时返回 `STALE`，由模型重新观察，避免使用旧目标。
|
||
|
||
文本动作包括 `set_text`、`set_selection`、`replace_selection`、`ime_enter`。选择区使用 Android UTF-16 索引，不能切开代理对；例如 `A😀B中文` 中 emoji 的范围是 `[1,3]`。`replace_selection` 保留其它文字并将光标移至插入末尾；空白与空字符串按原样传入。密码字段不公开原文，不支持基于隐藏原文替换选区。`ime_enter` 仅提交控件支持的 IME 动作，不代表业务表单已成功提交。
|
||
|
||
## 手势、组合与验证
|
||
|
||
坐标空间明确写作 `normalized`（0..1000，默认）或 `pixel`（原图像素），全程只换算一次。`pinch` 的归一化间距按屏幕短边换算，保留物理纵横比例；`angle_degrees` 是起始双指方向，`rotation_degrees` 是旋转量。`touch_gesture.frames` 每项含 `at_ms` 与按固定手指顺序排列的 `points`；从 0 开始，时间严格增加，手指数量保持不变。同坐标后续帧表示继续按住。越界、相交或合并的触点在输入前拒绝，不夹到屏幕边缘。
|
||
|
||
`action_sequence` 可组合 `pinch`、`touch_gesture`、`wait_until` 及 `control_action`。控制动作成员把参数放入 `request`：`{"action":"control_action","request":{"selector":{"content_desc":"观察到的名称"},"action":"click"}}`。数量沿用任务的 `pro.execution.max_burst_actions`，等待也算成员；组内条件等待最多 3 秒，文本最多 1024 字符。全部成员先校验参数与能力，后执行；部分失败停止余下成员，保留已经完成与结果不明的回执。不要整组重发。较大文本用单独 `control_action`；序列仍保留 16,384 字符参数流保护。
|
||
|
||
`wait_until` 遇到窗口过渡产生的 READ_FAILED/UNAVAILABLE 时，在原定时限内继续只读轮询，并重新计算稳定窗口；只有可靠的后续观测才能满足条件。持续不可读会超时并保留最后的原始错误，不会当作控件消失。歧义、无效状态及不支持等错误立即返回。
|
||
|
||
原生滚动接受动作后，仍等待容器内容及目标可见性/身份连续停稳 `settle_ms`，再确认目标或追加下一次滚动；动画中短暂进入视口不能证明完成。首次内容更新有至少 500ms 的观测余量，总等待仍受 `timeout_ms` 限制，结果不明的输入不重复派发。
|
||
|
||
执行回执区分 `not_started`、`observed`、`completed`、`partial`、`cancelled`、`unknown`，并保留节点前后状态、观测与中间滚动记录。派发完成只证明 Android 完成输入，不能证明 APP 收到了输入或业务通过；键盘、弹层、透明遮挡都可能截获触点。每组动作后重新观察实际控件值、刻度或 APP 状态。取消先到会记录 operation ID，阻止迟到的同一手势；输入仍不确定时保持通道占用，旧点击/滑动也不能抢占。原生写请求不会切换到其它后端重放。
|
||
|
||
原生能力由连接时的助手声明决定。新助手协议为 3，多段/多指手势需要 Android 8.0/API 26；旧助手或其它后端不支持时工具不会暴露，直接调用也明确拒绝。没有原生语义的控件继续使用观察后手势，不能冒充原生设值。
|
||
|
||
## 时间轴精度
|
||
|
||
双指距离变化不一定等于 APP 比例尺变化：先小幅缩放，再读取实际刻度，建立像素与时间的局部对应。平移后等待停稳，读取残差再修正；播放中应先暂停后验收。
|
||
|
||
如果常驻读数通过标签、节点角色或层级明确绑定到固定指针当前选时，且在暂停或独立停稳观测中持续显示、与刻度一致，可以直接作为秒级证据，无须再要求粗像素插值独立达到同样精度。事件卡片、录像水印和短暂拖动浮层不能代替当前选时。真实冲突、来源不明或缺少稳定证据时继续保留不确定结论；没有可信读数时仍用刻度插值并计入读图误差。
|
||
|
||
## 开发验证
|
||
|
||
默认单元测试不需要设备。真实设备回归使用隔离测试 Activity，先通过 ARTEMIS 探索，再显式执行 [测试夹具说明](../tests/native_actions_fixture/README.md)。回调模拟只能验证状态机，不能代替 APP 的真实 MotionEvent、控件值或屏幕证据。
|