Merge branch 'dev'——录制手势纯轨迹回放（手机 getevent 真手指录制）

用户反馈：录制出来的滑动又被套上滑动那套逻辑（方向/幅度/拟人重新生成），
"导致滑动还是不顺畅"。录制就该是录制——按录下的路径与时间原样重放。

- 新步骤 `gesture`「录制手势」：存完整轨迹点列 `[[x,y,t_ms],…]`，
  回放时原样交给设备（`d.swipe_points(points, duration)`），不做任何加工。
  与 `swipe` 是两套东西（滑动是参数化的，录制是点列）。
- core/gesture.py（新）：
  · 手机端录制 `PhoneRecorder`：`getevent` 读**真触屏**设备（自动挑 fts_ts 这类、
    排除 uinput/vitural-sar 等合成节点），解析两套协议（BTN_TOUCH / ABS_MT_TRACKING_ID）；
    **合成的注入事件不会出现在真触屏节点上**（实测），所以录到的只有人手的动作；
  · 点列清洗：按 ≥16ms 抽稀但**末点必留**（快划时不能把收尾丢了）；
  · 回放**一次调用**而不是逐点注入：实测这台设备单次触摸 RPC ≈190ms，
    逐点回放 20 点要 3.8 秒——只能让设备自己插值，"时间"由点密度还原。
- 接口：POST /api/gesture/record/{start,stop}（需设备权限；重复开始返回 409）。
- 「录制手势」步骤卡片：录到就回填（手机上录 / 网页上录），显示点数/时长；
  **滑动步骤上的「录制手势」按钮已移除**（按用户要求，录制不再走滑动逻辑）。
- 录制前自动唤醒设备：**息屏时 u2 抓 UI 树会从 3 秒退化到 65 秒**（实测），
  截图也是黑的——这是本次排查最耗时的坑，已写进文档。

自测：假设备单测（点列/时长/抽稀/失败退回直线，10 项）；
无头浏览器 + CDP 真模拟拖动 → 录到 14 点/605ms 并按实际轨迹回填；
手机录制接口起停/重复拦截；
真机回放：用录下的轨迹跑任务 → 步骤 `gesture ok`。
⚠️ 手机端"真手指轨迹"这一段需要人真的去划才能端到端验证（我没有手指）。
文档：TASK_DEV §3.2（两套东西对比 + 三个坑）、步骤表 21 种、API、README。

.env.example

@@ -7,6 +7,33 @@
 #   - 完整说明见 doc/DEVELOPMENT.md §4 配置速查、doc/DEPLOY.md §2.2
 # ==============================================================================
 
+# ==================== 数据库 ====================
+# 平台用 MySQL（正式用法）。DEPLOY_ENV 声明"这份配置连的是哪个环境的库"，
+# 并与库名一一绑定，启动时会互相校验，不符直接拒绝启动：
+#   DEPLOY_ENV=dev  →  期望库名 auto_control_dev（本地开发，可随意折腾）
+#   DEPLOY_ENV=prod →  期望库名 auto_control    （正式数据）
+# 首次连接的库会被打上环境标签（app_meta.deployment_env）；标签与 DEPLOY_ENV
+# 不符时拒绝启动——这是防止「开发配置连到生产库」的最后一道闸。
+DEPLOY_ENV=dev
+DB_HOST=
+DB_PORT=3306
+DB_USER=
+DB_PASSWORD=
+DB_NAME=auto_control_dev
+# 排序规则用 _bin（逐码点比较，等价 SQLite 的大小写敏感语义），别改成 _general_ci
+DB_CHARSET=utf8mb4
+DB_COLLATION=utf8mb4_bin
+
+# 完整连接串：优先级最高，用于脚本临时指向别的库（一般不用配）
+# DATABASE_URL=mysql+pymysql://user:pass@host:3306/auto_control_dev?charset=utf8mb4
+
+# 逃生阀（默认关，仅在明确知道后果时打开）
+#   DB_ALLOW_ENV_MISMATCH=1     环境与库名/库标签不符时仍启动（危险）
+#   DB_ALLOW_SQLITE_FALLBACK=1  生产环境 DB_HOST 为空时允许回退 SQLite（回滚用）
+# DB_ALLOW_ENV_MISMATCH=0
+# DB_ALLOW_SQLITE_FALLBACK=0
+
+
 # ==================== Web 服务 ====================
 # 会话密钥【必须，生产务必固定】：不配则每次启动随机生成，重启后登录态失效。
 # 生成：python -c "import secrets; print(secrets.token_hex(32))"

.gitignore

@@ -10,8 +10,11 @@ env/
 
 # 运行时数据
 logs/*.log
+data/*.log
 data/apks/*.apk
 data/*.migrated
+# uiauto.pid 之类的运行时 PID 文件（**注释必须单独一行**：gitignore 不支持行尾注释）
+data/*.pid
 data/*.db-shm
 data/*.db-wal
 
@@ -37,8 +40,11 @@ desktop.ini
 *.bak
 
 # 密钥/环境变量（真实 .env 含 token/密钥，绝不提交）
+# .env.* 一并忽略：改配置前留的 .env.bak_xxx / .env.old 同样含生产密钥，
+# 220 上就出现过一次（2026-09-13 切 MySQL 时的备份），差点被 git add . 带进去。
 .env
-.env.local
+.env.*
+!.env.example
 
 
 bin/adb/*

README.md

@@ -46,13 +46,18 @@
 | **多设备并发任务** | 每设备一个 Worker 线程；同一设备同时只跑一个任务（可配置"抢占"打断其他任务） |
 | **设备池** | SQLite 清单 + adb 在线状态；支持手工添加、网段自动发现、一键重连、型号采集、启用/停用 |
 | **任务调度** | 手动 / cron 定时 / 定时启停；运行窗口；失败重试（含端口耗尽类的长退避） |
-| **步骤编辑器** | 可视化拖拽编排 18 种步骤（含循环/条件/OCR），可打包成"自定义动作"复用 |
+| **步骤编辑器** | 可视化拖拽编排 21 种步骤（含循环/条件/OCR/通知/录制回放），可打包成"自定义动作"复用 |
+| **拟人化操作** | 滑动默认走弧线轨迹、位置/幅度/时长每次抖动，且**每台设备有自己的手速与习惯**（同设备风格稳定、设备之间明显不同）——批量跑时不像同步机器人（见 [TASK_DEV.md](doc/TASK_DEV.md) §8.4） |
+| **录制回放** | 「录制手势」步骤 = **纯录制**：**用手指在真机上划**（读 getevent 真触屏）或在网页画面上拖，把轨迹点列原样存下来，回放时**照原路径与时长重放**——不套滑动那套方向/幅度/拟人参数 |
+| **动作配置 / 录制** | 「任务 → 动作配置」：① 配**步骤默认值**（新建步骤预填：滑动时长/幅度/抖动/拟人、点击超时、等待区间…）② **录制动作**——在设备画面上点/划/按键，自动翻译成步骤（点元素记选择器、划一下记方向/幅度/时长），可存成可复用动作，也可只取一个手势回填滑动步骤 |
+| **公共巡检** | 任务级的守护条件（**独立于步骤画布**）：每 N 秒检查屏幕亮/熄、元素在不在、前台是不是某 App，命中就点亮/息屏/停本设备/推通知——通知标题正文自己写（见 [TASK_DEV.md](doc/TASK_DEV.md) §4.5） |
 | **元素抓取** | 拉取设备 UI 元素树 → 点选回填选择器；支持"点一下"与"测选择器"真机验证 |
 | **实时看屏** | MJPEG 实时流 + 点击/滑动/按键/文字输入；全屏监控大屏（`/wall`） |
 | **应用管理** | APK 上传/解析/批量安装；设备已装应用与版本查询；剪贴板注入 |
 | **AI 控制台** | 用自然语言驱动 AI 操作指定设备（MCP 工具 + 截图），流式输出、Markdown 渲染、推理链折叠、token 统计；成功操作自动沉淀「经验库 / 动作库」并在相似任务中召回 |
-| **MCP 接入** | 19 个 `de_*` 工具，把手机控制开放给外部 AI；写操作有开关、设备忙时拒绝、全量审计 |
+| **MCP 接入** | 20 个 `de_*` 工具，把手机控制开放给外部 AI；写操作有开关、设备忙时拒绝、全量审计 |
 | **备份导出/导入** | 一键导出 zip（库快照 + manifest + 可选 APK），导入前校验预览、自动预备份、重启生效 |
+| **通知 / Webhook** | 任务成功失败、设备上下线、安装完成、备份恢复等事件推送到企业微信 / 钉钉 / 飞书 / Bark / 自建服务（Slack 用通用 JSON）；多条 webhook 各自订阅；聚合+限流防刷屏（见 [doc/NOTIFY.md](doc/NOTIFY.md)） |
 
 ---
 
@@ -120,6 +125,7 @@ auto_control/
 │   ├── tailscale_api.py       #   Tailscale 管理（改名/授权/密钥/IP/auth key）
 │   ├── agent_api.py           #   AI 控制台（会话/SSE/经验库/动作库/巡检）
 │   ├── system_api.py          #   系统数据备份导出/导入
+│   ├── notify_api.py          #   通知 / Webhook 配置（系统 Tab）
 │   ├── common.py              #   跨模块共享工具（合并设备列表、屏幕状态）
 │   └── context.py             #   共享对象注入（mgr / apk_mgr / device_pool）
 │
@@ -136,6 +142,11 @@ auto_control/
 │   ├── clipboard_helper.py    #   剪贴板注入（ClipInject 通道）
 │   ├── apk_manager.py         #   APK 上传/解析/批量安装
 │   ├── system_backup.py       #   数据备份导出/导入（重启生效）
+│   ├── humanize.py            #   拟人化：弧线滑动/抖动 + 每台设备的"手感"（按 serial 播种）
+│   ├── notifier.py            #   通知分发（队列/聚合/限流/适配器）+ notify_events.py 事件目录
+│   ├── step_log.py            #   任务步骤明细（异步写线程 + 保留期清理）
+│   ├── patrol.py              #   任务级公共巡检（检查项/动作注册表，穿插执行）
+│   ├── step_defaults.py       #   步骤默认值（app_meta 单键，出厂值 + 用户覆盖）
 │   ├── tailscale_client.py    #   Tailscale API v2 客户端
 │   ├── ssh_client.py          #   SSH 封装（当前无人调用，预留）
 │   ├── logger.py              #   分文件日志（core/task/web/action）
@@ -144,9 +155,9 @@ auto_control/
 ├── tasks/                     # 任务定义层
 │   ├── base.py                #   BaseTask + _TASK_TYPES + register_task
 │   └── generic/               #   通用步骤任务（task_type=generic_steps，当前唯一类型）
-│       └── task.py            #     STEP_TYPES（18 种步骤）+ Worker + 执行器
+│       └── task.py            #     STEP_TYPES（21 种步骤）+ Worker + 执行器
 │
-├── mcp_server/                # MCP Server（19 个 de_* 工具，:8033）
+├── mcp_server/                # MCP Server（20 个 de_* 工具，:8033）
 │   ├── mcp_server.py          #   工具定义 + 平台登录 + 门控
 │   ├── platform_client.py     #   平台 HTTP 客户端（复用 Web 账号）
 │   ├── direct_ops.py          #   直连设备的 adb/u2 操作
@@ -162,7 +173,7 @@ auto_control/
 │   ├── monitor.html           #   主单页应用（7 个顶级 Tab + 模态框 + 内联样式）
 │   ├── login.html             #   登录页
 │   └── wall.html              #   监控大屏（独立页面，自包含）
-├── static/admin/              # 前端 JS（11 个文件，按顺序同步加载，见下）
+├── static/admin/              # 前端 JS（13 个文件，按顺序同步加载，见下）
 ├── static/fonts/              # 自托管字体（Bricolage Grotesque + IBM Plex Mono）
 │
 ├── data/                      # 运行时数据（不入 git）
@@ -181,7 +192,7 @@ auto_control/
 
 ```
 base.js → markdown.js → list.js → monitor.js → editor.js → tasks.js
-        → tools.js → apps.js → admin.js → agent.js → system.js
+        → tools.js → apps.js → admin.js → agent.js → taskgen.js → system.js → notify.js → steplog.js → recorder.js
 ```
 
 ---
@@ -242,8 +253,8 @@ self.set_progress(done=5, total=80, unit="视频", action_counts={"like": 3}, el
 | Tab | 内容 | 可见性 |
 |-----|------|--------|
 | **监控** | 统计卡片 + 设备表（在线/型号/任务状态/进度/前台 App/最近错误，支持排序、搜索、分页、多选批量操作）+ 异常汇总 + **任务运行概况**（每张任务卡：执行任务 / 停用任务 + 覆盖设备彩色 chip）；导航栏「📺 大屏」打开 `/wall` | 所有登录用户（设备操作按钮需"设备控制"） |
-| **任务** | 子分栏：**任务计划**（CRUD / 启停 / 执行 / 下次运行时间 / 离线跳过 / 步骤编辑器）、**自定义动作**（步骤打包复用） | 可看；写操作需"任务管理" |
+| **任务** | 子分栏：**任务计划**（CRUD / 启停 / 执行 / 下次运行时间 / 离线跳过 / 步骤编辑器 / **公共巡检**）、**自定义动作**（步骤打包复用）、**动作配置**（步骤默认值 + 录制动作） | 可看；写操作需"任务管理" |
-| **日志** | 实时日志（按文件切换、可自动刷新） | 需"日志查看" |
+| **日志** | 子分栏：**文件日志**（文件切换含滚动历史、关键字/级别/时间过滤、命中高亮、下载筛选结果、自动刷新）、**步骤明细**（按设备/任务/结果/时间过滤、按运行归组的概览、导出 CSV） | 需"日志查看" |
 | **用户** | 用户 CRUD、改密、分配权限 | 仅管理员 |
 | **工具** | 8 个子分栏：剪贴板注入 / adb 远程终端 / Tailscale 管理 / 应用管理 / 应用版本管理 / 设备已装应用 / **设备池管理**（含自动发现）/ 设备分组 | 仅管理员 |
 | **AI 控制台** | 会话列表 + 对话区（Markdown 渲染、推理链折叠、token 统计）+ 实时画面（MJPEG）+ 目标设备选择；右上角：经验库 / 动作库 / 模型配置 | 仅管理员 |
@@ -270,7 +281,7 @@ self.set_progress(done=5, total=80, unit="视频", action_counts={"like": 3}, el
 
 `generic_steps` 的执行内容全在 `params.steps`（JSON 数组），由步骤编辑器产出。**没有默认步骤**——空步骤任务执行时会明确报错。
 
-**18 种步骤**（完整参数见 [doc/TASK_DEV.md](doc/TASK_DEV.md)）：
+**21 种步骤**（完整参数见 [doc/TASK_DEV.md](doc/TASK_DEV.md)）：
 
 | 类别 | 步骤 |
 |------|------|
@@ -304,7 +315,7 @@ self.set_progress(done=5, total=80, unit="视频", action_counts={"like": 3}, el
 
 ### MCP（外部 AI 接入）
 
-MCP Server 监听 `:8033`，暴露 19 个 `de_*` 工具（截屏、点击、滑动、输入、OCR、元素树、应用管理等）。写操作需 `MCP_ALLOW_WRITE=1`；设备正在跑任务时拒绝（`device_busy`）；每次调用写审计日志。
+MCP Server 监听 `:8033`，暴露 20 个 `de_*` 工具（截屏、点击、滑动、输入、OCR、元素树、应用管理等）。写操作需 `MCP_ALLOW_WRITE=1`；设备正在跑任务时拒绝（`device_busy`）；每次调用写审计日志。
 
 ```bash
 # 本机手动启动（生产容器由 scripts/start.sh 自动拉起）
@@ -347,13 +358,23 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 | `logs/task.log` | `task.*` | 任务执行（worker 业务逻辑） |
 | `logs/web.log` | `web.*` | Web 请求与管理操作 |
 | `logs/action.log` | `action.*` | 操作执行 |
+| `logs/notify.log` | `notify` | 通知发送（成功/失败/平台错误码） |
 
 ```python
 from core.logger import get_logger
 log = get_logger("task.generic")   # → logs/task.log
 ```
 
-「日志」Tab 可在线查看。
+「日志」Tab 可在线查看：文件下拉包含 `.1/.2…` 滚动历史（可回溯更早的日志），
+支持关键字（命中高亮）/最低级别/时间范围过滤，点「下载」导出当前筛选结果
+（无筛选就是整个文件）。读取逻辑在 `core/logger.py` 的 `list_log_files()/query_log()/
+read_log_text()`，`file` 参数走白名单，不接受任意路径。
+
+「日志 → 步骤明细」是**结构化**的另一半：每一次步骤执行落一行 `task_step_log`
+（设备/任务/步骤路径/结果/耗时/选择器），因此能按设备、任务、结果、时间过滤，
+也能按 `run_id` 归组看"这一次运行为什么失败"、导出 CSV。写入是异步的
+（`core/step_log.py`，任务线程只入队，不阻塞执行），保留 14 天、单次运行最多
+2000 条 —— 这两个上限决定这张表（以及备份包）能长多大。
 
 ---
 
@@ -382,7 +403,7 @@ log = get_logger("task.generic")   # → logs/task.log
 | [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) | 架构详解（分层、装配顺序、线程模型、设备生命周期、调度链路、设计决策） |
 | [doc/DATA_MODEL.md](doc/DATA_MODEL.md) | 数据模型（表结构、迁移、`app_meta`、数据目录、备份覆盖清单） |
 | [doc/API.md](doc/API.md) | HTTP 接口全量说明 |
-| [doc/TASK_DEV.md](doc/TASK_DEV.md) | 任务与步骤开发（18 种步骤、选择器、自定义动作、新增任务类型） |
+| [doc/TASK_DEV.md](doc/TASK_DEV.md) | 任务与步骤开发（21 种步骤、公共巡检、录制回放、选择器、自定义动作） |
 | [doc/MCP.md](doc/MCP.md) · [doc/MCP_DESIGN.md](doc/MCP_DESIGN.md) | MCP 使用手册 / 设计文档 |
 | [doc/AI_CONSOLE.md](doc/AI_CONSOLE.md) · [doc/AI_TASK_GEN.md](doc/AI_TASK_GEN.md) | AI 控制台机制 / AI 建任务设计（规划） |
 | [doc/DEPLOY.md](doc/DEPLOY.md) | 部署与运维（含生产容器、备份导入、故障排查） |

config.py

@@ -47,6 +47,33 @@ else:
     # 部署后需执行 chmod +x bin/adb/adb
     ADB_PATH = os.path.join(_ADB_DIR, "adb")
 
+# ================== 数据库 ==================
+# 平台支持 MySQL（正式用法）与 SQLite（仅作回退，见 core/db_config.py）。
+#
+# DEPLOY_ENV 声明"这套配置连的是哪个环境的库"，与库名一一绑定：
+#   dev  → auto_control_dev（本地开发，可随意折腾）
+#   prod → auto_control    （正式数据）
+# 启动时会校验「.env 声明的环境」与「目标库登记的环境」是否一致，
+# 不一致直接拒绝启动——防止把开发配置连到生产库上。
+DEPLOY_ENV = _env("DEPLOY_ENV", "dev").strip().lower()
+
+DB_HOST = _env("DB_HOST", "")          # 为空则回退 SQLite（生产禁止静默回退）
+DB_PORT = int(_env("DB_PORT", "3306"))
+DB_USER = _env("DB_USER", "")
+DB_PASSWORD = _env("DB_PASSWORD", "")  # 写入 .env，不要提交到 git
+DB_NAME = _env("DB_NAME", "")
+DB_CHARSET = _env("DB_CHARSET", "utf8mb4")
+# 排序规则用 _bin（逐码点比较，等价 SQLite 的大小写敏感语义）。
+# 用默认的 utf8mb4_general_ci 会让 Admin/admin、Phone1/phone1 被判重复。
+DB_COLLATION = _env("DB_COLLATION", "utf8mb4_bin")
+
+# 完整连接串（优先级最高，迁移/回归脚本用它临时指向别的库）
+DATABASE_URL = _env("DATABASE_URL", "")
+
+# 逃生阀（默认关；仅在你明确知道自己在干什么时打开）
+DB_ALLOW_ENV_MISMATCH = _env("DB_ALLOW_ENV_MISMATCH", "0") == "1"
+DB_ALLOW_SQLITE_FALLBACK = _env("DB_ALLOW_SQLITE_FALLBACK", "0") == "1"
+
 # ================== Web 后台 ==================
 WEB_HOST = "0.0.0.0"
 # 端口必须避开 Windows 动态端口范围（本机被改成 1024-15000，默认 49152-65535）
@@ -63,9 +90,12 @@ APK_DIR = os.path.join(DATA_DIR, "apks")
 # ================== 系统数据备份（导出/导入） ==================
 # 导出 zip 与恢复前快照存放；导入暂存目录；待下次启动生效的恢复目录
 # （运行时产物，不入 git，见 .gitignore data/backups 等）
-BACKUP_DIR = os.path.join(DATA_DIR, "backups")
+#
-RESTORE_STAGING_DIR = os.path.join(DATA_DIR, "restore_staging")
+# 三个目录都支持用环境变量改到别处——自动化测试必须把恢复目录指到临时位置，
-RESTORE_PENDING_DIR = os.path.join(DATA_DIR, "restore_pending")
+# 否则测试造出来的"待生效恢复任务"会在服务下次重启时被真当成用户的操作消费掉。
+BACKUP_DIR = _env("DATA_BACKUP_DIR", "") or os.path.join(DATA_DIR, "backups")
+RESTORE_STAGING_DIR = _env("DATA_RESTORE_STAGING_DIR", "") or os.path.join(DATA_DIR, "restore_staging")
+RESTORE_PENDING_DIR = _env("DATA_RESTORE_PENDING_DIR", "") or os.path.join(DATA_DIR, "restore_pending")
 
 # ================== SSH 到部署机（已废弃，STF 相关操作退役） ==================
 # 阶段 3 后代码不再使用 SSH；保留配置仅供手动运维 220（如 docker stop stf）。

core/apk_manager.py

@@ -22,12 +22,15 @@
 import os
 import time
 import uuid
+
 import threading
 import subprocess
-from concurrent.futures import ThreadPoolExecutor, as_completed
+from concurrent.futures import (ThreadPoolExecutor, as_completed,
+                                TimeoutError as FuturesTimeout)
 
 from config import APK_DIR, ADB_PATH
 from core.logger import get_logger
+from core import notifier
 from core.models import db, ApkFile as ApkRow
 from .device_worker import get_all_worker_status
 
@@ -35,6 +38,9 @@ _log = get_logger("core.apk")
 
 # adb install 超时（秒）。大 APK 安装慢，给 5 分钟
 _INSTALL_TIMEOUT = 300
+# 分块推送"多久没有任何字节被接收"就算链路卡死（秒）。注意这是**停滞**判据，
+# 不是总时长：正常推送会不断刷新它。
+_PUSH_STALL_TIMEOUT = 90
 # 并发安装数
 _INSTALL_CONCURRENCY = 5
 
@@ -127,7 +133,7 @@ class ApkManager:
 
     # ================== 列表 ==================
     def list_all(self):
-        """列出所有 APK。"""
+        """列出所有 APK（**每个上传版本一行**，内部用）。"""
         try:
             with self._db():
                 rows = ApkRow.query.order_by(ApkRow.upload_time.desc()).all()
@@ -136,6 +142,42 @@ class ApkManager:
             _log.error(f"列出 APK 失败: {e}")
             return []
 
+    def list_latest(self):
+        """按**包名**合并后的列表：一个应用一行，只显示最新版本。
+
+        为什么：同一个应用传过多个版本（v1.2 / v1.3）时，列表里会并排出现两行——
+        用户看到的是"同一个应用怎么重复了"。这里合并成一行（最新版），
+        其余版本的信息放在 `versions` 里，界面可以提示"另有 N 个旧版本"并按需清理。
+
+        管理页和设备端商店都用这个（设备上选应用时同样不该出现两行同一个 App）。
+        解析不出包名的 APK 各自独立成行，不做合并（避免把无关文件混在一起）。
+        """
+        rows = self.list_all()
+        groups = {}
+        for r in rows:
+            pkg = (r.get("package_name") or "").strip()
+            key = pkg if pkg else ("__single__" + str(r.get("id")))
+            groups.setdefault(key, []).append(r)
+
+        def sort_key(x):
+            return (x.get("version_code") or 0, x.get("upload_time") or "")
+
+        out = []
+        for items in groups.values():
+            items.sort(key=sort_key, reverse=True)
+            top = dict(items[0])
+            top["version_count"] = len(items)
+            top["versions"] = [{
+                "id": i.get("id"),
+                "version_name": i.get("version_name") or "",
+                "version_code": i.get("version_code") or 0,
+                "size": i.get("size") or 0,
+                "upload_time": i.get("upload_time") or "",
+            } for i in items]
+            out.append(top)
+        out.sort(key=lambda x: x.get("upload_time") or "", reverse=True)
+        return out
+
     # ================== 删除 ==================
     def delete(self, apk_id):
         """删除 APK 文件和数据库记录。"""
@@ -161,6 +203,47 @@ class ApkManager:
             _log.error(f"删除 APK 失败: {e}")
             return False, str(e)
 
+    def delete_package(self, apk_id, keep_latest=False):
+        """按**包名**删除：一个应用的所有版本一起处理。
+
+        keep_latest=True → 只删旧版本、保留最新那版（"清理旧版本"）
+        keep_latest=False → 整个应用删掉（所有版本）
+        没有包名的 APK 退回单条删除。
+        """
+        try:
+            with self._db():
+                row = ApkRow.query.get(apk_id)
+                if not row:
+                    return False, "APK 不存在"
+                pkg = (row.package_name or "").strip()
+                if not pkg:
+                    return self.delete(apk_id)
+
+                items = ApkRow.query.filter_by(package_name=pkg).all()
+                items.sort(key=lambda r: ((r.version_code or 0),
+                                          (r.upload_time or "")), reverse=True)
+                targets = items[1:] if keep_latest else items
+                if not targets:
+                    return True, "没有需要清理的旧版本"
+                name = row.display_name or pkg
+                for r in targets:
+                    p = os.path.join(APK_DIR, r.filename)
+                    if os.path.exists(p):
+                        try:
+                            os.remove(p)
+                        except Exception as e:
+                            _log.warning(f"删除 APK 文件失败: {e}")
+                    db.session.delete(r)
+                db.session.commit()
+                _log.info(f"已删除 {name} 的 {len(targets)} 个版本"
+                          f"（{'保留最新' if keep_latest else '整个应用'}）")
+                if keep_latest:
+                    return True, f"已清理 {name} 的 {len(targets)} 个旧版本（保留最新）"
+                return True, f"已删除 {name}（共 {len(targets)} 个版本）"
+        except Exception as e:
+            _log.error(f"按包名删除失败: {e}")
+            return False, str(e)
+
     # ================== 批量安装 ==================
     def install(self, apk_id, serials):
         """批量安装 APK 到指定设备（后台线程执行）。
@@ -198,13 +281,26 @@ class ApkManager:
         # 获取 worker 状态（判断设备是否运行中）
         worker_status = {w["serial"]: w for w in get_all_worker_status()}
 
+        # 设备名（平台给设备起的名字，如 A08）—— 进度表里显示这个而不是型号：
+        # 8 台同型号时型号根本区分不了，名字才行
+        pool_names, fp_names = {}, {}
+        try:
+            from core import device_pool
+            # list_devices() 返回字典（含 name/fingerprint）
+            for d in device_pool.list_devices():
+                if d.get("serial"):
+                    pool_names[d["serial"]] = d.get("name") or ""
+                # USB 设备的 adb serial == ro.serialno == 池里那条记录的指纹
+                if d.get("fingerprint"):
+                    fp_names[d["fingerprint"]] = d.get("name") or ""
+        except Exception as e:
+            _log.warning(f"读取设备名失败（进度表将显示地址）: {e}")
+
         # 构造安装任务
         items = {}
         for s in serials:
-            dev = all_devices.get(s, {})
-            model = dev.get("model") or dev.get("manufacturer") or s
             items[s] = {
-                "name": model,
+                "name": pool_names.get(s) or fp_names.get(s) or s,
                 "status": "pending",
                 "msg": "",
             }
@@ -225,6 +321,8 @@ class ApkManager:
                              name="apk-install", daemon=True)
         t.start()
         _log.info(f"开始安装 {apk_name} 到 {len(serials)} 台设备")
+        notifier.notify("apk.install.started", apk_id=apk_id, apk_name=apk_name,
+                        package_name=package_name, total=len(serials))
         return True, f"开始安装 {apk_name} 到 {len(serials)} 台设备"
 
     def _install_worker(self, apk_id, apk_path, apk_name, package_name,
@@ -243,7 +341,10 @@ class ApkManager:
                   f"跳过={len(serials)-len(install_list)}")
 
         if install_list:
-            with ThreadPoolExecutor(max_workers=_INSTALL_CONCURRENCY) as pool:
+            # 不用 with（它退出时会 wait 卡住的线程）：超时后要能立刻收尾，
+            # 否则界面永远停在"安装中"，后续安装全被"已有安装任务在进行"挡住
+            pool = ThreadPoolExecutor(max_workers=_INSTALL_CONCURRENCY)
+            try:
                 futures = {pool.submit(self._install_one, s, apk_path,
                                        package_name): s
                            for s in install_list}
@@ -253,8 +354,23 @@ class ApkManager:
                         fut.result()
                     except Exception as e:
                         self._set_item(s, "failed", f"安装异常: {e}")
+            except FuturesTimeout:
+                _log.warning(f"安装任务 {apk_name}: 有设备超时未返回，先收尾")
+                for s in install_list:
+                    it = ((self._install_task or {}).get("items") or {}).get(s) or {}
+                    if it.get("status") in ("pending", "installing"):
+                        self._set_item(s, "failed", "安装超时（设备无响应）")
+            except Exception as e:
+                _log.exception(f"安装任务 {apk_name} 异常")
+                for s in install_list:
+                    it = ((self._install_task or {}).get("items") or {}).get(s) or {}
+                    if it.get("status") in ("pending", "installing"):
+                        self._set_item(s, "failed", f"安装异常: {e}")
+            finally:
+                pool.shutdown(wait=False)
 
-        # 标记完成
+        # 标记完成（**必须**落到这里：没置 finished 的安装任务会一直挂着，
+        # 让"已有安装任务正在进行"永久挡住后续安装 —— 2026-09-14 事故）
         if self._install_task:
             self._install_task["finished"] = True
         # 统计
@@ -265,6 +381,16 @@ class ApkManager:
         skipped = sum(1 for v in self._install_task["items"].values()
                       if v["status"] == "skipped")
         _log.info(f"安装完成 {apk_name}: 成功={success}, 失败={failed}, 跳过={skipped}")
+        # 通知：批量安装结束（带失败设备与原因，运维要知道哪几台没装上）
+        try:
+            items = ((self._install_task or {}).get("items") or {})
+            failed_items = [f"{v.get('name') or s}·{v.get('msg') or ''}"
+                            for s, v in items.items() if v.get("status") == "failed"][:10]
+            notifier.notify("apk.install.finished", apk_name=apk_name,
+                            success=success, failed=failed, skipped=skipped,
+                            total=len(items), failed_items=failed_items)
+        except Exception as e:
+            _log.warning(f"发送安装完成通知失败（不影响安装）: {e}")
 
     def _install_one(self, serial, apk_path, package_name=""):
         """直连设备安装 APK。
@@ -308,20 +434,17 @@ class ApkManager:
                      "verifier_verify_adb_installs", "0")
             except Exception:
                 pass
-            # 2. 推送 APK 到设备（大 APK 经 WiFi 推送较慢，超时与安装共用）
+            # 2. 推送 APK 到设备（分块 + 实时进度）
-            self._set_item(serial, "installing", "正在推送 APK...")
+            ok_push, msg_push = self._push_with_progress(serial, apk_path)
-            r = subprocess.run(
+            if not ok_push:
-                [ADB_PATH, "-s", serial, "push", apk_path, "/data/local/tmp/_install.apk"],
+                self._set_item(serial, "failed", msg_push)
-                capture_output=True, timeout=_INSTALL_TIMEOUT
+                _log.warning(f"[{serial}] APK 推送失败: {msg_push}")
-            )
-            push_out = ((r.stdout or b"") + (r.stderr or b"")).decode("utf-8", errors="replace")
-            if r.returncode != 0 or "1 file pushed" not in push_out:
-                msg = push_out.strip().replace("\n", " ")[:150] or f"推送失败(returncode={r.returncode})"
-                self._set_item(serial, "failed", msg)
-                _log.warning(f"[{serial}] APK 推送失败: {msg}")
                 return
             # 3. pm install 强制安装（-r 覆盖安装 / -t 允许测试包 / -d 允许降级版本）
-            self._set_item(serial, "installing", "正在安装...")
+            # 这一步在**设备端**解包/优化，耗时随包大小增长（抖音 336MB 实测 ~65s），
+            # 但系统没给进度接口，只能给出预期时间，别让用户以为是卡住了。
+            self._set_item(serial, "installing",
+                           "正在设备上安装...（大包要 1-2 分钟，无进度可读）")
             r = subprocess.run(
                 [ADB_PATH, "-s", serial, "shell", "pm", "install", "-r", "-t", "-d",
                  "/data/local/tmp/_install.apk"],
@@ -385,6 +508,166 @@ class ApkManager:
             # adb 连接保持即可，不影响设备和后续操作。
             pass
 
+    def _push_with_progress(self, serial, apk_path,
+                            remote="/data/local/tmp/_install.apk"):
+        """把 APK 分块写进设备，边传边更新进度。返回 (ok, msg)。
+
+        为什么不用 `adb push`：它只在**结束时**吐一行汇总
+        （"1 file pushed, 3.0 MB/s"），大包（抖音 336MB ≈ 1.8 分钟/台）整个传输过程
+        界面上只有一句"正在推送 APK..."，用户只能干等 —— 这就是要优化的问题。
+
+        改用 `exec-in` 分块写：每块回调一次进度（百分比/已传/速度/剩余时间）。
+        实测速度略降（2.6 vs 3.1 MB/s），换来看得见的进度，划算。
+        传完校验设备上的文件大小；exec-in 不可用时退回原来的 `adb push`。
+        """
+        total = os.path.getsize(apk_path)
+        chunk = 1 << 20            # 1MB：再大提升有限，再小 adb 调用开销明显
+        t0 = time.time()
+        sent = 0
+        last_report = 0.0
+        try:
+            proc = subprocess.Popen(
+                [ADB_PATH, "-s", serial, "exec-in", "cat > %s" % remote],
+                stdin=subprocess.PIPE, stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE)
+        except Exception as e:
+            _log.warning(f"[{serial}] exec-in 启动失败，退回 adb push: {e}")
+            return self._push_fallback(serial, apk_path, remote)
+
+        # 看门狗：链路卡死时 `proc.stdin.write()` 会**永久阻塞**（设备掉线、
+        # WiFi 断了、任务在抢 adb…）→ 线程挂死 → 整批安装永不 finished → 界面
+        # 卡在"安装中"、后续安装全被"已有安装任务在进行"挡住（2026-09-14 事故）。
+        # 这里盯住"已写字节数"是否还在推进，停滞超时就 kill 掉 adb —— 阻塞中的
+        # write 会立刻以异常退出，走下面的回退逻辑。
+        # 为什么用看门狗而不是非阻塞写：`os.set_blocking`/管道 select 是 Unix 专有，
+        # 开发机是 Windows，看门狗两边都能用。
+        stop_watch = threading.Event()
+
+        def _stall_watchdog():
+            last_seen, since = -1, time.time()
+            while not stop_watch.wait(2.0):
+                if sent == total:
+                    return
+                if sent != last_seen:
+                    last_seen, since = sent, time.time()
+                elif time.time() - since > _PUSH_STALL_TIMEOUT:
+                    _log.warning(f"[{serial}] 推送停滞 {int(time.time() - since)} 秒"
+                                 f"（{sent}/{total} 字节），杀掉推送进程并回退")
+                    try:
+                        proc.kill()
+                    except Exception:
+                        pass
+                    return
+
+        watchdog = threading.Thread(target=_stall_watchdog, daemon=True)
+        watchdog.start()
+        try:
+            with open(apk_path, "rb") as f:
+                while True:
+                    buf = f.read(chunk)
+                    if not buf:
+                        break
+                    proc.stdin.write(buf)
+                    sent += len(buf)
+                    now = time.time()
+                    if now - last_report >= 0.8 or sent >= total:
+                        last_report = now
+                        spent = max(now - t0, 0.001)
+                        speed = sent / spent / 1048576.0          # MB/s
+                        left = int((total - sent) / max(sent / spent, 1))
+                        self._set_item(
+                            serial, "installing",
+                            "推送中 %d%%（%.1f/%.1f MB · %.1f MB/s · 剩约 %ds）"
+                            % (sent * 100 // max(total, 1), sent / 1048576.0,
+                               total / 1048576.0, speed, left))
+            proc.stdin.close()
+        except Exception as e:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+            _log.warning(f"[{serial}] exec-in 推送中断（{e}），已传 {sent}/{total} 字节，"
+                         f"退回 adb push 重传")
+            return self._push_fallback(serial, apk_path, remote)
+        finally:
+            stop_watch.set()
+
+        try:
+            rc = proc.wait(timeout=_INSTALL_TIMEOUT)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            return False, "推送超时（设备无响应）"
+        if rc != 0:
+            err = ""
+            try:
+                err = (proc.stderr.read() or b"").decode("utf-8", "replace")[:150]
+            except Exception:
+                pass
+            _log.warning(f"[{serial}] exec-in 推送到一半失败(rc={rc})，退回 adb push")
+            return self._push_fallback(serial, apk_path, remote)
+
+        # 校验设备上文件大小。**必须轮询等它长齐**——见 _wait_remote_size 的说明：
+        # exec-in 返回后设备侧可能仍在落盘，只量一次会把成功的传输误判成截断。
+        got = self._wait_remote_size(serial, remote, total)
+        if got is not None and got != total:
+            _log.warning(f"[{serial}] exec-in 推送不完整（设备 {got} / 本地 {total} 字节），"
+                         f"改用 adb push 重传")
+            return self._push_fallback(serial, apk_path, remote)
+
+        return True, "推送完成 %.1fMB / %.0fs" % (total / 1048576.0, time.time() - t0)
+
+    @staticmethod
+    def _remote_size(serial, remote):
+        """设备上文件字节数；取不到返回 None（stat 参数各机型有差异，不据此判失败）。"""
+        try:
+            rs = subprocess.run(
+                [ADB_PATH, "-s", serial, "shell", "stat", "-c", "%s", remote],
+                capture_output=True, timeout=30)
+            lines = (rs.stdout or b"").decode("utf-8", "replace").strip().splitlines()
+            return int(lines[-1]) if lines else None
+        except Exception:
+            return None
+
+    def _wait_remote_size(self, serial, remote, want, timeout=20.0):
+        """轮询设备上的文件大小，直到等于 want / 超时 / 取不到（None）。
+
+        为什么不能只量一次：**adb 进程退出 ≠ 设备上文件写完**。exec-in 把数据交给
+        设备侧（adbd → shell → `cat >`）后，缓冲区里的数据还会继续落盘。实测同一份
+        5.9MB 的 APK：adb 刚返回时 stat 读到 3710967，紧接着 4264448，几秒后才是完整的
+        5933150。旧实现量一次就判"推送不完整"，把**成功的传输误报成失败**
+        （2026-09-14 用户报的就是这个；同一份文件在多台设备上"失败"，断点还各不相同）。
+        """
+        deadline = time.time() + timeout
+        last = None
+        while True:
+            last = self._remote_size(serial, remote)
+            if last == want or last is None:
+                return last
+            if time.time() >= deadline:
+                return last
+            time.sleep(0.3)
+
+    def _push_fallback(self, serial, apk_path, remote):
+        """老 adb 或 exec-in 失败时的退路：原来的 `adb push`（无进度）。"""
+        self._set_item(serial, "installing", "正在推送 APK...（无进度显示）")
+        try:
+            r = subprocess.run(
+                [ADB_PATH, "-s", serial, "push", apk_path, remote],
+                capture_output=True, timeout=_INSTALL_TIMEOUT)
+        except subprocess.TimeoutExpired:
+            return False, "推送超时"
+        out = ((r.stdout or b"") + (r.stderr or b"")).decode("utf-8", errors="replace")
+        if r.returncode != 0 or "1 file pushed" not in out:
+            return False, (out.strip().replace("\n", " ")[:150]
+                           or f"推送失败(returncode={r.returncode})")
+        # adb push 是同步的（不会出现 exec-in 那种"退出后才落盘"），但仍量一次大小：
+        # 设备空间不足/文件被并发覆盖时，"1 file pushed" 也可能是残缺的
+        total = os.path.getsize(apk_path)
+        got = self._wait_remote_size(serial, remote, total, timeout=10)
+        if got is not None and got != total:
+            return False, f"推送不完整（设备 {got} / 本地 {total} 字节）"
+        return True, "推送完成(adb push)"
+
     def _set_item(self, serial, status, msg=""):
         """更新安装任务中某设备的状态。"""
         if not self._install_task:

core/db_config.py

@@ -0,0 +1,287 @@
+"""数据库连接装配：URI 组装、引擎参数、环境防呆校验、启动横幅。
+
+为什么单独一个模块：
+  web_server 要装配 app、迁移脚本/回归脚本要复用同一套 URI 与校验逻辑；
+  塞进 config.py 会把它撑肥，塞进 models.py 会引入循环依赖。
+
+支持两种后端：
+  - **MySQL**（DB_HOST 非空）：正式用法，dev 库 / 正式库由 .env 的 DEPLOY_ENV 决定
+  - **SQLite**（DB_HOST 为空）：仅作迁移期回退；生产禁止静默回退，需 DB_ALLOW_SQLITE_FALLBACK=1
+
+防呆设计（曾经把生产数据搞混过，这层是刚需）：
+  1. 库名与环境绑定：dev → auto_control_dev，prod → auto_control，对不上拒绝启动
+  2. 库标签：app_meta.deployment_env 记录"这个库属于哪个环境"，不匹配硬停
+  3. 启动横幅：每次启动都打印目标库，prod 用 WARNING 级（tail 日志必然可见）
+"""
+import os
+import uuid
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import make_url
+
+from config import (DATABASE_URL, DB_ALLOW_ENV_MISMATCH, DB_ALLOW_SQLITE_FALLBACK,
+                    DB_CHARSET, DB_COLLATION, DB_HOST, DB_NAME, DB_PASSWORD,
+                    DB_PORT, DB_USER, DATA_DIR, DEPLOY_ENV)
+from core.logger import get_logger
+
+_log = get_logger("core.db")
+
+# 环境 ↔ 库名绑定：防止「dev 的 .env 抄错成正式库名」这类事故
+_EXPECTED_DB_NAME = {"dev": "auto_control_dev", "prod": "auto_control"}
+
+_REQUIRED_MYSQL_VERSION = "5.7"
+
+# app_meta 里记录库身份的键
+_K_ENV, _K_ID, _K_CLAIMED = "deployment_env", "deployment_id", "deployment_claimed_at"
+
+
+class DBConfigError(Exception):
+    """数据库配置错误（消息直接面向运维，要说清怎么改）。"""
+
+
+# ================== URI 与引擎参数 ==================
+def is_sqlite(uri):
+    return str(uri).startswith("sqlite")
+
+
+def build_db_uri():
+    """按 .env 组装连接串。DATABASE_URL 优先级最高（脚本临时指向别的库用）。"""
+    if DATABASE_URL:
+        return DATABASE_URL
+    if DB_HOST:
+        from urllib.parse import quote_plus
+        return "mysql+pymysql://{}:{}@{}:{}/{}?charset={}".format(
+            quote_plus(DB_USER), quote_plus(DB_PASSWORD),
+            DB_HOST, DB_PORT, DB_NAME, DB_CHARSET)
+    # 回退 SQLite：生产环境必须显式开逃生阀，否则拒绝启动（静默降级本身就是混库温床）
+    if DEPLOY_ENV == "prod" and not DB_ALLOW_SQLITE_FALLBACK:
+        raise DBConfigError(
+            "生产环境（DEPLOY_ENV=prod）未配置 DB_HOST，且未显式允许回退 SQLite。\n"
+            "  如确需临时回退到 sqlite，请在 .env 里加 DB_ALLOW_SQLITE_FALLBACK=1\n"
+            "  否则请补全 DB_HOST/DB_USER/DB_PASSWORD/DB_NAME。")
+    return "sqlite:///" + os.path.join(DATA_DIR, "users.db")
+
+
+def engine_options(uri):
+    """create_engine 参数。SQLite 与 MySQL 需求不同，必须分叉。"""
+    if is_sqlite(uri):
+        return {"pool_pre_ping": True}
+    return {
+        # 长驻后台线程（TaskManager/device_discovery）长时间空闲后，
+        # 连接可能已被 MySQL 的 wait_timeout 掐断 / 中间链路掉线
+        "pool_pre_ping": True,
+        "pool_recycle": 1800,
+        "pool_size": 10,
+        "max_overflow": 20,
+        "pool_timeout": 30,
+        # 接近 SQLite「逐语句读最新提交」的语义，并显著降低间隙锁/死锁概率。
+        # 备份导出需要一致性快照时会单独把那个连接提到 REPEATABLE READ。
+        "isolation_level": "READ COMMITTED",
+        "connect_args": {
+            "charset": DB_CHARSET,
+            # 保留 STRICT_TRANS_TABLES（超长写入报错而不是静默截断）；
+            # 去掉 5.7 默认带的 ONLY_FULL_GROUP_BY，避免给未来埋雷
+            "init_command": "SET sql_mode='STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION'",
+        },
+    }
+
+
+def create_engine_from_uri(uri=None):
+    """独立建一个 engine（不经过 Flask-SQLAlchemy）。脚本与启动前探活用。"""
+    uri = uri or build_db_uri()
+    return create_engine(uri, **engine_options(uri))
+
+
+def describe_target(uri=None):
+    """人类可读的目标描述（**不含密码**），用于日志与横幅。"""
+    uri = uri or build_db_uri()
+    try:
+        u = make_url(uri)
+    except Exception:
+        return str(uri)
+    if u.get_backend_name() == "sqlite":
+        return u.database
+    return "{}@{}:{}/{}".format(u.username or "", u.host or "", u.port or 3306,
+                                u.database or "")
+
+
+# ================== app_meta 读写（方言中立）==================
+def _q(name):
+    """按当前方言给标识符加引号：MySQL 里 key 是保留字，必须反引号。"""
+    from core.models import db
+    return db.engine.dialect.identifier_preparer.quote(name)
+
+
+def meta_get(key, default=None):
+    from core.models import db
+    row = db.session.execute(
+        text("SELECT value FROM app_meta WHERE {} = :k".format(_q("key"))),
+        {"k": key}).fetchone()
+    return row[0] if row else default
+
+
+def meta_set(key, value):
+    """方言中立 upsert：SQLite 用 INSERT OR REPLACE，MySQL 用 ON DUPLICATE KEY。"""
+    from core.models import db
+    k = _q("key")
+    if db.engine.dialect.name == "mysql":
+        sql = ("INSERT INTO app_meta ({k}, value) VALUES (:k, :v) "
+               "ON DUPLICATE KEY UPDATE value = VALUES(value)").format(k=k)
+    else:
+        sql = "INSERT OR REPLACE INTO app_meta ({k}, value) VALUES (:k, :v)".format(k=k)
+    db.session.execute(text(sql), {"k": key, "v": str(value)})
+    db.session.commit()
+
+
+# ================== 启动前校验（不需要业务表）==================
+def check_connection(uri=None):
+    """连接探活 + 环境/库名一致性校验。失败抛 DBConfigError，由调用方决定是否退出。
+
+    不需要业务表，因此可以在 init_db 之前跑，做到"配置错就早点死"。
+    """
+    uri = uri or build_db_uri()
+
+    if is_sqlite(uri):
+        _log.warning("数据库为 SQLite（%s）—— 回退模式，非正式用法", describe_target(uri))
+        return {"backend": "sqlite", "target": describe_target(uri)}
+
+    if DEPLOY_ENV not in _EXPECTED_DB_NAME:
+        raise DBConfigError(
+            "DEPLOY_ENV 取值非法: {!r}（只允许 dev / prod）".format(DEPLOY_ENV))
+
+    try:
+        eng = create_engine_from_uri(uri)
+        with eng.connect() as conn:
+            version = conn.execute(text("SELECT VERSION()")).scalar() or ""
+            db_name = conn.execute(text("SELECT DATABASE()")).scalar() or ""
+        eng.dispose()
+    except DBConfigError:
+        raise
+    except Exception as e:
+        raise DBConfigError(
+            "连接数据库失败: {}\n  目标: {}\n  请检查 .env 的 DB_HOST/DB_PORT/"
+            "DB_USER/DB_PASSWORD 与本机到该主机的网络。/".format(e, describe_target(uri)))
+
+    if not version.startswith(_REQUIRED_MYSQL_VERSION):
+        _log.warning("MySQL 版本为 %s，本项目按 %s.x 验证（更高版本通常兼容，"
+                     "但请留意差异）", version, _REQUIRED_MYSQL_VERSION)
+
+    expected = _EXPECTED_DB_NAME[DEPLOY_ENV]
+    if db_name != expected and not DB_ALLOW_ENV_MISMATCH:
+        raise DBConfigError(
+            "环境与库名不匹配，已拒绝启动：\n"
+            "  .env 声明 DEPLOY_ENV={}  →  期望库名 {}\n"
+            "  实际连接的库           →  {}\n"
+            "  目标: {}\n"
+            "如确认无误（例如临时指向别的库），可在 .env 加 DB_ALLOW_ENV_MISMATCH=1。"
+            .format(DEPLOY_ENV, expected, db_name, describe_target(uri)))
+
+    return {"backend": "mysql", "version": version, "database": db_name,
+            "target": describe_target(uri)}
+
+
+# ================== 库标签校验（需要 app_meta 表，init_db 之后调用）==================
+def verify_deployment_label():
+    """核对 app_meta 里登记的库环境，与 .env 声明的环境是否一致。
+
+    首次见到某个库时会自动"认领"（写入标签）——生产库的标签由迁移脚本显式写入，
+    所以正常情况下不会走到自动认领分支。
+    """
+    from core.models import db
+    # SQLite（回退模式）也照样打标签：这样"从 dev 的 SQLite 导出的备份"在
+    # 预览里就能标出来源环境，跨环境导入的防呆才有依据。
+    recorded = meta_get(_K_ENV)
+    if recorded is None:
+        meta_set(_K_ENV, DEPLOY_ENV)
+        meta_set(_K_ID, uuid.uuid4().hex)
+        meta_set(_K_CLAIMED, _now())
+        _log.warning("首次见到该库，已登记为 %s 环境（部署标识 %s）",
+                     DEPLOY_ENV, meta_get(_K_ID))
+        return
+
+    if recorded != DEPLOY_ENV and not DB_ALLOW_ENV_MISMATCH:
+        raise DBConfigError(
+            "目标库登记的环境与 .env 声明不符，已拒绝启动：\n"
+            "  .env 声明             →  {}\n"
+            "  库中登记（{}）→  {}\n"
+            "  目标: {}\n"
+            "这通常意味着你正把「{} 的配置」连到「{} 的库」上。\n"
+            "如确需这样操作，请在 .env 加 DB_ALLOW_ENV_MISMATCH=1。"
+            .format(DEPLOY_ENV, meta_get(_K_CLAIMED) or "认领时间未知", recorded,
+                    describe_target(), DEPLOY_ENV, recorded))
+    elif recorded != DEPLOY_ENV:
+        _log.warning("库环境标签不符已按 DB_ALLOW_ENV_MISMATCH=1 放行：声明 %s / 库登记 %s",
+                     DEPLOY_ENV, recorded)
+
+
+# ================== 启动横幅 ==================
+def print_banner():
+    """每次启动打印一次「我现在连的是哪个库」。prod 用 WARNING 级。"""
+    from core.models import db
+    eng = db.engine
+    uri = eng.url
+    lines = []
+    if is_sqlite(uri):
+        lines.append("  数据库   : SQLite 回退模式  <<< 非正式用法 >>>")
+        lines.append("  目标     : " + describe_target())
+    else:
+        try:
+            with eng.connect() as conn:
+                version = conn.execute(text("SELECT VERSION()")).scalar() or ""
+                db_name = conn.execute(text("SELECT DATABASE()")).scalar() or ""
+                coll = conn.execute(text(
+                    "SELECT @@collation_database")).scalar() or ""
+                n_tables = conn.execute(text(
+                    "SELECT COUNT(*) FROM information_schema.tables "
+                    "WHERE table_schema = DATABASE()")).scalar() or 0
+            counts = []
+            for t in ("device", "task_job", "device_group", "agent_conversation"):
+                try:
+                    n = db.session.execute(
+                        text("SELECT COUNT(*) FROM {}".format(t))).scalar()
+                    counts.append("{}={}".format(t, n))
+                except Exception:
+                    db.session.rollback()
+            lines.append("  MySQL    : {}    库 {} ({})".format(version, db_name, coll))
+            lines.append("  目标     : " + describe_target())
+            lines.append("  表       : {} 张".format(n_tables))
+            lines.append("  数据量   : " + "  ".join(counts))
+        except Exception as e:
+            lines.append("  连接信息采集失败: {}".format(e))
+        lines.append("  库标签   : {}（{} 认领）".format(
+            meta_get(_K_ENV) or "未登记", meta_get(_K_CLAIMED) or "—"))
+
+    tag = "生产库 PROD" if DEPLOY_ENV == "prod" else "开发库 DEV"
+    bar = "=" * 64
+    head = ("{}  数据库已连接  [ {} ]{}".format(
+        bar, tag, "   <<< 这是正式数据，操作前想清楚 >>>" if DEPLOY_ENV == "prod" else ""))
+    body = "\n".join(lines)
+    text_block = "\n{}\n{}\n{}".format(head, body, bar)
+    if DEPLOY_ENV == "prod":
+        _log.warning(text_block)
+    else:
+        _log.info(text_block)
+
+
+def env_badge():
+    """给页面顶部徽标用的环境信息（不含密码）。
+
+    防混库的第 4 层：光靠启动日志不够——用户点开任何页面都该一眼看出
+    自己正在操作哪个库。生产用红底。
+    """
+    try:
+        from core.models import db
+        backend = "sqlite" if is_sqlite(db.engine.url) else "mysql"
+    except Exception:
+        backend = "?"
+    try:
+        target = describe_target()
+    except Exception:
+        target = DB_HOST or "(未配置)"
+    return {"env": DEPLOY_ENV, "is_prod": DEPLOY_ENV == "prod",
+            "backend": backend, "target": target}
+
+
+def _now():
+    import time
+    return time.strftime("%Y-%m-%d %H:%M:%S")

core/device_discovery.py

@@ -22,6 +22,7 @@ from config import (USB_ADB_HOST,
                     DISCOVERY_PORT, DISCOVERY_SUBNETS, DISCOVERY_INTERVAL)
 from core.adb_helper import _adb, adb_connect_light
 from core.logger import get_logger
+from core import notifier
 from core.models import db, Device, PendingDevice
 
 _log = get_logger("core.disc")
@@ -42,6 +43,8 @@ _PROBE_TIMEOUT = 0.4
 
 _app = None
 _scan_lock = threading.Lock()     # 定时/手动扫描互斥
+# 上一轮"池内离线"集合：通知只报**状态沿**（这一轮新变成离线的），不每轮刷屏
+_last_offline = set()
 _stop_event = threading.Event()   # shutdown 用
 _scanning = False                 # 状态快照（API/前端）
 _last_scan = None                 # (时间串, 开放数, 可连数, 新增数)
@@ -61,9 +64,10 @@ def _fmt(ts=None):
 def get_settings():
     """读发现配置（app_meta，缺键用 config 默认值补齐）。"""
     with _ctx():
+        from core.db_config import meta_get
+
         def _get(key, default):
-            v = db.session.execute(
+            v = meta_get(key)
-                db.text("SELECT value FROM app_meta WHERE key=:k"), {"k": key}).scalar()
             return v if v is not None else default
         try:
             subnets = json.loads(_get(_K_SUBNETS, "[]")) or DISCOVERY_SUBNETS
@@ -100,10 +104,8 @@ def save_settings(enabled=None, subnets=None, interval=None, port=None, auto_cla
     except (TypeError, ValueError):
         return False, "参数不合法"
     with _ctx():
-        def _put(key, value):
+        from core.db_config import meta_set
-            db.session.execute(
+        _put = meta_set   # 方言中立 upsert（app_meta.key 在 MySQL 里是保留字）
-                db.text("INSERT OR REPLACE INTO app_meta(key,value) VALUES(:k,:v)"),
-                {"k": key, "v": str(value)})
         if enabled is not None:
             _put(_K_ENABLED, "1" if enabled else "0")
         if subnets is not None:
@@ -267,6 +269,7 @@ def scan_once(manual=False):
             now = _fmt()
             existing = {p.serial for p in PendingDevice.query.all()}
             added = 0
+            added_serials = []
             from core import device_pool
             fps = {}
             for serial in verified:
@@ -284,6 +287,7 @@ def scan_once(manual=False):
                                                  first_seen=now, last_seen=now,
                                                  fingerprint=fp))
                     added += 1
+                    added_serials.append(serial)
             db.session.commit()
             # 5.5 自动认领（可选，默认关）：指纹命中池中已有设备 → 直接把记录迁到新地址。
             #     默认关是因为认领会改写分组/任务引用（数据结构变动），交人工点一下更稳妥；
@@ -294,11 +298,34 @@ def scan_once(manual=False):
             #    全局锁串行），连上即恢复在线，无需人工干预。pending 池是给
             #    「未授权新设备」的，正式池设备断联不进 pending，而是自动重连。
             back = _reconnect_offline(configured)
+            # 7. 离线集合（供"状态沿"通知用：只报**这一轮新变成离线**的，不每轮刷屏）
+            offline_now = {s for s in configured if not device_pool.is_online(s)}
             _log.info(f"发现: 探测开放 {len(open_ips)} 台，可连 {len(verified)} 台，"
                       f"新增待连接 {added} 台"
                       + (f"，自动重连恢复 {len(back)} 台 {back}" if back else "")
                       + (f"，自动认领 {len(claimed)} 台 {[c[0] + '→' + c[1] for c in claimed]}"
                          if claimed else ""))
+        # 通知统一放在 `with _ctx():` 之后（别在 DB 事务期间做额外的事）
+        global _last_offline
+        try:
+            newly_offline = sorted(offline_now - _last_offline)
+            _last_offline = set(offline_now)
+            if newly_offline:
+                notifier.notify("device.offline", serials=newly_offline,
+                                count=len(newly_offline),
+                                devices=newly_offline[:10])
+            if back:
+                notifier.notify("device.online", serials=list(back), count=len(back))
+            if added_serials:
+                notifier.notify("device.discovered", serials=added_serials[:10],
+                                count=len(added_serials))
+            if claimed:
+                notifier.notify("device.claimed",
+                                pairs=[f"{c[0]}→{c[1]}" for c in claimed][:10],
+                                count=len(claimed))
+        except Exception as e:
+            _log.warning(f"发送设备上下线通知失败（不影响扫描）: {e}")
+
         _last_scan = (now, len(open_ips), len(verified), added)
         _last_error = ""
         return True, {"found": len(open_ips), "verified": len(verified),

core/device_worker.py

@@ -19,6 +19,7 @@ import uiautomator2 as u2
 from config import USB_ADB_HOST, USB_ADB_PORT
 from core.logger import get_logger
 from core import device_pool
+from core import notifier
 from .adb_helper import _adb, adb_connect, _adb_remote
 
 _log = get_logger("core.worker")
@@ -188,9 +189,18 @@ class _Watchdog(threading.Thread):
                 if hb and now - hb > _HEARTBEAT_TIMEOUT:
                     stale.append(serial)
         for serial in stale:
-            _log.error(f"[{serial}] 心跳超时 {now - get_worker_heartbeat(serial):.0f}s，标记卡死")
+            hb_age = now - get_worker_heartbeat(serial)
+            _log.error(f"[{serial}] 心跳超时 {hb_age:.0f}s，标记卡死")
+            with _WORKERS_LOCK:
+                cur = dict(_WORKERS.get(serial, {}))
             _update_status(serial, status="error",
                            last_error=f"心跳超时 {_HEARTBEAT_TIMEOUT}s，worker 可能卡死")
+            # 设备卡死是最需要人工介入的静默故障——通知一次
+            # （天然只报一次：下面的检查只针对 running/connecting，标成 error 后不再命中）
+            notifier.notify("device.heartbeat_timeout", serial=serial,
+                            device_name=cur.get("device_name") or "",
+                            timeout_s=int(hb_age), task_job=cur.get("task_job") or "",
+                            model=cur.get("model") or "")
 
     def stop(self):
         self._stop.set()
@@ -265,10 +275,13 @@ class BaseWorker(threading.Thread):
       其他异常           — 可重试
     """
 
-    def __init__(self, serial, params=None, daemon=True):
+    def __init__(self, serial, params=None, daemon=True, ctx=None):
         super().__init__(daemon=daemon)
         self.serial = serial
         self.params = params or {}
+        # 本次运行的上下文（run_id / job_id / job_name / device_name），由
+        # TaskManager 传入，供步骤明细等"结构化记录"标注来源。可空。
+        self.ctx = dict(ctx or {})
         self._stop_flag = threading.Event()
         self.d = None  # u2.Device，run_task 里用
         # 通用进度字段（子类通过 set_progress 上报）

core/gesture.py

@@ -0,0 +1,276 @@
+"""录制手势：**纯录制、纯回放**——录下真实手指的轨迹与时间，回放时一模一样地重放。
+
+和「滑动」步骤的区别（这是两套东西，别混）：
+
+| | `swipe` 步骤 | `gesture` 步骤（本模块） |
+|---|---|---|
+| 内容 | 方向 + 幅度 + 时长区间 | **完整轨迹点列** `[[x, y, t_ms], ...]` |
+| 回放 | 每次重新生成（弧线/抖动/本设备手速） | **照录制的路径与时间逐点重放**，不加任何修饰 |
+| 适合 | 通用滑动，换设备也能用 | 你亲手划的、要求一模一样的手势 |
+
+两个录制来源：
+1. **手机上录**（`PhoneRecorder`）：`getevent` 读**真触屏**设备，抓的是你手指的真实轨迹
+   ——注意合成的注入事件不会出现在真触屏节点上（实测确认），所以录到的只有人手的动作；
+2. **网页上录**：看着设备画面拖鼠标，前端采样路径与时间（见 `static/admin/recorder.js`）。
+
+## 回放怎么做（实测定的，别改回去）
+
+**一次调用把整条轨迹交给设备**（`d.swipe_points(points, duration)`），不是逐点注入。
+原因：实测这台设备上**单次触摸注入 RPC ≈190ms**（`d.touch.move` 25 次平均 190ms），
+逐点回放 20 个点要 3.8 秒——比录的手势慢一个数量级，根本不能用。所以只能让设备
+自己去插值：`swipe_points` 内部按 `steps = duration/0.005` 在轨迹上均匀推进，
+手势的真实速度由设备端决定。
+
+拿到"时间"靠的是**点密度**：手指慢的地方采样点天然更密（单位长度上点更多），
+无论设备是按弧长均匀插值还是按段均匀插值，"点密的段落走得更久"都成立
+——所以把**录制的原始点 + 录制总时长**一起交给设备，速度曲线就能大致还原。
+"""
+import re
+import subprocess
+import threading
+import time
+
+from core.adb_helper import ADB_PATH
+from core.logger import get_logger
+
+_log = get_logger("core.gesture")
+
+# 采样下限：手指在 16ms 内位移极小，比这更密的点只增加注入次数与延迟误差
+MIN_GAP_MS = 16
+MAX_POINTS = 240          # 单条手势的点数上限（约 4s @60Hz，够用且不让步骤 JSON 膨胀）
+MAX_REPLAY_POINTS = 40    # 回放时最多发给设备多少个点（实测每点开销大，40 点是画质/耗时折中）
+MIN_POINTS = 2
+
+# getevent -lt 的行： [   12345.678901] EV_ABS       ABS_MT_POSITION_X    000003e8
+# 第 4 列不能限定十六进制：BTN_TOUCH 的值是 DOWN/UP 这类**键名**（含非十六进制字母），
+# 限定 [0-9a-fA-F]+ 会让这些行整个被跳过 → 老协议解析不出任何手势
+_LINE_RE = re.compile(r"\[\s*([\d.]+)\]\s+(\S+)\s+(\S+)\s+(\S+)")
+
+# "像真触屏"的设备名特征（先挑这些）；明显是合成/虚拟的一律排除
+_TOUCH_HINTS = ("ts", "touch", "goodix", "fts", "synaptics", "novatek", "himax", "sec_touch")
+_VIRTUAL_HINTS = ("uinput", "virtual", "vitural", "sar", "gpio", "pon", "jack", "button")
+
+
+# ================== 点列处理 ==================
+
+def clean_points(points, min_gap_ms=MIN_GAP_MS, max_points=MAX_POINTS):
+    """规范点列：丢掉过密的采样、限制总数，时间归零到第一点。
+
+    输入/输出都是 `[[x, y, t_ms], ...]`（t 为相对第一点的毫秒）。点数不足 2 返回 []。
+    """
+    pts = []
+    for p in points or []:
+        try:
+            pts.append([int(p[0]), int(p[1]), float(p[2])])
+        except (TypeError, ValueError, IndexError):
+            continue
+    if len(pts) < MIN_POINTS:
+        return []
+    out = [pts[0]]
+    for p in pts[1:-1]:
+        if (p[2] - out[-1][2]) >= min_gap_ms:
+            out.append(p)
+    # 末点**必须保留**：它决定手势收尾在哪（快划时中间点稀，终点不能跟着丢）
+    if pts[-1][:2] != out[-1][:2] or pts[-1][2] > out[-1][2]:
+        out.append(pts[-1])
+    if len(out) < MIN_POINTS:
+        return []
+    if len(out) > max_points:                         # 均匀抽稀，保住首尾
+        step = len(out) / float(max_points)
+        out = [out[min(len(out) - 1, int(i * step))] for i in range(max_points)]
+    t0 = out[0][2]
+    for p in out:
+        p[2] = int(round(p[2] - t0))
+    return out
+
+
+def duration_ms(points):
+    return int(points[-1][2]) if points else 0
+
+
+def replay(d, points, speed=1.0):
+    """按录制的轨迹与时长回放（一次调用交给设备插值）。返回发给设备的参数。
+
+    点太多会让设备端逐点开销累积（实测每个点约 1s 量级），所以超过 MAX_REPLAY_POINTS
+    就抽稀——路径形状基本不变，但快得多。首尾点一定保留。
+    """
+    pts = clean_points(points, min_gap_ms=0)          # 回放不再按时间丢点
+    if len(pts) < MIN_POINTS:
+        raise ValueError("手势点列无效（少于 2 个点）")
+    if len(pts) > MAX_REPLAY_POINTS:
+        n = MAX_REPLAY_POINTS
+        step = (len(pts) - 1) / float(n - 1)
+        pts = [pts[min(len(pts) - 1, int(round(i * step)))] for i in range(n)]
+    speed = max(0.1, float(speed or 1.0))
+    dur = max(0.05, duration_ms(pts) / 1000.0 / speed)
+    xy = [[x, y] for x, y, _ in pts]
+    try:
+        d.swipe_points(xy, dur)
+    except Exception as e:                            # 有的设备/agent 不支持多点注入
+        _log.warning("swipe_points 回放失败（%s），退回直线滑动", e)
+        d.swipe(xy[0][0], xy[0][1], xy[-1][0], xy[-1][1], dur)
+    return {"points": len(pts), "duration": round(dur, 3)}
+
+
+# ================== getevent 解析（纯函数，好单测） ==================
+
+def parse_getevent(lines, max_x, max_y, screen_w, screen_h):
+    """把 getevent 行流解析成若干条轨迹 `[[x, y, t_ms], ...]`（屏幕坐标）。
+
+    兼容两套协议：`BTN_TOUCH DOWN/UP`（老）与 `ABS_MT_TRACKING_ID`（新，-1=抬起）。
+    只认 EV_ABS 的 X/Y；Y 到达时才落一个点（X/Y 是先后到达的两个事件）。
+    """
+    strokes, cur = [], None
+    lx = ly = 0
+    t0 = None
+    for ln in lines or []:
+        m = _LINE_RE.search(ln)
+        if not m:
+            continue
+        ts, kind, code, val = float(m.group(1)), m.group(2), m.group(3), m.group(4)
+        if kind == "EV_ABS":
+            if code == "ABS_MT_POSITION_X":
+                lx = int(val, 16)
+            elif code == "ABS_MT_POSITION_Y":
+                ly = int(val, 16)
+                if cur is not None:
+                    if t0 is None:
+                        t0 = ts
+                    cur.append([lx, ly, (ts - t0) * 1000.0])
+            elif code == "ABS_MT_TRACKING_ID":
+                if val.lower().endswith("ffffffff"):     # 抬起
+                    if cur:
+                        strokes.append(cur)
+                    cur = None
+                elif cur is None:                        # 按下
+                    cur = []
+        elif kind == "EV_KEY" and code == "BTN_TOUCH":
+            if val == "DOWN":
+                if cur is None:
+                    cur = []
+            else:
+                if cur:
+                    strokes.append(cur)
+                cur = None
+    if cur:
+        strokes.append(cur)
+
+    sx = float(screen_w) / max_x if max_x else 1.0
+    sy = float(screen_h) / max_y if max_y else 1.0
+    out = []
+    for st in strokes:
+        pts = [[int(round(x * sx)), int(round(y * sy)), t] for x, y, t in st]
+        pts = clean_points(pts)
+        if len(pts) >= MIN_POINTS:
+            out.append(pts)
+    return out
+
+
+def find_touch_device(serial, screen_w=0, screen_h=0):
+    """找真触屏设备，返回 (device_path, max_x, max_y)；找不到返回 (None, 0, 0)。
+
+    设备名里带 uinput/virtual/sar/gpio 的一律排除（那些是合成输入）；
+    多个候选时优先名字像触屏的，其次挑坐标范围最接近屏幕的那个。
+    """
+    from core.adb_helper import _adb
+    out = _adb("-s", serial, "shell", "getevent -pl") or ""
+    cands, dev, name = [], None, ""
+    for ln in out.splitlines():
+        s = ln.strip()
+        if s.startswith("add device"):
+            dev, name = s.split(":", 1)[-1].strip(), ""
+        elif s.startswith("name:"):
+            name = s.split(":", 1)[1].strip().strip('"')
+        elif "ABS_MT_POSITION_X" in s or "ABS_MT_POSITION_Y" in s:
+            m = re.search(r"max (\d+)", s)
+            if not (dev and m):
+                continue
+            key = "x" if "POSITION_X" in s else "y"
+            for c in cands:
+                if c[0] == dev:
+                    c[1 if key == "x" else 2] = int(m.group(1))
+                    break
+            else:
+                mx = int(m.group(1)) if key == "x" else 0
+                my = int(m.group(1)) if key == "y" else 0
+                cands.append([dev, mx, my, name])
+    real = [c for c in cands
+            if not any(h in (c[3] or "").lower() for h in _VIRTUAL_HINTS)]
+    pool = real or cands
+    if not pool:
+        return None, 0, 0
+
+    def score(c):
+        hit = any(h in (c[3] or "").lower() for h in _TOUCH_HINTS)
+        return (0 if hit else 1, abs(c[1] - (screen_w or c[1])) + abs(c[2] - (screen_h or c[2])))
+
+    pool.sort(key=score)
+    best = pool[0]
+    _log.info(f"[{serial}] 录制用手势设备: {best[0]} ({best[3]}) {best[1]}x{best[2]}"
+              f"，候选 {[c[0] + '/' + (c[3] or '?') for c in cands]}")
+    return best[0], best[1], best[2]
+
+
+# ================== 手机端录制 ==================
+
+class PhoneRecorder:
+    """在**手机真触屏**上录手指轨迹（getevent 流式读取）。"""
+
+    def __init__(self, serial, screen_w=0, screen_h=0):
+        self.serial = serial
+        self.screen_w = int(screen_w or 0)
+        self.screen_h = int(screen_h or 0)
+        self.device = None
+        self.max_x = self.max_y = 0
+        self._proc = None
+        self._lines = []
+        self._thread = None
+        self._stop = threading.Event()
+        self._started = 0.0
+        self.error = ""
+
+    def start(self):
+        """起 getevent 子进程并开始收行。失败抛异常（调用方转成用户可读错误）。"""
+        self.device, self.max_x, self.max_y = find_touch_device(
+            self.serial, self.screen_w, self.screen_h)
+        if not self.device or not self.max_x:
+            raise RuntimeError("没找到触屏设备节点，无法在手机上录制")
+        self._proc = subprocess.Popen(
+            [ADB_PATH, "-s", self.serial, "shell", f"getevent -lt {self.device}"],
+            stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+        self._started = time.time()
+        self._thread = threading.Thread(target=self._pump, daemon=True)
+        self._thread.start()
+        _log.info(f"[{self.serial}] 手机录制已开始（{self.device}）")
+
+    def _pump(self):
+        try:
+            for raw in iter(self._proc.stdout.readline, b""):
+                if self._stop.is_set():
+                    break
+                self._lines.append(raw.decode("utf-8", "replace").rstrip())
+                if len(self._lines) > 20000:             # 防爆：留最近 2 万行足够解析
+                    del self._lines[:5000]
+        except Exception as e:
+            self.error = f"读取事件流失败: {e}"
+
+    def stop(self):
+        """停止并返回 `[[[x,y,t_ms], ...], ...]`（每条手势一段）。"""
+        self._stop.set()
+        try:
+            if self._proc:
+                self._proc.terminate()
+                try:
+                    self._proc.wait(timeout=3)
+                except Exception:
+                    self._proc.kill()
+        except Exception:
+            pass
+        if self._thread:
+            self._thread.join(timeout=2)
+        w = self.screen_w or self.max_x
+        h = self.screen_h or self.max_y
+        gestures = parse_getevent(self._lines, self.max_x, self.max_y, w, h)
+        _log.info(f"[{self.serial}] 手机录制结束：{len(self._lines)} 行事件 → "
+                  f"{len(gestures)} 条手势（{sum(len(g) for g in gestures)} 点）")
+        return gestures

core/humanize.py

@@ -0,0 +1,186 @@
+"""拟人化操作：滑动不机械，且**每台设备有自己的手感**。
+
+分两个层次，别混在一起：
+
+1. **每次都不一样**（抖动）：起点/终点位置、滑动幅度、时长、弧线方向都随机——
+   最容易被识别的特征不是"慢"，而是"同一帧重复播放"。
+2. **每台设备稳定不同**（性格）：由 `serial` 派生一份固定的偏好（手速、幅度、
+   弧度、停顿、常用触点的横向位置）。同一台设备多次运行风格一致，不同设备之间
+   明显不同——批量跑 13 台时看起来像 13 个人各刷各的，而不是 13 台同步机器人。
+
+**性格稳定、抖动随机**，两者都由 serial 播种，不引入全局状态、不做任何 IO。
+
+性格怎么来的：`crc32(serial)` 作种子 → 几个围绕 1.0 的比例因子（见 `profile()`）。
+换设备换风格，改名字**不改**风格（按 serial 而不是设备名），换地址会换风格——
+这符合直觉：地址代表"这一台"。
+
+想手工看一眼某台设备的性格：`python -c "from core import humanize; print(humanize.profile('192.168.20.55:5555'))"`
+"""
+import random
+import time
+import zlib
+
+from core.logger import get_logger
+
+_log = get_logger("core.humanize")
+
+_PROFILE_CACHE = {}
+# serial -> (w, h, ts)：屏幕尺寸缓存（见 screen_size）
+_SIZE_CACHE = {}
+_SIZE_TTL = 120
+
+
+def profile(serial):
+    """设备性格（按 serial 缓存，恒定）。字段都是围绕 1.0 的比例因子。"""
+    key = str(serial or "")
+    p = _PROFILE_CACHE.get(key)
+    if p is not None:
+        return p
+    # 用独立的 Random 实例而不是全局 random：worker 是多线程的，全局 random 的
+    # 取值顺序会被其它线程打乱 —— 那样"每台设备的性格"就串味了
+    r = random.Random(zlib.crc32(("human:" + key).encode("utf-8")))
+    p = {
+        "speed": r.uniform(0.82, 1.32),      # <1 划得快（时长短），>1 划得慢
+        "distance": r.uniform(0.86, 1.16),   # 有人习惯一划到底，有人小步快跑
+        "curve": r.uniform(0.4, 1.6),        # 弧线弯度系数
+        "x_bias": r.uniform(-0.09, 0.09),    # 常用触点的横向偏移（屏幕宽比例）
+        "pause": r.uniform(0.80, 1.35),      # 停顿倍率（wait 步骤可选启用）
+    }
+    _PROFILE_CACHE[key] = p
+    return p
+
+
+def screen_size(d, serial=""):
+    """屏幕尺寸，带缓存。
+
+    为什么不用 `d.info`：它在部分设备上**极慢**（实测 14s，见 doc/backlog），而
+    尺寸在一次运行里根本不会变。`d.window_size()` 快得多（同设备 0.6s）。
+    缓存 120s 过期：够躲开慢调用，又能在屏幕旋转/换分辨率后自愈。
+    """
+    key = str(serial or "")
+    now = time.time()
+    hit = _SIZE_CACHE.get(key)
+    if hit and now - hit[2] < _SIZE_TTL:
+        return hit[0], hit[1]
+    try:
+        w, h = d.window_size()
+    except Exception:                      # 老 agent 没有 window_size 就退回 info
+        info = d.info
+        w, h = info["displayWidth"], info["displayHeight"]
+    w, h = int(w), int(h)
+    if w > 0 and h > 0:
+        _SIZE_CACHE[key] = (w, h, now)
+    return w, h
+
+
+def _bezier(p0, p1, p2, n):
+    """二次贝塞尔采样——手指划出来是弧线，不是尺子画的直线。"""
+    pts = []
+    for i in range(n + 1):
+        t = i / n
+        x = (1 - t) ** 2 * p0[0] + 2 * (1 - t) * t * p1[0] + t * t * p2[0]
+        y = (1 - t) ** 2 * p0[1] + 2 * (1 - t) * t * p1[1] + t * t * p2[1]
+        pts.append((int(round(x)), int(round(y))))
+    # 同样的点会连续出现（曲线很平时）——去掉，免得下发冗余坐标
+    out = [pts[0]]
+    for p in pts[1:]:
+        if p != out[-1]:
+            out.append(p)
+    return out
+
+
+def swipe(d, direction, serial="", duration_min=0.25, duration_max=0.50,
+          distance_ratio=0.6, jitter=0.15, humanize=True):
+    """按人类习惯滑一下（上/下/左/右）。
+
+    参数：
+      direction       上滑 up / 下滑 down / 左滑 left / 右滑 right
+      serial          用来取本设备的性格（不传就是"普通人"）
+      duration_min/max 手指接触屏幕的时长区间（秒），再乘本设备手速系数
+      distance_ratio  滑动幅度占屏幕高（竖滑）或宽（横滑）的比例，默认 0.6
+      jitter          抖动幅度 0~0.4：位置/幅度/时长各抖这么多；0 = 每次都一样
+      humanize        False = 退回老的直线滑动（完全规则，用于对照/排障）
+
+    返回实际参数 dict（时长/起止点），方便日志与排障。异常向上抛，由调用方兜。
+    """
+    w, h = screen_size(d, serial)
+    prof = profile(serial)
+    vertical = direction in ("up", "down")
+    j = max(0.0, min(float(jitter or 0), 0.4))
+
+    # ---- 时长：用户给的范围 × 本设备手速 × 本次抖动 ----
+    dur = random.uniform(float(duration_min), float(duration_max))
+    dur *= prof["speed"]
+    if j:
+        dur *= 1 + random.uniform(-j, j) * 0.6
+    dur = max(0.08, round(dur, 3))
+
+    # ---- 幅度与中心点 ----
+    span = (h if vertical else w) * float(distance_ratio) * prof["distance"]
+    if j:
+        span *= 1 + random.uniform(-j, j)
+    span = max(0.08, min(span, (h if vertical else w) * 0.92))
+
+    # 起点不在正中：人不会每次都在屏幕同一条线上划
+    if vertical:
+        cx = w * (0.5 + prof["x_bias"] + (random.uniform(-j, j) * 0.6 if j else 0))
+        cx = int(max(w * 0.10, min(cx, w * 0.90)))
+        cy = h * 0.5
+        if j:
+            cy += h * random.uniform(-j, j) * 0.5
+        sign = -1 if direction == "up" else 1
+        p0 = (cx, int(max(h * 0.03, min(cy - sign * span / 2, h * 0.97))))
+        p2 = (cx, int(max(h * 0.03, min(cy + sign * span / 2, h * 0.97))))
+    else:
+        cy = int(h * (0.5 + prof["x_bias"] + (random.uniform(-j, j) * 0.6 if j else 0)))
+        cy = int(max(h * 0.10, min(cy, h * 0.90)))
+        cx = w * 0.5
+        if j:
+            cx += w * random.uniform(-j, j) * 0.5
+        sign = -1 if direction == "left" else 1
+        p0 = (int(max(w * 0.03, min(cx - sign * span / 2, w * 0.97))), cy)
+        p2 = (int(max(w * 0.03, min(cx + sign * span / 2, w * 0.97))), cy)
+
+    if not humanize:
+        # 老行为：正中直线、无抖动（点与点之间由设备等分插值）
+        if vertical:
+            s, e = (0.8, 0.2) if direction == "up" else (0.2, 0.8)
+            base = (int(w * 0.5), int(h * s), int(w * 0.5), int(h * e))
+        else:
+            s, e = (0.8, 0.2) if direction == "left" else (0.2, 0.8)
+            base = (int(w * s), int(h * 0.5), int(w * e), int(h * 0.5))
+        d.swipe(*base, random.uniform(float(duration_min), float(duration_max)))
+        return {"duration": dur, "from": base[:2], "to": base[2:], "human": False}
+
+    # ---- 弧线：控制点在中点、垂直于滑动方向偏移 ----
+    amp = span * 0.05 * prof["curve"]
+    if j:
+        amp *= random.uniform(0.3, 1.0)
+        amp *= random.choice((-1, 1))                   # 这次往左弯还是往右弯
+    else:
+        # jitter=0 时不引入任何随机：弯向由设备性格决定，便于对照排障
+        amp *= -1 if prof["curve"] < 1.0 else 1
+    mx, my = (p0[0] + p2[0]) / 2, (p0[1] + p2[1]) / 2
+    if vertical:
+        ctrl = (mx + amp, my)
+    else:
+        ctrl = (mx, my + amp)
+    # 点数刻意压到 4：`swipe_points` 在慢设备上**每多一个点就多约 1s**
+    # （实测 2 点 1.4s / 6 点 6.0s / 10 点 10.6s），而设备自己会在点之间
+    # 插值 70 步，4 个点的贝塞尔已经足够弯
+    pts = _bezier(p0, ctrl, p2, 4)
+    if len(pts) < 2:                                     # 幅度太小时退化成直线
+        pts = [p0, p2]
+    try:
+        d.swipe_points([[x, y] for x, y in pts], dur)
+    except Exception as e:                               # 老设备/agent 不支持曲线就退回直线
+        _log.warning("swipe_points 不可用，退回直线滑动: %s", e)
+        d.swipe(p0[0], p0[1], p2[0], p2[1], dur)
+    return {"duration": dur, "from": p0, "to": p2, "curve": amp, "human": True}
+
+
+def pace(serial, seconds, enabled=True):
+    """按本设备节奏微调一个停顿（wait 步骤可选启用）。enabled=False 原样返回。"""
+    if not enabled:
+        return float(seconds)
+    return float(seconds) * profile(serial)["pause"]

core/logger.py

@@ -16,7 +16,9 @@
 文件按 10MB 滚动，保留 5 个历史文件。
 """
 import os
+import re
 import logging
+from collections import deque
 from logging.handlers import RotatingFileHandler
 
 _LOG_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "logs")
@@ -31,6 +33,8 @@ _MODULE_FILES = {
     "task": "task.log",
     "web": "web.log",
     "action": "action.log",
+    # 通知单独一个文件：排障时"哪条通知发了/失败了/为什么"要能一眼翻到
+    "notify": "notify.log",
 }
 
 _FORMAT = "%(asctime)s [%(levelname)s] [%(name)s] %(message)s"
@@ -82,3 +86,192 @@ def log_print(msg, level="info", module="core"):
     """print 的替代品，转发到 logging。"""
     log = get_logger(module)
     getattr(log, level, log.info)(msg)
+
+
+# ================== 日志读取（「日志」页的筛选 / 下载） ==================
+#
+# 读日志的代码放这里而不是 web 层：文件命名与滚动规则归本模块管
+# （_MODULE_FILES + RotatingFileHandler 的 backupCount），**白名单校验必须和
+# 写入侧用同一份事实**，否则改了文件名就会漏掉一处，变成目录穿越。
+
+# 行格式与 _FORMAT 对应：2026-09-16 00:27:11 [INFO] [web.notify] 消息
+_LINE_RE = re.compile(r"^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) "
+                      r"\[([A-Z]+)\] \[([^\]]*)\] ?(.*)$")
+_LEVEL_ORDER = {"DEBUG": 10, "INFO": 20, "WARNING": 30, "ERROR": 40, "CRITICAL": 50}
+
+# 单次读取的行数上限：文件本身被限在 10MB（约 10 万行），这里再兜一层，
+# 万一将来有人调大 maxBytes，也不会把内存吃爆。
+_MAX_SCAN_LINES = 500000
+
+_MODULE_LABELS = {
+    "core.log": "核心(adb/调度)",
+    "task.log": "任务执行",
+    "web.log": "Web/AI",
+    "action.log": "动作执行",
+    "notify.log": "通知发送",
+}
+
+
+def _rotation_files(base):
+    """基础名 + 磁盘上实际存在的滚动副本（core.log → core.log.1/.2…）。
+
+    RotatingFileHandler 的备份编号**越大越旧**，所以 base 最新，接着 .1/.2…
+    """
+    names = []
+    if os.path.exists(os.path.join(_LOG_DIR, base)):
+        names.append(base)
+    i = 1
+    while i <= 99 and os.path.exists(os.path.join(_LOG_DIR, f"{base}.{i}")):
+        names.append(f"{base}.{i}")
+        i += 1
+    return names
+
+
+def list_log_files():
+    """可查看的日志文件（模块文件 + 滚动历史），最近写入的排前面。
+
+    `file` 参数只能取这里的 name（白名单），杜绝 `../../` 之类的路径穿越。
+    """
+    out = []
+    for base in sorted(set(_MODULE_FILES.values())):
+        label = _MODULE_LABELS.get(base, base)
+        for name in _rotation_files(base):
+            try:
+                st = os.stat(os.path.join(_LOG_DIR, name))
+            except OSError:
+                continue
+            rotated = name != base
+            out.append({
+                "name": name,
+                "label": f"{label} · {name}" + ("（历史）" if rotated else ""),
+                "module": base,
+                "size": st.st_size,
+                "mtime": int(st.st_mtime),
+                "rotated": rotated,
+            })
+    out.sort(key=lambda f: (-f["mtime"], f["name"]))
+    return out
+
+
+def norm_ts(value, end=False):
+    """把前端的时间输入归一成 'YYYY-MM-DD HH:MM:SS'（可比字符串）。
+
+    接受 datetime-local 的 'YYYY-MM-DDTHH:MM'、'YYYY-MM-DD HH:MM' 和纯日期；
+    纯日期按整天算（end=True 取 23:59:59，否则 00:00:00）。
+    """
+    s = (value or "").strip().replace("T", " ")
+    if not s:
+        return ""
+    if len(s) == 10:                      # 只给了日期 → 按整天
+        return s + (" 23:59:59" if end else " 00:00:00")
+    if len(s) == 16:                      # YYYY-MM-DD HH:MM
+        return s + (":59" if end else ":00")
+    return s[:19]
+
+
+def _iter_filtered(fh, keyword, min_level, since, until, stats=None):
+    """逐行读文件，产出命中的 {ts, level, module, msg, cont}。
+
+    过滤口径：
+      - 时间/级别用**继承值**——续行（traceback 的缩进行等）本身没有前缀，
+        继承上一条带前缀的行，这样按 ERROR 筛选时整段堆栈不会被拆散；
+      - 关键字匹配本行原文（续行也参与），大小写不敏感。
+
+    stats（可选 dict）里回填 scanned：本次实际读了多少行（用于告诉用户
+    "是读到文件开头了，还是被行数上限截断的"）。
+    """
+    kw = (keyword or "").strip().lower()
+    floor = _LEVEL_ORDER.get((min_level or "").upper(), 0)
+    cur_ts = cur_level = cur_module = ""
+    for raw in fh:
+        if stats is not None:
+            stats["scanned"] += 1
+        line = raw.rstrip("\r\n")
+        m = _LINE_RE.match(line)
+        if m:
+            cur_ts, cur_level, cur_module, msg = m.groups()
+            cont = False
+        else:
+            # 续行（traceback、被切成多行的长消息）：沿用上一条的元信息
+            msg, cont = line, True
+        if since and (not cur_ts or cur_ts < since):
+            continue
+        if until and (not cur_ts or cur_ts > until):
+            continue
+        if floor and _LEVEL_ORDER.get(cur_level, 0) < floor:
+            continue
+        if kw and kw not in line.lower():
+            continue
+        yield {"ts": cur_ts, "level": cur_level, "module": cur_module,
+               "msg": msg, "cont": cont}
+
+
+def query_log(name, keyword="", min_level="", since="", until="",
+              limit=300, max_scan=_MAX_SCAN_LINES):
+    """取日志文件里**最近** limit 条满足条件的行。
+
+    返回 dict：
+      rows      — [{ts, level, module, msg, cont}]，保持文件原顺序（旧→新）
+      matched   — 命中总数（可能大于 len(rows)：更早的命中没返回）
+      scanned   — 实际读了多少行（达到 max_scan 说明是被上限截断的）
+      truncated — matched > len(rows)，即"还有更早的命中没显示"
+      error     — 出错时的原因（如文件不存在）
+
+    正序读整文件 + deque 保留最后 N 条：文件被 RollingFileHandler 限在 10MB
+    （约 10 万行），整读一次百毫秒级；换来的是续行能正确继承时间戳——倒着
+    读的写法在遇到 traceback 时必须把续行攒着等前面那行，容易出错。
+    """
+    # 白名单：`name` 必须来自 list_log_files()，否则一律拒绝（防目录穿越）
+    if name not in {f["name"] for f in list_log_files()}:
+        return {"rows": [], "matched": 0, "scanned": 0, "truncated": False,
+                "error": "日志文件不存在或不可读取"}
+    since, until = norm_ts(since), norm_ts(until, end=True)
+    try:
+        keep = max(1, min(int(limit or 300), 5000))
+    except (TypeError, ValueError):
+        keep = 300
+    rows, matched, stats = deque(maxlen=keep), 0, {"scanned": 0}
+    try:
+        with open(os.path.join(_LOG_DIR, name), encoding="utf-8",
+                  errors="replace") as fh:
+            for row in _iter_filtered(fh, keyword, min_level, since, until, stats):
+                matched += 1
+                rows.append(row)
+                if stats["scanned"] >= max_scan:
+                    break
+    except OSError as e:
+        return {"rows": [], "matched": 0, "scanned": 0, "truncated": False,
+                "error": f"读取失败: {e}"}
+    return {"rows": list(rows), "matched": matched, "scanned": stats["scanned"],
+            "truncated": matched > len(rows), "error": ""}
+
+
+def read_log_text(name, keyword="", min_level="", since="", until="",
+                  limit=200000):
+    """导出用的整段文本：命中行按原格式拼回去（下载按钮）。
+
+    没给任何条件时直接读整个文件（含滚动历史由调用方选定的那一个）。
+    """
+    if name not in {f["name"] for f in list_log_files()}:
+        return None, "日志文件不存在或不可读取"
+    since, until = norm_ts(since), norm_ts(until, end=True)
+    any_filter = bool((keyword or "").strip() or min_level or since or until)
+    path = os.path.join(_LOG_DIR, name)
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            if not any_filter:
+                return fh.read(), ""
+            buf, n = [], 0
+            for row in _iter_filtered(fh, keyword, min_level, since, until):
+                if row["cont"]:
+                    buf.append(row["msg"])          # 续行原样输出
+                else:
+                    buf.append(f"{row['ts']} [{row['level']}] "
+                               f"[{row['module']}] {row['msg']}")
+                n += 1
+                if n >= limit:
+                    buf.append(f"...（已达导出上限 {limit} 行，请缩小时间范围）")
+                    break
+            return "\n".join(buf) + ("\n" if buf else ""), ""
+    except OSError as e:
+        return None, f"读取失败: {e}"

core/models.py

@@ -17,6 +17,7 @@
 import os
 import json
 import hashlib
+import sqlite3
 
 from flask_sqlalchemy import SQLAlchemy
 from flask_login import UserMixin
@@ -31,12 +32,33 @@ _log = get_logger("core.models")
 db = SQLAlchemy()
 
 
+def _long_text():
+    """长文本列：SQLite 用 TEXT，MySQL 用 MEDIUMTEXT。
+
+    裸 TEXT 在 MySQL 只有 64KB（而且是"字节"），AI 会话消息、任务参数这类
+    JSON 文本很容易超；超了在严格模式下直接报错（不是截断）。
+    """
+    from sqlalchemy.dialects.mysql import MEDIUMTEXT
+    return db.Text().with_variant(MEDIUMTEXT(), "mysql")
+
+
+def _DOUBLE():
+    """REAL/DOUBLE：MySQL 的 FLOAT 是单精度，评分这类值会出现 7.8000001 这种尾巴。"""
+    from sqlalchemy.dialects.mysql import DOUBLE
+    return DOUBLE()
+
+
 @event.listens_for(Engine, "connect")
 def _sqlite_pragma(dbapi_connection, connection_record):
     """SQLite 并发写优化：WAL 模式 + 忙等待超时 + 降同步级别。
 
     多 worker 后台线程同时写库（任务参数/分组）时，避免 database is locked。
+
+    注意：这个监听器挂在 Engine 基类上，对**所有方言**的连接都会触发；
+    MySQL 下执行 PRAGMA 会直接报语法错误导致连接失败，所以必须先判类型。
     """
+    if not isinstance(dbapi_connection, sqlite3.Connection):
+        return
     cursor = dbapi_connection.cursor()
     cursor.execute("PRAGMA journal_mode=WAL")
     cursor.execute("PRAGMA busy_timeout=5000")
@@ -261,35 +283,162 @@ class PendingDevice(db.Model):
                 "fingerprint": self.fingerprint or ""}
 
 
-# 版本化 schema 迁移：新增结构变更时在此追加 (版本号, 说明, SQL)
+class AppMeta(db.Model):
-# 版本号单调递增，只执行比当前 schema_version 新的迁移。
+    """全局 KV 配置（AI 配置、设备发现参数、schema_version、库环境标签…）。
+
+    ⚠️ 列名沿用历史的 `key`/`value`：**`key` 在 MySQL 里是保留字**，
+    因此不要直接拼裸 SQL 读写本表，统一走 `core/db_config.meta_get/meta_set`
+    （方言中立、自动按方言加引号）。
+
+    ORM 属性名用 `k`：`key` 在 SQLAlchemy 声明式 API 里是保留名，不能直接当属性。
+    """
+    __tablename__ = "app_meta"
+    k = db.Column("key", db.String(64), primary_key=True)
+    value = db.Column(db.Text)
+
+    def __repr__(self):
+        return f"<AppMeta {self.k}>"
+
+
+class AgentExperience(db.Model):
+    """AI 控制台经验记忆：任务成功后的操作配方，下次相似任务检索注入。
+
+    recipe/tool_seq 存 JSON 文本；hits 是被召回引用的次数（巡检按它判重要性）。
+    """
+    __tablename__ = "agent_experience"
+    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
+    task_prompt = db.Column(_long_text(), default="")
+    recipe = db.Column(_long_text(), default="")
+    tool_seq = db.Column(_long_text(), default="")
+    hits = db.Column(db.Integer, default=0)
+    created_at = db.Column(db.String(20), default="")
+
+    def __repr__(self):
+        return f"<AgentExperience {self.id}>"
+
+
+class ExperienceAudit(db.Model):
+    """经验巡检记录（AI 质检）：疑似有问题的经验标 pending，删除只走人工确认。"""
+    __tablename__ = "experience_audit"
+    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
+    exp_id = db.Column(db.Integer, nullable=False)          # 对应的 agent_experience.id
+    verdict = db.Column(db.String(20), default="")          # keep / delete
+    score = db.Column(db.Float().with_variant(_DOUBLE(), "mysql"), default=0)
+    reason = db.Column(_long_text(), default="")
+    hits = db.Column(db.Integer, default=0)                 # 巡检时的引用次数
+    action = db.Column(db.String(20), default="pending")    # pending/kept/deleted
+    audited_at = db.Column(db.String(20), default="")
+
+
+class AgentAction(db.Model):
+    """动作库：带语义名的可复用动作单元（含元素定位、不含坐标）。
+
+    与任务级配方（agent_experience）互补；执行前按 name/别名/App 召回注入。
+    """
+    __tablename__ = "agent_action"
+    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
+    name = db.Column(db.String(120), nullable=False)
+    app = db.Column(db.String(80), default="")
+    aliases = db.Column(_long_text(), default="[]")
+    params = db.Column(_long_text(), default="[]")
+    steps = db.Column(_long_text(), nullable=False)
+    preconditions = db.Column(_long_text(), default="")
+    hits = db.Column(db.Integer, default=0)
+    source_prompt = db.Column(_long_text(), default="")
+    created_at = db.Column(db.String(20), default="")
+    updated_at = db.Column(db.String(20), default="")
+
+
+class DeviceInstallLog(db.Model):
+    """设备端应用商店的下载/安装记录（设备上的 Agent 上报，平台侧展示）。
+
+    平台**不主动**发起这条通道的安装：设备自己拉清单、自己下载、自己调
+    PackageInstaller 安装——这样走的是普通应用安装流程，不会触发 MIUI 针对
+    `adb install` 的「USB 安装」拦截（USER_RESTRICTED）。
+    """
+    __tablename__ = "device_install_log"
+    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
+    fingerprint = db.Column(db.String(120), default="")   # ro.serialno，识别物理设备
+    serial = db.Column(db.String(120), default="")        # 上报时的地址（可能换过）
+    device_name = db.Column(db.String(80), default="")    # 平台侧的名称（快照）
+    apk_id = db.Column(db.String(32), default="")
+    package_name = db.Column(db.String(200), default="")
+    version_name = db.Column(db.String(50), default="")
+    action = db.Column(db.String(20), default="")         # download / install_ok / install_fail
+    message = db.Column(db.String(500), default="")       # 失败原因等
+    created_at = db.Column(db.String(20), default="")
+
+
+class TaskStepLog(db.Model):
+    """任务步骤明细：每一次步骤执行的落库记录（「日志 → 步骤明细」页）。
+
+    与 `logs/task.log` 的分工：文本日志是**排障时的原始现场**（什么都往里写、
+    10MB 滚动），本表是**结构化的一份**——设备/任务/步骤/结果/耗时都是列，
+    所以能按设备、任务、时间、结果过滤和统计，文本日志只能 grep。
+
+    写入方是 `core/step_log.py` 的专用写线程（异步批量落库），**任务线程不直接
+    写库**：一次运行可能上万步，每步一次 INSERT 会拖慢热路径。
+
+    保留期由 `core/step_log.py` 的清理任务控制（默认 14 天，见该模块常量）。
+    """
+    __tablename__ = "task_step_log"
+    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
+    run_id = db.Column(db.String(24), default="", index=True)   # 一次运行=设备×任务×第几次尝试
+    job_id = db.Column(db.String(32), default="")
+    job_name = db.Column(db.String(120), default="")
+    serial = db.Column(db.String(120), default="")
+    device_name = db.Column(db.String(80), default="")
+    step_path = db.Column(db.String(32), default="")      # 嵌套位置，如 "2.1.3"
+    step_label = db.Column(db.String(120), default="")
+    step_type = db.Column(db.String(40), default="")      # click_el / loop / input_text …
+    selector = db.Column(db.String(300), default="")      # 元素选择器（长选择器截断）
+    result = db.Column(db.String(16), default="")         # ok/skip/miss/error/unknown/cap
+    detail = db.Column(db.String(500), default="")        # 异常消息、跳过原因等
+    duration_ms = db.Column(db.Integer, default=0)
+    created_at = db.Column(db.String(20), default="", index=True)
+
+    __table_args__ = (
+        db.Index("ix_step_log_serial_ts", "serial", "created_at"),
+        db.Index("ix_step_log_job_ts", "job_id", "created_at"),
+    )
+
+
+class AgentConversation(db.Model):
+    """AI 控制台会话：整个消息序列以 JSON 存在一行里（单会话几十 KB，够用）。"""
+    __tablename__ = "agent_conversation"
+    id = db.Column(db.String(20), primary_key=True)
+    title = db.Column(db.String(100), default="")
+    messages = db.Column(_long_text(), default="[]")
+    created_at = db.Column(db.String(20), default="")
+    updated_at = db.Column(db.String(20), default="")
+
+
+# 版本化 schema 迁移账本 (版本号, 说明, 数据回填 SQL 或 None)
+#
+# 注意：**建表与补列不再由这张表驱动**——改由 db.create_all() + _sync_columns()
+# 按模型定义自动完成（SQLite / MySQL 两种方言都正确）。这里只保留：
+#   - 版本号（写进 app_meta.schema_version，备份/恢复时用来判断新旧）
+#   - 未来可能需要的数据回填语句（纯数据操作，与方言无关）
+# 历史条目（v1~v6 建表/加列）保留在账本里以便追溯，SQL 位置一律为 None。
 SCHEMA_MIGRATIONS = [
-    (1, "用户权限位：user 表新增 perms 列（JSON 数组，默认空=无业务权限，管理员不受限）",
+    (1, "用户权限位：user 表新增 perms 列（JSON 数组，默认空=无业务权限，管理员不受限）", None),
-     "ALTER TABLE user ADD COLUMN perms TEXT DEFAULT '[]'"),
+    (2, "设备池：device 表（本地设备清单，替代 STF 池）", None),
-    (2, "设备池：device 表（本地设备清单，替代 STF 池）",
+    (3, "设备池：device 表新增 model 列（型号，在线时自动采集）", None),
-     "CREATE TABLE IF NOT EXISTS device ("
+    (4, "自动发现：pending_device 待连接池表（扫描发现的设备，用户确认后才入正式池）", None),
-     "serial VARCHAR(120) PRIMARY KEY,"
+    (5, "设备池：device 表新增 fingerprint 列（设备指纹 ro.serialno，换 IP 后认领回原记录）", None),
-     "name VARCHAR(80) DEFAULT '',"
+    (6, "自动发现：pending_device 表新增 fingerprint 列（扫描时读取，用于提示是已有设备换了 IP）", None),
-     "enabled BOOLEAN DEFAULT 1,"
-     "note TEXT DEFAULT '',"
-     "created_at VARCHAR(20) DEFAULT '')"),
-    (3, "设备池：device 表新增 model 列（型号，在线时自动采集）",
-     "ALTER TABLE device ADD COLUMN model TEXT DEFAULT ''"),
-    (4, "自动发现：pending_device 待连接池表（扫描发现的设备，用户确认后才入正式池）",
-     "CREATE TABLE IF NOT EXISTS pending_device ("
-     "serial VARCHAR(120) PRIMARY KEY,"
-     "source VARCHAR(20) DEFAULT '',"
-     "first_seen VARCHAR(20) DEFAULT '',"
-     "last_seen VARCHAR(20) DEFAULT '')"),
-    (5, "设备池：device 表新增 fingerprint 列（设备指纹 ro.serialno，换 IP 后认领回原记录）",
-     "ALTER TABLE device ADD COLUMN fingerprint VARCHAR(120) DEFAULT ''"),
-    (6, "自动发现：pending_device 表新增 fingerprint 列（扫描时读取，用于提示是已有设备换了 IP）",
-     "ALTER TABLE pending_device ADD COLUMN fingerprint VARCHAR(120) DEFAULT ''"),
 ]
 
-# 唯一索引（部分索引：空值不参与唯一约束，兼容历史未命名/未采指纹的老数据）
+# 当前 schema 版本（备份/恢复用它判断新旧，也写进 app_meta.schema_version）
+CURRENT_SCHEMA_VERSION = max(v for v, _, _ in SCHEMA_MIGRATIONS)
+
+# 唯一索引（语义 = 部分索引：空值不参与唯一约束，兼容历史未命名/未采指纹的老数据）
 # 名称唯一 = 设备的人可读标识；指纹唯一 = 一台物理设备在池中只能有一条记录
-_UNIQUE_INDEXES = (
+#
+# SQLite 支持带 WHERE 的部分索引，直接写；MySQL 5.7 不支持过滤索引，
+# 改用「虚拟生成列 + 唯一索引」复刻同一语义（唯一索引允许多个 NULL）——
+# 见 _ensure_unique_indexes() 的 MySQL 分支。
+_UNIQUE_INDEXES_SQLITE = (
     ("ux_device_name", "CREATE UNIQUE INDEX IF NOT EXISTS ux_device_name "
                        "ON device(name) WHERE name IS NOT NULL AND name <> ''"),
     ("ux_device_fingerprint", "CREATE UNIQUE INDEX IF NOT EXISTS ux_device_fingerprint "
@@ -297,66 +446,118 @@ _UNIQUE_INDEXES = (
                               "AND fingerprint <> ''"),
 )
 
+# MySQL：为空值生成 NULL 的伴随列，唯一索引建在它上面
+_MYSQL_UQ_COLUMNS = (
+    # (表, 源列, 生成列名, 生成列类型)
+    ("device", "name", "name_uq", "VARCHAR(80)"),
+    ("device", "fingerprint", "fingerprint_uq", "VARCHAR(120)"),
+)
+_MYSQL_UNIQUE_INDEXES = (
+    ("ux_device_name", "device", "name_uq"),
+    ("ux_device_fingerprint", "device", "fingerprint_uq"),
+)
+
 
 def init_db(app):
     """在 Flask app context 里初始化数据库 + 创建默认管理员。
 
-    web_server 启动时调用。自动迁移旧 groups.json/jobs.json 到 SQLite。
+    web_server 启动时调用。自动迁移旧 groups.json/jobs.json 到数据库。
+
+    顺序：建表（create_all）→ 补列（_sync_columns）→ 版本账本 → 唯一索引 → 管理员/旧 JSON。
+    建表与补列都以模型定义为准，SQLite / MySQL 两种方言自动匹配，不再手写 DDL。
     """
     db.init_app(app)
     with app.app_context():
         db.create_all()
+        _sync_columns()
         _migrate_schema()
+        _ensure_unique_indexes()
         _ensure_default_admin()
         _migrate_old_json()
 
 
-def _migrate_schema():
+def _sync_columns():
-    """按 SCHEMA_MIGRATIONS 顺序执行版本化迁移，记录当前 schema_version。
+    """按模型定义补齐"实表缺的列"（幂等）。
 
-    create_all 只负责首次建表；结构变更必须走迁移，避免改了模型后老库对不上。
+    取代原来靠 "duplicate column name" 报错文本判断的老写法：那是 SQLite 时代的
+    容错路径，换 MySQL 后报错文本/错误码都不同，靠字符串匹配太脆。
+    现在直接读数据库元数据（sqlalchemy.inspect）比对，缺什么补什么。
     """
+    from sqlalchemy import inspect
+    from sqlalchemy.schema import CreateColumn
+
     try:
-        db.session.execute(text(
+        insp = inspect(db.engine)
-            "CREATE TABLE IF NOT EXISTS app_meta (key TEXT PRIMARY KEY, value TEXT)"))
+        existing = set(insp.get_table_names())
-        db.session.commit()
+    except Exception as e:
-        cur = db.session.execute(
+        _log.error(f"读取表结构失败，跳过补列: {e}")
-            text("SELECT value FROM app_meta WHERE key='schema_version'")).scalar()
+        return
-        current = int(cur) if cur else 0
+
-        for version, desc, sql in SCHEMA_MIGRATIONS:
+    added = []
+    for table in db.metadata.sorted_tables:
+        if table.name not in existing:
+            continue                                  # 缺整表交给 create_all
+        try:
+            have = {c["name"] for c in insp.get_columns(table.name)}
+        except Exception as e:
+            _log.warning(f"读取 {table.name} 列失败: {e}")
+            continue
+        for col in table.columns:
+            if col.name in have:
+                continue
+            try:
+                ddl = CreateColumn(col).compile(dialect=db.engine.dialect)
+                db.session.execute(
+                    text("ALTER TABLE {} ADD COLUMN {}".format(table.name, ddl)))
+                db.session.commit()
+                added.append(f"{table.name}.{col.name}")
+            except Exception as e:
+                db.session.rollback()
+                _log.warning(f"补列失败 {table.name}.{col.name}: {e}")
+    if added:
+        _log.info("schema 补列: " + ", ".join(added))
+
+
+def _migrate_schema():
+    """维护 schema_version 账本 + 执行数据回填类迁移。
+
+    建表/加列已由 create_all + _sync_columns 按模型自动完成，本函数不再写 DDL；
+    SCHEMA_MIGRATIONS 里带 SQL 的条目只允许是方言无关的数据操作。
+    """
+    from core import db_config
+    try:
+        try:
+            current = int(db_config.meta_get("schema_version") or 0)
+        except Exception:
+            current = 0
+        for version, desc, backfill_sql in SCHEMA_MIGRATIONS:
             if version <= current:
                 continue
-            if sql:
+            if backfill_sql:
                 try:
-                    db.session.execute(text(sql))
+                    db.session.execute(text(backfill_sql))
+                    db.session.commit()
                 except Exception as e:
-                    # 幂等兜底：目标结构已存在也视为该迁移生效。典型场景——
-                    # create_all 已按当前模型把列/表直接建好（如 perms、device.model），
-                    # 而 schema_version 又因历史中断没记录，导致每次启动重复 ALTER 报错。
-                    # duplicate column name 说明列已存在=迁移目标已达成：回滚本次语句后
-                    # 仍记录版本号，一次启动即自愈；其它异常才中止本批迁移。
-                    if "duplicate column name" not in str(e).lower():
-                        raise
                     db.session.rollback()
-                    _log.info(f"schema 迁移 {version} 目标已存在，跳过: {desc}")
+                    _log.error(f"迁移 v{version} 数据回填失败: {e}")
-            db.session.execute(
+            _log.info(f"schema 迁移到版本 {version}（结构由模型自动同步）: {desc}")
-                text("INSERT OR REPLACE INTO app_meta(key,value) VALUES('schema_version',:v)"),
+        if current < CURRENT_SCHEMA_VERSION:
-                {"v": str(version)})
+            db_config.meta_set("schema_version", str(CURRENT_SCHEMA_VERSION))
-            db.session.commit()
-            _log.info(f"schema 迁移到版本 {version}: {desc}")
-        _ensure_unique_indexes()
     except Exception as e:
         _log.error(f"schema 迁移失败（不阻塞启动）: {e}")
 
 
 def _ensure_unique_indexes():
-    """建设备池的唯一索引（幂等）。
+    """建"空值不参与唯一约束"的设备名/指纹唯一索引（幂等，方言分叉）。
 
     单独抽出来是因为索引不属于某个版本迁移：老库升级后也要补建。
     历史数据若存在重复（名称/指纹撞车），建索引会失败——只告警不回滚、
     不阻塞启动，由管理页提示用户改名（唯一约束从此刻起对新数据生效）。
     """
-    for name, sql in _UNIQUE_INDEXES:
+    if db.engine.dialect.name == "mysql":
+        _ensure_unique_indexes_mysql()
+        return
+    for name, sql in _UNIQUE_INDEXES_SQLITE:
         try:
             db.session.execute(text(sql))
             db.session.commit()
@@ -365,6 +566,44 @@ def _ensure_unique_indexes():
             _log.warning(f"唯一索引 {name} 创建失败（历史数据可能有重复）: {e}")
 
 
+def _ensure_unique_indexes_mysql():
+    """MySQL 5.7 没有过滤索引，用「虚拟生成列 + 唯一索引」复刻部分索引语义。
+
+    生成列把空值映射成 NULL，而唯一索引允许多个 NULL —— 正好等于
+    「空值不参与唯一约束」。生成列不进 ORM 模型（进了 create_all 会尝试写入它
+    并报 Error 3105），所以只能在这里用 DDL 补。
+    """
+    from sqlalchemy import inspect
+    coll = "utf8mb4_bin"   # 与库默认一致：逐码点比较，等价 SQLite 的大小写敏感
+    for table, col, gen, typ in _MYSQL_UQ_COLUMNS:
+        try:
+            have = {c["name"] for c in inspect(db.engine).get_columns(table)}
+            if gen in have:
+                continue
+            db.session.execute(text(
+                "ALTER TABLE {t} ADD COLUMN {g} {ty} COLLATE {coll} "
+                "GENERATED ALWAYS AS (IF({c} IS NULL OR {c} = '', NULL, {c})) VIRTUAL"
+                .format(t=table, g=gen, ty=typ, coll=coll, c=col)))
+            db.session.commit()
+            _log.info(f"已建生成列 {table}.{gen}（部分唯一索引的 MySQL 替代）")
+        except Exception as e:
+            db.session.rollback()
+            _log.warning(f"生成列 {table}.{gen} 创建失败: {e}")
+
+    for name, table, gen in _MYSQL_UNIQUE_INDEXES:
+        try:
+            have = {i["name"] for i in inspect(db.engine).get_indexes(table)}
+            if name in have:
+                continue
+            db.session.execute(
+                text("CREATE UNIQUE INDEX {} ON {}({})".format(name, table, gen)))
+            db.session.commit()
+            _log.info(f"已建唯一索引 {name}")
+        except Exception as e:
+            db.session.rollback()
+            _log.warning(f"唯一索引 {name} 创建失败（历史数据可能有重复）: {e}")
+
+
 def _ensure_default_admin():
     """首次启动创建默认管理员 admin/admin123。"""
     if not User.query.filter_by(username="admin").first():

core/notify_events.py

@@ -0,0 +1,219 @@
+"""通知事件目录（**唯一真相**）。
+
+约定：
+- **key 点分层**：`模块.对象.动作`（如 `task.device.failed`），支持通配订阅
+  （`task.*`、`device.*`、`*`），匹配规则见 `match()`。
+- **登记 ≠ 会发**：所有事件 `default` 一律 False —— 用户在「系统 → 通知」里
+  按 webhook 勾选才会推送。`recommend` 只用于界面高亮"建议开启"，不改默认值。
+- **聚合**：`agg_window` 秒内的同 `(hook, event, agg_key 取值)` 事件合并成一条
+  （保留前几个样本）；`agg_window=0` = 不聚合，立即发（低频高危事件用它）。
+- **fields**：该事件保证携带的上下文字段，供前端画字段表、也是模板占位符白名单。
+
+新增事件：在 `EVENTS` 里加一条 + 在触发点调 `notifier.notify(key, **fields)`，
+并同步 `doc/NOTIFY.md` 的事件表（见 doc/README.md 的文档同步红线）。
+"""
+from collections import namedtuple
+
+# key, label, category, default, recommend, agg_window, agg_key, fields, desc
+EventDef = namedtuple(
+    "EventDef",
+    "key label category default recommend agg_window agg_key fields desc")
+
+
+def _e(key, label, category, fields, desc="", agg_window=30, agg_key=None,
+       recommend=False):
+    """构造一条事件定义（default 恒为 False：登记不等于推送）。"""
+    return EventDef(key, label, category, False, recommend, agg_window,
+                    agg_key, tuple(fields), desc)
+
+
+# 聚合键：按"任务批次"合并（同一次任务的多台设备结果合成一条）
+_BY_JOB = ("job_id",)
+# 按"设备"合并（一台设备的重复抖动合成一条）
+_BY_SERIAL = ("serial",)
+
+EVENTS = [
+    # ---------------- 任务批次 ----------------
+    _e("task.batch.started", "任务批次开始", "任务批次",
+       ["job_id", "job_name", "task_type", "device_count", "serials_preview"],
+       "一次任务开始铺开到 N 台设备", agg_window=0, recommend=True),
+    _e("task.batch.finished", "任务批次结束", "任务批次",
+       ["job_id", "job_name", "total", "success", "failed", "stopped", "skipped",
+        "failed_devices", "duration_s"],
+       "整批跑完（成功/失败/停止台数 + 耗时；有失败时列出失败设备与型号）",
+       agg_window=0, recommend=True),
+    _e("task.batch.no_device", "任务无可用设备", "任务批次",
+       ["job_id", "job_name", "target"],
+       "触发时一台可用设备都没有（任务空跑）", agg_window=0, recommend=True),
+    _e("task.batch.unknown_type", "任务类型不存在", "任务批次",
+       ["job_id", "job_name", "task_type"],
+       "任务类型已从代码里删掉，任务永远不会执行", agg_window=0, recommend=True),
+    _e("task.cron.stopped", "定时停止任务", "任务批次",
+       ["job_id", "job_name", "stopped_count", "serials"],
+       "cron_stop 到点，停掉了正在跑的设备", agg_window=0),
+
+    # ---------------- 任务 · 单设备（权威结论点） ----------------
+    _e("task.device.success", "设备任务成功", "任务·单设备",
+       ["serial", "device_name", "model", "job_id", "job_name", "attempt", "duration_s"],
+       "某台设备上的任务最终成功。**只在目标设备只有 1 台时发送**——多设备批次看"
+       "「任务批次结束」就够了，13 台设备就是 13 条刷屏", agg_key=_BY_JOB),
+
+    _e("task.device.failed", "设备任务失败", "任务·单设备",
+       ["serial", "device_name", "model", "job_id", "job_name", "attempts",
+        "cause", "msg"],
+       "某台设备上的任务最终失败（带真实原因与型号）", agg_key=_BY_JOB, recommend=True),
+    _e("task.device.offline", "设备离线放弃", "任务·单设备",
+       ["serial", "device_name", "model", "job_id", "job_name", "error"],
+       "设备离线，不重试直接失败", agg_key=_BY_JOB, recommend=True),
+    _e("task.device.error", "单次尝试异常", "任务·单设备",
+       ["serial", "device_name", "model", "job_name", "attempt", "error"],
+       "某次尝试抛异常（后面还会重试，噪音较大）", agg_key=_BY_JOB),
+    _e("task.device.retry", "设备任务重试", "任务·单设备",
+       ["serial", "device_name", "job_name", "attempt", "next_attempt", "delay_s", "reason"],
+       "即将重试", agg_key=_BY_JOB),
+    _e("task.device.stopped", "设备任务被停止", "任务·单设备",
+       ["serial", "device_name", "model", "job_name", "attempt", "phase"],
+       "用户手动停止 / cron 停止", agg_key=_BY_JOB),
+    _e("task.device.preempted", "设备被抢占", "任务·单设备",
+       ["serial", "device_name", "job_name", "preempted_job_id", "preempted_job_name"],
+       "本任务抢占了该设备上正在跑的其他任务", agg_key=_BY_JOB, recommend=True),
+    _e("task.device.preempt_timeout", "抢占超时跳过", "任务·单设备",
+       ["serial", "device_name", "job_name", "preempted_job_id"],
+       "等被抢占任务退出超时，本设备放弃执行", agg_window=0, recommend=True),
+    _e("task.device.released", "抢占结束归还", "任务·单设备",
+       ["serial", "device_name", "job_name", "preempted_job_id", "returned", "reason"],
+       "抢占结束时重新拉起被抢占的任务", agg_key=_BY_JOB),
+
+    # ---------------- Worker 状态机（单次 attempt 级，默认关） ----------------
+    _e("worker.connected", "设备已连接", "Worker",
+       ["serial", "model", "remote_adb_url"],
+       "worker 连上设备（单次尝试级，噪音大）"),
+    _e("worker.attempt.done", "单次执行完成", "Worker",
+       ["serial", "task_type", "duration_s", "max_duration_hit"],
+       "单次 attempt 正常跑完（不代表任务最终成功）"),
+    _e("worker.attempt.error", "单次执行出错", "Worker",
+       ["serial", "task_type", "error", "transient"],
+       "单次 attempt 抛异常"),
+
+    # ---------------- 业务（任务内容） ----------------
+    _e("task.patrol.hit", "任务巡检命中", "业务",
+       ["title", "message", "patrol_name", "check_label", "detail", "action_label",
+        "job_id", "job_name", "serial", "device_name", "model"],
+       "任务里配置的「公共巡检」命中（熄屏/元素/前台…），已执行动作——"
+       "标题正文可在巡检项里自己写，支持 {device}/{job}/{time}/{app}/{screen}",
+       agg_window=0, recommend=True),
+    _e("task.notify.custom", "任务自定义通知", "业务",
+       ["title", "message", "job_id", "job_name", "serial", "device_name", "model"],
+       "任务里的「发通知」步骤被触发——标题与正文由任务自己写，支持 "
+       "{device}/{serial}/{job}/{time}/{app}/{screen} 占位符", agg_window=0,
+       recommend=True),
+    _e("task.selector.invalid", "选择器连续失效", "业务",
+       ["serial", "device_name", "selector", "miss_count"],
+       "某选择器连续 10 次未命中——任务可能显示成功但什么都没做", agg_window=0,
+       recommend=True),
+
+    # ---------------- 设备 ----------------
+    _e("device.online", "设备恢复在线", "设备",
+       ["serials", "count"],
+       "原本断联的设备又能连上了", agg_window=0, recommend=True),
+    _e("device.offline", "设备断联", "设备",
+       ["serials", "count", "devices"],
+       "设备池里的设备连不上了", agg_window=0, recommend=True),
+    _e("device.discovered", "发现新设备", "设备",
+       ["serials", "count"],
+       "扫描到尚未在池内的设备（待认领）", agg_window=0),
+    _e("device.claimed", "设备自动认领", "设备",
+       ["pairs", "count"],
+       "指纹匹配成功，自动把旧记录迁到新地址", agg_window=0),
+    _e("device.heartbeat_timeout", "心跳超时", "设备",
+       ["serial", "device_name", "timeout_s", "task_job", "model"],
+       "设备卡死（长时间没心跳），任务可能已中断", agg_window=0, recommend=True),
+
+    # ---------------- 应用安装 ----------------
+    _e("apk.install.started", "应用安装开始", "安装",
+       ["apk_id", "apk_name", "package_name", "total"],
+       "开始往 N 台设备推装", agg_window=0),
+    _e("apk.install.finished", "应用安装完成", "安装",
+       ["apk_name", "success", "failed", "skipped", "total", "failed_items"],
+       "批量安装结束（含失败台数与原因）", agg_window=0, recommend=True),
+
+    # ---------------- 系统 ----------------
+    _e("system.backup.exported", "备份已导出", "系统",
+       ["filename", "size", "tables", "include_apk", "user"],
+       "有人导出了整库备份", agg_window=0, recommend=True),
+    _e("system.backup.imported", "备份导入已挂起", "系统",
+       ["token_prefix", "env_label", "force"],
+       "上传了备份并确认导入（重启后生效）", agg_window=0),
+    _e("system.backup.restored", "备份已恢复", "系统",
+       ["applied_rows", "schema_version"],
+       "启动时应用了待恢复的备份（所以这条是重启后才发）", agg_window=0,
+       recommend=True),
+    _e("system.backup.restore_failed", "备份恢复失败", "系统",
+       ["error", "fail_dir"],
+       "恢复校验没过，已搁置（数据未被改动）", agg_window=0, recommend=True),
+    _e("service.started", "服务已启动", "系统",
+       ["version", "env", "db_target", "device_count", "job_count"],
+       "平台进程起来了", agg_window=0, recommend=True),
+    _e("service.stopping", "服务正在停止", "系统",
+       ["uptime_s"],
+       "平台进程收到退出信号", agg_window=0),
+    _e("user.login", "用户登录", "系统",
+       ["username"],
+       "有人登录了后台", agg_window=0),
+
+    # ---------------- AI ----------------
+    _e("ai.audit.finished", "经验巡检完成", "AI",
+       ["reviewed", "suggested", "summary"],
+       "每日经验库巡检跑完（或手动触发）", agg_window=0, recommend=True),
+    _e("ai.audit.failed", "经验巡检异常", "AI",
+       ["error"],
+       "巡检过程中报错", agg_window=0),
+    _e("ai.audit.skipped", "经验巡检跳过", "AI",
+       ["reason"],
+       "没配模型 Key 等原因跳过巡检", agg_window=0),
+
+    # ---------------- 其它 ----------------
+    _e("notify.test", "测试通知", "其它",
+       ["hook_name", "operator"],
+       "「发送测试」按钮专用", agg_window=0),
+]
+
+BY_KEY = {e.key: e for e in EVENTS}
+
+# 界面上的分组顺序
+CATEGORIES = ("任务批次", "任务·单设备", "业务", "设备", "安装", "系统", "AI",
+              "Worker", "其它")
+
+
+def get(key):
+    """按 key 取事件定义；未知 key 返回 None（未知事件会被 notify 丢弃）。"""
+    return BY_KEY.get(key)
+
+
+def match(pattern, key):
+    """事件订阅匹配。
+
+    - `*`             → 全部
+    - `task.*`        → task 下所有（含 task.device.failed）
+    - `task.device.*` → 任意层级前缀匹配
+    - `task.device.failed` → 精确
+    """
+    if not pattern:
+        return False
+    if pattern == "*" or pattern == key:
+        return True
+    if pattern.endswith(".*"):
+        return key.startswith(pattern[:-1])      # "task.*" → "task."
+    return False
+
+
+def list_events():
+    """给接口/前端用的事件目录（按 CATEGORIES 排序）。"""
+    order = {c: i for i, c in enumerate(CATEGORIES)}
+    rows = [{"key": e.key, "label": e.label, "category": e.category,
+             "default": e.default, "recommend": e.recommend,
+             "agg_window": e.agg_window, "agg_key": list(e.agg_key or ()),
+             "fields": list(e.fields), "desc": e.desc}
+            for e in EVENTS]
+    rows.sort(key=lambda r: (order.get(r["category"], 99), r["key"]))
+    return rows

core/patrol.py

@@ -0,0 +1,110 @@
+"""任务内**公共巡检**：任务运行期间按间隔穿插检查设备状态，命中就动作 + 通知。
+
+和步骤编辑器的关系（重要，别混）：
+
+| | 步骤（`params.steps`） | 公共巡检（`params.watchers`） |
+|---|---|---|
+| 配置位置 | 步骤画布，拖出来的 | 任务编辑器里单独一块 |
+| 执行方式 | 顺序执行 | **穿插**：每执行完一步（以及长等待的每个分片）看一眼"哪个巡检到点了" |
+| 适合什么 | 一段固定流程 | 全程都要盯的守护条件（熄屏就点亮、掉到桌面就通知） |
+
+为什么用穿插而不是另起线程：不需要并发模型，不会和主流程抢屏幕（否则巡检点屏幕、
+主流程也在点，动作会互相打断）。代价是巡检精度受步长影响——某一步卡 30 秒，
+巡检最多晚 30 秒；这也是刻意的取舍（见 doc/TASK_DEV.md §4.5）。
+
+配置结构（`params.watchers` 数组，每项）：
+
+```json
+{"name": "熄屏点亮", "enabled": true, "interval": 60,
+ "check": "screen_off",                    // 见 CHECKS
+ "selector_type": "xpath", "selector_value": "",   // 元素类检查才用
+ "action": "screen_on",                    // 见 ACTIONS
+ "notify": true, "title": "{device} 熄屏了",
+ "message": "任务 {job} 在 {time} 发现 {screen}，已点亮",
+ "cooldown": 300}                          // 命中后多久内不再重复动作/通知（防刷屏）
+```
+"""
+from core.logger import get_logger
+from core.u2_helper import screen_is_on, current_package
+
+_log = get_logger("task.generic")
+
+# 检查项：need 说明该项还要填什么（selector=元素选择器 / package=包名）
+CHECKS = {
+    "screen_off": {"label": "屏幕熄灭", "need": ""},
+    "screen_on": {"label": "屏幕亮着", "need": ""},
+    "element_exists": {"label": "元素存在", "need": "selector"},
+    "element_missing": {"label": "元素不存在", "need": "selector"},
+    "foreground_is": {"label": "前台是该App", "need": "package"},
+    "foreground_not": {"label": "前台不是该App", "need": "package"},
+}
+
+ACTIONS = {
+    "none": {"label": "只发通知，不动设备"},
+    "screen_on": {"label": "点亮屏幕"},
+    "screen_off": {"label": "熄灭屏幕"},
+    "stop_self": {"label": "停止本设备任务"},
+}
+
+# 通知正文里可用的占位符（前端提示、文档、渲染三处共用一份，避免漂移）
+PLACEHOLDERS = ("device", "serial", "job", "time", "app", "screen")
+
+
+def _element_exists(d, sel_type, sel_val):
+    """元素是否存在（不等超时，立即判定）。一次 UI dump 的代价，慢设备上可能要几秒。"""
+    if sel_type == "xpath":
+        return bool(d.xpath(sel_val).exists())
+    return bool(d(**{sel_type: sel_val}).exists())
+
+
+def evaluate(d, spec):
+    """跑一次检查，返回 (是否命中, 一句人话说明)。异常由调用方兜。"""
+    check = str(spec.get("check") or "")
+    val = str(spec.get("selector_value") or "").strip()
+
+    if check in ("screen_off", "screen_on"):
+        state = screen_is_on(d)
+        if state is None:
+            return False, "屏幕状态读不到"
+        hit = (not state) if check == "screen_off" else state
+        return hit, f"屏幕{'亮着' if state else '熄灭'}"
+
+    if check in ("element_exists", "element_missing"):
+        if not val:
+            return False, "没填选择器"
+        found = _element_exists(d, spec.get("selector_type") or "xpath", val)
+        return (found if check == "element_exists" else not found), \
+            f"元素{'存在' if found else '不存在'}"
+
+    if check in ("foreground_is", "foreground_not"):
+        if not val:
+            return False, "没填包名"
+        cur = current_package(d)
+        return (cur == val) if check == "foreground_is" else (cur != val), \
+            f"前台={cur or '未知'}"
+
+    return False, f"未知检查项 {check}"
+
+
+def act(d, spec, worker=None):
+    """执行命中后的动作，返回一句人话（没动作返回空串）。"""
+    action = str(spec.get("action") or "none")
+    if action == "screen_on":
+        d.unlock()                       # 与 screen_on 步骤同语义：唤醒 + 解锁
+        return "已点亮屏幕"
+    if action == "screen_off":
+        d.screen_off()
+        return "已熄灭屏幕"
+    if action == "stop_self":
+        if worker is not None:
+            worker.stop()                # 置停止位，主流程下一步就退出
+        return "已停止本设备任务"
+    return ""
+
+
+def check_label(check):
+    return (CHECKS.get(check) or {}).get("label", check)
+
+
+def action_label(action):
+    return (ACTIONS.get(action) or {}).get("label", action)

core/step_defaults.py

@@ -0,0 +1,148 @@
+"""步骤默认值：新建步骤时预填的参数（后台「任务 → 动作配置」页可改）。
+
+存在 `app_meta.step_defaults` 一个键里（**不建表** → 不碰备份覆盖红线），
+与 `notify_webhooks` 同一套做法：**出厂默认 + 用户覆盖**，读的时候合并。
+
+为什么是"出厂 + 覆盖"而不是只存用户值：以后调整某个步骤的出厂默认时，
+**没配过的字段**会跟着变好，**配过的字段**不动——这符合直觉。
+
+字段白名单 + 范围校验都在这里（`SPEC`）：写进库的东西必须能校验，否则手改
+JSON 塞个奇怪值进去，之后新建步骤就把它带进任务里了。
+
+⚠️ 这里只管**编辑器预填**；`tasks/generic/task.py` 的 `STEP_TYPES` 仍是执行侧
+的默认值来源（AI/MCP 造步骤也用它）。两处都改了要一起同步。
+"""
+import json
+
+# 出厂默认（前端「动作配置」页的初始内容，也是没配过时的回退）
+FACTORY = {
+    "swipe": {"direction": "up", "duration_min": 0.25, "duration_max": 0.5,
+              "distance_ratio": 0.6, "jitter": 0.15, "humanize": True},
+    "click": {"wait_timeout": 2},
+    "long_click": {"duration": 1.0, "wait_timeout": 2},
+    "wait": {"min": 1.0, "max": 3.0},
+    "key_event": {"key": "back"},
+    "input_text": {"mode": "random", "texts": "你好\n有趣\n支持",
+                   "fixed_text": "", "clear_first": True},
+}
+
+# 字段规格：("num", 最小, 最大) / ("bool",) / ("choice", 可选值) / ("text", 最大长度)
+SPEC = {
+    "swipe": {
+        "direction": ("choice", ("up", "down", "left", "right")),
+        "duration_min": ("num", 0.05, 5.0),
+        "duration_max": ("num", 0.05, 5.0),
+        "distance_ratio": ("num", 0.1, 0.9),
+        "jitter": ("num", 0.0, 0.4),
+        "humanize": ("bool",),
+    },
+    "click": {"wait_timeout": ("num", 0.0, 30.0)},
+    "long_click": {"duration": ("num", 0.2, 10.0),
+                   "wait_timeout": ("num", 0.0, 30.0)},
+    "wait": {"min": ("num", 0.1, 600.0), "max": ("num", 0.1, 600.0)},
+    "key_event": {"key": ("text", 30)},
+    "input_text": {"mode": ("choice", ("random", "fixed")),
+                   "texts": ("text", 2000), "fixed_text": ("text", 200),
+                   "clear_first": ("bool",)},
+}
+
+# 与 notifier 的键同住 app_meta（`key` 是 MySQL 保留字，读写只走 db_config.meta_get/set）
+META_KEY = "step_defaults"
+
+
+def factory():
+    """出厂默认的深拷贝（别让调用方改到常量）。"""
+    return json.loads(json.dumps(FACTORY, ensure_ascii=False))
+
+
+def _clean_one(stype, raw):
+    """校验并清洗单个步骤类型的默认值；非法字段**丢弃**（不让脏值进库）。"""
+    spec = SPEC.get(stype)
+    if not spec or not isinstance(raw, dict):
+        return None
+    out = {}
+    for k, v in raw.items():
+        rule = spec.get(k)
+        if not rule:
+            continue
+        kind = rule[0]
+        try:
+            if kind == "bool":
+                out[k] = bool(v)
+            elif kind == "num":
+                n = float(v)
+                lo, hi = rule[1], rule[2]
+                out[k] = max(lo, min(hi, n))
+            elif kind == "choice":
+                s = str(v)
+                if s in rule[1]:
+                    out[k] = s
+            elif kind == "text":
+                out[k] = str(v)[:rule[1]]
+        except (TypeError, ValueError):
+            continue
+    return out or None
+
+
+def clean(raw):
+    """清洗整份配置（只保留白名单里的步骤类型与字段）。"""
+    if not isinstance(raw, dict):
+        return {}
+    out = {}
+    for stype in SPEC:
+        got = _clean_one(stype, raw.get(stype))
+        if got:
+            out[stype] = got
+    return out
+
+
+def merged(user):
+    """出厂默认 + 用户覆盖（按字段合并）。"""
+    out = factory()
+    for stype, vals in (clean(user) or {}).items():
+        out.setdefault(stype, {}).update(vals)
+    return out
+
+
+def get():
+    """当前生效的默认值（读库，必须在 app context 内调）。"""
+    from core.db_config import meta_get
+    raw = meta_get(META_KEY) or ""
+    if not raw:
+        return factory()
+    try:
+        return merged(json.loads(raw))
+    except (ValueError, TypeError):
+        return factory()
+
+
+def save(raw):
+    """保存（只落用户显式给的字段）。返回 (ok, msg)。
+
+    与出厂默认**相同的字段不入库**：这样以后调出厂值，这些字段能跟着更新
+    ——库里只留"用户真的改过"的部分。
+    """
+    from core.db_config import meta_set
+    cleaned = clean(raw)
+    fac = FACTORY
+    diff = {}
+    for stype, vals in cleaned.items():
+        keep = {k: v for k, v in vals.items()
+                if not (stype in fac and k in fac[stype] and fac[stype][k] == v)}
+        if keep:
+            diff[stype] = keep
+    try:
+        meta_set(META_KEY, json.dumps(diff, ensure_ascii=False))
+    except Exception as e:
+        return False, f"保存失败: {e}"
+    return True, "已保存"
+
+
+def as_payload():
+    """给前端的完整载荷：生效值 + 出厂值 + 字段规格（前端据此画表单与范围）。"""
+    spec = {st: {k: (list(r[1]) if r[0] == "choice" else
+                      (list(r[1:]) if r[0] == "num" else None))
+                 for k, r in fields.items()}
+            for st, fields in SPEC.items()}
+    kinds = {st: {k: r[0] for k, r in fields.items()} for st, fields in SPEC.items()}
+    return {"defaults": get(), "factory": factory(), "spec": spec, "kinds": kinds}

core/step_log.py

@@ -0,0 +1,247 @@
+"""任务步骤明细：异步落库（专用写线程）+ 保留期清理。
+
+为什么不让任务线程直接写库：步骤执行是**热路径**（一次运行可能上万步），每步
+一次 INSERT 要建会话、等 MySQL 往返，还会和业务事务抢连接。这里改成「专用写
+线程 + 有界队列」：任务线程只做一次 put_nowait（微秒级），落库、重排、批量都
+在写线程里做。
+
+铁律（与 `core/notifier.py` 一致）：
+  - `record()` 零阻塞、零 DB、**绝不抛异常** —— 记录绝不影响任务执行；
+  - 落库失败只写日志、丢弃该批，**不重排**（不为补数据把内存撑爆）。
+
+线程用裸 `threading.Thread(daemon=True)`（与项目其它后台线程一致；线程池的
+非 daemon 线程会在退出时被 atexit join 卡住）。
+"""
+import queue
+import threading
+import time
+
+from core.logger import get_logger
+
+_log = get_logger("task.step")
+
+# 一次运行最多记录多少条：防「2 小时无限循环」这类任务把表写爆。
+# 达到上限后本次运行不再逐条记，只补一条 cap 说明行。
+MAX_ROWS_PER_RUN = 2000
+
+# 保留天数：每日清理任务删除更早的记录。**这个值直接决定备份包体积**
+# （task_step_log 会进整库备份，见 doc/DATA_MODEL.md §6），改大前先想清楚。
+KEEP_DAYS = 14
+
+# 队列上限与批量：队列满 = 丢弃并计数（宁可丢明细，也不能拖住任务线程）
+_QUEUE_MAX = 5000
+_BATCH = 200
+_FLUSH_INTERVAL = 1.0
+
+_app = None
+_q = queue.Queue(maxsize=_QUEUE_MAX)
+_writer = None
+_stop = threading.Event()
+_stats = {"queued": 0, "written": 0, "dropped": 0, "failed": 0}
+
+
+# ================== 生命周期 ==================
+
+def init_app(app):
+    """启动写线程（web_server 启动时调用；重复调用安全）。"""
+    global _app, _writer
+    _app = app
+    if _writer is not None and _writer.is_alive():
+        return
+    _stop.clear()
+    _writer = threading.Thread(target=_writer_loop, name="step-log-writer",
+                               daemon=True)
+    _writer.start()
+    _log.info(f"步骤明细写线程已启动（保留 {KEEP_DAYS} 天，单次运行上限 "
+              f"{MAX_ROWS_PER_RUN} 条）")
+
+
+def shutdown(timeout=3.0):
+    """退出前停写线程并尽量排空队列（超时就算了，明细不是关键数据）。"""
+    _stop.set()
+    if _writer is not None:
+        _writer.join(timeout)
+
+
+def stats():
+    """本进程内的计数（排障用：看有没有在丢记录）。"""
+    return dict(_stats, queue_size=_q.qsize())
+
+
+# ================== 写入侧 ==================
+
+def record(run_id="", job_id="", job_name="", serial="", device_name="",
+           step_path="", step_label="", step_type="", selector="",
+           result="", detail="", duration_ms=0):
+    """记录一次步骤执行。**任务线程直接调用**——零阻塞、零 DB、不抛异常。
+
+    队列满时丢弃并计数（dropped），不会阻塞调用方。
+    """
+    try:
+        row = {
+            "run_id": (run_id or "")[:24],
+            "job_id": (job_id or "")[:32],
+            "job_name": (job_name or "")[:120],
+            "serial": (serial or "")[:120],
+            "device_name": (device_name or "")[:80],
+            "step_path": (step_path or "")[:32],
+            "step_label": (step_label or "")[:120],
+            "step_type": (step_type or "")[:40],
+            "selector": (selector or "")[:300],
+            "result": (result or "")[:16],
+            "detail": (detail or "")[:500],
+            "duration_ms": int(duration_ms or 0),
+            "created_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+        }
+        _q.put_nowait(row)
+        _stats["queued"] += 1
+    except queue.Full:
+        _stats["dropped"] += 1
+    except Exception:                      # 截断/类型异常都不该冒泡到任务线程
+        _stats["dropped"] += 1
+
+
+def _collect():
+    """取一批待写记录：最多等 _FLUSH_INTERVAL，凑够 _BATCH 就走。"""
+    rows = []
+    try:
+        rows.append(_q.get(timeout=_FLUSH_INTERVAL))
+    except queue.Empty:
+        return rows
+    while len(rows) < _BATCH:
+        try:
+            rows.append(_q.get_nowait())
+        except queue.Empty:
+            break
+    return rows
+
+
+def _insert(rows):
+    """批量落库。失败只记日志——明细丢了可以接受，任务不能被拖住。"""
+    if not rows or _app is None:
+        return
+    from core.models import TaskStepLog, db
+    try:
+        with _app.app_context():
+            db.session.execute(db.insert(TaskStepLog), rows)
+            db.session.commit()
+        _stats["written"] += len(rows)
+    except Exception as e:
+        _stats["failed"] += len(rows)
+        try:
+            db.session.rollback()
+        except Exception:
+            pass
+        _log.error(f"步骤明细落库失败（丢弃 {len(rows)} 条）: {e}")
+
+
+def _writer_loop():
+    while not _stop.is_set():
+        batch = _collect()
+        if batch:
+            _insert(batch)
+    # 退出前再排空一次，尽量不丢最后几条
+    while True:
+        batch = _collect()
+        if not batch:
+            break
+        _insert(batch)
+
+
+# ================== 查询（给 API 用，在请求线程里跑） ==================
+
+def query(serial="", job_id="", result="", run_id="", keyword="",
+          since="", until="", limit=200, offset=0):
+    """按条件查明细，返回 (rows, total)。**倒序**（最近的在前）。"""
+    from sqlalchemy import or_
+    from core.models import TaskStepLog
+    q = TaskStepLog.query
+    if serial:
+        q = q.filter(TaskStepLog.serial == serial)
+    if job_id:
+        q = q.filter(TaskStepLog.job_id == job_id)
+    if result:
+        q = q.filter(TaskStepLog.result == result)
+    if run_id:
+        q = q.filter(TaskStepLog.run_id == run_id)
+    if since:
+        q = q.filter(TaskStepLog.created_at >= since)
+    if until:
+        q = q.filter(TaskStepLog.created_at <= until)
+    if keyword:
+        kw = f"%{keyword}%"
+        q = q.filter(or_(TaskStepLog.detail.like(kw),
+                         TaskStepLog.step_label.like(kw),
+                         TaskStepLog.step_type.like(kw),
+                         TaskStepLog.selector.like(kw),
+                         TaskStepLog.job_name.like(kw)))
+    total = q.count()
+    rows = (q.order_by(TaskStepLog.id.desc())
+             .offset(max(0, int(offset or 0)))
+             .limit(max(1, min(int(limit or 200), 2000)))
+             .all())
+    return rows, total
+
+
+def runs(serial="", job_id="", since="", until="", limit=100):
+    """按 run_id 归组的一次运行概览（哪次运行失败、失败几步）。
+
+    用一次 GROUP BY 查出来，避免前端按明细自己聚合。
+    """
+    from sqlalchemy import case, func
+    from core.models import TaskStepLog, db
+    q = db.session.query(
+        TaskStepLog.run_id,
+        func.min(TaskStepLog.created_at).label("started_at"),
+        func.max(TaskStepLog.created_at).label("ended_at"),
+        func.max(TaskStepLog.job_name).label("job_name"),
+        func.max(TaskStepLog.job_id).label("job_id"),
+        func.max(TaskStepLog.serial).label("serial"),
+        func.max(TaskStepLog.device_name).label("device_name"),
+        func.count(TaskStepLog.id).label("steps"),
+        func.sum(case((TaskStepLog.result.in_(("error", "miss", "unknown")), 1),
+                      else_=0)).label("failures"),
+    )
+    if serial:
+        q = q.filter(TaskStepLog.serial == serial)
+    if job_id:
+        q = q.filter(TaskStepLog.job_id == job_id)
+    if since:
+        q = q.filter(TaskStepLog.created_at >= since)
+    if until:
+        q = q.filter(TaskStepLog.created_at <= until)
+    q = (q.filter(TaskStepLog.run_id != "")
+          .group_by(TaskStepLog.run_id)
+          .order_by(func.max(TaskStepLog.id).desc())
+          .limit(max(1, min(int(limit or 100), 500))))
+    return q.all()
+
+
+def purge_old(keep_days=None, batch=5000):
+    """删除超过保留期的明细。返回删除行数。
+
+    分批删（先取 id 再按 id 删，**不用 DELETE ... LIMIT**——SQLite 默认编译
+    选项不支持它），避免一条长事务把表锁住。
+    """
+    from core.models import TaskStepLog, db
+    days = KEEP_DAYS if keep_days is None else int(keep_days)
+    cutoff = time.strftime("%Y-%m-%d %H:%M:%S",
+                           time.localtime(time.time() - days * 86400))
+    deleted = 0
+    try:
+        while True:
+            ids = [r.id for r in db.session.query(TaskStepLog.id)
+                   .filter(TaskStepLog.created_at < cutoff).limit(batch).all()]
+            if not ids:
+                break
+            deleted += db.session.query(TaskStepLog) \
+                .filter(TaskStepLog.id.in_(ids)) \
+                .delete(synchronize_session=False)
+            db.session.commit()
+    except Exception as e:
+        db.session.rollback()
+        _log.error(f"步骤明细清理失败（已删 {deleted} 条）: {e}")
+        return deleted
+    if deleted:
+        _log.info(f"步骤明细清理: 删除 {deleted} 条（保留 {days} 天）")
+    return deleted

core/system_backup.py

@@ -1,18 +1,25 @@
 """系统数据备份导出/导入（数据库 + APK 文件）。
 
-导出：用 sqlite3 在线备份 API 对 data/users.db 做一致性快照 → zip
+**归档格式：zip（`users.db` + `manifest.json` + 可选 `apks/*.apk`）。**
-      （users.db + manifest.json + 可选 apks/*.apk）。
+SQLite 在这里的角色是**交换格式**，不是运行时数据库——这在迁到 MySQL 之后依然成立，
-导入：上传(zip/db) → 暂存校验预览 → 应用（先把当前库快照到
+带来三个好处：
-      BACKUP_DIR/pre_restore_*.db，再把暂存库移到 RESTORE_PENDING_DIR）→
+  1. 前端三个接口的请求/响应结构一行都不用改
-      下次启动 consume_pending_restore() 换位生效。
+  2. 校验逻辑（完整性 / 必需表 / schema 版本 / 未登记表反向自检）可以整体沿用
+  3. 2026-09-13 之前导出的老备份继续可导入；也不依赖任何外部二进制
+     （`sqlite3` 是 Python 标准库，python:slim 容器里现成）
 
-为什么必须重启生效：web_server 单进程内 SQLAlchemy engine + 多个常驻后台线程
+导出：把**当前库**（MySQL 或 SQLite）整库读出来，写进一个临时 SQLite 文件 → zip。
-（TaskManager 内存态 / 设备发现 / Agent 等）持有 users.db（WAL）；Windows 下
+      MySQL 下把这条连接提到 REPEATABLE READ，保证所有表读的是同一时刻。
-不能直接替换正被打开的文件，且 TaskManager 启动时才把 groups/jobs 读入内存。
+导入：上传(zip/db) → 暂存校验预览 → 应用（先自动导出一份当前库到
-故导入只落一个「待生效恢复任务」，由 web_server.py 在 init_db 之前消费。
+      BACKUP_DIR/pre_restore_*.zip 作安全网，再把暂存归档移到 RESTORE_PENDING_DIR）
+      → 下次启动 consume_pending_restore() 在**单个事务内**整库替换生效。
 
-安全红线：全程只读现有库 / 新增或移动自己目录下的文件；绝不 kill-server、
+为什么仍然要重启生效：TaskManager / device_pool 把任务与设备**缓存在内存**里，
-绝不 disconnect（与全项目一致）。
+整库替换后内存副本全部失效。（SQLite 时代还有"Windows 无法替换被持有的文件"这层，
+改用 MySQL 之后只剩内存态这一层。）
+
+安全红线：全程只读现有库 / 只写自己目录下的文件；替换数据用单事务，失败回滚，
+绝不留下半新半旧的库；绝不 kill-server、绝不 disconnect（与全项目一致）。
 """
 import json
 import os
@@ -23,36 +30,33 @@ import uuid
 import zipfile
 from urllib.parse import quote
 
+from sqlalchemy import create_engine, inspect, select, text
+
 from config import (DATA_DIR, APK_DIR, BACKUP_DIR,
                     RESTORE_STAGING_DIR, RESTORE_PENDING_DIR)
 from core.logger import get_logger
-from core.models import SCHEMA_MIGRATIONS
+from core.models import CURRENT_SCHEMA_VERSION, db
+from core import notifier
 
 _log = get_logger("core.backup")
 
-# 当前代码期望的 schema 版本（来自版本化迁移表）
-CURRENT_SCHEMA_VERSION = max(v[0] for v in SCHEMA_MIGRATIONS) if SCHEMA_MIGRATIONS else 0
-
 DB_FILE = os.path.join(DATA_DIR, "users.db")
 
 # 判定「本平台备份库」的必需表（缺任何一张即拒绝导入）
 REQUIRED_TABLES = ("app_meta", "user", "task_job", "device_group")
-# 预览/清单里展示行数的业务表（存在才统计）
+# 备份覆盖清单：**由模型元数据派生**，不再手工维护。
-# ⚠️ 红线：**新增任何持久化表，必须同步登记到这里**——备份覆盖清单以此为准，
+# 这样「新增持久化表必须登记进备份清单」这条红线从"靠人记"变成结构上不可能漏
-#    漏登记的表在导出清单/预览里不可见（2026-09-10 动作库 agent_action 即因此
+# （2026-09-10 动作库 agent_action 就漏过：数据其实在快照里，只是清单没列，
-#    被误判为"没有备份"：数据其实在 users.db 快照里，只是清单没列）。
+#   导出预览里看不到那一行 → 被误判成"没备份"）。
-SUMMARY_TABLES = (
+SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
-    "app_meta", "user", "device_group", "task_job", "custom_action",
-    "apk_file", "device", "pending_device",
-    "agent_conversation", "agent_experience", "experience_audit", "agent_action",
-)
 TABLE_LABELS = {
     "app_meta": "系统配置(app_meta)",
     "user": "用户", "device_group": "设备分组", "task_job": "任务计划",
     "custom_action": "自定义动作", "apk_file": "APK 记录", "device": "设备池",
     "pending_device": "待连接设备", "agent_conversation": "AI 会话",
     "agent_experience": "经验库", "experience_audit": "经验巡检",
-    "agent_action": "动作库",
+    "agent_action": "动作库", "device_install_log": "设备端安装记录",
+    "task_step_log": "任务步骤明细",
 }
 _STAGE_TTL = 1800  # 导入暂存有效期（秒）
 
@@ -66,9 +70,19 @@ def _ts():
     return time.strftime("%Y%m%d_%H%M%S")
 
 
+def _sqlite_uri(path):
+    """把路径转成 sqlite URI（兼容含空格/中文/反斜杠的 Windows 路径）。"""
+    return "file:{}".format(quote(os.path.abspath(path).replace("\\", "/"), safe="/:"))
+
+
 def _readonly_uri(path):
-    """把文件路径转成 sqlite 只读 URI（兼容含空格/中文/反斜杠的 Windows 路径）。"""
+    """sqlite 只读 URI。"""
-    return "file:{}?mode=ro".format(quote(os.path.abspath(path).replace("\\", "/"), safe="/:"))
+    return _sqlite_uri(path) + "?mode=ro"
+
+
+def _sqlite_engine_url(path):
+    """SQLAlchemy 用的 SQLite URL（注意与 file: URI 不同，engine 不吃那个格式）。"""
+    return "sqlite:///" + os.path.abspath(path).replace("\\", "/")
 
 
 def _connect_readonly(path):
@@ -114,34 +128,6 @@ def _table_rows(con, table):
         return None
 
 
-# ================== 在线快照 ==================
-def snapshot_db(dest_path, src_path=None):
-    """对 src（默认当前 users.db）做 sqlite 在线一致快照到 dest_path。
-
-    用标准库备份 API（不依赖 SQLAlchemy engine，WAL 模式下读一致快照安全）。
-    备份完成后把目标强制落回单文件（journal_mode=DELETE + checkpoint），
-    避免副本以 WAL 模式残留 -wal/-shm 或主文件缺刚提交帧。
-    """
-    src_path = src_path or DB_FILE
-    if not os.path.exists(src_path):
-        raise BackupError(f"数据库不存在: {src_path}")
-    con = _connect_readonly(src_path)
-    out = sqlite3.connect(dest_path)
-    try:
-        con.backup(out)
-        try:
-            out.execute("PRAGMA journal_mode=DELETE")  # checkpoint 并转回 DELETE
-        except sqlite3.Error:
-            pass
-    finally:
-        out.close()
-        con.close()
-    # 防御：确保没有任何残留附属文件
-    remove_quiet(dest_path + "-wal")
-    remove_quiet(dest_path + "-shm")
-
-
-# ================== 导出 ==================
 def _summary_info(con):
     """表行数摘要（只列出存在的表）。"""
     rows = []
@@ -168,13 +154,123 @@ def _prune_old_exports(max_age=3600):
                 pass
 
 
+def _prune_stale_staging():
+    """清理超时未应用的暂存目录（TTL 后自动删除）。"""
+    now = time.time()
+    if not os.path.isdir(RESTORE_STAGING_DIR):
+        return
+    for name in os.listdir(RESTORE_STAGING_DIR):
+        p = os.path.join(RESTORE_STAGING_DIR, name)
+        try:
+            if os.path.isdir(p) and now - os.path.getmtime(p) > _STAGE_TTL:
+                remove_quiet(p)
+        except OSError:
+            pass
+
+
+def _current_env_label():
+    """当前库登记的环境标签（dev/prod）与库唯一标识（未登记则空）。"""
+    from core import db_config
+    try:
+        return db_config.meta_get("deployment_env") or "", db_config.meta_get("deployment_id") or ""
+    except Exception:
+        return "", ""
+
+
+# ================== 导出：当前库 → SQLite 归档 ==================
+def dump_to_sqlite(dest_path):
+    """把当前数据库整库导出成一个 SQLite 文件（备份归档格式）。
+
+    一致性：MySQL 下把这条连接提到 REPEATABLE READ，让所有表读同一个时间点
+    （应用全局是 READ COMMITTED，事务提交后自增/被改的行会"漂移"）。
+    SQLite 下不需要——单文件库天然一致。
+    """
+    _ensure_dir(os.path.dirname(os.path.abspath(dest_path)))
+    remove_quiet(dest_path)
+    remove_quiet(dest_path + "-wal")
+    remove_quiet(dest_path + "-shm")
+
+    out_eng = create_engine(_sqlite_engine_url(dest_path))
+    is_mysql = db.engine.dialect.name == "mysql"
+    conn = db.engine.connect()
+    if is_mysql:
+        conn = conn.execution_options(isolation_level="REPEATABLE READ")
+
+    dumped = []
+    try:
+        # 归档库用同一套模型建表（mysql_* 表选项在 SQLite 下被忽略）
+        db.metadata.create_all(out_eng)
+        src_cols = {}
+        insp = inspect(conn)
+        for table in db.metadata.sorted_tables:
+            try:
+                src_cols[table.name] = {c["name"] for c in insp.get_columns(table.name)}
+            except Exception:
+                src_cols[table.name] = set()
+
+        with out_eng.begin() as out:
+            for table in db.metadata.sorted_tables:
+                have = src_cols.get(table.name) or set()
+                cols = [c for c in table.columns if c.name in have]
+                if not cols:
+                    _log.warning(f"导出跳过 {table.name}：源库没有这张表")
+                    continue
+                try:
+                    rows = [dict(r._mapping)
+                            for r in conn.execute(select(*cols))]
+                except Exception as e:
+                    _log.error(f"导出读取 {table.name} 失败: {e}")
+                    raise BackupError(f"导出失败：读取 {table.name} 出错（{e}）")
+                if rows:
+                    out.execute(table.insert(), rows)
+                dumped.append((table.name, len(rows)))
+    finally:
+        conn.close()
+        out_eng.dispose()
+
+    # 归档库收尾：落回单文件 + 补"空值不参与唯一"的唯一索引。
+    # SQLAlchemy 建的 sqlite 连接会被 PRAGMA 监听器设成 WAL，留下 -wal/-shm；
+    # zip 里只打包主文件，所以必须先 checkpoint 回 DELETE 模式再删附属文件。
+    try:
+        con = sqlite3.connect(dest_path)
+        try:
+            con.execute("PRAGMA journal_mode=DELETE")
+        except sqlite3.Error as e:
+            _log.warning(f"归档库切回单文件模式失败: {e}")
+        for name, sql in (("ux_device_name",
+                           "CREATE UNIQUE INDEX IF NOT EXISTS ux_device_name "
+                           "ON device(name) WHERE name IS NOT NULL AND name <> ''"),
+                          ("ux_device_fingerprint",
+                           "CREATE UNIQUE INDEX IF NOT EXISTS ux_device_fingerprint "
+                           "ON device(fingerprint) WHERE fingerprint IS NOT NULL "
+                           "AND fingerprint <> ''")):
+            try:
+                con.execute(sql)
+            except Exception as e:
+                _log.warning(f"归档库建索引 {name} 失败（数据可能有重复）: {e}")
+        con.commit()
+        con.close()
+    except Exception as e:
+        _log.warning(f"归档库收尾失败（不影响导出）: {e}")
+    remove_quiet(dest_path + "-wal")
+    remove_quiet(dest_path + "-shm")
+
+    _log.info("已导出到 SQLite 归档: %s（%d 张表）",
+              os.path.basename(dest_path), len(dumped))
+    return dumped
+
+
+# 兼容旧名（历史代码/脚本里叫 snapshot_db）
+snapshot_db = dump_to_sqlite
+
+
 def create_export(include_apk=True):
     """生成导出 zip，返回 (zip_path, filename, manifest)。"""
     _ensure_dir(BACKUP_DIR)
     _prune_old_exports()
     base = os.path.join(BACKUP_DIR, f"export_{_ts()}")
     snap = base + ".snapshot.db"
-    snapshot_db(snap)
+    dump_to_sqlite(snap)
 
     apk_meta = []
     if include_apk and os.path.isdir(APK_DIR):
@@ -186,14 +282,18 @@ def create_export(include_apk=True):
                 except OSError:
                     pass
 
+    env_label, db_id = _current_env_label()
     zip_path = base + ".zip"
     con = _connect_readonly(snap)
     try:
         manifest = {
             "format": "auto_control_backup",
-            "version": 1,
+            "version": 2,
             "created_at": time.strftime("%Y-%m-%d %H:%M:%S"),
             "schema_version": _read_schema_version(con),
+            "db_backend": db.engine.dialect.name,   # mysql / sqlite
+            "deployment_env": env_label,            # 来源环境（跨环境导入时告警）
+            "source_db_id": db_id,                  # 来源库唯一标识
             "include_apk": include_apk,
             "tables": _summary_info(con),
             "apks": apk_meta,
@@ -244,7 +344,7 @@ def validate_backup(db_file):
         if schema_version < CURRENT_SCHEMA_VERSION:
             warnings.append(
                 f"备份 schema 较旧（v{schema_version} < 当前 v{CURRENT_SCHEMA_VERSION}），"
-                f"应用后首次启动会自动迁移补齐结构与新表")
+                f"缺失的表/列按当前结构补空，不会报错但那些数据回不来")
         elif schema_version > CURRENT_SCHEMA_VERSION:
             warnings.append(
                 f"备份 schema 较新（v{schema_version} > 当前 v{CURRENT_SCHEMA_VERSION}），"
@@ -252,14 +352,15 @@ def validate_backup(db_file):
         if missing_optional:
             warnings.append("备份缺少部分可选表（" + "、".join(
                 TABLE_LABELS.get(t, t) for t in missing_optional)
-                + "），应用后启动会自动补建空表")
+                + "），导入后这些表为空")
         # 反向自检：备份里有"未登记"的表 → 提醒把它纳入覆盖清单（红线）
         extra_tables = sorted(t for t in tables
                               if t not in SUMMARY_TABLES and not t.startswith("sqlite_"))
         if extra_tables:
             warnings.append("备份含未登记的其它表（" + "、".join(extra_tables)
-                            + "）——如属业务数据，请登记进 core/system_backup.py 的覆盖清单")
+                            + "）——如属业务数据，请登记进 core/models.py 的模型与 "
-        warnings.append("备份为全量快照：含用户口令哈希、AI 配置里的 API Key 等敏感信息，请妥善保管")
+                              "core/system_backup.py 的 TABLE_LABELS")
+        warnings.append("备份为全量数据：含用户口令哈希、AI 配置里的 API Key 等敏感信息，请妥善保管")
         return True, {
             "integrity": integrity,
             "schema_version": schema_version,
@@ -277,7 +378,7 @@ def validate_backup(db_file):
 
 # ================== 导入：暂存 + 预览 ==================
 def _extract_zip(zip_path, staging_dir):
-    """解压备份 zip：取顶层 users.db 与可选 apks/*.apk（防路径穿越，只用 basename）。"""
+    """解压备份 zip：取顶层 users.db、可选 apks/*.apk 与 manifest.json（防路径穿越）。"""
     db_dest = os.path.join(staging_dir, "users.db")
     apk_dest = os.path.join(staging_dir, "apks")
     got_db = False
@@ -290,6 +391,10 @@ def _extract_zip(zip_path, staging_dir):
             if name == "users.db" and base == "users.db":
                 z.extract(info, staging_dir)  # 已确认顶层名字，无穿越
                 got_db = True
+            elif name == "manifest.json":
+                with z.open(info) as src, open(
+                        os.path.join(staging_dir, "manifest.json"), "wb") as dst:
+                    shutil.copyfileobj(src, dst)
             elif name.startswith("apks/") and base.lower().endswith(".apk"):
                 _ensure_dir(apk_dest)
                 with z.open(info) as src, open(
@@ -300,18 +405,15 @@ def _extract_zip(zip_path, staging_dir):
     return db_dest
 
 
-def _prune_stale_staging():
+def _read_staged_manifest(staging_dir):
-    """清理超时未应用的暂存目录（TTL 后自动删除）。"""
+    p = os.path.join(staging_dir, "manifest.json")
-    now = time.time()
+    if not os.path.exists(p):
-    if not os.path.isdir(RESTORE_STAGING_DIR):
+        return {}
-        return
+    try:
-    for name in os.listdir(RESTORE_STAGING_DIR):
+        with open(p, encoding="utf-8") as f:
-        p = os.path.join(RESTORE_STAGING_DIR, name)
+            return json.load(f) or {}
-        try:
+    except Exception:
-            if os.path.isdir(p) and now - os.path.getmtime(p) > _STAGE_TTL:
+        return {}
-                remove_quiet(p)
-        except OSError:
-            pass
 
 
 def stage_upload(file_storage):
@@ -333,12 +435,25 @@ def stage_upload(file_storage):
             db_file = os.path.join(staging_dir, "users.db")
             os.replace(raw_path, db_file)
         else:
-            raise BackupError("仅支持 .zip（平台导出）或 .db（sqlite 库）文件")
+            raise BackupError("仅支持 .zip（平台导出）或 .db（备份库文件）")
         ok, info = validate_backup(db_file)
         if not ok:
             raise BackupError(info)
         info["file_name"] = orig_name
         info["file_size"] = os.path.getsize(db_file)
+
+        # 跨环境提示（防混库第 5 层）：备份来自哪个环境、当前连的是哪个环境
+        man = _read_staged_manifest(staging_dir)
+        info["source_env"] = man.get("deployment_env") or ""
+        info["source_db_id"] = man.get("source_db_id") or ""
+        info["source_backend"] = man.get("db_backend") or "sqlite(旧版备份)"
+        cur_env, _ = _current_env_label()
+        info["current_env"] = cur_env
+        if info["source_env"] and cur_env and info["source_env"] != cur_env:
+            info["warnings"].append(
+                f"该备份来自 {info['source_env']} 环境，而当前连接的是 {cur_env} 库 —— "
+                f"导入会覆盖当前全部数据。确认这是你要的操作再继续（跨环境导入默认被拒绝）。")
+        # 暂存目录里留住 manifest，apply 时还要用它做环境校验
         return token, info
     except BackupError:
         remove_quiet(staging_dir)
@@ -349,8 +464,8 @@ def stage_upload(file_storage):
 
 
 # ================== 导入：应用（落待生效任务） ==================
-def apply_restore(token):
+def apply_restore(token, force_env_mismatch=False):
-    """校验 token → 快照当前库 → 把暂存库移到 restore_pending。
+    """校验 token → 自动备份当前库（zip 安全网）→ 把暂存归档移到 restore_pending。
 
     返回 dict {ok, backup_name, message}；失败抛 BackupError。token 形如 12 位 hex。
     """
@@ -364,25 +479,41 @@ def apply_restore(token):
     if not ok:
         raise BackupError(info)
 
-    # 1) 自动备份当前库（安全网，可回滚）
+    # 跨环境硬停：默认不许把 prod 的备份灌进 dev 库（反之亦然）
+    man = _read_staged_manifest(staging_dir)
+    src_env = man.get("deployment_env") or ""
+    cur_env, _ = _current_env_label()
+    if src_env and cur_env and src_env != cur_env and not force_env_mismatch:
+        raise BackupError(
+            f"备份来自 {src_env} 环境，当前库是 {cur_env} 环境 —— 已拒绝导入。\n"
+            f"如确需跨环境恢复，请在确认页勾选「允许跨环境导入」后重试。")
+
+    # 1) 自动备份当前库（安全网，可回滚；导出成 zip，能直接再导入回来）
     _ensure_dir(BACKUP_DIR)
-    backup_name = f"pre_restore_{_ts()}.db"
+    try:
-    snapshot_db(os.path.join(BACKUP_DIR, backup_name))
+        zip_path, _, _ = create_export(include_apk=True)
+        backup_name = f"pre_restore_{_ts()}.zip"
+        shutil.move(zip_path, os.path.join(BACKUP_DIR, backup_name))
+    except Exception as e:
+        raise BackupError(f"导入前自动备份当前库失败，已中止导入: {e}")
 
     # 2) 落待生效恢复任务（旧未消费任务被覆盖——上一份已无意义）
-    pending_dir = RESTORE_PENDING_DIR
+    if os.path.isdir(RESTORE_PENDING_DIR):
-    if os.path.isdir(pending_dir):
+        remove_quiet(RESTORE_PENDING_DIR)
-        remove_quiet(pending_dir)
+    _ensure_dir(RESTORE_PENDING_DIR)
-    _ensure_dir(pending_dir)
+    os.replace(db_file, os.path.join(RESTORE_PENDING_DIR, "users.db"))
-    os.replace(db_file, os.path.join(pending_dir, "users.db"))
+    for extra in ("manifest.json",):
+        src = os.path.join(staging_dir, extra)
+        if os.path.exists(src):
+            shutil.move(src, os.path.join(RESTORE_PENDING_DIR, extra))
     apk_src = os.path.join(staging_dir, "apks")
     if os.path.isdir(apk_src) and os.listdir(apk_src):
-        shutil.move(apk_src, os.path.join(pending_dir, "apks"))
+        shutil.move(apk_src, os.path.join(RESTORE_PENDING_DIR, "apks"))
     remove_quiet(staging_dir)
 
     schema_version = info.get("schema_version", 0)
     _log.info(f"导入已落恢复任务: schema v{schema_version}，"
-              f"重启 web_server 后生效；当前库已快照 {backup_name}")
+              f"重启 web_server 后生效；当前库已自动备份 {backup_name}")
     return {
         "ok": True,
         "backup_name": backup_name,
@@ -390,32 +521,45 @@ def apply_restore(token):
     }
 
 
-# ================== 启动消费（web_server.py init_db 前调用） ==================
+# ================== 启动消费（init_db 之后、TaskManager 之前调用）==================
-def consume_pending_restore():
+def _pending_db_path():
-    """把 restore_pending/users.db 换位为当前 users.db（删除旧 wal/shm，合并 apks）。
+    """待生效恢复的归档路径（兼容旧版扁平布局）。"""
+    p = os.path.join(RESTORE_PENDING_DIR, "users.db")
+    return p if os.path.exists(p) else None
 
-    必须在 SQLAlchemy engine 首次打开 users.db 之前执行（web_server 装配时调用）。
+
-    失败不阻塞启动：坏恢复文件会挪到 BACKUP_DIR/restore_failed_*/ 并继续用旧库。
+def consume_pending_restore():
+    """把 restore_pending/users.db 的内容在**单个事务内**整库替换进来。
+
+    与 SQLite 时代的"换文件"不同：现在是 DELETE 全表 + 分块 INSERT，全程一个事务——
+    任何一步失败就 rollback，当前数据保持原样（比换文件更安全）。
+
+    必须在 init_db() 之后调用（表已建好、app context 可用）；失败不阻塞启动：
+    坏归档挪到 BACKUP_DIR/restore_failed_*/ 并继续用当前数据。
     返回是否真的应用了恢复。
     """
-    pending_db = os.path.join(RESTORE_PENDING_DIR, "users.db")
+    pending_db = _pending_db_path()
-    if not os.path.exists(pending_db):
+    if not pending_db:
         return False
-    # 消费前轻量复验（防止意外损坏文件把主库换掉）
+    # 消费前轻量复验（防止意外损坏的文件把主库换掉）
     ok, msg = validate_backup(pending_db)
     if not ok:
         fail_dir = os.path.join(BACKUP_DIR, f"restore_failed_{_ts()}")
         _ensure_dir(fail_dir)
-        os.replace(pending_db, os.path.join(fail_dir, "users.db"))
+        shutil.move(pending_db, os.path.join(fail_dir, "users.db"))
         remove_quiet(RESTORE_PENDING_DIR)
         _log.error(f"恢复任务校验失败，已搁置到 {fail_dir}，继续使用当前库: {msg}")
+        notifier.notify("system.backup.restore_failed", error=str(msg)[:200],
+                        fail_dir=fail_dir)
         return False
-    _ensure_dir(DATA_DIR)
+
-    os.replace(pending_db, DB_FILE)
+    try:
-    for ext in ("-wal", "-shm"):
+        applied = _apply_archive_to_db(pending_db)
-        p = DB_FILE + ext
+    except Exception as e:
-        if os.path.exists(p):
+        _log.error(f"应用备份恢复失败，已回滚（当前数据未改动）: {e}，"
-            remove_quiet(p)
+                   f"归档保留在 {RESTORE_PENDING_DIR} 供排查")
+        return False
+
     # 合并 apks（覆盖同名）
     apk_src = os.path.join(RESTORE_PENDING_DIR, "apks")
     if os.path.isdir(apk_src):
@@ -427,6 +571,45 @@ def consume_pending_restore():
                 os.remove(dst)
             shutil.move(src, dst)
     remove_quiet(RESTORE_PENDING_DIR)
-    schema_version = msg.get("schema_version", 0) if isinstance(msg, dict) else "?"
+    schema_version = msg.get("schema_version", "?") if isinstance(msg, dict) else "?"
-    _log.info(f"已应用备份恢复: users.db 替换完成（schema v{schema_version}），apks 已合并")
+    _log.info(f"已应用备份恢复（单事务替换）: {applied}，schema v{schema_version}，apks 已合并")
+    # 通知在"下一次启动"才发得出去（恢复本身是重启生效的），文案里说明白
+    notifier.notify("system.backup.restored", applied_rows=applied,
+                    schema_version=schema_version)
     return True
+
+
+def _apply_archive_to_db(db_file, chunk=500):
+    """把 SQLite 归档里的数据整库写进当前数据库，单事务、失败回滚。
+
+    用 DELETE 而不是 TRUNCATE：TRUNCATE 是 DDL，会隐式提交，破坏原子性。
+    """
+    con = _connect_readonly(db_file)
+    arch_tables = _list_tables(con)
+    stats = []
+    try:
+        # 单事务：MySQL/SQLite 都支持事务内 DELETE + INSERT
+        with db.engine.begin() as dst:
+            for table in reversed(db.metadata.sorted_tables):
+                dst.execute(table.delete())
+            for table in db.metadata.sorted_tables:
+                if table.name not in arch_tables:
+                    _log.warning(f"归档里没有 {table.name}，该表导入后为空")
+                    continue
+                have = {r[1] for r in con.execute(
+                    'PRAGMA table_info("%s")' % table.name)}
+                cols = [c for c in table.columns if c.name in have]
+                if not cols:
+                    _log.warning(f"归档表 {table.name} 没有可用列，跳过")
+                    continue
+                sel = "SELECT {} FROM \"{}\"".format(
+                    ", ".join('"%s"' % c.name for c in cols), table.name)
+                rows = con.execute(sel).fetchall()
+                names = [c.name for c in cols]
+                for i in range(0, len(rows), chunk):
+                    batch = [dict(zip(names, r)) for r in rows[i:i + chunk]]
+                    dst.execute(table.insert(), batch)
+                stats.append(f"{table.name}={len(rows)}")
+    finally:
+        con.close()
+    return " ".join(stats)

core/task_draft.py

@@ -0,0 +1,541 @@
+"""AI 建任务的 draft 契约：**校验 + 归一化**（唯一真相）。
+
+## 为什么必须有这个模块
+
+任务执行器对"写错的地方"是**静默跳过**的：未知步骤类型只打一条 warning 继续
+（`tasks/generic/task.py` 的 `_exec_one`），空 `selector_value` 直接 return。
+而 `POST /api/jobs` 只校验 `name` + `task_type`，`params` 完全盲存
+（`web/tasks_api.py`）。两者叠加的后果是：AI（或任何人）交上一条写错的任务，
+**创建成功、运行不报错、但什么都没做**。
+
+所以这里把执行器的每个"静默跳过点"前移成显式 error，在**落库之前**拦住。
+错误文案是给**模型**看的（走 `submit_task` 的返回值回灌，让它逐条改完重提），
+所以每条都要说清"哪个节点的哪个字段、错在哪、应该是什么"。
+
+## 用法
+
+    res = validate_draft(draft, groups=..., pool=..., default_serial="...")
+    # → {"ok": bool, "errors": [...], "warnings": [...], "draft": 归一化后的草稿}
+
+`errors` 非空就是不能落库；`warnings` 只是提醒（前端醒目展示，不拦）。
+
+契约与规则的权威描述见 `doc/AI_TASK_GEN.md`。
+"""
+import re
+
+from core.logger import get_logger
+
+_log = get_logger("core.task_draft")
+
+# ================== 常量（规则的唯一来源） ==================
+
+# 单条任务最多多少个步骤节点（含嵌套），防止模型输出失控/被输出长度截断
+MAX_NODES = 60
+# 嵌套深度上限（执行器 >5 层直接跳过该分支，见 tasks/generic/task.py）
+MAX_DEPTH = 5
+# 选择器值长度上限
+MAX_SELECTOR_LEN = 200
+# 单条 input_text 的候选文案条数
+MAX_TEXTS = 20
+
+# 与编辑器下拉（static/admin/editor.js 的 selector_type 选项）严格同集。
+# 故意不含 textContains —— 下拉里没有它，用户一改就丢。
+SELECTOR_TYPES = ("xpath", "description", "text", "resourceId",
+                  "descriptionContains", "className")
+IF_SELECTOR_TYPES = SELECTOR_TYPES + ("ocr",)
+
+# 按键白名单（u2 的 d.press 支持更多，这里只放"不会把设备弄坏"的那些：
+# 不含 power/camera —— 探索期误按 power 会让设备息屏、任务中途失联）
+KEY_WHITELIST = ("back", "home", "enter", "menu", "recent", "delete",
+                 "volume_up", "volume_down", "search")
+
+DIRECTIONS = ("up", "down", "left", "right")
+LOOP_MODES = ("rounds", "time", "forever")
+SCHEDULE_MODES = ("once", "cron", "cron_stop")
+TARGET_MODES = ("all", "group", "serial")
+
+# 需要选择器的步骤类型（缺 selector_value 时执行器静默跳过）
+NEED_SELECTOR = ("click", "long_click", "wait_el", "swipe_until", "if_el")
+# 需要包名的步骤类型
+NEED_PACKAGE = ("open_app", "stop_app")
+# 需要非空 children 的容器
+NEED_CHILDREN = ("loop", "group")
+
+# 有副作用的动作关键词：命中的步骤在 AI 通道只给 warning（人工复核），不拦
+DESTRUCTIVE_HINTS = ("评论", "发送", "发布", "投稿", "转发", "分享到",
+                     "购买", "下单", "支付", "付款", "删除", "卸载",
+                     "退出登录", "注销", "举报", "拉黑", "清空")
+# 命中上面关键词的步骤，触发概率被压到这个值（可人工改回）
+SAFE_PROBABILITY = 30
+
+_PKG_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$")
+_HHMM_RE = re.compile(r"^([01]\d|2[0-3]):[0-5]\d$")
+# 「序号型」选择器的两种形态：
+#   (//*[@resource-id="x"])[4]  ← 抓取器在语义消歧失败时给的（当前形态）
+#   //*[@resource-id="x"][4]    ← 历史形态（执行器会自动纠正成上面那种）
+# 两者都依赖"同类元素有几个"，界面一变就指到别的元素上，都值得提醒换语义选择器。
+_SEQ_SELECTOR_RE = re.compile(r"^(?:\(\s*//\*\[@[^\]]+\]\s*\)|//\*\[@[^\]]+\])\[\d+\]")
+
+
+def _step_types():
+    """步骤类型 → (label, 默认 params)，直接取自执行器的权威定义。"""
+    from tasks.generic.task import STEP_TYPES
+    return {s["type"]: (s.get("label", s["type"]), dict(s.get("params") or {}))
+            for s in STEP_TYPES}
+
+
+def _is_num(v):
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def _num(params, key, default=None):
+    v = params.get(key, default)
+    return v if _is_num(v) else default
+
+
+# ================== 步骤树校验 ==================
+
+def validate_steps(steps, depth=1, path="steps", errors=None, warnings=None,
+                   types=None, counter=None):
+    """递归校验步骤树，返回 (errors, warnings, 节点总数)。
+
+    每条 error 都带上路径（如 `steps[0].params.children[2]`），模型据此能直接定位。
+    """
+    errors = [] if errors is None else errors
+    warnings = [] if warnings is None else warnings
+    types = _step_types() if types is None else types
+    counter = [0] if counter is None else counter
+
+    if not isinstance(steps, list):
+        errors.append(f"{path}: 必须是数组")
+        return errors, warnings, counter[0]
+
+    for i, step in enumerate(steps):
+        here = f"{path}[{i}]"
+        if not isinstance(step, dict):
+            errors.append(f"{here}: 必须是对象")
+            continue
+        stype = step.get("type")
+        if not stype:
+            errors.append(f"{here}: 缺少 type 字段")
+            continue
+        if stype not in types:
+            errors.append(f"{here}: 未知步骤类型 {stype!r}（可用类型："
+                          f"{'、'.join(types)}）")
+            continue
+        if stype == "click_xy":
+            errors.append(f"{here}: 不允许坐标点击（click_xy）—— 坐标在不同分辨率/"
+                          "设备上必失配，请改用 click + 选择器定位元素")
+            continue
+
+        counter[0] += 1
+        if counter[0] > MAX_NODES:
+            errors.append(f"{here}: 步骤节点总数超过 {MAX_NODES} 个，请精简"
+                          "（去掉冗余的等待/滑动，合并重复结构）")
+            return errors, warnings, counter[0]
+
+        params = step.get("params")
+        if params is None:
+            params = {}
+        if not isinstance(params, dict):
+            errors.append(f"{here}.params: 必须是对象")
+            continue
+
+        # 触发概率（执行器对所有类型通用）
+        prob = params.get("probability")
+        if prob is not None:
+            if not _is_num(prob) or not (0 <= prob <= 100):
+                errors.append(f"{here}.params.probability: 必须是 0~100 的数字"
+                              f"（当前 {prob!r}）")
+
+        # 选择器类步骤
+        if stype in NEED_SELECTOR:
+            sel = params.get("selector_value")
+            if not isinstance(sel, str) or not sel.strip():
+                errors.append(f"{here}.params.selector_value: 不能为空 —— "
+                              "该步骤没有定位目标，执行时会被静默跳过。"
+                              "如果这一步还没探索出可靠的定位，请把它从 steps 里去掉，"
+                              "需要人工确认的写进 notes")
+            else:
+                _check_selector(params, here, stype, errors, warnings)
+
+        # 包名类步骤
+        if stype in NEED_PACKAGE:
+            pkg = params.get("package")
+            if not isinstance(pkg, str) or not _PKG_RE.match(pkg.strip()):
+                errors.append(f"{here}.params.package: 必须是包名（如 "
+                              "com.ss.android.ugc.aweme），当前 "
+                              f"{pkg!r}")
+
+        # 容器
+        if stype in NEED_CHILDREN:
+            children = params.get("children")
+            if not isinstance(children, list) or not children:
+                errors.append(f"{here}.params.children: 不能为空 —— "
+                              "空容器等于什么都没做")
+                continue
+            if depth >= MAX_DEPTH:
+                errors.append(f"{here}: 嵌套层级超过 {MAX_DEPTH} 层"
+                              "（执行器会直接跳过这个分支）")
+                continue
+            validate_steps(children, depth + 1, f"{here}.params.children",
+                           errors, warnings, types, counter)
+
+        if stype == "loop":
+            mode, fixed = _norm_loop_mode(params.get("loop_mode"))
+            params["loop_mode"] = mode
+            if fixed:
+                warnings.append(f"{here}.params.loop_mode: 已按 {fixed!r} 归一为 "
+                                f"{mode!r}（执行器对未知取值按轮次处理）")
+            if mode == "rounds":
+                it = params.get("max_iterations")
+                if it is None:
+                    # 执行器默认 10（tasks/generic/task.py 的 _exec_loop）——
+                    # 能跑通的就不该拦，补默认值并提示即可
+                    params["max_iterations"] = 10
+                    warnings.append(f"{here}.params.max_iterations: 未填，按默认 10 轮")
+                elif not _is_num(it) or it < 1:
+                    errors.append(f"{here}.params.max_iterations: 按轮次循环时"
+                                  f"必须 ≥1（当前 {it!r}）")
+            elif mode == "time":
+                dur = params.get("loop_duration")
+                # 按时间循环缺时长时执行器**直接跳过**整块（静默无操作）→ 必须拦
+                if not _is_num(dur) or dur < 10:
+                    errors.append(f"{here}.params.loop_duration: 按时间循环时"
+                                  f"必须 ≥10 秒（当前 {dur!r}）")
+
+        if stype == "if_el":
+            then = params.get("then")
+            if not isinstance(then, list) or not then:
+                errors.append(f"{here}.params.then: 不能为空 —— "
+                              "条件命中后必须做点什么")
+            if depth >= MAX_DEPTH:
+                errors.append(f"{here}: 嵌套层级超过 {MAX_DEPTH} 层")
+                continue
+            if isinstance(then, list):
+                validate_steps(then, depth + 1, f"{here}.params.then",
+                               errors, warnings, types, counter)
+            else_ = params.get("else")
+            if isinstance(else_, list) and else_:
+                validate_steps(else_, depth + 1, f"{here}.params.else",
+                               errors, warnings, types, counter)
+
+        if stype == "swipe":
+            _check_direction(params, here, errors)
+            dmin, dmax = _num(params, "duration_min"), _num(params, "duration_max")
+            if dmin is not None and dmax is not None and dmin > dmax:
+                errors.append(f"{here}.params: duration_min({dmin}) 不能大于 "
+                              f"duration_max({dmax})")
+
+        if stype == "swipe_until":
+            _check_direction(params, here, errors)
+            n = params.get("max_swipes")
+            if not _is_num(n) or not (1 <= n <= 50):
+                errors.append(f"{here}.params.max_swipes: 必须是 1~50（当前 {n!r}）")
+
+        if stype == "wait":
+            lo, hi = _num(params, "min"), _num(params, "max")
+            if lo is None or hi is None or lo < 0 or hi > 600 or lo > hi:
+                errors.append(f"{here}.params: 需要 0 ≤ min ≤ max ≤ 600"
+                              f"（当前 min={lo!r} max={hi!r}）")
+
+        if stype == "input_text":
+            mode = params.get("mode", "random")
+            if mode not in ("random", "fixed"):
+                errors.append(f"{here}.params.mode: 必须是 random 或 fixed"
+                              f"（当前 {mode!r}）")
+            elif mode == "fixed":
+                if not str(params.get("fixed_text") or "").strip():
+                    errors.append(f"{here}.params.fixed_text: mode=fixed 时不能为空")
+            else:
+                texts = params.get("texts")
+                if not isinstance(texts, str) or not texts.strip():
+                    errors.append(f"{here}.params.texts: mode=random 时必须给候选"
+                                  "文案（换行分隔，如 \"你好\\n不错\"）")
+                elif len([t for t in texts.split("\n") if t.strip()]) > MAX_TEXTS:
+                    errors.append(f"{here}.params.texts: 候选文案最多 {MAX_TEXTS} 条")
+
+        if stype == "clipboard":
+            if not str(params.get("text") or "").strip():
+                errors.append(f"{here}.params.text: 剪贴板内容不能为空")
+
+        if stype == "keep_screen":
+            if params.get("mode", "on") not in ("on", "off"):
+                errors.append(f"{here}.params.mode: 必须是 on 或 off")
+
+        if stype == "key_event":
+            key = params.get("key", "back")
+            if key not in KEY_WHITELIST:
+                errors.append(f"{here}.params.key: 不支持的按键 {key!r}"
+                              f"（可用：{'、'.join(KEY_WHITELIST)}）")
+
+        _check_destructive(step, here, warnings)
+
+    return errors, warnings, counter[0]
+
+
+def _check_selector(params, here, stype, errors, warnings):
+    """选择器类型/取值合法性（跨 xpath 与 u2 kwarg 两套语义）。"""
+    stype_ok = IF_SELECTOR_TYPES if stype == "if_el" else SELECTOR_TYPES
+    sel_type = params.get("selector_type") or "xpath"
+    value = (params.get("selector_value") or "").strip()
+    if sel_type not in stype_ok:
+        errors.append(f"{here}.params.selector_type: 不支持 {sel_type!r}"
+                      f"（可用：{'、'.join(stype_ok)}）")
+        return
+    if len(value) > MAX_SELECTOR_LEN:
+        errors.append(f"{here}.params.selector_value: 太长（>{MAX_SELECTOR_LEN} 字符）")
+        return
+    if sel_type == "xpath":
+        if not (value.startswith("//") or value.startswith("(//")):
+            errors.append(f"{here}.params.selector_value: 类型是 xpath，但取值不是 "
+                          f"// 或 (// 开头（当前 {value[:40]!r}）")
+        elif _SEQ_SELECTOR_RE.match(value):
+            # 执行器有 _norm_legacy_xpath 兜底纠正，所以只提醒不拦：
+            # 序号型选择器「同类元素个数一变就失配」，能换成文字限定就用文字
+            warnings.append(f"{here}.params.selector_value: 序号型选择器"
+                            f"（{value[:40]}）依赖同类元素个数，界面一变就会点空，"
+                            "建议改用 @text/@content-desc 限定")
+
+
+# 模型常见的近义写法 → 执行器认的枚举值。
+# 归一化而不是报错：执行器对未知 loop_mode 是按"轮次"处理的（else 分支），
+# 拦下来只会让模型反复重试（实测把一个 40 步的探索硬生生耗在改这一个字段上）。
+_LOOP_MODE_ALIAS = {
+    "count": "rounds", "times": "rounds", "round": "rounds",
+    "iterations": "rounds", "iteration": "rounds", "n": "rounds",
+    "duration": "time", "seconds": "time", "secs": "time", "timeout": "time",
+    "infinite": "forever", "infinity": "forever", "until_stop": "forever",
+    "while": "forever", "loop": "forever",
+}
+
+
+def _norm_loop_mode(mode):
+    """返回 (规范化后的 loop_mode, 原始值或 None)。"""
+    if mode in LOOP_MODES:
+        return mode, None
+    m = str(mode or "").strip().lower()
+    if m in _LOOP_MODE_ALIAS:
+        return _LOOP_MODE_ALIAS[m], mode
+    return "rounds", mode if mode is not None else None
+
+
+def _check_direction(params, here, errors):
+    d = params.get("direction", "up")
+    if d not in DIRECTIONS:
+        errors.append(f"{here}.params.direction: 必须是 "
+                      f"{'/'.join(DIRECTIONS)} 之一（当前 {d!r}）")
+
+
+def _check_destructive(step, here, warnings):
+    """有副作用的步骤给 warning（不拦）：让人知道哪里需要复核。"""
+    text = " ".join(str(step.get(f) or "") for f in ("label",))
+    text += " " + str((step.get("params") or {}).get("selector_value") or "")
+    text += " " + str((step.get("params") or {}).get("texts") or "")
+    hits = [w for w in DESTRUCTIVE_HINTS if w in text]
+    if not hits:
+        return
+    tags = "、".join(hits)
+    # 有副作用的动作默认调低触发概率（安全默认值，编辑器里可改回）：
+    # 探索期本来就不许真做这类动作（只核对元素存在），产物更不该一上来就每次都触发
+    params = step.setdefault("params", {})
+    prob = params.get("probability", 100)
+    if _is_num(prob) and prob > SAFE_PROBABILITY:
+        params["probability"] = SAFE_PROBABILITY
+        warnings.append(f"{here}: 含「{tags}」类有副作用的操作，触发概率已从 {prob}% "
+                        f"降到 {SAFE_PROBABILITY}% —— 核对无误后可在步骤编辑器里改回")
+    else:
+        warnings.append(f"{here}: 含「{tags}」类有副作用的操作，"
+                        "请人工复核后再启用")
+
+
+# ================== draft 整体 ==================
+
+def validate_draft(draft, groups=None, pool=None, default_serial="", overrides=None):
+    """校验并归一化 AI 提交的任务草稿。
+
+    draft      —— 模型提交的原始对象
+    groups     —— 现有分组名集合（校验 target.mode=group 时用；None=不校验）
+    pool       —— 设备池 serial 集合（用于给"设备不在池"的 warning；None=不校验）
+    default_serial —— 本次探索用的设备（target 缺省时兜底）
+    overrides  —— 页面上的"任务设置"覆盖项（用户在页面上填的优先）
+
+    → {"ok", "errors", "warnings", "draft"}
+    """
+    errors, warnings = [], []
+    if not isinstance(draft, dict):
+        return {"ok": False, "errors": ["draft 必须是对象"], "warnings": [],
+                "draft": None}
+
+    # ---- summary ----
+    summary = str(draft.get("summary") or "").strip()
+    if not summary:
+        errors.append("summary: 不能为空 —— 用一句话说明这条任务做什么")
+    elif len(summary) > 200:
+        summary = summary[:200]
+
+    # ---- task ----
+    task = draft.get("task")
+    if not isinstance(task, dict):
+        errors.append("task: 缺少任务对象")
+        task = {}
+    task = _normalize_task(task, summary, default_serial, overrides or {},
+                           errors, warnings)
+
+    types = _step_types()
+    steps = ((task.get("params") or {}).get("steps")) or []
+    if not steps:
+        errors.append("task.params.steps: 不能为空 —— 没有步骤的任务创建后"
+                      "每次运行都会报错")
+    else:
+        validate_steps(steps, 1, "task.params.steps", errors, warnings, types)
+
+    _check_target(task, groups, pool, errors, warnings)
+    _check_schedule(task, errors, warnings)
+
+    return {"ok": not errors, "errors": errors, "warnings": warnings,
+            "draft": {"summary": summary, "task": task,
+                      "notes": [str(n) for n in (draft.get("notes") or [])][:5],
+                      "evidence": list(draft.get("evidence") or [])[:10]}}
+
+
+def _normalize_task(task, summary, default_serial, overrides, errors, warnings):
+    """补齐缺失字段（缺什么补什么，但**不掩盖**该报错的必填项）。"""
+    name = str(overrides.get("name") or task.get("name") or "").strip()
+    if not name:
+        name = (summary[:20] or "AI 任务").strip()
+    task["name"] = name[:40]
+
+    task_type = task.get("task_type") or "generic_steps"
+    if task_type != "generic_steps":
+        errors.append(f"task.task_type: 目前只支持 generic_steps（收到 {task_type!r}）")
+    task["task_type"] = "generic_steps"
+
+    target = task.get("target")
+    if not isinstance(target, dict) or not target.get("mode"):
+        target = {"mode": "serial", "serial": default_serial} if default_serial \
+            else {"mode": "all"}
+        warnings.append(f"task.target: 未指定，已按探索设备兜底为 {target}")
+    # 页面上显式选了目标就以页面为准
+    ov_mode = overrides.get("target_mode")
+    if ov_mode in TARGET_MODES:
+        target = {"mode": ov_mode}
+        if ov_mode == "group":
+            target["group_name"] = overrides.get("group_name") or ""
+        elif ov_mode == "serial":
+            target["serial"] = overrides.get("serial") or default_serial
+    task["target"] = target
+
+    schedule = task.get("schedule")
+    if not isinstance(schedule, dict) or not schedule.get("mode"):
+        schedule = {"mode": "once"}
+    if overrides.get("schedule"):
+        schedule = overrides["schedule"]
+    task["schedule"] = schedule
+
+    retry = task.get("retry")
+    if not isinstance(retry, dict):
+        retry = {}
+    attempts = retry.get("max_attempts", 1)
+    delay = retry.get("delay", 60)
+    if not _is_num(attempts) or not (1 <= attempts <= 10):
+        warnings.append(f"task.retry.max_attempts: 应为 1~10，已改为 1（原 {attempts!r}）")
+        attempts = 1
+    if not _is_num(delay) or not (10 <= delay <= 3600):
+        warnings.append(f"task.retry.delay: 应为 10~3600 秒，已改为 60（原 {delay!r}）")
+        delay = 60
+    task["retry"] = {"max_attempts": int(attempts), "delay": int(delay)}
+    task["enabled"] = bool(task.get("enabled", True))
+
+    params = task.get("params")
+    if not isinstance(params, dict):
+        params = {}
+    dur = overrides.get("max_duration", params.get("max_duration", 0))
+    if not _is_num(dur) or dur < 0 or dur > 604800:
+        errors.append(f"task.params.max_duration: 必须是 0~604800 的秒数"
+                      f"（当前 {dur!r}）")
+        dur = 0
+    params["max_duration"] = int(dur)
+    # 步骤里的 id 由编辑器生成，落库前不需要（保留会让前端 id 重复）
+    if isinstance(params.get("steps"), list):
+        _strip_ids(params["steps"])
+    task["params"] = params
+    return task
+
+
+def _strip_ids(steps):
+    for s in steps:
+        if isinstance(s, dict):
+            s.pop("id", None)
+            p = s.get("params")
+            if isinstance(p, dict):
+                for key in ("children", "then", "else"):
+                    if isinstance(p.get(key), list):
+                        _strip_ids(p[key])
+
+
+def _check_target(task, groups, pool, errors, warnings):
+    target = task.get("target") or {}
+    mode = target.get("mode")
+    if mode not in TARGET_MODES:
+        errors.append(f"task.target.mode: 必须是 {'/'.join(TARGET_MODES)} 之一"
+                      f"（当前 {mode!r}）")
+        return
+    if mode == "group":
+        gname = (target.get("group_name") or "").strip()
+        if not gname:
+            errors.append("task.target.group_name: mode=group 时必须给分组名")
+        elif groups is not None and gname not in groups:
+            errors.append(f"task.target.group_name: 分组 {gname!r} 不存在"
+                          f"（现有：{'、'.join(groups) or '无'}）")
+    elif mode == "serial":
+        serial = (target.get("serial") or "").strip()
+        if not serial:
+            errors.append("task.target.serial: mode=serial 时必须给设备 serial")
+        elif pool is not None and serial not in pool:
+            warnings.append(f"task.target.serial: 设备 {serial} 不在设备池里，"
+                            "任务运行时会被跳过")
+
+
+def _check_schedule(task, errors, warnings):
+    sch = task.get("schedule") or {}
+    mode = sch.get("mode")
+    if mode not in SCHEDULE_MODES:
+        errors.append(f"task.schedule.mode: 必须是 {'/'.join(SCHEDULE_MODES)} 之一"
+                      f"（当前 {mode!r}）")
+        return
+    if mode == "once":
+        return
+    cron = sch.get("cron")
+    if not isinstance(cron, str) or not _cron_ok(cron):
+        errors.append(f"task.schedule.cron: 不是合法的 5 段 crontab（分 时 日 月 周）"
+                      f"，当前 {cron!r}")
+    if mode == "cron_stop":
+        stop = sch.get("stop_cron")
+        if not isinstance(stop, str) or not _cron_ok(stop):
+            errors.append("task.schedule.stop_cron: 定时停止必须给合法的 5 段 "
+                          f"crontab，当前 {stop!r}")
+    win = sch.get("window")
+    if isinstance(win, dict):
+        start, end = win.get("start"), win.get("end")
+        if not (_HHMM_RE.match(str(start or "")) and _HHMM_RE.match(str(end or ""))):
+            warnings.append("task.schedule.window: 时间窗应形如 {\"start\":\"09:00\","
+                            "\"end\":\"18:00\"}，格式不对会被忽略")
+        elif start == end:
+            warnings.append("task.schedule.window: 起止相同等于不限制")
+    dur = (task.get("params") or {}).get("max_duration", 0)
+    if mode == "cron_stop" and not dur:
+        warnings.append("task.params.max_duration 为 0：本任务靠定时停止结束，"
+                        "建议同时给一个运行时长上限（秒）兜底")
+
+
+def _cron_ok(expr):
+    """5 段 crontab 且能被 APScheduler 解析（任务是**静默**不注册的，必须提前拦）。"""
+    if len(str(expr).split()) != 5:
+        return False
+    try:
+        from apscheduler.triggers.cron import CronTrigger
+        CronTrigger.from_crontab(expr)
+        return True
+    except Exception:
+        return False

core/task_manager.py

@@ -21,6 +21,7 @@ import json
 import time
 import uuid
 import threading
+from collections import Counter
 from datetime import datetime
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
@@ -31,6 +32,7 @@ from config import DATA_DIR
 from core.logger import get_logger
 from core.models import db, DeviceGroup as GroupRow, TaskJob as JobRow
 from core import device_pool
+from core import notifier
 from .adb_helper import get_foreground_app, get_foreground_app_remote
 from .device_worker import (
     DeviceOfflineError,
@@ -47,6 +49,81 @@ _log = get_logger("core.tm")
 _START_STAGGER_SEC = 0.2
 
 
+def _dev_model(serial, tracker=None):
+    """设备型号：优先用批次开始时查好的设备池快照，退回 worker 上报的状态表。
+
+    为什么优先快照：worker 每次启动都会 `_update_status(model=…)`，但那次采集
+    （`d.info()`）可能超时/失败 → 型号是空；而设备池的型号是后台统一采集的、
+    稳定得多。快照还有个好处：不查库（通知路径上不碰 DB）。
+    """
+    if tracker is not None:
+        m = (tracker.models or {}).get(serial)
+        if m:
+            return m
+    with _WORKERS_LOCK:
+        return _WORKERS.get(serial, {}).get("model") or ""
+
+
+def _dev_fail_note(serial, dname, tracker=None):
+    """失败设备的一行说明：`名字（型号）：原因`——批次汇总里直接列出来。
+
+    型号同上用快照；原因取 worker 上报的 last_error（刚写进去，还在）。
+    """
+    with _WORKERS_LOCK:
+        err = _WORKERS.get(serial, {}).get("last_error") or ""
+    cause = err.strip().splitlines()[0] if err.strip() else ""
+    model = _dev_model(serial, tracker)
+    head = f"{dname}（{model}）" if model else str(dname)
+    return f"{head}：{cause[:60]}" if cause else head
+
+
+class _BatchTracker:
+    """一次任务批次的收尾统计：**所有设备都出结果**后发一条 `task.batch.finished`。
+
+    为什么不每台设备各发一条"批次结束"：100 台设备就是 100 条刷屏。这里只计数，
+    归零那一刻发一条汇总（锁外发，见 done()）。
+
+    每台设备的结果由 `_run_with_retry` 的 finally 调一次 `done(serial, outcome)`——
+    放在 finally 里是为了保证"任何一个 return 分支都会被计数一次"，不会漏也不会重。
+    """
+
+    def __init__(self, job, total, names=None, models=None):
+        self.job = job
+        self.total = total
+        # serial -> 设备名（通知里显示名字而不是裸地址）；取不到就是空
+        self.names = dict(names or {})
+        # serial -> 型号（批次开始时从设备池查一次带下来，通知里直接用）
+        self.models = dict(models or {})
+        self._lock = threading.Lock()
+        self._left = total
+        self._stats = Counter()
+        self._failed = []          # 失败设备明细（型号 + 原因），汇总里有失败时列出
+        self._t0 = time.time()
+
+    def done(self, serial, outcome="failed", detail=""):
+        """登记一台设备的结果（success/failed/stopped/skipped）。
+
+        detail 只对 failed 有意义（"设备名（型号）：原因"），最多留 5 条 ——
+        批次汇总里列出来，用户不用再去翻日志。
+        """
+        with self._lock:
+            self._left -= 1
+            self._stats[outcome] += 1
+            if outcome == "failed" and detail and len(self._failed) < 5:
+                self._failed.append(detail)
+            left = self._left
+            s = dict(self._stats)
+            fails = list(self._failed)
+        if left > 0:
+            return
+        notifier.notify("task.batch.finished", job_id=self.job.id,
+                        job_name=self.job.name, total=self.total,
+                        success=s.get("success", 0), failed=s.get("failed", 0),
+                        stopped=s.get("stopped", 0), skipped=s.get("skipped", 0),
+                        failed_devices=fails,
+                        duration_s=int(time.time() - self._t0))
+
+
 def _in_run_window(schedule, now=None):
     """是否在当前运行窗口内。
 
@@ -633,6 +710,8 @@ class TaskManager:
                 w.stop()
                 stopped.append(serial)
         _log.info(f"定时停止 {job.name}({job.id}): 停止 {len(stopped)} 台设备 {stopped}")
+        notifier.notify("task.cron.stopped", job_id=job.id, job_name=job.name,
+                        stopped_count=len(stopped), serials=stopped[:10])
 
     def next_run_of(self, job):
         """任务下次真正执行的时间（考虑运行窗口）。停用/无 cron 返回 None。"""
@@ -664,23 +743,43 @@ class TaskManager:
         serials = job.resolve_serials(self)
         if not serials:
             _log.warning(f"任务 {job.name} 无可用设备")
+            notifier.notify("task.batch.no_device", job_id=job.id, job_name=job.name,
+                            target=job.target)
             return
         task_cls = get_task_class(job.task_type)
         if not task_cls:
             _log.error(f"未知任务类型: {job.task_type}")
+            notifier.notify("task.batch.unknown_type", job_id=job.id, job_name=job.name,
+                            task_type=job.task_type)
             return
         task = task_cls()
         max_attempts = max(1, job.retry.get("max_attempts", 1))
         delay = job.retry.get("delay", 60)
 
+        notifier.notify("task.batch.started", job_id=job.id, job_name=job.name,
+                        task_type=job.task_type, device_count=len(serials),
+                        serials_preview=serials[:5])
+        # 批次收尾统计：所有设备都出结果后发一条汇总（见 _BatchTracker）
+        # 设备名一次查好带下去（worker 线程里没有 app context，查库要显式包 context）
+        names, models = {}, {}
+        try:
+            with self._db():
+                rows = device_pool.list_devices()
+            names = {d["serial"]: (d.get("name") or "") for d in rows}
+            models = {d["serial"]: (d.get("model") or "") for d in rows}
+        except Exception as e:
+            _log.warning(f"读取设备名/型号失败（通知里将显示地址）: {e}")
+        tracker = _BatchTracker(job, len(serials), names, models)
+
         for idx, serial in enumerate(serials):
             # 每台设备一个重试循环线程，互不影响；错峰延迟在各自线程内等待
             t = threading.Thread(target=self._run_with_retry,
                                  args=(task, serial, job, max_attempts, delay,
-                                       idx * _START_STAGGER_SEC), daemon=True)
+                                       idx * _START_STAGGER_SEC, tracker), daemon=True)
             t.start()
 
-    def _run_with_retry(self, task, serial, job, max_attempts, delay, start_delay=0):
+    def _run_with_retry(self, task, serial, job, max_attempts, delay, start_delay=0,
+                        tracker=None):
         """单设备任务执行 + 重试。
 
         异常分类：
@@ -691,36 +790,58 @@ class TaskManager:
         # 错峰启动：在各自线程内等待，分摊批量启动的连接/占用压力
         if start_delay > 0:
             time.sleep(start_delay)
+        # 设备名（通知里显示"设备：A08"而不是裸地址）
+        dname = (tracker.names.get(serial) if tracker is not None else "") or serial
         # 被抢占的原任务 id（抢占结束后归还）——必须在循环外：
         # 重试时若重置为 None，finally 归还逻辑会丢失信息，被抢占任务永不恢复
         preempted_job = None
+        # 本台设备的结果（供批次统计与通知用）。默认 "failed"：走到重试耗尽就是失败；
+        # 各提前 return 的分支会覆盖它。**在 finally 里统一上报**，保证不漏不重。
+        outcome = "failed"
         try:
             for attempt in range(1, max_attempts + 1):
                 # 用户已请求停止 → 不再启动新 attempt
+                stopped_by_user = False
                 with self._lock:
                     if serial in self._stop_requested:
                         _log.info(f"{serial} 用户已请求停止，取消重试 (job={job.name})")
-                        return
+                        stopped_by_user = True
+                if stopped_by_user:
+                    outcome = "stopped"
+                    notifier.notify("task.device.stopped", serial=serial, device_name=dname,
+                                    job_id=job.id, job_name=job.name, attempt=attempt,
+                                    phase="start")
+                    return
                 # 同一 serial 同时只能一个 worker；不同任务可配置抢占
                 preempt = False
+                skip_reason = ""
                 with self._lock:
                     if serial in self._running:
                         cur = self._running[serial]
                         if cur.get("job_id") == job.id:
                             # 同一任务重复触发：跳过（原行为）
                             _log.warning(f"{serial} 已有任务在跑，跳过 (job={job.name})")
-                            return
+                            skip_reason = "同一任务已在运行"
-                        if not job.params.get("preempt"):
+                        elif not job.params.get("preempt"):
                             # 不同任务且本任务未开启抢占：跳过
                             _log.warning(f"{serial} 已有任务在跑，跳过 (job={job.name})")
-                            return
+                            skip_reason = "设备被其他任务占用"
-                        preempt = True
+                        else:
-                        if not preempted_job:
+                            preempt = True
-                            preempted_job = cur.get("job_id")
+                            if not preempted_job:
+                                preempted_job = cur.get("job_id")
+                if skip_reason:
+                    outcome = "skipped"
+                    return
                 if preempt:
                     # 抢占：锁外停止该设备上的其他任务（stop_device 内部拿同一把锁，
                     # 在锁内调用会死锁！），等其释放后接管
                     _log.warning(f"{serial} 抢占：停止任务 {preempted_job} 后执行 {job.name}")
+                    notifier.notify("task.device.preempted", serial=serial, device_name=dname,
+                                    job_id=job.id, job_name=job.name,
+                                    preempted_job_id=preempted_job,
+                                    preempted_job_name=(self.jobs.get(preempted_job).name
+                                                        if self.jobs.get(preempted_job) else ""))
                     self.stop_device(serial)
                     deadline = time.time() + 30
                     while time.time() < deadline:
@@ -730,6 +851,10 @@ class TaskManager:
                         time.sleep(0.5)
                     else:
                         _log.warning(f"{serial} 抢占超时（旧任务 30s 未退出），跳过 (job={job.name})")
+                        outcome = "skipped"
+                        notifier.notify("task.device.preempt_timeout", serial=serial,
+                                        device_name=dname, job_id=job.id, job_name=job.name,
+                                        preempted_job_id=preempted_job)
                         return
                 with self._lock:
                     self._running[serial] = {"job_id": job.id, "started_at": time.time(),
@@ -739,8 +864,14 @@ class TaskManager:
                                max_attempts=max_attempts)
 
                 worker = None
+                t_attempt = time.time()          # 单次 attempt 耗时（通知里带）
+                # 本次运行的上下文：步骤明细按 run_id 归组，把同一设备同一次尝试
+                # 执行的步骤串起来（重试会生成新的 run_id，两次尝试不混在一起）
+                run_ctx = {"run_id": uuid.uuid4().hex[:12], "job_id": job.id,
+                           "job_name": job.name, "device_name": dname,
+                           "attempt": attempt}
                 try:
-                    worker = task.create_worker(serial, job.params)
+                    worker = task.create_worker(serial, job.params, ctx=run_ctx)
                     with self._lock:
                         self._running[serial]["worker"] = worker
                     _log.info(f"{serial} 开始任务 {job.name} (第{attempt}/{max_attempts}次)")
@@ -756,12 +887,40 @@ class TaskManager:
                     _update_status(serial, task_job="")
                     if st == "done":
                         _log.info(f"{serial} 任务 {job.name} 成功完成")
+                        outcome = "success"
+                        # 单设备成功：**只在"这一批本来就只有一台设备"时发**。
+                        # 多设备批次里逐台报成功没有信息量（批次汇总里已有成功台数），
+                        # 13 台就是 13 条刷屏；失败仍然逐台发——那是少数且要知道是哪台。
+                        if tracker is None or tracker.total <= 1:
+                            notifier.notify("task.device.success", serial=serial,
+                                            device_name=dname,
+                                            model=_dev_model(serial, tracker),
+                                            job_id=job.id, job_name=job.name,
+                                            attempt=attempt,
+                                            duration_s=int(time.time() - t_attempt))
                         return
                     # 用户请求停止（无论 attempt 第几次、status 是什么）→ 不重试
                     with self._lock:
                         if serial in self._stop_requested:
                             _log.info(f"{serial} 用户已请求停止，不再重试 (job={job.name})")
+                            outcome = "stopped"
+                            notifier.notify("task.device.stopped", serial=serial,
+                                            device_name=dname, job_id=job.id,
+                                            job_name=job.name, attempt=attempt,
+                                            phase="after")
                             return
+                    if worker is not None and worker.stopped():
+                        # 任务**自己**停的（步骤里的「停止本设备」）：不是失败，也不重试。
+                        # 判据是"worker 置了停止位但 _stop_requested 里没有"——上面那个
+                        # 分支已经排除了用户/调度停止的情况。
+                        _log.info(f"{serial} 任务内主动停止本设备 (job={job.name})")
+                        outcome = "stopped"
+                        notifier.notify("task.device.stopped", serial=serial,
+                                        device_name=dname,
+                                        model=_dev_model(serial, tracker),
+                                        job_id=job.id, job_name=job.name,
+                                        attempt=attempt, phase="self")
+                        return
                     _log.warning(f"{serial} 任务未成功(status={st})")
                 except DeviceOfflineError as e:
                     # 设备掉线，立即放弃，不重试
@@ -770,30 +929,49 @@ class TaskManager:
                         self._running.pop(serial, None)
                     _update_status(serial, status="failed", task_job="",
                                    last_error=f"设备离线: {e}")
+                    outcome = "failed"
+                    notifier.notify("task.device.offline", serial=serial, device_name=dname,
+                                    model=_dev_model(serial, tracker),
+                                    job_id=job.id, job_name=job.name,
+                                    error=str(e)[:200])
                     return
                 except Exception as e:
                     _log.error(f"{serial} 执行异常: {e}", exc_info=True)
                     with self._lock:
                         self._running.pop(serial, None)
                     _update_status(serial, task_job="")
+                    notifier.notify("task.device.error", serial=serial, device_name=dname,
+                                    model=_dev_model(serial, tracker),
+                                    job_name=job.name, attempt=attempt,
+                                    error=str(e)[:200])
 
                 if attempt < max_attempts:
                     # 用户在 sleep 期间点停止也能中断
                     with self._lock:
                         if serial in self._stop_requested:
                             _log.info(f"{serial} 用户已请求停止，取消重试 (job={job.name})")
+                            outcome = "stopped"
+                            notifier.notify("task.device.stopped", serial=serial,
+                                            device_name=dname, job_name=job.name,
+                                            attempt=attempt, phase="retry-wait")
                             return
                     # 检查是否是端口耗尽类临时错误，需要更长退避等端口释放
                     with _WORKERS_LOCK:
                         err = _WORKERS.get(serial, {}).get("last_error", "")
-                    if err.startswith("[transient]"):
+                    transient = err.startswith("[transient]")
+                    if transient:
                         # Windows TCP 端口耗尽，TIME_WAIT 默认 2-4 分钟，等 120 秒
                         extra_delay = max(delay, 120)
                         _log.info(f"{serial} ADB 连接临时错误（端口耗尽），{extra_delay}s 后重试 ({attempt+1}/{max_attempts})")
-                        time.sleep(extra_delay)
+                        wait = extra_delay
                     else:
                         _log.info(f"{serial} {delay}s 后重试 ({attempt+1}/{max_attempts})")
-                        time.sleep(delay)
+                        wait = delay
+                    notifier.notify("task.device.retry", serial=serial, device_name=dname,
+                                    job_name=job.name, attempt=attempt,
+                                    next_attempt=attempt + 1, delay_s=int(wait),
+                                    reason="transient" if transient else "normal")
+                    time.sleep(wait)
 
             _log.error(f"{serial} 任务 {job.name} 重试耗尽，放弃")
             # 带上最后一次的真实失败原因——只写"重试N次失败"会让用户看不到为什么失败
@@ -805,20 +983,40 @@ class TaskManager:
             if cause and cause != msg:
                 msg += f"：{cause}"
             _update_status(serial, status="failed", last_error=msg[:200])
+            outcome = "failed"
+            notifier.notify("task.device.failed", serial=serial, device_name=dname,
+                            model=_dev_model(serial, tracker), job_id=job.id,
+                            job_name=job.name, attempts=max_attempts,
+                            cause=cause, msg=msg)
         finally:
             # 清除停止标志：整个重试循环结束（成功/失败/停止）后允许下次任务
             with self._lock:
                 self._stop_requested.discard(serial)
+            # 批次统计：**每台设备只在这里上报一次**（所有 return 分支都会走到 finally）
+            if tracker is not None:
+                try:
+                    tracker.done(serial, outcome,
+                                 detail=_dev_fail_note(serial, dname, tracker)
+                                 if outcome == "failed" else "")
+                except Exception as e:
+                    _log.warning(f"批次统计上报失败（不影响任务）: {e}")
             # 归还：本任务是抢占任务，结束后自动重新启动被抢占的原任务
             if preempted_job:
                 j = self.jobs.get(preempted_job)
                 if j and j.enabled:
                     _log.info(f"{serial} 抢占任务 {job.name} 结束，归还设备给任务 {j.name}")
+                    notifier.notify("task.device.released", serial=serial, device_name=dname,
+                                    job_name=job.name, preempted_job_id=preempted_job,
+                                    returned=True, reason="归还并重启被抢占任务")
                     threading.Thread(target=self._run_job, args=(j,), daemon=True).start()
                 else:
                     # 打日志便于排查：被抢占任务已删除/停用时不会归还，但要知道原因
                     _log.info(f"{serial} 抢占任务 {job.name} 结束，"
                               f"被抢占任务 {preempted_job} {'已停用，不归还' if j else '已不存在，不归还'}")
+                    notifier.notify("task.device.released", serial=serial, device_name=dname,
+                                    job_name=job.name, preempted_job_id=preempted_job,
+                                    returned=False,
+                                    reason="被抢占任务已停用" if j else "被抢占任务已不存在")
 
     # ---- 运行控制 ----
     def stop_device(self, serial):

core/u2_helper.py

@@ -5,6 +5,7 @@
 """
 import time
 import random
+import re
 
 from core.logger import get_logger
 
@@ -65,6 +66,34 @@ def random_sleep(min_s, max_s):
     time.sleep(random.uniform(min_s, max_s))
 
 
+def screen_is_on(d):
+    """屏幕是否亮着。返回 True/False，取不到返回 None（三态，别当 False 用）。
+
+    为什么不用 `d.info`：它在部分设备上一次要**十几秒**（见 doc/backlog/TODO.md）；
+    `dumpsys power` 经 atx-agent 跑只要 ~0.3s，且 `mWakefulness` 字段全机型都有
+    （MIUI 的 `dumpsys display` 反而没有 mScreenState）。
+    """
+    try:
+        out = d.shell("dumpsys power")
+        out = getattr(out, "output", None) or str(out)
+        m = re.search(r"mWakefulness=(\w+)", out)
+        if m:
+            return m.group(1).lower() != "asleep"
+    except Exception as e:
+        _log.warning(f"读取屏幕状态失败: {e}")
+    return None
+
+
+def current_package(d):
+    """当前前台 App 包名；取不到返回空串。"""
+    try:
+        cur = d.app_current() or {}
+        return cur.get("package") or ""
+    except Exception as e:
+        _log.warning(f"读取前台 App 失败: {e}")
+    return ""
+
+
 def safe_click(el, timeout=1):
     """安全点击：元素存在才点，不抛异常。返回是否点击成功。"""
     try:

core/uiauto_helper.py

@@ -12,7 +12,7 @@ API 参考（uiautodev 0.14）：
   - GET /api/android/{serial}/dump_hierarchy — 元素树 JSON
 """
 import requests
-from collections import Counter
+from collections import Counter, defaultdict
 
 from core.logger import get_logger
 
@@ -79,24 +79,32 @@ def get_elements(serial):
     """获取指定设备的 UI 元素树。
 
     返回 (ok, data_or_error)：
-      ok=True  — data 是元素列表 [{name, attrs..., suggested:{type,value,indexed?,occ?,total?,broad?}}, ...]
+      ok=True  — data 是元素列表 [{name, attrs..., suggested:{type,value,semantic?,via?,indexed?,occ?,total?,broad?}}, ...]
       ok=False — data 是错误消息字符串
 
     元素树由 uiautodev 的 dump_hierarchy 返回（JSON）。我们递归提取每个节点的
     关键属性（resource-id/text/description/class/bounds...），供前端列表展示和选择。
 
-    选择器精度策略（精确到具体按钮的关键）：
+    选择器精度策略（精确到具体按钮的关键，优先级见 doc/research/U2_ELEMENT_SELECTORS.md §三）：
       1. 有 resource-id/text/content-desc 的元素：
          先预统计该属性在整棵树中的出现次数——
            - 唯一出现：直接用属性选择器 //*[@resource-id="x"]
-           - 重复出现（如抖音底部导航 4 个 tab 同 id）：用**整体加括号**的
+           - 重复出现（如抖音底部导航的 tab 同 id，个数还随灰度版本变）：
-             `(//*[@resource-id="x"])[k]` 精确到第 k 个匹配。
+             **优先用第二个属性把目标单独圈出来**（语义选择器）：
+               //*[@resource-id="x" and @text="我"]
+             它只认"这个元素的文字/id 是什么"，不认"同 id 一共几个"，
+             换设备/换版本依然成立 → 标记 semantic + via（用于限定的属性）。
+           - 两个属性组合仍圈不出来时，才退回**整体加括号**的
+             `(//*[@resource-id="x"])[k]`（标记 indexed，前端醒目提示脆弱）。
              注意 XPath 语义：`//*[@id="x"][k]` 是"在其父节点中排第 k"，不是
              第 k 个匹配——历史实现踩过这个坑（多实例时 [2..n] 全部失配）。
       2. 无任何属性的元素：
          用最近一个有属性祖先的选择器限定范围 + 同 class 兄弟序号定位
-         （如 //*[@resource-id="x"]/FrameLayout/ImageView[2]）；
+         （如 //*[@resource-id="x"]/*[@class="android.widget.ImageView"][2]）；
-         整棵树都没有属性时退化为从根开始的结构路径（标记 broad，前端提示脆弱）。
+         整棵树都没有属性时退化为从根开始的结构路径
+         （//hierarchy/*[1]/*[3]…，标记 broad，前端提示脆弱）。
+         注意：dump 的 XML 标签一律是 <node>，class 在 @class 上 —— 任何把
+         class 名当标签名的写法（//FrameLayout[1]）都永远匹配不到，别再用。
     """
     if not serial:
         return False, "缺少 serial"
@@ -125,6 +133,25 @@ def get_elements(serial):
         return False, f"抓取失败: {e}"
 
 
+def _child_path(path):
+    """内部路径 `/0/2/1` → XPath 段 `/*[1]/*[3]/*[2]`（按**子节点位置**逐层定位）。
+
+    用于"整棵树都没有可用属性"时的兜底结构路径。为什么按位置而不是 `@index`：
+    实测 Android dump 里同级节点的 index 属性**会重复**（状态栏/内容区/导航栏
+    三个兄弟的 index 全是 "0"），拿它定位会一次命中好几个。
+    """
+    return "".join(f"/*[{int(seg) + 1}]"
+                   for seg in path.strip("/").split("/") if seg)
+
+
+def _xpath(conds):
+    """由条件列表拼 XPath：[(attr, value), ...] → `//*[@a="1" and @b="2"]`。
+
+    单个条件即 `//*[@a="1"]`。多个条件是**并列且**，任一条不成立就不匹配。
+    """
+    return "//*[" + " and ".join(f"@{a}={_xpath_q(v)}" for a, v in conds) + "]"
+
+
 def _xpath_q(v):
     """XPath 字符串字面量：优先双引号，值含双引号时改用单引号包裹（XPath 1.0 无转义）。"""
     if '"' in v:
@@ -134,8 +161,10 @@ def _xpath_q(v):
 
 def _extract(root, out):
     """把 uiautodev 元素树扁平化为可选列表，并为每个节点生成精确选择器建议。"""
-    # 全树属性出现次数（预统计，供重复元素加 [k] 序号消歧）
+    # 全树属性出现次数（预统计：判断"这个值重不重复"，决定要不要消歧）
     id_cnt, text_cnt, desc_cnt = Counter(), Counter(), Counter()
+    # 同属性值 → 该值对应的全部节点 properties（语义消歧要在"同值节点"里比第二个属性）
+    id_nodes, text_nodes, desc_nodes = defaultdict(list), defaultdict(list), defaultdict(list)
     # 文档顺序已出现次数（决定当前元素是第几个）
     seen_id, seen_text, seen_desc = Counter(), Counter(), Counter()
 
@@ -146,15 +175,57 @@ def _extract(root, out):
         rid, text, desc = (props.get(k, "") for k in ("resource-id", "text", "content-desc"))
         if rid:
             id_cnt[rid] += 1
+            id_nodes[rid].append(props)
         if text:
             text_cnt[text] += 1
+            text_nodes[text].append(props)
         if desc:
             desc_cnt[desc] += 1
+            desc_nodes[desc].append(props)
         for c in node.get("children") or []:
             count_attrs(c)
 
-    def attr_selector(attr, value, cnt, seen):
+    # 消歧时可用的次要属性（按"越稳越靠前"排：文字 > 描述 > class）
-        """属性选择器：唯一直接出；重复时用 `(…)[k]` 精确到**第 k 个匹配**。
+    _SECONDARY_ATTRS = ("text", "content-desc", "class")
+
+    def secondary_conds(peers, props):
+        """属性值重复时，找一组能**把本节点单独圈出来**的次要属性。
+
+        例：抖音底部 4 个 tab 共享 resource-id `…:0qf`，但 text 分别是
+        首页/朋友/消息/我 —— 于是
+            //*[@resource-id="…:0qf" and @text="我"]
+        这种**语义选择器**只依赖"目标自己长什么样"，不依赖"同 id 一共几个"：
+        灰度版把 tab 从 4 个变 3 个、换一台设备，它照样命中。
+        对比 `(…)[k]`：那是"第 k 个匹配"，界面一变就指到别的元素上 → 点不中。
+
+        返回 ([(attr, value), ...], via) 或 (None, None)。peers 是"同主属性值"的
+        全部节点 properties —— 唯一性只需在这一集合内成立（任何匹配都必然在此集合中）。
+        """
+        def matched(conds):
+            return sum(1 for p in peers
+                       if all((p.get(a) or "") == v for a, v in conds))
+
+        usable = [(a, props.get(a) or "") for a in _SECONDARY_ATTRS]
+        usable = [(a, v) for a, v in usable if v.strip()]  # 空值不能做限定条件
+        # 单个次要属性够了就用它（选择器最短）
+        for a, v in usable:
+            if matched([(a, v)]) == 1:
+                return [(a, v)], a
+        # 单个不够 → 两个次要属性组合（如 @text + @class）
+        for i in range(len(usable)):
+            for j in range(i + 1, len(usable)):
+                conds = [usable[i], usable[j]]
+                if matched(conds) == 1:
+                    return conds, f"{usable[i][0]}+{usable[j][0]}"
+        return None, None
+
+    def attr_selector(attr, value, cnt, seen, peers, props):
+        """属性选择器：唯一直接出；重复时**先语义消歧，再退化到序号**。
+
+        语义消歧（2026-09-13 新增，见 doc/research/U2_ELEMENT_SELECTORS.md §五）：
+          //*[@resource-id="x" and @text="我"]   ← 不依赖元素个数，换设备/换版本仍成立
+        退而求其次（同 id 同文字都分不开，如列表里的重复项）：
+          (//*[@resource-id="x"])[2]            ← 精确到第 2 个匹配，但界面一变就失配
 
         重要（XPath 位置谓词语义）：
           //*[@resource-id="x"][2]   → 「在**其父节点**中排第 2 的属性匹配」，**不是**第 2 个匹配
@@ -163,12 +234,20 @@ def _extract(root, out):
         [2..n] 全部匹配不到 → 运行时"未找到元素"（2026-09-10 实测修复）。
         """
         seen[value] += 1
-        base = f'//*[@{attr}={_xpath_q(value)}]'
+        conds = [(attr, value)]
         if cnt[value] > 1:
-            val = f"({base})[{seen[value]}]"
+            extra, via = secondary_conds(peers, props)
-            return val, {"type": "xpath", "value": val,
+            if extra:
-                         "indexed": True, "occ": seen[value], "total": cnt[value]}
+                conds += extra
-        return base, {"type": "xpath", "value": base}
+            else:
+                val = f"({_xpath(conds)})[{seen[value]}]"
+                return val, {"type": "xpath", "value": val, "indexed": True,
+                             "occ": seen[value], "total": cnt[value]}
+        val = _xpath(conds)
+        info = {"type": "xpath", "value": val}
+        if len(conds) > 1:
+            info.update(semantic=True, via=via)
+        return val, info
 
     def flatten(node, depth=0, path="", ctx=None, tag_path="", tag_index=1):
         """递归扁平化。
@@ -201,7 +280,10 @@ def _extract(root, out):
         # 始终带同 class 兄弟序号（含 [1]），结构路径才精确无歧义；
         # class 为空的层（tag=*）不参与结构路径，避免 //*[N] 前缀污染导致选择器定位到任意节点
         if tag != "*":
-            seg = f"{tag}[{tag_index}]"
+            # 步进必须写成 `*[@class="…"]`，**不能**写 `FrameLayout[1]`：
+            # Android dump 的 XML 里每个元素的**标签名都是 `<node>`**，class 在
+            # @class 属性上 —— 写成标签名会永远匹配不到任何东西（见下方 broad 注释）。
+            seg = f"*[@class={_xpath_q(cls)}][{tag_index}]"
             own_tag_path = f"{tag_path}/{seg}" if tag_path else seg
         else:
             seg = ""
@@ -209,11 +291,14 @@ def _extract(root, out):
 
         # ---- 推荐选择器：唯一属性 > 锚点祖先限定 > 全结构路径 ----
         if rid:
-            child_ctx, suggested = attr_selector("resource-id", rid, id_cnt, seen_id)
+            child_ctx, suggested = attr_selector("resource-id", rid, id_cnt, seen_id,
+                                                 id_nodes[rid], props)
         elif text:
-            child_ctx, suggested = attr_selector("text", text, text_cnt, seen_text)
+            child_ctx, suggested = attr_selector("text", text, text_cnt, seen_text,
+                                                 text_nodes[text], props)
         elif desc:
-            child_ctx, suggested = attr_selector("content-desc", desc, desc_cnt, seen_desc)
+            child_ctx, suggested = attr_selector("content-desc", desc, desc_cnt, seen_desc,
+                                                 desc_nodes[desc], props)
         elif ctx:
             val = f"{ctx}/{seg}"
             suggested = {"type": "xpath", "value": val}
@@ -226,8 +311,12 @@ def _extract(root, out):
                              "invalid": True,
                              "reason": "该元素无可用属性（id/文本/class），无法生成可靠选择器"}
             else:
-                # 无唯一属性且无锚点祖先：用从根开始的结构路径（脆弱，标记 broad 让前端提示）
+                # 无唯一属性且无锚点祖先：用从根开始的结构路径（脆弱，标记 broad 让前端提示）。
-                suggested = {"type": "xpath", "value": f"//{own_tag_path}", "broad": True}
+                # 按子节点位置逐层定位 —— 历史实现写成 //FrameLayout[1]/LinearLayout[2]
+                # 这种"class 当标签名"的路径，**永远零命中**（dump 的标签全是 <node>）；
+                # 实测 248 个元素里 26 条死选择器，2026-09-13 修复。
+                suggested = {"type": "xpath", "value": f"//hierarchy{_child_path(path)}",
+                             "broad": True}
             child_ctx = None
 
         out.append({
@@ -258,3 +347,96 @@ def _extract(root, out):
 
     count_attrs(root)
     flatten(root)
+
+
+# ================== 原生 u2 快照（截图 + 元素树一次取齐） ==================
+def _xml_to_node(elem):
+    """把 uiautomator2 的 XML 节点转成 uiautodev 那套 {name, properties, children}。
+
+    两边的属性名本来就一样（resource-id / text / content-desc / class / bounds 字符串），
+    所以只要套一层壳，就能原样复用上面的 _extract（选择器建议逻辑不用写第二遍）。
+    """
+    props = dict(elem.attrib)
+    return {"name": props.get("class", ""), "properties": props,
+            "children": [_xml_to_node(c) for c in list(elem)]}
+
+
+def _shots_differ(a, b, threshold=8):
+    """两张截图是不是"明显不一样"（用来判断抓取期间界面有没有在动）。
+
+    逐像素求差的包围盒 → 用"变化区域占比"判断，避免个别像素抖动误报。
+    """
+    try:
+        from PIL import ImageChops
+        if a.size != b.size:
+            return True
+        diff = ImageChops.difference(a.convert("RGB"), b.convert("RGB"))
+        bbox = diff.getbbox()
+        if not bbox:
+            return False
+        area = (bbox[2] - bbox[0]) * (bbox[3] - bbox[1])
+        total = a.size[0] * a.size[1]
+        # 变化面积超过阈值（默认 8%）才算"界面在动"
+        return (area / total) * 100.0 > threshold
+    except Exception:
+        return False
+
+
+def snapshot(serial, quality=85):
+    """一次取齐：设备截图 + 元素树（**同一个 u2 连接、背靠背取**）。
+
+    为什么不用现在的"两个接口"：截图和元素树分两次取时，中间隔着 dump 本身的
+    1.3~1.8 秒；界面只要在动画（信息流/视频/加载），框就会落在旧位置上。
+
+    顺带做**双截图校验**：dump 前后各截一张，两张差得多就标 `unstable`，
+    让前端明确提示"界面在变化中，请停在静止界面再抓"——而不是悄悄给一个错位的框。
+
+    返回 (ok, 数据 | 错误信息)。数据形如：
+      {"image": "data:image/jpeg;base64,…", "width": 720, "height": 1650,
+       "elements": [...], "unstable": false, "screen_state": "on", "cost_ms": 1800}
+    """
+    import base64
+    import io
+    import time as _t
+    import xml.etree.ElementTree as ET
+
+    import uiautomator2 as u2
+
+    t0 = _t.time()
+    try:
+        d = u2.connect(serial)
+        img1 = d.screenshot()                  # 先截：用户看到的就是这一刻
+        # 屏幕开关状态（MCP 的 de_snapshot 要用它判断"要不要先 de_wake"；
+        # 本来只有 /api/screen/thumb 的响应头里有，这里顺手带上）
+        try:
+            screen_on = d.info.get("screenOn")
+        except Exception:
+            screen_on = None
+        xml = d.dump_hierarchy()               # 慢的一步（1.3~1.8s）
+        img2 = d.screenshot()                  # 再截：和第一张比对
+    except Exception as e:
+        return False, f"抓取失败: {e}"
+
+    unstable = _shots_differ(img1, img2)
+    if not unstable:
+        img2.close()
+    try:
+        buf = io.BytesIO()
+        img1.convert("RGB").save(buf, format="JPEG", quality=quality)
+        image = "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode()
+        w, h = img1.size
+    except Exception as e:
+        return False, f"截图编码失败: {e}"
+
+    elements = []
+    try:
+        root = ET.fromstring(xml)
+        _extract(_xml_to_node(root), elements)
+    except Exception as e:
+        return False, f"元素树解析失败: {e}"
+
+    return True, {"image": image, "width": w, "height": h,
+                  "elements": elements, "unstable": unstable,
+                  "screen_state": ("on" if screen_on else "off")
+                                  if screen_on is not None else "unknown",
+                  "cost_ms": int((_t.time() - t0) * 1000)}

doc/AI_CONSOLE.md

@@ -7,7 +7,14 @@
 
 ## 1. 它是什么
 
-「AI 控制台」是后台的一个顶级 Tab（仅管理员）：选一台设备，用自然语言下指令，AI 通过 MCP 工具**看屏幕、点按、输入**，边做边把过程和结论流式显示出来。
+「AI 控制台」是后台的一个顶级 Tab（仅管理员），下面有两个子分栏：
+
+| 子分栏 | 做什么 | 文档 |
+|--------|--------|------|
+| 💬 **聊天** | 选一台设备用自然语言下指令，AI 通过 MCP 工具**看屏幕、点按、输入**，边做边把过程和结论流式显示出来（本文内容） | 本文 |
+| 🧭 **AI 建任务** | 描述"要什么样的自动化"，AI **自己在真机上探索**（看屏/读元素树/点按验证），把走通的路径写成**一条可调度任务**，校验后交人工在步骤编辑器确认 | [AI_TASK_GEN.md](AI_TASK_GEN.md) |
+
+> 两个子分栏共用**同一个运行槽**（全平台同时只允许一个 Agent 运行）：建任务在探索时，聊天页会显示"● 建任务探索中"并禁用发送，反之亦然。
 
 ```
 你：「打开小红书搜索苏州好吃的饭店，把前 5 条列出来」
@@ -78,6 +85,11 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage,
 - 一轮整体超时 **900 秒**；达到步数上限会让模型做一次收尾总结
 - 工具调用由 MCP Server 执行（`:8033`），后者再调平台 HTTP 接口/直连设备
 - **设备忙时拒绝**：目标设备正在跑任务 → `409`（"AI 不与任务抢设备"）
+- `mode:"designer"`（AI 建任务）走同一条链路，差别：换一套 system prompt（任务设计师）、
+  输出上限提到 8192、**不吃聊天历史**、多一个平台级本地工具 `submit_task`
+  （不经 MCP，服务端用 `core/task_draft` 校验，见 [AI_TASK_GEN.md](AI_TASK_GEN.md)）
+- 工具结果必须是**连续的** tool 消息：一轮里若同时调了截图与别的工具，图像会攒到本轮工具
+  消息发完后再作为一条 user 消息附上（否则模型侧会以"工具回应不足"报 400）
 
 ### 3.2 会话消息模型
 
@@ -99,11 +111,16 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage,
 | `delta` | `{"text","kind":"content"\|"reasoning"}` | 正文增量渲染 Markdown；推理增量进入可折叠「💭 思考过程」 |
 | `step` | `{"tool","args","image"?}` | 追加工具卡片（含缩略截图，点击放大）；伪卡片提示经验/动作命中与沉淀 |
 | `usage` | `{"prompt_tokens","completion_tokens","total_tokens","calls"}` | 刷新单条消息脚注与顶栏「本会话累计」 |
-| `done` | `{"answer","usage"}` | 最终答案 + 收尾 |
+| `done` | `{"answer","usage","mode","draft"?,"warnings"?,"draft_error"?}` | 最终答案 + 收尾；`mode=designer` 时带任务草稿（或草稿被拦的原因） |
 | `error` | `{"message"}` | 展示错误（MCP 不可达等已转成明确文案） |
 
 **刷新/重连不丢进度**：服务端事件队列保留积压，页面重新订阅（`GET /api/agent/stream?run_id=`）后会补发 delta/step/usage/done；`EventSource.onerror` **刻意不结束运行**，靠自动重连续上。另外 `GET /api/agent/run` 提供状态快照（其他窗口/8s 轮询用）。
 
+**多页面同时看同一轮**：一轮的事件用**扇出**（`web/agent_api.py` 的 `_Fanout`）发给每个订阅者各自
+的队列——两个页面都收到全量事件。**不要**退回"一个 run 一个 `queue.Queue`"：那样第二个页面一订阅，
+两个 EventSource 就开始瓜分同一条队列，谁先取到算谁的（2026-09-14 实测：聊天页把建任务页的 `done`
+取走了，建任务页永远等不到草稿）。
+
 ### 3.4 token 统计
 
 - 请求带 `stream_options.include_usage`，服务端在**末尾 chunk** 返回 usage
@@ -167,7 +184,7 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage,
 从本轮**成功**的步骤轨迹里提炼命名动作（如「打开抖音」）。硬约束：
 
 - **禁坐标**：带 `click_xy` 的步骤不会被沉淀（坐标换个设备/分辨率就失效）
-- 白名单步骤类型（18 种去掉 `click_xy`、`keep_screen`）
+- 白名单步骤类型（21 种去掉 `click_xy`、`keep_screen`、`gesture`）
 - 每类型有必填参数校验（如 `click` 必须有选择器）
 - 输入/产出限量：最多 10 步输入、最多 3 个动作 × 4 步
 - 保存时服务端**再校验一次**，含坐标的提交直接 400
@@ -191,8 +208,10 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage,
 | `agent_api_key` | API Key（**明文存库**） | — |
 | `agent_default_serial` | 默认目标设备 | 空 |
 | `agent_max_steps` | 最大步数（钳制 1-200） | 40 |
+| `agent_task_draft` | **AI 建任务**最近一份草稿（JSON：`{draft, warnings, prompt, created}`，只留最近一份；不是任务，入库仍走人工确认） | 空 |
 
-其它常量：单轮超时 900s、推理链落库上限 6000 字符、会话消息上限 60 条、历史上下文取最近 12 轮。
+其它常量：单轮超时 900s、推理链落库上限 6000 字符、会话消息上限 60 条、历史上下文取最近 12 轮；
+建任务模式（designer）输出上限 8192、单工具调用上限 40 次（`mcp_agent/agent.py`）。
 
 ---
 

doc/AI_TASK_GEN.md

@@ -1,14 +1,15 @@
 # AI 建任务（AI Task Generator）设计文档
 
-> 状态：**设计稿，尚未实现**（P0 未开工）——本文描述的是「要做什么、为什么这么做」，不是现状。
+> 状态：**P0 已实现**（2026-09-13）——§1~§9 是设计稿（与实现基本一致），
-> 现状请读：[AI_CONSOLE.md](AI_CONSOLE.md)（AI 控制台已实现的能力）、[TASK_DEV.md](TASK_DEV.md)（任务与步骤）、[MCP.md](MCP.md)（已实现的 19 个工具）。
+> **§10 是实现记录**：差异、落地细节、怎么自测，以 §10 为准。
+> 现状请读：[AI_CONSOLE.md](AI_CONSOLE.md)（AI 控制台已实现的能力）、[TASK_DEV.md](TASK_DEV.md)（任务与步骤）、[MCP.md](MCP.md)（已实现的 20 个工具）。
 > 关联代码：`web/agent_api.py`、`mcp_server/`、`mcp_agent/`、`tasks/generic/`、`static/admin/editor.js`。最后核对：2026-09-10。
 
 ## 1. 背景与目标
 
 平台已有两套能力，但互不相通：
-- **AI 控制台**：一句话 + 选设备 → 多模态 Agent（DeepSeek）通过 19 个 `de_*` 工具在手机上「边看边做」（截图看屏、`de_ui_tree` 拿元素树、`de_tap_element/de_tap_text` 语义点按），流式回放步骤。
+- **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…21 种节点），在编辑器里拖拽编排、单步试跑、定时调度。
 
 目标：让**非工程用户用一句自然语言需求**（例：「创建一个每日养号刷视频的任务，每天 8:00-9:00 在 100.100.10.13 跑」）得到**一条可直接调度、可继续在现有步骤编辑器里手改的任务**。AI 先自己在设备上打开 App、看 UI 树、确认可点元素，再直接撰写编辑器的步骤 JSON。
 
@@ -35,7 +36,7 @@
 
 ## 3. 现状与可复用点（实现依据）
 
-- 多模态 Agent 链路：`web/agent_api.py`（`POST /api/agent/run` 起后台线程、SSE `delta/step/done/error`、`/stop`、刷新恢复 `GET /api/agent/run`）→ `mcp_agent/agent.py`（OpenAI 兼容流式，工具经 fastmcp Client 拉 8033 的 19 个 `de_*`）→ `mcp_server/mcp_server.py`。
+- 多模态 Agent 链路：`web/agent_api.py`（`POST /api/agent/run` 起后台线程、SSE `delta/step/done/error`、`/stop`、刷新恢复 `GET /api/agent/run`）→ `mcp_agent/agent.py`（OpenAI 兼容流式，工具经 fastmcp Client 拉 8033 的 20 个 `de_*`）→ `mcp_server/mcp_server.py`。
 - 前端 AI 控制台骨架：`templates/admin/monitor.html` `#tab-agent` + `static/admin/agent.js`（设备选择、`sendAgentMsg`、`listenStream` 渲染 `agent-toolcard`、实时画面跟随）。
 - 步骤权威 schema（前后端同构）：`tasks/generic/task.py` `STEP_TYPES`（L44-83）/ `DEFAULT_PARAMS`（L86-103） 与 `static/admin/editor.js` `STEP_LIB`（L3-23）。
 - 元素抓取 → XPath：`web/tasks_api.py /api/uiauto/elements`（L224）→ `core/uiauto_helper.get_elements`（`suggested.value` 即编辑器可用的 XPath）。
@@ -154,10 +155,10 @@
 
 ## 9. 需要转成 MCP / 平台工具的能力（分层，2026-09-09 与用户确认）
 
-> 背景问答结论：目前 MCP 只有**设备层 19 个 `de_*`**（控制 + 只读 `de_list_tasks`），平台 CRUD（任务增改/启停/立即运行、分组、设备池、自定义动作、APK、备份、用户）**都还没 MCP 化**。方向认同「先把工具链补完善」，但不做"把所有平台 CRUD 一次性搬成 MCP"的大而全——**按消费方（AI 建任务 / 外部自动化）分层、按需补**。新增 MCP 工具一律：进 `doc/MCP.md` 手册 + `doc/MCP_DESIGN.md` 规格 + 与 web 同源的权限/busy/审计 + 校验逻辑下沉到 `core/` 共用（防双份漂移）。
+> 背景问答结论：目前 MCP 只有**设备层 20 个 `de_*`**（控制 + 只读 `de_list_tasks`），平台 CRUD（任务增改/启停/立即运行、分组、设备池、自定义动作、APK、备份、用户）**都还没 MCP 化**。方向认同「先把工具链补完善」，但不做"把所有平台 CRUD 一次性搬成 MCP"的大而全——**按消费方（AI 建任务 / 外部自动化）分层、按需补**。新增 MCP 工具一律：进 `doc/MCP.md` 手册 + `doc/MCP_DESIGN.md` 规格 + 与 web 同源的权限/busy/审计 + 校验逻辑下沉到 `core/` 共用（防双份漂移）。
 
 ### 9.1 现状盘点
-- MCP（`mcp_server/mcp_server.py`，19 个 `de_*`）＝ 设备控制 + 设备只读 + `de_list_tasks`（平台任务只读）。
+- MCP（`mcp_server/mcp_server.py`，20 个 `de_*`）＝ 设备控制 + 设备只读 + `de_list_tasks`（平台任务只读）。
 - 任务创建/修改/删除、toggle、立即运行、分组、设备池管理、自定义动作、APK、系统备份等 **REST 路由只给前端用，未暴露 MCP**。
 
 ### 9.2 P0 —— AI 建任务链路真正需要的「平台工具」（最小集）
@@ -181,3 +182,86 @@
 ### 9.4 分层与登记（红线）
 - 每新增/修改/删除一个 MCP 工具或平台配置：同步更新 `doc/MCP.md`（全清单）、`doc/MCP_DESIGN.md`（规格/层级），并在提交里体现——见全局「doc 同步红线」。
 - `core/task_draft.py` 是 web 校验与 MCP 校验的**唯一来源**，杜绝两套规则漂移。
+
+---
+
+## 10. 实现记录（2026-09-13）
+
+### 10.1 与设计稿的差异（以本节为准）
+
+| 设计稿 | 实际实现 | 为什么 |
+|---|---|---|
+| 聊天页加「模式」开关 | AI 控制台下的**独立子分栏**「🧭 AI 建任务」 | 用户要求独立页面；探索回放 + 草稿预览需要自己的版面 |
+| `submit_task` 作为平台工具（§9.2，未指定放哪层） | **Agent 本地工具**（`mcp_agent/agent.py` 的 `LOCAL_TOOL_SPECS`），**不进 MCP Server** | 放进 MCP 等于给外部客户端开"写任务"的口子，还要连带改 MCP.md/MCP_DESIGN.md 与审计；收益为零 |
+| draft 经前端灌进步骤编辑器 | 同上，但草稿**先落 `app_meta`**（`agent_task_draft`，只留最近一份） | 刷新/重进页面能拿回来；**不新建表**，绕开备份覆盖红线（SUMMARY_TABLES / DEPLOY §3.5） |
+| （未提） | designer 跑**不绑会话、不吃聊天历史**，且**不沉淀**经验/动作 | 探索轨迹里有试错与误点，沉淀会污染记忆库；"draft→经验"归到 P1 |
+| —— | 校验失败把 `errors` **原样回灌模型**，最多重提 3 次（提示词约束） | 这是"AI 写坏任务"的唯一闸门：`POST /api/jobs` 对 params 盲存、执行器又静默跳过错误步骤 |
+
+### 10.2 关键实现点
+
+- **校验器**：`core/task_draft.py`。`validate_draft()` 逐条复刻执行器的"静默跳过点"
+  （未知 type / 空 selector / 空 children / 嵌套 >5 / 深度节点数 >60 / cron 非法 /
+  必填 params 缺失 / `click_xy` 直接拒）→ 返回可被模型读懂的 `errors` + 不拦的 `warnings`。
+  `normalize_draft` 负责兜底（任务名、target、schedule、retry、时长）；页面上的任务设置
+  以 `overrides` 形式**优先**于模型给的。
+- **提示词**：`mcp_agent/agent.py` 的 `DESIGNER_SYSTEM_PROMPT`（16 条规则：先看再动、
+  定位优先级、禁坐标、禁序号型 XPath、**副作用动作只核对不真点**、时长语义映射、
+  随机化三件套、规模上限、收尾方式）。
+- **护栏**：单工具调用上限 40 次（`Agent.tool_call_limit`；总步数由 `max_steps` 兜底，
+  两个值都要**大于**正常重试次数，否则会把一轮探索截断在"改字段"上——实测踩过）；输出上限 8192（designer）；
+  `json.loads` 容错（草稿被截断时返回可读错误而不是整轮崩）。
+- **前端**：`static/admin/taskgen.js` + `#agent-sub-taskgen`（子 Tab 机制见
+  `static/admin/base.js` 的 `showSubTab`）。草稿预览能直接点「在步骤编辑器中打开」→
+  `openTaskModal(null, prefill)` 预填（用唯一 draftKey，避开 localStorage 旧草稿覆盖）。
+- **两个页面共用一个运行槽**：`GET /api/agent/run` 回 `mode`，两个前端各按 mode 决定
+  是否订阅 SSE；服务端用 `_Fanout` 给**每个订阅者一条自己的队列**（谁都不丢事件）。
+- **切 Tab 不丢回放**：`initTaskGen()` 每次进入子页都会 `tgRestore()`——已经在盯同一轮就
+  **不重复订阅**（否则服务端会把这一轮从头补发一遍，卡片成两份）；换了一轮/刚刷新过页面才清空
+  回放区重新订阅（`_Fanout` 的历史缓冲会把已发生的事件补回来）。跟随画面的 MJPEG 长连接
+  在切回来时重新拉一次（`tgRearmLive`），避免定格。
+- **落库出口**：页面上的「✓ 直接创建任务」（`POST /api/agent/task_draft/create`）与
+  「在步骤编辑器中核对」（预填编辑器 → 用户点保存）——两条路最终都汇到 `add_job`。
+
+### 10.3 附带修掉的两个 bug
+
+**(1) 事件被另一个页面抢走**（用户报的"探索完没法创建任务"的真因）：一轮的事件原先只有一个
+`queue.Queue`，聊天页与建任务页同时开着时，两个 EventSource **瓜分**同一条队列——建任务页的回放
+会卡在中间，`done` 事件被聊天页取走 → 永远等不到草稿 → 页面上没有可点的"创建"。
+现改为**扇出**（`web/agent_api.py` 的 `_Fanout`）：每个订阅者一个专属队列，多开页面各看各的；
+前端两侧也按 `mode` 门控，不互相订阅。
+
+**(2) 工具消息配对**
+
+Chat 模式同样受益：一轮里若模型同时调了 `de_screenshot` 与别的工具，旧实现会把截图图像
+作为一条 `user` 消息**插在两条 tool 消息之间**，模型侧判定"工具回应不足"直接 400
+（`An assistant message with 'tool_calls' must be followed by tool messages…`）。
+现改为：本轮 tool 消息发完后再附一条 user 图像消息；`_repair_tool_messages` 也改成
+只数**连续**的 tool 消息。
+
+### 10.4 后续批次（2026-09-14 已完成的三项）
+
+- ✅ **「直接创建」**：`POST /api/agent/task_draft/create` + 页面上的按钮与「探索完直接创建任务」
+  勾选框。两条设计约束：草稿体只存在于服务端（客户端只能传 overrides，少一个可篡改入口）；
+  创建前**再校验一次**，通过后走与「新建任务」完全相同的 `context.mgr.add_job`，
+  创建成功后清草稿（同一份草稿不会被重复建成多个任务）。
+- ✅ **草稿沉淀经验/动作**：designer 轮次也走 `_distill_experience` / `_distill_actions`
+  沉淀，但**只在草稿通过校验时**（说明这轮探索确实走通了一条路；没草稿的试错不入库）。
+- ✅ **MCP `de_snapshot`**：截图+元素树一次取齐（20 个 `de_*` 工具了），并把
+  `screen_state` 一并返回；designer/聊天两套提示词都改为**优先用 de_snapshot**。
+  见 [MCP.md](MCP.md) §4.2。
+
+### 10.5 仍未做
+
+- 多设备并行探索、探索成本/token 控制（一轮真机探索 3~30 万 token）。
+- 把**动作库**当 generic_steps 的预制件复用（设计稿 §9.2 的只读清单类 MCP 工具）。
+- 平台的 `/api/uiauto/snapshot` 目前只被 MCP 与抓取弹窗用，还可在 designer 里做"同屏缓存"。
+
+### 10.6 自测怎么跑
+
+1. 纯逻辑：`core/task_draft` 的正反例（未知 type / 空 selector / `click_xy` / cron 少段 /
+   深度 6 / probability 越界 …），断言 `errors` 文案模型能读懂。
+2. 真机：AI 控制台 →「AI 建任务」→ 选空闲设备 → 描述需求 → 看回放 → 核对草稿 →
+   「在步骤编辑器中打开」→ 单步试跑 → 保存。
+3. 反例：需求里出现"自动评论并发送" → 草稿的这类步骤应是"只核对存在性"（`notes` 里提示
+   人工复核），**探索期审计日志里不应有对发送键的 `de_tap_*`**。
+4. 自测产生的东西（草稿/自建任务）用后即删，别碰用户真实数据。

doc/API.md

@@ -21,9 +21,10 @@
 - [11. 运维工具（adb / 剪贴板 / 应用版本 / Tailscale）](#11-运维工具adb--剪贴板--应用版本--tailscale)
 - [12. AI 控制台](#12-ai-控制台)
 - [13. 系统备份](#13-系统备份)
-- [14. 非 JSON 响应汇总](#14-非-json-响应汇总)
+- [14. 设备端应用商店](#14-设备端应用商店)
-- [15. 错误分支速查](#15-错误分支速查)
+- [15. 非 JSON 响应汇总](#15-非-json-响应汇总)
-- [16. 已知问题](#16-已知问题)
+- [16. 错误分支速查](#16-错误分支速查)
+- [17. 已知问题](#17-已知问题)
 
 ---
 
@@ -48,14 +49,14 @@
 ### 1.3 CSRF
 
 - `GET /api/csrf` 取 token（存在 session）；前端对所有非 GET 请求带 `X-CSRF-Token`。
-- ⚠️ **当前服务端并未强制校验**（`web_server.py` 只 import 了 `_csrf_protect`，没有注册 `before_request`）。即 token 已签发、前端已携带，但**伪造请求不会被拦**。见 [§16 已知问题](#16-已知问题)。
+- ⚠️ **当前服务端并未强制校验**（`web_server.py` 只 import 了 `_csrf_protect`，没有注册 `before_request`）。即 token 已签发、前端已携带，但**伪造请求不会被拦**。见 [§17 已知问题](#17-已知问题)。
 
 ### 1.4 响应约定
 
 - 绝大多数接口返回 **JSON**：成功 `{"ok": true, ...}`，失败 `{"ok": false, "error": "中文原因"}`（部分接口额外带 `msg`）。
 - **HTTP 状态码与 `ok` 并存**：参数错误用 400，权限 403，不存在 404，冲突 409，依赖不可用 502/503。少数接口用 `{"ok":false}` + HTTP 200（如 `POST /api/jobs/<id>/run` 的"任务类型不存在"）。以本文每节标注为准。
 - 时间统一字符串：`"YYYY-MM-DD HH:MM"`（展示）或 `"YYYY-MM-DD HH:MM:SS"`（cron 相关）。
-- 非 JSON 接口（HTML / 图片 / SSE / MJPEG / zip）见 [§14](#14-非-json-响应汇总)。
+- 非 JSON 接口（HTML / 图片 / SSE / MJPEG / zip）见 [§15](#15-非-json-响应汇总)。
 
 ---
 
@@ -123,9 +124,14 @@
 | POST | `/api/custom_actions` | T | 新建自定义动作 |
 | PUT | `/api/custom_actions/<action_id>` | T | 更新自定义动作 |
 | DELETE | `/api/custom_actions/<action_id>` | T | 删除自定义动作 |
+| GET | `/api/step_defaults` | L | 步骤默认值（生效值 + 出厂值 + 字段规格，供「动作配置」页画表单） |
+| POST | `/api/step_defaults` | T | 保存步骤默认值（只落与出厂值不同的字段） |
+| POST | `/api/gesture/record/start` | D | 开始录制手势（手机端 getevent，返回 token） |
+| POST | `/api/gesture/record/stop` | D | 停止录制并取回轨迹 `gestures:[[[x,y,t_ms],…]]` |
 | GET | `/api/uiauto/status` | L | uiautodev 服务是否在跑 |
 | GET | `/api/uiauto/devices` | D | 抓元素可选设备 |
 | GET | `/api/uiauto/elements` | D | 设备 UI 元素树 |
+| GET | `/api/uiauto/snapshot` | D | **一次取齐**截图 + 元素树（原生 u2，抓取弹窗用） |
 | GET | `/api/uiauto/screenshot` | D | uiautodev 截图（JPEG） |
 | POST | `/api/steps/test` | D | 真机试执行单个步骤 |
 
@@ -137,7 +143,12 @@
 | POST | `/api/users` | Admin | 新建用户 |
 | PUT | `/api/users/<int:uid>` | Admin | 更新用户（改密/权限/管理员） |
 | DELETE | `/api/users/<int:uid>` | Admin | 删除用户 |
-| GET | `/api/logs` | G | 读日志文件尾部 N 行 |
+| GET | `/api/logs` | G | 读日志（关键字/级别/时间过滤，返回结构化行） |
+| GET | `/api/logs/download` | G | 下载日志（同样支持过滤；无过滤即整个文件） |
+| GET | `/api/step_logs` | G | 任务步骤明细（按设备/任务/结果/时间/关键字过滤，分页） |
+| GET | `/api/step_logs/runs` | G | 按 `run_id` 归组的一次运行概览（几步、失败几步） |
+| GET | `/api/step_logs/filters` | G | 步骤明细的筛选项（明细里出现过的设备/任务 + 结果枚举） |
+| GET | `/api/step_logs/download` | G | 导出步骤明细 CSV（带 UTF-8 BOM，Excel 直接打开） |
 
 ### 2.5 devices（`web/devices_api.py`）
 
@@ -150,6 +161,7 @@
 | POST | `/api/devices/pool/remove` | D | 从池中删除 |
 | POST | `/api/devices/pool/toggle` | D | 启用/停用（停用不参与调度） |
 | POST | `/api/devices/pool/reconnect` | D | 一键重连全部池内网络设备 |
+| GET | `/api/devices/qrcode?serial=` | D | 生成该设备的**配置二维码**（设备端 Agent 扫码即配好） |
 | POST | `/api/devices/pool/refresh_models` | D | 批量采集型号 |
 | GET | `/api/devices/discovery` | D | 发现状态 + 待连接 + 断联列表 |
 | POST | `/api/devices/discovery/scan` | D | 手动触发一轮扫描 |
@@ -195,8 +207,8 @@
 |------|------|------|
 | GET/POST | `/api/agent/config` | 读写 AI 配置（key 打码回显） |
 | GET | `/api/agent/devices` | AI 可用设备（含名称与 busy 标记） |
-| POST | `/api/agent/run` | 启动一轮 AI 会话 |
+| POST | `/api/agent/run` | 启动一轮 AI 会话（`mode:"chat"`=聊天 / `"designer"`=AI 建任务） |
-| GET | `/api/agent/run` | 运行状态（刷新恢复用） |
+| GET | `/api/agent/run` | 运行状态（刷新恢复用；含 `mode`/`draft`） |
 | GET | `/api/agent/stream` | **SSE 事件流** |
 | POST | `/api/agent/stop` | 中断当前运行 |
 | POST | `/api/agent/clear` | 清空对话历史 |
@@ -210,6 +222,22 @@
 | GET | `/api/agent/actions` | 动作库列表 |
 | POST | `/api/agent/actions/save` | 新增/编辑动作（禁坐标） |
 | POST | `/api/agent/actions/delete` | 删除动作 |
+| GET | `/api/agent/task_draft` | **AI 建任务**：读回最近一份草稿（`{saved, running, mode, run_id, draft, draft_error}`） |
+| POST | `/api/agent/task_draft` | 回存草稿并**重新校验**（不通过返回 400 + `errors`） |
+| POST | `/api/agent/task_draft/create` | **直接创建**：取暂存草稿 → 再校验 → `add_job` → 清草稿（body 可带 `{serial, overrides}`；草稿体不接受客户端提交） |
+| POST | `/api/agent/task_draft/clear` | 丢弃草稿 |
+
+**AI 建任务（designer 模式）要点**（详见 [AI_TASK_GEN.md](AI_TASK_GEN.md)）：
+
+- `POST /api/agent/run` 额外接受 `mode:"designer"` 与 `settings`（页面上的任务设置，作为草稿
+  的 overrides：`name`/`target_mode`/`group_name`/`serial`/`schedule`/`max_duration`）。
+  designer 跑**不绑会话**（单轮，不吃聊天历史、也不污染会话）。
+- designer 模式下 Agent 多一个**平台级本地工具** `submit_task(draft)`（**不在 MCP 层**）：
+  服务端用 `core/task_draft.validate_draft` 校验，失败把 `errors` 回灌给模型让它改；
+  通过也只**暂存**（运行态 + `app_meta.agent_task_draft`），**不落库**——入库仍要用户在
+  步骤编辑器里确认后走 `POST /api/jobs`。
+- `done` 事件在 designer 下多带 `{mode, draft, warnings, draft_error}`。
+- 设备忙 409、单实例运行、权限同聊天模式。
 
 ### 2.10 system（`web/system_api.py`，全部 Admin）
 
@@ -219,6 +247,43 @@
 | POST | `/api/system/backup/preview` | 上传备份校验预览（multipart，字段 `file`） |
 | POST | `/api/system/backup/apply` | 应用恢复（重启生效） |
 
+### 2.11 notify（`web/notify_api.py`，全部 Admin）
+
+通知 / Webhook 配置与发送记录（事件目录、推送格式、限流语义见 [NOTIFY.md](NOTIFY.md)）：
+
+| 方法 | 路径 | 功能 |
+|------|------|------|
+| GET | `/api/notify/webhooks` | 全部 webhook（`url` 打码、`secret` 只回 `secret_set`）+ 格式清单 |
+| POST | `/api/notify/webhooks` | 新建（body 见 NOTIFY.md §4） |
+| PUT | `/api/notify/webhooks/<id>` | 更新（`url`/`secret` 省略或为打码值 → **保持原值**） |
+| DELETE | `/api/notify/webhooks/<id>` | 删除 |
+| POST | `/api/notify/webhooks/<id>/test` | **同步**发一条测试消息（不占业务令牌桶，单独限 10 次/分） |
+| POST | `/api/notify/preview` | 预览真实请求体 + UTF-8 字节数 + 是否截断 |
+| GET | `/api/notify/events` | 事件目录（含字段清单） |
+| GET | `/api/notify/logs?limit=` | 最近发送记录（内存 200 条，重启清空） |
+| POST | `/api/notify/settings` | 全局开关与默认聚合/限流 |
+
+### 2.12 device_agent（`web/device_agent_api.py`）
+
+**设备端专用**（无登录会话，靠 `X-Device-Token` 鉴权；平台未启用时统一 404）：
+
+| 方法 | 路径 | 功能 |
+|------|------|------|
+| GET | `/api/device/agent/bootstrap` | 设备拉自己的身份 + 可安装应用清单 |
+| GET | `/api/device/agent/apk/<apk_id>` | 下载 APK 文件 |
+| POST | `/api/device/agent/report` | 上报下载/安装结果 |
+
+**管理端**（登录 + 应用管理权限）：
+
+| 方法 | 路径 | 功能 |
+|------|------|------|
+| GET | `/api/agent-store/config` | 读配置（含设备令牌） |
+| POST | `/api/agent-store/config` | 启用/停用、重置令牌 |
+| GET | `/api/agent-store/logs` | 设备端安装记录 |
+| POST | `/api/agent/show-info` | 让设备上的 Agent 显示/关闭**身份大字页**（监控页「打开设备端 Agent」按钮）|
+
+> 完整协议、鉴权与版本约定见 [DEVICE_AGENT.md](DEVICE_AGENT.md)。
+
 ---
 
 ## 3. 认证与页面
@@ -281,7 +346,7 @@
 | `POST /api/stop_all` | — | 停止全部 |
 | `POST /api/device/clear_error` | `{"serial":"…"}` | 运行中/重试等待中拒绝清理 |
 | `POST /api/device/clear_all_errors` | — | 跳过 running/connecting |
-| `POST /api/device/screen_all` | `{"mode":"on"\|"off", "serials":[…]}` | 不传 serials 则对全部在线设备 |
+| `POST /api/device/screen_all` | `{"mode":"on"\|"off", "serials":[…]}` | 不传 serials 则对全部在线设备。**熄屏是单向的**（`KEYCODE_SLEEP`），不会把已息屏的设备唤醒；亮屏用 `KEYCODE_WAKEUP` + `dismiss-keyguard` |
 | `POST /api/scan_foreground` | — | 已扫描中时返回 `{"ok":false}`（**HTTP 200**） |
 | `POST /api/device/locate` | `{"serial":"…","show":true}` | `show=true` 时在设备上打开 `/locate` |
 | `POST /api/device/locate/stop` | `{"serial":"…"}` | 结束定位 |
@@ -441,8 +506,31 @@
 | 任务编辑器「指定设备」下拉 | `名称 · serial` |
 | 分组编辑的设备勾选列表 | `名称 · serial` |
 | 设备池 / 待连接池 / 断联设备表 | 名称列 + 指纹列 |
+| 剪贴板注入的设备勾选列表 | `名称 · serial`（无名只显示地址） |
+| 应用管理的安装弹窗设备列表 | `名称 · serial` |
+| 应用版本管理表格的「设备」列 | `名称 · serial` |
+| 应用安装进度表的「设备」列 | 名称（取自设备池；无名退地址） |
 | MCP `de_list_devices` | 返回 `name` 字段，提示 AI 汇报时用名称 |
 
+> 这几个接口的字段来源：`/api/adb/devices`、`/api/apks/install/devices` 走
+> `web/common.py:_merged_device_list()`（带 `name`）；`/api/tools/appver` 把
+> `name` 塞进每个设备的结果里。
+
+### 6.2.2 设备配置二维码（扫码配置）
+
+| 接口 | 鉴权 | 请求 | 说明 |
+|------|------|------|------|
+| `GET /api/devices/qrcode?serial=<地址>` | 设备权限 | — | 返回 `{png(base64 data-url), payload, warn}` |
+
+给设备端 Agent 扫的配置二维码，一次写入**平台地址 + 设备令牌 + 该设备指纹**：
+
+- `payload` 是二维码里的原始 JSON：`{"v":1,"server":…,"token":…,"fingerprint":…,"name":…}`
+- `warn` **非空时必须显示**给操作者，最常见两种：
+  - "你是用 localhost 打开平台的" → 二维码里的地址手机会连不上，要改用局域网地址重开本页
+  - "这台设备还没采集到指纹" → 扫码后平台认不出它是哪一台
+- 前置条件：先在「应用管理 → 设备端应用商店」**启用**（令牌从那儿来），否则 400
+- 设备端如何解析见 [DEVICE_AGENT.md](DEVICE_AGENT.md) §5.3
+
 ### 6.3 自动发现
 
 | 接口 | 请求 | 说明 |
@@ -480,10 +568,20 @@
 |------|------|---------|
 | `GET /api/uiauto/status` | — | uiautodev（:20242）是否在跑，前端据此禁/启用"抓取元素" |
 | `GET /api/uiauto/devices` | — | 可选设备列表（uiautodev 设备 + 池内在线补全） |
-| `GET /api/uiauto/elements?serial=` | — | 扁平元素列表，每项带 `suggested`（推荐选择器）、`bounds`、`depth` |
+| `GET /api/uiauto/elements?serial=` | — | 扁平元素列表（走 uiautodev），每项带 `suggested`、`bounds`、`depth` |
+| `GET /api/uiauto/snapshot?serial=` | — | **一次取齐**：截图 + 元素树（原生 u2 同一连接背靠背）→ `{image,width,height,elements,unstable,screen_state,cost_ms}`；抓取弹窗与 MCP 的 `de_snapshot` 都用它，失败返回 **502** |
 | `GET /api/uiauto/screenshot?serial=` | — | JPEG |
 | `POST /api/steps/test` | `{"serial","step":{…}}` | 真机试执行单个步骤 → `命中 / 未找到 / 已执行` |
 
+**`suggested`（推荐选择器）字段**：`{type, value, semantic?, via?, indexed?, occ?, total?, broad?, invalid?, reason?}`
+
+| 字段 | 含义 |
+|------|------|
+| `semantic` + `via` | **语义选择器**：`//*[@id="x" and @text="y"]`，`via` 是用于限定的第二属性（`text`/`content-desc`/`class` 或 `a+b`）——不依赖同类元素个数，换设备/换版本仍命中 |
+| `indexed` + `occ`/`total` | 退化形式 `(//*[@id="x"])[k]`：同 id 且同文字分不开时才用，**界面一变即失配**，前端黄标提醒 |
+| `broad` | 结构路径兜底（`//hierarchy/*[i]/*[j]`），最脆 |
+| `invalid` + `reason` | 无任何可用属性，前端禁止回填 |
+
 `GET /api/uiauto/elements` 在 uiautodev 不可用时返回 **503**。设备 dump 慢时可能超时（见 [backlog](backlog/TODO.md)）。
 
 ---
@@ -497,7 +595,24 @@
 | `DELETE /api/apks/<apk_id>` | — | 删文件 + 记录 |
 | `POST /api/apks/install` | `{"apk_id","serials":[…]}` | 后台并发 5 台安装；已在装 → 失败提示 |
 | `GET /api/apks/install/devices` | — | 可安装设备（pool / usb / adb 三个来源） |
-| `GET /api/apks/install/status` | — | 安装进度（前端 3s 轮询） |
+| `GET /api/apks/install/status` | — | 安装进度（前端 1.5s 轮询） |
+
+> 每台设备的状态机：`pending`（等待）→ `installing`（**带文字的实时进度**）→ `success` / `failed` / `skipped`。
+> 安装分两段，`items[serial].msg` 会跟着更新：
+> 1. **推送到设备**：`推送中 62%（211.0/336.1 MB · 2.6 MB/s · 剩约 48s）` —— 用分块写
+>    （`adb exec-in`）拿字节级进度；不用 `adb push` 是因为它只在结束时吐一行汇总，
+>    大包（抖音 336MB≈2 分钟）整个传输过程界面上只能干等
+>    ⚠️ **`adb exec-in` 返回 ≠ 设备上写完**：数据还在设备侧（adbd → shell → `cat >`）缓冲里
+>    继续落盘。所以收尾必须**轮询文件大小直到长齐**（`_wait_remote_size`，最长 20s），
+>    量一次就判"推送不完整"会把成功的传输误报成失败（2026-09-14 的真实案例：同一份
+>    5.9MB 的 APK 在多台设备上报了 8 次假失败，实际文件最终都是完整的）。真不齐才退回
+>    `adb push` 重传。
+
+> 2. **设备上安装**：`正在设备上安装...（大包要 1-2 分钟，无进度可读）` —— `pm install`
+>    在设备端解包，系统没给进度接口
+>
+> 参考耗时（336MB 抖音 / 单台）：推送 ~134s + 安装 ~65s ≈ 3.3 分钟；多台并发（上限 5）时
+> 带宽共享，整体时间取决于 WiFi。
 
 ---
 
@@ -509,7 +624,59 @@
 | `POST /api/users` | Admin | `{"username","password","is_admin"?,"perms"?}` | 用户名/密码空、重名 → 400 |
 | `PUT /api/users/<int:uid>` | Admin | `{"password"?,"is_admin"?,"perms"?}` | 取消最后一个管理员 → 400；不存在 404 |
 | `DELETE /api/users/<int:uid>` | Admin | — | 删 `admin`/删自己/删最后一个管理员 → 400 |
-| `GET /api/logs?file=core.log&lines=300` | G | — | 返回日志尾部 + 可选文件清单 |
+| `GET /api/logs?file=core.log&lines=300` | G | `q` 关键字、`level` 最低级别、`since`/`until` 时间 | 见下 §10.1 |
+| `GET /api/logs/download?file=core.log` | G | 同上（参数一致） | 以附件返回 `.txt`，文件名带时间戳 |
+
+#### 10.1 日志查询（`GET /api/logs`）
+
+参数：
+
+| 参数 | 说明 |
+|------|------|
+| `file` | 日志文件名，**白名单校验**（只能取接口返回的 `files[].name`，含 `.1/.2` 滚动历史）；非法值返回 `ok:false` |
+| `lines` | 返回**最近**多少条命中（默认 300，上限 5000） |
+| `q` | 关键字，大小写不敏感，匹配整行原文 |
+| `level` | 最低级别：`ERROR` / `WARNING` / `INFO` / `DEBUG`（含以上）；留空为全部 |
+| `since` / `until` | 时间范围，接受 `YYYY-MM-DDTHH:MM`（datetime-local）或 `YYYY-MM-DD`（按整天） |
+
+返回：
+
+```json
+{"ok": true, "file": "core.log",
+ "files": [{"name": "core.log", "label": "核心(adb/调度) · core.log",
+            "size": 1175910, "mtime": 1789519242, "rotated": false}],
+ "rows": [{"ts": "2026-09-16 08:26:50", "level": "INFO",
+           "module": "core.disc", "msg": "发现: …", "cont": false}],
+ "matched": 11423, "scanned": 11423, "truncated": true}
+```
+
+- `rows` 保持文件原顺序（旧→新），即"最近 N 条命中"按时间正序排列；
+- `cont=true` 是**续行**（traceback 的缩进行等）：它本身没有时间/级别前缀，
+  过滤时**继承上一条带前缀的行**，所以按 ERROR 筛选不会把堆栈拆散；
+- `matched` 是命中总数，`truncated=true` 表示更早的命中没返回（应缩小时间范围或加关键字）；
+- `scanned` 是实际扫描行数（上限 50 万行）。
+
+#### 10.2 任务步骤明细（`/api/step_logs*`）
+
+数据源是 `task_step_log` 表（**结构化**，与上面的文本日志不是一回事）：每一次步骤
+执行一条，能按设备/任务/结果/时间过滤、能按运行归组、能导出 CSV。写入侧见
+[DATA_MODEL.md](DATA_MODEL.md) §2.8 与 `core/step_log.py`。
+
+| 接口 | 参数 | 返回 |
+|------|------|------|
+| `GET /api/step_logs` | `serial` `job_id` `result` `run_id` `q` `since` `until` `limit`(≤2000，默认 200) `offset` | `rows`（**最近的在前**）、`total`、`stats`（本次进程的 queued/written/dropped/failed）、`keep_days`、`max_rows_per_run` |
+| `GET /api/step_logs/runs` | `serial` `job_id` `since` `until` `limit`(≤500) | `runs[]`：`run_id` `started_at` `ended_at` `steps` `failures` |
+| `GET /api/step_logs/filters` | — | `devices[]` / `jobs[]`（**只列明细里真的出现过的**，不依赖设备池与任务表）、`results[]` |
+| `GET /api/step_logs/download` | 同列表接口 | 附件 `.csv`（UTF-8 **带 BOM**），最多 2 万行，按时间正序 |
+
+`result` 取值：`ok` / `miss`（handler 返回 False，如元素没找到）/ `error`（抛异常）/
+`unknown`（未知步骤类型）/ `skip`（概率未触发）/ `cap`（本次运行已达记录上限）。
+
+`run_id` 是"设备 × 任务 × 第几次尝试"，同一行里能拿到 `step_path`（如 `2.1.3`）
+还原嵌套结构——**步骤明细面板的「最近运行概览 → 查看」就是按它过滤**。
+
+> 稳定性：记录走异步队列（`record()` 零阻塞），**队列满会丢弃**（计数在 `stats.dropped`，
+> 页面提示栏会显示），所以明细允许缺条 —— 权威结论仍看任务状态与 [NOTIFY.md](NOTIFY.md) 的事件。
 
 ---
 
@@ -610,45 +777,91 @@
 
 ### POST /api/system/backup/export
 
-**JSON body**（不是表单）：`{"include_apks": false}`。响应为 **zip 附件**：
+**JSON body**（不是表单）：`{"include_apk": true}`（默认 true）。响应为 **zip 附件**：
 
 ```
-users.db           # sqlite 在线备份 API 做的一致快照
+users.db           # 当前库（MySQL 或回退 SQLite）整库一致快照成的 SQLite 归档
-apks/*.apk         # include_apks=true 时
+apks/*.apk         # include_apk=true 时
-manifest.json      # {format:"auto_control_backup", version, created_at, schema_version,
+manifest.json      # {format:"auto_control_backup", version:2, created_at, schema_version,
-                   #  include_apk, tables:[{table,label,rows}], apks:[…], coverage_missing?}
+                   #  db_backend, deployment_env, source_db_id, include_apk,
+                   #  tables:[{table,label,rows}], apks:[…], coverage_missing?}
 ```
 
+> SQLite 在这里是**备份交换格式**而非运行时库：MySQL 下导出时把连接提到 REPEATABLE READ，
+> 保证 12 张表读的是同一时刻。
+
 ### POST /api/system/backup/preview
 
 multipart 上传 `.zip` 或 `.db`（字段 `file`）→ 校验并暂存：
 
 ```json
 {"ok": true, "token": "e172dc75e2f7",
- "preview": {"integrity": "ok", "schema_version": 4, "current_schema_version": 4,
+ "preview": {"integrity": "ok", "schema_version": 6, "current_schema_version": 6,
-             "tables": [{"table":"agent_action","label":"动作库","rows":4}],
+             "source_env": "dev", "current_env": "dev", "source_backend": "mysql",
+             "source_db_id": "704fbbb0…",
+             "tables": [{"table":"agent_action","label":"动作库","rows":5}],
              "missing_optional": [], "extra_tables": [],
-             "warnings": ["备份为全量快照，含用户口令哈希、AI 控制台 API Key 等敏感信息…"]}}
+             "warnings": ["备份为全量数据，含用户口令哈希、AI 配置里的 API Key 等敏感信息…"]}}
 ```
 
 - 完整性 `PRAGMA integrity_check` 必须 `ok`；缺必需表（`app_meta`/`user`/`task_job`/`device_group`）直接拒绝
-- `extra_tables` 非空 = 备份含**未登记进覆盖清单**的表（提示去登记）
+- `extra_tables` 非空 = 备份含**未登记的表**（提示去登记）
+- `source_env` ≠ `current_env` 时 `warnings` 会多一条跨环境告警
 - 暂存 **TTL 30 分钟**，过期自动清理
 - 文件非法 / 未选文件 → 400
 
 ### POST /api/system/backup/apply
 
-`{"token":"…"}` → 先自动把当前库快照到 `data/backups/pre_restore_<ts>.db`（安全网），再把暂存库落到 `data/restore_pending/`。
+`{"token":"…", "force_env_mismatch": false}` → 先自动把当前库导出成
+`data/backups/pre_restore_<ts>.zip`（安全网，可直接再导入回来），再把暂存归档落到
+`data/restore_pending/`。
 
-**必须重启服务才生效**（`web_server.py` 在 `init_db` 之前消费该目录）。token 无效/暂存缺失 → 400。
+- **必须重启服务才生效**：`web_server.py` 在 `init_db` 之后、`TaskManager` 之前消费该目录
+- 重启时**单事务整库替换**（DELETE 全表 + 分块 INSERT），失败自动回滚，当前数据不受影响
+- 备份来源环境与当前库不符时**默认拒绝**（400），要跨环境须显式传 `force_env_mismatch: true`
+- token 无效/暂存缺失 → 400
 
 ---
 
-## 14. 非 JSON 响应汇总
+## 14. 设备端应用商店
+
+**设备侧**三个接口（`bootstrap` / `apk` / `report`）的完整协议、鉴权、错误码与版本约定
+见 [DEVICE_AGENT.md](DEVICE_AGENT.md)——那份文档同时是设备端 APK 仓库的对接契约。
+
+**管理侧**（登录 + 应用管理权限）：
+
+### GET /api/agent-store/config
+
+```json
+{"ok": true, "enabled": false, "token": "…", "token_created_at": "2026-09-13 14:38:11",
+ "api_version": 1, "base_url_hint": "http://192.168.20.220:18050"}
+```
+
+`base_url_hint` 由请求的 Host 回填，直接可作为设备端要填的平台地址。
+
+### POST /api/agent-store/config
+
+`{"enabled": true}` 启用（并自动生成令牌）；`{"regenerate_token": true}` 重置令牌
+（旧令牌立即失效）。返回 `{"ok": true, "enabled": …, "token": …}`。
+
+### GET /api/agent-store/logs?limit=50
+
+```json
+{"ok": true, "logs": [{"id": 1, "device_name": "A08", "serial": "192.168.20.100:5555",
+  "fingerprint": "…", "apk_id": "56b114aa", "package_name": "com.example.clipinject",
+  "version_name": "1.0", "action": "install_fail", "message": "MIUI 拦截未确认",
+  "created_at": "2026-09-13 14:40:00"}]}
+```
+
+`action` ∈ `download` / `install_ok` / `install_fail`；记录表最多保留 500 条（自动裁旧）。
+
+---
+
+## 15. 非 JSON 响应汇总
 
 | 方法 | 路径 | 响应类型 | 说明 |
 |------|------|---------|------|
-| GET | `/` `/wall` `/login` `/locate` | `text/html` | 四个页面（`/locate` 免登录） |
+| GET | `/` `/wall` `/login` `/locate` | `text/html` | 四个页面（`/locate` 免登录；**已被设备端 Agent 的身份页取代**，仅作历史保留）|
 | GET | `/api/device/screenshot` | `image/png` | 原始截图（`Cache-Control: no-store`） |
 | GET | `/api/screen/thumb` | `image/jpeg` | 360px 缩略图 + `X-Screen-State` |
 | GET | `/api/screen/stream` | `multipart/x-mixed-replace` | MJPEG 实时流 |
@@ -658,7 +871,7 @@ multipart 上传 `.zip` 或 `.db`（字段 `file`）→ 校验并暂存：
 
 ---
 
-## 15. 错误分支速查
+## 16. 错误分支速查
 
 | 码 | 典型触发 |
 |----|---------|
@@ -674,7 +887,7 @@ multipart 上传 `.zip` 或 `.db`（字段 `file`）→ 校验并暂存：
 
 ---
 
-## 16. 已知问题
+## 17. 已知问题
 
 | 问题 | 影响 | 位置 |
 |------|------|------|

doc/ARCHITECTURE.md

@@ -30,6 +30,8 @@
                             │
 ┌───────────────────────────▼──────────────────────────────────────────┐
 │ 基础层   adb_helper · u2_helper · uiauto_helper · ocr · clipboard      │
+│          notifier（通知分发：队列/聚合/限流/适配器）                      │
+│          step_log（步骤明细：队列 + 批量落库 + 保留期清理）               │
 │          models（SQLite）· logger · config                             │
 └──────────────────────────────────────────────────────────────────────┘
                             ▲
@@ -39,7 +41,7 @@
                             ▲                       ▲
 ┌───────────────────────────┴────────┐  ┌───────────┴──────────────────┐
 │ MCP Server（mcp_server/，:8033）    │  │ AI Agent（mcp_agent/）        │
-│ 19 个 de_* 工具，供外部 AI 调用      │  │ OpenAI 兼容模型 → MCP 工具     │
+│ 20 个 de_* 工具，供外部 AI 调用      │  │ OpenAI 兼容模型 → MCP 工具     │
 └────────────────────────────────────┘  └──────────────────────────────┘
 ```
 
@@ -75,17 +77,17 @@
 
 | 阶段 | 位置 | 做了什么 |
 |------|------|---------|
-| **B** | `:28-41` | `Flask(__name__)`；会话密钥（`.env` 的 `WEB_SECRET_KEY`，缺失则随机生成并 warning）；`TEMPLATES_AUTO_RELOAD=True`；`SQLALCHEMY_DATABASE_URI=sqlite:///data/users.db`；`LoginManager` + `login_view="auth.login"` |
+| **B** | `:28-58` | `Flask(__name__)`；会话密钥（`.env` 的 `WEB_SECRET_KEY`，缺失则随机生成并 warning）；`TEMPLATES_AUTO_RELOAD=True`；**数据库目标由 `core/db_config` 装配**（`.env` 的 `DEPLOY_ENV`/`DB_*` → URI + 引擎参数），配置错直接 `SystemExit(2)`；`LoginManager` + `login_view="auth.login"` |
-| **C** | `:43-50` | **恢复任务消费** `consume_pending_restore()` —— 必须在 engine 首次打开 `users.db` **之前**（Windows 无法替换被持有的文件）。失败只记日志，不阻塞启动 |
+| **C** | `:60-67` | **恢复任务消费** `consume_pending_restore()`。SQLite 时代它必须在 engine 首次打开 `users.db` **之前**（Windows 无法替换被持有的文件）；改用 MySQL 后这一步的语义会变成"启动期事务替换"，见 §7 |
-| **D** | `:53-61` | `init_db(app)`（建表 → 版本化迁移 → 默认管理员 → 旧 JSON 迁移）；`device_pool.init_app`（**起一次性线程**，3s 后采集型号）；`device_discovery.init_app`（**起常驻扫描线程**）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)` |
+| **D** | `:69-88` | `init_db(app)`（建表 → 补列 → 版本账本 → 唯一索引 → 默认管理员 → 旧 JSON 迁移）→ `notifier.init_app`（通知 dispatcher/sender 线程）与 `step_log.init_app`（步骤明细写线程）→ **恢复任务消费** `consume_pending_restore()` → **库环境标签校验 + 启动横幅**（`db_config.verify_deployment_label/print_banner`，不符拒绝启动）；`device_pool.init_app`（**起一次性线程**，3s 后采集型号）；`device_discovery.init_app`（**起常驻扫描线程**）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)` |
 
 ### 2.3 阶段 E~G：蓝图、巡检调度器、真正启动
 
 | 阶段 | 位置 | 做了什么 |
 |------|------|---------|
 | **E** | `:64-67` | `context.init(...)`；`register_blueprints(app)`（10 个蓝图）；`agent_api.set_app(app)`（供后台线程推 app context） |
-| **F** | `:71-80` | **第二个独立 APScheduler**：`CronTrigger(hour=3, minute=47)` 挂经验库巡检；失败仅 warning |
+| **F** | 同上附近 | **第二个独立 APScheduler**：`CronTrigger(hour=3, minute=47)` 挂经验库巡检、`hour=4, minute=13` 挂步骤明细清理（`_purge_step_log`，自建 app context）；失败仅 warning |
-| **G** | `:253-265`（`__main__`） | `_ensure_uiauto_running()`（拉起 uiautodev:20242，写 `data/uiauto.pid`，`atexit` 清理）→ `_preconnect_pool_devices()`（后台并发 connect 池内网络设备）→ `_run_server()`（候选端口依次 bind：`0.0.0.0:18050` → `127.0.0.1:18050` → `127.0.0.1:18051..18055`）；退出时 `mgr.shutdown()` + `device_discovery.shutdown()` + 停 uiautodev |
+| **G** | `__main__` | `_ensure_uiauto_running()`（拉起 uiautodev:20242，写 `data/uiauto.pid`，`atexit` 清理）→ `_preconnect_pool_devices()`（后台并发 connect 池内网络设备）→ `_purge_step_log_async()`（后台清理超期步骤明细）→ `_run_server()`（候选端口依次 bind：`0.0.0.0:18050` → `127.0.0.1:18050` → `127.0.0.1:18051..18055`）；退出时 `notifier.shutdown()` + `step_log.shutdown()` + `mgr.shutdown()` + `device_discovery.shutdown()` + 停 uiautodev |
 
 > ⚠️ **阶段 A~F 在 import 期就会起线程/调度器**，只有 uiautodev 拉起与预连接在 `__main__` 分支。以 WSGI 方式 import 本模块会得到"半个启动"的进程——本地调试请直接 `python web_server.py`。
 
@@ -109,6 +111,9 @@
 | `apk-install` | `ApkManager.install` | 并发 5 台安装 APK | 安装期，全局单任务 |
 | Agent 执行线程 | `web/agent_api.py` | AI 控制台一轮会话 | 按需 |
 | 巡检手动线程 | `web/agent_api.py` | 手动触发巡检 | 按需 |
+| **通知 dispatcher** | `core/notifier.init_app` | 通知聚合 + 每 hook 限流 + 折叠摘要 | 常驻 1 个 |
+| **通知 sender ×3** | 同上 | 真实发 webhook（退避重试、环形记录） | 常驻 3 个 |
+| **步骤明细写线程** | `core/step_log.init_app` | 批量落库 `task_step_log`（队列满丢弃并计数） | 常驻 1 个 |
 
 两个 APScheduler 相互独立，时区均固定 `Asia/Shanghai`。
 
@@ -123,7 +128,7 @@
 | `_scan_lock` / `_stop_event` | `core/device_discovery.py` | 定时/手动扫描互斥 | `acquire(blocking=False)` |
 | `_status_cache_lock` | `core/task_manager.py` | 状态缓存（TTL 5s） | 避免 `/api/status` 每次都查库 + adb |
 
-**无锁部分**：`device_pool` 与 `models` 不持显式锁，依赖"每次操作独立 app context + SQLite WAL + `busy_timeout=5000`"。
+**无锁部分**：`device_pool` 与 `models` 不持显式锁，依赖"每次操作独立 app context" + 数据库自身的并发控制（MySQL 下是 InnoDB 行锁 + READ COMMITTED，回退 SQLite 时是 WAL + `busy_timeout=5000`）。
 
 ### 3.3 错峰与心跳
 
@@ -294,7 +299,8 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
 | `tools.js` | 工具 Tab：剪贴板、adb 终端、Tailscale、设备池、自动发现、远程看屏 | |
 | `apps.js` | 应用管理：APK 上传/安装/删除、设备已装应用 | |
 | `admin.js` | 分组、日志、用户 + **全局初始化入口**（末尾 `initCsrf(); loadMe(); showTab('monitor')`） | |
-| `agent.js` | AI 控制台：会话、SSE 流、Markdown / 推理链 / token 渲染、实时画面、经验库 / 动作库 | |
+| `agent.js` | AI 控制台·聊天：会话、SSE 流、Markdown / 推理链 / token 渲染、实时画面、经验库 / 动作库 | |
+| `taskgen.js` | AI 控制台·**AI 建任务**子页：发起探索、回放工具卡、草稿预览（步骤树/提醒/证据）、打开步骤编辑器预填 | 运行槽与聊天共用，按 `mode` 互斥订阅事件流 |
 | `system.js` | 系统 Tab：备份导出 / 导入预览与应用 | |
 
 加载顺序见根 [README](../README.md)；都是全局脚本（非 ES module），靠加载顺序保证依赖。
@@ -319,14 +325,14 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
 
 | 决策 | 为什么 | 代价 / 注意 |
 |------|--------|------------|
-| **SQLite + WAL** 而非 MySQL/PG | 单机部署、零运维；WAL 支持多线程读写 | 写并发有限；必须设 `busy_timeout`；`data/` 不入 git |
+| **数据库走 MySQL，SQLite 仅作回退** | 多环境（dev 库 / 正式库）需要同一套代码指向不同库；备份/恢复也不再受"文件被占用"掣肘 | 多一套连接配置与防混库校验（`core/db_config.py`）；`DB_HOST` 为空时回退 SQLite，生产禁止静默回退 |
 | **threading 而非 asyncio** | uiautomator2 是同步阻塞库；每设备一线程模型直观 | 线程数随设备数增长；跨线程访问 DB 必须自推 app context |
 | **状态放内存** 而非落库 | 状态每秒都变，落库纯属浪费 | 重启丢失运行中状态（进程重启 = 任务终止） |
 | **蓝图按功能域拆包** | `web_server.py` 只做装配，路由就近维护 | 拆包易出现 import 遗漏 → 用 `scripts/regression_test.py` 兜底 |
 | **单页应用 + 全局脚本** | 无构建步骤、无 npm 依赖，改完强刷即生效 | 11 个文件共享全局作用域，需手工维护加载顺序 |
 | **任务类型注册表** | 新增任务类型不动调度器 | 删改类型要做兼容（未知类型必须显式报错，不能静默） |
 | **自建设备池**（不用 STF） | 规避共享 adb transport 的历史坑，清单可控 | 需自己处理在线状态、型号、自动发现 |
-| **备份"重启生效"** | Windows 无法替换被持有的 db；调度器/worker 持有内存态 | 导入后必须重启（在 `init_db` 之前消费恢复任务） |
+| **备份"重启生效"** | 调度器 / worker / 设备池都把任务与设备**缓存在内存**里，整库替换后内存副本全部失效 | 导入后必须重启（重启时消费恢复任务）。SQLite 时代还有"Windows 无法替换被持有的文件"这层原因，改用 MySQL 后只剩内存态这一层 |
 | **uiautodev 独立子进程** | 元素抓取是重活，隔离崩溃、可单独重启 | 固定端口 20242；PID 文件防重复拉起（杀之前必须校验 cmdline，防误杀同容器进程） |
 | **MCP 独立端口** | 外部 AI 用标准协议接入，不侵入 Web 会话 | MCP 端点自身无鉴权，靠网络隔离；写操作用开关门控 |
 
@@ -390,5 +396,7 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
 | 加一张表 | `core/models.py` 模型 + `SCHEMA_MIGRATIONS`（老库） | **登记进备份覆盖清单** + [DATA_MODEL.md](DATA_MODEL.md)（红线） |
 | 加一个常驻线程 | 参考 `device_discovery` 的 `init_app` / `shutdown` 模式 | 更新本文 §3 与 [DEVELOPMENT.md](DEVELOPMENT.md) |
 | 加一个前端模块 | `static/admin/<name>.js` + 在 `monitor.html` 按序引入 | 更新本文 §6 与 [DEVELOPMENT.md](DEVELOPMENT.md) |
+| **加一个通知事件** | `core/notify_events.py` 的 `EVENTS` 加一条 + 触发点调 `notifier.notify(key, **fields)` | 事件目录要做全、默认不启用；**notify 必须放在锁外**（见 [NOTIFY.md](NOTIFY.md) §7） |
+| 加一种通知格式 | `core/notifier.py` 的 `ADAPTERS` 注册一个 `BaseAdapter` 子类 | 补字节上限/默认限流；更新 [NOTIFY.md](NOTIFY.md) §5 |
 | 加一个 MCP 工具 | `mcp_server/mcp_server.py`（需要时加 `direct_ops.py`） | 写操作要挂门控三连；更新 [MCP.md](MCP.md) |
 | 加一个配置键 | `config.py`（程序级）或 `.env`（密钥类） | 更新 `.env.example` + [DEVELOPMENT.md](DEVELOPMENT.md) 配置速查 |

doc/DATA_MODEL.md

@@ -2,7 +2,7 @@
 
 > 适用读者：改后端 / 排数据问题的开发者与运维。
 > 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)（运行时架构）、[DEPLOY.md](DEPLOY.md) §数据备份（备份覆盖红线）、[API.md](API.md)（消费这些数据的接口）。
-> **表结构以 `core/models.py` 与各模块的建表 SQL 为准**，本文是它们的映射说明。
+> **表结构以 `core/models.py` 的 ORM 模型为唯一准**（2026-09-13 起各模块的裸建表 SQL 已全部并入模型），本文是它们的映射说明。
 
 ---
 
@@ -10,32 +10,51 @@
 
 | 项 | 值 |
 |----|----|
-| 引擎 | SQLite（单文件 `data/users.db`） |
+| 引擎 | MySQL（正式用法；目标由 `.env` 的 `DEPLOY_ENV` + `DB_*` 决定）／SQLite（回退模式，`DB_HOST` 为空时） |
-| driver | Flask-SQLAlchemy（SQLAlchemy 2.x） |
+| driver | Flask-SQLAlchemy（SQLAlchemy 2.x）+ PyMySQL |
-| 连接 PRAGMA | `journal_mode=WAL`、`busy_timeout=5000`、`synchronous=NORMAL` |
+| 连接参数 | 见 `core/db_config.py`：utf8mb4、排序规则 `utf8mb4_bin`、`pool_pre_ping`、`pool_recycle=1800`、隔离级别 READ COMMITTED、`sql_mode=STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION` |
-| 建表方式 | ① 模型表：`db.create_all()`；② 版本化迁移 `SCHEMA_MIGRATIONS`；③ 幂等原生 `CREATE TABLE IF NOT EXISTS` |
+| SQLite 回退时的 PRAGMA | `journal_mode=WAL`、`busy_timeout=5000`、`synchronous=NORMAL`（监听器按连接类型守卫，MySQL 连接不会执行） |
-| 主库文件 | `data/users.db`（运行时另有 `-wal` / `-shm`） |
+| 建表方式 | **唯一真相是模型**：`db.create_all()`（建缺表）+ `_sync_columns()`（补缺列）；`SCHEMA_MIGRATIONS` 只作版本账本与数据回填 |
-| 当前 schema 版本 | `app_meta.schema_version = 4` |
+| 库位置 | MySQL：由 `DB_HOST/DB_NAME` 指定；SQLite：`data/users.db` |
+| 当前 schema 版本 | `app_meta.schema_version = 6` |
 
-**表清单（12 张业务表 + 1 张 SQLite 内部表）**
+**环境与库的绑定**（防混库，见 [DEPLOY.md](DEPLOY.md) §2.2）
 
-| # | 表 | 来源 | 用途 |
+| `DEPLOY_ENV` | 期望库名 | 用途 |
-|---|---|------|------|
+|---|---|---|
-| 1 | `user` | 模型 | 登录用户与权限 |
+| `dev` | `auto_control_dev` | 本地开发 |
-| 2 | `device_group` | 模型 | 设备分组（JSON 存 serial 列表） |
+| `prod` | `auto_control` | 正式环境（220 容器） |
-| 3 | `task_job` | 模型 | 任务计划 |
-| 4 | `custom_action` | 模型 | 自定义动作（可复用步骤包） |
-| 5 | `apk_file` | 模型 | APK 记录 |
-| 6 | `device` | 模型 + 迁移 v2/v3 | 设备池 |
-| 7 | `pending_device` | 模型 + 迁移 v4 | 待确认的发现设备 |
-| 8 | `app_meta` | 原生（迁移前建） | KV 配置（schema 版本、AI 配置、发现配置） |
-| 9 | `agent_conversation` | 原生（`web/agent_api.py`） | AI 控制台会话 |
-| 10 | `agent_experience` | 原生（`web/agent_api.py`） | 经验库（任务级配方） |
-| 11 | `experience_audit` | 原生（`web/agent_api.py`） | 经验巡检结论 |
-| 12 | `agent_action` | 原生（`web/agent_api.py`） | 动作库（命名动作） |
-| — | `sqlite_sequence` | SQLite 内部 | `AUTOINCREMENT` 的附带产物（备份自检时按 `sqlite_` 前缀排除） |
 
-> **没有外键、没有关系（relationship）、没有索引**：全部靠应用层维护一致性。分组 ↔ 设备是多对多的 **JSON 列表**（`device_group.serials`），删除设备不会级联清理分组里的 serial。
+启动时校验「`.env` 声明」与「库名」「库中登记的 `app_meta.deployment_env`」三方一致，不符**拒绝启动**。
+
+**表清单（14 张，全部是 `core/models.py` 里的 ORM 模型）**
+
+| # | 表 | 用途 |
+|---|---|------|
+| 1 | `user` | 登录用户与权限 |
+| 2 | `device_group` | 设备分组（JSON 存 serial 列表） |
+| 3 | `task_job` | 任务计划 |
+| 4 | `custom_action` | 自定义动作（可复用步骤包） |
+| 5 | `apk_file` | APK 记录 |
+| 6 | `device` | 设备池 |
+| 7 | `pending_device` | 待确认的发现设备 |
+| 8 | `app_meta` | KV 配置（schema 版本、AI 配置、发现配置、库环境标签） |
+| 9 | `agent_conversation` | AI 控制台会话 |
+| 10 | `agent_experience` | 经验库（任务级配方） |
+| 11 | `experience_audit` | 经验巡检结论 |
+| 12 | `agent_action` | 动作库（命名动作） |
+| 13 | `device_install_log` | 设备端应用商店的下载/安装记录（设备上报，见 [DEVICE_AGENT.md](DEVICE_AGENT.md)） |
+| 14 | `task_step_log` | 任务步骤明细（每次步骤执行一条，见 §2.8；**唯一有无界增长风险的表**，靠保留期清理） |
+
+> 2026-09-13 之前，`app_meta` 与 4 张 `agent_*` 表是各模块里的裸 `CREATE TABLE`
+> （不进模型层）。迁 MySQL 时那批 SQL 的 `AUTOINCREMENT`/`TEXT DEFAULT ''`/`TEXT PRIMARY KEY`
+> 全都建不出来，而异常被 `except: pass` 吞掉 —— 表现为「经验库/动作库静默失灵」。
+> 现在全部升为模型，建表只有一条路径。
+
+> **没有外键、没有关系（relationship）**：全部靠应用层维护一致性。分组 ↔ 设备是多对多的
+> **JSON 列表**（`device_group.serials`），删除设备不会级联清理分组里的 serial。
+>
+> **唯一索引只有两个**（设备名 / 指纹，见 §4.2），且都是「空值不参与唯一约束」的语义。
 
 ---
 
@@ -118,6 +137,41 @@
 
 > ⚠️ SQLAlchemy 模型的 `default=` 是 **Python 侧默认值**，SQLite 建表语句里没有 `DEFAULT` 子句；只有原生建表的表才有真正的 SQL DEFAULT。
 
+### 2.8 `task_step_log` — 任务步骤明细
+
+每一次步骤执行一条（`tasks/generic/task.py:_exec_one` 里记录），是「日志 → 步骤明细」
+页的数据源。与 `logs/task.log` 的分工：那边是**排障原文**（什么都写、10MB 滚动），
+这边是**结构化的一份**——设备/任务/步骤/结果/耗时都是列，能过滤、能统计、能导出 CSV。
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | Integer | — | 主键 |
+| `run_id` | String(24) | `""` | 一次运行 = 设备 × 任务 × 第几次尝试；`TaskManager._run_with_retry` 每次尝试生成一个（12 位 hex），把这次尝试的所有步骤串起来 |
+| `job_id` / `job_name` | String(32/120) | `""` | 任务快照（任务删了明细还在，名字仍可读） |
+| `serial` / `device_name` | String(120/80) | `""` | 设备地址与**当时**的名字（快照，改名不影响历史） |
+| `step_path` | String(32) | `""` | 嵌套位置，如 `2.1.3`；容器步骤（loop/group/if_el）会记自己那条，children 追加一级 |
+| `step_label` / `step_type` | String(120/40) | `""` | 步骤标签与类型（`click_el`/`loop`/`wait`…） |
+| `selector` | String(300) | `""` | 元素选择器（长选择器截断） |
+| `result` | String(16) | `""` | `ok` / `miss`（handler 返回 False）/ `error`（抛异常）/ `unknown`（未知步骤类型）/ `skip`（概率未触发）/ `cap`（本次运行已达上限） |
+| `detail` | String(500) | `""` | 异常消息、跳过原因等 |
+| `duration_ms` | Integer | `0` | 本步耗时（慢步骤一眼可辨） |
+| `created_at` | String(20) | `""` | 执行时刻（**保留期按它算**） |
+
+索引：`run_id`、`created_at`、`(serial, created_at)`、`(job_id, created_at)`。
+
+**两条硬边界**（都在 `core/step_log.py`）：
+
+| 常量 | 默认 | 作用 |
+|---|---|---|
+| `MAX_ROWS_PER_RUN` | 2000 | 单次运行最多记 2000 条，超出只补一条 `cap` 说明行。**没有它，`forever` 循环任务会瞬间写爆这张表** |
+| `KEEP_DAYS` | 14 | 保留期：每天 04:13（+ 每次启动）清理更早的记录 |
+
+> ⚠️ **这张表是唯一有无界增长风险的表**，而它会**自动进整库备份**（§6 的派生规则），
+> 所以 `KEEP_DAYS` 直接决定备份包体积。调大之前先想清楚导出的 zip 会有多大。
+
+写入走 `core/step_log.py` 的**专用写线程 + 有界队列**（任务线程只 `put_nowait`，
+微秒级；队列满丢弃并计数）——步骤执行是热路径，绝不能在任务线程里同步写库。
+
 ---
 
 ## 3. 非模型表
@@ -140,50 +194,64 @@
 | `experience_audit` | `id`(PK) · `exp_id` · `verdict`(keep/delete) · `score`(REAL) · `reason` · `hits` · `action`(pending/kept/deleted) · `audited_at` |
 | `agent_action` | `id`(PK) · `name` · `app` · `aliases`(JSON) · `params`(JSON) · `steps`(JSON) · `preconditions` · `hits` · `source_prompt` · `created_at` · `updated_at` |
 
-> ⚠️ 这四张表**不走 `SCHEMA_MIGRATIONS`，无版本管理**，由各模块首次使用时 `CREATE TABLE IF NOT EXISTS` 幂等创建；建表失败会被 `except: pass` 吞掉（后续 SQL 才会报错）。新增此类表时，务必同时登记进备份覆盖清单（§6）。
+> 2026-09-13 起这四张表**已升为 ORM 模型**（见 §1 的说明），建表统一走 `db.create_all()`。
 
 ---
 
 ## 4. 迁移机制
 
-### 4.1 版本化迁移 `SCHEMA_MIGRATIONS`
+### 4.1 建表与补列（以模型为准）
 
-| 版本 | 内容 | SQL 幂等性 |
+**模型定义是唯一真相**。启动时：
-|------|------|-----------|
-| 1 | `user` 增加 `perms` | `ALTER TABLE`（非幂等，靠 duplicate column 兜底） |
-| 2 | 建 `device` 表（**无 `model` 列**） | 幂等（`IF NOT EXISTS`） |
-| 3 | `device` 增加 `model` | `ALTER TABLE`（同上兜底） |
-| 4 | 建 `pending_device` 表 | 幂等 |
-| 5 | `device` 增加 `fingerprint`（设备指纹） | `ALTER TABLE`（靠 duplicate column 兜底） |
-| 6 | `pending_device` 增加 `fingerprint` | 同上 |
 
-执行器 `_migrate_schema()`：
+| 步骤 | 做什么 | 幂等性 |
+|------|--------|--------|
+| `db.create_all()` | 建**缺的表**（模型里有的都在） | 幂等 |
+| `_sync_columns()` | 用 `sqlalchemy.inspect` 比对模型与实表，**补实表缺的列** | 幂等 |
+| `_migrate_schema()` | 维护 `app_meta.schema_version` 账本 + 执行数据回填 | 幂等 |
+| `_ensure_unique_indexes()` | 建设备名/指纹唯一索引（见 §4.2） | 幂等 |
+| `_ensure_default_admin()` | 首次创建 `admin/admin123` | 幂等 |
+| `_migrate_old_json()` | 旧 `groups.json`/`jobs.json` 一次性迁移 | 见 §4.3 |
 
-1. 先 `CREATE TABLE IF NOT EXISTS app_meta(...)`（幂等）
+> 2026-09-13 之前，补列靠 `ALTER TABLE` 报错文本里有没有 `duplicate column name` 来判断
-2. 读 `app_meta.schema_version`（缺省 0）
+> 「列已存在」——那是 SQLite 时代的写法，换方言（MySQL 的错误码/文本都不同）就失效了。
-3. 只执行 `version > current` 的迁移；**SQL 报 `duplicate column name` 时回滚该语句但仍记版本号**（自愈：`create_all` 已建列而版本未记录时不再卡住），其它异常才抛出
+> 现在改为直接读数据库元数据比对，**缺什么补什么，两种方言一套代码**。
-4. 每条迁移后 `INSERT OR REPLACE app_meta('schema_version', v)` 并提交
-5. 整体包 try：失败只记 error 日志，**不阻塞启动**
 
 ### 4.2 唯一索引（设备身份）
 
-`_migrate_schema()` 末尾会补建两个**部分唯一索引**（幂等，与版本号无关，老库升级时也会补）：
+两个「空值不参与唯一约束」的唯一索引，与版本号无关，每次启动都补建：
 
 | 索引 | 作用 |
 |------|------|
-| `ux_device_name` | 设备**名称唯一**（`WHERE name <> ''`，兼容历史空名） |
+| `ux_device_name` | 设备**名称唯一**（空名不参与，兼容历史未命名设备） |
-| `ux_device_fingerprint` | **一台物理设备在池中只有一条记录**（`WHERE fingerprint <> ''`） |
+| `ux_device_fingerprint` | **一台物理设备在池中只有一条记录**（空指纹不参与） |
+
+实现按方言分叉（`_ensure_unique_indexes()`）：
+
+- **SQLite**：直接用带 `WHERE name <> ''` 的**部分索引**
+- **MySQL 5.7**：不支持过滤索引，改用「**虚拟生成列 + 唯一索引**」——
+  生成列把空值映射成 `NULL`（`IF(col IS NULL OR col='', NULL, col)`），
+  而唯一索引允许多个 `NULL`，正好等于「空值不参与唯一」。生成列名 `name_uq` /
+  `fingerprint_uq`，**只由 DDL 添加、不进 ORM 模型**（进了 `create_all` 会尝试写入
+  它并报 Error 3105）。
 
-> 用**部分索引**而不是表级约束：历史数据可能有空名称/空指纹，`<> ''` 让它们不参与唯一性判断。
 > 若历史数据里已有重复（建索引失败），只告警不回滚、不阻塞启动——约束从此刻起对新数据生效，
 > 老的重复行由管理页「改名」处理。
 
+### 4.2.1 排序规则为什么必须是 `utf8mb4_bin`
+
+SQLite 的文本比较是**逐字节**的（大小写敏感）。MySQL 默认的 `utf8mb4_general_ci`
+是大小写**不**敏感，会让 `Admin`/`admin`、`Phone1`/`phone1` 被判成重复，唯一索引和
+等值查询语义全变。所以库、表、连接三处都统一用 `utf8mb4_bin`（逐码点比较，对合法
+UTF-8 等价于字节序）。
+
+唯一的语义差异：`LIKE` 在 `_bin` 下是大小写敏感的（SQLite 对 ASCII 默认不敏感）。
+当前代码里没有任何 `LIKE`/`ilike` 查询，暂无影响。
+
 ### 4.3 旧 JSON 迁移（一次性）
 
 启动时若存在 `data/groups.json` / `data/jobs.json`：对应表为空则导入，随后把文件重命名为 `<name>.json.migrated` 归档。**库非空但 JSON 仍在 → 直接归档**，防止"用户删空数据后重启又复原"。
 
-`init_db(app)` 顺序：`db.init_app` → `create_all()` → `_migrate_schema()` → `_ensure_default_admin()`（首次创建 `admin/admin123`）→ `_migrate_old_json()`。
-
 ---
 
 ## 5. `app_meta` 键清单
@@ -196,41 +264,50 @@
 | `agent_api_key` | API Key（**明文存库**） | 同上 |
 | `agent_default_serial` | 默认目标设备 | 同上 |
 | `agent_max_steps` | 最大步数（钳制 1-200，默认 40） | 同上 |
+| `agent_task_draft` | **AI 建任务**最近一份任务草稿（JSON `{draft,warnings,prompt,created}`，只留最近一份、超限自动瘦身）。**不是任务**：入库仍要用户在步骤编辑器确认后走 `POST /api/jobs` | AI 建任务页 / `submit_task` 工具 |
 | `discovery_enabled` | 自动发现开关（`"1"`/`"0"`） | 工具页「设备池管理」 |
 | `discovery_subnets` | 扫描网段 JSON 数组 | 同上 |
 | `discovery_interval` | 扫描周期秒（10-3600） | 同上 |
 | `discovery_port` | adb 探测端口（1-65535） | 同上 |
+| `discovery_auto_claim` | 指纹匹配时自动认领（`"1"`/`"0"`，默认关） | 同上 |
+| `agent_store_enabled` | 设备端应用商店开关（`"1"`/`"0"`，默认关） | 应用管理页 |
+| `agent_device_token` | **设备端令牌**（Agent 调设备接口用；属凭据） | 同上（启用时自动生成，可重置） |
+| `agent_device_token_at` | 令牌生成/重置时间 | 同上 |
+| `deployment_env` | **库环境标签**（`dev`/`prod`），启动时与 `.env` 比对 | `core/db_config.py`（首次连接）/ 迁移脚本 |
+| `deployment_id` | 库唯一标识（uuid），用于识别"这份备份来自哪个库" | 同上 |
+| `deployment_claimed_at` | 标签写入时间 | 同上 |
+| `notify_webhooks` | **通知 / Webhook 全部配置**（JSON：`{version, settings, webhooks[]}`，见 [NOTIFY.md](NOTIFY.md) §4）。**不建表**——新增/删除 webhook 都只改这一个键 | 系统 → 通知 页 |
+| `step_defaults` | **步骤默认值**（JSON：`{步骤类型: {字段: 值}}`，见 [TASK_DEV.md](TASK_DEV.md) §3.1）。新建步骤时预填用。**只存与出厂值不同的字段**，这样以后调出厂默认能跟着走 | 任务 → 动作配置 页 |
 
 > ⚠️ `agent_api_key` 是**明文存储**，导出备份的 zip 里也含它——备份预览会固定给出"含敏感信息"告警。
+> **同理 `notify_webhooks` 里的 webhook URL 本身就是凭据**（企业微信 `?key=`、钉钉 `?access_token=`、
+> 飞书 `/hook/<token>`）：拿到它就能往群里发消息。接口回显/发送记录/日志一律走
+> `notifier.mask_url()/scrub()` 打码，导出备份时也按敏感信息对待。
+> `app_meta` 的列名 `key` 在 MySQL 里是保留字，**不要直接拼裸 SQL**，统一走
+> `core/db_config.meta_get / meta_set`（方言中立、自动加引号）。
 
 ---
 
 ## 6. 备份覆盖清单（红线）
 
-`core/system_backup.py` 的 `SUMMARY_TABLES`（12 张，与库中实际业务表一一对应）：
+`core/system_backup.py` 的 `SUMMARY_TABLES` **由模型元数据派生**：
 
-| 表 | 中文标签 |
+```python
-|----|---------|
+SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
-| `app_meta` | 系统配置(app_meta) |
+```
-| `user` | 用户 |
+
-| `device_group` | 设备分组 |
+也就是说——**新增一张 ORM 表，自动就进备份覆盖清单**，不可能再漏。
-| `task_job` | 任务计划 |
+`TABLE_LABELS`（预览页的中文标签）仍是手工维护，缺标签时回退显示表名。
-| `custom_action` | 自定义动作 |
-| `apk_file` | APK 记录 |
-| `device` | 设备池 |
-| `pending_device` | 待连接设备 |
-| `agent_conversation` | AI 会话 |
-| `agent_experience` | 经验库 |
-| `experience_audit` | 经验巡检 |
-| `agent_action` | 动作库 |
 
 **双向自检**：
 
 - **导出侧**：登记在 `SUMMARY_TABLES` 但快照里缺失 → 写入 `manifest.coverage_missing` + 日志告警
-- **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警"请登记进 `core/system_backup.py` 的覆盖清单"（字段 `extra_tables`）
+- **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警（字段 `extra_tables`）
-- `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入
+- `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入（这四项是"判定这是不是本平台备份"的最小集合，故意手工维护）
 
-> **红线**：**新增任何持久化表（含原生建表的 agent 类表），必须同时登记进 `SUMMARY_TABLES` 与 `TABLE_LABELS`**，并更新 [DEPLOY.md](DEPLOY.md) §数据备份。历史教训：`agent_action` 曾漏登记，导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
+> **红线**：新增持久化表时**同时补 `TABLE_LABELS` 的中文标签**并更新 [DEPLOY.md](DEPLOY.md) §数据备份。
+> 覆盖清单本身不再需要手工登记（已由 metadata 派生）。历史教训：`agent_action` 曾漏登记，
+> 导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
 
 ---
 
@@ -238,11 +315,15 @@
 
 | 路径 | 内容 | 进 git |
 |------|------|--------|
-| `data/users.db`(+`-wal`/`-shm`) | SQLite 主库 | 否 |
+| `data/users.db`(+`-wal`/`-shm`) | SQLite 主库（**仅回退模式用**；连 MySQL 时这些文件不被读写，可留作历史归档） | 否 |
 | `data/apks/*.apk` | 上传的 APK | 否 |
-| `data/backups/` | 导出临时 zip、`pre_restore_*.db`（导入前安全网）、`restore_failed_*` | 否 |
+| `data/backups/` | 导出临时 zip、`pre_restore_*.zip`（导入前安全网）、`restore_failed_*` | 否 |
 | `data/restore_staging/<token>/` | 导入暂存（TTL 1800s 自动清理） | 否 |
-| `data/restore_pending/` | 待生效恢复任务（重启时消费） | 否 |
+| `data/restore_pending/` | 待生效恢复任务（重启时单事务消费） | 否 |
+
+> 后三个目录可用环境变量改到别处（`DATA_BACKUP_DIR` / `DATA_RESTORE_STAGING_DIR` /
+> `DATA_RESTORE_PENDING_DIR`）——自动化测试必须这么做，否则测试造的待生效恢复任务
+> 会被服务当成用户的操作在下次重启时消费掉。
 | `data/mcp_audit.log` | MCP 调用审计（路径由 `MCP_AUDIT_FILE` 指定） | 否 |
 | `data/uiauto.pid` | uiautodev 子进程 PID | 否 |
 | `data/*.json.migrated` | 旧 JSON 迁移归档 | 否 |

doc/DEPLOY.md

@@ -63,11 +63,25 @@ pip install -r requirements.txt
 
 ```ini
 WEB_SECRET_KEY=<随机 64 hex>            # 不配则每次重启登录态失效
+DEPLOY_ENV=prod                         # 声明"这是生产环境"，与库名 auto_control 绑定
+DB_HOST=<MySQL 主机>                     # 数据库目标（不配则回退 SQLite，生产会拒绝启动）
+DB_USER=<账号>
+DB_PASSWORD=<口令>
+DB_NAME=auto_control
 # USB_ADB_HOST=100.100.10.1             # USB 设备所在的部署机（默认值通常可用）
 # TAILSCALE_API_KEY=<...>               # 需要 Tailscale 管理功能时
 # MCP_PLATFORM_PASS=<admin 的密码>       # 改过 admin 密码必须同步，否则 MCP 登录失败
 ```
 
+**防混库**（`DEPLOY_ENV` 与库名/库标签双向校验，配置项说明见 [DEVELOPMENT.md](DEVELOPMENT.md) §4.2
+与 `.env.example` 的「数据库」段）：启动时若
+「`.env` 声明的环境」与「库名」或「库中登记的 `app_meta.deployment_env`」不符，**直接拒绝启动**并打印
+两边分别是什么。每次启动还会打印一条横幅写明当前连的是哪个库（生产用 WARNING 级），
+页面顶部也常驻一个环境徽标（生产红底 `PROD · <库>`，开发灰底 `DEV`），
+**浏览器标签名也带环境前缀**（开发 `dev-设备自动化后台`，生产 `设备自动化后台`）——
+同时开着两个环境时一眼分得清哪个标签是哪个。
+两个逃生阀 `DB_ALLOW_ENV_MISMATCH` / `DB_ALLOW_SQLITE_FALLBACK` 默认关闭。
+
 其余配置项与默认值见 [DEVELOPMENT.md](DEVELOPMENT.md) §配置速查。
 
 ### 2.3 启动
@@ -172,25 +186,61 @@ tail -20 logs/web.log                              # 无 ERROR/Traceback
 
 **「系统 → 数据备份 / 导入恢复」**（仅管理员）：
 
-- **导出**：`POST /api/system/backup/export` → sqlite 在线备份 API 做一致快照 → 打包 zip（`users.db` + `manifest.json` + 可选 `apks/*.apk`）
+- **导出**：`POST /api/system/backup/export` → 把当前库（MySQL 或回退模式的 SQLite）
-- **导入**：上传 zip/`.db` → 校验预览（完整性 / 必需表 / schema 版本 / 未登记表告警）→ 确认后自动把当前库快照到 `data/backups/pre_restore_*.db`（安全网）→ 落 `data/restore_pending/` → **重启服务生效**
+  整库一致快照成一份 SQLite 归档 → 打包 zip（`users.db` + `manifest.json` + 可选 `apks/*.apk`）
+- **导入**：上传 zip/`.db` → 校验预览（完整性 / 必需表 / schema 版本 / 未登记表 / **来源环境**）
+  → 确认后自动把当前库导出一份 `data/backups/pre_restore_*.zip`（安全网，可再导入回来）
+  → 落 `data/restore_pending/` → **重启服务生效**
+
+> **SQLite 在这里是"备份交换格式"，不是运行时数据库。** 所以归档里永远是一个 `users.db`，
+> 无论平台连的是 MySQL 还是 SQLite —— 前端接口、校验逻辑、老备份的兼容性都不用变，
+> 也不依赖 `mysqldump` 这类外部二进制（容器是 `python:slim`，没有 MySQL 客户端）。
+
+**恢复是怎么生效的**：重启时 `consume_pending_restore()` 在**单个事务内** `DELETE` 全表 +
+分块 `INSERT`，任何一步失败就回滚——当前数据保持原样，不会留下半新半旧的库。
+坏归档会被挪到 `data/backups/restore_failed_*/` 且不阻塞启动。
+
+**跨环境导入默认拒绝**：备份的 manifest 里记了来源环境（`deployment_env`），
+若与当前库环境不一致（例如拿生产备份灌 dev 库），预览会弹黄框告警、直接应用会被拒绝；
+确需跨环境时在预览页勾选「允许跨环境导入」。
 
 ### 5.2 备份覆盖清单（红线）
 
-覆盖清单 = `core/system_backup.py` 的 `SUMMARY_TABLES`，当前 12 张表：`app_meta` / `user` / `device_group` / `task_job` / `custom_action` / `apk_file` / `device` / `pending_device` / `agent_conversation` / `agent_experience` / `experience_audit` / `agent_action`。完整说明见 [DATA_MODEL.md](DATA_MODEL.md) §6。
+覆盖清单 = `core/system_backup.py` 的 `SUMMARY_TABLES`，**由模型元数据自动派生**：
 
-> **新增任何持久化表，必须同步登记进该清单**——否则导出预览里看不到它，会被误判为"没有备份"（2026-09-10 动作库 `agent_action` 就踩过：数据其实在快照里，只是清单漏列）。
+```python
-> 导出侧有**覆盖自检**（登记表缺失 → `manifest.coverage_missing` + 日志告警）；导入侧有**反向自检**（备份含未登记表 → 预览告警）。
+SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
+```
+
+当前 14 张表：`app_meta` / `user` / `device_group` / `task_job` / `custom_action` /
+`apk_file` / `device` / `pending_device` / `agent_conversation` / `agent_experience` /
+`experience_audit` / `agent_action` / `device_install_log` / `task_step_log`。
+完整说明见 [DATA_MODEL.md](DATA_MODEL.md) §6。
+
+> ⚠️ `task_step_log`（任务步骤明细）是**唯一会持续增长**的表：它按 `KEEP_DAYS`
+> （默认 14 天，见 `core/step_log.py`）自动清理，但备份包里会带上保留期内的全部行。
+> 设备多、任务密时导出 zip 会明显变大——需要更小的包就调小那个常量。
+
+> **新增一张 ORM 表，就自动进了覆盖清单**，不可能再漏（2026-09-10 动作库 `agent_action`
+> 曾因手工维护漏登记，数据其实在快照里，只是清单没列 → 被误判为"没有备份"）。
+> 还需要手工做的只有：给新表补 `TABLE_LABELS` 的中文标签。
+> 导出侧有**覆盖自检**（登记表缺失 → `manifest.coverage_missing` + 日志告警）；
+> 导入侧有**反向自检**（备份含未登记表 → 预览告警）。
 
 ### 5.3 目录与手工备份
 
-| 目录 | 用途 |
+| 目录 | 用途 | 可否用环境变量改 |
-|------|------|
+|------|------|------------------|
-| `data/backups/` | 导出临时 zip、`pre_restore_*.db`、`restore_failed_*` |
+| `data/backups/` | 导出临时 zip、`pre_restore_*.zip`（导入前安全网）、`restore_failed_*` | `DATA_BACKUP_DIR` |
-| `data/restore_staging/` | 导入暂存（TTL 30 分钟自动清理） |
+| `data/restore_staging/` | 导入暂存（TTL 30 分钟自动清理） | `DATA_RESTORE_STAGING_DIR` |
-| `data/restore_pending/` | 待生效恢复任务（重启时消费） |
+| `data/restore_pending/` | 待生效恢复任务（重启时消费） | `DATA_RESTORE_PENDING_DIR` |
 
-手工整目录备份 `data/` 仍可作兜底，但**整库恢复建议走内置功能**（在线一致快照 + 预恢复备份 + 重启原子生效，避免手工替换被 WAL/占用文件破坏）。
+> 这三个环境变量主要给**自动化测试**用：测试必须把恢复目录指到临时位置，
+> 否则测试造出来的"待生效恢复任务"会在服务下次重启时被当成用户的操作消费掉。
+
+连 MySQL 时 `data/users.db` 及其 `-wal`/`-shm` **不再被读写**（只有回退模式才用），
+可以留作历史归档。手工整目录备份 `data/` 仍可作兜底，但**整库恢复建议走内置功能**
+（一致快照 + 预恢复备份 + 重启时事务替换）。
 
 > ⚠️ 备份 zip 含**用户口令哈希与 AI 控制台 API Key（明文）**，注意保管与传输。
 
@@ -226,9 +276,32 @@ docker restart python-app        # 容器场景
 
 ### 7.2 数据库迁移
 
-- 表结构变化由 `init_db()` 自动处理：`create_all()` 建新表 + `SCHEMA_MIGRATIONS` 补列（幂等，失败不阻塞启动）
+- **表结构变化**由 `init_db()` 自动处理：`create_all()` 建缺表 + `_sync_columns()` 补缺列（幂等，失败不阻塞启动，见 [DATA_MODEL.md](DATA_MODEL.md) §4）
 - 旧 `groups.json` / `jobs.json` 首次启动自动迁移并归档为 `.migrated`
-- **跨版本恢复**：用「导入恢复」上传旧库 → 预览会提示 schema 版本差异 → 应用后重启（新版本会自动补迁移）
+- **跨版本恢复**：用「导入恢复」上传旧库 → 预览会提示 schema 版本差异 → 应用后重启（新版本会自动补列/补空表）
+
+#### SQLite → MySQL（一次性）
+
+首次把平台从单文件 SQLite 换到 MySQL 时，用迁移脚本搬数据：
+
+```bash
+# 0) 先在 .env 里配好 DB_HOST/DB_USER/DB_PASSWORD/DB_NAME（或用 --target-url）
+# 1) 干跑：审计源库 + 建目标 schema，不搬数据
+python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev --dry-run
+# 2) 正式搬（目标库已有的数据会被整表替换；单事务，失败自动回滚）
+python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev
+# 3) 复验（只比对不写）
+python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev --mode verify
+```
+
+脚本做的事：源库完整性校验 → **列宽审计**（SQLite 不强制长度，MySQL 严格模式下超长会直接报错，
+所以先拦下来）→ 建目标 schema（复用平台的 `create_all` + 补列 + 唯一索引）→ 逐表搬行
+（单事务）→ **逐表行数 + 全行 SHA-256 比对** → 写库环境标签与 `schema_version`。
+
+> `--env prod` 必须额外加 `--allow-prod`，交互终端还要手打 `prod` 确认（这是唯一会往生产库灌数据的入口）。
+> 目标库若已登记为别的环境（`app_meta.deployment_env`），除非 `--force-env` 否则拒绝。
+
+建库建账号见 `scripts/sql/init_mysql_5.7.sql`（utf8mb4 + `utf8mb4_bin`，两个库对应 dev/prod）。
 
 ### 7.3 跨机迁移（换部署机）
 

doc/DEVELOPMENT.md

@@ -35,6 +35,16 @@
 
 > 每个改动**单独分支 + 单独 commit**，主题单一，便于评审与回退。不允许"开发完顺手 commit/push"。
 
+**修复也走这条流程，包括线上紧急修复**（2026-09-14 补：当天两次 APK 安装修复因为"生产卡着"
+直接提交在 dev 上、紧接着就合 main 部署，被负责人纠正）：
+
+- 紧急修复照样从 dev 切 `fix/xxx` 分支——**不允许直接 commit/push 到 dev**，
+  哪怕改动只有几行、哪怕生产正卡着
+- 第 ② 步的"自测"要**跑通本机服务**（起服务/点页面/看日志），不能只有脚本级验证
+- 第 ③ 步的确认要点名两件事：**「是否合 dev」**和**「是否合 main + 部署生产」**——
+  紧急场景可以一次性问清，但**不能把两个节点合并成一次默认同意**
+- 线上正卡住时：先**恢复**（重启/回滚等运维动作，经确认即可执行），再按流程走修复
+
 ---
 
 ## 2. 技术红线（违反会打断共享 adb transport 或造成生产事故）
@@ -46,7 +56,7 @@
 | 3 | **空闲设备扫描不主动 connect/disconnect** | 避免扰动共享连接 | 前台扫描对空闲设备直接返回"空闲"；设备发现用 socket 探测 |
 | 4 | **adb key 保持历史 key 不变** | 设备信任该 key，换 key 全部 `unauthorized` | 部署沿用 `~/.android/adbkey` |
 | 5 | **生产（220）默认只读** | 生产事故成本高 | 任何写操作（pull/重启/改文件）都需负责人确认 |
-| 6 | **新增持久化表必须登记备份覆盖清单** | 漏登记 = 等于没备份 | `core/system_backup.py` 的 `SUMMARY_TABLES` + `TABLE_LABELS`，详见 [DEPLOY.md](DEPLOY.md) §5.2 |
+| 6 | **新增持久化表必须进备份覆盖清单** | 漏登记 = 等于没备份 | `SUMMARY_TABLES` 已由模型元数据自动派生（加了 ORM 表就进清单）；**手工要做的只有补 `TABLE_LABELS` 中文标签**，详见 [DEPLOY.md](DEPLOY.md) §5.2 |
 | 7 | **功能/配置/接口改动必须同步文档** | 文档落后会误导开发与运维 | 见 §6；索引 [doc/README.md](README.md) |
 
 ### 其它开发约束
@@ -97,6 +107,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 | 前端验证 | 无 npm/构建，改完强刷；浏览器控制台看报错 |
 | 接口 500 巡检 | `python scripts/regression_test.py`（**⚠️ 当前在 Windows 上会因 `signal.alarm` 报错**，Linux/macOS 可用） |
 | 停止设备/清异常 | 监控页「停止全部 / 停止选中 / 清除全部异常」 |
+| AI 建任务（designer）验证 | AI 控制台 →「AI 建任务」选**空闲**设备跑一轮；脚本方式见 [AI_TASK_GEN.md](AI_TASK_GEN.md) §10.5。草稿只落 `app_meta.agent_task_draft`（不是任务），验证完 `POST /api/agent/task_draft/clear` 清掉。**注意它会真在设备上点按**（导航类动作），且与聊天共用同一个运行槽 |
 
 > **改了数据库/配置想复原**：删 `data/users.db*` 会丢数据，别这么干；用「系统 → 备份/导入」或先手工复制一份 `data/`。
 
@@ -117,7 +128,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 ### 4.1 配置文件与优先级
 
 - `config.py`：**程序级常量**（端口、路径、USB 远程 adb 等），改它要重启
-- `.env`（项目根，不入 git）：**密钥与可覆盖配置**，逐行解析 + `os.environ.setdefault`（**真实环境变量优先**）
+- `.env`（项目根，不入 git）：**密钥与可覆盖配置**，逐行解析 + `os.environ.setdefault`（**真实环境变量优先**）；**数据库目标（`DEPLOY_ENV` + `DB_*`）也在这里**
 - `app_meta`（数据库 KV）：**运行时可改的配置**（AI 配置、设备发现参数），在界面上改
 
 ### 4.2 `config.py` 常量
@@ -128,6 +139,11 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 | `WEB_HOST` / `WEB_PORT` | `0.0.0.0` / `18050` | 硬编码 | 18050 避开 Windows 动态端口段 |
 | `DATA_DIR` / `APK_DIR` | `data/` / `data/apks/` | 代码计算 | |
 | `BACKUP_DIR` / `RESTORE_STAGING_DIR` / `RESTORE_PENDING_DIR` | `data/backups` / `data/restore_staging` / `data/restore_pending` | 代码计算 | 备份相关 |
+| `DEPLOY_ENV` | `dev` | `.env` 可覆盖 | 声明这套配置连哪个环境的库；与库名绑定（dev→`auto_control_dev`，prod→`auto_control`），不符拒绝启动 |
+| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | 空 / `3306` / 空 / 空 / 空 | `.env` 可覆盖 | MySQL 目标；`DB_HOST` 为空则回退 SQLite（**生产禁止静默回退**，需 `DB_ALLOW_SQLITE_FALLBACK=1`） |
+| `DB_CHARSET` / `DB_COLLATION` | `utf8mb4` / `utf8mb4_bin` | `.env` 可覆盖 | 排序规则必须用 `_bin`（逐码点比较，等价 SQLite 的大小写敏感语义） |
+| `DATABASE_URL` | 空 | `.env` 可覆盖 | 完整连接串，优先级最高；脚本临时指向别的库时用 |
+| `DB_ALLOW_ENV_MISMATCH` / `DB_ALLOW_SQLITE_FALLBACK` | `0` | `.env` | 逃生阀，见 [DEPLOY.md](DEPLOY.md) |
 | `USB_ADB_HOST` / `USB_ADB_PORT` | `100.100.10.1` / `5037` | `.env` 可覆盖 | USB 设备所在部署机的远程 adb server |
 | `TAILSCALE_API_KEY` / `TAILSCALE_TAILNET` | 空 | `.env` | Tailscale 管理功能 |
 | `DISCOVERY_PORT` / `DISCOVERY_INTERVAL` | `5555` / `60` | `.env` 可覆盖 | 设备发现（网段在工具页配置，存 `app_meta`） |
@@ -140,6 +156,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 |------|------|------|------|
 | `WEB_SECRET_KEY` | 未配置则随机 | `web_server.py` | 会话密钥，**生产必须固定** |
 | `DISABLE_SCHEDULER` | 未设 | `core/task_manager.py` | 设任意值则**不启动 cron 调度器**（测试用） |
+| `DATA_BACKUP_DIR` / `DATA_RESTORE_STAGING_DIR` / `DATA_RESTORE_PENDING_DIR` | `data/backups` 等 | `config.py` | 备份/恢复目录改到别处；**自动化测试必须指到临时目录**（否则测试造的待生效恢复任务会在下次重启被当成用户操作消费） |
 | `MCP_ENABLED` | `1` | `scripts/start.sh` | =0 则不后台拉起 MCP |
 | `MCP_ALLOW_WRITE` | `0`（脚本内强制 1） | `mcp_server/config.py` | 写操作总开关 |
 | `MCP_PLATFORM_URL` / `_USER` / `_PASS` | `http://127.0.0.1:18050` / `admin` / 空 | `mcp_server/config.py` | 登录平台的凭据（改过 admin 密码要同步） |
@@ -167,9 +184,10 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 
 ### 5.2 新增数据库字段/表
 
-- 模型改 `core/models.py`；新表 `create_all()` 会建
+- 模型改 `core/models.py`；新表 `create_all()` 会建（**幂等**：已是模型就会自动建/补列）
 - **老库**要在 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）
-- **新增表**：登记进 `core/system_backup.py` 的 `SUMMARY_TABLES` + `TABLE_LABELS`（**红线**）
+- **新增表**：`SUMMARY_TABLES` 由模型元数据**自动派生**（＝自动进备份覆盖清单），
+  仍需手工做的是补 `TABLE_LABELS` 的中文标签（**红线**）
 - 更新 [DATA_MODEL.md](DATA_MODEL.md) 与 [DEPLOY.md](DEPLOY.md) §5.2
 
 ### 5.3 修改前端

doc/DEVICE_AGENT.md

@@ -0,0 +1,258 @@
+# 设备端 Agent 接口契约（DEVICE_AGENT）
+
+> 适用读者：写**设备端 Agent APK**（另一个仓库）的人，以及改平台侧这组接口的人。
+> 相关：[API.md](API.md)（管理端接口）、[DEPLOY.md](DEPLOY.md)（部署）、[ARCHITECTURE.md](ARCHITECTURE.md)。
+
+**这份文档是两个仓库之间的契约。** 平台侧实现见 `web/device_agent_api.py`；
+设备端实现见另一个仓库。**改协议必须同时改两边**（见 §6 版本约定）。
+
+---
+
+## 1. 为什么有这组接口
+
+平台通过 **adb** 驱动设备（点击/输入/装应用……），但有三件事 adb 干不好，需要设备上装一个 App：
+
+| 需求 | adb 的困境 | Agent 的做法 |
+|------|-----------|-------------|
+| 写系统剪贴板 | Android 10+ 禁止后台/shell 写剪贴板；u2 的 `set_clipboard` 会"成功但内容被丢弃" | 启动一个**透明 Activity**（有焦点才能写），写完立即退出 |
+| 安装 APK | MIUI 会拦 `adb install`（`USER_RESTRICTED`），要人工点「继续安装」 | **App 自己调系统安装器** → 走普通应用安装流程，**不触发那道 USB 拦截** |
+| 显示设备身份 | 现在要把一个 HTML 大字页推给设备浏览器打开，依赖浏览器 | 全屏大字显示：设备名/IP/序列号/平台地址 |
+
+其中「装应用」是**设备主动来取**（拉清单 → 选 → 下载 → 装），所以平台开了一组
+**设备专用接口**；「写剪贴板」「显示身份」是**平台推指令**，仍走 adb（§5）。
+
+---
+
+## 2. 接入流程（设备端视角）
+
+```
+① 一次性：平台在「工具 → 应用管理 → 📱 设备端应用商店」启用，拿到
+   接入地址 base_url（如 http://192.168.20.220:18050）和设备令牌 token
+   —— 这两个值可以通过 adb 一次性推给设备（见 §5.3），不必在每台手机上手输
+
+② 开机/定时：GET  {base_url}/api/device/agent/bootstrap
+   带上 X-Device-Token / X-Device-Fingerprint
+   → 拿到「我是谁」（平台分配的设备名）+「有哪些应用可以装」
+
+③ 用户在手机上选一个应用：
+   GET  {base_url}/api/device/agent/apk/{id}  → 下载 APK 到应用私有目录
+
+④ 调系统安装器安装（PackageInstaller / ACTION_VIEW + FileProvider）
+   —— 会弹系统安装确认框，用户在屏幕上点一下即可
+
+⑤ 回报结果：POST {base_url}/api/device/agent/report
+   （download / install_ok / install_fail + 失败原因）
+   平台在「设备端应用商店」面板能看到记录
+```
+
+> Agent 需要 `INTERNET` 与 `REQUEST_INSTALL_PACKAGES` 权限；还需要用户在系统设置里
+> 给"安装未知应用"授权（这是 App 自装的**唯一**前置条件，比 MIUI 的 USB 拦截好过得多）。
+
+---
+
+## 3. 接口规格
+
+所有接口：
+- **不需要登录会话**，靠 `X-Device-Token` 鉴权
+- 请求/响应均为 UTF-8 JSON（下载接口除外）
+- **功能默认关闭**：平台侧未启用时，全部返回 `404 {"ok":false,"error":"not found"}`
+  （不暴露接口是否存在）
+
+### 3.1 通用请求头
+
+| 头 | 必填 | 说明 |
+|----|------|------|
+| `X-Device-Token` | ✅ | 平台生成的设备令牌 |
+| `X-Device-Fingerprint` | 建议 | `ro.serialno`。**平台靠它认出"你是哪台设备"**（换 IP 也能认回原名） |
+| `X-Device-Serial` | 可选 | 当前 adb 地址（`IP:5555`），指纹认不出时的兜底 |
+
+错误码：
+
+| 状态 | 含义 | 设备端该怎么办 |
+|------|------|---------------|
+| 404 | 平台未启用设备端商店（或接口不存在） | 提示管理员去平台开启；不要重试轰炸 |
+| 401 | 令牌不对/缺失 | 提示重新配置令牌（管理员重置后要在设备上更新） |
+| 500 | 平台内部错误 | 退避重试 |
+
+### 3.2 `GET /api/device/agent/bootstrap`
+
+拉设备身份 + 可安装应用清单。建议开机后拉一次 + 每次打开"商店"界面时拉一次。
+
+**响应**
+```json
+{
+  "ok": true,
+  "agent_api_version": 1,
+  "server_time": "2026-09-13 14:38:11",
+  "platform": { "url": "http://192.168.20.220:18050" },
+  "device": {
+    "fingerprint": "woijo7v4sgnrhqb6",
+    "serial": "192.168.20.100:5555",
+    "name": "A08",
+    "known": true
+  },
+  "apks": [
+    {
+      "id": "56b114aa",
+      "display_name": "ClipInject",
+      "package_name": "com.example.clipinject",
+      "version_name": "1.0",
+      "version_code": 1,
+      "size": 11615,
+      "upload_time": "2026-09-09 13:49:06",
+      "download_path": "/api/device/agent/apk/56b114aa"
+    }
+  ]
+}
+```
+
+- `device.name`：**平台给这台设备起的名字**（如 `A08`）—— 身份显示界面直接用它
+- `device.known=false`：这台设备还没登记进平台设备池（指纹没匹配上），`name` 为空；
+  设备端应显示"未登记"，不要假装自己有名字
+- `platform.url`：按**设备实际请求到的地址**回填，可直接用于拼下载地址
+- `apks[].download_path` 是相对路径，拼 `platform.url` 即完整 URL
+
+### 3.3 `GET /api/device/agent/apk/{apk_id}`
+
+下载 APK 文件本体（`application/vnd.android.package-archive`）。
+
+- 成功：`200` + 文件流
+- `404`：id 不存在或平台侧文件已删（**注意与"未启用"的 404 区分：看响应体**，
+  未启用时是 JSON `{"ok":false,...}`，文件缺失时也是 JSON —— 设备端拿到非 `application/...` 的响应就视为失败）
+
+### 3.4 `POST /api/device/agent/install`（可选：让平台帮你静默装）
+
+**背景**：设备上的 App 自己调系统安装器，MIUI 上要过「继续 → 勾选未经安全检测 →
+继续更新」甚至 ICP 备案检查好几步；而**平台用 adb 装是静默的**（实测升级 2.7s、
+全新安装 7.9s、336MB 大包都没弹过一次框）。
+
+所以"安装/更新"按钮**建议走这个接口**：用户在手机上选（商店体验），平台用 adb 落地（静默）。
+
+**请求体**：`{"apk_id": "56b114aa"}`
+
+**响应**：
+```json
+{"ok": true, "msg": "开始安装 X 到 1 台设备", "serial": "192.168.20.100:5555"}
+```
+
+- 受理后平台**异步**安装，设备端应轮询本机该包的 versionCode 变化来判断结果
+  （装上后按 §3.5 上报 `install_ok`）
+- 平台装不了（比如 MIUI 拦了 adb 安装、设备不在池里）→ `ok=false` + `error`，
+  **设备端应退回本机安装**（`ACTION_VIEW` + FileProvider，会弹系统确认框，但至少能装）
+- `409` = 这台设备还没登记进平台设备池（平台不认识它，不能替它装）
+
+### 3.5 `POST /api/device/agent/report`
+
+回报下载/安装结果，平台侧留档（面板可见）。
+
+**请求体**
+```json
+{
+  "apk_id": "56b114aa",
+  "action": "download | install_ok | install_fail",
+  "package_name": "com.example.clipinject",
+  "version_name": "1.0",
+  "message": "失败原因（install_fail 时必填，越具体越好）"
+}
+```
+
+**响应**：`{"ok": true}`；`action` 非法 → `400`。
+
+> **失败原因请写人话**：平台面板直接显示 `message`。
+> 例如「MIUI 拦截：用户未确认」「安装包解析失败」「存储空间不足」。
+
+---
+
+## 4. 平台侧配置（管理端）
+
+「工具 → 应用管理 → 📱 设备端应用商店」：
+
+| 操作 | 接口 |
+|------|------|
+| 读配置（含令牌） | `GET /api/agent-store/config` |
+| 启用/停用 | `POST /api/agent-store/config` `{"enabled": true}` |
+| 重置令牌 | `POST /api/agent-store/config` `{"regenerate_token": true}` |
+| 安装记录 | `GET /api/agent-store/logs?limit=50` |
+
+- 三个接口都需要**登录 + 应用管理权限**
+- **停用**不影响已装的 App，只是设备端拿不到清单（返回 404）
+- **重置令牌**后旧令牌立即失效，所有设备要在 Agent 里更新
+
+---
+
+## 5. 平台 → 设备的指令（走 adb，不走网络）
+
+这些**没有 HTTP 接口**，由平台用 `adb shell am start` 拉起设备上的 Activity。
+
+### 5.1 剪贴板注入（已在用，务必保持兼容）
+
+```bash
+adb -s <serial> shell am start -n <pkg>/.ClipActivity --es text_b64 <base64(UTF-8)>
+```
+
+- **必须 base64**：adb shell 直传中文/特殊字符会变形
+- 必须用**透明 Activity**（有焦点才能写剪贴板），写完**立即退出**
+- 平台判定失败的方式：`am start` 输出里有 `unable to resolve Intent` / `does not exist`
+  → 视为"设备未安装 Agent"
+
+### 5.2 设备身份显示（设备端已实现）
+
+```bash
+adb -s <serial> shell am start -n <pkg>/.InfoActivity \
+  --es name "A08" --es ip "192.168.20.100" --es serial "192.168.20.100:5555" \
+  --es server "http://192.168.20.220:18050"
+# 关闭：--es close 1
+```
+
+要求：全屏大字、再次调用可覆盖内容、`close` 可关闭、不驻留前台。
+
+### 5.3 扫码配置（设备端已实现）
+
+平台「设备池」里点某台设备的「**二维码**」→ 生成一张二维码 → 手机上的 Agent 点
+「扫码配置」扫一下，就把 **平台地址 + 设备令牌 + 这台设备的指纹** 一次写入。
+
+**二维码内容**（JSON 文本，设备端按字段名解析，多余的字段忽略）：
+```json
+{"v":1,"server":"http://192.168.20.250:18050","token":"<设备令牌>",
+ "fingerprint":"s8o7nrt8pbzhfadq","name":"A07"}
+```
+
+- `v` = 格式版本（当前 1）；`fingerprint` 可能为空串（平台还没采到指纹）
+- 设备端扫到**不是本平台的二维码**时应提示并继续扫，不要静默失败
+- 平台侧生成接口：`GET /api/devices/qrcode?serial=<设备地址>`（需登录 + 设备权限），
+  返回 `{png( base64 data-url), payload, warn}`；`warn` 非空时要显示出来
+  （最常见的是"你现在用 localhost 打开平台，二维码里的地址手机会连不上"）
+
+> 与 §5.4 的 adb 下发**等价、互为补位**：设备已经连上平台时用 adb 批量下发（零操作），
+> 人在机器旁或设备还没接进来时用扫码（不用线、不用打字）。
+
+### 5.4 一次性配置下发（adb，建议设备端实现）
+
+```bash
+adb -s <serial> shell am start -n <pkg>/.ConfigActivity \
+  --es server "http://192.168.20.220:18050" --es token "<设备令牌>"
+```
+
+有了它，8 台设备不用一台台手输地址和令牌。
+
+---
+
+## 6. 版本与兼容
+
+- `agent_api_version`（当前 **1**）在每次 `bootstrap` 响应里返回
+- **设备端**：启动时对比自己实现的版本，不一致要在日志里明确记下来（不要静默）
+- **平台端**：
+  - 加字段 / 加接口 = 小版本，设备端忽略未知字段即可
+  - 改已有字段语义 / 删字段 / 改鉴权方式 = **大版本**，两边必须同时改
+- 改了协议，**必须同时改这份文档的两个仓库版本**（本文件是平台侧那一份）
+
+---
+
+## 7. 安全须知
+
+- **令牌是凭据**：等于"能读平台的应用清单和 APK 文件"。别写进日志、别外传、
+  别提交到 git（平台侧存在 `app_meta.agent_device_token`，会随备份一起走）
+- 平台侧这组接口**只读**：只能读清单和下载 APK，**不能**触发任务、不能改设备池、
+  不能读配置或密钥
+- 生产环境建议：令牌泄露时立即在面板点「重置令牌」
+- 设备端**不需要也不应该**拿 admin 账号密码

doc/MCP.md

@@ -12,7 +12,7 @@
 AI 控制台 / 外部 MCP 客户端
         │  Streamable HTTP（http://<host>:8033/mcp）
         ▼
-MCP Server（mcp_server/mcp_server.py）        ← 19 个 de_* 工具
+MCP Server（mcp_server/mcp_server.py）        ← 20 个 de_* 工具
         │  平台 HTTP API（登录 + CSRF）  或  轻量 adb/u2 直连
         ▼
 auto_control 平台（:18050）                    ← 设备池 / 任务 / 看屏
@@ -63,7 +63,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> \
 
 ---
 
-## 4. 工具清单（19 个）
+## 4. 工具清单（20 个）
 
 统一返回约定：
 
@@ -88,6 +88,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> \
 |------|------|------------|
 | `de_screenshot` | `serial` | `{image:{type:"image",data:<base64>,mimeType:"image/jpeg"}, width, height, native_size, screen_state}`。多模态模型直接看图 |
 | `de_ui_tree` | `serial`, `limit`(150，1-300) | `{count, elements:[{text,id,desc,class,clickable,bounds}]}`，**可点击元素排前**；`limit` 控 token |
+| `de_snapshot` | `serial`, `limit`(120，1-300) | **截图 + 元素树一次取齐**（推荐用它代替 `de_screenshot`+`de_ui_tree`）：平台侧同一个 u2 连接背靠背取 + 双截图校验。返回 `{image, width, height, native_size, screen_state, unstable, cost_ms, count, elements}`；`unstable=true` 表示抓取期间界面在变化（此时元素坐标不可信，让设备静下来再取）。**同样会建立 `de_tap/de_swipe` 的坐标空间** |
 | `de_ocr` | `serial` | `{count, texts:[{text,score}]}`（≤100 条）。UI 树拿不到的图片/WebView 文字用它 |
 | `de_read_clipboard` | `serial` | `{clipboard}` |
 | `de_list_apps` | `serial`, `keyword`("") | `{count, packages}` 第三方已装包名（`pm list packages -3`，≤200） |

doc/MCP_DESIGN.md

@@ -1,6 +1,6 @@
 # MCP 手机控制（Mobile Control MCP Server）设计文档
 
-> 状态：**设计稿 / 演进记录**——凡与实现不符处，以 [MCP.md](MCP.md)（使用手册，含 19 个工具的权威清单）与 `mcp_server/` 代码为准。
+> 状态：**设计稿 / 演进记录**——凡与实现不符处，以 [MCP.md](MCP.md)（使用手册，含 20 个工具的权威清单）与 `mcp_server/` 代码为准。
 > 本文保留设计取舍与里程碑，便于回溯"为什么这么做"；文中的"演进备选"均**未落地**。
 > 最后核对：2026-09-10（对照 dev 现状）。
 

doc/NOTIFY.md

@@ -0,0 +1,245 @@
+# 通知 / Webhook（NOTIFY）
+
+> 面向：要给平台接告警的运维、以及往各组件加通知点的开发。
+> 相关：[API.md](API.md)（接口）、[DATA_MODEL.md](DATA_MODEL.md)（配置存哪）、
+> [ARCHITECTURE.md](ARCHITECTURE.md)（线程模型）。
+
+---
+
+## 1. 它是什么
+
+平台各组件（任务、设备、安装、备份、AI 巡检…）在关键时刻调一个统一入口：
+
+```python
+from core import notifier
+notifier.notify("task.device.failed", serial="192.168.20.71:5555",
+                device_name="A02", job_name="抖音养号", cause="选择器连续 10 次未命中")
+```
+
+`notify()` **只做内存操作**（读配置快照 → 匹配订阅 → 丢进队列），真正发 HTTP 的是后台
+daemon 线程。所以：
+
+- 任务线程里可以直接调，**不用包 app_context、不用 try/except**（内部全兜住了）
+- **但必须放在所有 `with self._lock` 之外**——别让通知拖住调度锁
+- 通知模块自己出问题（地址写错、对方挂了、配置坏了）**绝不影响任务/设备/备份**，
+  最多在日志里留一条警告
+
+```
+业务线程 notify() ──入队──▶ dispatcher（1 线程）──▶ sender ×3 ──▶ 企业微信/自建服务
+                                ① 聚合  ② 限流  ③ 折叠
+                                         └─▶ 发送记录（内存 200 条 + logs/notify.log）
+```
+
+---
+
+## 2. 快速上手（企业微信）
+
+1. 企业微信群里 → 群机器人 → 添加 → 复制 Webhook 地址（形如
+   `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxx`）
+2. 后台 → **系统 → 通知 / Webhook → ＋ 新建 Webhook**：名称随便起、格式选「企业微信」、
+   粘贴地址、在事件树里勾上关心的事件（★ 是建议开的）
+3. 点该行的 **发送测试** —— 群里立刻能收到一条 markdown；收不到就看返回的 HTTP/errcode
+
+---
+
+## 3. 事件目录
+
+**权威定义在 `core/notify_events.py`**（后台「通知」页也是从它渲染的，不会漂移）。
+所有事件**默认不启用**——登记不等于推送，勾了才发。
+
+| 类别 | 事件 |
+|---|---|
+| 任务批次 | `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` |
+| 系统 | `system.backup.exported` · `.imported` · `.restored` · `.restore_failed` · `service.started` · `.stopping` · `user.login` |
+| AI | `ai.audit.finished` · `.failed` · `.skipped` |
+| 其它 | `notify.test`（测试按钮专用） |
+
+订阅支持通配：`*`（全部）、`task.*`、`device.*`。
+
+> 语义分工（**避免重复告警**）：`worker.*` 是**单次尝试**层面；`task.device.success/failed`
+> 是"这台设备最终成功/失败"的**唯一权威点**。所以一个设备重试 3 次后失败，只会收到 **1 条**
+> `task.device.failed`，不会收到 3 条噪音。
+
+**多设备批次怎么发**（设备一多，逐台发就等于刷屏）：
+
+| 事件 | 多设备批次（>1 台） | 单台任务 |
+|---|---|---|
+| `task.batch.started` | 发 1 条（N 台） | 发 |
+| `task.device.success` | **不发**（批次汇总里已有成功台数） | 发 |
+| `task.device.failed` / `.offline` | 逐台发（失败是少数，且要知道是哪台） | 发 |
+| `task.batch.finished` | **发 1 条汇总** | 发 |
+
+批次汇总长这样（有失败时才会多出一行「失败设备」，列出名字（型号）：原因，最多 5 条）：
+
+```
+### ✅ 任务批次结束：抖音养号
+> **任务ID**：b370bbbc
+> **总数**：13
+> **成功**：13
+> **失败**：0
+> **停止**：0
+> **跳过**：0
+> **耗时(秒)**：1347
+> **时间**：2026-09-16 09:22:57
+```
+
+单设备事件里的设备一律**显示名字**（`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. 配置
+
+存在 `app_meta.notify_webhooks` 一个键里（JSON，**不建表**，因此不涉及备份覆盖清单）：
+
+```json
+{
+  "version": 1,
+  "settings": {"global_enabled": true, "default_agg_window": 30,
+               "default_rate_limit": 18, "log_keep": 200, "http_timeout": 5},
+  "webhooks": [
+    {"id": "wh_ab12cd34", "name": "运维群", "enabled": true, "format": "wecom",
+     "url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=…",
+     "secret": "", "events": ["task.device.failed", "device.*"],
+     "agg_window": 30, "rate_limit_per_min": 18,
+     "title_template": "", "body_template": "", "headers": {}}
+  ]
+}
+```
+
+上限（超了**拒绝保存**，不静默截断）：webhook ≤ 20 条、整体 JSON ≤ 60000 字符、URL ≤ 2048。
+
+**安全**：URL 里带凭据（企微 `?key=`、钉钉 `?access_token=`、飞书 `/hook/<token>`、
+Bark `/…/<key>`、Slack `/services/T…/B…/X…`）→ 接口回显、发送记录、日志一律打码
+（`mask_url` 同时处理 query 与**路径里的 token**；异常消息过 `scrub`）；
+编辑时**留空即不修改**；`secret` 永不回显（只回"已配置"）。
+
+---
+
+## 5. 推送格式
+
+| 格式 | 请求体 | URL 怎么填 | 成功判定 / 关键约束 |
+|---|---|---|---|
+| `wecom` 企业微信 | `{"msgtype":"markdown","markdown":{"content":"…"}}` | 群机器人 → 复制的 Webhook 地址（含 `?key=`） | **`errcode==0`**；content **≤4096 字节**（按字节截断、不会截出半个汉字）；**每机器人每分钟 20 条**，超限 `45009` |
+| `dingtalk` 钉钉 | `{"msgtype":"markdown","markdown":{"title","text"}}` | 群设置 → 智能群助手 → 添加机器人 → 自定义 → 复制的 Webhook 地址（含 `?access_token=`） | **`errcode==0`**；正文 ≤20000 字节；官方 20 条/分，**超限会被限流 10 分钟**（这里默认 15 留余量）；机器人安全设置选「加签」时密钥必填 |
+| `feishu` 飞书 | `{"msg_type":"interactive","card":{header + markdown 元素[,"timestamp","sign"]}}` | 群设置 → 群机器人 → 添加 → 自定义机器人 → 复制的 Webhook 地址（`…/bot/v2/hook/<token>`） | **`code==0`**；请求体 ≤20KB；官方 100 条/分（这里默认 60）；开了「签名校验」时密钥必填 |
+| `bark` iOS 推送 | `{"title","body","markdown","group","level"[,"device_key"]}` | Bark App 里复制的那串（`https://api.day.app/<key>`）**或** `https://api.day.app/push` + 设备 Key 填到「设备 Key」 | **`code==200`**（注意和企业微信不一样！）；走 APNs，正文按 2048 字节截断；`markdown` 传富文本、`body` 传纯文本兜底 |
+| `json` 通用 / Slack | 由 `body_template` 决定 | 你自己的接收端；Slack 填它的 Incoming Webhook URL | HTTP 200（响应体里有 `code`/`errcode` 时必须为 0）；模板保存前**干跑校验**；`secret` 会作为 `X-Webhook-Secret` 头发出 |
+
+> 成功码**按格式**判定（企微/钉钉/飞书 = 0，Bark = 200），写在适配器的 `ok_codes` 上——
+> 加新格式时别忘了一起定。
+
+### 加签：钉钉和飞书**算法不一样**，别互相照抄
+
+| | 钉钉 | 飞书 |
+|---|---|---|
+| key（HMAC 的密钥） | `secret` | `"{timestamp}\n{secret}"` |
+| message（被签内容） | `"{timestamp}\n{secret}"` | **空** |
+| timestamp 单位 | **毫秒** | **秒** |
+| 拼在哪 | **URL query**（`&timestamp=…&sign=…`） | **JSON body** 的 `timestamp`/`sign` |
+| 结果编码 | Base64 后再 **urlencode** | Base64 |
+| 出错码 | `errcode 310000 invalid signature` | `code 19021 sign match fail` |
+
+实现见 `core/notifier.py` 的 `DingtalkAdapter.sign_request` / `FeishuAdapter.sign_request`；
+两家的算法都用官方示例代码对拍过（钉钉逐字节一致，含 urlencode）。
+
+**字段一律渲染成 `> **字段**：值` 引用行，不用 Markdown 表格**——企业微信/钉钉的 markdown
+子集不支持表格，表格会原样吐出来。
+
+通用 JSON 的占位符：`{{event}} {{title}} {{summary}} {{ts}} {{level}} {{markdown}}
+{{fields}} {{fields_json}} {{hook_name}} {{field.<字段名>}}`。
+替换值按 JSON 字符串转义，所以标题里带引号/换行也不会打坏请求体。Slack 直接写
+`{"text":"{{markdown}}"}` 就行。
+
+**格式相关的提示文案（URL 示例/说明、密钥叫什么、限流上限）都挂在适配器上**
+（`BaseAdapter.url_hint/url_help/secret_label/secret_help/limit_help`），界面按当前格式渲染、
+切格式即时更新——新增格式时把这些一起填上，别把某个平台的说明写死在页面上。
+
+**再加新格式**：写一个 `BaseAdapter` 子类（`render` + 可选 `sign_request`）并把元信息
+（`byte_limit`/`ok_codes`/`limit_default`/`url_hint`/`url_help`/`secret_*`/`limit_help`）填全，
+然后注册进 `ADAPTERS` —— 界面上的下拉项与提示文案会自动跟着出来，**不用改前端**。
+`PLANNED_FORMATS` 是"还没实现、下拉里置灰"的占位表（目前为空）。
+
+---
+
+## 6. 防打爆（四层）
+
+100 台设备同时失败 = 100 条消息，群里会被刷到静音——**刷屏会让通知彻底失效**。所以：
+
+| 层 | 机制 | 默认 |
+|---|---|---|
+| L1 聚合 | 同 webhook、同事件、同聚合键（如 `job_id`）在一个窗口内合并成一条，保留前 3 个样本 | 30s（**事件声明 `agg_window=0` 的一律立即发**，如批次结束 / 服务启停 / 备份恢复） |
+| L2 限流 | 每 webhook 一个令牌桶 | 18 条/分（企业微信硬限 20，留余量） |
+| L3 折叠 | 被限流的事件**不丢弃**，压成一条「被限流折叠 N 条」摘要 | 最多 60s 一条 |
+| L4 背压 | 有界队列（event 2000 / send 1000），满了丢弃并计数 | 溢出会告警一次 |
+
+取舍写明白：**失败通知最多延迟一个聚合窗口（默认 30s）**，换来群不被刷屏。
+
+窗口口径（代码在 `core/notifier.py` 的 `notify()`）：
+
+- 事件自己写了 `agg_window=0` → **立即发**，不受 webhook 的窗口影响；
+- 其余事件 → 用该 webhook 配置的 `agg_window`（它表示"这个群最多等多久合并"）。
+
+「样本」行只在**真的合并了多条**（>1）时出现，且按**设备**维度写（`cs1 · 超时`）——
+合并多台设备时写任务名每条都一样，等于没写。
+
+> ⚠️ 保存通知配置（`save_config`）会清空**待发聚合**与限流令牌桶。清理 hook 时
+> 顺手丢掉的正是还没到窗口的聚合事件——排障时别把它当成"没发"。
+
+---
+
+## 7. 开发：给新功能加通知
+
+1. 在 `core/notify_events.py` 的 `EVENTS` 里加一条 `_e("模块.对象.动作", "中文标签",
+   "分类", ["字段1", "字段2"], "什么时候发", agg_window=…, recommend=…)`
+2. 在触发点调 `notifier.notify("模块.对象.动作", 字段1=…, 字段2=…)`
+   —— **放在所有 `with self._lock` 之外**，且不要改变原有 `return` 的顺序
+3. 把事件补进本文档 §3 的表格
+
+约定：
+
+- `notify()` **不阻塞、不抛异常、不碰 DB**——这是硬约束，别在它里面加 HTTP 或查库
+- 事件的 `fields` 是前端字段表与模板占位符的白名单，只写真正有用的
+- 高频事件（每台设备/每次尝试都会发生的）把 `agg_window` 设大一点或 `recommend=False`
+
+---
+
+## 8. 排障
+
+| 现象 | 看哪里 |
+|---|---|
+| 完全没收到 | ① 全局开关是不是关了（列表页「启用通知」）② 该 webhook 是否启用 ③ 事件勾了没（`task.device.failed` 是**单设备最终失败**，不是每次尝试） |
+| 收到但内容不全 | 消息被 4096 字节截断了（末尾有「…(已截断)」）；把 `cause` 之类长字段在事件侧截短 |
+| 只在群里看到「被限流折叠」 | 短时间内同类事件太多，触发了 L2/L3；调大该 webhook 的限流值（企微上限 20）或调大聚合窗口 |
+| 失败原因 | 后台「通知」页的**发送记录**（内存，重启清空）或 `logs/notify.log`（完整历史）。`errcode 45009`=企微限流、`93000`=Webhook 地址无效、`HTTP 200 + errcode≠0` **也算失败** |
+| 配置坏了 | 服务照常启动（启动日志有 error），通知静默不发；在后台删掉坏配置或直接改 `app_meta.notify_webhooks` |
+
+---
+
+## 9. 已知限制
+
+- 发送记录在**内存**（最近 200 条，重启清空）；持久历史只有 `logs/notify.log` 文本
+- **不支持自定义 webhook 请求头**（`headers` 字段留着但界面没暴露）——需要的话说一声
+- 只做 http/https，**不做内网 IP 黑名单**（内网自建 webhook 是合法用法），但禁止重定向
+  （`allow_redirects=False`）
+- `system.backup.restored` 是**重启后**才发（恢复本身就是重启生效的）

doc/README.md

@@ -13,16 +13,19 @@
 | [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 概念、21 种步骤全表、公共巡检、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
-| [MCP.md](MCP.md) | **MCP 手机控制手册**：19 个 `de_*` 工具用法、写操作门控、坐标换算、接入示例 | 接入方、数字员工 |
+| [MCP.md](MCP.md) | **MCP 手机控制手册**：20 个 `de_*` 工具用法、写操作门控、坐标换算、接入示例 | 接入方、数字员工 |
 | [MCP_DESIGN.md](MCP_DESIGN.md) | **MCP 设计文档**：边界划分、错误码、白名单/审计设计、演进方向 | 平台开发者 |
 | [AI_CONSOLE.md](AI_CONSOLE.md) | **AI 控制台**：会话/SSE、经验库、动作库、巡检、Markdown 渲染、推理链、token 统计 | 使用者、平台开发者 |
-| [AI_TASK_GEN.md](AI_TASK_GEN.md) | **AI 建任务**：设计稿与里程碑（P0 未实现，属规划） | 平台开发者 |
+| [AI_TASK_GEN.md](AI_TASK_GEN.md) | **AI 建任务**：AI 自己在真机探索 → 写出可调度任务 → 人工确认入库（P0 已实现；契约与红线） | 平台开发者、使用者 |
+| [NOTIFY.md](NOTIFY.md) | **通知 / Webhook**：事件目录、企业微信/通用 JSON 适配、防刷屏（聚合/限流/折叠）、排障、怎么加事件 | 运维、平台开发者 |
+| [DEVICE_AGENT.md](DEVICE_AGENT.md) | **设备端 Agent 接口契约**：应用商店的设备专用接口（清单/下载/上报）、adb 指令协议、版本约定 —— 与设备端 APK 仓库共享的契约 | 设备端开发者、平台开发者 |
 | [DEPLOY.md](DEPLOY.md) | **部署与运维**：环境准备、生产容器、数据备份导出/导入、故障排查 | 运维、部署者 |
 | [DEVELOPMENT.md](DEVELOPMENT.md) | **开发手册**：git 流程、技术红线、本地开发与调试、常见开发任务、文档同步约定 | 所有开发者 |
 | [STF_REMOVAL.md](STF_REMOVAL.md) | **历史记录**：摘除 OpenSTF 的迁移过程（阶段 0-3） | 追溯背景时参考 |
 | [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) | 给 StaffDeck 数字员工的知识库（MCP 接入/工具/约定/红线） | 外部 AI 接入方 |
 | [staffdeck/JOB_SPEC.md](staffdeck/JOB_SPEC.md) | 数字员工岗位说明（岗位描述/看板摘要/执行约束） | 外部 AI 接入方 |
+| [research/U2_ELEMENT_SELECTORS.md](research/U2_ELEMENT_SELECTORS.md) | **元素选择器研究**：「点不到按钮」的根因（序号型选择器随界面变形而错位）与语义选择器解法 | 写任务/抓元素的开发 |
 | [backlog/TODO.md](backlog/TODO.md) | 已确认但暂缓的待办（含已知问题） | 所有开发者 |
 
 项目根目录的 [README.md](../README.md) 是**项目总览与快速上手**（面向第一次接触项目的人），细节都在本目录。
@@ -56,6 +59,7 @@
 | 任务类型 / 步骤 schema | [TASK_DEV.md](TASK_DEV.md) |
 | 常驻线程 / 进程装配 | [ARCHITECTURE.md](ARCHITECTURE.md) §线程与并发 |
 | MCP 工具 | [MCP.md](MCP.md) + [MCP_DESIGN.md](MCP_DESIGN.md) |
+| 设备端 Agent（APK） | [DEVICE_AGENT.md](DEVICE_AGENT.md) |
 | 对外接入约定 | [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
 | 暂缓项 / 已知问题 | [backlog/TODO.md](backlog/TODO.md)（完成时移出并同步相关文档） |
 

doc/TASK_DEV.md

@@ -10,8 +10,8 @@
 
 - [1. 核心概念](#1-核心概念)
 - [2. 通用步骤任务 generic_steps](#2-通用步骤任务-generic_steps)
-- [3. 18 种步骤全表](#3-18-种步骤全表)
+- [3. 21 种步骤全表](#3-21-种步骤全表)（含 [3.1 步骤默认值与动作录制](#31-步骤默认值与动作录制任务--动作配置)）
-- [4. 容器步骤与公共参数](#4-容器步骤与公共参数)
+- [4. 容器步骤与公共参数](#4-容器步骤与公共参数)（含 [4.5 公共巡检](#45-公共巡检任务级独立于步骤画布)）
 - [5. 选择器与元素定位](#5-选择器与元素定位)
 - [6. 自定义动作](#6-自定义动作)
 - [7. 步骤编辑器（前端）](#7-步骤编辑器前端)
@@ -108,7 +108,7 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 
 ---
 
-## 3. 18 种步骤全表
+## 3. 21 种步骤全表
 
 > 参数与默认值以 `tasks/generic/task.py` 为准；前端 `STEP_LIB`（`static/admin/editor.js`）负责在编辑器里呈现这些字段。
 
@@ -118,20 +118,97 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 | 2 | `stop_app` | 结束 App | `package` | — | — | `app_stop`（`am force-stop`，下次打开是冷启动） |
 | 3 | `screen_on` | 亮屏 | — | — | — | `d.unlock()`（息屏时唤醒并滑动解锁） |
 | 4 | `screen_off` | 息屏 | — | — | — | `d.screen_off()` |
-| 5 | `keep_screen` | 保持亮屏 | `mode`("on") | — | — | `mode="off"` → 恢复自动息屏；否则 `svc power stayon true`（充电时常亮，适合长任务） |
+| 5 | `keep_screen` | 保持亮屏 | `mode`("on") | — | — | `mode="off"` → 恢复自动息屏；否则**把系统息屏超时顶到最大**（`screen_off_timeout=2147483647`）+ `svc power stayon true` + 唤醒一次。⚠️ 只发 `svc power stayon true` 对**没插充电器**的设备（走 WiFi 的那些）**完全无效**——它管的是"充电时屏幕常亮"，2026-09-14 就是因此被反馈"保持亮屏没用" |
 | 6 | `key_event` | 按键 | `key`("back") | — | — | `d.press(key)`；**值直传，无白名单校验** |
-| 7 | `swipe` | 滑动 | `direction`("up") | `duration_min`(0.25)、`duration_max`(0.50) | — | 时长取随机值；up = 中轴从 0.8h → 0.2h（down 反向，left/right 同理）；**非法 direction 静默不滑** |
+| 7 | `swipe` | 滑动 | `direction`("up") | `duration_min`(0.25)、`duration_max`(0.50)、`distance_ratio`(0.6)、`jitter`(0.15)、`humanize`(True) | — | **默认拟人**：弧线轨迹 + 起止点/幅度/时长抖动 + 本设备手速偏好（见 §8.4）；`humanize:false` 还原老的「正中直线」；`jitter:0` 时位置/幅度不抖（时长仍随机）；**非法 direction 静默不滑** |
-| 8 | `swipe_until` | 滑动直到元素 | `selector_type`、`selector_value` | `direction`("up")、`max_swipes`(8)、`click_when_found`(True) | — | 每轮滑动后 sleep 0.5s；命中即（可选）点击并返回 True；**只有 `direction="down"` 才是向下滑**，其余按上滑 |
+| 8 | `swipe_until` | 滑动直到元素 | `selector_type`、`selector_value` | `direction`("up")、`max_swipes`(8)、`click_when_found`(True)、`duration_min`(0.25)、`duration_max`(0.50)、`distance_ratio`(0.6)、`jitter`(0.15)、`humanize`(True) | — | 每次滑动都重新生成轨迹（同 §8.4）；每轮滑动后随机停 0.35~0.75s；命中即（可选）点击并返回 True；**只有 `direction="down"` 才是向下滑**，其余按上滑 |
 | 9 | `click` | 点击元素 | `selector_type`、`selector_value` | `wait_timeout`(2) | — | xpath 用 `wait(timeout)`，其它选择器用 `exists(timeout)`；`wait_timeout=0` 为立即判断。**空选择器只告警** |
 | 10 | `click_xy` | 点击坐标 | — | `x`(50)、`y`(50) | — | **屏幕百分比**（0-100，会夹取），50/50 = 屏幕中心。无选择器时的兜底，**最脆的方式** |
 | 11 | `long_click` | 长按元素 | `selector_type`、`selector_value` | `duration`(1.0)、`wait_timeout`(2) | — | 先等元素出现再 `long_click` |
 | 12 | `wait_el` | 等待元素 | `selector_type`、`selector_value` | `timeout`(10) | — | 等元素出现（条件等待，优于固定 `wait`） |
 | 13 | `input_text` | 输入文字 | — | `mode`("random")、`texts`("你好\n有趣\n支持")、`fixed_text`("")、`clear_first`(True) | — | `mode="fixed"` 用 `fixed_text`，否则从 `texts` 按行随机选一条；**只负责输入，不负责定位输入框**（要先 click 输入框） |
 | 14 | `clipboard` | 剪贴板注入 | `text` | `paste`(True) | — | 走 ClipInject 通道（绕开 Android 10+ 后台写剪贴板限制）；`paste=true` 时再触发一次粘贴 |
-| 15 | `wait` | 等待 | — | `min`(1.0)、`max`(3.0) | — | 随机时长；**分片 sleep**（每 ≤0.5s 检查停止/超时），可被抢占打断 |
+| 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 停止位，后续步骤不再执行，任务记成**被停止而不是失败**（不触发重试） |
+| 21 | `gesture` | 录制手势 | `points`（录出来的） | `speed`(1.0) | — | **纯录制回放**：把录下的轨迹点列 `[[x,y,t_ms],…]` 按原路径与时长交给设备插值，不做弧线/抖动/手速加工。与「滑动」是两套东西，见 §3.2 |
+
+### 3.2 录制手势：**纯录制、纯回放**（`core/gesture.py`）
+
+「滑动」和「录制手势」是**两套东西**，别混：
+
+| | `swipe` 步骤 | `gesture` 步骤 |
+|---|---|---|
+| 存什么 | 方向 + 幅度 + 时长区间 | **完整轨迹点列** `[[x,y,t_ms], …]` |
+| 回放时 | 每次重新生成（弧线/抖动/本设备手速） | **照录制的路径与时长**，不做任何修饰 |
+| 适合 | 通用滑动，换设备也能用 | 你亲手划的、要求一模一样的手势 |
+
+**为什么录制的不能走滑动那套**：滑动是"参数化"的——它按方向+幅度重新生成轨迹并叠
+拟人抖动，录下来的路径就被丢掉了。要"完全按我划的重放"，就只能存点列、回放点列。
+
+**两个录制来源**（都在「录制手势」步骤的卡片上）：
+
+| 来源 | 做法 | 特点 |
+|---|---|---|
+| ● 手机上录 | 点开始后**用手指在真机上划**，后端读 `getevent` 抓真触屏 | 最真实：录的是人手的原始轨迹。合成注入不会出现在真触屏节点上（实测），所以录到的只有人手 |
+| ● 网页上录 | 在弹窗画面里按住鼠标拖，前端按 8ms/3px 采样 | 不用碰手机，但有鼠标的机械感 |
+
+要点与坑：
+
+- **录制前必须唤醒设备**：息屏时 u2 抓 UI 树会从 3 秒退化到 **65 秒**（实测），截图还是黑的。
+  前端在选好设备后会自动调一次亮屏（`/api/device/screen_all`）。
+- **回放是一次调用**（`d.swipe_points(points, duration)`），不是逐点注入：实测这台设备
+  **单次触摸注入 RPC ≈190ms**，逐点回放 20 个点要 3.8 秒，比录的手势慢一个数量级。
+  所以只能让设备自己插值——"时间"靠**点密度**还原（手指慢的地方采样点更密）。
+- 回放点数**抽稀到 40 个**（`MAX_REPLAY_POINTS`）：这台设备每个点开销大，40 是画质/耗时折中；
+  首尾点一定保留。
+- 轨迹是**屏幕绝对像素**：换分辨率不同的设备可能偏，同型号/同分辨率最稳。
+- 点列存在步骤 JSON 里（一条 0.5s 的手势约 25 点 / 400 字节），不新建表。
+
+### 3.1 步骤默认值与动作录制（任务 → 动作配置）
+
+**步骤默认值**：新建步骤时预填的参数（`core/step_defaults.py`，存 `app_meta.step_defaults`）。
+在「任务 → 动作配置」页改，**只影响之后新建的步骤**，已有步骤里的参数不动。
+
+覆盖范围：`swipe`（方向/时长区间/幅度/抖动/拟人）、`click`（等待超时）、
+`long_click`（长按时长/超时）、`wait`（时长区间）、`key_event`（按键）、
+`input_text`（模式/候选文案/是否清空）。
+
+三条实现口径：
+
+- **只存与出厂值不同的字段**——以后调出厂默认时，没配过的字段能跟着更新；
+- 字段**白名单 + 范围夹取**（`SPEC`）：越界值夹到边界、非法值直接丢弃，
+  不会把手改 JSON 塞进来的脏值带进任务；
+- 前端 `_makeStep` 用 `STEP_LIB` 出厂值打底，再用这里的默认值覆盖，
+  `/api/step_defaults` 在打开「任务」Tab 时加载一次。
+
+**动作录制**（`static/admin/recorder.js`）：在设备画面上点/划/按键/输入，
+自动翻译成步骤。两个入口：
+
+| 入口 | 模式 | 产出 |
+|---|---|---|
+| 动作配置页「● 录制动作」 | `action` | 录完存成**自定义动作**（进动作库，拖进任何任务画布） |
+| 步骤编辑器里滑动那一步的「● 录制手势」 | `gesture` | 只取最后一个手势，**回填当前滑动步骤**的方向/幅度/时长 |
+
+翻译规则：
+
+| 你做的 | 记成 | 依据 |
+|---|---|---|
+| 点一下 | `click`（选择器） | 从当前元素树里取**包含该点的最小可点击元素**，用它的 `suggested` 选择器 |
+| 点一下（没命中元素） | `click_xy` | 退化成屏幕百分比坐标 |
+| 按住划一下 | `swipe` | 方向（dx/dy 谁大取谁）、幅度（划距 ÷ 屏高/宽）、时长（你按住的毫秒数） |
+| 停顿（间隔 ≥1s） | `wait` | 真实间隔 ±15%，可在录制器里关掉「记录停顿」 |
+| 按键 / 输入 | `key_event` / `input_text` | 输入文字按**原样**记 `fixed_text`（不是随机候选） |
+
+实现要点（改之前先看）：
+
+- 画面与元素树走 **`/api/uiauto/snapshot` 一次取齐**（截图+元素背靠背取，避免"框落在旧位置"）；
+  **每次操作后自动刷新**，所以下一次点击能用到最新的树。
+- 录制器**只负责翻译**，真正执行仍走 `/api/screen/{tap,swipe,key,text}`——和设备大屏同一套接口。
+- 录到的步骤在列表里可上移/下移/删除；存成动作走现有 `POST /api/custom_actions`（不新增表）。
 
 ---
 
@@ -149,7 +226,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 +251,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` 支持的值
@@ -206,22 +346,33 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 
 历史实现写了前者，导致同 id 多实例（如底部导航 4 个 tab）时 `[2..n]` 全部失配。现在：
 
-- `core/uiauto_helper.py` 生成的都是 `(//*[@…])[k]` 形式（唯一匹配时才省略序号）
+- 执行器 `tasks/generic/task.py` 的 `_norm_legacy_xpath` 会**自动纠正**旧任务里的 `//*[@x][k]` 写法（仅前缀，类名/位置步进不受影响）
-- 执行器 `tasks/generic/task.py` 的 `_norm_legacy_xpath` 会**自动纠正**旧任务里的 `//*[@x][k]` 写法（仅前缀，`.../FrameLayout[2]` 这类兄弟序号不受影响）
+- 抓取器生成 `(…)[k]` 前**先做语义消歧**（见 §5.4），序号型只是最后的退路
 
-⚠️ **序号型选择器仍然脆弱**：它依赖"抓取那一刻该属性有 ≥k 个实例"。界面不同（如 App 还在闪屏页）就会失配——优先选唯一 id 或文字。
+⚠️ **序号型选择器仍然脆弱**：它依赖"抓取那一刻该属性有 ≥k 个实例"。界面不同（如 App 还在闪屏页）就会失配——优先选带**文字**的元素，抓取器会自动产出语义选择器。
 
 ### 5.4 抓取器给的建议选择器
 
-`GET /api/uiauto/elements` 返回的元素带 `suggested`，生成优先级：
+`GET /api/uiauto/elements`、`GET /api/uiauto/snapshot` 返回的元素都带 `suggested`，生成优先级：
 
-1. 有 `resource-id` → `//*[@resource-id="v"]`（重复时带序号 `(…)[k]`，并标 `indexed:true` + 出现次数）
+1. 有 `resource-id` → `//*[@resource-id="v"]`；无 id 但有 `text`/`content-desc` 同理
-2. 无 id 有 `text` → `//*[@text="v"]`
+2. 该属性值**全树有多个**时，**先用第二个属性把目标单独圈出来**（语义选择器，标 `semantic:true` + `via`）：
-3. 无 id/text 有 `content-desc` → `//*[@content-desc="v"]`
+   `//*[@resource-id="v" and @text="我"]`。抖音底部导航同 id 的几个 tab 靠这个解决——
-4. 都没有但有"最近的有属性祖先" → `{祖先}/{Class}[n]` 结构路径
+   灰度版 tab 数量会变（4 个 ↔ 3 个），序号必然错位，文字不会
-5. 连祖先都没有 → `//{class_path}`（标 `broad:true`，脆弱，前端会提示）
+3. 两个属性组合仍分不开（列表里同 id 同文字）→ 才退回序号 `(…)[k]`（标 `indexed:true` + `occ`/`total`，前端打**黄标 ⚠ 序号**）
+4. 都没有属性、但有"最近的有属性祖先" → `{祖先}/*[@class="android.widget.ImageView"][n]`
+5. 连祖先都没有 → `//hierarchy/*[i]/*[j]`（按**子节点位置**逐层，标 `broad:true`，脆弱、前端会提示）
 6. 类名也是空 → 标 `invalid:true`（提示无法生成可靠选择器）
 
+**两个必须记住的 XPath 坑**（都实测踩过）：
+
+- **dump 的 XML 标签名一律是 `<node>`**，`class` 在 `@class` 属性上。所以结构步进只能写
+  `*[@class="…"]` 或位置 `*[i]`；写成 `//FrameLayout[1]` 这种"类名当标签名"的路径**永远零命中**
+  （2026-09-13 修：248 个元素里曾有 26 条死选择器）
+- **同级节点的 `index` 属性会重复**（状态栏/内容区/导航栏三个兄弟的 `index` 全是 `0`），
+  兜底结构路径要按**位置** `*[i+1]` 定位，不能按 `@index`
+
+
 ### 5.5 抓取与验证（编辑器里的两个按钮）
 
 - **「▶ 点一下」**：按元素 `bounds` 中心在设备上真点一次（`POST /api/screen/tap`，`snap=1` 自动吸附到可点元素中心），返回吸附结果并刷新截图——确认位置是否可达
@@ -337,9 +488,9 @@ class MyTask(BaseTask):
     def get_action_class(cls, action_type):
         return None
 
-    def create_worker(self, serial, params):
+    def create_worker(self, serial, params, ctx=None):
         merged = {**DEFAULT_PARAMS, **(params or {})}
-        return MyWorker(serial, params=merged)
+        return MyWorker(serial, params=merged, ctx=ctx)
 ```
 
 ```python
@@ -358,8 +509,45 @@ from .myapp import task      # ← 新增
 
 ### 8.3 签名约定
 
-- `BaseWorker.__init__(self, serial, params=None, daemon=True)`
+- `BaseWorker.__init__(self, serial, params=None, daemon=True, ctx=None)`
-- `Task.create_worker(self, serial, params)` —— **不要带 `stf_client` / `stf` 形参**（STF 已摘除，历史签名已清理）
+- `Task.create_worker(self, serial, params, ctx=None)` —— **不要带 `stf_client` / `stf` 形参**（STF 已摘除，历史签名已清理）
+- `ctx` 是本次运行的上下文（`run_id` / `job_id` / `job_name` / `device_name`），由
+  `TaskManager._run_with_retry` 传入；**只用于结构化记录**（如步骤明细
+  `core/step_log.py`），不参与业务逻辑。不关心就原样透传给 `BaseWorker` 即可。
+
+### 8.4 拟人化：滑动与设备节奏（`core/humanize.py`）
+
+自动化最容易被识别的地方不是"慢"，是**每次都一模一样**：同一坐标、同一时长、
+13 台设备整齐划一地做同一个动作。`core/humanize.py` 从两个层次解决：
+
+| 层次 | 机制 | 谁决定 |
+|---|---|---|
+| **每次不同** | 起点/终点/幅度/时长抖动，弧线方向随机 | 每次调用现算（`jitter` 控制幅度，0~0.4） |
+| **每台设备不同** | 手速(0.82~1.32)、幅度(0.86~1.16)、弧度、常用横坐标(±9%屏宽)、停顿(0.80~1.35) | `crc32(serial)` 播种，**同设备恒定** |
+
+用法（同步步骤里用）：
+
+```python
+from core import humanize
+humanize.swipe(d, "up", serial=self.serial, duration_min=0.25, duration_max=0.4,
+               distance_ratio=0.6, jitter=0.15, humanize=True)
+humanize.pace(self.serial, 5.0, enabled=True)   # wait 步骤的"按设备节奏微调"
+```
+
+要点与坑：
+
+- **性格稳定、抖动随机**：稳定才像"不同的人"，随机才不像"机器"。性格按 **serial**
+  而不是设备名播种——改名不改风格，换地址会换风格（地址代表"这一台"）。
+- 内部用**独立的 `random.Random` 实例**，不碰全局 `random`：worker 是多线程的，
+  全局 RNG 的取值顺序会被别的线程打乱，性格就串味了。
+- **屏幕尺寸别用 `d.info`**：部分设备上一次要 **14 秒**（实测），改用
+  `humanize.screen_size(d, serial)`——它走 `d.window_size()`（同设备 0.6s）并缓存
+  120 秒。这让"加了弧线反而更快"成为可能。
+- **曲线点数固定为 4**（5 个点）：`d.swipe_points` 在慢设备上**每多一个点约多 1 秒**
+  （实测 2 点 1.4s / 6 点 6.0s / 10 点 10.6s），而设备自己会在点之间插值几十步，
+  4 个点的贝塞尔已经足够弯。**不要为了"更平滑"把点数调大。**
+- `swipe_points` 抛异常时自动退回直线 `d.swipe`（老 agent 兜底），日志会留一行 warning。
+- 想关掉：步骤参数 `humanize: false`（完全还原老行为）；想调轻：`jitter: 0.05`。
 
 ---
 

doc/backlog/TODO.md

@@ -32,14 +32,6 @@
 - **涉及**：`web_server.py`（注册钩子）+ 需要回归所有写接口（前端、脚本、MCP 的 `platform_client` 都已带 token，风险点是第三方直接调 API）。
 - **验收**：注册后所有写接口在缺 token 时返回 403，且前端/MCP 全链路正常。
 
-### A4. 路由回归脚本在 Windows 上不可用
-
-- **现象**：`python scripts/regression_test.py` 直接报 `AttributeError: module 'signal' has no attribute 'alarm'` 退出。
-- **原因**：脚本用了 Unix 专有的 `signal.alarm`（第 29 行），docstring 里的示例路径也是 `.venv/bin/python`。
-- **影响**：本机（Windows）开发时没有"一条命令扫全接口 500"的手段——A1/A2 这类 import 遗漏本可被它第一时间发现。
-- **涉及**：`scripts/regression_test.py`（把 `signal.alarm` 换成跨平台超时，或 `hasattr` 守卫）。
-- **验收**：Windows 与 Linux 都能跑；能扫出 A1。
-
 ### A5. 前端 `--card-line` 变量未定义
 
 - **现象**：AI 控制台的会话/经验/动作模态框边框失效（`border:1px solid var(--card-line)` 解析为无效值）。
@@ -74,7 +66,7 @@
   - `ANDROID_ADB_SERVER_ADDRESS/HOST/PORT` 会被 `.env` 注入 `os.environ`，**adb 客户端**据此把所有调用指向 220；`ANDROID_ADB_SERVER_HOST` 是非标准键（adb 不认）。
   - 期望：在配置速查里写明该行为与取舍，或本地去掉这三行改走本机 adb。
 
-- [ ] **`.gitignore` 漏项**：`data/mcp_audit.log` 与 `data/uiauto.pid` 未被忽略（`git status` 会显示为未跟踪）；`data/apks/` 目录无占位文件。
+- [ ] **`.gitignore` 漏项**：`data/mcp_audit.log` 已补（`data/*.log`，2026-09-13）；**`data/uiauto.pid` 仍未忽略**（`git status` 会显示为未跟踪）；`data/apks/` 目录无占位文件。
 
 - [ ] 220 的 Tailscale / adb server(5037) 可达性巡检（曾出现连不通超时）。
 
@@ -94,7 +86,7 @@
 
 - [ ] **序号型 XPath / 界面就绪 的防呆**（2026-09-10 db03f16e 案例）
   - 背景：`(//*[@resource-id="…"])[6]` 依赖"抓取那一刻该属性有 ≥6 个实例"；运行时界面不同（App 仍在闪屏页）→ 序号必然失配。
-  - 期望：① `open_app` 提示勾选「等待首页」；② 抓取器对**带序号**的选择器加醒目提示；③ 抓取弹窗提醒"请先把设备停在任务运行到该步时的同一界面再抓"。
+  - 期望：① `open_app` 提示勾选「等待首页」；② ~~抓取器对**带序号**的选择器加醒目提示~~（✅ 2026-09-13 已完成，且更进一步：抓取器**优先产出语义选择器**再去掉序号，见 [research/U2_ELEMENT_SELECTORS.md](../research/U2_ELEMENT_SELECTORS.md) §五）；③ 抓取弹窗提醒"请先把设备停在任务运行到该步时的同一界面再抓"。
   - 涉及：`core/uiauto_helper.py`、`static/admin/editor.js`、`tasks/generic/task.py`、`doc/TASK_DEV.md`。
 
 - [ ] 自定义动作支持 `action_ref` 引用型节点（现状：拖入画布会**展开成 group**，改动需同步执行器 + 编辑器）。
@@ -104,7 +96,12 @@
 ## D. AI 控制台 / 经验与动作
 
 - [ ] 「🧠 经验库 / 🎬 动作库」合为一个面板（标签页切换）。
-- [ ] AI 建任务 P0：平台级 MCP 工具（只读清单 `task_types/groups/pool` + `submit_task(draft)` 校验）+ 把**动作库**当作 generic_steps 的预制件复用（见 [AI_TASK_GEN.md](../AI_TASK_GEN.md) §9）。
+- [x] ~~AI 建任务 P0~~（✅ 2026-09-13：独立子页「AI 建任务」+ `submit_task` 校验 + 草稿预览/预填；✅ 2026-09-14 补齐「直接创建」`POST /api/agent/task_draft/create`、草稿→经验/动作沉淀、MCP `de_snapshot`。见 [AI_TASK_GEN.md](../AI_TASK_GEN.md) §10）。
+  - 仍未做：平台级 MCP 只读清单（`task_types/groups/pool`）、把**动作库**当 generic_steps 预制件复用、探索成本控制。
+- [ ] `mcp_server/platform_client._login()` 对"登录失败"不设防：平台把登录页当 200 返回时会被当成
+  登录成功，后续所有调用都拿不到 JSON，最终只报含糊的 `platform_unavailable`（2026-09-14 排查
+  `de_snapshot` 时踩到：现场进程没带 `MCP_PLATFORM_PASS`）。应校验响应内容/最终 URL，并明确报
+  "平台账号或密码不对"。
 - [ ] 新增 MCP `de_screen_text`（文本化看屏：前台包名 + screen_state + 可点元素文本 + OCR），并把操作纪律写进工具 description。
 - [ ] 经验召回改进：现为 bigram + `ORDER BY hits`（候选只看 top50、hits 对所有命中行回写 → 马太效应）；改为对称相似度 / 更合理候选集，`hits` 仅在真正注入时 +1。
 - [ ] 经验/动作入库依赖模型蒸馏成功：加失败重试与可视化观测（现在只在日志里）。
@@ -129,3 +126,7 @@
 - [x] 监控页任务卡去掉「编辑/删除」，只留执行/停用 + 显示**覆盖设备**。
 - [x] 备份覆盖清单补 `agent_action` / `app_meta` + 导出/导入双向自检。
 - [x] AI 控制台：Markdown 渲染、推理链可折叠、token 用量显示。
+- [x] 路由回归脚本 Windows 可用（2026-09-13：`signal.alarm` 加 `hasattr` 守卫）+ 新增安全闸：
+  配置或目标库被标为 `prod` 时**拒绝运行**（脚本会发真实写请求，不能拿生产数据做实验）。
+- [x] 数据库从 SQLite 迁到 MySQL：连接层多环境配置 + 防混库校验、schema 收敛到 ORM metadata、
+  备份/恢复改为「SQLite 归档 + 单事务整库替换」、迁移脚本（2026-09-13）。

doc/research/U2_ELEMENT_SELECTORS.md

@@ -0,0 +1,174 @@
+# 元素选择器研究：为什么"点不到按钮"（2026-09-13）
+
+> 背景：任务步骤（`click` 等）频繁出现"元素明明在屏幕上却点不到"。用户怀疑是
+> 任务执行用的 u2 与元素抓取用的 uiautodev 两条通道不一致，要求研究。
+> 分支：`research/raw-u2-elements`。
+
+---
+
+## 一、先否掉一个假设：两条通道**并不**冲突
+
+| | 用的东西 | 连接方式 |
+|---|---|---|
+| 任务执行（点击/输入…）| 原生 `u2.connect(serial)` | 直连设备的 uiautomator2 server |
+| 元素抓取（编辑器按钮）| `uiautodev` 服务（localhost:20242）→ `/api/android/{serial}/hierarchy` | 它自己的连接 |
+
+实测（同一设备、同一屏、同一时刻，两边各 dump 一次）：
+
+| 对比项 | u2 | uiautodev |
+|---|---|---|
+| 节点总数 | 330 | 330 |
+| `id/0qf`（抖音底部 tab） | 3 | 3 |
+| `id/content_layout` | 5 | 5 |
+
+**逐项一致** —— 两个通道给出的元素树是同一份（都是设备的 UiAutomation dump）。
+所以"抓取看到的和执行看到的不是一回事"这个假设**不成立**。
+
+> 顺带纠正一处过时注释：`core/uiauto_helper.py` 说"uiautodev 归一化浮点坐标无法换算像素"。
+> 实际上 uiautodev 的节点里 **`rect` 就是像素**（`{x,y,width,height}`），`bounds` 才是
+> 归一化的 0~1 浮点。要用像素直接用 `rect` 即可。
+
+---
+
+## 二、真正的原因：**序号型选择器**（`(…)[k]`）会随界面变形而错位
+
+复现（192.168.20.100，抖音 v40.4.0）—— 进「我」页面，底部导航 dump 出来是：
+
+```
+[1] text='首页'  bounds=[38,1484][106,1530]
+[2] text='消息'  bounds=[470,1484][538,1530]
+[3] text='我'    bounds=[631,1484][665,1530]
+```
+
+只有 **3 个** `0qf`。而任务里的步骤写的是：
+
+```
+(//*[@resource-id="com.ss.android.ugc.aweme:id/0qf"])[4]    ← 第 4 个，根本不存在
+```
+
+**必然点空** —— 日志里表现为 `click 未找到元素`，而界面上那个「我」明明就在那儿。
+
+### 为什么有的设备是 4 个？
+
+抖音底部的「朋友」tab 是**灰度功能**：有的账号/设备有（首页/朋友/消息/我 = 4 个），
+有的没有（首页/消息/我 = 3 个）。同一个序号 `[4]`：
+
+- 4 个 tab 的设备 → 点到「我」（碰巧对）
+- 3 个 tab 的设备 → 点空（或点到别的东西）
+
+**同一个选择器在不同机器上语义不同**，这是"时好时坏"的根源。
+
+---
+
+## 三、解法：用**语义选择器**，不要依赖序号
+
+实测有效（同一台 3-tab 设备）：
+
+```python
+# ✗ 序号型：依赖"底部有几个 tab"
+(//*[@resource-id="com.ss.android.ugc.aweme:id/0qf"])[4]
+
+# ✓ 语义型：同一个 id，用文字限定 —— 不管有几个 tab 都对
+//*[@resource-id="com.ss.android.ugc.aweme:id/0qf" and @text="我"]
+```
+
+验证：命中（bounds 落在「我」上）→ 点击 → 进入我页面 → `jy-`（切换按钮）出现 ✓
+
+同类可用限定条件（按优先级）：
+
+1. `@text="…"` —— 文字最稳（tab 名、按钮名）
+2. `@content-desc="…"` —— 无文字但有描述（如 `首页，按钮`）
+3. `@resource-id="…"` —— **唯一**时直接用
+4. 组合：`//*[@resource-id="x" and @text="y"]` —— **同一 id 多实例时的最佳解**
+5. 结构路径（`…/FrameLayout[2]`）—— 最后手段，最脆
+6. `(…)[k]` —— **只在上面都不行时**
+
+---
+
+## 四、抓取弹窗"老是错位"的根因 —— **截图和元素树不是同一时刻**
+
+（2026-09-13 追加，用户反馈"抓取的窗口老是会错位"）
+
+先把几个常见猜测逐一排除（都实测过）：
+
+| 猜测 | 实测结果 |
+|------|---------|
+| 两条通道元素树不一致 | ✗ 排除：节点数/各 id 个数逐项相同 |
+| 截图被 CSS 缩放了、框没跟着缩 | ✗ 排除：`scaleX=clientWidth/naturalWidth` 算得对，实测框位置与理论值一致 |
+| 窗口 resize 后没重算 | ✗ 排除：预览列固定 320px，resize 不影响 |
+| 列表索引与框的 `data-idx` 对不上 | ✗ 排除：用 `indexOf` 保住原始序号，过滤后也不乱 |
+
+**真因：截图与元素树分两次取，中间隔了 1~2 秒。**
+
+| 取数方式 | 截图 | 元素树 | 两者时间差 |
+|---|---|---|---|
+| 现在（`/api/uiauto/screenshot` + `/api/uiauto/elements` 两次请求，走 uiautodev）| 0.4s | 1.8s | **约 1.8 秒** |
+| 原生 u2 背靠背（同一个连接）| 0.3s | 1.4s | **约 1.4 秒** |
+
+元素树的 dump 本身就要 1.3~1.8 秒（设备端 uiautomator 的开销，改不动）。
+界面**只要在动**（抖音信息流、视频、加载动画…），两秒足够让元素位置全变 →
+**框永远落在旧位置上** —— 这就是"老是错位"，不是偶发。
+
+### 解法（✅ 2026-09-13 已实现，见 `core/uiauto_helper.snapshot`）
+
+1. **一次请求取齐**（推荐，也是用户说的"用原始 u2"）：
+   新增 `GET /api/uiauto/snapshot?serial=X`，服务端用**一个 u2 连接**背靠背
+   `dump_hierarchy()` + `screenshot()`，返回 `{image, elements}`；
+   前端只调这一个接口 → 天然同源，间隔从 ~2.2s 降到 ~1.4s。
+   **并且抓取弹窗改成大图 1:1 预览**（原来预览列只有 320px、图片被缩到 294px，
+   框全挤在一起，看着就像"错位"；现在铺满左侧、按原始分辨率显示）。
+2. **双截图校验**（关键：让失败可见而不是悄悄错位）：
+   抓取时前后各截一张，两张**不一致就明确提示**"界面在抓取过程中变化了，
+   请让设备停在目标界面再抓"，而不是给一个已经错位的框。
+3. 文档里明确写：**抓元素要让设备停在静止界面**（设置页、已加载完的页面），
+   别在视频播放/信息流滑动中抓。
+
+---
+
+## 五、建议的改动
+
+1. ✅ **抓取器优先产出语义选择器**（2026-09-13 已实现，`core/uiauto_helper._extract`）：
+   同一属性值出现多个实例时，**先找第二个属性把目标单独圈出来** ——
+   `//*[@resource-id="x" and @text="…"]`（次属性按 `text` > `content-desc` > `class`
+   排，单个不够就两个组合）；只有怎么都分不开（列表里同 id 同文字）才退回
+   `(…)[k]`。返回值标 `semantic:true` + `via`（限定用的属性）或 `indexed:true`。
+   抓取列表里 **text/content-desc 排在最前并加粗上色**，让用户能看着选。
+2. ✅ **序号型加醒目提示**（同日）：前端把 `indexed` 的徽标从蓝色 `#k/n` 换成
+   黄色 **⚠ 序号 k/n**，悬浮说明"依赖同类元素个数，界面一变就指到别的元素上"；
+   语义型给绿色 **✓ 语义**；右侧「属性」页新增一行**选择器稳定性**。
+3. ⏳ **已存任务**：把 `(…)[k]` 型选择器扫一遍，能改成文字限定的自动改（脚本），
+   其余在编辑器里逐个复核。（用户自行处理）
+4. ⏳ **运行期**：`click` 未命中时，日志里顺带 dump 一下"同 id 现在有几个实例"，
+   让"序号错位"当场可诊断（现在是干巴巴一句"未找到元素"）。
+5. ✅ **（针对第四节的"抓取错位"）** 抓取接口合并成一个快照接口 + 双截图校验，
+   具体见第四节「解法」。
+
+---
+
+## 六、顺带修掉的两个"结构性"坑（2026-09-13）
+
+给 §五.1 做验证时（对真机 dump 逐条用 lxml 求值，比对"命中数==1 且 bounds 一致"），
+发现旧实现 248 个元素里有 **26 条选择器永远匹配不到任何东西** —— 都是"结构路径"类：
+
+| 坑 | 现象 | 原因 |
+|---|---|---|
+| `//FrameLayout[1]/LinearLayout[2]` | 零命中 | **dump 的 XML 标签名一律是 `<node>`**，class 在 `@class` 属性上 —— 把类名当标签名写的路径永远匹配不到 |
+| `//hierarchy/node[@index="1"]` | 零命中或一次命中多个 | 同级节点的 **`index` 属性会重复**（实测状态栏/内容区/导航栏三个兄弟的 `index` 全是 `0`） |
+
+**修法**：
+
+- 子路径步进改成 `*[@class="android.widget.ImageView"][n]`（谓词 `[n]` 在步进选出的
+  节点集上按文档序定位，语义与原来的"同 class 兄弟序号"一致）
+- 兜底结构路径改成按**子节点位置**：`//hierarchy/*[1]/*[3]`
+
+**效果**（同一份真机 XML，248 个元素）：
+
+| | 旧 | 新 |
+|---|---|---|
+| 先按 lxml 求值，精确命中目标 | 221 | **247** |
+| 零命中（死选择器） | 26 | **0** |
+| 语义型 / 序号型 | 0 / 141 | **26 / 115** |
+
+`core/uiauto_helper.py` 里 `_child_path()` 的注释与 `doc/TASK_DEV.md` §5.4 都记了这两个坑，
+避免以后又写回来。
+

doc/staffdeck/KNOWLEDGE_BASE.md

@@ -24,7 +24,7 @@
 
 安卓设备自动化中台：管理一批手机（网络 `IP:5555` / USB 串号），支持任务调度、步骤编排、看屏与操作。
 
-- 你能用的入口：**MCP Server**（推荐，19 个 `de_*` 工具）；备选 REST（§2.2）。
+- 你能用的入口：**MCP Server**（推荐，20 个 `de_*` 工具）；备选 REST（§2.2）。
 - **可做**：看屏、截图、UI 树、OCR、开/关 App、点击、滑动、按键、输入、剪贴板、亮/熄屏、看前台包名、列应用、只读看平台任务。
 - **不可做**：创建/修改/启停平台任务、分组/设备池/备份管理（MCP 未提供）。
 
@@ -52,9 +52,9 @@
 
 ---
 
-## 3. 工具清单（19 个）
+## 3. 工具清单（20 个）
 
-**只读（不触发占用锁）**：`de_list_devices` · `de_screenshot` · `de_ui_tree` · `de_ocr` · `de_foreground_app` · `de_list_apps` · `de_read_clipboard` · `de_list_tasks`
+**只读（不触发占用锁）**：`de_list_devices` · `de_screenshot` · `de_snapshot`（截图+元素树一次取齐，**推荐**）· `de_ui_tree` · `de_ocr` · `de_foreground_app` · `de_list_apps` · `de_read_clipboard` · `de_list_tasks`
 
 **写（受占用锁约束）**：`de_tap_text` · `de_tap_element` · `de_tap` · `de_swipe` · `de_press_key` · `de_type_text` · `de_set_clipboard` · `de_open_app` · `de_stop_app` · `de_wake` · `de_sleep`
 
@@ -69,7 +69,7 @@
 - **用 `de_list_devices` 取，别猜。**
 
 ### 4.2 坐标空间（重要）
-- `de_screenshot` 返回**缩放图（≤540px 宽）+ `native_size`**；`de_tap`/`de_swipe` 用**截图坐标系**，服务端换算原生。
+- `de_screenshot`/`de_snapshot` 返回**缩放图（≤540px 宽）+ `native_size`**；`de_tap`/`de_swipe` 用**截图坐标系**，服务端换算原生（两者都会建立坐标空间）。
 - **必须先截图再坐标操作**；否则报「请先执行 de_screenshot」。
 - 屏可能旋转/滚动 → **优先文字/元素，坐标仅兜底**。
 

mcp_agent/agent.py

@@ -25,15 +25,23 @@ _log = logging.getLogger("agent")
 S = AgentSettings()
 
 
+# 模型单次回复的长度上限。建任务模式要一次性输出整份任务 JSON（几十个步骤），
+# 4096 很容易被截断 → 工具参数变成半截 JSON（见 _execute_tool 的容错）。
+_DEFAULT_MAX_TOKENS = 4096
+_DESIGNER_MAX_TOKENS = 8192
+
+
 class _UsageUnsupported(RuntimeError):
     """模型/网关不认 stream_options.include_usage（400/422 或报错点名该字段）——降级重试用。"""
 
-SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操作 Android 手机。
+CHAT_SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操作 Android 手机。
 
 工作规范：
 1. 先 de_list_devices 确定目标设备（在线才可操作）；设备有 name（名称）与 serial（地址），
    **给用户汇报时用名称**（同型号多台靠它区分），调工具时仍用 serial
-2. 观察屏幕：先 de_screenshot 获取截图（图像会随后给你），基于截图理解当前界面
+2. 观察屏幕：优先 `de_snapshot`（截图+元素树一次取齐，图像会随后给你）——比
+   de_screenshot + de_ui_tree 两次取数更省步骤，界面在动时也不会出现"元素位置和
+   截图对不上"；需要单独看画面时才用 de_screenshot
 3. 点击定位分优先级（不要自己推算像素坐标，那是精度最差的方式）：
    a) 目标有可见文字（按钮/菜单/列表标题/标签/输入框提示）→ de_tap_text 直接给文字，
       一次完成「找到并点击」，原生控件与 WebView/图片渲染文字都支持
@@ -54,6 +62,103 @@ SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操
 
 可用工具清单将由系统提供。"""
 
+# 兼容旧名（CLI / 其它调用方仍可能 import SYSTEM_PROMPT）
+SYSTEM_PROMPT = CHAT_SYSTEM_PROMPT
+
+
+# ================== 建任务模式（designer）==================
+# 与聊天模式的根本区别：**产出物是一条任务，不是"替用户做完这件事"**。
+# 所以它要"看懂了就写下来"，而不是"一路点到底"；有副作用的动作只许核对、不许真做。
+DESIGNER_SYSTEM_PROMPT = """你是手机自动化**任务设计师**。你的产出物是**一条可调度、可在步骤编辑器里继续修改的任务**（不是替用户把这件事做完）。
+
+工作方式：在真机上探索够用即止 → 把探索到的元素与操作写成任务步骤 → 调 submit_task 提交草稿 → 人工确认后才会真正入库执行。
+
+## 探索规范
+1. 只用本次指定的设备 serial；给用户汇报时用设备名。设备离线/异常/被任务占用时**立即停止并说明**，不要硬试。
+2. **先看再动**：优先 `de_snapshot(limit=80~150)`——它**一次取齐**截图与元素树（元素字段只有 text/id/desc/class/clickable/bounds，**没有 xpath**），比"先 de_screenshot 再 de_ui_tree"少一次来回、且不会因为界面在动而错位；返回 `unstable=true` 时说明取的时候界面在变，等界面静下来再取一次。同一屏只取一次，不要反复截图。
+3. 不知道包名先 `de_list_apps(keyword=…)`，再 `de_open_app(package)`；用 `de_foreground_app` 确认前台。
+4. **定位优先级**：`text` / `description` / `resourceId` > `xpath` > 坐标。**禁止坐标**（绝不产 `click_xy`）。
+   包含匹配只能 `descriptionContains`，或 `xpath` 里的 `//*[contains(@text,"…")]`（没有 textContains 这个类型）。
+5. XPath 写法：`//*[@resource-id="包名:id/xxx"]`、`//*[@text="…"]`、`//*[@text="…" and @resource-id="…"]`。
+   **禁止** `//*[@id="x"][3]` 这种位置谓词（那是"父节点内第 3 个"，同类元素一多就全失配）。
+6. 验证分两档：
+   - **无害导航类**（tab、返回、搜索框、列表项、设置项）→ 可以 `de_tap_element` 真点一次确认能命中，记 `evidence.verified="tapped"`；
+   - **有副作用类**（点赞/关注/评论/发送/转发/购买/删除/退出登录）→ **只核对元素存在**（`verified="present"`），**绝不真点**；写进任务时 `probability ≤ 30`，并在 `notes` 里写明"请人工复核"。
+7. 没验证命中的元素**一律不写进任务**；拿不准的进 `notes`。宁可少写一步，也不要编一个选择器。
+
+## 步骤规范
+8. 只能用这 18 种步骤类型：open_app / stop_app / screen_on / screen_off / keep_screen / key_event / swipe / swipe_until / click / long_click / wait_el / input_text / clipboard / wait / loop / group / if_el（click_xy 禁用）。
+9. 输入文字必须"先 click 输入框，再 input_text"；滚动用 `swipe{direction}`，不用像素。
+10. 时长语义必须映射对：
+    - "跑 2 小时" → `params.max_duration = 7200` + 一个顶层 `loop{loop_mode:"forever"}`；
+    - "每天 8-9 点" → `schedule{mode:"cron_stop", cron:"0 8 * * *", stop_cron:"0 9 * * *"}`；
+    - **长任务必须给 max_duration**，否则等于无限跑。
+11. 随机化三件套：随机等待 `wait{min,max}`、随机文案 `input_text{mode:"random",texts:"a\\nb"}`、随机触发 `group{probability:<100}` 包住子步骤（概率对任何类型都生效）。
+12. 首步建议 `screen_on`（必要时 `keep_screen{mode:"on"}`）；**末步用 `key_event{key:"home"}` 把设备还给用户**（不要默认息屏）。
+13. 规模控制：工具调用 ≤ 25 步、steps ≤ 30 个节点、notes ≤ 5 条、evidence ≤ 10 条。结构要精简（去掉冗余的等待/滑动）。
+
+## 收尾
+14. 探索够了就调 `submit_task` 提交草稿。**校验失败时按返回的 errors 逐条修正后重提（最多 3 次）**，不要重复提交同一份草稿。
+15. 提交成功后**不要再调用任何工具**，用一句中文总结："建了什么任务、哪些步骤需要人工复核"。
+16. 若 system 里注入了"可复用动作"，优先复用其中的定位，跳过重复探索。
+
+可用工具清单将由系统提供。"""
+
+
+# 平台级（本地）工具：不经 MCP server，由 Agent 直接分派到调用方注册的 handler。
+# 为什么不放进 mcp_server：这些工具要读写平台自身的任务/草稿（依赖 Flask app context 与
+# 平台权限模型），放进 MCP 层等于给外部客户端开一个写任务的后门，且要连带改
+# MCP.md/MCP_DESIGN.md 与审计——收益为零（见 doc/AI_TASK_GEN.md §9.2）。
+LOCAL_TOOL_SPECS = {
+    "submit_task": {
+        "name": "submit_task",
+        "description": "提交任务草稿（**结束性调用**：提交成功后就不要再调任何工具，直接总结）。"
+                       "服务端会校验草稿（步骤类型/必填参数/嵌套深度/调度格式），"
+                       "校验失败返回 errors 数组，请逐条修正后重新调用本工具。"
+                       "常见被打回的原因：步骤缺 selector_value；loop 的 loop_mode 不是 "
+                       "rounds/time/forever（别写 count）；按时间循环缺 loop_duration；"
+                       "cron 不是 5 段；steps 为空。提交前请自己先按这些自查一遍。",
+        "parameters": {
+        "type": "object",
+        "properties": {
+            "summary": {"type": "string",
+                        "description": "一句话说明这条任务做什么（≤200 字）"},
+            "task": {
+                "type": "object",
+                "description": "任务信封，字段同平台任务：name/target/schedule/retry/enabled/params",
+                "properties": {
+                    "name": {"type": "string", "description": "任务名（≤40 字）"},
+                    "target": {"type": "object",
+                               "description": '{"mode":"all"|"group"|"serial", "serial":"…", "group_name":"…"}'},
+                    "schedule": {"type": "object",
+                                 "description": '{"mode":"once"} 或 {"mode":"cron","cron":"分 时 日 月 周"} 或 {"mode":"cron_stop","cron":"…","stop_cron":"…"}'},
+                    "retry": {"type": "object",
+                              "description": '{"max_attempts":1-10,"delay":10-3600}'},
+                    "enabled": {"type": "boolean"},
+                    "params": {
+                        "type": "object",
+                        "properties": {
+                            "max_duration": {"type": "integer",
+                                             "description": "单次运行时长上限（秒），0=不限时"},
+                            "steps": {"type": "array",
+                                      "description": "步骤树：[{type,label,params}]，容器用 params.children / params.then / params.else",
+                                      "items": {"type": "object"}},
+                        },
+                        "required": ["steps"],
+                    },
+                },
+                "required": ["params"],
+            },
+            "notes": {"type": "array", "items": {"type": "string"},
+                      "description": "需要人工复核/拿不准的点（≤5 条）"},
+            "evidence": {"type": "array", "items": {"type": "object"},
+                         "description": "每个选择器的探索依据：{screen,element,selector_type,selector_value,verified}"},
+        },
+        "required": ["summary", "task"],
+        },
+    },
+}
+
 
 class Agent:
     def __init__(self, settings: AgentSettings = None):
@@ -73,6 +178,32 @@ class Agent:
                       "total_tokens": 0, "calls": 0}
         self._include_usage = True   # 模型不认 stream_options 时自动置 False
         self._mcp = None
+        # ---- 建任务模式（designer）相关 ----
+        self.mode = "chat"
+        # 平台级本地工具：{名字: async handler(args) -> dict}，不走 MCP
+        self._local_handlers = {}
+        # 本轮每个工具调用了几次（防"原地打转"：同一个工具反复调不推进目标）
+        self._tool_counts = {}
+        # 单个工具本轮最多调用次数（防"原地打转"）。要**大于**正常重试次数：
+        # 探索里 submit_task 反复被校验驳回调几次是正常的，卡太死会把整轮探索截断
+        # （实测 25 时正好把一轮设计任务耗在修字段上）。总步数由 max_steps 兜底。
+        self.tool_call_limit = 40
+        self.max_tokens = None       # 模型单次回复上限（None=用 _DEFAULT_MAX_TOKENS）
+
+    # ---------- 本地（平台级）工具 ----------
+    def register_local_tool(self, name, handler):
+        """注册平台级本地工具。**必须在 `_load_tools()` 之前调用**（schema 在加载时组装）。
+
+        handler: `async def(args: dict) -> dict`，返回值会作为工具结果回给模型并推给前端。
+        """
+        if name not in LOCAL_TOOL_SPECS:
+            raise KeyError(f"未定义的本地工具: {name}（需先在 LOCAL_TOOL_SPECS 里声明 schema）")
+        self._local_handlers[name] = handler
+
+    def _count_tool_call(self, name):
+        n = self._tool_counts.get(name, 0) + 1
+        self._tool_counts[name] = n
+        return n
 
     # ---------- MCP 工具桥 ----------
     async def _load_tools(self):
@@ -91,6 +222,12 @@ class Agent:
                 "type": "function",
                 "function": {"name": name, "description": desc,
                              "parameters": schema}})
+        # 平台级本地工具（如 submit_task）随 MCP 工具一起暴露给模型，
+        # 执行时由 _execute_tool 本地分派（不发给 MCP server）
+        for name in self._local_handlers:
+            spec = LOCAL_TOOL_SPECS.get(name)
+            if spec:
+                self.tools_schema.append({"type": "function", "function": spec})
         _log.info("MCP 工具已加载: %s", [s["function"]["name"] for s in self.tools_schema])
 
     async def close(self):
@@ -123,7 +260,7 @@ class Agent:
             "model": self.s.model,
             "messages": self.messages,
             "tools": self.tools_schema if self.tools_schema else None,
-            "max_tokens": 4096,
+            "max_tokens": self.max_tokens or _DEFAULT_MAX_TOKENS,
             "stream": True,
         }
         if with_usage:
@@ -185,9 +322,44 @@ class Agent:
 
     # ---------- 工具执行 ----------
     async def _execute_tool(self, name, arguments):
-        """执行 MCP 工具，返回 (文本结果, image_data_or_None)。"""
+        """执行工具（MCP 或平台级本地工具），返回 (文本结果, image_data_or_None)。"""
-        args = json.loads(arguments) if isinstance(arguments, str) else (arguments or {})
+        try:
+            args = json.loads(arguments) if isinstance(arguments, str) else (arguments or {})
+        except (json.JSONDecodeError, TypeError) as e:
+            # 长参数被输出长度截断时 arguments 是半截 JSON。**不能整轮报错**——
+            # 把"坏了"告诉模型，让它精简后重发（designer 的 steps 可能很长）。
+            _log.warning("工具 %s 参数不是合法 JSON: %s", name, e)
+            return {"ok": False,
+                    "error": f"参数不是合法 JSON（{e}）——常见原因是这次输出过长被截断，"
+                             "请精简要提交的内容后重新调用一次"}, None
+        if not isinstance(args, dict):
+            return {"ok": False, "error": "工具参数必须是 JSON 对象"}, None
         _log.info("执行工具 %s %s", name, args)
+
+        # 同一个工具被反复调用（原地打转）时给模型一个明确的刹车
+        if self._count_tool_call(name) > self.tool_call_limit:
+            return {"ok": False,
+                    "error": f"{name} 本轮调用次数已达上限（{self.tool_call_limit} 次），"
+                             "请换一种做法推进，或直接总结当前进展"}, None
+
+        # 平台级本地工具：不发给 MCP server
+        handler = self._local_handlers.get(name)
+        if handler is not None:
+            # 平台级工具自己会推更贴切的提示卡（📝 任务草稿 / 草稿被拦下 / 未存下），
+            # 这里**不再重复推一张工具卡**——只在 handler 意外抛异常（自己没来得及推）时补一张
+            try:
+                result = await handler(args)
+            except Exception as e:
+                _log.exception("本地工具 %s 执行失败", name)
+                result = {"ok": False, "error": f"工具执行失败: {e}"}
+                if self.on_tool:
+                    try:
+                        self.on_tool({"tool": name, "args": args,
+                                      "result": result, "image": None})
+                    except Exception:
+                        pass
+            return result, None
+
         try:
             result = await self._mcp.call_tool(name, args)
             data = getattr(result, "data", result)
@@ -216,10 +388,14 @@ class Agent:
         for i in range(len(self.messages) - 1, -1, -1):
             m = self.messages[i]
             if m.get("role") == "assistant" and m.get("tool_calls"):
-                # 统计其后 tool 消息数是否匹配
+                # 只数**紧跟着的连续** tool 消息：模型侧要求工具回应连续排列，
+                # 中间夹一条 user（如截图图像）就会被判成"回应不足"。
                 need = len(m["tool_calls"])
-                have = sum(1 for x in self.messages[i + 1:]
+                have = 0
-                           if x.get("role") == "tool")
+                for x in self.messages[i + 1:]:
+                    if x.get("role") != "tool":
+                        break
+                    have += 1
                 if have < need:
                     _log.warning("修复不完整 tool_calls 段（need=%d have=%d），回退 %d 条消息",
                                  need, have, len(self.messages) - i)
@@ -229,7 +405,8 @@ class Agent:
     # ---------- 主循环（流式） ----------
     async def run_stream(self, prompt: str, serial: str = "",
                          history=None, on_delta=None, on_tool=None,
-                         should_stop=None, extra_context=None, on_usage=None):
+                         should_stop=None, extra_context=None, on_usage=None,
+                         mode: str = "chat"):
         """流式执行一轮指令，返回最终完整文本。
 
         history：上一轮的 [{"role": "user"|"assistant", "content": 文本}] 列表，
@@ -239,16 +416,21 @@ class Agent:
         should_stop：可调用 fn() -> bool，每轮模型调用前检查（用户中断用）
         extra_context：附加文本（经验记忆注入，放在 system prompt 末尾）
         on_usage(usage)：每完成一次模型调用回调一次（累计值，见 self.usage）
+        mode：`chat`（默认，AI 控制台聊天）或 `designer`（AI 建任务：改系统提示词、
+              放宽输出长度上限、注册的本地工具生效）
 
         本轮累计 token 用量同时留在 self.usage（调用方可直接读）。
         """
         self.on_delta = on_delta
         self.on_tool = on_tool
         self.on_usage = on_usage
+        self.mode = mode
+        self.max_tokens = _DESIGNER_MAX_TOKENS if mode == "designer" else _DEFAULT_MAX_TOKENS
+        self._tool_counts = {}
         self.usage = {"prompt_tokens": 0, "completion_tokens": 0,
                       "total_tokens": 0, "calls": 0}
         target = serial or self.s.default_serial
-        sys_txt = SYSTEM_PROMPT
+        sys_txt = DESIGNER_SYSTEM_PROMPT if mode == "designer" else CHAT_SYSTEM_PROMPT
         if target:
             sys_txt += f"\n\n本次默认目标设备 serial：{target}（未指定设备时用它）。"
         if extra_context:
@@ -321,6 +503,12 @@ class Agent:
                 self.messages.append({"role": "assistant",
                                       "content": full_content,
                                       "tool_calls": tcs})
+                # 工具结果必须**连续**跟在带 tool_calls 的 assistant 消息后面：
+                # 中间插任何消息都会被模型侧判成"工具回应不足"而 400
+                # （An assistant message with 'tool_calls' must be followed by tool
+                #   messages responding to each 'tool_call_id'）。
+                # 截图图像因此先攒着，等本轮所有 tool 消息都发完，再作为一条 user 消息附上。
+                pending_images = []
                 for tc in tcs:
                     fn = tc["function"]
                     text_result, image_b64 = await self._execute_tool(
@@ -329,13 +517,15 @@ class Agent:
                         "role": "tool", "tool_call_id": tc["id"],
                         "content": json.dumps(text_result, ensure_ascii=False)[:4000]})
                     if image_b64:
-                        self.messages.append({
+                        pending_images.append(image_b64)
-                            "role": "user",
+                if pending_images:
-                            "content": [{"type": "text",
+                    content = [{"type": "text",
-                                         "text": "这是最新屏幕截图，请基于它继续判断"},
+                                "text": "这是最新屏幕截图，请基于它继续判断"}]
-                                        {"type": "image_url",
+                    for img in pending_images:
-                                         "image_url": {"url":
+                        content.append({"type": "image_url",
-                                                       f"data:image/jpeg;base64,{image_b64}"}}]})
+                                        "image_url": {"url":
+                                                      f"data:image/jpeg;base64,{img}"}})
+                    self.messages.append({"role": "user", "content": content})
                 continue
 
             # 无工具调用：本轮即最终回答

mcp_server/mcp_server.py

@@ -204,6 +204,23 @@ _KEYS = ("back", "home", "recent", "menu", "power", "volume_up",
          "volume_down", "enter", "delete", "search", "camera")
 
 
+def _slim_elements(els, limit):
+    """精简元素列表（de_ui_tree / de_snapshot 共用）：去 suggested/深度噪音，
+    可点击优先、有文案优先，控制 token。"""
+    slim = []
+    for e in els:
+        slim.append({
+            "text": e.get("text", "")[:50],
+            "id": e.get("resource_id", "")[:80],
+            "desc": e.get("description", "")[:50],
+            "class": e.get("class", "").split(".")[-1],
+            "clickable": e.get("clickable", "") == "true",
+            "bounds": e.get("bounds", ""),
+        })
+    slim.sort(key=lambda x: (not x["clickable"], not (x["text"] or x["desc"])))
+    return slim[:limit]
+
+
 @mcp.tool()
 def de_ui_tree(serial: str, limit: int = 150) -> dict:
     """获取当前界面元素树（文本 JSON）：每元素含 text/resource_id/description/class/bounds。
@@ -219,20 +236,61 @@ def de_ui_tree(serial: str, limit: int = 150) -> dict:
         els = platform().ui_elements(serial)
     except PlatformError as e:
         return _err(e)
-    # 精简输出：去掉 suggested/深度噪音，保留可定位属性；可点击优先、有文案优先
+    slim = _slim_elements(els, limit)
-    slim = []
-    for e in els:
-        slim.append({
-            "text": e.get("text", "")[:50],
-            "id": e.get("resource_id", "")[:80],
-            "desc": e.get("description", "")[:50],
-            "class": e.get("class", "").split(".")[-1],
-            "clickable": e.get("clickable", "") == "true",
-            "bounds": e.get("bounds", ""),
-        })
-    slim.sort(key=lambda x: (not x["clickable"], not (x["text"] or x["desc"])))
     audit.audit("de_ui_tree", serial, "", f"{len(slim)} 元素")
-    return _ok({"count": len(slim), "elements": slim[:limit]})
+    return _ok({"count": len(slim), "elements": slim})
+
+
+@mcp.tool()
+def de_snapshot(serial: str, limit: int = 120) -> dict:
+    """一次取齐：屏幕截图 + 元素树（**推荐用它代替 de_screenshot + de_ui_tree**）。
+
+    那两条是两次独立取数，中间隔着元素树 dump 本身的 1~2 秒——界面只要在动
+    （信息流/视频/加载动画），返回的元素坐标就和截图对不上，照它点击会点偏。
+    本工具在平台侧用**同一个连接背靠背取**，并额外做双截图校验：
+    `unstable=true` 表示"抓取过程中界面在变化"，此时别把元素坐标当准的，
+    建议让设备停在静止界面再取一次。
+
+    返回 image（宽 ≤540 的可视截图，同时建立后续 de_tap/de_swipe 的坐标空间）、
+    native_size、screen_state、unstable、cost_ms，以及 elements
+    （结构与 de_ui_tree 相同；limit 控制条数，默认 120）。
+    """
+    try:
+        serial = _check_serial(serial)
+        if limit < 1 or limit > 300:
+            raise PlatformError("invalid_param", "limit 需在 1-300 之间")
+        snap = platform().snapshot(serial)
+        raw = snap.get("image") or ""
+        b64 = raw.split(",", 1)[1] if "," in raw else raw
+        img = Image.open(io.BytesIO(base64.b64decode(b64)))
+        nw, nh = img.size
+        if nw > S.screenshot_width:
+            ratio = S.screenshot_width / nw
+            img = img.resize((S.screenshot_width, int(nh * ratio)))
+        buf = io.BytesIO()
+        img.convert("RGB").save(buf, "JPEG", quality=S.jpeg_quality)
+        data = base64.b64encode(buf.getvalue()).decode()
+        # 与 de_screenshot 用同一套坐标口径：后续 de_tap/de_swipe 传的是这张图的坐标
+        _coord[serial] = (img.size[0], img.size[1], nw, nh)
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable", f"快照处理失败: {e}"))
+    slim = _slim_elements(snap.get("elements") or [], limit)
+    unstable = bool(snap.get("unstable"))
+    audit.audit("de_snapshot", serial, f"{len(slim)} 元素",
+                "unstable" if unstable else "ok")
+    out = {"image": {"type": "image", "data": data, "mimeType": "image/jpeg"},
+           "width": img.size[0], "height": img.size[1],
+           "native_size": {"width": nw, "height": nh},
+           "screen_state": snap.get("screen_state", "unknown"),
+           "unstable": unstable,
+           "cost_ms": snap.get("cost_ms", 0),
+           "count": len(slim), "elements": slim}
+    if unstable:
+        out["hint"] = ("抓取期间界面在变化（unstable）：元素坐标可能已过时，"
+                       "让设备停在静止界面再取一次更稳")
+    return _ok(out)
 
 
 @mcp.tool()

mcp_server/platform_client.py

@@ -80,6 +80,24 @@ class PlatformClient:
                                 f"截图 HTTP {r.status_code}")
         return r.content, r.headers.get("X-Screen-State", "unknown")
 
+    def snapshot(self, serial):
+        """一次取齐截图+元素树（GET /api/uiauto/snapshot）。
+
+        平台侧用**同一个 u2 连接**背靠背 dump+screenshot，并做双截图校验
+        （unstable 表示"抓取期间界面在变化"）。返回平台 JSON：
+        {ok, image(data-url), width, height, elements, unstable, screen_state, cost_ms}
+        """
+        r = self._get("/api/uiauto/snapshot", serial=serial, _t=0)
+        if r.status_code in (502, 503):
+            raise PlatformError("device_offline", r.text[:160])
+        if r.status_code != 200:
+            raise PlatformError("platform_unavailable",
+                                f"快照 HTTP {r.status_code}")
+        j = r.json() or {}
+        if not j.get("ok"):
+            raise PlatformError("device_offline", str(j.get("error", "快照失败"))[:160])
+        return j
+
     def screen_size(self, serial):
         """屏幕原生分辨率（GET /api/screen/size），返回 (w, h)。"""
         r = self._get("/api/screen/size", serial=serial)

requirements.txt

@@ -12,6 +12,14 @@ Flask>=2.3,<4.0
 Flask-Login>=0.6
 Flask-SQLAlchemy>=3.0,<4.0
 
+# MySQL 驱动（纯 Python，slim 容器里无需编译依赖）。
+# 连接参数与多环境配置见 core/db_config.py 与 .env.example 的「数据库」段。
+PyMySQL>=1.1
+
+# 设备端 Agent 的「扫码配置」二维码（设备池面板生成，手机扫一下配好 server/token/指纹）。
+# 纯 Python，配合已有的 Pillow 出 PNG，不引前端二维码库。
+qrcode>=7.4
+
 # 定时任务调度
 APScheduler>=3.10,<4.0
 

scripts/migrate_sqlite_to_mysql.py

@@ -0,0 +1,367 @@
+# -*- coding: utf-8 -*-
+"""把 SQLite 库整体迁移进 MySQL（一次性工具，长期保留）。
+
+用途：
+  * 平台从 SQLite 迁到 MySQL 时搬数据
+  * 从老备份（导出 zip 里的 users.db）恢复进 MySQL
+  * 换环境（dev 库 ↔ 正式库）
+
+用法示例：
+    # 先干跑：只审计源库 + 建 schema，不搬数据
+    python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev --dry-run
+
+    # 正式迁（目标库已有数据会被整表替换）
+    python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev --mode replace
+
+    # 迁完只做校验（逐表 SHA-256 比对，不写任何数据）
+    python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev --mode verify
+
+    # 生产（必须显式二次确认）
+    python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env prod --allow-prod --yes
+
+目标库怎么定：默认读 .env / 环境变量的 DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME
+（也可用 --target-url 直接给完整连接串）。脚本**不会**碰源库（只读打开）。
+
+安全设计：
+  * 全程只读源库；目标库的写入在**单个事务**里，失败回滚，可放心重跑
+  * 搬完做逐表行数 + 逐表全行 SHA-256 校验，不通过就报错
+  * `--env prod` 必须额外 `--allow-prod`，交互终端还要手打 prod 确认
+  * 目标库若已登记为别的环境（app_meta.deployment_env），除非 --force-env 否则拒绝
+"""
+import argparse
+import hashlib
+import json
+import os
+import sqlite3
+import sys
+import time
+import uuid
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, ROOT)
+
+# Windows 控制台默认 GBK，输出里带 ✔ 之类的符号会直接抛 UnicodeEncodeError
+# （本脚本是运维在终端里手跑的，崩在最后一步会让人以为迁移失败）
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+from sqlalchemy import inspect as sa_inspect, text as sa_text  # noqa: E402
+
+
+def _fail(msg):
+    print("\n[错误] " + msg)
+    sys.exit(2)
+
+
+def _readonly_uri(path):
+    from urllib.parse import quote
+    return "file:{}?mode=ro".format(
+        quote(os.path.abspath(path).replace("\\", "/"), safe="/:"))
+
+
+def parse_args():
+    ap = argparse.ArgumentParser(description="SQLite → MySQL 数据迁移")
+    ap.add_argument("--sqlite", default=os.path.join(ROOT, "data", "users.db"),
+                    help="源 SQLite 库路径（默认 data/users.db）")
+    ap.add_argument("--env", choices=["dev", "prod"], required=True,
+                    help="目标库属于哪个环境（写入 app_meta.deployment_env）")
+    ap.add_argument("--mode", choices=["replace", "verify"], default="replace",
+                    help="replace=建 schema 并搬数据；verify=只比对不写")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="只审计源库并建 schema，不搬数据")
+    ap.add_argument("--schema-only", action="store_true",
+                    help="只建目标库的表结构，不搬数据")
+    ap.add_argument("--target-url", default="",
+                    help="目标连接串（默认取 .env / 环境变量里的 DB_*）")
+    ap.add_argument("--allow-prod", action="store_true",
+                    help="允许对生产库操作（--env prod 时必填）")
+    ap.add_argument("--yes", action="store_true",
+                    help="非交互环境下的最终确认（与 --allow-prod 一起用）")
+    ap.add_argument("--force-env", action="store_true",
+                    help="目标库已登记为别的环境时仍然继续（危险）")
+    return ap.parse_args()
+
+
+# ================== 1. 源库审计 ==================
+def audit_source(src_path, tables):
+    """校验源库可读、完整，并做列宽审计。返回 {表: {列: 最大长度}}。"""
+    if not os.path.exists(src_path):
+        _fail("源库不存在: " + src_path)
+    con = sqlite3.connect(_readonly_uri(src_path), uri=True)
+    con.text_factory = str
+    try:
+        integrity = con.execute("PRAGMA integrity_check").fetchone()[0]
+        print(f"源库完整性: {integrity}")
+        if integrity != "ok":
+            _fail("源库完整性校验失败，请先修复源库再迁移")
+
+        have = {r[0] for r in con.execute(
+            "SELECT name FROM sqlite_master WHERE type='table'")}
+        print(f"源库表（{len(have)}）: " + ", ".join(sorted(have)))
+        missing = [t for t in tables if t not in have]
+        if missing:
+            print(f"  注意：模型里有但源库没有的表（迁移后为空）: {', '.join(missing)}")
+
+        # 列宽审计：SQLite 不强制长度，MySQL 严格模式下超长会直接报错
+        widths = {}
+        for t in sorted(have):
+            if t.startswith("sqlite_"):
+                continue
+            widths[t] = {}
+            cols = [r[1] for r in con.execute('PRAGMA table_info("%s")' % t)]
+            for c in cols:
+                try:
+                    n = con.execute(
+                        'SELECT MAX(LENGTH("%s")) FROM "%s"' % (c, t)).fetchone()[0]
+                except sqlite3.Error:
+                    continue
+                if n:
+                    widths[t][c] = n
+        return widths
+    finally:
+        con.close()
+
+
+def check_widths(widths):
+    """把源库实测列宽与模型声明比对，超限直接拦下（MySQL 严格模式会报错）。"""
+    from core.models import db
+    problems = []
+    print("\n列宽审计（源库实测最大长度 / 模型上限）:")
+    for table in db.metadata.sorted_tables:
+        w = widths.get(table.name) or {}
+        for col in table.columns:
+            n = w.get(col.name)
+            limit = getattr(col.type, "length", None)
+            if n is None or not limit:
+                continue
+            flag = ""
+            if n > limit:
+                flag = "  <== 超出！"
+                problems.append(f"{table.name}.{col.name}: {n} > {limit}")
+            if n > limit * 0.6:
+                print(f"   {table.name}.{col.name}: {n}/{limit}{flag}")
+    if problems:
+        _fail("以下列的实际数据超过模型声明长度，请先加长模型列宽或清理数据：\n  "
+              + "\n  ".join(problems))
+    print("   （只打印长度超过上限 60% 的列；全部在限内）")
+
+
+# ================== 2. 目标库 schema ==================
+def build_target_app(uri, env):
+    """用目标连接串建一个最小 Flask app，复用平台自己的建表逻辑。"""
+    os.environ["DEPLOY_ENV"] = env
+    os.environ["DATABASE_URL"] = uri
+    from flask import Flask
+    from core.models import db  # noqa: E402
+
+    app = Flask("migrate")
+    app.config["SQLALCHEMY_DATABASE_URI"] = uri
+    app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+    from core import db_config
+    app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+    db.init_app(app)
+    with app.app_context():
+        # 只做结构：建表 / 补列 / 唯一索引（跳过默认管理员与旧 JSON 迁移）
+        from core.models import _ensure_unique_indexes, _sync_columns
+        db.create_all()
+        _sync_columns()
+        _ensure_unique_indexes()
+    return app
+
+
+# ================== 3. 搬数据 + 校验 ==================
+def _rows_from_sqlite(con, table, cols):
+    names = [c.name for c in cols]
+    sel = "SELECT {} FROM \"{}\"".format(
+        ", ".join('"%s"' % n for n in names), table.name)
+    cur = con.execute(sel)
+    return names, cur.fetchall()
+
+
+def _norm(v):
+    """把驱动层返回的值统一成可跨库比较的形态。
+
+    两个库的类型系统不一样，直接比 Python 对象会误报：
+      * 布尔：SQLite 存 1/0（原始读出来是 int），走 ORM 读回来是 True/False
+      * 整数值的浮点：SQLite 的 REAL 列里可能存着 7，MySQL 的 DOUBLE 读回来是 7.0
+      * 文本：某些驱动可能给 bytes
+    """
+    if isinstance(v, bool):
+        return int(v)
+    if isinstance(v, float) and v.is_integer():
+        return int(v)
+    if isinstance(v, (bytes, bytearray)):
+        return v.decode("utf-8", "replace")
+    return v
+
+
+def _canonical(names, rows):
+    """把整表行规范化成一个字符串，用于跨库比对（行序无关：先排序再哈希）。"""
+    packed = [json.dumps([_norm(r[i]) for i in range(len(names))],
+                         ensure_ascii=False, default=str,
+                         sort_keys=False) for r in rows]
+    packed.sort()
+    h = hashlib.sha256()
+    for p in packed:
+        h.update(p.encode("utf-8"))
+        h.update(b"\n")
+    return h.hexdigest()
+
+
+def copy_and_verify(src_path, table_order, mode, chunk=500):
+    """搬运并校验。返回 (逐表统计, 是否全部一致)。
+
+    mode="replace"：DELETE 全表 + 插入 + 回读比对（单事务，失败整体回滚）
+    mode="verify" ：只回读比对，不写任何数据
+    """
+    from core.models import db
+
+    con = sqlite3.connect(_readonly_uri(src_path), uri=True)
+    con.text_factory = str
+    stats = []
+    try:
+        have = {r[0] for r in con.execute(
+            "SELECT name FROM sqlite_master WHERE type='table'")}
+        with db.engine.begin() as dst:          # 单事务：失败整体回滚
+            if mode == "replace":
+                for table in reversed(table_order):
+                    dst.execute(table.delete())
+            for table in table_order:
+                if table.name not in have:
+                    stats.append((table.name, 0, "源库无此表", "-"))
+                    continue
+                db_cols = {c["name"] for c in sa_inspect(dst).get_columns(table.name)}
+                cols = [c for c in table.columns if c.name in db_cols]
+                names, rows = _rows_from_sqlite(con, table, cols)
+                src_hash = _canonical(names, rows)
+                if mode == "replace":
+                    for i in range(0, len(rows), chunk):
+                        batch = [dict(zip(names, r)) for r in rows[i:i + chunk]]
+                        dst.execute(table.insert(), batch)
+                stats.append((table.name, len(rows), src_hash))
+    finally:
+        con.close()
+
+    # 回读目标库重算（verify 模式只有这一步）
+    with db.engine.connect() as dst:
+        out = []
+        for (name, srows, shash) in stats:
+            table = next((t for t in table_order if t.name == name), None)
+            if table is None or shash == "-":
+                out.append((name, srows, "-", "源库无此表", "-"))
+                continue
+            db_cols = {c["name"] for c in sa_inspect(dst).get_columns(name)}
+            names = [c.name for c in table.columns if c.name in db_cols]
+            # 用原生 SQL 回读：走 ORM/Core 的 typed select 会做类型转换
+            # （Boolean→True/False），与源库驱动层读出来的 1/0 对不上
+            prep = dst.dialect.identifier_preparer
+            sel = "SELECT {} FROM {}".format(
+                ", ".join(prep.quote(n) for n in names), prep.quote(name))
+            rows = [tuple(r) for r in dst.execute(sa_text(sel)).fetchall()]
+            thash = _canonical(names, rows)
+            same = (len(rows) == srows) and (thash == shash)
+            out.append((name, srows, len(rows), "一致" if same else "不一致", shash))
+    return out, all(r[3] == "一致" or r[3] == "源库无此表" for r in out)
+
+
+def print_stats(stats):
+    print("\n%-20s %6s %6s  %-10s %s" % ("表", "源", "目标", "结果", "SHA-256(前12)"))
+    for (name, srows, trows, verdict, shash) in stats:
+        print("%-20s %6s %6s  %-10s %s" % (name, srows, trows, verdict, (shash or "-")[:12]))
+
+
+# ================== 主流程 ==================
+def main():
+    args = parse_args()
+
+    if args.env == "prod":
+        if not args.allow_prod:
+            _fail("--env prod 必须同时给 --allow-prod（这条命令会写生产库）")
+        if sys.stdin.isatty() and not args.yes:
+            print("即将对【生产库】执行迁移。")
+            if input("请输入 prod 确认: ").strip() != "prod":
+                _fail("未确认，已中止")
+        elif not args.yes:
+            _fail("非交互环境下请追加 --yes 明确确认")
+
+    from core import db_config
+    uri = args.target_url or db_config.build_db_uri()
+    if db_config.is_sqlite(uri):
+        _fail("目标仍是 SQLite —— 请在 .env 里配好 DB_HOST/DB_USER/DB_PASSWORD/DB_NAME，"
+              "或用 --target-url 指定 MySQL 连接串")
+    print(f"源库   : {args.sqlite}")
+    print(f"目标库 : {db_config.describe_target(uri)}   (环境 {args.env})")
+
+    from core.models import db
+    tables = list(db.metadata.sorted_tables)
+    print(f"模型表（{len(tables)}）: " + ", ".join(t.name for t in tables))
+
+    widths = audit_source(args.sqlite, [t.name for t in tables])
+    check_widths(widths)
+
+    if args.mode == "verify":
+        # 不建 schema、不写数据，直接比对（用于迁移后复验）
+        os.environ["DEPLOY_ENV"] = args.env
+        os.environ["DATABASE_URL"] = uri
+        from flask import Flask
+        app = Flask("verify")
+        app.config["SQLALCHEMY_DATABASE_URI"] = uri
+        app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+        db.init_app(app)
+        with app.app_context():
+            stats, ok = copy_and_verify(args.sqlite, tables, "verify")
+        print_stats(stats)
+        print("\n校验结果: " + ("全部一致 OK" if ok else "存在不一致 FAIL"))
+        sys.exit(0 if ok else 1)
+
+    # 目标库环境标签检查（防止误把 dev 数据灌进生产库）
+    app = build_target_app(uri, args.env)
+    with app.app_context():
+        recorded = db_config.meta_get("deployment_env")
+        if recorded and recorded != args.env and not args.force_env:
+            _fail(f"目标库已登记为 {recorded} 环境，与 --env {args.env} 不符。"
+                  f"确认无误请加 --force-env")
+        if not recorded:
+            print(f"目标库首次使用，将登记为 {args.env} 环境")
+
+        if args.schema_only or args.dry_run:
+            print("\n[dry-run] schema 已建好，未搬数据。")
+            if args.dry_run:
+                print("  去掉 --dry-run 即正式搬运。")
+            return
+
+        print("\n开始搬运（单事务，失败自动回滚）…")
+        t0 = time.time()
+        stats, ok = copy_and_verify(args.sqlite, tables, "replace")
+        print_stats(stats)
+        if not ok:
+            _fail("搬运后校验不一致 —— 事务已回滚，目标库保持原样。请把上面的表格发给我排查")
+        print(f"\n搬运完成，用时 {time.time() - t0:.1f}s，逐表校验一致 OK")
+
+        # 4) 写库标签与版本
+        src = sqlite3.connect(_readonly_uri(args.sqlite), uri=True)
+        try:
+            src_id = None
+            try:
+                row = src.execute(
+                    "SELECT value FROM app_meta WHERE key='deployment_id'").fetchone()
+                src_id = row[0] if row else None
+            except sqlite3.Error:
+                pass
+        finally:
+            src.close()
+        db_config.meta_set("deployment_env", args.env)
+        db_config.meta_set("deployment_id", src_id or uuid.uuid4().hex)
+        db_config.meta_set("deployment_claimed_at",
+                           time.strftime("%Y-%m-%d %H:%M:%S"))
+        from core.models import CURRENT_SCHEMA_VERSION
+        db_config.meta_set("schema_version", str(CURRENT_SCHEMA_VERSION))
+        print(f"已登记库环境标签: {args.env}（部署标识 {db_config.meta_get('deployment_id')}）")
+        print("\n下一步：把 .env 的 DEPLOY_ENV/DB_* 配好，重启 web_server 即连到新库。")
+
+
+if __name__ == "__main__":
+    main()

scripts/regression_test.py

@@ -21,29 +21,79 @@ import signal
 # 项目根加入 sys.path（脚本在 scripts/ 下运行，保证可 import web_server/config）
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
+# Windows 控制台默认 GBK：汇总里的 ⚠/❌/✅ 会抛 UnicodeEncodeError，
+# 而且崩在"打印汇总"这一步 —— 看起来像脚本挂了、其实探测已经全跑完
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
 # 测试模式：禁用 cron 调度器（否则 test_client 会按 DB 里的任务 cron 真跑任务，
 # 干扰回归/占用设备——实测 ocr关键字任务每 30 分钟触发导致回归超时）
 os.environ["DISABLE_SCHEDULER"] = "1"
 
-# 单接口超时保护：adb 相关接口可能慢（连接/查询设备），给足时间
+# 单接口超时保护：adb 相关接口可能慢（连接/查询设备），给足时间。
-signal.alarm(300)
+# Windows 没有 signal.alarm（会 AttributeError 直接崩），那里就靠调用方自己掐时间。
+if hasattr(signal, "alarm"):
+    signal.alarm(300)
 
 from web_server import app  # noqa: E402  （导入即完成 app 装配，与生产一致）
 
+# ================== 安全闸：绝不对生产库跑写操作 ==================
+# 本脚本会发真实写请求（设备池增删、剪贴板注入、亮灭屏…）。跑在连生产库的配置上
+# 就是拿正式数据做实验——直接拒绝启动。
+from core import db_config  # noqa: E402
+
+if db_config.DEPLOY_ENV == "prod":
+    print("=" * 70)
+    print("拒绝运行：当前 .env 声明 DEPLOY_ENV=prod，本脚本会发真实写请求。")
+    print("回归测试请在 dev 环境跑（或先把 .env 指向 dev 库/临时库）。")
+    print("=" * 70)
+    sys.exit(3)
+with app.app_context():
+    _labeled = db_config.meta_get("deployment_env")
+    if _labeled == "prod":
+        print("=" * 70)
+        print("拒绝运行：目标库 %s 被登记为 prod 环境（app_meta.deployment_env）。"
+              % db_config.describe_target())
+        print("回归测试会写数据，不能对生产库执行。")
+        print("=" * 70)
+        sys.exit(3)
+
 
 # 流式/二进制接口：无法用普通 GET 断言，跳过（已有单独验证路径）
 _SKIP_PREFIXES = (
     "/api/screen/stream", "/api/screen/thumb",
     "/api/uiauto/screenshot", "/api/device/screenshot",
 )
+# 测试用的目标设备：运行期从设备池里挑一台真实的（占位串是池空时的兜底）。
+# 以前这里写死 Tailscale 时代的 100.100.10.11:5555，设备早换了 → 每次回归都要等
+# 好几轮 30s 的 adb connect 超时，还会误报"关键 POST 失败"。
+_TEST_SERIAL = "100.100.10.11:5555"
+_SERIAL_PH = "@SERIAL@"
+
+
+def _pick_serial():
+    """从设备池里挑一台启用的设备当测试目标（池空则返回占位串）。"""
+    try:
+        from core.models import Device, db as _db
+        with app.app_context():
+            d = _db.session.query(Device).filter(Device.enabled.is_(True)).order_by(
+                Device.serial).first()
+            return d.serial if d else _TEST_SERIAL
+    except Exception:
+        return _TEST_SERIAL
+
+
 # 关键业务 POST：用真实参数验证（这些覆盖了核心链路）
 _KEY_POSTS = [
     ("一键亮屏", "/api/device/screen_all", {"mode": "on"}),
     ("一键息屏", "/api/device/screen_all", {"mode": "off"}),
     ("剪贴板注入", "/api/tools/clipboard/set",
-     {"serials": ["100.100.10.11:5555"], "text": "回归测试"}),
+     {"serials": [_SERIAL_PH], "text": "回归测试"}),
     ("测试步骤(wait)", "/api/steps/test",
-     {"serial": "100.100.10.11:5555",
+     {"serial": _SERIAL_PH,
       "step": {"type": "wait", "label": "等待", "params": {"max": 1, "min": 1, "probability": 100}}}),
     ("adb 终端执行", "/api/adb/cmd", {"cmd": "adb devices"}),
     ("adb 红线拦截", "/api/adb/cmd", {"cmd": "adb kill-server"}),
@@ -53,10 +103,21 @@ _KEY_POSTS = [
 _EXPECT_REJECT = {"/api/adb/cmd"}
 
 
+def _sub_serial(obj):
+    """把请求体里的 @SERIAL@ 占位替换成运行期选定的设备串（支持嵌套 list/dict）。"""
+    if isinstance(obj, str):
+        return _TEST_SERIAL if obj == _SERIAL_PH else obj
+    if isinstance(obj, list):
+        return [_sub_serial(x) for x in obj]
+    if isinstance(obj, dict):
+        return {k: _sub_serial(v) for k, v in obj.items()}
+    return obj
+
+
 def _fill_path_params(rule):
     """把路由路径参数 <xxx> 替换为测试值（serial 用真实设备）。"""
     url = rule
-    url = url.replace("<serial>", "100.100.10.11:5555")
+    url = url.replace("<serial>", _TEST_SERIAL)
     url = url.replace("<apk_id>", "x")
     url = url.replace("<action_id>", "x")
     url = url.replace("<device_id>", "x")
@@ -135,7 +196,12 @@ def main():
     print(f"写操作路由: {len(write_rules)} 个（空 body 探测）")
 
     # ========== 3. 关键业务 POST（真实参数） ==========
+    global _TEST_SERIAL
+    _TEST_SERIAL = _pick_serial()
+    print(f"测试目标设备: {_TEST_SERIAL}")
     for name, url, body in _KEY_POSTS:
+        # 占位符换成运行期挑到的真实设备（含嵌套列表）
+        body = _sub_serial(body)
         try:
             r = c.post(url, json=body, headers=H)
             j = r.get_json() if r.is_json else None

scripts/sql/init_mysql_5.7.sql

@@ -0,0 +1,50 @@
+-- ==============================================================================
+-- auto_control —— MySQL 5.7 环境初始化（建库 + 建账号 + 授权）
+--
+-- 用法（在 MySQL 主机上以 root 执行）：
+--     mysql -uroot -p < scripts/sql/init_mysql_5.7.sql
+--
+-- 建两个库，与 .env 的 DEPLOY_ENV 一一绑定（core/db_config.py 会强制校验）：
+--     auto_control_dev  ← 本地开发机（DEPLOY_ENV=dev）
+--     auto_control      ← 生产 220 容器（DEPLOY_ENV=prod）
+--
+-- 字符集固定 utf8mb4 + utf8mb4_bin：
+--   * utf8mb4：中文/emoji 都不能丢（MySQL 的 "utf8" 是 3 字节残缺版）
+--   * _bin   ：逐码点比较（大小写敏感），等价 SQLite 的字节序语义。
+--              用默认的 utf8mb4_general_ci 会让 Admin/admin、Phone1/phone1 被判重复，
+--              唯一索引与等值查询语义全变。
+--
+-- ⚠️ 执行前把下面的 <改我> 换成强口令，并把主机段按实际情况收紧：
+--     '192.168.20.%'  局域网
+--     '100.100.10.%'  Tailscale（若走 tailnet 连库）
+--     220 容器是 host 网络，出口 IP 取决于路由，两条都要覆盖；图省事可用 '%' + 强口令。
+-- ==============================================================================
+
+CREATE DATABASE IF NOT EXISTS auto_control
+  DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
+CREATE DATABASE IF NOT EXISTS auto_control_dev
+  DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
+
+-- 一个专用账号，只授权这两个库（不用 root 跑应用）
+CREATE USER IF NOT EXISTS 'auto_control'@'%' IDENTIFIED BY '<改我>';
+GRANT ALL PRIVILEGES ON auto_control.*     TO 'auto_control'@'%';
+GRANT ALL PRIVILEGES ON auto_control_dev.* TO 'auto_control'@'%';
+FLUSH PRIVILEGES;
+
+-- 授权说明：
+--   * 应用需要 DDL 权限（建表 / 补列 / 建生成列与索引），所以给的是 ALL；
+--     若你的 DBA 只肯给 DML，就先用下面的「可选」段预建 schema，再只授
+--     SELECT/INSERT/UPDATE/DELETE。
+--   * 表结构由平台启动时自动创建（db.create_all + _sync_columns），
+--     正常情况下不需要手工建表。
+
+-- ---------------------------------------------------------------------------
+-- 可选：只给 DML 权限时，先让平台在别的环境把 schema 建好，再由本脚本导入。
+-- 也可用迁移脚本的「先建 schema」路径：
+--     python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev --schema-only
+-- ---------------------------------------------------------------------------
+
+-- 校验（执行完可以跑一下）：
+--   SELECT schema_name, default_character_set_name, default_collation_name
+--     FROM information_schema.schemata WHERE schema_name LIKE 'auto_control%';
+--   SHOW GRANTS FOR 'auto_control'@'%';

scripts/start.sh

@@ -16,7 +16,7 @@ python3 - <<'PY'
 import importlib.util, sys
 mods = ("flask", "flask_login", "flask_sqlalchemy", "apscheduler",
         "uiautomator2", "uiautodev", "rapidocr_onnxruntime", "PIL",
-        "fastmcp")
+        "fastmcp", "pymysql", "qrcode")
 if all(importlib.util.find_spec(m) for m in mods):
     try:
         import cv2
@@ -78,4 +78,7 @@ if [ -f mcp_server/mcp_server.py ] && [ "${MCP_ENABLED:-1}" = "1" ]; then
     python3 -m mcp_server.mcp_server > /tmp/mcp_server.log 2>&1 &
 fi
 
+# 启动前把"连的是哪个库"打在最显眼的位置（web_server 启动横幅是权威，
+# 这里再报一次是防止日志只截到容器入口这几行时看不出环境）
+echo "[start] DEPLOY_ENV=${DEPLOY_ENV:-<未设置，默认 dev>}  DB_NAME=${DB_NAME:-<未设置>}  DB_HOST=${DB_HOST:-<未设置>}"
 exec python -u web_server.py

static/admin/admin.js

@@ -91,22 +91,85 @@ async function deleteGroup(name){
 }
 
 // ================== Tab 4: 日志 ==================
+// 条件（文件/关键字/级别/时间）→ /api/logs（结构化行）；下载走 /api/logs/download
+function _logParams(){
+  const v=id=>document.getElementById(id);
+  const p=new URLSearchParams();
+  p.set('file', v('log-file').value||'');
+  p.set('lines', v('log-lines').value);
+  const q=v('log-q').value.trim();       if(q)p.set('q',q);
+  const lv=v('log-level').value;         if(lv)p.set('level',lv);
+  const since=v('log-since').value;      if(since)p.set('since',since);
+  const until=v('log-until').value;      if(until)p.set('until',until);
+  return p;
+}
+
+// 文件下拉由接口返回的清单渲染（写死的选项会漏掉新增模块，如 notify.log）
+function _renderLogFiles(files,current){
+  const sel=document.getElementById('log-file');
+  const sig=(files||[]).map(f=>f.name).join(',');
+  if(sel.dataset.sig!==sig){        // 只在清单变化时重建，避免打断当前选择
+    sel.dataset.sig=sig;
+    sel.innerHTML=(files||[]).map(f=>
+      '<option value="'+esc(f.name)+'">'+esc(f.label)+'</option>').join('');
+  }
+  if(current)sel.value=current;
+}
+
 async function loadLogs(){
-  const file=document.getElementById('log-file').value;
-  const lines=document.getElementById('log-lines').value;
-  const r=await apiGet('/api/logs?file='+encodeURIComponent(file)+'&lines='+lines);
-  if(!r||!r.ok)return;
-  const content=r.content||'';
-  // 简单着色
-  const colored=esc(content)
-    .replace(/\[ERROR\]/g,'<span class="log-err">[ERROR]</span>')
-    .replace(/\[WARNING\]/g,'<span class="log-warn">[WARNING]</span>')
-    .replace(/\[INFO\]/g,'<span class="log-info">[INFO]</span>');
-  document.getElementById('log-content').innerHTML=colored||'<span class="text-muted">（空）</span>';
-  document.getElementById('log-hint').textContent=file+' · '+content.split('\n').length+' 行';
-  // 自动滚动到底部
   const el=document.getElementById('log-content');
-  el.scrollTop=el.scrollHeight;
+  if(!el)return;
+  // 用户正往上翻看历史时不要被自动刷新拽回底部
+  const atBottom=el.scrollHeight-el.scrollTop-el.clientHeight<40;
+  const r=await apiGet('/api/logs?'+_logParams().toString());
+  if(!r)return;
+  _renderLogFiles(r.files,r.file);
+  const hint=document.getElementById('log-hint');
+  if(!r.ok){
+    el.innerHTML='<span class="text-muted">'+esc(r.error||'读取失败')+'</span>';
+    hint.textContent='';
+    return;
+  }
+  const rows=r.rows||[], kw=document.getElementById('log-q').value.trim();
+  el.innerHTML=rows.length
+    ? rows.map(row=>_logRowHtml(row,kw)).join('')
+    : '<span class="text-muted">（无匹配行）</span>';
+  let text=r.file+' · 命中 '+r.matched+' 行'
+    +(rows.length<r.matched?'（显示最近 '+rows.length+' 行）':'')
+    +' · 已扫描 '+r.scanned+' 行';
+  if(r.truncated)text+=' · 更早的命中已省略：缩小时间范围或加关键字';
+  hint.textContent=text;
+  if(atBottom)el.scrollTop=el.scrollHeight;
+}
+
+function _logRowHtml(r,kw){
+  const lvl=(r.level||'').toUpperCase();
+  const cls=lvl==='ERROR'||lvl==='CRITICAL'?'log-err'
+           :lvl==='WARNING'?'log-warn':'log-info';
+  // 续行（traceback 缩进行）没有前缀，只缩进显示消息体
+  const head=r.cont?'':esc(r.ts)+' <span class="'+cls+'">['+esc(lvl)+']</span> ['
+                    +esc(r.module)+'] ';
+  return '<div class="log-row'+(r.cont?' log-cont':'')+'">'+head+_logHl(r.msg,kw)+'</div>';
+}
+
+// 关键字高亮：**先转义再匹配**——反过来的话消息里的 < > 会先被吃成实体
+function _logHl(text,kw){
+  const safe=esc(text||'');
+  if(!kw)return safe;
+  const k=esc(kw);
+  if(!k)return safe;
+  const re=new RegExp(k.replace(/[.*+?^${}()|[\]\\]/g,'\\$&'),'gi');
+  return safe.replace(re,m=>'<span class="log-hit">'+m+'</span>');
+}
+
+function downloadLogs(){
+  window.location='/api/logs/download?'+_logParams().toString();
+}
+
+function resetLogFilters(){
+  ['log-q','log-since','log-until'].forEach(id=>{document.getElementById(id).value='';});
+  document.getElementById('log-level').value='';
+  loadLogs();
 }
 
 function toggleLogAuto(){

static/admin/agent.js

@@ -55,6 +55,9 @@ function initAgentChat(){
 function restoreRunningFlow(){
   apiGet('/api/agent/run').then(r=>{
     if(!r||!r.ok) return;
+    // 建任务模式（designer）的运行由「AI 建任务」子页订阅。这里必须让开：
+    // 服务端一个 run 只有一个事件队列，两个 EventSource 同时消费会互相瓜分事件。
+    if(r.mode === 'designer') return;
     if(r.state === 'running' && r.run_id){
       setRunning(true);
       listenStream(r.run_id);
@@ -116,14 +119,18 @@ function pollRunState(){
   apiGet('/api/agent/run').then(r=>{
     if(!r||!r.ok)return;
     const running = r.state === 'running';
-    document.getElementById('agent-running-tag').style.display = running ? 'inline' : 'none';
+    // 运行槽是全平台唯一的：建任务探索在跑时，聊天页也不能再发起（如实显示）
+    const tag = document.getElementById('agent-running-tag');
+    tag.style.display = running ? 'inline' : 'none';
+    tag.textContent = running && r.mode === 'designer' ? '● 建任务探索中' : '● 运行中';
     document.getElementById('btn-agent-stop').style.display = running ? 'inline-block' : 'none';
     const hint = document.getElementById('agent-target-hint');
     if(hint){
+      const dev = r.serial ? ' · ' + _agentTargetText(r.serial) : '';
       hint.textContent = running
-        ? ('⏳ 运行中' + (r.started ? ' ' + r.started + ' 起' : '')
+        ? ((r.mode === 'designer' ? '⏳ AI 正在「AI 建任务」页探索设备'
-           + (r.serial ? ' · ' + _agentTargetText(r.serial) : '')
+                                  : '⏳ 运行中' + (r.started ? ' ' + r.started + ' 起' : ''))
-           + '：' + (r.prompt||'').slice(0,70))
+           + dev + '：' + (r.prompt || '').slice(0, 70))
         : (document.getElementById('agent-target-select').value
            ? '将操作：' + _agentTargetText(document.getElementById('agent-target-select').value)
            : '');
@@ -570,7 +577,9 @@ function listenStream(runId){
       setTimeout(()=>{
         if(!_agentStream && _agentBusy){
           apiGet('/api/agent/run').then(r=>{
-            if(r&&r.ok&&r.state==='running'&&r.run_id) listenStream(r.run_id);
+            // 建任务模式（designer）归「AI 建任务」子页订阅，这里同样要让开
+            if(r&&r.ok&&r.state==='running'&&r.run_id&&r.mode!=='designer')
+              listenStream(r.run_id);
           });
         }
       }, 5000);

static/admin/apps.js

@@ -29,15 +29,22 @@ async function loadApks(){
   await fillAppsDeviceList();
 }
 function renderApkRow(a){
+  // 一行 = 一个应用（列表已按包名合并，显示最新版）；旧版本给个数提示 + 清理入口
+  const n=a.version_count||1;
+  const verCell=(a.version_name?esc(a.version_name):'-')+
+    (n>1?' <span style="font-size:11px;color:#94a3b8">（另有 '+(n-1)+' 个旧版本）</span>':'');
+  const clean=n>1?'<button class="btn btn-xs" onclick="cleanOldVersions(\''+a.id+'\',\''+esc(a.display_name||'')+'\','+(n-1)+')" title="只保留最新版，删掉旧版本">清理旧版本</button> ':'';
+  const title=n>1?('共 '+n+' 个版本：'+ (a.versions||[]).map(v=>v.version_name||'?').join(' / ')):'';
   return '<tr>'+
     '<td><strong>'+esc(a.display_name||'(未命名)')+'</strong></td>'+
     '<td style="font-family:monospace;font-size:12px;color:#64748b">'+esc(a.package_name||'-')+'</td>'+
-    '<td>'+(a.version_name?esc(a.version_name):'-')+'</td>'+
+    '<td title="'+esc(title)+'">'+verCell+'</td>'+
     '<td>'+fmtSize(a.size)+'</td>'+
     '<td style="font-size:12px;color:#94a3b8">'+esc(a.upload_time)+'</td>'+
     '<td>'+
       '<button class="btn btn-primary btn-xs" onclick="openInstallModal(\''+a.id+'\')">安装</button> '+
-      '<button class="btn btn-danger btn-xs" onclick="deleteApk(\''+a.id+'\')">删除</button>'+
+      clean+
+      '<button class="btn btn-danger btn-xs" onclick="deleteApk(\''+a.id+'\','+n+')">删除</button>'+
     '</td>'+
   '</tr>';
 }
@@ -50,7 +57,7 @@ async function fillAppsDeviceList(){
   const cur=sel.value;
   const devices=(sr.devices||[]).filter(d=>d.present);
   sel.innerHTML='<option value="">选择设备...</option>'+devices.map(d=>
-    '<option value="'+esc(d.serial)+'">'+esc((d.serial||'').replace(/:5555$/,'')+' ('+(d.device_name||d.model||'未知设备')+')')+'</option>'
+    '<option value="'+esc(d.serial)+'">'+esc(devText(d.device_name||d.name, d.serial))+'</option>'
   ).join('');
   if(cur)sel.value=cur;
 }
@@ -140,9 +147,20 @@ async function uploadApk(input){
   input.value='';
 }
 
-async function deleteApk(id){
+async function deleteApk(id, versionCount){
-  if(!confirm('确认删除此APK文件？'))return;
+  const n=versionCount||1;
-  const r=await apiDelete('/api/apks/'+id);
+  const msg = n>1
+    ? ('确认删除这个应用？\n\n它一共有 '+n+' 个版本，会**全部**删掉（想只留最新版请用「清理旧版本」）。')
+    : '确认删除此APK文件？';
+  if(!confirm(msg))return;
+  // 一行 = 一个应用 → 删除即删掉该包的所有版本
+  const r=await apiDelete('/api/apks/'+id+'?scope=package');
+  handleResult(r,loadApks);
+}
+
+async function cleanOldVersions(id, name, oldCount){
+  if(!confirm('清理「'+name+'」的 '+oldCount+' 个旧版本？\n\n只保留最新版，旧版本文件会被删除。'))return;
+  const r=await apiDelete('/api/apks/'+id+'?scope=older');
   handleResult(r,loadApks);
 }
 
@@ -168,8 +186,8 @@ async function openInstallModal(apkId){
       online.map(d=>{
         const isUsb=d.source==='usb';
         const st='<span class="label label-'+(isUsb?'primary':'default')+'" style="margin-left:6px">'+(isUsb?'本地USB':(d.source==='pool'?'设备池':'adb'))+'</span>';
-        // serial 唯一，显示 IP + 型号便于区分同型号设备
+        // 一律「名称 · 地址」——同型号多台时靠名称区分；没有名称的设备（不在池里）只显示地址
-        const label=(d.serial||'').replace(/:5555$/,'')+' · '+(d.model||(isUsb?'USB 有线设备':'设备'));
+        const label=devText(d.name, d.serial);
         return '<label><input type="checkbox" value="'+esc(d.serial)+'" checked>'+esc(label)+st+'</label>';
       }).join('')+
     '</div>';
@@ -210,7 +228,7 @@ function showInstallProgress(){
     '<button class="btn" onclick="closeInstallModal()" id="install-close-btn" style="display:none">关闭</button>';
   pollInstallStatus();
   if(_installTimer)clearInterval(_installTimer);
-  _installTimer=setInterval(pollInstallStatus,3000);
+  _installTimer=setInterval(pollInstallStatus,1500);
 }
 
 async function pollInstallStatus(){
@@ -226,10 +244,13 @@ async function pollInstallStatus(){
   const items=st.items||{};
   const itemRows=Object.entries(items).map(([serial,info])=>{
     const s=SS[info.status]||{t:info.status,c:'default'};
+    // 推送进度带百分比时补一条细进度条（大包传输要一两分钟，光有文字不够直观）
+    const m=/推送中 (\d+)%/.exec(info.msg||'');
+    const bar=m?'<div class="progress" style="height:6px;margin-top:4px;max-width:240px"><div class="progress-bar" style="width:'+m[1]+'%"></div></div>':'';
     return '<tr><td>'+esc(info.name||serial)+'</td>'+
       '<td style="font-family:monospace;font-size:11px;color:#94a3b8">'+esc(serial)+'</td>'+
       '<td><span class="label label-'+s.c+'">'+s.t+'</span></td>'+
-      '<td style="font-size:12px;color:#64748b">'+esc(info.msg||'')+'</td></tr>';
+      '<td style="font-size:12px;color:#64748b">'+esc(info.msg||'')+bar+'</td></tr>';
   }).join('');
 
   const pct=st.total>0?Math.round((st.success+st.failed+st.skipped)*100/st.total):0;
@@ -262,3 +283,77 @@ function closeInstallModal(){
 }
 
 
+
+// ================== 设备端应用商店（Agent 直连安装） ==================
+// 设备上的 Agent 拉 /api/device/agent/bootstrap 拿清单 → 自己下载 → 自己调系统安装器。
+// 因为安装由设备上的 App 发起，走普通应用安装流程，不会触发 MIUI 的「USB 安装」拦截。
+let _storeToken='';
+
+async function loadAgentStore(){
+  try{
+    const cfg=await (await fetch('/api/agent-store/config',{headers:_csrfHeaders()})).json();
+    if(cfg&&cfg.ok){
+      _storeToken=cfg.token||'';
+      const en=document.getElementById('store-enabled');
+      if(en)en.checked=!!cfg.enabled;
+      const u=document.getElementById('store-url');
+      if(u)u.value=cfg.base_url_hint||'';
+      const t=document.getElementById('store-token');
+      if(t)t.value=_storeToken||'(未生成，勾选启用后自动生成)';
+    }
+    const d=await (await fetch('/api/agent-store/logs?limit=30',{headers:_csrfHeaders()})).json();
+    renderStoreLogs((d&&d.logs)||[]);
+  }catch(e){ /* 面板没打开时静默 */ }
+}
+
+function renderStoreLogs(logs){
+  const tb=document.getElementById('tb-store-logs');
+  if(!tb)return;
+  if(!logs.length){
+    tb.innerHTML='<tr><td colspan="5" class="empty">暂无记录（设备还没从商店装过东西）</td></tr>';
+    return;
+  }
+  const act={download:'⬇ 已下载',install_ok:'✅ 安装成功',install_fail:'❌ 安装失败'};
+  tb.innerHTML=logs.map(l=>{
+    const app=[l.display_name||l.package_name||l.apk_id,
+               l.version_name?('v'+l.version_name):''].filter(Boolean).join(' ');
+    const cls=l.action==='install_fail'?'style="color:#b42318"':(l.action==='install_ok'?'style="color:#067647"':'');
+    return '<tr><td>'+esc(l.created_at||'')+'</td><td>'+esc(l.device_name||l.serial||'-')+'</td>'+
+           '<td title="'+esc(l.package_name||'')+'（'+esc(l.apk_id||'')+'）">'+esc(_cut(app,30))+'</td>'+
+           '<td '+cls+'>'+esc(act[l.action]||l.action||'')+'</td>'+
+           '<td>'+esc(_cut(l.message||'',60))+'</td></tr>';
+  }).join('');
+}
+
+async function toggleAgentStore(on){
+  const r=await apiPost('/api/agent-store/config',{enabled:!!on});
+  if(!r)return;
+  if(r.ok){
+    showToast(on?'设备端商店已启用':'设备端商店已停用','success');
+    loadAgentStore();
+  }else{
+    showToast(r.error||'设置失败','error');
+    document.getElementById('store-enabled').checked=!on;
+  }
+}
+
+async function regenStoreToken(){
+  if(!confirm('重置设备令牌？\n\n所有已配置该令牌的设备会立即失效，需要在设备端 Agent 里重新填新令牌。'))return;
+  const r=await apiPost('/api/agent-store/config',{regenerate_token:true});
+  if(r&&r.ok){showToast('令牌已重置','success');loadAgentStore();}
+  else if(r)showToast(r.error||'重置失败','error');
+}
+
+function copyStoreToken(){
+  if(!_storeToken){showToast('还没有令牌（先启用设备端商店）','error');return;}
+  const done=()=>showToast('令牌已复制','success');
+  if(navigator.clipboard&&navigator.clipboard.writeText){
+    navigator.clipboard.writeText(_storeToken).then(done).catch(()=>{
+      window.prompt('手动复制令牌：',_storeToken);
+    });
+  }else{
+    window.prompt('手动复制令牌：',_storeToken);
+  }
+}
+
+function _cut(s,n){s=String(s==null?'':s);return s.length>n?(s.slice(0,n-1)+'…'):s;}

static/admin/base.js

@@ -104,17 +104,26 @@ function showTab(name){
   if(_discoveryTimer){clearInterval(_discoveryTimer);_discoveryTimer=null;}
   // 按需加载数据
   if(name==='monitor'){loadMonitor();_monitorTimer=setInterval(loadMonitor,5000);}
-  if(name==='tasks'){showSubTab('tasks',_activeSubs.tasks);loadTasks();loadCustomActions();}
+  if(name==='tasks'){showSubTab('tasks',_activeSubs.tasks);loadTasks();loadCustomActions();
+    if(typeof loadStepDefaults==='function')loadStepDefaults();}
   if(name==='tools'){showSubTab('tools',_activeSubs.tools);loadToolsDevices();loadAdbDevices();loadTailscaleDevices();loadApks();}
-  if(name==='logs'){loadLogs();if(document.getElementById('log-auto').checked)_logTimer=setInterval(loadLogs,3000);}
+  if(name==='logs'){
-  if(name==='agent' && typeof initAgentChat==='function') initAgentChat();
+    showSubTab('logs', _activeSubs.logs||'files');   // 文件日志 / 步骤明细
+    if((_activeSubs.logs||'files')==='files'
+       && document.getElementById('log-auto').checked)_logTimer=setInterval(loadLogs,3000);
+  }
+  if(name==='agent'){
+    showSubTab('agent', _activeSubs.agent||'chat');   // 聊天 / AI 建任务
+    if(typeof initAgentChat==='function') initAgentChat();
+  }
   if(name==='users')loadUsers();
   if(name==='system'){showSubTab('system',_activeSubs.system||'backup');}
 }
 
 // ================== 页内子分栏（任务/工具 通用） ==================
 // 每个带子分栏的 Tab 记住上次选中的子分栏，切走再切回来保持原位
-let _activeSubs = {tasks: 'plan', tools: 'clipboard', system: 'backup'};
+let _activeSubs = {tasks: 'plan', tools: 'clipboard', system: 'backup', agent: 'chat',
+                   logs: 'files'};
 let _discoveryTimer = null;   // 设备自动发现 10s 轮询（仅 devpool 子分栏激活时）
 
 function showSubTab(tabId, name){
@@ -122,7 +131,13 @@ function showSubTab(tabId, name){
   const tab = document.getElementById('tab-'+tabId);
   tab.querySelectorAll('.sub-tab').forEach(b=>b.classList.toggle('active', b.dataset.sub===name));
   tab.querySelectorAll('.sub-panel').forEach(p=>p.classList.toggle('active', p.id===tabId+'-sub-'+name));
+  if(tabId==='agent' && name==='taskgen' && typeof initTaskGen==='function') initTaskGen();
+  if(tabId==='system' && name==='notify' && typeof loadNotifyPanel==='function') loadNotifyPanel();
+  if(tabId==='logs' && name==='files' && typeof loadLogs==='function') loadLogs();
+  if(tabId==='logs' && name==='steps' && typeof loadStepLogs==='function') loadStepLogs(true);
+  if(tabId==='tasks' && name==='actioncfg' && typeof loadActionConfig==='function') loadActionConfig();
   if(name==='groups' && typeof loadGroups==='function') loadGroups();
+  if(name==='apks' && typeof loadAgentStore==='function') loadAgentStore();
   if(name==='devpool' && typeof loadDevPool==='function'){
     loadDevPool();
     if(typeof loadDiscovery==='function'){

static/admin/editor.js

@@ -5,8 +5,8 @@ var STEP_LIB=[
   {type:'click',label:'点击元素',icon:'✦',cat:'interact',params:{selector_type:'xpath',selector_value:'',wait_timeout:2}},
   {type:'click_xy',label:'点击坐标',icon:'🎯',cat:'interact',params:{x:50,y:50}},
   {type:'long_click',label:'长按元素',icon:'👆',cat:'interact',params:{selector_type:'xpath',selector_value:'',duration:1.0,wait_timeout:2}},
-  {type:'swipe',label:'滑动',icon:'↕',cat:'interact',params:{direction:'up',duration_min:0.25,duration_max:0.50}},
+  {type:'swipe',label:'滑动',icon:'↕',cat:'interact',params:{direction:'up',duration_min:0.25,duration_max:0.50,distance_ratio:0.6,jitter:0.15,humanize:true}},
-  {type:'swipe_until',label:'滑动直到元素',icon:'🔍',cat:'interact',params:{selector_type:'xpath',selector_value:'',direction:'up',max_swipes:8,click_when_found:true}},
+  {type:'swipe_until',label:'滑动直到元素',icon:'🔍',cat:'interact',params:{selector_type:'xpath',selector_value:'',direction:'up',max_swipes:8,click_when_found:true,duration_min:0.25,duration_max:0.50,distance_ratio:0.6,jitter:0.15,humanize:true}},
   {type:'input_text',label:'输入文字',icon:'⌨',cat:'interact',params:{mode:'random',texts:'你好\n有趣\n支持',fixed_text:'',clear_first:true}},
   {type:'clipboard',label:'剪贴板注入',icon:'📋',cat:'interact',params:{text:'',paste:true}},
   {type:'key_event',label:'按键',icon:'⌨️',cat:'interact',params:{key:'back'}},
@@ -19,8 +19,13 @@ var STEP_LIB=[
   {type:'wait_el',label:'等待元素',icon:'⏳',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:10}},
   {type:'loop',label:'循环块',icon:'↻',cat:'flow',params:{loop_mode:'rounds',max_iterations:10,loop_duration:600,children:[]}},
   {type:'group',label:'动作组',icon:'📦',cat:'flow',params:{children:[]}},
-  {type:'if_el',label:'条件判断',icon:'❓',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:3,ocr_click:false,then:[],else:[]}}
+  {type:'if_el',label:'条件判断',icon:'❓',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:3,ocr_click:false,then:[],else:[]}},
+  {type:'notify',label:'发通知',icon:'🔔',cat:'flow',params:{title:'',message:'',level:'info'}},
+  {type:'stop_self',label:'停止本设备',icon:'⛔',cat:'flow',params:{reason:''}},
+  {type:'gesture',label:'录制手势',icon:'⏺',cat:'interact',params:{points:[],speed:1.0}}
 ];
+// 步骤默认值（「任务 → 动作配置」页配置，见 core/step_defaults.py）；新建步骤时预填
+let _stepDefaults = null;
 var STEP_LIB_CATS=[['interact','交互操作'],['screen','屏幕与App'],['flow','流程控制']];
 var _customActions=[]; // 后端加载的自定义动作
 var _stepIdCounter=0;
@@ -46,19 +51,31 @@ function _findLib(type){return STEP_LIB.find(function(s){return s.type===type;})
 // 选择器组件（类型下拉 + 值输入 + 抓取元素 + 测试按钮），click/long_click/swipe_until/wait_el/if_el 复用
 // withOcr=true 时额外提供 OCR识别 选项（图片/画布里的文字，仅条件判断支持）
 function _selRowHtml(p, extra, withOcr){
-  var types=withOcr?['xpath','description','text','resourceId','descriptionContains','className','ocr']:
+  // withOcr（条件判断用）额外提供"屏幕状态 / 前台App"两类非元素条件
+  var types=withOcr?['xpath','description','text','resourceId','descriptionContains','className','ocr','screen','foreground']:
     ['xpath','description','text','resourceId','descriptionContains','className'];
   var labels={xpath:'xpath',description:'description',text:'text',resourceId:'resourceId',
-    descriptionContains:'descriptionContains',className:'className',ocr:'OCR识别'};
+    descriptionContains:'descriptionContains',className:'className',ocr:'OCR识别',
+    screen:'屏幕状态',foreground:'前台App是'};
   var opts=types.map(function(d){
     return '<option value="'+d+'"'+(p.selector_type===d?' selected':'')+'>'+labels[d]+'</option>';}).join('');
-  var toggle=withOcr?' onchange="_stepEditor._toggleOcrMode(this)"':'';
+  var toggle=withOcr?' onchange="_stepEditor._condTypeChanged(this)"':'';
   var pick=_can('devices')?'<button class="btn btn-xs btn-pick" onclick="_stepEditor.openPicker(this)">抓取元素</button>':'';
   var test=_can('devices')?'<button class="btn btn-xs" onclick="_stepEditor._testStep(this)" title="在设备上试执行本步骤，验证选择器是否命中">测试</button>':'';
+  var isScreen=p.selector_type==='screen', isFg=p.selector_type==='foreground';
+  var valLabel=isScreen?'屏幕状态':(isFg?'前台包名':'选择器值');
+  var valHtml;
+  if(isScreen){
+    valHtml='<select class="form-control" data-key="selector_value" style="max-width:140px">'+
+      '<option value="off"'+(p.selector_value!=='on'?' selected':'')+'>熄屏时就命中</option>'+
+      '<option value="on"'+(p.selector_value==='on'?' selected':'')+'>亮屏时就命中</option></select>';
+  }else{
+    valHtml='<input type="text" class="form-control" data-key="selector_value" value="'+esc(p.selector_value||'')+
+      '" placeholder="'+(isFg?'如 com.ss.android.ugc.aweme':'如 点赞')+'">'+(isFg?'':pick+test);
+  }
   return '<div class="form-row"><div class="form-group"><label>选择器类型</label><select class="form-control" data-key="selector_type"'+toggle+'>'+opts+'</select></div>'+
-    '<div class="form-group" style="grid-column:span 2"><label>选择器值</label><div class="sel-picker">'+
+    '<div class="form-group" style="grid-column:span 2"><label>'+valLabel+'</label><div class="sel-picker">'+
-    '<input type="text" class="form-control" data-key="selector_value" value="'+esc(p.selector_value||'')+'" placeholder="如 点赞">'+pick+test+
+    valHtml+'</div></div></div>'+(extra||'');
-    '</div></div></div>'+(extra||'');
 }
 
 // 加载自定义动作库
@@ -69,6 +86,22 @@ function _loadCustomActions(){
   }).catch(function(){});
 }
 
+
+// 「拟人」开关 + 抖动幅度（滑动类步骤共用；见 core/humanize.py）
+function _humanizeChkHtml(p){
+  return '<div class="form-row"><div class="form-group form-check">'
+    +'<input type="checkbox" data-key="humanize" '+(p.humanize!==false?'checked':'')+'>'
+    +'<label>拟人轨迹（弧线）</label></div>'
+    +'<div class="form-group"><label>抖动幅度</label><input type="number" class="form-control" data-key="jitter" value="'
+    +(p.jitter!=null?p.jitter:0.15)+'" step="0.05" min="0" max="0.4"></div></div>';
+}
+function _humanizeRowHtml(p,extra){
+  return extra+_humanizeChkHtml(p)
+    +'<div class="help">拟人：滑动走弧线，起止点/幅度/时长每次都抖一点，并按本设备的手速与幅度偏好执行'
+    +'（每台设备风格稳定不同，批量跑时不像同步机器人）。关掉=还原成正中直线；'
+    +'抖动填 0=位置/幅度不抖（时长仍在你填的范围内随机）</div>';
+}
+
 var _stepEditor={
   _steps:[],
   _selected:[],
@@ -291,7 +324,7 @@ var _stepEditor={
       h+='<div class="help">息屏。任务结束后用，避免长时间亮屏导致烧屏/发热</div>';
     }else if(step.type==='keep_screen'){
       h+='<div class="form-group"><label>模式</label><select class="form-control" data-key="mode">'+
-        '<option value="on"'+(p.mode!=='off'?' selected':'')+'>保持亮屏（充电时屏幕常亮）</option>'+
+        '<option value="on"'+(p.mode!=='off'?' selected':'')+'>保持亮屏（把系统息屏超时顶到最大，不充电也不会黑屏）</option>'+
         '<option value="off"'+(p.mode==='off'?' selected':'')+'>恢复自动息屏</option></select></div>';
       h+='<div class="help">长任务（如养号看视频几小时）放"保持亮屏"防屏幕超时熄灭；任务结束前放"恢复自动息屏"</div>';
     }else if(step.type==='swipe'){
@@ -299,6 +332,8 @@ var _stepEditor={
         ['up','down','left','right'].map(function(d){return '<option value="'+d+'"'+(p.direction===d?' selected':'')+'>'+d+'</option>';}).join('')+'</select></div>';
       h+='<div class="form-group"><label>最短时长(秒)</label><input type="number" class="form-control" data-key="duration_min" value="'+(p.duration_min||0.25)+'" step="0.05" min="0.05"></div>';
       h+='<div class="form-group"><label>最长时长(秒)</label><input type="number" class="form-control" data-key="duration_max" value="'+(p.duration_max||0.50)+'" step="0.05" min="0.05"></div></div>';
+      h+=_humanizeRowHtml(p,'<div class="form-group"><label>幅度(屏占比)</label><input type="number" class="form-control" data-key="distance_ratio" value="'+(p.distance_ratio!=null?p.distance_ratio:0.6)+'" step="0.05" min="0.1" max="0.9"></div>');
+      h+='<div class="help">想要"照我划的那一下原样重放"，请用操作库里的《录制手势》步骤——那个是纯轨迹回放，不套这里的参数</div>';
     }else if(step.type==='click'){
       h+=_selRowHtml(p,'<div class="form-group"><label>等待超时(秒)</label><input type="number" class="form-control" data-key="wait_timeout" value="'+(p.wait_timeout||2)+'" step="0.5" min="0.5"></div>');
     }else if(step.type==='long_click'){
@@ -308,9 +343,12 @@ var _stepEditor={
       h+=_selRowHtml(p,'<div class="form-row"><div class="form-group"><label>方向</label><select class="form-control" data-key="direction">'+
         '<option value="up"'+(p.direction!=='down'?' selected':'')+'>上滑</option>'+
         '<option value="down"'+(p.direction==='down'?' selected':'')+'>下滑</option></select></div>'+
-        '<div class="form-group"><label>最多滑动次数</label><input type="number" class="form-control" data-key="max_swipes" value="'+(p.max_swipes||8)+'" min="1" max="50"></div></div>'+
+        '<div class="form-group"><label>最多滑动次数</label><input type="number" class="form-control" data-key="max_swipes" value="'+(p.max_swipes||8)+'" min="1" max="50"></div>'+
+        '<div class="form-group"><label>幅度(屏占比)</label><input type="number" class="form-control" data-key="distance_ratio" value="'+(p.distance_ratio!=null?p.distance_ratio:0.6)+'" step="0.05" min="0.1" max="0.9"></div></div>'+
         '<div class="form-group form-check"><input type="checkbox" data-key="click_when_found" '+(p.click_when_found!==false?'checked':'')+'><label>找到后点击</label></div>'+
-        '<div class="help">上滑/下滑直到目标元素出现（每次滑动后检查一次），找不到则跳过继续</div>');
+        _humanizeChkHtml(p)+
+
+        '<div class="help">上滑/下滑直到目标元素出现（每次滑动后检查一次），找不到则跳过继续。滑动同样走拟人轨迹</div>');
     }else if(step.type==='wait_el'){
       h+=_selRowHtml(p,'<div class="form-group"><label>最长等待(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||10)+'" min="1" max="120"></div>'+
         '<div class="help">等待目标元素出现（替代固定秒数等待），超时则继续</div>');
@@ -324,9 +362,41 @@ var _stepEditor={
           return '<option value="'+k[0]+'"'+(p.key===k[0]?' selected':'')+'>'+k[1]+'</option>';
         }).join('')+'</select></div>';
       h+='<div class="help">返回键用于退出评论/返回上一页，比结束App轻量</div>';
+    }else if(step.type==='notify'){
+      h+='<div class="form-group"><label>标题</label><input type="text" class="form-control" data-key="title" value="'+esc(p.title||'')+'" placeholder="如 抖音号1 掉线了（留空用任务通知）"></div>';
+      h+='<div class="form-group"><label>内容</label><textarea class="form-control" data-key="message" rows="2" style="min-height:52px">'+esc(p.message||'')+'</textarea></div>';
+      h+='<div class="form-row"><div class="form-group"><label>级别</label><select class="form-control" data-key="level">'+
+        [['info','ℹ️ 普通'],['success','✅ 正常'],['warning','⚠️ 警告'],['error','❌ 异常']].map(function(l){
+          return '<option value="'+l[0]+'"'+((p.level||'info')===l[0]?' selected':'')+'>'+l[1]+'</option>';}).join('')+
+        '</select></div></div>';
+      h+='<div class="help">推送到哪条群取决于 webhook 自己的<b>事件订阅</b>（勾了「任务自定义通知」的才收）。'
+        +'正文可用占位符：<b>{device}</b> 设备名、<b>{serial}</b> 地址、<b>{job}</b> 任务名、<b>{time}</b> 时间、'
+        +'<b>{app}</b> 当前前台包名、<b>{screen}</b> 亮屏/熄屏（后两个要查设备，不用就别写）</div>';
+    }else if(step.type==='stop_self'){
+      h+='<div class="form-group"><label>停止原因（可留空）</label><input type="text" class="form-control" data-key="reason" value="'+esc(p.reason||'')+'" placeholder="如 连续刷到广告"></div>';
+      h+='<div class="help">只停<b>本设备</b>的任务，其它设备照常；后续步骤不再执行，任务记为「被停止」而不是失败'
+        +'（不会触发失败重试）。常配合「条件判断」用：命中条件 → 先「发通知」再「停止本设备」</div>';
+    }else if(step.type==='gesture'){
+      var pts=(p.points||[]);
+      var dur=pts.length?pts[pts.length-1][2]:0;
+      h+='<div class="form-row"><div class="form-group" style="flex:2"><label>录制状态</label>'+
+        '<div style="padding:6px 0;font-size:13px">'+(pts.length
+          ? (pts.length+' 个轨迹点 · 时长 '+(dur/1000).toFixed(2)+' 秒 · 起点 ('+pts[0][0]+','+pts[0][1]+')')
+          : '<span class="text-muted">还没有录制</span>')+'</div></div>';
+      if(_can('devices')){
+        h+='<div class="form-group"><button class="btn btn-sm btn-primary" onclick="_stepEditor.recordInto(this,\'phone\')">● 手机上录</button></div>';
+        h+='<div class="form-group"><button class="btn btn-sm" onclick="_stepEditor.recordInto(this,\'web\')">● 网页上录</button></div>';
+      }
+      h+='<div class="form-group"><label>速度</label><input type="number" class="form-control" data-key="speed" value="'+(p.speed!=null?p.speed:1.0)+'" step="0.1" min="0.1" max="5"></div>';
+      h+='<div class="form-group"><button class="btn btn-sm btn-danger" onclick="_stepEditor.clearGesture(this)">清空</button></div></div>';
+      h+='<div class="help">这是<b>纯录制回放</b>：路径与时长照录制原样重放，不做弧线/抖动/手速那套加工（和「滑动」步骤是两回事）。'
+        +'<b>手机上录</b>=用手指在真机上划（最真实）；<b>网页上录</b>=在弹窗画面里按住鼠标拖。'
+        +'轨迹按屏幕绝对像素存，换分辨率不同的设备可能偏，同型号/同分辨率最稳</div>';
     }else if(step.type==='wait'){
       h+='<div class="form-row"><div class="form-group"><label>最短(秒)</label><input type="number" class="form-control" data-key="min" value="'+(p.min||1.0)+'" step="0.5" min="0.1"></div>';
       h+='<div class="form-group"><label>最长(秒)</label><input type="number" class="form-control" data-key="max" value="'+(p.max||3.0)+'" step="0.5" min="0.1"></div></div>';
+      h+='<div class="form-group form-check"><input type="checkbox" data-key="vary_pace" '+(p.vary_pace?'checked':'')+'><label>按设备节奏微调（0.8~1.35 倍）</label></div>';
+      h+='<div class="help">勾上后每台设备按自己的节奏缩放这个等待：批量跑时设备之间会逐渐错开，不再整齐划一。代价是实际时长不再严格等于上面填的值</div>';
     }else if(step.type==='clipboard'){
       h+='<div class="form-group"><label>注入内容</label><textarea class="form-control" data-key="text" rows="3" style="font-family:monospace;min-height:70px">'+esc(p.text||'')+'</textarea></div>';
       h+='<div class="form-group form-check"><input type="checkbox" data-key="paste" '+(p.paste!==false?'checked':'')+'><label>注入后立即粘贴（需输入框已聚焦）</label></div>';
@@ -353,12 +423,17 @@ var _stepEditor={
       h+='<div class="help">动作组：按顺序执行下方子步骤一次。把多个步骤打包成一个可复用的整体。</div>';
       h+='<div class="form-group"><button class="btn btn-xs btn-primary" onclick="_stepEditor.saveAsCustomAction(\''+esc(step.id||'')+'\')">存为自定义动作</button> <span class="help" style="display:inline">把本组步骤保存到左侧自定义动作库，方便复用</span></div>';
     }else if(step.type==='if_el'){
+      // 屏幕状态 / 前台App 是"直接读设备当前状态"，没有等待超时、也没有选择器可抓
+      var dyn=(p.selector_type==='screen'||p.selector_type==='foreground');
       h+=_selRowHtml(p,
-        '<div class="form-group"><label>查找超时(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||3)+'" min="0.5" max="30" step="0.5"></div>'+
+        (dyn?'':'<div class="form-group"><label>查找超时(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||3)+'" min="0.5" max="30" step="0.5"></div>'+
         '<div class="form-group form-check" data-ocr-field style="display:'+(p.selector_type==='ocr'?'block':'none')+'">'+
-        '<input type="checkbox" data-key="ocr_click" '+(p.ocr_click?'checked':'')+'><label>OCR 命中后自动点击该文字</label></div>'+
+        '<input type="checkbox" data-key="ocr_click" '+(p.ocr_click?'checked':'')+'><label>OCR 命中后自动点击该文字</label></div>')+
-        '<div class="help">超时内找到元素 → 执行下方"✅ 找到时"分支；未找到 → 执行"❌ 未找到时"分支。两分支可放任意步骤，也可再嵌套条件判断/循环；'+
+        '<div class="help">'+(dyn
-        '<b>OCR识别</b>可匹配图片/画布里的文字（截屏识别，跨平台）</div>', true);
+          ? '命中 → 执行下方"✅ 找到时"分支；未命中 → 执行"❌ 未找到时"分支。<b>屏幕状态</b>读系统 mWakefulness（亮/熄），'
+            +'<b>前台App是</b>判断当前前台是不是某个包名——都只看当前状态，不等待。'
+          : '超时内找到元素 → 执行下方"✅ 找到时"分支；未找到 → 执行"❌ 未找到时"分支。两分支可放任意步骤，也可再嵌套条件判断/循环；'
+            +'<b>OCR识别</b>可匹配图片/画布里的文字（截屏识别，跨平台）')+'</div>', true);
     }
     // 共享：触发概率（所有步骤通用，0~100）
     h+='<div class="form-row" style="margin-top:8px"><div class="form-group"><label>触发概率(%)</label><input type="number" class="form-control" data-key="probability" value="'+(p.probability!=null?p.probability:100)+'" min="0" max="100"><div class="help">0~100，&lt;100 表示按概率执行（如 30=隔几次才触发一次，适合"偶尔点赞"）</div></div></div>';
@@ -453,7 +528,44 @@ var _stepEditor={
     }
   },
   _makeStep:function(lib){
-    return {id:_newStepId(),type:lib.type,label:lib.label,params:JSON.parse(JSON.stringify(lib.params))};
+    // 参数 = STEP_LIB 出厂值 ← 用户在「动作配置」里配的默认值（有才覆盖）
+    var params=JSON.parse(JSON.stringify(lib.params));
+    var d=_stepDefaults&&_stepDefaults[lib.type];
+    if(d)Object.keys(d).forEach(function(k){ if(d[k]!==undefined)params[k]=d[k]; });
+    return {id:_newStepId(),type:lib.type,label:lib.label,params:params};
+  },
+  // 递归找步骤对象（按 id）——写入录音必须改 _steps，不能只改 DOM
+  _findStep:function(id,arr){
+    var self=this, found=null;
+    (arr||this._steps).forEach(function(st){
+      if(found)return;
+      if(st.id===id){found=st;return;}
+      _childArrs(st).forEach(function(a){ if(!found)found=self._findStep(id,a); });
+    });
+    return found;
+  },
+  // 给某个「录制手势」步骤录制轨迹（src: 'phone' 手机上录 / 'web' 网页上录）
+  recordInto:function(btn,src){
+    var card=btn.closest('.step-card');
+    var step=card?this._findStep(card.dataset.stepId):null;
+    if(!step){showToast('找不到这个步骤','error');return;}
+    if(typeof openRecorder!=='function'){showToast('录制器未加载','error');return;}
+    var self=this;
+    openRecorder({mode:'gesture', autoStartPhone: src==='phone', onDone:function(p,from){
+      step.params={points:p.points,speed:p.speed||1.0};
+      var dur=p.points.length?p.points[p.points.length-1][2]:0;
+      step.label='录制手势 '+(from==='phone'?'手机':'网页')+' '+p.points.length+'点';
+      self._renderCanvas();
+      showToast('已录到 '+(p.points.length)+' 个点 / '+(dur/1000).toFixed(2)+' 秒','success');
+    }});
+  },
+  clearGesture:function(btn){
+    var card=btn.closest('.step-card');
+    var step=card?this._findStep(card.dataset.stepId):null;
+    if(!step){return;}
+    step.params={points:[],speed:1.0};
+    this._renderCanvas();
+    showToast('已清空录制的轨迹','success');
   },
   // 测试此步骤：在选中设备上试执行当前步骤，验证选择器
   _testStep:function(btn){
@@ -626,10 +738,12 @@ var _stepEditor={
     });
   },
   // 条件判断：选择器类型切到 OCR 时显示"命中后点击"开关
-  _toggleOcrMode:function(sel){
+  _condTypeChanged:function(sel){
-    var card=sel.closest('.step-card');
+    // 条件类型一变，"值"控件也要跟着换（元素值输入框 / 屏幕亮熄下拉 / 包名输入），
-    var f=card&&card.querySelector('[data-ocr-field]');
+    // 整卡重渲染最省心。先把 DOM 的值同步回 _steps，否则重渲染会丢掉刚改的东西。
-    if(f)f.style.display=sel.value==='ocr'?'block':'none';
+    this._syncFromDom();
+    var self=this;
+    setTimeout(function(){self._renderCanvas();},0);
   },
   // 给数组分配唯一 id，用于 move/duplicate/remove/拖拽定位到正确的父数组
   _arrId:function(arr){
@@ -725,6 +839,10 @@ var _stepEditor={
           if(!s.params.text){
             warnings.push(name+' "'+label+'": 注入内容为空，步骤会跳过。');
           }
+        }else if(s.type==='gesture'){
+          if(!(s.params.points||[]).length){
+            warnings.push(name+' "'+label+'": 录制手势还没有轨迹，执行时会被跳过。');
+          }
         }else if(s.type==='if_el'){
           if(!s.params.selector_value){
             warnings.push(name+' "'+label+'": 条件判断的选择器为空，会直接走"未找到"分支。');
@@ -831,7 +949,7 @@ var _stepEditor={
       '<div class="el-picker-main">'+
         '<div class="el-shot-wrap">'+
           '<div class="el-shot-toolbar">'+
-            '<button class="btn" onclick="_stepEditor._refreshShot()" title="重新拉取截图和元素树（界面变化后刷新用）">刷新截图+元素</button>'+
+            '<button class="btn" onclick="_stepEditor._refreshShot()" title="重新抓取截图与元素树（一次取齐）">重新抓取</button>'+
             '<span class="el-shot-info" id="el-shot-info">加载中...</span>'+
           '</div>'+
           '<div class="el-shot-container" id="el-shot-container">'+
@@ -839,8 +957,20 @@ var _stepEditor={
           '</div>'+
         '</div>'+
         '<div class="el-list-wrap">'+
-          '<input type="text" class="el-picker-search" id="el-search" placeholder="搜索 resource-id/text/description..." oninput="_stepEditor._filterEl(this.value)">'+
+          '<div class="el-tabs">'+
-          '<div class="el-picker-list" id="el-list"><div class="se-empty">加载元素树...</div></div>'+
+            '<button class="el-tab active" data-pane="tree" onclick="_stepEditor._tab(this)">层级</button>'+
+            '<button class="el-tab" data-pane="attr" onclick="_stepEditor._tab(this)">属性</button>'+
+            '<button class="el-tab" data-pane="color" onclick="_stepEditor._tab(this)">颜色</button>'+
+          '</div>'+
+          '<div class="el-pane active" id="el-pane-tree">'+
+            '<input type="text" class="el-picker-search" id="el-search" placeholder="搜索 resource-id/text/description..." oninput="_stepEditor._filterEl(this.value)">'+
+            '<div class="el-picker-list" id="el-list" style="max-height:calc(100% - 42px)"><div class="se-empty">加载元素树...</div></div>'+
+          '</div>'+
+          '<div class="el-pane" id="el-pane-attr"><div class="se-empty">点左侧图上的元素，或点「层级」里的条目看属性</div></div>'+
+          '<div class="el-pane" id="el-pane-color">'+
+            '<div style="padding:8px 12px;font-size:11.5px;color:var(--text-light)">把鼠标移到左侧图上取色；点元素可看该元素的主色</div>'+
+            '<div id="el-color-list"></div>'+
+          '</div>'+
         '</div>'+
       '</div>';
     document.getElementById('el-picker-footer').innerHTML=
@@ -849,65 +979,138 @@ var _stepEditor={
       '<span class="text-muted" style="margin-left:10px;font-size:11.5px">'
       +'提示：先「▶ 点一下」在设备上验证位置，再点元素回填选择器；'
       +'「✓ 测选择器」会用将填入的选择器真跑一次点击</span>';
-    // 加载截图和元素树（_refreshShot 内部同时刷新两者）
+    // 一次取齐截图 + 元素树（见 _loadSnapshot 的说明）
-    self._refreshShot();
+    self._loadSnapshot();
   },
-  // 拉取元素树（进入页面和刷新时共用；带时间戳防缓存）
+  // 右侧页签切换
-  _loadElData:function(){
+  _tab:function(btn){
-    var serial=this._elSerial;
+    var pane=btn.dataset.pane;
-    if(!serial)return;
+    document.querySelectorAll('#el-picker-body .el-tab').forEach(function(b){
-    var listEl=document.getElementById('el-list');
+      b.classList.toggle('active', b===btn);
-    if(listEl)listEl.innerHTML='<div class="se-empty">加载元素树...</div>';
+    });
-    var self=this;
+    ['tree','attr','color'].forEach(function(p){
-    fetch('/api/uiauto/elements?serial='+encodeURIComponent(serial)+'&_='+Date.now())
+      var el=document.getElementById('el-pane-'+p);
-      .then(function(r){return r.json();})
+      if(el)el.classList.toggle('active', p===pane);
-      .then(function(data){
+    });
-        var le=document.getElementById('el-list');
-        if(!le)return;
-        if(!data.ok){
-          le.innerHTML='<div class="se-empty">'+esc(data.error||'抓取失败')+'</div>';
-          return;
-        }
-        self._elData=data.elements||[];
-        self._renderEl(self._elData);
-        // 刷新后保持搜索过滤状态
-        var search=document.getElementById('el-search');
-        if(search&&search.value)self._filterEl(search.value);
-        self._renderOverlays();
-      })
-      .catch(function(e){
-        var le=document.getElementById('el-list');
-        if(le)le.innerHTML='<div class="se-empty">请求失败: '+esc(e)+'</div>';
-      });
   },
-  // 刷新截图
+  // 属性页：选中元素的全部属性
-  _refreshShot:function(){
+  _renderAttrs:function(i){
+    var el=(this._elData||[])[i];
+    var box=document.getElementById('el-pane-attr');
+    if(!box)return;
+    if(!el){box.innerHTML='<div class="se-empty">点左侧图上的元素，或点「层级」里的条目看属性</div>';return;}
+    var sg=el.suggested||{};
+    // 稳定性说明：把"这个选择器靠什么定位"写清楚，用户才知道它会不会因为界面变化而失效
+    var stab=sg.semantic?'✓ 语义型 —— 靠 @'+(sg.via||'')+' 限定，不依赖同类元素个数，换设备/换版本仍命中'
+            :sg.indexed?'⚠ 序号型 —— 依赖「同类元素共 '+sg.total+' 个、取第 '+sg.occ+' 个」，界面一变就失配'
+            :sg.broad?'⚠ 宽泛 —— 无唯一属性，可能误匹配其他元素'
+            :(sg.value?'✓ 唯一属性，直接定位':'—');
+    var rows=[['建议选择器', sg.value||'(无可靠选择器)'],['选择器稳定性', stab],
+              ['class', el.class||''], ['resource-id', el.resource_id||''],
+              ['text', el.text||''], ['content-desc', el.description||''],
+              ['package', el.package||''], ['clickable', el.clickable||''],
+              ['bounds', el.bounds||''], ['层级深度', String(el.depth||0)]];
+    box.innerHTML=rows.map(function(r){
+      return '<div class="el-attr"><b>'+esc(r[0])+'</b><span>'+esc(r[1]||'-')+'</span></div>';
+    }).join('');
+  },
+  // 颜色页：鼠标位置的像素色 + 选中元素的主色
+  _pixelAt:function(x,y){
+    try{
+      var c=this._colorCanvas, img=document.getElementById('el-shot-container').querySelector('img');
+      if(!c||!img)return null;
+      if(c.width!==img.naturalWidth){c.width=img.naturalWidth;c.height=img.naturalHeight;}
+      var ctx=c.getContext('2d');
+      ctx.drawImage(img,0,0);
+      var d=ctx.getImageData(Math.max(0,Math.min(c.width-1,x)),Math.max(0,Math.min(c.height-1,y)),1,1).data;
+      return '#'+[d[0],d[1],d[2]].map(function(v){return ('0'+v.toString(16)).slice(-2);}).join('');
+    }catch(e){return null;}
+  },
+  _updatePixel:function(x,y){
+    var box=document.getElementById('el-color-list');
+    if(!box)return;
+    var col=this._pixelAt(Math.round(x),Math.round(y));
+    if(!col)return;
+    box.innerHTML='<div class="el-color-row"><span class="el-swatch" style="background:'+col+'"></span>'+
+      '<span>光标处 '+esc(col)+'</span></div>'+
+      (box.dataset.dom||'');
+  },
+  _renderColors:function(i){
+    var box=document.getElementById('el-color-list');
+    if(!box)return;
+    var el=(this._elData||[])[i];
+    var dom='';
+    if(el&&el.bounds){
+      var m=el.bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+      if(m){
+        var x=Math.round((+m[1]+ +m[3])/2), y=Math.round((+m[2]+ +m[4])/2);
+        var c=this._pixelAt(x,y);
+        if(c) dom='<div class="el-color-row"><span class="el-swatch" style="background:'+c+'"></span>'+
+          '<span>选中元素中心 '+esc(c)+'</span></div>';
+      }
+    }
+    box.dataset.dom=dom;
+    box.innerHTML=dom||'<div class="se-empty" style="padding:12px">把鼠标移到左侧图上取色</div>';
+  },
+  // 一次取齐：截图 + 元素树（后端用原生 u2 背靠背取）
+  // 为什么不再分两个接口：截图与元素树分两次拿，中间隔着 dump 本身的 1.3~1.8 秒，
+  // 界面只要在动（信息流/视频/加载），框就会落在旧位置上（"抓取错位"）。
+  _loadSnapshot:function(){
     var serial=this._elSerial;
     if(!serial)return;
     var container=document.getElementById('el-shot-container');
-    if(!container)return;
-    container.innerHTML='<div class="el-shot-loading">正在获取截图...</div>';
     var info=document.getElementById('el-shot-info');
-    if(info)info.textContent='加载中...';
+    var old=document.querySelector('.el-shot-warn');
+    if(old)old.remove();
+    if(container)container.innerHTML='<div class="el-shot-loading">正在抓取（截图 + 元素树一次取齐）…</div>';
+    if(info)info.textContent='抓取中…';
     var self=this;
-    var img=new Image();
+    fetch('/api/uiauto/snapshot?serial='+encodeURIComponent(serial)+'&_='+Date.now())
-    img.onload=function(){
+      .then(function(r){return r.json();})
-      container.innerHTML='';
+      .then(function(d){
-      container.appendChild(img);
+        if(!d.ok){
-      var infoEl=document.getElementById('el-shot-info');
+          if(container)container.innerHTML='<div class="el-shot-loading">'+esc(d.error||'抓取失败')+'</div>';
-      if(infoEl)infoEl.textContent=img.naturalWidth+'x'+img.naturalHeight;
+          if(info)info.textContent='失败';
-      // 截图加载完后重新渲染元素边界框
+          return;
-      self._renderOverlays();
+        }
-    };
+        self._elData=d.elements||[];
-    img.onerror=function(){
+        if(d.unstable){
-      container.innerHTML='<div class="el-shot-loading">截图加载失败</div>';
+          var w=document.createElement('div');
-      var infoEl=document.getElementById('el-shot-info');
+          w.className='el-shot-warn';
-      if(infoEl)infoEl.textContent='失败';
+          w.innerHTML='⚠ 抓取期间界面有变化，框可能对不上 —— 建议把设备停在<b>静止界面</b>后点「重新抓取」';
-    };
+          container.parentNode.insertBefore(w, container);
-    img.src='/api/uiauto/screenshot?serial='+encodeURIComponent(serial)+'&_='+Date.now();
+        }
-    // 同时重新拉取元素树——只刷截图会导致"截图是新的、元素框是旧的"错位
+        var img=new Image();
-    this._loadElData();
+        img.onload=function(){
+          container.innerHTML='';
+          container.appendChild(img);
+          if(info){
+            info.textContent=d.width+'x'+d.height+' · '+self._elData.length+' 个元素 · '
+              +(d.cost_ms||0)+'ms'+(d.unstable?' · ⚠ 界面在变化':'');
+          }
+          // 图片显示尺寸一变（窗口缩放、面板宽度变化、滚动条出现…）就重算所有框 ——
+          // 这是"完全不错位"的保证：框永远跟着图片走，不留旧坐标
+          if(window.ResizeObserver){
+            if(self._ro)self._ro.disconnect();
+            self._ro=new ResizeObserver(function(){ self._renderOverlays(); });
+            self._ro.observe(img);
+          }
+          self._colorCanvas=document.createElement('canvas');
+          self._renderOverlays();
+          self._renderAttrs(null);
+          self._renderColors(null);
+        };
+        img.src=d.image;
+        self._renderEl(self._elData);
+        var search=document.getElementById('el-search');
+        if(search&&search.value)self._filterEl(search.value);
+      })
+      .catch(function(e){
+        if(container)container.innerHTML='<div class="el-shot-loading">请求失败: '+esc(e)+'</div>';
+      });
   },
+  // 兼容旧调用名（工具栏「重新抓取」按钮）
+  _refreshShot:function(){ this._loadSnapshot(); },
   // 在截图上渲染元素边界框（可点击）
   _renderOverlays:function(){
     var container=document.getElementById('el-shot-container');
@@ -947,6 +1150,32 @@ var _stepEditor={
       });
       // 点击截图：按 bounds 命中测试，选中最小的（最深的）元素，
       // 而不是被 DOM 层叠中的大容器/大兄弟挡住
+      container.onmousemove=function(e){
+        var im=container.querySelector('img');
+        if(!im||!self._elData)return;
+        var r=im.getBoundingClientRect();
+        var px=(e.clientX-r.left)/scaleX, py=(e.clientY-r.top)/scaleY;
+        var best=-1,bestArea=Infinity;
+        self._elData.forEach(function(el,i){
+          var mb=el.bounds&&el.bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+          if(!mb)return;
+          var a=+mb[1],b=+mb[2],c=+mb[3],dd=+mb[4];
+          if(px>=a&&px<=c&&py>=b&&py<=dd){var ar=(c-a)*(dd-b); if(ar<bestArea){bestArea=ar;best=i;}}
+        });
+        self._updatePixel(px, py);
+        var hov=container.querySelector('.el-shot-hover');
+        if(best<0){ if(hov)hov.remove(); return; }
+        var b2=self._elData[best].bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+        if(!hov){hov=document.createElement('div');hov.className='el-shot-hover';container.appendChild(hov);}
+        hov.style.left=(imgOffsetX+(+b2[1])*scaleX)+'px';
+        hov.style.top=(imgOffsetY+(+b2[2])*scaleY)+'px';
+        hov.style.width=((+b2[3])-(+b2[1]))*scaleX+'px';
+        hov.style.height=((+b2[4])-(+b2[2]))*scaleY+'px';
+      };
+      container.onmouseleave=function(){
+        var hov=container.querySelector('.el-shot-hover');
+        if(hov)hov.remove();
+      };
       container.onclick=function(e){
         var im=container.querySelector('img');
         if(!im)return;
@@ -971,6 +1200,8 @@ var _stepEditor={
   },
   // 高亮元素（截图框 + 列表项联动）
   _highlightEl:function(i){
+    this._renderAttrs(i);
+    this._renderColors(i);
     // 清除旧高亮（只在 el-picker-overlay 范围内查找）
     var picker=document.getElementById('el-picker-overlay');
     picker.querySelectorAll('.el-shot-overlay.active').forEach(function(o){o.classList.remove('active');});
@@ -995,10 +1226,12 @@ var _stepEditor={
     var self=this;
     var html=list.map(function(el){
       var idx=self._elData.indexOf(el);
+      // 属性顺序有讲究：**文字/描述排最前并加粗**——它们是最稳的定位依据，
+      // 也是"一眼认出这是哪个元素"的凭据（id 只是补充）。见 doc/TASK_DEV.md §5.4。
       var attrs=[];
-      if(el.resource_id)attrs.push('<span>id:'+esc(el.resource_id)+'</span>');
+      if(el.text)attrs.push('<span class="ep-text">text:<b>'+esc(el.text)+'</b></span>');
-      if(el.text)attrs.push('<span>text:'+esc(el.text)+'</span>');
+      if(el.description)attrs.push('<span class="ep-desc">desc:<b>'+esc(el.description)+'</b></span>');
-      if(el.description)attrs.push('<span>desc:'+esc(el.description)+'</span>');
+      if(el.resource_id)attrs.push('<span class="ep-id">id:'+esc(el.resource_id)+'</span>');
       var indent='  '.repeat(Math.min(el.depth||0,6));
       var sg=el.suggested||{};
       if(sg.invalid)attrs.push('<span style="color:#dc2626">⚠ '+esc(sg.reason||'无可用属性')+'</span>');
@@ -1009,13 +1242,16 @@ var _stepEditor={
           ? '<button class="btn btn-xs" title="用将填入的选择器在设备上真跑一次 click，验证是否命中" '
             +'onclick="event.stopPropagation();_stepEditor._testSelector('+idx+')">✓ 测选择器</button>'
           : '')
+        +'<button class="btn btn-xs" title="把这条的选择器填入步骤" '
+        +'onclick="event.stopPropagation();_stepEditor._fillEl('+idx+')">✓ 填入</button>'
         +'</div>';
-      return '<div class="el-picker-item" data-idx="'+idx+'" title="点击填入: '+esc(sg.value||'')+'" onclick="_stepEditor._pickEl('+idx+')">'+
+      return '<div class="el-picker-item" data-idx="'+idx+'" title="'+esc(sg.value||'')+'" onclick="_stepEditor._pickEl('+idx+')">'+
         '<span class="ep-depth">'+(el.depth||0)+'</span>'+
         '<div class="ep-info"><div class="ep-name">'+indent+esc(el.name||el.class||'')+'</div>'+
         '<div class="ep-attrs">'+attrs.join('')+'</div></div>'+
         '<span class="ep-sel">'+esc(sg.type)+'</span>'+
-        (sg.indexed?' <span class="label label-info" title="界面中同属性元素共 '+sg.total+' 个，按从上到下这是第 '+sg.occ+' 个，选择器已带序号精确定位">#'+sg.occ+'/'+sg.total+'</span>':'')+
+        (sg.semantic?' <span class="label label-success" title="语义选择器：用 '+esc(sg.via||'')+' 限定，只认「这个元素长什么样」，不认「同类元素有几个」—— 换设备、换版本、界面增减元素都照样命中">✓ 语义</span>':'')+
+        (sg.indexed?' <span class="label label-warning" title="⚠ 序号型：依赖「同属性元素共 '+sg.total+' 个、这是第 '+sg.occ+' 个」。界面上多/少一个同类元素（如抖音灰度版少一个 tab）就会指到别的元素上 —— 建议改选带 text 或 content-desc 的元素，拿到语义选择器">⚠ 序号 '+sg.occ+'/'+sg.total+'</span>':'')+
         (sg.broad?' <span class="label label-warning" title="无唯一属性，选择器可能误匹配其他元素，建议选带文字/id 的元素">⚠宽泛</span>':'')+
         acts+
       '</div>';
@@ -1062,7 +1298,12 @@ var _stepEditor={
     });
     this._renderEl(f);
   },
+  // 点层级条目 = **选中**（看属性/颜色/高亮），不关窗不回填
   _pickEl:function(i){
+    this._highlightEl(i);
+  },
+  // 「✓ 填入」才回填选择器并关窗
+  _fillEl:function(i){
     var el=this._elData[i];
     if(!el||!this._elTargetInput)return;
     if(el.suggested&&el.suggested.invalid){
@@ -1097,6 +1338,11 @@ async function saveTask(jobId){
     }
     const mdEl=document.getElementById('f-max_duration');
     params={max_duration:mdEl?parseInt(mdEl.value)||0:0,steps:steps};
+    // 公共巡检（任务级，独立于步骤画布；实现在 tasks.js + core/patrol.py）
+    if(typeof patrolCollect==='function'){
+      const ws=patrolCollect();
+      if(ws.length)params.watchers=ws;
+    }
   }else{
     try{params=JSON.parse(document.getElementById('f-params').value||'{}');}
     catch(e){showToast('参数 JSON 格式错误','error');return;}

static/admin/monitor.js

@@ -70,27 +70,28 @@ async function stopSelectedDevices(){
   setTimeout(loadMonitor,500);
 }
 
-// 定位设备：点亮屏幕 + 打开大字定位页（显示设备 IP），便于在机架上找到目标
+// 打开设备端 Agent：让设备上的 Agent 弹出「身份大字页」（名称/IP/平台地址），
-// 注意：打开定位页会切换设备前台，任务运行中慎用
+// 人站在机架前一眼看出这台是平台上的哪一台。
-async function locateDevice(serial){
+// 替代原来的"推 HTML 让设备浏览器打开定位页"——那条路要设备装浏览器、页面还依赖
-  if(!confirm('点亮 '+serial+' 屏幕并打开大字定位页？\n\n（会切换设备前台显示，任务运行中慎用）'))return;
+// 设备能访问平台，且在 MIUI 上本来就不稳。
-  const r=await apiPost('/api/device/locate',{serial:serial,show:true});
+async function showAgentInfo(serial){
+  const r=await apiPost('/api/agent/show-info',{serial:serial});
   if(!r)return;
   if(r.ok){
     _locatingSerials.add(serial);
-    showToast(r.msg||'已定位','success');
+    showToast(r.msg||'已让设备显示身份信息','success');
     renderDevices();
-  }else showToast(r.error||'定位失败','error');
+  }else showToast(r.error||'打开失败','error');
 }
 
-// 结束定位：关闭设备上的定位页（浏览器），按钮恢复为"定位"
+// 关闭设备端 Agent 的身份页
-async function stopLocate(serial){
+async function hideAgentInfo(serial){
-  const r=await apiPost('/api/device/locate/stop',{serial:serial});
+  const r=await apiPost('/api/agent/show-info',{serial:serial,close:true});
   if(!r)return;
   _locatingSerials.delete(serial);
   renderDevices();
-  if(r.ok)showToast(r.msg||'已结束定位','success');
+  if(r.ok)showToast(r.msg||'已关闭','success');
-  else showToast(r.error||'结束定位失败','error');
+  else showToast(r.error||'关闭失败','error');
 }
 
 // 批量亮屏/息屏所有在线设备（息屏会中断运行中任务，前端已确认）
@@ -344,13 +345,13 @@ function renderDeviceRow(dev){
   // 设备操作按钮需要"设备控制"权限（无权限只保留截图查看）
   const canDev=_can('devices');
   const stopBtn=canDev&&(dev.worker_status==='running'||dev.worker_status==='connecting')?'<button class="btn btn-danger btn-xs" onclick="apiAction(\'/api/stop_device\',{serial:\''+esc(dev.serial)+'\'})">停止</button>':'';
-  // 截图按钮（任何状态都可看，离线时会报错）
+  // 看屏按钮（任何状态都可看，离线时会报错）
-  const shotBtn='<button class="btn btn-xs" onclick="openScreenshot(\''+esc(dev.serial)+'\')" title="查看设备画面（不影响任务）">截图</button>';
+  const shotBtn='<button class="btn btn-xs" onclick="openScreenshot(\''+esc(dev.serial)+'\')" title="查看设备实时画面（不影响任务）">看屏</button>';
-  // 定位按钮：定位中显示"结束定位"（关闭定位页），否则显示"定位"（点亮+大字页）
+  // 设备端 Agent：开着身份页时显示"关闭"，否则"打开设备端 Agent"
   const locating=_locatingSerials.has(dev.serial);
   const locateBtn=canDev?(locating
-    ?'<button class="btn btn-xs btn-danger" onclick="stopLocate(\''+esc(dev.serial)+'\')" title="关闭定位页（退出浏览器）">结束定位</button>'
+    ?'<button class="btn btn-xs btn-danger" onclick="hideAgentInfo(\''+esc(dev.serial)+'\')" title="让设备上的 Agent 关掉身份大字页">关闭 Agent</button>'
-    :'<button class="btn btn-xs" onclick="locateDevice(\''+esc(dev.serial)+'\')" title="点亮屏幕并显示设备IP大字页（会切换前台，任务运行中慎用）">定位</button>'):'';
+    :'<button class="btn btn-xs" onclick="showAgentInfo(\''+esc(dev.serial)+'\')" title="让设备上的 Agent 显示身份大字页（名称/IP/平台地址）——人在机架前对号用（会切换设备前台）">打开设备端 Agent</button>'):'';
   // 异常/失败设备提供"清除异常"（把状态恢复为未启动）
   const clearBtn=canDev&&(dev.worker_status==='error'||dev.worker_status==='failed')
     ?'<button class="btn btn-xs" onclick="clearDeviceError(\''+esc(dev.serial)+'\')" title="清除该设备的异常状态，恢复为未启动">清除异常</button>':'';

static/admin/notify.js

@@ -0,0 +1,384 @@
+// 系统 → 通知：多 webhook 配置（每条自己订阅事件）+ 测试发送 + 发送记录
+// 后端：web/notify_api.py（全部 admin_required）；配置落 app_meta.notify_webhooks 单键。
+// 安全口径：URL 里有凭据（企微 ?key=）→ 列表/记录里一律打码；编辑时**留空即不修改**。
+let _notifyHooks = [];
+let _notifyEvents = [];
+let _notifyFormats = [];
+let _notifySettings = {};
+let _notifyEditingId = null;     // null=新建
+let _notifyPatterns = [];        // 编辑中的通配订阅（如 task.*）
+let _notifyPrevFormat = '';      // 上一个选中格式（切换时判断限流值要不要跟着走）
+let _notifyRateTouched = false;  // 用户是否手动改过限流值（没改过就跟随格式的推荐值）
+
+// ================== 加载与渲染 ==================
+function loadNotifyPanel(){
+  Promise.all([apiGet('/api/notify/webhooks'),
+               apiGet('/api/notify/events'),
+               apiGet('/api/notify/logs?limit=50')]).then(function(res){
+    const [hooks, events, logs] = res;
+    if(hooks && hooks.ok){
+      _notifyHooks = hooks.webhooks || [];
+      _notifyFormats = hooks.formats || [];
+      _notifySettings = hooks.settings || {};
+    }
+    if(events && events.ok) _notifyEvents = events.events || [];
+    renderNotifySettings();
+    renderNotifyHooks();
+    renderNotifyLogs(logs && logs.ok ? (logs.logs || []) : []);
+  });
+}
+
+function renderNotifySettings(){
+  const on = document.getElementById('notify-global');
+  if(on) on.checked = _notifySettings.global_enabled !== false;
+  const agg = document.getElementById('notify-agg');
+  if(agg) agg.value = _notifySettings.default_agg_window != null ? _notifySettings.default_agg_window : 30;
+  const rate = document.getElementById('notify-rate');
+  if(rate) rate.value = _notifySettings.default_rate_limit != null ? _notifySettings.default_rate_limit : 18;
+}
+
+function renderNotifyHooks(){
+  const tb = document.getElementById('tb-notify-hooks');
+  if(!tb) return;
+  if(!_notifyHooks.length){
+    tb.innerHTML = '<tr><td colspan="6" class="empty">还没有配置 webhook。点「＋ 新建 Webhook」加一条——'
+      + '比如把「任务失败」推到企业微信群。</td></tr>';
+    return;
+  }
+  tb.innerHTML = _notifyHooks.map(function(h){
+    const fmt = (_notifyFormats.find(f => f.name === h.format) || {}).label || h.format;
+    const evs = (h.events || []).length;
+    return '<tr>'
+      + '<td>' + esc(h.name) + (h.secret_set ? ' <span class="label label-info" title="已配置密钥">🔑</span>' : '') + '</td>'
+      + '<td>' + esc(fmt) + '</td>'
+      + '<td style="max-width:280px;word-break:break-all;font-family:var(--mono);font-size:11px">'
+        + esc(h.url || '') + '</td>'
+      + '<td>' + evs + ' 个事件</td>'
+      + '<td>' + (h.enabled ? '<span class="label label-success">启用</span>'
+                            : '<span class="label">停用</span>') + '</td>'
+      + '<td style="white-space:nowrap">'
+        + '<button class="btn btn-xs" onclick="testNotifyHook(\'' + h.id + '\')" title="立刻发一条测试消息，看群里收不收得到">发送测试</button> '
+        + '<button class="btn btn-xs" onclick="toggleNotifyHook(\'' + h.id + '\',' + (h.enabled ? 'false' : 'true') + ')">'
+          + (h.enabled ? '停用' : '启用') + '</button> '
+        + '<button class="btn btn-xs" onclick="openNotifyModal(\'' + h.id + '\')">编辑</button> '
+        + '<button class="btn btn-xs btn-danger" onclick="deleteNotifyHook(\'' + h.id + '\')">删除</button>'
+      + '</td></tr>';
+  }).join('');
+}
+
+function renderNotifyLogs(logs){
+  const tb = document.getElementById('tb-notify-logs');
+  if(!tb) return;
+  if(!logs.length){
+    tb.innerHTML = '<tr><td colspan="5" class="empty">本次运行还没有发送记录（重启后清空，历史见 logs/notify.log）</td></tr>';
+    return;
+  }
+  tb.innerHTML = logs.map(function(r){
+    const t = r.ts ? new Date(r.ts * 1000).toLocaleString('zh-CN', {hour12:false}) : '';
+    const st = r.ok ? '<span class="label label-success">成功</span>'
+                    : '<span class="label label-warning">失败</span>';
+    const detail = r.ok ? ('HTTP ' + (r.http_status == null ? '' : r.http_status)
+                           + (r.errcode ? ' errcode ' + r.errcode : ''))
+                        : esc(r.error || '');
+    return '<tr><td style="white-space:nowrap">' + esc(t) + '</td>'
+      + '<td>' + esc(r.hook_name || '') + '</td>'
+      + '<td style="font-family:var(--mono);font-size:11px">' + esc(r.event || '') + '</td>'
+      + '<td>' + st + '</td>'
+      + '<td style="font-size:11px">' + detail + (r.elapsed_ms != null ? ' · ' + r.elapsed_ms + 'ms' : '') + '</td></tr>';
+  }).join('');
+}
+
+// ================== 编辑弹窗 ==================
+function notifyEventMatches(pattern, key){
+  if(!pattern) return false;
+  if(pattern === '*' || pattern === key) return true;
+  if(pattern.slice(-2) === '.*') return key.indexOf(pattern.slice(0, -1)) === 0;
+  return false;
+}
+
+function openNotifyModal(id){
+  _notifyEditingId = id || null;
+  const h = id ? (_notifyHooks.find(x => x.id === id) || {}) : {};
+  _notifyPatterns = (h.events || []).filter(p => p.indexOf('*') >= 0);
+  const checked = (h.events || []).filter(p => p.indexOf('*') < 0);
+  const fmtOpts = _notifyFormats.map(function(f){
+    const sel = (h.format || 'wecom') === f.name ? ' selected' : '';
+    return '<option value="' + f.name + '"' + sel + (f.implemented ? '' : ' disabled') + '>'
+      + esc(f.label) + '</option>';
+  }).join('');
+  const box = document.getElementById('notify-modal-box');
+  if(!box) return;
+  box.innerHTML =
+    '<div style="display:flex;align-items:center;margin-bottom:12px">'
+      + '<div style="font-size:15px;font-weight:700;flex:1">'
+        + (id ? '编辑 Webhook' : '新建 Webhook') + '</div>'
+      + '<button class="btn btn-xs" title="关闭（不保存）" onclick="closeNotifyModal()">✕ 关闭</button>'
+    + '</div>'
+    + '<div class="form-row">'
+      + '<div class="form-group"><label>名称</label>'
+        + '<input id="nf-name" class="form-control" value="' + esc(h.name || '') + '" placeholder="如：运维群"></div>'
+      + '<div class="form-group"><label>格式</label>'
+        + '<select id="nf-format" class="form-control" onchange="_notifyFormatChanged()">' + fmtOpts + '</select></div>'
+    + '</div>'
+    + '<div class="form-group"><label>Webhook URL</label>'
+      // 占位与说明都由**当前格式**决定（见 _notifyFormatChanged），切换格式会跟着变
+      + '<input id="nf-url" class="form-control" value="">'
+      + '<div class="help" id="nf-url-help"></div></div>'
+    + '<div class="form-row">'
+      + '<div class="form-group"><label id="nf-secret-label">签名密钥（可选）</label>'
+        + '<input id="nf-secret" type="password" class="form-control" placeholder="'
+        + (h.secret_set ? '已配置，留空不修改' : '留空即可') + '">'
+        + '<div class="help" id="nf-secret-help"></div></div>'
+      + '<div class="form-group" style="max-width:150px"><label>聚合窗口(秒)</label>'
+        + '<input id="nf-agg" type="number" class="form-control" min="0" max="600" value="'
+        + (h.agg_window != null ? h.agg_window : (_notifySettings.default_agg_window || 30)) + '">'
+        + '<div class="help">0=不聚合</div></div>'
+      + '<div class="form-group" style="max-width:150px"><label>限流(条/分)</label>'
+        + '<input id="nf-rate" type="number" class="form-control" min="0" max="60" '
+        + 'oninput="_notifyRateTouched=true" value="'
+        + (h.rate_limit_per_min != null ? h.rate_limit_per_min
+           : ((_notifyFormats.find(x => x.name === (h.format || 'wecom')) || {}).limit_default
+              || _notifySettings.default_rate_limit || 18)) + '">'
+        + '<div class="help" id="nf-limit-help"></div></div>'
+    + '</div>'
+    + '<div class="form-group"><label>订阅事件（不勾就不推）</label>'
+      + '<div class="help" style="margin-bottom:6px">按类别分的完整事件目录；'
+      + '带 <b>★</b> 的是建议开启的。也可以直接写通配（如 <code>task.*</code>）——在下面的芯片框里加。</div>'
+      + '<div id="nf-events" style="max-height:260px;overflow-y:auto;border:1px solid var(--border);border-radius:8px;padding:10px"></div>'
+    + '</div>'
+    + '<div class="form-group" id="nf-pattern-wrap"><label>通配订阅（可选，任何格式都适用）</label>'
+      + '<div id="nf-patterns" style="display:flex;gap:6px;flex-wrap:wrap;margin-bottom:6px"></div>'
+      + '<div style="display:flex;gap:6px"><input id="nf-pattern-input" class="form-control" placeholder="task.* 或 device.* 或 *">'
+      + '<button class="btn" onclick="addNotifyPattern()">添加</button></div></div>'
+    + '<div class="form-group" id="nf-body-wrap" style="display:none"><label>请求体模板（JSON）</label>'
+      + '<textarea id="nf-body" class="form-control" rows="5" placeholder=\'{"text":"{{title}}","desc":"{{summary}}"}\'></textarea>'
+      + '<div class="help">占位符：{{event}} {{title}} {{summary}} {{ts}} {{level}} {{markdown}} {{fields}} {{fields_json}} {{hook_name}} {{field.名称}}。'
+      + '保存前会做干跑校验（渲染后必须是合法 JSON）。Slack 可直接用：'
+      + '<code>{"text":"{{markdown}}"}</code></div></div>'
+    + '<div class="form-group">'
+      + '<label>预览</label><div id="nf-preview" class="help">点「预览请求体」看真实会发出去的内容与字节数。</div>'
+    + '</div>'
+    // 底部操作栏（缺了它就只能靠刷新页面逃出去）
+    + '<div style="display:flex;gap:8px;align-items:center;margin-top:16px;padding-top:12px;border-top:1px solid var(--border)">'
+      + '<button class="btn btn-primary" onclick="saveNotifyHook()">' + (id ? '保存' : '创建') + '</button>'
+      + '<button class="btn" onclick="previewNotifyHook()">预览请求体</button>'
+      + '<button class="btn" onclick="closeNotifyModal()">取消</button>'
+      + '<span class="help" style="margin-left:auto">Esc 或点空白处也能关</span>'
+    + '</div>';
+  box.querySelector('#nf-body').value = h.body_template || '';
+  renderEventTree(checked);
+  renderNotifyPatterns();
+  _notifyPrevFormat = (h.format || 'wecom');
+  _notifyRateTouched = (h.rate_limit_per_min != null);   // 编辑已有配置时视为"已定"
+  _notifyFormatChanged();
+  document.getElementById('notify-modal-overlay').style.display = 'flex';
+}
+
+function _notifyFormatChanged(){
+  const name = (document.getElementById('nf-format') || {}).value;
+  const meta = _notifyFormats.find(x => x.name === name) || {};
+  const h = _notifyEditingId
+    ? (_notifyHooks.find(x => x.id === _notifyEditingId) || {}) : {};
+
+  // URL：编辑时占位显示现有（打码）地址，新建时显示该格式的示例
+  const url = document.getElementById('nf-url');
+  if(url){
+    url.placeholder = (h.url && h.url !== undefined) ? h.url : (meta.url_hint || 'https://…');
+  }
+  const urlHelp = document.getElementById('nf-url-help');
+  if(urlHelp){
+    urlHelp.innerHTML = (h.url ? ('已配置：' + esc(h.url) + '（留空＝不修改）<br>') : '')
+      + esc(meta.url_help || '');
+  }
+
+  // 密钥：不同格式叫法/用途不同（企业微信不需要、Bark 是设备 Key、通用 JSON 是自定义头）
+  const sl = document.getElementById('nf-secret-label');
+  if(sl) sl.textContent = (h.secret_set ? '🔑 ' : '') + (meta.secret_label || '密钥（可选）');
+  const sh = document.getElementById('nf-secret-help');
+  if(sh) sh.innerHTML = esc(meta.secret_help || '')
+    + (h.secret_set ? '<br>已配置过：留空＝不修改，想清除请点上面的 🔑 后填写新值' : '');
+
+  // 限流：上限因格式而异（企微 20/分、Bark 无硬限）
+  const lh = document.getElementById('nf-limit-help');
+  if(lh) lh.textContent = meta.limit_help || '';
+  // 用户没手动改过限流值时，跟着格式的推荐值走（企微 20 / 通用 JSON 60 / Bark 60）
+  const rate = document.getElementById('nf-rate');
+  if(rate && !_notifyRateTouched && meta.limit_default){
+    rate.value = meta.limit_default;
+  }
+  // 请求体模板：只有需要模板的格式（通用 JSON）才显示
+  const bodyWrap = document.getElementById('nf-body-wrap');
+  if(bodyWrap) bodyWrap.style.display = meta.needs_template ? 'block' : 'none';
+
+  _notifyPrevFormat = name;
+}
+
+// Esc 关闭弹窗（点空白处关闭在 overlay 的 onclick 上）
+document.addEventListener('keydown', function(ev){
+  if(ev.key !== 'Escape') return;
+  const ov = document.getElementById('notify-modal-overlay');
+  if(ov && ov.style.display !== 'none') closeNotifyModal();
+});
+
+function renderEventTree(checked){
+  const box = document.getElementById('nf-events');
+  if(!box) return;
+  const cats = [];
+  _notifyEvents.forEach(function(e){ if(cats.indexOf(e.category) < 0) cats.push(e.category); });
+  box.innerHTML = cats.map(function(cat){
+    const rows = _notifyEvents.filter(e => e.category === cat);
+    const body = rows.map(function(e){
+      const id = 'nfe-' + e.key.replace(/\./g, '-');
+      return '<label style="display:flex;gap:6px;align-items:flex-start;padding:3px 0;cursor:pointer" title="'
+        + esc(e.desc || '') + '">'
+        + '<input type="checkbox" class="nf-ev" value="' + esc(e.key) + '" id="' + id + '"'
+        + (checked.indexOf(e.key) >= 0 ? ' checked' : '') + '>'
+        + '<span style="flex:1"><b>' + esc(e.label) + '</b>'
+        + (e.recommend ? ' <span class="label label-success">★建议</span>' : '')
+        + ' <code style="font-size:10.5px;opacity:.7">' + esc(e.key) + '</code></span></label>';
+    }).join('');
+    return '<div style="margin-bottom:8px"><div style="font-weight:600;font-size:12px;margin-bottom:2px">'
+      + esc(cat) + ' <button class="btn btn-xs" onclick="_notifyToggleCat(\'' + esc(cat) + '\')">全选/取消</button></div>'
+      + body + '</div>';
+  }).join('');
+}
+
+function _notifyToggleCat(cat){
+  const keys = _notifyEvents.filter(e => e.category === cat).map(e => e.key);
+  const boxes = [...document.querySelectorAll('#nf-events .nf-ev')].filter(b => keys.indexOf(b.value) >= 0);
+  const allOn = boxes.every(b => b.checked);
+  boxes.forEach(b => { b.checked = !allOn; });
+}
+
+function addNotifyPattern(){
+  const inp = document.getElementById('nf-pattern-input');
+  const v = (inp.value || '').trim();
+  if(!v) return;
+  if(v !== '*' && v.slice(-2) !== '.*'){ showToast('通配请写成 task.* 或 device.* 或 *', 'error'); return; }
+  if(_notifyPatterns.indexOf(v) < 0) _notifyPatterns.push(v);
+  inp.value = '';
+  renderNotifyPatterns();
+}
+
+function renderNotifyPatterns(){
+  const box = document.getElementById('nf-patterns');
+  if(!box) return;
+  box.innerHTML = _notifyPatterns.map(function(p, i){
+    return '<span class="label label-info" style="cursor:pointer" title="点一下移除" onclick="removeNotifyPattern(' + i + ')">'
+      + esc(p) + ' ×</span>';
+  }).join('') || '<span class="help">（无）</span>';
+}
+
+function removeNotifyPattern(i){
+  _notifyPatterns.splice(i, 1);
+  renderNotifyPatterns();
+}
+
+function closeNotifyModal(){
+  const ov = document.getElementById('notify-modal-overlay');
+  if(ov) ov.style.display = 'none';
+}
+
+// ================== 保存 / 删除 / 启停 / 测试 ==================
+function collectNotifyForm(){
+  const events = [...document.querySelectorAll('#nf-events .nf-ev')]
+    .filter(b => b.checked).map(b => b.value);
+  _notifyPatterns.forEach(function(p){ if(events.indexOf(p) < 0) events.push(p); });
+  const body = {name: (document.getElementById('nf-name').value || '').trim(),
+                format: document.getElementById('nf-format').value,
+                events: events,
+                agg_window: parseInt(document.getElementById('nf-agg').value, 10) || 0,
+                rate_limit_per_min: parseInt(document.getElementById('nf-rate').value, 10) || 0,
+                body_template: (document.getElementById('nf-body').value || '')};
+  const url = (document.getElementById('nf-url').value || '').trim();
+  if(url) body.url = url;                    // 留空 = 不修改（后端保留原值）
+  const sec = (document.getElementById('nf-secret').value || '').trim();
+  if(sec) body.secret = sec;
+  return body;
+}
+
+function saveNotifyHook(){
+  const body = collectNotifyForm();
+  if(!body.name){ showToast('请填名称', 'error'); return; }
+  if(!body.events.length){ showToast('至少要勾一个事件', 'error'); return; }
+  const id = _notifyEditingId;
+  const req = id ? apiPut('/api/notify/webhooks/' + id, body)
+                 : apiPost('/api/notify/webhooks', body);
+  req.then(function(r){
+    if(!r || !r.ok){
+      let msg = (r && r.error) || '保存失败';
+      if(r && r.errors && r.errors.length) msg = r.errors.join('；');
+      showToast(msg, 'error');
+      return;
+    }
+    showToast('已保存', 'success');
+    closeNotifyModal();
+    loadNotifyPanel();
+  });
+}
+
+function deleteNotifyHook(id){
+  const h = _notifyHooks.find(x => x.id === id) || {};
+  if(!confirm('删除 webhook「' + (h.name || '') + '」？\n（只是不再推送，不影响任何任务/设备数据）')) return;
+  apiDelete('/api/notify/webhooks/' + id).then(function(r){
+    if(!r || !r.ok){ showToast((r && r.error) || '删除失败', 'error'); return; }
+    showToast('已删除', 'success');
+    loadNotifyPanel();
+  });
+}
+
+function toggleNotifyHook(id, on){
+  apiPut('/api/notify/webhooks/' + id, {enabled: on}).then(function(r){
+    if(!r || !r.ok){ showToast((r && r.error) || '操作失败', 'error'); return; }
+    loadNotifyPanel();
+  });
+}
+
+function testNotifyHook(id){
+  showToast('正在发送测试消息…', 'success');
+  apiPost('/api/notify/webhooks/' + id + '/test', {}).then(function(r){
+    if(!r){ showToast('请求失败', 'error'); return; }
+    const detail = 'HTTP ' + (r.http_status == null ? '-' : r.http_status)
+      + (r.errcode ? ' · errcode ' + r.errcode : '')
+      + (r.elapsed_ms != null ? ' · ' + r.elapsed_ms + 'ms' : '')
+      + (r.attempts > 1 ? ' · 重试 ' + r.attempts + ' 次' : '')
+      + (r.error ? '\n' + r.error : '');
+    showToast(r.ok ? ('测试消息已发出（' + detail + '）') : ('发送失败（' + detail + '）'),
+              r.ok ? 'success' : 'error');
+    loadNotifyPanel();
+  });
+}
+
+function previewNotifyHook(){
+  const body = collectNotifyForm();
+  apiPost('/api/notify/preview', {hook: body, event: 'notify.test'}).then(function(r){
+    const box = document.getElementById('nf-preview');
+    if(!box) return;
+    if(!r || !r.ok){ box.innerHTML = '<span style="color:#dc2626">预览失败：' + esc((r && r.error) || '') + '</span>'; return; }
+    let html = '<div class="help">UTF-8 字节数：' + (r.bytes == null ? '-' : r.bytes)
+      + (r.byte_limit ? ' / 上限 ' + r.byte_limit : '')
+      + (r.truncated ? ' <b style="color:#b45309">（会截断）</b>' : '') + '</div>';
+    html += '<pre style="max-height:220px;overflow:auto;font-size:11px;background:#f6f7f9;padding:8px;border-radius:6px">'
+      + esc(r.request_body || '') + '</pre>';
+    box.innerHTML = html;
+  });
+}
+
+function saveNotifyGlobal(){
+  const on = document.getElementById('notify-global').checked;
+  const body = {global_enabled: on,
+                default_agg_window: parseInt(document.getElementById('notify-agg').value, 10) || 0,
+                default_rate_limit: parseInt(document.getElementById('notify-rate').value, 10) || 18};
+  apiPost('/api/notify/settings', body).then(function(r){
+    if(!r || !r.ok){ showToast((r && r.error) || '保存失败', 'error'); return; }
+    showToast('已保存（新配置对之后的事件生效）', 'success');
+    loadNotifyPanel();
+  });
+}
+
+function toggleNotifyGlobal(el){
+  apiPost('/api/notify/settings', {global_enabled: el.checked}).then(function(r){
+    if(!r || !r.ok){ el.checked = !el.checked; showToast((r && r.error) || '操作失败', 'error'); return; }
+    showToast(el.checked ? '通知总开关：已开启' : '通知总开关：已关闭（所有 webhook 暂停推送）', 'success');
+  });
+}

static/admin/recorder.js

@@ -0,0 +1,418 @@
+// ================== 动作录制器 ==================
+// 在设备截图上操作（点/划/按键/输入），自动翻译成**步骤**：
+//   · 点  → 命中元素就记「点击元素」(选择器)，抓不到就退化成「点击坐标」(百分比)
+//   · 划  → 记**「录制手势」**：完整轨迹点列 [[x,y,t_ms],…]，**纯回放**，不再套滑动逻辑
+//   · 停顿 → 可选记成「等待」（按真实间隔 ±15%）
+//
+// 两个录制来源：
+//   · 网页上录：在这个窗口里按住鼠标拖（采样路径 + 时间）
+//   · 手机上录：点「手机上录」后**用手指在真机上划**——后端读 getevent 抓真触屏，
+//     录到的是人手的真实轨迹（比在网页上模拟更真）
+//
+// 两种用法（同一个窗口）：
+//   mode='action'  —— 录一段，存成「自定义动作」（进动作库，能拖进任何任务）
+//   mode='gesture' —— 录到的手势直接回填给调用方（步骤编辑器里的「录制手势」步骤）
+//
+// 元素树用 /api/uiauto/snapshot 一次取齐（截图 + 元素），**每次操作后自动刷新**，
+// 这样下一次点击就能用最新的树翻译选择器（抖音这种没有 id 的界面靠 text/desc）。
+
+let _rec = null;
+
+function _recEl() { return document.getElementById('rec-overlay'); }
+
+async function openRecorder(opts) {
+  opts = opts || {};
+  if (_recEl()) return;
+  _rec = {
+    mode: opts.mode || 'action',
+    serial: opts.serial || '',
+    onDone: opts.onDone || null,
+    steps: [],
+    elements: [],
+    devW: 0, devH: 0, imgURL: '',
+    lastTs: 0, dragFrom: null, busy: false, keepPause: true,
+    samples: [], phone: null, autoPhone: !!opts.autoStartPhone,
+    shots: 0, unstable: false,
+  };
+  const ov = document.createElement('div');
+  ov.id = 'rec-overlay';
+  ov.className = 'modal-overlay show';   // .modal-overlay 默认 display:none，必须带 show
+  ov.innerHTML =
+    '<div class="modal-box rec-box">' +
+      '<div class="rec-head">' +
+        '<b>' + (_rec.mode === 'gesture' ? '录制手势' : '录制动作') + '</b>' +
+        '<select id="rec-device" class="form-control" style="width:auto" onchange="recPickDevice()"></select>' +
+        '<button class="btn btn-sm" onclick="recRefresh()">刷新画面</button>' +
+        '<label class="form-check"><input type="checkbox" id="rec-pause" checked onchange="_rec.keepPause=this.checked"><span>记录停顿</span></label>' +
+        '<span style="flex:1"></span>' +
+        '<button class="btn btn-sm" onclick="closeRecorder()">关闭</button>' +
+      '</div>' +
+      '<div class="rec-body">' +
+        '<div class="rec-stage" id="rec-stage"><div class="rec-hint">正在取画面…</div></div>' +
+        '<div class="rec-side">' +
+          '<div class="rec-ops">' +
+            '<button class="btn btn-sm" onclick="recKey(\'back\')">返回</button>' +
+            '<button class="btn btn-sm" onclick="recKey(\'home\')">Home</button>' +
+            '<button class="btn btn-sm" onclick="recKey(\'recent\')">最近</button>' +
+            '<button class="btn btn-sm" onclick="recKey(\'enter\')">回车</button>' +
+          '</div>' +
+          '<div class="rec-row"><input id="rec-text" class="form-control" placeholder="要输入的文字">' +
+            '<button class="btn btn-sm" onclick="recText()">输入</button></div>' +
+          '<div class="rec-ops">' +
+            '<button class="btn btn-sm" onclick="recAddWait()">+ 等待</button>' +
+            '<button class="btn btn-sm" onclick="recClear()">清空</button>' +
+          '</div>' +
+          '<div class="rec-list-title">录到的步骤 <span id="rec-count" class="text-muted"></span></div>' +
+          '<div class="rec-list" id="rec-list"></div>' +
+          '<div class="rec-foot" id="rec-foot"></div>' +
+        '</div>' +
+      '</div>' +
+    '</div>';
+  ov.addEventListener('mousedown', function (e) { if (e.target === ov) closeRecorder(); });
+  document.body.appendChild(ov);
+  await recLoadDevices();
+  recRender();
+  if (_rec.autoPhone && _rec.serial) recStartPhone();
+}
+
+function closeRecorder() {
+  const ov = _recEl();
+  if (ov) ov.remove();
+  _rec = null;
+}
+
+async function recLoadDevices() {
+  const sel = document.getElementById('rec-device');
+  if (!sel) return;
+  sel.innerHTML = '<option value="">选择设备…</option>';
+  const r = await apiGet('/api/devices');
+  if (!r || !r.ok) return;
+  (r.items || []).forEach(function (d) {
+    const o = document.createElement('option');
+    o.value = d.serial;
+    o.textContent = d.name ? (d.name + '（' + d.serial + '）') : d.serial;
+    sel.appendChild(o);
+  });
+  if (_rec.serial) { sel.value = _rec.serial; }
+  else if ((r.items || []).length) { sel.value = r.items[0].serial; _rec.serial = r.items[0].serial; }
+  if (_rec.serial) { await recWake(); recRefresh(); }
+}
+
+async function recPickDevice() {
+  const sel = document.getElementById('rec-device');
+  _rec.serial = sel ? sel.value : '';
+  _rec.elements = [];
+  recRender();
+  if (_rec.serial) { await recWake(); recRefresh(); }
+}
+
+// 录制前先唤醒设备：**息屏时 u2 抓 UI 树会退化到几十秒**（实测 65s，唤醒后 3.3s），
+// 截图也是一片黑。唤醒是幂等的，多调一次没有副作用。
+async function recWake() {
+  if (!_rec || !_rec.serial) return;
+  try {
+    const r = await apiPost('/api/device/screen_all', { mode: 'on', serials: [_rec.serial] });
+    if (r && r.ok) await new Promise(function (z) { setTimeout(z, 800); });
+  } catch (e) { /* 唤醒失败也继续，用户自己会看到黑屏 */ }
+}
+
+// 取一张快照：截图 + 元素树（同一个连接背靠背取，避免框错位）
+async function recRefresh() {
+  if (!_rec || !_rec.serial) return;
+  const r = await apiGet('/api/uiauto/snapshot?serial=' + encodeURIComponent(_rec.serial));
+  if (!r || !r.ok) {
+    const st = document.getElementById('rec-stage');
+    if (st) st.innerHTML = '<div class="rec-hint">取画面失败：' + esc((r && r.error) || '未知错误') + '</div>';
+    return;
+  }
+  _rec.imgURL = r.image || '';
+  _rec.devW = r.width || 0;
+  _rec.devH = r.height || 0;
+  _rec.elements = r.elements || [];
+  _rec.unstable = !!r.unstable;
+  _rec.shots++;
+  recPaint();
+}
+
+function recPaint() {
+  const st = document.getElementById('rec-stage');
+  if (!st) return;
+  if (!_rec.imgURL) { st.innerHTML = '<div class="rec-hint">正在取画面…</div>'; return; }
+  st.innerHTML = '<img id="rec-img" src="' + _rec.imgURL + '" draggable="false">' +
+    (_rec.unstable ? '<div class="rec-warn">画面在变化，这次框可能不准</div>' : '');
+  const img = document.getElementById('rec-img');
+  img.addEventListener('mousedown', recDown);
+  img.addEventListener('mousemove', recMove);
+  img.addEventListener('mouseup', recUp);
+  img.addEventListener('mouseleave', function () { _rec.dragFrom = null; recPaintOverlay(); });
+  recPaintOverlay();
+}
+
+// 拖动中的轨迹提示（录制时能看见自己划到哪）
+function recPaintOverlay() {
+  const st = document.getElementById('rec-stage');
+  if (!st) return;
+  let cv = document.getElementById('rec-overlay-line');
+  if (!cv) {
+    cv = document.createElement('div');
+    cv.id = 'rec-overlay-line';
+    cv.className = 'rec-line';
+    st.appendChild(cv);
+  }
+  if (!_rec.dragFrom) { cv.style.display = 'none'; return; }
+  cv.style.display = 'block';
+  const a = _rec.dragFrom;
+  const b = _rec.dragTo || a;
+  const x = Math.min(a.x, b.x), y = Math.min(a.y, b.y);
+  cv.style.left = x + 'px'; cv.style.top = y + 'px';
+  cv.style.width = Math.abs(b.x - a.x) + 'px';
+  cv.style.height = Math.abs(b.y - a.y) + 'px';
+}
+
+function _recPos(e) {
+  const img = document.getElementById('rec-img');
+  if (!img) return null;
+  const r = img.getBoundingClientRect();
+  const x = e.clientX - r.left, y = e.clientY - r.top;
+  if (x < 0 || y < 0 || x > r.width || y > r.height) return null;
+  // 显示坐标 → 设备坐标
+  const sx = _rec.devW / r.width, sy = _rec.devH / r.height;
+  return { x: Math.round(x * sx), y: Math.round(y * sy), rx: x, ry: y, cssW: r.width, cssH: r.height };
+}
+
+function recDown(e) {
+  if (_rec.busy) return;
+  const p = _recPos(e);
+  if (!p) return;
+  _rec.dragFrom = p; _rec.dragTo = null; _rec.dragT0 = Date.now();
+  // 采样：拖动过程中把每个点连时间一起记下来（这就是"轨迹"）
+  _rec.samples = [[p.x, p.y, 0]];
+  recPaintOverlay();
+}
+
+function recMove(e) {
+  if (!_rec.dragFrom) return;
+  const p = _recPos(e);
+  if (!p) return;
+  _rec.dragTo = p;
+  const t = Date.now() - _rec.dragT0;
+  const last = _rec.samples[_rec.samples.length - 1];
+  if (!last || t - last[2] >= 8 || Math.abs(p.x - last[0]) + Math.abs(p.y - last[1]) >= 3) {
+    if (_rec.samples.length < 400) _rec.samples.push([p.x, p.y, t]);
+  }
+  recPaintOverlay();
+}
+
+async function recUp(e) {
+  if (!_rec.dragFrom || _rec.busy) { _rec.dragFrom = null; return; }
+  const a = _rec.dragFrom;
+  const b = _recPos(e) || a;
+  const durMs = Date.now() - _rec.dragT0;
+  _rec.dragFrom = null;
+  recPaintOverlay();
+  const dist = Math.hypot(b.x - a.x, b.y - a.y);
+  if (dist < 12 || durMs < 60) {          // 视为点击
+    _rec.samples = [];
+    await recTap(a.x, a.y);
+  } else {
+    const pts = _rec.samples.slice();
+    pts.push([b.x, b.y, durMs]);          // 末点补上（决定手势收尾位置）
+    _rec.samples = [];
+    recPushGesture(pts, 'web');
+    await recRefresh();
+  }
+}
+
+// 一条录到的轨迹 → 「录制手势」步骤（**纯回放**：点列+时长原样存下，不再套滑动逻辑）
+function recPushGesture(points, src) {
+  if (!points || points.length < 2) { showToast('没录到有效轨迹（太短了）', 'error'); return; }
+  if (_rec.mode === 'gesture') {          // 回填模式：直接交给调用方，收工
+    const cb = _rec.onDone;
+    closeRecorder();
+    if (cb) cb({ points: points, speed: 1.0 }, src);
+    return;
+  }
+  const dur = points[points.length - 1][2] || 0;
+  _recPush({ type: 'gesture',
+             label: '录制手势 ' + points.length + '点/' + (dur / 1000).toFixed(1) + 's',
+             params: { points: points, speed: 1.0 } });
+}
+
+// ---------- 手机端录制（getevent 抓真手指） ----------
+async function recStartPhone() {
+  if (!_rec.serial) { showToast('先选设备', 'error'); return; }
+  const r = await apiPost('/api/gesture/record/start', { serial: _rec.serial });
+  if (!r || !r.ok) { showToast((r && r.error) || '开始失败', 'error'); return; }
+  _rec.phone = { token: r.token, t0: Date.now() };
+  showToast('开始录制——现在用手指在手机上划', 'success');
+  recRenderFoot();
+}
+
+async function recStopPhone() {
+  if (!_rec.phone) return;
+  const token = _rec.phone.token;
+  _rec.phone = null;
+  const r = await apiPost('/api/gesture/record/stop', { token: token });
+  if (!r || !r.ok) { showToast((r && r.error) || '停止失败', 'error'); recRenderFoot(); return; }
+  const gs = r.gestures || [];
+  if (!gs.length) {
+    showToast('没录到手势——请在手机屏幕上用指划一下（不是点）', 'error');
+    recRenderFoot(); return;
+  }
+  if (_rec.mode === 'gesture') { recPushGesture(gs[gs.length - 1], 'phone'); return; }
+  gs.forEach(function (g) { recPushGesture(g, 'phone'); });
+  showToast('录到 ' + gs.length + ' 个手势', 'success');
+  recRenderFoot();
+  recRefresh();
+}
+
+// ---------- 翻译：点击 → 步骤 ----------
+function _recFindElement(x, y) {
+  // 取包含该点的最小元素；优先可点击的（和 /api/screen/tap 的 snap 同一口径）
+  let best = null, bestClick = null;
+  (_rec.elements || []).forEach(function (el) {
+    const m = (el.bounds || '').match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+    if (!m) return;
+    const x1 = +m[1], y1 = +m[2], x2 = +m[3], y2 = +m[4];
+    if (!(x1 <= x && x <= x2 && y1 <= y && y <= y2)) return;
+    const area = (x2 - x1) * (y2 - y1);
+    const cand = { el: el, area: area, cx: Math.round((x1 + x2) / 2), cy: Math.round((y1 + y2) / 2) };
+    if (!best || area < best.area) best = cand;
+    if (String(el.clickable) === 'true' && (!bestClick || area < bestClick.area)) bestClick = cand;
+  });
+  return bestClick || best;
+}
+
+async function recTap(x, y) {
+  if (!_rec || _rec.busy) return;
+  _rec.busy = true;
+  try {
+    const hit = _recFindElement(x, y);
+    let step;
+    if (hit && hit.el.suggested && hit.el.suggested.value) {
+      step = { type: 'click', label: '点击' + _recShort(hit.el),
+               params: { selector_type: hit.el.suggested.type || 'xpath',
+                         selector_value: hit.el.suggested.value, wait_timeout: 2 } };
+    } else {
+      step = { type: 'click_xy', label: '点击坐标',
+               params: { x: Math.round(x / _rec.devW * 100), y: Math.round(y / _rec.devH * 100) } };
+    }
+    _recPush(step);
+    const r = await apiPost('/api/screen/tap', { serial: _rec.serial, x: x, y: y, snap: 1 });
+    if (r && !r.ok) showToast((r.error || '点击失败'), 'error');
+    await recRefresh();
+  } finally { _rec.busy = false; }
+}
+
+function _recShort(el) {
+  const s = el.text || el.description || el.name || el.resource_id || '';
+  return s ? ('「' + String(s).slice(0, 12) + '」') : '';
+}
+
+async function recKey(key) {
+  if (!_rec || !_rec.serial) { showToast('先选设备', 'error'); return; }
+  _recPush({ type: 'key_event', label: '按键 ' + key, params: { key: key } });
+  const r = await apiPost('/api/screen/key', { serial: _rec.serial, key: key });
+  if (r && !r.ok) showToast((r.error || '按键失败'), 'error');
+  await recRefresh();
+}
+
+async function recText() {
+  if (!_rec || !_rec.serial) { showToast('先选设备', 'error'); return; }
+  const inp = document.getElementById('rec-text');
+  const t = (inp ? inp.value : '').trim();
+  if (!t) { showToast('先填要输入的文字', 'error'); return; }
+  _recPush({ type: 'input_text', label: '输入 ' + t.slice(0, 8),
+             params: { mode: 'fixed', fixed_text: t, clear_first: false } });
+  const r = await apiPost('/api/screen/text', { serial: _rec.serial, text: t });
+  if (r && !r.ok) showToast((r.error || '输入失败'), 'error');
+  if (inp) inp.value = '';
+  await recRefresh();
+}
+
+function recAddWait() {
+  _recPush({ type: 'wait', label: '等待', params: { min: 1, max: 3 } });
+}
+
+// 入列：按需自动补一条「等待」（真实停顿，±15%），并刷新列表
+function _recPush(step) {
+  const now = Date.now();
+  if (_rec.keepPause && _rec.lastTs && step.type !== 'wait') {
+    const gap = (now - _rec.lastTs) / 1000;
+    if (gap >= 1.0) {
+      _rec.steps.push({ id: 'rec_' + Math.random().toString(36).slice(2, 8),
+                        type: 'wait', label: '等待 ' + gap.toFixed(1) + 's',
+                        params: { min: +(gap * 0.85).toFixed(1), max: +(gap * 1.15).toFixed(1) } });
+    }
+  }
+  step.id = 'rec_' + Math.random().toString(36).slice(2, 8);
+  _rec.steps.push(step);
+  _rec.lastTs = now;
+  recRender();
+}
+
+function recClear() { _rec.steps = []; _rec.lastTs = 0; recRender(); }
+
+function recDel(i) { _rec.steps.splice(i, 1); recRender(); }
+function recMove2(i, d) {
+  const j = i + d;
+  if (j < 0 || j >= _rec.steps.length) return;
+  const t = _rec.steps[i]; _rec.steps[i] = _rec.steps[j]; _rec.steps[j] = t;
+  recRender();
+}
+
+function recRender() {
+  const list = document.getElementById('rec-list');
+  if (!list) return;
+  const steps = _rec ? _rec.steps : [];
+  document.getElementById('rec-count').textContent = steps.length ? ('共 ' + steps.length + ' 步') : '';
+  list.innerHTML = steps.map(function (s, i) {
+    return '<div class="rec-item"><span class="rec-idx">' + (i + 1) + '</span>' +
+      '<span class="rec-label">' + esc(s.label || s.type) + '</span>' +
+      '<span class="rec-ops2">' +
+      '<button class="btn btn-xs" onclick="recMove2(' + i + ',-1)" title="上移">↑</button>' +
+      '<button class="btn btn-xs" onclick="recMove2(' + i + ',1)" title="下移">↓</button>' +
+      '<button class="btn btn-xs btn-danger" onclick="recDel(' + i + ')">×</button>' +
+      '</span></div>';
+  }).join('') || '<div class="text-muted" style="font-size:12px;padding:6px 0">还没有录到步骤——在左边画面上点一下或划一下试试</div>';
+  recRenderFoot();
+}
+
+function recRenderFoot() {
+  const foot = document.getElementById('rec-foot');
+  if (!foot) return;
+  const steps = _rec.steps;
+  if (_rec.mode === 'gesture') {
+    // 回填模式：录到就立刻填回那个步骤，不用再点确认
+    foot.innerHTML = _rec.phone
+      ? '<button class="btn btn-danger" onclick="recStopPhone()">■ 停止并填入</button>'
+      : '<button class="btn btn-primary" onclick="recStartPhone()">● 手机上录</button>' +
+        '<div class="help">或在左边画面上按住鼠标拖一下——录到就立刻填进那一步</div>';
+    return;
+  }
+  const phoneBtn = _rec.phone
+    ? '<button class="btn btn-danger" onclick="recStopPhone()">■ 停止手机录制</button>'
+    : '<button class="btn btn-primary" onclick="recStartPhone()">● 手机上录</button>';
+  foot.innerHTML =
+    '<div class="rec-row" style="margin-bottom:6px">' + phoneBtn +
+    '<span class="help" style="margin:0">' + (_rec.phone
+      ? '正在录：请用手指在手机屏幕上划，划完点「停止」'
+      : '手机上用手指划 = 录真手指轨迹；在左边画面上拖 = 网页录制') + '</span></div>' +
+    '<div class="rec-row"><input id="rec-name" class="form-control" placeholder="动作名，如「抖音-进评论」">' +
+    '<button class="btn btn-primary" onclick="recSaveAsAction()">存成动作</button></div>' +
+    '<div class="help">划出来的每一段都是一条「录制手势」步骤（按原路径与时长回放，不再套滑动逻辑）</div>';
+}
+
+async function recSaveAsAction() {
+  const el = document.getElementById('rec-name');
+  const name = (el ? el.value : '').trim();
+  if (!name) { showToast('先给动作起个名', 'error'); return; }
+  const steps = _rec.steps.filter(function (s) { return s.type !== 'wait' || true; })
+    .map(function (s) { return { type: s.type, label: s.label, params: s.params }; });
+  if (!steps.length) { showToast('还没有录到步骤', 'error'); return; }
+  const r = await apiPost('/api/custom_actions', { name: name, icon: '⏺', steps: steps });
+  if (!r || !r.ok) { showToast((r && r.error) || '保存失败', 'error'); return; }
+  showToast('已存成动作「' + name + '」（' + steps.length + ' 步）', 'success');
+  if (typeof loadCustomActions === 'function') loadCustomActions();
+  closeRecorder();
+}

static/admin/steplog.js

@@ -0,0 +1,143 @@
+// ================== 「日志 → 步骤明细」子分栏 ==================
+// 数据源：task_step_log 表（结构化），接口 /api/step_logs*（见 web/admin_api.py）。
+// 与「文件日志」的分工：那边是原始文本，这边能按设备/任务/时间/结果过滤、能导出。
+
+let _slOffset = 0;        // 分页偏移
+let _slTotal = 0;         // 命中总数
+let _slRunId = '';        // "只看某次运行"时的 run_id（空 = 不限）
+let _slInited = false;    // 下拉选项只拉一次
+
+function _slVal(id){const el=document.getElementById(id);return el?el.value:'';}
+
+function _slParams(){
+  const p=new URLSearchParams();
+  const put=(k,v)=>{if(v)p.set(k,v);};
+  put('serial', _slVal('sl-device'));
+  put('job_id', _slVal('sl-job'));
+  put('result', _slVal('sl-result'));
+  put('q', _slVal('sl-q').trim());
+  put('since', _slVal('sl-since'));
+  put('until', _slVal('sl-until'));
+  put('run_id', _slRunId);
+  p.set('limit', _slVal('sl-limit')||200);
+  p.set('offset', _slOffset);
+  return p;
+}
+
+async function loadStepLogs(reset){
+  const body=document.getElementById('sl-body');
+  if(!body)return;
+  if(reset)_slOffset=0;
+  const p=_slParams();
+  const r=await apiGet('/api/step_logs?'+p.toString());
+  if(!r||!r.ok){body.innerHTML='<tr><td colspan="9" class="text-muted">读取失败</td></tr>';return;}
+  _slTotal=r.total||0;
+  const rows=r.rows||[];
+  body.innerHTML = rows.length ? rows.map(_slRowHtml).join('')
+    : '<tr><td colspan="9" class="text-muted">（没有匹配的步骤记录——先跑一个任务，'
+      +'或在上面放宽筛选条件）</td></tr>';
+  // 提示栏：分页位置 + 保留期 + 运行期间丢弃计数（排障用）
+  const from=_slTotal?(_slOffset+1):0, to=_slOffset+rows.length;
+  let hint=`命中 ${_slTotal} 条 · 显示 ${from}-${to}`;
+  if(_slRunId)hint=`只看运行 ${_slRunId} · `+hint;
+  const st=r.stats||{};
+  if(st.dropped)hint+=` · 队列溢出丢弃 ${st.dropped} 条`;
+  if(st.failed)hint+=` · 落库失败 ${st.failed} 条`;
+  document.getElementById('sl-hint').textContent=hint;
+  document.getElementById('sl-page').textContent=
+    `第 ${Math.floor(_slOffset/(parseInt(_slVal('sl-limit'),10)||200))+1} 页`;
+  document.getElementById('sl-prev').disabled = _slOffset<=0;
+  document.getElementById('sl-next').disabled = _slOffset+rows.length>=_slTotal;
+  if(!_slInited){_slInited=true;loadStepFilters();}
+  if(reset)loadStepRuns();
+}
+
+// 结果 → 颜色。注意不能复用 .log-err/.log-warn/.log-info：那套的作用域是
+// .log-content（文件日志面板），表格里得用下面这套 res-*
+const _SL_RESULT={error:'res-error',unknown:'res-error',miss:'res-miss',
+                  cap:'res-miss',skip:'res-skip',ok:'res-ok'};
+
+function _slRowHtml(r){
+  const cls=_SL_RESULT[r.result]||'';
+  const dev=esc(r.device_name||r.serial||'');
+  const dur=r.duration_ms>=1000?(r.duration_ms/1000).toFixed(1)+'s':(r.duration_ms||0)+'ms';
+  return '<tr>'
+    +'<td class="text-muted" style="white-space:nowrap">'+esc(r.created_at||'')+'</td>'
+    +'<td title="'+esc(r.serial||'')+'">'+dev+'</td>'
+    +'<td>'+esc(r.job_name||'')+'</td>'
+    +'<td>'+esc(r.step_path||'')+'</td>'
+    +'<td>'+esc(r.step_label||'')+'</td>'
+    +'<td class="text-muted">'+esc(r.step_type||'')+'</td>'
+    +'<td class="'+cls+'">'+esc(r.result||'')+'</td>'
+    +'<td class="text-muted">'+dur+'</td>'
+    +'<td class="text-muted" title="'+esc(r.detail||'')+'">'+esc(_slTrim(r.detail,120))+'</td>'
+    +'</tr>';
+}
+
+function _slTrim(s,n){s=s||'';return s.length>n?s.slice(0,n)+'…':s;}
+
+function stepLogPage(delta){
+  const size=parseInt(_slVal('sl-limit'),10)||200;
+  _slOffset=Math.max(0,_slOffset+delta*size);
+  loadStepLogs(false);
+}
+
+function resetStepFilters(){
+  ['sl-q','sl-since','sl-until'].forEach(id=>{const el=document.getElementById(id);if(el)el.value='';});
+  ['sl-device','sl-job','sl-result'].forEach(id=>{const el=document.getElementById(id);if(el)el.value='';});
+  _slRunId='';
+  loadStepLogs(true);
+}
+
+function downloadStepLogs(){
+  const p=_slParams();
+  p.delete('limit');p.delete('offset');
+  window.location='/api/step_logs/download?'+p.toString();
+}
+
+// ---------- 筛选下拉（只列"明细里真的出现过"的设备/任务） ----------
+async function loadStepFilters(){
+  const r=await apiGet('/api/step_logs/filters');
+  if(!r||!r.ok)return;
+  const dev=document.getElementById('sl-device');
+  const job=document.getElementById('sl-job');
+  const keep=(sel,val)=>{const cur=sel.value;sel.innerHTML=val;sel.value=cur;};
+  keep(dev,'<option value="">全部设备</option>'+(r.devices||[]).map(d=>
+    '<option value="'+esc(d.serial)+'">'+esc(d.device_name||d.serial)+'</option>').join(''));
+  keep(job,'<option value="">全部任务</option>'+(r.jobs||[]).map(j=>
+    '<option value="'+esc(j.job_id)+'">'+esc(j.job_name||j.job_id)+'</option>').join(''));
+  document.getElementById('sl-note').textContent=
+    `明细保留 ${r.keep_days} 天（超期自动清理）；单次运行最多记录 `
+    +`${r.max_rows_per_run} 条（无限循环任务不会写爆这张表）。`;
+}
+
+// ---------- 最近运行概览（点一行 = 只看那次运行） ----------
+async function loadStepRuns(){
+  const p=new URLSearchParams();
+  if(_slVal('sl-device'))p.set('serial',_slVal('sl-device'));
+  if(_slVal('sl-job'))p.set('job_id',_slVal('sl-job'));
+  if(_slVal('sl-since'))p.set('since',_slVal('sl-since'));
+  if(_slVal('sl-until'))p.set('until',_slVal('sl-until'));
+  p.set('limit','20');
+  const r=await apiGet('/api/step_logs/runs?'+p.toString());
+  const body=document.getElementById('sl-runs-body');
+  if(!r||!r.ok){body.innerHTML='';return;}
+  const runs=r.runs||[];
+  document.getElementById('sl-runs-summary').textContent=
+    `最近运行概览（${runs.length} 次，点「查看」只看那次）`;
+  body.innerHTML = runs.length ? runs.map(x=>'<tr>'
+    +'<td class="text-muted" style="white-space:nowrap">'+esc(x.started_at||'')+'</td>'
+    +'<td>'+esc(x.device_name||x.serial||'')+'</td>'
+    +'<td>'+esc(x.job_name||'')+'</td>'
+    +'<td>'+x.steps+'</td>'
+    +'<td class="'+(x.failures?'res-error':'text-muted')+'">'+(x.failures||0)+'</td>'
+    +'<td><button class="btn btn-sm" onclick="filterByRun(\''+esc(x.run_id)+'\')">查看</button></td>'
+    +'</tr>').join('')
+    : '<tr><td colspan="6" class="text-muted">（暂无运行记录）</td></tr>';
+}
+
+function filterByRun(runId){
+  _slRunId=runId||'';
+  document.getElementById('sl-runs-box').open=false;
+  loadStepLogs(true);
+}

static/admin/system.js

@@ -79,14 +79,19 @@ function renderRestorePreview(p){
   const rows=(p.tables||[]).map(t=>
     '<tr><td>'+esc(t.label||t.table)+'</td><td>'+esc(t.table)+'</td><td>'+esc(t.rows)+'</td></tr>').join('');
   const warns=(p.warnings||[]).map(w=>'<li>'+esc(w)+'</li>').join('');
+  const crossEnv=!!(p.source_env&&p.current_env&&p.source_env!==p.current_env);
   box.innerHTML=
     '<table class="table table-hover table-sm" style="max-width:560px">'+
       '<tbody>'+
         '<tr><th style="width:120px">文件</th><td>'+esc(p.file_name||'')+'（'+(p.file_size!=null?fmtSize(p.file_size):'')+'）</td></tr>'+
         '<tr><th>库结构版本</th><td>备份 v'+esc(p.schema_version)+' / 当前 v'+esc(p.current_schema_version)+'</td></tr>'+
+        '<tr><th>来源 / 当前环境</th><td>'+(p.source_env?esc(p.source_env):'（旧版备份，未记录）')+' → '+esc(p.current_env||'未登记')+'</td></tr>'+
         '<tr><th>完整性</th><td>'+esc(p.integrity||'')+'</td></tr>'+
       '</tbody>'+
     '</table>'+
+    (crossEnv?'<label style="display:block;margin:8px 0;padding:8px 12px;background:#fdecea;border:1px solid #f5c6cb;border-radius:6px">'+
+      '<input type="checkbox" id="restore-force-env"> '+
+      '允许跨环境导入（'+esc(p.source_env)+' → '+esc(p.current_env)+'）—— 默认拒绝</label>':'')+
     '<div class="section-title" style="margin-top:8px">表数据行数</div>'+
     '<table class="table table-hover table-sm" style="max-width:560px"><thead><tr><th>业务</th><th>表</th><th>行数</th></tr></thead><tbody>'+(rows||'<tr><td colspan="3">—</td></tr>')+'</tbody></table>'+
     (warns?'<div style="background:#fff3cd;border:1px solid #ffda6a;color:#7a5b00;padding:8px 12px;border-radius:6px;margin-top:8px"><ul style="margin:0;padding-left:18px">'+warns+'</ul></div>':'');
@@ -104,10 +109,12 @@ async function applyRestore(){
   const applyBtn=document.getElementById('btn-apply-restore');
   const st=document.getElementById('restore-status');
   if(!_restoreToken)return;
-  if(!confirm('确认应用导入？\n\n系统会先自动备份当前库（data/backups/pre_restore_*.db），再把待导入数据覆盖现有全部数据。\n导入将在重启 web_server 后生效。\n\n确定继续？'))return;
+  const forceEl=document.getElementById('restore-force-env');
+  const force=!!(forceEl&&forceEl.checked);
+  if(!confirm('确认应用导入？\n\n系统会先自动备份当前库（data/backups/pre_restore_*.zip），再把待导入数据覆盖现有全部数据。\n导入将在重启 web_server 后生效。\n\n确定继续？'))return;
   if(applyBtn)applyBtn.disabled=true;
   if(st)st.textContent='正在生成恢复任务…';
-  const r=await apiPost('/api/system/backup/apply',{token:_restoreToken});
+  const r=await apiPost('/api/system/backup/apply',{token:_restoreToken,force_env_mismatch:force});
   if(!r)return;
   if(r.ok){
     const box=document.getElementById('restore-preview');

static/admin/taskgen.js

@@ -0,0 +1,507 @@
+// ================== AI 建任务（AI 自己探索 → 写出任务步骤） ==================
+// 链路：
+//   需求 → POST /api/agent/run{mode:'designer'}
+//        → AI 用 de_* 工具在真机上探索（看屏 / 读元素树 / 点按验证）
+//        → 调平台级本地工具 submit_task 提交草稿（服务端用 core/task_draft 校验，
+//          不通过就把 errors 回灌给模型让它改）
+//        → SSE done 带草稿 → 这里预览 → 打开步骤编辑器预填 → **用户点保存才入库**
+// 设计见 doc/AI_TASK_GEN.md；契约与两条红线（AI 不直接落库、有副作用的动作不真做）在 §5。
+
+let _tgInit = false;
+let _tgStream = null;     // EventSource
+let _tgBusy = false;
+let _tgRunId = '';        // 当前已订阅的 run（切 Tab 回来时避免重复订阅）
+let _tgDraft = null;      // {summary, task, notes, evidence}
+let _tgWarnings = [];
+let _tgPrompt = '';       // 本次需求（回存草稿时带上）
+let _tgLiveSerial = '';
+
+// ---------------- 初始化 ----------------
+function initTaskGen(){
+  if(!_tgInit){
+    _tgInit = true;
+    const inp = document.getElementById('tg-prompt');
+    if(inp){
+      inp.addEventListener('keydown', ev=>{
+        if(ev.key==='Enter' && (ev.ctrlKey||ev.metaKey)){ ev.preventDefault(); startExplore(); }
+      });
+    }
+  }
+  tgLoadDevices();
+  tgLoadGroups();
+  tgRestore();
+  tgRearmLive();
+}
+
+// 切走再切回来时，观众侧的 MJPEG 长连接可能被浏览器挂起（画面定格）——
+// 重新拉一次流，画面接着动
+function tgRearmLive(){
+  const card = document.getElementById('tg-live-card');
+  const img = document.getElementById('tg-live-img');
+  if(!card || !img || !_tgLiveSerial || card.style.display === 'none') return;
+  img.src = '/api/screen/stream?serial=' + encodeURIComponent(_tgLiveSerial)
+          + '&q=80&fps=8&t=' + Date.now();
+}
+
+function tgExample(){
+  const inp = document.getElementById('tg-prompt');
+  if(!inp) return;
+  inp.value = '建一个跑 2 小时的任务：自动刷抖音，随机点赞（概率低一点，像真人）；'
+            + '有弹窗就关掉；评论这种拿不准的先别真发。';
+  inp.focus();
+}
+
+function tgToggleAdv(){
+  const box = document.getElementById('tg-adv');
+  const arrow = document.getElementById('tg-adv-arrow');
+  if(!box) return;
+  const show = box.style.display === 'none';
+  box.style.display = show ? 'block' : 'none';
+  if(arrow) arrow.textContent = show ? '▾' : '▸';
+}
+function tgToggleTarget(){
+  const v = (document.getElementById('tg-target')||{}).value;
+  const w = document.getElementById('tg-group-wrap');
+  if(w) w.style.display = (v==='group') ? 'block' : 'none';
+}
+function tgToggleSched(){
+  const v = (document.getElementById('tg-sched-mode')||{}).value;
+  const w = document.getElementById('tg-sched-wrap');
+  if(w) w.style.display = (v==='daily') ? 'flex' : 'none';
+}
+
+// ---------------- 设备 / 分组 ----------------
+function tgLoadDevices(){
+  apiGet('/api/agent/devices').then(r=>{
+    if(!r||!r.ok) return;
+    const sel = document.getElementById('tg-serial');
+    if(!sel) return;
+    const cur = sel.value;
+    const devs = (r.devices||[]).filter(x=>x.online);
+    // 建任务页不按 serial 形态过滤：USB 序列号与 IP:5555 都是合法的 AI 目标
+    sel.innerHTML = '<option value="">请选择设备…</option>'
+      + devs.map(d=>{
+          const label = devText(d.name, d.serial) + (d.model ? ' · ' + d.model : '')
+            + (d.busy ? ' ⛔ 任务中：' + d.task_job : '');
+          return '<option value="'+esc(d.serial)+'"' + (d.busy?' disabled':'')
+            + '>' + esc(label) + '</option>';
+        }).join('');
+    if(cur && [...sel.options].some(o=>o.value===cur)) sel.value = cur;
+  });
+}
+
+function tgLoadGroups(){
+  apiGet('/api/groups').then(r=>{
+    if(!r||!r.ok) return;
+    const sel = document.getElementById('tg-group');
+    if(!sel) return;
+    sel.innerHTML = '<option value="">选择分组…</option>'
+      + (r.groups||[]).map(g=>'<option value="'+esc(g.name)+'">'+esc(g.name)
+                              +'（'+((g.serials||[]).length)+' 台）</option>').join('');
+  });
+}
+
+// ---------------- 收集页面上的任务设置 ----------------
+// 返回 {settings, hints}：settings 是服务端 validate_draft 的 overrides（页面填的说了算），
+// hints 是要写进提示词告诉模型的自然语言（避免模型自己编一套跟页面冲突的调度）。
+function tgCollectSettings(){
+  const v = id => { const e = document.getElementById(id); return e ? (e.value||'').trim() : ''; };
+  const s = {}, hints = [];
+  if(v('tg-name')) s.name = v('tg-name');
+  const tmode = v('tg-target');
+  const serial = v('tg-serial');
+  if(tmode){ s.target_mode = tmode; s.serial = serial; }
+  if(tmode === 'group'){
+    if(!v('tg-group')){ showToast('选了「按分组」但没选分组','error'); return null; }
+    s.group_name = v('tg-group');
+  }
+  const smode = v('tg-sched-mode');
+  if(smode === 'once'){ s.schedule = {mode:'once'}; s.schedule_hint = '手动启动（不自动跑）'; }
+  if(smode === 'daily'){
+    const st = v('tg-sched-start'), sp = v('tg-sched-stop');
+    if(!st){ showToast('选了「每天定时」但没填启动时间','error'); return null; }
+    const cron = tgTimeToCron(st);
+    if(sp){
+      s.schedule = {mode:'cron_stop', cron:cron, stop_cron:tgTimeToCron(sp)};
+      s.schedule_hint = '每天 ' + st + ' 启动、' + sp + ' 停止';
+    }else{
+      s.schedule = {mode:'cron', cron:cron};
+      s.schedule_hint = '每天 ' + st + ' 启动（不自动停止）';
+    }
+  }
+  const dur = parseInt(v('tg-maxdur'), 10);
+  if(dur > 0){ s.max_duration = dur; }
+  return {settings: s, hints: hints};
+}
+
+// "20:30" → "30 20 * * *"（每天）
+function tgTimeToCron(hhmm){
+  const m = String(hhmm||'').match(/^(\d{1,2}):(\d{2})$/);
+  if(!m) return '';
+  return parseInt(m[2],10) + ' ' + parseInt(m[1],10) + ' * * *';
+}
+
+// ---------------- 发起探索 ----------------
+function startExplore(){
+  if(_tgBusy) return;
+  const prompt = ((document.getElementById('tg-prompt')||{}).value||'').trim();
+  if(!prompt){ showToast('先说说要做什么','error'); return; }
+  const serial = ((document.getElementById('tg-serial')||{}).value||'').trim();
+  if(!serial){ showToast('请选择一台设备（AI 只操作你选定的设备）','error'); return; }
+  const cfg = tgCollectSettings();
+  if(!cfg) return;
+  _tgPrompt = prompt;
+  _tgDraft = null; _tgWarnings = [];
+  document.getElementById('tg-stream').innerHTML = '';
+  document.getElementById('tg-draft').innerHTML = '';
+  tgSetBusy(true, '正在启动…');
+  apiPost('/api/agent/run', {prompt: prompt, serial: serial,
+                             mode: 'designer', settings: cfg.settings})
+    .then(r=>{
+      if(!r || !r.ok){
+        tgSetBusy(false, '');
+        showToast((r&&r.error)||'启动失败','error');
+        return;
+      }
+      tgWatch(serial);
+      listenTaskGenStream(r.run_id);
+    });
+}
+
+function stopExplore(){
+  apiPost('/api/agent/stop', {}).then(r=>{
+    showToast((r&&r.ok) ? '已请求停止' : ((r&&r.error)||'停止失败'),
+              (r&&r.ok)?'success':'error');
+  });
+}
+
+function tgSetBusy(busy, text){
+  _tgBusy = busy;
+  const b = document.getElementById('tg-start'), s = document.getElementById('tg-stop');
+  if(b) b.disabled = busy;
+  if(s) s.style.display = busy ? 'inline-block' : 'none';
+  if(text !== undefined) tgStatus(text);
+}
+function tgStatus(t){
+  const el = document.getElementById('tg-status');
+  if(el) el.textContent = t || '';
+}
+
+// ---------------- 事件流 ----------------
+function listenTaskGenStream(runId){
+  if(_tgStream) _tgStream.close();
+  _tgRunId = runId;
+  const es = new EventSource('/api/agent/stream?run_id=' + runId);
+  _tgStream = es;
+  let steps = 0;
+
+  es.addEventListener('delta', ev=>{
+    let d = {}; try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    if(d.kind === 'reasoning') return;              // 推理链不铺在回放区（噪音太大）
+    if(d.text) tgStatus('AI 思考中… ' + String(d.text).replace(/\s+/g,' ').slice(-60));
+  });
+
+  es.addEventListener('usage', ev=>{
+    let d = {}; try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    tgToken(d);
+  });
+
+  es.addEventListener('step', ev=>{
+    let d = {}; try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    steps++;
+    tgFollow(d.args);
+    tgAddCard(d.tool, d.args, d.image, d.error);
+    tgStatus('已执行 ' + steps + ' 步…');
+  });
+
+  es.addEventListener('done', ev=>{
+    let d = {}; try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    tgSetBusy(false, '');
+    if(d.draft){
+      _tgDraft = d.draft; _tgWarnings = d.warnings || [];
+      tgRenderDraft();
+      if(tgAutoCreateOn()){
+        // 用户勾了「探索完直接创建」：不再等确认，直接建（服务端仍会再校验一次）
+        tgStatus('探索完成，正在直接创建任务…');
+        createDraft(true);
+        endTaskGenStream();
+        return;
+      }
+      tgStatus('探索完成，共 ' + steps + ' 步。请核对草稿后创建任务。');
+    }else{
+      tgStatus(steps ? ('探索结束（' + steps + ' 步），但没有产出草稿。')
+                     : '没有什么可做的，AI 没给出草稿。');
+      tgAddCard('⚠ 未产出草稿',
+                (d.draft_error || 'AI 没有提交任务草稿 —— 可能是需求太模糊，或设备/App 不可用。'
+                 + ' 可以补一句更具体的要求再试。'));
+    }
+    endTaskGenStream();
+  });
+
+  es.addEventListener('error', ev=>{
+    let msg = '连接中断';
+    try{ if(ev.data) msg = (JSON.parse(ev.data)||{}).message || msg; }catch(e){}
+    tgSetBusy(false, '');
+    tgAddCard('⚠ 出错', msg);
+    endTaskGenStream();
+  });
+
+  es.onerror = ()=>{
+    // 与聊天页同理：不在这里收尾——断网/节流会触发 onerror，但后台仍在跑，
+    // EventSource 会自动重连，服务端队列保留积压事件。
+    if(_tgBusy && es.readyState === EventSource.CLOSED){
+      tgStatus('⚠ 实时连接中断，探索仍在后台进行；刷新页面可恢复。');
+    }
+  };
+}
+
+function endTaskGenStream(){
+  if(_tgStream){ _tgStream.close(); _tgStream = null; }
+}
+
+function tgAddCard(tool, args, image, err){
+  const box = document.getElementById('tg-stream');
+  if(!box) return;
+  const empty = box.querySelector('.agent-empty');
+  if(empty) empty.remove();
+  const card = document.createElement('div');
+  card.className = 'agent-toolcard';
+  const argsTxt = typeof args === 'string' ? args
+                  : JSON.stringify(args || {}, null, 0).slice(0, 240);
+  card.innerHTML = '<span class="dot"></span>'
+    + '<code style="color:var(--teal)">' + esc(tool||'') + '</code> '
+    + '<span class="text-muted">' + esc(argsTxt || '') + '</span>';
+  if(err){
+    const e = document.createElement('div');
+    e.className = 'tg-err';
+    e.textContent = '⚠ ' + err;
+    card.appendChild(e);
+  }
+  if(image){
+    const img = document.createElement('img');
+    img.src = 'data:image/jpeg;base64,' + image;
+    img.style.cursor = 'zoom-in';
+    img.onclick = ()=> zoomScreenshot(img);
+    card.appendChild(img);
+  }
+  box.appendChild(card);
+  box.scrollTop = box.scrollHeight;
+}
+
+function tgToken(u){
+  const el = document.getElementById('tg-token');
+  if(el && u && u.total_tokens) el.textContent = 'token ' + _fmtInt(u.total_tokens)
+                                                + '（' + (u.calls||0) + ' 次调用）';
+}
+
+// 跟随画面：AI 一动哪个设备就切哪个（复用平台 MJPEG 流）
+function tgFollow(args){
+  let a = args;
+  if(typeof args === 'string'){ try{ a = JSON.parse(args); }catch(e){ return; } }
+  if(a && a.serial) tgWatch(a.serial);
+}
+function tgWatch(serial){
+  if(!serial || serial === _tgLiveSerial) return;
+  _tgLiveSerial = serial;
+  const card = document.getElementById('tg-live-card');
+  const img = document.getElementById('tg-live-img');
+  if(!card || !img) return;
+  card.style.display = 'block';
+  img.style.display = 'block';
+  img.src = '/api/screen/stream?serial=' + encodeURIComponent(serial)
+          + '&q=80&fps=8&t=' + Date.now();
+  const s = document.getElementById('tg-live-serial');
+  if(s) s.textContent = serial;
+}
+
+// ---------------- 草稿预览 ----------------
+function tgRenderDraft(){
+  const box = document.getElementById('tg-draft');
+  if(!box) return;
+  if(!_tgDraft){ box.innerHTML = ''; return; }
+  const task = _tgDraft.task || {};
+  const steps = ((task.params||{}).steps) || [];
+  const html = []
+    .concat(['<h4>📝 ' + esc(task.name || _tgDraft.summary || '任务草稿') + '</h4>'])
+    .concat(['<div class="tg-hint">' + esc(_tgDraft.summary || '') + '</div>'])
+    .concat(['<div class="tg-hint">目标：' + esc(tgTargetText(task.target))
+             + ' ｜ 调度：' + esc(tgScheduleText(task.schedule))
+             + ' ｜ 时长上限：' + esc(String((task.params||{}).max_duration || 0)) + ' 秒</div>'])
+    .concat(['<div style="margin-top:8px">'])
+    .concat(tgRenderSteps(steps, 0))
+    .concat(['</div>']);
+  if((_tgWarnings||[]).length){
+    html.push('<div class="tg-warn"><b>⚠ ' + _tgWarnings.length + ' 处提醒（不拦，但请核对）</b>'
+      + _tgWarnings.map(w=>'<div>· ' + esc(w) + '</div>').join('') + '</div>');
+  }
+  if((_tgDraft.notes||[]).length){
+    html.push('<div class="tg-note"><b>需要人工复核</b>'
+      + _tgDraft.notes.map(n=>'<div>· ' + esc(n) + '</div>').join('') + '</div>');
+  }
+  const ev = _tgDraft.evidence || [];
+  if(ev.length){
+    html.push('<details class="tg-evidence"><summary>探索依据（' + ev.length + ' 条）</summary>'
+      + ev.map(e=>'<div>' + esc(e.screen || '') + ' · '
+                  + esc(e.selector_type || '') + '='
+                  + esc(e.selector_value || '') + ' · '
+                  + esc(e.verified || '') + '</div>').join('')
+      + '</details>');
+  }
+  html.push('<div class="tg-btns">'
+    + '<button class="btn btn-primary" onclick="createDraft(false)" title="按草稿直接建成任务（可在任务页继续改）；不需要人工核对时用它">'
+    + '✓ 直接创建任务</button>'
+    + '<button class="btn" onclick="openDraftInEditor()" title="打开步骤编辑器预填，核对/试跑后再保存">'
+    + '在步骤编辑器中核对</button>'
+    + '<button class="btn" onclick="discardDraft()">丢弃</button>'
+    + '</div>');
+  box.innerHTML = '<div class="tg-draft">' + html.join('') + '</div>';
+}
+
+function tgRenderSteps(steps, depth){
+  const pad = '  '.repeat(Math.min(depth, 5));
+  return (steps||[]).map(s=>{
+    const p = s.params || {};
+    const bits = [];
+    if(p.selector_value) bits.push(p.selector_type + '=' + p.selector_value);
+    if(p.package) bits.push(p.package);
+    if(p.direction) bits.push(p.direction);
+    if(p.key) bits.push(p.key);
+    if(p.min !== undefined && p.max !== undefined) bits.push(p.min + '~' + p.max + 's');
+    if(p.loop_mode) bits.push(p.loop_mode);
+    if(p.probability !== undefined && p.probability < 100) bits.push(p.probability + '%');
+    let row = '<div class="tg-step">' + esc(pad) + '<span class="t">' + esc(s.type) + '</span>'
+      + (s.label ? ' 「' + esc(s.label) + '」' : '')
+      + (bits.length ? ' <span class="p">' + esc(bits.join(' · ')) + '</span>' : '')
+      + '</div>';
+    if(Array.isArray(p.children)) row += tgRenderSteps(p.children, depth+1);
+    if(Array.isArray(p.then)) row += tgRenderSteps(p.then, depth+1);
+    if(Array.isArray(p.else)) row += tgRenderSteps(p.else, depth+1);
+    return row;
+  }).join('');
+}
+
+function tgTargetText(t){
+  t = t || {};
+  if(t.mode === 'serial') return '指定设备 ' + (t.serial || '');
+  if(t.mode === 'group') return '分组 ' + (t.group_name || '');
+  return '全部空闲设备';
+}
+function tgScheduleText(s){
+  s = s || {};
+  if(s.mode === 'cron') return '每天/定时 ' + (s.cron || '');
+  if(s.mode === 'cron_stop') return '定时 ' + (s.cron || '') + ' → 停 ' + (s.stop_cron || '');
+  return '手动（不自动启动）';
+}
+
+// ---------------- 草稿的动作 ----------------
+async function openDraftInEditor(){
+  if(!_tgDraft){ showToast('还没有草稿','error'); return; }
+  // 步骤编辑器要用到任务类型/分组/设备下拉，先确保它们已加载
+  await loadTasks();
+  openTaskModal(null, {task: _tgDraft.task, notes: _tgDraft.notes || [],
+                       warnings: _tgWarnings});
+}
+
+// 勾了「探索完直接创建」就用它
+function tgAutoCreateOn(){
+  const c = document.getElementById('tg-auto-create');
+  return !!(c && c.checked);
+}
+
+// 把草稿直接建成任务（服务端取暂存草稿 → 再校验 → add_job → 清草稿）
+// auto=true 表示是勾了开关后的自动创建（不再弹确认）
+function createDraft(auto){
+  if(!_tgDraft){ showToast('还没有草稿','error'); return; }
+  const name = ((_tgDraft.task||{}).name) || '这条任务';
+  if(!auto && !confirm('直接创建任务「' + name + '」？\n\n'
+      + '创建后就是一条正式的可调度任务（可在任务页编辑/停用），'
+      + '不再经过步骤编辑器的核对。')) return;
+  const cfg = tgCollectSettings();
+  tgStatus('正在创建任务…');
+  apiPost('/api/agent/task_draft/create', {
+    serial: ((document.getElementById('tg-serial')||{}).value||''),
+    overrides: cfg ? cfg.settings : {}
+  }).then(r=>{
+    if(!r || !r.ok){
+      const errs = (r && r.errors && r.errors.length)
+        ? '：' + r.errors.slice(0,3).join('；') : '';
+      showToast(((r&&r.error)||'创建失败') + errs, 'error');
+      tgStatus('创建失败 —— 可以「在步骤编辑器中核对」后手工保存');
+      return;
+    }
+    const job = r.job || {};
+    _tgDraft = null; _tgWarnings = [];
+    const box = document.getElementById('tg-draft');
+    if(box){
+      box.innerHTML = '<div class="tg-draft"><h4>✅ 任务已创建：' + esc(job.name||'') + '</h4>'
+        + '<div class="tg-hint">下次运行：' + esc(job.next_run || '手动触发')
+        + ' ｜ 调度：' + esc(tgScheduleText(job.schedule))
+        + ' ｜ id ' + esc(job.id||'') + '</div>'
+        + ((r.warnings||[]).length
+           ? '<div class="tg-warn">' + r.warnings.map(w=>'· ' + esc(w)).join('<br>') + '</div>'
+           : '')
+        + '<div class="tg-btns">'
+        + '<button class="btn btn-primary" onclick="showTab(\'tasks\')">去任务页看</button>'
+        + '<button class="btn" onclick="tgResetDraftView()">再探索一条</button>'
+        + '</div></div>';
+    }
+    tgStatus('任务已创建：' + (job.name||''));
+    showToast('任务「' + (job.name||'') + '」已创建', 'success');
+    if(typeof loadTasks === 'function') loadTasks();
+  });
+}
+
+function tgResetDraftView(){
+  _tgDraft = null; _tgWarnings = [];
+  const box = document.getElementById('tg-draft');
+  if(box) box.innerHTML = '';
+  tgStatus('');
+}
+
+function discardDraft(){
+  if(!confirm('丢弃这份草稿？')) return;
+  apiPost('/api/agent/task_draft/clear', {}).then(r=>{
+    if(!r||!r.ok){ showToast((r&&r.error)||'丢弃失败','error'); return; }
+    _tgDraft = null; _tgWarnings = [];
+    document.getElementById('tg-draft').innerHTML = '';
+    tgStatus('已丢弃草稿');
+  });
+}
+
+// ---------------- 页面恢复（刷新/重进） ----------------
+function tgRestore(){
+  apiGet('/api/agent/task_draft').then(r=>{
+    if(!r||!r.ok) return;
+    // 运行中的 designer 由本页接管订阅；聊天页见 agent.js 的 mode 判断
+    if(r.running && r.mode === 'designer' && r.run_id){
+      tgSetBusy(true, '探索进行中…');
+      // 已经在盯着同一轮了（切走再切回来）→ 别重复订阅：
+      // 重订阅会让服务端把这一轮从头发一遍（历史缓冲），卡片就成两份了
+      if(_tgRunId === r.run_id && _tgStream && _tgStream.readyState !== 2){
+        tgStatus('探索进行中…');
+        return;
+      }
+      // 换了一轮 / 刚刷新过页面：回放区清空重建（服务端会把已发生的事件补发回来）
+      const box = document.getElementById('tg-stream');
+      if(box) box.innerHTML = '';
+      const db = document.getElementById('tg-draft');
+      if(db) db.innerHTML = '';
+      tgStatus('探索进行中…（已连接，回放会从头补齐）');
+      listenTaskGenStream(r.run_id);
+      return;
+    }
+    if(r.draft){          // 运行态里就有（同一次会话内切页回来）
+      _tgDraft = r.draft; _tgWarnings = [];
+      tgRenderDraft();
+      return;
+    }
+    const saved = r.saved;
+    if(saved && saved.draft){
+      _tgDraft = saved.draft; _tgWarnings = saved.warnings || [];
+      tgRenderDraft();
+      tgStatus('已恢复 ' + (saved.created || '') + ' 的草稿（可直接创建，或重新探索）');
+      const inp = document.getElementById('tg-prompt');
+      if(inp && saved.prompt) inp.value = saved.prompt;
+    }
+  });
+}

static/admin/tasks.js

@@ -64,14 +64,157 @@ function renderTaskRow(j){
   '</tr>';
 }
 
-function openTaskModal(jobId){
+// 任务信封归一化：补齐 7 个键，避免下游无保护访问
+// （原文只对"已存在的 job"安全，AI 草稿/半成品信封会让 j.retry.max_attempts 之类直接抛错）
+function _normalizeTaskEnv(env){
+  const e=env||{}, t=e.target||{}, s=e.schedule||{}, r=e.retry||{}, p=e.params||{};
+  return {
+    name:e.name||'',
+    task_type:e.task_type||'generic_steps',
+    enabled:(e.enabled===undefined)?true:!!e.enabled,
+    target:{mode:t.mode||'all', group_name:t.group_name||'', serial:t.serial||''},
+    schedule:{mode:s.mode||'once', cron:s.cron||'', stop_cron:s.stop_cron||'',
+              window:s.window||null},
+    retry:{max_attempts:r.max_attempts||1, delay:r.delay||60},
+    params:Object.assign({}, p)
+  };
+}
+
+// ================== 公共巡检（任务级，独立于步骤画布） ==================
+// 与后端 core/patrol.py 的 CHECKS/ACTIONS 一一对应；选项变动时两边一起改。
+// 存进任务 params.watchers，worker 在步骤之间穿插执行（见 core/patrol.py 模块注释）。
+const _PATROL_CHECKS=[
+  ['screen_off','屏幕熄灭',''], ['screen_on','屏幕亮着',''],
+  ['element_exists','元素存在','selector'], ['element_missing','元素不存在','selector'],
+  ['foreground_is','前台是该App','package'], ['foreground_not','前台不是该App','package'],
+];
+const _PATROL_ACTIONS=[
+  ['none','只发通知，不动设备'], ['screen_on','点亮屏幕'],
+  ['screen_off','熄灭屏幕'], ['stop_self','停止本设备任务'],
+];
+let _patrolItems=[];
+
+function patrolInit(items){
+  _patrolItems=(items||[]).filter(function(x){return x&&typeof x==='object';})
+    .map(function(x){return Object.assign({},x);});
+  patrolRender();
+}
+function patrolAdd(){
+  patrolSync();
+  _patrolItems.push({enabled:true,name:'',interval:60,check:'screen_off',selector_type:'xpath',
+                     selector_value:'',action:'screen_on',notify:true,
+                     title:'',message:'',cooldown:300});
+  patrolRender();
+}
+function patrolRemove(i){
+  patrolSync();
+  _patrolItems.splice(i,1);
+  patrolRender();
+}
+// DOM → 内存（重渲染前必须调，否则刚填的值会被覆盖）
+function patrolSync(){
+  const list=document.getElementById('patrol-list');
+  if(!list)return;
+  list.querySelectorAll('.patrol-card').forEach(function(card,i){
+    const w=_patrolItems[i]; if(!w)return;
+    const get=function(k){
+      const el=card.querySelector('[data-pk="'+k+'"]');
+      if(!el)return undefined;
+      return el.type==='checkbox'?el.checked:el.value;
+    };
+    ['name','check','action','selector_type','selector_value','title','message'].forEach(function(k){
+      const v=get(k); if(v!==undefined)w[k]=v;
+    });
+    ['interval','cooldown'].forEach(function(k){
+      const v=get(k); if(v!==undefined)w[k]=parseInt(v,10)||0;
+    });
+    ['enabled','notify'].forEach(function(k){
+      const v=get(k); if(v!==undefined)w[k]=v;
+    });
+  });
+}
+function patrolCollect(){
+  patrolSync();
+  return _patrolItems.map(function(w){
+    return {enabled:w.enabled!==false, name:(w.name||'').trim(), interval:parseInt(w.interval,10)||60,
+            check:w.check||'screen_off', selector_type:w.selector_type||'xpath',
+            selector_value:(w.selector_value||'').trim(), action:w.action||'none',
+            notify:w.notify!==false, title:(w.title||'').trim(), message:(w.message||'').trim(),
+            cooldown:parseInt(w.cooldown,10)||0};
+  });
+}
+// 检查项一变，条件行（选择器/包名）跟着换
+function patrolCheckChanged(sel){
+  const card=sel.closest('.patrol-card');
+  const need=(_PATROL_CHECKS.find(function(c){return c[0]===sel.value;})||[])[2]||'';
+  const row=card.querySelector('.patrol-cond');
+  row.style.display=need?'flex':'none';
+  const typeBox=row.querySelector('.patrol-seltype');
+  if(typeBox)typeBox.style.display=(need==='selector')?'block':'none';
+  const lb=row.querySelector('.patrol-vallabel');
+  if(lb)lb.textContent=(need==='package')?'前台包名':'选择器值';
+  const inp=row.querySelector('[data-pk="selector_value"]');
+  if(inp)inp.placeholder=(need==='package')?'如 com.ss.android.ugc.aweme':'如 点赞';
+}
+function patrolRender(){
+  const list=document.getElementById('patrol-list');
+  if(!list)return;
+  if(!_patrolItems.length){
+    list.innerHTML='<div class="text-muted" style="font-size:12px;padding:4px 0">（没有巡检项）</div>';
+    return;
+  }
+  list.innerHTML=_patrolItems.map(_patrolCardHtml).join('');
+}
+function _patrolCardHtml(w,i){
+  const need=(_PATROL_CHECKS.find(function(c){return c[0]===w.check;})||[])[2]||'';
+  const chkOpts=_PATROL_CHECKS.map(function(c){
+    return '<option value="'+c[0]+'"'+(w.check===c[0]?' selected':'')+'>'+c[1]+'</option>';}).join('');
+  const actOpts=_PATROL_ACTIONS.map(function(a){
+    return '<option value="'+a[0]+'"'+(w.action===a[0]?' selected':'')+'>'+a[1]+'</option>';}).join('');
+  const typeOpts=['xpath','description','text','resourceId','descriptionContains','className']
+    .map(function(t){return '<option value="'+t+'"'+(w.selector_type===t?' selected':'')+'>'+t+'</option>';}).join('');
+  return '<div class="patrol-card">'
+   +'<div class="patrol-row">'
+     +'<label class="form-check"><input type="checkbox" data-pk="enabled" '+(w.enabled!==false?'checked':'')+'><span>启用</span></label>'
+     +'<input class="form-control" data-pk="name" style="flex:1" placeholder="巡检名，如 熄屏点亮" value="'+esc(w.name||'')+'">'
+     +'<button class="btn btn-xs btn-danger" onclick="patrolRemove('+i+')">删除</button>'
+   +'</div>'
+   +'<div class="patrol-row">'
+     +'<div class="pg"><label>每隔(秒)</label><input type="number" class="form-control" data-pk="interval" value="'+(w.interval||60)+'" min="5"></div>'
+     +'<div class="pg"><label>检查</label><select class="form-control" data-pk="check" onchange="patrolCheckChanged(this)">'+chkOpts+'</select></div>'
+     +'<div class="pg"><label>命中后动作</label><select class="form-control" data-pk="action">'+actOpts+'</select></div>'
+     +'<div class="pg"><label>冷却(秒)</label><input type="number" class="form-control" data-pk="cooldown" value="'+(w.cooldown!=null?w.cooldown:300)+'" min="0"></div>'
+   +'</div>'
+   +'<div class="patrol-row patrol-cond" style="display:'+(need?'flex':'none')+'">'
+     +'<div class="pg patrol-seltype" style="display:'+(need==='selector'?'block':'none')+'"><label>选择器类型</label>'
+     +'<select class="form-control" data-pk="selector_type">'+typeOpts+'</select></div>'
+     +'<div class="pg" style="flex:1"><label class="patrol-vallabel">'+(need==='package'?'前台包名':'选择器值')+'</label>'
+     +'<input class="form-control" data-pk="selector_value" value="'+esc(w.selector_value||'')+'" placeholder="'
+     +(need==='package'?'如 com.ss.android.ugc.aweme':'如 点赞')+'"></div>'
+   +'</div>'
+   +'<div class="patrol-row">'
+     +'<label class="form-check"><input type="checkbox" data-pk="notify" '+(w.notify!==false?'checked':'')+'><span>命中发通知</span></label>'
+     +'<div class="pg" style="flex:1"><label>标题</label><input class="form-control" data-pk="title" value="'+esc(w.title||'')+'" placeholder="{device} 熄屏了"></div>'
+     +'<div class="pg" style="flex:2"><label>内容</label><input class="form-control" data-pk="message" value="'+esc(w.message||'')+'" placeholder="任务 {job} 在 {time} 发现 {screen}，已处理"></div>'
+   +'</div>'
+   +'<div class="help">占位符：{device} 设备名、{serial} 地址、{job} 任务名、{time} 时间、{app} 当前前台包名、'
+   +'{screen} 亮屏/熄屏（后两个要查设备，不用就别写）。冷却期内重复命中不会重复动作/通知，防刷屏</div>'
+   +'</div>';
+}
+
+// openTaskModal(jobId, prefill)
+//   jobId   —— 传 id = 编辑已有任务
+//   prefill —— AI 建任务的草稿：{task, notes, warnings}（服务端已校验，这里只预填给人核对）
+function openTaskModal(jobId, prefill){
   const job=jobId?(_jobsData||[]).find(j=>j.id===jobId):null;
   const isEdit=!!job;
-  document.getElementById('modal-title').textContent=isEdit?'编辑任务':'新建任务';
+  const pf=(prefill&&prefill.task)?prefill:null;
+  document.getElementById('modal-title').textContent=
+    isEdit?'编辑任务':(pf?'AI 生成任务（请核对后保存）':'新建任务');
   // 任务编辑器含步骤编辑，加宽弹窗；关闭时在 closeModal 移除
   document.getElementById('modal-box').classList.add('wide-modal');
 
-  const j=job||{name:'',task_type:'generic_steps',enabled:true,target:{mode:'all'},params:{},schedule:{mode:'once'},retry:{max_attempts:1,delay:60}};
+  const j=_normalizeTaskEnv(job||(pf&&pf.task)||{});
   const tt=_taskTypes.map(t=>'<option value="'+t.task_type+'"'+(t.task_type===j.task_type?' selected':'')+'>'+esc(t.name)+'</option>').join('');
   const gl=_groupsList.map(g=>'<option value="'+g.name+'"'+(g.name===j.target.group_name?' selected':'')+'>'+esc(g.name)+'</option>').join('');
   const dl=_devicesList.map(x=>'<option value="'+esc(x.serial)+'"'+(x.serial===j.target.serial?' selected':'')+'>'
@@ -158,10 +301,36 @@ function openTaskModal(jobId){
         '<div class="se-lib" id="se-lib"><div class="lib-title">操作库</div></div>'+
         '<div class="se-canvas" id="se-canvas"></div>'+
       '</div>'+
+    '</div>'+
+    // 公共巡检：任务级配置，**不在步骤画布里**（穿插执行，见 core/patrol.py）
+    '<div class="patrol-box" id="patrol-box">'+
+      '<div class="patrol-head">'+
+        '<span>公共巡检<span class="hint" style="margin-left:8px">可选：任务运行期间按间隔穿插检查，命中就动作 + 通知</span></span>'+
+        '<button class="btn btn-xs" onclick="patrolAdd()">＋ 添加巡检</button>'+
+      '</div>'+
+      '<div id="patrol-list"></div>'+
+      '<div class="help">和步骤的区别：步骤是"按顺序做完这一段"，巡检是"全程都要盯着的条件"（比如熄屏就点亮、掉到桌面就通知）。'+
+      '检查穿插在步骤之间执行，不额外抢设备；某一步耗时很长时，巡检最多晚那一步的时间。</div>'+
     '</div>';
 
-  // 初始化步骤编辑器（generic_steps 时显示，其他隐藏）；jobId 作为草稿 key
+  // AI 草稿的提醒/复核项：贴在步骤编辑器上方，别让人漏看
-  _stepEditor.init(j.params&&j.params.steps?j.params.steps:[],j.params&&j.params.max_duration?j.params.max_duration:0,jobId||'');
+  if(pf&&((pf.notes&&pf.notes.length)||(pf.warnings&&pf.warnings.length))){
+    const se=document.getElementById('step-editor');
+    if(se) se.insertAdjacentHTML('beforebegin',
+      '<div class="tg-note" style="margin-bottom:10px"><b>AI 探索说明（请核对）</b>'
+      +(pf.notes||[]).map(n=>'<div>· '+esc(n)+'</div>').join('')
+      +((pf.warnings||[]).length
+        ? '<div style="margin-top:6px;color:#b45309"><b>校验提醒</b>'
+          +pf.warnings.map(w=>'<div>· '+esc(w)+'</div>').join('')+'</div>'
+        : '')
+      +'</div>');
+  }
+  // 初始化步骤编辑器（generic_steps 时显示，其他隐藏）；jobId 作为草稿 key。
+  // AI 草稿用一个唯一 key：既避开 localStorage 里"新建任务"的旧草稿覆盖预填内容，
+  // 又保留自动存草稿（保存成功时 saveTask 会 clearDraft 清掉它）。
+  const draftKey=jobId||(pf?('ai:'+Date.now()):'');
+  _stepEditor.init(j.params&&j.params.steps?j.params.steps:[],j.params&&j.params.max_duration?j.params.max_duration:0,draftKey);
+  patrolInit(j.params&&j.params.watchers);
 
   document.getElementById('modal-footer').innerHTML=
     '<button class="btn" onclick="closeModal()">取消</button>'+
@@ -249,6 +418,8 @@ function onTaskTypeChange(){
   const isGeneric=tt==='generic_steps';
   document.getElementById('step-editor').classList.toggle('show',isGeneric);
   document.getElementById('f-params_wrap').style.display=isGeneric?'none':'block';
+  const pb=document.getElementById('patrol-box');
+  if(pb)pb.style.display=isGeneric?'block':'none';   // 巡检只对通用步骤任务有意义
 }
 
 // ================== 自定义动作管理 ==================
@@ -332,3 +503,103 @@ function closeActionModal(){
   document.getElementById('action-modal-overlay').classList.remove('show');
 }
 
+
+// ================== 动作配置：步骤默认值 ==================
+// 存 app_meta.step_defaults（见 core/step_defaults.py）；只影响**之后新建**的步骤。
+const _CFG_LABELS = {
+  swipe: '滑动', click: '点击元素', long_click: '长按元素', wait: '等待',
+  key_event: '按键', input_text: '输入文字',
+};
+const _CFG_FIELD_LABELS = {
+  direction: '方向', duration_min: '最短时长(秒)', duration_max: '最长时长(秒)',
+  distance_ratio: '幅度(屏占比)', jitter: '抖动幅度', humanize: '拟人轨迹',
+  wait_timeout: '等待超时(秒)', duration: '长按时长(秒)', min: '最短(秒)',
+  max: '最长(秒)', key: '按键', mode: '输入模式', texts: '候选文案(每行一条)',
+  fixed_text: '固定文字', clear_first: '输入前清空',
+};
+const _CFG_DIR_LABELS = {up:'上滑', down:'下滑', left:'左滑', right:'右滑'};
+let _cfgPayload = null;
+
+// 取一次步骤默认值缓存在 _stepDefaults（editor.js 的 _makeStep 用它预填新步骤）
+async function loadStepDefaults(force) {
+  if (_stepDefaults && !force) return _stepDefaults;
+  const r = await apiGet('/api/step_defaults');
+  _stepDefaults = (r && r.ok) ? (r.defaults || {}) : {};
+  return _stepDefaults;
+}
+
+async function loadActionConfig(force) {
+  const box = document.getElementById('cfg-forms');
+  if (!box) return;
+  if (_cfgPayload && !force) { renderStepDefaults(); return; }
+  box.innerHTML = '<div class="text-muted" style="padding:10px">加载中…</div>';
+  const r = await apiGet('/api/step_defaults');
+  if (!r || !r.ok) { box.innerHTML = '<div class="text-muted" style="padding:10px">加载失败</div>'; return; }
+  _cfgPayload = r;
+  _stepDefaults = r.defaults || {};      // 编辑器新建步骤时预填用
+  renderStepDefaults();
+}
+
+function renderStepDefaults() {
+  const box = document.getElementById('cfg-forms');
+  if (!box || !_cfgPayload) return;
+  const d = _cfgPayload.defaults || {}, kinds = _cfgPayload.kinds || {}, spec = _cfgPayload.spec || {};
+  box.innerHTML = Object.keys(d).map(function (st) {
+    const fields = Object.keys(kinds[st] || {}).map(function (k) {
+      const kind = kinds[st][k], v = d[st][k], rule = spec[st] ? spec[st][k] : null;
+      let inp;
+      if (kind === 'bool') {
+        inp = '<label class="form-check"><input type="checkbox" data-st="' + st + '" data-k="' + k + '"' +
+              (v ? ' checked' : '') + '><span>' + (_CFG_FIELD_LABELS[k] || k) + '</span></label>';
+        return inp;
+      }
+      if (kind === 'choice') {
+        inp = '<select class="form-control" data-st="' + st + '" data-k="' + k + '">' +
+              (rule || []).map(function (o) {
+                const lab = _CFG_DIR_LABELS[o] || (o === 'random' ? '随机' : o === 'fixed' ? '指定' : o);
+                return '<option value="' + esc(o) + '"' + (v === o ? ' selected' : '') + '>' + esc(lab) + '</option>';
+              }).join('') + '</select>';
+      } else if (kind === 'num') {
+        inp = '<input type="number" class="form-control" data-st="' + st + '" data-k="' + k + '" value="' + esc(v) +
+              '" step="0.05" min="' + (rule ? rule[0] : '') + '" max="' + (rule ? rule[1] : '') + '">';
+      } else if (k === 'texts') {
+        inp = '<textarea class="form-control" rows="3" data-st="' + st + '" data-k="' + k + '">' + esc(v) + '</textarea>';
+      } else {
+        inp = '<input type="text" class="form-control" data-st="' + st + '" data-k="' + k + '" value="' + esc(v) + '">';
+      }
+      return '<div class="pg"><label>' + (_CFG_FIELD_LABELS[k] || k) + '</label>' + inp + '</div>';
+    }).join('');
+    return '<div class="cfg-card"><h4>' + (_CFG_LABELS[st] || st) + ' <span class="text-muted" style="font-weight:400">' + st + '</span></h4>' +
+           '<div class="cfg-row">' + fields + '</div></div>';
+  }).join('');
+  document.getElementById('cfg-hint').textContent = '';
+}
+
+function collectStepDefaults() {
+  const out = {};
+  document.querySelectorAll('#cfg-forms [data-st]').forEach(function (el) {
+    const st = el.dataset.st, k = el.dataset.k;
+    out[st] = out[st] || {};
+    if (el.type === 'checkbox') out[st][k] = el.checked;
+    else if (el.type === 'number') out[st][k] = parseFloat(el.value);
+    else out[st][k] = el.value;
+  });
+  return out;
+}
+
+async function saveStepDefaults() {
+  const r = await apiPost('/api/step_defaults', { defaults: collectStepDefaults() });
+  if (!r || !r.ok) { showToast((r && r.error) || '保存失败', 'error'); return; }
+  _cfgPayload = r;
+  _stepDefaults = r.defaults || {};
+  showToast('默认值已保存（只影响之后新建的步骤）', 'success');
+  document.getElementById('cfg-hint').textContent = '已保存 ' + new Date().toLocaleTimeString();
+  renderStepDefaults();
+}
+
+function resetStepDefaults() {
+  if (!_cfgPayload) return;
+  if (!confirm('恢复成出厂默认？（只影响这张表单，点「保存默认值」才真正生效）')) return;
+  _cfgPayload.defaults = JSON.parse(JSON.stringify(_cfgPayload.factory || {}));
+  renderStepDefaults();
+}

static/admin/tools.js

@@ -35,7 +35,7 @@ async function loadToolsDevices(force){
     const stCls = d.state==='device' ? 'label-success' : 'label-warning';
     return '<label data-serial="'+esc(d.serial)+'">'
       +'<input type="checkbox" value="'+esc(d.serial)+'"'+( _clipSelected.has(d.serial)?' checked':'')+' onchange="toggleClipDevice(this)">'
-      +'<span style="font-family:monospace;flex:1;overflow:hidden;text-overflow:ellipsis">'+esc(d.serial)+'</span>'
+      +'<span style="font-family:monospace;flex:1;overflow:hidden;text-overflow:ellipsis">'+esc(devText(d.name,d.serial))+'</span>'
       +'<span class="label '+stCls+'">'+st+'</span></label>';
   }).join('');
   status.textContent = '共 '+_clipDevices.length+' 台设备';
@@ -252,12 +252,14 @@ async function queryAppVers(){
   }
 }
 function renderAppVerRow(x){
-  if(x.error)return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+  // 设备列显示「名称 · 地址」（名称来自设备池；没名字就只显示地址）
+  const dev='<td style="font-family:monospace">'+esc(devText(x.name,x.serial))+'</td>';
+  if(x.error)return '<tr>'+dev+
     '<td><span class="label label-warning">查询失败</span></td><td colspan="2">'+esc(x.error)+'</td></tr>';
-  if(x.installed)return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+  if(x.installed)return '<tr>'+dev+
     '<td><span class="label label-success">已安装</span></td>'+
     '<td>'+esc(x.version_name||'')+'</td><td style="font-family:monospace">'+esc(x.version_code||'')+'</td></tr>';
-  return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+  return '<tr>'+dev+
     '<td><span class="label label-default">未安装</span></td><td>-</td><td>-</td></tr>';
 }
 
@@ -496,6 +498,7 @@ async function loadDevPool(){
       '<td style="color:var(--text-light)">'+esc(d.created_at||'')+'</td>'+
       '<td style="white-space:nowrap">'+
         '<button class="btn btn-xs" onclick="renamePoolDev(\''+esc(d.serial)+'\')">改名</button> '+
+        '<button class="btn btn-xs" title="生成配置二维码：设备端 Agent 扫一下即配好（平台地址/令牌/指纹）" onclick="showDevQrcode(\''+esc(d.serial)+'\')">二维码</button> '+
         (d.online ? '' :
           '<button class="btn btn-xs" title="设备换了 IP、旧地址连不上时：把这条记录迁到新地址（名称与分组/任务引用自动保留）" onclick="relocatePoolDev(\''+esc(d.serial)+'\')">换地址</button> ') +
         '<button class="btn btn-xs" onclick="togglePoolDev(\''+esc(d.serial)+'\','+(!d.enabled)+')">'+(d.enabled?'停用':'启用')+'</button> '+
@@ -570,3 +573,37 @@ async function refreshPoolModels(){
   if(r.ok){showToast(r.msg,'success');setTimeout(loadDevPool,12000);}
   else showToast(r.error,'error');
 }
+
+// ================== 设备配置二维码（设备端 Agent 扫码即配好） ==================
+// 二维码内容：平台地址 + 设备令牌 + 这台设备的指纹（JSON）。
+// 手机上的 Agent 扫一下 → 保存这三项 → 不用在手机上打字、也不用连 adb。
+async function showDevQrcode(serial){
+  document.getElementById('modal-title').textContent='设备配置二维码';
+  document.getElementById('modal-body').innerHTML='<p class="text-muted">生成中...</p>';
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">关闭</button>';
+  showModal();
+  const r=await apiGet('/api/devices/qrcode?serial='+encodeURIComponent(serial));
+  const box=document.getElementById('modal-body');
+  if(!r||!r.ok){
+    box.innerHTML='<div style="background:#fdecea;border:1px solid #f5c6cb;color:#b42318;'+
+      'padding:10px 12px;border-radius:6px">'+esc((r&&r.error)||'生成失败')+'</div>';
+    return;
+  }
+  const warn=r.warn?'<div style="background:#fff3cd;border:1px solid #ffda6a;color:#7a5b00;'+
+      'padding:8px 12px;border-radius:6px;margin-bottom:10px;font-size:13px">⚠️ '+esc(r.warn)+'</div>':'';
+  box.innerHTML=
+    warn+
+    '<div style="text-align:center;padding:8px 0">'+
+      '<img src="'+r.png+'" style="width:240px;height:240px;image-rendering:pixelated;'+
+        'background:#fff;padding:8px;border:1px solid #e5e7eb;border-radius:8px" alt="配置二维码">'+
+      '<div style="margin-top:10px;font-size:15px"><strong>'+esc(r.name||'(未命名)')+
+        '</strong> <span style="font-family:monospace;color:#6b7280">'+esc(r.serial)+'</span></div>'+
+    '</div>'+
+    '<div class="help" style="margin-top:6px">在设备上打开 <strong>设备 Agent</strong> → 点「扫码配置」→ 扫这个二维码，'+
+      '平台地址、令牌、指纹一次写入，不用在手机上打字。</div>'+
+    '<details style="margin-top:8px"><summary style="cursor:pointer;color:#6b7280;font-size:12px">'+
+      '查看二维码内容（排查用）</summary>'+
+      '<div style="font-family:monospace;font-size:11px;color:#64748b;word-break:break-all;'+
+        'background:#f8fafc;padding:8px;border-radius:6px;margin-top:6px">'+esc(r.payload)+'</div></details>';
+}

tasks/base.py

@@ -49,8 +49,8 @@
                from .actions import get_action_class
                return get_action_class(action_type)
 
-           def create_worker(self, serial, params):
+           def create_worker(self, serial, params, ctx=None):
-               return MyWorker(serial, params=params)
+               return MyWorker(serial, params=params, ctx=ctx)
 
   5. 在 my_task/__init__.py 加：from . import task  （触发注册）
   6. 在 tasks/__init__.py 加：from .my_task import task  （触发注册）
@@ -85,8 +85,12 @@ class BaseTask:
     description = ""
     default_params = {}
 
-    def create_worker(self, serial, params):
+    def create_worker(self, serial, params, ctx=None):
-        """返回一个 threading.Thread（已启动或待启动），执行实际任务。"""
+        """返回一个 threading.Thread（已启动或待启动），执行实际任务。
+
+        ctx：本次运行的上下文（`run_id`/`job_id`/`job_name`/`device_name`），
+        由 TaskManager 传入，供步骤明细等结构化记录标注来源；可为 None。
+        """
         raise NotImplementedError
 
     @classmethod

tasks/generic/task.py

@@ -26,6 +26,9 @@ worker 按 steps 顺序执行，支持 loop 步骤循环、停止信号、进度
   wait_el     - 等待元素出现（条件等待，替代固定时长 wait）
   input_text  - 输入文字（随机候选/指定文字，可先清空）
   wait        - 等待时长
+  notify      - 发自定义通知（标题/正文自己写，推送 webhook）
+  stop_self   - 停止本设备的任务（其它设备不受影响）
+  gesture     - 回放录制的手势轨迹（纯录制：路径与时长照录制，见 core/gesture.py）
   loop        - 循环块（含 children 步骤列表 + max_iterations）
   group       - 动作组（含 children 步骤列表，按序执行一次，可折叠复用）
 """
@@ -35,8 +38,10 @@ import time
 
 from tasks.base import BaseTask, register_task
 from core.device_worker import BaseWorker, _update_status
-from core.u2_helper import ensure_app_running, wait_for_app_home, random_sleep
+from core.u2_helper import (ensure_app_running, wait_for_app_home, random_sleep,
+                           screen_is_on, current_package)
 from core.logger import get_logger
+from core import notifier, step_log, humanize, patrol, gesture
 
 _log = get_logger("task.generic")
 
@@ -45,6 +50,13 @@ _log = get_logger("task.generic")
 _LEGACY_IDX_XPATH = re.compile(r'^(//\*\[@[^\]]+\])\[(\d+)\](.*)$')
 
 
+# ---- 「保持亮屏」用的系统设置 ----
+# 系统息屏超时（毫秒）：保持亮屏时顶到最大，恢复时写回原值
+_SCREEN_TIMEOUT_MAX = "2147483647"
+_SCREEN_TIMEOUT_DEFAULT = "600000"        # 兜底恢复值：10 分钟（原值记不住时用）
+_SCREEN_TIMEOUT_BACKUP = {}               # serial -> 原始 screen_off_timeout
+
+
 def _norm_legacy_xpath(sel_val):
     """把历史 `//*[@attr=…][k]` 纠正为 `(//*[@attr=…])[k]`（只改整体前缀，保留后续子路径）。
 
@@ -74,10 +86,13 @@ STEP_TYPES = [
     {"type": "key_event", "label": "按键", "icon": "⌨️",
      "params": {"key": "back"}},
     {"type": "swipe", "label": "滑动", "icon": "↕",
-     "params": {"direction": "up", "duration_min": 0.25, "duration_max": 0.50}},
+     "params": {"direction": "up", "duration_min": 0.25, "duration_max": 0.50,
+                "distance_ratio": 0.6, "jitter": 0.15, "humanize": True}},
     {"type": "swipe_until", "label": "滑动直到元素", "icon": "🔍",
      "params": {"selector_type": "xpath", "selector_value": "", "direction": "up",
-                "max_swipes": 8, "click_when_found": True}},
+                "max_swipes": 8, "click_when_found": True,
+                "duration_min": 0.25, "duration_max": 0.50,
+                "distance_ratio": 0.6, "jitter": 0.15, "humanize": True}},
     {"type": "click", "label": "点击元素", "icon": "✦",
      "params": {"selector_type": "description", "selector_value": "", "wait_timeout": 2}},
     {"type": "click_xy", "label": "点击坐标", "icon": "🎯",
@@ -99,6 +114,12 @@ STEP_TYPES = [
     {"type": "if_el", "label": "条件判断", "icon": "❓",
      "params": {"selector_type": "xpath", "selector_value": "", "timeout": 3,
                 "then": [], "else": []}},
+    {"type": "notify", "label": "发通知", "icon": "🔔",
+     "params": {"title": "", "message": "", "level": "info"}},
+    {"type": "stop_self", "label": "停止本设备", "icon": "⛔",
+     "params": {"reason": ""}},
+    {"type": "gesture", "label": "录制手势", "icon": "⏺",
+     "params": {"points": [], "speed": 1.0}},
 ]
 
 
@@ -116,13 +137,29 @@ class GenericStepsWorker(BaseWorker):
     只实现 run_task，按步骤类型分发到 _exec_<type> 方法。
     """
 
-    def __init__(self, serial, params=None):
+    def __init__(self, serial, params=None, ctx=None):
-        super().__init__(serial, params)
+        super().__init__(serial, params, ctx=ctx)
         p = {**DEFAULT_PARAMS, **(self.params or {})}
         self.max_duration = int(p.get("max_duration", 0))
         self.steps = p.get("steps", [])
         self._action_counts = {}   # 步骤执行计数 {step_label: count}
         self._miss_counts = {}     # 选择器健康：selector -> 连续未命中次数
+        # 步骤路径：容器步骤（loop/group/if_el）进出时压栈，得到 "2.1.3" 这种位置，
+        # 写进「步骤明细」用来还原嵌套结构。worker 每台设备一个线程，实例级状态安全。
+        self._path = []
+        self._step_rows = 0        # 本次运行已记录的明细条数（封顶见 _record_step）
+        self._step_capped = False
+        # 公共巡检（任务级配置，独立于步骤画布；见 core/patrol.py）：
+        # _wid 内部标识，用来记"下次到点 / 上次命中"两个节奏
+        self._watchers = []
+        for i, w in enumerate(p.get("watchers") or []):
+            if not isinstance(w, dict) or not w.get("enabled", True):
+                continue
+            w = dict(w)
+            w["_wid"] = f"w{i}"
+            self._watchers.append(w)
+        self._watch_next = {}      # wid -> 下次到点（缺省 0 = 任务一开始就先查一次）
+        self._watch_last = {}      # wid -> 上次命中（冷却用）
 
     # 某 click 选择器连续未找到元素的次数达到该值，判定可能失效（App 改版）
     _MAX_CONSECUTIVE_MISS = 10
@@ -141,6 +178,10 @@ class GenericStepsWorker(BaseWorker):
             _log.error(f"[{self.serial}] 选择器连续 {n} 次未找到元素，可能已失效（App 改版？）：{sel_val}")
             _update_status(self.serial, last_warning=f"选择器连续{n}次未命中")
             self._miss_counts.pop(sel_val, None)  # 已上报，重置避免刷屏
+            # 通知：这是"任务显示成功但什么都没做"的隐蔽故障，值得人看一眼
+            # （重置计数后要再攒满 10 次才会再报，天然不刷屏）
+            notifier.notify("task.selector.invalid", serial=self.serial,
+                            selector=str(sel_val)[:200], miss_count=n)
 
     def run_task(self, d):
         """按 steps 顺序执行。loop 步骤递归执行其 children。"""
@@ -165,10 +206,17 @@ class GenericStepsWorker(BaseWorker):
         if depth > 5:
             _log.warning(f"[{self.serial}] 步骤嵌套深度超限(>5)，跳过")
             return
-        for step in steps:
+        for i, step in enumerate(steps):
             if self.stopped() or self.is_time_up():
                 return
-            self._exec_one(d, step, depth)
+            self._maybe_patrol(d)      # 穿插：每步之前看一眼有没有巡检到点了
+            # 压入本步在兄弟里的序号（1 起）：容器步骤执行 children 时会在其后
+            # 继续追加，得到 "2.1" 这样的嵌套路径
+            self._path.append(str(i + 1))
+            try:
+                self._exec_one(d, step, depth)
+            finally:
+                self._path.pop()
 
     def _exec_one(self, d, step, depth=0):
         """执行单个步骤。"""
@@ -185,19 +233,33 @@ class GenericStepsWorker(BaseWorker):
         prob = float(params.get("probability", 100))
         if prob < 100 and random.random() * 100 > prob:
             _log.info(f"[{self.serial}] 步骤 '{label}' 概率 {prob}% 未触发，跳过")
+            self._record_step(step, "skip", f"概率 {prob}% 未触发", 0)
             return
         self.set_action(f"执行: {label}")
-        _log.info(f"[{self.serial}] 步骤: {label}({stype}) params={params}")
+        if stype == "gesture":      # 点列可能有几十个点，别整段甩进日志
+            _log.info(f"[{self.serial}] 步骤: {label}({stype}) "
+                      f"{len(params.get('points') or [])} 个轨迹点")
+        else:
+            _log.info(f"[{self.serial}] 步骤: {label}({stype}) params={params}")
 
         ret = None
+        # 结果归类：异常 > 未命中（handler 返回 False）> 正常
+        # （True/None 都算正常——None 是"没有判断语义"的步骤，如点击坐标）
+        result, detail = "ok", ""
+        t0 = time.time()
         handler = getattr(self, f"_exec_{stype}", None)
         if handler:
             try:
                 ret = handler(d, params, depth)
+                if ret is False:
+                    result, detail = "miss", "未命中/超时"
             except Exception as e:
                 _log.error(f"[{self.serial}] 步骤 {label}({stype}) 异常: {e}")
+                result, detail = "error", str(e)
         else:
             _log.warning(f"[{self.serial}] 未知步骤类型: {stype}")
+            result, detail = "unknown", f"未知步骤类型: {stype}"
+        self._record_step(step, result, detail, int((time.time() - t0) * 1000))
         # 容器步骤（loop/group/if_el）不计入操作计数，避免监控显示噪音
         if stype not in ("loop", "group", "if_el"):
             self._action_counts[label] = self._action_counts.get(label, 0) + 1
@@ -208,6 +270,109 @@ class GenericStepsWorker(BaseWorker):
                           action_counts=dict(self._action_counts), elapsed=elapsed)
         return ret  # 命中结果（True/False/None），"测试此步骤"用
 
+    def _record_step(self, step, result, detail, duration_ms):
+        """把这一步写进「步骤明细」（异步落库，不阻塞任务线程）。
+
+        单次运行条数封顶：`forever` 循环任务会执行成千上万步，不封顶这张表
+        会被瞬间写爆。到顶后只补一条 cap 说明行，此后本次运行不再记录。
+        """
+        try:
+            # 只记"任务运行"里的步骤：编辑器里的「测试此步骤」也会走 _exec_one，
+            # 但没有 run_id（不归任何一次运行），记进来只是噪音
+            if not self.ctx.get("run_id") or self._step_capped:
+                return
+            params = step.get("params") or {}
+            label = step.get("label") or step.get("type", "")
+            if self._step_rows >= step_log.MAX_ROWS_PER_RUN:
+                self._step_capped = True
+                step_log.record(
+                    run_id=self.ctx.get("run_id", ""), serial=self.serial,
+                    device_name=self.ctx.get("device_name", ""),
+                    job_id=self.ctx.get("job_id", ""),
+                    job_name=self.ctx.get("job_name", ""),
+                    step_path=".".join(self._path), step_label=label,
+                    step_type=step.get("type", ""), result="cap",
+                    detail=f"本次运行明细已达上限 {step_log.MAX_ROWS_PER_RUN} 条，"
+                           f"后续步骤不再记录（保留期与上限见 core/step_log.py）")
+                return
+            self._step_rows += 1
+            step_log.record(
+                run_id=self.ctx.get("run_id", ""), serial=self.serial,
+                device_name=self.ctx.get("device_name", ""),
+                job_id=self.ctx.get("job_id", ""),
+                job_name=self.ctx.get("job_name", ""),
+                step_path=".".join(self._path), step_label=label,
+                step_type=step.get("type", ""),
+                selector=str(params.get("selector_value", "") or ""),
+                result=result, detail=detail, duration_ms=duration_ms)
+        except Exception:
+            pass          # 记录失败绝不能影响任务执行
+
+    # ================== 公共巡检（任务级，穿插执行） ==================
+    def _maybe_patrol(self, d):
+        """看一眼有没有巡检到点了；到点就跑一次检查（配置见 core/patrol.py）。
+
+        穿插式：不起线程、不抢屏幕，所以巡检精度受主流程步长影响——某一步卡
+        30 秒，巡检最多晚 30 秒（这是刻意取舍，换来的是绝不会和主流程打架）。
+        """
+        if not self._watchers or self.stopped():
+            return
+        now = time.time()
+        for w in self._watchers:
+            wid = w["_wid"]
+            if now < self._watch_next.get(wid, 0):
+                continue
+            # 先排下一次再执行：检查本身可能慢（元素检查要 dump UI 树），
+            # 否则慢检查会导致"每分钟"变成"每检查一次"
+            self._watch_next[wid] = now + max(5, int(w.get("interval") or 60))
+            try:
+                self._run_patrol(d, w, now)
+            except Exception as e:
+                _log.warning(f"[{self.serial}] 巡检[{w.get('name') or wid}]异常: {e}")
+
+    def _run_patrol(self, d, w, now):
+        """执行一次巡检：命中 → 过冷却 → 做动作 + 发通知 + 记一条明细。"""
+        wid, name = w["_wid"], (w.get("name") or patrol.check_label(w.get("check")))
+        hit, detail = patrol.evaluate(d, w)
+        if not hit:
+            return
+        # 命中后冷却：条件持续成立（比如一直熄屏）时不要每分钟都动作/发通知
+        cooldown = max(0, int(w.get("cooldown") or 0))
+        if now - self._watch_last.get(wid, 0) < cooldown:
+            _log.info(f"[{self.serial}] 巡检[{name}]命中（{detail}）但在冷却期内，不重复动作")
+            return
+        self._watch_last[wid] = now
+        # 文案在**动作之前**渲染：动作会改变设备状态（点亮后 {screen} 就成了"亮屏"），
+        # 而用户要看的是"发现时"的样子——"发现熄屏，已点亮"而不是"发现亮屏，已点亮"
+        title = self._render_vars(d, w.get("title") or "") or f"巡检命中：{name}"
+        message = self._render_vars(d, w.get("message") or "") or detail
+        done = patrol.act(d, w, self)
+        _log.info(f"[{self.serial}] 巡检[{name}]命中：{detail}"
+                  f"{(' → ' + done) if done else '（只通知）'}")
+        self.set_action(f"巡检[{name}]：{detail}{('，' + done) if done else ''}")
+        summary = f"{detail}{(' → ' + done) if done else ''}"
+        try:                                   # 明细：只记命中，不记"没事发生"
+            step_log.record(run_id=self.ctx.get("run_id", ""), serial=self.serial,
+                            device_name=self.ctx.get("device_name", ""),
+                            job_id=self.ctx.get("job_id", ""),
+                            job_name=self.ctx.get("job_name", ""),
+                            step_label=f"巡检[{name}]", step_type="patrol",
+                            result="hit", detail=summary)
+        except Exception:
+            pass
+        if w.get("notify", True):
+            notifier.notify("task.patrol.hit",
+                            patrol_name=name,
+                            check_label=patrol.check_label(w.get("check")),
+                            action_label=patrol.action_label(w.get("action")),
+                            detail=detail,
+                            job_id=self.ctx.get("job_id", ""),
+                            job_name=self.ctx.get("job_name", ""),
+                            serial=self.serial,
+                            device_name=self.ctx.get("device_name", ""),
+                            title=title, message=message,
+                            level=w.get("level", "warning"))
+
     # ================== 步骤执行器 ==================
     def _exec_screen_on(self, d, params, depth=0):
         """亮屏：息屏时唤醒并滑动解锁。任务执行前用（息屏时 u2 无法操作）。"""
@@ -228,17 +393,35 @@ class GenericStepsWorker(BaseWorker):
     def _exec_keep_screen(self, d, params, depth=0):
         """保持亮屏 / 恢复自动息屏。
 
-        长任务（养号看视频数小时）时屏幕会按系统超时自动熄灭导致任务无法执行，
+        ⚠️ 只用 `svc power stayon true` **不管用**：它管的是「**充电时**屏幕常亮」
-        用 svc power stayon 让充电时屏幕常亮；任务结束前用 mode=off 恢复自动息屏。
+        （= stay_on_while_plugged_in）。设备走 WiFi 跑任务、没插充电器时它完全不起作用
+        ——以前"保持亮屏"看着像没生效就是这个原因（2026-09-14 用户反馈）。
+
+        真正管用的是把系统**息屏超时**顶到最大（`screen_off_timeout`）：不充电也不会
+        自动黑屏。进入时记下原值，`mode=off` 写回；进程重启丢了记录就写回常规的 10 分钟。
         """
         mode = params.get("mode", "on")
         try:
             if mode == "off":
                 d.shell("svc power stayon false")
-                _log.info(f"[{self.serial}] 恢复自动息屏")
+                orig = _SCREEN_TIMEOUT_BACKUP.pop(self.serial, _SCREEN_TIMEOUT_DEFAULT)
+                d.shell(f"settings put system screen_off_timeout {orig}")
+                _log.info(f"[{self.serial}] 恢复自动息屏（超时 {orig}ms）")
             else:
-                d.shell("svc power stayon true")
+                cur = ""
-                _log.info(f"[{self.serial}] 保持亮屏（充电时屏幕常亮）")
+                try:
+                    cur = (d.shell("settings get system screen_off_timeout") or "").strip()
+                except Exception:
+                    pass
+                if self.serial not in _SCREEN_TIMEOUT_BACKUP:
+                    # 没设过时 `settings get` 会返回 "null"（走系统默认）——别把 null 写回去
+                    _SCREEN_TIMEOUT_BACKUP[self.serial] = \
+                        cur if cur.isdigit() else _SCREEN_TIMEOUT_DEFAULT
+                d.shell("svc power stayon true")          # 充电场景（顺带）
+                d.shell(f"settings put system screen_off_timeout {_SCREEN_TIMEOUT_MAX}")
+                d.shell("input keyevent 224")             # 立刻唤醒（KEYCODE_WAKEUP，单向）
+                _log.info(f"[{self.serial}] 保持亮屏（息屏超时→最大，原值 "
+                          f"{_SCREEN_TIMEOUT_BACKUP.get(self.serial)}ms）")
         except Exception as e:
             _log.warning(f"[{self.serial}] keep_screen({mode}) 异常: {e}")
 
@@ -290,13 +473,14 @@ class GenericStepsWorker(BaseWorker):
         if not sel_val:
             _log.warning("swipe_until 缺少选择器")
             return None
-        info = d.info
+        # 每次滑动都重新生成（弧线方向/幅度/时长都不一样），不用预算好的固定坐标
-        w, h = info["displayWidth"], info["displayHeight"]
+        swipe_kw = dict(
-        cx = int(w * 0.5)
+            serial=self.serial,
-        if direction == "down":
+            duration_min=float(params.get("duration_min", 0.25)),
-            sy, ey = int(h * 0.2), int(h * 0.8)
+            duration_max=float(params.get("duration_max", 0.50)),
-        else:
+            distance_ratio=float(params.get("distance_ratio", 0.6) or 0.6),
-            sy, ey = int(h * 0.8), int(h * 0.2)
+            jitter=params.get("jitter", 0.15),
+            humanize=params.get("humanize", True) is not False)
         for i in range(1, max_swipes + 1):
             if self.stopped() or self.is_time_up():
                 return None
@@ -322,8 +506,8 @@ class GenericStepsWorker(BaseWorker):
                     _log.info(f"[{self.serial}] 滑动{i}次后找到: {sel_val}")
                 self._track_selector_health(sel_val, True)
                 return True
-            d.swipe(cx, sy, cx, ey, 0.3)
+            humanize.swipe(d, direction, **swipe_kw)
-            time.sleep(0.5)
+            time.sleep(random.uniform(0.35, 0.75))   # 每次滑动后停顿也抖动一下
         self._track_selector_health(sel_val, False)
         _log.warning(f"[{self.serial}] 滑动{max_swipes}次未找到元素: {sel_val}")
         return False
@@ -401,7 +585,23 @@ class GenericStepsWorker(BaseWorker):
             _log.warning(f"[{self.serial}] if_el 缺少选择器，跳过")
             return None
         found = False
-        if sel_type == "ocr":
+        # 非元素类条件（屏幕状态/前台 App）：不参与"选择器健康"统计——它们不是选择器，
+        # 连续未命中不该被记成"选择器失效"
+        dynamic = sel_type in ("screen", "foreground")
+        detail = ""
+        if sel_type == "screen":
+            # 屏幕亮/熄：selector_value 填 on / off（也认 熄屏/灭屏 这类中文）
+            want = str(sel_val).strip().lower()
+            want_off = want in ("off", "0", "false", "no", "熄屏", "灭屏", "黑屏")
+            state = screen_is_on(d)
+            found = (state is False) if want_off else (state is True)
+            detail = (f"屏幕{'熄屏' if state is False else '亮屏' if state else '状态未知'}"
+                      f"（判断{'熄屏' if want_off else '亮屏'}）")
+        elif sel_type == "foreground":
+            cur = current_package(d)
+            found = cur == str(sel_val).strip()
+            detail = f"前台='{cur or '未知'}'（期望 {sel_val}）"
+        elif sel_type == "ocr":
             # OCR 模式：截图 → 识别文字 → 关键词匹配（UI 树里没有的文字也能找到）
             try:
                 from core.ocr import available as _ocr_available, find_on_screen
@@ -434,29 +634,102 @@ class GenericStepsWorker(BaseWorker):
             except Exception as e:
                 _log.warning(f"[{self.serial}] 条件判断异常: {e}")
                 found = False
-        self._track_selector_health(sel_val, found)
+        if dynamic:
+            _log.info(f"[{self.serial}] 条件判断 {detail} → {'命中' if found else '未命中'}")
+        else:
+            self._track_selector_health(sel_val, found)
         branch = params.get("then" if found else "else") or []
         self.set_action(f"条件{'命中' if found else '未命中'} → 执行{'找到' if found else '未找到'}分支({len(branch)}步)")
-        _log.info(f"[{self.serial}] 条件判断 {'命中' if found else '未命中'}: {sel_val}，执行{'then' if found else 'else'}分支 {len(branch)} 步")
+        _log.info(f"[{self.serial}] 条件判断 {'命中' if found else '未命中'}: {detail or sel_val}，执行{'then' if found else 'else'}分支 {len(branch)} 步")
         self._exec_steps(d, branch, depth + 1)
         return found
 
     def _exec_swipe(self, d, params, depth=0):
+        """滑动一次（默认拟人：弧线 + 抖动 + 本设备手速，见 core/humanize.py）。
+
+        老行为（正中直线、每次都一样）可以用 humanize=false 还原；
+        jitter=0 则保留轨迹但去掉随机抖动（对照排障用）。
+        """
         direction = params.get("direction", "up")
-        dur_min = float(params.get("duration_min", 0.25))
+        info = humanize.swipe(
-        dur_max = float(params.get("duration_max", 0.50))
+            d, direction, serial=self.serial,
-        dur = random.uniform(dur_min, dur_max)
+            duration_min=float(params.get("duration_min", 0.25)),
-        info = d.info
+            duration_max=float(params.get("duration_max", 0.50)),
-        w, h = info["displayWidth"], info["displayHeight"]
+            distance_ratio=float(params.get("distance_ratio", 0.6) or 0.6),
-        cx = int(w * 0.5)
+            jitter=params.get("jitter", 0.15),
-        if direction == "up":
+            humanize=params.get("humanize", True) is not False)
-            d.swipe(cx, int(h * 0.8), cx, int(h * 0.2), dur)
+        _log.info(f"[{self.serial}] 滑动 {direction} 时长{info['duration']}s "
-        elif direction == "down":
+                  f"({info['from']}→{info['to']}"
-            d.swipe(cx, int(h * 0.2), cx, int(h * 0.8), dur)
+                  f"{'，弧线' if info.get('human') else '，直线'})")
-        elif direction == "left":
+
-            d.swipe(int(w * 0.8), int(h * 0.5), int(w * 0.2), int(h * 0.5), dur)
+    def _exec_notify(self, d, params, depth=0):
-        elif direction == "right":
+        """发一条自定义通知（标题/正文由任务自己写，支持占位符）。
-            d.swipe(int(w * 0.2), int(h * 0.5), int(w * 0.8), int(h * 0.5), dur)
+
+        事件是 `task.notify.custom`：**谁能收到取决于 webhook 的事件订阅**——
+        这个步骤只负责"把消息交出去"，不关心发给谁（与平台其它通知同一套口径）。
+        """
+        title = self._render_vars(d, params.get("title") or "")
+        msg = self._render_vars(d, params.get("message") or "")
+        if not (title or msg):
+            _log.warning(f"[{self.serial}] notify 步骤既没标题也没内容，跳过")
+            return None
+        notifier.notify("task.notify.custom",
+                        job_id=self.ctx.get("job_id", ""),
+                        job_name=self.ctx.get("job_name", ""),
+                        serial=self.serial,
+                        device_name=self.ctx.get("device_name", ""),
+                        title=title or "任务通知", message=msg,
+                        level=params.get("level", "info"))
+        _log.info(f"[{self.serial}] 已发自定义通知: {title} {msg}")
+        return True
+
+    def _render_vars(self, d, text):
+        """替换通知文本里的占位符：{device} {serial} {job} {time} {app} {screen}。
+
+        `{app}` / `{screen}` 要查设备（0.3~0.7s），**只在文本里真用到时才查**，
+        否则每条通知都白付一次设备往返。
+        """
+        if not text or "{" not in text:
+            return text
+        vals = {"device": self.ctx.get("device_name") or self.serial,
+                "serial": self.serial,
+                "job": self.ctx.get("job_name", ""),
+                "time": time.strftime("%Y-%m-%d %H:%M:%S")}
+        if "{app}" in text:
+            vals["app"] = current_package(d) or "未知"
+        if "{screen}" in text:
+            st = screen_is_on(d)
+            vals["screen"] = "未知" if st is None else ("亮屏" if st else "熄屏")
+        for k, v in vals.items():
+            text = text.replace("{" + k + "}", str(v))
+        return text
+
+    def _exec_stop_self(self, d, params, depth=0):
+        """停止本设备的任务（其它设备的任务不受影响）。
+
+        实现只是置 worker 的停止位：`_exec_steps` 每步前检查 `stopped()`，所以
+        后续步骤不会再跑；TaskManager 侧把它记成"被停止"而不是失败
+        （见 `core/task_manager.py` 的 `_run_with_retry` 自停分支）。
+        """
+        reason = (params.get("reason") or "").strip()
+        _log.info(f"[{self.serial}] 任务内主动停止本设备（{reason or '未填原因'}）")
+        self.set_action(f"停止本设备任务{('：' + reason) if reason else ''}")
+        self.stop()
+        return True
+
+    def _exec_gesture(self, d, params, depth=0):
+        """回放**录制**的手势（路径与时长照录制，不做任何再加工）。
+
+        与「滑动」步骤是两套东西：滑动每次重新生成（弧线/抖动/本设备手速），
+        这里只把录下来的点列原样交给设备插值（原因见 core/gesture.py 模块头）。
+        """
+        pts = params.get("points") or []
+        if len(pts) < 2:
+            _log.warning(f"[{self.serial}] gesture 步骤没有有效轨迹（points 为空），跳过")
+            return None
+        info = gesture.replay(d, pts, speed=params.get("speed", 1.0))
+        _log.info(f"[{self.serial}] 录制回放：{info['points']} 个点 / {info['duration']}s")
+        return True
 
     def _exec_click(self, d, params, depth=0):
         sel_type = params.get("selector_type", "xpath")
@@ -531,11 +804,17 @@ class GenericStepsWorker(BaseWorker):
         max_s = float(params.get("max", 3.0))
         # 分片 sleep：每 0.5s 检查停止/超时信号，抢占任务能及时接管（纯 sleep 无法中断）
         total = random.uniform(min_s, max_s)
+        # 可选：按本设备节奏缩放（勾了"设备节奏差异"才生效，默认关——
+        # 时长被放大/缩小是业务语义，不能悄悄改）
+        total = humanize.pace(self.serial, total, enabled=params.get("vary_pace", False))
         end = time.time() + total
         while time.time() < end:
             if self.stopped() or self.is_time_up():
                 return
-            time.sleep(min(0.5, end - time.time()))
+            self._maybe_patrol(d)      # 长等待里也看一眼，别让巡检被 wait 拖住
+            # max(0, …)：巡检本身要花时间（屏幕 0.3s、前台 0.7s、元素检查更久），
+            # 扣掉这段时间后可能已经过点了，负数 sleep 会直接抛异常
+            time.sleep(max(0.0, min(0.5, end - time.time())))
 
     def _exec_loop(self, d, params, depth=0):
         children = params.get("children", [])
@@ -641,9 +920,9 @@ class GenericStepsTask(BaseTask):
     def get_action_class(cls, action_type):
         return None
 
-    def create_worker(self, serial, params):
+    def create_worker(self, serial, params, ctx=None):
         merged = {**DEFAULT_PARAMS, **(params or {})}
-        return GenericStepsWorker(serial, params=merged)
+        return GenericStepsWorker(serial, params=merged, ctx=ctx)
 
 
 def test_step(serial, step):

templates/admin/login.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>登录 · 设备自动化后台</title>
+<title>{% if db_env and not db_env.is_prod %}{{ db_env.env }}-{% endif %}登录 · 设备自动化后台</title>
 <style>
 *{box-sizing:border-box;margin:0;padding:0}
 body{font-family:-apple-system,"Segoe UI",Roboto,"PingFang SC","Microsoft YaHei",sans-serif;

templates/admin/monitor.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>设备自动化后台</title>
+<title>{% if db_env and not db_env.is_prod %}{{ db_env.env }}-{% endif %}设备自动化后台</title>
 <style>
 /* ========== 仪表控制台主题（Instrument Console） ==========
    自托管字体：Bricolage Grotesque（展示/数字）+ IBM Plex Mono（数据/串号）
@@ -46,6 +46,8 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .brand-dot{width:9px;height:9px;border-radius:50%;background:var(--primary);box-shadow:0 0 0 0 rgba(15,118,110,.6);animation:brandPulse 2.4s infinite}
 @keyframes brandPulse{0%{box-shadow:0 0 0 0 rgba(15,118,110,.45)}70%{box-shadow:0 0 0 8px rgba(15,118,110,0)}100%{box-shadow:0 0 0 0 rgba(15,118,110,0)}}
 .navbar .tabs{display:flex;gap:2px;flex:1;align-self:stretch}
+.env-badge{margin-right:18px;padding:3px 10px;border-radius:10px;font-size:11px;font-weight:700;letter-spacing:.5px;background:#2b3038;color:#9aa3af;border:1px solid #3a4048;white-space:nowrap}
+.env-badge-prod{background:#4a1519;color:#ff9b9b;border-color:#8a2b31}
 .navbar .tab{position:relative;padding:0 18px;color:#9aa3af;font-size:14px;font-weight:500;cursor:pointer;border:none;background:none;transition:color .15s;letter-spacing:.2px}
 .navbar .tab::after{content:"";position:absolute;left:14px;right:14px;bottom:0;height:2px;border-radius:2px;background:var(--primary);transform:scaleX(0);transition:transform .18s}
 .navbar .tab:hover{color:#e5e7eb}
@@ -110,7 +112,31 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .log-content .log-err{color:#f87171}
 .log-content .log-warn{color:#fbbf24}
 .log-content .log-info{color:#67e8f9}
-.log-toolbar{display:flex;gap:10px;margin-bottom:12px;align-items:center}
+.log-row{white-space:pre-wrap}
+.log-cont{color:#8a94a6;padding-left:2.2em}   /* 续行（traceback 缩进行）：淡色缩进 */
+.log-hit{background:#fbbf2433}                /* 关键字命中高亮 */
+
+/* 「公共巡检」配置块（任务编辑器里，独立于步骤画布） */
+.patrol-box{margin-top:14px;border:1px solid var(--border-strong);border-radius:10px;padding:12px}
+.patrol-head{display:flex;align-items:center;justify-content:space-between;margin-bottom:8px}
+.patrol-head>span:first-child{font-weight:600;font-size:13px}
+.patrol-card{border:1px solid var(--border);border-radius:8px;padding:10px;margin-bottom:8px;background:var(--surface-2,#fafafa)}
+.patrol-row{display:flex;gap:10px;align-items:flex-end;margin-bottom:8px;flex-wrap:wrap}
+.patrol-row:last-child{margin-bottom:0}
+.patrol-row .pg{display:flex;flex-direction:column;gap:2px;min-width:110px}
+.patrol-row .pg label{font-size:11px;color:var(--text-light)}
+.patrol-row .form-check{margin-bottom:6px;display:flex;align-items:center;gap:4px;font-size:12px}
+.patrol-cond{background:rgba(59,130,246,.05);border-radius:6px;padding:6px 8px;margin:0 -2px 8px}
+
+/* 「步骤明细」表格的结果列配色（.log-* 那套作用域在 .log-content 里，表格用这套） */
+.res-error{color:#dc2626;font-weight:600}     /* 异常 / 未知步骤类型 */
+.res-miss{color:#d97706}                      /* 未命中 / 超时 / 已达上限 */
+.res-skip{color:var(--text-light)}            /* 概率未触发 */
+.res-ok{color:#059669}
+/* 工具栏：控件较多，允许换行；控件本身不参与收缩（否则会被挤成竖排文字） */
+.log-toolbar{display:flex;flex-wrap:wrap;gap:8px 10px;margin-bottom:12px;align-items:center}
+.log-toolbar>*{flex:0 0 auto}
+.log-toolbar .hint{flex:1 1 200px;min-width:160px}
 
 /* 区块标题 */
 .section-title{font-family:var(--display);font-size:15px;font-weight:700;color:var(--text);margin:0 0 12px;padding-bottom:8px;border-bottom:2px solid var(--primary);display:inline-block;letter-spacing:.2px}
@@ -287,7 +313,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .el-device-card .edc-model{font-size:12px;color:var(--text-light);margin-top:2px}
 .el-device-card .edc-status{font-size:11px;padding:2px 10px;border-radius:99px;background:var(--success-soft);color:#15803d;flex-shrink:0;font-weight:600}
 .el-picker-main{display:flex;flex:1;overflow:hidden}
-.el-shot-wrap{flex:0 0 320px;border-right:1px solid var(--border);background:var(--ink);display:flex;flex-direction:column}
+.el-shot-wrap{flex:1 1 auto;min-width:0;border-right:1px solid var(--border);background:var(--ink);display:flex;flex-direction:column}
 .el-shot-toolbar{padding:6px 10px;background:var(--ink-2);display:flex;gap:6px;align-items:center;border-bottom:1px solid var(--ink-line)}
 .el-shot-toolbar .btn{padding:3px 10px;font-size:12px;background:#39414d;color:#e5e7eb;border:none;box-shadow:none}
 .el-shot-toolbar .btn:hover{background:#4b5563}
@@ -295,21 +321,37 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .el-shot-container{flex:1;overflow:auto;display:flex;align-items:flex-start;justify-content:center;padding:8px;position:relative}
 .el-shot-container img{max-width:100%;height:auto;border-radius:4px;display:block}
 .el-shot-container .el-shot-loading{color:#8a93a0;font-size:13px;padding:40px}
-.el-shot-overlay{position:absolute;border:1px solid rgba(103,232,249,.35);background:transparent;cursor:pointer;border-radius:2px;transition:all .1s}
+.el-shot-overlay{position:absolute;border:1px solid rgba(103,232,249,.45);background:transparent;cursor:pointer;border-radius:2px;transition:all .1s}
+.el-shot-hover{position:absolute;outline:2px solid rgba(248,113,113,.9);outline-offset:-1px;background:rgba(248,113,113,.15);pointer-events:none;border-radius:2px;z-index:5}
+.el-shot-warn{background:#fff3cd;border-bottom:1px solid #ffda6a;color:#7a5b00;font-size:12px;padding:6px 10px}
 .el-shot-overlay:hover{border-color:#67e8f9;background:rgba(103,232,249,.18)}
-.el-shot-overlay.active{border:2px solid #f87171;background:rgba(248,113,113,.22)}
+.el-shot-overlay.active{outline:2px solid #f87171;outline-offset:-1px;background:rgba(248,113,113,.22)}
-.el-list-wrap{flex:1;display:flex;flex-direction:column;overflow:hidden}
+.el-list-wrap{flex:0 0 460px;display:flex;flex-direction:column;overflow:hidden;border-left:1px solid var(--border)}
+.el-tabs{display:flex;border-bottom:1px solid var(--border);background:var(--ink-2);flex:none}
+.el-tab{padding:7px 14px;font-size:12.5px;color:var(--text-light);cursor:pointer;border:none;background:none;border-bottom:2px solid transparent}
+.el-tab.active{color:var(--primary);border-bottom-color:var(--primary);font-weight:600}
+.el-pane{flex:1;overflow:auto;display:none}
+.el-pane.active{display:block}
+.el-attr{display:flex;gap:8px;padding:5px 12px;border-bottom:1px solid var(--border);font-size:12px}
+.el-attr b{color:var(--text-light);font-weight:500;flex:0 0 96px;font-family:var(--mono)}
+.el-attr span{color:var(--text);word-break:break-all;flex:1}
+.el-color-row{display:flex;align-items:center;gap:8px;padding:6px 12px;font-size:12px;border-bottom:1px solid var(--border)}
+.el-swatch{width:22px;height:22px;border-radius:4px;border:1px solid var(--border);flex:none}
 .el-picker-search{width:100%;padding:8px 12px;border:none;border-bottom:1px solid var(--border);font-size:13px;outline:none;font-family:var(--body)}
 .el-picker-list{flex:1;overflow-y:auto}
 .el-picker-item{padding:8px 12px;border-bottom:1px solid var(--border);cursor:pointer;font-size:12px;display:flex;gap:8px;align-items:flex-start}
 .el-picker-item:hover{background:var(--primary-soft)}
-.el-picker-item.active{background:var(--primary-soft);border-left:3px solid var(--primary)}
+.el-picker-item.active{background:var(--primary-soft);box-shadow:inset 3px 0 0 var(--primary)}
 .el-picker-item:last-child{border-bottom:none}
 .el-picker-item .ep-depth{color:var(--text-light);font-family:var(--mono);flex-shrink:0;width:28px}
 .el-picker-item .ep-info{flex:1;min-width:0}
 .el-picker-item .ep-info .ep-name{color:var(--text);font-weight:500;word-break:break-all}
 .el-picker-item .ep-info .ep-attrs{color:var(--text-light);font-size:11px;margin-top:2px;word-break:break-all}
 .el-picker-item .ep-info .ep-attrs span{margin-right:8px}
+/* 文字/content-desc 是最稳的定位依据，加粗上色让它一眼可见（id 退为补充信息） */
+.el-picker-item .ep-info .ep-attrs .ep-text b{color:#0f766e;font-weight:600}
+.el-picker-item .ep-info .ep-attrs .ep-desc b{color:#7c3aed;font-weight:600}
+.el-picker-item .ep-info .ep-attrs .ep-id{font-family:var(--mono);opacity:.8}
 .el-picker-item .ep-sel{font-size:10px;color:#fff;background:var(--primary);padding:1px 7px;border-radius:99px;flex-shrink:0;font-weight:600}
 
 /* ===== AI 控制台（聊天界面，浅色内容区——DeepSeek 风格，图片文字清晰） ===== */
@@ -334,6 +376,43 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .agent-live-body .agent-empty{color:#4b5563;padding:20px;font-size:12px;line-height:1.8}
 .agent-shell{display:flex;flex-direction:column;height:calc(100vh - 150px);min-height:520px;border:1px solid #e5e7eb;border-radius:14px;overflow:hidden;background:#fff}
 .agent-shell{display:flex;flex-direction:column;height:calc(100vh - 150px);min-height:480px;border:1px solid #e5e7eb;border-radius:14px;overflow:hidden;background:#fff}
+/* AI 控制台里的子分栏占了一行，聊天区高度相应扣掉，避免整页出现滚动条 */
+#agent-sub-chat .agent-shell{height:calc(100vh - 205px)}
+
+/* ===== AI 建任务（子面板 2） ===== */
+.tg-wrap{display:flex;gap:14px;height:calc(100vh - 205px);min-height:500px}
+.tg-left{width:360px;flex:none;display:flex;flex-direction:column;gap:10px;overflow-y:auto;padding-right:2px}
+.tg-right{flex:1;min-width:0;display:flex;flex-direction:column;gap:10px}
+.tg-card{border:1px solid #e5e7eb;border-radius:12px;padding:12px;background:#fff}
+.tg-title{font-size:12.5px;font-weight:700;color:#374151;margin-bottom:8px}
+.tg-fold:hover{color:var(--primary)}
+.tg-row{display:flex;align-items:center;gap:8px;margin-top:8px}
+.tg-hint{font-size:11px;color:var(--text-light);line-height:1.5}
+.tg-actions{display:flex;gap:8px}
+.tg-actions .btn{flex:1}
+.tg-check{display:flex;align-items:flex-start;gap:6px;font-size:11.5px;color:var(--text-light);cursor:pointer;line-height:1.5}
+.tg-check input{margin-top:2px;flex:none}
+.tg-check b{color:var(--text)}
+.tg-status{font-size:11.5px;color:var(--text-light);min-height:16px;line-height:1.5}
+.tg-right-head{display:flex;justify-content:space-between;align-items:center;font-size:12.5px;font-weight:700;color:#374151}
+.tg-stream{flex:1;min-height:120px;overflow-y:auto;border:1px solid #e5e7eb;border-radius:12px;background:#fff;padding:10px;display:flex;flex-direction:column;gap:6px}
+.tg-stream .agent-toolcard{border-left:2px solid var(--teal);padding-left:8px;font-size:12px}
+.tg-stream .agent-toolcard img{max-width:180px;border-radius:6px;display:block;margin-top:6px}
+.tg-stream .agent-toolcard .dot{width:6px;height:6px;border-radius:99px;background:var(--teal);display:inline-block;margin-right:6px}
+.tg-stream .tg-err{color:#b91c1c;font-size:11.5px;margin-top:4px;font-family:var(--mono);word-break:break-all}
+.tg-draft-wrap{max-height:46%;overflow-y:auto}
+.tg-draft{border:1px solid #e5e7eb;border-radius:12px;background:#fff;padding:12px}
+.tg-draft h4{margin:0 0 8px;font-size:13px}
+.tg-step{font-family:var(--mono);font-size:11.5px;padding:3px 0;border-bottom:1px dashed #eef0f3;white-space:pre-wrap;word-break:break-all}
+.tg-step:last-child{border-bottom:none}
+.tg-step .t{color:#0f766e;font-weight:600}
+.tg-step .p{color:#b45309}
+.tg-note{background:#fffbeb;border:1px solid #fde68a;border-radius:8px;padding:8px 10px;font-size:11.5px;color:#92400e;margin-top:8px}
+.tg-warn{background:#fef2f2;border:1px solid #fecaca;border-radius:8px;padding:8px 10px;font-size:11.5px;color:#b91c1c;margin-top:8px}
+.tg-evidence{margin-top:8px;font-size:11px;color:var(--text-light)}
+.tg-evidence summary{cursor:pointer;font-weight:600}
+.tg-evidence div{padding:3px 0;border-bottom:1px dashed #eef0f3}
+.tg-btns{display:flex;gap:8px;margin-top:12px;flex-wrap:wrap}
 .agent-topbar{display:flex;align-items:center;justify-content:space-between;padding:10px 16px;border-bottom:1px solid #e5e7eb;background:#f9fafb}
 .agent-title{font-size:14px;font-weight:700;color:#111827}
 .agent-model-tag{margin-left:8px;font-size:11px;color:#0e7490;font-family:var(--mono);background:#e0f2fe;padding:2px 8px;border-radius:10px}
@@ -385,6 +464,37 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .agent-inputbar .btn-primary:hover{background:#155e75}
 .agent-inputbar .btn-primary:disabled{background:#9ca3af}
 .agent-empty{color:#6b7280;font-size:13px;text-align:center;padding:44px 0}
+
+/* ===== 动作配置：步骤默认值表单 ===== */
+.cfg-card{border:1px solid var(--border-strong);border-radius:10px;padding:12px;margin-bottom:10px}
+.cfg-card>h4{margin:0 0 8px;font-size:13px}
+.cfg-row{display:flex;gap:12px;flex-wrap:wrap}
+.cfg-row .pg{display:flex;flex-direction:column;gap:2px;min-width:120px}
+.cfg-row .pg label{font-size:11px;color:var(--text-light)}
+
+/* ===== 动作录制器 ===== */
+.rec-box{width:min(1180px,96vw);max-height:92vh;display:flex;flex-direction:column}
+.rec-head{display:flex;align-items:center;gap:10px;padding:12px 16px;border-bottom:1px solid var(--border)}
+.rec-head b{font-size:14px}
+.rec-body{display:flex;gap:14px;padding:14px 16px;overflow:hidden;flex:1;min-height:0}
+.rec-stage{flex:1;min-width:0;position:relative;background:var(--ink);border-radius:10px;
+  display:flex;align-items:center;justify-content:center;overflow:hidden}
+.rec-stage img{max-width:100%;max-height:74vh;display:block;cursor:crosshair;user-select:none}
+.rec-hint{color:#8a94a6;font-size:13px;padding:40px}
+.rec-warn{position:absolute;left:10px;top:10px;background:#fbbf24;color:#3b2f00;
+  font-size:11px;padding:2px 8px;border-radius:6px}
+.rec-line{position:absolute;border:2px dashed #f97316;border-radius:4px;pointer-events:none}
+.rec-side{width:330px;flex:0 0 330px;display:flex;flex-direction:column;gap:8px;min-height:0}
+.rec-ops{display:flex;gap:6px;flex-wrap:wrap}
+.rec-row{display:flex;gap:6px}
+.rec-list-title{font-size:12px;color:var(--text-light);margin-top:4px}
+.rec-list{flex:1;overflow-y:auto;border:1px solid var(--border);border-radius:8px;padding:6px;min-height:120px}
+.rec-item{display:flex;align-items:center;gap:6px;padding:3px 4px;border-bottom:1px dashed var(--border)}
+.rec-item:last-child{border-bottom:0}
+.rec-idx{width:18px;color:var(--text-light);font-size:11px;text-align:right}
+.rec-label{flex:1;font-size:12px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.rec-ops2{display:flex;gap:2px}
+.rec-foot{border-top:1px solid var(--border);padding-top:8px}
 </style>
 </head>
 <body>
@@ -392,6 +502,12 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 <!-- 顶部导航 -->
 <nav class="navbar">
   <div class="brand"><span class="brand-dot"></span>设备自动化后台</div>
+  {% if db_env %}
+  <span class="env-badge{% if db_env.is_prod %} env-badge-prod{% endif %}"
+        title="数据库目标：{{ db_env.target }}（{{ db_env.backend }}）">
+    {% if db_env.is_prod %}PROD · {{ db_env.target }}{% else %}{{ db_env.env|upper }}{% endif %}
+  </span>
+  {% endif %}
   <div class="tabs">
     <button class="tab active" data-tab="monitor" onclick="showTab('monitor')">监控</button>
     <button class="tab" data-tab="tasks" onclick="showTab('tasks')">任务</button>
@@ -471,6 +587,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
   <div class="sub-tabs">
     <button class="sub-tab active" data-sub="plan" onclick="showSubTab('tasks','plan')">任务计划</button>
     <button class="sub-tab" data-sub="actions" onclick="showSubTab('tasks','actions')">自定义动作</button>
+    <button class="sub-tab" data-sub="actioncfg" onclick="showSubTab('tasks','actioncfg')">动作配置</button>
   </div>
 
   <!-- 子分栏 1：任务计划 -->
@@ -503,11 +620,36 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
     </table>
     <div class="list-pager" id="pager-actions"></div>
   </div>
+
+  <!-- 子分栏 3：动作配置（步骤默认值 + 录制动作） -->
+  <div class="sub-panel" id="tasks-sub-actioncfg">
+    <div class="toolbar">
+      <button class="btn btn-primary" onclick="saveStepDefaults()" data-perm="tasks">保存默认值</button>
+      <button class="btn" onclick="resetStepDefaults()">恢复出厂</button>
+      <button class="btn" onclick="openRecorder({mode:'action'})" data-perm="devices">● 录制动作</button>
+      <button class="btn" onclick="loadActionConfig()">刷新</button>
+      <span class="hint" id="cfg-hint"></span>
+    </div>
+    <div class="help">
+      <b>步骤默认值</b>：新建步骤时预填这套参数（<b>只影响之后新建的步骤</b>，已有步骤不动；
+      单步想改就打开那个任务改那一步）。<br>
+      <b>录制动作</b>：在设备画面上点/划/按键，自动翻译成步骤 —— 既能存成可复用的「自定义动作」，
+      也能只取一个手势回填到滑动步骤上（步骤编辑器里滑动那一步有「录制手势」按钮）。
+    </div>
+    <div id="cfg-forms"><div class="text-muted" style="padding:10px">加载中…</div></div>
+  </div>
 </div>
 
 <!-- ========== Tab 3: 分组 ========== -->
 <!-- ========== Tab: AI 控制台（DeepSeek 风格聊天 + 实时 MCP 步骤） ========== -->
 <div id="tab-agent" class="tab-panel">
+  <div class="sub-tabs">
+    <button class="sub-tab active" data-sub="chat" onclick="showSubTab('agent','chat')">💬 聊天</button>
+    <button class="sub-tab" data-sub="taskgen" onclick="showSubTab('agent','taskgen')">🧭 AI 建任务</button>
+  </div>
+
+  <!-- ===== 子面板 1：聊天（原有 AI 控制台，原样不动） ===== -->
+  <div class="sub-panel active" id="agent-sub-chat">
   <div class="agent-shell">
     <div class="agent-topbar">
       <div class="agent-title">🤖 AI 控制台<span id="agent-model-tag" class="agent-model-tag"></span><span id="agent-token-total" class="agent-token-total" title=""></span></div>
@@ -556,6 +698,97 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
       </div>
     </div>
   </div>
+  </div><!-- /agent-sub-chat -->
+
+  <!-- ===== 子面板 2：AI 建任务 =====
+       AI 自己在真机上探索（看屏/读元素树/点按验证），把路径写成**任务步骤**，
+       经服务端校验后交人工确认（打开步骤编辑器 → 保存才入库）。
+       见 doc/AI_TASK_GEN.md -->
+  <div class="sub-panel" id="agent-sub-taskgen">
+    <div class="tg-wrap">
+      <div class="tg-left">
+        <div class="tg-card">
+          <div class="tg-title">1️⃣ 说清楚要做什么</div>
+          <textarea id="tg-prompt" class="form-control" rows="4"
+                    placeholder="例如：建一个跑 2 小时的任务，自动刷抖音、随机点赞；拿不准的先别真发"></textarea>
+          <div class="tg-row">
+            <button class="btn btn-xs" onclick="tgExample()">用个例子</button>
+            <span class="tg-hint">AI 会自己在设备上探索，把走通的路径写成任务步骤</span>
+          </div>
+        </div>
+
+        <div class="tg-card">
+          <div class="tg-title">2️⃣ 选一台空闲设备</div>
+          <select id="tg-serial" class="form-control">
+            <option value="">加载设备…</option>
+          </select>
+          <div class="tg-hint" id="tg-serial-hint">有任务在跑的设备不可选（AI 不与任务抢设备）</div>
+        </div>
+
+        <div class="tg-card">
+          <div class="tg-title tg-fold" onclick="tgToggleAdv()">3️⃣ 任务设置（可选，留空由 AI 判断）
+            <span style="float:right" id="tg-adv-arrow">▸</span></div>
+          <div id="tg-adv" style="display:none">
+            <div class="form-group"><label>任务名</label>
+              <input id="tg-name" class="form-control" placeholder="留空=AI 自动起名"></div>
+            <div class="form-group"><label>目标设备</label>
+              <select id="tg-target" class="form-control" onchange="tgToggleTarget()">
+                <option value="">跟随探索设备</option>
+                <option value="all">全部空闲设备</option>
+                <option value="group">按分组</option>
+                <option value="serial">指定设备</option>
+              </select>
+            </div>
+            <div class="form-group" id="tg-group-wrap" style="display:none">
+              <label>分组</label><select id="tg-group" class="form-control"></select>
+            </div>
+            <div class="form-group"><label>调度</label>
+              <select id="tg-sched-mode" class="form-control" onchange="tgToggleSched()">
+                <option value="">跟随 AI 判断</option>
+                <option value="once">手动（不自动启动）</option>
+                <option value="daily">每天定时</option>
+              </select>
+            </div>
+            <div class="form-row" id="tg-sched-wrap" style="display:none">
+              <div class="form-group"><label>启动</label>
+                <input type="time" id="tg-sched-start" class="form-control" value="20:00"></div>
+              <div class="form-group"><label>停止（可留空）</label>
+                <input type="time" id="tg-sched-stop" class="form-control"></div>
+            </div>
+            <div class="form-group"><label>运行时长上限（秒）</label>
+              <input id="tg-maxdur" type="number" class="form-control"
+                     placeholder="如 7200 = 2 小时；0/留空 = 不限"></div>
+          </div>
+        </div>
+
+        <div class="tg-actions">
+          <button class="btn btn-primary" id="tg-start" onclick="startExplore()">🚀 开始探索</button>
+          <button class="btn btn-danger" id="tg-stop" style="display:none" onclick="stopExplore()">■ 停止</button>
+        </div>
+        <label class="tg-check" title="勾上后：探索出草稿就直接建成任务（不再等你点确认）。草稿入库前仍会再校验一次；任务建好后可在任务页编辑/停用">
+          <input type="checkbox" id="tg-auto-create">
+          <span>探索完<b>直接创建任务</b>（跳过人工核对）</span>
+        </label>
+        <div class="tg-status" id="tg-status"></div>
+
+        <div class="tg-card" id="tg-live-card" style="display:none">
+          <div class="tg-title">📺 跟随画面 <span class="tg-hint" id="tg-live-serial"></span></div>
+          <img id="tg-live-img" alt="" style="width:100%;border-radius:8px;display:none">
+        </div>
+      </div>
+
+      <div class="tg-right">
+        <div class="tg-right-head">
+          <span>探索回放</span>
+          <span class="tg-hint" id="tg-token"></span>
+        </div>
+        <div class="tg-stream" id="tg-stream">
+          <div class="agent-empty">AI 在设备上的每一步（看屏 / 读元素树 / 点按验证）会实时显示在这里。</div>
+        </div>
+        <div class="tg-draft-wrap" id="tg-draft"></div>
+      </div>
+    </div>
+  </div><!-- /agent-sub-taskgen -->
 </div>
 
 <!-- ========== 配置模态框 ========== -->
@@ -619,25 +852,103 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 <!-- ========== Tab 4: 日志 ========== -->
 <div id="tab-logs" class="tab-panel">
   <div class="page-title">日志查看</div>
-  <div class="page-sub">查看系统各模块运行日志</div>
+  <div class="page-sub">原始文本日志 + 任务步骤明细（结构化，可按设备/任务/时间过滤）</div>
+
+  <div class="sub-tabs">
+    <button class="sub-tab active" data-sub="files" onclick="showSubTab('logs','files')">文件日志</button>
+    <button class="sub-tab" data-sub="steps" onclick="showSubTab('logs','steps')">步骤明细</button>
+  </div>
+
+  <!-- 子分栏 1：文件日志 -->
+  <div class="sub-panel active" id="logs-sub-files">
   <div class="log-toolbar">
-    <select id="log-file" class="form-control" style="width:auto" onchange="loadLogs()">
+    <!-- 文件下拉由 /api/logs 返回的清单动态渲染（含 .1/.2 滚动历史与 notify.log） -->
-      <option value="core.log">核心日志 (core.log)</option>
+    <select id="log-file" class="form-control" style="width:auto" onchange="loadLogs()"></select>
-      <option value="task.log">任务日志 (task.log)</option>
+    <input id="log-q" class="form-control" style="width:190px" placeholder="关键字（设备号/包名/报错…）"
-      <option value="web.log">Web日志 (web.log)</option>
+           onkeydown="if(event.key==='Enter')loadLogs()">
-      <option value="action.log">操作日志 (action.log)</option>
+    <select id="log-level" class="form-control" style="width:auto" onchange="loadLogs()">
+      <option value="">全部级别</option>
+      <option value="ERROR">仅 ERROR</option>
+      <option value="WARNING">WARNING 及以上</option>
+      <option value="INFO">INFO 及以上</option>
     </select>
+    <input id="log-since" type="datetime-local" class="form-control" style="width:auto"
+           title="起始时间" onchange="loadLogs()">
+    <span class="text-muted">~</span>
+    <input id="log-until" type="datetime-local" class="form-control" style="width:auto"
+           title="结束时间" onchange="loadLogs()">
     <select id="log-lines" class="form-control" style="width:auto" onchange="loadLogs()">
       <option value="100">最近 100 行</option>
       <option value="300" selected>最近 300 行</option>
       <option value="500">最近 500 行</option>
       <option value="1000">最近 1000 行</option>
+      <option value="5000">最近 5000 行</option>
     </select>
     <label class="form-check"><input type="checkbox" id="log-auto" checked onchange="toggleLogAuto()"> 自动刷新</label>
     <button class="btn" onclick="loadLogs()">刷新</button>
+    <button class="btn" onclick="downloadLogs()" title="下载当前筛选结果（无筛选即整个文件）">下载</button>
+    <button class="btn" onclick="resetLogFilters()">重置</button>
     <span class="hint" id="log-hint"></span>
   </div>
   <div id="log-content" class="log-content"></div>
+  </div><!-- /logs-sub-files -->
+
+  <!-- 子分栏 2：步骤明细（task_step_log 表，结构化，可按设备/任务/时间/结果过滤） -->
+  <div class="sub-panel" id="logs-sub-steps">
+    <div class="log-toolbar">
+      <select id="sl-device" class="form-control" style="width:auto" onchange="loadStepLogs(true)"></select>
+      <select id="sl-job" class="form-control" style="width:auto" onchange="loadStepLogs(true)"></select>
+      <select id="sl-result" class="form-control" style="width:auto" onchange="loadStepLogs(true)">
+        <option value="">全部结果</option>
+        <option value="error">异常 error</option>
+        <option value="miss">未命中 miss</option>
+        <option value="unknown">未知类型 unknown</option>
+        <option value="skip">概率跳过 skip</option>
+        <option value="ok">正常 ok</option>
+        <option value="cap">已截断 cap</option>
+      </select>
+      <input id="sl-q" class="form-control" style="width:170px" placeholder="关键字（步骤名/选择器/详情）"
+             onkeydown="if(event.key==='Enter')loadStepLogs(true)">
+      <input id="sl-since" type="datetime-local" class="form-control" style="width:auto" onchange="loadStepLogs(true)">
+      <span class="text-muted">~</span>
+      <input id="sl-until" type="datetime-local" class="form-control" style="width:auto" onchange="loadStepLogs(true)">
+      <select id="sl-limit" class="form-control" style="width:auto" onchange="loadStepLogs(true)">
+        <option value="100">每页 100</option>
+        <option value="200" selected>每页 200</option>
+        <option value="500">每页 500</option>
+      </select>
+      <button class="btn" onclick="loadStepLogs(true)">刷新</button>
+      <button class="btn" onclick="downloadStepLogs()" title="导出当前筛选结果（CSV）">导出 CSV</button>
+      <button class="btn" onclick="resetStepFilters()">重置</button>
+      <span class="hint" id="sl-hint"></span>
+    </div>
+    <div class="hint" id="sl-note"></div>
+
+    <details id="sl-runs-box" style="margin:10px 0">
+      <summary style="cursor:pointer;font-size:13px" id="sl-runs-summary">最近运行概览</summary>
+      <table class="table" style="margin-top:8px">
+        <thead><tr>
+          <th style="width:150px">开始</th><th style="width:110px">设备</th><th>任务</th>
+          <th style="width:70px">步骤数</th><th style="width:80px">失败</th><th style="width:70px"></th>
+        </tr></thead>
+        <tbody id="sl-runs-body"></tbody>
+      </table>
+    </details>
+
+    <table class="table">
+      <thead><tr>
+        <th style="width:145px">时间</th><th style="width:105px">设备</th><th style="width:150px">任务</th>
+        <th style="width:60px">步骤</th><th>标签</th><th style="width:95px">类型</th>
+        <th style="width:75px">结果</th><th style="width:65px">耗时</th><th>详情</th>
+      </tr></thead>
+      <tbody id="sl-body"></tbody>
+    </table>
+    <div class="toolbar" style="margin-top:10px">
+      <button class="btn" id="sl-prev" onclick="stepLogPage(-1)">上一页</button>
+      <span class="hint" id="sl-page"></span>
+      <button class="btn" id="sl-next" onclick="stepLogPage(1)">下一页</button>
+    </div>
+  </div><!-- /logs-sub-steps -->
 </div>
 
 <!-- ========== Tab 5: 用户 ========== -->
@@ -780,6 +1091,34 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
       <tbody id="tb-apks"></tbody>
     </table>
     <div class="list-pager" id="pager-apks"></div>
+
+    <!-- 设备端应用商店：设备上的 Agent 自己拉清单/下载/安装（绕开 MIUI 的 USB 安装拦截） -->
+    <div class="section-title" style="margin-top:16px">📱 设备端应用商店（Agent 直连安装）</div>
+    <div class="help">
+      设备上装的 <b>Agent</b> 自己来拉这份应用清单 → 在手机上选一个 → 自己下载 → 自己调系统安装器安装。
+      因为安装由设备上的 App 发起，走的是<b>普通应用安装流程</b>，
+      <b>不会触发 MIUI 针对 adb 安装的「USB 安装」拦截</b>（那正是 <code>adb install</code> 报 USER_RESTRICTED 的原因）。
+      适合"人就在机器旁边"的场景（本来就要点一次安装确认）。平台批量推送仍用上面的「安装」按钮。
+      <br><span class="text-muted">接口契约见 <code>doc/DEVICE_AGENT.md</code>；令牌属于凭据，别外传。</span>
+    </div>
+    <div class="toolbar" style="gap:10px;flex-wrap:wrap">
+      <label style="display:inline-flex;align-items:center;gap:4px;margin:0">
+        <input type="checkbox" id="store-enabled" onchange="toggleAgentStore(this.checked)"> 启用设备端商店
+      </label>
+      <input class="form-control" id="store-url" readonly style="width:290px;font-family:monospace" title="Agent 里要填的平台地址">
+      <input class="form-control" id="store-token" readonly style="width:300px;font-family:monospace" title="Agent 里要填的设备令牌">
+      <button class="btn" onclick="copyStoreToken()">复制令牌</button>
+      <button class="btn" onclick="regenStoreToken()">重置令牌</button>
+      <button class="btn" onclick="loadAgentStore()">刷新记录</button>
+      <span class="text-muted" id="store-status"></span>
+    </div>
+    <table class="table">
+      <thead><tr>
+        <th style="width:150px">时间</th><th style="width:90px">设备</th>
+        <th style="width:200px">应用</th><th style="width:110px">动作</th><th>说明</th>
+      </tr></thead>
+      <tbody id="tb-store-logs"><tr><td colspan="5" class="empty">暂无记录（设备还没从商店装过东西）</td></tr></tbody>
+    </table>
   </div>
 
   <!-- 子分栏 5：应用版本管理 -->
@@ -925,15 +1264,17 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
   <div class="sub-tabs">
     <button class="sub-tab active" data-sub="backup" onclick="showSubTab('system','backup')">数据备份</button>
     <button class="sub-tab" data-sub="restore" onclick="showSubTab('system','restore')">导入恢复</button>
+    <button class="sub-tab" data-sub="notify" onclick="showSubTab('system','notify')">通知 / Webhook</button>
   </div>
 
   <!-- 子分栏 1：数据备份 -->
   <div class="sub-panel active" id="system-sub-backup">
     <div class="help">
-      <b>导出</b>当前系统数据为 zip：含 <code>users.db</code> 在线一致快照（<b>全部业务表</b>：用户 / 任务计划 / 设备分组 /
+      <b>导出</b>当前系统数据为 zip：把数据库（MySQL 或回退模式的 SQLite）整库一致快照成
+      <code>users.db</code> 归档（<b>全部业务表</b>：用户 / 任务计划 / 设备分组 /
       自定义动作 / APK 记录 / 设备池 / 待连接设备 / AI 会话 / 经验库 / 经验巡检 / <b>动作库</b> / 系统配置）+ 可选的
       <code>apks/</code> 应用文件。恢复用：换机 / 整库迁移 / 出问题前留底。
-      <br><span class="text-muted">清单见预览的「表数据行数」；新增持久化表须登记进备份覆盖清单（红线，见 doc/DEPLOY.md §5.2）。</span>
+      <br><span class="text-muted">清单见预览的「表数据行数」（由模型元数据自动派生，新增表不会漏）；备份里记录了来源环境，跨环境导入默认拒绝。</span>
     </div>
     <div class="toolbar" style="gap:8px">
       <label style="display:inline-flex;align-items:center;gap:4px;margin:0 6px">
@@ -951,7 +1292,9 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
   <div class="sub-panel" id="system-sub-restore">
     <div class="help">
       <b>导入恢复</b>：上传平台导出的 <code>.zip</code> 或 <code>.db</code> → 先<b>校验预览</b> →
-      确认后系统会<b>自动备份当前库</b>并把恢复任务挂起，<b>重启 web_server 后生效</b>（导入将覆盖现有全部数据）。
+      确认后系统会<b>自动备份当前库</b>（<code>data/backups/pre_restore_*.zip</code>，可直接再导入回来）并把恢复任务挂起，
+      <b>重启 web_server 后生效</b>（导入将覆盖现有全部数据；数据替换在单个事务里完成，失败会自动回滚）。
+      <br><span class="text-muted">备份来自另一个环境（dev↔prod）时默认拒绝导入，需在预览页显式勾选「允许跨环境导入」。</span>
     </div>
     <div class="toolbar" style="gap:8px">
       <input type="file" id="restore-file" accept=".zip,.db">
@@ -961,6 +1304,51 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
     </div>
     <div id="restore-preview" style="margin-top:8px"></div>
   </div>
+
+  <!-- 子分栏 3：通知 / Webhook -->
+  <div class="sub-panel" id="system-sub-notify">
+    <div class="help">
+      <b>通知</b>：把平台事件（任务失败/成功、设备上下线、安装完成、备份恢复…）推到 webhook，
+      例如企业微信群机器人。每条 webhook <b>自己勾选关心哪些事件</b>——不勾就不推。
+      <br><span class="text-muted">为防刷屏：同一条 webhook 默认每 30 秒合并一次同类事件、每分钟最多 18 条
+      （企业微信硬限 20），超出的会压成一条「被限流折叠」摘要而不是丢掉。详见 <code>doc/NOTIFY.md</code>。</span>
+    </div>
+    <div class="toolbar" style="gap:10px;flex-wrap:wrap">
+      <button class="btn btn-primary" onclick="openNotifyModal(null)" data-perm="admin">＋ 新建 Webhook</button>
+      <button class="btn" onclick="loadNotifyPanel()">刷新</button>
+      <label style="display:flex;align-items:center;gap:6px;font-size:12.5px;cursor:pointer"
+             title="关掉后所有 webhook 暂停推送（配置保留）">
+        <input type="checkbox" id="notify-global" onchange="toggleNotifyGlobal(this)"> 启用通知
+      </label>
+      <span class="text-muted" style="font-size:11.5px">默认聚合
+        <input type="number" id="notify-agg" min="0" max="600" class="form-control"
+               style="width:64px;display:inline-block"> 秒 ·
+        限流 <input type="number" id="notify-rate" min="0" max="60" class="form-control"
+                  style="width:64px;display:inline-block"> 条/分
+        <button class="btn btn-xs" onclick="saveNotifyGlobal()">保存默认</button>
+      </span>
+    </div>
+    <table class="table">
+      <thead><tr><th>名称</th><th>格式</th><th>URL</th><th>订阅</th><th>状态</th><th>操作</th></tr></thead>
+      <tbody id="tb-notify-hooks"></tbody>
+    </table>
+
+    <div style="margin-top:18px;display:flex;align-items:center;gap:10px">
+      <b>发送记录</b>
+      <span class="text-muted" style="font-size:11.5px">仅本次运行期间（重启清空）；完整历史见 <code>logs/notify.log</code></span>
+      <button class="btn btn-xs" onclick="loadNotifyPanel()">刷新记录</button>
+    </div>
+    <table class="table">
+      <thead><tr><th style="width:160px">时间</th><th style="width:120px">Webhook</th><th style="width:180px">事件</th><th style="width:70px">结果</th><th>详情</th></tr></thead>
+      <tbody id="tb-notify-logs"></tbody>
+    </table>
+  </div>
+</div>
+
+<!-- 通知：编辑弹窗（内容由 static/admin/notify.js 渲染） -->
+<div id="notify-modal-overlay" onclick="if(event.target===this)closeNotifyModal()"
+     style="display:none;position:fixed;inset:0;background:rgba(0,0,0,.6);z-index:1340;align-items:flex-start;justify-content:center;overflow-y:auto;padding:30px 0">
+  <div id="notify-modal-box" style="background:#fff;border-radius:14px;padding:20px;width:760px;max-width:94vw;margin:auto"></div>
 </div>
 
 </div><!-- /.content -->
@@ -1003,12 +1391,12 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 
 <!-- ========== 元素抓取模态框（独立第二层，不覆盖任务编辑窗口）========== -->
 <div id="el-picker-overlay" class="modal-overlay" style="z-index:1100" onclick="if(event.target===this)closeElPicker()">
-  <div class="modal" id="el-picker-box" style="max-width:900px">
+  <div class="modal" id="el-picker-box" style="max-width:1800px;width:98vw">
     <div class="modal-header">
       <h3 id="el-picker-title">抓取元素</h3>
       <button class="close" onclick="closeElPicker()">&times;</button>
     </div>
-    <div class="modal-body" id="el-picker-body" style="max-height:75vh;padding:0;overflow:hidden;display:flex;flex-direction:column"></div>
+    <div class="modal-body" id="el-picker-body" style="height:88vh;padding:0;overflow:hidden;display:flex;flex-direction:column"></div>
     <div class="modal-footer" id="el-picker-footer"></div>
   </div>
 </div>
@@ -1027,6 +1415,10 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 <script src="/static/admin/apps.js"></script>
 <script src="/static/admin/admin.js"></script>
 <script src="/static/admin/agent.js"></script>
+<script src="/static/admin/taskgen.js"></script>
 <script src="/static/admin/system.js"></script>
+<script src="/static/admin/notify.js"></script>
+<script src="/static/admin/steplog.js"></script>
+<script src="/static/admin/recorder.js"></script>
 </body>
 </html>

templates/admin/wall.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>设备监控大屏</title>
+<title>{% if db_env and not db_env.is_prod %}{{ db_env.env }}-{% endif %}设备监控大屏</title>
 <style>
 /* ========== 监控大屏：深色控制室风格 ========== */
 @font-face{font-family:'Bricolage Grotesque';font-style:normal;font-weight:700;font-display:swap;src:url('/static/fonts/bricolage-700.woff2') format('woff2')}

web/__init__.py

@@ -10,6 +10,8 @@
   apks        — 应用管理
   tailscale   — Tailscale 管理
   system      — 系统数据备份导出/导入
+  device_agent— 设备端 Agent 专用接口（应用商店：清单/下载/上报）+ 其管理端配置
+  notify      — 通知 / Webhook 管理（配置、测试发送、发送记录、事件目录）
 """
 from flask import Blueprint
 
@@ -28,6 +30,9 @@ def register_blueprints(app):
     from .agent_api import bp as agent_bp
     _agent_mod.set_app(app)
     from .system_api import bp as system_bp
+    from .device_agent_api import bp as devagent_bp
+    from .notify_api import bp as notify_bp
     for bp in (auth_bp, monitor_bp, tasks_bp, admin_bp, tools_bp,
-               devices_bp, apks_bp, tailscale_bp, agent_bp, system_bp):
+               devices_bp, apks_bp, tailscale_bp, agent_bp, system_bp,
+               devagent_bp, notify_bp):
         app.register_blueprint(bp)

web/admin_api.py

@@ -1,17 +1,19 @@
 """管理域 API：用户管理/日志查看。"""
-import os
 import time
+from io import BytesIO
 
-from flask import Blueprint, jsonify, request
+from flask import Blueprint, jsonify, request, send_file
 from flask_login import current_user
 from flask import session
 
-from core.logger import _LOG_DIR, _MODULE_FILES
+from core import logger
+from core.logger import get_logger
 from core.models import db, User
 from web import context
 from web.auth import (admin_required, perm_required, _validate_perms,
                              PERM_LOGS)
 
+_log = get_logger("web")
 bp = Blueprint("admin", __name__)
 
 @bp.route("/api/users")
@@ -79,22 +81,173 @@ def api_users_delete(uid):
 
 
 # ================== API：日志查看 ==================
+#
+# 过滤/白名单都在 core.logger 里做（读取侧与写入侧共用同一份文件清单，
+# 见 core/logger.py「日志读取」一节）；这里只负责取参数 + 组装响应。
+
+
+def _log_filters():
+    """从 query string 取过滤条件（/api/logs 与 /api/logs/download 共用）。"""
+    return dict(keyword=request.args.get("q", ""),
+                min_level=request.args.get("level", ""),
+                since=request.args.get("since", ""),
+                until=request.args.get("until", ""))
+
 
 @bp.route("/api/logs")
 @perm_required(PERM_LOGS)
 def api_logs():
-    files = list(_MODULE_FILES.values())
+    """读日志：可按关键字 / 最低级别 / 时间范围过滤，返回结构化行。
-    current = request.args.get("file", "core.log")
+
-    lines = int(request.args.get("lines", 300))
+    参数：file 文件名（白名单）、q 关键字、level 最低级别（ERROR 含以上…）、
-    content = ""
+    since/until 时间、lines 返回条数（取**最近** N 条命中）。
-    path = os.path.join(_LOG_DIR, current)
+    """
-    if os.path.exists(path):
+    files = logger.list_log_files()
-        try:
+    names = [f["name"] for f in files]
-            with open(path, encoding="utf-8") as f:
+    # 默认仍落在 core.log（接口按 mtime 倒序返回，names[0] 会随当前哪个模块在
-                content = "".join(f.readlines()[-lines:])
+    # 写而漂移，作为"打开日志页时看哪个"不稳定）
-        except Exception as e:
+    default = "core.log" if "core.log" in names else (names[0] if names else "")
-            content = f"读取失败: {e}"
+    current = request.args.get("file") or default
-    return jsonify({"ok": True, "content": content, "file": current, "files": files})
+    try:
+        lines = int(request.args.get("lines", 300))
+    except (TypeError, ValueError):
+        lines = 300
+    res = logger.query_log(current, limit=lines, **_log_filters())
+    return jsonify({"ok": not res["error"], "error": res["error"], "file": current,
+                    "files": files, "rows": res["rows"], "matched": res["matched"],
+                    "scanned": res["scanned"], "truncated": res["truncated"]})
+
+
+@bp.route("/api/logs/download")
+@perm_required(PERM_LOGS)
+def api_logs_download():
+    """下载日志文件（带同样的过滤条件；无条件时就是整个文件）。
+
+    用 BytesIO 发送而不是 send_file(路径)：Windows 上流式发送时文件句柄可能
+    到 close 仍未释放，而日志文件正被日志线程持续写入，按路径发容易踩锁。
+    """
+    name = request.args.get("file", "")
+    text, err = logger.read_log_text(name, **_log_filters())
+    if err:
+        return jsonify({"ok": False, "error": err}), 404
+    data = text.encode("utf-8")
+    fname = f"{name}_{time.strftime('%Y%m%d_%H%M%S')}.txt"
+    _log.info("下载日志: %s（%d 字节）by %s", name, len(data),
+              getattr(current_user, "username", ""))
+    return send_file(BytesIO(data), as_attachment=True, download_name=fname,
+                     mimetype="text/plain; charset=utf-8")
+
+
+# ================== API：任务步骤明细 ==================
+#
+# 数据源是 task_step_log 表（结构化），不是 logs/task.log 文本——所以能按设备/
+# 任务/时间/结果过滤。写入侧见 core/step_log.py（异步写线程 + 保留期清理）。
+
+def _step_filters():
+    """从 query string 取步骤明细的过滤条件（列表与下载共用）。"""
+    return dict(serial=request.args.get("serial", ""),
+                job_id=request.args.get("job_id", ""),
+                result=request.args.get("result", ""),
+                run_id=request.args.get("run_id", ""),
+                keyword=request.args.get("q", ""),
+                since=logger.norm_ts(request.args.get("since", "")),
+                until=logger.norm_ts(request.args.get("until", ""), end=True))
+
+
+def _step_to_dict(r):
+    return {"id": r.id, "run_id": r.run_id, "job_id": r.job_id,
+            "job_name": r.job_name, "serial": r.serial,
+            "device_name": r.device_name, "step_path": r.step_path,
+            "step_label": r.step_label, "step_type": r.step_type,
+            "selector": r.selector, "result": r.result, "detail": r.detail,
+            "duration_ms": r.duration_ms, "created_at": r.created_at}
+
+
+@bp.route("/api/step_logs")
+@perm_required(PERM_LOGS)
+def api_step_logs():
+    """任务步骤明细（分页，最近的在前）。"""
+    from core import step_log
+    try:
+        limit = int(request.args.get("limit", 200))
+        offset = int(request.args.get("offset", 0))
+    except (TypeError, ValueError):
+        limit, offset = 200, 0
+    rows, total = step_log.query(limit=limit, offset=offset, **_step_filters())
+    return jsonify({"ok": True, "rows": [_step_to_dict(r) for r in rows],
+                    "total": total, "limit": limit, "offset": offset,
+                    "stats": step_log.stats(),
+                    "keep_days": step_log.KEEP_DAYS,
+                    "max_rows_per_run": step_log.MAX_ROWS_PER_RUN})
+
+
+@bp.route("/api/step_logs/runs")
+@perm_required(PERM_LOGS)
+def api_step_logs_runs():
+    """按 run_id 归组的一次运行概览（哪次运行、几步、失败几步）。"""
+    from core import step_log
+    f = _step_filters()
+    rows = step_log.runs(serial=f["serial"], job_id=f["job_id"],
+                         since=f["since"], until=f["until"],
+                         limit=request.args.get("limit", 100))
+    return jsonify({"ok": True, "runs": [
+        {"run_id": r.run_id, "job_id": r.job_id, "job_name": r.job_name,
+         "serial": r.serial, "device_name": r.device_name,
+         "started_at": r.started_at, "ended_at": r.ended_at,
+         "steps": int(r.steps or 0), "failures": int(r.failures or 0)}
+        for r in rows]})
+
+
+@bp.route("/api/step_logs/filters")
+@perm_required(PERM_LOGS)
+def api_step_logs_filters():
+    """筛选下拉的可选项：**只在明细里出现过的**设备与任务（按数据自洽，不依赖
+    设备池/任务表，也不要求调用方另有 task/device 权限）。"""
+    from core import step_log
+    from core.models import TaskStepLog, db
+    devices = (db.session.query(TaskStepLog.serial, TaskStepLog.device_name)
+               .filter(TaskStepLog.serial != "").distinct().limit(500).all())
+    jobs = (db.session.query(TaskStepLog.job_id, TaskStepLog.job_name)
+            .filter(TaskStepLog.job_id != "").distinct().limit(500).all())
+    return jsonify({"ok": True,
+                    "devices": sorted(({"serial": s, "device_name": n}
+                                       for s, n in devices),
+                                      key=lambda x: x["device_name"] or x["serial"]),
+                    "jobs": sorted(({"job_id": i, "job_name": n} for i, n in jobs),
+                                   key=lambda x: x["job_name"] or x["job_id"]),
+                    "results": ["ok", "miss", "error", "unknown", "skip", "cap"],
+                    "keep_days": step_log.KEEP_DAYS,
+                    "max_rows_per_run": step_log.MAX_ROWS_PER_RUN})
+
+
+@bp.route("/api/step_logs/download")
+@perm_required(PERM_LOGS)
+def api_step_logs_download():
+    """导出步骤明细为 CSV（带同样的过滤条件）。
+
+    加 UTF-8 BOM：不加的话 Excel 打开中文是乱码（这是给运维看的表，
+    大概率会被 Excel 打开）。
+    """
+    import csv
+    from io import StringIO
+    from core import step_log
+    f = _step_filters()
+    # 导出上限：和列表页共用同一次查询，最多 2 万行（再多请缩小时间范围）
+    rows, total = step_log.query(limit=20000, offset=0, **f)
+    buf = StringIO()
+    w = csv.writer(buf)
+    w.writerow(["时间", "设备", "设备名", "任务", "运行ID", "步骤路径", "步骤",
+                "类型", "选择器", "结果", "耗时(ms)", "详情"])
+    for r in reversed(rows):        # 导出的时间序与页面相反：文件里按正序更好读
+        w.writerow([r.created_at, r.serial, r.device_name, r.job_name,
+                    r.run_id, r.step_path, r.step_label, r.step_type,
+                    r.selector, r.result, r.duration_ms, r.detail])
+    data = buf.getvalue().encode("utf-8-sig")   # utf-8-sig = UTF-8 带 BOM（Excel 中文不乱码）
+    fname = f"step_log_{time.strftime('%Y%m%d_%H%M%S')}.csv"
+    _log.info("导出步骤明细: %d 行（命中 %d）by %s", len(rows), total,
+              getattr(current_user, "username", ""))
+    return send_file(BytesIO(data), as_attachment=True, download_name=fname,
+                     mimetype="text/csv; charset=utf-8")
 
 
 # ================== API：运行控制 ==================

web/agent_api.py

@@ -43,12 +43,22 @@ _CFG_KEYS = {"api_base": "agent_api_base",
 # 推理链落库上限（字符）：只留够回看的量，避免会话消息无限膨胀
 _REASONING_KEEP = 6000
 
+# AI 建任务：草稿落库的 app_meta 键（**不新建表** —— 只存最近一份，
+# 刷新/重进页面能拿回来；见 doc/AI_TASK_GEN.md）
+_DRAFT_META_KEY = "agent_task_draft"
+# 草稿 JSON 体积上限（app_meta.value 是 TEXT）：超了截断 notes/evidence，不报错
+_DRAFT_MAX_CHARS = 60000
+
 
 # ---------- 运行状态（单实例 + 事件队列） ----------
 _run = {"id": None, "state": "idle", "prompt": "", "serial": "",
         "answer": "", "error": "", "usage": {},
+        "mode": "chat",       # chat（聊天）| designer（AI 建任务）
+        "draft": None,        # designer：submit_task 校验通过的任务草稿
+        "draft_error": "",    # designer：草稿被拦下的原因（errors 拼接）
+        "warnings": [],       # designer：草稿的提醒项（不拦，前端醒目展示）
         "history": []}   # 多轮对话历史 [{role: user|assistant, content}]
-_queues = {}            # run_id -> queue.Queue（SSE 消费者读取）
+_queues = {}            # run_id -> _Fanout（SSE 消费者各自订阅，见下）
 _stop_events = {}       # run_id -> threading.Event（用户中断）
 _lock = threading.Lock()
 _flask_app = None       # web_server 注册时注入（后台线程 db 操作需 app context）
@@ -59,15 +69,71 @@ def set_app(app):
     _flask_app = app
 
 
+class _Fanout:
+    """一个 Agent 轮次的事件，扇出给**所有**订阅者（每个订阅者一个独立队列）。
+
+    历史实现是"一个 run 一个 queue.Queue"：第二个页面一订阅，两个 EventSource 就
+    开始**瓜分**同一条队列——谁先取到算谁的。2026-09-14 实测踩到：同一个浏览器里
+    聊天页与建任务页同时开着，建任务页的回放卡到一半就不动了、`done` 事件被另一个
+    页面取走 → 永远等不到草稿（表现为"探索完没法创建任务"）。
+    扇出之后，多开几个页面都各看各的，谁都不丢事件。
+    """
+
+    # 单轮事件缓冲上限：新订阅者从这里补齐"订阅之前"的回放（刷新/重连不丢进度）。
+    # 只留最近 _HISTORY_KEEP 条，避免长任务把内存拖大；终止事件（done/error）永远保留。
+    _HISTORY_KEEP = 400
+
+    def __init__(self):
+        self._subs = []
+        self._history = []
+        self._closed = False
+        self._lock = threading.Lock()
+
+    def subscribe(self):
+        """新订阅者拿一个专属队列（**预填已发生的事件**）；轮次已结束则返回 None。"""
+        with self._lock:
+            if self._closed:
+                return None
+            q = queue.Queue()
+            for item in self._history:
+                q.put(item)
+            self._subs.append(q)
+            return q
+
+    def unsubscribe(self, q):
+        with self._lock:
+            if q in self._subs:
+                self._subs.remove(q)
+
+    def put(self, item):
+        with self._lock:
+            subs = list(self._subs)
+            self._history.append(item)
+            # 只留最近 N 条。终止事件（done/error 及其后的哨兵）永远在尾部，
+            # 按这个规则裁剪不会把它们丢掉。
+            if len(self._history) > self._HISTORY_KEEP:
+                del self._history[:len(self._history) - self._HISTORY_KEEP]
+        for q in subs:
+            q.put(item)
+
+    def close(self):
+        """结束：给每个订阅者发终止哨兵（None）。"""
+        with self._lock:
+            self._closed = True
+            subs, self._subs = self._subs, []
+        for q in subs:
+            q.put(None)
+
+
 def _meta_get(key):
-    return db.session.execute(
+    # 走方言中立助手（app_meta 的列名 key 在 MySQL 里是保留字，裸 SQL 会语法错）
-        db.text("SELECT value FROM app_meta WHERE key=:k"), {"k": key}).scalar() or ""
+    from core.db_config import meta_get
+    return meta_get(key) or ""
 
 
 def _meta_put(key, value):
-    db.session.execute(
+    from core.db_config import meta_set
-        db.text("INSERT OR REPLACE INTO app_meta(key,value) VALUES(:k,:v)"),
+    meta_set(key, str(value))
-        {"k": key, "v": str(value)})
 
 
 def _read_cfg():
@@ -75,29 +141,10 @@ def _read_cfg():
 
 
 # ================== 经验记忆（自进化） ==================
-# agent_experience：任务成功后的操作配方，下次相似任务检索注入 system prompt。
+# agent_experience / experience_audit / agent_action / agent_conversation 四张表
-# 原始 SQLite（CREATE IF NOT EXISTS 幂等），不进模型层迁移。
+# 已在 core/models.py 里定义为 ORM 模型（唯一真相），建表统一由 db.create_all() 完成。
-_EXP_TABLE = """
+# 以前这里是各写一段 SQLite 的 CREATE TABLE + try/except: pass —— 换 MySQL 后
-CREATE TABLE IF NOT EXISTS agent_experience (
+# AUTOINCREMENT / TEXT DEFAULT 全都建不出来，而异常被吞掉，表现为"功能静默失灵"。""
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  task_prompt TEXT DEFAULT '',
-  recipe TEXT DEFAULT '',
-  tool_seq TEXT DEFAULT '',
-  hits INTEGER DEFAULT 0,
-  created_at VARCHAR(20) DEFAULT '')"""
-
-# 经验巡检（AI 质检）：每日定时把经验交给模型评审，疑似问题标 pending 待人工确认。
-# 删除只允许人工（前端 confirm / 本 API），巡检绝不自动删。
-_AUDIT_TABLE = """
-CREATE TABLE IF NOT EXISTS experience_audit (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  exp_id INTEGER NOT NULL,
-  verdict TEXT DEFAULT '',       -- keep 保留 / delete 建议删除
-  score REAL DEFAULT 0,          -- 0-10 可用性评分
-  reason TEXT DEFAULT '',        -- 模型给出的理由
-  hits INTEGER DEFAULT 0,        -- 巡检时的引用次数（hits>0 被删要更谨慎）
-  action TEXT DEFAULT 'pending', -- pending 待人工确认 / kept 已保留 / deleted 已删除
-  audited_at VARCHAR(20) DEFAULT '')"""
 
 # 巡检评审提示词：模型只判「保留/建议删除」+ 评分 + 理由，不直接删。
 _AUDIT_PROMPT = """你是「手机自动化经验库」质检员。经验库存放 AI 成功操作手机后提炼的
@@ -119,12 +166,20 @@ _AUDIT_PROMPT = """你是「手机自动化经验库」质检员。经验库存
 只输出 JSON：{{"keep": true或false, "score": 0到10的整数, "reason": "一句话中文理由"}}"""
 
 
-def _ensure_exp_table():
+def _ensure_tables():
+    """确保 agent 系四张表存在（幂等）。create_all 只建缺失的表，开销可以忽略。
+
+    失败必须落日志：以前是 except: pass，MySQL 下建表失败会被完全吞掉，
+    表不存在 → 后续查询全报错，而日志里什么都看不到。
+    """
     try:
-        db.session.execute(db.text(_EXP_TABLE))
+        db.create_all()
-        db.session.commit()
+    except Exception as e:
-    except Exception:
+        _log.error(f"agent 表创建失败: {e}")
-        pass
+
+
+def _ensure_exp_table():
+    _ensure_tables()
 
 
 def _bigrams(text):
@@ -366,19 +421,7 @@ def _save_experience(prompt, recipe, tool_seq):
 # steps 直接用编辑器 schema（open_app/click/input_text…），带**元素定位**
 # （selector_type/selector_value），**不含坐标**（分辨率/旋转/改版即失效）。
 # 复用：执行前按 name/别名/App 召回并注入 system prompt，模型可跳过重新探索。
-_ACTION_TABLE = (
+# 建表见 core/models.py 的 AgentAction
-    "CREATE TABLE IF NOT EXISTS agent_action ("
-    "id INTEGER PRIMARY KEY AUTOINCREMENT,"
-    "name TEXT NOT NULL,"
-    "app TEXT DEFAULT '',"
-    "aliases TEXT DEFAULT '[]',"
-    "params TEXT DEFAULT '[]',"
-    "steps TEXT NOT NULL,"
-    "preconditions TEXT DEFAULT '',"
-    "hits INTEGER DEFAULT 0,"
-    "source_prompt TEXT DEFAULT '',"
-    "created_at TEXT DEFAULT '',"
-    "updated_at TEXT DEFAULT '')")
 
 # 允许沉淀的步骤类型（编辑器 STEP_TYPES 子集；显式排除 click_xy 等坐标类）
 _ACTION_STEP_TYPES = {
@@ -398,11 +441,7 @@ _ACTION_TOOLS = {
 
 
 def _ensure_action_table():
-    try:
+    _ensure_tables()
-        db.session.execute(db.text(_ACTION_TABLE))
-        db.session.commit()
-    except Exception:
-        pass
 
 
 def _brief_result(result):
@@ -731,11 +770,7 @@ _audit_state = {"running": False, "last": "", "last_summary": ""}
 
 
 def _ensure_audit_table():
-    try:
+    _ensure_tables()
-        db.session.execute(db.text(_AUDIT_TABLE))
-        db.session.commit()
-    except Exception:
-        pass
 
 
 def _review_one_exp(cfg, prompt, recipe, tool_seq, hits):
@@ -801,6 +836,8 @@ def run_experience_audit():
             cfg = _read_cfg()
             if not cfg.get("api_key"):
                 _log.info("经验巡检跳过：未配置 API Key")
+                from core import notifier
+                notifier.notify("ai.audit.skipped", reason="未配置模型 API Key")
                 return
             rows = db.session.execute(db.text(
                 "SELECT id, task_prompt, recipe, tool_seq, hits FROM agent_experience "
@@ -833,8 +870,16 @@ def run_experience_audit():
             summary = f"评审 {reviewed} 条，建议删除 {suggested} 条（待人工确认）"
             _audit_state.update(last=now, last_summary=summary)
             _log.info("经验巡检完成: %s", summary)
+            from core import notifier
+            notifier.notify("ai.audit.finished", reviewed=reviewed,
+                            suggested=suggested, summary=summary)
     except Exception as e:
         _log.warning(f"经验巡检异常: {e}")
+        try:
+            from core import notifier
+            notifier.notify("ai.audit.failed", error=str(e)[:200])
+        except Exception:
+            pass
     finally:
         _audit_state["running"] = False
 
@@ -1002,22 +1047,11 @@ def agent_actions_save():
 
 # ================== 历史会话（DeepSeek 式：多会话持久化） ==================
 # 会话 = 消息序列（JSON），一轮 run 的 user/assistant 文本完成后追加落库。
-# 单表 JSON 存储（每会话几十 KB 内，无需独立消息表）。
+# 单表 JSON 存储（每会话几十 KB 内，无需独立消息表）。建表见 core/models.py。
-_CONV_TABLE = """
-CREATE TABLE IF NOT EXISTS agent_conversation (
-  id VARCHAR(20) PRIMARY KEY,
-  title VARCHAR(100) DEFAULT '',
-  messages TEXT DEFAULT '[]',
-  created_at VARCHAR(20) DEFAULT '',
-  updated_at VARCHAR(20) DEFAULT '')"""
 
 
 def _ensure_conv_table():
-    try:
+    _ensure_tables()
-        db.session.execute(db.text(_CONV_TABLE))
-        db.session.commit()
-    except Exception:
-        pass
 
 
 def _conv_msgs(conv_id):
@@ -1143,13 +1177,26 @@ def agent_conversations_rename(conv_id):
 @bp.route("/api/agent/run", methods=["POST"])
 @admin_required
 def agent_run():
-    """启动 Agent：{prompt, serial?, conversation_id?}。运行中返回 409。"""
+    """启动 Agent：{prompt, serial?, conversation_id?, mode?, settings?}。运行中返回 409。
+
+    mode=chat（默认）：AI 控制台聊天（现状不变）
+    mode=designer：AI 建任务 —— 探索设备 → 用 submit_task 提交任务草稿（不落库）
+    settings：建任务页上用户填的任务设置（任务名/目标/调度），作为草稿的 overrides
+    """
     data = request.json or {}
     prompt = (data.get("prompt") or "").strip()
     if not prompt:
         return jsonify({"ok": False, "error": "请输入指令"}), 400
     serial = (data.get("serial") or "").strip()
     conv_id = (data.get("conversation_id") or "").strip()
+    mode = (data.get("mode") or "chat").strip()
+    if mode not in ("chat", "designer"):
+        return jsonify({"ok": False, "error": f"未知模式: {mode}"}), 400
+    settings = data.get("settings") if isinstance(data.get("settings"), dict) else {}
+    # 建任务模式是单轮的：不绑会话（避免把聊天历史灌进设计师上下文，
+    # 也避免探索过程污染聊天会话）
+    if mode == "designer":
+        conv_id = ""
     cfg = _read_cfg()
     if not cfg.get("api_key"):
         return jsonify({"ok": False, "error": "请先在配置区填写 API Key"}), 400
@@ -1181,13 +1228,15 @@ def agent_run():
             try:
                 from datetime import datetime as _dt2
                 now = _dt2.now().strftime("%Y-%m-%d %H:%M")
+                # 上面刚确认过会话不存在，普通 INSERT 即可；
+                # 并发下撞主键就回滚忽略（原来用 SQLite 专有的 INSERT OR IGNORE）
                 db.session.execute(db.text(
-                    "INSERT OR IGNORE INTO agent_conversation(id, messages, "
+                    "INSERT INTO agent_conversation(id, messages, "
                     "created_at, updated_at) VALUES(:i, '[]', :c, :c)"),
                     {"i": conv_id, "c": now})
                 db.session.commit()
             except Exception:
-                pass
+                db.session.rollback()
     with _lock:
         if _run["state"] == "running":
             return jsonify({"ok": False, "error":
@@ -1196,15 +1245,17 @@ def agent_run():
         run_id = uuid.uuid4().hex[:8]
         from datetime import datetime as _dt
         _run.update(id=run_id, state="running", prompt=prompt,
-                    serial=serial, conv_id=conv_id,
+                    serial=serial, conv_id=conv_id, mode=mode,
                     started=_dt.now().strftime("%H:%M:%S"),
-                    answer="", error="", usage={})
+                    answer="", error="", usage={},
+                    draft=None, draft_error="", warnings=[])
         # history 保留（多轮上下文），由会话/「新建会话」管理
-        _queues[run_id] = queue.Queue()
+        _queues[run_id] = _Fanout()
         _stop_events[run_id] = threading.Event()
-    _log.info(f"Agent 启动: {prompt[:60]} @ {serial or 'default'} conv={conv_id or '-'}")
+    _log.info(f"Agent 启动[{mode}]: {prompt[:60]} @ {serial or 'default'} "
+              f"conv={conv_id or '-'}")
     threading.Thread(target=_agent_thread,
-                     args=(run_id, prompt, serial, cfg),
+                     args=(run_id, prompt, serial, cfg, mode, settings),
                      daemon=True).start()
     return jsonify({"ok": True, "run_id": run_id})
 @bp.route("/api/agent/config", methods=["GET"])
@@ -1251,6 +1302,10 @@ def agent_run_status():
                         "answer": (_run.get("answer") or "")[:4000],
                         "error": (_run.get("error") or "")[:400],
                         "usage": _run.get("usage") or {},
+                        "mode": _run.get("mode") or "chat",
+                        "draft": _run.get("draft"),
+                        "draft_error": _run.get("draft_error") or "",
+                        "warnings": _run.get("warnings") or [],
                         "history": hist[-16:]})
 
 
@@ -1287,21 +1342,29 @@ def agent_stream():
     with _lock:
         if run_id != _run["id"]:
             return jsonify({"ok": False, "error": "run_id 不存在"}), 404
-        q = _queues.get(run_id)
+        fan = _queues.get(run_id)
+    # 每个订阅者一个专属队列（多开页面互不抢事件）；轮次已结束 → 404
+    q = fan.subscribe() if fan is not None else None
+    if q is None:
+        return jsonify({"ok": False, "error": "本轮已结束"}), 404
 
     def gen():
-        while True:
+        try:
-            try:
+            while True:
-                evt = q.get(timeout=15)
+                try:
-            except queue.Empty:
+                    evt = q.get(timeout=15)
-                yield ": keepalive\n\n"   # 心跳防超时
+                except queue.Empty:
-                continue
+                    yield ": keepalive\n\n"   # 心跳防超时
-            if evt is None:
+                    continue
-                break
+                if evt is None:
-            kind, payload = evt
+                    break
-            yield f"event: {kind}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"
+                kind, payload = evt
-            if kind in ("done", "error"):
+                yield f"event: {kind}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"
-                break
+                if kind in ("done", "error"):
+                    break
+        finally:
+            # 页面关掉/断线时摘掉自己的队列，别让扇出往里堆没人读的事件
+            fan.unsubscribe(q)
 
     return Response(gen(), mimetype="text/event-stream",
                     headers={"Cache-Control": "no-cache",
@@ -1331,6 +1394,165 @@ def agent_clear():
     return jsonify({"ok": True, "msg": "已清空"})
 
 
+# ================== AI 建任务：草稿 ==================
+# 草稿只存**最近一份**（app_meta 单键），用途是"刷新/重进页面能拿回来"与审计；
+# 它不是任务 —— 真正入库仍要用户在步骤编辑器里确认后走 POST /api/jobs。
+def _load_draft_meta():
+    """读回最近一份草稿（无则 None）。"""
+    raw = _meta_get(_DRAFT_META_KEY)
+    if not raw:
+        return None
+    try:
+        obj = json.loads(raw)
+        return obj if isinstance(obj, dict) else None
+    except (json.JSONDecodeError, TypeError):
+        _log.warning("草稿 JSON 解析失败，忽略")
+        return None
+
+
+def _draft_env():
+    """校验草稿要用的环境信息：现有分组名 + 设备池（取不到就跳过对应校验）。"""
+    groups = pool = None
+    try:
+        from core import device_pool
+        from web import context
+        groups = set(context.mgr.groups.keys())
+        pool = set(device_pool.list_configured())
+    except Exception as e:
+        _log.warning(f"分组/设备池读取失败，跳过对应校验: {e}")
+    return groups, pool
+
+
+def _persist_draft(draft, warnings, prompt=""):
+    """把草稿存进 app_meta（体积超限时逐级瘦身，不报错）。"""
+    from datetime import datetime as _dt
+    saved = {"draft": draft, "warnings": list(warnings or []),
+             "prompt": (prompt or "")[:500],
+             "created": _dt.now().strftime("%Y-%m-%d %H:%M")}
+    raw = json.dumps(saved, ensure_ascii=False)
+    if len(raw) > _DRAFT_MAX_CHARS:
+        saved["draft"]["evidence"] = []
+        raw = json.dumps(saved, ensure_ascii=False)
+    if len(raw) > _DRAFT_MAX_CHARS:
+        saved["draft"]["notes"] = list(saved["draft"].get("notes") or [])[:2]
+        raw = json.dumps(saved, ensure_ascii=False)
+    if len(raw) > _DRAFT_MAX_CHARS:
+        _log.warning(f"草稿体积仍超限（{len(raw)} 字符），照原样存入")
+    _meta_put(_DRAFT_META_KEY, raw)
+    try:
+        db.session.commit()
+    except Exception:
+        db.session.rollback()
+    return saved
+
+
+@bp.route("/api/agent/task_draft")
+@admin_required
+def agent_task_draft_get():
+    """读回最近一次 AI 建任务的草稿（页面刷新/重进时恢复用）。"""
+    saved = _load_draft_meta()
+    with _lock:
+        cur = _run.get("draft")
+        st = _run.get("state")
+        mode = _run.get("mode") or "chat"
+        run_id = _run.get("id") or "" if st == "running" else ""
+    return jsonify({"ok": True, "saved": saved,
+                    "running": st == "running", "mode": mode, "run_id": run_id,
+                    "draft": cur, "draft_error": _run.get("draft_error") or ""})
+
+
+@bp.route("/api/agent/task_draft", methods=["POST"])
+@admin_required
+def agent_task_draft_save():
+    """回存一份草稿（人工在页面上改过之后）。会重新校验一次。"""
+    from core.task_draft import validate_draft
+    data = request.json or {}
+    groups, pool = _draft_env()
+    res = validate_draft(data.get("draft"), groups=groups, pool=pool,
+                         default_serial=(data.get("serial") or "").strip())
+    if not res["ok"]:
+        return jsonify({"ok": False, "error": "草稿校验未通过",
+                        "errors": res["errors"]}), 400
+    saved = _persist_draft(res["draft"], res["warnings"],
+                           prompt=data.get("prompt") or "")
+    with _lock:
+        _run["draft"] = res["draft"]
+        _run["warnings"] = res["warnings"]
+        _run["draft_error"] = ""
+    return jsonify({"ok": True, "msg": "草稿已保存", "saved": saved})
+
+
+@bp.route("/api/agent/task_draft/create", methods=["POST"])
+@admin_required
+def agent_task_draft_create():
+    """把暂存的草稿**直接创建**成任务（AI 建任务页的「直接创建任务」）。
+
+    这是"AI 直接建任务"的落点，两条设计约束：
+      - **草稿体只在服务端**（app_meta）：客户端只能传 overrides，不能把任务内容
+        再提交一遍——少一个可被篡改的入口；
+      - 创建前**再校验一次**（草稿可能是人工改过的），通过后走与「新建任务」
+        **完全相同**的落库路径 `context.mgr.add_job`。
+    创建成功后清掉草稿（同一份草稿不该被重复建成多个任务）。
+    """
+    from core.task_draft import validate_draft
+    from web import context
+    saved = _load_draft_meta()
+    if not saved or not saved.get("draft"):
+        return jsonify({"ok": False, "error": "没有可创建的草稿，请先探索一次"}), 400
+    data = request.json or {}
+    overrides = data.get("overrides") if isinstance(data.get("overrides"), dict) else {}
+    groups, pool = _draft_env()
+    res = validate_draft(saved["draft"], groups=groups, pool=pool,
+                         default_serial=(data.get("serial") or "").strip(),
+                         overrides=overrides)
+    if not res["ok"]:
+        return jsonify({"ok": False, "error": "草稿校验未通过（请在编辑器里核对）",
+                        "errors": res["errors"]}), 400
+    task = res["draft"]["task"]
+    params = task["params"]
+    params.setdefault("skip_offline", True)   # 与编辑器保存时一致
+    try:
+        job = context.mgr.add_job(name=task["name"], task_type=task["task_type"],
+                                  target=task["target"], params=params,
+                                  schedule=task["schedule"], retry=task["retry"],
+                                  enabled=bool(task.get("enabled", True)))
+    except Exception as e:
+        _log.exception("AI 草稿创建任务失败")
+        return jsonify({"ok": False, "error": f"创建失败: {e}"}), 500
+    # 用掉就清掉，避免重复创建
+    _meta_put(_DRAFT_META_KEY, "")
+    try:
+        db.session.commit()
+    except Exception:
+        db.session.rollback()
+    with _lock:
+        _run["draft"] = None
+        _run["warnings"] = []
+    d = job.to_dict()
+    nr = context.mgr.next_run_of(job)
+    d["next_run"] = nr.strftime("%Y-%m-%d %H:%M") if nr else None
+    _log.info(f"AI 草稿已创建任务: {job.name}（{job.id}）"
+              f"{'，' + str(len(res['warnings'])) + ' 条提醒' if res['warnings'] else ''}")
+    return jsonify({"ok": True, "msg": f"任务「{job.name}」已创建",
+                    "job": d, "warnings": res["warnings"]})
+
+
+@bp.route("/api/agent/task_draft/clear", methods=["POST"])
+@admin_required
+def agent_task_draft_clear():
+    """丢弃当前草稿。"""
+    _meta_put(_DRAFT_META_KEY, "")
+    try:
+        db.session.commit()
+    except Exception:
+        db.session.rollback()
+    with _lock:
+        _run["draft"] = None
+        _run["warnings"] = []
+        _run["draft_error"] = ""
+    return jsonify({"ok": True, "msg": "已丢弃草稿"})
+
+
 def _shrink_image(b64, width=220, quality=50):
     """截图降采样（SSE step 事件用，控制传输体积）。失败原样返回。"""
     try:
@@ -1345,9 +1567,15 @@ def _shrink_image(b64, width=220, quality=50):
         return b64
 
 
-def _agent_thread(run_id, prompt, serial, cfg):
+def _agent_thread(run_id, prompt, serial, cfg, mode="chat", settings=None):
-    """后台线程：Agent 流式执行，事件推入队列供 SSE 消费。"""
+    """后台线程：Agent 流式执行，事件推入队列供 SSE 消费。
+
+    mode=designer 时额外注册平台级工具 `submit_task`：它把 AI 探索出的任务草稿
+    交给 `core/task_draft` 校验，**通过也只暂存、不落库**（人工确认后才入库）。
+    """
     q = _queues.get(run_id)
+    settings = settings if isinstance(settings, dict) else {}
+    designer = (mode == "designer")
     try:
         # 平台进程 cwd=/app（含 mcp_agent 包），进程内 import
         sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
@@ -1379,6 +1607,12 @@ def _agent_thread(run_id, prompt, serial, cfg):
                    "args": step.get("args") or {}}
             if step.get("image"):
                 rec["image"] = _shrink_image(step["image"])
+            # 工具报错时把原因带出去：前端卡片直接显示"这步为什么失败"
+            # （模型看得到 errors，人也要看得到）
+            r = step.get("result")
+            if isinstance(r, dict) and r.get("ok") is False:
+                rec["error"] = str(r.get("error")
+                                   or "；".join(r.get("errors") or []) or "失败")[:300]
             q.put(("step", rec))
             # 记录精简工具序列 + 结构化轨迹（去 serial、结果截断）
             try:
@@ -1421,6 +1655,76 @@ def _agent_thread(run_id, prompt, serial, cfg):
                 history = list(_run.get("history") or [])
         target = serial or cfg.get("default_serial") or ""
         stop_evt = _stop_events.get(run_id)
+        if designer:
+            # 建任务模式是单轮的：不吃聊天历史（避免把聊天上下文灌进设计师）
+            with _lock:
+                _run["history"] = []
+            history = []
+
+        async def submit_task(args):
+            """平台级工具：校验 AI 提交的任务草稿。
+
+            失败 → 把 errors 原样回给模型，让它逐条修正后重提（这是"AI 写坏任务"
+            的唯一闸门：POST /api/jobs 对 params 是盲存的，执行器又静默跳过错误步骤）。
+            成功 → 只暂存在运行态 + app_meta，等用户在步骤编辑器里确认后才入库。
+            """
+            from core.task_draft import validate_draft
+
+            def _work():
+                """校验 + 暂存（读分组/设备池、写 app_meta 都要 app context）。"""
+                groups, pool = _draft_env()
+                r = validate_draft(args, groups=groups, pool=pool,
+                                   default_serial=target, overrides=settings)
+                if r["ok"]:
+                    _persist_draft(r["draft"], r["warnings"], prompt=prompt)
+                return r
+
+            try:
+                if _flask_app is not None:
+                    with _flask_app.app_context():
+                        res = _work()
+                else:
+                    res = _work()
+            except Exception as e:
+                # 后台线程里任何异常都不能冒泡成"工具执行失败"这种含糊文案——
+                # 模型与用户都需要知道草稿到底存没存下
+                _log.exception("[designer] 草稿处理失败")
+                with _lock:
+                    _run["draft_error"] = f"草稿处理失败: {e}"
+                q.put(("step", {"tool": "📝 草稿未存下",
+                                "args": f"服务端处理草稿时出错：{type(e).__name__}: {str(e)[:160]}",
+                                "image": None}))
+                return {"ok": False,
+                        "error": f"服务端处理草稿时出错（{type(e).__name__}: {e}），"
+                                 "草稿没有保存。请把 steps 精简后重试一次；"
+                                 "若仍失败，说明是平台问题，先向用户说明。"}
+            if not res["ok"]:
+                msg = "；".join(res["errors"][:6])
+                with _lock:
+                    _run["draft_error"] = msg
+                q.put(("step", {"tool": "📝 草稿被拦下",
+                                "args": f"{len(res['errors'])} 处问题需要修正：{msg}",
+                                "image": None}))
+                return {"ok": False,
+                        "error": "草稿未通过校验，请按下面的 errors 逐条修正后"
+                                 "**重新调用一次 submit_task**",
+                        "errors": res["errors"], "warnings": res["warnings"]}
+            draft = res["draft"]
+            n_steps = len(((draft.get("task") or {}).get("params") or {}).get("steps") or [])
+            with _lock:
+                _run["draft"] = draft
+                _run["warnings"] = res["warnings"]
+                _run["draft_error"] = ""
+            q.put(("step", {"tool": "📝 任务草稿",
+                            "args": f"已提交草稿「{draft['task'].get('name', '')}」："
+                                    f"{n_steps} 个顶层步骤"
+                                    + (f"，{len(res['warnings'])} 条待复核提醒"
+                                       if res["warnings"] else ""),
+                            "image": None}))
+            return {"ok": True,
+                    "msg": "草稿已收到并通过校验，已交给用户确认。请立即停止调用工具，"
+                           "用一句中文总结这条任务做什么、哪些步骤需要人工复核。",
+                    "warnings": res["warnings"]}
 
         # 经验检索：相似历史任务的操作配方注入 system（自进化记忆）
         exp_ctx, exp_items = _find_experiences(prompt)
@@ -1443,6 +1747,25 @@ def _agent_thread(run_id, prompt, serial, cfg):
         if act_ctx:
             recall_ctx += ("\n\n## 可复用动作（优先按其中的元素定位操作；"
                            "若与当前界面不符，再自行截图确认）\n" + act_ctx)
+        if designer and settings:
+            # 用户在页面上填的任务设置：必须落到 draft 里，别让模型自己编
+            hints = []
+            if settings.get("name"):
+                hints.append(f"- 任务名：{settings['name']}")
+            mode_ = settings.get("target_mode")
+            if mode_ == "group" and settings.get("group_name"):
+                hints.append(f"- 目标：分组「{settings['group_name']}」")
+            elif mode_ == "all":
+                hints.append("- 目标：全部空闲设备")
+            elif mode_ == "serial":
+                hints.append(f"- 目标：指定设备 {settings.get('serial') or target}")
+            if settings.get("schedule_hint"):
+                hints.append(f"- 调度：{settings['schedule_hint']}")
+            if settings.get("max_duration"):
+                hints.append(f"- 运行时长上限：{settings['max_duration']} 秒")
+            if hints:
+                recall_ctx += ("\n\n## 用户已指定的任务设置（必须原样写进 draft.task）\n"
+                               + "\n".join(hints))
 
         mcp_url = getattr(getattr(agent, "s", None), "mcp_url", "")
 
@@ -1457,6 +1780,9 @@ def _agent_thread(run_id, prompt, serial, cfg):
                 "network is unreachable", "connect timeout"))
 
         async def _execute():
+            # 建任务模式：先注册平台级工具（必须在 _load_tools 之前，schema 在加载时组装）
+            if designer:
+                agent.register_local_tool("submit_task", submit_task)
             try:
                 await agent._load_tools()
             except Exception as e:
@@ -1473,7 +1799,8 @@ def _agent_thread(run_id, prompt, serial, cfg):
                                               should_stop=lambda: bool(
                                                   stop_evt and stop_evt.is_set()),
                                               extra_context=recall_ctx,
-                                              on_usage=on_usage)
+                                              on_usage=on_usage,
+                                              mode=mode)
             except Exception as e:
                 if _mcp_unreachable(e):
                     raise RuntimeError(
@@ -1518,7 +1845,11 @@ def _agent_thread(run_id, prompt, serial, cfg):
         # 自进化：成功执行过工具则提炼配方写入经验。必须在 done 之前完成——
         # done 发出后 SSE 关流，用户就看不到「已写入经验」的提示了。
         # 提炼/保存失败静默（不阻塞、不影响结果），只在成功时推送 🧠 卡片。
-        if tool_seq:
+        # 建任务（designer）模式也沉淀，但**只在草稿通过校验时**：那说明这轮探索
+        # 确实走通了一条路。没有草稿的探索（试错、半途而废）不入库，免得把误点当经验。
+        with _lock:
+            draft_ok = bool(_run.get("draft"))
+        if tool_seq and (not designer or draft_ok):
             try:
                 recipe = _clean_recipe(_distill_experience(cfg, prompt, " -> ".join(tool_seq)))
                 if recipe:
@@ -1544,7 +1875,13 @@ def _agent_thread(run_id, prompt, serial, cfg):
                                     "image": None}))
             except Exception as e:
                 _log.warning(f"经验保存异常: {e}")
-        q.put(("done", {"answer": answer, "usage": usage}))
+        with _lock:
+            done_evt = {"answer": answer, "usage": usage, "mode": mode}
+            if designer:
+                done_evt["draft"] = _run.get("draft")
+                done_evt["warnings"] = _run.get("warnings") or []
+                done_evt["draft_error"] = _run.get("draft_error") or ""
+        q.put(("done", done_evt))
     except Exception as e:
         _log.warning(f"Agent 运行异常: {e}")
         # 诊断：打印消息结构（tool_calls 与 tool 消息配对检查）
@@ -1567,6 +1904,10 @@ def _agent_thread(run_id, prompt, serial, cfg):
                 pass
         q.put(("error", {"message": str(e)[:200]}))
     finally:
-        q.put(None)   # 关闭 SSE
+        # 关闭 SSE：扇出把终止哨兵发给**每个**订阅者
+        if isinstance(q, _Fanout):
+            q.close()
+        else:
+            q.put(None)
         _queues.pop(run_id, None)
         _stop_events.pop(run_id, None)

web/apks_api.py

@@ -17,8 +17,12 @@ bp = Blueprint("apks", __name__)
 @bp.route("/api/apks")
 @login_required
 def api_apks_list():
-    """列出所有已上传的 APK。"""
+    """列出已上传的 APK —— **按包名合并，一个应用一行（最新版本）**。
-    return jsonify({"ok": True, "apks": context.apk_mgr.list_all()})
+
+    同一个应用传过 v1.2 / v1.3 时不再并排显示两行；每行带 versions
+    （全部版本）与 version_count，界面可提示"另有 N 个旧版本"并按需清理。
+    """
+    return jsonify({"ok": True, "apks": context.apk_mgr.list_latest()})
 
 @bp.route("/api/apks/upload", methods=["POST"])
 @perm_required(PERM_APKS)
@@ -36,8 +40,19 @@ def api_apks_upload():
 @bp.route("/api/apks/<apk_id>", methods=["DELETE"])
 @perm_required(PERM_APKS)
 def api_apks_delete(apk_id):
-    """删除 APK 文件和记录。"""
+    """删除 APK。
-    ok, msg = context.apk_mgr.delete(apk_id)
+
+    默认只删这一个版本（列表里一行 = 一个应用，所以界面通常传 scope）：
+      ?scope=package → 删掉**这个应用的所有版本**
+      ?scope=older   → 只清理**旧版本**，保留最新那版
+    不带 scope 时保持老行为（单条删除），给脚本/外部调用留兼容。
+    """
+    scope = (request.args.get("scope") or "").strip()
+    if scope in ("package", "older"):
+        ok, msg = context.apk_mgr.delete_package(
+            apk_id, keep_latest=(scope == "older"))
+    else:
+        ok, msg = context.apk_mgr.delete(apk_id)
     if ok:
         return jsonify({"ok": True, "msg": msg})
     return jsonify({"ok": False, "error": msg}), 400
@@ -50,21 +65,33 @@ def api_apks_install_devices():
     source: pool=设备池 / usb=本机有线 adb / adb=本机网络 adb。
     """
     devices, seen = [], set()
+    name_by_serial, name_by_fp = {}, {}
     try:
         online = set(device_pool.list_online())
-        for serial in device_pool.list_configured():
+        # list_devices() 返回字典（含 name/fingerprint）；list_configured() 只有 serial 字符串
-            if serial in online:
+        for d in device_pool.list_devices():
-                devices.append({"serial": serial, "model": "", "source": "pool"})
+            serial = d.get("serial")
+            if serial in online and serial not in seen:
+                devices.append({"serial": serial, "model": "",
+                                "name": d.get("name") or "", "source": "pool"})
                 seen.add(serial)
-    except Exception:
+            if serial:
-        pass
+                name_by_serial[serial] = d.get("name") or ""
+            # USB 设备的 adb serial == ro.serialno == 池里那条网络记录的指纹，
+            # 靠指纹才认得出是同一台（否则插着 USB 时会冒出一个没名字的裸序列号）
+            if d.get("fingerprint"):
+                name_by_fp[d["fingerprint"]] = d.get("name") or ""
+    except Exception as e:
+        _log.warning("读取设备名失败（列表将只显示地址）: %s", e)
     out = _adb("devices")
     for line in (out or "").splitlines()[1:]:
         parts = line.split()
         if len(parts) >= 2 and parts[0] and parts[0] not in seen:
-            devices.append({"serial": parts[0], "model": "",
+            s = parts[0]
-                            "source": "usb" if ":" not in parts[0] else "adb"})
+            devices.append({"serial": s, "model": "",
-            seen.add(parts[0])
+                            "name": name_by_serial.get(s) or name_by_fp.get(s) or "",
+                            "source": "usb" if ":" not in s else "adb"})
+            seen.add(s)
     return jsonify({"ok": True, "devices": devices})
 
 @bp.route("/api/apks/install", methods=["POST"])

web/auth.py

@@ -144,6 +144,11 @@ def login():
             login_user(user)
             _csrf_token()  # 建立 CSRF token，前端通过 /api/csrf 获取
             _log.info(f"用户 {username} 登录")
+            try:
+                from core import notifier
+                notifier.notify("user.login", username=username)
+            except Exception:
+                pass
             return redirect(request.args.get("next") or url_for("auth.index"))
         return render_template("admin/login.html", error="用户名或密码错误")
     return render_template("admin/login.html", error=None)

web/common.py

@@ -7,10 +7,12 @@ _log = get_logger("web")
 
 
 def _merged_device_list():
-    """本地 adb（含 USB）+ 设备池的合并列表（[{serial, state}]）。
+    """本地 adb（含 USB）+ 设备池的合并列表（[{serial, name, state}]）。
 
     供维护终端/剪贴板注入/应用版本管理等设备选择场景共用。
     状态：device/offline=本机 adb 实际状态；pool=设备池已配置但本机未连接。
+    name 来自设备池（平台给设备起的名字，如 A08）—— 界面上统一按「名称 · 地址」
+    显示，同型号多台时才分得清是哪一台；池里没有的设备 name 为空，界面回退显示地址。
     """
     states = {}
     out = _adb("devices")
@@ -18,13 +20,30 @@ def _merged_device_list():
         parts = line.split()
         if len(parts) >= 2 and parts[0] and not parts[0].startswith("*"):
             states[parts[0]] = parts[1]
+    # 注意用的是 list_devices()（**字典**，含 name/fingerprint）；
+    # list_configured() 只返回 serial 字符串列表，别拿它当字典用（实测踩过：.get 抛异常
+    # 被 except 吞掉 → 名字全空）
+    names, fp_names = {}, {}
+    try:
+        for d in device_pool.list_devices():
+            if d.get("serial"):
+                names[d["serial"]] = d.get("name") or ""
+            # USB 设备在 adb 里的 serial 就是 ro.serialno，等于池里那条网络记录的
+            # **指纹** —— 插着 USB 时会以另一个 serial 出现，靠指纹才认得出是同一台，
+            # 否则界面上会冒出一个没名字的裸序列号（实测踩过）
+            if d.get("fingerprint"):
+                fp_names[d["fingerprint"]] = d.get("name") or ""
+    except Exception as e:
+        import logging
+        logging.getLogger("web").warning(f"读取设备名失败: {e}")
     try:
         for serial in device_pool.list_configured():
             if serial not in states:
                 states[serial] = "pool"
     except Exception:
         pass
-    return [{"serial": s, "state": st} for s, st in sorted(states.items())]
+    return [{"serial": s, "name": names.get(s) or fp_names.get(s) or "", "state": st}
+            for s, st in sorted(states.items())]
 
 
 def _device_screen_state(serial):

web/device_agent_api.py

@@ -0,0 +1,384 @@
+"""设备端 Agent 专用接口（设备主动来取，**不走登录会话**，靠设备令牌鉴权）。
+
+用途：设备上装的聚合 Agent（剪贴板注入 / 身份显示 / 应用商店）用这组接口
+自报身份、拉可安装的应用清单、下载 APK、回报安装结果。
+
+为什么另开一组接口而不是复用管理端 API：
+  * 设备登录不了后台会话，也不该拿 admin 的凭据；
+  * 平台 → 设备的**指令**仍然走 adb（`am start`），这组接口只解决
+    「设备主动来取东西」这一半，边界清楚。
+
+安全设计（这组接口是平台唯一对设备开放的面）：
+  1. **默认关闭**：`app_meta.agent_store_enabled != "1"` 时统一返回 404，
+     不暴露接口是否存在；
+  2. 必须带 `X-Device-Token`，与 `app_meta.agent_device_token` **常量时间**比对；
+  3. 只暴露 APK 元数据与文件本身 —— 不返回任何配置、密钥、设备凭据；
+  4. 令牌可一键重置（重置后旧令牌立即失效）。
+
+管理端接口在文件后半段（`/api/agent-store/*`，走正常登录 + 权限）。
+"""
+import hmac
+import os
+import secrets
+import time
+
+from flask import Blueprint, jsonify, request, send_file
+
+from config import APK_DIR
+from core import device_pool
+from core.db_config import meta_get, meta_set
+from core.logger import get_logger
+from web.auth import PERM_APKS, PERM_DEVICES, perm_required
+
+bp = Blueprint("device_agent", __name__)
+_log = get_logger("web.devagent")
+
+# app_meta 键
+_K_ENABLED = "agent_store_enabled"      # "1" 开启；默认关
+_K_TOKEN = "agent_device_token"         # 设备令牌（首次开启时生成）
+_K_CREATED = "agent_device_token_at"    # 令牌生成/重置时间
+
+_API_VERSION = 1                        # 本组接口的版本（契约里写死给 agent 对照）
+_MAX_LOG = 500                          # 记录表最多保留条数（超了删最旧）
+
+
+# ================== 公共：开关与令牌 ==================
+def store_enabled():
+    return (meta_get(_K_ENABLED) or "0") == "1"
+
+
+def get_token():
+    return meta_get(_K_TOKEN) or ""
+
+
+def ensure_token(regenerate=False):
+    """取设备令牌，没有（或要求重置）就生成一个。"""
+    tok = get_token()
+    if regenerate or not tok:
+        tok = secrets.token_urlsafe(24)
+        meta_set(_K_TOKEN, tok)
+        meta_set(_K_CREATED, time.strftime("%Y-%m-%d %H:%M:%S"))
+        _log.info("设备端商店令牌已%s", "重置" if regenerate else "生成")
+    return tok
+
+
+def _deny():
+    """统一拒绝：功能关着就 404（不暴露存在性），令牌不对 401。"""
+    if not store_enabled():
+        return jsonify({"ok": False, "error": "not found"}), 404
+    tok = request.headers.get("X-Device-Token", "") or ""
+    real = get_token()
+    if not real or not tok or not hmac.compare_digest(tok, real):
+        _log.warning("设备端接口鉴权失败（来源 %s）", request.remote_addr)
+        return jsonify({"ok": False, "error": "unauthorized"}), 401
+    return None
+
+
+def _identify():
+    """从请求头识别是哪台设备：指纹优先（换过 IP 也认得出），其次序列号。"""
+    fp = (request.headers.get("X-Device-Fingerprint", "") or "").strip()
+    serial = (request.headers.get("X-Device-Serial", "") or "").strip()
+    name = ""
+    try:
+        if fp:
+            # 注意：find_by_fingerprint / list_configured 返回的都是 dict（不是 ORM 对象）
+            d = device_pool.find_by_fingerprint(fp)
+            if d:
+                return fp, d.get("serial", serial), d.get("name") or "", True
+        if serial:
+            for d in device_pool.list_devices():      # 返回字典（list_configured 只有 serial）
+                if d.get("serial") == serial:
+                    return fp, serial, d.get("name") or "", True
+    except Exception as e:
+        _log.warning("识别设备失败: %s", e)
+    return fp, serial, name, False
+
+
+# ================== 设备侧接口 ==================
+@bp.route("/api/device/agent/bootstrap")
+def api_dev_agent_bootstrap():
+    """设备开机/定时来拉：我是谁 + 有哪些应用可以装。
+
+    请求头：`X-Device-Token`（必带）、`X-Device-Fingerprint`、`X-Device-Serial`
+    响应：设备身份（平台分配的名称）+ 应用清单（含下载地址）
+    """
+    deny = _deny()
+    if deny:
+        return deny
+    fp, serial, name, known = _identify()
+
+    from web import context
+    apks = []
+    try:
+        # 用「按包名合并」的列表：同一个应用只出现一行（最新版），
+        # 设备上不会看到同一个 App 的 v1.2 / v1.3 两行
+        for a in context.apk_mgr.list_latest():
+            apks.append({
+                "id": a.get("id", ""),
+                "display_name": a.get("display_name") or a.get("filename") or "",
+                "package_name": a.get("package_name") or "",
+                "version_name": a.get("version_name") or "",
+                "version_code": a.get("version_code") or 0,
+                "size": a.get("size") or 0,
+                "upload_time": a.get("upload_time") or "",
+                "download_path": "/api/device/agent/apk/{}".format(a.get("id", "")),
+            })
+    except Exception as e:
+        _log.error("设备端拉取应用清单失败: %s", e)
+        return jsonify({"ok": False, "error": "清单读取失败"}), 500
+
+    _log.info("设备端拉清单: %s(%s) 应用 %d 个", name or "未登记", serial or fp, len(apks))
+    return jsonify({
+        "ok": True,
+        "agent_api_version": _API_VERSION,
+        "server_time": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "platform": {
+            # 用请求里的 Host 回填，设备按自己实际能连通的地址访问
+            "url": request.host_url.rstrip("/"),
+        },
+        "device": {"fingerprint": fp, "serial": serial,
+                   "name": name, "known": known},
+        "apks": apks,
+    })
+
+
+@bp.route("/api/device/agent/apk/<apk_id>")
+def api_dev_agent_apk(apk_id):
+    """下载 APK 文件（设备自己拉，比 adb push 快且可并行）。"""
+    deny = _deny()
+    if deny:
+        return deny
+    from core.models import ApkFile
+
+    row = ApkFile.query.get(apk_id)
+    if not row:
+        return jsonify({"ok": False, "error": "apk not found"}), 404
+    path = os.path.join(APK_DIR, row.filename or (apk_id + ".apk"))
+    fname = row.display_name or row.filename or apk_id
+
+    if not os.path.exists(path):
+        return jsonify({"ok": False, "error": "apk file missing"}), 404
+    _log.info("设备端下载 APK: %s", apk_id)
+    return send_file(path, as_attachment=True,
+                     download_name="{}.apk".format(fname),
+                     mimetype="application/vnd.android.package-archive")
+
+
+@bp.route("/api/device/agent/install", methods=["POST"])
+def api_dev_agent_install():
+    """设备请求**平台**帮它装这个应用（平台走 adb，静默，没有系统安装框）。
+
+    为什么这么设计：普通 App 自己调系统安装器，MIUI 上要过「继续 → 勾选未检测
+    → 继续更新」甚至 ICP 备案检查好几步；而 `adb install` 在同一台设备上实测是
+    **静默**的（升级 2.7s、全新安装 7.9s，零弹框）。
+
+    所以设备端商店的「安装/更新」按钮走这里：**用户还是在手机上选**（应用商店体验），
+    真正干活的是平台，几秒钟装完。万一 adb 被 MIUI 拦了，返回 ok=false，
+    设备端自己退回本地安装（有弹框，但至少能装）。
+    """
+    deny = _deny()
+    if deny:
+        return deny
+    data = request.json or {}
+    apk_id = str(data.get("apk_id", ""))
+    if not apk_id:
+        return jsonify({"ok": False, "error": "缺少 apk_id"}), 400
+
+    fp, serial, name, known = _identify()
+    if not serial:
+        return jsonify({"ok": False, "error": "无法识别设备"}), 400
+    if not known:
+        return jsonify({"ok": False, "error": "这台设备还没登记进平台设备池"}), 409
+
+    from core.models import ApkFile
+    if not ApkFile.query.get(apk_id):
+        return jsonify({"ok": False, "error": "apk not found"}), 404
+
+    from web import context
+    try:
+        ok, msg = context.apk_mgr.install(apk_id, [serial])
+    except Exception as e:
+        _log.error("设备端请求安装失败: %s", e)
+        return jsonify({"ok": False, "error": "平台安装任务启动失败"}), 500
+    _log.info("设备端请求安装: %s(%s) apk=%s -> %s", name or "未登记", serial, apk_id, msg)
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 400
+    return jsonify({"ok": True, "msg": msg, "serial": serial})
+
+
+@bp.route("/api/device/agent/report", methods=["POST"])
+def api_dev_agent_report():
+    """设备上报下载/安装结果，平台侧留下记录（应用管理页可见）。
+
+    请求体：{apk_id, action: download|install_ok|install_fail,
+            package_name?, version_name?, message?, serial?}
+    """
+    deny = _deny()
+    if deny:
+        return deny
+    data = request.json or {}
+    action = str(data.get("action", ""))[:20]
+    if action not in ("download", "install_ok", "install_fail"):
+        return jsonify({"ok": False, "error": "action 非法"}), 400
+    fp, serial, name, _known = _identify()
+    if data.get("serial"):
+        serial = str(data["serial"])[:120]
+
+    from core.models import DeviceInstallLog, db
+    try:
+        db.session.add(DeviceInstallLog(
+            fingerprint=fp, serial=serial, device_name=name,
+            apk_id=str(data.get("apk_id", ""))[:32],
+            package_name=str(data.get("package_name", ""))[:200],
+            version_name=str(data.get("version_name", ""))[:50],
+            action=action,
+            message=str(data.get("message", ""))[:500],
+            created_at=time.strftime("%Y-%m-%d %H:%M:%S")))
+        db.session.commit()
+        _prune_logs()
+    except Exception as e:
+        db.session.rollback()
+        _log.error("设备端安装记录写入失败: %s", e)
+        return jsonify({"ok": False, "error": "记录失败"}), 500
+    _log.info("设备端上报: %s(%s) %s %s %s", name or "未登记", serial or fp,
+              action, data.get("apk_id", ""), data.get("message", ""))
+    return jsonify({"ok": True})
+
+
+def _prune_logs(keep=_MAX_LOG):
+    """记录表只留最近 N 条（失败忽略，不影响上报）。"""
+    try:
+        from core.models import DeviceInstallLog, db
+        n = db.session.query(DeviceInstallLog).count()
+        if n <= keep:
+            return
+        old = (db.session.query(DeviceInstallLog.id)
+               .order_by(DeviceInstallLog.id).limit(n - keep).all())
+        if old:
+            db.session.query(DeviceInstallLog).filter(
+                DeviceInstallLog.id.in_([r[0] for r in old])).delete(
+                synchronize_session=False)
+            db.session.commit()
+    except Exception as e:
+        _log.warning("清理设备端安装记录失败: %s", e)
+
+
+# ================== 管理端接口（登录 + 权限）==================
+@bp.route("/api/agent/show-info", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_agent_show_info():
+    """让设备上的 Agent 打开「身份大字页」（监控页那个按钮调它）。
+
+    替代原来那套「推 HTML 让设备浏览器打开定位页」——那套在 MIUI 上要装浏览器、
+    页面还依赖设备能访问平台；Agent 是常驻 App，一条 `am start` 就出画面。
+
+    请求：{"serial": "…", "close": false}
+    返回：{ok, msg}；设备没装 Agent 时明确报出来（不静默失败）
+    """
+    from core.adb_helper import _adb
+
+    data = request.json or {}
+    serial = (data.get("serial") or "").strip()
+    close = bool(data.get("close"))
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+
+    if close:
+        args = ["--es", "close", "1"]
+    else:
+        # 设备信息：名称/IP/平台地址 —— Agent 用它们显示大字页
+        name, ip = "", ""
+        ip = serial.split(":")[0] if ":" in serial else ""
+        for d in device_pool.list_devices():      # 字典列表（list_configured 只有 serial）
+            if d.get("serial") == serial:
+                name = d.get("name") or ""
+                break
+        if not name:
+            # USB 设备的 serial 就是指纹：池里那条记录的 serial 是网络地址，
+            # 靠指纹才认得出来（否则大字页标题会显示一串裸序列号）
+            for d in device_pool.list_devices():
+                if d.get("fingerprint") and d["fingerprint"] == serial:
+                    name = d.get("name") or ""
+                    break
+        if not ip:
+            # USB 设备：平台不知道它的 IP，现问一下设备（只读命令，不影响设备）
+            out = _adb("-s", serial, "shell", "ip", "-4", "addr", "show", "wlan0")
+            import re as _re
+            m = _re.search(r"inet\s+(\d+\.\d+\.\d+\.\d+)", out or "")
+            ip = m.group(1) if m else ""
+        # 平台地址：用操作者当前访问的地址；如果是 localhost，设备根本连不上 →
+        # 换成局域网地址（设备上显示 127.0.0.1 毫无意义）
+        server = request.host_url.rstrip("/")
+        if "127.0.0.1" in server or "localhost" in server:
+            from web.devices_api import _lan_ip
+            server = "http://%s:18050" % _lan_ip()
+        args = ["--es", "name", name or serial.split(":")[0],
+                "--es", "serial", serial,
+                "--es", "server", server]
+        if ip:
+            args += ["--es", "ip", ip]
+
+    # 先点亮屏幕、解除锁屏：设备息屏时 am start 会把大字页开在锁屏**后面**，
+    # 人看到的还是一片黑（实测踩过）——这正是原来"定位"按钮里的"点亮屏幕"那一步
+    if not close:
+        try:
+            _adb("-s", serial, "shell", "input", "keyevent", "KEYCODE_WAKEUP")
+            _adb("-s", serial, "shell", "wm", "dismiss-keyguard")
+        except Exception as e:
+            _log.warning("点亮屏幕失败（不影响显示身份页）: %s", e)
+
+    try:
+        out = _adb("-s", serial, "shell", "am", "start", "-n",
+                   "com.example.deviceagent/.InfoActivity", *args) or ""
+    except Exception as e:
+        return jsonify({"ok": False, "error": f"adb 执行失败: {e}"}), 500
+
+    low = out.lower()
+    if "unable to resolve intent" in low or "does not exist" in low or "error" in low:
+        return jsonify({"ok": False,
+                        "error": "这台设备没装设备 Agent（com.example.deviceagent）——"
+                                 "可以从「应用管理 → 设备端应用商店」装，或用扫码配置"}), 400
+    _log.info("设备端 Agent %s: %s", "关闭身份页" if close else "打开身份页", serial)
+    return jsonify({"ok": True, "msg": "已关闭" if close else "已让设备显示身份信息"})
+
+
+@bp.route("/api/agent-store/config", methods=["GET", "POST"])
+@perm_required(PERM_APKS)
+def api_agent_store_config():
+    """查看/修改设备端商店配置（应用管理页）。GET 也要权限：令牌属于敏感信息。"""
+    if request.method == "GET":
+        return jsonify({
+            "ok": True,
+            "enabled": store_enabled(),
+            "token": get_token(),
+            "token_created_at": meta_get(_K_CREATED) or "",
+            "api_version": _API_VERSION,
+            "base_url_hint": request.host_url.rstrip("/"),
+        })
+
+    data = request.json or {}
+    if "enabled" in data:
+        meta_set(_K_ENABLED, "1" if data["enabled"] else "0")
+        if data["enabled"]:
+            ensure_token()
+    if data.get("regenerate_token"):
+        ensure_token(regenerate=True)
+    _log.info("设备端商店配置更新: enabled=%s", store_enabled())
+    return jsonify({"ok": True, "enabled": store_enabled(), "token": get_token()})
+
+
+@bp.route("/api/agent-store/logs")
+@perm_required(PERM_APKS)
+def api_agent_store_logs():
+    """设备端安装记录（最近 N 条）。"""
+    limit = min(int(request.args.get("limit", 50) or 50), 200)
+    from core.models import DeviceInstallLog
+    rows = (DeviceInstallLog.query
+            .order_by(DeviceInstallLog.id.desc()).limit(limit).all())
+    return jsonify({"ok": True, "logs": [{
+        "id": r.id, "device_name": r.device_name or "", "serial": r.serial or "",
+        "fingerprint": r.fingerprint or "", "apk_id": r.apk_id or "",
+        "package_name": r.package_name or "", "version_name": r.version_name or "",
+        "action": r.action or "", "message": r.message or "",
+        "created_at": r.created_at or "",
+    } for r in rows]})

web/devices_api.py

@@ -12,6 +12,100 @@ from web.auth import perm_required, PERM_DEVICES
 _log = get_logger("web")
 bp = Blueprint("devices", __name__)
 
+
+def _lan_ip():
+    """挑一个手机连得上的本机地址：优先 192.168.x，其次 10.x。
+
+    不能用 gethostbyname(hostname) —— 这台机器上它可能返回 Tailscale 的
+    100.x（CGNAT 地址，手机不在 tailnet 里根本连不上），或 docker 的 172.17。
+    """
+    import socket
+    candidates = []
+    try:
+        for info in socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET):
+            ip = info[4][0]
+            if ip.startswith("127.") or ip.startswith("169.254."):
+                continue
+            candidates.append(ip)
+    except Exception:
+        pass
+    for ip in candidates:
+        if ip.startswith("192.168."):
+            return ip
+    for ip in candidates:
+        if ip.startswith("10."):
+            return ip
+    return candidates[0] if candidates else "本机IP"
+
+
+@bp.route("/api/devices/qrcode")
+@perm_required(PERM_DEVICES)
+def api_devices_qrcode():
+    """给某台设备生成「配置二维码」——设备端 Agent 扫一下就把自己配好。
+
+    二维码里是一段 JSON（平台地址 + 设备令牌 + 这台设备的指纹），扫码即完成：
+    填 server/token/指纹 三件事，不用在手机上打字，也不用连 adb。
+
+    ⚠️ 两条使用前提（都会在返回里给提示，不静默失败）：
+      1. 平台要先在「应用管理 → 设备端应用商店」启用（令牌是从那儿来的）
+      2. **要用局域网地址打开本页面**（二维码里的地址取自当前访问地址；
+         如果你是用 localhost 打开的，手机会连不上，这里会明确告诉你）
+    """
+    import base64
+    import io
+    import json as _json
+
+    serial = (request.args.get("serial") or "").strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+
+    dev = None
+    for d in device_pool.list_devices():
+        if d.get("serial") == serial:
+            dev = d
+            break
+    if dev is None:
+        return jsonify({"ok": False, "error": "设备不在池里"}), 404
+
+    # 令牌必须先启用设备端商店才有
+    from core.db_config import meta_get
+    from web.device_agent_api import store_enabled, ensure_token
+    if not store_enabled():
+        return jsonify({"ok": False,
+                        "error": "还没启用设备端商店：先到「应用管理 → 设备端应用商店」勾选启用"}), 400
+    token = ensure_token()
+
+    server = request.host_url.rstrip("/")
+    warn = ""
+    if "127.0.0.1" in server or "localhost" in server:
+        warn = ("你现在是用本机地址打开平台的，二维码里的地址手机会连不上 —— "
+                "请改用局域网地址（如 http://%s:18050）重新打开本页再生成。"
+                % _lan_ip())
+
+    fp = dev.get("fingerprint") or ""
+    if not fp:
+        warn = (warn + " " if warn else "") + \
+            "这台设备还没采集到指纹，扫码后平台认不出它是哪一台（设备端会显示「未登记」）；" \
+            "建议先让它在线并刷新一次型号/指纹，再生成二维码。"
+
+    payload = {"v": 1, "server": server, "token": token,
+               "fingerprint": fp, "name": dev.get("name") or ""}
+    text = _json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+    try:
+        import qrcode
+        img = qrcode.make(text)
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        png = "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
+    except Exception as e:
+        _log.error(f"生成二维码失败: {e}")
+        return jsonify({"ok": False, "error": f"生成二维码失败: {e}"}), 500
+
+    _log.info(f"生成设备配置二维码: {dev.get('name') or serial}")
+    return jsonify({"ok": True, "serial": serial, "name": dev.get("name") or "",
+                    "fingerprint": fp, "png": png, "payload": text, "warn": warn})
+
 @bp.route("/api/devices/pool", methods=["GET"])
 @perm_required(PERM_DEVICES)
 def api_devices_pool_list():

web/monitor.py

@@ -102,6 +102,11 @@ def api_status():
     devices, err = context.mgr.get_status()
     if err:
         return jsonify({"ok": False, "error": err}), 500
+    # 按**名称**排（A01/A02/…）——之前是 adb 返回的顺序，看着像按 IP 排，很别扭。
+    # 没名字的排在最后、彼此按地址排（历史数据里可能有没命名的设备）。
+    devices.sort(key=lambda d: (
+        1 if not (d.get("device_name") or "").strip() else 0,
+        (d.get("device_name") or "").strip() or d.get("serial", "")))
     return jsonify({
         "ok": True, "devices": devices, "server_time": time.time(),
         "fg_scanning": context.mgr._fg_scanner.is_scanning,
@@ -234,8 +239,11 @@ def api_device_screen_all():
             if ":" in serial:
                 adb_connect(serial)
             if mode == "off":
-                subprocess.run([ADB_PATH, "-s", serial, "shell", "input", "keyevent", "26"],
+                # KEYCODE_SLEEP(223) 是**单向**熄屏；不能用 KEYCODE_POWER(26)——
-                               capture_output=True, timeout=15)  # KEYCODE_POWER 息屏
+                # 那是电源键**开关**，对已经息屏的设备会把屏幕点亮（2026-09-14 用户反馈：
+                # "一键息屏"把睡着的设备唤醒了，看着像按钮反了）
+                subprocess.run([ADB_PATH, "-s", serial, "shell", "input", "keyevent", "223"],
+                               capture_output=True, timeout=15)
             else:
                 subprocess.run([ADB_PATH, "-s", serial, "shell", "input", "keyevent", "224"],
                                capture_output=True, timeout=15)  # WAKEUP

web/notify_api.py

@@ -0,0 +1,190 @@
+"""通知 / Webhook 管理接口（系统级设置，全部 admin_required）。
+
+配置读写统一走 `core/notifier`（它落 `app_meta.notify_webhooks` 一个键）——本模块
+只做"取配置 → 改一处 → 存回去"的编排，**校验与持久化都在 notifier 里**，不在 web 层
+重复实现（避免两份规则漂移）。
+
+安全口径：
+- URL 里有凭据（企微 `?key=`）→ 回显一律 `notifier.mask_url()`；
+- 前端"留空不修改"：提交上来的 url 若是打码值或空，`save_config` 会保留原值；
+- `secret` 永不回显，只回 `secret_set`。
+"""
+import uuid
+
+from flask import Blueprint, jsonify, request
+from flask_login import current_user
+
+from core import notify_events, notifier
+from core.logger import get_logger
+from web.auth import admin_required
+
+_log = get_logger("web.notify")
+bp = Blueprint("notify", __name__)
+
+
+def _operator():
+    try:
+        return current_user.username or "admin"
+    except Exception:
+        return "admin"
+
+
+def _formats():
+    """可用格式（含未实现的，前端据此置灰）。
+
+    每项带**该格式自己的提示文案**（URL 占位/说明、密钥标签、限流说明）——
+    这些必须跟着格式走，不能把企业微信的说明写死在页面上。
+    """
+    out = [cls.meta() for _, cls in notifier.ADAPTERS.items()]
+    for name, label in notifier.PLANNED_FORMATS.items():
+        out.append({"name": name, "label": label + "（未实现）", "implemented": False,
+                    "byte_limit": 0, "limit_default": 20, "needs_template": False,
+                    "secret_label": "签名密钥（可选）", "secret_help": "",
+                    "url_hint": "", "url_help": "该格式尚未实现，可先用「通用 JSON」手搓",
+                    "limit_help": ""})
+    return out
+
+
+@bp.route("/api/notify/webhooks")
+@admin_required
+def api_notify_webhooks():
+    """全部 webhook 配置（url 打码、secret 只回是否配置过）+ 格式清单 + 事件目录。"""
+    cfg = notifier.get_public_config()
+    return jsonify({"ok": True, "webhooks": cfg["webhooks"], "settings": cfg["settings"],
+                    "formats": _formats(), "meta_key": notifier.META_KEY,
+                    "max_hooks": notifier.MAX_HOOKS,
+                    "planned": list(notifier.PLANNED_FORMATS)})
+
+
+@bp.route("/api/notify/webhooks", methods=["POST"])
+@admin_required
+def api_notify_webhook_create():
+    """新建一条 webhook。body 即该条配置（见 doc/NOTIFY.md 的字段表）。"""
+    data = request.json or {}
+    cfg = notifier.get_config()
+    if len(cfg["webhooks"]) >= notifier.MAX_HOOKS:
+        return jsonify({"ok": False, "error": f"最多 {notifier.MAX_HOOKS} 条"}), 400
+    new_id = "wh_" + uuid.uuid4().hex[:8]
+    hook = dict(data)
+    hook["id"] = new_id
+    cfg["webhooks"].append(hook)
+    ok, msg = notifier.save_config(cfg)
+    if not ok:
+        return jsonify({"ok": False, "error": msg, "errors": msg
+                        if isinstance(msg, list) else None}), 400
+    _log.info("新增通知 webhook: %s（%s）by %s", hook.get("name"), new_id, _operator())
+    return jsonify({"ok": True, "msg": "已创建", "id": new_id})
+
+
+@bp.route("/api/notify/webhooks/<hook_id>", methods=["PUT"])
+@admin_required
+def api_notify_webhook_update(hook_id):
+    """更新一条（部分字段；url/secret 省略或为打码值时保持原值）。"""
+    data = request.json or {}
+    cfg = notifier.get_config()
+    target = next((h for h in cfg["webhooks"] if h["id"] == hook_id), None)
+    if not target:
+        return jsonify({"ok": False, "error": "webhook 不存在"}), 404
+    for k, v in data.items():
+        if k in ("id", "created_at"):
+            continue
+        target[k] = v
+    ok, msg = notifier.save_config(cfg)
+    if not ok:
+        return jsonify({"ok": False, "error": msg, "errors": msg
+                        if isinstance(msg, list) else None}), 400
+    _log.info("更新通知 webhook: %s by %s", hook_id, _operator())
+    return jsonify({"ok": True, "msg": "已保存"})
+
+
+@bp.route("/api/notify/webhooks/<hook_id>", methods=["DELETE"])
+@admin_required
+def api_notify_webhook_delete(hook_id):
+    cfg = notifier.get_config()
+    before = len(cfg["webhooks"])
+    cfg["webhooks"] = [h for h in cfg["webhooks"] if h["id"] != hook_id]
+    if len(cfg["webhooks"]) == before:
+        return jsonify({"ok": False, "error": "webhook 不存在"}), 404
+    ok, msg = notifier.save_config(cfg)
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 400
+    _log.info("删除通知 webhook: %s by %s", hook_id, _operator())
+    return jsonify({"ok": True, "msg": "已删除"})
+
+
+@bp.route("/api/notify/webhooks/<hook_id>/test", methods=["POST"])
+@admin_required
+def api_notify_webhook_test(hook_id):
+    """同步发一条测试消息（用户等结果），返回真实 HTTP 状态与平台错误码。
+
+    ⚠ 不占业务令牌桶：否则管理员点两下测试就把业务通知的配额吃掉了。
+    """
+    cfg = notifier.get_config()
+    hook = next((h for h in cfg["webhooks"] if h["id"] == hook_id), None)
+    if not hook:
+        return jsonify({"ok": False, "error": "webhook 不存在"}), 404
+    event = ((request.json or {}).get("event") or "notify.test").strip()
+    rec = notifier.send_test(hook, event=event, operator=_operator())
+    return jsonify({"ok": bool(rec.get("ok")),
+                    "msg": "测试消息已发出" if rec.get("ok") else "发送失败",
+                    "http_status": rec.get("http_status"),
+                    "errcode": rec.get("errcode"),
+                    "elapsed_ms": rec.get("elapsed_ms"),
+                    "attempts": rec.get("attempts"),
+                    "error": rec.get("error") or "",
+                    "url": notifier.mask_url(hook.get("url", ""))})
+
+
+@bp.route("/api/notify/preview", methods=["POST"])
+@admin_required
+def api_notify_preview():
+    """保存前预览：真实请求体 + UTF-8 字节数 + 是否会被截断。"""
+    data = request.json or {}
+    hook = data.get("hook") or {}
+    # 预览时 URL 可能还没填：给个占位，只关心渲染结果
+    hook = dict(hook)
+    hook.setdefault("url", "https://example.invalid/hook")
+    out = notifier.preview(hook, event=(data.get("event") or "notify.test"))
+    return jsonify({"ok": not out.get("error"), **out})
+
+
+@bp.route("/api/notify/events")
+@admin_required
+def api_notify_events():
+    """事件目录（前端画勾选树 / 模板占位符速查）。"""
+    rows = notify_events.list_events()
+    cats = []
+    for e in rows:
+        if e["category"] not in cats:
+            cats.append(e["category"])
+    return jsonify({"ok": True, "events": rows, "categories": cats})
+
+
+@bp.route("/api/notify/logs")
+@admin_required
+def api_notify_logs():
+    """最近发送记录（内存环形缓冲，重启清空；历史见 logs/notify.log）。"""
+    limit = request.args.get("limit", 50)
+    try:
+        limit = max(1, min(int(limit), 200))
+    except (TypeError, ValueError):
+        limit = 50
+    return jsonify({"ok": True, "logs": notifier.get_logs(limit),
+                    "note": "仅显示本次运行期间记录；历史见 logs/notify.log"})
+
+
+@bp.route("/api/notify/settings", methods=["POST"])
+@admin_required
+def api_notify_settings():
+    """全局设置：global_enabled / default_agg_window / default_rate_limit / log_keep。"""
+    data = request.json or {}
+    cfg = notifier.get_config()
+    for k in ("global_enabled", "default_agg_window", "default_rate_limit",
+              "log_keep", "http_timeout"):
+        if k in data and data[k] is not None:
+            cfg["settings"][k] = data[k]
+    ok, msg = notifier.save_config(cfg)
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 400
+    _log.info("更新通知全局设置 by %s: %s", _operator(), data)
+    return jsonify({"ok": True, "msg": "已保存"})

web/system_api.py

@@ -9,6 +9,7 @@
 from io import BytesIO
 
 from flask import Blueprint, jsonify, request, send_file
+from flask_login import current_user
 
 from web.auth import admin_required
 from core import system_backup as sb
@@ -39,6 +40,14 @@ def api_system_backup_export():
     with open(zip_path, "rb") as f:
         data = f.read()
     sb.remove_quiet(zip_path)
+    try:
+        from core import notifier
+        notifier.notify("system.backup.exported", filename=fname, size=len(data),
+                        tables=len(manifest.get("tables") or []),
+                        include_apk=include_apk,
+                        user=getattr(current_user, "username", ""))
+    except Exception:
+        pass          # 通知失败不影响导出
     resp = send_file(BytesIO(data), as_attachment=True, download_name=fname,
                      mimetype="application/zip")
     return resp
@@ -66,10 +75,16 @@ def api_system_backup_preview():
 @bp.route("/api/system/backup/apply", methods=["POST"])
 @admin_required
 def api_system_backup_apply():
-    """确认应用导入：自动备份当前库 → 落待生效恢复任务（重启后生效）。"""
+    """确认应用导入：自动备份当前库 → 落待生效恢复任务（重启后生效）。
-    token = (request.json or {}).get("token", "")
+
+    force_env_mismatch 默认 False：备份来源环境与当前库环境不符时拒绝导入，
+    要跨环境（如把生产数据导进 dev 库）必须显式传 true。
+    """
+    body = request.json or {}
+    token = body.get("token", "")
+    force = bool(body.get("force_env_mismatch", False))
     try:
-        res = sb.apply_restore(str(token).strip())
+        res = sb.apply_restore(str(token).strip(), force_env_mismatch=force)
     except sb.BackupError as e:
         return jsonify({"ok": False, "error": str(e)}), 400
     except Exception as e:

web/tasks_api.py

@@ -7,9 +7,9 @@ from datetime import datetime
 from concurrent.futures import ThreadPoolExecutor, as_completed, TimeoutError as FuturesTimeout
 
 from flask import (Blueprint, jsonify, request, Response)
-from flask_login import login_required
+from flask_login import login_required, current_user
 
-from core import device_pool, uiauto_helper
+from core import device_pool, uiauto_helper, step_defaults
 from core.adb_helper import adb_connect_light
 from core.models import db, DeviceGroup, TaskJob, CustomAction
 from core.logger import get_logger
@@ -215,6 +215,111 @@ def api_groups_delete(name):
     return jsonify({"ok": False, "error": "分组不存在"}), 404
 
 
+# ================== API：录制手势（手机端真手指轨迹） ==================
+#
+# 用 getevent 读**真触屏**设备抓手指轨迹（见 core/gesture.py）。合成的注入事件不会
+# 出现在真触屏节点上，所以录到的只有人手的动作。
+# 录制器实例存在内存里（单进程；不落库——录完的点列由前端放进步骤/动作再保存）。
+
+_gesture_recorders = {}          # token -> PhoneRecorder
+_gesture_lock = threading.Lock()
+_GESTURE_TTL = 300               # 超过 5 分钟自动收摊，避免忘了点"停止"
+
+
+def _gesture_sweep():
+    """清掉超时的录制器（停止并释放 getevent 进程）。"""
+    now = time.time()
+    with _gesture_lock:
+        stale = [t for t, r in _gesture_recorders.items()
+                 if now - r._started > _GESTURE_TTL]
+        for t in stale:
+            _gesture_recorders.pop(t, None)
+    for t in stale:
+        try:
+            r.stop()
+        except Exception:
+            pass
+        _log.info("录制手势超时自动停止: %s", t)
+
+
+@bp.route("/api/gesture/record/start", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_gesture_record_start():
+    """开始录：{serial} → {token}。之后在手机屏幕上用手指划，停止时取回轨迹。"""
+    from core import gesture
+    _gesture_sweep()
+    serial = ((request.json or {}).get("serial") or "").strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    with _gesture_lock:
+        if _gesture_recorders:
+            return jsonify({"ok": False, "error": "已有录制在进行中，先停止"}), 409
+    try:
+        w, h = 0, 0
+        try:
+            import uiautomator2 as u2
+            from core.u2_helper import screen_size
+            d = u2.connect(serial)
+            d.unlock()                           # 息屏时 u2 抓树会退化到几十秒，先唤醒
+            w, h = screen_size(d, serial)
+        except Exception as e:
+            _log.warning("录制前取屏幕尺寸失败（按原始坐标范围换算）: %s", e)
+        rec = gesture.PhoneRecorder(serial, w, h)
+        rec.start()
+    except Exception as e:
+        return jsonify({"ok": False, "error": f"开始录制失败: {e}"}), 502
+    token = uuid.uuid4().hex[:12]
+    with _gesture_lock:
+        _gesture_recorders[token] = rec
+    _log.info("开始录制手势: %s @ %s（%s）by %s", token, serial, rec.device,
+              getattr(current_user, "username", ""))
+    return jsonify({"ok": True, "token": token, "device": rec.device,
+                    "screen": [w, h],
+                    "msg": "现在请用手指在手机上划，划完点「停止」"})
+
+
+@bp.route("/api/gesture/record/stop", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_gesture_record_stop():
+    """停止录制：{token} → {gestures: [[[x,y,t_ms],...], ...]}。"""
+    token = ((request.json or {}).get("token") or "").strip()
+    with _gesture_lock:
+        rec = _gesture_recorders.pop(token, None)
+    if rec is None:
+        return jsonify({"ok": False, "error": "录制会话不存在或已超时"}), 404
+    try:
+        gestures = rec.stop()
+    except Exception as e:
+        return jsonify({"ok": False, "error": f"停止录制失败: {e}"}), 500
+    _log.info("停止录制手势: %s → %s 条", token, len(gestures))
+    return jsonify({"ok": True, "gestures": gestures, "count": len(gestures),
+                    "device": rec.device})
+
+
+# ================== API：步骤默认值（「动作配置」页） ==================
+#
+# 存 app_meta.step_defaults 一个键（不建表），校验与合并都在 core/step_defaults.py。
+
+@bp.route("/api/step_defaults")
+@login_required
+def api_step_defaults_get():
+    """生效的默认值 + 出厂值 + 字段规格（前端画表单用）。"""
+    return jsonify({"ok": True, **step_defaults.as_payload()})
+
+
+@bp.route("/api/step_defaults", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_step_defaults_save():
+    """保存默认值（只落与出厂值不同的字段，便于以后出厂值升级能跟着走）。"""
+    data = request.json or {}
+    ok, msg = step_defaults.save(data.get("defaults") or data)
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 400
+    _log.info("更新步骤默认值 by %s: %s", getattr(current_user, "username", ""),
+              list((data.get("defaults") or data).keys()))
+    return jsonify({"ok": True, "msg": msg, **step_defaults.as_payload()})
+
+
 # ================== API：用户管理 CRUD ==================
 
 @bp.route("/api/custom_actions")
@@ -358,6 +463,30 @@ def api_uiauto_devices():
         _log.info(f"抓取元素设备列表补全 {added} 台在线设备: {list(seen)}")
     return jsonify({"ok": True, "devices": data})
 
+@bp.route("/api/uiauto/snapshot")
+@perm_required(PERM_DEVICES)
+def api_uiauto_snapshot():
+    """一次取齐：设备截图 + 元素树（**原生 u2，同一个连接背靠背取**）。
+
+    抓取元素时用它代替「/api/uiauto/screenshot + /api/uiauto/elements」两连击：
+    那两条是两次独立取数，中间隔着 dump 本身的 1.3~1.8 秒 —— 界面只要在动
+    （信息流/视频/加载动画），框就会落在旧位置上（"抓取错位"）。
+    同一个连接背靠背取把这个窗口压到最小，并额外用**双截图校验**标出
+    "抓取期间界面在变化"（`unstable`），前端据此明确提示而不是悄悄给错位的框。
+
+    ?serial=xxx
+    → {ok, image(data-url), width, height, elements:[...], unstable, cost_ms}
+    """
+    serial = request.args.get("serial", "")
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    ok, data = uiauto_helper.snapshot(serial)
+    if not ok:
+        # 设备没连上/抓取失败：502（依赖不可用），与 /api/uiauto/elements 一致
+        return jsonify({"ok": False, "error": data}), 502
+    return jsonify({"ok": True, **data})
+
+
 @bp.route("/api/uiauto/screenshot")
 @perm_required(PERM_DEVICES)
 def api_uiauto_screenshot():

web/tools_api.py

@@ -156,6 +156,9 @@ def api_tools_appver():
                 results[d["serial"]] = fut.result()
             except Exception as e:
                 results[d["serial"]] = {"installed": False, "error": str(e)}
+            # 结果里带上设备名：界面按「名称 · 地址」显示，同型号多台才分得清
+            if isinstance(results.get(d["serial"]), dict):
+                results[d["serial"]]["name"] = d.get("name") or ""
     fail = sum(1 for v in results.values() if v.get("error"))
     return jsonify({"ok": True, "results": results, "fail": fail,
                     "total": len(results)})

web_server.py

@@ -33,24 +33,65 @@ if not os.environ.get("WEB_SECRET_KEY"):
 app.config["SECRET_KEY"] = _web_secret
 # debug=False 时模板默认不自动重载，开发期改 HTML 需重启才生效；这里显式开启
 app.config["TEMPLATES_AUTO_RELOAD"] = True
-app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///" + os.path.join(
+# 数据库目标与连接参数统一由 core/db_config 装配（.env 的 DEPLOY_ENV / DB_* 决定）。
-    os.path.dirname(os.path.abspath(__file__)), "data", "users.db")
+# 这里就把配置校验做完：连不上、环境与库名不匹配 → 直接拒绝启动，不要带着错配置跑起来。
+from core import db_config
+try:
+    _DB_URI = db_config.build_db_uri()
+    db_config.check_connection(_DB_URI)
+except db_config.DBConfigError as _e:
+    _log.error("数据库配置校验失败，拒绝启动：\n%s", _e)
+    raise SystemExit(2)
+app.config["SQLALCHEMY_DATABASE_URI"] = _DB_URI
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(_DB_URI)
 app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
 
 login_manager = LoginManager(app)
 login_manager.login_view = "auth.login"  # 蓝图化后路由前缀 auth
 
-# 消费「待生效的备份恢复」：若存在 data/restore_pending/users.db，在 engine 首次
+
-# 打开数据库之前换位。导入必须重启生效——TaskManager 启动时读库入内存，
+def _consume_pending_restore():
-# Windows 无法热替换正被持有的库文件。
+    """消费「待生效的备份恢复」（若存在 data/restore_pending/users.db）。
-try:
+
-    from core.system_backup import consume_pending_restore
+    必须在 init_db 之后调用：现在是「单事务整库替换」而不是换文件，
-    consume_pending_restore()
+    要先有建好的表和 app context。导入仍然要重启才生效——因为 TaskManager /
-except Exception as _e:
+    device_pool 把任务与设备缓存在内存里，整库替换后内存副本全部失效。
-    _log.error(f"消费备份恢复任务异常（不影响启动）: {_e}")
+    """
+    try:
+        from core.system_backup import consume_pending_restore
+        with app.app_context():
+            consume_pending_restore()
+    except Exception as _e:
+        _log.error(f"消费备份恢复任务异常（不影响启动）: {_e}")
 
 # 先初始化数据库（含旧 JSON 迁移），再创建 TaskManager（需要 app context 读写 DB）
 init_db(app)
+# 通知模块：**必须早于 _consume_pending_restore()**——启动期就要能发「备份已恢复」
+# 这类通知（notify 在未就绪时静默丢弃，晚初始化就丢事件了）
+try:
+    from core import notifier as _notifier
+    _notifier.init_app(app)
+except Exception as _e:            # 通知出问题不影响启动
+    _log.warning(f"通知模块初始化失败（不影响启动）: {_e}")
+# 任务步骤明细：起一个专用写线程，任务线程只入队（见 core/step_log.py）
+try:
+    from core import step_log as _step_log
+    _step_log.init_app(app)
+except Exception as _e:
+    _log.warning(f"步骤明细模块初始化失败（不影响启动）: {_e}")
+# 消费「待生效的备份恢复」——必须在 init_db 之后（表已建好，且现在是事务替换而非换文件）
+_consume_pending_restore()
+# 库环境标签校验 + 启动横幅：每次启动都明确写出「现在连的是哪个库」，
+# 避免在不知情的情况下对着生产库操作（app_meta 表要存在，所以放在 init_db 之后）
+try:
+    with app.app_context():          # db.engine / app_meta 读取都需要 app context
+        db_config.verify_deployment_label()
+        db_config.print_banner()
+        # 页面顶部环境徽标（防混库第 4 层：点开任何页面都能看出连的是哪个库）
+        app.jinja_env.globals["db_env"] = db_config.env_badge()
+except db_config.DBConfigError as _e:
+    _log.error("数据库环境校验失败，拒绝启动：\n%s", _e)
+    raise SystemExit(2)
 # 设备池（本地清单 + adb 在线状态）：任务调度的数据源
 from core import device_pool
 device_pool.init_app(app)
@@ -69,6 +110,24 @@ from web.auth import _csrf_protect, _csrf_token
 context.init(mgr, apk_mgr, device_pool)
 register_blueprints(app)
 
+def _purge_step_log():
+    """清理超期的任务步骤明细（启动时 + 每日 04:13）。
+
+    app context 由本函数自建：APScheduler 的作业跑在调度线程里，没有请求上下文。
+    """
+    try:
+        from core.step_log import purge_old
+        with app.app_context():
+            purge_old()
+    except Exception as e:
+        _log.warning(f"步骤明细清理失败（不影响主服务）: {e}")
+
+
+def _purge_step_log_async():
+    """启动时后台清理一次（不阻塞启动；服务若频繁重启，定时任务可能一直轮不到）。"""
+    threading.Thread(target=_purge_step_log, daemon=True).start()
+
+
 # 经验库每日 AI 巡检（凌晨 03:47）：评审标记疑似问题经验，删除只走人工确认。
 # 巡检线程在 run_experience_audit 内自建 app context，不依赖这里。
 try:
@@ -77,6 +136,9 @@ try:
     from web.agent_api import run_experience_audit
     _audit_sched = BackgroundScheduler(timezone="Asia/Shanghai")
     _audit_sched.add_job(run_experience_audit, CronTrigger(hour=3, minute=47))
+    # 步骤明细清理：超过保留期（core/step_log.KEEP_DAYS）的记录每天删一次。
+    # 不清理的话这张表是唯一无界增长的表，会一路顶大备份包。
+    _audit_sched.add_job(_purge_step_log, CronTrigger(hour=4, minute=13))
     _audit_sched.start()
     _log.info("经验库每日巡检已注册（03:47 Asia/Shanghai）")
 except Exception as e:
@@ -259,10 +321,35 @@ if __name__ == "__main__":
     _ensure_uiauto_running()
     # 预连接设备池：adb server 重启后设备全掉线，后台并发重连加速恢复
     _preconnect_pool_devices()
+    # 步骤明细清理：服务频繁重启时定时任务可能一直轮不到，启动也清一次
+    _purge_step_log_async()
     _log.info(f"管理后台: http://localhost:{WEB_PORT}/ (admin/admin123)")
+    # 启动通知：放在 __main__ 里是刻意的——以 WSGI 方式 import 本模块只有"半个启动"
+    # （阶段 A~F 在 import 期就跑完了），不该发"服务已启动"。
+    try:
+        from core import notifier as _notifier
+        with app.app_context():
+            _devs = len(device_pool.list_configured())
+        _notifier.notify("service.started", env=db_config.env_badge().get("env", ""),
+                         db_target=db_config.describe_target(),
+                         device_count=_devs, job_count=len(mgr.jobs))
+    except Exception as _e:
+        _log.warning(f"发送启动通知失败（不影响启动）: {_e}")
+    _t0 = time.time()
     try:
         _run_server(WEB_HOST, WEB_PORT)
     finally:
+        try:
+            from core import notifier as _notifier
+            _notifier.notify("service.stopping", uptime_s=int(time.time() - _t0))
+            _notifier.shutdown(timeout=3.0)
+        except Exception:
+            pass
+        try:
+            from core import step_log as _step_log
+            _step_log.shutdown(timeout=3.0)     # 排空队列后再退
+        except Exception:
+            pass
         mgr.shutdown()
         device_discovery.shutdown()
         _stop_uiauto()