# WAIT

> [返回动作目录](README.md) · [任务协议](../protocol.md) · [Condition](../flow-control.md#2-condition-提案) · [统一选择器](../selector.md)

## 1. 当前行为 **[已实现]**

~~~json
{
  "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 扩展 **[提案]**

~~~json
{
  "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 兼容行为。