Merge branch 'dev'——标题行两种写法都认 + 行首 # 不再无条件当注释

一、标题行解析（core/video_plan.parse_title_line）
- 原来只认「标题内容_手机号_日期_编号」（右锚定）。现在**两种都认**：
   ① 标题内容_手机号_日期_编号        （推荐，右锚定 —— 标题里带下划线也不会错配）
   ② 手机号_日期_编号_标题            （左锚定，跟视频文件名同序 = "文件名去掉扩展名 + 标题"）
  两种里都**先试带编号的**，保证同一行永远只有一种解释；编号都可省略。
- 新拒收一条：`手机号_日期_1`（只有编号、没标题）**直接拒** ——
  不能把它当标题"1"（静默生成一条标题是"1"的文案，比拒收危险得多）；
  标题真是纯数字的用写法①。

二、`#` 开头的行（parse_titles_text）
- 原来是"以 `#` 开头就整行忽略" → **`#中秋快乐_...` 这种正常标题会被静默丢掉**。
- 改成**先按标题行解析，解析得出就当标题；解析不出且以 `#` 开头才算注释**。
  `# 这是注释` 照样忽略，`#话题` 开头的标题照收（`#` 保留在标题里）。

三、其它
- 文案同步：上传标题面板/帮助文案、doc/API.md 的 upload_titles 语义（两种写法、`#` 规则、拒收条件）
- 测试：新增 8 条（两种写法 × 带/不带编号 × 标题含下划线与 #话题、只有编号要拒收、整段注释与报错）

.env.example

@@ -1,41 +1,126 @@
-# 环境变量示例：复制为 .env 并按需修改（.env 不进 git）
-# 生产环境建议用环境变量/密钥管理注入，不要把真实 token 写进 git。
-# 全部可配置项见 config.py（_env() 读取，未配置时用代码内默认值）；
-# 标"必须"的项务必设置，其余可留空用默认。
+# ==============================================================================
+# auto_control 环境变量示例
+#   - 复制为项目根目录的 .env 再按需修改（.env 已被 .gitignore 排除，不会进 git）
+#   - 加载方式：config.py 逐行解析后用 os.environ.setdefault 注入
+#     → 因此"真实环境变量"优先于 .env（容器/CI 里用 env 覆盖更方便）
+#   - 标【必须】的项务必设置；其余留空即用代码默认值
+#   - 完整说明见 doc/DEVELOPMENT.md §4 配置速查、doc/DEPLOY.md §2.2
+# ==============================================================================
 
-# ==================== STF 平台 ====================
-# STF 服务地址（默认 http://192.168.20.220:7100）
-STF_URL=http://192.168.20.220:7100
+# ==================== 数据库 ====================
+# 平台用 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
 
-# STF API Token（必须：STF 个人设置 → API Keys 生成）
-STF_TOKEN=请填写你的STF_token
+# 完整连接串：优先级最高，用于脚本临时指向别的库（一般不用配）
+# DATABASE_URL=mysql+pymysql://user:pass@host:3306/auto_control_dev?charset=utf8mb4
 
-# 启动时自动释放残留 STF 占用（单实例无人值守开 true；多实例共用账户勿开，会误放另一实例的任务）
-# AUTO_RELEASE_STALE_OCCUPY=true
+# 逃生阀（默认关，仅在明确知道后果时打开）
+#   DB_ALLOW_ENV_MISMATCH=1     环境与库名/库标签不符时仍启动（危险）
+#   DB_ALLOW_SQLITE_FALLBACK=1  生产环境 DB_HOST 为空时允许回退 SQLite（回滚用）
+# DB_ALLOW_ENV_MISMATCH=0
+# DB_ALLOW_SQLITE_FALLBACK=0
 
-# ==================== Web 会话 ====================
-# Web 会话密钥（必须：生产设置为随机长字符串，重启不失效）
+
+# ==================== Web 服务 ====================
+# 会话密钥【必须，生产务必固定】：不配则每次启动随机生成，重启后登录态失效。
 # 生成：python -c "import secrets; print(secrets.token_hex(32))"
 WEB_SECRET_KEY=请填写随机密钥
 
-# ==================== SSH 到部署机（维护页重启 STF / 工具页 STF 设备管理） ====================
-# SSH 目标（默认 [email protected]）
-# [email protected]
+# 监听地址与端口是 config.py 里的常量（不进 .env）：WEB_HOST=0.0.0.0、WEB_PORT=18050
+# 需要修改直接改 config.py（18050 是为了避开 Windows 动态端口段）
 
-# SSH 认证密码（推荐）：配置后走 paramiko **纯密码**登录（不碰本地密钥/SSH agent，
-# 不会弹授权框，跨平台无需 sshpass）；留空则退回系统 ssh 免密密钥（BatchMode=yes）。
-STF_SSH_PASSWORD=请填写SSH密码
 
-# 220 上 STF / adb 的 Docker 容器名（默认 stf / adb，一般不用改）
-# STF_DOCKER_CONTAINER=stf
-# STF_ADB_CONTAINER=adb
+# ==================== 设备与 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
 
-# STF 设备池脚本路径（工具页"STF 设备管理"增删设备时读写其 DEVICES 列表，默认值见 config.py）
-# STF_SCRIPT_PATH=/mnt/data/openstf/connect_devices.sh
+# 设备自动发现（扫描网段找开放 5555 的设备）。
+# 扫描网段在「工具 → 设备池管理」界面里配置（存数据库 app_meta），此处只管端口与周期。
+# DISCOVERY_PORT=5555
+# DISCOVERY_INTERVAL=60
 
-# ==================== Tailscale 管理（工具页） ====================
-# API key（必须：Tailscale 后台 → Settings → API Access Tokens 生成）
+# 把本机的 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（默认按邮箱前缀，如 1422726308@gmail.com）
-# TAILSCALE_TAILNET=1422726308@gmail.com
+# tailnet 名/ID（一般填登录邮箱，如 user@example.com）
+# TAILSCALE_TAILNET=user@example.com
+
+
+# ==================== 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
+
+
+# ==============================================================================
+# 已废弃的历史配置（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
+# ==============================================================================

.gitignore

@@ -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
 
@@ -37,8 +42,11 @@ desktop.ini
 *.bak
 
 # 密钥/环境变量（真实 .env 含 token/密钥，绝不提交）
+# .env.* 一并忽略：改配置前留的 .env.bak_xxx / .env.old 同样含生产密钥，
+# 220 上就出现过一次（2026-09-13 切 MySQL 时的备份），差点被 git add . 带进去。
 .env
-.env.local
+.env.*
+!.env.example
 
 
 bin/adb/*
@@ -48,3 +56,6 @@ data/*.corrupt_*
 data/users.db*
 data/users.db-wal
 data/users.db-shm
+data/backups/
+data/restore_staging/
+data/restore_pending/

README.md

@@ -1,23 +1,67 @@
-# 设备自动化后台（platform-tools）
+# auto_control — Android 多设备自动化任务平台
 
-基于 **uiautomator2 + Flask + 自建设备池** 的 Android 多设备自动化任务执行平台（已摘除 OpenSTF 依赖）。
+基于 **uiautomator2 + Flask + 自建设备池** 的 Android 多设备自动化平台（已摘除 OpenSTF 依赖，见 [doc/STF_REMOVAL.md](doc/STF_REMOVAL.md)）。
 
-提供 Web 管理后台，支持多设备并发任务执行、定时调度、设备分组管理、设备池管理（新增/停用/删除/型号采集）、APK 批量安装、网页远程看屏（MJPEG 实时流 + 触控）、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） |
+| **账号台账** | 「账号」页维护"**哪台设备上登着哪些号**"（设备号/手机号/账号名/抖音号/注册时间/卡在机内/可发视频/简介/备注）：支持**从 Excel 粘贴批量导入**（表头识别、逐行结果、先预览后写入）。三个用处：① 任务的「条件判断」**直接从这里取号**，不用把几十个号手写进比对值；② 手机端 Agent 的**身份大字页**显示本机账号；③ 设备池里一眼看到每台登记了几个号（见 [DATA_MODEL.md](doc/DATA_MODEL.md) §2.10、[TASK_DEV.md](doc/TASK_DEV.md) §4.2） |
+| **视频发布计划** | 「账号 → 发布计划」页：批量上传视频（文件名 `手机号_日期_编号`）与标题 txt → 自动按 (手机号,日期,编号) 配对到台账账号 → **按日期的时间线**看每天谁要发、发到哪一步。**平台只负责把素材推到手机**（推到 `/sdcard/DCIM/rp/`、触发相册刷新、把标题写进剪贴板），**抖音里怎么发由你自己在任务里写步骤**（步骤顺序：`推送发布视频` → 你的发布步骤 → `标记发布结果`；「发布计划」页顶部有**「发布任务」**块可一键建好骨架 + 看下次运行/启停，`输入文字` 那一步可以选**取值来源＝计划标题**自动填文案并回读校验）；发完可抓作品的**分享链接**存下来（平台不长期囤视频，链接才是长期资产，也方便后续铺评论：可一键复制、按日期/账号导出 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 +70,8 @@
 ### 环境要求
 
 - **Python 3.10+**（推荐 3.12）
-- **Windows / Linux / macOS**均可（adb 二进制需放对应平台版本到 `bin/adb/`）
-- 设备需开启 **USB 调试**（USB 连上后 `adb tcpip 5555` 转网络调试），并加入 Tailscale 获得 `100.100.10.x` IP
-- 新增设备在后台「工具 → 设备池管理」添加 `IP:5555`（自动连接，任务运行时 u2 自动推送 atx-agent）
+- Windows / Linux / macOS 均可（`bin/adb/` 需放对应平台的 adb 二进制）
+- 设备开启 **USB 调试**；网络调试设备建议 `adb tcpip 5555` 并接入同一网络（本项目生产环境走 Tailscale `100.100.10.x`，见 [doc/DEPLOY.md](doc/DEPLOY.md)）
 
 ### 三步启动
 
@@ -36,421 +79,346 @@
 # 1. 安装依赖
 pip install -r requirements.txt
 
-# 2. 修改配置（可选）：USB 设备在 220 上时配置 USB_ADB_HOST/PORT（默认 100.100.10.1:5037 已可用）
-#    密钥类配置放 .env（WEB_SECRET_KEY / TAILSCALE_API_KEY）
+# 2. 配置（可选）：把 .env.example 复制成 .env，至少填 WEB_SECRET_KEY
+#    密钥类配置一律放 .env（不入 git）
 
-# 3. 启动 Web 后台
+# 3. 启动
 python web_server.py
 ```
 
-启动后访问 **http://localhost:18050/**，默认账号 `admin` / `admin123`。
+启动后访问 **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. **添加设备** → "工具 → 设备池管理"添加设备（serial 形如 `100.100.10.20:5555`，自动连接并采集型号）
-3. **查看设备** → 首页"监控"Tab 展示设备池状态（在线/型号/任务）
-4. **创建分组**（可选）→ "分组"Tab 按批次/项目给设备分组
-5. **创建任务** → "任务"Tab 新建任务，选择任务类型、目标设备、参数、调度
-6. **执行任务** → 任务列表点"立即执行"，或在"监控"Tab 勾选设备批量操作（亮屏/息屏/停止）
-7. **查看日志** → "日志"Tab 实时查看运行日志
+1. **登录** → `admin/admin123`，改密
+2. **加设备** → 「工具 → 设备池管理」添加 `IP:5555`（自动连接 + 采集型号）；也可用「设备自动发现」扫描网段后确认入池
+3. **看设备** → 「监控」页设备表（在线/型号/任务/进度/前台 App）
+4. **建任务** → 「任务 → 任务计划 → 新建任务」（只有 `generic_steps` 一种类型）→ 拖步骤 → 选目标设备 → 保存
+5. **跑任务** → 任务行「执行」，或在「任务」/「监控」页操作
+6. **看日志** → 「日志」页按模块实时查看
 
 ---
 
 ## 项目结构
 
 ```
-platform-tools/
-├── config.py                    # 根配置（部署配置统一从 .env 读，模板见 .env.example）
-├── web_server.py                # Flask 入口（app 装配 + 蓝图注册 + 启动，193 行）
-├── web/                         # Web 层蓝图包（按功能域拆分，路由都在这里）
-│   ├── auth.py                  #   登录/CSRF/权限装饰器/页面路由（/、/wall）
-│   ├── monitor.py               #   状态/运行控制/设备操作/远程看屏
-│   ├── tasks_api.py             #   任务计划/分组/自定义动作/元素抓取
-│   ├── admin_api.py             #   用户管理/日志
-│   ├── tools_api.py             #   adb 终端/剪贴板注入/应用版本
-│   ├── devices_api.py           #   设备池管理
-│   ├── apks_api.py              #   应用管理
-│   ├── tailscale_api.py         #   Tailscale 管理
-│   ├── common.py                #   跨模块共享工具（合并设备列表/屏幕状态）
-│   └── context.py               #   共享对象注入（mgr/apk_mgr/device_pool）
-├── requirements.txt             # Python 依赖清单
+auto_control/
+├── config.py                  # 程序级配置常量（部署配置从 .env 读，模板 .env.example）
+├── web_server.py              # 入口：app 装配 + 蓝图注册 + 恢复消费 + 拉起 uiautodev + 启动
+├── requirements.txt           # 依赖清单
 │
-├── core/                        # 核心基础设施层
-│   ├── logger.py                #   统一日志（分文件、10MB 滚动）
-│   ├── device_pool.py           #   设备池（SQLite 清单 + adb 在线状态 + 型号采集）
-│   ├── adb_helper.py            #   adb 命令封装（全局锁，绝不 kill-server）
-│   ├── device_worker.py         #   BaseWorker 基类 + 设备生命周期 + 心跳看门狗
-│   ├── task_manager.py          #   TaskManager 调度器 + 前台App扫描器
-│   ├── u2_helper.py             #   uiautomator2 通用辅助函数
-│   ├── uiauto_helper.py         #   uiautodev 元素抓取客户端
-│   ├── apk_manager.py           #   APK 上传/解析/批量安装
-│   ├── ocr.py                   #   屏幕 OCR（RapidOCR，条件判断 OCR 选择器）
-│   ├── ssh_client.py            #   SSH 统一执行（paramiko 纯密码 / 免密密钥，预留运维用）
-│   ├── tailscale_client.py      #   Tailscale API v2 客户端
-│   ├── models.py                #   SQLAlchemy 数据模型 + 数据库初始化
-│   └── actions/                 #   全局 Action 框架
+├── 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/                  #   抖音养号任务
-│   └── generic/                 #   通用步骤任务（可视化编辑器编排）
-│       └── task.py              #     步骤执行引擎（open_app/click/swipe/if_el...）
+├── 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 只读）+ 低电量告警
+│   ├── ledger.py              #   账号台账（CRUD / 表格粘贴解析 / 给任务取号 / 设备端账号块）
+│   ├── video_plan.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             #   单页应用（监控/任务/分组/日志/用户/工具）
-│   └── login.html               #   登录页
+├── tasks/                     # 任务定义层
+│   ├── base.py                #   BaseTask + _TASK_TYPES + register_task
+│   └── generic/               #   通用步骤任务（task_type=generic_steps，当前唯一类型）
+│       └── task.py            #     STEP_TYPES（24 种步骤）+ Worker + 执行器
 │
-├── static/admin/                # 前端 JS 模块（monitor.html 按依赖顺序加载）
-│   ├── base.js                  #   通用基础：API/CSRF/权限/Tab切换/子分栏/模态框
-│   ├── list.js                  #   统一列表组件（搜索+分页+排序）
-│   ├── monitor.js               #   监控页（设备表/截图/异常汇总）
-│   ├── editor.js                #   步骤编辑器（拖拽/条件判断/元素抓取）
-│   ├── tasks.js                 #   任务 Tab + 自定义动作
-│   ├── tools.js                 #   工具 Tab（剪贴板/设备池管理/adb终端/Tailscale/远程看屏）
-│   ├── apps.js                  #   工具 Tab-应用管理（APK/设备已装应用）
-│   ├── admin.js                 #   管理 Tab（分组/日志/用户）+ 初始化
+├── 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_* 环境变量
+│
+├── mcp_agent/                 # AI Agent 编排层（OpenAI 兼容模型 → MCP 工具）
+│   ├── agent.py               #   Agent：流式循环 + 工具调用 + 截图 + token 统计
+│   ├── config.py              #   AGENT_* 环境变量
+│   └── cli.py                 #   命令行入口
+│
+├── templates/admin/           # 页面
+│   ├── monitor.html           #   主单页应用（7 个顶级 Tab + 模态框 + 内联样式）
+│   ├── login.html             #   登录页
+│   └── wall.html              #   监控大屏（独立页面，自包含）
+├── static/admin/              # 前端 JS（13 个文件，按顺序同步加载，见下）
 ├── static/fonts/              # 自托管字体（Bricolage Grotesque + IBM Plex Mono）
 │
-├── data/
-│
-├── data/                        # 运行时数据
-│   ├── users.db                 #   SQLite（用户/分组/任务/自定义动作/APK记录）
-│   └── apks/                    #   上传的 APK 文件存储
-│
-├── logs/                        # 日志文件（自动生成，10MB 滚动保留 5 份）
-├── bin/adb/                     # adb 可执行文件（Windows: adb.exe + dll）
-├── scripts/                     # 实用脚本
-│   ├── pack.py                  #   打包项目为 zip（排除运行时产物）
-│   └── supervise.sh             #   进程守护（崩溃自动重启）
-└── doc/                         # 项目文档
-    ├── API.md                   #   API 文档
-    ├── ARCHITECTURE.md          #   架构详解
-    ├── DEPLOY.md                #   部署指南
-    ├── DEVELOPMENT.md           #   开发指南
-    └── 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
 
-```
-设备池选定设备（TaskManager._running 内存锁保证互斥）
-    ↓
-IP:5555 → adb connect 直连；USB（serial 无冒号）→ 本机 adb 或 220 远程 adb server
-    ↓
-u2.connect（连接 uiautomator2，自动推送 atx-agent）
-    ↓
-Worker.run_task（执行业务逻辑）
-    ↓
-释放（不 disconnect，遵守共享 adb transport 红线）
-```
+一台设备对应一个 `Worker` 线程（`core/device_worker.py` 的 `BaseWorker`）。基类封装了设备获取、adb/u2 连接（带超时保护）、状态上报、异常分类、停止信号、心跳看门狗；子类只实现 `run_task(d)`。
 
-> 单实例部署下互斥由调度器内存锁保证；多实例场景可扩展 SQLite 行锁（见 doc/STF_REMOVAL.md 阶段 4）。
+执行链路：`设备池选定 → 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）
 
-- 设备获取（IP:5555 直连 / USB 远程 adb server，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` | 是否参与调度 |
 
-**简单设置**：编辑任务时选"定时启动/定时启动+停止"后，频率用下拉选择——每天（选时间）、每小时（整点）、每隔 N 小时、每周（选星期+时间）——cron 表达式自动生成，不需要懂 cron 语法。老手可在"自定义 cron（高级）"里直接填。
+**调度模式**：`once` 仅手动；`cron` 到点启动；`cron_stop` 到点启动 + 到点停止。cron 为标准 5 段 `分 时 日 月 周`，编辑器提供"每天/每小时/每隔 N 小时/每周"的可视化选择自动生成，也可手填。
 
-cron 表达式为标准 5 段格式：`分 时 日 月 周`（如 `0 9 * * *` = 每天 9:00，`0 */2 * * *` = 每 2 小时整点，周 `0`/`7` 均为周日）
+**运行窗口**（`schedule.window`，如 `21:00-09:00`，支持跨午夜）：窗口外定时触发与手动执行都不启动。
 
-**运行窗口**：任务可勾选"启用运行窗口"，设置每天允许运行的时间段（如 `21:00-09:00` = 晚 9 点到次日早 9 点，支持跨午夜）。窗口外**定时触发和手动执行都不会启动**（手动执行会提示"当前不在运行窗口内"）。典型用法：`每小时`定时 + 窗口 `09:00-21: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` 顶部）。
-
-| 配置项 | 默认值 | 说明 |
-|-------|--------|------|
-| `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 文件存储目录 |
-| `USB_ADB_HOST` | `100.100.10.1` | USB 设备所在部署机（220）的 Tailscale IP（USB 设备远程 adb server） |
-| `USB_ADB_PORT` | `5037` | 220 adb 容器监听端口（host 网络模式） |
-| `TAILSCALE_API_KEY` | （.env 配置） | Tailscale 管理 API key（Settings → API Access Tokens） |
-| `TAILSCALE_TAILNET` | 按邮箱前缀 | tailnet 名/ID |
-
-**必须修改的配置**：`.env` 里的 `WEB_SECRET_KEY`（会话密钥，不入 git）；其余均为可选（默认值开箱即用）。
+前端展示为进度条 + `5/80 视频` + 计数徽章 + 运行时长。
 
 ---
 
 ## Web 管理后台
 
-### 页面结构
+单页应用（`templates/admin/monitor.html`），**7 个顶级 Tab**；「任务 / 工具 / 系统」内部还有页内子分栏（会记住上次选中位置）。
 
-单页应用（`templates/admin/monitor.html`），6 个 Tab；任务/工具 Tab 内部再有页内子分栏：
-
-| Tab | 功能 | 可见性 |
+| Tab | 内容 | 可见性 |
 |-----|------|--------|
-| 监控 | 设备状态大屏：在线/离线、型号、运行任务、当前动作、进度条、前台 App、截图、勾选批量操作（亮屏/息屏/停止）；导航栏「📺 大屏」打开全屏监控墙（/wall，缩略图+统计+时钟，挂墙/电视用） | 所有登录用户（设备操作按钮需"设备控制"权限） |
-| 任务 | 子分栏：任务计划（CRUD/启用停用/立即执行/下次运行时间/**离线设备自动跳过**）、自定义动作（打包复用） | 所有登录用户可看，写操作需"任务管理"权限 |
-| 分组 | 设备分组管理：创建/编辑/删除分组 | 所有登录用户可看，写操作需"任务管理"权限 |
-| 日志 | 实时日志查看：按模块切换（core/task/web/action） | 需"日志查看"权限 |
-| 用户 | 用户管理：创建/删除/修改密码/分配权限 | 仅管理员 |
-| 工具 | 子分栏：剪贴板注入、adb 远程终端（快捷命令/自动 `-s`）、**设备池管理**（新增/停用/删除/一键重连/型号采集）、**远程看屏**（MJPEG 实时流 + 点击/滑动/按键/文字）、Tailscale 管理（改名/授权/密钥不过期/设置IP/auth key）、应用管理（APK 上传安装）、应用版本管理（按包名查所有设备版本）、设备已装应用 | 仅管理员 |
+| **监控** | 统计卡片 + 设备表（在线/型号/任务状态/进度/前台 App/最近错误，支持排序、搜索、分页、多选批量操作）+ 异常汇总 + **任务运行概况**（每张任务卡：执行任务 / 停用任务 + 覆盖设备彩色 chip）；导航栏「📺 大屏」打开 `/wall` | 所有登录用户（设备操作按钮需"设备控制"） |
+| **任务** | 子分栏：**任务计划**（CRUD / 启停 / 执行 / 下次运行时间 / 离线跳过 / 步骤编辑器 / **公共巡检**）、**自定义动作**（步骤打包复用）、**动作配置**（步骤默认值 + 录制动作） | 可看；写操作需"任务管理" |
+| **日志** | 子分栏：**文件日志**（文件切换含滚动历史、关键字/级别/时间过滤、命中高亮、下载筛选结果、自动刷新）、**步骤明细**（按设备/任务/结果/时间过滤、按运行归组的概览、导出 CSV） | 需"日志查看" |
+| **用户** | 用户 CRUD、改密、分配权限 | 仅管理员 |
+| **工具** | 8 个子分栏：剪贴板注入 / adb 远程终端 / Tailscale 管理 / 应用管理 / 应用版本管理 / 设备已装应用 / **设备池管理**（含自动发现）/ 设备分组 | 仅管理员 |
+| **AI 控制台** | 会话列表 + 对话区（Markdown 渲染、推理链折叠、token 统计）+ 实时画面（MJPEG）+ 目标设备选择；右上角：经验库 / 动作库 / 模型配置 | 仅管理员 |
+| **系统** | 子分栏：数据备份（导出 zip）/ 导入恢复（上传→校验预览→应用，重启生效） | 仅管理员 |
 
-任务/工具 Tab 的子分栏会记住上次选中的位置；无权限的 tab 和按钮自动隐藏。
+### 权限模型
 
-### 用户与权限
+默认账号 `admin/admin123`（管理员，权限不受限）。权限位：
 
-默认账号 `admin` / `admin123`（管理员，拥有全部权限）。管理员可在"用户"Tab 创建普通用户并分配权限：
+| 权限位 | 键 | 覆盖 |
+|--------|----|------|
+| 任务管理 | `tasks` | 任务/分组/自定义动作的写操作 |
+| 设备控制 | `devices` | 停止设备、亮息屏、定位、清异常、前台扫描、元素抓取、步骤测试 |
+| 应用管理 | `apks` | APK 上传/安装/删除 |
+| 日志查看 | `logs` | 日志 Tab |
 
-| 权限位 | 说明 | 覆盖功能 |
-|--------|------|---------|
-| 任务管理 `tasks` | 任务/自定义动作/分组的增删改、启停、立即执行 | 任务 Tab、分组 Tab 的写操作 |
-| 设备控制 `devices` | 停止设备、释放占用、清除异常、前台扫描、元素抓取 | 监控 Tab 的设备操作按钮、步骤编辑器的"抓取元素" |
-| 应用管理 `apks` | APK 上传、安装、删除 | 应用管理/设备已装应用（当前并入工具 Tab，工具页整体仅管理员可见） |
-| 日志查看 `logs` | 日志页 | 日志 Tab |
-
-规则：
-- **管理员拥有全部权限**，不受权限位限制
 - 查看类接口（设备/任务/分组列表、状态、截图）所有登录用户可用
-- **用户管理仅管理员可用**；不能删除/取消最后一个管理员
-- 无权限的 tab 和按钮在界面上自动隐藏（后端同样拦截，返回 403）
-
-### 前台 App 扫描
-
-监控页"扫描前台App"按钮，获取所有设备当前前台 App。**不打扰设备**：
-
-| 设备状态 | 处理方式 |
-|---------|---------|
-| worker 运行中（IP:5555） | 复用已有 ADB 连接查询 |
-| worker 运行中（USB） | 经 220 远程 adb server 查询 |
-| 完全空闲 | 返回"空闲"（不主动 connect，避免扰动共享 adb transport） |
-
-### 截图功能
-
-监控页每台设备可查看实时截图。用 `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（指定包名，可选等待首页） |
-| `stop_app` | 强制结束 App（am force-stop，清后台，下次打开冷启动） |
-| `screen_on` | 亮屏（息屏时唤醒并滑动解锁） |
-| `screen_off` | 息屏 |
-| `keep_screen` | 保持亮屏/恢复自动息屏（充电时屏幕常亮，适合长任务） |
-| `key_event` | 按键：返回/Home/回车/菜单等（退出评论、返回上一页） |
-| `swipe` | 滑动（上/下/左/右，可配置时长） |
-| `swipe_until` | 滑动直到元素出现（最多 N 次，可选找到后点击） |
-| `click_xy` | 点击坐标（屏幕百分比，无选择器时兜底） |
-| `long_click` | 长按元素（选择器 + 时长） |
-| `wait_el` | 等待元素出现（条件等待，替代固定时长） |
-| `input_text` | 输入文字（随机候选/指定文字，可选输入前先清空） |
-| `click` | 点击元素（支持 xpath/description/resourceId/text 选择器） |
-| `wait` | 等待（可配置时长范围） |
-| `loop` | 循环块（含子步骤，可配置循环次数） |
-| `group` | 动作组（含子步骤，按序执行一次） |
-| `if_el` | 条件判断：找元素（支持 xpath 等选择器或 **OCR识别** 截屏匹配图片文字），命中执行"找到时"分支，未命中执行"未找到时"分支；OCR 命中可自动点击。分支可嵌套循环/条件判断 |
-
-步骤编辑器特性：操作库按分类分组、卡片可拖拽排序/跨层级嵌套（循环套循环）、☑ 多选打包自定义动作、
-"测试此步骤"真机验证、"抓取元素"回填选择器、条件判断的 OCR 识别依赖 `rapidocr_onnxruntime`（跨平台）。
-
-### 新增 App 任务
-
-参照 `tasks/douyin/` 结构，6 步即可新增一个 App 任务，详见 [doc/TASK_DEV.md](doc/TASK_DEV.md)。
+完整键表（含 `MCP_*` / `AGENT_*`）见 [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md) §配置速查。
 
 ---
 
-## 日志系统
+## 日志
 
-日志按模块分文件，自动滚动（10MB 一份，保留 5 份历史）：
+按模块分文件，单文件 10MB 滚动、保留 5 份：
 
-| 文件 | 模块前缀 | 内容 |
-|------|---------|------|
-| `logs/core.log` | `core.*` | 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 scripts/pack.py` | 打包项目为 zip（排除日志/数据库/APK） |
-| `bash scripts/supervise.sh` | 进程守护（web_server 崩溃自动重启） |
+「日志 → 步骤明细」是**结构化**的另一半：每一次步骤执行落一行 `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` 到一个不在排除范围内的端口。
-
-### 设备显示离线
-
-先确认本机 `adb devices` 能看到设备（工具 → 设备池管理 → 一键重连）；看不到则检查 Tailscale 是否在线、设备是否加入了正确的 tailnet（平台与设备必须在同一 tailnet）。
-
-### 新增设备后任务不调度它
-
-新设备需在「工具 → 设备池管理」添加（serial 为 `IP:5555`），仅连上 adb 不会进入设备池。添加后自动连接并采集型号，下一轮任务即可调度。
-
-### 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/DEVELOPMENT.md](doc/DEVELOPMENT.md) | **开发手册**：开发流程、git 工作流、技术红线、环境、本地开发 |
-| [doc/TASK_DEV.md](doc/TASK_DEV.md) | 任务开发指南（新增 App 任务的完整模板和规范） |
-| [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) | 架构详解（分层设计、数据流、关键设计决策） |
-| [doc/DEPLOY.md](doc/DEPLOY.md) | 部署指南（环境准备、设备池配置、生产部署） |
-| [doc/STF_REMOVAL.md](doc/STF_REMOVAL.md) | STF 摘除迁移记录（阶段 0-3 已完成，含多实例锁方案） |
-| [doc/API.md](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 的历史记录 |
 
-> **注意**：所有 git 操作（含 push 到 dev）都需负责人确认后才能执行，详见开发手册。修改 `core/`、`tasks/`、`templates/` 后需重启服务/强刷浏览器才生效。
+> ⚠️ **改动必须同步文档**：功能/配置/接口/表结构的任何增删改，都要在同一个 commit 里更新对应文档（红线，详见 [doc/README.md](doc/README.md) §3）。
+> ⚠️ **git 操作需负责人确认**（含 push 到 dev），详见 [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md)。
 
 ---
 
@@ -458,10 +426,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 元信息解析 |
-| 自建设备池 | 设备清单/在线状态/型号（SQLite + adb） |
+| fastmcp | MCP Server（Streamable HTTP）+ AI 控制台 Agent |
+| adb（项目自带 `bin/adb/`） | 设备连接与底层操作 |

config.py

@@ -47,6 +47,33 @@ else:
     # 部署后需执行 chmod +x bin/adb/adb
     ADB_PATH = os.path.join(_ADB_DIR, "adb")
 
+# ================== 数据库 ==================
+# 平台支持 MySQL（正式用法）与 SQLite（仅作回退，见 core/db_config.py）。
+#
+# DEPLOY_ENV 声明"这套配置连的是哪个环境的库"，与库名一一绑定：
+#   dev  → auto_control_dev（本地开发，可随意折腾）
+#   prod → auto_control    （正式数据）
+# 启动时会校验「.env 声明的环境」与「目标库登记的环境」是否一致，
+# 不一致直接拒绝启动——防止把开发配置连到生产库上。
+DEPLOY_ENV = _env("DEPLOY_ENV", "dev").strip().lower()
+
+DB_HOST = _env("DB_HOST", "")          # 为空则回退 SQLite（生产禁止静默回退）
+DB_PORT = int(_env("DB_PORT", "3306"))
+DB_USER = _env("DB_USER", "")
+DB_PASSWORD = _env("DB_PASSWORD", "")  # 写入 .env，不要提交到 git
+DB_NAME = _env("DB_NAME", "")
+DB_CHARSET = _env("DB_CHARSET", "utf8mb4")
+# 排序规则用 _bin（逐码点比较，等价 SQLite 的大小写敏感语义）。
+# 用默认的 utf8mb4_general_ci 会让 Admin/admin、Phone1/phone1 被判重复。
+DB_COLLATION = _env("DB_COLLATION", "utf8mb4_bin")
+
+# 完整连接串（优先级最高，迁移/回归脚本用它临时指向别的库）
+DATABASE_URL = _env("DATABASE_URL", "")
+
+# 逃生阀（默认关；仅在你明确知道自己在干什么时打开）
+DB_ALLOW_ENV_MISMATCH = _env("DB_ALLOW_ENV_MISMATCH", "0") == "1"
+DB_ALLOW_SQLITE_FALLBACK = _env("DB_ALLOW_SQLITE_FALLBACK", "0") == "1"
+
 # ================== Web 后台 ==================
 WEB_HOST = "0.0.0.0"
 # 端口必须避开 Windows 动态端口范围（本机被改成 1024-15000，默认 49152-65535）
@@ -60,6 +87,24 @@ 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")
+
+# 单次请求体上限（字节）。**必须大于现有 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", "")

core/__init__.py

@@ -1,7 +1,7 @@
 """core 包：基础设施层。
 
-  config         — 全局配置常量（STF、adb 路径、养号参数）
+  config         — 全局配置常量（adb 路径、设备发现等）
   adb_helper     — adb 命令封装（并发安全）
-  device_worker  — 设备生命周期 + 养号 worker + 全局状态注册表
+  device_worker  — 设备生命周期 + 任务 worker 基类 + 全局状态注册表
   task_manager   — 任务管理框架（分组/计划/调度/重试/持久化）
 """

core/actions/__init__.py

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

core/actions/base.py

@@ -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：

core/apk_manager.py

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

core/clipboard_helper.py

@@ -1,10 +1,13 @@
-"""剪贴板注入公共模块（ClipInject APK 通道）。
+"""剪贴板注入公共模块（设备端 Agent 通道）。
 
 背景：Android 10+ 禁止后台（atx-agent/shell）写剪贴板——u2.set_clipboard
-调用"成功"但内容被系统静默丢弃（Android 12/13 实测）。ClipInject
-（com.example.clipinject，用户自研 APK）通过 am start 启动透明 Activity，
-窗口聚焦后 setPrimaryClip；shell 身份启动 Activity 不受后台启动限制
-（广播方式在 MIUI 会被 Background activity start 拦截，必须用 am start）。
+调用"成功"但内容被系统静默丢弃（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）共用本模块。
 """
@@ -19,17 +22,43 @@ from core.logger import get_logger
 
 _log = get_logger("core.clip")
 
-_CLIP_PACKAGE = "com.example.clipinject"
-_CLIP_ACTIVITY = "com.example.clipinject/.ClipActivity"
+# (包名, 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，红线）
-    - 未装 ClipInject / 读回不一致都会明确报错（不再静默失败）
+    - 通道缺失 / 读回不一致都会明确报错（不再静默失败）
     """
     import uiautomator2 as u2
     if ":" in serial:
@@ -39,31 +68,45 @@ def inject_clipboard(serial, text, d=None):
             return False, f"adb 连接失败: {e}"
     b64 = base64.b64encode(text.encode("utf-8")).decode()
     # 1. am start 透明 Activity 写剪贴板（shell 身份，不受后台启动限制）
-    try:
-        r = subprocess.run(
-            [ADB_PATH, "-s", serial, "shell", "am", "start",
-             "-n", _CLIP_ACTIVITY, "--es", "text_b64", b64],
-            capture_output=True, timeout=30)
-        out = ((r.stdout or b"") + (r.stderr or b"")).decode(errors="replace")
-        if "does not exist" in out or "unable to resolve Intent" in out:
-            return False, f"设备未安装 ClipInject（{_CLIP_PACKAGE}），请先安装"
-        if "Error" in out or ("Starting" not in out and r.returncode != 0):
-            return False, f"am start 失败: {out.strip()[:120]}"
-    except subprocess.TimeoutExpired:
-        return False, "am start 超时（adb 无响应）"
-    except Exception as e:
-        return False, f"{type(e).__name__}: {str(e)[:120]}"
-    # 2. 读回验证（等透明 Activity 完成写入；u2 读剪贴板在 Android 12 实测可用）
-    time.sleep(0.5)
+    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)
-        with ThreadPoolExecutor(max_workers=1) as pool:
-            got = pool.submit(lambda: d.clipboard).result(timeout=15)
+    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, "已注入"
-        return False, f"剪贴板读回不一致（写入可能被拒）: {str(got)[:60]!r}"
-    except Exception as e:
-        # 读回不可用（旧版 u2/连接失败）时按写入成功处理，避免误报，但带上具体原因
-        return True, f"已注入（读回验证不可用: {type(e).__name__}: {str(e)[:80]}）"
+        if time.time() >= deadline:
+            return False, f"剪贴板读回不一致（写入可能被拒）: {str(got)[:60]!r}"

core/db_config.py

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

core/dedup.py

@@ -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

core/device_battery.py

@@ -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()

core/device_discovery.py

@@ -22,7 +22,8 @@ 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.models import db, PendingDevice
+from core import notifier
+from core.models import db, Device, PendingDevice
 
 _log = get_logger("core.disc")
 
@@ -31,6 +32,8 @@ _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
@@ -40,6 +43,8 @@ _PROBE_TIMEOUT = 0.4
 
 _app = None
 _scan_lock = threading.Lock()     # 定时/手动扫描互斥
+# 上一轮"池内离线"集合：通知只报**状态沿**（这一轮新变成离线的），不每轮刷屏
+_last_offline = set()
 _stop_event = threading.Event()   # shutdown 用
 _scanning = False                 # 状态快照（API/前端）
 _last_scan = None                 # (时间串, 开放数, 可连数, 新增数)
@@ -59,9 +64,10 @@ def _fmt(ts=None):
 def get_settings():
     """读发现配置（app_meta，缺键用 config 默认值补齐）。"""
     with _ctx():
+        from core.db_config import meta_get
+
         def _get(key, default):
-            v = db.session.execute(
-                db.text("SELECT value FROM app_meta WHERE key=:k"), {"k": key}).scalar()
+            v = meta_get(key)
             return v if v is not None else default
         try:
             subnets = json.loads(_get(_K_SUBNETS, "[]")) or DISCOVERY_SUBNETS
@@ -72,10 +78,11 @@ def get_settings():
             "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):
+def save_settings(enabled=None, subnets=None, interval=None, port=None, auto_claim=None):
     """写发现配置（部分字段更新）。subnets 逐项校验 CIDR，非法返回 (False, 原因)。"""
     if subnets is not None:
         clean = []
@@ -97,10 +104,8 @@ def save_settings(enabled=None, subnets=None, interval=None, port=None):
     except (TypeError, ValueError):
         return False, "参数不合法"
     with _ctx():
-        def _put(key, value):
-            db.session.execute(
-                db.text("INSERT OR REPLACE INTO app_meta(key,value) VALUES(:k,:v)"),
-                {"k": key, "v": str(value)})
+        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:
@@ -109,22 +114,46 @@ def save_settings(enabled=None, subnets=None, interval=None, port=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}
-    try:  # 本机自身 IP（接口枚举，尽力而为；无 hostname -I 的平台跳过）
-        import subprocess
-        out = subprocess.run(["hostname", "-I"], capture_output=True, text=True,
-                             timeout=3).stdout or ""
-        self_ips.update(p for p in out.split() if p)
-    except Exception:
-        pass
+    self_ips = {USB_ADB_HOST} | _local_ips()
     ips = []
     for cidr in subnets:
         try:
@@ -174,6 +203,35 @@ def _parse_adb_devices(out):
     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 调用。"""
@@ -206,25 +264,72 @@ def scan_once(manual=False):
             # 4. state==device 过滤（排除 unauthorized/offline）
             verified = _parse_adb_devices(_adb("devices")) & candidates
 
-            # 5. 写 pending：新 → 插入；已有 → 更新 last_seen
+            # 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})
+                        {"last_seen": now, "fingerprint": fp})
                 else:
                     db.session.add(PendingDevice(serial=serial, source=source,
-                                                 first_seen=now, last_seen=now))
+                                                 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"新增待连接 {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}
+        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]
@@ -240,6 +345,39 @@ def device_pool_list_configured():
     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 线程。每轮重读配置（开关/周期即时生效）。
@@ -291,6 +429,7 @@ def get_status():
         "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],
@@ -310,20 +449,47 @@ def list_pending():
     with _ctx():
         rows = [p.to_dict() for p in PendingDevice.query.order_by(
             PendingDevice.first_seen.desc()).all()]
-    return [dict(r, online=True) for r in rows if r["serial"] in online]
+    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=""):
+def confirm_pending(serial, name="", fingerprint=""):
     """确认连接：pending 行 → 正式设备池（add_device upsert）→ 删 pending。
 
-    返回 (ok, msg, is_new)。adb_connect + 采型号由 API 层后台线程做。
+    先按指纹尝试**认领**：同一台物理设备换了地址时，把池中旧记录迁到新 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
-        is_new = device_pool.add_device(serial, name=name or "")
+        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

core/device_pool.py

@@ -22,6 +22,16 @@ 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):
@@ -29,13 +39,59 @@ def init_app(app):
     并后台刷新一次设备型号（首次启动/设备更换后型号可能变化）。"""
     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)  # 等服务起来再查
@@ -109,8 +165,132 @@ def list_ready():
     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):
+def add_device(serial, name="", note="", enabled=True, fingerprint=""):
     """添加/更新设备（upsert）。返回 True 新增 / False 已存在并更新。"""
     serial = (serial or "").strip()
     if not serial:
@@ -119,16 +299,50 @@ def add_device(serial, name="", note="", enabled=True):
         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,
+                              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():
@@ -137,6 +351,7 @@ def remove_device(serial):
             return False
         db.session.delete(d)
         db.session.commit()
+        refresh_names()
         _log.info(f"设备池删除设备: {serial}")
         return True
 
@@ -194,18 +409,45 @@ def refresh_model(serial, timeout=8):
     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，后台线程调用）。返回成功数。"""
+    """批量采集池内在线设备的型号（顺带补齐缺失的设备指纹），并发 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_model, s): s for s in serials}
+        futures = {pool.submit(refresh_info, s): s for s in serials}
         for fut in as_completed(futures):
             try:
-                if fut.result():
+                model, _fp = fut.result()
+                if model:
                     ok += 1
             except Exception:
                 pass

core/device_worker.py

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

core/gesture.py

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

core/humanize.py

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

core/ledger.py

@@ -0,0 +1,551 @@
+"""账号台账：一台设备上登录着哪些账号。
+
+**它解决什么**（用户场景）：一台手机登好几个抖音号、十几台手机四五十个号，
+账号信息散在一张电子表格里 —— 换 IP、加号、想查"这台登的是哪几个号"都得翻表。
+台账落进平台后有三个月牙：
+
+  1. web「账号」页 —— 列表 / 增删改 / **从表格粘贴导入**（`web/devices_api.py` 的 `/api/ledger*`）
+  2. 任务的「条件判断」取号 —— `if_el` 的 `cmp_source=device|all|group`
+     （比对运算符用「包含」时，纯号 `35377983067` 能匹配元素原文 `抖音号：35377983067`）
+  3. 手机端 Agent 的「身份大字页」 —— 平台推 `accounts_b64`（`doc/DEVICE_AGENT.md` §5.2）
+
+⚠ **台账里的抖音号是纯号，绝不能拿去当去重身份**：
+`done_mark.identity` 存的是**元素原文**、逐字算 key，格式不一致（`35377983067`
+vs `抖音号：35377983067`）会让去重**静默失效**。取号只用于条件判断的比对值。
+
+DB 访问自建 app context（照 `core/dedup.py`），调用方（任务线程 / Web 线程）不用关心。
+"""
+import re
+import time
+import uuid
+
+from core.logger import get_logger
+from core.models import db, Device, DeviceAccount, DeviceGroup
+
+_log = get_logger("core.ledger")
+
+# 可编辑字段（接口 / 导入 / 前端共用一份清单，避免某处漏字段）
+FIELDS = ("device_name", "phone", "nickname", "douyin_id", "registered_at",
+          "sim_in_device", "can_post_video", "bio", "note")
+# 这两列是布尔（"空=否"）
+BOOL_FIELDS = ("sim_in_device", "can_post_video")
+
+# 粘贴导入：表头列名 → 字段（允许乱序/缺列/多列；认不出的列忽略）
+HEADER_ALIASES = {
+    "device_name": ("设备号", "设备", "设备名", "机器", "机型"),
+    "phone": ("手机号", "手机", "号码", "手机号码"),
+    "nickname": ("账号名称", "账号名", "昵称", "账号", "名称"),
+    "douyin_id": ("抖音号", "抖音", "抖音id", "douyin"),
+    "registered_at": ("注册时间", "注册日期", "注册"),
+    "sim_in_device": ("卡在机内", "卡在机", "卡在", "机内"),
+    "can_post_video": ("可发视频", "可发", "发视频"),
+    "bio": ("简介", "签名", "个人简介"),
+    "note": ("备注", "说明"),
+}
+# 没有表头时按这个顺序解析（= 用户表格的列顺序，界面上要写明）
+DEFAULT_ORDER = FIELDS
+
+_TRUE_WORDS = ("是", "有", "对", "在", "✔", "√", "✓", "1", "true", "y", "yes", "t")
+_FALSE_WORDS = ("否", "无", "没有", "不在", "不", "0", "false", "n", "no", "f", "")
+# 抖音号形态：纯数字。不拦（少数号可能带字母），只在导入结果里留痕 ——
+# 候选值一旦是错的，任务会"正常跑完但永远不命中"，最难查
+_DOUYIN_RE = re.compile(r"^\d{6,20}$")
+
+_app = None
+
+
+def init_app(app):
+    """web_server 启动时调用：绑 app（后台线程/任务线程访问 db 要自推 context）。"""
+    global _app
+    _app = app
+
+
+def _ctx():
+    if _app is None:
+        raise RuntimeError("ledger 未关联 Flask app（web_server 启动时调用 init_app）")
+    return _app.app_context()
+
+
+def _now():
+    return time.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _norm_bool(v):
+    """是/否 → (True/False, 是否认得)。认不出的按"否"处理，但**留痕**。"""
+    if isinstance(v, bool):
+        return v, True
+    s = str(v or "").strip().lower()
+    if s in _TRUE_WORDS:
+        return True, True
+    if s in _FALSE_WORDS:
+        return False, True
+    return False, False
+
+
+def _clean(fields):
+    """把接口来的字段清洗成可落库的值。只处理传进来的键。返回 (values, error)。"""
+    out = {}
+    for k in FIELDS:
+        if k not in (fields or {}):
+            continue
+        v = fields.get(k)
+        out[k] = _norm_bool(v)[0] if k in BOOL_FIELDS else str(v or "").strip()
+    if "device_name" in out and not out["device_name"]:
+        return {}, "设备号不能为空"
+    if "douyin_id" in out and not out["douyin_id"]:
+        return {}, "抖音号不能为空"
+    return out, ""
+
+
+# ================== 查 ==================
+def get_by_id(acc_id):
+    """取一条（dict）或 None。
+
+    **跨边界一律返回 dict**：commit 之后 ORM 行的属性会过期，出了 app context
+    再读属性会抛 DetachedInstanceError（接口层 `row.to_dict()` 必炸）。
+    """
+    with _ctx():
+        row = DeviceAccount.query.get(acc_id)
+        return row.to_dict() if row else None
+
+
+def find_by_douyin(douyin_id, exclude_id=""):
+    """按抖音号找已存在的那条（唯一性判据；空号不参与）。返回 (id, 设备号) 或 None。
+
+    只返回两个纯值，同样是为了不让 ORM 行溜出 context。
+    """
+    d = str(douyin_id or "").strip()
+    if not d:
+        return None
+    with _ctx():
+        q = DeviceAccount.query.filter(DeviceAccount.douyin_id == d)
+        if exclude_id:
+            q = q.filter(DeviceAccount.id != exclude_id)
+        row = q.first()
+        return (row.id, row.device_name or "") if row else None
+
+
+def list_accounts(device_name="", q="", limit=500):
+    """列表 + 统计（「账号」页用）。返回 (rows, stats)。"""
+    with _ctx():
+        query = DeviceAccount.query
+        if device_name:
+            query = query.filter(DeviceAccount.device_name == device_name)
+        if q:
+            like = f"%{q.strip()}%"
+            query = query.filter(db.or_(DeviceAccount.douyin_id.like(like),
+                                        DeviceAccount.phone.like(like),
+                                        DeviceAccount.nickname.like(like)))
+        rows = (query.order_by(DeviceAccount.device_name, DeviceAccount.id)
+                .limit(max(1, min(int(limit or 500), 2000))).all())
+        all_rows = DeviceAccount.query.all()
+        stats = {
+            "total": len(all_rows),
+            "devices": len({r.device_name for r in all_rows if r.device_name}),
+            "can_post_video": len([r for r in all_rows if r.can_post_video]),
+            "shown": len(rows),
+        }
+        return [r.to_dict() for r in rows], stats
+
+
+def device_names():
+    """台账里出现过的设备号（筛选下拉用）。"""
+    try:
+        with _ctx():
+            return sorted({r.device_name for r in DeviceAccount.query.all() if r.device_name})
+    except Exception:
+        return []
+
+
+def for_device(serial="", device_name=""):
+    """这台设备的账号。serial 优先，再按设备名（换 IP / 改名都找得到）。
+
+    `serial` 是**录入时的快照**：设备换 IP 后台账里那条还是旧地址，
+    所以两边都查一遍并按抖音号去重。
+    """
+    with _ctx():
+        rows, seen = [], set()
+        if serial:
+            for r in DeviceAccount.query.filter(DeviceAccount.serial == serial).all():
+                rows.append(r)
+                seen.add(r.douyin_id)
+        name = device_name
+        if not name and serial:
+            dev = Device.query.get(serial)
+            name = (dev.name if dev else "") or ""
+        if name:
+            for r in DeviceAccount.query.filter(DeviceAccount.device_name == name).all():
+                if r.douyin_id not in seen:
+                    rows.append(r)
+                    seen.add(r.douyin_id)
+        return [r.to_dict() for r in rows]
+
+
+def resolve_device(serial="", device_name=""):
+    """serial/设备名 → (设备号, 账号行, 说明)。
+
+    "本机是哪台设备"这条链只在这一个地方定义，任务侧和设备端都走它 ——
+    两套规则必然分叉（那会变成"任务取到 3 个号、页面显示 0 个号"这种鬼故事）。
+    """
+    name = (device_name or "").strip()
+    if not name and serial:
+        with _ctx():
+            dev = Device.query.get(serial)
+            name = (dev.name if dev else "") or ""
+    rows = for_device(serial=serial, device_name=name)
+    # 兜底：台账里有人把"设备号"直接填成地址（手填习惯），按 serial 再认一次
+    if not rows and serial:
+        with _ctx():
+            hit = DeviceAccount.query.filter(DeviceAccount.device_name == serial).all()
+            if hit:
+                name = serial
+                rows = [r.to_dict() for r in hit]
+    if not rows:
+        note = (f"设备名『{name}』在台账里没有账号" if name
+                else f"设备 {serial or '（无地址）'} 认不出设备名（设备池里没登记或还没刷新）")
+        if serial and name:
+            note += f"，地址 {serial} 也没对上台账"
+        return name, [], note
+    return name, rows, f"设备『{name}』登记 {len(rows)} 个号"
+
+
+def serial_of(device_name):
+    """设备名 → **当前**地址（拿不到返回空串）。
+
+    ⚠ 为什么不能直接用台账/计划行里的 `serial` 快照：设备地址会变（换 IP、重连）。
+    快照是"录入时"的值，久了就是错的 —— 要下发操作（发布视频等）时必须现查。
+    优先设备池的**内存快照**（零 DB、已经是刷新过的），再退回 DB。
+    """
+    name = (device_name or "").strip()
+    if not name:
+        return ""
+    try:
+        from core import device_pool
+        for d in device_pool.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 douyin_ids(scope, serial="", device_name="", group=""):
+    """按范围取抖音号（任务「条件判断」取号用）。返回 (去重后的纯号列表, 说明)。
+
+    说明是给日志/步骤明细看的**人话解释** —— 取不到号时它是唯一线索
+    （取不到候选值的后果是"这一步永远不命中"，但任务本身会正常跑完）。
+    scope: `device`=本机台账 / `all`=全部 / `group`=某设备分组 / 其他=不取
+    """
+    scope = (scope or "").strip()
+    if scope in ("", "manual", "none"):
+        return [], ""
+    try:
+        with _ctx():
+            if scope == "device":
+                _, rows, note = resolve_device(serial=serial, device_name=device_name)
+                return _uniq([r.get("douyin_id") for r in rows]), note
+            if scope == "all":
+                ids = _uniq([r.douyin_id for r in DeviceAccount.query.all()])
+                return ids, f"全部台账共 {len(ids)} 个号"
+            if scope == "group":
+                names = _device_names_of_group(group)
+                if not names:
+                    return [], f"设备分组『{group}』没有设备（或分组不存在）"
+                rows = DeviceAccount.query.filter(
+                    DeviceAccount.device_name.in_(list(names))).all()
+                ids = _uniq([r.douyin_id for r in rows])
+                return ids, f"设备分组『{group}』（{len(names)} 台设备）共 {len(ids)} 个号"
+            return [], f"未知的取号范围 {scope!r}"
+    except Exception as e:
+        # 取号失败绝不拦住任务：返回空，由调用方回落到手填值
+        _log.warning(f"台账取号失败（回落手填值）: {e}")
+        return [], f"台账取号失败: {e}"
+
+
+def _uniq(ids):
+    out, seen = [], set()
+    for i in ids or []:
+        s = str(i or "").strip()
+        if s and s not in seen:
+            seen.add(s)
+            out.append(s)
+    return out
+
+
+def _device_names_of_group(group_name):
+    """设备分组 → 设备名集合（分组里存的是 serial，这里换成台账里的设备号）。"""
+    g = DeviceGroup.query.filter(DeviceGroup.name == (group_name or "").strip()).first()
+    if not g:
+        return set()
+    serials = g.get_serials() or []
+    if not serials:
+        return set()
+    devs = Device.query.filter(Device.serial.in_(list(serials))).all()
+    return {d.name for d in devs if d.name}
+
+
+def counts_by_device():
+    """{设备名: 号数}（设备池显示"这台几个号"用，一次拿全避免 N 次请求）。"""
+    try:
+        with _ctx():
+            out = {}
+            for r in DeviceAccount.query.all():
+                if r.device_name:
+                    out[r.device_name] = out.get(r.device_name, 0) + 1
+            return out
+    except Exception as e:
+        _log.warning(f"台账统计失败: {e}")
+        return {}
+
+
+def by_device():
+    """{设备名: {count, accounts[]}}（设备维度查看弹窗用）。"""
+    groups = {}
+    try:
+        with _ctx():
+            for r in DeviceAccount.query.order_by(DeviceAccount.douyin_id).all():
+                g = groups.setdefault(r.device_name or "", {"count": 0, "accounts": []})
+                g["count"] += 1
+                g["accounts"].append(r.to_dict())
+    except Exception as e:
+        _log.warning(f"台账按设备分组失败: {e}")
+    return groups
+
+
+def agent_accounts(serial="", device_name="", limit=50, include_phone=False):
+    """设备端 Agent 的账号块（身份大字页用）。
+
+    · **默认不带手机号**：大字页是放在机器旁的公开屏幕，手机号不该默认上屏
+    · 超量**按整条丢**（`truncated=True`），绝不按字节切 —— 切了就是坏 JSON，
+      设备端只能整块丢掉
+    · 任何异常都返回空块（不是抛）：台账坏了不能把"显示身份"这个动作弄坏
+    """
+    try:
+        name, rows, note = resolve_device(serial=serial, device_name=device_name)
+        out = []
+        for r in rows[:max(1, int(limit or 50))]:
+            item = {"name": r.get("nickname") or "", "douyin_id": r.get("douyin_id") or "",
+                    "device_name": r.get("device_name") or "", "device_no": name,
+                    "sim_in_device": bool(r.get("sim_in_device")),
+                    "can_post_video": bool(r.get("can_post_video"))}
+            if include_phone:
+                item["phone"] = r.get("phone") or ""
+            out.append(item)
+        return {"v": 1, "total": len(rows), "shown": len(out),
+                "truncated": len(out) < len(rows), "accounts": out, "note": note}
+    except Exception as e:
+        _log.warning(f"设备端账号块生成失败: {e}")
+        return {"v": 1, "total": 0, "shown": 0, "truncated": False, "accounts": [],
+                "note": f"读取失败: {e}"}
+
+
+# ================== 增 / 改 / 删 ==================
+def add(fields):
+    """新增一条。返回 (dict, error)。"""
+    values, err = _clean(fields)
+    if err:
+        return None, err
+    if not values.get("device_name"):
+        return None, "设备号不能为空"
+    if not values.get("douyin_id"):
+        return None, "抖音号不能为空"
+    # try 必须在 `with _ctx()` 里面：否则 rollback 自己会在 context 外抛
+    # RuntimeError，把真正的错误盖掉（这条踩过一次，别挪出去）
+    with _ctx():
+        try:
+            if find_by_douyin(values["douyin_id"]):
+                return None, f"抖音号 {values['douyin_id']} 已在台账里（一个号只能有一条）"
+            row = DeviceAccount(id=uuid.uuid4().hex[:8], created_at=_now(), updated_at=_now())
+            for k in FIELDS:
+                # 没传的布尔列必须是 False，不能是 ""（Boolean 列收到空串会直接报
+                # TypeError: Not a boolean value，整条插不进去）
+                setattr(row, k, values.get(k, False if k in BOOL_FIELDS else ""))
+            _fill_serial(row)
+            db.session.add(row)
+            db.session.commit()
+            _log.info(f"账号台账新增：{row.device_name} / {row.nickname} / {row.douyin_id}")
+            return row.to_dict(), ""       # 出 context 前转成纯值
+        except Exception as e:
+            db.session.rollback()
+            return None, f"保存失败: {e}"
+
+
+def update(acc_id, fields):
+    """改一条（只改传进来的键）。返回 (dict, error)。"""
+    with _ctx():
+        try:
+            row = DeviceAccount.query.get(acc_id)
+            if not row:
+                return None, "记录不存在"
+            values, err = _clean(fields)
+            if err:
+                return None, err
+            new_id = values.get("douyin_id", row.douyin_id)
+            dup = find_by_douyin(new_id, exclude_id=acc_id)
+            if dup:
+                return None, f"抖音号 {new_id} 已被 {dup[1]} 占用（一个号只能有一条）"
+            for k, v in values.items():
+                setattr(row, k, v)
+            row.updated_at = _now()
+            _fill_serial(row)
+            db.session.commit()
+            return row.to_dict(), ""
+        except Exception as e:
+            db.session.rollback()
+            return None, f"保存失败: {e}"
+
+
+def delete(acc_id):
+    """删一条（删掉之后任务就取不到这个号了）。"""
+    with _ctx():
+        try:
+            row = DeviceAccount.query.get(acc_id)
+            if not row:
+                return False
+            db.session.delete(row)
+            db.session.commit()
+            _log.info(f"账号台账删除：{row.device_name} / {row.nickname} / {row.douyin_id}")
+            return True
+        except Exception as e:
+            db.session.rollback()
+            _log.warning(f"账号台账删除失败: {e}")
+            return False
+
+
+def _fill_serial(row):
+    """按设备名补 serial 快照（台账只填设备号时，自动关联设备池那条）。"""
+    if row.serial:
+        return
+    if not row.device_name:
+        return
+    dev = Device.query.filter(Device.name == row.device_name).first()
+    if dev:
+        row.serial = dev.serial
+
+
+# ================== 粘贴导入 ==================
+def parse_paste(text, delimiter="\t"):
+    """把粘贴的表格文本解析成台账行。返回 (rows, errors)。
+
+    rows 里每行是 `{"_line": 3, "device_name": "...", ..., "_warns": [...]}`
+    （`_line` = 粘贴文本里的行号，界面把错误指回原行；`_warns` 是"能导但要注意"的提示）。
+    errors 是 `[{"line": 3, "reason": "..."}]`（这些行会被跳过）。
+
+    分隔符默认 Tab（Excel 直接粘贴就是 Tab）。**不做"多个空格当分隔"**——
+    账号名里本来就有双空格（实测 `有牛奶面包  你吃吗？`），按空格切会切坏。
+    带表头时按列名映射（顺序随意、缺列留空）；不带表头则按 DEFAULT_ORDER 的固定顺序。
+    """
+    if delimiter not in ("\t", "|", ","):
+        delimiter = "\t"
+    text = (text or "").replace("\r\n", "\n").replace("\r", "\n")
+    lines = [(i + 1, ln) for i, ln in enumerate(text.split("\n")) if ln.strip()]
+    if not lines:
+        return [], [{"line": 0, "reason": "没有可解析的内容"}]
+
+    first_cells = [c.strip() for c in lines[0][1].split(delimiter)]
+    mapped = _map_header(first_cells)
+    if mapped:
+        body = lines[1:]
+    else:
+        mapped = {name: i for i, name in enumerate(DEFAULT_ORDER)}
+        body = lines
+    if not body:
+        return [], [{"line": lines[0][0], "reason": "只有表头，没有数据行"}]
+
+    rows, errors = [], []
+    for lineno, line in body:
+        cells = line.split(delimiter)
+        row = {"_line": lineno, "_warns": []}
+        for f in FIELDS:                       # 先把所有字段填上，缺列留空
+            row[f] = ""
+        for field, idx in mapped.items():
+            if field in FIELDS:
+                row[field] = cells[idx].strip() if idx < len(cells) else ""
+        if not row["device_name"] and not row["douyin_id"]:
+            errors.append({"line": lineno, "reason": "设备号与抖音号都是空的，已跳过"})
+            continue
+        if not row["device_name"]:
+            errors.append({"line": lineno, "reason": "缺设备号，已跳过"})
+            continue
+        if not row["douyin_id"]:
+            errors.append({"line": lineno, "reason": "缺抖音号，已跳过"})
+            continue
+        for f in BOOL_FIELDS:
+            raw = row[f]
+            val, known = _norm_bool(raw)
+            row[f] = val
+            if not known:
+                row["_warns"].append(f"『{raw}』认不出，按「否」处理")
+        if not _DOUYIN_RE.match(row["douyin_id"]):
+            row["_warns"].append(f"抖音号『{row['douyin_id']}』不是纯数字 —— "
+                                 f"任务比对时可能匹配不上")
+        rows.append(row)
+    return rows, errors
+
+
+def _map_header(cells):
+    """列名 → 列下标（认不出"设备号+抖音号"时返回 {}，按固定顺序解析）。"""
+    mapping = {}
+    for idx, cell in enumerate(cells):
+        c = re.sub(r"\s+", "", cell or "")
+        if not c:
+            continue
+        for field, aliases in HEADER_ALIASES.items():
+            if field in mapping:
+                continue
+            if any(c == a or c.startswith(a) for a in aliases):
+                mapping[field] = idx
+                break
+    if "device_name" in mapping and "douyin_id" in mapping:
+        return mapping
+    return {}
+
+
+def import_rows(rows, mode="skip", dry_run=False):
+    """把解析好的行落库（或只预览）。返回逐行结果 + 汇总。
+
+    mode=`skip`（默认）：抖音号已在台账里 → 跳过（不动现有那条）
+    mode=`overwrite`：抖音号已在台账里 → 用粘贴的这行**整行覆盖**它
+    dry_run=True：只判重、不写库（界面上"先预览后导入"）
+    """
+    mode = mode if mode in ("skip", "overwrite") else "skip"
+    counts = {"total": 0, "added": 0, "updated": 0, "skipped": 0, "failed": 0}
+    out_rows = []
+    for row in rows or []:
+        line = row.get("_line", 0)
+        fields = {k: v for k, v in row.items() if k not in ("_line", "_warns")}
+        counts["total"] += 1
+        existing = find_by_douyin(fields.get("douyin_id"))
+        item = {"line": line, "device_name": fields.get("device_name", ""),
+                "douyin_id": fields.get("douyin_id", ""),
+                "nickname": fields.get("nickname", ""),
+                "warns": list(row.get("_warns") or []), "error": ""}
+        if existing:
+            if mode == "overwrite":
+                item["action"] = "update"
+                if not dry_run:
+                    _, err = update(existing[0], fields)
+                    if err:
+                        item["action"], item["error"] = "fail", err
+                counts["updated" if item["action"] == "update" else "failed"] += 1
+            else:
+                item["action"] = "skip"
+                item["error"] = f"已存在（{existing[1]}），跳过"
+                counts["skipped"] += 1
+        else:
+            item["action"] = "add"
+            if not dry_run:
+                _, err = add(fields)
+                if err:
+                    item["action"], item["error"] = "fail", err
+            counts["added" if item["action"] == "add" else "failed"] += 1
+        out_rows.append(item)
+    if not dry_run:
+        _log.info(f"账号台账导入：新增 {counts['added']}、覆盖 {counts['updated']}、"
+                  f"跳过 {counts['skipped']}、失败 {counts['failed']}")
+    return {"counts": counts, "rows": out_rows, "mode": mode, "dry_run": bool(dry_run)}

core/logger.py

@@ -16,7 +16,9 @@
 文件按 10MB 滚动，保留 5 个历史文件。
 """
 import os
+import re
 import logging
+from collections import deque
 from logging.handlers import RotatingFileHandler
 
 _LOG_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "logs")
@@ -31,6 +33,8 @@ _MODULE_FILES = {
     "task": "task.log",
     "web": "web.log",
     "action": "action.log",
+    # 通知单独一个文件：排障时"哪条通知发了/失败了/为什么"要能一眼翻到
+    "notify": "notify.log",
 }
 
 _FORMAT = "%(asctime)s [%(levelname)s] [%(name)s] %(message)s"
@@ -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}"

core/models.py

@@ -17,6 +17,7 @@
 import os
 import json
 import hashlib
+import sqlite3
 
 from flask_sqlalchemy import SQLAlchemy
 from flask_login import UserMixin
@@ -31,12 +32,33 @@ _log = get_logger("core.models")
 db = SQLAlchemy()
 
 
+def _long_text():
+    """长文本列：SQLite 用 TEXT，MySQL 用 MEDIUMTEXT。
+
+    裸 TEXT 在 MySQL 只有 64KB（而且是"字节"），AI 会话消息、任务参数这类
+    JSON 文本很容易超；超了在严格模式下直接报错（不是截断）。
+    """
+    from sqlalchemy.dialects.mysql import MEDIUMTEXT
+    return db.Text().with_variant(MEDIUMTEXT(), "mysql")
+
+
+def _DOUBLE():
+    """REAL/DOUBLE：MySQL 的 FLOAT 是单精度，评分这类值会出现 7.8000001 这种尾巴。"""
+    from sqlalchemy.dialects.mysql import DOUBLE
+    return DOUBLE()
+
+
 @event.listens_for(Engine, "connect")
 def _sqlite_pragma(dbapi_connection, connection_record):
     """SQLite 并发写优化：WAL 模式 + 忙等待超时 + 降同步级别。
 
     多 worker 后台线程同时写库（任务参数/分组）时，避免 database is locked。
+
+    注意：这个监听器挂在 Engine 基类上，对**所有方言**的连接都会触发；
+    MySQL 下执行 PRAGMA 会直接报语法错误导致连接失败，所以必须先判类型。
     """
+    if not isinstance(dbapi_connection, sqlite3.Connection):
+        return
     cursor = dbapi_connection.cursor()
     cursor.execute("PRAGMA journal_mode=WAL")
     cursor.execute("PRAGMA busy_timeout=5000")
@@ -128,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
@@ -223,16 +245,20 @@ class Device(db.Model):
     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="") # 添加时间
+    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="")  # 添加时间
+    # 设备指纹（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 ""}
+                "note": self.note or "", "created_at": self.created_at or "",
+                "fingerprint": self.fingerprint or ""}
 
     def __repr__(self):
         return f"<Device {self.serial}>"
@@ -247,74 +273,510 @@ class PendingDevice(db.Model):
     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 ""}
+                "first_seen": self.first_seen or "", "last_seen": self.last_seen or "",
+                "fingerprint": self.fingerprint or ""}
 
 
-# 版本化 schema 迁移：新增结构变更时在此追加 (版本号, 说明, SQL)
-# 版本号单调递增，只执行比当前 schema_version 新的迁移。
+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):
+    """账号台账：一台设备上登录着哪些账号（「账号」页）。
+
+    要解决的问题（用户场景）：一台手机登好几个抖音号、十几台手机四五十个号，
+    账号信息散在一张电子表格里 —— 换 IP、加号、想查"这台登的是哪几个号"都要翻表。
+    这里把台账落进平台：web 能查能改（支持从表格粘贴导入），
+    手机端 Agent 的「身份大字页」顺带显示本机账号，任务的「条件判断」
+    也可以直接从台账取号（不用再把号一个个手写进 cmp_value）。
+
+    ⚠ **`douyin_id` 是纯号（`35377983067`），而元素原文是 `抖音号：35377983067`。**
+    - 当条件判断的**比对值**可以 ✓（运算符用「包含」，纯号是子串）
+    - **绝不能当去重身份** ✗ —— `done_mark.identity` 存的是元素原文、逐字算 key，
+      格式不一致会让去重**静默失效**（见 `core/dedup.py`）。
+
+    `device_name` 是设备号（平台设备名，如 A01）；`serial` 是**录入时的地址快照**，
+    设备换 IP 或改名后，台账靠任一侧都能找回来（见 `core/ledger.for_device`）。
+    同一抖音号不允许两条 —— 唯一性由服务层保证（号可能为空，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` 记录失败发生在哪一步，是这两者互相转换的唯一依据。
+
+    **唯一性**：`(phone, 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)   # → device_account.id（不做外键）
+    phone = db.Column(db.String(32), default="", index=True)        # 配对键（冗余存：账号删了也留痕）
+    device_name = db.Column(db.String(80), default="", index=True)  # 设备号快照（聚合/下发免 join）
+    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="")                          # 文案
+    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="")             # 推到手机上的绝对路径（删它/排查用）
+    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"),
+    )
+
+    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 "", "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 "",
+                "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, "用户权限位：user 表新增 perms 列（JSON 数组，默认空=无业务权限，管理员不受限）",
-     "ALTER TABLE user ADD COLUMN perms TEXT DEFAULT '[]'"),
-    (2, "设备池：device 表（本地设备清单，替代 STF 池）",
-     "CREATE TABLE IF NOT EXISTS device ("
-     "serial VARCHAR(120) PRIMARY KEY,"
-     "name VARCHAR(80) DEFAULT '',"
-     "enabled BOOLEAN DEFAULT 1,"
-     "note TEXT DEFAULT '',"
-     "created_at VARCHAR(20) DEFAULT '')"),
-    (3, "设备池：device 表新增 model 列（型号，在线时自动采集）",
-     "ALTER TABLE device ADD COLUMN model TEXT DEFAULT ''"),
-    (4, "自动发现：pending_device 待连接池表（扫描发现的设备，用户确认后才入正式池）",
-     "CREATE TABLE IF NOT EXISTS pending_device ("
-     "serial VARCHAR(120) PRIMARY KEY,"
-     "source VARCHAR(20) DEFAULT '',"
-     "first_seen VARCHAR(20) DEFAULT '',"
-     "last_seen VARCHAR(20) DEFAULT '')"),
+    (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),
 ]
 
+# 当前 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"),
+)
+
 
 def init_db(app):
     """在 Flask app context 里初始化数据库 + 创建默认管理员。
 
-    web_server 启动时调用。自动迁移旧 groups.json/jobs.json 到 SQLite。
+    web_server 启动时调用。自动迁移旧 groups.json/jobs.json 到数据库。
+
+    顺序：建表（create_all）→ 补列（_sync_columns）→ 版本账本 → 唯一索引 → 管理员/旧 JSON。
+    建表与补列都以模型定义为准，SQLite / MySQL 两种方言自动匹配，不再手写 DDL。
     """
     db.init_app(app)
     with app.app_context():
         db.create_all()
+        _sync_columns()
         _migrate_schema()
+        _ensure_unique_indexes()
         _ensure_default_admin()
         _migrate_old_json()
 
 
-def _migrate_schema():
-    """按 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_default_admin():
     """首次启动创建默认管理员 admin/admin123。"""
     if not User.query.filter_by(username="admin").first():
@@ -373,7 +835,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)

core/notify_events.py

@@ -0,0 +1,240 @@
+"""通知事件目录（**唯一真相**）。
+
+约定：
+- **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.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

core/ocr.py

@@ -69,11 +69,22 @@ def recognize(image):
 def find_on_screen(image, keyword):
     """在截图上查找包含 keyword 的文字。
 
-    返回 (found, center_xy, matched_text)；center_xy 为文字中心像素坐标（可点击），
-    未命中返回 (False, None, "")。
+    返回 (found, center_xy, matched_text)；center_xy 为**关键词**中心像素坐标
+    （可点击），未命中返回 (False, None, "")。
+
+    OCR 一行常含多段文字（如 "医值得推荐#苏州济世璞真…展开"），若直接点整块
+    中心会偏离关键词很远。命中块文本较长时，按关键词在文本中的位置比例估算 x
+    （块内文字近似等宽），y 取块中心——中文场景估算偏差小，点击能落准。
     """
     for r in recognize(image):
-        if keyword in r["text"]:
+        text = r["text"]
+        if keyword in text:
             b = r["box"]
-            return True, ((b[0] + b[2]) // 2, (b[1] + b[3]) // 2), r["text"]
+            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, ""

core/patrol.py

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

core/step_defaults.py

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

core/step_log.py

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

core/system_backup.py

@@ -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)

core/task_draft.py

@@ -0,0 +1,578 @@
+"""AI 建任务的 draft 契约：**校验 + 归一化**（唯一真相）。
+
+## 为什么必须有这个模块
+
+任务执行器对"写错的地方"是**静默跳过**的：未知步骤类型只打一条 warning 继续
+（`tasks/generic/task.py` 的 `_exec_one`），空 `selector_value` 直接 return。
+而 `POST /api/jobs` 只校验 `name` + `task_type`，`params` 完全盲存
+（`web/tasks_api.py`）。两者叠加的后果是：AI（或任何人）交上一条写错的任务，
+**创建成功、运行不报错、但什么都没做**。
+
+所以这里把执行器的每个"静默跳过点"前移成显式 error，在**落库之前**拦住。
+错误文案是给**模型**看的（走 `submit_task` 的返回值回灌，让它逐条改完重提），
+所以每条都要说清"哪个节点的哪个字段、错在哪、应该是什么"。
+
+## 用法
+
+    res = validate_draft(draft, groups=..., pool=..., default_serial="...")
+    # → {"ok": bool, "errors": [...], "warnings": [...], "draft": 归一化后的草稿}
+
+`errors` 非空就是不能落库；`warnings` 只是提醒（前端醒目展示，不拦）。
+
+契约与规则的权威描述见 `doc/AI_TASK_GEN.md`。
+"""
+import re
+
+from core.logger import get_logger
+
+_log = get_logger("core.task_draft")
+
+# ================== 常量（规则的唯一来源） ==================
+
+# 单条任务最多多少个步骤节点（含嵌套），防止模型输出失控/被输出长度截断
+MAX_NODES = 60
+# 嵌套深度上限（执行器 >5 层直接跳过该分支，见 tasks/generic/task.py）
+MAX_DEPTH = 5
+# 选择器值长度上限
+MAX_SELECTOR_LEN = 200
+# 单条 input_text 的候选文案条数
+MAX_TEXTS = 20
+
+# 与编辑器下拉（static/admin/editor.js 的 selector_type 选项）严格同集。
+# 故意不含 textContains —— 下拉里没有它，用户一改就丢。
+SELECTOR_TYPES = ("xpath", "description", "text", "resourceId",
+                  "descriptionContains", "className")
+IF_SELECTOR_TYPES = SELECTOR_TYPES + ("ocr",)
+
+# 按键白名单（u2 的 d.press 支持更多，这里只放"不会把设备弄坏"的那些：
+# 不含 power/camera —— 探索期误按 power 会让设备息屏、任务中途失联）
+KEY_WHITELIST = ("back", "home", "enter", "menu", "recent", "delete",
+                 "volume_up", "volume_down", "search")
+
+DIRECTIONS = ("up", "down", "left", "right")
+LOOP_MODES = ("rounds", "time", "forever")
+SCHEDULE_MODES = ("once", "cron", "cron_stop")
+TARGET_MODES = ("all", "group", "serial")
+
+# 需要选择器的步骤类型（缺 selector_value 时执行器静默跳过）
+NEED_SELECTOR = ("click", "long_click", "wait_el", "swipe_until", "if_el")
+# 需要包名的步骤类型
+NEED_PACKAGE = ("open_app", "stop_app")
+# 需要非空 children 的容器
+NEED_CHILDREN = ("loop", "group")
+
+# 有副作用的动作关键词：命中的步骤在 AI 通道只给 warning（人工复核），不拦
+DESTRUCTIVE_HINTS = ("评论", "发送", "发布", "投稿", "转发", "分享到",
+                     "购买", "下单", "支付", "付款", "删除", "卸载",
+                     "退出登录", "注销", "举报", "拉黑", "清空")
+# 命中上面关键词的步骤，触发概率被压到这个值（可人工改回）
+SAFE_PROBABILITY = 30
+
+_PKG_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$")
+_HHMM_RE = re.compile(r"^([01]\d|2[0-3]):[0-5]\d$")
+# 「序号型」选择器的两种形态：
+#   (//*[@resource-id="x"])[4]  ← 抓取器在语义消歧失败时给的（当前形态）
+#   //*[@resource-id="x"][4]    ← 历史形态（执行器会自动纠正成上面那种）
+# 两者都依赖"同类元素有几个"，界面一变就指到别的元素上，都值得提醒换语义选择器。
+_SEQ_SELECTOR_RE = re.compile(r"^(?:\(\s*//\*\[@[^\]]+\]\s*\)|//\*\[@[^\]]+\])\[\d+\]")
+
+
+def _step_types():
+    """步骤类型 → (label, 默认 params)，直接取自执行器的权威定义。"""
+    from tasks.generic.task import STEP_TYPES
+    return {s["type"]: (s.get("label", s["type"]), dict(s.get("params") or {}))
+            for s in STEP_TYPES}
+
+
+def _is_num(v):
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def _num(params, key, default=None):
+    v = params.get(key, default)
+    return v if _is_num(v) else default
+
+
+# ================== 步骤树校验 ==================
+
+def validate_steps(steps, depth=1, path="steps", errors=None, warnings=None,
+                   types=None, counter=None):
+    """递归校验步骤树，返回 (errors, warnings, 节点总数)。
+
+    每条 error 都带上路径（如 `steps[0].params.children[2]`），模型据此能直接定位。
+    """
+    errors = [] if errors is None else errors
+    warnings = [] if warnings is None else warnings
+    types = _step_types() if types is None else types
+    counter = [0] if counter is None else counter
+
+    if not isinstance(steps, list):
+        errors.append(f"{path}: 必须是数组")
+        return errors, warnings, counter[0]
+
+    for i, step in enumerate(steps):
+        here = f"{path}[{i}]"
+        if not isinstance(step, dict):
+            errors.append(f"{here}: 必须是对象")
+            continue
+        stype = step.get("type")
+        if not stype:
+            errors.append(f"{here}: 缺少 type 字段")
+            continue
+        if stype not in types:
+            errors.append(f"{here}: 未知步骤类型 {stype!r}（可用类型："
+                          f"{'、'.join(types)}）")
+            continue
+        if stype == "click_xy":
+            errors.append(f"{here}: 不允许坐标点击（click_xy）—— 坐标在不同分辨率/"
+                          "设备上必失配，请改用 click + 选择器定位元素")
+            continue
+
+        counter[0] += 1
+        if counter[0] > MAX_NODES:
+            errors.append(f"{here}: 步骤节点总数超过 {MAX_NODES} 个，请精简"
+                          "（去掉冗余的等待/滑动，合并重复结构）")
+            return errors, warnings, counter[0]
+
+        params = step.get("params")
+        if params is None:
+            params = {}
+        if not isinstance(params, dict):
+            errors.append(f"{here}.params: 必须是对象")
+            continue
+
+        # 触发概率（执行器对所有类型通用）
+        prob = params.get("probability")
+        if prob is not None:
+            if not _is_num(prob) or not (0 <= prob <= 100):
+                errors.append(f"{here}.params.probability: 必须是 0~100 的数字"
+                              f"（当前 {prob!r}）")
+
+        # 选择器类步骤（例外：if_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", "device", "all", "group"):
+                errors.append(f"{here}.params.cmp_source: 不支持的候选值来源 {cmp_src!r}"
+                              f"（可用：空/manual/device/all/group）")
+            if cmp_src == "group" and not (params.get("cmp_group") or "").strip():
+                warnings.append(f"{here}: 候选值来源是「按设备分组」，但没填分组名 —— 取不到号")
+            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 ("device", "all", "group"):
+                    # 候选值来自台账时允许手填留空（台账取号就够）；
+                    # 其余情况仍要求填值，否则永远不命中
+                    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":
+            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

core/task_manager.py

@@ -1,9 +1,9 @@
 """通用任务管理框架：任务类型注册 + 设备分组 + 任务计划 + 定时调度 + 重试 + 持久化。
 
-设计目标：可扩展，未来加非抖音任务只需注册新的 Task 类。
+设计目标：可扩展——新增任务类型只需在 tasks/ 下注册新的 Task 类（见 doc/TASK_DEV.md）。
 
 核心概念：
-  TaskType  — 任务类型（如"抖音养号"），可注册，含默认参数和 worker 工厂
+  TaskType  — 任务类型（如"通用步骤"），可注册，含默认参数和 worker 工厂
   DeviceGroup — 设备分组，持久化到 SQLite（core.models.DeviceGroup）
   TaskJob   — 任务计划（类型+目标+参数+调度+重试），持久化到 SQLite（core.models.TaskJob）
   TaskManager — 统管调度器、分组、任务、运行实例、状态
@@ -21,6 +21,7 @@ import json
 import time
 import uuid
 import threading
+from collections import Counter
 from datetime import datetime
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
@@ -31,6 +32,8 @@ from config import DATA_DIR
 from core.logger import get_logger
 from core.models import db, DeviceGroup as GroupRow, TaskJob as JobRow
 from core import device_pool
+from core import device_battery
+from core import notifier
 from .adb_helper import get_foreground_app, get_foreground_app_remote
 from .device_worker import (
     DeviceOfflineError,
@@ -47,6 +50,81 @@ _log = get_logger("core.tm")
 _START_STAGGER_SEC = 0.2
 
 
+def _dev_model(serial, tracker=None):
+    """设备型号：优先用批次开始时查好的设备池快照，退回 worker 上报的状态表。
+
+    为什么优先快照：worker 每次启动都会 `_update_status(model=…)`，但那次采集
+    （`d.info()`）可能超时/失败 → 型号是空；而设备池的型号是后台统一采集的、
+    稳定得多。快照还有个好处：不查库（通知路径上不碰 DB）。
+    """
+    if tracker is not None:
+        m = (tracker.models or {}).get(serial)
+        if m:
+            return m
+    with _WORKERS_LOCK:
+        return _WORKERS.get(serial, {}).get("model") or ""
+
+
+def _dev_fail_note(serial, dname, tracker=None):
+    """失败设备的一行说明：`名字（型号）：原因`——批次汇总里直接列出来。
+
+    型号同上用快照；原因取 worker 上报的 last_error（刚写进去，还在）。
+    """
+    with _WORKERS_LOCK:
+        err = _WORKERS.get(serial, {}).get("last_error") or ""
+    cause = err.strip().splitlines()[0] if err.strip() else ""
+    model = _dev_model(serial, tracker)
+    head = f"{dname}（{model}）" if model else str(dname)
+    return f"{head}：{cause[:60]}" if cause else head
+
+
+class _BatchTracker:
+    """一次任务批次的收尾统计：**所有设备都出结果**后发一条 `task.batch.finished`。
+
+    为什么不每台设备各发一条"批次结束"：100 台设备就是 100 条刷屏。这里只计数，
+    归零那一刻发一条汇总（锁外发，见 done()）。
+
+    每台设备的结果由 `_run_with_retry` 的 finally 调一次 `done(serial, outcome)`——
+    放在 finally 里是为了保证"任何一个 return 分支都会被计数一次"，不会漏也不会重。
+    """
+
+    def __init__(self, job, total, names=None, models=None):
+        self.job = job
+        self.total = total
+        # serial -> 设备名（通知里显示名字而不是裸地址）；取不到就是空
+        self.names = dict(names or {})
+        # serial -> 型号（批次开始时从设备池查一次带下来，通知里直接用）
+        self.models = dict(models or {})
+        self._lock = threading.Lock()
+        self._left = total
+        self._stats = Counter()
+        self._failed = []          # 失败设备明细（型号 + 原因），汇总里有失败时列出
+        self._t0 = time.time()
+
+    def done(self, serial, outcome="failed", detail=""):
+        """登记一台设备的结果（success/failed/stopped/skipped）。
+
+        detail 只对 failed 有意义（"设备名（型号）：原因"），最多留 5 条 ——
+        批次汇总里列出来，用户不用再去翻日志。
+        """
+        with self._lock:
+            self._left -= 1
+            self._stats[outcome] += 1
+            if outcome == "failed" and detail and len(self._failed) < 5:
+                self._failed.append(detail)
+            left = self._left
+            s = dict(self._stats)
+            fails = list(self._failed)
+        if left > 0:
+            return
+        notifier.notify("task.batch.finished", job_id=self.job.id,
+                        job_name=self.job.name, total=self.total,
+                        success=s.get("success", 0), failed=s.get("failed", 0),
+                        stopped=s.get("stopped", 0), skipped=s.get("skipped", 0),
+                        failed_devices=fails,
+                        duration_s=int(time.time() - self._t0))
+
+
 def _in_run_window(schedule, now=None):
     """是否在当前运行窗口内。
 
@@ -121,7 +199,7 @@ class DeviceGroup:
 class TaskJob:
     """一个任务计划：什么任务、跑哪些设备、什么参数、何时跑、失败重试策略。"""
 
-    def __init__(self, job_id=None, name="", task_type="douyin_nurture",
+    def __init__(self, job_id=None, name="", task_type="generic_steps",
                  target=None, params=None, schedule=None, retry=None, enabled=True):
         self.id = job_id or uuid.uuid4().hex[:8]
         self.name = name
@@ -378,24 +456,22 @@ class TaskManager:
                 for row in GroupRow.query.all():
                     g = DeviceGroup(row.name, row.get_serials(), row.description or "")
                     self.groups[g.name] = g
-                dirty = False  # 标记是否有任务参数需要写回
+                stale = []   # 任务类型已不存在（历史任务类型被删除）的任务
                 for row in JobRow.query.all():
                     j = TaskJob(job_id=row.id, name=row.name, task_type=row.task_type,
                                target=row.get_target(), params=row.get_params(),
                                schedule=row.get_schedule(), retry=row.get_retry(),
                                enabled=row.enabled)
-                    # 数据规整：移除已废弃的 action 配置（如抖音的 comment 已删除）
-                    if j.task_type == "douyin_nurture":
-                        actions = j.params.get("actions", {})
-                        if "comment" in actions:
-                            del actions["comment"]
-                            row.set_params(j.params)
-                            dirty = True
-                            _log.info(f"任务 {j.name}({j.id}): 已移除废弃的 comment 配置")
+                    # 启动时告警：库里留着已删除的任务类型（如 douyin_nurture），
+                    # 这类任务跑不起来也不该静默——提示人工删除或改用现有类型。
+                    # 只告警不改数据（不自动删用户的任务）。
+                    if not get_task_class(j.task_type):
+                        stale.append(j)
                     self.jobs[j.id] = j
-                if dirty:
-                    db.session.commit()
-                    _log.info("已将规整后的任务参数写回数据库")
+                if stale:
+                    _log.warning(
+                        "以下任务的任务类型已不存在，无法执行，请在「任务」页删除或改用现有类型："
+                        + "；".join(f"{j.name}({j.id}, type={j.task_type})" for j in stale))
             _log.info(f"从数据库加载 {len(self.groups)} 个分组, {len(self.jobs)} 个任务")
         except Exception as e:
             _log.error(f"从数据库加载失败: {e}")
@@ -451,18 +527,55 @@ class TaskManager:
         self._save_groups()
         return g
 
+    def sync_device_serial(self, old_serial, new_serial):
+        """设备换地址（认领/迁址）后，把分组与任务里的引用改到新地址。
+
+        由 device_pool 的迁址回调触发（见 device_pool.set_move_hook）。
+        **必须同时改内存与库**：调度用的是内存里的 groups/jobs，只改库不重启不生效
+        —— 表现就是"分组里少了一台、指定设备的任务仍跑向不存在的地址"。
+
+        返回被更新的引用条数。
+        """
+        if not old_serial or not new_serial or old_serial == new_serial:
+            return 0
+        n = 0
+        for name, g in list(self.groups.items()):
+            try:
+                serials = list(g.serials or [])
+            except Exception:
+                continue
+            if old_serial in serials:
+                self.update_group(name, serials=[new_serial if s == old_serial else s
+                                                 for s in serials])
+                n += 1
+                _log.info(f"设备换地址: 分组『{name}』的 {old_serial} → {new_serial}")
+        for job_id, job in list(self.jobs.items()):
+            try:
+                target = dict(job.target or {})
+            except Exception:
+                continue
+            if target.get("mode") == "serial" and target.get("serial") == old_serial:
+                target["serial"] = new_serial
+                self.update_job(job_id, target=target)
+                n += 1
+                _log.info(f"设备换地址: 任务『{job.name}』目标 → {new_serial}")
+        return n
+
     def delete_group(self, name):
+        removed = False
         if name in self.groups:
             del self.groups[name]
             self._save_groups()
-            # 同上：显式删数据库行，避免删除的分组重启后复活
-            with self._db():
-                row = GroupRow.query.filter_by(name=name).first()
-                if row:
-                    db.session.delete(row)
-                    db.session.commit()
-            return True
-        return False
+            removed = True
+        # 无论内存里有没有都尝试删库行：内存与库不一致时（手工插行、上次异常退出、
+        # 上个版本漏删）也能删干净，避免"删不掉的分组"
+        with self._db():
+            row = GroupRow.query.filter_by(name=name).first()
+            if row:
+                db.session.delete(row)
+                db.session.commit()
+                removed = True
+        return removed
 
     # ---- 任务计划管理 ----
     def add_job(self, name, task_type, target, params, schedule, retry, enabled=True):
@@ -492,18 +605,20 @@ class TaskManager:
 
     def delete_job(self, job_id):
         self._remove_cron(job_id)
+        removed = False
         if job_id in self.jobs:
             del self.jobs[job_id]
             self._save_jobs()
-            # _save_jobs 只做 upsert 不会删行：必须显式删数据库行，
-            # 否则删除的任务重启后会从数据库重新加载回来
-            with self._db():
-                row = JobRow.query.get(job_id)
-                if row:
-                    db.session.delete(row)
-                    db.session.commit()
-            return True
-        return False
+            removed = True
+        # _save_jobs 只做 upsert 不会删行：必须显式删库行，否则删除的任务重启会复活。
+        # 内存里没有（手工插行/上次异常退出）时也要删——否则会出现"删不掉的任务"
+        with self._db():
+            row = JobRow.query.get(job_id)
+            if row:
+                db.session.delete(row)
+                db.session.commit()
+                removed = True
+        return removed
 
     def toggle_job(self, job_id, enabled):
         job = self.jobs.get(job_id)
@@ -596,6 +711,8 @@ class TaskManager:
                 w.stop()
                 stopped.append(serial)
         _log.info(f"定时停止 {job.name}({job.id}): 停止 {len(stopped)} 台设备 {stopped}")
+        notifier.notify("task.cron.stopped", job_id=job.id, job_name=job.name,
+                        stopped_count=len(stopped), serials=stopped[:10])
 
     def next_run_of(self, job):
         """任务下次真正执行的时间（考虑运行窗口）。停用/无 cron 返回 None。"""
@@ -608,6 +725,11 @@ class TaskManager:
         job = self.jobs.get(job_id)
         if not job:
             return {"ok": False, "error": "任务不存在"}
+        # 任务类型已不存在（历史类型被删除）→ 明确报错，别只返回"已触发"然后线程里静默失败
+        if not get_task_class(job.task_type):
+            return {"ok": False, "error":
+                    f"任务类型 {job.task_type} 已不存在（该类型已被删除），"
+                    f"请删除此任务或改用现有类型"}
         # 在独立线程跑，不阻塞调用方
         t = threading.Thread(target=self._run_job, args=(job,), daemon=True)
         t.start()
@@ -622,23 +744,43 @@ class TaskManager:
         serials = job.resolve_serials(self)
         if not serials:
             _log.warning(f"任务 {job.name} 无可用设备")
+            notifier.notify("task.batch.no_device", job_id=job.id, job_name=job.name,
+                            target=job.target)
             return
         task_cls = get_task_class(job.task_type)
         if not task_cls:
             _log.error(f"未知任务类型: {job.task_type}")
+            notifier.notify("task.batch.unknown_type", job_id=job.id, job_name=job.name,
+                            task_type=job.task_type)
             return
         task = task_cls()
         max_attempts = max(1, job.retry.get("max_attempts", 1))
         delay = job.retry.get("delay", 60)
 
+        notifier.notify("task.batch.started", job_id=job.id, job_name=job.name,
+                        task_type=job.task_type, device_count=len(serials),
+                        serials_preview=serials[:5])
+        # 批次收尾统计：所有设备都出结果后发一条汇总（见 _BatchTracker）
+        # 设备名一次查好带下去（worker 线程里没有 app context，查库要显式包 context）
+        names, models = {}, {}
+        try:
+            with self._db():
+                rows = device_pool.list_devices()
+            names = {d["serial"]: (d.get("name") or "") for d in rows}
+            models = {d["serial"]: (d.get("model") or "") for d in rows}
+        except Exception as e:
+            _log.warning(f"读取设备名/型号失败（通知里将显示地址）: {e}")
+        tracker = _BatchTracker(job, len(serials), names, models)
+
         for idx, serial in enumerate(serials):
             # 每台设备一个重试循环线程，互不影响；错峰延迟在各自线程内等待
             t = threading.Thread(target=self._run_with_retry,
                                  args=(task, serial, job, max_attempts, delay,
-                                       idx * _START_STAGGER_SEC), daemon=True)
+                                       idx * _START_STAGGER_SEC, tracker), daemon=True)
             t.start()
 
-    def _run_with_retry(self, task, serial, job, max_attempts, delay, start_delay=0):
+    def _run_with_retry(self, task, serial, job, max_attempts, delay, start_delay=0,
+                        tracker=None):
         """单设备任务执行 + 重试。
 
         异常分类：
@@ -649,36 +791,58 @@ class TaskManager:
         # 错峰启动：在各自线程内等待，分摊批量启动的连接/占用压力
         if start_delay > 0:
             time.sleep(start_delay)
+        # 设备名（通知里显示"设备：A08"而不是裸地址）
+        dname = (tracker.names.get(serial) if tracker is not None else "") or serial
         # 被抢占的原任务 id（抢占结束后归还）——必须在循环外：
         # 重试时若重置为 None，finally 归还逻辑会丢失信息，被抢占任务永不恢复
         preempted_job = None
+        # 本台设备的结果（供批次统计与通知用）。默认 "failed"：走到重试耗尽就是失败；
+        # 各提前 return 的分支会覆盖它。**在 finally 里统一上报**，保证不漏不重。
+        outcome = "failed"
         try:
             for attempt in range(1, max_attempts + 1):
                 # 用户已请求停止 → 不再启动新 attempt
+                stopped_by_user = False
                 with self._lock:
                     if serial in self._stop_requested:
                         _log.info(f"{serial} 用户已请求停止，取消重试 (job={job.name})")
-                        return
+                        stopped_by_user = True
+                if stopped_by_user:
+                    outcome = "stopped"
+                    notifier.notify("task.device.stopped", serial=serial, device_name=dname,
+                                    job_id=job.id, job_name=job.name, attempt=attempt,
+                                    phase="start")
+                    return
                 # 同一 serial 同时只能一个 worker；不同任务可配置抢占
                 preempt = False
+                skip_reason = ""
                 with self._lock:
                     if serial in self._running:
                         cur = self._running[serial]
                         if cur.get("job_id") == job.id:
                             # 同一任务重复触发：跳过（原行为）
                             _log.warning(f"{serial} 已有任务在跑，跳过 (job={job.name})")
-                            return
-                        if not job.params.get("preempt"):
+                            skip_reason = "同一任务已在运行"
+                        elif not job.params.get("preempt"):
                             # 不同任务且本任务未开启抢占：跳过
                             _log.warning(f"{serial} 已有任务在跑，跳过 (job={job.name})")
-                            return
-                        preempt = True
-                        if not preempted_job:
-                            preempted_job = cur.get("job_id")
+                            skip_reason = "设备被其他任务占用"
+                        else:
+                            preempt = True
+                            if not preempted_job:
+                                preempted_job = cur.get("job_id")
+                if skip_reason:
+                    outcome = "skipped"
+                    return
                 if preempt:
                     # 抢占：锁外停止该设备上的其他任务（stop_device 内部拿同一把锁，
                     # 在锁内调用会死锁！），等其释放后接管
                     _log.warning(f"{serial} 抢占：停止任务 {preempted_job} 后执行 {job.name}")
+                    notifier.notify("task.device.preempted", serial=serial, device_name=dname,
+                                    job_id=job.id, job_name=job.name,
+                                    preempted_job_id=preempted_job,
+                                    preempted_job_name=(self.jobs.get(preempted_job).name
+                                                        if self.jobs.get(preempted_job) else ""))
                     self.stop_device(serial)
                     deadline = time.time() + 30
                     while time.time() < deadline:
@@ -688,6 +852,10 @@ class TaskManager:
                         time.sleep(0.5)
                     else:
                         _log.warning(f"{serial} 抢占超时（旧任务 30s 未退出），跳过 (job={job.name})")
+                        outcome = "skipped"
+                        notifier.notify("task.device.preempt_timeout", serial=serial,
+                                        device_name=dname, job_id=job.id, job_name=job.name,
+                                        preempted_job_id=preempted_job)
                         return
                 with self._lock:
                     self._running[serial] = {"job_id": job.id, "started_at": time.time(),
@@ -697,8 +865,14 @@ class TaskManager:
                                max_attempts=max_attempts)
 
                 worker = None
+                t_attempt = time.time()          # 单次 attempt 耗时（通知里带）
+                # 本次运行的上下文：步骤明细按 run_id 归组，把同一设备同一次尝试
+                # 执行的步骤串起来（重试会生成新的 run_id，两次尝试不混在一起）
+                run_ctx = {"run_id": uuid.uuid4().hex[:12], "job_id": job.id,
+                           "job_name": job.name, "device_name": dname,
+                           "attempt": attempt}
                 try:
-                    worker = task.create_worker(serial, job.params)
+                    worker = task.create_worker(serial, job.params, ctx=run_ctx)
                     with self._lock:
                         self._running[serial]["worker"] = worker
                     _log.info(f"{serial} 开始任务 {job.name} (第{attempt}/{max_attempts}次)")
@@ -714,12 +888,40 @@ class TaskManager:
                     _update_status(serial, task_job="")
                     if st == "done":
                         _log.info(f"{serial} 任务 {job.name} 成功完成")
+                        outcome = "success"
+                        # 单设备成功：**只在"这一批本来就只有一台设备"时发**。
+                        # 多设备批次里逐台报成功没有信息量（批次汇总里已有成功台数），
+                        # 13 台就是 13 条刷屏；失败仍然逐台发——那是少数且要知道是哪台。
+                        if tracker is None or tracker.total <= 1:
+                            notifier.notify("task.device.success", serial=serial,
+                                            device_name=dname,
+                                            model=_dev_model(serial, tracker),
+                                            job_id=job.id, job_name=job.name,
+                                            attempt=attempt,
+                                            duration_s=int(time.time() - t_attempt))
                         return
                     # 用户请求停止（无论 attempt 第几次、status 是什么）→ 不重试
                     with self._lock:
                         if serial in self._stop_requested:
                             _log.info(f"{serial} 用户已请求停止，不再重试 (job={job.name})")
+                            outcome = "stopped"
+                            notifier.notify("task.device.stopped", serial=serial,
+                                            device_name=dname, job_id=job.id,
+                                            job_name=job.name, attempt=attempt,
+                                            phase="after")
                             return
+                    if worker is not None and worker.stopped():
+                        # 任务**自己**停的（步骤里的「停止本设备」）：不是失败，也不重试。
+                        # 判据是"worker 置了停止位但 _stop_requested 里没有"——上面那个
+                        # 分支已经排除了用户/调度停止的情况。
+                        _log.info(f"{serial} 任务内主动停止本设备 (job={job.name})")
+                        outcome = "stopped"
+                        notifier.notify("task.device.stopped", serial=serial,
+                                        device_name=dname,
+                                        model=_dev_model(serial, tracker),
+                                        job_id=job.id, job_name=job.name,
+                                        attempt=attempt, phase="self")
+                        return
                     _log.warning(f"{serial} 任务未成功(status={st})")
                 except DeviceOfflineError as e:
                     # 设备掉线，立即放弃，不重试
@@ -728,47 +930,94 @@ class TaskManager:
                         self._running.pop(serial, None)
                     _update_status(serial, status="failed", task_job="",
                                    last_error=f"设备离线: {e}")
+                    outcome = "failed"
+                    notifier.notify("task.device.offline", serial=serial, device_name=dname,
+                                    model=_dev_model(serial, tracker),
+                                    job_id=job.id, job_name=job.name,
+                                    error=str(e)[:200])
                     return
                 except Exception as e:
                     _log.error(f"{serial} 执行异常: {e}", exc_info=True)
                     with self._lock:
                         self._running.pop(serial, None)
                     _update_status(serial, task_job="")
+                    notifier.notify("task.device.error", serial=serial, device_name=dname,
+                                    model=_dev_model(serial, tracker),
+                                    job_name=job.name, attempt=attempt,
+                                    error=str(e)[:200])
 
                 if attempt < max_attempts:
                     # 用户在 sleep 期间点停止也能中断
                     with self._lock:
                         if serial in self._stop_requested:
                             _log.info(f"{serial} 用户已请求停止，取消重试 (job={job.name})")
+                            outcome = "stopped"
+                            notifier.notify("task.device.stopped", serial=serial,
+                                            device_name=dname, job_name=job.name,
+                                            attempt=attempt, phase="retry-wait")
                             return
                     # 检查是否是端口耗尽类临时错误，需要更长退避等端口释放
                     with _WORKERS_LOCK:
                         err = _WORKERS.get(serial, {}).get("last_error", "")
-                    if err.startswith("[transient]"):
+                    transient = err.startswith("[transient]")
+                    if transient:
                         # Windows TCP 端口耗尽，TIME_WAIT 默认 2-4 分钟，等 120 秒
                         extra_delay = max(delay, 120)
                         _log.info(f"{serial} ADB 连接临时错误（端口耗尽），{extra_delay}s 后重试 ({attempt+1}/{max_attempts})")
-                        time.sleep(extra_delay)
+                        wait = extra_delay
                     else:
                         _log.info(f"{serial} {delay}s 后重试 ({attempt+1}/{max_attempts})")
-                        time.sleep(delay)
+                        wait = delay
+                    notifier.notify("task.device.retry", serial=serial, device_name=dname,
+                                    job_name=job.name, attempt=attempt,
+                                    next_attempt=attempt + 1, delay_s=int(wait),
+                                    reason="transient" if transient else "normal")
+                    time.sleep(wait)
 
             _log.error(f"{serial} 任务 {job.name} 重试耗尽，放弃")
-            _update_status(serial, status="failed", last_error=f"{job.name} 重试{max_attempts}次失败")
+            # 带上最后一次的真实失败原因——只写"重试N次失败"会让用户看不到为什么失败
+            # （worker 出错时已把原因写进 _WORKERS[serial]["last_error"]）
+            with _WORKERS_LOCK:
+                cause = (_WORKERS.get(serial, {}).get("last_error") or "").strip()
+            msg = (f"{job.name} 重试{max_attempts}次仍失败" if max_attempts > 1
+                   else f"{job.name} 执行失败")
+            if cause and cause != msg:
+                msg += f"：{cause}"
+            _update_status(serial, status="failed", last_error=msg[:200])
+            outcome = "failed"
+            notifier.notify("task.device.failed", serial=serial, device_name=dname,
+                            model=_dev_model(serial, tracker), job_id=job.id,
+                            job_name=job.name, attempts=max_attempts,
+                            cause=cause, msg=msg)
         finally:
             # 清除停止标志：整个重试循环结束（成功/失败/停止）后允许下次任务
             with self._lock:
                 self._stop_requested.discard(serial)
+            # 批次统计：**每台设备只在这里上报一次**（所有 return 分支都会走到 finally）
+            if tracker is not None:
+                try:
+                    tracker.done(serial, outcome,
+                                 detail=_dev_fail_note(serial, dname, tracker)
+                                 if outcome == "failed" else "")
+                except Exception as e:
+                    _log.warning(f"批次统计上报失败（不影响任务）: {e}")
             # 归还：本任务是抢占任务，结束后自动重新启动被抢占的原任务
             if preempted_job:
                 j = self.jobs.get(preempted_job)
                 if j and j.enabled:
                     _log.info(f"{serial} 抢占任务 {job.name} 结束，归还设备给任务 {j.name}")
+                    notifier.notify("task.device.released", serial=serial, device_name=dname,
+                                    job_name=job.name, preempted_job_id=preempted_job,
+                                    returned=True, reason="归还并重启被抢占任务")
                     threading.Thread(target=self._run_job, args=(j,), daemon=True).start()
                 else:
                     # 打日志便于排查：被抢占任务已删除/停用时不会归还，但要知道原因
                     _log.info(f"{serial} 抢占任务 {job.name} 结束，"
                               f"被抢占任务 {preempted_job} {'已停用，不归还' if j else '已不存在，不归还'}")
+                    notifier.notify("task.device.released", serial=serial, device_name=dname,
+                                    job_name=job.name, preempted_job_id=preempted_job,
+                                    returned=False,
+                                    reason="被抢占任务已停用" if j else "被抢占任务已不存在")
 
     # ---- 运行控制 ----
     def stop_device(self, serial):
@@ -874,6 +1123,9 @@ class TaskManager:
                 "owner": "",
                 "worker_status": w.get("status", "idle"),
                 "foreground_app": self._fg_scanner.get(serial),
+                # 电量（后台线程采的缓存，这里只读内存不查 adb）：
+                # {"level":85,"charging":false,"at":ts} 或 None（还没采到）
+                "battery": device_battery.get(serial),
                 # 通用进度字段（任意 app 通用，前端统一解析展示）
                 # 结构：{"done": int, "total": int, "unit": str, "action_counts": dict}
                 "progress": w.get("progress", {}),

core/u2_helper.py

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

core/uiauto_helper.py

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

doc/AI_CONSOLE.md

@@ -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` 等前端文件有缓存 |

doc/AI_TASK_GEN.md

@@ -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. 自测产生的东西（草稿/自建任务）用后即删，别碰用户真实数据。

doc/ARCHITECTURE.md

@@ -1,376 +1,409 @@
-# 架构详解
+# 架构详解（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` | 项目根配置：adb 路径、web 端口、USB 远程 adb server 等基础设施。**不放任务参数** |
-| 核心层 | `core/` | 框架运行时：日志、设备池、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                        │                   ┌─────────────────┐
-       ▼                          ┌──────────────┐           │ 设备 adb        │
-┌──────────────┐                  │  看门狗监控   │           │ (IP:5555 直连  │
-│  web/ 蓝图包  │                  └──────────────┘           │  / USB 远程)   │
-│  (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 DevicePool（`core/device_pool.py`）
+### 3.1 常驻线程一览
 
-设备池（已摘除 OpenSTF）：SQLite `devices` 表 = 设备清单，本机 adb = 在线状态。
+| 名称 | 启动位置 | 职责 | 周期 |
+|------|---------|------|------|
+| 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 个 |
 
-**关键设计**：
-- `list_configured()` — 清单（管理页维护，enabled=False 不参与调度）
-- `list_online()` — 本机 adb 在线设备；池内有 USB 设备（serial 无冒号）时合并 220
-  远程 adb server（`USB_ADB_HOST:PORT`，host 网络模式 5037）状态
-- `list_ready()` — 清单 ∩ 在线（任务调度用）
-- CRUD — `add_device`（upsert）/ `remove_device` / `set_enabled`
-- 单实例互斥由 `TaskManager._running[serial]` 内存锁保证（无跨实例占用概念）
-- 全模块不 connect/kill-server/disconnect（遵守共享 adb transport 红线）
+两个 APScheduler 相互独立，时区均固定 `Asia/Shanghai`。
 
-### 3.2 STFDevice + BaseWorker（`core/device_worker.py`）
+### 3.2 锁与并发保护
 
-**STFDevice** — 单设备生命周期管理：
-- `acquire()`：IP:5555 直连 adb connect；USB（serial 无冒号）校验 220 远程 adb server 可见性
-- `release()`：无操作（不 disconnect，红线）
-- 互斥由 TaskManager `_running` 保证，设备池负责在线判断
+| 锁 | 位置 | 保护对象 | 说明 |
+|----|------|---------|------|
+| `_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` / 告警状态机共用 |
 
-**BaseWorker** — 通用 Worker 基类（继承 threading.Thread）：
+**无锁部分**：`device_pool` 与 `models` 不持显式锁，依赖"每次操作独立 app context" + 数据库自身的并发控制（MySQL 下是 InnoDB 行锁 + READ COMMITTED，回退 SQLite 时是 WAL + `busy_timeout=5000`）。
 
-```
-run() 主循环（不要重写）：
-  1. acquire 设备
-  2. u2.connect（30s 超时保护）
-  3. setup(d)        ← 子类可选钩子
-  4. run_task(d)     ← 子类必须实现
-  5. teardown(d)     ← 子类可选钩子
-  6. finally: release 设备
-```
+### 3.3 错峰与心跳
 
-**超时保护**：
-- `u2.connect()` 用 `ThreadPoolExecutor + 30s 超时`，防止 atx-agent 无响应永久 hang
-- `d.info` 用 `ThreadPoolExecutor + 10s 超时`
+- **错峰启动**：`_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`）；重复触发同任务跳过，不同任务未开抢占也跳过。
 
-**心跳看门狗**（`_Watchdog`）：
-- 后台线程，每 30 秒扫描一次
-- Worker 超过 120 秒无心跳 → 标记 `error`
-- 防止设备被占用却不干活
+---
 
-**全局状态注册表**（`_WORKERS`）：
-- `serial -> status dict`，线程安全（`_WORKERS_LOCK`）
-- 供 `web_server` 读取实时状态，前端通过 `/api/status` 展示
+## 4. 设备生命周期
 
-### 3.3 TaskManager（`core/task_manager.py`）
+### 4.0 设备身份：名称 + 指纹（2026-09-11）
 
-统一管理：任务类型注册、设备分组、任务计划、定时调度、重试、持久化。
+设备池原以 **serial（IP）当身份**，设备一换 IP 旧记录就成了连不上的"僵尸条目"，分组与
+serial 模式的任务还吊着死地址。现在拆成三层：
 
-**核心组成**：
+| 概念 | 是否稳定 | 作用 |
+|------|---------|------|
+| `name`（名称，**必填唯一**） | 稳定 | 人可读身份；分组/任务/日志按名称认设备 |
+| `fingerprint`（`ro.serialno`） | 稳定 | **机器识别**：认出"这是同一台设备" |
+| `serial`（IP:5555 / USB 序号） | **可变** | 当前连接地址 |
 
-| 组件 | 说明 |
-|------|------|
-| `scheduler` | APScheduler BackgroundScheduler，cron 触发任务 |
-| `groups` | 设备分组（内存业务对象，持久化到 SQLite） |
-| `jobs` | 任务计划（内存业务对象，持久化到 SQLite） |
-| `_running` | 运行中的 worker（serial -> worker 信息） |
-| `_stop_requested` | 用户请求停止的 serial 集合（阻止后续重试） |
-| `_fg_scanner` | 前台 App 扫描器（不打扰设备） |
+**认领**（`device_pool.claim_device` 自动 / `relocate_device` 人工）：指纹命中或人工指认后，
+把旧记录迁到新地址（名称/型号/备注/启用状态/添加时间全保留）并同步引用。
 
-**调度模式**：
-- `once`：不注册 cron，手动执行
-- `cron`：注册启动 cron，到点启动所有目标设备
-- `cron_stop`：注册启动 cron + 停止 cron，到点停止本任务 worker
+> ⚠️ **引用同步必须同时改库与内存**：分组、任务在 `TaskManager` 里还有一份内存副本，
+> **调度用的是内存对象**——只改库不重启不生效（表现为"分组里少一台、任务仍跑向旧地址"）。
+> 因此 `device_pool` 迁址后回调 `TaskManager.sync_device_serial`，由装配层用
+> `device_pool.set_move_hook(...)` 注册；`device_pool` 不能反向 import `task_manager`（循环依赖）。
 
-**重试策略**：
-- `DeviceOfflineError`：立即放弃，不重试（设备掉线短时间不会自愈）
-- 其他异常：按 `retry.max_attempts` 重试，间隔 `retry.delay`
-- 临时错误（端口耗尽）：退避 max(delay, 120s)
-- 用户停止：加入 `_stop_requested`，阻止任何后续重试
+### 4.1 入池（三条路径）
 
-**并发控制**：同一 serial 同时只允许一个 worker，避免冲突。
-
-**状态缓存**：`get_status()` 带 5 秒缓存，避免每次 /api/status 都查库/adb 阻塞前端。
-
-### 3.4 前台 App 扫描器（`_ForegroundScanner`）
-
-**设计原则：不打扰设备**，扫描不会让设备退出当前 App。
-
-| 设备状态 | 处理方式 | 是否打扰 |
-|---------|---------|---------|
-| worker 运行中（IP:5555） | 复用已有 ADB 连接查询 | 否 |
-| worker 运行中（USB） | 经 220 远程 adb server 查询 | 否 |
-| 完全空闲 | 返回"空闲"（不主动 connect） | 否 |
-
-> **为什么不扫描空闲设备的前台 App**：IP:5555 的 adb transport 是共享的（历史与 STF provider 共用），外部 connect/disconnect 会扰动共享连接，遵守既有红线。
-
-### 3.5 ADB 操作（`core/adb_helper.py`）
-
-**全局锁串行化**：`_ADB_LOCK` 确保所有 adb 调用串行执行，避免多线程竞争 adb server。
-
-**铁律：绝不 kill-server**：
-- `adb kill-server` 会断开所有设备的 adb transport
-- 全部设备连接被重建，影响所有运行中的任务
-- 同理绝不 disconnect IP:5555（共享 transport 红线，见 DEVELOPMENT.md）
-
-| 函数 | 说明 |
-|------|------|
-| `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 密码；`is_admin` 管理员 + `perms` 业务权限位） |
-| `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`）
-- 版本化 schema 迁移（`SCHEMA_MIGRATIONS`）：结构变更必须追加迁移条目，`create_all` 只建新表不加列
+> 任何一条入池路径在设备可连时都会读取**设备指纹**；指纹命中池中已有设备 = 同一台换了地址
+> → 走**认领**（§4.0），不新增记录。
 
-### 权限模型
+断联设备的自动重连由发现线程每轮执行（只重连 `IP:5555`）。
 
-- `User.perms` 存业务权限位 JSON 数组（`tasks`/`devices`/`apks`/`logs`），`is_admin=true` 拥有全部权限（`has_perm` 短路）
-- 后端统一用 `@perm_required(PERM_X)` / `@admin_required` 装饰器拦截（web/auth.py），无权限返回 403；
-  查看类 GET 接口只要求登录；用户管理、adb 终端（`/api/adb/cmd`）强制 `admin_required`
-- adb 终端安全红线：拒绝 `kill-server` / `disconnect`（共享 adb transport）
-- 前端 `loadMe()` 拉取 `/api/me`，用 `data-perm` 属性隐藏无权限的 tab/按钮，行内按钮用 `_can(perm)` 判断
-- 安全兜底：**前端隐藏只是 UX，权限强制在后端**；新增路由时按"写操作必须带权限装饰器"的约定
+### 4.2 可用性判定
 
-### 3.7 APK 管理（`core/apk_manager.py`）
+```
+list_configured()   设备池中 enabled=True 的 serial
+list_online()       本机 adb devices 中 state=device（池内有 USB 设备时并查 220 远程 adb server）
+list_ready()        两者交集 ← 调度 "all" 模式取这个
+```
 
-APK 上传/解析/批量安装。
+### 4.3 执行期状态字段
 
-**设备连接策略（直连）**：
-- 直接 `adb connect serial`（serial 是 IP:5555）
-- 不经过占用/释放（单实例互斥由调度器内存锁保证）
-- 安装后不主动 disconnect（共享 adb transport 红线）
+设备状态存在内存注册表 `_WORKERS[serial]`（**不落库，重启即清零**）：
 
-**安装流程**：
-1. 上传 APK → 保存到 `data/apks/` → pyaxmlparser 解析包名/版本 → 入库
-2. 批量安装 → 后台线程 → 每台设备直连 adb install → 验证包名
-3. 跳过 worker 运行中的设备（避免打断任务）
-
-### 3.8 元素抓取（`core/uiauto_helper.py`）
-
-封装 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 状态迁移
 
-### 3.9 屏幕 OCR（`core/ocr.py`）
+**Worker 侧**（`BaseWorker.run`）：
 
-条件判断的 `ocr` 选择器实现：截屏 → RapidOCR（ONNX 推理，中英文模型随包内置）→ 关键词匹配 → 返回文字中心像素坐标（与 u2 `d.click` 一致）。
+```
+connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ setup ──▶ run_task ──▶ teardown
+                                                                    │
+                                     未被 stop ──▶ done             │
+                                     异常 ──▶ error（DeviceOfflineError 单独分类，不重试）
+                                     finally ──▶ 仅当仍为 running/connecting 时置 released
+```
 
-- **跨平台**（Windows/Linux/macOS），依赖 `rapidocr_onnxruntime`；服务器无显示器环境建议将 opencv-python 换成 opencv-python-headless
-- 引擎懒加载单例 + 并发加锁（识别约 0.2-0.5s/次）
-- 返回坐标约定：像素、原点左上
+> `finally` 里的状态判断是为了**不覆盖业务结果**（`done`/`error` 必须保留）。
 
-### 3.10 Web 层蓝图包（`web/`）
+**调度侧**（`_run_with_retry`）：worker 结束后读 `status` → `done` 即成功返回；否则按 `max_attempts` 重试（`[transient]` 错误额外加长退避）→ 重试耗尽置 `status="failed"`，并把**真实失败原因**拼进 `last_error`（截断 200 字符）。
 
-路由按功能域拆分（模块化开发底线，便于定位问题）：
+### 4.5 释放
 
-| 模块 | 职责 |
-|------|------|
-| `auth.py` | 登录/登出/CSRF/权限装饰器/页面路由（/、/wall） |
-| `monitor.py` | 状态/运行控制/设备操作/远程看屏（流+缩略图+触控） |
-| `tasks_api.py` | 任务计划/分组/自定义动作/元素抓取/步骤测试 |
-| `admin_api.py` | 用户管理/日志 |
-| `tools_api.py` | adb 终端/剪贴板注入/应用版本 |
-| `devices_api.py` | 设备池管理（增删停用/重连/型号采集） |
-| `apks_api.py` | 应用管理 |
-| `tailscale_api.py` | Tailscale 管理 |
-| `common.py` | 跨模块共享（合并设备列表/屏幕状态） |
-| `context.py` | 共享对象注入（mgr/apk_mgr/device_pool） |
-
-`web_server.py` 只保留：app 创建、数据库初始化、蓝图注册、uiautodev 生命周期、启动（193 行）。
+`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` | 登录即可 | — |
+| 账号 | `account` | `devices` | `ledger` 账号台账（列表/增删改/粘贴导入）/ `plan` **发布计划**（上传视频与标题、时间线、推送到手机、导出链接 + **发布任务就地编辑**，见 [DATA_MODEL.md](DATA_MODEL.md) §2.10 §2.11） |
+| 任务 | `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` 任务的步骤编辑器（任务弹窗已加宽到 1000px）：
-- 左侧操作库（拖拽源，按 交互操作/屏幕与App/流程控制 分组）
-- 中间画布（步骤卡片列表，HTML5 Drag API 排序 + 跨层级嵌套：循环套循环、动作组）
-- 每个步骤卡片可展开参数表单
-- 选择器字段旁有"抓取元素"按钮（独立模态框）
-- **容器步骤**（loop/group/if_el）：卡片内嵌子步骤容器接收拖入；if_el 有"✅找到时/❌未找到时"两个独立分支容器，分支可嵌套任意步骤
-- **条件判断**（if_el）：选择器支持 xpath 等 UI 树选择器或 OCR识别（`core/ocr.py`，截屏匹配图片/画布文字，命中可自动点击）
-- 所有递归操作（选择打包、存自定义动作、校验、防循环自套）统一遍历 children/then/else 三个子数组
+子分栏会记住上次选中位置（`_activeSubs`）；`devpool` 子分栏自带 10s 轮询，切走即停。
 
-### 5.3 页内子分栏
+### 6.3 JS 分工
 
-任务/工具 Tab 用通用 `showSubTab(tabId, name)` 实现页内子分栏：每个子分栏一个 `.sub-panel`，
-`_activeSubs` 记住各 Tab 上次选中的子分栏。工具 Tab 集中了全部管理工具（剪贴板注入/adb 终端/
-Tailscale/应用管理/应用版本/已装应用/STF 设备管理），维护 Tab 仅保留 STF 服务。
+| 文件 | 职责 | 备注 |
+|------|------|------|
+| `base.js` | esc / CSRF / 权限 / API 封装 / Toast / Tab 与子分栏切换 / 模态框 / 常量表 | 所有模块的公共底座 |
+| `markdown.js` | 轻量 Markdown 渲染（`renderMarkdown`） | 无 CDN 依赖；**先转义再套标记** |
+| `list.js` | 统一列表组件：搜索 + 分页 + 排序 | 状态注册表 `_LIST_PAGERS`；`setListPager` **不重置**页码/搜索/排序（避免轮询刷新打断用户） |
+| `ledger.js` | 账号台账页（列表 / 单条增删改 / 从表格粘贴导入 + 逐行结果 / 设备维度弹窗）+ `ledgerCell()` 供设备池那一列 | 服务层 `core/ledger.py`；导入默认**先预览再写**（`dry_run`） |
+| `release.js` | 发布计划页（时间线按日期分组 / 多选视频**串行**上传 + 逐文件进度与结果 / 标题 txt 上传 / 推送到手机 + **一键推送**（当天全部）、相册校验徽章与裁决 / 链接复制与导出 CSV / **发布任务的就地编辑**） | 服务层 `core/video_plan.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：备份导出 / 导入预览与应用 | |
 
-### 5.4 元素抓取模态框
+加载顺序见根 [README](../README.md)；都是全局脚本（非 ES module），靠加载顺序保证依赖。
 
-独立的第二层模态框（`el-picker-overlay`，z-index 1100），不影响任务编辑窗口：
-1. 选择设备 → 2. 加载截图 + 元素树 → 3. 点击元素/边界框 → 4. 回填选择器
+### 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) 配置速查 |

doc/DATA_MODEL.md

@@ -0,0 +1,463 @@
+# 数据模型（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 = 10`（迁移清单见 `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；任务「条件判断」的取号来源、设备端身份页显示用） |
+| 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 后据此认领回原记录 |
+
+### 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` — 账号台账（一台设备上登录着哪些账号）
+
+「账号」页维护；服务层 `core/ledger.py`，接口 `/api/ledger*`（见 [API.md](API.md) §2.15）。
+
+| 列 | 类型 | 说明 |
+|----|------|------|
+| `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) | 字符串时间（仓库惯例） |
+
+**三个使用方**：
+
+1. **web「账号」页** —— 列表 / 增删改 / 从 Excel 粘贴导入（解析规则见 `core/ledger.parse_paste`）
+2. **任务的「条件判断」取号** —— `if_el` 的 `cmp_source`（`device` 本机 / `all` 全部 / `group` 按设备分组），
+   见 [TASK_DEV.md](TASK_DEV.md) §4.2
+3. **手机端 Agent 的身份大字页** —— 平台推 `accounts_b64`（见 [DEVICE_AGENT.md](DEVICE_AGENT.md) §5.2）
+
+⚠️ **`douyin_id` 是纯号，绝不能当去重身份**：`done_mark.identity` 存的是**元素原文**
+（`抖音号：35377983067`）、逐字算 key，格式不一致会让去重**静默失效**。
+它只做"比对用的候选值"（运算符用「包含」时纯号是子串）。
+
+**唯一性在应用层**（`core/ledger`）：同一抖音号不允许两条。没做成 DB 唯一索引的理由：
+抖音号可能为空，DB 级要写"部分唯一索引"（§4.2 那套 SQLite `WHERE` + MySQL 虚拟生成列），
+而台账是人工维护的几十条 —— 三处方言适配不划算。
+
+这张表**自动进整库备份**（§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 位 |
+| `account_id` / `phone` | String(32) | 台账行 id（**不做外键**）/ 配对键（冗余存：账号删了也留痕） |
+| `device_name` / `nickname` / `douyin_id` / `serial` | String | 账号与设备快照（时间线卡片直接显示，免 join） |
+| `release_date` | String(10) index | **`2026-09-12`** 纯日期（等值比较走索引） |
+| `seq` / `seq_auto` | Integer / Boolean | 编号从 **1** 起（不用 0 表示"无"）；`seq_auto`=号是自动分配的 |
+| `title` | 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` |
+| `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` 卡片标橙 + 硬提示，人工到抖音确认后点「已发出 / 未发出」裁决。
+
+**唯一性**：`(phone, release_date, seq)` 由**服务层**保证，**不加 DB 唯一索引** ——
+`seq` 从 1 起、没有"空值"可言，做部分唯一索引要写三处方言适配 + MySQL 生成列（§4.2），
+收益不匹配；违反的代价只是低频人工上传产生的重复行（可见、可删）。
+
+**索引**：`(release_date,status)` 时间线主查询 · `(account_id,release_date)` 账号视角 ·
+`(phone,release_date,seq)` 配对/幂等 · `(video_file)` 清理时反查引用。
+
+这张表**自动进整库备份**（§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 红线）。

doc/DEPLOY.md

@@ -1,324 +1,378 @@
-# 部署指南
+# 部署与运维（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 依赖）
-
-设备池由平台自身管理（SQLite `devices` 表 + 本机 adb 在线状态），**不再依赖 OpenSTF**。
-新增设备在管理后台「工具 → 设备池管理」添加（serial 形如 `100.100.10.x:5555`）。
-
-USB 设备（serial 无冒号）插在部署机（220）时，经 220 的 adb server 驱动：
-- 220 的 adb 容器需为 **host 网络模式**（5037 已监听所有网卡，含 Tailscale）
-- 平台配置 `USB_ADB_HOST`（默认 `100.100.10.1`）/ `USB_ADB_PORT`（默认 5037）
-
-### 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 调试**（设置 → 开发者选项）
-- 转网络调试：USB 连上后 `adb -s <serial> tcpip 5555`（管理后台「adb 终端」有一键快捷命令）
-- 设备加入 Tailscale（同一账号，获得 100.100.10.x IP）
-- 在「工具 → 设备池管理」添加 `IP:5555`（自动尝试连接，任务运行时 u2 自动推送 atx-agent）
 
----
+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 元信息解析 |
-| rapidocr_onnxruntime | >=1.4 | 屏幕 OCR（条件判断的 OCR识别 选择器，中英文模型随包内置，跨平台） |
-
-> 服务器（无显示器/Linux）环境建议把 opencv-python 换成 `opencv-python-headless`（rapidocr 依赖 cv2，两者取一）。
-
-> uiautomator2 首次连接设备时会自动推送 atx-agent 到设备，无需手动安装。
-
-### 2.3 修改配置
-
-**密钥类配置统一放项目根目录 `.env`**（已被 `.gitignore` 排除，不会提交到 git；
-`config.py` 不再内置任何密钥）：
-
-```ini
-# .env 示例
-WEB_SECRET_KEY=随机字符串（会话密钥，python -c "import secrets;print(secrets.token_hex(32))" 生成）
-TAILSCALE_API_KEY=你的Tailscale_API_key
-# USB_ADB_HOST=100.100.10.1   # 220 的 Tailscale IP（USB 设备远程 adb server，默认值已可用）
-```
-
-其他配置按需调整：
-
-| 配置项 | 默认值 | 何时修改 |
-|-------|--------|---------|
-| `WEB_HOST` | `0.0.0.0` | 仅本机访问改为 `127.0.0.1` |
-| `WEB_PORT` | `18050` | 端口冲突时修改 |
-| `ADB_PATH` | 自动识别 | 用自定义 adb 时修改 |
-| `USB_ADB_HOST` | `100.100.10.1` | USB 设备所在部署机（220）的 Tailscale IP |
-| `USB_ADB_PORT` | `5037` | 220 adb 容器监听端口（host 网络模式） |
-| `TAILSCALE_TAILNET` | 按邮箱前缀 | tailnet 名称/ID（个人账号一般为登录邮箱前缀） |
-
-> **未配置 `WEB_SECRET_KEY`**：启动时随机生成（每次重启登录态失效，生产务必配置固定值）。
-> **工具页 Tailscale 管理前置**：`.env` 写入 `TAILSCALE_API_KEY` 后重启服务；
-> 未配置时管理分区显示明确提示，不影响其他功能。
-> （历史遗留的 `STF_URL`/`STF_TOKEN`/`STF_SSH_*` 等配置已废弃，代码不再读取。）
-
-### 2.4 启动服务
-
-**命令行启动**
-
-```bash
-python web_server.py
-```
-
-（推荐配合 `scripts/supervise.sh` 进程守护，见 3.1 节）
-
-### 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
-```
-
-**通用脚本（Linux/macOS，无需 systemd）**：
-
-项目自带 `scripts/supervise.sh`：web_server 崩溃自动重启、带退避和重启上限（防崩溃死循环）。
-
-```bash
-# 用 venv 的 python 守护
-PYTHON=./.venv/bin/python bash scripts/supervise.sh
-```
-
-> 进程守护只保证服务重启，不恢复已运行的任务（worker 状态在内存）。
->
-> **悬空设备自愈**：崩溃后残留的设备占用（STF 仍显示占用）可配置启动自动清理。单实例部署时在 `.env` 设置 `AUTO_RELEASE_STALE_OCCUPY=true`，web_server 启动会自动释放本账户残留占用；**多实例共用 STF 账户时不要开**（会误放另一实例的任务）。默认关，仅启动时提示。
-
-**Docker（生产 python-app 容器）**：
-
-docker-compose 已配置 `restart: unless-stopped`，web_server 进程退出 → 容器退出 → Docker 自动重启。建议再加健康检查，让编排感知服务存活：
-
-```yaml
-# docker-compose.yaml 的 python-app 服务下添加
-healthcheck:
-  test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:18050/api/health', timeout=3)"]
-  interval: 30s
-  timeout: 5s
-  retries: 3
-  start_period: 10s
-```
-
-### 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 密码
-- **最小权限分配**：需要多人使用后台时，在"用户"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）
-
-Windows 可能将某些端口范围划为动态排除范围，导致绑定失败（WinError 10013）。
-
-```bash
-# 查看排除的端口范围
-netsh interface ipv4 show excludedportrange protocol=tcp
-```
-
-如果 18050 在排除范围内，修改 `config.py` 的 `WEB_PORT` 到一个不在排除范围内的端口。
-
-### 4.3 局域网访问
-
-- `WEB_HOST = "0.0.0.0"` 允许局域网访问
-- 需要添加防火墙入站规则（Windows 手动添加，或参考 `netsh advfirewall firewall add rule`）
-- 局域网其他机器访问 `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 登录失败
+```
+
+**防混库**（`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`。

doc/DEVELOPMENT.md

@@ -1,220 +1,257 @@
 # 开发手册（DEVELOPMENT）
 
-面向本项目开发者：开发流程、git 工作流、环境说明、技术红线、本地开发、常见开发任务。
+> 适用读者：所有参与 `auto_control` 开发的人。**动手前先读 §2 技术红线**。
+> 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)（架构，先懂再改）、[DATA_MODEL.md](DATA_MODEL.md)（表结构）、[doc/README.md](README.md)（文档索引与维护约定）。
 
 ---
 
-## 1. 开发流程与 git 工作流
+## 1. 开发流程
 
 ### 1.1 分支策略
 
 | 分支 | 用途 |
 |------|------|
-| `dev` | **开发分支**，所有新功能/修复都在这里开发 |
-| `main` | **生产分支**（主分支），只放已确认的稳定版本 |
+| `dev` | 开发分支，所有新功能/修复从它切出、合并回它 |
+| `main` | 生产分支，只放已确认的稳定版本 |
+| `fix/xxx` · `feat/xxx` · `chore/xxx` | 单个改动的临时分支（从 `dev` 切出） |
 
-生产环境 = 部署机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（python-app 容器运行 `web_server.py`）。
+生产环境 = 部署机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（`python-app` 容器）。
 
-### 1.2 git 操作铁律（重要）
+### 1.2 git 铁律
 
-**所有 git 操作都必须先经项目负责人明确确认后才能执行**，包括但不限于：
+**所有 git 操作都必须先经项目负责人明确确认**，包括但不限于 `commit` / `push`（**即使 push 到 dev 也要确认**）/ `merge` / `rebase` / `reset` / `branch -D`。
 
-- `commit` / `push`（**即使 push 到 dev 也要确认**）
-- `merge`（dev → main）
-- `revert` / `checkout` / `reset` / `branch -D` 等
-
-**标准流程：**
+**标准流程**：
 
 ```
-1. 在 dev 分支开发、本地测试
-2. 完成改动 → 把改动清单 + 建议 commit 信息 列给负责人
-3. 负责人确认 → 才能 commit + push dev
-4. 需要发布 → 负责人确认后再合并到 main
-5. 部署生产 → 负责人明确指示后才 pull 到 220
+① 本机新建分支          fix/xxx 或 feat/xxx（从 dev 切出）
+② 分支上开发 + 自测     跑通本机（服务/接口/页面），能自测就别只靠"看代码没问题"
+③ 交负责人确认          ★ 未经确认不合 dev
+④ 合并到 dev            确认通过后（保持线性：rebase 后 ff-merge）
+⑤ dev 整体就绪          功能齐全、验证完毕
+⑥ 合并到 main           ★ 负责人确认后
+⑦ 生产 220 部署         git pull → docker restart python-app → 验证（见 DEPLOY.md §3）
 ```
 
-> 不允许"开发完顺手就 commit/push"。即使是一次性小改动，也要先确认。
+> 每个改动**单独分支 + 单独 commit**，主题单一，便于评审与回退。不允许"开发完顺手 commit/push"。
+
+**修复也走这条流程，包括线上紧急修复**（2026-09-14 补：当天两次 APK 安装修复因为"生产卡着"
+直接提交在 dev 上、紧接着就合 main 部署，被负责人纠正）：
+
+- 紧急修复照样从 dev 切 `fix/xxx` 分支——**不允许直接 commit/push 到 dev**，
+  哪怕改动只有几行、哪怕生产正卡着
+- 第 ② 步的"自测"要**跑通本机服务**（起服务/点页面/看日志），不能只有脚本级验证
+- 第 ③ 步的确认要点名两件事：**「是否合 dev」**和**「是否合 main + 部署生产」**——
+  紧急场景可以一次性问清，但**不能把两个节点合并成一次默认同意**
+- 线上正卡住时：先**恢复**（重启/回滚等运维动作，经确认即可执行），再按流程走修复
 
 ---
 
-## 2. 环境说明
+## 2. 技术红线（违反会打断共享 adb transport 或造成生产事故）
 
-| 环境 | 位置 | 说明 |
-|------|------|------|
-| 开发机 | 本机（192.168.20.57） | `.venv` + 本地运行 `web_server.py` |
-| 生产机 | 部署机 220 的 `auto_control` | python-app 容器，`network_mode: host` |
-| STF 服务 | ~~`192.168.20.220:7100`~~ | 已停用（2026-08-18 `docker stop stf`，代码已摘除依赖） |
-| adb 容器 | 220 上 `adb`（host 网络 5037） | USB 设备远程 adb server；网络设备补连用 |
-| 设备 | Tailscale `100.100.10.x:5555` | Xiaomi 舰队，本机 `100.100.10.2` 在 tailnet 内 |
-| uiautodev | 本机 `20242` | 元素抓取服务（web_server 自动拉起） |
+| # | 红线 | 为什么 | 代码里的体现 |
+|---|------|--------|-------------|
+| 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) |
 
-### 2.1 adb key（关键）
+### 其它开发约束
 
-- 本机 `~/.android/adbkey` 沿用历史 key（原取自 STF adb 容器，全部设备都信任）
-- **不要随意更换 key**——设备会变 unauthorized 连不上
-- 旧 key 备份在 `~/.android/adbkey.local.bak`
-- 生产环境的容器也需要用这把 key（部署时处理）
-
-### 2.2 设备连接方式
-
-- 设备 serial 是 `IP:5555`（Tailscale 地址），**直连**优先（只 connect、绝不 disconnect）
-- USB 设备（serial 无冒号）：插本机走本地 adb；插 220 走远程 adb server（`USB_ADB_HOST:5037`）
-- 本机已在 tailnet 内，直连可靠且快（<1s）
-- 设备加入/退出平台：工具 → 设备池管理（SQLite 清单，自动连接 + 型号采集）
+- **`web_server.py` 以 `debug=False` 运行**：改 `core/`、`tasks/`、`templates/` 后**必须重启**；改前端 JS 后**强刷浏览器**
+- **任务参数放各自 `tasks/<app>/` 顶部**，不放 `config.py`
+- **运行时数据不提交 git**：`data/`、`logs/` 全是运行时产物
+- **不要移除分页与错峰**：监控/列表页已分页（100 台设备只渲染 10 行/页）；任务批量触发已错峰（`_START_STAGGER_SEC`）
+- **不要手工改库结构**：走 `SCHEMA_MIGRATIONS`（模型表）或幂等原生建表
 
 ---
 
-## 3. 技术红线（开发限制）—— 违反会打断共享 adb transport，需人工恢复
+## 3. 本地开发
 
-这些是踩过坑后总结的，**任何修改都不能引入**。违反任何一条都会导致设备连接被全部重建（历史原因：STF provider 共享同一 adb transport，摘除 STF 后仍保留此约束）：
-
-1. **绝不 `adb kill-server`**
-   - 会断开所有设备的 adb transport，全部设备连接被重建，运行中任务中断
-   - 见 `core/adb_helper.py`
-
-2. **绝不对 `IP:5555` 设备 `adb disconnect`**
-   - 该地址的 adb transport 是共享的（历史与 STF provider 共用），disconnect 会断掉全部相关连接
-   - 直连模式下 `release()` 不 disconnect
-   - 见 `core/device_worker.py` `STFDevice.release()`
-
-3. **空闲设备扫描不主动 connect/disconnect**
-   - IP:5555 的 transport 由多方共享（历史与 STF provider 共用），外部 connect/disconnect 会扰动共享连接
-   - `_ForegroundScanner._scan_free` 对空闲设备直接返回"空闲"，不碰 adb
-   - 见 `core/task_manager.py`
-
-4. **adb key 保持历史 key 不变**（见 2.1，设备信任该 key）
-
-5. **直连优先，不引入第三方桥接**（见 2.2）
-
-### 3.1 其他开发限制
-
-- **`web_server.py` 以 `debug=False` 运行，不热重载**：改 `core/`、`tasks/`、`templates/`、`static/` 后必须重启 web_server（前端 HTML 改完强刷浏览器）
-- **任务参数放各自 `tasks/<app>/task.py` 顶部，不放 `config.py`**
-- **生产环境（220）默认只读**：任何写操作（改文件/重启容器/部署）都必须先经负责人确认
-- **数据库是 SQLite**（`data/users.db`，WAL 模式）：运行时数据不提交 git
-- **前端 JS 在 `static/admin/monitor.js`**（已从 HTML 拆分），HTML 里用 `<script src>` 引用
-- **监控页/大列表已加分页**：100 台设备也只渲染 10 行/页，不要移除分页逻辑
-- **任务批量触发已错峰**（`_START_STAGGER_SEC`）：避免大量设备同时启动造成 adb 连接风暴，不要移除
-
----
-
-## 4. 本地开发手册
-
-### 4.1 首次安装
+### 3.1 安装
 
 ```bash
-# 用 Python 3.12 建 venv（README 推荐版本）
-/opt/homebrew/bin/python3.12 -m venv .venv
-.venv/bin/pip install -r requirements.txt
-
-# macOS：adb 用系统自带的（bin/adb/adb 是被 gitignore 的符号链接）
-ln -sf /opt/homebrew/bin/adb bin/adb/adb
-
-# 确认 adb key（必须是 STF 容器的 key，否则设备连不上）
-ls -la ~/.android/adbkey
+python -m venv .venv
+# Windows: .venv\Scripts\activate    Linux/macOS: source .venv/bin/activate
+pip install -r requirements.txt
 ```
 
-### 4.2 启动
+确认 adb key（沿用既有 key，否则设备连不上）：`ls -la ~/.android/adbkey`。
+
+### 3.2 启动
 
 ```bash
-.venv/bin/python web_server.py
-# 访问 http://localhost:18050/  账号 admin/admin123
+python web_server.py
+# 访问 http://localhost:18050/   admin / admin123
 ```
 
-启动日志看到以下即成功：
-```
-[INFO] [core.worker] 心跳看门狗已启动
-[INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
-[INFO] [web] 启动服务: http://localhost:18050/
+需要 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
 ```
 
-### 4.3 测试
+（容器里由 `scripts/start.sh` 自动拉起，不需要手动。）
 
-- **后端逻辑**：直接 `.venv/bin/python -c "..."` 调用（如 `tasks/`、`core/` 的函数）
-- **前端 UI**：Playwright（系统 `python3` 已装），脚本示例见下
-- **浏览器冒烟**：切 6 个 tab、开任务编辑器，确认无 JS 错误
+### 3.3 调试
 
-```python
-# Playwright 冒烟示例（python3 运行）
-from playwright.sync_api import sync_playwright
-with sync_playwright() as p:
-    b = p.chromium.launch(headless=True)
-    pg = b.new_page()
-    pg.goto("http://127.0.0.1:18050/login")
-    pg.fill("input[name=username]", "admin")
-    pg.fill("input[name=password]", "admin123")
-    pg.click("input[type=submit], button[type=submit]")
-    pg.wait_for_load_state("networkidle")
-    # ... 检查各 tab、编辑器
-    b.close()
-```
+| 目的 | 做法 |
+|------|------|
+| 看日志 | `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 可用） |
+| 停止设备/清异常 | 监控页「停止全部 / 停止选中 / 清除全部异常」 |
+| 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` 清掉。**注意它会真在设备上点按**（导航类动作），且与聊天共用同一个运行槽 |
 
-### 4.4 常用调试
+> **改了数据库/配置想复原**：删 `data/users.db*` 会丢数据，别这么干；用「系统 → 备份/导入」或先手工复制一份 `data/`。
 
-- **看日志**：`logs/` 下 `core.log` / `task.log` / `web.log` / `action.log`（10MB 滚动，保留 5 份）
-- **看设备/任务状态**：浏览器监控页，或 `GET /api/status`、`GET /api/health`
-- **清理 STF 残留占用**：前端监控页"强制释放占用"（或 `.env` 配 `AUTO_RELEASE_STALE_OCCUPY=true` 启动自动清理）
-- **打包项目**：`python scripts/pack.py`
+### 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. 常见开发任务
 
-### 5.1 新增 App 任务
+> 每一项的"改哪里"清单也见 [ARCHITECTURE.md](ARCHITECTURE.md) §10。
 
-参照 `tasks/douyin/` 结构，详见 **[doc/TASK_DEV.md](TASK_DEV.md)**（6 步模板）。
+### 5.1 新增 HTTP 接口
 
-```
-tasks/<app>/
-  __init__.py     # from . import task
-  task.py         # DEFAULT_PARAMS + Worker + @register_task
-  actions/        # 专属操作（可选）
-```
+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 新增专属操作
+### 5.2 新增数据库字段/表
 
-在 `tasks/<app>/actions/` 建 `.py`，继承 `BaseAction` + `@register_action(ACTIONS)`，在 `__init__.py` import。
+- 模型改 `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` | HTML 结构 + CSS + `<script src>` 引用 |
-| `static/admin/monitor.js` | 全部前端 JS |
+| 改什么 | 文件 |
+|--------|------|
+| 页面结构 / 样式 / 引入脚本 | `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,ledger,release}.js` |
 
-改完**强刷浏览器**（Cmd/Ctrl+Shift+R），必要时重启 web_server。
+新增 JS 模块：建文件 → 在 `monitor.html` 里按依赖顺序加 `<script src>` → 更新 [ARCHITECTURE.md](ARCHITECTURE.md) §6.3 与本文 §5.3。
 
-### 5.4 新增 API
+### 5.4 新增步骤类型 / 任务类型
 
-在 `web_server.py` 加 Flask 路由，更新 **[doc/API.md](API.md)**。
+见 [TASK_DEV.md](TASK_DEV.md)（步骤类型要同时改后端 `STEP_TYPES` 与前端 `STEP_LIB`）。
 
-### 5.5 新增数据库字段/表
+### 5.5 新增 MCP 工具
 
-- 模型改 `core/models.py`，首次建表用 `create_all()`
-- **已有数据的老库**：在 `core/models.py` 的 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）
+在 `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. 发布流程
+## 6. 文档同步（红线）
 
-详见 **[doc/DEPLOY.md](DEPLOY.md)**。摘要：
+**任何功能 / 配置 / 接口 / 表结构的增删改，都要在同一个 commit 里更新对应文档。**
 
-1. dev 开发测试完成
-2. 负责人确认 → 合并到 main
-3. 负责人确认 → 生产 220 `git pull`
-4. 重启 python-app 容器生效
+| 改动类型 | 必须更新 |
+|---------|---------|
+| 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) |
 
-**发布前检查**：生产容器 adb key、依赖、数据库迁移。
+新增文档时：登记进 [doc/README.md](README.md) §1 与根 [README](../README.md) 的文档索引。
+历史文档（[STF_REMOVAL.md](STF_REMOVAL.md)）只增不改。
 
 ---
 
-## 7. 文档索引
+## 7. 常见坑速查
 
-| 文档 | 内容 |
-|------|------|
-| [README](../README.md) | 项目总览、快速上手 |
-| **[DEVELOPMENT.md](DEVELOPMENT.md)** | 本文档：流程/准则/限制/手册 |
-| [TASK_DEV.md](TASK_DEV.md) | 任务开发指南（新增 App 任务模板） |
-| [ARCHITECTURE.md](ARCHITECTURE.md) | 架构详解（分层、数据流、设计决策） |
-| [API.md](API.md) | 全部 HTTP 接口说明 |
-| [DEPLOY.md](DEPLOY.md) | 部署指南（环境、生产、故障排查） |
+| 坑 | 说明 |
+|----|------|
+| 跨线程访问 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。

doc/DEVICE_AGENT.md

@@ -0,0 +1,316 @@
+# 设备端 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.2.1 本机账号台账（`accounts_b64`，可选 extras — **需要设备端配合实现**）
+
+平台在**打开**身份页时会顺带把这台设备在「账号」页登记的抖音账号推过去
+（`--es close 1` 时**不带**）。**中文必须 base64**（同 §5.1：adb shell 直传中文会变形）：
+
+```bash
+adb -s <serial> shell am start -n <pkg>/.InfoActivity \
+  --es name "A03" --es serial "192.168.20.63:5555" --es server "http://192.168.20.220:18050" \
+  --es ip "192.168.20.63" \
+  --es accounts_b64 "<base64(UTF-8 JSON)>"
+```
+
+解码：**标准 base64**（不是 URL-safe）+ UTF-8。JSON 结构（字段名的设备端解析按名取，多余字段忽略）：
+
+```json
+{"v":1,"total":4,"shown":4,"truncated":false,
+ "note":"设备『A03』登记 4 个号",
+ "accounts":[
+   {"name":"AA建材王总","douyin_id":"66057500463","device_name":"A03","device_no":"A03",
+    "sim_in_device":true,"can_post_video":true}]}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `v` | 本块格式版本（当前 **1**）。解不出来时用它区分"格式变了"与"平台没给" |
+| `total` / `shown` / `truncated` | 该设备在台账里的总数 / 本次带了几条 / 是否被截断 |
+| `accounts[].name` | 账号名称（台账的「账号名称」列） |
+| `accounts[].douyin_id` | **抖音号（纯号）**，如 `35377983067` |
+| `accounts[].sim_in_device` / `can_post_video` | 卡在机内 / 可发视频（布尔） |
+| `accounts[].phone` | **默认不推**（大字页是机器旁的公开屏幕，手机号不宜默认上屏）。需要时平台请求体传 `{"include_phone":true}` |
+
+**设备端要做的**（当前版本忽略该 extra，行为与旧版逐字一致）：
+
+1. 读 `accounts_b64` → base64 解码 → `JSONObject`
+2. 在身份页上按 `name` / `douyin_id` 渲染一个列表（建议 1~3 行简短列表，最多显示 `shown` 条）
+3. `truncated=true` 时提示"还有更多，见平台账号页"
+
+**约定与边界**（平台侧实现见 `web/device_agent_api.py` 的 `_encode_accounts`）：
+
+- **没有这个 extra = 这台设备在台账里没有账号**（不是"平台忘了给"）——设备端保持原样显示即可，
+  不要显示空列表
+- 超预算时平台**按整条丢**（`shown` 变小 + `truncated=true`），**绝不按字节切**（切了就是坏 JSON）；
+  台账过大时可能**整个 extra 不发**（平台响应体里 `warn` 会说明原因）
+- 台账读取失败时同样**不发**这个 extra —— 台账故障不影响"显示身份"这个动作
+
+### 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. 版本与兼容
+
+- **§5.2.1 的 `accounts_b64` 是"加字段"= 小版本**：`agent_api_version` **仍是 1**，
+  设备端忽略它时行为必须与旧版逐字一致（只是大字页少一块内容）。也**不**走
+  `bootstrap`：身份页由平台用 adb 推，加进 bootstrap 没人用还会让契约多一处要同步。
+- `agent_api_version`（当前 **1**）在每次 `bootstrap` 响应里返回
+- **设备端**：启动时对比自己实现的版本，不一致要在日志里明确记下来（不要静默）
+- **平台端**：
+  - 加字段 / 加接口 = 小版本，设备端忽略未知字段即可
+  - 改已有字段语义 / 删字段 / 改鉴权方式 = **大版本**，两边必须同时改
+- 改了协议，**必须同时改这份文档的两个仓库版本**（本文件是平台侧那一份）
+
+---
+
+## 7. 安全须知
+
+- **令牌是凭据**：等于"能读平台的应用清单和 APK 文件"。别写进日志、别外传、
+  别提交到 git（平台侧存在 `app_meta.agent_device_token`，会随备份一起走）
+- 平台侧这组接口**只读**：只能读清单和下载 APK，**不能**触发任务、不能改设备池、
+  不能读配置或密钥
+- 生产环境建议：令牌泄露时立即在面板点「重置令牌」
+- 设备端**不需要也不应该**拿 admin 账号密码

doc/MCP.md

@@ -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 同步红线）。

doc/MCP_DESIGN.md

@@ -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 工具层统一把关，绝不越权触碰平台红线。

doc/NOTIFY.md

@@ -0,0 +1,288 @@
+# 通知 / 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.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` 是**重启后**才发（恢复本身就是重启生效的）

doc/README.md

@@ -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) 是迁移阶段的历史记录，只增不改，不随现状改写。

doc/STF_REMOVAL.md

@@ -1,5 +1,10 @@
 # 摘除 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 已禁用）、网页看屏。

doc/backlog/TODO.md

@@ -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）。

doc/research/U2_ELEMENT_SELECTORS.md

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

doc/staffdeck/JOB_SPEC.md

@@ -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`

doc/staffdeck/KNOWLEDGE_BASE.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`

mcp_agent/__init__.py

@@ -0,0 +1 @@
+"""Agent 编排层：第三方 LLM（OpenAI 兼容）经 MCP 工具控制手机。"""

mcp_agent/agent.py

@@ -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)

mcp_agent/cli.py

@@ -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()

mcp_agent/config.py

@@ -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")

mcp_server/__init__.py

@@ -0,0 +1 @@
+"""MCP 手机控制 Server 包。"""

mcp_server/audit.py

@@ -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

mcp_server/config.py

@@ -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"))

mcp_server/direct_ops.py

@@ -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 ""

mcp_server/mcp_server.py

@@ -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()

mcp_server/platform_client.py

@@ -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

mcp_server/requirements.txt

@@ -0,0 +1,3 @@
+fastmcp>=2.0
+httpx>=0.27
+Pillow>=10.0

requirements.txt

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

scripts/migrate_sqlite_to_mysql.py

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

scripts/pack.py

@@ -1,14 +1,14 @@
 """打包脚本：把项目代码打成 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"}

scripts/regression_test.py

@@ -21,29 +21,79 @@ import signal
 # 项目根加入 sys.path（脚本在 scripts/ 下运行，保证可 import web_server/config）
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
+# Windows 控制台默认 GBK：汇总里的 ⚠/❌/✅ 会抛 UnicodeEncodeError，
+# 而且崩在"打印汇总"这一步 —— 看起来像脚本挂了、其实探测已经全跑完
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
 # 测试模式：禁用 cron 调度器（否则 test_client 会按 DB 里的任务 cron 真跑任务，
 # 干扰回归/占用设备——实测 ocr关键字任务每 30 分钟触发导致回归超时）
 os.environ["DISABLE_SCHEDULER"] = "1"
 
-# 单接口超时保护：adb 相关接口可能慢（连接/查询设备），给足时间
-signal.alarm(300)
+# 单接口超时保护：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": ["100.100.10.11:5555"], "text": "回归测试"}),
+     {"serials": [_SERIAL_PH], "text": "回归测试"}),
     ("测试步骤(wait)", "/api/steps/test",
-     {"serial": "100.100.10.11:5555",
+     {"serial": _SERIAL_PH,
       "step": {"type": "wait", "label": "等待", "params": {"max": 1, "min": 1, "probability": 100}}}),
     ("adb 终端执行", "/api/adb/cmd", {"cmd": "adb devices"}),
     ("adb 红线拦截", "/api/adb/cmd", {"cmd": "adb kill-server"}),
@@ -53,10 +103,21 @@ _KEY_POSTS = [
 _EXPECT_REJECT = {"/api/adb/cmd"}
 
 
+def _sub_serial(obj):
+    """把请求体里的 @SERIAL@ 占位替换成运行期选定的设备串（支持嵌套 list/dict）。"""
+    if isinstance(obj, str):
+        return _TEST_SERIAL if obj == _SERIAL_PH else obj
+    if isinstance(obj, list):
+        return [_sub_serial(x) for x in obj]
+    if isinstance(obj, dict):
+        return {k: _sub_serial(v) for k, v in obj.items()}
+    return obj
+
+
 def _fill_path_params(rule):
     """把路由路径参数 <xxx> 替换为测试值（serial 用真实设备）。"""
     url = rule
-    url = url.replace("<serial>", "100.100.10.11:5555")
+    url = url.replace("<serial>", _TEST_SERIAL)
     url = url.replace("<apk_id>", "x")
     url = url.replace("<action_id>", "x")
     url = url.replace("<device_id>", "x")
@@ -135,7 +196,12 @@ def main():
     print(f"写操作路由: {len(write_rules)} 个（空 body 探测）")
 
     # ========== 3. 关键业务 POST（真实参数） ==========
+    global _TEST_SERIAL
+    _TEST_SERIAL = _pick_serial()
+    print(f"测试目标设备: {_TEST_SERIAL}")
     for name, url, body in _KEY_POSTS:
+        # 占位符换成运行期挑到的真实设备（含嵌套列表）
+        body = _sub_serial(body)
         try:
             r = c.post(url, json=body, headers=H)
             j = r.get_json() if r.is_json else None

scripts/sql/init_mysql_5.7.sql

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

scripts/start.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
-# 容器启动脚本：安装依赖 + 环境修复 + 启动 web_server。
-# compose 的 python-app 服务 command 指向本脚本。
+# 容器启动脚本：依赖安装（仅首次/缺失时）+ 环境修复 + 启动 web_server。
+# compose 的 python-app 服务 command 指向本脚本（不要在 compose 里再跑 pip，
+# 否则每次容器重启都重装依赖——实测每轮重新下载 opencv 5.0(73MB) 并破坏 cv2）。
 #
 # 为什么需要环境修复（必须在 pip install 之后）：
 #   rapidocr_onnxruntime 的依赖声明是 opencv-python（GUI 版），pip 解析依赖时
@@ -8,18 +9,39 @@
 #   直接崩溃 → RapidOCR 不可用 → 条件判断的 OCR 步骤抛异常 → 任务失败退出。
 #   因此在安装完 requirements 后，最后强制卸载 GUI 版并装 headless（幂等）。
 #   本地 Mac 有 GUI 环境不受影响。
-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 偶发丢根文件（4.14.0.94 实测 site-packages/cv2 只剩子目录，
-# cv2.abi3.so / __init__.py 缺失 → import cv2 成空壳，OCR 全挂）→ 空壳检测 + wheel 手动解压兜底（幂等）
+# ---- 依赖就绪守卫：flask/u2/uiautodev/rapidocr/cv2 全部可用则跳过安装 ----
+# （容器重启秒级启动；只有首次部署或依赖缺失时才走完整安装）
 python3 - <<'PY'
-import glob, os, shutil, site, subprocess, sys, zipfile
+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:
@@ -30,20 +52,33 @@ def cv2_ok():
 
 if cv2_ok():
     sys.exit(0)
-print("cv2 空壳，wheel 手动解压修复...")
-r = subprocess.run(["pip", "download", "--no-deps", "-q",
+print("cv2 异常，pip 强制重装 opencv-python-headless...")
+r = subprocess.run(["pip", "install", "--force-reinstall", "-q",
                     "-i", "https://pypi.tuna.tsinghua.edu.cn/simple",
-                    "-d", "/tmp/ocv", "opencv-python-headless>=4.8,<5"], capture_output=True)
-if r.returncode != 0:
-    sys.exit(1)
-w = sorted(glob.glob("/tmp/ocv/opencv_python_headless*.whl"))[-1]
-with zipfile.ZipFile(w) as z:
-    z.extractall("/tmp/ocv")
-dst = os.path.join(site.getsitepackages()[0], "cv2")
-shutil.rmtree(dst, ignore_errors=True)
-shutil.copytree("/tmp/ocv/cv2", dst)
-import cv2
-print(f"cv2 {cv2.__version__} 手动解压修复完成")
+                    "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

static/admin/admin.js

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

static/admin/agent.js

@@ -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');
+  });
+}

static/admin/apps.js

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

static/admin/base.js

@@ -3,6 +3,13 @@
 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]));}
@@ -95,17 +102,30 @@ function showTab(name){
   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(name==='tasks'){showSubTab('tasks',_activeSubs.tasks);loadTasks();loadCustomActions();
+    if(typeof loadStepDefaults==='function')loadStepDefaults();}
   if(name==='tools'){showSubTab('tools',_activeSubs.tools);loadToolsDevices();loadAdbDevices();loadTailscaleDevices();loadApks();}
-  if(name==='logs'){loadLogs();if(document.getElementById('log-auto').checked)_logTimer=setInterval(loadLogs,3000);}
+  if(name==='logs'){
+    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==='account'){showSubTab('account',_activeSubs.account||'ledger');}
   if(name==='users')loadUsers();
+  if(name==='system'){showSubTab('system',_activeSubs.system||'backup');}
 }
 
 // ================== 页内子分栏（任务/工具 通用） ==================
 // 每个带子分栏的 Tab 记住上次选中的子分栏，切走再切回来保持原位
-let _activeSubs = {tasks: 'plan', tools: 'clipboard'};
+let _activeSubs = {tasks: 'plan', tools: 'clipboard', system: 'backup', agent: 'chat',
+                   logs: 'files', account: 'ledger'};
 let _discoveryTimer = null;   // 设备自动发现 10s 轮询（仅 devpool 子分栏激活时）
 
 function showSubTab(tabId, name){
@@ -113,7 +133,19 @@ function showSubTab(tabId, name){
   const tab = document.getElementById('tab-'+tabId);
   tab.querySelectorAll('.sub-tab').forEach(b=>b.classList.toggle('active', b.dataset.sub===name));
   tab.querySelectorAll('.sub-panel').forEach(p=>p.classList.toggle('active', p.id===tabId+'-sub-'+name));
+  if(tabId==='agent' && name==='taskgen' && typeof initTaskGen==='function') initTaskGen();
+  if(tabId==='system' && name==='notify' && typeof loadNotifyPanel==='function') loadNotifyPanel();
+  if(tabId==='logs' && name==='files' && typeof loadLogs==='function') loadLogs();
+  if(tabId==='logs' && name==='steps' && typeof loadStepLogs==='function') loadStepLogs(true);
+  if(tabId==='tasks' && name==='actioncfg' && typeof loadActionConfig==='function') loadActionConfig();
+  if(tabId==='tasks' && name==='dedup' && typeof loadDedup==='function') loadDedup();
+  if(tabId==='account' && name==='ledger' && typeof loadLedger==='function') loadLedger();
+  if(tabId==='account' && name==='plan' && typeof loadReleasePlan==='function'){
+    loadReleasePlan();
+    if(typeof loadReleaseTasks==='function') loadReleaseTasks();
+  }
   if(name==='groups' && typeof loadGroups==='function') loadGroups();
+  if(name==='apks' && typeof loadAgentStore==='function') loadAgentStore();
   if(name==='devpool' && typeof loadDevPool==='function'){
     loadDevPool();
     if(typeof loadDiscovery==='function'){

static/admin/dedup.js

@@ -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');
+  });
+}

static/admin/editor.js

@@ -5,9 +5,9 @@ var STEP_LIB=[
   {type:'click',label:'点击元素',icon:'✦',cat:'interact',params:{selector_type:'xpath',selector_value:'',wait_timeout:2}},
   {type:'click_xy',label:'点击坐标',icon:'🎯',cat:'interact',params:{x:50,y:50}},
   {type:'long_click',label:'长按元素',icon:'👆',cat:'interact',params:{selector_type:'xpath',selector_value:'',duration:1.0,wait_timeout:2}},
-  {type:'swipe',label:'滑动',icon:'↕',cat:'interact',params:{direction:'up',duration_min:0.25,duration_max:0.50}},
-  {type:'swipe_until',label:'滑动直到元素',icon:'🔍',cat:'interact',params:{selector_type:'xpath',selector_value:'',direction:'up',max_swipes:8,click_when_found:true}},
-  {type:'input_text',label:'输入文字',icon:'⌨',cat:'interact',params:{mode:'random',texts:'你好\n有趣\n支持',fixed_text:'',clear_first:true}},
+  {type:'swipe',label:'滑动',icon:'↕',cat:'interact',params:{direction:'up',duration_min:0.25,duration_max:0.50,distance_ratio:0.6,jitter:0.15,humanize:true}},
+  {type:'swipe_until',label:'滑动直到元素',icon:'🔍',cat:'interact',params:{selector_type:'xpath',selector_value:'',direction:'up',max_swipes:8,click_when_found:true,duration_min:0.25,duration_max:0.50,distance_ratio:0.6,jitter:0.15,humanize:true}},
+  {type:'input_text',label:'输入文字',icon:'⌨',cat:'interact',params:{mode:'random',texts:'你好\n有趣\n支持',fixed_text:'',clear_first:true,text_source:'manual',release_topics:''}},
   {type:'clipboard',label:'剪贴板注入',icon:'📋',cat:'interact',params:{text:'',paste:true}},
   {type:'key_event',label:'按键',icon:'⌨️',cat:'interact',params:{key:'back'}},
   {type:'open_app',label:'打开App',icon:'▶',cat:'screen',params:{package:'',wait_home:false,home_feature:''}},
@@ -19,8 +19,20 @@ var STEP_LIB=[
   {type:'wait_el',label:'等待元素',icon:'⏳',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:10}},
   {type:'loop',label:'循环块',icon:'↻',cat:'flow',params:{loop_mode:'rounds',max_iterations:10,loop_duration:600,children:[]}},
   {type:'group',label:'动作组',icon:'📦',cat:'flow',params:{children:[]}},
-  {type:'if_el',label:'条件判断',icon:'❓',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:3,ocr_click:false,then:[],else:[]}}
+  {type:'if_el',label:'条件判断',icon:'❓',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:3,ocr_click:false,cmp_op:'',cmp_value:'',cmp_source:'',cmp_group:'',ident_type:'text',ident_value:'',then:[],else:[]}},
+  {type:'mark_done',label:'记为已做',icon:'✅',cat:'flow',params:{selector_type:'text',selector_value:''}},
+  {type:'notify',label:'发通知',icon:'🔔',cat:'flow',params:{title:'',message:'',level:'info'}},
+  {type:'stop_self',label:'停止本设备',icon:'⛔',cat:'flow',params:{reason:''}},
+  {type:'gesture',label:'录制手势',icon:'⏺',cat:'interact',params:{points:[],speed:1.0}}
 ];
+// 步骤默认值（「任务 → 动作配置」页配置，见 core/step_defaults.py）；新建步骤时预填
+let _stepDefaults = null;
+// 去重有效期选了「按小时」才显示小时数输入框
+function _toggleDedupHours(){
+  var sel=document.getElementById('f-dedup_reset');
+  var wrap=document.getElementById('f-dedup_hours_wrap');
+  if(sel&&wrap)wrap.style.display=(sel.value==='hours')?'inline-flex':'none';
+}
 var STEP_LIB_CATS=[['interact','交互操作'],['screen','屏幕与App'],['flow','流程控制']];
 var _customActions=[]; // 后端加载的自定义动作
 var _stepIdCounter=0;
@@ -45,20 +57,43 @@ function _stripIds(steps){
 function _findLib(type){return STEP_LIB.find(function(s){return s.type===type;});}
 // 选择器组件（类型下拉 + 值输入 + 抓取元素 + 测试按钮），click/long_click/swipe_until/wait_el/if_el 复用
 // withOcr=true 时额外提供 OCR识别 选项（图片/画布里的文字，仅条件判断支持）
-function _selRowHtml(p, extra, withOcr){
-  var types=withOcr?['xpath','description','text','resourceId','descriptionContains','className','ocr']:
-    ['xpath','description','text','resourceId','descriptionContains','className'];
+// withDedup=true 时额外提供「去重」条件类型（身份做过了吗，见 core/dedup.py）
+// keys 可换字段名（默认 selector_type/selector_value）——「去重」的身份元素用
+// ident_type/ident_value，好让同一个条件里既能有主选择器又能有身份元素
+function _selRowHtml(p, extra, withOcr, withDedup, keys){
+  keys=keys||{};
+  var kType=keys.type||'selector_type', kVal=keys.value||'selector_value';
+  var typeList=['xpath','description','text','resourceId','descriptionContains','className'];
+  // withOcr（条件判断用）额外提供"屏幕状态 / 前台App / 去重"三类非元素条件
+  var types=withOcr?typeList.concat(['ocr','screen','foreground']):typeList.slice();
+  if(withDedup)types.push('dedup');
   var labels={xpath:'xpath',description:'description',text:'text',resourceId:'resourceId',
-    descriptionContains:'descriptionContains',className:'className',ocr:'OCR识别'};
+    descriptionContains:'descriptionContains',className:'className',ocr:'OCR识别',
+    screen:'屏幕状态',foreground:'前台App是',dedup:'去重（这个身份做过了吗）'};
   var opts=types.map(function(d){
-    return '<option value="'+d+'"'+(p.selector_type===d?' selected':'')+'>'+labels[d]+'</option>';}).join('');
-  var toggle=withOcr?' onchange="_stepEditor._toggleOcrMode(this)"':'';
+    return '<option value="'+d+'"'+(p[kType]===d?' selected':'')+'>'+labels[d]+'</option>';}).join('');
+  var toggle=withOcr?' onchange="_stepEditor._condTypeChanged(this)"':'';
   var pick=_can('devices')?'<button class="btn btn-xs btn-pick" onclick="_stepEditor.openPicker(this)">抓取元素</button>':'';
   var test=_can('devices')?'<button class="btn btn-xs" onclick="_stepEditor._testStep(this)" title="在设备上试执行本步骤，验证选择器是否命中">测试</button>':'';
-  return '<div class="form-row"><div class="form-group"><label>选择器类型</label><select class="form-control" data-key="selector_type"'+toggle+'>'+opts+'</select></div>'+
-    '<div class="form-group" style="grid-column:span 2"><label>选择器值</label><div class="sel-picker">'+
-    '<input type="text" class="form-control" data-key="selector_value" value="'+esc(p.selector_value||'')+'" placeholder="如 点赞">'+pick+test+
-    '</div></div></div>'+(extra||'');
+  var isScreen=p[kType]==='screen', isFg=p[kType]==='foreground';
+  var valLabel=isScreen?'屏幕状态':(isFg?'前台包名':'选择器值');
+  var valHtml;
+  if(isScreen){
+    valHtml='<select class="form-control" data-key="'+kVal+'" style="max-width:140px">'+
+      '<option value="off"'+(p[kVal]!=='on'?' selected':'')+'>熄屏时就命中</option>'+
+      '<option value="on"'+(p[kVal]==='on'?' selected':'')+'>亮屏时就命中</option></select>';
+  }else{
+    valHtml='<input type="text" class="form-control" data-key="'+kVal+'" value="'+esc(p[kVal]||'')+
+      '" placeholder="'+(isFg?'如 com.ss.android.ugc.aweme':'如 点赞')+'">'+(isFg?'':pick+test);
+  }
+  var head='<div class="form-group"'+(keys.hideValue?' style="grid-column:span 3"':'')+'>'+
+    '<label>选择器类型</label><select class="form-control" data-key="'+kType+'"'+toggle+'>'+opts+'</select></div>';
+  // hideValue：「去重」条件不需要 selector_value（身份元素在 ident_value 里），
+  // 与其显示一个没人用的输入框，不如只留类型下拉
+  if(keys.hideValue)return '<div class="form-row">'+head+'</div>'+(extra||'');
+  return '<div class="form-row">'+head+
+    '<div class="form-group" style="grid-column:span 2"><label>'+valLabel+'</label><div class="sel-picker">'+
+    valHtml+'</div></div></div>'+(extra||'');
 }
 
 // 加载自定义动作库
@@ -69,11 +104,27 @@ function _loadCustomActions(){
   }).catch(function(){});
 }
 
+
+// 「拟人」开关 + 抖动幅度（滑动类步骤共用；见 core/humanize.py）
+function _humanizeChkHtml(p){
+  return '<div class="form-row"><div class="form-group form-check">'
+    +'<input type="checkbox" data-key="humanize" '+(p.humanize!==false?'checked':'')+'>'
+    +'<label>拟人轨迹（弧线）</label></div>'
+    +'<div class="form-group"><label>抖动幅度</label><input type="number" class="form-control" data-key="jitter" value="'
+    +(p.jitter!=null?p.jitter:0.15)+'" step="0.05" min="0" max="0.4"></div></div>';
+}
+function _humanizeRowHtml(p,extra){
+  return extra+_humanizeChkHtml(p)
+    +'<div class="help">拟人：滑动走弧线，起止点/幅度/时长每次都抖一点，并按本设备的手速与幅度偏好执行'
+    +'（每台设备风格稳定不同，批量跑时不像同步机器人）。关掉=还原成正中直线；'
+    +'抖动填 0=位置/幅度不抖（时长仍在你填的范围内随机）</div>';
+}
+
 var _stepEditor={
   _steps:[],
   _selected:[],
   _dragSuppressClick:false,
-  init:function(steps,maxDuration,draftKey,canvasId,libId){
+  init:function(steps,maxDuration,draftKey,canvasId,libId,taskExtra){
     this._draftKey=draftKey||'new';
     this._selected=[];
     this._updatePackBtns();
@@ -114,6 +165,25 @@ var _stepEditor={
       md.innerHTML='运行时长上限(秒,0=不限) <input type="number" id="f-max_duration" value="'+(maxDuration||0)+'" min="0" style="width:70px;padding:2px 6px;border:1px solid var(--border);border-radius:4px;font-size:12px">';
       head.appendChild(md);
     }
+    // 去重有效期（任务级）：**只在这一处配**——「条件判断→去重」和「记为已做」两处
+    // 各填一份的话，填不一致就会算出两个不同的 key、去重静默失效，所以强制共用。
+    var drHost=document.querySelector('#step-editor .se-head');
+    if(drHost&&!document.getElementById('f-dedup_reset')){
+      var ex=taskExtra||{};
+      var dr=document.createElement('span');
+      dr.style.cssText='font-size:11px;display:flex;align-items:center;gap:4px';
+      var selStyle='padding:2px 6px;border:1px solid var(--border);border-radius:4px;font-size:12px';
+      dr.innerHTML='去重有效期 <select id="f-dedup_reset" style="'+selStyle+'">'+
+        '<option value="day">每天一次</option>'+
+        '<option value="all">只做一次</option>'+
+        '<option value="hours">按小时</option></select>'+
+        '<span id="f-dedup_hours_wrap" style="display:none;align-items:center;gap:3px">每 '+
+        '<input type="number" id="f-dedup_hours" value="'+(ex.dedup_hours||6)+'" min="1" max="168" style="width:52px;'+selStyle+'"> 小时</span>';
+      drHost.appendChild(dr);
+      document.getElementById('f-dedup_reset').value=ex.dedup_reset||'day';
+      _toggleDedupHours();
+      document.getElementById('f-dedup_reset').addEventListener('change',_toggleDedupHours);
+    }
   },
   _ensureIds:function(steps){
     var self=this;
@@ -291,7 +361,7 @@ var _stepEditor={
       h+='<div class="help">息屏。任务结束后用，避免长时间亮屏导致烧屏/发热</div>';
     }else if(step.type==='keep_screen'){
       h+='<div class="form-group"><label>模式</label><select class="form-control" data-key="mode">'+
-        '<option value="on"'+(p.mode!=='off'?' selected':'')+'>保持亮屏（充电时屏幕常亮）</option>'+
+        '<option value="on"'+(p.mode!=='off'?' selected':'')+'>保持亮屏（把系统息屏超时顶到最大，不充电也不会黑屏）</option>'+
         '<option value="off"'+(p.mode==='off'?' selected':'')+'>恢复自动息屏</option></select></div>';
       h+='<div class="help">长任务（如养号看视频几小时）放"保持亮屏"防屏幕超时熄灭；任务结束前放"恢复自动息屏"</div>';
     }else if(step.type==='swipe'){
@@ -299,6 +369,8 @@ var _stepEditor={
         ['up','down','left','right'].map(function(d){return '<option value="'+d+'"'+(p.direction===d?' selected':'')+'>'+d+'</option>';}).join('')+'</select></div>';
       h+='<div class="form-group"><label>最短时长(秒)</label><input type="number" class="form-control" data-key="duration_min" value="'+(p.duration_min||0.25)+'" step="0.05" min="0.05"></div>';
       h+='<div class="form-group"><label>最长时长(秒)</label><input type="number" class="form-control" data-key="duration_max" value="'+(p.duration_max||0.50)+'" step="0.05" min="0.05"></div></div>';
+      h+=_humanizeRowHtml(p,'<div class="form-group"><label>幅度(屏占比)</label><input type="number" class="form-control" data-key="distance_ratio" value="'+(p.distance_ratio!=null?p.distance_ratio:0.6)+'" step="0.05" min="0.1" max="0.9"></div>');
+      h+='<div class="help">想要"照我划的那一下原样重放"，请用操作库里的《录制手势》步骤——那个是纯轨迹回放，不套这里的参数</div>';
     }else if(step.type==='click'){
       h+=_selRowHtml(p,'<div class="form-group"><label>等待超时(秒)</label><input type="number" class="form-control" data-key="wait_timeout" value="'+(p.wait_timeout||2)+'" step="0.5" min="0.5"></div>');
     }else if(step.type==='long_click'){
@@ -308,9 +380,12 @@ var _stepEditor={
       h+=_selRowHtml(p,'<div class="form-row"><div class="form-group"><label>方向</label><select class="form-control" data-key="direction">'+
         '<option value="up"'+(p.direction!=='down'?' selected':'')+'>上滑</option>'+
         '<option value="down"'+(p.direction==='down'?' selected':'')+'>下滑</option></select></div>'+
-        '<div class="form-group"><label>最多滑动次数</label><input type="number" class="form-control" data-key="max_swipes" value="'+(p.max_swipes||8)+'" min="1" max="50"></div></div>'+
+        '<div class="form-group"><label>最多滑动次数</label><input type="number" class="form-control" data-key="max_swipes" value="'+(p.max_swipes||8)+'" min="1" max="50"></div>'+
+        '<div class="form-group"><label>幅度(屏占比)</label><input type="number" class="form-control" data-key="distance_ratio" value="'+(p.distance_ratio!=null?p.distance_ratio:0.6)+'" step="0.05" min="0.1" max="0.9"></div></div>'+
         '<div class="form-group form-check"><input type="checkbox" data-key="click_when_found" '+(p.click_when_found!==false?'checked':'')+'><label>找到后点击</label></div>'+
-        '<div class="help">上滑/下滑直到目标元素出现（每次滑动后检查一次），找不到则跳过继续</div>');
+        _humanizeChkHtml(p)+
+
+        '<div class="help">上滑/下滑直到目标元素出现（每次滑动后检查一次），找不到则跳过继续。滑动同样走拟人轨迹</div>');
     }else if(step.type==='wait_el'){
       h+=_selRowHtml(p,'<div class="form-group"><label>最长等待(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||10)+'" min="1" max="120"></div>'+
         '<div class="help">等待目标元素出现（替代固定秒数等待），超时则继续</div>');
@@ -324,20 +399,64 @@ var _stepEditor={
           return '<option value="'+k[0]+'"'+(p.key===k[0]?' selected':'')+'>'+k[1]+'</option>';
         }).join('')+'</select></div>';
       h+='<div class="help">返回键用于退出评论/返回上一页，比结束App轻量</div>';
+    }else if(step.type==='notify'){
+      h+='<div class="form-group"><label>标题</label><input type="text" class="form-control" data-key="title" value="'+esc(p.title||'')+'" placeholder="如 抖音号1 掉线了（留空用任务通知）"></div>';
+      h+='<div class="form-group"><label>内容</label><textarea class="form-control" data-key="message" rows="2" style="min-height:52px">'+esc(p.message||'')+'</textarea></div>';
+      h+='<div class="form-row"><div class="form-group"><label>级别</label><select class="form-control" data-key="level">'+
+        [['info','ℹ️ 普通'],['success','✅ 正常'],['warning','⚠️ 警告'],['error','❌ 异常']].map(function(l){
+          return '<option value="'+l[0]+'"'+((p.level||'info')===l[0]?' selected':'')+'>'+l[1]+'</option>';}).join('')+
+        '</select></div></div>';
+      h+='<div class="help">推送到哪条群取决于 webhook 自己的<b>事件订阅</b>（勾了「任务自定义通知」的才收）。'
+        +'正文可用占位符：<b>{device}</b> 设备名、<b>{serial}</b> 地址、<b>{job}</b> 任务名、<b>{time}</b> 时间、'
+        +'<b>{app}</b> 当前前台包名、<b>{screen}</b> 亮屏/熄屏（后两个要查设备，不用就别写）</div>';
+    }else if(step.type==='stop_self'){
+      h+='<div class="form-group"><label>停止原因（可留空）</label><input type="text" class="form-control" data-key="reason" value="'+esc(p.reason||'')+'" placeholder="如 连续刷到广告"></div>';
+      h+='<div class="help">只停<b>本设备</b>的任务，其它设备照常；后续步骤不再执行，任务记为「被停止」而不是失败'
+        +'（不会触发失败重试）。常配合「条件判断」用：命中条件 → 先「发通知」再「停止本设备」</div>';
+    }else if(step.type==='gesture'){
+      var pts=(p.points||[]);
+      var dur=pts.length?pts[pts.length-1][2]:0;
+      h+='<div class="form-row"><div class="form-group" style="flex:2"><label>录制状态</label>'+
+        '<div style="padding:6px 0;font-size:13px">'+(pts.length
+          ? (pts.length+' 个轨迹点 · 时长 '+(dur/1000).toFixed(2)+' 秒 · 起点 ('+pts[0][0]+','+pts[0][1]+')')
+          : '<span class="text-muted">还没有录制</span>')+'</div></div>';
+      if(_can('devices')){
+        h+='<div class="form-group"><button class="btn btn-sm btn-primary" onclick="_stepEditor.recordInto(this,\'phone\')">● 手机上录</button></div>';
+        h+='<div class="form-group"><button class="btn btn-sm" onclick="_stepEditor.recordInto(this,\'web\')">● 网页上录</button></div>';
+      }
+      h+='<div class="form-group"><label>速度</label><input type="number" class="form-control" data-key="speed" value="'+(p.speed!=null?p.speed:1.0)+'" step="0.1" min="0.1" max="5"></div>';
+      h+='<div class="form-group"><button class="btn btn-sm btn-danger" onclick="_stepEditor.clearGesture(this)">清空</button></div></div>';
+      h+='<div class="help">这是<b>纯录制回放</b>：路径与时长照录制原样重放，不做弧线/抖动/手速那套加工（和「滑动」步骤是两回事）。'
+        +'<b>手机上录</b>=用手指在真机上划（最真实）；<b>网页上录</b>=在弹窗画面里按住鼠标拖。'
+        +'轨迹按屏幕绝对像素存，换分辨率不同的设备可能偏，同型号/同分辨率最稳</div>';
     }else if(step.type==='wait'){
       h+='<div class="form-row"><div class="form-group"><label>最短(秒)</label><input type="number" class="form-control" data-key="min" value="'+(p.min||1.0)+'" step="0.5" min="0.1"></div>';
       h+='<div class="form-group"><label>最长(秒)</label><input type="number" class="form-control" data-key="max" value="'+(p.max||3.0)+'" step="0.5" min="0.1"></div></div>';
+      h+='<div class="form-group form-check"><input type="checkbox" data-key="vary_pace" '+(p.vary_pace?'checked':'')+'><label>按设备节奏微调（0.8~1.35 倍）</label></div>';
+      h+='<div class="help">勾上后每台设备按自己的节奏缩放这个等待：批量跑时设备之间会逐渐错开，不再整齐划一。代价是实际时长不再严格等于上面填的值</div>';
     }else if(step.type==='clipboard'){
       h+='<div class="form-group"><label>注入内容</label><textarea class="form-control" data-key="text" rows="3" style="font-family:monospace;min-height:70px">'+esc(p.text||'')+'</textarea></div>';
       h+='<div class="form-group form-check"><input type="checkbox" data-key="paste" '+(p.paste!==false?'checked':'')+'><label>注入后立即粘贴（需输入框已聚焦）</label></div>';
       h+='<div class="help">批量发链接场景：先"点击元素"聚焦评论区输入框，再执行本步骤注入+粘贴；循环里依次更换注入内容即可逐个发</div>';
     }else if(step.type==='input_text'){
       const im=p.mode==='fixed'?'fixed':'random';
-      h+='<div class="form-group"><label>输入模式</label><select class="form-control" data-key="mode" onchange="_stepEditor._toggleInputMode(this)">'+
+      const tsrc=p.text_source||'manual';
+      const fromPlan=(tsrc!=='manual');
+      // 取值来源：默认手填（行为与以前一致）；也可以直接吃「发布计划」里那一条的标题
+      h+='<div class="form-group"><label>取值来源</label><select class="form-control" data-key="text_source" onchange="_stepEditor._inputSourceChanged(this)">'+
+        [['manual','手填 / 随机候选（默认）'],['release_title','发布计划这一条的标题'],['release_title_topics','发布计划标题 + 话题']]
+          .map(function(o){return '<option value="'+o[0]+'"'+(tsrc===o[0]?' selected':'')+'>'+o[1]+'</option>';}).join('')+
+        '</select><div class="help">选"发布计划"时，标题由前面的「推送发布视频」那一步取出来（同一次运行里传递；没取到会跳过并告警）—— 你就不用把同一句文案再抄一遍了</div></div>';
+      if(fromPlan){
+        h+='<div class="form-group" data-key-wrap="release_topics" style="display:'+(tsrc==='release_title_topics'?'block':'none')+'"><label>话题（逗号分隔，不带 # 会自动补）</label><input type="text" class="form-control" data-key="release_topics" value="'+esc(p.release_topics||'')+'" placeholder="如 苏州,日常"></div>';
+        h+='<div class="help" style="color:#f59e0b">取计划标题时<b>会回读输入框校验</b>：抖音的输入框有时不吃键盘输入，不校验就可能发出一篇空文案；校验不过会自动改走剪贴板粘贴再验一次</div>';
+      }
+      // 手填那两块：**只隐藏不删**（_syncParams 按 DOM 存在与否收集，删了会把用户填的值抹掉）
+      h+='<div class="form-group" style="display:'+(fromPlan?'none':'block')+'"><label>输入模式</label><select class="form-control" data-key="mode" onchange="_stepEditor._toggleInputMode(this)">'+
         '<option value="random"'+(im==='random'?' selected':'')+'>随机候选</option>'+
         '<option value="fixed"'+(im==='fixed'?' selected':'')+'>指定文字</option></select></div>';
-      h+='<div class="form-group" data-mode="random" style="display:'+(im==='random'?'block':'none')+'"><label>候选文字（每行一个，随机选一条）</label><textarea class="form-control" data-key="texts" rows="4" style="font-family:monospace;min-height:80px">'+esc(p.texts||'你好\n有趣\n支持')+'</textarea></div>';
-      h+='<div class="form-group" data-mode="fixed" style="display:'+(im==='fixed'?'block':'none')+'"><label>指定文字</label><input type="text" class="form-control" data-key="fixed_text" value="'+esc(p.fixed_text||'')+'"></div>';
+      h+='<div class="form-group" data-mode="random" style="display:'+((!fromPlan&&im==='random')?'block':'none')+'"><label>候选文字（每行一个，随机选一条）</label><textarea class="form-control" data-key="texts" rows="4" style="font-family:monospace;min-height:80px">'+esc(p.texts||'你好\n有趣\n支持')+'</textarea></div>';
+      h+='<div class="form-group" data-mode="fixed" style="display:'+((!fromPlan&&im==='fixed')?'block':'none')+'"><label>指定文字</label><input type="text" class="form-control" data-key="fixed_text" value="'+esc(p.fixed_text||'')+'"></div>';
       h+='<div class="form-group form-check"><input type="checkbox" data-key="clear_first" '+(p.clear_first!==false?'checked':'')+'><label>输入前先清空</label></div>';
       h+='<div class="help">需先用"点击元素"步骤定位到输入框，本步骤只负责输入文字</div>';
     }else if(step.type==='loop'){
@@ -353,12 +472,83 @@ var _stepEditor={
       h+='<div class="help">动作组：按顺序执行下方子步骤一次。把多个步骤打包成一个可复用的整体。</div>';
       h+='<div class="form-group"><button class="btn btn-xs btn-primary" onclick="_stepEditor.saveAsCustomAction(\''+esc(step.id||'')+'\')">存为自定义动作</button> <span class="help" style="display:inline">把本组步骤保存到左侧自定义动作库，方便复用</span></div>';
     }else if(step.type==='if_el'){
+      // 屏幕状态 / 前台App / 去重 是"直接读设备当前状态或账本"，没有等待超时、也没有选择器可抓
+      var isDedup=(p.selector_type==='dedup');
+      var dyn=(p.selector_type==='screen'||p.selector_type==='foreground'||isDedup);
+      // 文本比对：屏幕状态没有文本可比（亮/熄）、去重也不比文本，只有元素/OCR/前台 App 才给这块
+      // 候选值来源：默认"手填"（行为与以前完全一致）；也可以直接吃「账号」页的台账
+      var cmpSrc=p.cmp_source||'';
+      var fromLedger=(cmpSrc==='device'||cmpSrc==='all'||cmpSrc==='group');
+      var cmpRow=dyn?'':'<div class="form-row"><div class="form-group"><label>文本比对</label>'+
+        '<select class="form-control" data-key="cmp_op">'+
+        [['','不比对（只看元素在不在）'],['等于','等于'],['不等于','不等于'],['包含','包含'],['不包含','不包含']]
+          .map(function(o){return '<option value="'+o[0]+'"'+((p.cmp_op||'')===o[0]?' selected':'')+'>'+o[1]+'</option>';}).join('')+
+        '</select></div>'+
+        '<div class="form-group"><label>候选值来源</label>'+
+        '<select class="form-control" data-key="cmp_source" onchange="_stepEditor._cmpSourceChanged(this)">'+
+        [['','手填（默认）'],['device','本机台账'],['all','全部台账'],['group','按设备分组'],
+         ['release','本机当前发布计划（要发的那个号）']]
+          .map(function(o){return '<option value="'+o[0]+'"'+((p.cmp_source||'')===o[0]?' selected':'')+'>'+o[1]+'</option>';}).join('')+
+        '</select><div class="help">'+(p.cmp_source==='release'
+          ? '取<b>本机下一条要发的发布计划</b>的抖音号 + 账号名称（推送前校验"当前登录的是不是要发的号"就用它）'
+          : '台账在「账号」页维护')+'</div></div>'+
+        (cmpSrc==='group'?
+          '<div class="form-group"><label>设备分组名</label>'+
+          '<input class="form-control" data-key="cmp_group" value="'+esc(p.cmp_group||'')+'" '+
+          'placeholder="分组名（工具→设备分组）"></div>':'')+
+        // 选台账时**只隐藏、不删**这个输入框：_syncParams 是按 DOM 存在与否收集的，
+        // 删了就等于把用户手填的值悄悄抹掉（同类坑见本文件 927 行附近的注释）
+        '<div class="form-group" style="grid-column:span 2'+(fromLedger?';display:none':'')+'">'+
+        '<label>比对的值（可多行，任一命中即可）</label>'+
+        '<textarea class="form-control" data-key="cmp_value" rows="2" style="font-family:var(--mono)" '+
+        'placeholder="如 35377983067&#10;35377983068">'+esc(p.cmp_value||'')+'</textarea>'+
+        '<div class="help">一行一个（也认 <code>|</code> 分隔）：<b>任意一个命中就算命中</b>——多个号的场景把号都列上。'+
+        '<b>逗号不当分隔符</b>，因为要比对的文本本身常带逗号'
+        +(fromLedger?'<br><b>候选值来自台账</b>：这台设备在台账里登记的抖音号会作为候选，'
+          +'手填的值<b>追加</b>在后面（台账取不到号时只用手填值，不会把任务打哑）。'
+          +'<br>⚠ 台账只提供<b>比对用的号</b>；<b>不要</b>把台账号填到「去重」的身份元素里'
+          +'（身份是元素原文、逐字比，格式不同会让去重静默失效）。':'')
+        +'</div></div></div>';
+      // 「去重」条件：身份元素用 ident_type/ident_value（主选择器那行只剩类型下拉）
+      var identRow=isDedup?_selRowHtml(p,
+        '<div class="help"><b>身份元素</b>：填"账号"那个元素（点「抓取元素」选，如抖音号那个 TextView）。'
+        +'<b>留空 = 用本设备当身份</b>（一号一机时这样就行）。'
+        +'<br>身份<b>读不到时不会去重</b>（当"没做过"照常执行）——宁可重复一次，也不会误判成"做过"而漏做。'
+        +'<br>有效期在上方任务级的<b>「去重有效期」</b>里设，检查和记账共用一套（不用在步骤里各填一遍）。</div>',
+        false, false, {type:'ident_type', value:'ident_value'}):'';
       h+=_selRowHtml(p,
-        '<div class="form-group"><label>查找超时(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||3)+'" min="0.5" max="30" step="0.5"></div>'+
+        (dyn?'':'<div class="form-group"><label>查找超时(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||3)+'" min="0.5" max="30" step="0.5"></div>'+
         '<div class="form-group form-check" data-ocr-field style="display:'+(p.selector_type==='ocr'?'block':'none')+'">'+
         '<input type="checkbox" data-key="ocr_click" '+(p.ocr_click?'checked':'')+'><label>OCR 命中后自动点击该文字</label></div>'+
-        '<div class="help">超时内找到元素 → 执行下方"✅ 找到时"分支；未找到 → 执行"❌ 未找到时"分支。两分支可放任意步骤，也可再嵌套条件判断/循环；'+
-        '<b>OCR识别</b>可匹配图片/画布里的文字（截屏识别，跨平台）</div>', true);
+        cmpRow)+
+        '<div class="help">'+(isDedup
+          ? '命中 → 执行下方"✅ 找到时"分支；未命中 → 执行"❌ 未找到时"分支。'
+            +'<b>去重</b>读的是平台的「去重账本」（所有设备共享一份，见「任务 → 去重记录」）：'
+            +'<b>任何一台设备做过了，其余设备的这一步都会命中</b>——'
+            +'所以多个手机跑同一个任务、反复重跑，也不会把同一个号做两次。'
+            +'<br>建议这样摆：<b>命中分支</b>放「停止本设备」或「发通知」；'
+            +'<b>未命中分支</b>里放要做的动作（评论…），动作后面跟一个「记为已做」。'
+            +'<br>⚠ 记账要放在动作<b>成功之后</b>（用「记为已做」步骤），失败就不记账、下次还会重试。'
+          : (dyn
+          ? '命中 → 执行下方"✅ 找到时"分支；未命中 → 执行"❌ 未找到时"分支。<b>屏幕状态</b>读系统 mWakefulness（亮/熄），'
+            +'<b>前台App是</b>判断当前前台是不是某个包名——都只看当前状态，不等待。'
+          : '超时内找到元素 → 执行下方"✅ 找到时"分支；未找到 → 执行"❌ 未找到时"分支。两分支可放任意步骤，也可再嵌套条件判断/循环；'
+            +'<b>OCR识别</b>可匹配图片/画布里的文字（截屏识别，跨平台）'
+            +'<br><b>文本比对</b>（可选）：填了就把找到的那个元素的<b>文本</b>和"比对的值"比，'
+            +'比中了才算命中。例：元素文本是 <code>抖音号：35377983067</code>，'
+            +'想判断"这台登录的是不是这个号"，选<b>包含</b>、值填 <code>35377983067</code> 即可（要整段一模一样才用"等于"）。'
+            +'多个值一行一个，<b>任一命中即可</b>——"这几个号都算我的"。'
+            +'<br>⚠ 元素<b>没找到</b>时一律算未命中（走"未找到时"分支）——"没读到"不会被当成"和我设的不一样"。'))+'</div>',
+        true, true, isDedup?{hideValue:true}:null)+identRow;
+    }else if(step.type==='mark_done'){
+      h+=_selRowHtml(p,
+        '<div class="help">把身份值记进平台「去重账本」（所有设备共享一份）。'
+        +'放在动作<b>成功之后</b>——动作失败就不会记账，下次重跑还会重试这台设备。'
+        +'<br>✅ <b>留空 = 自动跟随上面「去重」检查的身份</b>（推荐）：'
+        +'检查与记账必须用<b>同一个身份字符串</b>，key 才算得到一起；'
+        +'两处各配一遍的话，一边填了另一边忘了去重就会失效。'
+        +'<br>没有前置去重检查、又留空时，退回用<b>本设备</b>当身份（一号一机场景）。'
+        +'<br>有效期在上方任务级的<b>「去重有效期」</b>里设。</div>');
     }
     // 共享：触发概率（所有步骤通用，0~100）
     h+='<div class="form-row" style="margin-top:8px"><div class="form-group"><label>触发概率(%)</label><input type="number" class="form-control" data-key="probability" value="'+(p.probability!=null?p.probability:100)+'" min="0" max="100"><div class="help">0~100，&lt;100 表示按概率执行（如 30=隔几次才触发一次，适合"偶尔点赞"）</div></div></div>';
@@ -453,7 +643,44 @@ var _stepEditor={
     }
   },
   _makeStep:function(lib){
-    return {id:_newStepId(),type:lib.type,label:lib.label,params:JSON.parse(JSON.stringify(lib.params))};
+    // 参数 = STEP_LIB 出厂值 ← 用户在「动作配置」里配的默认值（有才覆盖）
+    var params=JSON.parse(JSON.stringify(lib.params));
+    var d=_stepDefaults&&_stepDefaults[lib.type];
+    if(d)Object.keys(d).forEach(function(k){ if(d[k]!==undefined)params[k]=d[k]; });
+    return {id:_newStepId(),type:lib.type,label:lib.label,params:params};
+  },
+  // 递归找步骤对象（按 id）——写入录音必须改 _steps，不能只改 DOM
+  _findStep:function(id,arr){
+    var self=this, found=null;
+    (arr||this._steps).forEach(function(st){
+      if(found)return;
+      if(st.id===id){found=st;return;}
+      _childArrs(st).forEach(function(a){ if(!found)found=self._findStep(id,a); });
+    });
+    return found;
+  },
+  // 给某个「录制手势」步骤录制轨迹（src: 'phone' 手机上录 / 'web' 网页上录）
+  recordInto:function(btn,src){
+    var card=btn.closest('.step-card');
+    var step=card?this._findStep(card.dataset.stepId):null;
+    if(!step){showToast('找不到这个步骤','error');return;}
+    if(typeof openRecorder!=='function'){showToast('录制器未加载','error');return;}
+    var self=this;
+    openRecorder({mode:'gesture', autoStartPhone: src==='phone', onDone:function(p,from){
+      step.params={points:p.points,speed:p.speed||1.0};
+      var dur=p.points.length?p.points[p.points.length-1][2]:0;
+      step.label='录制手势 '+(from==='phone'?'手机':'网页')+' '+p.points.length+'点';
+      self._renderCanvas();
+      showToast('已录到 '+(p.points.length)+' 个点 / '+(dur/1000).toFixed(2)+' 秒','success');
+    }});
+  },
+  clearGesture:function(btn){
+    var card=btn.closest('.step-card');
+    var step=card?this._findStep(card.dataset.stepId):null;
+    if(!step){return;}
+    step.params={points:[],speed:1.0};
+    this._renderCanvas();
+    showToast('已清空录制的轨迹','success');
   },
   // 测试此步骤：在选中设备上试执行当前步骤，验证选择器
   _testStep:function(btn){
@@ -480,10 +707,7 @@ var _stepEditor={
       if(!list)return;
       if(!r||!r.ok){list.innerHTML='<div class="se-empty">'+esc((r&&r.error)||'获取设备失败')+'</div>';return;}
       list.innerHTML=(r.devices||[]).map(function(d){
-        return '<div class="el-device-card" onclick="_stepEditor._runTestStep(\''+esc(d.serial)+'\')">'+
-          '<div class="edc-icon">📱</div>'+
-          '<div class="edc-info"><div class="edc-serial">'+esc(d.serial)+'</div>'+
-          '<div class="edc-model">'+esc(d.model||d.product||'')+'</div></div></div>';
+        return self._devCard(d, "_stepEditor._runTestStep('"+esc(d.serial)+"')");
       }).join('')||'<div class="se-empty">无可用设备</div>';
     });
   },
@@ -625,11 +849,26 @@ var _stepEditor={
       g.style.display=g.dataset.lmode===mode?'block':'none';
     });
   },
+  // 输入文字：取值来源切到"发布计划"时，把手填那两块藏起来（话题输入框反过来显示）
+  _inputSourceChanged:function(sel){
+    this._syncFromDom();          // 同 _cmpSourceChanged：不先同步，重渲染会吞掉刚改的值
+    var self=this;
+    setTimeout(function(){self._renderCanvas();},0);
+  },
+  // 条件判断：候选值来源切到台账时，把"比对的值"藏起来（按分组还要显示分组名输入框）
+  _cmpSourceChanged:function(sel){
+    // 同 _condTypeChanged：先把 DOM 的值同步回 _steps，否则重渲染会吞掉刚改的东西
+    this._syncFromDom();
+    var self=this;
+    setTimeout(function(){self._renderCanvas();},0);
+  },
   // 条件判断：选择器类型切到 OCR 时显示"命中后点击"开关
-  _toggleOcrMode:function(sel){
-    var card=sel.closest('.step-card');
-    var f=card&&card.querySelector('[data-ocr-field]');
-    if(f)f.style.display=sel.value==='ocr'?'block':'none';
+  _condTypeChanged:function(sel){
+    // 条件类型一变，"值"控件也要跟着换（元素值输入框 / 屏幕亮熄下拉 / 包名输入），
+    // 整卡重渲染最省心。先把 DOM 的值同步回 _steps，否则重渲染会丢掉刚改的东西。
+    this._syncFromDom();
+    var self=this;
+    setTimeout(function(){self._renderCanvas();},0);
   },
   // 给数组分配唯一 id，用于 move/duplicate/remove/拖拽定位到正确的父数组
   _arrId:function(arr){
@@ -694,6 +933,8 @@ var _stepEditor={
   validate:function(steps){
     // 校验步骤配置，返回警告列表
     var warnings=[];
+    // 去重：收集「条件判断→去重」与「记为已做」各自用的身份元素，最后比对是否一致
+    var dedupIdents=[], hasDedupCheck=false, hasMarkDone=false;
     function check(arr,prefix){
       arr.forEach(function(s,i){
         var name=prefix?(prefix+'.'+(i+1)):('步骤'+(i+1));
@@ -725,10 +966,49 @@ var _stepEditor={
           if(!s.params.text){
             warnings.push(name+' "'+label+'": 注入内容为空，步骤会跳过。');
           }
+        }else if(s.type==='gesture'){
+          if(!(s.params.points||[]).length){
+            warnings.push(name+' "'+label+'": 录制手势还没有轨迹，执行时会被跳过。');
+          }
         }else if(s.type==='if_el'){
-          if(!s.params.selector_value){
+          // 「去重」「屏幕状态」这两类条件**不用文本比对**（面板里那块是隐藏的）。
+          // 所以：① 留着旧 cmp_op/cmp_value 不该报警告（用户看不到、也清不掉，
+          // 只会每次保存都被打扰）；② 也别报"会被忽略"——那是设计如此。
+          var cmpUsed=(s.params.selector_type!=='screen'&&s.params.selector_type!=='dedup');
+          if(s.params.selector_type!=='dedup'&&!s.params.selector_value){
             warnings.push(name+' "'+label+'": 条件判断的选择器为空，会直接走"未找到"分支。');
           }
+          var cmpSrcV=(s.params.cmp_source||'');
+          var fromLedger=(cmpSrcV==='device'||cmpSrcV==='all'||cmpSrcV==='group');
+          // 候选值"从别处取"的那两档（台账 / 发布计划）：手填可以留空，别报"没填值"
+          var fromOther=(fromLedger||cmpSrcV==='release');
+          if(cmpUsed&&s.params.cmp_op&&!String(s.params.cmp_value||'').trim()&&!fromOther){
+            warnings.push(name+' "'+label+'": 选了"文本比对('+s.params.cmp_op+')"但没填比对的值，'
+              +'执行时永远不命中（相当于每次都走"未找到时"分支）。');
+          }
+          if(cmpUsed&&fromLedger&&s.params.cmp_op){
+            warnings.push(name+' "'+label+'": 候选值来自台账 —— 台账里没有这台设备'
+              +'（或设备池里的设备名与台账「设备号」对不上）时会取不到号，'
+              +'这一步将永远走"未找到"分支。请到「账号」页核对设备号。');
+          }
+          if(cmpUsed&&cmpSrcV==='release'&&s.params.cmp_op){
+            warnings.push(name+' "'+label+'": 候选值来自"本机当前发布计划" —— 本机没有待发的计划'
+              +'时取不到号（这一步会走"未找到"分支）。这是设计如此（宁可不发、也不发错号），'
+              +'但请确认前面有「推送发布视频」步骤、且这条计划确实排到了本机。');
+          }
+          if(s.params.selector_type==='dedup'){
+            hasDedupCheck=true;
+            // 空值也收进来：一边填了、另一边没填 = 两处身份不一致（去重会对不上），
+            // 必须报出来 —— 只收非空的话，这种最常见的不一致反而检测不到
+            dedupIdents.push({where:name,type:s.params.ident_type||'text',
+                              value:(s.params.ident_value||'').trim()});
+          }
+        }else if(s.type==='mark_done'){
+          hasMarkDone=true;
+          // 留空 = 自动跟随去重检查的身份（执行器就是这么做的），所以**空值不参与比对**；
+          // 只有"填了、且和检查侧不一样"才是真问题
+          var mv=(s.params.selector_value||'').trim();
+          if(mv)dedupIdents.push({where:name,type:s.params.selector_type||'text',value:mv});
         }
         _childArrs(s).forEach(function(a){
           if(a.length)check(a,name+' 子步骤');
@@ -736,6 +1016,28 @@ var _stepEditor={
       });
     }
     check(steps,'');
+    // 去重的两个坑，保存时直接点出来（配错的话去重会「静默失效」，最难查）
+    if(hasDedupCheck&&!hasMarkDone){
+      warnings.push('任务里有「条件判断→去重」但没有「记为已做」：做完动作不会记账，'
+        +'下次重跑还会再做一遍（去重起不到作用）。请在动作后面加一个「记为已做」。');
+    }
+    if(hasMarkDone&&!hasDedupCheck){
+      warnings.push('任务里有「记为已做」但没有「条件判断→去重」：只会记账、不会拦重复。'
+        +'请在动作前面加一个条件判断、类型选「去重」。');
+    }
+    if(dedupIdents.length>1){
+      var first=dedupIdents[0];
+      var showId=function(x){ return x.value?('「'+x.value+'」'):'（留空 → 用设备当身份）'; };
+      dedupIdents.slice(1).forEach(function(d){
+        if(d.value!==first.value||d.type!==first.type){
+          warnings.push('去重两处的身份不一致：'+first.where+' 是 '+showId(first)
+            +'，而 '+d.where+' 是 '+showId(d)
+            +' —— 身份不一致会算出两个不同的 key，去重会失效'
+            +'（检查查不到记账 / 或者反过来，结果就是重复或漏做）。'
+            +'建议把「记为已做」的身份元素留空（自动跟随检查），或两处填成同一个元素。');
+        }
+      });
+    }
     return warnings;
   },
   _syncParams:function(container,steps){
@@ -765,11 +1067,16 @@ var _stepEditor={
         self._syncParams(childWrap,steps[i].params.children);
       }
       // if_el 双分支（then/else 在 .if-branch 内，不会与上面的直接子级选择器冲突）
-      var thenWrap=card.querySelector(':scope > .if-branch .step-children.if-then');
+      //
+      // ⚠ `.if-branch` 与 `.step-children` 之间**必须是 `>`（直接子级）**：
+      // 写成后代（空格）时，条件判断里再嵌套一个条件判断的话，本卡片会**匹配到内层
+      // 那个 if_el 的分支容器**（文档顺序上更靠前），于是把内层分支的子步骤当成自己的
+      // 去同步 —— 症状：自己的步骤"填了值保存就没了"、步骤名被内层的容器步骤覆盖。
+      var thenWrap=card.querySelector(':scope > .if-branch > .step-children.if-then');
       if(thenWrap&&steps[i].params&&Array.isArray(steps[i].params.then)){
         self._syncParams(thenWrap,steps[i].params.then);
       }
-      var elseWrap=card.querySelector(':scope > .if-branch .step-children.if-else');
+      var elseWrap=card.querySelector(':scope > .if-branch > .step-children.if-else');
       if(elseWrap&&steps[i].params&&Array.isArray(steps[i].params.else)){
         self._syncParams(elseWrap,steps[i].params.else);
       }
@@ -800,8 +1107,20 @@ var _stepEditor={
     // 直接弹设备选择页（独立模态框，不影响任务编辑窗口）
     this._showDevicePicker();
   },
+  // 设备选择卡片（「抓取元素」与「测试此步骤」两处共用）：
+  // **设备名优先**，型号与地址降为副标题——同型号好几台时只有平台起的名字
+  // （A08）能认出"是哪一台"，光看 IP 选错设备是常事。
+  _devCard:function(d,onclick){
+    var sub=[d.model||d.product||'', d.serial||''].filter(Boolean).join(' · ');
+    return '<div class="el-device-card" onclick="'+onclick+'">'+
+      '<div class="edc-icon">📱</div>'+
+      '<div class="edc-info"><div class="edc-name">'+esc(d.name||d.serial)+'</div>'+
+      '<div class="edc-serial">'+esc(sub)+'</div></div>'+
+      (d.status?'<span class="edc-status">'+esc(d.status)+'</span>':'')+'</div>';
+  },
   // 步骤1：设备选择页
   _showDevicePicker:function(){
+    var self=this;
     document.getElementById('el-picker-title').textContent='抓取元素 - 选择设备';
     document.getElementById('el-picker-body').innerHTML='<div class="el-device-grid"><div class="egd-title">选择要抓取元素的设备</div><div id="el-device-list">加载中...</div></div>';
     document.getElementById('el-picker-footer').innerHTML='<button class="btn" onclick="closeElPicker()">取消</button>';
@@ -812,11 +1131,7 @@ var _stepEditor={
       var devices=res.devices||[];
       if(!devices.length){list.innerHTML='<div class="se-empty">uiauto2 未发现已连接设备</div>';return;}
       list.innerHTML=devices.map(function(d){
-        return '<div class="el-device-card" onclick="_stepEditor._showElPicker(\''+esc(d.serial)+'\')">'+
-          '<div class="edc-icon">📱</div>'+
-          '<div class="edc-info"><div class="edc-serial">'+esc(d.serial)+'</div>'+
-          '<div class="edc-model">'+esc(d.model||d.product||'')+'</div></div>'+
-          '<span class="edc-status">'+esc(d.status||'device')+'</span></div>';
+        return self._devCard(d, "_stepEditor._showElPicker('"+esc(d.serial)+"')");
       }).join('');
     }).catch(function(e){
       document.getElementById('el-device-list').innerHTML='<div class="se-empty">请求失败: '+esc(e)+'<br><button class="btn btn-sm" style="margin-top:10px" onclick="_stepEditor._showDevicePicker()">重试</button></div>';
@@ -831,7 +1146,7 @@ var _stepEditor={
       '<div class="el-picker-main">'+
         '<div class="el-shot-wrap">'+
           '<div class="el-shot-toolbar">'+
-            '<button class="btn" onclick="_stepEditor._refreshShot()" title="重新拉取截图和元素树（界面变化后刷新用）">刷新截图+元素</button>'+
+            '<button class="btn" onclick="_stepEditor._refreshShot()" title="重新抓取截图与元素树（一次取齐）">重新抓取</button>'+
             '<span class="el-shot-info" id="el-shot-info">加载中...</span>'+
           '</div>'+
           '<div class="el-shot-container" id="el-shot-container">'+
@@ -839,72 +1154,160 @@ var _stepEditor={
           '</div>'+
         '</div>'+
         '<div class="el-list-wrap">'+
-          '<input type="text" class="el-picker-search" id="el-search" placeholder="搜索 resource-id/text/description..." oninput="_stepEditor._filterEl(this.value)">'+
-          '<div class="el-picker-list" id="el-list"><div class="se-empty">加载元素树...</div></div>'+
+          '<div class="el-tabs">'+
+            '<button class="el-tab active" data-pane="tree" onclick="_stepEditor._tab(this)">层级</button>'+
+            '<button class="el-tab" data-pane="attr" onclick="_stepEditor._tab(this)">属性</button>'+
+            '<button class="el-tab" data-pane="color" onclick="_stepEditor._tab(this)">颜色</button>'+
+          '</div>'+
+          '<div class="el-pane active" id="el-pane-tree">'+
+            '<input type="text" class="el-picker-search" id="el-search" placeholder="搜索 resource-id/text/description..." oninput="_stepEditor._filterEl(this.value)">'+
+            '<div class="el-picker-list" id="el-list" style="max-height:calc(100% - 42px)"><div class="se-empty">加载元素树...</div></div>'+
+          '</div>'+
+          '<div class="el-pane" id="el-pane-attr"><div class="se-empty">点左侧图上的元素，或点「层级」里的条目看属性</div></div>'+
+          '<div class="el-pane" id="el-pane-color">'+
+            '<div style="padding:8px 12px;font-size:11.5px;color:var(--text-light)">把鼠标移到左侧图上取色；点元素可看该元素的主色</div>'+
+            '<div id="el-color-list"></div>'+
+          '</div>'+
         '</div>'+
       '</div>';
     document.getElementById('el-picker-footer').innerHTML=
       '<button class="btn" onclick="_stepEditor._showDevicePicker()">← 返回选设备</button>'+
-      '<button class="btn" onclick="closeElPicker()">取消</button>';
-    // 加载截图和元素树（_refreshShot 内部同时刷新两者）
-    self._refreshShot();
+      '<button class="btn" onclick="closeElPicker()">取消</button>'+
+      '<span class="text-muted" style="margin-left:10px;font-size:11.5px">'
+      +'提示：先「▶ 点一下」在设备上验证位置，再点元素回填选择器；'
+      +'「✓ 测选择器」会用将填入的选择器真跑一次点击</span>';
+    // 一次取齐截图 + 元素树（见 _loadSnapshot 的说明）
+    self._loadSnapshot();
   },
-  // 拉取元素树（进入页面和刷新时共用；带时间戳防缓存）
-  _loadElData:function(){
-    var serial=this._elSerial;
-    if(!serial)return;
-    var listEl=document.getElementById('el-list');
-    if(listEl)listEl.innerHTML='<div class="se-empty">加载元素树...</div>';
-    var self=this;
-    fetch('/api/uiauto/elements?serial='+encodeURIComponent(serial)+'&_='+Date.now())
-      .then(function(r){return r.json();})
-      .then(function(data){
-        var le=document.getElementById('el-list');
-        if(!le)return;
-        if(!data.ok){
-          le.innerHTML='<div class="se-empty">'+esc(data.error||'抓取失败')+'</div>';
-          return;
-        }
-        self._elData=data.elements||[];
-        self._renderEl(self._elData);
-        // 刷新后保持搜索过滤状态
-        var search=document.getElementById('el-search');
-        if(search&&search.value)self._filterEl(search.value);
-        self._renderOverlays();
-      })
-      .catch(function(e){
-        var le=document.getElementById('el-list');
-        if(le)le.innerHTML='<div class="se-empty">请求失败: '+esc(e)+'</div>';
-      });
+  // 右侧页签切换
+  _tab:function(btn){
+    var pane=btn.dataset.pane;
+    document.querySelectorAll('#el-picker-body .el-tab').forEach(function(b){
+      b.classList.toggle('active', b===btn);
+    });
+    ['tree','attr','color'].forEach(function(p){
+      var el=document.getElementById('el-pane-'+p);
+      if(el)el.classList.toggle('active', p===pane);
+    });
   },
-  // 刷新截图
-  _refreshShot:function(){
+  // 属性页：选中元素的全部属性
+  _renderAttrs:function(i){
+    var el=(this._elData||[])[i];
+    var box=document.getElementById('el-pane-attr');
+    if(!box)return;
+    if(!el){box.innerHTML='<div class="se-empty">点左侧图上的元素，或点「层级」里的条目看属性</div>';return;}
+    var sg=el.suggested||{};
+    // 稳定性说明：把"这个选择器靠什么定位"写清楚，用户才知道它会不会因为界面变化而失效
+    var stab=sg.semantic?'✓ 语义型 —— 靠 @'+(sg.via||'')+' 限定，不依赖同类元素个数，换设备/换版本仍命中'
+            :sg.indexed?'⚠ 序号型 —— 依赖「同类元素共 '+sg.total+' 个、取第 '+sg.occ+' 个」，界面一变就失配'
+            :sg.broad?'⚠ 宽泛 —— 无唯一属性，可能误匹配其他元素'
+            :(sg.value?'✓ 唯一属性，直接定位':'—');
+    var rows=[['建议选择器', sg.value||'(无可靠选择器)'],['选择器稳定性', stab],
+              ['class', el.class||''], ['resource-id', el.resource_id||''],
+              ['text', el.text||''], ['content-desc', el.description||''],
+              ['package', el.package||''], ['clickable', el.clickable||''],
+              ['bounds', el.bounds||''], ['层级深度', String(el.depth||0)]];
+    box.innerHTML=rows.map(function(r){
+      return '<div class="el-attr"><b>'+esc(r[0])+'</b><span>'+esc(r[1]||'-')+'</span></div>';
+    }).join('');
+  },
+  // 颜色页：鼠标位置的像素色 + 选中元素的主色
+  _pixelAt:function(x,y){
+    try{
+      var c=this._colorCanvas, img=document.getElementById('el-shot-container').querySelector('img');
+      if(!c||!img)return null;
+      if(c.width!==img.naturalWidth){c.width=img.naturalWidth;c.height=img.naturalHeight;}
+      var ctx=c.getContext('2d');
+      ctx.drawImage(img,0,0);
+      var d=ctx.getImageData(Math.max(0,Math.min(c.width-1,x)),Math.max(0,Math.min(c.height-1,y)),1,1).data;
+      return '#'+[d[0],d[1],d[2]].map(function(v){return ('0'+v.toString(16)).slice(-2);}).join('');
+    }catch(e){return null;}
+  },
+  _updatePixel:function(x,y){
+    var box=document.getElementById('el-color-list');
+    if(!box)return;
+    var col=this._pixelAt(Math.round(x),Math.round(y));
+    if(!col)return;
+    box.innerHTML='<div class="el-color-row"><span class="el-swatch" style="background:'+col+'"></span>'+
+      '<span>光标处 '+esc(col)+'</span></div>'+
+      (box.dataset.dom||'');
+  },
+  _renderColors:function(i){
+    var box=document.getElementById('el-color-list');
+    if(!box)return;
+    var el=(this._elData||[])[i];
+    var dom='';
+    if(el&&el.bounds){
+      var m=el.bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+      if(m){
+        var x=Math.round((+m[1]+ +m[3])/2), y=Math.round((+m[2]+ +m[4])/2);
+        var c=this._pixelAt(x,y);
+        if(c) dom='<div class="el-color-row"><span class="el-swatch" style="background:'+c+'"></span>'+
+          '<span>选中元素中心 '+esc(c)+'</span></div>';
+      }
+    }
+    box.dataset.dom=dom;
+    box.innerHTML=dom||'<div class="se-empty" style="padding:12px">把鼠标移到左侧图上取色</div>';
+  },
+  // 一次取齐：截图 + 元素树（后端用原生 u2 背靠背取）
+  // 为什么不再分两个接口：截图与元素树分两次拿，中间隔着 dump 本身的 1.3~1.8 秒，
+  // 界面只要在动（信息流/视频/加载），框就会落在旧位置上（"抓取错位"）。
+  _loadSnapshot:function(){
     var serial=this._elSerial;
     if(!serial)return;
     var container=document.getElementById('el-shot-container');
-    if(!container)return;
-    container.innerHTML='<div class="el-shot-loading">正在获取截图...</div>';
     var info=document.getElementById('el-shot-info');
-    if(info)info.textContent='加载中...';
+    var old=document.querySelector('.el-shot-warn');
+    if(old)old.remove();
+    if(container)container.innerHTML='<div class="el-shot-loading">正在抓取（截图 + 元素树一次取齐）…</div>';
+    if(info)info.textContent='抓取中…';
     var self=this;
-    var img=new Image();
-    img.onload=function(){
-      container.innerHTML='';
-      container.appendChild(img);
-      var infoEl=document.getElementById('el-shot-info');
-      if(infoEl)infoEl.textContent=img.naturalWidth+'x'+img.naturalHeight;
-      // 截图加载完后重新渲染元素边界框
-      self._renderOverlays();
-    };
-    img.onerror=function(){
-      container.innerHTML='<div class="el-shot-loading">截图加载失败</div>';
-      var infoEl=document.getElementById('el-shot-info');
-      if(infoEl)infoEl.textContent='失败';
-    };
-    img.src='/api/uiauto/screenshot?serial='+encodeURIComponent(serial)+'&_='+Date.now();
-    // 同时重新拉取元素树——只刷截图会导致"截图是新的、元素框是旧的"错位
-    this._loadElData();
+    fetch('/api/uiauto/snapshot?serial='+encodeURIComponent(serial)+'&_='+Date.now())
+      .then(function(r){return r.json();})
+      .then(function(d){
+        if(!d.ok){
+          if(container)container.innerHTML='<div class="el-shot-loading">'+esc(d.error||'抓取失败')+'</div>';
+          if(info)info.textContent='失败';
+          return;
+        }
+        self._elData=d.elements||[];
+        if(d.unstable){
+          var w=document.createElement('div');
+          w.className='el-shot-warn';
+          w.innerHTML='⚠ 抓取期间界面有变化，框可能对不上 —— 建议把设备停在<b>静止界面</b>后点「重新抓取」';
+          container.parentNode.insertBefore(w, container);
+        }
+        var img=new Image();
+        img.onload=function(){
+          container.innerHTML='';
+          container.appendChild(img);
+          if(info){
+            info.textContent=d.width+'x'+d.height+' · '+self._elData.length+' 个元素 · '
+              +(d.cost_ms||0)+'ms'+(d.unstable?' · ⚠ 界面在变化':'');
+          }
+          // 图片显示尺寸一变（窗口缩放、面板宽度变化、滚动条出现…）就重算所有框 ——
+          // 这是"完全不错位"的保证：框永远跟着图片走，不留旧坐标
+          if(window.ResizeObserver){
+            if(self._ro)self._ro.disconnect();
+            self._ro=new ResizeObserver(function(){ self._renderOverlays(); });
+            self._ro.observe(img);
+          }
+          self._colorCanvas=document.createElement('canvas');
+          self._renderOverlays();
+          self._renderAttrs(null);
+          self._renderColors(null);
+        };
+        img.src=d.image;
+        self._renderEl(self._elData);
+        var search=document.getElementById('el-search');
+        if(search&&search.value)self._filterEl(search.value);
+      })
+      .catch(function(e){
+        if(container)container.innerHTML='<div class="el-shot-loading">请求失败: '+esc(e)+'</div>';
+      });
   },
+  // 兼容旧调用名（工具栏「重新抓取」按钮）
+  _refreshShot:function(){ this._loadSnapshot(); },
   // 在截图上渲染元素边界框（可点击）
   _renderOverlays:function(){
     var container=document.getElementById('el-shot-container');
@@ -944,6 +1347,32 @@ var _stepEditor={
       });
       // 点击截图：按 bounds 命中测试，选中最小的（最深的）元素，
       // 而不是被 DOM 层叠中的大容器/大兄弟挡住
+      container.onmousemove=function(e){
+        var im=container.querySelector('img');
+        if(!im||!self._elData)return;
+        var r=im.getBoundingClientRect();
+        var px=(e.clientX-r.left)/scaleX, py=(e.clientY-r.top)/scaleY;
+        var best=-1,bestArea=Infinity;
+        self._elData.forEach(function(el,i){
+          var mb=el.bounds&&el.bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+          if(!mb)return;
+          var a=+mb[1],b=+mb[2],c=+mb[3],dd=+mb[4];
+          if(px>=a&&px<=c&&py>=b&&py<=dd){var ar=(c-a)*(dd-b); if(ar<bestArea){bestArea=ar;best=i;}}
+        });
+        self._updatePixel(px, py);
+        var hov=container.querySelector('.el-shot-hover');
+        if(best<0){ if(hov)hov.remove(); return; }
+        var b2=self._elData[best].bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+        if(!hov){hov=document.createElement('div');hov.className='el-shot-hover';container.appendChild(hov);}
+        hov.style.left=(imgOffsetX+(+b2[1])*scaleX)+'px';
+        hov.style.top=(imgOffsetY+(+b2[2])*scaleY)+'px';
+        hov.style.width=((+b2[3])-(+b2[1]))*scaleX+'px';
+        hov.style.height=((+b2[4])-(+b2[2]))*scaleY+'px';
+      };
+      container.onmouseleave=function(){
+        var hov=container.querySelector('.el-shot-hover');
+        if(hov)hov.remove();
+      };
       container.onclick=function(e){
         var im=container.querySelector('img');
         if(!im)return;
@@ -968,6 +1397,8 @@ var _stepEditor={
   },
   // 高亮元素（截图框 + 列表项联动）
   _highlightEl:function(i){
+    this._renderAttrs(i);
+    this._renderColors(i);
     // 清除旧高亮（只在 el-picker-overlay 范围内查找）
     var picker=document.getElementById('el-picker-overlay');
     picker.querySelectorAll('.el-shot-overlay.active').forEach(function(o){o.classList.remove('active');});
@@ -992,24 +1423,68 @@ var _stepEditor={
     var self=this;
     var html=list.map(function(el){
       var idx=self._elData.indexOf(el);
+      // 属性顺序有讲究：**文字/描述排最前并加粗**——它们是最稳的定位依据，
+      // 也是"一眼认出这是哪个元素"的凭据（id 只是补充）。见 doc/TASK_DEV.md §5.4。
       var attrs=[];
-      if(el.resource_id)attrs.push('<span>id:'+esc(el.resource_id)+'</span>');
-      if(el.text)attrs.push('<span>text:'+esc(el.text)+'</span>');
-      if(el.description)attrs.push('<span>desc:'+esc(el.description)+'</span>');
+      if(el.text)attrs.push('<span class="ep-text">text:<b>'+esc(el.text)+'</b></span>');
+      if(el.description)attrs.push('<span class="ep-desc">desc:<b>'+esc(el.description)+'</b></span>');
+      if(el.resource_id)attrs.push('<span class="ep-id">id:'+esc(el.resource_id)+'</span>');
       var indent='  '.repeat(Math.min(el.depth||0,6));
       var sg=el.suggested||{};
       if(sg.invalid)attrs.push('<span style="color:#dc2626">⚠ '+esc(sg.reason||'无可用属性')+'</span>');
-      return '<div class="el-picker-item" data-idx="'+idx+'" title="点击填入: '+esc(sg.value||'')+'" onclick="_stepEditor._pickEl('+idx+')">'+
+      var acts='<div class="ep-acts" style="margin-left:auto;display:flex;gap:4px;flex:none">'
+        +'<button class="btn btn-xs" title="直接在设备上点这个元素（按元素中心坐标点击，服务端自动吸附到可点元素）" '
+        +'onclick="event.stopPropagation();_stepEditor._testTap('+idx+')">▶ 点一下</button>'
+        +(!sg.invalid&&sg.value
+          ? '<button class="btn btn-xs" title="用将填入的选择器在设备上真跑一次 click，验证是否命中" '
+            +'onclick="event.stopPropagation();_stepEditor._testSelector('+idx+')">✓ 测选择器</button>'
+          : '')
+        +'<button class="btn btn-xs" title="把这条的选择器填入步骤" '
+        +'onclick="event.stopPropagation();_stepEditor._fillEl('+idx+')">✓ 填入</button>'
+        +'</div>';
+      return '<div class="el-picker-item" data-idx="'+idx+'" title="'+esc(sg.value||'')+'" onclick="_stepEditor._pickEl('+idx+')">'+
         '<span class="ep-depth">'+(el.depth||0)+'</span>'+
         '<div class="ep-info"><div class="ep-name">'+indent+esc(el.name||el.class||'')+'</div>'+
         '<div class="ep-attrs">'+attrs.join('')+'</div></div>'+
         '<span class="ep-sel">'+esc(sg.type)+'</span>'+
-        (sg.indexed?' <span class="label label-info" title="界面中同属性元素共 '+sg.total+' 个，按从上到下这是第 '+sg.occ+' 个，选择器已带序号精确定位">#'+sg.occ+'/'+sg.total+'</span>':'')+
+        (sg.semantic?' <span class="label label-success" title="语义选择器：用 '+esc(sg.via||'')+' 限定，只认「这个元素长什么样」，不认「同类元素有几个」—— 换设备、换版本、界面增减元素都照样命中">✓ 语义</span>':'')+
+        (sg.indexed?' <span class="label label-warning" title="⚠ 序号型：依赖「同属性元素共 '+sg.total+' 个、这是第 '+sg.occ+' 个」。界面上多/少一个同类元素（如抖音灰度版少一个 tab）就会指到别的元素上 —— 建议改选带 text 或 content-desc 的元素，拿到语义选择器">⚠ 序号 '+sg.occ+'/'+sg.total+'</span>':'')+
         (sg.broad?' <span class="label label-warning" title="无唯一属性，选择器可能误匹配其他元素，建议选带文字/id 的元素">⚠宽泛</span>':'')+
+        acts+
       '</div>';
     }).join('');
     document.getElementById('el-list').innerHTML=html||'<div class="se-empty">无元素</div>';
   },
+  // 抓取时"直接点一下"：按元素 bounds 中心在设备上点击（服务端 snap 吸附）
+  _testTap:function(idx){
+    var el=this._elData&&this._elData[idx]; var serial=this._elSerial;
+    if(!el||!serial)return;
+    var m=(el.bounds||'').match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+    if(!m){ showToast('该元素没有 bounds，无法坐标点击','error'); return; }
+    var x=Math.round((+m[1]+ +m[3])/2), y=Math.round((+m[2]+ +m[4])/2);
+    var self=this;
+    apiPost('/api/screen/tap', {serial:serial, x:x, y:y, snap:1}).then(function(r){
+      if(!r||!r.ok){ showToast((r&&r.error)||'点击失败','error'); return; }
+      showToast('已点击'+(r.label?('「'+r.label+'」'):'')+' ('+r.x+','+r.y+')'+(r.snapped?' [已吸附]':''),'success');
+      setTimeout(function(){ if(self._elSerial===serial)self._refreshShot(); }, 800);
+    });
+  },
+  // 抓取时验证"将填入的选择器"：走 /api/steps/test 真跑一次 click
+  _testSelector:function(idx){
+    var el=this._elData&&this._elData[idx]; var serial=this._elSerial;
+    if(!el||!serial)return;
+    var sg=el.suggested||{};
+    if(!sg.value){ showToast('该元素没有可用选择器','error'); return; }
+    var self=this;
+    var step={type:'click', label:'测试点击',
+              params:{selector_type:sg.type||'xpath', selector_value:sg.value, wait_timeout:2}};
+    apiPost('/api/steps/test', {serial:serial, step:step}).then(function(r){
+      if(!r||!r.ok){ showToast((r&&r.error)||'测试失败','error'); return; }
+      var ok=(r.result==='命中');
+      showToast('选择器测试: '+(r.result||'')+(r.msg?(' — '+r.msg):''), ok?'success':'error');
+      setTimeout(function(){ if(self._elSerial===serial)self._refreshShot(); }, 800);
+    });
+  },
   _filterEl:function(kw){
     if(!kw){this._renderEl(this._elData);this._renderOverlays();return;}
     kw=kw.toLowerCase();
@@ -1020,7 +1495,12 @@ var _stepEditor={
     });
     this._renderEl(f);
   },
+  // 点层级条目 = **选中**（看属性/颜色/高亮），不关窗不回填
   _pickEl:function(i){
+    this._highlightEl(i);
+  },
+  // 「✓ 填入」才回填选择器并关窗
+  _fillEl:function(i){
     var el=this._elData[i];
     if(!el||!this._elTargetInput)return;
     if(el.suggested&&el.suggested.invalid){
@@ -1029,10 +1509,16 @@ var _stepEditor={
     }
     // 填入推荐选择器值，并切换选择器类型
     this._elTargetInput.value=el.suggested.value;
-    var sel=this._elTargetInput.closest('.sc-body').querySelector('[data-key="selector_type"]');
+    // 选择器类型下拉：通用编辑器里在同一个 .sc-body 内；别的编辑器（「发布计划」页的
+    // 步骤就地编辑）结构不同，取不到就跳过、交给下面的 _onFill 自己处理
+    var box=this._elTargetInput.closest('.sc-body');
+    var sel=box?box.querySelector('[data-key="selector_type"]'):null;
     if(sel)sel.value=el.suggested.type;
-    // 程序赋值不会触发 input 事件，手动同步回 _steps 防丢失
-    this._syncFromDom();
+    // 程序赋值不会触发 input 事件，手动同步防丢失。
+    // 默认同步回通用编辑器的 _steps；**别的编辑器用 _onFill 接管**
+    // （见 static/admin/release.js 的就地编辑），否则会同步到不相干的模型上
+    if(typeof this._onFill==='function')this._onFill(el, this._elTargetInput);
+    else this._syncFromDom();
     // 只关闭抓取元素弹窗，不影响任务编辑窗口
     closeElPicker();
     showToast('已填入: '+el.suggested.type+'='+el.suggested.value,'success');
@@ -1055,6 +1541,18 @@ async function saveTask(jobId){
     }
     const mdEl=document.getElementById('f-max_duration');
     params={max_duration:mdEl?parseInt(mdEl.value)||0:0,steps:steps};
+    // 去重有效期（任务级；「条件判断→去重」与「记为已做」共用这一套）
+    const drEl=document.getElementById('f-dedup_reset');
+    params.dedup_reset=drEl?drEl.value:'day';
+    if(drEl&&drEl.value==='hours'){
+      const dhEl=document.getElementById('f-dedup_hours');
+      params.dedup_hours=Math.max(1,parseInt(dhEl&&dhEl.value)||6);
+    }
+    // 公共巡检（任务级，独立于步骤画布；实现在 tasks.js + core/patrol.py）
+    if(typeof patrolCollect==='function'){
+      const ws=patrolCollect();
+      if(ws.length)params.watchers=ws;
+    }
   }else{
     try{params=JSON.parse(document.getElementById('f-params').value||'{}');}
     catch(e){showToast('参数 JSON 格式错误','error');return;}

static/admin/ledger.js

@@ -0,0 +1,300 @@
+// 账号台账（「账号」顶级 Tab）
+// 数据在 device_account 表，服务层 core/ledger.py，接口 /api/ledger*（web/devices_api.py）。
+//
+// 这一页的三重价值：
+//   ① 一台设备登好几个号、十几台设备几十个号 —— 换 IP / 加号时不用再翻电子表格；
+//   ② 任务的「条件判断」可以直接从这里取号（cmp_source），不用手写一串抖音号；
+//   ③ 手机端 Agent 的「身份大字页」会显示本机账号（平台推 accounts_b64）。
+//
+// ⚠ 台账里的抖音号是**纯号**，只当"比对用的候选值"；**别**拿它去填「去重」的身份元素
+//   ——身份是元素原文、逐字算 key，格式不同会让去重静默失效（core/ledger.py 顶部有警告）。
+var _ledgerAll = [];          // 全部账号（一次拉回，搜索/筛选在前端做：几十条量级）
+var _ledgerStats = {};
+var _ledgerDeviceNames = [];
+var _ledgerCounts = {};       // {设备号: 号数}（设备池那一列用）
+var _ledgerDevices = {};      // {设备号: {count, accounts[]}}（点开看明细用）
+
+function loadLedger() {
+  var sel = document.getElementById('ledger-device');
+  var keep = sel ? sel.value : '';
+  apiGet('/api/ledger?limit=2000').then(function (r) {
+    var tb = document.getElementById('tb-ledger');
+    if (!r || !r.ok) {
+      if (tb) tb.innerHTML = '<tr><td colspan="10" class="empty">读取失败：' + esc((r && r.error) || '') + '</td></tr>';
+      return;
+    }
+    _ledgerAll = r.accounts || [];
+    _ledgerStats = r.stats || {};
+    _ledgerDeviceNames = r.device_names || [];
+    _renderLedgerDeviceFilter(keep);
+    _renderLedgerStats();
+    renderLedger();
+  });
+}
+
+function _renderLedgerDeviceFilter(keep) {
+  var sel = document.getElementById('ledger-device');
+  if (!sel) return;
+  var html = '<option value="">全部设备</option>';
+  _ledgerDeviceNames.forEach(function (n) {
+    html += '<option value="' + esc(n) + '">' + esc(n) + '</option>';
+  });
+  sel.innerHTML = html;
+  sel.value = keep || '';
+}
+
+function _renderLedgerStats() {
+  var el = document.getElementById('ledger-stats');
+  if (!el) return;
+  var s = _ledgerStats || {};
+  el.textContent = '共 ' + (s.total || 0) + ' 个号 · ' + (s.devices || 0) + ' 台设备 · '
+    + (s.can_post_video || 0) + ' 个可发视频';
+}
+
+function ledgerDeviceChanged() { renderLedger(); }
+
+function renderLedger() {
+  var sel = document.getElementById('ledger-device');
+  var dev = sel ? sel.value : '';
+  var rows = dev ? _ledgerAll.filter(function (a) { return a.device_name === dev; }) : _ledgerAll;
+  setListPager('ledger', {
+    data: function () { return rows; },
+    filter: function (a, kw) {
+      return ((a.douyin_id || '') + (a.phone || '') + (a.nickname || '')
+        + (a.device_name || '') + (a.note || '')).toLowerCase().indexOf(kw) >= 0;
+    },
+    sortValue: function (a, k) { return a[k]; },
+    render: renderLedgerRow,
+    tbody: 'tb-ledger', pager: 'pager-ledger', pageSize: 20,
+    empty: '<tr><td colspan="10" class="empty">还没有账号 —— 点「粘贴导入」把你那张表贴进来</td></tr>'
+  });
+  applyListPager('ledger');
+  initListSearch('ledger', 'search-ledger');
+}
+
+function _yn(v) {
+  return v ? '<span class="label label-success">是</span>'
+           : '<span class="label label-default">否</span>';
+}
+
+function _clip(s, n) {
+  var t = String(s || '');
+  if (!t) return '';
+  return '<span title="' + esc(t) + '">' + esc(t.length > n ? t.slice(0, n) + '…' : t) + '</span>';
+}
+
+function renderLedgerRow(a) {
+  return '<tr>' +
+    '<td><strong>' + esc(a.device_name || '-') + '</strong></td>' +
+    '<td>' + esc(a.nickname || '-') + '</td>' +
+    '<td style="font-family:var(--mono)">' + esc(a.douyin_id || '-') + '</td>' +
+    '<td style="font-family:var(--mono)">' + esc(a.phone || '-') + '</td>' +
+    '<td>' + esc(a.registered_at || '-') + '</td>' +
+    '<td>' + _yn(a.sim_in_device) + '</td>' +
+    '<td>' + _yn(a.can_post_video) + '</td>' +
+    '<td>' + _clip(a.bio, 12) + '</td>' +
+    '<td>' + _clip(a.note, 12) + '</td>' +
+    '<td>' +
+      '<button class="btn btn-xs" onclick="openLedgerModal(\'' + a.id + '\')" data-perm="devices">编辑</button> ' +
+      '<button class="btn btn-xs btn-danger" data-id="' + a.id + '" ' +
+        'onclick="deleteLedger(this.dataset.id)" data-perm="devices">删除</button>' +
+    '</td></tr>';
+}
+
+function _ledgerById(id) {
+  for (var i = 0; i < _ledgerAll.length; i++) {
+    if (_ledgerAll[i].id === id) return _ledgerAll[i];
+  }
+  return null;
+}
+
+// ================== 单条新增 / 编辑 ==================
+function _ledgerField(label, key, val, ph) {
+  return '<div class="form-group"><label>' + label + '</label>' +
+    '<input class="form-control" data-lf="' + key + '" value="' + esc(val || '') + '" ' +
+    'placeholder="' + (ph || '') + '"></div>';
+}
+
+function openLedgerModal(id) {
+  var a = id ? _ledgerById(id) : null;
+  document.getElementById('modal-title').textContent = a ? ('编辑账号：' + (a.nickname || a.douyin_id)) : '新增账号';
+  var h = '<div class="form-row">' +
+    _ledgerField('设备号', 'device_name', a && a.device_name, '如 A01（要和设备池里的设备名一致）') +
+    _ledgerField('账号名称', 'nickname', a && a.nickname, '如 AA建材王总') + '</div>' +
+    '<div class="form-row">' +
+    _ledgerField('抖音号', 'douyin_id', a && a.douyin_id, '纯号，如 35377983067（不带「抖音号：」前缀）') +
+    _ledgerField('手机号', 'phone', a && a.phone, '') + '</div>' +
+    '<div class="form-row">' +
+    _ledgerField('注册时间', 'registered_at', a && a.registered_at, '如 2026/9/24（原样存）') +
+    '<div class="form-group"><label>卡在机内 / 可发视频</label>' +
+    '<div style="display:flex;gap:16px;align-items:center;padding-top:4px">' +
+    '<label style="display:inline-flex;gap:4px;align-items:center"><input type="checkbox" data-lf="sim_in_device" '
+      + (a && a.sim_in_device ? 'checked' : '') + '> 卡在机内</label>' +
+    '<label style="display:inline-flex;gap:4px;align-items:center"><input type="checkbox" data-lf="can_post_video" '
+      + (a && a.can_post_video ? 'checked' : '') + '> 可发视频</label>' +
+    '</div></div></div>' +
+    '<div class="form-group"><label>简介</label><input class="form-control" data-lf="bio" value="'
+      + esc(a && a.bio || '') + '"></div>' +
+    '<div class="form-group"><label>备注</label><input class="form-control" data-lf="note" value="'
+      + esc(a && a.note || '') + '"></div>' +
+    '<div class="help">抖音号在整个台账里必须唯一（一个号只能有一条记录）。' +
+    '<b>设备号</b>要和「工具 → 设备池」里的设备名一致 —— 任务的「本机台账」取号、' +
+    '设备端身份页显示本机账号都靠它匹配。</div>';
+  document.getElementById('modal-body').innerHTML = h;
+  document.getElementById('modal-footer').innerHTML =
+    '<button class="btn" onclick="closeModal()">取消</button>' +
+    '<button class="btn btn-primary" onclick="saveLedger(\'' + (a ? a.id : '') + '\')">保存</button>';
+  showModal();
+}
+
+function _ledgerFormValues() {
+  var out = {};
+  document.querySelectorAll('#modal-body [data-lf]').forEach(function (el) {
+    var k = el.dataset.lf;
+    out[k] = (el.type === 'checkbox') ? !!el.checked : el.value;
+  });
+  return out;
+}
+
+function saveLedger(id) {
+  var body = _ledgerFormValues();
+  var p = id ? apiPut('/api/ledger/' + id, body) : apiPost('/api/ledger', body);
+  p.then(function (r) {
+    if (r && r.ok) { closeModal(); showToast(r.msg || '已保存', 'success'); loadLedger(); }
+    else showToast('保存失败: ' + ((r && r.error) || ''), 'error');
+  });
+}
+
+function deleteLedger(id) {
+  var a = _ledgerById(id);
+  var who = a ? ((a.device_name || '') + ' / ' + (a.nickname || '') + ' / ' + (a.douyin_id || '')) : id;
+  if (!confirm('删掉这条账号？\n\n' + who + '\n\n删掉之后：任务从台账取号就取不到它了。')) return;
+  apiDelete('/api/ledger/' + id).then(function (r) {
+    if (r && r.ok) { showToast(r.msg || '已删除', 'success'); loadLedger(); loadLedgerCounts(); }
+    else showToast('删除失败: ' + ((r && r.error) || ''), 'error');
+  });
+}
+
+// ================== 粘贴导入 ==================
+function openLedgerImport() {
+  document.getElementById('modal-title').textContent = '粘贴导入账号台账';
+  document.getElementById('modal-box').classList.add('wide-modal');
+  document.getElementById('modal-body').innerHTML =
+    '<div class="help" style="margin-bottom:8px">' +
+    '把 Excel 里的表格<b>连表头一起</b>复制，粘到下面。首行是列名，顺序随意、缺列留空。<br>' +
+    '认得的列名：<code>设备号 / 手机号 / 账号名称 / 抖音号 / 注册时间 / 卡在机内 / 可发视频 / 简介 / 备注</code>' +
+    '（认不出的列会被忽略）。<b>没有表头</b>时按上面这个顺序解析。<br>' +
+    '「卡在机内 / 可发视频」认 <code>是/有/1</code> 与 <code>否/空</code>。' +
+    '</div>' +
+    '<div class="form-row" style="align-items:end">' +
+    '<div class="form-group"><label>分隔符</label>' +
+    '<select class="form-control" id="ledger-import-delim">' +
+    '<option value="tab">Tab（Excel 直接粘贴）</option>' +
+    '<option value="|">竖线 |</option><option value=",">逗号 ,</option></select></div>' +
+    '<div class="form-group"><label>遇到已存在的抖音号</label>' +
+    '<select class="form-control" id="ledger-import-mode">' +
+    '<option value="skip">跳过（不动已有记录）</option>' +
+    '<option value="overwrite">覆盖（整行替换，空单元格会覆盖掉原值）</option></select></div>' +
+    '</div>' +
+    '<div class="form-group"><textarea id="ledger-import-text" class="form-control" rows="10" ' +
+    'style="font-family:var(--mono);font-size:12px" placeholder="设备号&#9;手机号&#9;账号名称&#9;抖音号&#9;注册时间&#9;卡在机内&#9;可发视频&#9;简介&#9;备注&#10;A01&#9;13800000000&#9;示例账号&#9;35000000001&#9;2026/9/24&#9;否&#9;是&#9;&#9;"></textarea></div>' +
+    '<div id="ledger-import-result"></div>';
+  document.getElementById('modal-footer').innerHTML =
+    '<button class="btn" onclick="closeModal()">取消</button>' +
+    '<button class="btn" onclick="ledgerImport(true)">先预览</button>' +
+    '<button class="btn btn-primary" onclick="ledgerImport(false)">直接导入</button>';
+  showModal();
+}
+
+function ledgerImport(dryRun) {
+  var text = (document.getElementById('ledger-import-text') || {}).value || '';
+  if (!text.trim()) { showToast('先粘贴表格内容', 'error'); return; }
+  var delim = (document.getElementById('ledger-import-delim') || {}).value || 'tab';
+  var mode = (document.getElementById('ledger-import-mode') || {}).value || 'skip';
+  var box = document.getElementById('ledger-import-result');
+  if (box) box.innerHTML = '<div class="text-muted">' + (dryRun ? '解析中…' : '导入中…') + '</div>';
+  apiPost('/api/ledger/import', { text: text, delimiter: delim, mode: mode, dry_run: !!dryRun })
+    .then(function (r) {
+      if (!r || !r.ok) {
+        if (box) box.innerHTML = '<div class="text-danger">失败：' + esc((r && r.error) || '') + '</div>';
+        return;
+      }
+      renderImportResult(r);
+      if (!dryRun) { loadLedger(); loadLedgerCounts(); }
+    });
+}
+
+var _IMP_ACTION = {
+  add: ['label-success', '新增'], update: ['label-warning', '覆盖'],
+  skip: ['label-default', '跳过'], fail: ['label-danger', '失败']
+};
+
+function renderImportResult(r) {
+  var box = document.getElementById('ledger-import-result');
+  if (!box) return;
+  var c = r.counts || {};
+  var head = '<div style="margin:10px 0 6px"><b>' + (r.dry_run ? '预览结果（还没有写入）' : '导入结果')
+    + '</b>　共 ' + (c.total || 0) + ' 行：新增 ' + (c.added || 0) + ' · 覆盖 ' + (c.updated || 0)
+    + ' · 跳过 ' + (c.skipped || 0) + ' · 失败 ' + (c.failed || 0) + '</div>';
+  var rows = (r.rows || []).map(function (x) {
+    var a = _IMP_ACTION[x.action] || ['label-default', x.action];
+    var msg = x.error || (x.warns && x.warns.length ? x.warns.join('；') : '');
+    return '<tr><td>' + esc(x.line) + '</td>' +
+      '<td><span class="label ' + a[0] + '">' + a[1] + '</span></td>' +
+      '<td>' + esc(x.device_name || '') + '</td>' +
+      '<td style="font-family:var(--mono)">' + esc(x.douyin_id || '') + '</td>' +
+      '<td>' + esc(x.nickname || '') + '</td>' +
+      '<td style="color:#f59e0b">' + esc(msg) + '</td></tr>';
+  }).join('');
+  var errs = (r.errors || []).map(function (e) {
+    return '<li>第 ' + esc(e.line) + ' 行：' + esc(e.reason) + '</li>';
+  }).join('');
+  box.innerHTML = head +
+    _importErrorsNote(errs) +
+    '<div style="max-height:320px;overflow:auto"><table class="table table-sm">' +
+    '<thead><tr><th>行</th><th>动作</th><th>设备号</th><th>抖音号</th><th>账号名称</th><th>说明</th></tr></thead>' +
+    '<tbody>' + (rows || '<tr><td colspan="6" class="empty">没有可导入的行</td></tr>') + '</tbody></table></div>' +
+    (r.dry_run ? '<div class="help">确认没问题后点「直接导入」。</div>' : '');
+}
+
+function _importErrorsNote(errs) {
+  return errs ? ('<div class="help" style="color:#f59e0b">这些行被跳过了（不会导入）：<ul>' + errs + '</ul></div>') : '';
+}
+
+// ================== 设备维度：设备池那一列的"账号 N" ==================
+function loadLedgerCounts() {
+  return apiGet('/api/ledger/by_device').then(function (r) {
+    if (r && r.ok) { _ledgerCounts = r.counts || {}; _ledgerDevices = r.devices || {}; }
+    return _ledgerCounts;
+  }).catch(function () { return _ledgerCounts; });
+}
+
+function ledgerCell(serial, name) {
+  var n = _ledgerCounts[name] || 0;
+  if (!n) return '<span class="label label-default">未登记</span>';
+  return '<button class="btn btn-xs" onclick="showDeviceAccounts(\'' + esc(name) + '\')">' + n + ' 个号</button>';
+}
+
+function showDeviceAccounts(name) {
+  var g = _ledgerDevices[name];
+  if (!g) {
+    // 没缓存过就现拉一次（例如直接打开设备池）
+    loadLedgerCounts().then(function () { showDeviceAccounts(name); });
+    return;
+  }
+  document.getElementById('modal-title').textContent = name + ' 上的账号（' + (g.count || 0) + ' 个）';
+  var rows = (g.accounts || []).map(function (a) {
+    return '<tr><td>' + esc(a.nickname || '-') + '</td>' +
+      '<td style="font-family:var(--mono)">' + esc(a.douyin_id || '-') + '</td>' +
+      '<td style="font-family:var(--mono)">' + esc(a.phone || '-') + '</td>' +
+      '<td>' + _yn(a.sim_in_device) + '</td><td>' + _yn(a.can_post_video) + '</td>' +
+      '<td>' + esc(a.registered_at || '-') + '</td><td>' + _clip(a.note, 16) + '</td></tr>';
+  }).join('');
+  document.getElementById('modal-body').innerHTML =
+    '<div style="max-height:60vh;overflow:auto"><table class="table table-sm">' +
+    '<thead><tr><th>账号名称</th><th>抖音号</th><th>手机号</th><th>卡在机内</th><th>可发视频</th><th>注册时间</th><th>备注</th></tr></thead>' +
+    '<tbody>' + (rows || '<tr><td colspan="7" class="empty">这台设备还没有登记账号</td></tr>') + '</tbody></table></div>' +
+    '<div class="help">在「账号」页可以增删改；设备端 Agent 的「身份大字页」显示的就是这些。</div>';
+  document.getElementById('modal-footer').innerHTML = '<button class="btn" onclick="closeModal()">关闭</button>';
+  showModal();
+}

static/admin/markdown.js

@@ -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('');
+}

static/admin/monitor.js

@@ -13,6 +13,9 @@ function _sortValue(dev,key){
     // 按状态优先级排序：running>connecting>idle>done>error>released
     const order={running:0,connecting:1,idle:2,done:3,released:4,error:5,failed:6};
     v=order[dev.worker_status]||99;
+  }else if(key==='battery'){
+    // 没采到电量的排最后（用 -1 而不是 0，0% 是真实电量）
+    v=dev.battery?dev.battery.level:-1;
   }else{
     v=dev[key]||'';
   }
@@ -70,27 +73,28 @@ async function stopSelectedDevices(){
   setTimeout(loadMonitor,500);
 }
 
-// 定位设备：点亮屏幕 + 打开大字定位页（显示设备 IP），便于在机架上找到目标
-// 注意：打开定位页会切换设备前台，任务运行中慎用
-async function locateDevice(serial){
-  if(!confirm('点亮 '+serial+' 屏幕并打开大字定位页？\n\n（会切换设备前台显示，任务运行中慎用）'))return;
-  const r=await apiPost('/api/device/locate',{serial:serial,show:true});
+// 打开设备端 Agent：让设备上的 Agent 弹出「身份大字页」（名称/IP/平台地址），
+// 人站在机架前一眼看出这台是平台上的哪一台。
+// 替代原来的"推 HTML 让设备浏览器打开定位页"——那条路要设备装浏览器、页面还依赖
+// 设备能访问平台，且在 MIUI 上本来就不稳。
+async function showAgentInfo(serial){
+  const r=await apiPost('/api/agent/show-info',{serial:serial});
   if(!r)return;
   if(r.ok){
     _locatingSerials.add(serial);
-    showToast(r.msg||'已定位','success');
+    showToast(r.msg||'已让设备显示身份信息','success');
     renderDevices();
-  }else showToast(r.error||'定位失败','error');
+  }else showToast(r.error||'打开失败','error');
 }
 
-// 结束定位：关闭设备上的定位页（浏览器），按钮恢复为"定位"
-async function stopLocate(serial){
-  const r=await apiPost('/api/device/locate/stop',{serial:serial});
+// 关闭设备端 Agent 的身份页
+async function hideAgentInfo(serial){
+  const r=await apiPost('/api/agent/show-info',{serial:serial,close:true});
   if(!r)return;
   _locatingSerials.delete(serial);
   renderDevices();
-  if(r.ok)showToast(r.msg||'已结束定位','success');
-  else showToast(r.error||'结束定位失败','error');
+  if(r.ok)showToast(r.msg||'已关闭','success');
+  else showToast(r.error||'关闭失败','error');
 }
 
 // 批量亮屏/息屏所有在线设备（息屏会中断运行中任务，前端已确认）
@@ -324,6 +328,22 @@ function renderDevices(){
   applyListPager('devices');
   initListSearch('devices','search-devices');
 }
+// 电量单元格：告警档位（tier 0 正常/1 低/2 严重）由后端算好，前端只上色——
+// 阈值只在「工具 → 设备发现 → 电量监控」一处定义，两边不重复判
+function _battCell(dev){
+  const b=dev.battery;
+  if(!b)return '<span class="text-muted">-</span>';
+  const t=b.tier||0;
+  const cls=t===2?'label-danger':(t===1?'label-warning':'label-success');
+  const mins=b.at?Math.floor((Date.now()/1000-b.at)/60):-1;
+  const ageTxt=(mins<0?'':(mins<1?'刚刚':mins+' 分钟前'));
+  const chg=b.charging?' ⚡':'';
+  const tip=(t===2?'电量严重不足':(t===1?'电量低':'电量正常'))
+    +(b.charging?'（充电中）':'')+(ageTxt?'（'+ageTxt+'采集）':'')
+    +(dev.present?'':'（设备已离线，显示最后一次读数）');
+  const stale=dev.present?'':'<div style="font-size:11px;color:#94a3b8">'+ageTxt+'</div>';
+  return '<span class="label '+cls+'" title="'+tip+'">'+b.level+'%'+chg+'</span>'+stale;
+}
 function renderDeviceRow(dev){
   const offline=dev.present?'':' <span class="label label-danger">离线</span>';
   const st=STATUS_MAP[dev.worker_status]||{t:dev.worker_status,c:'default'};
@@ -344,24 +364,28 @@ function renderDeviceRow(dev){
   // 设备操作按钮需要"设备控制"权限（无权限只保留截图查看）
   const canDev=_can('devices');
   const stopBtn=canDev&&(dev.worker_status==='running'||dev.worker_status==='connecting')?'<button class="btn btn-danger btn-xs" onclick="apiAction(\'/api/stop_device\',{serial:\''+esc(dev.serial)+'\'})">停止</button>':'';
-  // 截图按钮（任何状态都可看，离线时会报错）
-  const shotBtn='<button class="btn btn-xs" onclick="openScreenshot(\''+esc(dev.serial)+'\')" title="查看设备画面（不影响任务）">截图</button>';
-  // 定位按钮：定位中显示"结束定位"（关闭定位页），否则显示"定位"（点亮+大字页）
+  // 看屏按钮（任何状态都可看，离线时会报错）
+  const shotBtn='<button class="btn btn-xs" onclick="openScreenshot(\''+esc(dev.serial)+'\')" title="查看设备实时画面（不影响任务）">看屏</button>';
+  // 设备端 Agent：开着身份页时显示"关闭"，否则"打开设备端 Agent"
   const locating=_locatingSerials.has(dev.serial);
   const locateBtn=canDev?(locating
-    ?'<button class="btn btn-xs btn-danger" onclick="stopLocate(\''+esc(dev.serial)+'\')" title="关闭定位页（退出浏览器）">结束定位</button>'
-    :'<button class="btn btn-xs" onclick="locateDevice(\''+esc(dev.serial)+'\')" title="点亮屏幕并显示设备IP大字页（会切换前台，任务运行中慎用）">定位</button>'):'';
+    ?'<button class="btn btn-xs btn-danger" onclick="hideAgentInfo(\''+esc(dev.serial)+'\')" title="让设备上的 Agent 关掉身份大字页">关闭 Agent</button>'
+    :'<button class="btn btn-xs" onclick="showAgentInfo(\''+esc(dev.serial)+'\')" title="让设备上的 Agent 显示身份大字页（名称/IP/平台地址）——人在机架前对号用（会切换设备前台）">打开设备端 Agent</button>'):'';
   // 异常/失败设备提供"清除异常"（把状态恢复为未启动）
   const clearBtn=canDev&&(dev.worker_status==='error'||dev.worker_status==='failed')
     ?'<button class="btn btn-xs" onclick="clearDeviceError(\''+esc(dev.serial)+'\')" title="清除该设备的异常状态，恢复为未启动">清除异常</button>':'';
   const btns='<div style="display:flex;gap:4px;flex-wrap:wrap">'+shotBtn+locateBtn+clearBtn+stopBtn+'</div>';
-  const devName=dev.device_name||dev.model||'';
-  const devLabel=(devName?'<strong>'+esc(dev.serial)+'</strong><br><span style="font-size:11px;color:#94a3b8">'+esc(devName)+'</span>':'<strong>'+esc(dev.serial)+'</strong>')+offline;
+  // 名称优先（设备身份），地址作副标题；未命名的历史数据显示提醒
+  const nm=(dev.device_name||'').trim();
+  const devLabel=(nm
+      ? '<strong>'+esc(nm)+'</strong><br><span style="font-size:11px;color:#94a3b8;font-family:var(--mono)">'+esc(dev.serial)+'</span>'
+      : '<strong style="font-family:var(--mono)">'+esc(dev.serial)+'</strong>'
+        +'<br><span style="font-size:11px;color:#d97706">未命名</span>') + offline;
   // 复选框列
   const checked=_selectedSerials.has(dev.serial)?'checked':'';
   const rowCls=_selectedSerials.has(dev.serial)?'row-checked':'';
   const cb='<input type="checkbox" '+checked+' onclick="toggleDevice(\''+esc(dev.serial)+'\',this.checked)">';
-  return '<tr class="'+rowCls+'"><td class="col-cb">'+cb+'</td><td>'+devLabel+'</td><td>'+esc(dev.model)+'</td><td>'+wb+'</td><td>'+fg+'</td><td>'+prog+'</td><td>'+tname+retry+endInfo+'</td><td class="text-muted">'+esc(dev.current_action||'-')+warnInfo+'</td><td class="err-text" title="'+esc(dev.last_error||'')+'">'+esc(dev.last_error||'-')+'</td><td>'+btns+'</td></tr>';
+  return '<tr class="'+rowCls+'"><td class="col-cb">'+cb+'</td><td>'+devLabel+'</td><td>'+esc(dev.model)+'</td><td>'+_battCell(dev)+'</td><td>'+wb+'</td><td>'+fg+'</td><td>'+prog+'</td><td>'+tname+retry+endInfo+'</td><td class="text-muted">'+esc(dev.current_action||'-')+warnInfo+'</td><td class="err-text" title="'+esc(dev.last_error||'')+'">'+esc(dev.last_error||'-')+'</td><td>'+btns+'</td></tr>';
 }
 
 async function loadJobsForMonitor(){
@@ -445,6 +469,36 @@ function fmtParams(params){
   return parts.join('');
 }
 
+// 任务覆盖的设备：后端给 serial 清单（coverage），这里用实时状态标注在线/运行中
+function _jobCoverageHtml(j){
+  const cov=j.coverage||{}, serials=cov.serials||[];
+  const st={};
+  if(_statusData)for(const d of (_statusData.devices||[]))st[d.serial]=d;
+  if(!serials.length){
+    return '<div class="job-cov"><span class="kv">覆盖设备 0 台</span>'
+      +'<span class="cov-note">该目标下暂无可调度设备（检查设备池/分组）</span></div>';
+  }
+  let onlineN=0,busyN=0;
+  const chips=serials.map(s=>{
+    const d=st[s]||{};
+    const online=!!d.present;
+    const busy=(d.worker_status==='running'||d.worker_status==='connecting');
+    if(online)onlineN++;
+    if(busy)busyN++;
+    const cls=busy?'running':(online?'online':'offline');
+    // chip 优先显示设备名称（身份），没有名称才退回地址
+    const nm=(d.device_name||'').trim();
+    const title=s+(nm?' · '+nm:'')+(d.model?' · '+d.model:'')
+      +(busy?' · 任务中：'+(d.task_job||''):'')
+      +(online?'':' · 离线或不在设备池');
+    return '<span class="cov-chip '+cls+'" title="'+esc(title)+'">'
+      +esc(nm || s.replace(/:5555$/,''))+(busy?' ⏳':'')+(online?'':' ✕')+'</span>';
+  }).join('');
+  return '<div class="job-cov"><span class="kv">覆盖 '+serials.length+' 台 · 在线 '+onlineN
+    +(busyN?' · 运行中 '+busyN:'')+'</span>'
+    +'<div class="cov-chips">'+chips+'</div></div>';
+}
+
 function renderJobCards(){
   const jobs=_jobsData||[];
   const running={};
@@ -470,12 +524,11 @@ function renderJobCards(){
         '<span class="kv">调度:'+esc(sched)+'</span>'+
         '<span class="kv">重试:'+esc(retry)+'</span></div>'+
         '<div style="margin-top:4px">'+fmtParams(j.params)+'</div>'+
+        _jobCoverageHtml(j)+
       '</div>'+
       '<div class="job-actions">'+
-        '<button class="btn btn-primary btn-xs" onclick="apiAction(\'/api/jobs/'+j.id+'/run\')">立即执行</button>'+
-        '<button class="btn btn-xs" onclick="apiAction(\'/api/jobs/'+j.id+'/toggle\',{enabled:'+(!j.enabled)+'})">'+(j.enabled?'停用':'启用')+'</button>'+
-        '<button class="btn btn-xs" onclick="openTaskModal(\''+j.id+'\')">编辑</button>'+
-        '<button class="btn btn-danger btn-xs" onclick="deleteTask(\''+j.id+'\')">删除</button>'+
+        '<button class="btn btn-primary btn-xs" onclick="apiAction(\'/api/jobs/'+j.id+'/run\')">执行任务</button>'+
+        '<button class="btn btn-xs" onclick="apiAction(\'/api/jobs/'+j.id+'/toggle\',{enabled:'+(!j.enabled)+'})">'+(j.enabled?'停用任务':'启用任务')+'</button>'+
       '</div>'+
     '</div>';
   }).join(''):'<div class="empty">暂无任务，到"任务"Tab 新建</div>';

static/admin/notify.js

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

static/admin/recorder.js

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

static/admin/steplog.js

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

static/admin/system.js

@@ -0,0 +1,132 @@
+// 「系统」Tab：数据备份导出/导入（依赖 base.js：esc/_csrfHeaders/apiPost/showToast/handleResult）
+let _restoreToken = '';   // 预览通过后的暂存标识（用于 apply）
+
+// ================== 导出 ==================
+async function doExportBackup(){
+  const st=document.getElementById('backup-status');
+  const btn=event&&event.target||null;
+  if(btn)btn.disabled=true;
+  const includeApk=document.getElementById('backup-include-apk').checked;
+  if(st)st.textContent='正在生成备份并打包…';
+  try{
+    const r=await fetch('/api/system/backup/export',{
+      method:'POST',
+      headers:{'Content-Type':'application/json',..._csrfHeaders()},
+      body:JSON.stringify({include_apk:includeApk})
+    });
+    if(r.status===401){window.location='/login';return;}
+    if(!r.ok){
+      let msg='导出失败';
+      try{const d=await r.json();if(d&&d.error)msg=d.error;}catch(e){}
+      showToast(msg,'error');
+      if(st)st.textContent='';
+      return;
+    }
+    const blob=await r.blob();
+    const cd=r.headers.get('Content-Disposition')||'';
+    const m=/filename="?([^";]+)"?/i.exec(cd);
+    const fname=m?m[1]:('auto_control_backup_'+Date.now()+'.zip');
+    const url=URL.createObjectURL(blob);
+    const a=document.createElement('a');
+    a.href=url;a.download=fname;document.body.appendChild(a);
+    a.click();a.remove();
+    setTimeout(()=>URL.revokeObjectURL(url),3000);
+    if(st)st.textContent='已生成 '+fname;
+    showToast('导出成功','success');
+  }catch(e){
+    showToast('导出失败: '+e,'error');
+    if(st)st.textContent='';
+  }finally{
+    if(btn)btn.disabled=false;
+  }
+}
+
+// ================== 导入：上传预览 ==================
+async function previewRestore(){
+  const fileEl=document.getElementById('restore-file');
+  const f=fileEl&&fileEl.files&&fileEl.files[0];
+  const box=document.getElementById('restore-preview');
+  const st=document.getElementById('restore-status');
+  const applyBtn=document.getElementById('btn-apply-restore');
+  if(!f){showToast('请先选择备份文件（.zip 或 .db）','error');return;}
+  _restoreToken='';
+  if(applyBtn)applyBtn.style.display='none';
+  if(st)st.textContent='';
+  box.innerHTML='<span class="text-muted">解析校验中…</span>';
+  const fd=new FormData();
+  fd.append('file',f);
+  try{
+    const r=await fetch('/api/system/backup/preview',{
+      method:'POST',
+      headers:_csrfHeaders(),   // FormData 不能手动设 Content-Type
+      body:fd
+    });
+    if(r.status===401){window.location='/login';return;}
+    const d=await r.json();
+    box.innerHTML='';
+    if(!d.ok){showToast(d.error||'解析失败','error');return;}
+    _restoreToken=d.token;
+    renderRestorePreview(d.preview);
+    if(applyBtn)applyBtn.style.display='';
+  }catch(e){
+    box.innerHTML='';
+    showToast('上传失败: '+e,'error');
+  }
+}
+
+function renderRestorePreview(p){
+  const box=document.getElementById('restore-preview');
+  const rows=(p.tables||[]).map(t=>
+    '<tr><td>'+esc(t.label||t.table)+'</td><td>'+esc(t.table)+'</td><td>'+esc(t.rows)+'</td></tr>').join('');
+  const warns=(p.warnings||[]).map(w=>'<li>'+esc(w)+'</li>').join('');
+  const crossEnv=!!(p.source_env&&p.current_env&&p.source_env!==p.current_env);
+  box.innerHTML=
+    '<table class="table table-hover table-sm" style="max-width:560px">'+
+      '<tbody>'+
+        '<tr><th style="width:120px">文件</th><td>'+esc(p.file_name||'')+'（'+(p.file_size!=null?fmtSize(p.file_size):'')+'）</td></tr>'+
+        '<tr><th>库结构版本</th><td>备份 v'+esc(p.schema_version)+' / 当前 v'+esc(p.current_schema_version)+'</td></tr>'+
+        '<tr><th>来源 / 当前环境</th><td>'+(p.source_env?esc(p.source_env):'（旧版备份，未记录）')+' → '+esc(p.current_env||'未登记')+'</td></tr>'+
+        '<tr><th>完整性</th><td>'+esc(p.integrity||'')+'</td></tr>'+
+      '</tbody>'+
+    '</table>'+
+    (crossEnv?'<label style="display:block;margin:8px 0;padding:8px 12px;background:#fdecea;border:1px solid #f5c6cb;border-radius:6px">'+
+      '<input type="checkbox" id="restore-force-env"> '+
+      '允许跨环境导入（'+esc(p.source_env)+' → '+esc(p.current_env)+'）—— 默认拒绝</label>':'')+
+    '<div class="section-title" style="margin-top:8px">表数据行数</div>'+
+    '<table class="table table-hover table-sm" style="max-width:560px"><thead><tr><th>业务</th><th>表</th><th>行数</th></tr></thead><tbody>'+(rows||'<tr><td colspan="3">—</td></tr>')+'</tbody></table>'+
+    (warns?'<div style="background:#fff3cd;border:1px solid #ffda6a;color:#7a5b00;padding:8px 12px;border-radius:6px;margin-top:8px"><ul style="margin:0;padding-left:18px">'+warns+'</ul></div>':'');
+}
+
+function fmtSize(n){
+  if(n==null)return '';
+  if(n<1024)return n+' B';
+  if(n<1024*1024)return (n/1024).toFixed(1)+' KB';
+  return (n/1024/1024).toFixed(1)+' MB';
+}
+
+// ================== 导入：确认应用 ==================
+async function applyRestore(){
+  const applyBtn=document.getElementById('btn-apply-restore');
+  const st=document.getElementById('restore-status');
+  if(!_restoreToken)return;
+  const forceEl=document.getElementById('restore-force-env');
+  const force=!!(forceEl&&forceEl.checked);
+  if(!confirm('确认应用导入？\n\n系统会先自动备份当前库（data/backups/pre_restore_*.zip），再把待导入数据覆盖现有全部数据。\n导入将在重启 web_server 后生效。\n\n确定继续？'))return;
+  if(applyBtn)applyBtn.disabled=true;
+  if(st)st.textContent='正在生成恢复任务…';
+  const r=await apiPost('/api/system/backup/apply',{token:_restoreToken,force_env_mismatch:force});
+  if(!r)return;
+  if(r.ok){
+    const box=document.getElementById('restore-preview');
+    box.innerHTML='<div style="background:#e8f5e9;border:1px solid #a5d6a7;padding:10px 14px;border-radius:6px">'+
+      '✅ 恢复任务已生成。<br>当前库已自动备份到 <code>'+esc(r.backup_name||'')+'</code>。<br>'+
+      '请<b>重启 web_server</b>，启动时将自动应用导入数据（恢复完成前不要再次导入）。</div>';
+    if(st)st.textContent='';
+    if(applyBtn)applyBtn.style.display='none';
+    document.getElementById('restore-file').value='';
+    _restoreToken='';
+  }else{
+    showToast(r.error||'应用导入失败','error');
+    if(applyBtn)applyBtn.disabled=false;
+  }
+}

static/admin/taskgen.js

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

static/admin/tasks.js

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

static/admin/tools.js

@@ -35,7 +35,7 @@ async function loadToolsDevices(force){
     const stCls = d.state==='device' ? 'label-success' : 'label-warning';
     return '<label data-serial="'+esc(d.serial)+'">'
       +'<input type="checkbox" value="'+esc(d.serial)+'"'+( _clipSelected.has(d.serial)?' checked':'')+' onchange="toggleClipDevice(this)">'
-      +'<span style="font-family:monospace;flex:1;overflow:hidden;text-overflow:ellipsis">'+esc(d.serial)+'</span>'
+      +'<span style="font-family:monospace;flex:1;overflow:hidden;text-overflow:ellipsis">'+esc(devText(d.name,d.serial))+'</span>'
       +'<span class="label '+stCls+'">'+st+'</span></label>';
   }).join('');
   status.textContent = '共 '+_clipDevices.length+' 台设备';
@@ -43,6 +43,7 @@ async function loadToolsDevices(force){
 
 // ================== 设备自动发现（扫描 → 待连接池 → 确认） ==================
 function loadDiscovery(){
+  loadBattery();   // 电量监控与发现同住一个子面板，跟着它的 10s 轮询一起刷新状态行
   apiGet('/api/devices/discovery').then(r=>{
     if(!r||!r.ok)return;
     const status=document.getElementById('discovery-status');
@@ -51,22 +52,26 @@ function loadDiscovery(){
     const subnets=document.getElementById('discovery-subnets');
     if(!enabled)return;   // 面板未渲染（离开子分栏）
     enabled.checked=!!r.enabled;
+    const ac=document.getElementById('discovery-autoclaim');
+    if(ac)ac.checked=!!r.auto_claim;
     interval.value=r.interval||60;
     subnets.value=(r.subnets||[]).join(', ');
     // 状态行
     if(r.scanning){status.textContent='扫描中...';}
     else if(r.last_scan){
       let txt='上次扫描 '+esc(r.last_scan)+' · 开放 '+r.last_result.found+' · 可连 '
-        +(r.last_result.verified||0)+' · 新增 '+(r.last_result.new||0);
+        +(r.last_result.verified||0)+' · 新增 '+(r.last_result.new||0)
+        +(r.last_result.claimed?' · 自动认领 '+r.last_result.claimed:'');
       if(r.last_error)txt+=' · ⚠ '+esc(r.last_error);
       status.textContent=txt;
     }else{status.textContent='尚未扫描';}
     // 待连接表格：只显示在线设备（离线候选不可确认连接，隐藏；恢复在线后自动出现）
     const rows=(r.pending||[]).filter(x=>x.online);
+    _discoveryRows=rows;   // 供确认时判断"是不是已有设备换了地址"
     const tb=document.getElementById('tb-discovery');
     if(!tb)return;
     if(!rows.length){
-      tb.innerHTML='<tr><td colspan="6" class="empty">待连接池为空（扫描到的设备会出现在这里）</td></tr>';
+      tb.innerHTML='<tr><td colspan="7" class="empty">待连接池为空（扫描到的设备会出现在这里）</td></tr>';
     }else{
       tb.innerHTML=rows.map(x=>{
         const src=x.source==='tailscale'
@@ -75,14 +80,118 @@ function loadDiscovery(){
         const onl=x.online
           ?'<span class="label label-success">在线</span>'
           :'<span class="label label-warning">离线</span>';
+        // 指纹命中池中已有设备 → 提示"这台是 X 换了地址"，确认即认领（不需要起新名）
+        const m=x.match;
+        const ident=m
+          ?'<span class="label label-info" title="指纹一致：同一台设备换了地址；确认后会迁移原记录并同步分组/任务">≈ '
+            +esc(m.name||m.serial)+'（原 '+esc(m.serial)+'）</span>'
+          :'<span class="text-muted">新设备</span>';
+        const btnTxt=m?'认领为『'+esc(m.name||'原设备')+'』':'确认添加';
         return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'
+          +'<td>'+ident+'</td>'
           +'<td>'+src+'</td><td>'+esc(x.first_seen)+'</td><td>'+esc(x.last_seen)+'</td><td>'+onl+'</td>'
-          +'<td><button class="btn btn-primary btn-xs" data-serial="'+esc(x.serial)+'" onclick="confirmDiscoveryDev(this.dataset.serial)">确认添加</button> '
+          +'<td><button class="btn btn-primary btn-xs" data-serial="'+esc(x.serial)+'" onclick="confirmDiscoveryDev(this.dataset.serial)">'+btnTxt+'</button> '
           +'<button class="btn btn-xs" data-serial="'+esc(x.serial)+'" onclick="ignoreDiscoveryDev(this.dataset.serial)">忽略</button></td></tr>';
       }).join('');
     }
+    // 正式池断联设备：仍在设备池（不删除），扫描线程自动重连，可手动立即重连
+    const offTb=document.getElementById('tb-pool-offline');
+    if(offTb){
+      const off=(r.pool_offline||[]);
+      if(!off.length){
+        offTb.innerHTML='<tr><td colspan="5" class="empty">全部在线</td></tr>';
+      }else{
+        offTb.innerHTML=off.map(x=>{
+          return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'
+            +'<td>'+(x.name ? esc(x.name) :
+                     '<span class="label label-warning">未命名</span>')+'</td>'
+            +'<td>'+esc(x.model||'-')+'</td>'
+            +'<td><span class="label label-danger">断联·自动重连中</span></td>'
+            +'<td style="white-space:nowrap">'
+            +'<button class="btn btn-xs" data-serial="'+esc(x.serial)+'" onclick="reconnectPoolDev(this.dataset.serial)">立即重连</button> '
+            // 设备换了 IP 时旧地址永远连不上——给一条"换地址"的出路（迁移记录 + 同步引用）
+            +'<button class="btn btn-xs" data-serial="'+esc(x.serial)+'" title="设备换了 IP、这个旧地址已经连不上时：把记录迁到新地址（名称与分组/任务引用自动保留）" onclick="relocatePoolDev(this.dataset.serial)">换地址</button>'
+            +'</td></tr>';
+        }).join('');
+      }
+    }
   });
 }
+// ================== 设备电量监控（定时采集 + 低电量告警） ==================
+// 电量本身随 /api/status 下发（监控页电量列 / 大屏卡片），这里只管配置与采集器状态。
+let _batteryLoaded=false;   // 表单只回填一次：10s 轮询不能把用户正在输的值冲掉
+
+function loadBattery(){
+  apiGet('/api/devices/battery').then(r=>{
+    if(!r||!r.ok)return;
+    const en=document.getElementById('battery-enabled');
+    if(!en)return;                                   // 面板不在页面上
+    const s=r.settings||{};
+    if(!_batteryLoaded){
+      en.checked=!!s.enabled;
+      document.getElementById('battery-low').value=s.low;
+      document.getElementById('battery-critical').value=s.critical;
+      document.getElementById('battery-skip-charging').checked=!!s.skip_charging;
+      document.getElementById('battery-interval').value=s.interval;
+      _batteryLoaded=true;
+    }
+    const st=document.getElementById('battery-status');
+    if(r.scanning)st.textContent='采集中...';
+    else if(r.last_scan)st.textContent='上次采集 '+r.last_scan[0]+' · 成功 '+r.last_scan[1]+'/'+r.last_scan[2]+' 台';
+    else st.textContent='尚未采集';
+  });
+}
+
+function saveBatterySettings(){
+  const body={
+    enabled:document.getElementById('battery-enabled').checked,
+    low:document.getElementById('battery-low').value,
+    critical:document.getElementById('battery-critical').value,
+    skip_charging:document.getElementById('battery-skip-charging').checked,
+    interval:document.getElementById('battery-interval').value,
+  };
+  apiPost('/api/devices/battery/settings',body).then(r=>{
+    if(!r||!r.ok){showToast('保存失败: '+((r&&r.error)||''),'error');return;}
+    showToast(r.msg||'已保存','success');
+    // 回填后端钳制后的真实值（填 999 会被钳到 100，严重阈值高于低电量会被压回来）
+    const s=r.settings;
+    if(s){
+      document.getElementById('battery-low').value=s.low;
+      document.getElementById('battery-critical').value=s.critical;
+      document.getElementById('battery-interval').value=s.interval;
+    }
+  });
+}
+
+function scanBatteryNow(){
+  apiPost('/api/devices/battery/scan',{}).then(r=>{
+    if(r&&r.ok){
+      showToast(r.msg||'采集已启动','success');
+      setTimeout(loadBattery,3000);
+      if(typeof loadMonitor==='function')setTimeout(loadMonitor,3000);   // 监控页设备表跟着更新
+    }else showToast('采集失败: '+((r&&r.error)||''),'error');
+  });
+}
+
+function reconnectPoolDev(serial){
+  apiPost('/api/devices/discovery/reconnect',{serial}).then(r=>{
+    if(r&&r.ok){
+      showToast('重连已启动（约 5-15 秒生效）','success');
+      setTimeout(loadDiscovery,8000);
+    }else showToast('重连失败: '+((r&&r.error)||''),'error');
+  });
+}
+// 指纹匹配自动认领开关（默认关：认领会改写分组/任务引用，交人工确认更稳妥）
+function toggleAutoClaim(checked){
+  const tip=checked
+    ? '已开启自动认领：扫描到"同一台设备换了 IP"时会自动迁移记录并同步分组/任务引用'
+    : '已关闭自动认领：扫描到换 IP 的设备会提示，由你点确认';
+  apiPost('/api/devices/discovery/settings',{auto_claim:checked}).then(r=>{
+    if(r&&r.ok)showToast(tip,'success');
+    else{showToast('设置失败: '+((r&&r.error)||''),'error');loadDiscovery();}
+  });
+}
+
 function toggleDiscovery(checked){
   apiPost('/api/devices/discovery/settings',{enabled:checked}).then(r=>{
     if(r&&r.ok)showToast('定时扫描已'+(checked?'开启':'关闭'),'success');
@@ -105,11 +214,23 @@ function runDiscoveryScan(){
   });
 }
 function confirmDiscoveryDev(serial){
-  const name=prompt('备注名（可选，留空直接添加）','');
-  if(name===null)return;
+  const row=(_discoveryRows||[]).find(x=>x.serial===serial)||{};
+  const m=row.match;
+  let name='';
+  if(m){
+    // 指纹命中：这是池中某台设备换了地址 → 认领（保留原名与引用），无需再起名
+    if(!confirm('这台就是『'+(m.name||m.serial)+'』（原地址 '+m.serial+'）。\n\n'
+               +'确认认领到 '+serial+' 吗？\n'
+               +'名称、型号、备注都会保留，分组与任务里的旧地址会自动同步到新地址。'))return;
+  }else{
+    const input=prompt('给这台设备起个名称（必填，平台内唯一）：','');
+    if(input===null)return;
+    name=(input||'').trim();
+    if(!name){showToast('必须填写设备名称','error');return;}
+  }
   apiPost('/api/devices/discovery/confirm',{serial,name}).then(r=>{
     if(r&&r.ok){
-      showToast('已加入设备池'+(r.is_new?'':'（已存在，已更新）'),'success');
+      showToast(r.msg||'已加入设备池','success');
       loadDevPool();loadDiscovery();
     }else showToast('确认失败: '+((r&&r.error)||''),'error');
   });
@@ -188,12 +309,14 @@ async function queryAppVers(){
   }
 }
 function renderAppVerRow(x){
-  if(x.error)return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+  // 设备列显示「名称 · 地址」（名称来自设备池；没名字就只显示地址）
+  const dev='<td style="font-family:monospace">'+esc(devText(x.name,x.serial))+'</td>';
+  if(x.error)return '<tr>'+dev+
     '<td><span class="label label-warning">查询失败</span></td><td colspan="2">'+esc(x.error)+'</td></tr>';
-  if(x.installed)return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+  if(x.installed)return '<tr>'+dev+
     '<td><span class="label label-success">已安装</span></td>'+
     '<td>'+esc(x.version_name||'')+'</td><td style="font-family:monospace">'+esc(x.version_code||'')+'</td></tr>';
-  return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+  return '<tr>'+dev+
     '<td><span class="label label-default">未安装</span></td><td>-</td><td>-</td></tr>';
 }
 
@@ -388,19 +511,26 @@ function copyTsKey(){
 
 
 // ================== Tab: 工具 - 设备池管理（本地 SQLite 清单） ==================
+let _devPoolRows=[];     // 设备池最近一次结果（改名时取当前名称）
+let _discoveryRows=[];   // 待连接池最近一次结果（确认时判断是否为已有设备换了地址）
 async function loadDevPool(){
   const tb=document.getElementById('tb-devpool');
   const status=document.getElementById('devpool-status');
   if(!tb)return;
-  tb.innerHTML='<tr><td colspan="7" class="empty">加载中...</td></tr>';
+  tb.innerHTML='<tr><td colspan="9" class="empty">加载中...</td></tr>';
   const r=await apiGet('/api/devices/pool');
-  if(!r||!r.ok){tb.innerHTML='<tr><td colspan="7" class="empty">加载失败</td></tr>';return;}
+  if(!r||!r.ok){tb.innerHTML='<tr><td colspan="9" class="empty">加载失败</td></tr>';return;}
+  // 账号台账：这台设备登记了几个号（顺手把明细也缓存下来，点开就弹）
+  if(typeof loadLedgerCounts==='function'){
+    try{ await loadLedgerCounts(); }catch(e){}
+  }
   let rows=r.devices||[];
   // 在线优先排序；「只看在线」勾选时过滤掉离线（IP 换了/长期离线的旧条目不再碍眼）
   const onlyOnline=document.getElementById('devpool-filter-online')
     ? document.getElementById('devpool-filter-online').checked : false;
   rows.sort((a,b)=>(b.online?1:0)-(a.online?1:0));
   if(onlyOnline)rows=rows.filter(x=>x.online);
+  _devPoolRows=rows;
   const onlineCnt=rows.filter(x=>x.online).length;
   status.textContent=onlyOnline
     ? '在线 '+rows.length+' 台（共 '+(r.devices||[]).length+' 台配置）'
@@ -412,24 +542,41 @@ async function loadDevPool(){
     const online= d.online
       ? '<span class="label label-success">在线</span>'
       : '<span class="label label-warning">离线</span>';
+    // 名称是设备身份：老数据可能有空的 → 标出来提示补
+    const nameCell = d.name
+      ? esc(d.name)
+      : '<span class="label label-warning" title="设备名称必填且唯一（分组/任务/日志按名称认设备）；点右侧「改名」补上">未命名</span>';
+    const fp = d.fingerprint
+      ? '<span title="设备指纹 '+esc(d.fingerprint)+'（ro.serialno）：换 IP 后靠它自动认领">🔑</span>'
+      : '<span class="text-muted" title="尚未采集到指纹：设备离线时采不到；采集到之后换 IP 才能自动认领">—</span>';
     return '<tr>'+
       '<td style="font-family:monospace">'+esc(d.serial)+'</td>'+
-      '<td>'+esc(d.name||'')+'</td>'+
-      '<td>'+esc(d.model||'<span style="color:var(--text-light)">-</span>')+'</td>'+
+      '<td>'+nameCell+'</td>'+
+      '<td>'+esc(d.model||'-')+'</td>'+
       '<td>'+online+'</td>'+
       '<td>'+st+'</td>'+
+      '<td style="text-align:center">'+fp+'</td>'+
+      // 账号台账（「账号」页维护）：0 个号显示"未登记"而不是空白 ——
+      // 空白会让人以为功能坏了，而"未登记"是明确信息
+      '<td style="white-space:nowrap">'+(typeof ledgerCell==='function'
+        ? ledgerCell(d.serial, d.name||'') : '—')+'</td>'+
       '<td style="color:var(--text-light)">'+esc(d.created_at||'')+'</td>'+
       '<td style="white-space:nowrap">'+
+        '<button class="btn btn-xs" onclick="renamePoolDev(\''+esc(d.serial)+'\')">改名</button> '+
+        '<button class="btn btn-xs" title="生成配置二维码：设备端 Agent 扫一下即配好（平台地址/令牌/指纹）" onclick="showDevQrcode(\''+esc(d.serial)+'\')">二维码</button> '+
+        (d.online ? '' :
+          '<button class="btn btn-xs" title="设备换了 IP、旧地址连不上时：把这条记录迁到新地址（名称与分组/任务引用自动保留）" onclick="relocatePoolDev(\''+esc(d.serial)+'\')">换地址</button> ') +
         '<button class="btn btn-xs" onclick="togglePoolDev(\''+esc(d.serial)+'\','+(!d.enabled)+')">'+(d.enabled?'停用':'启用')+'</button> '+
         '<button class="btn btn-xs btn-danger" onclick="removePoolDev(\''+esc(d.serial)+'\')">删除</button>'+
       '</td></tr>';
-  }).join('')||'<tr><td colspan="7" class="empty">设备池为空，添加第一台设备开始</td></tr>';
+  }).join('')||'<tr><td colspan="9" class="empty">设备池为空，添加第一台设备开始</td></tr>';
 }
 
 async function addPoolDev(){
   const serial=document.getElementById('devpool-serial').value.trim();
   const name=document.getElementById('devpool-name').value.trim();
   if(!serial){showToast('请输入 serial','error');return;}
+  if(!name){showToast('请填写设备名称（平台内唯一，用于分组/任务/日志认设备）','error');return;}
   const r=await apiPost('/api/devices/pool/add',{serial,name});
   if(!r)return;
   if(r.ok){
@@ -440,6 +587,28 @@ async function addPoolDev(){
   }else showToast(r.error,'error');
 }
 
+async function renamePoolDev(serial){
+  const cur=(((_devPoolRows||[]).find(x=>x.serial===serial))||{}).name||'';
+  const nw=(prompt('设备名称（必填，平台内唯一）：', cur)||'').trim();
+  if(!nw || nw===cur)return;
+  const r=await apiPost('/api/devices/pool/rename',{serial,name:nw});
+  if(!r)return;
+  if(r.ok){showToast(r.msg,'success');loadDevPool();}
+  else showToast(r.error,'error');
+}
+
+// 换地址（人工认领）：设备换了 IP、旧地址已连不上时用；名称与分组/任务引用都保留
+async function relocatePoolDev(serial){
+  if(!serial){showToast('没取到设备地址，请刷新页面后重试','error');return;}
+  const nw=(prompt('把记录 ' + serial + ' 迁到新地址（设备换 IP、旧地址连不上时用）：\n\n'
+                  +'名称、型号、备注都会保留，分组与任务里的旧地址会自动同步。','')||'').trim();
+  if(!nw || nw===serial)return;
+  const r=await apiPost('/api/devices/pool/relocate',{old_serial:serial,new_serial:nw});
+  if(!r)return;
+  if(r.ok){showToast(r.msg,'success');loadDevPool();loadDiscovery();}
+  else showToast(r.error,'error');
+}
+
 async function removePoolDev(serial){
   if(!confirm('从设备池删除 '+serial+'？\n\n删除后不再参与任务调度（不影响设备本身与其他功能）。'))return;
   const r=await apiPost('/api/devices/pool/remove',{serial});
@@ -469,3 +638,37 @@ async function refreshPoolModels(){
   if(r.ok){showToast(r.msg,'success');setTimeout(loadDevPool,12000);}
   else showToast(r.error,'error');
 }
+
+// ================== 设备配置二维码（设备端 Agent 扫码即配好） ==================
+// 二维码内容：平台地址 + 设备令牌 + 这台设备的指纹（JSON）。
+// 手机上的 Agent 扫一下 → 保存这三项 → 不用在手机上打字、也不用连 adb。
+async function showDevQrcode(serial){
+  document.getElementById('modal-title').textContent='设备配置二维码';
+  document.getElementById('modal-body').innerHTML='<p class="text-muted">生成中...</p>';
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">关闭</button>';
+  showModal();
+  const r=await apiGet('/api/devices/qrcode?serial='+encodeURIComponent(serial));
+  const box=document.getElementById('modal-body');
+  if(!r||!r.ok){
+    box.innerHTML='<div style="background:#fdecea;border:1px solid #f5c6cb;color:#b42318;'+
+      'padding:10px 12px;border-radius:6px">'+esc((r&&r.error)||'生成失败')+'</div>';
+    return;
+  }
+  const warn=r.warn?'<div style="background:#fff3cd;border:1px solid #ffda6a;color:#7a5b00;'+
+      'padding:8px 12px;border-radius:6px;margin-bottom:10px;font-size:13px">⚠️ '+esc(r.warn)+'</div>':'';
+  box.innerHTML=
+    warn+
+    '<div style="text-align:center;padding:8px 0">'+
+      '<img src="'+r.png+'" style="width:240px;height:240px;image-rendering:pixelated;'+
+        'background:#fff;padding:8px;border:1px solid #e5e7eb;border-radius:8px" alt="配置二维码">'+
+      '<div style="margin-top:10px;font-size:15px"><strong>'+esc(r.name||'(未命名)')+
+        '</strong> <span style="font-family:monospace;color:#6b7280">'+esc(r.serial)+'</span></div>'+
+    '</div>'+
+    '<div class="help" style="margin-top:6px">在设备上打开 <strong>设备 Agent</strong> → 点「扫码配置」→ 扫这个二维码，'+
+      '平台地址、令牌、指纹一次写入，不用在手机上打字。</div>'+
+    '<details style="margin-top:8px"><summary style="cursor:pointer;color:#6b7280;font-size:12px">'+
+      '查看二维码内容（排查用）</summary>'+
+      '<div style="font-family:monospace;font-size:11px;color:#64748b;word-break:break-all;'+
+        'background:#f8fafc;padding:8px;border-radius:6px;margin-top:6px">'+esc(r.payload)+'</div></details>';
+}

tasks/__init__.py

@@ -7,7 +7,7 @@
 from .base import BaseTask, register_task, list_task_types, get_task_class
 
 # 导入所有任务包，触发 @register_task 注册
-from .douyin import task  # noqa: F401
+# 当前只有一个任务类型：generic_steps（通用步骤，前端步骤编辑器编排）
 from .generic import task  # noqa: F401
 
 __all__ = ["BaseTask", "register_task", "list_task_types", "get_task_class"]

tasks/base.py

@@ -12,7 +12,7 @@
         base.py       — 本任务的操作基类 + 注册器
         xxx.py        — 具体操作
 
-新增任务步骤（照着 tasks/douyin/ 抄即可）：
+新增任务步骤（照着 tasks/generic/ 抄即可）：
 
   1. 在 tasks/ 下新建 my_task/ 子包（文件夹 + __init__.py）
   2. 在 my_task/task.py 顶部写默认参数：
@@ -49,8 +49,8 @@
                from .actions import get_action_class
                return get_action_class(action_type)
 
-           def create_worker(self, serial, params):
-               return MyWorker(serial, params=params)
+           def create_worker(self, serial, params, ctx=None):
+               return MyWorker(serial, params=params, ctx=ctx)
 
   5. 在 my_task/__init__.py 加：from . import task  （触发注册）
   6. 在 tasks/__init__.py 加：from .my_task import task  （触发注册）
@@ -85,8 +85,12 @@ class BaseTask:
     description = ""
     default_params = {}
 
-    def create_worker(self, serial, params):
-        """返回一个 threading.Thread（已启动或待启动），执行实际任务。"""
+    def create_worker(self, serial, params, ctx=None):
+        """返回一个 threading.Thread（已启动或待启动），执行实际任务。
+
+        ctx：本次运行的上下文（`run_id`/`job_id`/`job_name`/`device_name`），
+        由 TaskManager 传入，供步骤明细等结构化记录标注来源；可为 None。
+        """
         raise NotImplementedError
 
     @classmethod

tasks/douyin/__init__.py

@@ -1,9 +0,0 @@
-"""抖音养号任务包。
-
-本包自包含：任务定义（task.py）+ 抖音专属操作（actions/）。
-抖音的点赞/评论 xpath 只适用于抖音，不放全局，避免和其他任务混淆。
-
-加新抖音操作：在 actions/ 下建 .py，继承本包 BaseAction + @register_action，
-在 actions/__init__.py import。
-"""
-from . import task  # noqa: F401  触发 @register_task 注册抖音任务

tasks/douyin/actions/__init__.py

@@ -1,21 +0,0 @@
-"""抖音操作注册包。import 触发各操作注册。
-
-加新抖音操作：新建 xxx.py，在下面加一行 from . import xxx。
-注意：必须先从 base 导入 ACTIONS，再导入各操作模块，否则循环导入。
-"""
-# 先初始化注册表（base.py 里定义了 ACTIONS = create_action_registry()）
-from .base import (
-    BaseAction, register_action, create_action_registry,
-    list_actions, get_action, should_trigger,
-    ACTIONS,
-    list_action_types, get_action_class,
-)
-
-# 再导入各操作模块，触发 @register_action(ACTIONS) 注册
-from . import like  # noqa: F401
-
-__all__ = [
-    "BaseAction", "register_action", "create_action_registry",
-    "list_actions", "get_action", "should_trigger",
-    "ACTIONS", "list_action_types", "get_action_class",
-]

tasks/douyin/actions/base.py

@@ -1,51 +0,0 @@
-"""抖音操作基类与注册机制。
-
-操作 = 抖音养号主循环里某个时机执行的一次具体行为（点赞/评论/关注等）。
-这里的注册表只对抖音任务生效，其他任务有自己的 actions 包。
-
-设计：抖音的 ACTIONS 注册表是独立的 dict，用 core.actions 的
-register_action(ACTIONS) 装饰器注册，和全局/其他 app 互不污染。
-
-新增抖音操作步骤（照着 like.py 抄）：
-
-  1. 在 tasks/douyin/actions/ 下新建 my_action.py
-  2. 写一个 BaseAction 子类，用 @register_action 装饰，实现 execute：
-
-       from core.actions import BaseAction, register_action, should_trigger
-       from . import ACTIONS  # 本任务注册表
-
-       @register_action(ACTIONS)
-       class MyAction(BaseAction):
-           action_type = "my_action"
-           name = "我的操作"
-           description = "做什么"
-           default_params = {"rate": 0.5}
-
-           def execute(self, d, params, worker):
-               if not should_trigger(params["rate"]):
-                   return False
-               # ... 用 d(xpath=...) / d(text=...) 操作
-               return True
-
-  3. 在 tasks/douyin/actions/__init__.py 加一行：from . import my_action
-
-  做完前端自动出现该操作的可勾选项。
-"""
-from core.actions import (
-    BaseAction, register_action, create_action_registry,
-    list_actions, get_action, should_trigger,
-)
-
-# 抖音专属操作注册表（独立 dict，不污染其他 app）
-ACTIONS = create_action_registry()
-
-
-# 兼容旧导入：tasks/douyin/actions/__init__.py 原来从这里导出
-def list_action_types():
-    """返回所有已注册抖音操作的元信息（供前端展示）。"""
-    return list_actions(ACTIONS)
-
-
-def get_action_class(action_type):
-    """按 action_type 取抖音操作类。"""
-    return get_action(ACTIONS, action_type)

tasks/douyin/actions/like.py

@@ -1,108 +0,0 @@
-"""抖音点赞操作。
-
-两种方式：
-  by_element   — 用 xpath 找右侧红心按钮点击（相对定位，不依赖视频卡片序号）
-  double_click — 双击屏幕中央（需明确选择此方式，抖音"双击点赞"手势）
-
-by_element 找不到点赞按钮时**跳过本次，不点屏幕**（避免直播/无按钮页误触）。
-要适配新版本抖音：用 weditor 重新抓当前界面，调整下面定位逻辑。
-"""
-from core.actions import BaseAction, register_action, should_trigger
-from core.logger import get_logger
-from . import ACTIONS
-
-_log = get_logger("action.like")
-
-
-@register_action(ACTIONS)
-class LikeAction(BaseAction):
-    action_type = "like"
-    name = "点赞"
-    description = "看完视频后随机点赞（找红心按钮，找不到回退双击）"
-    default_params = {
-        "rate": 0.3,                 # 触发概率 0~1
-        "method": "by_element",      # by_element=找红心 | double_click=双击屏幕
-    }
-
-    def execute(self, d, params, worker):
-        rate = float(params.get("rate", 0.3))
-        if not should_trigger(rate):
-            return False
-        method = params.get("method", "by_element")
-        if method == "by_element":
-            if self._like_by_element(d):
-                worker.set_action("点赞(红心)")
-                return True
-            # 找不到点赞按钮：跳过本次，不点屏幕，避免误触（如直播/无点赞按钮的页面）
-            worker.set_action("点赞(未找到，跳过)")
-            return False
-        # 仅在明确选择 double_click 方式时才双击屏幕
-        ok = self._double_click_center(d)
-        if ok:
-            worker.set_action("点赞(双击)")
-        return ok
-
-    @staticmethod
-    def _like_by_element(d):
-        """找右侧操作栏红心按钮点击，成功返回 True。
-
-        定位优先级：description 精确 → descriptionContains 模糊 → resourceId → xpath
-        每种方式找到即点即返回，找不到继续下一种。全程记日志。
-        """
-        # 方式1：description 精确匹配（最稳，不依赖结构）
-        for desc in ("点赞", "未点赞", "like"):
-            el = d(description=desc)
-            if el.exists:
-                el.click()
-                _log.info(f"like 命中 description={desc}")
-                return True
-        # 方式2：descriptionContains 模糊匹配（适配不同版本文案）
-        for kw in ("赞", "like"):
-            el = d(descriptionContains=kw)
-            if el.exists:
-                el.click()
-                _log.info(f"like 命中 descriptionContains={kw}")
-                return True
-        # 方式3：resourceId 列表（扩充候选，覆盖更多抖音版本）
-        for rid in ("com.ss.android.ugc.aweme:id/aky",
-                    "com.ss.android.ugc.aweme:id/d-like-view-icon",
-                    "com.ss.android.ugc.aweme:id/h3r",
-                    "com.ss.android.ugc.aweme:id/dfz",
-                    "com.ss.android.ugc.aweme:id/c5w"):
-            el = d(resourceId=rid)
-            if el.exists:
-                el.click()
-                _log.info(f"like 命中 resourceId={rid}")
-                return True
-        # 方式4：xpath 相对定位——右侧操作栏 LinearLayout 的第一个 ImageView
-        # 定位思路：ViewPager 下当前 FrameLayout 里的 LinearLayout，
-        # 取其直接子 FrameLayout 里的第一个 ImageView（点赞在操作栏最上方）
-        try:
-            el = d.xpath(
-                '//androidx.viewpager.widget.ViewPager'
-                '/android.widget.FrameLayout'
-                '/com.bytedance.highperformanceview.layout.MeasureOnceRelativeLayout2'
-                '/com.bytedance.highperformanceview.layout.MeasureOnceRelativeLayout2'
-                '/android.widget.LinearLayout/android.widget.FrameLayout[2]'
-                '/android.widget.LinearLayout/android.widget.FrameLayout[1]'
-                '/android.widget.FrameLayout[1]/android.widget.ImageView'
-            )
-            if el.exists:
-                el.click()
-                _log.info("like 命中 xpath")
-                return True
-        except Exception as e:
-            _log.warning(f"like xpath 异常: {e}")
-        _log.info("like_by_element 全部失败，准备回退双击")
-        return False
-
-    @staticmethod
-    def _double_click_center(d):
-        """双击屏幕中央点赞。按屏幕尺寸算坐标，适配不同分辨率。"""
-        try:
-            info = d.info
-            w, h = info["displayWidth"], info["displayHeight"]
-            d.double_click(int(w * 0.5), int(h * 0.5))
-            return True
-        except Exception:
-            return False

tasks/douyin/task.py

@@ -1,269 +0,0 @@
-"""抖音养号任务定义。
-
-本文件自包含所有抖音养号参数（观看、滑动、操作等），不依赖 core 的业务配置。
-抖音专属操作（点赞/评论）在 actions/ 子包里，xpath 只适用于抖音。
-
-修改养号行为：改下面 DEFAULT_PARAMS 默认值，或通过前端任务参数覆盖。
-修改养号逻辑：改 DouyinNurtureWorker.run_task。
-加新抖音操作：在 actions/ 下建 .py，继承 BaseAction + @register_action。
-"""
-import time
-import random
-
-from tasks.base import BaseTask, register_task
-from .actions import list_action_types, get_action_class
-from core.device_worker import BaseWorker, _update_status
-from core.u2_helper import ensure_app_running, wait_for_app_home
-from core.logger import get_logger
-
-_log = get_logger("task.douyin")
-
-
-# ================== 抖音养号参数（本任务专属，写在这里） ==================
-DOUYIN_PKG = "com.ss.android.ugc.aweme"
-
-DEFAULT_PARAMS = {
-    # 观看
-    "watch_count": 80,        # 观看视频数量（0=不限数量，仅按 max_duration 终止）
-    "watch_min": 5.0,         # 单个视频最短观看秒数
-    "watch_max": 35.0,        # 单个视频最长观看秒数
-    # 运行时长终止（通用，0=不限时，按 watch_count 终止）
-    # 两个条件哪个先到就停；都为 0 则永不停止（需手动停止）
-    "max_duration": 0,        # 最大运行时长（秒），如 1800=30分钟，0=不限时
-    # 滑动
-    "swipe_min": 0.25,        # 上滑手势最短时长(秒)
-    "swipe_max": 0.50,        # 上滑手势最长时长(秒)
-    "gap_min": 1.0,           # 视频间隔最短秒数
-    "gap_max": 3.0,           # 视频间隔最长秒数
-    # 操作（每个操作有 enabled 开关 + 自身参数）
-    "actions": {
-        "like": {
-            "enabled": True,
-            "params": {"rate": 0.3, "method": "by_element"},
-        },
-    },
-}
-
-
-class DouyinNurtureWorker(BaseWorker):
-    """抖音养号 worker：看视频 + 按配置执行操作（点赞/评论等），被退出自动重连。
-
-    只需实现 run_task(d)，STF 占用/释放、u2 连接、异常、状态上报由基类处理。
-    操作参数优先级：任务 params.actions > 本文件 DEFAULT_PARAMS.actions。
-    """
-
-    def __init__(self, serial, params=None):
-        super().__init__(serial, params)
-        p = {**DEFAULT_PARAMS, **(self.params or {})}
-        self.watch_count = int(p["watch_count"])
-        self.watch_min = float(p["watch_min"])
-        self.watch_max = float(p["watch_max"])
-        # 通用运行时长终止（0=不限时）
-        self.max_duration = int(p.get("max_duration", 0))
-        self.swipe_min = float(p["swipe_min"])
-        self.swipe_max = float(p["swipe_max"])
-        self.gap_min = float(p["gap_min"])
-        self.gap_max = float(p["gap_max"])
-        # 操作配置：{action_type: {"enabled":bool, "params":{...}}}
-        self.actions_cfg = p.get("actions", {})
-        # 实例化所有启用的操作
-        self._actions = []
-        for atype, cfg in self.actions_cfg.items():
-            if not cfg.get("enabled"):
-                continue
-            cls = get_action_class(atype)
-            if cls:
-                self._actions.append(cls())
-        # 启动日志：打印终止条件 + 启用的 action，便于排查
-        stop_conds = []
-        if self.watch_count > 0:
-            stop_conds.append(f"数量={self.watch_count}")
-        if self.max_duration > 0:
-            stop_conds.append(f"时长={self.max_duration}s")
-        if not stop_conds:
-            stop_conds.append("无（需手动停止）")
-        _log.info(f"[{serial}] 终止条件: {', '.join(stop_conds)}")
-        if self._actions:
-            summary = ", ".join(
-                f"{a.action_type}(rate={self.actions_cfg.get(a.action_type, {}).get('params', {}).get('rate', '?')})"
-                for a in self._actions
-            )
-            _log.info(f"[{serial}] 启用操作: {summary}")
-        else:
-            _log.warning(f"[{serial}] 未启用任何操作，整个任务期间不会执行点赞")
-
-    def run_task(self, d):
-        """抖音养号主逻辑。d 是 u2.Device，已由基类连好。
-
-        终止条件（哪个先到就停）：
-          - watch_count > 0：看完指定数量视频
-          - max_duration > 0：达到最大运行时长
-          - 两者都为 0：永不停止，需手动停止
-        """
-        def is_home(d):
-            return (d(descriptionContains="拍摄").exists
-                    or d(descriptionContains="首页").exists)
-
-        # 启动运行时长计时（基类通用方法）
-        self._start_timer()
-
-        d.app_start(DOUYIN_PKG, wait=True)
-        if not wait_for_app_home(d, DOUYIN_PKG, is_home, timeout=40):
-            self.set_action("首页加载超时，继续尝试")
-
-        watched = 0
-        action_counts = {a.action_type: 0 for a in self._actions}
-        # 初始化通用进度上报
-        # total=0 时前端不显示百分比，只显示已看数量 + 运行时长
-        total = self.watch_count if self.watch_count > 0 else 0
-        self.set_progress(done=0, total=total, unit="视频",
-                          action_counts=action_counts)
-        while not self.stopped():
-            # 终止条件检查
-            if self.watch_count > 0 and watched >= self.watch_count:
-                break
-            if self.is_time_up():
-                _log.info(f"[{self.serial}] 达到最大运行时长 {self.max_duration}s，停止")
-                break
-
-            if not ensure_app_running(d, DOUYIN_PKG):
-                _update_status(self.serial, status="error",
-                               last_error="抖音连续重启失败，放弃该设备")
-                return
-            _update_status(self.serial, douyin_running=True, last_error="")
-
-            watch = random.uniform(self.watch_min, self.watch_max)
-            # 动作描述包含运行时长，便于前端观察
-            elapsed = self.elapsed()
-            time_info = f"，已运行 {elapsed//60}m{elapsed%60}s" if elapsed > 0 else ""
-            self.set_action(f"观看视频 {watched+1}，{watch:.0f}s{time_info}")
-            time.sleep(watch)
-
-            # 检测当前是否为可操作的正常视频页（有右侧操作栏 = 点赞/评论按钮）
-            # 营销广告、直播、异常页通常没有这些元素，直接滑过去不做操作
-            is_normal = self._is_normal_video(d)
-            if is_normal:
-                # 正常视频：执行所有启用的操作（看完视频后、滑动前）
-                if not self._actions:
-                    _log.info(f"[{self.serial}] 视频{watched+1}: 正常视频但无启用操作")
-                for action in self._actions:
-                    if self.stopped():
-                        break
-                    cfg = self.actions_cfg.get(action.action_type, {})
-                    params = {**action.default_params, **cfg.get("params", {})}
-                    rate = params.get("rate", "?")
-                    try:
-                        ok = action.execute(d, params, self)
-                        _log.info(f"[{self.serial}] 视频{watched+1}: {action.action_type} "
-                                  f"rate={rate} execute={ok}")
-                        if ok:
-                            action_counts[action.action_type] += 1
-                            time.sleep(random.uniform(0.5, 1.5))
-                    except Exception as e:
-                        _log.error(f"[{self.serial}] 视频{watched+1}: 操作 {action.action_type} "
-                                   f"异常: {e}")
-            else:
-                self.set_action(f"跳过广告/直播 {watched+1}")
-                _log.info(f"[{self.serial}] 视频{watched+1}: 非正常视频页，跳过操作")
-
-            if self.stopped():
-                break
-            d.swipe(500, 1000, 500, 300, random.uniform(self.swipe_min, self.swipe_max))
-            time.sleep(random.uniform(self.gap_min, self.gap_max))
-            watched += 1
-            # 上报通用进度（含运行时长，前端展示）
-            elapsed = self.elapsed()
-            self.set_progress(done=watched, total=total, unit="视频",
-                              action_counts=dict(action_counts),
-                              elapsed=elapsed)
-
-        # 终止原因汇总
-        stop_reason = ""
-        if self.stopped():
-            stop_reason = "（手动停止）"
-        elif self.is_time_up():
-            stop_reason = f"（达到时长 {self.max_duration}s）"
-        elif self.watch_count > 0 and watched >= self.watch_count:
-            stop_reason = f"（达到数量 {self.watch_count}）"
-        summary = f"完成 {watched} 个视频" + "".join(
-            f"，{k} {v}次" for k, v in action_counts.items() if v
-        ) + stop_reason
-        _update_status(self.serial, douyin_running=False, current_action=summary)
-
-    @staticmethod
-    def _is_normal_video(d):
-        """判断当前是否为可操作的正常视频页。
-
-        正常视频页右侧有操作栏（点赞/评论/分享按钮）。
-        营销广告、直播、异常页通常没有这些元素 → 返回 False，直接滑过去。
-        检测任一特征元素存在即认为是正常视频页。
-
-        定位优先级：description 精确 → descriptionContains 模糊 → resourceId 列表 → 兜底
-        每次返回 False 时记日志，便于定位"为什么操作没执行"。
-        """
-        try:
-            # 1. description 精确匹配（最稳）
-            for desc in ("点赞", "未点赞", "评论", "未评论"):
-                if d(description=desc).exists:
-                    return True
-            # 2. descriptionContains 模糊匹配（适配不同版本文案）
-            for kw in ("赞", "评论"):
-                if d(descriptionContains=kw).exists:
-                    return True
-            # 3. resourceId 列表（扩充候选，覆盖更多抖音版本）
-            for rid in ("com.ss.android.ugc.aweme:id/aky",
-                        "com.ss.android.ugc.aweme:id/akq",
-                        "com.ss.android.ugc.aweme:id/d-like-view-icon",
-                        "com.ss.android.ugc.aweme:id/d-comment-view-icon",
-                        "com.ss.android.ugc.aweme:id/h3r"):
-                if d(resourceId=rid).exists:
-                    return True
-            # 所有特征元素都没找到 → 非正常视频页（广告/直播/异常）
-            _log.info(f"_is_normal_video=False: 未找到点赞/评论特征元素")
-            return False
-        except Exception as e:
-            _log.warning(f"_is_normal_video 异常: {e}")
-            return False
-
-
-@register_task
-class DouyinNurtureTask(BaseTask):
-    """抖音养号：看视频 + 按配置执行操作（点赞/评论等），被退出自动重连。"""
-    task_type = "douyin_nurture"
-    name = "抖音养号"
-    description = "自动观看抖音视频，按配置执行点赞/评论等操作，被退出自动重连"
-    default_params = dict(DEFAULT_PARAMS)
-
-    @classmethod
-    def list_action_types(cls):
-        """返回本任务支持的抖音操作列表。"""
-        return list_action_types()
-
-    @classmethod
-    def get_action_class(cls, action_type):
-        """按 action_type 取抖音操作类。"""
-        return get_action_class(action_type)
-
-    def create_worker(self, serial, params):
-        merged = {**DEFAULT_PARAMS, **(params or {})}
-        # actions 字段深合并（参数级，保留前端没传的操作默认值）
-        # 确保即使前端只传 actions.like.enabled，like.params.rate 也能拿到默认 0.3
-        default_actions = DEFAULT_PARAMS["actions"]
-        merged_actions = params.get("actions", {}) if params else {}
-        for atype, dflt in default_actions.items():
-            if atype not in merged_actions:
-                # 前端完全没传这个操作 → 用默认
-                merged_actions[atype] = dflt
-            else:
-                # 前端传了 → 参数级深合并
-                cfg = merged_actions[atype]
-                merged_cfg = {}
-                for k in ("enabled", "params"):
-                    merged_cfg[k] = cfg.get(k, dflt.get(k))
-                # params 再深合并一层
-                merged_params = dict(dflt.get("params", {}))
-                merged_params.update(cfg.get("params", {}))
-                merged_cfg["params"] = merged_params
-                merged_actions[atype] = merged_cfg
-        merged["actions"] = merged_actions
-        return DouyinNurtureWorker(serial, params=merged)

tasks/generic/__init__.py

@@ -1,6 +1,6 @@
 """通用步骤任务包。
 
 通过前端步骤编辑器编排任务流程，worker 按 steps 顺序执行。
-与 douyin_nurture 共存，互不影响。
+当前平台唯一的任务类型（task_type=generic_steps）。
 """
 from . import task  # noqa: F401  触发 @register_task 注册通用步骤任务

tasks/generic/publish_flow.py

@@ -0,0 +1,379 @@
+"""发布计划的执行原语：**把视频推到手机**、抓分享链接、清理手机上的素材。
+
+**分工**（用户定的）：平台只负责"素材到手机 + 状态记账"，
+**抖音里怎么发（打开→点+→相册→下一步→填文案→发布）由用户在任务画布里自己写步骤** ——
+所以这里**没有**写死的抖音发布流程，只有三个原语 + 一段编排：
+
+```
+push_one()            取计划 → 原子占位 → adb push 到指定目录 → 触发相册刷新
+                      → 把标题写进剪贴板（供后面的「粘贴」步骤直接用）
+capture_share_link()  进「我 → 作品」第一条 → 分享 → 复制链接 → 读剪贴板 → 抠出 v.douyin.com 链接
+clean_phone_video()   删手机上的素材（**精确路径**，绝不 rm 通配）
+```
+
+任务步骤（`task.py`）：
+  · 「推送发布视频」`push_release` —— 调 `push_one()`
+  · 「标记发布结果」`mark_release` —— 用户在自己的发布流程末尾调用，回写状态（可顺带抓链接）
+
+⚠ **失败阶段决定落 `failed` 还是 `unknown`**（见 `core/video_plan.STAGE_STATUS`）：
+推送阶段失败=还没碰抖音 → `failed`（可安全重试）；推送完成后（stage=`post`）出的岔子
+→ `unknown`（**可能已经发出去了，绝不自动重试**）。
+"""
+import os
+import re
+import time
+
+from core.logger import get_logger
+
+_log = get_logger("task.publish")
+
+# 相册目录：**DCIM/Camera**（用户定的）。
+# ⚠ 实测踩过的两件事：
+#   ① 相册（含抖音的选视频页）读的是 **MediaStore 索引**，`adb push` 只放文件、不进索引
+#      → 推完必须触发一次扫描（见 scan_media），否则"推送成功但相册里没有"。
+#   ② 推到自建子目录 `/sdcard/DCIM/rp` 时，MIUI 会把它归进「其他相册」，
+#      抖音的选视频页看不顺眼 —— 干脆放官方相机目录，哪儿都列得出来。
+# 放 Camera 的代价：用户自己拍的视频也在这个目录里 → **必须靠"刚推的排最前"来定位它**
+#   → 所以推完要 `touch` 把手机上那个文件的 mtime 改成"现在"（adb push 会保留**本地**修改时间，
+#     推一个 3 天前上传的素材，在按时间排序的相册里就排不到最前面 —— 实测踩过）。
+ALBUM_DIR = "/sdcard/DCIM/Camera"
+SCAN_WAIT = 2.0          # 媒体扫描后等相册刷新（真机实测再调）
+# 平台**曾经用过**的推送目录：推送前把同一计划在别处的旧副本清掉（历史遗留 + 换目录后的残留）。
+# 不清的后果实测过：相册里同一个 plan id 出现 2~3 个同名视频，"点第一个"点到的可能是指向
+# 已删文件的老记录 —— 这正是"相册里选错视频"的来源。
+KNOWN_ALBUM_DIRS = ("/sdcard/DCIM/Camera", "/sdcard/DCIM/rp", "/sdcard/Movies/rp")
+
+
+def _norm_path(p):
+    """路径归一化，用于比对：去掉引号、`/storage/emulated/0` 与 `/sdcard` 等价、统一小写。
+
+    ⚠ 大小写不是洁癖：MediaStore 的 `_data` 返回的是 **`/storage/emulated/0/dcim/rp/...`**
+    （目录部分被小写了），而我们写的是 `/sdcard/DCIM/...` —— 直接字符串比对永远不相等。
+    """
+    s = (p or "").strip().strip("'\"")
+    s = s.replace("/storage/emulated/0", "/sdcard").replace("/storage/self/primary", "/sdcard")
+    return s.lower()
+
+
+def _log_of(log):
+    return log or (lambda s: _log.info(s))
+
+
+def _sh(d, cmd):
+    """跑一条 shell 并**拿回文本**。
+
+    uiautomator2 3.x 的 `d.shell()` 返回 `ShellResponse`（**tuple 子类**，字段 .output/.exit_code），
+    不是 str —— 直接 `'abc' in resp`（元组成员判断，恒 False）或 `resp.strip()`（没有这方法）
+    都会得到错误结果。实测踩过：推送后的"文件大小校验"永远不通过、
+    "有没有进相册"永远报没进 —— 全是这一步读错了。统一走这里取文本。
+    """
+    r = d.shell(cmd)
+    out = getattr(r, "output", None)          # u2 3.x
+    if out is None:
+        out = r if isinstance(r, str) else str(r)   # 老版本 u2 / 异常返回
+    return (out or "").strip()
+
+
+# ================== 原语 ==================
+def push_video(d, serial, local_path, plan_id, album_dir=ALBUM_DIR, ext=".mp4"):
+    """把平台素材推到手机相册目录，并把手机上的时间改成"现在"。返回 (remote_path, error)。
+
+    改时间是为了**排序**：相册/抖音的选视频页按时间倒序，
+    `adb push` 保留的是**本地文件的修改时间**（推一个 3 天前上传的素材 → 排在很后面），
+    那"点第一个缩略图 = 刚推的那个"就不成立、可能点到别的视频。所以推完 `touch` 一下。
+    """
+    remote = f"{album_dir}/{plan_id}{ext}"
+    try:
+        local_size = os.path.getsize(local_path)
+        _sh(d, f"mkdir -p {album_dir}")
+        if hasattr(d, "push"):
+            d.push(local_path, remote)
+        else:                                   # 老版本 u2 兜底
+            from core.adb_helper import _adb
+            out = _adb("-s", serial, "push", local_path, remote)
+            if "error" in (out or "").lower():
+                return "", f"adb push 失败: {out[:120]}"
+        # 校验：**比对大小列**（不是"输出里有没有这个数字"—— 那种子串匹配会把日期里的
+        # 数字也当命中；u2 的 ShellResponse 更会让它恒不通过，见 _sh 的注释）
+        info = _sh(d, f"ls -l '{remote}'")
+        got = _remote_size(info)
+        if got is None:
+            return "", f"推上去的文件找不到: {info[:120] or '（ls 无输出）'}"
+        if got != local_size:
+            return "", f"推上去的文件大小不对: 本地 {local_size} / 手机 {got}"
+        # 排到最前：把手机上这个文件的 mtime 改成现在（改不动也不拦，只是排序可能不理想）
+        try:
+            _sh(d, f"touch '{remote}'")
+        except Exception as e:
+            _log.warning(f"touch 手机上的素材失败（排序可能不理想）: {e}")
+        drop_old_copies(d, plan_id, keep=remote, ext=ext)   # 老目录里的同名副本顺手清掉
+        return remote, ""
+    except Exception as e:
+        return "", f"推文件异常: {type(e).__name__}: {str(e)[:120]}"
+
+
+def _remote_size(ls_out):
+    """从 `ls -l` 输出里取**大小列**（字节）。取不到返回 None。
+
+    MIUI 的 toybox 输出形如 `-rw-rw---- 1 u0_a163 media_rw 15405006 2026-09-25 08:42 /sdcard/...`。
+    判据两道：① 行首是文件类型字符（`-`/`d`/`l`…）—— 挡住 "No such file" 这类错误行；
+    ② 第 5 列是纯数字 —— 大小列就在那（`ls -l` 一定有 size 列，第 4 列是 owner）。
+    比"输出里有没有这个数字"这种子串匹配可靠得多（后者会被日期/权限里的数字骗到）。
+    """
+    for line in (ls_out or "").splitlines():
+        parts = line.split()
+        if len(parts) >= 6 and parts[0][:1] in "-dlcbps" and parts[4].isdigit():
+            return int(parts[4])
+    return None
+
+
+def _indexed_paths(d, name):
+    """这个文件名在相册索引里对应哪些路径（MediaStore 的 `_data` 列表）。"""
+    query = ("content query --uri content://media/external/video/media --user 0 "
+             f"--projection _id:_display_name:_data --where \"_display_name='{name}'\"")
+    out = _sh(d, query)
+    return [m.group(1) for m in re.finditer(r"_data=(\S+)", out or "")]
+
+
+def scan_media(d, remote):
+    """触发相册刷新，并**按路径**验证它真的进了相册索引。
+
+    返回 `(verify, detail)`：`verify` ∈ `ok`（**这个路径**在索引里）/ `no_index`（扫完还是查不到）。
+
+    ⚠ 为什么要验证：相册读的是 MediaStore 索引，`adb push` 只是放文件 ——
+    推成功但相册看不到是个**静默失败**（"点了第一个缩略图结果点到别的东西"就是这么来的）。
+    ⚠ **必须比路径而不是比文件名**：同一个 plan id 可能在老目录里还留着同名副本
+    （实测 A01 上 `Movies/rp` + `DCIM/rp` 各有一份），只比名字会把"老副本在索引里"
+    误判成"新文件已就绪" —— 相册里点第一个，点到的是那份指向旧文件的记录。
+    ⚠ 命令只用**实测有效**的那两条：Android 12 上 `am broadcast MEDIA_SCANNER_SCAN_FILE`
+    已基本无效（返回 result=0 但什么也不做），真正干活的是 `content call … scan_file`；
+    老写法里那条 `MEDIA_MOUNTED` 广播在新系统上无效、还可能触发全盘重扫，已去掉。
+    """
+    for cmd in (f"content call --uri content://media/external/file --method scan_file --arg '{remote}'",
+                f"am broadcast -a android.intent.action.MEDIA_SCANNER_SCAN_FILE -d file://{remote}"):
+        try:
+            _sh(d, cmd)
+        except Exception as e:
+            _log.warning(f"媒体扫描命令失败（继续）: {e}")
+    time.sleep(SCAN_WAIT)
+    name = remote.split("/")[-1]
+    want = _norm_path(remote)
+    others = []
+    for _ in range(3):          # 索引有时慢半拍，给它一秒再查两次
+        try:
+            paths = _indexed_paths(d, name)
+            if any(_norm_path(p) == want for p in paths):
+                return "ok", f"已进相册索引（{remote}）"
+            others = [p for p in paths if _norm_path(p) != want]
+        except Exception as e:
+            _log.warning(f"查相册索引失败（当作没进）: {e}")
+            break
+        time.sleep(1)
+    if others:
+        _log.warning(f"⚠ 相册索引里只有**同名但不同路径**的记录：{others[:2]} ——"
+                     f"这个文件本身（{remote}）还没进索引")
+    _log.warning(f"⚠ 文件已推到 {remote}，但**没进相册索引**（相册里可能看不到它）——"
+                 f"推送目录 {ALBUM_DIR} 或系统抓取策略可能要调整，见 doc/TASK_DEV.md §4.7")
+    return "no_index", "扫完仍没进相册索引（相册里可能看不到它）"
+
+
+def drop_old_copies(d, plan_id, keep, ext=".mp4"):
+    """把**同一个计划**在平台用过别的目录里的旧副本删掉（精确文件名，绝不通配）。
+
+    为什么要删：换了推送目录之后，老目录里的同名副本还在相册里（实测一个 plan id 躺了 3 份），
+    "点第一个缩略图 = 刚推的那个"就不成立了。删完顺手扫一下，让相册索引把那行去掉。
+    """
+    gone = []
+    for adir in KNOWN_ALBUM_DIRS:
+        old = f"{adir}/{plan_id}{ext}"
+        if _norm_path(old) == _norm_path(keep):
+            continue
+        try:
+            if _remote_size(_sh(d, f"ls -l '{old}'")) is None:
+                continue
+            _sh(d, f"rm -f '{old}'")
+            _sh(d, f"content call --uri content://media/external/file --method scan_file --arg '{old}'")
+            gone.append(old)
+        except Exception as e:
+            _log.warning(f"清旧副本失败（不影响本次推送）: {old}: {e}")
+    if gone:
+        _log.info(f"已清掉同一计划在旧目录里的副本: {gone}")
+    return gone
+
+
+def verify_pushed(d, remote):
+    """**推送后的一致性检查**：文件在不在 + 进没进相册索引。返回 (verify, detail)。
+
+    `verify` ∈ `ok` / `no_index` / `nofile`。**这是"推送成功"的判据**：
+    只看文件在不在是不够的 —— 后面的步骤要在相册里点它。
+    """
+    size = _remote_size(_sh(d, f"ls -l '{remote}'"))
+    if size is None:
+        return "nofile", "手机上找不到这个文件"
+    return scan_media(d, remote)
+
+
+def clean_phone_video(d, remote):
+    """删手机上的素材（**精确路径**，绝不通配 —— 通配会删掉用户自己拍的东西）。"""
+    if not remote:
+        return False
+    try:
+        _sh(d, f"rm -f '{remote}'")
+        if _remote_size(_sh(d, f"ls -l '{remote}'")) is not None:
+            _log.warning(f"手机上的素材没删掉: {remote}")
+            return False
+        return True
+    except Exception as e:
+        _log.warning(f"删手机素材异常（不影响发布结论）: {e}")
+        return False
+
+
+def _first_album_item(d):
+    """点相册/作品网格里的**第一个**缩略图（抖音按时间倒序，最新的在最前）。
+
+    不用固定坐标：dump 出网格里的图片单元，按 (y, x) 排序取第一个 ——
+    分辨率/刘海不同的机器都能用。仅用于**抓分享链接**（进「我」的作品第一条）。
+    """
+    try:
+        xml = d.dump_hierarchy()
+    except Exception as e:
+        return False, f"dump 失败: {e}"
+    cells = []
+    for m in re.finditer(r"<node[^>]*>", xml):
+        tag = m.group(0)
+
+        def g(k):
+            mm = re.search(k + r'="([^"]*)"', tag)
+            return mm.group(1) if mm else ""
+        bounds = g("bounds")
+        mb = re.match(r"\[(\d+),(\d+)\]\[(\d+),(\d+)\]", bounds)
+        if not mb:
+            continue
+        x0, y0, x1, y1 = (int(v) for v in mb.groups())
+        if y0 < 200 or (y1 - y0) < 120 or (x1 - x0) < 120:
+            continue
+        cells.append((y0, x0, (x0 + x1) // 2, (y0 + y1) // 2))
+    if not cells:
+        return False, "没找到缩略图"
+    cells.sort()
+    d.click(cells[0][2], cells[0][3])
+    return True, f"点了第一个缩略图 ({cells[0][2]},{cells[0][3]})"
+
+
+def _click_any(d, sels, timeout=3):
+    """按顺序试几个选择器（形如 "text=分享" / "descriptionContains=分享"），点中即返回。"""
+    for sel in sels:
+        try:
+            key, val = sel.split("=", 1)
+            el = d(**{key: val})
+            if el.exists(timeout=timeout):
+                el.click()
+                return True, sel
+        except Exception:
+            continue
+    return False, ""
+
+
+def capture_share_link(d, serial, timeout=30):
+    """抓作品的分享链接：我 → 作品第一条 → 分享 → 复制链接 → 读剪贴板。
+
+    返回 (url, msg)。**抓不到不算失败**：链接空着，界面上标"缺链接"、素材文件不删。
+    ⚠ 这一段仍是抖音 UI 流程，**按文字定位、需真机确认**；抖音改版就走不通。
+    """
+    from core.video_plan import extract_share_url
+    from core.clipboard_helper import inject_clipboard
+    try:
+        _click_any(d, ["descriptionContains=我", "text=我"], timeout=4)
+        time.sleep(2)
+        ok, msg = _first_album_item(d)
+        if not ok:
+            return "", f"进作品页失败: {msg}"
+        time.sleep(2.5)
+        ok, sel = _click_any(d, ["descriptionContains=分享", "text=分享"], timeout=4)
+        if not ok:
+            return "", "没找到「分享」按钮"
+        time.sleep(1.5)
+        ok, sel = _click_any(d, ["text=复制链接", "text=复制"], timeout=4)
+        if not ok:
+            return "", "分享面板里没找到「复制链接」"
+        time.sleep(1.2)
+        try:
+            got = d.clipboard
+        except Exception as e:
+            return "", f"读剪贴板失败: {e}"
+        url = extract_share_url(got or "")
+        return (url, "ok") if url else ("", f"剪贴板里没有抖音链接: {str(got)[:60]!r}")
+    except Exception as e:
+        return "", f"抓链接异常: {type(e).__name__}: {str(e)[:100]}"
+
+
+# ================== 编排 ==================
+def push_one(serial, plan, opts=None, log=None):
+    """把一条计划的素材推到手机（**不发布**）。返回 (ok, msg)。
+
+    做四件事：原子占位（防多设备/重跑重复推）→ 推文件 → 触发相册刷新 →
+    （可选）把标题写进手机剪贴板，供你后面画的「粘贴」步骤直接用。
+
+    占位成功后把 `stage` 置成 `post` —— 意思是"**后面的事不归平台管了**"：
+    再出岔子（比如你标记失败）按 `unknown` 处理，而不是"可安全重试"，
+    避免任务把一条你其实已经发出去的计划又推一遍、又发一遍。
+    """
+    opts = opts or {}
+    log = _log_of(log)
+    import uiautomator2 as u2
+    from core import video_plan as vp
+
+    plan_id = plan["id"]
+    if not vp.claim(plan_id, status=vp.ST_PUSHING, stage=vp.STAGE_MANUAL):
+        return False, "这条已被别的任务/设备领走了（跳过）"
+    d = None
+    try:
+        local = vp._video_path(plan.get("video_file"))
+        if not local or not os.path.exists(local):
+            vp.mark_failed(plan_id, "push", "平台上的素材文件不在了（可能已被清理，要发请重传视频）")
+            return False, "平台素材缺失"
+        d = u2.connect(serial)
+        remote, err = push_video(d, serial, local, plan_id,
+                                 album_dir=opts.get("album_dir") or ALBUM_DIR)
+        if err:
+            vp.mark_failed(plan_id, "push", err)
+            return False, err
+        log(f"素材已推到手机: {remote}")
+        verify, vmsg = verify_pushed(d, remote)
+        if verify == "nofile":
+            # 文件都不在 → 真失败（可重试），别往后走
+            vp.mark_failed(plan_id, "push", vmsg)
+            return False, f"推送校验失败：{vmsg}"
+        log(f"推送校验：{'✅ ' + vmsg if verify == 'ok' else '⚠ ' + vmsg}")
+        title = (plan.get("title") or "").strip()
+        if opts.get("to_clipboard", True) and title:
+            try:
+                from core.clipboard_helper import inject_clipboard
+                okc, msgc = inject_clipboard(serial, title, d=d)
+                log(f"标题已写进剪贴板（{'成功' if okc else '失败: ' + msgc}）"
+                    f"—— 后面用「粘贴」步骤就能填进抖音")
+            except Exception as e:
+                log(f"标题写剪贴板失败（不影响推送）: {e}")
+        vp.mark_pushed(plan_id, remote=remote, verify=verify)
+        return True, (f"已推送到手机：{remote}" if verify == "ok"
+                      else f"已推送到手机：{remote}（⚠ {vmsg}）")
+    except Exception as e:
+        vp.mark_failed(plan_id, "push", f"异常: {type(e).__name__}: {str(e)[:150]}")
+        return False, f"推送异常: {type(e).__name__}"
+    finally:
+        try:
+            row = vp.get_plan(plan_id)
+            if row and row["status"] == vp.ST_PUSHING and not row.get("stage") == vp.STAGE_MANUAL:
+                vp.mark_failed(plan_id, "push", "执行中断（兜底降级）")
+        except Exception:
+            pass
+
+
+def run_push(serial, plan_id, opts=None):
+    """给计划页「推送到手机」按钮用的入口（在后台线程里跑）。"""
+    from core import video_plan as vp
+    plan = vp.get_plan(plan_id)
+    if not plan:
+        _log.warning(f"推送：计划 {plan_id} 不存在")
+        return False, "计划不存在"
+    return push_one(serial, plan, opts)

templates/admin/login.html

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

templates/admin/wall.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>设备监控大屏</title>
+<title>{% if db_env and not db_env.is_prod %}{{ db_env.env }}-{% endif %}设备监控大屏</title>
 <style>
 /* ========== 监控大屏：深色控制室风格 ========== */
 @font-face{font-family:'Bricolage Grotesque';font-style:normal;font-weight:700;font-display:swap;src:url('/static/fonts/bricolage-700.woff2') format('woff2')}
@@ -73,6 +73,17 @@ main{position:relative;z-index:2;height:calc(100vh - 88px);overflow-y:auto;paddi
 .card .info .name{font-size:13.5px;font-weight:700;color:#f1f4f8;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .card .info .ip{font-family:var(--mono);font-size:12px;color:var(--muted);margin-top:2px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .card .info .model{font-size:10.5px;color:var(--faint);margin-top:2px}
+/* 型号 + 电量同一行（省一行高度，卡片本来就矮） */
+.card .info .meta{display:flex;align-items:center;gap:8px;margin-top:2px;white-space:nowrap;overflow:hidden}
+.card .info .meta .model{margin-top:0;overflow:hidden;text-overflow:ellipsis}
+.card .info .batt{margin-left:auto;display:inline-flex;align-items:center;gap:2px;font-size:11px;color:var(--faint);flex:0 0 auto}
+.card .info .batt .lv{font-family:var(--mono);font-weight:700}
+.card .info .batt.ok .lv{color:var(--green)}
+.card .info .batt.low .lv{color:var(--amber)}
+.card .info .batt.crit .lv{color:var(--red)}
+.card .info .batt.crit{animation:pulse 1.6s infinite}
+.card .info .batt.stale{opacity:.4}
+.card .info .batt .chg{color:var(--teal)}
 .card .info .action{font-size:11.5px;color:var(--muted);margin-top:6px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;min-height:16px}
 .card .info .action b{color:var(--amber);font-weight:600}
 .card .info .prog{margin-top:7px;height:4px;background:#1d242e;border-radius:99px;overflow:hidden}
@@ -202,8 +213,8 @@ async function refreshStatus(){
   const r=await apiGet('/api/status');
   if(!r||!r.ok)return;
   const devs=(r.devices||[]).sort((a,b)=>a.serial.localeCompare(b.serial));
-  const changed=JSON.stringify(devs.map(d=>[d.serial,d.present,d.worker_status,d.task_job,d.current_action,d.progress,d.device_name,d.model]))!==
-                JSON.stringify(_devices.map(d=>[d.serial,d.present,d.worker_status,d.task_job,d.current_action,d.progress,d.device_name,d.model]));
+  const changed=JSON.stringify(devs.map(d=>[d.serial,d.present,d.worker_status,d.task_job,d.current_action,d.progress,d.device_name,d.model,d.battery]))!==
+                JSON.stringify(_devices.map(d=>[d.serial,d.present,d.worker_status,d.task_job,d.current_action,d.progress,d.device_name,d.model,d.battery]));
   _devices=devs;
   renderStats(devs);
   if(changed)renderGrid(visibleDevs(devs));
@@ -249,6 +260,22 @@ function fmtProgress(p){
 }
 function shortIp(serial){return String(serial||'').replace(/:5555$/,'');}
 
+// 电量：告警档位（tier 0 正常/1 低/2 严重）由后端算好，前端只上色——
+// 阈值只在「工具 → 设备发现 → 电量监控」一处定义，前端不重复判，免得两边不一致
+function battHtml(d){
+  const b=d.battery;
+  if(!b)return '<span class="batt">🔋<span class="lv">—</span></span>';
+  const t=b.tier||0;
+  const cls=t===2?'crit':(t===1?'low':'ok');
+  const chg=b.charging?'<span class="chg" title="充电中">⚡</span>':'';
+  const mins=b.at?Math.floor((Date.now()/1000-b.at)/60):-1;
+  const minsTxt=(mins<0?'未知':(mins<1?'刚刚':mins+' 分钟前'));
+  const tip=(t===2?'电量严重不足':(t===1?'电量低':'电量正常'))
+    +'（'+minsTxt+'采集'+(d.present?'':'，设备已离线，显示最后一次读数')+'）';
+  return '<span class="batt '+cls+(d.present?'':' stale')+'" title="'+tip+'">🔋'
+    +'<span class="lv">'+b.level+'%</span>'+chg+'</span>';
+}
+
 function cardHtml(d, i){
   const cls=cardCls(d);
   const serial=esc(d.serial);
@@ -268,7 +295,8 @@ function cardHtml(d, i){
     '<div class="info">'+
       '<div class="name">'+name+'</div>'+
       '<div class="ip">'+ip+'</div>'+
-      '<div class="model">'+esc(d.model||'')+'</div>'+
+      '<div class="meta"><span class="model">'+esc(d.model||'')+'</span>'
+        +'<span class="batt-wrap">'+battHtml(d)+'</span></div>'+
       action+fmtProgress(d.progress)+
       '<div class="hint">点击进入设备操作</div>'+
     '</div>'+
@@ -306,6 +334,9 @@ function renderGrid(devs){
       card.querySelector('.name').textContent=d.device_name||d.model||'设备';
       card.querySelector('.ip').textContent=shortIp(serial);
       card.querySelector('.model').textContent=d.model||'';
+      // 电量（与型号同一行，见 .meta）
+      const bw=card.querySelector('.batt-wrap');
+      if(bw)bw.innerHTML=battHtml(d);
       const action=d.current_action
         ?(d.task_job?'<b>'+esc(d.task_job)+'</b> · ':'')+esc(d.current_action)
         :(d.task_job?'<b>'+esc(d.task_job)+'</b>':'');

web/__init__.py

@@ -6,9 +6,13 @@
   tasks       — 任务计划/分组/自定义动作/元素抓取/步骤测试
   admin       — 用户管理/日志
   tools       — adb 终端/剪贴板注入/应用版本
-  devices     — 设备池管理
+  devices     — 设备池管理 + 账号台账
+  video_plan  — 视频发布计划（上传/时间线/链接导出/单条发布）
   apks        — 应用管理
   tailscale   — Tailscale 管理
+  system      — 系统数据备份导出/导入
+  device_agent— 设备端 Agent 专用接口（应用商店：清单/下载/上报）+ 其管理端配置
+  notify      — 通知 / Webhook 管理（配置、测试发送、发送记录、事件目录）
 """
 from flask import Blueprint
 
@@ -21,8 +25,16 @@ def register_blueprints(app):
     from .admin_api import bp as admin_bp
     from .tools_api import bp as tools_bp
     from .devices_api import bp as devices_bp
+    from .video_plan_api import bp as video_plan_bp
     from .apks_api import bp as apks_bp
     from .tailscale_api import bp as tailscale_bp
+    from . import agent_api as _agent_mod
+    from .agent_api import bp as agent_bp
+    _agent_mod.set_app(app)
+    from .system_api import bp as system_bp
+    from .device_agent_api import bp as devagent_bp
+    from .notify_api import bp as notify_bp
     for bp in (auth_bp, monitor_bp, tasks_bp, admin_bp, tools_bp,
-               devices_bp, apks_bp, tailscale_bp):
+               devices_bp, video_plan_bp, apks_bp, tailscale_bp, agent_bp, system_bp,
+               devagent_bp, notify_bp):
         app.register_blueprint(bp)

web/admin_api.py

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