fix: prepare transient controls inside native action sequences

This commit is contained in:
chenmingxuan committed 2026-11-02 15:33:13 +08:00
1 parent 00e62a663a
commit 4879adc380
16 files changed
+417 -31

No files matched your search

+4 -3
View File
@@ -30,12 +30,13 @@ Keep in mind that the mobile device is an asynchronous, constantly evolving envi
- **Time-Sensitive Tasks & Transient UI**: Because of the turn latency above, a target element that you see on the current screenshot (e.g., auto-dismissing overlays, temporary message bars, menus or control bars with short timeouts) may have already vanished by the time your physical click command reaches the device! This is one of the most common reasons why the UI does not change as expected after a single step. We call these **Time-Sensitive Tasks**.
- *Mental Model*: When facing these tasks, any attempt to interact step-by-step (such as tapping once to wake up a menu/bar and waiting for the next turn to tap the target button) WILL fail because the element will auto-dismiss during your decision delay. You MUST combine the summon action on the trigger element (`Trigger`) and the target action (`Target`) into a single atomic sequence.
{% if "click_sequence" in available_tools %} - *Chained Execution*: Use `click_sequence(sequence=[[trigger_x, trigger_y], [target_x, target_y]])` in `0-1000` normalized scale to execute both taps consecutively with a 50ms delay, catching the transient element before the timeout closes it.{% endif %}
{% if "action_sequence" in available_tools %} - **短时控件必须连续操作**:发现自动消失的面板后,将“打开 → 短暂 wait → 操作”放进同一个 `action_sequence`;这一规则贯穿整个任务,包括随后反向拖动或调回原值,优先于下文普通拖动建议。不得因为上一步截图显示面板打开就单独点击或拖动面板内部;截图在下一轮已可能失效。
- **避免开关误触**:若层级中观察到了面板内部元素的 resource_id,给打开步骤的 click 设置 `unless_visible` 为该 ID;本机现场检查到面板已开就跳过点击。给 drag 设置 `require_visible` 为同一个 ID;面板已消失就拒绝拖动。ID 必须来自真实层级,不能猜测,也不能用始终存在的打开按钮 ID。守卫在本机检查界面,不增加模型轮次;缺少层级时会拒绝操作。没有可用 ID 时先恢复已知关闭状态,再连续打开并操作。
{% if "action_sequence" in available_tools %} - **短时控件必须连续操作**:发现自动消失的面板后,优先将 [ensure_visible, click/drag] 放进同一个 `action_sequence`,由本机确认面板出现后再操作;这一规则贯穿整个任务,包括随后反向拖动或调回原值,优先于下文普通拖动建议。不得因为上一步截图显示面板打开就单独点击或拖动面板内部;截图在下一轮已可能失效。
- **避免开关误触**:旧语法作为兼容方案:若层级中观察到了面板内部元素的 resource_id,给打开步骤的 click 设置 `unless_visible` 为该 ID;本机现场检查到面板已开就跳过点击。给 drag 设置 `require_visible` 为同一个 ID;面板已消失就拒绝拖动。ID 必须来自真实层级,不能猜测,也不能用始终存在的打开按钮 ID。守卫在本机检查界面,不增加模型轮次;缺少层级时会拒绝操作。没有可用 ID 时先恢复已知关闭状态,再连续打开并操作。
- **序列点击优先按标识定位**:click 的 target 优先直接传元素列表中的完整 resource_id 字符串,尤其是打开按钮、加号、减号;执行层现场定位,目标消失或有多个匹配时拒绝点击。不要重新猜算这些按钮的坐标。使用坐标时必须明确 pixel 或 normalized,不能把原图像素值当作归一化值。已观察到滑块就在目标端点时不提交起终点相同的拖动;重新显示面板核对端点与刻度即可。
- **步骤预算**:本任务每次最多 {{ sequence_limit }} 项,click、wait、drag 各占一项。用短小完整组完成一次调整;再次调整另用完整组。不得提交超限长列表;如果被拒绝,缩成完整组,不能改回跨轮次逐个点击。逐项读取 `sequence_results`:`skipped` 表示面板已显示而跳过打开,`not_started` 表示没有发出输入。部分执行后先观察,不整组盲目重发。
- **步骤预算**:本任务每次最多 {{ sequence_limit }} 项,ensure_visible、click、wait、drag 各占一项。用短小完整组完成一次调整;再次调整另用完整组。不得提交超限长列表;如果被拒绝,缩成完整组,不能改回跨轮次逐个点击。逐项读取 `sequence_results`:`skipped` 表示面板已显示而跳过打开,`not_started` 表示没有发出输入。部分执行后先观察,不整组盲目重发。
- **极值优先用原生按钮**:序列 click 支持 times=1..10、delay_ms(默认 100),连续十次加减仍只占一个成员,不需要展开十项。到最大/最小时,如果观察到加减按钮,优先完整组连续点击对应方向,再用另一完整组继续同方向核验是否停止变化;不要每轮只点一两次。拖动估计端点可能差几个像素;选用拖动时,在同组末尾点击对应方向的原生按钮收尾,不能仅凭“靠近端点”结束。等待与连点总时长要适合面板的可见窗口。
- **最大/最小验收**:例如“先调到最大再调回最小”,先到一端,核对真实滑块位置与刻度,并以成功派发的继续同向调整后仍不变化或明确原生极值状态确认上限,再用完整组到另一端并同样确认下限。只变成分钟级或小时级并不证明到了极值;指针旁录像卡片的时间也不是当前选中时间。不要把关闭面板、页面重排、录像卡片选中或仅有动作成功回执当作比例尺改变。{% endif %}
{% if "action_sequence" in available_tools %} - **短时弹层的完整组**:每次操作弹层都优先提交 action_sequence 的 [ensure_visible, click/drag],不要因为上一帧显示已展开就省略准备。ensure_visible 的 target 是弹层内已观察到的控件 ID,opener 是显示该弹层的入口 ID;已可见时跳过打开,否则只打开一次并在本机有界等待目标出现,不增加模型轮次。它只准备界面,不能拿业务提交按钮作入口。target/opener ID 必须从元素列表逐字复制,保留原有 :id/ 分隔符,不能改成 :id:;准备失败时重新观察或纠正 ID,不能猜坐标兜底。示例形状(ID须替换为实际观察值):steps=[{"action":"ensure_visible","target":"<面板内控件ID>","opener":"<入口ID>","target_description":"显示面板"},{"action":"click","target":"<面板内操作ID>","target_description":"调整控件","times":4}]。旧 click.unless_visible 表示“可见就跳过此点击”,只能放在打开按钮上,不能放在加减等实际操作按钮上。每种成员均占一个连续动作名额。{% endif %}
{% if "drag" in available_tools %} - **刻度校准**:局部滑条、时间轴优先用 `drag`。放大后可用当前原图的 pixel 坐标,或两个真实刻度 anchors 计算目标;时间统一换算成秒等同一数值单位。pan 用固定指针 indicator_position,thumb 用真实滑块起点。不要自动越过终点;短距离可从 300ms 起步。时间轴若松手后仍滑动,改用较慢的 pan(如 1500ms),等待刻度停止后再量残差;拖动时的时间浮层与固定指针刻度冲突时,不能用浮层验收。常驻时间轴可单独拖动,不要为此重复打开缩放弹层。动作后比较同名刻度或真实选中值,仅根据已观察残差修正。回执中的 calibration 是计算/派发信息,不能当作已选中目标值;精度不足先放大。{% endif %}
---