feat: 设备分组移入工具页（原顶级 tab 删除）——工具页新增「设备分组」子分栏，分组管理入口与其他设备工具聚合

- _merge_status 清理不在 STF 设备池且无运行 worker 的陈旧状态
- /api/summary 按当前设备池过滤，STF 异常时不隐藏任何记录

.env.example

@@ -0,0 +1,41 @@
+# 环境变量示例：复制为 .env 并按需修改（.env 不进 git）
+# 生产环境建议用环境变量/密钥管理注入，不要把真实 token 写进 git。
+# 全部可配置项见 config.py（_env() 读取，未配置时用代码内默认值）；
+# 标"必须"的项务必设置，其余可留空用默认。
+
+# ==================== STF 平台 ====================
+# STF 服务地址（默认 http://192.168.20.220:7100）
+STF_URL=http://192.168.20.220:7100
+
+# STF API Token（必须：STF 个人设置 → API Keys 生成）
+STF_TOKEN=请填写你的STF_token
+
+# 启动时自动释放残留 STF 占用（单实例无人值守开 true；多实例共用账户勿开，会误放另一实例的任务）
+# AUTO_RELEASE_STALE_OCCUPY=true
+
+# ==================== Web 会话 ====================
+# Web 会话密钥（必须：生产设置为随机长字符串，重启不失效）
+# 生成：python -c "import secrets; print(secrets.token_hex(32))"
+WEB_SECRET_KEY=请填写随机密钥
+
+# ==================== SSH 到部署机（维护页重启 STF / 工具页 STF 设备管理） ====================
+# SSH 目标（默认 [email protected]）
+# [email protected]
+
+# 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
+
+# STF 设备池脚本路径（工具页"STF 设备管理"增删设备时读写其 DEVICES 列表，默认值见 config.py）
+# STF_SCRIPT_PATH=/mnt/data/openstf/connect_devices.sh
+
+# ==================== Tailscale 管理（工具页） ====================
+# API key（必须：Tailscale 后台 → Settings → API Access Tokens 生成）
+TAILSCALE_API_KEY=请填写Tailscale_API_key
+
+# tailnet 名/ID（默认按邮箱前缀，如 [email protected]）
+# [email protected]

.gitignore

@@ -12,6 +12,8 @@ env/
 logs/*.log
 data/apks/*.apk
 data/*.migrated
+data/*.db-shm
+data/*.db-wal
 
 # 数据库（含用户和任务数据，按需决定是否提交）
 
@@ -22,6 +24,9 @@ data/*.migrated
 *.swp
 *.swo
 
+# Trae / AI 工具产物
+.claude/
+
 # OS
 .DS_Store
 Thumbs.db
@@ -31,5 +36,15 @@ desktop.ini
 *.tmp
 *.bak
 
+# 密钥/环境变量（真实 .env 含 token/密钥，绝不提交）
+.env
+.env.local
+
 
 bin/adb/*
+# 数据备份与损坏库（运维临时文件，不入库）
+data/db_backup_*/
+data/*.corrupt_*
+data/users.db*
+data/users.db-wal
+data/users.db-shm

README.md

@@ -0,0 +1,467 @@
+# 设备自动化后台（platform-tools）
+
+基于 **uiautomator2 + Flask + 自建设备池** 的 Android 多设备自动化任务执行平台（已摘除 OpenSTF 依赖）。
+
+提供 Web 管理后台，支持多设备并发任务执行、定时调度、设备分组管理、设备池管理（新增/停用/删除/型号采集）、APK 批量安装、网页远程看屏（MJPEG 实时流 + 触控）、UI 元素抓取等功能。内置抖音养号任务和通用步骤任务，可扩展任意 App 的自动化操作。
+
+---
+
+## 目录
+
+- [快速上手](#快速上手)
+- [项目结构](#项目结构)
+- [核心概念](#核心概念)
+- [配置说明](#配置说明)
+- [Web 管理后台](#web-管理后台)
+- [任务系统](#任务系统)
+- [日志系统](#日志系统)
+- [常用脚本](#常用脚本)
+- [常见问题](#常见问题)
+- [更多文档](#更多文档)
+
+---
+
+## 快速上手
+
+### 环境要求
+
+- **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）
+
+### 三步启动
+
+```bash
+# 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）
+
+# 3. 启动 Web 后台
+python web_server.py
+```
+
+启动后访问 **http://localhost:18050/**，默认账号 `admin` / `admin123`。
+
+### 验证启动
+
+控制台看到以下日志即表示启动成功：
+
+```
+[INFO] [core.worker] 心跳看门狗已启动
+[INFO] [core.tm] 从数据库加载 X 个分组, X 个任务
+[INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
+[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 实时查看运行日志
+
+---
+
+## 项目结构
+
+```
+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 依赖清单
+│
+├── 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 框架
+│
+├── tasks/                       # 任务定义层（每个 App 一个子包）
+│   ├── __init__.py              #   全局任务注册表
+│   ├── base.py                  #   BaseTask 基类 + @register_task 装饰器
+│   ├── douyin/                  #   抖音养号任务
+│   └── generic/                 #   通用步骤任务（可视化编辑器编排）
+│       └── task.py              #     步骤执行引擎（open_app/click/swipe/if_el...）
+│
+├── templates/admin/             # 前端页面
+│   ├── monitor.html             #   单页应用（监控/任务/分组/日志/用户/工具）
+│   └── login.html               #   登录页
+│
+├── 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（分组/日志/用户）+ 初始化
+├── 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 接口文档
+```
+
+---
+
+## 核心概念
+
+### 设备生命周期
+
+```
+设备池选定设备（TaskManager._running 内存锁保证互斥）
+    ↓
+IP:5555 → adb connect 直连；USB（serial 无冒号）→ 本机 adb 或 220 远程 adb server
+    ↓
+u2.connect（连接 uiautomator2，自动推送 atx-agent）
+    ↓
+Worker.run_task（执行业务逻辑）
+    ↓
+释放（不 disconnect，遵守共享 adb transport 红线）
+```
+
+> 单实例部署下互斥由调度器内存锁保证；多实例场景可扩展 SQLite 行锁（见 doc/STF_REMOVAL.md 阶段 4）。
+
+### Worker — 单设备执行线程
+
+每台设备对应一个 `Worker` 线程，继承 `BaseWorker`（`core/device_worker.py`）。基类已封装：
+
+- 设备获取（IP:5555 直连 / USB 远程 adb server，try/finally 保证释放）
+- adb 连接 + u2.connect（带 30 秒超时保护）
+- 状态上报（实时推送到前端监控大屏）
+- 异常捕获（设备离线不重试，其他异常按策略重试）
+- stop 停止信号（循环里检查 `self.stopped()`）
+- 心跳看门狗（120 秒无心跳自动标记卡死）
+
+子类只需实现 `run_task(d)` 方法专注业务逻辑。
+
+### TaskType — 任务类型
+
+| 任务类型 | 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 |
+
+**简单设置**：编辑任务时选"定时启动/定时启动+停止"后，频率用下拉选择——每天（选时间）、每小时（整点）、每隔 N 小时、每周（选星期+时间）——cron 表达式自动生成，不需要懂 cron 语法。老手可在"自定义 cron（高级）"里直接填。
+
+cron 表达式为标准 5 段格式：`分 时 日 月 周`（如 `0 9 * * *` = 每天 9:00，`0 */2 * * *` = 每 2 小时整点，周 `0`/`7` 均为周日）
+
+**运行窗口**：任务可勾选"启用运行窗口"，设置每天允许运行的时间段（如 `21:00-09:00` = 晚 9 点到次日早 9 点，支持跨午夜）。窗口外**定时触发和手动执行都不会启动**（手动执行会提示"当前不在运行窗口内"）。典型用法：`每小时`定时 + 窗口 `09:00-21:00`，即只在白天每小时跑一次。
+
+### 设备分组
+
+设备分组存于 SQLite，便于按批次/项目分组下发任务。一个 Job 指定 `target.mode="group"` 时，调度器展开为组内全部设备。
+
+### 进度上报
+
+Worker 通过 `self.set_progress()` 上报通用进度字段，前端统一解析展示：
+
+```python
+self.set_progress(done=5, total=80, unit="视频",
+                  action_counts={"like": 3})
+```
+
+前端展示：进度条 + `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）；其余均为可选（默认值开箱即用）。
+
+---
+
+## Web 管理后台
+
+### 页面结构
+
+单页应用（`templates/admin/monitor.html`），6 个 Tab；任务/工具 Tab 内部再有页内子分栏：
+
+| Tab | 功能 | 可见性 |
+|-----|------|--------|
+| 监控 | 设备状态大屏：在线/离线、型号、运行任务、当前动作、进度条、前台 App、截图、勾选批量操作（亮屏/息屏/停止）；导航栏「📺 大屏」打开全屏监控墙（/wall，缩略图+统计+时钟，挂墙/电视用） | 所有登录用户（设备操作按钮需"设备控制"权限） |
+| 任务 | 子分栏：任务计划（CRUD/启用停用/立即执行/下次运行时间/**离线设备自动跳过**）、自定义动作（打包复用） | 所有登录用户可看，写操作需"任务管理"权限 |
+| 分组 | 设备分组管理：创建/编辑/删除分组 | 所有登录用户可看，写操作需"任务管理"权限 |
+| 日志 | 实时日志查看：按模块切换（core/task/web/action） | 需"日志查看"权限 |
+| 用户 | 用户管理：创建/删除/修改密码/分配权限 | 仅管理员 |
+| 工具 | 子分栏：剪贴板注入、adb 远程终端（快捷命令/自动 `-s`）、**设备池管理**（新增/停用/删除/一键重连/型号采集）、**远程看屏**（MJPEG 实时流 + 点击/滑动/按键/文字）、Tailscale 管理（改名/授权/密钥不过期/设置IP/auth key）、应用管理（APK 上传安装）、应用版本管理（按包名查所有设备版本）、设备已装应用 | 仅管理员 |
+
+任务/工具 Tab 的子分栏会记住上次选中的位置；无权限的 tab 和按钮自动隐藏。
+
+### 用户与权限
+
+默认账号 `admin` / `admin123`（管理员，拥有全部权限）。管理员可在"用户"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` 启动时会自动拉起。
+
+---
+
+## 任务系统
+
+### 抖音养号（douyin_nurture）
+
+自动观看抖音视频，按配置随机执行点赞操作。参数（在 `tasks/douyin/task.py` 顶部）：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `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(双击) |
+
+终止条件（哪个先到就停）：`watch_count` 数量到 / `max_duration` 时长到 / 手动停止。
+
+### 通用步骤（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)。
+
+---
+
+## 日志系统
+
+日志按模块分文件，自动滚动（10MB 一份，保留 5 份历史）：
+
+| 文件 | 模块前缀 | 内容 |
+|------|---------|------|
+| `logs/core.log` | `core.*` | adb/worker/task_manager/设备池 核心程序 |
+| `logs/task.log` | `task.*` | 任务执行（worker 业务逻辑） |
+| `logs/web.log` | `web.*` | Web 请求/管理 |
+| `logs/action.log` | `action.*` | 操作执行（点赞/评论等） |
+
+使用方式：
+
+```python
+from core.logger import get_logger
+log = get_logger("task.douyin")    # 写入 task.log
+log.info(f"[{self.serial}] 开始任务")
+```
+
+Web 后台"日志"Tab 可实时查看各模块日志。
+
+---
+
+## 常用脚本
+
+| 脚本 | 用途 |
+|------|------|
+| `python web_server.py` | 启动 Web 管理后台 |
+| `python scripts/pack.py` | 打包项目为 zip（排除日志/数据库/APK） |
+| `bash scripts/supervise.sh` | 进程守护（web_server 崩溃自动重启） |
+
+---
+
+## 常见问题
+
+### 端口被占用（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` 启动时会自动拉起该服务。
+
+---
+
+## 更多文档
+
+| 文档 | 内容 |
+|------|------|
+| [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 接口说明） |
+
+> **注意**：所有 git 操作（含 push 到 dev）都需负责人确认后才能执行，详见开发手册。修改 `core/`、`tasks/`、`templates/` 后需重启服务/强刷浏览器才生效。
+
+---
+
+## 技术栈
+
+| 组件 | 用途 |
+|------|------|
+| Flask + Flask-Login | Web 后台 + 用户认证 |
+| Flask-SQLAlchemy | SQLite 数据持久化 |
+| APScheduler | 定时任务调度 |
+| uiautomator2 | Android UI 自动化 |
+| uiautodev | UI 元素抓取（步骤编辑器"抓取元素"） |
+| pyaxmlparser | APK 元信息解析 |
+| 自建设备池 | 设备清单/在线状态/型号（SQLite + adb） |

config.py

@@ -4,12 +4,34 @@
 放各自 tasks/xxx.py 顶部，保持每个任务自包含、互不干扰。
 
 改 STF 地址/token、adb 路径、web 端口都改这里。
+
+安全：STF_TOKEN / WEB_SECRET_KEY 建议用环境变量注入（生产不要提交到 git）。
+支持 `.env` 文件（项目根目录），也可直接 `export STF_TOKEN=xxx`。
 """
 import os
 
-# ================== STF 配置 ==================
+# 可选加载 .env 文件（不存在则忽略）
-STF_URL = "http://192.168.20.220:7100"
+_env_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), ".env")
-STF_TOKEN = "9024544b571647d3a6b09dab5dbfcb28bfd950f5b659400394e44e7217b7051b"
+if os.path.exists(_env_path):
+    try:
+        with open(_env_path, encoding="utf-8") as _f:
+            for _line in _f:
+                _line = _line.strip()
+                if _line and not _line.startswith("#") and "=" in _line:
+                    _k, _v = _line.split("=", 1)
+                    os.environ.setdefault(_k.strip(), _v.strip())
+    except OSError:
+        pass
+
+
+def _env(key, default):
+    """读环境变量，未设置则返回默认值。"""
+    return os.environ.get(key, default)
+
+
+# ================== STF 配置（已废弃，阶段 3 摘除 STF 后仅保留供历史参考） ==================
+STF_URL = _env("STF_URL", "")
+STF_TOKEN = _env("STF_TOKEN", "")   # 写入 .env，不要提交到 git
 
 # ================== adb 路径 ==================
 # adb 二进制及依赖统一放在 bin/adb/ 下
@@ -37,3 +59,33 @@ DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data")
 
 # APK 文件存储目录（应用管理功能）
 APK_DIR = os.path.join(DATA_DIR, "apks")
+
+# ================== SSH 到部署机（已废弃，STF 相关操作退役） ==================
+# 阶段 3 后代码不再使用 SSH；保留配置仅供手动运维 220（如 docker stop stf）。
+STF_SSH_TARGET = _env("STF_SSH_TARGET", "")
+STF_SSH_PASSWORD = _env("STF_SSH_PASSWORD", "")
+STF_DOCKER_CONTAINER = _env("STF_DOCKER_CONTAINER", "")
+STF_ADB_CONTAINER = _env("STF_ADB_CONTAINER", "")
+STF_SCRIPT_PATH = _env("STF_SCRIPT_PATH", "")
+
+# ================== USB 设备远程 adb server（阶段 2） ==================
+# USB 设备插在 220（STF 主机）上，本机 adb 看不到；220 的 adb 容器是 host 网络
+# 模式，5037 已监听所有网卡（含 Tailscale），平台用 adb -H/-P 直接驱动。
+# 平台自身 USB（serial 无冒号且在本机 adb 里）不受影响，仍走本地。
+USB_ADB_HOST = _env("USB_ADB_HOST", "100.100.10.1")   # 220 的 Tailscale IP
+USB_ADB_PORT = int(_env("USB_ADB_PORT", "5037"))
+
+# ================== Tailscale 管理（工具页） ==================
+# 调用官方 API v2 管理 tailnet 设备。配置从 .env 读取：
+#   TAILSCALE_API_KEY：后台 → Settings → API Access Tokens 生成（或 OAuth client_id:secret）
+#   TAILSCALE_TAILNET：tailnet 名称/ID，个人账号一般是登录邮箱前缀
+# 安全：密钥用环境变量/.env 注入，不要写死在代码或提交到 git。
+TAILSCALE_API_KEY = _env("TAILSCALE_API_KEY", "")   # 写入 .env，不要提交到 git
+TAILSCALE_TAILNET = _env("TAILSCALE_TAILNET", "")
+
+# ================== 设备自动发现 ==================
+# 定时扫描网段中开放 adb 5555 的设备 → 待连接池（用户确认后才加入正式池）。
+# 网段默认：局域网 + Tailscale；可在工具页设备池面板修改（存 app_meta）。
+DISCOVERY_PORT = int(_env("DISCOVERY_PORT", "5555"))
+DISCOVERY_SUBNETS = ["192.168.20.0/24", "100.100.10.0/24"]
+DISCOVERY_INTERVAL = int(_env("DISCOVERY_INTERVAL", "60"))

core/__init__.py

@@ -2,7 +2,6 @@
 
   config         — 全局配置常量（STF、adb 路径、养号参数）
   adb_helper     — adb 命令封装（并发安全）
-  stf_client     — OpenSTF REST API 客户端
   device_worker  — 设备生命周期 + 养号 worker + 全局状态注册表
   task_manager   — 任务管理框架（分组/计划/调度/重试/持久化）
 """

core/adb_helper.py

@@ -14,15 +14,44 @@ from core.logger import get_logger
 _log = get_logger("core.adb")
 
 _ADB_LOCK = threading.Lock()
+# adb 命令超时（秒）。adb connect 到不可达主机（如 Tailscale IP 不通）会长时间挂起，
+# 没有超时会让 worker 永久卡在 connecting。connect/disconnect 正常都应瞬时完成。
+_ADB_TIMEOUT = 30
 
 
-def _adb(*args):
+def _adb(*args, timeout=_ADB_TIMEOUT):
     """执行 adb 命令，返回 (stdout+stderr) 文本。不用 shell=True，避免子进程环境问题。
 
     用 bytes 模式自己解码（Windows 下 subprocess text=True 会用 GBK 读 adb 输出，
     遇到非 GBK 字节会崩溃）。
+    带 30s 超时：adb connect 到不可达地址可能挂很久，超时返回空串由调用方处理。
+    timeout 可覆盖（扫描验证等非关键路径用短超时快速失败）。
     """
-    r = subprocess.run([ADB_PATH, *args], capture_output=True)
+    try:
+        r = subprocess.run([ADB_PATH, *args], capture_output=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        _log.warning(f"adb {' '.join(args)} 超时 {timeout}s")
+        return ""
+    return _decode(r)
+
+
+def _adb_remote(host, port, *args):
+    """在远程 adb server（如 220）上执行 adb 命令，返回文本。
+
+    USB 设备插在 220，本机 adb server 看不到，必须 -H/-P 指向 220 的 adb server
+    （host 网络模式，5037 全接口监听，Tailscale 可达）。超时语义同 _adb。
+    """
+    try:
+        r = subprocess.run([ADB_PATH, "-H", host, "-P", str(port), *args],
+                           capture_output=True, timeout=_ADB_TIMEOUT)
+    except subprocess.TimeoutExpired:
+        _log.warning(f"adb -H {host} -P {port} {' '.join(args)} 超时 {_ADB_TIMEOUT}s")
+        return ""
+    return _decode(r)
+
+
+def _decode(r):
+    """subprocess 结果解码（Windows GBK 兼容）。"""
     out = (r.stdout or b"") + (r.stderr or b"")
     try:
         return out.decode("utf-8", errors="replace").strip()
@@ -69,6 +98,41 @@ def get_foreground_app(remote_adb_url, timeout=3):
         return None
 
 
+def get_foreground_app_remote(host, port, serial, timeout=3):
+    """远程 adb server（220）上设备的前台 App（USB 设备用）。
+
+    与 get_foreground_app 同逻辑，只是 adb 指向远程 server（-H/-P）。
+    """
+    if not serial:
+        return None
+    try:
+        r = subprocess.run(
+            [ADB_PATH, "-H", host, "-P", str(port), "-s", serial, "shell",
+             "dumpsys window | grep mCurrentFocus"],
+            capture_output=True, timeout=timeout
+        )
+        out = ((r.stdout or b"") + (r.stderr or b"")).decode("utf-8", errors="replace").strip()
+        if not out:
+            return None
+        low = out.lower()
+        if "device offline" in low or "device not found" in low or "error:" in low:
+            return None
+        for line in out.split("\n"):
+            if "mCurrentFocus" not in line:
+                continue
+            m = re.search(r'\bu0\s+(\S+)', line)
+            if m:
+                token = m.group(1).rstrip("}")
+                if "/" in token:
+                    return token.split("/")[0]
+                return token or None
+        return None
+    except subprocess.TimeoutExpired:
+        return None
+    except Exception:
+        return None
+
+
 def adb_connect(remote_adb_url, retries=5):
     """adb connect（带重试）。返回 True/False。
 
@@ -94,16 +158,18 @@ def _try_connect(remote_adb_url, retries):
     return False
 
 
-def adb_connect_light(remote_adb_url):
+def adb_connect_light(remote_adb_url, timeout=5):
-    """轻量 adb connect（扫描专用）：单次尝试，不重试，绝不 kill-server。
+    """轻量 adb connect（扫描/验证专用）：单次尝试，不重试，绝不 kill-server。
 
     与 adb_connect 的区别：
       - 不重试：失败立即返回 False
       - 不 kill-server：避免断开其他 worker 正在使用的 ADB 连接
+      - 短超时（默认 5s）：验证场景（设备发现）连不上的主机快速放弃，
+        避免每台卡 30s 拖慢整轮发现并长时间占用全局 adb 锁
     用于前台 App 扫描等非关键路径，连不上就跳过，不影响正在运行的任务。
     """
     with _ADB_LOCK:
-        out = _adb("connect", remote_adb_url)
+        out = _adb("connect", remote_adb_url, timeout=timeout)
         if "connected" in out.lower() and "failed" not in out.lower():
             return True
         return False
@@ -146,6 +212,148 @@ def screenshot(serial, timeout=5):
         return False, str(e)
 
 
+# 常见应用名映射：快速识别大/重要应用，避免拉取 APK 解析（慢）
+COMMON_APPS = {
+    "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.settings": "设置",
+    "com.android.systemui": "系统",
+    "com.github.uiautomator": "ATX",
+    "com.github.uiautomator.test": "ATX测试",
+    "jp.co.cyberagent.stf": "STF服务",
+    "moe.shizuku.privileged.api": "Shizuku",
+    "moe.shizuku.api": "Shizuku",
+    "io.tailscale.android": "Tailscale",
+    "com.immomo.momo": "陌陌",
+    "com.xingin.xhs": "小红书",
+}
+# 解析应用名时，超过该大小的 APK 不拉取（太慢），用映射或包名兜底
+_LABEL_PARSE_MAX_BYTES = 5 * 1024 * 1024  # 5MB
+# 应用名缓存：(serial, package) -> label
+_APP_LABEL_CACHE = {}
+
+
+def list_installed_apps(serial, timeout=40):
+    """获取设备上已安装应用列表：应用名 + 包名 + versionCode + versionName + APK路径。
+
+    - `pm list packages --show-versioncode -f` 取包名/版本码/路径（快）
+    - `pm dump packages` 取人性化 versionName（实测 ~0.8s）
+    - 应用名 label：常见应用走映射；用户安装且较小(<=10MB)的未知应用流式拉 APK 用
+      pyaxmlparser 解析（带缓存），其余用包名兜底。
+    返回 (ok, apps) 或 (False, 错误消息)。
+    """
+    if not serial:
+        return False, "缺少 serial"
+    try:
+        # 1. 包名 + versionCode + APK 路径
+        r1 = subprocess.run(
+            [ADB_PATH, "-s", serial, "shell", "pm", "list", "packages",
+             "--show-versioncode", "-f"],
+            capture_output=True, timeout=timeout)
+        apps = {}
+        for line in (r1.stdout or b"").decode("utf-8", errors="replace").splitlines():
+            line = line.strip()
+            m = re.match(r'package:(.+)=(\S+) versionCode:(\d+)', line)
+            if m:
+                apps[m.group(2)] = {"package": m.group(2), "path": m.group(1),
+                                    "version_code": int(m.group(3)), "version_name": "",
+                                    "label": COMMON_APPS.get(m.group(2), "")}
+            else:
+                m2 = re.match(r'package:(.+)=(\S+)', line)
+                if m2:
+                    apps[m2.group(2)] = {"package": m2.group(2), "path": m2.group(1),
+                                         "version_code": 0, "version_name": "",
+                                         "label": COMMON_APPS.get(m2.group(2), "")}
+        # 2. 人性化版本号 versionName
+        try:
+            r2 = subprocess.run(
+                [ADB_PATH, "-s", serial, "shell", "pm", "dump", "packages"],
+                capture_output=True, timeout=timeout)
+            out2 = (r2.stdout or b"").decode("utf-8", errors="replace")
+            for m in re.finditer(r'Package \[([^\]]+)\]', out2):
+                pkg = m.group(1)
+                if pkg not in apps:
+                    continue
+                nxt = out2.find("Package [", m.end())
+                seg = out2[m.end():nxt if nxt != -1 else len(out2)]
+                vm = re.search(r'versionName=(\S+)', seg)
+                if vm:
+                    apps[pkg]["version_name"] = vm.group(1)
+        except Exception:
+            pass  # versionName 拿不到不阻塞
+        # 3. 应用名 label：用户安装且未映射的小 APK，流式拉取解析真实名
+        _resolve_app_labels(serial, apps, timeout)
+        return True, sorted(apps.values(), key=lambda a: a["package"])
+    except subprocess.TimeoutExpired:
+        return False, "查询超时"
+    except Exception as e:
+        return False, str(e)
+
+
+def _resolve_app_labels(serial, apps, timeout):
+    """并行解析用户安装小应用的显示名 label（带缓存）。失败/超时静默跳过。"""
+    import io as _io
+    from concurrent.futures import ThreadPoolExecutor
+    targets = [(pkg, a["path"]) for pkg, a in apps.items()
+               if a["path"].startswith("/data/") and not a["label"]
+               and (serial, pkg) not in _APP_LABEL_CACHE]
+    if not targets:
+        return
+    # 用 ls -l 一次拿所有候选 APK 大小，跳过过大的（流式拉大 APK 太慢）
+    sizes = {}
+    try:
+        rsz = subprocess.run(
+            [ADB_PATH, "-s", serial, "shell", "ls", "-l"] + [p for _, p in targets],
+            capture_output=True, timeout=min(timeout, 15))
+        for line in (rsz.stdout or b"").decode("utf-8", errors="replace").splitlines():
+            parts = line.split()
+            # ls -l(toybox): 权限 链接 属主 属组 大小 日期 时间 路径 = 8 字段
+            if len(parts) >= 6:
+                try:
+                    sizes[parts[-1]] = int(parts[4])
+                except ValueError:
+                    pass
+    except Exception:
+        pass
+    small = [(pkg, path) for pkg, path in targets if sizes.get(path, 0) <= _LABEL_PARSE_MAX_BYTES]
+
+    def _fetch(pkg_path):
+        pkg, path = pkg_path
+        label = ""
+        try:
+            rp = subprocess.run(
+                [ADB_PATH, "-s", serial, "exec-out", "cat", path],
+                capture_output=True, timeout=min(timeout, 8))
+            from pyaxmlparser import APK as _APKParser
+            label = (_APKParser(_io.BytesIO(rp.stdout)).get_app_name() or "").strip()
+        except Exception:
+            label = ""
+        _APP_LABEL_CACHE[(serial, pkg)] = label
+        return pkg, label
+
+    if small:
+        try:
+            with ThreadPoolExecutor(max_workers=8) as pool:
+                for pkg, label in pool.map(_fetch, small):
+                    if pkg in apps:
+                        apps[pkg]["label"] = label
+        except Exception:
+            pass  # label 解析失败不影响主流程
+
+
 def identify_device(serial, duration=3):
     """让设备响铃以供识别（直连 serial，不经过 STF）。
 

core/apk_manager.py

@@ -29,7 +29,6 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from config import APK_DIR, ADB_PATH
 from core.logger import get_logger
 from core.models import db, ApkFile as ApkRow
-from .stf_client import STFClient
 from .device_worker import get_all_worker_status
 
 _log = get_logger("core.apk")
@@ -43,8 +42,7 @@ _INSTALL_CONCURRENCY = 5
 class ApkManager:
     """APK 文件管理 + 批量安装。"""
 
-    def __init__(self, stf_client=None, app=None):
+    def __init__(self, app=None):
-        self.stf = stf_client or STFClient()
         self.app = app  # Flask app，用于 db context
         os.makedirs(APK_DIR, exist_ok=True)
         self._lock = threading.Lock()
@@ -194,10 +192,7 @@ class ApkManager:
         if not serials:
             return False, "未选择设备"
 
-        # 获取设备信息（型号等）
+        # 设备信息（型号从 worker 状态取，池内无型号信息）
-        try:
-            all_devices = {d["serial"]: d for d in self.stf.list_all_devices()}
-        except Exception:
         all_devices = {}
 
         # 获取 worker 状态（判断设备是否运行中）
@@ -274,13 +269,15 @@ class ApkManager:
     def _install_one(self, serial, apk_path, package_name=""):
         """直连设备安装 APK。
 
-        serial 即设备的 adb 网络地址（IP:5555），直接 adb connect 即可。
+        serial 为 adb 网络地址（IP:5555）时直接 adb connect；
+        本机 USB 有线设备（serial 无冒号，如 ZY322XXXX）已在 adb 中，无需 connect。
         不经过 STF occupy/release，安装完断开连接，app 永久保留。
         """
         from .adb_helper import _adb
         self._set_item(serial, "installing", f"正在连接 {serial}...")
         try:
-            # adb connect（带重试，设备网络可能需要几次握手）
+            if ":" in serial:
+                # 网络设备：adb connect（带重试，设备网络可能需要几次握手）
                 connected = False
                 last_out = ""
                 for attempt in range(1, 4):  # 最多 3 次
@@ -295,13 +292,46 @@ class ApkManager:
                     _log.warning(f"[{serial}] adb connect 失败: 输出={last_out}")
                     self._set_item(serial, "failed", f"adb connect 失败: {last_out[:150]}")
                     return
+            else:
+                # 本机 USB 设备：确认已在 adb devices 列表中
+                dev_out = _adb("devices")
+                if serial not in (dev_out or ""):
+                    self._set_item(serial, "failed",
+                                   "设备未在本地 adb 列表中，请检查 USB 连接/驱动")
+                    return
 
-            # 安装
+            # 强制安装：绕过厂商安全防护（MIUI 等用 adb install 会弹"通过 USB 安装应用"
-            self._set_item(serial, "installing", "正在安装...")
+            # 确认框需要手点；改为 推送 + pm install，shell 安装不弹窗）
+            # 1. 关闭 adb 安装校验（包校验器/安全守护拦截）
+            try:
+                _adb("-s", serial, "shell", "settings", "put", "global",
+                     "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, "install", "-r", apk_path],
+                [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}")
+                return
+            # 3. pm install 强制安装（-r 覆盖安装 / -t 允许测试包 / -d 允许降级版本）
+            self._set_item(serial, "installing", "正在安装...")
+            r = subprocess.run(
+                [ADB_PATH, "-s", serial, "shell", "pm", "install", "-r", "-t", "-d",
+                 "/data/local/tmp/_install.apk"],
+                capture_output=True, timeout=_INSTALL_TIMEOUT
+            )
+            # 4. 清理设备临时文件（失败残留下次推送会覆盖，不影响）
+            try:
+                _adb("-s", serial, "shell", "rm", "-f", "/data/local/tmp/_install.apk")
+            except Exception:
+                pass
             out = ((r.stdout or b"") + (r.stderr or b""))
             try:
                 out = out.decode("utf-8", errors="replace")

core/clipboard_helper.py

@@ -0,0 +1,69 @@
+"""剪贴板注入公共模块（ClipInject APK 通道）。
+
+背景：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）。
+
+工具页（web/tools_api.py）与任务执行器（tasks/generic/task.py）共用本模块。
+"""
+import base64
+import subprocess
+import time
+from concurrent.futures import ThreadPoolExecutor
+
+from config import ADB_PATH
+from core.adb_helper import adb_connect
+from core.logger import get_logger
+
+_log = get_logger("core.clip")
+
+_CLIP_PACKAGE = "com.example.clipinject"
+_CLIP_ACTIVITY = "com.example.clipinject/.ClipActivity"
+
+
+def inject_clipboard(serial, text, d=None):
+    """向设备剪贴板注入文字，返回 (ok, msg)。
+
+    - d：可选，任务执行器已持有 u2 Device 时传入复用（跳过重复连接），
+      读回验证直接用它；不传则临时 u2.connect（工具页场景，带超时保护）
+    - IP:port 设备先 adb connect（已连接自动跳过；绝不 disconnect，红线）
+    - 未装 ClipInject / 读回不一致都会明确报错（不再静默失败）
+    """
+    import uiautomator2 as u2
+    if ":" in serial:
+        try:
+            adb_connect(serial)
+        except Exception as e:
+            return False, f"adb 连接失败: {e}"
+    b64 = base64.b64encode(text.encode("utf-8")).decode()
+    # 1. am start 透明 Activity 写剪贴板（shell 身份，不受后台启动限制）
+    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)
+    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)
+        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]}）"

core/device_discovery.py

@@ -0,0 +1,340 @@
+"""设备自动发现：扫描网段中开放 adb 5555 的设备 → 待连接池（pending）。
+
+流程：socket 并发探测 5555（标准库，不碰 adb）→ 剔除已在设备池的 serial →
+串行 adb 验证（adb_connect_light，内部全局锁）→ 用 `adb devices` 的
+state=="device" 过滤（排除 unauthorized/offline，connect 输出不可信）→
+写入 pending_device 表。**扫描只验证、不自动连接入池**——用户在前端确认后
+才调 device_pool.add_device + adb_connect（见 web/devices_api.py）。
+
+安全红线：绝不 kill-server / 绝不 disconnect（与全项目一致）。
+
+配置存 app_meta KV 表（discovery_enabled/subnets/interval/port），定时线程
+每轮重读，开关/周期/网段改动即时生效无需重启。
+"""
+import ipaddress
+import json
+import socket
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+
+from config import (USB_ADB_HOST,
+                    DISCOVERY_PORT, DISCOVERY_SUBNETS, DISCOVERY_INTERVAL)
+from core.adb_helper import _adb, adb_connect_light
+from core.logger import get_logger
+from core.models import db, PendingDevice
+
+_log = get_logger("core.disc")
+
+# 扫描配置键（app_meta）
+_K_ENABLED = "discovery_enabled"
+_K_SUBNETS = "discovery_subnets"
+_K_INTERVAL = "discovery_interval"
+_K_PORT = "discovery_port"
+
+# 单网段主机数上限（防误配 /8 之类），超过截断并告警
+_MAX_HOSTS_PER_SUBNET = 1024
+# socket 探测并发数与单 IP 超时
+_PROBE_WORKERS = 64
+_PROBE_TIMEOUT = 0.4
+
+_app = None
+_scan_lock = threading.Lock()     # 定时/手动扫描互斥
+_stop_event = threading.Event()   # shutdown 用
+_scanning = False                 # 状态快照（API/前端）
+_last_scan = None                 # (时间串, 开放数, 可连数, 新增数)
+_last_error = ""
+
+
+def _ctx():
+    """后台线程访问 db 时自行推 app context（仿 device_pool._ctx）。"""
+    return _app.app_context() if _app else None
+
+
+def _fmt(ts=None):
+    return (ts or datetime.now()).strftime("%Y-%m-%d %H:%M")
+
+
+# ================== 配置读写 ==================
+def get_settings():
+    """读发现配置（app_meta，缺键用 config 默认值补齐）。"""
+    with _ctx():
+        def _get(key, default):
+            v = db.session.execute(
+                db.text("SELECT value FROM app_meta WHERE key=:k"), {"k": key}).scalar()
+            return v if v is not None else default
+        try:
+            subnets = json.loads(_get(_K_SUBNETS, "[]")) or DISCOVERY_SUBNETS
+        except Exception:
+            subnets = DISCOVERY_SUBNETS
+        return {
+            "enabled": _get(_K_ENABLED, "1") == "1",   # 默认开启
+            "subnets": subnets,
+            "interval": int(_get(_K_INTERVAL, str(DISCOVERY_INTERVAL)) or DISCOVERY_INTERVAL),
+            "port": int(_get(_K_PORT, str(DISCOVERY_PORT)) or DISCOVERY_PORT),
+        }
+
+
+def save_settings(enabled=None, subnets=None, interval=None, port=None):
+    """写发现配置（部分字段更新）。subnets 逐项校验 CIDR，非法返回 (False, 原因)。"""
+    if subnets is not None:
+        clean = []
+        for s in subnets:
+            s = (s or "").strip()
+            if not s:
+                continue
+            try:
+                ipaddress.ip_network(s, strict=False)
+            except ValueError:
+                return False, f"网段格式错误: {s}"
+            clean.append(s)
+        subnets = clean
+    try:
+        if interval is not None and (int(interval) < 10 or int(interval) > 3600):
+            return False, "扫描周期需在 10-3600 秒之间"
+        if port is not None and (int(port) < 1 or int(port) > 65535):
+            return False, "端口不合法"
+    except (TypeError, ValueError):
+        return False, "参数不合法"
+    with _ctx():
+        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)})
+        if enabled is not None:
+            _put(_K_ENABLED, "1" if enabled else "0")
+        if subnets is not None:
+            _put(_K_SUBNETS, json.dumps(subnets))
+        if interval is not None:
+            _put(_K_INTERVAL, str(int(interval)))
+        if port is not None:
+            _put(_K_PORT, str(int(port)))
+        db.session.commit()
+    return True, "已保存"
+
+
+# ================== 网段展开与端口探测 ==================
+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
+    ips = []
+    for cidr in subnets:
+        try:
+            net = ipaddress.ip_network((cidr or "").strip(), strict=False)
+        except ValueError:
+            _log.warning(f"发现: 跳过非法网段 {cidr}")
+            continue
+        hosts = [str(h) for h in net.hosts()
+                 if str(h) not in self_ips]
+        if len(hosts) > max_hosts:
+            _log.warning(f"发现: 网段 {cidr} 主机数 {len(hosts)} 超过上限，截断前 {max_hosts}")
+            hosts = hosts[:max_hosts]
+        ips.extend(hosts)
+    return ips
+
+
+def _probe_port(ip, port, timeout=_PROBE_TIMEOUT):
+    """单 IP 端口探测（标准库 socket，超时/拒绝/不可达一律 False）。"""
+    try:
+        with socket.create_connection((ip, port), timeout=timeout):
+            return True
+    except Exception:
+        return False
+
+
+def _probe_open(ips, port, workers=_PROBE_WORKERS):
+    """并发探测，返回开放端口的主机列表。"""
+    if not ips:
+        return []
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        results = list(ex.map(lambda ip: (ip, _probe_port(ip, port)), ips))
+    return [ip for ip, ok in results if ok]
+
+
+# ================== adb devices 解析 ==================
+def _parse_adb_devices(out):
+    """解析 `adb devices` 输出 → state=="device" 的 serial 集合。
+
+    只看 connect 输出不可靠（未授权设备也返回 connected），必须用 state 过滤。
+    """
+    devices = set()
+    for line in (out or "").splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[0] and not parts[0].startswith("*"):
+            if parts[1] == "device":
+                devices.add(parts[0])
+    return devices
+
+
+# ================== 扫描 ==================
+def scan_once(manual=False):
+    """执行一轮扫描。返回 (ok, result_dict)；后台线程/API 调用。"""
+    global _scanning, _last_scan, _last_error
+    if not _scan_lock.acquire(blocking=False):
+        return False, {"error": "扫描进行中"}
+    _scanning = True
+    try:
+        settings = get_settings()
+        port = settings["port"]
+        subnets = settings["subnets"]
+        if not subnets:
+            _last_error = "未配置扫描网段"
+            return True, {"found": 0, "verified": 0, "new": 0, "error": _last_error}
+
+        # 1. socket 并发探测（不碰 adb，把几百台缩小到开放端口量级）
+        open_ips = _probe_open(_expand_subnets(subnets), port)
+        candidates = {f"{ip}:{port}" for ip in open_ips}
+
+        with _ctx():
+            # 2. 剔除已在正式设备池的 serial
+            configured = set(device_pool_list_configured())
+            candidates -= configured
+
+            # 3. 串行 adb 验证：已连接的直接跳过（零成本），其余 adb_connect_light
+            already = _parse_adb_devices(_adb("devices"))
+            for serial in candidates - already:
+                adb_connect_light(serial)  # 内部全局锁串行；失败无妨，下面按 state 过滤
+
+            # 4. state==device 过滤（排除 unauthorized/offline）
+            verified = _parse_adb_devices(_adb("devices")) & candidates
+
+            # 5. 写 pending：新 → 插入；已有 → 更新 last_seen
+            now = _fmt()
+            existing = {p.serial for p in PendingDevice.query.all()}
+            added = 0
+            for serial in verified:
+                source = "tailscale" if serial.split(":")[0].startswith("100.") else "lan"
+                if serial in existing:
+                    PendingDevice.query.filter_by(serial=serial).update(
+                        {"last_seen": now})
+                else:
+                    db.session.add(PendingDevice(serial=serial, source=source,
+                                                 first_seen=now, last_seen=now))
+                    added += 1
+            db.session.commit()
+            _log.info(f"发现: 探测开放 {len(open_ips)} 台，可连 {len(verified)} 台，"
+                      f"新增待连接 {added} 台")
+        _last_scan = (now, len(open_ips), len(verified), added)
+        _last_error = ""
+        return True, {"found": len(open_ips), "verified": len(verified), "new": added}
+    except Exception as e:
+        _log.warning(f"发现扫描异常: {e}")
+        _last_error = str(e)[:200]
+        return False, {"error": _last_error}
+    finally:
+        _scanning = False
+        _scan_lock.release()
+
+
+def device_pool_list_configured():
+    """设备池已配置 serial（延迟 import 避免循环依赖）。"""
+    from core import device_pool
+    return device_pool.list_configured()
+
+
+# ================== 定时扫描线程 ==================
+def _discovery_loop():
+    """定时扫描 daemon 线程。每轮重读配置（开关/周期即时生效）。
+
+    启动先 sleep 15s 避让 web_server 预连接线程（两者都抢 adb 全局锁）。
+    等待用 30s 切片（_stop_event.wait），关停/改周期 ≤30s 生效。
+    """
+    try:
+        _stop_event.wait(15)
+        while not _stop_event.is_set():
+            try:
+                settings = get_settings()
+                if settings["enabled"]:
+                    scan_once()
+            except Exception as e:
+                _log.warning(f"发现定时扫描异常: {e}")
+            wait_s = max(10, settings.get("interval", 60))
+            waited = 0
+            while waited < wait_s and not _stop_event.is_set():
+                _stop_event.wait(min(30, wait_s - waited))
+                waited += min(30, wait_s - waited)
+    except Exception:
+        pass
+
+
+def init_app(app):
+    """web_server 启动时调用：绑 app + 起定时扫描 daemon 线程。"""
+    global _app
+    _app = app
+    _stop_event.clear()
+    t = threading.Thread(target=_discovery_loop, name="device-discovery", daemon=True)
+    t.start()
+    _log.info("设备自动发现线程已启动（默认 60s 扫描一次）")
+
+
+def shutdown():
+    """优雅退出：置 stop_event，等待中的循环在切片边界退出。"""
+    _stop_event.set()
+
+
+# ================== 对外查询与确认 ==================
+def get_status():
+    """API 状态快照：配置 + 扫描状态 + 最近一轮结果 + 待连接数量。"""
+    settings = get_settings()
+    with _ctx():
+        pending = PendingDevice.query.count()
+    return {
+        "enabled": settings["enabled"],
+        "subnets": settings["subnets"],
+        "interval": settings["interval"],
+        "port": settings["port"],
+        "scanning": _scanning,
+        "last_scan": _last_scan[0] if _last_scan else "",
+        "last_result": ({"found": _last_scan[1], "verified": _last_scan[2],
+                         "new": _last_scan[3]} if _last_scan else None),
+        "last_error": _last_error,
+        "pending_count": pending,
+    }
+
+
+def list_pending():
+    """待连接列表：只返回当前在线的设备（离线候选不可确认，不展示）。
+
+    后端直接过滤（2026-09-04）：不依赖前端 JS 版本，任何客户端都拿不到
+    离线条目；设备恢复在线后扫描自动更新 last_seen 并重新出现在列表。
+    """
+    online = _parse_adb_devices(_adb("devices"))
+    with _ctx():
+        rows = [p.to_dict() for p in PendingDevice.query.order_by(
+            PendingDevice.first_seen.desc()).all()]
+    return [dict(r, online=True) for r in rows if r["serial"] in online]
+
+
+def confirm_pending(serial, name=""):
+    """确认连接：pending 行 → 正式设备池（add_device upsert）→ 删 pending。
+
+    返回 (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 "")
+        PendingDevice.query.filter_by(serial=serial).delete()
+        db.session.commit()
+    return True, "已加入设备池" + ("" if is_new else "（已存在，信息已更新）"), is_new
+
+
+def ignore_pending(serial):
+    """忽略：删除 pending 行（下轮扫描可能再次发现）。"""
+    with _ctx():
+        row = PendingDevice.query.get(serial)
+        if not row:
+            return False, "设备不在待连接列表"
+        PendingDevice.query.filter_by(serial=serial).delete()
+        db.session.commit()
+    return True, "已忽略"

core/device_pool.py

@@ -0,0 +1,213 @@
+"""设备池：SQLite devices 表 = 设备清单，本地 adb = 在线状态（STF 替代数据源）。
+
+设计：
+  - list_configured() — devices 表里 enabled 的设备（清单，管理页维护）
+  - list_online()     — 本机 `adb devices` 里 state=device 的设备（实时；
+                        池内有 USB 设备时合并 220 远程 adb server 状态）
+  - list_ready()      — configured ∩ online（任务调度用）
+  - CRUD              — add/update/remove/set_enabled（设备池管理页用）
+
+红线：全模块不 connect / 不 kill-server / 不 disconnect，遵守既有技术约束。
+后台线程（task_manager 等）调用时由本模块自行推 app context，调用方无需关心。
+"""
+import time
+import threading
+import subprocess
+
+from config import ADB_PATH, USB_ADB_HOST, USB_ADB_PORT
+from core.adb_helper import _adb, _adb_remote
+from core.logger import get_logger
+from core.models import db, Device
+
+_log = get_logger("core.device_pool")
+
+_app = None
+
+
+def init_app(app):
+    """web_server 启动时调用：绑定 Flask app（供后台线程推 db context），
+    并后台刷新一次设备型号（首次启动/设备更换后型号可能变化）。"""
+    global _app
+    _app = app
+    try:
+        t = threading.Thread(target=_refresh_models_bg, daemon=True)
+        t.start()
+    except Exception:
+        pass
+
+
+def _refresh_models_bg():
+    """后台批量采集在线设备型号（启动时/手动触发）。失败静默，不影响启动。"""
+    time.sleep(3)  # 等服务起来再查
+    try:
+        refresh_all_models()
+    except Exception as e:
+        _log.warning(f"启动型号采集失败（可稍后手动采集）: {e}")
+
+
+def _ctx():
+    """后台线程访问 db 需自行推 app context（与 task_manager._db 同思路）。"""
+    if _app is None:
+        raise RuntimeError("device_pool 未关联 Flask app（web_server 启动时调用 init_app）")
+    return _app.app_context()
+
+
+# ================== 清单 ==================
+def list_configured(enabled_only=True):
+    """devices 表里的设备清单（serial 列表）。"""
+    with _ctx():
+        q = Device.query
+        if enabled_only:
+            q = q.filter_by(enabled=True)
+        return [d.serial for d in q.order_by(Device.serial).all()]
+
+
+def list_devices():
+    """全量设备行（设备池管理页用）。"""
+    with _ctx():
+        return [d.to_dict() for d in Device.query.order_by(Device.serial).all()]
+
+
+# ================== 在线状态 ==================
+def list_online():
+    """本机 adb 中 state=device 的设备 + 池内 USB 设备（经 220 远程 adb server）。
+
+    池内无 USB 设备（serial 无冒号）时不查远程 server，零额外开销。
+    """
+    out = _adb("devices") or ""
+    serials = []
+    for line in out.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[0] and parts[1] == "device":
+            serials.append(parts[0])
+    # 池内有 USB 设备时，补查远程 adb server（220，host 网络 5037 全接口监听）
+    try:
+        usb = [s for s in list_configured() if ":" not in s]
+    except Exception:
+        usb = []
+    if usb:
+        try:
+            out = _adb_remote(USB_ADB_HOST, USB_ADB_PORT, "devices") or ""
+            for line in out.splitlines()[1:]:
+                parts = line.split()
+                if len(parts) >= 2 and parts[0] and parts[1] == "device":
+                    if parts[0] not in serials:
+                        serials.append(parts[0])
+        except Exception:
+            pass
+    return serials
+
+
+def is_online(serial):
+    """设备当前是否在线（本机 adb 可达且状态正常）。"""
+    return serial in list_online()
+
+
+def list_ready():
+    """可调度设备：清单 ∩ 在线（取代 STF list_free_devices）。"""
+    online = set(list_online())
+    return [s for s in list_configured() if s in online]
+
+
+# ================== 管理（CRUD） ==================
+def add_device(serial, name="", note="", enabled=True):
+    """添加/更新设备（upsert）。返回 True 新增 / False 已存在并更新。"""
+    serial = (serial or "").strip()
+    if not serial:
+        return False
+    with _ctx():
+        d = Device.query.get(serial)
+        if d:
+            d.name, d.note, d.enabled = name or "", note or "", enabled
+            db.session.commit()
+            return False
+        db.session.add(Device(serial=serial, name=name or "", note=note or "",
+                              enabled=enabled,
+                              created_at=time.strftime("%Y-%m-%d %H:%M")))
+        db.session.commit()
+        _log.info(f"设备池新增设备: {serial}")
+        return True
+
+
+def remove_device(serial):
+    """删除设备。返回是否删除成功。"""
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d:
+            return False
+        db.session.delete(d)
+        db.session.commit()
+        _log.info(f"设备池删除设备: {serial}")
+        return True
+
+
+def set_enabled(serial, enabled):
+    """启用/停用设备（停用后不参与调度）。返回是否成功。"""
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d:
+            return False
+        d.enabled = enabled
+        db.session.commit()
+        return True
+
+
+# ================== 型号采集 ==================
+def refresh_model(serial, timeout=8):
+    """采集单台设备型号（getprop ro.product.model）并写回 DB。
+
+    IP:5555 设备走本机 adb；USB 设备先查本机 adb，查不到再查 220 远程 adb server。
+    采集失败返回空串（静默，不影响主流程）。返回采集到的型号。
+    """
+    if not serial:
+        return ""
+    model = ""
+    if ":" in serial:
+        try:
+            r = subprocess.run([ADB_PATH, "-s", serial, "shell",
+                                "getprop", "ro.product.model"],
+                               capture_output=True, timeout=timeout)
+            model = (r.stdout or b"").decode("utf-8", errors="replace").strip()
+        except Exception:
+            model = ""
+    else:
+        # USB：先本机，再远程
+        try:
+            r = subprocess.run([ADB_PATH, "-s", serial, "shell",
+                                "getprop", "ro.product.model"],
+                               capture_output=True, timeout=timeout)
+            model = (r.stdout or b"").decode("utf-8", errors="replace").strip()
+        except Exception:
+            model = ""
+        if not model:
+            model = _adb_remote(USB_ADB_HOST, USB_ADB_PORT, "-s", serial,
+                                "shell", "getprop", "ro.product.model")
+    model = model.strip() or ""
+    if not model:
+        return ""
+    with _ctx():
+        d = Device.query.get(serial)
+        if d and d.model != model:
+            d.model = model
+            db.session.commit()
+            _log.info(f"设备池采集型号: {serial} -> {model}")
+    return model
+
+
+def refresh_all_models():
+    """批量采集池内在线设备的型号（并发 10，后台线程调用）。返回成功数。"""
+    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}
+        for fut in as_completed(futures):
+            try:
+                if fut.result():
+                    ok += 1
+            except Exception:
+                pass
+    _log.info(f"设备池批量采集型号完成: {ok}/{len(serials)} 台")
+    return ok

core/device_worker.py

@@ -1,9 +1,9 @@
 """设备生命周期 + 通用 Worker 基类 + 全局状态注册表 + 心跳看门狗。
 
-  STFDevice    — 单设备生命周期：acquire（占用+adb连接）→ release（断开+释放）
+  STFDevice    — 单设备生命周期：acquire（直连/远程 server）→ release
-  BaseWorker   — 通用 worker 基类：封装 STF 生命周期 + u2 连接 + 状态上报 + stop
+  BaseWorker   — 通用 worker 基类：封装设备生命周期 + u2 连接 + 状态上报 + stop
                  + 生命周期钩子(setup/teardown/on_error) + 心跳上报
-                 子类只需实现 run_task(d)，可选实现钩子，不用管 STF/adb/状态/异常
+                 子类只需实现 run_task(d)，可选实现钩子，不用管 adb/状态/异常
   _WORKERS     — 全局状态注册表，供 web_server 读取实时状态
   _watchdog    — 心跳看门狗线程，检测 worker 卡死
 
@@ -16,12 +16,25 @@ from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeou
 
 import uiautomator2 as u2
 
+from config import USB_ADB_HOST, USB_ADB_PORT
 from core.logger import get_logger
-from core.stf_client import DeviceOfflineError, STFError
+from core import device_pool
-from .adb_helper import adb_connect, adb_disconnect
+from .adb_helper import _adb, adb_connect, _adb_remote
 
 _log = get_logger("core.worker")
 
+
+class STFError(Exception):
+    """设备操作错误（历史名称保留兼容）。code: offline/conflict/..."""
+
+    def __init__(self, message, code=""):
+        super().__init__(message)
+        self.code = code
+
+
+class DeviceOfflineError(STFError):
+    """设备离线/不可用：任务不重试（换设备也没用）。"""
+
 # 心跳超时阈值（秒）。worker 超过这个时间没更新心跳，判定为卡死
 _HEARTBEAT_TIMEOUT = 120
 # 看门狗检查间隔
@@ -32,61 +45,58 @@ _U2_INFO_TIMEOUT = 10
 
 
 class STFDevice:
-    """单设备生命周期：acquire（占用+连接）→ release（断开+释放）。
+    """单设备生命周期：acquire（直连）→ release（无操作）。
 
-    用 try/finally 保证设备一定被释放，即使养号中途报错。
+    阶段 2：已摘除 STF occupy/release 与 remoteConnect 桥接——
+    单实例互斥由 TaskManager._running 保证；非 IP:port（USB 序列号）设备
+    通过 220 的远程 adb server（-H/-P）驱动，不再依赖 STF。
     """
 
-    def __init__(self, stf_client, serial=None):
+    def __init__(self, serial=None):
-        self.stf = stf_client
         self.serial = serial
-        self.remote_adb_url = None
+        self.remote_adb_url = None      # IP:5555 设备：设备地址
+        self.usb_server = None          # USB 设备：远程 adb server 地址（host:port）
 
     def acquire(self, serial=None):
         self.serial = serial or self.serial or self._pick_free()
         _log.info(f"[{self.serial}] 选定设备")
 
-        ok, msg = self.stf.occupy(self.serial)
+        # 直连优先：serial 本身是 IP:5555（如 Tailscale 网络设备）时直接 adb connect。
-        if not ok:
+        # 只 connect、绝不 disconnect/kill-server（红线），不影响共享 adb transport。
-            raise STFError(f"占用设备失败: {msg}", "conflict")
-        _log.info(f"[{self.serial}] STF 占用成功")
-
-        # 优先直连设备 serial（当 serial 本身就是 IP:5555 时，如 Tailscale 网络）
-        # 这比 STF remoteConnect 桥接更稳定，避免桥接地址认证失败
         if ":" in self.serial:
             self.remote_adb_url = self.serial
             _log.info(f"[{self.serial}] 直连设备: {self.remote_adb_url}")
-        else:
-            # serial 不是 IP:port 格式，走 STF remoteConnect 桥接
-            self.remote_adb_url = self.stf.remote_connect(self.serial)
-            _log.info(f"[{self.serial}] STF 桥接: {self.remote_adb_url}")
-
             if not adb_connect(self.remote_adb_url):
                 raise STFError(f"adb connect 失败: {self.remote_adb_url}", "offline")
+        else:
+            # USB 设备（serial 无冒号）：优先本机 adb（插在平台本机），
+            # 其次 220 远程 adb server（插在 220 上，经 Tailscale 驱动）。
+            # 两者都不需要 adb connect——设备已连接在对应 server 上，只做可见性校验。
+            local = {line.split()[0] for line in (_adb("devices") or "").splitlines()[1:]
+                     if len(line.split()) >= 2}
+            if self.serial in local:
+                self.remote_adb_url = self.serial  # u2 走本地 adb（无需 connect）
+                _log.info(f"[{self.serial}] USB 设备，本机 adb 直连")
+            else:
+                self.usb_server = f"{USB_ADB_HOST}:{USB_ADB_PORT}"
+                _log.info(f"[{self.serial}] USB 设备，远程 adb server: {self.usb_server}")
+                out = _adb_remote(USB_ADB_HOST, USB_ADB_PORT, "devices") or ""
+                seen = {line.split()[0] for line in out.splitlines()[1:]
+                        if len(line.split()) >= 2}
+                if self.serial not in seen:
+                    raise STFError(
+                        f"USB 设备 {self.serial} 不在本机 adb 也不在远程 adb server", "offline")
         time.sleep(2)
 
     def _pick_free(self):
-        free = self.stf.list_free_devices()
+        free = device_pool.list_ready()
         if not free:
             raise STFError("没有可用的在线空闲设备", "offline")
-        return free[0]["serial"]
+        return free[0]
 
     def release(self):
-        if not self.serial:
+        # 直连模式：不 disconnect（红线，STF 共享 transport）；USB：无连接可断
-            return
-        # 直连模式（remote_adb_url == serial）：不 disconnect
-        # STF agent 可能共享同一个 adb 连接，disconnect 会导致 STF 设备离线后重新连接
-        if self.remote_adb_url and self.remote_adb_url != self.serial:
-            adb_disconnect(self.remote_adb_url)
-            try:
-                self.stf.remote_disconnect(self.serial)
-            except Exception:
         pass
-        try:
-            self.stf.release(self.serial)
-            _log.info(f"[{self.serial}] 已释放")
-        except Exception as e:
-            _log.warning(f"[{self.serial}] 释放失败: {e}")
 
 
 # ================== 全局 worker 状态注册表（供 web_server 读取） ==================
@@ -111,6 +121,36 @@ def _remove_worker(serial):
         _WORKERS.pop(serial, None)
 
 
+def clear_worker_error(serial):
+    """清除设备错误/失败状态，恢复为 idle。运行中/连接中返回 False 不清理。
+
+    检查与更新在同一把锁内完成，避免与任务启动写 connecting/running 的竞态。
+    """
+    with _WORKERS_LOCK:
+        w = _WORKERS.get(serial)
+        if w is None:
+            return True  # 本就没有状态记录，视作已清理
+        if w.get("status") in ("running", "connecting"):
+            return False
+        w.update(status="idle", last_error="", last_warning="", task_job="",
+                 current_action="", attempt=0, progress={}, end_time=0,
+                 last_heartbeat=time.time())
+    return True
+
+
+def clear_all_worker_errors(exclude=()):
+    """批量清除所有 error/failed 状态（exclude 里的跳过）。返回清除数。"""
+    exclude = set(exclude)
+    with _WORKERS_LOCK:
+        targets = [s for s, w in _WORKERS.items()
+                   if s not in exclude and w.get("status") in ("error", "failed")]
+    cleared = 0
+    for s in targets:
+        if clear_worker_error(s):
+            cleared += 1
+    return cleared
+
+
 def get_worker_heartbeat(serial):
     """返回 worker 最近一次心跳时间，没有返回 0。"""
     with _WORKERS_LOCK:
@@ -180,11 +220,11 @@ def stop_watchdog():
 class BaseWorker(threading.Thread):
     """通用 worker 基类。
 
-    自动处理：STF 占用/释放、u2 连接、状态上报、异常捕获、stop 信号、心跳。
+    自动处理：设备获取、u2 连接、状态上报、异常捕获、stop 信号、心跳。
     子类只需实现 run_task(d) 方法，专注业务逻辑。
 
     生命周期（基类 run() 已封装，不要重写）：
-      1. acquire 设备（STF 占用 + adb 连接）
+      1. acquire 设备（直连 IP:5555 / USB 走远程 adb server）
       2. u2.connect 拿到 d
       3. 调用 setup(d)        ← 子类可选钩子，做初始化
       4. 调用子类 run_task(d)  ← 业务逻辑
@@ -225,9 +265,8 @@ class BaseWorker(threading.Thread):
       其他异常           — 可重试
     """
 
-    def __init__(self, stf_client, serial, params=None, daemon=True):
+    def __init__(self, serial, params=None, daemon=True):
         super().__init__(daemon=daemon)
-        self.stf = stf_client
         self.serial = serial
         self.params = params or {}
         self._stop_flag = threading.Event()
@@ -242,6 +281,9 @@ class BaseWorker(threading.Thread):
     def _start_timer(self):
         """子类在 run_task 开头调用，启动运行时长计时。"""
         self._start_time = time.time()
+        if self.max_duration > 0:
+            # 预计结束时间（前端监控页展示），到点自动停止
+            _update_status(self.serial, end_time=self._start_time + self.max_duration)
 
     def is_time_up(self):
         """是否已达最大运行时长。max_duration=0 时永远返回 False。"""
@@ -322,14 +364,19 @@ class BaseWorker(threading.Thread):
     # ================== 基类主循环（不要重写） ==================
     def run(self):
         """基类主循环：不要重写。子类实现 run_task + 可选钩子。"""
-        device = STFDevice(self.stf, serial=self.serial)
+        device = STFDevice(serial=self.serial)
-        _update_status(self.serial, status="connecting", stf_occupied=False,
+        _update_status(self.serial, status="connecting",
-                       last_error="", remote_adb_url="", model="",
+                       last_error="", remote_adb_url="", usb_server="", model="",
                        current_action="")
         try:
             device.acquire()
             remote = device.remote_adb_url
-            # u2.connect 可能 hang 住（atx-agent 无响应），用线程池+超时保护
+            usb_server = device.usb_server
+            # u2.connect 可能 hang 住（atx-agent 无响应），用线程池+超时保护；
+            # USB 设备（无 IP:5555）经远程 adb server 建 u2 连接
+            if usb_server:
+                self.d = self._u2_connect_usb_with_timeout(usb_server)
+            else:
                 self.d = self._u2_connect_with_timeout(remote)
             if self.d is None:
                 raise STFError(f"u2.connect 超时 {_U2_CONNECT_TIMEOUT}s，atx-agent 无响应", "offline")
@@ -341,8 +388,9 @@ class BaseWorker(threading.Thread):
                     model = info.get("productName") or ""
             except Exception:
                 pass
-            _update_status(self.serial, status="running", stf_occupied=True,
+            _update_status(self.serial, status="running",
-                           remote_adb_url=remote, model=model)
+                           remote_adb_url=remote or "", usb_server=usb_server or "",
+                           model=model)
 
             # setup 钩子
             try:
@@ -395,9 +443,9 @@ class BaseWorker(threading.Thread):
             with _WORKERS_LOCK:
                 cur = _WORKERS.get(self.serial, {}).get("status")
             if cur in ("running", "connecting"):
-                _update_status(self.serial, stf_occupied=False, status="released")
+                _update_status(self.serial, status="released")
             else:
-                _update_status(self.serial, stf_occupied=False)
+                pass
 
     def _u2_connect_with_timeout(self, remote):
         """u2.connect 带超时保护，避免 atx-agent 无响应时永久 hang。"""
@@ -408,6 +456,28 @@ class BaseWorker(threading.Thread):
             except FuturesTimeout:
                 _log.error(f"[{self.serial}] u2.connect 超时 {_U2_CONNECT_TIMEOUT}s")
                 return None
+
+    def _u2_connect_usb_with_timeout(self, server):
+        """USB 设备：经远程 adb server（220）建 u2 连接，带超时保护。
+
+        u2 3.7 底层 adbutils 支持远程 adb server：AdbClient(host, port).device(serial)，
+        再交给 u2.connect(AdbDevice)（与本地连接同语义，无需 adb connect）。
+        """
+        host, _, port = server.partition(":")
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            def _connect():
+                from adbutils import AdbClient
+                dev = AdbClient(host=host, port=int(port)).device(self.serial)
+                return u2.connect(dev)
+            fut = pool.submit(_connect)
+            try:
+                return fut.result(timeout=_U2_CONNECT_TIMEOUT)
+            except FuturesTimeout:
+                _log.error(f"[{self.serial}] u2 远程连接超时 {_U2_CONNECT_TIMEOUT}s")
+                return None
+            except Exception as e:
+                _log.error(f"[{self.serial}] u2 远程连接失败: {e}")
+                return None
             except Exception as e:
                 _log.error(f"[{self.serial}] u2.connect 异常: {e}")
                 return None

core/models.py

@@ -20,6 +20,9 @@ import hashlib
 
 from flask_sqlalchemy import SQLAlchemy
 from flask_login import UserMixin
+from sqlalchemy import event, text
+from sqlalchemy.engine import Engine
+from werkzeug.security import generate_password_hash, check_password_hash
 
 from core.logger import get_logger
 
@@ -28,18 +31,67 @@ _log = get_logger("core.models")
 db = SQLAlchemy()
 
 
+@event.listens_for(Engine, "connect")
+def _sqlite_pragma(dbapi_connection, connection_record):
+    """SQLite 并发写优化：WAL 模式 + 忙等待超时 + 降同步级别。
+
+    多 worker 后台线程同时写库（任务参数/分组）时，避免 database is locked。
+    """
+    cursor = dbapi_connection.cursor()
+    cursor.execute("PRAGMA journal_mode=WAL")
+    cursor.execute("PRAGMA busy_timeout=5000")
+    cursor.execute("PRAGMA synchronous=NORMAL")
+    cursor.close()
+
+
 class User(UserMixin, db.Model):
-    """后台用户。"""
+    """后台用户。
+
+    权限模型：
+      - is_admin=True：管理员，拥有全部权限，不受 perms 限制
+      - is_admin=False：按 perms 授权（JSON 数组，如 ["tasks","devices"]）
+      - 权限位：tasks=任务管理, devices=设备控制, apks=应用管理, logs=日志查看
+      - 用户管理本身只有管理员能做（web_server 层强制），不设普通权限位
+    """
     id = db.Column(db.Integer, primary_key=True)
     username = db.Column(db.String(80), unique=True, nullable=False)
-    password_hash = db.Column(db.String(120), nullable=False)
+    password_hash = db.Column(db.String(255), nullable=False)
     is_admin = db.Column(db.Boolean, default=True)
+    perms = db.Column(db.Text, default="[]")          # JSON 数组：业务权限位
+
+    def get_perms(self):
+        try:
+            return json.loads(self.perms or "[]")
+        except Exception:
+            return []
+
+    def set_perms(self, lst):
+        """设置权限位。管理员强制为全部权限（内部不区分）。"""
+        self.perms = json.dumps(list(lst or []), ensure_ascii=False)
+
+    def has_perm(self, perm):
+        """是否拥有指定权限。管理员恒为 True。"""
+        if self.is_admin:
+            return True
+        return perm in self.get_perms()
 
     def set_password(self, password):
-        self.password_hash = hashlib.sha256(password.encode()).hexdigest()
+        self.password_hash = generate_password_hash(password)
 
     def check_password(self, password):
-        return self.password_hash == hashlib.sha256(password.encode()).hexdigest()
+        """校验密码。兼容旧 SHA-256 哈希（匹配则自动升级为新哈希）。"""
+        ph = self.password_hash or ""
+        if ph and not ph.startswith(("pbkdf2:", "scrypt:")):
+            # 旧版裸 SHA-256：比对通过则升级为加盐哈希
+            if hashlib.sha256(password.encode()).hexdigest() == ph:
+                self.set_password(password)
+                try:
+                    db.session.commit()
+                except Exception:
+                    pass
+                return True
+            return False
+        return check_password_hash(ph, password)
 
     def __repr__(self):
         return f"<User {self.username}>"
@@ -111,6 +163,35 @@ class TaskJob(db.Model):
         return f"<TaskJob {self.name}>"
 
 
+class CustomAction(db.Model):
+    """自定义动作（把一系列步骤打包成一个可复用的动作）。
+
+    steps 字段存 JSON 数组，格式同 generic_steps 的 step schema。
+    前端拖拽到画布时，展开为 group 步骤（type='group'）。
+    """
+    id = db.Column(db.String(32), primary_key=True)
+    name = db.Column(db.String(120), nullable=False)
+    icon = db.Column(db.String(4), default="📦")
+    steps = db.Column(db.Text, default="[]")    # JSON 数组
+    created_at = db.Column(db.String(20), default="")
+
+    def get_steps(self):
+        try:
+            return json.loads(self.steps or "[]")
+        except Exception:
+            return []
+
+    def set_steps(self, v):
+        self.steps = json.dumps(v or [], ensure_ascii=False)
+
+    def to_dict(self):
+        return {"id": self.id, "name": self.name, "icon": self.icon or "📦",
+                "steps": self.get_steps(), "created_at": self.created_at or ""}
+
+    def __repr__(self):
+        return f"<CustomAction {self.name}>"
+
+
 class ApkFile(db.Model):
     """上传的 APK 文件元信息（应用管理功能）。"""
     id = db.Column(db.String(32), primary_key=True)   # uuid 前 8 位
@@ -135,6 +216,66 @@ class ApkFile(db.Model):
         return f"<ApkFile {self.display_name}>"
 
 
+class Device(db.Model):
+    """设备池（本地设备清单，替代 STF 池作为调度数据源）。
+
+    serial 即 adb 序列号（IP:5555 或 USB 序列号）；enabled=False 不参与调度。
+    model 为在线时自动采集的型号（如 Redmi 12C），供管理页/监控页区分设备。
+    """
+    serial = db.Column(db.String(120), primary_key=True)
+    name = db.Column(db.String(80), default="")       # 备注名（可选）
+    model = db.Column(db.String(120), default="")     # 型号（自动采集）
+    enabled = db.Column(db.Boolean, default=True)     # 是否参与调度
+    note = db.Column(db.Text, default="")             # 备注
+    created_at = db.Column(db.String(20), default="") # 添加时间
+
+    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 ""}
+
+    def __repr__(self):
+        return f"<Device {self.serial}>"
+
+
+class PendingDevice(db.Model):
+    """自动发现待连接池：扫描验证通过的设备，等待用户确认后才入正式池。
+
+    与 Device 表的区别：只代表"被扫描到、可连接"，不参与任务调度。
+    """
+    serial = db.Column(db.String(120), primary_key=True)   # 如 192.168.20.5:5555
+    source = db.Column(db.String(20), default="")          # lan / tailscale
+    first_seen = db.Column(db.String(20), default="")      # 首次发现时间
+    last_seen = db.Column(db.String(20), default="")       # 最近一次扫描仍可见的时间
+
+    def to_dict(self):
+        return {"serial": self.serial, "source": self.source or "",
+                "first_seen": self.first_seen or "", "last_seen": self.last_seen or ""}
+
+
+# 版本化 schema 迁移：新增结构变更时在此追加 (版本号, 说明, SQL)
+# 版本号单调递增，只执行比当前 schema_version 新的迁移。
+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 '')"),
+]
+
+
 def init_db(app):
     """在 Flask app context 里初始化数据库 + 创建默认管理员。
 
@@ -143,10 +284,37 @@ def init_db(app):
     db.init_app(app)
     with app.app_context():
         db.create_all()
+        _migrate_schema()
         _ensure_default_admin()
         _migrate_old_json()
 
 
+def _migrate_schema():
+    """按 SCHEMA_MIGRATIONS 顺序执行版本化迁移，记录当前 schema_version。
+
+    create_all 只负责首次建表；结构变更必须走迁移，避免改了模型后老库对不上。
+    """
+    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:
+            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}")
+    except Exception as e:
+        _log.error(f"schema 迁移失败（不阻塞启动）: {e}")
+
+
 def _ensure_default_admin():
     """首次启动创建默认管理员 admin/admin123。"""
     if not User.query.filter_by(username="admin").first():

core/ocr.py

@@ -0,0 +1,79 @@
+"""屏幕 OCR 识别（RapidOCR，ONNX 推理，跨平台：Windows/Linux/macOS）。
+
+用于"条件判断"步骤的 ocr 选择器：截屏 → 识别文字 → 按关键词匹配 → 可点击。
+UI 树里找不到的文字（图片、画布、WebView 渲染的文字）也能识别。
+
+依赖 rapidocr_onnxruntime（中英文模型随包内置，无需下载/联网）：
+  pip install rapidocr_onnxruntime
+服务器（无显示器）环境建议把 opencv-python 换成 opencv-python-headless。
+
+坐标约定：返回 box 为像素坐标（原点左上），与 u2 的 d.click 一致。
+"""
+import threading
+
+import numpy as np
+
+from core.logger import get_logger
+
+_log = get_logger("core.ocr")
+
+_engine = None
+_engine_lock = threading.Lock()
+
+
+def _get_engine():
+    global _engine
+    with _engine_lock:
+        if _engine is None:
+            from rapidocr_onnxruntime import RapidOCR
+            _log.info("初始化 RapidOCR 引擎（首次约 1-2 秒加载模型）")
+            _engine = RapidOCR()
+    return _engine
+
+
+def available():
+    """OCR 是否可用。返回 (ok, hint)。"""
+    try:
+        _get_engine()
+        return True, ""
+    except Exception as e:
+        return False, f"OCR 不可用（需 pip install rapidocr_onnxruntime）: {e}"
+
+
+def recognize(image):
+    """识别 PIL Image 上的文字。
+
+    返回 [{text, score, box}]，box=[x1,y1,x2,y2] 像素坐标（原点左上，与 u2 一致）。
+    """
+    engine = _get_engine()
+    # PIL(RGB) → ndarray(BGR)，与 OpenCV 约定一致
+    arr = np.array(image.convert("RGB"))[:, :, ::-1]
+    results = []
+    try:
+        # 引擎实例并发调用加锁保护（识别本身约 0.2-0.5s，锁开销可忽略）
+        with _engine_lock:
+            result, _ = engine(arr)
+    except Exception as e:
+        _log.warning(f"OCR 识别异常: {e}")
+        return results
+    for item in result or []:
+        box4, text, score = item
+        xs = [p[0] for p in box4]
+        ys = [p[1] for p in box4]
+        results.append({"text": text, "score": float(score),
+                        "box": [round(min(xs)), round(min(ys)),
+                                round(max(xs)), round(max(ys))]})
+    return results
+
+
+def find_on_screen(image, keyword):
+    """在截图上查找包含 keyword 的文字。
+
+    返回 (found, center_xy, matched_text)；center_xy 为文字中心像素坐标（可点击），
+    未命中返回 (False, None, "")。
+    """
+    for r in recognize(image):
+        if keyword in r["text"]:
+            b = r["box"]
+            return True, ((b[0] + b[2]) // 2, (b[1] + b[3]) // 2), r["text"]
+    return False, None, ""

core/ssh_client.py

@@ -0,0 +1,100 @@
+"""SSH 远程命令执行统一封装（STF 重启 / STF 设备管理共用）。
+
+认证方式二选一：
+  1. `.env` 配置 STF_SSH_PASSWORD → 密码认证（paramiko 实现，跨平台，
+     无需 sshpass/ssh 等外部工具，Windows/Linux/macOS 通吃）
+  2. 未配置 → 退回系统 `ssh` 命令 + BatchMode=yes（免密密钥，与旧行为一致）
+
+用法：
+  code, out, err = ssh_client.run("docker ps")     # 返回 (退出码, stdout, stderr)
+  失败抛 SSHError（连接失败/超时），由调用方转成友好错误返回。
+"""
+import re
+import socket
+import subprocess
+
+import paramiko
+
+from config import STF_SSH_TARGET, STF_SSH_PASSWORD
+from core.logger import get_logger
+
+_log = get_logger("core.ssh")
+
+
+class SSHError(Exception):
+    """SSH 执行错误（连接失败/超时等）。"""
+
+
+def _parse_target(target):
+    """解析 STF_SSH_TARGET（user@host[:port] 或 host）→ (user, host, port)。"""
+    target = (target or "").strip()
+    user, host, port = "root", target, 22
+    m = re.match(r"^([^@]+)@(.+)$", target)
+    if m:
+        user, host = m.group(1), m.group(2)
+    if ":" in host:
+        host, p = host.rsplit(":", 1)
+        try:
+            port = int(p)
+        except ValueError:
+            pass
+    return user, host, port
+
+
+def uses_password():
+    """当前是否走密码认证。"""
+    return bool(STF_SSH_PASSWORD)
+
+
+def run(cmd, timeout=25):
+    """在部署机上执行一条命令。返回 (code, stdout, stderr)。"""
+    if uses_password():
+        return _run_paramiko(cmd, timeout)
+    return _run_system_ssh(cmd, timeout)
+
+
+def _run_system_ssh(cmd, timeout):
+    """免密密钥路径：系统 ssh + BatchMode=yes（不弹密码提示）。"""
+    ssh = ["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=5",
+           "-o", "StrictHostKeyChecking=no", STF_SSH_TARGET]
+    try:
+        r = subprocess.run(ssh + [cmd], capture_output=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        raise SSHError(f"SSH 执行超时: {cmd[:80]}")
+    except FileNotFoundError:
+        raise SSHError("本机未安装 ssh，无法远程执行")
+    except Exception as e:
+        raise SSHError(f"SSH 连接失败: {e}")
+    return r.returncode, (r.stdout or b"").decode("utf-8", errors="replace"), \
+        (r.stderr or b"").decode("utf-8", errors="replace")
+
+
+def _run_paramiko(cmd, timeout):
+    """密码路径：paramiko SSHClient，**纯密码认证**。
+
+    look_for_keys=False + allow_agent=False：不尝试本地密钥、不询问 SSH agent
+    （如 Bitwarden），否则 agent 会弹授权框/用密钥绕过密码。
+    """
+    user, host, port = _parse_target(STF_SSH_TARGET)
+    client = paramiko.SSHClient()
+    client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+    try:
+        client.connect(host, port=port, username=user, password=STF_SSH_PASSWORD,
+                       timeout=8, banner_timeout=8, auth_timeout=8,
+                       look_for_keys=False, allow_agent=False)
+        try:
+            stdin, stdout, stderr = client.exec_command(cmd, timeout=timeout)
+            out = stdout.read().decode("utf-8", errors="replace")
+            err = stderr.read().decode("utf-8", errors="replace")
+            code = stdout.channel.recv_exit_status()
+            return code, out, err
+        finally:
+            client.close()
+    except paramiko.AuthenticationException:
+        raise SSHError(f"SSH 密码认证失败（请检查 .env 的 STF_SSH_PASSWORD）")
+    except socket.timeout:
+        raise SSHError(f"SSH 执行超时（{timeout}s 内未完成，命令可能耗时较长）")
+    except paramiko.SSHException as e:
+        raise SSHError(f"SSH 连接失败: {e}")
+    except Exception as e:
+        raise SSHError(f"SSH 连接失败: {e}")

core/stf_client.py

@@ -1,210 +0,0 @@
-"""OpenSTF REST API 客户端封装。
-
-负责：设备列表查询、占用、远程 ADB 隧道建立、释放。
-不负责实际 UI 操作（那是 DeviceWorker 的事）。
-
-健壮性设计：
-  - 所有请求带 timeout，避免 STF 网关 504 时长时间卡死
-  - remoteConnect 带重试，STF provider 偶尔慢启动
-  - 友好错误分类：设备离线 / 网络不通 / STF 内部错误，便于上层决策
-  - 占用冲突自动重试（STF 偶发 400 "device already in use"）
-"""
-import time
-
-import requests
-
-from config import STF_URL, STF_TOKEN
-from core.logger import get_logger
-
-_log = get_logger("core.stf")
-
-# 请求超时（秒）。connect 超时 + read 超时
-_TIMEOUT = (5, 15)
-# remoteConnect 重试次数（STF provider 慢启动时需要重试）
-_RC_RETRIES = 3
-# remoteConnect 重试间隔
-_RC_DELAY = 2
-
-
-class STFError(Exception):
-    """STF 相关错误基类。"""
-
-    def __init__(self, message, code=""):
-        super().__init__(message)
-        self.code = code  # 错误码：offline / network / conflict / server / unknown
-
-
-class DeviceOfflineError(STFError):
-    """设备离线/不可用。"""
-
-
-class STFNetworkError(STFError):
-    """STF 服务不可达。"""
-
-
-class DeviceConflictError(STFError):
-    """设备已被占用。"""
-
-
-def _headers():
-    return {"Authorization": f"Bearer {STF_TOKEN}"}
-
-
-class STFClient:
-    """OpenSTF REST API 封装。"""
-
-    def __init__(self, base_url=STF_URL, token=STF_TOKEN):
-        self.base_url = base_url
-        self.headers = _headers()
-
-    # ================== 设备查询 ==================
-    def list_all_devices(self):
-        """返回 STF 上所有设备（含状态）。"""
-        try:
-            resp = requests.get(f"{self.base_url}/api/v1/devices",
-                                headers=self.headers, timeout=_TIMEOUT)
-            resp.raise_for_status()
-            return resp.json().get("devices", [])
-        except requests.exceptions.ConnectionError as e:
-            raise STFNetworkError(f"STF 服务不可达: {e}", "network") from e
-        except requests.exceptions.Timeout as e:
-            raise STFNetworkError(f"STF 请求超时: {e}", "network") from e
-        except requests.exceptions.RequestException as e:
-            _log.error(f"获取设备列表失败: {e}")
-            raise STFError(f"获取设备列表失败: {e}", "server") from e
-
-    def list_free_devices(self):
-        """返回可占用的空闲设备。"""
-        return [d for d in self.list_all_devices()
-                if d.get("present") and d.get("ready")
-                and not d.get("using") and d.get("owner") is None]
-
-    def list_my_devices(self):
-        """返回当前账户已占用的设备。"""
-        try:
-            resp = requests.get(f"{self.base_url}/api/v1/user/devices",
-                                headers=self.headers, timeout=_TIMEOUT)
-            resp.raise_for_status()
-            return resp.json().get("devices", [])
-        except requests.exceptions.RequestException as e:
-            _log.error(f"获取已占用设备失败: {e}")
-            return []
-
-    # ================== 占用/释放 ==================
-    def occupy(self, serial, retries=2):
-        """占用设备。返回 (ok, msg)。
-
-        冲突（已被占用）时自动重试，偶发 400 "already in use" 可能是脏状态。
-        """
-        for attempt in range(1, retries + 1):
-            try:
-                r = requests.post(f"{self.base_url}/api/v1/user/devices/{serial}",
-                                  headers=self.headers, timeout=_TIMEOUT)
-                if r.status_code in (200, 201):
-                    return True, r.text[:200]
-                if r.status_code == 400 and "already" in r.text.lower():
-                    # 已被占用（可能是自己之前占用没释放干净），尝试先释放再占
-                    _log.warning(f"{serial} 占用冲突，尝试清理后重试 ({attempt}/{retries})")
-                    try:
-                        requests.delete(f"{self.base_url}/api/v1/user/devices/{serial}",
-                                        headers=self.headers, timeout=_TIMEOUT)
-                    except Exception:
-                        pass
-                    time.sleep(1)
-                    continue
-                return False, f"HTTP {r.status_code}: {r.text[:200]}"
-            except requests.exceptions.RequestException as e:
-                _log.warning(f"{serial} 占用请求异常 ({attempt}/{retries}): {e}")
-                if attempt < retries:
-                    time.sleep(1)
-                return False, str(e)
-        return False, "占用冲突重试耗尽"
-
-    def release(self, serial):
-        """释放设备占用（含远程断开）。"""
-        self.remote_disconnect(serial)
-        try:
-            requests.delete(f"{self.base_url}/api/v1/user/devices/{serial}",
-                            headers=self.headers, timeout=_TIMEOUT)
-        except requests.exceptions.RequestException as e:
-            _log.warning(f"释放 {serial} 请求失败: {e}")
-
-    def release_all_mine(self):
-        """释放当前账户占用的所有设备（清理用）。"""
-        released = []
-        for d in self.list_my_devices():
-            serial = d["serial"]
-            try:
-                self.release(serial)
-                released.append(serial)
-                _log.info(f"已释放 {serial}")
-            except Exception as e:
-                _log.error(f"释放 {serial} 失败: {e}")
-        return released
-
-    # ================== 远程 ADB 隧道 ==================
-    def remote_connect(self, serial):
-        """建立远程 ADB 隧道，返回 remoteConnectUrl。
-
-        STF provider 慢启动或设备掉线时会 504，这里带重试。
-        设备真离线时快速失败，不长时间卡住 worker。
-        """
-        last_err = None
-        for attempt in range(1, _RC_RETRIES + 1):
-            try:
-                conn = requests.post(
-                    f"{self.base_url}/api/v1/user/devices/{serial}/remoteConnect",
-                    headers=self.headers, timeout=_TIMEOUT,
-                )
-                # 504 = STF 网关等 provider 响应超时，通常是设备掉线或 provider 卡死
-                if conn.status_code == 504:
-                    last_err = f"STF 网关超时(504)，设备可能掉线"
-                    _log.warning(f"{serial} remoteConnect 504 ({attempt}/{_RC_RETRIES})")
-                    if attempt < _RC_RETRIES:
-                        time.sleep(_RC_DELAY)
-                        continue
-                    raise DeviceOfflineError(
-                        f"{serial} remoteConnect 超时，设备可能掉线或 provider 卡死",
-                        "offline",
-                    )
-                conn.raise_for_status()
-                data = conn.json()
-                if not data.get("success"):
-                    raise STFError(f"远程连接失败: {data.get('description')}", "server")
-                url = (data.get("remoteConnectUrl") or data.get("remoteAdbUrl")
-                       or data.get("remote_adb_url") or data.get("adbUrl")
-                       or data.get("url"))
-                if not url:
-                    raise STFError("STF 返回成功但无 remoteConnectUrl", "server")
-                return url
-            except DeviceOfflineError:
-                raise
-            except requests.exceptions.ConnectionError as e:
-                last_err = str(e)
-                _log.warning(f"{serial} remoteConnect 网络异常 ({attempt}/{_RC_RETRIES}): {e}")
-                if attempt < _RC_RETRIES:
-                    time.sleep(_RC_DELAY)
-            except requests.exceptions.Timeout as e:
-                last_err = str(e)
-                _log.warning(f"{serial} remoteConnect 超时 ({attempt}/{_RC_RETRIES}): {e}")
-                if attempt < _RC_RETRIES:
-                    time.sleep(_RC_DELAY)
-            except requests.exceptions.RequestException as e:
-                last_err = str(e)
-                _log.error(f"{serial} remoteConnect 请求异常: {e}")
-                raise STFError(f"远程连接请求失败: {e}", "server") from e
-        # 重试耗尽
-        raise DeviceOfflineError(
-            f"{serial} remoteConnect 重试 {_RC_RETRIES} 次失败: {last_err}",
-            "offline",
-        )
-
-    def remote_disconnect(self, serial):
-        """断开远程 ADB 隧道。"""
-        try:
-            requests.post(
-                f"{self.base_url}/api/v1/user/devices/{serial}/remoteDisconnect",
-                headers=self.headers, timeout=_TIMEOUT,
-            )
-        except requests.exceptions.RequestException:
-            pass  # 断开失败不影响主流程

core/tailscale_client.py

@@ -0,0 +1,213 @@
+"""Tailscale API v2 客户端封装（维护页"Tailscale 管理"用）。
+
+能力：
+  - 列出 tailnet 全部设备（名称/主机名/IP/系统/在线/授权/密钥过期状态）
+  - 更新设备：显示名、主机名、授权开关、密钥不过期（keyExpiryDisabled）
+  - 生成设备接入 auth key（可配置 reusable/ephemeral/preauthorized/有效期）
+  - 删除设备
+
+配置（config.py，支持 .env 注入，**不要提交密钥到 git**）：
+  TAILSCALE_API_KEY — 管理后台 → Settings → API Access Tokens 生成的 key（或 OAuth client 的 client_id:secret）
+  TAILSCALE_TAILNET  — tailnet 名称或 ID（个人账号一般是登录邮箱前缀，如 1422726308）
+
+注意：设备 IP 由 tailnet 自动分配，API 无法修改；列表里的 addresses 只读展示。
+
+参考：https://tailscale.com/api
+"""
+import requests
+
+from config import TAILSCALE_API_KEY, TAILSCALE_TAILNET
+from core.logger import get_logger
+
+_log = get_logger("core.tailscale")
+
+_API_BASE = "https://api.tailscale.com/api/v2"
+_TIMEOUT = (3, 15)
+
+
+class TailscaleError(Exception):
+    """Tailscale API 错误（含 HTTP 状态码）。"""
+
+    def __init__(self, message, code=""):
+        super().__init__(message)
+        self.code = code
+
+
+class TailscaleClient:
+    """Tailscale API v2 客户端。
+
+    认证：Basic Auth，API key 作为用户名、空密码；
+    也可传 OAuth client 的 "client_id:client_secret" 作为 key。
+    """
+
+    def __init__(self, api_key=None, tailnet=None):
+        self.api_key = api_key or TAILSCALE_API_KEY
+        self.tailnet = tailnet or TAILSCALE_TAILNET
+
+    # ================== 配置状态 ==================
+    def is_configured(self):
+        """是否已配置 API key 与 tailnet。"""
+        return bool(self.api_key and self.tailnet)
+
+    def config_hint(self):
+        """未配置时的提示文案。"""
+        missing = []
+        if not self.api_key:
+            missing.append("TAILSCALE_API_KEY（Tailscale 后台 → Settings → API Access Tokens）")
+        if not self.tailnet:
+            missing.append("TAILSCALE_TAILNET（tailnet 名，个人账号一般是邮箱前缀）")
+        return "；".join(missing)
+
+    # ================== 请求基座 ==================
+    def _headers(self):
+        return {"Authorization": f"Basic {self._basic()}"}
+
+    def _basic(self):
+        import base64
+        return base64.b64encode(f"{self.api_key}:".encode()).decode()
+
+    def _get(self, path):
+        if not self.is_configured():
+            raise TailscaleError(f"未配置：{self.config_hint()}", "config")
+        try:
+            r = requests.get(f"{_API_BASE}{path}", headers=self._headers(), timeout=_TIMEOUT)
+        except requests.exceptions.ConnectionError as e:
+            raise TailscaleError(f"Tailscale API 不可达: {e}", "network") from e
+        except requests.exceptions.Timeout as e:
+            raise TailscaleError("Tailscale API 请求超时", "network") from e
+        return self._handle(r)
+
+    def _post(self, path, body):
+        if not self.is_configured():
+            raise TailscaleError(f"未配置：{self.config_hint()}", "config")
+        try:
+            r = requests.post(f"{_API_BASE}{path}", json=body,
+                              headers=self._headers(), timeout=_TIMEOUT)
+        except requests.exceptions.ConnectionError as e:
+            raise TailscaleError(f"Tailscale API 不可达: {e}", "network") from e
+        except requests.exceptions.Timeout as e:
+            raise TailscaleError("Tailscale API 请求超时", "network") from e
+        return self._handle(r)
+
+    def _handle(self, r):
+        try:
+            data = r.json()
+        except Exception:
+            data = {}
+        if r.status_code == 401:
+            raise TailscaleError("API key 无效或已过期（401）", "auth")
+        if r.status_code == 404:
+            raise TailscaleError("tailnet 不存在或无权访问（404），请检查 TAILSCALE_TAILNET", "notfound")
+        if r.status_code >= 400:
+            msg = data.get("message") or str(data)[:200]
+            _log.error(f"Tailscale API 错误 {r.status_code}: {msg}")
+            raise TailscaleError(f"Tailscale API 错误 {r.status_code}: {msg}", "api")
+        return data
+
+    # ================== 设备 ==================
+    def list_devices(self):
+        """列出 tailnet 全部设备。
+
+        返回 [{id, name, hostname, os, addresses[], authorized,
+               key_expiry_disabled, online, last_seen, ...}]（字段已规整）。
+        """
+        data = self._get(f"/tailnet/{self.tailnet}/devices")
+        devices = []
+        for d in data.get("devices", []):
+            online = d.get("online")
+            devices.append({
+                "id": d.get("id", ""),
+                "name": d.get("name", ""),
+                "hostname": d.get("hostname", ""),
+                "os": d.get("os", ""),
+                "addresses": d.get("addresses", []),
+                "authorized": bool(d.get("authorized")),
+                "key_expiry_disabled": bool(d.get("keyExpiryDisabled")),
+                # online 三态：True=在线 / False=离线 / None=最近 12 小时内见过但当前未上报（API 返回 null）。
+                # 注意不能 bool(null)——那会把"最近在线"误显示成"离线"。
+                "online": online if online is not None else None,
+                "last_seen": d.get("lastSeen", ""),
+                "tags": d.get("tags", []),
+            })
+        return devices
+
+    def set_device_name(self, device_id, name):
+        """修改设备显示名（POST /device/{id}/name）。
+
+        注意：POST /device/{id} 是 405，改名/授权/密钥各有专属端点。
+        """
+        if not name or not str(name).strip():
+            raise TailscaleError("名称不能为空")
+        self._post(f"/device/{device_id}/name", {"name": str(name).strip()})
+        return True
+
+    def set_device_authorized(self, device_id, authorized):
+        """授权/取消授权（POST /device/{id}/authorized）。"""
+        self._post(f"/device/{device_id}/authorized", {"authorized": bool(authorized)})
+        return True
+
+    def set_device_key_expiry(self, device_id, disabled):
+        """关闭/恢复设备密钥过期（POST /device/{id}/key）。
+
+        disabled=True 即"密钥不过期"（设备不会被定期踢下线）；
+        恢复过期后按原定过期时间执行，若已过期需重新授权。
+        """
+        self._post(f"/device/{device_id}/key", {"keyExpiryDisabled": bool(disabled)})
+        return True
+
+    def set_device_ip(self, device_id, ipv4):
+        """为设备设置新的 Tailscale IPv4 地址。
+
+        端点 POST /device/{device_id}/ip 实测存在（官方文档未收录，属未公开接口）。
+        注意：
+          - 修改 IP 会断开该设备当前的 tailscale 会话，几秒后以新 IP 重连
+          - 平台设备池（STF serial）用的就是 tailnet IP，改完需同步更新 STF 设备池
+          - IPv6 无公开 API 可改
+        """
+        if not ipv4 or not str(ipv4).strip():
+            raise TailscaleError("IPv4 地址不能为空")
+        self._post(f"/device/{device_id}/ip", {"ipv4": str(ipv4).strip()})
+        return True
+
+    def delete_device(self, device_id):
+        """从 tailnet 移除设备（下次设备上线需重新授权）。"""
+        if not self.is_configured():
+            raise TailscaleError(f"未配置：{self.config_hint()}", "config")
+        try:
+            r = requests.delete(f"{_API_BASE}/device/{device_id}",
+                                headers=self._headers(), timeout=_TIMEOUT)
+        except requests.exceptions.ConnectionError as e:
+            raise TailscaleError(f"Tailscale API 不可达: {e}", "network") from e
+        return self._handle(r)
+
+    # ================== Auth key ==================
+    def create_auth_key(self, description="auto_control", reusable=False,
+                        ephemeral=False, preauthorized=True, expiry_seconds=3600):
+        """生成设备接入 auth key。
+
+        返回 {id, key, expires}。key 只显示这一次，请立即复制保存。
+        preauthorized=True：新设备接入自动授权（免去后台手动点授权）。
+        """
+        body = {
+            "description": description,
+            "expirySeconds": max(60, int(expiry_seconds)),
+            "capabilities": {
+                "devices": {
+                    "create": {
+                        "reusable": bool(reusable),
+                        "ephemeral": bool(ephemeral),
+                        "preauthorized": bool(preauthorized),
+                    }
+                }
+            },
+        }
+        data = self._post(f"/tailnet/{self.tailnet}/keys", body)
+        return {
+            "id": data.get("id", ""),
+            "key": data.get("key", ""),
+            "expires": data.get("expires", ""),
+        }
+
+
+# 模块级单例（与 stf_client 的用法一致）
+tailscale = TailscaleClient()

core/task_manager.py

@@ -21,6 +21,7 @@ import json
 import time
 import uuid
 import threading
+from datetime import datetime
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
 from apscheduler.schedulers.background import BackgroundScheduler
@@ -29,9 +30,10 @@ from apscheduler.triggers.cron import CronTrigger
 from config import DATA_DIR
 from core.logger import get_logger
 from core.models import db, DeviceGroup as GroupRow, TaskJob as JobRow
-from .stf_client import STFClient, DeviceOfflineError
+from core import device_pool
-from .adb_helper import get_foreground_app, adb_connect_light, adb_disconnect
+from .adb_helper import get_foreground_app, get_foreground_app_remote
 from .device_worker import (
+    DeviceOfflineError,
     get_all_worker_status, _update_status, _remove_worker,
     _WORKERS, _WORKERS_LOCK,
     start_watchdog, stop_watchdog,
@@ -40,6 +42,65 @@ from tasks import list_task_types, get_task_class
 
 _log = get_logger("core.tm")
 
+# 错峰启动间隔（秒）：批量触发时设备逐个开始连接，避免 adb 全局锁串行堆积。
+# 100 台 × 0.2s = 20s 全部开始启动。
+_START_STAGGER_SEC = 0.2
+
+
+def _in_run_window(schedule, now=None):
+    """是否在当前运行窗口内。
+
+    schedule.window = {"start": "HH:MM", "end": "HH:MM"}，每天重复；
+    窗口外（定时触发 + 手动执行）任务不会启动。未配置/非法配置视为不限制。
+    支持跨午夜（如 21:00-09:00 = 晚上 9 点运行到次日早 9 点）。
+    """
+    win = (schedule or {}).get("window") or {}
+    start, end = win.get("start", ""), win.get("end", "")
+    if not start or not end:
+        return True
+    try:
+        cur = (now or datetime.now()).hour * 60 + (now or datetime.now()).minute
+        s = int(start.split(":")[0]) * 60 + int(start.split(":")[1])
+        e = int(end.split(":")[0]) * 60 + int(end.split(":")[1])
+    except (ValueError, AttributeError, IndexError):
+        return True  # 配置非法按不限制处理
+    if s == e:
+        return True  # 起止相同视为不限制
+    if s < e:
+        return s <= cur < e
+    return cur >= s or cur < e  # 跨午夜
+
+
+def _next_run_time(schedule, now=None):
+    """任务下次真正执行的时间（考虑运行窗口）。
+
+    用 CronTrigger.get_next_fire_time 从当前时间向后找触发点，
+    跳过运行窗口外的触发点（最多找 200 次防死循环）。
+    返回 datetime 或 None（无 cron / 配置非法）。
+    """
+    sched = schedule or {}
+    if sched.get("mode") not in ("cron", "cron_stop"):
+        return None
+    cron = sched.get("cron", "")
+    if not cron:
+        return None
+    try:
+        trigger = CronTrigger.from_crontab(cron)
+    except Exception:
+        return None
+    now = now or datetime.now()
+    win = sched.get("window") or {}
+    if not win.get("start") or not win.get("end"):
+        return trigger.get_next_fire_time(None, now)
+    fire = trigger.get_next_fire_time(None, now)
+    for _ in range(200):
+        if fire is None:
+            return None
+        if _in_run_window({"window": win}, fire):
+            return fire
+        fire = trigger.get_next_fire_time(fire, fire)
+    return None
+
 
 # ================== 设备分组 ==================
 class DeviceGroup:
@@ -83,18 +144,59 @@ class TaskJob:
                    d.get("params"), d.get("schedule"), d.get("retry"), d.get("enabled", True))
 
     def resolve_serials(self, manager):
-        """根据 target 解析出实际要跑的 serial 列表。"""
+        """根据 target 解析出实际要跑的 serial 列表。
+
+        数据源：core.device_pool（本地清单 + adb 在线状态），不再查 STF。
+        """
         mode = self.target.get("mode", "all")
         if mode == "serial":
-            return [self.target["serial"]]
+            serials = [self.target["serial"]]
-        if mode == "group":
+        elif mode == "group":
             g = manager.groups.get(self.target.get("group_name"))
-            return list(g.serials) if g else []
+            serials = list(g.serials) if g else []
-        # all：返回所有空闲设备
+            # 分组应引用设备池内设备：不在池内的（如手动填的旧 IP）不参与调度，
+            # 与 all/preempt 模式口径一致（2026-09-01）
             try:
-            return [d["serial"] for d in manager.stf.list_free_devices()]
+                configured = set(device_pool.list_configured())
+                serials = [s for s in serials if s in configured]
+            except Exception:
+                pass
+        else:
+            # all：默认返回池内在线设备（单实例互斥由 _run_with_retry 的 _running 保证）；
+            # 抢占模式返回全部在线设备（含运行中，执行时抢占）
+            if self.params.get("preempt"):
+                try:
+                    # 抢占模式：只抢设备池内的在线设备——
+                    # list_online() 会包含待连接/未入池设备（如自动发现验证时连上的），
+                    # 它们不在设备池就不该被任务调度（2026-09-01 修复）
+                    online = set(device_pool.list_online())
+                    configured = set(device_pool.list_configured())
+                    return [s for s in device_pool.list_online() if s in configured]
                 except Exception:
                     return []
+            try:
+                return device_pool.list_ready()
+            except Exception:
+                return []
+        # 离线自动跳过（serial/group 模式）：跳过本机 adb 不可达的设备，
+        # 避免反复尝试连接后报"设备离线"。默认开启，可在任务编辑器取消勾选。
+        if serials and self.params.get("skip_offline", True):
+            try:
+                online = set(device_pool.list_online())
+            except Exception:
+                online = None  # 查询失败时不过滤，维持原行为
+            if online is not None:
+                kept, skipped = [], []
+                for s in serials:
+                    if s in online:
+                        kept.append(s)
+                    else:
+                        skipped.append((s, "离线(未连接)"))
+                if skipped:
+                    detail = ", ".join(f"{s}({why})" for s, why in skipped)
+                    _log.info(f"任务 {self.name} 跳过 {len(skipped)} 台设备: {detail}")
+                serials = kept
+        return serials
 
 
 # ================== 前台 App 扫描器 ==================
@@ -105,17 +207,16 @@ class _ForegroundScanner:
 
     策略（按设备状态区分获取逻辑）：
       - worker 运行中设备：用已有 remote_adb_url 直接查询（已有 adb 连接，无额外开销）
-      - 空闲设备：直接 adb connect <serial> → 查询 → adb disconnect（绕过 STF，不打扰设备）
+      - USB 运行中设备：经远程 adb server（220）查询
-      - 被别人占用的设备：标记 "他人占用"
+      - 空闲设备：不主动连接（返回"空闲"）——IP:5555 的 adb transport 与 220
-      - STF occupy/release 会打扰设备（可能退回桌面），绝不使用
+        共享，外部 connect/disconnect 会扰动共享连接
 
     serial 格式为 IP:5555（设备本身的 adb 网络地址），可直接 adb connect。
     adb connect/disconnect 只建立/断开调试连接，不影响设备 UI。
     dumpsys window 只读取窗口状态，不执行任何操作。
     """
 
-    def __init__(self, stf):
+    def __init__(self):
-        self.stf = stf
         self._cache = {}            # serial -> app_name
         self._cache_lock = threading.Lock()
         self._scanning = threading.Event()  # 标记是否正在扫描
@@ -153,61 +254,44 @@ class _ForegroundScanner:
     def _scan_all(self):
         """扫描所有在线设备（后台线程执行）。
 
-        按设备归属分四类处理：
+        按设备归属分两类处理：
           1. worker 运行中：用已有 remote_adb_url 直接查询（无额外开销）
-          2. 自己账户占用但无 worker：调用 STF remoteConnect 获取隧道查询
+          2. 空闲设备：返回"空闲"——不主动连接。IP:5555 的 adb transport
-             （不 occupy/release，不打扰设备 UI）
+             与 STF provider 共享，外部 connect/disconnect 会让 STF 误判
-          3. 完全空闲设备（using=False）：尝试轻量 adb connect serial
+             设备离线并触发重连（迁移期仍保留此约束，摘除 STF 后可放开）
-             （单次尝试，不 kill-server，不影响其他 worker）
-          4. 被他人占用：标记 "(他人占用)"
         """
         self._scanning.set()
         _log.info("前台 App 扫描已启动")
         try:
-            all_devices = self.stf.list_all_devices()
+            online = set(device_pool.list_online())
         except Exception as e:
-            _log.error("前台 App 扫描: 获取设备列表失败: %s", e)
+            _log.error("前台 App 扫描: 获取在线设备失败: %s", e)
             self._scanning.clear()
             return
 
-        # 自己账户已占用的设备列表（用于区分"自己占用"vs"他人占用"）
-        try:
-            my_serials = {d["serial"] for d in self.stf.list_my_devices()}
-        except Exception:
-            my_serials = set()
-
         worker_status = {w["serial"]: w for w in get_all_worker_status()}
 
         # 分类设备
-        have_conn = {}    # serial -> remote_adb_url（worker 运行中，已有 adb 连接）
+        have_conn = {}    # serial -> remote_adb_url（IP:5555 运行中设备）
-        my_owned = []      # 自己账户占用但无 running worker，需 remoteConnect 获取隧道
+        usb_conn = {}     # serial -> usb_server（USB 运行中设备，经远程 adb server）
-        free_serials = []  # 完全空闲设备，尝试轻量 adb connect
+        free_serials = []  # 空闲设备
-        skip_serials = []  # 被他人占用
 
-        for dev in all_devices:
+        for serial in online:
-            if not dev.get("present"):
-                continue
-            serial = dev.get("serial", "")
-            if not serial:
-                continue
             w = worker_status.get(serial, {})
-            url = w.get("remote_adb_url")
+            if w.get("status") not in ("running", "connecting"):
-            if url and w.get("status") in ("running", "connecting"):
+                free_serials.append(serial)
-                # 1. 设备正在执行任务，已有 adb 连接，直接查询
+            elif w.get("remote_adb_url"):
-                have_conn[serial] = url
+                # 1. IP:5555 设备正在执行任务，已有 adb 连接，直接查询
-            elif serial in my_serials:
+                have_conn[serial] = w["remote_adb_url"]
-                # 2. 自己账户占用但无 worker，可安全 remoteConnect（不打扰设备）
+            elif w.get("usb_server"):
-                my_owned.append(serial)
+                # 1b. USB 设备运行中：经远程 adb server 查询
-            elif dev.get("using"):
+                usb_conn[serial] = w["usb_server"]
-                # 4. 被他人占用
-                skip_serials.append(serial)
             else:
-                # 3. 完全空闲，尝试轻量 adb connect（不 kill-server）
                 free_serials.append(serial)
 
         results = {}
-        _log.info("前台 App 扫描分类: 运行中=%d, 自己占用=%d, 空闲=%d, 他人占用=%d",
+        _log.info("前台 App 扫描分类: 运行中=%d, USB运行中=%d, 空闲=%d",
-                  len(have_conn), len(my_owned), len(free_serials), len(skip_serials))
+                  len(have_conn), len(usb_conn), len(free_serials))
 
         # 1. worker 运行中设备：用已有 remote_adb_url 查询（并发 10）
         if have_conn:
@@ -221,33 +305,21 @@ class _ForegroundScanner:
                     except Exception:
                         results[s] = None
 
-        # 2. 自己占用设备：remoteConnect 获取隧道 → 查询 → 断开（并发 5，不打扰设备）
+        # 1b. USB 运行中设备：经远程 adb server 查询（并发 5）
-        if my_owned:
+        if usb_conn:
-            with ThreadPoolExecutor(max_workers=min(5, len(my_owned))) as pool:
+            with ThreadPoolExecutor(max_workers=min(5, len(usb_conn))) as pool:
-                futures = {pool.submit(self._scan_my_owned, s): s
+                futures = {pool.submit(self._scan_usb_conn, s): s
-                           for s in my_owned}
+                           for s, server in usb_conn.items()}
-                for fut in as_completed(futures, timeout=30):
+                for fut in as_completed(futures, timeout=15):
                     s = futures[fut]
                     try:
                         results[s] = fut.result()
                     except Exception:
                         results[s] = None
 
-        # 3. 空闲设备：轻量 adb connect serial → 查询 → disconnect（并发 10）
+        # 2. 空闲设备：不打扰，直接返回"空闲"
-        if free_serials:
+        for s in free_serials:
-            with ThreadPoolExecutor(max_workers=min(10, len(free_serials))) as pool:
+            results[s] = "空闲"
-                futures = {pool.submit(self._scan_free, s): s
-                           for s in free_serials}
-                for fut in as_completed(futures, timeout=20):
-                    s = futures[fut]
-                    try:
-                        results[s] = fut.result()
-                    except Exception:
-                        results[s] = None
-
-        # 4. 被别人占用的设备
-        for s in skip_serials:
-            results[s] = "(他人占用)"
 
         # 更新缓存
         with self._cache_lock:
@@ -259,51 +331,37 @@ class _ForegroundScanner:
         self._scanning.clear()
         _log.info("前台 App 扫描完成: %d 台设备", len(results))
 
-    def _scan_my_owned(self, serial):
+    def _scan_usb_conn(self, serial):
-        """自己账户占用的设备：通过 STF remoteConnect 获取隧道查询。
+        """USB 运行中设备：经远程 adb server（220）查询前台 App。"""
-
-        不调用 occupy/release，只建立/断开 ADB 隧道，不打扰设备 UI。
-        """
         try:
-            url = self.stf.remote_connect(serial)
+            with _WORKERS_LOCK:
-            if not url:
+                server = _WORKERS.get(serial, {}).get("usb_server", "")
+            if not server:
                 return None
-            try:
+            host, _, port = server.partition(":")
-                if not adb_connect_light(url):
+            return get_foreground_app_remote(host, int(port), serial)
-                    return None
-                return get_foreground_app(url)
-            finally:
-                adb_disconnect(url)
-                self.stf.remote_disconnect(serial)
         except Exception:
             return None
 
-    def _scan_free(self, serial):
-        """空闲设备：不扫描前台 App，直接返回"空闲"。
-
-        原因：STF provider 内部通过 IP:5555 维持 adb 连接监控设备。
-        外部 adb connect/disconnect IP:5555 会让 adb server 断开该地址的
-        transport，连带 STF provider 的连接一起断，STF 误判设备 offline
-        并触发重连——表现就是"一扫描前台 App 设备就离线、需要重连"。
-        因此空闲设备绝不主动 adb connect/disconnect，只对运行中设备
-        （走 STF 隧道端口，不动 5555）和自占设备（remoteConnect 隧道）扫描。
-        """
-        return "空闲"
-
 
 # ================== 任务管理器 ==================
 class TaskManager:
-    def __init__(self, stf_client=None, app=None):
+    def __init__(self, app=None):
-        self.stf = stf_client or STFClient()
         self.app = app  # Flask app，用于 db context
         self.scheduler = BackgroundScheduler(timezone="Asia/Shanghai")
+        if os.environ.get("DISABLE_SCHEDULER"):
+            # 测试/回归模式：不启动 cron 调度器，避免 test_client 加载任务后
+            # 按 cron 真的跑任务（干扰回归、占用设备）。add_job 仍可调用不报错。
+            _log.info("DISABLE_SCHEDULER=1：跳过 cron 调度器（测试/回归模式）")
+        else:
             self.scheduler.start()
         start_watchdog()  # 启动心跳看门狗
         self.groups = {}        # name -> DeviceGroup(内存业务对象)
         self.jobs = {}          # id -> TaskJob(内存业务对象)
         self._running = {}      # serial -> {"worker", "job_id", "started_at", "attempt"}
+        self._stop_requested = set()  # serial 集合：用户请求停止，阻止后续重试
         self._lock = threading.Lock()
-        self._fg_scanner = _ForegroundScanner(self.stf)
+        self._fg_scanner = _ForegroundScanner()
         self._load()
 
     def _db(self):
@@ -397,6 +455,12 @@ class TaskManager:
         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
 
@@ -431,6 +495,13 @@ class TaskManager:
         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
 
@@ -499,6 +570,11 @@ class TaskManager:
         job = self.jobs.get(job_id)
         if not job:
             return
+        if not _in_run_window(job.schedule):
+            win = job.schedule.get("window") or {}
+            _log.info(f"定时触发 {job.name}({job.id}) 跳过：当前不在运行窗口内 "
+                      f"（{win.get('start','')}-{win.get('end','')}）")
+            return
         _log.info(f"定时触发: {job.name}({job.id})")
         self._run_job(job)
 
@@ -521,8 +597,14 @@ class TaskManager:
                 stopped.append(serial)
         _log.info(f"定时停止 {job.name}({job.id}): 停止 {len(stopped)} 台设备 {stopped}")
 
+    def next_run_of(self, job):
+        """任务下次真正执行的时间（考虑运行窗口）。停用/无 cron 返回 None。"""
+        if not job or not job.enabled:
+            return None
+        return _next_run_time(job.schedule)
+
     def run_job_now(self, job_id):
-        """立即执行任务（手动触发）。"""
+        """立即执行任务（手动触发）。运行窗口只约束定时触发，手动执行不受限制。"""
         job = self.jobs.get(job_id)
         if not job:
             return {"ok": False, "error": "任务不存在"}
@@ -532,7 +614,11 @@ class TaskManager:
         return {"ok": True, "msg": f"任务 {job.name} 已触发"}
 
     def _run_job(self, job):
-        """执行任务：为每个目标设备起 worker（含重试循环）。"""
+        """执行任务：为每个目标设备起 worker（含重试循环）。
+
+        大量设备同时启动会触发 adb connect 全局锁串行 + STF occupy 并发风暴，
+        这里按 _START_STAGGER_SEC 间隔逐个启动，分摊连接压力（100 台 × 0.2s = 20s）。
+        """
         serials = job.resolve_serials(self)
         if not serials:
             _log.warning(f"任务 {job.name} 无可用设备")
@@ -545,33 +631,74 @@ class TaskManager:
         max_attempts = max(1, job.retry.get("max_attempts", 1))
         delay = job.retry.get("delay", 60)
 
-        for serial in serials:
+        for idx, serial in enumerate(serials):
-            # 每台设备一个重试循环线程，互不影响
+            # 每台设备一个重试循环线程，互不影响；错峰延迟在各自线程内等待
             t = threading.Thread(target=self._run_with_retry,
-                                 args=(task, serial, job, max_attempts, delay), daemon=True)
+                                 args=(task, serial, job, max_attempts, delay,
+                                       idx * _START_STAGGER_SEC), daemon=True)
             t.start()
 
-    def _run_with_retry(self, task, serial, job, max_attempts, delay):
+    def _run_with_retry(self, task, serial, job, max_attempts, delay, start_delay=0):
         """单设备任务执行 + 重试。
 
         异常分类：
           DeviceOfflineError — 设备掉线，立即放弃不重试（换设备也没用）
           其他异常           — 按 max_attempts 重试
+        用户停止（stop_device）会加入 _stop_requested，阻止任何后续重试。
         """
+        # 错峰启动：在各自线程内等待，分摊批量启动的连接/占用压力
+        if start_delay > 0:
+            time.sleep(start_delay)
+        # 被抢占的原任务 id（抢占结束后归还）——必须在循环外：
+        # 重试时若重置为 None，finally 归还逻辑会丢失信息，被抢占任务永不恢复
+        preempted_job = None
+        try:
             for attempt in range(1, max_attempts + 1):
-            # 同一 serial 同时只能一个 worker
+                # 用户已请求停止 → 不再启动新 attempt
+                with self._lock:
+                    if serial in self._stop_requested:
+                        _log.info(f"{serial} 用户已请求停止，取消重试 (job={job.name})")
+                        return
+                # 同一 serial 同时只能一个 worker；不同任务可配置抢占
+                preempt = False
                 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"):
+                            # 不同任务且本任务未开启抢占：跳过
+                            _log.warning(f"{serial} 已有任务在跑，跳过 (job={job.name})")
+                            return
+                        preempt = True
+                        if not preempted_job:
+                            preempted_job = cur.get("job_id")
+                if preempt:
+                    # 抢占：锁外停止该设备上的其他任务（stop_device 内部拿同一把锁，
+                    # 在锁内调用会死锁！），等其释放后接管
+                    _log.warning(f"{serial} 抢占：停止任务 {preempted_job} 后执行 {job.name}")
+                    self.stop_device(serial)
+                    deadline = time.time() + 30
+                    while time.time() < deadline:
+                        with self._lock:
+                            if serial not in self._running:
+                                break
+                        time.sleep(0.5)
+                    else:
+                        _log.warning(f"{serial} 抢占超时（旧任务 30s 未退出），跳过 (job={job.name})")
+                        return
+                with self._lock:
                     self._running[serial] = {"job_id": job.id, "started_at": time.time(),
-                                         "attempt": attempt, "task_type": job.task_type}
+                                             "attempt": attempt, "task_type": job.task_type,
+                                             "preempted_job": preempted_job}
                 _update_status(serial, task_job=job.name, attempt=attempt,
                                max_attempts=max_attempts)
 
                 worker = None
                 try:
-                worker = task.create_worker(self.stf, serial, job.params)
+                    worker = task.create_worker(serial, job.params)
                     with self._lock:
                         self._running[serial]["worker"] = worker
                     _log.info(f"{serial} 开始任务 {job.name} (第{attempt}/{max_attempts}次)")
@@ -588,8 +715,10 @@ class TaskManager:
                     if st == "done":
                         _log.info(f"{serial} 任务 {job.name} 成功完成")
                         return
-                if st == "released" and attempt == 1:
+                    # 用户请求停止（无论 attempt 第几次、status 是什么）→ 不重试
-                    # 被手动停止，不重试
+                    with self._lock:
+                        if serial in self._stop_requested:
+                            _log.info(f"{serial} 用户已请求停止，不再重试 (job={job.name})")
                             return
                     _log.warning(f"{serial} 任务未成功(status={st})")
                 except DeviceOfflineError as e:
@@ -607,6 +736,11 @@ class TaskManager:
                     _update_status(serial, task_job="")
 
                 if attempt < max_attempts:
+                    # 用户在 sleep 期间点停止也能中断
+                    with self._lock:
+                        if serial in self._stop_requested:
+                            _log.info(f"{serial} 用户已请求停止，取消重试 (job={job.name})")
+                            return
                     # 检查是否是端口耗尽类临时错误，需要更长退避等端口释放
                     with _WORKERS_LOCK:
                         err = _WORKERS.get(serial, {}).get("last_error", "")
@@ -621,24 +755,44 @@ class TaskManager:
 
             _log.error(f"{serial} 任务 {job.name} 重试耗尽，放弃")
             _update_status(serial, status="failed", last_error=f"{job.name} 重试{max_attempts}次失败")
+        finally:
+            # 清除停止标志：整个重试循环结束（成功/失败/停止）后允许下次任务
+            with self._lock:
+                self._stop_requested.discard(serial)
+            # 归还：本任务是抢占任务，结束后自动重新启动被抢占的原任务
+            if preempted_job:
+                j = self.jobs.get(preempted_job)
+                if j and j.enabled:
+                    _log.info(f"{serial} 抢占任务 {job.name} 结束，归还设备给任务 {j.name}")
+                    threading.Thread(target=self._run_job, args=(j,), daemon=True).start()
+                else:
+                    # 打日志便于排查：被抢占任务已删除/停用时不会归还，但要知道原因
+                    _log.info(f"{serial} 抢占任务 {job.name} 结束，"
+                              f"被抢占任务 {preempted_job} {'已停用，不归还' if j else '已不存在，不归还'}")
 
     # ---- 运行控制 ----
     def stop_device(self, serial):
-        """停止指定设备的 worker。"""
+        """停止指定设备的 worker，并阻止后续重试。
+
+        无论 worker 当前在运行还是在重试 sleep 中，都会阻止下一次重试。
+        """
         with self._lock:
+            self._stop_requested.add(serial)
             info = self._running.get(serial)
-        if not info:
+        if info:
-            return False
             w = info.get("worker")
             if w and w.is_alive():
                 w.stop()
                 return True
-        return False
+        # worker 已结束但重试循环可能还在 sleep —— 仍然返回 True 表示已阻止重试
+        return True
 
     def stop_all(self):
-        """停止所有运行中的 worker。"""
+        """停止所有运行中的 worker，并阻止后续重试。"""
         with self._lock:
             items = list(self._running.items())
+            for s, _ in items:
+                self._stop_requested.add(s)
         stopped = []
         for serial, info in items:
             w = info.get("worker")
@@ -651,15 +805,15 @@ class TaskManager:
         with self._lock:
             return {s: dict(v) for s, v in self._running.items()}
 
-    # ---- 状态查询（带缓存，避免 STF 请求阻塞前端）----
+    # ---- 状态查询（带缓存，避免设备列表查询阻塞前端）----
     _status_cache = None       # (timestamp, data, error)
     _status_cache_lock = threading.Lock()
     _STATUS_CACHE_TTL = 5.0    # 缓存 5 秒，前端 5 秒刷新刚好命中
 
     def get_status(self):
-        """综合状态：STF 设备池 + 本地 worker + 运行中的任务。
+        """综合状态：设备池（清单+在线）+ 本地 worker + 运行中的任务。
 
-        带 5 秒缓存：STF 请求慢时避免每次 /api/status 都打 STF 阻塞 Flask。
+        带 5 秒缓存：避免每次 /api/status 都查库/adb 阻塞 Flask。
         worker 状态实时读（内存，无 IO），不受缓存影响。
         """
         with self._status_cache_lock:
@@ -670,36 +824,54 @@ class TaskManager:
                         return None, err
                     # 用缓存的设备列表 + 实时 worker 状态重新组装
                     return self._merge_status(cached), None
-        # 缓存过期或不存在，重新拉 STF
+        # 缓存过期或不存在，重新拉设备池
         try:
-            all_devices = self.stf.list_all_devices()
+            configured = device_pool.list_configured()
         except Exception as e:
             with self._status_cache_lock:
                 self._status_cache = (time.time(), None, str(e))
             return None, f"获取设备列表失败: {e}"
         with self._status_cache_lock:
-            self._status_cache = (time.time(), all_devices, None)
+            self._status_cache = (time.time(), configured, None)
-        return self._merge_status(all_devices), None
+        return self._merge_status(configured), None
 
-    def _merge_status(self, all_devices):
+    def _merge_status(self, configured_serials):
-        """用 STF 设备列表 + 实时 worker 状态 + 前台 App 组装返回结果。"""
+        """用设备池清单 + 实时 worker 状态 + 前台 App 组装返回结果。"""
         worker_status = {w["serial"]: w for w in get_all_worker_status()}
         running = self.get_running()
+        try:
+            online = set(device_pool.list_online())
+        except Exception:
+            online = set()
+        try:
+            pool_rows = device_pool.list_devices()
+            names = {d["serial"]: d["name"] for d in pool_rows}
+            models = {d["serial"]: d["model"] for d in pool_rows}
+        except Exception:
+            names, models = {}, {}
+
+        # 清理陈旧状态：serial 已不在设备池、且没有在跑 worker 的条目，
+        # 避免设备被删除后其失败记录仍残留在"异常汇总"里
+        configured = set(configured_serials)
+        for serial, w in list(worker_status.items()):
+            if serial in configured or serial in running:
+                continue
+            if w.get("status") in ("running", "connecting"):
+                continue
+            _remove_worker(serial)
 
         result = []
-        for dev in all_devices:
+        for serial in configured_serials:
-            serial = dev.get("serial", "")
+            is_online = serial in online
-            owner = dev.get("owner")
             w = worker_status.get(serial, {})
             r = running.get(serial, {})
             result.append({
                 "serial": serial,
-                "model": dev.get("model") or w.get("model", "") or dev.get("product", ""),
+                "model": w.get("model") or models.get(serial, ""),
-                "device_name": dev.get("name") or "",
+                "device_name": names.get(serial, ""),
-                "present": dev.get("present", False),
+                "present": is_online,
-                "ready": dev.get("ready", False),
+                "ready": is_online,          # 阶段 1：ready 概念并入在线状态
-                "stf_occupied": dev.get("using", False),
+                "owner": "",
-                "owner": owner.get("name", "") if owner else "",
                 "worker_status": w.get("status", "idle"),
                 "foreground_app": self._fg_scanner.get(serial),
                 # 通用进度字段（任意 app 通用，前端统一解析展示）
@@ -707,24 +879,26 @@ class TaskManager:
                 "progress": w.get("progress", {}),
                 "current_action": w.get("current_action", ""),
                 "last_error": w.get("last_error", ""),
+                "last_warning": w.get("last_warning", ""),
                 "running_job": r.get("job_id", ""),
                 "task_job": w.get("task_job", ""),
                 "attempt": r.get("attempt", 0),
+                "end_time": w.get("end_time", 0),
             })
         return result
 
     def list_all_serials(self):
-        """返回 STF 上所有在线设备的 serial 列表（供分组表单勾选用）。
+        """返回设备池在线设备的 serial 列表（供分组表单勾选用）。"""
-
+        try:
-        复用 get_status 缓存，避免开页面时阻塞。
+            return device_pool.list_ready()
-        """
+        except Exception:
-        devices, err = self.get_status()
-        if err or not devices:
             return []
-        return [d["serial"] for d in devices if d.get("present")]
 
     def shutdown(self):
         self.stop_all()
         self._fg_scanner.stop()
         stop_watchdog()
+        try:
             self.scheduler.shutdown(wait=False)
+        except Exception:
+            pass  # DISABLE_SCHEDULER 模式下 scheduler 未 start，shutdown 会抛异常

core/uiauto_helper.py

@@ -0,0 +1,252 @@
+"""uiauto2 (uiautodev) 本地服务客户端封装。
+
+uiautodev 启动后本地监听 http://localhost:20242，提供设备元素树查询。
+前端步骤编辑器"抓取元素"按钮通过本模块拉取当前设备 UI 树供选择。
+
+依赖：
+  - 用户需先 `pip install uiautodev` 并运行 `uiauto.dev` 启动本地服务
+  - 未运行时本模块函数返回友好错误，不抛异常
+
+API 参考（uiautodev 0.14）：
+  - GET /api/info                          — 服务信息（用于探测是否运行）
+  - GET /api/android/{serial}/dump_hierarchy — 元素树 JSON
+"""
+import requests
+from collections import Counter
+
+from core.logger import get_logger
+
+_log = get_logger("core.uiauto")
+
+# uiautodev 默认本地端口（固定 20242）
+_UIAUTO_BASE = "http://localhost:20242"
+# 请求超时（秒）。connect 超时短，避免前端等太久
+_TIMEOUT = (1, 8)
+
+
+def is_running():
+    """探测 uiauto2 本地服务是否在运行。"""
+    try:
+        r = requests.get(f"{_UIAUTO_BASE}/api/info", timeout=_TIMEOUT)
+        return r.status_code == 200
+    except Exception:
+        return False
+
+
+def list_devices():
+    """获取 uiauto2 已连接的设备列表。
+
+    返回 (ok, data_or_error)：
+      ok=True  — data 是设备列表 [{serial, model, product, name, status}, ...]
+      ok=False — data 是错误消息字符串
+    """
+    try:
+        r = requests.get(f"{_UIAUTO_BASE}/api/android/list", timeout=_TIMEOUT)
+        r.raise_for_status()
+        data = r.json()
+        return True, data
+    except requests.exceptions.ConnectionError:
+        return False, "uiauto2 未启动，请运行 `uiauto.dev`"
+    except Exception as e:
+        _log.warning(f"list_devices 异常: {e}")
+        return False, f"获取设备列表失败: {e}"
+
+
+def get_screenshot(serial):
+    """获取设备截图（通过 uiauto2 服务）。
+
+    返回 (ok, data_or_error)：
+      ok=True  — data 是 JPEG 二进制数据
+      ok=False — data 是错误消息字符串
+    """
+    if not serial:
+        return False, "缺少 serial"
+    try:
+        r = requests.get(
+            f"{_UIAUTO_BASE}/api/android/{serial}/screenshot/0",
+            timeout=_TIMEOUT,
+        )
+        r.raise_for_status()
+        return True, r.content
+    except requests.exceptions.ConnectionError:
+        return False, "uiauto2 未启动"
+    except Exception as e:
+        _log.warning(f"get_screenshot 异常: {e}")
+        return False, f"截图失败: {e}"
+
+
+def get_elements(serial):
+    """获取指定设备的 UI 元素树。
+
+    返回 (ok, data_or_error)：
+      ok=True  — data 是元素列表 [{name, attrs..., suggested:{type,value,indexed?,occ?,total?,broad?}}, ...]
+      ok=False — data 是错误消息字符串
+
+    元素树由 uiautodev 的 dump_hierarchy 返回（JSON）。我们递归提取每个节点的
+    关键属性（resource-id/text/description/class/bounds...），供前端列表展示和选择。
+
+    选择器精度策略（精确到具体按钮的关键）：
+      1. 有 resource-id/text/content-desc 的元素：
+         先预统计该属性在整棵树中的出现次数——
+           - 唯一出现：直接用属性选择器 //*[@resource-id="x"]
+           - 重复出现（如抖音信息流点赞按钮同 id 几十个）：附加 [k] 位置谓词
+             精确到具体实例 //*[@resource-id="x"][k]。uiautomator2 的 d.xpath()
+             底层是 lxml 标准 XPath，[k] 与抓取时同一语义，不会误中屏幕外第一个。
+      2. 无任何属性的元素：
+         用最近一个有属性祖先的选择器限定范围 + 同 class 兄弟序号定位
+         （如 //*[@resource-id="x"]/FrameLayout/ImageView[2]）；
+         整棵树都没有属性时退化为从根开始的结构路径（标记 broad，前端提示脆弱）。
+    """
+    if not serial:
+        return False, "缺少 serial"
+    try:
+        r = requests.get(
+            f"{_UIAUTO_BASE}/api/android/{serial}/hierarchy",
+            timeout=_TIMEOUT,
+        )
+        if r.status_code == 404:
+            return False, f"设备 {serial} 未连接到 uiauto2"
+        r.raise_for_status()
+        data = r.json()
+        # uiautodev hierarchy 返回 Node 树：{key, name, bounds, rect, properties, children}
+        # 提取成扁平的可选列表（保留层级缩进信息）
+        elements = []
+        _extract(data, elements)
+        if not elements:
+            return False, "当前界面未抓取到元素"
+        return True, elements
+    except requests.exceptions.ConnectionError:
+        return False, "uiauto2 未启动，请运行 `uiauto.dev`"
+    except requests.exceptions.Timeout:
+        return False, "uiauto2 请求超时"
+    except Exception as e:
+        _log.warning(f"get_elements 异常: {e}")
+        return False, f"抓取失败: {e}"
+
+
+def _xpath_q(v):
+    """XPath 字符串字面量：优先双引号，值含双引号时改用单引号包裹（XPath 1.0 无转义）。"""
+    if '"' in v:
+        return "'" + v + "'"
+    return '"' + v + '"'
+
+
+def _extract(root, out):
+    """把 uiautodev 元素树扁平化为可选列表，并为每个节点生成精确选择器建议。"""
+    # 全树属性出现次数（预统计，供重复元素加 [k] 序号消歧）
+    id_cnt, text_cnt, desc_cnt = Counter(), Counter(), Counter()
+    # 文档顺序已出现次数（决定当前元素是第几个）
+    seen_id, seen_text, seen_desc = Counter(), Counter(), Counter()
+
+    def count_attrs(node):
+        if not isinstance(node, dict):
+            return
+        props = node.get("properties") or {}
+        rid, text, desc = (props.get(k, "") for k in ("resource-id", "text", "content-desc"))
+        if rid:
+            id_cnt[rid] += 1
+        if text:
+            text_cnt[text] += 1
+        if desc:
+            desc_cnt[desc] += 1
+        for c in node.get("children") or []:
+            count_attrs(c)
+
+    def attr_selector(attr, value, cnt, seen):
+        """属性选择器：唯一直接出，重复加 [k] 位置谓词。返回 (选择器, suggested)。"""
+        seen[value] += 1
+        val = f'//*[@{attr}={_xpath_q(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}
+
+    def flatten(node, depth=0, path="", ctx=None, tag_path="", tag_index=1):
+        """递归扁平化。
+
+        ctx: 最近一个有属性祖先的选择器（含序号），无属性元素用它限定范围。
+        tag_path: 从根到本节点的完整结构路径（class + 同class兄弟序号），兜底用。
+        tag_index: 本节点在父下同 class 兄弟中的序号（1-based）。
+        """
+        if not isinstance(node, dict):
+            return
+        props = node.get("properties") or {}
+        name = node.get("name") or props.get("class") or ""
+        # bounds：优先取 properties 中的原始字符串 "[x1,y1][x2,y2]"（前端渲染 overlay 用）
+        bounds_str = props.get("bounds", "")
+        if not bounds_str and node.get("rect"):
+            # rect 兜底：只有整数像素坐标才用；uiautodev 归一化浮点坐标无法换算像素
+            r = node["rect"]
+            try:
+                vals = [r["x"], r["y"], r["x"] + r["width"], r["y"] + r["height"]]
+                if all(isinstance(v, (int, float)) and float(v).is_integer() for v in vals):
+                    bounds_str = f"[{int(vals[0])},{int(vals[1])}][{int(vals[2])},{int(vals[3])}]"
+            except (TypeError, KeyError):
+                pass
+
+        rid = props.get("resource-id", "")
+        text = props.get("text", "")
+        desc = props.get("content-desc", "")
+        cls = props.get("class", "")
+        tag = cls.split(".")[-1] if cls else "*"
+        # 始终带同 class 兄弟序号（含 [1]），结构路径才精确无歧义；
+        # class 为空的层（tag=*）不参与结构路径，避免 //*[N] 前缀污染导致选择器定位到任意节点
+        if tag != "*":
+            seg = f"{tag}[{tag_index}]"
+            own_tag_path = f"{tag_path}/{seg}" if tag_path else seg
+        else:
+            seg = ""
+            own_tag_path = tag_path
+
+        # ---- 推荐选择器：唯一属性 > 锚点祖先限定 > 全结构路径 ----
+        if rid:
+            child_ctx, suggested = attr_selector("resource-id", rid, id_cnt, seen_id)
+        elif text:
+            child_ctx, suggested = attr_selector("text", text, text_cnt, seen_text)
+        elif desc:
+            child_ctx, suggested = attr_selector("content-desc", desc, desc_cnt, seen_desc)
+        elif ctx:
+            val = f"{ctx}/{seg}"
+            suggested = {"type": "xpath", "value": val}
+            child_ctx = val
+        else:
+            if tag == "*":
+                # class 也为空的元素：结构路径 //*[N] 无意义（匹配到文档任意节点），
+                # 标记 invalid，前端提示不可选，避免回填垃圾选择器导致"点击不到"
+                suggested = {"type": "xpath", "value": "",
+                             "invalid": True,
+                             "reason": "该元素无可用属性（id/文本/class），无法生成可靠选择器"}
+            else:
+                # 无唯一属性且无锚点祖先：用从根开始的结构路径（脆弱，标记 broad 让前端提示）
+                suggested = {"type": "xpath", "value": f"//{own_tag_path}", "broad": True}
+            child_ctx = None
+
+        out.append({
+            "depth": depth,
+            "path": path,
+            "name": name,
+            "resource_id": rid,
+            "text": text,
+            "description": desc,
+            "class": cls,
+            "package": props.get("package", ""),
+            "clickable": props.get("clickable", ""),
+            "bounds": bounds_str,
+            "suggested": suggested,
+        })
+
+        # 递归子节点，同时计算每个子节点在父下同 class 兄弟中的序号
+        children = node.get("children") or []
+        for i, child in enumerate(children):
+            cprops = child.get("properties") or {}
+            ccls = cprops.get("class", "")
+            ctag = ccls.split(".")[-1] if ccls else "*"
+            same = 1 + sum(
+                1 for prev in children[:i]
+                if ((prev.get("properties") or {}).get("class", "")).split(".")[-1] == ctag
+            )
+            flatten(child, depth + 1, f"{path}/{i}", child_ctx, own_tag_path, same)
+
+    count_attrs(root)
+    flatten(root)

create_task.py

@@ -1,85 +0,0 @@
-"""一次性脚本：创建"抖音定时8-9点"任务。
-
-用法（在 cmd 中执行，不是 PowerShell）：
-    cd /d d:\\platform-tools
-    python create_task.py
-
-任务配置：
-  - 名称：抖音定时8-9点
-  - 类型：douyin_nurture（抖音养号）
-  - 目标：全部空闲设备
-  - 调度：定时启停（每天 8:00 启动，9:00 自动停止）
-  - 视频数量：不限（watch_count=0，靠停止 cron 到点停）
-  - 运行时长：不限（max_duration=0，靠停止 cron 到点停）
-  - 点赞：启用，rate=0.3
-"""
-import sys
-import os
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-from flask import Flask
-from core.models import db, init_db, TaskJob as JobRow
-from core.task_manager import TaskManager, TaskJob
-from core.stf_client import STFClient
-
-app = Flask(__name__)
-app.config["SECRET_KEY"] = "dev-secret-key-change-in-production"
-app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///" + os.path.join(
-    os.path.dirname(os.path.abspath(__file__)), "data", "users.db")
-app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
-
-init_db(app)
-
-with app.app_context():
-    # 检查是否已存在同名任务
-    existing = JobRow.query.filter_by(name="抖音定时8-9点").first()
-    if existing:
-        print(f"任务已存在: id={existing.id}, name={existing.name}")
-        print("如需重新创建，请先在前端删除该任务。")
-        sys.exit(0)
-
-    # 构造任务计划
-    job = TaskJob(
-        name="抖音定时8-9点",
-        task_type="douyin_nurture",
-        target={"mode": "all"},
-        params={
-            "watch_count": 0,       # 不限视频数量
-            "max_duration": 0,      # 不限运行时长（靠 stop_cron 到点停止）
-            "actions": {
-                "like": {
-                    "enabled": True,
-                    "params": {"rate": 0.3, "method": "by_element"},
-                },
-            },
-        },
-        schedule={
-            "mode": "cron_stop",
-            "cron": "0 8 * * *",        # 每天 8:00 启动
-            "stop_cron": "0 9 * * *",   # 每天 9:00 停止
-        },
-        retry={"max_attempts": 1, "delay": 60},
-        enabled=True,
-    )
-
-    # 写入数据库
-    row = JobRow(id=job.id, name=job.name, task_type=job.task_type, enabled=job.enabled)
-    row.set_target(job.target)
-    row.set_params(job.params)
-    row.set_schedule(job.schedule)
-    row.set_retry(job.retry)
-    db.session.add(row)
-    db.session.commit()
-
-    print(f"✓ 任务创建成功！")
-    print(f"  ID: {job.id}")
-    print(f"  名称: {job.name}")
-    print(f"  类型: {job.task_type}")
-    print(f"  目标: 全部空闲设备")
-    print(f"  调度: 每天 08:00 启动 → 09:00 自动停止")
-    print(f"  视频数量: 不限（靠定时停止）")
-    print(f"  点赞: 启用 (rate=0.3)")
-    print()
-    print("启动 web_server 后，该任务会自动加载并注册定时。")
-    print("启动命令: python web_server.py")

doc/API.md

@@ -0,0 +1,851 @@
+# API 接口文档
+
+`platform-tools` Web 后台提供 JSON API，所有接口需登录后访问（Flask-Login session 认证）。
+
+**Base URL**：`http://localhost:18050`
+
+**认证方式**：Cookie Session（先 POST `/login` 获取 session cookie，后续请求带上）
+
+**通用响应格式**：
+```json
+{"ok": true, "data": "..."}
+{"ok": false, "error": "错误信息"}
+```
+
+---
+
+**权限模型**（v2 起）：
+- 所有接口需登录；**查看类 GET 接口**（状态/列表/截图）所有登录用户可用
+- **写操作按权限位授权**（管理员拥有全部权限）：
+  | 权限位 | 中文 | 覆盖接口 |
+  |--------|------|---------|
+  | `tasks` | 任务管理 | 任务/自定义动作/分组的增删改、启停、立即执行 |
+  | `devices` | 设备控制 | 停止设备、释放占用、清除异常、前台扫描、元素抓取 |
+  | `apks` | 应用管理 | APK 上传、安装、删除 |
+  | `logs` | 日志查看 | `GET /api/logs` |
+- **用户管理接口仅管理员可用**（普通用户即使被授予业务权限也无法访问）
+- 无权限访问返回 `403 {"ok": false, "error": "无权限执行此操作..."}`
+- 当前用户权限查询：`GET /api/me`
+
+---
+
+## 1. 认证
+
+### POST /login
+
+用户登录。
+
+**请求**（form-data）：
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| username | string | 用户名 |
+| password | string | 密码 |
+
+**响应**：成功重定向到 `/`，失败返回登录页（含 error 信息）。
+
+### GET /logout
+
+登出，重定向到登录页。
+
+---
+
+## 2. 页面路由
+
+### GET /
+
+单页应用首页（需登录）。响应头设置 `Cache-Control: no-store` 防止缓存。
+
+### GET /login
+
+登录页面（GET）。
+
+---
+
+## 3. 设备状态
+
+### GET /api/status
+
+获取设备池 + Worker 综合状态（带 5 秒缓存）。
+
+**响应**：
+```json
+{
+  "ok": true,
+  "server_time": 1700000000.0,
+  "fg_scanning": false,
+  "fg_last_scan": 1700000000.0,
+  "devices": [
+    {
+      "serial": "192.168.1.100:5555",
+      "model": "Pixel 6",
+      "device_name": "测试机1",
+      "present": true,
+      "ready": true,
+      "stf_occupied": false,
+      "owner": "",
+      "worker_status": "idle",
+      "foreground_app": "空闲",
+      "progress": {"done": 5, "total": 80, "unit": "视频", "action_counts": {"like": 3}},
+      "current_action": "观看视频 6",
+      "last_error": "",
+      "running_job": "",
+      "task_job": "",
+      "attempt": 0
+    }
+  ]
+}
+```
+
+**worker_status 取值**：`idle` / `connecting` / `running` / `done` / `error` / `failed` / `released`
+
+（权限：设备控制）
+
+手动触发前台 App 扫描（后台异步执行，不打扰设备）。
+
+**响应**：
+```json
+{"ok": true, "msg": "扫描已启动"}
+{"ok": false, "error": "已有扫描在进行中"}
+```
+
+### GET /api/devices
+
+返回所有在线设备 serial 列表（供分组表单勾选用）。
+
+**响应**：
+```json
+{"ok": true, "devices": ["192.168.1.100:5555", "192.168.1.101:5555"]}
+```
+
+### GET /api/device/screenshot
+
+获取设备当前画面截图（PNG）。
+
+**参数**：
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| serial | string | 设备 serial |
+| t | int | 时间戳（避免缓存，前端自动加） |
+
+**响应**：成功返回 `image/png`，失败返回 JSON 错误。
+
+> 用 `adb exec-out screencap -p`，只读操作，任务运行中调用安全。
+
+---
+
+## 4. 任务类型
+
+### GET /api/task_types
+
+返回所有已注册任务类型。
+
+**响应**：
+```json
+{
+  "ok": true,
+  "task_types": [
+    {
+      "task_type": "douyin_nurture",
+      "name": "抖音养号",
+      "description": "自动观看抖音视频...",
+      "default_params": {"watch_count": 80, "...": "..."}
+    },
+    {
+      "task_type": "generic_steps",
+      "name": "通用步骤",
+      "description": "通过步骤编辑器编排...",
+      "default_params": {"steps": [...]}
+    }
+  ]
+}
+```
+
+### GET /api/actions
+
+返回指定任务类型支持的专属操作。
+
+**参数**：
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| task_type | string | 任务类型 |
+
+**响应**：
+```json
+{
+  "ok": true,
+  "actions": [
+    {"action_type": "like", "name": "点赞", "description": "...", "default_params": {"rate": 0.3}}
+  ]
+}
+```
+
+---
+
+## 5. 任务计划 CRUD
+
+### GET /api/jobs
+
+列出所有任务计划。
+
+**响应**：
+```json
+{
+  "ok": true,
+  "jobs": [{"id": "abc123", "name": "抖音养号", "task_type": "douyin_nurture",
+            "next_run": "2026-08-12 09:00", "...": "..."}],
+  "task_types": [...]
+}
+```
+`next_run`：下次真正执行时间（已按运行窗口跳过窗口外触发点，格式 `YYYY-MM-DD HH:MM`）；手动任务/已停用为 `null`。
+
+（权限：任务管理）
+
+创建任务计划。
+
+**请求**（JSON）：
+```json
+{
+  "name": "抖音养号",
+  "task_type": "douyin_nurture",
+  "target": {"mode": "all"},
+  "params": {"watch_count": 50, "actions": {"like": {"params": {"rate": 0.5}}}},
+  "schedule": {"mode": "cron", "cron": "0 */2 * * *"},
+  "retry": {"max_attempts": 3, "delay": 60},
+  "enabled": true
+}
+```
+
+**响应**：
+```json
+{"ok": true, "msg": "任务已创建", "job": {"id": "abc123", "...": "..."}}
+```
+
+`schedule` 字段格式：
+| 字段 | 说明 |
+|------|------|
+| `mode` | `once` 手动 / `cron` 定时启动 / `cron_stop` 定时启动+停止 |
+| `cron` | 标准 5 段 cron：`分 时 日 月 周`（周 `0`/`7`=周日）；如 `0 */2 * * *` 每 2 小时整点 |
+| `stop_cron` | （cron_stop 必填）到点停止本任务 worker |
+| `window` | 可选，运行窗口 `{"start": "21:00", "end": "09:00"}`（每天重复，支持跨午夜）。窗口外定时触发和手动执行（`POST /api/jobs/:id/run`）均不启动，手动执行返回错误提示 |
+
+（权限：任务管理）
+
+更新任务计划。只需传要更新的字段。
+
+**请求**（JSON）：
+```json
+{"params": {"watch_count": 100}}
+```
+
+**响应**：
+```json
+{"ok": true, "msg": "任务已更新", "job": {"...": "..."}}
+```
+
+（权限：任务管理）
+
+删除任务计划。
+
+**响应**：
+```json
+{"ok": true, "msg": "任务已删除"}
+```
+
+（权限：任务管理）
+
+立即执行任务（异步，不阻塞）。
+
+**响应**：
+```json
+{"ok": true, "msg": "任务 抖音养号 已触发"}
+```
+
+（权限：任务管理）
+
+启用/停用任务。
+
+**请求**（JSON）：
+```json
+{"enabled": false}
+```
+
+**响应**：
+```json
+{"ok": true, "msg": "任务已停用"}
+```
+
+---
+
+## 6. 设备分组
+
+### GET /api/groups
+
+列出所有分组。
+
+**响应**：
+```json
+{
+  "ok": true,
+  "groups": [
+    {"name": "A组", "serials": ["192.168.1.100:5555"], "description": "测试组"}
+  ]
+}
+```
+
+（权限：任务管理）
+
+创建分组。
+
+**请求**（JSON）：
+```json
+{"name": "A组", "serials": ["192.168.1.100:5555"], "description": "测试组"}
+```
+
+（权限：任务管理）
+
+更新分组。
+
+**请求**（JSON）：
+```json
+{"serials": ["192.168.1.100:5555", "192.168.1.101:5555"], "description": "更新描述"}
+```
+
+（权限：任务管理）
+
+删除分组。
+
+---
+
+## 7. 运行控制
+
+（权限：设备控制）
+
+停止单台设备的 worker（并阻止后续重试）。
+
+**请求**（JSON）：
+```json
+{"serial": "192.168.1.100:5555"}
+```
+
+**响应**：
+```json
+{"ok": true, "msg": "已发送停止信号给 192.168.1.100:5555"}
+```
+
+（权限：设备控制）
+
+停止所有运行中的 worker。
+
+**响应**：
+```json
+{"ok": true, "stopped": ["192.168.1.100:5555", "192.168.1.101:5555"]}
+```
+
+（权限：设备控制）
+
+（已随 STF 摘除移除，此接口不再存在；设备互斥由调度器内存锁保证）
+
+**响应**：
+```json
+{"ok": true, "released": ["192.168.1.100:5555"]}
+```
+
+---
+
+## 8. 用户管理
+
+（仅管理员）
+
+列出所有用户。
+
+**响应**：
+```json
+{"ok": true, "users": [{"id": 1, "username": "admin", "is_admin": true}]}
+```
+
+（仅管理员）
+
+创建用户。
+
+**请求**（JSON）：
+```json
+{"username": "user1", "password": "pass123", "is_admin": false}
+```
+
+（仅管理员）
+
+更新用户（修改密码/管理员权限）。
+
+**请求**（JSON）：
+```json
+{"password": "newpass", "is_admin": true}
+```
+
+（仅管理员）
+
+删除用户（不能删除 admin 和当前登录用户）。
+
+---
+
+## 9. 日志
+
+（权限：日志查看）
+
+查看日志文件内容。
+
+**参数**：
+| 参数 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| file | string | `core.log` | 日志文件名 |
+| lines | int | 300 | 返回最后 N 行 |
+
+**可选文件**：`core.log` / `task.log` / `web.log` / `action.log`
+
+**响应**：
+```json
+{
+  "ok": true,
+  "content": "2026-08-08 10:00:00 [INFO] [core.worker] ...",
+  "file": "core.log",
+  "files": {"core": "core.log", "task": "task.log", "web": "web.log", "action": "action.log"}
+}
+```
+
+---
+
+## 10. 自定义动作
+
+### GET /api/custom_actions
+
+列出所有自定义动作（步骤打包）。
+
+（权限：任务管理）
+
+创建自定义动作。
+
+**请求**（JSON）：
+```json
+{"name": "登录流程", "icon": "📦", "steps": [{"type": "click", "...": "..."}]}
+```
+
+（权限：任务管理）
+
+更新自定义动作。
+
+（权限：任务管理）
+
+删除自定义动作。
+
+---
+
+## 11. 元素抓取（uiauto2）
+
+### GET /api/uiauto/status
+
+探测 uiauto2 本地服务是否运行。
+
+**响应**：
+```json
+{"ok": true, "running": true}
+```
+
+（权限：设备控制）
+
+获取 uiauto2 已连接的设备列表。
+
+**响应**：
+```json
+{"ok": true, "devices": [{"serial": "192.168.1.100:5555", "model": "Pixel 6"}]}
+```
+
+（权限：设备控制）
+
+通过 uiauto2 获取设备截图（JPEG）。
+
+**参数**：
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| serial | string | 设备 serial |
+
+**响应**：成功返回 `image/jpeg`，失败返回 JSON 错误。
+
+（权限：设备控制）
+
+获取设备 UI 元素树。
+
+**参数**：
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| serial | string | 设备 serial |
+
+**响应**：
+```json
+{
+  "ok": true,
+  "elements": [
+    {
+      "depth": 0,
+      "name": "android.widget.FrameLayout",
+      "resource_id": "",
+      "text": "",
+      "description": "",
+      "class": "android.widget.FrameLayout",
+      "bounds": "[0,0][1080,2400]",
+      "suggested": {"type": "xpath", "value": "//*"}
+    }
+  ]
+}
+```
+
+---
+
+## 12. 应用管理（APK）
+
+### GET /api/apks
+
+列出所有已上传的 APK。
+
+**响应**：
+```json
+{
+  "ok": true,
+  "apks": [
+    {
+      "id": "abc123",
+      "display_name": "抖音",
+      "package_name": "com.ss.android.ugc.aweme",
+      "version_name": "25.0.0",
+      "version_code": 2500,
+      "size": 104857600,
+      "upload_time": "2026-08-08 10:00:00"
+    }
+  ]
+}
+```
+
+（权限：应用管理）
+
+上传 APK 文件（自动解析包名/版本/应用名）。
+
+**请求**（multipart/form-data）：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| file | file | APK 文件 |
+
+**响应**：
+```json
+{"ok": true, "apk": {"...": "..."}, "msg": "上传成功: 抖音"}
+```
+
+（权限：应用管理）
+
+删除 APK 文件和记录。
+
+（权限：应用管理）
+
+批量安装 APK 到指定设备。
+
+**请求**（JSON）：
+```json
+{"apk_id": "abc123", "serials": ["192.168.1.100:5555", "192.168.1.101:5555"]}
+```
+
+**响应**：
+```json
+{"ok": true, "msg": "开始安装 抖音 到 2 台设备"}
+```
+
+### GET /api/apks/install/devices
+
+可安装设备列表：设备池在线设备（标记 `pool`）+ 本机 adb 设备（**含 USB 有线连接**，serial 无冒号标记 `usb`）。
+安装弹窗用此列表，USB 设备安装时跳过 adb connect 直接安装。
+
+**响应**：
+```json
+{"ok": true, "devices": [
+  {"serial": "100.100.10.11:5555", "model": "22120RN86C", "source": "stf"},
+  {"serial": "ZY322ABCDEF", "model": "", "source": "usb"}
+]}
+```
+
+### GET /api/apks/install/status
+
+获取安装任务实时状态。
+
+**响应**：
+```json
+{
+  "ok": true,
+  "status": {
+    "apk_name": "抖音",
+    "finished": false,
+    "total": 2,
+    "success": 1,
+    "failed": 0,
+    "skipped": 0,
+    "installing": 1,
+    "pending": 0,
+    "items": {
+      "192.168.1.100:5555": {"name": "Pixel 6", "status": "success", "msg": "安装成功(已验证)"},
+      "192.168.1.101:5555": {"name": "Pixel 7", "status": "installing", "msg": "正在安装..."}
+    }
+  }
+}
+```
+
+---
+
+## 13. 维护 / 工具（仅管理员）
+
+以下接口都**仅管理员可用**（普通用户即使有业务权限也访问不了，返回 403）。
+设备池管理、远程看屏、adb 终端等集中在"工具"页（页内子分栏）。
+
+### GET /api/devices/pool
+
+设备池清单（SQLite devices 表），含实时在线状态。**权限**：`devices`。
+
+**响应**：
+```json
+{"ok": true, "devices": [
+  {"serial": "100.100.10.20:5555", "name": "", "model": "22120RN86C",
+   "enabled": true, "online": true, "note": "", "created_at": "2026-08-17 11:10"}
+]}
+```
+
+### POST /api/devices/pool/add
+
+添加/更新设备（upsert）。**权限**：`devices`。
+**请求**（JSON）：`{"serial": "100.100.10.20:5555", "name": "备注", "note": ""}`
+IP:5555 设备添加后立即尝试 adb connect，并后台采集型号（getprop ro.product.model）。
+
+### POST /api/devices/pool/toggle
+
+启用/停用设备（停用后不参与任务调度）。**权限**：`devices`。
+**请求**（JSON）：`{"serial": "...", "enabled": false}`
+
+### POST /api/devices/pool/remove
+
+从设备池删除（不再参与调度，不影响设备本身）。**权限**：`devices`。
+**请求**（JSON）：`{"serial": "..."}`
+
+### POST /api/devices/pool/reconnect
+
+一键重连：并发 adb connect 池内全部 IP:5555 设备（后台执行），完成后自动批量刷新型号。**权限**：`devices`。
+
+### POST /api/devices/pool/refresh_models
+
+批量采集池内在线设备的型号（后台执行）。**权限**：`devices`。
+
+### GET /api/screen/stream
+
+远程看屏：MJPEG 实时画面流（`multipart/x-mixed-replace`）。**权限**：`devices`。
+
+`?serial=xxx` 指定设备；浏览器 `<img src>` 直接渲染，客户端断开自动停止。数据源 u2（atx-agent minicap，约 3-6 帧/秒）。
+
+### GET /api/screen/thumb
+
+大屏缩略图：单张 JPEG（360px 宽，质量 55）。**权限**：`devices`。
+
+`?serial=xxx` 指定设备。监控大屏按设备每 ~2.5s 轮询一帧（页面不可见时暂停）；
+一次性请求（非流），与任务并发安全（与任务截图同走 u2 minicap）。
+
+### GET /wall
+
+监控大屏页面（全屏深色控制室风格，登录后可访问）：设备卡片网格（缩略图/型号/
+状态/当前动作/进度）、顶部统计与时钟；状态每 5s 刷新、缩略图每 2.5s 轮询。
+20 台设备整体开销约 0.2 核 CPU + 100KB/s 带宽，普通电脑无压力。
+
+### POST /api/screen/tap
+
+点击设备屏幕。**权限**：`devices`。
+**请求**（JSON）：`{"serial": "...", "x": 360, "y": 800}`（设备原生分辨率坐标）
+
+### POST /api/screen/swipe
+
+滑动。**请求**（JSON）：`{"serial": "...", "x1": 360, "y1": 1200, "x2": 360, "y2": 600, "duration": 0.2}`
+
+### POST /api/screen/key
+
+按键。**请求**（JSON）：`{"serial": "...", "key": "back"}`。
+支持：back/home/recent/menu/power/volume_up/volume_down/enter/delete/search/camera
+
+### POST /api/screen/text
+
+输入文字（需焦点在输入框）。**请求**（JSON）：`{"serial": "...", "text": "你好"}`
+
+### POST /api/device/screen_all
+
+批量亮屏/息屏（并发）。**权限**：`devices`。
+
+**请求**（JSON）：
+```json
+{"mode": "on", "serials": ["100.100.10.11:5555"]}
+```
+`serials` 可选：指定设备（离线自动过滤）；不带则作用于全部在线设备。息屏会中断运行中的任务，前端有确认提示。
+
+### GET /api/adb/devices
+
+维护终端设备列表：本地 adb 已连接（含 offline）+ 设备池已配置设备（标记 `pool`）。
+供终端设备选择器使用——选中后前端自动附加 `-s <serial>`。
+
+**响应**：
+```json
+{"ok": true, "devices": [
+  {"serial": "100.100.10.11:5555", "state": "device"},
+  {"serial": "100.100.10.13:5555", "state": "offline"},
+  {"serial": "100.100.10.12:5555", "state": "stf"}
+]}
+```
+
+### POST /api/adb/cmd
+
+adb 远程终端：用平台 adb 二进制执行任意 adb 命令（20s 超时）。
+
+**请求**（JSON）：
+```json
+{"cmd": "adb -s 100.100.10.11:5555 shell ls /sdcard"}
+```
+（开头的 `adb` 前缀可省略）
+
+**安全红线**：包含 `kill-server` / `disconnect` 的命令直接拒绝（400）——会断开共享的 adb transport，导致全部设备连接重建。
+
+**响应**：
+```json
+{"ok": true, "stdout": "...", "stderr": "", "code": 0}
+```
+
+---
+
+## 14. 步骤测试（仅管理员可触发，需"设备控制"权限）
+
+### POST /api/steps/test
+
+在指定设备上单步试执行（步骤编辑器"测试此步骤"按钮），验证选择器是否命中。
+只读连接（adb connect + u2），与运行中任务互不干扰。
+
+**请求**（JSON）：
+```json
+{
+  "serial": "100.100.10.11:5555",
+  "step": {"type": "click", "label": "测试", "params": {"selector_type": "xpath", "selector_value": "//*[@resource-id=\"x\"]"}}
+}
+```
+
+**响应**：
+```json
+{"ok": true, "msg": "步骤已执行（测试）", "result": "命中"}
+```
+`result`：`命中` / `未找到` / `已执行`（无选择器命中语义的步骤）。
+无"设备控制"权限返回 403。
+
+---
+
+## 15. Tailscale 管理（仅管理员）
+
+工具页"Tailscale 管理"子分栏，调用 Tailscale 官方 API v2。所有接口仅管理员可用。
+前置：`.env` 配置 `TAILSCALE_API_KEY`（Settings → API Access Tokens）与
+`TAILSCALE_TAILNET`（tailnet 名，个人账号一般为邮箱前缀）；未配置返回 502 并附提示。
+设备 IP 由 tailnet 分配，API 不可修改，列表只读展示。
+
+### GET /api/tailscale/status
+
+配置状态检查。
+
+**响应**：
+```json
+{"ok": true, "configured": false, "hint": "TAILSCALE_API_KEY（...）；TAILSCALE_TAILNET（...）"}
+```
+
+### GET /api/tailscale/devices
+
+列出 tailnet 全部设备。
+
+**响应**：
+```json
+{"ok": true, "devices": [
+  {"id": "d1", "name": "dev-a", "hostname": "dev-a", "os": "linux",
+   "addresses": ["100.100.10.11"], "authorized": true,
+   "key_expiry_disabled": false, "online": true, "last_seen": "...", "tags": []}
+]}
+```
+
+### POST /api/tailscale/devices/:device_id
+
+更新设备（按传入字段分发到 Tailscale 专属端点，`POST /device/{id}` 本身是 405）：
+`name` → `/name` 显示名；`authorized` → `/authorized` 授权开关；
+`key_expiry_disabled` → `/key`（true=密钥永不过期，即关闭设备密钥验证，恢复后按原定过期时间执行）。
+
+**请求**（JSON）：
+```json
+{"key_expiry_disabled": true}
+```
+
+### POST /api/tailscale/devices/:device_id/ip
+
+设置设备的 Tailscale IPv4 地址（未公开端点，实测可用）。
+
+**请求**（JSON）：
+```json
+{"ipv4": "100.100.10.16"}
+```
+
+⚠ 改 IP 会断开设备当前 tailscale 会话；平台设备池 serial 随之变化，需同步更新设备池/分组/任务目标。
+
+### DELETE /api/tailscale/devices/:device_id
+
+从 tailnet 移除设备（下次上线需重新授权）。
+
+### POST /api/tailscale/authkey
+
+生成设备接入 auth key（key 只返回一次）。
+
+**请求**（JSON）：
+```json
+{"description": "新设备接入", "reusable": false, "ephemeral": false,
+ "preauthorized": true, "expiry_seconds": 3600}
+```
+
+**响应**：
+```json
+{"ok": true, "key": "tskey-auth-...", "id": "k1", "expires": "2026-08-11T01:00:00Z"}
+```
+
+---
+
+## 16. 工具（仅管理员）
+
+工具页（剪贴板注入 / 应用版本管理 / 设备池管理）接口，均仅管理员可用。
+
+### POST /api/tools/clipboard/set
+
+剪贴板注入：把指定文字写入一台或多台设备的剪贴板。
+
+**请求**（JSON）：
+```json
+{"serials": ["100.100.10.11:5555", "0123456789ABCDEF"], "text": "要注入的文字"}
+```
+设备来源与维护终端一致（本地 adb 含 USB + 设备池）。
+实现：u2 `jsonrpc.setClipboard`（实测 `cmd clipboard` 在 MIUI 上不存在），支持中文/引号/换行；
+IP 设备先 adb connect（已连接跳过，绝不 disconnect），USB 设备首次自动推送 atx-agent。
+
+**响应**：
+```json
+{"ok": true, "results": {"100.100.10.11:5555": {"ok": true, "msg": "已注入"}},
+ "ok_count": 1, "fail_count": 0, "error": null}
+```
+
+### POST /api/tools/appver
+
+应用版本管理：查询所有设备上指定包名的安装情况与版本号（并发 10 台）。
+
+**请求**（JSON）：
+```json
+{"pkg": "com.ss.android.ugc.aweme"}
+```
+
+**响应**：
+```json
+{"ok": true, "total": 8, "fail": 0,
+ "results": {"100.100.10.11:5555": {"installed": true, "version_name": "28.5.0", "version_code": "280500"}}}
+```
+未安装返回 `installed: false`；查询失败的设备带 `error` 字段。

doc/ARCHITECTURE.md

@@ -0,0 +1,376 @@
+# 架构详解
+
+本文面向想深入理解 `platform-tools` 内部设计的开发者。如果你只想使用，看 [README.md](file:///d:/platform-tools/README.md) 即可。
+
+---
+
+## 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/` | 实用脚本 |
+
+### 分层原则
+
+- **任务自包含**：每个任务的参数、Worker、操作都放在 `tasks/<app>/` 下，不污染全局
+- **核心不依赖任务**：`core/` 不 import `tasks/`，任务通过注册机制接入
+- **配置最小化**：`config.py` 只放基础设施配置，任务参数在各自 `task.py` 顶部
+
+---
+
+## 2. 数据流
+
+```
+┌──────────────┐  创建/编辑任务    ┌─────────────┐  分发 worker   ┌──────────────┐
+│ 单页应用前端  │ ───────────────► │ TaskManager │ ─────────────► │  Worker(设备) │
+│ (monitor.html│                  └─────────────┘                └──────────────┘
+│  fetch+DOM)  │                         ▲                            │
+└──────────────┘                         │ 状态/心跳                    │ u2 操作
+       │                                 │                            ▼
+       │ JSON API                        │                   ┌─────────────────┐
+       ▼                          ┌──────────────┐           │ 设备 adb        │
+┌──────────────┐                  │  看门狗监控   │           │ (IP:5555 直连  │
+│  web/ 蓝图包  │                  └──────────────┘           │  / USB 远程)   │
+│  (Flask API) │                                            └─────────────────┘
+└──────────────┘
+       │
+       ▼
+┌──────────────┐
+│ data/users.db│  SQLite 持久化（用户/分组/任务/设备池/自定义动作/APK记录）
+└──────────────┘
+```
+
+### 任务执行流程
+
+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 状态
+
+---
+
+## 3. 核心模块详解
+
+### 3.1 DevicePool（`core/device_pool.py`）
+
+设备池（已摘除 OpenSTF）：SQLite `devices` 表 = 设备清单，本机 adb = 在线状态。
+
+**关键设计**：
+- `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 红线）
+
+### 3.2 STFDevice + BaseWorker（`core/device_worker.py`）
+
+**STFDevice** — 单设备生命周期管理：
+- `acquire()`：IP:5555 直连 adb connect；USB（serial 无冒号）校验 220 远程 adb server 可见性
+- `release()`：无操作（不 disconnect，红线）
+- 互斥由 TaskManager `_running` 保证，设备池负责在线判断
+
+**BaseWorker** — 通用 Worker 基类（继承 threading.Thread）：
+
+```
+run() 主循环（不要重写）：
+  1. acquire 设备
+  2. u2.connect（30s 超时保护）
+  3. setup(d)        ← 子类可选钩子
+  4. run_task(d)     ← 子类必须实现
+  5. teardown(d)     ← 子类可选钩子
+  6. finally: release 设备
+```
+
+**超时保护**：
+- `u2.connect()` 用 `ThreadPoolExecutor + 30s 超时`，防止 atx-agent 无响应永久 hang
+- `d.info` 用 `ThreadPoolExecutor + 10s 超时`
+
+**心跳看门狗**（`_Watchdog`）：
+- 后台线程，每 30 秒扫描一次
+- Worker 超过 120 秒无心跳 → 标记 `error`
+- 防止设备被占用却不干活
+
+**全局状态注册表**（`_WORKERS`）：
+- `serial -> status dict`，线程安全（`_WORKERS_LOCK`）
+- 供 `web_server` 读取实时状态，前端通过 `/api/status` 展示
+
+### 3.3 TaskManager（`core/task_manager.py`）
+
+统一管理：任务类型注册、设备分组、任务计划、定时调度、重试、持久化。
+
+**核心组成**：
+
+| 组件 | 说明 |
+|------|------|
+| `scheduler` | APScheduler BackgroundScheduler，cron 触发任务 |
+| `groups` | 设备分组（内存业务对象，持久化到 SQLite） |
+| `jobs` | 任务计划（内存业务对象，持久化到 SQLite） |
+| `_running` | 运行中的 worker（serial -> worker 信息） |
+| `_stop_requested` | 用户请求停止的 serial 集合（阻止后续重试） |
+| `_fg_scanner` | 前台 App 扫描器（不打扰设备） |
+
+**调度模式**：
+- `once`：不注册 cron，手动执行
+- `cron`：注册启动 cron，到点启动所有目标设备
+- `cron_stop`：注册启动 cron + 停止 cron，到点停止本任务 worker
+
+**重试策略**：
+- `DeviceOfflineError`：立即放弃，不重试（设备掉线短时间不会自愈）
+- 其他异常：按 `retry.max_attempts` 重试，间隔 `retry.delay`
+- 临时错误（端口耗尽）：退避 max(delay, 120s)
+- 用户停止：加入 `_stop_requested`，阻止任何后续重试
+
+**并发控制**：同一 serial 同时只允许一个 worker，避免冲突。
+
+**状态缓存**：`get_status()` 带 5 秒缓存，避免每次 /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 文件元信息 |
+
+**数据库初始化**（`init_db`）：
+- 创建所有表
+- 首次启动创建默认管理员 `admin/admin123`
+- 自动迁移旧 `groups.json` / `jobs.json` 到 SQLite（迁移后归档为 `.migrated`）
+- 版本化 schema 迁移（`SCHEMA_MIGRATIONS`）：结构变更必须追加迁移条目，`create_all` 只建新表不加列
+
+### 权限模型
+
+- `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，权限强制在后端**；新增路由时按"写操作必须带权限装饰器"的约定
+
+### 3.7 APK 管理（`core/apk_manager.py`）
+
+APK 上传/解析/批量安装。
+
+**设备连接策略（直连）**：
+- 直接 `adb connect serial`（serial 是 IP:5555）
+- 不经过占用/释放（单实例互斥由调度器内存锁保证）
+- 安装后不主动 disconnect（共享 adb transport 红线）
+
+**安装流程**：
+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 元素树（扁平化列表） |
+
+元素树解析：递归提取每个节点的 `resource-id/text/content-desc/class/bounds` 等属性，并推荐最佳选择器（优先 xpath）。
+
+### 3.9 屏幕 OCR（`core/ocr.py`）
+
+条件判断的 `ocr` 选择器实现：截屏 → RapidOCR（ONNX 推理，中英文模型随包内置）→ 关键词匹配 → 返回文字中心像素坐标（与 u2 `d.click` 一致）。
+
+- **跨平台**（Windows/Linux/macOS），依赖 `rapidocr_onnxruntime`；服务器无显示器环境建议将 opencv-python 换成 opencv-python-headless
+- 引擎懒加载单例 + 并发加锁（识别约 0.2-0.5s/次）
+- 返回坐标约定：像素、原点左上
+
+### 3.10 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） |
+
+`web_server.py` 只保留：app 创建、数据库初始化、蓝图注册、uiautodev 生命周期、启动（193 行）。
+
+---
+
+## 4. 任务系统设计
+
+### 4.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
+```
+
+`@register_task` 装饰器将 Task 类注册到全局 `_TASK_TYPES` 字典，key 为 `task_type` 字符串。
+
+### 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`。
+
+---
+
+## 5. 前端设计
+
+### 5.1 单页应用
+
+`templates/admin/monitor.html` 是纯 HTML+CSS+JS 单页应用，无框架依赖。
+
+- **Tab 切换**：5 个 Tab（监控/任务/分组/日志/用户），纯 DOM 操作
+- **数据获取**：`fetch()` 调 JSON API，5 秒轮询 `/api/status`
+- **状态渲染**：设备表格、任务卡片、进度条、徽章，纯 DOM 操作
+
+### 5.2 步骤编辑器
+
+`generic_steps` 任务的步骤编辑器（任务弹窗已加宽到 1000px）：
+- 左侧操作库（拖拽源，按 交互操作/屏幕与App/流程控制 分组）
+- 中间画布（步骤卡片列表，HTML5 Drag API 排序 + 跨层级嵌套：循环套循环、动作组）
+- 每个步骤卡片可展开参数表单
+- 选择器字段旁有"抓取元素"按钮（独立模态框）
+- **容器步骤**（loop/group/if_el）：卡片内嵌子步骤容器接收拖入；if_el 有"✅找到时/❌未找到时"两个独立分支容器，分支可嵌套任意步骤
+- **条件判断**（if_el）：选择器支持 xpath 等 UI 树选择器或 OCR识别（`core/ocr.py`，截屏匹配图片/画布文字，命中可自动点击）
+- 所有递归操作（选择打包、存自定义动作、校验、防循环自套）统一遍历 children/then/else 三个子数组
+
+### 5.3 页内子分栏
+
+任务/工具 Tab 用通用 `showSubTab(tabId, name)` 实现页内子分栏：每个子分栏一个 `.sub-panel`，
+`_activeSubs` 记住各 Tab 上次选中的子分栏。工具 Tab 集中了全部管理工具（剪贴板注入/adb 终端/
+Tailscale/应用管理/应用版本/已装应用/STF 设备管理），维护 Tab 仅保留 STF 服务。
+
+### 5.4 元素抓取模态框
+
+独立的第二层模态框（`el-picker-overlay`，z-index 1100），不影响任务编辑窗口：
+1. 选择设备 → 2. 加载截图 + 元素树 → 3. 点击元素/边界框 → 4. 回填选择器
+
+---
+
+## 6. 关键设计决策
+
+### 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 恢复后再启用。
+
+---
+
+## 7. 线程模型
+
+```
+主线程（Flask）
+  ├── HTTP 请求处理（threaded=True，每请求一线程）
+  ├── APScheduler 线程（cron 触发）
+  ├── 看门狗线程（_Watchdog，30s 间隔）
+  ├── uiautodev 子进程
+  └── Worker 线程（每台设备一个）
+        ├── _run_with_retry 线程（重试循环）
+        └── BaseWorker 线程（设备生命周期 + run_task）
+```
+
+**线程安全**：
+- `_WORKERS_LOCK`：保护全局 worker 状态字典
+- `_ADB_LOCK`：串行化所有 adb 调用
+- `TaskManager._lock`：保护运行中任务字典
+- `_ForegroundScanner._cache_lock`：保护前台 App 缓存

doc/DEPLOY.md

@@ -0,0 +1,324 @@
+# 部署指南
+
+本文介绍如何从零部署 `platform-tools` 设备自动化后台。
+
+---
+
+## 1. 环境准备
+
+### 1.1 Python 环境
+
+- **Python 3.10+**（推荐 3.12）
+- 安装后确认 `python --version` 和 `pip` 可用
+
+```bash
+# 验证
+python --version    # 应输出 3.10+
+pip --version
+```
+
+### 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 设备准备
+
+设备需满足：
+- 开启 **USB 调试**（设置 → 开发者选项）
+- 转网络调试：USB 连上后 `adb -s <serial> tcpip 5555`（管理后台「adb 终端」有一键快捷命令）
+- 设备加入 Tailscale（同一账号，获得 100.100.10.x IP）
+- 在「工具 → 设备池管理」添加 `IP:5555`（自动尝试连接，任务运行时 u2 自动推送 atx-agent）
+
+---
+
+## 2. 安装部署
+
+### 2.1 获取代码
+
+```bash
+# 方式一：直接拷贝项目目录
+# 方式二：解压打包文件（python scripts/pack.py 生成的 zip）
+```
+
+### 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 端口说明
+
+| 端口 | 服务 | 说明 |
+|------|------|------|
+| 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/`
+
+---
+
+## 5. 更新升级
+
+### 5.1 代码更新
+
+```bash
+# 1. 停止服务
+# 2. 替换代码文件（或解压新的 zip）
+# 3. 重新安装依赖（如有新增）
+pip install -r requirements.txt
+# 4. 启动服务
+python web_server.py
+```
+
+### 5.2 数据库迁移
+
+- SQLite 表结构变化时，`init_db()` 会自动 `db.create_all()` 创建新表
+- 旧 `groups.json` / `jobs.json` 首次启动自动迁移到 SQLite
+- 迁移后 JSON 文件归档为 `.migrated`（保留备份，不再迁移）
+
+### 5.3 注意事项
+
+- **修改 `core/` 目录下的文件后必须重启 web_server**（`debug=False` 不热重载）
+- **修改 `templates/` 下的 HTML 文件**：Flask 模板默认不缓存，但建议重启确保生效
+- **修改 `tasks/` 下的文件后必须重启**（任务注册在启动时完成）
+
+---
+
+## 6. 故障排查
+
+### 6.1 启动失败
+
+| 现象 | 原因 | 解决 |
+|------|------|------|
+| `ModuleNotFoundError: No module named 'flask'` | 依赖未安装 | `pip install -r requirements.txt` |
+| `WinError 10013` | 端口被排除/权限不足 | 改端口或用管理员运行 |
+| `WinError 10048` | 端口被占用 | 改端口或杀占用进程 |
+| STF 获取设备列表失败 | STF 地址/token 错误 | 检查 `config.py` 的 `STF_URL` 和 `STF_TOKEN` |
+
+### 6.2 设备连接失败
+
+| 现象 | 原因 | 解决 |
+|------|------|------|
+| `DeviceOfflineError` | 设备掉线/STF provider 卡死 | 检查设备网络/STF 状态 |
+| `u2.connect 超时` | atx-agent 无响应 | 重启设备/重新推送 atx-agent |
+| `adb connect failed` | 设备网络不通/端口未开放 | 检查设备 IP 和 5555 端口 |
+| STF 设备显示离线 | STF 状态缓存 | 用"扫描前台App"复测 |
+
+### 6.3 任务不执行
+
+| 现象 | 原因 | 解决 |
+|------|------|------|
+| 任务列表有任务但不执行 | 任务未启用 / cron 未到点 | 检查 `enabled` 和 `schedule` |
+| 立即执行无反应 | 无可用设备 | 检查设备池是否有空闲设备 |
+| worker 状态 error | 查看日志的 `last_error` | 查看 `logs/core.log` 和 `logs/task.log` |
+| 看门狗误杀 | 长操作未心跳 | 在长循环内加 `self.heartbeat()` |
+
+### 6.4 日志查看
+
+```bash
+# 查看核心日志
+# 方式一：Web 后台"日志"Tab
+# 方式二：直接看文件
+# logs/core.log   — STF/adb/worker/task_manager
+# logs/task.log   — 任务执行
+# logs/web.log    — Web 请求
+# logs/action.log — 操作执行
+```

doc/DEVELOPMENT.md

@@ -0,0 +1,220 @@
+# 开发手册（DEVELOPMENT）
+
+面向本项目开发者：开发流程、git 工作流、环境说明、技术红线、本地开发、常见开发任务。
+
+---
+
+## 1. 开发流程与 git 工作流
+
+### 1.1 分支策略
+
+| 分支 | 用途 |
+|------|------|
+| `dev` | **开发分支**，所有新功能/修复都在这里开发 |
+| `main` | **生产分支**（主分支），只放已确认的稳定版本 |
+
+生产环境 = 部署机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（python-app 容器运行 `web_server.py`）。
+
+### 1.2 git 操作铁律（重要）
+
+**所有 git 操作都必须先经项目负责人明确确认后才能执行**，包括但不限于：
+
+- `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
+```
+
+> 不允许"开发完顺手就 commit/push"。即使是一次性小改动，也要先确认。
+
+---
+
+## 2. 环境说明
+
+| 环境 | 位置 | 说明 |
+|------|------|------|
+| 开发机 | 本机（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 自动拉起） |
+
+### 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 清单，自动连接 + 型号采集）
+
+---
+
+## 3. 技术红线（开发限制）—— 违反会打断共享 adb transport，需人工恢复
+
+这些是踩过坑后总结的，**任何修改都不能引入**。违反任何一条都会导致设备连接被全部重建（历史原因：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 首次安装
+
+```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
+```
+
+### 4.2 启动
+
+```bash
+.venv/bin/python web_server.py
+# 访问 http://localhost:18050/  账号 admin/admin123
+```
+
+启动日志看到以下即成功：
+```
+[INFO] [core.worker] 心跳看门狗已启动
+[INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
+[INFO] [web] 启动服务: http://localhost:18050/
+```
+
+### 4.3 测试
+
+- **后端逻辑**：直接 `.venv/bin/python -c "..."` 调用（如 `tasks/`、`core/` 的函数）
+- **前端 UI**：Playwright（系统 `python3` 已装），脚本示例见下
+- **浏览器冒烟**：切 6 个 tab、开任务编辑器，确认无 JS 错误
+
+```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()
+```
+
+### 4.4 常用调试
+
+- **看日志**：`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`
+
+---
+
+## 5. 常见开发任务
+
+### 5.1 新增 App 任务
+
+参照 `tasks/douyin/` 结构，详见 **[doc/TASK_DEV.md](TASK_DEV.md)**（6 步模板）。
+
+```
+tasks/<app>/
+  __init__.py     # from . import task
+  task.py         # DEFAULT_PARAMS + Worker + @register_task
+  actions/        # 专属操作（可选）
+```
+
+### 5.2 新增专属操作
+
+在 `tasks/<app>/actions/` 建 `.py`，继承 `BaseAction` + `@register_action(ACTIONS)`，在 `__init__.py` import。
+
+### 5.3 修改前端
+
+| 文件 | 内容 |
+|------|------|
+| `templates/admin/monitor.html` | HTML 结构 + CSS + `<script src>` 引用 |
+| `static/admin/monitor.js` | 全部前端 JS |
+
+改完**强刷浏览器**（Cmd/Ctrl+Shift+R），必要时重启 web_server。
+
+### 5.4 新增 API
+
+在 `web_server.py` 加 Flask 路由，更新 **[doc/API.md](API.md)**。
+
+### 5.5 新增数据库字段/表
+
+- 模型改 `core/models.py`，首次建表用 `create_all()`
+- **已有数据的老库**：在 `core/models.py` 的 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）
+
+---
+
+## 6. 发布流程
+
+详见 **[doc/DEPLOY.md](DEPLOY.md)**。摘要：
+
+1. dev 开发测试完成
+2. 负责人确认 → 合并到 main
+3. 负责人确认 → 生产 220 `git pull`
+4. 重启 python-app 容器生效
+
+**发布前检查**：生产容器 adb key、依赖、数据库迁移。
+
+---
+
+## 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) | 部署指南（环境、生产、故障排查） |

doc/STF_REMOVAL.md

@@ -0,0 +1,154 @@
+# 摘除 STF 迁移计划
+
+背景：全舰队设备为 Tailscale IP:5555 直连（adb key 沿用 STF 的），单实例部署。
+STF 当前仅提供：occupy/release 互斥、present+ready 健康信号、设备池清单（与
+220 的 connect_devices.sh 双维护）、remoteConnect 桥接（IP:port 已禁用）、网页看屏。
+任务本体跑 uiautomator2（atx-agent），与 STF agent（jp.co.cyberagent.stf）无关。
+
+摘除收益：告别 agent 安装死锁（MIUI 弹窗）、STF 容器重启风险、occupy 冲突悬空；
+调度直接基于 adb 真实现状。风险点：多实例互斥（当前单实例无此需求，见阶段 3）。
+
+## 已确认的决策（2026-08-17）
+
+1. **设备清单放本地 SQLite**（data/users.db 新增 devices 表），220 的 connect_devices.sh
+   退役（其"每 5 分钟补连"职责由平台定时器 + SSH 兜底接管，或直接依赖 adb 重试）
+2. **USB 有线设备保留支持**——当前舰队 0 台 USB（全 IP:5555），但能力要保留。
+   实施中发现 **220 的 adb 容器是 host 网络模式、5037 已监听所有网卡（含 Tailscale
+   100.100.10.1），无需改动 220 任何配置**。平台用 `adb -H 100.100.10.1 -P 5037`
+   和 `adbutils.AdbClient(host=..., port=5037)`（u2 底层）驱动远端 USB 设备；
+   本机 USB 设备照旧走本地 adb。已验证（阶段 2 完成）
+3. **网页远程看屏**——原计划 ws-scrcpy **不在 npm 分发**（仅 GitHub，国内下载不可靠），
+   改**自建**：MJPEG 流（u2/atx-agent minicap 截图，~5fps，实测 0.19s/帧）+ u2 触控
+   （tap/swipe/key/text），管理页新子分栏，零新依赖（阶段 2 完成）
+
+---
+
+## 迁移难度与程度评估（2026-08-17）
+
+### 代码量
+
+| 项 | 量级 |
+|---|---|
+| 删除 `core/stf_client.py` 及引用 | ~250 行 |
+| 新增 `core/device_pool.py`（清单+在线状态） | ~150 行 |
+| 新增 devices 表 CRUD（复用现有 SQLite 基建） | ~120 行 |
+| 修改 `task_manager`（resolve_serials/调度） | ~120 行 |
+| 重写 `device_worker.STFDevice`（去 occupy/release） | ~80 行 |
+| 修改 `web_server` 约 8 处调用点 | ~60 行 |
+| 改造 `stf_device_mgmt`（SSH 脚本 → SQLite 管理） | ~100 行 |
+| 前端 6 个文件文案/组件 | ~80 行 |
+
+净效果：**-600 行 / +400 行 / 改 ~300 行**，集中在 task_manager 与 device_worker 两个核心文件。
+
+### 分项难度（单人）
+
+| 模块 | 难度 | 估算 | 关键点 |
+|---|---|---|---|
+| 设备池 SQLite + device_pool | 低 | 0.5-1 天 | 表结构 + CRUD + 管理页改数据源 |
+| 调度替换 | 中 | 1-2 天 | 内存锁已有（`_running[serial]`），换数据源 + 对照验证 |
+| web_server 调用点 | 低 | 0.5 天 | 8 处机械替换 |
+| USB 支持 | 中 | 1 天 | 220 容器发端口 + adb_helper 支持 `-H/-P` + u2 远程 server；**需一台真机验证** |
+| 网页看屏（ws-scrcpy） | 中 | 0.5-1 天 | 独立 Node 服务 + 内嵌页 + 认证联动 |
+| 界面清理 | 低 | 0.5 天 | 文案/按钮/列 |
+| 回归验证 | 中 | 1 天 | 调度/抢占/重试/离线跳过/亮屏/剪贴板/终端/看屏 |
+
+**总计约 4-6 人日**，分 4 个 commit 阶段，每阶段可独立回滚。
+
+### 风险
+
+- **中**：USB 真机方案当前无设备可验，落地时需借一台 USB 设备
+- **低**：离线跳过判定语义变化（STF 状态 → adb 状态），个别边界行为可能微变，需对照
+- **低**：唯一动 220 的地方 = adb 容器发布 5037 端口（一次性）
+- **低**：ws-scrcpy 是新增 Node 依赖，需评估其维护性与内存占用（可先试用再定）
+
+### 实施顺序（调整后）
+
+- **阶段 0**：SQLite 设备表 + `core/device_pool.py`（纯新增，STF 照常跑）
+- **阶段 1**：调度/生命周期替换（STF 保留运行对照验证）
+- **阶段 2**：USB 远程 adb server 打通 + ws-scrcpy 看屏部署
+- **阶段 3**：界面清理 + 220 停 STF 容器（`docker stop` 不删，可回滚）
+
+---
+
+## 阶段 0：新建设备池模块（纯新增，不改行为）
+
+新建 `core/device_pool.py` + devices 表（data/users.db）：
+
+- devices 表：serial（主键）、name、enabled、note、created_at；管理页增删改
+- `list_configured()` — 读 SQLite devices 表（取代 SSH 读 220 脚本）
+- `list_online()` — 本机 `adb devices` 中 state=device 的设备（实时）
+- `is_online(serial)` — 在 list_online 中；可选 `adb -s get-state` 兜底（带超时）
+- `list_ready()` — list_configured 与 list_online 的交集（取代 STF list_free_devices）
+- 全模块不 connect/不 kill-server/disconnect，遵守既有红线
+- 迁移脚本：现有 8 台设备从 STF 池导入 devices 表
+
+产出：`core/device_pool.py` + `doc/ARCHITECTURE.md` 设备章节初稿 + 数据迁移脚本。
+
+## 阶段 1：替换调度与生命周期（STF 保留运行，可对照验证）
+
+| 位置 | 现状 | 改为 |
+|---|---|---|
+| `task_manager.resolve_serials` (145-183) | `stf.list_free_devices()` / `list_all_devices()` | `device_pool.list_ready()`；preempt 模式 = 全部 list_online |
+| `resolve_serials` skip_offline 过滤 (166-183) | STF present/ready 判定 | `device_pool.is_online()`；跳过原因文案"离线/未连接" |
+| `device_worker.STFDevice.acquire` (45-70) | `stf.occupy()` + 直连/桥接 | 去掉 occupy（互斥由 `_running[serial]` 负责）；**USB 桥接保留到阶段 2**（避免迁移期 USB 断档，阶段 2 换成 220 adb server）；保留 adb_connect 重试 + 2s 等待 |
+| `STFDevice.release` (78-93) | `stf.release()` | 置空（仅保留 USB 隧道断开） |
+| `STFDevice._pick_free` (72-76) | `list_free_devices` | `device_pool.list_ready()` |
+| `_ForegroundScanner` (234-386) | `list_all_devices` / `list_my_devices` / remote_connect | `device_pool.list_online()`；桥接分支删除 |
+| `web_server.api_device_screen_all` (646) | STF present 列表 | `device_pool.list_online()` |
+| `web_server` 设备列表 (924 / 1011 / 1079) | STF 池合并 | SQLite devices 表 + 本地 adb（`_merged_device_list` 改数据源，保留 stf_not_ready 状态的等价物"未连接"） |
+| `web_server.api_release` (740) / 启动清理 (1581) | release_all_mine | 删除或改为清理本实例 `_running` 状态（重启本就清零） |
+
+验证清单（阶段 1 完成后全跑一遍）：
+- [ ] 任务调度（serial/group/all 三种模式）+ 抢占/归还 + 重试 + 离线跳过
+- [ ] 一键亮屏/息屏、剪贴板注入、应用版本查询、维护终端设备列表
+- [ ] 前台 App 扫描
+- [ ] 对照 STF 状态确认无行为差异
+
+## 阶段 2：USB 打通 + 网页看屏（阶段 1 稳定运行 ≥ 3 天后）
+
+- **USB 远程 adb server**：
+  - 220 侧一次性改动：adb 容器发布 5037 端口（`docker run -p 5037:5037` 或 iptables），
+    Tailscale 可达
+  - `core/adb_helper._adb` 支持 `-H <220-tailscale-ip> -P 5037`（仅 USB 序列号设备）
+  - u2 连接：USB 设备走 `adbutils.Adb(host=220_ip, port=5037)` → `u2.Device(dev)`
+    （已验证 u2 3.7.0 底层 adbutils 支持远程 adb server）
+  - 本机 USB 设备照旧走本地 adb，零改动
+  - 需要一台真机 USB 设备验证
+- **网页看屏（ws-scrcpy）**：
+  - 平台机部署 ws-scrcpy（Node 服务，WebRTC 低延迟流 + 触控），本机 adb 为数据源
+  - 管理员页面新增「远程看屏」入口，iframe 内嵌；登录态复用（ws-scrcpy 自身鉴权
+    走 token 或仅内网/Tailscale 暴露）
+  - 备选方案（若 ws-scrcpy 试用不达标）：自建 minicap JPEG 流 + u2 触控注入（2-3 天）
+
+## 阶段 3：界面清理 + STF 停用（已完成代码部分，2026-08-18）
+
+✅ 已完成的代码部分（commit a5ce57b，-956 行）：
+- 删「一键重启 STF 容器」区块、设备表 STF 占用列、强制释放占用按钮
+- 删「STF 设备管理」子分栏（设备池管理面板接管）+ 卸载/检查 STF agent 按钮
+- 删除 `core/stf_client.py`、`core/stf_device_mgmt.py` 及全部引用（含 web_server
+  全部 STF API、启动残留清理、设备池首导 seed）
+- 错误类（STFError/DeviceOfflineError）迁入 `core/device_worker.py`；
+  `create_worker`/`BaseWorker` 去掉 stf 参数；`stf_occupied` 字段全链路移除
+- 文案清理（tools/apps/editor/monitor）+ `config.py` STF/SSH 配置标注废弃
+- 文档更新（ARCHITECTURE/DEPLOY）
+
+⏳ 待人工确认的最后一步（220 侧）：
+- **停 STF 容器**（`docker stop stf`，不删除，可 `docker start stf` 回滚）
+- 保留 adb 容器（host 网络 5037，USB 设备远程驱动依赖它）；
+  connect_devices.sh cron 可留可退役（对网络设备补连已无必要，无害）
+- 停容器前请确认：任务调度/看屏/设备池管理已稳定运行 ≥1 天
+
+## 阶段 4（可选，未来多实例/多机时）
+
+跨实例互斥：SQLite 行锁替代 occupy——
+```sql
+UPDATE device_locks SET owner=?, ts=? WHERE serial=? AND (owner IS NULL OR owner=?)
+```
+
+---
+
+## 回滚方式
+
+- 每个阶段一个 commit，问题可整体 `git revert`；STF 阶段 3 前一直运行，随时回切
+- 阶段 3 的 STF 容器是 `docker stop` 而非删除，回滚 = `git revert` + `docker start stf`
+- 每个阶段 commit 后在 dev 观察 ≥3 天再进下一阶段

doc/TASK_DEV.md

@@ -26,9 +26,8 @@
 
 ```
 platform-tools/
-├── config.py                  # 根配置（STF/adb/web，不放任务参数）
+├── config.py                  # 根配置（部署值从 .env 读，不放任务参数）
 ├── web_server.py              # Flask 入口（JSON API + 登录页 + 单页应用）
-├── main.py                    # 根目录入口
 ├── core/                      # 核心程序层
 │   ├── __init__.py
 │   ├── logger.py              # 日志器（分文件、10MB 滚动）
@@ -42,16 +41,18 @@ platform-tools/
 │       ├── __init__.py        # create_action_registry / register_action / should_trigger
 │       └── base.py            # BaseAction 全局基类
 ├── tasks/                     # 任务定义层
-│   ├── __init__.py            # 全局 _TASK_TYPES 注册表
+│   ├── __init__.py            # 全局 _TASK_TYPES 注册表（import 各任务包触发注册）
 │   ├── base.py                # BaseTask 基类
-│   └── douyin/                # 抖音养号（示例）
+│   ├── douyin/                # 抖音养号（示例）
+│   │   ├── __init__.py
+│   │   ├── task.py            #   DEFAULT_PARAMS + Worker + Task + @register_task
+│   │   └── actions/
+│   │       ├── __init__.py    #   先 from .base import ACTIONS，再 from . import like
+│   │       ├── base.py        #   ACTIONS = create_action_registry()
+│   │       └── like.py        #   @register_action(ACTIONS) LikeAction
+│   └── generic/               # 通用步骤任务（可视化步骤编辑器编排）
 │       ├── __init__.py
-│       ├── task.py            # DEFAULT_PARAMS + Worker + Task + @register_task
+│       └── task.py            #   STEP_TYPES + Worker + Task（按 steps 顺序执行）
-│       └── actions/
-│           ├── __init__.py    # 先 from .base import ACTIONS，再 from . import like, comment
-│           ├── base.py        # ACTIONS = create_action_registry()
-│           ├── like.py        # @register_action(ACTIONS) LikeAction
-│           └── comment.py     # @register_action(ACTIONS) CommentAction
 ├── templates/admin/
 │   ├── monitor.html           # 单页应用（5 Tab，纯前端渲染）
 │   └── login.html             # 登录页
@@ -135,7 +136,7 @@ def get_task_class(task_type):
 
 ### 2.5 Action — 操作
 
-`Action` 是任务循环里执行的"原子操作"（点赞 / 评论 / 滑动 / 关注）。每个 app 有**独立的 Action 注册表**（通过 `create_action_registry()` 创建），互不污染。全局基类 `core/actions/base.py::BaseAction` 提供通用能力。
+`Action` 是任务循环里执行的"原子操作"（点赞 / 关注 / 滑动等）。每个 app 有**独立的 Action 注册表**（通过 `create_action_registry()` 创建），互不污染。全局基类 `core/actions/base.py::BaseAction` 提供通用能力。
 
 ### 2.6 进度上报（通用，适配任意 app）
 
@@ -326,7 +327,7 @@ from .base import (
 
 # 再导入各操作模块，触发 @register_action(ACTIONS) 注册
 from . import like  # noqa: F401
-# from . import comment  # 新增 action 在此 import
+# 新增 action 在此 import，例如：from . import follow
 
 __all__ = [
     "BaseAction", "register_action", "create_action_registry",
@@ -342,7 +343,7 @@ __all__ = [
 """快手养号任务定义。
 
 本文件自包含所有快手养号参数，不依赖 core 的业务配置。
-快手专属操作（点赞/评论）在 actions/ 子包里，xpath 只适用于快手。
+快手专属操作（点赞/关注等）在 actions/ 子包里，xpath 只适用于快手。
 """
 import time
 import random
@@ -509,8 +510,9 @@ from . import task  # noqa: F401  触发 @register_task 注册
 ```python
 # tasks/__init__.py
 from .base import BaseTask, register_task, list_task_types, get_task_class
-from . import douyin  # noqa: F401
+from .douyin import task  # noqa: F401
-from . import kuaishou  # noqa: F401  ← 新增这一行
+from .generic import task  # noqa: F401
+from .kuaishou import task  # noqa: F401  ← 新增这一行
 ```
 
 完成。重启 web 后，前端任务类型下拉自动出现 `kuaishou_nurture`。
@@ -672,8 +674,10 @@ def run_task(self, d):
 
 ### 5.3 完整 Action 模板
 
+下面以"关注"操作为例，展示一个完整 Action 的写法（多策略定位 + 概率触发 + 异常兜底）：
+
 ```python
-# tasks/xxx/actions/comment.py
+# tasks/xxx/actions/follow.py
 import time
 import random
 
@@ -681,17 +685,16 @@ from core.actions import BaseAction, register_action, should_trigger
 from core.logger import get_logger
 from . import ACTIONS  # 从 __init__ 导入本 app 注册表
 
-_log = get_logger("action.xxx.comment")
+_log = get_logger("action.xxx.follow")
 
 
 @register_action(ACTIONS)
-class CommentAction(BaseAction):
+class FollowAction(BaseAction):
-    action_type = "comment"
+    action_type = "follow"
-    name = "评论"
+    name = "关注"
-    description = "看完视频后随机发一条评论"
+    description = "看完视频后随机关注作者"
     default_params = {
         "rate": 0.1,
-        "texts": ["不错", "666", "学到了"],
     }
 
     def execute(self, d, params, worker):
@@ -699,51 +702,19 @@ class CommentAction(BaseAction):
         if not should_trigger(rate):
             return False
 
-        texts = params.get("texts") or ["不错"]
+        # 定位关注按钮（多策略组合，失败回退）
-        text = random.choice(texts)
+        for desc in ("关注", "未关注", "follow"):
-
-        # 定位评论按钮（多策略组合，失败回退）
-        for desc in ("评论", "未评论", "comment"):
             el = d(description=desc)
             if el.exists:
                 el.click()
                 break
         else:
-            _log.info("未找到评论按钮")
+            _log.info("未找到关注按钮")
             return False
 
-        time.sleep(1.5)
-
-        # 找输入框
-        for rid in ("com.xxx:id/comment_input",):
-            el = d(resourceId=rid)
-            if el.exists:
-                el.click()
-                break
-        else:
-            d.press("back")
-            return False
-
-        time.sleep(0.8)
-
-        # 输入文本（中文需切输入法）
-        try:
-            d.set_fastinput_ime(True)
-        except Exception:
-            pass
-        d.send_keys(text)
-        time.sleep(0.6)
-
-        # 发送
-        el = d(text="发送")
-        if el.exists:
-            el.click()
-            _log.info(f"评论成功: {text}")
         time.sleep(1.0)
-            d.press("back")
+        _log.info("关注成功")
         return True
-        d.press("back")
-        return False
 ```
 
 > **返回值约定**：`True`=成功执行；`False`=主动跳过（概率未中、元素不存在等）；抛异常=执行失败，由 Worker 捕获并记录。
@@ -931,10 +902,10 @@ d.xpath('//FrameLayout[2]/LinearLayout[1]/TextView[3]').click()
 ```python
 # tasks/xxx/actions/__init__.py
 from .base import ACTIONS, ...   # 1. 先建注册表
-from . import like, comment      # 2. 再导入各 action，触发 @register_action
+from . import like               # 2. 再导入各 action，触发 @register_action
 ```
 
-`tasks/__init__.py` 同理：先 `from .base import BaseTask`，再 `from . import douyin`。
+`tasks/__init__.py` 同理：先 `from .base import BaseTask`，再 `from . import douyin`、`from . import generic`。
 
 ### 10.2 中文输入
 
@@ -1036,7 +1007,7 @@ self.set_progress(videos_watched=5, round_idx=3)
 - [ ] `tasks/<app>/actions/__init__.py` 先 `from .base import ACTIONS` 再导入各 action
 - [ ] 每个 Action 有 `action_type` / `name` / `default_params` / `execute`，返回 `True/False`
 - [ ] `Task.create_worker` 做 actions 参数级深合并（照抄抖音模板）
-- [ ] `tasks/__init__.py` 已 `from . import <app>` 注册
+- [ ] `tasks/__init__.py` 已 `from .<app> import task` 注册
 - [ ] 日志用 `get_logger("task.<app>")` / `get_logger("action.<app>.<name>")`，无 `print`
 - [ ] 定位元素优先 `description` / `descriptionContains`，resourceId 多候选，xpath 用相对定位
 - [ ] 中文输入用 `set_fastinput_ime`，加 try/except

main.py

@@ -1,43 +0,0 @@
-"""抖音养号命令行入口。
-
-直接运行：python main.py
-  - 单设备跑一次养号，不走 web/调度
-  - 任务参数默认值在 tasks/douyin_nurture.py 顶部，可通过环境变量 WATCH_COUNT 覆盖视频数
-
-web 管理后台请运行：python web_server.py
-清理 STF 残留占用：python scripts/cleanup.py
-
-目录结构：
-  config.py    — 项目根配置（STF 地址/token、adb 路径、web 端口、数据目录）
-  bin/adb/     — adb.exe 及依赖 dll
-  core/        — 核心程序（STF 客户端、adb 工具、BaseWorker 基类、任务管理器）
-  tasks/       — 任务定义（每个任务一个 .py，自带参数默认值，继承 BaseTask + @register_task）
-  web/         — 前端页面（index.html）
-  data/        — 持久化数据（分组、任务计划）
-  scripts/     — 实用脚本
-"""
-import os
-
-from core.stf_client import STFClient
-from tasks import get_task_class
-
-
-def run_once(serial=None, **overrides):
-    """单设备跑一次养号（命令行入口，不启动 web）。
-
-    走任务框架：取 douyin_nurture 任务类 → create_worker → 直接 run（当前线程）。
-    overrides 可传任务参数覆盖默认值，如 run_once(watch_count=20, like_enabled=False)。
-    """
-    stf = STFClient()
-    task_cls = get_task_class("douyin_nurture")
-    task = task_cls()
-    params = dict(overrides)
-    # 命令行友好：环境变量 WATCH_COUNT 覆盖视频数
-    if "WATCH_COUNT" in os.environ and "watch_count" not in params:
-        params["watch_count"] = int(os.environ["WATCH_COUNT"])
-    worker = task.create_worker(stf, serial, params)
-    worker.run()  # 直接在当前线程跑，不起子线程
-
-
-if __name__ == "__main__":
-    run_once()

requirements.txt

@@ -15,11 +15,24 @@ Flask-SQLAlchemy>=3.0,<4.0
 # 定时任务调度
 APScheduler>=3.10,<4.0
 
-# HTTP 客户端（STF API 调用）
+# HTTP 客户端
 requests>=2.28
 
+# SSH 远程执行（预留运维用；.env 配 STF_SSH_PASSWORD 时走密码认证，
+# 跨平台无需 sshpass；未配置则退回系统 ssh 免密密钥）
+paramiko>=3.0
+
 # Android UI 自动化（uiautomator2）
 uiautomator2>=3.0
 
+# UI 元素抓取（步骤编辑器"抓取元素"功能，本地服务端口 20242）
+uiautodev>=0.14
+
+# 屏幕 OCR（条件判断的 OCR识别 选择器，ONNX 推理，跨平台：Windows/Linux/macOS，
+# 中英文模型随包内置；服务器/容器环境必须用 headless 版 opencv——
+# opencv-python 依赖 X11 库（libxcb），slim 容器里 import cv2 直接崩，OCR 步骤任务失败退出）
+rapidocr_onnxruntime>=1.4
+opencv-python-headless>=4.8,<5  # 锁定 4.x：5.x wheel 打包异常（无 cv2 模块）
+
 # APK 元信息解析（应用管理功能：自动读取包名/版本/应用名）
 pyaxmlparser>=0.3.27

scripts/cleanup.py

@@ -1,49 +0,0 @@
-"""清理 STF 上残留的设备占用（强杀进程导致没正常释放时用）。
-
-运行：python scripts/cleanup.py
-       （在 auto/ 目录下运行也可：python -m scripts.cleanup）
-"""
-import os
-import sys
-
-# 让脚本既能直接运行（python scripts/cleanup.py）又能作为模块运行。
-# scripts/ 的上一级 auto/ 是 core 包的父目录，需加入 sys.path。
-_AUTO_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-if _AUTO_DIR not in sys.path:
-    sys.path.insert(0, _AUTO_DIR)
-
-import requests
-from config import STF_URL, STF_TOKEN
-
-headers = {"Authorization": f"Bearer {STF_TOKEN}"}
-
-# /user/devices 返回当前用户正在占用的设备
-resp = requests.get(f"{STF_URL}/api/v1/user/devices", headers=headers)
-resp.raise_for_status()
-data = resp.json()
-mine = data.get("devices", [])
-print(f"当前账户占用的设备数: {len(mine)}")
-for d in mine:
-    print(f"  - {d.get('serial')}  using={d.get('using')}")
-
-# 全部释放
-for d in mine:
-    serial = d["serial"]
-    try:
-        requests.post(
-            f"{STF_URL}/api/v1/user/devices/{serial}/remoteDisconnect",
-            headers=headers,
-        )
-    except Exception:
-        pass
-    r = requests.delete(f"{STF_URL}/api/v1/user/devices/{serial}", headers=headers)
-    print(f"释放 {serial}: HTTP {r.status_code}")
-
-# 再看一次总设备池
-resp = requests.get(f"{STF_URL}/api/v1/devices", headers=headers)
-resp.raise_for_status()
-free = [d for d in resp.json().get("devices", [])
-        if d.get("present") and d.get("ready") and not d.get("using") and d.get("owner") is None]
-print(f"\n清理后空闲设备数: {len(free)}")
-for d in free:
-    print(f"  - {d.get('serial')}")

scripts/fix_web.bat

@@ -1,57 +0,0 @@
-@echo off
-title Fix Web Access
-
-:: Auto elevate to admin
-net session >nul 2>&1
-if %errorLevel% neq 0 (
-    echo Requesting admin privileges...
-    powershell -Command "Start-Process cmd -ArgumentList '/c ""%~f0""' -Verb RunAs"
-    exit /b
-)
-
-echo ============================================
-echo   Fix Web Backend Access
-echo ============================================
-echo.
-
-:: 1. Disable residual system proxy (blocks localhost)
-echo [1/4] Disabling system proxy...
-reg add "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v ProxyEnable /t REG_DWORD /d 0 /f >nul 2>&1
-reg delete "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v ProxyServer /f >nul 2>&1
-echo Done.
-echo.
-
-:: 2. Add firewall rules for Python
-echo [2/4] Adding firewall rules for Python...
-for /f "delims=" %%i in ('where python') do set PYTHON_PATH=%%i
-if not defined PYTHON_PATH (
-    echo ERROR: Python not found in PATH
-    pause
-    exit /b 1
-)
-echo Python path: %PYTHON_PATH%
-netsh advfirewall firewall delete rule name="PythonWeb" >nul 2>&1
-netsh advfirewall firewall add rule name="PythonWeb" dir=in action=allow program="%PYTHON_PATH%" enable=yes profile=any >nul
-netsh advfirewall firewall delete rule name="PythonWebOut" >nul 2>&1
-netsh advfirewall firewall add rule name="PythonWebOut" dir=out action=allow program="%PYTHON_PATH%" enable=yes profile=any >nul
-echo Done.
-echo.
-
-:: 3. Flush DNS cache
-echo [3/4] Flushing DNS cache...
-ipconfig /flushdns >nul 2>&1
-echo Done.
-echo.
-
-:: 4. Show excluded port ranges for reference
-echo [4/4] TCP excluded port ranges (for reference):
-netsh interface ipv4 show excludedportrange protocol=tcp
-echo.
-
-echo ============================================
-echo  Fix complete! Now:
-echo  1. Close ALL browser windows and reopen
-echo  2. Run: python web_server.py
-echo  3. Open: http://127.0.0.1:18050/
-echo ============================================
-pause

scripts/pack.py

@@ -15,7 +15,7 @@ SKIP_EXTS = {".pyc", ".pyo"}
 # 路径片段包含这些的跳过
 SKIP_PARTS = {"__pycache__"}
 # 文件名完全匹配这些的跳过
-SKIP_FILES = {"fix_web.bat"}
+SKIP_FILES = {}
 # 文件名后缀匹配这些的跳过
 SKIP_SUFFIX = (".migrated",)
 # 特定目录下特定后缀跳过

scripts/regression_test.py

@@ -0,0 +1,167 @@
+"""全量路由回归测试：启动后遍历所有 API 路由发请求，抓 500/异常。
+
+用法（项目根目录）：
+    .venv/bin/python scripts/regression_test.py
+
+设计：
+  - 用 Flask test_client（不占用 18050，不影响运行中的服务）
+  - GET 路由全量请求（路径参数自动替换）；流式/二进制接口跳过
+  - 写操作（POST/PUT/DELETE）发空 body 探测：期望 400/403/404（参数校验），
+    返回 500 = 代码缺陷（import 遗漏/引用错误），立即报出
+  - 关键业务 POST 用真实参数验证（亮屏/剪贴板/测试步骤/设备池增删）
+  - 退出码：有失败返回 1（可接入检查流程）
+
+背景：web/ 蓝图拆分后多次出现 import 遗漏导致接口 500（ADB_PATH/_log/常量等），
+每次都是线上报错才暴露。此脚本让这类问题在改动后 30 秒内现形。
+"""
+import os
+import sys
+import signal
+
+# 项目根加入 sys.path（脚本在 scripts/ 下运行，保证可 import web_server/config）
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# 测试模式：禁用 cron 调度器（否则 test_client 会按 DB 里的任务 cron 真跑任务，
+# 干扰回归/占用设备——实测 ocr关键字任务每 30 分钟触发导致回归超时）
+os.environ["DISABLE_SCHEDULER"] = "1"
+
+# 单接口超时保护：adb 相关接口可能慢（连接/查询设备），给足时间
+signal.alarm(300)
+
+from web_server import app  # noqa: E402  （导入即完成 app 装配，与生产一致）
+
+
+# 流式/二进制接口：无法用普通 GET 断言，跳过（已有单独验证路径）
+_SKIP_PREFIXES = (
+    "/api/screen/stream", "/api/screen/thumb",
+    "/api/uiauto/screenshot", "/api/device/screenshot",
+)
+# 关键业务 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": "回归测试"}),
+    ("测试步骤(wait)", "/api/steps/test",
+     {"serial": "100.100.10.11:5555",
+      "step": {"type": "wait", "label": "等待", "params": {"max": 1, "min": 1, "probability": 100}}}),
+    ("adb 终端执行", "/api/adb/cmd", {"cmd": "adb devices"}),
+    ("adb 红线拦截", "/api/adb/cmd", {"cmd": "adb kill-server"}),
+    ("应用版本查询", "/api/tools/appver", {"pkg": "jp.co.cyberagent.stf"}),
+]
+# 红线接口：期望被拒绝（不是 ok）
+_EXPECT_REJECT = {"/api/adb/cmd"}
+
+
+def _fill_path_params(rule):
+    """把路由路径参数 <xxx> 替换为测试值（serial 用真实设备）。"""
+    url = rule
+    url = url.replace("<serial>", "100.100.10.11:5555")
+    url = url.replace("<apk_id>", "x")
+    url = url.replace("<action_id>", "x")
+    url = url.replace("<device_id>", "x")
+    url = url.replace("<uid>", "1")
+    return url
+
+
+def main():
+    c = app.test_client()
+    # 登录 + CSRF
+    r = c.post("/login", data={"username": "admin", "password": "admin123"})
+    if r.status_code != 302:
+        print("❌ 登录失败（请检查 admin 账号）")
+        sys.exit(1)
+    token = c.get("/api/csrf").get_json()["token"]
+    H = {"X-CSRF-Token": token}
+
+    fails = []
+    warns = []
+    passed = 0
+
+    # ========== 1. GET 全量 ==========
+    rules = sorted({r.rule for r in app.url_map.iter_rules()
+                    if r.rule.startswith("/api") and "GET" in r.methods})
+    for rule in rules:
+        if rule.startswith(_SKIP_PREFIXES):
+            continue
+        url = _fill_path_params(rule)
+        try:
+            r = c.get(url)
+            if r.status_code == 500:
+                fails.append(f"GET {rule} -> HTTP 500（代码缺陷）")
+            elif r.status_code >= 502:
+                warns.append(f"GET {rule} -> HTTP {r.status_code}（业务错误，如未配置/设备离线）")
+            else:
+                passed += 1
+        except Exception as e:
+            fails.append(f"GET {rule} -> {type(e).__name__}: {e}")
+    print(f"GET 路由: {len(rules)} 个（跳过 {len([r for r in rules if r.startswith(_SKIP_PREFIXES)])} 个流式/二进制）")
+
+    # ========== 1.5 未登录访问（登录重定向链路） ==========
+    try:
+        r = c.get("/")
+        if r.status_code == 302 and "login" in (r.headers.get("Location") or ""):
+            passed += 1
+        elif r.status_code == 200:
+            passed += 1  # 已登录态也可能 200（测试客户端无 cookie 时走 302）
+        else:
+            fails.append(f"未登录访问 / -> HTTP {r.status_code}（应 302 到登录页）")
+    except Exception as e:
+        fails.append(f"未登录访问 / -> {type(e).__name__}: {e}")
+
+    # ========== 2. 写操作空 body 探测（抓 import 遗漏/引用错误） ==========
+    write_rules = sorted({r.rule for r in app.url_map.iter_rules()
+                          if r.rule.startswith("/api")
+                          and (r.methods & {"POST", "PUT", "DELETE"})})
+    for rule in write_rules:
+        url = _fill_path_params(rule)
+        try:
+            methods = {m for r2 in app.url_map.iter_rules() if r2.rule == rule for m in r2.methods}
+            if "DELETE" in methods:
+                r = c.delete(url, headers=H)
+            elif "PUT" in methods:
+                r = c.put(url, json={}, headers=H)
+            else:
+                r = c.post(url, json={}, headers=H)
+            # 空 body 期望 400（参数校验）；403=权限/404=路径参数、500=代码缺陷
+            if r.status_code == 500:
+                fails.append(f"写操作 {rule} -> HTTP 500（空 body 应 400，500=代码缺陷）")
+            elif r.status_code >= 502:
+                warns.append(f"写操作 {rule} -> HTTP {r.status_code}（业务错误，如未配置/设备离线）")
+            else:
+                passed += 1
+        except Exception as e:
+            fails.append(f"写操作 {rule} -> {type(e).__name__}: {e}")
+    print(f"写操作路由: {len(write_rules)} 个（空 body 探测）")
+
+    # ========== 3. 关键业务 POST（真实参数） ==========
+    for name, url, body in _KEY_POSTS:
+        try:
+            r = c.post(url, json=body, headers=H)
+            j = r.get_json() if r.is_json else None
+            is_reject = url in _EXPECT_REJECT and "kill" in (body.get("cmd") or "")
+            good = (not j.get("ok")) if is_reject else bool(j and j.get("ok") is not False)
+            if good:
+                passed += 1
+                print(f"  ✅ {name}: {r.status_code}")
+            else:
+                fails.append(f"关键 POST {name} -> HTTP {r.status_code} {str(j)[:80]}")
+        except Exception as e:
+            fails.append(f"关键 POST {name} -> {type(e).__name__}: {e}")
+
+    # ========== 汇总 ==========
+    print("-" * 50)
+    if warns:
+        print(f"⚠ 业务性提示 {len(warns)} 个（非代码缺陷）：")
+        for w in warns:
+            print("   ", w)
+    if fails:
+        print(f"❌ 发现 {len(fails)} 个代码缺陷：")
+        for f in fails:
+            print("   ", f)
+        sys.exit(1)
+    print(f"✅ 全部通过（{passed} 项检查，含 {len(rules)} GET + {len(write_rules)} 写操作探测 + {len(_KEY_POSTS)} 关键业务）")
+
+
+if __name__ == "__main__":
+    main()

scripts/start.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# 容器启动脚本：安装依赖 + 环境修复 + 启动 web_server。
+# compose 的 python-app 服务 command 指向本脚本。
+#
+# 为什么需要环境修复（必须在 pip install 之后）：
+#   rapidocr_onnxruntime 的依赖声明是 opencv-python（GUI 版），pip 解析依赖时
+#   会强制装回它；而 GUI 版依赖 X11 库（libxcb），python:slim 容器里 import cv2
+#   直接崩溃 → 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 手动解压兜底（幂等）
+python3 - <<'PY'
+import glob, os, shutil, site, subprocess, sys, zipfile
+
+def cv2_ok():
+    try:
+        import cv2
+        return hasattr(cv2, "__version__") and cv2.__file__ is not None
+    except Exception:
+        return False
+
+if cv2_ok():
+    sys.exit(0)
+print("cv2 空壳，wheel 手动解压修复...")
+r = subprocess.run(["pip", "download", "--no-deps", "-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__} 手动解压修复完成")
+PY
+
+exec python -u web_server.py

scripts/supervise.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# web_server.py 进程守护脚本：崩溃自动重启，带退避和重启上限。
+#
+# 用法：
+#   bash scripts/supervise.sh                 # 用 python3 启动
+#   PYTHON=./.venv/bin/python bash scripts/supervise.sh   # 指定 Python（venv）
+#
+# 行为：
+#   - web_server 崩溃（非 0/130 退出码）→ 等待 BACKOFF_MIN 秒自动重启
+#   - 重启窗口（RESTART_WINDOW 秒）内超过 MAX_RESTARTS 次 → 停止（防崩溃死循环）
+#   - 正常退出（Ctrl+C=130 或 code=0）→ 守护结束
+#   - 日志写到 logs/supervise.log
+#
+# 生产无人值守建议配合 Docker 的 restart: unless-stopped 或 systemd 一起用。
+
+cd "$(dirname "$0")/.."
+PYTHON="${PYTHON:-python3}"
+mkdir -p logs
+
+MAX_RESTARTS="${MAX_RESTARTS:-10}"        # 窗口内最大重启次数
+RESTART_WINDOW="${RESTART_WINDOW:-300}"    # 重启窗口（秒）
+BACKOFF_MIN="${BACKOFF_MIN:-2}"            # 重启前等待（秒）
+
+restarts=0
+window_start=$(date +%s)
+
+echo "[$(date '+%F %T')] 进程守护启动，python=$PYTHON"
+while true; do
+  echo "[$(date '+%F %T')] 启动 web_server.py..."
+  "$PYTHON" web_server.py >> logs/supervise.log 2>&1
+  code=$?
+  echo "[$(date '+%F %T')] web_server 退出，code=$code"
+
+  # 0 = 正常结束；130 = Ctrl+C（SIGINT）→ 手动停止，守护结束
+  if [ "$code" -eq 0 ] || [ "$code" -eq 130 ]; then
+    echo "[$(date '+%F %T')] 正常退出，守护进程结束"
+    break
+  fi
+
+  # 滑动窗口计数
+  now=$(date +%s)
+  if [ $((now - window_start)) -gt "$RESTART_WINDOW" ]; then
+    window_start=$now
+    restarts=0
+  fi
+  restarts=$((restarts + 1))
+  if [ "$restarts" -gt "$MAX_RESTARTS" ]; then
+    echo "[$(date '+%F %T')] ${RESTART_WINDOW}s 内崩溃超过 ${MAX_RESTARTS} 次，停止守护（可能配置/环境问题）"
+    break
+  fi
+
+  echo "[$(date '+%F %T')] ${BACKOFF_MIN}s 后重启 (窗口内第 ${restarts} 次)"
+  sleep "$BACKOFF_MIN"
+done

start_web.bat

@@ -1,34 +0,0 @@
-@echo off
-chcp 65001 >nul 2>&1
-title 设备自动化后台（局域网模式）
-
-REM ===== 自动提权到管理员 =====
-net session >nul 2>&1
-if %errorlevel% neq 0 (
-    echo 需要管理员权限以支持局域网访问，正在提权...
-    powershell -Command "Start-Process -FilePath '%~f0' -Verb RunAs"
-    exit /b
-)
-
-cd /d "%~dp0"
-
-REM ===== 添加防火墙入站规则（放行 Python，仅一次） =====
-for /f "delims=" %%i in ('where python') do set PY_EXE=%%i
-netsh advfirewall firewall show rule name="PlatformTools Web" >nul 2>&1
-if %errorlevel% neq 0 (
-    echo 正在添加防火墙规则...
-    netsh advfirewall firewall add rule name="PlatformTools Web" dir=in action=allow program="%PY_EXE%" enable=yes >nul 2>&1
-    netsh advfirewall firewall add rule name="PlatformTools Web" dir=out action=allow program="%PY_EXE%" enable=yes >nul 2>&1
-)
-
-echo ============================================
-echo  管理后台已启动（局域网可访问）
-echo  本机访问: http://127.0.0.1:18050/
-echo  局域网访问: http://本机IP:18050/
-echo  默认账号: admin / admin123
-echo  按 Ctrl+C 停止
-echo ============================================
-echo.
-
-python web_server.py
-pause

static/admin/admin.js

@@ -0,0 +1,220 @@
+// 管理 Tab：分组/日志/用户
+// ================== Tab 3: 分组 ==================
+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||[]:[];
+  renderGroupTable();
+}
+
+function renderGroupTable(){
+  const groups=_groupsList||[];
+  setListPager('groups',{
+    data:()=>groups,
+    filter:(g,kw)=>((g.name||'').toLowerCase().includes(kw)||(g.description||'').toLowerCase().includes(kw)||(g.serials||[]).join(' ').toLowerCase().includes(kw)),
+    sortValue:(g,k)=>{ if(k==='count')return (g.serials||[]).length; return g[k]||''; },
+    render:renderGroupRow,
+    tbody:'tb-groups',pager:'pager-groups',pageSize:10,
+    empty:'<tr><td colspan="5" class="empty">暂无分组，点击"新建分组"创建</td></tr>'
+  });
+  applyListPager('groups');
+  initListSearch('groups','search-groups');
+}
+function renderGroupRow(g){
+  const serials=g.serials||[];
+  return '<tr>'+
+    '<td><strong>'+esc(g.name)+'</strong></td>'+
+    '<td>'+esc(g.description||'-')+'</td>'+
+    '<td>'+serials.length+'</td>'+
+    '<td class="text-muted" style="max-width:300px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">'+(serials.length?serials.map(esc).join(', '):'-')+'</td>'+
+    '<td>'+
+      (_can('tasks')?(
+        '<button class="btn btn-xs" onclick="openGroupModal(\''+esc(g.name)+'\')">编辑</button>'+
+        '<button class="btn btn-danger btn-xs" onclick="deleteGroup(\''+esc(g.name)+'\')">删除</button>'
+      ):'<span class="text-muted">只读</span>')+
+    '</td>'+
+  '</tr>';
+}
+
+function openGroupModal(name){
+  const group=name?(_groupsList||[]).find(g=>g.name===name):null;
+  const isEdit=!!group;
+  document.getElementById('modal-title').textContent=isEdit?'编辑分组':'新建分组';
+  const g=group||{name:'',description:'',serials:[]};
+  const current= new Set(g.serials||[]);
+  const allSerials=[...new Set([..._devicesList, ...(g.serials||[])])].sort();
+  const deviceCheckboxes=allSerials.map(s=>
+    '<label><input type="checkbox" value="'+esc(s)+'" '+(current.has(s)?'checked':'')+'>'+esc(s)+'</label>'
+  ).join('');
+
+  document.getElementById('modal-body').innerHTML=
+    '<div class="form-group"><label>分组名</label><input type="text" class="form-control" id="g-name" value="'+esc(g.name)+'" placeholder="如：测试组" '+(isEdit?'readonly':'')+'></div>'+
+    '<div class="form-group"><label>描述</label><input type="text" class="form-control" id="g-description" value="'+esc(g.description||'')+'" placeholder="可选"></div>'+
+    '<div class="form-group"><label>设备列表（勾选属于此分组的设备）</label>'+
+      '<div class="device-list">'+(deviceCheckboxes||'<div class="text-muted">暂无在线设备</div>')+'</div>'+
+      '<div class="help">仅显示当前在线设备，已选设备即使离线也会保留</div>'+
+    '</div>';
+
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">取消</button>'+
+    '<button class="btn btn-primary" onclick="saveGroup('+(isEdit?'\''+esc(g.name)+'\'':'null')+')">'+(isEdit?'保存':'创建')+'</button>';
+
+  showModal();
+}
+
+async function saveGroup(name){
+  const newName=document.getElementById('g-name').value.trim();
+  if(!newName){showToast('分组名不能为空','error');return;}
+  const desc=document.getElementById('g-description').value;
+  const serials=Array.from(document.querySelectorAll('.device-list input:checked')).map(c=>c.value);
+  const data={name:newName,description:desc,serials:serials};
+
+  if(name){
+    const r=await apiPut('/api/groups/'+encodeURIComponent(name),data);
+    handleResult(r,()=>{closeModal();loadGroups();});
+  }else{
+    const r=await apiPost('/api/groups',data);
+    handleResult(r,()=>{closeModal();loadGroups();});
+  }
+}
+
+async function deleteGroup(name){
+  if(!confirm('确认删除分组"'+name+'"吗？'))return;
+  const r=await apiDelete('/api/groups/'+encodeURIComponent(name));
+  handleResult(r,()=>loadGroups());
+}
+
+// ================== Tab 4: 日志 ==================
+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;
+}
+
+function toggleLogAuto(){
+  if(_logTimer){clearInterval(_logTimer);_logTimer=null;}
+  if(document.getElementById('log-auto').checked && _activeTab==='logs'){
+    _logTimer=setInterval(loadLogs,3000);
+  }
+}
+
+// ================== Tab 5: 用户 ==================
+async function loadUsers(){
+  const r=await apiGet('/api/users');if(!r)return;
+  const users=r.users||[];
+  setListPager('users',{
+    data:()=>users,
+    filter:(u,kw)=>(u.username||'').toLowerCase().includes(kw),
+    sortValue:(u,k)=>{ if(k==='is_admin')return u.is_admin?1:0; return u[k]||''; },
+    render:renderUserRow,
+    tbody:'tb-users',pager:'pager-users',pageSize:10,
+    empty:'<tr><td colspan="5" class="empty">暂无用户</td></tr>'
+  });
+  applyListPager('users');
+  initListSearch('users','search-users');
+}
+function renderUserRow(u){
+  const admin=u.is_admin?'<span class="label label-primary">管理员</span>':'<span class="label label-default">普通</span>';
+  const perms=(u.perms||[]).map(p=>'<span class="label label-info">'+(PERM_LABELS[p]||p)+'</span>').join(' ')
+    ||'<span class="text-muted">-</span>';
+  return '<tr>'+
+    '<td>'+u.id+'</td>'+
+    '<td><strong>'+esc(u.username)+'</strong></td>'+
+    '<td>'+admin+'</td>'+
+    '<td>'+perms+'</td>'+
+    '<td>'+
+      '<button class="btn btn-xs" onclick="openUserModal('+u.id+')">编辑</button>'+
+      (u.username==='admin'?'':'<button class="btn btn-danger btn-xs" onclick="deleteUser('+u.id+')">删除</button>')+
+    '</td>'+
+  '</tr>';
+}
+
+function togglePermBoxes(){
+  // 勾选"管理员权限"时：权限位全选并禁用（管理员拥有全部权限）
+  const isAdmin=document.getElementById('u-is_admin').checked;
+  document.querySelectorAll('.u-perm').forEach(cb=>{
+    cb.disabled=isAdmin;
+    if(isAdmin)cb.checked=true;
+  });
+}
+
+function openUserModal(uid){
+  const isEdit=!!uid;
+  document.getElementById('modal-title').textContent=isEdit?'编辑用户':'新建用户';
+  const permBoxes=Object.keys(PERM_LABELS).map(p=>
+    '<label style="margin-right:12px"><input type="checkbox" class="u-perm" value="'+p+'">'+PERM_LABELS[p]+'</label>'
+  ).join('');
+  document.getElementById('modal-body').innerHTML=
+    '<div class="form-group"><label>用户名</label><input type="text" class="form-control" id="u-username" '+(isEdit?'disabled':'')+' placeholder="用户名"></div>'+
+    '<div class="form-group"><label>密码'+(isEdit?'（留空不修改）':'')+'</label><input type="password" class="form-control" id="u-password" placeholder="密码"></div>'+
+    '<div class="form-group form-check"><input type="checkbox" id="u-is_admin" onchange="togglePermBoxes()" checked><label for="u-is_admin">管理员权限（拥有全部权限）</label></div>'+
+    '<div class="form-group"><label>业务权限（管理员自动拥有全部，无需勾选）</label>'+
+      '<div>'+permBoxes+'</div>'+
+      '<div class="help">任务管理=任务/自定义动作/分组；设备控制=停止/释放/清异常/扫描/抓元素；应用管理=APK上传安装；日志查看=日志页</div>'+
+    '</div>';
+
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">取消</button>'+
+    '<button class="btn btn-primary" onclick="saveUser('+(uid||'null')+')">'+(isEdit?'保存':'创建')+'</button>';
+
+  if(isEdit){
+    // 预填充（从表格数据获取）
+    apiGet('/api/users').then(r=>{
+      const u=(r&&r.users||[]).find(x=>x.id===uid);
+      if(u){
+        document.getElementById('u-username').value=u.username;
+        document.getElementById('u-is_admin').checked=u.is_admin;
+        document.querySelectorAll('.u-perm').forEach(cb=>{
+          cb.checked=(u.perms||[]).includes(cb.value);
+        });
+        togglePermBoxes();
+      }
+    });
+  }else{
+    togglePermBoxes();
+  }
+  showModal();
+}
+
+async function saveUser(uid){
+  const username=document.getElementById('u-username').value.trim();
+  const password=document.getElementById('u-password').value;
+  const is_admin=document.getElementById('u-is_admin').checked;
+  const perms=[...document.querySelectorAll('.u-perm:checked')].map(cb=>cb.value);
+
+  if(uid){
+    const data={is_admin:is_admin,perms:perms};
+    if(password)data.password=password;
+    const r=await apiPut('/api/users/'+uid,data);
+    handleResult(r,()=>{closeModal();loadUsers();});
+  }else{
+    if(!username||!password){showToast('用户名和密码不能为空','error');return;}
+    const r=await apiPost('/api/users',{username:username,password:password,is_admin:is_admin,perms:perms});
+    handleResult(r,()=>{closeModal();loadUsers();});
+  }
+}
+
+async function deleteUser(uid){
+  if(!confirm('确认删除此用户吗？'))return;
+  const r=await apiDelete('/api/users/'+uid);
+  handleResult(r,()=>loadUsers());
+}
+
+
+// ================== 初始化 ==================
+initCsrf();   // 获取 CSRF token（非 GET 请求需携带）
+loadMe();     // 获取当前用户权限，隐藏无权限的功能入口
+showTab('monitor');

static/admin/apps.js

@@ -0,0 +1,264 @@
+// 工具 Tab-应用管理：APK 上传/安装/删除 + 设备已装应用
+// ================== Tab: 应用 ==================
+let _apksCache=[];
+let _installTimer=null;
+let _devAppsData=[];
+
+function fmtSize(b){
+  if(!b)return '0 B';
+  if(b<1024)return b+' B';
+  if(b<1048576)return (b/1024).toFixed(1)+' KB';
+  return (b/1048576).toFixed(1)+' MB';
+}
+
+async function loadApks(){
+  const r=await apiGet('/api/apks');if(!r||!r.ok)return;
+  const apks=r.apks||[];
+  _apksCache=apks;
+  document.getElementById('apk-hint').textContent='共 '+apks.length+' 个应用';
+  setListPager('apks',{
+    data:()=>apks,
+    sortValue:(a,k)=>{ if(k==='size')return a.size||0; if(k==='upload_time')return a.upload_time||''; if(k==='package_name')return a.package_name||''; if(k==='version_name')return a.version_name||''; return a.display_name||''; },
+    filter:(a,kw)=>((a.display_name||'').toLowerCase().includes(kw)||(a.package_name||'').toLowerCase().includes(kw)),
+    render:renderApkRow,
+    tbody:'tb-apks',pager:'pager-apks',pageSize:10,
+    empty:'<tr><td colspan="6" class="empty">暂无APK，点击"上传APK"上传</td></tr>'
+  });
+  applyListPager('apks');
+  initListSearch('apks','search-apks');
+  await fillAppsDeviceList();
+}
+function renderApkRow(a){
+  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>'+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>'+
+    '</td>'+
+  '</tr>';
+}
+
+// 填充"设备已装应用"的设备下拉（保留当前选择）
+async function fillAppsDeviceList(){
+  const sr=await apiGet('/api/status');if(!sr||!sr.ok)return;
+  const sel=document.getElementById('apps-device');
+  if(!sel)return;
+  const cur=sel.value;
+  const devices=(sr.devices||[]).filter(d=>d.present);
+  sel.innerHTML='<option value="">选择设备...</option>'+devices.map(d=>
+    '<option value="'+esc(d.serial)+'">'+esc((d.serial||'').replace(/:5555$/,'')+' ('+(d.device_name||d.model||'未知设备')+')')+'</option>'
+  ).join('');
+  if(cur)sel.value=cur;
+}
+
+// 查看指定设备已安装应用
+async function loadDeviceApps(){
+  const sel=document.getElementById('apps-device');
+  const serial=sel.value;
+  if(!serial){showToast('请先选择设备','error');return;}
+  const hint=document.getElementById('apps-hint');
+  const tb=document.getElementById('tb-device-apps');
+  hint.textContent='加载中...';
+  const r=await apiGet('/api/devices/'+encodeURIComponent(serial)+'/apps');
+  hint.textContent='';
+  if(!r||!r.ok){
+    tb.innerHTML='<tr><td colspan="4" class="empty">'+(r&&r.error?esc(r.error):'获取失败')+'</td></tr>';
+    showToast('获取失败','error');return;
+  }
+  const apps=r.apps||[];
+  if(!apps.length){tb.innerHTML='<tr><td colspan="4" class="empty">无应用</td></tr>';return;}
+  const userApps=apps.filter(a=>/^\/data\//.test(a.path||'')).length;
+  hint.textContent='共 '+apps.length+' 个应用（用户安装 '+userApps+'）';
+  _devAppsData=apps;
+  setListPager('devapps',{
+    data:()=>_devAppsData||[],
+    filter:(a,kw)=>((a.label||a.package||'').toLowerCase().includes(kw)||(a.package||'').toLowerCase().includes(kw)||(a.path||'').toLowerCase().includes(kw)),
+    sortValue:(a,k)=>{ if(k==='version_code')return parseInt(a.version_code)||0; if(k==='version_name')return a.version_name||''; if(k==='label')return (a.label||a.package||''); return a[k]||''; },
+    render:renderDevAppRow,
+    tbody:'tb-device-apps',pager:'pager-devapps',pageSize:20,
+    empty:'<tr><td colspan="4" class="empty">无应用</td></tr>'
+  });
+  applyListPager('devapps');
+  initListSearch('devapps','search-devapps');
+}
+function renderDevAppRow(a){
+  return '<tr>'+
+    '<td><strong>'+esc(a.label||a.package)+'</strong>'+(a.label?' <span style="font-size:11px;color:#94a3b8;font-family:monospace">'+esc(a.package)+'</span>':'')+'</td>'+
+    '<td>'+(a.version_name?esc(a.version_name):'-')+'</td>'+
+    '<td style="font-size:12px;color:#94a3b8">'+(a.version_code!=null?esc(a.version_code):'-')+'</td>'+
+    '<td style="font-size:11px;color:#94a3b8;word-break:break-all">'+esc(a.path||'-')+'</td>'+
+  '</tr>';
+}
+
+async function uploadApk(input){
+  if(!input.files||!input.files[0])return;
+  const file=input.files[0];
+  if(!file.name.toLowerCase().endsWith('.apk')){
+    showToast('请选择 .apk 文件','error');return;
+  }
+  const hint=document.getElementById('apk-hint');
+  const fd=new FormData();
+  fd.append('file',file);
+  // 用 XMLHttpRequest 才能拿到上传进度（fetch 不支持上传进度事件）
+  const xhr=new XMLHttpRequest();
+  xhr.open('POST','/api/apks/upload');
+  if(_csrfToken)xhr.setRequestHeader('X-CSRF-Token',_csrfToken);
+  xhr.upload.onprogress=function(e){
+    if(e.lengthComputable){
+      const pct=Math.round(e.loaded*100/e.total);
+      const loaded=(e.loaded/1048576).toFixed(1);
+      const total=(e.total/1048576).toFixed(1);
+      hint.innerHTML='<span style="color:#f59e0b">正在上传 '+esc(file.name)+' '+pct+'% ('+loaded+'/'+total+' MB)</span>'+
+        '<div class="progress" style="width:200px;height:6px;margin-top:4px"><div class="progress-bar" style="width:'+pct+'%"></div></div>';
+    }
+  };
+  xhr.onload=function(){
+    if(xhr.status===401){window.location='/login';return;}
+    try{
+      const data=JSON.parse(xhr.responseText);
+      if(data.ok){
+        showToast(data.msg||'上传成功','success');
+        loadApks();
+      }else{
+        showToast(data.error||'上传失败','error');
+        hint.textContent='';
+      }
+    }catch(e){
+      showToast('解析响应失败','error');
+      hint.textContent='';
+    }
+  };
+  xhr.onerror=function(){
+    showToast('上传失败：网络错误','error');
+    hint.textContent='';
+  };
+  xhr.send(fd);
+  input.value='';
+}
+
+async function deleteApk(id){
+  if(!confirm('确认删除此APK文件？'))return;
+  const r=await apiDelete('/api/apks/'+id);
+  handleResult(r,loadApks);
+}
+
+async function openInstallModal(apkId){
+  const apk=_apksCache.find(a=>a.id===apkId);
+  const apkName=apk?(apk.display_name||'APK'):'APK';
+  const r=await apiGet('/api/apks/install/devices');
+  const online=(r&&r.ok)?(r.devices||[]):[];
+  if(!online.length){
+    showToast('没有可用设备（设备池或本机 adb 均无）','error');return;
+  }
+  const body=
+    '<div style="margin-bottom:12px">'+
+      '<strong>安装应用：</strong><span class="label label-primary">'+esc(apkName)+'</span>'+
+      ' <span style="font-size:12px;color:#94a3b8">运行中设备将自动跳过</span>'+
+    '</div>'+
+    '<div style="margin-bottom:8px">'+
+      '<button class="btn btn-sm" onclick="document.querySelectorAll(\'#install-dev-list input[type=checkbox]\').forEach(c=>c.checked=true)">全选</button> '+
+      '<button class="btn btn-sm" onclick="document.querySelectorAll(\'#install-dev-list input[type=checkbox]\').forEach(c=>c.checked=false)">全不选</button> '+
+      '<button class="btn btn-sm btn-primary" onclick="selectIdleForInstall()">全选空闲</button>'+
+    '</div>'+
+    '<div id="install-dev-list" class="device-list">'+
+      online.map(d=>{
+        const isUsb=d.source==='usb';
+        const st='<span class="label label-'+(isUsb?'primary':'default')+'" style="margin-left:6px">'+(isUsb?'本地USB':(d.source==='pool'?'设备池':'adb'))+'</span>';
+        // serial 唯一，显示 IP + 型号便于区分同型号设备
+        const label=(d.serial||'').replace(/:5555$/,'')+' · '+(d.model||(isUsb?'USB 有线设备':'设备'));
+        return '<label><input type="checkbox" value="'+esc(d.serial)+'" checked>'+esc(label)+st+'</label>';
+      }).join('')+
+    '</div>';
+
+  document.getElementById('modal-title').textContent='安装应用到设备';
+  document.getElementById('modal-body').innerHTML=body;
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">取消</button>'+
+    '<button class="btn btn-primary" onclick="startInstall(\''+apkId+'\')">开始安装</button>';
+  document.getElementById('modal-overlay').classList.add('show');
+}
+
+function selectIdleForInstall(){
+  document.querySelectorAll('#install-dev-list label').forEach(lbl=>{
+    const cb=lbl.querySelector('input[type=checkbox]');
+    const isRunning=lbl.querySelector('.label-success');
+    cb.checked=!isRunning;
+  });
+}
+
+async function startInstall(apkId){
+  const checked=document.querySelectorAll('#install-dev-list input[type=checkbox]:checked');
+  const serials=Array.from(checked).map(c=>c.value);
+  if(!serials.length){
+    showToast('请至少选择一台设备','error');return;
+  }
+  const r=await apiPost('/api/apks/install',{apk_id:apkId,serials:serials});
+  if(!r||!r.ok){showToast(r?r.error:'请求失败','error');return;}
+  showToast(r.msg||'安装已启动','success');
+  showInstallProgress();
+}
+
+function showInstallProgress(){
+  document.getElementById('modal-title').textContent='安装进度';
+  document.getElementById('modal-body').innerHTML=
+    '<div id="install-progress" style="min-height:200px"><p class="text-muted">加载中...</p></div>';
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeInstallModal()" id="install-close-btn" style="display:none">关闭</button>';
+  pollInstallStatus();
+  if(_installTimer)clearInterval(_installTimer);
+  _installTimer=setInterval(pollInstallStatus,3000);
+}
+
+async function pollInstallStatus(){
+  const r=await apiGet('/api/apks/install/status');
+  if(!r||!r.ok)return;
+  const st=r.status;
+  if(!st){
+    document.getElementById('install-progress').innerHTML='<p class="text-muted">无安装任务</p>';
+    if(_installTimer){clearInterval(_installTimer);_installTimer=null;}
+    return;
+  }
+  const SS={pending:{t:'等待',c:'default'},installing:{t:'安装中',c:'warning'},success:{t:'成功',c:'success'},failed:{t:'失败',c:'danger'},skipped:{t:'跳过',c:'default'}};
+  const items=st.items||{};
+  const itemRows=Object.entries(items).map(([serial,info])=>{
+    const s=SS[info.status]||{t:info.status,c:'default'};
+    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>';
+  }).join('');
+
+  const pct=st.total>0?Math.round((st.success+st.failed+st.skipped)*100/st.total):0;
+  const summary=
+    '<div style="margin-bottom:12px">'+
+      '<div style="display:flex;gap:8px;margin-bottom:8px;font-size:13px;flex-wrap:wrap">'+
+        '<span>应用：<strong>'+esc(st.apk_name)+'</strong></span>'+
+        '<span class="label label-success">成功 '+st.success+'</span>'+
+        '<span class="label label-danger">失败 '+st.failed+'</span>'+
+        '<span class="label label-default">跳过 '+st.skipped+'</span>'+
+        '<span class="label label-warning">安装中 '+st.installing+'</span>'+
+        '<span class="label label-default">等待 '+st.pending+'</span>'+
+      '</div>'+
+      '<div class="progress" style="width:100%;height:8px"><div class="progress-bar" style="width:'+pct+'%"></div></div>'+
+    '</div>';
+
+  document.getElementById('install-progress').innerHTML=
+    summary+'<table class="table" style="margin-bottom:0"><thead><tr><th>设备</th><th>Serial</th><th>状态</th><th>详情</th></tr></thead><tbody>'+itemRows+'</tbody></table>';
+
+  if(st.finished){
+    if(_installTimer){clearInterval(_installTimer);_installTimer=null;}
+    document.getElementById('install-close-btn').style.display='';
+    showToast('安装完成：成功'+st.success+' 失败'+st.failed+' 跳过'+st.skipped,'success');
+  }
+}
+
+function closeInstallModal(){
+  if(_installTimer){clearInterval(_installTimer);_installTimer=null;}
+  closeModal();
+}
+
+

static/admin/base.js

@@ -0,0 +1,172 @@
+// 通用基础：esc/CSRF/权限/API/Toast、Tab 切换与页内子分栏、模态框、行内按钮操作
+// ================== 通用工具 ==================
+const ACTION_LABELS={like:'点赞',comment:'评论',follow:'关注',share:'分享'};
+const STATUS_MAP={idle:{t:'未启动',c:'default'},connecting:{t:'连接中',c:'warning'},running:{t:'运行中',c:'success'},done:{t:'完成',c:'primary'},error:{t:'异常',c:'danger'},released:{t:'已释放',c:'default'},failed:{t:'失败',c:'danger'}};
+const TARGET_MAP={all:'全部空闲',group:'按分组',serial:'指定设备'};
+const APP_NAMES={'com.ss.android.ugc.aweme':'抖音','com.ss.android.ugc.aweme.lite':'抖音极速版','com.smile.gifmaker':'快手','com.kuaishou.nebula':'快手极速版','com.tencent.mm':'微信','com.tencent.mobileqq':'QQ','com.tencent.qqlive':'腾讯视频','com.eg.android.AlipayGphone':'支付宝','com.taobao.taobao':'淘宝','com.tmall.wireless':'天猫','com.jingdong.app.mall':'京东','com.xunmeng.pinduoduo':'拼多多','com.ss.android.article.news':'今日头条','com.zhihu.android':'知乎','com.miui.home':'桌面','com.android.launcher':'桌面','com.android.settings':'设置','com.android.systemui':'系统','com.github.uiautomator':'U2','com.github.uiautomator.test':'U2测试'};
+
+function esc(s){return String(s||'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));}
+
+// ===== CSRF =====
+let _csrfToken='';
+// 页面加载后调用：获取 CSRF token，非 GET 请求需携带
+async function initCsrf(){
+  try{
+    const r=await fetch('/api/csrf');
+    const d=await r.json();
+    _csrfToken=d.token||'';
+  }catch(e){}
+}
+function _csrfHeaders(){
+  return _csrfToken?{'X-CSRF-Token':_csrfToken}:{};
+}
+
+// ===== 当前用户与权限 =====
+// _me 来自 /api/me：{username, is_admin, perms:[tasks/devices/apks/logs]}
+// 管理员 perms 恒为全部。无权限的功能入口（tab/按钮）用 data-perm 标记或 _can() 判断隐藏。
+let _me={is_admin:false,perms:[],username:''};
+async function loadMe(){
+  try{
+    const r=await apiGet('/api/me');
+    if(r&&r.ok)_me=r.user||{is_admin:false,perms:[],username:''};
+    const un=document.getElementById('me-username');
+    if(un)un.textContent=_me.username||'';
+    // 隐藏无权限的 tab 和按钮（data-perm="admin" 表示仅管理员）
+    document.querySelectorAll('[data-perm]').forEach(function(el){
+      const p=el.dataset.perm;
+      const ok=(p==='admin')?_me.is_admin:(_me.perms||[]).includes(p);
+      if(!ok)el.style.display='none';
+    });
+  }catch(e){}
+}
+function _can(perm){
+  return _me.is_admin||(_me.perms||[]).includes(perm);
+}
+const PERM_LABELS={tasks:'任务管理',devices:'设备控制',apks:'应用管理',logs:'日志查看'};
+
+async function apiGet(url){
+  const r=await fetch(url);
+  if(r.status===401){window.location='/login';return null;}
+  return r.json();
+}
+async function apiPost(url,body){
+  const r=await fetch(url,{method:'POST',headers:{'Content-Type':'application/json',..._csrfHeaders()},body:body?JSON.stringify(body):'{}'});
+  if(r.status===401){window.location='/login';return null;}
+  return r.json();
+}
+async function apiPut(url,body){
+  const r=await fetch(url,{method:'PUT',headers:{'Content-Type':'application/json',..._csrfHeaders()},body:body?JSON.stringify(body):'{}'});
+  if(r.status===401){window.location='/login';return null;}
+  return r.json();
+}
+
+async function apiDelete(url){
+  const r=await fetch(url,{method:'DELETE',headers:_csrfHeaders()});
+  if(r.status===401){window.location='/login';return null;}
+  return r.json();
+}
+
+function showToast(msg,type){
+  const t=document.getElementById('toast');
+  t.className='toast show toast-'+(type||'success');
+  t.textContent=msg;
+  setTimeout(()=>t.className='toast',3000);
+}
+function handleResult(r,callback){
+  if(!r)return;
+  if(r.ok){showToast(r.msg||'操作成功','success');if(callback)callback();}
+  else{showToast(r.error||'操作失败','error');}
+}
+
+// ================== Tab 切换 ==================
+let _activeTab='monitor';
+let _monitorTimer=null;
+let _logTimer=null;
+
+function showTab(name){
+  _activeTab=name;
+  document.querySelectorAll('.tab-panel').forEach(p=>p.classList.remove('active'));
+  document.querySelectorAll('.navbar .tab').forEach(t=>t.classList.remove('active'));
+  const panel=document.getElementById('tab-'+name);
+  if(panel)panel.classList.add('active');
+  const btn=document.querySelector('.navbar .tab[data-tab="'+name+'"]');
+  if(btn)btn.classList.add('active');
+  // 停止所有定时器
+  if(_monitorTimer){clearInterval(_monitorTimer);_monitorTimer=null;}
+  if(_logTimer){clearInterval(_logTimer);_logTimer=null;}
+  if(_discoveryTimer){clearInterval(_discoveryTimer);_discoveryTimer=null;}
+  // 按需加载数据
+  if(name==='monitor'){loadMonitor();_monitorTimer=setInterval(loadMonitor,5000);}
+  if(name==='tasks'){showSubTab('tasks',_activeSubs.tasks);loadTasks();loadCustomActions();}
+  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==='users')loadUsers();
+}
+
+// ================== 页内子分栏（任务/工具 通用） ==================
+// 每个带子分栏的 Tab 记住上次选中的子分栏，切走再切回来保持原位
+let _activeSubs = {tasks: 'plan', tools: 'clipboard'};
+let _discoveryTimer = null;   // 设备自动发现 10s 轮询（仅 devpool 子分栏激活时）
+
+function showSubTab(tabId, name){
+  _activeSubs[tabId] = name;
+  const tab = document.getElementById('tab-'+tabId);
+  tab.querySelectorAll('.sub-tab').forEach(b=>b.classList.toggle('active', b.dataset.sub===name));
+  tab.querySelectorAll('.sub-panel').forEach(p=>p.classList.toggle('active', p.id===tabId+'-sub-'+name));
+  if(name==='groups' && typeof loadGroups==='function') loadGroups();
+  if(name==='devpool' && typeof loadDevPool==='function'){
+    loadDevPool();
+    if(typeof loadDiscovery==='function'){
+      loadDiscovery();
+      if(_discoveryTimer){clearInterval(_discoveryTimer);_discoveryTimer=null;}
+      _discoveryTimer=setInterval(loadDiscovery,10000);   // 10s 轮询：扫完自动出新结果
+    }
+  } else if(_discoveryTimer){clearInterval(_discoveryTimer);_discoveryTimer=null;}
+}
+
+// ================== 模态框 ==================
+function showModal(){
+  document.getElementById('modal-overlay').classList.add('show');
+}
+function closeModal(){
+  // 先关闭弹窗（最重要的一步，确保一定执行）
+  const ov=document.getElementById('modal-overlay');
+  if(ov)ov.classList.remove('show');
+  // 再做清理工作，任何异常都不影响弹窗关闭
+  try{
+    stopShotTimer();
+    _shotSerial='';
+    const box=document.getElementById('modal-box');
+    if(box){box.classList.remove('shot-modal');box.classList.remove('wide-modal');}
+  }catch(e){console.warn('closeModal cleanup error:',e);}
+}
+
+// 测试此步骤弹窗关闭（editor.js 的测试按钮用；曾随 STF 清理误删）
+function closeTestModal(){
+  const ov=document.getElementById('test-overlay');
+  if(ov)ov.classList.remove('show');
+}
+
+// 关闭元素抓取弹窗（不影响任务编辑窗口）
+function closeElPicker(){
+  var ov=document.getElementById('el-picker-overlay');
+  if(ov)ov.classList.remove('show');
+  // 清理状态
+  try{ _stepEditor._elData=null; _stepEditor._elSerial=''; }catch(e){}
+}
+
+// ================== 行内按钮操作（停止/执行/启停等，自动 toast + 刷新）==================
+async function apiAction(url,body){
+  const r=await apiPost(url,body);
+  if(!r)return;
+  if(r.ok){showToast(r.msg||'操作成功','success');if(_activeTab==='monitor')loadMonitor();if(_activeTab==='tasks')loadTasks();}
+  else{showToast(r.error||'操作失败','error');}
+}
+
+async function scanForeground(){
+  const r=await apiPost('/api/scan_foreground');
+  if(!r)return;
+  if(r.ok){showToast('扫描已启动，请等待几秒...','success');loadMonitor();}
+  else{showToast(r.error||'扫描失败','error');}
+}
+

static/admin/list.js

@@ -0,0 +1,94 @@
+// 统一列表组件：setListPager 搜索 + 分页 + 排序（_lpSort）
+// ================== 通用列表：搜索 + 分页 + 排序 ==================
+// 用法：
+//   setListPager(key,{data:()=>array, filter:(item,kw)=>bool, render:(item)=>html,
+//                     tbody:'tb-id', pager:'pager-id', pageSize:N,
+//                     sortValue:(item,colKey)=>值,   // 可排序列的取值函数
+//                     empty:'<tr>...'});
+//   applyListPager(key);             // 数据变化后重渲染（含搜索/翻页/排序状态）
+//   initListSearch(key,'search-id'); // 搜索框绑定
+//   _lpSort(key,'colKey');           // 表头排序：th 加 data-sort="colKey" + onclick，
+//                                    // 再点切换升降序，第三次取消；排序指示器自动更新
+var _LIST_PAGERS={};
+
+function _lp(key){ return _LIST_PAGERS[key] || (_LIST_PAGERS[key]={page:1,kw:'',cfg:null,sort:null}); }
+
+function setListPager(key,cfg){
+  // 只更新配置，不重置 page/kw/sort —— 监控列表 5 秒自动刷新时保持用户当前状态
+  var st=_lp(key); st.cfg=cfg;
+}
+function initListSearch(key,inputId){
+  var input=document.getElementById(inputId);
+  if(!input||input.dataset.bound)return;
+  input.dataset.bound='1';
+  input.addEventListener('input',function(){
+    var st=_lp(key); st.kw=this.value.trim(); st.page=1; applyListPager(key);
+  });
+}
+function _lpSort(key,colKey){
+  var st=_lp(key);
+  if(st.sort&&st.sort.key===colKey){
+    if(st.sort.dir===1)st.sort.dir=-1;      // 升序 → 降序
+    else if(st.sort.dir===-1)st.sort=null;  // 降序 → 取消排序
+    else st.sort={key:colKey,dir:1};
+  }else{
+    st.sort={key:colKey,dir:1};
+  }
+  applyListPager(key);
+}
+function applyListPager(key){
+  var st=_lp(key);
+  if(!st.cfg)return;
+  var cfg=st.cfg;
+  var all=(cfg.data&&cfg.data())||[];
+  var kw=st.kw.toLowerCase();
+  var filtered=kw?all.filter(function(x){return cfg.filter(x,kw);}):all;
+  // 排序：cfg.sortValue 取列值；空值/缺失恒排最后；字符串用中文数字感知比较（10 排在 9 后）
+  if(st.sort&&cfg.sortValue){
+    var sk=st.sort.key, dir=st.sort.dir;
+    filtered=filtered.slice().sort(function(a,b){
+      var va=cfg.sortValue(a,sk), vb=cfg.sortValue(b,sk);
+      if(va===vb)return 0;
+      if(va==null||va==='')return 1;
+      if(vb==null||vb==='')return -1;
+      if(typeof va==='number'&&typeof vb==='number')return (va-vb)*dir;
+      return String(va).localeCompare(String(vb),'zh-Hans-CN',{numeric:true})*dir;
+    });
+  }
+  var pageSize=cfg.pageSize||10;
+  var pages=Math.max(1,Math.ceil(filtered.length/pageSize));
+  if(st.page>pages)st.page=pages;
+  if(st.page<1)st.page=1;
+  var start=(st.page-1)*pageSize;
+  var slice=filtered.slice(start,start+pageSize);
+  var tb=document.getElementById(cfg.tbody);
+  if(tb){
+    tb.innerHTML=slice.map(cfg.render).join('')||(cfg.empty||'<tr><td colspan="20" class="empty">无数据</td></tr>');
+    // 表头排序指示器（th[data-sort]，所有表格统一）
+    if(cfg.sortValue){
+      var table=tb.closest('table');
+      if(table)table.querySelectorAll('thead th[data-sort]').forEach(function(th){
+        th.classList.add('sortable');
+        th.classList.toggle('sort-asc',!!st.sort&&st.sort.key===th.dataset.sort&&st.sort.dir===1);
+        th.classList.toggle('sort-desc',!!st.sort&&st.sort.key===th.dataset.sort&&st.sort.dir===-1);
+      });
+    }
+  }
+  var pg=document.getElementById(cfg.pager);
+  if(pg)pg.innerHTML=_lpPagerHtml(key,pages,st.page,filtered.length,pageSize);
+}
+function _lpPagerHtml(key,pages,cur,total,pageSize){
+  if(pages<=1)return total>0?'<div class="list-pager"><span class="lp-total">共 '+total+' 条</span></div>':'';
+  var h='<div class="list-pager"><span class="lp-total">共 '+total+' 条</span>';
+  h+='<button class="btn btn-xs" onclick="_lpGo(\''+key+'\','+(cur-1)+')"'+(cur<=1?' disabled':'')+'>‹ 上一页</button>';
+  for(var p=Math.max(1,cur-2);p<=Math.min(pages,cur+2);p++){
+    h+='<button class="btn btn-xs'+(p===cur?' btn-primary':'')+'" onclick="_lpGo(\''+key+'\','+p+')">'+p+'</button>';
+  }
+  h+='<button class="btn btn-xs" onclick="_lpGo(\''+key+'\','+(cur+1)+')"'+(cur>=pages?' disabled':'')+'>下一页 ›</button>';
+  h+='</div>';
+  return h;
+}
+function _lpGo(key,p){
+  var st=_lp(key); st.page=p; applyListPager(key);
+}
+

static/admin/monitor.js

@@ -0,0 +1,483 @@
+// 监控页：设备状态表（排序/多选/截图/异常汇总/任务运行概况）
+// ================== 设备列表排序与多选 ==================
+let _selectedSerials=new Set();  // 已勾选的 serial 集合
+let _locatingSerials=new Set();  // 定位中的设备（按钮显示"结束定位"）
+
+// 排序比较：从设备对象取排序值（统一排序用，见 setListPager/sortValue）
+function _sortValue(dev,key){
+  let v;
+  if(key==='progress'){
+    const p=dev.progress||{};
+    v=(p.done||0)+(((p.total||0)>0?(p.done||0)/(p.total):0)*10000);
+  }else if(key==='worker_status'){
+    // 按状态优先级排序：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{
+    v=dev[key]||'';
+  }
+  return v;
+}
+
+// 全选/取消全选
+function toggleAllDevices(checked){
+  if(checked){
+    _statusData.devices.forEach(d=>_selectedSerials.add(d.serial));
+  }else{
+    _selectedSerials.clear();
+  }
+  renderDevices();
+  updateSelCount();
+}
+
+// 单个勾选
+function toggleDevice(serial,checked){
+  if(checked){_selectedSerials.add(serial);}else{_selectedSerials.delete(serial);}
+  updateSelCount();
+  // 同步全选框状态
+  const all=document.getElementById('cb-all');
+  if(all){
+    const total=_statusData?(_statusData.devices||[]).length:0;
+    all.checked=total>0&&_selectedSerials.size===total;
+  }
+}
+
+function updateSelCount(){
+  const n=_selectedSerials.size;
+  const el=document.getElementById('sel-count');
+  if(el)el.textContent=n>0?('已选 '+n+' 台'):'未选中';
+  const btn=document.getElementById('btn-stop-selected');
+  if(btn)btn.disabled=n===0;
+}
+
+// 批量停止选中的运行中设备
+async function stopSelectedDevices(){
+  const serials=Array.from(_selectedSerials);
+  if(serials.length===0){showToast('请先勾选设备','error');return;}
+  // 只停止运行中/连接中的
+  const toStop=serials.filter(s=>{
+    const d=(_statusData.devices||[]).find(x=>x.serial===s);
+    return d&&(d.worker_status==='running'||d.worker_status==='connecting');
+  });
+  if(toStop.length===0){showToast('选中的设备没有运行中的任务','error');return;}
+  if(!confirm('确定停止选中的 '+toStop.length+' 台设备的任务吗？'))return;
+  let ok=0,fail=0;
+  for(const s of toStop){
+    const r=await apiPost('/api/stop_device',{serial:s});
+    if(r&&r.ok){ok++;}else{fail++;}
+  }
+  showToast('已停止 '+ok+' 台'+(fail>0?('，失败 '+fail+' 台'):''),ok>0?'success':'error');
+  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});
+  if(!r)return;
+  if(r.ok){
+    _locatingSerials.add(serial);
+    showToast(r.msg||'已定位','success');
+    renderDevices();
+  }else showToast(r.error||'定位失败','error');
+}
+
+// 结束定位：关闭设备上的定位页（浏览器），按钮恢复为"定位"
+async function stopLocate(serial){
+  const r=await apiPost('/api/device/locate/stop',{serial:serial});
+  if(!r)return;
+  _locatingSerials.delete(serial);
+  renderDevices();
+  if(r.ok)showToast(r.msg||'已结束定位','success');
+  else showToast(r.error||'结束定位失败','error');
+}
+
+// 批量亮屏/息屏所有在线设备（息屏会中断运行中任务，前端已确认）
+// 亮屏/息屏：优先作用于勾选设备；未勾选则作用于全部在线设备
+async function screenAllDevices(mode){
+  const label=(mode==='on'?'亮屏':'息屏');
+  const selected=Array.from(_selectedSerials);
+  const target=selected.length?('选中设备 '+selected.length+' 台'):'全部在线设备';
+  if(!confirm(label+'：将作用于'+target+'。\n\n'+(mode==='off'?'息屏会中断运行中的任务（u2 无法操作），':'')+'确认继续吗？'))return;
+  const r=await apiPost('/api/device/screen_all',{mode:mode,serials:selected.length?selected:undefined});
+  if(!r)return;
+  if(r.ok)showToast((mode==='off'?'已息屏':'已亮屏')+' '+r.success+'/'+r.total+' 台设备','success');
+  else showToast(r.error||'操作失败','error');
+}
+
+// 清除单台设备的异常状态（error/failed → 未启动）
+async function clearDeviceError(serial){
+  if(!confirm('确认清除设备 '+serial+' 的异常状态？'))return;
+  const r=await apiPost('/api/device/clear_error',{serial:serial});
+  handleResult(r,()=>loadMonitor());
+}
+// 一键清除所有异常/失败设备的错误状态（运行中的任务不受影响）
+async function clearAllErrors(){
+  if(!confirm('确认清除所有设备的异常状态？（运行中/等待重试的设备会跳过）'))return;
+  const r=await apiPost('/api/device/clear_all_errors');
+  handleResult(r,()=>loadMonitor());
+}
+
+// ================== 设备画面查看 ==================
+let _shotTimer=null;       // 自动刷新定时器
+let _shotSerial='';        // 当前查看的 serial
+let _shotLoading=false;    // 防止并发请求
+
+// 打开截图弹窗
+function openScreenshot(serial){
+  _shotSerial=serial;
+  _shotLoading=false;
+  // 渲染弹窗
+  document.getElementById('modal-title').textContent='设备画面 - '+serial;
+  document.getElementById('modal-body').innerHTML=
+    '<div id="shot-content" class="shot-loading">正在获取画面...</div>'+
+    '<div class="shot-toolbar">'+
+      '<button class="btn btn-primary btn-sm" onclick="refreshShot()">刷新</button>'+
+      '<label class="auto-label"><input type="checkbox" id="shot-auto" checked onchange="toggleShotAuto()"> 自动刷新(3秒)</label>'+
+      '<span class="shot-info" id="shot-time"></span>'+
+    '</div>';
+  document.getElementById('modal-footer').innerHTML='<button class="btn" onclick="closeShotModal()">关闭</button>';
+  // 切换为截图弹窗样式（自适应大小）
+  document.getElementById('modal-box').classList.add('shot-modal');
+  showModal();
+  // 立即取一次
+  refreshShot();
+  // 开启自动刷新
+  startShotTimer();
+}
+
+// 关闭截图弹窗（停掉定时器 + 关闭 modal + 还原样式）
+function closeShotModal(){
+  stopShotTimer();
+  _shotSerial='';
+  document.getElementById('modal-box').classList.remove('shot-modal');
+  closeModal();
+}
+
+function toggleShotAuto(){
+  const cb=document.getElementById('shot-auto');
+  if(cb&&cb.checked){startShotTimer();}else{stopShotTimer();}
+}
+
+function startShotTimer(){
+  stopShotTimer();
+  _shotTimer=setInterval(refreshShot,3000);
+}
+function stopShotTimer(){
+  // 用 typeof 容错：变量未声明时不报错（避免 closeModal 调用时抛异常导致弹窗关不掉）
+  if(typeof _shotTimer!=='undefined'&&_shotTimer){clearInterval(_shotTimer);_shotTimer=null;}
+}
+
+// 取一次截图
+async function refreshShot(){
+  if(!_shotSerial)return;
+  if(_shotLoading)return;  // 上一次还没回来，跳过这次
+  _shotLoading=true;
+  const el=document.getElementById('shot-content');
+  if(!el){_shotLoading=false;return;}
+  // 首次或出错后显示 loading
+  if(!el.querySelector('img')){
+    el.className='shot-loading';
+    el.textContent='正在获取画面...';
+  }
+  const url='/api/device/screenshot?serial='+encodeURIComponent(_shotSerial)+'&t='+Date.now();
+  try{
+    const r=await fetch(url);
+    if(r.status===401){window.location='/login';return;}
+    if(!r.ok){
+      const j=await r.json().catch(()=>({}));
+      throw new Error(j.error||('HTTP '+r.status));
+    }
+    const blob=await r.blob();
+    const objUrl=URL.createObjectURL(blob);
+    el.className='';
+    el.innerHTML='<img class="shot-img" src="'+objUrl+'" alt="设备画面">';
+    // 更新时间
+    const tEl=document.getElementById('shot-time');
+    if(tEl)tEl.textContent='更新于 '+new Date().toLocaleTimeString();
+    // 释放上一个 objUrl（避免内存泄漏）
+    if(el._lastObjUrl)URL.revokeObjectURL(el._lastObjUrl);
+    el._lastObjUrl=objUrl;
+  }catch(e){
+    el.className='shot-err';
+    el.textContent='截图失败：'+e.message;
+  }finally{
+    _shotLoading=false;
+  }
+}
+// ================== Tab 1: 监控 ==================
+let _statusData=null;
+let _jobsData=null;
+
+async function loadMonitor(){
+  try{
+    const r=await apiGet('/api/status');if(!r||!r.ok)return;
+    _statusData=r;
+    document.getElementById('srvTime').textContent=new Date(r.server_time*1000).toLocaleTimeString();
+    // 前台 App 扫描状态
+    const fgStatus=document.getElementById('fg-status');
+    const scanBtn=document.getElementById('btn-scan-fg');
+    if(r.fg_scanning){
+      fgStatus.innerHTML='<span style="color:#f59e0b">扫描中...</span>';
+      scanBtn.disabled=true;scanBtn.textContent='扫描中...';
+    }else{
+      scanBtn.disabled=false;scanBtn.textContent='扫描前台App';
+      if(r.fg_last_scan){
+        fgStatus.innerHTML='上次扫描: '+new Date(r.fg_last_scan*1000).toLocaleTimeString();
+      }else{
+        fgStatus.innerHTML='<span style="color:#94a3b8">未扫描</span>';
+      }
+    }
+    const devices=r.devices||[];
+    const running=devices.filter(x=>x.worker_status==='running').length;
+    const idle=devices.filter(x=>x.worker_status==='idle').length;
+    const error=devices.filter(x=>['error','failed'].includes(x.worker_status)).length;
+    const total=devices.length;
+    const online=devices.filter(x=>x.present).length;
+    const cards=[
+      {n:total,l:'设备总数',c:'#3b82f6'},
+      {n:online,l:'在线',c:'#10b981'},
+      {n:running,l:'运行中',c:'#10b981'},
+      {n:idle,l:'空闲',c:'#94a3b8'},
+      {n:error,l:'异常',c:'#ef4444'},
+    ];
+    document.getElementById('stats').innerHTML=cards.map(c=>
+      '<div class="stat-card" style="--accent:'+c.c+'"><div class="stat-num" style="color:'+c.c+'">'+c.n+'</div><div class="stat-lbl">'+c.l+'</div></div>'
+    ).join('');
+    // 渲染设备表格（含排序+多选）
+    renderDevices();
+    // 同步全选框状态
+    const all=document.getElementById('cb-all');
+    if(all){
+      all.checked=devices.length>0&&_selectedSerials.size===devices.length;
+    }
+    updateSelCount();
+    // 加载任务卡片
+    loadJobsForMonitor();
+    // 加载异常汇总
+    loadSummary();
+  }catch(e){console.error(e);}
+}
+
+// ===== 异常设备汇总 =====
+async function loadSummary(){
+  try{
+    const r=await apiGet('/api/summary');
+    if(!r||!r.ok)return;
+    const counts=r.counts||{};
+    const errors=r.errors||[];
+    const errCount=(counts.error||0)+(counts.failed||0);
+    const badge=document.getElementById('summary-badge');
+    const panel=document.getElementById('summary-panel');
+    const empty=document.getElementById('summary-empty');
+    if(badge)badge.textContent='· 异常 '+errCount+' · 运行 '+counts.running+' · 完成 '+counts.done;
+    if(!panel||!empty)return;
+    if(!errors.length){
+      panel.style.display='none';
+      empty.style.display='block';
+      return;
+    }
+    panel.style.display='block';
+    empty.style.display='none';
+    const tb=document.getElementById('tb-summary');
+    tb.innerHTML=errors.map(e=>{
+      const st=e.status==='failed'?'<span class="label label-danger">失败</span>':'<span class="label label-warning">异常</span>';
+      const up=e.updated?new Date(e.updated*1000).toLocaleTimeString():'';
+      return '<tr>'+
+        '<td><strong>'+esc(e.serial)+'</strong>'+(e.model?' <span style="font-size:11px;color:#94a3b8">'+esc(e.model)+'</span>':'')+'</td>'+
+        '<td>'+st+'</td>'+
+        '<td>'+esc(e.task||'-')+'</td>'+
+        '<td>'+(e.attempt>0?e.attempt+'次':'<span class="text-muted">-</span>')+'</td>'+
+        '<td class="err-text" title="'+esc(e.last_error||'')+'">'+esc(e.last_error||'-')+'</td>'+
+      '</tr>';
+    }).join('');
+  }catch(e){console.error(e);}
+}
+
+// 渲染设备表格（统一排序+搜索+分页，复选状态保持）
+let _devicesSig='';
+function renderDevices(){
+  if(!_statusData||!_statusData.devices){return;}
+  // 5秒自动刷新时若设备数据/分页/搜索/排序/定位状态都没变化，跳过整表重渲染（避免DOM抖动）
+  const _st=_lp('devices');
+  const _sig=JSON.stringify({d:_statusData.devices,p:_st.page,k:_st.kw,s:_st.sort,
+                             l:[..._locatingSerials].sort().join(','),
+                             sel:[..._selectedSerials].sort().join(',')});
+  if(_sig===_devicesSig)return;
+  _devicesSig=_sig;
+  // 排序由 applyListPager 统一处理（sortValue + _lpSort）
+  // 「只看在线」勾选时过滤离线设备（默认勾选）
+  const onlyOnline=document.getElementById('monitor-filter-online')
+    ? document.getElementById('monitor-filter-online').checked : true;
+  setListPager('devices',{
+    data:()=>{
+      const all=_statusData.devices||[];
+      return onlyOnline? all.filter(d=>d.present) : all;
+    },
+    filter:(dev,kw)=>((dev.serial||'').toLowerCase().includes(kw)||(dev.model||'').toLowerCase().includes(kw)||(dev.foreground_app||'').toLowerCase().includes(kw)||(dev.task_job||'').toLowerCase().includes(kw)||(dev.current_action||'').toLowerCase().includes(kw)),
+    sortValue:_sortValue,
+    render:renderDeviceRow,
+    tbody:'tb-devices',pager:'pager-devices',pageSize:10,
+    empty:'<tr><td colspan="11" class="empty">暂无设备</td></tr>'
+  });
+  applyListPager('devices');
+  initListSearch('devices','search-devices');
+}
+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'};
+  const wb='<span class="label label-'+st.c+'">'+st.t+'</span>';
+  const fgApp=dev.foreground_app;
+  const fg=fgApp?(
+    fgApp==='(他人占用)'?'<span class="label label-warning">他人占用</span>':
+    fgApp==='(不可达)'?'<span class="label label-default">不可达</span>':
+    '<span class="label label-primary">'+esc(APP_NAMES[fgApp]||fgApp)+'</span>'
+  ):'<span class="text-muted">-</span>';
+  const prog=fmtProgress(dev.progress, dev.worker_status);
+  const tname=dev.task_job?'<span class="label label-info">'+esc(dev.task_job)+'</span>':'<span class="text-muted">-</span>';
+  const retry=dev.attempt>0?' <span class="text-muted">'+dev.attempt+'次</span>':'';
+  // 预计结束时间（设置了运行时长上限时显示）
+  const endInfo=(dev.worker_status==='running'&&dev.end_time)?'<div style="font-size:11px;color:#94a3b8">预计结束 '+new Date(dev.end_time*1000).toLocaleTimeString()+'</div>':'';
+  // 选择器健康警告（某步骤连续未找到元素，可能 App 改版选择器失效）
+  const warnInfo=dev.last_warning?'<div style="font-size:11px;color:#f59e0b" title="'+esc(dev.last_warning)+'">⚠ '+esc(dev.last_warning)+'</div>':'';
+  // 设备操作按钮需要"设备控制"权限（无权限只保留截图查看）
+  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 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>'):'';
+  // 异常/失败设备提供"清除异常"（把状态恢复为未启动）
+  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 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>';
+}
+
+async function loadJobsForMonitor(){
+  try{
+    const r=await apiGet('/api/jobs');if(!r||!r.ok)return;
+    _jobsData=r.jobs||[];
+    renderJobCards();
+  }catch(e){console.error(e);}
+}
+
+// 通用进度展示：解析 progress = {done, total, unit, action_counts, elapsed}
+// 任意 app 都能用：显示进度条 + "done/total unit" + 运行时长 + 操作计数徽章
+// 下次运行时间格式化："2026-08-12 09:00:00" → "08-12 09:00"
+function fmtNextRun(iso){
+  if(!iso)return '';
+  const s=String(iso).replace('T',' ');
+  return s.length>=16?s.slice(5,16):s;
+}
+
+function fmtProgress(progress, workerStatus){
+  if(!progress||!Object.keys(progress).length){
+    // 空闲/未运行 → 显示"-"
+    return '<span class="text-muted">-</span>';
+  }
+  const done=progress.done||0;
+  const total=progress.total||0;
+  const unit=progress.unit||'';
+  const elapsed=progress.elapsed||0;
+  const counts=progress.action_counts||{};
+  // 进度条（百分比）
+  let barHtml='';
+  if(total>0){
+    const pct=Math.min(100,Math.round(done*100/total));
+    barHtml='<div class="progress"><div class="progress-bar" style="width:'+pct+'%"></div></div> ';
+  }
+  // 计数文本："5/80 视频" 或 "5 视频"（无 total 时）
+  let countHtml='';
+  if(total>0){
+    countHtml='<span style="font-size:12px;color:#64748b">'+done+'/'+total+(unit?' '+esc(unit):'')+'</span>';
+  }else if(done>0){
+    countHtml='<span style="font-size:12px;color:#64748b">'+done+(unit?' '+esc(unit):'')+'</span>';
+  }
+  // 运行时长（elapsed>0 才显示）
+  let timeHtml='';
+  if(elapsed>0){
+    const m=Math.floor(elapsed/60), s=elapsed%60;
+    timeHtml=' <span style="font-size:11px;color:#94a3b8">'+m+'m'+s+'s</span>';
+  }
+  // 操作计数徽章（按数量降序，最多显示6个，超出的折叠为 +N）
+  const countEntries=Object.entries(counts).filter(([_,v])=>v>0).sort((a,b)=>b[1]-a[1]);
+  const MAX_COUNTS=6;
+  const shown=countEntries.slice(0,MAX_COUNTS);
+  const more=countEntries.length-MAX_COUNTS;
+  let countsHtml='';
+  if(shown.length){
+    countsHtml='<div style="margin-top:2px">'+shown.map(([k,v])=>
+      '<span class="label label-info" style="margin-left:4px;font-size:11px">'+(ACTION_LABELS[k]||esc(k))+' '+v+'</span>'
+    ).join('')+(more>0?' <span style="font-size:11px;color:#94a3b8">+'+more+'</span>':'')+'</div>';
+  }
+  // 空闲/完成但无进度数据 → 灰显
+  if(done===0&&total===0&&elapsed===0&&!countParts.length){
+    return '<span class="text-muted">-</span>';
+  }
+  return '<div>'+barHtml+countHtml+timeHtml+'</div>'+countsHtml;
+}
+
+function fmtParams(params){
+  if(!params||!Object.keys(params).length)return '';
+  const parts=[];
+  for(const [k,v] of Object.entries(params)){
+    if(k==='actions'){
+      if(v&&Object.keys(v).length){
+        const on=Object.entries(v).filter(([_,c])=>c.enabled).map(([a])=>ACTION_LABELS[a]||a);
+        if(on.length)parts.push('<span class="kv">操作:'+on.join('/')+'</span>');
+      }
+      continue;
+    }
+    const val=typeof v==='boolean'?(v?'开':'关'):(Array.isArray(v)?v.length+'条':v);
+    parts.push('<span class="kv">'+k+'='+val+'</span>');
+  }
+  return parts.join('');
+}
+
+function renderJobCards(){
+  const jobs=_jobsData||[];
+  const running={};
+  if(_statusData)for(const dev of _statusData.devices){
+    if(dev.task_job)running[dev.task_job]=(running[dev.task_job]||0)+1;
+  }
+  document.getElementById('jobs-grid').innerHTML=jobs.length?jobs.map(j=>{
+    const runCount=running[j.name]||0;
+    const isRunning=runCount>0;
+    const tgt=TARGET_MAP[j.target.mode]||j.target.mode;
+    const tgtDetail=j.target.mode==='group'?(j.target.group_name||''):(j.target.mode==='serial'?(j.target.serial||''):'');
+    const sched=j.schedule.mode==='cron_stop'?('启停 '+j.schedule.cron+'→'+j.schedule.stop_cron):
+                 j.schedule.mode==='cron'?('定时 '+j.schedule.cron):'手动';
+    const retry=j.retry.max_attempts>1?(j.retry.max_attempts+'次/间隔'+j.retry.delay+'s'):'不重试';
+    const en=j.enabled?'<span class="label label-success">启用</span>':'<span class="label label-default">停用</span>';
+    const runBadge=isRunning?'<span class="label label-success pulse">运行中 '+runCount+'台</span>':'<span class="label label-default">空闲</span>';
+    return '<div class="job-card'+(isRunning?' running':'')+'">'+
+      '<div class="job-head"><div><div class="job-name">'+esc(j.name)+'</div>'+
+      '<div class="job-type">'+esc(j.task_type)+'</div></div>'+
+      '<div>'+en+' '+runBadge+'</div></div>'+
+      '<div class="job-body">'+
+        '<div><span class="kv">目标:'+esc(tgt)+(tgtDetail?'('+esc(tgtDetail)+')':'')+'</span>'+
+        '<span class="kv">调度:'+esc(sched)+'</span>'+
+        '<span class="kv">重试:'+esc(retry)+'</span></div>'+
+        '<div style="margin-top:4px">'+fmtParams(j.params)+'</div>'+
+      '</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>'+
+      '</div>'+
+    '</div>';
+  }).join(''):'<div class="empty">暂无任务，到"任务"Tab 新建</div>';
+}
+

static/admin/tasks.js

@@ -0,0 +1,331 @@
+// 任务 Tab：任务计划 CRUD/调度解析/运行窗口 + 自定义动作管理
+// ================== Tab 2: 任务 ==================
+let _taskTypes=[];
+let _groupsList=[];
+let _devicesList=[];
+
+async function loadTasks(){
+  const [jr,gr,dr,tr]=await Promise.all([
+    apiGet('/api/jobs'),apiGet('/api/groups'),apiGet('/api/devices'),apiGet('/api/task_types')
+  ]);
+  if(!jr)return;
+  _jobsData=jr.jobs||[];
+  _taskTypes=tr?tr.task_types||[]:[];
+  _groupsList=gr?gr.groups||[]:[];
+  _devicesList=dr?dr.devices||[]:[];
+  renderTaskTable();
+}
+
+function renderTaskTable(){
+  const jobs=_jobsData||[];
+  setListPager('tasks',{
+    data:()=>jobs,
+    filter:(j,kw)=>((j.name||'').toLowerCase().includes(kw)||(j.task_type||'').toLowerCase().includes(kw)||(j.id||'').toLowerCase().includes(kw)),
+    sortValue:(j,k)=>{ if(k==='id')return j.id||''; if(k==='enabled')return j.enabled?1:0; if(k==='next_run')return j.next_run||''; return j[k]||''; },
+    render:renderTaskRow,
+    tbody:'tb-tasks',pager:'pager-tasks',pageSize:10,
+    empty:'<tr><td colspan="9" class="empty">暂无任务，点击"新建任务"创建</td></tr>'
+  });
+  applyListPager('tasks');
+  initListSearch('tasks','search-tasks');
+}
+function renderTaskRow(j){
+  const tgt=TARGET_MAP[j.target.mode]||j.target.mode;
+  const tgtDetail=j.target.mode==='group'?(j.target.group_name||''):(j.target.mode==='serial'?(j.target.serial||''):'');
+  const sched=j.schedule.mode==='cron_stop'?('启停 '+cronToText(j.schedule.cron||'')+' → '+cronToText(j.schedule.stop_cron||'')):
+               j.schedule.mode==='cron'?('定时 '+cronToText(j.schedule.cron||'')):'手动';
+  const schedTxt=sched+((j.schedule.window&&j.schedule.window.start&&j.schedule.window.end)
+    ?' [窗口 '+esc(j.schedule.window.start)+'-'+esc(j.schedule.window.end)+']':'');
+  const schedOut='<td>'+schedTxt+'</td>';
+  // 下次运行时间（后端已按运行窗口跳过窗口外触发点）
+  const nextRun=fmtNextRun(j.next_run);
+  const nextOut='<td>'+(nextRun||'<span class="text-muted">-</span>')+'</td>';
+  const retry=j.retry.max_attempts>1?(j.retry.max_attempts+'次/'+j.retry.delay+'s'):'不重试';
+  const en=j.enabled?'<span class="label label-success">启用</span>':'<span class="label label-default">停用</span>';
+  return '<tr>'+
+    '<td><code>'+esc(j.id)+'</code></td>'+
+    '<td><strong>'+esc(j.name)+'</strong></td>'+
+    '<td>'+esc(j.task_type)+'</td>'+
+    '<td>'+en+'</td>'+
+    '<td>'+esc(tgt)+(tgtDetail?'('+esc(tgtDetail)+')':'')+'</td>'+
+    schedOut+
+    nextOut+
+    '<td>'+retry+'</td>'+
+    '<td>'+
+      (_can('tasks')?(
+        '<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>'
+      ):'<span class="text-muted">只读</span>')+
+    '</td>'+
+  '</tr>';
+}
+
+function openTaskModal(jobId){
+  const job=jobId?(_jobsData||[]).find(j=>j.id===jobId):null;
+  const isEdit=!!job;
+  document.getElementById('modal-title').textContent=isEdit?'编辑任务':'新建任务';
+  // 任务编辑器含步骤编辑，加宽弹窗；关闭时在 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 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 sm=j.schedule.mode;
+  const startCron=(sm==='cron'||sm==='cron_stop')?(j.schedule.cron||''):'';
+  const stopCron=sm==='cron_stop'?(j.schedule.stop_cron||''):'';
+  // 运行窗口（每天时间段，窗口外不启动）
+  const win=j.schedule.window||null;
+  const winStart=win?(win.start||'09:00'):'09:00';
+  const winEnd=win?(win.end||'18:00'):'18:00';
+  // 简单调度：把已有 cron 解析回"频率+时间"，编辑时回填；解析不了落到自定义
+  const sc=parseCronToFreq(startCron);
+  const stopF=parseCronToFreq(stopCron).time;
+  const weekdayOpts=[0,1,2,3,4,5,6].map(w=>
+    '<option value="'+w+'"'+(sc.weekday===w?' selected':'')+'>'+WEEKDAY_NAMES[w]+'</option>').join('');
+
+  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><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>'+
+    '<div class="form-group"><label>目标设备</label>'+
+      '<select class="form-control" id="f-target_mode" onchange="toggleTargetFields()">'+
+        '<option value="all"'+(j.target.mode==='all'?' selected':'')+'>全部空闲设备</option>'+
+        '<option value="group"'+(j.target.mode==='group'?' selected':'')+'>按分组</option>'+
+        '<option value="serial"'+(j.target.mode==='serial'?' selected':'')+'>指定设备</option>'+
+      '</select>'+
+      '<div id="f-target_group_wrap" class="form-group" style="margin-top:8px;margin-bottom:0">'+
+        '<select class="form-control" id="f-target_group"><option value="">选择分组...</option>'+gl+'</select>'+
+      '</div>'+
+      '<div id="f-target_serial_wrap" class="form-group" style="margin-top:8px;margin-bottom:0">'+
+        '<select class="form-control" id="f-target_serial"><option value="">选择设备...</option>'+dl+'</select>'+
+      '</div>'+
+      '<div class="form-check" style="margin-top:8px">'+
+        '<input type="checkbox" id="f-skip_offline" '+(j.params&&j.params.skip_offline===false?'':'checked')+'>'+
+        '<label for="f-skip_offline">离线设备自动跳过（推荐）</label>'+
+      '</div>'+
+      '<div class="form-check" style="margin-top:6px">'+
+        '<input type="checkbox" id="f-preempt" '+(j.params&&j.params.preempt?'checked':'')+'>'+
+        '<label for="f-preempt" title="触发时停止目标设备上正在运行的其他任务，接管设备执行本任务">抢占设备（打断其他任务）</label>'+
+      '</div>'+
+    '</div>'+
+    '<div class="form-row">'+
+      '<div class="form-group"><label>调度方式</label>'+
+        '<select class="form-control" id="f-schedule_mode" onchange="toggleScheduleFields()">'+
+          '<option value="once"'+(sm==='once'?' selected':'')+'>手动（不自动启动）</option>'+
+          '<option value="cron"'+(sm==='cron'?' selected':'')+'>定时启动</option>'+
+          '<option value="cron_stop"'+(sm==='cron_stop'?' selected':'')+'>定时启动+停止</option>'+
+        '</select>'+
+      '</div>'+
+      '<div class="form-group" id="f-freq_wrap" style="display:none"><label>频率</label>'+
+        '<select class="form-control" id="f-schedule_freq" onchange="toggleScheduleFields()">'+
+          '<option value="daily"'+((sc.freq==='daily')?' selected':'')+'>每天</option>'+
+          '<option value="hourly"'+((sc.freq==='hourly')?' selected':'')+'>每小时（整点）</option>'+
+          '<option value="everyN"'+((sc.freq==='everyN')?' selected':'')+'>每隔 N 小时</option>'+
+          '<option value="weekly"'+((sc.freq==='weekly')?' selected':'')+'>每周</option>'+
+          '<option value="custom"'+((sc.freq==='custom')?' selected':'')+'>自定义 cron（高级）</option>'+
+        '</select>'+
+      '</div>'+
+      '<div class="form-group" id="f-time_wrap" style="display:none"><label>启动时间</label><input type="time" class="form-control" id="f-schedule_time" value="'+esc(sc.time||'09:00')+'"></div>'+
+      '<div class="form-group" id="f-interval_wrap" style="display:none"><label>间隔（小时）</label><input type="number" class="form-control" id="f-schedule_interval" value="'+(sc.interval||2)+'" min="1" max="12"><div class="help">从 0 点起算，如 2 = 0/2/4/6...点启动</div></div>'+
+      '<div class="form-group" id="f-weekday_wrap" style="display:none"><label>星期</label><select class="form-control" id="f-schedule_weekday">'+weekdayOpts+'</select></div>'+
+      '<div class="form-group" id="f-cron_wrap" style="display:none"><label>启动 Cron 表达式</label><input type="text" class="form-control" id="f-schedule_cron" value="'+esc(startCron)+'" placeholder="如 0 9 * * * = 每天9点启动" style="font-family:monospace"><div class="help">格式：分 时 日 月 周（0 0 * * 0 = 每周日零点）</div></div>'+
+      '<div class="form-group" id="f-stop_wrap" style="display:none"><label>停止时间（每天）</label><input type="time" class="form-control" id="f-schedule_stop_time" value="'+esc(stopF||'18:00')+'"><div class="help">到点自动停止所有运行中的 worker</div></div>'+
+    '</div>'+
+    '<div class="form-group form-check" style="margin-top:4px"><input type="checkbox" id="f-window_enable" '+(win?'checked':'')+' onchange="toggleWindowFields()"><label for="f-window_enable">启用运行窗口（只在指定时间段内运行）</label></div>'+
+    '<div class="form-row" id="f-window_wrap" style="display:'+(win?'flex':'none')+'">'+
+      '<div class="form-group"><label>允许运行·开始</label><input type="time" class="form-control" id="f-window_start" value="'+esc(winStart)+'"></div>'+
+      '<div class="form-group"><label>允许运行·结束</label><input type="time" class="form-control" id="f-window_end" value="'+esc(winEnd)+'"></div>'+
+    '</div>'+
+    '<div class="help" id="f-window_help" style="display:'+(win?'block':'none')+'">窗口只约束定时触发：窗口外定时不会启动，手动执行不受限制。跨午夜示例：21:00-09:00 = 晚 9 点到次日早 9 点允许运行</div>'+
+    '<div class="form-row">'+
+      '<div class="form-group"><label>重试次数</label><input type="number" class="form-control" id="f-retry_attempts" value="'+j.retry.max_attempts+'" min="1" max="10"></div>'+
+      '<div class="form-group"><label>重试间隔(秒)</label><input type="number" class="form-control" id="f-retry_delay" value="'+j.retry.delay+'" min="10" max="3600"></div>'+
+    '</div>'+
+    '<div class="form-group" id="f-params_wrap"><label>任务参数 (JSON)</label><textarea class="form-control" id="f-params" rows="6">'+esc(JSON.stringify(j.params||{},null,2))+'</textarea><div class="help">可留空使用默认参数。抖音任务可设 max_duration（秒，如 1800=30分钟）限制单设备运行时长</div></div>'+
+    '<div class="step-editor" id="step-editor">'+
+      '<div class="se-head"><span>步骤编辑器</span><span style="font-size:11px;color:var(--text-light);flex:1;margin-left:12px">用步骤卡片上的 ☑ 选中多个步骤，可打包成自定义动作</span>'+
+        (_can('tasks')?'<button class="btn btn-xs btn-primary" id="se-pack-btn" disabled onclick="_stepEditor.saveAsCustomAction()">打包选中步骤</button>':'')+
+      '</div>'+
+      '<div class="se-body">'+
+        '<div class="se-lib" id="se-lib"><div class="lib-title">操作库</div></div>'+
+        '<div class="se-canvas" id="se-canvas"></div>'+
+      '</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||'');
+
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">取消</button>'+
+    '<button class="btn btn-primary" onclick="saveTask('+(isEdit?'\''+jobId+'\'':'null')+')">'+(isEdit?'保存':'创建')+'</button>';
+
+  toggleTargetFields();
+  toggleScheduleFields();
+  onTaskTypeChange();
+  showModal();
+}
+
+function toggleTargetFields(){
+  const mode=document.getElementById('f-target_mode').value;
+  document.getElementById('f-target_group_wrap').style.display=mode==='group'?'block':'none';
+  document.getElementById('f-target_serial_wrap').style.display=mode==='serial'?'block':'none';
+}
+
+// ===== 简单调度：cron(5段) ↔ 频率+时间 互转 =====
+const WEEKDAY_NAMES=['周日','周一','周二','周三','周四','周五','周六'];
+// cron → 简单设置 {freq: daily|hourly|everyN|weekly|custom, time:"HH:MM", interval, weekday(0-6)}
+function parseCronToFreq(cron){
+  const r={freq:'custom',time:'',interval:2,weekday:1};
+  const p=(cron||'').trim().split(/\s+/);
+  if(p.length!==5)return r;
+  const [mi,h,d,m,w]=p;
+  if(mi==='0'&&h==='*'&&d==='*'&&m==='*'&&w==='*'){r.freq='hourly';return r;}
+  const n=(h.match(/^\*\/(\d+)$/)||[])[1];  // 每隔N小时：时位是 */N
+  if(n&&mi==='0'&&d==='*'&&m==='*'&&w==='*'){r.freq='everyN';r.interval=parseInt(n)||2;return r;}
+  if(/^\d{1,2}$/.test(mi)&&/^\d{1,2}$/.test(h)&&d==='*'&&m==='*'&&w==='*'){
+    r.freq='daily';r.time=h.padStart(2,'0')+':'+mi.padStart(2,'0');return r;
+  }
+  if(/^\d{1,2}$/.test(mi)&&/^\d{1,2}$/.test(h)&&d==='*'&&m==='*'&&/^[0-7]$/.test(w)){
+    r.freq='weekly';r.time=h.padStart(2,'0')+':'+mi.padStart(2,'0');r.weekday=parseInt(w)%7;return r;
+  }
+  return r; // 解析不了 → 落到自定义
+}
+// 表单 → cron(5段)
+function buildCronFromFreq(){
+  const freq=document.getElementById('f-schedule_freq').value;
+  if(freq==='custom')return document.getElementById('f-schedule_cron').value.trim();
+  if(freq==='hourly')return '0 * * * *';
+  if(freq==='everyN'){
+    const n=parseInt(document.getElementById('f-schedule_interval').value)||2;
+    return '0 */'+Math.min(Math.max(n,1),12)+' * * *';
+  }
+  const t=(document.getElementById('f-schedule_time').value||'09:00').split(':');
+  const mi=parseInt(t[1])||0, h=parseInt(t[0])||0;
+  if(freq==='weekly'){
+    const w=parseInt(document.getElementById('f-schedule_weekday').value)||0;
+    return mi+' '+h+' * * '+w;
+  }
+  return mi+' '+h+' * * *'; // daily
+}
+// cron(5段) → 中文描述（任务列表显示）
+function cronToText(cron){
+  const r=parseCronToFreq(cron||'');
+  if(r.freq==='hourly')return '每小时';
+  if(r.freq==='everyN')return '每'+r.interval+'小时';
+  if(r.freq==='daily')return '每天 '+r.time;
+  if(r.freq==='weekly')return WEEKDAY_NAMES[r.weekday]+' '+r.time;
+  return 'cron: '+(cron||'-');
+}
+function toggleScheduleFields(){
+  const mode=document.getElementById('f-schedule_mode').value;
+  const showSched=(mode==='cron'||mode==='cron_stop');
+  document.getElementById('f-freq_wrap').style.display=showSched?'block':'none';
+  document.getElementById('f-stop_wrap').style.display=mode==='cron_stop'?'block':'none';
+  if(showSched)showFreqFields();
+}
+function toggleWindowFields(){
+  const on=document.getElementById('f-window_enable').checked;
+  document.getElementById('f-window_wrap').style.display=on?'flex':'none';
+  document.getElementById('f-window_help').style.display=on?'block':'none';
+}
+function showFreqFields(){
+  const freq=document.getElementById('f-schedule_freq').value;
+  document.getElementById('f-time_wrap').style.display=(freq==='daily'||freq==='weekly')?'block':'none';
+  document.getElementById('f-interval_wrap').style.display=freq==='everyN'?'block':'none';
+  document.getElementById('f-weekday_wrap').style.display=freq==='weekly'?'block':'none';
+  document.getElementById('f-cron_wrap').style.display=freq==='custom'?'block':'none';
+}
+
+function onTaskTypeChange(){
+  const tt=document.getElementById('f-task_type').value;
+  const isGeneric=tt==='generic_steps';
+  document.getElementById('step-editor').classList.toggle('show',isGeneric);
+  document.getElementById('f-params_wrap').style.display=isGeneric?'none':'block';
+}
+
+// ================== 自定义动作管理 ==================
+async function loadCustomActions(){
+  const r=await apiGet('/api/custom_actions'); if(!r||!r.ok)return;
+  _customActions=r.actions||[];
+  setListPager('actions',{
+    data:()=>_customActions,
+    filter:(a,kw)=>((a.name||'').toLowerCase().includes(kw)),
+    sortValue:(a,k)=>{ if(k==='steps')return (a.steps||[]).length; if(k==='created_at')return a.created_at||''; return a[k]||''; },
+    render:renderActionRow,
+    tbody:'tb-actions',pager:'pager-actions',pageSize:10,
+    empty:'<tr><td colspan="5" class="empty">暂无自定义动作，可点击"新建动作"或用任务编辑器☑选中步骤打包</td></tr>'
+  });
+  applyListPager('actions');
+  initListSearch('actions','search-actions');
+  _stepEditor._renderLib(); // 刷新步骤编辑器左侧动作库
+}
+function renderActionRow(a){
+  const n=(a.steps||[]).length;
+  return '<tr>'+
+    '<td style="font-size:20px">'+esc(a.icon||'📦')+'</td>'+
+    '<td><strong>'+esc(a.name)+'</strong></td>'+
+    '<td>'+n+'</td>'+
+    '<td style="font-size:12px;color:#94a3b8">'+esc(a.created_at||'-')+'</td>'+
+    '<td>'+
+      (_can('tasks')?(
+        '<button class="btn btn-xs" onclick="openActionModal(\''+a.id+'\')">编辑</button> '+
+        '<button class="btn btn-danger btn-xs" onclick="deleteAction(\''+a.id+'\')">删除</button>'
+      ):'<span class="text-muted">只读</span>')+
+    '</td>'+
+  '</tr>';
+}
+function openActionModal(actionId){
+  const action=actionId?_customActions.find(a=>a.id===actionId):null;
+  const isEdit=!!action;
+  document.getElementById('action-modal-title').textContent=isEdit?'编辑动作':'新建动作';
+  document.getElementById('action-modal-body').innerHTML=
+    '<div class="form-row">'+
+      '<div class="form-group"><label>动作名称</label><input type="text" class="form-control" id="a-name" value="'+esc(action?action.name:'')+'" placeholder="如：点赞动作"></div>'+
+      '<div class="form-group"><label>图标</label><input type="text" class="form-control" id="a-icon" value="'+esc(action?(action.icon&&action.icon!=='📦'?action.icon:''):'')+'" placeholder="📦" style="width:80px"></div>'+
+    '</div>'+
+    '<div class="help" style="margin-bottom:8px">用下方步骤编辑器编排动作内容，保存后可拖入任务步骤编辑器复用</div>'+
+    '<div class="step-editor" style="display:block">'+
+      '<div class="se-head"><span>动作步骤</span><span style="font-size:11px;color:var(--text-light);margin-left:12px">支持循环/分组/概率触发/拖拽排序</span>'+
+        (_can('tasks')?'<button class="btn btn-xs btn-primary" id="se-pack-btn2" disabled onclick="_stepEditor.saveAsCustomAction()">打包选中步骤</button>':'')+'</div>'+
+      '<div class="se-body">'+
+        '<div class="se-lib" id="action-lib"><div class="lib-title">操作库</div></div>'+
+        '<div class="se-canvas" id="action-canvas"></div>'+
+      '</div>'+
+    '</div>';
+  document.getElementById('action-modal-footer').innerHTML=
+    '<button class="btn" onclick="closeActionModal()">取消</button>'+
+    '<button class="btn btn-primary" onclick="saveAction('+(isEdit?'\''+actionId+'\'':'null')+')">保存动作</button>';
+  // 用独立画布初始化步骤编辑器（不与任务编辑器冲突）
+  _stepEditor.init(action&&action.steps?action.steps:[], 0, 'action:'+(actionId||'new'), 'action-canvas', 'action-lib');
+  document.getElementById('action-modal-overlay').classList.add('show');
+}
+async function saveAction(actionId){
+  const name=document.getElementById('a-name').value.trim();
+  if(!name){showToast('动作名不能为空','error');return;}
+  const icon=document.getElementById('a-icon').value.trim()||'📦';
+  const steps=_stepEditor.collect();
+  _stripIds(steps); // 入库前去掉 id，避免重复使用后 id 冲突
+  if(!steps.length){showToast('至少需要1个步骤','error');return;}
+  const data={name:name,icon:icon,steps:steps};
+  if(actionId){
+    const r=await apiPut('/api/custom_actions/'+actionId,data);
+    handleResult(r,()=>{_stepEditor.clearDraft();closeActionModal();loadCustomActions();});
+  }else{
+    const r=await apiPost('/api/custom_actions',data);
+    handleResult(r,()=>{_stepEditor.clearDraft();closeActionModal();loadCustomActions();});
+  }
+}
+async function deleteAction(id){
+  if(!confirm('确认删除此动作？'))return;
+  const r=await apiDelete('/api/custom_actions/'+id);
+  handleResult(r,()=>loadCustomActions());
+}
+function closeActionModal(){
+  document.getElementById('action-modal-overlay').classList.remove('show');
+}
+

static/admin/tools.js

@@ -0,0 +1,471 @@
+// 工具 Tab：剪贴板注入/应用版本/设备池管理 + adb终端 + Tailscale管理 + 远程看屏
+// ================== 工具：剪贴板注入 ==================
+let _clipDevices = [];          // [{serial, state}]，来源 /api/adb/devices（本地 adb + 设备池）
+let _clipSelected = new Set();
+
+// 本地 adb 设备列表共享缓存（剪贴板/终端两个面板同源，10 秒内复用避免重复请求；force 强制刷新）
+let _adbDevicesCache = null;    // {ts, data}
+
+async function _fetchAdbDevices(force){
+  const now = Date.now();
+  if(!force && _adbDevicesCache && now - _adbDevicesCache.ts < 10000){
+    return _adbDevicesCache.data;
+  }
+  const r = await apiGet('/api/adb/devices');
+  if(!r || !r.ok) return null;
+  _adbDevicesCache = {ts: now, data: r.devices || []};
+  return _adbDevicesCache.data;
+}
+
+async function loadToolsDevices(force){
+  const list = await _fetchAdbDevices(force);
+  const status = document.getElementById('clip-status');
+  if(list === null){status.textContent='加载失败';showToast('加载设备失败','error');return;}
+  // 剪贴板注入只对在线设备有意义：过滤掉设备池未连接(pool)/离线条目；
+  // adb 终端面板保留全部（重连设备需要），它用自己的渲染逻辑不受影响
+  _clipDevices = list.filter(d=>d.state==='device');
+  const wrap = document.getElementById('clip-devices');
+  if(!_clipDevices.length){
+    wrap.innerHTML='<div class="empty" style="padding:20px">无可用设备（本地 adb 或设备池均无）</div>';
+    status.textContent='';
+    return;
+  }
+  wrap.innerHTML = _clipDevices.map(d=>{
+    const st = d.state==='device' ? '已连接' : (d.state==='pool' ? '设备池' : d.state);
+    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 class="label '+stCls+'">'+st+'</span></label>';
+  }).join('');
+  status.textContent = '共 '+_clipDevices.length+' 台设备';
+}
+
+// ================== 设备自动发现（扫描 → 待连接池 → 确认） ==================
+function loadDiscovery(){
+  apiGet('/api/devices/discovery').then(r=>{
+    if(!r||!r.ok)return;
+    const status=document.getElementById('discovery-status');
+    const enabled=document.getElementById('discovery-enabled');
+    const interval=document.getElementById('discovery-interval');
+    const subnets=document.getElementById('discovery-subnets');
+    if(!enabled)return;   // 面板未渲染（离开子分栏）
+    enabled.checked=!!r.enabled;
+    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);
+      if(r.last_error)txt+=' · ⚠ '+esc(r.last_error);
+      status.textContent=txt;
+    }else{status.textContent='尚未扫描';}
+    // 待连接表格：只显示在线设备（离线候选不可确认连接，隐藏；恢复在线后自动出现）
+    const rows=(r.pending||[]).filter(x=>x.online);
+    const tb=document.getElementById('tb-discovery');
+    if(!tb)return;
+    if(!rows.length){
+      tb.innerHTML='<tr><td colspan="6" class="empty">待连接池为空（扫描到的设备会出现在这里）</td></tr>';
+    }else{
+      tb.innerHTML=rows.map(x=>{
+        const src=x.source==='tailscale'
+          ?'<span class="label label-info">Tailscale</span>'
+          :'<span class="label label-warning">局域网</span>';
+        const onl=x.online
+          ?'<span class="label label-success">在线</span>'
+          :'<span class="label label-warning">离线</span>';
+        return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</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> '
+          +'<button class="btn btn-xs" data-serial="'+esc(x.serial)+'" onclick="ignoreDiscoveryDev(this.dataset.serial)">忽略</button></td></tr>';
+      }).join('');
+    }
+  });
+}
+function toggleDiscovery(checked){
+  apiPost('/api/devices/discovery/settings',{enabled:checked}).then(r=>{
+    if(r&&r.ok)showToast('定时扫描已'+(checked?'开启':'关闭'),'success');
+    else showToast('设置失败: '+((r&&r.error)||''),'error');
+  });
+}
+function saveDiscoverySettings(){
+  const subnets=(document.getElementById('discovery-subnets').value||'')
+    .split(',').map(s=>s.trim()).filter(Boolean);
+  const interval=parseInt(document.getElementById('discovery-interval').value)||60;
+  apiPost('/api/devices/discovery/settings',{subnets,interval}).then(r=>{
+    if(r&&r.ok)showToast('设置已保存','success');
+    else showToast('保存失败: '+((r&&r.error)||''),'error');
+  });
+}
+function runDiscoveryScan(){
+  apiPost('/api/devices/discovery/scan',{}).then(r=>{
+    if(r&&r.ok){showToast(r.msg||'扫描已启动','success');setTimeout(loadDiscovery,3000);}
+    else showToast('扫描失败: '+((r&&r.error)||''),'error');
+  });
+}
+function confirmDiscoveryDev(serial){
+  const name=prompt('备注名（可选，留空直接添加）','');
+  if(name===null)return;
+  apiPost('/api/devices/discovery/confirm',{serial,name}).then(r=>{
+    if(r&&r.ok){
+      showToast('已加入设备池'+(r.is_new?'':'（已存在，已更新）'),'success');
+      loadDevPool();loadDiscovery();
+    }else showToast('确认失败: '+((r&&r.error)||''),'error');
+  });
+}
+function ignoreDiscoveryDev(serial){
+  if(!confirm('忽略 '+serial+'？下轮扫描可能再次发现'))return;
+  apiPost('/api/devices/discovery/ignore',{serial}).then(r=>{
+    if(r&&r.ok){showToast('已忽略','success');loadDiscovery();}
+    else showToast('操作失败: '+((r&&r.error)||''),'error');
+  });
+}
+
+function toggleClipDevice(cb){
+  if(cb.checked)_clipSelected.add(cb.value);
+  else _clipSelected.delete(cb.value);
+}
+
+// 注入剪贴板（ClipInject APK 通道，Android 10+ 可用）：
+// am start 透明 Activity 写入 + u2 读回比对验证；结果逐台渲染 + toast 汇总
+function injectClipboard(){
+  const text = document.getElementById('clip-text').value;
+  const serials = [..._clipSelected];
+  if(!serials.length){showToast('请先勾选目标设备','error');return;}
+  if(!text.trim()){showToast('请输入注入内容','error');return;}
+  const btn = Array.from(document.querySelectorAll('#tools-sub-clipboard .btn-primary'))
+    .find(b=>b.textContent.includes('注入剪贴板'));
+  if(btn){btn.disabled = true; const old = btn.textContent; btn.textContent = '注入中...'; btn._old = old;}
+  apiPost('/api/tools/clipboard/set', {serials, text}).then(r=>{
+    if(!r){showToast('请求失败','error');return;}
+    const rows = Object.entries(r.results||{}).map(([s,v])=>{
+      const ok = !!v.ok;
+      return '<tr><td style="font-family:monospace">'+esc(s)+'</td>'
+        +'<td><span class="label '+(ok?'label-success':'label-danger')+'">'
+        +(ok?'成功':'失败')+'</span> '+esc(v.msg||'')+'</td></tr>';
+    }).join('');
+    document.getElementById('clip-result').innerHTML = rows;
+    document.getElementById('clip-result-wrap').style.display='block';
+    const okc = r.ok_count||0, fail = r.fail_count||0;
+    if(fail>0) showToast(okc+' 台成功，'+fail+' 台失败','error');
+    else showToast(okc+' 台设备注入成功','success');
+  }).catch(e=>{showToast('注入异常: '+e,'error');})
+  .finally(()=>{ if(btn){btn.disabled=false; btn.textContent=btn._old;} });
+}
+
+// ================== 工具：应用版本管理 ==================
+let _appVerRows = [];            // [{serial, installed, version_name, version_code, error}]
+
+async function queryAppVers(){
+  const pkg = document.getElementById('appver-pkg').value.trim();
+  if(!pkg){showToast('请输入包名','error');return;}
+  const btn = document.querySelector('#tools-sub-appver .btn-primary');
+  btn.disabled = true; const old = btn.textContent; btn.textContent = '查询中...';
+  try{
+    const r = await apiPost('/api/tools/appver', {pkg});
+    if(!r || !r.ok){showToast('查询失败: '+(r&&r.error||''),'error');return;}
+    _appVerRows = Object.entries(r.results||{}).map(([serial,v])=>({serial, ...v}));
+    setListPager('appver',{
+      data:()=>_appVerRows,
+      filter:(x,kw)=>((x.serial||'').toLowerCase().includes(kw)||(x.version_name||'').toLowerCase().includes(kw)||(x.version_code||'').toLowerCase().includes(kw)),
+      sortValue:(x,k)=>{
+        if(k==='state'){ if(x.error)return 2; return x.installed?0:1; }
+        if(k==='code')return parseInt(x.version_code)||0;
+        if(k==='version')return x.version_name||'';
+        return x.serial||'';
+      },
+      render:renderAppVerRow,
+      tbody:'tb-appver',pager:'pager-appver',pageSize:10,
+      empty:'<tr><td colspan="4" class="empty">无可用设备</td></tr>'
+    });
+    applyListPager('appver');
+    initListSearch('appver','search-appver');
+    document.getElementById('appver-status').textContent = '共 '+(r.total||0)+' 台设备'+(r.fail?'，'+r.fail+' 台查询失败':'');
+    if(r.fail)showToast(r.fail+' 台设备查询失败，详见表格','error');
+  } finally {
+    btn.disabled = false; btn.textContent = old;
+  }
+}
+function renderAppVerRow(x){
+  if(x.error)return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+    '<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>'+
+    '<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>'+
+    '<td><span class="label label-default">未安装</span></td><td>-</td><td>-</td></tr>';
+}
+
+// ================== Tab: 维护（仅管理员） ==================
+// 服务器类命令（不需要 -s 目标设备）
+const _NO_DEVICE_CMDS=['devices','version','help','start-server','connect','kill-server','disconnect'];
+function _selectedSerial(){
+  const sel=document.getElementById('adb-device');
+  return sel?sel.value:'';
+}
+// 选中目标设备时自动附加 -s <serial>；服务器类命令保持原样
+function _attachDevice(cmd){
+  const serial=_selectedSerial();
+  if(!serial)return cmd;
+  if(/^-s\s/.test(cmd))return cmd;  // 已手写 -s 不再重复附加
+  const first=(cmd.split(/\s+/)[0]||'').toLowerCase();
+  if(_NO_DEVICE_CMDS.indexOf(first)>=0)return cmd;
+  return '-s '+serial+' '+cmd;
+}
+async function loadAdbDevices(force){
+  const sel=document.getElementById('adb-device');
+  if(!sel)return;
+  const list=await _fetchAdbDevices(force);
+  if(list===null)return;
+  const cur=sel.value;
+  const stateTxt={device:'在线',offline:'离线',pool:'设备池(未连接)'};
+  const opts=['<option value="">（不指定设备）</option>'].concat(
+    list.map(d=>
+      '<option value="'+esc(d.serial)+'">'+esc(d.serial)+' ('+(stateTxt[d.state]||d.state)+')</option>'
+    )
+  );
+  sel.innerHTML=opts.join('');
+  if(cur)sel.value=cur;
+}
+function fillAdbCmd(cmd){
+  document.getElementById('adb-cmd-input').value=cmd;
+}
+async function _runAdbFull(full){
+  const out=document.getElementById('adb-output');
+  out.textContent='$ '+full+'\n执行中...';
+  const r=await apiPost('/api/adb/cmd',{cmd:full});
+  if(!r)return;
+  if(!r.ok){out.textContent='$ '+full+'\n⚠ '+r.error;return;}
+  out.textContent='$ '+full+'\n\n'+(r.stdout||'')+(r.stderr?'\n[stderr] '+r.stderr:'')+'\n\n[exit '+r.code+']';
+  out.scrollTop=out.scrollHeight;
+}
+async function runAdbCmd(){
+  const input=document.getElementById('adb-cmd-input');
+  let cmd=(input.value||'').trim();
+  if(!cmd){showToast('请输入 adb 命令','error');return;}
+  cmd=cmd.replace(/^adb\s+/i,'');  // 兼容手输/快捷按钮带的 "adb " 前缀，避免拼成 "adb adb devices"
+  cmd=_attachDevice(cmd);
+  await _runAdbFull('adb '+cmd);
+}
+function reconnectAdbDevice(){
+  const serial=_selectedSerial();
+  if(!serial){showToast('请先选择目标设备','error');return;}
+  _runAdbFull('adb connect '+serial);
+}
+// ================== Tab: 维护 - Tailscale 管理 ==================
+// 与其他表格共用 setListPager/applyListPager 统一逻辑（搜索 + 分页）
+let _tsDevices=[];
+async function loadTailscaleDevices(){
+  const tb=document.getElementById('tb-tailscale');
+  const st=document.getElementById('ts-status');
+  const hint=document.getElementById('ts-hint');
+  if(!tb)return;
+  tb.innerHTML='<tr><td colspan="8" class="empty">加载中...</td></tr>';
+  const r=await apiGet('/api/tailscale/devices');
+  if(!r)return;
+  if(!r.ok){
+    tb.innerHTML='<tr><td colspan="8" class="empty">'+esc(r.error||'获取失败')+'</td></tr>';
+    if(st)st.textContent='';
+    const s=await apiGet('/api/tailscale/status');
+    if(s&&s.ok&&!s.configured&&hint)hint.textContent='⚠ 未配置：'+esc(s.hint||'')+'（写入 .env 后重启服务生效）';
+    return;
+  }
+  if(hint)hint.textContent='';
+  _tsDevices=r.devices||[];
+  setListPager('tailscale',{
+    data:()=>_tsDevices,
+    filter:(d,kw)=>((d.hostname||'').toLowerCase().includes(kw)||(d.name||'').toLowerCase().includes(kw)||(d.addresses||[]).join(',').includes(kw)),
+    sortValue:(d,k)=>{
+      if(k==='ip')return (d.addresses||[])[0]||'';
+      if(k==='online'){ if(d.online===true)return 0; if(d.online===false)return 2; return 1; } // null=最近12h在线
+      if(k==='authorized')return d.authorized?1:0;
+      if(k==='key_expiry')return d.key_expiry_disabled?1:0;
+      return d[k]||'';
+    },
+    render:renderTsRow,
+    tbody:'tb-tailscale',pager:'pager-tailscale',pageSize:10,
+    empty:'<tr><td colspan="8" class="empty">tailnet 暂无设备</td></tr>'
+  });
+  applyListPager('tailscale');
+  initListSearch('tailscale','search-tailscale');
+  if(st)st.textContent='共 '+_tsDevices.length+' 台设备';
+}
+function renderTsRow(d){
+  const ip=(d.addresses||[])[0]||'-';
+  return '<tr>'+
+    '<td><code>'+esc(d.hostname||'-')+'</code></td>'+
+    '<td>'+esc(d.name||'-')+'</td>'+
+    '<td style="font-family:monospace">'+esc(ip)+'</td>'+
+    '<td>'+esc(d.os||'-')+'</td>'+
+    '<td>'+((d.online===true)?'<span class="label label-success">在线</span>':(d.online===false?'<span class="label label-default">离线</span>':'<span class="label label-warning" title="12 小时内见过但当前未上报">最近在线</span>'))+'</td>'+
+    '<td>'+(d.authorized?'<span class="label label-success">已授权</span>':'<span class="label label-danger">未授权</span>')+'</td>'+
+    '<td>'+(d.key_expiry_disabled?'<span class="label label-warning">永不过期</span>':'<span class="label label-default">会过期</span>')+'</td>'+
+    '<td style="white-space:nowrap">'+
+      '<button class="btn btn-xs" onclick="renameTailscaleDevice(\''+esc(d.id)+'\',\''+esc(d.name||'')+'\')">改名</button> '+
+      '<button class="btn btn-xs" onclick="setTsIp(\''+esc(d.id)+'\',\''+esc((d.addresses||[])[0]||'')+'\')" title="修改设备的 Tailscale IPv4（会断开当前连接，平台 serial 随之变化）">设置IP</button> '+
+      '<button class="btn btn-xs" onclick="toggleTsAuth(\''+esc(d.id)+'\','+(!d.authorized)+')">'+(d.authorized?'取消授权':'授权')+'</button> '+
+      '<button class="btn btn-xs" onclick="toggleTsKeyExpiry(\''+esc(d.id)+'\','+(!d.key_expiry_disabled)+')">'+(d.key_expiry_disabled?'恢复过期':'密钥不过期')+'</button> '+
+      '<button class="btn btn-danger btn-xs" onclick="deleteTailscaleDevice(\''+esc(d.id)+'\')">移除</button>'+
+    '</td></tr>';
+}
+function renameTailscaleDevice(id, current){
+  const name=prompt('修改显示名（只改名称，不影响主机名）：', current||'');
+  if(name===null)return;
+  apiPost('/api/tailscale/devices/'+id,{name:name}).then(r=>{
+    if(!r)return;
+    if(r.ok){showToast(r.msg,'success');loadTailscaleDevices();}
+    else showToast(r.error,'error');
+  });
+}
+function setTsIp(id, current){
+  const ip=prompt('设置新的 Tailscale IPv4 地址（如 100.100.10.16）：\n\n⚠ 改 IP 会断开设备当前 tailscale 连接，且平台设备池（serial）随之变化，改完记得同步设备池/分组/任务目标。', (current||'').split(':')[0]||'');
+  if(ip===null)return;
+  const v=ip.trim();
+  if(!v){showToast('IP 不能为空','error');return;}
+  apiPost('/api/tailscale/devices/'+id+'/ip',{ipv4:v}).then(r=>{
+    if(!r)return;
+    if(r.ok){showToast(r.msg,'success');loadTailscaleDevices();}
+    else showToast(r.error,'error');
+  });
+}
+function toggleTsAuth(id, authorized){
+  apiPost('/api/tailscale/devices/'+id,{authorized:authorized}).then(r=>{
+    if(!r)return;
+    if(r.ok){showToast(authorized?'已授权':'已取消授权','success');loadTailscaleDevices();}
+    else showToast(r.error,'error');
+  });
+}
+function toggleTsKeyExpiry(id, disabled){
+  apiPost('/api/tailscale/devices/'+id,{key_expiry_disabled:disabled}).then(r=>{
+    if(!r)return;
+    if(r.ok){showToast(disabled?'已设置密钥永不过期（设备不再被踢下线）':'已恢复密钥定期过期','success');loadTailscaleDevices();}
+    else showToast(r.error,'error');
+  });
+}
+function deleteTailscaleDevice(id){
+  if(!confirm('确定从 tailnet 移除该设备？\n设备下次上线需重新授权。'))return;
+  apiDelete('/api/tailscale/devices/'+id).then(r=>{
+    if(!r)return;
+    if(r.ok){showToast(r.msg,'success');loadTailscaleDevices();}
+    else showToast(r.error,'error');
+  });
+}
+function openTailscaleAuthKey(){
+  const desc=prompt('auth key 用途说明（可空，仅支持英文/数字）：','auto_control');
+  if(desc===null)return;
+  const reusable=confirm('允许复用（同一 key 给多台设备用）？\n确定=可复用，取消=一次性');
+  const secs=prompt('有效期（秒，默认 3600=1 小时）：','3600');
+  if(secs===null)return;
+  const st=document.getElementById('ts-status');
+  if(st)st.textContent='正在生成 auth key...';
+  apiPost('/api/tailscale/authkey',{description:desc||'',reusable:reusable,expiry_seconds:parseInt(secs)||3600}).then(r=>{
+    if(!r)return;
+    if(st)st.textContent='';
+    if(r.ok){
+      const ov=document.getElementById('test-overlay');
+      document.getElementById('test-modal-title').textContent='Tailscale Auth Key（只显示一次）';
+      document.getElementById('test-modal-body').innerHTML=
+        '<div style="margin-bottom:10px">新设备执行 <code>tailscale up --authkey=...</code> 接入（默认已预授权）</div>'+
+        '<textarea id="ts-key-box" class="form-control" rows="4" style="font-family:monospace" readonly>'+esc(r.key||'')+'</textarea>'+
+        '<button class="btn btn-primary" style="margin-top:10px" onclick="copyTsKey()">复制</button>'+
+        ' <span id="ts-key-status" class="text-muted"></span>';
+      ov.classList.add('show');
+      showToast('Auth Key 已生成','success');
+    }else{
+      showToast(r.error,'error');
+    }
+  });
+}
+function copyTsKey(){
+  const box=document.getElementById('ts-key-box');
+  if(!box)return;
+  box.select();
+  try{document.execCommand('copy');}catch(e){}
+  const s=document.getElementById('ts-key-status');
+  if(s)s.textContent='已复制';
+}
+
+
+// ================== Tab: 工具 - 设备池管理（本地 SQLite 清单） ==================
+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>';
+  const r=await apiGet('/api/devices/pool');
+  if(!r||!r.ok){tb.innerHTML='<tr><td colspan="7" class="empty">加载失败</td></tr>';return;}
+  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);
+  const onlineCnt=rows.filter(x=>x.online).length;
+  status.textContent=onlyOnline
+    ? '在线 '+rows.length+' 台（共 '+(r.devices||[]).length+' 台配置）'
+    : '共 '+rows.length+' 台，在线 '+onlineCnt+' 台';
+  tb.innerHTML=rows.map(d=>{
+    const st= d.enabled
+      ? '<span class="label label-success">启用</span>'
+      : '<span class="label label-default">停用</span>';
+    const online= d.online
+      ? '<span class="label label-success">在线</span>'
+      : '<span class="label label-warning">离线</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>'+online+'</td>'+
+      '<td>'+st+'</td>'+
+      '<td style="color:var(--text-light)">'+esc(d.created_at||'')+'</td>'+
+      '<td style="white-space:nowrap">'+
+        '<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>';
+}
+
+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;}
+  const r=await apiPost('/api/devices/pool/add',{serial,name});
+  if(!r)return;
+  if(r.ok){
+    showToast(r.msg+(serial.includes(':')?'（已尝试连接）':''),'success');
+    document.getElementById('devpool-serial').value='';
+    document.getElementById('devpool-name').value='';
+    loadDevPool();
+  }else showToast(r.error,'error');
+}
+
+async function removePoolDev(serial){
+  if(!confirm('从设备池删除 '+serial+'？\n\n删除后不再参与任务调度（不影响设备本身与其他功能）。'))return;
+  const r=await apiPost('/api/devices/pool/remove',{serial});
+  if(!r)return;
+  if(r.ok){showToast(r.msg,'success');loadDevPool();}
+  else showToast(r.error,'error');
+}
+
+async function togglePoolDev(serial,enabled){
+  const r=await apiPost('/api/devices/pool/toggle',{serial,enabled});
+  if(!r)return;
+  if(r.ok){showToast(r.msg,'success');loadDevPool();}
+  else showToast(r.error,'error');
+}
+
+async function reconnectPoolDevices(){
+  if(!confirm('并发 adb connect 设备池内全部设备？\n\n已连接的自动跳过。'))return;
+  const r=await apiPost('/api/devices/pool/reconnect',{});
+  if(!r)return;
+  if(r.ok){showToast(r.msg,'success');setTimeout(loadDevPool,12000);}
+  else showToast(r.error,'error');
+}
+
+async function refreshPoolModels(){
+  const r=await apiPost('/api/devices/pool/refresh_models',{});
+  if(!r)return;
+  if(r.ok){showToast(r.msg,'success');setTimeout(loadDevPool,12000);}
+  else showToast(r.error,'error');
+}

tasks/__init__.py

@@ -8,5 +8,6 @@ from .base import BaseTask, register_task, list_task_types, get_task_class
 
 # 导入所有任务包，触发 @register_task 注册
 from .douyin import task  # noqa: F401
+from .generic import task  # noqa: F401
 
 __all__ = ["BaseTask", "register_task", "list_task_types", "get_task_class"]

tasks/base.py

@@ -49,8 +49,8 @@
                from .actions import get_action_class
                return get_action_class(action_type)
 
-           def create_worker(self, stf, serial, params):
+           def create_worker(self, serial, params):
-               return MyWorker(stf, serial, params=params)
+               return MyWorker(serial, params=params)
 
   5. 在 my_task/__init__.py 加：from . import task  （触发注册）
   6. 在 tasks/__init__.py 加：from .my_task import task  （触发注册）
@@ -85,7 +85,7 @@ class BaseTask:
     description = ""
     default_params = {}
 
-    def create_worker(self, stf, serial, params):
+    def create_worker(self, serial, params):
         """返回一个 threading.Thread（已启动或待启动），执行实际任务。"""
         raise NotImplementedError
 

tasks/douyin/actions/like.py

@@ -2,9 +2,9 @@
 
 两种方式：
   by_element   — 用 xpath 找右侧红心按钮点击（相对定位，不依赖视频卡片序号）
-  double_click — 双击屏幕中央（兜底，不依赖元素，抖音"双击点赞"手势）
+  double_click — 双击屏幕中央（需明确选择此方式，抖音"双击点赞"手势）
 
-定位器随抖音版本变，by_element 找不到会自动回退双击，不会卡住。
+by_element 找不到点赞按钮时**跳过本次，不点屏幕**（避免直播/无按钮页误触）。
 要适配新版本抖音：用 weditor 重新抓当前界面，调整下面定位逻辑。
 """
 from core.actions import BaseAction, register_action, should_trigger
@@ -33,7 +33,10 @@ class LikeAction(BaseAction):
             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("点赞(双击)")

tasks/douyin/task.py

@@ -52,8 +52,8 @@ class DouyinNurtureWorker(BaseWorker):
     操作参数优先级：任务 params.actions > 本文件 DEFAULT_PARAMS.actions。
     """
 
-    def __init__(self, stf_client, serial, params=None):
+    def __init__(self, serial, params=None):
-        super().__init__(stf_client, serial, params)
+        super().__init__(serial, params)
         p = {**DEFAULT_PARAMS, **(self.params or {})}
         self.watch_count = int(p["watch_count"])
         self.watch_min = float(p["watch_min"])
@@ -244,7 +244,7 @@ class DouyinNurtureTask(BaseTask):
         """按 action_type 取抖音操作类。"""
         return get_action_class(action_type)
 
-    def create_worker(self, stf, serial, params):
+    def create_worker(self, serial, params):
         merged = {**DEFAULT_PARAMS, **(params or {})}
         # actions 字段深合并（参数级，保留前端没传的操作默认值）
         # 确保即使前端只传 actions.like.enabled，like.params.rate 也能拿到默认 0.3
@@ -266,4 +266,4 @@ class DouyinNurtureTask(BaseTask):
                 merged_cfg["params"] = merged_params
                 merged_actions[atype] = merged_cfg
         merged["actions"] = merged_actions
-        return DouyinNurtureWorker(stf, serial, params=merged)
+        return DouyinNurtureWorker(serial, params=merged)

tasks/generic/__init__.py

@@ -0,0 +1,6 @@
+"""通用步骤任务包。
+
+通过前端步骤编辑器编排任务流程，worker 按 steps 顺序执行。
+与 douyin_nurture 共存，互不影响。
+"""
+from . import task  # noqa: F401  触发 @register_task 注册通用步骤任务

tasks/generic/task.py

@@ -0,0 +1,663 @@
+"""通用步骤任务定义。
+
+前端步骤编辑器编排步骤链，保存为 params.steps（JSON 数组）。
+worker 按 steps 顺序执行，支持 loop 步骤循环、停止信号、进度上报。
+
+步骤 schema:
+  {
+    "id": "step_1",            # 唯一 id（前端生成）
+    "type": "open_app",        # 步骤类型
+    "label": "打开抖音",        # 用户可读名称
+    "params": { ... }          # 步骤参数（按 type 不同）
+  }
+
+支持的步骤类型：
+  open_app    - 启动 app
+  stop_app    - 强制结束 app（am force-stop，下次打开冷启动）
+  screen_on   - 亮屏（息屏时唤醒并滑动解锁）
+  screen_off  - 息屏
+  keep_screen - 保持亮屏/恢复自动息屏（svc power stayon，设备充电时常亮）
+  key_event   - 按键（返回/Home/回车/菜单等，d.press）
+  swipe       - 滑动（方向/时长）
+  swipe_until - 滑动直到元素出现（最多 N 次，可选中找到后点击）
+  click       - 点击元素（选择器）
+  click_xy    - 点击坐标（屏幕百分比，无选择器时兜底）
+  long_click  - 长按元素（选择器 + 时长）
+  wait_el     - 等待元素出现（条件等待，替代固定时长 wait）
+  input_text  - 输入文字（随机候选/指定文字，可先清空）
+  wait        - 等待时长
+  loop        - 循环块（含 children 步骤列表 + max_iterations）
+  group       - 动作组（含 children 步骤列表，按序执行一次，可折叠复用）
+"""
+import random
+import time
+
+from tasks.base import BaseTask, register_task
+from core.device_worker import BaseWorker, _update_status
+from core.u2_helper import ensure_app_running, wait_for_app_home, random_sleep
+from core.logger import get_logger
+
+_log = get_logger("task.generic")
+
+
+# ================== 步骤类型定义（前端操作库 + 后端执行共用）==================
+STEP_TYPES = [
+    {"type": "open_app", "label": "打开App", "icon": "▶",
+     "params": {"package": "", "wait_home": False, "home_feature": ""}},
+    {"type": "stop_app", "label": "结束App", "icon": "⏹",
+     "params": {"package": ""}},
+    {"type": "screen_on", "label": "亮屏", "icon": "💡",
+     "params": {}},
+    {"type": "screen_off", "label": "息屏", "icon": "🌙",
+     "params": {}},
+    {"type": "keep_screen", "label": "保持亮屏", "icon": "🔆",
+     "params": {"mode": "on"}},
+    {"type": "key_event", "label": "按键", "icon": "⌨️",
+     "params": {"key": "back"}},
+    {"type": "swipe", "label": "滑动", "icon": "↕",
+     "params": {"direction": "up", "duration_min": 0.25, "duration_max": 0.50}},
+    {"type": "swipe_until", "label": "滑动直到元素", "icon": "🔍",
+     "params": {"selector_type": "xpath", "selector_value": "", "direction": "up",
+                "max_swipes": 8, "click_when_found": True}},
+    {"type": "click", "label": "点击元素", "icon": "✦",
+     "params": {"selector_type": "description", "selector_value": "", "wait_timeout": 2}},
+    {"type": "click_xy", "label": "点击坐标", "icon": "🎯",
+     "params": {"x": 50, "y": 50}},
+    {"type": "long_click", "label": "长按元素", "icon": "👆",
+     "params": {"selector_type": "xpath", "selector_value": "", "duration": 1.0, "wait_timeout": 2}},
+    {"type": "wait_el", "label": "等待元素", "icon": "⏳",
+     "params": {"selector_type": "xpath", "selector_value": "", "timeout": 10}},
+    {"type": "input_text", "label": "输入文字", "icon": "⌨",
+     "params": {"mode": "random", "texts": "你好\n有趣\n支持", "fixed_text": "", "clear_first": True}},
+    {"type": "clipboard", "label": "剪贴板注入", "icon": "📋",
+     "params": {"text": "", "paste": True}},
+    {"type": "wait", "label": "等待", "icon": "⏱",
+     "params": {"min": 1.0, "max": 3.0}},
+    {"type": "loop", "label": "循环块", "icon": "↻",
+     "params": {"loop_mode": "rounds", "max_iterations": 10, "loop_duration": 600, "children": []}},
+    {"type": "group", "label": "动作组", "icon": "📦",
+     "params": {"children": []}},
+    {"type": "if_el", "label": "条件判断", "icon": "❓",
+     "params": {"selector_type": "xpath", "selector_value": "", "timeout": 3,
+                "then": [], "else": []}},
+]
+
+
+DEFAULT_PARAMS = {
+    "max_duration": 0,          # 最大运行时长（秒），0=不限时
+    "steps": [                  # 默认示例：打开抖音→循环(看视频→滑动)
+        {
+            "id": "step_1", "type": "open_app", "label": "打开抖音",
+            "params": {"package": "com.ss.android.ugc.aweme", "wait_home": True, "home_feature": "拍摄"},
+        },
+        {
+            "id": "step_2", "type": "loop", "label": "循环看视频",
+            "params": {"max_iterations": 20, "children": [
+                {"id": "step_2_1", "type": "wait", "label": "观看视频",
+                 "params": {"min": 5.0, "max": 35.0}},
+                {"id": "step_2_2", "type": "swipe", "label": "上滑下一个",
+                 "params": {"direction": "up", "duration_min": 0.25, "duration_max": 0.50}},
+            ]},
+        },
+    ],
+}
+
+
+class GenericStepsWorker(BaseWorker):
+    """通用步骤 worker：按 params.steps 顺序执行步骤链。
+
+    复用 BaseWorker 的设备生命周期（STF 占用/释放、u2 连接、异常、状态上报、stop）。
+    只实现 run_task，按步骤类型分发到 _exec_<type> 方法。
+    """
+
+    def __init__(self, serial, params=None):
+        super().__init__(serial, params)
+        p = {**DEFAULT_PARAMS, **(self.params or {})}
+        self.max_duration = int(p.get("max_duration", 0))
+        self.steps = p.get("steps", [])
+        self._action_counts = {}   # 步骤执行计数 {step_label: count}
+        self._miss_counts = {}     # 选择器健康：selector -> 连续未命中次数
+
+    # 某 click 选择器连续未找到元素的次数达到该值，判定可能失效（App 改版）
+    _MAX_CONSECUTIVE_MISS = 10
+
+    def _track_selector_health(self, sel_val, found):
+        """记录某选择器的连续未命中次数，达到阈值上报 last_warning 并重置计数。
+
+        用于发现"选择器失效但任务仍显示成功"的静默空转问题（如 App 改版后元素找不到了）。
+        """
+        if found:
+            self._miss_counts.pop(sel_val, None)
+            return
+        n = self._miss_counts.get(sel_val, 0) + 1
+        self._miss_counts[sel_val] = n
+        if n >= self._MAX_CONSECUTIVE_MISS:
+            _log.error(f"[{self.serial}] 选择器连续 {n} 次未找到元素，可能已失效（App 改版？）：{sel_val}")
+            _update_status(self.serial, last_warning=f"选择器连续{n}次未命中")
+            self._miss_counts.pop(sel_val, None)  # 已上报，重置避免刷屏
+
+    def run_task(self, d):
+        """按 steps 顺序执行。loop 步骤递归执行其 children。"""
+        self._start_timer()
+        self.set_action("开始执行步骤链")
+        self.set_progress(done=0, total=0, unit="操作",
+                          action_counts=dict(self._action_counts))
+
+        try:
+            self._exec_steps(d, self.steps)
+        finally:
+            elapsed = self.elapsed()
+            summary = f"完成步骤链，运行 {elapsed//60}m{elapsed%60}s"
+            _update_status(self.serial, douyin_running=False, current_action=summary)
+
+    def _exec_steps(self, d, steps, depth=0):
+        """执行步骤列表。depth 防止无限嵌套。"""
+        if depth > 5:
+            _log.warning(f"[{self.serial}] 步骤嵌套深度超限(>5)，跳过")
+            return
+        for step in steps:
+            if self.stopped() or self.is_time_up():
+                return
+            self._exec_one(d, step, depth)
+
+    def _exec_one(self, d, step, depth=0):
+        """执行单个步骤。"""
+        stype = step.get("type", "")
+        label = step.get("label", stype)
+        params = step.get("params", {})
+        # 概率触发：probability=100 必执行，<100 按百分比概率决定本次是否执行
+        prob = float(params.get("probability", 100))
+        if prob < 100 and random.random() * 100 > prob:
+            _log.info(f"[{self.serial}] 步骤 '{label}' 概率 {prob}% 未触发，跳过")
+            return
+        self.set_action(f"执行: {label}")
+        _log.info(f"[{self.serial}] 步骤: {label}({stype}) params={params}")
+
+        ret = None
+        handler = getattr(self, f"_exec_{stype}", None)
+        if handler:
+            try:
+                ret = handler(d, params, depth)
+            except Exception as e:
+                _log.error(f"[{self.serial}] 步骤 {label}({stype}) 异常: {e}")
+        else:
+            _log.warning(f"[{self.serial}] 未知步骤类型: {stype}")
+        # 容器步骤（loop/group/if_el）不计入操作计数，避免监控显示噪音
+        if stype not in ("loop", "group", "if_el"):
+            self._action_counts[label] = self._action_counts.get(label, 0) + 1
+        elapsed = self.elapsed()
+        # done=累计执行的操作次数（无固定总数），前端显示"已执行 N 次操作"
+        self.set_progress(done=sum(self._action_counts.values()),
+                          total=0, unit="操作",
+                          action_counts=dict(self._action_counts), elapsed=elapsed)
+        return ret  # 命中结果（True/False/None），"测试此步骤"用
+
+    # ================== 步骤执行器 ==================
+    def _exec_screen_on(self, d, params, depth=0):
+        """亮屏：息屏时唤醒并滑动解锁。任务执行前用（息屏时 u2 无法操作）。"""
+        try:
+            d.unlock()
+            _log.info(f"[{self.serial}] 亮屏")
+        except Exception as e:
+            _log.warning(f"[{self.serial}] 亮屏异常: {e}")
+
+    def _exec_screen_off(self, d, params, depth=0):
+        """息屏：任务结束后用，避免长时间亮屏（烧屏/发热）。"""
+        try:
+            d.screen_off()
+            _log.info(f"[{self.serial}] 息屏")
+        except Exception as e:
+            _log.warning(f"[{self.serial}] 息屏异常: {e}")
+
+    def _exec_keep_screen(self, d, params, depth=0):
+        """保持亮屏 / 恢复自动息屏。
+
+        长任务（养号看视频数小时）时屏幕会按系统超时自动熄灭导致任务无法执行，
+        用 svc power stayon 让充电时屏幕常亮；任务结束前用 mode=off 恢复自动息屏。
+        """
+        mode = params.get("mode", "on")
+        try:
+            if mode == "off":
+                d.shell("svc power stayon false")
+                _log.info(f"[{self.serial}] 恢复自动息屏")
+            else:
+                d.shell("svc power stayon true")
+                _log.info(f"[{self.serial}] 保持亮屏（充电时屏幕常亮）")
+        except Exception as e:
+            _log.warning(f"[{self.serial}] keep_screen({mode}) 异常: {e}")
+
+    def _exec_stop_app(self, d, params, depth=0):
+        """强制结束 App（am force-stop）。清后台不留进程，下次打开为冷启动。"""
+        package = params.get("package", "")
+        if not package:
+            _log.warning(f"[{self.serial}] stop_app 缺少 package 参数")
+            return
+        try:
+            d.app_stop(package)
+            _log.info(f"[{self.serial}] 已强制结束 {package}")
+        except Exception as e:
+            _log.warning(f"[{self.serial}] 结束 {package} 异常: {e}")
+
+    def _exec_open_app(self, d, params, depth=0):
+        package = params.get("package", "")
+        if not package:
+            _log.warning("open_app 缺少 package 参数")
+            return
+        wait_home = params.get("wait_home", False)
+        home_feature = params.get("home_feature", "")
+        d.app_start(package, wait=True)
+        if wait_home:
+            home_check = (lambda d: d(descriptionContains=home_feature).exists) if home_feature else (lambda d: True)
+            if not wait_for_app_home(d, package, home_check, timeout=40):
+                self.set_action(f"{package} 首页加载超时，继续")
+
+    def _exec_key_event(self, d, params, depth=0):
+        """按键：返回/Home/回车等（d.press）。退出评论、返回上一页必备。"""
+        key = params.get("key", "back")
+        try:
+            d.press(key)
+            _log.info(f"[{self.serial}] 按键: {key}")
+        except Exception as e:
+            _log.warning(f"[{self.serial}] 按键 {key} 异常: {e}")
+
+    def _exec_swipe_until(self, d, params, depth=0):
+        """滑动直到元素出现（最多 max_swipes 次），可选找到后点击。
+
+        养号核心动作：信息流刷到目标按钮（点赞/评论）再操作。
+        返回 True=找到, False=未找到, None=配置缺选择器。
+        """
+        sel_type = params.get("selector_type", "xpath")
+        sel_val = params.get("selector_value", "")
+        direction = params.get("direction", "up")
+        max_swipes = max(1, int(params.get("max_swipes", 8)))
+        click_when_found = params.get("click_when_found", True)
+        if not sel_val:
+            _log.warning("swipe_until 缺少选择器")
+            return None
+        info = d.info
+        w, h = info["displayWidth"], info["displayHeight"]
+        cx = int(w * 0.5)
+        if direction == "down":
+            sy, ey = int(h * 0.2), int(h * 0.8)
+        else:
+            sy, ey = int(h * 0.8), int(h * 0.2)
+        for i in range(1, max_swipes + 1):
+            if self.stopped() or self.is_time_up():
+                return None
+            found = False
+            try:
+                if sel_type == "xpath":
+                    el = d.xpath(sel_val)
+                    found = el.wait(timeout=1)
+                else:
+                    el = d(**{sel_type: sel_val})
+                    found = el.exists(timeout=1)
+            except Exception:
+                found = False
+            if found:
+                self.set_action(f"滑动找到元素(第{i}次)")
+                if click_when_found:
+                    try:
+                        el.click()
+                        _log.info(f"[{self.serial}] 滑动{i}次后找到并点击: {sel_val}")
+                    except Exception as e:
+                        _log.warning(f"[{self.serial}] 找到但点击失败: {e}")
+                else:
+                    _log.info(f"[{self.serial}] 滑动{i}次后找到: {sel_val}")
+                self._track_selector_health(sel_val, True)
+                return True
+            d.swipe(cx, sy, cx, ey, 0.3)
+            time.sleep(0.5)
+        self._track_selector_health(sel_val, False)
+        _log.warning(f"[{self.serial}] 滑动{max_swipes}次未找到元素: {sel_val}")
+        return False
+
+    def _exec_click_xy(self, d, params, depth=0):
+        """点击坐标（屏幕百分比 0-100，50/50=屏幕中心）。无选择器时兜底。"""
+        x_pct = float(params.get("x", 50))
+        y_pct = float(params.get("y", 50))
+        info = d.info
+        w, h = info["displayWidth"], info["displayHeight"]
+        x = int(w * min(max(x_pct, 0), 100) / 100)
+        y = int(h * min(max(y_pct, 0), 100) / 100)
+        d.click(x, y)
+        _log.info(f"[{self.serial}] 点击坐标 ({x},{y})")
+
+    def _exec_long_click(self, d, params, depth=0):
+        """长按元素（选择器 + 时长秒）。复制链接/呼出菜单用。"""
+        sel_type = params.get("selector_type", "xpath")
+        sel_val = params.get("selector_value", "")
+        duration = float(params.get("duration", 1.0))
+        timeout = float(params.get("wait_timeout", 2))
+        if not sel_val:
+            _log.warning("long_click 缺少选择器")
+            return None
+        found = False
+        try:
+            if sel_type == "xpath":
+                el = d.xpath(sel_val)
+                if el.wait(timeout=timeout):
+                    el.long_click(duration=duration)
+                    found = True
+            else:
+                el = d(**{sel_type: sel_val})
+                if el.exists(timeout=timeout):
+                    el.long_click(duration=duration)
+                    found = True
+            self._track_selector_health(sel_val, found)
+            _log.info(f"[{self.serial}] 长按 {'命中' if found else '未找到'}: {sel_val}")
+        except Exception as e:
+            _log.warning(f"[{self.serial}] 长按异常: {e}")
+        return found
+
+    def _exec_wait_el(self, d, params, depth=0):
+        """等待元素出现（条件等待）。返回 True=出现, False=超时, None=缺选择器。"""
+        sel_type = params.get("selector_type", "xpath")
+        sel_val = params.get("selector_value", "")
+        timeout = float(params.get("timeout", 10))
+        if not sel_val:
+            _log.warning("wait_el 缺少选择器")
+            return None
+        try:
+            if sel_type == "xpath":
+                found = d.xpath(sel_val).wait(timeout=timeout)
+            else:
+                found = d(**{sel_type: sel_val}).exists(timeout=timeout)
+            self._track_selector_health(sel_val, found)
+            _log.info(f"[{self.serial}] 等待元素 {'出现' if found else '超时未出现'}: {sel_val}")
+            return found
+        except Exception as e:
+            _log.warning(f"[{self.serial}] 等待元素异常: {e}")
+            return False
+
+    def _exec_if_el(self, d, params, depth=0):
+        """条件判断：找到元素 → 执行 then 分支；超时未找到 → 执行 else 分支。
+
+        selector_type=ocr 时用屏幕 OCR 匹配文字（图片/画布/WebView 里的文字也能找到），
+        命中且 ocr_click=True 时自动点击该文字中心。
+        分支里可放任意步骤（含循环/嵌套条件判断），实现"有弹窗就关掉、没弹窗就继续"这类逻辑。
+        返回 True=命中 / False=未命中 / None=缺选择器或 OCR 不可用。
+        """
+        sel_type = params.get("selector_type", "xpath")
+        sel_val = params.get("selector_value", "")
+        timeout = float(params.get("timeout", 3))
+        if not sel_val:
+            _log.warning(f"[{self.serial}] if_el 缺少选择器，跳过")
+            return None
+        found = False
+        if sel_type == "ocr":
+            # OCR 模式：截图 → 识别文字 → 关键词匹配（UI 树里没有的文字也能找到）
+            try:
+                from core.ocr import available as _ocr_available, find_on_screen
+                ok, hint = _ocr_available()
+                if not ok:
+                    _log.error(f"[{self.serial}] OCR 条件判断不可用: {hint}")
+                    return None
+                img = d.screenshot()
+                if img is None:
+                    _log.warning(f"[{self.serial}] OCR 截图失败")
+                else:
+                    found, center, matched = find_on_screen(img, sel_val)
+                    if found:
+                        if params.get("ocr_click") and center:
+                            d.click(*center)
+                            _log.info(f"[{self.serial}] OCR 命中 '{matched}'，已点击 ({center[0]},{center[1]})")
+                        else:
+                            _log.info(f"[{self.serial}] OCR 命中 '{matched}'")
+                    else:
+                        _log.info(f"[{self.serial}] OCR 未命中: '{sel_val}'")
+            except Exception as e:
+                _log.warning(f"[{self.serial}] OCR 条件判断异常: {e}")
+                found = False
+        else:
+            try:
+                if sel_type == "xpath":
+                    found = d.xpath(sel_val).wait(timeout=timeout)
+                else:
+                    found = d(**{sel_type: sel_val}).exists(timeout=timeout)
+            except Exception as e:
+                _log.warning(f"[{self.serial}] 条件判断异常: {e}")
+                found = False
+        self._track_selector_health(sel_val, found)
+        branch = params.get("then" if found else "else") or []
+        self.set_action(f"条件{'命中' if found else '未命中'} → 执行{'找到' if found else '未找到'}分支({len(branch)}步)")
+        _log.info(f"[{self.serial}] 条件判断 {'命中' if found else '未命中'}: {sel_val}，执行{'then' if found else 'else'}分支 {len(branch)} 步")
+        self._exec_steps(d, branch, depth + 1)
+        return found
+
+    def _exec_swipe(self, d, params, depth=0):
+        direction = params.get("direction", "up")
+        dur_min = float(params.get("duration_min", 0.25))
+        dur_max = float(params.get("duration_max", 0.50))
+        dur = random.uniform(dur_min, dur_max)
+        info = d.info
+        w, h = info["displayWidth"], info["displayHeight"]
+        cx = int(w * 0.5)
+        if direction == "up":
+            d.swipe(cx, int(h * 0.8), cx, int(h * 0.2), dur)
+        elif direction == "down":
+            d.swipe(cx, int(h * 0.2), cx, int(h * 0.8), dur)
+        elif direction == "left":
+            d.swipe(int(w * 0.8), int(h * 0.5), int(w * 0.2), int(h * 0.5), dur)
+        elif direction == "right":
+            d.swipe(int(w * 0.2), int(h * 0.5), int(w * 0.8), int(h * 0.5), dur)
+
+    def _exec_click(self, d, params, depth=0):
+        sel_type = params.get("selector_type", "xpath")
+        sel_val = params.get("selector_value", "")
+        timeout = float(params.get("wait_timeout", 2))
+        if not sel_val:
+            _log.warning(f"[{self.serial}] click 跳过：selector_value 为空，请在步骤编辑器中填写或抓取元素")
+            return
+        # 兼容旧配置：selector_type 不是 xpath 但值是 XPath（以 // 开头）
+        if sel_type != "xpath" and sel_val.strip().startswith("//"):
+            sel_type = "xpath"
+        found = False
+        try:
+            if sel_type == "xpath":
+                # u2 的 d.xpath() 返回 XPathSelector，exists 是属性需用 wait()
+                el = d.xpath(sel_val)
+                if el.wait(timeout=timeout):
+                    el.click()
+                    _log.info(f"[{self.serial}] click 命中: xpath={sel_val}")
+                    found = True
+                else:
+                    _log.warning(f"[{self.serial}] click 未找到元素: xpath={sel_val} (等待{timeout}s)")
+            else:
+                # UiSelector 风格：d(description=xxx) 等，exists() 支持 timeout 参数
+                el = d(**{sel_type: sel_val})
+                if el.exists(timeout=timeout):
+                    el.click()
+                    _log.info(f"[{self.serial}] click 命中: {sel_type}={sel_val}")
+                    found = True
+                else:
+                    _log.warning(f"[{self.serial}] click 未找到元素: {sel_type}={sel_val} (等待{timeout}s)")
+            self._track_selector_health(sel_val, found)
+        except Exception as e:
+            _log.warning(f"[{self.serial}] click 异常: {e}")
+        return found  # 命中结果，"测试此步骤"用
+
+    def _exec_clipboard(self, d, params, depth=0):
+        """剪贴板注入（ClipInject 通道，Android 10+ 可用），可选立即粘贴。
+
+        批量发链接场景：先聚焦评论区输入框 → 注入+粘贴链接1 → 换链接 → 注入+粘贴链接2……
+        粘贴模式：ClipInject 写入剪贴板后调 atx-agent pasteClipboard 粘贴到当前
+        焦点输入框；动作失败时兜底 u2 set_text 直接设置聚焦输入框文本（不依赖
+        剪贴板，与"输入文字"兜底同机制）。
+        """
+        text = str(params.get("text", "") or "")
+        if not text:
+            _log.warning(f"[{self.serial}] clipboard 内容为空，跳过")
+            return False
+        from core.clipboard_helper import inject_clipboard
+        ok, msg = inject_clipboard(self.serial, text, d=d)
+        if not ok:
+            _log.warning(f"[{self.serial}] 剪贴板注入失败: {msg}")
+            return False
+        _log.info(f"[{self.serial}] 剪贴板注入: {text[:60]}（{msg}）")
+        if not params.get("paste"):
+            return True
+        try:
+            d.jsonrpc.pasteClipboard()
+            _log.info(f"[{self.serial}] 已粘贴: {text[:60]}")
+            return True
+        except Exception as e:
+            try:
+                d(focused=True).set_text(text)
+                _log.info(f"[{self.serial}] 粘贴兜底 set_text: {text[:60]}")
+                return True
+            except Exception as e2:
+                _log.warning(f"[{self.serial}] 粘贴失败: {e} / {e2}")
+                return True  # 剪贴板已写入，粘贴失败不致命
+
+    def _exec_wait(self, d, params, depth=0):
+        min_s = float(params.get("min", 1.0))
+        max_s = float(params.get("max", 3.0))
+        # 分片 sleep：每 0.5s 检查停止/超时信号，抢占任务能及时接管（纯 sleep 无法中断）
+        total = random.uniform(min_s, max_s)
+        end = time.time() + total
+        while time.time() < end:
+            if self.stopped() or self.is_time_up():
+                return
+            time.sleep(min(0.5, end - time.time()))
+
+    def _exec_loop(self, d, params, depth=0):
+        children = params.get("children", [])
+        if not children:
+            return
+        mode = params.get("loop_mode", "rounds")
+        if mode == "forever":
+            # 一直循环：无限跑直到任务被外部停止（定时停止 cron / 运行时长上限 / 手动停止）。
+            # 配合"定时启动+停止"调度（如 9:00 启动 / 18:00 停止）实现全天候运行。
+            i = 0
+            while not self.stopped() and not self.is_time_up():
+                i += 1
+                self.set_action(f"循环第 {i} 轮(持续)")
+                if i % 10 == 0 or i <= 2:
+                    _log.info(f"[{self.serial}] loop 第 {i} 轮(持续运行)")
+                self._exec_steps(d, children, depth + 1)
+        elif mode == "time":
+            # 按时间循环：跑满 loop_duration 秒，同时受全局 stopped/max_duration 约束
+            duration = float(params.get("loop_duration", 0) or 0)
+            if duration <= 0:
+                _log.warning(f"[{self.serial}] 按时间循环未设置时长，跳过")
+                return
+            start = time.time()
+            i = 0
+            while not self.stopped() and not self.is_time_up() and (time.time() - start) < duration:
+                i += 1
+                self.set_action(f"循环第 {i} 轮(按时间)")
+                _log.info(f"[{self.serial}] loop 第 {i} 轮(按时间, 已{(time.time()-start):.0f}s/{duration:.0f}s)")
+                self._exec_steps(d, children, depth + 1)
+        else:
+            # 按轮次循环
+            max_iter = int(params.get("max_iterations", 10))
+            for i in range(max_iter):
+                if self.stopped() or self.is_time_up():
+                    return
+                self.set_action(f"循环第 {i+1}/{max_iter} 轮")
+                _log.info(f"[{self.serial}] loop 第 {i+1}/{max_iter} 轮")
+                self._exec_steps(d, children, depth + 1)
+
+    def _exec_group(self, d, params, depth=0):
+        """动作组：按序执行 children 一次（类似 loop 但不循环）。
+
+        用于把一系列步骤打包成一个可复用的动作。
+        """
+        children = params.get("children", [])
+        if not children:
+            return
+        self._exec_steps(d, children, depth + 1)
+
+    def _exec_input_text(self, d, params, depth=0):
+        """在当前焦点输入框输入文字。
+
+        需先用"点击元素"步骤定位到输入框，本步骤只负责输入。
+        mode=random: 从 texts（换行分隔）随机选一条
+        mode=fixed:  输入 fixed_text
+        """
+        mode = params.get("mode", "random")
+        if mode == "fixed":
+            text = params.get("fixed_text", "")
+        else:
+            raw = params.get("texts", "")
+            candidates = [t.strip() for t in raw.splitlines() if t.strip()]
+            if not candidates:
+                _log.warning("input_text 无候选文字")
+                return
+            text = random.choice(candidates)
+        if not text:
+            return
+        clear_first = params.get("clear_first", True)
+        try:
+            # 优先用 u2 的 send_keys（对当前焦点元素输入）；clear=True 先清空再输入
+            d.send_keys(text, clear=clear_first)
+            _log.info(f"[{self.serial}] input_text: {text}" + ("（已先清空）" if clear_first else ""))
+        except Exception as e:
+            # 兜底：找 EditText 设置文本
+            try:
+                edit = d(className="android.widget.EditText")
+                if edit.exists:
+                    if clear_first:
+                        edit.clear_text()
+                    edit.set_text(text)
+                    _log.info(f"[{self.serial}] input_text(set_text): {text}")
+                else:
+                    _log.warning(f"[{self.serial}] input_text 未找到输入框: {e}")
+            except Exception as e2:
+                _log.warning(f"[{self.serial}] input_text 失败: {e2}")
+
+
+@register_task
+class GenericStepsTask(BaseTask):
+    """通用步骤任务：前端编辑器编排步骤链，worker 按顺序执行。"""
+    task_type = "generic_steps"
+    name = "通用步骤"
+    description = "通过步骤编辑器编排任务流程，支持循环/点击/滑动/点赞/评论等"
+    default_params = dict(DEFAULT_PARAMS)
+
+    @classmethod
+    def list_action_types(cls):
+        """返回支持的步骤类型列表（前端操作库用）。"""
+        return STEP_TYPES
+
+    @classmethod
+    def get_action_class(cls, action_type):
+        return None
+
+    def create_worker(self, serial, params):
+        merged = {**DEFAULT_PARAMS, **(params or {})}
+        return GenericStepsWorker(serial, params=merged)
+
+
+def test_step(serial, step):
+    """在设备上单步试执行（编辑器"测试此步骤"按钮用）。
+
+    直接 adb connect + u2 连接后执行单个步骤，验证选择器是否命中。
+    返回 (ok, msg, result)：result 为执行器返回的命中结果（True/False/None）。
+    与运行中的任务互不干扰（只读连接，不占用/不释放 STF）。
+    """
+    import uiautomator2 as u2
+    from concurrent.futures import ThreadPoolExecutor  # 与 device_worker 一致（本机 stdlib threading 无此属性）
+    from core.adb_helper import adb_connect
+    from core.device_worker import _U2_CONNECT_TIMEOUT
+
+    try:
+        if not adb_connect(serial):
+            return False, f"adb connect {serial} 失败", None
+    except Exception as e:
+        return False, f"adb connect 异常: {e}", None
+    try:
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            fut = pool.submit(u2.connect, serial)
+            d = fut.result(timeout=_U2_CONNECT_TIMEOUT)
+    except Exception as e:
+        return False, f"u2 连接失败: {e}", None
+    if d is None:
+        return False, "u2 连接超时", None
+    try:
+        w = GenericStepsWorker(serial, {})
+        result = w._exec_one(d, step)
+        return True, f"步骤已执行（{step.get('label') or step.get('type')}）", result
+    except Exception as e:
+        return False, f"执行异常: {e}", None

templates/admin/wall.html

@@ -0,0 +1,481 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>设备监控大屏</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')}
+@font-face{font-family:'Bricolage Grotesque';font-style:normal;font-weight:800;font-display:swap;src:url('/static/fonts/bricolage-800.woff2') format('woff2')}
+@font-face{font-family:'IBM Plex Mono';font-style:normal;font-weight:400;font-display:swap;src:url('/static/fonts/plexmono-400.woff2') format('woff2')}
+@font-face{font-family:'IBM Plex Mono';font-style:normal;font-weight:600;font-display:swap;src:url('/static/fonts/plexmono-600.woff2') format('woff2')}
+:root{
+  --bg:#0d0f13; --card:#14181f; --card-line:#232936; --ink-line:#2a303c;
+  --text:#e8ecf2; --muted:#8b93a3; --faint:#5c6472;
+  --teal:#2dd4bf; --green:#34d399; --red:#f87171; --amber:#fbbf24; --indigo:#818cf8;
+  --display:'Bricolage Grotesque','PingFang SC','Microsoft YaHei',sans-serif;
+  --mono:'IBM Plex Mono',Menlo,Consolas,monospace;
+  --body:-apple-system,'PingFang SC','Microsoft YaHei',sans-serif;
+}
+*{box-sizing:border-box;margin:0;padding:0}
+html,body{height:100%}
+body{background:var(--bg);font-family:var(--body);color:var(--text);overflow:hidden}
+body::before{content:"";position:fixed;inset:0;pointer-events:none;
+  background-image:linear-gradient(rgba(45,212,191,.035) 1px,transparent 1px),
+                   linear-gradient(90deg,rgba(45,212,191,.035) 1px,transparent 1px);
+  background-size:42px 42px}
+/* 顶部栏 */
+header{display:flex;align-items:center;gap:24px;padding:14px 26px 12px;border-bottom:1px solid var(--ink-line);background:rgba(13,15,19,.85);backdrop-filter:blur(6px);position:relative;z-index:5}
+header .title{font-family:var(--display);font-size:21px;font-weight:800;letter-spacing:1px;color:#fff;display:flex;align-items:center;gap:12px;white-space:nowrap}
+header .title::before{content:"";width:10px;height:10px;border-radius:50%;background:var(--teal);box-shadow:0 0 0 0 rgba(45,212,191,.55);animation:pulse 2.2s infinite}
+@keyframes pulse{0%{box-shadow:0 0 0 0 rgba(45,212,191,.5)}70%{box-shadow:0 0 0 9px rgba(45,212,191,0)}100%{box-shadow:0 0 0 0 rgba(45,212,191,0)}}
+header .stats{display:flex;gap:10px;flex:1}
+header .stat{background:var(--card);border:1px solid var(--card-line);border-radius:10px;padding:6px 16px;text-align:center;min-width:84px}
+header .stat .n{font-family:var(--mono);font-size:20px;font-weight:600;line-height:1.15}
+header .stat .l{font-size:11px;color:var(--faint);margin-top:2px;letter-spacing:.4px}
+header .stat.online .n{color:var(--green)}
+header .stat.running .n{color:var(--teal)}
+header .stat.error .n{color:var(--red)}
+header .wall-btn{background:var(--card);border:1px solid var(--card-line);color:var(--teal);border-radius:10px;padding:8px 18px;font-size:13px;font-weight:600;cursor:pointer;transition:all .15s;font-family:var(--body)}
+header .wall-btn:hover{background:#1a2029;border-color:var(--teal);transform:translateY(-1px)}
+header .wall-btn:disabled{opacity:.5;cursor:not-allowed}
+header .clock{font-family:var(--mono);font-size:18px;color:var(--muted);text-align:right;line-height:1.2;white-space:nowrap}
+header .clock .date{font-size:11px;color:var(--faint)}
+/* 设备网格 */
+main{position:relative;z-index:2;height:calc(100vh - 88px);overflow-y:auto;padding:16px 24px 30px;display:grid;grid-template-columns:repeat(auto-fill,minmax(200px,1fr));gap:14px;align-content:start}
+/* 设备卡片（可点击进操作） */
+.card{background:var(--card);border:1px solid var(--card-line);border-radius:14px;overflow:hidden;position:relative;animation:cardIn .4s ease-out backwards;cursor:pointer;transition:border-color .2s,box-shadow .2s,transform .15s}
+.card:hover{transform:translateY(-3px);box-shadow:0 8px 22px rgba(0,0,0,.4)}
+@keyframes cardIn{from{opacity:0;transform:translateY(10px)}to{opacity:1;transform:none}}
+.card.running{border-color:rgba(45,212,191,.55);box-shadow:0 0 18px rgba(45,212,191,.12),inset 0 0 0 1px rgba(45,212,191,.2)}
+.card.error{border-color:rgba(248,113,113,.5)}
+.card.offline{opacity:.62}
+.card .thumb{aspect-ratio:9/16;background:#0a0c10;position:relative;overflow:hidden}
+.card .thumb img{width:100%;height:100%;object-fit:cover;display:block;transition:opacity .2s}
+.card.offline .thumb img{display:none}
+.card .thumb .ph{position:absolute;inset:0;display:none;flex-direction:column;align-items:center;justify-content:center;gap:8px;color:var(--faint);font-size:12px;background:repeating-linear-gradient(45deg,#0c0e12,#0c0e12 12px,#0f1218 12px,#0f1218 24px)}
+.card .thumb .ph .ico{font-size:26px;opacity:.6}
+/* 状态角标 */
+.card .badge{position:absolute;top:8px;left:8px;display:flex;align-items:center;gap:6px;background:rgba(13,15,19,.8);backdrop-filter:blur(4px);border-radius:99px;padding:3px 10px;font-size:11px;font-weight:600;color:var(--muted);border:1px solid var(--ink-line)}
+.card.running .badge{color:var(--teal);border-color:rgba(45,212,191,.4)}
+.card.error .badge{color:var(--red)}
+.card .badge .dot{width:7px;height:7px;border-radius:50%;background:var(--faint)}
+.card.running .badge .dot{background:var(--teal);box-shadow:0 0 7px rgba(45,212,191,.8);animation:pulse 1.6s infinite}
+.card.error .badge .dot{background:var(--red);box-shadow:0 0 6px rgba(248,113,113,.7)}
+.card.offline .badge .dot{background:var(--faint)}
+/* 熄屏角标（右上） */
+.card .screen-tag{position:absolute;top:8px;right:8px;background:rgba(13,15,19,.8);backdrop-filter:blur(4px);border-radius:99px;padding:3px 10px;font-size:11px;font-weight:600;border:1px solid var(--ink-line)}
+.card .screen-tag.on{color:var(--green)}
+.card .screen-tag.off{color:var(--faint)}
+/* 信息区 */
+.card .info{padding:9px 12px 11px}
+.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 .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}
+.card .info .prog i{display:block;height:100%;background:linear-gradient(90deg,var(--teal),#5eead4);border-radius:99px;transition:width .5s}
+.card .info .prog-txt{font-size:10px;color:var(--faint);margin-top:3px;font-family:var(--mono)}
+.card .info .hint{font-size:10px;color:var(--faint);margin-top:5px;text-align:center;opacity:0;transition:opacity .2s}
+.card:hover .info .hint{opacity:.8}
+/* 空状态 */
+.empty-wall{grid-column:1/-1;text-align:center;color:var(--faint);padding:80px 0;font-size:14px}
+/* 设备操作弹窗 */
+.ctrl-overlay{display:none;position:fixed;inset:0;background:rgba(5,7,10,.78);backdrop-filter:blur(3px);z-index:100;justify-content:center;align-items:center;padding:26px}
+.ctrl-overlay.show{display:flex}
+.ctrl-box{background:var(--card);border:1px solid var(--card-line);border-radius:16px;width:min(420px,94vw);max-height:94vh;display:flex;flex-direction:column;overflow:hidden;box-shadow:0 24px 70px rgba(0,0,0,.6);animation:modalIn .18s ease-out}
+@keyframes modalIn{from{opacity:0;transform:translateY(12px) scale(.98)}to{opacity:1;transform:none}}
+.ctrl-head{padding:12px 16px;border-bottom:1px solid var(--ink-line);display:flex;align-items:center;gap:12px;background:#11151c}
+.ctrl-head .info{flex:1;min-width:0}
+.ctrl-head .name{font-size:15px;font-weight:700;color:#f1f4f8;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.ctrl-head .sub{font-family:var(--mono);font-size:11.5px;color:var(--faint);margin-top:1px}
+.ctrl-head .close{background:none;border:none;color:var(--faint);font-size:22px;cursor:pointer;padding:0 6px;line-height:1;border-radius:6px}
+.ctrl-head .close:hover{color:#fff;background:#1d242e}
+.ctrl-body{flex:1;overflow-y:auto;padding:12px;background:#0a0c10}
+.ctrl-body .screen{position:relative;border-radius:10px;overflow:hidden;background:#000;cursor:crosshair;user-select:none;touch-action:none}
+.ctrl-body .screen img{width:100%;display:block;max-height:62vh;object-fit:contain;background:#000}
+.ctrl-body .screen .loading{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;background:rgba(0,0,0,.55);color:var(--muted);font-size:12px;border-radius:10px}
+.ctrl-tools{display:flex;gap:6px;flex-wrap:wrap;padding:10px 12px 12px;border-top:1px solid var(--ink-line);background:#11151c}
+.ctrl-tools .btn{background:#1a2029;border:1px solid var(--card-line);color:var(--muted);border-radius:8px;padding:6px 12px;font-size:12px;cursor:pointer;transition:all .12s;font-family:var(--body)}
+.ctrl-tools .btn:hover{color:var(--teal);border-color:var(--teal)}
+.ctrl-tools .btn.wake{color:var(--green);border-color:rgba(52,211,153,.4)}
+.ctrl-tools .btn.wake:hover{border-color:var(--green)}
+.ctrl-tools .btn.sleep{color:var(--faint)}
+.ctrl-tools .text-row{display:flex;gap:6px;flex:1 0 100%;margin-top:2px}
+.ctrl-tools .text-row input{flex:1;background:#0d1117;border:1px solid var(--card-line);border-radius:8px;padding:6px 10px;font-size:12px;color:var(--text);outline:none;font-family:var(--body)}
+.ctrl-tools .text-row input:focus{border-color:var(--teal)}
+/* 滚动条 */
+::-webkit-scrollbar{width:8px}
+::-webkit-scrollbar-thumb{background:#232936;border-radius:4px}
+::-webkit-scrollbar-track{background:transparent}
+</style>
+</head>
+<body>
+<header>
+  <div class="title">设备监控大屏</div>
+  <div class="stats" id="wall-stats"></div>
+  <label class="wall-btn" style="display:inline-flex;align-items:center;gap:4px;cursor:pointer">
+    <input type="checkbox" id="wall-filter-online" checked onchange="refreshStatus()"> 只看在线
+  </label>
+  <button class="wall-btn" id="btn-wake-all" onclick="wakeAll()">💡 一键亮屏</button>
+  <div class="clock"><span id="wall-clock">--:--:--</span><div class="date" id="wall-date"></div></div>
+</header>
+<main id="wall-grid"></main>
+
+<!-- 设备操作弹窗（看屏 + 触控） -->
+<div class="ctrl-overlay" id="ctrl-overlay">
+  <div class="ctrl-box">
+    <div class="ctrl-head">
+      <div class="info">
+        <div class="name" id="ctrl-name">设备</div>
+        <div class="sub" id="ctrl-sub">--</div>
+      </div>
+      <button class="close" onclick="closeCtrl()">×</button>
+    </div>
+    <div class="ctrl-body">
+      <div class="screen" id="ctrl-screen">
+        <img id="ctrl-img" alt="">
+        <div class="loading" id="ctrl-loading">连接中（首次需推送 atx-agent，最长约 30 秒）...</div>
+      </div>
+    </div>
+    <div class="ctrl-tools">
+      <button class="btn wake" onclick="ctrlWake()">💡 亮屏</button>
+      <button class="btn sleep" onclick="ctrlSleep()">🌙 息屏</button>
+      <button class="btn" onclick="ctrlKey('back')">◀ 返回</button>
+      <button class="btn" onclick="ctrlKey('home')">🏠 主页</button>
+      <button class="btn" onclick="ctrlKey('recent')">📋 最近</button>
+      <button class="btn" onclick="ctrlKey('menu')">☰ 菜单</button>
+      <button class="btn" onclick="ctrlKey('power')">⏻ 电源</button>
+      <div class="text-row">
+        <input type="text" id="ctrl-text" placeholder="输入文字（需光标在输入框）" onkeydown="if(event.key==='Enter')ctrlSendText()">
+        <button class="btn" onclick="ctrlSendText()">发送</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<script>
+// ================== 监控大屏（深色控制室） ==================
+// 状态每 5s 刷新；缩略图每 2.5s 轮询（页面不可见时暂停）
+// 缩略图走 fetch 读取 X-Screen-State 头，卡片显示 亮屏中/熄屏中
+const STATUS_MAP={idle:'空闲',connecting:'连接中',running:'运行中',done:'完成',error:'异常',released:'已释放',failed:'失败'};
+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.miui.home':'桌面','com.android.launcher':'桌面','com.android.settings':'设置','com.android.systemui':'系统'};
+let _devices=[];
+let _ctrlSerial='';          // 操作弹窗当前设备
+let _ctrlTimer=null;         // 弹窗状态刷新定时器
+let _screenState={};         // serial -> on/off（来自缩略图响应头）
+
+function esc(s){return String(s||'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));}
+// CSRF：独立页面需先取 token，POST 必须携带（与主后台 base.js 一致）
+let _csrfToken='';
+async function initCsrf(){
+  try{const r=await fetch('/api/csrf');const d=await r.json();_csrfToken=d.token||'';}catch(e){}
+}
+async function apiGet(url){
+  try{
+    const r=await fetch(url);
+    if(r.status===401){window.location='/login';return null;}
+    return await r.json();
+  }catch(e){return null;}
+}
+async function apiPost(url,body){
+  try{
+    const r=await fetch(url,{method:'POST',headers:{'Content-Type':'application/json','X-CSRF-Token':_csrfToken},body:JSON.stringify(body||{})});
+    if(r.status===401){window.location='/login';return null;}
+    return await r.json();
+  }catch(e){return null;}
+}
+
+// 时钟
+function tickClock(){
+  const now=new Date();
+  document.getElementById('wall-clock').textContent=
+    String(now.getHours()).padStart(2,'0')+':'+String(now.getMinutes()).padStart(2,'0')+':'+String(now.getSeconds()).padStart(2,'0');
+  document.getElementById('wall-date').textContent=
+    now.getFullYear()+'-'+String(now.getMonth()+1).padStart(2,'0')+'-'+String(now.getDate()).padStart(2,'0')+' '+['周日','周一','周二','周三','周四','周五','周六'][now.getDay()];
+}
+
+// 状态刷新（5s）
+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]));
+  _devices=devs;
+  renderStats(devs);
+  if(changed)renderGrid(visibleDevs(devs));
+  // 操作弹窗打开时同步刷新其标题状态
+  if(_ctrlSerial)updateCtrlHead();
+}
+
+// 「只看在线」勾选时过滤离线设备（默认勾选）
+function visibleDevs(devs){
+  const onlyOnline=document.getElementById('wall-filter-online')
+    ? document.getElementById('wall-filter-online').checked : true;
+  return onlyOnline? devs.filter(d=>d.present) : devs;
+}
+
+function renderStats(devs){
+  const online=devs.filter(d=>d.present).length;
+  const running=devs.filter(d=>['running','connecting'].includes(d.worker_status)).length;
+  const error=devs.filter(d=>['error','failed'].includes(d.worker_status)).length;
+  document.getElementById('wall-stats').innerHTML=
+    '<div class="stat"><div class="n">'+devs.length+'</div><div class="l">设备总数</div></div>'+
+    '<div class="stat online"><div class="n">'+online+'</div><div class="l">在线</div></div>'+
+    '<div class="stat running"><div class="n">'+running+'</div><div class="l">运行中</div></div>'+
+    '<div class="stat error"><div class="n">'+error+'</div><div class="l">异常</div></div>';
+}
+
+function cardCls(d){
+  if(['error','failed'].includes(d.worker_status))return 'error';
+  if(['running','connecting'].includes(d.worker_status))return 'running';
+  return d.present?'online':'offline';
+}
+// 状态角标文案：运行中/异常优先，其次熄屏/亮屏状态
+function badgeText(d){
+  if(['running','connecting'].includes(d.worker_status))return STATUS_MAP[d.worker_status]||d.worker_status;
+  if(['error','failed'].includes(d.worker_status))return STATUS_MAP[d.worker_status]||d.worker_status;
+  if(!d.present)return '离线';
+  return _screenState[d.serial]==='off'?'熄屏中':'亮屏中';
+}
+function fmtProgress(p){
+  if(!p||!p.total)return '';
+  const pct=Math.min(100,Math.round((p.done||0)/p.total*100));
+  return '<div class="prog"><i style="width:'+pct+'%"></i></div>'+
+         '<div class="prog-txt">'+(p.done||0)+'/'+p.total+(p.unit?' '+esc(p.unit):'')+' · '+pct+'%</div>';
+}
+function shortIp(serial){return String(serial||'').replace(/:5555$/,'');}
+
+function cardHtml(d, i){
+  const cls=cardCls(d);
+  const serial=esc(d.serial);
+  const name=esc(d.device_name||d.model||'设备');
+  const ip=esc(shortIp(d.serial));
+  const st=badgeText(d);
+  const stTag=_screenState[d.serial]==='off'?'<div class="screen-tag off">🌙</div>':'';
+  const action=d.current_action
+    ?'<div class="action">'+(d.task_job?'<b>'+esc(d.task_job)+'</b> · ':'')+esc(d.current_action)+'</div>'
+    :(d.task_job?'<div class="action"><b>'+esc(d.task_job)+'</b></div>':'<div class="action"></div>');
+  return '<div class="card '+cls+'" data-serial="'+serial+'" style="animation-delay:'+(i*30)+'ms" onclick="openCtrl(\''+serial+'\')">'+
+    '<div class="thumb">'+
+      '<img data-thumb="'+serial+'" alt="">'+
+      '<div class="ph"><span class="ico">📱</span><span>'+serial+'</span></div>'+
+      '<div class="badge"><span class="dot"></span>'+st+'</div>'+stTag+
+    '</div>'+
+    '<div class="info">'+
+      '<div class="name">'+name+'</div>'+
+      '<div class="ip">'+ip+'</div>'+
+      '<div class="model">'+esc(d.model||'')+'</div>'+
+      action+fmtProgress(d.progress)+
+      '<div class="hint">点击进入设备操作</div>'+
+    '</div>'+
+  '</div>';
+}
+
+// 增量渲染：已有卡片只更新信息区（不重建 img，缩略图不闪不重载）；增删设备才动 DOM
+function renderGrid(devs){
+  const grid=document.getElementById('wall-grid');
+  if(!devs.length){
+    grid.innerHTML='<div class="empty-wall">设备池为空，请到「工具 → 设备池管理」添加设备</div>';
+    return;
+  }
+  const existing={};
+  grid.querySelectorAll('.card').forEach(c=>{existing[c.dataset.serial]=c;});
+  // 1. 移除已不存在的卡片
+  Object.keys(existing).forEach(s=>{
+    if(!devs.find(d=>d.serial===s))existing[s].remove();
+  });
+  // 2. 更新/新建
+  devs.forEach((d,i)=>{
+    const serial=d.serial;
+    const card=existing[serial];
+    if(card){
+      // 已有卡片：只更新状态类信息（badge/class/信息区），不动 img
+      card.className='card '+cardCls(d);
+      const badge=card.querySelector('.badge');
+      const bt=badgeText(d);
+      if(badge&&badge.textContent!==bt)badge.innerHTML='<span class="dot"></span>'+bt;
+      // 熄屏角标
+      const tag=card.querySelector('.screen-tag');
+      if(_screenState[serial]==='off'&&!tag)card.querySelector('.thumb').insertAdjacentHTML('beforeend','<div class="screen-tag off">🌙</div>');
+      else if(_screenState[serial]!=='off'&&tag)tag.remove();
+      // 信息区
+      card.querySelector('.name').textContent=d.device_name||d.model||'设备';
+      card.querySelector('.ip').textContent=shortIp(serial);
+      card.querySelector('.model').textContent=d.model||'';
+      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>':'');
+      card.querySelector('.action').innerHTML=action;
+      // 进度
+      const progWrap=card.querySelector('.prog-wrap');
+      if(progWrap)progWrap.innerHTML=fmtProgress(d.progress);
+      else if(d.progress&&d.progress.total)card.querySelector('.info').insertAdjacentHTML('beforeend','<div class="prog-wrap">'+fmtProgress(d.progress)+'</div>');
+      // 离线占位切换
+      const img=card.querySelector('img[data-thumb]');
+      const ph=card.querySelector('.ph');
+      if(d.present){if(img)img.style.display='block';if(ph)ph.style.display='none';}
+      else{if(img)img.style.display='none';if(ph)ph.style.display='flex';}
+    }else{
+      grid.insertAdjacentHTML('beforeend',cardHtml(d,i));
+      const nc=grid.lastElementChild;
+      if(!d.present)nc.querySelector('.ph').style.display='flex';
+    }
+  });
+  refreshThumbs();
+}
+
+// 缩略图轮询（2.5s）：fetch 读取 X-Screen-State 头 → blob 喂 img
+async function refreshThumbs(){
+  // 进入设备操作弹窗后：停止全部缩略图获取，资源全部给当前设备的高清流
+  if(_ctrlSerial)return;
+  if(document.visibilityState!=='visible')return;
+  const now=Date.now();
+  const imgs=[...document.querySelectorAll('img[data-thumb]')];
+  await Promise.all(imgs.map(async img=>{
+    const serial=img.dataset.thumb;
+    try{
+      const r=await fetch('/api/screen/thumb?serial='+encodeURIComponent(serial)+'&t='+now);
+      if(!r.ok)return;
+      _screenState[serial]=r.headers.get('X-Screen-State')||'unknown';
+      const blob=await r.blob();
+      if(blob.size>0)img.src=URL.createObjectURL(blob);
+      // 状态角标变化时更新（熄屏中/亮屏中）
+      const card=img.closest('.card');
+      if(card){
+        const d=_devices.find(x=>x.serial===serial);
+        if(d&&d.present&&!(['running','connecting','error','failed'].includes(d.worker_status))){
+          const badge=card.querySelector('.badge');
+          const txt=badgeText(d);
+          if(badge&&badge.textContent!==txt)badge.innerHTML='<span class="dot"></span>'+txt;
+          const tag=card.querySelector('.screen-tag');
+          if(_screenState[serial]==='off'&&!tag)card.querySelector('.thumb').insertAdjacentHTML('beforeend','<div class="screen-tag off">🌙</div>');
+          else if(_screenState[serial]!=='off'&&tag)tag.remove();
+        }
+      }
+    }catch(e){}
+  }));
+}
+
+// ================== 一键亮屏 ==================
+async function wakeAll(){
+  const btn=document.getElementById('btn-wake-all');
+  btn.disabled=true;btn.textContent='亮屏中...';
+  const r=await apiPost('/api/device/screen_all',{mode:'on'});
+  btn.disabled=false;btn.textContent='💡 一键亮屏';
+  if(r&&r.ok){refreshStatus();setTimeout(refreshThumbs,800);}
+}
+
+// ================== 设备操作弹窗（看屏 + 触控） ==================
+function openCtrl(serial){
+  const d=_devices.find(x=>x.serial===serial);
+  if(!d)return;
+  _ctrlSerial=serial;
+  document.getElementById('ctrl-name').textContent=d.device_name||d.model||shortIp(serial);
+  document.getElementById('ctrl-sub').textContent=serial;
+  document.getElementById('ctrl-overlay').classList.add('show');
+  const img=document.getElementById('ctrl-img');
+  img.src='';
+  document.getElementById('ctrl-loading').style.display='flex';
+  img.onload=()=>{document.getElementById('ctrl-loading').style.display='none';};
+  img.onerror=()=>{document.getElementById('ctrl-loading').style.display='none';};
+  startCtrlStream();
+}
+function closeCtrl(){
+  _ctrlSerial='';
+  document.getElementById('ctrl-overlay').classList.remove('show');
+  document.getElementById('ctrl-img').src='';
+}
+function startCtrlStream(){
+  if(!_ctrlSerial)return;
+  const img=document.getElementById('ctrl-img');
+  img.src='/api/screen/stream?serial='+encodeURIComponent(_ctrlSerial)+'&q=85&fps=10&t='+Date.now();  // 弹窗高清高帧
+}
+function updateCtrlHead(){
+  const d=_devices.find(x=>x.serial===_ctrlSerial);
+  if(!d)return;
+  document.getElementById('ctrl-name').textContent=d.device_name||d.model||shortIp(_ctrlSerial);
+  document.getElementById('ctrl-sub').textContent=_ctrlSerial+(d.present?'':'（离线）');
+}
+// 坐标映射：显示尺寸 -> 设备原生分辨率
+// 图片 object-fit:contain 时实际绘制区域小于盒子（居中留黑边），
+// 必须按绘制区域换算，否则黑边/偏移导致点击错位
+function ctrlCoords(ev){
+  const img=document.getElementById('ctrl-img');
+  if(!img.naturalWidth||!img.naturalHeight)return[null,null];
+  const r=img.getBoundingClientRect();
+  const scale=Math.min(r.width/img.naturalWidth,r.height/img.naturalHeight);
+  const drawW=img.naturalWidth*scale, drawH=img.naturalHeight*scale;
+  const ox=(r.width-drawW)/2, oy=(r.height-drawH)/2;   // contain 偏移
+  const px=ev.clientX-r.left, py=ev.clientY-r.top;
+  if(px<ox||px>ox+drawW||py<oy||py>oy+drawH)return[null,null]; // 黑边点击忽略
+  return[Math.round((px-ox)/scale),Math.round((py-oy)/scale)];
+}
+function ctrlTap(x,y){
+  if(x==null||!x)return;
+  apiPost('/api/screen/tap',{serial:_ctrlSerial,x,y});
+}
+function ctrlSwipe(x1,y1,x2,y2){
+  if(x1==null)return;
+  apiPost('/api/screen/swipe',{serial:_ctrlSerial,x1,y1,x2,y2});
+}
+function ctrlKey(key){
+  if(!_ctrlSerial)return;
+  apiPost('/api/screen/key',{serial:_ctrlSerial,key});
+}
+function ctrlWake(){if(_ctrlSerial)apiPost('/api/device/screen_all',{mode:'on',serials:[_ctrlSerial]});}
+function ctrlSleep(){if(_ctrlSerial)apiPost('/api/device/screen_all',{mode:'off',serials:[_ctrlSerial]});}
+function ctrlSendText(){
+  const inp=document.getElementById('ctrl-text');
+  const text=(inp.value||'').trim();
+  if(!_ctrlSerial||!text)return;
+  apiPost('/api/screen/text',{serial:_ctrlSerial,text}).then(r=>{if(r&&r.ok)inp.value='';});
+}
+// 鼠标/触控：拖拽=滑动，点按=轻触
+(function(){
+  const screen=document.getElementById('ctrl-screen');
+  let dragging=false,sx=0,sy=0;
+  screen.addEventListener('mousedown',ev=>{
+    if(!_ctrlSerial)return;
+    ev.preventDefault();dragging=true;
+    const[x,y]=ctrlCoords(ev);sx=x;sy=y;
+  });
+  screen.addEventListener('mousemove',ev=>{if(dragging)ev.preventDefault();});
+  window.addEventListener('mouseup',ev=>{
+    if(!dragging)return;dragging=false;
+    const[x,y]=ctrlCoords(ev);
+    if(x==null)return;
+    if(Math.abs(x-sx)<8&&Math.abs(y-sy)<8)ctrlTap(x,y);
+    else ctrlSwipe(sx,sy,x,y);
+  });
+  screen.addEventListener('touchstart',ev=>{
+    if(!_ctrlSerial)return;
+    ev.preventDefault();const t=ev.touches[0];dragging=true;
+    const[x,y]=ctrlCoords(t);sx=x;sy=y;
+  },{passive:false});
+  screen.addEventListener('touchend',ev=>{
+    if(!dragging)return;dragging=false;
+    const t=ev.changedTouches[0];
+    const[x,y]=ctrlCoords(t);
+    if(x==null)return;
+    if(Math.abs(x-sx)<8&&Math.abs(y-sy)<8)ctrlTap(x,y);
+    else ctrlSwipe(sx,sy,x,y);
+  },{passive:false});
+})();
+
+// 定时器
+setInterval(()=>{if(document.visibilityState==='visible')refreshThumbs();},5000);  // 网格低帧率（省资源）
+setInterval(()=>{if(document.visibilityState==='visible')refreshStatus();},5000);
+
+// 初始化
+initCsrf();tickClock();setInterval(tickClock,1000);
+refreshStatus();
+document.addEventListener('visibilitychange',()=>{
+  if(document.visibilityState==='visible'){refreshStatus();refreshThumbs();}
+});
+</script>
+</body>
+</html>

web/__init__.py

@@ -0,0 +1,28 @@
+"""Web 层蓝图包：web_server.py 只保留 app 初始化与装配，路由按功能域拆分。
+
+模块划分（按功能定位问题）：
+  auth        — 登录/登出/CSRF/权限装饰器/页面路由（/、/wall）
+  monitor     — 状态/运行控制/设备操作/远程看屏
+  tasks       — 任务计划/分组/自定义动作/元素抓取/步骤测试
+  admin       — 用户管理/日志
+  tools       — adb 终端/剪贴板注入/应用版本
+  devices     — 设备池管理
+  apks        — 应用管理
+  tailscale   — Tailscale 管理
+"""
+from flask import Blueprint
+
+
+def register_blueprints(app):
+    """注册全部蓝图（url_prefix 为空，路由路径保持原样）。"""
+    from .auth import bp as auth_bp
+    from .monitor import bp as monitor_bp
+    from .tasks_api import bp as tasks_bp
+    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 .apks_api import bp as apks_bp
+    from .tailscale_api import bp as tailscale_bp
+    for bp in (auth_bp, monitor_bp, tasks_bp, admin_bp, tools_bp,
+               devices_bp, apks_bp, tailscale_bp):
+        app.register_blueprint(bp)

web/admin_api.py

@@ -0,0 +1,101 @@
+"""管理域 API：用户管理/日志查看。"""
+import os
+import time
+
+from flask import Blueprint, jsonify, request
+from flask_login import current_user
+from flask import session
+
+from core.logger import _LOG_DIR, _MODULE_FILES
+from core.models import db, User
+from web import context
+from web.auth import (admin_required, perm_required, _validate_perms,
+                             PERM_LOGS)
+
+bp = Blueprint("admin", __name__)
+
+@bp.route("/api/users")
+@admin_required
+def api_users_list():
+    users = [{"id": u.id, "username": u.username,
+              "is_admin": u.is_admin, "perms": u.get_perms()} for u in User.query.all()]
+    return jsonify({"ok": True, "users": users})
+
+@bp.route("/api/users", methods=["POST"])
+@admin_required
+def api_users_create():
+    data = request.json or {}
+    username = (data.get("username") or "").strip()
+    password = data.get("password", "")
+    if not username or not password:
+        return jsonify({"ok": False, "error": "用户名和密码不能为空"}), 400
+    if User.query.filter_by(username=username).first():
+        return jsonify({"ok": False, "error": "用户名已存在"}), 400
+    # 默认普通用户（最小权限）；管理员由 is_admin 决定，权限位照常保存（降级后生效）
+    u = User(username=username, is_admin=bool(data.get("is_admin", False)))
+    u.set_perms(_validate_perms(data.get("perms") or []))
+    u.set_password(password)
+    db.session.add(u)
+    db.session.commit()
+    _log.info(f"创建用户 {username} (admin={u.is_admin}, perms={u.get_perms()})")
+    return jsonify({"ok": True, "msg": "用户已创建"})
+
+@bp.route("/api/users/<int:uid>", methods=["PUT"])
+@admin_required
+def api_users_update(uid):
+    u = User.query.get(uid)
+    if not u:
+        return jsonify({"ok": False, "error": "用户不存在"}), 404
+    data = request.json or {}
+    if "password" in data and data["password"]:
+        u.set_password(data["password"])
+    if "is_admin" in data:
+        new_admin = bool(data["is_admin"])
+        if u.is_admin and not new_admin and User.query.filter_by(is_admin=True).count() <= 1:
+            return jsonify({"ok": False, "error": "不能取消最后一个管理员"}), 400
+        u.is_admin = new_admin
+    if "perms" in data:
+        u.set_perms(_validate_perms(data["perms"]))
+    db.session.commit()
+    _log.info(f"更新用户 {u.username} (admin={u.is_admin}, perms={u.get_perms()})")
+    return jsonify({"ok": True, "msg": "用户已更新"})
+
+@bp.route("/api/users/<int:uid>", methods=["DELETE"])
+@admin_required
+def api_users_delete(uid):
+    u = User.query.get(uid)
+    if not u:
+        return jsonify({"ok": False, "error": "用户不存在"}), 404
+    if u.username == "admin":
+        return jsonify({"ok": False, "error": "不能删除默认管理员"}), 400
+    if u.id == current_user.id:
+        return jsonify({"ok": False, "error": "不能删除当前登录用户"}), 400
+    if u.is_admin and User.query.filter_by(is_admin=True).count() <= 1:
+        return jsonify({"ok": False, "error": "不能删除最后一个管理员"}), 400
+    db.session.delete(u)
+    db.session.commit()
+    _log.info(f"删除用户 {u.username}")
+    return jsonify({"ok": True, "msg": "用户已删除"})
+
+
+# ================== API：日志查看 ==================
+
+@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})
+
+
+# ================== API：运行控制 ==================
+

web/apks_api.py

@@ -0,0 +1,123 @@
+"""应用管理 API（APK 上传/安装/删除/设备已装应用）。"""
+import re
+import shlex
+import subprocess
+
+from flask import Blueprint, jsonify, request
+from flask_login import login_required
+
+from core import device_pool
+from core.adb_helper import adb_connect_light, _adb
+from web import context
+from web.auth import perm_required, PERM_APKS
+from web.common import _merged_device_list
+
+bp = Blueprint("apks", __name__)
+
+@bp.route("/api/apks")
+@login_required
+def api_apks_list():
+    """列出所有已上传的 APK。"""
+    return jsonify({"ok": True, "apks": context.apk_mgr.list_all()})
+
+@bp.route("/api/apks/upload", methods=["POST"])
+@perm_required(PERM_APKS)
+def api_apks_upload():
+    """上传 APK 文件（multipart/form-data，字段名 file）。"""
+    file = request.files.get("file")
+    if not file or not file.filename:
+        return jsonify({"ok": False, "error": "未选择文件"}), 400
+    info = context.apk_mgr.upload(file)
+    if info:
+        return jsonify({"ok": True, "apk": info,
+                        "msg": f"上传成功: {info['display_name']}"})
+    return jsonify({"ok": False, "error": "上传失败，请检查文件格式"}), 500
+
+@bp.route("/api/apks/<apk_id>", methods=["DELETE"])
+@perm_required(PERM_APKS)
+def api_apks_delete(apk_id):
+    """删除 APK 文件和记录。"""
+    ok, msg = context.apk_mgr.delete(apk_id)
+    if ok:
+        return jsonify({"ok": True, "msg": msg})
+    return jsonify({"ok": False, "error": msg}), 400
+
+@bp.route("/api/apks/install/devices")
+@perm_required(PERM_APKS)
+def api_apks_install_devices():
+    """可安装设备列表（应用管理）：设备池在线设备 + 本机 adb 设备（含 USB 有线连接）。
+
+    source: pool=设备池 / usb=本机有线 adb / adb=本机网络 adb。
+    """
+    devices, seen = [], set()
+    try:
+        online = set(device_pool.list_online())
+        for serial in device_pool.list_configured():
+            if serial in online:
+                devices.append({"serial": serial, "model": "", "source": "pool"})
+                seen.add(serial)
+    except Exception:
+        pass
+    out = _adb("devices")
+    for line in (out or "").splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[0] and parts[0] not in seen:
+            devices.append({"serial": parts[0], "model": "",
+                            "source": "usb" if ":" not in parts[0] else "adb"})
+            seen.add(parts[0])
+    return jsonify({"ok": True, "devices": devices})
+
+@bp.route("/api/apks/install", methods=["POST"])
+@perm_required(PERM_APKS)
+def api_apks_install():
+    """批量安装 APK 到指定设备。参数: {apk_id, serials:[]}"""
+    data = request.json or {}
+    apk_id = data.get("apk_id", "")
+    serials = data.get("serials", [])
+    ok, msg = context.apk_mgr.install(apk_id, serials)
+    if ok:
+        return jsonify({"ok": True, "msg": msg})
+    return jsonify({"ok": False, "error": msg}), 400
+
+@bp.route("/api/apks/install/status")
+@login_required
+def api_apks_install_status():
+    """获取安装任务实时状态。"""
+    status = context.apk_mgr.get_install_status()
+    return jsonify({"ok": True, "status": status})
+
+
+# ================== API：维护（仅管理员） ==================
+# 维护功能：STF 容器一键重启 + adb 远程终端。两个接口都仅管理员可用。
+# adb 终端安全红线（技术约束）：绝不 kill-server / 绝不 disconnect IP:5555——
+# STF provider 共享该 adb transport，断开会让 STF 误判全部设备离线并触发重连。
+_ADB_BLOCKED_PATTERNS = ("kill-server", "disconnect")
+
+
+def _blocked_adb_cmd(cmd):
+    """命中红线的 adb 命令（kill-server / disconnect）直接拒绝。"""
+    low = cmd.lower()
+    return any(p in low for p in _ADB_BLOCKED_PATTERNS)
+
+
+def _merged_device_list():
+    """本地 adb（含 USB）+ 设备池的合并列表（[{serial, state}]）。
+
+    供维护终端/剪贴板注入/应用版本管理等设备选择场景共用。
+    状态：device/offline=本机 adb 实际状态；pool=设备池已配置但本机未连接；
+    stf_not_ready=STF agent 未就绪（迁移期保留，阶段 3 摘除 STF 后删除）。
+    """
+    states = {}
+    out = _adb("devices")
+    for line in (out or "").splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[0] and not parts[0].startswith("*"):
+            states[parts[0]] = parts[1]
+    try:
+        for serial in device_pool.list_configured():
+            if serial not in states:
+                states[serial] = "pool"
+    except Exception:
+        pass
+    return [{"serial": s, "state": st} for s, st in sorted(states.items())]
+

web/auth.py

@@ -0,0 +1,157 @@
+"""认证与页面路由：登录/登出/CSRF/权限装饰器/页面（/、/wall）。
+
+CSRF 的 before_request 由 web_server 注册（app 级），本模块提供实现。
+"""
+import functools
+import secrets
+
+from flask import (Blueprint, jsonify, request, redirect, url_for,
+                   render_template, make_response, session)
+from flask_login import (login_user, logout_user, login_required, current_user)
+
+from core.logger import get_logger
+from core.models import User
+
+_log = get_logger("web")
+
+bp = Blueprint("auth", __name__)
+
+
+# ================== CSRF ==================
+def _csrf_token():
+    """获取或生成当前会话的 CSRF token（非 GET 请求需在 X-CSRF-Token 头携带）。"""
+    if "csrf_token" not in session:
+        session["csrf_token"] = secrets.token_hex(16)
+    return session["csrf_token"]
+
+
+def _csrf_protect():
+    """非安全方法（POST/PUT/DELETE/PATCH）校验 X-CSRF-Token 请求头。"""
+    if request.method not in ("POST", "PUT", "DELETE", "PATCH"):
+        return
+    # 登录表单（未登录，尚无 token）和静态文件跳过
+    if request.endpoint in ("login", "static"):
+        return
+    sess = session.get("csrf_token", "")
+    header = request.headers.get("X-CSRF-Token", "")
+    if not sess or header != sess:
+        return jsonify({"ok": False, "error": "CSRF 校验失败"}), 403
+
+
+@bp.route("/api/csrf")
+@login_required
+def api_csrf():
+    """获取 CSRF token（前端非 GET 请求需携带 X-CSRF-Token 头）。"""
+    return jsonify({"ok": True, "token": _csrf_token()})
+
+
+# ================== 权限控制 ==================
+PERM_TASKS = "tasks"
+PERM_DEVICES = "devices"
+PERM_APKS = "apks"
+PERM_LOGS = "logs"
+ALL_PERMS = (PERM_TASKS, PERM_DEVICES, PERM_APKS, PERM_LOGS)
+_PERM_LABELS = {PERM_TASKS: "任务管理", PERM_DEVICES: "设备控制",
+                PERM_APKS: "应用管理", PERM_LOGS: "日志查看"}
+
+
+def _has_perm(perm):
+    """当前用户是否拥有指定权限。管理员恒为 True。"""
+    u = current_user
+    return bool(u and (u.is_admin or u.has_perm(perm)))
+
+
+def _validate_perms(raw):
+    """校验权限位列表：只保留合法值、去重。返回合法列表。"""
+    valid = set(ALL_PERMS)
+    out = []
+    for p in raw or []:
+        if p in valid and p not in out:
+            out.append(p)
+    return out
+
+
+def perm_required(perm):
+    """路由装饰器：要求登录且拥有指定业务权限，否则 403。"""
+    def deco(fn):
+        @functools.wraps(fn)
+        @login_required
+        def wrapper(*args, **kwargs):
+            if not _has_perm(perm):
+                return jsonify({"ok": False,
+                                "error": f"无权限执行此操作（需要权限: {_PERM_LABELS.get(perm, perm)}）"}), 403
+            return fn(*args, **kwargs)
+        return wrapper
+    return deco
+
+
+def admin_required(fn):
+    """路由装饰器：仅管理员可用（用户管理类接口），否则 403。"""
+    @functools.wraps(fn)
+    @login_required
+    def wrapper(*args, **kwargs):
+        if not current_user.is_admin:
+            return jsonify({"ok": False, "error": "仅管理员可执行此操作"}), 403
+        return fn(*args, **kwargs)
+    return wrapper
+
+
+@bp.route("/api/me")
+@login_required
+def api_me():
+    """当前登录用户信息（含权限位），前端据此隐藏无权限的功能入口。"""
+    u = current_user
+    return jsonify({"ok": True, "user": {
+        "id": u.id,
+        "username": u.username,
+        "is_admin": bool(u.is_admin),
+        # 管理员返回全部权限位，前端统一用 perms 判断
+        "perms": list(ALL_PERMS) if u.is_admin else u.get_perms(),
+    }})
+
+
+# ================== 页面路由 ==================
+@bp.route("/")
+@login_required
+def index():
+    """单页应用首页。"""
+    resp = make_response(render_template("admin/monitor.html"))
+    resp.headers["Cache-Control"] = "no-store, no-cache, must-revalidate, max-age=0"
+    resp.headers["Pragma"] = "no-cache"
+    return resp
+
+
+@bp.route("/wall")
+@login_required
+def wall():
+    """监控大屏（独立全屏页面，供挂墙/电视展示）。
+
+    深色控制室风格；设备缩略图按需轮询（每设备 ~5s 一帧），
+    20 台设备整体开销约 0.1 核 CPU + 50KB/s，普通电脑无压力。
+    """
+    resp = make_response(render_template("admin/wall.html"))
+    resp.headers["Cache-Control"] = "no-store, no-cache, must-revalidate, max-age=0"
+    return resp
+
+
+@bp.route("/login", methods=["GET", "POST"])
+def login():
+    if request.method == "POST":
+        username = request.form.get("username", "")
+        password = request.form.get("password", "")
+        user = User.query.filter_by(username=username).first()
+        if user and user.check_password(password):
+            login_user(user)
+            _csrf_token()  # 建立 CSRF token，前端通过 /api/csrf 获取
+            _log.info(f"用户 {username} 登录")
+            return redirect(request.args.get("next") or url_for("auth.index"))
+        return render_template("admin/login.html", error="用户名或密码错误")
+    return render_template("admin/login.html", error=None)
+
+
+@bp.route("/logout")
+@login_required
+def logout():
+    _log.info(f"用户 {current_user.username} 登出")
+    logout_user()
+    return redirect(url_for("auth.login"))

web/common.py

@@ -0,0 +1,46 @@
+"""跨模块共享工具（web 层）。"""
+from core import device_pool
+from core.adb_helper import _adb
+from core.logger import get_logger
+
+_log = get_logger("web")
+
+
+def _merged_device_list():
+    """本地 adb（含 USB）+ 设备池的合并列表（[{serial, state}]）。
+
+    供维护终端/剪贴板注入/应用版本管理等设备选择场景共用。
+    状态：device/offline=本机 adb 实际状态；pool=设备池已配置但本机未连接。
+    """
+    states = {}
+    out = _adb("devices")
+    for line in (out or "").splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[0] and not parts[0].startswith("*"):
+            states[parts[0]] = parts[1]
+    try:
+        for serial in device_pool.list_configured():
+            if serial not in states:
+                states[serial] = "pool"
+    except Exception:
+        pass
+    return [{"serial": s, "state": st} for s, st in sorted(states.items())]
+
+
+def _device_screen_state(serial):
+    """设备屏幕状态：on/off/unknown（dumpsys power 只读查询）。
+
+    用 mWakefulness 判断（Asleep=熄屏）：MIUI 的 dumpsys display 没有
+    mScreenState 字段，power 字段全机型存在。USB 设备查询失败返回 unknown。
+    """
+    try:
+        if ":" not in serial:
+            return "unknown"
+        out = _adb("-s", serial, "shell", "dumpsys", "power") or ""
+        import re
+        m = re.search(r"mWakefulness=(\w+)", out)
+        if m:
+            return "off" if m.group(1).lower() == "asleep" else "on"
+    except Exception:
+        pass
+    return "unknown"

web/context.py

@@ -0,0 +1,12 @@
+"""共享上下文：web_server 启动时注入全局对象，各蓝图模块从这里取。
+
+避免蓝图模块与 web_server 循环 import。
+"""
+mgr = None          # core.task_manager.TaskManager
+apk_mgr = None      # core.apk_manager.ApkManager
+device_pool = None  # core.device_pool
+
+
+def init(mgr_, apk_mgr_, device_pool_):
+    global mgr, apk_mgr, device_pool
+    mgr, apk_mgr, device_pool = mgr_, apk_mgr_, device_pool_

web/devices_api.py

@@ -0,0 +1,203 @@
+"""设备池管理 API（本地 SQLite 清单）。"""
+import threading
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from flask import Blueprint, jsonify, request
+
+from core import device_pool, device_discovery
+from core.adb_helper import adb_connect
+from core.logger import get_logger
+from web.auth import perm_required, PERM_DEVICES
+
+_log = get_logger("web")
+bp = Blueprint("devices", __name__)
+
+@bp.route("/api/devices/pool", methods=["GET"])
+@perm_required(PERM_DEVICES)
+def api_devices_pool_list():
+    """设备池清单（SQLite，含实时在线状态）。"""
+    try:
+        online = set(device_pool.list_online())
+    except Exception:
+        online = set()
+    rows = device_pool.list_devices()
+    for r in rows:
+        r["online"] = r["serial"] in online
+    return jsonify({"ok": True, "devices": rows})
+
+@bp.route("/api/devices/pool/add", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_pool_add():
+    """添加/更新设备：{serial, name?, note?}。
+
+    IP:5555 设备添加后立即尝试 adb connect（不可达显示离线，不影响其他设备）。
+    """
+    data = request.json or {}
+    serial = (data.get("serial") or "").strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "请输入设备 serial（如 100.100.10.20:5555）"}), 400
+    is_new = device_pool.add_device(serial,
+                                    name=(data.get("name") or "").strip(),
+                                    note=(data.get("note") or "").strip())
+    msg = "已添加" if is_new else "已更新"
+    if ":" in serial:
+        try:
+            adb_connect(serial)
+        except Exception:
+            pass
+    # 后台采集型号（不阻塞添加响应）
+    import threading
+    threading.Thread(target=device_pool.refresh_model, args=(serial,),
+                     daemon=True).start()
+    _log.info(f"设备池管理: {msg} {serial}")
+    return jsonify({"ok": True, "msg": msg, "is_new": is_new})
+
+@bp.route("/api/devices/pool/remove", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_pool_remove():
+    """从设备池删除（不再参与调度；不影响其他系统）。"""
+    serial = (request.json or {}).get("serial", "").strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    ok = device_pool.remove_device(serial)
+    if not ok:
+        return jsonify({"ok": False, "error": "设备不存在"}), 404
+    return jsonify({"ok": True, "msg": "已删除"})
+
+@bp.route("/api/devices/pool/toggle", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_pool_toggle():
+    """启用/停用设备（停用后不参与调度）。"""
+    data = request.json or {}
+    serial = (data.get("serial") or "").strip()
+    enabled = data.get("enabled")
+    if not serial or enabled is None:
+        return jsonify({"ok": False, "error": "缺少参数"}), 400
+    ok = device_pool.set_enabled(serial, bool(enabled))
+    if not ok:
+        return jsonify({"ok": False, "error": "设备不存在"}), 404
+    return jsonify({"ok": True, "msg": "已" + ("启用" if enabled else "停用")})
+
+@bp.route("/api/devices/pool/reconnect", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_pool_reconnect():
+    """一键重连：并发 adb connect 池内全部 IP:5555 设备（后台执行，不阻塞）。"""
+    def _run():
+        try:
+            serials = [s for s in device_pool.list_configured() if ":" in s]
+        except Exception:
+            return
+        if not serials:
+            return
+        from concurrent.futures import ThreadPoolExecutor, as_completed
+        with ThreadPoolExecutor(max_workers=10) as pool:
+            futures = {pool.submit(adb_connect, s): s for s in serials}
+            for _ in as_completed(futures):
+                pass
+        _log.info(f"设备池一键重连完成（{len(serials)} 台）")
+        # 重连后顺手刷新型号
+        try:
+            device_pool.refresh_all_models()
+        except Exception:
+            pass
+    import threading
+    threading.Thread(target=_run, daemon=True).start()
+    return jsonify({"ok": True, "msg": "重连已启动（后台并发，约 10-20 秒）"})
+
+@bp.route("/api/devices/pool/refresh_models", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_pool_refresh_models():
+    """批量采集池内在线设备的型号（后台执行，不阻塞）。"""
+    import threading
+    threading.Thread(target=device_pool.refresh_all_models, daemon=True).start()
+    return jsonify({"ok": True, "msg": "型号采集已启动（后台并发，约 10 秒）"})
+
+
+# ================== API：设备自动发现（扫描 → 待连接池 → 确认） ==================
+# 扫描只把设备放进待连接池（pending），用户确认后才加入正式设备池并连接。
+@bp.route("/api/devices/discovery", methods=["GET"])
+@perm_required(PERM_DEVICES)
+def api_devices_discovery():
+    """发现状态 + 待连接列表（前端 10s 轮询一次请求）。"""
+    try:
+        status = device_discovery.get_status()
+        pending = device_discovery.list_pending()
+    except Exception as e:
+        _log.warning(f"discovery 状态获取失败: {e}")
+        return jsonify({"ok": False, "error": str(e)[:120]}), 503
+    status["pending"] = pending
+    return jsonify({"ok": True, **status})
+
+
+@bp.route("/api/devices/discovery/scan", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_discovery_scan():
+    """手动触发一轮扫描（后台执行，约 5-30 秒）。"""
+    ok, result = device_discovery.scan_once(manual=True)
+    if not ok:
+        return jsonify({"ok": False, "error": result.get("error", "扫描失败")}), 409
+    if "error" in result:
+        return jsonify({"ok": False, "error": result["error"]}), 400
+    return jsonify({"ok": True, "msg": "扫描已启动（后台执行，约 5-30 秒）",
+                    "result": result})
+
+
+@bp.route("/api/devices/discovery/confirm", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_discovery_confirm():
+    """确认连接：待连接 → 正式设备池 + 后台 adb connect + 采型号。"""
+    data = request.json or {}
+    serial = (data.get("serial") or "").strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    ok, msg, is_new = device_discovery.confirm_pending(
+        serial, name=(data.get("name") or "").strip())
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 404
+    if ":" in serial:
+        def _connect():
+            try:
+                adb_connect(serial)
+            except Exception:
+                pass
+            try:
+                device_pool.refresh_model(serial)
+            except Exception:
+                pass
+        threading.Thread(target=_connect, daemon=True).start()
+    _log.info(f"设备池管理: 发现确认 {serial}")
+    return jsonify({"ok": True, "msg": msg, "is_new": is_new})
+
+
+@bp.route("/api/devices/discovery/ignore", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_discovery_ignore():
+    """忽略：从待连接池删除（下轮扫描可能再次发现）。"""
+    serial = (request.json or {}).get("serial", "").strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    ok, msg = device_discovery.ignore_pending(serial)
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 404
+    return jsonify({"ok": True, "msg": msg})
+
+
+@bp.route("/api/devices/discovery/settings", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_discovery_settings():
+    """保存发现配置（部分字段更新）：{enabled?, subnets?, interval?, port?}。"""
+    data = request.json or {}
+    ok, msg = device_discovery.save_settings(
+        enabled=data.get("enabled"),
+        subnets=data.get("subnets"),
+        interval=data.get("interval"),
+        port=data.get("port"))
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 400
+    return jsonify({"ok": True, "msg": msg})
+
+
+# ================== API：Tailscale 管理（仅管理员） ==================
+# 通过 Tailscale 官方 API v2 管理 tailnet 设备（列表/改名/授权/密钥不过期/删除/生成 auth key）。
+# 设备 IP 由 tailnet 自动分配，API 无法修改，列表只读展示。
+

web/index.html

@@ -1,94 +0,0 @@
-<!DOCTYPE html>
-<html lang="zh-CN"><head><meta charset="UTF-8"><title>设备监控大屏</title>
-<style>
-  *{box-sizing:border-box} body{font-family:-apple-system,"Segoe UI",Roboto,sans-serif;margin:0;background:#f0f2f5;color:#2c3e50}
-  .header{background:#fff;padding:14px 24px;box-shadow:0 1px 4px rgba(0,0,0,.08);display:flex;align-items:center;gap:16px}
-  .header h1{font-size:18px;margin:0} .header .ts{color:#95a5a6;font-size:12px;margin-left:auto}
-  .header a{color:#1890ff;text-decoration:none;font-size:13px}
-  .header a:hover{text-decoration:underline}
-  .content{padding:20px 24px;max-width:1400px;margin:0 auto}
-  .bar{display:flex;gap:8px;margin-bottom:16px;align-items:center;flex-wrap:wrap}
-  button{padding:7px 16px;border:1px solid #d9d9d9;border-radius:4px;cursor:pointer;font-size:13px;background:#fff;color:#595959}
-  button:hover{border-color:#40a9ff;color:#40a9ff} button.primary{background:#1890ff;color:#fff;border-color:#1890ff}
-  button.primary:hover{background:#40a9ff} button.danger{color:#ff4d4f;border-color:#ff4d4f}
-  button.danger:hover{background:#ff4d4f;color:#fff} button.sm{padding:3px 10px;font-size:12px}
-  table{width:100%;border-collapse:collapse;background:#fff;border-radius:6px;overflow:hidden;box-shadow:0 1px 3px rgba(0,0,0,.08)}
-  th,td{padding:9px 10px;text-align:left;border-bottom:1px solid #f0f0f0;font-size:13px}
-  th{background:#fafafa;font-weight:600;color:#595959} tr:hover td{background:#fafafa}
-  .badge{padding:2px 8px;border-radius:10px;font-size:11px;color:#fff}
-  .b-running{background:#52c41a}.b-connecting{background:#faad14}.b-error{background:#ff4d4f}
-  .b-done{background:#1890ff}.b-idle{background:#bfbfbf;color:#595959}.b-released{background:#8c8c8c}.b-failed{background:#ff4d4f}
-  .ok{color:#52c41a}.no{color:#ff4d4f}.muted{color:#8c8c8c;font-size:12px}
-  .err{color:#ff4d4f;font-size:12px;max-width:180px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
-  .progress{width:70px;height:5px;background:#f0f0f0;border-radius:3px;overflow:hidden;display:inline-block;vertical-align:middle}
-  .progress>div{height:100%;background:#1890ff}
-  .tag{display:inline-block;background:#e6f7ff;color:#1890ff;padding:1px 8px;border-radius:3px;font-size:11px;margin:1px}
-  .kv{display:inline-block;background:#f5f5f5;border-radius:3px;padding:0 6px;margin:1px;font-size:11px;color:#595959}
-  .stats{display:flex;gap:16px;margin-bottom:16px}
-  .stat-card{background:#fff;padding:14px 20px;border-radius:6px;box-shadow:0 1px 3px rgba(0,0,0,.08);min-width:120px}
-  .stat-card .num{font-size:24px;font-weight:600;color:#1890ff}
-  .stat-card .lbl{font-size:12px;color:#8c8c8c;margin-top:2px}
-</style></head><body>
-<div class="header">
-  <h1>设备监控大屏</h1>
-  <span class="muted" id="devCount"></span>
-  <span class="ts" id="srvTime"></span>
-  <a href="/admin" target="_blank">管理后台 →</a>
-</div>
-<div class="content">
-  <div class="stats" id="stats"></div>
-  <div class="bar">
-    <button class="primary" onclick="doPost('/api/jobs/_quick/run')" title="快速启动：对全部空闲设备跑默认抖音养号">快速启动全部</button>
-    <button class="danger" onclick="doPost('/api/stop_all')">停止全部</button>
-    <button onclick="doPost('/api/release')">强制释放占用</button>
-    <button onclick="loadStatus()">刷新</button>
-    <span class="muted">每 5 秒自动刷新 · 分组/任务管理请到 <a href="/admin" target="_blank">管理后台</a></span>
-  </div>
-  <table><thead><tr>
-    <th>设备</th><th>型号</th><th>STF</th><th>任务状态</th><th>抖音</th><th>进度</th>
-    <th>任务名称</th><th>当前动作</th><th>操作计数</th><th>最近错误</th><th>操作</th>
-  </tr></thead><tbody id="tb-devices"></tbody></table>
-</div>
-<script>
-const ACTION_LABELS={like:'点赞',comment:'评论',follow:'关注',share:'分享'};
-function doPost(url,body){return fetch(url,{method:'POST',headers:{'Content-Type':'application/json'},body:body?JSON.stringify(body):'{}'}).then(r=>r.json()).then(d=>{alert(JSON.stringify(d,null,1));loadStatus();}).catch(e=>alert(e));}
-function fmtActionCounts(c){
-  if(!c||!Object.keys(c).length)return '<span class="muted">-</span>';
-  const parts=Object.entries(c).filter(([_,v])=>v>0).map(([k,v])=>'<span class="kv">'+(ACTION_LABELS[k]||k)+v+'</span>');
-  return parts.length?parts.join(''):'<span class="muted">-</span>';
-}
-async function loadStatus(){
-  try{
-    const r=await fetch('/api/status');const d=await r.json();if(!d.ok)return;
-    document.getElementById('devCount').textContent='设备 '+d.devices.length;
-    document.getElementById('srvTime').textContent=new Date(d.server_time*1000).toLocaleTimeString();
-    // 统计卡片
-    const running=d.devices.filter(x=>x.worker_status==='running').length;
-    const idle=d.devices.filter(x=>x.worker_status==='idle').length;
-    const error=d.devices.filter(x=>['error','failed'].includes(x.worker_status)).length;
-    const occupied=d.devices.filter(x=>x.stf_occupied).length;
-    document.getElementById('stats').innerHTML=
-      '<div class="stat-card"><div class="num" style="color:#52c41a">'+running+'</div><div class="lbl">运行中</div></div>'+
-      '<div class="stat-card"><div class="num" style="color:#1890ff">'+occupied+'</div><div class="lbl">STF占用</div></div>'+
-      '<div class="stat-card"><div class="num" style="color:#bfbfbf">'+idle+'</div><div class="lbl">空闲</div></div>'+
-      '<div class="stat-card"><div class="num" style="color:#ff4d4f">'+error+'</div><div class="lbl">异常</div></div>';
-    // 设备表格
-    document.getElementById('tb-devices').innerHTML=d.devices.map(dev=>{
-      const stf=dev.stf_occupied?'<span class="badge b-running">占用</span>':'<span class="badge b-idle">空闲</span>';
-      if(!dev.present)stf+=' <span class="no">离线</span>';
-      const ws=dev.worker_status;
-      const wb='<span class="badge b-'+ws+'">'+({idle:'未启动',connecting:'连接中',running:'运行中',done:'完成',error:'异常',released:'已释放',failed:'失败'}[ws]||ws)+'</span>';
-      const dy=dev.douyin_running?'<span class="ok">●</span>':'<span class="no">○</span>';
-      const pct=Math.round(dev.videos_watched/80*100);
-      const prog='<span class="progress"><div style="width:'+pct+'%"></div></span> '+dev.videos_watched;
-      const tname=dev.task_job?'<span class="tag">'+dev.task_job+'</span>':'<span class="muted">-</span>';
-      const retry=dev.attempt>0?' <span class="muted">'+dev.attempt+'次</span>':'';
-      const btn=dev.worker_status==='running'||dev.worker_status==='connecting'?'<button class="danger sm" onclick="doPost(\'/api/stop_device\',{serial:\''+dev.serial+'\'})">停止</button>':'';
-      return '<tr><td>'+dev.serial+'</td><td>'+dev.model+'</td><td>'+stf+'</td><td>'+wb+'</td><td>'+dy+'</td><td>'+prog+'</td><td>'+tname+retry+'</td><td class="muted">'+(dev.current_action||'-')+'</td><td>'+fmtActionCounts(dev.action_counts)+'</td><td class="err" title="'+(dev.last_error||'')+'">'+(dev.last_error||'-')+'</td><td>'+btn+'</td></tr>';
-    }).join('');
-  }catch(e){console.error(e);}
-}
-loadStatus();
-setInterval(loadStatus,5000);
-</script>
-</body></html>

web/monitor.py

@@ -0,0 +1,586 @@
+"""监控域 API：状态/运行控制/设备操作/远程看屏。"""
+import time
+import threading
+import subprocess
+import shlex
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from flask import (Blueprint, jsonify, request, Response, render_template)
+from flask_login import login_required
+
+from core import device_pool
+from core.adb_helper import (screenshot, list_installed_apps, adb_connect,
+                             adb_connect_light, _ADB_LOCK, _adb)
+from core.device_worker import (get_all_worker_status, clear_worker_error,
+                             clear_all_worker_errors)
+from web import context
+from web.auth import perm_required, PERM_DEVICES
+from web.common import _merged_device_list, _device_screen_state
+from config import ADB_PATH
+from core.logger import get_logger
+
+_log = get_logger("web")
+
+bp = Blueprint("monitor", __name__)
+
+# 远程看屏参数
+_SCREEN_JPEG_QUALITY = 65
+_SCREEN_FRAME_GAP = 0.05
+
+@bp.route("/api/health")
+def api_health():
+    """轻量健康检查：返回进程/设备/任务摘要，不暴露敏感信息，供运维探活。"""
+    try:
+        devices, err = context.mgr.get_status()
+        devs = devices or []
+        return jsonify({
+            "ok": True,
+            "status": "up",
+            "time": time.time(),
+            "device_total": len(devs),
+            "device_online": sum(1 for d in devs if d.get("present")),
+            "device_running": sum(1 for d in devs
+                                  if d.get("worker_status") in ("running", "connecting")),
+            "device_error": sum(1 for d in devs
+                                if d.get("worker_status") in ("error", "failed")),
+            "jobs": len(context.mgr.jobs),
+        })
+    except Exception as e:
+        return jsonify({"ok": False, "status": "down", "error": str(e)}), 500
+
+
+# ================== API：失败任务汇总 ==================
+
+@bp.route("/api/summary")
+@login_required
+def api_summary():
+    """失败/异常任务汇总：各状态计数 + 异常设备列表（last_error / 重试次数）。
+
+    供监控页"异常汇总"面板使用，便于长期运行观察设备健康度。
+    """
+    try:
+        sts = get_all_worker_status()
+        # 已删除/不在当前 STF 设备池的设备，其陈旧失败记录不应展示。
+        # 复用 get_status 缓存（顺带触发上面的状态清理），STF 异常时不隐藏任何记录。
+        try:
+            devices, derr = context.mgr.get_status()
+            if not derr:
+                present = {d.get("serial") for d in devices}
+                sts = [s for s in sts if s.get("serial") in present]
+        except Exception:
+            pass
+        counts = {"total": 0, "running": 0, "done": 0,
+                  "error": 0, "failed": 0, "idle": 0}
+        errors = []
+        for s in sts:
+            st = s.get("status", "idle")
+            counts["total"] += 1
+            if st in counts:
+                counts[st] += 1
+            if st in ("error", "failed") and s.get("last_error"):
+                errors.append({
+                    "serial": s.get("serial"),
+                    "model": s.get("model", ""),
+                    "status": st,
+                    "last_error": s.get("last_error", ""),
+                    "task": s.get("task_job", ""),
+                    "attempt": s.get("attempt", 0),
+                    "updated": s.get("last_heartbeat", 0),
+                })
+        errors.sort(key=lambda x: x.get("updated", 0), reverse=True)
+        return jsonify({"ok": True, "counts": counts, "errors": errors[:50]})
+    except Exception as e:
+        return jsonify({"ok": False, "error": str(e)}), 500
+
+
+# ================== API：状态（监控大屏用）==================
+
+@bp.route("/api/status")
+@login_required
+def api_status():
+    devices, err = context.mgr.get_status()
+    if err:
+        return jsonify({"ok": False, "error": err}), 500
+    return jsonify({
+        "ok": True, "devices": devices, "server_time": time.time(),
+        "fg_scanning": context.mgr._fg_scanner.is_scanning,
+        "fg_last_scan": context.mgr._fg_scanner.last_scan_time,
+    })
+
+@bp.route("/api/scan_foreground", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_scan_foreground():
+    """手动触发前台 App 扫描（不打扰设备）。"""
+    started = context.mgr._fg_scanner.scan_once()
+    if started:
+        return jsonify({"ok": True, "msg": "扫描已启动"})
+    return jsonify({"ok": False, "error": "已有扫描在进行中"})
+
+@bp.route("/api/stop_device", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_stop_device():
+    serial = (request.json or {}).get("serial", "")
+    if context.mgr.stop_device(serial):
+        return jsonify({"ok": True, "msg": f"已发送停止信号给 {serial}"})
+    return jsonify({"ok": False, "error": f"{serial} 没有运行中的任务"}), 400
+
+@bp.route("/locate")
+def locate_page():
+    """设备端定位页（免登录）：点亮后浏览器打开，大字显示设备 IP/序列号。
+
+    只展示 serial 文本，无任何平台数据，免登录可接受。
+    """
+    serial = request.args.get("serial", "")
+    return render_template_string(
+        """<!DOCTYPE html><html><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>设备定位</title><style>
+body{margin:0;background:#000;color:#fff;display:flex;flex-direction:column;
+align-items:center;justify-content:center;height:100vh;font-family:monospace}
+.serial{font-size:min(9vw,72px);font-weight:700;color:#ffd700;word-break:break-all;padding:0 20px;text-align:center}
+.ip{font-size:min(5vw,36px);color:#7dd3fc;margin-top:24px;word-break:break-all;padding:0 20px;text-align:center}
+.hint{font-size:min(3vw,16px);color:#64748b;margin-top:40px}
+</style></head><body>
+<div class="serial">{{ serial }}</div>
+<div class="ip">{{ ip }}</div>
+<div class="hint">定位完成 · 按返回键退出</div>
+</body></html>""",
+        serial=_esc(serial), ip=_esc(serial.split(":")[0]))
+
+
+# 常见浏览器包名（结束定位时 force-stop 用）
+_BROWSER_PKGS = {"com.android.browser", "com.miui.browser", "com.android.chrome",
+                 "com.brave.browser", "com.opera.browser", "org.mozilla.firefox",
+                 "com.UCMobile", "com.tencent.mtt", "com.baidu.browser.apps"}
+# 定位时启动的浏览器：serial -> 包名（结束定位时无论前后台都关闭它）
+_locate_browsers = {}
+_locate_lock = threading.Lock()
+
+
+def _current_focus_pkg(serial):
+    """取设备当前前台包名（dumpsys window 解析，失败返回空串）。"""
+    try:
+        r = subprocess.run([ADB_PATH, "-s", serial, "shell", "dumpsys", "window"],
+                           capture_output=True, timeout=20)
+        out = (r.stdout or b"").decode("utf-8", errors="replace")
+        m = re.search(r"mCurrentFocus=.*?([\w.]+)/", out)
+        return m.group(1) if m else ""
+    except Exception:
+        return ""
+
+@bp.route("/api/device/locate/stop", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_device_locate_stop():
+    """结束定位：关闭定位启动的浏览器（无论当前是否前台）。
+
+    优先 force-stop 定位时记录下的浏览器包名（切到后台也能关掉）；
+    无记录时退回：前台是浏览器 → force-stop；否则按返回键（不误杀任务应用）。
+    """
+    serial = str((request.json or {}).get("serial", "")).strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少设备 serial"}), 400
+    try:
+        if ":" in serial:
+            adb_connect(serial)
+        # 1. 优先关闭定位时启动的浏览器（无论前后台）
+        with _locate_lock:
+            started = _locate_browsers.pop(serial, None)
+        if started:
+            subprocess.run([ADB_PATH, "-s", serial, "shell", "am", "force-stop", started],
+                           capture_output=True, timeout=20)
+            msg = f"已关闭定位浏览器 {started}"
+        else:
+            # 2. 退回：前台是浏览器则关闭，否则返回键轻量退出
+            pkg = _current_focus_pkg(serial)
+            if pkg in _BROWSER_PKGS:
+                subprocess.run([ADB_PATH, "-s", serial, "shell", "am", "force-stop", pkg],
+                               capture_output=True, timeout=20)
+                msg = f"已关闭浏览器 {pkg}"
+            else:
+                subprocess.run([ADB_PATH, "-s", serial, "shell", "input", "keyevent", "4"],
+                               capture_output=True, timeout=15)  # BACK 轻量退出
+                msg = "已按返回键退出" + (f"（前台 {pkg}）" if pkg else "")
+        _log.info(f"结束定位 {serial}: {msg}")
+        return jsonify({"ok": True, "msg": msg})
+    except Exception as e:
+        return jsonify({"ok": False, "error": f"结束定位失败: {e}"}), 502
+
+@bp.route("/api/device/screen_all", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_device_screen_all():
+    """批量亮屏/息屏（并发）。mode: on=亮屏解锁 / off=息屏。
+
+    请求可带 serials 指定设备（前端勾选）；不带则作用于全部在线设备。
+    息屏会中断运行中的任务（u2 无法操作），前端已有确认提示。
+    """
+    data = request.json or {}
+    mode = data.get("mode", "on")
+    try:
+        online = set(device_pool.list_online())
+    except Exception as e:
+        return jsonify({"ok": False, "error": f"获取设备列表失败: {e}"}), 502
+    serials = data.get("serials") or []
+    if serials:
+        # 指定设备：过滤掉不在线的（离线设备操作无意义，直接跳过）
+        serials = [s for s in serials if s in online]
+    else:
+        serials = list(online)
+    if not serials:
+        return jsonify({"ok": False, "error": "无在线设备"}), 400
+
+    def _do(serial):
+        try:
+            if ":" in serial:
+                adb_connect(serial)
+            if mode == "off":
+                subprocess.run([ADB_PATH, "-s", serial, "shell", "input", "keyevent", "26"],
+                               capture_output=True, timeout=15)  # KEYCODE_POWER 息屏
+            else:
+                subprocess.run([ADB_PATH, "-s", serial, "shell", "input", "keyevent", "224"],
+                               capture_output=True, timeout=15)  # WAKEUP
+                subprocess.run([ADB_PATH, "-s", serial, "shell", "wm", "dismiss-keyguard"],
+                               capture_output=True, timeout=15)
+            return True
+        except Exception:
+            return False
+
+    with ThreadPoolExecutor(max_workers=min(10, len(serials))) as pool:
+        results = list(pool.map(_do, serials))
+    ok_n = sum(1 for x in results if x)
+    _log.info(f"批量{'息屏' if mode == 'off' else '亮屏'}: 成功 {ok_n}/{len(serials)}")
+    return jsonify({"ok": True, "success": ok_n, "total": len(serials)})
+
+@bp.route("/api/device/locate", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_device_locate():
+    """定位设备：点亮屏幕并解除锁屏，可选打开大字定位页（查找设备用）。
+
+    请求 {"serial": "...", "show": true}：show=true 时额外用浏览器打开
+    平台 /locate 定位页，全屏大字显示设备 IP（更醒目，但会切换前台，
+    任务运行中慎用）。点亮组合：WAKEUP → dismiss-keyguard → MENU 兜底。
+    绝不 disconnect，红线。
+    """
+    data = request.json or {}
+    serial = str(data.get("serial", "")).strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少设备 serial"}), 400
+    try:
+        if ":" in serial:
+            adb_connect(serial)
+        for cmd in (["shell", "input", "keyevent", "224"],
+                    ["shell", "wm", "dismiss-keyguard"],
+                    ["shell", "input", "keyevent", "82"]):
+            try:
+                subprocess.run([ADB_PATH, "-s", serial, *cmd],
+                               capture_output=True, timeout=15)
+            except Exception:
+                pass  # 单步失败不阻塞，继续下一步
+        msgs = ["屏幕已点亮"]
+        if data.get("show"):
+            # 用设备浏览器打开定位页（设备走 tailnet 访问本机 100.100.10.2:18050）
+            locate_url = f"http://100.100.10.2:18050/locate?serial={urllib.parse.quote(serial)}"
+            r = subprocess.run([ADB_PATH, "-s", serial, "shell", "am", "start",
+                                "-a", "android.intent.action.VIEW", "-d", locate_url],
+                               capture_output=True, timeout=20)
+            out = ((r.stdout or b"") + (r.stderr or b"")).decode("utf-8", errors="replace")
+            if "error" in out.lower() or "exception" in out.lower():
+                msgs.append(f"打开定位页失败: {out.strip()[:80]}")
+            else:
+                msgs.append("已打开大字定位页（按返回键退出）")
+                # 记录启动的浏览器包名：结束定位时无论前后台都关闭它。
+                # 优先从 am start 输出解析 pkg=（浏览器可能尚未到前台，前台检测会扑空）
+                pkg = ""
+                m2 = re.search(r"pkg=([\w.]+)", out)
+                if m2 and m2.group(1) in _BROWSER_PKGS:
+                    pkg = m2.group(1)
+                else:
+                    time.sleep(1.5)  # 等浏览器切到前台再查
+                    pkg = _current_focus_pkg(serial)
+                if pkg in _BROWSER_PKGS:
+                    with _locate_lock:
+                        _locate_browsers[serial] = pkg
+        _log.info(f"定位设备 {serial}: {'; '.join(msgs)}")
+        return jsonify({"ok": True, "msg": f"{serial} {'；'.join(msgs)}"})
+    except Exception as e:
+        return jsonify({"ok": False, "error": f"定位失败: {e}"}), 502
+
+@bp.route("/api/stop_all", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_stop_all():
+    stopped = context.mgr.stop_all()
+    return jsonify({"ok": True, "stopped": stopped})
+
+@bp.route("/api/device/clear_error", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_device_clear_error():
+    """清除单台设备的异常状态（error/failed → idle），供设备列表"清除异常"按钮使用。"""
+    serial = (request.json or {}).get("serial", "")
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    if serial in context.mgr.get_running():
+        return jsonify({"ok": False, "error": "设备正在运行或等待重试，无法清除"}), 400
+    if not clear_worker_error(serial):
+        return jsonify({"ok": False, "error": "设备正在运行任务，无法清除"}), 400
+    _log.info(f"清除设备 {serial} 的异常状态")
+    return jsonify({"ok": True, "msg": f"已清除 {serial} 的异常状态"})
+
+@bp.route("/api/device/clear_all_errors", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_device_clear_all_errors():
+    """一键清除所有异常/失败设备（跳过正在运行/等待重试的）。"""
+    running = set(context.mgr.get_running())
+    cleared = clear_all_worker_errors(exclude=running)
+    _log.info(f"一键清除异常：共清除 {cleared} 台")
+    return jsonify({"ok": True, "cleared": cleared,
+                    "msg": f"已清除 {cleared} 台设备的异常状态"})
+
+@bp.route("/api/device/screenshot")
+@login_required
+def api_device_screenshot():
+    """获取设备当前画面截图（PNG）。
+
+    用 adb exec-out screencap -p，只读操作，不抢占 u2 的 atx-agent 通道，
+    任务运行中调用安全。直接返回 image/png，前端用 <img> 加载。
+    ?serial=xxx  设备 serial
+    ?t=123       时间戳，避免浏览器缓存（前端自动加）
+    """
+    serial = request.args.get("serial", "")
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    ok, data = screenshot(serial)
+    if ok:
+        return Response(data, mimetype="image/png",
+                        headers={"Cache-Control": "no-store"})
+    return jsonify({"ok": False, "error": data}), 500
+
+@bp.route("/api/devices/<serial>/apps")
+@login_required
+def api_device_apps(serial):
+    """获取指定设备上已安装的应用列表（包名 + versionCode + versionName + 路径）。"""
+    ok, data = list_installed_apps(serial)
+    if ok:
+        return jsonify({"ok": True, "apps": data})
+    return jsonify({"ok": False, "error": data}), 500
+
+
+# ================== 自定义动作（步骤打包） ==================
+
+@bp.route("/api/screen/stream")
+@perm_required(PERM_DEVICES)
+def api_screen_stream():
+    """远程看屏：MJPEG 实时画面流（multipart/x-mixed-replace）。
+
+    ?serial=xxx  设备 serial
+    浏览器 <img> 直接渲染；客户端断开（GeneratorExit）自动停止，不占资源。
+    设备离线/atx-agent 无响应时流自然结束，前端提示重新连接。
+    """
+    serial = request.args.get("serial", "")
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+
+    # 参数：q=JPEG 质量（大屏弹窗用 85 更清晰）；fps=目标帧率（0=默认节流）
+    try:
+        quality = max(30, min(95, int(request.args.get("q", _SCREEN_JPEG_QUALITY))))
+        fps = float(request.args.get("fps", 0) or 0)
+    except ValueError:
+        quality, fps = _SCREEN_JPEG_QUALITY, 0
+    gap = (1.0 / fps) if fps > 0 else _SCREEN_FRAME_GAP
+
+    def generate():
+        import io
+        import uiautomator2 as u2
+        try:
+            d = u2.connect(serial)
+        except Exception as e:
+            _log.warning(f"远程看屏 {serial} u2 连接失败: {e}")
+            return
+        while True:
+            try:
+                img = d.screenshot()
+                if img is None:
+                    break
+                if img.mode != "RGB":
+                    img = img.convert("RGB")
+                buf = io.BytesIO()
+                img.save(buf, "JPEG", quality=quality)
+                yield (b"--frame\r\nContent-Type: image/jpeg\r\n\r\n"
+                       + buf.getvalue() + b"\r\n")
+            except GeneratorExit:
+                break
+            except Exception as e:
+                _log.debug(f"远程看屏 {serial} 流中断: {e}")
+                break
+            time.sleep(gap)
+
+    return Response(generate(),
+                    mimetype="multipart/x-mixed-replace; boundary=frame")
+
+
+_screen_u2_cache = {}  # serial -> (ts, device)：大屏高频触控复用连接（60s TTL）
+
+
+def _screen_get_device(serial):
+    """远程看屏用的 u2 连接（60s 缓存复用，避免每次 tap/swipe 都重建连接）。
+
+    大屏高频操作（点击/滑动/按键）每次 u2.connect 有 1-3s 握手开销（atx-agent
+    探测），体验卡顿。缓存 60s 内复用；连接失败（设备离线/重启）时清缓存重建，
+    由调用方把异常转 503。
+    """
+    import time
+    import uiautomator2 as u2
+    now = time.time()
+    cached = _screen_u2_cache.get(serial)
+    if cached and now - cached[0] < 60:
+        return cached[1]
+    d = u2.connect(serial)
+    _screen_u2_cache[serial] = (now, d)
+    if len(_screen_u2_cache) > 30:  # 惰性清理过期项
+        for k in list(_screen_u2_cache):
+            if now - _screen_u2_cache[k][0] >= 60:
+                del _screen_u2_cache[k]
+    return d
+
+
+def _screen_invalidate(serial):
+    """u2 调用失败时清掉缓存（设备离线/atx-agent 重启），下次请求重新连接。"""
+    _screen_u2_cache.pop(serial, None)
+
+@bp.route("/api/screen/thumb")
+@perm_required(PERM_DEVICES)
+def api_screen_thumb():
+    """大屏缩略图：单张 JPEG（360px 宽，质量 55），供监控大屏轮询。
+
+    一次性请求（非流），与任务并发安全（与任务截图同走 u2 minicap）。
+    大屏按需轮询：每设备约 2.5s 一帧，20 台 ≈ 0.2 核 CPU + 100KB/s。
+    响应头 X-Screen-State: on/off/unknown —— 大屏据此显示「亮屏中/熄屏中」。
+    """
+    serial = request.args.get("serial", "")
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    import io
+    import uiautomator2 as u2
+    try:
+        d = u2.connect(serial)
+        img = d.screenshot()
+        if img is None:
+            return jsonify({"ok": False, "error": "截图失败"}), 503
+        if img.width > 360:
+            ratio = 360 / img.width
+            img = img.resize((360, int(img.height * ratio)))
+        buf = io.BytesIO()
+        img.convert("RGB").save(buf, "JPEG", quality=55)
+        return Response(buf.getvalue(), mimetype="image/jpeg",
+                        headers={"Cache-Control": "no-store",
+                                 "X-Screen-State": _device_screen_state(serial)})
+    except Exception as e:
+        return jsonify({"ok": False, "error": str(e)}), 503
+
+
+@bp.route("/api/screen/tap", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_screen_tap():
+    """点击：{serial, x, y}（设备原生分辨率坐标）。"""
+    data = request.json or {}
+    serial, x, y = data.get("serial", ""), data.get("x"), data.get("y")
+    if not serial or x is None or y is None:
+        return jsonify({"ok": False, "error": "缺少 serial/x/y"}), 400
+    try:
+        _screen_get_device(serial).click(int(x), int(y))
+        return jsonify({"ok": True})
+    except Exception as e:
+        _screen_invalidate(serial)
+        return jsonify({"ok": False, "error": f"点击失败: {e}"}), 503
+
+@bp.route("/api/screen/swipe", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_screen_swipe():
+    """滑动：{serial, x1, y1, x2, y2, duration?}（设备原生分辨率坐标）。"""
+    data = request.json or {}
+    serial = data.get("serial", "")
+    x1, y1, x2, y2 = (data.get(k) for k in ("x1", "y1", "x2", "y2"))
+    if not serial or None in (x1, y1, x2, y2):
+        return jsonify({"ok": False, "error": "缺少 serial/x1/y1/x2/y2"}), 400
+    try:
+        _screen_get_device(serial).swipe(int(x1), int(y1), int(x2), int(y2),
+                                         duration=float(data.get("duration", 0.2)))
+        return jsonify({"ok": True})
+    except Exception as e:
+        _screen_invalidate(serial)
+        return jsonify({"ok": False, "error": f"滑动失败: {e}"}), 503
+
+
+_SCREEN_KEYS = {"back", "home", "recent", "menu", "power", "volume_up",
+                "volume_down", "enter", "delete", "search", "camera"}
+
+@bp.route("/api/screen/key", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_screen_key():
+    """按键：{serial, key}（back/home/recent/menu/power 等，见 _SCREEN_KEYS）。"""
+    data = request.json or {}
+    serial, key = data.get("serial", ""), (data.get("key") or "").strip().lower()
+    if not serial or key not in _SCREEN_KEYS:
+        return jsonify({"ok": False, "error": "缺少 serial 或不支持的按键"}), 400
+    try:
+        _screen_get_device(serial).press(key)
+        return jsonify({"ok": True})
+    except Exception as e:
+        _screen_invalidate(serial)
+        return jsonify({"ok": False, "error": f"按键失败: {e}"}), 503
+
+@bp.route("/api/screen/text", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_screen_text():
+    """输入文字：{serial, text}（需焦点在输入框，u2 send_keys）。"""
+    data = request.json or {}
+    serial, text = data.get("serial", ""), (data.get("text") or "").strip()
+    if not serial or not text:
+        return jsonify({"ok": False, "error": "缺少 serial/text"}), 400
+    try:
+        _screen_get_device(serial).send_keys(text)
+        return jsonify({"ok": True})
+    except Exception as e:
+        return jsonify({"ok": False, "error": f"输入失败: {e}"}), 503
+
+
+# ================== API：应用管理（APK 上传/安装）==================
+
+def _current_focus_pkg(serial):
+    """取设备当前前台包名（dumpsys window 解析，失败返回空串）。"""
+    try:
+        r = subprocess.run([ADB_PATH, "-s", serial, "shell", "dumpsys", "window"],
+                           capture_output=True, timeout=20)
+        out = (r.stdout or b"").decode("utf-8", errors="replace")
+        m = re.search(r"mCurrentFocus=.*?([\w.]+)/", out)
+        return m.group(1) if m else ""
+    except Exception:
+        return ""
+
+_screen_u2_cache = {}  # serial -> (ts, device)：大屏高频触控复用连接（60s TTL）
+
+
+def _screen_get_device(serial):
+    """远程看屏用的 u2 连接（60s 缓存复用，避免每次 tap/swipe 都重建连接）。
+
+    大屏高频操作（点击/滑动/按键）每次 u2.connect 有 1-3s 握手开销（atx-agent
+    探测），体验卡顿。缓存 60s 内复用；连接失败（设备离线/重启）时清缓存重建，
+    由调用方把异常转 503。
+    """
+    import time
+    import uiautomator2 as u2
+    now = time.time()
+    cached = _screen_u2_cache.get(serial)
+    if cached and now - cached[0] < 60:
+        return cached[1]
+    d = u2.connect(serial)
+    _screen_u2_cache[serial] = (now, d)
+    if len(_screen_u2_cache) > 30:  # 惰性清理过期项
+        for k in list(_screen_u2_cache):
+            if now - _screen_u2_cache[k][0] >= 60:
+                del _screen_u2_cache[k]
+    return d
+
+
+def _screen_invalidate(serial):
+    """u2 调用失败时清掉缓存（设备离线/atx-agent 重启），下次请求重新连接。"""
+    _screen_u2_cache.pop(serial, None)
+

web/tailscale_api.py

@@ -0,0 +1,98 @@
+"""Tailscale 管理 API（仅管理员）。"""
+import re
+
+from flask import Blueprint, jsonify, request
+
+from core import tailscale_client
+from core.tailscale_client import TailscaleError
+from core.logger import get_logger
+
+_log = get_logger("web")
+from web.auth import admin_required
+
+bp = Blueprint("tailscale", __name__)
+
+@bp.route("/api/tailscale/status")
+@admin_required
+def api_tailscale_status():
+    """Tailscale 管理配置状态（API key / tailnet 是否已配置）。"""
+    c = tailscale_client.tailscale
+    return jsonify({"ok": True, "configured": c.is_configured(),
+                    "hint": c.config_hint() if not c.is_configured() else ""})
+
+@bp.route("/api/tailscale/devices")
+@admin_required
+def api_tailscale_devices():
+    """列出 tailnet 全部设备。"""
+    try:
+        return jsonify({"ok": True, "devices": tailscale_client.tailscale.list_devices()})
+    except TailscaleError as e:
+        return jsonify({"ok": False, "error": str(e)}), 502
+
+@bp.route("/api/tailscale/devices/<device_id>", methods=["POST"])
+@admin_required
+def api_tailscale_device_update(device_id):
+    """更新设备：按传入字段分发到专属端点（改名 /name、授权 /authorized、密钥 /key）。"""
+    data = request.json or {}
+    c = tailscale_client.tailscale
+    try:
+        if "name" in data:
+            c.set_device_name(device_id, data.get("name"))
+        if "authorized" in data:
+            c.set_device_authorized(device_id, data.get("authorized"))
+        if "key_expiry_disabled" in data:
+            c.set_device_key_expiry(device_id, data.get("key_expiry_disabled"))
+        _log.info(f"Tailscale 设备更新 {device_id}: {data}")
+        return jsonify({"ok": True, "msg": "设备已更新"})
+    except TailscaleError as e:
+        return jsonify({"ok": False, "error": str(e)}), 502
+
+@bp.route("/api/tailscale/devices/<device_id>/ip", methods=["POST"])
+@admin_required
+def api_tailscale_device_ip(device_id):
+    """设置设备 IPv4 地址（未公开端点，实测可用）。
+
+    ⚠ 改 IP 会断开设备当前 tailscale 会话，且平台设备池 serial 随之变化，
+    改完需同步更新 STF 设备池（分组/任务目标里的旧 IP 会失效）。
+    """
+    data = request.json or {}
+    ipv4 = (data.get("ipv4") or "").strip()
+    if not ipv4:
+        return jsonify({"ok": False, "error": "缺少 ipv4"}), 400
+    try:
+        tailscale_client.tailscale.set_device_ip(device_id, ipv4)
+        _log.info(f"Tailscale 设备 {device_id} IP 已设置为 {ipv4}")
+        return jsonify({"ok": True, "msg": f"设备 IP 已设置为 {ipv4}"})
+    except TailscaleError as e:
+        return jsonify({"ok": False, "error": str(e)}), 502
+
+@bp.route("/api/tailscale/devices/<device_id>", methods=["DELETE"])
+@admin_required
+def api_tailscale_device_delete(device_id):
+    """从 tailnet 移除设备。"""
+    try:
+        tailscale_client.tailscale.delete_device(device_id)
+        _log.info(f"Tailscale 设备已移除: {device_id}")
+        return jsonify({"ok": True, "msg": "设备已从 tailnet 移除"})
+    except TailscaleError as e:
+        return jsonify({"ok": False, "error": str(e)}), 502
+
+@bp.route("/api/tailscale/authkey", methods=["POST"])
+@admin_required
+def api_tailscale_authkey():
+    """生成设备接入 auth key（key 只显示一次）。"""
+    data = request.json or {}
+    try:
+        # Tailscale 要求 description 仅 ASCII（中文会 400）
+        desc = re.sub(r"[^\x20-\x7e]", "", (data.get("description") or "").strip())
+        key = tailscale_client.tailscale.create_auth_key(
+            description=desc or "auto_control",
+            reusable=bool(data.get("reusable", False)),
+            ephemeral=bool(data.get("ephemeral", False)),
+            preauthorized=data.get("preauthorized", True),
+            expiry_seconds=int(data.get("expiry_seconds", 3600)))
+        _log.info(f"Tailscale auth key 已生成: {key['id']}")
+        return jsonify({"ok": True, "key": key["key"], "id": key["id"],
+                        "expires": key["expires"]})
+    except TailscaleError as e:
+        return jsonify({"ok": False, "error": str(e)}), 502

web/tasks_api.py

@@ -0,0 +1,339 @@
+"""任务域 API：任务计划/分组/自定义动作/元素抓取/步骤测试。"""
+import re
+import time
+import uuid
+import threading
+from datetime import datetime
+from concurrent.futures import ThreadPoolExecutor, as_completed, TimeoutError as FuturesTimeout
+
+from flask import (Blueprint, jsonify, request, Response)
+from flask_login import login_required
+
+from core import device_pool, uiauto_helper
+from core.adb_helper import adb_connect_light
+from core.models import db, DeviceGroup, TaskJob, CustomAction
+from core.logger import get_logger
+
+_log = get_logger("web")
+from web import context
+from web.auth import perm_required, PERM_DEVICES, PERM_TASKS
+from tasks import list_task_types, get_task_class
+from web.common import _merged_device_list
+
+bp = Blueprint("tasks", __name__)
+
+@bp.route("/api/task_types")
+@login_required
+def api_task_types():
+    return jsonify({"ok": True, "task_types": list_task_types()})
+
+@bp.route("/api/actions")
+@login_required
+def api_actions():
+    """返回指定任务类型支持的专属操作。"""
+    task_type = request.args.get("task_type", "")
+    task_cls = get_task_class(task_type)
+    if not task_cls:
+        return jsonify({"ok": False, "error": "未知任务类型", "actions": []})
+    actions = task_cls.list_action_types()
+    return jsonify({"ok": True, "actions": actions})
+
+@bp.route("/api/devices")
+@login_required
+def api_devices():
+    """返回所有在线设备 serial（供分组表单勾选用）。"""
+    try:
+        return jsonify({"ok": True, "devices": context.mgr.list_all_serials()})
+    except Exception as e:
+        return jsonify({"ok": False, "error": str(e)}), 500
+
+
+# ================== API：任务计划 CRUD ==================
+def _job_next_run(job):
+    """任务下次执行时间，格式化为 "YYYY-MM-DD HH:MM"（Flask 序列化 aware datetime 会变 GMT 格式）。"""
+    nr = context.mgr.next_run_of(job)
+    return nr.strftime("%Y-%m-%d %H:%M") if nr else None
+
+@bp.route("/api/jobs")
+@login_required
+def api_jobs_list():
+    jobs = []
+    for j in context.mgr.jobs.values():
+        d = j.to_dict()
+        d["next_run"] = _job_next_run(j)
+        jobs.append(d)
+    return jsonify({"ok": True, "jobs": jobs,
+                    "task_types": list_task_types()})
+
+@bp.route("/api/jobs", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_jobs_create():
+    data = request.json or {}
+    name = (data.get("name") or "").strip()
+    if not name:
+        return jsonify({"ok": False, "error": "任务名不能为空"}), 400
+    task_type = data.get("task_type", "douyin_nurture")
+    if not get_task_class(task_type):
+        return jsonify({"ok": False, "error": f"未知任务类型: {task_type}"}), 400
+    job = context.mgr.add_job(
+        name=name, task_type=task_type,
+        target=data.get("target", {"mode": "all"}),
+        params=data.get("params", {}),
+        schedule=data.get("schedule", {"mode": "once"}),
+        retry=data.get("retry", {"max_attempts": 1, "delay": 60}),
+        enabled=data.get("enabled", True))
+    d = job.to_dict()
+    d["next_run"] = _job_next_run(job)
+    return jsonify({"ok": True, "msg": "任务已创建", "job": d})
+
+@bp.route("/api/jobs/<job_id>", methods=["PUT"])
+@perm_required(PERM_TASKS)
+def api_jobs_update(job_id):
+    job = context.mgr.jobs.get(job_id)
+    if not job:
+        return jsonify({"ok": False, "error": "任务不存在"}), 404
+    data = request.json or {}
+    fields = {}
+    for k in ("name", "task_type", "target", "params", "schedule", "retry", "enabled"):
+        if k in data:
+            fields[k] = data[k]
+    if "task_type" in fields and not get_task_class(fields["task_type"]):
+        return jsonify({"ok": False, "error": f"未知任务类型: {fields['task_type']}"}), 400
+    context.mgr.update_job(job_id, **fields)
+    d = job.to_dict()
+    d["next_run"] = _job_next_run(job)
+    return jsonify({"ok": True, "msg": "任务已更新", "job": d})
+
+@bp.route("/api/jobs/<job_id>", methods=["DELETE"])
+@perm_required(PERM_TASKS)
+def api_jobs_delete(job_id):
+    if context.mgr.delete_job(job_id):
+        return jsonify({"ok": True, "msg": "任务已删除"})
+    return jsonify({"ok": False, "error": "任务不存在"}), 404
+
+@bp.route("/api/jobs/<job_id>/run", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_jobs_run(job_id):
+    return jsonify(context.mgr.run_job_now(job_id))
+
+@bp.route("/api/jobs/<job_id>/toggle", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_jobs_toggle(job_id):
+    enabled = (request.json or {}).get("enabled", True)
+    job = context.mgr.toggle_job(job_id, enabled)
+    if not job:
+        return jsonify({"ok": False, "error": "任务不存在"}), 404
+    return jsonify({"ok": True, "msg": f"任务已{'启用' if enabled else '停用'}"})
+
+
+# ================== API：设备分组 CRUD ==================
+
+@bp.route("/api/groups")
+@login_required
+def api_groups_list():
+    return jsonify({"ok": True, "groups": [g.to_dict() for g in context.mgr.groups.values()]})
+
+@bp.route("/api/groups", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_groups_create():
+    data = request.json or {}
+    name = (data.get("name") or "").strip()
+    if not name:
+        return jsonify({"ok": False, "error": "分组名不能为空"}), 400
+    if name in context.mgr.groups:
+        return jsonify({"ok": False, "error": "分组名已存在"}), 400
+    context.mgr.add_group(name, data.get("serials", []), data.get("description", ""))
+    return jsonify({"ok": True, "msg": "分组已创建"})
+
+@bp.route("/api/groups/<name>", methods=["PUT"])
+@perm_required(PERM_TASKS)
+def api_groups_update(name):
+    if name not in context.mgr.groups:
+        return jsonify({"ok": False, "error": "分组不存在"}), 404
+    data = request.json or {}
+    context.mgr.update_group(name,
+                     serials=data.get("serials"),
+                     description=data.get("description"))
+    return jsonify({"ok": True, "msg": "分组已更新"})
+
+@bp.route("/api/groups/<name>", methods=["DELETE"])
+@perm_required(PERM_TASKS)
+def api_groups_delete(name):
+    if context.mgr.delete_group(name):
+        return jsonify({"ok": True, "msg": "分组已删除"})
+    return jsonify({"ok": False, "error": "分组不存在"}), 404
+
+
+# ================== API：用户管理 CRUD ==================
+
+@bp.route("/api/custom_actions")
+@login_required
+def api_custom_actions_list():
+    rows = CustomAction.query.order_by(CustomAction.created_at.desc()).all()
+    return jsonify({"ok": True, "actions": [r.to_dict() for r in rows]})
+
+@bp.route("/api/custom_actions", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_custom_actions_create():
+    data = request.json or {}
+    name = (data.get("name") or "").strip()
+    if not name:
+        return jsonify({"ok": False, "error": "动作名不能为空"}), 400
+    steps = data.get("steps", [])
+    if not steps:
+        return jsonify({"ok": False, "error": "至少需要1个步骤"}), 400
+    row = CustomAction(id=uuid.uuid4().hex[:8], name=name,
+                       icon=data.get("icon") or "📦",
+                       created_at=datetime.now().strftime("%Y-%m-%d %H:%M"))
+    row.set_steps(steps)
+    db.session.add(row)
+    db.session.commit()
+    return jsonify({"ok": True, "msg": "动作已保存", "action": row.to_dict()})
+
+@bp.route("/api/custom_actions/<action_id>", methods=["PUT"])
+@perm_required(PERM_TASKS)
+def api_custom_actions_update(action_id):
+    row = CustomAction.query.get(action_id)
+    if not row:
+        return jsonify({"ok": False, "error": "动作不存在"}), 404
+    data = request.json or {}
+    if "name" in data:
+        name = (data["name"] or "").strip()
+        if not name:
+            return jsonify({"ok": False, "error": "动作名不能为空"}), 400
+        row.name = name
+    if "icon" in data:
+        row.icon = data["icon"] or "📦"
+    if "steps" in data:
+        if not data["steps"]:
+            return jsonify({"ok": False, "error": "至少需要1个步骤"}), 400
+        row.set_steps(data["steps"])
+    db.session.commit()
+    return jsonify({"ok": True, "msg": "已更新", "action": row.to_dict()})
+
+@bp.route("/api/custom_actions/<action_id>", methods=["DELETE"])
+@perm_required(PERM_TASKS)
+def api_custom_actions_delete(action_id):
+    row = CustomAction.query.get(action_id)
+    if not row:
+        return jsonify({"ok": False, "error": "动作不存在"}), 404
+    db.session.delete(row)
+    db.session.commit()
+    return jsonify({"ok": True, "msg": "已删除"})
+
+@bp.route("/api/uiauto/elements")
+@perm_required(PERM_DEVICES)
+def api_uiauto_elements():
+    """获取设备当前 UI 元素树（供步骤编辑器"抓取元素"用）。
+
+    依赖本地运行的 uiautodev 服务（端口 20242）。
+    ?serial=xxx  设备 serial
+    返回：
+      200 — {ok:true, elements:[...]}
+      503 — {ok:false, error:"..."}（uiauto2 未启动）
+    """
+    serial = request.args.get("serial", "")
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    ok, data = uiauto_helper.get_elements(serial)
+    if ok:
+        return jsonify({"ok": True, "elements": data})
+    return jsonify({"ok": False, "error": data}), 503
+
+@bp.route("/api/uiauto/status")
+@login_required
+def api_uiauto_status():
+    """探测 uiauto2 本地服务是否运行（前端按钮禁启用）。"""
+    return jsonify({"ok": True, "running": uiauto_helper.is_running()})
+
+@bp.route("/api/steps/test", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_steps_test():
+    """测试单个步骤：在指定设备上试执行，验证选择器是否命中（步骤编辑器"测试此步骤"）。
+
+    请求: {"serial": "100.100.10.11:5555", "step": {"type": "click", "params": {...}}}
+    只读连接（adb connect + u2），与运行中任务互不干扰。
+    返回 result: "命中" / "未找到" / "已执行"。
+    """
+    data = request.json or {}
+    serial = (data.get("serial") or "").strip()
+    step = data.get("step") or {}
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    if not step.get("type"):
+        return jsonify({"ok": False, "error": "缺少步骤类型"}), 400
+    from tasks.generic.task import test_step
+    ok, msg, result = test_step(serial, step)
+    res_txt = {True: "命中", False: "未找到"}.get(result, "已执行")
+    _log.info(f"测试步骤 {step.get('type')} @ {serial}: {res_txt} ({msg})")
+    return jsonify({"ok": ok, "msg": msg, "result": res_txt})
+
+@bp.route("/api/uiauto/devices")
+@perm_required(PERM_DEVICES)
+def api_uiauto_devices():
+    """获取可选设备列表（抓取元素用）。
+
+    uiautodev 只认识本地 adb 已连接的设备；设备池里在线但未本地连接的设备
+    在这里补全，并先做一次轻量 adb connect（单次尝试，绝不 kill-server），
+    让它们可被 uiautodev 抓取。
+    """
+    ok, data = uiauto_helper.list_devices()
+    if not ok:
+        return jsonify({"ok": False, "error": data}), 503
+    seen = {d.get("serial") for d in data}
+    try:
+        online = set(device_pool.list_online())
+        pool = [s for s in device_pool.list_configured() if s in online]
+    except Exception:
+        pool = []
+    added = 0
+    for serial in pool:
+        if not serial or serial in seen:
+            continue
+        # 轻量连接（单次尝试，不重试不 kill-server）；连不上也照样列出，
+        # 前端抓取时会报明确错误，不影响其他设备的连接
+        adb_connect_light(serial)
+        data.append({
+            "serial": serial,
+            "model": "",
+            "product": "",
+            "name": serial,
+            "status": "device",
+            "enabled": True,
+        })
+        seen.add(serial)
+        added += 1
+    if added:
+        _log.info(f"抓取元素设备列表补全 {added} 台在线设备: {list(seen)}")
+    return jsonify({"ok": True, "devices": data})
+
+@bp.route("/api/uiauto/screenshot")
+@perm_required(PERM_DEVICES)
+def api_uiauto_screenshot():
+    """通过 uiauto2 获取设备截图（供抓取元素时显示设备画面）。
+
+    ?serial=xxx  设备 serial
+    直接返回 image/jpeg，前端用 <img> 加载。
+    """
+    serial = request.args.get("serial", "")
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    ok, data = uiauto_helper.get_screenshot(serial)
+    if ok:
+        return Response(data, mimetype="image/jpeg",
+                        headers={"Cache-Control": "no-store"})
+    return jsonify({"ok": False, "error": data}), 503
+
+
+# ================== API：远程看屏（阶段 2） ==================
+# MJPEG 实时画面流 + u2 触控注入。数据源 u2（atx-agent minicap 截图，单帧 ~200ms），
+# 零新依赖（原计划 ws-scrcpy 不在 npm 分发，GitHub 下载在国内不可靠，改自建）。
+# 坐标约定：前端以 <img> 显示尺寸归一化后映射到设备原生分辨率（naturalWidth/Height）。
+_SCREEN_JPEG_QUALITY = 65
+_SCREEN_FRAME_GAP = 0.05  # 帧间最小间隔（秒），防止空转烧 CPU
+
+def _job_next_run(job):
+    """任务下次执行时间，格式化为 "YYYY-MM-DD HH:MM"（Flask 序列化 aware datetime 会变 GMT 格式）。"""
+    nr = context.mgr.next_run_of(job)
+    return nr.strftime("%Y-%m-%d %H:%M") if nr else None
+

web/tools_api.py

@@ -0,0 +1,249 @@
+"""工具域 API：adb 终端/剪贴板注入/应用版本。"""
+import re
+import subprocess
+import shlex
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from flask import Blueprint, jsonify, request
+
+from core import device_pool
+from core.adb_helper import adb_connect, adb_connect_light, _ADB_LOCK, _adb
+from config import ADB_PATH
+from core.logger import get_logger
+from web import context
+from web.auth import admin_required, perm_required
+from web.common import _merged_device_list
+
+_log = get_logger("web")
+bp = Blueprint("tools", __name__)
+
+# adb 终端安全红线：绝不 kill-server / 绝不 disconnect IP:5555——
+# 共享 adb transport，断开会让全部设备连接重建（历史与 STF provider 共用）。
+_ADB_BLOCKED_PATTERNS = ("kill-server", "disconnect")
+
+@bp.route("/api/adb/devices")
+@admin_required
+def api_adb_devices():
+    """维护终端设备列表（仅管理员）：本地 adb 已连接 + 设备池（SQLite）。
+
+    状态：device/offline=本机 adb 实际状态；pool=设备池已配置但本机未连接。
+    供终端设备选择器使用——选中后自动附加 `-s <serial>`，
+    离线/未连接的设备也可选，配合"重连设备"按钮恢复。
+    """
+    return jsonify({"ok": True, "devices": _merged_device_list()})
+
+@bp.route("/api/adb/cmd", methods=["POST"])
+@admin_required
+def api_adb_cmd():
+    """维护终端：执行 adb 命令（仅管理员）。
+
+    请求: {"cmd": "adb -s 100.100.10.11:5555 shell ls /sdcard"}
+    用平台 adb 二进制执行（config.ADB_PATH），带 20s 超时。
+    """
+    data = request.json or {}
+    cmd = (data.get("cmd") or "").strip()
+    if not cmd:
+        return jsonify({"ok": False, "error": "命令不能为空"}), 400
+    if _blocked_adb_cmd(cmd):
+        return jsonify({"ok": False,
+                        "error": "禁止执行 kill-server / disconnect（会中断 STF 设备监控，影响所有任务）"}), 400
+    tokens = shlex.split(cmd)
+    if tokens and tokens[0] == "adb":
+        tokens = tokens[1:]
+    if not tokens:
+        return jsonify({"ok": False, "error": "命令不能为空"}), 400
+    try:
+        # 与 worker 的 adb 调用共用锁，避免并发操作同一 adb server
+        with _ADB_LOCK:
+            r = subprocess.run([ADB_PATH, *tokens], capture_output=True, timeout=20)
+        out = (r.stdout or b"").decode("utf-8", errors="replace")
+        err = (r.stderr or b"").decode("utf-8", errors="replace")
+        _log.info(f"维护终端执行 adb {' '.join(tokens)} -> exit {r.returncode}")
+        return jsonify({"ok": True, "stdout": out, "stderr": err, "code": r.returncode})
+    except subprocess.TimeoutExpired:
+        return jsonify({"ok": False, "error": "命令执行超时（20s）"}), 408
+    except Exception as e:
+        _log.warning(f"维护终端 adb 执行异常: {e}")
+        return jsonify({"ok": False, "error": f"执行失败: {e}"}), 500
+
+@bp.route("/api/tools/clipboard/set", methods=["POST"])
+@admin_required
+def api_tools_clipboard_set():
+    """工具-剪贴板注入：把指定文字写入一台或多台设备的剪贴板。
+
+    请求: {"serials": ["100.100.10.11:5555", ...], "text": "要注入的文字"}
+    设备来源与维护终端一致：本地 adb 已连接设备（含 USB）+ 设备池。
+    实现：u2 jsonrpc.setClipboard（实测 cmd clipboard 在 MIUI 上不存在）。
+    """
+    data = request.json or {}
+    serials = data.get("serials") or []
+    text = (data.get("text") or "").strip()
+    if not isinstance(serials, list) or not serials:
+        return jsonify({"ok": False, "error": "未选择设备"}), 400
+    if not text:
+        return jsonify({"ok": False, "error": "注入内容不能为空"}), 400
+    results = {}
+    for serial in serials:
+        ok, msg = _set_device_clipboard(serial, text)
+        results[serial] = {"ok": ok, "msg": msg}
+    ok_count = sum(1 for v in results.values() if v["ok"])
+    fail_count = len(results) - ok_count
+    return jsonify({"ok": True, "results": results,
+                    "ok_count": ok_count, "fail_count": fail_count,
+                    "error": None if ok_count == len(results) else f"{fail_count} 台设备注入失败"})
+
+
+def _set_device_clipboard(serial, text):
+    """向单台设备注入剪贴板文字（ClipInject 通道，见 core.clipboard_helper）。"""
+    from core.clipboard_helper import inject_clipboard
+    return inject_clipboard(serial, text)
+
+
+def _app_ver_on_device(serial, pkg):
+    """单设备包版本查询：pm path 检查安装 → dumpsys 取 versionName/versionCode。
+
+    IP:port 设备先轻量 adb connect（单次尝试，绝不 disconnect，红线）。
+    查询是只读 shell 命令，无需 adb server 锁（锁只保护 connect/kill-server 类操作）。
+    """
+    if ":" in serial:
+        try:
+            adb_connect_light(serial)
+        except Exception as e:
+            return {"installed": False, "error": f"adb 连接失败: {e}"}
+    try:
+        r = subprocess.run([ADB_PATH, "-s", serial, "shell", "pm", "path", pkg],
+                           capture_output=True, timeout=15)
+        if b"package:" not in (r.stdout or b""):
+            return {"installed": False, "version_name": "", "version_code": ""}
+        r2 = subprocess.run([ADB_PATH, "-s", serial, "shell", "dumpsys", "package", pkg],
+                            capture_output=True, timeout=20)
+        out2 = (r2.stdout or b"").decode("utf-8", errors="replace")
+        vm = re.search(r"versionName=(\S+)", out2)
+        vc = re.search(r"versionCode=(\d+)", out2)
+        return {"installed": True,
+                "version_name": vm.group(1) if vm else "",
+                "version_code": vc.group(1) if vc else ""}
+    except subprocess.TimeoutExpired:
+        return {"installed": False, "error": "查询超时"}
+    except Exception as e:
+        return {"installed": False, "error": str(e)}
+
+@bp.route("/api/tools/appver", methods=["POST"])
+@admin_required
+def api_tools_appver():
+    """工具-应用版本管理：查询所有设备上指定包名的安装情况与版本号。
+
+    请求: {"pkg": "com.ss.android.ugc.aweme"}
+    设备来源：本地 adb（含 USB）+ 设备池，并发查询（最多 10 台同时）。
+    """
+    pkg = (request.json or {}).get("pkg", "").strip()
+    if not re.match(r"^[A-Za-z0-9_.]+$", pkg or ""):
+        return jsonify({"ok": False, "error": "包名格式不正确（仅字母/数字/._）"}), 400
+    # 只查在线设备：池内离线条目（如陈旧记录）不连，避免 connect 重试拖慢查询
+    try:
+        online = set(device_pool.list_online())
+        devices = [d for d in _merged_device_list() if d["serial"] in online]
+    except Exception:
+        devices = []
+    if not devices:
+        return jsonify({"ok": False, "error": "无在线设备"}), 404
+    results = {}
+    with ThreadPoolExecutor(max_workers=min(10, len(devices))) as pool:
+        futures = {pool.submit(_app_ver_on_device, d["serial"], pkg): d for d in devices}
+        for fut in as_completed(futures, timeout=90):
+            d = futures[fut]
+            try:
+                results[d["serial"]] = fut.result()
+            except Exception as e:
+                results[d["serial"]] = {"installed": False, "error": str(e)}
+    fail = sum(1 for v in results.values() if v.get("error"))
+    return jsonify({"ok": True, "results": results, "fail": fail,
+                    "total": len(results)})
+
+def _blocked_adb_cmd(cmd):
+    """命中红线的 adb 命令（kill-server / disconnect）直接拒绝。"""
+    low = cmd.lower()
+    return any(p in low for p in _ADB_BLOCKED_PATTERNS)
+
+def _set_device_clipboard(serial, text):
+    """向单台设备注入剪贴板文字（ClipInject APK：透明 Activity 聚焦后写入）。
+
+    Android 10+ 禁止后台（atx-agent/shell）写剪贴板，u2.set_clipboard 在
+    Android 12/13 上调用"成功"但内容被系统静默丢弃。ClipInject
+    （com.example.clipinject）通过 am start 启动透明 Activity，窗口聚焦后
+    setPrimaryClip，shell 启动 Activity 不受后台启动限制（广播方式在 MIUI
+    会被 Background activity start 拦截，必须用 am start）。
+
+    - IP:port 设备：先 adb connect（已连接自动跳过；绝不 disconnect，红线）
+    - 设备未装 ClipInject：am start 返回 unable to resolve Intent，明确报错
+    - 注入后 u2 读回比对验证（后台读剪贴板实测可用），不一致也明确报错
+    """
+    import base64
+    import time
+    import uiautomator2 as u2
+    if ":" in serial:
+        try:
+            adb_connect(serial)
+        except Exception as e:
+            return False, f"adb 连接失败: {e}"
+    b64 = base64.b64encode(text.encode("utf-8")).decode()
+    # 1. am start 透明 Activity 写剪贴板（shell 身份启动，不受后台启动限制）
+    try:
+        r = subprocess.run(
+            [ADB_PATH, "-s", serial, "shell", "am", "start",
+             "-n", "com.example.clipinject/.ClipActivity",
+             "--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, ("设备未安装 ClipInject（com.example.clipinject），"
+                           f"请先安装: {out.strip()[:100]}")
+        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)
+    try:
+        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)
+        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]}）"
+
+def _app_ver_on_device(serial, pkg):
+    """单设备包版本查询：pm path 检查安装 → dumpsys 取 versionName/versionCode。
+
+    IP:port 设备先轻量 adb connect（单次尝试，绝不 disconnect，红线）。
+    查询是只读 shell 命令，无需 adb server 锁（锁只保护 connect/kill-server 类操作）。
+    """
+    if ":" in serial:
+        try:
+            adb_connect_light(serial)
+        except Exception as e:
+            return {"installed": False, "error": f"adb 连接失败: {e}"}
+    try:
+        r = subprocess.run([ADB_PATH, "-s", serial, "shell", "pm", "path", pkg],
+                           capture_output=True, timeout=15)
+        if b"package:" not in (r.stdout or b""):
+            return {"installed": False, "version_name": "", "version_code": ""}
+        r2 = subprocess.run([ADB_PATH, "-s", serial, "shell", "dumpsys", "package", pkg],
+                            capture_output=True, timeout=20)
+        out2 = (r2.stdout or b"").decode("utf-8", errors="replace")
+        vm = re.search(r"versionName=(\S+)", out2)
+        vc = re.search(r"versionCode=(\d+)", out2)
+        return {"installed": True,
+                "version_name": vm.group(1) if vm else "",
+                "version_code": vc.group(1) if vc else ""}
+    except subprocess.TimeoutExpired:
+        return {"installed": False, "error": "查询超时"}
+    except Exception as e:
+        return {"installed": False, "error": str(e)}
+

web_server.py

@@ -1,48 +1,61 @@
-"""设备自动化管理后台（Flask + Flask-Login，单页应用）。
+"""设备自动化管理后台入口：Flask app 装配 + 启动。
 
-启动：python web_server.py
+路由按功能域拆分到 web/ 蓝图包（auth/monitor/tasks/admin/tools/devices/apks/tailscale），
-访问：http://localhost:5000
+本文件只负责：app 创建、数据库初始化、共享对象装配、蓝图注册、uiautodev 生命周期、启动。
-
-页面结构：
-  /                — 单页应用（监控/任务/分组/日志/用户 Tab 切换，需登录）
-  /login /logout   — 用户登录/登出
-  /api/*           — JSON API
-
-用户系统：
-  首次启动自动创建默认管理员 admin/admin123（请及时改密码）。
-  用户数据存 data/users.db（SQLite）。
 """
 import os
 import time
+import atexit
+import secrets
+import socket
+import subprocess
+import sys
+import threading
 
-from flask import Flask, jsonify, request, redirect, url_for, render_template, Response, make_response
+from flask import Flask
-from flask_login import (LoginManager, login_user, logout_user,
+from flask_login import LoginManager
-                         login_required, current_user)
 
-from core.stf_client import STFClient
 from core.task_manager import TaskManager
-from core.logger import get_logger, _LOG_DIR, _MODULE_FILES
-from core.models import db, init_db, User, DeviceGroup, TaskJob
 from core.apk_manager import ApkManager
-from core.adb_helper import screenshot
+from core.logger import get_logger
-from tasks import list_task_types, get_task_class
+from core.models import db, init_db, User
+from core import uiauto_helper
+from config import WEB_HOST, WEB_PORT
 
 _log = get_logger("web")
 
+
 app = Flask(__name__)
-app.config["SECRET_KEY"] = "dev-secret-key-change-in-production"
+# 会话密钥：优先 .env 的 WEB_SECRET_KEY；未配置则随机生成（重启后登录态失效，生产务必配置固定值）
+_web_secret = os.environ.get("WEB_SECRET_KEY") or secrets.token_hex(32)
+if not os.environ.get("WEB_SECRET_KEY"):
+    _log.warning("未配置 WEB_SECRET_KEY，已随机生成会话密钥（重启后登录态失效）")
+app.config["SECRET_KEY"] = _web_secret
+# debug=False 时模板默认不自动重载，开发期改 HTML 需重启才生效；这里显式开启
+app.config["TEMPLATES_AUTO_RELOAD"] = True
 app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///" + os.path.join(
     os.path.dirname(os.path.abspath(__file__)), "data", "users.db")
 app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
 
 login_manager = LoginManager(app)
-login_manager.login_view = "login"
+login_manager.login_view = "auth.login"  # 蓝图化后路由前缀 auth
 
 # 先初始化数据库（含旧 JSON 迁移），再创建 TaskManager（需要 app context 读写 DB）
 init_db(app)
-stf = STFClient()
+# 设备池（本地清单 + adb 在线状态）：任务调度的数据源
-mgr = TaskManager(stf, app=app)
+from core import device_pool
-apk_mgr = ApkManager(stf, app=app)
+device_pool.init_app(app)
+# 设备自动发现：定时扫描网段 → 待连接池（确认后才入池）
+from core import device_discovery
+device_discovery.init_app(app)
+mgr = TaskManager(app=app)
+apk_mgr = ApkManager(app=app)
+
+# Web 层按模块拆分（web/ 蓝图包）：认证/监控/任务/管理/工具/设备池/APK/Tailscale
+from web import context, register_blueprints
+from web.auth import _csrf_protect, _csrf_token
+context.init(mgr, apk_mgr, device_pool)
+register_blueprints(app)
 
 
 @login_manager.user_loader
@@ -50,371 +63,119 @@ def load_user(user_id):
     return User.query.get(int(user_id))
 
 
-# ================== 页面路由 ==================
+# ================== API：健康检查（无需登录，供探活） ==================
-@app.route("/")
-@login_required
-def index():
-    """单页应用首页。"""
-    resp = make_response(render_template("admin/monitor.html"))
-    resp.headers["Cache-Control"] = "no-store, no-cache, must-revalidate, max-age=0"
-    resp.headers["Pragma"] = "no-cache"
-    return resp
 
 
-@app.route("/login", methods=["GET", "POST"])
+_UIAUTO_PID_FILE = os.path.join(
-def login():
+    os.path.dirname(os.path.abspath(__file__)), "data", "uiauto.pid")
-    if request.method == "POST":
+_uiauto_proc = None
-        username = request.form.get("username", "")
-        password = request.form.get("password", "")
-        user = User.query.filter_by(username=username).first()
-        if user and user.check_password(password):
-            login_user(user)
-            _log.info(f"用户 {username} 登录")
-            return redirect(request.args.get("next") or url_for("index"))
-        return render_template("admin/login.html", error="用户名或密码错误")
-    return render_template("admin/login.html", error=None)
 
 
-@app.route("/logout")
+def _kill_stale_uiauto():
-@login_required
+    """清理上次 web_server 残留的 uiautodev 进程（读取 PID 文件）。"""
-def logout():
+    if not os.path.exists(_UIAUTO_PID_FILE):
-    _log.info(f"用户 {current_user.username} 登出")
+        return
-    logout_user()
-    return redirect(url_for("login"))
-
-
-# ================== API：状态（监控大屏用）==================
-@app.route("/api/status")
-@login_required
-def api_status():
-    devices, err = mgr.get_status()
-    if err:
-        return jsonify({"ok": False, "error": err}), 500
-    return jsonify({
-        "ok": True, "devices": devices, "server_time": time.time(),
-        "fg_scanning": mgr._fg_scanner.is_scanning,
-        "fg_last_scan": mgr._fg_scanner.last_scan_time,
-    })
-
-
-@app.route("/api/scan_foreground", methods=["POST"])
-@login_required
-def api_scan_foreground():
-    """手动触发前台 App 扫描（不打扰设备）。"""
-    started = mgr._fg_scanner.scan_once()
-    if started:
-        return jsonify({"ok": True, "msg": "扫描已启动"})
-    return jsonify({"ok": False, "error": "已有扫描在进行中"})
-
-
-@app.route("/api/task_types")
-@login_required
-def api_task_types():
-    return jsonify({"ok": True, "task_types": list_task_types()})
-
-
-@app.route("/api/actions")
-@login_required
-def api_actions():
-    """返回指定任务类型支持的专属操作。"""
-    task_type = request.args.get("task_type", "")
-    task_cls = get_task_class(task_type)
-    if not task_cls:
-        return jsonify({"ok": False, "error": "未知任务类型", "actions": []})
-    actions = task_cls.list_action_types()
-    return jsonify({"ok": True, "actions": actions})
-
-
-@app.route("/api/devices")
-@login_required
-def api_devices():
-    """返回所有在线设备 serial（供分组表单勾选用）。"""
     try:
-        return jsonify({"ok": True, "devices": mgr.list_all_serials()})
+        with open(_UIAUTO_PID_FILE) as f:
-    except Exception as e:
+            pid = int(f.read().strip())
-        return jsonify({"ok": False, "error": str(e)}), 500
+        if pid > 0 and pid != os.getpid():
-
-
-# ================== API：任务计划 CRUD ==================
-@app.route("/api/jobs")
-@login_required
-def api_jobs_list():
-    return jsonify({"ok": True, "jobs": [j.to_dict() for j in mgr.jobs.values()],
-                    "task_types": list_task_types()})
-
-
-@app.route("/api/jobs", methods=["POST"])
-@login_required
-def api_jobs_create():
-    data = request.json or {}
-    name = (data.get("name") or "").strip()
-    if not name:
-        return jsonify({"ok": False, "error": "任务名不能为空"}), 400
-    task_type = data.get("task_type", "douyin_nurture")
-    if not get_task_class(task_type):
-        return jsonify({"ok": False, "error": f"未知任务类型: {task_type}"}), 400
-    job = mgr.add_job(
-        name=name, task_type=task_type,
-        target=data.get("target", {"mode": "all"}),
-        params=data.get("params", {}),
-        schedule=data.get("schedule", {"mode": "once"}),
-        retry=data.get("retry", {"max_attempts": 1, "delay": 60}),
-        enabled=data.get("enabled", True))
-    return jsonify({"ok": True, "msg": "任务已创建", "job": job.to_dict()})
-
-
-@app.route("/api/jobs/<job_id>", methods=["PUT"])
-@login_required
-def api_jobs_update(job_id):
-    job = mgr.jobs.get(job_id)
-    if not job:
-        return jsonify({"ok": False, "error": "任务不存在"}), 404
-    data = request.json or {}
-    fields = {}
-    for k in ("name", "task_type", "target", "params", "schedule", "retry", "enabled"):
-        if k in data:
-            fields[k] = data[k]
-    if "task_type" in fields and not get_task_class(fields["task_type"]):
-        return jsonify({"ok": False, "error": f"未知任务类型: {fields['task_type']}"}), 400
-    mgr.update_job(job_id, **fields)
-    return jsonify({"ok": True, "msg": "任务已更新", "job": job.to_dict()})
-
-
-@app.route("/api/jobs/<job_id>", methods=["DELETE"])
-@login_required
-def api_jobs_delete(job_id):
-    if mgr.delete_job(job_id):
-        return jsonify({"ok": True, "msg": "任务已删除"})
-    return jsonify({"ok": False, "error": "任务不存在"}), 404
-
-
-@app.route("/api/jobs/<job_id>/run", methods=["POST"])
-@login_required
-def api_jobs_run(job_id):
-    return jsonify(mgr.run_job_now(job_id))
-
-
-@app.route("/api/jobs/<job_id>/toggle", methods=["POST"])
-@login_required
-def api_jobs_toggle(job_id):
-    enabled = (request.json or {}).get("enabled", True)
-    job = mgr.toggle_job(job_id, enabled)
-    if not job:
-        return jsonify({"ok": False, "error": "任务不存在"}), 404
-    return jsonify({"ok": True, "msg": f"任务已{'启用' if enabled else '停用'}"})
-
-
-# ================== API：设备分组 CRUD ==================
-@app.route("/api/groups")
-@login_required
-def api_groups_list():
-    return jsonify({"ok": True, "groups": [g.to_dict() for g in mgr.groups.values()]})
-
-
-@app.route("/api/groups", methods=["POST"])
-@login_required
-def api_groups_create():
-    data = request.json or {}
-    name = (data.get("name") or "").strip()
-    if not name:
-        return jsonify({"ok": False, "error": "分组名不能为空"}), 400
-    if name in mgr.groups:
-        return jsonify({"ok": False, "error": "分组名已存在"}), 400
-    mgr.add_group(name, data.get("serials", []), data.get("description", ""))
-    return jsonify({"ok": True, "msg": "分组已创建"})
-
-
-@app.route("/api/groups/<name>", methods=["PUT"])
-@login_required
-def api_groups_update(name):
-    if name not in mgr.groups:
-        return jsonify({"ok": False, "error": "分组不存在"}), 404
-    data = request.json or {}
-    mgr.update_group(name,
-                     serials=data.get("serials"),
-                     description=data.get("description"))
-    return jsonify({"ok": True, "msg": "分组已更新"})
-
-
-@app.route("/api/groups/<name>", methods=["DELETE"])
-@login_required
-def api_groups_delete(name):
-    if mgr.delete_group(name):
-        return jsonify({"ok": True, "msg": "分组已删除"})
-    return jsonify({"ok": False, "error": "分组不存在"}), 404
-
-
-# ================== API：用户管理 CRUD ==================
-@app.route("/api/users")
-@login_required
-def api_users_list():
-    users = [{"id": u.id, "username": u.username, "is_admin": u.is_admin} for u in User.query.all()]
-    return jsonify({"ok": True, "users": users})
-
-
-@app.route("/api/users", methods=["POST"])
-@login_required
-def api_users_create():
-    data = request.json or {}
-    username = (data.get("username") or "").strip()
-    password = data.get("password", "")
-    if not username or not password:
-        return jsonify({"ok": False, "error": "用户名和密码不能为空"}), 400
-    if User.query.filter_by(username=username).first():
-        return jsonify({"ok": False, "error": "用户名已存在"}), 400
-    u = User(username=username, is_admin=data.get("is_admin", True))
-    u.set_password(password)
-    db.session.add(u)
-    db.session.commit()
-    _log.info(f"创建用户 {username}")
-    return jsonify({"ok": True, "msg": "用户已创建"})
-
-
-@app.route("/api/users/<int:uid>", methods=["PUT"])
-@login_required
-def api_users_update(uid):
-    u = User.query.get(uid)
-    if not u:
-        return jsonify({"ok": False, "error": "用户不存在"}), 404
-    data = request.json or {}
-    if "password" in data and data["password"]:
-        u.set_password(data["password"])
-    if "is_admin" in data:
-        u.is_admin = bool(data["is_admin"])
-    db.session.commit()
-    _log.info(f"更新用户 {u.username}")
-    return jsonify({"ok": True, "msg": "用户已更新"})
-
-
-@app.route("/api/users/<int:uid>", methods=["DELETE"])
-@login_required
-def api_users_delete(uid):
-    u = User.query.get(uid)
-    if not u:
-        return jsonify({"ok": False, "error": "用户不存在"}), 404
-    if u.username == "admin":
-        return jsonify({"ok": False, "error": "不能删除默认管理员"}), 400
-    if u.id == current_user.id:
-        return jsonify({"ok": False, "error": "不能删除当前登录用户"}), 400
-    db.session.delete(u)
-    db.session.commit()
-    _log.info(f"删除用户 {u.username}")
-    return jsonify({"ok": True, "msg": "用户已删除"})
-
-
-# ================== API：日志查看 ==================
-@app.route("/api/logs")
-@login_required
-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:
+                os.kill(pid, 0)  # 探测进程是否存活
-                content = "".join(f.readlines()[-lines:])
+                os.kill(pid, 15)  # 终止残留
-        except Exception as e:
+                _log.warning(f"已清理残留的 uiautodev 进程 (PID={pid})")
-            content = f"读取失败: {e}"
+            except ProcessLookupError:
-    return jsonify({"ok": True, "content": content, "file": current, "files": files})
+                pass
+            except PermissionError:
+                _log.warning(f"无权限清理残留 uiautodev (PID={pid})，忽略")
+    except Exception:
+        pass
+    finally:
+        try:
+            os.remove(_UIAUTO_PID_FILE)
+        except OSError:
+            pass
 
 
-# ================== API：运行控制 ==================
+def _ensure_uiauto_running():
-@app.route("/api/stop_device", methods=["POST"])
+    """确保 uiautodev 本地服务在运行（元素抓取功能依赖，端口 20242）。
-@login_required
-def api_stop_device():
-    serial = (request.json or {}).get("serial", "")
-    if mgr.stop_device(serial):
-        return jsonify({"ok": True, "msg": f"已发送停止信号给 {serial}"})
-    return jsonify({"ok": False, "error": f"{serial} 没有运行中的任务"}), 400
 
-
+    已在运行则跳过；未运行则用子进程启动 `uiautodev server --no-browser`。
-@app.route("/api/stop_all", methods=["POST"])
+    启动失败只记日志，不影响主服务。
-@login_required
-def api_stop_all():
-    stopped = mgr.stop_all()
-    return jsonify({"ok": True, "stopped": stopped})
-
-
-@app.route("/api/release", methods=["POST"])
-@login_required
-def api_release():
-    released = stf.release_all_mine()
-    return jsonify({"ok": True, "released": released})
-
-
-@app.route("/api/device/screenshot")
-@login_required
-def api_device_screenshot():
-    """获取设备当前画面截图（PNG）。
-
-    用 adb exec-out screencap -p，只读操作，不抢占 u2 的 atx-agent 通道，
-    任务运行中调用安全。直接返回 image/png，前端用 <img> 加载。
-    ?serial=xxx  设备 serial
-    ?t=123       时间戳，避免浏览器缓存（前端自动加）
     """
-    serial = request.args.get("serial", "")
+    global _uiauto_proc
-    if not serial:
+    _kill_stale_uiauto()
-        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    if uiauto_helper.is_running():
-    ok, data = screenshot(serial)
+        _log.info("uiauto2 服务已在运行 (端口 20242)")
-    if ok:
+        return
-        return Response(data, mimetype="image/png",
+    try:
-                        headers={"Cache-Control": "no-store"})
+        _log.info("正在自动启动 uiautodev 服务 (端口 20242)...")
-    return jsonify({"ok": False, "error": data}), 500
+        kwargs = dict(stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        if sys.platform == "win32":
+            kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+        _uiauto_proc = subprocess.Popen(
+            [sys.executable, "-m", "uiautodev", "server", "--no-browser"],
+            **kwargs,
+        )
+        _log.info(f"uiautodev 服务已启动 (PID={_uiauto_proc.pid})")
+        try:
+            with open(_UIAUTO_PID_FILE, "w") as f:
+                f.write(str(_uiauto_proc.pid))
+        except OSError:
+            pass
+        atexit.register(_stop_uiauto)
+    except FileNotFoundError:
+        _log.warning("uiautodev 未安装，元素抓取功能不可用。请运行: pip install uiautodev")
+    except Exception as e:
+        _log.warning(f"自动启动 uiautodev 失败: {e}（元素抓取功能不可用）")
 
 
-# ================== API：应用管理（APK 上传/安装）==================
+def _stop_uiauto():
-@app.route("/api/apks")
+    """停止自动启动的 uiautodev 子进程。"""
-@login_required
+    global _uiauto_proc
-def api_apks_list():
+    try:
-    """列出所有已上传的 APK。"""
+        if os.path.exists(_UIAUTO_PID_FILE):
-    return jsonify({"ok": True, "apks": apk_mgr.list_all()})
+            os.remove(_UIAUTO_PID_FILE)
+    except OSError:
+        pass
+    if not _uiauto_proc:
+        return
+    try:
+        _uiauto_proc.terminate()
+        _uiauto_proc.wait(timeout=5)
+        _log.info("uiautodev 服务已停止")
+    except Exception:
+        try:
+            _uiauto_proc.kill()
+        except Exception:
+            pass
+    _uiauto_proc = None
 
 
-@app.route("/api/apks/upload", methods=["POST"])
+def _preconnect_pool_devices():
-@login_required
+    """容器/服务重启后 adb server 重启，设备全部掉线，逐个重连要几分钟；
-def api_apks_upload():
+    启动时后台并发 connect 设备池里的网络设备（IP:5555），把恢复时间降到秒级。
-    """上传 APK 文件（multipart/form-data，字段名 file）。"""
-    file = request.files.get("file")
-    if not file or not file.filename:
-        return jsonify({"ok": False, "error": "未选择文件"}), 400
-    info = apk_mgr.upload(file)
-    if info:
-        return jsonify({"ok": True, "apk": info,
-                        "msg": f"上传成功: {info['display_name']}"})
-    return jsonify({"ok": False, "error": "上传失败，请检查文件格式"}), 500
 
-
+    USB 设备无需 connect（adb server 自动重枚举），只连网络设备。
-@app.route("/api/apks/<apk_id>", methods=["DELETE"])
+    预连接幂等：已连接的设备返回 already connected，无副作用。
-@login_required
+    """
-def api_apks_delete(apk_id):
+    def _run():
-    """删除 APK 文件和记录。"""
+        try:
-    ok, msg = apk_mgr.delete(apk_id)
+            from core import device_pool
-    if ok:
+            from core.adb_helper import _adb
-        return jsonify({"ok": True, "msg": msg})
+            serials = [s for s in device_pool.list_configured() if ":" in s]
-    return jsonify({"ok": False, "error": msg}), 400
+            if not serials:
-
+                return
-
+            _log.info(f"预连接设备池 {len(serials)} 台网络设备（重启后加速恢复）...")
-@app.route("/api/apks/install", methods=["POST"])
+            import concurrent.futures
-@login_required
+            with concurrent.futures.ThreadPoolExecutor(max_workers=8) as ex:
-def api_apks_install():
+                list(ex.map(lambda s: _adb("connect", s), serials))
-    """批量安装 APK 到指定设备。参数: {apk_id, serials:[]}"""
+            out = _adb("devices")
-    data = request.json or {}
+            online = sum(1 for ln in (out or "").splitlines()[1:]
-    apk_id = data.get("apk_id", "")
+                         if len(ln.split()) >= 2 and ln.split()[1] == "device")
-    serials = data.get("serials", [])
+            _log.info(f"设备池预连接完成: {online} 台在线")
-    ok, msg = apk_mgr.install(apk_id, serials)
+        except Exception as e:
-    if ok:
+            _log.warning(f"设备池预连接失败: {e}")
-        return jsonify({"ok": True, "msg": msg})
+    threading.Thread(target=_run, daemon=True).start()
-    return jsonify({"ok": False, "error": msg}), 400
-
-
-@app.route("/api/apks/install/status")
-@login_required
-def api_apks_install_status():
-    """获取安装任务实时状态。"""
-    status = apk_mgr.get_install_status()
-    return jsonify({"ok": True, "status": status})
 
 
 def _run_server(host, port):
@@ -453,8 +214,14 @@ def _run_server(host, port):
 
 if __name__ == "__main__":
     from config import WEB_HOST, WEB_PORT
+    # 自动启动 uiautodev 服务（元素抓取功能依赖，端口 20242）
+    _ensure_uiauto_running()
+    # 预连接设备池：adb server 重启后设备全掉线，后台并发重连加速恢复
+    _preconnect_pool_devices()
     _log.info(f"管理后台: http://localhost:{WEB_PORT}/ (admin/admin123)")
     try:
         _run_server(WEB_HOST, WEB_PORT)
     finally:
         mgr.shutdown()
+        device_discovery.shutdown()
+        _stop_uiauto()