Merge branch 'feat/task-patrol'——任务级公共巡检（含与拟人滑动的合并：import、能力表两处冲突已解）

doc/TASK_DEV.md

@@ -10,8 +10,8 @@
 
 - [1. 核心概念](#1-核心概念)
 - [2. 通用步骤任务 generic_steps](#2-通用步骤任务-generic_steps)
-- [3. 18 种步骤全表](#3-18-种步骤全表)
-- [4. 容器步骤与公共参数](#4-容器步骤与公共参数)
+- [3. 20 种步骤全表](#3-20-种步骤全表)
+- [4. 容器步骤与公共参数](#4-容器步骤与公共参数)（含 [4.5 公共巡检](#45-公共巡检任务级独立于步骤画布)）
 - [5. 选择器与元素定位](#5-选择器与元素定位)
 - [6. 自定义动作](#6-自定义动作)
 - [7. 步骤编辑器（前端）](#7-步骤编辑器前端)
@@ -108,7 +108,7 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 
 ---
 
-## 3. 18 种步骤全表
+## 3. 20 种步骤全表
 
 > 参数与默认值以 `tasks/generic/task.py` 为准；前端 `STEP_LIB`（`static/admin/editor.js`）负责在编辑器里呈现这些字段。
 
@@ -131,7 +131,9 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 | 15 | `wait` | 等待 | — | `min`(1.0)、`max`(3.0)、`vary_pace`(False) | — | 随机时长；**分片 sleep**（每 ≤0.5s 检查停止/超时），可被抢占打断；勾了 `vary_pace` 再按**本设备节奏**缩放 0.8~1.35 倍（批量跑时设备之间会逐渐错开） |
 | 16 | `loop` | 循环块 | — | `loop_mode`("rounds")、`max_iterations`(10)、`loop_duration`(600) | `children` | 见 §4.1 |
 | 17 | `group` | 动作组 | — | — | `children` | 子步骤**按序执行一次**（不循环）；自定义动作拖入画布就是展开成 group |
-| 18 | `if_el` | 条件判断 | `selector_type`、`selector_value`、`timeout`(3) | `ocr_click`(False) | `then` / `else` | 见 §4.2 |
+| 18 | `if_el` | 条件判断 | `selector_type`、`selector_value`、`timeout`(3) | `ocr_click`(False) | `then` / `else` | 见 §4.2；条件类型除元素/OCR 外还支持 **屏幕状态**、**前台App** |
+| 19 | `notify` | 发通知 | — | `title`("")、`message`("")、`level`("info") | — | 推一条**自定义**通知（事件 `task.notify.custom`）：标题正文自己写，支持 `{device} {serial} {job} {time} {app} {screen}`；谁收到取决于 webhook 的事件订阅。两者都空则跳过 |
+| 20 | `stop_self` | 停止本设备 | — | `reason`("") | — | 只停**本设备**的任务（其它设备照跑）：置 worker 停止位，后续步骤不再执行，任务记成**被停止而不是失败**（不触发重试） |
 
 ---
 
@@ -149,7 +151,11 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 
 ### 4.2 `if_el` 条件判断
 
-- 先做元素判断：命中 → 执行 `then` 分支；未命中 → 执行 `else` 分支（分支都可继续嵌套）
+- 先做判断：命中 → 执行 `then` 分支；未命中 → 执行 `else` 分支（分支都可继续嵌套）
+- **`selector_type` 还支持两类非元素条件**（只有条件判断有，别的带选择器的步骤没有）：
+  - `screen` —— 屏幕状态，`selector_value` 填 `off` / `on`（也认 `熄屏`/`灭屏`）：读 `dumpsys power` 的 `mWakefulness`；
+  - `foreground` —— 前台是不是某个包名，`selector_value` 填包名（如 `com.ss.android.ugc.aweme`）。
+  - 这两类**不参与「选择器健康」统计**（它们不是选择器，不该攒出「连续未命中」告警），也不吃 `timeout`（只看当前状态，不等待）
 - `selector_type="ocr"` 时改用 **OCR**：截屏 → `find_on_screen(img, selector_value)` 子串匹配；命中且 `ocr_click=true` 会点击命中位置。
   - OCR 模式下 **`timeout` 不生效**（单次截图即判定）
   - OCR 不可用（未装 `rapidocr_onnxruntime`）时该步返回 `None`（不判定）
@@ -170,6 +176,65 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 
 ---
 
+### 4.5 公共巡检（任务级，独立于步骤画布）
+
+任务运行期间**要全程盯着的条件**（熄屏就点亮、掉到桌面就通知、刷到广告就停），
+配在任务编辑器的「公共巡检」块里，**不进步骤画布**。权威实现在 `core/patrol.py`。
+
+| | 步骤（`params.steps`） | 公共巡检（`params.watchers`） |
+|---|---|---|
+| 配置位置 | 步骤画布，拖出来的 | 任务编辑器单独一块 |
+| 执行方式 | 顺序执行 | **穿插**：每执行完一步、以及长等待的每个分片，看一眼"哪个巡检到点了" |
+| 适合 | 一段固定流程 | 全程都要盯的守护条件 |
+
+为什么穿插而不是另起线程：不需要并发模型，也**不会和主流程抢屏幕**（否则巡检点屏幕、
+主流程同时也在点，动作互相打断）。代价是**精度受步长影响**——某一步卡 30 秒，
+巡检最多晚 30 秒。
+
+配置结构（`params.watchers` 数组，每项）：
+
+```json
+{"name": "熄屏点亮", "enabled": true, "interval": 60,
+ "check": "screen_off",
+ "selector_type": "xpath", "selector_value": "",
+ "action": "screen_on",
+ "notify": true, "title": "{device} 熄屏了",
+ "message": "任务 {job} 在 {time} 发现 {screen}，已点亮",
+ "cooldown": 300}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `interval` | 检查间隔（秒，最小 5）。**首次检查在任务开始时立刻做一次**，之后按间隔 |
+| `check` | `screen_off` 屏幕熄灭 / `screen_on` 屏幕亮着 / `element_exists` 元素存在 / `element_missing` 元素不存在 / `foreground_is` 前台是该App / `foreground_not` 前台不是该App |
+| `selector_type`/`selector_value` | 元素类检查填选择器；`foreground_*` 填**包名**；屏幕类不用填 |
+| `action` | `none` 只发通知 / `screen_on` 点亮屏幕 / `screen_off` 熄灭屏幕 / `stop_self` 停止本设备任务 |
+| `notify` | 命中是否推通知（事件 `task.patrol.hit`，见 [NOTIFY.md](NOTIFY.md)）；`false` 就只做动作 |
+| `title`/`message` | 通知标题正文，可用 `{device}` `{serial}` `{job}` `{time}` `{app}` `{screen}`。**文案在动作之前渲染**，所以写的是"发现熄屏，已点亮"而不是"发现亮屏" |
+| `cooldown` | 命中后多少秒内不再重复动作/通知（默认 300）。**条件持续成立时（一直熄屏）靠它防刷屏** |
+
+两个能直接抄的例子：
+
+```jsonc
+// 1) 熄屏就点亮（不吵人）：每分钟看一眼，熄了就点亮
+{"name":"熄屏点亮","interval":60,"check":"screen_off","action":"screen_on","notify":false}
+
+// 2) 掉出抖音就通知 + 停本设备：前台不是抖音 → 通知 → 停下来等你处理
+{"name":"掉出抖音","interval":60,"check":"foreground_not","selector_value":"com.ss.android.ugc.aweme",
+ "action":"stop_self","notify":true,"title":"{device} 掉出抖音了",
+ "message":"当前前台 {app}，已停止本设备任务"}
+```
+
+要点与坑：
+
+- **巡检不是步骤**：不要试图在画布上找它；它也不计入"已执行 N 次操作"的进度。
+- 一次检查要查设备：屏幕 `0.3s`、前台 `0.7s`，**元素检查要 dump UI 树（慢设备上可能几秒）**。
+  所以 `interval` 别设太小（元素检查建议 ≥30s）。
+- 巡检命中会往「日志 → 步骤明细」记一行（`step_type=patrol`，只记命中不记"没事发生"）。
+- 巡检内部异常只记日志、**绝不影响任务主流程**（同 `notifier.notify` 的口径）。
+
+---
+
 ## 5. 选择器与元素定位
 
 ### 5.1 `selector_type` 支持的值