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

doc/AI_CONSOLE.md

@@ -184,7 +184,7 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage,
 从本轮**成功**的步骤轨迹里提炼命名动作（如「打开抖音」）。硬约束：
 
 - **禁坐标**：带 `click_xy` 的步骤不会被沉淀（坐标换个设备/分辨率就失效）
-- 白名单步骤类型（18 种去掉 `click_xy`、`keep_screen`）
+- 白名单步骤类型（20 种去掉 `click_xy`、`keep_screen`）
 - 每类型有必填参数校验（如 `click` 必须有选择器）
 - 输入/产出限量：最多 10 步输入、最多 3 个动作 × 4 步
 - 保存时服务端**再校验一次**，含坐标的提交直接 400

doc/AI_TASK_GEN.md

@@ -9,7 +9,7 @@
 
 平台已有两套能力，但互不相通：
 - **AI 控制台**：一句话 + 选设备 → 多模态 Agent（DeepSeek）通过 20 个 `de_*` 工具在手机上「边看边做」（截图看屏、`de_ui_tree` 拿元素树、`de_tap_element/de_tap_text` 语义点按），流式回放步骤。
-- **任务系统 + 步骤编辑器**：`generic_steps` 任务 = 一棵可嵌套步骤树（open_app/click/swipe/loop/group/if_el…18 种节点），在编辑器里拖拽编排、单步试跑、定时调度。
+- **任务系统 + 步骤编辑器**：`generic_steps` 任务 = 一棵可嵌套步骤树（open_app/click/swipe/loop/group/if_el…20 种节点），在编辑器里拖拽编排、单步试跑、定时调度。
 
 目标：让**非工程用户用一句自然语言需求**（例：「创建一个每日养号刷视频的任务，每天 8:00-9:00 在 100.100.10.13 跑」）得到**一条可直接调度、可继续在现有步骤编辑器里手改的任务**。AI 先自己在设备上打开 App、看 UI 树、确认可点元素，再直接撰写编辑器的步骤 JSON。
 

doc/NOTIFY.md

@@ -52,6 +52,7 @@ daemon 线程。所以：
 | 任务批次 | `task.batch.started` · `.finished` · `.no_device` · `.unknown_type` · `task.cron.stopped` |
 | 任务·单设备 | `task.device.success` · `.failed` · `.offline` · `.error` · `.retry` · `.stopped` · `.preempted` · `.preempt_timeout` · `.released` |
 | 业务 | `task.selector.invalid`（选择器连续 10 次未命中——"任务成功但什么都没做"的隐蔽故障） |
+| 业务·任务自己发 | `task.notify.custom`（步骤「发通知」）/ `task.patrol.hit`（任务「公共巡检」命中）——**标题正文由任务自己写**，见下 |
 | Worker | `worker.connected` · `.attempt.done` · `.attempt.error`（单次尝试级，噪音大，默认没人勾） |
 | 设备 | `device.online` · `.offline` · `.discovered` · `.claimed` · `device.heartbeat_timeout` |
 | 安装 | `apk.install.started` · `.finished` |
@@ -91,6 +92,20 @@ daemon 线程。所以：
 单设备事件里的设备一律**显示名字**（`cs1`）而不是地址；只有设备没命名时才退回 IP。
 `型号` 取自设备池的快照（后台统一采集的那份），比 worker 每次连接时现采的稳。
 
+**任务自己发的通知**（两种，文案都由任务侧提供）：
+
+| 事件 | 谁发 | 文案从哪来 |
+|---|---|---|
+| `task.notify.custom` | 步骤「发通知」 | 步骤参数 `title` / `message` |
+| `task.patrol.hit` | 任务「公共巡检」命中 | 巡检项 `title` / `message`（留空则用默认：`巡检命中：<巡检名>` + 检查结果） |
+
+- 两者都支持占位符 `{device}` `{serial}` `{job}` `{time}` `{app}` `{screen}`
+  （见 [TASK_DEV.md](TASK_DEV.md) §4.5；`{app}`/`{screen}` 要查设备，不用就别写）。
+- **给了 `title` 就用它做消息标题**（不再拼"任务通知：" 前缀），`level` 字段可点名级别
+  （`info`/`success`/`warning`/`error` → 决定 emoji，默认按事件名猜）。
+- 谁能收到仍然只看 webhook 的**事件订阅**：想让某个群收任务自定义消息，就在那条
+  webhook 上勾 `task.notify.custom` / `task.patrol.hit`。
+
 ---
 
 ## 4. 配置

doc/README.md

@@ -13,7 +13,7 @@
 | [ARCHITECTURE.md](ARCHITECTURE.md) | **架构详解**：分层、启动装配顺序、线程与并发模型、设备生命周期、任务调度链路、状态机、关键设计决策与扩展点 | 所有开发者（先读这篇） |
 | [DATA_MODEL.md](DATA_MODEL.md) | **数据模型**：SQLite 表与字段、schema 迁移、非模型表、`app_meta` 配置键、数据目录、备份覆盖清单 | 后端开发、运维 |
 | [API.md](API.md) | **HTTP 接口全量**：按蓝图分组的路由表、鉴权、请求/响应示例、非 JSON 响应、错误分支 | 前端开发、外部接入 |
-| [TASK_DEV.md](TASK_DEV.md) | **任务与步骤开发**：TaskType/TaskJob 概念、18 种步骤全表、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
+| [TASK_DEV.md](TASK_DEV.md) | **任务与步骤开发**：TaskType/TaskJob 概念、20 种步骤全表、公共巡检、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
 | [MCP.md](MCP.md) | **MCP 手机控制手册**：20 个 `de_*` 工具用法、写操作门控、坐标换算、接入示例 | 接入方、数字员工 |
 | [MCP_DESIGN.md](MCP_DESIGN.md) | **MCP 设计文档**：边界划分、错误码、白名单/审计设计、演进方向 | 平台开发者 |
 | [AI_CONSOLE.md](AI_CONSOLE.md) | **AI 控制台**：会话/SSE、经验库、动作库、巡检、Markdown 渲染、推理链、token 统计 | 使用者、平台开发者 |

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` 支持的值