agent_admin/docs/agent/actions/wait.md

WAIT

返回动作目录 · 任务协议 · Condition · 统一选择器

1. 当前行为 [已实现]

{
  "id": "wait-ready",
  "action": "WAIT",
  "packageName": "com.example.target",
  "selector": {
    "text": "准备完成"
  },
  "timeoutMs": 5000,
  "optional": false
}

当前 WAIT：

• 约每 100 毫秒查询一次。
• selector 匹配一个节点时成功。
• 没有匹配时等待到超时。
• 多个匹配时立即返回 TASK_AMBIGUOUS。
• 超时返回 TASK_NOT_MATCHED；optional=true 时继续下一步。

2. Condition 扩展 [提案]

{
  "id": "wait-result",
  "action": "WAIT",
  "packageName": "com.example.target",
  "condition": {
    "state": "VISIBLE",
    "selector": {
      "text": {
        "mode": "CONTAINS_ANY",
        "values": ["操作完成", "处理成功"]
      }
    },
    "cardinality": "ANY"
  },
  "pollIntervalMs": 200,
  "timeoutMs": 10000
}

首批状态：

• PRESENT：存在匹配节点。
• GONE：不存在匹配节点。
• VISIBLE、ENABLED、SELECTED、CHECKED：节点满足对应状态。
• PAGE_STABLE：页面结构在指定时间内保持不变。

cardinality 支持 ONE 和 ANY。v1 兼容格式仍保持 ONE，不能改变现有任务语义。

3. 执行规则

1. 在总 timeoutMs 内等待包名和可选 Activity。
2. 每轮重新读取当前页面。
3. 求值 Condition。
4. 条件满足时成功，否则按 pollIntervalMs 继续。
5. 读取或条件错误立即失败，不无限重试。

timeoutMs 是总时间，不因轮询或稳定性判断重新计时。

4. 结果码

• OK：条件满足。
• WAIT_TIMEOUT：超时未满足。
• TARGET_AMBIGUOUS：要求 ONE 但匹配多个。
• CONDITION_ERROR：条件无法正常求值。

v1 对外仍可映射为现有 OK、TASK_AMBIGUOUS 和 TASK_NOT_MATCHED。

5. 测试

覆盖立即满足、等待后满足、超时、多目标、GONE、状态变化、页面稳定和 optional 兼容行为。