# 任务流程控制

> [返回文档中心](README.md) · [任务协议](protocol.md) · [执行与结果](execution.md)

## 1. 当前状态

协议 v1 只支持线性 `steps` 和 `optional`。`when`、`BRANCH`、`nextStepId` 和 `onFailure` 均为 **[提案]**。

流程控制只在出现实际条件流程时实现，不提前引入循环、脚本表达式或复杂工作流引擎。

## 2. Condition **[提案]**

WAIT、动作 `after`、`when` 和 BRANCH 共用简单 Condition。

节点条件：

~~~json
{
  "state": "VISIBLE",
  "selector": {
    "text": {
      "mode": "CONTAINS",
      "value": "操作完成"
    }
  }
}
~~~

组合条件：

~~~json
{
  "mode": "ALL",
  "items": [
    {
      "type": "PACKAGE_IS",
      "value": "com.example.target"
    },
    {
      "state": "VISIBLE",
      "selector": {
        "resourceId": "com.example.target:id/result"
      }
    }
  ]
}
~~~

首批只需要：

- `ALL`、`ANY`。
- 节点状态：`PRESENT`、`GONE`、`VISIBLE`、`ENABLED`、`SELECTED`、`CHECKED`。
- 上下文：`PACKAGE_IS`、`ACTIVITY_IS`。
- 结果：`STEP_SUCCESS_IS`、`STEP_CODE_IS`。
- 输出比较：`EQ`、`NE`，需要时再增加数值比较。

Condition 返回 `MATCHED`、`NOT_MATCHED` 或 `ERROR`。引用缺失和读取失败属于 ERROR，不能当成条件不成立。

## 3. when **[提案]**

~~~json
{
  "id": "click-confirm",
  "action": "CLICK",
  "packageName": "com.example.target",
  "when": {
    "type": "STEP_SUCCESS_IS",
    "stepId": "prepare",
    "value": true
  },
  "selector": {
    "text": "确认"
  }
}
~~~

- MATCHED：执行动作。
- NOT_MATCHED：跳过步骤。
- ERROR：步骤失败。
- when 只判断当前状态，不等待；需要等待时使用 WAIT。

## 4. BRANCH **[提案]**

~~~json
{
  "id": "route-result",
  "action": "BRANCH",
  "cases": [
    {
      "condition": {
        "state": "VISIBLE",
        "selector": {
          "text": "操作完成"
        }
      },
      "targetStepId": "read-result"
    }
  ],
  "defaultStepId": "handle-unknown"
}
~~~

BRANCH 按顺序选择第一个匹配项。目标步骤必须存在并位于当前步骤之后，避免循环和无限执行。没有匹配项且没有 default 时返回 `BRANCH_NO_MATCH`。

## 5. onFailure **[提案]**

首版只需要三种处理：

- `STOP`：停止任务，默认值。
- `CONTINUE`：继续下一步。
- `GOTO`：跳到后续指定步骤。

~~~json
{
  "onFailure": {
    "codes": ["TARGET_NOT_FOUND"],
    "action": "GOTO",
    "targetStepId": "handle-missing"
  }
}
~~~

不提供自动重试动作或整个任务。需要再次尝试时，在任务中写一个明确的后续步骤，并继续受总超时限制。

## 6. 最小校验

解析时确认步骤 id 唯一、跳转目标存在且只向前。跨分支输出和复杂汇合规则等到实际需要时再设计。