feat(android): add state conditions and measured gesture feedback

Add optional ensure_state, gesture region and final value feedback shared by Flash and Pro. Preserve completed inputs when verification fails and stop repeated ineffective strategies. Regenerate pinned tool schemas for the new optional arguments.
This commit is contained in:
chenmingxuan committed 2026-11-02 23:20:34 +08:00
1 parent 6a69a595ef
commit 4ea7939d9c
20 files changed
+2779 -33

No files matched your search

@@ -37,6 +37,24 @@ Flash、普通 Pro 和探索共用同一套动作参数、助手执行入口与
## 时间轴精度
精确调整可绑定可选的 `feedback`:`selector` 指向原生可读取、唯一且持久的真实选中值,`value_format` 为 `range`(原生范围)、`number`(完整数字文本)或 `clock`(文本中唯一的 HH:MM:SS,换算为当天秒数),并提供同单位的 `target_value` 与 `tolerance`。不要选择录像卡片、视频水印或短暂拖动浮层,也不要在 selector 中包含会变化的读数文本。无法建立真实绑定时继续视觉观测,不能编造控件或把手势派发当作读值。
单独拖动把 feedback 放在 `drag` 参数上;“拖动后暂停”等组合把它放在 `action_sequence` 顶层,不放在 drag 成员上。输入前确认可读,整组成功后再等待读数连续稳定 `stable_ms`(默认 1000,范围 100–5000),总观察不超过 `timeout_ms`(默认 3000,上限 10000,必须大于稳定时长)。时钟稳定时长应覆盖其刷新周期。回执含 before_value、after_value、residual、within_tolerance 和连续无效次数;数值条件满足与最终业务验收分开。输入完成但读数失败或未达标仍保留完成回执,不会自动重发。
同一执行实例内,同读数、目标和策略连续两次没有减小实际误差,第三次拒绝输入,提示重新观察并放大、改变有效移动距离或使用原生设值。微改坐标不算换策略;新刻度比例、轴向或明显不同的距离可重新尝试。读数改变或任务实例更换后重新判断。此守卫依赖显式 feedback,不声称能够自动理解所有自绘控件。
所有手指路径可以通过 `region=[left,top,right,bottom]` 限定到已观察到的手势区域;坐标单位跟随 coordinate_space,右/下边界不包含在区域内。拖动、缩放或多指轨迹离开区域时整组在首个输入前拒绝;区域只验证几何边界,不证明窗口未被遮挡。calibration.tolerance 检查像素取整误差,回执给出每像素数值和允许像素误差;min_movement_px 只能填实测起效距离,过小则拒绝并要求放大。几何误差不包括读图、惯性与 APP 的内部吸附误差。
暂停或勾选等状态可用 `control_action.ensure_state`,支持 checked/unchecked、selected/unselected、text/content_desc 精确匹配及 value/tolerance。先 read_control 确认其语义,稳定 selector 不包含会改变的文字/描述。达到状态时跳过;未达到时仅操作一次,再只读等待 verify_timeout_ms(默认 1500,上限 3000)。状态缺失不当作 false,核验失败保留已完成输入,不继续盲点切换。不能假定 selected 就表示暂停。
例如,已观察确认资源 ID `player` 的描述为“播放”时表示暂停,可将以下成员放在拖动后:
```json
{"action":"control_action","request":{"selector":{"resource_id":"player"},"action":"click","ensure_state":{"state":"content_desc","expected_text":"播放"}}}
```
示例 ID 和状态含义必须换成实际观察结果。绑定时间反馈示例为 `{"selector":{"resource_id":"observed_current_time"},"value_format":"clock","target_value":63737,"tolerance":5}`,对应目标 17:42:17±5 秒;不用于日期验收或跨日时间差。
双指距离变化不一定等于 APP 比例尺变化:先小幅缩放,再读取实际刻度,建立像素与时间的局部对应。平移后等待停稳,读取残差再修正;播放中应先暂停后验收。
如果常驻读数通过标签、节点角色或层级明确绑定到固定指针当前选时,且在暂停或独立停稳观测中持续显示、与刻度一致,可以直接作为秒级证据,无须再要求粗像素插值独立达到同样精度。事件卡片、录像水印和短暂拖动浮层不能代替当前选时。真实冲突、来源不明或缺少稳定证据时继续保留不确定结论;没有可信读数时仍用刻度插值并计入读图误差。