3.3-任务流水线协议.md

# 任务流水线（Pipeline）协议

## 整体介绍

```jsonc
{
    "TaskA": {
        "next: [
            "TaskB",
            "TaskC"
        ]
        // properties ...
    },
    "TaskB": {
        // properties ...
    },
    // other task ...
}
```

我们执行某个 Task 时（MaaPostTask 接口传入任务名），会对其 next 列表中的 Task **依次** 进行识别（根据每个 Task 的 recognition 相关设置）  
且一旦匹配上了，则会退出 next 列表识别，转而去执行匹配上的任务。类似遍历比较，一旦找到了，就直接 break 转而去执行找到的那个 Task。

## 举例

例如我们有一个游戏，画面中可能出现一种水果，可能是苹果、橘子、香蕉，我们需要点击它。一个简单的演示 JSON：

```jsonc
{
    "StartFruit": {
        "next": [
            "Apple",
            "Orange",
            "Banana"
        ]
    },
    "Apple": {
        "recognition": XXX,
        "action": "Click",
        // ...
    },
    "Orange": {
        "recognition": XXX,
        "action": "Click",
        "next": [
            "Cat",
            "Dog"
        ]
    },
    "Banana": {
        // ...
    },
    // ...
}
```

假设现在画面中没有 Apple，但有 Orange 和 Banana。  
在上述 JSON 中，若我们执行 "StartFruit"（即 MaaPostTask 接口传入 "StartFruit"），会先识别 Apple，画面中没有，所以继续识别 Orange，这次识别到了，则我们开始执行 Orange，不会再去识别 Banana 了。  
执行 Orange 就是根据其 action 去进行对应的操作，当执行完成后，我们会再去识别 Orange 的 next。  

Orange 的 next 中，  
若识别到了 Cat，则不会继续去识别 Dog 了。这时同样会去执行 Cat 的 action，并在 action 完成后继续识别 Cat 的 next。  
若 Cat, Dog 都没有识别到，我们会再次尝试识别这两个，直至超时为止。  

如此循环，直至某个任务的 next 为空，即认为任务完成。

## 属性字段

- `recognition` : *string*  
    识别算法类型。可选，默认 `DirectHit`。  
    可选的值：`DirectHit` | `TemplateMatch` | `OCR` | `Custom`  
    详见 [算法类型](#算法类型)。

- `action`: *string*  
    执行的动作。可选，默认 `DoNothing`。  
    可选的值：`DoNothing` | `Click` | `Swipe` | `Key` | `StartApp` | `StopApp` | `StopTask` | `Custom`  
    详见 [动作类型](#动作类型)。

- `next` : *string* | *list<string, >*  
    接下来要执行的任务列表。可选，默认空。  
    按序识别每个任务，只执行第一个识别到的。

- `is_sub`: *bool*  
    是否是子任务。可选，默认否。  
    如果是子任务，执行完本任务（及后续 next 等）后，会返回来再次识别本任务 **所在的** next 列表。  
    例如：A.next = [B, Sub_C, D]，这里的 Sub_C.is_sub = true，  
    若匹配上了 Sub_C，在完整执行完 Sub_C 及后续任务后，会返回来再次识别 [B, Sub_C, D] 并执行命中项及后续任务。

- `timeout`: *uint*  
    `next` 识别超时时间，毫秒。默认 20 * 1000。  

- `timeout_next`: *string* | *list<string, >*  
    超时后执行的任务列表。可选，默认空。

- `times_limit`: *uint*  
    任务执行次数。可选，默认 UINT_MAX。

- `runout_next`: *string* | *list<string, >*  
    任务执行次数达到了后执行的任务列表，可选，默认空。

- `pre_delay`: *uint*  
    识别到 到 执行动作前 的延迟，毫秒。可选，默认 200。  
    推荐尽可能增加中间过程任务，少用延迟，不然既慢还不稳定。

- `post_delay`: *uint*  
    执行动作后 到 识别 next 的延迟，毫秒。可选，默认 500。  
    推荐尽可能增加中间过程任务，少用延迟，不然既慢还不稳定。

- `pre_wait_freezes`: *uint* | *object*  
    识别到 到 执行动作前，等待画面不动了的时间，毫秒。可选，默认 0，即不等待。  
    连续 `pre_wait_freezes` 毫秒 画面 **没有较大变化** 才会退出动作。  
    若为 object，可设置更多参数，详见 [等待画面静止](#等待画面静止)。  
    具体的顺序为 `pre_wait_freezes` - `pre_delay` - `action` - `post_wait_freezes` - `post_delay`。

- `post_wait_freezes`: *uint* | *object*  
    行动动作后 到 识别 next，等待画面不动了的时间，毫秒。可选，默认 0，即不等待。  
    其余逻辑同 `pre_wait_freezes`。

- `notify`: *bool*  
    产生一条回调消息。可选，默认 false，即不产生。  
    详见 [任务通知](#任务通知)。

## 算法类型

### `DirectHit`

直接命中，即不进行识别，直接执行动作。  

该任务属性需额外部分字段：

- `roi`: *array<int, 4>* | *list<array<int, 4>>*  
    假装识别到的位置。可选，默认 [0, 0, 0, 0]，即全屏。  
    四个值分别为 [x, y, w, h]。

### `TemplateMatch`

模板匹配，即“找图”。  

该任务属性需额外部分字段：

- `roi`: *array<int, 4>* | *list<array<int, 4>>*  
    识别区域坐标。可选，默认 [0, 0, 0, 0]，即全屏。  
    四个值分别为 [x, y, w, h]。

- `template`: *string* | *list<string, >*  
    模板图片路径，绝对、相对均可。必选。

- `threshold`: *double* | *list<double, >*  
    模板匹配阈值。可选，默认 0.7 。  
    若为数组，长度需和 `template` 数组长度相同。

- `method`: *int*  
    模板匹配算法，即 cv::TemplateMatchModes。可选，默认 5 。  
    仅支持 1、3、5，可简单理解为越大的越精确，但也会更慢。  
    详情请参考 [OpenCV 官方文档](https://docs.opencv.org/4.x/df/dfb/group__imgproc__object.html)。

- `green_mask`: *bool*  
    是否进行绿色掩码。可选，默认 false。  
    若为 true，可以将图片中不希望匹配的部分涂绿 RGB: (0, 255, 0)，则不对绿色部分进行匹配。

### `OCR`

文字识别。  

该任务属性需额外部分字段：

- `roi`: *array<int, 4>* | *list<array<int, 4>>*  
    同 `TemplateMatch`.`roi`

- `text`: *string* | *list<string, >*  
    要匹配的文字，支持正则。必选（除非通过接口单独设置）。

- `replace`: *array<string, 2>* | *list<array<string, 2>>*  
    部分文字识别结果不准确，进行替换。可选。

- `only_rec`: *bool*  
    是否仅识别（不进行检测，需要精确设置 `roi`）。可选，默认 false。

### `Custom`

执行通过 `MaaRegisterCustomRecognizer` 接口传入的识别器句柄  

该任务属性需额外部分字段：

- `custom_recognizer`: *string*  
    任务名，同 `MaaRegisterCustomRecognizer` 接口传入的识别器名。必选。
- `custom_recognizer_param`: *any*  
    任务参数，任意类型，会在执行时透传（。可选，默认空 json，即 `{}`

## 动作类型

### `DoNothing`

什么都不做。

### `Click`

点击。  

该任务属性需额外部分字段：

- `target`: *true* | *string* | *array<int, 4>*  
    点击的位置。可选，默认 true。  
        - *true*: 点击本任务中刚刚识别到的目标。  
        - *string*: 填写任务名，点击之前执行过的某任务识别到的目标。  
        - *array<int, 4>*: 点击固定坐标区域内随机一点，[x, y, w, h]，若希望全屏可设为 [0, 0, 0, 0]。

- `target_offset`: *array<int, 4>*  
    在 `target` 的基础上额外移动再点击，四个值分别相加。可选，默认 [0, 0, 0, 0]。

### `Swipe`

滑动。  

该任务属性需额外部分字段：

- `begin`: *true* | *string* | *array<int, 4>*  
    滑动起点。可选，默认 true。值同上述 `Click`.`target`

- `begin_offset`: *array<int, 4>*  
    在 `begin` 的基础上额外移动再作为起点，四个值分别相加。可选，默认 [0, 0, 0, 0]。

- `end`: *true* | *string* | *array<int, 4>*  
    滑动终点。必选。值同上述 `Click`.`target`

- `end_offset`: *array<int, 4>*  
    在 `end` 的基础上额外移动再作为终点，四个值分别相加。可选，默认 [0, 0, 0, 0]。

- `duration`: *uint*  
    滑动持续时间，单位毫秒。可选，默认 200

### `Key`

按键。  

- `key`: *string* | *int* | *list<int, >*  
    要按的键，仅支持 ascii。

### `StartApp`

启动 App。  

该任务属性需额外部分字段：

- `package`: *string*  
    启动入口。可选，默认空。  
    需要填入 activity，例如 `com.hypergryph.arknights/com.u8.sdk.U8UnityContext`  
    若为空，将启动 `MaaControllerSetOption` - `MaaCtrlOption_DefaultAppPackageEntry` 设置的入口。

### `StopApp`

关闭 App。  

该任务属性需额外部分字段：

- `package`: *string*  
    关闭要关闭的程序。可选，默认空。  
    需要填入 package name，例如 `com.hypergryph.arknights`  
    若为空，将关闭 `MaaControllerSetOption` - `MaaCtrlOption_DefaultAppPackage` 设置的 APP。

### `StopTask`

停止当前任务链（MaaPostTask 传入的单个任务链）

### `Custom`

执行通过 `MaaRegisterCustomAction` 接口传入的动作句柄  

该任务属性需额外部分字段：

- `custom_action`: *string*  
    任务名，同 `MaaRegisterCustomAction` 接口传入的动作名。必选。
- `custom_action_param`: *any*  
    任务参数，任意类型，通过 MaaCustomRecognizerAPI 传入 json string。可选，默认空 json，即 `{}`

## 等待画面静止

等待画面静止。需连续一定时间 画面 **没有较大变化** 才会退出动作。  

字段值为 uint 或 object，举例：

```jsonc
{
    "TaskA": {
        "pre_wait_freezes": 500,
    },
    "TaskB": {
        "pre_wait_freezes": {
            // more properties ...
        },
    },
}
```

若值为 object，可设置部分额外字段：  

- `time`: *uint*  
    连续 `time` 毫秒 画面 **没有较大变化** 才会退出动作。可选，默认 1。

- `target`: *true* | *string* | *array<int, 4>*  
    等待的目标。可选，默认 true。值同上述 `Click`.`target`

- `target_offset`: *array<int, 4>*  
    在 `target` 的基础上额外移动再作为等待目标，四个值分别相加。可选，默认 [0, 0, 0, 0]。

- `threshold`: *double*  
    判断“没有较大变化”的模板匹配阈值。可选，默认 0.95 。  

- `method`: *int*  
    判断“没有较大变化”的模板匹配算法，即 cv::TemplateMatchModes。可选，默认 5 。  
    同 `TemplateMatch`.`method`。

## 任务通知

TODO