feat(大屏): 顶部加「📤 发布」按钮 —— 选设备直接注入视频/图片、注入剪贴板

用户要求："大屏按钮右边加一个按钮叫发布，就是选择设备号注入视频或者图片，位置就和发布页面的一样，然后还有在选择设备号注入剪贴板"。大屏（`/wall`）顶栏「一键亮屏」右边加 **「📤 发布」**，点开是一块面板： · **设备**下拉（设备名 + 地址，离线会标注；每次打开现取最新列表） · **视频 / 图片**：选文件 → 「注入素材」→ 推到该机相册 `/sdcard/DCIM/Camera` · **剪贴板文字**：填一段 → 「注入剪贴板」→ 写进该机剪贴板（发文案用） · 面板下方是操作日志（✅/❌ + 原因），失败会写清为什么后端（`web/tools_api.py`，都按 **设备位** 放行 —— 大屏上随手一推是设备操作，不该要管理员位）： · `POST /api/tools/push_material`（form-data：file + serial）：保存上传 → `publish_flow.push_video` 推到相册（文件名带 `wall` 前缀、mtime 改成现在，保证它在相册里排最前）→ `verify_pushed` 校验进没进相册索引 → 返回 `{ok,msg,remote,verify}` · **不占位、不写库**：与「发布计划 → 推送」是两回事（那条按计划走占位/去重/回写状态）；这条是"手上有一段素材，想马上在这台机器上发" · 扩展名按 `video_plan.MEDIA_EXTS` 校验（视频+图片），不在其中 → 400；设备不在线 → 400 · 临时目录用完即删（`finally` 里 rmtree） · `POST /api/tools/push_clipboard`：与 `/api/tools/clipboard/set` **同一个实现** （`_set_device_clipboard`），只是权限位不同真机验过（A01）：剪贴板注入 ✅；1×1 测试图推到相册 ✅（`verify=no_index` 的 ⚠ 是这张图太小、媒体库没索引它，真视频/图片是 ✅）；`.txt` 被 400 拦住 ✅；测试文件已从手机删掉、不留痕。文档：doc/API.md 加两条接口（含请求/返回/错误口径）、README 实时看屏那行补上发布面板。
feat(编辑器): 选择器值旁边加「{变量}」按钮 + 「点击元素」补变量说明
2026-10-12 14:57:01 +08:00 · 2026-10-12 13:54:59 +08:00 · 2026-10-12 13:40:20 +08:00 · 2026-10-12 13:31:02 +08:00 · 2026-10-12 11:49:48 +08:00 · 2026-10-12 11:08:40 +08:00
141 changed files with 38705 additions and 6207 deletions
@@ -0,0 +1,147 @@
+# ==============================================================================
+# auto_control 环境变量示例
+#   - 复制为项目根目录的 .env 再按需修改（.env 已被 .gitignore 排除，不会进 git）
+#   - 加载方式：config.py 逐行解析后用 os.environ.setdefault 注入
+#     → 因此"真实环境变量"优先于 .env（容器/CI 里用 env 覆盖更方便）
+#   - 标【必须】的项务必设置；其余留空即用代码默认值
+#   - 完整说明见 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))"
+WEB_SECRET_KEY=请填写随机密钥
+
+# 监听地址与端口是 config.py 里的常量（不进 .env）：WEB_HOST=0.0.0.0、WEB_PORT=18050
+# 需要修改直接改 config.py（18050 是为了避开 Windows 动态端口段）
+
+
+# ==================== 设备与 adb ====================
+# USB 设备（serial 无冒号）所在的部署机 —— 平台经它的 adb server 驱动这些设备。
+# 默认 100.100.10.1:5037（220 的 Tailscale IP + adb 容器端口，host 网络模式）。
+# USB_ADB_HOST=100.100.10.1
+# USB_ADB_PORT=5037
+
+# 设备自动发现（扫描网段找开放 5555 的设备）。
+# 扫描网段在「工具 → 设备池管理」界面里配置（存数据库 app_meta），此处只管端口与周期。
+# DISCOVERY_PORT=5555
+# DISCOVERY_INTERVAL=60
+
+# 把本机的 adb 客户端指向远程 adb server（注意：这三个键由 adb/adbutils 自己读取，
+# 不是本项目代码读的；两个变量名都要设，adb 实际认 ADDRESS，部分库读 HOST）。
+# 用途：让本机 adb 直接看到 220 侧插着的 USB 设备。
+# ANDROID_ADB_SERVER_ADDRESS=192.168.20.220
+# ANDROID_ADB_SERVER_HOST=192.168.20.220
+# ANDROID_ADB_SERVER_PORT=5037
+
+
+# ==================== Tailscale 管理（工具 → Tailscale 管理） ====================
+# API key：Tailscale 后台 → Settings → API Access Tokens 生成
+TAILSCALE_API_KEY=请填写Tailscale_API_key
+
+# tailnet 名/ID（一般填登录邮箱，如 [email protected]）
+# [email protected]
+
+
+# ==================== MCP Server（外部 AI 接入，:8033） ====================
+# 注意：mcp_server 只读进程环境变量，**不读本文件**！
+#   容器场景由 scripts/start.sh 用下面这些变量拉起进程；
+#   本机手动启动请直接在命令行前加环境变量（见 doc/MCP.md §2）。
+#
+# MCP_ENABLED=1                  # 仅 start.sh 消费：=0 则不自动拉起 MCP
+# MCP_ALLOW_WRITE=1              # 写操作总开关（0=只读；start.sh 内强制为 1）
+# MCP_PLATFORM_URL=http://127.0.0.1:18050
+# MCP_PLATFORM_USER=admin
+# MCP_PLATFORM_PASS=请填写平台admin密码   # 【改过 admin 密码必须同步，否则 MCP 登录失败】
+# MCP_ALLOWED_SERIALS=           # 设备白名单（逗号分隔）；空=不限制（语义缺口见 backlog）
+# MCP_HTTP_HOST=0.0.0.0
+# MCP_HTTP_PORT=8033
+# MCP_SCREENSHOT_WIDTH=540       # 返回给模型的截图宽度
+# MCP_JPEG_QUALITY=70
+# MCP_AUDIT_FILE=/tmp/mcp_audit.log
+# MCP_PLATFORM_TIMEOUT=30
+
+
+# ==================== AI Agent（mcp_agent，命令行/独立运行时用） ====================
+# 注意：同样只读进程环境变量、不读本文件。
+# Web 的「AI 控制台」配置走数据库（app_meta 的 agent_* 键），与本组变量互不影响。
+#
+# AGENT_API_BASE=https://api.deepseek.com
+# AGENT_MODEL=deepseek-v4-flash-vision-exp
+# AGENT_API_KEY=请填写模型 API Key
+# DEEPSEEK_API_KEY=              # AGENT_API_KEY 的兼容别名
+# AGENT_MCP_URL=http://127.0.0.1:8033/mcp
+# AGENT_DEFAULT_SERIAL=
+# AGENT_MAX_STEPS=40
+# AGENT_TIMEOUT=120
+# AGENT_LANG=zh
+
+
+# ==================== 开发/测试 ====================
+# 设置后不启动 cron 调度器（跑测试脚本时避免真实触发任务、占用设备）
+# DISABLE_SCHEDULER=1
+
+# 视频发布计划的素材目录（默认 data/videos）。
+# **自动化测试必须指到临时目录**，否则测试传的视频会落进用户真实数据目录。
+# DATA_VIDEO_DIR=/tmp/videos_test
+
+# 单次上传体积上限（MB，默认 2048）。
+# ⚠ 必须大于「应用管理」里最大的 APK（实测有 336MB 的包），否则 APK 上传会被一起卡死。
+# MAX_UPLOAD_MB=2048
+
+# ==================== 发布计划：抖音「我」页面上的控件（抓一次填这里） ====================
+# 发布任务按**名字**发（名字 = 抖音昵称），所以平台要知道"名字在屏幕上哪个控件里"。
+# 用「抓取元素」抓一次抖音「我」页面上的**昵称**（那个 TextView），填到下面。
+# 一处配置、三处一致：任务骨架的「读取本机账号名字」步骤默认值、切号后的回读校验、
+# 以及「发布计划 → 一键推送（按名字找设备）」的实时探测。
+# 留空 = 还没抓：相关步骤会明确报错并跳过，**绝不会猜一个名字去发**。
+#
+# 2026-10-12 在 A01（抖音 40.6.0）实测可用的值：昵称那个 TextView 的 resource-id 是混淆 id `tk+`，
+# 所以填 resourceId（等价 xpath：//*[@resource-id="com.ss.android.ugc.aweme:id/tk+"]）。
+# 2026-10-12 实测：40.7.0 的昵称 id 是 `tkv`、40.6.0 是 `tk+` —— 用 **xpath 联合**一个值通吃两版
+# DOUYIN_NAME_SELECTOR_TYPE=xpath
+# DOUYIN_NAME_SELECTOR_VALUE=//*[@resource-id="com.ss.android.ugc.aweme:id/tkv"] | //*[@resource-id="com.ss.android.ugc.aweme:id/tk+"]
+
+# 「我」页面 →「切换账号」列表那个入口（自动切号用，同样抓一次填这里）。
+# 它是个只有 content-desc 的 ImageView（desc 就是「切换账号」），所以用 descriptionContains。
+# 留空 = 「切换账号」步骤会明确报错并跳过（不会瞎点）。
+# DOUYIN_SWITCH_SELECTOR_TYPE=descriptionContains
+# DOUYIN_SWITCH_SELECTOR_VALUE=切换账号
+#
+# 细节与结构图见 doc/research/U2_ELEMENT_SELECTORS.md §七（含"为什么不要用 (…b7w)[N]"）。
+
+
+# ==============================================================================
+# 已废弃的历史配置（STF 已从代码层摘除，下列键代码不再使用，保留仅为兼容旧 .env）
+#   STF_URL / STF_TOKEN / STF_SSH_TARGET / STF_SSH_PASSWORD /
+#   STF_DOCKER_CONTAINER / STF_ADB_CONTAINER / STF_SCRIPT_PATH /
+#   AUTO_RELEASE_STALE_OCCUPY
+# 迁移背景见 doc/STF_REMOVAL.md
+# ==============================================================================
@@ -10,8 +10,13 @@ env/

 # 运行时数据
 logs/*.log
+data/*.log
 data/apks/*.apk
+# 视频发布计划的素材（几百 MB 一个，绝不入库）
+data/videos/
 data/*.migrated
+# uiauto.pid 之类的运行时 PID 文件（**注释必须单独一行**：gitignore 不支持行尾注释）
+data/*.pid
 data/*.db-shm
 data/*.db-wal

@@ -36,5 +41,21 @@ desktop.ini
 *.tmp
 *.bak

+# 密钥/环境变量（真实 .env 含 token/密钥，绝不提交）
+# .env.* 一并忽略：改配置前留的 .env.bak_xxx / .env.old 同样含生产密钥，
+# 220 上就出现过一次（2026-09-13 切 MySQL 时的备份），差点被 git add . 带进去。
+.env
+.env.*
+!.env.example

-bin/adb/*
+
+bin/adb/*
+# 数据备份与损坏库（运维临时文件，不入库）
+data/db_backup_*/
+data/*.corrupt_*
+data/users.db*
+data/users.db-wal
+data/users.db-shm
+data/backups/
+data/restore_staging/
+data/restore_pending/
@@ -1,23 +1,66 @@
-# 设备自动化后台（platform-tools）
+# auto_control — Android 多设备自动化任务平台

-基于 **STF（Smartphone Test Farm）+ uiautomator2 + Flask** 的 Android 多设备自动化任务执行平台。
+基于 **uiautomator2 + Flask + 自建设备池** 的 Android 多设备自动化平台（已摘除 OpenSTF 依赖，见 [doc/STF_REMOVAL.md](doc/STF_REMOVAL.md)）。

-提供 Web 管理后台，支持多设备并发任务执行、定时调度、设备分组管理、APK 批量安装、UI 元素抓取等功能。内置抖音养号任务和通用步骤任务，可扩展任意 App 的自动化操作。
+一台机器上统管一批 Android 设备：定时/手动下发任务、并发执行、实时看屏与远程触控、元素抓取与步骤编排、APK 批量安装、数据备份导出/导入；并通过 **MCP** 把手机控制能力开放给外部 AI（数字员工）。
+
+```
+                       ┌──────────── Web 管理后台（单页应用，:18050）────────────┐
+   浏览器 ────────────▶ │ 监控 │ 任务 │ 日志 │ 用户 │ 工具 │ AI 控制台 │ 系统     │
+                       └───────────────────────┬─────────────────────────────────┘
+                                               │ Flask 蓝图（web/）
+                       ┌───────────────────────▼──────┐   ┌──────────────────────┐
+                       │ 调度 TaskManager             │   │ AI Agent（mcp_agent）│
+                       │ 设备池 device_pool           │   └──────────┬───────────┘
+                       │ Worker（每设备一线程）        │              │ MCP :8033
+                       └───────┬──────────────┬───────┘   ┌──────────▼───────────┐
+                               │              │           │ MCP Server（de_* 工具）│
+                          adb 直连         uiautodev        └──────────┬───────────┘
+                        IP:5555 / USB   :20242（抓元素）                │
+                               ▼                                      ▼
+                         Android 设备 ◀──────────────────────── Android 设备
+```

 ---

 ## 目录

+- [核心能力](#核心能力)
 - [快速上手](#快速上手)
 - [项目结构](#项目结构)
 - [核心概念](#核心概念)
- [配置说明](#配置说明)
 - [Web 管理后台](#web-管理后台)
- [任务系统](#任务系统)
- [日志系统](#日志系统)
- [常用脚本](#常用脚本)
+- [任务与步骤](#任务与步骤)
+- [AI 与 MCP](#ai-与-mcp)
+- [配置说明](#配置说明)
+- [日志](#日志)
 - [常见问题](#常见问题)
- [更多文档](#更多文档)
+- [文档索引](#文档索引)
+
+---
+
+## 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| **多设备并发任务** | 每设备一个 Worker 线程；同一设备同时只跑一个任务（可配置"抢占"打断其他任务） |
+| **设备池** | SQLite 清单 + adb 在线状态；支持手工添加、网段自动发现、一键重连、型号采集、启用/停用 |
+| **电量监控** | 后台每分钟 `dumpsys battery`（只读）采一次电量，**大屏卡片**与**监控页设备列表**都显示（按档位着色 + ⚡ 充电中）；低于阈值推 webhook 告警（**充电中不报、"插着却没充电"照报**，掉档/恢复各报一次，不刷屏）。电量只放内存不落库（见 [NOTIFY.md](doc/NOTIFY.md) §3.1） |
+| **任务调度** | 手动 / cron 定时 / 定时启停；运行窗口；失败重试（含端口耗尽类的长退避） |
+| **步骤编辑器** | 可视化拖拽编排 24 种步骤（含循环/条件/OCR/通知/录制回放），可打包成"自定义动作"复用 |
+| **拟人化操作** | 滑动默认走弧线轨迹、位置/幅度/时长每次抖动，且**每台设备有自己的手速与习惯**（同设备风格稳定、设备之间明显不同）——批量跑时不像同步机器人（见 [TASK_DEV.md](doc/TASK_DEV.md) §8.4） |
+| **录制回放** | 「录制手势」步骤 = **纯录制**：**用手指在真机上划**（读 getevent 真触屏）或在网页画面上拖，把轨迹点列原样存下来，回放时**照原路径与时长重放**——不套滑动那套方向/幅度/拟人参数 |
+| **动作配置 / 录制** | 「任务 → 动作配置」：① 配**步骤默认值**（新建步骤预填：滑动时长/幅度/抖动/拟人、点击超时、等待区间…）② **录制动作**——在设备画面上点/划/按键，自动翻译成步骤（点元素记选择器、划一下记方向/幅度/时长），可存成可复用动作，也可只取一个手势回填滑动步骤 |
+| **公共巡检** | 任务级的守护条件（**独立于步骤画布**）：每 N 秒检查屏幕亮/熄、元素在不在、前台是不是某 App，命中就点亮/息屏/停本设备/推通知——通知标题正文自己写（见 [TASK_DEV.md](doc/TASK_DEV.md) §4.5） |
+| **去重账本** | 解决"**同一个号被做两次、有的号还没做**"：任务里用「条件判断→去重」+「记为已做」，把"这个身份做过了"记进一张**所有设备共享**的账本——多台手机、反复重跑都不会重复做同一个号。「任务 → 去重记录」页能看"谁做过了、还差谁"，也能删记录让它重跑（见 [TASK_DEV.md](doc/TASK_DEV.md) §4.6） |
+| **视频发布计划** | 「发布计划」页：批量上传**视频/图片**（文件名 `名字_日期_编号`，**名字 = 抖音昵称**；视频和图片同一套规则）与标题 txt（每行 `标题 || 正文_名字_日期_编号`）→ 自动按 (名字,日期,编号) 配对 → **按日期的时间线**看每天谁要发、发到哪一步。**平台只负责把素材推到手机**（推到 `/sdcard/DCIM/Camera/`、触发相册刷新、把标题写进剪贴板），**抖音里怎么发由你自己在任务里写步骤**（步骤顺序：`读取本机账号名字` → `条件判断`校验 → `推送发布视频` → 你的发布步骤 → `标记发布结果`；页顶部有**「发布任务」**块可一键建好骨架 + 看下次运行/启停，`输入文字` 那一步可以选**取值来源＝计划标题/正文**自动填文案并回读校验）；发完可抓作品的**分享链接**存下来（平台不长期囤视频，链接才是长期资产，也方便后续铺评论：可一键复制、按日期/名字导出 CSV）。状态区分"**可重试**"（推送阶段失败，还没到抖音）与"**结果未知、需人工确认**"（推送之后出的岔子，绝不自动重发）（见 [DATA_MODEL.md](doc/DATA_MODEL.md) §2.11、[TASK_DEV.md](doc/TASK_DEV.md) §4.7） |
+| **元素抓取** | 拉取设备 UI 元素树 → 点选回填选择器；支持"点一下"与"测选择器"真机验证 |
+| **实时看屏** | MJPEG 实时流 + 点击/滑动/按键/文字输入；全屏监控大屏（`/wall`）：每个设备卡片点开就能操作，顶部还有 **「📤 发布」面板** —— 选设备直接把视频/图片推到相册、或把文案写进剪贴板（临时手动推，不占发布计划、不写库） |
+| **应用管理** | APK 上传/解析/批量安装；设备已装应用与版本查询；剪贴板注入 |
+| **AI 控制台** | 用自然语言驱动 AI 操作指定设备（MCP 工具 + 截图），流式输出、Markdown 渲染、推理链折叠、token 统计；成功操作自动沉淀「经验库 / 动作库」并在相似任务中召回 |
+| **MCP 接入** | 20 个 `de_*` 工具，把手机控制开放给外部 AI；写操作有开关、设备忙时拒绝、全量审计 |
+| **备份导出/导入** | 一键导出 zip（库快照 + manifest + 可选 APK），导入前校验预览、自动预备份、重启生效 |
+| **通知 / Webhook** | 任务成功失败、设备上下线、安装完成、备份恢复等事件推送到企业微信 / 钉钉 / 飞书 / Bark / 自建服务（Slack 用通用 JSON）；多条 webhook 各自订阅；聚合+限流防刷屏（见 [doc/NOTIFY.md](doc/NOTIFY.md)） |

 ---

@@ -26,9 +69,8 @@
 ### 环境要求

 - **Python 3.10+**（推荐 3.12）
- **OpenSTF 服务**：已部署并运行，设备已接入 STF
- **Windows / Linux / macOS**均可（adb 二进制需放对应平台版本到 `bin/adb/`）
- 设备需开启 **USB 调试**或通过 **adb 网络连接**（IP:5555）接入
+- Windows / Linux / macOS 均可（`bin/adb/` 需放对应平台的 adb 二进制）
+- 设备开启 **USB 调试**；网络调试设备建议 `adb tcpip 5555` 并接入同一网络（本项目生产环境走 Tailscale `100.100.10.x`，见 [doc/DEPLOY.md](doc/DEPLOY.md)）

 ### 三步启动

@@ -36,380 +78,346 @@
 # 1. 安装依赖
 pip install -r requirements.txt

-# 2. 修改配置（STF 地址、token、adb 路径等）
-#    编辑 config.py 中的 STF_URL 和 STF_TOKEN
+# 2. 配置（可选）：把 .env.example 复制成 .env，至少填 WEB_SECRET_KEY
+#    密钥类配置一律放 .env（不入 git）

-# 3. 启动 Web 后台
+# 3. 启动
 python web_server.py
 ```

-启动后访问 **http://localhost:18050/**，默认账号 `admin` / `admin123`。
-
-> Windows 用户也可双击 `start_web.bat` 启动（自动提权 + 添加防火墙规则，支持局域网访问）。
+启动后访问 **http://localhost:18050/**，默认账号 `admin` / `admin123`（**首次登录请立即改密**）。

 ### 验证启动

-控制台看到以下日志即表示启动成功：
-
 ```
 [INFO] [core.worker] 心跳看门狗已启动
 [INFO] [core.tm] 从数据库加载 X 个分组, X 个任务
+[INFO] [web] uiautodev 服务已启动 (PID=...)
 [INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
+[INFO] [web] 设备池预连接完成: X 台在线
 [INFO] [web] 启动服务: http://localhost:18050/
 ```

-### 首次使用流程
+### 首次使用

-1. **登录后台** → 用 `admin/admin123` 登录，建议立即修改密码
-2. **查看设备** → 首页"监控"Tab 自动展示 STF 设备池状态
-3. **创建分组**（可选）→ "分组"Tab 按批次/项目给设备分组
-4. **创建任务** → "任务"Tab 新建任务，选择任务类型、目标设备、参数、调度
-5. **执行任务** → 任务列表点"立即执行"，或在"监控"Tab 勾选设备批量操作
-6. **查看日志** → "日志"Tab 实时查看运行日志
+1. **登录** → `admin/admin123`，改密
+2. **加设备** → 「工具 → 设备池管理」添加 `IP:5555`（自动连接 + 采集型号）；也可用「设备自动发现」扫描网段后确认入池
+3. **看设备** → 「监控」页设备表（在线/型号/任务/进度/前台 App）
+4. **建任务** → 「任务 → 任务计划 → 新建任务」（只有 `generic_steps` 一种类型）→ 拖步骤 → 选目标设备 → 保存
+5. **跑任务** → 任务行「执行」，或在「任务」/「监控」页操作
+6. **看日志** → 「日志」页按模块实时查看

 ---

 ## 项目结构

 ```
-platform-tools/
-├── config.py                    # 根配置（STF地址/token、adb路径、web端口）
-├── web_server.py                # Flask 入口（API + 登录 + 单页应用）
-├── main.py                      # 命令行入口（单设备跑一次，不走 web）
-├── create_task.py               # 一次性脚本（创建定时任务示例）
-├── requirements.txt             # Python 依赖清单
-├── start_web.bat                # Windows 一键启动（提权 + 防火墙）
+auto_control/
+├── config.py                  # 程序级配置常量（部署配置从 .env 读，模板 .env.example）
+├── web_server.py              # 入口：app 装配 + 蓝图注册 + 恢复消费 + 拉起 uiautodev + 启动
+├── requirements.txt           # 依赖清单
 │
-├── core/                        # 核心基础设施层
-│   ├── logger.py                #   统一日志（分文件、10MB 滚动）
-│   ├── stf_client.py            #   STF REST API 封装（占用/释放/远程连接）
-│   ├── adb_helper.py            #   adb 命令封装（全局锁，绝不 kill-server）
-│   ├── device_worker.py         #   BaseWorker 基类 + STFDevice + 心跳看门狗
-│   ├── task_manager.py          #   TaskManager 调度器 + 前台App扫描器
-│   ├── u2_helper.py             #   uiautomator2 通用辅助函数
-│   ├── uiauto_helper.py         #   uiautodev 元素抓取客户端
-│   ├── apk_manager.py           #   APK 上传/解析/批量安装
-│   ├── models.py                #   SQLAlchemy 数据模型 + 数据库初始化
-│   └── actions/
-│       ├── __init__.py          #   全局 Action 框架导出
-│       └── base.py              #   BaseAction 基类 + 注册机制
+├── web/                       # Web 层（蓝图包，路由都在这里，全部无 url_prefix）
+│   ├── auth.py                #   登录/登出/CSRF/权限装饰器/页面路由（/、/wall）
+│   ├── monitor.py             #   设备状态/运行控制/设备操作/远程看屏（MJPEG、点击、按键）
+│   ├── tasks_api.py           #   任务计划/分组/自定义动作/元素抓取/步骤测试
+│   ├── admin_api.py           #   用户管理/日志
+│   ├── tools_api.py           #   adb 终端/剪贴板注入/应用版本查询
+│   ├── devices_api.py         #   设备池管理 + 自动发现
+│   ├── apks_api.py            #   APK 上传/安装/删除
+│   ├── 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）
 │
-├── tasks/                       # 任务定义层（每个 App 一个子包）
-│   ├── __init__.py              #   全局任务注册表
-│   ├── base.py                  #   BaseTask 基类 + @register_task 装饰器
-│   ├── douyin/                  #   抖音养号任务
-│   │   ├── __init__.py
-│   │   ├── task.py              #     DEFAULT_PARAMS + Worker + Task
-│   │   └── actions/             #     抖音专属操作（点赞等）
-│   │       ├── __init__.py
-│   │       ├── base.py          #     抖音 ACTIONS 注册表
-│   │       └── like.py          #     点赞操作（找红心/双击回退）
-│   └── generic/                 #   通用步骤任务（可视化编辑器编排）
-│       ├── __init__.py
-│       └── task.py              #     步骤执行引擎（open_app/click/swipe/loop...）
+├── core/                      # 基础设施层
+│   ├── models.py              #   SQLAlchemy 模型 + 建表 + 版本化迁移 + 旧 JSON 迁移
+│   ├── device_pool.py         #   设备池（清单/在线状态/型号/设备名→当前地址）
+│   ├── device_worker.py       #   BaseWorker + 设备生命周期 + 心跳看门狗 + 全局状态表
+│   ├── task_manager.py        #   调度器：分组/任务/APScheduler/重试/运行控制
+│   ├── adb_helper.py          #   adb 命令封装（全局锁，红线：绝不 kill-server）
+│   ├── device_discovery.py    #   网段扫描发现设备 → 待连接池
+│   ├── device_battery.py      #   设备电量采集（dumpsys 只读）+ 低电量告警
+│   ├── video_plan.py          #   视频发布计划（文件名解析配对 / 时间线 / 幂等占位 / 素材清理）
+│   ├── account_probe.py       #   实时探测设备当前登录的抖音号（按名字找设备用）
+│   ├── u2_helper.py           #   uiautomator2 通用辅助（等首页/安全点击等）
+│   ├── uiauto_helper.py       #   uiautodev 客户端（元素树 + XPath 建议）
+│   ├── ocr.py                 #   屏幕 OCR（RapidOCR，条件判断用）
+│   ├── 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）
+│   └── actions/               #   全局 Action 框架（BaseAction + 注册器）
 │
-├── templates/admin/             # 前端页面
-│   ├── monitor.html             #   单页应用（监控/任务/分组/日志/用户 5 Tab）
-│   └── login.html               #   登录页
+├── tasks/                     # 任务定义层
+│   ├── base.py                #   BaseTask + _TASK_TYPES + register_task
+│   └── generic/               #   通用步骤任务（task_type=generic_steps，当前唯一类型）
+│       └── task.py            #     STEP_TYPES（24 种步骤）+ Worker + 执行器
 │
-├── static/admin/
-│   └── custom.css               # 自定义样式
+├── mcp_server/                # MCP Server（20 个 de_* 工具，:8033）
+│   ├── mcp_server.py          #   工具定义 + 平台登录 + 门控
+│   ├── platform_client.py     #   平台 HTTP 客户端（复用 Web 账号）
+│   ├── direct_ops.py          #   直连设备的 adb/u2 操作
+│   ├── audit.py               #   调用审计（JSON Lines）
+│   └── config.py              #   MCP_* 环境变量
 │
-├── data/                        # 运行时数据
-│   ├── users.db                 #   SQLite（用户/分组/任务/自定义动作/APK记录）
-│   └── apks/                    #   上传的 APK 文件存储
+├── mcp_agent/                 # AI Agent 编排层（OpenAI 兼容模型 → MCP 工具）
+│   ├── agent.py               #   Agent：流式循环 + 工具调用 + 截图 + token 统计
+│   ├── config.py              #   AGENT_* 环境变量
+│   └── cli.py                 #   命令行入口
 │
-├── logs/                        # 日志文件（自动生成，10MB 滚动保留 5 份）
-│   ├── core.log                 #   核心程序日志
-│   ├── task.log                 #   任务执行日志
-│   ├── web.log                  #   Web 请求日志
-│   └── action.log               #   操作执行日志
+├── templates/admin/           # 页面
+│   ├── monitor.html           #   主单页应用（7 个顶级 Tab + 模态框 + 内联样式）
+│   ├── login.html             #   登录页
+│   └── wall.html              #   监控大屏（独立页面，自包含）
+├── static/admin/              # 前端 JS（13 个文件，按顺序同步加载，见下）
+├── static/fonts/              # 自托管字体（Bricolage Grotesque + IBM Plex Mono）
 │
-├── bin/adb/                     # adb 可执行文件（Windows: adb.exe + dll）
-├── scripts/                     # 实用脚本
-│   ├── cleanup.py               #   清理 STF 残留设备占用
-│   └── pack.py                  #   打包项目为 zip（排除运行时产物）
-└── doc/                         # 项目文档
-    ├── TASK_DEV.md              #   任务开发指南（新增 App 任务模板）
-    ├── ARCHITECTURE.md          #   架构详解
-    ├── DEPLOY.md                #   部署指南
-    └── API.md                   #   API 接口文档
+├── data/                      # 运行时数据（不入 git）
+│   ├── users.db               #   SQLite 主库
+│   ├── apks/                  #   上传的 APK
+│   ├── backups/               #   导出 zip / 预恢复快照
+│   ├── restore_staging/       #   导入暂存（TTL 30 分钟）
+│   └── restore_pending/       #   待重启生效的恢复任务
+├── logs/                      # 日志（10MB 滚动，保留 5 份）
+├── bin/adb/                   # adb 二进制
+├── scripts/                   # pack.py / start.sh / supervise.sh / regression_test.py
+└── doc/                       # 完整文档（入口 → doc/README.md）
+```
+
+前端 JS 加载顺序（`templates/admin/monitor.html` 底部，全部为全局脚本，无模块隔离）：
+
+```
+base.js → markdown.js → list.js → monitor.js → editor.js → tasks.js
+        → tools.js → apps.js → admin.js → agent.js → taskgen.js → system.js → notify.js → steplog.js → recorder.js
 ```

 ---

 ## 核心概念

-### 设备生命周期
+### 设备与 Worker

-```
-STF occupy（占用设备）
-    ↓
-STF remoteConnect（建立远程 ADB 隧道）
-    ↓
-adb connect（连接远程设备）
-    ↓
-u2.connect（连接 uiautomator2，自动推送 atx-agent）
-    ↓
-Worker.run_task（执行业务逻辑）
-    ↓
-adb disconnect + STF release（释放设备）
-```
+一台设备对应一个 `Worker` 线程（`core/device_worker.py` 的 `BaseWorker`）。基类封装了设备获取、adb/u2 连接（带超时保护）、状态上报、异常分类、停止信号、心跳看门狗；子类只实现 `run_task(d)`。

-> 直连模式：当设备 serial 为 `IP:5555` 格式时，直接 adb connect，不走 STF 桥接，更稳定。
+执行链路：`设备池选定 → adb connect 直连（IP:5555）或经 220 远程 adb server（USB）→ u2.connect（自动推送 atx-agent）→ run_task → 释放（不断开连接）`。

-### Worker — 单设备执行线程
+**同一设备同时只允许一个 Worker**：由 `TaskManager._running` 内存锁保证；任务可开 `preempt` 抢占（先停掉正在跑的任务再接管，结束后归还）。

-每台设备对应一个 `Worker` 线程，继承 `BaseWorker`（`core/device_worker.py`）。基类已封装：
+### 任务类型（TaskType）

- STF 设备占用/释放（try/finally 保证释放）
- adb 连接 + u2.connect（带 30 秒超时保护）
- 状态上报（实时推送到前端监控大屏）
- 异常捕获（设备离线不重试，其他异常按策略重试）
- stop 停止信号（循环里检查 `self.stopped()`）
- 心跳看门狗（120 秒无心跳自动标记卡死）
+| task_type | 名称 | 说明 |
+|-----------|------|------|
+| `generic_steps` | 通用步骤 | 步骤编辑器编排的流程（**当前唯一类型**） |

-子类只需实现 `run_task(d)` 方法专注业务逻辑。
+新增专属任务类型的方法见 [doc/TASK_DEV.md](doc/TASK_DEV.md)。

-### TaskType — 任务类型
+### 任务计划（TaskJob）

-| 任务类型 | task_type | 说明 |
-|---------|-----------|------|
-| 抖音养号 | `douyin_nurture` | 自动看视频 + 随机点赞，被退出自动重连 |
-| 通用步骤 | `generic_steps` | 可视化步骤编辑器编排流程，支持循环/点击/滑动等 |
+描述"什么任务、跑哪些设备、什么参数、何时跑、失败怎么重试"：

-### TaskJob — 任务计划
-
-一个 TaskJob 描述"什么时候、在哪些设备上、用什么参数执行什么任务"：
-
-| 字段 | 说明 | 示例 |
-|------|------|------|
-| `task_type` | 任务类型 | `"douyin_nurture"` |
-| `target` | 目标设备 | `{"mode": "all"}` 或 `{"mode": "group", "group_name": "A组"}` 或 `{"mode": "serial", "serial": "192.168.1.100:5555"}` |
-| `params` | 任务参数（与默认值深合并） | `{"watch_count": 50, "actions": {"like": {"params": {"rate": 0.5}}}}` |
-| `schedule` | 调度策略 | `{"mode": "once"}` 或 `{"mode": "cron", "cron": "0 9 * * *"}` 或 `{"mode": "cron_stop", "cron": "0 9 * * *", "stop_cron": "0 18 * * *"}` |
-| `retry` | 重试策略 | `{"max_attempts": 3, "delay": 60}` |
-| `enabled` | 是否启用 | `true` |
-
-### 调度模式
-
-| 模式 | 行为 |
+| 字段 | 说明 |
 |------|------|
-| `once` | 手动执行（前端点"立即执行"） |
-| `cron` | 定时启动：到 cron 时间点自动启动所有目标设备 |
-| `cron_stop` | 定时启停：启动 cron 到点启动，停止 cron 到点停止本任务 worker |
+| `task_type` | 任务类型（不传默认 `generic_steps`） |
+| `target` | `{"mode":"all"}` / `{"mode":"group","group_name":"A组"}` / `{"mode":"serial","serial":"100.100.10.20:5555"}` |
+| `params` | 任务参数，与任务类默认值合并；含两个隐藏开关 `skip_offline`（默认 true）、`preempt`（默认 false） |
+| `schedule` | `{"mode":"once"}` / `{"mode":"cron","cron":"0 9 * * *"}` / `{"mode":"cron_stop","cron":...,"stop_cron":...}`，可选 `window` 运行窗口 |
+| `retry` | `{"max_attempts":1,"delay":60}` |
+| `enabled` | 是否参与调度 |

-cron 表达式为标准 5 段格式：`分 时 日 月 周`（如 `0 9 * * *` = 每天 9:00）
+**调度模式**：`once` 仅手动；`cron` 到点启动；`cron_stop` 到点启动 + 到点停止。cron 为标准 5 段 `分 时 日 月 周`，编辑器提供"每天/每小时/每隔 N 小时/每周"的可视化选择自动生成，也可手填。

-### 设备分组
+**运行窗口**（`schedule.window`，如 `21:00-09:00`，支持跨午夜）：窗口外定时触发与手动执行都不启动。

-设备分组存于 SQLite，便于按批次/项目分组下发任务。一个 Job 指定 `target.mode="group"` 时，调度器展开为组内全部设备。
+**目标解析**（`TaskJob.resolve_serials`）：`all` = 设备池 ∩ 在线（开了抢占则取全部在线池内设备）；`group` = 分组 ∩ 设备池；`serial` = 指定设备。后两者默认跳过离线设备。

 ### 进度上报

-Worker 通过 `self.set_progress()` 上报通用进度字段，前端统一解析展示：
+Worker 通过 `set_progress()` 上报统一字段，前端统一渲染：

 ```python
-self.set_progress(done=5, total=80, unit="视频",
-                  action_counts={"like": 3})
+self.set_progress(done=5, total=80, unit="视频", action_counts={"like": 3}, elapsed=120)
 ```

-前端展示：进度条 + `5/80 视频` + `点赞 3` 徽章。
-
---
-
-## 配置说明
-
-所有核心配置在 [config.py](file:///d:/platform-tools/config.py)，**任务参数不放在这里**（放各自 `tasks/xxx.py` 顶部）。
-
-| 配置项 | 默认值 | 说明 |
-|-------|--------|------|
-| `STF_URL` | `http://192.168.20.220:7100` | OpenSTF 服务地址 |
-| `STF_TOKEN` | （需替换） | STF API Token，在 STF 个人设置里生成 |
-| `ADB_PATH` | 自动识别 | adb 二进制路径，自动区分 Windows/Linux |
-| `WEB_HOST` | `0.0.0.0` | Web 监听地址（0.0.0.0 支持局域网访问） |
-| `WEB_PORT` | `18050` | Web 端口（避开 Windows 动态端口范围） |
-| `DATA_DIR` | `data/` | 持久化数据目录 |
-| `APK_DIR` | `data/apks/` | APK 文件存储目录 |
-
-**必须修改的配置**：`STF_URL` 和 `STF_TOKEN`，改成你自己的 STF 服务地址和 Token。
+前端展示为进度条 + `5/80 视频` + 计数徽章 + 运行时长。

 ---

 ## Web 管理后台

-### 页面结构
+单页应用（`templates/admin/monitor.html`），**7 个顶级 Tab**；「任务 / 工具 / 系统」内部还有页内子分栏（会记住上次选中位置）。

-单页应用（`templates/admin/monitor.html`），5 个 Tab：
+| Tab | 内容 | 可见性 |
+|-----|------|--------|
+| **监控** | 统计卡片 + 设备表（在线/型号/任务状态/进度/前台 App/最近错误，支持排序、搜索、分页、多选批量操作）+ 异常汇总 + **任务运行概况**（每张任务卡：执行任务 / 停用任务 + 覆盖设备彩色 chip）；导航栏「📺 大屏」打开 `/wall` | 所有登录用户（设备操作按钮需"设备控制"） |
+| **任务** | 子分栏：**任务计划**（CRUD / 启停 / 执行 / 下次运行时间 / 离线跳过 / 步骤编辑器 / **公共巡检**）、**自定义动作**（步骤打包复用）、**动作配置**（步骤默认值 + 录制动作） | 可看；写操作需"任务管理" |
+| **日志** | 子分栏：**文件日志**（文件切换含滚动历史、关键字/级别/时间过滤、命中高亮、下载筛选结果、自动刷新）、**步骤明细**（按设备/任务/结果/时间过滤、按运行归组的概览、导出 CSV） | 需"日志查看" |
+| **用户** | 用户 CRUD、改密、分配权限 | 仅管理员 |
+| **工具** | 8 个子分栏：剪贴板注入 / adb 远程终端 / Tailscale 管理 / 应用管理 / 应用版本管理 / 设备已装应用 / **设备池管理**（含自动发现）/ 设备分组 | 仅管理员 |
+| **AI 控制台** | 会话列表 + 对话区（Markdown 渲染、推理链折叠、token 统计）+ 实时画面（MJPEG）+ 目标设备选择；右上角：经验库 / 动作库 / 模型配置 | 仅管理员 |
+| **系统** | 子分栏：数据备份（导出 zip）/ 导入恢复（上传→校验预览→应用，重启生效） | 仅管理员 |

-| Tab | 功能 |
-|-----|------|
-| 监控 | 设备状态大屏：在线/离线、运行任务、当前动作、进度条、前台 App、截图、停止 |
-| 任务 | 任务计划 CRUD：新建/编辑/删除/启用停用/立即执行 |
-| 分组 | 设备分组管理：创建/编辑/删除分组 |
-| 日志 | 实时日志查看：按模块切换（core/task/web/action） |
-| 用户 | 用户管理：创建/删除/修改密码 |
+### 权限模型

-### 前台 App 扫描
+默认账号 `admin/admin123`（管理员，权限不受限）。权限位：

-监控页"扫描前台App"按钮，获取所有设备当前前台 App。**不打扰设备**：
+| 权限位 | 键 | 覆盖 |
+|--------|----|------|
+| 任务管理 | `tasks` | 任务/分组/自定义动作的写操作 |
+| 设备控制 | `devices` | 停止设备、亮息屏、定位、清异常、前台扫描、元素抓取、步骤测试 |
+| 应用管理 | `apks` | APK 上传/安装/删除 |
+| 日志查看 | `logs` | 日志 Tab |

-| 设备状态 | 处理方式 |
-|---------|---------|
-| worker 运行中 | 复用已有 ADB 连接查询 |
-| 自己占用 | 通过 STF remoteConnect 隧道查询（不 occupy/release） |
-| 完全空闲 | 返回"空闲"（不主动 adb connect，避免 STF 误判离线） |
-| 他人占用 | 标记"(他人占用)" |
-
-### 截图功能
-
-监控页每台设备可查看实时截图。用 `adb exec-out screencap -p`，只读操作，**任务运行中也能安全调用**（不抢占 u2 的 atx-agent 通道）。
-
-### 元素抓取
-
-任务编辑器的"抓取元素"按钮可拉取设备当前 UI 元素树，点击元素一键回填选择器。依赖本地运行的 uiautodev 服务（端口 20242），`web_server.py` 启动时会自动拉起。
+- 查看类接口（设备/任务/分组列表、状态、截图）所有登录用户可用
+- 后端 `@perm_required` / `@admin_required` 拦截并返回 403；前端用 `data-perm` 属性与 `_can(perm)` 隐藏入口（**仅隐藏，安全依赖后端**）
+- 不能删除/降级最后一个管理员

 ---

-## 任务系统
+## 任务与步骤

-### 抖音养号（douyin_nurture）
+`generic_steps` 的执行内容全在 `params.steps`（JSON 数组），由步骤编辑器产出。**没有默认步骤**——空步骤任务执行时会明确报错。

-自动观看抖音视频，按配置随机执行点赞操作。参数（在 `tasks/douyin/task.py` 顶部）：
+**24 种步骤**（完整参数见 [doc/TASK_DEV.md](doc/TASK_DEV.md)）：

-| 参数 | 默认值 | 说明 |
+| 类别 | 步骤 |
+|------|------|
+| 屏幕 | `screen_on` 亮屏 · `screen_off` 息屏 · `keep_screen` 保持亮屏 |
+| 应用与输入 | `open_app` 打开 App · `stop_app` 结束 App · `input_text` 输入文字 · `clipboard` 剪贴板注入 · `key_event` 按键 |
+| 交互 | `click` 点击元素 · `click_xy` 点击坐标 · `long_click` 长按 · `swipe` 滑动 · `swipe_until` 滑动直到元素出现 · `wait_el` 等待元素 · `wait` 等待时长 |
+| 流程 | `loop` 循环块 · `group` 动作组 · `if_el` 条件判断（元素 / **OCR 识别** / 屏幕状态 / 前台App / **去重**）· `mark_done` 记为已做（配套去重） |
+
+要点：
+
+- 每一步都可有 `probability`（0-100，默认 100）决定本次是否执行
+- 容器类步骤（`loop`/`group`/`if_el`）可嵌套，**深度上限 5 层**
+- 选择器支持 `xpath` / `description` / `text` / `resourceId` / `descriptionContains` / `className`（`ocr` 仅条件判断）
+- **优先用文字/id 定位**，坐标 (`click_xy`) 是最脆的方式
+- 未知步骤类型、缺必填参数只告警跳过，不会中断任务链（排查时留意"看起来成功但没做事"）
+
+---
+
+## AI 与 MCP
+
+### AI 控制台
+
+在「AI 控制台」选一台设备，用自然语言下指令，AI 通过 MCP 工具看屏幕、点按、输入，边做边把过程流式显示出来。配置（模型 / API Key / 默认设备 / 最大步数）存在数据库 `app_meta`，不落 `.env`。
+
+自带两个"自进化记忆"：
+
+- **经验库**：任务成功后把操作套路蒸馏成配方，下次相似任务自动召回注入；每日 03:47 由 AI 巡检建议清理（删除永远需人工确认）
+- **动作库**：把成功步骤沉淀为带元素定位的命名动作（禁坐标），可复用、可编辑
+
+详细机制见 [doc/AI_CONSOLE.md](doc/AI_CONSOLE.md)。
+
+### MCP（外部 AI 接入）
+
+MCP Server 监听 `:8033`，暴露 20 个 `de_*` 工具（截屏、点击、滑动、输入、OCR、元素树、应用管理等）。写操作需 `MCP_ALLOW_WRITE=1`；设备正在跑任务时拒绝（`device_busy`）；每次调用写审计日志。
+
+```bash
+# 本机手动启动（生产容器由 scripts/start.sh 自动拉起）
+MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
+  python -m mcp_server.mcp_server
+```
+
+工具清单与接入示例见 [doc/MCP.md](doc/MCP.md)。
+
+---
+
+## 配置说明
+
+**密钥类配置统一放项目根 `.env`**（不入 git；模板见 [.env.example](.env.example)）。加载规则：逐行解析后用 `os.environ.setdefault` 注入，**真实环境变量优先**。
+
+| 配置 | 默认值 | 说明 |
 |------|--------|------|
-| `watch_count` | 80 | 观看视频数量（0=不限，靠时长停止） |
-| `watch_min` / `watch_max` | 5.0 / 35.0 | 单视频观看时长范围（秒） |
-| `max_duration` | 0 | 最大运行时长（秒），0=不限时 |
-| `swipe_min` / `swipe_max` | 0.25 / 0.50 | 上滑手势时长范围（秒） |
-| `gap_min` / `gap_max` | 1.0 / 3.0 | 视频间隔时长范围（秒） |
-| `actions.like.enabled` | true | 是否启用点赞 |
-| `actions.like.params.rate` | 0.3 | 点赞概率（0~1） |
-| `actions.like.params.method` | by_element | 点赞方式：by_element(找红心) / double_click(双击) |
+| `WEB_SECRET_KEY` | 未配置则随机 | 会话密钥；不配则每次重启登录态失效（**生产必须固定**） |
+| `WEB_HOST` / `WEB_PORT` | `0.0.0.0` / `18050` | Web 监听（**常量，改 config.py**） |
+| `ADB_PATH` | 自动识别 `bin/adb/` | adb 二进制（常量，按平台自动选） |
+| `DATA_DIR` / `APK_DIR` | `data/` / `data/apks/` | 持久化目录（常量） |
+| `USB_ADB_HOST` / `USB_ADB_PORT` | `100.100.10.1` / `5037` | USB 设备所在的部署机（远程 adb server） |
+| `DISCOVERY_PORT` / `DISCOVERY_INTERVAL` | `5555` / `60` | 设备自动发现（网段也在工具页配置，存 `app_meta`） |
+| `TAILSCALE_API_KEY` / `TAILSCALE_TAILNET` | 空 | Tailscale 管理功能 |
+| `WEB_SECRET_KEY` 之外的一切密钥 | — | 一律进 `.env`，**不要写进 config.py** |

-终止条件（哪个先到就停）：`watch_count` 数量到 / `max_duration` 时长到 / 手动停止。
+> **任务参数不放 config.py**——放各自 `tasks/<name>/task.py` 顶部的 `DEFAULT_PARAMS`。

-### 通用步骤（generic_steps）
-
-通过可视化步骤编辑器编排任务流程，worker 按步骤顺序执行。支持的步骤类型：
-
-| 步骤类型 | 说明 |
-|---------|------|
-| `open_app` | 启动 App（指定包名，可选等待首页） |
-| `swipe` | 滑动（上/下/左/右，可配置时长） |
-| `click` | 点击元素（支持 xpath/description/resourceId/text 选择器） |
-| `input_text` | 输入文字（随机候选/固定文字） |
-| `wait` | 等待（可配置时长范围） |
-| `loop` | 循环块（含子步骤，可配置循环次数） |
-| `group` | 动作组（含子步骤，按序执行一次） |
-
-### 新增 App 任务
-
-参照 `tasks/douyin/` 结构，6 步即可新增一个 App 任务，详见 [doc/TASK_DEV.md](file:///d:/platform-tools/doc/TASK_DEV.md)。
+完整键表（含 `MCP_*` / `AGENT_*`）见 [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md) §配置速查。

 ---

-## 日志系统
+## 日志

-日志按模块分文件，自动滚动（10MB 一份，保留 5 份历史）：
+按模块分文件，单文件 10MB 滚动、保留 5 份：

-| 文件 | 模块前缀 | 内容 |
-|------|---------|------|
-| `logs/core.log` | `core.*` | STF/adb/worker/task_manager 核心程序 |
+| 文件 | 前缀 | 内容 |
+|------|------|------|
+| `logs/core.log` | `core.*` | adb / device_worker / task_manager / 设备池 |
 | `logs/task.log` | `task.*` | 任务执行（worker 业务逻辑） |
-| `logs/web.log` | `web.*` | Web 请求/管理 |
-| `logs/action.log` | `action.*` | 操作执行（点赞/评论等） |
-
-使用方式：
+| `logs/web.log` | `web.*` | Web 请求与管理操作 |
+| `logs/action.log` | `action.*` | 操作执行 |
+| `logs/notify.log` | `notify` | 通知发送（成功/失败/平台错误码） |

 ```python
 from core.logger import get_logger
-log = get_logger("task.douyin")    # 写入 task.log
-log.info(f"[{self.serial}] 开始任务")
+log = get_logger("task.generic")   # → logs/task.log
 ```

-Web 后台"日志"Tab 可实时查看各模块日志。
+「日志」Tab 可在线查看：文件下拉包含 `.1/.2…` 滚动历史（可回溯更早的日志），
+支持关键字（命中高亮）/最低级别/时间范围过滤，点「下载」导出当前筛选结果
+（无筛选就是整个文件）。读取逻辑在 `core/logger.py` 的 `list_log_files()/query_log()/
+read_log_text()`，`file` 参数走白名单，不接受任意路径。

---
-
-## 常用脚本
-
-| 脚本 | 用途 |
-|------|------|
-| `python web_server.py` | 启动 Web 管理后台 |
-| `python main.py` | 命令行跑一次抖音养号（单设备，不走 web） |
-| `python create_task.py` | 创建"抖音定时8-9点"任务（示例脚本） |
-| `python scripts/cleanup.py` | 清理 STF 残留设备占用（强杀进程后用） |
-| `python scripts/pack.py` | 打包项目为 zip（排除日志/数据库/APK） |
-| `start_web.bat` | Windows 一键启动（提权 + 防火墙规则） |
+「日志 → 步骤明细」是**结构化**的另一半：每一次步骤执行落一行 `task_step_log`
+（设备/任务/步骤路径/结果/耗时/选择器），因此能按设备、任务、结果、时间过滤，
+也能按 `run_id` 归组看"这一次运行为什么失败"、导出 CSV。写入是异步的
+（`core/step_log.py`，任务线程只入队，不阻塞执行），保留 14 天、单次运行最多
+2000 条 —— 这两个上限决定这张表（以及备份包）能长多大。

 ---

 ## 常见问题

-### 端口被占用（WinError 10013/10048）
-
-`web_server.py` 会自动重试候选端口（原端口 → 127.0.0.1:原端口 → 127.0.0.1:原端口+1~+5）。如果全部失败，检查 Windows 动态端口范围：
-
-```bash
-netsh interface ipv4 show excludedportrange protocol=tcp
-```
-
-修改 `config.py` 中的 `WEB_PORT` 到一个不在排除范围内的端口。
-
-### STF 设备显示离线但实际在线
-
-STF 状态有缓存，`present=True` 不代表设备真在线。用"扫描前台App"按钮复测，或直接尝试执行任务。
-
-### 设备一直被占用无法释放
-
-运行清理脚本：
-
-```bash
-python scripts/cleanup.py
-```
-
-会释放当前账户占用的所有设备。
-
-### u2.connect 卡死
-
-`u2.connect()` 在 atx-agent 无响应时会永久 hang。基类已用 `ThreadPoolExecutor + 30 秒超时` 保护，超时自动放弃。如果频繁超时，检查设备 atx-agent 是否正常（重启设备或重新推送 atx-agent）。
-
-### 任务运行中看门狗误杀
-
-看门狗 120 秒无心跳会标记卡死。长耗时操作（如长视频等待）需在循环内周期性调用 `self.heartbeat()`。
-
-### 中文输入失败
-
-uiautomator2 默认 IME 不支持中文，需切到 FastInput 输入法：
-
-```python
-try:
-    d.set_fastinput_ime(True)
-    d.send_keys("中文内容")
-finally:
-    d.set_fastinput_ime(False)
-```
-
-### 修改 core/ 后不生效
-
-`web_server.py` 以 `debug=False` 运行，Python 不会热重载。修改 `core/` 目录下的文件后**必须重启 web_server 进程**。
-
-### 元素抓取按钮不可用
-
-依赖 uiautodev 服务（端口 20242）。确保已安装 `pip install uiautodev`。`web_server.py` 启动时会自动拉起该服务。
+| 现象 | 处理 |
+|------|------|
+| 端口被占用（WinError 10013/10048） | 启动会自动回退候选端口（`18050` → `127.0.0.1:18050` → `127.0.0.1:18051..18055`）；仍失败则改 `WEB_PORT`（注意 Windows 动态端口排除段） |
+| 设备显示离线 | 「工具 → 设备池管理」一键重连；确认设备在线且同一网络（生产走 Tailscale 同 tailnet） |
+| 新加的设备不被调度 | 必须**加入设备池**（仅 adb 连上不算）；确认该设备为"启用"状态 |
+| `u2.connect` 卡死 | 基类有 30s 超时保护；频繁超时说明 atx-agent 异常，重启设备或重新推送 |
+| 任务运行中被看门狗标记卡死 | 看门狗 120s 无心跳即判定；长循环内需周期性 `self.heartbeat()` |
+| 任务"成功"但什么都没做 | 步骤类型未知/缺必填参数会被**告警跳过**；查 `logs/task.log` 的 WARNING |
+| 中文输入失败 | u2 默认 IME 不支持中文，需 `set_fastinput_ime(True)`（`input_text` 步骤已处理） |
+| 改了 `core/` 不生效 | 服务以 `debug=False` 运行、不热重载；**必须重启**。前端改动还需强刷浏览器（Ctrl+Shift+R） |
+| 元素抓取按钮不可用 | 依赖本机 uiautodev（:20242），`web_server.py` 启动时自动拉起；未安装时 `pip install uiautodev` |

 ---

-## 更多文档
+## 文档索引
+
+**完整文档入口 → [doc/README.md](doc/README.md)**（文档地图、阅读路径、维护约定）

 | 文档 | 内容 |
 |------|------|
-| [doc/TASK_DEV.md](file:///d:/platform-tools/doc/TASK_DEV.md) | 任务开发指南（新增 App 任务的完整模板和规范） |
-| [doc/ARCHITECTURE.md](file:///d:/platform-tools/doc/ARCHITECTURE.md) | 架构详解（分层设计、数据流、关键设计决策） |
-| [doc/DEPLOY.md](file:///d:/platform-tools/doc/DEPLOY.md) | 部署指南（环境准备、STF 配置、生产部署） |
-| [doc/API.md](file:///d:/platform-tools/doc/API.md) | API 接口文档（全部 HTTP 接口说明） |
+| [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) | 任务与步骤开发（24 种步骤、公共巡检、录制回放、去重、选择器、自定义动作） |
+| [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) | 部署与运维（含生产容器、备份导入、故障排查） |
+| [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md) | 开发手册（git 流程、技术红线、本地开发、文档同步约定） |
+| [doc/STF_REMOVAL.md](doc/STF_REMOVAL.md) | 摘除 OpenSTF 的历史记录 |
+
+> ⚠️ **改动必须同步文档**：功能/配置/接口/表结构的任何增删改，都要在同一个 commit 里更新对应文档（红线，详见 [doc/README.md](doc/README.md) §3）。
+> ⚠️ **git 操作需负责人确认**（含 push 到 dev），详见 [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md)。

 ---

@@ -417,10 +425,10 @@ finally:

 | 组件 | 用途 |
 |------|------|
-| Flask + Flask-Login | Web 后台 + 用户认证 |
-| Flask-SQLAlchemy | SQLite 数据持久化 |
-| APScheduler | 定时任务调度 |
-| uiautomator2 | Android UI 自动化 |
-| uiautodev | UI 元素抓取（步骤编辑器"抓取元素"） |
+| Flask + Flask-Login + Flask-SQLAlchemy | Web 后台 / 认证 / SQLite ORM |
+| APScheduler | 定时任务调度（任务 + 经验巡检两个独立调度器） |
+| uiautomator2 / uiautodev | Android UI 自动化 / 元素抓取 |
+| rapidocr_onnxruntime (+ opencv-headless) | 屏幕 OCR |
 | pyaxmlparser | APK 元信息解析 |
-| OpenSTF | 设备农场管理（占用/释放/远程 ADB） |
+| fastmcp | MCP Server（Streamable HTTP）+ AI 控制台 Agent |
+| adb（项目自带 `bin/adb/`） | 设备连接与底层操作 |
@@ -4,12 +4,34 @@
 放各自 tasks/xxx.py 顶部，保持每个任务自包含、互不干扰。

 改 STF 地址/token、adb 路径、web 端口都改这里。
+
+安全：STF_TOKEN / WEB_SECRET_KEY 建议用环境变量注入（生产不要提交到 git）。
+支持 `.env` 文件（项目根目录），也可直接 `export STF_TOKEN=xxx`。
 """
 import os

-# ================== STF 配置 ==================
-STF_URL = "http://192.168.20.220:7100"
-STF_TOKEN = "9024544b571647d3a6b09dab5dbfcb28bfd950f5b659400394e44e7217b7051b"
+# 可选加载 .env 文件（不存在则忽略）
+_env_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), ".env")
+if os.path.exists(_env_path):
+    try:
+        with open(_env_path, encoding="utf-8") as _f:
+            for _line in _f:
+                _line = _line.strip()
+                if _line and not _line.startswith("#") and "=" in _line:
+                    _k, _v = _line.split("=", 1)
+                    os.environ.setdefault(_k.strip(), _v.strip())
+    except OSError:
+        pass
+
+
+def _env(key, default):
+    """读环境变量，未设置则返回默认值。"""
+    return os.environ.get(key, default)
+
+
+# ================== STF 配置（已废弃，阶段 3 摘除 STF 后仅保留供历史参考） ==================
+STF_URL = _env("STF_URL", "")
+STF_TOKEN = _env("STF_TOKEN", "")   # 写入 .env，不要提交到 git

 # ================== adb 路径 ==================
 # adb 二进制及依赖统一放在 bin/adb/ 下
@@ -25,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）
@@ -37,3 +86,65 @@ DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data")

 # APK 文件存储目录（应用管理功能）
 APK_DIR = os.path.join(DATA_DIR, "apks")
+
+# 视频发布计划的素材目录（发布计划功能）。**支持 env 覆盖**，理由同下面三个：
+# 自动化测试必须把素材目录指到临时位置，否则测试上传的视频会落进用户真实数据目录。
+VIDEO_DIR = _env("DATA_VIDEO_DIR", "") or os.path.join(DATA_DIR, "videos")
+
+# ================== 抖音「我」页面的昵称控件（发布计划按名字发） ==================
+# **抓一次填这里**（用「抓取元素」抓抖音「我」页面上的昵称那个 TextView）。
+# 一处配置、三处一致：发布任务骨架的「读取本机账号名字」步骤默认值、
+# 「切换账号」的切后校验、以及「发布计划 → 一键推送（按名字找设备）」的实时探测。
+# 任务步骤里仍可单独改（存进那一步的参数），这里只是**默认值**。
+# 留空 = 还没抓：相关步骤会明确报"请抓取元素"，绝不会猜一个名字去发。
+DOUYIN_NAME_SELECTOR_TYPE = _env("DOUYIN_NAME_SELECTOR_TYPE", "xpath")
+DOUYIN_NAME_SELECTOR_VALUE = _env("DOUYIN_NAME_SELECTOR_VALUE", "")
+
+# 「我」页面 →「切换账号」列表那个入口（同样是**抓一次填这里**）：自动切号要用。
+# 留空 = 「切换账号」步骤会明确报"请抓取元素"并跳过（不会瞎点）。
+DOUYIN_SWITCH_SELECTOR_TYPE = _env("DOUYIN_SWITCH_SELECTOR_TYPE", "xpath")
+DOUYIN_SWITCH_SELECTOR_VALUE = _env("DOUYIN_SWITCH_SELECTOR_VALUE", "")
+
+# 单次请求体上限（字节）。**必须大于现有 APK 上传的最大包**（实测 336MB），
+# 否则「应用管理」的 APK 上传会被一起卡死。默认 2GiB：一个视频 + 余量。
+MAX_CONTENT_LENGTH = int(_env("MAX_UPLOAD_MB", "2048")) * 1024 * 1024
+
+# ================== 系统数据备份（导出/导入） ==================
+# 导出 zip 与恢复前快照存放；导入暂存目录；待下次启动生效的恢复目录
+# （运行时产物，不入 git，见 .gitignore data/backups 等）
+#
+# 三个目录都支持用环境变量改到别处——自动化测试必须把恢复目录指到临时位置，
+# 否则测试造出来的"待生效恢复任务"会在服务下次重启时被真当成用户的操作消费掉。
+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）。
+STF_SSH_TARGET = _env("STF_SSH_TARGET", "")
+STF_SSH_PASSWORD = _env("STF_SSH_PASSWORD", "")
+STF_DOCKER_CONTAINER = _env("STF_DOCKER_CONTAINER", "")
+STF_ADB_CONTAINER = _env("STF_ADB_CONTAINER", "")
+STF_SCRIPT_PATH = _env("STF_SCRIPT_PATH", "")
+
+# ================== USB 设备远程 adb server（阶段 2） ==================
+# USB 设备插在 220（STF 主机）上，本机 adb 看不到；220 的 adb 容器是 host 网络
+# 模式，5037 已监听所有网卡（含 Tailscale），平台用 adb -H/-P 直接驱动。
+# 平台自身 USB（serial 无冒号且在本机 adb 里）不受影响，仍走本地。
+USB_ADB_HOST = _env("USB_ADB_HOST", "100.100.10.1")   # 220 的 Tailscale IP
+USB_ADB_PORT = int(_env("USB_ADB_PORT", "5037"))
+
+# ================== Tailscale 管理（工具页） ==================
+# 调用官方 API v2 管理 tailnet 设备。配置从 .env 读取：
+#   TAILSCALE_API_KEY：后台 → Settings → API Access Tokens 生成（或 OAuth client_id:secret）
+#   TAILSCALE_TAILNET：tailnet 名称/ID，个人账号一般是登录邮箱前缀
+# 安全：密钥用环境变量/.env 注入，不要写死在代码或提交到 git。
+TAILSCALE_API_KEY = _env("TAILSCALE_API_KEY", "")   # 写入 .env，不要提交到 git
+TAILSCALE_TAILNET = _env("TAILSCALE_TAILNET", "")
+
+# ================== 设备自动发现 ==================
+# 定时扫描网段中开放 adb 5555 的设备 → 待连接池（用户确认后才加入正式池）。
+# 网段默认：局域网 + Tailscale；可在工具页设备池面板修改（存 app_meta）。
+DISCOVERY_PORT = int(_env("DISCOVERY_PORT", "5555"))
+DISCOVERY_SUBNETS = ["192.168.20.0/24", "100.100.10.0/24"]
+DISCOVERY_INTERVAL = int(_env("DISCOVERY_INTERVAL", "60"))
@@ -1,8 +1,7 @@
 """core 包：基础设施层。

-  config         — 全局配置常量（STF、adb 路径、养号参数）
+  config         — 全局配置常量（adb 路径、设备发现等）
  adb_helper     — adb 命令封装（并发安全）
-  stf_client     — OpenSTF REST API 客户端
-  device_worker  — 设备生命周期 + 养号 worker + 全局状态注册表
+  device_worker  — 设备生命周期 + 任务 worker 基类 + 全局状态注册表
  task_manager   — 任务管理框架（分组/计划/调度/重试/持久化）
 """
@@ -0,0 +1,158 @@
+"""实时探测"这台设备现在登的是哪个抖音号"（**按名字找设备**用）。
+
+**谁用它**：人工入口 —— 「发布计划」页的「一键推送（按名字找设备）」要先知道
+"哪台在线设备现在登着这个名字"，才能把素材推过去。
+**自动任务不靠它**：任务里的「读取本机账号名字」永远是现场读屏幕（缓存旧了也不能影响发布正确性）。
+
+它只做**只读/幂等**的动作：连设备 → 需要时把抖音拉到前台 → 点「我」→ 读昵称控件 → 清洗。
+**绝不登录、绝不滑块、绝不改设备设置**；连不上/读不到只报那一台，不影响别的设备。
+也绝不 `kill-server` / `disconnect`（技术约束红线）。
+
+昵称控件在 `config.DOUYIN_NAME_SELECTOR_VALUE`（**抓一次填 .env**，与任务骨架同一处配置）；
+没填就明确报"还没抓"，不去猜。
+"""
+import time
+from concurrent.futures import ThreadPoolExecutor
+
+from config import DOUYIN_NAME_SELECTOR_TYPE, DOUYIN_NAME_SELECTOR_VALUE
+from core import u2_helper
+from core.logger import get_logger
+
+_log = get_logger("core.account_probe")
+
+DOUYIN_PKG = "com.ss.android.ugc.aweme"
+_CONNECT_TIMEOUT = 20        # u2.connect 超时（秒）；设备端 u2 服务没响应时别把请求挂死
+_STEP_WAIT = 2.5             # 进「我」页面后等它渲染完
+
+
+def _connect(serial, timeout=_CONNECT_TIMEOUT):
+    """带超时的 u2.connect。
+
+    ⚠ 用**手动 shutdown(wait=False)** —— `with ThreadPoolExecutor(...)` 退出时会
+    `shutdown(wait=True)`，超时线程不死它就跟着等，30 秒的"超时"会变成真卡住
+    （`core/device_worker` 里踩过这个坑）。
+    """
+    import uiautomator2 as u2
+    pool = ThreadPoolExecutor(max_workers=1)
+    try:
+        return pool.submit(u2.connect, serial).result(timeout=timeout)
+    finally:
+        pool.shutdown(wait=False)
+
+
+def probe_one(serial, click_me=True):
+    """读一台设备当前登录的抖音名字。返回 `{serial, name, error}`。
+
+    `name` 非空 = 读到了；`error` 非空 = 没读到（人话原因，给界面直接显示）。
+    """
+    if not DOUYIN_NAME_SELECTOR_VALUE:
+        return {"serial": serial, "name": "",
+                "error": "还没抓抖音昵称控件：在 .env 里填 DOUYIN_NAME_SELECTOR_VALUE"
+                         "（抓取元素抓一下「我」页面上的昵称）"}
+    d = None
+    try:
+        d = _connect(serial)
+    except Exception as e:
+        return {"serial": serial, "name": "",
+                "error": f"连不上设备（u2 {_CONNECT_TIMEOUT}s 超时）：{type(e).__name__}"}
+    try:
+        pkg = u2_helper.current_package(d)
+        if pkg != DOUYIN_PKG:
+            # 不在抖音 → 拉到前台（幂等：已经在就什么都不做）
+            try:
+                d.app_start(DOUYIN_PKG, wait=True)
+            except Exception as e:
+                return {"serial": serial, "name": "",
+                        "error": f"打不开抖音：{type(e).__name__}: {str(e)[:60]}"}
+            time.sleep(4)
+        if click_me:
+            u2_helper.find_and_click(d, timeout=3,
+                                     **{"descriptionContains": "我"})
+        time.sleep(_STEP_WAIT)
+        from core import video_plan as vp
+        if DOUYIN_NAME_SELECTOR_TYPE == "xpath":
+            el = d.xpath(DOUYIN_NAME_SELECTOR_VALUE)
+            raw = el.get_text() if el.exists else ""
+        else:
+            el = d(**{DOUYIN_NAME_SELECTOR_TYPE: DOUYIN_NAME_SELECTOR_VALUE})
+            raw = el.get_text(timeout=3) if el.exists(timeout=3) else ""
+        name = vp.clean_account_name(raw)
+        if not name:
+            return {"serial": serial, "name": "",
+                    "error": f"读到空（元素原文 {raw!r}）—— 昵称控件的选择器可能抓错了"}
+        return {"serial": serial, "name": name, "error": ""}
+    except Exception as e:
+        return {"serial": serial, "name": "",
+                "error": f"读取失败：{type(e).__name__}: {str(e)[:80]}"}
+    finally:
+        # **不 disconnect、不 kill-server**（红线）：u2 的连接自己会超时回收
+        pass
+
+
+def busy_serials():
+    """正在跑任务/正在连接的设备（探测要跳过它们：抢屏会打断任务）。"""
+    from core import device_worker
+    out = set()
+    try:
+        for s in device_worker.get_all_worker_status():
+            if (s.get("status") or "") in ("running", "connecting"):
+                out.add(s.get("serial") or "")
+    except Exception as e:
+        _log.warning(f"读设备运行状态失败（按「都不忙」处理）: {e}")
+    return {x for x in out if x}
+
+
+def probe_online(serials=None, skip_busy=True, workers=4):
+    """并行探测多台设备。返回 `{serial: {serial, name, error}}`。
+
+    · `serials=None` → 取设备池里**在线且启用**的设备（`device_pool.list_ready()`）
+    · `skip_busy=True`（默认）→ 跳过正在跑任务/连接中的设备（别抢它们的屏）
+    · 单台失败只影响那一台；顺序按传入/池里的顺序
+    """
+    from core import device_pool
+    if serials is None:
+        try:
+            serials = list(device_pool.list_ready())
+        except Exception as e:
+            _log.warning(f"取在线设备失败: {e}")
+            return {}
+    serials = [s for s in (serials or []) if s]
+    if skip_busy:
+        busy = busy_serials()
+        if busy:
+            _log.info(f"探测跳过正在跑任务的设备：{'、'.join(sorted(busy))}")
+        serials = [s for s in serials if s not in busy]
+    out = {}
+    if not serials:
+        return out
+    with ThreadPoolExecutor(max_workers=max(1, min(workers, len(serials)))) as pool:
+        for r in pool.map(probe_one, serials):
+            out[r["serial"]] = r
+    return out
+
+
+def cache_names(result):
+    """把探测结果写进 `device.cur_account_name/cur_name_at`（**只用于人工入口的设备建议**）。
+
+    ⚠ 必须在 **Flask app context** 里调用（web 请求线程本身就有；脚本里自己推）。
+    探测失败的那台**不清空旧值**（旧值好歹是个线索，界面上带时间戳显示）。
+    """
+    from core.models import Device, db
+    try:
+        now = time.strftime("%Y-%m-%d %H:%M:%S")
+        for serial, r in (result or {}).items():
+            name = (r or {}).get("name") or ""
+            if not name:
+                continue
+            row = Device.query.get(serial)
+            if not row:
+                continue
+            row.cur_account_name = name[:80]
+            row.cur_name_at = now
+        db.session.commit()
+    except Exception as e:
+        _log.warning(f"写设备当前账号缓存失败（不影响探测结果）: {e}")
+        try:
+            db.session.rollback()
+        except Exception:
+            pass
@@ -1,7 +1,7 @@
 """全局操作框架：所有 app 任务共用的 Action 基类与注册机制。

 为什么放这里：
-  抖音的点赞/评论 xpath 只适用抖音，留在 tasks/douyin/actions/。
+  某个 app 专属的 xpath 只适用那个 app，留在 tasks/<app>/actions/。
  但"操作"的抽象（BaseAction 接口、概率触发、注册机制）是通用的，
  放这里让所有 app 任务共享同一套操作开发范式。

@@ -3,11 +3,11 @@
 设计要点：
  1. BaseAction 定义统一接口：execute(d, params, worker) -> bool
  2. 每个 app 任务有自己的注册表（create_action_registry），
-     互不污染——抖音的 like 和快手的 like 各注册各的。
+     互不污染——A 应用的 like 和 B 应用的 like 各注册各的。
  3. 概率触发、状态上报等通用逻辑放这里，子类不重复写。
  4. ActionContext 封装执行上下文，方便扩展（传 d/worker/进度/计数器）。

-新增 app 专属操作步骤（照着 tasks/douyin/actions/like.py 抄）：
+新增 app 专属操作步骤（在 tasks/<app>/actions/ 下新建，参考该包已有实现）：

  1. 在 tasks/<app>/actions/ 下新建 my_action.py
  2. 写一个 BaseAction 子类，用 @register_action 装饰，实现 execute：
@@ -19,18 +19,39 @@ _ADB_LOCK = threading.Lock()
 _ADB_TIMEOUT = 30


-def _adb(*args):
+def _adb(*args, timeout=_ADB_TIMEOUT):
    """执行 adb 命令，返回 (stdout+stderr) 文本。不用 shell=True，避免子进程环境问题。

    用 bytes 模式自己解码（Windows 下 subprocess text=True 会用 GBK 读 adb 输出，
    遇到非 GBK 字节会崩溃）。
    带 30s 超时：adb connect 到不可达地址可能挂很久，超时返回空串由调用方处理。
+    timeout 可覆盖（扫描验证等非关键路径用短超时快速失败）。
    """
    try:
-        r = subprocess.run([ADB_PATH, *args], capture_output=True, timeout=_ADB_TIMEOUT)
+        r = subprocess.run([ADB_PATH, *args], capture_output=True, timeout=timeout)
    except subprocess.TimeoutExpired:
-        _log.warning(f"adb {' '.join(args)} 超时 {_ADB_TIMEOUT}s")
+        _log.warning(f"adb {' '.join(args)} 超时 {timeout}s")
        return ""
+    return _decode(r)
+
+
+def _adb_remote(host, port, *args):
+    """在远程 adb server（如 220）上执行 adb 命令，返回文本。
+
+    USB 设备插在 220，本机 adb server 看不到，必须 -H/-P 指向 220 的 adb server
+    （host 网络模式，5037 全接口监听，Tailscale 可达）。超时语义同 _adb。
+    """
+    try:
+        r = subprocess.run([ADB_PATH, "-H", host, "-P", str(port), *args],
+                           capture_output=True, timeout=_ADB_TIMEOUT)
+    except subprocess.TimeoutExpired:
+        _log.warning(f"adb -H {host} -P {port} {' '.join(args)} 超时 {_ADB_TIMEOUT}s")
+        return ""
+    return _decode(r)
+
+
+def _decode(r):
+    """subprocess 结果解码（Windows GBK 兼容）。"""
    out = (r.stdout or b"") + (r.stderr or b"")
    try:
        return out.decode("utf-8", errors="replace").strip()
@@ -77,6 +98,41 @@ def get_foreground_app(remote_adb_url, timeout=3):
        return None


+def get_foreground_app_remote(host, port, serial, timeout=3):
+    """远程 adb server（220）上设备的前台 App（USB 设备用）。
+
+    与 get_foreground_app 同逻辑，只是 adb 指向远程 server（-H/-P）。
+    """
+    if not serial:
+        return None
+    try:
+        r = subprocess.run(
+            [ADB_PATH, "-H", host, "-P", str(port), "-s", serial, "shell",
+             "dumpsys window | grep mCurrentFocus"],
+            capture_output=True, timeout=timeout
+        )
+        out = ((r.stdout or b"") + (r.stderr or b"")).decode("utf-8", errors="replace").strip()
+        if not out:
+            return None
+        low = out.lower()
+        if "device offline" in low or "device not found" in low or "error:" in low:
+            return None
+        for line in out.split("\n"):
+            if "mCurrentFocus" not in line:
+                continue
+            m = re.search(r'\bu0\s+(\S+)', line)
+            if m:
+                token = m.group(1).rstrip("}")
+                if "/" in token:
+                    return token.split("/")[0]
+                return token or None
+        return None
+    except subprocess.TimeoutExpired:
+        return None
+    except Exception:
+        return None
+
+
 def adb_connect(remote_adb_url, retries=5):
    """adb connect（带重试）。返回 True/False。

@@ -102,16 +158,18 @@ def _try_connect(remote_adb_url, retries):
    return False


-def adb_connect_light(remote_adb_url):
-    """轻量 adb connect（扫描专用）：单次尝试，不重试，绝不 kill-server。
+def adb_connect_light(remote_adb_url, timeout=5):
+    """轻量 adb connect（扫描/验证专用）：单次尝试，不重试，绝不 kill-server。

    与 adb_connect 的区别：
      - 不重试：失败立即返回 False
      - 不 kill-server：避免断开其他 worker 正在使用的 ADB 连接
+      - 短超时（默认 5s）：验证场景（设备发现）连不上的主机快速放弃，
+        避免每台卡 30s 拖慢整轮发现并长时间占用全局 adb 锁
    用于前台 App 扫描等非关键路径，连不上就跳过，不影响正在运行的任务。
    """
    with _ADB_LOCK:
-        out = _adb("connect", remote_adb_url)
+        out = _adb("connect", remote_adb_url, timeout=timeout)
        if "connected" in out.lower() and "failed" not in out.lower():
            return True
        return False
@@ -22,20 +22,25 @@
 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 .stf_client import STFClient
 from .device_worker import get_all_worker_status

 _log = get_logger("core.apk")

 # adb install 超时（秒）。大 APK 安装慢，给 5 分钟
 _INSTALL_TIMEOUT = 300
+# 分块推送"多久没有任何字节被接收"就算链路卡死（秒）。注意这是**停滞**判据，
+# 不是总时长：正常推送会不断刷新它。
+_PUSH_STALL_TIMEOUT = 90
 # 并发安装数
 _INSTALL_CONCURRENCY = 5

@@ -43,8 +48,7 @@ _INSTALL_CONCURRENCY = 5
 class ApkManager:
    """APK 文件管理 + 批量安装。"""

-    def __init__(self, stf_client=None, app=None):
-        self.stf = stf_client or STFClient()
+    def __init__(self, app=None):
        self.app = app  # Flask app，用于 db context
        os.makedirs(APK_DIR, exist_ok=True)
        self._lock = threading.Lock()
@@ -129,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()
@@ -138,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 文件和数据库记录。"""
@@ -163,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 到指定设备（后台线程执行）。
@@ -194,22 +275,32 @@ class ApkManager:
        if not serials:
            return False, "未选择设备"

-        # 获取设备信息（型号等）
-        try:
-            all_devices = {d["serial"]: d for d in self.stf.list_all_devices()}
-        except Exception:
-            all_devices = {}
+        # 设备信息（型号从 worker 状态取，池内无型号信息）
+        all_devices = {}

        # 获取 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": "",
            }
@@ -230,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,
@@ -248,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}
@@ -258,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
        # 统计
@@ -270,38 +381,80 @@ 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。

-        serial 即设备的 adb 网络地址（IP:5555），直接 adb connect 即可。
+        serial 为 adb 网络地址（IP:5555）时直接 adb connect；
+        本机 USB 有线设备（serial 无冒号，如 ZY322XXXX）已在 adb 中，无需 connect。
        不经过 STF occupy/release，安装完断开连接，app 永久保留。
        """
        from .adb_helper import _adb
        self._set_item(serial, "installing", f"正在连接 {serial}...")
        try:
-            # adb connect（带重试，设备网络可能需要几次握手）
-            connected = False
-            last_out = ""
-            for attempt in range(1, 4):  # 最多 3 次
-                out = _adb("connect", serial)
-                last_out = out
-                if "connected" in out.lower() and "failed" not in out.lower():
-                    connected = True
-                    break
-                _log.info(f"[{serial}] adb connect 第{attempt}次: {out}")
-                time.sleep(1 + attempt)
-            if not connected:
-                _log.warning(f"[{serial}] adb connect 失败: 输出={last_out}")
-                self._set_item(serial, "failed", f"adb connect 失败: {last_out[:150]}")
-                return
+            if ":" in serial:
+                # 网络设备：adb connect（带重试，设备网络可能需要几次握手）
+                connected = False
+                last_out = ""
+                for attempt in range(1, 4):  # 最多 3 次
+                    out = _adb("connect", serial)
+                    last_out = out
+                    if "connected" in out.lower() and "failed" not in out.lower():
+                        connected = True
+                        break
+                    _log.info(f"[{serial}] adb connect 第{attempt}次: {out}")
+                    time.sleep(1 + attempt)
+                if not connected:
+                    _log.warning(f"[{serial}] adb connect 失败: 输出={last_out}")
+                    self._set_item(serial, "failed", f"adb connect 失败: {last_out[:150]}")
+                    return
+            else:
+                # 本机 USB 设备：确认已在 adb devices 列表中
+                dev_out = _adb("devices")
+                if serial not in (dev_out or ""):
+                    self._set_item(serial, "failed",
+                                   "设备未在本地 adb 列表中，请检查 USB 连接/驱动")
+                    return

-            # 安装
-            self._set_item(serial, "installing", "正在安装...")
+            # 强制安装：绕过厂商安全防护（MIUI 等用 adb install 会弹"通过 USB 安装应用"
+            # 确认框需要手点；改为 推送 + pm install，shell 安装不弹窗）
+            # 1. 关闭 adb 安装校验（包校验器/安全守护拦截）
+            try:
+                _adb("-s", serial, "shell", "settings", "put", "global",
+                     "verifier_verify_adb_installs", "0")
+            except Exception:
+                pass
+            # 2. 推送 APK 到设备（分块 + 实时进度）
+            ok_push, msg_push = self._push_with_progress(serial, apk_path)
+            if not ok_push:
+                self._set_item(serial, "failed", msg_push)
+                _log.warning(f"[{serial}] APK 推送失败: {msg_push}")
+                return
+            # 3. pm install 强制安装（-r 覆盖安装 / -t 允许测试包 / -d 允许降级版本）
+            # 这一步在**设备端**解包/优化，耗时随包大小增长（抖音 336MB 实测 ~65s），
+            # 但系统没给进度接口，只能给出预期时间，别让用户以为是卡住了。
+            self._set_item(serial, "installing",
+                           "正在设备上安装...（大包要 1-2 分钟，无进度可读）")
            r = subprocess.run(
-                [ADB_PATH, "-s", serial, "install", "-r", apk_path],
+                [ADB_PATH, "-s", serial, "shell", "pm", "install", "-r", "-t", "-d",
+                 "/data/local/tmp/_install.apk"],
                capture_output=True, timeout=_INSTALL_TIMEOUT
            )
+            # 4. 清理设备临时文件（失败残留下次推送会覆盖，不影响）
+            try:
+                _adb("-s", serial, "shell", "rm", "-f", "/data/local/tmp/_install.apk")
+            except Exception:
+                pass
            out = ((r.stdout or b"") + (r.stderr or b""))
            try:
                out = out.decode("utf-8", errors="replace")
@@ -355,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:
@@ -0,0 +1,112 @@
+"""剪贴板注入公共模块（设备端 Agent 通道）。
+
+背景：Android 10+ 禁止后台（atx-agent/shell）写剪贴板——u2.set_clipboard
+调用"成功"但内容被系统静默丢弃（Android 12/13 实测）。设备端 APK 通过 am start
+启动**透明 Activity**，窗口聚焦后 setPrimaryClip；shell 身份启动 Activity 不受
+后台启动限制（广播方式在 MIUI 会被 Background activity start 拦截，必须用 am start）。
+
+**注入目标按顺序尝试**：先设备端聚合 Agent（`com.example.deviceagent`，现在的标准通道），
+再兜底老设备上可能残留的独立 ClipInject（`com.example.clipinject`）。
+两者只有一个 `--es text_b64` 的契约差异为零，所以是"换个包名再试一次"。
+
+工具页（web/tools_api.py）与任务执行器（tasks/generic/task.py）共用本模块。
+"""
+import base64
+import subprocess
+import time
+from concurrent.futures import ThreadPoolExecutor
+
+from config import ADB_PATH
+from core.adb_helper import adb_connect
+from core.logger import get_logger
+
+_log = get_logger("core.clip")
+
+# (包名, am start 目标, 给用户看的名字)；顺序 = 尝试顺序
+_CLIP_TARGETS = (
+    ("com.example.deviceagent", "com.example.deviceagent/.ClipActivity", "设备端 Agent"),
+    ("com.example.clipinject", "com.example.clipinject/.ClipActivity", "旧版 ClipInject"),
+)
+
+
+def _am_start(serial, activity, b64):
+    """拉起透明 Activity 写剪贴板。返回 (输出文本, 是否执行成功)。"""
+    try:
+        r = subprocess.run(
+            [ADB_PATH, "-s", serial, "shell", "am", "start",
+             "-n", activity, "--es", "text_b64", b64],
+            capture_output=True, timeout=30)
+    except subprocess.TimeoutExpired:
+        return "am start 超时（adb 无响应）", False
+    except Exception as e:
+        return f"{type(e).__name__}: {str(e)[:120]}", False
+    out = ((r.stdout or b"") + (r.stderr or b"")).decode(errors="replace")
+    # "Starting: Intent {…}" 后面跟 "Error type 3 / Error: Activity class … does not exist."
+    # 时也是失败——所以不能只看有没有 Starting
+    if "does not exist" in out or "unable to resolve Intent" in out or "Error type 3" in out:
+        return out, False
+    if "Error" in out or ("Starting" not in out and r.returncode != 0):
+        return out, False
+    return out, True
+
+
+def inject_clipboard(serial, text, d=None):
+    """向设备剪贴板注入文字，返回 (ok, msg)。
+
+    - 依次尝试 `_CLIP_TARGETS`（设备端 Agent → 旧版 ClipInject）：设备上装哪个用哪个，
+      两个都没有时明确报"需要装设备端 Agent"（不再只说 ClipInject，用户会以为要装老 APK）
+    - d：可选，任务执行器已持有 u2 Device 时传入复用（跳过重复连接），
+      读回验证直接用它；不传则临时 u2.connect（工具页场景，带超时保护）
+    - IP:port 设备先 adb connect（已连接自动跳过；绝不 disconnect，红线）
+    - 通道缺失 / 读回不一致都会明确报错（不再静默失败）
+    """
+    import uiautomator2 as u2
+    if ":" in serial:
+        try:
+            adb_connect(serial)
+        except Exception as e:
+            return False, f"adb 连接失败: {e}"
+    b64 = base64.b64encode(text.encode("utf-8")).decode()
+    # 1. am start 透明 Activity 写剪贴板（shell 身份，不受后台启动限制）
+    tried = []
+    for pkg, activity, label in _CLIP_TARGETS:
+        out, started = _am_start(serial, activity, b64)
+        if started:
+            if tried:
+                # 走到兜底通道：记一条，好提醒"这台设备该装 Agent 了"
+                _log.info(f"[{serial}] 剪贴板注入：{'、'.join(tried)} 都没有，"
+                          f"改用{label}（{pkg}）成功 —— 建议给这台设备装设备端 Agent")
+            break
+        if "does not exist" in out or "unable to resolve Intent" in out or "Error type 3" in out:
+            tried.append(label)
+            continue
+        # 装了但启动失败：直接报错，不再往下试（下一个包大概率也没装）
+        return False, f"am start 失败（{label}）: {out.strip()[:120]}"
+    else:
+        return False, ("设备未安装剪贴板注入通道：需要设备端 Agent"
+                       "（com.example.deviceagent）——从「应用管理 → 设备端应用商店」安装；"
+                       "旧版独立 ClipInject（com.example.clipinject）也可以，但已不再随平台分发")
+    # 2. 读回验证：**必须轮询**。透明 Activity 要等窗口拿到焦点才写（还有 800ms 兜底），
+    #    只睡一次 0.5s 会读到**上一次的剪贴板内容** → 误报"写入可能被拒"（实测踩过：
+    #    内容明明写进去了，接口却回 1 台失败）。轮询到 ~3 秒：一致即成功；
+    #    一直不一致才算真的被拒。
+    try:
+        if d is None:
+            with ThreadPoolExecutor(max_workers=1) as pool:
+                d = pool.submit(u2.connect, serial).result(timeout=30)
+    except Exception as e:
+        return True, f"已注入（读回验证不可用: {type(e).__name__}: {str(e)[:80]}）"
+    deadline = time.time() + 3.0
+    got = None
+    while True:
+        time.sleep(0.4)
+        try:
+            with ThreadPoolExecutor(max_workers=1) as pool:
+                got = pool.submit(lambda: d.clipboard).result(timeout=15)
+        except Exception as e:
+            # 读回不可用（旧版 u2/连接失败）时按写入成功处理，避免误报，但带上具体原因
+            return True, f"已注入（读回验证不可用: {type(e).__name__}: {str(e)[:80]}）"
+        if got == text:
+            return True, "已注入"
+        if time.time() >= deadline:
+            return False, f"剪贴板读回不一致（写入可能被拒）: {str(got)[:60]!r}"
@@ -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")
@@ -0,0 +1,235 @@
+"""「已做过」账本：跨设备幂等（评论不重复）+ 进度可见。
+
+**它解决什么**（用户场景）：一台手机登录多个账号、多台手机跑同一个任务，
+每天跑一次但不知道什么时候跑完，于是反复重跑 → 同一个号被做两次、有的号还没做。
+账本给出两个东西：
+  1. `check()` —— "这个身份在这个任务里做过了吗"（跨设备，多台手机共享同一份判断）
+  2. `list_marks()` —— "谁做过了、还差谁"（界面上看得见，就不用靠"一直重跑"来确认）
+
+**为什么必须靠唯一索引**：多台设备可能同时判断"没做过"。
+"先 SELECT 再 INSERT"有竞态——两台都会插进去。唯一索引 + `INSERT ... ON DUPLICATE KEY`
+（MySQL）/ `INSERT OR IGNORE`（SQLite）的**受影响行数**才是原子的判据：
+`1` = 你抢到了首次，`0` = 别人已经做过。
+
+**身份值读不到时绝不去重**（`identity is None`）：宁可漏拦一次，
+也不能让"读不到"退化成"空身份"——那会让所有设备共用一个 key，
+第一台记账后其余全部被误跳过。同理，身份值过长时也不截断（截断会让两个身份撞车）。
+
+有效期策略（`kind`）由任务级参数 `dedup_reset` 决定，**只在一处配**：
+步骤里各填一份的话，两处填不一致就会算出不用的 key、去重静默失效。
+
+DB 访问由本模块自建 app context（照 `core/device_pool.py` 的 `_ctx()`），
+调用方（任务线程 / Web 线程 / 每日清理）都不用关心。
+"""
+import time
+from datetime import datetime, timedelta
+
+from core.logger import get_logger
+from core.models import db
+
+_log = get_logger("core.dedup")
+
+# 有效期策略
+KIND_DAY = "day"        # 每天一次（默认；"每天跑一次"的场景）
+KIND_HOURS = "hours"    # 每 N 小时一次
+KIND_ALL = "all"        # 只做一次（永久）
+RESET_KINDS = (KIND_DAY, KIND_ALL, KIND_HOURS)
+DEFAULT_HOURS = 6
+# 账本保留期：只影响 day/hours 桶（它们过期就没意义了）；
+# **kind='all' 的记录永不清理**——清了就等于"只做一次"失效
+KEEP_DAYS = 180
+# scope_key 上限（= DoneMark.scope_key 列宽）。超了不去重、只告警：
+# 截断会让两个不同身份撞成同一个 key，进而误跳过
+MAX_KEY_LEN = 290
+
+_app = None
+
+
+def init_app(app):
+    """web_server 启动时调用：绑 app（后台线程访问 db 要自推 context）。"""
+    global _app
+    _app = app
+
+
+def _ctx():
+    if _app is None:
+        raise RuntimeError("dedup 未关联 Flask app（web_server 启动时调用 init_app）")
+    return _app.app_context()
+
+
+# ================== 唯一键 ==================
+def build_key(job_id, identity, kind=KIND_DAY, hours=DEFAULT_HOURS, now=None):
+    """算唯一键：`任务 | 身份 | 时间桶`。
+
+    桶只影响"多久之后算新的一轮"：
+      · day   → `|d:2026-09-24`（本地日期，跟着自然日走）
+      · hours → `|h6:4939219`（epoch // (N*3600)，改 N 就换了桶）
+      · all   → `|all`（无桶，永远命中同一个 key）
+    """
+    now = time.time() if now is None else now
+    base = f"{(job_id or '').strip()}|{(identity or '').strip()}"
+    if kind == KIND_ALL:
+        return base + "|all"
+    if kind == KIND_HOURS:
+        h = max(1, int(hours or DEFAULT_HOURS))
+        return f"{base}|h{h}:{int(now // (h * 3600))}"
+    return base + "|d:" + time.strftime("%Y-%m-%d", time.localtime(now))
+
+
+def _key_or_none(job_id, identity, kind, hours):
+    """算 key 并做长度体检；超长返回 None（调用方按"不去重"处理，不截断）。"""
+    if not (identity or "").strip():
+        return None
+    key = build_key(job_id, identity, kind, hours)
+    if len(key) > MAX_KEY_LEN:
+        _log.warning(f"去重键过长（{len(key)} 字符）→ 本次不去重，避免截断后两个身份撞车: {key[:80]}…")
+        return None
+    return key
+
+
+# ================== 查 / 记 ==================
+def check(job_id, identity, kind=KIND_DAY, hours=DEFAULT_HOURS):
+    """这个身份在这个任务里做过了吗？（只读）
+
+    返回 True=做过 / False=没做过。identity 为空时返回 False（不去重，照常执行）。
+    """
+    key = _key_or_none(job_id, identity, kind, hours)
+    if key is None:
+        return False
+    try:
+        with _ctx():
+            row = db.session.execute(
+                db.text("SELECT 1 FROM done_mark WHERE scope_key = :k LIMIT 1"),
+                {"k": key}).fetchone()
+            return row is not None
+    except Exception as e:
+        # 账本读失败不能拦住任务：当"没做过"放行（宁可重复，不可卡死）
+        _log.warning(f"去重检查失败（按未做过放行）: {e}")
+        return False
+
+
+def mark(job_id, identity, kind=KIND_DAY, hours=DEFAULT_HOURS,
+         serial="", device_name="", job_name=""):
+    """原子记账。返回 True=本次是首次（你抢到了）/ False=别人已经记过（或没记成）。
+
+    ⚠ **必须靠唯一索引**：不能先 check 再 insert（多台设备会同时通过）。
+    """
+    key = _key_or_none(job_id, identity, kind, hours)
+    if key is None:
+        return False
+    args = {"k": key, "kind": kind, "jid": job_id or "", "jname": job_name or "",
+            "serial": serial or "", "dname": device_name or "",
+            "ident": (identity or "").strip()[:200],
+            "ts": time.strftime("%Y-%m-%d %H:%M:%S")}
+    try:
+        with _ctx():
+            is_mysql = db.engine.dialect.name == "mysql"
+            cols = ("scope_key, kind, job_id, job_name, serial, device_name, "
+                    "identity, created_at")
+            vals = (":k, :kind, :jid, :jname, :serial, :dname, :ident, :ts")
+            if is_mysql:
+                # 冲突时做一次"无变化"的更新：受影响行数 1=插入、0=已存在（MySQL 语义）
+                sql = (f"INSERT INTO done_mark ({cols}) VALUES ({vals}) "
+                       f"ON DUPLICATE KEY UPDATE scope_key = scope_key")
+            else:
+                sql = f"INSERT OR IGNORE INTO done_mark ({cols}) VALUES ({vals})"
+            r = db.session.execute(db.text(sql), args)
+            db.session.commit()
+            first = (r.rowcount or 0) > 0
+            if first:
+                _log.info(f"[{serial}] 记账：任务『{job_name or job_id}』身份『{args['ident']}』"
+                          f"（{kind}）")
+            return first
+    except Exception as e:
+        _log.warning(f"去重记账失败（本次不记，下次重跑会重试）: {e}")
+        return False
+
+
+# ================== 界面：看 / 清 ==================
+def list_marks(job_id="", limit=200):
+    """去重记录（界面用）：返回 (rows, stats)。
+
+    stats：`total` 本任务全部 · `today_devices` 今天已做的设备数 ·
+    `today_identities` 今天已做的身份值数（== "今天做成了几个号"）。
+    """
+    limit = max(1, min(int(limit or 200), 2000))
+    today0 = time.strftime("%Y-%m-%d 00:00:00")
+    where, args = "", {}
+    if job_id:
+        where = "WHERE job_id = :jid"
+        args["jid"] = job_id
+    with _ctx():
+        rows = db.session.execute(db.text(
+            f"SELECT id, scope_key, kind, job_id, job_name, serial, device_name, "
+            f"identity, created_at FROM done_mark {where} "
+            f"ORDER BY id DESC LIMIT :lim"), {**args, "lim": limit}).fetchall()
+        twhere = where + (" AND " if where else "WHERE ") + "created_at >= :t0"
+        stat = db.session.execute(db.text(
+            f"SELECT COUNT(*) AS total, "
+            f"COUNT(DISTINCT serial) AS devs, "
+            f"COUNT(DISTINCT identity) AS ids "
+            f"FROM done_mark {where}"), args).fetchone()
+        today = db.session.execute(db.text(
+            f"SELECT COUNT(DISTINCT serial) AS devs, "
+            f"COUNT(DISTINCT identity) AS ids "
+            f"FROM done_mark {twhere}"), {**args, "t0": today0}).fetchone()
+    out = [{"id": r[0], "scope_key": r[1], "kind": r[2], "job_id": r[3], "job_name": r[4],
+            "serial": r[5], "device_name": r[6], "identity": r[7], "created_at": r[8]}
+           for r in rows]
+    stats = {"total": stat[0] if stat else 0,
+             "devices": stat[1] if stat else 0,
+             "identities": stat[2] if stat else 0,
+             "today_devices": today[0] if today else 0,
+             "today_identities": today[1] if today else 0}
+    return out, stats
+
+
+def delete_mark(mark_id):
+    """删一条记录（让某个号/某台设备能重跑）。返回是否删掉了。"""
+    try:
+        with _ctx():
+            r = db.session.execute(db.text("DELETE FROM done_mark WHERE id = :i"),
+                                   {"i": int(mark_id)})
+            db.session.commit()
+            return (r.rowcount or 0) > 0
+    except Exception as e:
+        _log.warning(f"删除去重记录失败: {e}")
+        return False
+
+
+def clear_job(job_id):
+    """清空某个任务的全部去重记录（整批重跑）。返回删掉的行数。"""
+    try:
+        with _ctx():
+            r = db.session.execute(db.text("DELETE FROM done_mark WHERE job_id = :j"),
+                                   {"j": job_id or ""})
+            db.session.commit()
+            n = r.rowcount or 0
+            _log.info(f"清空去重记录：任务 {job_id} 共 {n} 条")
+            return n
+    except Exception as e:
+        _log.warning(f"清空去重记录失败: {e}")
+        return 0
+
+
+def purge_old(keep_days=KEEP_DAYS):
+    """清理过期的 day/hours 桶记录。**kind='all' 永不清理**（清了等于去重失效）。
+
+    量级很小（设备数 × 天数），直接一条 DELETE 就行，不用像步骤明细那样分批。
+    """
+    cutoff = (datetime.now() - timedelta(days=max(1, int(keep_days)))
+              ).strftime("%Y-%m-%d %H:%M:%S")
+    try:
+        with _ctx():
+            r = db.session.execute(db.text(
+                "DELETE FROM done_mark WHERE kind <> :all AND created_at < :cut"),
+                {"all": KIND_ALL, "cut": cutoff})
+            db.session.commit()
+            n = r.rowcount or 0
+        if n:
+            _log.info(f"去重记录清理：删除 {n} 条（保留 {keep_days} 天；"
+                      f"kind={KIND_ALL} 的永不清理）")
+        return n
+    except Exception as e:
+        _log.warning(f"去重记录清理失败: {e}")
+        return 0
@@ -0,0 +1,404 @@
+"""设备电量采集 + 低电量告警（大屏/监控展示 + webhook 通知）。
+
+设计要点（都是被现有代码/实测约束逼出来的，改之前先读一遍）：
+
+  - **只读**：`adb -s <serial> shell dumpsys battery`（实测 0.2~0.35s/台）。
+    全模块不 connect / 不 disconnect / 不 kill-server（技术红线，见 doc/DEVELOPMENT.md）。
+    能查到的前提是设备已在 adb server 里（= device_pool.list_online()），
+    所以连"空闲设备"也能查——**不需要 connect**，这是本模块敢每轮扫全量的原因。
+  - **后台独立线程**采集（照 core/device_discovery.py 的 daemon 循环）：`/api/status`
+    只读内存缓存。绝不能把 dumpsys 放进 /api/status——前端 5 秒轮询一次，
+    14 台设备同步查会把 Flask 拖死（`get_status` 的 5s 缓存注释也写了这条）。
+  - **不落库**：电量是易变值，重启重新采一轮即可 → 不建表、**不动备份覆盖清单**。
+  - 告警走 notifier（`device.battery.low` / `device.battery.recovered`），
+    **按档位做状态沿检测**（正常/低/严重），掉档才报，绝不满屏刷。
+  - 配置存 `app_meta.device_battery` 一个键（照 core/step_defaults.py 的做法：
+    出厂默认 + 字段白名单 + 只落"与出厂值不同"的字段）。
+"""
+import json
+import re
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from config import USB_ADB_HOST, USB_ADB_PORT
+from core import notifier, device_pool
+from core.adb_helper import _adb, _adb_remote
+from core.logger import get_logger
+from core.models import db
+
+_log = get_logger("core.battery")
+
+# 出厂默认（前端「工具 → 设备发现 → 电量监控」的初始内容，也是没配过时的回退）
+FACTORY = {
+    "enabled": True,
+    "low": 20,             # 低电量阈值（%）
+    "critical": 10,        # 严重低电量阈值（%）——通知等级升到 error
+    "skip_charging": True,  # 充电中不告警（插着充电器说明正在补电）
+    "interval": 60,        # 采集间隔（秒）
+}
+
+# 字段规格：("num", 最小, 最大) / ("bool",)。白名单之外的一律丢弃。
+SPEC = {
+    "enabled": ("bool",),
+    "low": ("num", 1, 100),
+    "critical": ("num", 1, 100),
+    "skip_charging": ("bool",),
+    "interval": ("num", 30, 3600),
+}
+
+META_KEY = "device_battery"
+
+# 恢复迟滞：掉到阈值下之后，要回升到 low+HYSTERESIS 才算"恢复"。
+# 没有它的话，电量在阈值上下浮动（充电器接触不良）会反复告警。
+HYSTERESIS = 5
+# 持续低电量的重复提醒间隔（秒）。0 = 只提醒一次（等恢复后才重新武装）。
+RE_NOTIFY_S = 6 * 3600
+# 单台设备读取超时（秒）。正常 0.2~0.35s，8s 已经非常宽松。
+_READ_TIMEOUT = 8
+
+_app = None
+_cache = {}       # serial -> {"level": int, "charging": bool, "at": ts}
+_tiers = {}       # serial -> {"tier": int, "at": ts}  告警档位状态（0 正常/1 低/2 严重）
+_lock = threading.Lock()
+_stop_event = threading.Event()
+_scanning = False
+_last_scan = None   # (时间串, 采集成功数, 在线数)
+
+
+def _ctx():
+    """后台线程访问 db 时自行推 app context（仿 device_pool._ctx）。"""
+    return _app.app_context() if _app else None
+
+
+# ================== 配置读写 ==================
+def factory():
+    """出厂默认的拷贝（别让调用方改到常量）。"""
+    return dict(FACTORY)
+
+
+def _clean(raw):
+    """按 SPEC 校验清洗；非法字段**丢弃**（不让脏值进库）。"""
+    if not isinstance(raw, dict):
+        return {}
+    out = {}
+    for k, rule in SPEC.items():
+        if k not in raw:
+            continue
+        v = raw[k]
+        try:
+            if rule[0] == "bool":
+                out[k] = bool(v)
+            elif rule[0] == "num":
+                out[k] = int(round(max(rule[1], min(rule[2], float(v)))))
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
+def get_settings():
+    """当前生效配置（读库；模块未初始化时回退出厂值，别让调用方炸）。"""
+    ctx = _ctx()
+    if ctx is None:
+        return factory()
+    try:
+        from core.db_config import meta_get
+        with ctx:
+            raw = meta_get(META_KEY) or ""
+        if not raw:
+            return factory()
+        return _merge(json.loads(raw))
+    except Exception:
+        return factory()
+
+
+def _merge(user):
+    """出厂默认 + 用户覆盖（逐字段合并 + 钳制）。"""
+    vals = dict(FACTORY)
+    vals.update(_clean(user))
+    # 严重阈值不能高于低电量阈值，否则"严重"永远先触发，语义反了
+    if vals["critical"] > vals["low"]:
+        vals["critical"] = vals["low"]
+    return vals
+
+
+def save_settings(payload):
+    """保存配置。返回 (ok, msg, saved)。
+
+    与出厂默认**相同的字段不入库**（照 step_defaults）：以后调出厂值时，
+    没配过的字段能跟着更新，库里只留"用户真的改过"的部分。
+    """
+    vals = _merge(payload)
+    diff = {k: v for k, v in vals.items() if FACTORY.get(k) != v}
+    ctx = _ctx()
+    if ctx is None:
+        return False, "电量模块未初始化", {}
+    try:
+        from core.db_config import meta_set
+        with ctx:
+            meta_set(META_KEY, json.dumps(diff, ensure_ascii=False))
+            db.session.commit()
+    except Exception as e:
+        return False, f"保存失败: {e}", {}
+    _log.info(f"电量监控配置已保存: {vals}")
+    return True, "已保存", vals
+
+
+# ================== 单台读取与解析 ==================
+_BAT_LEVEL_RE = re.compile(r"^\s*level:\s*(\d+)", re.M)
+_BAT_SCALE_RE = re.compile(r"^\s*scale:\s*(\d+)", re.M)
+_BAT_STATUS_RE = re.compile(r"^\s*status:\s*(\d+)", re.M)
+# 部分 ROM 没有 status 行时的兜底：插着电就算充电中
+_POWERED_RE = re.compile(r"^\s*(?:AC|USB|Wireless) powered:\s*true", re.M)
+
+
+def _parse_battery(text):
+    """解析 `dumpsys battery` 输出，返回 (level, charging) 或 None。
+
+    status: 2=充电中 5=已充满 → charging；3=放电 4=未充电（插着但不充，
+    例如劣质线/温控/满电停充）→ 不算充电中。所以"插着却掉电"仍然会告警，
+    这正是最该让人知道的情况。
+    """
+    if not text or "level:" not in text:
+        return None
+    m = _BAT_LEVEL_RE.search(text)
+    if not m:
+        return None
+    level = int(m.group(1))
+    ms = _BAT_SCALE_RE.search(text)
+    scale = int(ms.group(1)) if ms else 100
+    if scale > 0 and scale != 100:
+        level = int(round(level * 100.0 / scale))
+    st = _BAT_STATUS_RE.search(text)
+    if st:
+        charging = int(st.group(1)) in (2, 5)
+    else:
+        charging = bool(_POWERED_RE.search(text))
+    return max(0, min(100, level)), charging
+
+
+def _read_battery(serial):
+    """读一台设备的电量，返回 (level, charging) 或 None。
+
+    与 device_pool.refresh_model 同思路：IP:5555 设备走本机 adb server；
+    USB 设备本机看不到，再走 220 远程 adb server 兜底。
+    """
+    out = ""
+    try:
+        out = _adb("-s", serial, "shell", "dumpsys", "battery", timeout=_READ_TIMEOUT)
+    except Exception:
+        out = ""
+    if not out and ":" not in serial:
+        try:
+            out = _adb_remote(USB_ADB_HOST, USB_ADB_PORT, "-s", serial,
+                              "shell", "dumpsys", "battery")
+        except Exception:
+            out = ""
+    return _parse_battery(out)
+
+
+# ================== 告警（档位状态沿） ==================
+def _tier_of(level, charging, spec, prev):
+    """电量档位：0 正常 / 1 低 / 2 严重。
+
+    充电中（且配了「充电中不告警」）直接算 0——正在补电就不用管它。
+    回升要越过 low+HYSTERESIS 才回 0，避免在阈值上下反复告警。
+    """
+    if spec["skip_charging"] and charging:
+        return 0
+    if level <= spec["critical"]:
+        return 2
+    if level <= spec["low"]:
+        return 1
+    if level >= spec["low"] + HYSTERESIS:
+        return 0
+    return prev          # 迟滞带内：维持原档位（不报也不恢复）
+
+
+def _check_alerts(serial, level, charging, spec, dname, model):
+    """比上一轮档位，决定是否发通知。只在档位变化/到重复提醒点时发。"""
+    now = time.time()
+    with _lock:
+        st = _tiers.setdefault(serial, {"tier": 0, "at": 0.0})
+        prev = st["tier"]
+        tier = _tier_of(level, charging, spec, prev)
+        # 掉档（正常→低→严重）立刻报；同一档位停留太久到重复提醒间隔再报一次
+        fire = tier > prev or (tier > 0 and now - st["at"] >= RE_NOTIFY_S)
+        if fire:
+            st["tier"], st["at"] = tier, now
+        recovered = prev > 0 and tier == 0
+        if recovered:
+            st["tier"], st["at"] = 0, now
+    if fire:
+        notifier.notify(
+            "device.battery.low", serial=serial, device_name=dname, model=model,
+            battery=level, charging=charging,
+            threshold=spec["critical"] if tier == 2 else spec["low"],
+            level="error" if tier == 2 else "warning")
+    if recovered:
+        notifier.notify(
+            "device.battery.recovered", serial=serial, device_name=dname,
+            model=model, battery=level, charging=charging, threshold=spec["low"])
+
+
+# ================== 一轮全量采集 ==================
+def _scan_all():
+    """采集池内所有在线设备的电量（后台线程执行）。
+
+    读失败的设备（离线/超时）**保持上一次的读数不动**——大屏上显示的是
+    "最后一次知道的电量"，比直接变成空白有用。
+    """
+    global _scanning, _last_scan
+    if _scanning:
+        return
+    _scanning = True
+    try:
+        spec = get_settings()
+        try:
+            online = list(device_pool.list_online())
+        except Exception as e:
+            _log.warning(f"电量采集: 获取在线设备失败: {e}")
+            return
+        if not online:
+            _last_scan = (time.strftime("%H:%M:%S"), 0, 0)
+            return
+        # 设备名/型号：通知里要显示「A08（Redmi K40）」而不是一串 IP
+        names, models, known = {}, {}, set()
+        try:
+            for d in device_pool.list_devices():
+                s = d.get("serial") or ""
+                if not s:
+                    continue
+                known.add(s)
+                names[s] = d.get("name") or ""
+                models[s] = d.get("model") or ""
+        except Exception:
+            pass
+
+        # 只采集「设备池 ∩ 在线」：平台管的是设备池（与 list_ready 同口径），
+        # 池外的设备不上大屏、也不告警——adb 里能看到但不归平台管的设备不该吵人。
+        # known 为空 = 设备表没读到（不能因此整轮不采），退回按在线设备采。
+        targets = [s for s in online if s in known] if known else list(online)
+        if not targets:
+            _last_scan = (time.strftime("%H:%M:%S"), 0, 0)
+            return
+
+        results = {}
+        try:
+            with ThreadPoolExecutor(max_workers=min(10, len(targets))) as pool:
+                futures = {pool.submit(_read_battery, s): s for s in targets}
+                for fut in as_completed(futures, timeout=_READ_TIMEOUT + 15):
+                    s = futures[fut]
+                    try:
+                        results[s] = fut.result()
+                    except Exception:
+                        results[s] = None
+        except Exception as e:
+            _log.warning(f"电量采集: 部分设备读取超时（保留已取到的）: {e}")
+
+        now = time.time()
+        with _lock:
+            for s, r in results.items():
+                if r:
+                    _cache[s] = {"level": r[0], "charging": r[1], "at": now}
+            # 设备已从池里删除的，连缓存一起清掉（避免大屏上冒出幽灵设备）。
+            # ⚠️ 只在真的读到设备清单时才清理：list_devices 失败时 known 是空的，
+            # 照清下去会把整份缓存抹掉、大屏全体变「—」。
+            if known:
+                for s in [k for k in _cache if k not in known]:
+                    _cache.pop(s, None)
+                    _tiers.pop(s, None)
+
+        for s, r in results.items():
+            if r:
+                _check_alerts(s, r[0], r[1], spec, names.get(s, ""), models.get(s, ""))
+
+        ok = sum(1 for r in results.values() if r)
+        _last_scan = (time.strftime("%H:%M:%S"), ok, len(targets))
+        _log.info(f"电量采集完成: {ok}/{len(targets)} 台（池内在线；adb 可见 {len(online)} 台）")
+    except Exception as e:
+        _log.warning(f"电量采集异常: {e}")
+    finally:
+        _scanning = False
+
+
+def scan_once():
+    """手动触发一轮采集（后台线程执行，不阻塞调用者）。返回是否已启动。
+
+    不看 enabled 开关：用户点了「立即采集」就应该采，开关只管定时循环。
+    """
+    if _scanning:
+        return False
+    threading.Thread(target=_scan_all, name="battery-scan-once", daemon=True).start()
+    return True
+
+
+# ================== 对外读取 ==================
+def get(serial):
+    """设备电量快照（供 /api/status 组装）或 None。
+
+    结构 {"level": int, "charging": bool, "at": ts, "tier": 0|1|2}。
+    **带上 tier 是刻意的**：前端只按档位上色，不在 JS 里重算阈值——
+    否则「工具 → 设备发现」改了阈值，大屏/监控页的判定就和告警对不上了。
+    """
+    with _lock:
+        v = _cache.get(serial)
+        if not v:
+            return None
+        out = dict(v)
+        st = _tiers.get(serial)
+        out["tier"] = st["tier"] if st else 0
+        return out
+
+
+def get_status():
+    """采集器状态（面板显示用）。"""
+    with _lock:
+        cached = len(_cache)
+    return {
+        "settings": get_settings(),
+        "scanning": _scanning,
+        "last_scan": _last_scan,
+        "cached": cached,
+    }
+
+
+# ================== 定时采集线程 ==================
+def _battery_loop():
+    """定时采集 daemon 线程。每轮重读配置（开关/间隔即时生效）。
+
+    启动先等 20s：让开 web_server 的预连接与型号采集（都抢 adb）。
+    等待用 15s 切片，关停/改间隔 ≤15s 生效。
+    """
+    try:
+        _stop_event.wait(20)
+        while not _stop_event.is_set():
+            interval = 60
+            try:
+                spec = get_settings()
+                interval = max(30, int(spec.get("interval", 60)))
+                if spec.get("enabled"):
+                    _scan_all()
+            except Exception as e:
+                _log.warning(f"电量定时采集异常: {e}")
+            waited = 0
+            while waited < interval and not _stop_event.is_set():
+                _stop_event.wait(min(15, interval - waited))
+                waited += min(15, interval - waited)
+    except Exception:
+        pass
+
+
+def init_app(app):
+    """web_server 启动时调用：绑 app + 起定时采集 daemon 线程。"""
+    global _app
+    _app = app
+    _stop_event.clear()
+    t = threading.Thread(target=_battery_loop, name="device-battery", daemon=True)
+    t.start()
+    _log.info("设备电量采集线程已启动（默认 60s 一次）")
+
+
+def shutdown():
+    """优雅退出：置 stop_event，等待中的循环在切片边界退出。"""
+    _stop_event.set()
@@ -0,0 +1,506 @@
+"""设备自动发现：扫描网段中开放 adb 5555 的设备 → 待连接池（pending）。
+
+流程：socket 并发探测 5555（标准库，不碰 adb）→ 剔除已在设备池的 serial →
+串行 adb 验证（adb_connect_light，内部全局锁）→ 用 `adb devices` 的
+state=="device" 过滤（排除 unauthorized/offline，connect 输出不可信）→
+写入 pending_device 表。**扫描只验证、不自动连接入池**——用户在前端确认后
+才调 device_pool.add_device + adb_connect（见 web/devices_api.py）。
+
+安全红线：绝不 kill-server / 绝不 disconnect（与全项目一致）。
+
+配置存 app_meta KV 表（discovery_enabled/subnets/interval/port），定时线程
+每轮重读，开关/周期/网段改动即时生效无需重启。
+"""
+import ipaddress
+import json
+import socket
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+
+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")
+
+# 扫描配置键（app_meta）
+_K_ENABLED = "discovery_enabled"
+_K_SUBNETS = "discovery_subnets"
+_K_INTERVAL = "discovery_interval"
+_K_PORT = "discovery_port"
+# 指纹匹配时是否自动认领（默认关：认领会改写分组/任务引用，默认交人工确认）
+_K_AUTO_CLAIM = "discovery_auto_claim"
+
+# 单网段主机数上限（防误配 /8 之类），超过截断并告警
+_MAX_HOSTS_PER_SUBNET = 1024
+# socket 探测并发数与单 IP 超时
+_PROBE_WORKERS = 64
+_PROBE_TIMEOUT = 0.4
+
+_app = None
+_scan_lock = threading.Lock()     # 定时/手动扫描互斥
+# 上一轮"池内离线"集合：通知只报**状态沿**（这一轮新变成离线的），不每轮刷屏
+_last_offline = set()
+_stop_event = threading.Event()   # shutdown 用
+_scanning = False                 # 状态快照（API/前端）
+_last_scan = None                 # (时间串, 开放数, 可连数, 新增数)
+_last_error = ""
+
+
+def _ctx():
+    """后台线程访问 db 时自行推 app context（仿 device_pool._ctx）。"""
+    return _app.app_context() if _app else None
+
+
+def _fmt(ts=None):
+    return (ts or datetime.now()).strftime("%Y-%m-%d %H:%M")
+
+
+# ================== 配置读写 ==================
+def get_settings():
+    """读发现配置（app_meta，缺键用 config 默认值补齐）。"""
+    with _ctx():
+        from core.db_config import meta_get
+
+        def _get(key, default):
+            v = meta_get(key)
+            return v if v is not None else default
+        try:
+            subnets = json.loads(_get(_K_SUBNETS, "[]")) or DISCOVERY_SUBNETS
+        except Exception:
+            subnets = DISCOVERY_SUBNETS
+        return {
+            "enabled": _get(_K_ENABLED, "1") == "1",   # 默认开启
+            "subnets": subnets,
+            "interval": int(_get(_K_INTERVAL, str(DISCOVERY_INTERVAL)) or DISCOVERY_INTERVAL),
+            "port": int(_get(_K_PORT, str(DISCOVERY_PORT)) or DISCOVERY_PORT),
+            "auto_claim": _get(_K_AUTO_CLAIM, "0") == "1",   # 默认关
+        }
+
+
+def save_settings(enabled=None, subnets=None, interval=None, port=None, auto_claim=None):
+    """写发现配置（部分字段更新）。subnets 逐项校验 CIDR，非法返回 (False, 原因)。"""
+    if subnets is not None:
+        clean = []
+        for s in subnets:
+            s = (s or "").strip()
+            if not s:
+                continue
+            try:
+                ipaddress.ip_network(s, strict=False)
+            except ValueError:
+                return False, f"网段格式错误: {s}"
+            clean.append(s)
+        subnets = clean
+    try:
+        if interval is not None and (int(interval) < 10 or int(interval) > 3600):
+            return False, "扫描周期需在 10-3600 秒之间"
+        if port is not None and (int(port) < 1 or int(port) > 65535):
+            return False, "端口不合法"
+    except (TypeError, ValueError):
+        return False, "参数不合法"
+    with _ctx():
+        from core.db_config import meta_set
+        _put = meta_set   # 方言中立 upsert（app_meta.key 在 MySQL 里是保留字）
+        if enabled is not None:
+            _put(_K_ENABLED, "1" if enabled else "0")
+        if subnets is not None:
+            _put(_K_SUBNETS, json.dumps(subnets))
+        if interval is not None:
+            _put(_K_INTERVAL, str(int(interval)))
+        if port is not None:
+            _put(_K_PORT, str(int(port)))
+        if auto_claim is not None:
+            _put(_K_AUTO_CLAIM, "1" if auto_claim else "0")
+        db.session.commit()
+    return True, "已保存"
+
+
+# ================== 网段展开与端口探测 ==================
+def _local_ips():
+    """本机自身 IP 集合（尽力而为）：扫描时排除，避免探测到自己的 5555。
+
+    优先 `hostname -I`（Linux/macOS 支持，一行空格分隔多 IP）；不支持/失败的
+    平台退回 socket.getaddrinfo 枚举。关键：外部命令必须用 bytes 收——Windows
+    上 git-bash 的 coreutils hostname 不支持 -I，会把 GBK 报错写进 stderr，
+    text=True 在 subprocess 后台读线程里 utf-8 严格解码会直接炸线程（主线程
+    try/except 接不住异步线程异常）。
+    """
+    import subprocess
+    ips = set()
+    try:
+        r = subprocess.run(["hostname", "-I"], capture_output=True, timeout=3)
+        if r.returncode == 0:
+            ips.update(p for p in
+                       r.stdout.decode("utf-8", errors="ignore").split() if p)
+    except Exception:
+        pass
+    if not ips:  # 兜底：主机名解析出的接口 IPv4
+        try:
+            for info in socket.getaddrinfo(socket.gethostname(), None):
+                ip = info[4][0]
+                if ":" not in ip:
+                    ips.add(ip)
+        except Exception:
+            pass
+    return ips
+
+
+def _expand_subnets(subnets, max_hosts=_MAX_HOSTS_PER_SUBNET):
+    """CIDR 列表 → IP 列表。排除 220 自身（USB_ADB_HOST）与本机 IP；
+    非法网段跳过记日志；单网段超过 max_hosts 截断并告警。"""
+    self_ips = {USB_ADB_HOST} | _local_ips()
+    ips = []
+    for cidr in subnets:
+        try:
+            net = ipaddress.ip_network((cidr or "").strip(), strict=False)
+        except ValueError:
+            _log.warning(f"发现: 跳过非法网段 {cidr}")
+            continue
+        hosts = [str(h) for h in net.hosts()
+                 if str(h) not in self_ips]
+        if len(hosts) > max_hosts:
+            _log.warning(f"发现: 网段 {cidr} 主机数 {len(hosts)} 超过上限，截断前 {max_hosts}")
+            hosts = hosts[:max_hosts]
+        ips.extend(hosts)
+    return ips
+
+
+def _probe_port(ip, port, timeout=_PROBE_TIMEOUT):
+    """单 IP 端口探测（标准库 socket，超时/拒绝/不可达一律 False）。"""
+    try:
+        with socket.create_connection((ip, port), timeout=timeout):
+            return True
+    except Exception:
+        return False
+
+
+def _probe_open(ips, port, workers=_PROBE_WORKERS):
+    """并发探测，返回开放端口的主机列表。"""
+    if not ips:
+        return []
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        results = list(ex.map(lambda ip: (ip, _probe_port(ip, port)), ips))
+    return [ip for ip, ok in results if ok]
+
+
+# ================== adb devices 解析 ==================
+def _parse_adb_devices(out):
+    """解析 `adb devices` 输出 → state=="device" 的 serial 集合。
+
+    只看 connect 输出不可靠（未授权设备也返回 connected），必须用 state 过滤。
+    """
+    devices = set()
+    for line in (out or "").splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[0] and not parts[0].startswith("*"):
+            if parts[1] == "device":
+                devices.add(parts[0])
+    return devices
+
+
+# ================== 自动认领（可选） ==================
+def _auto_claim(fps):
+    """指纹命中池中已有设备 → 自动认领：迁移记录到新地址并同步分组/任务引用。
+
+    仅在设置 discovery_auto_claim 打开时由扫描线程调用（默认关）。
+    返回 [(old_serial, new_serial, name), ...]。
+    """
+    from core import device_pool
+    done = []
+    for serial, fp in (fps or {}).items():
+        if not fp:
+            continue
+        try:
+            info = device_pool.find_by_fingerprint(fp)
+            if not info or info.get("serial") == serial:
+                continue          # 没匹配到，或本来就是这条（无需迁移）
+            old, name = device_pool.claim_device(serial, fp)
+            if not old:
+                continue
+            PendingDevice.query.filter_by(serial=serial).delete()
+            db.session.commit()
+            done.append((old, serial, name or info.get("name") or ""))
+            _log.info(f"自动认领: 『{name or info.get('name') or old}』{old} → {serial}")
+        except Exception as e:
+            db.session.rollback()
+            _log.warning(f"自动认领 {serial} 失败: {e}")
+    return done
+
+
+# ================== 扫描 ==================
+def scan_once(manual=False):
+    """执行一轮扫描。返回 (ok, result_dict)；后台线程/API 调用。"""
+    global _scanning, _last_scan, _last_error
+    if not _scan_lock.acquire(blocking=False):
+        return False, {"error": "扫描进行中"}
+    _scanning = True
+    try:
+        settings = get_settings()
+        port = settings["port"]
+        subnets = settings["subnets"]
+        if not subnets:
+            _last_error = "未配置扫描网段"
+            return True, {"found": 0, "verified": 0, "new": 0, "error": _last_error}
+
+        # 1. socket 并发探测（不碰 adb，把几百台缩小到开放端口量级）
+        open_ips = _probe_open(_expand_subnets(subnets), port)
+        candidates = {f"{ip}:{port}" for ip in open_ips}
+
+        with _ctx():
+            # 2. 剔除已在正式设备池的 serial
+            configured = set(device_pool_list_configured())
+            candidates -= configured
+
+            # 3. 串行 adb 验证：已连接的直接跳过（零成本），其余 adb_connect_light
+            already = _parse_adb_devices(_adb("devices"))
+            for serial in candidates - already:
+                adb_connect_light(serial)  # 内部全局锁串行；失败无妨，下面按 state 过滤
+
+            # 4. state==device 过滤（排除 unauthorized/offline）
+            verified = _parse_adb_devices(_adb("devices")) & candidates
+
+            # 5. 写 pending：新 → 插入；已有 → 更新 last_seen（顺带刷新指纹）
+            #    指纹用于认出"这台其实是设备池里某台设备换了 IP"，见 list_pending 的 match
+            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:
+                source = "tailscale" if serial.split(":")[0].startswith("100.") else "lan"
+                try:
+                    fp = device_pool.read_fingerprint(serial, timeout=4)
+                except Exception:
+                    fp = ""
+                fps[serial] = fp
+                if serial in existing:
+                    PendingDevice.query.filter_by(serial=serial).update(
+                        {"last_seen": now, "fingerprint": fp})
+                else:
+                    db.session.add(PendingDevice(serial=serial, source=source,
+                                                 first_seen=now, last_seen=now,
+                                                 fingerprint=fp))
+                    added += 1
+                    added_serials.append(serial)
+            db.session.commit()
+            # 5.5 自动认领（可选，默认关）：指纹命中池中已有设备 → 直接把记录迁到新地址。
+            #     默认关是因为认领会改写分组/任务引用（数据结构变动），交人工点一下更稳妥；
+            #     打开后零点击完成，见 doc/API.md §6。
+            claimed = _auto_claim(fps) if settings.get("auto_claim") else []
+            # 6. 正式池断联设备自动重连：adb connect 会因 WiFi 波动/设备重启/
+            #    adb 服务重启而断开——扫描线程每轮顺带重试（幂等轻量，内部
+            #    全局锁串行），连上即恢复在线，无需人工干预。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),
+                      "new": added, "claimed": len(claimed)}
+    except Exception as e:
+        _log.warning(f"发现扫描异常: {e}")
+        _last_error = str(e)[:200]
+        return False, {"error": _last_error}
+    finally:
+        _scanning = False
+        _scan_lock.release()
+
+
+def device_pool_list_configured():
+    """设备池已配置 serial（延迟 import 避免循环依赖）。"""
+    from core import device_pool
+    return device_pool.list_configured()
+
+
+# ================== 正式池断联设备：自动重连 ==================
+def _reconnect_offline(configured):
+    """对正式池中断联的网络设备逐个 adb 重连，返回恢复的 serial 列表。
+
+    只重连网络设备（IP:5555；USB 设备插着就在，无需 connect）。
+    幂等轻量：内部 adb 全局锁串行，失败静默（下轮扫描再试）。
+    """
+    online_now = _parse_adb_devices(_adb("devices"))
+    targets = [s for s in (configured or [])
+               if ":" in s and s not in online_now]
+    if not targets:
+        return []
+    for serial in targets:
+        adb_connect_light(serial)
+    online_after = _parse_adb_devices(_adb("devices"))
+    return [s for s in targets if s in online_after]
+
+
+def list_pool_offline():
+    """正式设备池中断联的设备（serial + 型号 + 备注名），面板展示用。
+
+    断联设备仍是正式池成员（不删除、不进 pending）——pending 是给未授权
+    新设备的；它们由扫描线程每轮自动重连，也可前端手动立即重连。
+    """
+    online = _parse_adb_devices(_adb("devices"))
+    with _ctx():
+        rows = [d.to_dict() for d in Device.query.filter_by(enabled=True)
+                .order_by(Device.serial).all()]
+    return [{"serial": r["serial"], "model": r.get("model") or "",
+             "name": r.get("name") or ""}
+            for r in rows if r["serial"] not in online]
+
+
+# ================== 定时扫描线程 ==================
+def _discovery_loop():
+    """定时扫描 daemon 线程。每轮重读配置（开关/周期即时生效）。
+
+    启动先 sleep 15s 避让 web_server 预连接线程（两者都抢 adb 全局锁）。
+    等待用 30s 切片（_stop_event.wait），关停/改周期 ≤30s 生效。
+    """
+    try:
+        _stop_event.wait(15)
+        while not _stop_event.is_set():
+            try:
+                settings = get_settings()
+                if settings["enabled"]:
+                    scan_once()
+            except Exception as e:
+                _log.warning(f"发现定时扫描异常: {e}")
+            wait_s = max(10, settings.get("interval", 60))
+            waited = 0
+            while waited < wait_s and not _stop_event.is_set():
+                _stop_event.wait(min(30, wait_s - waited))
+                waited += min(30, wait_s - waited)
+    except Exception:
+        pass
+
+
+def init_app(app):
+    """web_server 启动时调用：绑 app + 起定时扫描 daemon 线程。"""
+    global _app
+    _app = app
+    _stop_event.clear()
+    t = threading.Thread(target=_discovery_loop, name="device-discovery", daemon=True)
+    t.start()
+    _log.info("设备自动发现线程已启动（默认 60s 扫描一次）")
+
+
+def shutdown():
+    """优雅退出：置 stop_event，等待中的循环在切片边界退出。"""
+    _stop_event.set()
+
+
+# ================== 对外查询与确认 ==================
+def get_status():
+    """API 状态快照：配置 + 扫描状态 + 最近一轮结果 + 待连接数量。"""
+    settings = get_settings()
+    with _ctx():
+        pending = PendingDevice.query.count()
+    return {
+        "enabled": settings["enabled"],
+        "subnets": settings["subnets"],
+        "interval": settings["interval"],
+        "port": settings["port"],
+        "auto_claim": settings["auto_claim"],
+        "scanning": _scanning,
+        "last_scan": _last_scan[0] if _last_scan else "",
+        "last_result": ({"found": _last_scan[1], "verified": _last_scan[2],
+                         "new": _last_scan[3]} if _last_scan else None),
+        "last_error": _last_error,
+        "pending_count": pending,
+    }
+
+
+def list_pending():
+    """待连接列表：只返回当前在线的设备（离线候选不可确认，不展示）。
+
+    后端直接过滤（2026-09-04）：不依赖前端 JS 版本，任何客户端都拿不到
+    离线条目；设备恢复在线后扫描自动更新 last_seen 并重新出现在列表。
+    """
+    online = _parse_adb_devices(_adb("devices"))
+    with _ctx():
+        rows = [p.to_dict() for p in PendingDevice.query.order_by(
+            PendingDevice.first_seen.desc()).all()]
+    out = []
+    for r in rows:
+        if r["serial"] not in online:
+            continue
+        r["online"] = True
+        # 指纹匹配：这台其实就是设备池里某台设备换了地址（前端据此提示"认领"）
+        r["match"] = None
+        if r.get("fingerprint"):
+            try:
+                from core import device_pool
+                m = device_pool.find_by_fingerprint(r["fingerprint"])
+                if m and m["serial"] != r["serial"]:
+                    r["match"] = {"serial": m["serial"], "name": m.get("name") or ""}
+            except Exception:
+                pass
+        out.append(r)
+    return out
+
+
+def confirm_pending(serial, name="", fingerprint=""):
+    """确认连接：pending 行 → 正式设备池（add_device upsert）→ 删 pending。
+
+    先按指纹尝试**认领**：同一台物理设备换了地址时，把池中旧记录迁到新 serial，
+    并同步分组/任务里的引用（名称等信息全部保留），而不是新增一条。
+
+    返回 (ok, msg, is_new)。adb_connect + 采型号/指纹由调用方（API 层后台线程）做。
+    """
+    with _ctx():
+        row = PendingDevice.query.get(serial)
+        if not row:
+            return False, "设备不在待连接列表", False
+        from core import device_pool
+        fp = (fingerprint or row.fingerprint or "").strip()
+        claimed_old, claimed_name = device_pool.claim_device(serial, fp)
+        if claimed_old:
+            device_pool.add_device(serial, name=claimed_name or name, fingerprint=fp)
+            PendingDevice.query.filter_by(serial=serial).delete()
+            db.session.commit()
+            return True, (f"已认领为『{claimed_name or claimed_old}』"
+                          f"（原地址 {claimed_old}，分组/任务的引用已同步）"), False
+        is_new = device_pool.add_device(serial, name=name or "", fingerprint=fp)
+        PendingDevice.query.filter_by(serial=serial).delete()
+        db.session.commit()
+    return True, "已加入设备池" + ("" if is_new else "（已存在，信息已更新）"), is_new
+
+
+def ignore_pending(serial):
+    """忽略：删除 pending 行（下轮扫描可能再次发现）。"""
+    with _ctx():
+        row = PendingDevice.query.get(serial)
+        if not row:
+            return False, "设备不在待连接列表"
+        PendingDevice.query.filter_by(serial=serial).delete()
+        db.session.commit()
+    return True, "已忽略"
@@ -0,0 +1,482 @@
+"""设备池：SQLite devices 表 = 设备清单，本地 adb = 在线状态（STF 替代数据源）。
+
+设计：
+  - list_configured() — devices 表里 enabled 的设备（清单，管理页维护）
+  - list_online()     — 本机 `adb devices` 里 state=device 的设备（实时；
+                        池内有 USB 设备时合并 220 远程 adb server 状态）
+  - list_ready()      — configured ∩ online（任务调度用）
+  - CRUD              — add/update/remove/set_enabled（设备池管理页用）
+
+红线：全模块不 connect / 不 kill-server / 不 disconnect，遵守既有技术约束。
+后台线程（task_manager 等）调用时由本模块自行推 app context，调用方无需关心。
+"""
+import time
+import threading
+import subprocess
+
+from config import ADB_PATH, USB_ADB_HOST, USB_ADB_PORT
+from core.adb_helper import _adb, _adb_remote
+from core.logger import get_logger
+from core.models import db, Device
+
+_log = get_logger("core.device_pool")
+
+_app = None
+# 设备换地址（认领/迁址）后的回调：(old_serial, new_serial) -> None
+# 由 web_server 装配时注册为 TaskManager.sync_device_serial——
+# 分组/任务的内存副本在 TaskManager 里，只改库不改内存不生效（见 _move_device_row）
+_move_hook = None
+
+
+def set_move_hook(fn):
+    """注册"设备换地址"回调（web_server 创建完 TaskManager 后调用）。"""
+    global _move_hook
+    _move_hook = fn
+
+
+def init_app(app):
+    """web_server 启动时调用：绑定 Flask app（供后台线程推 db context），
+    并后台刷新一次设备型号（首次启动/设备更换后型号可能变化）。"""
+    global _app
+    _app = app
+    refresh_names()          # 同步刷一次名称快照，让通知从第一条起就有名字
+    try:
+        t = threading.Thread(target=_refresh_models_bg, daemon=True)
+        t.start()
+        t2 = threading.Thread(target=_names_loop, name="device-names", daemon=True)
+        t2.start()
+    except Exception:
+        pass
+
+
+# ================== 名称内存快照（给通知用） ==================
+# 为什么单独存一份：webhook 通知里要显示"是哪台设备"（A08）而不是地址（IP），
+# 但 `notifier.notify()` 有一条硬红线——**零 DB 访问**（不能为了取个名字去查库，
+# 更不能在业务线程里阻塞）。所以由这里维护一份 serial→名称 的内存快照：
+# 启动刷一次、池子有变动时刷一次、再兜底每 60s 刷一次（覆盖整库恢复等外部改动）。
+_names = {}
+_names_lock = threading.Lock()
+_NAMES_INTERVAL = 60
+
+
+def refresh_names():
+    """把设备池的 serial→名称刷进内存快照（只查库，不碰 adb）。返回条数。"""
+    try:
+        rows = list_devices()
+    except Exception as e:
+        _log.debug(f"刷新设备名快照失败: {e}")
+        return 0
+    m = {}
+    for d in rows:
+        s = d.get("serial") or ""
+        if s:
+            m[s] = d.get("name") or ""
+    with _names_lock:
+        _names.clear()
+        _names.update(m)
+    return len(m)
+
+
+def name_of(serial):
+    """serial 对应的设备名称（**纯内存，可在通知路径上调用**）。没有则返回 ""。"""
+    if not serial:
+        return ""
+    with _names_lock:
+        return _names.get(str(serial), "")
+
+
+def _names_loop():
+    """兜底定时刷新名称快照（覆盖整库恢复这类进程外改动）。"""
+    while True:
+        time.sleep(_NAMES_INTERVAL)
+        refresh_names()
+
+
+def _refresh_models_bg():
+    """后台批量采集在线设备型号（启动时/手动触发）。失败静默，不影响启动。"""
+    time.sleep(3)  # 等服务起来再查
+    try:
+        refresh_all_models()
+    except Exception as e:
+        _log.warning(f"启动型号采集失败（可稍后手动采集）: {e}")
+
+
+def _ctx():
+    """后台线程访问 db 需自行推 app context（与 task_manager._db 同思路）。"""
+    if _app is None:
+        raise RuntimeError("device_pool 未关联 Flask app（web_server 启动时调用 init_app）")
+    return _app.app_context()
+
+
+# ================== 清单 ==================
+def list_configured(enabled_only=True):
+    """devices 表里的设备清单（serial 列表）。"""
+    with _ctx():
+        q = Device.query
+        if enabled_only:
+            q = q.filter_by(enabled=True)
+        return [d.serial for d in q.order_by(Device.serial).all()]
+
+
+def list_devices():
+    """全量设备行（设备池管理页用）。"""
+    with _ctx():
+        return [d.to_dict() for d in Device.query.order_by(Device.serial).all()]
+
+
+def serial_of(device_name):
+    """设备名 → **当前**地址（拿不到返回空串）。
+
+    从已删掉的 `core/ledger.py` 迁过来的（账号台账停用后，那边只剩这一个函数还有用 ——
+    它跟账号无关，只做"设备名 ↔ 地址"）。
+
+    ⚠ 为什么不能直接用计划行里的 `serial` 快照：设备地址会变（换 IP、重连）。
+    快照是"录入时"的值，久了就是错的 —— 要下发操作（推视频等）时必须现查。
+    优先设备池的**内存快照**（零 DB、已经是刷新过的），再退回 DB。
+    """
+    name = (device_name or "").strip()
+    if not name:
+        return ""
+    try:
+        for d in list_devices():
+            if (d.get("name") or "") == name:
+                return d.get("serial") or ""
+    except Exception:
+        pass
+    try:
+        with _ctx():
+            dev = Device.query.filter(Device.name == name).first()
+            return (dev.serial if dev else "") or ""
+    except Exception:
+        return ""
+
+
+# ================== 在线状态 ==================
+def list_online():
+    """本机 adb 中 state=device 的设备 + 池内 USB 设备（经 220 远程 adb server）。
+
+    池内无 USB 设备（serial 无冒号）时不查远程 server，零额外开销。
+    """
+    out = _adb("devices") or ""
+    serials = []
+    for line in out.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[0] and parts[1] == "device":
+            serials.append(parts[0])
+    # 池内有 USB 设备时，补查远程 adb server（220，host 网络 5037 全接口监听）
+    try:
+        usb = [s for s in list_configured() if ":" not in s]
+    except Exception:
+        usb = []
+    if usb:
+        try:
+            out = _adb_remote(USB_ADB_HOST, USB_ADB_PORT, "devices") or ""
+            for line in out.splitlines()[1:]:
+                parts = line.split()
+                if len(parts) >= 2 and parts[0] and parts[1] == "device":
+                    if parts[0] not in serials:
+                        serials.append(parts[0])
+        except Exception:
+            pass
+    return serials
+
+
+def is_online(serial):
+    """设备当前是否在线（本机 adb 可达且状态正常）。"""
+    return serial in list_online()
+
+
+def list_ready():
+    """可调度设备：清单 ∩ 在线（取代 STF list_free_devices）。"""
+    online = set(list_online())
+    return [s for s in list_configured() if s in online]
+
+
+# ================== 设备指纹（识别"同一台物理设备"） ==================
+def read_fingerprint(serial, timeout=6):
+    """读取设备指纹（ro.serialno）——设备换 IP 后据此认领回原记录。
+
+    只对网络设备（serial 含 ":"）读取：USB 设备的 serial 本身就是稳定序列号，
+    不存在"换地址"问题。采集失败返回空串（静默，不影响主流程）。
+    """
+    serial = (serial or "").strip()
+    if not serial or ":" not in serial:
+        return ""
+    # 部分机型 ro.serialno 为空，退回 ro.boot.serialno
+    for prop in ("ro.serialno", "ro.boot.serialno"):
+        try:
+            r = subprocess.run([ADB_PATH, "-s", serial, "shell", "getprop", prop],
+                               capture_output=True, timeout=timeout)
+            fp = (r.stdout or b"").decode("utf-8", errors="replace").strip()
+        except Exception:
+            continue
+        if fp and fp.isprintable():
+            return fp
+    return ""
+
+
+def find_by_fingerprint(fingerprint, exclude_serial=""):
+    """按指纹查池中设备（返回 dict 或 None），可排除指定 serial。"""
+    fingerprint = (fingerprint or "").strip()
+    if not fingerprint:
+        return None
+    with _ctx():
+        row = Device.query.filter(Device.fingerprint == fingerprint).first()
+        if not row or row.serial == exclude_serial:
+            return None
+        return row.to_dict()
+
+
+def name_taken(name, exclude_serial=""):
+    """名称是否已被其它设备占用（唯一约束的应用层检查，给友好提示用）。"""
+    name = (name or "").strip()
+    if not name:
+        return False
+    with _ctx():
+        q = Device.query.filter(Device.name == name)
+        if exclude_serial:
+            q = q.filter(Device.serial != exclude_serial)
+        return q.first() is not None
+
+
+def _move_device_row(old, new_serial, fingerprint=""):
+    """把 old 记录迁到 new_serial（调用方持 app context）。
+
+    只动 device 表本身；**分组/任务引用的同步交给上层**（见 set_move_hook）：
+    分组与任务在 TaskManager 里还有一份内存副本，调度用的是内存对象——
+    只改库不改内存，不重启不生效。而 device_pool 不能反向依赖 task_manager
+    （会造成循环 import），所以用回调把这件事交给装配层。
+    """
+    old_serial, name = old.serial, (old.name or "")
+    # 新地址上若已有记录（重复添加等），以"被认领的旧记录"为准，删掉它
+    dup = Device.query.get(new_serial)
+    if dup is not None and dup.serial != old.serial:
+        db.session.delete(dup)
+    old.serial = new_serial
+    if fingerprint:
+        old.fingerprint = fingerprint
+    db.session.commit()
+    refresh_names()          # 键变了（serial → 名称的映射也跟着变）
+    if _move_hook is not None:
+        try:
+            _move_hook(old_serial, new_serial)
+        except Exception as e:
+            _log.warning(f"设备迁址后同步分组/任务引用失败: {e}")
+    return old_serial, name
+
+
+def claim_device(new_serial, fingerprint):
+    """认领：同一台物理设备换了地址，把池中旧记录迁到新 serial 并同步所有引用。
+
+    做三件事（一个事务内）：
+      1. 把旧记录的 serial 改成新地址（名称/型号/备注/启用状态/添加时间全部保留）
+      2. 同步 device_group.serials 里的旧 serial → 新 serial（否则分组吊着死 IP）
+      3. 同步 task_job.target.serial（指定设备模式的任务目标）
+
+    返回 (old_serial, name)；没有匹配到旧记录时返回 (None, "")。
+    """
+    fingerprint = (fingerprint or "").strip()
+    new_serial = (new_serial or "").strip()
+    if not fingerprint or not new_serial:
+        return None, ""
+    with _ctx():
+        old = Device.query.filter(Device.fingerprint == fingerprint,
+                                  Device.serial != new_serial).first()
+        if not old:
+            return None, ""
+        old_serial, name = _move_device_row(old, new_serial)
+        _log.info(f"设备认领: 指纹 {fingerprint} 的『{name or old_serial}』"
+                  f"由 {old_serial} 迁到 {new_serial}")
+        return old_serial, name
+
+
+def relocate_device(old_serial, new_serial, fingerprint=""):
+    """人工认领：把池中 old_serial 的记录改到 new_serial（换地址的手工兜底）。
+
+    用在"设备已经断联、读不到指纹"的场景：设备换了 IP 后旧地址连不上，
+    指纹也没采过，自动认领无从匹配——此时由人工指认"这条就是那台，
+    现在在 X"，本函数负责迁移并同步分组/任务引用。
+
+    返回 (ok, name, msg)。
+    """
+    old_serial = (old_serial or "").strip()
+    new_serial = (new_serial or "").strip()
+    if not old_serial or not new_serial:
+        return False, "", "缺少参数"
+    if old_serial == new_serial:
+        return False, "", "新旧地址相同，无需迁移"
+    with _ctx():
+        old = Device.query.get(old_serial)
+        if not old:
+            return False, "", f"设备池中没有 {old_serial}"
+        if Device.query.get(new_serial) is not None:
+            return False, "", f"{new_serial} 已在设备池中，请先处理那条记录"
+        _, name = _move_device_row(old, new_serial, fingerprint)
+        _log.info(f"设备人工认领: 『{name or old_serial}』{old_serial} → {new_serial}")
+        return True, name, f"『{name or old_serial}』已迁到 {new_serial}，分组/任务引用已同步"
+
+
+# ================== 管理（CRUD） ==================
+def add_device(serial, name="", note="", enabled=True, fingerprint=""):
+    """添加/更新设备（upsert）。返回 True 新增 / False 已存在并更新。"""
+    serial = (serial or "").strip()
+    if not serial:
+        return False
+    with _ctx():
+        d = Device.query.get(serial)
+        if d:
+            d.name, d.note, d.enabled = name or "", note or "", enabled
+            if fingerprint:
+                d.fingerprint = fingerprint
+            db.session.commit()
+            refresh_names()          # 名字可能改了：通知里要立刻用新名字
+            return False
+        db.session.add(Device(serial=serial, name=name or "", note=note or "",
+                              enabled=enabled, fingerprint=fingerprint or "",
+                              created_at=time.strftime("%Y-%m-%d %H:%M")))
+        db.session.commit()
+        refresh_names()
+        _log.info(f"设备池新增设备: {serial}")
+        return True
+
+
+def rename_device(serial, name):
+    """重命名设备（唯一性由调用方先校验）。返回是否成功。"""
+    name = (name or "").strip()
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d or not name or (d.name or "") == name:
+            return False
+        old = d.name or ""
+        d.name = name
+        db.session.commit()
+        refresh_names()
+        _log.info(f"设备池重命名: {old or serial} → {name}（{serial}）")
+        return True
+
+
+def set_fingerprint(serial, fingerprint):
+    """补写设备指纹（认领需要；采集是后来才做的）。"""
+    fingerprint = (fingerprint or "").strip()
+    if not fingerprint:
+        return False
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d or d.fingerprint == fingerprint:
+            return False
+        d.fingerprint = fingerprint
+        db.session.commit()
+        _log.info(f"设备池采集指纹: {serial} -> {fingerprint}")
+        return True
+
+
+def remove_device(serial):
+    """删除设备。返回是否删除成功。"""
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d:
+            return False
+        db.session.delete(d)
+        db.session.commit()
+        refresh_names()
+        _log.info(f"设备池删除设备: {serial}")
+        return True
+
+
+def set_enabled(serial, enabled):
+    """启用/停用设备（停用后不参与调度）。返回是否成功。"""
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d:
+            return False
+        d.enabled = enabled
+        db.session.commit()
+        return True
+
+
+# ================== 型号采集 ==================
+def refresh_model(serial, timeout=8):
+    """采集单台设备型号（getprop ro.product.model）并写回 DB。
+
+    IP:5555 设备走本机 adb；USB 设备先查本机 adb，查不到再查 220 远程 adb server。
+    采集失败返回空串（静默，不影响主流程）。返回采集到的型号。
+    """
+    if not serial:
+        return ""
+    model = ""
+    if ":" in serial:
+        try:
+            r = subprocess.run([ADB_PATH, "-s", serial, "shell",
+                                "getprop", "ro.product.model"],
+                               capture_output=True, timeout=timeout)
+            model = (r.stdout or b"").decode("utf-8", errors="replace").strip()
+        except Exception:
+            model = ""
+    else:
+        # USB：先本机，再远程
+        try:
+            r = subprocess.run([ADB_PATH, "-s", serial, "shell",
+                                "getprop", "ro.product.model"],
+                               capture_output=True, timeout=timeout)
+            model = (r.stdout or b"").decode("utf-8", errors="replace").strip()
+        except Exception:
+            model = ""
+        if not model:
+            model = _adb_remote(USB_ADB_HOST, USB_ADB_PORT, "-s", serial,
+                                "shell", "getprop", "ro.product.model")
+    model = model.strip() or ""
+    if not model:
+        return ""
+    with _ctx():
+        d = Device.query.get(serial)
+        if d and d.model != model:
+            d.model = model
+            db.session.commit()
+            _log.info(f"设备池采集型号: {serial} -> {model}")
+    return model
+
+
+def refresh_fingerprint(serial, timeout=6):
+    """读取并写回设备指纹，返回指纹（失败返回空串）。"""
+    fp = read_fingerprint(serial, timeout=timeout)
+    if fp:
+        set_fingerprint(serial, fp)
+    return fp
+
+
+def refresh_info(serial):
+    """采集一台设备的型号 + 指纹（指纹缺失时才读，避免每次启动都白跑一次 adb）。
+
+    返回 (model, fingerprint)。任一失败都静默——设备池展示用，不影响主流程。
+    """
+    model = refresh_model(serial)
+    fp = ""
+    with _ctx():
+        row = Device.query.get(serial)
+        fp = (row.fingerprint or "") if row else ""
+    if not fp:
+        fp = refresh_fingerprint(serial)
+    return model, fp
+
+
+def refresh_all_models():
+    """批量采集池内在线设备的型号（顺带补齐缺失的设备指纹），并发 10，后台线程调用。
+
+    返回成功数。指纹补齐很重要：老库里的设备没有指纹，补上之后换 IP 才能被认领。
+    """
+    serials = list_online()
+    if not serials:
+        return 0
+    from concurrent.futures import ThreadPoolExecutor, as_completed
+    ok = 0
+    with ThreadPoolExecutor(max_workers=min(10, len(serials))) as pool:
+        futures = {pool.submit(refresh_info, s): s for s in serials}
+        for fut in as_completed(futures):
+            try:
+                model, _fp = fut.result()
+                if model:
+                    ok += 1
+            except Exception:
+                pass
+    _log.info(f"设备池批量采集型号完成: {ok}/{len(serials)} 台")
+    return ok
@@ -1,9 +1,9 @@
 """设备生命周期 + 通用 Worker 基类 + 全局状态注册表 + 心跳看门狗。

-  STFDevice    — 单设备生命周期：acquire（占用+adb连接）→ release（断开+释放）
-  BaseWorker   — 通用 worker 基类：封装 STF 生命周期 + u2 连接 + 状态上报 + stop
+  STFDevice    — 单设备生命周期：acquire（直连/远程 server）→ release
+  BaseWorker   — 通用 worker 基类：封装设备生命周期 + u2 连接 + 状态上报 + stop
                 + 生命周期钩子(setup/teardown/on_error) + 心跳上报
-                 子类只需实现 run_task(d)，可选实现钩子，不用管 STF/adb/状态/异常
+                 子类只需实现 run_task(d)，可选实现钩子，不用管 adb/状态/异常
  _WORKERS     — 全局状态注册表，供 web_server 读取实时状态
  _watchdog    — 心跳看门狗线程，检测 worker 卡死

@@ -16,12 +16,26 @@ from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeou

 import uiautomator2 as u2

+from config import USB_ADB_HOST, USB_ADB_PORT
 from core.logger import get_logger
-from core.stf_client import DeviceOfflineError, STFError
-from .adb_helper import adb_connect, adb_disconnect
+from core import device_pool
+from core import notifier
+from .adb_helper import _adb, adb_connect, _adb_remote

 _log = get_logger("core.worker")

+
+class STFError(Exception):
+    """设备操作错误（历史名称保留兼容）。code: offline/conflict/..."""
+
+    def __init__(self, message, code=""):
+        super().__init__(message)
+        self.code = code
+
+
+class DeviceOfflineError(STFError):
+    """设备离线/不可用：任务不重试（换设备也没用）。"""
+
 # 心跳超时阈值（秒）。worker 超过这个时间没更新心跳，判定为卡死
 _HEARTBEAT_TIMEOUT = 120
 # 看门狗检查间隔
@@ -32,65 +46,58 @@ _U2_INFO_TIMEOUT = 10


 class STFDevice:
-    """单设备生命周期：acquire（占用+连接）→ release（断开+释放）。
+    """单设备生命周期：acquire（直连）→ release（无操作）。

-    用 try/finally 保证设备一定被释放，即使养号中途报错。
+    阶段 2：已摘除 STF occupy/release 与 remoteConnect 桥接——
+    单实例互斥由 TaskManager._running 保证；非 IP:port（USB 序列号）设备
+    通过 220 的远程 adb server（-H/-P）驱动，不再依赖 STF。
    """

-    def __init__(self, stf_client, serial=None):
-        self.stf = stf_client
+    def __init__(self, serial=None):
        self.serial = serial
-        self.remote_adb_url = None
+        self.remote_adb_url = None      # IP:5555 设备：设备地址
+        self.usb_server = None          # USB 设备：远程 adb server 地址（host:port）

    def acquire(self, serial=None):
        self.serial = serial or self.serial or self._pick_free()
        _log.info(f"[{self.serial}] 选定设备")

-        ok, msg = self.stf.occupy(self.serial)
-        if not ok:
-            raise STFError(f"占用设备失败: {msg}", "conflict")
-        _log.info(f"[{self.serial}] STF 占用成功")
-
        # 直连优先：serial 本身是 IP:5555（如 Tailscale 网络设备）时直接 adb connect。
-        # 实测（本机 100.100.10.2，设备 100.100.10.x）：
-        #   - 本机在 tailnet 内时直连可靠且快（<1s），且只 connect、绝不 disconnect/kill-server，
-        #     不会影响 STF provider 共享的 adb 连接（STF 端设备保持 present/ready）。
-        #   - STF remoteConnect 桥接在此环境反而有 adb key 认证问题（隧道显示 unauthorized，
-        #     即使设备已授权本机 key），直连才是可靠路径。
-        # 仅当 serial 不是 IP:port（如 USB 序列号）时才走 STF 桥接。
+        # 只 connect、绝不 disconnect/kill-server（红线），不影响共享 adb transport。
        if ":" in self.serial:
            self.remote_adb_url = self.serial
            _log.info(f"[{self.serial}] 直连设备: {self.remote_adb_url}")
+            if not adb_connect(self.remote_adb_url):
+                raise STFError(f"adb connect 失败: {self.remote_adb_url}", "offline")
        else:
-            self.remote_adb_url = self.stf.remote_connect(self.serial)
-            _log.info(f"[{self.serial}] STF 桥接: {self.remote_adb_url}")
-
-        if not adb_connect(self.remote_adb_url):
-            raise STFError(f"adb connect 失败: {self.remote_adb_url}", "offline")
+            # USB 设备（serial 无冒号）：优先本机 adb（插在平台本机），
+            # 其次 220 远程 adb server（插在 220 上，经 Tailscale 驱动）。
+            # 两者都不需要 adb connect——设备已连接在对应 server 上，只做可见性校验。
+            local = {line.split()[0] for line in (_adb("devices") or "").splitlines()[1:]
+                     if len(line.split()) >= 2}
+            if self.serial in local:
+                self.remote_adb_url = self.serial  # u2 走本地 adb（无需 connect）
+                _log.info(f"[{self.serial}] USB 设备，本机 adb 直连")
+            else:
+                self.usb_server = f"{USB_ADB_HOST}:{USB_ADB_PORT}"
+                _log.info(f"[{self.serial}] USB 设备，远程 adb server: {self.usb_server}")
+                out = _adb_remote(USB_ADB_HOST, USB_ADB_PORT, "devices") or ""
+                seen = {line.split()[0] for line in out.splitlines()[1:]
+                        if len(line.split()) >= 2}
+                if self.serial not in seen:
+                    raise STFError(
+                        f"USB 设备 {self.serial} 不在本机 adb 也不在远程 adb server", "offline")
        time.sleep(2)

    def _pick_free(self):
-        free = self.stf.list_free_devices()
+        free = device_pool.list_ready()
        if not free:
            raise STFError("没有可用的在线空闲设备", "offline")
-        return free[0]["serial"]
+        return free[0]

    def release(self):
-        if not self.serial:
-            return
-        # 直连模式（remote_adb_url == serial）：不 disconnect
-        # STF provider 共享该 IP:5555 的 adb transport，disconnect 会让 STF 误判离线并重连
-        if self.remote_adb_url and self.remote_adb_url != self.serial:
-            adb_disconnect(self.remote_adb_url)
-            try:
-                self.stf.remote_disconnect(self.serial)
-            except Exception:
-                pass
-        ok, msg = self.stf.release(self.serial)
-        if ok:
-            _log.info(f"[{self.serial}] 已释放")
-        else:
-            _log.warning(f"[{self.serial}] STF 释放失败: {msg}")
+        # 直连模式：不 disconnect（红线，STF 共享 transport）；USB：无连接可断
+        pass


 # ================== 全局 worker 状态注册表（供 web_server 读取） ==================
@@ -115,6 +122,36 @@ def _remove_worker(serial):
        _WORKERS.pop(serial, None)


+def clear_worker_error(serial):
+    """清除设备错误/失败状态，恢复为 idle。运行中/连接中返回 False 不清理。
+
+    检查与更新在同一把锁内完成，避免与任务启动写 connecting/running 的竞态。
+    """
+    with _WORKERS_LOCK:
+        w = _WORKERS.get(serial)
+        if w is None:
+            return True  # 本就没有状态记录，视作已清理
+        if w.get("status") in ("running", "connecting"):
+            return False
+        w.update(status="idle", last_error="", last_warning="", task_job="",
+                 current_action="", attempt=0, progress={}, end_time=0,
+                 last_heartbeat=time.time())
+    return True
+
+
+def clear_all_worker_errors(exclude=()):
+    """批量清除所有 error/failed 状态（exclude 里的跳过）。返回清除数。"""
+    exclude = set(exclude)
+    with _WORKERS_LOCK:
+        targets = [s for s, w in _WORKERS.items()
+                   if s not in exclude and w.get("status") in ("error", "failed")]
+    cleared = 0
+    for s in targets:
+        if clear_worker_error(s):
+            cleared += 1
+    return cleared
+
+
 def get_worker_heartbeat(serial):
    """返回 worker 最近一次心跳时间，没有返回 0。"""
    with _WORKERS_LOCK:
@@ -152,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()
@@ -184,11 +230,11 @@ def stop_watchdog():
 class BaseWorker(threading.Thread):
    """通用 worker 基类。

-    自动处理：STF 占用/释放、u2 连接、状态上报、异常捕获、stop 信号、心跳。
+    自动处理：设备获取、u2 连接、状态上报、异常捕获、stop 信号、心跳。
    子类只需实现 run_task(d) 方法，专注业务逻辑。

    生命周期（基类 run() 已封装，不要重写）：
-      1. acquire 设备（STF 占用 + adb 连接）
+      1. acquire 设备（直连 IP:5555 / USB 走远程 adb server）
      2. u2.connect 拿到 d
      3. 调用 setup(d)        ← 子类可选钩子，做初始化
      4. 调用子类 run_task(d)  ← 业务逻辑
@@ -229,11 +275,13 @@ class BaseWorker(threading.Thread):
      其他异常           — 可重试
    """

-    def __init__(self, stf_client, serial, params=None, daemon=True):
+    def __init__(self, serial, params=None, daemon=True, ctx=None):
        super().__init__(daemon=daemon)
-        self.stf = stf_client
        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 上报）
@@ -329,15 +377,20 @@ class BaseWorker(threading.Thread):
    # ================== 基类主循环（不要重写） ==================
    def run(self):
        """基类主循环：不要重写。子类实现 run_task + 可选钩子。"""
-        device = STFDevice(self.stf, serial=self.serial)
-        _update_status(self.serial, status="connecting", stf_occupied=False,
-                       last_error="", remote_adb_url="", model="",
+        device = STFDevice(serial=self.serial)
+        _update_status(self.serial, status="connecting",
+                       last_error="", remote_adb_url="", usb_server="", model="",
                       current_action="")
        try:
            device.acquire()
            remote = device.remote_adb_url
-            # u2.connect 可能 hang 住（atx-agent 无响应），用线程池+超时保护
-            self.d = self._u2_connect_with_timeout(remote)
+            usb_server = device.usb_server
+            # u2.connect 可能 hang 住（atx-agent 无响应），用线程池+超时保护；
+            # USB 设备（无 IP:5555）经远程 adb server 建 u2 连接
+            if usb_server:
+                self.d = self._u2_connect_usb_with_timeout(usb_server)
+            else:
+                self.d = self._u2_connect_with_timeout(remote)
            if self.d is None:
                raise STFError(f"u2.connect 超时 {_U2_CONNECT_TIMEOUT}s，atx-agent 无响应", "offline")
            _log.info(f"[{self.serial}] u2 连接成功")
@@ -348,8 +401,9 @@ class BaseWorker(threading.Thread):
                    model = info.get("productName") or ""
            except Exception:
                pass
-            _update_status(self.serial, status="running", stf_occupied=True,
-                           remote_adb_url=remote, model=model)
+            _update_status(self.serial, status="running",
+                           remote_adb_url=remote or "", usb_server=usb_server or "",
+                           model=model)

            # setup 钩子
            try:
@@ -402,9 +456,9 @@ class BaseWorker(threading.Thread):
            with _WORKERS_LOCK:
                cur = _WORKERS.get(self.serial, {}).get("status")
            if cur in ("running", "connecting"):
-                _update_status(self.serial, stf_occupied=False, status="released")
+                _update_status(self.serial, status="released")
            else:
-                _update_status(self.serial, stf_occupied=False)
+                pass

    def _u2_connect_with_timeout(self, remote):
        """u2.connect 带超时保护，避免 atx-agent 无响应时永久 hang。"""
@@ -415,6 +469,28 @@ class BaseWorker(threading.Thread):
            except FuturesTimeout:
                _log.error(f"[{self.serial}] u2.connect 超时 {_U2_CONNECT_TIMEOUT}s")
                return None
+
+    def _u2_connect_usb_with_timeout(self, server):
+        """USB 设备：经远程 adb server（220）建 u2 连接，带超时保护。
+
+        u2 3.7 底层 adbutils 支持远程 adb server：AdbClient(host, port).device(serial)，
+        再交给 u2.connect(AdbDevice)（与本地连接同语义，无需 adb connect）。
+        """
+        host, _, port = server.partition(":")
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            def _connect():
+                from adbutils import AdbClient
+                dev = AdbClient(host=host, port=int(port)).device(self.serial)
+                return u2.connect(dev)
+            fut = pool.submit(_connect)
+            try:
+                return fut.result(timeout=_U2_CONNECT_TIMEOUT)
+            except FuturesTimeout:
+                _log.error(f"[{self.serial}] u2 远程连接超时 {_U2_CONNECT_TIMEOUT}s")
+                return None
+            except Exception as e:
+                _log.error(f"[{self.serial}] u2 远程连接失败: {e}")
+                return None
            except Exception as e:
                _log.error(f"[{self.serial}] u2.connect 异常: {e}")
                return None
@@ -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
@@ -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"]
@@ -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"
@@ -41,7 +45,7 @@ def get_logger(name="core"):
    """获取指定模块的 logger。

    name: 模块名（core/task/web/action），决定写哪个文件。
-          也可传子模块名如 "task.douyin"，会归到 task.log。
+          也可传子模块名如 "task.generic"，会归到 task.log。
    返回配置好的 logging.Logger。
    """
    if name in _LOGGERS:
@@ -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}"
@@ -17,11 +17,13 @@
 import os
 import json
 import hashlib
+import sqlite3

 from flask_sqlalchemy import SQLAlchemy
 from flask_login import UserMixin
 from sqlalchemy import event, text
 from sqlalchemy.engine import Engine
+from werkzeug.security import generate_password_hash, check_password_hash

 from core.logger import get_logger

@@ -30,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")
@@ -44,17 +67,53 @@ def _sqlite_pragma(dbapi_connection, connection_record):


 class User(UserMixin, db.Model):
-    """后台用户。"""
+    """后台用户。
+
+    权限模型：
+      - is_admin=True：管理员，拥有全部权限，不受 perms 限制
+      - is_admin=False：按 perms 授权（JSON 数组，如 ["tasks","devices"]）
+      - 权限位：tasks=任务管理, devices=设备控制, apks=应用管理, logs=日志查看
+      - 用户管理本身只有管理员能做（web_server 层强制），不设普通权限位
+    """
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
-    password_hash = db.Column(db.String(120), nullable=False)
+    password_hash = db.Column(db.String(255), nullable=False)
    is_admin = db.Column(db.Boolean, default=True)
+    perms = db.Column(db.Text, default="[]")          # JSON 数组：业务权限位
+
+    def get_perms(self):
+        try:
+            return json.loads(self.perms or "[]")
+        except Exception:
+            return []
+
+    def set_perms(self, lst):
+        """设置权限位。管理员强制为全部权限（内部不区分）。"""
+        self.perms = json.dumps(list(lst or []), ensure_ascii=False)
+
+    def has_perm(self, perm):
+        """是否拥有指定权限。管理员恒为 True。"""
+        if self.is_admin:
+            return True
+        return perm in self.get_perms()

    def set_password(self, password):
-        self.password_hash = hashlib.sha256(password.encode()).hexdigest()
+        self.password_hash = generate_password_hash(password)

    def check_password(self, password):
-        return self.password_hash == hashlib.sha256(password.encode()).hexdigest()
+        """校验密码。兼容旧 SHA-256 哈希（匹配则自动升级为新哈希）。"""
+        ph = self.password_hash or ""
+        if ph and not ph.startswith(("pbkdf2:", "scrypt:")):
+            # 旧版裸 SHA-256：比对通过则升级为加盐哈希
+            if hashlib.sha256(password.encode()).hexdigest() == ph:
+                self.set_password(password)
+                try:
+                    db.session.commit()
+                except Exception:
+                    pass
+                return True
+            return False
+        return check_password_hash(ph, password)

    def __repr__(self):
        return f"<User {self.username}>"
@@ -91,7 +150,7 @@ class TaskJob(db.Model):
    """
    id = db.Column(db.String(32), primary_key=True)   # uuid 前 8 位
    name = db.Column(db.String(120), nullable=False)
-    task_type = db.Column(db.String(60), default="douyin_nurture")
+    task_type = db.Column(db.String(60), default="generic_steps")
    target = db.Column(db.Text, default='{"mode":"all"}')       # JSON
    params = db.Column(db.Text, default="{}")                    # JSON
    schedule = db.Column(db.Text, default='{"mode":"once"}')     # JSON
@@ -179,52 +238,596 @@ class ApkFile(db.Model):
        return f"<ApkFile {self.display_name}>"


-# 版本化 schema 迁移：新增结构变更时在此追加 (版本号, 说明, SQL)
-# 版本号单调递增，只执行比当前 schema_version 新的迁移。
+class Device(db.Model):
+    """设备池（本地设备清单，替代 STF 池作为调度数据源）。
+
+    serial 即 adb 序列号（IP:5555 或 USB 序列号）；enabled=False 不参与调度。
+    model 为在线时自动采集的型号（如 Redmi 12C），供管理页/监控页区分设备。
+    """
+    serial = db.Column(db.String(120), primary_key=True)
+    name = db.Column(db.String(80), default="")        # 设备名（唯一，人可读标识）
+    model = db.Column(db.String(120), default="")      # 型号（自动采集）
+    enabled = db.Column(db.Boolean, default=True)      # 是否参与调度
+    note = db.Column(db.Text, default="")              # 备注
+    created_at = db.Column(db.String(20), default="")  # 添加时间
+    # 上次探测到的**抖音当前登录账号名字**（「发布计划 → 一键推送（按名字找设备）」用）。
+    # 只是**缓存**：自动任务永远现场读屏幕，不读这两列（缓存旧了也不影响发布正确性）。
+    cur_account_name = db.Column(db.String(80), default="")
+    cur_name_at = db.Column(db.String(20), default="")   # 上面那个名字是什么时候读的
+    # 设备指纹（ro.serialno）：识别"同一台物理设备"的稳定标识。
+    # 网络设备（serial=IP:5555）换 IP 后靠它认领回原记录，名称/分组/任务引用都不丢。
+    fingerprint = db.Column(db.String(120), default="")
+
+    def to_dict(self):
+        return {"serial": self.serial, "name": self.name or "",
+                "model": self.model or "", "enabled": bool(self.enabled),
+                "note": self.note or "", "created_at": self.created_at or "",
+                "fingerprint": self.fingerprint or "",
+                "cur_account_name": self.cur_account_name or "",
+                "cur_name_at": self.cur_name_at or ""}
+
+    def __repr__(self):
+        return f"<Device {self.serial}>"
+
+
+class PendingDevice(db.Model):
+    """自动发现待连接池：扫描验证通过的设备，等待用户确认后才入正式池。
+
+    与 Device 表的区别：只代表"被扫描到、可连接"，不参与任务调度。
+    """
+    serial = db.Column(db.String(120), primary_key=True)   # 如 192.168.20.5:5555
+    source = db.Column(db.String(20), default="")          # lan / tailscale
+    first_seen = db.Column(db.String(20), default="")      # 首次发现时间
+    last_seen = db.Column(db.String(20), default="")       # 最近一次扫描仍可见的时间
+    # 扫描时顺带读取的设备指纹：与设备池中已有记录比对，用于提示
+    # 「这台其实就是 <名称>（原 IP 变了）」而不是让用户在一堆陌生 IP 里猜
+    fingerprint = db.Column(db.String(120), default="")
+
+    def to_dict(self):
+        return {"serial": self.serial, "source": self.source or "",
+                "first_seen": self.first_seen or "", "last_seen": self.last_seen or "",
+                "fingerprint": self.fingerprint or ""}
+
+
+class AppMeta(db.Model):
+    """全局 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 DoneMark(db.Model):
+    """「已做过」账本：跨设备幂等的标记（「任务 → 去重记录」页）。
+
+    要解决的问题（用户场景）：一台手机登录多个账号、多台手机跑同一个任务，
+    任务被反复重跑（因为不知道什么时候跑完）→ 同一个号被做两次、有的号还没做。
+
+    **判据只有一条：`scope_key` 的唯一索引。**
+    多台设备可能同时判断"没做过"，"先查后插"会两台都插进去；
+    唯一索引 + `INSERT ... ON DUPLICATE KEY`/`INSERT OR IGNORE` 的**受影响行数**
+    才是原子的（见 `core/dedup.py` 的 `mark()`）。
+
+    写入方是任务步骤 `_exec_mark_done`（**成功之后才记账**）：动作失败就不记账，
+    下次重跑还会重试该设备——这是"失败不丢"的关键。
+
+    `kind` 是有效期策略（`day`/`hours`/`all`），清理时**只删 day/hours**：
+    `all` 代表"只做一次"，删掉就等于去重失效。
+    """
+    __tablename__ = "done_mark"
+    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
+    scope_key = db.Column(db.String(300), unique=True)      # 幂等的全部依据（唯一索引）
+    kind = db.Column(db.String(12), default="day")          # day / hours / all
+    job_id = db.Column(db.String(32), default="", index=True)
+    job_name = db.Column(db.String(120), default="")
+    serial = db.Column(db.String(120), default="")
+    device_name = db.Column(db.String(80), default="")
+    identity = db.Column(db.String(200), default="")        # 身份值（如抖音号）
+    created_at = db.Column(db.String(20), default="", index=True)
+
+    __table_args__ = (
+        db.Index("ix_done_mark_job_ts", "job_id", "created_at"),
+    )
+
+
+class DeviceAccount(db.Model):
+    """账号台账（**2026-10-12 起已停用**：页面/接口/任务依赖全部下线，表和数据保留）。
+
+    保留模型 = 保留表和 42 行历史数据、并继续留在备份清单（`SUMMARY_TABLES` 按模型派生）——
+    停用不等于删数据（删不可逆）。新功能**不要再读写这张表**。
+    历史用途：一台设备上登录着哪些账号（「账号」页维护）。
+
+    要解决的问题（用户场景）：一台手机登好几个抖音号、十几台手机四五十个号，
+    账号信息散在一张电子表格里 —— 换 IP、加号、想查"这台登的是哪几个号"都要翻表。
+    这里把台账落进平台：web 能查能改（支持从表格粘贴导入），
+    手机端 Agent 的「身份大字页」顺带显示本机账号，任务的「条件判断」
+    也可以直接从台账取号（不用再把号一个个手写进 cmp_value）。
+
+    ⚠ **`douyin_id` 是纯号（`35377983067`），而元素原文是 `抖音号：35377983067`。**
+    - 当条件判断的**比对值**可以 ✓（运算符用「包含」，纯号是子串）
+    - **绝不能当去重身份** ✗ —— `done_mark.identity` 存的是元素原文、逐字算 key，
+      格式不一致会让去重**静默失效**（见 `core/dedup.py`）。
+
+    `device_name` 是设备号（平台设备名，如 A01）；`serial` 是**录入时的地址快照**，
+    设备换 IP 或改名后，台账靠任一侧都能找回来（账号管理已停用，这列仅留作历史数据）。
+    同一抖音号不允许两条 —— 唯一性由服务层保证（号可能为空，DB 层要做
+    "部分唯一索引"三处方言适配，人工维护的几十条不值当）。
+    """
+    __tablename__ = "device_account"
+    id = db.Column(db.String(32), primary_key=True)                 # uuid 前 8 位
+    device_name = db.Column(db.String(80), default="", index=True)  # 设备号（平台设备名）
+    serial = db.Column(db.String(120), default="")                  # 录入时的地址快照
+    phone = db.Column(db.String(32), default="", index=True)        # 手机号
+    nickname = db.Column(db.String(80), default="")                 # 账号名称
+    douyin_id = db.Column(db.String(64), default="", index=True)    # 抖音号（纯号，不带前缀）
+    registered_at = db.Column(db.String(20), default="")            # 注册时间（原样存文本）
+    sim_in_device = db.Column(db.Boolean, default=False)            # 卡在机内（空=否）
+    can_post_video = db.Column(db.Boolean, default=False)           # 可发视频（空=否）
+    bio = db.Column(db.Text, default="")                            # 简介
+    note = db.Column(db.Text, default="")                           # 备注
+    created_at = db.Column(db.String(20), default="")
+    updated_at = db.Column(db.String(20), default="")
+
+    def to_dict(self):
+        return {"id": self.id, "device_name": self.device_name or "",
+                "serial": self.serial or "", "phone": self.phone or "",
+                "nickname": self.nickname or "", "douyin_id": self.douyin_id or "",
+                "registered_at": self.registered_at or "",
+                "sim_in_device": bool(self.sim_in_device),
+                "can_post_video": bool(self.can_post_video),
+                "bio": self.bio or "", "note": self.note or "",
+                "created_at": self.created_at or "", "updated_at": self.updated_at or ""}
+
+    def __repr__(self):
+        return f"<DeviceAccount {self.device_name} {self.nickname}>"
+
+
+class VideoPlan(db.Model):
+    """视频发布计划：账号 × 发布日期 × 编号 → 一个视频素材 + 一条标题 + 发布结果。
+
+    一条记录 = **一个账号在某天要发的一个视频**（素材与计划天然 1:1，所以不拆两张表；
+    但上传是分两步的 —— 先视频后标题或反过来 —— 靠 `status` 的 `pending` 态兜住）。
+
+    **状态机**（这是本表的灵魂，不要简化）：
+
+    | status | 含义 |
+    |---|---|
+    | `pending` | 有视频、还没标题 |
+    | `ready` | 素材齐，等发布日期 |
+    | `pushing` | 已原子占位，正在把视频推到手机 |
+    | `publishing` | 已推到手机，正在走抖音发布流程 |
+    | `done` | 发布成功（终态） |
+    | `failed` | 失败在 `push`/`scan` 阶段 —— 还没碰抖音，**可安全重试** |
+    | `unknown` | 失败在 `post`/`verify` 阶段 —— **可能已经发出去了，绝不自动重试**，要人工裁决 |
+    | `skipped` | 人工跳过（终态） |
+
+    ⚠ **`failed` 与 `unknown` 必须分开**：把"不知道自己发没发"混成"知道自己没发"，
+    就是重复发布的来源。`stage` 记录失败发生在哪一步，是这两者互相转换的唯一依据。
+
+    **唯一性**：`(nickname, release_date, seq)` 由服务层（`core/video_plan.py`）保证，
+    **不加 DB 唯一索引** —— `seq` 从 1 起、没有"空值"可言，做部分唯一索引要写三处方言适配
+    （见 §唯一索引那段注释与 `_ensure_unique_indexes`），收益不匹配；违反的代价只是
+    低频人工上传产生的重复行，可见、可删。
+
+    **分享链接**：发布成功后抓作品的分享链接存 `share_url` —— 平台**不长期囤视频**
+    （存不下），链接才是长期资产，也方便后续拿它去铺评论。
+    """
+    __tablename__ = "video_plan"
+    id = db.Column(db.String(32), primary_key=True)                 # uuid 前 8 位
+    account_id = db.Column(db.String(32), default="", index=True)   # 老台账账号 id（已停用，保留列）
+    phone = db.Column(db.String(32), default="", index=True)        # 老台账手机号快照（已停用，保留列）
+    device_name = db.Column(db.String(80), default="", index=True)  # 设备号快照（**已不写入**；实际由谁发的看 posted_device_name）
+    nickname = db.Column(db.String(80), default="")                 # **识别键**：上传文件名里的名字（= 抖音昵称）
+    douyin_id = db.Column(db.String(64), default="")                # 抖音号快照（已停用，保留列）
+    serial = db.Column(db.String(120), default="")                  # 地址快照（已停用，保留列）
+    release_date = db.Column(db.String(10), default="", index=True)  # "YYYY-MM-DD"（纯日期，等值比较）
+    seq = db.Column(db.Integer, default=1)                          # 编号，从 1 起（不用 0 表示"无"）
+    seq_auto = db.Column(db.Boolean, default=True)                  # 编号是自动分配出来的（界面要提示）
+    title = db.Column(db.Text, default="")                          # 标题（抖音发布页的「标题」框）
+    body = db.Column(db.Text, default="")                           # 正文/文案（发布页的文案框；标题 txt 里用 || 分隔）
+    video_file = db.Column(db.String(120), default="")              # 平台落盘文件名（不含绝对路径）
+    video_name = db.Column(db.String(200), default="")              # 原始上传名（排查用）
+    video_size = db.Column(db.Integer, default=0)
+    video_sha1 = db.Column(db.String(40), default="")               # 内容指纹（重复上传的判据）
+    status = db.Column(db.String(16), default="", index=True)
+    stage = db.Column(db.String(16), default="")                    # push/scan/post/verify（决定 failed vs unknown）
+    attempts = db.Column(db.Integer, default=0)                     # 尝试次数（超上限不再自动取）
+    published_at = db.Column(db.String(20), default="")
+    share_url = db.Column(db.String(300), default="")               # 作品分享链接（发布后抓取）
+    link_at = db.Column(db.String(20), default="")                  # 抓到链接的时刻
+    video_deleted_at = db.Column(db.String(20), default="")         # 平台素材文件何时被清理
+    push_verify = db.Column(db.String(16), default="")              # 推送后的相册校验：ok=进索引 / no_index=没进 / nofile=文件不在
+    push_remote = db.Column(db.String(200), default="")             # 推到手机上的绝对路径（删它/排查用）
+    posted_serial = db.Column(db.String(120), default="")           # **实际是哪台设备发的**（地址快照）
+    posted_device_name = db.Column(db.String(80), default="")       # **实际是哪台设备发的**（设备名，界面显示用）
+    last_error = db.Column(db.String(500), default="")
+    note = db.Column(db.Text, default="")
+    created_at = db.Column(db.String(20), default="", index=True)
+    updated_at = db.Column(db.String(20), default="")
+
+    __table_args__ = (
+        db.Index("ix_video_plan_date_status", "release_date", "status"),
+        db.Index("ix_video_plan_acct_date", "account_id", "release_date"),
+        db.Index("ix_video_plan_phone_slot", "phone", "release_date", "seq"),
+        db.Index("ix_video_plan_file", "video_file"),
+        # 主查询路径（按名字取待发计划/查重）——老库靠 _ensure_plain_indexes 补建
+        db.Index("ix_video_plan_name_date", "nickname", "release_date"),
+    )
+
+    def to_dict(self):
+        return {"id": self.id, "account_id": self.account_id or "",
+                "phone": self.phone or "", "device_name": self.device_name or "",
+                "nickname": self.nickname or "", "douyin_id": self.douyin_id or "",
+                "serial": self.serial or "", "release_date": self.release_date or "",
+                "seq": int(self.seq or 1), "seq_auto": bool(self.seq_auto),
+                "title": self.title or "", "body": self.body or "",
+                "video_file": self.video_file or "",
+                "video_name": self.video_name or "", "video_size": int(self.video_size or 0),
+                "video_sha1": self.video_sha1 or "", "status": self.status or "",
+                "stage": self.stage or "", "attempts": int(self.attempts or 0),
+                "published_at": self.published_at or "", "share_url": self.share_url or "",
+                "link_at": self.link_at or "", "video_deleted_at": self.video_deleted_at or "",
+                "push_verify": self.push_verify or "", "push_remote": self.push_remote or "",
+                "posted_serial": self.posted_serial or "",
+                "posted_device_name": self.posted_device_name or "",
+                "last_error": self.last_error or "", "note": self.note or "",
+                "created_at": self.created_at or "", "updated_at": self.updated_at or ""}
+
+    def __repr__(self):
+        return f"<VideoPlan {self.phone} {self.release_date} #{self.seq} {self.status}>"
+
+
+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, "初始 schema（由 create_all 建立，版本标记从 1 开始）", None),
+    (1, "用户权限位：user 表新增 perms 列（JSON 数组，默认空=无业务权限，管理员不受限）", None),
+    (2, "设备池：device 表（本地设备清单，替代 STF 池）", None),
+    (3, "设备池：device 表新增 model 列（型号，在线时自动采集）", None),
+    (4, "自动发现：pending_device 待连接池表（扫描发现的设备，用户确认后才入正式池）", None),
+    (5, "设备池：device 表新增 fingerprint 列（设备指纹 ro.serialno，换 IP 后认领回原记录）", None),
+    (6, "自动发现：pending_device 表新增 fingerprint 列（扫描时读取，用于提示是已有设备换了 IP）", None),
+    (7, "去重账本：done_mark 表（跨设备幂等的「已做过」标记，唯一索引 scope_key）", None),
+    (8, "账号台账：device_account 表（设备号/手机号/账号名称/抖音号/注册时间/卡在机内/可发视频/简介/备注）", None),
+    (9, "视频发布计划：video_plan 表（账号×发布日期×编号 → 素材 + 标题 + 发布状态 + 分享链接）", None),
+    (10, "视频发布计划：video_plan 新增 push_verify（推送后相册校验：ok/no_index/nofile）"
+         "与 push_remote（手机上的绝对路径，删它/排查用）", None),
+    (11, "视频发布计划：video_plan 新增 body（正文）—— 标题 txt 一行里用 || 分隔「标题 || 正文」", None),
+    (12, "发布计划按名字发：计划行以 nickname 为识别键，新增 posted_serial/posted_device_name"
+         "（**实际是哪台设备发的**）；账号台账（device_account）停用但表与数据保留", None),
+    (13, "按名字找设备：device 表新增 cur_account_name/cur_name_at"
+         "（上次探测到的抖音当前账号名字，仅供人工入口做设备建议）", None),
 ]

+# 当前 schema 版本（备份/恢复用它判断新旧，也写进 app_meta.schema_version）
+CURRENT_SCHEMA_VERSION = max(v for v, _, _ in SCHEMA_MIGRATIONS)
+
+# 唯一索引（语义 = 部分索引：空值不参与唯一约束，兼容历史未命名/未采指纹的老数据）
+# 名称唯一 = 设备的人可读标识；指纹唯一 = 一台物理设备在池中只能有一条记录
+#
+# 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 "
+                              "ON device(fingerprint) WHERE fingerprint IS NOT NULL "
+                              "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"),
+)
+
+# 普通索引：模型里已经声明了（`__table_args__`），但那对**已有表**不生效 ——
+# `create_all` 只建缺的表，不补已有表的新索引。这里按名字查了再建，老库升级也能有。
+_PLAIN_INDEXES = (
+    ("ix_video_plan_name_date", "video_plan", "nickname, release_date"),
+)
+

 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_plain_indexes()
        _ensure_default_admin()
        _migrate_old_json()


-def _migrate_schema():
-    """按 SCHEMA_MIGRATIONS 顺序执行版本化迁移，记录当前 schema_version。
+def _sync_columns():
+    """按模型定义补齐"实表缺的列"（幂等）。

-    create_all 只负责首次建表；结构变更必须走迁移，避免改了模型后老库对不上。
+    取代原来靠 "duplicate column name" 报错文本判断的老写法：那是 SQLite 时代的
+    容错路径，换 MySQL 后报错文本/错误码都不同，靠字符串匹配太脆。
+    现在直接读数据库元数据（sqlalchemy.inspect）比对，缺什么补什么。
    """
+    from sqlalchemy import inspect
+    from sqlalchemy.schema import CreateColumn
+
    try:
-        db.session.execute(text(
-            "CREATE TABLE IF NOT EXISTS app_meta (key TEXT PRIMARY KEY, value TEXT)"))
-        db.session.commit()
-        cur = db.session.execute(
-            text("SELECT value FROM app_meta WHERE key='schema_version'")).scalar()
-        current = int(cur) if cur else 0
-        for version, desc, sql in SCHEMA_MIGRATIONS:
+        insp = inspect(db.engine)
+        existing = set(insp.get_table_names())
+    except Exception as e:
+        _log.error(f"读取表结构失败，跳过补列: {e}")
+        return
+
+    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:
-                db.session.execute(text(sql))
-            db.session.execute(
-                text("INSERT OR REPLACE INTO app_meta(key,value) VALUES('schema_version',:v)"),
-                {"v": str(version)})
-            db.session.commit()
-            _log.info(f"schema 迁移到版本 {version}: {desc}")
+            if backfill_sql:
+                try:
+                    db.session.execute(text(backfill_sql))
+                    db.session.commit()
+                except Exception as e:
+                    db.session.rollback()
+                    _log.error(f"迁移 v{version} 数据回填失败: {e}")
+            _log.info(f"schema 迁移到版本 {version}（结构由模型自动同步）: {desc}")
+        if current < CURRENT_SCHEMA_VERSION:
+            db_config.meta_set("schema_version", str(CURRENT_SCHEMA_VERSION))
    except Exception as e:
        _log.error(f"schema 迁移失败（不阻塞启动）: {e}")


+def _ensure_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()
+        except Exception as e:
+            db.session.rollback()
+            _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_plain_indexes():
+    """补建模型里声明、但已有表上还没有的普通索引（幂等）。
+
+    SQLite / MySQL 都能跑同一条 `CREATE INDEX`（MySQL 5.7 没有 `IF NOT EXISTS`，
+    所以先 inspect 查名字再建，不靠方言特有能力）。
+    """
+    from sqlalchemy import inspect
+    for name, table, cols in _PLAIN_INDEXES:
+        try:
+            have = {i["name"] for i in inspect(db.engine).get_indexes(table)}
+            if name in have:
+                continue
+            db.session.execute(text("CREATE INDEX {} ON {}({})".format(name, table, cols)))
+            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():
@@ -283,7 +886,7 @@ def _migrate_old_json():
                    del actions["comment"]
                    _log.info(f"迁移任务 {j.get('name')}: 已剔除废弃的 comment 配置")
                row = TaskJob(id=j["id"], name=j["name"],
-                              task_type=j.get("task_type", "douyin_nurture"),
+                              task_type=j.get("task_type", "generic_steps"),
                              enabled=j.get("enabled", True))
                row.set_target(j.get("target", {"mode": "all"}))
                row.set_params(params)
@@ -0,0 +1,254 @@
+"""通知事件目录（**唯一真相**）。
+
+约定：
+- **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("task.page.mismatch", "页面不对（校验没过）", "业务",
+       ["serial", "device_name", "model", "want", "msg"],
+       "「校验页面」步骤没等到该出现的特征元素 —— **说明上一步没生效**（没进到相册页/剪辑页等）。"
+       "默认会**跳过本轮剩余步骤**（这一条不发、换下一个号），避免在错的页面上继续盲点",
+       agg_window=0, agg_key=_BY_SERIAL, recommend=True),
+    _e("task.account.switch_failed", "切号失败", "业务",
+       ["serial", "device_name", "model", "want", "got", "attempts", "msg"],
+       "想切到某个账号但没切成功（列表里找不到这个名字，或切完读回来的还是别人）——"
+       "**本次不会发这个号的内容**。请人工到设备上确认这个号还在不在抖音的账号列表里",
+       agg_window=0, agg_key=_BY_SERIAL, recommend=True),
+    _e("task.account.need_login", "需要登录/验证码", "业务",
+       ["serial", "device_name", "model", "want", "msg"],
+       "抖音停在登录页或要验证码 —— **需要人工登录**（平台绝不代替登录/过滑块），"
+       "本设备已停止本轮任务", agg_window=0, agg_key=_BY_SERIAL, recommend=True),
+    _e("task.video.published", "视频已发布", "业务",
+       ["serial", "device_name", "model", "phone", "nickname", "release_date", "seq",
+        "title", "share_url"],
+       "「发布视频」步骤把某个账号的视频发出去了（share_url 是作品分享链接，"
+       "没抓到链接时为空——界面上会标「缺链接」）", agg_window=0, recommend=True),
+    _e("task.video.failed", "视频发布失败/结果未知", "业务",
+       ["serial", "device_name", "model", "phone", "nickname", "release_date", "seq",
+        "title", "msg"],
+       "「发布视频」步骤失败：推文件阶段失败=可重试；抖音那一步失败=**可能已经发出去了**，"
+       "要到计划页看状态并人工确认（平台不会自动重发）", agg_window=0,
+       agg_key=_BY_SERIAL, 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("device.battery.low", "设备电量低", "设备",
+       ["serial", "device_name", "model", "battery", "charging", "threshold"],
+       "设备电量掉到阈值以下（默认 20%，可在「工具 → 设备发现 → 电量监控」改）。"
+       "充电中的设备不报——插着充电器说明正在补电；"
+       "「插着却没充电」（劣质线/温控/满电停充）仍会报，那正是最该知道的情况",
+       agg_window=0, agg_key=_BY_SERIAL, recommend=True),
+    _e("device.battery.recovered", "设备电量已恢复", "设备",
+       ["serial", "device_name", "model", "battery", "charging", "threshold"],
+       "低电量设备重新充上电，或电量回升到阈值以上（含恢复迟滞）", agg_window=0,
+       agg_key=_BY_SERIAL),
+
+    # ---------------- 应用安装 ----------------
+    _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
@@ -0,0 +1,90 @@
+"""屏幕 OCR 识别（RapidOCR，ONNX 推理，跨平台：Windows/Linux/macOS）。
+
+用于"条件判断"步骤的 ocr 选择器：截屏 → 识别文字 → 按关键词匹配 → 可点击。
+UI 树里找不到的文字（图片、画布、WebView 渲染的文字）也能识别。
+
+依赖 rapidocr_onnxruntime（中英文模型随包内置，无需下载/联网）：
+  pip install rapidocr_onnxruntime
+服务器（无显示器）环境建议把 opencv-python 换成 opencv-python-headless。
+
+坐标约定：返回 box 为像素坐标（原点左上），与 u2 的 d.click 一致。
+"""
+import threading
+
+import numpy as np
+
+from core.logger import get_logger
+
+_log = get_logger("core.ocr")
+
+_engine = None
+_engine_lock = threading.Lock()
+
+
+def _get_engine():
+    global _engine
+    with _engine_lock:
+        if _engine is None:
+            from rapidocr_onnxruntime import RapidOCR
+            _log.info("初始化 RapidOCR 引擎（首次约 1-2 秒加载模型）")
+            _engine = RapidOCR()
+    return _engine
+
+
+def available():
+    """OCR 是否可用。返回 (ok, hint)。"""
+    try:
+        _get_engine()
+        return True, ""
+    except Exception as e:
+        return False, f"OCR 不可用（需 pip install rapidocr_onnxruntime）: {e}"
+
+
+def recognize(image):
+    """识别 PIL Image 上的文字。
+
+    返回 [{text, score, box}]，box=[x1,y1,x2,y2] 像素坐标（原点左上，与 u2 一致）。
+    """
+    engine = _get_engine()
+    # PIL(RGB) → ndarray(BGR)，与 OpenCV 约定一致
+    arr = np.array(image.convert("RGB"))[:, :, ::-1]
+    results = []
+    try:
+        # 引擎实例并发调用加锁保护（识别本身约 0.2-0.5s，锁开销可忽略）
+        with _engine_lock:
+            result, _ = engine(arr)
+    except Exception as e:
+        _log.warning(f"OCR 识别异常: {e}")
+        return results
+    for item in result or []:
+        box4, text, score = item
+        xs = [p[0] for p in box4]
+        ys = [p[1] for p in box4]
+        results.append({"text": text, "score": float(score),
+                        "box": [round(min(xs)), round(min(ys)),
+                                round(max(xs)), round(max(ys))]})
+    return results
+
+
+def find_on_screen(image, keyword):
+    """在截图上查找包含 keyword 的文字。
+
+    返回 (found, center_xy, matched_text)；center_xy 为**关键词**中心像素坐标
+    （可点击），未命中返回 (False, None, "")。
+
+    OCR 一行常含多段文字（如 "医值得推荐#苏州济世璞真…展开"），若直接点整块
+    中心会偏离关键词很远。命中块文本较长时，按关键词在文本中的位置比例估算 x
+    （块内文字近似等宽），y 取块中心——中文场景估算偏差小，点击能落准。
+    """
+    for r in recognize(image):
+        text = r["text"]
+        if keyword in text:
+            b = r["box"]
+            if len(text) <= 12:   # 短文本：整块中心即关键词中心
+                return True, ((b[0] + b[2]) // 2, (b[1] + b[3]) // 2), text
+            idx = text.find(keyword)
+            ratio = (idx + len(keyword) / 2) / len(text)
+            cx = b[0] + int((b[2] - b[0]) * ratio)
+            cy = (b[1] + b[3]) // 2
+            return True, (cx, cy), text
+    return False, None, ""
@@ -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)
@@ -0,0 +1,100 @@
+"""SSH 远程命令执行统一封装（STF 重启 / STF 设备管理共用）。
+
+认证方式二选一：
+  1. `.env` 配置 STF_SSH_PASSWORD → 密码认证（paramiko 实现，跨平台，
+     无需 sshpass/ssh 等外部工具，Windows/Linux/macOS 通吃）
+  2. 未配置 → 退回系统 `ssh` 命令 + BatchMode=yes（免密密钥，与旧行为一致）
+
+用法：
+  code, out, err = ssh_client.run("docker ps")     # 返回 (退出码, stdout, stderr)
+  失败抛 SSHError（连接失败/超时），由调用方转成友好错误返回。
+"""
+import re
+import socket
+import subprocess
+
+import paramiko
+
+from config import STF_SSH_TARGET, STF_SSH_PASSWORD
+from core.logger import get_logger
+
+_log = get_logger("core.ssh")
+
+
+class SSHError(Exception):
+    """SSH 执行错误（连接失败/超时等）。"""
+
+
+def _parse_target(target):
+    """解析 STF_SSH_TARGET（user@host[:port] 或 host）→ (user, host, port)。"""
+    target = (target or "").strip()
+    user, host, port = "root", target, 22
+    m = re.match(r"^([^@]+)@(.+)$", target)
+    if m:
+        user, host = m.group(1), m.group(2)
+    if ":" in host:
+        host, p = host.rsplit(":", 1)
+        try:
+            port = int(p)
+        except ValueError:
+            pass
+    return user, host, port
+
+
+def uses_password():
+    """当前是否走密码认证。"""
+    return bool(STF_SSH_PASSWORD)
+
+
+def run(cmd, timeout=25):
+    """在部署机上执行一条命令。返回 (code, stdout, stderr)。"""
+    if uses_password():
+        return _run_paramiko(cmd, timeout)
+    return _run_system_ssh(cmd, timeout)
+
+
+def _run_system_ssh(cmd, timeout):
+    """免密密钥路径：系统 ssh + BatchMode=yes（不弹密码提示）。"""
+    ssh = ["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=5",
+           "-o", "StrictHostKeyChecking=no", STF_SSH_TARGET]
+    try:
+        r = subprocess.run(ssh + [cmd], capture_output=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        raise SSHError(f"SSH 执行超时: {cmd[:80]}")
+    except FileNotFoundError:
+        raise SSHError("本机未安装 ssh，无法远程执行")
+    except Exception as e:
+        raise SSHError(f"SSH 连接失败: {e}")
+    return r.returncode, (r.stdout or b"").decode("utf-8", errors="replace"), \
+        (r.stderr or b"").decode("utf-8", errors="replace")
+
+
+def _run_paramiko(cmd, timeout):
+    """密码路径：paramiko SSHClient，**纯密码认证**。
+
+    look_for_keys=False + allow_agent=False：不尝试本地密钥、不询问 SSH agent
+    （如 Bitwarden），否则 agent 会弹授权框/用密钥绕过密码。
+    """
+    user, host, port = _parse_target(STF_SSH_TARGET)
+    client = paramiko.SSHClient()
+    client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+    try:
+        client.connect(host, port=port, username=user, password=STF_SSH_PASSWORD,
+                       timeout=8, banner_timeout=8, auth_timeout=8,
+                       look_for_keys=False, allow_agent=False)
+        try:
+            stdin, stdout, stderr = client.exec_command(cmd, timeout=timeout)
+            out = stdout.read().decode("utf-8", errors="replace")
+            err = stderr.read().decode("utf-8", errors="replace")
+            code = stdout.channel.recv_exit_status()
+            return code, out, err
+        finally:
+            client.close()
+    except paramiko.AuthenticationException:
+        raise SSHError(f"SSH 密码认证失败（请检查 .env 的 STF_SSH_PASSWORD）")
+    except socket.timeout:
+        raise SSHError(f"SSH 执行超时（{timeout}s 内未完成，命令可能耗时较长）")
+    except paramiko.SSHException as e:
+        raise SSHError(f"SSH 连接失败: {e}")
+    except Exception as e:
+        raise SSHError(f"SSH 连接失败: {e}")
@@ -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}
@@ -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
@@ -1,228 +0,0 @@
-"""OpenSTF REST API 客户端封装。
-
-负责：设备列表查询、占用、远程 ADB 隧道建立、释放。
-不负责实际 UI 操作（那是 DeviceWorker 的事）。
-
-健壮性设计：
-  - 所有请求带 timeout，避免 STF 网关 504 时长时间卡死
-  - remoteConnect 带重试，STF provider 偶尔慢启动
-  - 友好错误分类：设备离线 / 网络不通 / STF 内部错误，便于上层决策
-  - 占用冲突自动重试（STF 偶发 400 "device already in use"）
-"""
-import time
-
-import requests
-
-from config import STF_URL, STF_TOKEN
-from core.logger import get_logger
-
-_log = get_logger("core.stf")
-
-# 请求超时（秒）。connect 超时 + read 超时
-_TIMEOUT = (5, 15)
-# remoteConnect 重试次数（STF provider 慢启动时需要重试）
-_RC_RETRIES = 3
-# remoteConnect 重试间隔
-_RC_DELAY = 2
-
-
-class STFError(Exception):
-    """STF 相关错误基类。"""
-
-    def __init__(self, message, code=""):
-        super().__init__(message)
-        self.code = code  # 错误码：offline / network / conflict / server / unknown
-
-
-class DeviceOfflineError(STFError):
-    """设备离线/不可用。"""
-
-
-class STFNetworkError(STFError):
-    """STF 服务不可达。"""
-
-
-class DeviceConflictError(STFError):
-    """设备已被占用。"""
-
-
-def _headers():
-    return {"Authorization": f"Bearer {STF_TOKEN}"}
-
-
-class STFClient:
-    """OpenSTF REST API 封装。"""
-
-    def __init__(self, base_url=STF_URL, token=STF_TOKEN):
-        self.base_url = base_url
-        self.headers = _headers()
-
-    # ================== 设备查询 ==================
-    def list_all_devices(self):
-        """返回 STF 上所有设备（含状态）。"""
-        try:
-            resp = requests.get(f"{self.base_url}/api/v1/devices",
-                                headers=self.headers, timeout=_TIMEOUT)
-            resp.raise_for_status()
-            return resp.json().get("devices", [])
-        except requests.exceptions.ConnectionError as e:
-            raise STFNetworkError(f"STF 服务不可达: {e}", "network") from e
-        except requests.exceptions.Timeout as e:
-            raise STFNetworkError(f"STF 请求超时: {e}", "network") from e
-        except requests.exceptions.RequestException as e:
-            _log.error(f"获取设备列表失败: {e}")
-            raise STFError(f"获取设备列表失败: {e}", "server") from e
-
-    def list_free_devices(self):
-        """返回可占用的空闲设备。"""
-        return [d for d in self.list_all_devices()
-                if d.get("present") and d.get("ready")
-                and not d.get("using") and d.get("owner") is None]
-
-    def list_my_devices(self):
-        """返回当前账户已占用的设备。"""
-        try:
-            resp = requests.get(f"{self.base_url}/api/v1/user/devices",
-                                headers=self.headers, timeout=_TIMEOUT)
-            resp.raise_for_status()
-            return resp.json().get("devices", [])
-        except requests.exceptions.RequestException as e:
-            _log.error(f"获取已占用设备失败: {e}")
-            return []
-
-    # ================== 占用/释放 ==================
-    def occupy(self, serial, retries=2):
-        """占用设备。返回 (ok, msg)。
-
-        冲突（已被占用）时自动重试，偶发 400 "already in use" 可能是脏状态。
-        """
-        for attempt in range(1, retries + 1):
-            try:
-                r = requests.post(f"{self.base_url}/api/v1/user/devices/{serial}",
-                                  headers=self.headers, timeout=_TIMEOUT)
-                if r.status_code in (200, 201):
-                    return True, r.text[:200]
-                if r.status_code == 400 and "already" in r.text.lower():
-                    # 已被占用（可能是自己之前占用没释放干净），尝试先释放再占
-                    _log.warning(f"{serial} 占用冲突，尝试清理后重试 ({attempt}/{retries})")
-                    try:
-                        requests.delete(f"{self.base_url}/api/v1/user/devices/{serial}",
-                                        headers=self.headers, timeout=_TIMEOUT)
-                    except Exception:
-                        pass
-                    time.sleep(1)
-                    continue
-                return False, f"HTTP {r.status_code}: {r.text[:200]}"
-            except requests.exceptions.RequestException as e:
-                _log.warning(f"{serial} 占用请求异常 ({attempt}/{retries}): {e}")
-                if attempt < retries:
-                    time.sleep(1)
-                return False, str(e)
-        return False, "占用冲突重试耗尽"
-
-    def release(self, serial, retries=3):
-        """释放设备占用。返回 (ok, msg)。
-
-        STF 释放可能因设备响应超时返回 504（如设备过载/卡死），此时设备实际未释放。
-        必须检查响应状态并重试，不能静默吞掉——否则占用会一直悬着。
-        """
-        self.remote_disconnect(serial)
-        last_status = None
-        last_body = ""
-        for attempt in range(1, retries + 1):
-            try:
-                r = requests.delete(f"{self.base_url}/api/v1/user/devices/{serial}",
-                                    headers=self.headers, timeout=_TIMEOUT)
-                if r.status_code in (200, 201, 202, 204):
-                    return True, "released"
-                last_status = r.status_code
-                last_body = r.text[:150]
-                _log.warning(f"释放 {serial} 失败 HTTP {r.status_code}: {last_body} ({attempt}/{retries})")
-            except requests.exceptions.RequestException as e:
-                _log.warning(f"释放 {serial} 请求异常 ({attempt}/{retries}): {e}")
-                last_status = -1
-                last_body = str(e)
-            if attempt < retries:
-                time.sleep(2)
-        return False, f"STF 释放失败(HTTP {last_status}): {last_body}"
-
-    def release_all_mine(self):
-        """释放当前账户占用的所有设备（清理用）。返回 (released, failed)。"""
-        released, failed = [], []
-        for d in self.list_my_devices():
-            serial = d["serial"]
-            ok, msg = self.release(serial)
-            if ok:
-                released.append(serial)
-                _log.info(f"已释放 {serial}")
-            else:
-                failed.append(serial)
-                _log.error(f"释放 {serial} 失败: {msg}")
-        return released, failed
-
-    # ================== 远程 ADB 隧道 ==================
-    def remote_connect(self, serial):
-        """建立远程 ADB 隧道，返回 remoteConnectUrl。
-
-        STF provider 慢启动或设备掉线时会 504，这里带重试。
-        设备真离线时快速失败，不长时间卡住 worker。
-        """
-        last_err = None
-        for attempt in range(1, _RC_RETRIES + 1):
-            try:
-                conn = requests.post(
-                    f"{self.base_url}/api/v1/user/devices/{serial}/remoteConnect",
-                    headers=self.headers, timeout=_TIMEOUT,
-                )
-                # 504 = STF 网关等 provider 响应超时，通常是设备掉线或 provider 卡死
-                if conn.status_code == 504:
-                    last_err = f"STF 网关超时(504)，设备可能掉线"
-                    _log.warning(f"{serial} remoteConnect 504 ({attempt}/{_RC_RETRIES})")
-                    if attempt < _RC_RETRIES:
-                        time.sleep(_RC_DELAY)
-                        continue
-                    raise DeviceOfflineError(
-                        f"{serial} remoteConnect 超时，设备可能掉线或 provider 卡死",
-                        "offline",
-                    )
-                conn.raise_for_status()
-                data = conn.json()
-                if not data.get("success"):
-                    raise STFError(f"远程连接失败: {data.get('description')}", "server")
-                url = (data.get("remoteConnectUrl") or data.get("remoteAdbUrl")
-                       or data.get("remote_adb_url") or data.get("adbUrl")
-                       or data.get("url"))
-                if not url:
-                    raise STFError("STF 返回成功但无 remoteConnectUrl", "server")
-                return url
-            except DeviceOfflineError:
-                raise
-            except requests.exceptions.ConnectionError as e:
-                last_err = str(e)
-                _log.warning(f"{serial} remoteConnect 网络异常 ({attempt}/{_RC_RETRIES}): {e}")
-                if attempt < _RC_RETRIES:
-                    time.sleep(_RC_DELAY)
-            except requests.exceptions.Timeout as e:
-                last_err = str(e)
-                _log.warning(f"{serial} remoteConnect 超时 ({attempt}/{_RC_RETRIES}): {e}")
-                if attempt < _RC_RETRIES:
-                    time.sleep(_RC_DELAY)
-            except requests.exceptions.RequestException as e:
-                last_err = str(e)
-                _log.error(f"{serial} remoteConnect 请求异常: {e}")
-                raise STFError(f"远程连接请求失败: {e}", "server") from e
-        # 重试耗尽
-        raise DeviceOfflineError(
-            f"{serial} remoteConnect 重试 {_RC_RETRIES} 次失败: {last_err}",
-            "offline",
-        )
-
-    def remote_disconnect(self, serial):
-        """断开远程 ADB 隧道。"""
-        try:
-            requests.post(
-                f"{self.base_url}/api/v1/user/devices/{serial}/remoteDisconnect",
-                headers=self.headers, timeout=_TIMEOUT,
-            )
-        except requests.exceptions.RequestException:
-            pass  # 断开失败不影响主流程
@@ -0,0 +1,661 @@
+"""系统数据备份导出/导入（数据库 + APK 文件）。
+
+**归档格式：zip（`users.db` + `manifest.json` + 可选 `apks/*.apk`）。**
+SQLite 在这里的角色是**交换格式**，不是运行时数据库——这在迁到 MySQL 之后依然成立，
+带来三个好处：
+  1. 前端三个接口的请求/响应结构一行都不用改
+  2. 校验逻辑（完整性 / 必需表 / schema 版本 / 未登记表反向自检）可以整体沿用
+  3. 2026-09-13 之前导出的老备份继续可导入；也不依赖任何外部二进制
+     （`sqlite3` 是 Python 标准库，python:slim 容器里现成）
+
+导出：把**当前库**（MySQL 或 SQLite）整库读出来，写进一个临时 SQLite 文件 → zip。
+      MySQL 下把这条连接提到 REPEATABLE READ，保证所有表读的是同一时刻。
+导入：上传(zip/db) → 暂存校验预览 → 应用（先自动导出一份当前库到
+      BACKUP_DIR/pre_restore_*.zip 作安全网，再把暂存归档移到 RESTORE_PENDING_DIR）
+      → 下次启动 consume_pending_restore() 在**单个事务内**整库替换生效。
+
+为什么仍然要重启生效：TaskManager / device_pool 把任务与设备**缓存在内存**里，
+整库替换后内存副本全部失效。（SQLite 时代还有"Windows 无法替换被持有的文件"这层，
+改用 MySQL 之后只剩内存态这一层。）
+
+安全红线：全程只读现有库 / 只写自己目录下的文件；替换数据用单事务，失败回滚，
+绝不留下半新半旧的库；绝不 kill-server、绝不 disconnect（与全项目一致）。
+"""
+import json
+import os
+import shutil
+import sqlite3
+import time
+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 CURRENT_SCHEMA_VERSION, db
+from core import notifier
+
+_log = get_logger("core.backup")
+
+DB_FILE = os.path.join(DATA_DIR, "users.db")
+
+# 判定「本平台备份库」的必需表（缺任何一张即拒绝导入）
+REQUIRED_TABLES = ("app_meta", "user", "task_job", "device_group")
+# 备份覆盖清单：**由模型元数据派生**，不再手工维护。
+# 这样「新增持久化表必须登记进备份清单」这条红线从"靠人记"变成结构上不可能漏
+# （2026-09-10 动作库 agent_action 就漏过：数据其实在快照里，只是清单没列，
+#   导出预览里看不到那一行 → 被误判成"没备份"）。
+SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
+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": "动作库", "device_install_log": "设备端安装记录",
+    "task_step_log": "任务步骤明细",
+    "done_mark": "去重记录（已做过）",
+    "device_account": "账号台账",
+    "video_plan": "视频发布计划",
+}
+_STAGE_TTL = 1800  # 导入暂存有效期（秒）
+
+
+class BackupError(Exception):
+    """备份/导入相关可预期错误（msg 直接给前端展示）。"""
+
+
+# ================== 通用工具 ==================
+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。"""
+    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):
+    con = sqlite3.connect(_readonly_uri(path), uri=True)
+    con.text_factory = str  # 与平台一致按 UTF-8 读（表内文本均为 UTF-8）
+    return con
+
+
+def remove_quiet(path):
+    """尽力删除文件/目录（发送完成清理等场景，忽略不存在）。"""
+    try:
+        if os.path.isdir(path):
+            shutil.rmtree(path, ignore_errors=True)
+        elif os.path.exists(path):
+            os.remove(path)
+    except OSError:
+        pass
+
+
+def _ensure_dir(path):
+    os.makedirs(path, exist_ok=True)
+
+
+def _list_tables(con):
+    rows = con.execute(
+        "SELECT name FROM sqlite_master WHERE type='table'").fetchall()
+    return {r[0] for r in rows}
+
+
+def _read_schema_version(con):
+    try:
+        row = con.execute(
+            "SELECT value FROM app_meta WHERE key='schema_version'").fetchone()
+        return int(row[0]) if row and row[0] else 0
+    except Exception:
+        return 0
+
+
+def _table_rows(con, table):
+    try:
+        return con.execute('SELECT COUNT(*) FROM "%s"' % table).fetchone()[0]
+    except Exception:
+        return None
+
+
+def _summary_info(con):
+    """表行数摘要（只列出存在的表）。"""
+    rows = []
+    for t in SUMMARY_TABLES:
+        n = _table_rows(con, t)
+        if n is not None:
+            rows.append({"table": t, "label": TABLE_LABELS.get(t, t), "rows": n})
+    return rows
+
+
+def _video_summary():
+    """视频素材目录的概况（写进 manifest；**不进备份包**，但要交代清楚）。
+
+    · `missing`：`video_plan` 引用了、但文件已经不在了的清单 —— 反向自检
+      （与 `coverage_missing` 同一个思路：别让"看起来有其实没有"悄悄发生）
+    """
+    try:
+        from config import VIDEO_DIR
+    except Exception:
+        return {"included": False, "error": "config 读取失败"}
+    count = 0
+    size = 0
+    try:
+        for root, _dirs, files in os.walk(VIDEO_DIR):
+            for fn in files:
+                if fn.startswith(".tmp_"):
+                    continue
+                try:
+                    size += os.path.getsize(os.path.join(root, fn))
+                    count += 1
+                except OSError:
+                    pass
+    except Exception:
+        pass
+    missing = []
+    try:
+        from core.models import VideoPlan
+        with db.app_context():
+            for r in VideoPlan.query.filter(VideoPlan.video_file != "").all():
+                p = os.path.join(VIDEO_DIR, r.video_file)
+                if not os.path.exists(p):
+                    missing.append({"id": r.id, "file": r.video_file})
+    except Exception:
+        pass
+    return {"included": False, "dir": "data/videos", "count": count, "bytes": size,
+            "note": "视频素材不进备份包（体积）。恢复后需重新上传；"
+                    "计划、发布状态与分享链接在 video_plan 表里，已备份。",
+            "missing": missing[:200], "missing_count": len(missing)}
+
+
+def _prune_old_exports(max_age=3600):
+    """清理过期的导出临时 zip（下载完成后的 call_on_close 在 Windows 上可能
+    因文件锁删不掉，这里按时间兜底清理；保留近 1 小时的便于失败重试）。"""
+    now = time.time()
+    if not os.path.isdir(BACKUP_DIR):
+        return
+    for n in os.listdir(BACKUP_DIR):
+        if n.startswith("export_") and n.endswith(".zip"):
+            p = os.path.join(BACKUP_DIR, n)
+            try:
+                if now - os.path.getmtime(p) > max_age:
+                    os.remove(p)
+            except OSError:
+                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"
+    dump_to_sqlite(snap)
+
+    apk_meta = []
+    if include_apk and os.path.isdir(APK_DIR):
+        for fname in sorted(os.listdir(APK_DIR)):
+            if fname.lower().endswith(".apk"):
+                fp = os.path.join(APK_DIR, fname)
+                try:
+                    apk_meta.append({"name": fname, "size": os.path.getsize(fp)})
+                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": 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,
+            # 视频发布计划的素材**不进备份包**（几十 GB 会把备份能力搞坏），
+            # 但必须在 manifest 里交代清楚 —— 否则就是"以为备份了其实没有"（红线）。
+            "videos": _video_summary(),
+        }
+        # 覆盖自检：登记在册的业务表若在快照里缺失（新增功能忘了登记 / 建表失败），
+        # 显式告警并写进 manifest——避免"以为备份了其实没有"（备份覆盖红线）。
+        _present = {t["table"] for t in manifest["tables"]}
+        _missing = [t for t in SUMMARY_TABLES if t not in _present]
+        if _missing:
+            manifest["coverage_missing"] = _missing
+            _log.warning(f"备份覆盖检查：以下登记表未纳入快照，请确认是否应备份: {_missing}")
+    finally:
+        con.close()
+
+    try:
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as z:
+            z.write(snap, arcname="users.db")
+            for a in apk_meta:
+                z.write(os.path.join(APK_DIR, a["name"]), arcname="apks/" + a["name"])
+            z.writestr("manifest.json", json.dumps(
+                manifest, ensure_ascii=False, indent=2))
+    finally:
+        remove_quiet(snap)
+    return zip_path, os.path.basename(zip_path), manifest
+
+
+# ================== 校验 ==================
+def validate_backup(db_file):
+    """校验备份库可读、是本平台库。返回 (ok, info|error_msg)。"""
+    if not os.path.exists(db_file):
+        return False, "缺少数据库文件 users.db"
+    try:
+        con = _connect_readonly(db_file)
+    except sqlite3.Error as e:
+        return False, f"无法打开数据库: {e}"
+    try:
+        integrity = con.execute("PRAGMA integrity_check").fetchone()[0]
+        if integrity != "ok":
+            return False, f"数据库完整性校验失败: {integrity}"
+        tables = _list_tables(con)
+        missing = [t for t in REQUIRED_TABLES if t not in tables]
+        if missing:
+            return False, f"不是本平台备份库（缺少必需表: {', '.join(missing)}）"
+        schema_version = _read_schema_version(con)
+        missing_optional = [t for t in SUMMARY_TABLES
+                            if t not in REQUIRED_TABLES and t not in tables]
+        warnings = []
+        if schema_version < CURRENT_SCHEMA_VERSION:
+            warnings.append(
+                f"备份 schema 较旧（v{schema_version} < 当前 v{CURRENT_SCHEMA_VERSION}），"
+                f"缺失的表/列按当前结构补空，不会报错但那些数据回不来")
+        elif schema_version > CURRENT_SCHEMA_VERSION:
+            warnings.append(
+                f"备份 schema 较新（v{schema_version} > 当前 v{CURRENT_SCHEMA_VERSION}），"
+                f"当前平台版本可能读不了新增列/表，建议先升级再恢复")
+        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/models.py 的模型与 "
+                              "core/system_backup.py 的 TABLE_LABELS")
+        warnings.append("备份为全量数据：含用户口令哈希、AI 配置里的 API Key 等敏感信息，请妥善保管")
+        return True, {
+            "integrity": integrity,
+            "schema_version": schema_version,
+            "current_schema_version": CURRENT_SCHEMA_VERSION,
+            "tables": _summary_info(con),
+            "missing_optional": missing_optional,
+            "extra_tables": extra_tables,
+            "warnings": warnings,
+        }
+    except sqlite3.Error as e:
+        return False, f"读取数据库失败: {e}"
+    finally:
+        con.close()
+
+
+# ================== 导入：暂存 + 预览 ==================
+def _extract_zip(zip_path, staging_dir):
+    """解压备份 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
+    with zipfile.ZipFile(zip_path) as z:
+        for info in z.infolist():
+            if info.is_dir():
+                continue
+            name = info.filename.replace("\\", "/")
+            base = os.path.basename(name)
+            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(
+                        os.path.join(apk_dest, base), "wb") as dst:
+                    shutil.copyfileobj(src, dst)
+    if not got_db:
+        raise BackupError("zip 内未找到 users.db（顶层）")
+    return db_dest
+
+
+def _read_staged_manifest(staging_dir):
+    p = os.path.join(staging_dir, "manifest.json")
+    if not os.path.exists(p):
+        return {}
+    try:
+        with open(p, encoding="utf-8") as f:
+            return json.load(f) or {}
+    except Exception:
+        return {}
+
+
+def stage_upload(file_storage):
+    """保存上传备份并校验，返回 (token, info)。失败抛 BackupError。"""
+    _prune_stale_staging()
+    orig_name = file_storage.filename or "backup"
+    token = uuid.uuid4().hex[:12]
+    staging_dir = os.path.join(RESTORE_STAGING_DIR, token)
+    _ensure_dir(staging_dir)
+    low = (orig_name or "").lower()
+    try:
+        raw_path = os.path.join(staging_dir, "upload" + ("." + low.rsplit(".", 1)[1] if "." in low else ""))
+        file_storage.save(raw_path)
+        if low.endswith(".zip"):
+            _extract_zip(raw_path, staging_dir)
+            db_file = os.path.join(staging_dir, "users.db")
+            remove_quiet(raw_path)
+        elif low.endswith(".db"):
+            db_file = os.path.join(staging_dir, "users.db")
+            os.replace(raw_path, db_file)
+        else:
+            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)
+        raise
+    except Exception as e:
+        remove_quiet(staging_dir)
+        raise BackupError(f"暂存上传文件失败: {e}")
+
+
+# ================== 导入：应用（落待生效任务） ==================
+def apply_restore(token, force_env_mismatch=False):
+    """校验 token → 自动备份当前库（zip 安全网）→ 把暂存归档移到 restore_pending。
+
+    返回 dict {ok, backup_name, message}；失败抛 BackupError。token 形如 12 位 hex。
+    """
+    if not token or len(token) != 12 or not all(c in "0123456789abcdef" for c in token):
+        raise BackupError("无效的导入标识")
+    staging_dir = os.path.join(RESTORE_STAGING_DIR, token)
+    db_file = os.path.join(staging_dir, "users.db")
+    if not os.path.exists(db_file):
+        raise BackupError("导入会话已失效，请重新上传预览")
+    ok, info = validate_backup(db_file)
+    if not ok:
+        raise BackupError(info)
+
+    # 跨环境硬停：默认不许把 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)
+    try:
+        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) 落待生效恢复任务（旧未消费任务被覆盖——上一份已无意义）
+    if os.path.isdir(RESTORE_PENDING_DIR):
+        remove_quiet(RESTORE_PENDING_DIR)
+    _ensure_dir(RESTORE_PENDING_DIR)
+    os.replace(db_file, os.path.join(RESTORE_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(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}")
+    return {
+        "ok": True,
+        "backup_name": backup_name,
+        "message": "恢复任务已生成：当前库已自动备份，重启 web_server 后即应用导入的数据",
+    }
+
+
+# ================== 启动消费（init_db 之后、TaskManager 之前调用）==================
+def _pending_db_path():
+    """待生效恢复的归档路径（兼容旧版扁平布局）。"""
+    p = os.path.join(RESTORE_PENDING_DIR, "users.db")
+    return p if os.path.exists(p) else None
+
+
+def consume_pending_restore():
+    """把 restore_pending/users.db 的内容在**单个事务内**整库替换进来。
+
+    与 SQLite 时代的"换文件"不同：现在是 DELETE 全表 + 分块 INSERT，全程一个事务——
+    任何一步失败就 rollback，当前数据保持原样（比换文件更安全）。
+
+    必须在 init_db() 之后调用（表已建好、app context 可用）；失败不阻塞启动：
+    坏归档挪到 BACKUP_DIR/restore_failed_*/ 并继续用当前数据。
+    返回是否真的应用了恢复。
+    """
+    pending_db = _pending_db_path()
+    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)
+        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
+
+    try:
+        applied = _apply_archive_to_db(pending_db)
+    except Exception as e:
+        _log.error(f"应用备份恢复失败，已回滚（当前数据未改动）: {e}，"
+                   f"归档保留在 {RESTORE_PENDING_DIR} 供排查")
+        return False
+
+    # 合并 apks（覆盖同名）
+    apk_src = os.path.join(RESTORE_PENDING_DIR, "apks")
+    if os.path.isdir(apk_src):
+        _ensure_dir(APK_DIR)
+        for fname in os.listdir(apk_src):
+            src = os.path.join(apk_src, fname)
+            dst = os.path.join(APK_DIR, fname)
+            if os.path.exists(dst):
+                os.remove(dst)
+            shutil.move(src, dst)
+    remove_quiet(RESTORE_PENDING_DIR)
+    schema_version = msg.get("schema_version", "?") if isinstance(msg, dict) else "?"
+    _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)
@@ -0,0 +1,213 @@
+"""Tailscale API v2 客户端封装（维护页"Tailscale 管理"用）。
+
+能力：
+  - 列出 tailnet 全部设备（名称/主机名/IP/系统/在线/授权/密钥过期状态）
+  - 更新设备：显示名、主机名、授权开关、密钥不过期（keyExpiryDisabled）
+  - 生成设备接入 auth key（可配置 reusable/ephemeral/preauthorized/有效期）
+  - 删除设备
+
+配置（config.py，支持 .env 注入，**不要提交密钥到 git**）：
+  TAILSCALE_API_KEY — 管理后台 → Settings → API Access Tokens 生成的 key（或 OAuth client 的 client_id:secret）
+  TAILSCALE_TAILNET  — tailnet 名称或 ID（个人账号一般是登录邮箱前缀，如 1422726308）
+
+注意：设备 IP 由 tailnet 自动分配，API 无法修改；列表里的 addresses 只读展示。
+
+参考：https://tailscale.com/api
+"""
+import requests
+
+from config import TAILSCALE_API_KEY, TAILSCALE_TAILNET
+from core.logger import get_logger
+
+_log = get_logger("core.tailscale")
+
+_API_BASE = "https://api.tailscale.com/api/v2"
+_TIMEOUT = (3, 15)
+
+
+class TailscaleError(Exception):
+    """Tailscale API 错误（含 HTTP 状态码）。"""
+
+    def __init__(self, message, code=""):
+        super().__init__(message)
+        self.code = code
+
+
+class TailscaleClient:
+    """Tailscale API v2 客户端。
+
+    认证：Basic Auth，API key 作为用户名、空密码；
+    也可传 OAuth client 的 "client_id:client_secret" 作为 key。
+    """
+
+    def __init__(self, api_key=None, tailnet=None):
+        self.api_key = api_key or TAILSCALE_API_KEY
+        self.tailnet = tailnet or TAILSCALE_TAILNET
+
+    # ================== 配置状态 ==================
+    def is_configured(self):
+        """是否已配置 API key 与 tailnet。"""
+        return bool(self.api_key and self.tailnet)
+
+    def config_hint(self):
+        """未配置时的提示文案。"""
+        missing = []
+        if not self.api_key:
+            missing.append("TAILSCALE_API_KEY（Tailscale 后台 → Settings → API Access Tokens）")
+        if not self.tailnet:
+            missing.append("TAILSCALE_TAILNET（tailnet 名，个人账号一般是邮箱前缀）")
+        return "；".join(missing)
+
+    # ================== 请求基座 ==================
+    def _headers(self):
+        return {"Authorization": f"Basic {self._basic()}"}
+
+    def _basic(self):
+        import base64
+        return base64.b64encode(f"{self.api_key}:".encode()).decode()
+
+    def _get(self, path):
+        if not self.is_configured():
+            raise TailscaleError(f"未配置：{self.config_hint()}", "config")
+        try:
+            r = requests.get(f"{_API_BASE}{path}", headers=self._headers(), timeout=_TIMEOUT)
+        except requests.exceptions.ConnectionError as e:
+            raise TailscaleError(f"Tailscale API 不可达: {e}", "network") from e
+        except requests.exceptions.Timeout as e:
+            raise TailscaleError("Tailscale API 请求超时", "network") from e
+        return self._handle(r)
+
+    def _post(self, path, body):
+        if not self.is_configured():
+            raise TailscaleError(f"未配置：{self.config_hint()}", "config")
+        try:
+            r = requests.post(f"{_API_BASE}{path}", json=body,
+                              headers=self._headers(), timeout=_TIMEOUT)
+        except requests.exceptions.ConnectionError as e:
+            raise TailscaleError(f"Tailscale API 不可达: {e}", "network") from e
+        except requests.exceptions.Timeout as e:
+            raise TailscaleError("Tailscale API 请求超时", "network") from e
+        return self._handle(r)
+
+    def _handle(self, r):
+        try:
+            data = r.json()
+        except Exception:
+            data = {}
+        if r.status_code == 401:
+            raise TailscaleError("API key 无效或已过期（401）", "auth")
+        if r.status_code == 404:
+            raise TailscaleError("tailnet 不存在或无权访问（404），请检查 TAILSCALE_TAILNET", "notfound")
+        if r.status_code >= 400:
+            msg = data.get("message") or str(data)[:200]
+            _log.error(f"Tailscale API 错误 {r.status_code}: {msg}")
+            raise TailscaleError(f"Tailscale API 错误 {r.status_code}: {msg}", "api")
+        return data
+
+    # ================== 设备 ==================
+    def list_devices(self):
+        """列出 tailnet 全部设备。
+
+        返回 [{id, name, hostname, os, addresses[], authorized,
+               key_expiry_disabled, online, last_seen, ...}]（字段已规整）。
+        """
+        data = self._get(f"/tailnet/{self.tailnet}/devices")
+        devices = []
+        for d in data.get("devices", []):
+            online = d.get("online")
+            devices.append({
+                "id": d.get("id", ""),
+                "name": d.get("name", ""),
+                "hostname": d.get("hostname", ""),
+                "os": d.get("os", ""),
+                "addresses": d.get("addresses", []),
+                "authorized": bool(d.get("authorized")),
+                "key_expiry_disabled": bool(d.get("keyExpiryDisabled")),
+                # online 三态：True=在线 / False=离线 / None=最近 12 小时内见过但当前未上报（API 返回 null）。
+                # 注意不能 bool(null)——那会把"最近在线"误显示成"离线"。
+                "online": online if online is not None else None,
+                "last_seen": d.get("lastSeen", ""),
+                "tags": d.get("tags", []),
+            })
+        return devices
+
+    def set_device_name(self, device_id, name):
+        """修改设备显示名（POST /device/{id}/name）。
+
+        注意：POST /device/{id} 是 405，改名/授权/密钥各有专属端点。
+        """
+        if not name or not str(name).strip():
+            raise TailscaleError("名称不能为空")
+        self._post(f"/device/{device_id}/name", {"name": str(name).strip()})
+        return True
+
+    def set_device_authorized(self, device_id, authorized):
+        """授权/取消授权（POST /device/{id}/authorized）。"""
+        self._post(f"/device/{device_id}/authorized", {"authorized": bool(authorized)})
+        return True
+
+    def set_device_key_expiry(self, device_id, disabled):
+        """关闭/恢复设备密钥过期（POST /device/{id}/key）。
+
+        disabled=True 即"密钥不过期"（设备不会被定期踢下线）；
+        恢复过期后按原定过期时间执行，若已过期需重新授权。
+        """
+        self._post(f"/device/{device_id}/key", {"keyExpiryDisabled": bool(disabled)})
+        return True
+
+    def set_device_ip(self, device_id, ipv4):
+        """为设备设置新的 Tailscale IPv4 地址。
+
+        端点 POST /device/{device_id}/ip 实测存在（官方文档未收录，属未公开接口）。
+        注意：
+          - 修改 IP 会断开该设备当前的 tailscale 会话，几秒后以新 IP 重连
+          - 平台设备池（STF serial）用的就是 tailnet IP，改完需同步更新 STF 设备池
+          - IPv6 无公开 API 可改
+        """
+        if not ipv4 or not str(ipv4).strip():
+            raise TailscaleError("IPv4 地址不能为空")
+        self._post(f"/device/{device_id}/ip", {"ipv4": str(ipv4).strip()})
+        return True
+
+    def delete_device(self, device_id):
+        """从 tailnet 移除设备（下次设备上线需重新授权）。"""
+        if not self.is_configured():
+            raise TailscaleError(f"未配置：{self.config_hint()}", "config")
+        try:
+            r = requests.delete(f"{_API_BASE}/device/{device_id}",
+                                headers=self._headers(), timeout=_TIMEOUT)
+        except requests.exceptions.ConnectionError as e:
+            raise TailscaleError(f"Tailscale API 不可达: {e}", "network") from e
+        return self._handle(r)
+
+    # ================== Auth key ==================
+    def create_auth_key(self, description="auto_control", reusable=False,
+                        ephemeral=False, preauthorized=True, expiry_seconds=3600):
+        """生成设备接入 auth key。
+
+        返回 {id, key, expires}。key 只显示这一次，请立即复制保存。
+        preauthorized=True：新设备接入自动授权（免去后台手动点授权）。
+        """
+        body = {
+            "description": description,
+            "expirySeconds": max(60, int(expiry_seconds)),
+            "capabilities": {
+                "devices": {
+                    "create": {
+                        "reusable": bool(reusable),
+                        "ephemeral": bool(ephemeral),
+                        "preauthorized": bool(preauthorized),
+                    }
+                }
+            },
+        }
+        data = self._post(f"/tailnet/{self.tailnet}/keys", body)
+        return {
+            "id": data.get("id", ""),
+            "key": data.get("key", ""),
+            "expires": data.get("expires", ""),
+        }
+
+
+# 模块级单例（与 stf_client 的用法一致）
+tailscale = TailscaleClient()
@@ -0,0 +1,584 @@
+"""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", "expect_el",
+                 "read_text")
+# 需要包名的步骤类型
+NEED_PACKAGE = ("open_app", "stop_app")
+# 需要非空 children 的容器
+NEED_CHILDREN = ("loop", "group", "foreach_account")
+
+# 有副作用的动作关键词：命中的步骤在 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_el 用「去重」条件时不需要 selector_value，
+        # 它的身份元素在 ident_value 里，按自己的规则校验）
+        if stype in NEED_SELECTOR and not (stype == "if_el"
+                                           and params.get("selector_type") == "dedup"):
+            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)
+            # 文本比对（可选）：运算符必须认得，且配了运算符就得有值——
+            # 执行器对认不出的运算符是"一律不命中"，写错了会静默走 else，
+            # 所以在这里拦住，别让 AI 草稿悄悄变成"永远不命中"
+            cmp_op = (params.get("cmp_op") or "").strip()
+            cmp_src = (params.get("cmp_source") or "").strip()
+            if cmp_src not in ("", "manual", "release", "account_target", "var"):
+                errors.append(f"{here}.params.cmp_source: 不支持的候选值来源 {cmp_src!r}"
+                              f"（可用：空/manual/release/account_target/var）")
+            if cmp_src == "var" and not (params.get("cmp_var") or "").strip():
+                errors.append(f"{here}.params.cmp_var: 候选值来源选了「变量」就必须填变量名"
+                              f"（默认 account_name —— 由「读取文字」写入）")
+            if cmp_op:
+                from tasks.generic.task import CMP_OPS
+                if cmp_op not in CMP_OPS:
+                    errors.append(f"{here}.params.cmp_op: 不支持的比对运算符 {cmp_op!r}"
+                                  f"（可用：{'、'.join(CMP_OPS)}）")
+                elif not str(params.get("cmp_value") or "").strip() \
+                        and cmp_src not in ("release", "account_target", "var"):
+                    # 候选值来自发布计划 / 本次要发的名字 / 变量时，允许手填留空（候选不是手填的）；
+                    # 其余情况仍要求填值，否则永远不命中
+                    errors.append(f"{here}.params.cmp_value: 选了文本比对"
+                                  f"（{cmp_op}）就必须填比对的值，否则永远不命中")
+                elif (params.get("selector_type") or "xpath") == "screen":
+                    warnings.append(f"{here}: 屏幕状态没有文本可比，"
+                                    "cmp_op/cmp_value 会被忽略")
+            # 去重条件（见 tasks/generic/task.py 的 selector_type="dedup"）：
+            # 不用 selector_value，身份元素填在 ident_value
+            if (params.get("selector_type") or "") == "dedup":
+                iv = (params.get("ident_value") or "").strip()
+                if not iv:
+                    warnings.append(f"{here}: 去重条件没填身份元素，将按「设备」当身份"
+                                    "（一号一机时没问题；一台机器多个号时要填账号那个元素）")
+                elif (params.get("ident_type") or "text") == "xpath" \
+                        and not (iv.startswith("//") or iv.startswith("(//")):
+                    errors.append(f"{here}.params.ident_value: 身份元素的类型是 xpath，"
+                                  f"取值应以 // 或 (// 开头（当前 {iv[:40]!r}）")
+
+        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":
+            # 文案来自「发布计划」（`text_source` 不是 manual）时 texts/fixed_text **都不参与输入** ——
+            # 别按"手填"的规则要求候选文案（发布任务骨架里那两步就是这么配的：
+            # mode 留默认、内容由计划给，靠 `release_title`/`release_body` 现取）
+            if str(params.get("text_source") or "manual").strip() == "manual":
+                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 and not (sel_type == "dedup" and stype == "if_el"):
+        errors.append(f"{here}.params.selector_type: 不支持 {sel_type!r}"
+                      f"（可用：{'、'.join(stype_ok + ('dedup',))}）")
+        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
@@ -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:
@@ -12,6 +12,7 @@ API 参考（uiautodev 0.14）：
  - GET /api/android/{serial}/dump_hierarchy — 元素树 JSON
 """
 import requests
+from collections import Counter, defaultdict

 from core.logger import get_logger

@@ -78,12 +79,32 @@ def get_elements(serial):
    """获取指定设备的 UI 元素树。

    返回 (ok, data_or_error)：
-      ok=True  — data 是元素列表 [{name, attrs:{...}, children:[...]}, ...]
+      ok=True  — data 是元素列表 [{name, attrs..., suggested:{type,value,semantic?,via?,indexed?,occ?,total?,broad?}}, ...]
      ok=False — data 是错误消息字符串

-    元素树由 uiautodev 的 U2AndroidDriver.dump_hierarchy 返回（JSON）。
-    我们递归提取每个节点的关键属性（resource-id/text/description/class/...），
-    供前端列表展示和选择。
+    元素树由 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"]
+           - 重复出现（如抖音底部导航的 tab 同 id，个数还随灰度版本变）：
+             **优先用第二个属性把目标单独圈出来**（语义选择器）：
+               //*[@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"]/*[@class="android.widget.ImageView"][2]）；
+         整棵树都没有属性时退化为从根开始的结构路径
+         （//hierarchy/*[1]/*[3]…，标记 broad，前端提示脆弱）。
+         注意：dump 的 XML 标签一律是 <node>，class 在 @class 上 —— 任何把
+         class 名当标签名的写法（//FrameLayout[1]）都永远匹配不到，别再用。
    """
    if not serial:
        return False, "缺少 serial"
@@ -99,7 +120,7 @@ def get_elements(serial):
        # uiautodev hierarchy 返回 Node 树：{key, name, bounds, rect, properties, children}
        # 提取成扁平的可选列表（保留层级缩进信息）
        elements = []
-        _flatten(data, elements, depth=0)
+        _extract(data, elements)
        if not elements:
            return False, "当前界面未抓取到元素"
        return True, elements
@@ -112,78 +133,310 @@ def get_elements(serial):
        return False, f"抓取失败: {e}"


-def _flatten(node, out, depth=0, path="", ctx=None, tag_index=0):
-    """递归扁平化元素树，提取关键属性供前端选择。
+def _child_path(path):
+    """内部路径 `/0/2/1` → XPath 段 `/*[1]/*[3]/*[2]`（按**子节点位置**逐层定位）。

-    uiautodev dump_hierarchy 返回 Node 格式：
-      {key, name, bounds(归一化浮点), rect({x,y,width,height}), properties({所有属性}), children}
-    其中 properties 包含原始 XML 属性（resource-id/text/content-desc/class/bounds 字符串等）。
-
-    ctx: 最近一个有唯一属性（resource-id/text/content-desc）祖先的 xpath。
-         无唯一属性的元素用它限定范围生成精确选择器，避免裸 class（如 //ImageView）过宽误点。
-    tag_index: 本节点在父节点同 class 兄弟中的序号（1-based），用于消歧。
+    用于"整棵树都没有可用属性"时的兜底结构路径。为什么按位置而不是 `@index`：
+    实测 Android dump 里同级节点的 index 属性**会重复**（状态栏/内容区/导航栏
+    三个兄弟的 index 全是 "0"），拿它定位会一次命中好几个。
    """
-    if not isinstance(node, dict):
-        return
-    props = node.get("properties") or {}
-    name = node.get("name") or props.get("class") or ""
-    # bounds：优先取 properties 中的原始字符串 "[x1,y1][x2,y2]"（前端渲染 overlay 用）
-    bounds_str = props.get("bounds", "")
-    if not bounds_str and node.get("rect"):
-        r = node["rect"]
-        bounds_str = f"[{r['x']},{r['y']}][{r['x']+r['width']},{r['y']+r['height']}]"
+    return "".join(f"/*[{int(seg) + 1}]"
+                   for seg in path.strip("/").split("/") if seg)

-    rid = props.get("resource-id", "")
-    text = props.get("text", "")
-    desc = props.get("content-desc", "")
-    cls = props.get("class", "")
-    tag = cls.split(".")[-1] if cls else "*"

-    # 推荐选择器：唯一属性优先；否则用最近锚点祖先限定范围（带同class序号消歧）
-    if rid:
-        suggested = {"type": "xpath", "value": f'//*[@resource-id="{rid}"]'}
-        child_ctx = suggested["value"]
-    elif text:
-        suggested = {"type": "xpath", "value": f'//*[@text="{text}"]'}
-        child_ctx = suggested["value"]
-    elif desc:
-        suggested = {"type": "xpath", "value": f'//*[@content-desc="{desc}"]'}
-        child_ctx = suggested["value"]
-    else:
-        if ctx:
-            seg = f"/{tag}" + (f"[{tag_index}]" if tag_index > 1 else "")
-            suggested = {"type": "xpath", "value": f"{ctx}{seg}"}
-            child_ctx = f"{ctx}{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:
+        return "'" + v + "'"
+    return '"' + v + '"'
+
+
+def _extract(root, out):
+    """把 uiautodev 元素树扁平化为可选列表，并为每个节点生成精确选择器建议。"""
+    # 全树属性出现次数（预统计：判断"这个值重不重复"，决定要不要消歧）
+    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()
+
+    def count_attrs(node):
+        if not isinstance(node, dict):
+            return
+        props = node.get("properties") or {}
+        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)
+
+    # 消歧时可用的次要属性（按"越稳越靠前"排：文字 > 描述 > class）
+    _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 个匹配
+          (//*[@resource-id="x"])[2] → 「第 2 个匹配」← 我们要的
+        历史实现写成前者，导致同 id 多实例（如抖音底部导航 4 个 tab 同 id）时
+        [2..n] 全部匹配不到 → 运行时"未找到元素"（2026-09-10 实测修复）。
+        """
+        seen[value] += 1
+        conds = [(attr, value)]
+        if cnt[value] > 1:
+            extra, via = secondary_conds(peers, props)
+            if extra:
+                conds += extra
+            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):
+        """递归扁平化。
+
+        ctx: 最近一个有属性祖先的选择器（含序号），无属性元素用它限定范围。
+        tag_path: 从根到本节点的完整结构路径（class + 同class兄弟序号），兜底用。
+        tag_index: 本节点在父下同 class 兄弟中的序号（1-based）。
+        """
+        if not isinstance(node, dict):
+            return
+        props = node.get("properties") or {}
+        name = node.get("name") or props.get("class") or ""
+        # bounds：优先取 properties 中的原始字符串 "[x1,y1][x2,y2]"（前端渲染 overlay 用）
+        bounds_str = props.get("bounds", "")
+        if not bounds_str and node.get("rect"):
+            # rect 兜底：只有整数像素坐标才用；uiautodev 归一化浮点坐标无法换算像素
+            r = node["rect"]
+            try:
+                vals = [r["x"], r["y"], r["x"] + r["width"], r["y"] + r["height"]]
+                if all(isinstance(v, (int, float)) and float(v).is_integer() for v in vals):
+                    bounds_str = f"[{int(vals[0])},{int(vals[1])}][{int(vals[2])},{int(vals[3])}]"
+            except (TypeError, KeyError):
+                pass
+
+        rid = props.get("resource-id", "")
+        text = props.get("text", "")
+        desc = props.get("content-desc", "")
+        cls = props.get("class", "")
+        tag = cls.split(".")[-1] if cls else "*"
+        # 始终带同 class 兄弟序号（含 [1]），结构路径才精确无歧义；
+        # class 为空的层（tag=*）不参与结构路径，避免 //*[N] 前缀污染导致选择器定位到任意节点
+        if tag != "*":
+            # 步进必须写成 `*[@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:
-            # 无唯一属性且无锚点祖先：裸 class 过宽，标记 broad 让前端提示
-            suggested = {"type": "xpath", "value": f"//{tag}", "broad": True}
+            seg = ""
+            own_tag_path = tag_path
+
+        # ---- 推荐选择器：唯一属性 > 锚点祖先限定 > 全结构路径 ----
+        if rid:
+            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,
+                                                 text_nodes[text], props)
+        elif 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}
+            child_ctx = val
+        else:
+            if tag == "*":
+                # class 也为空的元素：结构路径 //*[N] 无意义（匹配到文档任意节点），
+                # 标记 invalid，前端提示不可选，避免回填垃圾选择器导致"点击不到"
+                suggested = {"type": "xpath", "value": "",
+                             "invalid": True,
+                             "reason": "该元素无可用属性（id/文本/class），无法生成可靠选择器"}
+            else:
+                # 无唯一属性且无锚点祖先：用从根开始的结构路径（脆弱，标记 broad 让前端提示）。
+                # 按子节点位置逐层定位 —— 历史实现写成 //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

-    item = {
-        "depth": depth,
-        "path": path,
-        "name": name,
-        "resource_id": rid,
-        "text": text,
-        "description": desc,
-        "class": cls,
-        "package": props.get("package", ""),
-        "clickable": props.get("clickable", ""),
-        "bounds": bounds_str,
-        # 推荐选择器（resource-id > text > description > 锚点祖先限定class）
-        "suggested": suggested,
-    }
-    out.append(item)
-    # 递归子节点，同时计算每个子节点在父下同 class 兄弟中的序号
-    children = node.get("children") or []
-    for i, child in enumerate(children):
-        cprops = child.get("properties") or {}
-        ccls = cprops.get("class", "")
-        ctag = ccls.split(".")[-1] if ccls else "*"
-        same = 1
-        for prev in children[:i]:
-            pcls = (prev.get("properties") or {}).get("class", "")
-            ptag = pcls.split(".")[-1] if pcls else "*"
-            if ptag == ctag:
-                same += 1
-        _flatten(child, out, depth + 1, f"{path}/{i}", child_ctx, same)
+        out.append({
+            "depth": depth,
+            "path": path,
+            "name": name,
+            "resource_id": rid,
+            "text": text,
+            "description": desc,
+            "class": cls,
+            "package": props.get("package", ""),
+            "clickable": props.get("clickable", ""),
+            "bounds": bounds_str,
+            "suggested": suggested,
+        })
+
+        # 递归子节点，同时计算每个子节点在父下同 class 兄弟中的序号
+        children = node.get("children") or []
+        for i, child in enumerate(children):
+            cprops = child.get("properties") or {}
+            ccls = cprops.get("class", "")
+            ctag = ccls.split(".")[-1] if ccls else "*"
+            same = 1 + sum(
+                1 for prev in children[:i]
+                if ((prev.get("properties") or {}).get("class", "")).split(".")[-1] == ctag
+            )
+            flatten(child, depth + 1, f"{path}/{i}", child_ctx, own_tag_path, same)
+
+    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)}
@@ -1,85 +0,0 @@
-"""一次性脚本：创建"抖音定时8-9点"任务。
-
-用法（在 cmd 中执行，不是 PowerShell）：
-    cd /d d:\\platform-tools
-    python create_task.py
-
-任务配置：
-  - 名称：抖音定时8-9点
-  - 类型：douyin_nurture（抖音养号）
-  - 目标：全部空闲设备
-  - 调度：定时启停（每天 8:00 启动，9:00 自动停止）
-  - 视频数量：不限（watch_count=0，靠停止 cron 到点停）
-  - 运行时长：不限（max_duration=0，靠停止 cron 到点停）
-  - 点赞：启用，rate=0.3
-"""
-import sys
-import os
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-from flask import Flask
-from core.models import db, init_db, TaskJob as JobRow
-from core.task_manager import TaskManager, TaskJob
-from core.stf_client import STFClient
-
-app = Flask(__name__)
-app.config["SECRET_KEY"] = "dev-secret-key-change-in-production"
-app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///" + os.path.join(
-    os.path.dirname(os.path.abspath(__file__)), "data", "users.db")
-app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
-
-init_db(app)
-
-with app.app_context():
-    # 检查是否已存在同名任务
-    existing = JobRow.query.filter_by(name="抖音定时8-9点").first()
-    if existing:
-        print(f"任务已存在: id={existing.id}, name={existing.name}")
-        print("如需重新创建，请先在前端删除该任务。")
-        sys.exit(0)
-
-    # 构造任务计划
-    job = TaskJob(
-        name="抖音定时8-9点",
-        task_type="douyin_nurture",
-        target={"mode": "all"},
-        params={
-            "watch_count": 0,       # 不限视频数量
-            "max_duration": 0,      # 不限运行时长（靠 stop_cron 到点停止）
-            "actions": {
-                "like": {
-                    "enabled": True,
-                    "params": {"rate": 0.3, "method": "by_element"},
-                },
-            },
-        },
-        schedule={
-            "mode": "cron_stop",
-            "cron": "0 8 * * *",        # 每天 8:00 启动
-            "stop_cron": "0 9 * * *",   # 每天 9:00 停止
-        },
-        retry={"max_attempts": 1, "delay": 60},
-        enabled=True,
-    )
-
-    # 写入数据库
-    row = JobRow(id=job.id, name=job.name, task_type=job.task_type, enabled=job.enabled)
-    row.set_target(job.target)
-    row.set_params(job.params)
-    row.set_schedule(job.schedule)
-    row.set_retry(job.retry)
-    db.session.add(row)
-    db.session.commit()
-
-    print(f"✓ 任务创建成功！")
-    print(f"  ID: {job.id}")
-    print(f"  名称: {job.name}")
-    print(f"  类型: {job.task_type}")
-    print(f"  目标: 全部空闲设备")
-    print(f"  调度: 每天 08:00 启动 → 09:00 自动停止")
-    print(f"  视频数量: 不限（靠定时停止）")
-    print(f"  点赞: 启用 (rate=0.3)")
-    print()
-    print("启动 web_server 后，该任务会自动加载并注册定时。")
-    print("启动命令: python web_server.py")
@@ -0,0 +1,233 @@
+# AI 控制台（AI_CONSOLE）
+
+> 适用读者：使用 AI 控制台的人 + 改这部分代码的开发者。
+> 相关文档：[API.md](API.md) §12（接口）、[MCP.md](MCP.md)（AI 用的工具层）、[AI_TASK_GEN.md](AI_TASK_GEN.md)（"一句话建任务"的设计稿，尚未实现）。
+
+---
+
+## 1. 它是什么
+
+「AI 控制台」是后台的一个顶级 Tab（仅管理员），下面有两个子分栏：
+
+| 子分栏 | 做什么 | 文档 |
+|--------|--------|------|
+| 💬 **聊天** | 选一台设备用自然语言下指令，AI 通过 MCP 工具**看屏幕、点按、输入**，边做边把过程和结论流式显示出来（本文内容） | 本文 |
+| 🧭 **AI 建任务** | 描述"要什么样的自动化"，AI **自己在真机上探索**（看屏/读元素树/点按验证），把走通的路径写成**一条可调度任务**，校验后交人工在步骤编辑器确认 | [AI_TASK_GEN.md](AI_TASK_GEN.md) |
+
+> 两个子分栏共用**同一个运行槽**（全平台同时只允许一个 Agent 运行）：建任务在探索时，聊天页会显示"● 建任务探索中"并禁用发送，反之亦然。
+
+```
+你：「打开小红书搜索苏州好吃的饭店，把前 5 条列出来」
+AI：de_list_devices → de_screenshot → de_tap_text("搜索") → de_type_text("苏州好吃的饭店")
+    → de_screenshot → de_ui_tree → … → 汇总结论（Markdown 表格）
+```
+
+两个"自进化记忆"让它越用越顺：
+
+| 记忆 | 存什么 | 怎么产生 | 怎么用 |
+|------|--------|---------|--------|
+| **🧠 经验库** | 任务级**操作配方**（这一步该怎么做） | 一轮任务成功后由模型蒸馏 | 相似任务开始时召回注入 system prompt |
+| **🎬 动作库** | **命名动作**（可复用的动作单元，带元素定位） | 从**成功步骤**蒸馏，禁坐标 | 相似任务开始时召回注入，可直接复用定位 |
+
+---
+
+## 2. 使用
+
+### 2.1 配置（首次必做）
+
+右上角 **⚙ 配置**：
+
+| 项 | 说明 |
+|----|------|
+| API Base | OpenAI 兼容地址（默认 `https://api.deepseek.com`） |
+| 模型名 | 如 `deepseek-v4-flash-vision-exp`（需支持**视觉**，因为要看截图） |
+| API Key | 只存数据库 `app_meta`，回显打码 |
+| 默认设备 | 不选目标设备时用它 |
+| 最大步数 | 1-200，默认 40（每轮模型调用算一步） |
+
+> 配置存在数据库（`app_meta` 的 `agent_*` 键），**不在 `.env`**。`CLI（mcp_agent/cli.py）` 走的是环境变量 `AGENT_*`，两套互不影响。
+
+### 2.2 跑一轮
+
+1. 选 **🎯 目标设备**（AI **只操作你选定的设备**；有任务在跑的设备不可选）
+2. 输入指令，Enter 发送
+3. 右侧「📺 实时画面」自动跟随 AI 操作的设备（MJPEG）
+4. 中途可「■ 停止」（下一个检查点生效，通常几秒内）
+5. 刷新/换窗口：会话与运行状态都会自动恢复（见 §3.3）
+
+### 2.3 会话管理
+
+左侧会话列表 = 多轮对话（DeepSeek 风格）：不同话题建不同会话，历史消息会作为上下文续上（最近 12 轮）。会话条目上显示 ID（前 8 位，点击复制），便于反馈问题时引用 `conv=<id>`。
+
+---
+
+## 3. 机制
+
+### 3.1 执行链路
+
+```
+POST /api/agent/run            web/agent_api.py 起后台线程（单实例：同时只允许一个）
+        │
+        ├─ 经验召回 _find_experiences(prompt)   ─┐
+        └─ 动作召回 _find_actions(prompt)        ├─ 拼成 extra_context 注入 system prompt
+                                                 ┘
+        ▼
+mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage, …)
+        │  循环（最多 max_steps 轮）：
+        │    ① 流式调模型（OpenAI 兼容 /chat/completions）
+        │    ② 有 tool_calls → 执行 MCP 工具 → 结果回灌 → 继续
+        │       截图工具的结果会转成 image_url 追加，模型"看得见"
+        │    ③ 无 tool_calls → 本轮即最终回答
+        ▼
+   事件 → queue → SSE /api/agent/stream → 前端
+```
+
+- 一轮整体超时 **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 会话消息模型
+
+`agent_conversation.messages`（JSON 数组）：
+
+```json
+[{"role": "user", "content": "…"},
+ {"role": "assistant", "content": "最终回答（Markdown）",
+  "usage":     {"prompt_tokens": 3480, "completion_tokens": 126, "total_tokens": 3606, "calls": 1},
+  "reasoning": "模型的推理链（最多保留 6000 字符）"}]
+```
+
+> `usage` / `reasoning` **只用于前端展示与回看**；回灌给模型的历史只取 `role` / `content`（不污染上下文预算）。
+
+### 3.3 SSE 事件与刷新恢复
+
+| event | payload | 前端行为 |
+|-------|---------|---------|
+| `delta` | `{"text","kind":"content"\|"reasoning"}` | 正文增量渲染 Markdown；推理增量进入可折叠「💭 思考过程」 |
+| `step` | `{"tool","args","image"?}` | 追加工具卡片（含缩略截图，点击放大）；伪卡片提示经验/动作命中与沉淀 |
+| `usage` | `{"prompt_tokens","completion_tokens","total_tokens","calls"}` | 刷新单条消息脚注与顶栏「本会话累计」 |
+| `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
+- 按「每次模型调用」累加（多轮工具调用会累加多次）；`calls` = 模型调用次数
+- 个别网关不认该参数会直接 400/422 → **自动关掉并重试一次**，不影响主流程（只是没有 token 数字）
+- 展示位置：单条消息脚注（`🪙 3,606 tokens（↑3,480 ↓126 · 1 次调用）`）+ 顶栏「🪙 本会话 3,606 tokens」
+
+### 3.5 回答渲染
+
+- **Markdown**：自研轻量渲染器（`static/admin/markdown.js`，**无 CDN 依赖**，生产在内网）
+  支持标题/段落/列表（含嵌套）/表格/代码块/引用/链接；**先 `esc()` 转义再套标记**，所以模型输出里的 HTML 只会显示为文本
+- **推理链**：`<details>` 折叠块，流式时展开、正文开始时自动收起；手动点过后不再自动改；摘要显示字数
+- **工具卡片**：每步 MCP 调用一行（工具名 + 参数 + 截图缩略）
+
+---
+
+## 4. 经验库
+
+### 4.1 产生（蒸馏）
+
+一轮任务**成功执行过工具**后，把「任务描述 + 工具序列」交给模型，提炼成一段**可复用的操作配方**（纯文本，不含具体坐标）。
+
+健壮性设计（都是踩坑后加的）：
+
+| 措施 | 原因 |
+|------|------|
+| 蒸馏调用**关闭推理**（`thinking: {"type":"disabled"}`） | 推理模型会把 token 预算烧在 reasoning 上，导致 `content` 为空/被截断 → 经验被静默丢弃 |
+| 纯文本问法 + 质量门槛 | 早期提示词里放了可照抄的占位示例，模型会把 `"1. …\n2. …"` 原样当配方存下来 |
+| 截断容忍解析 | JSON 被截断时逐个对象抢救 |
+| 失败有日志 | 不再静默 |
+
+### 4.2 召回
+
+相似任务开始时按 bigram 相似度检索（阈值 + 取前 2 条），拼进 system prompt，并在对话里推一张「🧠 经验记忆」卡片（"命中 N 条同类历史经验，已注入参考"）。命中会累加 `hits`。
+
+### 4.3 巡检（质量治理）
+
+- 每日 **03:47**（独立 APScheduler）自动跑一轮：把经验交给模型评审，输出「保留 / 建议删除」+ 评分 + 理由，写入 `experience_audit`
+- 也可在面板里手动触发
+- **删除永远需要人工确认**（巡检只打标 `pending`，面板上显示 ⚠ 建议删除 + 理由，人工点「确认删除」或「保留」）
+- 「保留」会记 `action='kept'`，后续不再重复建议
+
+### 4.4 面板
+
+「🧠 经验库」按钮打开：列表（任务描述、配方摘要、引用次数、巡检建议）+ 删除/保留操作。
+
+---
+
+## 5. 动作库
+
+### 5.1 与经验库的区别
+
+| | 经验库 | 动作库 |
+|---|--------|--------|
+| 粒度 | 整个任务的操作套路（文字） | 单个可复用动作（结构化步骤） |
+| 内容 | 自由文本配方 | 命名动作 + `steps`（编辑器 schema，**带元素定位**） |
+| 用途 | 让 AI 知道"这类任务一般怎么做" | 让 AI 直接复用"打开抖音"这种动作，跳过重新探索 |
+
+### 5.2 产生（蒸馏）
+
+从本轮**成功**的步骤轨迹里提炼命名动作（如「打开抖音」）。硬约束：
+
+- **禁坐标**：带 `click_xy` 的步骤不会被沉淀（坐标换个设备/分辨率就失效）
+- 白名单步骤类型（**显式列举 16 种**，见 `web/agent_api.py` 的 `_ACTION_STEP_TYPES`）：
+  `open_app` / `stop_app` / `screen_on` / `screen_off` / `key_event` / `swipe` /
+  `swipe_until` / `click` / `long_click` / `wait_el` / `input_text` / `clipboard` /
+  `wait` / `loop` / `group` / `if_el`——坐标类（`click_xy`）与流程标记类
+  （`keep_screen` / `gesture` / `notify` / `stop_self` / `mark_done`）都不沉淀
+- 每类型有必填参数校验（如 `click` 必须有选择器）
+- 输入/产出限量：最多 10 步输入、最多 3 个动作 × 4 步
+- 保存时服务端**再校验一次**，含坐标的提交直接 400
+
+### 5.3 召回与使用
+
+相似任务时按动作名/别名匹配（子串或 bigram 相似度），注入「## 可复用动作」段，并推「🧠 动作经验」卡片。AI 被提示"优先按其中的元素定位操作；若与当前界面不符，再自行截图确认"。
+
+### 5.4 面板
+
+「🎬 动作库」：查看/编辑/删除/手动新建。编辑时直接改 `steps` JSON（有格式说明），保存走同一套校验。
+
+---
+
+## 6. 配置项（`app_meta`）
+
+| key | 含义 | 默认 |
+|-----|------|------|
+| `agent_api_base` | 模型接口地址 | `https://api.deepseek.com` |
+| `agent_model` | 模型名 | — |
+| `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 轮；
+建任务模式（designer）输出上限 8192、单工具调用上限 40 次（`mcp_agent/agent.py`）。
+
+---
+
+## 7. 故障排查
+
+| 现象 | 原因 / 处理 |
+|------|------------|
+| 报「MCP server(8033) 不可达」 | MCP 没启动：容器由 `start.sh` 拉起；本机手动 `MCP_ALLOW_WRITE=1 python -m mcp_server.mcp_server` |
+| 报模型 API **401** | API Key 无效/过期 → ⚙ 配置重填 |
+| 报"请先选择目标设备" | 没选设备且没配默认设备 |
+| 报"设备正在执行任务…"（409） | AI 不与任务抢设备：等任务结束，或去监控页停止该任务 |
+| 没有 token 数字 | 该网关不支持 `stream_options.include_usage`（已自动降级，功能不受影响） |
+| 经验/动作没沉淀 | 只有**成功执行过工具**才会蒸馏；看 `logs/web.log` 的「经验提炼 / 动作提炼」日志 |
+| 推理链看不到 | 模型未返回 `reasoning_content`（非推理模型），或本轮没有推理输出 |
+| 界面样式/脚本异常 | 强刷浏览器（Ctrl+Shift+R）——`markdown.js` 等前端文件有缓存 |
@@ -0,0 +1,267 @@
+# AI 建任务（AI Task Generator）设计文档
+
+> 状态：**P0 已实现**（2026-09-13）——§1~§9 是设计稿（与实现基本一致），
+> **§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）通过 20 个 `de_*` 工具在手机上「边看边做」（截图看屏、`de_ui_tree` 拿元素树、`de_tap_element/de_tap_text` 语义点按），流式回放步骤。
+- **任务系统 + 步骤编辑器**：`generic_steps` 任务 = 一棵可嵌套步骤树（open_app/click/swipe/loop/group/if_el…22 种节点），在编辑器里拖拽编排、单步试跑、定时调度。
+
+目标：让**非工程用户用一句自然语言需求**（例：「创建一个每日养号刷视频的任务，每天 8:00-9:00 在 100.100.10.13 跑」）得到**一条可直接调度、可继续在现有步骤编辑器里手改的任务**。AI 先自己在设备上打开 App、看 UI 树、确认可点元素，再直接撰写编辑器的步骤 JSON。
+
+### 产品体验（一页）
+1. 用户进入「AI 控制台 → 模式=AI 建任务」，选一台**空闲**设备，填需求 +（可选）任务名/调度/目标。
+2. AI 自探并**流式回放**（工具卡 + 截图，与现在一致）：开 App → dump UI 树 → 确认要点的元素可命中 → 写步骤。
+3. 完成后平台返回任务草稿 `draft`，服务端 schema 校验后，**前端直接打开现有「新建任务 → 步骤编辑器」**预填。
+4. 用户核对/手改/单步试跑 → 保存 → 进任务列表，走原有调度器执行。
+
+**核心信任原则：AI 只“提案”，不直接建库、不直接执行最终任务；最终落库/执行都在用户确认后由现有机制完成。**
+
+## 2. 范围（P0 定稿，2026-09-09 与用户确认）
+
+- **入口**：AI 控制台加「聊天 / AI 建任务」模式开关，复用会话/SSE/设备选择/停止/刷新恢复骨架。不新建顶级 Tab。
+- **产出方式**：**AI 直接撰写编辑器的步骤 JSON**（非操作轨迹翻译）。自探信息只作上下文与审计；探索中的误点/多余截图不会混入任务。
+- **任务类型**：**只产 `generic_steps`**（通用步骤）——平台当前唯一的任务类型
+  （原 `douyin_nurture` 预设参数生成已随该类型删除，不再做）。
+- **定位原则：全部基于 UI 树**：
+  - 模型定位/点击一律走 `de_ui_tree` 拿到的元素（`text`/`id`/`description`/`text_contains`），多实例用 index，或后端 `uiauto_helper` 生成的 `//*[@resource-id=..][k]` XPath；
+  - `de_tap_element` 确认能命中后才写进 `click` 步骤；
+  - **默认不产 `click_xy` 坐标点击**；UI 树给不了的元素记入 notes，交给人工/OCR 兜底；
+  - 滑动用方向语义 `swipe{direction}`，不用像素坐标。
+- 产出完整任务信封：`{name, task_type:"generic_steps", target, schedule, retry, enabled, params:{max_duration, steps}}`。
+
+## 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 的 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）。
+- 单步试跑：`/api/steps/test`（tasks_api.py L249）+ `editor.js _testStep`；`tasks/generic/task.py test_step`（L633）。
+- 任务/调度/目标：`core/task_manager.py` `TaskJob`（L121-199）；`POST /api/jobs`（tasks_api.py L68）。
+- 设备占用语义：MCP 写工具 `_ensure_device_free`（mcp_server.py L60-78，running/connecting → `device_busy`）；`agent_api` run 入口同样对 worker running/connecting 拒绝（409）。
+- 经验库自进化：`agent_experience` + bigram 检索注入 + 每日巡检（`web/agent_api.py`）——P1 沉淀模板的现成载体。
+
+## 4. 架构与数据流
+
+```
+需求+设备(空闲) ──▶  Designer Agent(自探, 模式=designer)
+                        │  de_open_app / de_ui_tree / de_screenshot / de_tap_element…
+                        ▼
+                平台工具 submit_task(draft)  ← 结束性调用
+                        │  服务端 draft schema 校验(白名单+必填+深度≤5)
+                        ▼
+        前端: 打开 openTaskModal 步骤编辑器, 预填 draft.task
+                        │  用户核对/手改/单步试跑(/api/steps/test)
+                        ▼
+                POST /api/jobs  → 任务列表(原调度器执行)
+   (P1) draft+需求 沉淀 agent_experience, 相似需求注入参考
+```
+
+### 4.1 Designer Agent（新增模式，复用现有 Agent）
+- `mcp_agent` 增加 designer 系统提示词：角色=自动化任务设计师；行为约束见 §5.1。
+- 增加**平台级工具**（不属设备 `de_*`）：
+  - `submit_task(draft)`：结束性工具，模型完成自探后提交草稿即停止，服务端立即校验。
+- 会话内同时记录**结构化 trace**（每轮 `on_tool` 的 `{tool, args 精简, 屏号/证据}`），用于：校验证据（每个 selector 来自哪次树）、审计、P2 回放。
+- `POST /api/agent/run` 增加 `mode:"designer"`；`done` 事件负载携带 `draft`（校验通过）或 `draft_error`（校验失败+原因，让模型补一轮）。
+
+### 4.2 draft 契约
+```json
+{
+  "summary": "每日8-9点刷抖音养号：开抖音→循环(看5~35s+上滑)+随机间隔",
+  "task": {
+    "name": "抖音每日养号",
+    "task_type": "generic_steps",
+    "target": {"mode":"serial","serial":"100.100.10.13:5555"}
+            | {"mode":"group","group_name":"测试"} | {"mode":"all"},
+    "schedule": {"mode":"once"} | {"mode":"cron","cron":"0 8 * * *"}
+               | {"mode":"cron_stop","cron":"0 8 * * *","stop_cron":"0 9 * * *"},
+    "retry": {"max_attempts":5,"delay":30},
+    "enabled": true,
+    "params": {
+      "max_duration": 0,
+      "steps": [
+        {"type":"open_app","label":"打开抖音","params":{"package":"com.ss.android.ugc.aweme","wait_home":true}},
+        {"type":"loop","params":{"loop_mode":"rounds","max_iterations":30,"children":[
+           {"type":"wait","params":{"min":5,"max":35}},
+           {"type":"swipe","params":{"direction":"up","duration_min":0.25,"duration_max":0.5}}
+        ]}}
+      ]
+    }
+  },
+  "notes": ["评论按钮需先进入视频页才可见"],
+  "evidence": [{"screen":"抖音首页","element":{"text":"关注","id":"..."},"xpath":"//*[@resource-id=\".../gvo\"]"}]
+}
+```
+- 步骤节点结构：`{id?, type, label?, params}`；`id` 执行端忽略（编辑器重新生成），`params` 必填。
+- 必填字段语义（**空值会被执行端静默跳过**，校验器必须拦）：
+  - `click / long_click / swipe_until / wait_el / if_el` → `params.selector_value`
+  - `open_app / stop_app` → `params.package`
+  - 容器：`loop / group` → `params.children`（非空）；`if_el` → `params.then`（`else` 可选）
+  - `swipe_until` → direction + max_swipes；`click_xy` P0 不产（如允许则 x/y 0-100）
+  - 节点公共可选 `params.probability`（0-100，缺省 100）
+- `selector_type` 允许值：`xpath / description / text / resourceId / descriptionContains / className`（`if_el` 可 `ocr`）。
+
+### 4.3 服务端新增
+- `core/task_draft.py`：
+  - `STEP_TYPES` 白名单 + 每类必填/深度校验 `validate_steps(steps, depth)`（嵌套≤5）；
+  - `validate_draft(draft)`：任务信封（name 非空、task_type==generic_steps、target mode ∈ {all,group,serial}（group 名存在）、schedule cron 合法、steps 校验）；
+  - 归一化：把 `schedule` 里「每天 8-9 点」这类由前端/向导填的值转成 cron/cron_stop。
+- `web/taskgen_api.py`（或并入 `agent_api`，推荐并入以最大化复用）：
+  - 入口检查：serial 必须、设备在池/在线、worker 非 running/connecting（409，与现有语义一致）；
+  - 起 designer 后台线程；SSE 事件在现有 `delta/step/done/error` 基础上，`done` 可带 `draft`。
+- **注意**：现有 `POST /api/jobs` 对 params **盲存**（只校验 name+task_type）。AI 通道在**保存前**必须过 `validate_steps`，避免「任务 done 但什么都没做」（执行器对未知 type/空 selector 静默跳过）。
+
+### 4.4 前端
+- `monitor.html` AI 控制台加模式切换；建任务模式下输入栏旁有折叠「任务设置」（名称/调度时间/目标 serial·分组·全部/备注）。
+- `agent.js`：done 携带 draft 后：
+  - generic_steps → 调 `openTaskModal()`（tasks.js）并把 `draft.task` 灌入步骤编辑器（step 卡片可视化、可拖改、单步试跑、保存）；
+  - 弹窗内对 `notes`（含“需人工复核/OCR 兜底”项）给出醒目提示。
+- 过程回放沿用现有 `agent-toolcard` 渲染；可标记当前为 designer 轮以便后续区分。
+
+## 5. 约束与安全（红线）
+
+### 5.1 Designer 自探规则（写入提示词）
+1. 先 `de_open_app(package)`，再 `de_ui_tree` + `de_screenshot` 看每屏；点到关键状态后再 dump 下一屏。
+2. 每个将写入步骤的目标元素，先用 `de_tap_element`（by=text/id/desc…）+ 截图**确认可命中**，并记下证据。
+3. **不做破坏性动作**：需“评论/发送”时只确认输入框/发送键存在，不真发；产物里这类步骤 `probability` 调低并在 notes 标注“请人工复核”。
+4. 探索步数上限（P0 建议 30 步），可被 `/stop` 打断；结束后尽力还原前台 App。
+5. 未命中的元素一律不进任务；拿不准的进 notes 而非硬编。
+
+### 5.2 平台级约束
+- 自探/试跑只在**用户选的空闲设备**（busy → 409），杜绝与运行中任务在设备上物理打架。
+- AI 不直接建库；生成任务仍需用户点保存（POST /api/jobs 现有权限）。
+- 尽量不写死坐标；P0 默认禁 `click_xy`，产物以树元素定位为主。
+
+## 6. 里程碑
+- **P0（本设计主体）**：designer 模式 → 自探（UI 树定位）→ 直接撰写 generic_steps draft → 服务端 schema 校验 → 前端步骤编辑器预填确认保存。验收：一句话在真实设备上生成一条可调度的 generic_steps，步骤全部来自 UI 树且编辑器可打开。（平台只剩 generic_steps 一种任务类型，与原规划一致）
+- **P1**：模板沉淀：把 draft+需求写入 `agent_experience`（新列存结构化 steps 或 JSON），相似需求注入参考；整链「演示试跑」（把 steps 在设备上以受控方式跑一遍并截图回报，需新增端点，复刻 `device_busy` 拒绝语义）。
+  - **进展（2026-09-10）**：动作级沉淀已落地——`agent_action` 表 + 从**成功步骤**蒸馏"命名动作"（steps 用编辑器 schema、带元素定位、禁坐标）+ 执行前按名/别名召回注入（`web/agent_api.py`）。AI 建任务可直接把这些动作当作 generic_steps 的**预制件**复用。
+- **P2**：自定义动作支持（内联展开成 group，或新增 `action_ref` 节点 + 执行器/编辑器同步）；多设备并行；成本与 token 控制。
+
+## 7. 实现时需新增/改动文件（规划）
+- 改：`mcp_agent/`（designer 提示词与 `submit_task` 工具、结构化 trace）、`web/agent_api.py`（mode=designer、done 带 draft）、`static/admin/agent.js` + `templates/admin/monitor.html`（模式切换/任务设置/draft 预填）、`doc/`（本文档关联）。
+- 新：`core/task_draft.py`（schema+校验+归一化）、（可选）`web/taskgen_api.py`。
+- 不动：任务执行器、调度器、`POST /api/jobs` 主体（保持现有盲存，只在 AI 通道校验）。
+
+## 8. 验收（P0 实现后自测）
+1. 目标设备空闲时：需求「每日 8-9 点刷抖音养号」→ 生成 generic_steps 任务，步骤为 `open_app → loop(wait+swipe)` 结构，调度 cron_stop 8-9 点。
+2. 打开编辑器中该任务：步骤卡片完整、可拖改、单步试跑命中；保存后任务列表出现且下次运行时间正确。
+3. 反例：模型产出含 `click_xy` 或未知 type / 空 selector → 服务端校验拦截并让模型补正；busy 设备入口 409。
+4. 探索全程可在前端回放（工具卡+截图），未发送真实评论/未污染设备状态。
+
+## 9. 需要转成 MCP / 平台工具的能力（分层，2026-09-09 与用户确认）
+
+> 背景问答结论：目前 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`，20 个 `de_*`）＝ 设备控制 + 设备只读 + `de_list_tasks`（平台任务只读）。
+- 任务创建/修改/删除、toggle、立即运行、分组、设备池管理、自定义动作、APK、系统备份等 **REST 路由只给前端用，未暴露 MCP**。
+
+### 9.2 P0 —— AI 建任务链路真正需要的「平台工具」（最小集）
+只补两小类，其余设备操作全部复用现有 `de_*`：
+1. **只读清单**（供自探确定 target/能不能做）：
+   - `list_task_types` / `list_groups`（target 选 group 用）/ `list_pool`（可调度设备，含 busy 状态）
+   - （可与现有 `de_list_devices` 合并语义，避免重复）
+2. **校验 + 提交（结束性）**：
+   - `submit_task(draft)` → 服务端用 **共用** `core/task_draft.validate_steps()/validate_draft()` 校验，**不直接落库**，返回 draft 供前端打开步骤编辑器预填、人工确认后走 `POST /api/jobs`。
+
+> 关键：P0 的 Agent **不暴露任务 CRUD 写权限**（create/update/toggle/run），否则模型可绕过"AI 提案 → 人工确认"直接入库，破坏信任模型。
+
+### 9.3 P1 —— 外部自动化 / 后续 Agent 的「写 MCP」（受权限约束，逐块加）
+若目标延伸为"外部程序能像调 REST 一样操控平台"，则按此清单**逐个**补（每加一个都做权限+busy+审计+校验下沉）：
+- 任务：`create_job` / `update_job` / `delete_job` / `toggle_job` / `run_job_now` / `query_jobs`
+- 分组：`list_groups` / `create_group` / `update_group` / `delete_group`
+- 设备池：`pool_list` / `pool_add` / `pool_remove` / `pool_toggle`
+- 自定义动作 / APK 清单 等视使用再加
+- **只读清单优先搬**；写类确认有真实消费方再做，避免空转。
+
+### 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. 自测产生的东西（草稿/自建任务）用后即删，别碰用户真实数据。
@@ -1,340 +1,408 @@
-# 架构详解
+# 架构详解（ARCHITECTURE）

-本文面向想深入理解 `platform-tools` 内部设计的开发者。如果你只想使用，看 [README.md](file:///d:/platform-tools/README.md) 即可。
+> 适用读者：要改后端 / 前端 / 任务引擎的开发者。
+> 相关文档：[DATA_MODEL.md](DATA_MODEL.md)（表结构）、[API.md](API.md)（接口清单）、[DEVELOPMENT.md](DEVELOPMENT.md)（流程与红线）。
+> 文中引用为 `文件:行号`，以当前代码为准；**行号会随改动漂移，函数名与常量名是稳定锚点**。

 ---

-## 1. 分层设计
+## 1. 总览

-平台按"配置 / 核心 / 任务 / 前端 / 数据 / 日志 / 工具"分层，职责清晰、互不交叉：
+### 1.1 分层

-| 层 | 路径 | 职责 |
-|----|------|------|
-| 配置层 | `config.py` | 项目根配置：STF 地址、adb 路径、web 端口等基础设施。**不放任务参数** |
-| 核心层 | `core/` | 框架运行时：日志、STF 客户端、adb 操作、Worker 基类、任务管理器、u2 辅助、Action 基类 |
-| 任务层 | `tasks/` | 每个 App 一个子包，自包含 `task.py` + `actions/`，互不依赖 |
-| 前端层 | `templates/admin/` | 单页应用（纯 HTML+CSS+JS，无框架） |
-| 数据层 | `data/` | SQLite 持久化 |
-| 日志层 | `logs/` | 四类日志，10MB 滚动保留 5 份 |
-| 工具层 | `bin/adb/` | adb 可执行文件 |
-| 脚本层 | `scripts/` | 实用脚本 |
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│ 表现层   templates/admin/*.html + static/admin/*.js（单页应用，无框架）  │
+│          7 个顶级 Tab；轮询 / SSE / MJPEG 三类实时通道                    │
+└───────────────────────────┬──────────────────────────────────────────┘
+                            │ fetch JSON / SSE / MJPEG / 表单
+┌───────────────────────────▼──────────────────────────────────────────┐
+│ Web 层   web/（10 个 Flask 蓝图，全部 url_prefix 为空）                 │
+│   auth 鉴权 · monitor 状态与设备操作 · tasks 任务 · admin 用户与日志     │
+│   tools 运维 · devices 设备池 · apks 应用 · tailscale · agent AI 控制台  │
+│   system 备份                                                          │
+└───────────────────────────┬──────────────────────────────────────────┘
+                            │ 直接函数调用（共享对象由 web/context.py 注入）
+┌───────────────────────────▼──────────────────────────────────────────┐
+│ 领域层   task_manager（调度）  device_worker（执行）  device_pool（池）  │
+│          system_backup（备份）  apk_manager（应用）  device_discovery   │
+│          device_battery（电量采集 + 低电量告警）  dedup（去重账本）        │
+└───────────────────────────┬──────────────────────────────────────────┘
+                            │
+┌───────────────────────────▼──────────────────────────────────────────┐
+│ 基础层   adb_helper · u2_helper · uiauto_helper · ocr · clipboard      │
+│          notifier（通知分发：队列/聚合/限流/适配器）                      │
+│          step_log（步骤明细：队列 + 批量落库 + 保留期清理）               │
+│          models（SQLite）· logger · config                             │
+└──────────────────────────────────────────────────────────────────────┘
+                            ▲
+┌───────────────────────────┴──────────────────────────────────────────┐
+│ 任务定义层  tasks/（BaseTask 注册表 + generic/ 通用步骤引擎）            │
+└───────────────────────────┬──────────────────────────────────────────┘
+                            ▲                       ▲
+┌───────────────────────────┴────────┐  ┌───────────┴──────────────────┐
+│ MCP Server（mcp_server/，:8033）    │  │ AI Agent（mcp_agent/）        │
+│ 20 个 de_* 工具，供外部 AI 调用      │  │ OpenAI 兼容模型 → MCP 工具     │
+└────────────────────────────────────┘  └──────────────────────────────┘
+```

-### 分层原则
+### 1.2 各层职责边界

- **任务自包含**：每个任务的参数、Worker、操作都放在 `tasks/<app>/` 下，不污染全局
- **核心不依赖任务**：`core/` 不 import `tasks/`，任务通过注册机制接入
- **配置最小化**：`config.py` 只放基础设施配置，任务参数在各自 `task.py` 顶部
+| 层 | 做什么 | 不做什么 |
+|----|--------|---------|
+| 表现层 | 渲染、交互、轮询/流式拉取、按权限隐藏入口 | 不校验权限（只隐藏）；不做业务判断 |
+| Web 层 | 参数校验、鉴权装饰器、JSON 序列化、调用领域层 | 不直接操作 adb/u2（`monitor` 的看屏/截图除外，那本身就是"设备操作"） |
+| 领域层 | 调度、并发、重试、状态机、持久化 | 不感知 HTTP |
+| 基础层 | adb / u2 / OCR / 数据库 / 日志的原子能力 | 不含业务规则 |
+| 任务定义层 | 任务类型注册 + 具体任务执行逻辑 | 不感知调度与设备获取（`BaseWorker` 已封装） |
+
+**装配方向**：`web_server.py` 是唯一组装点；`web/context.py` 注入 `mgr` / `apk_mgr` / `device_pool`，避免 Web 层与领域层循环 import。

 ---

-## 2. 数据流
+## 2. 启动与装配顺序

-```
-┌──────────────┐  创建/编辑任务    ┌─────────────┐  分发 worker   ┌──────────────┐
-│ 单页应用前端  │ ───────────────► │ TaskManager │ ─────────────► │  Worker(设备) │
-│ (monitor.html│                  └─────────────┘                └──────────────┘
-│  fetch+DOM)  │                         ▲                            │
-└──────────────┘                         │ 状态/心跳                    │ u2 操作
-       │                                 │                            ▼
-       │ JSON API                        │                   ┌─────────────────┐
-       ▼                          ┌──────────────┐           │ STF Device / adb │
-┌──────────────┐                  │  看门狗监控   │           └─────────────────┘
-│  web_server  │                  └──────────────┘
-│  (Flask API) │
-└──────────────┘
-       │
-       ▼
-┌──────────────┐
-│ data/users.db│  SQLite 持久化（用户/分组/任务/自定义动作/APK记录）
-└──────────────┘
-```
+理解启动顺序很关键——**很多副作用发生在 import 期**。

-### 任务执行流程
+### 2.1 阶段 A：import 期副作用（`web_server.py:6-25`）

-1. 前端创建 TaskJob（HTTP POST `/api/jobs`）
-2. `TaskManager` 保存到 SQLite，如启用 cron 则注册到 APScheduler
-3. 手动执行或 cron 触发时，`_run_job` 解析目标设备列表
-4. 每台设备起一个线程 `_run_with_retry`，含重试循环
-5. 线程内 `task.create_worker()` 创建 Worker，`worker.start()` 启动
-6. `BaseWorker.run()` 执行设备生命周期：占用 → 连接 → setup → run_task → teardown → 释放
-7. Worker 通过 `_update_status()` 实时上报状态到全局 `_WORKERS` 字典
-8. 前端轮询 `/api/status`（5 秒缓存）获取设备 + Worker 状态
+| 顺序 | 触发 | 副作用 |
+|------|------|--------|
+| 1 | `from core.task_manager import TaskManager` | 链式触发：`config.py` 模块体 → **读取根目录 `.env`**（`os.environ.setdefault`）；`core/logger.py` → 创建 `logs/`；`tasks/__init__.py` → **任务类型注册**（`@register_task` 在 import 期执行） |
+| 2 | `get_logger` / `core.models` | 得到 `db` / `init_db` / `User` |
+| 3 | `from config import WEB_HOST, WEB_PORT` | 读取端口常量 |
+
+> `.env` 是"import config 的副作用"，因此 `web_server.py:30` 读 `WEB_SECRET_KEY` 时它已生效。
+
+### 2.2 阶段 B~D：Flask 与领域对象
+
+| 阶段 | 位置 | 做了什么 |
+|------|------|---------|
+| **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** | `:60-67` | **恢复任务消费** `consume_pending_restore()`。SQLite 时代它必须在 engine 首次打开 `users.db` **之前**（Windows 无法替换被持有的文件）；改用 MySQL 后这一步的语义会变成"启动期事务替换"，见 §7 |
+| **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`（**刷一次 `serial→名称` 内存快照** + **起线程**：3s 后采集型号、另起 `device-names` 每 60s 刷名称）；`device_discovery.init_app`（**起常驻扫描线程**）；`device_battery.init_app`（**起常驻电量采集线程**）；`dedup.init_app`（**去重账本绑 app**，供任务线程/Web/清理自推 context）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)`；`notifier.set_device_name_resolver(device_pool.name_of)`（通知里显示设备名而不是 IP，见 [NOTIFY.md](NOTIFY.md) §7） |
+### 2.3 阶段 E~G：蓝图、巡检调度器、真正启动
+
+| 阶段 | 位置 | 做了什么 |
+|------|------|---------|
+| **E** | `:64-67` | `context.init(...)`；`register_blueprints(app)`（10 个蓝图）；`agent_api.set_app(app)`（供后台线程推 app context） |
+| **F** | 同上附近 | **第二个独立 APScheduler**：`CronTrigger(hour=3, minute=47)` 挂经验库巡检、`hour=4, minute=13` 挂步骤明细清理（`_purge_step_log`）、`hour=4, minute=23` 挂去重记录清理（`_purge_done_mark`，只清 `day`/`hours` 桶）、`hour=4, minute=41` 挂发布计划清理（`_purge_video_plan`：僵尸占位回收 + 过期行）、`hour=4, minute=47` 挂素材文件清理（`_purge_video_files`）——时间刻意错开（都是删数据的大操作），各任务自建 app context；失败仅 warning。**僵尸回收是必须有的一步**：占位后崩溃的行没有它会永远卡在"推送中"，再也不会被取到 |
+| **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()` + `device_battery.shutdown()` + 停 uiautodev |
+
+> ⚠️ **阶段 A~F 在 import 期就会起线程/调度器**，只有 uiautodev 拉起与预连接在 `__main__` 分支。以 WSGI 方式 import 本模块会得到"半个启动"的进程——本地调试请直接 `python web_server.py`。

 ---

-## 3. 核心模块详解
+## 3. 线程与并发模型

-### 3.1 STFClient（`core/stf_client.py`）
+### 3.1 常驻线程一览

-OpenSTF REST API 封装，负责设备池管理。
+| 名称 | 启动位置 | 职责 | 周期 |
+|------|---------|------|------|
+| Flask 请求线程 | `app.run(threaded=True)` | 每请求一线程 | — |
+| **任务调度器** `BackgroundScheduler` | `TaskManager.__init__` | cron 触发 / 停止任务 | 按 cron |
+| **巡检调度器** `BackgroundScheduler` | `web_server.py` | 经验库 AI 巡检 | 每日 03:47 |
+| `worker-watchdog` | `start_watchdog()` | `running/connecting` 心跳超时 → 标 `error` | 30s 检查 / 120s 阈值 |
+| `device-discovery` | `device_discovery.init_app` | 网段扫描 + 断联重连 | 首轮延迟 15s，之后 interval（默认 60s） |
+| `device-names` | `device_pool.init_app` | 刷 `serial → 名称` 内存快照（通知显示设备名用；只查库） | 60s（另有启动/增删改名时主动刷） |
+| `_refresh_models_bg` | `device_pool.init_app` | 启动后采集全部在线设备型号 | 一次性（3s 后） |
+| `device-battery` | `device_battery.init_app` | 采设备电量（`dumpsys battery` 只读）+ 低电量告警 | 首轮延迟 20s，之后 interval（默认 60s） |
+| `BaseWorker` × N | `TaskManager._run_with_retry` | 单设备任务执行 | 任务期 |
+| `_run_with_retry` × N | 同上 | 单设备重试循环 | 任务期 |
+| `fg-scan-once` | `_ForegroundScanner.scan_once` | 前台 App 扫描 | 手动触发，`Event` 防重入 |
+| `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 个 |

-**关键设计**：
- 所有请求带 `timeout=(5, 15)`，避免 STF 网关 504 时卡死
- `remote_connect` 带重试（3 次），STF provider 慢启动时需要
- 错误分类：`DeviceOfflineError`（不重试）/ `STFNetworkError` / `DeviceConflictError`（自动重试）
- 占用冲突自动清理重试（偶发 "already in use" 脏状态）
+两个 APScheduler 相互独立，时区均固定 `Asia/Shanghai`。

-**核心方法**：
+### 3.2 锁与并发保护

-| 方法 | 说明 |
-|------|------|
-| `list_all_devices()` | 返回 STF 上所有设备（含状态） |
-| `list_free_devices()` | 返回可占用的空闲设备 |
-| `list_my_devices()` | 返回当前账户已占用的设备 |
-| `occupy(serial)` | 占用设备（冲突自动重试） |
-| `release(serial)` | 释放设备（含远程断开） |
-| `remote_connect(serial)` | 建立远程 ADB 隧道，返回 remoteConnectUrl |
-| `remote_disconnect(serial)` | 断开远程 ADB 隧道 |
+| 锁 | 位置 | 保护对象 | 说明 |
+|----|------|---------|------|
+| `_ADB_LOCK` | `core/adb_helper.py` | adb connect 串行化 | connect 很快，串行不影响整体并发；不覆盖长命令 |
+| `_WORKERS_LOCK` | `core/device_worker.py` | 全局设备状态表 `_WORKERS` | "检查+更新"在同一锁内，避免与任务启动竞态 |
+| `TaskManager._lock` | `core/task_manager.py` | `_running` / `_stop_requested` | **抢占时禁止在锁内调 `stop_device`（死锁）** |
+| `_engine_lock` | `core/ocr.py` | OCR 引擎懒加载 + 推理串行 | 推理 0.2~0.5s，锁开销可忽略 |
+| `_scan_lock` / `_stop_event` | `core/device_discovery.py` | 定时/手动扫描互斥 | `acquire(blocking=False)` |
+| `_status_cache_lock` | `core/task_manager.py` | 状态缓存（TTL 5s） | 避免 `/api/status` 每次都查库 + adb |
+| `device_battery._lock` | `core/device_battery.py` | 电量缓存 `_cache` + 告警档位 `_tiers` | 采集线程 / `/api/status` / 告警状态机共用 |

-### 3.2 STFDevice + BaseWorker（`core/device_worker.py`）
+**无锁部分**：`device_pool` 与 `models` 不持显式锁，依赖"每次操作独立 app context" + 数据库自身的并发控制（MySQL 下是 InnoDB 行锁 + READ COMMITTED，回退 SQLite 时是 WAL + `busy_timeout=5000`）。

-**STFDevice** — 单设备生命周期管理：
- `acquire()`：占用 → remoteConnect → adb connect
- `release()`：adb disconnect → remoteDisconnect → STF release
- 直连模式：serial 为 `IP:5555` 时直接 adb connect，不走 STF 桥接
+### 3.3 错峰与心跳

-**BaseWorker** — 通用 Worker 基类（继承 threading.Thread）：
+- **错峰启动**：`_START_STAGGER_SEC = 0.2`，第 i 台设备延迟 `i × 0.2s` 启动（100 台 ≈ 20s 铺开），避免批量触发时的 adb 连接风暴。
+- **心跳看门狗**：任何状态写入都会刷新 `last_heartbeat`；`running/connecting` 设备超过 120s 无心跳 → `status="error"` + `last_error="心跳超时…"`。长耗时的业务循环必须周期性 `self.heartbeat()`（`set_action` / `set_progress` 也会刷新）。
+- **单实例约束**：同一 serial 同时只有一个 worker（`TaskManager._running`）；重复触发同任务跳过，不同任务未开抢占也跳过。

-```
-run() 主循环（不要重写）：
-  1. acquire 设备
-  2. u2.connect（30s 超时保护）
-  3. setup(d)        ← 子类可选钩子
-  4. run_task(d)     ← 子类必须实现
-  5. teardown(d)     ← 子类可选钩子
-  6. finally: release 设备
-```
+---

-**超时保护**：
- `u2.connect()` 用 `ThreadPoolExecutor + 30s 超时`，防止 atx-agent 无响应永久 hang
- `d.info` 用 `ThreadPoolExecutor + 10s 超时`
+## 4. 设备生命周期

-**心跳看门狗**（`_Watchdog`）：
- 后台线程，每 30 秒扫描一次
- Worker 超过 120 秒无心跳 → 标记 `error`
- 防止设备被占用却不干活
+### 4.0 设备身份：名称 + 指纹（2026-09-11）

-**全局状态注册表**（`_WORKERS`）：
- `serial -> status dict`，线程安全（`_WORKERS_LOCK`）
- 供 `web_server` 读取实时状态，前端通过 `/api/status` 展示
+设备池原以 **serial（IP）当身份**，设备一换 IP 旧记录就成了连不上的"僵尸条目"，分组与
+serial 模式的任务还吊着死地址。现在拆成三层：

-### 3.3 TaskManager（`core/task_manager.py`）
+| 概念 | 是否稳定 | 作用 |
+|------|---------|------|
+| `name`（名称，**必填唯一**） | 稳定 | 人可读身份；分组/任务/日志按名称认设备 |
+| `fingerprint`（`ro.serialno`） | 稳定 | **机器识别**：认出"这是同一台设备" |
+| `serial`（IP:5555 / USB 序号） | **可变** | 当前连接地址 |

-统一管理：任务类型注册、设备分组、任务计划、定时调度、重试、持久化。
+**认领**（`device_pool.claim_device` 自动 / `relocate_device` 人工）：指纹命中或人工指认后，
+把旧记录迁到新地址（名称/型号/备注/启用状态/添加时间全保留）并同步引用。

-**核心组成**：
+> ⚠️ **引用同步必须同时改库与内存**：分组、任务在 `TaskManager` 里还有一份内存副本，
+> **调度用的是内存对象**——只改库不重启不生效（表现为"分组里少一台、任务仍跑向旧地址"）。
+> 因此 `device_pool` 迁址后回调 `TaskManager.sync_device_serial`，由装配层用
+> `device_pool.set_move_hook(...)` 注册；`device_pool` 不能反向 import `task_manager`（循环依赖）。

-| 组件 | 说明 |
-|------|------|
-| `scheduler` | APScheduler BackgroundScheduler，cron 触发任务 |
-| `groups` | 设备分组（内存业务对象，持久化到 SQLite） |
-| `jobs` | 任务计划（内存业务对象，持久化到 SQLite） |
-| `_running` | 运行中的 worker（serial -> worker 信息） |
-| `_stop_requested` | 用户请求停止的 serial 集合（阻止后续重试） |
-| `_fg_scanner` | 前台 App 扫描器（不打扰设备） |
+### 4.1 入池（三条路径）

-**调度模式**：
- `once`：不注册 cron，手动执行
- `cron`：注册启动 cron，到点启动所有目标设备
- `cron_stop`：注册启动 cron + 停止 cron，到点停止本任务 worker
-
-**重试策略**：
- `DeviceOfflineError`：立即放弃，不重试（设备掉线短时间不会自愈）
- 其他异常：按 `retry.max_attempts` 重试，间隔 `retry.delay`
- 临时错误（端口耗尽）：退避 max(delay, 120s)
- 用户停止：加入 `_stop_requested`，阻止任何后续重试
-
-**并发控制**：同一 serial 同时只允许一个 worker，避免冲突。
-
-**状态缓存**：`get_status()` 带 5 秒缓存，STF 请求慢时不阻塞前端。
-
-### 3.4 前台 App 扫描器（`_ForegroundScanner`）
-
-**设计原则：不打扰设备**，扫描不会让设备退出当前 App。
-
-| 设备状态 | 处理方式 | 是否打扰 |
-|---------|---------|---------|
-| worker 运行中 | 复用已有 ADB 连接查询 | 否 |
-| 自己占用无 worker | STF remoteConnect 隧道查询 | 否 |
-| 完全空闲 | 返回"空闲"（不 adb connect，避免 STF 误判离线） | 否 |
-| 他人占用 | 标记"(他人占用)" | 否 |
-
-> **为什么不扫描空闲设备的前台 App**：STF provider 内部通过 IP:5555 维持 adb 连接。外部 adb connect/disconnect 会让 adb server 断开该 transport，连带 STF provider 的连接断开，STF 误判设备 offline 并触发重连。
-
-### 3.5 ADB 操作（`core/adb_helper.py`）
-
-**全局锁串行化**：`_ADB_LOCK` 确保所有 adb 调用串行执行，避免多线程竞争 adb server。
-
-**铁律：绝不 kill-server**：
- `adb kill-server` 会断开所有设备的 adb transport
- 导致 STF provider 对全部设备误判离线并触发重连
- 影响所有运行中的任务
-
-| 函数 | 说明 |
-|------|------|
-| `adb_connect(url, retries=5)` | adb connect（带重试，绝不 kill-server） |
-| `adb_connect_light(url)` | 轻量 connect（单次尝试，扫描专用） |
-| `adb_disconnect(url)` | adb disconnect |
-| `screenshot(serial)` | 截图（adb exec-out screencap -p，只读安全） |
-| `get_foreground_app(url)` | 获取前台 App 包名（dumpsys window） |
-| `identify_device(serial)` | 让设备响铃识别 |
-
-### 3.6 数据模型（`core/models.py`）
-
-SQLAlchemy 模型，存于 `data/users.db`：
-
-| 模型 | 表名 | 说明 |
+| 路径 | 入口 | 过程 |
 |------|------|------|
-| `User` | user | 后台用户（Flask-Login 认证，SHA256 密码） |
-| `DeviceGroup` | device_group | 设备分组（serials 存 JSON） |
-| `TaskJob` | task_job | 任务计划（target/params/schedule/retry 存 JSON） |
-| `CustomAction` | custom_action | 自定义动作（步骤打包，steps 存 JSON） |
-| `ApkFile` | apk_file | APK 文件元信息 |
+| 手工添加 | `POST /api/devices/pool/add` | `device_pool.add_device`（upsert）→ 有 `:` 则 `adb connect` → 后台采集型号 |
+| 自动发现确认 | `POST /api/devices/discovery/confirm` | 扫描写 `pending_device` → 确认后 `add_device` + 删 pending + connect + 采型号 |
+| 启动预连接 | `_preconnect_pool_devices()` | 进程启动时并发 connect 池内网络设备（仅 `IP:5555`） |

-**数据库初始化**（`init_db`）：
- 创建所有表
- 首次启动创建默认管理员 `admin/admin123`
- 自动迁移旧 `groups.json` / `jobs.json` 到 SQLite（迁移后归档为 `.migrated`）
+> 任何一条入池路径在设备可连时都会读取**设备指纹**；指纹命中池中已有设备 = 同一台换了地址
+> → 走**认领**（§4.0），不新增记录。

-### 3.7 APK 管理（`core/apk_manager.py`）
+断联设备的自动重连由发现线程每轮执行（只重连 `IP:5555`）。

-APK 上传/解析/批量安装。
+### 4.2 可用性判定

-**设备连接策略（直连，绕过 STF）**：
- 直接 `adb connect serial`（serial 是 IP:5555）
- 不经过 STF occupy/release，避免 STF release 触发 agent 清理卸载 app
- 安装后不主动 disconnect（STF provider 共享该 adb transport）
+```
+list_configured()   设备池中 enabled=True 的 serial
+list_online()       本机 adb devices 中 state=device（池内有 USB 设备时并查 220 远程 adb server）
+list_ready()        两者交集 ← 调度 "all" 模式取这个
+```

-**安装流程**：
-1. 上传 APK → 保存到 `data/apks/` → pyaxmlparser 解析包名/版本 → 入库
-2. 批量安装 → 后台线程 → 每台设备直连 adb install → 验证包名
-3. 跳过 worker 运行中的设备（避免打断任务）
+### 4.3 执行期状态字段

-### 3.8 元素抓取（`core/uiauto_helper.py`）
+设备状态存在内存注册表 `_WORKERS[serial]`（**不落库，重启即清零**）：

-封装 uiautodev 本地服务（端口 20242）的客户端。
-
-| 函数 | 说明 |
+| 字段 | 含义 |
 |------|------|
-| `is_running()` | 探测 uiauto2 服务是否运行 |
-| `list_devices()` | 获取 uiauto2 已连接的设备列表 |
-| `get_screenshot(serial)` | 获取设备截图（JPEG） |
-| `get_elements(serial)` | 获取设备 UI 元素树（扁平化列表） |
+| `status` | `idle` / `connecting` / `running` / `done` / `error` / `released` / `failed` |
+| `serial` / `model` / `device_name` | 标识 |
+| `task_job` / `attempt` / `max_attempts` | 当前任务与重试进度 |
+| `current_action` / `progress` | 当前动作与进度（前端直接渲染） |
+| `last_error` / `last_warning` | 最近错误 / 选择器健康告警 |
+| `last_heartbeat` / `end_time` | 看门狗与时长上限 |
+| `present` / `ready` | 是否在线（对外 `/api/status` 字段） |

-元素树解析：递归提取每个节点的 `resource-id/text/content-desc/class/bounds` 等属性，并推荐最佳选择器（优先 xpath）。
+### 4.4 状态迁移
+
+**Worker 侧**（`BaseWorker.run`）：
+
+```
+connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ setup ──▶ run_task ──▶ teardown
+                                                                    │
+                                     未被 stop ──▶ done             │
+                                     异常 ──▶ error（DeviceOfflineError 单独分类，不重试）
+                                     finally ──▶ 仅当仍为 running/connecting 时置 released
+```
+
+> `finally` 里的状态判断是为了**不覆盖业务结果**（`done`/`error` 必须保留）。
+
+**调度侧**（`_run_with_retry`）：worker 结束后读 `status` → `done` 即成功返回；否则按 `max_attempts` 重试（`[transient]` 错误额外加长退避）→ 重试耗尽置 `status="failed"`，并把**真实失败原因**拼进 `last_error`（截断 200 字符）。
+
+### 4.5 释放
+
+`STFDevice.release()` 是**空实现**——直连模式下**绝不 disconnect**（共享 adb transport 红线）。类名 `STFDevice` / `STFError` 是 STF 时代的历史命名，功能上已与 STF 无关。

 ---

-## 4. 任务系统设计
+## 5. 任务调度链路

-### 4.1 注册机制
+### 5.1 完整调用链

 ```
-tasks/__init__.py
-  ├── from .base import BaseTask, register_task, list_task_types, get_task_class
-  ├── from .douyin import task    # 触发 @register_task
-  └── from .generic import task   # 触发 @register_task
+① 注册   add_job / update_job / toggle_job
+         → _add_cron：scheduler.add_job(_on_cron_trigger, CronTrigger.from_crontab(...),
+                                       id=f"job_{id}_start", replace_existing=True)
+         （cron_stop 额外注册 job_{id}_stop；启动时 _load() 为 enabled 任务重注册）
+
+② 触发   APScheduler → _on_cron_trigger(job_id)
+         → 任务存在？→ _in_run_window(schedule)？→ _run_job(job)
+
+③ 解析   job.resolve_serials(self)     # all=池内在线 / group=分组∩池 / serial=指定
+         → 为空则 warning 返回
+
+④ 任务类 get_task_class(job.task_type) → 未知则 error 返回（run_job_now 会直接报错）
+         → task_cls()；max_attempts = max(1, retry.max_attempts)
+
+⑤ 铺开   对每台设备起线程 _run_with_retry(task, serial, job, ..., idx * 0.2s)
+
+⑥ 单设备 _run_with_retry：
+         sleep(错峰) → 停止检查 → 单实例/抢占判定 → 登记 _running[serial]
+         → _update_status(task_job=..., attempt=...)
+         → worker = task.create_worker(serial, job.params)
+         → worker.start() → worker.join()
+         → 读 status：done 成功；否则重试（[transient] 退避 max(delay,120)s）
+         → 耗尽：status="failed" + last_error（含真实原因）
+         → finally：清停止标志；本任务若是抢占任务则归还设备（重跑被抢占任务）
+
+⑦ 上报   worker 内 _update_status → 内存注册表
+         → TaskManager.get_status（5s 缓存）
+         → _merge_status（合并池信息、清理陈旧条目）
+         → GET /api/status → 前端 5s 轮询渲染
+
+⑧ 停止   stop_device / stop_all → _stop_requested.add + worker.stop()（置 Event）
+         业务循环检查 self.stopped()
+
+⑨ 下次运行时间 next_run_of → _next_run_time（考虑运行窗口，最多向后探测 200 次）
 ```

-`@register_task` 装饰器将 Task 类注册到全局 `_TASK_TYPES` 字典，key 为 `task_type` 字符串。
+### 5.2 抢占机制

-### 4.2 参数深合并
-
-Job 下发时只传需要覆盖的字段，调度器做三层合并：
-
-1. **顶层字段**：Job params 覆盖 DEFAULT_PARAMS
-2. **actions 字段**：参数级深合并
-   - 前端没传的 action → 用默认
-   - 前端传了 → `enabled` 和 `params` 分别合并
-   - `params` 再深合并一层（保留前端没传的子参数）
-
-示例：只想改点赞概率，Job params 只需：
-```json
-{"actions": {"like": {"params": {"rate": 0.5}}}}
-```
-
-### 4.3 Action 系统
-
-每个 App 有独立的 Action 注册表（`create_action_registry()`），互不污染。
-
-```
-core/actions/base.py        — BaseAction 全局基类 + should_trigger + register_action
-tasks/douyin/actions/base.py — ACTIONS = create_action_registry() + list/get 函数
-tasks/douyin/actions/like.py — @register_action(ACTIONS) LikeAction
-```
-
-**循环导入坑**：`actions/__init__.py` 必须先 `from .base import ACTIONS`，再 `from . import like`。
+任务参数 `preempt=true` 时：`all` 模式目标集合变为"全部在线池内设备"（含正在跑的）；遇到设备已被占用时在**锁外**调 `stop_device` 并最多等 30s 接管；本任务结束后自动重新启动被抢占的任务（`preempted_job` 必须定义在重试循环外，否则归还信息会丢）。

 ---

-## 5. 前端设计
+## 6. 前端架构

-### 5.1 单页应用
+### 6.1 单页应用

-`templates/admin/monitor.html` 是纯 HTML+CSS+JS 单页应用，无框架依赖。
+- 主页面 `templates/admin/monitor.html`：一个内联 `<style>` + 8 个 Tab 面板 + 10 个模态框容器 + 17 个 `<script src>`
+- 独立页面：`login.html`（登录）、`wall.html`（监控大屏，**完全自包含**，自带 CSS/JS，不加载 `static/admin/*.js`）
+- 服务端内联页：`GET /locate`（设备端定位大字页，免登录）
+- 响应头强制 `no-store`，避免后台改版后浏览器拿旧页面

- **Tab 切换**：5 个 Tab（监控/任务/分组/日志/用户），纯 DOM 操作
- **数据获取**：`fetch()` 调 JSON API，5 秒轮询 `/api/status`
- **状态渲染**：设备表格、任务卡片、进度条、徽章，纯 DOM 操作
+### 6.2 Tab 与子分栏

-### 5.2 步骤编辑器
+| 顶级 Tab | `data-tab` | 权限 | 子分栏 |
+|---------|-----------|------|--------|
+| 监控 | `monitor` | 登录即可 | — |
+| **发布计划** | `plan` | `devices` | 上传视频与标题（按**名字**配对）、时间线、推送到手机、导出链接 + **发布任务就地编辑**（见 [DATA_MODEL.md](DATA_MODEL.md) §2.11）。2026-10-12 起「账号台账」整页下线（表保留），本页从「账号」页的子分栏升为一级页签 |
+| 任务 | `tasks` | 登录即可（写操作需 `tasks`） | `plan` 任务计划 / `actions` 自定义动作 / `actioncfg` 动作配置 / `dedup` 去重记录 |
+| 日志 | `logs` | `logs` | — |
+| 用户 | `users` | `admin` | — |
+| 工具 | `tools` | `admin` | `clipboard` / `adb` / `ts` / `apks` / `appver` / `devapps` / `devpool` / `groups` |
+| AI 控制台 | `agent` | `admin` | — |
+| 系统 | `system` | `admin` | `backup` 数据备份 / `restore` 导入恢复 / `notify` 通知 Webhook |

-`generic_steps` 任务的步骤编辑器：
- 左侧操作库（拖拽源）
- 中间画布（步骤卡片列表，HTML5 Drag API 排序）
- 每个步骤卡片可展开参数表单
- 选择器字段旁有"抓取元素"按钮（独立模态框）
+子分栏会记住上次选中位置（`_activeSubs`）；`devpool` 子分栏自带 10s 轮询，切走即停。

-### 5.3 元素抓取模态框
+### 6.3 JS 分工

-独立的第二层模态框（`el-picker-overlay`，z-index 1100），不影响任务编辑窗口：
-1. 选择设备 → 2. 加载截图 + 元素树 → 3. 点击元素/边界框 → 4. 回填选择器
+| 文件 | 职责 | 备注 |
+|------|------|------|
+| `base.js` | esc / CSRF / 权限 / API 封装 / Toast / Tab 与子分栏切换 / 模态框 / 常量表 | 所有模块的公共底座 |
+| `markdown.js` | 轻量 Markdown 渲染（`renderMarkdown`） | 无 CDN 依赖；**先转义再套标记** |
+| `list.js` | 统一列表组件：搜索 + 分页 + 排序 | 状态注册表 `_LIST_PAGERS`；`setListPager` **不重置**页码/搜索/排序（避免轮询刷新打断用户） |
+| `release.js` | 发布计划页（时间线按日期分组 / 多选**素材（视频/图片）**串行上传 + 逐文件进度与结果 / 标题+正文 txt 上传（`标题 || 正文_名字_日期_编号`，卡片与明细**以名字为主**）/ 推送到手机 + **一键推送**（当天全部，**按名字找设备**：实时探测哪台在线设备登着这个号，逐条报出"没有设备登着"的号）、相册校验徽章与裁决 / 链接复制与导出 CSV / **发布任务的就地编辑**） | 服务层 `core/video_plan.py`（实时探测在 `core/account_probe.py`）；上传前把队列**按文件名排序**并让用户确认解析结果（顺序 = "无编号按顺序配"的依据）。就地编辑只放常用字段（名字/目标/时间/启停/逐步参数 + 抓取元素），更复杂的编排走「打开通用编辑器」→ `openTaskModal`；步骤路径里 `then/else/children` 在**步骤的 params 下**（`_rpWalk`），走错这一层会把分支当数组下标用 |
+| `monitor.js` | 监控页：设备表（含**电量列**，按 `battery.tier` 上色）、批量操作、异常汇总、任务概况卡片（含覆盖设备 chip） | 5s 轮询 + 脏检查（签名不变不重渲染） |
+| `editor.js` | 步骤编辑器（拖拽 / 参数表单 / 条件分支 / 元素抓取 / 测试此步骤）+ `saveTask` | 最大的前端文件；`_stepEditor` 单例；设备选择卡 `_devCard` 供「抓取元素」「测试此步骤」共用（**名字优先**，型号·地址作副标题） |
+| `tasks.js` | 任务 Tab：任务 CRUD / 调度解析 / 运行窗口 + 自定义动作 | |
+| `tools.js` | 工具 Tab：剪贴板、adb 终端、Tailscale、设备池、自动发现、远程看屏、**电量监控配置**（阈值/间隔/立即采集） | 电量表单只回填一次，10s 轮询不冲掉用户正在输的值 |
+| `dedup.js` | 任务 Tab·**去重记录**：账本列表 + 统计（"今天做了几个号"）+ 删单条/清空任务 | 数据来自 `done_mark` 表，见 [TASK_DEV.md](TASK_DEV.md) §4.6 |
+| `apps.js` | 应用管理：APK 上传/安装/删除、设备已装应用 | |
+| `admin.js` | 分组、日志、用户 + **全局初始化入口**（末尾 `initCsrf(); loadMe(); showTab('monitor')`） | |
+| `agent.js` | AI 控制台·聊天：会话、SSE 流、Markdown / 推理链 / token 渲染、实时画面、经验库 / 动作库 | |
+| `taskgen.js` | AI 控制台·**AI 建任务**子页：发起探索、回放工具卡、草稿预览（步骤树/提醒/证据）、打开步骤编辑器预填 | 运行槽与聊天共用，按 `mode` 互斥订阅事件流 |
+| `system.js` | 系统 Tab：备份导出 / 导入预览与应用 | |
+
+加载顺序见根 [README](../README.md)；都是全局脚本（非 ES module），靠加载顺序保证依赖。
+
+### 6.4 实时通道
+
+| 通道 | 场景 | 机制 |
+|------|------|------|
+| **轮询** | 设备状态（5s）、日志（3s，可关）、自动发现（10s）、截图（3s）、APK 安装（3s）、AI 运行状态（8s） | `setInterval`，切 Tab 时统一清理 |
+| **SSE** | AI 控制台一轮会话 | `EventSource /api/agent/stream`；`onerror` **刻意不结束运行**，靠自动重连 + 服务端事件队列补发 |
+| **MJPEG** | 实时看屏 | `img.src = /api/screen/stream?...`，浏览器原生长连接 |
+
+### 6.5 前端权限
+
+三条并存：① `data-perm` 属性（`loadMe()` 时统一隐藏无权限元素）；② `_can(perm)`（动态拼 HTML 时决定是否出按钮）；③ 后端装饰器兜底（403）。
+
+> 前端隐藏只是体验优化，**安全完全依赖后端**；`data-perm` 只在页面加载时求值一次，改权限后需刷新页面。

 ---

-## 6. 关键设计决策
+## 7. 关键设计决策

-### 6.1 为什么用 SQLite 而不是 JSON 文件
-
- 支持用户/分组/任务的关系存储
- 并发安全（WAL 模式）
- 迁移旧 JSON 时归档为 `.migrated`，避免删空后重启又复原
-
-### 6.2 为什么用 threading 而不是 asyncio
-
- uiautomator2 是同步阻塞库，不适合 asyncio
- 多设备并发用多线程即可，每台设备一个 Worker 线程
- Flask `threaded=True` 处理并发 HTTP 请求
-
-### 6.3 为什么绝不 kill-server
-
-`adb kill-server` 会断开所有设备的 adb transport，导致 STF provider 误判全部设备离线并触发重连。连接失败就返回 False，由调用方处理。
-
-### 6.4 为什么状态查询带缓存
-
-STF API 响应慢（设备多时 2-5 秒），每次 `/api/status` 都打 STF 会阻塞 Flask。带 5 秒缓存，Worker 状态实时读内存（无 IO）。
-
-### 6.5 为什么 DeviceOfflineError 不重试
-
-设备掉线后短时间内不会自愈，重试只会浪费配额并阻塞调度器。让设备进入冷却，由运维/STF 恢复后再启用。
+| 决策 | 为什么 | 代价 / 注意 |
+|------|--------|------------|
+| **数据库走 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 的历史坑，清单可控 | 需自己处理在线状态、型号、自动发现 |
+| **备份"重启生效"** | 调度器 / worker / 设备池都把任务与设备**缓存在内存**里，整库替换后内存副本全部失效 | 导入后必须重启（重启时消费恢复任务）。SQLite 时代还有"Windows 无法替换被持有的文件"这层原因，改用 MySQL 后只剩内存态这一层 |
+| **uiautodev 独立子进程** | 元素抓取是重活，隔离崩溃、可单独重启 | 固定端口 20242；PID 文件防重复拉起（杀之前必须校验 cmdline，防误杀同容器进程） |
+| **MCP 独立端口** | 外部 AI 用标准协议接入，不侵入 Web 会话 | MCP 端点自身无鉴权，靠网络隔离；写操作用开关门控 |

 ---

-## 7. 线程模型
+## 8. 技术红线与实现位置

-```
-主线程（Flask）
-  ├── HTTP 请求处理（threaded=True，每请求一线程）
-  ├── APScheduler 线程（cron 触发）
-  ├── 看门狗线程（_Watchdog，30s 间隔）
-  ├── uiautodev 子进程
-  └── Worker 线程（每台设备一个）
-        ├── _run_with_retry 线程（重试循环）
-        └── BaseWorker 线程（设备生命周期 + run_task）
-```
+| 红线 | 为什么 | 代码里的体现 |
+|------|--------|-------------|
+| **绝不 `adb kill-server`** | 会断掉所有设备的 adb transport，运行中任务全废 | `adb_helper` 只 connect 不 kill；Web 层硬拦截 `kill-server` / `disconnect` 字符串 |
+| **绝不对 `IP:5555` 设备 `disconnect`** | 该地址的 adb transport 是共享的 | `adb_disconnect` 全项目**零调用方**；`STFDevice.release()` 空实现 |
+| **空闲设备扫描不碰 adb** | 避免扰动共享连接 | 前台扫描对空闲设备直接返回"空闲"；设备发现用 socket 探测而非 adb |
+| **adb key 不变** | 设备信任当前 key，换 key 全部变 unauthorized | 部署沿用既有 `~/.android/adbkey` |
+| **生产只读原则** | 220 是生产机 | 任何写操作（重启 / pull / 改文件）都需负责人确认 |
+| **备份覆盖清单** | 漏登记 = 等于没备份 | `core/system_backup.py` 的 `SUMMARY_TABLES`，导出/导入双向自检（见 [DATA_MODEL.md](DATA_MODEL.md) §6） |
+| **文档同步** | 文档落后会误导开发与运维 | 功能/配置/接口改动的同一个 commit 里更新 `doc/`（索引见 [doc/README.md](README.md)） |

-**线程安全**：
- `_WORKERS_LOCK`：保护全局 worker 状态字典
- `_ADB_LOCK`：串行化所有 adb 调用
- `TaskManager._lock`：保护运行中任务字典
- `_ForegroundScanner._cache_lock`：保护前台 App 缓存
+---
+
+## 9. 已知问题与"坑"
+
+### 9.1 代码缺陷（截至 2026-09-10，详见 [backlog/TODO.md](backlog/TODO.md)）
+
+| 问题 | 现象 | 位置 |
+|------|------|------|
+| `GET /locate` 返回 500 | 设备定位大字页打不开（NameError：`render_template_string` / `_esc` 未导入） | `web/monitor.py` |
+| `POST /api/device/locate`（`show=true`）失败 | 在设备浏览器打开定位页那步抛异常（`urllib` 未导入），被转成 502 | `web/monitor.py` |
+| CSRF 未实际启用 | 前端会取并携带 `X-CSRF-Token`，但服务端**没有注册** `before_request` 校验 | `web_server.py` 只 import 了 `_csrf_protect` |
+| 回归脚本在 Windows 不可用 | `scripts/regression_test.py` 用了 `signal.alarm`（Windows 无此 API），直接报错退出 | `scripts/regression_test.py` |
+| 前端 `--card-line` 未定义 | AI 控制台相关深色容器边框失效（该变量只在 wall.html 定义） | `templates/admin/monitor.html` 的 `:root` |
+| `countParts` 未定义 | 进度为 0 时可能抛 ReferenceError（被上层 try/catch 吞掉，用户无感） | `static/admin/monitor.js` |
+
+### 9.2 代码里写明的坑（改代码前务必读）
+
+| 坑 | 说明 |
+|----|------|
+| **跨线程访问 DB 必须自推 app context** | 后台线程用 `with app.app_context()`（各模块 `_ctx()` / `_db()` 已封装） |
+| **`debug=False` 不热重载** | 改 `core/`、`tasks/` 后必须重启；改 JS 需强刷浏览器 |
+| **Windows adb 输出不能用 `text=True`** | adb 输出含非 GBK 字节会崩；必须收 bytes 再解码 |
+| **`u2.connect` / `d.info` 可能永久 hang** | 必须放 `ThreadPoolExecutor` 里加超时 |
+| **Windows TCP 端口耗尽（WinError 10048）** | 属临时错误，重试需更长退避（代码识别后打 `[transient]`，退避 `max(delay,120)` 秒） |
+| **抢占时不能在锁内 `stop_device`** | 会死锁 |
+| **`preempted_job` 必须在重试循环外** | 否则被抢占任务永不归还 |
+| **删除任务/分组必须显式删行** | 只 upsert 的话，重启会从库里"复活" |
+| **旧 JSON 迁移后必须归档** | 否则用户删空数据后重启又复原 |
+| **XPath 位置谓词语义** | `//*[@id="x"][k]` = 父节点下第 k 个；`(//*[@id="x"])[k]` = 第 k 个匹配。抓取器生成后者，执行器会自动纠正历史写法 |
+| **容器重启后 PID 会被复用** | 杀残留 uiautodev 前必须校验 `/proc/<pid>/cmdline`，否则可能误杀同容器进程 |
+| **`.env` 用 `setdefault` 注入** | 真实环境变量优先于 `.env` |
+| **备份必须重启才生效** | 恢复任务在 `init_db` 之前被消费 |
+
+---
+
+## 10. 扩展点（改哪里）
+
+| 想做什么 | 改哪里 | 别忘了 |
+|---------|--------|--------|
+| 加一种步骤类型 | `tasks/generic/task.py` 的 `STEP_TYPES` + `_exec_<type>`；`static/admin/editor.js` 的 `STEP_LIB` | 两处保持一致；更新 [TASK_DEV.md](TASK_DEV.md) |
+| 加一个专属任务类型 | `tasks/<app>/`（照 `tasks/generic/` 结构）+ `tasks/__init__.py` 注册 | 重启生效；更新 [TASK_DEV.md](TASK_DEV.md) |
+| 加一个 HTTP 接口 | 对应功能域的 `web/xxx_api.py` | 加鉴权装饰器；更新 [API.md](API.md) |
+| 加一个蓝图 | 新建 `web/xxx_api.py` + 在 `web/__init__.py` 注册 | 更新 [API.md](API.md) 与本文 §1 |
+| 加一张表 | `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) 配置速查 |
@@ -0,0 +1,472 @@
+# 数据模型（DATA_MODEL）
+
+> 适用读者：改后端 / 排数据问题的开发者与运维。
+> 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)（运行时架构）、[DEPLOY.md](DEPLOY.md) §数据备份（备份覆盖红线）、[API.md](API.md)（消费这些数据的接口）。
+> **表结构以 `core/models.py` 的 ORM 模型为唯一准**（2026-09-13 起各模块的裸建表 SQL 已全部并入模型），本文是它们的映射说明。
+
+---
+
+## 1. 总览
+
+| 项 | 值 |
+|----|----|
+| 引擎 | MySQL（正式用法；目标由 `.env` 的 `DEPLOY_ENV` + `DB_*` 决定）／SQLite（回退模式，`DB_HOST` 为空时） |
+| driver | Flask-SQLAlchemy（SQLAlchemy 2.x）+ PyMySQL |
+| 连接参数 | 见 `core/db_config.py`：utf8mb4、排序规则 `utf8mb4_bin`、`pool_pre_ping`、`pool_recycle=1800`、隔离级别 READ COMMITTED、`sql_mode=STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION` |
+| SQLite 回退时的 PRAGMA | `journal_mode=WAL`、`busy_timeout=5000`、`synchronous=NORMAL`（监听器按连接类型守卫，MySQL 连接不会执行） |
+| 建表方式 | **唯一真相是模型**：`db.create_all()`（建缺表）+ `_sync_columns()`（补缺列）；`SCHEMA_MIGRATIONS` 只作版本账本与数据回填 |
+| 库位置 | MySQL：由 `DB_HOST/DB_NAME` 指定；SQLite：`data/users.db` |
+| 当前 schema 版本 | `app_meta.schema_version = 11`（迁移清单见 `core/models.py` 的 `SCHEMA_MIGRATIONS`：建表/补列以模型为准，这里只作版本账本） |
+
+**环境与库的绑定**（防混库，见 [DEPLOY.md](DEPLOY.md) §2.2）
+
+| `DEPLOY_ENV` | 期望库名 | 用途 |
+|---|---|---|
+| `dev` | `auto_control_dev` | 本地开发 |
+| `prod` | `auto_control` | 正式环境（220 容器） |
+
+启动时校验「`.env` 声明」与「库名」「库中登记的 `app_meta.deployment_env`」三方一致，不符**拒绝启动**。
+
+**表清单（17 张，全部是 `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；**唯一有无界增长风险的表**，靠保留期清理） |
+| 15 | `done_mark` | 去重账本：跨设备"已做过"标记（见 §2.9；本清单此前漏列，2026-09-24 补上） |
+| 16 | `device_account` | **已停用**：账号台账（见 §2.10；2026-10-12 起页面/接口/任务依赖全部下线，**表和 42 行历史数据保留、仍在备份内**，可回滚） |
+| 17 | `video_plan` | 视频发布计划：**名字** × 发布日期 × 编号 → 素材 + 标题/正文 + 发布状态 + 分享链接（见 §2.11） |
+
+> 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），且都是「空值不参与唯一约束」的语义。
+
+---
+
+## 2. 模型表（`core/models.py`）
+
+### 2.1 `user` — 登录用户
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | Integer | — | 主键 |
+| `username` | String(80) | — | **唯一**，非空 |
+| `password_hash` | String(255) | — | werkzeug 加盐哈希；兼容旧裸 SHA-256（校验通过后自动升级） |
+| `is_admin` | Boolean | `True` | 管理员不受权限位限制 |
+| `perms` | Text | `"[]"` | JSON 数组：`tasks` / `devices` / `apks` / `logs` |
+
+方法：`get_perms` / `set_perms` / `has_perm` / `set_password` / `check_password`。
+
+### 2.2 `device_group` — 设备分组
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | Integer | — | 主键 |
+| `name` | String(80) | — | **唯一**，非空 |
+| `serials` | Text | `"[]"` | 组内设备 serial 的 JSON 数组 |
+| `description` | Text | `""` | 备注 |
+
+### 2.3 `task_job` — 任务计划
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | String(32) | — | 主键，uuid 前 8 位 |
+| `name` | String(120) | — | 非空 |
+| `task_type` | String(60) | `"generic_steps"` | 必须已注册 |
+| `target` | Text | `'{"mode":"all"}'` | JSON |
+| `params` | Text | `"{}"` | JSON（与任务类默认值合并后使用） |
+| `schedule` | Text | `'{"mode":"once"}'` | JSON |
+| `retry` | Text | `'{"max_attempts":1,"delay":60}'` | JSON |
+| `enabled` | Boolean | `True` | 是否参与调度 |
+
+### 2.4 `custom_action` — 自定义动作
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | String(32) | — | 主键 |
+| `name` | String(120) | — | 非空 |
+| `icon` | String(4) | `"📦"` | 展示图标 |
+| `steps` | Text | `"[]"` | JSON，schema 与 `generic_steps` 的 `params.steps` 一致 |
+| `created_at` | String(20) | `""` | 时间串 |
+
+### 2.5 `apk_file` — APK 记录
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | String(32) | — | 主键；磁盘文件名为 `<id>.apk` |
+| `filename` | String(255) | — | 原始文件名 |
+| `display_name` / `package_name` / `version_name` | String | `""` | 解析结果 |
+| `version_code` / `size` | Integer | `0` | |
+| `upload_time` | String(20) | `""` | |
+
+### 2.6 `device` — 设备池
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `serial` | String(120) | — | 主键：`IP:5555` 或 USB 序列号 |
+| `name` | String(80) | `""` | 备注名 |
+| `model` | String(120) | `""` | 型号（迁移 v3 追加） |
+| `enabled` | Boolean | `True` | 停用则不参与调度 |
+| `note` | Text | `""` | |
+| `created_at` | String(20) | `""` | |
+| `fingerprint` | String(120) | `""` | **设备指纹**（`ro.serialno`，迁移 v5 追加）：同一台物理设备换 IP 后据此认领回原记录 |
+| `cur_account_name` / `cur_name_at` | String(80)/String(20) | `""` | **上次探测到的抖音当前账号名字**（迁移 v13 追加）：只有「按名字找设备」（计划页的推送）会写它。**纯缓存** —— 自动任务永远现场读屏幕，缓存旧了也不影响发布的正确性；界面上带时间戳显示 |
+
+### 2.7 `pending_device` — 待确认的发现设备
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `serial` | String(120) | — | 主键 |
+| `source` | String(20) | `""` | `lan` / `tailscale` |
+| `first_seen` / `last_seen` | String(20) | `""` | 时间串 |
+| `fingerprint` | String(120) | `""` | 扫描时读取的设备指纹（迁移 v6 追加），用于提示"这是已有设备换了地址" |
+
+> ⚠️ 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`，
+微秒级；队列满丢弃并计数）——步骤执行是热路径，绝不能在任务线程里同步写库。
+
+### 2.9 `done_mark` — 去重账本（跨设备"已做过"）
+
+| 列 | 类型 | 说明 |
+|----|------|------|
+| `id` | Integer PK | |
+| `scope_key` | String(300) **UNIQUE** | **幂等的全部依据**：`任务ID \| 身份值 \| 时间桶` |
+| `kind` | String(12) | `day` / `hours` / `all`（有效期策略，任务级 `dedup_reset`） |
+| `job_id` | String(32) idx | 哪个任务 |
+| `job_name` | String(120) | |
+| `serial` / `device_name` | String | 哪台设备（界面上显示"谁做过了"） |
+| `identity` | String(200) | 身份值（如抖音号 `35377983067`） |
+| `created_at` | String(20) idx | |
+
+索引：`job_id`、`created_at`、`(job_id, created_at)`。
+
+**为什么靠唯一索引**：多台设备会同时判断"没做过"，"先查后插"有竞态（两台都插）；
+唯一索引 + `INSERT ... ON DUPLICATE KEY`/`INSERT OR IGNORE` 的**受影响行数**才是原子的。
+实现在 `core/dedup.py`（`check` / `mark` / `list_marks` / `delete_mark` / `clear_job` / `purge_old`）。
+
+**保留期**：每天 04:23 清理过保留期（`core/dedup.KEEP_DAYS`，默认 180 天）的记录，
+但**只清 `day`/`hours` 桶**——`kind='all'`（"只做一次"）清了就等于去重失效，永不清理。
+量级很小（设备数 × 天数），单条 DELETE 足够，不需要像步骤明细那样分批。
+
+⚠️ 这张表**自动进整库备份**（§6 派生规则）；接任务步骤见 [TASK_DEV.md](TASK_DEV.md) §4.6。
+
+### 2.10 `device_account` — 账号台账（**已停用，表保留**）
+
+> **2026-10-12：账号管理整块下线。** 页面（「账号」页）、接口（`/api/ledger*`）、
+> 服务层（`core/ledger.py` 已删）、任务取号（`cmp_source=device/all/group`）、
+> 设备端身份页的账号块（`accounts_b64`）、设备池的「账号 N」列**全部移除**。
+>
+> 为什么留着表和这 42 行数据：**删数据不可逆**，而这张表在备份清单里（红线：功能涉及的数据
+> 必须纳入备份）—— 先停用、确认稳定后再单开一次清理动作。
+> 发布计划改走**名字**（见 §2.11），不再需要台账。
+>
+> 唯一从 `core/ledger.py` 迁走的是 `serial_of(设备名) → 当前地址`（与账号无关），
+> 现在在 `core/device_pool.py`。
+
+历史结构（停用前）：一台设备上登录着哪些账号。「账号」页维护。
+
+| 列 | 类型 | 说明 |
+|----|------|------|
+| `id` | String(32) PK | uuid 前 8 位 |
+| `device_name` | String(80) **index** | 设备号（= 设备池里的**设备名**，如 `A01`） |
+| `serial` | String(120) | 录入时的**地址快照**（设备换 IP / 改名后台账仍能靠任一侧找回） |
+| `phone` | String(32) index | 手机号 |
+| `nickname` | String(80) | 账号名称 |
+| `douyin_id` | String(64) index | **抖音号（纯号）**，如 `35377983067` |
+| `registered_at` | String(20) | 注册时间（**原样存文本**，如 `2026/9/24`） |
+| `sim_in_device` | Boolean | 卡在机内（**空 = 否**） |
+| `can_post_video` | Boolean | 可发视频（**空 = 否**） |
+| `bio` / `note` | Text | 简介 / 备注 |
+| `created_at` / `updated_at` | String(20) | 字符串时间（仓库惯例） |
+
+**（停用前的）三个使用方**：① web「账号」页（列表/增删改/从 Excel 粘贴导入）；
+② 任务「条件判断」取号（`cmp_source=device/all/group`）；③ 手机端 Agent 的身份大字页（`accounts_b64`）。
+**三个都已移除**；发布计划现在按**名字**走（§2.11）。
+
+⚠️ 历史提醒：`douyin_id` 是纯号，**绝不能当去重身份**（`done_mark.identity` 存的是元素原文、
+逐字算 key，格式不一致会让去重静默失效）—— 这是当年 `cmp_source` 取号的边界，
+现在候选值来自"本次要发的名字"，同理不得拿去填 `ident_value`。
+
+这张表**仍在整库备份内**（§6 派生规则）—— 停用不等于删数据。
+
+### 2.11 `video_plan` — 视频发布计划（**一个名字**在某天要发的一个视频）
+
+「发布计划」页维护；服务层 `core/video_plan.py`，接口 `/api/video_plan/*`（见 [API.md](API.md) §2.14），
+任务步骤「发布视频」按它自动发布（见 [TASK_DEV.md](TASK_DEV.md) §4.7）。
+**素材文件（视频/图片）**落在 `data/videos/YYYY-MM/`（文件名 `{sha1[:12]}_{安全原名}`，内容寻址），**不进整库备份**（§6）。
+
+| 列 | 类型 | 说明 |
+|----|------|------|
+| `id` | String(32) PK | uuid 前 8 位 |
+| `nickname` | String(80) | **识别键**：上传文件名里的**名字**（= 抖音昵称）。运行时就按它取计划、找设备/账号 |
+| `account_id` / `phone` / `douyin_id` / `device_name` / `serial` | String | **已停用**（老台账快照，保留列不再写入）：账号 id / 手机号 / 抖音号 / 设备号 / 地址 |
+| `release_date` | String(10) index | **`2026-09-12`** 纯日期（等值比较走索引） |
+| `seq` / `seq_auto` | Integer / Boolean | 编号从 **1** 起（不用 0 表示"无"）；`seq_auto`=号是自动分配的 |
+| `title` | Text | **标题**（发布页的「标题」框；标题 txt 配对写入） |
+| `body` | Text | **正文/文案**（发布页的文案框，可带 `#话题`）—— 标题 txt 一行里用 `||` 分隔：`标题 || 正文_名字_日期_编号`；**标题与正文都为空的行不会被发布** |
+| `video_file` / `video_name` / `video_size` / `video_sha1` | 各自 | **素材**（视频或图片，看扩展名）：落盘相对路径 / 原始名 / 大小 / 内容指纹（重复上传判据）。推送时**扩展名原样带到手机**——抖音按它判断视频还是图文 |
+| `status` | String(16) index | 见下方状态机 |
+| `stage` | String(16) | 失败发生在哪一步：`push`/`scan`/`post`/`verify` |
+| `attempts` | Integer | 尝试次数（上限 3，超了不再自动取） |
+| `published_at` / `share_url` / `link_at` / `video_deleted_at` | String | 发布时刻 / **作品分享链接** / 抓到链接的时刻 / 素材何时清理 |
+| `push_verify` / `push_remote` | String(16)/String(200) | **推送后的相册校验**：`ok`=已进相册索引 / `no_index`=文件在但没进索引（相册里可能看不到）/ `nofile`=文件不在；`push_remote` = 推到手机上的绝对路径（删它、排查用）。**文件推上去了 ≠ 相册里点得到它**，所以单独存一列而不是混进 `last_error` |
+| `posted_serial` / `posted_device_name` | String(120)/String(80) | **实际是哪台设备发的**（推送时现场写）。计划不再绑设备，所以"这条最后是谁发的"只能这么记 —— 排查"怎么发到那台机器上去了"全靠它 |
+| `last_error` / `note` / `created_at` / `updated_at` | | 失败原因 / 人工备注 / 时间 |
+
+**状态机**（本表的灵魂，别简化）：
+
+```
+pending    有视频、还没标题              ready      素材齐，等推送
+pushing    已推到手机（等人/用户的步骤去发）  done       已发布（终态）
+skipped    人工跳过（终态）              failed     推送阶段就失败 —— 还没到抖音，**可安全重试**
+unknown    推送之后出的岔子 —— **可能已经发出去了，绝不自动重试**，要人工裁决
+```
+
+> **平台只负责把素材推到手机**（`push_release` 步骤 / 计划页「推送到手机」）：
+> 推文件 → 触发相册刷新 → 把标题写进手机剪贴板。**抖音里怎么发由用户在任务画布上自己写**，
+> 最后放一个 `mark_release`「标记发布结果」回写这里的状态（`published`→`done`、`failed`、`unknown`）。
+> 这样抖音改版时用户改自己的步骤即可，不用等平台发版。
+
+> ⚠ **`failed` 与 `unknown` 必须分开**：把"不知道自己发没发"混成"知道自己没发"，
+> 就是重复发布的来源。`stage` 是两者互相转换的唯一依据（`core/video_plan.STAGE_STATUS`）。
+> 界面上的 `unknown` 卡片标橙 + 硬提示，人工到抖音确认后点「已发出 / 未发出」裁决。
+
+**唯一性**：`(nickname, release_date, seq)` 由**服务层**保证，**不加 DB 唯一索引** ——
+`seq` 从 1 起、没有"空值"可言，做部分唯一索引要写三处方言适配 + MySQL 生成列（§4.2），
+收益不匹配；违反的代价只是低频人工上传产生的重复行（可见、可删）。
+
+**索引**：`(release_date,status)` 时间线主查询 · `(nickname,release_date)` **按名字取计划/查重**（主路径）·
+`(account_id,release_date)` · `(phone,release_date,seq)` 老台账路径（已停用，保留）· `(video_file)` 清理时反查引用。
+后三个里带 `account_id`/`phone` 的两个是历史遗留（账号台账停用后不再走），等确认稳定后一并清理。
+`ix_video_plan_name_date` 由 `_ensure_plain_indexes()` 在启动时补建（`create_all` 不管已有表的新索引）。
+
+这张表**自动进整库备份**（§6 派生规则）；**素材文件不进备份包**，见 §6 与 §7。
+
+---
+
+## 3. 非模型表
+
+### 3.1 `app_meta` — KV 配置
+
+| 列 | 类型 |
+|----|------|
+| `key` | TEXT PRIMARY KEY |
+| `value` | TEXT |
+
+由 `_migrate_schema()` 建表（启动必执行）。**所有键见 §5**。
+
+### 3.2 AI 相关四张表（`web/agent_api.py`，原生建表）
+
+| 表 | 列 |
+|----|----|
+| `agent_conversation` | `id`(PK) · `title` · `messages`(JSON) · `created_at` · `updated_at` |
+| `agent_experience` | `id`(PK AUTOINCREMENT) · `task_prompt` · `recipe` · `tool_seq` · `hits` · `created_at` |
+| `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` |
+
+> 2026-09-13 起这四张表**已升为 ORM 模型**（见 §1 的说明），建表统一走 `db.create_all()`。
+
+---
+
+## 4. 迁移机制
+
+### 4.1 建表与补列（以模型为准）
+
+**模型定义是唯一真相**。启动时：
+
+| 步骤 | 做什么 | 幂等性 |
+|------|--------|--------|
+| `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 |
+
+> 2026-09-13 之前，补列靠 `ALTER TABLE` 报错文本里有没有 `duplicate column name` 来判断
+> 「列已存在」——那是 SQLite 时代的写法，换方言（MySQL 的错误码/文本都不同）就失效了。
+> 现在改为直接读数据库元数据比对，**缺什么补什么，两种方言一套代码**。
+
+### 4.2 唯一索引（设备身份）
+
+两个「空值不参与唯一约束」的唯一索引，与版本号无关，每次启动都补建：
+
+| 索引 | 作用 |
+|------|------|
+| `ux_device_name` | 设备**名称唯一**（空名不参与，兼容历史未命名设备） |
+| `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 仍在 → 直接归档**，防止"用户删空数据后重启又复原"。
+
+---
+
+## 5. `app_meta` 键清单
+
+| key | 用途 | 写入方 |
+|-----|------|--------|
+| `schema_version` | 迁移版本游标 | `core/models.py` |
+| `agent_api_base` | AI 接口地址 | AI 控制台配置页 |
+| `agent_model` | 模型名 | 同上 |
+| `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）。新建步骤时预填用。**只存与出厂值不同的字段**，这样以后调出厂默认能跟着走 | 任务 → 动作配置 页 |
+| `device_battery` | **电量监控配置**（JSON：`{enabled, low, critical, skip_charging, interval}`，见 [NOTIFY.md](NOTIFY.md) §3.1）。**只存与出厂值不同的字段**（出厂：`low=20 critical=10 skip_charging=true interval=60`）。**电量本身不落库**——只放采集线程的内存缓存（重启重新采一轮），所以没有对应表、不动备份覆盖清单 | 工具 → 设备发现 → 电量监控 |
+
+> ⚠️ `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` **由模型元数据派生**：
+
+```python
+SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
+```
+
+也就是说——**新增一张 ORM 表，自动就进备份覆盖清单**，不可能再漏。
+`TABLE_LABELS`（预览页的中文标签）仍是手工维护，缺标签时回退显示表名。
+
+**双向自检**：
+
+- **导出侧**：登记在 `SUMMARY_TABLES` 但快照里缺失 → 写入 `manifest.coverage_missing` + 日志告警
+- **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警（字段 `extra_tables`）
+- `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入（这四项是"判定这是不是本平台备份"的最小集合，故意手工维护）
+
+> **素材文件不进备份包**：`create_export()` 只打包 `data/apks/*.apk`，**不含 `data/videos/`**
+> （几十 GB 会把"数据库备份"这个核心能力搞坏）。备份的 `manifest.json` 里有
+> `videos.included=false` + 数量/字节数，备份预览页也会提示"素材需另外备份 `data/videos/`"
+> —— **不能让人以为备份了**。恢复后素材要重新上传（计划与发布状态、分享链接都在表里，已备份）。
+
+> **红线**：新增持久化表时**同时补 `TABLE_LABELS` 的中文标签**并更新 [DEPLOY.md](DEPLOY.md) §数据备份。
+> 覆盖清单本身不再需要手工登记（已由 metadata 派生）。历史教训：`agent_action` 曾漏登记，
+> 导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
+
+---
+
+## 7. 数据目录
+
+| 路径 | 内容 | 进 git |
+|------|------|--------|
+| `data/users.db`(+`-wal`/`-shm`) | SQLite 主库（**仅回退模式用**；连 MySQL 时这些文件不被读写，可留作历史归档） | 否 |
+| `data/apks/*.apk` | 上传的 APK | 否 |
+| `data/videos/YYYY-MM/*` | 视频发布计划的素材（几百 MB 一个；**不进整库备份**，见 §6） | 否 |
+| `data/backups/` | 导出临时 zip、`pre_restore_*.zip`（导入前安全网）、`restore_failed_*` | 否 |
+| `data/restore_staging/<token>/` | 导入暂存（TTL 1800s 自动清理） | 否 |
+| `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 迁移归档 | 否 |
+| `logs/*.log` | 运行日志 | 否 |
+
+> `data/` 与 `logs/` 全部是运行时产物，**任何文件都不入 git**。生产机上的库由「系统 → 数据备份导出/导入」或整目录手工备份。
+
+---
+
+## 8. 约定与注意事项
+
+1. **主键用 uuid 前 8 位字符串**（`task_job` / `custom_action` / `apk_file` / `agent_conversation`）：可读性好，理论上有碰撞概率（8 位 hex = 32 bit）。
+2. **JSON 字段一律 Text 存储**，读写通过 `get_*/set_*` 方法；解析失败回退默认值。
+3. **时间统一为字符串**（`"YYYY-MM-DD HH:MM"` 或 `"YYYY-MM-DD HH:MM:SS"`），排序依赖字符串序。
+4. **删除必须显式删行**（`delete_job` / `delete_group`）：只 upsert 会导致重启后数据"复活"。
+5. **跨线程访问 DB 必须自推 app context**（后台线程里用 `with app.app_context()`）。
+6. **不要手工改库结构**：走 `SCHEMA_MIGRATIONS`（模型表）或幂等建表（原生表），否则 `create_all` 与版本号会不一致。
+7. **改表结构后记得**：① 更新本文；② 若是新表，登记备份覆盖清单（§6 红线）。
@@ -1,288 +1,387 @@
-# 部署指南
+# 部署与运维（DEPLOY）

-本文介绍如何从零部署 `platform-tools` 设备自动化后台。
+> 适用读者：部署与运维 `auto_control` 的人。
+> 相关文档：[DEVELOPMENT.md](DEVELOPMENT.md)（开发流程/红线）、[DATA_MODEL.md](DATA_MODEL.md) §数据目录、[ARCHITECTURE.md](ARCHITECTURE.md) §启动装配。

 ---

 ## 1. 环境准备

-### 1.1 Python 环境
+### 1.1 主机与 Python

 - **Python 3.10+**（推荐 3.12）
- 安装后确认 `python --version` 和 `pip` 可用
+- Windows / Linux / macOS 均可；生产跑在 Linux 容器里
+- `pip install -r requirements.txt`

-```bash
-# 验证
-python --version    # 应输出 3.10+
-pip --version
-```
+项目自带的 **adb 二进制**在 `bin/adb/`（Windows 为 `adb.exe` + 依赖 dll；Linux/macOS 为 `adb`，需 `chmod +x`）。`config.py` 按平台自动选路径，换成自己的 adb 覆盖该目录即可。

-### 1.2 OpenSTF 服务
-
-本项目依赖 OpenSTF 管理设备池。如已有 STF 服务，跳过本节。
-
-STF 部署参考官方文档：https://github.com/DeviceFarmer/stf
-
-**需要获取的信息**：
- STF 服务地址（如 `http://192.168.20.220:7100`）
- STF API Token（在 STF 个人设置 → API Keys 里生成）
-
-### 1.3 adb 工具
-
-项目自带 adb 二进制在 `bin/adb/` 目录：
-
- **Windows**：`bin/adb/adb.exe` + 依赖 dll（已包含）
- **Linux**：`bin/adb/adb`（需 `chmod +x`）
- **macOS**：`bin/adb/adb`（需 `chmod +x`）
-
-如需替换为自己的 adb 版本，把对应平台的 adb 放进 `bin/adb/` 即可，`config.py` 会自动识别操作系统。
-
-### 1.4 设备准备
+### 1.2 设备接入

 设备需满足：
- 开启 **USB 调试**（设置 → 开发者选项）
- 或通过 **adb 网络连接**（设置 → 开发者选项 → 无线调试，获取 IP:5555）
- 已接入 STF 设备池（STF 显示 present=True, ready=True）

---
+1. 开启 **USB 调试**
+2. 转网络调试：USB 连上后 `adb -s <serial> tcpip 5555`（后台「工具 → adb 终端」有快捷命令）
+3. 与平台**网络互通**（生产用 Tailscale，设备与部署机在同一 tailnet，serial 形如 `100.100.10.x:5555`）
+4. 在「工具 → 设备池管理」加入设备池（**只连上 adb 不算入池，不参与调度**）

-## 2. 安装部署
+**USB 设备**（serial 无冒号）经部署机的 adb server 驱动：

-### 2.1 获取代码
+- adb 容器需 **host 网络模式**（5037 监听所有网卡，含 Tailscale）
+- 平台通过 `USB_ADB_HOST`（默认 `100.100.10.1`）/ `USB_ADB_PORT`（默认 5037）访问它

-```bash
-# 方式一：直接拷贝项目目录
-# 方式二：解压打包文件（python scripts/pack.py 生成的 zip）
-```
+> **adb key 必须沿用既有 key**（设备信任它）。换 key 会让全部设备变 `unauthorized`。

-### 2.2 安装依赖
-
-```bash
-cd platform-tools
-pip install -r requirements.txt
-```
-
-**依赖清单**（`requirements.txt`）：
-
-| 包 | 版本 | 用途 |
-|----|------|------|
-| Flask | >=2.3,<4.0 | Web 框架 |
-| Flask-Login | >=0.6 | 用户认证 |
-| Flask-SQLAlchemy | >=3.0,<4.0 | SQLite ORM |
-| APScheduler | >=3.10,<4.0 | 定时调度 |
-| requests | >=2.28 | HTTP 客户端 |
-| uiautomator2 | >=3.0 | Android UI 自动化 |
-| uiautodev | >=0.14 | UI 元素抓取 |
-| pyaxmlparser | >=0.3.27 | APK 元信息解析 |
-
-> uiautomator2 首次连接设备时会自动推送 atx-agent 到设备，无需手动安装。
-
-### 2.3 修改配置
-
-编辑 `config.py`，**必须修改**以下两项：
-
-```python
-STF_URL = "http://你的STF地址:端口"
-STF_TOKEN = "你的STF_API_Token"
-```
-
-其他配置按需调整：
-
-| 配置项 | 默认值 | 何时修改 |
-|-------|--------|---------|
-| `WEB_HOST` | `0.0.0.0` | 仅本机访问改为 `127.0.0.1` |
-| `WEB_PORT` | `18050` | 端口冲突时修改 |
-| `ADB_PATH` | 自动识别 | 用自定义 adb 时修改 |
-
-### 2.4 启动服务
-
-**方式一：命令行启动**
-
-```bash
-python web_server.py
-```
-
-**方式二：Windows 一键启动**
-
-双击 `start_web.bat`：
- 自动提权到管理员
- 添加防火墙规则（支持局域网访问）
- 启动 web_server
-
-### 2.5 验证部署
-
-1. 控制台看到 `启动服务: http://localhost:18050/` 即成功
-2. 浏览器访问 `http://localhost:18050/`
-3. 用 `admin/admin123` 登录
-4. 监控页应显示 STF 设备池中的设备
-
---
-
-## 3. 生产部署建议
-
-### 3.1 进程守护
-
-用进程守护工具确保服务自动重启：
-
-**Windows（NSSM）**：
-```bat
-nssm install platform-tools "C:\Python312\python.exe" "D:\platform-tools\web_server.py"
-nssm start platform-tools
-```
-
-**Linux（systemd）**：
-```ini
-# /etc/systemd/system/platform-tools.service
-[Unit]
-Description=Platform Tools Web Server
-After=network.target
-
-[Service]
-Type=simple
-User=www
-WorkingDirectory=/opt/platform-tools
-ExecStart=/usr/bin/python3 web_server.py
-Restart=always
-RestartSec=10
-
-[Install]
-WantedBy=multi-user.target
-```
-
-### 3.2 反向代理（可选）
-
-如需 HTTPS 或 80 端口，用 Nginx 反向代理：
-
-```nginx
-server {
-    listen 80;
-    server_name auto.example.com;
-
-    location / {
-        proxy_pass http://127.0.0.1:18050;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-### 3.3 安全加固
-
- **修改默认密码**：登录后立即在"用户"Tab 修改 admin 密码
- **修改 SECRET_KEY**：编辑 `web_server.py`，把 `app.config["SECRET_KEY"]` 改成随机字符串
- **限制访问**：生产环境把 `WEB_HOST` 改为 `127.0.0.1`，配合反向代理
- **防火墙**：只开放必要端口
-
-### 3.4 日志管理
-
- 日志自动滚动（10MB 一份，保留 5 份）
- 日志目录 `logs/`，可在"日志"Tab 在线查看
- 长期运行建议定期清理或配置 logrotate
-
-### 3.5 数据备份
-
- 数据库 `data/users.db` 包含用户/分组/任务数据
- APK 文件在 `data/apks/`
- 建议定期备份 `data/` 目录
-
---
-
-## 4. 网络配置
-
-### 4.1 端口说明
+### 1.3 端口

 | 端口 | 服务 | 说明 |
 |------|------|------|
-| 18050 | Web 后台 | 主服务端口（config.py 可改） |
-| 20242 | uiautodev | 元素抓取服务（自动启动，固定端口） |
-| 7100 | STF | STF 服务端口（STF 自己的配置） |
-| 5555 | adb | 设备 adb 网络端口（设备端） |
-
-### 4.2 Windows 端口问题
-
-Windows 可能将某些端口范围划为动态排除范围，导致绑定失败（WinError 10013）。
-
-```bash
-# 查看排除的端口范围
-netsh interface ipv4 show excludedportrange protocol=tcp
-```
-
-如果 18050 在排除范围内，修改 `config.py` 的 `WEB_PORT` 到一个不在排除范围内的端口。
-
-或运行 `scripts/fix_web.bat`（关闭系统代理 + 添加防火墙规则 + 刷新 DNS）。
-
-### 4.3 局域网访问
-
- `WEB_HOST = "0.0.0.0"` 允许局域网访问
- 需要添加防火墙入站规则（`start_web.bat` 会自动处理）
- 局域网其他机器访问 `http://部署机IP:18050/`
+| 18050 | Web 后台 | `config.py` 的 `WEB_PORT`；绑定失败会自动回退候选端口 |
+| 8033 | MCP Server | `MCP_HTTP_PORT`；由 `scripts/start.sh` 拉起 |
+| 20242 | uiautodev | 元素抓取；`web_server.py` 启动时自动 Popen |
+| 5555 | 设备 adb | 设备侧端口 |

 ---

-## 5. 更新升级
+## 2. 安装与启动

-### 5.1 代码更新
+### 2.1 获取代码与依赖

 ```bash
-# 1. 停止服务
-# 2. 替换代码文件（或解压新的 zip）
-# 3. 重新安装依赖（如有新增）
+cd auto_control
 pip install -r requirements.txt
-# 4. 启动服务
+```
+
+主要依赖：Flask / Flask-Login / Flask-SQLAlchemy / APScheduler / uiautomator2 / uiautodev / rapidocr_onnxruntime / **opencv-python-headless** / pyaxmlparser / fastmcp / paramiko。
+
+> ⚠️ **服务器与容器环境必须用 `opencv-python-headless`**：GUI 版 `opencv-python` 依赖 X11 库，`python:slim` 容器里 `import cv2` 直接崩 → OCR 步骤抛异常 → 任务失败退出。版本锁 `<5`（5.x wheel 没有 cv2 模块）。`scripts/start.sh` 会自动做这个替换。
+
+### 2.2 配置
+
+**密钥类配置统一放项目根 `.env`**（不入 git，模板见 `.env.example`）。加载方式：逐行解析 + `os.environ.setdefault`（**真实环境变量优先**）。
+
+生产至少配：
+
+```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 登录失败
+
+# 发布计划按名字发：抖音「我」页面上的**昵称控件**（用「抓取元素」抓一次，见 .env.example）
+# DOUYIN_NAME_SELECTOR_VALUE=
+# 自动切号：进「账号切换」列表那个入口（同样抓一次）
+# DOUYIN_SWITCH_SELECTOR_VALUE=
+```
+
+> ⚠ **发布计划相关的两个选择器必须抓一次**（`DOUYIN_NAME_SELECTOR_VALUE` /
+> `DOUYIN_SWITCH_SELECTOR_VALUE`）：不填时「读取本机账号名字」「切换账号」会**明确报错并跳过**
+> （不会瞎点、不会发错号），但也就发不出视频。改完 `.env` 要重启容器生效。
+
+**防混库**（`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 启动
+
+```bash
 python web_server.py
 ```

-### 5.2 数据库迁移
+启动成功日志：

- SQLite 表结构变化时，`init_db()` 会自动 `db.create_all()` 创建新表
- 旧 `groups.json` / `jobs.json` 首次启动自动迁移到 SQLite
- 迁移后 JSON 文件归档为 `.migrated`（保留备份，不再迁移）
+```
+[INFO] [core.worker] 心跳看门狗已启动
+[INFO] [core.tm] 从数据库加载 X 个分组, X 个任务
+[INFO] [web] uiautodev 服务已启动 (PID=...)
+[INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
+[INFO] [web] 设备池预连接完成: X 台在线
+[INFO] [web] 启动服务: http://localhost:18050/
+```

-### 5.3 注意事项
-
- **修改 `core/` 目录下的文件后必须重启 web_server**（`debug=False` 不热重载）
- **修改 `templates/` 下的 HTML 文件**：Flask 模板默认不缓存，但建议重启确保生效
- **修改 `tasks/` 下的文件后必须重启**（任务注册在启动时完成）
+默认账号 **admin / admin123**（**登录后立即改密**）。

 ---

-## 6. 故障排查
+## 3. 生产部署（220 容器）

-### 6.1 启动失败
+生产环境固定为 **192.168.20.220** 的 `/mnt/data/openstf/auto_control`，由 `docker-compose` 的 **`python-app`** 容器运行：

-| 现象 | 原因 | 解决 |
-|------|------|------|
-| `ModuleNotFoundError: No module named 'flask'` | 依赖未安装 | `pip install -r requirements.txt` |
-| `WinError 10013` | 端口被排除/权限不足 | 改端口或用管理员运行 |
-| `WinError 10048` | 端口被占用 | 改端口或杀占用进程 |
-| STF 获取设备列表失败 | STF 地址/token 错误 | 检查 `config.py` 的 `STF_URL` 和 `STF_TOKEN` |
+| 项 | 值 |
+|----|----|
+| 宿主目录 | `/mnt/data/openstf/auto_control`（git 仓库，分支 `main`） |
+| 容器挂载 | 宿主目录 → 容器 `/app` |
+| 网络 | `network_mode: host` |
+| 入口 | `scripts/start.sh`（`command`） |
+| 重启策略 | `restart: unless-stopped` |
+| 同级容器 | `adb`（USB 远程 adb server，5037）、以及该机器上其它无关服务 |

-### 6.2 设备连接失败
+> ⚠️ **`docker-compose.yaml` 不在仓库里**，只存在于 220 上；仓库里只有 `scripts/start.sh` 这一半。

-| 现象 | 原因 | 解决 |
-|------|------|------|
-| `DeviceOfflineError` | 设备掉线/STF provider 卡死 | 检查设备网络/STF 状态 |
-| `u2.connect 超时` | atx-agent 无响应 | 重启设备/重新推送 atx-agent |
-| `adb connect failed` | 设备网络不通/端口未开放 | 检查设备 IP 和 5555 端口 |
-| STF 设备显示离线 | STF 状态缓存 | 用"扫描前台App"复测 |
+### 3.1 容器入口 `scripts/start.sh` 做三件事

-### 6.3 任务不执行
+1. **依赖就绪守卫**：检查 9 个模块 + `cv2` 可用性；全部可用就跳过安装
+2. **依赖安装与修复**（仅在需要时）：`pip install -r requirements.txt` → 卸载 GUI `opencv-python` → 装 `opencv-python-headless>=4.8,<5` → 再验 cv2，仍异常则 `--force-reinstall`
+3. **拉起 MCP + 前台启动 Web**：

-| 现象 | 原因 | 解决 |
-|------|------|------|
-| 任务列表有任务但不执行 | 任务未启用 / cron 未到点 | 检查 `enabled` 和 `schedule` |
-| 立即执行无反应 | 无可用设备 | 检查设备池是否有空闲设备 |
-| worker 状态 error | 查看日志的 `last_error` | 查看 `logs/core.log` 和 `logs/task.log` |
-| 看门狗误杀 | 长操作未心跳 | 在长循环内加 `self.heartbeat()` |
+```
+MCP_ALLOW_WRITE=1                     # 脚本内强制开启写操作
+MCP_PLATFORM_USER=${…:-admin}
+MCP_PLATFORM_PASS=${…:-admin123}      # ← 改过 admin 密码必须覆盖它
+MCP_AUDIT_FILE=${…:-/tmp/mcp_audit.log}
+python3 -m mcp_server.mcp_server > /tmp/mcp_server.log 2>&1 &
+exec python -u web_server.py
+```

-### 6.4 日志查看
+> **`scripts/supervise.sh` 只守护 web_server，不拉起 MCP**——容器场景不要用它替代 `start.sh`。
+
+### 3.2 发布流程

 ```bash
-# 查看核心日志
-# 方式一：Web 后台"日志"Tab
-# 方式二：直接看文件
-# logs/core.log   — STF/adb/worker/task_manager
-# logs/task.log   — 任务执行
-# logs/web.log    — Web 请求
-# logs/action.log — 操作执行
+cd /mnt/data/openstf/auto_control
+git fetch origin && git checkout main && git pull --ff-only origin main
+docker restart python-app
 ```
+
+重启后验证：
+
+```bash
+curl -s http://127.0.0.1:18050/api/health          # {"ok":true,"status":"up",...}
+ss -ltnp | grep -E ':(18050|8033|20242)'           # 三个端口都在
+docker exec python-app tail -5 /tmp/mcp_server.log # MCP 已启动
+tail -20 logs/web.log                              # 无 ERROR/Traceback
+```
+
+**发布前检查清单**：
+
+- [ ] 本机 `dev` 已合并 `main` 并推送（且经负责人确认）
+- [ ] 新增依赖已进 `requirements.txt`
+- [ ] **新增持久化表已登记进备份覆盖清单**（`core/system_backup.py`，红线）
+- [ ] 文档已同步（`doc/`）
+- [ ] 若改过 admin 密码 → 同步容器环境变量 `MCP_PLATFORM_PASS`
+- [ ] 启动日志里没有"任务类型已不存在"告警（有则说明库里有历史遗留任务，需人工处理）
+
+> ⚠️ **重启会终止正在运行的任务**（worker 状态在内存）。选低峰期，或先在监控页「停止全部」。
+
+---
+
+## 4. 进程守护（非容器场景）
+
+| 方式 | 用法 | 说明 |
+|------|------|------|
+| `scripts/supervise.sh` | `PYTHON=./.venv/bin/python bash scripts/supervise.sh` | 崩溃自动重启；300s 内最多重启 10 次；**不拉起 MCP** |
+| systemd | `ExecStart=/usr/bin/python3 web_server.py` + `Restart=always` | Linux 通用 |
+| NSSM | `nssm install auto_control <python> web_server.py` | Windows |
+| Docker | `restart: unless-stopped` | 生产用法 |
+
+> 进程守护只保证**服务重启**，不恢复已运行的任务。生产建议加健康检查打 `/api/health`（`interval 30s` / `timeout 5s` / `retries 3` / `start_period 10s`）。
+
+---
+
+## 5. 数据备份（重要）
+
+### 5.1 平台内置（推荐）
+
+**「系统 → 数据备份 / 导入恢复」**（仅管理员）：
+
+- **导出**：`POST /api/system/backup/export` → 把当前库（MySQL 或回退模式的 SQLite）
+  整库一致快照成一份 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`，**由模型元数据自动派生**：
+
+```python
+SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
+```
+
+当前 17 张表：`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` / `done_mark` /
+`device_account`（账号台账，**已停用但仍在备份内**——停用不等于删数据）/ `video_plan`（视频发布计划）。
+完整说明见 [DATA_MODEL.md](DATA_MODEL.md) §6。
+
+> ⚠ **视频素材（`data/videos/`）不进备份包**（几十 GB 会把备份搞坏）：manifest 里有
+> `videos.included=false` 与数量/字节数，预览页也会提示 —— **素材要另外备份**。
+> 计划、发布状态与分享链接都在 `video_plan` 表里，随备份一起走。
+
+> ⚠️ `task_step_log`（任务步骤明细）是会持续增长的表：它按 `KEEP_DAYS`
+> （默认 14 天，见 `core/step_log.py`）自动清理，但备份包里会带上保留期内的全部行。
+> 设备多、任务密时导出 zip 会明显变大——需要更小的包就调小那个常量。
+> `done_mark`（去重账本）也会增长，但量级是"设备数 × 天数"，可以忽略；它同样有保留期
+> （默认 180 天，且 `kind='all'` 的记录**永不清理**）。
+
+> **新增一张 ORM 表，就自动进了覆盖清单**，不可能再漏（2026-09-10 动作库 `agent_action`
+> 曾因手工维护漏登记，数据其实在快照里，只是清单没列 → 被误判为"没有备份"）。
+> 还需要手工做的只有：给新表补 `TABLE_LABELS` 的中文标签。
+> 导出侧有**覆盖自检**（登记表缺失 → `manifest.coverage_missing` + 日志告警）；
+> 导入侧有**反向自检**（备份含未登记表 → 预览告警）。
+>
+> **回滚注意事项**：把"含新表的备份"导回**旧版本代码**时，旧代码的 `SUMMARY_TABLES`
+> 里没有那张新表 → 导入预览会报 `extra_tables` 告警。**数据仍在快照里、不会丢**，
+> 属于预期行为（升级回新版即可正常识别）。
+
+### 5.3 目录与手工备份
+
+| 目录 | 用途 | 可否用环境变量改 |
+|------|------|------------------|
+| `data/backups/` | 导出临时 zip、`pre_restore_*.zip`（导入前安全网）、`restore_failed_*` | `DATA_BACKUP_DIR` |
+| `data/restore_staging/` | 导入暂存（TTL 30 分钟自动清理） | `DATA_RESTORE_STAGING_DIR` |
+| `data/restore_pending/` | 待生效恢复任务（重启时消费） | `DATA_RESTORE_PENDING_DIR` |
+
+> 这三个环境变量主要给**自动化测试**用：测试必须把恢复目录指到临时位置，
+> 否则测试造出来的"待生效恢复任务"会在服务下次重启时被当成用户的操作消费掉。
+
+连 MySQL 时 `data/users.db` 及其 `-wal`/`-shm` **不再被读写**（只有回退模式才用），
+可以留作历史归档。手工整目录备份 `data/` 仍可作兜底，但**整库恢复建议走内置功能**
+（一致快照 + 预恢复备份 + 重启时事务替换）。
+
+> ⚠️ 备份 zip 含**用户口令哈希与 AI 控制台 API Key（明文）**，注意保管与传输。
+
+---
+
+## 6. 安全加固
+
+- **改默认密码**：登录后立即改 admin 密码；需要多人使用时在「用户」页建普通用户并只勾必要权限位
+- **固定会话密钥**：`.env` 写 `WEB_SECRET_KEY`（`python -c "import secrets;print(secrets.token_hex(32))"`）
+- **限制访问面**：`WEB_HOST` 改 `127.0.0.1` + Nginx 反代，或靠防火墙只放必要端口
+- **MCP 端点（8033）自身无鉴权**：它只做**出站**登录平台，不对入站做校验 → **必须靠网络隔离**（同机/内网），不要直接暴露公网
+- **写操作门控**：`MCP_ALLOW_WRITE=0`（默认）时 MCP 只读
+- **HTTPS/80 端口**：用 Nginx 反代
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:18050;
+    proxy_set_header Host $host;
+    # ⚠ 必须加：nginx 默认 client_max_body_size 只有 1m，
+    # 不加的话「应用管理」传 APK（有 336MB 的包）和视频素材上传都会 413。
+    client_max_body_size 2048m;
+}
+```
+
+---
+
+## 7. 升级与迁移
+
+### 7.1 代码升级
+
+```bash
+git pull --ff-only origin main
+docker restart python-app        # 容器场景
+# 或 systemd: systemctl restart auto_control
+```
+
+- **改 `core/`、`tasks/`、`templates/` 后必须重启**（`debug=False` 不热重载）
+- 改前端 JS 后浏览器需**强刷**（Ctrl+Shift+R）
+
+### 7.2 数据库迁移
+
+- **表结构变化**由 `init_db()` 自动处理：`create_all()` 建缺表 + `_sync_columns()` 补缺列（幂等，失败不阻塞启动，见 [DATA_MODEL.md](DATA_MODEL.md) §4）
+- 旧 `groups.json` / `jobs.json` 首次启动自动迁移并归档为 `.migrated`
+- **跨版本恢复**：用「导入恢复」上传旧库 → 预览会提示 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 跨机迁移（换部署机）
+
+1. 新机装依赖、放好 `bin/adb/` 与 **同一把 adb key**
+2. 复制 `.env`
+3. 老机「系统 → 数据备份」导出 zip → 新机「导入恢复」上传并应用
+4. **重启新机服务**（恢复任务在 `init_db` 之前被消费）
+5. 核对设备池在线状态与任务列表
+
+---
+
+## 8. 故障排查
+
+### 8.1 启动类
+
+| 现象 | 原因 / 处理 |
+|------|------------|
+| `ModuleNotFoundError: No module named 'flask'` | 依赖未装：`pip install -r requirements.txt` |
+| `WinError 10013`（Windows） | 端口被排除/权限不足：`netsh interface ipv4 show excludedportrange protocol=tcp` 查看，或改 `WEB_PORT` |
+| `WinError 10048` | 端口被占用：换端口或杀占用进程 |
+| 启动日志只有一半 | 以 WSGI 方式 import 了模块（只跑了 import 期的装配，没跑 `__main__` 分支）；直接 `python web_server.py` |
+| 登录后立刻掉线 | 没配 `WEB_SECRET_KEY`（每次重启换密钥） |
+| 容器里 `import cv2` 崩 | 装成了 GUI 版 opencv：换 `opencv-python-headless`（`start.sh` 会自动修） |
+
+### 8.2 设备类
+
+| 现象 | 处理 |
+|------|------|
+| 设备显示离线 | 「设备池管理 → 一键重连」；确认设备在线、网络互通（生产：同 tailnet） |
+| **设备"断联"但其实没关机** | 多数是**换了 IP**（DHCP 重新分配）：设备池管理点「**换地址**」把记录迁到新地址（名称与分组/任务引用自动保留）；已采集指纹的设备会被扫描自动识别为"已有设备换了地址"，确认即认领 |
+| 加了设备但不被调度 | 只连上 adb 不够，必须在**设备池**中且 `enabled=true` |
+| `u2.connect 超时` | atx-agent 无响应：重启设备或重新推送 atx-agent（基类有 30s 超时保护） |
+| 大量设备同时连接时超时 | Windows 端口耗尽（`WinError 10048`）：代码会打 `[transient]` 并退避 120s 重试；减少并发或调整系统 TIME_WAIT |
+| 设备 `unauthorized` | adb key 变了：恢复原 key |
+
+### 8.3 任务类
+
+| 现象 | 处理 |
+|------|------|
+| 任务不执行 | 检查 `enabled`、`schedule`、是否在运行窗口内、目标设备是否在线 |
+| 立即执行无反应 | 无可用设备（`resolve_serials` 为空）；看 `logs/core.log` |
+| 任务"成功"但没做事 | 步骤类型未知/缺必填参数会被**告警跳过**；查 `logs/task.log` 的 WARNING |
+| 执行报"任务类型 xxx 已不存在" | 库里残留了已删除类型的任务（如历史 `douyin_nurture`）：在「任务」页删除或改用现有类型。启动日志也会点名列出 |
+| 长任务被看门狗杀 | 120s 无心跳：业务循环里要周期性 `self.heartbeat()` |
+| 任务卡在 running | 监控页「停止选中」；必要时重启服务（重启会清空内存状态） |
+
+### 8.4 其它
+
+| 现象 | 处理 |
+|------|------|
+| 元素抓取按钮不可用 | uiautodev（:20242）没起来；`web_server.py` 启动时自动拉起，手动可 `python -m uiautodev server --no-browser` |
+| 抓元素超时 | 部分设备 dump 慢（~18s）超过平台超时（8s），见 [backlog/TODO.md](backlog/TODO.md) |
+| AI 控制台报"MCP server(8033) 不可达" | MCP 没启动：容器由 `start.sh` 拉起，本机手动 `MCP_ALLOW_WRITE=1 python -m mcp_server.mcp_server` |
+| AI 控制台报 401 | 模型 API Key 无效/过期：在「AI 控制台 ⚙ 配置」重填 |
+| 备份导入后没变化 | **必须重启服务**，恢复任务在重启时才被消费 |
+
+日志位置：`logs/core.log`（adb/调度）、`logs/task.log`（任务执行）、`logs/web.log`（Web/AI）、`logs/action.log`；容器内 MCP 日志 `/tmp/mcp_server.log`。
@@ -0,0 +1,258 @@
+# 开发手册（DEVELOPMENT）
+
+> 适用读者：所有参与 `auto_control` 开发的人。**动手前先读 §2 技术红线**。
+> 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)（架构，先懂再改）、[DATA_MODEL.md](DATA_MODEL.md)（表结构）、[doc/README.md](README.md)（文档索引与维护约定）。
+
+---
+
+## 1. 开发流程
+
+### 1.1 分支策略
+
+| 分支 | 用途 |
+|------|------|
+| `dev` | 开发分支，所有新功能/修复从它切出、合并回它 |
+| `main` | 生产分支，只放已确认的稳定版本 |
+| `fix/xxx` · `feat/xxx` · `chore/xxx` | 单个改动的临时分支（从 `dev` 切出） |
+
+生产环境 = 部署机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（`python-app` 容器）。
+
+### 1.2 git 铁律
+
+**所有 git 操作都必须先经项目负责人明确确认**，包括但不限于 `commit` / `push`（**即使 push 到 dev 也要确认**）/ `merge` / `rebase` / `reset` / `branch -D`。
+
+**标准流程**：
+
+```
+① 本机新建分支          fix/xxx 或 feat/xxx（从 dev 切出）
+② 分支上开发 + 自测     跑通本机（服务/接口/页面），能自测就别只靠"看代码没问题"
+③ 交负责人确认          ★ 未经确认不合 dev
+④ 合并到 dev            确认通过后（保持线性：rebase 后 ff-merge）
+⑤ dev 整体就绪          功能齐全、验证完毕
+⑥ 合并到 main           ★ 负责人确认后
+⑦ 生产 220 部署         git pull → docker restart python-app → 验证（见 DEPLOY.md §3）
+```
+
+> 每个改动**单独分支 + 单独 commit**，主题单一，便于评审与回退。不允许"开发完顺手 commit/push"。
+
+**修复也走这条流程，包括线上紧急修复**（2026-09-14 补：当天两次 APK 安装修复因为"生产卡着"
+直接提交在 dev 上、紧接着就合 main 部署，被负责人纠正）：
+
+- 紧急修复照样从 dev 切 `fix/xxx` 分支——**不允许直接 commit/push 到 dev**，
+  哪怕改动只有几行、哪怕生产正卡着
+- 第 ② 步的"自测"要**跑通本机服务**（起服务/点页面/看日志），不能只有脚本级验证
+- 第 ③ 步的确认要点名两件事：**「是否合 dev」**和**「是否合 main + 部署生产」**——
+  紧急场景可以一次性问清，但**不能把两个节点合并成一次默认同意**
+- 线上正卡住时：先**恢复**（重启/回滚等运维动作，经确认即可执行），再按流程走修复
+
+---
+
+## 2. 技术红线（违反会打断共享 adb transport 或造成生产事故）
+
+| # | 红线 | 为什么 | 代码里的体现 |
+|---|------|--------|-------------|
+| 1 | **绝不 `adb kill-server`** | 会断掉所有设备的 adb transport，运行中任务全废 | `core/adb_helper.py` 只 connect 不 kill；Web 层硬拦截 `kill-server`/`disconnect` 字符串 |
+| 2 | **绝不对 `IP:5555` 设备 `adb disconnect`** | 该地址的 adb transport 是共享的 | `adb_disconnect` **全项目零调用方**；`STFDevice.release()` 空实现 |
+| 3 | **空闲设备扫描不主动 connect/disconnect** | 避免扰动共享连接 | 前台扫描对空闲设备直接返回"空闲"；设备发现用 socket 探测 |
+| 3b | （3 的边界）**只读 `adb -s <serial> shell …` 是允许的**，它不建立/断开 transport | 设备已在 `adb devices` 里就说明 transport 现成，读一下不扰动任何人 | 电量采集 `core/device_battery.py` 就是这么读**包括空闲设备在内**的全部在线设备（`dumpsys battery`，实测 0.2~0.35s/台）；**别"顺手"给它加 connect** |
+| 4 | **adb key 保持历史 key 不变** | 设备信任该 key，换 key 全部 `unauthorized` | 部署沿用 `~/.android/adbkey` |
+| 5 | **生产（220）默认只读** | 生产事故成本高 | 任何写操作（pull/重启/改文件）都需负责人确认 |
+| 6 | **新增持久化表必须进备份覆盖清单** | 漏登记 = 等于没备份 | `SUMMARY_TABLES` 已由模型元数据自动派生（加了 ORM 表就进清单）；**手工要做的只有补 `TABLE_LABELS` 中文标签**，详见 [DEPLOY.md](DEPLOY.md) §5.2 |
+| 7 | **功能/配置/接口改动必须同步文档** | 文档落后会误导开发与运维 | 见 §6；索引 [doc/README.md](README.md) |
+
+### 其它开发约束
+
+- **`web_server.py` 以 `debug=False` 运行**：改 `core/`、`tasks/`、`templates/` 后**必须重启**；改前端 JS 后**强刷浏览器**
+- **任务参数放各自 `tasks/<app>/` 顶部**，不放 `config.py`
+- **运行时数据不提交 git**：`data/`、`logs/` 全是运行时产物
+- **不要移除分页与错峰**：监控/列表页已分页（100 台设备只渲染 10 行/页）；任务批量触发已错峰（`_START_STAGGER_SEC`）
+- **不要手工改库结构**：走 `SCHEMA_MIGRATIONS`（模型表）或幂等原生建表
+
+---
+
+## 3. 本地开发
+
+### 3.1 安装
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate    Linux/macOS: source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+确认 adb key（沿用既有 key，否则设备连不上）：`ls -la ~/.android/adbkey`。
+
+### 3.2 启动
+
+```bash
+python web_server.py
+# 访问 http://localhost:18050/   admin / admin123
+```
+
+需要 AI 控制台 / MCP 时，**另起一个进程**：
+
+```bash
+MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
+  python -m mcp_server.mcp_server      # 默认 http://127.0.0.1:8033/mcp
+```
+
+（容器里由 `scripts/start.sh` 自动拉起，不需要手动。）
+
+### 3.3 调试
+
+| 目的 | 做法 |
+|------|------|
+| 看日志 | `logs/core.log`（adb/调度）、`task.log`（任务）、`web.log`（Web/AI）、`action.log`；或「日志」Tab |
+| 看设备/任务状态 | 监控页；或 `GET /api/status`、`GET /api/health` |
+| 后端逻辑验证 | 直接 `python -c "…"` 调用 `core/`、`tasks/` 的函数（如构造 worker 检查参数合并） |
+| 前端验证 | 无 npm/构建，改完强刷；浏览器控制台看报错 |
+| 接口 500 巡检 | `python scripts/regression_test.py`（**⚠️ 当前在 Windows 上会因 `signal.alarm` 报错**，Linux/macOS 可用） |
+| 发布计划（按名字发）用例 | `python scripts/tests/run_all.py` —— 6 套：解析 / 上传配标题 / 读名字与作用域 / 切换账号 / 循环本机待发的号 / 按名字找设备推送。**纯临时库 + 假设备，不连真机**（见 `scripts/tests/run_all.py` 顶部） |
+| 停止设备/清异常 | 监控页「停止全部 / 停止选中 / 清除全部异常」 |
+| 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/`。
+
+### 3.4 写测试的约定（重要）
+
+本仓库没有单元测试框架，验证靠"跑起来 + 真实调用"。写验证脚本时**必须**：
+
+- **不要碰真实数据**：需要会话/任务/分组时**自建**（如 `POST /api/agent/conversations` 建专属会话），绝不要依赖"当前选中项"，也不要删自己没建的东西
+- **改配置前后都要回读校验**：改前 GET 存原值，收尾写回后**再 GET 比对**，不一致要显式报错
+- 临时数据用完即删，并核对"集合已复原"
+
+> 教训：曾用浏览器脚本跑 AI 控制台冒烟，脚本清空 `localStorage` 后前端自动选中了**用户最近的会话**，收尾的"删除测试会话"把用户真实会话删了；同一脚本还把 AI 配置改成了假值。恢复手段见 [DATA_MODEL.md](DATA_MODEL.md) §7 与 git 历史。
+
+---
+
+## 4. 配置速查
+
+### 4.1 配置文件与优先级
+
+- `config.py`：**程序级常量**（端口、路径、USB 远程 adb 等），改它要重启
+- `.env`（项目根，不入 git）：**密钥与可覆盖配置**，逐行解析 + `os.environ.setdefault`（**真实环境变量优先**）；**数据库目标（`DEPLOY_ENV` + `DB_*`）也在这里**
+- `app_meta`（数据库 KV）：**运行时可改的配置**（AI 配置、设备发现参数），在界面上改
+
+### 4.2 `config.py` 常量
+
+| 常量 | 默认值 | 来源 | 说明 |
+|------|--------|------|------|
+| `ADB_PATH` | `bin/adb/adb(.exe)` | 按平台自动 | **不可用 env 覆盖** |
+| `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` | 代码计算 | 备份相关 |
+| `VIDEO_DIR` | `data/videos` | `DATA_VIDEO_DIR` | 视频发布计划的素材目录（**不进整库备份**；测试要指到临时目录） |
+| `MAX_CONTENT_LENGTH` | 2 GiB | `MAX_UPLOAD_MB` | 单次上传体积上限；**必须大于最大的 APK（实测 336MB）**，否则 APK 上传会被卡死 |
+| `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`） |
+| `DISCOVERY_SUBNETS` | 局域网 + Tailscale 网段 | **硬编码列表**（当前无 env 支持） | 默认扫描网段 |
+| `STF_*` | 空 | `.env` | **已废弃**，仅历史保留，代码不再使用 |
+
+### 4.3 进程读取的环境变量（不在 config.py）
+
+| 变量 | 默认 | 谁读 | 说明 |
+|------|------|------|------|
+| `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 密码要同步） |
+| `MCP_ALLOWED_SERIALS` | 空=不限 | 同上 | 逗号分隔白名单（语义缺口见 [backlog](backlog/TODO.md)） |
+| `MCP_HTTP_HOST` / `_PORT` | `0.0.0.0` / `8033` | 同上 | |
+| `MCP_SCREENSHOT_WIDTH` / `MCP_JPEG_QUALITY` | `540` / `70` | 同上 | 返回给模型的截图层参数 |
+| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log`（脚本兜底 `/tmp/mcp_audit.log`） | 同上 | 审计日志路径 |
+| `AGENT_API_BASE` / `AGENT_MODEL` / `AGENT_API_KEY` / `DEEPSEEK_API_KEY` | DeepSeek 默认地址 / 默认模型 / 空 | `mcp_agent/config.py` | **仅 CLI 用**；Web 端 AI 配置优先读数据库 `app_meta` |
+| `AGENT_MCP_URL` / `AGENT_MAX_STEPS` / `AGENT_TIMEOUT` / `AGENT_LANG` | `http://127.0.0.1:8033/mcp` / 40 / 120 / zh | 同上 | |
+| `ANDROID_ADB_SERVER_ADDRESS` / `_HOST` / `_PORT` | 未设 | **adb 客户端自身**（非本项目代码） | 把 adb 调用指向远程 server；两套变量名都要设 |
+
+> `mcp_server/config.py` 与 `mcp_agent/config.py` **不读 `.env`**（只读进程环境变量），与根 `config.py` 的行为不同。
+
+---
+
+## 5. 常见开发任务
+
+> 每一项的"改哪里"清单也见 [ARCHITECTURE.md](ARCHITECTURE.md) §10。
+
+### 5.1 新增 HTTP 接口
+
+1. 在对应功能域的 `web/xxx_api.py` 加 `@bp.route(...)` + 鉴权装饰器（`@login_required` / `@perm_required(PERM_X)` / `@admin_required`）
+2. 新蓝图需在 `web/__init__.py` 的 `register_blueprints` 里注册
+3. 更新 [API.md](API.md)（路由索引表 + 详细小节）
+
+### 5.2 新增数据库字段/表
+
+- 模型改 `core/models.py`；新表 `create_all()` 会建（**幂等**：已是模型就会自动建/补列）
+- **老库**要在 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）
+- **新增表**：`SUMMARY_TABLES` 由模型元数据**自动派生**（＝自动进备份覆盖清单），
+  仍需手工做的是补 `TABLE_LABELS` 的中文标签（**红线**）
+- 更新 [DATA_MODEL.md](DATA_MODEL.md) 与 [DEPLOY.md](DEPLOY.md) §5.2
+
+### 5.3 修改前端
+
+| 改什么 | 文件 |
+|--------|------|
+| 页面结构 / 样式 / 引入脚本 | `templates/admin/monitor.html` |
+| 公共工具（API/权限/Toast/Tab） | `static/admin/base.js` |
+| 列表分页排序 | `static/admin/list.js` |
+| 各功能域逻辑 | `static/admin/{monitor,editor,tasks,tools,apps,admin,agent,system,markdown,dedup,release}.js` |
+
+新增 JS 模块：建文件 → 在 `monitor.html` 里按依赖顺序加 `<script src>` → 更新 [ARCHITECTURE.md](ARCHITECTURE.md) §6.3 与本文 §5.3。
+
+### 5.4 新增步骤类型 / 任务类型
+
+见 [TASK_DEV.md](TASK_DEV.md)（步骤类型要同时改后端 `STEP_TYPES` 与前端 `STEP_LIB`）。
+
+### 5.5 新增 MCP 工具
+
+在 `mcp_server/mcp_server.py` 加 `@mcp.tool()` 函数；写操作必须挂门控（`_check_write` → `_check_serial` → `_ensure_device_free`）；更新 [MCP.md](MCP.md)。
+
+### 5.6 新增常驻线程
+
+参考 `core/device_discovery.py` 的 `init_app(app)` / `shutdown()` 模式；更新 [ARCHITECTURE.md](ARCHITECTURE.md) §3。
+
+---
+
+## 6. 文档同步（红线）
+
+**任何功能 / 配置 / 接口 / 表结构的增删改，都要在同一个 commit 里更新对应文档。**
+
+| 改动类型 | 必须更新 |
+|---------|---------|
+| HTTP 接口 | [API.md](API.md) |
+| 表结构 / 迁移 | [DATA_MODEL.md](DATA_MODEL.md)（+ 备份覆盖清单） |
+| `config.py` / `.env` 键 | 本文 §4 + [DEPLOY.md](DEPLOY.md) + `.env.example` |
+| 页面 Tab / 子分栏 / 前端模块 | [ARCHITECTURE.md](ARCHITECTURE.md) §6 + 本文 §5.3 |
+| 任务类型 / 步骤 schema | [TASK_DEV.md](TASK_DEV.md) |
+| 常驻线程 / 装配顺序 | [ARCHITECTURE.md](ARCHITECTURE.md) §2-3 |
+| MCP 工具 | [MCP.md](MCP.md) + [MCP_DESIGN.md](MCP_DESIGN.md) |
+| 对外接入约定 | [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
+| 暂缓项 / 已知问题 | [backlog/TODO.md](backlog/TODO.md) |
+
+新增文档时：登记进 [doc/README.md](README.md) §1 与根 [README](../README.md) 的文档索引。
+历史文档（[STF_REMOVAL.md](STF_REMOVAL.md)）只增不改。
+
+---
+
+## 7. 常见坑速查
+
+| 坑 | 说明 |
+|----|------|
+| 跨线程访问 DB | 必须自推 app context（`with app.app_context()`） |
+| 改了不生效 | `core/`、`tasks/`、`templates/` 改动要重启；JS 要强刷 |
+| Windows adb 输出 | 不能用 `text=True`（非 GBK 字节会崩），要收 bytes 再解码 |
+| u2 卡死 | `u2.connect` / `d.info` 可能永久 hang，必须加超时 |
+| 抢占死锁 | 不能在 `TaskManager._lock` 内调 `stop_device` |
+| 删除不生效 | 删任务/分组必须显式删行，否则重启会"复活" |
+| 前端写了 `data-perm` 仍可见 | 它只在 `loadMe()` 时求值一次；改权限后需刷新 |
+| 新步骤没生效 | 后端 `STEP_TYPES` 与前端 `STEP_LIB` 要同时改 |
+| 备份导入后没变化 | 必须重启服务 |
+| `.env` 不生效 | `setdefault` 语义：**已存在的环境变量优先**，检查是否被系统环境覆盖 |
+
+更完整的"代码里写明的坑"见 [ARCHITECTURE.md](ARCHITECTURE.md) §9.2。
@@ -0,0 +1,271 @@
+# 设备端 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` /
+  `Error type 3` → 视为"这台设备没有这个通道"
+
+**平台按顺序试两个包**（`core/clipboard_helper.py` 的 `_CLIP_TARGETS`）：
+
+| 顺序 | 包 | 说明 |
+|---|---|---|
+| 1 | `com.example.deviceagent`（**本 Agent**） | 现在的标准通道；装了就只调它 |
+| 2 | `com.example.clipinject`（早期独立 APK） | 老设备上可能还残留 → 兜底；走这条会在日志里提示"建议装设备端 Agent" |
+
+两个都没有时报"设备未安装剪贴板注入通道：需要设备端 Agent"（不再只说 ClipInject，
+否则用户会去装那个已经不再分发的旧 APK）。**设备端无需为这条改动做任何事**。
+
+### 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. 版本与兼容
+
+- 身份页 extras（`name`/`ip`/`serial`/`server`/`close`）是**平台单向下发**：设备端多收/少收
+  都不影响旧行为。（2026-10-12：账号台账下线，原先顺带下发的 `accounts_b64` 已不再发送 ——
+  设备端收到"没有这个 extra"时照旧只显示身份信息即可。）
+- `agent_api_version`（当前 **1**）在每次 `bootstrap` 响应里返回
+- **设备端**：启动时对比自己实现的版本，不一致要在日志里明确记下来（不要静默）
+- **平台端**：
+  - 加字段 / 加接口 = 小版本，设备端忽略未知字段即可
+  - 改已有字段语义 / 删字段 / 改鉴权方式 = **大版本**，两边必须同时改
+- 改了协议，**必须同时改这份文档的两个仓库版本**（本文件是平台侧那一份）
+
+---
+
+## 7. 安全须知
+
+- **令牌是凭据**：等于"能读平台的应用清单和 APK 文件"。别写进日志、别外传、
+  别提交到 git（平台侧存在 `app_meta.agent_device_token`，会随备份一起走）
+- 平台侧这组接口**只读**：只能读清单和下载 APK，**不能**触发任务、不能改设备池、
+  不能读配置或密钥
+- 生产环境建议：令牌泄露时立即在面板点「重置令牌」
+- 设备端**不需要也不应该**拿 admin 账号密码
@@ -0,0 +1,204 @@
+# MCP 手机控制手册（MCP.md）
+
+多模态 AI（DeepSeek / Claude 等）通过 [MCP（Model Context Protocol）](https://modelcontextprotocol.io) 操作 Android 手机的统一出口。平台自带的「AI 控制台」（`mcp_agent/`）与外部 MCP 客户端使用的都是这一批工具。
+
+> 本文 = **使用手册**（工具清单 / 用法 / 接入）。设计取舍与演进见 [MCP_DESIGN.md](MCP_DESIGN.md)；AI 控制台的会话/经验/动作机制见 [AI_CONSOLE.md](AI_CONSOLE.md)。
+
+---
+
+## 1. 架构与边界
+
+```
+AI 控制台 / 外部 MCP 客户端
+        │  Streamable HTTP（http://<host>:8033/mcp）
+        ▼
+MCP Server（mcp_server/mcp_server.py）        ← 20 个 de_* 工具
+        │  平台 HTTP API（登录 + CSRF）  或  轻量 adb/u2 直连
+        ▼
+auto_control 平台（:18050）                    ← 设备池 / 任务 / 看屏
+        │  adb / uiautomator2 / uiautodev / OCR
+        ▼
+Android 设备（IP:5555）
+```
+
+- **轻量通道直连**（adb monkey 开 App、u2 输入、本地 OCR）不绕平台，省时间省 token
+- **坐标换算、UI 吸附、剪贴板注入**等细节全部在 Server 层消化，模型只给"意图"
+- **只暴露设备层能力**：平台级的任务增改/分组/设备池/APK/备份等 REST 只给 Web 前端用，未做成 MCP 工具（补齐规划见 [AI_TASK_GEN.md](AI_TASK_GEN.md) §9）
+
+---
+
+## 2. 运行与配置
+
+生产跑在 220 的 `python-app` 容器内（`scripts/start.sh` 自动拉起），端点 `http://192.168.20.220:8033/mcp`。
+
+```bash
+# 本机手动启动
+MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> \
+  MCP_AUDIT_FILE=data/mcp_audit.log python -m mcp_server.mcp_server
+```
+
+| 环境变量 | 默认 | 说明 |
+|---|---|---|
+| `MCP_PLATFORM_URL` | `http://127.0.0.1:18050` | 平台地址 |
+| `MCP_PLATFORM_USER` / `MCP_PLATFORM_PASS` | `admin` / 空（`start.sh` 兜底 `admin123`） | 平台登录凭据。**改过 admin 密码必须同步**，否则登录失败 |
+| `MCP_ALLOW_WRITE` | `0`（`start.sh` 内强制 `1`） | **写门控**：=1 才允许点击/输入/开关 App（只读工具不受限） |
+| `MCP_ALLOWED_SERIALS` | 空 | 设备白名单（逗号分隔）。非空 = 只允许列出的 serial；**为空时只校验 serial 非空，不按平台设备池过滤**（语义缺口见 [backlog](backlog/TODO.md)） |
+| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `0.0.0.0` / `8033` | 监听 |
+| `MCP_SCREENSHOT_WIDTH` | `540` | 截图返回宽度上限（模型看到的坐标系） |
+| `MCP_JPEG_QUALITY` | `70` | 截图 JPEG 质量 |
+| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log`（容器兜底 `/tmp/mcp_audit.log`） | 审计日志路径 |
+| `MCP_PLATFORM_TIMEOUT` | `30` | 平台请求超时（秒） |
+| `MCP_ENABLED` | `1` | **只被 `scripts/start.sh` 消费**：=0 则不后台拉起 MCP |
+
+> `mcp_server/config.py` **只读进程环境变量，不读 `.env`**；`scripts/supervise.sh` 不拉起 MCP（容器场景由 `start.sh` 负责）。
+
+---
+
+## 3. 坐标空间（重要）
+
+- `de_screenshot` 返回 **≤540px 宽**的 JPEG（display 空间），同时给出 `native_size`（设备原生分辨率）与 `screen_state`
+- `de_tap` / `de_swipe` 的坐标一律用 **`de_screenshot` 返回图像的坐标系**，Server 按比例换算成原生坐标
+- **必须先截图再点击**：Server 需要最近一次截图来建立坐标空间，否则报 `invalid_param`「请先对该设备执行 de_screenshot」
+- `de_tap` 带**自动吸附**：落点若在某个可点击元素内，实际点该元素中心 → 坐标**只需大致对准**；返回 `snapped` / `label` 便于核对
+
+---
+
+## 4. 工具清单（20 个）
+
+统一返回约定：
+
+```json
+{"ok": true,  "data": { … }}
+{"ok": false, "error": {"code": "device_busy", "message": "设备正在执行任务…"}}
+```
+
+错误码：`invalid_param` · `device_not_allowed` · `write_disabled` · `device_busy` · `platform_unavailable` · `device_offline` · `text_not_found`。
+
+### 4.1 设备与状态（只读）
+
+| 工具 | 参数 | 返回 / 说明 |
+|------|------|------------|
+| `de_list_devices` | — | `[{serial, name, model, online, task_job, worker_status, foreground_app}]`。**开局第一步**；`name` 是设备在平台里的名称（身份），**向用户汇报时用名称**（同型号多台靠它区分），调工具仍用 `serial` |
+| `de_foreground_app` | `serial` | `{foreground_app}` 当前前台包名（dumpsys，MIUI 焦点为空时兜底） |
+| `de_list_tasks` | — | 平台任务计划 `[{id,name,task_type,enabled,schedule}]`（只读） |
+
+### 4.2 观察屏幕（只读）
+
+| 工具 | 参数 | 返回 / 说明 |
+|------|------|------------|
+| `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） |
+
+### 4.3 点击与滑动（**写操作**）
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `de_tap_text` | `serial`, `text`(≤100 字符) | **推荐**：按屏幕可见文字点击。原生控件走 UI 树，WebView/图片文字自动 **OCR 兜底**；找不到 → `text_not_found` |
+| `de_tap_element` | `serial`, `by`(`text`/`id`/`desc`/`text_contains`/`desc_contains`), `value`, `index`(1) | 按元素属性点击，无需坐标；多命中用 `index` |
+| `de_tap` | `serial`, `x`, `y` | 坐标点击（截图坐标系 + 自动吸附）。**纯图形目标才用** |
+| `de_swipe` | `serial`, `x1,y1,x2,y2`, `duration`(0.2) | 滑动（长按 = 同点起止 + `duration≥1`） |
+| `de_press_key` | `serial`, `key` | `back` / `home` / `recent` / `menu` / `power` / `volume_up` / `volume_down` / `enter` / `delete` / `search` / `camera` |
+
+### 4.4 输入与剪贴板（**写操作**）
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `de_type_text` | `serial`, `text` | 向当前输入框输入（支持中文，直设 EditText，不依赖剪贴板） |
+| `de_set_clipboard` | `serial`, `text` | 写入设备剪贴板（设备端 Agent 通道 + 读回验证） |
+
+### 4.5 App 管理（**写操作**，走 adb 直连不建 u2 会话）
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `de_open_app` | `serial`, `package` | `adb monkey` 直启（最快路径，无需知道 activity） |
+| `de_stop_app` | `serial`, `package` | `am force-stop` |
+
+### 4.6 亮屏 / 熄屏（**写操作**）
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `de_wake` | `serial` | 亮屏并解锁（熄屏时先调它再截图） |
+| `de_sleep` | `serial` | 熄屏（**会中断正在运行的任务，慎用**） |
+
+> 后两组分别经 `direct_ops`（adb）与平台 `POST /api/device/screen_all` 实现，不在 MCP 进程内建 u2 会话。
+
+### 4.7 写操作门控（三连）
+
+所有写工具在执行前依次检查：
+
+1. `_check_write()` —— `MCP_ALLOW_WRITE=1`？否则 `write_disabled`
+2. `_check_serial()` —— serial 非空 / 在白名单内？否则 `device_not_allowed`
+3. `_ensure_device_free()` —— 设备 `worker_status` 不是 `running`/`connecting`？否则 `device_busy`（**AI 不与任务抢设备**）
+
+> 设备状态查询有 **5 秒缓存**；查询本身异常时**放行**（不阻塞），由平台侧兜底。
+
+---
+
+## 5. 推荐使用模式
+
+1. **`de_list_devices`** 确认目标设备在线
+2. **`de_screenshot`** 看图理解当前界面（图像会在下一回合送达模型）
+3. **点击定位优先级**：
+   - 目标有可见文字 → **`de_tap_text`**（一次调用完成"找到并点击"，最可靠）
+   - 文字有歧义/多候选 → `de_ui_tree` 确认后用 `de_tap_element`（可用 `text_contains` 模糊匹配）
+   - 纯图形目标 → `de_tap` 坐标（**无需精算**，会自动吸附）
+4. **输入文字**：先点中输入框，再 `de_type_text`
+5. **每步验证**：关键操作后再 `de_screenshot`——界面变了 = 成功；没变 = 未命中 → 换 `de_tap_text`/`de_tap_element` 重新定位，**不要重复点同一坐标**
+6. **收尾**：用中文总结做了什么、当前状态、注意事项
+7. **效率**：界面未变时不重复截图/点击；连续 6 步无进展就停止并总结
+
+---
+
+## 6. 安全与审计
+
+| 机制 | 说明 |
+|------|------|
+| **写门控** | `MCP_ALLOW_WRITE=0`（默认）时所有写操作被拒，只读可用 |
+| **任务互斥** | 写操作前检查设备是否在跑任务，忙则 `device_busy` |
+| **平台会话** | `platform_client` 内部登录（`MCP_PLATFORM_USER/PASS`）、会话失效自动重登、POST 自动带 `X-CSRF-Token`；**平台凭据不暴露给客户端** |
+| **白名单** | `MCP_ALLOWED_SERIALS` 非空时限制可操作 serial |
+| **审计** | 每次调用（**含只读**）写一行 JSON 到 `MCP_AUDIT_FILE`：`{ts, tool, serial, args 摘要, result 摘要}` |
+| **红线** | 任何工具都不执行 `adb kill-server` / `adb disconnect` |
+| **端点鉴权** | ⚠️ MCP HTTP 端点自身**没有** token/账号校验，只做出站登录 → **必须靠网络隔离**（同机/内网），不要直接暴露公网 |
+
+---
+
+## 7. 客户端接入示例
+
+```python
+import asyncio
+from fastmcp import Client
+
+async def main():
+    async with Client("http://192.168.20.220:8033/mcp", timeout=30) as c:
+        devs = await c.call_tool("de_list_devices", {})
+        serial = devs.data["data"][0]["serial"]          # 第一台设备
+        shot = await c.call_tool("de_screenshot", {"serial": serial})
+        img = shot.data["data"]["image"]                 # base64 JPEG（给多模态模型看）
+        await c.call_tool("de_tap_text", {"serial": serial, "text": "搜索"})
+
+asyncio.run(main())
+```
+
+> 给外部数字员工的使用约定与红线，另见 [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md)。
+
+---
+
+## 8. AI 控制台（内置 Agent）
+
+Web 的「AI 控制台」Tab 内建 Agent（`mcp_agent/`，OpenAI 兼容模型）用的就是本 Server 的同一批工具：
+
+- 流式输出 + 每步 MCP 调用实时展示（含截图缩略）
+- 多轮会话（同会话保留上下文）
+- **自进化记忆**：经验库（任务配方）+ 动作库（命名动作），相似任务自动注入参考
+- 模型与 Key 在控制台右上角 ⚙ 配置（存平台 `app_meta`）
+
+> **依赖提示**：AI 控制台依赖本 MCP Server（默认 `http://127.0.0.1:8033/mcp`）。未启动时平台会把 SDK 的含糊报错映射成明确文案「**MCP server(8033) 不可达 …**」。
+
+---
+
+> **维护约定**：新增 / 修改 / 删除任何一个 MCP 工具或相关配置，必须**同步更新本文与 [MCP_DESIGN.md](MCP_DESIGN.md)**（doc 同步红线）。
@@ -0,0 +1,275 @@
+# MCP 手机控制（Mobile Control MCP Server）设计文档
+
+> 状态：**设计稿 / 演进记录**——凡与实现不符处，以 [MCP.md](MCP.md)（使用手册，含 20 个工具的权威清单）与 `mcp_server/` 代码为准。
+> 本文保留设计取舍与里程碑，便于回溯"为什么这么做"；文中的"演进备选"均**未落地**。
+> 最后核对：2026-09-10（对照 dev 现状）。
+
+## 1. 背景与目标
+
+平台（auto_control，生产 220:18050）已具备完整的手机远程控制与自动化能力：设备池管理、u2 控制（tap/swipe/key/输入/剪贴板）、minicap 看屏（截图/流）、uiautodev 元素树、RapidOCR、任务调度与动作编辑器。
+
+本设计的目标：**新增一个 MCP Server，把平台能力以 MCP 协议暴露给多模态 AI（Claude 等），使 AI 能像人一样"看到手机屏幕 → 理解 → 操作 → 再看到"地闭环控制手机**。
+
+核心判断：平台能力全部已有，MCP Server 是**薄封装层**——主要工作在：工具规格设计、多模态图像链路、认证与安全、部署。
+
+## 2. 术语
+
+| 术语 | 说明 |
+|---|---|
+| MCP | Model Context Protocol，模型上下文协议（客户端-服务器，工具调用） |
+| Tools | MCP 暴露的可调用能力（本设计按 L1/L2/L3 分层） |
+| serial | 设备标识，如 `192.168.20.66:5555`（设备池唯一主键） |
+| 平台 | 指 auto_control web 服务（18050）及其 core 层能力 |
+| 宿主 | MCP Server 运行进程/容器 |
+
+## 3. 总体架构
+
+```
+┌──────────────┐   MCP (Streamable HTTP / stdio)   ┌──────────────────┐
+│  多模态 AI    │ ────────────────────────────────▶ │   MCP Server     │
+│ Claude Desktop│   tools + image content block    │  （与平台同容器） │
+│ Claude Code  │ ◀──────────────────────────────── │  mcp_server/ 包  │
+└──────────────┘   截图图像 / JSON 结果             └────────┬─────────┘
+                                                            │ 内部调用
+                                                            ▼
+                                                 ┌──────────────────┐
+                                                 │ auto_control     │
+                                                 │ 18050 REST API   │
+                                                 │ （登录会话 token）│
+                                                 ├──────────────────┤
+                                                 │ core 层能力：     │
+                                                 │ u2 / minicap /   │
+                                                 │ uiautodev / OCR /│
+                                                 │ 任务调度 / 设备池 │
+                                                 └──────────────────┘
+```
+
+- **图像方向**：MCP 协议支持 `image` content block（base64），截图以此返回，多模态模型原生可读——这是"AI 看到手机"的关键链路。
+- **控制方向**：AI 返回结构化工具调用（tap/swipe/type…），MCP Server 转发平台执行。
+- **循环**：截图 → 模型视觉推理 → 工具调用 → 平台执行 → 截图验证。
+
+## 4. 平台现有能力复用清单
+
+| 平台能力 | 现有入口 | MCP 复用方式 |
+|---|---|---|
+| 设备列表/状态 | `GET /api/status`、`/api/devices/pool` | MCP server 内部 HTTP 调用（带会话） |
+| 截图 | `GET /api/screen/thumb?serial=`（单帧 JPEG） | 直接转发为 image block（亦可直连 core u2 screenshot） |
+| 看屏流 | `/api/screen/stream`（MJPEG） | M0-M2 不需要；M3 可选（视频理解场景） |
+| 点击 | `POST /api/screen/tap {serial,x,y}` | 封装 tool `tap` |
+| 滑动 | `POST /api/screen/swipe` | 封装 `swipe` |
+| 按键 | `POST /api/screen/key` | 封装 `press_key` |
+| 输入文字 | 设备端 Agent 通道（core.clipboard_helper）+ u2 input | 封装 `type_text` |
+| 剪贴板 | `POST /api/tools/clipboard/set`（设备端 Agent 通道） | 封装 `set_clipboard` |
+| 元素树 | `GET /api/uiauto/...`（uiautodev） | 封装 `get_ui_tree` |
+| OCR | core.ocr（RapidOCR） | 封装 `ocr_screen` |
+| 打开 App | u2 `app_start`（经任务层/直连） | 封装 `open_app`（走 core device 直连） |
+| 设备在线状态/亮熄屏 | `/api/device/screen_all`、dumpsys | 封装 `screen_state`/`wake` |
+
+> 决策：MCP Server 优先走 **HTTP API**（薄封装，认证简单、与平台解耦、平台安全逻辑全复用）。对延迟敏感且 HTTP 无入口的能力（u2 直连截图/输入），经平台 core 模块进程内调用或新增少量只读端点，不绕过平台安全层。
+
+## 5. MCP Server 设计
+
+### 5.1 技术栈
+
+- 语言/运行时：Python 3.11（与平台一致）
+- 框架：**FastMCP**（`fastmcp`，官方 SDK 之上，装饰器式 tools，自带 Streamable HTTP/stdio 双传输）
+- 依赖：`fastmcp`（requirements.txt 已含，>=2.0）、`httpx`、`Pillow`（图像处理）、`mcp[cli]`（**设计依赖，未落地**——当前 requirements 未含，仅 fastmcp）
+- 日志：logging → 平台同款格式（时间/级别/模块）
+
+### 5.2 进程与容器
+
+> **实现现状**：当前 MCP 与 web_server **同容器**，由 `scripts/start.sh` 后台拉起（`MCP_ENABLED=1` 默认，=0 可关），监听 8033。下方独立容器方案为**演进备选**。
+
+- 独立容器 `mcp-server`（220 docker-compose 追加），image `python:3.11-slim`（演进备选）
+- 挂载：无数据挂载（无状态，配置走环境变量）；网络 host 或独立端口（**候选：8033**，避免与 18050/18051 冲突）
+- 独立于 auto_control 重启，互不阻塞；MCP Server 崩溃不影响平台，平台不可用时 MCP tools 返回明确错误
+
+### 5.3 配置（环境变量）
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `MCP_PLATFORM_URL` | `http://127.0.0.1:18050` | 平台地址 |
+| `MCP_PLATFORM_USER` / `MCP_PLATFORM_PASS` | 空 | 平台登录账号（admin） |
+| `MCP_ALLOW_WRITE` | `0` | 写操作总开关（0=只读感知，1=可操作） |
+| `MCP_ALLOWED_SERIALS` | 空=全部 | 设备白名单（逗号分隔；为空时自动=设备池内设备）——**设计目标，代码未实现**（实现仅校验 serial 非空，见 §8.3 注） |
+| `MCP_HTTP_HOST` | `0.0.0.0` | HTTP 监听地址 |
+| `MCP_HTTP_PORT` | `8033` | HTTP 传输端口 |
+| `MCP_PLATFORM_TIMEOUT` | `30` | 平台请求超时（秒） |
+| `MCP_SCREENSHOT_WIDTH` | `540` | 截图宽度（等比缩放，控图像 token 成本） |
+| `MCP_JPEG_QUALITY` | `70` | 截图 JPEG 质量 |
+| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log` | 审计日志路径 |
+
+> `MCP_ENABLED` 由 `scripts/start.sh` 消费（默认 1），非 MCP 进程内配置；`MCP_PLATFORM_PASS` 在 start.sh 兜底 `admin123`，改 admin 密码须同步（见 doc/MCP.md）。
+
+## 6. Tools 规格
+
+命名空间 `de_`（device）前缀避免与常见工具冲突。全部工具对**未配置白名单/离线设备**返回明确错误，不做静默跳过。
+
+> **实现现状对照**（本节以下是设计规格；实际实现以 `mcp_server/` 与 [doc/MCP.md](MCP.md) 为准，主要差异）：
+> - `de_screen_state` **未独立实现**：并入 `de_screenshot` 返回的 `screen_state` 字段
+> - 实际另有（设计稿未列）：`de_tap_text` / `de_tap_element` / `de_stop_app` / `de_read_clipboard` / `de_foreground_app` / `de_list_apps` / `de_list_tasks`
+> - `de_type_text` 实际签名 `(serial, text)`，走 u2 `EditText.set_text`（非设计稿的 ClipInject+paste 优先）
+> - `de_tap` 坐标语义已是**截图坐标系、server 按比例换算原生**（非设计稿「原生像素、调用方自换算」）
+> - `de_open_app` 是 **adb monkey 直启**（非 u2 `app_start`）
+> - `de_find_and_tap` / `de_wait_until` / `de_get_task_state` **未实现**；语义点击由 `de_tap_text` / `de_tap_element` 承担
+> - **平台级工具层未实现**：任务 CRUD/提交、分组/设备池/自定义动作/APK/备份等 REST 只给前端用，未 MCP 化；补齐规划见 [doc/AI_TASK_GEN.md](AI_TASK_GEN.md) §9——P0 只补 `list_task_types` / `list_groups` / `list_pool` + `submit_task`（校验不落库），**不暴露写 CRUD**，维持「AI 提案 → 人工确认」
+
+### L1 感知层
+
+#### `de_list_devices`
+- 描述：列出可控制设备及其状态（在线/任务/型号/前台 App）
+- 返回：`[{serial, model, online, task_job, worker_status, foreground_app, screen_state}]`
+- 错误：平台不可达 → `platform_unavailable`
+
+#### `de_screenshot(serial: str) -> image`
+- 描述：截取设备当前屏幕（JPEG），返回 image content block；同时返回 `width/height/serial` 元信息
+- 实现：平台 `/api/screen/thumb`（X-Screen-State 头复用判断亮熄屏）；失败（离线/超时）→ 明确错误
+- 图像规格：宽 ≤ `MCP_SCREENSHOT_WIDTH`（默认 540），质量 `MCP_JPEG_QUALITY`；**需保证图像方向正确**（设备可能横竖屏，含 EXIF 或由调用方按截图尺寸推断）
+- 限制：截图频率 ≥ 1s/次（防 AI 疯狂截图），可配置（**未落地**：现状无频率限制）
+
+#### `de_ui_tree(serial: str) -> str`
+- 描述：获取当前界面元素树（扁平 JSON：resource-id/text/content-desc/class/bounds），供定位
+- 返回：文本 JSON（大树截断至 `MCP_UI_TREE_MAX` 字符，默认 20000，防 context 爆炸）
+- 空界面/无元素 → 明确错误
+
+#### `de_ocr(serial: str) -> str`
+- 描述：OCR 识别当前屏幕文字，返回 `[{text, score, box}]`
+- 场景：图片/画布/WebView 渲染文字（UI 树里没有的）
+
+#### `de_screen_state(serial: str) -> str`
+- 描述：亮屏/熄屏/未知
+
+### L2 操作层（受 `MCP_ALLOW_WRITE=1` 门控）
+
+#### `de_tap(serial, x: int, y: int)`
+- 坐标：设备**原生分辨率**像素（与截图 1:1 换算——调用方用截图尺寸按比例换算，server 不做猜测）
+
+#### `de_swipe(serial, x1,y1,x2,y2, duration: float=0.2)`
+
+#### `de_press_key(serial, key: str)`
+- key ∈ back/home/recent/menu/power/enter/delete…
+
+#### `de_type_text(serial, text: str, clear_first: bool=True)`
+- 实现：优先设备端 Agent 通道（`core/clipboard_helper.inject_clipboard` 语义：写入剪贴板 + paste 到焦点输入框），失败回退 u2 input
+- 中文/emoji 全支持（Agent 通道实测通过）
+
+#### `de_set_clipboard(serial, text: str)`
+- 写入设备剪贴板（设备端 Agent 的 am start 通道），读回验证
+
+#### `de_open_app(serial, package: str)`
+- 打开指定 App（u2 app_start）；`package` 需在已知清单或完全限定名
+
+#### `de_wake(serial)` / `de_sleep(serial)`
+
+### L3 语义层（M2 里程碑）
+
+#### `de_find_and_tap(serial, target: str, by: "text"|"id"|"ocr"|"desc"=...)`
+- UI 树/OCR 定位含 target 的元素 → 自动点击其中心；多命中返回候选列表让 AI 选择
+- 复用平台元素选择器策略（属性唯一/重复序号消歧）
+
+#### `de_wait_until(serial, condition: str, timeout: int=15)`
+- 轮询 OCR/UI 树直到出现条件文本（或消失），返回命中的坐标/文本
+
+#### `de_get_task_state(serial)`（若二期接任务系统）
+- 设备当前任务状态；可选 `de_run_task(task_id)` 需单独授权
+
+### 工具返回约定
+- 全部工具返回结构化 JSON：`{ok: true, data: ...}` 或 `{ok: false, error: {code, message}}`
+- 错误码：`platform_unavailable` / `device_offline` / `device_not_allowed` / `invalid_param` / `write_disabled` / `device_busy`（设备被任务占用，running/connecting 拒写） / `text_not_found`（de_tap_text 屏幕上无该文字）
+- image 返回：`{ok:true, image: <content block>, width, height}`
+
+## 7. 图像链路细节
+
+1. 平台截图（`/api/screen/thumb`）→ JPEG 字节
+2. MCP Server 校验尺寸 → 等比缩放到 `MCP_SCREENSHOT_WIDTH`（用 Pillow，不重压缩已够质量则跳过）
+3. 组装 MCP `image` content block（`{"type":"image","data":<base64>,"mimeType":"image/jpeg"}`）
+4. 客户端（Claude）原生把 image 传入视觉上下文
+
+性能预算：540px JPEG ~40-80KB/张；模型一次多步操作 5-15 张 ≈ 1MB 以内，可接受。
+
+## 8. 认证与安全
+
+1. **平台会话**：MCP Server 启动时用 `MCP_PLATFORM_USER/PASS` 登录平台拿会话（Cookie），会话失效自动重登；不向客户端暴露平台凭据
+2. **写操作门控**：`MCP_ALLOW_WRITE=0`（默认）时 L2/L3 操作全部拒绝（`write_disabled`）——先部署只读，验证感知链路后再开写
+3. **设备白名单**：`MCP_ALLOWED_SERIALS` 指定；为空时自动限制为**设备池 enabled 设备**（平台口径）——**此为设计目标，当前代码未实现**：实现只校验 serial 非空，空名单不按设备池过滤（如需收紧请配置白名单）
+4. **占用互斥**：写操作前查设备 `worker_status`——running/connecting 中拒绝（`device_busy`），避免 MCP 与任务打架（已实现，只读工具不受限）
+5. **审计**：每次调用（含只读）写审计日志：`ts|tool|serial|args摘要|result`；落盘 `MCP_AUDIT_FILE`
+6. **传输安全**：内网部署（host 网络 8033）默认无 TLS；若外网暴露需前置 TLS/网络隔离（平台红线：设备控制接口不进公网）
+7. **无状态**：MCP Server 不存设备数据，全量透传平台
+
+## 9. 部署（220 docker-compose 追加）
+
+> **演进备选**：下方「独立 mcp-server 容器」为演进方案。**当前实现**＝与 web_server 同容器，由 `scripts/start.sh` 后台拉起（`MCP_ENABLED=1` 默认、`MCP_ALLOW_WRITE=1`、`MCP_PLATFORM_PASS` 兜底 admin123），见 [doc/MCP.md](MCP.md) 与 DEPLOY §2.4。
+
+```yaml
+  mcp-server:
+    container_name: mcp-server
+    image: dockerproxy.net/library/python:3.11-slim
+    restart: unless-stopped
+    working_dir: /app
+    volumes:
+      - "./mcp_server:/app"
+    command: sh -c "pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt && python -m mcp_server.mcp_server"
+    environment:
+      - MCP_PLATFORM_URL=http://127.0.0.1:18050
+      - MCP_PLATFORM_USER=admin
+      - MCP_PLATFORM_PASS=${MCP_PLATFORM_PASS}   # .env 提供
+      - MCP_ALLOW_WRITE=1
+      - MCP_ALLOWED_SERIALS=
+    network_mode: host
+```
+
+客户端接入（Claude Code / Desktop）：
+
+```json
+// .mcp.json / claude_desktop_config.json
+{ "mcpServers": { "mobile": {
+    "url": "http://192.168.20.220:8033/mcp",
+    "transport": "streamable-http"
+}}}
+```
+
+## 10. 里程碑与验收
+
+| 里程碑 | 内容 | 验收标准 |
+|---|---|---|
+| M0 | Server 骨架 + `de_list_devices` + `de_screenshot` + `de_tap`/`de_swipe`（HTTP 传输、登录会话、审计骨架） | Claude Code 连上后：能列设备、截图（AI 能描述屏幕内容）、点击指定坐标生效 |
+| M1 | L1 完备（ui_tree/ocr/screen_state）+ L2 全量（key/type/clipboard/open_app/wake） | AI 完成「打开抖音搜索『奚学东』」多步操作 |
+| M2 | L3 语义层（find_and_tap/wait_until）+ 图像尺寸/性能调优 | AI 用自然语言指令（含中文输入）完成跨 3 步以上操作且自适应页面变化 |
+| M3 | 生产化：安全加固复核、审计看板、部署脚本、接入文档、任务系统互斥回归 | 日常稳定使用 1 周无异常 |
+
+> **实现状态备注**：M0/M1 已实现；M2 部分实现（`de_tap_text` / `de_tap_element` 已实现，`de_find_and_tap` / `de_wait_until` 未实现）；M3 未验收。
+
+## 11. 风险与开放问题
+
+1. **AI 误操作**：模型点击错位/误触关键按钮（如删除）——缓解：L3 定位优先于裸坐标、写门控先行、审计可追溯；**不做**二次确认（破坏自动化体验），靠白名单+占用互斥兜底
+2. **截图成本**：长会话多截图 → token/延迟成本——缓解：尺寸/质量可调、截图上限、`de_ui_tree` 作为低成本替代（文本树比图像便宜）
+3. **横竖屏/分辨率异构**：设备多样 → 坐标换算依赖截图 1:1；`de_find_and_tap`（语义层）不受分辨率影响
+4. **图像 content block 兼容性**：Claude 系原生支持；其他多模态客户端需验证（M0 用 Claude Code 验证）
+5. **是否接任务系统**：二期决策——`de_run_task` 语义与"单设备操作"不同（任务面向多设备调度），倾向二期用独立命名空间
+6. **clipboard/input 通道差异**：个别 MIUI 需授权写入剪贴板的透明 Activity——M0 阶段在受控设备集验证，必要时 fallback 链已在 core 层（设备端 Agent → 旧版 ClipInject）
+
+## 12. 附录：平台 API 映射（MCP → 平台）
+
+| MCP tool | 实际平台调用（现状） |
+|---|---|
+| de_list_devices | GET /api/status |
+| de_screenshot | GET /api/screen/thumb?serial=（X-Screen-State 头 → screen_state；另 GET /api/screen/size 取原生分辨率） |
+| de_ui_tree | GET /api/uiauto/elements（uiautodev） |
+| de_ocr | direct_ops.ocr：u2 截图 + core.ocr RapidOCR |
+| de_tap | POST /api/screen/tap（snap=1 自动吸附） |
+| de_swipe | POST /api/screen/swipe |
+| de_press_key | POST /api/screen/key |
+| de_tap_text | POST /api/screen/tap_text（UI 树子串匹配 → OCR 兜底） |
+| de_tap_element | u2 元素直连（uiautomator2 `d(by=value).click()`，无平台端点） |
+| de_type_text | u2 `EditText.set_text`（direct_ops.type_text，不走剪贴板通道） |
+| de_set_clipboard | core.clipboard_helper 设备端 Agent 通道（inject_clipboard，读回验证） |
+| de_read_clipboard | u2 `d.clipboard` |
+| de_open_app | adb monkey 直启（direct_ops.open_app） |
+| de_stop_app | adb `am force-stop`（direct_ops.stop_app） |
+| de_foreground_app | adb `dumpsys window`（direct_ops.foreground_app，mCurrentFocus/mFocusedApp 兜底） |
+| de_list_apps | adb `pm list packages -3`（direct_ops.list_apps） |
+| de_wake / de_sleep | POST /api/device/screen_all（mode=on/off） |
+| de_list_tasks | GET /api/jobs |
+
+> `de_screen_state` 无独立工具，已并入 `de_screenshot` 的 `screen_state` 字段；设计稿中 `de_find_and_tap`/`de_wait_until`/`de_get_task_state` 未实现，不在此表。现状中 MCP 直连面（u2/adb）不经平台 REST，但安全（白名单/写门控/busy/审计）仍在 MCP 工具层统一把关，绝不越权触碰平台红线。
@@ -0,0 +1,289 @@
+# 通知 / 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.video.published`（视频发布成功，带作品分享链接）/ `task.video.failed`（发布失败**或结果未知**——结果未知意味着可能已经发出去了，要到计划页人工确认，平台不会自动重发） |
+| 业务 | `task.page.mismatch`（「校验页面」没等到该出现的特征元素 —— **上一步没生效**，默认跳过本轮剩余步骤，避免在错的页面上继续盲点；见 TASK_DEV §4.7）/ `task.account.switch_failed`（切号失败：账号列表里没这个名字，或切完回读还是别人 —— **本轮不会发这个号的内容**，要人工到设备上确认号还在不在）/ `task.account.need_login`（抖音停在登录/验证码页，**需要人工登录**，平台绝不代替登录/过滑块；本设备已停止本轮任务）—— 都由「切换账号」步骤发出 |
+| 业务·任务自己发 | `task.notify.custom`（步骤「发通知」）/ `task.patrol.hit`（任务「公共巡检」命中）——**标题正文由任务自己写**，见下 |
+| Worker | `worker.connected` · `.attempt.done` · `.attempt.error`（单次尝试级，噪音大，默认没人勾） |
+| 设备 | `device.online` · `.offline` · `.discovered` · `.claimed` · `device.heartbeat_timeout` · `device.battery.low` · `.battery.recovered` |
+| 安装 | `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`。
+
+### 3.1 设备电量告警（`device.battery.low` / `.battery.recovered`）
+
+采集与判定都在 `core/device_battery.py`（后台线程 `device-battery`，默认 60s 一轮，
+`adb -s <serial> shell dumpsys battery` **只读**查询）。阈值配置在
+**「工具 → 设备发现 → 电量监控」**，存在 `app_meta.device_battery`（见 [DATA_MODEL.md](DATA_MODEL.md) §5）。
+
+阈值语义（**这是唯一判定处，前端只读后端算好的 `tier` 上色**）：
+
+| 档位 | 条件 | 通知 |
+|---|---|---|
+| `0` 正常 | `电量 >= 低电量阈值 + 5`（迟滞）或 充电中 | 从低/严重回到 0 → 发 `device.battery.recovered` |
+| `1` 低 | `严重阈值 < 电量 <= 低电量阈值` | **掉到这一档才发** `device.battery.low`（`warning`） |
+| `2` 严重 | `电量 <= 严重阈值` | 掉到这一档再发一次（`error`），阈值字段是严重阈值 |
+
+- **迟滞 +5**：回升要到 `低电量阈值 + 5` 才算恢复。没有它，电量在阈值上下浮动
+  （充电器接触不良）会反复告警。
+- **"充电中"看的是 `status:` 行**（`2` 充电中 / `5` 已充满），不是"插着电"。
+  所以**"插着却没充电"**（劣质线、温控停充、满电停充 `status:4`）**仍然会告警**——
+  那正是最该让人知道的情况。想连充电中一起报，把「充电中不告警」勾掉即可。
+- **重复提醒**：同一档位持续不恢复时，每 **6 小时**再提醒一次（`core/device_battery.RE_NOTIFY_S`）。
+- 只对**「设备池 ∩ 在线」**的设备告警：adb 里能看到但不归平台管的设备不吵人。
+- 一周内改了阈值**不用重启**：采集线程每轮重读配置，档位下一轮就按新阈值算。
+
+排查：`logs/core.log` 搜 `core.battery`（每轮一行「电量采集完成: N/M 台」）。
+
+---
+
+## 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`
+
+**设备一律只传 `serial`，名字自动补**（不用每个调用点自己去查名字）：
+
+群消息里没人想看 `192.168.20.110:5555`，要看「A09」。这件事在通知链路里
+**统一做掉**，调用点照旧只传 `serial` 就行：
+
+| 环节 | 做什么 |
+|---|---|
+| `core/device_pool.py` | 维护一份 `serial → 名称` 的**内存快照**：启动刷一次、池子增删改名/迁址时刷一次、每 60s 兜底刷一次（覆盖整库恢复这类进程外改动） |
+| `web_server.py` | `notifier.set_device_name_resolver(device_pool.name_of)` 把快照接给通知 |
+| `core/notifier.py` | `fill_device_names()` 在 `notify()` 与 `build_message()` 里把 `serial` 补成 `device_name`、把 `serials`/`devices` 列表逐项换成名字 |
+
+为什么绕这一圈：`notify()` 的红线是**零 DB**，不能为了取个名字去查库（那等于在业务
+线程里加一次阻塞查询）。所以名字由 `device_pool` 预先算好放内存，`notifier` 只读。
+
+降级规则（**绝不把内容弄丢**）：调用点自己传了 `device_name` 就用它的；查不到名字
+（设备没命名 / 已不在池里）就保留原来的地址。解析器缺失或抛异常都只是降级，不影响发送。
+
+---
+
+## 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` 是**重启后**才发（恢复本身就是重启生效的）
@@ -0,0 +1,68 @@
+# auto_control 文档总索引
+
+本目录是 `auto_control`（Android 多设备自动化任务平台）的**唯一权威文档源**。代码即事实，文档与代码不一致时以代码为准，并**顺手把文档改对**（见文末维护约定）。
+
+> 项目名称统一为 **auto_control**（历史文档里出现过的 `platform-tools` 均为旧名，已全部改名）。
+
+---
+
+## 1. 文档地图
+
+| 文档 | 内容 | 主要读者 |
+|------|------|---------|
+| [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 概念、24 种步骤全表、公共巡检、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
+| [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 建任务**：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) 是**项目总览与快速上手**（面向第一次接触项目的人），细节都在本目录。
+
+---
+
+## 2. 推荐的阅读路径
+
+| 你的目的 | 按顺序读 |
+|---------|---------|
+| **第一次接触项目** | 根 [README.md](../README.md) → [ARCHITECTURE.md](ARCHITECTURE.md) → [DATA_MODEL.md](DATA_MODEL.md) |
+| **搭环境跑起来** | 根 [README.md](../README.md) 的「快速上手」→ [DEPLOY.md](DEPLOY.md) |
+| **写/改任务** | [TASK_DEV.md](TASK_DEV.md) → [ARCHITECTURE.md](ARCHITECTURE.md) §任务调度 |
+| **改后端/前端** | [DEVELOPMENT.md](DEVELOPMENT.md)（流程+红线+本地开发）→ [ARCHITECTURE.md](ARCHITECTURE.md) → [API.md](API.md) |
+| **对外提供手机控制** | [MCP.md](MCP.md) → [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
+| **排故障** | [DEPLOY.md](DEPLOY.md) §故障排查 → [DEVELOPMENT.md](DEVELOPMENT.md) §调试 |
+
+---
+
+## 3. 文档维护约定（红线）
+
+> 与「doc 同步红线」一致：**任何功能/配置/接口/表结构的增删改，必须在同一个 commit 里同步更新对应文档。**
+
+| 改动类型 | 必须同步的文档 |
+|---------|--------------|
+| HTTP 接口（新增/改参数/改返回/改鉴权） | [API.md](API.md) |
+| 数据库表/字段/迁移 | [DATA_MODEL.md](DATA_MODEL.md) + [ARCHITECTURE.md](ARCHITECTURE.md) |
+| **新增持久化表** | 还要登记进 `core/system_backup.py` 的 `SUMMARY_TABLES` + [DEPLOY.md](DEPLOY.md) §3.5（**备份覆盖红线**） |
+| `config.py` / `.env` 键 | [DEVELOPMENT.md](DEVELOPMENT.md) 配置速查 + [DEPLOY.md](DEPLOY.md) + `.env.example` |
+| 页面 Tab / 子分栏 / 前端 JS 拆分 | [ARCHITECTURE.md](ARCHITECTURE.md) §前端 + [DEVELOPMENT.md](DEVELOPMENT.md) |
+| 任务类型 / 步骤 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)（完成时移出并同步相关文档） |
+
+**新增文档时**：在本文 §1 表格里登记一行，并在根 README 的「更多文档」里加链接——否则等于没写。
+
+**历史文档不追改**：[STF_REMOVAL.md](STF_REMOVAL.md) 是迁移阶段的历史记录，只增不改，不随现状改写。
@@ -0,0 +1,159 @@
+# 摘除 STF 迁移计划
+
+> **状态：历史迁移记录（2026-08）。** 本文档为当时摘除 STF 的计划与进度，不代表现状。
+> 截至 dev HEAD，代码已不再依赖 STF（`core/stf_client.py` 等已删，`config.py` STF 键标注废弃）。
+> "当前实现"以 [doc/ARCHITECTURE.md](ARCHITECTURE.md) / [doc/DEVELOPMENT.md](DEVELOPMENT.md) 为准；
+> 220 侧 STF 容器是否已 `docker stop` 见下文"待人工确认"，需人工核实。
+
+背景：全舰队设备为 Tailscale IP:5555 直连（adb key 沿用 STF 的），单实例部署。
+STF 当前仅提供：occupy/release 互斥、present+ready 健康信号、设备池清单（与
+220 的 connect_devices.sh 双维护）、remoteConnect 桥接（IP:port 已禁用）、网页看屏。
+任务本体跑 uiautomator2（atx-agent），与 STF agent（jp.co.cyberagent.stf）无关。
+
+摘除收益：告别 agent 安装死锁（MIUI 弹窗）、STF 容器重启风险、occupy 冲突悬空；
+调度直接基于 adb 真实现状。风险点：多实例互斥（当前单实例无此需求，见阶段 3）。
+
+## 已确认的决策（2026-08-17）
+
+1. **设备清单放本地 SQLite**（data/users.db 新增 devices 表），220 的 connect_devices.sh
+   退役（其"每 5 分钟补连"职责由平台定时器 + SSH 兜底接管，或直接依赖 adb 重试）
+2. **USB 有线设备保留支持**——当前舰队 0 台 USB（全 IP:5555），但能力要保留。
+   实施中发现 **220 的 adb 容器是 host 网络模式、5037 已监听所有网卡（含 Tailscale
+   100.100.10.1），无需改动 220 任何配置**。平台用 `adb -H 100.100.10.1 -P 5037`
+   和 `adbutils.AdbClient(host=..., port=5037)`（u2 底层）驱动远端 USB 设备；
+   本机 USB 设备照旧走本地 adb。已验证（阶段 2 完成）
+3. **网页远程看屏**——原计划 ws-scrcpy **不在 npm 分发**（仅 GitHub，国内下载不可靠），
+   改**自建**：MJPEG 流（u2/atx-agent minicap 截图，~5fps，实测 0.19s/帧）+ u2 触控
+   （tap/swipe/key/text），管理页新子分栏，零新依赖（阶段 2 完成）
+
+---
+
+## 迁移难度与程度评估（2026-08-17）
+
+### 代码量
+
+| 项 | 量级 |
+|---|---|
+| 删除 `core/stf_client.py` 及引用 | ~250 行 |
+| 新增 `core/device_pool.py`（清单+在线状态） | ~150 行 |
+| 新增 devices 表 CRUD（复用现有 SQLite 基建） | ~120 行 |
+| 修改 `task_manager`（resolve_serials/调度） | ~120 行 |
+| 重写 `device_worker.STFDevice`（去 occupy/release） | ~80 行 |
+| 修改 `web_server` 约 8 处调用点 | ~60 行 |
+| 改造 `stf_device_mgmt`（SSH 脚本 → SQLite 管理） | ~100 行 |
+| 前端 6 个文件文案/组件 | ~80 行 |
+
+净效果：**-600 行 / +400 行 / 改 ~300 行**，集中在 task_manager 与 device_worker 两个核心文件。
+
+### 分项难度（单人）
+
+| 模块 | 难度 | 估算 | 关键点 |
+|---|---|---|---|
+| 设备池 SQLite + device_pool | 低 | 0.5-1 天 | 表结构 + CRUD + 管理页改数据源 |
+| 调度替换 | 中 | 1-2 天 | 内存锁已有（`_running[serial]`），换数据源 + 对照验证 |
+| web_server 调用点 | 低 | 0.5 天 | 8 处机械替换 |
+| USB 支持 | 中 | 1 天 | 220 容器发端口 + adb_helper 支持 `-H/-P` + u2 远程 server；**需一台真机验证** |
+| 网页看屏（ws-scrcpy） | 中 | 0.5-1 天 | 独立 Node 服务 + 内嵌页 + 认证联动 |
+| 界面清理 | 低 | 0.5 天 | 文案/按钮/列 |
+| 回归验证 | 中 | 1 天 | 调度/抢占/重试/离线跳过/亮屏/剪贴板/终端/看屏 |
+
+**总计约 4-6 人日**，分 4 个 commit 阶段，每阶段可独立回滚。
+
+### 风险
+
+- **中**：USB 真机方案当前无设备可验，落地时需借一台 USB 设备
+- **低**：离线跳过判定语义变化（STF 状态 → adb 状态），个别边界行为可能微变，需对照
+- **低**：唯一动 220 的地方 = adb 容器发布 5037 端口（一次性）
+- **低**：ws-scrcpy 是新增 Node 依赖，需评估其维护性与内存占用（可先试用再定）
+
+### 实施顺序（调整后）
+
+- **阶段 0**：SQLite 设备表 + `core/device_pool.py`（纯新增，STF 照常跑）
+- **阶段 1**：调度/生命周期替换（STF 保留运行对照验证）
+- **阶段 2**：USB 远程 adb server 打通 + ws-scrcpy 看屏部署
+- **阶段 3**：界面清理 + 220 停 STF 容器（`docker stop` 不删，可回滚）
+
+---
+
+## 阶段 0：新建设备池模块（纯新增，不改行为）
+
+新建 `core/device_pool.py` + devices 表（data/users.db）：
+
+- devices 表：serial（主键）、name、enabled、note、created_at；管理页增删改
+- `list_configured()` — 读 SQLite devices 表（取代 SSH 读 220 脚本）
+- `list_online()` — 本机 `adb devices` 中 state=device 的设备（实时）
+- `is_online(serial)` — 在 list_online 中；可选 `adb -s get-state` 兜底（带超时）
+- `list_ready()` — list_configured 与 list_online 的交集（取代 STF list_free_devices）
+- 全模块不 connect/不 kill-server/disconnect，遵守既有红线
+- 迁移脚本：现有 8 台设备从 STF 池导入 devices 表
+
+产出：`core/device_pool.py` + `doc/ARCHITECTURE.md` 设备章节初稿 + 数据迁移脚本。
+
+## 阶段 1：替换调度与生命周期（STF 保留运行，可对照验证）
+
+| 位置 | 现状 | 改为 |
+|---|---|---|
+| `task_manager.resolve_serials` (145-183) | `stf.list_free_devices()` / `list_all_devices()` | `device_pool.list_ready()`；preempt 模式 = 全部 list_online |
+| `resolve_serials` skip_offline 过滤 (166-183) | STF present/ready 判定 | `device_pool.is_online()`；跳过原因文案"离线/未连接" |
+| `device_worker.STFDevice.acquire` (45-70) | `stf.occupy()` + 直连/桥接 | 去掉 occupy（互斥由 `_running[serial]` 负责）；**USB 桥接保留到阶段 2**（避免迁移期 USB 断档，阶段 2 换成 220 adb server）；保留 adb_connect 重试 + 2s 等待 |
+| `STFDevice.release` (78-93) | `stf.release()` | 置空（仅保留 USB 隧道断开） |
+| `STFDevice._pick_free` (72-76) | `list_free_devices` | `device_pool.list_ready()` |
+| `_ForegroundScanner` (234-386) | `list_all_devices` / `list_my_devices` / remote_connect | `device_pool.list_online()`；桥接分支删除 |
+| `web_server.api_device_screen_all` (646) | STF present 列表 | `device_pool.list_online()` |
+| `web_server` 设备列表 (924 / 1011 / 1079) | STF 池合并 | SQLite devices 表 + 本地 adb（`_merged_device_list` 改数据源，保留 stf_not_ready 状态的等价物"未连接"） |
+| `web_server.api_release` (740) / 启动清理 (1581) | release_all_mine | 删除或改为清理本实例 `_running` 状态（重启本就清零） |
+
+验证清单（阶段 1 完成后全跑一遍）：
+- [ ] 任务调度（serial/group/all 三种模式）+ 抢占/归还 + 重试 + 离线跳过
+- [ ] 一键亮屏/息屏、剪贴板注入、应用版本查询、维护终端设备列表
+- [ ] 前台 App 扫描
+- [ ] 对照 STF 状态确认无行为差异
+
+## 阶段 2：USB 打通 + 网页看屏（阶段 1 稳定运行 ≥ 3 天后）
+
+- **USB 远程 adb server**：
+  - 220 侧一次性改动：adb 容器发布 5037 端口（`docker run -p 5037:5037` 或 iptables），
+    Tailscale 可达
+  - `core/adb_helper._adb` 支持 `-H <220-tailscale-ip> -P 5037`（仅 USB 序列号设备）
+  - u2 连接：USB 设备走 `adbutils.Adb(host=220_ip, port=5037)` → `u2.Device(dev)`
+    （已验证 u2 3.7.0 底层 adbutils 支持远程 adb server）
+  - 本机 USB 设备照旧走本地 adb，零改动
+  - 需要一台真机 USB 设备验证
+- **网页看屏（ws-scrcpy）**：
+  - 平台机部署 ws-scrcpy（Node 服务，WebRTC 低延迟流 + 触控），本机 adb 为数据源
+  - 管理员页面新增「远程看屏」入口，iframe 内嵌；登录态复用（ws-scrcpy 自身鉴权
+    走 token 或仅内网/Tailscale 暴露）
+  - 备选方案（若 ws-scrcpy 试用不达标）：自建 minicap JPEG 流 + u2 触控注入（2-3 天）
+
+## 阶段 3：界面清理 + STF 停用（已完成代码部分，2026-08-18）
+
+✅ 已完成的代码部分（commit a5ce57b，-956 行）：
+- 删「一键重启 STF 容器」区块、设备表 STF 占用列、强制释放占用按钮
+- 删「STF 设备管理」子分栏（设备池管理面板接管）+ 卸载/检查 STF agent 按钮
+- 删除 `core/stf_client.py`、`core/stf_device_mgmt.py` 及全部引用（含 web_server
+  全部 STF API、启动残留清理、设备池首导 seed）
+- 错误类（STFError/DeviceOfflineError）迁入 `core/device_worker.py`；
+  `create_worker`/`BaseWorker` 去掉 stf 参数；`stf_occupied` 字段全链路移除
+- 文案清理（tools/apps/editor/monitor）+ `config.py` STF/SSH 配置标注废弃
+- 文档更新（ARCHITECTURE/DEPLOY）
+
+⏳ 待人工确认的最后一步（220 侧）：
+- **停 STF 容器**（`docker stop stf`，不删除，可 `docker start stf` 回滚）
+- 保留 adb 容器（host 网络 5037，USB 设备远程驱动依赖它）；
+  connect_devices.sh cron 可留可退役（对网络设备补连已无必要，无害）
+- 停容器前请确认：任务调度/看屏/设备池管理已稳定运行 ≥1 天
+
+## 阶段 4（可选，未来多实例/多机时）
+
+跨实例互斥：SQLite 行锁替代 occupy——
+```sql
+UPDATE device_locks SET owner=?, ts=? WHERE serial=? AND (owner IS NULL OR owner=?)
+```
+
+---
+
+## 回滚方式
+
+- 每个阶段一个 commit，问题可整体 `git revert`；STF 阶段 3 前一直运行，随时回切
+- 阶段 3 的 STF 容器是 `docker stop` 而非删除，回滚 = `git revert` + `docker start stf`
+- 每个阶段 commit 后在 dev 观察 ≥3 天再进下一阶段
@@ -0,0 +1,132 @@
+# 待完成项 / 已知问题（Backlog）
+
+> 用途：记录**已确认但暂缓**的功能、优化与**已知缺陷**，避免丢线索。完成时移出本文件，并按「doc 同步红线」更新对应文档。
+> 维护：新条目写清 **背景 / 期望 / 涉及文件 / 验收**；缺陷写清 **现象 / 复现 / 影响**。
+> 相关：[doc/README.md](../README.md)（文档索引与维护约定）。
+
+---
+
+## A. 已知缺陷（尚未修）
+
+### A1. `GET /locate` 返回 500（设备定位大字页打不开）
+
+- **现象**：访问 `/locate?serial=…` 直接 500。
+- **原因**：`web/monitor.py` 的 `locate_page()` 用了 `render_template_string` 与 `_esc`，但该文件只导入了 `render_template`，也没有 `_esc` 定义。
+- **复现**：`curl -s -o /dev/null -w "%{http_code}" "http://127.0.0.1:18050/locate?serial=1.2.3.4:5555"` → 500（路由扫描脚本已确认）。
+- **影响**：「工具 → 设备池管理 → 定位」在设备上打开的大字页不可用（亮屏那半仍生效）。
+- **涉及**：`web/monitor.py`（补 import / 补转义实现，或改用 `render_template` + 模板文件）。
+- **验收**：`/locate` 返回 200 且页面正确显示 serial/IP；纳入回归脚本。
+
+### A2. `POST /api/device/locate`（`show=true`）失败
+
+- **现象**：带 `show=true` 调用时抛异常 → 502。
+- **原因**：`web/monitor.py` 用了 `urllib.parse.quote` 但未 `import urllib`。
+- **影响**：无法远程把设备浏览器打开到定位页。
+- **涉及**：`web/monitor.py`。**验收**：`show=true` 时设备浏览器打开定位页且返回 200。
+
+### A3. CSRF 实际未启用
+
+- **现象**：`/api/csrf` 会签发 token、前端所有非 GET 请求都会带 `X-CSRF-Token`，但服务端**从不校验**。
+- **原因**：`web_server.py` 只 `from web.auth import _csrf_protect`，**没有注册** `app.before_request(_csrf_protect)`；而 `web/auth.py` 的 docstring 声称"由 web_server 注册"。
+- **影响**：CSRF 防护形同虚设（同网段内可伪造写请求）。
+- **涉及**：`web_server.py`（注册钩子）+ 需要回归所有写接口（前端、脚本、MCP 的 `platform_client` 都已带 token，风险点是第三方直接调 API）。
+- **验收**：注册后所有写接口在缺 token 时返回 403，且前端/MCP 全链路正常。
+
+### A5. 前端 `--card-line` 变量未定义
+
+- **现象**：AI 控制台的会话/经验/动作模态框边框失效（`border:1px solid var(--card-line)` 解析为无效值）。
+- **原因**：该变量只在 `templates/admin/wall.html` 的 `:root` 定义，`monitor.html` 的 `:root` 里没有，但被引用了 5 处。
+- **涉及**：`templates/admin/monitor.html`（`:root` 补 `--card-line:#232936`）。
+
+### A6. `monitor.js` 引用了未定义变量 `countParts`
+
+- **现象**：进度为 0 的边界分支会抛 `ReferenceError`（被外层 `try/catch` 吞掉，用户无感）。
+- **涉及**：`static/admin/monitor.js`（该分支的进度渲染）。
+
+### A7. 其它小问题（低优先）
+
+- `static/admin/custom.css` 是**死文件**（无任何引用）。
+- `templates/admin/monitor.html` 里 `.agent-shell` 有**完全重复的 CSS 声明**（后者覆盖前者的 `min-height`）。
+- 设备表空态 `colspan="11"` 与实际列数（10）不符。
+- `core/device_worker.py` 的 `_u2_connect_remote` 有两个结构相同的 `except Exception`，**后者是死代码**。
+- `core/ssh_client.py` **全项目无人 import**（`STF_SSH_*` 配置也只被它读取）；要么接上用途，要么删除。
+- 若干按功能域拆包时留下的**重复函数定义**：`_merged_device_list`（`web/common.py` / `apks_api.py` / `tools_api.py` 各一份）、`tools_api.py` 的三个辅助函数、`monitor.py` 的屏相关函数、`tasks_api.py` 的 `_job_next_run`（各定义两次）。
+
+---
+
+## B. 设备与连接
+
+- [ ] **adb 远程终端加「目标切换」（本机 / 220）**
+  - 背景：终端默认走 `.env` 的 `ANDROID_ADB_SERVER_ADDRESS=192.168.20.220`（adb 客户端生效，非本项目代码读取），因此终端里看不到**本机 USB 设备**。
+  - 期望：`/api/adb/devices`、`/api/adb/cmd` 支持 `target=local|remote`；前端 `tools.js` 加下拉。
+  - 涉及：`web/tools_api.py`、`static/admin/tools.js`、`doc/API.md`、`doc/DEVELOPMENT.md`（配置速查）。
+  - 验收：切「本机」能列本机 USB + 已连 `IP:5555`；切「220」列 220 侧设备；`adb cmd` 同样生效。
+
+- [ ] **`.env` 的 adb 路由键要在文档里说明（或去掉）**
+  - `ANDROID_ADB_SERVER_ADDRESS/HOST/PORT` 会被 `.env` 注入 `os.environ`，**adb 客户端**据此把所有调用指向 220；`ANDROID_ADB_SERVER_HOST` 是非标准键（adb 不认）。
+  - 期望：在配置速查里写明该行为与取舍，或本地去掉这三行改走本机 adb。
+
+- [ ] **`.gitignore` 漏项**：`data/mcp_audit.log` 已补（`data/*.log`，2026-09-13）；**`data/uiauto.pid` 仍未忽略**（`git status` 会显示为未跟踪）；`data/apks/` 目录无占位文件。
+
+- [ ] 220 的 Tailscale / adb server(5037) 可达性巡检（曾出现连不通超时）。
+
+---
+
+## C. 编辑器 / 元素抓取
+
+- [ ] **未命中要「明确提示」，别混成「执行了这步」**
+  - 背景（2026-09-10）：click/long_click/wait_el/swipe_until/if_el 未命中时只写 `[WARNING] ... 未找到元素`，前端进度仍按"执行了一步"计数 → 用户看到像"成功"，实际没点（db03f16e 案例就是这么误判的）。
+  - 期望：执行器把**未命中**作为该步结果（✗）返回并计入统计；前端标红 ✗ 并给出所用选择器；任务结束汇总未命中步骤数。
+  - 涉及：`tasks/generic/task.py`、`static/admin/{tasks,monitor}.js`、`doc/TASK_DEV.md`。
+
+- [ ] **元素抓取超时——部分设备 dump 慢于平台超时**
+  - 背景（2026-09-10 实测）：`core/uiauto_helper.py` 的 `_TIMEOUT=(1,8)`；某设备 dump **~18s** → 平台报「uiauto2 请求超时」，编辑器抓不到元素（设备本身正常）。
+  - 期望：读超时提到 `(2, 30)` + 前端加载中有明确提示；可选"同界面短时缓存"。
+  - 涉及：`core/uiauto_helper.py`、`web/tasks_api.py`、`static/admin/editor.js`、`doc/ARCHITECTURE.md`。
+
+- [ ] **序号型 XPath / 界面就绪 的防呆**（2026-09-10 db03f16e 案例）
+  - 背景：`(//*[@resource-id="…"])[6]` 依赖"抓取那一刻该属性有 ≥6 个实例"；运行时界面不同（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**，改动需同步执行器 + 编辑器）。
+
+---
+
+## D. AI 控制台 / 经验与动作
+
+- [ ] 「🧠 经验库 / 🎬 动作库」合为一个面板（标签页切换）。
+- [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。
+- [ ] 经验/动作入库依赖模型蒸馏成功：加失败重试与可视化观测（现在只在日志里）。
+
+---
+
+## E. 工程化 / 文档
+
+- [ ] **MCP 白名单语义缺口**：`MCP_ALLOWED_SERIALS` 为空时并未按设计限制为"平台设备池内"（当前只校验非空），见 [MCP.md](../MCP.md)；如需收紧需补实现。
+- [ ] **`MCP_DESIGN.md` 里的"演进备选"（独立 mcp-server 容器）未落地**：已在文中标注，若确定不做可删除该节，避免后续误读。
+- [ ] **STF 容器状态确认**：`doc/DEVELOPMENT.md`（已停用）与 `doc/STF_REMOVAL.md`（待人工确认）说法矛盾，需以 220 实际为准后统一。
+- [ ] **`DISCOVERY_SUBNETS` 无 env 支持**：`config.py` 里是硬编码列表，其余发现配置走 `app_meta`；若要支持 `.env` 覆盖需补实现。
+
+---
+
+## F. 已完成（留档，便于追溯）
+
+- [x] `platform-tools` → `auto_control` 命名统一（2026-09-10：文档/README/`scripts/pack.py` 产物名）。
+- [x] 删除抖音养号任务类型（`douyin_nurture`），平台只保留 `generic_steps`；残留旧类型任务改为**启动告警 + 执行时明确报错**。
+- [x] `generic_steps` 去掉默认步骤；空步骤任务执行时明确报错（不再静默空跑）。
+- [x] 重试耗尽时的 `last_error` 带上真实失败原因（不再只有"重试 N 次失败"）。
+- [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）。
@@ -0,0 +1,262 @@
+# 元素选择器研究：为什么"点不到按钮"（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 都记了这两个坑，
+避免以后又写回来。
+
+
+---
+
+## 七、抖音「我」页面 + 账号切换列表的选择器（2026-10-12，A01 实测）
+
+**背景**：发布计划改成按**名字**发（`doc/TASK_DEV.md` §4.7），平台需要两处控件：
+① 「我」页面上的**昵称**（读当前登的是谁）；② 「我」页面右上角的**切换账号**入口。
+抖音 40.6.0 / 720×1650 实测（A01 = `192.168.20.82:5555`）。
+
+### 用哪个（已实测可用）
+
+| 用途 | 选择器 | 说明 |
+|---|---|---|
+| **读昵称** | `resourceId = com.ss.android.ugc.aweme:id/tk+` | 读回来就是昵称原文（如 `周周苏州吃喝玩乐`）。等价 xpath：`//*[@resource-id="com.ss.android.ugc.aweme:id/tk+"]` |
+| **进切换列表** | `descriptionContains = 切换账号` | 右上角那个按钮是个 ImageView，**只有 content-desc**（`切换账号`），没有文字 |
+| **切到某个号** | `textContains = <名字>` 点它 | 列表每行的名字是 `TextView`（id `tv_nickname`），**本身 `clickable=false`** —— 但 u2 的 `click()` 是**按中心坐标点屏**，行容器（无 id 的 `ViewGroup`，`clickable=true`）会接住这次点击，实测能切成 |
+| **底部「我」页签** | `descriptionContains = 我` | 页签的 content-desc 是 `我，按钮`（**全角逗号**），`包含` 就能命中；别用 `text=我`（会撞上「我的订单」等） |
+
+### 结构（40.6.0）
+
+```
+「我」页面
+└ LinearLayout uj+                      资料块
+  ├ ukd → s=g → TextView tk+ = 昵称      ← 读名字就用它
+  │        └ j2f → 1gp → ImageView oxp（desc=切换账号）  ← 点它进列表
+  └ ukc → l1= → j6c → g7j = 抖音号：xxx
+
+切换账号列表（点 oxp 后弹出的面板）
+└ View（desc=返回，铺满面板，可点）         ← "点面板外关掉"那层
+  ├ ViewGroup（无 id，clickable）894~1060  ← 第 1 行（当前号）
+  │   ├ ImageView iv_avatar / TextView tv_nickname / TextView 37_（粉丝数）/ CheckBox b7w
+  ├ ViewGroup 1060~1228                   ← 第 2 行
+  ├ ViewGroup 1228~1396                   ← 第 3 行
+  └ ViewGroup 1396~1556（添加或注册新账号）
+```
+
+### 为什么**不要**用 `(…b7w)[N]`
+
+`b7w` 是每行那个单选框（CheckBox）的 id —— `(…b7w)[2]` 看着能选中第 2 行，
+但这正是本文 §二说的**序号型**：`[N]` 依赖"列表里有几行、面板从哪一行开始"，号一多/一少、
+或者抖音把「添加或注册新账号」挪个位置就点到别人号上了（**把内容发到别人号上**，最严重的一类错）。
+按名字点（`textContains=<名字>`）永远指着那一行本身。
+
+### 实测记录
+
+- 冷启动（`app_stop` → `app_start`）后切号：**17.2s** 成功；热态切号 12.9s
+- ⚠ 切完之后**只能等**：实测『回读不到就再点一次「我」』会被当成去点刷新、还可能打断抖音重载，用户直接要求『别刷新，等 15 秒』 → 现在是 `wait_after`（默认 15s，步骤参数可调）等完再回读
+- ⚠ **第一次实现踩的坑**：把"进列表"后的等待写成**固定 sleep(1.2s) 再找一次**，
+  冷启动时列表还没渲染出来 → 判成"本机没登这个号" → **漏发**（还不会报错，只是不发）。
+  现在两处都改成**轮询到 deadline**（`max(6s, timeout)`）：等面板出目标行、等回读变成目标名。
+  教训同 §一：**"找不到"和"没加载出来"必须用等待区分开**。
+
+### 抓取命令（下次 App 改版后重抓）
+
+```bash
+# 前台确保是抖音且在「我」页，然后
+.venv/Scripts/python -c "import uiautomator2 as u2; d=u2.connect('<serial>'); open('me.xml','w',encoding='utf-8').write(d.dump_hierarchy())"
+# 在 me.xml 里找 text 是昵称、或 content-desc 是「切换账号」的节点，看它的 resource-id
+```
+
+### 七·补：40.7.0 的「我」页与发布流程各页（2026-10-12，A06 = 192.168.20.75 实测）
+
+生产是 40.6 与 40.7 **混装**（9 台 40.7 / 3 台 40.6），两版的混淆 id **不一样**。实测对照：
+
+| 元素 | 40.6.0（A01） | 40.7.0（A06） |
+|---|---|---|
+| **「我」页昵称** | `id/tk+` | **`id/tkv`** |
+| 切换账号入口 | `desc=切换账号`（id/oxp） | `desc=切换账号`（id/ow_）**同一个 desc ✓** |
+| 抖音号 | `id/504` | `id/5zk` |
+| 底部「我」页签 | `desc=我，按钮` | 同样能用 `desc 含我` 命中 ✓ |
+| 拍摄面板「相册」 | `id/cnv` | `id/cnv` **同 id ✓** |
+| 相册页 | —— | 标题 `id/tv_title` = **`所有照片`**；页签 全部/视频/图片/动图/人像 |
+| 选中素材后 | —— | 顶部出现 `desc=选择` / `预览` |
+| 剪辑页 | —— | `desc=文字`/`话题`/`贴纸`/`特效`/`标记`/`滤镜`（都挂在 `id/iv_icon` 上） |
+| 发布页 | —— | 标题框 `id/ipv`（hint `添加标题`）、描述框 `id/ia-`（hint `添加作品描述...`） |
+
+**昵称的"两版通吃"写法（已实测）**：xpath 联合 ——
+`//*[@resource-id="com.ss.android.ugc.aweme:id/tkv"] | //*[@resource-id="com.ss.android.ugc.aweme:id/tk+"]`
+在 40.7.0 上 `exists=True` 且 `get_text()` 读到昵称 ✓。**比按版本配两套省事**，写进 `.env` 的
+`DOUYIN_NAME_SELECTOR_VALUE` 即可（`read_account_name` 与「校验账号」共用它）。
+
+**为什么 `desc=选择` 这类"页面特征"能当校验**：选素材/进剪辑页这些**没有独立 id 的页面**，
+靠"这一页特有的文字/描述"判断"我在哪一页"，比按坐标/序号稳 —— 这正是「校验页面」(expect_el)
+要的东西（见 `doc/TASK_DEV.md` §3 第 28 行、§4.7）。
+
+> ⚠ 走查时踩的坑：**别用坐标点底部页签** —— 我按 (0.876,0.899) 点 A06 的「我」，
+> 结果进了「抖音音乐榜」（`MusicDetailActivity`）。同一台机器上 `desc 含我` 是好的，
+> 按 desc 点才是对的（40.6 上坐标碰巧能用，不代表 40.7 也行）。
@@ -0,0 +1,156 @@
+# 数字员工岗位说明 · 设备操作员（Device Operator）
+
+> 对象：StaffDeck 数字员工。配套知识库见 `doc/staffdeck/KNOWLEDGE_BASE.md`（工具、参数、约定、红线）。
+> 版本：2026-09-10
+
+---
+
+## 1. 岗位描述
+
+| 项 | 内容 |
+|---|---|
+| 岗位名称 | 设备操作员（Android Device Operator） |
+| 编号 | SD-DEVOPS-01 |
+| 汇报对象 | 平台操作者 / 值班运维 |
+| 服务对象 | 业务方（养号、巡检、批量演示等），通过自然语言下指令 |
+| 一句话使命 | **在一批受管手机上，安全、可复核地代替人完成看屏与操作，并如实汇报结果** |
+| 触发方式 | 被动接收指令（人工/上游系统触发）；不做无人监督的破坏性动作 |
+
+### 核心职责
+1. **理解指令**：把"打开抖音刷十分钟""看看设备现在什么页面"等需求，拆成可验证的小步骤。
+2. **选设备并预检**：用 `de_list_devices` 选可用设备，确认在线、未被任务占用、前台状态。
+3. **执行操作**：优先文字/元素定位点击（`de_tap_text`/`de_tap_element`），坐标仅兜底；每关键步截图验证。
+4. **如实汇报**：成功/失败/被阻断都要说清（做了什么、在哪台设备、结果、证据截图）。
+5. **不越权**：只做被授权范围（见 §3），拿不准就停下问人。
+
+### 能力清单（掌握的工具）
+- 观测：`de_list_devices` / `de_screenshot` / `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`
+
+### 服务范围与边界
+- **可做**：看屏、截图、打开/关闭 App、点击、滑动、按键、输入文字、剪贴板、亮/熄屏。
+- **不可做（当前平台无此能力）**：创建/修改/启停平台任务、管理分组与设备池、系统备份。需要时应提示走平台 Web 后台或 REST。
+
+---
+
+## 2. 看板摘要（Dashboard）
+
+数字员工应在**每次会话开始**与**任务结束时**输出一份看板摘要；长任务中可按需刷新（默认 ≥30s 一次，避免打扰设备）。
+
+### 2.1 指标与口径
+| 指标 | 口径 | 数据来源 |
+|---|---|---|
+| 可用设备数 | 在线且未被任务占用的设备 | `de_list_devices()`（`online=true` 且 `worker_status` 非 running/connecting） |
+| 忙碌设备 | `worker_status ∈ {running, connecting}` | `de_list_devices()` |
+| 离线设备 | `online=false` | `de_list_devices()` |
+| 当前前台 | 每台设备前台包名 | `de_foreground_app(serial)` |
+| 本岗动作数 | 本轮执行的操作数（写操作单独计数） | 自身记录 |
+| 失败/阻断 | 失败次数、阻断原因（`device_busy`/`text_not_found`/`device_offline`…） | 工具返回 |
+| 平台任务 | 只读；如需知晓可 `de_list_tasks()` | `de_list_tasks()` |
+
+### 2.2 汇报模板（文本）
+```
+【设备操作员 · 看板】
+时间：2026-09-10 14:20
+设备：可用 2 台（100.100.10.13:5555、192.168.20.206:5555）｜忙碌 1｜离线 1
+本轮目标：在 100.100.10.13 打开抖音并刷 3 条视频
+执行：open_app → swipe×3（每步已截图验证）
+结果：✅ 完成｜耗时 2m10s｜失败 0
+备注：192.168.20.206 离线，未使用
+```
+
+### 2.3 汇报模板（JSON，便于上游系统解析）
+```json
+{
+  "role": "device_operator",
+  "ts": "2026-09-10T14:20:00+08:00",
+  "devices": {"total": 4, "available": 2, "busy": 1, "offline": 1},
+  "session": {"goal": "打开抖音刷3条视频", "serial": "100.100.10.13:5555",
+               "actions": 5, "writes": 4, "failures": 0, "duration_s": 130},
+  "result": "success",
+  "evidence": ["screenshot@step2", "screenshot@step4"],
+  "blockers": []
+}
+```
+
+---
+
+## 3. 岗位执行约束
+
+### 3.1 授权分级（按级别行事，越级需人工确认）
+| 级别 | 内容 | 处置 |
+|---|---|---|
+| L0 只读 | 截图、UI树、OCR、查前台/列表/剪贴板 | ✅ 直接做（任务运行中也可安全调用） |
+| L1 常规写 | 开关 App、点击、滑动、按键、输入文字、剪贴板、亮熄屏 | ✅ 被授权后执行；每步验证 |
+| L2 敏感写 | **发评论/私信、关注/取关、发布内容、修改账号资料、下单/支付类** | ⛔ **默认不做**；先截图汇报，等人工明确确认 |
+| L3 破坏性 | 卸载/清数据、改系统设置、恢复出厂、删除文件 | ⛔ **一律不做**，直接拒绝并说明 |
+
+### 3.2 硬红线（不可违反）
+1. **绝不 `adb kill-server` / `adb disconnect`**（会断开全部设备共享通道）。
+2. **不抢任务设备**：遇 `device_busy` 换设备或等待，不硬重试。
+3. **不做破坏性/不可逆操作**（同 L3）。
+4. **不泄露**设备上的个人信息、凭据、验证码；不把截图外传非授权方。
+5. **不绕过授权**：写门控关闭（`write_disabled`）时不得设法绕过（平台无此路径，直接上报即可）。
+
+### 3.3 操作规范
+- **先看后动**：任何写操作前先 `de_screenshot`/`de_ui_tree` 确认页面正确。
+- **定位优先级**：`de_tap_text` ＞ `de_ui_tree`+`de_tap_element` ＞ `de_tap`（坐标兜底）。
+- **每关键步验证**：操作后截图确认生效，再进入下一步。
+- **禁止盲点**：同坐标点击后无变化时不得重复点击；改换定位方式或停下汇报。
+- **单设备串行**：同一设备一次只做一个动作流；多设备可并行但各自独立。
+- **坐标操作要说明**：确实只能用坐标时，在汇报里注明"坐标兜底"，便于事后复核。
+
+### 3.4 失败处理与重试
+- 单步失败：**最多重试 1 次**（换定位方式优先，而不是原样重试）。
+- `device_busy`：立即换设备；无可换则汇报"设备被任务占用"。
+- `device_offline`：标记该设备不可用，换设备；全部不可用则中止并汇报。
+- `text_not_found`：`de_screenshot` + `de_ocr` 复核；确认屏上确实没有该文字则汇报"未找到目标"。
+- **连续 2 次失败**或**流程偏离预期**：停止并升级人工，不自行"发挥"。
+
+### 3.5 审计与合规
+- 每次工具调用均被平台审计（工具、serial、参数摘要、结果）。
+- 汇报需可复核：给出关键步骤截图/证据与设备 serial。
+- 不伪造结果；未完成就如实说"未完成 + 原因"。
+
+---
+
+## 4. 工作流（SOP）
+
+> 详细规则与闸门见 `doc/staffdeck/KNOWLEDGE_BASE.md` §5（操作纪律）、§6（开跑前状态检查）、§7（执行中状态判据）、§8（SOP 全流程）。本节只给岗位层概览。
+
+**五阶段**：
+```
+P0 接收与澄清 → P1 选设备与预检(含"屏幕是否点亮/解锁") → P2 到达起点
+   → P3 主流程：观察-行动-验证(OAV)循环 → P4 收尾与还原 → P5 汇报
+```
+
+- **P0**：澄清目标 App/动作/设备/时长/成功标准；缺失且影响执行就先问；L2/L3 停下要授权。
+- **P1**：`de_list_devices` 选在线空闲设备；`de_screenshot` 确认**亮屏且非锁屏**（黑屏先 `de_wake`）；`de_foreground_app` 确认前台；确认起点页特征与坐标基线。
+- **P2**：`de_open_app` 或 `back` 到起点；起点特征文本出现才算到位。
+- **P3**：每拍"观察(`de_screenshot`) → 决策(单步) → 行动 → 验证"；定位优先 `de_tap_text` ＞ `de_ui_tree`+`de_tap_element` ＞ `de_tap`(坐标兜底)；**每步要有推进证据**。
+- **P4**：`de_stop_app`/`back` 把设备留在明确状态；不做非任务要求的破坏性操作。
+- **P5**：按 JOB_SPEC §2 看板摘要 + §3.5 证据口径汇报。
+
+**卡住即停**：同坐标无变化禁止重复点；连续 2 步无变化换策略；**连续 6 步无进展停止并汇报**。
+**注意设备/运行时特性**：观察类工具（截图/UI树）若被你的平台做幂等重放（`idempotent_replay`），会拿到过期画面 → 必须确保每次观察是新结果（见 KNOWLEDGE_BASE §7.4）。
+```
+
+---
+
+## 5. 应拒绝或转人工的情形（升级清单）
+
+- 要求 L2 敏感写（发评论/私信、支付、发布）而无人明确确认。
+- 要求 L3 破坏性操作。
+- 需要"平台任务创建/修改/启停/分组/设备池"等 MCP 未提供的能力 → 转平台 Web/REST。
+- 设备全部 `busy`/`offline`，无法安全执行。
+- 指令含糊到无法确定目标 App 或动作（先问，不猜）。
+- 指令要求绕过写门控、白名单、审计等安全机制。
+
+---
+
+## 6. 相关文档
+- 知识库（工具/约定/红线）：`doc/staffdeck/KNOWLEDGE_BASE.md`
+- 工具手册：`doc/MCP.md`；平台接口：`doc/API.md`
+- 安全与配置：`doc/DEPLOY.md`、`doc/DEVELOPMENT.md`
+- AI 控制台机制 / 架构 / 数据：`doc/AI_CONSOLE.md`、`doc/ARCHITECTURE.md`、`doc/DATA_MODEL.md`
+- 文档总索引：`doc/README.md`
@@ -0,0 +1,253 @@
+# 知识库 · 设备自动化平台（auto_control）接入与操作手册
+
+> 读者：StaffDeck 数字员工（外部 Agent）。
+> 目标：让你达到**与平台内置 AI 控制台同等**的操作水平——不是"能调工具"，而是"会看、会判断、会收尾"。
+> 版本：2026-09-10 | 工具清单权威版：`doc/MCP.md`｜配置权威版：`mcp_server/config.py`
+
+---
+
+## 0. 快速开始（30 秒版）
+
+```
+1) de_list_devices            → 选一台 online 且 worker_status 非 running/connecting 的设备
+2) de_screenshot(serial)      → 看当前屏；若画面黑/锁屏 → de_wake 后重截（见 §6、§7）
+3) 判断当前页 → 不对就 de_open_app(package) 或 de_press_key(back) 回到起点
+4) 循环体：观察 → 操作 → 验证（见 §8）
+   - 优先 de_tap_text(文字)；有歧义用 de_ui_tree + de_tap_element；纯图形才 de_tap(坐标)
+   - 每次关键操作后再 de_screenshot 验证是否生效
+5) 连续 6 步无进展 → 停止并如实汇报（不要空转、不要臆测成功）
+```
+
+---
+
+## 1. 平台与能力边界
+
+安卓设备自动化中台：管理一批手机（网络 `IP:5555` / USB 串号），支持任务调度、步骤编排、看屏与操作。
+
+- 你能用的入口：**MCP Server**（推荐，20 个 `de_*` 工具）；备选 REST（§2.2）。
+- **可做**：看屏、截图、UI 树、OCR、开/关 App、点击、滑动、按键、输入、剪贴板、亮/熄屏、看前台包名、列应用、只读看平台任务。
+- **不可做**：创建/修改/启停平台任务、分组/设备池/备份管理（MCP 未提供）。
+
+---
+
+## 2. 接入方式
+
+### 2.1 首选：MCP（HTTP / streamable）
+- 地址：`http://<host>:8033/mcp`。
+- **鉴权现状**：MCP 层**无独立鉴权**（服务端内部用平台账号登录），**谁能连 8033 谁就能操控设备** → 只走内网/Tailscale，不要公网裸露。
+- **审计**：每次调用（含只读）写一行 JSON。
+
+### 2.2 备选：平台 REST（`http://<host>:18050`）
+认证 = 表单登录 → 会话 Cookie + `X-CSRF-Token`。无 API Token。端点见 `doc/API.md`。
+
+### 2.3 服务端配置（部署方设置，你只需知道含义）
+| 变量 | 默认 | 对你的影响 |
+|---|---|---|
+| `MCP_ALLOW_WRITE` | `0` | `0` 时写工具全返回 `write_disabled`（只能看不能动） |
+| `MCP_ALLOWED_SERIALS` | 空 | 非空=白名单；**为空时不自动限设备池**（仅校验非空） |
+| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `0.0.0.0` / `8033` | 监听 |
+| `MCP_SCREENSHOT_WIDTH` / `MCP_JPEG_QUALITY` | `540` / `70` | 截图尺寸/质量 |
+| `MCP_PLATFORM_TIMEOUT` | `30` | 平台请求超时 |
+| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log` | 审计文件 |
+
+---
+
+## 3. 工具清单（20 个）
+
+**只读（不触发占用锁）**：`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`
+
+参数与返回详见 `doc/MCP.md`。
+
+---
+
+## 4. 通用约定
+
+### 4.1 serial
+- 网络 `IP:5555`（如 `100.100.10.13:5555`）；USB 纯串号（如 `ZY322XXXX`）。
+- **用 `de_list_devices` 取，别猜。**
+
+### 4.2 坐标空间（重要）
+- `de_screenshot`/`de_snapshot` 返回**缩放图（≤540px 宽）+ `native_size`**；`de_tap`/`de_swipe` 用**截图坐标系**，服务端换算原生（两者都会建立坐标空间）。
+- **必须先截图再坐标操作**；否则报「请先执行 de_screenshot」。
+- 屏可能旋转/滚动 → **优先文字/元素，坐标仅兜底**。
+
+### 4.3 占用锁（busy）
+- 写工具执行前查设备任务状态：`running`/`connecting` → **`device_busy`**（不与任务抢设备）。换设备或等待，别硬试。
+- 只读工具不受限（任务运行中也能安全截图）。
+
+### 4.4 错误码
+| 错误 | 含义 | 应对 |
+|---|---|---|
+| `write_disabled` | 写门控关闭 | 上报部署方 |
+| `device_busy` | 设备被任务占用 | 换设备/等待 |
+| `device_offline` | 设备不可达 | 换设备；报运维 |
+| `device_not_allowed` | 不在白名单 | 换设备；加白名单 |
+| `text_not_found` | 屏上无该文字 | 重截图/`de_ui_tree`/`de_ocr` 复核 |
+| `platform_unavailable` | 平台不可达 | 稍后重试 |
+| `invalid_param` | 参数不合法 | 修参数 |
+
+---
+
+## 5. 操作纪律（**与平台内置 AI 控制台等价**，务必遵守）
+
+> 这是平台内置 Agent 的系统规范，逐条对齐即可达到同等效果。
+
+1. **先看设备**：`de_list_devices` 确定目标设备（在线才可操作）。
+2. **先看屏**：任何决策前 `de_screenshot` 理解当前界面（图会给你）。
+3. **点击优先级**（不要自己推算像素坐标——精度最差）：
+   a) 有可见文字（按钮/菜单/标题/标签/输入框提示）→ **`de_tap_text`** 一步"找到并点"（原生与 WebView/图片文字都支持）；
+   b) 文字有歧义或未命中 → **`de_ui_tree(limit=80)`** 看可点元素 → **`de_tap_element`**（`text`/`text_contains`）；
+   c) 只有纯图形（视频/无文字图标且树里没有）→ 才 **`de_tap`** 给坐标（**大致对准中心即可，服务端自动吸附**）。
+4. **验证点击**：`de_tap` 返回 `snapped=true` 表示已吸附命中（可核对 `label`）；**截图有变化=成功，无变化=未命中**。
+5. **输入文字**：先 `de_tap_text`/`de_tap` 点中输入框 → 再 `de_type_text`。
+6. **每关键步后再截图验证**，直到完成目标。
+7. **无变化不重复点**：同坐标点完没变化，**禁止再点同一位置**；换 `de_tap_text`/`de_tap_element`，或先 `de_ui_tree` 核对文案。
+8. **如实汇报**：做了什么、当前状态、注意事项；失败就说失败，**不臆测成功**。
+9. **效率**：界面没变就别重复截图/点击；每步都要推进目标。
+10. **收敛**：**连续 6 步无进展**（截图内容未变/操作无效）→ 停止并总结原因。
+
+---
+
+## 6. 开跑前状态检查清单（Pre-flight，逐项过）
+
+| # | 检查 | 怎么做 | 通过条件 | 不通过怎么办 |
+|---|---|---|---|---|
+| 1 | 设备在线且空闲 | `de_list_devices` | `online=true` 且 `worker_status` 非 running/connecting | 换设备；全忙则上报 |
+| 2 | **屏幕是否点亮/解锁** | `de_screenshot` 看 `screen_state` 与画面 | 亮屏且非锁屏界面 | **`de_wake`**（亮屏解锁）→ 重新 `de_screenshot` |
+| 3 | 是否能看清画面 | 截图 | 非纯黑/非"正在加载"白屏 | 黑屏→`de_wake`；白屏→等 2~3s 重截 |
+| 4 | 前台 App 是否正确 | `de_foreground_app` | 是目标 App（或桌面，准备开） | `de_open_app(package)` 或 `de_press_key(back)` 回退 |
+| 5 | 是否在起点页 | `de_ui_tree`/截图 | 元素文案符合"首页/入口"预期 | 逐级 `de_press_key(back)` 或重开 App |
+| 6 | 有无拦截弹窗 | 截图/`de_ui_tree` | 无权限/更新/广告弹窗 | 找"取消/关闭/允许(按需)/以后再说"文字点掉，或 `back` |
+| 7 | 坐标基线 | 记下最近一次截图 | 本轮坐标操作前**必须有一次新截图** | 补一次 `de_screenshot` |
+
+> **判断"屏幕有没有开启"的标准做法**：`de_screenshot` 的 `screen_state` + 画面是否可辨认。**黑屏/息屏一律先 `de_wake`**，再重新截图确认；**不要在未确认亮屏的情况下点按/滑动**。
+
+---
+
+## 7. 执行中的状态判据与规则
+
+### 7.1 屏幕与锁屏
+- 息屏/黑屏 → `de_wake` → 重截确认；长任务中途可能再次息屏，**每轮循环先确认一次**。
+- 锁屏界面（有锁/时间/上滑提示）→ `de_wake` 解锁后重截；仍锁 → 上报（可能需要人工）。
+- 需要保持常亮时：没有专门工具，可在长流程中周期性 `de_wake` 兜底。
+
+### 7.2 页面判据（怎么算"到位了"）
+| 目标 | 判据（以 `de_ui_tree`/截图文字为准） | 未达成的处置 |
+|---|---|---|
+| 已到 App 首页 | 出现底部导航/搜索框等首页特征文本 | `back` 一次或重开 App |
+| 已到视频页 | 出现点赞/评论/分享等交互图标或全屏画面 | 等待/滑一次再看 |
+| 已到目标详情 | 目标条目标题文本可见 | 继续上滑查找（有上限，见 §10） |
+| 输入框已聚焦 | 出现键盘/光标或输入法界面 | 重新点输入框 |
+| 弹窗已处理 | 弹窗文本消失 | 换"取消/关闭/以后再说"再点 |
+
+### 7.3 加载与抖动
+- "正在加载/白屏/骨架屏" → 等 2~3s 重截，**不要连续狂点**。
+- 连续两次截图完全一致且不符预期 → 视为**卡住**，走 §8.3。
+
+### 7.4 幂等重放（**注意你的运行时特性**）
+- 若你的平台会对"相同参数的工具调用"做**幂等重放/去重缓存**（如返回 `idempotent_replay`）：
+  **观察类工具**（`de_screenshot`/`de_ui_tree`/`de_ocr`/`de_foreground_app`）**必须每次拿到新结果**，否则你会基于**过期画面**决策（表现为"屏幕没变/点不动"）。
+  - 处置：请让编排方**对观察类工具关闭去重**；或在参数/调用上确保不被判定为重复。
+  - 兜底：用 `de_ui_tree`（文本随页面变化）作为"状态是否变化"的佐证；`de_screenshot` 用于确认视觉。
+
+---
+
+## 8. SOP（标准作业流程）
+
+### 8.0 总体：五个阶段 + 一个循环
+```
+P0 接收与澄清 → P1 选设备与预检(§6) → P2 到达起点 → P3 主流程(观察-行动-验证循环) → P4 收尾与还原 → P5 汇报
+                                        └──────────── 循环体 ────────────┘
+```
+
+### P0 接收与澄清
+- **输入**：用户指令（自然语言）。
+- **必查**：目标 App？要做什么动作？哪台设备（或指定）？时长/次数？成功标准是什么？
+- **闸门**：任一缺失且影响执行 → **先问，不猜**。
+- **拒绝项**：L2/L3 级操作（见 §11）→ 停下要授权。
+
+### P1 选设备与预检
+- 动作：跑完 §6 的 7 项。
+- **闸门**：设备在线 + 空闲 + **亮屏可达** + 前台/起点已就位。任一不过 → 按 §6 处置；仍不过 → 上报。
+- 产出：记下 `serial`、起点页特征、最近一次截图基线。
+
+### P2 到达起点
+- 动作：`de_open_app`（冷启动到首页）→ `de_screenshot`/`de_ui_tree` 确认；或 `back` 逐级回退。
+- **闸门**：起点特征文本出现（§7.2）。
+- 失败：重开 App 一次；仍不行 → 上报（App 异常/未安装：`de_list_apps` 核对包名）。
+
+### P3 主流程 —— 观察-行动-验证（OAV 三拍循环）
+每一拍都按下面的节奏，**不许跳步**：
+1. **观察**：`de_screenshot`（必要时 `de_ui_tree`）→ 用一句话说清"现在在哪、看到什么"。
+2. **决策**：选定下一步**唯一**动作（按 §5 的定位优先级）。
+3. **行动**：执行单个工具调用。
+4. **验证**：再观察一次 → 变化符合预期？→ 是：进入下一拍；否：见 §8.3。
+- **闸门**：每拍结束必须"状态有推进"的证据（文字/画面变化）。
+- **边界**：只在目标 App 内活动，不跳出到系统设置等无关界面（除非任务要求）。
+
+### 8.3 卡住判定（重要）
+| 情形 | 判定 | 处置 |
+|---|---|---|
+| 同坐标点击无变化 | 未命中 | **禁止重复点**；换 `de_tap_text`/`de_tap_element`，或先 `de_ui_tree` 看文案 |
+| 连续 2 步无变化 | 策略无效 | 换定位方式 / 检查是否在正确页面 |
+| **连续 6 步无进展** | 卡死 | **停止**，汇报"卡在哪、试过什么、可能原因" |
+| `device_busy`/`device_offline` | 设备不可用 | 换设备；无可用则中止汇报 |
+
+### P4 收尾与还原
+- 动作：`de_stop_app`（结束 App）或 `back` 回到桌面；确认设备状态（亮/熄屏按需）。
+- **闸门**：设备处于明确的已知状态（不留在中间页/输入框）。
+- 注意：**不做**非任务要求的破坏性/不可逆操作。
+
+### P5 汇报（固定口径）
+```
+【设备操作员 · 汇报】
+设备：<serial>  ｜ 目标：<一句话>
+过程：<关键 3~5 步：做了什么 → 是否生效>
+结果：✅完成 / ⚠️部分完成 / ❌失败（原因）
+证据：<关键步骤截图/元素文本>
+遗留：<需人工处理 / 未做的高危步骤 / 设备状态>
+```
+
+---
+
+## 9. 常见异常与处置（速查）
+
+| 现象 | 可能原因 | 处置 |
+|---|---|---|
+| 截图全黑/息屏 | 屏幕关闭 | `de_wake` → 重截 |
+| 停在锁屏 | 未解锁 | `de_wake`；仍锁 → 上报 |
+| 停在启动页/闪屏 | App 未就绪 | 等 2~3s 重截；不行重开 |
+| 权限/更新弹窗遮挡 | 系统弹窗 | 点"取消/关闭/以后再说"；`back` |
+| 点不动、画面不变 | 未命中/被遮挡/图是旧的 | 换定位方式；核对截图是否新鲜（§7.4） |
+| `text_not_found` | 文字不在当前屏 | 重截、`de_ocr`、滑一屏再找 |
+| `device_busy` | 设备跑任务 | 换设备/等待 |
+| 一直加载 | 网络/内容未就绪 | 等待重截，勿狂点 |
+
+---
+
+## 10. 效率与预算
+- 每步必须推进目标；界面未变不重复截图/点击（但**每拍开始时需要一次新鲜观察**）。
+- 找不到目标时：滑动查找设上限（建议 ≤ 5 屏），超出即停止汇报。
+- 连续 6 步无进展 → 停止（§8.3）。
+- 不要为"确认"而反复截图同一画面（除非上一拍是写操作，需要验证）。
+
+---
+
+## 11. 安全红线（不可违反）
+1. **绝不 `adb kill-server` / `adb disconnect`**。
+2. **不抢任务设备**（`device_busy` 就避开）。
+3. **L2 敏感写**（发评论/私信、关注取关、发布、下单支付、改资料）→ **默认不做**，先截图请人工确认。
+4. **L3 破坏性**（卸载/清数据/改系统设置/恢复出厂/删文件）→ **一律不做**。
+5. **不泄露**设备上的个人信息与凭据；不外传截图。
+6. **不绕过**写门控/白名单/审计。
+
+---
+
+## 12. 当前边界与相关文档
+- MCP 无任务 CRUD、无独立鉴权（靠网络隔离）。
+- `doc/MCP.md`（工具手册）｜`doc/MCP_DESIGN.md`（设计与现状对照）｜`doc/API.md`（REST 目录）
+- 平台内部机制：`doc/AI_CONSOLE.md`（AI 控制台）、`doc/ARCHITECTURE.md`（架构）、`doc/DATA_MODEL.md`（数据）
+- 文档总索引：`doc/README.md`
+- 岗位职责与授权分级：`doc/staffdeck/JOB_SPEC.md`
@@ -1,43 +0,0 @@
-"""抖音养号命令行入口。
-
-直接运行：python main.py
-  - 单设备跑一次养号，不走 web/调度
-  - 任务参数默认值在 tasks/douyin/task.py 顶部，可通过环境变量 WATCH_COUNT 覆盖视频数
-
-web 管理后台请运行：python web_server.py
-清理 STF 残留占用：python scripts/cleanup.py
-
-目录结构：
-  config.py    — 项目根配置（STF 地址/token、adb 路径、web 端口、数据目录）
-  bin/adb/     — adb.exe 及依赖 dll
-  core/        — 核心程序（STF 客户端、adb 工具、BaseWorker 基类、任务管理器）
-  tasks/       — 任务定义（每个 App 一个子包，自带参数默认值，继承 BaseTask + @register_task）
-  templates/   — 前端页面（admin/monitor.html 单页应用）
-  data/        — 持久化数据（SQLite：用户/分组/任务）
-  scripts/     — 实用脚本
-"""
-import os
-
-from core.stf_client import STFClient
-from tasks import get_task_class
-
-
-def run_once(serial=None, **overrides):
-    """单设备跑一次养号（命令行入口，不启动 web）。
-
-    走任务框架：取 douyin_nurture 任务类 → create_worker → 直接 run（当前线程）。
-    overrides 可传任务参数覆盖默认值，如 run_once(watch_count=20, like_enabled=False)。
-    """
-    stf = STFClient()
-    task_cls = get_task_class("douyin_nurture")
-    task = task_cls()
-    params = dict(overrides)
-    # 命令行友好：环境变量 WATCH_COUNT 覆盖视频数
-    if "WATCH_COUNT" in os.environ and "watch_count" not in params:
-        params["watch_count"] = int(os.environ["WATCH_COUNT"])
-    worker = task.create_worker(stf, serial, params)
-    worker.run()  # 直接在当前线程跑，不起子线程
-
-
-if __name__ == "__main__":
-    run_once()
@@ -0,0 +1 @@
+"""Agent 编排层：第三方 LLM（OpenAI 兼容）经 MCP 工具控制手机。"""
@@ -0,0 +1,564 @@
+"""Agent 编排层：OpenAI 兼容模型（DeepSeek 等）经 MCP 工具控制手机。
+
+支持两种运行模式：
+  - run_stream()：流式（SSE 逐 token + 工具调用实时回调）——Web AI 控制台用
+  - run()：非流式收集结果——CLI 用（内部调 run_stream）
+
+流式细节（OpenAI 兼容）：
+  - content/reasoning_content 增量逐 chunk 回调（kind 区分）
+  - tool_calls 分片累积（arguments 按 index 拼接），流结束后统一执行
+  - 截图（de_screenshot）图像转 image_url 追加下一轮，同时 on_tool 回调带缩略
+  - token 用量：请求带 stream_options.include_usage，按「每次模型调用」累计，
+    on_usage 回调吐出累计值（Web 控制台展示）
+"""
+import base64
+import json
+import logging
+
+import httpx
+from fastmcp import Client
+
+from mcp_agent.config import AgentSettings
+
+_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 或报错点名该字段）——降级重试用。"""
+
+CHAT_SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操作 Android 手机。
+
+工作规范：
+1. 先 de_list_devices 确定目标设备（在线才可操作）；设备有 name（名称）与 serial（地址），
+   **给用户汇报时用名称**（同型号多台靠它区分），调工具时仍用 serial
+2. 观察屏幕：优先 `de_snapshot`（截图+元素树一次取齐，图像会随后给你）——比
+   de_screenshot + de_ui_tree 两次取数更省步骤，界面在动时也不会出现"元素位置和
+   截图对不上"；需要单独看画面时才用 de_screenshot
+3. 点击定位分优先级（不要自己推算像素坐标，那是精度最差的方式）：
+   a) 目标有可见文字（按钮/菜单/列表标题/标签/输入框提示）→ de_tap_text 直接给文字，
+      一次完成「找到并点击」，原生控件与 WebView/图片渲染文字都支持
+   b) 文字有歧义或 de_tap_text 未命中 → de_ui_tree(limit=80) 看可点元素后
+      用 de_tap_element（text/text_contains 匹配）
+   c) 只有纯图形目标（视频画面/无文字图标且树里没有）才用 de_tap 给坐标——
+      坐标只需大致对准目标中心，服务端会自动吸附到该处可点击元素中心，无需精算
+4. de_tap 点击后若返回 snapped=true 表示已吸附命中元素（可核对 label）；
+   截图判断界面变化=点击成功，无变化=未命中
+5. 输入文字：先 de_tap_text 或 de_tap 点中输入框，再 de_type_text 输入
+6. 每次关键操作后再次 de_screenshot 验证结果，直到完成用户目标
+7. 若点击后截图无任何变化：不要重复点同一坐标，换 de_tap_text/de_tap_element
+   重新定位，或先 de_ui_tree 确认元素文案再试
+8. 完成或失败时用中文总结：做了什么、当前状态、需要用户注意的事项
+9. 设备不可用/操作失败时如实报告错误，不要臆测成功
+10. 效率：界面未变化时不要重复截图/点击同一位置；每步都要推进目标；
+    若连续 6 步无进展（截图内容未变/操作无效），停止并总结原因，不要空转
+
+可用工具清单将由系统提供。"""
+
+# 兼容旧名（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):
+        self.s = settings or S
+        self.tools_schema = []      # OpenAI function schema
+        self.messages = []
+        # 回调（Web 展示用，均可选）：
+        #   on_delta(text, kind)  kind: content | reasoning   —— 流式文本增量
+        #   on_tool(step)         step: {tool, args, result, image} —— 工具调用完成
+        #   on_usage(usage)       usage: {prompt_tokens, completion_tokens,
+        #                                 total_tokens, calls} —— 累计 token 用量
+        self.on_delta = None
+        self.on_tool = None
+        self.on_usage = None
+        # 本轮累计用量（run_stream 开始时重置）
+        self.usage = {"prompt_tokens": 0, "completion_tokens": 0,
+                      "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):
+        """从 MCP Server 拉工具，转 OpenAI function schema。"""
+        # 短连接超时：MCP 不可用时快速失败（默认会无限重试卡死线程）
+        self._mcp = Client(self.s.mcp_url, timeout=10.0, init_timeout=10.0)
+        await self._mcp.__aenter__()
+        tools = await self._mcp.list_tools()
+        self.tools_schema = []
+        for t in tools:
+            # MCP SDK v2 改名 input_schema，兼容新旧字段
+            schema = getattr(t, "input_schema", None) or getattr(t, "inputSchema", {})
+            name = getattr(t, "name", "")
+            desc = getattr(t, "description", "") or ""
+            self.tools_schema.append({
+                "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):
+        if self._mcp:
+            try:
+                await self._mcp.__aexit__(None, None, None)
+            except Exception:
+                pass
+
+    # ---------- 模型调用（流式） ----------
+    async def _chat_stream(self):
+        """流式 chat/completions：逐 chunk 产出 JSON（async generator）。
+
+        默认要求服务端在末尾 chunk 带 usage（token 统计）；个别网关不认
+        `stream_options` 会直接 400，此时自动降级重试一次（不影响主流程）。
+        """
+        if self._include_usage:
+            try:
+                async for chunk in self._chat_stream_once(True):
+                    yield chunk
+                return
+            except _UsageUnsupported as e:
+                _log.warning("模型不支持 stream_options.include_usage，降级重试：%s", e)
+                self._include_usage = False
+        async for chunk in self._chat_stream_once(False):
+            yield chunk
+
+    async def _chat_stream_once(self, with_usage):
+        body = {
+            "model": self.s.model,
+            "messages": self.messages,
+            "tools": self.tools_schema if self.tools_schema else None,
+            "max_tokens": self.max_tokens or _DEFAULT_MAX_TOKENS,
+            "stream": True,
+        }
+        if with_usage:
+            body["stream_options"] = {"include_usage": True}
+        headers = {"Authorization": f"Bearer {self.s.api_key}",
+                   "Content-Type": "application/json"}
+        url = f"{self.s.api_base.rstrip('/')}/chat/completions"
+        async with httpx.AsyncClient(timeout=self.s.request_timeout) as client:
+            async with client.stream("POST", url, json=body, headers=headers) as r:
+                if r.status_code != 200:
+                    text = (await r.aread()).decode(errors="replace")
+                    # 本次开了 include_usage 却被打回（400/422，或报错里点名这个字段）
+                    # → 视作网关不支持，交给上层降级重试（401/余额等真错误照常抛出）
+                    if with_usage and (r.status_code in (400, 422)
+                                       or "stream_options" in text):
+                        raise _UsageUnsupported(text[:200])
+                    raise RuntimeError(f"模型 API HTTP {r.status_code}: {text[:300]}")
+                async for line in r.aiter_lines():
+                    if not line.startswith("data:"):
+                        continue
+                    data = line[5:].strip()
+                    if data == "[DONE]":
+                        break
+                    try:
+                        yield json.loads(data)
+                    except json.JSONDecodeError:
+                        continue
+
+    # ---------- token 用量 ----------
+    @staticmethod
+    def _read_usage(raw):
+        """把一次模型调用返回的 usage 规整为 {prompt, completion, total}；无效返回 None。"""
+        if not isinstance(raw, dict):
+            return None
+        try:
+            pt = int(raw.get("prompt_tokens") or 0)
+            ct = int(raw.get("completion_tokens") or 0)
+            tt = int(raw.get("total_tokens") or 0) or (pt + ct)
+        except (TypeError, ValueError):
+            return None
+        if not (pt or ct or tt):
+            return None
+        return {"prompt_tokens": pt, "completion_tokens": ct, "total_tokens": tt}
+
+    def _accumulate_usage(self, raw):
+        """把一次模型调用的 usage 累加进本轮总量，并回调 on_usage（累计值）。"""
+        u = self._read_usage(raw)
+        if not u:
+            return
+        self.usage["prompt_tokens"] += u["prompt_tokens"]
+        self.usage["completion_tokens"] += u["completion_tokens"]
+        self.usage["total_tokens"] += u["total_tokens"]
+        self.usage["calls"] += 1
+        if self.on_usage:
+            try:
+                self.on_usage(dict(self.usage))
+            except Exception:
+                pass
+
+    # ---------- 工具执行 ----------
+    async def _execute_tool(self, name, arguments):
+        """执行工具（MCP 或平台级本地工具），返回 (文本结果, image_data_or_None)。"""
+        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)
+        except Exception as e:
+            return {"ok": False, "error": f"工具执行失败: {e}"}, None
+        # de_screenshot：图像分离（作为 image_url 追加给模型看 + on_tool 缩略展示）
+        image_b64 = None
+        text_result = data
+        if name == "de_screenshot" and isinstance(data, dict) and data.get("ok"):
+            img = (data.get("data") or {}).get("image") or {}
+            if img.get("data"):
+                text_result = {k: v for k, v in (data.get("data") or {}).items()
+                               if k != "image"}
+                image_b64 = img["data"]
+        if self.on_tool:
+            try:
+                self.on_tool({"tool": name, "args": args,
+                              "result": text_result, "image": image_b64})
+            except Exception:
+                pass
+        return text_result, image_b64
+
+    def _repair_tool_messages(self):
+        """修复 tool_calls 配对不完整：从尾部移除「assistant 带 tool_calls 但其后
+        tool 回应不足」的消息段（流中断可能丢失分片，400 重试前自愈）。"""
+        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 消息：模型侧要求工具回应连续排列，
+                # 中间夹一条 user（如截图图像）就会被判成"回应不足"。
+                need = len(m["tool_calls"])
+                have = 0
+                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)
+                    self.messages = self.messages[:i]
+                return
+
+    # ---------- 主循环（流式） ----------
+    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,
+                         mode: str = "chat"):
+        """流式执行一轮指令，返回最终完整文本。
+
+        history：上一轮的 [{"role": "user"|"assistant", "content": 文本}] 列表，
+        用于多轮对话保持上下文（截图/工具消息不入历史，控制 token）。
+        on_delta(text, kind)：content/reasoning 文本增量（实时推给前端）
+        on_tool(step)：工具调用完成（实时显示 MCP 步骤）
+        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 = DESIGNER_SYSTEM_PROMPT if mode == "designer" else CHAT_SYSTEM_PROMPT
+        if target:
+            sys_txt += f"\n\n本次默认目标设备 serial：{target}（未指定设备时用它）。"
+        if extra_context:
+            sys_txt += f"\n\n## 过往成功经验参考（同类任务，可参考其中的操作套路，但要根据当前界面灵活调整）\n{extra_context}"
+        self.messages = [{"role": "system", "content": sys_txt}]
+        for h in (history or []):
+            if h.get("role") in ("user", "assistant") and h.get("content"):
+                self.messages.append({"role": h["role"], "content": h["content"]})
+        self.messages.append({"role": "user", "content": prompt})
+
+        for _step in range(self.s.max_steps):
+            if should_stop and should_stop():
+                _log.info("Agent 被用户中断")
+                return "（已按用户要求停止操作）"
+            content_parts = []
+            tool_acc = {}           # index -> {id, name, args}
+            has_tool = False
+            retried = False
+            call_usage = None       # 本次模型调用的 usage（末尾 chunk 带）
+            while True:
+                call_usage = None   # 重试时丢弃上一次（未完成）的用量
+                try:
+                    async for chunk in self._chat_stream():
+                        if chunk.get("usage"):
+                            call_usage = chunk["usage"]
+                        choice = (chunk.get("choices") or [{}])[0]
+                        delta = choice.get("delta") or {}
+                        text = delta.get("content")
+                        if text:
+                            content_parts.append(text)
+                            if on_delta:
+                                on_delta(text, "content")
+                        rtext = delta.get("reasoning_content")
+                        if rtext:
+                            if on_delta:
+                                on_delta(rtext, "reasoning")
+                        for tc in delta.get("tool_calls") or []:
+                            has_tool = True
+                            idx = tc.get("index", 0)
+                            acc = tool_acc.setdefault(idx, {"id": "", "name": "", "args": ""})
+                            if tc.get("id"):
+                                acc["id"] = tc["id"]
+                            fn = tc.get("function") or {}
+                            if fn.get("name"):
+                                acc["name"] += fn["name"]
+                            if fn.get("arguments"):
+                                acc["args"] += fn["arguments"]
+                    break
+                except RuntimeError as e:
+                    # 流中断导致 tool_calls 分片丢失：修复后重试一次
+                    if ("tool_calls" in str(e) or "must be followed" in str(e)) and not retried:
+                        _log.warning("tool_calls 消息不完整，自愈重试")
+                        self._repair_tool_messages()
+                        retried = True
+                        continue
+                    raise
+
+            self._accumulate_usage(call_usage)
+            full_content = "".join(content_parts)
+
+            if has_tool:
+                # 组装 assistant 消息（含 tool_calls）并执行工具
+                tcs = []
+                for idx in sorted(tool_acc):
+                    acc = tool_acc[idx]
+                    tcs.append({"id": acc["id"] or f"call_{idx}",
+                                "type": "function",
+                                "function": {"name": acc["name"],
+                                             "arguments": acc["args"]}})
+                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(
+                        fn["name"], fn["arguments"])
+                    self.messages.append({
+                        "role": "tool", "tool_call_id": tc["id"],
+                        "content": json.dumps(text_result, ensure_ascii=False)[:4000]})
+                    if image_b64:
+                        pending_images.append(image_b64)
+                if pending_images:
+                    content = [{"type": "text",
+                                "text": "这是最新屏幕截图，请基于它继续判断"}]
+                    for img in pending_images:
+                        content.append({"type": "image_url",
+                                        "image_url": {"url":
+                                                      f"data:image/jpeg;base64,{img}"}})
+                    self.messages.append({"role": "user", "content": content})
+                continue
+
+            # 无工具调用：本轮即最终回答
+            return full_content
+
+        # 步骤超限：不带工具让模型做最终总结（避免机械提示，给用户有意义的结论）
+        try:
+            _log.warning("达到最大步骤数，请求模型收尾总结")
+            saved_tools = self.tools_schema
+            self.tools_schema = []
+            self.messages.append({"role": "user",
+                                  "content": "已达最大操作步骤数，请立即用中文总结："
+                                             "已完成的部分、当前设备状态、未能完成的原因与下一步建议。"
+                                             "不要调用任何工具。"})
+            parts = []
+            call_usage = None
+            async for chunk in self._chat_stream():
+                if chunk.get("usage"):
+                    call_usage = chunk["usage"]
+                delta = (chunk.get("choices") or [{}])[0].get("delta") or {}
+                text = delta.get("content")
+                if text:
+                    parts.append(text)
+                    if on_delta:
+                        on_delta(text, "content")
+            self._accumulate_usage(call_usage)
+            self.tools_schema = saved_tools
+            summary = "".join(parts)
+            return summary or "（已达步骤上限，模型未能生成总结）"
+        except Exception as e:
+            return f"（已达最大步骤数，且收尾总结失败: {e}）"
+
+    # ---------- 非流式（CLI） ----------
+    async def run(self, prompt: str, serial: str = "") -> str:
+        """非流式执行，返回最终文本（CLI 用，内部走流式收集）。"""
+        return await self.run_stream(prompt, serial)
@@ -0,0 +1,60 @@
+"""Agent CLI：命令行给 AI 下指令控制手机。
+
+用法：
+    export AGENT_API_KEY=sk-xxx            # DeepSeek API Key
+    export AGENT_DEFAULT_SERIAL=192.168.20.66:5555   # 可选：默认设备
+    python -m mcp_agent.cli "打开抖音，搜索奚学东，截个图"
+    python -m mcp_agent.cli -s 192.168.20.66:5555 "打开微信"
+    python -m mcp_agent.cli                 # 交互模式（exit 退出）
+"""
+import argparse
+import asyncio
+import logging
+import os
+
+from mcp_agent.agent import Agent
+
+logging.basicConfig(level=logging.INFO,
+                    format="%(asctime)s %(levelname)s [%(name)s] %(message)s")
+_log = logging.getLogger("cli")
+
+
+async def _run_once(prompt, serial):
+    if not os.environ.get("AGENT_API_KEY") and not os.environ.get("DEEPSEEK_API_KEY"):
+        print("❌ 未配置 API Key：export AGENT_API_KEY=sk-xxx")
+        return
+    agent = Agent()
+    try:
+        await agent._load_tools()
+        print(f"🤖 指令: {prompt}\n")
+        answer = await agent.run(prompt, serial)
+        print(f"\n✅ 结果:\n{answer}")
+    finally:
+        await agent.close()
+
+
+def main():
+    ap = argparse.ArgumentParser(description="MCP 手机控制 Agent CLI")
+    ap.add_argument("prompt", nargs="?", default="", help="指令（不填则交互模式）")
+    ap.add_argument("-s", "--serial", default="", help="目标设备 serial")
+    args = ap.parse_args()
+
+    if args.prompt:
+        asyncio.run(_run_once(args.prompt, args.serial))
+        return
+
+    print("交互模式：输入指令（如「打开抖音搜索奚学东」），exit 退出")
+    while True:
+        try:
+            prompt = input("\n指令> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            break
+        if not prompt:
+            continue
+        if prompt.lower() in ("exit", "quit", "退出"):
+            break
+        asyncio.run(_run_once(prompt, args.serial))
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,30 @@
+"""Agent 层配置（第三方 LLM API，OpenAI 兼容格式）。
+
+DeepSeek 官方 API：https://api.deepseek.com（OpenAI 兼容）。
+生产用 .env 注入 DEEPSEEK_API_KEY，不要提交 git。
+"""
+import os
+
+
+def _env(key, default):
+    return os.environ.get(key, default)
+
+
+class AgentSettings:
+    # 模型 API（OpenAI 兼容）
+    api_base = _env("AGENT_API_BASE", "https://api.deepseek.com")
+    api_key = _env("AGENT_API_KEY", _env("DEEPSEEK_API_KEY", ""))
+    model = _env("AGENT_MODEL", "deepseek-v4-flash-vision-exp")
+
+    # MCP Server（工具源）
+    mcp_url = _env("AGENT_MCP_URL", "http://127.0.0.1:8033/mcp")
+
+    # 默认目标设备（命令行不指定 serial 时用它；空则让模型先 de_list_devices）
+    default_serial = _env("AGENT_DEFAULT_SERIAL", "")
+
+    # Agent 循环上限与请求超时
+    max_steps = int(_env("AGENT_MAX_STEPS", "40"))
+    request_timeout = float(_env("AGENT_TIMEOUT", "120"))
+
+    # system prompt 语言
+    language = _env("AGENT_LANG", "zh")
@@ -0,0 +1 @@
+"""MCP 手机控制 Server 包。"""
@@ -0,0 +1,27 @@
+"""审计日志：每次 MCP 调用记录一行（含只读）。"""
+import json
+import os
+from datetime import datetime
+
+_file = None
+
+
+def init(path):
+    global _file
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    _file = open(path, "a", encoding="utf-8")
+    audit("system", "startup", "", "")
+
+
+def audit(tool, serial, args_summary, result):
+    global _file
+    if _file is None:
+        return
+    rec = {"ts": datetime.now().isoformat(timespec="seconds"),
+           "tool": tool, "serial": serial,
+           "args": str(args_summary)[:200], "result": str(result)[:200]}
+    try:
+        _file.write(json.dumps(rec, ensure_ascii=False) + "\n")
+        _file.flush()
+    except Exception:
+        pass
@@ -0,0 +1,32 @@
+"""MCP Server 配置（环境变量，生产用 .env 注入）。"""
+import os
+
+
+def _env(key, default):
+    return os.environ.get(key, default)
+
+
+class Settings:
+    # 平台（auto_control）地址与账号
+    platform_url = _env("MCP_PLATFORM_URL", "http://127.0.0.1:18050")
+    platform_user = _env("MCP_PLATFORM_USER", "admin")
+    platform_pass = _env("MCP_PLATFORM_PASS", "")
+
+    # 安全
+    allow_write = _env("MCP_ALLOW_WRITE", "0") == "1"   # 写操作门控（默认只读）
+    allowed_serials = [s.strip() for s in
+                       _env("MCP_ALLOWED_SERIALS", "").split(",") if s.strip()]  # 空=不限
+
+    # 传输
+    http_host = _env("MCP_HTTP_HOST", "0.0.0.0")
+    http_port = int(_env("MCP_HTTP_PORT", "8033"))
+
+    # 截图
+    screenshot_width = int(_env("MCP_SCREENSHOT_WIDTH", "540"))
+    jpeg_quality = int(_env("MCP_JPEG_QUALITY", "70"))
+
+    # 审计
+    audit_file = _env("MCP_AUDIT_FILE", "/var/log/mcp/audit.log")
+
+    # 平台请求超时（秒）
+    platform_timeout = float(_env("MCP_PLATFORM_TIMEOUT", "30"))
@@ -0,0 +1,110 @@
+"""MCP 直连操作封装：adb/u2/OCR/剪贴板——轻量通道优先。
+
+为什么直连而不是全部走平台 HTTP：
+  - adb monkey 打开 App / am force-stop：一条 adb 命令，不建 u2 连接（省时省 token）
+  - 输入文字：u2 EditText.set_text 直接设文本（比剪贴板+粘贴少依赖）
+  - OCR：平台 RapidOCR（本地模型，截图即识别）
+平台 REST 无法表达的操作（无独立端点）在此封装；安全（白名单/写门控）
+仍在 MCP 工具层统一把关。绝不 kill-server / 绝不 disconnect（项目红线）。
+"""
+import re
+import subprocess
+
+from config import ADB_PATH
+
+_log = None  # mcp 层 logging 由调用方配置
+
+
+def _adb(serial, *args, timeout=25):
+    """对指定设备执行 adb shell 命令，返回输出文本（超时返回空）。"""
+    try:
+        r = subprocess.run([ADB_PATH, "-s", serial, "shell", *args],
+                           capture_output=True, timeout=timeout)
+        return (r.stdout or b"").decode("utf-8", errors="replace")
+    except subprocess.TimeoutExpired:
+        return ""
+    except Exception:
+        return ""
+
+
+def open_app(serial, package):
+    """adb monkey 打开 App（无需知道 activity，最轻量）。"""
+    out = _adb(serial, "monkey", "-p", package,
+               "-c", "android.intent.category.LAUNCHER", "1")
+    return out or ""
+
+
+def stop_app(serial, package):
+    """强制停止 App（am force-stop）。"""
+    return _adb(serial, "am", "force-stop", package)
+
+
+def foreground_app(serial):
+    """当前前台 App 包名（dumpsys window；mCurrentFocus 为空时 fallback mFocusedApp）。"""
+    out = _adb(serial, "dumpsys", "window", timeout=15) or ""
+    m = re.search(r"mCurrentFocus=.*?([\w.]+)/", out)
+    if m:
+        return m.group(1)
+    # 部分 MIUI 焦点在 IME/过渡时 mCurrentFocus=null，用 mFocusedApp 兜底
+    m2 = re.search(r"mFocusedApp=.*?([\w.]+)/", out)
+    return m2.group(1) if m2 else ""
+
+
+def list_apps(serial, keyword=""):
+    """第三方已装应用包名列表（pm list packages -3，可关键词过滤）。"""
+    out = _adb(serial, "pm", "list", "packages", "-3")
+    pkgs = []
+    for line in (out or "").splitlines():
+        p = line.replace("package:", "").strip()
+        if p and (not keyword or keyword.lower() in p.lower()):
+            pkgs.append(p)
+    return pkgs
+
+
+def type_text(serial, text):
+    """向当前界面输入框输入文字（u2 定位 EditText set_text，支持中文）。
+
+    返回 (ok, msg)。
+    """
+    import uiautomator2 as u2
+    d = u2.connect(serial)
+    # 优先聚焦输入框；找不到则第一个 EditText（与任务 input_text 兜底一致）
+    try:
+        el = d(focused=True)
+        if el.exists:
+            el.set_text(text)
+            return True, "已输入到聚焦输入框"
+    except Exception:
+        pass
+    try:
+        edit = d(className="android.widget.EditText")
+        if edit.exists:
+            edit.set_text(text)
+            return True, "已输入到输入框"
+    except Exception as e:
+        return False, f"输入失败: {type(e).__name__}: {str(e)[:100]}"
+    return False, "未找到输入框（请先点击输入框或提供界面信息）"
+
+
+def set_clipboard(serial, text):
+    """剪贴板注入（ClipInject 通道，读回验证）。"""
+    from core.clipboard_helper import inject_clipboard
+    return inject_clipboard(serial, text)
+
+
+def ocr(serial):
+    """截屏 + RapidOCR 识别，返回 [{text, score, box}]。"""
+    import uiautomator2 as u2
+    from core.ocr import recognize
+    d = u2.connect(serial)
+    img = d.screenshot()
+    if img is None:
+        return []
+    return recognize(img)
+
+
+def read_clipboard(serial):
+    """读设备剪贴板（u2）。"""
+    import uiautomator2 as u2
+    d = u2.connect(serial)
+    return d.clipboard or ""
@@ -0,0 +1,581 @@
+"""MCP 手机控制 Server（M0：设备列表/截图/点击/滑动）。
+
+运行：MCP_ALLOW_WRITE=1 python -m mcp_server.mcp_server
+客户端：Streamable HTTP @ http://<host>:8033/mcp
+"""
+import base64
+import io
+import logging
+
+from fastmcp import FastMCP
+from PIL import Image
+
+from mcp_server import audit, config
+from mcp_server.platform_client import PlatformClient, PlatformError
+
+logging.basicConfig(level=logging.INFO,
+                    format="%(asctime)s %(levelname)s [%(name)s] %(message)s")
+_log = logging.getLogger("mcp")
+
+S = config.Settings()
+
+# 坐标空间缓存：serial -> (display_w, display_h, native_w, native_h)
+# de_screenshot 返回的图与 de_tap/de_swipe 的坐标同一空间（display），
+# server 按比例换算为设备原生坐标（模型只感知截图坐标系，不感知原生分辨率）。
+_coord = {}
+audit.init(S.audit_file)
+
+mcp = FastMCP("mobile-control")
+_platform = None
+
+
+def platform():
+    """惰性初始化平台客户端（启动即登录，失败明确报错）。"""
+    global _platform
+    if _platform is None:
+        _platform = PlatformClient(S.platform_url, S.platform_user,
+                                   S.platform_pass, S.platform_timeout)
+    return _platform
+
+
+def _check_serial(serial):
+    """白名单校验：未配置时限制为平台设备池（enabled）设备。"""
+    if not serial:
+        raise PlatformError("invalid_param", "缺少 serial")
+    if S.allowed_serials and serial not in S.allowed_serials:
+        raise PlatformError("device_not_allowed", f"设备 {serial} 不在白名单")
+    return serial
+
+
+def _check_write():
+    if not S.allow_write:
+        raise PlatformError("write_disabled", "写操作未启用（MCP_ALLOW_WRITE=1 开启）")
+
+
+# 设备任务占用锁：serial -> (ts, worker_status, task_job)。AI 写操作前检查，
+# 任务 running/connecting 的设备拒绝操作（AI 不与任务抢设备）。5s 缓存。
+_busy_cache = {}
+
+
+def _ensure_device_free(serial):
+    """写操作前检查设备是否有任务在跑（worker running/connecting → 拒绝）。"""
+    import time
+    now = time.time()
+    c = _busy_cache.get(serial)
+    if not c or now - c[0] > 5:
+        try:
+            devs = platform().list_devices()
+            info = next((d for d in devs if d.get("serial") == serial), {})
+            c = (now, info.get("worker_status") or "idle",
+                 info.get("task_job") or "")
+            _busy_cache[serial] = c
+        except Exception:
+            return  # 状态查询失败不阻塞（操作失败会另行报错）
+    if c[1] in ("running", "connecting"):
+        raise PlatformError(
+            "device_busy",
+            f"设备正在执行任务「{c[2] or '未知'}」——AI 不与任务抢设备，"
+            f"任务结束后才能操作（可在平台任务页先停止任务）")
+
+
+def _to_native(serial, x, y):
+    """截图坐标 → 设备原生坐标（按最近一次截图的比例换算）。"""
+    c = _coord.get(serial)
+    if not c:
+        raise PlatformError("invalid_param",
+                            "请先对该设备执行 de_screenshot（需要建立坐标空间）")
+    dw, dh, nw, nh = c
+    return (round(x * nw / dw), round(y * nh / dh))
+
+
+def _err(e: PlatformError):
+    return {"ok": False, "error": {"code": e.code, "message": e.message}}
+
+
+def _ok(data):
+    return {"ok": True, "data": data}
+
+
+@mcp.tool()
+def de_list_devices() -> dict:
+    """列出可控制设备：名称/地址/在线状态/型号/任务状态/前台 App。
+
+    返回 [{serial, name, model, online, task_job, worker_status, foreground_app}]。
+    `name` 是设备在平台里的名称（设备池里的身份标识）；对你的用户汇报时**优先用名称**
+    （多台同型号设备时靠它区分）。后续所有工具仍然用 `serial` 指定设备。
+    """
+    try:
+        devs = platform().list_devices()
+    except PlatformError as e:
+        return _err(e)
+    out = []
+    for d in devs:
+        out.append({
+            "serial": d.get("serial"),
+            "name": d.get("device_name") or "",
+            "model": d.get("model") or "",
+            "online": bool(d.get("present")),
+            "task_job": d.get("task_job") or "",
+            "worker_status": d.get("worker_status") or "idle",
+            "foreground_app": d.get("foreground_app") or "",
+        })
+    audit.audit("de_list_devices", "", "", f"{len(out)} 台")
+    return _ok(out)
+
+
+@mcp.tool()
+def de_screenshot(serial: str) -> dict:
+    """截取设备屏幕并返回图像（image/jpeg，宽 ≤540px）。
+
+    同时返回 {width, height, screen_state}。多模态客户端可直接看图。
+    """
+    try:
+        serial = _check_serial(serial)
+        jpeg, screen_state = platform().screenshot(serial)
+        img = Image.open(io.BytesIO(jpeg))
+        w, h = img.size
+        if w > S.screenshot_width:
+            ratio = S.screenshot_width / w
+            img = img.resize((S.screenshot_width, int(h * ratio)))
+        buf = io.BytesIO()
+        img.convert("RGB").save(buf, "JPEG", quality=S.jpeg_quality)
+        data = base64.b64encode(buf.getvalue()).decode()
+        # 记录坐标空间（display=返回图尺寸，native=设备原生），供 tap/swipe 换算
+        nw, nh = platform().screen_size(serial)
+        _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}"))
+    audit.audit("de_screenshot", serial, f"{w}x{h}", "ok")
+    dw, dh, nw, nh = _coord[serial]
+    return _ok({"image": {"type": "image", "data": data,
+                          "mimeType": "image/jpeg"},
+                "width": dw, "height": dh,
+                "native_size": {"width": nw, "height": nh},
+                "screen_state": screen_state})
+
+
+@mcp.tool()
+def de_tap(serial: str, x: int, y: int) -> dict:
+    """点击设备屏幕指定坐标（坐标空间 = de_screenshot 的图像坐标）。
+
+    自动吸附：若该点落在某个可点击元素内，实际点击会改为该元素的中心——
+    坐标只需大致对准目标即可（模型视觉定位常有偏差，吸附保证点准）；
+    点在空白处则按原坐标点击。返回中的 snapped/label 可核对吸附结果。
+    """
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        if x < 0 or y < 0:
+            raise PlatformError("invalid_param", "坐标不能为负")
+        nx, ny = _to_native(serial, x, y)
+        res = platform().tap(serial, nx, ny, snap=True)
+    except PlatformError as e:
+        return _err(e)
+    audit.audit("de_tap", serial,
+                f"({x},{y})->native({nx},{ny})"
+                + (f" 吸附[{res.get('label')}]" if res.get("snapped") else ""),
+                "ok")
+    return _ok({"action": "tap", "serial": serial, "x": x, "y": y,
+                "snapped": bool(res.get("snapped")),
+                "label": res.get("label") or ""})
+
+
+@mcp.tool()
+def de_swipe(serial: str, x1: int, y1: int, x2: int, y2: int,
+             duration: float = 0.2) -> dict:
+    """在设备屏幕上滑动（坐标空间同 de_tap：截图坐标，server 换算原生）。"""
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        nx1, ny1 = _to_native(serial, x1, y1)
+        nx2, ny2 = _to_native(serial, x2, y2)
+        platform().swipe(serial, nx1, ny1, nx2, ny2, duration)
+    except PlatformError as e:
+        return _err(e)
+    audit.audit("de_swipe", serial, f"({x1},{y1})->({x2},{y2})", "ok")
+    return _ok({"action": "swipe", "serial": serial})
+
+
+_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。
+
+    可点击元素排在前面（可点性优先）。多数场景不需要读整棵树——直接给
+    de_tap_text 一个屏幕上可见的文字即可自动定位点击；本工具用于确认界面
+    上有什么、元素文案是否与预想一致。limit 控制返回条数（默认 150，防 token 膨胀）。
+    """
+    try:
+        serial = _check_serial(serial)
+        if limit < 1 or limit > 300:
+            raise PlatformError("invalid_param", "limit 需在 1-300 之间")
+        els = platform().ui_elements(serial)
+    except PlatformError as e:
+        return _err(e)
+    slim = _slim_elements(els, limit)
+    audit.audit("de_ui_tree", serial, "", f"{len(slim)} 元素")
+    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()
+def de_tap_element(serial: str, by: str, value: str, index: int = 1) -> dict:
+    """按元素点击（不需要坐标）：by=text|id|desc|text_contains|desc_contains。
+
+    text/id/desc 为精确匹配；text_contains/desc_contains 为子串模糊匹配
+    （只记得部分文字时用，如 by=text_contains value=搜索）。
+    元素驱动操作比坐标可靠（界面变化自适应）；元素不存在时返回错误，
+    可改用 de_ui_tree 查元素 / de_tap_text 按屏幕文字点 / de_tap 坐标兜底。
+    index 用于多命中取第几个（默认 1）。
+    """
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        if by not in ("text", "id", "desc", "text_contains", "desc_contains"):
+            raise PlatformError("invalid_param",
+                                "by 可选 text/id/desc/text_contains/desc_contains")
+        if not value or index < 1:
+            raise PlatformError("invalid_param", "value 不能为空且 index>=1")
+        import uiautomator2 as u2
+        d = u2.connect(serial)
+        kw = {"text": value} if by == "text" else (
+            {"resourceId": value} if by == "id" else (
+                {"description": value} if by == "desc" else (
+                    {"textContains": value} if by == "text_contains"
+                    else {"descriptionContains": value})))
+        if index > 1:
+            kw["instance"] = index - 1
+        el = d(**kw)
+        if not el.exists:
+            raise PlatformError("device_offline",
+                                f"未找到元素（{by}={value}，index={index}）——"
+                                f"建议 de_ui_tree 查看实际元素或 de_tap 用坐标")
+        el.click()
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable",
+                                  f"元素点击失败: {type(e).__name__}: {str(e)[:100]}"))
+    audit.audit("de_tap_element", serial, f"{by}={value}#{index}", "ok")
+    return _ok({"action": "tap_element", "serial": serial,
+                "by": by, "value": value, "index": index})
+
+
+@mcp.tool()
+def de_read_clipboard(serial: str) -> dict:
+    """读取设备当前剪贴板内容（ClipInject/atx-agent 通道读回，M1 起支持）。"""
+    try:
+        serial = _check_serial(serial)
+        import uiautomator2 as u2
+        d = u2.connect(serial)
+        text = d.clipboard
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable",
+                                  f"剪贴板读取失败: {type(e).__name__}: {str(e)[:100]}"))
+    audit.audit("de_read_clipboard", serial, "", f"{len(text or '')} 字符")
+    return _ok({"clipboard": text or ""})
+
+
+@mcp.tool()
+def de_wake(serial: str) -> dict:
+    """点亮设备屏幕并解锁（熄屏时先调用它再截图）。"""
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        platform().wake(serial)
+    except PlatformError as e:
+        return _err(e)
+    audit.audit("de_wake", serial, "", "ok")
+    return _ok({"action": "wake", "serial": serial})
+
+
+@mcp.tool()
+def de_press_key(serial: str, key: str) -> dict:
+    """按设备按键：back/home/recent/menu/power/enter/delete 等。"""
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        if key not in _KEYS:
+            raise PlatformError("invalid_param", f"不支持的按键: {key}（可选 {_KEYS}）")
+        platform().press_key(serial, key)
+    except PlatformError as e:
+        return _err(e)
+    audit.audit("de_press_key", serial, key, "ok")
+    return _ok({"action": "press_key", "serial": serial, "key": key})
+
+
+# ================== L2 扩展工具（轻量通道：adb/u2 直连，省 token） ==================
+@mcp.tool()
+def de_open_app(serial: str, package: str) -> dict:
+    """打开 App（adb monkey 直启，最快路径）。package 为应用包名，如 com.ss.android.ugc.aweme。"""
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        if not package:
+            raise PlatformError("invalid_param", "缺少包名")
+        from mcp_server import direct_ops
+        direct_ops.open_app(serial, package)
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable", f"打开失败: {str(e)[:100]}"))
+    audit.audit("de_open_app", serial, package, "ok")
+    return _ok({"action": "open_app", "package": package})
+
+
+@mcp.tool()
+def de_stop_app(serial: str, package: str) -> dict:
+    """强制停止 App（am force-stop）。"""
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        if not package:
+            raise PlatformError("invalid_param", "缺少包名")
+        from mcp_server import direct_ops
+        direct_ops.stop_app(serial, package)
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable", f"停止失败: {str(e)[:100]}"))
+    audit.audit("de_stop_app", serial, package, "ok")
+    return _ok({"action": "stop_app", "package": package})
+
+
+@mcp.tool()
+def de_foreground_app(serial: str) -> dict:
+    """查询设备当前前台运行的 App 包名（轻量 dumpsys，不打扰设备）。"""
+    try:
+        serial = _check_serial(serial)
+        from mcp_server import direct_ops
+        pkg = direct_ops.foreground_app(serial)
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable", f"查询失败: {str(e)[:100]}"))
+    audit.audit("de_foreground_app", serial, "", pkg or "未知")
+    return _ok({"foreground_app": pkg or ""})
+
+
+@mcp.tool()
+def de_type_text(serial: str, text: str) -> dict:
+    """向设备当前输入框输入文字（支持中文，直接 set_text 不依赖剪贴板）。"""
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        if not text:
+            raise PlatformError("invalid_param", "内容为空")
+        from mcp_server import direct_ops
+        ok, msg = direct_ops.type_text(serial, text)
+        if not ok:
+            raise PlatformError("device_offline", msg)
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable", f"输入失败: {str(e)[:100]}"))
+    audit.audit("de_type_text", serial, f"{text[:30]}...", "ok")
+    return _ok({"action": "type_text"})
+
+
+@mcp.tool()
+def de_set_clipboard(serial: str, text: str) -> dict:
+    """写入设备剪贴板（ClipInject 通道，读回验证）。"""
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        if not text:
+            raise PlatformError("invalid_param", "内容为空")
+        from mcp_server import direct_ops
+        ok, msg = direct_ops.set_clipboard(serial, text)
+        if not ok:
+            raise PlatformError("device_offline", msg)
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable", f"注入失败: {str(e)[:100]}"))
+    audit.audit("de_set_clipboard", serial, f"{text[:30]}...", "ok")
+    return _ok({"action": "set_clipboard"})
+
+
+@mcp.tool()
+def de_sleep(serial: str) -> dict:
+    """熄灭设备屏幕（运行中任务会中断，慎用）。"""
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        platform().sleep(serial)
+    except PlatformError as e:
+        return _err(e)
+    audit.audit("de_sleep", serial, "", "ok")
+    return _ok({"action": "sleep"})
+
+
+@mcp.tool()
+def de_ocr(serial: str) -> dict:
+    """OCR 识别当前屏幕文字（图片/画布/WebView 里 UI 树没有的文字也能识别）。
+
+    返回 [{text, score}]——搜屏幕关键词后可配合 de_tap_element/de_tap 操作。
+    """
+    try:
+        serial = _check_serial(serial)
+        from mcp_server import direct_ops
+        results = direct_ops.ocr(serial)
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable", f"OCR 失败: {str(e)[:100]}"))
+    slim = [{"text": r["text"], "score": round(r["score"], 2)} for r in results]
+    audit.audit("de_ocr", serial, "", f"{len(slim)} 条")
+    return _ok({"count": len(slim), "texts": slim[:100]})
+
+
+@mcp.tool()
+def de_tap_text(serial: str, text: str) -> dict:
+    """点击屏幕上显示该文字的位置（语义点击：一次调用完成「找到并点击」，无需坐标）。
+
+    想点带文字的按钮/列表项/标签/链接时用它：text 只需是屏幕上可见文字的
+    一部分（子串匹配，如「搜索」「立即购买」）。原生控件直接命中；
+    WebView/图片/画布里渲染的文字自动走 OCR 兜底。多命中点第一处（想点
+    更靠下的请把文字换独特些）。屏幕确实没有该文字时返回错误提示，
+    请截图确认后换关键词。比 de_tap 坐标点击可靠，涉及文字目标时优先使用。
+    """
+    try:
+        _check_write()
+        serial = _check_serial(serial)
+        _ensure_device_free(serial)
+        if not text or len(text) > 100:
+            raise PlatformError("invalid_param", "text 不能为空且 ≤100 字符")
+        res = platform().tap_text(serial, text)
+    except PlatformError as e:
+        return _err(e)
+    if not res.get("found"):
+        err = PlatformError("text_not_found",
+                            f"屏幕上未找到文字「{text}」——先 de_screenshot 看当前界面，"
+                            f"换用屏幕上实际存在的文字；若文字在需滑动后才可见请先滑动")
+        audit.audit("de_tap_text", serial, f"「{text[:30]}」", "未找到")
+        return _err(err)
+    audit.audit("de_tap_text", serial,
+                f"「{text[:30]}」via {res.get('method')} @({res.get('x')},{res.get('y')})", "ok")
+    return _ok({"action": "tap_text", "serial": serial, "text": text,
+                "method": res.get("method"), "matched": res.get("matched") or text,
+                "x": res.get("x"), "y": res.get("y")})
+
+
+@mcp.tool()
+def de_list_apps(serial: str, keyword: str = "") -> dict:
+    """列出设备第三方已装应用包名（可关键词过滤，如 keyword='douyin' 找抖音）。"""
+    try:
+        serial = _check_serial(serial)
+        from mcp_server import direct_ops
+        pkgs = direct_ops.list_apps(serial, keyword)
+    except PlatformError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(PlatformError("platform_unavailable", f"查询失败: {str(e)[:100]}"))
+    audit.audit("de_list_apps", serial, keyword or "", f"{len(pkgs)} 个")
+    return _ok({"count": len(pkgs), "packages": pkgs[:200]})
+
+
+@mcp.tool()
+def de_list_tasks() -> dict:
+    """列出平台任务计划（名称/启用状态/调度），供了解可自动化的任务。"""
+    try:
+        tasks = platform().list_tasks()
+    except PlatformError as e:
+        return _err(e)
+    audit.audit("de_list_tasks", "", "", f"{len(tasks)} 个")
+    return _ok({"tasks": tasks})
+
+
+def main():
+    _log.info("MCP mobile-control 启动: allow_write=%s port=%s",
+              S.allow_write, S.http_port)
+    mcp.run(transport="http", host=S.http_host, port=S.http_port)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,204 @@
+"""平台（auto_control）HTTP 客户端：登录会话 + CSRF + API 封装。
+
+会话失效自动重登；CSRF token 每次登录后获取，POST 必带。
+只读接口（GET）与写接口（POST）分离封装，写操作由 MCP 门控层决定是否调用。
+"""
+import httpx
+import logging
+
+_log = logging.getLogger("mcp.platform")
+
+_CSRF_HEADER = "X-CSRF-Token"
+
+
+class PlatformError(Exception):
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+class PlatformClient:
+    def __init__(self, url, user, password, timeout=30.0):
+        self.url = url.rstrip("/")
+        self.user = user
+        self.password = password
+        self._client = httpx.Client(base_url=self.url, timeout=timeout,
+                                    follow_redirects=True)
+        self._csrf = ""
+        self._login()
+
+    # ---------- 会话 ----------
+    def _login(self):
+        """登录平台，拿会话 cookie + CSRF token。"""
+        r = self._client.post("/login", data={
+            "username": self.user, "password": self.password})
+        if r.status_code != 302 and r.status_code != 200:
+            raise PlatformError("platform_unavailable",
+                                f"平台登录失败 HTTP {r.status_code}: {r.text[:120]}")
+        csrf = self._client.get("/api/csrf")
+        if csrf.status_code == 200:
+            self._csrf = (csrf.json() or {}).get("token", "")
+        _log.info("平台登录成功: %s", self.user)
+
+    def _ensure_session(self):
+        """会话过期（401/403/302 到登录页）时重登。"""
+        r = self._client.get("/api/status")
+        if r.status_code in (401, 403) or r.url.path.endswith("/login"):
+            _log.warning("会话失效，重新登录")
+            self._login()
+            return True
+        return False
+
+    # ---------- 基础请求 ----------
+    def _get(self, path, **params):
+        self._ensure_session()
+        return self._client.get(path, params=params)
+
+    def _post(self, path, json=None):
+        self._ensure_session()
+        headers = {_CSRF_HEADER: self._csrf} if self._csrf else {}
+        return self._client.post(path, json=json or {}, headers=headers)
+
+    # ---------- 平台 API 封装（M0） ----------
+    def list_devices(self):
+        """设备列表与状态（GET /api/status）。"""
+        r = self._get("/api/status")
+        if r.status_code != 200:
+            raise PlatformError("platform_unavailable",
+                                f"/api/status HTTP {r.status_code}")
+        j = r.json() or {}
+        return j.get("devices", [])
+
+    def screenshot(self, serial):
+        """截图（GET /api/screen/thumb），返回 (jpeg_bytes, screen_state)。"""
+        r = self._get("/api/screen/thumb", serial=serial)
+        if r.status_code == 503:
+            raise PlatformError("device_offline", r.text[:120])
+        if r.status_code != 200:
+            raise PlatformError("platform_unavailable",
+                                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)
+        if r.status_code == 503:
+            raise PlatformError("device_offline", r.text[:120])
+        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", "取分辨率失败"))[:120])
+        return int(j["width"]), int(j["height"])
+
+    def tap(self, serial, x, y, snap=False):
+        """点击（POST /api/screen/tap）。
+
+        snap=True：点落在可点击元素内则吸附到元素中心（AI 粗略坐标也能点准）。
+        返回平台 JSON（含 snapped/x/y/label）。
+        """
+        r = self._post("/api/screen/tap", json={"serial": serial,
+                                                "x": int(x), "y": int(y),
+                                                "snap": 1 if snap else 0})
+        return self._check_op(r, "tap")
+
+    def tap_text(self, serial, text):
+        """按屏幕文字点击（平台解析：UI 树子串匹配 → OCR 兜底）。
+
+        返回 {ok, found, method, matched, x, y}——found=false 是业务结果
+        （屏幕无该文字），非设备错误；设备离线/不可达仍抛 PlatformError。
+        """
+        r = self._post("/api/screen/tap_text",
+                       json={"serial": serial, "text": str(text)})
+        if r.status_code == 503:
+            raise PlatformError("device_offline", r.text[:120])
+        if r.status_code != 200:
+            raise PlatformError("platform_unavailable",
+                                f"tap_text HTTP {r.status_code}: {r.text[:120]}")
+        return r.json() or {}
+
+    def swipe(self, serial, x1, y1, x2, y2, duration=0.2):
+        """滑动（POST /api/screen/swipe）。"""
+        r = self._post("/api/screen/swipe", json={
+            "serial": serial, "x1": int(x1), "y1": int(y1),
+            "x2": int(x2), "y2": int(y2),
+            "duration": float(duration)})
+        return self._check_op(r, "swipe")
+
+    def ui_elements(self, serial):
+        """UI 元素树（GET /api/uiauto/elements，uiautodev 服务）。"""
+        r = self._get("/api/uiauto/elements", serial=serial)
+        if r.status_code == 503:
+            raise PlatformError("device_offline", r.text[:120])
+        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", "取元素失败"))[:120])
+        return j.get("elements", [])
+
+    def wake(self, serial):
+        """亮屏并解锁（POST /api/device/screen_all mode=on）。"""
+        r = self._post("/api/device/screen_all",
+                       json={"mode": "on", "serials": [serial]})
+        return self._check_op(r, "wake")
+
+    def sleep(self, serial):
+        """熄屏（POST /api/device/screen_all mode=off）。"""
+        r = self._post("/api/device/screen_all",
+                       json={"mode": "off", "serials": [serial]})
+        return self._check_op(r, "sleep")
+
+    def list_tasks(self):
+        """任务计划列表（GET /api/jobs）。"""
+        r = self._get("/api/jobs")
+        if r.status_code != 200:
+            raise PlatformError("platform_unavailable",
+                                f"/api/jobs HTTP {r.status_code}")
+        j = r.json() or {}
+        tasks = []
+        for t in j.get("jobs") or []:
+            tasks.append({"id": t.get("id"), "name": t.get("name"),
+                          "task_type": t.get("task_type"),
+                          "enabled": t.get("enabled"),
+                          "schedule": (t.get("schedule") or {}).get("mode", "")})
+        return tasks
+
+    def press_key(self, serial, key):
+        """按键（POST /api/screen/key）。"""
+        r = self._post("/api/screen/key",
+                       json={"serial": serial, "key": key})
+        return self._check_op(r, "key")
+
+    @staticmethod
+    def _check_op(r, name):
+        if r.status_code == 503:
+            raise PlatformError("device_offline", r.text[:120])
+        if r.status_code != 200:
+            raise PlatformError("platform_unavailable",
+                                f"{name} HTTP {r.status_code}: {r.text[:120]}")
+        j = r.json() or {}
+        if not j.get("ok"):
+            raise PlatformError("device_offline", str(j.get("error", "操作失败"))[:120])
+        return j
@@ -0,0 +1,3 @@
+fastmcp>=2.0
+httpx>=0.27
+Pillow>=10.0
@@ -12,17 +12,38 @@ 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

-# HTTP 客户端（STF API 调用）
+# HTTP 客户端
 requests>=2.28

+# SSH 远程执行（预留运维用；.env 配 STF_SSH_PASSWORD 时走密码认证，
+# 跨平台无需 sshpass；未配置则退回系统 ssh 免密密钥）
+paramiko>=3.0
+
 # Android UI 自动化（uiautomator2）
 uiautomator2>=3.0

 # UI 元素抓取（步骤编辑器"抓取元素"功能，本地服务端口 20242）
 uiautodev>=0.14

+# 屏幕 OCR（条件判断的 OCR识别 选择器，ONNX 推理，跨平台：Windows/Linux/macOS，
+# 中英文模型随包内置；服务器/容器环境必须用 headless 版 opencv——
+# opencv-python 依赖 X11 库（libxcb），slim 容器里 import cv2 直接崩，OCR 步骤任务失败退出）
+rapidocr_onnxruntime>=1.4
+opencv-python-headless>=4.8,<5  # 锁定 4.x：5.x wheel 打包异常（无 cv2 模块）
+
 # APK 元信息解析（应用管理功能：自动读取包名/版本/应用名）
 pyaxmlparser>=0.3.27
+
+# MCP Server + AI 控制台 Agent（fastmcp：Streamable HTTP 服务端/客户端）
+fastmcp>=2.0
@@ -1,48 +0,0 @@
-"""清理 STF 上残留的设备占用（强杀进程导致没正常释放时用）。
-
-运行：python scripts/cleanup.py
-"""
-import os
-import sys
-
-# 让脚本既能直接运行（python scripts/cleanup.py）又能作为模块运行。
-# scripts/ 的上一级是项目根目录（core 包的父目录），需加入 sys.path。
-_PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-if _PROJECT_ROOT not in sys.path:
-    sys.path.insert(0, _PROJECT_ROOT)
-
-import requests
-from config import STF_URL, STF_TOKEN
-
-headers = {"Authorization": f"Bearer {STF_TOKEN}"}
-
-# /user/devices 返回当前用户正在占用的设备
-resp = requests.get(f"{STF_URL}/api/v1/user/devices", headers=headers)
-resp.raise_for_status()
-data = resp.json()
-mine = data.get("devices", [])
-print(f"当前账户占用的设备数: {len(mine)}")
-for d in mine:
-    print(f"  - {d.get('serial')}  using={d.get('using')}")
-
-# 全部释放
-for d in mine:
-    serial = d["serial"]
-    try:
-        requests.post(
-            f"{STF_URL}/api/v1/user/devices/{serial}/remoteDisconnect",
-            headers=headers,
-        )
-    except Exception:
-        pass
-    r = requests.delete(f"{STF_URL}/api/v1/user/devices/{serial}", headers=headers)
-    print(f"释放 {serial}: HTTP {r.status_code}")
-
-# 再看一次总设备池
-resp = requests.get(f"{STF_URL}/api/v1/devices", headers=headers)
-resp.raise_for_status()
-free = [d for d in resp.json().get("devices", [])
-        if d.get("present") and d.get("ready") and not d.get("using") and d.get("owner") is None]
-print(f"\n清理后空闲设备数: {len(free)}")
-for d in free:
-    print(f"  - {d.get('serial')}")
@@ -1,57 +0,0 @@
-@echo off
-title Fix Web Access
-
-:: Auto elevate to admin
-net session >nul 2>&1
-if %errorLevel% neq 0 (
-    echo Requesting admin privileges...
-    powershell -Command "Start-Process cmd -ArgumentList '/c ""%~f0""' -Verb RunAs"
-    exit /b
-)
-
-echo ============================================
-echo   Fix Web Backend Access
-echo ============================================
-echo.
-
-:: 1. Disable residual system proxy (blocks localhost)
-echo [1/4] Disabling system proxy...
-reg add "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v ProxyEnable /t REG_DWORD /d 0 /f >nul 2>&1
-reg delete "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v ProxyServer /f >nul 2>&1
-echo Done.
-echo.
-
-:: 2. Add firewall rules for Python
-echo [2/4] Adding firewall rules for Python...
-for /f "delims=" %%i in ('where python') do set PYTHON_PATH=%%i
-if not defined PYTHON_PATH (
-    echo ERROR: Python not found in PATH
-    pause
-    exit /b 1
-)
-echo Python path: %PYTHON_PATH%
-netsh advfirewall firewall delete rule name="PythonWeb" >nul 2>&1
-netsh advfirewall firewall add rule name="PythonWeb" dir=in action=allow program="%PYTHON_PATH%" enable=yes profile=any >nul
-netsh advfirewall firewall delete rule name="PythonWebOut" >nul 2>&1
-netsh advfirewall firewall add rule name="PythonWebOut" dir=out action=allow program="%PYTHON_PATH%" enable=yes profile=any >nul
-echo Done.
-echo.
-
-:: 3. Flush DNS cache
-echo [3/4] Flushing DNS cache...
-ipconfig /flushdns >nul 2>&1
-echo Done.
-echo.
-
-:: 4. Show excluded port ranges for reference
-echo [4/4] TCP excluded port ranges (for reference):
-netsh interface ipv4 show excludedportrange protocol=tcp
-echo.
-
-echo ============================================
-echo  Fix complete! Now:
-echo  1. Close ALL browser windows and reopen
-echo  2. Run: python web_server.py
-echo  3. Open: http://127.0.0.1:18050/
-echo ============================================
-pause
@@ -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()
@@ -1,21 +1,21 @@
 """打包脚本：把项目代码打成 zip 压缩包，排除运行时产物。

 用法：python scripts/pack.py
-输出：项目根目录下 platform-tools.zip
+输出：项目根目录下 auto_control.zip
 """
 import os
 import sys
 import zipfile

 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-OUT = os.path.join(os.path.dirname(ROOT), "platform-tools.zip")
+OUT = os.path.join(os.path.dirname(ROOT), "auto_control.zip")

 SKIP_DIRS = {"__pycache__", ".git", ".idea", "venv", ".venv", "node_modules"}
 SKIP_EXTS = {".pyc", ".pyo"}
 # 路径片段包含这些的跳过
 SKIP_PARTS = {"__pycache__"}
 # 文件名完全匹配这些的跳过
-SKIP_FILES = {"fix_web.bat"}
+SKIP_FILES = {}
 # 文件名后缀匹配这些的跳过
 SKIP_SUFFIX = (".migrated",)
 # 特定目录下特定后缀跳过
@@ -0,0 +1,233 @@
+"""全量路由回归测试：启动后遍历所有 API 路由发请求，抓 500/异常。
+
+用法（项目根目录）：
+    .venv/bin/python scripts/regression_test.py
+
+设计：
+  - 用 Flask test_client（不占用 18050，不影响运行中的服务）
+  - GET 路由全量请求（路径参数自动替换）；流式/二进制接口跳过
+  - 写操作（POST/PUT/DELETE）发空 body 探测：期望 400/403/404（参数校验），
+    返回 500 = 代码缺陷（import 遗漏/引用错误），立即报出
+  - 关键业务 POST 用真实参数验证（亮屏/剪贴板/测试步骤/设备池增删）
+  - 退出码：有失败返回 1（可接入检查流程）
+
+背景：web/ 蓝图拆分后多次出现 import 遗漏导致接口 500（ADB_PATH/_log/常量等），
+每次都是线上报错才暴露。此脚本让这类问题在改动后 30 秒内现形。
+"""
+import os
+import sys
+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 相关接口可能慢（连接/查询设备），给足时间。
+# 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": [_SERIAL_PH], "text": "回归测试"}),
+    ("测试步骤(wait)", "/api/steps/test",
+     {"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"}),
+    ("应用版本查询", "/api/tools/appver", {"pkg": "jp.co.cyberagent.stf"}),
+]
+# 红线接口：期望被拒绝（不是 ok）
+_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>", _TEST_SERIAL)
+    url = url.replace("<apk_id>", "x")
+    url = url.replace("<action_id>", "x")
+    url = url.replace("<device_id>", "x")
+    url = url.replace("<uid>", "1")
+    return url
+
+
+def main():
+    c = app.test_client()
+    # 登录 + CSRF
+    r = c.post("/login", data={"username": "admin", "password": "admin123"})
+    if r.status_code != 302:
+        print("❌ 登录失败（请检查 admin 账号）")
+        sys.exit(1)
+    token = c.get("/api/csrf").get_json()["token"]
+    H = {"X-CSRF-Token": token}
+
+    fails = []
+    warns = []
+    passed = 0
+
+    # ========== 1. GET 全量 ==========
+    rules = sorted({r.rule for r in app.url_map.iter_rules()
+                    if r.rule.startswith("/api") and "GET" in r.methods})
+    for rule in rules:
+        if rule.startswith(_SKIP_PREFIXES):
+            continue
+        url = _fill_path_params(rule)
+        try:
+            r = c.get(url)
+            if r.status_code == 500:
+                fails.append(f"GET {rule} -> HTTP 500（代码缺陷）")
+            elif r.status_code >= 502:
+                warns.append(f"GET {rule} -> HTTP {r.status_code}（业务错误，如未配置/设备离线）")
+            else:
+                passed += 1
+        except Exception as e:
+            fails.append(f"GET {rule} -> {type(e).__name__}: {e}")
+    print(f"GET 路由: {len(rules)} 个（跳过 {len([r for r in rules if r.startswith(_SKIP_PREFIXES)])} 个流式/二进制）")
+
+    # ========== 1.5 未登录访问（登录重定向链路） ==========
+    try:
+        r = c.get("/")
+        if r.status_code == 302 and "login" in (r.headers.get("Location") or ""):
+            passed += 1
+        elif r.status_code == 200:
+            passed += 1  # 已登录态也可能 200（测试客户端无 cookie 时走 302）
+        else:
+            fails.append(f"未登录访问 / -> HTTP {r.status_code}（应 302 到登录页）")
+    except Exception as e:
+        fails.append(f"未登录访问 / -> {type(e).__name__}: {e}")
+
+    # ========== 2. 写操作空 body 探测（抓 import 遗漏/引用错误） ==========
+    write_rules = sorted({r.rule for r in app.url_map.iter_rules()
+                          if r.rule.startswith("/api")
+                          and (r.methods & {"POST", "PUT", "DELETE"})})
+    for rule in write_rules:
+        url = _fill_path_params(rule)
+        try:
+            methods = {m for r2 in app.url_map.iter_rules() if r2.rule == rule for m in r2.methods}
+            if "DELETE" in methods:
+                r = c.delete(url, headers=H)
+            elif "PUT" in methods:
+                r = c.put(url, json={}, headers=H)
+            else:
+                r = c.post(url, json={}, headers=H)
+            # 空 body 期望 400（参数校验）；403=权限/404=路径参数、500=代码缺陷
+            if r.status_code == 500:
+                fails.append(f"写操作 {rule} -> HTTP 500（空 body 应 400，500=代码缺陷）")
+            elif r.status_code >= 502:
+                warns.append(f"写操作 {rule} -> HTTP {r.status_code}（业务错误，如未配置/设备离线）")
+            else:
+                passed += 1
+        except Exception as e:
+            fails.append(f"写操作 {rule} -> {type(e).__name__}: {e}")
+    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
+            is_reject = url in _EXPECT_REJECT and "kill" in (body.get("cmd") or "")
+            good = (not j.get("ok")) if is_reject else bool(j and j.get("ok") is not False)
+            if good:
+                passed += 1
+                print(f"  ✅ {name}: {r.status_code}")
+            else:
+                fails.append(f"关键 POST {name} -> HTTP {r.status_code} {str(j)[:80]}")
+        except Exception as e:
+            fails.append(f"关键 POST {name} -> {type(e).__name__}: {e}")
+
+    # ========== 汇总 ==========
+    print("-" * 50)
+    if warns:
+        print(f"⚠ 业务性提示 {len(warns)} 个（非代码缺陷）：")
+        for w in warns:
+            print("   ", w)
+    if fails:
+        print(f"❌ 发现 {len(fails)} 个代码缺陷：")
+        for f in fails:
+            print("   ", f)
+        sys.exit(1)
+    print(f"✅ 全部通过（{passed} 项检查，含 {len(rules)} GET + {len(write_rules)} 写操作探测 + {len(_KEY_POSTS)} 关键业务）")
+
+
+if __name__ == "__main__":
+    main()
@@ -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'@'%';
@@ -0,0 +1,84 @@
+#!/bin/bash
+# 容器启动脚本：依赖安装（仅首次/缺失时）+ 环境修复 + 启动 web_server。
+# compose 的 python-app 服务 command 指向本脚本（不要在 compose 里再跑 pip，
+# 否则每次容器重启都重装依赖——实测每轮重新下载 opencv 5.0(73MB) 并破坏 cv2）。
+#
+# 为什么需要环境修复（必须在 pip install 之后）：
+#   rapidocr_onnxruntime 的依赖声明是 opencv-python（GUI 版），pip 解析依赖时
+#   会强制装回它；而 GUI 版依赖 X11 库（libxcb），python:slim 容器里 import cv2
+#   直接崩溃 → RapidOCR 不可用 → 条件判断的 OCR 步骤抛异常 → 任务失败退出。
+#   因此在安装完 requirements 后，最后强制卸载 GUI 版并装 headless（幂等）。
+#   本地 Mac 有 GUI 环境不受影响。
+
+# ---- 依赖就绪守卫：flask/u2/uiautodev/rapidocr/cv2 全部可用则跳过安装 ----
+# （容器重启秒级启动；只有首次部署或依赖缺失时才走完整安装）
+python3 - <<'PY'
+import importlib.util, sys
+mods = ("flask", "flask_login", "flask_sqlalchemy", "apscheduler",
+        "uiautomator2", "uiautodev", "rapidocr_onnxruntime", "PIL",
+        "fastmcp", "pymysql", "qrcode")
+if all(importlib.util.find_spec(m) for m in mods):
+    try:
+        import cv2
+        ok = hasattr(cv2, "__version__") and cv2.__file__ is not None
+    except Exception:
+        ok = False
+    sys.exit(0 if ok else 1)
+sys.exit(1)
+PY
+if [ $? -ne 0 ]; then
+    echo "[start] 依赖缺失或 cv2 异常，执行安装与环境修复（首次启动较慢）..."
+    if [ -f requirements.txt ]; then
+        pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
+    fi
+
+    # 环境修复：最后强制 headless（覆盖 rapidocr 拉回的 GUI 版）
+    pip uninstall -y -q opencv-python 2>/dev/null || true
+    pip install -q -i https://pypi.tuna.tsinghua.edu.cn/simple "opencv-python-headless>=4.8,<5"  # 5.x wheel 无 cv2 模块，锁定 4.x
+
+    # pip 24.0 解压 abi3 wheel 偶发丢根文件（site-packages/cv2 只剩子目录，
+    # cv2.abi3.so / __init__.py 缺失 → import cv2 成空壳，OCR 全挂）。
+    # 手动解压兜底在部分环境修不好（解压后仍无 cv2.__version__），
+    # 实测 pip --force-reinstall 完整安装有效（220 验证 cv2 4.14.0 恢复）。
+    python3 - <<'PY'
+import subprocess, sys
+
+def cv2_ok():
+    try:
+        import cv2
+        return hasattr(cv2, "__version__") and cv2.__file__ is not None
+    except Exception:
+        return False
+
+if cv2_ok():
+    sys.exit(0)
+print("cv2 异常，pip 强制重装 opencv-python-headless...")
+r = subprocess.run(["pip", "install", "--force-reinstall", "-q",
+                    "-i", "https://pypi.tuna.tsinghua.edu.cn/simple",
+                    "opencv-python-headless>=4.8,<5"])
+if r.returncode == 0:
+    import cv2
+    print(f"cv2 {cv2.__version__} 重装修复完成")
+sys.exit(r.returncode)
+PY
+else
+    echo "[start] 依赖已就绪（cv2 $(python3 -c 'import cv2; print(cv2.__version__)' 2>/dev/null)），跳过安装"
+fi
+
+# 启动 MCP server（后台，AI 控制台/外部客户端经 127.0.0.1:8033 调用）。
+# web_server.py 内 agent 依赖它，容器重启必须自动拉起（MCP_ENABLED=0 可关）。
+# 平台账号：MCP_PLATFORM_USER 默认 admin；密码优先取环境变量（compose/.env），
+# 兜底 admin123 与部署时的手动启动参数一致。
+if [ -f mcp_server/mcp_server.py ] && [ "${MCP_ENABLED:-1}" = "1" ]; then
+    echo "[start] 启动 MCP server..."
+    MCP_ALLOW_WRITE=1 \
+    MCP_PLATFORM_USER="${MCP_PLATFORM_USER:-admin}" \
+    MCP_PLATFORM_PASS="${MCP_PLATFORM_PASS:-admin123}" \
+    MCP_AUDIT_FILE="${MCP_AUDIT_FILE:-/tmp/mcp_audit.log}" \
+    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
@@ -0,0 +1,54 @@
+#!/bin/bash
+# web_server.py 进程守护脚本：崩溃自动重启，带退避和重启上限。
+#
+# 用法：
+#   bash scripts/supervise.sh                 # 用 python3 启动
+#   PYTHON=./.venv/bin/python bash scripts/supervise.sh   # 指定 Python（venv）
+#
+# 行为：
+#   - web_server 崩溃（非 0/130 退出码）→ 等待 BACKOFF_MIN 秒自动重启
+#   - 重启窗口（RESTART_WINDOW 秒）内超过 MAX_RESTARTS 次 → 停止（防崩溃死循环）
+#   - 正常退出（Ctrl+C=130 或 code=0）→ 守护结束
+#   - 日志写到 logs/supervise.log
+#
+# 生产无人值守建议配合 Docker 的 restart: unless-stopped 或 systemd 一起用。
+
+cd "$(dirname "$0")/.."
+PYTHON="${PYTHON:-python3}"
+mkdir -p logs
+
+MAX_RESTARTS="${MAX_RESTARTS:-10}"        # 窗口内最大重启次数
+RESTART_WINDOW="${RESTART_WINDOW:-300}"    # 重启窗口（秒）
+BACKOFF_MIN="${BACKOFF_MIN:-2}"            # 重启前等待（秒）
+
+restarts=0
+window_start=$(date +%s)
+
+echo "[$(date '+%F %T')] 进程守护启动，python=$PYTHON"
+while true; do
+  echo "[$(date '+%F %T')] 启动 web_server.py..."
+  "$PYTHON" web_server.py >> logs/supervise.log 2>&1
+  code=$?
+  echo "[$(date '+%F %T')] web_server 退出，code=$code"
+
+  # 0 = 正常结束；130 = Ctrl+C（SIGINT）→ 手动停止，守护结束
+  if [ "$code" -eq 0 ] || [ "$code" -eq 130 ]; then
+    echo "[$(date '+%F %T')] 正常退出，守护进程结束"
+    break
+  fi
+
+  # 滑动窗口计数
+  now=$(date +%s)
+  if [ $((now - window_start)) -gt "$RESTART_WINDOW" ]; then
+    window_start=$now
+    restarts=0
+  fi
+  restarts=$((restarts + 1))
+  if [ "$restarts" -gt "$MAX_RESTARTS" ]; then
+    echo "[$(date '+%F %T')] ${RESTART_WINDOW}s 内崩溃超过 ${MAX_RESTARTS} 次，停止守护（可能配置/环境问题）"
+    break
+  fi
+
+  echo "[$(date '+%F %T')] ${BACKOFF_MIN}s 后重启 (窗口内第 ${restarts} 次)"
+  sleep "$BACKOFF_MIN"
+done
@@ -0,0 +1,49 @@
+"""发布计划「按名字发」相关用例：一次跑完，汇总结果。
+
+用法（项目根目录）：
+    .venv/Scripts/python scripts/tests/run_all.py        # Windows
+    .venv/bin/python scripts/tests/run_all.py            # Linux/macOS
+
+这些用例的**铁律**（与 doc/DEVELOPMENT.md 的测试约定一致）：
+  · 一律**临时 SQLite + 临时目录**（`DATABASE_URL` / `DATA_VIDEO_DIR` 指向 tempfile 建的目录），
+    **绝不碰用户的真实库与真实素材目录**；
+  · 需要设备的地方一律用**假设备**（桩对象/stub），**不连真机、不下发 adb**；
+  · 每个用例自己退出码非 0 表示失败，本脚本据此汇总。
+
+覆盖：
+  test_parse_name        文件名/标题行解析（`名字_日期_编号`、`标题 || 正文_...`、各种拒收）
+  test_upload_name       上传 + 配标题落库（不再依赖任何账号台账）
+  test_name_scope        读本机账号名字、按名字取计划、推送前核对
+  test_switch_account    切换账号（按名字点控件、回读校验、登录页停设备）
+  test_foreach_account   循环本机待发的号（一轮跑完、试过不回头、干净退出）
+  test_push_by_name      按名字找设备推送（matched/unmatched、缓存）
+  test_expect_el         「校验页面」：特征在就过；不在就按 on_missing 处置（默认跳过本轮剩余步骤）
+  test_read_text         「读取文字」+ 选择器里的 {变量} +「条件判断→变量」
+"""
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+CASES = ["test_parse_name.py", "test_upload_name.py", "test_name_scope.py",
+         "test_switch_account.py", "test_foreach_account.py", "test_push_by_name.py",
+         "test_expect_el.py", "test_read_text.py"]
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+failed = []
+for name in CASES:
+    print("=" * 66)
+    print("▶", name)
+    print("=" * 66)
+    r = subprocess.run([sys.executable, os.path.join(HERE, name)])
+    if r.returncode != 0:
+        failed.append(name)
+
+print()
+print("=" * 66)
+if failed:
+    print("❌ 失败 %d / %d：%s" % (len(failed), len(CASES), "、".join(failed)))
+    sys.exit(1)
+print("✅ 全部 %d 个用例通过" % len(CASES))
@@ -0,0 +1,145 @@
+# -*- coding: utf-8 -*-
+"""「校验页面」(expect_el) 用例：看到就过；没看到按 on_missing 处置（默认跳过本轮剩余步骤）。
+
+假设备，不连真机。重点验两件事：
+  ① 特征元素在 → True，且**不影响**后面的步骤；
+  ② 特征元素不在 → 默认 `skip_rest`：**本轮剩下的步骤一步都不执行**（不盲点后面的按钮）。
+"""
+import io
+import os
+import sqlite3
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+os.environ['DATABASE_URL'] = 'sqlite:///' + os.path.join(tempfile.mkdtemp(), 'ac.db').replace('\\', '/')
+os.environ['DATA_VIDEO_DIR'] = tempfile.mkdtemp()
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+os.chdir(sys.path[0])
+
+from tasks.generic import task as gt                                   # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+class El:
+    def __init__(self, flag):
+        self._flag = flag
+
+    @property
+    def exists(self):
+        return _Ex(self._flag)
+
+    def wait(self, timeout=0):
+        return self._flag
+
+    def get_text(self, timeout=None):
+        return ""
+
+
+class _Ex:
+    def __init__(self, f):
+        self.f = f
+
+    def __call__(self, timeout=0):
+        return self.f
+
+    def __bool__(self):
+        return self.f
+
+
+class StubD:
+    """`present` 里有的 xpath 才算存在（用来模拟"这一页的特征元素"）。"""
+
+    def __init__(self, present=()):
+        self.present = set(present)
+        self.calls = []
+
+    def xpath(self, v):
+        self.calls.append(v)
+        return El(v in self.present)
+
+    def __call__(self, **kw):
+        v = kw.get('selector_value') or ''
+        self.calls.append('kw:%s' % kw)
+        return El(v in self.present)
+
+
+notes = []
+orig = gt.notifier.notify
+gt.notifier.notify = lambda ev, **kw: notes.append((ev, kw.get('want') or ''))
+try:
+    print('=== 1. 特征在 → True，后面的步骤照跑 ===')
+    P = {'selector_type': 'xpath', 'selector_value': '//*[@text="所有照片"]',
+         'timeout': 1, 'on_missing': 'skip_rest', 'what': '相册页'}
+    w = gt.GenericStepsWorker("F1", {})
+    d = StubD(present=['//*[@text="所有照片"]'])
+    check('返回 True', w._exec_expect_el(d, P), True)
+    check('没置"跳过剩余"', w._skip_rest, False)
+    check('没发通知', notes, [])
+
+    print('=== 2. 特征不在 → 默认 skip_rest：**本轮剩余步骤一步都不执行** ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F2", {})
+    d = StubD(present=[])               # 特征不在（没到相册页）
+    ran = []
+    real_one = gt.GenericStepsWorker._exec_one
+
+    def fake_one(dd, step, depth=0):
+        """真跑 expect_el 那一步；其它步骤只记一笔（被跳过就不该记）。"""
+        if step.get('type') == 'expect_el':
+            return real_one(w, dd, step, depth)
+        ran.append(step.get('label'))
+
+    w._exec_one = fake_one
+    steps = [{"type": "expect_el", "label": "校验：应在相册页", "params": P},
+             {"type": "click", "label": "点第一个素材", "params": {}},
+             {"type": "click", "label": "点下一步", "params": {}}]
+    w._exec_steps(d, steps)
+    check('后面的点击一步都没执行', ran, [])
+    check('置了"跳过剩余"', w._skip_rest, True)
+    check('发了页面不对的通知', [n[0] for n in notes], ['task.page.mismatch'])
+    check('通知里带上"在等什么"', notes[0][1], '相册页')
+
+    print('=== 3. on_missing=stop → 停本设备 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F3", {})
+    d = StubD(present=[])
+    check('返回 False', w._exec_expect_el(d, dict(P, on_missing='stop')), False)
+    check('本设备已停', w.stopped(), True)
+    check('发了通知', [n[0] for n in notes], ['task.page.mismatch'])
+    check('没置"跳过剩余"（停设备就够了）', w._skip_rest, False)
+
+    print('=== 4. on_missing=notify → 只通知、继续 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F4", {})
+    d = StubD(present=[])
+    check('返回 False', w._exec_expect_el(d, dict(P, on_missing='notify')), False)
+    check('设备没停', w.stopped(), False)
+    check('没置"跳过剩余"', w._skip_rest, False)
+    check('发了通知', [n[0] for n in notes], ['task.page.mismatch'])
+
+    print('=== 5. 选择器为空 → 明确报错，不乱判 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F5", {})
+    d = StubD(present=[])
+    check('返回 None', w._exec_expect_el(d, dict(P, selector_value='')), None)
+    check('没置"跳过剩余"', w._skip_rest, False)
+    check('没发通知', notes, [])
+finally:
+    gt.notifier.notify = orig
+
+print()
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（没连任何真机）')
@@ -0,0 +1,177 @@
+# -*- coding: utf-8 -*-
+"""P5 测试：`foreach_account`（一轮把本机待发的号跑完）—— 临时库，不碰真实数据。"""
+import io
+import os
+import shutil
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+
+TMP = tempfile.mkdtemp(prefix='ac_p5_')
+os.environ['DATABASE_URL'] = 'sqlite:///' + TMP.replace(chr(92), '/') + '/ac.db'
+os.environ['DATA_VIDEO_DIR'] = os.path.join(TMP, 'videos')
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from flask import Flask                                              # noqa: E402
+from core import db_config, models                                   # noqa: E402
+from core import video_plan as vp                                    # noqa: E402
+from tasks.generic import task as gt                                 # noqa: E402
+
+DATE = '2026-09-12'
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+app = Flask("t")
+uri = db_config.build_db_uri()
+app.config["SQLALCHEMY_DATABASE_URI"] = uri
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+models.db.init_app(app)
+with app.app_context():
+    models.db.create_all()
+vp.init_app(app)
+
+
+def seed():
+    """小王 2 条、小李 1 条、小张 1 条（未来）。"""
+    with app.app_context():
+        for i, (nm, d, s) in enumerate([('小王', DATE, 1), ('小王', DATE, 2),
+                                        ('小李', DATE, 1), ('小张', '2027-01-01', 1)]):
+            models.db.session.add(models.VideoPlan(
+                id='p%d' % i, nickname=nm, phone='', device_name='', douyin_id='',
+                serial='', release_date=d, seq=s, seq_auto=False, title='t' + str(s),
+                body='', video_file='x', video_name='x', status=vp.ST_READY,
+                created_at=vp._now(), updated_at=vp._now()))
+        models.db.session.commit()
+
+
+def status_of():
+    with app.app_context():
+        out = {}
+        for r in models.VideoPlan.query.all():
+            out.setdefault(r.nickname, []).append(r.status)
+        return {k: sorted(v) for k, v in out.items()}
+
+
+print('=== 1. 一轮把本机待发的号跑完（模拟"推+发成功"）===')
+seed()
+w = gt.GenericStepsWorker("FAKE01", {}, ctx={"job_id": "t1", "device_name": "A01"})
+order = []
+
+
+def fake_exec_ok(d, steps, depth=0):
+    """模拟一段正常的循环体：把当前 target_name 的下一条待发计划标成 done。"""
+    name = w._vars.get('target_name')
+    order.append(name)
+    with app.app_context():
+        row = (models.VideoPlan.query.filter_by(nickname=name, status=vp.ST_READY)
+               .order_by(models.VideoPlan.seq).first())
+        if row:
+            row.status = vp.ST_DONE
+            models.db.session.commit()
+
+
+w._exec_steps = fake_exec_ok
+w._exec_foreach_account(None, {"children": [{"type": "x"}],
+                               "date_source": "fixed", "fixed_date": DATE})
+# 同日期同编号时按名字**码点**定序：李 U+674E < 王 U+738B → 小李先跑
+check('两个号都跑过（小李 1 条 → 小王 2 条）', order, ['小李', '小王', '小王'])
+check('小王两条都发了', status_of()['小王'], ['done', 'done'])
+check('小李发了', status_of()['小李'], ['done'])
+check('未来的小张没动', status_of()['小张'], ['ready'])
+check('跑完把 target_name 清掉了', w._vars.get('target_name'), None)
+
+print('=== 2. 本机没登这个号 → 不卡死，直接换下一个 ===')
+with app.app_context():
+    models.VideoPlan.query.delete()
+    models.db.session.commit()
+seed()
+w2 = gt.GenericStepsWorker("FAKE02", {}, ctx={"job_id": "t2"})
+seen = []
+
+
+def fake_exec_only_xiaowang(d, steps, depth=0):
+    """只有小王的号在这台机器上：切到别人时什么都不做（模拟切号失败/守卫挡下）。"""
+    name = w2._vars.get('target_name')
+    seen.append(name)
+    if name != '小王':
+        return
+    with app.app_context():
+        row = (models.VideoPlan.query.filter_by(nickname=name, status=vp.ST_READY)
+               .order_by(models.VideoPlan.seq).first())
+        if row:
+            row.status = vp.ST_DONE
+            models.db.session.commit()
+
+
+w2._exec_steps = fake_exec_only_xiaowang
+w2._exec_foreach_account(None, {"children": [{"type": "x"}],
+                                "date_source": "fixed", "fixed_date": DATE})
+check('小王发完（2 条）', status_of()['小王'], ['done', 'done'])
+check('小李只被试了 1 次就跳过（没空转）', seen.count('小李'), 1)
+check('试过的名字不回头', seen, ['小李', '小王', '小王'])
+check('小李还是待发', status_of()['小李'], ['ready'])
+
+print('=== 3. 下一轮会接着发小李（上一轮没发完的还在队列里）===')
+w3 = gt.GenericStepsWorker("FAKE03", {}, ctx={"job_id": "t3"})
+
+
+def fake_exec_all(d, steps, depth=0):
+    name = w3._vars.get('target_name')
+    with app.app_context():
+        row = (models.VideoPlan.query.filter_by(nickname=name, status=vp.ST_READY)
+               .order_by(models.VideoPlan.seq).first())
+        if row:
+            row.status = vp.ST_DONE
+            models.db.session.commit()
+
+
+w3._exec_steps = fake_exec_all
+w3._exec_foreach_account(None, {"children": [{"type": "x"}],
+                                "date_source": "fixed", "fixed_date": DATE})
+check('小李补上了', status_of()['小李'], ['done'])
+
+print('=== 4. 没有待发的号 → 干净收工 ===')
+w4 = gt.GenericStepsWorker("FAKE04", {}, ctx={"job_id": "t4"})
+w4._exec_steps = lambda d, s, depth=0: None
+w4._exec_foreach_account(None, {"children": [{"type": "x"}],
+                                "date_source": "fixed", "fixed_date": DATE})
+check('一条都没跑（不会死循环）', w4._vars.get('target_name'), None)
+
+print('=== 5. max_accounts 上限 ===')
+with app.app_context():
+    models.VideoPlan.query.delete()
+    models.db.session.commit()
+seed()
+w5 = gt.GenericStepsWorker("FAKE05", {}, ctx={"job_id": "t5"})
+ran = []
+w5._exec_steps = lambda d, s, depth=0: ran.append(w5._vars.get('target_name'))
+w5._exec_foreach_account(None, {"children": [{"type": "x"}], "max_accounts": 1,
+                               "date_source": "fixed", "fixed_date": DATE})
+check('只跑 1 个号', ran, ['小李'])
+
+print('=== 6. 子步骤为空 → 不报错、直接结束 ===')
+w6 = gt.GenericStepsWorker("FAKE06", {})
+w6._exec_foreach_account(None, {"children": []})
+check('空 children 直接返回', w6._vars.get('target_name'), None)
+
+print()
+shutil.rmtree(TMP, ignore_errors=True)
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（临时库已清理）')
@@ -0,0 +1,224 @@
+# -*- coding: utf-8 -*-
+"""P2 测试：读名字 / 按名字取计划 / 推送前核对（**临时库 + 假设备**，不碰真实数据、不连真机）。"""
+import io
+import os
+import shutil
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+
+TMP = tempfile.mkdtemp(prefix='ac_p2_')
+os.environ['DATABASE_URL'] = 'sqlite:///' + os.path.join(TMP, 'ac.db').replace('\\', '/')
+os.environ['DATA_VIDEO_DIR'] = os.path.join(TMP, 'videos')
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from flask import Flask                                              # noqa: E402
+from core import db_config, models                                   # noqa: E402
+from core import video_plan as vp                                    # noqa: E402
+from tasks.generic import task as gt                                 # noqa: E402
+from tasks.generic import publish_flow as flow                       # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+def ok(label, cond, detail=''):
+    if not cond:
+        fails.append(label)
+    print(('  ✅ ' if cond else '  ❌ ') + label + ('' if cond else '  ' + str(detail)))
+
+
+class StubEl:
+    """假元素：u2 的 XPathSelector / UiObject 各用到的成员都给上。"""
+
+    def __init__(self, text):
+        self._t = text
+
+    @property
+    def exists(self):
+        return self._t is not None
+
+    def wait(self, timeout=0):
+        return self._t is not None
+
+    def get_text(self, timeout=None):
+        return self._t
+
+
+class StubD:
+    def __init__(self, text):
+        self.text = text
+
+    def xpath(self, v):
+        return StubEl(self.text)
+
+
+app = Flask("t")
+uri = db_config.build_db_uri()
+app.config["SQLALCHEMY_DATABASE_URI"] = uri
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+models.db.init_app(app)
+with app.app_context():
+    models.db.create_all()
+vp.init_app(app)
+
+print('=== 1. clean_account_name（纯函数）===')
+check('只有名字', vp.clean_account_name('小王'), '小王')
+check('多行：取第一行', vp.clean_account_name('小王\n编辑资料\n抖音号：35377983067'), '小王')
+check('首行是标签 → 往下找', vp.clean_account_name('编辑资料\n小王'), '小王')
+check('抖音号行跳过', vp.clean_account_name('抖音号：35377983067\n小王'), '小王')
+check('统计行跳过', vp.clean_account_name('关注\n粉丝\n小王'), '小王')
+check('名字里的双空格保留', vp.clean_account_name('有牛奶面包  你吃吗？'), '有牛奶面包  你吃吗？')
+check('名字带表情保留', vp.clean_account_name('🐟小鱼'), '🐟小鱼')
+check('「关注我领福利」不当标签', vp.clean_account_name('关注我领福利'), '关注我领福利')
+check('读到空 → ""', vp.clean_account_name('编辑资料\n抖音号：123'), '')
+check('None → ""', vp.clean_account_name(None), '')
+check('首尾空白去掉', vp.clean_account_name('  小王  '), '小王')
+
+print('=== 2. 临时库里造两条计划（小王 / 小李）===')
+with app.app_context():
+    def mk(name, date, seq, status=vp.ST_READY, title="标题"):
+        row = models.VideoPlan(id=name + str(seq) + date[-2:], nickname=name, phone="",
+                               device_name="", douyin_id="", serial="", release_date=date,
+                               seq=seq, seq_auto=False, title=title, body="",
+                               video_file=f"2026-10/x{seq}.mp4", video_name="x.mp4",
+                               status=status, created_at=vp._now(), updated_at=vp._now())
+        models.db.session.add(row)
+    mk('小王', '2026-09-12', 1)
+    mk('小王', '2026-09-13', 2)          # 同一个号，后天那条
+    mk('小李', '2026-09-12', 1)
+    mk('小张', '2026-09-20', 1)          # 未来：不该被取到
+    mk('小赵', '2026-09-10', 1, status=vp.ST_DONE)   # 已发：不该被取到
+    models.db.session.commit()
+
+    print('=== 3. 按名字取计划 ===')
+    check('小王 在 09-12 有一条', [p['seq'] for p in vp.take_for_name(['小王'], '2026-09-12')], [1])
+    check('取 09-13 时，过期的那条先发', [p['seq'] for p in vp.take_for_name(['小王'], '2026-09-13')], [1])
+    check('小李 只认自己的', [p['nickname'] for p in vp.take_for_name(['小李'], '2026-09-12')],
+          ['小李'])
+    check('没有的名字取不到', vp.take_for_name(['不存在'], '2026-09-12'), [])
+    check('名字为空不取（绝不猜）', vp.take_for_name([], '2026-09-12'), [])
+    check('未来的不发', vp.take_for_name(['小张'], '2026-09-12'), [])
+    check('已发的（done）不再入队', vp.take_for_name(['小赵'], '2026-09-12'), [])
+    check('peek 只看不占位', vp.peek_for_name(['小王'], '2026-09-12')['seq'], 1)
+    check('peek 不存在的名字 → None', vp.peek_for_name(['不存在'], '2026-09-12'), None)
+
+    print('=== 4. pending_names / pending_count（循环块的数据源）===')
+    # 同日期同编号时按名字的**码点**定序（只要确定就行，不追求拼音序）：李 U+674E < 王 U+738B
+    check('有待发内容的名字（按最早日期，同日期按名字定序）',
+          [(x['name'], x['release_date'], x['seq'])
+           for x in vp.pending_names('2026-09-13')],
+          [('小李', '2026-09-12', 1), ('小王', '2026-09-12', 1)])
+    check('只看指定的名字', [x['name'] for x in vp.pending_names('2026-09-13', names=['小王'])],
+          ['小王'])
+    check('小王 待发 2 条', vp.pending_count('小王', '2026-09-13'), 2)
+    check('小李 待发 1 条', vp.pending_count('小李', '2026-09-13'), 1)
+    check('已完成的名字不在列表里', [x['name'] for x in vp.pending_names('2026-09-12', names=['小赵'])],
+          [])
+    check('未来日期还没到 → 今天不列', vp.pending_count('小张', '2026-09-12'), 0)
+
+    print('=== 5. 读名字步骤（假设备）===')
+    ctx = {"job_id": "t1", "job_name": "测试"}
+    w = gt.GenericStepsWorker("FAKE01", {}, ctx=ctx)
+    el_raw = '小王\n编辑资料\n抖音号：35377983067'
+    r = w._exec_read_account_name(StubD(el_raw), {"selector_type": "xpath",
+                                                  "selector_value": "//x", "timeout": 1})
+    check('读到名字 → True', r, True)
+    check('_vars.account_name', w._vars.get('account_name'), '小王')
+    check('_vars.name_selector 记下了', w._vars.get('name_selector'), ('xpath', '//x'))
+
+    w2 = gt.GenericStepsWorker("FAKE02", {}, ctx=ctx)
+    r2 = w2._exec_read_account_name(StubD('编辑资料\n抖音号：123'),
+                                    {"selector_type": "xpath", "selector_value": "//x", "timeout": 1})
+    check('读不到（on_missing=fail）→ False', r2, False)
+    check('读不到时不写 account_name', w2._vars.get('account_name'), None)
+
+    w3 = gt.GenericStepsWorker("FAKE03", {}, ctx=ctx)
+    r3 = w3._exec_read_account_name(StubD('编辑资料'), {"selector_type": "xpath",
+                                                       "selector_value": "//x",
+                                                       "on_missing": "skip"})
+    check('on_missing=skip → None（不失败）', r3, None)
+
+    w4 = gt.GenericStepsWorker("FAKE04", {}, ctx=ctx)
+    r4 = w4._exec_read_account_name(StubD('小王'), {"selector_type": "xpath",
+                                                   "selector_value": ""})
+    check('选择器为空 → False（并提示去抓元素）', r4, False)
+
+    print('=== 6. _release_scope：这次发的是哪个号 ===')
+    check('默认按名字（读到谁就是谁）', w._release_scope({}), ('name', ['小王'], '名字『小王』'))
+    check('没有名字 → 空值（跳过，不猜）', w2._release_scope({}),
+          ('name', [], '没读到本机账号名字（前面要有「读取本机账号名字」，'
+                       '或由循环块设目标名字）→ 跳过'))
+    check('account=phone 走老路径', w._release_scope({'account': 'phone',
+                                                    'account_phone': '13300000000'}),
+          ('phone', ['13300000000'], '指定手机号 13300000000'))
+    check('cycle 设的目标名字优先', (w._vars.__setitem__('target_name', '小李'),
+                                    w._release_scope({}))[1], ('name', ['小李'], '名字『小李』'))
+    w._vars.pop('target_name')
+
+    print('=== 7. 条件判断候选值 ===')
+    txt, note = w._resolve_cmp_value({'cmp_source': 'account_target'}, '')
+    check('account_target → 候选=名字', txt, '小王')
+    ok('说明里写了名字', '小王' in note, note)
+    txt2, _ = w2._resolve_cmp_value({'cmp_source': 'account_target'}, '')
+    check('读不到名字 → 候选为空（永远不命中 → 不发）', txt2, '')
+    txt3, _ = w2._resolve_cmp_value({'cmp_source': 'account_target', 'cmp_value': '手填的'}, '手填的')
+    check('读不到名字时手填值仍然生效', txt3, '手填的')
+
+    print('=== 8. 推送前核对（假设备，push_one 打桩）===')
+    calls = []
+    orig = flow.push_one
+
+    def fake_push(serial, plan, opts, log=None):
+        calls.append((serial, plan['id']))
+        return True, "ok"
+
+    flow.push_one = fake_push
+    try:
+        # 8a 屏幕上不是我们要发的人 → 不推
+        w._vars['account_name'] = '小王'
+        w._vars['name_selector'] = ('xpath', '//x')
+        bad = w._exec_push_release(StubD('小李'), {'account': 'name',
+                                                  'date_source': 'fixed',
+                                                  'fixed_date': '2026-09-12'})
+        check('核对不过 → 不推（返回 None）', bad, None)
+        check('push_one 一次都没调', calls, [])
+
+        # 8b 屏幕上就是本人 → 推
+        good = w._exec_push_release(StubD('小王'), {'account': 'name',
+                                                   'date_source': 'fixed',
+                                                   'fixed_date': '2026-09-12'})
+        check('核对通过 → 推成功', good, True)
+        check('push_one 被调了 1 次', len(calls), 1)
+        check('推的是小王那条', calls[0][1], '小王112')
+
+        # 8c 读不到名字 → 不推
+        calls.clear()
+        w2._vars['name_selector'] = ('xpath', '//x')
+        none_ = w2._exec_push_release(StubD('编辑资料'), {'date_source': 'fixed',
+                                                          'fixed_date': '2026-09-12'})
+        check('读不到名字 → 不推', none_, None)
+        check('push_one 没被调', calls, [])
+    finally:
+        flow.push_one = orig
+
+print()
+shutil.rmtree(TMP, ignore_errors=True)
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（临时库已清理）')
@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""P1 纯函数测试：`名字_日期_编号` 解析（不碰 DB、不碰用户数据）。"""
+import io
+import os
+import sys
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+from core import video_plan as vp                                     # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+print('=== parse_video_name：合法 ===')
+check('名字_日期_编号', vp.parse_video_name('小王_20260912_1.mp4')[0],
+      {"name": "小王", "date": "2026-09-12", "seq": 1, "seq_given": True})
+check('名字_日期（无编号）', vp.parse_video_name('建材王总_20260913.mp4')[0],
+      {"name": "建材王总", "date": "2026-09-13", "seq": None, "seq_given": False})
+check('名字里带数字', vp.parse_video_name('翻斗花园我最强2号_20260913.mp4')[0]['name'], '翻斗花园我最强2号')
+check('名字里带空格/表情', vp.parse_video_name('有牛奶面包  你吃吗？_20260912_2.mp4')[0]['name'],
+      '有牛奶面包  你吃吗？')
+check('名字里带表情', vp.parse_video_name('🐟小鱼_20260912.mp4')[0]['name'], '🐟小鱼')
+check('大写扩展名', vp.parse_video_name('小王_20260912.MP4')[0]['date'], '2026-09-12')
+check('编号 3 位', vp.parse_video_name('小王_20260912_999.mp4')[0]['seq'], 999)
+
+print('=== parse_video_name：图片（图文）也认 ===')
+check('jpg', vp.parse_video_name('小王_20260912_1.jpg')[0],
+      {"name": "小王", "date": "2026-09-12", "seq": 1, "seq_given": True})
+check('png（无编号）', vp.parse_video_name('建材王总_20260913.png')[0],
+      {"name": "建材王总", "date": "2026-09-13", "seq": None, "seq_given": False})
+check('大写 JPG', vp.parse_video_name('小王_20260912.JPG')[0]['name'], '小王')
+check('webp', vp.parse_video_name('小王_20260912.webp')[0]['date'], '2026-09-12')
+check('gif 不收（没进白名单）',
+      '不是视频/图片' in (vp.parse_video_name('小王_20260912.gif')[1] or ''), True)
+
+print('=== parse_video_name：拒收 ===')
+
+
+def err_of(fn):
+    return fn[1]
+
+
+check('名字带下划线', err_of(vp.parse_video_name('小_王_20260912.mp4')),
+      '名字里不能有下划线：`小_王_20260912` 里日期前面有 2 段 ——应为 名字_日期_编号')
+check('名字是纯数字', err_of(vp.parse_video_name('12345678_20260912.mp4')),
+      '名字不能是纯数字（12345678 会被当成日期/编号）—— 请填抖音上的昵称')
+check('结尾不是日期', err_of(vp.parse_video_name('小王_20260912_1234.mp4')),
+      '文件名格式不对：`小王_20260912_1234` 的结尾既不是日期（8 位数字，如 20260912），'
+      '也不是「日期_编号」—— 应为 名字_日期_编号')
+check('老格式（手机号在前）', err_of(vp.parse_video_name('13382508423_20261011_01.mp4')),
+      '这一段（13382508423）是手机号 —— 文件名第一段要填**抖音上的名字**，'
+      '格式是 名字_日期_编号（现在不认手机号了）')
+check('非法日期', err_of(vp.parse_video_name('小王_20260230.mp4')),
+      '日期 20260230 不是合法日期（应为 20260912 这种 8 位）')
+check('只有一段', err_of(vp.parse_video_name('小王.mp4')),
+      '文件名格式不对，应为 名字_日期_编号（编号可省略，如 小王_20260912.mp4）')
+check('不是视频/图片', err_of(vp.parse_video_name('小王_20260912.txt')),
+      '不是视频/图片文件（支持 mp4/mov/mkv/avi/3gp/flv/wmv/m4v/ts/webm/jpg/jpeg/png/webp/heic）')
+check('空文件名', err_of(vp.parse_video_name('')), '文件名为空')
+check('多段（名字含下划线还带日期）', err_of(vp.parse_video_name('小_王_总_20260912.mp4')),
+      '名字里不能有下划线：`小_王_总_20260912` 里日期前面有 3 段 ——应为 名字_日期_编号')
+
+print('=== parse_title_line：合法 ===')
+check('标题 || 正文_名字_日期_编号', vp.parse_title_line('中秋祝福 || 祝大家中秋快乐_小王_20260912_1')[0],
+      {"title": "中秋祝福", "body": "祝大家中秋快乐", "name": "小王",
+       "date": "2026-09-12", "seq": 1, "seq_given": True})
+check('只有标题', vp.parse_title_line('中秋祝福_小王_20260912')[0],
+      {"title": "中秋祝福", "body": "", "name": "小王",
+       "date": "2026-09-12", "seq": None, "seq_given": False})
+check('只有正文（|| 在最前）', vp.parse_title_line(' || 只有正文_小王_20260912')[0]['body'], '只有正文')
+check('标题里带下划线', vp.parse_title_line('名字带_下划线也行_小王_20260912')[0]['title'], '名字带_下划线也行')
+check('#话题开头的标题', vp.parse_title_line('#中秋快乐_小王_20260929')[0]['title'], '#中秋快乐')
+check('正文里再有 || 原样保留', vp.parse_title_line('标题 || 正文 || 又一处_小王_20260912')[0]['body'],
+      '正文 || 又一处')
+check('标题是纯数字', vp.parse_title_line('2026_小王_20260912_1')[0]['title'], '2026')
+
+print('=== parse_title_line：拒收 ===')
+check('只有名字/日期（没文字）', err_of(vp.parse_title_line('小王_20260912')),
+      '缺标题/正文内容（只有名字/日期/编号，没有文字）')
+check('名字/日期/编号（没文字）', err_of(vp.parse_title_line('小王_20260912_1')),
+      '缺标题/正文内容（只有名字/日期/编号，没有文字）')
+check('老写法（名字在前）', err_of(vp.parse_title_line('19286456013_20260912_1_标题')),
+      "格式不对，应为「标题 || 正文_名字_日期_编号」（编号可省略；日期是 8 位数字，如 20260912）")
+check('名字是手机号', err_of(vp.parse_title_line('标题_13382508423_20260912')),
+      '这一段（13382508423）是手机号 —— 文件名第一段要填**抖音上的名字**，'
+      '格式是 名字_日期_编号（现在不认手机号了）')
+check('标题里带下划线（名字取紧挨日期那段）',
+      vp.parse_title_line('标题_小_王_20260912')[0],
+      {"title": "标题_小", "body": "", "name": "王", "date": "2026-09-12",
+       "seq": None, "seq_given": False})
+check('空行', err_of(vp.parse_title_line('   ')), '空行')
+
+print('=== parse_titles_text：注释与多行 ===')
+rows, errors = vp.parse_titles_text(
+    '标题一_小王_20260912\n# 这是注释\n\n#中秋快乐_小王_20260913\n'
+    '#真注释_没有日期\n标题没有日期')
+check('收下 2 条标题', [r['title'] for r in rows], ['标题一', '#中秋快乐'])
+check('# 认不出名字/日期 → 当注释忽略', [(e['line'], e['raw']) for e in errors], [(6, '标题没有日期')])
+
+print('=== pair_slots：按名字配对 ===')
+videos = [dict(vp.parse_video_name('小王_20260912_1.mp4')[0], ref='v1'),
+          dict(vp.parse_video_name('小王_20260912_2.mp4')[0], ref='v2'),
+          dict(vp.parse_video_name('小李_20260912.mp4')[0], ref='v3')]
+titles = [dict(vp.parse_title_line('标题A_小王_20260912')[0], ref='t1'),
+          dict(vp.parse_title_line('标题B_小王_20260912')[0], ref='t2'),
+          dict(vp.parse_title_line('标题C_小李_20260912')[0], ref='t3')]
+pairs, rejected = vp.pair_slots(videos, titles)
+check('配成 3 对', len(pairs), 3)
+check('没有拒收', rejected, [])
+check('按 (日期,名字,编号) 排序', [(p['date'], p['name'], p['seq']) for p in pairs],
+      [('2026-09-12', '小李', 1), ('2026-09-12', '小王', 1), ('2026-09-12', '小王', 2)])
+check('每对都配上标题', sorted(p['title']['title'] for p in pairs), ['标题A', '标题B', '标题C'])
+check('配对结果里的键是 name', all('name' in p and 'phone' not in p for p in pairs), True)
+
+print()
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过')
@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+"""P6 测试：按名字找设备推送（`_push_by_name`）—— 临时库 + 假探测/假推送，不碰真机。"""
+import io
+import os
+import shutil
+import sys
+import tempfile
+import time
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+
+TMP = tempfile.mkdtemp(prefix='ac_p6_')
+os.environ['DATABASE_URL'] = 'sqlite:///' + TMP.replace(chr(92), '/') + '/ac.db'
+os.environ['DATA_VIDEO_DIR'] = os.path.join(TMP, 'videos')
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from flask import Flask                                              # noqa: E402
+from core import db_config, models, device_pool                      # noqa: E402
+from core import video_plan as vp                                    # noqa: E402
+from core import account_probe                                       # noqa: E402
+from tasks.generic import publish_flow as flow                       # noqa: E402
+from web import video_plan_api as vapi                               # noqa: E402
+
+DATE = '2026-09-12'
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+app = Flask("t")
+uri = db_config.build_db_uri()
+app.config["SQLALCHEMY_DATABASE_URI"] = uri
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+models.db.init_app(app)
+with app.app_context():
+    models.db.create_all()
+vp.init_app(app)
+device_pool.init_app(app)
+
+with app.app_context():
+    models.db.session.add(models.Device(serial='A:5555', name='A01', enabled=True,
+                                        created_at=vp._now()))
+    models.db.session.add(models.Device(serial='B:5555', name='A02', enabled=True,
+                                        created_at=vp._now()))
+    for i, (nm, s) in enumerate([('小王', 1), ('小王', 2), ('小李', 1)]):
+        models.db.session.add(models.VideoPlan(
+            id='p%d' % i, nickname=nm, phone='', device_name='', douyin_id='', serial='',
+            release_date=DATE, seq=s, seq_auto=False, title='t', body='',
+            video_file='x', video_name='x', status=vp.ST_READY,
+            created_at=vp._now(), updated_at=vp._now()))
+    models.db.session.commit()
+
+pushed = []
+lock = []
+
+
+def fake_push(serial, plan, opts=None, log=None):
+    pushed.append((serial, plan['nickname'], plan['seq'], (opts or {}).get('device_name')))
+    return True, "ok"
+
+
+print('=== 1. 名字 → 设备（两台设备各登一个）===')
+probe = {'A:5555': {'serial': 'A:5555', 'name': '小王', 'error': ''},
+         'B:5555': {'serial': 'B:5555', 'name': '小李', 'error': ''}}
+orig_probe, orig_push = account_probe.probe_online, flow.push_one
+account_probe.probe_online = lambda serials=None, skip_busy=True, workers=4: probe
+flow.push_one = fake_push
+try:
+    with app.app_context():
+        rows = vp.pushable_plans(DATE)
+        matched, unmatched = vapi._push_by_name(rows)
+        deadline = time.time() + 3
+        while len(pushed) < 3 and time.time() < deadline:
+            time.sleep(0.05)
+    check('两个名字都找到设备', sorted((m['name'], m['count']) for m in matched),
+          [('小李', 1), ('小王', 2)])
+    check('小王的设备是 A01', [m['device_name'] for m in matched if m['name'] == '小王'], ['A01'])
+    check('没有 unmatched', unmatched, [])
+    check('推了小王的 2 条 + 小李的 1 条', len(pushed), 3)
+    check('推给 A 的是小王的两条（按编号）',
+          sorted((s, q) for (ser, n, q, dn) in pushed if ser == 'A:5555'), [(1, 1), (1, 2)])
+    check('推给 B 的是小李', [(n, q) for (ser, n, q, dn) in pushed if ser == 'B:5555'],
+          [('小李', 1)])
+    check('顺手把设备名字传给了 push_one（写 posted_device_name 用）',
+          {dn for (ser, n, q, dn) in pushed}, {'A01', 'A02'})
+    with app.app_context():
+        cached = [(d.serial, d.cur_account_name)
+                  for d in models.Device.query.order_by(models.Device.serial)]
+    check('探测结果缓存进了 device 表', cached,
+          [('A:5555', '小王'), ('B:5555', '小李')])
+
+    print('=== 2. 没人登着某个名字 → unmatched 里逐条说明 ===')
+    pushed.clear()
+    probe2 = {'A:5555': {'serial': 'A:5555', 'name': '小王', 'error': ''},
+              'B:5555': {'serial': 'B:5555', 'name': '别的号', 'error': ''}}
+    account_probe.probe_online = lambda serials=None, skip_busy=True, workers=4: probe2
+    with app.app_context():
+        rows = vp.pushable_plans(DATE)
+        matched2, unmatched2 = vapi._push_by_name(rows)
+        deadline = time.time() + 3
+        while len(pushed) < 2 and time.time() < deadline:
+            time.sleep(0.05)
+    check('只推了小王那 2 条', len(pushed), 2)
+    check('小李进了 unmatched', [(u['name'], u['count']) for u in unmatched2], [('小李', 1)])
+    check('原因说清了「先切号」', ('没有在线设备登着' in unmatched2[0]['reason']
+                                  and '小李' in unmatched2[0]['reason']
+                                  and '先到设备上切到它' in unmatched2[0]['reason']), True)
+    check('原因里带上当前探测到的号（排查用，别把整个 dict 打出来）',
+          unmatched2[0]['reason'].endswith('（当前探测到：A:5555(小王)、B:5555(别的号)）'), True)
+    if 'dict' in unmatched2[0]['reason'] or '{' in unmatched2[0]['reason']:
+        print('     原因里混进了原始 dict：', unmatched2[0]['reason'])
+
+    print('=== 3. 探测失败（比如选择器没配）→ 也算没设备登着，不炸 ===')
+    pushed.clear()
+    account_probe.probe_online = lambda serials=None, skip_busy=True, workers=4: {
+        'A:5555': {'serial': 'A:5555', 'name': '', 'error': '还没抓昵称控件'},
+        'B:5555': {'serial': 'B:5555', 'name': '', 'error': '连不上设备'}}
+    with app.app_context():
+        rows = vp.pushable_plans(DATE)
+        matched3, unmatched3 = vapi._push_by_name(rows)
+    check('一条都没推', pushed, [])
+    check('两个名字都 unmatched', sorted(u['name'] for u in unmatched3), ['小李', '小王'])
+    with app.app_context():
+        keep = models.Device.query.get('A:5555').cur_account_name
+    check('失败的那台不清空旧缓存', keep, '小王')
+finally:
+    account_probe.probe_online, flow.push_one = orig_probe, orig_push
+
+print()
+shutil.rmtree(TMP, ignore_errors=True)
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（临时库已清理）')
@@ -0,0 +1,198 @@
+# -*- coding: utf-8 -*-
+"""「读取文字」+ 选择器里的 `{变量}` +「条件判断→变量」用例。
+
+假设备，不连真机。验三件事：
+  ① 选择器值里写 `{本次要发的名字}` / `{本机账号名字}` → 真的换成本轮的值；
+     变量是空的 → 换成空串、这一步找不到元素（**不能留着字面量去瞎点**）；
+  ② 「读取文字」把元素文字读出来、清洗、存进指定变量（变量名叫 account_name 时顺手记下昵称控件）；
+  ③ 「条件判断」候选值来源选「变量」→ 候选就是那个变量的值，空变量 = 不命中。
+"""
+import io
+import os
+import sqlite3
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+os.environ['DATABASE_URL'] = 'sqlite:///' + os.path.join(tempfile.mkdtemp(), 'ac.db').replace('\\', '/')
+os.environ['DATA_VIDEO_DIR'] = tempfile.mkdtemp()
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+os.chdir(sys.path[0])
+
+from tasks.generic import task as gt                                   # noqa: E402
+from core import task_draft                                            # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+class El:
+    def __init__(self, flag, text=""):
+        self._flag = flag
+        self._text = text
+        self.clicked = False
+
+    @property
+    def exists(self):
+        return _Ex(self._flag)
+
+    def wait(self, timeout=0):
+        return self._flag
+
+    def get_text(self, timeout=None):
+        return self._text
+
+    def click(self):
+        self.clicked = True
+
+
+class _Ex:
+    def __init__(self, f):
+        self.f = f
+
+    def __call__(self, timeout=0):
+        return self.f
+
+    def __bool__(self):
+        return self.f
+
+
+class StubD:
+    """`kw` 里记最后一次 d(**kw) 的参数；`texts` 给元素文本。"""
+
+    def __init__(self, present=(), texts=None):
+        self.present = set(present)
+        self.texts = texts or {}
+        self.last_kw = None
+        self.clicked = []
+
+    def xpath(self, v):
+        return El(v in self.present, self.texts.get(v, ""))
+
+    def __call__(self, **kw):
+        self.last_kw = kw
+        v = list(kw.values())[0]
+        if v in self.present:
+            self.clicked.append(v)
+        return El(v in self.present, self.texts.get(v, ""))
+
+
+print('=== 1. 选择器值里的 {本次要发的名字} 换成本轮目标 ===')
+w = gt.GenericStepsWorker("F1", {})
+w._vars['target_name'] = '锋哥苏州寻宝藏小店'
+d = StubD(present=['锋哥苏州寻宝藏小店'])
+check('点击命中（说明选择器已代入）',
+      w._exec_click(d, {"selector_type": "textContains",
+                        "selector_value": "{本次要发的名字}", "wait_timeout": 1}, 0), True)
+check('实际用的选择器 = 名字本身', d.last_kw, {'textContains': '锋哥苏州寻宝藏小店'})
+
+print('=== 2. 变量还是空的 → 选择器变空 → 不许瞎点 ===')
+w = gt.GenericStepsWorker("F2", {})
+d = StubD(present=[''])
+check('返回 False（没找到）',
+      w._exec_click(d, {"selector_type": "textContains",
+                        "selector_value": "prefix-{本次要发的名字}", "wait_timeout": 1}, 0), False)
+check('空变量 → 字符串里不留 {…} 字面量', d.last_kw, {'textContains': 'prefix-'})
+
+print('=== 3. {本机账号名字} 用「读取文字」读到的值 ===')
+w = gt.GenericStepsWorker("F3", {})
+w._vars['account_name'] = '小王'
+d = StubD(present=['小王'])
+check('等待元素命中', w._exec_wait_el(d, {"selector_type": "text",
+                                          "selector_value": "{本机账号名字}", "timeout": 1}, 0), True)
+check('用的是本机账号名', d.last_kw, {'text': '小王'})
+
+print('=== 4. 「读取文字」读出来、清洗、存变量 ===')
+w = gt.GenericStepsWorker("F4", {})
+d = StubD(present=['//*[@text="nick"]'],
+          texts={'//*[@text="nick"]': '  锋哥苏州康养探店  \n编辑资料  \n抖音号：123'})
+check('返回 True', w._exec_read_text(d, {"selector_type": "xpath",
+                                        "selector_value": '//*[@text="nick"]',
+                                        "var": "account_name", "clean": "account",
+                                        "timeout": 1}, 0), True)
+check('存进 account_name（按账号名清洗：取第一行非标签）',
+      w._vars.get('account_name'), '锋哥苏州康养探店')
+check('顺手记下昵称控件（切号/推送核对复用）',
+      w._vars.get('name_selector'), ('xpath', '//*[@text="nick"]'))
+
+print('=== 5. clean=strip：原样（只去首尾空白） ===')
+w = gt.GenericStepsWorker("F5", {})
+d = StubD(present=['//*[@text="x"]'],
+          texts={'//*[@text="x"]': '  小王  \n编辑资料'})
+w._exec_read_text(d, {"selector_type": "xpath", "selector_value": '//*[@text="x"]',
+                      "var": "raw_name", "clean": "strip", "timeout": 1}, 0)
+check('只去首尾空白、不按行取', w._vars.get('raw_name'), '小王  \n编辑资料')
+check('变量名不是 account_name → 不记昵称控件', w._vars.get('name_selector'), None)
+
+print('=== 6. 读不到：默认 skip（只记一句、不拦任务） ===')
+w = gt.GenericStepsWorker("F6", {})
+d = StubD(present=[])
+check('返回 None（skip 不算失败）',
+      w._exec_read_text(d, {"selector_type": "xpath", "selector_value": '//*[@text="没有"]',
+                            "var": "account_name", "timeout": 1}, 0), None)
+check('变量被置空', w._vars.get('account_name'), '')
+
+print('=== 7. 读不到 + on_missing=fail → 算这一步失败 ===')
+w = gt.GenericStepsWorker("F7", {})
+d = StubD(present=[])
+check('返回 False',
+      w._exec_read_text(d, {"selector_type": "xpath", "selector_value": '//*[@text="没有"]',
+                            "var": "v", "timeout": 1, "on_missing": "fail"}, 0), False)
+
+print('=== 8. 「条件判断」候选值来源=变量 ===')
+w = gt.GenericStepsWorker("F8", {})
+w._vars['account_name'] = '小王'
+val, note = w._resolve_cmp_value({"cmp_op": "等于", "cmp_source": "var",
+                                  "cmp_var": "account_name"}, "")
+check('候选值 = 变量的值', val, '小王')
+check('来源说明写清了', 'account_name' in note and '小王' in note, True)
+
+print('=== 9. 变量是空的 → 候选为空（永远不命中，走 else） ===')
+w = gt.GenericStepsWorker("F9", {})
+val, note = w._resolve_cmp_value({"cmp_op": "等于", "cmp_source": "var",
+                                  "cmp_var": "account_name"}, "手填兜底")
+check('只剩手填值', val, '手填兜底')
+check('说明里点出变量是空的', '空' in note, True)
+
+print('=== 10. 草稿校验认这两个新能力 ===')
+ok_steps = [{"type": "read_text", "label": "读取文字",
+             "params": {"selector_type": "xpath", "selector_value": '//*[@id="nick"]',
+                        "var": "account_name"}},
+            {"type": "if_el", "label": "条件判断",
+             "params": {"selector_type": "xpath", "selector_value": '//*[@id="nick"]',
+                        "cmp_op": "包含", "cmp_source": "var", "cmp_var": "account_name",
+                        "then": [{"type": "notify", "label": "命中",
+                                  "params": {"title": "ok", "message": "ok"}}],
+                        "else": []}}]
+errs, warns = [], []
+task_draft.validate_steps(ok_steps, errors=errs, warnings=warns)
+check('合法草稿没有 error', errs, [])
+
+bad_steps = [{"type": "read_text", "label": "读取文字",
+              "params": {"selector_type": "xpath", "selector_value": ""}}]
+errs2 = []
+task_draft.validate_steps(bad_steps, errors=errs2, warnings=[])
+check('「读取文字」缺选择器 → 报错',
+      any('selector_value' in e for e in errs2), True)
+
+bad2 = [{"type": "if_el", "label": "条件判断",
+         "params": {"selector_type": "xpath", "selector_value": '//*[@id="x"]',
+                    "cmp_op": "包含", "cmp_source": "var", "then": [], "else": []}}]
+errs3 = []
+task_draft.validate_steps(bad2, errors=errs3, warnings=[])
+check('来源=变量但没填变量名 → 报错',
+      any('cmp_var' in e for e in errs3), True)
+
+print()
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（没连任何真机）')
@@ -0,0 +1,213 @@
+# -*- coding: utf-8 -*-
+"""P4 测试：`switch_account`（按名字找控件点击 + 回读校验）—— 假设备，不碰真机。
+
+不连 adb、不连真机：`d` 是个模拟对象，只实现 u2 里这一步用到的那几个成员。
+"""
+import io
+import os
+import sys
+import time
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+os.environ['DATABASE_URL'] = 'sqlite:///:memory:'
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from tasks.generic import task as gt                                 # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+class Exists:
+    """u2 的 `exists` 语义：**既可当属性判真假、也可当函数带超时调用**。
+
+    真实 u2 里 `d.xpath(...).exists` 是纯 bool 属性，而 `d(text=...).exists` 是
+    可调用的 Exists 对象（`bool()` 即时判断、`exists(timeout=t)` 带等待）。
+    两处写法都要能被这一步的代码用，所以桩里做个两者通吃的。
+    """
+
+    def __init__(self, flag):
+        self.flag = flag
+
+    def __call__(self, timeout=0):
+        return self.flag
+
+    def __bool__(self):
+        return self.flag
+
+
+class El:
+    def __init__(self, text=None, exists=True, on_click=None):
+        self._t = text
+        self._on = on_click
+        self._e = Exists(exists)
+
+    @property
+    def exists(self):
+        return self._e
+
+    def wait(self, timeout=0):
+        return self._e.flag
+
+    def get_text(self, timeout=None):
+        return self._t
+
+    def click(self):
+        if self._on:
+            self._on()
+
+
+class StubD:
+    """模拟抖音：能读昵称、能进账号列表、能按名字点号。"""
+
+    def __init__(self, cur='小李', accounts=('小王', '小李'), login=False):
+        self.cur = cur
+        self.accounts = list(accounts)
+        self.login = login
+        self.clicked = []
+        self.switch_ok = True          # False = 点了但没切过去（模拟没生效）
+        self.switch_open = True        # False = 进不去账号列表
+
+    def _click_name(self, name):
+        self.clicked.append(name)
+        if self.switch_ok:
+            self.cur = name
+            self.accounts = []      # 真机上点成功后**面板会关掉**（那几行消失）——
+            # 步骤就是靠这个判断"点成功了"的：面板还在 = 这一下被吞了，要再点一次
+
+    LOGIN_HINTS = ('验证码', '其他方式登录', '手机号登录', '一键登录', '密码登录')
+
+    def xpath(self, v):
+        if v == '//name':
+            # 登录页上**根本没有昵称这个控件**（元素不存在）—— 这才是真实情况，
+            # 所以"读名字"会读到空串（而不是读到一堆登录页的文字）
+            return El(None, exists=False) if self.login else El(self.cur)
+        if v == '//switch':
+            return El('', exists=(self.switch_open and not self.login))
+        return El('', exists=False)
+
+    def __call__(self, **kw):
+        if 'descriptionContains' in kw:
+            return El('', exists=(kw['descriptionContains'] == '我'))
+        if 'textContains' in kw:
+            nm = kw['textContains']
+            if self.login and nm in self.LOGIN_HINTS:
+                return El(nm)
+            if nm in self.accounts:
+                return El(nm, on_click=lambda n=nm: self._click_name(n))
+            return El('', exists=False)
+        if 'text' in kw:
+            nm = kw['text']
+            if nm in self.accounts:
+                return El(nm, on_click=lambda n=nm: self._click_name(n))
+            return El('', exists=False)
+        return El('', exists=False)
+
+
+PARAMS = {'target': 'var:target_name', 'switch_selector_type': 'xpath',
+          'switch_selector_value': '//switch', 'name_selector_type': 'xpath',
+          'name_selector_value': '//name', 'timeout': 1, 'max_attempts': 2,
+          # 切完后等它重载的秒数（真机默认 15s）—— 用例里调小，不然一跑就是一分多钟
+          'wait_after': 0.2}
+
+notes = []
+orig_notify = gt.notifier.notify
+gt.notifier.notify = lambda ev, **kw: notes.append((ev, kw.get('want') or ''))
+try:
+    print('=== 1. 已经是目标 → 直接成功，不点任何东西 ===')
+    w = gt.GenericStepsWorker("F1", {})
+    w._vars['target_name'] = '小李'
+    d = StubD(cur='小李')
+    check('返回 True', w._exec_switch_account(d, PARAMS), True)
+    check('一个号都没点', d.clicked, [])
+
+    print('=== 2. 切到另一个号（在列表里按名字点）===')
+    w = gt.GenericStepsWorker("F2", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李')
+    check('返回 True', w._exec_switch_account(d, PARAMS), True)
+    check('点是按名字点的', d.clicked, ['小王'])
+    check('当前号变了', d.cur, '小王')
+    check('顺手把运行期变量同步成新名字', w._vars.get('account_name'), '小王')
+
+    print('=== 3. 列表里没有这个名字（本机没登）→ 立刻 False、不重试 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F3", {})
+    w._vars['target_name'] = '不存在的号'
+    d = StubD(cur='小李')
+    check('返回 False', w._exec_switch_account(d, PARAMS), False)
+    check('只找了一次（没重试）', d.clicked, [])
+    check('发了切号失败通知', [n[0] for n in notes], ['task.account.switch_failed'])
+    check('通知里带上想切的目标', notes[0][1], '不存在的号')
+
+    print('=== 4. 点了但没切过去 → 按 max_attempts 重试后放弃 + 通知 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F4", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李')
+    d.switch_ok = False            # 抖音没反应
+    check('返回 False', w._exec_switch_account(d, PARAMS), False)
+    # 面板一直没关（点一次吞一次）→ 每次尝试点两下、共 2 次尝试
+    check('试了 2 次尝试、每次点两下', d.clicked, ['小王', '小王', '小王', '小王'])
+    check('发了切号失败通知', [n[0] for n in notes], ['task.account.switch_failed'])
+
+    print('=== 5. 卡在登录/验证码页 → 通知 + 停本设备 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F5", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李', login=True)
+    check('返回 False', w._exec_switch_account(d, PARAMS), False)
+    check('发了 need_login 通知', [n[0] for n in notes], ['task.account.need_login'])
+    check('本设备已停止', w.stopped(), True)
+
+    print('=== 6. on_login_page=continue → 不停设备（只记一句）===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F6", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李', login=True)
+    p = dict(PARAMS, on_login_page='continue')
+    check('返回 False', w._exec_switch_account(d, p), False)
+    check('还是发了 need_login 通知', [n[0] for n in notes], ['task.account.need_login'])
+    check('设备没被停', w.stopped(), False)
+
+    print('=== 7. 进账号列表的选择器没配 → 明确报错、不乱点 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F7", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李')
+    p = dict(PARAMS, switch_selector_value='')
+    check('返回 False', w._exec_switch_account(d, p), False)
+    check('没点任何东西', d.clicked, [])
+    check('没瞎发通知（这是配置问题，不是切号失败）', notes, [])
+
+    print('=== 8. 没给目标名字 → 跳过 ===')
+    w = gt.GenericStepsWorker("F8", {})
+    d = StubD(cur='小李')
+    check('返回 False', w._exec_switch_account(d, PARAMS), False)
+    check('没点任何东西', d.clicked, [])
+
+    print('=== 9. verify=False → 点了就算过（不回读）===')
+    w = gt.GenericStepsWorker("F9", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李')
+    d.switch_ok = False
+    check('返回 True', w._exec_switch_account(d, dict(PARAMS, verify=False)), True)
+finally:
+    gt.notifier.notify = orig_notify
+
+print()
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（没连任何真机）')
@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+"""P1 集成测试：按名字上传/配标题走通（**临时 SQLite + 临时视频目录**，不碰真实数据）。"""
+import io
+import os
+import shutil
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+
+TMP = tempfile.mkdtemp(prefix='ac_p1_')
+os.environ['DATABASE_URL'] = 'sqlite:///' + os.path.join(TMP, 'ac.db').replace('\\', '/')
+os.environ['DATA_VIDEO_DIR'] = os.path.join(TMP, 'videos')
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from flask import Flask                                              # noqa: E402
+from sqlalchemy import inspect                                       # noqa: E402
+from core import db_config, models                                   # noqa: E402
+from core import video_plan as vp                                    # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+def ok(label, cond, detail=''):
+    if not cond:
+        fails.append(label)
+    print(('  ✅ ' if cond else '  ❌ ') + label + ('' if cond else '  ' + str(detail)))
+
+
+class FakeFile:
+    """够用的 FileStorage 替身：只用到 .filename / .stream。"""
+
+    def __init__(self, filename, data):
+        self.filename = filename
+        self.stream = io.BytesIO(data)
+
+
+app = Flask("t")
+uri = db_config.build_db_uri()
+print('测试库:', uri)
+app.config["SQLALCHEMY_DATABASE_URI"] = uri
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+models.db.init_app(app)
+with app.app_context():
+    models.db.create_all()
+    models._ensure_plain_indexes()        # 生产启动路径里的那一步（老库补索引）
+vp.init_app(app)
+
+with app.app_context():
+    print('=== 0. 前提：台账一张空表也不依赖 ===')
+    check('device_account 里 0 行（上传完全不查台账）', models.DeviceAccount.query.count(), 0)
+    check('video_plan 里 0 行', models.VideoPlan.query.count(), 0)
+
+    print('=== 1. 上传：名字_日期_编号 ===')
+    r = vp.upload_video(FakeFile('小王_20260912_1.mp4', b'A' * 500))
+    ok('上传成功', r.get('ok') is True, r)
+    p = r['plan']
+    check('昵称 = 文件名里的名字', p['nickname'], '小王')
+    check('手机号留空（不再写台账快照）', p['phone'], '')
+    check('设备号留空', p['device_name'], '')
+    check('发布日期', p['release_date'], '2026-09-12')
+    check('编号', p['seq'], 1)
+    check('编号不是自动的', p['seq_auto'], False)
+    check('状态 = 待标题', p['status'], 'pending')
+
+    print('=== 2. 幂等：同一份内容重传 ===')
+    r2 = vp.upload_video(FakeFile('小王_20260912_1.mp4', b'A' * 500))
+    check('跳过', r2.get('action'), 'skip')
+
+    print('=== 3. 同槽位换内容：先拒收、replace 才行 ===')
+    r3 = vp.upload_video(FakeFile('小王_20260912_1.mp4', b'B' * 600))
+    ok('拒收', r3.get('ok') is False and '已有视频' in (r3.get('error') or ''), r3)
+    r4 = vp.upload_video(FakeFile('小王_20260912_1.mp4', b'B' * 600), replace=True)
+    check('覆盖成功', r4.get('action'), 'replace')
+    check('还是 1 行', models.VideoPlan.query.count(), 1)
+
+    print('=== 4. 不带编号 → 自动排到空位 ===')
+    r5 = vp.upload_video(FakeFile('小王_20260912.mp4', b'C' * 700))
+    check('自动编号 = 2', r5['plan']['seq'], 2)
+    check('标记为自动', r5['plan']['seq_auto'], True)
+
+    print('=== 5. 老格式（手机号）被拒 + 说清怎么改 ===')
+    r6 = vp.upload_video(FakeFile('13382508423_20261011_01.mp4', b'D' * 700))
+    ok('拒收且提示是手机号', r6.get('ok') is False and '手机号' in (r6.get('error') or ''), r6)
+    check('库里还是 2 行', models.VideoPlan.query.count(), 2)
+
+    print('=== 6. 配标题（`标题 || 正文_名字_日期_编号`）===')
+    t1 = vp.import_titles('聚划算 || 今天全场五折，点进来看看_小王_20260912')
+    check('配到 1 条', t1['counts']['attached'], 1)
+    row1 = models.VideoPlan.query.filter_by(nickname='小王', release_date='2026-09-12',
+                                            seq=1).first()
+    check('标题落库', row1.title, '聚划算')
+    check('正文落库', row1.body, '今天全场五折，点进来看看')
+    check('状态自动切到待发布', row1.status, 'ready')
+    check('返回体里键是 name', t1['rows'][0]['name'], '小王')
+
+    t2 = vp.import_titles('第二个 || 正文二_小王_20260912_2')
+    check('按编号精确配对', t2['counts']['attached'], 1)
+    row2 = models.VideoPlan.query.filter_by(nickname='小王', release_date='2026-09-12',
+                                            seq=2).first()
+    check('第 2 条标题', row2.title, '第二个')
+
+    t3 = vp.import_titles('这条没有主_不存在的名字_20260912')
+    check('认不出名字 → 拒收', (t3['counts']['rejected'], t3['rows'][0]['error']),
+          (1, '该名字 2026-09-12 没有待配标题的视频（请先上传视频）'))
+
+    # 带编号重配同一条 → 认出来是"配过了"，跳过（幂等）
+    t4 = vp.import_titles('聚划算 || 今天全场五折，点进来看看_小王_20260912_1')
+    check('带编号重配同一条 → 跳过', t4['counts']['skipped'], 1)
+    # 不带编号：它只会找"还没有标题的行"，两行都配过 → 拒收（既有语义，文案说清了原因）
+    t5 = vp.import_titles('聚划算 || 今天全场五折，点进来看看_小王_20260912')
+    check('不带编号且两行都有标题 → 拒收', (t5['counts']['rejected'], t5['rows'][0]['error']),
+          (1, '该名字 2026-09-12 没有待配标题的视频（请先上传视频）'))
+
+    print('=== 7. 老命名空间不受影响：按名字查重/取槽位 ===')
+    check('taken_slots 按名字', vp.taken_slots('小王', '2026-09-12'), {1, 2})
+    check('别的名字是空的', vp.taken_slots('小李', '2026-09-12'), set())
+
+    print('=== 8. 索引补建 ===')
+    idx = {i['name'] for i in inspect(models.db.engine).get_indexes('video_plan')}
+    ok('ix_video_plan_name_date 已建', 'ix_video_plan_name_date' in idx, sorted(idx))
+
+    print('=== 9. 素材落盘 ===')
+    files = os.listdir(os.path.join(TMP, 'videos', '2026-10'))
+    check('落盘 2 个文件（覆盖后旧文件已删）', len(files), 2)
+
+print()
+shutil.rmtree(TMP, ignore_errors=True)
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（临时库已清理）')
@@ -1,34 +0,0 @@
-@echo off
-chcp 65001 >nul 2>&1
-title 设备自动化后台（局域网模式）
-
-REM ===== 自动提权到管理员 =====
-net session >nul 2>&1
-if %errorlevel% neq 0 (
-    echo 需要管理员权限以支持局域网访问，正在提权...
-    powershell -Command "Start-Process -FilePath '%~f0' -Verb RunAs"
-    exit /b
-)
-
-cd /d "%~dp0"
-
-REM ===== 添加防火墙入站规则（放行 Python，仅一次） =====
-for /f "delims=" %%i in ('where python') do set PY_EXE=%%i
-netsh advfirewall firewall show rule name="PlatformTools Web" >nul 2>&1
-if %errorlevel% neq 0 (
-    echo 正在添加防火墙规则...
-    netsh advfirewall firewall add rule name="PlatformTools Web" dir=in action=allow program="%PY_EXE%" enable=yes >nul 2>&1
-    netsh advfirewall firewall add rule name="PlatformTools Web" dir=out action=allow program="%PY_EXE%" enable=yes >nul 2>&1
-)
-
-echo ============================================
-echo  管理后台已启动（局域网可访问）
-echo  本机访问: http://127.0.0.1:18050/
-echo  局域网访问: http://本机IP:18050/
-echo  默认账号: admin / admin123
-echo  按 Ctrl+C 停止
-echo ============================================
-echo.
-
-python web_server.py
-pause
@@ -0,0 +1,288 @@
+// 管理 Tab：分组/日志/用户
+// ================== Tab 3: 分组 ==================
+async function loadGroups(){
+  const r=await apiGet('/api/groups');if(!r)return;
+  _groupsList=r.groups||[];
+  const dr=await apiGet('/api/devices');
+  // items 带名称（设备身份）；老接口只有 serial 列表时兜底成对象
+  _devicesList=(dr&&dr.items)?dr.items
+    :((dr&&dr.devices)||[]).map(s=>({serial:s,name:'',model:''}));
+  renderGroupTable();
+}
+
+function renderGroupTable(){
+  const groups=_groupsList||[];
+  setListPager('groups',{
+    data:()=>groups,
+    filter:(g,kw)=>((g.name||'').toLowerCase().includes(kw)||(g.description||'').toLowerCase().includes(kw)||(g.serials||[]).join(' ').toLowerCase().includes(kw)),
+    sortValue:(g,k)=>{ if(k==='count')return (g.serials||[]).length; return g[k]||''; },
+    render:renderGroupRow,
+    tbody:'tb-groups',pager:'pager-groups',pageSize:10,
+    empty:'<tr><td colspan="5" class="empty">暂无分组，点击"新建分组"创建</td></tr>'
+  });
+  applyListPager('groups');
+  initListSearch('groups','search-groups');
+}
+function renderGroupRow(g){
+  const serials=g.serials||[];
+  return '<tr>'+
+    '<td><strong>'+esc(g.name)+'</strong></td>'+
+    '<td>'+esc(g.description||'-')+'</td>'+
+    '<td>'+serials.length+'</td>'+
+    '<td class="text-muted" style="max-width:300px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">'+(serials.length?serials.map(esc).join(', '):'-')+'</td>'+
+    '<td>'+
+      (_can('tasks')?(
+        '<button class="btn btn-xs" onclick="openGroupModal(\''+esc(g.name)+'\')">编辑</button>'+
+        '<button class="btn btn-danger btn-xs" onclick="deleteGroup(\''+esc(g.name)+'\')">删除</button>'
+      ):'<span class="text-muted">只读</span>')+
+    '</td>'+
+  '</tr>';
+}
+
+function openGroupModal(name){
+  const group=name?(_groupsList||[]).find(g=>g.name===name):null;
+  const isEdit=!!group;
+  document.getElementById('modal-title').textContent=isEdit?'编辑分组':'新建分组';
+  const g=group||{name:'',description:'',serials:[]};
+  const current= new Set(g.serials||[]);
+  const nameOf={};
+  (_devicesList||[]).forEach(x=>{ if(x&&x.serial) nameOf[x.serial]=x.name||''; });
+  const allSerials=[...new Set([...(_devicesList||[]).map(x=>x.serial||x), ...(g.serials||[])])].sort();
+  const deviceCheckboxes=allSerials.map(s=>
+    '<label><input type="checkbox" value="'+esc(s)+'" '+(current.has(s)?'checked':'')+'>'
+      +esc(nameOf[s]?devText(nameOf[s], s):s)+'</label>'
+  ).join('');
+
+  document.getElementById('modal-body').innerHTML=
+    '<div class="form-group"><label>分组名</label><input type="text" class="form-control" id="g-name" value="'+esc(g.name)+'" placeholder="如：测试组" '+(isEdit?'readonly':'')+'></div>'+
+    '<div class="form-group"><label>描述</label><input type="text" class="form-control" id="g-description" value="'+esc(g.description||'')+'" placeholder="可选"></div>'+
+    '<div class="form-group"><label>设备列表（勾选属于此分组的设备）</label>'+
+      '<div class="device-list">'+(deviceCheckboxes||'<div class="text-muted">暂无在线设备</div>')+'</div>'+
+      '<div class="help">仅显示当前在线设备，已选设备即使离线也会保留</div>'+
+    '</div>';
+
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">取消</button>'+
+    '<button class="btn btn-primary" onclick="saveGroup('+(isEdit?'\''+esc(g.name)+'\'':'null')+')">'+(isEdit?'保存':'创建')+'</button>';
+
+  showModal();
+}
+
+async function saveGroup(name){
+  const newName=document.getElementById('g-name').value.trim();
+  if(!newName){showToast('分组名不能为空','error');return;}
+  const desc=document.getElementById('g-description').value;
+  const serials=Array.from(document.querySelectorAll('.device-list input:checked')).map(c=>c.value);
+  const data={name:newName,description:desc,serials:serials};
+
+  if(name){
+    const r=await apiPut('/api/groups/'+encodeURIComponent(name),data);
+    handleResult(r,()=>{closeModal();loadGroups();});
+  }else{
+    const r=await apiPost('/api/groups',data);
+    handleResult(r,()=>{closeModal();loadGroups();});
+  }
+}
+
+async function deleteGroup(name){
+  if(!confirm('确认删除分组"'+name+'"吗？'))return;
+  const r=await apiDelete('/api/groups/'+encodeURIComponent(name));
+  handleResult(r,()=>loadGroups());
+}
+
+// ================== 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 el=document.getElementById('log-content');
+  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(){
+  if(_logTimer){clearInterval(_logTimer);_logTimer=null;}
+  if(document.getElementById('log-auto').checked && _activeTab==='logs'){
+    _logTimer=setInterval(loadLogs,3000);
+  }
+}
+
+// ================== Tab 5: 用户 ==================
+async function loadUsers(){
+  const r=await apiGet('/api/users');if(!r)return;
+  const users=r.users||[];
+  setListPager('users',{
+    data:()=>users,
+    filter:(u,kw)=>(u.username||'').toLowerCase().includes(kw),
+    sortValue:(u,k)=>{ if(k==='is_admin')return u.is_admin?1:0; return u[k]||''; },
+    render:renderUserRow,
+    tbody:'tb-users',pager:'pager-users',pageSize:10,
+    empty:'<tr><td colspan="5" class="empty">暂无用户</td></tr>'
+  });
+  applyListPager('users');
+  initListSearch('users','search-users');
+}
+function renderUserRow(u){
+  const admin=u.is_admin?'<span class="label label-primary">管理员</span>':'<span class="label label-default">普通</span>';
+  const perms=(u.perms||[]).map(p=>'<span class="label label-info">'+(PERM_LABELS[p]||p)+'</span>').join(' ')
+    ||'<span class="text-muted">-</span>';
+  return '<tr>'+
+    '<td>'+u.id+'</td>'+
+    '<td><strong>'+esc(u.username)+'</strong></td>'+
+    '<td>'+admin+'</td>'+
+    '<td>'+perms+'</td>'+
+    '<td>'+
+      '<button class="btn btn-xs" onclick="openUserModal('+u.id+')">编辑</button>'+
+      (u.username==='admin'?'':'<button class="btn btn-danger btn-xs" onclick="deleteUser('+u.id+')">删除</button>')+
+    '</td>'+
+  '</tr>';
+}
+
+function togglePermBoxes(){
+  // 勾选"管理员权限"时：权限位全选并禁用（管理员拥有全部权限）
+  const isAdmin=document.getElementById('u-is_admin').checked;
+  document.querySelectorAll('.u-perm').forEach(cb=>{
+    cb.disabled=isAdmin;
+    if(isAdmin)cb.checked=true;
+  });
+}
+
+function openUserModal(uid){
+  const isEdit=!!uid;
+  document.getElementById('modal-title').textContent=isEdit?'编辑用户':'新建用户';
+  const permBoxes=Object.keys(PERM_LABELS).map(p=>
+    '<label style="margin-right:12px"><input type="checkbox" class="u-perm" value="'+p+'">'+PERM_LABELS[p]+'</label>'
+  ).join('');
+  document.getElementById('modal-body').innerHTML=
+    '<div class="form-group"><label>用户名</label><input type="text" class="form-control" id="u-username" '+(isEdit?'disabled':'')+' placeholder="用户名"></div>'+
+    '<div class="form-group"><label>密码'+(isEdit?'（留空不修改）':'')+'</label><input type="password" class="form-control" id="u-password" placeholder="密码"></div>'+
+    '<div class="form-group form-check"><input type="checkbox" id="u-is_admin" onchange="togglePermBoxes()" checked><label for="u-is_admin">管理员权限（拥有全部权限）</label></div>'+
+    '<div class="form-group"><label>业务权限（管理员自动拥有全部，无需勾选）</label>'+
+      '<div>'+permBoxes+'</div>'+
+      '<div class="help">任务管理=任务/自定义动作/分组；设备控制=停止/释放/清异常/扫描/抓元素；应用管理=APK上传安装；日志查看=日志页</div>'+
+    '</div>';
+
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">取消</button>'+
+    '<button class="btn btn-primary" onclick="saveUser('+(uid||'null')+')">'+(isEdit?'保存':'创建')+'</button>';
+
+  if(isEdit){
+    // 预填充（从表格数据获取）
+    apiGet('/api/users').then(r=>{
+      const u=(r&&r.users||[]).find(x=>x.id===uid);
+      if(u){
+        document.getElementById('u-username').value=u.username;
+        document.getElementById('u-is_admin').checked=u.is_admin;
+        document.querySelectorAll('.u-perm').forEach(cb=>{
+          cb.checked=(u.perms||[]).includes(cb.value);
+        });
+        togglePermBoxes();
+      }
+    });
+  }else{
+    togglePermBoxes();
+  }
+  showModal();
+}
+
+async function saveUser(uid){
+  const username=document.getElementById('u-username').value.trim();
+  const password=document.getElementById('u-password').value;
+  const is_admin=document.getElementById('u-is_admin').checked;
+  const perms=[...document.querySelectorAll('.u-perm:checked')].map(cb=>cb.value);
+
+  if(uid){
+    const data={is_admin:is_admin,perms:perms};
+    if(password)data.password=password;
+    const r=await apiPut('/api/users/'+uid,data);
+    handleResult(r,()=>{closeModal();loadUsers();});
+  }else{
+    if(!username||!password){showToast('用户名和密码不能为空','error');return;}
+    const r=await apiPost('/api/users',{username:username,password:password,is_admin:is_admin,perms:perms});
+    handleResult(r,()=>{closeModal();loadUsers();});
+  }
+}
+
+async function deleteUser(uid){
+  if(!confirm('确认删除此用户吗？'))return;
+  const r=await apiDelete('/api/users/'+uid);
+  handleResult(r,()=>loadUsers());
+}
+
+
+// ================== 初始化 ==================
+initCsrf();   // 获取 CSRF token（非 GET 请求需携带）
+loadMe();     // 获取当前用户权限，隐藏无权限的功能入口
+showTab('monitor');
@@ -0,0 +1,853 @@
+// AI 控制台（顶级 Tab）：DeepSeek 风格聊天 + 流式输出 + 实时 MCP 步骤
+let _agentBusy = false;
+let _agentStream = null;      // EventSource
+let _agentCfgLoaded = false;
+
+// 后端异常文案兜底：MCP 客户端在工具服务不可达时只抛
+// "Server returned an error response" 这类含糊字样，这里映射成明确指引。
+function _friendlyAgentError(msg){
+  const raw = String(msg || '');
+  const s = raw.replace(/^[A-Za-z_]*Error:\s*/, '');   // 去掉 "RuntimeError: " 之类前缀
+  if(/不可达|连接中断/.test(s)) return s;              // 后端已给出明确文案，直接用
+  if(/mcp_server|server returned an error response|connecterror|connection refused|all connection attempts failed|server disconnected|network is unreachable|connect timeout/i.test(s))
+    return 'MCP server(8033) 不可达：AI 无法连接设备工具服务，请确认 MCP server 已启动（本机可运行 python -m mcp_server.mcp_server）';
+  return raw;
+}
+
+// ================== 初始化 ==================
+let _agentDefaultSerial = '';
+// 目标设备显示文案：名称优先（设备身份），没有名称退地址
+let _agentTargets={};   // serial -> name
+function _agentTargetText(serial){
+  const nm=_agentTargets[serial];
+  return nm ? (nm + ' · ' + serial) : String(serial||'');
+}
+function initAgentChat(){
+  if(_agentCfgLoaded)return;
+  _agentCfgLoaded = true;
+  loadAgentConfig();
+  const chat = document.getElementById('agent-chat');
+  if(chat && !chat.children.length){
+    chat.innerHTML = '<div class="agent-empty">👋 给 AI 下达指令，它将通过截图观察手机并执行操作。<br>'
+      + '例如：「打开抖音搜索奚学东，告诉我第一个视频的标题」<br>'
+      + '先选「🎯 目标设备」（AI 只操作你选定的设备），点击右上角 ⚙ 配置模型与 API Key。</div>';
+  }
+  bindChatScroll();
+  loadLiveDevices();
+  loadAgentTargetDevices();
+  startRunPoll();
+  renderConvList();           // 会话列表（决定当前会话）
+  loadCurrentConvMessages();  // 渲染当前会话历史
+  restoreRunningFlow();       // 若任务运行中：重订阅事件流
+  // 输入框快捷键
+  const inp = document.getElementById('agent-input');
+  inp.addEventListener('keydown', ev=>{
+    if(ev.key==='Enter' && !ev.shiftKey){
+      ev.preventDefault();
+      if(!_agentBusy) sendAgentMsg();
+    }
+  });
+}
+
+// ================== 页面刷新/重进恢复（运行中任务续流） ==================
+// 历史轮次由 loadCurrentConvMessages 从会话渲染；这里只处理「任务仍在后台跑」：
+// 重新订阅事件流（服务端队列保留积压，重连后补发 delta/step/done）。
+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);
+    }else if(r.state === 'error' && r.error && _currentConvId){
+      // 错误提示仅当本会话相关时展示
+      const chat = document.getElementById('agent-chat');
+      if(chat && !chat.children.length){
+        const div = newAssistantMsg();
+        div.querySelector('.agent-text').textContent = '⚠ ' + _friendlyAgentError(r.error);
+      }
+    }
+  });
+}
+
+// ================== 配置 ==================
+function loadAgentConfig(){
+  apiGet('/api/agent/config').then(r=>{
+    if(!r||!r.ok)return;
+    const tag = document.getElementById('agent-model-tag');
+    if(tag && r.model) tag.textContent = r.model;
+    _agentDefaultSerial = r.default_serial || '';
+  });
+}
+
+// ================== 目标设备选择（AI 只操作选定设备） ==================
+function loadAgentTargetDevices(){
+  apiGet('/api/agent/devices').then(r=>{
+    if(!r||!r.ok)return;
+    const sel = document.getElementById('agent-target-select');
+    if(!sel)return;
+    const cur = sel.value;
+    const devs = (r.devices||[]).filter(x=>x.online);
+    _agentTargets = {};
+    devs.forEach(d=>{ if(d.name) _agentTargets[d.serial]=d.name; });
+    sel.innerHTML = '<option value="">请选择设备（AI 只操作选定设备）…</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;
+    else if(_agentDefaultSerial && [...sel.options].some(o=>o.value===_agentDefaultSerial))
+      sel.value = _agentDefaultSerial;
+    const hint = document.getElementById('agent-target-hint');
+    if(hint && sel.value) hint.textContent = '将操作：' + _agentTargetText(sel.value);
+  });
+}
+
+// ================== 跨窗口运行状态（多人/多窗口可见并可停止） ==================
+let _runPoll = null;
+function startRunPoll(){
+  if(_runPoll) return;
+  _runPoll = setInterval(pollRunState, 8000);
+}
+function pollRunState(){
+  if(_agentStream) return;   // 本窗口正在跑（事件流驱动），不轮询
+  apiGet('/api/agent/run').then(r=>{
+    if(!r||!r.ok)return;
+    const running = r.state === 'running';
+    // 运行槽是全平台唯一的：建任务探索在跑时，聊天页也不能再发起（如实显示）
+    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.mode === 'designer' ? '⏳ AI 正在「AI 建任务」页探索设备'
+                                  : '⏳ 运行中' + (r.started ? ' ' + r.started + ' 起' : ''))
+           + dev + '：' + (r.prompt || '').slice(0, 70))
+        : (document.getElementById('agent-target-select').value
+           ? '将操作：' + _agentTargetText(document.getElementById('agent-target-select').value)
+           : '');
+    }
+    document.getElementById('btn-agent-send').disabled = running;
+    // 运行中同步 token（本窗口没订阅事件流时也能看到进度）
+    if(running && !_agentStream && r.usage && r.usage.total_tokens){
+      _liveUsage = r.usage;
+      updateSessionTokens();
+    }
+    if(!running && _agentBusy){ setRunning(false); }   // 流异常丢失时复位
+  });
+}
+function openAgentConfig(){
+  apiGet('/api/agent/config').then(r=>{
+    if(!r||!r.ok)return;
+    document.getElementById('acfg-base').value = r.api_base || 'https://api.deepseek.com';
+    document.getElementById('acfg-model').value = r.model || '';
+    document.getElementById('acfg-serial').value = r.default_serial || '';
+    document.getElementById('acfg-steps').value = r.max_steps || 40;
+    document.getElementById('acfg-key-hint').textContent =
+      r.api_key_masked ? ('已配置 ' + r.api_key_masked) : '未配置';
+    document.getElementById('acfg-key').value = '';
+    document.getElementById('agent-cfg-overlay').style.display = 'flex';
+  });
+}
+function closeAgentConfig(){
+  document.getElementById('agent-cfg-overlay').style.display = 'none';
+}
+function saveAgentConfig(){
+  const body = {
+    api_base: document.getElementById('acfg-base').value.trim(),
+    model: document.getElementById('acfg-model').value.trim(),
+    default_serial: document.getElementById('acfg-serial').value.trim(),
+    max_steps: document.getElementById('acfg-steps').value.trim(),
+  };
+  const key = document.getElementById('acfg-key').value.trim();
+  if(key) body.api_key = key;
+  apiPost('/api/agent/config', body).then(r=>{
+    if(r&&r.ok){
+      showToast('配置已保存','success');
+      closeAgentConfig();
+      loadAgentConfig();
+      loadAgentTargetDevices();
+    }else showToast('保存失败: ' + ((r&&r.error)||''),'error');
+  });
+}
+
+// ================== 聊天渲染 ==================
+function addUserMsg(text){
+  const chat = document.getElementById('agent-chat');
+  clearEmpty();
+  const div = document.createElement('div');
+  div.className = 'agent-msg user';
+  div.textContent = text;
+  chat.appendChild(div);
+  scrollChat();
+}
+function newAssistantMsg(){
+  const chat = document.getElementById('agent-chat');
+  clearEmpty();
+  const div = document.createElement('div');
+  div.className = 'agent-msg assistant';
+  // 结构：工具卡片 → 可折叠推理链 → 正文（Markdown）→ token 用量脚注
+  div.innerHTML =
+      '<div class="agent-toolcards"></div>'
+    + '<details class="reasoning" style="display:none"><summary>💭 思考过程</summary>'
+    +   '<div class="reasoning-text"></div></details>'
+    + '<div class="agent-text"></div>'
+    + '<div class="agent-usage" style="display:none"></div>';
+  chat.appendChild(div);
+  scrollChat();
+  return div;
+}
+
+// ---------- 推理链（可折叠） ----------
+function _appendReasoning(msgEl, text){
+  const box = msgEl.querySelector('.reasoning');
+  if(!box) return;
+  const body = box.querySelector('.reasoning-text');
+  body.textContent += text;
+  box.querySelector('summary').textContent =
+    '💭 思考过程（' + body.textContent.length + ' 字）';
+  box.style.display = 'block';
+  _bindReasoning(box);
+  if(!box.open) box.open = true;      // 流式思考时展开，正文开始时自动收起
+}
+// 用户手动点过 summary 后不再自动收起/展开（尊重手动状态）
+function _bindReasoning(box){
+  const sum = box.querySelector('summary');
+  if(sum && !sum.dataset.bound){
+    sum.dataset.bound = '1';
+    sum.addEventListener('click', ()=>{ box.dataset.touched = '1'; });
+  }
+}
+
+// ---------- 正文 Markdown 渲染（渲染器见 markdown.js） ----------
+function _renderMd(msgEl){
+  const el = msgEl.querySelector('.agent-text');
+  if(el) el.innerHTML = renderMarkdown(msgEl._md || '');
+}
+function _scheduleMd(msgEl){
+  if(msgEl._mdRaf) return;            // 流式增量按帧合并渲染，避免每个 token 重排
+  msgEl._mdRaf = requestAnimationFrame(()=>{
+    msgEl._mdRaf = 0;
+    _renderMd(msgEl);
+    scrollChat();
+  });
+}
+
+// ---------- token 用量 ----------
+let _convUsage = {};    // 当前会话历史累计（读会话时算）
+let _liveUsage = {};    // 本轮运行中累计（SSE usage 事件）
+function _fmtInt(n){ return String(n || 0).replace(/\B(?=(\d{3})+(?!\d))/g, ','); }
+function _usageSum(a, b){
+  const o = {prompt_tokens:0, completion_tokens:0, total_tokens:0, calls:0};
+  [a, b].forEach(u=>{
+    if(!u) return;
+    o.prompt_tokens     += (u.prompt_tokens || 0);
+    o.completion_tokens += (u.completion_tokens || 0);
+    o.total_tokens      += (u.total_tokens || 0);
+    o.calls             += (u.calls || 0);
+  });
+  return o;
+}
+// 单条消息脚注
+function renderUsage(msgEl, u){
+  const el = msgEl.querySelector('.agent-usage');
+  if(!el) return;
+  if(!u || !u.total_tokens){ el.style.display = 'none'; return; }
+  el.style.display = 'block';
+  el.title = '输入 ' + _fmtInt(u.prompt_tokens) + ' + 输出 ' + _fmtInt(u.completion_tokens)
+           + ' = ' + _fmtInt(u.total_tokens) + ' tokens，共 ' + (u.calls || 0) + ' 次模型调用';
+  el.textContent = '🪙 ' + _fmtInt(u.total_tokens) + ' tokens'
+                 + '（↑' + _fmtInt(u.prompt_tokens) + ' ↓' + _fmtInt(u.completion_tokens)
+                 + ' · ' + (u.calls || 0) + ' 次调用）';
+}
+// 顶栏「本会话累计」= 已落库历史 + 运行中本轮
+function updateSessionTokens(){
+  const el = document.getElementById('agent-token-total');
+  if(!el) return;
+  const t = _usageSum(_convUsage, _liveUsage);
+  if(!t.total_tokens){ el.textContent = ''; el.title = ''; return; }
+  el.textContent = '🪙 本会话 ' + _fmtInt(t.total_tokens) + ' tokens';
+  el.title = '本会话累计：输入 ' + _fmtInt(t.prompt_tokens)
+           + ' + 输出 ' + _fmtInt(t.completion_tokens)
+           + ' = ' + _fmtInt(t.total_tokens) + ' tokens，共 ' + t.calls + ' 次模型调用';
+}
+function clearEmpty(){
+  const empty = document.querySelector('#agent-chat .agent-empty');
+  if(empty) empty.remove();
+}
+let _chatPinned = true;   // 用户是否在底部（贴底才自动跟随滚动）
+function scrollChat(force){
+  const chat = document.getElementById('agent-chat');
+  if(force || _chatPinned){
+    chat.scrollTop = chat.scrollHeight;
+  }
+}
+function bindChatScroll(){
+  const chat = document.getElementById('agent-chat');
+  chat.addEventListener('scroll', ()=>{
+    _chatPinned = chat.scrollHeight - chat.scrollTop - chat.clientHeight < 60;
+  });
+}
+function clearAgentChat(){
+  document.getElementById('agent-chat').innerHTML = '';
+  _convUsage = {};    // 换会话：token 累计重新算
+  _liveUsage = {};
+  updateSessionTokens();
+}
+
+// ================== 历史会话（DeepSeek 式：左侧列表，多会话持久化） ==================
+let _currentConvId = localStorage.getItem('agent_conv_id') || '';
+function saveConvId(id){
+  _currentConvId = id || '';
+  if(id) localStorage.setItem('agent_conv_id', id);
+  else localStorage.removeItem('agent_conv_id');
+}
+function createAgentSession(){
+  if(_agentBusy){showToast('运行中不能新建会话','error');return;}
+  apiPost('/api/agent/conversations',{}).then(r=>{
+    if(r&&r.ok){
+      saveConvId(r.id);
+      clearAgentChat();
+      showToast('已新建会话','success');
+      renderConvList();
+    }else showToast('新建失败: '+((r&&r.error)||''),'error');
+  });
+}
+function selectAgentSession(id){
+  if(_agentBusy){showToast('运行中不能切换会话','error');return;}
+  if(id === _currentConvId) return;
+  saveConvId(id);
+  clearAgentChat();
+  loadCurrentConvMessages();
+  renderConvList();
+}
+function deleteAgentSession(id){
+  if(!confirm('删除该会话？历史消息将不可恢复。')) return;
+  apiDelete('/api/agent/conversations/'+id).then(r=>{
+    if(r&&r.ok){
+      if(_currentConvId === id) saveConvId('');
+      showToast('会话已删除','success');
+      renderConvList();
+      loadCurrentConvMessages();
+    }else showToast('删除失败: '+((r&&r.error)||''),'error');
+  });
+}
+function renderConvList(){
+  apiGet('/api/agent/conversations').then(r=>{
+    if(!r||!r.ok)return;
+    const list = document.getElementById('agent-sess-list');
+    if(!list)return;
+    const convs = r.conversations || [];
+    let cur = _currentConvId;
+    if(!convs.some(c=>c.id===cur)) cur = convs.length ? convs[0].id : '';
+    if(cur !== _currentConvId){ saveConvId(cur); clearAgentChat(); loadCurrentConvMessages(); }
+    if(!convs.length){
+      list.innerHTML = '<div class="agent-empty" style="padding:20px 10px;font-size:12px">'
+        + '暂无历史会话<br><br>点「＋ 新建会话」开始</div>';
+      return;
+    }
+    list.innerHTML = convs.map(c=>{
+      const t = c.title || '新会话';
+      const sid = String(c.id || '');
+      return '<div class="agent-sess-item'+(c.id===cur?' active':'')
+        +'" onclick="selectAgentSession(\''+c.id+'\')">'
+        +'<button class="agent-sess-del" title="删除会话" '
+        +'onclick="event.stopPropagation();deleteAgentSession(\''+c.id+'\')">✕</button>'
+        +'<div class="t">'+esc(t)+'</div>'
+        +'<div class="m">'+esc(c.updated_at||'')+(c.count ? ' · '+c.count+' 轮' : '')
+        +' · <span style="font-family:monospace;opacity:.75" title="会话 ID：'+esc(sid)+'（点击复制）" '
+        +'onclick="event.stopPropagation();copyConvId(\''+sid+'\')">#'+esc(sid.slice(0,8))+'</span>'
+        +'</div></div>';
+    }).join('');
+  });
+}
+// 复制会话 ID（便于反馈问题时引用，如 conv=2ba4da0e43）
+function copyConvId(id){
+  const done = ()=>showToast('会话 ID 已复制: '+id,'success');
+  try{
+    if(navigator.clipboard && navigator.clipboard.writeText){
+      navigator.clipboard.writeText(id).then(done).catch(()=>fallback());
+      return;
+    }
+  }catch(e){}
+  fallback();
+  function fallback(){
+    const ta=document.createElement('textarea');
+    ta.value=id; document.body.appendChild(ta); ta.select();
+    try{ document.execCommand('copy'); done(); }catch(e){ showToast('会话 ID: '+id,'success'); }
+    ta.remove();
+  }
+}
+function loadCurrentConvMessages(){
+  const chat = document.getElementById('agent-chat');
+  if(!chat) return;
+  if(!_currentConvId){
+    chat.innerHTML = '<div class="agent-empty">👋 点左侧「＋ 新建会话」开始，'
+      + '给 AI 下达指令（先选 🎯 目标设备）。</div>';
+    return;
+  }
+  apiGet('/api/agent/conversations/'+_currentConvId).then(r=>{
+    if(!r||!r.ok)return;
+    chat.innerHTML = '';
+    _convUsage = {};
+    _liveUsage = {};
+    (r.messages||[]).forEach(m=>{
+      const txt = (m.content||'').trim();
+      if(m.role==='user'){ if(txt) addUserMsg(txt); return; }
+      if(!txt && !m.reasoning && !(m.usage && m.usage.total_tokens)) return;
+      const div = newAssistantMsg();
+      if(txt){ div._md = txt; _renderMd(div); }
+      if(m.reasoning){
+        _appendReasoning(div, m.reasoning);
+        const box = div.querySelector('.reasoning');
+        _bindReasoning(box);
+        box.open = false;                 // 历史消息默认折叠推理链
+      }
+      if(m.usage){
+        renderUsage(div, m.usage);
+        _convUsage = _usageSum(_convUsage, m.usage);
+      }
+    });
+    updateSessionTokens();
+    if(!chat.children.length){
+      chat.innerHTML = '<div class="agent-empty">新会话。给 AI 下达指令'
+        + '（先选 🎯 目标设备）…</div>';
+    }
+  });
+}
+
+// ================== 发送与流式接收 ==================
+function setRunning(on){
+  _agentBusy = on;
+  document.getElementById('agent-running-tag').style.display = on ? 'inline' : 'none';
+  document.getElementById('btn-agent-stop').style.display = on ? 'inline-block' : 'none';
+  document.getElementById('btn-agent-send').disabled = on;
+}
+function stopAgent(){
+  if(!confirm('确定停止当前 AI 运行任务？\n（其他人发起的任务也会被停止）')) return;
+  apiPost('/api/agent/stop',{}).then(r=>{
+    if(r&&r.ok) showToast('已请求停止，正在中断…','success');
+    else showToast((r&&r.error)||'停止失败','error');
+  });
+}
+function sendAgentMsg(){
+  if(_agentBusy){showToast('上一轮还在运行','error');return;}
+  const sel = document.getElementById('agent-target-select');
+  const serial = sel ? sel.value : '';
+  if(!serial){
+    showToast('请先选择目标设备（AI 只操作你选定的设备；任务中的设备不可选）','error');
+    if(sel) sel.focus();
+    return;
+  }
+  const inp = document.getElementById('agent-input');
+  const text = inp.value.trim();
+  if(!text){showToast('请输入指令','error');return;}
+  inp.value = '';
+  addUserMsg(text);
+
+  // 会话：无当前会话时自动新建（DeepSeek 式：消息总归属于一个会话）
+  const doRun = (convId)=>{
+    apiPost('/api/agent/run', {prompt: text, serial: serial,
+                               conversation_id: convId}).then(r=>{
+      if(!r||!r.ok){
+        const msg = r ? (r.error||'启动失败') : '请求失败';
+        const div = newAssistantMsg();
+        div.querySelector('.agent-text').textContent = '⚠ ' + _friendlyAgentError(msg);
+        showToast(_friendlyAgentError(msg),'error');
+        return;
+      }
+      setRunning(true);
+      listenStream(r.run_id);
+    });
+  };
+  if(_currentConvId){
+    doRun(_currentConvId);
+  }else{
+    apiPost('/api/agent/conversations',{}).then(r=>{
+      if(r&&r.ok){
+        saveConvId(r.id);
+        renderConvList();
+        doRun(r.id);
+      }else{
+        const div = newAssistantMsg();
+        div.querySelector('.agent-text').textContent = '⚠ 新建会话失败';
+        showToast('新建会话失败','error');
+      }
+    });
+  }
+}
+
+function listenStream(runId){
+  if(_agentStream) _agentStream.close();
+  const es = new EventSource('/api/agent/stream?run_id=' + runId);
+  _agentStream = es;
+  let msgEl = null;
+
+  es.addEventListener('delta', ev=>{
+    if(!msgEl) msgEl = newAssistantMsg();
+    const d = JSON.parse(ev.data);
+    if(d.kind === 'reasoning'){
+      _appendReasoning(msgEl, d.text || '');
+    }else{
+      // 正文开始 → 收起推理链（用户手动开过的保持原样）
+      const r = msgEl.querySelector('.reasoning');
+      if(r && r.open && !r.dataset.touched) r.open = false;
+      msgEl._md = (msgEl._md || '') + (d.text || '');
+      msgEl._mdPending = false;
+      _scheduleMd(msgEl);
+    }
+    scrollChat();
+  });
+
+  // 每次模型调用完成 → 实时刷新 token 计数（本轮累计）
+  es.addEventListener('usage', ev=>{
+    if(!msgEl) msgEl = newAssistantMsg();
+    let d = {};
+    try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    _liveUsage = d;
+    renderUsage(msgEl, d);
+    updateSessionTokens();
+  });
+
+  es.addEventListener('step', ev=>{
+    const d = JSON.parse(ev.data);
+    followSerialFromArgs(d.args);
+    if(!msgEl) msgEl = newAssistantMsg();
+    const cards = msgEl.querySelector('.agent-toolcards');
+    const card = document.createElement('div');
+    card.className = 'agent-toolcard';
+    const argsTxt = typeof d.args === 'string' ? d.args
+                    : JSON.stringify(d.args || {});
+    card.innerHTML = '<span class="dot"></span>'
+      + '<code style="color:var(--teal)">' + esc(d.tool||'') + '</code>'
+      + '<span class="text-muted">' + esc(argsTxt) + '</span>';
+    if(d.image){
+      const img = document.createElement('img');
+      img.src = 'data:image/jpeg;base64,' + d.image;
+      card.appendChild(img);
+    }
+    cards.appendChild(card);
+    scrollChat();
+  });
+
+  es.addEventListener('done', ev=>{
+    const d = JSON.parse(ev.data);
+    if(d.answer || d.usage || !msgEl){
+      if(!msgEl) msgEl = newAssistantMsg();
+      if(d.answer){ msgEl._md = d.answer; _renderMd(msgEl); }
+      if(d.usage) renderUsage(msgEl, d.usage);
+    }
+    // 本轮用量并入会话累计（脚注已展示，顶栏不该因此变小），再清空「运行中」
+    _convUsage = _usageSum(_convUsage, _liveUsage);
+    _liveUsage = {};
+    updateSessionTokens();
+    scrollChat();
+    endRun();
+    renderConvList();   // 落库已完成：刷新标题/时间/轮数
+  });
+
+  es.addEventListener('error', ev=>{
+    let msg = '连接中断';
+    try{
+      if(ev.data) msg = JSON.parse(ev.data).message || msg;
+    }catch(e){}
+    if(!msgEl) msgEl = newAssistantMsg();
+    msgEl.querySelector('.agent-text').textContent = '⚠ ' + _friendlyAgentError(msg);
+    _liveUsage = {};            // 本轮可能已花费 token，但结果无效——不并入会话累计
+    endRun();
+  });
+
+  es.onerror = ()=>{
+    // 重要：不能在这里 endRun()——断网/后台标签页节流/服务端瞬时抖动都会触发
+    // onerror，但后端任务仍在跑。EventSource 会自动重连，服务端事件队列保留
+    // 积压（delta/step/done），重连成功后全部补发，界面无缝续上。
+    // 只有连接彻底关闭（非自动重连态）且任务还在跑时才提示。
+    if(_agentBusy && es.readyState === EventSource.CLOSED){
+      const hint = document.getElementById('agent-target-hint');
+      if(hint) hint.textContent = '⚠ 实时连接已中断，任务仍在后台运行——可刷新页面恢复查看';
+      // 连接彻底失败时周期探测，恢复后重订阅
+      setTimeout(()=>{
+        if(!_agentStream && _agentBusy){
+          apiGet('/api/agent/run').then(r=>{
+            // 建任务模式（designer）归「AI 建任务」子页订阅，这里同样要让开
+            if(r&&r.ok&&r.state==='running'&&r.run_id&&r.mode!=='designer')
+              listenStream(r.run_id);
+          });
+        }
+      }, 5000);
+    }
+  };
+}
+
+// ============ 实时画面（右侧，MJPEG 流） ============
+let _liveSerial = '';
+function showLive(serial){
+  if(!serial || serial === _liveSerial) return;
+  _liveSerial = serial;
+  const img = document.getElementById('agent-live-img');
+  img.src = '/api/screen/stream?serial=' + encodeURIComponent(serial) + '&q=80&fps=8&t=' + Date.now();
+  img.style.display = 'block';
+  document.getElementById('agent-live-empty').style.display = 'none';
+  document.getElementById('agent-live-serial').textContent = serial;
+  const sel = document.getElementById('agent-live-select');
+  if(sel) sel.value = serial;
+}
+function stopLive(){
+  _liveSerial = '';
+  const img = document.getElementById('agent-live-img');
+  img.src = '';
+  img.style.display = 'none';
+  document.getElementById('agent-live-empty').style.display = 'block';
+  document.getElementById('agent-live-serial').textContent = '';
+}
+function followSerialFromArgs(args){
+  // 工具 args（后端 SSE 已序列化为对象；兼容历史字符串格式）
+  let a = args;
+  if(typeof args === 'string'){
+    try{ a = JSON.parse(args); }catch(e){ return; }
+  }
+  if(a && a.serial) showLive(a.serial);
+}
+function watchDevice(serial){
+  if(!serial){ stopLive(); return; }
+  showLive(serial);
+}
+function loadLiveDevices(){
+  apiGet('/api/devices').then(r=>{
+    if(!r||!r.ok)return;
+    const sel = document.getElementById('agent-live-select');
+    if(!sel)return;
+    const cur = sel.value;
+    // items 带设备名称（设备身份）；老接口只有 serial 列表时兜底
+    const items = (r.items && r.items.length ? r.items
+                   : (r.devices||[]).map(x=>({serial:x, name:''})))
+                  .filter(x=>String(x.serial||'').indexOf(':')>=0);
+    sel.innerHTML = '<option value="">选择设备观看…</option>'
+      + items.map(x=>'<option value="'+esc(x.serial)+'"'+(x.serial===cur?' selected':'')+'>'
+                     +esc(devText(x.name, x.serial))+'</option>').join('');
+  });
+}
+
+// 截图点击放大查看
+function zoomScreenshot(img){
+  const ov = document.getElementById('agent-zoom');
+  if(!ov){
+    const d = document.createElement('div');
+    d.id = 'agent-zoom';
+    d.style.cssText = 'display:none;position:fixed;inset:0;background:rgba(0,0,0,.8);z-index:1400;align-items:center;justify-content:center;cursor:zoom-out';
+    d.onclick = ()=>d.style.display='none';
+    document.body.appendChild(d);
+  }
+  const ovEl = document.getElementById('agent-zoom');
+  ovEl.innerHTML = '';
+  const big = document.createElement('img');
+  big.src = img.src;
+  big.style.cssText = 'max-width:88vw;max-height:88vh;border-radius:8px';
+  ovEl.appendChild(big);
+  ovEl.style.display = 'flex';
+}
+// 截图 img 绑定点击放大
+document.addEventListener('click', ev=>{
+  const t = ev.target;
+  if(t && t.tagName==='IMG' && t.closest('.agent-toolcard') && !t.closest('#agent-zoom')){
+    zoomScreenshot(t);
+  }
+});
+
+function endRun(){
+  setRunning(false);
+  _agentStream && _agentStream.close();
+  _agentStream = null;
+  scrollChat();
+}
+
+// ================== 动作库（可复用动作：查看/编辑/删除/新建） ==================
+let _actCache = [];
+function openActLib(){
+  document.getElementById('agent-act-overlay').style.display = 'flex';
+  loadActLib();
+}
+function closeActLib(){
+  document.getElementById('agent-act-overlay').style.display = 'none';
+}
+function _actStepBrief(a){
+  return (a.steps||[]).map(s=>{
+    const p = s.params || {};
+    const loc = p.selector_value || p.package || p.fixed_text || '';
+    return (s.type || '?') + (loc ? (':' + loc) : '');
+  }).join(' → ');
+}
+function loadActLib(){
+  const list = document.getElementById('act-lib-list');
+  apiGet('/api/agent/actions').then(r=>{
+    if(!r||!r.ok){ showToast((r&&r.error)||'加载失败','error'); return; }
+    _actCache = r.actions || [];
+    document.getElementById('act-lib-hint').textContent = '共 ' + _actCache.length + ' 个动作';
+    if(!_actCache.length){
+      list.innerHTML = '<div class="text-muted" style="padding:20px;text-align:center">暂无动作——跑一轮以元素/文字点击为主的任务后会自动沉淀</div>';
+      return;
+    }
+    list.innerHTML = '';
+    _actCache.forEach(a=>{
+      const card = document.createElement('div');
+      card.style.cssText = 'border:1px solid var(--card-line);border-radius:10px;padding:9px 13px;background:#0d1117';
+      card.innerHTML = '<div style="display:flex;justify-content:space-between;gap:10px;align-items:flex-start">'
+        + '<div style="flex:1;min-width:0">'
+        +   '<div style="font-weight:600">' + esc(a.name||'')
+        +     (a.app ? '<span class="text-muted" style="font-size:11px;font-weight:400;margin-left:6px">' + esc(a.app) + '</span>' : '')
+        +   '</div>'
+        +   '<div style="font-size:11.5px;color:#9fb3d1;margin-top:2px;word-break:break-all">' + esc(_actStepBrief(a) || '—') + '</div>'
+        +   '<div class="text-muted" style="font-size:11px;margin-top:2px">别名: ' + esc((a.aliases||[]).join('、')||'—')
+        +     ' ｜ 命中 ' + (a.hits||0) + ' 次 ｜ ' + esc(a.updated_at||'') + '</div>'
+        + '</div>'
+        + '<div style="display:flex;flex-direction:column;gap:4px;flex:none">'
+        +   '<button class="btn btn-xs" onclick="actEdit(' + a.id + ')">编辑</button>'
+        +   '<button class="btn btn-xs btn-danger" onclick="actDelete(' + a.id + ')">删除</button>'
+        + '</div></div>';
+      list.appendChild(card);
+    });
+  });
+}
+function actDelete(id){
+  if(!confirm('确认删除该动作？删除后同类任务不再自动复用它。')) return;
+  apiPost('/api/agent/actions/delete',{id:id}).then(r=>{
+    showToast((r&&(r.msg||r.error))||'删除失败', (r&&r.ok)?'success':'error');
+    loadActLib();
+  });
+}
+function actNew(){ _actForm({name:'', app:'', aliases:[], params:[], steps:[]}); }
+function actEdit(id){
+  const a = _actCache.find(x=>x.id===id);
+  if(a) _actForm(a);
+}
+function _actForm(a){
+  const list = document.getElementById('act-lib-list');
+  const isNew = !a.id;
+  list.innerHTML = '';
+  const box = document.createElement('div');
+  box.style.cssText = 'border:1px solid var(--card-line);border-radius:10px;padding:12px 14px;background:#0d1117';
+  box.innerHTML =
+      '<div style="font-weight:600;margin-bottom:8px">' + (isNew?'新建动作':'编辑动作 #'+a.id) + '</div>'
+    + '<div style="display:flex;gap:8px;flex-wrap:wrap;margin-bottom:6px">'
+    +   '<input id="act-f-name" class="form-control" style="flex:1;min-width:180px" placeholder="动作名（如 打开抖音）" value="' + esc(a.name||'') + '">'
+    +   '<input id="act-f-app" class="form-control" style="flex:1;min-width:180px" placeholder="包名（可空，如 com.ss.android.ugc.aweme）" value="' + esc(a.app||'') + '">'
+    + '</div>'
+    + '<div style="display:flex;gap:8px;flex-wrap:wrap;margin-bottom:6px">'
+    +   '<input id="act-f-alias" class="form-control" style="flex:1;min-width:180px" placeholder="别名（逗号分隔）" value="' + esc((a.aliases||[]).join(',')) + '">'
+    +   '<input id="act-f-params" class="form-control" style="flex:1;min-width:180px" placeholder="参数名（逗号分隔，可空）" value="' + esc((a.params||[]).join(',')) + '">'
+    + '</div>'
+    + '<textarea id="act-f-steps" class="form-control" rows="9" style="font-family:monospace;font-size:12px" '
+    +   'placeholder=\'步骤 JSON 数组，例：[{"type":"click","params":{"selector_type":"text","selector_value":"搜索"}}]\'>'
+    +   esc(JSON.stringify(a.steps||[], null, 2)) + '</textarea>'
+    + '<div class="text-muted" style="font-size:11px;margin:6px 0">可用 type：open_app/click/input_text/swipe/wait/key_event/group…；click 必须有 selector_value（xpath/text/resourceId/description…）；<b>不接受坐标(click_xy)</b>。</div>'
+    + '<div style="display:flex;gap:8px"><button class="btn btn-primary btn-sm" onclick="actSave(' + (a.id||0) + ')">保存</button>'
+    + '<button class="btn btn-sm" onclick="loadActLib()">取消</button></div>';
+  list.appendChild(box);
+}
+function actSave(id){
+  const g = (i)=>document.getElementById(i).value;
+  const split = (s)=>String(s||'').split(/[,，]/).map(x=>x.trim()).filter(x=>x);
+  let steps;
+  try{ steps = JSON.parse(g('act-f-steps')||'[]'); }
+  catch(e){ showToast('steps 不是合法 JSON: '+e.message,'error'); return; }
+  apiPost('/api/agent/actions/save', {
+    id: id||0, name: g('act-f-name'), app: g('act-f-app'),
+    aliases: split(g('act-f-alias')), params: split(g('act-f-params')), steps: steps
+  }).then(r=>{
+    if(!r||!r.ok){ showToast((r&&r.error)||'保存失败','error'); return; }
+    showToast(r.msg||'已保存','success');
+    loadActLib();
+  });
+}
+
+// ================== 经验库（自进化记忆管理） ==================
+function openExpLib(){
+  document.getElementById('agent-exp-overlay').style.display = 'flex';
+  loadExpLib();
+}
+function closeExpLib(){
+  document.getElementById('agent-exp-overlay').style.display = 'none';
+}
+function loadExpLib(){
+  const list = document.getElementById('exp-lib-list');
+  apiGet('/api/agent/experience').then(r=>{
+    if(!r||!r.ok){ showToast((r&&r.error)||'加载失败','error'); return; }
+    document.getElementById('exp-lib-last').textContent =
+      (r.last ? ('最近巡检 ' + r.last + '：' + (r.last_summary||'')) : '');
+    if(r.running){
+      list.innerHTML = '<div class="text-muted" style="padding:20px;text-align:center">🔍 AI 巡检进行中（约 1 分钟），完成后请刷新…</div>';
+      return;
+    }
+    const exps = r.experiences||[];
+    if(!exps.length){
+      list.innerHTML = '<div class="text-muted" style="padding:20px;text-align:center">暂无经验——跑一轮带手机操作的任务后会自动沉淀</div>';
+      return;
+    }
+    list.innerHTML = '';
+    exps.forEach(e=>{
+      const a = e.audit||{};
+      const card = document.createElement('div');
+      card.style.cssText = 'border:1px solid var(--card-line);border-radius:10px;padding:9px 13px;background:#0d1117';
+      // 徽章
+      let badge = '';
+      if(a.action === 'pending' && a.verdict === 'delete'){
+        badge = '<span style="background:#7f1d1d;color:#fecaca;font-size:10.5px;padding:1px 8px;border-radius:9px;margin-left:8px">⚠ 建议删除</span>';
+      }else if(a.action === 'kept'){
+        badge = '<span style="background:#0f3d2e;color:#a7f3d0;font-size:10.5px;padding:1px 8px;border-radius:9px;margin-left:8px">' +
+                (a.verdict === 'delete' ? '已人工保留' : '✓ 已保留') + '</span>';
+      }
+      let actBtns = '';
+      if(a.action === 'pending'){
+        actBtns = '<button class="btn btn-xs btn-danger" onclick="expDelete(' + e.id + ')">确认删除</button>'
+                + '<button class="btn btn-xs" onclick="expKeep(' + e.id + ')">保留</button>';
+      }else{
+        actBtns = '<button class="btn btn-xs" style="border-color:#7f1d1d;color:#f87171" onclick="expDelete(' + e.id + ')" title="强制删除此经验">删除</button>';
+      }
+      card.innerHTML =
+        '<div style="display:flex;align-items:center;gap:6px;font-size:12px">'
+        + '<span class="text-muted" style="font-family:var(--mono)">#' + e.id + '</span>'
+        + '<span class="text-muted">' + esc(e.created_at||'') + '</span>'
+        + '<span class="text-muted">引用 ' + (e.hits||0) + ' 次</span>' + badge
+        + '<span style="flex:1"></span>' + actBtns + '</div>'
+        + '<div style="font-size:13px;color:#e5e7eb;margin:5px 0 3px">' + esc(e.task_prompt) + '</div>'
+        + '<div class="text-muted" style="font-size:11.5px;line-height:1.6;white-space:pre-wrap">' + esc((e.recipe||'').slice(0,220)) + '</div>'
+        + (a.action === 'pending' && a.reason
+           ? '<div style="font-size:11.5px;color:#fbbf24;margin-top:5px">AI 建议理由：' + esc(a.reason)
+             + (a.score ? '（评分 ' + a.score + '/10）' : '') + '</div>'
+           : '');
+      list.appendChild(card);
+    });
+  });
+}
+function triggerExpAudit(){
+  apiPost('/api/agent/experience/audit',{}).then(r=>{
+    if(r&&r.ok){
+      showToast('巡检已启动，约 1 分钟完成','success');
+      document.getElementById('exp-lib-list').innerHTML =
+        '<div class="text-muted" style="padding:20px;text-align:center">🔍 AI 巡检进行中…</div>';
+      // 完成后自动刷新
+      setTimeout(()=>{ if(document.getElementById('agent-exp-overlay').style.display==='flex') loadExpLib(); }, 90000);
+    }else showToast((r&&r.error)||'巡检启动失败','error');
+  });
+}
+function expDelete(id){
+  if(!confirm('确认删除该经验？删除后不可恢复（下次相似任务不再自动参考）。')) return;
+  apiPost('/api/agent/experience/delete',{id:id}).then(r=>{
+    if(r&&r.ok){ showToast('已删除','success'); loadExpLib(); }
+    else showToast((r&&r.error)||'删除失败','error');
+  });
+}
+function expKeep(id){
+  apiPost('/api/agent/experience/keep',{id:id}).then(r=>{
+    if(r&&r.ok){ showToast('已保留，后续不再重复建议','success'); loadExpLib(); }
+    else showToast((r&&r.error)||'操作失败','error');
+  });
+}
@@ -0,0 +1,359 @@
+// 工具 Tab-应用管理：APK 上传/安装/删除 + 设备已装应用
+// ================== Tab: 应用 ==================
+let _apksCache=[];
+let _installTimer=null;
+let _devAppsData=[];
+
+function fmtSize(b){
+  if(!b)return '0 B';
+  if(b<1024)return b+' B';
+  if(b<1048576)return (b/1024).toFixed(1)+' KB';
+  return (b/1048576).toFixed(1)+' MB';
+}
+
+async function loadApks(){
+  const r=await apiGet('/api/apks');if(!r||!r.ok)return;
+  const apks=r.apks||[];
+  _apksCache=apks;
+  document.getElementById('apk-hint').textContent='共 '+apks.length+' 个应用';
+  setListPager('apks',{
+    data:()=>apks,
+    sortValue:(a,k)=>{ if(k==='size')return a.size||0; if(k==='upload_time')return a.upload_time||''; if(k==='package_name')return a.package_name||''; if(k==='version_name')return a.version_name||''; return a.display_name||''; },
+    filter:(a,kw)=>((a.display_name||'').toLowerCase().includes(kw)||(a.package_name||'').toLowerCase().includes(kw)),
+    render:renderApkRow,
+    tbody:'tb-apks',pager:'pager-apks',pageSize:10,
+    empty:'<tr><td colspan="6" class="empty">暂无APK，点击"上传APK"上传</td></tr>'
+  });
+  applyListPager('apks');
+  initListSearch('apks','search-apks');
+  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 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> '+
+      clean+
+      '<button class="btn btn-danger btn-xs" onclick="deleteApk(\''+a.id+'\','+n+')">删除</button>'+
+    '</td>'+
+  '</tr>';
+}
+
+// 填充"设备已装应用"的设备下拉（保留当前选择）
+async function fillAppsDeviceList(){
+  const sr=await apiGet('/api/status');if(!sr||!sr.ok)return;
+  const sel=document.getElementById('apps-device');
+  if(!sel)return;
+  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(devText(d.device_name||d.name, d.serial))+'</option>'
+  ).join('');
+  if(cur)sel.value=cur;
+}
+
+// 查看指定设备已安装应用
+async function loadDeviceApps(){
+  const sel=document.getElementById('apps-device');
+  const serial=sel.value;
+  if(!serial){showToast('请先选择设备','error');return;}
+  const hint=document.getElementById('apps-hint');
+  const tb=document.getElementById('tb-device-apps');
+  hint.textContent='加载中...';
+  const r=await apiGet('/api/devices/'+encodeURIComponent(serial)+'/apps');
+  hint.textContent='';
+  if(!r||!r.ok){
+    tb.innerHTML='<tr><td colspan="4" class="empty">'+(r&&r.error?esc(r.error):'获取失败')+'</td></tr>';
+    showToast('获取失败','error');return;
+  }
+  const apps=r.apps||[];
+  if(!apps.length){tb.innerHTML='<tr><td colspan="4" class="empty">无应用</td></tr>';return;}
+  const userApps=apps.filter(a=>/^\/data\//.test(a.path||'')).length;
+  hint.textContent='共 '+apps.length+' 个应用（用户安装 '+userApps+'）';
+  _devAppsData=apps;
+  setListPager('devapps',{
+    data:()=>_devAppsData||[],
+    filter:(a,kw)=>((a.label||a.package||'').toLowerCase().includes(kw)||(a.package||'').toLowerCase().includes(kw)||(a.path||'').toLowerCase().includes(kw)),
+    sortValue:(a,k)=>{ if(k==='version_code')return parseInt(a.version_code)||0; if(k==='version_name')return a.version_name||''; if(k==='label')return (a.label||a.package||''); return a[k]||''; },
+    render:renderDevAppRow,
+    tbody:'tb-device-apps',pager:'pager-devapps',pageSize:20,
+    empty:'<tr><td colspan="4" class="empty">无应用</td></tr>'
+  });
+  applyListPager('devapps');
+  initListSearch('devapps','search-devapps');
+}
+function renderDevAppRow(a){
+  return '<tr>'+
+    '<td><strong>'+esc(a.label||a.package)+'</strong>'+(a.label?' <span style="font-size:11px;color:#94a3b8;font-family:monospace">'+esc(a.package)+'</span>':'')+'</td>'+
+    '<td>'+(a.version_name?esc(a.version_name):'-')+'</td>'+
+    '<td style="font-size:12px;color:#94a3b8">'+(a.version_code!=null?esc(a.version_code):'-')+'</td>'+
+    '<td style="font-size:11px;color:#94a3b8;word-break:break-all">'+esc(a.path||'-')+'</td>'+
+  '</tr>';
+}
+
+async function uploadApk(input){
+  if(!input.files||!input.files[0])return;
+  const file=input.files[0];
+  if(!file.name.toLowerCase().endsWith('.apk')){
+    showToast('请选择 .apk 文件','error');return;
+  }
+  const hint=document.getElementById('apk-hint');
+  const fd=new FormData();
+  fd.append('file',file);
+  // 用 XMLHttpRequest 才能拿到上传进度（fetch 不支持上传进度事件）
+  const xhr=new XMLHttpRequest();
+  xhr.open('POST','/api/apks/upload');
+  if(_csrfToken)xhr.setRequestHeader('X-CSRF-Token',_csrfToken);
+  xhr.upload.onprogress=function(e){
+    if(e.lengthComputable){
+      const pct=Math.round(e.loaded*100/e.total);
+      const loaded=(e.loaded/1048576).toFixed(1);
+      const total=(e.total/1048576).toFixed(1);
+      hint.innerHTML='<span style="color:#f59e0b">正在上传 '+esc(file.name)+' '+pct+'% ('+loaded+'/'+total+' MB)</span>'+
+        '<div class="progress" style="width:200px;height:6px;margin-top:4px"><div class="progress-bar" style="width:'+pct+'%"></div></div>';
+    }
+  };
+  xhr.onload=function(){
+    if(xhr.status===401){window.location='/login';return;}
+    try{
+      const data=JSON.parse(xhr.responseText);
+      if(data.ok){
+        showToast(data.msg||'上传成功','success');
+        loadApks();
+      }else{
+        showToast(data.error||'上传失败','error');
+        hint.textContent='';
+      }
+    }catch(e){
+      showToast('解析响应失败','error');
+      hint.textContent='';
+    }
+  };
+  xhr.onerror=function(){
+    showToast('上传失败：网络错误','error');
+    hint.textContent='';
+  };
+  xhr.send(fd);
+  input.value='';
+}
+
+async function deleteApk(id, versionCount){
+  const n=versionCount||1;
+  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);
+}
+
+async function openInstallModal(apkId){
+  const apk=_apksCache.find(a=>a.id===apkId);
+  const apkName=apk?(apk.display_name||'APK'):'APK';
+  const r=await apiGet('/api/apks/install/devices');
+  const online=(r&&r.ok)?(r.devices||[]):[];
+  if(!online.length){
+    showToast('没有可用设备（设备池或本机 adb 均无）','error');return;
+  }
+  const body=
+    '<div style="margin-bottom:12px">'+
+      '<strong>安装应用：</strong><span class="label label-primary">'+esc(apkName)+'</span>'+
+      ' <span style="font-size:12px;color:#94a3b8">运行中设备将自动跳过</span>'+
+    '</div>'+
+    '<div style="margin-bottom:8px">'+
+      '<button class="btn btn-sm" onclick="document.querySelectorAll(\'#install-dev-list input[type=checkbox]\').forEach(c=>c.checked=true)">全选</button> '+
+      '<button class="btn btn-sm" onclick="document.querySelectorAll(\'#install-dev-list input[type=checkbox]\').forEach(c=>c.checked=false)">全不选</button> '+
+      '<button class="btn btn-sm btn-primary" onclick="selectIdleForInstall()">全选空闲</button>'+
+    '</div>'+
+    '<div id="install-dev-list" class="device-list">'+
+      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>';
+        // 一律「名称 · 地址」——同型号多台时靠名称区分；没有名称的设备（不在池里）只显示地址
+        const label=devText(d.name, d.serial);
+        return '<label><input type="checkbox" value="'+esc(d.serial)+'" checked>'+esc(label)+st+'</label>';
+      }).join('')+
+    '</div>';
+
+  document.getElementById('modal-title').textContent='安装应用到设备';
+  document.getElementById('modal-body').innerHTML=body;
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">取消</button>'+
+    '<button class="btn btn-primary" onclick="startInstall(\''+apkId+'\')">开始安装</button>';
+  document.getElementById('modal-overlay').classList.add('show');
+}
+
+function selectIdleForInstall(){
+  document.querySelectorAll('#install-dev-list label').forEach(lbl=>{
+    const cb=lbl.querySelector('input[type=checkbox]');
+    const isRunning=lbl.querySelector('.label-success');
+    cb.checked=!isRunning;
+  });
+}
+
+async function startInstall(apkId){
+  const checked=document.querySelectorAll('#install-dev-list input[type=checkbox]:checked');
+  const serials=Array.from(checked).map(c=>c.value);
+  if(!serials.length){
+    showToast('请至少选择一台设备','error');return;
+  }
+  const r=await apiPost('/api/apks/install',{apk_id:apkId,serials:serials});
+  if(!r||!r.ok){showToast(r?r.error:'请求失败','error');return;}
+  showToast(r.msg||'安装已启动','success');
+  showInstallProgress();
+}
+
+function showInstallProgress(){
+  document.getElementById('modal-title').textContent='安装进度';
+  document.getElementById('modal-body').innerHTML=
+    '<div id="install-progress" style="min-height:200px"><p class="text-muted">加载中...</p></div>';
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeInstallModal()" id="install-close-btn" style="display:none">关闭</button>';
+  pollInstallStatus();
+  if(_installTimer)clearInterval(_installTimer);
+  _installTimer=setInterval(pollInstallStatus,1500);
+}
+
+async function pollInstallStatus(){
+  const r=await apiGet('/api/apks/install/status');
+  if(!r||!r.ok)return;
+  const st=r.status;
+  if(!st){
+    document.getElementById('install-progress').innerHTML='<p class="text-muted">无安装任务</p>';
+    if(_installTimer){clearInterval(_installTimer);_installTimer=null;}
+    return;
+  }
+  const SS={pending:{t:'等待',c:'default'},installing:{t:'安装中',c:'warning'},success:{t:'成功',c:'success'},failed:{t:'失败',c:'danger'},skipped:{t:'跳过',c:'default'}};
+  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||'')+bar+'</td></tr>';
+  }).join('');
+
+  const pct=st.total>0?Math.round((st.success+st.failed+st.skipped)*100/st.total):0;
+  const summary=
+    '<div style="margin-bottom:12px">'+
+      '<div style="display:flex;gap:8px;margin-bottom:8px;font-size:13px;flex-wrap:wrap">'+
+        '<span>应用：<strong>'+esc(st.apk_name)+'</strong></span>'+
+        '<span class="label label-success">成功 '+st.success+'</span>'+
+        '<span class="label label-danger">失败 '+st.failed+'</span>'+
+        '<span class="label label-default">跳过 '+st.skipped+'</span>'+
+        '<span class="label label-warning">安装中 '+st.installing+'</span>'+
+        '<span class="label label-default">等待 '+st.pending+'</span>'+
+      '</div>'+
+      '<div class="progress" style="width:100%;height:8px"><div class="progress-bar" style="width:'+pct+'%"></div></div>'+
+    '</div>';
+
+  document.getElementById('install-progress').innerHTML=
+    summary+'<table class="table" style="margin-bottom:0"><thead><tr><th>设备</th><th>Serial</th><th>状态</th><th>详情</th></tr></thead><tbody>'+itemRows+'</tbody></table>';
+
+  if(st.finished){
+    if(_installTimer){clearInterval(_installTimer);_installTimer=null;}
+    document.getElementById('install-close-btn').style.display='';
+    showToast('安装完成：成功'+st.success+' 失败'+st.failed+' 跳过'+st.skipped,'success');
+  }
+}
+
+function closeInstallModal(){
+  if(_installTimer){clearInterval(_installTimer);_installTimer=null;}
+  closeModal();
+}
+
+
+
+// ================== 设备端应用商店（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;}
@@ -0,0 +1,203 @@
+// 通用基础：esc/CSRF/权限/API/Toast、Tab 切换与页内子分栏、模态框、行内按钮操作
+// ================== 通用工具 ==================
+const ACTION_LABELS={like:'点赞',comment:'评论',follow:'关注',share:'分享'};
+const STATUS_MAP={idle:{t:'未启动',c:'default'},connecting:{t:'连接中',c:'warning'},running:{t:'运行中',c:'success'},done:{t:'完成',c:'primary'},error:{t:'异常',c:'danger'},released:{t:'已释放',c:'default'},failed:{t:'失败',c:'danger'}};
+const TARGET_MAP={all:'全部空闲',group:'按分组',serial:'指定设备'};
+
+// 设备显示文案：**名称是设备身份**，地址只是当前连接位置。
+// 有名称 → 「名称 · serial」；没名称（历史数据）→ 只显示 serial
+function devText(name, serial){
+  const n=String(name||'').trim();
+  return n ? (n + ' · ' + serial) : String(serial||'');
+}
+const APP_NAMES={'com.ss.android.ugc.aweme':'抖音','com.ss.android.ugc.aweme.lite':'抖音极速版','com.smile.gifmaker':'快手','com.kuaishou.nebula':'快手极速版','com.tencent.mm':'微信','com.tencent.mobileqq':'QQ','com.tencent.qqlive':'腾讯视频','com.eg.android.AlipayGphone':'支付宝','com.taobao.taobao':'淘宝','com.tmall.wireless':'天猫','com.jingdong.app.mall':'京东','com.xunmeng.pinduoduo':'拼多多','com.ss.android.article.news':'今日头条','com.zhihu.android':'知乎','com.miui.home':'桌面','com.android.launcher':'桌面','com.android.settings':'设置','com.android.systemui':'系统','com.github.uiautomator':'U2','com.github.uiautomator.test':'U2测试'};
+
+function esc(s){return String(s||'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));}
+
+// ===== CSRF =====
+let _csrfToken='';
+// 页面加载后调用：获取 CSRF token，非 GET 请求需携带
+async function initCsrf(){
+  try{
+    const r=await fetch('/api/csrf');
+    const d=await r.json();
+    _csrfToken=d.token||'';
+  }catch(e){}
+}
+function _csrfHeaders(){
+  return _csrfToken?{'X-CSRF-Token':_csrfToken}:{};
+}
+
+// ===== 当前用户与权限 =====
+// _me 来自 /api/me：{username, is_admin, perms:[tasks/devices/apks/logs]}
+// 管理员 perms 恒为全部。无权限的功能入口（tab/按钮）用 data-perm 标记或 _can() 判断隐藏。
+let _me={is_admin:false,perms:[],username:''};
+async function loadMe(){
+  try{
+    const r=await apiGet('/api/me');
+    if(r&&r.ok)_me=r.user||{is_admin:false,perms:[],username:''};
+    const un=document.getElementById('me-username');
+    if(un)un.textContent=_me.username||'';
+    // 隐藏无权限的 tab 和按钮（data-perm="admin" 表示仅管理员）
+    document.querySelectorAll('[data-perm]').forEach(function(el){
+      const p=el.dataset.perm;
+      const ok=(p==='admin')?_me.is_admin:(_me.perms||[]).includes(p);
+      if(!ok)el.style.display='none';
+    });
+  }catch(e){}
+}
+function _can(perm){
+  return _me.is_admin||(_me.perms||[]).includes(perm);
+}
+const PERM_LABELS={tasks:'任务管理',devices:'设备控制',apks:'应用管理',logs:'日志查看'};
+
+async function apiGet(url){
+  const r=await fetch(url);
+  if(r.status===401){window.location='/login';return null;}
+  return r.json();
+}
+async function apiPost(url,body){
+  const r=await fetch(url,{method:'POST',headers:{'Content-Type':'application/json',..._csrfHeaders()},body:body?JSON.stringify(body):'{}'});
+  if(r.status===401){window.location='/login';return null;}
+  return r.json();
+}
+async function apiPut(url,body){
+  const r=await fetch(url,{method:'PUT',headers:{'Content-Type':'application/json',..._csrfHeaders()},body:body?JSON.stringify(body):'{}'});
+  if(r.status===401){window.location='/login';return null;}
+  return r.json();
+}
+
+async function apiDelete(url){
+  const r=await fetch(url,{method:'DELETE',headers:_csrfHeaders()});
+  if(r.status===401){window.location='/login';return null;}
+  return r.json();
+}
+
+function showToast(msg,type){
+  const t=document.getElementById('toast');
+  t.className='toast show toast-'+(type||'success');
+  t.textContent=msg;
+  setTimeout(()=>t.className='toast',3000);
+}
+function handleResult(r,callback){
+  if(!r)return;
+  if(r.ok){showToast(r.msg||'操作成功','success');if(callback)callback();}
+  else{showToast(r.error||'操作失败','error');}
+}
+
+// ================== Tab 切换 ==================
+let _activeTab='monitor';
+let _monitorTimer=null;
+let _logTimer=null;
+
+function showTab(name){
+  _activeTab=name;
+  document.querySelectorAll('.tab-panel').forEach(p=>p.classList.remove('active'));
+  document.querySelectorAll('.navbar .tab').forEach(t=>t.classList.remove('active'));
+  const panel=document.getElementById('tab-'+name);
+  if(panel)panel.classList.add('active');
+  const btn=document.querySelector('.navbar .tab[data-tab="'+name+'"]');
+  if(btn)btn.classList.add('active');
+  // 停止所有定时器
+  if(_monitorTimer){clearInterval(_monitorTimer);_monitorTimer=null;}
+  if(_logTimer){clearInterval(_logTimer);_logTimer=null;}
+  if(_discoveryTimer){clearInterval(_discoveryTimer);_discoveryTimer=null;}
+  if(typeof _rpTimer!=='undefined'&&_rpTimer){clearInterval(_rpTimer);_rpTimer=null;}
+  // 按需加载数据
+  if(name==='monitor'){loadMonitor();_monitorTimer=setInterval(loadMonitor,5000);}
+  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'){
+    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==='plan'){
+    if(typeof loadReleasePlan==='function')loadReleasePlan();
+    if(typeof loadReleaseTasks==='function')loadReleaseTasks();
+  }
+  if(name==='users')loadUsers();
+  if(name==='system'){showSubTab('system',_activeSubs.system||'backup');}
+}
+
+// ================== 页内子分栏（任务/工具 通用） ==================
+// 每个带子分栏的 Tab 记住上次选中的子分栏，切走再切回来保持原位
+let _activeSubs = {tasks: 'plan', tools: 'clipboard', system: 'backup', agent: 'chat',
+                   logs: 'files'};
+let _discoveryTimer = null;   // 设备自动发现 10s 轮询（仅 devpool 子分栏激活时）
+
+function showSubTab(tabId, name){
+  _activeSubs[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(tabId==='tasks' && name==='dedup' && typeof loadDedup==='function') loadDedup();
+  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'){
+      loadDiscovery();
+      if(_discoveryTimer){clearInterval(_discoveryTimer);_discoveryTimer=null;}
+      _discoveryTimer=setInterval(loadDiscovery,10000);   // 10s 轮询：扫完自动出新结果
+    }
+  } else if(_discoveryTimer){clearInterval(_discoveryTimer);_discoveryTimer=null;}
+}
+
+// ================== 模态框 ==================
+function showModal(){
+  document.getElementById('modal-overlay').classList.add('show');
+}
+function closeModal(){
+  // 先关闭弹窗（最重要的一步，确保一定执行）
+  const ov=document.getElementById('modal-overlay');
+  if(ov)ov.classList.remove('show');
+  // 再做清理工作，任何异常都不影响弹窗关闭
+  try{
+    stopShotTimer();
+    _shotSerial='';
+    const box=document.getElementById('modal-box');
+    if(box){box.classList.remove('shot-modal');box.classList.remove('wide-modal');}
+  }catch(e){console.warn('closeModal cleanup error:',e);}
+}
+
+// 测试此步骤弹窗关闭（editor.js 的测试按钮用；曾随 STF 清理误删）
+function closeTestModal(){
+  const ov=document.getElementById('test-overlay');
+  if(ov)ov.classList.remove('show');
+}
+
+// 关闭元素抓取弹窗（不影响任务编辑窗口）
+function closeElPicker(){
+  var ov=document.getElementById('el-picker-overlay');
+  if(ov)ov.classList.remove('show');
+  // 清理状态
+  try{ _stepEditor._elData=null; _stepEditor._elSerial=''; }catch(e){}
+}
+
+// ================== 行内按钮操作（停止/执行/启停等，自动 toast + 刷新）==================
+async function apiAction(url,body){
+  const r=await apiPost(url,body);
+  if(!r)return;
+  if(r.ok){showToast(r.msg||'操作成功','success');if(_activeTab==='monitor')loadMonitor();if(_activeTab==='tasks')loadTasks();}
+  else{showToast(r.error||'操作失败','error');}
+}
+
+async function scanForeground(){
+  const r=await apiPost('/api/scan_foreground');
+  if(!r)return;
+  if(r.ok){showToast('扫描已启动，请等待几秒...','success');loadMonitor();}
+  else{showToast(r.error||'扫描失败','error');}
+}
+
@@ -0,0 +1,85 @@
+// 去重记录（「任务 → 去重记录」页）
+// 账本在 done_mark 表（跨设备幂等），后端见 core/dedup.py + web/tasks_api.py 的三个接口。
+// 这一页的价值：**"谁做过了、还差谁"看得见**——用户原来不知道任务什么时候跑完，
+// 只能一直重跑，而重跑本身又在制造重复。
+var _dedupMarks = [];
+
+function loadDedup(){
+  var sel=document.getElementById('dedup-job');
+  if(!sel)return;
+  var jobId=sel.value||'';
+  apiGet('/api/done_marks?limit=300'+(jobId?('&job='+encodeURIComponent(jobId)):'')).then(function(r){
+    if(!r||!r.ok){
+      var tb=document.getElementById('tb-dedup');
+      if(tb)tb.innerHTML='<tr><td colspan="6" class="empty">读取失败：'+esc((r&&r.error)||'')+'</td></tr>';
+      return;
+    }
+    _dedupMarks=r.marks||[];
+    renderDedupJobs(r.job_id||'');
+    renderDedup(r.stats||{});
+  });
+}
+
+// 任务下拉：用已加载的任务列表填（含"全部任务"）；保持当前选中项
+// `_jobsData` 是全局任务列表（monitor.js 声明、tasks.js 的 loadTasks 填充）
+function renderDedupJobs(current){
+  var sel=document.getElementById('dedup-job');
+  if(!sel)return;
+  var jobs=_jobsData||[];
+  if(!jobs.length)return;          // 任务列表还没加载就先留着旧选项
+  var cur=current!==undefined?current:(sel.value||'');
+  var html='<option value="">全部任务</option>';
+  jobs.forEach(function(j){
+    html+='<option value="'+esc(j.id)+'">'+esc(j.name||j.id)+'</option>';
+  });
+  sel.innerHTML=html;
+  sel.value=cur;
+}
+
+function renderDedup(stats){
+  var tb=document.getElementById('tb-dedup');
+  if(!tb)return;
+  var st=document.getElementById('dedup-stats');
+  if(st){
+    st.textContent='共 '+stats.total+' 条 · 涉及 '+stats.devices+' 台设备 / '
+      +stats.identities+' 个身份值｜今天已做 '+stats.today_devices+' 台 · '
+      +stats.today_identities+' 个身份值';
+  }
+  if(!_dedupMarks.length){
+    tb.innerHTML='<tr><td colspan="6" class="empty">暂无记录（任务里用了「去重」条件 + 「记为已做」并成功做完之后才会有）</td></tr>';
+    return;
+  }
+  var KIND={day:'每天一次',all:'只做一次',hours:'按小时'};
+  tb.innerHTML=_dedupMarks.map(function(m){
+    var who=m.device_name?('<strong>'+esc(m.device_name)+'</strong><br>'
+              +'<span style="font-size:11px;color:#94a3b8;font-family:var(--mono)">'+esc(m.serial)+'</span>')
+             :('<span style="font-family:var(--mono)">'+esc(m.serial||'-')+'</span>');
+    return '<tr><td style="font-size:12px">'+esc(m.created_at)+'</td>'+
+      '<td>'+who+'</td>'+
+      '<td style="font-family:var(--mono)">'+esc(m.identity||'-')+'</td>'+
+      '<td><span class="label label-default">'+esc(KIND[m.kind]||m.kind)+'</span></td>'+
+      '<td>'+esc(m.job_name||m.job_id||'-')+'</td>'+
+      '<td><button class="btn btn-xs btn-danger" data-id="'+m.id+'" '+
+        'onclick="deleteDedupMark(this.dataset.id)" data-perm="tasks" '+
+        'title="删掉这条 → 这台设备/这个身份下次会重新执行">删除</button></td></tr>';
+  }).join('');
+}
+
+function deleteDedupMark(id){
+  if(!confirm('删掉这条去重记录？\n\n删掉之后，这台设备/这个身份下次跑该任务时会重新执行一遍。'))return;
+  apiPost('/api/done_marks/delete',{id:id}).then(function(r){
+    if(r&&r.ok){showToast(r.msg||'已删除','success');loadDedup();}
+    else showToast('删除失败: '+((r&&r.error)||''),'error');
+  });
+}
+
+function clearJobDedup(){
+  var sel=document.getElementById('dedup-job');
+  var jobId=sel?sel.value:'';
+  if(!jobId){showToast('先在左边选一个任务（"清空本任务记录"要指定任务）','error');return;}
+  if(!confirm('清空这个任务的全部去重记录？\n\n清空之后，所有设备/身份下次跑该任务都会重新执行一遍。'))return;
+  apiPost('/api/done_marks/clear',{job:jobId}).then(function(r){
+    if(r&&r.ok){showToast(r.msg||'已清空','success');loadDedup();}
+    else showToast('清空失败: '+((r&&r.error)||''),'error');
+  });
+}
@@ -0,0 +1,94 @@
+// 统一列表组件：setListPager 搜索 + 分页 + 排序（_lpSort）
+// ================== 通用列表：搜索 + 分页 + 排序 ==================
+// 用法：
+//   setListPager(key,{data:()=>array, filter:(item,kw)=>bool, render:(item)=>html,
+//                     tbody:'tb-id', pager:'pager-id', pageSize:N,
+//                     sortValue:(item,colKey)=>值,   // 可排序列的取值函数
+//                     empty:'<tr>...'});
+//   applyListPager(key);             // 数据变化后重渲染（含搜索/翻页/排序状态）
+//   initListSearch(key,'search-id'); // 搜索框绑定
+//   _lpSort(key,'colKey');           // 表头排序：th 加 data-sort="colKey" + onclick，
+//                                    // 再点切换升降序，第三次取消；排序指示器自动更新
+var _LIST_PAGERS={};
+
+function _lp(key){ return _LIST_PAGERS[key] || (_LIST_PAGERS[key]={page:1,kw:'',cfg:null,sort:null}); }
+
+function setListPager(key,cfg){
+  // 只更新配置，不重置 page/kw/sort —— 监控列表 5 秒自动刷新时保持用户当前状态
+  var st=_lp(key); st.cfg=cfg;
+}
+function initListSearch(key,inputId){
+  var input=document.getElementById(inputId);
+  if(!input||input.dataset.bound)return;
+  input.dataset.bound='1';
+  input.addEventListener('input',function(){
+    var st=_lp(key); st.kw=this.value.trim(); st.page=1; applyListPager(key);
+  });
+}
+function _lpSort(key,colKey){
+  var st=_lp(key);
+  if(st.sort&&st.sort.key===colKey){
+    if(st.sort.dir===1)st.sort.dir=-1;      // 升序 → 降序
+    else if(st.sort.dir===-1)st.sort=null;  // 降序 → 取消排序
+    else st.sort={key:colKey,dir:1};
+  }else{
+    st.sort={key:colKey,dir:1};
+  }
+  applyListPager(key);
+}
+function applyListPager(key){
+  var st=_lp(key);
+  if(!st.cfg)return;
+  var cfg=st.cfg;
+  var all=(cfg.data&&cfg.data())||[];
+  var kw=st.kw.toLowerCase();
+  var filtered=kw?all.filter(function(x){return cfg.filter(x,kw);}):all;
+  // 排序：cfg.sortValue 取列值；空值/缺失恒排最后；字符串用中文数字感知比较（10 排在 9 后）
+  if(st.sort&&cfg.sortValue){
+    var sk=st.sort.key, dir=st.sort.dir;
+    filtered=filtered.slice().sort(function(a,b){
+      var va=cfg.sortValue(a,sk), vb=cfg.sortValue(b,sk);
+      if(va===vb)return 0;
+      if(va==null||va==='')return 1;
+      if(vb==null||vb==='')return -1;
+      if(typeof va==='number'&&typeof vb==='number')return (va-vb)*dir;
+      return String(va).localeCompare(String(vb),'zh-Hans-CN',{numeric:true})*dir;
+    });
+  }
+  var pageSize=cfg.pageSize||10;
+  var pages=Math.max(1,Math.ceil(filtered.length/pageSize));
+  if(st.page>pages)st.page=pages;
+  if(st.page<1)st.page=1;
+  var start=(st.page-1)*pageSize;
+  var slice=filtered.slice(start,start+pageSize);
+  var tb=document.getElementById(cfg.tbody);
+  if(tb){
+    tb.innerHTML=slice.map(cfg.render).join('')||(cfg.empty||'<tr><td colspan="20" class="empty">无数据</td></tr>');
+    // 表头排序指示器（th[data-sort]，所有表格统一）
+    if(cfg.sortValue){
+      var table=tb.closest('table');
+      if(table)table.querySelectorAll('thead th[data-sort]').forEach(function(th){
+        th.classList.add('sortable');
+        th.classList.toggle('sort-asc',!!st.sort&&st.sort.key===th.dataset.sort&&st.sort.dir===1);
+        th.classList.toggle('sort-desc',!!st.sort&&st.sort.key===th.dataset.sort&&st.sort.dir===-1);
+      });
+    }
+  }
+  var pg=document.getElementById(cfg.pager);
+  if(pg)pg.innerHTML=_lpPagerHtml(key,pages,st.page,filtered.length,pageSize);
+}
+function _lpPagerHtml(key,pages,cur,total,pageSize){
+  if(pages<=1)return total>0?'<div class="list-pager"><span class="lp-total">共 '+total+' 条</span></div>':'';
+  var h='<div class="list-pager"><span class="lp-total">共 '+total+' 条</span>';
+  h+='<button class="btn btn-xs" onclick="_lpGo(\''+key+'\','+(cur-1)+')"'+(cur<=1?' disabled':'')+'>‹ 上一页</button>';
+  for(var p=Math.max(1,cur-2);p<=Math.min(pages,cur+2);p++){
+    h+='<button class="btn btn-xs'+(p===cur?' btn-primary':'')+'" onclick="_lpGo(\''+key+'\','+p+')">'+p+'</button>';
+  }
+  h+='<button class="btn btn-xs" onclick="_lpGo(\''+key+'\','+(cur+1)+')"'+(cur>=pages?' disabled':'')+'>下一页 ›</button>';
+  h+='</div>';
+  return h;
+}
+function _lpGo(key,p){
+  var st=_lp(key); st.page=p; applyListPager(key);
+}
+
@@ -0,0 +1,163 @@
+// 轻量 Markdown 渲染（AI 控制台回答用）——不引外部库/CDN（生产 220 在内网）。
+// 安全：**先 esc() 转义，再套标记**——模型输出里的原始 HTML 只会以文本显示，
+//       不会变成可执行标签。
+// 支持：标题 / 段落 / 换行 / 粗体 / 斜体 / 删除线 / 行内代码 / 围栏代码块 /
+//       有序与无序列表（含一层以上嵌套）/ 引用 / 表格 / 分隔线 / 链接。
+// 依赖：esc()（base.js，本文件须在其后加载）
+
+// 行内代码占位符（控制字符，正文几乎不可能出现）
+const _MD_PH = '\u0001';
+
+function _mdInline(s){
+  const codes = [];
+  // 行内代码先摘出，避免其中的 ** * ~~ 被继续当标记解析
+  s = s.replace(/`([^`]+)`/g, (m, c)=>{
+    codes.push(c);
+    return _MD_PH + (codes.length - 1) + _MD_PH;
+  });
+  s = s.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+       .replace(/~~([^~]+)~~/g, '<del>$1</del>')
+       .replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<em>$2</em>')
+       .replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g,
+                '<a href="$2" target="_blank" rel="noopener noreferrer">$1</a>');
+  return s.replace(new RegExp(_MD_PH + '(\\d+)' + _MD_PH, 'g'),
+                   (m, i)=>'<code>' + codes[+i] + '</code>');
+}
+
+// 表格行 → 单元格数组
+function _mdCells(line){
+  return line.trim().replace(/^\|/, '').replace(/\|$/, '')
+             .split('|').map(c=>c.trim());
+}
+
+// 列表项递归渲染（缩进 = 层级；同类标记合并，类型变了外层另起一个列表）
+function _mdList(items, out, idx, indent){
+  const ordered = items[idx].ordered;
+  const tag = ordered ? 'ol' : 'ul';
+  out.push('<' + tag + ' class="md-list">');
+  while(idx < items.length && items[idx].indent >= indent){
+    const it = items[idx];
+    if(it.indent > indent) break;               // 更深缩进块由外层另起列表（避免非法嵌套）
+    if(it.ordered !== ordered) break;           // 同级但标记类型变了 → 交回外层
+    out.push('<li>' + _mdInline(esc(it.text)));
+    if(idx + 1 < items.length && items[idx + 1].indent > indent){
+      idx = _mdList(items, out, idx + 1, items[idx + 1].indent);
+      out.push('</li>');
+      continue;
+    }
+    out.push('</li>');
+    idx++;
+  }
+  out.push('</' + tag + '>');
+  return idx;
+}
+
+// 主入口：Markdown 文本 → HTML 字符串
+function renderMarkdown(src){
+  const lines = String(src == null ? '' : src).replace(/\r\n?/g, '\n').split('\n');
+  const out = [];
+  let para = [];
+  let i = 0;
+
+  const flushPara = ()=>{
+    if(!para.length) return;
+    out.push('<p>' + para.map(l=>_mdInline(esc(l))).join('<br>') + '</p>');
+    para = [];
+  };
+
+  while(i < lines.length){
+    const ln = lines[i];
+    let m;
+
+    // 围栏代码块 ```lang … ```
+    if(/^\s*```/.test(ln)){
+      flushPara();
+      const body = [];
+      i++;
+      while(i < lines.length && !/^\s*```/.test(lines[i])){ body.push(lines[i]); i++; }
+      if(i < lines.length) i++;                 // 跳过结束围栏
+      out.push('<pre class="md-code"><code>' + esc(body.join('\n')) + '</code></pre>');
+      continue;
+    }
+
+    // 表格：表头行 + 分隔行（|---|---|）
+    if(/^\s*\|.*\|\s*$/.test(ln) && i + 1 < lines.length
+       && /^\s*\|[\s:|-]+\|\s*$/.test(lines[i + 1])){
+      flushPara();
+      const head = _mdCells(ln);
+      i += 2;
+      const rows = [];
+      while(i < lines.length && /^\s*\|.*\|\s*$/.test(lines[i])){
+        rows.push(_mdCells(lines[i])); i++;
+      }
+      out.push('<table class="md-table"><thead><tr>'
+        + head.map(c=>'<th>' + _mdInline(esc(c)) + '</th>').join('') + '</tr></thead><tbody>'
+        + rows.map(r=>'<tr>' + r.map(c=>'<td>' + _mdInline(esc(c)) + '</td>').join('')
+                     + '</tr>').join('')
+        + '</tbody></table>');
+      continue;
+    }
+
+    // 标题 #~######
+    m = ln.match(/^\s{0,3}(#{1,6})\s+(.*)$/);
+    if(m){
+      flushPara();
+      const lv = m[1].length;
+      out.push('<h' + lv + ' class="md-h">' + _mdInline(esc(m[2])) + '</h' + lv + '>');
+      i++;
+      continue;
+    }
+
+    // 分隔线 --- / *** / ___
+    if(/^\s{0,3}([-*_])\s*(\1\s*){2,}$/.test(ln)){
+      flushPara(); out.push('<hr>'); i++; continue;
+    }
+
+    // 引用 >
+    if(/^\s{0,3}>\s?/.test(ln)){
+      flushPara();
+      const body = [];
+      while(i < lines.length && /^\s{0,3}>\s?/.test(lines[i])){
+        body.push(lines[i].replace(/^\s{0,3}>\s?/, '')); i++;
+      }
+      out.push('<blockquote class="md-quote">'
+        + body.map(l=>_mdInline(esc(l))).join('<br>') + '</blockquote>');
+      continue;
+    }
+
+    // 列表（- * + / 1. 1)）——含缩进续行
+    m = ln.match(/^(\s*)([-*+]|\d+[.)])\s+(.*)$/);
+    if(m){
+      flushPara();
+      const items = [];
+      while(i < lines.length){
+        const mm = lines[i].match(/^(\s*)([-*+]|\d+[.)])\s+(.*)$/);
+        if(!mm) break;
+        items.push({indent: mm[1].replace(/\t/g, '  ').length,
+                    ordered: /\d/.test(mm[2]), text: mm[3]});
+        i++;
+        // 紧跟的纯缩进行算上一条的续行
+        while(i < lines.length && /^\s+\S/.test(lines[i])
+              && !/^\s*([-*+]|\d+[.)])\s+/.test(lines[i])){
+          items[items.length - 1].text += ' ' + lines[i].trim();
+          i++;
+        }
+      }
+      let k = 0;
+      while(k < items.length){
+        const n = _mdList(items, out, k, items[k].indent);
+        if(n <= k) break;                        // 防死循环
+        k = n;
+      }
+      continue;
+    }
+
+    // 空行 = 段落分隔
+    if(!ln.trim()){ flushPara(); i++; continue; }
+
+    para.push(ln);
+    i++;
+  }
+  flushPara();
+  return out.join('');
+}
@@ -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');
+  });
+}
@@ -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();
+}
@@ -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);
+}
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`"""Agent 编排层：第三方 LLM（OpenAI 兼容）经 MCP 工具控制手机。"""`