chore: 容器依赖守卫补 qrcode——设备配置二维码用了它，不加的话容器重启不会安装（守卫只看固定模块列表）

用户反馈的三件事：

1) **监控页设备排序**改成按**名称**（A01/A02/…），没名字的排最后按地址。
   之前是 adb 返回的顺序，看着像按 IP 排，同型号多台时对不上号。
   排序放在 `/api/status`（后端），大屏页一并受益。

2) **操作按钮改名 + 换实现**：
   - 「截图」→「**看屏**」（行为不变，就是查看设备实时画面）
   - 「定位」→「**打开设备端 Agent**」：改成让设备上的 Agent 弹身份大字页
     （名称/IP/平台地址），替代原来"推 HTML 让设备浏览器打开定位页"那套
     （那套要设备装浏览器、页面还依赖设备能访问平台，backlog A1/A2 一直没修）
     * 新接口 `POST /api/agent/show-info {serial, close?}`；没装 Agent 时明确报出来
     * **先点亮屏幕 + 解除锁屏再拉起** —— 设备息屏时 am start 会把大字页开在锁屏后面，
       人看到的还是一片黑（实测踩过）
     * 平台地址取操作者当前访问地址；若是 localhost 则换成本机局域网地址
       （设备上显示 127.0.0.1 毫无意义）

3) **安装应用的选择设备界面仍显示裸序列号**：USB 设备在 adb 里的 serial 就是
   `ro.serialno`，等于池里那条网络记录的**指纹** —— 之前只按 serial 匹配，插着 USB
   时会冒出一个没名字的 `s8o7nrt8pbzhfadq`。现在按 serial 或指纹任一命中都取名称，
   三处（剪贴板注入 / 安装弹窗 / 安装进度表）统一。

顺带修掉几个自己踩出来的坑：
- `device_pool.list_configured()` 返回的是 **serial 字符串列表**，我当成字典用了
  （`.get("serial")` 抛异常被 except 吞掉 → 名字全空）→ 改用 `list_devices()`
- `web/device_agent_api.py` 用了 `PERM_DEVICES` 但没导入 → 服务直接起不来（502）
- Agent 自检里的版本号是写死的常量（升到 1.4 还显示 1.0）→ 改成读包信息
- `doc/API.md` 章节编号（插了一节没把后面整体下移，出现两个 §16）

验证：安装弹窗里 USB 那台现在显示「A07」（指纹匹配）；监控页按钮为
「看屏 / 打开设备端 Agent」；对装/未装 Agent 的设备分别得到大字页 / 明确报错；
大字页实测显示 A07 + 192.168.20.250:18050 + Agent v1.4。

.env.example

@@ -1,41 +1,118 @@
-# 环境变量示例：复制为 .env 并按需修改（.env 不进 git）
+# ==============================================================================
-# 生产环境建议用环境变量/密钥管理注入，不要把真实 token 写进 git。
+# auto_control 环境变量示例
-# 全部可配置项见 config.py（_env() 读取，未配置时用代码内默认值）；
+#   - 复制为项目根目录的 .env 再按需修改（.env 已被 .gitignore 排除，不会进 git）
-# 标"必须"的项务必设置，其余可留空用默认。
+#   - 加载方式：config.py 逐行解析后用 os.environ.setdefault 注入
+#     → 因此"真实环境变量"优先于 .env（容器/CI 里用 env 覆盖更方便）
+#   - 标【必须】的项务必设置；其余留空即用代码默认值
+#   - 完整说明见 doc/DEVELOPMENT.md §4 配置速查、doc/DEPLOY.md §2.2
+# ==============================================================================
 
-# ==================== STF 平台 ====================
+# ==================== 数据库 ====================
-# STF 服务地址（默认 http://192.168.20.220:7100）
+# 平台用 MySQL（正式用法）。DEPLOY_ENV 声明"这份配置连的是哪个环境的库"，
-STF_URL=http://192.168.20.220:7100
+# 并与库名一一绑定，启动时会互相校验，不符直接拒绝启动：
+#   DEPLOY_ENV=dev  →  期望库名 auto_control_dev（本地开发，可随意折腾）
+#   DEPLOY_ENV=prod →  期望库名 auto_control    （正式数据）
+# 首次连接的库会被打上环境标签（app_meta.deployment_env）；标签与 DEPLOY_ENV
+# 不符时拒绝启动——这是防止「开发配置连到生产库」的最后一道闸。
+DEPLOY_ENV=dev
+DB_HOST=
+DB_PORT=3306
+DB_USER=
+DB_PASSWORD=
+DB_NAME=auto_control_dev
+# 排序规则用 _bin（逐码点比较，等价 SQLite 的大小写敏感语义），别改成 _general_ci
+DB_CHARSET=utf8mb4
+DB_COLLATION=utf8mb4_bin
 
-# STF API Token（必须：STF 个人设置 → API Keys 生成）
+# 完整连接串：优先级最高，用于脚本临时指向别的库（一般不用配）
-STF_TOKEN=请填写你的STF_token
+# DATABASE_URL=mysql+pymysql://user:pass@host:3306/auto_control_dev?charset=utf8mb4
 
-# 启动时自动释放残留 STF 占用（单实例无人值守开 true；多实例共用账户勿开，会误放另一实例的任务）
+# 逃生阀（默认关，仅在明确知道后果时打开）
-# AUTO_RELEASE_STALE_OCCUPY=true
+#   DB_ALLOW_ENV_MISMATCH=1     环境与库名/库标签不符时仍启动（危险）
+#   DB_ALLOW_SQLITE_FALLBACK=1  生产环境 DB_HOST 为空时允许回退 SQLite（回滚用）
+# DB_ALLOW_ENV_MISMATCH=0
+# DB_ALLOW_SQLITE_FALLBACK=0
 
-# ==================== Web 会话 ====================
+
-# Web 会话密钥（必须：生产设置为随机长字符串，重启不失效）
+# ==================== Web 服务 ====================
+# 会话密钥【必须，生产务必固定】：不配则每次启动随机生成，重启后登录态失效。
 # 生成：python -c "import secrets; print(secrets.token_hex(32))"
 WEB_SECRET_KEY=请填写随机密钥
 
-# ==================== SSH 到部署机（维护页重启 STF / 工具页 STF 设备管理） ====================
+# 监听地址与端口是 config.py 里的常量（不进 .env）：WEB_HOST=0.0.0.0、WEB_PORT=18050
-# SSH 目标（默认 [email protected]）
+# 需要修改直接改 config.py（18050 是为了避开 Windows 动态端口段）
-# [email protected]
 
-# SSH 认证密码（推荐）：配置后走 paramiko **纯密码**登录（不碰本地密钥/SSH agent，
-# 不会弹授权框，跨平台无需 sshpass）；留空则退回系统 ssh 免密密钥（BatchMode=yes）。
-STF_SSH_PASSWORD=请填写SSH密码
 
-# 220 上 STF / adb 的 Docker 容器名（默认 stf / adb，一般不用改）
+# ==================== 设备与 adb ====================
-# STF_DOCKER_CONTAINER=stf
+# USB 设备（serial 无冒号）所在的部署机 —— 平台经它的 adb server 驱动这些设备。
-# STF_ADB_CONTAINER=adb
+# 默认 100.100.10.1:5037（220 的 Tailscale IP + adb 容器端口，host 网络模式）。
+# USB_ADB_HOST=100.100.10.1
+# USB_ADB_PORT=5037
 
-# STF 设备池脚本路径（工具页"STF 设备管理"增删设备时读写其 DEVICES 列表，默认值见 config.py）
+# 设备自动发现（扫描网段找开放 5555 的设备）。
-# STF_SCRIPT_PATH=/mnt/data/openstf/connect_devices.sh
+# 扫描网段在「工具 → 设备池管理」界面里配置（存数据库 app_meta），此处只管端口与周期。
+# DISCOVERY_PORT=5555
+# DISCOVERY_INTERVAL=60
 
-# ==================== Tailscale 管理（工具页） ====================
+# 把本机的 adb 客户端指向远程 adb server（注意：这三个键由 adb/adbutils 自己读取，
-# API key（必须：Tailscale 后台 → Settings → API Access Tokens 生成）
+# 不是本项目代码读的；两个变量名都要设，adb 实际认 ADDRESS，部分库读 HOST）。
+# 用途：让本机 adb 直接看到 220 侧插着的 USB 设备。
+# ANDROID_ADB_SERVER_ADDRESS=192.168.20.220
+# ANDROID_ADB_SERVER_HOST=192.168.20.220
+# ANDROID_ADB_SERVER_PORT=5037
+
+
+# ==================== Tailscale 管理（工具 → Tailscale 管理） ====================
+# API key：Tailscale 后台 → Settings → API Access Tokens 生成
 TAILSCALE_API_KEY=请填写Tailscale_API_key
 
-# tailnet 名/ID（默认按邮箱前缀，如 1422726308@gmail.com）
+# tailnet 名/ID（一般填登录邮箱，如 user@example.com）
-# TAILSCALE_TAILNET=1422726308@gmail.com
+# TAILSCALE_TAILNET=user@example.com
+
+
+# ==================== MCP Server（外部 AI 接入，:8033） ====================
+# 注意：mcp_server 只读进程环境变量，**不读本文件**！
+#   容器场景由 scripts/start.sh 用下面这些变量拉起进程；
+#   本机手动启动请直接在命令行前加环境变量（见 doc/MCP.md §2）。
+#
+# MCP_ENABLED=1                  # 仅 start.sh 消费：=0 则不自动拉起 MCP
+# MCP_ALLOW_WRITE=1              # 写操作总开关（0=只读；start.sh 内强制为 1）
+# MCP_PLATFORM_URL=http://127.0.0.1:18050
+# MCP_PLATFORM_USER=admin
+# MCP_PLATFORM_PASS=请填写平台admin密码   # 【改过 admin 密码必须同步，否则 MCP 登录失败】
+# MCP_ALLOWED_SERIALS=           # 设备白名单（逗号分隔）；空=不限制（语义缺口见 backlog）
+# MCP_HTTP_HOST=0.0.0.0
+# MCP_HTTP_PORT=8033
+# MCP_SCREENSHOT_WIDTH=540       # 返回给模型的截图宽度
+# MCP_JPEG_QUALITY=70
+# MCP_AUDIT_FILE=/tmp/mcp_audit.log
+# MCP_PLATFORM_TIMEOUT=30
+
+
+# ==================== AI Agent（mcp_agent，命令行/独立运行时用） ====================
+# 注意：同样只读进程环境变量、不读本文件。
+# Web 的「AI 控制台」配置走数据库（app_meta 的 agent_* 键），与本组变量互不影响。
+#
+# AGENT_API_BASE=https://api.deepseek.com
+# AGENT_MODEL=deepseek-v4-flash-vision-exp
+# AGENT_API_KEY=请填写模型 API Key
+# DEEPSEEK_API_KEY=              # AGENT_API_KEY 的兼容别名
+# AGENT_MCP_URL=http://127.0.0.1:8033/mcp
+# AGENT_DEFAULT_SERIAL=
+# AGENT_MAX_STEPS=40
+# AGENT_TIMEOUT=120
+# AGENT_LANG=zh
+
+
+# ==================== 开发/测试 ====================
+# 设置后不启动 cron 调度器（跑测试脚本时避免真实触发任务、占用设备）
+# DISABLE_SCHEDULER=1
+
+
+# ==============================================================================
+# 已废弃的历史配置（STF 已从代码层摘除，下列键代码不再使用，保留仅为兼容旧 .env）
+#   STF_URL / STF_TOKEN / STF_SSH_TARGET / STF_SSH_PASSWORD /
+#   STF_DOCKER_CONTAINER / STF_ADB_CONTAINER / STF_SCRIPT_PATH /
+#   AUTO_RELEASE_STALE_OCCUPY
+# 迁移背景见 doc/STF_REMOVAL.md
+# ==============================================================================

.gitignore

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

README.md

@@ -1,23 +1,58 @@
-# 设备自动化后台（platform-tools）
+# auto_control — Android 多设备自动化任务平台
 
-基于 **uiautomator2 + Flask + 自建设备池** 的 Android 多设备自动化任务执行平台（已摘除 OpenSTF 依赖）。
+基于 **uiautomator2 + Flask + 自建设备池** 的 Android 多设备自动化平台（已摘除 OpenSTF 依赖，见 [doc/STF_REMOVAL.md](doc/STF_REMOVAL.md)）。
 
-提供 Web 管理后台，支持多设备并发任务执行、定时调度、设备分组管理、设备池管理（新增/停用/删除/型号采集）、APK 批量安装、网页远程看屏（MJPEG 实时流 + 触控）、UI 元素抓取等功能。内置抖音养号任务和通用步骤任务，可扩展任意 App 的自动化操作。
+一台机器上统管一批 Android 设备：定时/手动下发任务、并发执行、实时看屏与远程触控、元素抓取与步骤编排、APK 批量安装、数据备份导出/导入；并通过 **MCP** 把手机控制能力开放给外部 AI（数字员工）。
+
+```
+                       ┌──────────── Web 管理后台（单页应用，:18050）────────────┐
+   浏览器 ────────────▶ │ 监控 │ 任务 │ 日志 │ 用户 │ 工具 │ AI 控制台 │ 系统     │
+                       └───────────────────────┬─────────────────────────────────┘
+                                               │ Flask 蓝图（web/）
+                       ┌───────────────────────▼──────┐   ┌──────────────────────┐
+                       │ 调度 TaskManager             │   │ AI Agent（mcp_agent）│
+                       │ 设备池 device_pool           │   └──────────┬───────────┘
+                       │ Worker（每设备一线程）        │              │ MCP :8033
+                       └───────┬──────────────┬───────┘   ┌──────────▼───────────┐
+                               │              │           │ MCP Server（de_* 工具）│
+                          adb 直连         uiautodev        └──────────┬───────────┘
+                        IP:5555 / USB   :20242（抓元素）                │
+                               ▼                                      ▼
+                         Android 设备 ◀──────────────────────── Android 设备
+```
 
 ---
 
 ## 目录
 
+- [核心能力](#核心能力)
 - [快速上手](#快速上手)
 - [项目结构](#项目结构)
 - [核心概念](#核心概念)
-- [配置说明](#配置说明)
 - [Web 管理后台](#web-管理后台)
-- [任务系统](#任务系统)
+- [任务与步骤](#任务与步骤)
-- [日志系统](#日志系统)
+- [AI 与 MCP](#ai-与-mcp)
-- [常用脚本](#常用脚本)
+- [配置说明](#配置说明)
+- [日志](#日志)
 - [常见问题](#常见问题)
-- [更多文档](#更多文档)
+- [文档索引](#文档索引)
+
+---
+
+## 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| **多设备并发任务** | 每设备一个 Worker 线程；同一设备同时只跑一个任务（可配置"抢占"打断其他任务） |
+| **设备池** | SQLite 清单 + adb 在线状态；支持手工添加、网段自动发现、一键重连、型号采集、启用/停用 |
+| **任务调度** | 手动 / cron 定时 / 定时启停；运行窗口；失败重试（含端口耗尽类的长退避） |
+| **步骤编辑器** | 可视化拖拽编排 18 种步骤（含循环/条件/OCR），可打包成"自定义动作"复用 |
+| **元素抓取** | 拉取设备 UI 元素树 → 点选回填选择器；支持"点一下"与"测选择器"真机验证 |
+| **实时看屏** | MJPEG 实时流 + 点击/滑动/按键/文字输入；全屏监控大屏（`/wall`） |
+| **应用管理** | APK 上传/解析/批量安装；设备已装应用与版本查询；剪贴板注入 |
+| **AI 控制台** | 用自然语言驱动 AI 操作指定设备（MCP 工具 + 截图），流式输出、Markdown 渲染、推理链折叠、token 统计；成功操作自动沉淀「经验库 / 动作库」并在相似任务中召回 |
+| **MCP 接入** | 19 个 `de_*` 工具，把手机控制开放给外部 AI；写操作有开关、设备忙时拒绝、全量审计 |
+| **备份导出/导入** | 一键导出 zip（库快照 + manifest + 可选 APK），导入前校验预览、自动预备份、重启生效 |
 
 ---
 
@@ -26,9 +61,8 @@
 ### 环境要求
 
 - **Python 3.10+**（推荐 3.12）
-- **Windows / Linux / macOS**均可（adb 二进制需放对应平台版本到 `bin/adb/`）
+- Windows / Linux / macOS 均可（`bin/adb/` 需放对应平台的 adb 二进制）
-- 设备需开启 **USB 调试**（USB 连上后 `adb tcpip 5555` 转网络调试），并加入 Tailscale 获得 `100.100.10.x` IP
+- 设备开启 **USB 调试**；网络调试设备建议 `adb tcpip 5555` 并接入同一网络（本项目生产环境走 Tailscale `100.100.10.x`，见 [doc/DEPLOY.md](doc/DEPLOY.md)）
-- 新增设备在后台「工具 → 设备池管理」添加 `IP:5555`（自动连接，任务运行时 u2 自动推送 atx-agent）
 
 ### 三步启动
 
@@ -36,421 +70,327 @@
 # 1. 安装依赖
 pip install -r requirements.txt
 
-# 2. 修改配置（可选）：USB 设备在 220 上时配置 USB_ADB_HOST/PORT（默认 100.100.10.1:5037 已可用）
+# 2. 配置（可选）：把 .env.example 复制成 .env，至少填 WEB_SECRET_KEY
-#    密钥类配置放 .env（WEB_SECRET_KEY / TAILSCALE_API_KEY）
+#    密钥类配置一律放 .env（不入 git）
 
-# 3. 启动 Web 后台
+# 3. 启动
 python web_server.py
 ```
 
-启动后访问 **http://localhost:18050/**，默认账号 `admin` / `admin123`。
+启动后访问 **http://localhost:18050/**，默认账号 `admin` / `admin123`（**首次登录请立即改密**）。
 
 ### 验证启动
 
-控制台看到以下日志即表示启动成功：
-
 ```
 [INFO] [core.worker] 心跳看门狗已启动
 [INFO] [core.tm] 从数据库加载 X 个分组, X 个任务
+[INFO] [web] uiautodev 服务已启动 (PID=...)
 [INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
+[INFO] [web] 设备池预连接完成: X 台在线
 [INFO] [web] 启动服务: http://localhost:18050/
 ```
 
-### 首次使用流程
+### 首次使用
 
-1. **登录后台** → 用 `admin/admin123` 登录，建议立即修改密码
+1. **登录** → `admin/admin123`，改密
-2. **添加设备** → "工具 → 设备池管理"添加设备（serial 形如 `100.100.10.20:5555`，自动连接并采集型号）
+2. **加设备** → 「工具 → 设备池管理」添加 `IP:5555`（自动连接 + 采集型号）；也可用「设备自动发现」扫描网段后确认入池
-3. **查看设备** → 首页"监控"Tab 展示设备池状态（在线/型号/任务）
+3. **看设备** → 「监控」页设备表（在线/型号/任务/进度/前台 App）
-4. **创建分组**（可选）→ "分组"Tab 按批次/项目给设备分组
+4. **建任务** → 「任务 → 任务计划 → 新建任务」（只有 `generic_steps` 一种类型）→ 拖步骤 → 选目标设备 → 保存
-5. **创建任务** → "任务"Tab 新建任务，选择任务类型、目标设备、参数、调度
+5. **跑任务** → 任务行「执行」，或在「任务」/「监控」页操作
-6. **执行任务** → 任务列表点"立即执行"，或在"监控"Tab 勾选设备批量操作（亮屏/息屏/停止）
+6. **看日志** → 「日志」页按模块实时查看
-7. **查看日志** → "日志"Tab 实时查看运行日志
 
 ---
 
 ## 项目结构
 
 ```
-platform-tools/
+auto_control/
-├── config.py                    # 根配置（部署配置统一从 .env 读，模板见 .env.example）
+├── config.py                  # 程序级配置常量（部署配置从 .env 读，模板 .env.example）
-├── web_server.py                # Flask 入口（app 装配 + 蓝图注册 + 启动，193 行）
+├── web_server.py              # 入口：app 装配 + 蓝图注册 + 恢复消费 + 拉起 uiautodev + 启动
-├── web/                         # Web 层蓝图包（按功能域拆分，路由都在这里）
+├── requirements.txt           # 依赖清单
-│   ├── auth.py                  #   登录/CSRF/权限装饰器/页面路由（/、/wall）
+│
-│   ├── monitor.py               #   状态/运行控制/设备操作/远程看屏
+├── web/                       # Web 层（蓝图包，路由都在这里，全部无 url_prefix）
-│   ├── tasks_api.py             #   任务计划/分组/自定义动作/元素抓取
+│   ├── auth.py                #   登录/登出/CSRF/权限装饰器/页面路由（/、/wall）
+│   ├── monitor.py             #   设备状态/运行控制/设备操作/远程看屏（MJPEG、点击、按键）
+│   ├── tasks_api.py           #   任务计划/分组/自定义动作/元素抓取/步骤测试
 │   ├── admin_api.py           #   用户管理/日志
-│   ├── tools_api.py             #   adb 终端/剪贴板注入/应用版本
+│   ├── tools_api.py           #   adb 终端/剪贴板注入/应用版本查询
-│   ├── devices_api.py           #   设备池管理
+│   ├── devices_api.py         #   设备池管理 + 自动发现
-│   ├── apks_api.py              #   应用管理
+│   ├── apks_api.py            #   APK 上传/安装/删除
-│   ├── tailscale_api.py         #   Tailscale 管理
+│   ├── tailscale_api.py       #   Tailscale 管理（改名/授权/密钥/IP/auth key）
-│   ├── common.py                #   跨模块共享工具（合并设备列表/屏幕状态）
+│   ├── agent_api.py           #   AI 控制台（会话/SSE/经验库/动作库/巡检）
-│   └── context.py               #   共享对象注入（mgr/apk_mgr/device_pool）
+│   ├── system_api.py          #   系统数据备份导出/导入
-├── requirements.txt             # Python 依赖清单
+│   ├── common.py              #   跨模块共享工具（合并设备列表、屏幕状态）
+│   └── context.py             #   共享对象注入（mgr / apk_mgr / device_pool）
 │
-├── core/                        # 核心基础设施层
+├── core/                      # 基础设施层
-│   ├── logger.py                #   统一日志（分文件、10MB 滚动）
+│   ├── models.py              #   SQLAlchemy 模型 + 建表 + 版本化迁移 + 旧 JSON 迁移
-│   ├── device_pool.py           #   设备池（SQLite 清单 + adb 在线状态 + 型号采集）
+│   ├── device_pool.py         #   设备池（清单/在线状态/型号）
-│   ├── adb_helper.py            #   adb 命令封装（全局锁，绝不 kill-server）
+│   ├── device_worker.py       #   BaseWorker + 设备生命周期 + 心跳看门狗 + 全局状态表
-│   ├── device_worker.py         #   BaseWorker 基类 + 设备生命周期 + 心跳看门狗
+│   ├── task_manager.py        #   调度器：分组/任务/APScheduler/重试/运行控制
-│   ├── task_manager.py          #   TaskManager 调度器 + 前台App扫描器
+│   ├── adb_helper.py          #   adb 命令封装（全局锁，红线：绝不 kill-server）
-│   ├── u2_helper.py             #   uiautomator2 通用辅助函数
+│   ├── device_discovery.py    #   网段扫描发现设备 → 待连接池
-│   ├── uiauto_helper.py         #   uiautodev 元素抓取客户端
+│   ├── u2_helper.py           #   uiautomator2 通用辅助（等首页/安全点击等）
+│   ├── uiauto_helper.py       #   uiautodev 客户端（元素树 + XPath 建议）
+│   ├── ocr.py                 #   屏幕 OCR（RapidOCR，条件判断用）
+│   ├── clipboard_helper.py    #   剪贴板注入（ClipInject 通道）
 │   ├── apk_manager.py         #   APK 上传/解析/批量安装
-│   ├── ocr.py                   #   屏幕 OCR（RapidOCR，条件判断 OCR 选择器）
+│   ├── system_backup.py       #   数据备份导出/导入（重启生效）
-│   ├── ssh_client.py            #   SSH 统一执行（paramiko 纯密码 / 免密密钥，预留运维用）
 │   ├── tailscale_client.py    #   Tailscale API v2 客户端
-│   ├── models.py                #   SQLAlchemy 数据模型 + 数据库初始化
+│   ├── ssh_client.py          #   SSH 封装（当前无人调用，预留）
-│   └── actions/                 #   全局 Action 框架
+│   ├── logger.py              #   分文件日志（core/task/web/action）
+│   └── actions/               #   全局 Action 框架（BaseAction + 注册器）
 │
-├── tasks/                       # 任务定义层（每个 App 一个子包）
+├── tasks/                     # 任务定义层
-│   ├── __init__.py              #   全局任务注册表
+│   ├── base.py                #   BaseTask + _TASK_TYPES + register_task
-│   ├── base.py                  #   BaseTask 基类 + @register_task 装饰器
+│   └── generic/               #   通用步骤任务（task_type=generic_steps，当前唯一类型）
-│   ├── douyin/                  #   抖音养号任务
+│       └── task.py            #     STEP_TYPES（18 种步骤）+ Worker + 执行器
-│   └── generic/                 #   通用步骤任务（可视化编辑器编排）
-│       └── task.py              #     步骤执行引擎（open_app/click/swipe/if_el...）
 │
-├── templates/admin/             # 前端页面
+├── mcp_server/                # MCP Server（19 个 de_* 工具，:8033）
-│   ├── monitor.html             #   单页应用（监控/任务/分组/日志/用户/工具）
+│   ├── mcp_server.py          #   工具定义 + 平台登录 + 门控
-│   └── login.html               #   登录页
+│   ├── platform_client.py     #   平台 HTTP 客户端（复用 Web 账号）
+│   ├── direct_ops.py          #   直连设备的 adb/u2 操作
+│   ├── audit.py               #   调用审计（JSON Lines）
+│   └── config.py              #   MCP_* 环境变量
 │
-├── static/admin/                # 前端 JS 模块（monitor.html 按依赖顺序加载）
+├── mcp_agent/                 # AI Agent 编排层（OpenAI 兼容模型 → MCP 工具）
-│   ├── base.js                  #   通用基础：API/CSRF/权限/Tab切换/子分栏/模态框
+│   ├── agent.py               #   Agent：流式循环 + 工具调用 + 截图 + token 统计
-│   ├── list.js                  #   统一列表组件（搜索+分页+排序）
+│   ├── config.py              #   AGENT_* 环境变量
-│   ├── monitor.js               #   监控页（设备表/截图/异常汇总）
+│   └── cli.py                 #   命令行入口
-│   ├── editor.js                #   步骤编辑器（拖拽/条件判断/元素抓取）
+│
-│   ├── tasks.js                 #   任务 Tab + 自定义动作
+├── templates/admin/           # 页面
-│   ├── tools.js                 #   工具 Tab（剪贴板/设备池管理/adb终端/Tailscale/远程看屏）
+│   ├── monitor.html           #   主单页应用（7 个顶级 Tab + 模态框 + 内联样式）
-│   ├── apps.js                  #   工具 Tab-应用管理（APK/设备已装应用）
+│   ├── login.html             #   登录页
-│   ├── admin.js                 #   管理 Tab（分组/日志/用户）+ 初始化
+│   └── wall.html              #   监控大屏（独立页面，自包含）
+├── static/admin/              # 前端 JS（11 个文件，按顺序同步加载，见下）
 ├── static/fonts/              # 自托管字体（Bricolage Grotesque + IBM Plex Mono）
 │
-├── data/
+├── data/                      # 运行时数据（不入 git）
-│
+│   ├── users.db               #   SQLite 主库
-├── data/                        # 运行时数据
+│   ├── apks/                  #   上传的 APK
-│   ├── users.db                 #   SQLite（用户/分组/任务/自定义动作/APK记录）
+│   ├── backups/               #   导出 zip / 预恢复快照
-│   └── apks/                    #   上传的 APK 文件存储
+│   ├── restore_staging/       #   导入暂存（TTL 30 分钟）
-│
+│   └── restore_pending/       #   待重启生效的恢复任务
-├── logs/                        # 日志文件（自动生成，10MB 滚动保留 5 份）
+├── logs/                      # 日志（10MB 滚动，保留 5 份）
-├── bin/adb/                     # adb 可执行文件（Windows: adb.exe + dll）
+├── bin/adb/                   # adb 二进制
-├── scripts/                     # 实用脚本
+├── scripts/                   # pack.py / start.sh / supervise.sh / regression_test.py
-│   ├── pack.py                  #   打包项目为 zip（排除运行时产物）
+└── doc/                       # 完整文档（入口 → doc/README.md）
-│   └── supervise.sh             #   进程守护（崩溃自动重启）
+```
-└── doc/                         # 项目文档
+
-    ├── API.md                   #   API 文档
+前端 JS 加载顺序（`templates/admin/monitor.html` 底部，全部为全局脚本，无模块隔离）：
-    ├── ARCHITECTURE.md          #   架构详解
+
-    ├── DEPLOY.md                #   部署指南
+```
-    ├── DEVELOPMENT.md           #   开发指南
+base.js → markdown.js → list.js → monitor.js → editor.js → tasks.js
-    └── TASK_DEV.md              #   任务开发指南（新增 App 任务模板）
+        → tools.js → apps.js → admin.js → agent.js → system.js
-    ├── ARCHITECTURE.md          #   架构详解
-    ├── DEPLOY.md                #   部署指南
-    └── API.md                   #   API 接口文档
 ```
 
 ---
 
 ## 核心概念
 
-### 设备生命周期
+### 设备与 Worker
 
-```
+一台设备对应一个 `Worker` 线程（`core/device_worker.py` 的 `BaseWorker`）。基类封装了设备获取、adb/u2 连接（带超时保护）、状态上报、异常分类、停止信号、心跳看门狗；子类只实现 `run_task(d)`。
-设备池选定设备（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）。
+执行链路：`设备池选定 → adb connect 直连（IP:5555）或经 220 远程 adb server（USB）→ u2.connect（自动推送 atx-agent）→ run_task → 释放（不断开连接）`。
 
-### Worker — 单设备执行线程
+**同一设备同时只允许一个 Worker**：由 `TaskManager._running` 内存锁保证；任务可开 `preempt` 抢占（先停掉正在跑的任务再接管，结束后归还）。
 
-每台设备对应一个 `Worker` 线程，继承 `BaseWorker`（`core/device_worker.py`）。基类已封装：
+### 任务类型（TaskType）
 
-- 设备获取（IP:5555 直连 / USB 远程 adb server，try/finally 保证释放）
+| task_type | 名称 | 说明 |
-- adb 连接 + u2.connect（带 30 秒超时保护）
+|-----------|------|------|
-- 状态上报（实时推送到前端监控大屏）
+| `generic_steps` | 通用步骤 | 步骤编辑器编排的流程（**当前唯一类型**） |
-- 异常捕获（设备离线不重试，其他异常按策略重试）
-- stop 停止信号（循环里检查 `self.stopped()`）
-- 心跳看门狗（120 秒无心跳自动标记卡死）
 
-子类只需实现 `run_task(d)` 方法专注业务逻辑。
+新增专属任务类型的方法见 [doc/TASK_DEV.md](doc/TASK_DEV.md)。
 
-### TaskType — 任务类型
+### 任务计划（TaskJob）
 
-| 任务类型 | task_type | 说明 |
+描述"什么任务、跑哪些设备、什么参数、何时跑、失败怎么重试"：
-|---------|-----------|------|
-| 抖音养号 | `douyin_nurture` | 自动看视频 + 随机点赞，被退出自动重连 |
-| 通用步骤 | `generic_steps` | 可视化步骤编辑器编排流程，支持循环/点击/滑动等 |
 
-### TaskJob — 任务计划
+| 字段 | 说明 |
-
-一个 TaskJob 描述"什么时候、在哪些设备上、用什么参数执行什么任务"：
-
-| 字段 | 说明 | 示例 |
-|------|------|------|
-| `task_type` | 任务类型 | `"douyin_nurture"` |
-| `target` | 目标设备 | `{"mode": "all"}` 或 `{"mode": "group", "group_name": "A组"}` 或 `{"mode": "serial", "serial": "192.168.1.100:5555"}` |
-| `params` | 任务参数（与默认值深合并） | `{"watch_count": 50, "actions": {"like": {"params": {"rate": 0.5}}}}` |
-| `schedule` | 调度策略 | `{"mode": "once"}` 或 `{"mode": "cron", "cron": "0 9 * * *"}` 或 `{"mode": "cron_stop", "cron": "0 9 * * *", "stop_cron": "0 18 * * *"}` |
-| `retry` | 重试策略 | `{"max_attempts": 3, "delay": 60}` |
-| `enabled` | 是否启用 | `true` |
-
-### 调度模式
-
-| 模式 | 行为 |
 |------|------|
-| `once` | 手动执行（前端点"立即执行"） |
+| `task_type` | 任务类型（不传默认 `generic_steps`） |
-| `cron` | 定时启动：到 cron 时间点自动启动所有目标设备 |
+| `target` | `{"mode":"all"}` / `{"mode":"group","group_name":"A组"}` / `{"mode":"serial","serial":"100.100.10.20:5555"}` |
-| `cron_stop` | 定时启停：启动 cron 到点启动，停止 cron 到点停止本任务 worker |
+| `params` | 任务参数，与任务类默认值合并；含两个隐藏开关 `skip_offline`（默认 true）、`preempt`（默认 false） |
+| `schedule` | `{"mode":"once"}` / `{"mode":"cron","cron":"0 9 * * *"}` / `{"mode":"cron_stop","cron":...,"stop_cron":...}`，可选 `window` 运行窗口 |
+| `retry` | `{"max_attempts":1,"delay":60}` |
+| `enabled` | 是否参与调度 |
 
-**简单设置**：编辑任务时选"定时启动/定时启动+停止"后，频率用下拉选择——每天（选时间）、每小时（整点）、每隔 N 小时、每周（选星期+时间）——cron 表达式自动生成，不需要懂 cron 语法。老手可在"自定义 cron（高级）"里直接填。
+**调度模式**：`once` 仅手动；`cron` 到点启动；`cron_stop` 到点启动 + 到点停止。cron 为标准 5 段 `分 时 日 月 周`，编辑器提供"每天/每小时/每隔 N 小时/每周"的可视化选择自动生成，也可手填。
 
-cron 表达式为标准 5 段格式：`分 时 日 月 周`（如 `0 9 * * *` = 每天 9:00，`0 */2 * * *` = 每 2 小时整点，周 `0`/`7` 均为周日）
+**运行窗口**（`schedule.window`，如 `21:00-09:00`，支持跨午夜）：窗口外定时触发与手动执行都不启动。
 
-**运行窗口**：任务可勾选"启用运行窗口"，设置每天允许运行的时间段（如 `21:00-09:00` = 晚 9 点到次日早 9 点，支持跨午夜）。窗口外**定时触发和手动执行都不会启动**（手动执行会提示"当前不在运行窗口内"）。典型用法：`每小时`定时 + 窗口 `09:00-21:00`，即只在白天每小时跑一次。
+**目标解析**（`TaskJob.resolve_serials`）：`all` = 设备池 ∩ 在线（开了抢占则取全部在线池内设备）；`group` = 分组 ∩ 设备池；`serial` = 指定设备。后两者默认跳过离线设备。
-
-### 设备分组
-
-设备分组存于 SQLite，便于按批次/项目分组下发任务。一个 Job 指定 `target.mode="group"` 时，调度器展开为组内全部设备。
 
 ### 进度上报
 
-Worker 通过 `self.set_progress()` 上报通用进度字段，前端统一解析展示：
+Worker 通过 `set_progress()` 上报统一字段，前端统一渲染：
 
 ```python
-self.set_progress(done=5, total=80, unit="视频",
+self.set_progress(done=5, total=80, unit="视频", action_counts={"like": 3}, elapsed=120)
-                  action_counts={"like": 3})
 ```
 
-前端展示：进度条 + `5/80 视频` + `点赞 3` 徽章。
+前端展示为进度条 + `5/80 视频` + 计数徽章 + 运行时长。
-
----
-
-## 配置说明
-
-所有核心配置在 [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`），**7 个顶级 Tab**；「任务 / 工具 / 系统」内部还有页内子分栏（会记住上次选中位置）。
 
-单页应用（`templates/admin/monitor.html`），6 个 Tab；任务/工具 Tab 内部再有页内子分栏：
+| Tab | 内容 | 可见性 |
-
-| Tab | 功能 | 可见性 |
 |-----|------|--------|
-| 监控 | 设备状态大屏：在线/离线、型号、运行任务、当前动作、进度条、前台 App、截图、勾选批量操作（亮屏/息屏/停止）；导航栏「📺 大屏」打开全屏监控墙（/wall，缩略图+统计+时钟，挂墙/电视用） | 所有登录用户（设备操作按钮需"设备控制"权限） |
+| **监控** | 统计卡片 + 设备表（在线/型号/任务状态/进度/前台 App/最近错误，支持排序、搜索、分页、多选批量操作）+ 异常汇总 + **任务运行概况**（每张任务卡：执行任务 / 停用任务 + 覆盖设备彩色 chip）；导航栏「📺 大屏」打开 `/wall` | 所有登录用户（设备操作按钮需"设备控制"） |
-| 任务 | 子分栏：任务计划（CRUD/启用停用/立即执行/下次运行时间/**离线设备自动跳过**）、自定义动作（打包复用） | 所有登录用户可看，写操作需"任务管理"权限 |
+| **任务** | 子分栏：**任务计划**（CRUD / 启停 / 执行 / 下次运行时间 / 离线跳过 / 步骤编辑器）、**自定义动作**（步骤打包复用） | 可看；写操作需"任务管理" |
-| 分组 | 设备分组管理：创建/编辑/删除分组 | 所有登录用户可看，写操作需"任务管理"权限 |
+| **日志** | 实时日志（按文件切换、可自动刷新） | 需"日志查看" |
-| 日志 | 实时日志查看：按模块切换（core/task/web/action） | 需"日志查看"权限 |
+| **用户** | 用户 CRUD、改密、分配权限 | 仅管理员 |
-| 用户 | 用户管理：创建/删除/修改密码/分配权限 | 仅管理员 |
+| **工具** | 8 个子分栏：剪贴板注入 / adb 远程终端 / Tailscale 管理 / 应用管理 / 应用版本管理 / 设备已装应用 / **设备池管理**（含自动发现）/ 设备分组 | 仅管理员 |
-| 工具 | 子分栏：剪贴板注入、adb 远程终端（快捷命令/自动 `-s`）、**设备池管理**（新增/停用/删除/一键重连/型号采集）、**远程看屏**（MJPEG 实时流 + 点击/滑动/按键/文字）、Tailscale 管理（改名/授权/密钥不过期/设置IP/auth key）、应用管理（APK 上传安装）、应用版本管理（按包名查所有设备版本）、设备已装应用 | 仅管理员 |
+| **AI 控制台** | 会话列表 + 对话区（Markdown 渲染、推理链折叠、token 统计）+ 实时画面（MJPEG）+ 目标设备选择；右上角：经验库 / 动作库 / 模型配置 | 仅管理员 |
+| **系统** | 子分栏：数据备份（导出 zip）/ 导入恢复（上传→校验预览→应用，重启生效） | 仅管理员 |
 
-任务/工具 Tab 的子分栏会记住上次选中的位置；无权限的 tab 和按钮自动隐藏。
+### 权限模型
 
-### 用户与权限
+默认账号 `admin/admin123`（管理员，权限不受限）。权限位：
 
-默认账号 `admin` / `admin123`（管理员，拥有全部权限）。管理员可在"用户"Tab 创建普通用户并分配权限：
+| 权限位 | 键 | 覆盖 |
+|--------|----|------|
+| 任务管理 | `tasks` | 任务/分组/自定义动作的写操作 |
+| 设备控制 | `devices` | 停止设备、亮息屏、定位、清异常、前台扫描、元素抓取、步骤测试 |
+| 应用管理 | `apks` | APK 上传/安装/删除 |
+| 日志查看 | `logs` | 日志 Tab |
 
-| 权限位 | 说明 | 覆盖功能 |
-|--------|------|---------|
-| 任务管理 `tasks` | 任务/自定义动作/分组的增删改、启停、立即执行 | 任务 Tab、分组 Tab 的写操作 |
-| 设备控制 `devices` | 停止设备、释放占用、清除异常、前台扫描、元素抓取 | 监控 Tab 的设备操作按钮、步骤编辑器的"抓取元素" |
-| 应用管理 `apks` | APK 上传、安装、删除 | 应用管理/设备已装应用（当前并入工具 Tab，工具页整体仅管理员可见） |
-| 日志查看 `logs` | 日志页 | 日志 Tab |
-
-规则：
-- **管理员拥有全部权限**，不受权限位限制
 - 查看类接口（设备/任务/分组列表、状态、截图）所有登录用户可用
-- **用户管理仅管理员可用**；不能删除/取消最后一个管理员
+- 后端 `@perm_required` / `@admin_required` 拦截并返回 403；前端用 `data-perm` 属性与 `_can(perm)` 隐藏入口（**仅隐藏，安全依赖后端**）
-- 无权限的 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）
+`generic_steps` 的执行内容全在 `params.steps`（JSON 数组），由步骤编辑器产出。**没有默认步骤**——空步骤任务执行时会明确报错。
 
-自动观看抖音视频，按配置随机执行点赞操作。参数（在 `tasks/douyin/task.py` 顶部）：
+**18 种步骤**（完整参数见 [doc/TASK_DEV.md](doc/TASK_DEV.md)）：
 
-| 参数 | 默认值 | 说明 |
+| 类别 | 步骤 |
+|------|------|
+| 屏幕 | `screen_on` 亮屏 · `screen_off` 息屏 · `keep_screen` 保持亮屏 |
+| 应用与输入 | `open_app` 打开 App · `stop_app` 结束 App · `input_text` 输入文字 · `clipboard` 剪贴板注入 · `key_event` 按键 |
+| 交互 | `click` 点击元素 · `click_xy` 点击坐标 · `long_click` 长按 · `swipe` 滑动 · `swipe_until` 滑动直到元素出现 · `wait_el` 等待元素 · `wait` 等待时长 |
+| 流程 | `loop` 循环块 · `group` 动作组 · `if_el` 条件判断（元素或 **OCR 识别**） |
+
+要点：
+
+- 每一步都可有 `probability`（0-100，默认 100）决定本次是否执行
+- 容器类步骤（`loop`/`group`/`if_el`）可嵌套，**深度上限 5 层**
+- 选择器支持 `xpath` / `description` / `text` / `resourceId` / `descriptionContains` / `className`（`ocr` 仅条件判断）
+- **优先用文字/id 定位**，坐标 (`click_xy`) 是最脆的方式
+- 未知步骤类型、缺必填参数只告警跳过，不会中断任务链（排查时留意"看起来成功但没做事"）
+
+---
+
+## AI 与 MCP
+
+### AI 控制台
+
+在「AI 控制台」选一台设备，用自然语言下指令，AI 通过 MCP 工具看屏幕、点按、输入，边做边把过程流式显示出来。配置（模型 / API Key / 默认设备 / 最大步数）存在数据库 `app_meta`，不落 `.env`。
+
+自带两个"自进化记忆"：
+
+- **经验库**：任务成功后把操作套路蒸馏成配方，下次相似任务自动召回注入；每日 03:47 由 AI 巡检建议清理（删除永远需人工确认）
+- **动作库**：把成功步骤沉淀为带元素定位的命名动作（禁坐标），可复用、可编辑
+
+详细机制见 [doc/AI_CONSOLE.md](doc/AI_CONSOLE.md)。
+
+### MCP（外部 AI 接入）
+
+MCP Server 监听 `:8033`，暴露 19 个 `de_*` 工具（截屏、点击、滑动、输入、OCR、元素树、应用管理等）。写操作需 `MCP_ALLOW_WRITE=1`；设备正在跑任务时拒绝（`device_busy`）；每次调用写审计日志。
+
+```bash
+# 本机手动启动（生产容器由 scripts/start.sh 自动拉起）
+MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
+  python -m mcp_server.mcp_server
+```
+
+工具清单与接入示例见 [doc/MCP.md](doc/MCP.md)。
+
+---
+
+## 配置说明
+
+**密钥类配置统一放项目根 `.env`**（不入 git；模板见 [.env.example](.env.example)）。加载规则：逐行解析后用 `os.environ.setdefault` 注入，**真实环境变量优先**。
+
+| 配置 | 默认值 | 说明 |
 |------|--------|------|
-| `watch_count` | 80 | 观看视频数量（0=不限，靠时长停止） |
+| `WEB_SECRET_KEY` | 未配置则随机 | 会话密钥；不配则每次重启登录态失效（**生产必须固定**） |
-| `watch_min` / `watch_max` | 5.0 / 35.0 | 单视频观看时长范围（秒） |
+| `WEB_HOST` / `WEB_PORT` | `0.0.0.0` / `18050` | Web 监听（**常量，改 config.py**） |
-| `max_duration` | 0 | 最大运行时长（秒），0=不限时 |
+| `ADB_PATH` | 自动识别 `bin/adb/` | adb 二进制（常量，按平台自动选） |
-| `swipe_min` / `swipe_max` | 0.25 / 0.50 | 上滑手势时长范围（秒） |
+| `DATA_DIR` / `APK_DIR` | `data/` / `data/apks/` | 持久化目录（常量） |
-| `gap_min` / `gap_max` | 1.0 / 3.0 | 视频间隔时长范围（秒） |
+| `USB_ADB_HOST` / `USB_ADB_PORT` | `100.100.10.1` / `5037` | USB 设备所在的部署机（远程 adb server） |
-| `actions.like.enabled` | true | 是否启用点赞 |
+| `DISCOVERY_PORT` / `DISCOVERY_INTERVAL` | `5555` / `60` | 设备自动发现（网段也在工具页配置，存 `app_meta`） |
-| `actions.like.params.rate` | 0.3 | 点赞概率（0~1） |
+| `TAILSCALE_API_KEY` / `TAILSCALE_TAILNET` | 空 | Tailscale 管理功能 |
-| `actions.like.params.method` | by_element | 点赞方式：by_element(找红心) / double_click(双击) |
+| `WEB_SECRET_KEY` 之外的一切密钥 | — | 一律进 `.env`，**不要写进 config.py** |
 
-终止条件（哪个先到就停）：`watch_count` 数量到 / `max_duration` 时长到 / 手动停止。
+> **任务参数不放 config.py**——放各自 `tasks/<name>/task.py` 顶部的 `DEFAULT_PARAMS`。
 
-### 通用步骤（generic_steps）
+完整键表（含 `MCP_*` / `AGENT_*`）见 [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md) §配置速查。
-
-通过可视化步骤编辑器编排任务流程，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 份历史）：
+按模块分文件，单文件 10MB 滚动、保留 5 份：
 
-| 文件 | 模块前缀 | 内容 |
+| 文件 | 前缀 | 内容 |
-|------|---------|------|
+|------|------|------|
-| `logs/core.log` | `core.*` | adb/worker/task_manager/设备池 核心程序 |
+| `logs/core.log` | `core.*` | adb / device_worker / task_manager / 设备池 |
 | `logs/task.log` | `task.*` | 任务执行（worker 业务逻辑） |
-| `logs/web.log` | `web.*` | Web 请求/管理 |
+| `logs/web.log` | `web.*` | Web 请求与管理操作 |
-| `logs/action.log` | `action.*` | 操作执行（点赞/评论等） |
+| `logs/action.log` | `action.*` | 操作执行 |
-
-使用方式：
 
 ```python
 from core.logger import get_logger
-log = get_logger("task.douyin")    # 写入 task.log
+log = get_logger("task.generic")   # → logs/task.log
-log.info(f"[{self.serial}] 开始任务")
 ```
 
-Web 后台"日志"Tab 可实时查看各模块日志。
+「日志」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 动态端口范围：
+| 端口被占用（WinError 10013/10048） | 启动会自动回退候选端口（`18050` → `127.0.0.1:18050` → `127.0.0.1:18051..18055`）；仍失败则改 `WEB_PORT`（注意 Windows 动态端口排除段） |
-
+| 设备显示离线 | 「工具 → 设备池管理」一键重连；确认设备在线且同一网络（生产走 Tailscale 同 tailnet） |
-```bash
+| 新加的设备不被调度 | 必须**加入设备池**（仅 adb 连上不算）；确认该设备为"启用"状态 |
-netsh interface ipv4 show excludedportrange protocol=tcp
+| `u2.connect` 卡死 | 基类有 30s 超时保护；频繁超时说明 atx-agent 异常，重启设备或重新推送 |
-```
+| 任务运行中被看门狗标记卡死 | 看门狗 120s 无心跳即判定；长循环内需周期性 `self.heartbeat()` |
-
+| 任务"成功"但什么都没做 | 步骤类型未知/缺必填参数会被**告警跳过**；查 `logs/task.log` 的 WARNING |
-修改 `config.py` 中的 `WEB_PORT` 到一个不在排除范围内的端口。
+| 中文输入失败 | u2 默认 IME 不支持中文，需 `set_fastinput_ime(True)`（`input_text` 步骤已处理） |
-
+| 改了 `core/` 不生效 | 服务以 `debug=False` 运行、不热重载；**必须重启**。前端改动还需强刷浏览器（Ctrl+Shift+R） |
-### 设备显示离线
+| 元素抓取按钮不可用 | 依赖本机 uiautodev（:20242），`web_server.py` 启动时自动拉起；未安装时 `pip install uiautodev` |
-
-先确认本机 `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/README.md](doc/README.md)**（文档地图、阅读路径、维护约定）
 
 | 文档 | 内容 |
 |------|------|
-| [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md) | **开发手册**：开发流程、git 工作流、技术红线、环境、本地开发 |
+| [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) | 架构详解（分层、装配顺序、线程模型、设备生命周期、调度链路、设计决策） |
-| [doc/TASK_DEV.md](doc/TASK_DEV.md) | 任务开发指南（新增 App 任务的完整模板和规范） |
+| [doc/DATA_MODEL.md](doc/DATA_MODEL.md) | 数据模型（表结构、迁移、`app_meta`、数据目录、备份覆盖清单） |
-| [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) | 架构详解（分层设计、数据流、关键设计决策） |
+| [doc/API.md](doc/API.md) | HTTP 接口全量说明 |
-| [doc/DEPLOY.md](doc/DEPLOY.md) | 部署指南（环境准备、设备池配置、生产部署） |
+| [doc/TASK_DEV.md](doc/TASK_DEV.md) | 任务与步骤开发（18 种步骤、选择器、自定义动作、新增任务类型） |
-| [doc/STF_REMOVAL.md](doc/STF_REMOVAL.md) | STF 摘除迁移记录（阶段 0-3 已完成，含多实例锁方案） |
+| [doc/MCP.md](doc/MCP.md) · [doc/MCP_DESIGN.md](doc/MCP_DESIGN.md) | MCP 使用手册 / 设计文档 |
-| [doc/API.md](doc/API.md) | API 接口文档（全部 HTTP 接口说明） |
+| [doc/AI_CONSOLE.md](doc/AI_CONSOLE.md) · [doc/AI_TASK_GEN.md](doc/AI_TASK_GEN.md) | AI 控制台机制 / AI 建任务设计（规划） |
+| [doc/DEPLOY.md](doc/DEPLOY.md) | 部署与运维（含生产容器、备份导入、故障排查） |
+| [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md) | 开发手册（git 流程、技术红线、本地开发、文档同步约定） |
+| [doc/STF_REMOVAL.md](doc/STF_REMOVAL.md) | 摘除 OpenSTF 的历史记录 |
 
-> **注意**：所有 git 操作（含 push 到 dev）都需负责人确认后才能执行，详见开发手册。修改 `core/`、`tasks/`、`templates/` 后需重启服务/强刷浏览器才生效。
+> ⚠️ **改动必须同步文档**：功能/配置/接口/表结构的任何增删改，都要在同一个 commit 里更新对应文档（红线，详见 [doc/README.md](doc/README.md) §3）。
+> ⚠️ **git 操作需负责人确认**（含 push 到 dev），详见 [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md)。
 
 ---
 
@@ -458,10 +398,10 @@ finally:
 
 | 组件 | 用途 |
 |------|------|
-| Flask + Flask-Login | Web 后台 + 用户认证 |
+| Flask + Flask-Login + Flask-SQLAlchemy | Web 后台 / 认证 / SQLite ORM |
-| Flask-SQLAlchemy | SQLite 数据持久化 |
+| APScheduler | 定时任务调度（任务 + 经验巡检两个独立调度器） |
-| APScheduler | 定时任务调度 |
+| uiautomator2 / uiautodev | Android UI 自动化 / 元素抓取 |
-| uiautomator2 | Android UI 自动化 |
+| rapidocr_onnxruntime (+ opencv-headless) | 屏幕 OCR |
-| uiautodev | UI 元素抓取（步骤编辑器"抓取元素"） |
 | pyaxmlparser | APK 元信息解析 |
-| 自建设备池 | 设备清单/在线状态/型号（SQLite + adb） |
+| fastmcp | MCP Server（Streamable HTTP）+ AI 控制台 Agent |
+| adb（项目自带 `bin/adb/`） | 设备连接与底层操作 |

config.py

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

core/__init__.py

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

core/actions/__init__.py

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

core/actions/base.py

@@ -3,11 +3,11 @@
 设计要点：
   1. BaseAction 定义统一接口：execute(d, params, worker) -> bool
   2. 每个 app 任务有自己的注册表（create_action_registry），
-     互不污染——抖音的 like 和快手的 like 各注册各的。
+     互不污染——A 应用的 like 和 B 应用的 like 各注册各的。
   3. 概率触发、状态上报等通用逻辑放这里，子类不重复写。
   4. ActionContext 封装执行上下文，方便扩展（传 d/worker/进度/计数器）。
 
-新增 app 专属操作步骤（照着 tasks/douyin/actions/like.py 抄）：
+新增 app 专属操作步骤（在 tasks/<app>/actions/ 下新建，参考该包已有实现）：
 
   1. 在 tasks/<app>/actions/ 下新建 my_action.py
   2. 写一个 BaseAction 子类，用 @register_action 装饰，实现 execute：

core/apk_manager.py

@@ -127,7 +127,7 @@ class ApkManager:
 
     # ================== 列表 ==================
     def list_all(self):
-        """列出所有 APK。"""
+        """列出所有 APK（**每个上传版本一行**，内部用）。"""
         try:
             with self._db():
                 rows = ApkRow.query.order_by(ApkRow.upload_time.desc()).all()
@@ -136,6 +136,42 @@ class ApkManager:
             _log.error(f"列出 APK 失败: {e}")
             return []
 
+    def list_latest(self):
+        """按**包名**合并后的列表：一个应用一行，只显示最新版本。
+
+        为什么：同一个应用传过多个版本（v1.2 / v1.3）时，列表里会并排出现两行——
+        用户看到的是"同一个应用怎么重复了"。这里合并成一行（最新版），
+        其余版本的信息放在 `versions` 里，界面可以提示"另有 N 个旧版本"并按需清理。
+
+        管理页和设备端商店都用这个（设备上选应用时同样不该出现两行同一个 App）。
+        解析不出包名的 APK 各自独立成行，不做合并（避免把无关文件混在一起）。
+        """
+        rows = self.list_all()
+        groups = {}
+        for r in rows:
+            pkg = (r.get("package_name") or "").strip()
+            key = pkg if pkg else ("__single__" + str(r.get("id")))
+            groups.setdefault(key, []).append(r)
+
+        def sort_key(x):
+            return (x.get("version_code") or 0, x.get("upload_time") or "")
+
+        out = []
+        for items in groups.values():
+            items.sort(key=sort_key, reverse=True)
+            top = dict(items[0])
+            top["version_count"] = len(items)
+            top["versions"] = [{
+                "id": i.get("id"),
+                "version_name": i.get("version_name") or "",
+                "version_code": i.get("version_code") or 0,
+                "size": i.get("size") or 0,
+                "upload_time": i.get("upload_time") or "",
+            } for i in items]
+            out.append(top)
+        out.sort(key=lambda x: x.get("upload_time") or "", reverse=True)
+        return out
+
     # ================== 删除 ==================
     def delete(self, apk_id):
         """删除 APK 文件和数据库记录。"""
@@ -161,6 +197,47 @@ class ApkManager:
             _log.error(f"删除 APK 失败: {e}")
             return False, str(e)
 
+    def delete_package(self, apk_id, keep_latest=False):
+        """按**包名**删除：一个应用的所有版本一起处理。
+
+        keep_latest=True → 只删旧版本、保留最新那版（"清理旧版本"）
+        keep_latest=False → 整个应用删掉（所有版本）
+        没有包名的 APK 退回单条删除。
+        """
+        try:
+            with self._db():
+                row = ApkRow.query.get(apk_id)
+                if not row:
+                    return False, "APK 不存在"
+                pkg = (row.package_name or "").strip()
+                if not pkg:
+                    return self.delete(apk_id)
+
+                items = ApkRow.query.filter_by(package_name=pkg).all()
+                items.sort(key=lambda r: ((r.version_code or 0),
+                                          (r.upload_time or "")), reverse=True)
+                targets = items[1:] if keep_latest else items
+                if not targets:
+                    return True, "没有需要清理的旧版本"
+                name = row.display_name or pkg
+                for r in targets:
+                    p = os.path.join(APK_DIR, r.filename)
+                    if os.path.exists(p):
+                        try:
+                            os.remove(p)
+                        except Exception as e:
+                            _log.warning(f"删除 APK 文件失败: {e}")
+                    db.session.delete(r)
+                db.session.commit()
+                _log.info(f"已删除 {name} 的 {len(targets)} 个版本"
+                          f"（{'保留最新' if keep_latest else '整个应用'}）")
+                if keep_latest:
+                    return True, f"已清理 {name} 的 {len(targets)} 个旧版本（保留最新）"
+                return True, f"已删除 {name}（共 {len(targets)} 个版本）"
+        except Exception as e:
+            _log.error(f"按包名删除失败: {e}")
+            return False, str(e)
+
     # ================== 批量安装 ==================
     def install(self, apk_id, serials):
         """批量安装 APK 到指定设备（后台线程执行）。
@@ -198,13 +275,26 @@ class ApkManager:
         # 获取 worker 状态（判断设备是否运行中）
         worker_status = {w["serial"]: w for w in get_all_worker_status()}
 
+        # 设备名（平台给设备起的名字，如 A08）—— 进度表里显示这个而不是型号：
+        # 8 台同型号时型号根本区分不了，名字才行
+        pool_names, fp_names = {}, {}
+        try:
+            from core import device_pool
+            # list_devices() 返回字典（含 name/fingerprint）
+            for d in device_pool.list_devices():
+                if d.get("serial"):
+                    pool_names[d["serial"]] = d.get("name") or ""
+                # USB 设备的 adb serial == ro.serialno == 池里那条记录的指纹
+                if d.get("fingerprint"):
+                    fp_names[d["fingerprint"]] = d.get("name") or ""
+        except Exception as e:
+            _log.warning(f"读取设备名失败（进度表将显示地址）: {e}")
+
         # 构造安装任务
         items = {}
         for s in serials:
-            dev = all_devices.get(s, {})
-            model = dev.get("model") or dev.get("manufacturer") or s
             items[s] = {
-                "name": model,
+                "name": pool_names.get(s) or fp_names.get(s) or s,
                 "status": "pending",
                 "msg": "",
             }
@@ -308,20 +398,17 @@ class ApkManager:
                      "verifier_verify_adb_installs", "0")
             except Exception:
                 pass
-            # 2. 推送 APK 到设备（大 APK 经 WiFi 推送较慢，超时与安装共用）
+            # 2. 推送 APK 到设备（分块 + 实时进度）
-            self._set_item(serial, "installing", "正在推送 APK...")
+            ok_push, msg_push = self._push_with_progress(serial, apk_path)
-            r = subprocess.run(
+            if not ok_push:
-                [ADB_PATH, "-s", serial, "push", apk_path, "/data/local/tmp/_install.apk"],
+                self._set_item(serial, "failed", msg_push)
-                capture_output=True, timeout=_INSTALL_TIMEOUT
+                _log.warning(f"[{serial}] APK 推送失败: {msg_push}")
-            )
-            push_out = ((r.stdout or b"") + (r.stderr or b"")).decode("utf-8", errors="replace")
-            if r.returncode != 0 or "1 file pushed" not in push_out:
-                msg = push_out.strip().replace("\n", " ")[:150] or f"推送失败(returncode={r.returncode})"
-                self._set_item(serial, "failed", msg)
-                _log.warning(f"[{serial}] APK 推送失败: {msg}")
                 return
             # 3. pm install 强制安装（-r 覆盖安装 / -t 允许测试包 / -d 允许降级版本）
-            self._set_item(serial, "installing", "正在安装...")
+            # 这一步在**设备端**解包/优化，耗时随包大小增长（抖音 336MB 实测 ~65s），
+            # 但系统没给进度接口，只能给出预期时间，别让用户以为是卡住了。
+            self._set_item(serial, "installing",
+                           "正在设备上安装...（大包要 1-2 分钟，无进度可读）")
             r = subprocess.run(
                 [ADB_PATH, "-s", serial, "shell", "pm", "install", "-r", "-t", "-d",
                  "/data/local/tmp/_install.apk"],
@@ -385,6 +472,101 @@ class ApkManager:
             # adb 连接保持即可，不影响设备和后续操作。
             pass
 
+    def _push_with_progress(self, serial, apk_path,
+                            remote="/data/local/tmp/_install.apk"):
+        """把 APK 分块写进设备，边传边更新进度。返回 (ok, msg)。
+
+        为什么不用 `adb push`：它只在**结束时**吐一行汇总
+        （"1 file pushed, 3.0 MB/s"），大包（抖音 336MB ≈ 1.8 分钟/台）整个传输过程
+        界面上只有一句"正在推送 APK..."，用户只能干等 —— 这就是要优化的问题。
+
+        改用 `exec-in` 分块写：每块回调一次进度（百分比/已传/速度/剩余时间）。
+        实测速度略降（2.6 vs 3.1 MB/s），换来看得见的进度，划算。
+        传完校验设备上的文件大小；exec-in 不可用时退回原来的 `adb push`。
+        """
+        total = os.path.getsize(apk_path)
+        chunk = 1 << 20            # 1MB：再大提升有限，再小 adb 调用开销明显
+        t0 = time.time()
+        sent = 0
+        last_report = 0.0
+        try:
+            proc = subprocess.Popen(
+                [ADB_PATH, "-s", serial, "exec-in", "cat > %s" % remote],
+                stdin=subprocess.PIPE, stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE)
+        except Exception as e:
+            _log.warning(f"[{serial}] exec-in 启动失败，退回 adb push: {e}")
+            return self._push_fallback(serial, apk_path, remote)
+
+        try:
+            with open(apk_path, "rb") as f:
+                while True:
+                    buf = f.read(chunk)
+                    if not buf:
+                        break
+                    proc.stdin.write(buf)
+                    sent += len(buf)
+                    now = time.time()
+                    if now - last_report >= 0.8 or sent >= total:
+                        last_report = now
+                        spent = max(now - t0, 0.001)
+                        speed = sent / spent / 1048576.0          # MB/s
+                        left = int((total - sent) / max(sent / spent, 1))
+                        self._set_item(
+                            serial, "installing",
+                            "推送中 %d%%（%.1f/%.1f MB · %.1f MB/s · 剩约 %ds）"
+                            % (sent * 100 // max(total, 1), sent / 1048576.0,
+                               total / 1048576.0, speed, left))
+            proc.stdin.close()
+        except Exception as e:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+            return False, f"推送中断: {e}"
+
+        try:
+            rc = proc.wait(timeout=_INSTALL_TIMEOUT)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            return False, "推送超时（设备无响应）"
+        if rc != 0:
+            err = ""
+            try:
+                err = (proc.stderr.read() or b"").decode("utf-8", "replace")[:150]
+            except Exception:
+                pass
+            _log.warning(f"[{serial}] exec-in 推送到一半失败(rc={rc})，退回 adb push")
+            return self._push_fallback(serial, apk_path, remote)
+
+        # 校验设备上文件大小一致（exec-in 中途断流可能"成功"但少字节）
+        try:
+            rs = subprocess.run(
+                [ADB_PATH, "-s", serial, "shell", "stat", "-c", "%s", remote],
+                capture_output=True, timeout=30)
+            got = int((rs.stdout or b"").decode("utf-8", "replace").strip().splitlines()[-1])
+            if got != total:
+                return False, f"推送不完整（设备 {got} / 本地 {total} 字节）"
+        except Exception:
+            pass          # stat 参数各机型有差异，取不到就跳过校验
+
+        return True, "推送完成 %.1fMB / %.0fs" % (total / 1048576.0, time.time() - t0)
+
+    def _push_fallback(self, serial, apk_path, remote):
+        """老 adb 或 exec-in 失败时的退路：原来的 `adb push`（无进度）。"""
+        self._set_item(serial, "installing", "正在推送 APK...（无进度显示）")
+        try:
+            r = subprocess.run(
+                [ADB_PATH, "-s", serial, "push", apk_path, remote],
+                capture_output=True, timeout=_INSTALL_TIMEOUT)
+        except subprocess.TimeoutExpired:
+            return False, "推送超时"
+        out = ((r.stdout or b"") + (r.stderr or b"")).decode("utf-8", errors="replace")
+        if r.returncode != 0 or "1 file pushed" not in out:
+            return False, (out.strip().replace("\n", " ")[:150]
+                           or f"推送失败(returncode={r.returncode})")
+        return True, "推送完成(adb push)"
+
     def _set_item(self, serial, status, msg=""):
         """更新安装任务中某设备的状态。"""
         if not self._install_task:

core/db_config.py

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

core/device_discovery.py

@@ -31,6 +31,8 @@ _K_ENABLED = "discovery_enabled"
 _K_SUBNETS = "discovery_subnets"
 _K_INTERVAL = "discovery_interval"
 _K_PORT = "discovery_port"
+# 指纹匹配时是否自动认领（默认关：认领会改写分组/任务引用，默认交人工确认）
+_K_AUTO_CLAIM = "discovery_auto_claim"
 
 # 单网段主机数上限（防误配 /8 之类），超过截断并告警
 _MAX_HOSTS_PER_SUBNET = 1024
@@ -59,9 +61,10 @@ def _fmt(ts=None):
 def get_settings():
     """读发现配置（app_meta，缺键用 config 默认值补齐）。"""
     with _ctx():
+        from core.db_config import meta_get
+
         def _get(key, default):
-            v = db.session.execute(
+            v = meta_get(key)
-                db.text("SELECT value FROM app_meta WHERE key=:k"), {"k": key}).scalar()
             return v if v is not None else default
         try:
             subnets = json.loads(_get(_K_SUBNETS, "[]")) or DISCOVERY_SUBNETS
@@ -72,10 +75,11 @@ def get_settings():
             "subnets": subnets,
             "interval": int(_get(_K_INTERVAL, str(DISCOVERY_INTERVAL)) or DISCOVERY_INTERVAL),
             "port": int(_get(_K_PORT, str(DISCOVERY_PORT)) or DISCOVERY_PORT),
+            "auto_claim": _get(_K_AUTO_CLAIM, "0") == "1",   # 默认关
         }
 
 
-def save_settings(enabled=None, subnets=None, interval=None, port=None):
+def save_settings(enabled=None, subnets=None, interval=None, port=None, auto_claim=None):
     """写发现配置（部分字段更新）。subnets 逐项校验 CIDR，非法返回 (False, 原因)。"""
     if subnets is not None:
         clean = []
@@ -97,10 +101,8 @@ def save_settings(enabled=None, subnets=None, interval=None, port=None):
     except (TypeError, ValueError):
         return False, "参数不合法"
     with _ctx():
-        def _put(key, value):
+        from core.db_config import meta_set
-            db.session.execute(
+        _put = meta_set   # 方言中立 upsert（app_meta.key 在 MySQL 里是保留字）
-                db.text("INSERT OR REPLACE INTO app_meta(key,value) VALUES(:k,:v)"),
-                {"k": key, "v": str(value)})
         if enabled is not None:
             _put(_K_ENABLED, "1" if enabled else "0")
         if subnets is not None:
@@ -109,6 +111,8 @@ def save_settings(enabled=None, subnets=None, interval=None, port=None):
             _put(_K_INTERVAL, str(int(interval)))
         if port is not None:
             _put(_K_PORT, str(int(port)))
+        if auto_claim is not None:
+            _put(_K_AUTO_CLAIM, "1" if auto_claim else "0")
         db.session.commit()
     return True, "已保存"
 
@@ -196,6 +200,35 @@ def _parse_adb_devices(out):
     return devices
 
 
+# ================== 自动认领（可选） ==================
+def _auto_claim(fps):
+    """指纹命中池中已有设备 → 自动认领：迁移记录到新地址并同步分组/任务引用。
+
+    仅在设置 discovery_auto_claim 打开时由扫描线程调用（默认关）。
+    返回 [(old_serial, new_serial, name), ...]。
+    """
+    from core import device_pool
+    done = []
+    for serial, fp in (fps or {}).items():
+        if not fp:
+            continue
+        try:
+            info = device_pool.find_by_fingerprint(fp)
+            if not info or info.get("serial") == serial:
+                continue          # 没匹配到，或本来就是这条（无需迁移）
+            old, name = device_pool.claim_device(serial, fp)
+            if not old:
+                continue
+            PendingDevice.query.filter_by(serial=serial).delete()
+            db.session.commit()
+            done.append((old, serial, name or info.get("name") or ""))
+            _log.info(f"自动认领: 『{name or info.get('name') or old}』{old} → {serial}")
+        except Exception as e:
+            db.session.rollback()
+            _log.warning(f"自动认领 {serial} 失败: {e}")
+    return done
+
+
 # ================== 扫描 ==================
 def scan_once(manual=False):
     """执行一轮扫描。返回 (ok, result_dict)；后台线程/API 调用。"""
@@ -228,20 +261,33 @@ def scan_once(manual=False):
             # 4. state==device 过滤（排除 unauthorized/offline）
             verified = _parse_adb_devices(_adb("devices")) & candidates
 
-            # 5. 写 pending：新 → 插入；已有 → 更新 last_seen
+            # 5. 写 pending：新 → 插入；已有 → 更新 last_seen（顺带刷新指纹）
+            #    指纹用于认出"这台其实是设备池里某台设备换了 IP"，见 list_pending 的 match
             now = _fmt()
             existing = {p.serial for p in PendingDevice.query.all()}
             added = 0
+            from core import device_pool
+            fps = {}
             for serial in verified:
                 source = "tailscale" if serial.split(":")[0].startswith("100.") else "lan"
+                try:
+                    fp = device_pool.read_fingerprint(serial, timeout=4)
+                except Exception:
+                    fp = ""
+                fps[serial] = fp
                 if serial in existing:
                     PendingDevice.query.filter_by(serial=serial).update(
-                        {"last_seen": now})
+                        {"last_seen": now, "fingerprint": fp})
                 else:
                     db.session.add(PendingDevice(serial=serial, source=source,
-                                                 first_seen=now, last_seen=now))
+                                                 first_seen=now, last_seen=now,
+                                                 fingerprint=fp))
                     added += 1
             db.session.commit()
+            # 5.5 自动认领（可选，默认关）：指纹命中池中已有设备 → 直接把记录迁到新地址。
+            #     默认关是因为认领会改写分组/任务引用（数据结构变动），交人工点一下更稳妥；
+            #     打开后零点击完成，见 doc/API.md §6。
+            claimed = _auto_claim(fps) if settings.get("auto_claim") else []
             # 6. 正式池断联设备自动重连：adb connect 会因 WiFi 波动/设备重启/
             #    adb 服务重启而断开——扫描线程每轮顺带重试（幂等轻量，内部
             #    全局锁串行），连上即恢复在线，无需人工干预。pending 池是给
@@ -249,10 +295,13 @@ def scan_once(manual=False):
             back = _reconnect_offline(configured)
             _log.info(f"发现: 探测开放 {len(open_ips)} 台，可连 {len(verified)} 台，"
                       f"新增待连接 {added} 台"
-                      + (f"，自动重连恢复 {len(back)} 台 {back}" if back else ""))
+                      + (f"，自动重连恢复 {len(back)} 台 {back}" if back else "")
+                      + (f"，自动认领 {len(claimed)} 台 {[c[0] + '→' + c[1] for c in claimed]}"
+                         if claimed else ""))
         _last_scan = (now, len(open_ips), len(verified), added)
         _last_error = ""
-        return True, {"found": len(open_ips), "verified": len(verified), "new": added}
+        return True, {"found": len(open_ips), "verified": len(verified),
+                      "new": added, "claimed": len(claimed)}
     except Exception as e:
         _log.warning(f"发现扫描异常: {e}")
         _last_error = str(e)[:200]
@@ -352,6 +401,7 @@ def get_status():
         "subnets": settings["subnets"],
         "interval": settings["interval"],
         "port": settings["port"],
+        "auto_claim": settings["auto_claim"],
         "scanning": _scanning,
         "last_scan": _last_scan[0] if _last_scan else "",
         "last_result": ({"found": _last_scan[1], "verified": _last_scan[2],
@@ -371,20 +421,47 @@ def list_pending():
     with _ctx():
         rows = [p.to_dict() for p in PendingDevice.query.order_by(
             PendingDevice.first_seen.desc()).all()]
-    return [dict(r, online=True) for r in rows if r["serial"] in online]
+    out = []
+    for r in rows:
+        if r["serial"] not in online:
+            continue
+        r["online"] = True
+        # 指纹匹配：这台其实就是设备池里某台设备换了地址（前端据此提示"认领"）
+        r["match"] = None
+        if r.get("fingerprint"):
+            try:
+                from core import device_pool
+                m = device_pool.find_by_fingerprint(r["fingerprint"])
+                if m and m["serial"] != r["serial"]:
+                    r["match"] = {"serial": m["serial"], "name": m.get("name") or ""}
+            except Exception:
+                pass
+        out.append(r)
+    return out
 
 
-def confirm_pending(serial, name=""):
+def confirm_pending(serial, name="", fingerprint=""):
     """确认连接：pending 行 → 正式设备池（add_device upsert）→ 删 pending。
 
-    返回 (ok, msg, is_new)。adb_connect + 采型号由 API 层后台线程做。
+    先按指纹尝试**认领**：同一台物理设备换了地址时，把池中旧记录迁到新 serial，
+    并同步分组/任务里的引用（名称等信息全部保留），而不是新增一条。
+
+    返回 (ok, msg, is_new)。adb_connect + 采型号/指纹由调用方（API 层后台线程）做。
     """
     with _ctx():
         row = PendingDevice.query.get(serial)
         if not row:
             return False, "设备不在待连接列表", False
         from core import device_pool
-        is_new = device_pool.add_device(serial, name=name or "")
+        fp = (fingerprint or row.fingerprint or "").strip()
+        claimed_old, claimed_name = device_pool.claim_device(serial, fp)
+        if claimed_old:
+            device_pool.add_device(serial, name=claimed_name or name, fingerprint=fp)
+            PendingDevice.query.filter_by(serial=serial).delete()
+            db.session.commit()
+            return True, (f"已认领为『{claimed_name or claimed_old}』"
+                          f"（原地址 {claimed_old}，分组/任务的引用已同步）"), False
+        is_new = device_pool.add_device(serial, name=name or "", fingerprint=fp)
         PendingDevice.query.filter_by(serial=serial).delete()
         db.session.commit()
     return True, "已加入设备池" + ("" if is_new else "（已存在，信息已更新）"), is_new

core/device_pool.py

@@ -22,6 +22,16 @@ from core.models import db, Device
 _log = get_logger("core.device_pool")
 
 _app = None
+# 设备换地址（认领/迁址）后的回调：(old_serial, new_serial) -> None
+# 由 web_server 装配时注册为 TaskManager.sync_device_serial——
+# 分组/任务的内存副本在 TaskManager 里，只改库不改内存不生效（见 _move_device_row）
+_move_hook = None
+
+
+def set_move_hook(fn):
+    """注册"设备换地址"回调（web_server 创建完 TaskManager 后调用）。"""
+    global _move_hook
+    _move_hook = fn
 
 
 def init_app(app):
@@ -109,8 +119,131 @@ def list_ready():
     return [s for s in list_configured() if s in online]
 
 
+# ================== 设备指纹（识别"同一台物理设备"） ==================
+def read_fingerprint(serial, timeout=6):
+    """读取设备指纹（ro.serialno）——设备换 IP 后据此认领回原记录。
+
+    只对网络设备（serial 含 ":"）读取：USB 设备的 serial 本身就是稳定序列号，
+    不存在"换地址"问题。采集失败返回空串（静默，不影响主流程）。
+    """
+    serial = (serial or "").strip()
+    if not serial or ":" not in serial:
+        return ""
+    # 部分机型 ro.serialno 为空，退回 ro.boot.serialno
+    for prop in ("ro.serialno", "ro.boot.serialno"):
+        try:
+            r = subprocess.run([ADB_PATH, "-s", serial, "shell", "getprop", prop],
+                               capture_output=True, timeout=timeout)
+            fp = (r.stdout or b"").decode("utf-8", errors="replace").strip()
+        except Exception:
+            continue
+        if fp and fp.isprintable():
+            return fp
+    return ""
+
+
+def find_by_fingerprint(fingerprint, exclude_serial=""):
+    """按指纹查池中设备（返回 dict 或 None），可排除指定 serial。"""
+    fingerprint = (fingerprint or "").strip()
+    if not fingerprint:
+        return None
+    with _ctx():
+        row = Device.query.filter(Device.fingerprint == fingerprint).first()
+        if not row or row.serial == exclude_serial:
+            return None
+        return row.to_dict()
+
+
+def name_taken(name, exclude_serial=""):
+    """名称是否已被其它设备占用（唯一约束的应用层检查，给友好提示用）。"""
+    name = (name or "").strip()
+    if not name:
+        return False
+    with _ctx():
+        q = Device.query.filter(Device.name == name)
+        if exclude_serial:
+            q = q.filter(Device.serial != exclude_serial)
+        return q.first() is not None
+
+
+def _move_device_row(old, new_serial, fingerprint=""):
+    """把 old 记录迁到 new_serial（调用方持 app context）。
+
+    只动 device 表本身；**分组/任务引用的同步交给上层**（见 set_move_hook）：
+    分组与任务在 TaskManager 里还有一份内存副本，调度用的是内存对象——
+    只改库不改内存，不重启不生效。而 device_pool 不能反向依赖 task_manager
+    （会造成循环 import），所以用回调把这件事交给装配层。
+    """
+    old_serial, name = old.serial, (old.name or "")
+    # 新地址上若已有记录（重复添加等），以"被认领的旧记录"为准，删掉它
+    dup = Device.query.get(new_serial)
+    if dup is not None and dup.serial != old.serial:
+        db.session.delete(dup)
+    old.serial = new_serial
+    if fingerprint:
+        old.fingerprint = fingerprint
+    db.session.commit()
+    if _move_hook is not None:
+        try:
+            _move_hook(old_serial, new_serial)
+        except Exception as e:
+            _log.warning(f"设备迁址后同步分组/任务引用失败: {e}")
+    return old_serial, name
+
+
+def claim_device(new_serial, fingerprint):
+    """认领：同一台物理设备换了地址，把池中旧记录迁到新 serial 并同步所有引用。
+
+    做三件事（一个事务内）：
+      1. 把旧记录的 serial 改成新地址（名称/型号/备注/启用状态/添加时间全部保留）
+      2. 同步 device_group.serials 里的旧 serial → 新 serial（否则分组吊着死 IP）
+      3. 同步 task_job.target.serial（指定设备模式的任务目标）
+
+    返回 (old_serial, name)；没有匹配到旧记录时返回 (None, "")。
+    """
+    fingerprint = (fingerprint or "").strip()
+    new_serial = (new_serial or "").strip()
+    if not fingerprint or not new_serial:
+        return None, ""
+    with _ctx():
+        old = Device.query.filter(Device.fingerprint == fingerprint,
+                                  Device.serial != new_serial).first()
+        if not old:
+            return None, ""
+        old_serial, name = _move_device_row(old, new_serial)
+        _log.info(f"设备认领: 指纹 {fingerprint} 的『{name or old_serial}』"
+                  f"由 {old_serial} 迁到 {new_serial}")
+        return old_serial, name
+
+
+def relocate_device(old_serial, new_serial, fingerprint=""):
+    """人工认领：把池中 old_serial 的记录改到 new_serial（换地址的手工兜底）。
+
+    用在"设备已经断联、读不到指纹"的场景：设备换了 IP 后旧地址连不上，
+    指纹也没采过，自动认领无从匹配——此时由人工指认"这条就是那台，
+    现在在 X"，本函数负责迁移并同步分组/任务引用。
+
+    返回 (ok, name, msg)。
+    """
+    old_serial = (old_serial or "").strip()
+    new_serial = (new_serial or "").strip()
+    if not old_serial or not new_serial:
+        return False, "", "缺少参数"
+    if old_serial == new_serial:
+        return False, "", "新旧地址相同，无需迁移"
+    with _ctx():
+        old = Device.query.get(old_serial)
+        if not old:
+            return False, "", f"设备池中没有 {old_serial}"
+        if Device.query.get(new_serial) is not None:
+            return False, "", f"{new_serial} 已在设备池中，请先处理那条记录"
+        _, name = _move_device_row(old, new_serial, fingerprint)
+        _log.info(f"设备人工认领: 『{name or old_serial}』{old_serial} → {new_serial}")
+        return True, name, f"『{name or old_serial}』已迁到 {new_serial}，分组/任务引用已同步"
+
+
 # ================== 管理（CRUD） ==================
-def add_device(serial, name="", note="", enabled=True):
+def add_device(serial, name="", note="", enabled=True, fingerprint=""):
     """添加/更新设备（upsert）。返回 True 新增 / False 已存在并更新。"""
     serial = (serial or "").strip()
     if not serial:
@@ -119,16 +252,47 @@ def add_device(serial, name="", note="", enabled=True):
         d = Device.query.get(serial)
         if d:
             d.name, d.note, d.enabled = name or "", note or "", enabled
+            if fingerprint:
+                d.fingerprint = fingerprint
             db.session.commit()
             return False
         db.session.add(Device(serial=serial, name=name or "", note=note or "",
-                              enabled=enabled,
+                              enabled=enabled, fingerprint=fingerprint or "",
                               created_at=time.strftime("%Y-%m-%d %H:%M")))
         db.session.commit()
         _log.info(f"设备池新增设备: {serial}")
         return True
 
 
+def rename_device(serial, name):
+    """重命名设备（唯一性由调用方先校验）。返回是否成功。"""
+    name = (name or "").strip()
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d or not name or (d.name or "") == name:
+            return False
+        old = d.name or ""
+        d.name = name
+        db.session.commit()
+        _log.info(f"设备池重命名: {old or serial} → {name}（{serial}）")
+        return True
+
+
+def set_fingerprint(serial, fingerprint):
+    """补写设备指纹（认领需要；采集是后来才做的）。"""
+    fingerprint = (fingerprint or "").strip()
+    if not fingerprint:
+        return False
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d or d.fingerprint == fingerprint:
+            return False
+        d.fingerprint = fingerprint
+        db.session.commit()
+        _log.info(f"设备池采集指纹: {serial} -> {fingerprint}")
+        return True
+
+
 def remove_device(serial):
     """删除设备。返回是否删除成功。"""
     with _ctx():
@@ -194,18 +358,45 @@ def refresh_model(serial, timeout=8):
     return model
 
 
+def refresh_fingerprint(serial, timeout=6):
+    """读取并写回设备指纹，返回指纹（失败返回空串）。"""
+    fp = read_fingerprint(serial, timeout=timeout)
+    if fp:
+        set_fingerprint(serial, fp)
+    return fp
+
+
+def refresh_info(serial):
+    """采集一台设备的型号 + 指纹（指纹缺失时才读，避免每次启动都白跑一次 adb）。
+
+    返回 (model, fingerprint)。任一失败都静默——设备池展示用，不影响主流程。
+    """
+    model = refresh_model(serial)
+    fp = ""
+    with _ctx():
+        row = Device.query.get(serial)
+        fp = (row.fingerprint or "") if row else ""
+    if not fp:
+        fp = refresh_fingerprint(serial)
+    return model, fp
+
+
 def refresh_all_models():
-    """批量采集池内在线设备的型号（并发 10，后台线程调用）。返回成功数。"""
+    """批量采集池内在线设备的型号（顺带补齐缺失的设备指纹），并发 10，后台线程调用。
+
+    返回成功数。指纹补齐很重要：老库里的设备没有指纹，补上之后换 IP 才能被认领。
+    """
     serials = list_online()
     if not serials:
         return 0
     from concurrent.futures import ThreadPoolExecutor, as_completed
     ok = 0
     with ThreadPoolExecutor(max_workers=min(10, len(serials))) as pool:
-        futures = {pool.submit(refresh_model, s): s for s in serials}
+        futures = {pool.submit(refresh_info, s): s for s in serials}
         for fut in as_completed(futures):
             try:
-                if fut.result():
+                model, _fp = fut.result()
+                if model:
                     ok += 1
             except Exception:
                 pass

core/logger.py

@@ -41,7 +41,7 @@ def get_logger(name="core"):
     """获取指定模块的 logger。
 
     name: 模块名（core/task/web/action），决定写哪个文件。
-          也可传子模块名如 "task.douyin"，会归到 task.log。
+          也可传子模块名如 "task.generic"，会归到 task.log。
     返回配置好的 logging.Logger。
     """
     if name in _LOGGERS:

core/models.py

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

core/system_backup.py

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

core/task_manager.py

@@ -1,9 +1,9 @@
 """通用任务管理框架：任务类型注册 + 设备分组 + 任务计划 + 定时调度 + 重试 + 持久化。
 
-设计目标：可扩展，未来加非抖音任务只需注册新的 Task 类。
+设计目标：可扩展——新增任务类型只需在 tasks/ 下注册新的 Task 类（见 doc/TASK_DEV.md）。
 
 核心概念：
-  TaskType  — 任务类型（如"抖音养号"），可注册，含默认参数和 worker 工厂
+  TaskType  — 任务类型（如"通用步骤"），可注册，含默认参数和 worker 工厂
   DeviceGroup — 设备分组，持久化到 SQLite（core.models.DeviceGroup）
   TaskJob   — 任务计划（类型+目标+参数+调度+重试），持久化到 SQLite（core.models.TaskJob）
   TaskManager — 统管调度器、分组、任务、运行实例、状态
@@ -121,7 +121,7 @@ class DeviceGroup:
 class TaskJob:
     """一个任务计划：什么任务、跑哪些设备、什么参数、何时跑、失败重试策略。"""
 
-    def __init__(self, job_id=None, name="", task_type="douyin_nurture",
+    def __init__(self, job_id=None, name="", task_type="generic_steps",
                  target=None, params=None, schedule=None, retry=None, enabled=True):
         self.id = job_id or uuid.uuid4().hex[:8]
         self.name = name
@@ -378,24 +378,22 @@ class TaskManager:
                 for row in GroupRow.query.all():
                     g = DeviceGroup(row.name, row.get_serials(), row.description or "")
                     self.groups[g.name] = g
-                dirty = False  # 标记是否有任务参数需要写回
+                stale = []   # 任务类型已不存在（历史任务类型被删除）的任务
                 for row in JobRow.query.all():
                     j = TaskJob(job_id=row.id, name=row.name, task_type=row.task_type,
                                target=row.get_target(), params=row.get_params(),
                                schedule=row.get_schedule(), retry=row.get_retry(),
                                enabled=row.enabled)
-                    # 数据规整：移除已废弃的 action 配置（如抖音的 comment 已删除）
+                    # 启动时告警：库里留着已删除的任务类型（如 douyin_nurture），
-                    if j.task_type == "douyin_nurture":
+                    # 这类任务跑不起来也不该静默——提示人工删除或改用现有类型。
-                        actions = j.params.get("actions", {})
+                    # 只告警不改数据（不自动删用户的任务）。
-                        if "comment" in actions:
+                    if not get_task_class(j.task_type):
-                            del actions["comment"]
+                        stale.append(j)
-                            row.set_params(j.params)
-                            dirty = True
-                            _log.info(f"任务 {j.name}({j.id}): 已移除废弃的 comment 配置")
                     self.jobs[j.id] = j
-                if dirty:
+                if stale:
-                    db.session.commit()
+                    _log.warning(
-                    _log.info("已将规整后的任务参数写回数据库")
+                        "以下任务的任务类型已不存在，无法执行，请在「任务」页删除或改用现有类型："
+                        + "；".join(f"{j.name}({j.id}, type={j.task_type})" for j in stale))
             _log.info(f"从数据库加载 {len(self.groups)} 个分组, {len(self.jobs)} 个任务")
         except Exception as e:
             _log.error(f"从数据库加载失败: {e}")
@@ -451,18 +449,55 @@ class TaskManager:
         self._save_groups()
         return g
 
+    def sync_device_serial(self, old_serial, new_serial):
+        """设备换地址（认领/迁址）后，把分组与任务里的引用改到新地址。
+
+        由 device_pool 的迁址回调触发（见 device_pool.set_move_hook）。
+        **必须同时改内存与库**：调度用的是内存里的 groups/jobs，只改库不重启不生效
+        —— 表现就是"分组里少了一台、指定设备的任务仍跑向不存在的地址"。
+
+        返回被更新的引用条数。
+        """
+        if not old_serial or not new_serial or old_serial == new_serial:
+            return 0
+        n = 0
+        for name, g in list(self.groups.items()):
+            try:
+                serials = list(g.serials or [])
+            except Exception:
+                continue
+            if old_serial in serials:
+                self.update_group(name, serials=[new_serial if s == old_serial else s
+                                                 for s in serials])
+                n += 1
+                _log.info(f"设备换地址: 分组『{name}』的 {old_serial} → {new_serial}")
+        for job_id, job in list(self.jobs.items()):
+            try:
+                target = dict(job.target or {})
+            except Exception:
+                continue
+            if target.get("mode") == "serial" and target.get("serial") == old_serial:
+                target["serial"] = new_serial
+                self.update_job(job_id, target=target)
+                n += 1
+                _log.info(f"设备换地址: 任务『{job.name}』目标 → {new_serial}")
+        return n
+
     def delete_group(self, name):
+        removed = False
         if name in self.groups:
             del self.groups[name]
             self._save_groups()
-            # 同上：显式删数据库行，避免删除的分组重启后复活
+            removed = True
+        # 无论内存里有没有都尝试删库行：内存与库不一致时（手工插行、上次异常退出、
+        # 上个版本漏删）也能删干净，避免"删不掉的分组"
         with self._db():
             row = GroupRow.query.filter_by(name=name).first()
             if row:
                 db.session.delete(row)
                 db.session.commit()
-            return True
+                removed = True
-        return False
+        return removed
 
     # ---- 任务计划管理 ----
     def add_job(self, name, task_type, target, params, schedule, retry, enabled=True):
@@ -492,18 +527,20 @@ class TaskManager:
 
     def delete_job(self, job_id):
         self._remove_cron(job_id)
+        removed = False
         if job_id in self.jobs:
             del self.jobs[job_id]
             self._save_jobs()
-            # _save_jobs 只做 upsert 不会删行：必须显式删数据库行，
+            removed = True
-            # 否则删除的任务重启后会从数据库重新加载回来
+        # _save_jobs 只做 upsert 不会删行：必须显式删库行，否则删除的任务重启会复活。
+        # 内存里没有（手工插行/上次异常退出）时也要删——否则会出现"删不掉的任务"
         with self._db():
             row = JobRow.query.get(job_id)
             if row:
                 db.session.delete(row)
                 db.session.commit()
-            return True
+                removed = True
-        return False
+        return removed
 
     def toggle_job(self, job_id, enabled):
         job = self.jobs.get(job_id)
@@ -608,6 +645,11 @@ class TaskManager:
         job = self.jobs.get(job_id)
         if not job:
             return {"ok": False, "error": "任务不存在"}
+        # 任务类型已不存在（历史类型被删除）→ 明确报错，别只返回"已触发"然后线程里静默失败
+        if not get_task_class(job.task_type):
+            return {"ok": False, "error":
+                    f"任务类型 {job.task_type} 已不存在（该类型已被删除），"
+                    f"请删除此任务或改用现有类型"}
         # 在独立线程跑，不阻塞调用方
         t = threading.Thread(target=self._run_job, args=(job,), daemon=True)
         t.start()
@@ -754,7 +796,15 @@ class TaskManager:
                         time.sleep(delay)
 
             _log.error(f"{serial} 任务 {job.name} 重试耗尽，放弃")
-            _update_status(serial, status="failed", last_error=f"{job.name} 重试{max_attempts}次失败")
+            # 带上最后一次的真实失败原因——只写"重试N次失败"会让用户看不到为什么失败
+            # （worker 出错时已把原因写进 _WORKERS[serial]["last_error"]）
+            with _WORKERS_LOCK:
+                cause = (_WORKERS.get(serial, {}).get("last_error") or "").strip()
+            msg = (f"{job.name} 重试{max_attempts}次仍失败" if max_attempts > 1
+                   else f"{job.name} 执行失败")
+            if cause and cause != msg:
+                msg += f"：{cause}"
+            _update_status(serial, status="failed", last_error=msg[:200])
         finally:
             # 清除停止标志：整个重试循环结束（成功/失败/停止）后允许下次任务
             with self._lock:

doc/AI_CONSOLE.md

@@ -0,0 +1,210 @@
+# AI 控制台（AI_CONSOLE）
+
+> 适用读者：使用 AI 控制台的人 + 改这部分代码的开发者。
+> 相关文档：[API.md](API.md) §12（接口）、[MCP.md](MCP.md)（AI 用的工具层）、[AI_TASK_GEN.md](AI_TASK_GEN.md)（"一句话建任务"的设计稿，尚未实现）。
+
+---
+
+## 1. 它是什么
+
+「AI 控制台」是后台的一个顶级 Tab（仅管理员）：选一台设备，用自然语言下指令，AI 通过 MCP 工具**看屏幕、点按、输入**，边做边把过程和结论流式显示出来。
+
+```
+你：「打开小红书搜索苏州好吃的饭店，把前 5 条列出来」
+AI：de_list_devices → de_screenshot → de_tap_text("搜索") → de_type_text("苏州好吃的饭店")
+    → de_screenshot → de_ui_tree → … → 汇总结论（Markdown 表格）
+```
+
+两个"自进化记忆"让它越用越顺：
+
+| 记忆 | 存什么 | 怎么产生 | 怎么用 |
+|------|--------|---------|--------|
+| **🧠 经验库** | 任务级**操作配方**（这一步该怎么做） | 一轮任务成功后由模型蒸馏 | 相似任务开始时召回注入 system prompt |
+| **🎬 动作库** | **命名动作**（可复用的动作单元，带元素定位） | 从**成功步骤**蒸馏，禁坐标 | 相似任务开始时召回注入，可直接复用定位 |
+
+---
+
+## 2. 使用
+
+### 2.1 配置（首次必做）
+
+右上角 **⚙ 配置**：
+
+| 项 | 说明 |
+|----|------|
+| API Base | OpenAI 兼容地址（默认 `https://api.deepseek.com`） |
+| 模型名 | 如 `deepseek-v4-flash-vision-exp`（需支持**视觉**，因为要看截图） |
+| API Key | 只存数据库 `app_meta`，回显打码 |
+| 默认设备 | 不选目标设备时用它 |
+| 最大步数 | 1-200，默认 40（每轮模型调用算一步） |
+
+> 配置存在数据库（`app_meta` 的 `agent_*` 键），**不在 `.env`**。`CLI（mcp_agent/cli.py）` 走的是环境变量 `AGENT_*`，两套互不影响。
+
+### 2.2 跑一轮
+
+1. 选 **🎯 目标设备**（AI **只操作你选定的设备**；有任务在跑的设备不可选）
+2. 输入指令，Enter 发送
+3. 右侧「📺 实时画面」自动跟随 AI 操作的设备（MJPEG）
+4. 中途可「■ 停止」（下一个检查点生效，通常几秒内）
+5. 刷新/换窗口：会话与运行状态都会自动恢复（见 §3.3）
+
+### 2.3 会话管理
+
+左侧会话列表 = 多轮对话（DeepSeek 风格）：不同话题建不同会话，历史消息会作为上下文续上（最近 12 轮）。会话条目上显示 ID（前 8 位，点击复制），便于反馈问题时引用 `conv=<id>`。
+
+---
+
+## 3. 机制
+
+### 3.1 执行链路
+
+```
+POST /api/agent/run            web/agent_api.py 起后台线程（单实例：同时只允许一个）
+        │
+        ├─ 经验召回 _find_experiences(prompt)   ─┐
+        └─ 动作召回 _find_actions(prompt)        ├─ 拼成 extra_context 注入 system prompt
+                                                 ┘
+        ▼
+mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage, …)
+        │  循环（最多 max_steps 轮）：
+        │    ① 流式调模型（OpenAI 兼容 /chat/completions）
+        │    ② 有 tool_calls → 执行 MCP 工具 → 结果回灌 → 继续
+        │       截图工具的结果会转成 image_url 追加，模型"看得见"
+        │    ③ 无 tool_calls → 本轮即最终回答
+        ▼
+   事件 → queue → SSE /api/agent/stream → 前端
+```
+
+- 一轮整体超时 **900 秒**；达到步数上限会让模型做一次收尾总结
+- 工具调用由 MCP Server 执行（`:8033`），后者再调平台 HTTP 接口/直连设备
+- **设备忙时拒绝**：目标设备正在跑任务 → `409`（"AI 不与任务抢设备"）
+
+### 3.2 会话消息模型
+
+`agent_conversation.messages`（JSON 数组）：
+
+```json
+[{"role": "user", "content": "…"},
+ {"role": "assistant", "content": "最终回答（Markdown）",
+  "usage":     {"prompt_tokens": 3480, "completion_tokens": 126, "total_tokens": 3606, "calls": 1},
+  "reasoning": "模型的推理链（最多保留 6000 字符）"}]
+```
+
+> `usage` / `reasoning` **只用于前端展示与回看**；回灌给模型的历史只取 `role` / `content`（不污染上下文预算）。
+
+### 3.3 SSE 事件与刷新恢复
+
+| event | payload | 前端行为 |
+|-------|---------|---------|
+| `delta` | `{"text","kind":"content"\|"reasoning"}` | 正文增量渲染 Markdown；推理增量进入可折叠「💭 思考过程」 |
+| `step` | `{"tool","args","image"?}` | 追加工具卡片（含缩略截图，点击放大）；伪卡片提示经验/动作命中与沉淀 |
+| `usage` | `{"prompt_tokens","completion_tokens","total_tokens","calls"}` | 刷新单条消息脚注与顶栏「本会话累计」 |
+| `done` | `{"answer","usage"}` | 最终答案 + 收尾 |
+| `error` | `{"message"}` | 展示错误（MCP 不可达等已转成明确文案） |
+
+**刷新/重连不丢进度**：服务端事件队列保留积压，页面重新订阅（`GET /api/agent/stream?run_id=`）后会补发 delta/step/usage/done；`EventSource.onerror` **刻意不结束运行**，靠自动重连续上。另外 `GET /api/agent/run` 提供状态快照（其他窗口/8s 轮询用）。
+
+### 3.4 token 统计
+
+- 请求带 `stream_options.include_usage`，服务端在**末尾 chunk** 返回 usage
+- 按「每次模型调用」累加（多轮工具调用会累加多次）；`calls` = 模型调用次数
+- 个别网关不认该参数会直接 400/422 → **自动关掉并重试一次**，不影响主流程（只是没有 token 数字）
+- 展示位置：单条消息脚注（`🪙 3,606 tokens（↑3,480 ↓126 · 1 次调用）`）+ 顶栏「🪙 本会话 3,606 tokens」
+
+### 3.5 回答渲染
+
+- **Markdown**：自研轻量渲染器（`static/admin/markdown.js`，**无 CDN 依赖**，生产在内网）
+  支持标题/段落/列表（含嵌套）/表格/代码块/引用/链接；**先 `esc()` 转义再套标记**，所以模型输出里的 HTML 只会显示为文本
+- **推理链**：`<details>` 折叠块，流式时展开、正文开始时自动收起；手动点过后不再自动改；摘要显示字数
+- **工具卡片**：每步 MCP 调用一行（工具名 + 参数 + 截图缩略）
+
+---
+
+## 4. 经验库
+
+### 4.1 产生（蒸馏）
+
+一轮任务**成功执行过工具**后，把「任务描述 + 工具序列」交给模型，提炼成一段**可复用的操作配方**（纯文本，不含具体坐标）。
+
+健壮性设计（都是踩坑后加的）：
+
+| 措施 | 原因 |
+|------|------|
+| 蒸馏调用**关闭推理**（`thinking: {"type":"disabled"}`） | 推理模型会把 token 预算烧在 reasoning 上，导致 `content` 为空/被截断 → 经验被静默丢弃 |
+| 纯文本问法 + 质量门槛 | 早期提示词里放了可照抄的占位示例，模型会把 `"1. …\n2. …"` 原样当配方存下来 |
+| 截断容忍解析 | JSON 被截断时逐个对象抢救 |
+| 失败有日志 | 不再静默 |
+
+### 4.2 召回
+
+相似任务开始时按 bigram 相似度检索（阈值 + 取前 2 条），拼进 system prompt，并在对话里推一张「🧠 经验记忆」卡片（"命中 N 条同类历史经验，已注入参考"）。命中会累加 `hits`。
+
+### 4.3 巡检（质量治理）
+
+- 每日 **03:47**（独立 APScheduler）自动跑一轮：把经验交给模型评审，输出「保留 / 建议删除」+ 评分 + 理由，写入 `experience_audit`
+- 也可在面板里手动触发
+- **删除永远需要人工确认**（巡检只打标 `pending`，面板上显示 ⚠ 建议删除 + 理由，人工点「确认删除」或「保留」）
+- 「保留」会记 `action='kept'`，后续不再重复建议
+
+### 4.4 面板
+
+「🧠 经验库」按钮打开：列表（任务描述、配方摘要、引用次数、巡检建议）+ 删除/保留操作。
+
+---
+
+## 5. 动作库
+
+### 5.1 与经验库的区别
+
+| | 经验库 | 动作库 |
+|---|--------|--------|
+| 粒度 | 整个任务的操作套路（文字） | 单个可复用动作（结构化步骤） |
+| 内容 | 自由文本配方 | 命名动作 + `steps`（编辑器 schema，**带元素定位**） |
+| 用途 | 让 AI 知道"这类任务一般怎么做" | 让 AI 直接复用"打开抖音"这种动作，跳过重新探索 |
+
+### 5.2 产生（蒸馏）
+
+从本轮**成功**的步骤轨迹里提炼命名动作（如「打开抖音」）。硬约束：
+
+- **禁坐标**：带 `click_xy` 的步骤不会被沉淀（坐标换个设备/分辨率就失效）
+- 白名单步骤类型（18 种去掉 `click_xy`、`keep_screen`）
+- 每类型有必填参数校验（如 `click` 必须有选择器）
+- 输入/产出限量：最多 10 步输入、最多 3 个动作 × 4 步
+- 保存时服务端**再校验一次**，含坐标的提交直接 400
+
+### 5.3 召回与使用
+
+相似任务时按动作名/别名匹配（子串或 bigram 相似度），注入「## 可复用动作」段，并推「🧠 动作经验」卡片。AI 被提示"优先按其中的元素定位操作；若与当前界面不符，再自行截图确认"。
+
+### 5.4 面板
+
+「🎬 动作库」：查看/编辑/删除/手动新建。编辑时直接改 `steps` JSON（有格式说明），保存走同一套校验。
+
+---
+
+## 6. 配置项（`app_meta`）
+
+| key | 含义 | 默认 |
+|-----|------|------|
+| `agent_api_base` | 模型接口地址 | `https://api.deepseek.com` |
+| `agent_model` | 模型名 | — |
+| `agent_api_key` | API Key（**明文存库**） | — |
+| `agent_default_serial` | 默认目标设备 | 空 |
+| `agent_max_steps` | 最大步数（钳制 1-200） | 40 |
+
+其它常量：单轮超时 900s、推理链落库上限 6000 字符、会话消息上限 60 条、历史上下文取最近 12 轮。
+
+---
+
+## 7. 故障排查
+
+| 现象 | 原因 / 处理 |
+|------|------------|
+| 报「MCP server(8033) 不可达」 | MCP 没启动：容器由 `start.sh` 拉起；本机手动 `MCP_ALLOW_WRITE=1 python -m mcp_server.mcp_server` |
+| 报模型 API **401** | API Key 无效/过期 → ⚙ 配置重填 |
+| 报"请先选择目标设备" | 没选设备且没配默认设备 |
+| 报"设备正在执行任务…"（409） | AI 不与任务抢设备：等任务结束，或去监控页停止该任务 |
+| 没有 token 数字 | 该网关不支持 `stream_options.include_usage`（已自动降级，功能不受影响） |
+| 经验/动作没沉淀 | 只有**成功执行过工具**才会蒸馏；看 `logs/web.log` 的「经验提炼 / 动作提炼」日志 |
+| 推理链看不到 | 模型未返回 `reasoning_content`（非推理模型），或本轮没有推理输出 |
+| 界面样式/脚本异常 | 强刷浏览器（Ctrl+Shift+R）——`markdown.js` 等前端文件有缓存 |

doc/AI_TASK_GEN.md

@@ -1,7 +1,8 @@
 # AI 建任务（AI Task Generator）设计文档
 
-> 分支：dev | 状态：设计稿（未实现） | 日期：2026-09-09
+> 状态：**设计稿，尚未实现**（P0 未开工）——本文描述的是「要做什么、为什么这么做」，不是现状。
-> 关联：AI 控制台（web/agent_api.py）、MCP 设备工具（mcp_server/）、任务/步骤编辑器（tasks/generic、static/admin/editor.js）
+> 现状请读：[AI_CONSOLE.md](AI_CONSOLE.md)（AI 控制台已实现的能力）、[TASK_DEV.md](TASK_DEV.md)（任务与步骤）、[MCP.md](MCP.md)（已实现的 19 个工具）。
+> 关联代码：`web/agent_api.py`、`mcp_server/`、`mcp_agent/`、`tasks/generic/`、`static/admin/editor.js`。最后核对：2026-09-10。
 
 ## 1. 背景与目标
 
@@ -23,7 +24,8 @@
 
 - **入口**：AI 控制台加「聊天 / AI 建任务」模式开关，复用会话/SSE/设备选择/停止/刷新恢复骨架。不新建顶级 Tab。
 - **产出方式**：**AI 直接撰写编辑器的步骤 JSON**（非操作轨迹翻译）。自探信息只作上下文与审计；探索中的误点/多余截图不会混入任务。
-- **任务类型**：P0 **只产 `generic_steps`**（通用步骤）。`douyin_nurture` 预设参数生成放 P1。
+- **任务类型**：**只产 `generic_steps`**（通用步骤）——平台当前唯一的任务类型
+  （原 `douyin_nurture` 预设参数生成已随该类型删除，不再做）。
 - **定位原则：全部基于 UI 树**：
   - 模型定位/点击一律走 `de_ui_tree` 拿到的元素（`text`/`id`/`description`/`text_contains`），多实例用 index，或后端 `uiauto_helper` 生成的 `//*[@resource-id=..][k]` XPath；
   - `de_tap_element` 确认能命中后才写进 `click` 步骤；
@@ -134,8 +136,8 @@
 - 尽量不写死坐标；P0 默认禁 `click_xy`，产物以树元素定位为主。
 
 ## 6. 里程碑
-- **P0（本设计主体）**：designer 模式 → 自探（UI 树定位）→ 直接撰写 generic_steps draft → 服务端 schema 校验 → 前端步骤编辑器预填确认保存。验收：一句话在真实设备上生成一条可调度的 generic_steps，步骤全部来自 UI 树且编辑器可打开。
+- **P0（本设计主体）**：designer 模式 → 自探（UI 树定位）→ 直接撰写 generic_steps draft → 服务端 schema 校验 → 前端步骤编辑器预填确认保存。验收：一句话在真实设备上生成一条可调度的 generic_steps，步骤全部来自 UI 树且编辑器可打开。（平台只剩 generic_steps 一种任务类型，与原规划一致）
-- **P1**：`douyin_nurture` 参数预设生成（照 default_params 结构）；模板沉淀：把 draft+需求写入 `agent_experience`（新列存结构化 steps 或 JSON），相似需求注入参考；整链「演示试跑」（把 steps 在设备上以受控方式跑一遍并截图回报，需新增端点，复刻 `device_busy` 拒绝语义）。
+- **P1**：模板沉淀：把 draft+需求写入 `agent_experience`（新列存结构化 steps 或 JSON），相似需求注入参考；整链「演示试跑」（把 steps 在设备上以受控方式跑一遍并截图回报，需新增端点，复刻 `device_busy` 拒绝语义）。
   - **进展（2026-09-10）**：动作级沉淀已落地——`agent_action` 表 + 从**成功步骤**蒸馏"命名动作"（steps 用编辑器 schema、带元素定位、禁坐标）+ 执行前按名/别名召回注入（`web/agent_api.py`）。AI 建任务可直接把这些动作当作 generic_steps 的**预制件**复用。
 - **P2**：自定义动作支持（内联展开成 group，或新增 `action_ref` 节点 + 执行器/编辑器同步）；多设备并行；成本与 token 控制。
 

doc/ARCHITECTURE.md

@@ -1,417 +1,394 @@
-# 架构详解
+# 架构详解（ARCHITECTURE）
 
-本文面向想深入理解 `auto_control` 内部设计的开发者。如果你只想使用，看 [README.md](../README.md) 即可。
+> 适用读者：要改后端 / 前端 / 任务引擎的开发者。
+> 相关文档：[DATA_MODEL.md](DATA_MODEL.md)（表结构）、[API.md](API.md)（接口清单）、[DEVELOPMENT.md](DEVELOPMENT.md)（流程与红线）。
+> 文中引用为 `文件:行号`，以当前代码为准；**行号会随改动漂移，函数名与常量名是稳定锚点**。
 
 ---
 
-## 1. 分层设计
+## 1. 总览
 
-平台按"配置 / 核心 / 任务 / 前端 / 数据 / 日志 / 工具"分层，职责清晰、互不交叉：
+### 1.1 分层
-
-| 层 | 路径 | 职责 |
-|----|------|------|
-| 配置层 | `config.py` | 项目根配置：adb 路径、web 端口、USB 远程 adb server 等基础设施。**不放任务参数** |
-| 核心层 | `core/` | 框架运行时：日志、设备池、adb 操作、Worker 基类、任务管理器、u2 辅助、Action 基类 |
-| 任务层 | `tasks/` | 每个 App 一个子包，自包含 `task.py` + `actions/`，互不依赖 |
-| 前端层 | `templates/admin/` | 单页应用（纯 HTML+CSS+JS，无框架） |
-| 数据层 | `data/` | SQLite 持久化 |
-| 日志层 | `logs/` | 四类日志，10MB 滚动保留 5 份 |
-| 工具层 | `bin/adb/` | adb 可执行文件 |
-| 脚本层 | `scripts/` | 实用脚本 |
-
-### 分层原则
-
-- **任务自包含**：每个任务的参数、Worker、操作都放在 `tasks/<app>/` 下，不污染全局
-- **核心不依赖任务**：`core/` 不 import `tasks/`，任务通过注册机制接入
-- **配置最小化**：`config.py` 只放基础设施配置，任务参数在各自 `task.py` 顶部
-
----
-
-## 2. 数据流
 
 ```
-┌──────────────┐  创建/编辑任务    ┌─────────────┐  分发 worker   ┌──────────────┐
+┌──────────────────────────────────────────────────────────────────────┐
-│ 单页应用前端  │ ───────────────► │ TaskManager │ ─────────────► │  Worker(设备) │
+│ 表现层   templates/admin/*.html + static/admin/*.js（单页应用，无框架）  │
-│ (monitor.html│                  └─────────────┘                └──────────────┘
+│          7 个顶级 Tab；轮询 / SSE / MJPEG 三类实时通道                    │
-│  fetch+DOM)  │                         ▲                            │
+└───────────────────────────┬──────────────────────────────────────────┘
-└──────────────┘                         │ 状态/心跳                    │ u2 操作
+                            │ fetch JSON / SSE / MJPEG / 表单
-       │                                 │                            ▼
+┌───────────────────────────▼──────────────────────────────────────────┐
-       │ JSON API                        │                   ┌─────────────────┐
+│ Web 层   web/（10 个 Flask 蓝图，全部 url_prefix 为空）                 │
-       ▼                          ┌──────────────┐           │ 设备 adb        │
+│   auth 鉴权 · monitor 状态与设备操作 · tasks 任务 · admin 用户与日志     │
-┌──────────────┐                  │  看门狗监控   │           │ (IP:5555 直连  │
+│   tools 运维 · devices 设备池 · apks 应用 · tailscale · agent AI 控制台  │
-│  web/ 蓝图包  │                  └──────────────┘           │  / USB 远程)   │
+│   system 备份                                                          │
-│  (Flask API) │                                            └─────────────────┘
+└───────────────────────────┬──────────────────────────────────────────┘
-└──────────────┘
+                            │ 直接函数调用（共享对象由 web/context.py 注入）
+┌───────────────────────────▼──────────────────────────────────────────┐
+│ 领域层   task_manager（调度）  device_worker（执行）  device_pool（池）  │
+│          system_backup（备份）  apk_manager（应用）  device_discovery   │
+└───────────────────────────┬──────────────────────────────────────────┘
                             │
-       ▼
+┌───────────────────────────▼──────────────────────────────────────────┐
-┌──────────────┐
+│ 基础层   adb_helper · u2_helper · uiauto_helper · ocr · clipboard      │
-│ data/users.db│  SQLite 持久化（用户/分组/任务/设备池/待连接设备/自定义动作/APK记录/AI会话/经验库 + app_meta KV）
+│          models（SQLite）· logger · config                             │
-└──────────────┘
+└──────────────────────────────────────────────────────────────────────┘
+                            ▲
+┌───────────────────────────┴──────────────────────────────────────────┐
+│ 任务定义层  tasks/（BaseTask 注册表 + generic/ 通用步骤引擎）            │
+└───────────────────────────┬──────────────────────────────────────────┘
+                            ▲                       ▲
+┌───────────────────────────┴────────┐  ┌───────────┴──────────────────┐
+│ MCP Server（mcp_server/，:8033）    │  │ AI Agent（mcp_agent/）        │
+│ 19 个 de_* 工具，供外部 AI 调用      │  │ OpenAI 兼容模型 → MCP 工具     │
+└────────────────────────────────────┘  └──────────────────────────────┘
 ```
 
-### 任务执行流程
+### 1.2 各层职责边界
 
-1. 前端创建 TaskJob（HTTP POST `/api/jobs`）
+| 层 | 做什么 | 不做什么 |
-2. `TaskManager` 保存到 SQLite，如启用 cron 则注册到 APScheduler
+|----|--------|---------|
-3. 手动执行或 cron 触发时，`_run_job` 解析目标设备列表
+| 表现层 | 渲染、交互、轮询/流式拉取、按权限隐藏入口 | 不校验权限（只隐藏）；不做业务判断 |
-4. 每台设备起一个线程 `_run_with_retry`，含重试循环
+| Web 层 | 参数校验、鉴权装饰器、JSON 序列化、调用领域层 | 不直接操作 adb/u2（`monitor` 的看屏/截图除外，那本身就是"设备操作"） |
-5. 线程内 `task.create_worker()` 创建 Worker，`worker.start()` 启动
+| 领域层 | 调度、并发、重试、状态机、持久化 | 不感知 HTTP |
-6. `BaseWorker.run()` 执行设备生命周期：占用 → 连接 → setup → run_task → teardown → 释放
+| 基础层 | adb / u2 / OCR / 数据库 / 日志的原子能力 | 不含业务规则 |
-7. Worker 通过 `_update_status()` 实时上报状态到全局 `_WORKERS` 字典
+| 任务定义层 | 任务类型注册 + 具体任务执行逻辑 | 不感知调度与设备获取（`BaseWorker` 已封装） |
-8. 前端轮询 `/api/status`（5 秒缓存）获取设备 + Worker 状态
+
+**装配方向**：`web_server.py` 是唯一组装点；`web/context.py` 注入 `mgr` / `apk_mgr` / `device_pool`，避免 Web 层与领域层循环 import。
 
 ---
 
-## 3. 核心模块详解
+## 2. 启动与装配顺序
 
-### 3.1 DevicePool（`core/device_pool.py`）
+理解启动顺序很关键——**很多副作用发生在 import 期**。
 
-设备池（已摘除 OpenSTF）：SQLite `devices` 表 = 设备清单，本机 adb = 在线状态。
+### 2.1 阶段 A：import 期副作用（`web_server.py:6-25`）
 
-**关键设计**：
+| 顺序 | 触发 | 副作用 |
-- `list_configured()` — 清单（管理页维护，enabled=False 不参与调度）
+|------|------|--------|
-- `list_online()` — 本机 adb 在线设备；池内有 USB 设备（serial 无冒号）时合并 220
+| 1 | `from core.task_manager import TaskManager` | 链式触发：`config.py` 模块体 → **读取根目录 `.env`**（`os.environ.setdefault`）；`core/logger.py` → 创建 `logs/`；`tasks/__init__.py` → **任务类型注册**（`@register_task` 在 import 期执行） |
-  远程 adb server（`USB_ADB_HOST:PORT`，host 网络模式 5037）状态
+| 2 | `get_logger` / `core.models` | 得到 `db` / `init_db` / `User` |
-- `list_ready()` — 清单 ∩ 在线（任务调度用）
+| 3 | `from config import WEB_HOST, WEB_PORT` | 读取端口常量 |
-- 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`）
+> `.env` 是"import config 的副作用"，因此 `web_server.py:30` 读 `WEB_SECRET_KEY` 时它已生效。
 
-**STFDevice** — 单设备生命周期管理：
+### 2.2 阶段 B~D：Flask 与领域对象
-- `acquire()`：IP:5555 直连 adb connect；USB（serial 无冒号）校验 220 远程 adb server 可见性
-- `release()`：无操作（不 disconnect，红线）
-- 互斥由 TaskManager `_running` 保证，设备池负责在线判断
 
-**BaseWorker** — 通用 Worker 基类（继承 threading.Thread）：
+| 阶段 | 位置 | 做了什么 |
+|------|------|---------|
+| **B** | `:28-58` | `Flask(__name__)`；会话密钥（`.env` 的 `WEB_SECRET_KEY`，缺失则随机生成并 warning）；`TEMPLATES_AUTO_RELOAD=True`；**数据库目标由 `core/db_config` 装配**（`.env` 的 `DEPLOY_ENV`/`DB_*` → URI + 引擎参数），配置错直接 `SystemExit(2)`；`LoginManager` + `login_view="auth.login"` |
+| **C** | `:60-67` | **恢复任务消费** `consume_pending_restore()`。SQLite 时代它必须在 engine 首次打开 `users.db` **之前**（Windows 无法替换被持有的文件）；改用 MySQL 后这一步的语义会变成"启动期事务替换"，见 §7 |
+| **D** | `:69-80` | `init_db(app)`（建表 → 补列 → 版本账本 → 唯一索引 → 默认管理员 → 旧 JSON 迁移）→ **库环境标签校验 + 启动横幅**（`db_config.verify_deployment_label/print_banner`，不符拒绝启动）；`device_pool.init_app`（**起一次性线程**，3s 后采集型号）；`device_discovery.init_app`（**起常驻扫描线程**）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)` |
 
-```
+### 2.3 阶段 E~G：蓝图、巡检调度器、真正启动
-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 超时`
+| **E** | `:64-67` | `context.init(...)`；`register_blueprints(app)`（10 个蓝图）；`agent_api.set_app(app)`（供后台线程推 app context） |
+| **F** | `:71-80` | **第二个独立 APScheduler**：`CronTrigger(hour=3, minute=47)` 挂经验库巡检；失败仅 warning |
+| **G** | `:253-265`（`__main__`） | `_ensure_uiauto_running()`（拉起 uiautodev:20242，写 `data/uiauto.pid`，`atexit` 清理）→ `_preconnect_pool_devices()`（后台并发 connect 池内网络设备）→ `_run_server()`（候选端口依次 bind：`0.0.0.0:18050` → `127.0.0.1:18050` → `127.0.0.1:18051..18055`）；退出时 `mgr.shutdown()` + `device_discovery.shutdown()` + 停 uiautodev |
 
-**心跳看门狗**（`_Watchdog`）：
+> ⚠️ **阶段 A~F 在 import 期就会起线程/调度器**，只有 uiautodev 拉起与预连接在 `__main__` 分支。以 WSGI 方式 import 本模块会得到"半个启动"的进程——本地调试请直接 `python web_server.py`。
-- 后台线程，每 30 秒扫描一次
-- Worker 超过 120 秒无心跳 → 标记 `error`
-- 防止设备被占用却不干活
 
-**全局状态注册表**（`_WORKERS`）：
+---
-- `serial -> status dict`，线程安全（`_WORKERS_LOCK`）
-- 供 `web_server` 读取实时状态，前端通过 `/api/status` 展示
 
-### 3.3 TaskManager（`core/task_manager.py`）
+## 3. 线程与并发模型
 
-统一管理：任务类型注册、设备分组、任务计划、定时调度、重试、持久化。
+### 3.1 常驻线程一览
 
-**核心组成**：
+| 名称 | 启动位置 | 职责 | 周期 |
+|------|---------|------|------|
+| Flask 请求线程 | `app.run(threaded=True)` | 每请求一线程 | — |
+| **任务调度器** `BackgroundScheduler` | `TaskManager.__init__` | cron 触发 / 停止任务 | 按 cron |
+| **巡检调度器** `BackgroundScheduler` | `web_server.py` | 经验库 AI 巡检 | 每日 03:47 |
+| `worker-watchdog` | `start_watchdog()` | `running/connecting` 心跳超时 → 标 `error` | 30s 检查 / 120s 阈值 |
+| `device-discovery` | `device_discovery.init_app` | 网段扫描 + 断联重连 | 首轮延迟 15s，之后 interval（默认 60s） |
+| `_refresh_models_bg` | `device_pool.init_app` | 启动后采集全部在线设备型号 | 一次性（3s 后） |
+| `BaseWorker` × N | `TaskManager._run_with_retry` | 单设备任务执行 | 任务期 |
+| `_run_with_retry` × N | 同上 | 单设备重试循环 | 任务期 |
+| `fg-scan-once` | `_ForegroundScanner.scan_once` | 前台 App 扫描 | 手动触发，`Event` 防重入 |
+| `apk-install` | `ApkManager.install` | 并发 5 台安装 APK | 安装期，全局单任务 |
+| Agent 执行线程 | `web/agent_api.py` | AI 控制台一轮会话 | 按需 |
+| 巡检手动线程 | `web/agent_api.py` | 手动触发巡检 | 按需 |
 
-| 组件 | 说明 |
+两个 APScheduler 相互独立，时区均固定 `Asia/Shanghai`。
-|------|------|
-| `scheduler` | APScheduler BackgroundScheduler，cron 触发任务 |
-| `groups` | 设备分组（内存业务对象，持久化到 SQLite） |
-| `jobs` | 任务计划（内存业务对象，持久化到 SQLite） |
-| `_running` | 运行中的 worker（serial -> worker 信息） |
-| `_stop_requested` | 用户请求停止的 serial 集合（阻止后续重试） |
-| `_fg_scanner` | 前台 App 扫描器（不打扰设备） |
 
-**调度模式**：
+### 3.2 锁与并发保护
-- `once`：不注册 cron，手动执行
-- `cron`：注册启动 cron，到点启动所有目标设备
-- `cron_stop`：注册启动 cron + 停止 cron，到点停止本任务 worker
 
-**重试策略**：
+| 锁 | 位置 | 保护对象 | 说明 |
-- `DeviceOfflineError`：立即放弃，不重试（设备掉线短时间不会自愈）
+|----|------|---------|------|
-- 其他异常：按 `retry.max_attempts` 重试，间隔 `retry.delay`
+| `_ADB_LOCK` | `core/adb_helper.py` | adb connect 串行化 | connect 很快，串行不影响整体并发；不覆盖长命令 |
-- 临时错误（端口耗尽）：退避 max(delay, 120s)
+| `_WORKERS_LOCK` | `core/device_worker.py` | 全局设备状态表 `_WORKERS` | "检查+更新"在同一锁内，避免与任务启动竞态 |
-- 用户停止：加入 `_stop_requested`，阻止任何后续重试
+| `TaskManager._lock` | `core/task_manager.py` | `_running` / `_stop_requested` | **抢占时禁止在锁内调 `stop_device`（死锁）** |
+| `_engine_lock` | `core/ocr.py` | OCR 引擎懒加载 + 推理串行 | 推理 0.2~0.5s，锁开销可忽略 |
+| `_scan_lock` / `_stop_event` | `core/device_discovery.py` | 定时/手动扫描互斥 | `acquire(blocking=False)` |
+| `_status_cache_lock` | `core/task_manager.py` | 状态缓存（TTL 5s） | 避免 `/api/status` 每次都查库 + adb |
 
-**并发控制**：同一 serial 同时只允许一个 worker，避免冲突。
+**无锁部分**：`device_pool` 与 `models` 不持显式锁，依赖"每次操作独立 app context" + 数据库自身的并发控制（MySQL 下是 InnoDB 行锁 + READ COMMITTED，回退 SQLite 时是 WAL + `busy_timeout=5000`）。
 
-**状态缓存**：`get_status()` 带 5 秒缓存，避免每次 /api/status 都查库/adb 阻塞前端。
+### 3.3 错峰与心跳
 
-### 3.4 前台 App 扫描器（`_ForegroundScanner`）
+- **错峰启动**：`_START_STAGGER_SEC = 0.2`，第 i 台设备延迟 `i × 0.2s` 启动（100 台 ≈ 20s 铺开），避免批量触发时的 adb 连接风暴。
+- **心跳看门狗**：任何状态写入都会刷新 `last_heartbeat`；`running/connecting` 设备超过 120s 无心跳 → `status="error"` + `last_error="心跳超时…"`。长耗时的业务循环必须周期性 `self.heartbeat()`（`set_action` / `set_progress` 也会刷新）。
+- **单实例约束**：同一 serial 同时只有一个 worker（`TaskManager._running`）；重复触发同任务跳过，不同任务未开抢占也跳过。
 
-**设计原则：不打扰设备**，扫描不会让设备退出当前 App。
+---
 
-| 设备状态 | 处理方式 | 是否打扰 |
+## 4. 设备生命周期
-|---------|---------|---------|
-| worker 运行中（IP:5555） | 复用已有 ADB 连接查询 | 否 |
-| worker 运行中（USB） | 经 220 远程 adb server 查询 | 否 |
-| 完全空闲 | 返回"空闲"（不主动 connect） | 否 |
 
-> **为什么不扫描空闲设备的前台 App**：IP:5555 的 adb transport 是共享的（历史与 STF provider 共用），外部 connect/disconnect 会扰动共享连接，遵守既有红线。
+### 4.0 设备身份：名称 + 指纹（2026-09-11）
 
-### 3.5 ADB 操作（`core/adb_helper.py`）
+设备池原以 **serial（IP）当身份**，设备一换 IP 旧记录就成了连不上的"僵尸条目"，分组与
+serial 模式的任务还吊着死地址。现在拆成三层：
 
-**全局锁串行化**：`_ADB_LOCK` 确保所有 adb 调用串行执行，避免多线程竞争 adb server。
+| 概念 | 是否稳定 | 作用 |
+|------|---------|------|
+| `name`（名称，**必填唯一**） | 稳定 | 人可读身份；分组/任务/日志按名称认设备 |
+| `fingerprint`（`ro.serialno`） | 稳定 | **机器识别**：认出"这是同一台设备" |
+| `serial`（IP:5555 / USB 序号） | **可变** | 当前连接地址 |
 
-**铁律：绝不 kill-server**：
+**认领**（`device_pool.claim_device` 自动 / `relocate_device` 人工）：指纹命中或人工指认后，
-- `adb kill-server` 会断开所有设备的 adb transport
+把旧记录迁到新地址（名称/型号/备注/启用状态/添加时间全保留）并同步引用。
-- 全部设备连接被重建，影响所有运行中的任务
-- 同理绝不 disconnect IP:5555（共享 transport 红线，见 DEVELOPMENT.md）
 
-| 函数 | 说明 |
+> ⚠️ **引用同步必须同时改库与内存**：分组、任务在 `TaskManager` 里还有一份内存副本，
-|------|------|
+> **调度用的是内存对象**——只改库不重启不生效（表现为"分组里少一台、任务仍跑向旧地址"）。
-| `adb_connect(url, retries=5)` | adb connect（带重试，绝不 kill-server） |
+> 因此 `device_pool` 迁址后回调 `TaskManager.sync_device_serial`，由装配层用
-| `adb_connect_light(url)` | 轻量 connect（单次尝试，扫描专用） |
+> `device_pool.set_move_hook(...)` 注册；`device_pool` 不能反向 import `task_manager`（循环依赖）。
-| `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`）
+### 4.1 入池（三条路径）
 
-SQLAlchemy 模型，存于 `data/users.db`：
+| 路径 | 入口 | 过程 |
-
-| 模型 | 表名 | 说明 |
 |------|------|------|
-| `User` | user | 后台用户（Flask-Login 认证，Werkzeug 哈希密码；`is_admin` 管理员 + `perms` 业务权限位） |
+| 手工添加 | `POST /api/devices/pool/add` | `device_pool.add_device`（upsert）→ 有 `:` 则 `adb connect` → 后台采集型号 |
-| `DeviceGroup` | device_group | 设备分组（serials 存 JSON） |
+| 自动发现确认 | `POST /api/devices/discovery/confirm` | 扫描写 `pending_device` → 确认后 `add_device` + 删 pending + connect + 采型号 |
-| `TaskJob` | task_job | 任务计划（target/params/schedule/retry 存 JSON） |
+| 启动预连接 | `_preconnect_pool_devices()` | 进程启动时并发 connect 池内网络设备（仅 `IP:5555`） |
-| `CustomAction` | custom_action | 自定义动作（步骤打包，steps 存 JSON） |
-| `ApkFile` | apk_file | APK 文件元信息 |
-| `Device` | device | 设备池清单（替代 STF 池；enabled=False 不参与调度，含 model 型号列） |
-| `PendingDevice` | pending_device | 自动发现「待连接池」（扫描发现、用户确认后才入正式池） |
 
-> 表名默认取类名小写（models.py 未写 `__tablename__`）。另有三张非模型表，由原生 SQL 幂等创建、**不走 SCHEMA_MIGRATIONS**：
+> 任何一条入池路径在设备可连时都会读取**设备指纹**；指纹命中池中已有设备 = 同一台换了地址
-> - `app_meta`（KV）：`_migrate_schema()` 内建表，存 `schema_version`、`discovery_*`、agent 配置 `agent_*` 等；
+> → 走**认领**（§4.0），不新增记录。
-> - `agent_conversation` / `agent_experience` / `experience_audit`：AI 控制台会话 / 任务级经验（配方）/ 经验巡检（`web/agent_api.py` 顶部 `CREATE TABLE IF NOT EXISTS`）。
-> - `agent_action`：**动作经验库**（命名动作 = 可复用单元，steps 用编辑器 schema 且带元素定位、禁坐标）；由任务成功后从**成功步骤**蒸馏，执行前按名字/别名召回并注入（`web/agent_api.py` `_distill_actions/_find_actions`）。
 
-**数据库初始化**（`init_db`）：
+断联设备的自动重连由发现线程每轮执行（只重连 `IP:5555`）。
-- 创建所有表
-- 首次启动创建默认管理员 `admin/admin123`
-- 自动迁移旧 `groups.json` / `jobs.json` 到 SQLite（迁移后归档为 `.migrated`）
-- 版本化 schema 迁移（`SCHEMA_MIGRATIONS`，**当前到 v4**，见 `core/models.py`）：结构变更必须追加迁移条目，`create_all` 只建新表不加列
 
-### 权限模型
+### 4.2 可用性判定
 
-- `User.perms` 存业务权限位 JSON 数组（`tasks`/`devices`/`apks`/`logs`），`is_admin=true` 拥有全部权限（`has_perm` 短路）
+```
-- 后端统一用 `@perm_required(PERM_X)` / `@admin_required` 装饰器拦截（web/auth.py），无权限返回 403；
+list_configured()   设备池中 enabled=True 的 serial
-  查看类 GET 接口只要求登录；用户管理、adb 终端（`/api/adb/cmd`）强制 `admin_required`
+list_online()       本机 adb devices 中 state=device（池内有 USB 设备时并查 220 远程 adb server）
-- adb 终端安全红线：拒绝 `kill-server` / `disconnect`（共享 adb transport）
+list_ready()        两者交集 ← 调度 "all" 模式取这个
-- 前端 `loadMe()` 拉取 `/api/me`，用 `data-perm` 属性隐藏无权限的 tab/按钮，行内按钮用 `_can(perm)` 判断
+```
-- 安全兜底：**前端隐藏只是 UX，权限强制在后端**；新增路由时按"写操作必须带权限装饰器"的约定
 
-### 3.7 APK 管理（`core/apk_manager.py`）
+### 4.3 执行期状态字段
 
-APK 上传/解析/批量安装。
+设备状态存在内存注册表 `_WORKERS[serial]`（**不落库，重启即清零**）：
 
-**设备连接策略（直连）**：
+| 字段 | 含义 |
-- 直接 `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 服务是否运行 |
+| `status` | `idle` / `connecting` / `running` / `done` / `error` / `released` / `failed` |
-| `list_devices()` | 获取 uiauto2 已连接的设备列表 |
+| `serial` / `model` / `device_name` | 标识 |
-| `get_screenshot(serial)` | 获取设备截图（JPEG） |
+| `task_job` / `attempt` / `max_attempts` | 当前任务与重试进度 |
-| `get_elements(serial)` | 获取设备 UI 元素树（扁平化列表） |
+| `current_action` / `progress` | 当前动作与进度（前端直接渲染） |
+| `last_error` / `last_warning` | 最近错误 / 选择器健康告警 |
+| `last_heartbeat` / `end_time` | 看门狗与时长上限 |
+| `present` / `ready` | 是否在线（对外 `/api/status` 字段） |
 
-元素树解析：递归提取每个节点的 `resource-id/text/content-desc/class/bounds` 等属性，并推荐最佳选择器（优先 xpath）。
+### 4.4 状态迁移
 
-**XPath 序号语义（重要）**：同一属性多个实例时，生成 **`(//*[@resource-id="x"])[k]`**（整体加括号 = 第 k 个匹配）。
+**Worker 侧**（`BaseWorker.run`）：
-不可写成 `//*[@resource-id="x"][k]`——那在 XPath 里是"**在其父节点中排第 k**"，多实例时 `[2..n]` 会全部匹配不到
-（2026-09-10 实测修复：抖音底部 4 个 tab 同 id，旧写法除 `[1]` 外全失效）。执行器 `tasks/generic/task.py`
-对**历史遗留**的 `//*[@attr=…][k]` 形态做窄范围纠正（`_norm_legacy_xpath`，只改前缀、不动结构路径的兄弟序号）。
 
-### 3.9 屏幕 OCR（`core/ocr.py`）
+```
+connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ setup ──▶ run_task ──▶ teardown
+                                                                    │
+                                     未被 stop ──▶ done             │
+                                     异常 ──▶ error（DeviceOfflineError 单独分类，不重试）
+                                     finally ──▶ 仅当仍为 running/connecting 时置 released
+```
 
-条件判断的 `ocr` 选择器实现：截屏 → RapidOCR（ONNX 推理，中英文模型随包内置）→ 关键词匹配 → 返回文字中心像素坐标（与 u2 `d.click` 一致）。
+> `finally` 里的状态判断是为了**不覆盖业务结果**（`done`/`error` 必须保留）。
 
-- **跨平台**（Windows/Linux/macOS），依赖 `rapidocr_onnxruntime`；服务器无显示器环境建议将 opencv-python 换成 opencv-python-headless
+**调度侧**（`_run_with_retry`）：worker 结束后读 `status` → `done` 即成功返回；否则按 `max_attempts` 重试（`[transient]` 错误额外加长退避）→ 重试耗尽置 `status="failed"`，并把**真实失败原因**拼进 `last_error`（截断 200 字符）。
-- 引擎懒加载单例 + 并发加锁（识别约 0.2-0.5s/次）
-- 返回坐标约定：像素、原点左上
 
-### 3.10 Web 层蓝图包（`web/`）
+### 4.5 释放
 
-路由按功能域拆分（模块化开发底线，便于定位问题）：
+`STFDevice.release()` 是**空实现**——直连模式下**绝不 disconnect**（共享 adb transport 红线）。类名 `STFDevice` / `STFError` 是 STF 时代的历史命名，功能上已与 STF 无关。
-
-| 模块 | 职责 |
-|------|------|
-| `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 管理 |
-| `agent_api.py` | AI 控制台：会话 / 运行 / SSE / 停止 / 配置 / 经验库与巡检 / **动作库**（读写 `agent_conversation`、`agent_experience`、`agent_action`、app_meta `agent_*`） |
-| `system_api.py` | 系统数据备份导出 / 导入恢复（`/api/system/backup/*`，仅 admin） |
-| `common.py` | 跨模块共享（合并设备列表/屏幕状态） |
-| `context.py` | 共享对象注入（mgr/apk_mgr/device_pool） |
-
-`web_server.py` 只做装配与启动（266 行）：app 创建；`init_db` 前消费待生效备份恢复（`consume_pending_restore`）；初始化 device_pool / device_discovery；装配 TaskManager / ApkManager；注册 10 个蓝图（auth/monitor/tasks/admin/tools/devices/apks/tailscale/agent/system，`web/__init__.py`）；注册经验巡检 APScheduler（03:47 Asia/Shanghai）；uiautodev 子进程启停与设备池预连接线程；启动。
 
 ---
 
-## 4. 任务系统设计
+## 5. 任务调度链路
 
-### 4.1 注册机制
+### 5.1 完整调用链
 
 ```
-tasks/__init__.py
+① 注册   add_job / update_job / toggle_job
-  ├── from .base import BaseTask, register_task, list_task_types, get_task_class
+         → _add_cron：scheduler.add_job(_on_cron_trigger, CronTrigger.from_crontab(...),
-  ├── from .douyin import task    # 触发 @register_task
+                                       id=f"job_{id}_start", replace_existing=True)
-  └── from .generic import task   # 触发 @register_task
+         （cron_stop 额外注册 job_{id}_stop；启动时 _load() 为 enabled 任务重注册）
+
+② 触发   APScheduler → _on_cron_trigger(job_id)
+         → 任务存在？→ _in_run_window(schedule)？→ _run_job(job)
+
+③ 解析   job.resolve_serials(self)     # all=池内在线 / group=分组∩池 / serial=指定
+         → 为空则 warning 返回
+
+④ 任务类 get_task_class(job.task_type) → 未知则 error 返回（run_job_now 会直接报错）
+         → task_cls()；max_attempts = max(1, retry.max_attempts)
+
+⑤ 铺开   对每台设备起线程 _run_with_retry(task, serial, job, ..., idx * 0.2s)
+
+⑥ 单设备 _run_with_retry：
+         sleep(错峰) → 停止检查 → 单实例/抢占判定 → 登记 _running[serial]
+         → _update_status(task_job=..., attempt=...)
+         → worker = task.create_worker(serial, job.params)
+         → worker.start() → worker.join()
+         → 读 status：done 成功；否则重试（[transient] 退避 max(delay,120)s）
+         → 耗尽：status="failed" + last_error（含真实原因）
+         → finally：清停止标志；本任务若是抢占任务则归还设备（重跑被抢占任务）
+
+⑦ 上报   worker 内 _update_status → 内存注册表
+         → TaskManager.get_status（5s 缓存）
+         → _merge_status（合并池信息、清理陈旧条目）
+         → GET /api/status → 前端 5s 轮询渲染
+
+⑧ 停止   stop_device / stop_all → _stop_requested.add + worker.stop()（置 Event）
+         业务循环检查 self.stopped()
+
+⑨ 下次运行时间 next_run_of → _next_run_time（考虑运行窗口，最多向后探测 200 次）
 ```
 
-`@register_task` 装饰器将 Task 类注册到全局 `_TASK_TYPES` 字典，key 为 `task_type` 字符串。
+### 5.2 抢占机制
 
-### 4.2 参数深合并
+任务参数 `preempt=true` 时：`all` 模式目标集合变为"全部在线池内设备"（含正在跑的）；遇到设备已被占用时在**锁外**调 `stop_device` 并最多等 30s 接管；本任务结束后自动重新启动被抢占的任务（`preempted_job` 必须定义在重试循环外，否则归还信息会丢）。
-
-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. 前端设计
+## 6. 前端架构
 
-### 5.1 单页应用
+### 6.1 单页应用
 
-`templates/admin/monitor.html` 是纯 HTML+CSS+JS 单页应用，无框架依赖。
+- 主页面 `templates/admin/monitor.html`：一个内联 `<style>` + 7 个 Tab 面板 + 7 个模态框容器 + 11 个 `<script src>`
+- 独立页面：`login.html`（登录）、`wall.html`（监控大屏，**完全自包含**，自带 CSS/JS，不加载 `static/admin/*.js`）
+- 服务端内联页：`GET /locate`（设备端定位大字页，免登录）
+- 响应头强制 `no-store`，避免后台改版后浏览器拿旧页面
 
-- **Tab 切换**：7 个顶级 Tab（监控/任务/日志/用户/工具/AI 控制台/系统），均在 monitor.html 内 `.tab-panel` 切换（纯 DOM 操作）；独立页面仅 `/login`、`/wall`。原"分组"已无顶层入口（移到工具页子分栏）
+### 6.2 Tab 与子分栏
-- **数据获取**：`fetch()` 调 JSON API，5 秒轮询 `/api/status`
-- **状态渲染**：设备表格、任务卡片、进度条、徽章，纯 DOM 操作
 
-### 5.2 步骤编辑器
+| 顶级 Tab | `data-tab` | 权限 | 子分栏 |
+|---------|-----------|------|--------|
+| 监控 | `monitor` | 登录即可 | — |
+| 任务 | `tasks` | 登录即可（写操作需 `tasks`） | `plan` 任务计划 / `actions` 自定义动作 |
+| 日志 | `logs` | `logs` | — |
+| 用户 | `users` | `admin` | — |
+| 工具 | `tools` | `admin` | `clipboard` / `adb` / `ts` / `apks` / `appver` / `devapps` / `devpool` / `groups` |
+| AI 控制台 | `agent` | `admin` | — |
+| 系统 | `system` | `admin` | `backup` 数据备份 / `restore` 导入恢复 |
 
-`generic_steps` 任务的步骤编辑器（任务弹窗已加宽到 1000px）：
+子分栏会记住上次选中位置（`_activeSubs`）；`devpool` 子分栏自带 10s 轮询，切走即停。
-- 左侧操作库（拖拽源，按 交互操作/屏幕与App/流程控制 分组）
-- 中间画布（步骤卡片列表，HTML5 Drag API 排序 + 跨层级嵌套：循环套循环、动作组）
-- 每个步骤卡片可展开参数表单
-- 选择器字段旁有"抓取元素"按钮（独立模态框）
-- **容器步骤**（loop/group/if_el）：卡片内嵌子步骤容器接收拖入；if_el 有"✅找到时/❌未找到时"两个独立分支容器，分支可嵌套任意步骤
-- **条件判断**（if_el）：选择器支持 xpath 等 UI 树选择器或 OCR识别（`core/ocr.py`，截屏匹配图片/画布文字，命中可自动点击）
-- 所有递归操作（选择打包、存自定义动作、校验、防循环自套）统一遍历 children/then/else 三个子数组
 
-### 5.3 页内子分栏
+### 6.3 JS 分工
 
-任务/工具/系统 Tab 用通用 `showSubTab(tabId, name)` 实现页内子分栏：每个子分栏一个 `.sub-panel`，
+| 文件 | 职责 | 备注 |
-`_activeSubs` 记住各 Tab 上次选中的子分栏。现状子分栏：
+|------|------|------|
-- **任务**：任务计划 / 自定义动作
+| `base.js` | esc / CSRF / 权限 / API 封装 / Toast / Tab 与子分栏切换 / 模态框 / 常量表 | 所有模块的公共底座 |
-- **工具**：剪贴板注入 / adb 远程终端 / Tailscale 管理 / 应用管理 / 应用版本管理 / 设备已装应用 / 设备池管理 / 设备分组
+| `markdown.js` | 轻量 Markdown 渲染（`renderMarkdown`） | 无 CDN 依赖；**先转义再套标记** |
-- **系统**：数据备份 / 导入恢复
+| `list.js` | 统一列表组件：搜索 + 分页 + 排序 | 状态注册表 `_LIST_PAGERS`；`setListPager` **不重置**页码/搜索/排序（避免轮询刷新打断用户） |
+| `monitor.js` | 监控页：设备表、批量操作、异常汇总、任务概况卡片（含覆盖设备 chip） | 5s 轮询 + 脏检查（签名不变不重渲染） |
+| `editor.js` | 步骤编辑器（拖拽 / 参数表单 / 条件分支 / 元素抓取 / 测试此步骤）+ `saveTask` | 最大的前端文件；`_stepEditor` 单例 |
+| `tasks.js` | 任务 Tab：任务 CRUD / 调度解析 / 运行窗口 + 自定义动作 | |
+| `tools.js` | 工具 Tab：剪贴板、adb 终端、Tailscale、设备池、自动发现、远程看屏 | |
+| `apps.js` | 应用管理：APK 上传/安装/删除、设备已装应用 | |
+| `admin.js` | 分组、日志、用户 + **全局初始化入口**（末尾 `initCsrf(); loadMe(); showTab('monitor')`） | |
+| `agent.js` | AI 控制台：会话、SSE 流、Markdown / 推理链 / token 渲染、实时画面、经验库 / 动作库 | |
+| `system.js` | 系统 Tab：备份导出 / 导入预览与应用 | |
 
-（原"分组"顶级 Tab 与"维护/STF 服务"子分栏已不存在——分组已移入工具页子分栏，STF 已摘除。）
+加载顺序见根 [README](../README.md)；都是全局脚本（非 ES module），靠加载顺序保证依赖。
 
-### 5.4 AI 控制台的记忆面板
+### 6.4 实时通道
 
-AI 控制台（顶级 Tab）右上角两个模态框，管理自进化记忆：
+| 通道 | 场景 | 机制 |
-- **🧠 经验库**：任务级经验（`agent_experience`，整任务配方）+ 每日 AI 巡检建议（删除需人工确认）。
+|------|------|------|
-- **🎬 动作库**：动作级经验（`agent_action`）——命名动作（可含 1~N 步）+ 编辑器 schema 步骤 + **元素定位（禁坐标）**；由任务成功后从**成功步骤**自动蒸馏，执行前按名/别名召回注入；面板支持查看/编辑/删除/手动新建（保存经服务端校验，坐标步骤被拒）。
+| **轮询** | 设备状态（5s）、日志（3s，可关）、自动发现（10s）、截图（3s）、APK 安装（3s）、AI 运行状态（8s） | `setInterval`，切 Tab 时统一清理 |
-- **会话列表显示会话 ID**（前 8 位，等宽小字），点击即复制完整 ID——便于反馈问题时引用 `conv=<id>`。
+| **SSE** | AI 控制台一轮会话 | `EventSource /api/agent/stream`；`onerror` **刻意不结束运行**，靠自动重连 + 服务端事件队列补发 |
+| **MJPEG** | 实时看屏 | `img.src = /api/screen/stream?...`，浏览器原生长连接 |
 
-> **蒸馏健壮性（2026-09-10）**：经验/动作靠**模型蒸馏**落库。推理型模型会把 token 预算烧在 `reasoning` 上，导致 `content` 为空或被截断（`finish_reason=length`）→ 早期只读 `content`，经验/动作被**静默丢弃**（"小红书·苏州饭店"案例）。现策略：
+### 6.5 前端权限
-> 1. 蒸馏调用**关闭推理**：`"thinking": {"type": "disabled"}`（该代理支持；实测关掉后 reasoning=0、正文正常，配方 3/3 合格）——这是关键修复；
-> 2. 配方用**纯文本问法**（不要放可照抄的占位示例，否则模型会原样当配方存下来）+ 质量门槛 `_recipe_ok`（过短/含省略号占位 → 丢弃并重试）；
-> 3. 动作提炼用 JSON + **截断容忍**提取（`_loads_lenient` 逐对象抢救）+ 顶层 `{action,params}` 形状归一 + 输入/产出限量（≤10 步输入、≤3 动作×4 步）；
-> 4. 两类失败都有日志（`经验提炼:` / `动作提炼:` 含样本），不再静默。
 
-### 5.5 元素抓取模态框
+三条并存：① `data-perm` 属性（`loadMe()` 时统一隐藏无权限元素）；② `_can(perm)`（动态拼 HTML 时决定是否出按钮）；③ 后端装饰器兜底（403）。
 
-独立的第二层模态框（`el-picker-overlay`，z-index 1100），不影响任务编辑窗口：
+> 前端隐藏只是体验优化，**安全完全依赖后端**；`data-perm` 只在页面加载时求值一次，改权限后需刷新页面。
-1. 选择设备 → 2. 加载截图 + 元素树 → 3. 点击元素/边界框 → 4. 回填选择器
-5. **抓取时直接验证**（每条元素右侧两个按钮，不会与"点击回填"冲突）：
-   - 「▶ 点一下」：按元素 `bounds` 中心在设备上真点一次（`POST /api/screen/tap`，`snap=1` 自动吸附到可点元素），返回吸附结果并自动刷新截图——用于确认位置/是否可达；
-   - 「✓ 测选择器」：用**将填入的选择器**真跑一次 click（`POST /api/steps/test`），返回 `命中/未找到/已执行`——用于确认回填的选择器在真实界面能命中（元素无有效选择器时不显示此按钮）。
 
 ---
 
-## 6. 关键设计决策
+## 7. 关键设计决策
 
-### 6.1 为什么用 SQLite 而不是 JSON 文件
+| 决策 | 为什么 | 代价 / 注意 |
-
+|------|--------|------------|
-- 支持用户/分组/任务的关系存储
+| **数据库走 MySQL，SQLite 仅作回退** | 多环境（dev 库 / 正式库）需要同一套代码指向不同库；备份/恢复也不再受"文件被占用"掣肘 | 多一套连接配置与防混库校验（`core/db_config.py`）；`DB_HOST` 为空时回退 SQLite，生产禁止静默回退 |
-- 并发安全（WAL 模式）
+| **threading 而非 asyncio** | uiautomator2 是同步阻塞库；每设备一线程模型直观 | 线程数随设备数增长；跨线程访问 DB 必须自推 app context |
-- 迁移旧 JSON 时归档为 `.migrated`，避免删空后重启又复原
+| **状态放内存** 而非落库 | 状态每秒都变，落库纯属浪费 | 重启丢失运行中状态（进程重启 = 任务终止） |
-
+| **蓝图按功能域拆包** | `web_server.py` 只做装配，路由就近维护 | 拆包易出现 import 遗漏 → 用 `scripts/regression_test.py` 兜底 |
-### 6.2 为什么用 threading 而不是 asyncio
+| **单页应用 + 全局脚本** | 无构建步骤、无 npm 依赖，改完强刷即生效 | 11 个文件共享全局作用域，需手工维护加载顺序 |
-
+| **任务类型注册表** | 新增任务类型不动调度器 | 删改类型要做兼容（未知类型必须显式报错，不能静默） |
-- uiautomator2 是同步阻塞库，不适合 asyncio
+| **自建设备池**（不用 STF） | 规避共享 adb transport 的历史坑，清单可控 | 需自己处理在线状态、型号、自动发现 |
-- 多设备并发用多线程即可，每台设备一个 Worker 线程
+| **备份"重启生效"** | 调度器 / worker / 设备池都把任务与设备**缓存在内存**里，整库替换后内存副本全部失效 | 导入后必须重启（重启时消费恢复任务）。SQLite 时代还有"Windows 无法替换被持有的文件"这层原因，改用 MySQL 后只剩内存态这一层 |
-- Flask `threaded=True` 处理并发 HTTP 请求
+| **uiautodev 独立子进程** | 元素抓取是重活，隔离崩溃、可单独重启 | 固定端口 20242；PID 文件防重复拉起（杀之前必须校验 cmdline，防误杀同容器进程） |
-
+| **MCP 独立端口** | 外部 AI 用标准协议接入，不侵入 Web 会话 | MCP 端点自身无鉴权，靠网络隔离；写操作用开关门控 |
-### 6.3 为什么绝不 kill-server
-
-`adb kill-server` / `adb disconnect` 会断开共享的 adb transport（历史与 STF provider 共享；STF 摘除后红线仍保留——多 worker、前台扫描、设备自动发现共用同一 adb server），影响所有运行中的任务。连接失败就返回 False，由调用方处理。
-
-### 6.4 为什么状态查询带缓存
-
-状态源 = 本地 SQLite 设备池 + adb + 内存 worker 状态。5 秒缓存避免每次 `/api/status` 都查库/adb 阻塞 Flask；Worker 实时状态读内存，不受缓存影响。
-
-### 6.5 为什么 DeviceOfflineError 不重试
-
-设备掉线后短时间内不会自愈，重试只会浪费配额并阻塞调度器。让设备进入冷却，可依赖设备自动发现（device_discovery 对正式池断联设备每轮 adb 重连）恢复后再启用。
 
 ---
 
-## 7. 线程模型
+## 8. 技术红线与实现位置
 
-```
+| 红线 | 为什么 | 代码里的体现 |
-主线程（Flask）
+|------|--------|-------------|
-  ├── HTTP 请求处理（threaded=True，每请求一线程）
+| **绝不 `adb kill-server`** | 会断掉所有设备的 adb transport，运行中任务全废 | `adb_helper` 只 connect 不 kill；Web 层硬拦截 `kill-server` / `disconnect` 字符串 |
-  ├── TaskManager.scheduler（APScheduler，cron 触发任务计划）
+| **绝不对 `IP:5555` 设备 `disconnect`** | 该地址的 adb transport 是共享的 | `adb_disconnect` 全项目**零调用方**；`STFDevice.release()` 空实现 |
-  ├── 经验巡检 BackgroundScheduler（03:47 Asia/Shanghai，web_server 装配）
+| **空闲设备扫描不碰 adb** | 避免扰动共享连接 | 前台扫描对空闲设备直接返回"空闲"；设备发现用 socket 探测而非 adb |
-  ├── 设备自动发现线程（device_discovery._discovery_loop，默认 60s 一轮）
+| **adb key 不变** | 设备信任当前 key，换 key 全部变 unauthorized | 部署沿用既有 `~/.android/adbkey` |
-  ├── 设备池型号采集后台线程（device_pool._refresh_models_bg，启动/手动触发）
+| **生产只读原则** | 220 是生产机 | 任何写操作（重启 / pull / 改文件）都需负责人确认 |
-  ├── 设备池预连接线程（web_server._preconnect_pool_devices，重启后加速恢复）
+| **备份覆盖清单** | 漏登记 = 等于没备份 | `core/system_backup.py` 的 `SUMMARY_TABLES`，导出/导入双向自检（见 [DATA_MODEL.md](DATA_MODEL.md) §6） |
-  ├── AI Agent 运行线程（agent_api._agent_thread，单实例 + SSE 推送）
+| **文档同步** | 文档落后会误导开发与运维 | 功能/配置/接口改动的同一个 commit 里更新 `doc/`（索引见 [doc/README.md](README.md)） |
-  ├── 看门狗线程（_Watchdog，30s 间隔）
-  ├── uiautodev 子进程（PID + cmdline 校验，防容器 PID 复用误杀）
-  └── Worker 线程（每台设备一个）
-        ├── _run_with_retry 线程（重试循环）
-        └── BaseWorker 线程（设备生命周期 + run_task）
-```
 
-> MCP server（127.0.0.1:8033）是**独立进程**（scripts/start.sh 拉起），不是 web_server 的线程。
+---
 
-**线程安全**：
+## 9. 已知问题与"坑"
-- `_WORKERS_LOCK`：保护全局 worker 状态字典
+
-- `_ADB_LOCK`：串行化所有 adb 调用
+### 9.1 代码缺陷（截至 2026-09-10，详见 [backlog/TODO.md](backlog/TODO.md)）
-- `TaskManager._lock`：保护运行中任务字典
+
-- `_ForegroundScanner._cache_lock`：保护前台 App 缓存
+| 问题 | 现象 | 位置 |
+|------|------|------|
+| `GET /locate` 返回 500 | 设备定位大字页打不开（NameError：`render_template_string` / `_esc` 未导入） | `web/monitor.py` |
+| `POST /api/device/locate`（`show=true`）失败 | 在设备浏览器打开定位页那步抛异常（`urllib` 未导入），被转成 502 | `web/monitor.py` |
+| CSRF 未实际启用 | 前端会取并携带 `X-CSRF-Token`，但服务端**没有注册** `before_request` 校验 | `web_server.py` 只 import 了 `_csrf_protect` |
+| 回归脚本在 Windows 不可用 | `scripts/regression_test.py` 用了 `signal.alarm`（Windows 无此 API），直接报错退出 | `scripts/regression_test.py` |
+| 前端 `--card-line` 未定义 | AI 控制台相关深色容器边框失效（该变量只在 wall.html 定义） | `templates/admin/monitor.html` 的 `:root` |
+| `countParts` 未定义 | 进度为 0 时可能抛 ReferenceError（被上层 try/catch 吞掉，用户无感） | `static/admin/monitor.js` |
+
+### 9.2 代码里写明的坑（改代码前务必读）
+
+| 坑 | 说明 |
+|----|------|
+| **跨线程访问 DB 必须自推 app context** | 后台线程用 `with app.app_context()`（各模块 `_ctx()` / `_db()` 已封装） |
+| **`debug=False` 不热重载** | 改 `core/`、`tasks/` 后必须重启；改 JS 需强刷浏览器 |
+| **Windows adb 输出不能用 `text=True`** | adb 输出含非 GBK 字节会崩；必须收 bytes 再解码 |
+| **`u2.connect` / `d.info` 可能永久 hang** | 必须放 `ThreadPoolExecutor` 里加超时 |
+| **Windows TCP 端口耗尽（WinError 10048）** | 属临时错误，重试需更长退避（代码识别后打 `[transient]`，退避 `max(delay,120)` 秒） |
+| **抢占时不能在锁内 `stop_device`** | 会死锁 |
+| **`preempted_job` 必须在重试循环外** | 否则被抢占任务永不归还 |
+| **删除任务/分组必须显式删行** | 只 upsert 的话，重启会从库里"复活" |
+| **旧 JSON 迁移后必须归档** | 否则用户删空数据后重启又复原 |
+| **XPath 位置谓词语义** | `//*[@id="x"][k]` = 父节点下第 k 个；`(//*[@id="x"])[k]` = 第 k 个匹配。抓取器生成后者，执行器会自动纠正历史写法 |
+| **容器重启后 PID 会被复用** | 杀残留 uiautodev 前必须校验 `/proc/<pid>/cmdline`，否则可能误杀同容器进程 |
+| **`.env` 用 `setdefault` 注入** | 真实环境变量优先于 `.env` |
+| **备份必须重启才生效** | 恢复任务在 `init_db` 之前被消费 |
+
+---
+
+## 10. 扩展点（改哪里）
+
+| 想做什么 | 改哪里 | 别忘了 |
+|---------|--------|--------|
+| 加一种步骤类型 | `tasks/generic/task.py` 的 `STEP_TYPES` + `_exec_<type>`；`static/admin/editor.js` 的 `STEP_LIB` | 两处保持一致；更新 [TASK_DEV.md](TASK_DEV.md) |
+| 加一个专属任务类型 | `tasks/<app>/`（照 `tasks/generic/` 结构）+ `tasks/__init__.py` 注册 | 重启生效；更新 [TASK_DEV.md](TASK_DEV.md) |
+| 加一个 HTTP 接口 | 对应功能域的 `web/xxx_api.py` | 加鉴权装饰器；更新 [API.md](API.md) |
+| 加一个蓝图 | 新建 `web/xxx_api.py` + 在 `web/__init__.py` 注册 | 更新 [API.md](API.md) 与本文 §1 |
+| 加一张表 | `core/models.py` 模型 + `SCHEMA_MIGRATIONS`（老库） | **登记进备份覆盖清单** + [DATA_MODEL.md](DATA_MODEL.md)（红线） |
+| 加一个常驻线程 | 参考 `device_discovery` 的 `init_app` / `shutdown` 模式 | 更新本文 §3 与 [DEVELOPMENT.md](DEVELOPMENT.md) |
+| 加一个前端模块 | `static/admin/<name>.js` + 在 `monitor.html` 按序引入 | 更新本文 §6 与 [DEVELOPMENT.md](DEVELOPMENT.md) |
+| 加一个 MCP 工具 | `mcp_server/mcp_server.py`（需要时加 `direct_ops.py`） | 写操作要挂门控三连；更新 [MCP.md](MCP.md) |
+| 加一个配置键 | `config.py`（程序级）或 `.env`（密钥类） | 更新 `.env.example` + [DEVELOPMENT.md](DEVELOPMENT.md) 配置速查 |

doc/DATA_MODEL.md

@@ -0,0 +1,302 @@
+# 数据模型（DATA_MODEL）
+
+> 适用读者：改后端 / 排数据问题的开发者与运维。
+> 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)（运行时架构）、[DEPLOY.md](DEPLOY.md) §数据备份（备份覆盖红线）、[API.md](API.md)（消费这些数据的接口）。
+> **表结构以 `core/models.py` 的 ORM 模型为唯一准**（2026-09-13 起各模块的裸建表 SQL 已全部并入模型），本文是它们的映射说明。
+
+---
+
+## 1. 总览
+
+| 项 | 值 |
+|----|----|
+| 引擎 | MySQL（正式用法；目标由 `.env` 的 `DEPLOY_ENV` + `DB_*` 决定）／SQLite（回退模式，`DB_HOST` 为空时） |
+| driver | Flask-SQLAlchemy（SQLAlchemy 2.x）+ PyMySQL |
+| 连接参数 | 见 `core/db_config.py`：utf8mb4、排序规则 `utf8mb4_bin`、`pool_pre_ping`、`pool_recycle=1800`、隔离级别 READ COMMITTED、`sql_mode=STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION` |
+| SQLite 回退时的 PRAGMA | `journal_mode=WAL`、`busy_timeout=5000`、`synchronous=NORMAL`（监听器按连接类型守卫，MySQL 连接不会执行） |
+| 建表方式 | **唯一真相是模型**：`db.create_all()`（建缺表）+ `_sync_columns()`（补缺列）；`SCHEMA_MIGRATIONS` 只作版本账本与数据回填 |
+| 库位置 | MySQL：由 `DB_HOST/DB_NAME` 指定；SQLite：`data/users.db` |
+| 当前 schema 版本 | `app_meta.schema_version = 6` |
+
+**环境与库的绑定**（防混库，见 [DEPLOY.md](DEPLOY.md) §2.2）
+
+| `DEPLOY_ENV` | 期望库名 | 用途 |
+|---|---|---|
+| `dev` | `auto_control_dev` | 本地开发 |
+| `prod` | `auto_control` | 正式环境（220 容器） |
+
+启动时校验「`.env` 声明」与「库名」「库中登记的 `app_meta.deployment_env`」三方一致，不符**拒绝启动**。
+
+**表清单（12 张，全部是 `core/models.py` 里的 ORM 模型）**
+
+| # | 表 | 用途 |
+|---|---|------|
+| 1 | `user` | 登录用户与权限 |
+| 2 | `device_group` | 设备分组（JSON 存 serial 列表） |
+| 3 | `task_job` | 任务计划 |
+| 4 | `custom_action` | 自定义动作（可复用步骤包） |
+| 5 | `apk_file` | APK 记录 |
+| 6 | `device` | 设备池 |
+| 7 | `pending_device` | 待确认的发现设备 |
+| 8 | `app_meta` | KV 配置（schema 版本、AI 配置、发现配置、库环境标签） |
+| 9 | `agent_conversation` | AI 控制台会话 |
+| 10 | `agent_experience` | 经验库（任务级配方） |
+| 11 | `experience_audit` | 经验巡检结论 |
+| 12 | `agent_action` | 动作库（命名动作） |
+| 13 | `device_install_log` | 设备端应用商店的下载/安装记录（设备上报，见 [DEVICE_AGENT.md](DEVICE_AGENT.md)） |
+
+> 2026-09-13 之前，`app_meta` 与 4 张 `agent_*` 表是各模块里的裸 `CREATE TABLE`
+> （不进模型层）。迁 MySQL 时那批 SQL 的 `AUTOINCREMENT`/`TEXT DEFAULT ''`/`TEXT PRIMARY KEY`
+> 全都建不出来，而异常被 `except: pass` 吞掉 —— 表现为「经验库/动作库静默失灵」。
+> 现在全部升为模型，建表只有一条路径。
+
+> **没有外键、没有关系（relationship）**：全部靠应用层维护一致性。分组 ↔ 设备是多对多的
+> **JSON 列表**（`device_group.serials`），删除设备不会级联清理分组里的 serial。
+>
+> **唯一索引只有两个**（设备名 / 指纹，见 §4.2），且都是「空值不参与唯一约束」的语义。
+
+---
+
+## 2. 模型表（`core/models.py`）
+
+### 2.1 `user` — 登录用户
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | Integer | — | 主键 |
+| `username` | String(80) | — | **唯一**，非空 |
+| `password_hash` | String(255) | — | werkzeug 加盐哈希；兼容旧裸 SHA-256（校验通过后自动升级） |
+| `is_admin` | Boolean | `True` | 管理员不受权限位限制 |
+| `perms` | Text | `"[]"` | JSON 数组：`tasks` / `devices` / `apks` / `logs` |
+
+方法：`get_perms` / `set_perms` / `has_perm` / `set_password` / `check_password`。
+
+### 2.2 `device_group` — 设备分组
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | Integer | — | 主键 |
+| `name` | String(80) | — | **唯一**，非空 |
+| `serials` | Text | `"[]"` | 组内设备 serial 的 JSON 数组 |
+| `description` | Text | `""` | 备注 |
+
+### 2.3 `task_job` — 任务计划
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | String(32) | — | 主键，uuid 前 8 位 |
+| `name` | String(120) | — | 非空 |
+| `task_type` | String(60) | `"generic_steps"` | 必须已注册 |
+| `target` | Text | `'{"mode":"all"}'` | JSON |
+| `params` | Text | `"{}"` | JSON（与任务类默认值合并后使用） |
+| `schedule` | Text | `'{"mode":"once"}'` | JSON |
+| `retry` | Text | `'{"max_attempts":1,"delay":60}'` | JSON |
+| `enabled` | Boolean | `True` | 是否参与调度 |
+
+### 2.4 `custom_action` — 自定义动作
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | String(32) | — | 主键 |
+| `name` | String(120) | — | 非空 |
+| `icon` | String(4) | `"📦"` | 展示图标 |
+| `steps` | Text | `"[]"` | JSON，schema 与 `generic_steps` 的 `params.steps` 一致 |
+| `created_at` | String(20) | `""` | 时间串 |
+
+### 2.5 `apk_file` — APK 记录
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | String(32) | — | 主键；磁盘文件名为 `<id>.apk` |
+| `filename` | String(255) | — | 原始文件名 |
+| `display_name` / `package_name` / `version_name` | String | `""` | 解析结果 |
+| `version_code` / `size` | Integer | `0` | |
+| `upload_time` | String(20) | `""` | |
+
+### 2.6 `device` — 设备池
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `serial` | String(120) | — | 主键：`IP:5555` 或 USB 序列号 |
+| `name` | String(80) | `""` | 备注名 |
+| `model` | String(120) | `""` | 型号（迁移 v3 追加） |
+| `enabled` | Boolean | `True` | 停用则不参与调度 |
+| `note` | Text | `""` | |
+| `created_at` | String(20) | `""` | |
+| `fingerprint` | String(120) | `""` | **设备指纹**（`ro.serialno`，迁移 v5 追加）：同一台物理设备换 IP 后据此认领回原记录 |
+
+### 2.7 `pending_device` — 待确认的发现设备
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `serial` | String(120) | — | 主键 |
+| `source` | String(20) | `""` | `lan` / `tailscale` |
+| `first_seen` / `last_seen` | String(20) | `""` | 时间串 |
+| `fingerprint` | String(120) | `""` | 扫描时读取的设备指纹（迁移 v6 追加），用于提示"这是已有设备换了地址" |
+
+> ⚠️ SQLAlchemy 模型的 `default=` 是 **Python 侧默认值**，SQLite 建表语句里没有 `DEFAULT` 子句；只有原生建表的表才有真正的 SQL DEFAULT。
+
+---
+
+## 3. 非模型表
+
+### 3.1 `app_meta` — KV 配置
+
+| 列 | 类型 |
+|----|------|
+| `key` | TEXT PRIMARY KEY |
+| `value` | TEXT |
+
+由 `_migrate_schema()` 建表（启动必执行）。**所有键见 §5**。
+
+### 3.2 AI 相关四张表（`web/agent_api.py`，原生建表）
+
+| 表 | 列 |
+|----|----|
+| `agent_conversation` | `id`(PK) · `title` · `messages`(JSON) · `created_at` · `updated_at` |
+| `agent_experience` | `id`(PK AUTOINCREMENT) · `task_prompt` · `recipe` · `tool_seq` · `hits` · `created_at` |
+| `experience_audit` | `id`(PK) · `exp_id` · `verdict`(keep/delete) · `score`(REAL) · `reason` · `hits` · `action`(pending/kept/deleted) · `audited_at` |
+| `agent_action` | `id`(PK) · `name` · `app` · `aliases`(JSON) · `params`(JSON) · `steps`(JSON) · `preconditions` · `hits` · `source_prompt` · `created_at` · `updated_at` |
+
+> 2026-09-13 起这四张表**已升为 ORM 模型**（见 §1 的说明），建表统一走 `db.create_all()`。
+
+---
+
+## 4. 迁移机制
+
+### 4.1 建表与补列（以模型为准）
+
+**模型定义是唯一真相**。启动时：
+
+| 步骤 | 做什么 | 幂等性 |
+|------|--------|--------|
+| `db.create_all()` | 建**缺的表**（模型里有的都在） | 幂等 |
+| `_sync_columns()` | 用 `sqlalchemy.inspect` 比对模型与实表，**补实表缺的列** | 幂等 |
+| `_migrate_schema()` | 维护 `app_meta.schema_version` 账本 + 执行数据回填 | 幂等 |
+| `_ensure_unique_indexes()` | 建设备名/指纹唯一索引（见 §4.2） | 幂等 |
+| `_ensure_default_admin()` | 首次创建 `admin/admin123` | 幂等 |
+| `_migrate_old_json()` | 旧 `groups.json`/`jobs.json` 一次性迁移 | 见 §4.3 |
+
+> 2026-09-13 之前，补列靠 `ALTER TABLE` 报错文本里有没有 `duplicate column name` 来判断
+> 「列已存在」——那是 SQLite 时代的写法，换方言（MySQL 的错误码/文本都不同）就失效了。
+> 现在改为直接读数据库元数据比对，**缺什么补什么，两种方言一套代码**。
+
+### 4.2 唯一索引（设备身份）
+
+两个「空值不参与唯一约束」的唯一索引，与版本号无关，每次启动都补建：
+
+| 索引 | 作用 |
+|------|------|
+| `ux_device_name` | 设备**名称唯一**（空名不参与，兼容历史未命名设备） |
+| `ux_device_fingerprint` | **一台物理设备在池中只有一条记录**（空指纹不参与） |
+
+实现按方言分叉（`_ensure_unique_indexes()`）：
+
+- **SQLite**：直接用带 `WHERE name <> ''` 的**部分索引**
+- **MySQL 5.7**：不支持过滤索引，改用「**虚拟生成列 + 唯一索引**」——
+  生成列把空值映射成 `NULL`（`IF(col IS NULL OR col='', NULL, col)`），
+  而唯一索引允许多个 `NULL`，正好等于「空值不参与唯一」。生成列名 `name_uq` /
+  `fingerprint_uq`，**只由 DDL 添加、不进 ORM 模型**（进了 `create_all` 会尝试写入
+  它并报 Error 3105）。
+
+> 若历史数据里已有重复（建索引失败），只告警不回滚、不阻塞启动——约束从此刻起对新数据生效，
+> 老的重复行由管理页「改名」处理。
+
+### 4.2.1 排序规则为什么必须是 `utf8mb4_bin`
+
+SQLite 的文本比较是**逐字节**的（大小写敏感）。MySQL 默认的 `utf8mb4_general_ci`
+是大小写**不**敏感，会让 `Admin`/`admin`、`Phone1`/`phone1` 被判成重复，唯一索引和
+等值查询语义全变。所以库、表、连接三处都统一用 `utf8mb4_bin`（逐码点比较，对合法
+UTF-8 等价于字节序）。
+
+唯一的语义差异：`LIKE` 在 `_bin` 下是大小写敏感的（SQLite 对 ASCII 默认不敏感）。
+当前代码里没有任何 `LIKE`/`ilike` 查询，暂无影响。
+
+### 4.3 旧 JSON 迁移（一次性）
+
+启动时若存在 `data/groups.json` / `data/jobs.json`：对应表为空则导入，随后把文件重命名为 `<name>.json.migrated` 归档。**库非空但 JSON 仍在 → 直接归档**，防止"用户删空数据后重启又复原"。
+
+---
+
+## 5. `app_meta` 键清单
+
+| key | 用途 | 写入方 |
+|-----|------|--------|
+| `schema_version` | 迁移版本游标 | `core/models.py` |
+| `agent_api_base` | AI 接口地址 | AI 控制台配置页 |
+| `agent_model` | 模型名 | 同上 |
+| `agent_api_key` | API Key（**明文存库**） | 同上 |
+| `agent_default_serial` | 默认目标设备 | 同上 |
+| `agent_max_steps` | 最大步数（钳制 1-200，默认 40） | 同上 |
+| `discovery_enabled` | 自动发现开关（`"1"`/`"0"`） | 工具页「设备池管理」 |
+| `discovery_subnets` | 扫描网段 JSON 数组 | 同上 |
+| `discovery_interval` | 扫描周期秒（10-3600） | 同上 |
+| `discovery_port` | adb 探测端口（1-65535） | 同上 |
+| `discovery_auto_claim` | 指纹匹配时自动认领（`"1"`/`"0"`，默认关） | 同上 |
+| `agent_store_enabled` | 设备端应用商店开关（`"1"`/`"0"`，默认关） | 应用管理页 |
+| `agent_device_token` | **设备端令牌**（Agent 调设备接口用；属凭据） | 同上（启用时自动生成，可重置） |
+| `agent_device_token_at` | 令牌生成/重置时间 | 同上 |
+| `deployment_env` | **库环境标签**（`dev`/`prod`），启动时与 `.env` 比对 | `core/db_config.py`（首次连接）/ 迁移脚本 |
+| `deployment_id` | 库唯一标识（uuid），用于识别"这份备份来自哪个库" | 同上 |
+| `deployment_claimed_at` | 标签写入时间 | 同上 |
+
+> ⚠️ `agent_api_key` 是**明文存储**，导出备份的 zip 里也含它——备份预览会固定给出"含敏感信息"告警。
+> `app_meta` 的列名 `key` 在 MySQL 里是保留字，**不要直接拼裸 SQL**，统一走
+> `core/db_config.meta_get / meta_set`（方言中立、自动加引号）。
+
+---
+
+## 6. 备份覆盖清单（红线）
+
+`core/system_backup.py` 的 `SUMMARY_TABLES` **由模型元数据派生**：
+
+```python
+SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
+```
+
+也就是说——**新增一张 ORM 表，自动就进备份覆盖清单**，不可能再漏。
+`TABLE_LABELS`（预览页的中文标签）仍是手工维护，缺标签时回退显示表名。
+
+**双向自检**：
+
+- **导出侧**：登记在 `SUMMARY_TABLES` 但快照里缺失 → 写入 `manifest.coverage_missing` + 日志告警
+- **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警（字段 `extra_tables`）
+- `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入（这四项是"判定这是不是本平台备份"的最小集合，故意手工维护）
+
+> **红线**：新增持久化表时**同时补 `TABLE_LABELS` 的中文标签**并更新 [DEPLOY.md](DEPLOY.md) §数据备份。
+> 覆盖清单本身不再需要手工登记（已由 metadata 派生）。历史教训：`agent_action` 曾漏登记，
+> 导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
+
+---
+
+## 7. 数据目录
+
+| 路径 | 内容 | 进 git |
+|------|------|--------|
+| `data/users.db`(+`-wal`/`-shm`) | SQLite 主库（**仅回退模式用**；连 MySQL 时这些文件不被读写，可留作历史归档） | 否 |
+| `data/apks/*.apk` | 上传的 APK | 否 |
+| `data/backups/` | 导出临时 zip、`pre_restore_*.zip`（导入前安全网）、`restore_failed_*` | 否 |
+| `data/restore_staging/<token>/` | 导入暂存（TTL 1800s 自动清理） | 否 |
+| `data/restore_pending/` | 待生效恢复任务（重启时单事务消费） | 否 |
+
+> 后三个目录可用环境变量改到别处（`DATA_BACKUP_DIR` / `DATA_RESTORE_STAGING_DIR` /
+> `DATA_RESTORE_PENDING_DIR`）——自动化测试必须这么做，否则测试造的待生效恢复任务
+> 会被服务当成用户的操作在下次重启时消费掉。
+| `data/mcp_audit.log` | MCP 调用审计（路径由 `MCP_AUDIT_FILE` 指定） | 否 |
+| `data/uiauto.pid` | uiautodev 子进程 PID | 否 |
+| `data/*.json.migrated` | 旧 JSON 迁移归档 | 否 |
+| `logs/*.log` | 运行日志 | 否 |
+
+> `data/` 与 `logs/` 全部是运行时产物，**任何文件都不入 git**。生产机上的库由「系统 → 数据备份导出/导入」或整目录手工备份。
+
+---
+
+## 8. 约定与注意事项
+
+1. **主键用 uuid 前 8 位字符串**（`task_job` / `custom_action` / `apk_file` / `agent_conversation`）：可读性好，理论上有碰撞概率（8 位 hex = 32 bit）。
+2. **JSON 字段一律 Text 存储**，读写通过 `get_*/set_*` 方法；解析失败回退默认值。
+3. **时间统一为字符串**（`"YYYY-MM-DD HH:MM"` 或 `"YYYY-MM-DD HH:MM:SS"`），排序依赖字符串序。
+4. **删除必须显式删行**（`delete_job` / `delete_group`）：只 upsert 会导致重启后数据"复活"。
+5. **跨线程访问 DB 必须自推 app context**（后台线程里用 `with app.app_context()`）。
+6. **不要手工改库结构**：走 `SCHEMA_MIGRATIONS`（模型表）或幂等建表（原生表），否则 `create_all` 与版本号会不一致。
+7. **改表结构后记得**：① 更新本文；② 若是新表，登记备份覆盖清单（§6 红线）。

doc/DEPLOY.md

@@ -1,360 +1,356 @@
-# 部署指南
+# 部署与运维（DEPLOY）
 
-本文介绍如何从零部署 `platform-tools` 设备自动化后台。
+> 适用读者：部署与运维 `auto_control` 的人。
+> 相关文档：[DEVELOPMENT.md](DEVELOPMENT.md)（开发流程/红线）、[DATA_MODEL.md](DATA_MODEL.md) §数据目录、[ARCHITECTURE.md](ARCHITECTURE.md) §启动装配。
 
 ---
 
 ## 1. 环境准备
 
-### 1.1 Python 环境
+### 1.1 主机与 Python
 
 - **Python 3.10+**（推荐 3.12）
-- 安装后确认 `python --version` 和 `pip` 可用
+- Windows / Linux / macOS 均可；生产跑在 Linux 容器里
+- `pip install -r requirements.txt`
 
-```bash
+项目自带的 **adb 二进制**在 `bin/adb/`（Windows 为 `adb.exe` + 依赖 dll；Linux/macOS 为 `adb`，需 `chmod +x`）。`config.py` 按平台自动选路径，换成自己的 adb 覆盖该目录即可。
-# 验证
-python --version    # 应输出 3.10+
-pip --version
-```
 
-### 1.2 设备池（已摘除 OpenSTF 依赖）
+### 1.2 设备接入
-
-设备池由平台自身管理（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）
 
----
+1. 开启 **USB 调试**
+2. 转网络调试：USB 连上后 `adb -s <serial> tcpip 5555`（后台「工具 → adb 终端」有快捷命令）
+3. 与平台**网络互通**（生产用 Tailscale，设备与部署机在同一 tailnet，serial 形如 `100.100.10.x:5555`）
+4. 在「工具 → 设备池管理」加入设备池（**只连上 adb 不算入池，不参与调度**）
 
-## 2. 安装部署
+**USB 设备**（serial 无冒号）经部署机的 adb server 驱动：
 
-### 2.1 获取代码
+- adb 容器需 **host 网络模式**（5037 监听所有网卡，含 Tailscale）
+- 平台通过 `USB_ADB_HOST`（默认 `100.100.10.1`）/ `USB_ADB_PORT`（默认 5037）访问它
 
-```bash
+> **adb key 必须沿用既有 key**（设备信任它）。换 key 会让全部设备变 `unauthorized`。
-# 方式一：直接拷贝项目目录
-# 方式二：解压打包文件（python scripts/pack.py 生成的 zip）
-```
 
-### 2.2 安装依赖
+### 1.3 端口
-
-```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识别 选择器，中英文模型随包内置，跨平台） |
-| fastmcp | >=2.0 | MCP Server 与 AI 控制台 Agent（Streamable HTTP 服务端/客户端） |
-| paramiko | >=3.0 | SSH 运维预留（历史 STF SSH 通道退役；配置 `STF_SSH_PASSWORD` 时走密码认证，未配置则退回系统 ssh 免密） |
-
-> 服务器（无显示器/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（个人账号一般为登录邮箱前缀） |
-| `DISCOVERY_PORT` | `5555` | 设备自动发现扫描的 adb 端口（网段默认局域网 + Tailscale，可在设备池面板改） |
-| `DISCOVERY_INTERVAL` | `60` | 自动发现扫描间隔（秒） |
-
-> 配置来源区分：`WEB_HOST`/`WEB_PORT`/`ADB_PATH` 是 **config.py 常量**（直接改文件，不经 .env）；
-> `TAILSCALE_API_KEY`/`TAILSCALE_TAILNET`/`USB_ADB_HOST`/`USB_ADB_PORT`/`DISCOVERY_PORT`/`DISCOVERY_INTERVAL` 由 config.py 以环境变量读取，**可在 .env 覆盖**；
-> `BACKUP_DIR`/`RESTORE_STAGING_DIR`/`RESTORE_PENDING_DIR` 是常量（硬编码到 `data/`，见 §3.5）。
-
-> **未配置 `WEB_SECRET_KEY`**：启动时随机生成（每次重启登录态失效，生产务必配置固定值）。
-> **工具页 Tailscale 管理前置**：`.env` 写入 `TAILSCALE_API_KEY` 后重启服务；
-> 未配置时管理分区显示明确提示，不影响其他功能。
-> （历史遗留的 `STF_URL`/`STF_TOKEN`/`STF_SSH_*` 等配置：`config.py` 仍读取但无任何功能使用，仅历史保留；生产 `.env` 可留空。）
-
-### 2.4 启动服务
-
-**命令行启动**
-
-```bash
-python web_server.py
-```
-
-（推荐配合 `scripts/supervise.sh` 进程守护，见 3.1 节）
-
-**生产容器（220）入口 `scripts/start.sh`**（docker-compose 的 python-app 服务 command）：
-
-1. **依赖就绪守卫**：flask/u2/uiautodev/rapidocr/cv2/fastmcp 全可用则跳过安装；否则 `pip install -r requirements.txt` 并做 cv2 环境修复（卸 GUI opencv → 装 headless）
-2. **后台拉起 MCP server**：`MCP_ENABLED` 默认 `1` 时执行 `python3 -m mcp_server.mcp_server`（`MCP_ALLOW_WRITE=1`、`MCP_PLATFORM_USER` 默认 admin、`MCP_PLATFORM_PASS` 兜底 `admin123`），日志 `/tmp/mcp_server.log`
-3. **前台启动主服务**：`exec python -u web_server.py`
-
-注意：
-
-- `scripts/supervise.sh` **只守护 web_server，不拉起 MCP**——容器场景 MCP 由 start.sh 拉起，不要用 supervise.sh 替代容器入口
-- **AI 控制台依赖 MCP**：`AGENT_MCP_URL` 默认 `http://127.0.0.1:8033/mcp`（`mcp_agent/config.py`）
-- 手动起 web_server 需另启 MCP：`MCP_ALLOW_WRITE=1 python -m mcp_server.mcp_server`
-- **改过 admin 密码务必同步 `MCP_PLATFORM_PASS`**（start.sh 兜底 `admin123` 会登录失败）
-- 发布链路：dev 开发测试完成 → 负责人确认合并 main → 220 `git pull` → 重启 python-app 容器生效（详见 DEVELOPMENT §6）
-
-### 2.5 验证部署
-
-1. 控制台看到 `启动服务: http://localhost:18050/` 即成功
-2. 浏览器访问 `http://localhost:18050/`
-3. 用 `admin/admin123` 登录
-4. 监控页应显示设备池中的设备（本机 adb 在线 + SQLite 配置清单，serial 形如 `100.100.10.x:5555`）
-
----
-
-## 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 状态在内存）。
->
-> **崩溃后占用自愈（需人工核实）**：历史 `AUTO_RELEASE_STALE_OCCUPY` 机制已随 STF 摘除失效（全库代码不再读取该配置）。设备池的占用互斥仍在（任务 running/connecting 的设备会被锁），但崩溃后残留占用如何释放、是否自动清理，需按当前实现核实后补写本节。
-
-**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**：在 `.env` 写固定 `WEB_SECRET_KEY`（`python -c "import secrets;print(secrets.token_hex(32))"` 生成）；未配置时启动随机生成（每次重启登录态失效，生产务必配置固定值）
-- **限制访问**：生产环境把 `WEB_HOST` 改为 `127.0.0.1`，配合反向代理
-- **防火墙**：只开放必要端口
-
-### 3.4 日志管理
-
-- 日志自动滚动（10MB 一份，保留 5 份）
-- 日志目录 `logs/`，可在"日志"Tab 在线查看
-- 长期运行建议定期清理或配置 logrotate
-
-### 3.5 数据备份
-
-**优先推荐平台功能「系统 → 数据备份导出/导入」（仅 admin）**：
-
-- **导出**：`POST /api/system/backup/export` → 用 sqlite 在线备份 API 对 `data/users.db` 做一致快照，打包 zip（`users.db` + `manifest.json` + 可选 `apks/*.apk`）
-- **导入**：上传 zip/`.db` → 校验预览（完整性/必需表/schema 版本告警）→ 确认后自动把当前库快照到 `data/backups/pre_restore_*.db`（安全网可回滚）→ 落 `data/restore_pending/` → **重启 web_server 生效**（web_server 在 `init_db` 前自动消费恢复任务）
-
-目录与常量：
-
-| 目录 | 用途 |
-|---|---|
-| `data/backups/` | 导出临时 zip + 恢复前快照 `pre_restore_*.db` + 校验失败的 `restore_failed_*` |
-| `data/restore_staging/` | 导入暂存，TTL 30 分钟未应用自动清理 |
-| `data/restore_pending/` | 待生效恢复任务（重启时消费） |
-
-常量 `BACKUP_DIR` / `RESTORE_STAGING_DIR` / `RESTORE_PENDING_DIR`（config.py L63-68，非 .env，已 .gitignore）。
-
-手工备份 `data/` 目录仍可作兜底，但**整库恢复建议走上述功能**（在线一致快照 + 预恢复备份 + 重启原子生效，避免手工替换被 WAL/占用文件破坏）。
-
----
-
-## 4. 网络配置
-
-### 4.1 端口说明
 
 | 端口 | 服务 | 说明 |
 |------|------|------|
-| 18050 | Web 后台 | 主服务端口（config.py 可改） |
+| 18050 | Web 后台 | `config.py` 的 `WEB_PORT`；绑定失败会自动回退候选端口 |
-| 20242 | uiautodev | 元素抓取服务（自动启动，固定端口） |
+| 8033 | MCP Server | `MCP_HTTP_PORT`；由 `scripts/start.sh` 拉起 |
-| 8033 | MCP | MCP 手机控制 Server（scripts/start.sh 自动拉起，`MCP_ENABLED=0` 可关） |
+| 20242 | uiautodev | 元素抓取；`web_server.py` 启动时自动 Popen |
-| 5555 | adb | 设备 adb 网络端口（设备端） |
+| 5555 | 设备 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. 更新升级
+## 2. 安装与启动
 
-### 5.1 代码更新
+### 2.1 获取代码与依赖
 
 ```bash
-# 1. 停止服务
+cd auto_control
-# 2. 替换代码文件（或解压新的 zip）
-# 3. 重新安装依赖（如有新增）
 pip install -r requirements.txt
-# 4. 启动服务
+```
+
+主要依赖：Flask / Flask-Login / Flask-SQLAlchemy / APScheduler / uiautomator2 / uiautodev / rapidocr_onnxruntime / **opencv-python-headless** / pyaxmlparser / fastmcp / paramiko。
+
+> ⚠️ **服务器与容器环境必须用 `opencv-python-headless`**：GUI 版 `opencv-python` 依赖 X11 库，`python:slim` 容器里 `import cv2` 直接崩 → OCR 步骤抛异常 → 任务失败退出。版本锁 `<5`（5.x wheel 没有 cv2 模块）。`scripts/start.sh` 会自动做这个替换。
+
+### 2.2 配置
+
+**密钥类配置统一放项目根 `.env`**（不入 git，模板见 `.env.example`）。加载方式：逐行解析 + `os.environ.setdefault`（**真实环境变量优先**）。
+
+生产至少配：
+
+```ini
+WEB_SECRET_KEY=<随机 64 hex>            # 不配则每次重启登录态失效
+DEPLOY_ENV=prod                         # 声明"这是生产环境"，与库名 auto_control 绑定
+DB_HOST=<MySQL 主机>                     # 数据库目标（不配则回退 SQLite，生产会拒绝启动）
+DB_USER=<账号>
+DB_PASSWORD=<口令>
+DB_NAME=auto_control
+# USB_ADB_HOST=100.100.10.1             # USB 设备所在的部署机（默认值通常可用）
+# TAILSCALE_API_KEY=<...>               # 需要 Tailscale 管理功能时
+# MCP_PLATFORM_PASS=<admin 的密码>       # 改过 admin 密码必须同步，否则 MCP 登录失败
+```
+
+**防混库**（`DEPLOY_ENV` 与库名/库标签双向校验，配置项说明见 [DEVELOPMENT.md](DEVELOPMENT.md) §4.2
+与 `.env.example` 的「数据库」段）：启动时若
+「`.env` 声明的环境」与「库名」或「库中登记的 `app_meta.deployment_env`」不符，**直接拒绝启动**并打印
+两边分别是什么。每次启动还会打印一条横幅写明当前连的是哪个库（生产用 WARNING 级），
+页面顶部也常驻一个环境徽标（生产红底 `PROD · <库>`，开发灰底 `DEV`），
+**浏览器标签名也带环境前缀**（开发 `dev-设备自动化后台`，生产 `设备自动化后台`）——
+同时开着两个环境时一眼分得清哪个标签是哪个。
+两个逃生阀 `DB_ALLOW_ENV_MISMATCH` / `DB_ALLOW_SQLITE_FALLBACK` 默认关闭。
+
+其余配置项与默认值见 [DEVELOPMENT.md](DEVELOPMENT.md) §配置速查。
+
+### 2.3 启动
+
+```bash
 python web_server.py
 ```
 
-### 5.2 数据库迁移
+启动成功日志：
 
-- SQLite 表结构变化时，`init_db()` 会自动 `db.create_all()` 创建新表
+```
-- 旧 `groups.json` / `jobs.json` 首次启动自动迁移到 SQLite
+[INFO] [core.worker] 心跳看门狗已启动
-- 迁移后 JSON 文件归档为 `.migrated`（保留备份，不再迁移）
+[INFO] [core.tm] 从数据库加载 X 个分组, X 个任务
+[INFO] [web] uiautodev 服务已启动 (PID=...)
+[INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
+[INFO] [web] 设备池预连接完成: X 台在线
+[INFO] [web] 启动服务: http://localhost:18050/
+```
 
-### 5.3 注意事项
+默认账号 **admin / admin123**（**登录后立即改密**）。
-
-- **修改 `core/` 目录下的文件后必须重启 web_server**（`debug=False` 不热重载）
-- **修改 `templates/` 下的 HTML 文件**：Flask 模板默认不缓存，但建议重启确保生效
-- **修改 `tasks/` 下的文件后必须重启**（任务注册在启动时完成）
 
 ---
 
-## 6. 故障排查
+## 3. 生产部署（220 容器）
 
-### 6.1 启动失败
+生产环境固定为 **192.168.20.220** 的 `/mnt/data/openstf/auto_control`，由 `docker-compose` 的 **`python-app`** 容器运行：
 
-| 现象 | 原因 | 解决 |
+| 项 | 值 |
-|------|------|------|
+|----|----|
-| `ModuleNotFoundError: No module named 'flask'` | 依赖未安装 | `pip install -r requirements.txt` |
+| 宿主目录 | `/mnt/data/openstf/auto_control`（git 仓库，分支 `main`） |
-| `WinError 10013` | 端口被排除/权限不足 | 改端口或用管理员运行 |
+| 容器挂载 | 宿主目录 → 容器 `/app` |
-| `WinError 10048` | 端口被占用 | 改端口或杀占用进程 |
+| 网络 | `network_mode: host` |
-| 监控页设备列表为空 | 设备不在池中 / adb 连不上 | 「工具 → 设备池管理」确认已添加且在线，检查设备网络与 5555 端口 |
+| 入口 | `scripts/start.sh`（`command`） |
-| AI 控制台报「MCP server(8033) 不可达」 | MCP Server 未启动/不可达 | 启动 MCP Server：本机 `MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> MCP_AUDIT_FILE=data/mcp_audit.log python -m mcp_server.mcp_server`；220 容器由 `scripts/start.sh` 自动拉起（`MCP_ENABLED=0` 会关） |
+| 重启策略 | `restart: unless-stopped` |
+| 同级容器 | `adb`（USB 远程 adb server，5037）、以及该机器上其它无关服务 |
 
-### 6.2 设备连接失败
+> ⚠️ **`docker-compose.yaml` 不在仓库里**，只存在于 220 上；仓库里只有 `scripts/start.sh` 这一半。
 
-| 现象 | 原因 | 解决 |
+### 3.1 容器入口 `scripts/start.sh` 做三件事
-|------|------|------|
-| `DeviceOfflineError` | u2 连接超时 / atx-agent 无响应 | 检查设备网络，重启设备或重新推送 atx-agent |
-| `u2.connect 超时` | atx-agent 无响应 | 重启设备/重新推送 atx-agent |
-| `adb connect failed` | 设备网络不通/端口未开放 | 检查设备 IP 和 5555 端口 |
-| 设备显示离线 | 状态缓存/误报 | 管理后台设备池「重连」，或「扫描前台 App」复测 |
 
-### 6.3 任务不执行
+1. **依赖就绪守卫**：检查 9 个模块 + `cv2` 可用性；全部可用就跳过安装
+2. **依赖安装与修复**（仅在需要时）：`pip install -r requirements.txt` → 卸载 GUI `opencv-python` → 装 `opencv-python-headless>=4.8,<5` → 再验 cv2，仍异常则 `--force-reinstall`
+3. **拉起 MCP + 前台启动 Web**：
 
-| 现象 | 原因 | 解决 |
+```
-|------|------|------|
+MCP_ALLOW_WRITE=1                     # 脚本内强制开启写操作
-| 任务列表有任务但不执行 | 任务未启用 / cron 未到点 | 检查 `enabled` 和 `schedule` |
+MCP_PLATFORM_USER=${…:-admin}
-| 立即执行无反应 | 无可用设备 | 检查设备池是否有空闲设备 |
+MCP_PLATFORM_PASS=${…:-admin123}      # ← 改过 admin 密码必须覆盖它
-| worker 状态 error | 查看日志的 `last_error` | 查看 `logs/core.log` 和 `logs/task.log` |
+MCP_AUDIT_FILE=${…:-/tmp/mcp_audit.log}
-| 看门狗误杀 | 长操作未心跳 | 在长循环内加 `self.heartbeat()` |
+python3 -m mcp_server.mcp_server > /tmp/mcp_server.log 2>&1 &
+exec python -u web_server.py
+```
 
-### 6.4 日志查看
+> **`scripts/supervise.sh` 只守护 web_server，不拉起 MCP**——容器场景不要用它替代 `start.sh`。
+
+### 3.2 发布流程
 
 ```bash
-# 查看核心日志
+cd /mnt/data/openstf/auto_control
-# 方式一：Web 后台"日志"Tab
+git fetch origin && git checkout main && git pull --ff-only origin main
-# 方式二：直接看文件
+docker restart python-app
-# logs/core.log   — adb/worker/task_manager
-# logs/task.log   — 任务执行
-# logs/web.log    — Web 请求
-# logs/action.log — 操作执行
 ```
+
+重启后验证：
+
+```bash
+curl -s http://127.0.0.1:18050/api/health          # {"ok":true,"status":"up",...}
+ss -ltnp | grep -E ':(18050|8033|20242)'           # 三个端口都在
+docker exec python-app tail -5 /tmp/mcp_server.log # MCP 已启动
+tail -20 logs/web.log                              # 无 ERROR/Traceback
+```
+
+**发布前检查清单**：
+
+- [ ] 本机 `dev` 已合并 `main` 并推送（且经负责人确认）
+- [ ] 新增依赖已进 `requirements.txt`
+- [ ] **新增持久化表已登记进备份覆盖清单**（`core/system_backup.py`，红线）
+- [ ] 文档已同步（`doc/`）
+- [ ] 若改过 admin 密码 → 同步容器环境变量 `MCP_PLATFORM_PASS`
+- [ ] 启动日志里没有"任务类型已不存在"告警（有则说明库里有历史遗留任务，需人工处理）
+
+> ⚠️ **重启会终止正在运行的任务**（worker 状态在内存）。选低峰期，或先在监控页「停止全部」。
+
+---
+
+## 4. 进程守护（非容器场景）
+
+| 方式 | 用法 | 说明 |
+|------|------|------|
+| `scripts/supervise.sh` | `PYTHON=./.venv/bin/python bash scripts/supervise.sh` | 崩溃自动重启；300s 内最多重启 10 次；**不拉起 MCP** |
+| systemd | `ExecStart=/usr/bin/python3 web_server.py` + `Restart=always` | Linux 通用 |
+| NSSM | `nssm install auto_control <python> web_server.py` | Windows |
+| Docker | `restart: unless-stopped` | 生产用法 |
+
+> 进程守护只保证**服务重启**，不恢复已运行的任务。生产建议加健康检查打 `/api/health`（`interval 30s` / `timeout 5s` / `retries 3` / `start_period 10s`）。
+
+---
+
+## 5. 数据备份（重要）
+
+### 5.1 平台内置（推荐）
+
+**「系统 → 数据备份 / 导入恢复」**（仅管理员）：
+
+- **导出**：`POST /api/system/backup/export` → 把当前库（MySQL 或回退模式的 SQLite）
+  整库一致快照成一份 SQLite 归档 → 打包 zip（`users.db` + `manifest.json` + 可选 `apks/*.apk`）
+- **导入**：上传 zip/`.db` → 校验预览（完整性 / 必需表 / schema 版本 / 未登记表 / **来源环境**）
+  → 确认后自动把当前库导出一份 `data/backups/pre_restore_*.zip`（安全网，可再导入回来）
+  → 落 `data/restore_pending/` → **重启服务生效**
+
+> **SQLite 在这里是"备份交换格式"，不是运行时数据库。** 所以归档里永远是一个 `users.db`，
+> 无论平台连的是 MySQL 还是 SQLite —— 前端接口、校验逻辑、老备份的兼容性都不用变，
+> 也不依赖 `mysqldump` 这类外部二进制（容器是 `python:slim`，没有 MySQL 客户端）。
+
+**恢复是怎么生效的**：重启时 `consume_pending_restore()` 在**单个事务内** `DELETE` 全表 +
+分块 `INSERT`，任何一步失败就回滚——当前数据保持原样，不会留下半新半旧的库。
+坏归档会被挪到 `data/backups/restore_failed_*/` 且不阻塞启动。
+
+**跨环境导入默认拒绝**：备份的 manifest 里记了来源环境（`deployment_env`），
+若与当前库环境不一致（例如拿生产备份灌 dev 库），预览会弹黄框告警、直接应用会被拒绝；
+确需跨环境时在预览页勾选「允许跨环境导入」。
+
+### 5.2 备份覆盖清单（红线）
+
+覆盖清单 = `core/system_backup.py` 的 `SUMMARY_TABLES`，**由模型元数据自动派生**：
+
+```python
+SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
+```
+
+当前 12 张表：`app_meta` / `user` / `device_group` / `task_job` / `custom_action` /
+`apk_file` / `device` / `pending_device` / `agent_conversation` / `agent_experience` /
+`experience_audit` / `agent_action`。完整说明见 [DATA_MODEL.md](DATA_MODEL.md) §6。
+
+> **新增一张 ORM 表，就自动进了覆盖清单**，不可能再漏（2026-09-10 动作库 `agent_action`
+> 曾因手工维护漏登记，数据其实在快照里，只是清单没列 → 被误判为"没有备份"）。
+> 还需要手工做的只有：给新表补 `TABLE_LABELS` 的中文标签。
+> 导出侧有**覆盖自检**（登记表缺失 → `manifest.coverage_missing` + 日志告警）；
+> 导入侧有**反向自检**（备份含未登记表 → 预览告警）。
+
+### 5.3 目录与手工备份
+
+| 目录 | 用途 | 可否用环境变量改 |
+|------|------|------------------|
+| `data/backups/` | 导出临时 zip、`pre_restore_*.zip`（导入前安全网）、`restore_failed_*` | `DATA_BACKUP_DIR` |
+| `data/restore_staging/` | 导入暂存（TTL 30 分钟自动清理） | `DATA_RESTORE_STAGING_DIR` |
+| `data/restore_pending/` | 待生效恢复任务（重启时消费） | `DATA_RESTORE_PENDING_DIR` |
+
+> 这三个环境变量主要给**自动化测试**用：测试必须把恢复目录指到临时位置，
+> 否则测试造出来的"待生效恢复任务"会在服务下次重启时被当成用户的操作消费掉。
+
+连 MySQL 时 `data/users.db` 及其 `-wal`/`-shm` **不再被读写**（只有回退模式才用），
+可以留作历史归档。手工整目录备份 `data/` 仍可作兜底，但**整库恢复建议走内置功能**
+（一致快照 + 预恢复备份 + 重启时事务替换）。
+
+> ⚠️ 备份 zip 含**用户口令哈希与 AI 控制台 API Key（明文）**，注意保管与传输。
+
+---
+
+## 6. 安全加固
+
+- **改默认密码**：登录后立即改 admin 密码；需要多人使用时在「用户」页建普通用户并只勾必要权限位
+- **固定会话密钥**：`.env` 写 `WEB_SECRET_KEY`（`python -c "import secrets;print(secrets.token_hex(32))"`）
+- **限制访问面**：`WEB_HOST` 改 `127.0.0.1` + Nginx 反代，或靠防火墙只放必要端口
+- **MCP 端点（8033）自身无鉴权**：它只做**出站**登录平台，不对入站做校验 → **必须靠网络隔离**（同机/内网），不要直接暴露公网
+- **写操作门控**：`MCP_ALLOW_WRITE=0`（默认）时 MCP 只读
+- **HTTPS/80 端口**：用 Nginx 反代
+
+```nginx
+location / { proxy_pass http://127.0.0.1:18050; proxy_set_header Host $host; }
+```
+
+---
+
+## 7. 升级与迁移
+
+### 7.1 代码升级
+
+```bash
+git pull --ff-only origin main
+docker restart python-app        # 容器场景
+# 或 systemd: systemctl restart auto_control
+```
+
+- **改 `core/`、`tasks/`、`templates/` 后必须重启**（`debug=False` 不热重载）
+- 改前端 JS 后浏览器需**强刷**（Ctrl+Shift+R）
+
+### 7.2 数据库迁移
+
+- **表结构变化**由 `init_db()` 自动处理：`create_all()` 建缺表 + `_sync_columns()` 补缺列（幂等，失败不阻塞启动，见 [DATA_MODEL.md](DATA_MODEL.md) §4）
+- 旧 `groups.json` / `jobs.json` 首次启动自动迁移并归档为 `.migrated`
+- **跨版本恢复**：用「导入恢复」上传旧库 → 预览会提示 schema 版本差异 → 应用后重启（新版本会自动补列/补空表）
+
+#### SQLite → MySQL（一次性）
+
+首次把平台从单文件 SQLite 换到 MySQL 时，用迁移脚本搬数据：
+
+```bash
+# 0) 先在 .env 里配好 DB_HOST/DB_USER/DB_PASSWORD/DB_NAME（或用 --target-url）
+# 1) 干跑：审计源库 + 建目标 schema，不搬数据
+python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev --dry-run
+# 2) 正式搬（目标库已有的数据会被整表替换；单事务，失败自动回滚）
+python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev
+# 3) 复验（只比对不写）
+python scripts/migrate_sqlite_to_mysql.py --sqlite data/users.db --env dev --mode verify
+```
+
+脚本做的事：源库完整性校验 → **列宽审计**（SQLite 不强制长度，MySQL 严格模式下超长会直接报错，
+所以先拦下来）→ 建目标 schema（复用平台的 `create_all` + 补列 + 唯一索引）→ 逐表搬行
+（单事务）→ **逐表行数 + 全行 SHA-256 比对** → 写库环境标签与 `schema_version`。
+
+> `--env prod` 必须额外加 `--allow-prod`，交互终端还要手打 `prod` 确认（这是唯一会往生产库灌数据的入口）。
+> 目标库若已登记为别的环境（`app_meta.deployment_env`），除非 `--force-env` 否则拒绝。
+
+建库建账号见 `scripts/sql/init_mysql_5.7.sql`（utf8mb4 + `utf8mb4_bin`，两个库对应 dev/prod）。
+
+### 7.3 跨机迁移（换部署机）
+
+1. 新机装依赖、放好 `bin/adb/` 与 **同一把 adb key**
+2. 复制 `.env`
+3. 老机「系统 → 数据备份」导出 zip → 新机「导入恢复」上传并应用
+4. **重启新机服务**（恢复任务在 `init_db` 之前被消费）
+5. 核对设备池在线状态与任务列表
+
+---
+
+## 8. 故障排查
+
+### 8.1 启动类
+
+| 现象 | 原因 / 处理 |
+|------|------------|
+| `ModuleNotFoundError: No module named 'flask'` | 依赖未装：`pip install -r requirements.txt` |
+| `WinError 10013`（Windows） | 端口被排除/权限不足：`netsh interface ipv4 show excludedportrange protocol=tcp` 查看，或改 `WEB_PORT` |
+| `WinError 10048` | 端口被占用：换端口或杀占用进程 |
+| 启动日志只有一半 | 以 WSGI 方式 import 了模块（只跑了 import 期的装配，没跑 `__main__` 分支）；直接 `python web_server.py` |
+| 登录后立刻掉线 | 没配 `WEB_SECRET_KEY`（每次重启换密钥） |
+| 容器里 `import cv2` 崩 | 装成了 GUI 版 opencv：换 `opencv-python-headless`（`start.sh` 会自动修） |
+
+### 8.2 设备类
+
+| 现象 | 处理 |
+|------|------|
+| 设备显示离线 | 「设备池管理 → 一键重连」；确认设备在线、网络互通（生产：同 tailnet） |
+| **设备"断联"但其实没关机** | 多数是**换了 IP**（DHCP 重新分配）：设备池管理点「**换地址**」把记录迁到新地址（名称与分组/任务引用自动保留）；已采集指纹的设备会被扫描自动识别为"已有设备换了地址"，确认即认领 |
+| 加了设备但不被调度 | 只连上 adb 不够，必须在**设备池**中且 `enabled=true` |
+| `u2.connect 超时` | atx-agent 无响应：重启设备或重新推送 atx-agent（基类有 30s 超时保护） |
+| 大量设备同时连接时超时 | Windows 端口耗尽（`WinError 10048`）：代码会打 `[transient]` 并退避 120s 重试；减少并发或调整系统 TIME_WAIT |
+| 设备 `unauthorized` | adb key 变了：恢复原 key |
+
+### 8.3 任务类
+
+| 现象 | 处理 |
+|------|------|
+| 任务不执行 | 检查 `enabled`、`schedule`、是否在运行窗口内、目标设备是否在线 |
+| 立即执行无反应 | 无可用设备（`resolve_serials` 为空）；看 `logs/core.log` |
+| 任务"成功"但没做事 | 步骤类型未知/缺必填参数会被**告警跳过**；查 `logs/task.log` 的 WARNING |
+| 执行报"任务类型 xxx 已不存在" | 库里残留了已删除类型的任务（如历史 `douyin_nurture`）：在「任务」页删除或改用现有类型。启动日志也会点名列出 |
+| 长任务被看门狗杀 | 120s 无心跳：业务循环里要周期性 `self.heartbeat()` |
+| 任务卡在 running | 监控页「停止选中」；必要时重启服务（重启会清空内存状态） |
+
+### 8.4 其它
+
+| 现象 | 处理 |
+|------|------|
+| 元素抓取按钮不可用 | uiautodev（:20242）没起来；`web_server.py` 启动时自动拉起，手动可 `python -m uiautodev server --no-browser` |
+| 抓元素超时 | 部分设备 dump 慢（~18s）超过平台超时（8s），见 [backlog/TODO.md](backlog/TODO.md) |
+| AI 控制台报"MCP server(8033) 不可达" | MCP 没启动：容器由 `start.sh` 拉起，本机手动 `MCP_ALLOW_WRITE=1 python -m mcp_server.mcp_server` |
+| AI 控制台报 401 | 模型 API Key 无效/过期：在「AI 控制台 ⚙ 配置」重填 |
+| 备份导入后没变化 | **必须重启服务**，恢复任务在重启时才被消费 |
+
+日志位置：`logs/core.log`（adb/调度）、`logs/task.log`（任务执行）、`logs/web.log`（Web/AI）、`logs/action.log`；容器内 MCP 日志 `/tmp/mcp_server.log`。

doc/DEVELOPMENT.md

@@ -1,267 +1,242 @@
 # 开发手册（DEVELOPMENT）
 
-面向本项目开发者：开发流程、git 工作流、环境说明、技术红线、本地开发、常见开发任务。
+> 适用读者：所有参与 `auto_control` 开发的人。**动手前先读 §2 技术红线**。
+> 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)（架构，先懂再改）、[DATA_MODEL.md](DATA_MODEL.md)（表结构）、[doc/README.md](README.md)（文档索引与维护约定）。
 
 ---
 
-## 1. 开发流程与 git 工作流
+## 1. 开发流程
 
 ### 1.1 分支策略
 
 | 分支 | 用途 |
 |------|------|
-| `dev` | **开发分支**，所有新功能/修复都在这里开发 |
+| `dev` | 开发分支，所有新功能/修复从它切出、合并回它 |
-| `main` | **生产分支**（主分支），只放已确认的稳定版本 |
+| `main` | 生产分支，只放已确认的稳定版本 |
+| `fix/xxx` · `feat/xxx` · `chore/xxx` | 单个改动的临时分支（从 `dev` 切出） |
 
-生产环境 = 部署机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（python-app 容器运行 `web_server.py`）。
+生产环境 = 部署机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（`python-app` 容器）。
 
-### 1.2 git 操作铁律（重要）
+### 1.2 git 铁律
 
-**所有 git 操作都必须先经项目负责人明确确认后才能执行**，包括但不限于：
+**所有 git 操作都必须先经项目负责人明确确认**，包括但不限于 `commit` / `push`（**即使 push 到 dev 也要确认**）/ `merge` / `rebase` / `reset` / `branch -D`。
 
-- `commit` / `push`（**即使 push 到 dev 也要确认**）
+**标准流程**：
-- `merge`（dev → main）
-- `revert` / `checkout` / `reset` / `branch -D` 等
-
-**标准流程：**
 
 ```
-1. 在 dev 分支开发、本地测试
+① 本机新建分支          fix/xxx 或 feat/xxx（从 dev 切出）
-2. 完成改动 → 把改动清单 + 建议 commit 信息 列给负责人
+② 分支上开发 + 自测     跑通本机（服务/接口/页面），能自测就别只靠"看代码没问题"
-3. 负责人确认 → 才能 commit + push dev
+③ 交负责人确认          ★ 未经确认不合 dev
-4. 需要发布 → 负责人确认后再合并到 main
+④ 合并到 dev            确认通过后（保持线性：rebase 后 ff-merge）
-5. 部署生产 → 负责人明确指示后才 pull 到 220
+⑤ dev 整体就绪          功能齐全、验证完毕
+⑥ 合并到 main           ★ 负责人确认后
+⑦ 生产 220 部署         git pull → docker restart python-app → 验证（见 DEPLOY.md §3）
 ```
 
-> 不允许"开发完顺手就 commit/push"。即使是一次性小改动，也要先确认。
+> 每个改动**单独分支 + 单独 commit**，主题单一，便于评审与回退。不允许"开发完顺手 commit/push"。
 
 ---
 
-## 2. 环境说明
+## 2. 技术红线（违反会打断共享 adb transport 或造成生产事故）
 
-| 环境 | 位置 | 说明 |
+| # | 红线 | 为什么 | 代码里的体现 |
-|------|------|------|
+|---|------|--------|-------------|
-| 开发机 | 本机（192.168.20.57） | `.venv` + 本地运行 `web_server.py` |
+| 1 | **绝不 `adb kill-server`** | 会断掉所有设备的 adb transport，运行中任务全废 | `core/adb_helper.py` 只 connect 不 kill；Web 层硬拦截 `kill-server`/`disconnect` 字符串 |
-| 生产机 | 部署机 220 的 `auto_control` | python-app 容器，`network_mode: host` |
+| 2 | **绝不对 `IP:5555` 设备 `adb disconnect`** | 该地址的 adb transport 是共享的 | `adb_disconnect` **全项目零调用方**；`STFDevice.release()` 空实现 |
-| STF 服务 | ~~`192.168.20.220:7100`~~ | 已停用（代码已摘除依赖）。注意：此处"已停用"与 [STF_REMOVAL.md](STF_REMOVAL.md) 的"待人工确认"项矛盾（220 侧是否已 `docker stop stf` 未核实），需以 220 实际为准 |
+| 3 | **空闲设备扫描不主动 connect/disconnect** | 避免扰动共享连接 | 前台扫描对空闲设备直接返回"空闲"；设备发现用 socket 探测 |
-| adb 容器 | 220 上 `adb`（host 网络 5037） | USB 设备远程 adb server；网络设备补连用 |
+| 4 | **adb key 保持历史 key 不变** | 设备信任该 key，换 key 全部 `unauthorized` | 部署沿用 `~/.android/adbkey` |
-| 设备 | Tailscale `100.100.10.x:5555` | Xiaomi 舰队，本机 `100.100.10.2` 在 tailnet 内 |
+| 5 | **生产（220）默认只读** | 生产事故成本高 | 任何写操作（pull/重启/改文件）都需负责人确认 |
-| uiautodev | 本机 `20242` | 元素抓取服务（web_server 自动拉起） |
+| 6 | **新增持久化表必须登记备份覆盖清单** | 漏登记 = 等于没备份 | `core/system_backup.py` 的 `SUMMARY_TABLES` + `TABLE_LABELS`，详见 [DEPLOY.md](DEPLOY.md) §5.2 |
+| 7 | **功能/配置/接口改动必须同步文档** | 文档落后会误导开发与运维 | 见 §6；索引 [doc/README.md](README.md) |
 
-### 2.1 adb key（关键）
+### 其它开发约束
 
-- 本机 `~/.android/adbkey` 沿用历史 key（原取自 STF adb 容器，全部设备都信任）
+- **`web_server.py` 以 `debug=False` 运行**：改 `core/`、`tasks/`、`templates/` 后**必须重启**；改前端 JS 后**强刷浏览器**
-- **不要随意更换 key**——设备会变 unauthorized 连不上
+- **任务参数放各自 `tasks/<app>/` 顶部**，不放 `config.py`
-- 旧 key 备份在 `~/.android/adbkey.local.bak`
+- **运行时数据不提交 git**：`data/`、`logs/` 全是运行时产物
-- 生产环境的容器也需要用这把 key（部署时处理）
+- **不要移除分页与错峰**：监控/列表页已分页（100 台设备只渲染 10 行/页）；任务批量触发已错峰（`_START_STAGGER_SEC`）
-
+- **不要手工改库结构**：走 `SCHEMA_MIGRATIONS`（模型表）或幂等原生建表
-### 2.2 设备连接方式
-
-- 设备 serial 是 `IP:5555`（Tailscale 地址），**直连**优先（只 connect、绝不 disconnect）
-- USB 设备（serial 无冒号）：插本机走本地 adb；插 220 走远程 adb server（`USB_ADB_HOST:5037`）
-- 本机已在 tailnet 内，直连可靠且快（<1s）
-- 设备加入/退出平台：工具 → 设备池管理（SQLite 清单，自动连接 + 型号采集）
-
-### 2.3 配置键速查（`config.py` / `.env`）
-
-`.env` 加载方式：项目根目录逐行解析、`os.environ.setdefault`（环境变量已设则不覆盖）。以下默认值以 `config.py` 为准：
-
-| 键 | 默认值 | 说明 |
-|------|------|------|
-| `WEB_HOST` / `WEB_PORT` | `0.0.0.0` / `18050` | Web 后台监听（18050 避开 Windows 动态端口范围） |
-| `DATA_DIR` / `APK_DIR` | `data/` / `data/apks/` | 持久化数据目录 / APK 存储目录 |
-| `BACKUP_DIR` / `RESTORE_STAGING_DIR` / `RESTORE_PENDING_DIR` | `data/backups` / `data/restore_staging` / `data/restore_pending` | 系统备份：导出 zip、导入暂存、待重启生效的恢复目录 |
-| `ADB_PATH` | `bin/adb/adb`（Windows 为 `adb.exe`） | 按平台自动识别，代码只拼路径 |
-| `USB_ADB_HOST` / `USB_ADB_PORT` | `100.100.10.1` / `5037` | 220 的 adb 容器（host 网络），驱动远程 USB 设备 |
-| `DISCOVERY_PORT` / `DISCOVERY_SUBNETS` / `DISCOVERY_INTERVAL` | `5555` / 局域网+Tailscale 网段 / `60` | 设备自动发现；可在工具页设备池面板改，存 `app_meta` `discovery_*` 覆盖默认 |
-| `TAILSCALE_API_KEY` / `TAILSCALE_TAILNET` | 空 / 空 | 工具页 Tailscale 管理（官方 API v2） |
-| `WEB_SECRET_KEY` | 未配置则随机生成 | 会话密钥（web_server 读 `.env`；不配则重启登录态失效） |
-| `STF_URL` / `STF_TOKEN` / `STF_SSH_*` | 废弃 | STF 摘除后仅历史保留，代码不再使用 |
 
 ---
 
-## 3. 技术红线（开发限制）—— 违反会打断共享 adb transport，需人工恢复
+## 3. 本地开发
 
-这些是踩过坑后总结的，**任何修改都不能引入**。违反任何一条都会导致设备连接被全部重建（历史原因：STF provider 共享同一 adb transport，摘除 STF 后仍保留此约束）：
+### 3.1 安装
-
-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.html` 按 `base.js → list.js → monitor.js → editor.js → tasks.js → tools.js → apps.js → admin.js → agent.js → system.js` 的顺序用 `<script src>` 加载
-- **监控页/大列表已加分页**：100 台设备也只渲染 10 行/页，不要移除分页逻辑
-- **任务批量触发已错峰**（`_START_STAGGER_SEC`）：避免大量设备同时启动造成 adb 连接风暴，不要移除
-
----
-
-## 4. 本地开发手册
-
-### 4.1 首次安装
 
 ```bash
-# 用 Python 3.12 建 venv（README 推荐版本）
+python -m venv .venv
-/opt/homebrew/bin/python3.12 -m venv .venv
+# Windows: .venv\Scripts\activate    Linux/macOS: source .venv/bin/activate
-.venv/bin/pip install -r requirements.txt
+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 启动
+确认 adb key（沿用既有 key，否则设备连不上）：`ls -la ~/.android/adbkey`。
+
+### 3.2 启动
 
 ```bash
-.venv/bin/python web_server.py
+python web_server.py
-# 访问 http://localhost:18050/  账号 admin/admin123
+# 访问 http://localhost:18050/   admin / admin123
 ```
 
-启动日志看到以下即成功：
+需要 AI 控制台 / MCP 时，**另起一个进程**：
-```
+
-[INFO] [core.worker] 心跳看门狗已启动
+```bash
-[INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
+MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
-[INFO] [web] 启动服务: http://localhost:18050/
+  python -m mcp_server.mcp_server      # 默认 http://127.0.0.1:8033/mcp
 ```
 
-### 4.3 测试
+（容器里由 `scripts/start.sh` 自动拉起，不需要手动。）
 
-- **后端逻辑**：直接 `.venv/bin/python -c "..."` 调用（如 `tasks/`、`core/` 的函数）
+### 3.3 调试
-- **前端 UI**：Playwright（系统 `python3` 已装），脚本示例见下
-- **浏览器冒烟**：切 6 个 tab、开任务编辑器，确认无 JS 错误
 
-```python
+| 目的 | 做法 |
-# Playwright 冒烟示例（python3 运行）
+|------|------|
-from playwright.sync_api import sync_playwright
+| 看日志 | `logs/core.log`（adb/调度）、`task.log`（任务）、`web.log`（Web/AI）、`action.log`；或「日志」Tab |
-with sync_playwright() as p:
+| 看设备/任务状态 | 监控页；或 `GET /api/status`、`GET /api/health` |
-    b = p.chromium.launch(headless=True)
+| 后端逻辑验证 | 直接 `python -c "…"` 调用 `core/`、`tasks/` 的函数（如构造 worker 检查参数合并） |
-    pg = b.new_page()
+| 前端验证 | 无 npm/构建，改完强刷；浏览器控制台看报错 |
-    pg.goto("http://127.0.0.1:18050/login")
+| 接口 500 巡检 | `python scripts/regression_test.py`（**⚠️ 当前在 Windows 上会因 `signal.alarm` 报错**，Linux/macOS 可用） |
-    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 常用调试
+> **改了数据库/配置想复原**：删 `data/users.db*` 会丢数据，别这么干；用「系统 → 备份/导入」或先手工复制一份 `data/`。
 
-- **看日志**：`logs/` 下 `core.log` / `task.log` / `web.log` / `action.log`（10MB 滚动，保留 5 份）
+### 3.4 写测试的约定（重要）
-- **看设备/任务状态**：浏览器监控页，或 `GET /api/status`、`GET /api/health`
+
-- **停止设备/清异常**：监控页工具条用"停止全部 / 停止选中 / 清除全部异常"（`AUTO_RELEASE_STALE_OCCUPY` 等 STF occupy 残留清理配置代码已不再读取）；崩溃残留的 worker 状态重启即清零
+本仓库没有单元测试框架，验证靠"跑起来 + 真实调用"。写验证脚本时**必须**：
-- **打包项目**：`python scripts/pack.py`
+
+- **不要碰真实数据**：需要会话/任务/分组时**自建**（如 `POST /api/agent/conversations` 建专属会话），绝不要依赖"当前选中项"，也不要删自己没建的东西
+- **改配置前后都要回读校验**：改前 GET 存原值，收尾写回后**再 GET 比对**，不一致要显式报错
+- 临时数据用完即删，并核对"集合已复原"
+
+> 教训：曾用浏览器脚本跑 AI 控制台冒烟，脚本清空 `localStorage` 后前端自动选中了**用户最近的会话**，收尾的"删除测试会话"把用户真实会话删了；同一脚本还把 AI 配置改成了假值。恢复手段见 [DATA_MODEL.md](DATA_MODEL.md) §7 与 git 历史。
+
+---
+
+## 4. 配置速查
+
+### 4.1 配置文件与优先级
+
+- `config.py`：**程序级常量**（端口、路径、USB 远程 adb 等），改它要重启
+- `.env`（项目根，不入 git）：**密钥与可覆盖配置**，逐行解析 + `os.environ.setdefault`（**真实环境变量优先**）；**数据库目标（`DEPLOY_ENV` + `DB_*`）也在这里**
+- `app_meta`（数据库 KV）：**运行时可改的配置**（AI 配置、设备发现参数），在界面上改
+
+### 4.2 `config.py` 常量
+
+| 常量 | 默认值 | 来源 | 说明 |
+|------|--------|------|------|
+| `ADB_PATH` | `bin/adb/adb(.exe)` | 按平台自动 | **不可用 env 覆盖** |
+| `WEB_HOST` / `WEB_PORT` | `0.0.0.0` / `18050` | 硬编码 | 18050 避开 Windows 动态端口段 |
+| `DATA_DIR` / `APK_DIR` | `data/` / `data/apks/` | 代码计算 | |
+| `BACKUP_DIR` / `RESTORE_STAGING_DIR` / `RESTORE_PENDING_DIR` | `data/backups` / `data/restore_staging` / `data/restore_pending` | 代码计算 | 备份相关 |
+| `DEPLOY_ENV` | `dev` | `.env` 可覆盖 | 声明这套配置连哪个环境的库；与库名绑定（dev→`auto_control_dev`，prod→`auto_control`），不符拒绝启动 |
+| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | 空 / `3306` / 空 / 空 / 空 | `.env` 可覆盖 | MySQL 目标；`DB_HOST` 为空则回退 SQLite（**生产禁止静默回退**，需 `DB_ALLOW_SQLITE_FALLBACK=1`） |
+| `DB_CHARSET` / `DB_COLLATION` | `utf8mb4` / `utf8mb4_bin` | `.env` 可覆盖 | 排序规则必须用 `_bin`（逐码点比较，等价 SQLite 的大小写敏感语义） |
+| `DATABASE_URL` | 空 | `.env` 可覆盖 | 完整连接串，优先级最高；脚本临时指向别的库时用 |
+| `DB_ALLOW_ENV_MISMATCH` / `DB_ALLOW_SQLITE_FALLBACK` | `0` | `.env` | 逃生阀，见 [DEPLOY.md](DEPLOY.md) |
+| `USB_ADB_HOST` / `USB_ADB_PORT` | `100.100.10.1` / `5037` | `.env` 可覆盖 | USB 设备所在部署机的远程 adb server |
+| `TAILSCALE_API_KEY` / `TAILSCALE_TAILNET` | 空 | `.env` | Tailscale 管理功能 |
+| `DISCOVERY_PORT` / `DISCOVERY_INTERVAL` | `5555` / `60` | `.env` 可覆盖 | 设备发现（网段在工具页配置，存 `app_meta`） |
+| `DISCOVERY_SUBNETS` | 局域网 + Tailscale 网段 | **硬编码列表**（当前无 env 支持） | 默认扫描网段 |
+| `STF_*` | 空 | `.env` | **已废弃**，仅历史保留，代码不再使用 |
+
+### 4.3 进程读取的环境变量（不在 config.py）
+
+| 变量 | 默认 | 谁读 | 说明 |
+|------|------|------|------|
+| `WEB_SECRET_KEY` | 未配置则随机 | `web_server.py` | 会话密钥，**生产必须固定** |
+| `DISABLE_SCHEDULER` | 未设 | `core/task_manager.py` | 设任意值则**不启动 cron 调度器**（测试用） |
+| `DATA_BACKUP_DIR` / `DATA_RESTORE_STAGING_DIR` / `DATA_RESTORE_PENDING_DIR` | `data/backups` 等 | `config.py` | 备份/恢复目录改到别处；**自动化测试必须指到临时目录**（否则测试造的待生效恢复任务会在下次重启被当成用户操作消费） |
+| `MCP_ENABLED` | `1` | `scripts/start.sh` | =0 则不后台拉起 MCP |
+| `MCP_ALLOW_WRITE` | `0`（脚本内强制 1） | `mcp_server/config.py` | 写操作总开关 |
+| `MCP_PLATFORM_URL` / `_USER` / `_PASS` | `http://127.0.0.1:18050` / `admin` / 空 | `mcp_server/config.py` | 登录平台的凭据（改过 admin 密码要同步） |
+| `MCP_ALLOWED_SERIALS` | 空=不限 | 同上 | 逗号分隔白名单（语义缺口见 [backlog](backlog/TODO.md)） |
+| `MCP_HTTP_HOST` / `_PORT` | `0.0.0.0` / `8033` | 同上 | |
+| `MCP_SCREENSHOT_WIDTH` / `MCP_JPEG_QUALITY` | `540` / `70` | 同上 | 返回给模型的截图层参数 |
+| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log`（脚本兜底 `/tmp/mcp_audit.log`） | 同上 | 审计日志路径 |
+| `AGENT_API_BASE` / `AGENT_MODEL` / `AGENT_API_KEY` / `DEEPSEEK_API_KEY` | DeepSeek 默认地址 / 默认模型 / 空 | `mcp_agent/config.py` | **仅 CLI 用**；Web 端 AI 配置优先读数据库 `app_meta` |
+| `AGENT_MCP_URL` / `AGENT_MAX_STEPS` / `AGENT_TIMEOUT` / `AGENT_LANG` | `http://127.0.0.1:8033/mcp` / 40 / 120 / zh | 同上 | |
+| `ANDROID_ADB_SERVER_ADDRESS` / `_HOST` / `_PORT` | 未设 | **adb 客户端自身**（非本项目代码） | 把 adb 调用指向远程 server；两套变量名都要设 |
+
+> `mcp_server/config.py` 与 `mcp_agent/config.py` **不读 `.env`**（只读进程环境变量），与根 `config.py` 的行为不同。
 
 ---
 
 ## 5. 常见开发任务
 
-### 5.1 新增 App 任务
+> 每一项的"改哪里"清单也见 [ARCHITECTURE.md](ARCHITECTURE.md) §10。
 
-参照 `tasks/douyin/` 结构，详见 **[doc/TASK_DEV.md](TASK_DEV.md)**（6 步模板）。
+### 5.1 新增 HTTP 接口
 
-```
+1. 在对应功能域的 `web/xxx_api.py` 加 `@bp.route(...)` + 鉴权装饰器（`@login_required` / `@perm_required(PERM_X)` / `@admin_required`）
-tasks/<app>/
+2. 新蓝图需在 `web/__init__.py` 的 `register_blueprints` 里注册
-  __init__.py     # from . import task
+3. 更新 [API.md](API.md)（路由索引表 + 详细小节）
-  task.py         # DEFAULT_PARAMS + Worker + @register_task
-  actions/        # 专属操作（可选）
-```
 
-### 5.2 新增专属操作
+### 5.2 新增数据库字段/表
 
-在 `tasks/<app>/actions/` 建 `.py`，继承 `BaseAction` + `@register_action(ACTIONS)`，在 `__init__.py` import。
+- 模型改 `core/models.py`；新表 `create_all()` 会建
+- **老库**要在 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）
+- **新增表**：登记进 `core/system_backup.py` 的 `SUMMARY_TABLES` + `TABLE_LABELS`（**红线**）
+- 更新 [DATA_MODEL.md](DATA_MODEL.md) 与 [DEPLOY.md](DEPLOY.md) §5.2
 
 ### 5.3 修改前端
 
-| 文件 | 内容 |
+| 改什么 | 文件 |
-|------|------|
+|--------|------|
-| `templates/admin/monitor.html` | HTML 结构 + CSS + `<script src>` 引用 |
+| 页面结构 / 样式 / 引入脚本 | `templates/admin/monitor.html` |
-| `static/admin/`（base/list/monitor/editor/tasks/tools/apps/admin/agent/system.js） | 前端 JS（按 monitor.html 中 `<script src>` 顺序拆分加载，功能归属见各文件） |
+| 公共工具（API/权限/Toast/Tab） | `static/admin/base.js` |
+| 列表分页排序 | `static/admin/list.js` |
+| 各功能域逻辑 | `static/admin/{monitor,editor,tasks,tools,apps,admin,agent,system,markdown}.js` |
 
-改完**强刷浏览器**（Cmd/Ctrl+Shift+R），必要时重启 web_server。
+新增 JS 模块：建文件 → 在 `monitor.html` 里按依赖顺序加 `<script src>` → 更新 [ARCHITECTURE.md](ARCHITECTURE.md) §6.3 与本文 §5.3。
 
-### 5.4 新增 API
+### 5.4 新增步骤类型 / 任务类型
 
-路由按功能域放在 `web/` 蓝图包（`web/__init__.py` 的 `register_blueprints(app)` 统一注册 10 个蓝图：auth / monitor / tasks / admin / tools / devices / apks / tailscale / agent / system）。
+见 [TASK_DEV.md](TASK_DEV.md)（步骤类型要同时改后端 `STEP_TYPES` 与前端 `STEP_LIB`）。
 
-- 新增 API：在对应功能域的 `web/xxx_api.py` 里加 `@bp.route(...)` + 权限装饰器（如 `admin_required`）
+### 5.5 新增 MCP 工具
-- 新建蓝图：需在 `web/__init__.py` 里 import 并加进 `register_blueprints` 的注册元组
-- `web_server.py` 只做 app 装配（初始化、`register_blueprints(app)`、常驻线程启动），一般不改
-- 最后更新 **[doc/API.md](API.md)**
 
-### 5.5 新增数据库字段/表
+在 `mcp_server/mcp_server.py` 加 `@mcp.tool()` 函数；写操作必须挂门控（`_check_write` → `_check_serial` → `_ensure_device_free`）；更新 [MCP.md](MCP.md)。
 
-- 模型改 `core/models.py`，首次建表用 `create_all()`；SQLAlchemy 模型未写 `__tablename__` 时默认表名 = 小写类名
+### 5.6 新增常驻线程
-- **已有数据的老库**：在 `core/models.py` 的 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）
-- `app_meta`（KV 配置表）由 `core/models.py` 的 `_migrate_schema()` 建表并维护 `schema_version`
-- `agent_conversation` / `agent_experience` / `experience_audit` / `agent_action`（动作经验库）由 `web/agent_api.py` 内的原生 `CREATE TABLE IF NOT EXISTS` 幂等创建（模块内首次用时执行），**不经 `SCHEMA_MIGRATIONS`，无版本管理**
 
-### 5.6 改动必须同步文档
+参考 `core/device_discovery.py` 的 `init_app(app)` / `shutdown()` 模式；更新 [ARCHITECTURE.md](ARCHITECTURE.md) §3。
 
-任何功能/配置/接口/页面改动，须与代码同一 commit 同步更新对应文档：
+---
 
-| 改动类型 | 对应文档 |
+## 6. 文档同步（红线）
-|------|------|
+
+**任何功能 / 配置 / 接口 / 表结构的增删改，都要在同一个 commit 里更新对应文档。**
+
+| 改动类型 | 必须更新 |
+|---------|---------|
 | HTTP 接口 | [API.md](API.md) |
-| 数据表 / schema | [ARCHITECTURE.md](ARCHITECTURE.md) §3.6 |
+| 表结构 / 迁移 | [DATA_MODEL.md](DATA_MODEL.md)（+ 备份覆盖清单） |
-| `config.py` / `.env` 键增删 | 本文档 §2 + [.env.example](../.env.example) |
+| `config.py` / `.env` 键 | 本文 §4 + [DEPLOY.md](DEPLOY.md) + `.env.example` |
-| 页面 Tab / 子分栏 / 前端拆分 | [ARCHITECTURE.md](ARCHITECTURE.md) §5 |
+| 页面 Tab / 子分栏 / 前端模块 | [ARCHITECTURE.md](ARCHITECTURE.md) §6 + 本文 §5.3 |
-| 任务 / 步骤 | [TASK_DEV.md](TASK_DEV.md) |
+| 任务类型 / 步骤 schema | [TASK_DEV.md](TASK_DEV.md) |
-| 常驻线程 / 进程与装配 | [ARCHITECTURE.md](ARCHITECTURE.md) §7 |
+| 常驻线程 / 装配顺序 | [ARCHITECTURE.md](ARCHITECTURE.md) §2-3 |
-| MCP 工具 | [MCP.md](MCP.md) 与 [MCP_DESIGN.md](MCP_DESIGN.md) |
+| MCP 工具 | [MCP.md](MCP.md) + [MCP_DESIGN.md](MCP_DESIGN.md) |
-| 对外接入 / 数字员工知识库 | [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) 与 [staffdeck/JOB_SPEC.md](staffdeck/JOB_SPEC.md) |
+| 对外接入约定 | [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
+| 暂缓项 / 已知问题 | [backlog/TODO.md](backlog/TODO.md) |
 
-注：STF_REMOVAL.md 是历史迁移记录，不改写。
+新增文档时：登记进 [doc/README.md](README.md) §1 与根 [README](../README.md) 的文档索引。
+历史文档（[STF_REMOVAL.md](STF_REMOVAL.md)）只增不改。
 
 ---
 
-## 6. 发布流程
+## 7. 常见坑速查
 
-详见 **[doc/DEPLOY.md](DEPLOY.md)**。摘要：
+| 坑 | 说明 |
+|----|------|
+| 跨线程访问 DB | 必须自推 app context（`with app.app_context()`） |
+| 改了不生效 | `core/`、`tasks/`、`templates/` 改动要重启；JS 要强刷 |
+| Windows adb 输出 | 不能用 `text=True`（非 GBK 字节会崩），要收 bytes 再解码 |
+| u2 卡死 | `u2.connect` / `d.info` 可能永久 hang，必须加超时 |
+| 抢占死锁 | 不能在 `TaskManager._lock` 内调 `stop_device` |
+| 删除不生效 | 删任务/分组必须显式删行，否则重启会"复活" |
+| 前端写了 `data-perm` 仍可见 | 它只在 `loadMe()` 时求值一次；改权限后需刷新 |
+| 新步骤没生效 | 后端 `STEP_TYPES` 与前端 `STEP_LIB` 要同时改 |
+| 备份导入后没变化 | 必须重启服务 |
+| `.env` 不生效 | `setdefault` 语义：**已存在的环境变量优先**，检查是否被系统环境覆盖 |
 
-1. dev 开发测试完成
+更完整的"代码里写明的坑"见 [ARCHITECTURE.md](ARCHITECTURE.md) §9.2。
-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) | 部署指南（环境、生产、故障排查） |
-| [STF_REMOVAL.md](STF_REMOVAL.md) | 摘除 STF 的历史迁移记录（2026-08，不随现状改写） |
-| [MCP.md](MCP.md) | MCP 手机控制使用手册（工具清单/用法） |
-| [MCP_DESIGN.md](MCP_DESIGN.md) | MCP 架构与演进设计 |
-| [AI_TASK_GEN.md](AI_TASK_GEN.md) | AI 建任务设计文档 |
-| [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) | 给 StaffDeck 数字员工的知识库（MCP 接入/工具/约定/红线） |
-| [staffdeck/JOB_SPEC.md](staffdeck/JOB_SPEC.md) | 数字员工岗位说明（岗位描述/看板摘要/执行约束） |
-| [backlog/TODO.md](backlog/TODO.md) | 待完成项（已确认但暂缓的功能/优化，完成时移出并同步文档） |

doc/DEVICE_AGENT.md

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

doc/MCP.md

@@ -1,147 +1,172 @@
-# MCP 手机控制 Server（`mcp_server/`）
+# MCP 手机控制手册（MCP.md）
 
-多模态 AI（DeepSeek/Claude 等）通过 [MCP（Model Context Protocol）](https://modelcontextprotocol.io) 实时操作 Android 手机的统一出口。AI 控制台（`mcp_agent/`）与外部 MCP 客户端都经它控制设备池中的手机。
+多模态 AI（DeepSeek / Claude 等）通过 [MCP（Model Context Protocol）](https://modelcontextprotocol.io) 操作 Android 手机的统一出口。平台自带的「AI 控制台」（`mcp_agent/`）与外部 MCP 客户端使用的都是这一批工具。
 
-> 本文档 = 使用手册（工具清单/用法）。架构与演进设计见 [MCP_DESIGN.md](MCP_DESIGN.md)。
+> 本文 = **使用手册**（工具清单 / 用法 / 接入）。设计取舍与演进见 [MCP_DESIGN.md](MCP_DESIGN.md)；AI 控制台的会话/经验/动作机制见 [AI_CONSOLE.md](AI_CONSOLE.md)。
 
-## 架构
+---
+
+## 1. 架构与边界
 
 ```
 AI 控制台 / 外部 MCP 客户端
-        │  Streamable HTTP
+        │  Streamable HTTP（http://<host>:8033/mcp）
         ▼
-MCP Server  (:8033, mcp_server/mcp_server.py)     ← 19 个 de_* 工具
+MCP Server（mcp_server/mcp_server.py）        ← 19 个 de_* 工具
-        │  平台 HTTP API（登录 + CSRF）
+        │  平台 HTTP API（登录 + CSRF）  或  轻量 adb/u2 直连
         ▼
-auto_control 平台 (:18050)                        ← 设备池/任务/看屏
+auto_control 平台（:18050）                    ← 设备池 / 任务 / 看屏
         │  adb / uiautomator2 / uiautodev / OCR
         ▼
 Android 设备（IP:5555）
 ```
 
-- 轻量通道直连（adb monkey 开 App、u2 输入、本地 OCR）不绕平台，省时省 token
+- **轻量通道直连**（adb monkey 开 App、u2 输入、本地 OCR）不绕平台，省时间省 token
-- 坐标换算、UI 吸附、剪贴板注入等细节全部在 Server 层消化，模型只需给意图
+- **坐标换算、UI 吸附、剪贴板注入**等细节全部在 Server 层消化，模型只给"意图"
+- **只暴露设备层能力**：平台级的任务增改/分组/设备池/APK/备份等 REST 只给 Web 前端用，未做成 MCP 工具（补齐规划见 [AI_TASK_GEN.md](AI_TASK_GEN.md) §9）
 
-## 运行与配置
+---
 
-服务跑在 220 的 `python-app` 容器内（`scripts/start.sh` 自动拉起，端口 8033）。
+## 2. 运行与配置
-生产访问方式：`http://192.168.20.220:8033/mcp`；本机调试 `python3 -m mcp_server.mcp_server`。
+
+生产跑在 220 的 `python-app` 容器内（`scripts/start.sh` 自动拉起），端点 `http://192.168.20.220:8033/mcp`。
+
+```bash
+# 本机手动启动
+MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> \
+  MCP_AUDIT_FILE=data/mcp_audit.log python -m mcp_server.mcp_server
+```
 
 | 环境变量 | 默认 | 说明 |
 |---|---|---|
-| `MCP_PLATFORM_URL` | `http://127.0.0.1:18050` | 平台地址（Agent 与平台同机时用本机） |
+| `MCP_PLATFORM_URL` | `http://127.0.0.1:18050` | 平台地址 |
-| `MCP_PLATFORM_USER` / `MCP_PLATFORM_PASS` | `admin` / start.sh 兜底 `admin123`（手动直跑时默认空） | 平台登录账号 |
+| `MCP_PLATFORM_USER` / `MCP_PLATFORM_PASS` | `admin` / 空（`start.sh` 兜底 `admin123`） | 平台登录凭据。**改过 admin 密码必须同步**，否则登录失败 |
-| `MCP_ALLOW_WRITE` | `0` | **写门控**：=1 才允许点击/输入/开关 App 等写操作（只读工具不受限） |
+| `MCP_ALLOW_WRITE` | `0`（`start.sh` 内强制 `1`） | **写门控**：=1 才允许点击/输入/开关 App（只读工具不受限） |
-| `MCP_ALLOWED_SERIALS` | 空 | 设备白名单（逗号分隔）：**非空=只允许列出的 serial**；为空时代码只校验 serial 非空、**不校验是否在平台设备池内**（设计稿语义未实现） |
+| `MCP_ALLOWED_SERIALS` | 空 | 设备白名单（逗号分隔）。非空 = 只允许列出的 serial；**为空时只校验 serial 非空，不按平台设备池过滤**（语义缺口见 [backlog](backlog/TODO.md)） |
-| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `0.0.0.0` / `8033` | 监听地址 |
+| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `0.0.0.0` / `8033` | 监听 |
-| `MCP_SCREENSHOT_WIDTH` | `540` | 截图返回宽度上限（px），模型看到的图即该坐标系 |
+| `MCP_SCREENSHOT_WIDTH` | `540` | 截图返回宽度上限（模型看到的坐标系） |
 | `MCP_JPEG_QUALITY` | `70` | 截图 JPEG 质量 |
-| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log` | 审计日志（每次工具调用一行） |
+| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log`（容器兜底 `/tmp/mcp_audit.log`） | 审计日志路径 |
 | `MCP_PLATFORM_TIMEOUT` | `30` | 平台请求超时（秒） |
+| `MCP_ENABLED` | `1` | **只被 `scripts/start.sh` 消费**：=0 则不后台拉起 MCP |
 
-生产（220 容器）已设 `MCP_ALLOW_WRITE=1`；`MCP_ALLOWED_SERIALS` 未设（= 代码只校验 serial 非空，**不限制到平台设备池内**；如需收紧请配置白名单）。
+> `mcp_server/config.py` **只读进程环境变量，不读 `.env`**；`scripts/supervise.sh` 不拉起 MCP（容器场景由 `start.sh` 负责）。
 
-> **MCP_ENABLED**：由 `scripts/start.sh` 消费（默认 `1`，=0 可关掉后台拉起的 MCP）。
+---
-> **MCP_PLATFORM_PASS**：start.sh 兜底 `admin123`——改过平台 admin 密码必须同步该变量，否则 MCP 登录平台失败。
-> **supervise.sh 不拉起 MCP**：只守护 web_server；容器场景 MCP 由 start.sh 后台拉起（见 DEPLOY §2.4）。
 
-## 坐标空间（重要约定）
+## 3. 坐标空间（重要）
 
-- `de_screenshot` 返回 ≤540px 宽的 JPEG（display 空间），并附 `native_size`（设备原生分辨率）
+- `de_screenshot` 返回 **≤540px 宽**的 JPEG（display 空间），同时给出 `native_size`（设备原生分辨率）与 `screen_state`
-- `de_tap` / `de_swipe` 的坐标一律使用 **de_screenshot 返回图像的坐标系**，Server 按比例换算为原生坐标
+- `de_tap` / `de_swipe` 的坐标一律用 **`de_screenshot` 返回图像的坐标系**，Server 按比例换算成原生坐标
-- **先截图、后点击**：Server 需要最近一次截图才能建立坐标空间（未截图就点击会报「请先执行 de_screenshot」）
+- **必须先截图再点击**：Server 需要最近一次截图来建立坐标空间，否则报 `invalid_param`「请先对该设备执行 de_screenshot」
-- `de_tap` 带**自动吸附**：点击点若落在某个可点击元素内，实际会点该元素中心——坐标只需大致对准，偏十几像素也能点准；点空白处则按原坐标
+- `de_tap` 带**自动吸附**：落点若在某个可点击元素内，实际点该元素中心 → 坐标**只需大致对准**；返回 `snapped` / `label` 便于核对
-- 返回的 `snapped/label` 可核对吸附结果（snapped=true 表示已吸到元素，label 为该元素文案）
 
-## 工具清单（19 个）
+---
 
-### 设备与状态
+## 4. 工具清单（19 个）
 
-| 工具 | 用途 |
+统一返回约定：
-|---|---|
-| `de_list_devices` | 列出可控制设备：serial / 型号 / 在线 / 任务状态 / 前台 App。**开局第一步** |
-| `de_foreground_app(serial)` | 当前前台 App 包名（dumpsys，MIUI 焦点为空时自动兜底） |
 
-### 观察屏幕（感知）
+```json
+{"ok": true,  "data": { … }}
+{"ok": false, "error": {"code": "device_busy", "message": "设备正在执行任务…"}}
+```
 
-| 工具 | 用途 |
+错误码：`invalid_param` · `device_not_allowed` · `write_disabled` · `device_busy` · `platform_unavailable` · `device_offline` · `text_not_found`。
-|---|---|
-| `de_screenshot(serial)` | 截图并返回图像（≤540px JPEG）+ 尺寸 + 亮/熄屏状态。多模态模型直接看图 |
-| `de_ui_tree(serial, limit=150)` | 当前界面元素树（text/id/desc/class/bounds）。**可点击元素排前**；limit 1-300 控制条数防 token 膨胀。用于确认界面上有什么 |
-| `de_ocr(serial)` | OCR 识别当前屏幕文字（UI 树没有的图片/WebView 文字也能识别），返回 [{text, score}] |
 
-### 点击与滑动（操作）
+### 4.1 设备与状态（只读）
 
-| 工具 | 用途 |
+| 工具 | 参数 | 返回 / 说明 |
-|---|---|
+|------|------|------------|
-| `de_tap_text(serial, text)` | **按屏幕文字点击**（推荐）：给一个屏幕上可见的文字（子串匹配）即找到并点其中心。原生控件走 UI 树，WebView/图片文字自动 OCR 兜底。找不到返回明确错误 |
+| `de_list_devices` | — | `[{serial, name, model, online, task_job, worker_status, foreground_app}]`。**开局第一步**；`name` 是设备在平台里的名称（身份），**向用户汇报时用名称**（同型号多台靠它区分），调工具仍用 `serial` |
-| `de_tap_element(serial, by, value, index=1)` | 按元素点击：`by` = text / id / desc（精确）或 text_contains / desc_contains（模糊）。多命中用 index 取第几个 |
+| `de_foreground_app` | `serial` | `{foreground_app}` 当前前台包名（dumpsys，MIUI 焦点为空时兜底） |
-| `de_tap(serial, x, y)` | 坐标点击（截图坐标系，自动吸附，见上）。**纯图形目标（视频画面/无文字图标）才用它** |
+| `de_list_tasks` | — | 平台任务计划 `[{id,name,task_type,enabled,schedule}]`（只读） |
-| `de_swipe(serial, x1,y1,x2,y2, duration=0.2)` | 滑动（截图坐标系；长按=同点起止 + duration≥1） |
-| `de_press_key(serial, key)` | 按键：back / home / recent / menu / power / volume_up / volume_down / enter / delete / search / camera |
 
-### 输入与剪贴板
+### 4.2 观察屏幕（只读）
 
-| 工具 | 用途 |
+| 工具 | 参数 | 返回 / 说明 |
-|---|---|
+|------|------|------------|
-| `de_type_text(serial, text)` | 向当前界面输入框输入文字（支持中文，直设 EditText 不依赖剪贴板/粘贴） |
+| `de_screenshot` | `serial` | `{image:{type:"image",data:<base64>,mimeType:"image/jpeg"}, width, height, native_size, screen_state}`。多模态模型直接看图 |
-| `de_set_clipboard(serial, text)` | 写入设备剪贴板（ClipInject 通道注入 + 读回验证） |
+| `de_ui_tree` | `serial`, `limit`(150，1-300) | `{count, elements:[{text,id,desc,class,clickable,bounds}]}`，**可点击元素排前**；`limit` 控 token |
-| `de_read_clipboard(serial)` | 读取设备当前剪贴板内容 |
+| `de_ocr` | `serial` | `{count, texts:[{text,score}]}`（≤100 条）。UI 树拿不到的图片/WebView 文字用它 |
+| `de_read_clipboard` | `serial` | `{clipboard}` |
+| `de_list_apps` | `serial`, `keyword`("") | `{count, packages}` 第三方已装包名（`pm list packages -3`，≤200） |
 
-### App 管理（轻量 adb 直连，不建 u2 会话）
+### 4.3 点击与滑动（**写操作**）
 
-| 工具 | 用途 |
+| 工具 | 参数 | 说明 |
-|---|---|
+|------|------|------|
-| `de_open_app(serial, package)` | 打开 App（adb monkey 直启，无需知道 activity——最快的打开路径） |
+| `de_tap_text` | `serial`, `text`(≤100 字符) | **推荐**：按屏幕可见文字点击。原生控件走 UI 树，WebView/图片文字自动 **OCR 兜底**；找不到 → `text_not_found` |
-| `de_stop_app(serial, package)` | 强制停止 App（am force-stop） |
+| `de_tap_element` | `serial`, `by`(`text`/`id`/`desc`/`text_contains`/`desc_contains`), `value`, `index`(1) | 按元素属性点击，无需坐标；多命中用 `index` |
-| `de_list_apps(serial, keyword="")` | 列出第三方已装应用（pm list packages -3），keyword 可过滤（如 "douyin"） |
+| `de_tap` | `serial`, `x`, `y` | 坐标点击（截图坐标系 + 自动吸附）。**纯图形目标才用** |
+| `de_swipe` | `serial`, `x1,y1,x2,y2`, `duration`(0.2) | 滑动（长按 = 同点起止 + `duration≥1`） |
+| `de_press_key` | `serial`, `key` | `back` / `home` / `recent` / `menu` / `power` / `volume_up` / `volume_down` / `enter` / `delete` / `search` / `camera` |
 
-> 上表三个工具走 `direct_ops` 轻量 **adb 直连**（monkey / am force-stop / pm list packages），不建 u2 会话。
+### 4.4 输入与剪贴板（**写操作**）
 
-### 亮屏与熄屏（平台 screen_all 通道）
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `de_type_text` | `serial`, `text` | 向当前输入框输入（支持中文，直设 EditText，不依赖剪贴板） |
+| `de_set_clipboard` | `serial`, `text` | 写入设备剪贴板（ClipInject 通道 + 读回验证） |
 
-| 工具 | 用途 |
+### 4.5 App 管理（**写操作**，走 adb 直连不建 u2 会话）
-|---|---|
-| `de_sleep(serial)` | 熄屏（**运行中任务会中断，慎用**） |
-| `de_wake(serial)` | 亮屏并解锁（熄屏时先调它再截图） |
 
-> `de_sleep`/`de_wake` 走平台 `POST /api/device/screen_all`（`platform_client`），同样不在 MCP 进程内建 u2 会话。
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `de_open_app` | `serial`, `package` | `adb monkey` 直启（最快路径，无需知道 activity） |
+| `de_stop_app` | `serial`, `package` | `am force-stop` |
 
-### 平台联动
+### 4.6 亮屏 / 熄屏（**写操作**）
 
-| 工具 | 用途 |
+| 工具 | 参数 | 说明 |
-|---|---|
+|------|------|------|
-| `de_list_tasks()` | 列出平台任务计划（名称/类型/启用/调度），了解已自动化的工作 |
+| `de_wake` | `serial` | 亮屏并解锁（熄屏时先调它再截图） |
+| `de_sleep` | `serial` | 熄屏（**会中断正在运行的任务，慎用**） |
 
-### 现状边界
+> 后两组分别经 `direct_ops`（adb）与平台 `POST /api/device/screen_all` 实现，不在 MCP 进程内建 u2 会话。
 
-本 Server 目前只有**设备层**的 `de_*`（控制/感知/只读）+ 平台**只读**的 `de_list_tasks`；平台级**任务增改/提交/CRUD、分组/设备池/自定义动作/APK/备份**等 REST 路由只给 Web 前端用，**未暴露 MCP 工具**。
+### 4.7 写操作门控（三连）
 
-补齐分层规划见 [AI_TASK_GEN.md](AI_TASK_GEN.md) §9。**每新增/修改/删除一个 MCP 工具或平台配置，必须同步更新本手册与 [MCP_DESIGN.md](MCP_DESIGN.md)（doc 同步红线）**。
+所有写工具在执行前依次检查：
 
-## 推荐使用模式（操作手机的正确姿势）
+1. `_check_write()` —— `MCP_ALLOW_WRITE=1`？否则 `write_disabled`
+2. `_check_serial()` —— serial 非空 / 在白名单内？否则 `device_not_allowed`
+3. `_ensure_device_free()` —— 设备 `worker_status` 不是 `running`/`connecting`？否则 `device_busy`（**AI 不与任务抢设备**）
+
+> 设备状态查询有 **5 秒缓存**；查询本身异常时**放行**（不阻塞），由平台侧兜底。
+
+---
+
+## 5. 推荐使用模式
 
 1. **`de_list_devices`** 确认目标设备在线
-2. **`de_screenshot`** 看图理解当前界面（图像会在下一次模型回合送达）
+2. **`de_screenshot`** 看图理解当前界面（图像会在下一回合送达模型）
-3. **点击定位优先级**（从高到低）：
+3. **点击定位优先级**：
-   - 目标有可见文字 → **`de_tap_text`**（一次调用完成「找到并点击」，最可靠）
+   - 目标有可见文字 → **`de_tap_text`**（一次调用完成"找到并点击"，最可靠）
-   - 文字有歧义/多候选 → `de_ui_tree` 确认后 `de_tap_element`（text_contains 模糊匹配）
+   - 文字有歧义/多候选 → `de_ui_tree` 确认后用 `de_tap_element`（可用 `text_contains` 模糊匹配）
-   - 纯图形目标 → `de_tap` 坐标（**无需精算**，Server 自动吸附到可点元素中心）
+   - 纯图形目标 → `de_tap` 坐标（**无需精算**，会自动吸附）
-4. 输入文字：先点中输入框（de_tap_text / de_tap），再 `de_type_text`
+4. **输入文字**：先点中输入框，再 `de_type_text`
-5. 每次关键操作后 `de_screenshot` 验证：界面变化 = 成功；无变化 = 未命中，换 de_tap_text / de_tap_element 重新定位，**不要重复点同一坐标**
+5. **每步验证**：关键操作后再 `de_screenshot`——界面变了 = 成功；没变 = 未命中 → 换 `de_tap_text`/`de_tap_element` 重新定位，**不要重复点同一坐标**
-6. 完成/失败时用中文总结：做了什么、当前状态、注意事项
+6. **收尾**：用中文总结做了什么、当前状态、注意事项
-7. 效率约束：界面未变不重复截图/点同位置；连续 6 步无进展停止并总结
+7. **效率**：界面未变时不重复截图/点击；连续 6 步无进展就停止并总结
 
-## 安全与审计
+---
 
-- **写门控**：`MCP_ALLOW_WRITE=0`（默认）时点击/输入/开关 App 全部拒绝，只读工具可用
+## 6. 安全与审计
-- **任务占用互斥**：写工具操作前调 `_ensure_device_free` 检查设备 `worker_status`，running/connecting 直接拒 `device_busy`（只读工具不受限），AI 不与任务抢设备
-- **平台会话 + CSRF**：平台登录与会话由 `platform_client` 内部处理（`MCP_PLATFORM_USER/PASS` 登录拿 cookie、失效自动重登；POST 自动带 `X-CSRF-Token`），不向客户端暴露平台凭据
-- **设备白名单**：`MCP_ALLOWED_SERIALS` 非空时限制可操作的 serial；空名单时代码只校验 serial 非空，不按平台设备池过滤
-- **审计日志**：每次调用记录 `{ts, tool, serial, args, result}` 到 `MCP_AUDIT_FILE`（220 上 `/tmp/mcp_audit.log`）
-- 操作对象限定平台设备池；`adb kill-server` / `adb disconnect` 属项目红线，任何工具不触碰
 
-## 客户端接入示例
+| 机制 | 说明 |
+|------|------|
+| **写门控** | `MCP_ALLOW_WRITE=0`（默认）时所有写操作被拒，只读可用 |
+| **任务互斥** | 写操作前检查设备是否在跑任务，忙则 `device_busy` |
+| **平台会话** | `platform_client` 内部登录（`MCP_PLATFORM_USER/PASS`）、会话失效自动重登、POST 自动带 `X-CSRF-Token`；**平台凭据不暴露给客户端** |
+| **白名单** | `MCP_ALLOWED_SERIALS` 非空时限制可操作 serial |
+| **审计** | 每次调用（**含只读**）写一行 JSON 到 `MCP_AUDIT_FILE`：`{ts, tool, serial, args 摘要, result 摘要}` |
+| **红线** | 任何工具都不执行 `adb kill-server` / `adb disconnect` |
+| **端点鉴权** | ⚠️ MCP HTTP 端点自身**没有** token/账号校验，只做出站登录 → **必须靠网络隔离**（同机/内网），不要直接暴露公网 |
+
+---
+
+## 7. 客户端接入示例
 
 ```python
 import asyncio
@@ -150,24 +175,29 @@ from fastmcp import Client
 async def main():
     async with Client("http://192.168.20.220:8033/mcp", timeout=30) as c:
         devs = await c.call_tool("de_list_devices", {})
-        serial = devs.data["data"][0]["serial"]          # 取第一台在线设备
+        serial = devs.data["data"][0]["serial"]          # 第一台设备
         shot = await c.call_tool("de_screenshot", {"serial": serial})
-        img = shot.data["data"]["image"]                 # base64 JPEG（多模态模型可直接看图）
+        img = shot.data["data"]["image"]                 # base64 JPEG（给多模态模型看）
         await c.call_tool("de_tap_text", {"serial": serial, "text": "搜索"})
 
 asyncio.run(main())
 ```
 
-## AI 控制台（内置 Agent）
+> 给外部数字员工的使用约定与红线，另见 [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md)。
 
-Web 端「AI 控制台」Tab 内建的 Agent（`mcp_agent/`，OpenAI 兼容协议：DeepSeek 等）也通过本 Server 的同一批工具跑任务：
+---
 
-- 流式输出 + 每步 MCP 工具调用实时展示（含截图缩略）
+## 8. AI 控制台（内置 Agent）
-- 多轮会话记忆（同会话上下文保留，新建会话清空）
-- **自进化经验记忆**：一轮成功操作会被提炼成「配方」存入 `agent_experience` 表，下次相似任务自动注入参考（命中/写入均有 🧠 提示卡）
-- 模型与 API Key 在 AI 控制台右上角 ⚙ 配置，存平台 `app_meta`
 
-> **依赖提示**：AI 控制台依赖本 MCP Server（默认 `http://127.0.0.1:8033/mcp`）。若未启动，发起指令会直接失败——平台已把 SDK 的含糊报错（`Server returned an error response` 等）映射为明确文案：**「MCP server(8033) 不可达 …」**。
+Web 的「AI 控制台」Tab 内建 Agent（`mcp_agent/`，OpenAI 兼容模型）用的就是本 Server 的同一批工具：
-> 本机（非容器）需手动拉起：
+
-> `MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> MCP_AUDIT_FILE=data/mcp_audit.log python -m mcp_server.mcp_server`
+- 流式输出 + 每步 MCP 调用实时展示（含截图缩略）
-> 220 生产容器由 `scripts/start.sh` 自动拉起（`MCP_ENABLED=0` 会关）。
+- 多轮会话（同会话保留上下文）
+- **自进化记忆**：经验库（任务配方）+ 动作库（命名动作），相似任务自动注入参考
+- 模型与 Key 在控制台右上角 ⚙ 配置（存平台 `app_meta`）
+
+> **依赖提示**：AI 控制台依赖本 MCP Server（默认 `http://127.0.0.1:8033/mcp`）。未启动时平台会把 SDK 的含糊报错映射成明确文案「**MCP server(8033) 不可达 …**」。
+
+---
+
+> **维护约定**：新增 / 修改 / 删除任何一个 MCP 工具或相关配置，必须**同步更新本文与 [MCP_DESIGN.md](MCP_DESIGN.md)**（doc 同步红线）。

doc/MCP_DESIGN.md

@@ -1,6 +1,8 @@
 # MCP 手机控制（Mobile Control MCP Server）设计文档
 
-> 分支：dev | 状态：设计稿/演进（实现现状以 doc/MCP.md 为准） | 日期：2026-09-04
+> 状态：**设计稿 / 演进记录**——凡与实现不符处，以 [MCP.md](MCP.md)（使用手册，含 19 个工具的权威清单）与 `mcp_server/` 代码为准。
+> 本文保留设计取舍与里程碑，便于回溯"为什么这么做"；文中的"演进备选"均**未落地**。
+> 最后核对：2026-09-10（对照 dev 现状）。
 
 ## 1. 背景与目标
 
@@ -25,7 +27,7 @@
 ```
 ┌──────────────┐   MCP (Streamable HTTP / stdio)   ┌──────────────────┐
 │  多模态 AI    │ ────────────────────────────────▶ │   MCP Server     │
-│ Claude Desktop│   tools + image content block    │  （220 独立进程） │
+│ Claude Desktop│   tools + image content block    │  （与平台同容器） │
 │ Claude Code  │ ◀──────────────────────────────── │  mcp_server/ 包  │
 └──────────────┘   截图图像 / JSON 结果             └────────┬─────────┘
                                                             │ 内部调用

doc/README.md

@@ -0,0 +1,66 @@
+# auto_control 文档总索引
+
+本目录是 `auto_control`（Android 多设备自动化任务平台）的**唯一权威文档源**。代码即事实，文档与代码不一致时以代码为准，并**顺手把文档改对**（见文末维护约定）。
+
+> 项目名称统一为 **auto_control**（历史文档里出现过的 `platform-tools` 均为旧名，已全部改名）。
+
+---
+
+## 1. 文档地图
+
+| 文档 | 内容 | 主要读者 |
+|------|------|---------|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | **架构详解**：分层、启动装配顺序、线程与并发模型、设备生命周期、任务调度链路、状态机、关键设计决策与扩展点 | 所有开发者（先读这篇） |
+| [DATA_MODEL.md](DATA_MODEL.md) | **数据模型**：SQLite 表与字段、schema 迁移、非模型表、`app_meta` 配置键、数据目录、备份覆盖清单 | 后端开发、运维 |
+| [API.md](API.md) | **HTTP 接口全量**：按蓝图分组的路由表、鉴权、请求/响应示例、非 JSON 响应、错误分支 | 前端开发、外部接入 |
+| [TASK_DEV.md](TASK_DEV.md) | **任务与步骤开发**：TaskType/TaskJob 概念、18 种步骤全表、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
+| [MCP.md](MCP.md) | **MCP 手机控制手册**：19 个 `de_*` 工具用法、写操作门控、坐标换算、接入示例 | 接入方、数字员工 |
+| [MCP_DESIGN.md](MCP_DESIGN.md) | **MCP 设计文档**：边界划分、错误码、白名单/审计设计、演进方向 | 平台开发者 |
+| [AI_CONSOLE.md](AI_CONSOLE.md) | **AI 控制台**：会话/SSE、经验库、动作库、巡检、Markdown 渲染、推理链、token 统计 | 使用者、平台开发者 |
+| [AI_TASK_GEN.md](AI_TASK_GEN.md) | **AI 建任务**：设计稿与里程碑（P0 未实现，属规划） | 平台开发者 |
+| [DEVICE_AGENT.md](DEVICE_AGENT.md) | **设备端 Agent 接口契约**：应用商店的设备专用接口（清单/下载/上报）、adb 指令协议、版本约定 —— 与设备端 APK 仓库共享的契约 | 设备端开发者、平台开发者 |
+| [DEPLOY.md](DEPLOY.md) | **部署与运维**：环境准备、生产容器、数据备份导出/导入、故障排查 | 运维、部署者 |
+| [DEVELOPMENT.md](DEVELOPMENT.md) | **开发手册**：git 流程、技术红线、本地开发与调试、常见开发任务、文档同步约定 | 所有开发者 |
+| [STF_REMOVAL.md](STF_REMOVAL.md) | **历史记录**：摘除 OpenSTF 的迁移过程（阶段 0-3） | 追溯背景时参考 |
+| [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) | 给 StaffDeck 数字员工的知识库（MCP 接入/工具/约定/红线） | 外部 AI 接入方 |
+| [staffdeck/JOB_SPEC.md](staffdeck/JOB_SPEC.md) | 数字员工岗位说明（岗位描述/看板摘要/执行约束） | 外部 AI 接入方 |
+| [backlog/TODO.md](backlog/TODO.md) | 已确认但暂缓的待办（含已知问题） | 所有开发者 |
+
+项目根目录的 [README.md](../README.md) 是**项目总览与快速上手**（面向第一次接触项目的人），细节都在本目录。
+
+---
+
+## 2. 推荐的阅读路径
+
+| 你的目的 | 按顺序读 |
+|---------|---------|
+| **第一次接触项目** | 根 [README.md](../README.md) → [ARCHITECTURE.md](ARCHITECTURE.md) → [DATA_MODEL.md](DATA_MODEL.md) |
+| **搭环境跑起来** | 根 [README.md](../README.md) 的「快速上手」→ [DEPLOY.md](DEPLOY.md) |
+| **写/改任务** | [TASK_DEV.md](TASK_DEV.md) → [ARCHITECTURE.md](ARCHITECTURE.md) §任务调度 |
+| **改后端/前端** | [DEVELOPMENT.md](DEVELOPMENT.md)（流程+红线+本地开发）→ [ARCHITECTURE.md](ARCHITECTURE.md) → [API.md](API.md) |
+| **对外提供手机控制** | [MCP.md](MCP.md) → [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
+| **排故障** | [DEPLOY.md](DEPLOY.md) §故障排查 → [DEVELOPMENT.md](DEVELOPMENT.md) §调试 |
+
+---
+
+## 3. 文档维护约定（红线）
+
+> 与「doc 同步红线」一致：**任何功能/配置/接口/表结构的增删改，必须在同一个 commit 里同步更新对应文档。**
+
+| 改动类型 | 必须同步的文档 |
+|---------|--------------|
+| HTTP 接口（新增/改参数/改返回/改鉴权） | [API.md](API.md) |
+| 数据库表/字段/迁移 | [DATA_MODEL.md](DATA_MODEL.md) + [ARCHITECTURE.md](ARCHITECTURE.md) |
+| **新增持久化表** | 还要登记进 `core/system_backup.py` 的 `SUMMARY_TABLES` + [DEPLOY.md](DEPLOY.md) §3.5（**备份覆盖红线**） |
+| `config.py` / `.env` 键 | [DEVELOPMENT.md](DEVELOPMENT.md) 配置速查 + [DEPLOY.md](DEPLOY.md) + `.env.example` |
+| 页面 Tab / 子分栏 / 前端 JS 拆分 | [ARCHITECTURE.md](ARCHITECTURE.md) §前端 + [DEVELOPMENT.md](DEVELOPMENT.md) |
+| 任务类型 / 步骤 schema | [TASK_DEV.md](TASK_DEV.md) |
+| 常驻线程 / 进程装配 | [ARCHITECTURE.md](ARCHITECTURE.md) §线程与并发 |
+| MCP 工具 | [MCP.md](MCP.md) + [MCP_DESIGN.md](MCP_DESIGN.md) |
+| 设备端 Agent（APK） | [DEVICE_AGENT.md](DEVICE_AGENT.md) |
+| 对外接入约定 | [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
+| 暂缓项 / 已知问题 | [backlog/TODO.md](backlog/TODO.md)（完成时移出并同步相关文档） |
+
+**新增文档时**：在本文 §1 表格里登记一行，并在根 README 的「更多文档」里加链接——否则等于没写。
+
+**历史文档不追改**：[STF_REMOVAL.md](STF_REMOVAL.md) 是迁移阶段的历史记录，只增不改，不随现状改写。

doc/backlog/TODO.md

@@ -1,54 +1,127 @@
-# 待完成项（Backlog）
+# 待完成项 / 已知问题（Backlog）
 
-> 用途：记录**已确认但暂缓**的功能/优化，避免丢线索。完成时应移出本文件，并按「doc 同步红线」更新对应文档。
+> 用途：记录**已确认但暂缓**的功能、优化与**已知缺陷**，避免丢线索。完成时移出本文件，并按「doc 同步红线」更新对应文档。
-> 维护：新增条目写清 **背景 / 期望 / 涉及文件 / 验收**；完成后删除条目并在相关 doc 体现。
+> 维护：新条目写清 **背景 / 期望 / 涉及文件 / 验收**；缺陷写清 **现象 / 复现 / 影响**。
+> 相关：[doc/README.md](../README.md)（文档索引与维护约定）。
 
 ---
 
-## 设备与连接
+## A. 已知缺陷（尚未修）
 
-- [ ] **adb 远程终端加「目标切换」(本机 / 220)**
+### A1. `GET /locate` 返回 500（设备定位大字页打不开）
-  - 背景：终端默认走 `.env` 的 `ANDROID_ADB_SERVER_ADDRESS=192.168.20.220`（adb 客户端生效，非本项目代码读取），因此终端里看不到**本机 USB 设备**（实测本机 adb 有 `bebeoft4ztgiskba`，平台终端只显示 220 侧的 `192.168.20.206:5555`）。
+
-  - 期望：`web/tools_api.py` 的 `/api/adb/devices`、`/api/adb/cmd` 支持 `target=local|remote`；前端 `static/admin/tools.js` 加下拉；默认值按需。
+- **现象**：访问 `/locate?serial=…` 直接 500。
-  - 涉及：`web/tools_api.py`、`static/admin/tools.js`、`doc/API.md`、`doc/DEPLOY.md`、`doc/DEVELOPMENT.md`（配置速查）。
+- **原因**：`web/monitor.py` 的 `locate_page()` 用了 `render_template_string` 与 `_esc`，但该文件只导入了 `render_template`，也没有 `_esc` 定义。
-  - 验收：切换「本机」时终端能列出本机 USB + 本机已连 `IP:5555`；切「220」时列出 220 侧设备；`adb cmd` 同样生效。
+- **复现**：`curl -s -o /dev/null -w "%{http_code}" "http://127.0.0.1:18050/locate?serial=1.2.3.4:5555"` → 500（路由扫描脚本已确认）。
+- **影响**：「工具 → 设备池管理 → 定位」在设备上打开的大字页不可用（亮屏那半仍生效）。
+- **涉及**：`web/monitor.py`（补 import / 补转义实现，或改用 `render_template` + 模板文件）。
+- **验收**：`/locate` 返回 200 且页面正确显示 serial/IP；纳入回归脚本。
+
+### A2. `POST /api/device/locate`（`show=true`）失败
+
+- **现象**：带 `show=true` 调用时抛异常 → 502。
+- **原因**：`web/monitor.py` 用了 `urllib.parse.quote` 但未 `import urllib`。
+- **影响**：无法远程把设备浏览器打开到定位页。
+- **涉及**：`web/monitor.py`。**验收**：`show=true` 时设备浏览器打开定位页且返回 200。
+
+### A3. CSRF 实际未启用
+
+- **现象**：`/api/csrf` 会签发 token、前端所有非 GET 请求都会带 `X-CSRF-Token`，但服务端**从不校验**。
+- **原因**：`web_server.py` 只 `from web.auth import _csrf_protect`，**没有注册** `app.before_request(_csrf_protect)`；而 `web/auth.py` 的 docstring 声称"由 web_server 注册"。
+- **影响**：CSRF 防护形同虚设（同网段内可伪造写请求）。
+- **涉及**：`web_server.py`（注册钩子）+ 需要回归所有写接口（前端、脚本、MCP 的 `platform_client` 都已带 token，风险点是第三方直接调 API）。
+- **验收**：注册后所有写接口在缺 token 时返回 403，且前端/MCP 全链路正常。
+
+### A5. 前端 `--card-line` 变量未定义
+
+- **现象**：AI 控制台的会话/经验/动作模态框边框失效（`border:1px solid var(--card-line)` 解析为无效值）。
+- **原因**：该变量只在 `templates/admin/wall.html` 的 `:root` 定义，`monitor.html` 的 `:root` 里没有，但被引用了 5 处。
+- **涉及**：`templates/admin/monitor.html`（`:root` 补 `--card-line:#232936`）。
+
+### A6. `monitor.js` 引用了未定义变量 `countParts`
+
+- **现象**：进度为 0 的边界分支会抛 `ReferenceError`（被外层 `try/catch` 吞掉，用户无感）。
+- **涉及**：`static/admin/monitor.js`（该分支的进度渲染）。
+
+### A7. 其它小问题（低优先）
+
+- `static/admin/custom.css` 是**死文件**（无任何引用）。
+- `templates/admin/monitor.html` 里 `.agent-shell` 有**完全重复的 CSS 声明**（后者覆盖前者的 `min-height`）。
+- 设备表空态 `colspan="11"` 与实际列数（10）不符。
+- `core/device_worker.py` 的 `_u2_connect_remote` 有两个结构相同的 `except Exception`，**后者是死代码**。
+- `core/ssh_client.py` **全项目无人 import**（`STF_SSH_*` 配置也只被它读取）；要么接上用途，要么删除。
+- 若干按功能域拆包时留下的**重复函数定义**：`_merged_device_list`（`web/common.py` / `apks_api.py` / `tools_api.py` 各一份）、`tools_api.py` 的三个辅助函数、`monitor.py` 的屏相关函数、`tasks_api.py` 的 `_job_next_run`（各定义两次）。
+
+---
+
+## B. 设备与连接
+
+- [ ] **adb 远程终端加「目标切换」（本机 / 220）**
+  - 背景：终端默认走 `.env` 的 `ANDROID_ADB_SERVER_ADDRESS=192.168.20.220`（adb 客户端生效，非本项目代码读取），因此终端里看不到**本机 USB 设备**。
+  - 期望：`/api/adb/devices`、`/api/adb/cmd` 支持 `target=local|remote`；前端 `tools.js` 加下拉。
+  - 涉及：`web/tools_api.py`、`static/admin/tools.js`、`doc/API.md`、`doc/DEVELOPMENT.md`（配置速查）。
+  - 验收：切「本机」能列本机 USB + 已连 `IP:5555`；切「220」列 220 侧设备；`adb cmd` 同样生效。
 
 - [ ] **`.env` 的 adb 路由键要在文档里说明（或去掉）**
-  - 背景：`ANDROID_ADB_SERVER_ADDRESS/HOST/PORT` 会被 `.env` 注入 `os.environ`，**adb 客户端**据此把所有 adb 调用指向 220；`ANDROID_ADB_SERVER_HOST` 是非标准键（adb 不认）。
+  - `ANDROID_ADB_SERVER_ADDRESS/HOST/PORT` 会被 `.env` 注入 `os.environ`，**adb 客户端**据此把所有调用指向 220；`ANDROID_ADB_SERVER_HOST` 是非标准键（adb 不认）。
-  - 期望：在 `doc/DEVELOPMENT.md` 配置速查 / `doc/DEPLOY.md` 写明该行为与取舍；或本地去掉这三行改走本机 adb（`USB_ADB_HOST` 保留，平台对 220 的 USB 访问走显式 `-H/-P`）。
+  - 期望：在配置速查里写明该行为与取舍，或本地去掉这三行改走本机 adb。
+
+- [ ] **`.gitignore` 漏项**：`data/mcp_audit.log` 已补（`data/*.log`，2026-09-13）；**`data/uiauto.pid` 仍未忽略**（`git status` 会显示为未跟踪）；`data/apks/` 目录无占位文件。
 
 - [ ] 220 的 Tailscale / adb server(5037) 可达性巡检（曾出现连不通超时）。
 
-## 编辑器 / 元素抓取
+---
 
-- [ ] **未命中要"明确提示"，别混成"执行了这步"**
+## C. 编辑器 / 元素抓取
-  - 背景（2026-09-10）：click/long_click/wait_el/swipe_until/if_el 未命中时只写 `[WARNING] ... 未找到元素`，前端进度仍按"执行了一步"计数、任务日志 INFO 行也照常打 → 用户看到像"成功"，实际没点（db03f16e 案例就是这么误判的）。
-  - 期望：执行器把**未命中**作为该步结果（✗）返回并计入统计（如"未命中 N 步"）；前端任务进度/日志**标红 ✗** 并给出所用选择器；任务结束汇总未命中步骤数。
-  - 涉及：`tasks/generic/task.py`（各 handler 返回/记录命中结果）、`static/admin/tasks.js`/`monitor.js`（渲染）、`doc/API.md`（如需新增字段）、`doc/TASK_DEV.md`。
 
+- [ ] **未命中要「明确提示」，别混成「执行了这步」**
+  - 背景（2026-09-10）：click/long_click/wait_el/swipe_until/if_el 未命中时只写 `[WARNING] ... 未找到元素`，前端进度仍按"执行了一步"计数 → 用户看到像"成功"，实际没点（db03f16e 案例就是这么误判的）。
+  - 期望：执行器把**未命中**作为该步结果（✗）返回并计入统计；前端标红 ✗ 并给出所用选择器；任务结束汇总未命中步骤数。
+  - 涉及：`tasks/generic/task.py`、`static/admin/{tasks,monitor}.js`、`doc/TASK_DEV.md`。
 
-- [ ] **元素抓取（点击元素）超时——部分设备 dump 慢于平台超时**
+- [ ] **元素抓取超时——部分设备 dump 慢于平台超时**
-  - 背景（2026-09-10 实测）：`core/uiauto_helper.py:24` `_TIMEOUT=(1,8)`；`192.168.20.72:5555` dump 2.4s 正常，而 `192.168.20.206:5555` 与 USB 设备 dump **~18s** → 平台报「uiauto2 请求超时」，编辑器抓不到元素、无法选取/回填/测试点击。设备本身正常（直接请求 uiautodev 45s 内 HTTP 200）。
+  - 背景（2026-09-10 实测）：`core/uiauto_helper.py` 的 `_TIMEOUT=(1,8)`；某设备 dump **~18s** → 平台报「uiauto2 请求超时」，编辑器抓不到元素（设备本身正常）。
-  - 期望：提高读超时（如 `(2, 30)`）+ 前端 `/api/uiauto/elements` 加载中给明确提示；可选加「同一界面短时缓存」或「抓取前提示切到轻界面」。
+  - 期望：读超时提到 `(2, 30)` + 前端加载中有明确提示；可选"同界面短时缓存"。
-  - 涉及：`core/uiauto_helper.py`、`web/tasks_api.py`（/api/uiauto/elements）、`static/admin/editor.js`、`doc/API.md`、`doc/ARCHITECTURE.md`(§3.8)。
+  - 涉及：`core/uiauto_helper.py`、`web/tasks_api.py`、`static/admin/editor.js`、`doc/ARCHITECTURE.md`。
+
+- [ ] **序号型 XPath / 界面就绪 的防呆**（2026-09-10 db03f16e 案例）
+  - 背景：`(//*[@resource-id="…"])[6]` 依赖"抓取那一刻该属性有 ≥6 个实例"；运行时界面不同（App 仍在闪屏页）→ 序号必然失配。
+  - 期望：① `open_app` 提示勾选「等待首页」；② 抓取器对**带序号**的选择器加醒目提示；③ 抓取弹窗提醒"请先把设备停在任务运行到该步时的同一界面再抓"。
+  - 涉及：`core/uiauto_helper.py`、`static/admin/editor.js`、`tasks/generic/task.py`、`doc/TASK_DEV.md`。
 
 - [ ] 自定义动作支持 `action_ref` 引用型节点（现状：拖入画布会**展开成 group**，改动需同步执行器 + 编辑器）。
 
-- [ ] **序号型 XPath / 界面就绪 的防呆**（2026-09-10 db03f16e 案例）
+---
-  - 背景：`(//*[@resource-id="…"])[6]` 这类**带序号**的选择器依赖"抓取那一刻该属性有 ≥6 个实例"；运行时界面不同（实测抖音冷启动 5s 后仍在 `.splash.SplashActivity`，`content_layout` 只有 5 个）→ 序号必然失配。且步骤只有 `open_app(wait_home=false)+wait`，没有"等首页就绪"。
-  - 期望：①`open_app` 默认/提示勾选「等待首页」，或在编辑器给"点击前自动等某元素"的建议；②抓取器对**带 `#k/N` 序号**的选择器加醒目提示（"界面变化会失配，优先用文字/唯一 id"）；③抓取弹窗提醒"请先把设备停在任务运行到该步时的同一界面再抓"。
-  - 涉及：`core/uiauto_helper.py`、`static/admin/editor.js`（picker 提示）、`tasks/generic/task.py`（open_app 等待策略）、`doc/TASK_DEV.md`。
 
-## AI 控制台 / 经验与动作
+## D. AI 控制台 / 经验与动作
 
 - [ ] 「🧠 经验库 / 🎬 动作库」合为一个面板（标签页切换）。
-- [ ] AI 建任务 P0：平台级 MCP 工具（只读清单 `task_types/groups/pool` + `submit_task(draft)` 校验）+ 把**动作库**当作 generic_steps 的预制件复用（见 `doc/AI_TASK_GEN.md` §9）。
+- [ ] AI 建任务 P0：平台级 MCP 工具（只读清单 `task_types/groups/pool` + `submit_task(draft)` 校验）+ 把**动作库**当作 generic_steps 的预制件复用（见 [AI_TASK_GEN.md](../AI_TASK_GEN.md) §9）。
-- [ ] 新增 MCP `de_screen_text`（文本化看屏：前台包名 + screen_state + 可点元素文本 + OCR），并把操作纪律写进工具 description（对外部客户端尤其有用）。
+- [ ] 新增 MCP `de_screen_text`（文本化看屏：前台包名 + screen_state + 可点元素文本 + OCR），并把操作纪律写进工具 description。
-- [ ] 经验召回改进：现为 bigram + `ORDER BY hits`（候选只看 top50、hits 对所有命中行回写 → 马太效应）；改为对称相似度/更合理候选集，hits 仅在真正注入时 +1。
+- [ ] 经验召回改进：现为 bigram + `ORDER BY hits`（候选只看 top50、hits 对所有命中行回写 → 马太效应）；改为对称相似度 / 更合理候选集，`hits` 仅在真正注入时 +1。
 - [ ] 经验/动作入库依赖模型蒸馏成功：加失败重试与可视化观测（现在只在日志里）。
 
-## 其他
+---
 
-- [ ] `platform-tools` → `auto_control` 命名统一（README/服务名/单元名，待定）。
+## E. 工程化 / 文档
-- [ ] STF 容器状态确认：`doc/DEVELOPMENT.md`（已停用）与 `doc/STF_REMOVAL.md`（待人工确认）说法矛盾，需以 220 实际为准后统一。
+
-- [ ] MCP 白名单语义缺口：`MCP_ALLOWED_SERIALS` 为空时并未按设计限制为"平台设备池内"（当前只校验非空），见 `doc/MCP.md`；如需收紧需补实现。
+- [ ] **MCP 白名单语义缺口**：`MCP_ALLOWED_SERIALS` 为空时并未按设计限制为"平台设备池内"（当前只校验非空），见 [MCP.md](../MCP.md)；如需收紧需补实现。
+- [ ] **`MCP_DESIGN.md` 里的"演进备选"（独立 mcp-server 容器）未落地**：已在文中标注，若确定不做可删除该节，避免后续误读。
+- [ ] **STF 容器状态确认**：`doc/DEVELOPMENT.md`（已停用）与 `doc/STF_REMOVAL.md`（待人工确认）说法矛盾，需以 220 实际为准后统一。
+- [ ] **`DISCOVERY_SUBNETS` 无 env 支持**：`config.py` 里是硬编码列表，其余发现配置走 `app_meta`；若要支持 `.env` 覆盖需补实现。
+
+---
+
+## F. 已完成（留档，便于追溯）
+
+- [x] `platform-tools` → `auto_control` 命名统一（2026-09-10：文档/README/`scripts/pack.py` 产物名）。
+- [x] 删除抖音养号任务类型（`douyin_nurture`），平台只保留 `generic_steps`；残留旧类型任务改为**启动告警 + 执行时明确报错**。
+- [x] `generic_steps` 去掉默认步骤；空步骤任务执行时明确报错（不再静默空跑）。
+- [x] 重试耗尽时的 `last_error` 带上真实失败原因（不再只有"重试 N 次失败"）。
+- [x] 监控页任务卡去掉「编辑/删除」，只留执行/停用 + 显示**覆盖设备**。
+- [x] 备份覆盖清单补 `agent_action` / `app_meta` + 导出/导入双向自检。
+- [x] AI 控制台：Markdown 渲染、推理链可折叠、token 用量显示。
+- [x] 路由回归脚本 Windows 可用（2026-09-13：`signal.alarm` 加 `hasattr` 守卫）+ 新增安全闸：
+  配置或目标库被标为 `prod` 时**拒绝运行**（脚本会发真实写请求，不能拿生产数据做实验）。
+- [x] 数据库从 SQLite 迁到 MySQL：连接层多环境配置 + 防混库校验、schema 收敛到 ORM metadata、
+  备份/恢复改为「SQLite 归档 + 单事务整库替换」、迁移脚本（2026-09-13）。

doc/staffdeck/JOB_SPEC.md

@@ -152,3 +152,5 @@ P0 接收与澄清 → P1 选设备与预检(含"屏幕是否点亮/解锁") →
 - 知识库（工具/约定/红线）：`doc/staffdeck/KNOWLEDGE_BASE.md`
 - 工具手册：`doc/MCP.md`；平台接口：`doc/API.md`
 - 安全与配置：`doc/DEPLOY.md`、`doc/DEVELOPMENT.md`
+- AI 控制台机制 / 架构 / 数据：`doc/AI_CONSOLE.md`、`doc/ARCHITECTURE.md`、`doc/DATA_MODEL.md`
+- 文档总索引：`doc/README.md`

doc/staffdeck/KNOWLEDGE_BASE.md

@@ -248,4 +248,6 @@ P0 接收与澄清 → P1 选设备与预检(§6) → P2 到达起点 → P3 主
 ## 12. 当前边界与相关文档
 - MCP 无任务 CRUD、无独立鉴权（靠网络隔离）。
 - `doc/MCP.md`（工具手册）｜`doc/MCP_DESIGN.md`（设计与现状对照）｜`doc/API.md`（REST 目录）
+- 平台内部机制：`doc/AI_CONSOLE.md`（AI 控制台）、`doc/ARCHITECTURE.md`（架构）、`doc/DATA_MODEL.md`（数据）
+- 文档总索引：`doc/README.md`
 - 岗位职责与授权分级：`doc/staffdeck/JOB_SPEC.md`

mcp_agent/agent.py

@@ -8,6 +8,8 @@
   - content/reasoning_content 增量逐 chunk 回调（kind 区分）
   - tool_calls 分片累积（arguments 按 index 拼接），流结束后统一执行
   - 截图（de_screenshot）图像转 image_url 追加下一轮，同时 on_tool 回调带缩略
+  - token 用量：请求带 stream_options.include_usage，按「每次模型调用」累计，
+    on_usage 回调吐出累计值（Web 控制台展示）
 """
 import base64
 import json
@@ -22,10 +24,15 @@ _log = logging.getLogger("agent")
 
 S = AgentSettings()
 
+
+class _UsageUnsupported(RuntimeError):
+    """模型/网关不认 stream_options.include_usage（400/422 或报错点名该字段）——降级重试用。"""
+
 SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操作 Android 手机。
 
 工作规范：
-1. 先 de_list_devices 确定目标设备（在线才可操作）
+1. 先 de_list_devices 确定目标设备（在线才可操作）；设备有 name（名称）与 serial（地址），
+   **给用户汇报时用名称**（同型号多台靠它区分），调工具时仍用 serial
 2. 观察屏幕：先 de_screenshot 获取截图（图像会随后给你），基于截图理解当前界面
 3. 点击定位分优先级（不要自己推算像素坐标，那是精度最差的方式）：
    a) 目标有可见文字（按钮/菜单/列表标题/标签/输入框提示）→ de_tap_text 直接给文字，
@@ -56,8 +63,15 @@ class Agent:
         # 回调（Web 展示用，均可选）：
         #   on_delta(text, kind)  kind: content | reasoning   —— 流式文本增量
         #   on_tool(step)         step: {tool, args, result, image} —— 工具调用完成
+        #   on_usage(usage)       usage: {prompt_tokens, completion_tokens,
+        #                                 total_tokens, calls} —— 累计 token 用量
         self.on_delta = None
         self.on_tool = None
+        self.on_usage = None
+        # 本轮累计用量（run_stream 开始时重置）
+        self.usage = {"prompt_tokens": 0, "completion_tokens": 0,
+                      "total_tokens": 0, "calls": 0}
+        self._include_usage = True   # 模型不认 stream_options 时自动置 False
         self._mcp = None
 
     # ---------- MCP 工具桥 ----------
@@ -88,7 +102,23 @@ class Agent:
 
     # ---------- 模型调用（流式） ----------
     async def _chat_stream(self):
-        """流式 chat/completions：逐 chunk 产出 JSON（async generator）。"""
+        """流式 chat/completions：逐 chunk 产出 JSON（async generator）。
+
+        默认要求服务端在末尾 chunk 带 usage（token 统计）；个别网关不认
+        `stream_options` 会直接 400，此时自动降级重试一次（不影响主流程）。
+        """
+        if self._include_usage:
+            try:
+                async for chunk in self._chat_stream_once(True):
+                    yield chunk
+                return
+            except _UsageUnsupported as e:
+                _log.warning("模型不支持 stream_options.include_usage，降级重试：%s", e)
+                self._include_usage = False
+        async for chunk in self._chat_stream_once(False):
+            yield chunk
+
+    async def _chat_stream_once(self, with_usage):
         body = {
             "model": self.s.model,
             "messages": self.messages,
@@ -96,6 +126,8 @@ class Agent:
             "max_tokens": 4096,
             "stream": True,
         }
+        if with_usage:
+            body["stream_options"] = {"include_usage": True}
         headers = {"Authorization": f"Bearer {self.s.api_key}",
                    "Content-Type": "application/json"}
         url = f"{self.s.api_base.rstrip('/')}/chat/completions"
@@ -103,6 +135,11 @@ class Agent:
             async with client.stream("POST", url, json=body, headers=headers) as r:
                 if r.status_code != 200:
                     text = (await r.aread()).decode(errors="replace")
+                    # 本次开了 include_usage 却被打回（400/422，或报错里点名这个字段）
+                    # → 视作网关不支持，交给上层降级重试（401/余额等真错误照常抛出）
+                    if with_usage and (r.status_code in (400, 422)
+                                       or "stream_options" in text):
+                        raise _UsageUnsupported(text[:200])
                     raise RuntimeError(f"模型 API HTTP {r.status_code}: {text[:300]}")
                 async for line in r.aiter_lines():
                     if not line.startswith("data:"):
@@ -115,6 +152,37 @@ class Agent:
                     except json.JSONDecodeError:
                         continue
 
+    # ---------- token 用量 ----------
+    @staticmethod
+    def _read_usage(raw):
+        """把一次模型调用返回的 usage 规整为 {prompt, completion, total}；无效返回 None。"""
+        if not isinstance(raw, dict):
+            return None
+        try:
+            pt = int(raw.get("prompt_tokens") or 0)
+            ct = int(raw.get("completion_tokens") or 0)
+            tt = int(raw.get("total_tokens") or 0) or (pt + ct)
+        except (TypeError, ValueError):
+            return None
+        if not (pt or ct or tt):
+            return None
+        return {"prompt_tokens": pt, "completion_tokens": ct, "total_tokens": tt}
+
+    def _accumulate_usage(self, raw):
+        """把一次模型调用的 usage 累加进本轮总量，并回调 on_usage（累计值）。"""
+        u = self._read_usage(raw)
+        if not u:
+            return
+        self.usage["prompt_tokens"] += u["prompt_tokens"]
+        self.usage["completion_tokens"] += u["completion_tokens"]
+        self.usage["total_tokens"] += u["total_tokens"]
+        self.usage["calls"] += 1
+        if self.on_usage:
+            try:
+                self.on_usage(dict(self.usage))
+            except Exception:
+                pass
+
     # ---------- 工具执行 ----------
     async def _execute_tool(self, name, arguments):
         """执行 MCP 工具，返回 (文本结果, image_data_or_None)。"""
@@ -161,7 +229,7 @@ class Agent:
     # ---------- 主循环（流式） ----------
     async def run_stream(self, prompt: str, serial: str = "",
                          history=None, on_delta=None, on_tool=None,
-                         should_stop=None, extra_context=None):
+                         should_stop=None, extra_context=None, on_usage=None):
         """流式执行一轮指令，返回最终完整文本。
 
         history：上一轮的 [{"role": "user"|"assistant", "content": 文本}] 列表，
@@ -170,9 +238,15 @@ class Agent:
         on_tool(step)：工具调用完成（实时显示 MCP 步骤）
         should_stop：可调用 fn() -> bool，每轮模型调用前检查（用户中断用）
         extra_context：附加文本（经验记忆注入，放在 system prompt 末尾）
+        on_usage(usage)：每完成一次模型调用回调一次（累计值，见 self.usage）
+
+        本轮累计 token 用量同时留在 self.usage（调用方可直接读）。
         """
         self.on_delta = on_delta
         self.on_tool = on_tool
+        self.on_usage = on_usage
+        self.usage = {"prompt_tokens": 0, "completion_tokens": 0,
+                      "total_tokens": 0, "calls": 0}
         target = serial or self.s.default_serial
         sys_txt = SYSTEM_PROMPT
         if target:
@@ -193,9 +267,13 @@ class Agent:
             tool_acc = {}           # index -> {id, name, args}
             has_tool = False
             retried = False
+            call_usage = None       # 本次模型调用的 usage（末尾 chunk 带）
             while True:
+                call_usage = None   # 重试时丢弃上一次（未完成）的用量
                 try:
                     async for chunk in self._chat_stream():
+                        if chunk.get("usage"):
+                            call_usage = chunk["usage"]
                         choice = (chunk.get("choices") or [{}])[0]
                         delta = choice.get("delta") or {}
                         text = delta.get("content")
@@ -228,6 +306,7 @@ class Agent:
                         continue
                     raise
 
+            self._accumulate_usage(call_usage)
             full_content = "".join(content_parts)
 
             if has_tool:
@@ -272,13 +351,17 @@ class Agent:
                                              "已完成的部分、当前设备状态、未能完成的原因与下一步建议。"
                                              "不要调用任何工具。"})
             parts = []
+            call_usage = None
             async for chunk in self._chat_stream():
+                if chunk.get("usage"):
+                    call_usage = chunk["usage"]
                 delta = (chunk.get("choices") or [{}])[0].get("delta") or {}
                 text = delta.get("content")
                 if text:
                     parts.append(text)
                     if on_delta:
                         on_delta(text, "content")
+            self._accumulate_usage(call_usage)
             self.tools_schema = saved_tools
             summary = "".join(parts)
             return summary or "（已达步骤上限，模型未能生成总结）"

mcp_server/mcp_server.py

@@ -98,9 +98,11 @@ def _ok(data):
 
 @mcp.tool()
 def de_list_devices() -> dict:
-    """列出可控制设备：serial/在线状态/型号/任务状态/前台 App。
+    """列出可控制设备：名称/地址/在线状态/型号/任务状态/前台 App。
 
-    返回 [{serial, model, online, task_job, worker_status, foreground_app}]。
+    返回 [{serial, name, model, online, task_job, worker_status, foreground_app}]。
+    `name` 是设备在平台里的名称（设备池里的身份标识）；对你的用户汇报时**优先用名称**
+    （多台同型号设备时靠它区分）。后续所有工具仍然用 `serial` 指定设备。
     """
     try:
         devs = platform().list_devices()
@@ -110,7 +112,8 @@ def de_list_devices() -> dict:
     for d in devs:
         out.append({
             "serial": d.get("serial"),
-            "model": d.get("model") or d.get("device_name") or "",
+            "name": d.get("device_name") or "",
+            "model": d.get("model") or "",
             "online": bool(d.get("present")),
             "task_job": d.get("task_job") or "",
             "worker_status": d.get("worker_status") or "idle",

requirements.txt

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

scripts/migrate_sqlite_to_mysql.py

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

scripts/pack.py

@@ -1,14 +1,14 @@
 """打包脚本：把项目代码打成 zip 压缩包，排除运行时产物。
 
 用法：python scripts/pack.py
-输出：项目根目录下 platform-tools.zip
+输出：项目根目录下 auto_control.zip
 """
 import os
 import sys
 import zipfile
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-OUT = os.path.join(os.path.dirname(ROOT), "platform-tools.zip")
+OUT = os.path.join(os.path.dirname(ROOT), "auto_control.zip")
 
 SKIP_DIRS = {"__pycache__", ".git", ".idea", "venv", ".venv", "node_modules"}
 SKIP_EXTS = {".pyc", ".pyo"}

scripts/regression_test.py

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

scripts/sql/init_mysql_5.7.sql

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

scripts/start.sh

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

static/admin/admin.js

@@ -4,7 +4,9 @@ async function loadGroups(){
   const r=await apiGet('/api/groups');if(!r)return;
   _groupsList=r.groups||[];
   const dr=await apiGet('/api/devices');
-  _devicesList=dr?dr.devices||[]:[];
+  // items 带名称（设备身份）；老接口只有 serial 列表时兜底成对象
+  _devicesList=(dr&&dr.items)?dr.items
+    :((dr&&dr.devices)||[]).map(s=>({serial:s,name:'',model:''}));
   renderGroupTable();
 }
 
@@ -43,9 +45,12 @@ function openGroupModal(name){
   document.getElementById('modal-title').textContent=isEdit?'编辑分组':'新建分组';
   const g=group||{name:'',description:'',serials:[]};
   const current= new Set(g.serials||[]);
-  const allSerials=[...new Set([..._devicesList, ...(g.serials||[])])].sort();
+  const nameOf={};
+  (_devicesList||[]).forEach(x=>{ if(x&&x.serial) nameOf[x.serial]=x.name||''; });
+  const allSerials=[...new Set([...(_devicesList||[]).map(x=>x.serial||x), ...(g.serials||[])])].sort();
   const deviceCheckboxes=allSerials.map(s=>
-    '<label><input type="checkbox" value="'+esc(s)+'" '+(current.has(s)?'checked':'')+'>'+esc(s)+'</label>'
+    '<label><input type="checkbox" value="'+esc(s)+'" '+(current.has(s)?'checked':'')+'>'
+      +esc(nameOf[s]?devText(nameOf[s], s):s)+'</label>'
   ).join('');
 
   document.getElementById('modal-body').innerHTML=

static/admin/agent.js

@@ -16,6 +16,12 @@ function _friendlyAgentError(msg){
 
 // ================== 初始化 ==================
 let _agentDefaultSerial = '';
+// 目标设备显示文案：名称优先（设备身份），没有名称退地址
+let _agentTargets={};   // serial -> name
+function _agentTargetText(serial){
+  const nm=_agentTargets[serial];
+  return nm ? (nm + ' · ' + serial) : String(serial||'');
+}
 function initAgentChat(){
   if(_agentCfgLoaded)return;
   _agentCfgLoaded = true;
@@ -81,9 +87,11 @@ function loadAgentTargetDevices(){
     if(!sel)return;
     const cur = sel.value;
     const devs = (r.devices||[]).filter(x=>x.online);
+    _agentTargets = {};
+    devs.forEach(d=>{ if(d.name) _agentTargets[d.serial]=d.name; });
     sel.innerHTML = '<option value="">请选择设备（AI 只操作选定设备）…</option>'
       + devs.map(d=>{
-          const label = d.serial + (d.model ? ' · ' + d.model : '')
+          const label = devText(d.name, d.serial) + (d.model ? ' · ' + d.model : '')
             + (d.busy ? ' ⛔ 任务中：' + d.task_job : '');
           return '<option value="'+esc(d.serial)+'"' + (d.busy ? ' disabled' : '')
             + '>' + esc(label) + '</option>';
@@ -93,7 +101,7 @@ function loadAgentTargetDevices(){
     else if(_agentDefaultSerial && [...sel.options].some(o=>o.value===_agentDefaultSerial))
       sel.value = _agentDefaultSerial;
     const hint = document.getElementById('agent-target-hint');
-    if(hint && sel.value) hint.textContent = '将操作：' + sel.value;
+    if(hint && sel.value) hint.textContent = '将操作：' + _agentTargetText(sel.value);
   });
 }
 
@@ -114,12 +122,18 @@ function pollRunState(){
     if(hint){
       hint.textContent = running
         ? ('⏳ 运行中' + (r.started ? ' ' + r.started + ' 起' : '')
-           + (r.serial ? ' · ' + r.serial : '')
+           + (r.serial ? ' · ' + _agentTargetText(r.serial) : '')
            + '：' + (r.prompt||'').slice(0,70))
         : (document.getElementById('agent-target-select').value
-           ? '将操作：' + document.getElementById('agent-target-select').value : '');
+           ? '将操作：' + _agentTargetText(document.getElementById('agent-target-select').value)
+           : '');
     }
     document.getElementById('btn-agent-send').disabled = running;
+    // 运行中同步 token（本窗口没订阅事件流时也能看到进度）
+    if(running && !_agentStream && r.usage && r.usage.total_tokens){
+      _liveUsage = r.usage;
+      updateSessionTokens();
+    }
     if(!running && _agentBusy){ setRunning(false); }   // 流异常丢失时复位
   });
 }
@@ -173,11 +187,91 @@ function newAssistantMsg(){
   clearEmpty();
   const div = document.createElement('div');
   div.className = 'agent-msg assistant';
-  div.innerHTML = '<div class="agent-toolcards"></div><div class="agent-text"></div>';
+  // 结构：工具卡片 → 可折叠推理链 → 正文（Markdown）→ token 用量脚注
+  div.innerHTML =
+      '<div class="agent-toolcards"></div>'
+    + '<details class="reasoning" style="display:none"><summary>💭 思考过程</summary>'
+    +   '<div class="reasoning-text"></div></details>'
+    + '<div class="agent-text"></div>'
+    + '<div class="agent-usage" style="display:none"></div>';
   chat.appendChild(div);
   scrollChat();
   return div;
 }
+
+// ---------- 推理链（可折叠） ----------
+function _appendReasoning(msgEl, text){
+  const box = msgEl.querySelector('.reasoning');
+  if(!box) return;
+  const body = box.querySelector('.reasoning-text');
+  body.textContent += text;
+  box.querySelector('summary').textContent =
+    '💭 思考过程（' + body.textContent.length + ' 字）';
+  box.style.display = 'block';
+  _bindReasoning(box);
+  if(!box.open) box.open = true;      // 流式思考时展开，正文开始时自动收起
+}
+// 用户手动点过 summary 后不再自动收起/展开（尊重手动状态）
+function _bindReasoning(box){
+  const sum = box.querySelector('summary');
+  if(sum && !sum.dataset.bound){
+    sum.dataset.bound = '1';
+    sum.addEventListener('click', ()=>{ box.dataset.touched = '1'; });
+  }
+}
+
+// ---------- 正文 Markdown 渲染（渲染器见 markdown.js） ----------
+function _renderMd(msgEl){
+  const el = msgEl.querySelector('.agent-text');
+  if(el) el.innerHTML = renderMarkdown(msgEl._md || '');
+}
+function _scheduleMd(msgEl){
+  if(msgEl._mdRaf) return;            // 流式增量按帧合并渲染，避免每个 token 重排
+  msgEl._mdRaf = requestAnimationFrame(()=>{
+    msgEl._mdRaf = 0;
+    _renderMd(msgEl);
+    scrollChat();
+  });
+}
+
+// ---------- token 用量 ----------
+let _convUsage = {};    // 当前会话历史累计（读会话时算）
+let _liveUsage = {};    // 本轮运行中累计（SSE usage 事件）
+function _fmtInt(n){ return String(n || 0).replace(/\B(?=(\d{3})+(?!\d))/g, ','); }
+function _usageSum(a, b){
+  const o = {prompt_tokens:0, completion_tokens:0, total_tokens:0, calls:0};
+  [a, b].forEach(u=>{
+    if(!u) return;
+    o.prompt_tokens     += (u.prompt_tokens || 0);
+    o.completion_tokens += (u.completion_tokens || 0);
+    o.total_tokens      += (u.total_tokens || 0);
+    o.calls             += (u.calls || 0);
+  });
+  return o;
+}
+// 单条消息脚注
+function renderUsage(msgEl, u){
+  const el = msgEl.querySelector('.agent-usage');
+  if(!el) return;
+  if(!u || !u.total_tokens){ el.style.display = 'none'; return; }
+  el.style.display = 'block';
+  el.title = '输入 ' + _fmtInt(u.prompt_tokens) + ' + 输出 ' + _fmtInt(u.completion_tokens)
+           + ' = ' + _fmtInt(u.total_tokens) + ' tokens，共 ' + (u.calls || 0) + ' 次模型调用';
+  el.textContent = '🪙 ' + _fmtInt(u.total_tokens) + ' tokens'
+                 + '（↑' + _fmtInt(u.prompt_tokens) + ' ↓' + _fmtInt(u.completion_tokens)
+                 + ' · ' + (u.calls || 0) + ' 次调用）';
+}
+// 顶栏「本会话累计」= 已落库历史 + 运行中本轮
+function updateSessionTokens(){
+  const el = document.getElementById('agent-token-total');
+  if(!el) return;
+  const t = _usageSum(_convUsage, _liveUsage);
+  if(!t.total_tokens){ el.textContent = ''; el.title = ''; return; }
+  el.textContent = '🪙 本会话 ' + _fmtInt(t.total_tokens) + ' tokens';
+  el.title = '本会话累计：输入 ' + _fmtInt(t.prompt_tokens)
+           + ' + 输出 ' + _fmtInt(t.completion_tokens)
+           + ' = ' + _fmtInt(t.total_tokens) + ' tokens，共 ' + t.calls + ' 次模型调用';
+}
 function clearEmpty(){
   const empty = document.querySelector('#agent-chat .agent-empty');
   if(empty) empty.remove();
@@ -197,6 +291,9 @@ function bindChatScroll(){
 }
 function clearAgentChat(){
   document.getElementById('agent-chat').innerHTML = '';
+  _convUsage = {};    // 换会话：token 累计重新算
+  _liveUsage = {};
+  updateSessionTokens();
 }
 
 // ================== 历史会话（DeepSeek 式：左侧列表，多会话持久化） ==================
@@ -293,15 +390,26 @@ function loadCurrentConvMessages(){
   apiGet('/api/agent/conversations/'+_currentConvId).then(r=>{
     if(!r||!r.ok)return;
     chat.innerHTML = '';
+    _convUsage = {};
+    _liveUsage = {};
     (r.messages||[]).forEach(m=>{
       const txt = (m.content||'').trim();
-      if(!txt) return;
+      if(m.role==='user'){ if(txt) addUserMsg(txt); return; }
-      if(m.role==='user'){ addUserMsg(txt); }
+      if(!txt && !m.reasoning && !(m.usage && m.usage.total_tokens)) return;
-      else{
       const div = newAssistantMsg();
-        div.querySelector('.agent-text').textContent = txt;
+      if(txt){ div._md = txt; _renderMd(div); }
+      if(m.reasoning){
+        _appendReasoning(div, m.reasoning);
+        const box = div.querySelector('.reasoning');
+        _bindReasoning(box);
+        box.open = false;                 // 历史消息默认折叠推理链
+      }
+      if(m.usage){
+        renderUsage(div, m.usage);
+        _convUsage = _usageSum(_convUsage, m.usage);
       }
     });
+    updateSessionTokens();
     if(!chat.children.length){
       chat.innerHTML = '<div class="agent-empty">新会话。给 AI 下达指令'
         + '（先选 🎯 目标设备）…</div>';
@@ -379,21 +487,29 @@ function listenStream(runId){
   es.addEventListener('delta', ev=>{
     if(!msgEl) msgEl = newAssistantMsg();
     const d = JSON.parse(ev.data);
-    const textEl = msgEl.querySelector('.agent-text');
     if(d.kind === 'reasoning'){
-      let r = msgEl.querySelector('.reasoning');
+      _appendReasoning(msgEl, d.text || '');
-      if(!r){
-        r = document.createElement('div');
-        r.className = 'reasoning';
-        msgEl.insertBefore(r, textEl);
-      }
-      r.textContent += d.text;
     }else{
-      textEl.textContent += d.text;
+      // 正文开始 → 收起推理链（用户手动开过的保持原样）
+      const r = msgEl.querySelector('.reasoning');
+      if(r && r.open && !r.dataset.touched) r.open = false;
+      msgEl._md = (msgEl._md || '') + (d.text || '');
+      msgEl._mdPending = false;
+      _scheduleMd(msgEl);
     }
     scrollChat();
   });
 
+  // 每次模型调用完成 → 实时刷新 token 计数（本轮累计）
+  es.addEventListener('usage', ev=>{
+    if(!msgEl) msgEl = newAssistantMsg();
+    let d = {};
+    try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    _liveUsage = d;
+    renderUsage(msgEl, d);
+    updateSessionTokens();
+  });
+
   es.addEventListener('step', ev=>{
     const d = JSON.parse(ev.data);
     followSerialFromArgs(d.args);
@@ -417,10 +533,16 @@ function listenStream(runId){
 
   es.addEventListener('done', ev=>{
     const d = JSON.parse(ev.data);
-    if(d.answer){
+    if(d.answer || d.usage || !msgEl){
       if(!msgEl) msgEl = newAssistantMsg();
-      msgEl.querySelector('.agent-text').textContent = d.answer;
+      if(d.answer){ msgEl._md = d.answer; _renderMd(msgEl); }
+      if(d.usage) renderUsage(msgEl, d.usage);
     }
+    // 本轮用量并入会话累计（脚注已展示，顶栏不该因此变小），再清空「运行中」
+    _convUsage = _usageSum(_convUsage, _liveUsage);
+    _liveUsage = {};
+    updateSessionTokens();
+    scrollChat();
     endRun();
     renderConvList();   // 落库已完成：刷新标题/时间/轮数
   });
@@ -432,6 +554,7 @@ function listenStream(runId){
     }catch(e){}
     if(!msgEl) msgEl = newAssistantMsg();
     msgEl.querySelector('.agent-text').textContent = '⚠ ' + _friendlyAgentError(msg);
+    _liveUsage = {};            // 本轮可能已花费 token，但结果无效——不并入会话累计
     endRun();
   });
 
@@ -494,9 +617,13 @@ function loadLiveDevices(){
     const sel = document.getElementById('agent-live-select');
     if(!sel)return;
     const cur = sel.value;
-    const devs = (r.devices||[]).filter(x=>x.indexOf(':')>=0);
+    // items 带设备名称（设备身份）；老接口只有 serial 列表时兜底
+    const items = (r.items && r.items.length ? r.items
+                   : (r.devices||[]).map(x=>({serial:x, name:''})))
+                  .filter(x=>String(x.serial||'').indexOf(':')>=0);
     sel.innerHTML = '<option value="">选择设备观看…</option>'
-      + devs.map(s=>'<option value="'+esc(s)+'"'+(s===cur?' selected':'')+'>'+esc(s)+'</option>').join('');
+      + items.map(x=>'<option value="'+esc(x.serial)+'"'+(x.serial===cur?' selected':'')+'>'
+                     +esc(devText(x.name, x.serial))+'</option>').join('');
   });
 }
 

static/admin/apps.js

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

static/admin/base.js

@@ -3,6 +3,13 @@
 const ACTION_LABELS={like:'点赞',comment:'评论',follow:'关注',share:'分享'};
 const STATUS_MAP={idle:{t:'未启动',c:'default'},connecting:{t:'连接中',c:'warning'},running:{t:'运行中',c:'success'},done:{t:'完成',c:'primary'},error:{t:'异常',c:'danger'},released:{t:'已释放',c:'default'},failed:{t:'失败',c:'danger'}};
 const TARGET_MAP={all:'全部空闲',group:'按分组',serial:'指定设备'};
+
+// 设备显示文案：**名称是设备身份**，地址只是当前连接位置。
+// 有名称 → 「名称 · serial」；没名称（历史数据）→ 只显示 serial
+function devText(name, serial){
+  const n=String(name||'').trim();
+  return n ? (n + ' · ' + serial) : String(serial||'');
+}
 const APP_NAMES={'com.ss.android.ugc.aweme':'抖音','com.ss.android.ugc.aweme.lite':'抖音极速版','com.smile.gifmaker':'快手','com.kuaishou.nebula':'快手极速版','com.tencent.mm':'微信','com.tencent.mobileqq':'QQ','com.tencent.qqlive':'腾讯视频','com.eg.android.AlipayGphone':'支付宝','com.taobao.taobao':'淘宝','com.tmall.wireless':'天猫','com.jingdong.app.mall':'京东','com.xunmeng.pinduoduo':'拼多多','com.ss.android.article.news':'今日头条','com.zhihu.android':'知乎','com.miui.home':'桌面','com.android.launcher':'桌面','com.android.settings':'设置','com.android.systemui':'系统','com.github.uiautomator':'U2','com.github.uiautomator.test':'U2测试'};
 
 function esc(s){return String(s||'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));}
@@ -116,6 +123,7 @@ function showSubTab(tabId, name){
   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==='apks' && typeof loadAgentStore==='function') loadAgentStore();
   if(name==='devpool' && typeof loadDevPool==='function'){
     loadDevPool();
     if(typeof loadDiscovery==='function'){

static/admin/markdown.js

@@ -0,0 +1,163 @@
+// 轻量 Markdown 渲染（AI 控制台回答用）——不引外部库/CDN（生产 220 在内网）。
+// 安全：**先 esc() 转义，再套标记**——模型输出里的原始 HTML 只会以文本显示，
+//       不会变成可执行标签。
+// 支持：标题 / 段落 / 换行 / 粗体 / 斜体 / 删除线 / 行内代码 / 围栏代码块 /
+//       有序与无序列表（含一层以上嵌套）/ 引用 / 表格 / 分隔线 / 链接。
+// 依赖：esc()（base.js，本文件须在其后加载）
+
+// 行内代码占位符（控制字符，正文几乎不可能出现）
+const _MD_PH = '\u0001';
+
+function _mdInline(s){
+  const codes = [];
+  // 行内代码先摘出，避免其中的 ** * ~~ 被继续当标记解析
+  s = s.replace(/`([^`]+)`/g, (m, c)=>{
+    codes.push(c);
+    return _MD_PH + (codes.length - 1) + _MD_PH;
+  });
+  s = s.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+       .replace(/~~([^~]+)~~/g, '<del>$1</del>')
+       .replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<em>$2</em>')
+       .replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g,
+                '<a href="$2" target="_blank" rel="noopener noreferrer">$1</a>');
+  return s.replace(new RegExp(_MD_PH + '(\\d+)' + _MD_PH, 'g'),
+                   (m, i)=>'<code>' + codes[+i] + '</code>');
+}
+
+// 表格行 → 单元格数组
+function _mdCells(line){
+  return line.trim().replace(/^\|/, '').replace(/\|$/, '')
+             .split('|').map(c=>c.trim());
+}
+
+// 列表项递归渲染（缩进 = 层级；同类标记合并，类型变了外层另起一个列表）
+function _mdList(items, out, idx, indent){
+  const ordered = items[idx].ordered;
+  const tag = ordered ? 'ol' : 'ul';
+  out.push('<' + tag + ' class="md-list">');
+  while(idx < items.length && items[idx].indent >= indent){
+    const it = items[idx];
+    if(it.indent > indent) break;               // 更深缩进块由外层另起列表（避免非法嵌套）
+    if(it.ordered !== ordered) break;           // 同级但标记类型变了 → 交回外层
+    out.push('<li>' + _mdInline(esc(it.text)));
+    if(idx + 1 < items.length && items[idx + 1].indent > indent){
+      idx = _mdList(items, out, idx + 1, items[idx + 1].indent);
+      out.push('</li>');
+      continue;
+    }
+    out.push('</li>');
+    idx++;
+  }
+  out.push('</' + tag + '>');
+  return idx;
+}
+
+// 主入口：Markdown 文本 → HTML 字符串
+function renderMarkdown(src){
+  const lines = String(src == null ? '' : src).replace(/\r\n?/g, '\n').split('\n');
+  const out = [];
+  let para = [];
+  let i = 0;
+
+  const flushPara = ()=>{
+    if(!para.length) return;
+    out.push('<p>' + para.map(l=>_mdInline(esc(l))).join('<br>') + '</p>');
+    para = [];
+  };
+
+  while(i < lines.length){
+    const ln = lines[i];
+    let m;
+
+    // 围栏代码块 ```lang … ```
+    if(/^\s*```/.test(ln)){
+      flushPara();
+      const body = [];
+      i++;
+      while(i < lines.length && !/^\s*```/.test(lines[i])){ body.push(lines[i]); i++; }
+      if(i < lines.length) i++;                 // 跳过结束围栏
+      out.push('<pre class="md-code"><code>' + esc(body.join('\n')) + '</code></pre>');
+      continue;
+    }
+
+    // 表格：表头行 + 分隔行（|---|---|）
+    if(/^\s*\|.*\|\s*$/.test(ln) && i + 1 < lines.length
+       && /^\s*\|[\s:|-]+\|\s*$/.test(lines[i + 1])){
+      flushPara();
+      const head = _mdCells(ln);
+      i += 2;
+      const rows = [];
+      while(i < lines.length && /^\s*\|.*\|\s*$/.test(lines[i])){
+        rows.push(_mdCells(lines[i])); i++;
+      }
+      out.push('<table class="md-table"><thead><tr>'
+        + head.map(c=>'<th>' + _mdInline(esc(c)) + '</th>').join('') + '</tr></thead><tbody>'
+        + rows.map(r=>'<tr>' + r.map(c=>'<td>' + _mdInline(esc(c)) + '</td>').join('')
+                     + '</tr>').join('')
+        + '</tbody></table>');
+      continue;
+    }
+
+    // 标题 #~######
+    m = ln.match(/^\s{0,3}(#{1,6})\s+(.*)$/);
+    if(m){
+      flushPara();
+      const lv = m[1].length;
+      out.push('<h' + lv + ' class="md-h">' + _mdInline(esc(m[2])) + '</h' + lv + '>');
+      i++;
+      continue;
+    }
+
+    // 分隔线 --- / *** / ___
+    if(/^\s{0,3}([-*_])\s*(\1\s*){2,}$/.test(ln)){
+      flushPara(); out.push('<hr>'); i++; continue;
+    }
+
+    // 引用 >
+    if(/^\s{0,3}>\s?/.test(ln)){
+      flushPara();
+      const body = [];
+      while(i < lines.length && /^\s{0,3}>\s?/.test(lines[i])){
+        body.push(lines[i].replace(/^\s{0,3}>\s?/, '')); i++;
+      }
+      out.push('<blockquote class="md-quote">'
+        + body.map(l=>_mdInline(esc(l))).join('<br>') + '</blockquote>');
+      continue;
+    }
+
+    // 列表（- * + / 1. 1)）——含缩进续行
+    m = ln.match(/^(\s*)([-*+]|\d+[.)])\s+(.*)$/);
+    if(m){
+      flushPara();
+      const items = [];
+      while(i < lines.length){
+        const mm = lines[i].match(/^(\s*)([-*+]|\d+[.)])\s+(.*)$/);
+        if(!mm) break;
+        items.push({indent: mm[1].replace(/\t/g, '  ').length,
+                    ordered: /\d/.test(mm[2]), text: mm[3]});
+        i++;
+        // 紧跟的纯缩进行算上一条的续行
+        while(i < lines.length && /^\s+\S/.test(lines[i])
+              && !/^\s*([-*+]|\d+[.)])\s+/.test(lines[i])){
+          items[items.length - 1].text += ' ' + lines[i].trim();
+          i++;
+        }
+      }
+      let k = 0;
+      while(k < items.length){
+        const n = _mdList(items, out, k, items[k].indent);
+        if(n <= k) break;                        // 防死循环
+        k = n;
+      }
+      continue;
+    }
+
+    // 空行 = 段落分隔
+    if(!ln.trim()){ flushPara(); i++; continue; }
+
+    para.push(ln);
+    i++;
+  }
+  flushPara();
+  return out.join('');
+}

static/admin/monitor.js

@@ -70,27 +70,28 @@ async function stopSelectedDevices(){
   setTimeout(loadMonitor,500);
 }
 
-// 定位设备：点亮屏幕 + 打开大字定位页（显示设备 IP），便于在机架上找到目标
+// 打开设备端 Agent：让设备上的 Agent 弹出「身份大字页」（名称/IP/平台地址），
-// 注意：打开定位页会切换设备前台，任务运行中慎用
+// 人站在机架前一眼看出这台是平台上的哪一台。
-async function locateDevice(serial){
+// 替代原来的"推 HTML 让设备浏览器打开定位页"——那条路要设备装浏览器、页面还依赖
-  if(!confirm('点亮 '+serial+' 屏幕并打开大字定位页？\n\n（会切换设备前台显示，任务运行中慎用）'))return;
+// 设备能访问平台，且在 MIUI 上本来就不稳。
-  const r=await apiPost('/api/device/locate',{serial:serial,show:true});
+async function showAgentInfo(serial){
+  const r=await apiPost('/api/agent/show-info',{serial:serial});
   if(!r)return;
   if(r.ok){
     _locatingSerials.add(serial);
-    showToast(r.msg||'已定位','success');
+    showToast(r.msg||'已让设备显示身份信息','success');
     renderDevices();
-  }else showToast(r.error||'定位失败','error');
+  }else showToast(r.error||'打开失败','error');
 }
 
-// 结束定位：关闭设备上的定位页（浏览器），按钮恢复为"定位"
+// 关闭设备端 Agent 的身份页
-async function stopLocate(serial){
+async function hideAgentInfo(serial){
-  const r=await apiPost('/api/device/locate/stop',{serial:serial});
+  const r=await apiPost('/api/agent/show-info',{serial:serial,close:true});
   if(!r)return;
   _locatingSerials.delete(serial);
   renderDevices();
-  if(r.ok)showToast(r.msg||'已结束定位','success');
+  if(r.ok)showToast(r.msg||'已关闭','success');
-  else showToast(r.error||'结束定位失败','error');
+  else showToast(r.error||'关闭失败','error');
 }
 
 // 批量亮屏/息屏所有在线设备（息屏会中断运行中任务，前端已确认）
@@ -344,19 +345,23 @@ function renderDeviceRow(dev){
   // 设备操作按钮需要"设备控制"权限（无权限只保留截图查看）
   const canDev=_can('devices');
   const stopBtn=canDev&&(dev.worker_status==='running'||dev.worker_status==='connecting')?'<button class="btn btn-danger btn-xs" onclick="apiAction(\'/api/stop_device\',{serial:\''+esc(dev.serial)+'\'})">停止</button>':'';
-  // 截图按钮（任何状态都可看，离线时会报错）
+  // 看屏按钮（任何状态都可看，离线时会报错）
-  const shotBtn='<button class="btn btn-xs" onclick="openScreenshot(\''+esc(dev.serial)+'\')" title="查看设备画面（不影响任务）">截图</button>';
+  const shotBtn='<button class="btn btn-xs" onclick="openScreenshot(\''+esc(dev.serial)+'\')" title="查看设备实时画面（不影响任务）">看屏</button>';
-  // 定位按钮：定位中显示"结束定位"（关闭定位页），否则显示"定位"（点亮+大字页）
+  // 设备端 Agent：开着身份页时显示"关闭"，否则"打开设备端 Agent"
   const locating=_locatingSerials.has(dev.serial);
   const locateBtn=canDev?(locating
-    ?'<button class="btn btn-xs btn-danger" onclick="stopLocate(\''+esc(dev.serial)+'\')" title="关闭定位页（退出浏览器）">结束定位</button>'
+    ?'<button class="btn btn-xs btn-danger" onclick="hideAgentInfo(\''+esc(dev.serial)+'\')" title="让设备上的 Agent 关掉身份大字页">关闭 Agent</button>'
-    :'<button class="btn btn-xs" onclick="locateDevice(\''+esc(dev.serial)+'\')" title="点亮屏幕并显示设备IP大字页（会切换前台，任务运行中慎用）">定位</button>'):'';
+    :'<button class="btn btn-xs" onclick="showAgentInfo(\''+esc(dev.serial)+'\')" title="让设备上的 Agent 显示身份大字页（名称/IP/平台地址）——人在机架前对号用（会切换设备前台）">打开设备端 Agent</button>'):'';
   // 异常/失败设备提供"清除异常"（把状态恢复为未启动）
   const clearBtn=canDev&&(dev.worker_status==='error'||dev.worker_status==='failed')
     ?'<button class="btn btn-xs" onclick="clearDeviceError(\''+esc(dev.serial)+'\')" title="清除该设备的异常状态，恢复为未启动">清除异常</button>':'';
   const btns='<div style="display:flex;gap:4px;flex-wrap:wrap">'+shotBtn+locateBtn+clearBtn+stopBtn+'</div>';
-  const devName=dev.device_name||dev.model||'';
+  // 名称优先（设备身份），地址作副标题；未命名的历史数据显示提醒
-  const devLabel=(devName?'<strong>'+esc(dev.serial)+'</strong><br><span style="font-size:11px;color:#94a3b8">'+esc(devName)+'</span>':'<strong>'+esc(dev.serial)+'</strong>')+offline;
+  const nm=(dev.device_name||'').trim();
+  const devLabel=(nm
+      ? '<strong>'+esc(nm)+'</strong><br><span style="font-size:11px;color:#94a3b8;font-family:var(--mono)">'+esc(dev.serial)+'</span>'
+      : '<strong style="font-family:var(--mono)">'+esc(dev.serial)+'</strong>'
+        +'<br><span style="font-size:11px;color:#d97706">未命名</span>') + offline;
   // 复选框列
   const checked=_selectedSerials.has(dev.serial)?'checked':'';
   const rowCls=_selectedSerials.has(dev.serial)?'row-checked':'';
@@ -445,6 +450,36 @@ function fmtParams(params){
   return parts.join('');
 }
 
+// 任务覆盖的设备：后端给 serial 清单（coverage），这里用实时状态标注在线/运行中
+function _jobCoverageHtml(j){
+  const cov=j.coverage||{}, serials=cov.serials||[];
+  const st={};
+  if(_statusData)for(const d of (_statusData.devices||[]))st[d.serial]=d;
+  if(!serials.length){
+    return '<div class="job-cov"><span class="kv">覆盖设备 0 台</span>'
+      +'<span class="cov-note">该目标下暂无可调度设备（检查设备池/分组）</span></div>';
+  }
+  let onlineN=0,busyN=0;
+  const chips=serials.map(s=>{
+    const d=st[s]||{};
+    const online=!!d.present;
+    const busy=(d.worker_status==='running'||d.worker_status==='connecting');
+    if(online)onlineN++;
+    if(busy)busyN++;
+    const cls=busy?'running':(online?'online':'offline');
+    // chip 优先显示设备名称（身份），没有名称才退回地址
+    const nm=(d.device_name||'').trim();
+    const title=s+(nm?' · '+nm:'')+(d.model?' · '+d.model:'')
+      +(busy?' · 任务中：'+(d.task_job||''):'')
+      +(online?'':' · 离线或不在设备池');
+    return '<span class="cov-chip '+cls+'" title="'+esc(title)+'">'
+      +esc(nm || s.replace(/:5555$/,''))+(busy?' ⏳':'')+(online?'':' ✕')+'</span>';
+  }).join('');
+  return '<div class="job-cov"><span class="kv">覆盖 '+serials.length+' 台 · 在线 '+onlineN
+    +(busyN?' · 运行中 '+busyN:'')+'</span>'
+    +'<div class="cov-chips">'+chips+'</div></div>';
+}
+
 function renderJobCards(){
   const jobs=_jobsData||[];
   const running={};
@@ -470,12 +505,11 @@ function renderJobCards(){
         '<span class="kv">调度:'+esc(sched)+'</span>'+
         '<span class="kv">重试:'+esc(retry)+'</span></div>'+
         '<div style="margin-top:4px">'+fmtParams(j.params)+'</div>'+
+        _jobCoverageHtml(j)+
       '</div>'+
       '<div class="job-actions">'+
-        '<button class="btn btn-primary btn-xs" onclick="apiAction(\'/api/jobs/'+j.id+'/run\')">立即执行</button>'+
+        '<button class="btn btn-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="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/system.js

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

static/admin/tasks.js

@@ -12,7 +12,9 @@ async function loadTasks(){
   _jobsData=jr.jobs||[];
   _taskTypes=tr?tr.task_types||[]:[];
   _groupsList=gr?gr.groups||[]:[];
-  _devicesList=dr?dr.devices||[]:[];
+  // items 带名称（设备身份）；老接口只有 serial 列表时兜底成对象
+  _devicesList=(dr&&dr.items)?dr.items
+    :((dr&&dr.devices)||[]).map(s=>({serial:s,name:'',model:''}));
   renderTaskTable();
 }
 
@@ -69,10 +71,11 @@ function openTaskModal(jobId){
   // 任务编辑器含步骤编辑，加宽弹窗；关闭时在 closeModal 移除
   document.getElementById('modal-box').classList.add('wide-modal');
 
-  const j=job||{name:'',task_type:'douyin_nurture',enabled:true,target:{mode:'all'},params:{},schedule:{mode:'once'},retry:{max_attempts:1,delay:60}};
+  const j=job||{name:'',task_type:'generic_steps',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 dl=_devicesList.map(x=>'<option value="'+esc(x.serial)+'"'+(x.serial===j.target.serial?' selected':'')+'>'
+      +esc(devText(x.name, x.serial))+'</option>').join('');
   const sm=j.schedule.mode;
   const startCron=(sm==='cron'||sm==='cron_stop')?(j.schedule.cron||''):'';
   const stopCron=sm==='cron_stop'?(j.schedule.stop_cron||''):'';
@@ -88,7 +91,7 @@ function openTaskModal(jobId){
 
   document.getElementById('modal-body').innerHTML=
     '<div class="form-row">'+
-      '<div class="form-group"><label>任务名</label><input type="text" class="form-control" id="f-name" value="'+esc(j.name)+'" placeholder="如：抖音养号-上午"></div>'+
+      '<div class="form-group"><label>任务名</label><input type="text" class="form-control" id="f-name" value="'+esc(j.name)+'" placeholder="如：刷视频-上午"></div>'+
       '<div class="form-group"><label>任务类型</label><select class="form-control" id="f-task_type" onchange="onTaskTypeChange()">'+tt+'</select></div>'+
     '</div>'+
     '<div class="form-group form-check"><input type="checkbox" id="f-enabled" '+(j.enabled?'checked':'')+'><label for="f-enabled">启用此任务</label></div>'+

static/admin/tools.js

@@ -35,7 +35,7 @@ async function loadToolsDevices(force){
     const stCls = d.state==='device' ? 'label-success' : 'label-warning';
     return '<label data-serial="'+esc(d.serial)+'">'
       +'<input type="checkbox" value="'+esc(d.serial)+'"'+( _clipSelected.has(d.serial)?' checked':'')+' onchange="toggleClipDevice(this)">'
-      +'<span style="font-family:monospace;flex:1;overflow:hidden;text-overflow:ellipsis">'+esc(d.serial)+'</span>'
+      +'<span style="font-family:monospace;flex:1;overflow:hidden;text-overflow:ellipsis">'+esc(devText(d.name,d.serial))+'</span>'
       +'<span class="label '+stCls+'">'+st+'</span></label>';
   }).join('');
   status.textContent = '共 '+_clipDevices.length+' 台设备';
@@ -51,22 +51,26 @@ function loadDiscovery(){
     const subnets=document.getElementById('discovery-subnets');
     if(!enabled)return;   // 面板未渲染（离开子分栏）
     enabled.checked=!!r.enabled;
+    const ac=document.getElementById('discovery-autoclaim');
+    if(ac)ac.checked=!!r.auto_claim;
     interval.value=r.interval||60;
     subnets.value=(r.subnets||[]).join(', ');
     // 状态行
     if(r.scanning){status.textContent='扫描中...';}
     else if(r.last_scan){
       let txt='上次扫描 '+esc(r.last_scan)+' · 开放 '+r.last_result.found+' · 可连 '
-        +(r.last_result.verified||0)+' · 新增 '+(r.last_result.new||0);
+        +(r.last_result.verified||0)+' · 新增 '+(r.last_result.new||0)
+        +(r.last_result.claimed?' · 自动认领 '+r.last_result.claimed:'');
       if(r.last_error)txt+=' · ⚠ '+esc(r.last_error);
       status.textContent=txt;
     }else{status.textContent='尚未扫描';}
     // 待连接表格：只显示在线设备（离线候选不可确认连接，隐藏；恢复在线后自动出现）
     const rows=(r.pending||[]).filter(x=>x.online);
+    _discoveryRows=rows;   // 供确认时判断"是不是已有设备换了地址"
     const tb=document.getElementById('tb-discovery');
     if(!tb)return;
     if(!rows.length){
-      tb.innerHTML='<tr><td colspan="6" class="empty">待连接池为空（扫描到的设备会出现在这里）</td></tr>';
+      tb.innerHTML='<tr><td colspan="7" class="empty">待连接池为空（扫描到的设备会出现在这里）</td></tr>';
     }else{
       tb.innerHTML=rows.map(x=>{
         const src=x.source==='tailscale'
@@ -75,9 +79,17 @@ function loadDiscovery(){
         const onl=x.online
           ?'<span class="label label-success">在线</span>'
           :'<span class="label label-warning">离线</span>';
+        // 指纹命中池中已有设备 → 提示"这台是 X 换了地址"，确认即认领（不需要起新名）
+        const m=x.match;
+        const ident=m
+          ?'<span class="label label-info" title="指纹一致：同一台设备换了地址；确认后会迁移原记录并同步分组/任务">≈ '
+            +esc(m.name||m.serial)+'（原 '+esc(m.serial)+'）</span>'
+          :'<span class="text-muted">新设备</span>';
+        const btnTxt=m?'认领为『'+esc(m.name||'原设备')+'』':'确认添加';
         return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'
+          +'<td>'+ident+'</td>'
           +'<td>'+src+'</td><td>'+esc(x.first_seen)+'</td><td>'+esc(x.last_seen)+'</td><td>'+onl+'</td>'
-          +'<td><button class="btn btn-primary btn-xs" data-serial="'+esc(x.serial)+'" onclick="confirmDiscoveryDev(this.dataset.serial)">确认添加</button> '
+          +'<td><button class="btn btn-primary btn-xs" data-serial="'+esc(x.serial)+'" onclick="confirmDiscoveryDev(this.dataset.serial)">'+btnTxt+'</button> '
           +'<button class="btn btn-xs" data-serial="'+esc(x.serial)+'" onclick="ignoreDiscoveryDev(this.dataset.serial)">忽略</button></td></tr>';
       }).join('');
     }
@@ -90,9 +102,15 @@ function loadDiscovery(){
       }else{
         offTb.innerHTML=off.map(x=>{
           return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'
-            +'<td>'+esc(x.model||'-')+'</td><td>'+esc(x.name||'')+'</td>'
+            +'<td>'+(x.name ? esc(x.name) :
+                     '<span class="label label-warning">未命名</span>')+'</td>'
+            +'<td>'+esc(x.model||'-')+'</td>'
             +'<td><span class="label label-danger">断联·自动重连中</span></td>'
-            +'<td><button class="btn btn-xs" data-serial="'+esc(x.serial)+'" onclick="reconnectPoolDev(this.dataset.serial)">立即重连</button></td></tr>';
+            +'<td style="white-space:nowrap">'
+            +'<button class="btn btn-xs" data-serial="'+esc(x.serial)+'" onclick="reconnectPoolDev(this.dataset.serial)">立即重连</button> '
+            // 设备换了 IP 时旧地址永远连不上——给一条"换地址"的出路（迁移记录 + 同步引用）
+            +'<button class="btn btn-xs" data-serial="'+esc(x.serial)+'" title="设备换了 IP、这个旧地址已经连不上时：把记录迁到新地址（名称与分组/任务引用自动保留）" onclick="relocatePoolDev(this.dataset.serial)">换地址</button>'
+            +'</td></tr>';
         }).join('');
       }
     }
@@ -106,6 +124,17 @@ function reconnectPoolDev(serial){
     }else showToast('重连失败: '+((r&&r.error)||''),'error');
   });
 }
+// 指纹匹配自动认领开关（默认关：认领会改写分组/任务引用，交人工确认更稳妥）
+function toggleAutoClaim(checked){
+  const tip=checked
+    ? '已开启自动认领：扫描到"同一台设备换了 IP"时会自动迁移记录并同步分组/任务引用'
+    : '已关闭自动认领：扫描到换 IP 的设备会提示，由你点确认';
+  apiPost('/api/devices/discovery/settings',{auto_claim:checked}).then(r=>{
+    if(r&&r.ok)showToast(tip,'success');
+    else{showToast('设置失败: '+((r&&r.error)||''),'error');loadDiscovery();}
+  });
+}
+
 function toggleDiscovery(checked){
   apiPost('/api/devices/discovery/settings',{enabled:checked}).then(r=>{
     if(r&&r.ok)showToast('定时扫描已'+(checked?'开启':'关闭'),'success');
@@ -128,11 +157,23 @@ function runDiscoveryScan(){
   });
 }
 function confirmDiscoveryDev(serial){
-  const name=prompt('备注名（可选，留空直接添加）','');
+  const row=(_discoveryRows||[]).find(x=>x.serial===serial)||{};
-  if(name===null)return;
+  const m=row.match;
+  let name='';
+  if(m){
+    // 指纹命中：这是池中某台设备换了地址 → 认领（保留原名与引用），无需再起名
+    if(!confirm('这台就是『'+(m.name||m.serial)+'』（原地址 '+m.serial+'）。\n\n'
+               +'确认认领到 '+serial+' 吗？\n'
+               +'名称、型号、备注都会保留，分组与任务里的旧地址会自动同步到新地址。'))return;
+  }else{
+    const input=prompt('给这台设备起个名称（必填，平台内唯一）：','');
+    if(input===null)return;
+    name=(input||'').trim();
+    if(!name){showToast('必须填写设备名称','error');return;}
+  }
   apiPost('/api/devices/discovery/confirm',{serial,name}).then(r=>{
     if(r&&r.ok){
-      showToast('已加入设备池'+(r.is_new?'':'（已存在，已更新）'),'success');
+      showToast(r.msg||'已加入设备池','success');
       loadDevPool();loadDiscovery();
     }else showToast('确认失败: '+((r&&r.error)||''),'error');
   });
@@ -211,12 +252,14 @@ async function queryAppVers(){
   }
 }
 function renderAppVerRow(x){
-  if(x.error)return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+  // 设备列显示「名称 · 地址」（名称来自设备池；没名字就只显示地址）
+  const dev='<td style="font-family:monospace">'+esc(devText(x.name,x.serial))+'</td>';
+  if(x.error)return '<tr>'+dev+
     '<td><span class="label label-warning">查询失败</span></td><td colspan="2">'+esc(x.error)+'</td></tr>';
-  if(x.installed)return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+  if(x.installed)return '<tr>'+dev+
     '<td><span class="label label-success">已安装</span></td>'+
     '<td>'+esc(x.version_name||'')+'</td><td style="font-family:monospace">'+esc(x.version_code||'')+'</td></tr>';
-  return '<tr><td style="font-family:monospace">'+esc(x.serial)+'</td>'+
+  return '<tr>'+dev+
     '<td><span class="label label-default">未安装</span></td><td>-</td><td>-</td></tr>';
 }
 
@@ -411,19 +454,22 @@ function copyTsKey(){
 
 
 // ================== Tab: 工具 - 设备池管理（本地 SQLite 清单） ==================
+let _devPoolRows=[];     // 设备池最近一次结果（改名时取当前名称）
+let _discoveryRows=[];   // 待连接池最近一次结果（确认时判断是否为已有设备换了地址）
 async function loadDevPool(){
   const tb=document.getElementById('tb-devpool');
   const status=document.getElementById('devpool-status');
   if(!tb)return;
-  tb.innerHTML='<tr><td colspan="7" class="empty">加载中...</td></tr>';
+  tb.innerHTML='<tr><td colspan="8" class="empty">加载中...</td></tr>';
   const r=await apiGet('/api/devices/pool');
-  if(!r||!r.ok){tb.innerHTML='<tr><td colspan="7" class="empty">加载失败</td></tr>';return;}
+  if(!r||!r.ok){tb.innerHTML='<tr><td colspan="8" 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);
+  _devPoolRows=rows;
   const onlineCnt=rows.filter(x=>x.online).length;
   status.textContent=onlyOnline
     ? '在线 '+rows.length+' 台（共 '+(r.devices||[]).length+' 台配置）'
@@ -435,24 +481,37 @@ async function loadDevPool(){
     const online= d.online
       ? '<span class="label label-success">在线</span>'
       : '<span class="label label-warning">离线</span>';
+    // 名称是设备身份：老数据可能有空的 → 标出来提示补
+    const nameCell = d.name
+      ? esc(d.name)
+      : '<span class="label label-warning" title="设备名称必填且唯一（分组/任务/日志按名称认设备）；点右侧「改名」补上">未命名</span>';
+    const fp = d.fingerprint
+      ? '<span title="设备指纹 '+esc(d.fingerprint)+'（ro.serialno）：换 IP 后靠它自动认领">🔑</span>'
+      : '<span class="text-muted" title="尚未采集到指纹：设备离线时采不到；采集到之后换 IP 才能自动认领">—</span>';
     return '<tr>'+
       '<td style="font-family:monospace">'+esc(d.serial)+'</td>'+
-      '<td>'+esc(d.name||'')+'</td>'+
+      '<td>'+nameCell+'</td>'+
-      '<td>'+esc(d.model||'<span style="color:var(--text-light)">-</span>')+'</td>'+
+      '<td>'+esc(d.model||'-')+'</td>'+
       '<td>'+online+'</td>'+
       '<td>'+st+'</td>'+
+      '<td style="text-align:center">'+fp+'</td>'+
       '<td style="color:var(--text-light)">'+esc(d.created_at||'')+'</td>'+
       '<td style="white-space:nowrap">'+
+        '<button class="btn btn-xs" onclick="renamePoolDev(\''+esc(d.serial)+'\')">改名</button> '+
+        '<button class="btn btn-xs" title="生成配置二维码：设备端 Agent 扫一下即配好（平台地址/令牌/指纹）" onclick="showDevQrcode(\''+esc(d.serial)+'\')">二维码</button> '+
+        (d.online ? '' :
+          '<button class="btn btn-xs" title="设备换了 IP、旧地址连不上时：把这条记录迁到新地址（名称与分组/任务引用自动保留）" onclick="relocatePoolDev(\''+esc(d.serial)+'\')">换地址</button> ') +
         '<button class="btn btn-xs" onclick="togglePoolDev(\''+esc(d.serial)+'\','+(!d.enabled)+')">'+(d.enabled?'停用':'启用')+'</button> '+
         '<button class="btn btn-xs btn-danger" onclick="removePoolDev(\''+esc(d.serial)+'\')">删除</button>'+
       '</td></tr>';
-  }).join('')||'<tr><td colspan="7" class="empty">设备池为空，添加第一台设备开始</td></tr>';
+  }).join('')||'<tr><td colspan="8" class="empty">设备池为空，添加第一台设备开始</td></tr>';
 }
 
 async function addPoolDev(){
   const serial=document.getElementById('devpool-serial').value.trim();
   const name=document.getElementById('devpool-name').value.trim();
   if(!serial){showToast('请输入 serial','error');return;}
+  if(!name){showToast('请填写设备名称（平台内唯一，用于分组/任务/日志认设备）','error');return;}
   const r=await apiPost('/api/devices/pool/add',{serial,name});
   if(!r)return;
   if(r.ok){
@@ -463,6 +522,28 @@ async function addPoolDev(){
   }else showToast(r.error,'error');
 }
 
+async function renamePoolDev(serial){
+  const cur=(((_devPoolRows||[]).find(x=>x.serial===serial))||{}).name||'';
+  const nw=(prompt('设备名称（必填，平台内唯一）：', cur)||'').trim();
+  if(!nw || nw===cur)return;
+  const r=await apiPost('/api/devices/pool/rename',{serial,name:nw});
+  if(!r)return;
+  if(r.ok){showToast(r.msg,'success');loadDevPool();}
+  else showToast(r.error,'error');
+}
+
+// 换地址（人工认领）：设备换了 IP、旧地址已连不上时用；名称与分组/任务引用都保留
+async function relocatePoolDev(serial){
+  if(!serial){showToast('没取到设备地址，请刷新页面后重试','error');return;}
+  const nw=(prompt('把记录 ' + serial + ' 迁到新地址（设备换 IP、旧地址连不上时用）：\n\n'
+                  +'名称、型号、备注都会保留，分组与任务里的旧地址会自动同步。','')||'').trim();
+  if(!nw || nw===serial)return;
+  const r=await apiPost('/api/devices/pool/relocate',{old_serial:serial,new_serial:nw});
+  if(!r)return;
+  if(r.ok){showToast(r.msg,'success');loadDevPool();loadDiscovery();}
+  else showToast(r.error,'error');
+}
+
 async function removePoolDev(serial){
   if(!confirm('从设备池删除 '+serial+'？\n\n删除后不再参与任务调度（不影响设备本身与其他功能）。'))return;
   const r=await apiPost('/api/devices/pool/remove',{serial});
@@ -492,3 +573,37 @@ async function refreshPoolModels(){
   if(r.ok){showToast(r.msg,'success');setTimeout(loadDevPool,12000);}
   else showToast(r.error,'error');
 }
+
+// ================== 设备配置二维码（设备端 Agent 扫码即配好） ==================
+// 二维码内容：平台地址 + 设备令牌 + 这台设备的指纹（JSON）。
+// 手机上的 Agent 扫一下 → 保存这三项 → 不用在手机上打字、也不用连 adb。
+async function showDevQrcode(serial){
+  document.getElementById('modal-title').textContent='设备配置二维码';
+  document.getElementById('modal-body').innerHTML='<p class="text-muted">生成中...</p>';
+  document.getElementById('modal-footer').innerHTML=
+    '<button class="btn" onclick="closeModal()">关闭</button>';
+  showModal();
+  const r=await apiGet('/api/devices/qrcode?serial='+encodeURIComponent(serial));
+  const box=document.getElementById('modal-body');
+  if(!r||!r.ok){
+    box.innerHTML='<div style="background:#fdecea;border:1px solid #f5c6cb;color:#b42318;'+
+      'padding:10px 12px;border-radius:6px">'+esc((r&&r.error)||'生成失败')+'</div>';
+    return;
+  }
+  const warn=r.warn?'<div style="background:#fff3cd;border:1px solid #ffda6a;color:#7a5b00;'+
+      'padding:8px 12px;border-radius:6px;margin-bottom:10px;font-size:13px">⚠️ '+esc(r.warn)+'</div>':'';
+  box.innerHTML=
+    warn+
+    '<div style="text-align:center;padding:8px 0">'+
+      '<img src="'+r.png+'" style="width:240px;height:240px;image-rendering:pixelated;'+
+        'background:#fff;padding:8px;border:1px solid #e5e7eb;border-radius:8px" alt="配置二维码">'+
+      '<div style="margin-top:10px;font-size:15px"><strong>'+esc(r.name||'(未命名)')+
+        '</strong> <span style="font-family:monospace;color:#6b7280">'+esc(r.serial)+'</span></div>'+
+    '</div>'+
+    '<div class="help" style="margin-top:6px">在设备上打开 <strong>设备 Agent</strong> → 点「扫码配置」→ 扫这个二维码，'+
+      '平台地址、令牌、指纹一次写入，不用在手机上打字。</div>'+
+    '<details style="margin-top:8px"><summary style="cursor:pointer;color:#6b7280;font-size:12px">'+
+      '查看二维码内容（排查用）</summary>'+
+      '<div style="font-family:monospace;font-size:11px;color:#64748b;word-break:break-all;'+
+        'background:#f8fafc;padding:8px;border-radius:6px;margin-top:6px">'+esc(r.payload)+'</div></details>';
+}

tasks/__init__.py

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

tasks/base.py

@@ -12,7 +12,7 @@
         base.py       — 本任务的操作基类 + 注册器
         xxx.py        — 具体操作
 
-新增任务步骤（照着 tasks/douyin/ 抄即可）：
+新增任务步骤（照着 tasks/generic/ 抄即可）：
 
   1. 在 tasks/ 下新建 my_task/ 子包（文件夹 + __init__.py）
   2. 在 my_task/task.py 顶部写默认参数：

tasks/douyin/__init__.py

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

tasks/douyin/actions/__init__.py

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

tasks/douyin/actions/base.py

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

tasks/douyin/actions/like.py

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

tasks/douyin/task.py

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

tasks/generic/__init__.py

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

tasks/generic/task.py

@@ -104,21 +104,8 @@ STEP_TYPES = [
 
 DEFAULT_PARAMS = {
     "max_duration": 0,          # 最大运行时长（秒），0=不限时
-    "steps": [                  # 默认示例：打开抖音→循环(看视频→滑动)
+    # 注意：**没有默认 steps**。步骤由前端步骤编辑器编排产出，新建任务时从零开始拖；
-        {
+    # 缺 steps 的任务执行时会明确报错（见 run_task），不会静默空跑。
-            "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}},
-            ]},
-        },
-    ],
 }
 
 
@@ -157,6 +144,10 @@ class GenericStepsWorker(BaseWorker):
 
     def run_task(self, d):
         """按 steps 顺序执行。loop 步骤递归执行其 children。"""
+        if not self.steps:
+            # 任务没配步骤（DEFAULT_PARAMS 不含默认步骤，步骤只能由编辑器产出）：
+            # 明确报错而不是"跑完 0 步"当成功——设备表/任务页会显示该错误
+            raise ValueError("通用步骤任务没有可执行步骤：请在「任务」页编辑该任务并添加步骤")
         self._start_timer()
         self.set_action("开始执行步骤链")
         self.set_progress(done=0, total=0, unit="操作",
@@ -167,7 +158,7 @@ class GenericStepsWorker(BaseWorker):
         finally:
             elapsed = self.elapsed()
             summary = f"完成步骤链，运行 {elapsed//60}m{elapsed%60}s"
-            _update_status(self.serial, douyin_running=False, current_action=summary)
+            _update_status(self.serial, current_action=summary)
 
     def _exec_steps(self, d, steps, depth=0):
         """执行步骤列表。depth 防止无限嵌套。"""

templates/admin/login.html

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

templates/admin/monitor.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>设备自动化后台</title>
+<title>{% if db_env and not db_env.is_prod %}{{ db_env.env }}-{% endif %}设备自动化后台</title>
 <style>
 /* ========== 仪表控制台主题（Instrument Console） ==========
    自托管字体：Bricolage Grotesque（展示/数字）+ IBM Plex Mono（数据/串号）
@@ -46,6 +46,8 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .brand-dot{width:9px;height:9px;border-radius:50%;background:var(--primary);box-shadow:0 0 0 0 rgba(15,118,110,.6);animation:brandPulse 2.4s infinite}
 @keyframes brandPulse{0%{box-shadow:0 0 0 0 rgba(15,118,110,.45)}70%{box-shadow:0 0 0 8px rgba(15,118,110,0)}100%{box-shadow:0 0 0 0 rgba(15,118,110,0)}}
 .navbar .tabs{display:flex;gap:2px;flex:1;align-self:stretch}
+.env-badge{margin-right:18px;padding:3px 10px;border-radius:10px;font-size:11px;font-weight:700;letter-spacing:.5px;background:#2b3038;color:#9aa3af;border:1px solid #3a4048;white-space:nowrap}
+.env-badge-prod{background:#4a1519;color:#ff9b9b;border-color:#8a2b31}
 .navbar .tab{position:relative;padding:0 18px;color:#9aa3af;font-size:14px;font-weight:500;cursor:pointer;border:none;background:none;transition:color .15s;letter-spacing:.2px}
 .navbar .tab::after{content:"";position:absolute;left:14px;right:14px;bottom:0;height:2px;border-radius:2px;background:var(--primary);transform:scaleX(0);transition:transform .18s}
 .navbar .tab:hover{color:#e5e7eb}
@@ -169,6 +171,14 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .job-card .job-body{font-size:12px;color:var(--text-muted);margin-bottom:11px;line-height:1.65}
 .job-card .job-body .kv{display:inline-block;background:#faf9f5;border:1px solid var(--border);border-radius:6px;padding:1px 7px;margin:2px 3px 0 0;font-family:var(--mono);font-size:11px}
 .job-card .job-actions{display:flex;gap:6px;flex-wrap:wrap}
+/* 任务覆盖的设备（监控页任务概况） */
+.job-cov{margin-top:6px}
+.cov-chips{display:flex;flex-wrap:wrap;gap:4px;margin-top:4px}
+.cov-chip{font-family:var(--mono);font-size:11px;padding:1px 7px;border-radius:9px;border:1px solid;white-space:nowrap;cursor:default}
+.cov-chip.online{color:#0e7490;background:#e0f2fe;border-color:#bae6fd}
+.cov-chip.running{color:#b45309;background:#fef3c7;border-color:#fde68a}
+.cov-chip.offline{color:#9ca3af;background:#f3f4f6;border-color:#e5e7eb;text-decoration:line-through}
+.cov-note{font-size:11px;color:#94a3b8;margin-left:4px}
 
 /* 空状态 / 辅助文本 */
 .empty{text-align:center;padding:42px;color:var(--text-light);font-size:13px}
@@ -338,6 +348,32 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .agent-msg.user{align-self:flex-end;background:#0e7490;color:#fff;border-bottom-right-radius:3px}
 .agent-msg.assistant{align-self:flex-start;background:#fff;border:1px solid #e5e7eb;border-bottom-left-radius:3px;color:#1f2937;box-shadow:0 1px 2px rgba(0,0,0,.04)}
 .agent-msg.assistant .reasoning{color:#6b7280;font-size:12.5px;border-left:3px solid #d1d5db;padding-left:10px;margin:8px 0}
+/* 推理链（可折叠） */
+.agent-msg.assistant details.reasoning{margin:6px 0 10px;background:#f9fafb;border:1px solid #eef0f3;border-radius:9px;padding:6px 10px}
+.agent-msg.assistant details.reasoning>summary{cursor:pointer;font-size:12px;color:#6b7280;font-weight:600;user-select:none;outline:none}
+.agent-msg.assistant details.reasoning>summary:hover{color:#0e7490}
+.agent-msg.assistant .reasoning-text{margin-top:6px;color:#6b7280;font-size:12.5px;line-height:1.7;white-space:pre-wrap;word-break:break-word;max-height:320px;overflow-y:auto}
+/* token 用量脚注 */
+.agent-usage{margin-top:8px;padding-top:7px;border-top:1px dashed #e5e7eb;font-size:11px;color:#9ca3af;font-family:var(--mono)}
+.agent-token-total{margin-left:8px;font-size:11px;color:#6b7280;font-family:var(--mono);background:#f3f4f6;padding:2px 8px;border-radius:10px}
+/* 正文 Markdown（.agent-msg 默认 pre-wrap，正文改由标签排版） */
+.agent-msg.assistant .agent-text{white-space:normal}
+.agent-text p{margin:0 0 8px}
+.agent-text p:last-child{margin-bottom:0}
+.agent-text .md-h{margin:12px 0 6px;font-weight:700;line-height:1.4}
+.agent-text h1.md-h{font-size:17px}.agent-text h2.md-h{font-size:16px}.agent-text h3.md-h{font-size:15px}
+.agent-text h4.md-h,.agent-text h5.md-h,.agent-text h6.md-h{font-size:13.5px}
+.agent-text .md-list{margin:0 0 8px;padding-left:22px}
+.agent-text .md-list li{margin:2px 0}
+.agent-text .md-code{background:#0f172a;color:#e2e8f0;border-radius:8px;padding:9px 12px;overflow-x:auto;font-size:12px;font-family:var(--mono);margin:8px 0;white-space:pre}
+.agent-text code{background:#f1f5f9;border:1px solid #e2e8f0;border-radius:4px;padding:0 4px;font-size:12px;font-family:var(--mono);color:#0f766e}
+.agent-text .md-code code{background:none;border:none;color:inherit;padding:0}
+.agent-text .md-quote{margin:8px 0;padding:2px 0 2px 11px;border-left:3px solid #d1d5db;color:#4b5563}
+.agent-text .md-table{border-collapse:collapse;margin:8px 0;font-size:12.5px;display:block;overflow-x:auto;max-width:100%}
+.agent-text .md-table th,.agent-text .md-table td{border:1px solid #e5e7eb;padding:5px 10px;text-align:left;white-space:nowrap}
+.agent-text .md-table th{background:#f3f4f6;font-weight:600}
+.agent-text hr{border:none;border-top:1px solid #e5e7eb;margin:12px 0}
+.agent-text a{color:#0e7490;text-decoration:underline;word-break:break-all}
 .agent-toolcards{display:flex;flex-direction:column;gap:5px;margin-bottom:9px}
 .agent-toolcard{display:flex;align-items:flex-start;gap:8px;background:#f3f4f6;border:1px solid #e5e7eb;border-radius:9px;padding:6px 11px;font-size:12px;font-family:var(--mono);color:#374151;flex-wrap:wrap}
 .agent-toolcard .dot{width:7px;height:7px;border-radius:50%;background:#10b981;flex:none;margin-top:5px}
@@ -358,6 +394,12 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 <!-- 顶部导航 -->
 <nav class="navbar">
   <div class="brand"><span class="brand-dot"></span>设备自动化后台</div>
+  {% if db_env %}
+  <span class="env-badge{% if db_env.is_prod %} env-badge-prod{% endif %}"
+        title="数据库目标：{{ db_env.target }}（{{ db_env.backend }}）">
+    {% if db_env.is_prod %}PROD · {{ db_env.target }}{% else %}{{ db_env.env|upper }}{% endif %}
+  </span>
+  {% endif %}
   <div class="tabs">
     <button class="tab active" data-tab="monitor" onclick="showTab('monitor')">监控</button>
     <button class="tab" data-tab="tasks" onclick="showTab('tasks')">任务</button>
@@ -476,7 +518,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 <div id="tab-agent" class="tab-panel">
   <div class="agent-shell">
     <div class="agent-topbar">
-      <div class="agent-title">🤖 AI 控制台<span id="agent-model-tag" class="agent-model-tag"></span></div>
+      <div class="agent-title">🤖 AI 控制台<span id="agent-model-tag" class="agent-model-tag"></span><span id="agent-token-total" class="agent-token-total" title=""></span></div>
       <div class="agent-top-actions">
         <span id="agent-running-tag" class="agent-running-tag" style="display:none">● 运行中</span>
         <button class="btn btn-xs" onclick="openExpLib()" title="查看/管理自进化经验库（每日 AI 巡检建议，删除需确认）">🧠 经验库</button>
@@ -746,6 +788,34 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
       <tbody id="tb-apks"></tbody>
     </table>
     <div class="list-pager" id="pager-apks"></div>
+
+    <!-- 设备端应用商店：设备上的 Agent 自己拉清单/下载/安装（绕开 MIUI 的 USB 安装拦截） -->
+    <div class="section-title" style="margin-top:16px">📱 设备端应用商店（Agent 直连安装）</div>
+    <div class="help">
+      设备上装的 <b>Agent</b> 自己来拉这份应用清单 → 在手机上选一个 → 自己下载 → 自己调系统安装器安装。
+      因为安装由设备上的 App 发起，走的是<b>普通应用安装流程</b>，
+      <b>不会触发 MIUI 针对 adb 安装的「USB 安装」拦截</b>（那正是 <code>adb install</code> 报 USER_RESTRICTED 的原因）。
+      适合"人就在机器旁边"的场景（本来就要点一次安装确认）。平台批量推送仍用上面的「安装」按钮。
+      <br><span class="text-muted">接口契约见 <code>doc/DEVICE_AGENT.md</code>；令牌属于凭据，别外传。</span>
+    </div>
+    <div class="toolbar" style="gap:10px;flex-wrap:wrap">
+      <label style="display:inline-flex;align-items:center;gap:4px;margin:0">
+        <input type="checkbox" id="store-enabled" onchange="toggleAgentStore(this.checked)"> 启用设备端商店
+      </label>
+      <input class="form-control" id="store-url" readonly style="width:290px;font-family:monospace" title="Agent 里要填的平台地址">
+      <input class="form-control" id="store-token" readonly style="width:300px;font-family:monospace" title="Agent 里要填的设备令牌">
+      <button class="btn" onclick="copyStoreToken()">复制令牌</button>
+      <button class="btn" onclick="regenStoreToken()">重置令牌</button>
+      <button class="btn" onclick="loadAgentStore()">刷新记录</button>
+      <span class="text-muted" id="store-status"></span>
+    </div>
+    <table class="table">
+      <thead><tr>
+        <th style="width:150px">时间</th><th style="width:90px">设备</th>
+        <th style="width:200px">应用</th><th style="width:110px">动作</th><th>说明</th>
+      </tr></thead>
+      <tbody id="tb-store-logs"><tr><td colspan="5" class="empty">暂无记录（设备还没从商店装过东西）</td></tr></tbody>
+    </table>
   </div>
 
   <!-- 子分栏 5：应用版本管理 -->
@@ -806,22 +876,28 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
         <span class="text-muted">秒 · 网段</span>
         <input type="text" id="discovery-subnets" class="form-control" style="width:300px;font-family:monospace"
                placeholder="192.168.20.0/24, 100.100.10.0/24" title="逗号分隔的 CIDR 网段">
+        <label style="display:inline-flex;align-items:center;gap:4px;margin-left:10px"
+               title="开启后：扫描发现某台设备的指纹与设备池中已有记录一致（= 同一台设备换了 IP）时，自动把它认领到新地址——迁移原记录并同步分组/任务里的引用，不再需要人工确认。默认关：认领会改写分组与任务的引用，交人工点一下更稳妥。">
+          <input type="checkbox" id="discovery-autoclaim" onchange="toggleAutoClaim(this.checked)"> 指纹匹配自动认领
+        </label>
         <button class="btn" onclick="saveDiscoverySettings()">保存设置</button>
         <button class="btn btn-primary" onclick="runDiscoveryScan()">立即扫描</button>
         <span id="discovery-status" class="text-muted"></span>
       </div>
       <table class="table table-hover table-sm" style="margin-top:8px">
-        <thead><tr><th>serial</th><th>来源</th><th>首次发现</th><th>最近发现</th><th>在线</th><th>操作</th></tr></thead>
+        <thead><tr><th>serial</th><th>识别</th><th>来源</th><th>首次发现</th><th>最近发现</th><th>在线</th><th>操作</th></tr></thead>
-        <tbody id="tb-discovery"><tr><td colspan="6" class="empty">尚未扫描</td></tr></tbody>
+        <tbody id="tb-discovery"><tr><td colspan="7" class="empty">尚未扫描</td></tr></tbody>
       </table>
       <div class="help">扫描局域网/Tailscale 网段中开放 adb 5555 的设备进入<b>待连接池</b>；
-        <b>确认后才加入正式设备池</b>（不自动连接、不参与任务调度）。未授权设备（手机未接受 RSA 弹窗）不会出现。</div>
+        <b>确认后才加入正式设备池</b>（不自动连接、不参与任务调度）。未授权设备（手机未接受 RSA 弹窗）不会出现。<br>
+        <b>「识别」列</b>：平台按<b>设备指纹</b>认出这台其实就是池中某台设备换了 IP —— 确认后自动<b>认领</b>：
+        迁移原记录（名称/型号/备注全保留），并把分组与任务里的旧地址一并换成新地址。新设备则必须填名称。</div>
       <!-- 正式池断联设备：仍在设备池（不删除、不进待连接池），自动重连中 -->
       <div style="margin-top:10px">
         <div style="font-size:12.5px;font-weight:600;margin-bottom:6px">设备池断联设备
           <span class="text-muted" style="font-weight:400">（仍在设备池内，扫描线程每轮自动重连；也可手动立即重连）</span></div>
         <table class="table table-hover table-sm">
-          <thead><tr><th>serial</th><th>型号</th><th>备注</th><th>状态</th><th>操作</th></tr></thead>
+          <thead><tr><th>serial</th><th>名称</th><th>型号</th><th>状态</th><th>操作</th></tr></thead>
           <tbody id="tb-pool-offline"><tr><td colspan="5" class="empty">全部在线</td></tr></tbody>
         </table>
       </div>
@@ -829,8 +905,9 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
     <div class="toolbar">
       <input type="text" id="devpool-serial" class="form-control" style="width:220px;font-family:monospace"
              placeholder="serial，如 100.100.10.20:5555" onkeydown="if(event.key==='Enter')addPoolDev()">
-      <input type="text" id="devpool-name" class="form-control" style="width:150px"
+      <input type="text" id="devpool-name" class="form-control" style="width:170px"
-             placeholder="备注名（可选）" onkeydown="if(event.key==='Enter')addPoolDev()">
+             placeholder="设备名称（必填·唯一）" title="设备在平台里的标识；分组、任务目标、日志都用它认设备"
+             onkeydown="if(event.key==='Enter')addPoolDev()">
       <button class="btn btn-primary" onclick="addPoolDev()">添加设备</button>
       <button class="btn" onclick="reconnectPoolDevices()" title="并发 adb connect 池内全部设备">一键重连</button>
       <button class="btn" onclick="refreshPoolModels()" title="采集池内在线设备的型号（getprop）">采集型号</button>
@@ -842,14 +919,18 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
     </div>
     <table class="table table-hover table-sm" style="margin-top:8px">
       <thead><tr>
-        <th>serial</th><th>名称</th><th>型号</th><th>在线</th><th>状态</th><th>添加时间</th><th>操作</th>
+        <th>serial</th><th>名称</th><th>型号</th><th>在线</th><th>状态</th>
+        <th title="设备指纹（ro.serialno）：采集到之后，设备换 IP 才能被自动认领">指纹</th>
+        <th>添加时间</th><th>操作</th>
       </tr></thead>
       <tbody id="tb-devpool"></tbody>
     </table>
     <div class="help">
       新增设备流程：手机开 USB 调试 → 连上后「adb 终端」执行 <code>tcpip 5555</code> 转网络调试 →
       Tailscale 上线（同一账号）→ 在此添加 <code>IP:5555</code>（自动尝试连接）→
-      任务运行时 u2 自动推送 atx-agent。<b>停用 = 不参与任务调度</b>，删除 = 从池中移除（不影响其他系统）。
+      任务运行时 u2 自动推送 atx-agent。<b>停用 = 不参与任务调度</b>，删除 = 从池中移除（不影响其他系统）。<br>
+      <b>设备名称必填且唯一</b>：它是设备在平台里的身份（分组/任务/日志都按名称认设备）；
+      设备换了 IP 时用「换地址」把记录迁过去，分组与任务的引用会自动同步，不用重新配。
     </div>
   </div>
 
@@ -885,9 +966,11 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
   <!-- 子分栏 1：数据备份 -->
   <div class="sub-panel active" id="system-sub-backup">
     <div class="help">
-      <b>导出</b>当前系统数据为 zip：含 <code>users.db</code>（用户 / 任务计划 / 设备分组 / 自定义动作 /
+      <b>导出</b>当前系统数据为 zip：把数据库（MySQL 或回退模式的 SQLite）整库一致快照成
-      设备池 / AI 会话 / 经验库等全部表，SQLite 在线一致快照）+ 可选的 <code>apks/</code> 应用文件。
+      <code>users.db</code> 归档（<b>全部业务表</b>：用户 / 任务计划 / 设备分组 /
-      恢复用：换机 / 整库迁移 / 出问题前留底。
+      自定义动作 / APK 记录 / 设备池 / 待连接设备 / AI 会话 / 经验库 / 经验巡检 / <b>动作库</b> / 系统配置）+ 可选的
+      <code>apks/</code> 应用文件。恢复用：换机 / 整库迁移 / 出问题前留底。
+      <br><span class="text-muted">清单见预览的「表数据行数」（由模型元数据自动派生，新增表不会漏）；备份里记录了来源环境，跨环境导入默认拒绝。</span>
     </div>
     <div class="toolbar" style="gap:8px">
       <label style="display:inline-flex;align-items:center;gap:4px;margin:0 6px">
@@ -905,7 +988,9 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
   <div class="sub-panel" id="system-sub-restore">
     <div class="help">
       <b>导入恢复</b>：上传平台导出的 <code>.zip</code> 或 <code>.db</code> → 先<b>校验预览</b> →
-      确认后系统会<b>自动备份当前库</b>并把恢复任务挂起，<b>重启 web_server 后生效</b>（导入将覆盖现有全部数据）。
+      确认后系统会<b>自动备份当前库</b>（<code>data/backups/pre_restore_*.zip</code>，可直接再导入回来）并把恢复任务挂起，
+      <b>重启 web_server 后生效</b>（导入将覆盖现有全部数据；数据替换在单个事务里完成，失败会自动回滚）。
+      <br><span class="text-muted">备份来自另一个环境（dev↔prod）时默认拒绝导入，需在预览页显式勾选「允许跨环境导入」。</span>
     </div>
     <div class="toolbar" style="gap:8px">
       <input type="file" id="restore-file" accept=".zip,.db">
@@ -972,6 +1057,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 
 <!-- 前端模块（按依赖顺序加载：base → list → 页面模块 → admin(含初始化)） -->
 <script src="/static/admin/base.js"></script>
+<script src="/static/admin/markdown.js"></script>
 <script src="/static/admin/list.js"></script>
 <script src="/static/admin/monitor.js"></script>
 <script src="/static/admin/editor.js"></script>

templates/admin/wall.html

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

web/__init__.py

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

web/agent_api.py

@@ -5,7 +5,9 @@
   GET  /api/agent/stream?run_id=      → SSE 事件流（EventSource 订阅）：
         event: delta  {text, kind: content|reasoning}   流式文本增量
         event: step   {tool, args, image?}               工具调用完成（MCP 步骤）
-        event: done   {answer}                           完成
+        event: usage  {prompt_tokens, completion_tokens,
+                       total_tokens, calls}              本轮累计 token 用量
+        event: done   {answer, usage}                    完成
         event: error  {message}                          失败
   GET/POST /api/agent/config          → 配置读写（key 打码回显）
 
@@ -38,9 +40,13 @@ _CFG_KEYS = {"api_base": "agent_api_base",
              "default_serial": "agent_default_serial",
              "max_steps": "agent_max_steps"}
 
+# 推理链落库上限（字符）：只留够回看的量，避免会话消息无限膨胀
+_REASONING_KEEP = 6000
+
+
 # ---------- 运行状态（单实例 + 事件队列） ----------
 _run = {"id": None, "state": "idle", "prompt": "", "serial": "",
-        "answer": "", "error": "",
+        "answer": "", "error": "", "usage": {},
         "history": []}   # 多轮对话历史 [{role: user|assistant, content}]
 _queues = {}            # run_id -> queue.Queue（SSE 消费者读取）
 _stop_events = {}       # run_id -> threading.Event（用户中断）
@@ -54,14 +60,14 @@ def set_app(app):
 
 
 def _meta_get(key):
-    return db.session.execute(
+    # 走方言中立助手（app_meta 的列名 key 在 MySQL 里是保留字，裸 SQL 会语法错）
-        db.text("SELECT value FROM app_meta WHERE key=:k"), {"k": key}).scalar() or ""
+    from core.db_config import meta_get
+    return meta_get(key) or ""
 
 
 def _meta_put(key, value):
-    db.session.execute(
+    from core.db_config import meta_set
-        db.text("INSERT OR REPLACE INTO app_meta(key,value) VALUES(:k,:v)"),
+    meta_set(key, str(value))
-        {"k": key, "v": str(value)})
 
 
 def _read_cfg():
@@ -69,29 +75,10 @@ def _read_cfg():
 
 
 # ================== 经验记忆（自进化） ==================
-# agent_experience：任务成功后的操作配方，下次相似任务检索注入 system prompt。
+# agent_experience / experience_audit / agent_action / agent_conversation 四张表
-# 原始 SQLite（CREATE IF NOT EXISTS 幂等），不进模型层迁移。
+# 已在 core/models.py 里定义为 ORM 模型（唯一真相），建表统一由 db.create_all() 完成。
-_EXP_TABLE = """
+# 以前这里是各写一段 SQLite 的 CREATE TABLE + try/except: pass —— 换 MySQL 后
-CREATE TABLE IF NOT EXISTS agent_experience (
+# AUTOINCREMENT / TEXT DEFAULT 全都建不出来，而异常被吞掉，表现为"功能静默失灵"。""
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  task_prompt TEXT DEFAULT '',
-  recipe TEXT DEFAULT '',
-  tool_seq TEXT DEFAULT '',
-  hits INTEGER DEFAULT 0,
-  created_at VARCHAR(20) DEFAULT '')"""
-
-# 经验巡检（AI 质检）：每日定时把经验交给模型评审，疑似问题标 pending 待人工确认。
-# 删除只允许人工（前端 confirm / 本 API），巡检绝不自动删。
-_AUDIT_TABLE = """
-CREATE TABLE IF NOT EXISTS experience_audit (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  exp_id INTEGER NOT NULL,
-  verdict TEXT DEFAULT '',       -- keep 保留 / delete 建议删除
-  score REAL DEFAULT 0,          -- 0-10 可用性评分
-  reason TEXT DEFAULT '',        -- 模型给出的理由
-  hits INTEGER DEFAULT 0,        -- 巡检时的引用次数（hits>0 被删要更谨慎）
-  action TEXT DEFAULT 'pending', -- pending 待人工确认 / kept 已保留 / deleted 已删除
-  audited_at VARCHAR(20) DEFAULT '')"""
 
 # 巡检评审提示词：模型只判「保留/建议删除」+ 评分 + 理由，不直接删。
 _AUDIT_PROMPT = """你是「手机自动化经验库」质检员。经验库存放 AI 成功操作手机后提炼的
@@ -113,12 +100,20 @@ _AUDIT_PROMPT = """你是「手机自动化经验库」质检员。经验库存
 只输出 JSON：{{"keep": true或false, "score": 0到10的整数, "reason": "一句话中文理由"}}"""
 
 
-def _ensure_exp_table():
+def _ensure_tables():
+    """确保 agent 系四张表存在（幂等）。create_all 只建缺失的表，开销可以忽略。
+
+    失败必须落日志：以前是 except: pass，MySQL 下建表失败会被完全吞掉，
+    表不存在 → 后续查询全报错，而日志里什么都看不到。
+    """
     try:
-        db.session.execute(db.text(_EXP_TABLE))
+        db.create_all()
-        db.session.commit()
+    except Exception as e:
-    except Exception:
+        _log.error(f"agent 表创建失败: {e}")
-        pass
+
+
+def _ensure_exp_table():
+    _ensure_tables()
 
 
 def _bigrams(text):
@@ -360,19 +355,7 @@ def _save_experience(prompt, recipe, tool_seq):
 # steps 直接用编辑器 schema（open_app/click/input_text…），带**元素定位**
 # （selector_type/selector_value），**不含坐标**（分辨率/旋转/改版即失效）。
 # 复用：执行前按 name/别名/App 召回并注入 system prompt，模型可跳过重新探索。
-_ACTION_TABLE = (
+# 建表见 core/models.py 的 AgentAction
-    "CREATE TABLE IF NOT EXISTS agent_action ("
-    "id INTEGER PRIMARY KEY AUTOINCREMENT,"
-    "name TEXT NOT NULL,"
-    "app TEXT DEFAULT '',"
-    "aliases TEXT DEFAULT '[]',"
-    "params TEXT DEFAULT '[]',"
-    "steps TEXT NOT NULL,"
-    "preconditions TEXT DEFAULT '',"
-    "hits INTEGER DEFAULT 0,"
-    "source_prompt TEXT DEFAULT '',"
-    "created_at TEXT DEFAULT '',"
-    "updated_at TEXT DEFAULT '')")
 
 # 允许沉淀的步骤类型（编辑器 STEP_TYPES 子集；显式排除 click_xy 等坐标类）
 _ACTION_STEP_TYPES = {
@@ -392,11 +375,7 @@ _ACTION_TOOLS = {
 
 
 def _ensure_action_table():
-    try:
+    _ensure_tables()
-        db.session.execute(db.text(_ACTION_TABLE))
-        db.session.commit()
-    except Exception:
-        pass
 
 
 def _brief_result(result):
@@ -725,11 +704,7 @@ _audit_state = {"running": False, "last": "", "last_summary": ""}
 
 
 def _ensure_audit_table():
-    try:
+    _ensure_tables()
-        db.session.execute(db.text(_AUDIT_TABLE))
-        db.session.commit()
-    except Exception:
-        pass
 
 
 def _review_one_exp(cfg, prompt, recipe, tool_seq, hits):
@@ -996,22 +971,11 @@ def agent_actions_save():
 
 # ================== 历史会话（DeepSeek 式：多会话持久化） ==================
 # 会话 = 消息序列（JSON），一轮 run 的 user/assistant 文本完成后追加落库。
-# 单表 JSON 存储（每会话几十 KB 内，无需独立消息表）。
+# 单表 JSON 存储（每会话几十 KB 内，无需独立消息表）。建表见 core/models.py。
-_CONV_TABLE = """
-CREATE TABLE IF NOT EXISTS agent_conversation (
-  id VARCHAR(20) PRIMARY KEY,
-  title VARCHAR(100) DEFAULT '',
-  messages TEXT DEFAULT '[]',
-  created_at VARCHAR(20) DEFAULT '',
-  updated_at VARCHAR(20) DEFAULT '')"""
 
 
 def _ensure_conv_table():
-    try:
+    _ensure_tables()
-        db.session.execute(db.text(_CONV_TABLE))
-        db.session.commit()
-    except Exception:
-        pass
 
 
 def _conv_msgs(conv_id):
@@ -1175,13 +1139,15 @@ def agent_run():
             try:
                 from datetime import datetime as _dt2
                 now = _dt2.now().strftime("%Y-%m-%d %H:%M")
+                # 上面刚确认过会话不存在，普通 INSERT 即可；
+                # 并发下撞主键就回滚忽略（原来用 SQLite 专有的 INSERT OR IGNORE）
                 db.session.execute(db.text(
-                    "INSERT OR IGNORE INTO agent_conversation(id, messages, "
+                    "INSERT INTO agent_conversation(id, messages, "
                     "created_at, updated_at) VALUES(:i, '[]', :c, :c)"),
                     {"i": conv_id, "c": now})
                 db.session.commit()
             except Exception:
-                pass
+                db.session.rollback()
     with _lock:
         if _run["state"] == "running":
             return jsonify({"ok": False, "error":
@@ -1192,7 +1158,7 @@ def agent_run():
         _run.update(id=run_id, state="running", prompt=prompt,
                     serial=serial, conv_id=conv_id,
                     started=_dt.now().strftime("%H:%M:%S"),
-                    answer="", error="")
+                    answer="", error="", usage={})
         # history 保留（多轮上下文），由会话/「新建会话」管理
         _queues[run_id] = queue.Queue()
         _stop_events[run_id] = threading.Event()
@@ -1244,6 +1210,7 @@ def agent_run_status():
                         "started": _run.get("started", ""),
                         "answer": (_run.get("answer") or "")[:4000],
                         "error": (_run.get("error") or "")[:400],
+                        "usage": _run.get("usage") or {},
                         "history": hist[-16:]})
 
 
@@ -1263,6 +1230,7 @@ def agent_devices():
     for d in (devs or []):
         busy = d.get("worker_status") in ("running", "connecting")
         out.append({"serial": d.get("serial"),
+                    "name": d.get("device_name") or "",   # 设备名称（设备池里的身份标识）
                     "model": d.get("model") or "",
                     "online": bool(d.get("present")),
                     "busy": busy,
@@ -1345,9 +1313,22 @@ def _agent_thread(run_id, prompt, serial, cfg):
         sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
         from mcp_agent.agent import Agent
 
+        # 推理链（reasoning_content）累计——单纯流式展示会随页面刷新丢失，
+        # 落库后可在会话里折叠回看（只存文本，不回灌给模型）
+        reason_parts = []
+        reason_len = 0
+
         def on_delta(text, kind):
+            nonlocal reason_len
+            if kind == "reasoning" and reason_len < _REASONING_KEEP:
+                reason_parts.append(text)
+                reason_len += len(text)
             q.put(("delta", {"text": text, "kind": kind}))
 
+        def on_usage(usage):
+            """每次模型调用完成 → 推累计用量（前端实时刷新 token 计数）。"""
+            q.put(("usage", dict(usage)))
+
         tool_seq = []    # 本轮工具序列（任务级配方提炼用）
         tool_trace = []  # 结构化轨迹：{tool, args, result}（动作经验提炼用，判成败）
 
@@ -1451,7 +1432,8 @@ def _agent_thread(run_id, prompt, serial, cfg):
                                               on_delta=on_delta, on_tool=on_tool,
                                               should_stop=lambda: bool(
                                                   stop_evt and stop_evt.is_set()),
-                                              extra_context=recall_ctx)
+                                              extra_context=recall_ctx,
+                                              on_usage=on_usage)
             except Exception as e:
                 if _mcp_unreachable(e):
                     raise RuntimeError(
@@ -1460,13 +1442,22 @@ def _agent_thread(run_id, prompt, serial, cfg):
 
         # 整体超时保护：卡死时结束，释放单实例
         answer = asyncio.run(asyncio.wait_for(_execute(), timeout=900))
+        usage = dict(getattr(agent, "usage", None) or {})
         with _lock:
             _run["state"] = "done"
             _run["answer"] = answer
-            # 追加本轮进历史（多轮连续性；上限 12 轮防 token 膨胀）
+            _run["usage"] = usage
+            # 追加本轮进历史（多轮连续性；上限 12 轮防 token 膨胀）。
+            # usage/reasoning 仅用于前端展示与落库，不进模型上下文（读回时只取 role/content）
             hist = _run.setdefault("history", [])
             hist.append({"role": "user", "content": prompt[:2000]})
-            hist.append({"role": "assistant", "content": (answer or "")[:4000]})
+            turn = {"role": "assistant", "content": (answer or "")[:4000]}
+            if usage:
+                turn["usage"] = usage
+            reason = "".join(reason_parts).strip()
+            if reason:
+                turn["reasoning"] = reason[:_REASONING_KEEP]
+            hist.append(turn)
             _run["history"] = hist[-24:]
         # 会话落库：本轮追加写回（新会话自动用首条消息作标题）。
         # 后台线程 db 访问需 app context。
@@ -1513,7 +1504,7 @@ def _agent_thread(run_id, prompt, serial, cfg):
                                     "image": None}))
             except Exception as e:
                 _log.warning(f"经验保存异常: {e}")
-        q.put(("done", {"answer": answer}))
+        q.put(("done", {"answer": answer, "usage": usage}))
     except Exception as e:
         _log.warning(f"Agent 运行异常: {e}")
         # 诊断：打印消息结构（tool_calls 与 tool 消息配对检查）
@@ -1529,6 +1520,11 @@ def _agent_thread(run_id, prompt, serial, cfg):
         with _lock:
             _run["state"] = "error"
             _run["error"] = f"{type(e).__name__}: {str(e)[:200]}"
+            # 失败也保留已花费的 token（前端仍能展示本轮用量；agent 可能未建出来）
+            try:
+                _run["usage"] = dict(agent.usage or {})
+            except Exception:
+                pass
         q.put(("error", {"message": str(e)[:200]}))
     finally:
         q.put(None)   # 关闭 SSE

web/apks_api.py

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

web/common.py

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

web/device_agent_api.py

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

web/devices_api.py

@@ -5,13 +5,107 @@ 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.adb_helper import adb_connect, adb_connect_light
 from core.logger import get_logger
 from web.auth import perm_required, PERM_DEVICES
 
 _log = get_logger("web")
 bp = Blueprint("devices", __name__)
 
+
+def _lan_ip():
+    """挑一个手机连得上的本机地址：优先 192.168.x，其次 10.x。
+
+    不能用 gethostbyname(hostname) —— 这台机器上它可能返回 Tailscale 的
+    100.x（CGNAT 地址，手机不在 tailnet 里根本连不上），或 docker 的 172.17。
+    """
+    import socket
+    candidates = []
+    try:
+        for info in socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET):
+            ip = info[4][0]
+            if ip.startswith("127.") or ip.startswith("169.254."):
+                continue
+            candidates.append(ip)
+    except Exception:
+        pass
+    for ip in candidates:
+        if ip.startswith("192.168."):
+            return ip
+    for ip in candidates:
+        if ip.startswith("10."):
+            return ip
+    return candidates[0] if candidates else "本机IP"
+
+
+@bp.route("/api/devices/qrcode")
+@perm_required(PERM_DEVICES)
+def api_devices_qrcode():
+    """给某台设备生成「配置二维码」——设备端 Agent 扫一下就把自己配好。
+
+    二维码里是一段 JSON（平台地址 + 设备令牌 + 这台设备的指纹），扫码即完成：
+    填 server/token/指纹 三件事，不用在手机上打字，也不用连 adb。
+
+    ⚠️ 两条使用前提（都会在返回里给提示，不静默失败）：
+      1. 平台要先在「应用管理 → 设备端应用商店」启用（令牌是从那儿来的）
+      2. **要用局域网地址打开本页面**（二维码里的地址取自当前访问地址；
+         如果你是用 localhost 打开的，手机会连不上，这里会明确告诉你）
+    """
+    import base64
+    import io
+    import json as _json
+
+    serial = (request.args.get("serial") or "").strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+
+    dev = None
+    for d in device_pool.list_devices():
+        if d.get("serial") == serial:
+            dev = d
+            break
+    if dev is None:
+        return jsonify({"ok": False, "error": "设备不在池里"}), 404
+
+    # 令牌必须先启用设备端商店才有
+    from core.db_config import meta_get
+    from web.device_agent_api import store_enabled, ensure_token
+    if not store_enabled():
+        return jsonify({"ok": False,
+                        "error": "还没启用设备端商店：先到「应用管理 → 设备端应用商店」勾选启用"}), 400
+    token = ensure_token()
+
+    server = request.host_url.rstrip("/")
+    warn = ""
+    if "127.0.0.1" in server or "localhost" in server:
+        warn = ("你现在是用本机地址打开平台的，二维码里的地址手机会连不上 —— "
+                "请改用局域网地址（如 http://%s:18050）重新打开本页再生成。"
+                % _lan_ip())
+
+    fp = dev.get("fingerprint") or ""
+    if not fp:
+        warn = (warn + " " if warn else "") + \
+            "这台设备还没采集到指纹，扫码后平台认不出它是哪一台（设备端会显示「未登记」）；" \
+            "建议先让它在线并刷新一次型号/指纹，再生成二维码。"
+
+    payload = {"v": 1, "server": server, "token": token,
+               "fingerprint": fp, "name": dev.get("name") or ""}
+    text = _json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+    try:
+        import qrcode
+        img = qrcode.make(text)
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        png = "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
+    except Exception as e:
+        _log.error(f"生成二维码失败: {e}")
+        return jsonify({"ok": False, "error": f"生成二维码失败: {e}"}), 500
+
+    _log.info(f"生成设备配置二维码: {dev.get('name') or serial}")
+    return jsonify({"ok": True, "serial": serial, "name": dev.get("name") or "",
+                    "fingerprint": fp, "png": png, "payload": text, "warn": warn})
+
 @bp.route("/api/devices/pool", methods=["GET"])
 @perm_required(PERM_DEVICES)
 def api_devices_pool_list():
@@ -28,29 +122,97 @@ def api_devices_pool_list():
 @bp.route("/api/devices/pool/add", methods=["POST"])
 @perm_required(PERM_DEVICES)
 def api_devices_pool_add():
-    """添加/更新设备：{serial, name?, note?}。
+    """添加/更新设备：{serial, name, note?}。
 
-    IP:5555 设备添加后立即尝试 adb connect（不可达显示离线，不影响其他设备）。
+    **名称必填且唯一**（设备在平台里的身份标识，分组/任务/日志都靠它认设备）。
+    IP:5555 设备添加后立即尝试 adb connect 并读取**设备指纹**：若指纹命中池中已有
+    设备（同一台设备换了 IP），自动**认领**——迁移旧记录（保留原名）并同步
+    分组与任务里的引用，而不是新增一条。
     """
     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()
-                                    name=(data.get("name") or "").strip(),
+    note = (data.get("note") or "").strip()
-                                    note=(data.get("note") or "").strip())
+    if not name:
-    msg = "已添加" if is_new else "已更新"
+        return jsonify({"ok": False, "error":
+                        "请填写设备名称——名称是设备在平台里的唯一标识"
+                        "（分组、任务目标、日志都用它认设备）"}), 400
+    # 重名先查（放在 adb 之前：连不上的 IP 不该让用户白等）
+    if device_pool.name_taken(name, exclude_serial=serial):
+        return jsonify({"ok": False, "error": f"名称『{name}』已被其它设备占用，请换一个"}), 400
+    # 轻量 connect（单次、短超时，不用 5 次重试的 adb_connect，避免不可达设备把接口卡住）
     if ":" in serial:
         try:
-            adb_connect(serial)
+            adb_connect_light(serial)
         except Exception:
             pass
-    # 后台采集型号（不阻塞添加响应）
+    fp = device_pool.read_fingerprint(serial) if ":" in serial else ""
-    import threading
+    claimed_old, claimed_name = device_pool.claim_device(serial, fp) if fp else (None, "")
-    threading.Thread(target=device_pool.refresh_model, args=(serial,),
+    # 认领时保留设备**原有名称**（身份优先于本次输入），没有原名才用输入值
-                     daemon=True).start()
+    use_name = (claimed_name or name).strip()
-    _log.info(f"设备池管理: {msg} {serial}")
+    if use_name != name and device_pool.name_taken(use_name, exclude_serial=serial):
-    return jsonify({"ok": True, "msg": msg, "is_new": is_new})
+        return jsonify({"ok": False, "error": f"名称『{use_name}』已被其它设备占用，请换一个"}), 400
+    is_new = device_pool.add_device(serial, name=use_name, note=note, fingerprint=fp)
+    # 后台采集型号 + 指纹（不阻塞添加响应）
+    threading.Thread(target=device_pool.refresh_info, args=(serial,), daemon=True).start()
+    if claimed_old:
+        msg = (f"已认领：这是『{use_name}』（原地址 {claimed_old}），"
+               f"分组与任务的引用已自动同步")
+    else:
+        msg = "已添加" if is_new else "已更新"
+    _log.info(f"设备池管理: {msg} {serial} name={use_name}")
+    return jsonify({"ok": True, "msg": msg, "is_new": is_new,
+                    "claimed": bool(claimed_old), "old_serial": claimed_old or ""})
+
+
+@bp.route("/api/devices/pool/rename", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_pool_rename():
+    """重命名设备：{serial, name}。名称必填且唯一。"""
+    data = request.json or {}
+    serial = (data.get("serial") or "").strip()
+    name = (data.get("name") or "").strip()
+    if not serial or not name:
+        return jsonify({"ok": False, "error": "缺少 serial 或 name"}), 400
+    if device_pool.name_taken(name, exclude_serial=serial):
+        return jsonify({"ok": False, "error": f"名称『{name}』已被其它设备占用，请换一个"}), 400
+    if not device_pool.rename_device(serial, name):
+        return jsonify({"ok": False, "error": "设备不存在"}), 404
+    return jsonify({"ok": True, "msg": f"已重命名为『{name}』"})
+
+@bp.route("/api/devices/pool/relocate", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_pool_relocate():
+    """人工认领（换地址兜底）：{old_serial, new_serial}。
+
+    用于设备换了 IP 但**旧地址已断联、指纹也没采过**、自动认领无从匹配时：
+    由人工指认"这条记录就是那台设备，现在在新地址"，迁移并同步分组/任务引用。
+    """
+    data = request.json or {}
+    old_serial = (data.get("old_serial") or "").strip()
+    new_serial = (data.get("new_serial") or "").strip()
+    if not old_serial or not new_serial:
+        return jsonify({"ok": False, "error": "缺少 old_serial 或 new_serial"}), 400
+    if ":" in new_serial:
+        try:
+            adb_connect_light(new_serial)
+        except Exception:
+            pass
+    fp = device_pool.read_fingerprint(new_serial) if ":" in new_serial else ""
+    ok, name, msg = device_pool.relocate_device(old_serial, new_serial, fingerprint=fp)
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 400
+    # 新地址若在待连接池里，一并清掉（已经是池内设备了）
+    try:
+        device_discovery.ignore_pending(new_serial)
+    except Exception:
+        pass
+    threading.Thread(target=device_pool.refresh_info, args=(new_serial,), daemon=True).start()
+    _log.info(f"设备池管理: 人工认领 {old_serial} → {new_serial}（{name}）")
+    return jsonify({"ok": True, "msg": msg, "name": name})
+
 
 @bp.route("/api/devices/pool/remove", methods=["POST"])
 @perm_required(PERM_DEVICES)
@@ -147,13 +309,30 @@ def api_devices_discovery_scan():
 @bp.route("/api/devices/discovery/confirm", methods=["POST"])
 @perm_required(PERM_DEVICES)
 def api_devices_discovery_confirm():
-    """确认连接：待连接 → 正式设备池 + 后台 adb connect + 采型号。"""
+    """确认连接：待连接 → 正式设备池 + 后台 adb connect + 采型号。
+
+    名称规则：**新设备必须填名称**；若指纹命中池中已有设备（同一台换了 IP），
+    则不需要名称——保留原记录与原名，并把分组/任务引用同步到新地址。
+    """
     data = request.json or {}
     serial = (data.get("serial") or "").strip()
+    name = (data.get("name") or "").strip()
     if not serial:
         return jsonify({"ok": False, "error": "缺少 serial"}), 400
-    ok, msg, is_new = device_discovery.confirm_pending(
+    if ":" in serial:
-        serial, name=(data.get("name") or "").strip())
+        try:
+            adb_connect_light(serial)
+        except Exception:
+            pass
+    fp = device_pool.read_fingerprint(serial) if ":" in serial else ""
+    matched = device_pool.find_by_fingerprint(fp) if fp else None
+    in_pool = serial in device_pool.list_configured()
+    if not in_pool and not matched and not name:
+        return jsonify({"ok": False, "error":
+                        "请为该设备填写名称（名称是设备在平台里的唯一标识）"}), 400
+    if name and device_pool.name_taken(name, exclude_serial=serial if in_pool else ""):
+        return jsonify({"ok": False, "error": f"名称『{name}』已被其它设备占用，请换一个"}), 400
+    ok, msg, is_new = device_discovery.confirm_pending(serial, name=name, fingerprint=fp)
     if not ok:
         return jsonify({"ok": False, "error": msg}), 404
     if ":" in serial:
@@ -163,7 +342,7 @@ def api_devices_discovery_confirm():
             except Exception:
                 pass
             try:
-                device_pool.refresh_model(serial)
+                device_pool.refresh_info(serial)
             except Exception:
                 pass
         threading.Thread(target=_connect, daemon=True).start()
@@ -225,7 +404,8 @@ def api_devices_discovery_settings():
         enabled=data.get("enabled"),
         subnets=data.get("subnets"),
         interval=data.get("interval"),
-        port=data.get("port"))
+        port=data.get("port"),
+        auto_claim=data.get("auto_claim"))
     if not ok:
         return jsonify({"ok": False, "error": msg}), 400
     return jsonify({"ok": True, "msg": msg})

web/monitor.py

@@ -102,6 +102,11 @@ def api_status():
     devices, err = context.mgr.get_status()
     if err:
         return jsonify({"ok": False, "error": err}), 500
+    # 按**名称**排（A01/A02/…）——之前是 adb 返回的顺序，看着像按 IP 排，很别扭。
+    # 没名字的排在最后、彼此按地址排（历史数据里可能有没命名的设备）。
+    devices.sort(key=lambda d: (
+        1 if not (d.get("device_name") or "").strip() else 0,
+        (d.get("device_name") or "").strip() or d.get("serial", "")))
     return jsonify({
         "ok": True, "devices": devices, "server_time": time.time(),
         "fg_scanning": context.mgr._fg_scanner.is_scanning,

web/system_api.py

@@ -66,10 +66,16 @@ def api_system_backup_preview():
 @bp.route("/api/system/backup/apply", methods=["POST"])
 @admin_required
 def api_system_backup_apply():
-    """确认应用导入：自动备份当前库 → 落待生效恢复任务（重启后生效）。"""
+    """确认应用导入：自动备份当前库 → 落待生效恢复任务（重启后生效）。
-    token = (request.json or {}).get("token", "")
+
+    force_env_mismatch 默认 False：备份来源环境与当前库环境不符时拒绝导入，
+    要跨环境（如把生产数据导进 dev 库）必须显式传 true。
+    """
+    body = request.json or {}
+    token = body.get("token", "")
+    force = bool(body.get("force_env_mismatch", False))
     try:
-        res = sb.apply_restore(str(token).strip())
+        res = sb.apply_restore(str(token).strip(), force_env_mismatch=force)
     except sb.BackupError as e:
         return jsonify({"ok": False, "error": str(e)}), 400
     except Exception as e:

web/tasks_api.py

@@ -41,9 +41,24 @@ def api_actions():
 @bp.route("/api/devices")
 @login_required
 def api_devices():
-    """返回所有在线设备 serial（供分组表单勾选用）。"""
+    """在线设备列表（供分组表单/任务目标/AI 的「选择设备」下拉用）。
+
+    - `devices`：serial 字符串列表（兼容既有调用方）
+    - `items`：`[{serial, name, model}]` —— 界面显示**设备名称**用
+      （名称是设备的身份，见 doc/API.md §6）
+    """
     try:
-        return jsonify({"ok": True, "devices": context.mgr.list_all_serials()})
+        serials = context.mgr.list_all_serials()
+        info = {}
+        try:
+            for d in device_pool.list_devices():
+                info[d["serial"]] = d
+        except Exception:
+            pass
+        items = [{"serial": s,
+                  "name": (info.get(s) or {}).get("name") or "",
+                  "model": (info.get(s) or {}).get("model") or ""} for s in serials]
+        return jsonify({"ok": True, "devices": serials, "items": items})
     except Exception as e:
         return jsonify({"ok": False, "error": str(e)}), 500
 
@@ -54,13 +69,47 @@ def _job_next_run(job):
     nr = context.mgr.next_run_of(job)
     return nr.strftime("%Y-%m-%d %H:%M") if nr else None
 
+def _job_coverage(job, configured):
+    """任务覆盖的设备（监控页「任务运行概况」展示用）。
+
+    与 TaskJob.resolve_serials 的差别：这里按 **target 定义**给出「这台任务会覆盖
+    哪些设备」，不因设备当前是否空闲而变（在线/运行中由前端拿实时状态标注），
+    也不做离线过滤、不写调度日志——它是每 5s 轮询的展示接口。
+    """
+    tgt = job.target or {}
+    mode = tgt.get("mode", "all")
+    try:
+        if mode == "serial":
+            serials = [tgt.get("serial") or ""]
+        elif mode == "group":
+            g = context.mgr.groups.get(tgt.get("group_name"))
+            serials = [s for s in (list(g.serials) if g else []) if s in configured]
+        else:
+            serials = sorted(configured)
+        serials = [s for s in serials if s]
+        return {"mode": mode, "serials": serials, "total": len(serials)}
+    except Exception as e:
+        _log.warning(f"任务「{job.name}」覆盖设备解析失败: {e}")
+        return {"mode": mode, "serials": [], "total": 0, "error": str(e)[:80]}
+
+
+def _configured_set():
+    """设备池清单（coverage 计算用，取一次给所有任务复用）。"""
+    try:
+        return set(device_pool.list_configured())
+    except Exception:
+        return set()
+
+
 @bp.route("/api/jobs")
 @login_required
 def api_jobs_list():
+    configured = _configured_set()
     jobs = []
     for j in context.mgr.jobs.values():
         d = j.to_dict()
         d["next_run"] = _job_next_run(j)
+        d["coverage"] = _job_coverage(j, configured)
         jobs.append(d)
     return jsonify({"ok": True, "jobs": jobs,
                     "task_types": list_task_types()})
@@ -72,7 +121,7 @@ def api_jobs_create():
     name = (data.get("name") or "").strip()
     if not name:
         return jsonify({"ok": False, "error": "任务名不能为空"}), 400
-    task_type = data.get("task_type", "douyin_nurture")
+    task_type = data.get("task_type", "generic_steps")
     if not get_task_class(task_type):
         return jsonify({"ok": False, "error": f"未知任务类型: {task_type}"}), 400
     job = context.mgr.add_job(
@@ -84,6 +133,7 @@ def api_jobs_create():
         enabled=data.get("enabled", True))
     d = job.to_dict()
     d["next_run"] = _job_next_run(job)
+    d["coverage"] = _job_coverage(job, _configured_set())
     return jsonify({"ok": True, "msg": "任务已创建", "job": d})
 
 @bp.route("/api/jobs/<job_id>", methods=["PUT"])
@@ -102,6 +152,7 @@ def api_jobs_update(job_id):
     context.mgr.update_job(job_id, **fields)
     d = job.to_dict()
     d["next_run"] = _job_next_run(job)
+    d["coverage"] = _job_coverage(job, _configured_set())
     return jsonify({"ok": True, "msg": "任务已更新", "job": d})
 
 @bp.route("/api/jobs/<job_id>", methods=["DELETE"])

web/tools_api.py

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

web_server.py

@@ -33,24 +33,52 @@ if not os.environ.get("WEB_SECRET_KEY"):
 app.config["SECRET_KEY"] = _web_secret
 # debug=False 时模板默认不自动重载，开发期改 HTML 需重启才生效；这里显式开启
 app.config["TEMPLATES_AUTO_RELOAD"] = True
-app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///" + os.path.join(
+# 数据库目标与连接参数统一由 core/db_config 装配（.env 的 DEPLOY_ENV / DB_* 决定）。
-    os.path.dirname(os.path.abspath(__file__)), "data", "users.db")
+# 这里就把配置校验做完：连不上、环境与库名不匹配 → 直接拒绝启动，不要带着错配置跑起来。
+from core import db_config
+try:
+    _DB_URI = db_config.build_db_uri()
+    db_config.check_connection(_DB_URI)
+except db_config.DBConfigError as _e:
+    _log.error("数据库配置校验失败，拒绝启动：\n%s", _e)
+    raise SystemExit(2)
+app.config["SQLALCHEMY_DATABASE_URI"] = _DB_URI
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(_DB_URI)
 app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
 
 login_manager = LoginManager(app)
 login_manager.login_view = "auth.login"  # 蓝图化后路由前缀 auth
 
-# 消费「待生效的备份恢复」：若存在 data/restore_pending/users.db，在 engine 首次
+
-# 打开数据库之前换位。导入必须重启生效——TaskManager 启动时读库入内存，
+def _consume_pending_restore():
-# Windows 无法热替换正被持有的库文件。
+    """消费「待生效的备份恢复」（若存在 data/restore_pending/users.db）。
-try:
+
+    必须在 init_db 之后调用：现在是「单事务整库替换」而不是换文件，
+    要先有建好的表和 app context。导入仍然要重启才生效——因为 TaskManager /
+    device_pool 把任务与设备缓存在内存里，整库替换后内存副本全部失效。
+    """
+    try:
         from core.system_backup import consume_pending_restore
+        with app.app_context():
             consume_pending_restore()
-except Exception as _e:
+    except Exception as _e:
         _log.error(f"消费备份恢复任务异常（不影响启动）: {_e}")
 
 # 先初始化数据库（含旧 JSON 迁移），再创建 TaskManager（需要 app context 读写 DB）
 init_db(app)
+# 消费「待生效的备份恢复」——必须在 init_db 之后（表已建好，且现在是事务替换而非换文件）
+_consume_pending_restore()
+# 库环境标签校验 + 启动横幅：每次启动都明确写出「现在连的是哪个库」，
+# 避免在不知情的情况下对着生产库操作（app_meta 表要存在，所以放在 init_db 之后）
+try:
+    with app.app_context():          # db.engine / app_meta 读取都需要 app context
+        db_config.verify_deployment_label()
+        db_config.print_banner()
+        # 页面顶部环境徽标（防混库第 4 层：点开任何页面都能看出连的是哪个库）
+        app.jinja_env.globals["db_env"] = db_config.env_badge()
+except db_config.DBConfigError as _e:
+    _log.error("数据库环境校验失败，拒绝启动：\n%s", _e)
+    raise SystemExit(2)
 # 设备池（本地清单 + adb 在线状态）：任务调度的数据源
 from core import device_pool
 device_pool.init_app(app)
@@ -58,6 +86,9 @@ device_pool.init_app(app)
 from core import device_discovery
 device_discovery.init_app(app)
 mgr = TaskManager(app=app)
+# 设备换地址（认领/迁址）后同步分组与任务的引用：它们的"内存副本"在 TaskManager 里
+# （调度用内存对象），device_pool 只改库不改内存不生效，所以在此注册回调打通
+device_pool.set_move_hook(mgr.sync_device_serial)
 apk_mgr = ApkManager(app=app)
 
 # Web 层按模块拆分（web/ 蓝图包）：认证/监控/任务/管理/工具/设备池/APK/Tailscale