chore: 去掉 generic_steps 的默认步骤 + 重试失败带上真实原因

- tasks/generic/task.py：DEFAULT_PARAMS 只留 max_duration，**不再内置示例步骤**
  （步骤只能由前端编辑器产出；此前默认的"打开抖音→循环看视频"只有后端在用，
  编辑器新建任务本来就是空的，等于埋了个和界面不一致的隐性默认值）
- 空步骤不再静默空跑：worker 立即抛错「通用步骤任务没有可执行步骤…」，
  设备表「最近错误」能看到（此前会走完 0 步当成功）
- core/task_manager.py：重试耗尽的 last_error 现在带上最后一次的真实失败原因，
  不再只有"重试N次失败"（用户看不到为什么失败）；max_attempts=1 显示"执行失败"
  而非费解的"重试1次失败"；长度截断 200 字符
- 文档：TASK_DEV §2.10 说明无默认步骤 + 空步骤会报错；API.md 的 task_types 示例
  改 default_params={"max_duration":0}，POST /api/jobs 补「steps 要一起传」提示

自测（全通过）：default_params 无 steps；无步骤任务真跑一次 → 设备错误信息完整含原因；
有步骤任务（wait 1s）真跑一次 → status=done 无错误；临时任务验完已删，任务集合复原

.gitignore

@@ -48,3 +48,6 @@ data/*.corrupt_*
 data/users.db*
 data/users.db-wal
 data/users.db-shm
+data/backups/
+data/restore_staging/
+data/restore_pending/

README.md

@@ -2,7 +2,7 @@
 
 基于 **uiautomator2 + Flask + 自建设备池** 的 Android 多设备自动化任务执行平台（已摘除 OpenSTF 依赖）。
 
-提供 Web 管理后台，支持多设备并发任务执行、定时调度、设备分组管理、设备池管理（新增/停用/删除/型号采集）、APK 批量安装、网页远程看屏（MJPEG 实时流 + 触控）、UI 元素抓取等功能。内置抖音养号任务和通用步骤任务，可扩展任意 App 的自动化操作。
+提供 Web 管理后台，支持多设备并发任务执行、定时调度、设备分组管理、设备池管理（新增/停用/删除/型号采集）、APK 批量安装、网页远程看屏（MJPEG 实时流 + 触控）、UI 元素抓取等功能。内置通用步骤任务（可视化步骤编辑器编排，覆盖任意 App 的操作），可扩展专属任务类型。
 
 ---
 
@@ -105,8 +105,7 @@ platform-tools/
 ├── tasks/                       # 任务定义层（每个 App 一个子包）
 │   ├── __init__.py              #   全局任务注册表
 │   ├── base.py                  #   BaseTask 基类 + @register_task 装饰器
-│   ├── douyin/                  #   抖音养号任务
+│   └── generic/                 #   通用步骤任务（可视化编辑器编排，当前唯一任务类型）
-│   └── generic/                 #   通用步骤任务（可视化编辑器编排）
 │       └── task.py              #     步骤执行引擎（open_app/click/swipe/if_el...）
 │
 ├── templates/admin/             # 前端页面
@@ -183,8 +182,7 @@ Worker.run_task（执行业务逻辑）
 
 | 任务类型 | task_type | 说明 |
 |---------|-----------|------|
-| 抖音养号 | `douyin_nurture` | 自动看视频 + 随机点赞，被退出自动重连 |
+| 通用步骤 | `generic_steps` | 可视化步骤编辑器编排流程，支持循环/点击/滑动/条件/OCR 等 |
-| 通用步骤 | `generic_steps` | 可视化步骤编辑器编排流程，支持循环/点击/滑动等 |
 
 ### TaskJob — 任务计划
 
@@ -192,9 +190,9 @@ Worker.run_task（执行业务逻辑）
 
 | 字段 | 说明 | 示例 |
 |------|------|------|
-| `task_type` | 任务类型 | `"douyin_nurture"` |
+| `task_type` | 任务类型 | `"generic_steps"` |
 | `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}}}}` |
+| `params` | 任务参数（与默认值深合并） | `{"max_duration": 0, "steps": [{"type": "open_app", "params": {"package": "com.ss.android.ugc.aweme"}}]}` |
 | `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` |
@@ -306,23 +304,6 @@ self.set_progress(done=5, total=80, unit="视频",
 
 ## 任务系统
 
-### 抖音养号（douyin_nurture）
-
-自动观看抖音视频，按配置随机执行点赞操作。参数（在 `tasks/douyin/task.py` 顶部）：
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `watch_count` | 80 | 观看视频数量（0=不限，靠时长停止） |
-| `watch_min` / `watch_max` | 5.0 / 35.0 | 单视频观看时长范围（秒） |
-| `max_duration` | 0 | 最大运行时长（秒），0=不限时 |
-| `swipe_min` / `swipe_max` | 0.25 / 0.50 | 上滑手势时长范围（秒） |
-| `gap_min` / `gap_max` | 1.0 / 3.0 | 视频间隔时长范围（秒） |
-| `actions.like.enabled` | true | 是否启用点赞 |
-| `actions.like.params.rate` | 0.3 | 点赞概率（0~1） |
-| `actions.like.params.method` | by_element | 点赞方式：by_element(找红心) / double_click(双击) |
-
-终止条件（哪个先到就停）：`watch_count` 数量到 / `max_duration` 时长到 / 手动停止。
-
 ### 通用步骤（generic_steps）
 
 通过可视化步骤编辑器编排任务流程，worker 按步骤顺序执行。支持的步骤类型：
@@ -352,7 +333,8 @@ self.set_progress(done=5, total=80, unit="视频",
 
 ### 新增 App 任务
 
-参照 `tasks/douyin/` 结构，6 步即可新增一个 App 任务，详见 [doc/TASK_DEV.md](doc/TASK_DEV.md)。
+参照 `tasks/generic/` 结构，即可新增一个专属任务类型，详见 [doc/TASK_DEV.md](doc/TASK_DEV.md)。
+（注：当前平台只保留 `generic_steps` 一种类型；绝大多数 App 操作直接用步骤编辑器编排即可，不必新建类型。）
 
 ---
 
@@ -371,7 +353,7 @@ self.set_progress(done=5, total=80, unit="视频",
 
 ```python
 from core.logger import get_logger
-log = get_logger("task.douyin")    # 写入 task.log
+log = get_logger("task.generic")   # 写入 task.log
 log.info(f"[{self.serial}] 开始任务")
 ```
 

config.py

@@ -60,6 +60,13 @@ DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data")
 # APK 文件存储目录（应用管理功能）
 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")
+
 # ================== SSH 到部署机（已废弃，STF 相关操作退役） ==================
 # 阶段 3 后代码不再使用 SSH；保留配置仅供手动运维 220（如 docker stop stf）。
 STF_SSH_TARGET = _env("STF_SSH_TARGET", "")

core/__init__.py

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

core/actions/__init__.py

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

core/actions/base.py

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

core/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

@@ -128,7 +128,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
@@ -384,7 +384,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

@@ -0,0 +1,432 @@
+"""系统数据备份导出/导入（数据库 + APK 文件）。
+
+导出：用 sqlite3 在线备份 API 对 data/users.db 做一致性快照 → zip
+      （users.db + manifest.json + 可选 apks/*.apk）。
+导入：上传(zip/db) → 暂存校验预览 → 应用（先把当前库快照到
+      BACKUP_DIR/pre_restore_*.db，再把暂存库移到 RESTORE_PENDING_DIR）→
+      下次启动 consume_pending_restore() 换位生效。
+
+为什么必须重启生效：web_server 单进程内 SQLAlchemy engine + 多个常驻后台线程
+（TaskManager 内存态 / 设备发现 / Agent 等）持有 users.db（WAL）；Windows 下
+不能直接替换正被打开的文件，且 TaskManager 启动时才把 groups/jobs 读入内存。
+故导入只落一个「待生效恢复任务」，由 web_server.py 在 init_db 之前消费。
+
+安全红线：全程只读现有库 / 新增或移动自己目录下的文件；绝不 kill-server、
+绝不 disconnect（与全项目一致）。
+"""
+import json
+import os
+import shutil
+import sqlite3
+import time
+import uuid
+import zipfile
+from urllib.parse import quote
+
+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
+
+_log = get_logger("core.backup")
+
+# 当前代码期望的 schema 版本（来自版本化迁移表）
+CURRENT_SCHEMA_VERSION = max(v[0] for v in SCHEMA_MIGRATIONS) if SCHEMA_MIGRATIONS else 0
+
+DB_FILE = os.path.join(DATA_DIR, "users.db")
+
+# 判定「本平台备份库」的必需表（缺任何一张即拒绝导入）
+REQUIRED_TABLES = ("app_meta", "user", "task_job", "device_group")
+# 预览/清单里展示行数的业务表（存在才统计）
+# ⚠️ 红线：**新增任何持久化表，必须同步登记到这里**——备份覆盖清单以此为准，
+#    漏登记的表在导出清单/预览里不可见（2026-09-10 动作库 agent_action 即因此
+#    被误判为"没有备份"：数据其实在 users.db 快照里，只是清单没列）。
+SUMMARY_TABLES = (
+    "app_meta", "user", "device_group", "task_job", "custom_action",
+    "apk_file", "device", "pending_device",
+    "agent_conversation", "agent_experience", "experience_audit", "agent_action",
+)
+TABLE_LABELS = {
+    "app_meta": "系统配置(app_meta)",
+    "user": "用户", "device_group": "设备分组", "task_job": "任务计划",
+    "custom_action": "自定义动作", "apk_file": "APK 记录", "device": "设备池",
+    "pending_device": "待连接设备", "agent_conversation": "AI 会话",
+    "agent_experience": "经验库", "experience_audit": "经验巡检",
+    "agent_action": "动作库",
+}
+_STAGE_TTL = 1800  # 导入暂存有效期（秒）
+
+
+class BackupError(Exception):
+    """备份/导入相关可预期错误（msg 直接给前端展示）。"""
+
+
+# ================== 通用工具 ==================
+def _ts():
+    return time.strftime("%Y%m%d_%H%M%S")
+
+
+def _readonly_uri(path):
+    """把文件路径转成 sqlite 只读 URI（兼容含空格/中文/反斜杠的 Windows 路径）。"""
+    return "file:{}?mode=ro".format(quote(os.path.abspath(path).replace("\\", "/"), safe="/:"))
+
+
+def _connect_readonly(path):
+    con = sqlite3.connect(_readonly_uri(path), uri=True)
+    con.text_factory = str  # 与平台一致按 UTF-8 读（表内文本均为 UTF-8）
+    return con
+
+
+def remove_quiet(path):
+    """尽力删除文件/目录（发送完成清理等场景，忽略不存在）。"""
+    try:
+        if os.path.isdir(path):
+            shutil.rmtree(path, ignore_errors=True)
+        elif os.path.exists(path):
+            os.remove(path)
+    except OSError:
+        pass
+
+
+def _ensure_dir(path):
+    os.makedirs(path, exist_ok=True)
+
+
+def _list_tables(con):
+    rows = con.execute(
+        "SELECT name FROM sqlite_master WHERE type='table'").fetchall()
+    return {r[0] for r in rows}
+
+
+def _read_schema_version(con):
+    try:
+        row = con.execute(
+            "SELECT value FROM app_meta WHERE key='schema_version'").fetchone()
+        return int(row[0]) if row and row[0] else 0
+    except Exception:
+        return 0
+
+
+def _table_rows(con, table):
+    try:
+        return con.execute('SELECT COUNT(*) FROM "%s"' % table).fetchone()[0]
+    except Exception:
+        return None
+
+
+# ================== 在线快照 ==================
+def 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 = []
+    for t in SUMMARY_TABLES:
+        n = _table_rows(con, t)
+        if n is not None:
+            rows.append({"table": t, "label": TABLE_LABELS.get(t, t), "rows": n})
+    return rows
+
+
+def _prune_old_exports(max_age=3600):
+    """清理过期的导出临时 zip（下载完成后的 call_on_close 在 Windows 上可能
+    因文件锁删不掉，这里按时间兜底清理；保留近 1 小时的便于失败重试）。"""
+    now = time.time()
+    if not os.path.isdir(BACKUP_DIR):
+        return
+    for n in os.listdir(BACKUP_DIR):
+        if n.startswith("export_") and n.endswith(".zip"):
+            p = os.path.join(BACKUP_DIR, n)
+            try:
+                if now - os.path.getmtime(p) > max_age:
+                    os.remove(p)
+            except OSError:
+                pass
+
+
+def 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)
+
+    apk_meta = []
+    if include_apk and os.path.isdir(APK_DIR):
+        for fname in sorted(os.listdir(APK_DIR)):
+            if fname.lower().endswith(".apk"):
+                fp = os.path.join(APK_DIR, fname)
+                try:
+                    apk_meta.append({"name": fname, "size": os.path.getsize(fp)})
+                except OSError:
+                    pass
+
+    zip_path = base + ".zip"
+    con = _connect_readonly(snap)
+    try:
+        manifest = {
+            "format": "auto_control_backup",
+            "version": 1,
+            "created_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+            "schema_version": _read_schema_version(con),
+            "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()
+
+    try:
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as z:
+            z.write(snap, arcname="users.db")
+            for a in apk_meta:
+                z.write(os.path.join(APK_DIR, a["name"]), arcname="apks/" + a["name"])
+            z.writestr("manifest.json", json.dumps(
+                manifest, ensure_ascii=False, indent=2))
+    finally:
+        remove_quiet(snap)
+    return zip_path, os.path.basename(zip_path), manifest
+
+
+# ================== 校验 ==================
+def validate_backup(db_file):
+    """校验备份库可读、是本平台库。返回 (ok, info|error_msg)。"""
+    if not os.path.exists(db_file):
+        return False, "缺少数据库文件 users.db"
+    try:
+        con = _connect_readonly(db_file)
+    except sqlite3.Error as e:
+        return False, f"无法打开数据库: {e}"
+    try:
+        integrity = con.execute("PRAGMA integrity_check").fetchone()[0]
+        if integrity != "ok":
+            return False, f"数据库完整性校验失败: {integrity}"
+        tables = _list_tables(con)
+        missing = [t for t in REQUIRED_TABLES if t not in tables]
+        if missing:
+            return False, f"不是本平台备份库（缺少必需表: {', '.join(missing)}）"
+        schema_version = _read_schema_version(con)
+        missing_optional = [t for t in SUMMARY_TABLES
+                            if t not in REQUIRED_TABLES and t not in tables]
+        warnings = []
+        if schema_version < CURRENT_SCHEMA_VERSION:
+            warnings.append(
+                f"备份 schema 较旧（v{schema_version} < 当前 v{CURRENT_SCHEMA_VERSION}），"
+                f"应用后首次启动会自动迁移补齐结构与新表")
+        elif schema_version > CURRENT_SCHEMA_VERSION:
+            warnings.append(
+                f"备份 schema 较新（v{schema_version} > 当前 v{CURRENT_SCHEMA_VERSION}），"
+                f"当前平台版本可能读不了新增列/表，建议先升级再恢复")
+        if missing_optional:
+            warnings.append("备份缺少部分可选表（" + "、".join(
+                TABLE_LABELS.get(t, t) for t in missing_optional)
+                + "），应用后启动会自动补建空表")
+        # 反向自检：备份里有"未登记"的表 → 提醒把它纳入覆盖清单（红线）
+        extra_tables = sorted(t for t in tables
+                              if t not in SUMMARY_TABLES and not t.startswith("sqlite_"))
+        if extra_tables:
+            warnings.append("备份含未登记的其它表（" + "、".join(extra_tables)
+                            + "）——如属业务数据，请登记进 core/system_backup.py 的覆盖清单")
+        warnings.append("备份为全量快照：含用户口令哈希、AI 配置里的 API Key 等敏感信息，请妥善保管")
+        return True, {
+            "integrity": integrity,
+            "schema_version": schema_version,
+            "current_schema_version": CURRENT_SCHEMA_VERSION,
+            "tables": _summary_info(con),
+            "missing_optional": missing_optional,
+            "extra_tables": extra_tables,
+            "warnings": warnings,
+        }
+    except sqlite3.Error as e:
+        return False, f"读取数据库失败: {e}"
+    finally:
+        con.close()
+
+
+# ================== 导入：暂存 + 预览 ==================
+def _extract_zip(zip_path, staging_dir):
+    """解压备份 zip：取顶层 users.db 与可选 apks/*.apk（防路径穿越，只用 basename）。"""
+    db_dest = os.path.join(staging_dir, "users.db")
+    apk_dest = os.path.join(staging_dir, "apks")
+    got_db = False
+    with zipfile.ZipFile(zip_path) as z:
+        for info in z.infolist():
+            if info.is_dir():
+                continue
+            name = info.filename.replace("\\", "/")
+            base = os.path.basename(name)
+            if name == "users.db" and base == "users.db":
+                z.extract(info, staging_dir)  # 已确认顶层名字，无穿越
+                got_db = True
+            elif name.startswith("apks/") and base.lower().endswith(".apk"):
+                _ensure_dir(apk_dest)
+                with z.open(info) as src, open(
+                        os.path.join(apk_dest, base), "wb") as dst:
+                    shutil.copyfileobj(src, dst)
+    if not got_db:
+        raise BackupError("zip 内未找到 users.db（顶层）")
+    return db_dest
+
+
+def _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 stage_upload(file_storage):
+    """保存上传备份并校验，返回 (token, info)。失败抛 BackupError。"""
+    _prune_stale_staging()
+    orig_name = file_storage.filename or "backup"
+    token = uuid.uuid4().hex[:12]
+    staging_dir = os.path.join(RESTORE_STAGING_DIR, token)
+    _ensure_dir(staging_dir)
+    low = (orig_name or "").lower()
+    try:
+        raw_path = os.path.join(staging_dir, "upload" + ("." + low.rsplit(".", 1)[1] if "." in low else ""))
+        file_storage.save(raw_path)
+        if low.endswith(".zip"):
+            _extract_zip(raw_path, staging_dir)
+            db_file = os.path.join(staging_dir, "users.db")
+            remove_quiet(raw_path)
+        elif low.endswith(".db"):
+            db_file = os.path.join(staging_dir, "users.db")
+            os.replace(raw_path, db_file)
+        else:
+            raise BackupError("仅支持 .zip（平台导出）或 .db（sqlite 库）文件")
+        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)
+        return token, info
+    except BackupError:
+        remove_quiet(staging_dir)
+        raise
+    except Exception as e:
+        remove_quiet(staging_dir)
+        raise BackupError(f"暂存上传文件失败: {e}")
+
+
+# ================== 导入：应用（落待生效任务） ==================
+def apply_restore(token):
+    """校验 token → 快照当前库 → 把暂存库移到 restore_pending。
+
+    返回 dict {ok, backup_name, message}；失败抛 BackupError。token 形如 12 位 hex。
+    """
+    if not token or len(token) != 12 or not all(c in "0123456789abcdef" for c in token):
+        raise BackupError("无效的导入标识")
+    staging_dir = os.path.join(RESTORE_STAGING_DIR, token)
+    db_file = os.path.join(staging_dir, "users.db")
+    if not os.path.exists(db_file):
+        raise BackupError("导入会话已失效，请重新上传预览")
+    ok, info = validate_backup(db_file)
+    if not ok:
+        raise BackupError(info)
+
+    # 1) 自动备份当前库（安全网，可回滚）
+    _ensure_dir(BACKUP_DIR)
+    backup_name = f"pre_restore_{_ts()}.db"
+    snapshot_db(os.path.join(BACKUP_DIR, backup_name))
+
+    # 2) 落待生效恢复任务（旧未消费任务被覆盖——上一份已无意义）
+    pending_dir = RESTORE_PENDING_DIR
+    if os.path.isdir(pending_dir):
+        remove_quiet(pending_dir)
+    _ensure_dir(pending_dir)
+    os.replace(db_file, os.path.join(pending_dir, "users.db"))
+    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"))
+    remove_quiet(staging_dir)
+
+    schema_version = info.get("schema_version", 0)
+    _log.info(f"导入已落恢复任务: schema v{schema_version}，"
+              f"重启 web_server 后生效；当前库已快照 {backup_name}")
+    return {
+        "ok": True,
+        "backup_name": backup_name,
+        "message": "恢复任务已生成：当前库已自动备份，重启 web_server 后即应用导入的数据",
+    }
+
+
+# ================== 启动消费（web_server.py init_db 前调用） ==================
+def consume_pending_restore():
+    """把 restore_pending/users.db 换位为当前 users.db（删除旧 wal/shm，合并 apks）。
+
+    必须在 SQLAlchemy engine 首次打开 users.db 之前执行（web_server 装配时调用）。
+    失败不阻塞启动：坏恢复文件会挪到 BACKUP_DIR/restore_failed_*/ 并继续用旧库。
+    返回是否真的应用了恢复。
+    """
+    pending_db = os.path.join(RESTORE_PENDING_DIR, "users.db")
+    if not os.path.exists(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"))
+        remove_quiet(RESTORE_PENDING_DIR)
+        _log.error(f"恢复任务校验失败，已搁置到 {fail_dir}，继续使用当前库: {msg}")
+        return False
+    _ensure_dir(DATA_DIR)
+    os.replace(pending_db, DB_FILE)
+    for ext in ("-wal", "-shm"):
+        p = DB_FILE + ext
+        if os.path.exists(p):
+            remove_quiet(p)
+    # 合并 apks（覆盖同名）
+    apk_src = os.path.join(RESTORE_PENDING_DIR, "apks")
+    if os.path.isdir(apk_src):
+        _ensure_dir(APK_DIR)
+        for fname in os.listdir(apk_src):
+            src = os.path.join(apk_src, fname)
+            dst = os.path.join(APK_DIR, fname)
+            if os.path.exists(dst):
+                os.remove(dst)
+            shutil.move(src, dst)
+    remove_quiet(RESTORE_PENDING_DIR)
+    schema_version = msg.get("schema_version", 0) if isinstance(msg, dict) else "?"
+    _log.info(f"已应用备份恢复: users.db 替换完成（schema v{schema_version}），apks 已合并")
+    return True

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}")
@@ -608,6 +606,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 +757,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:

core/uiauto_helper.py

@@ -89,9 +89,10 @@ def get_elements(serial):
       1. 有 resource-id/text/content-desc 的元素：
          先预统计该属性在整棵树中的出现次数——
            - 唯一出现：直接用属性选择器 //*[@resource-id="x"]
-           - 重复出现（如抖音信息流点赞按钮同 id 几十个）：附加 [k] 位置谓词
+           - 重复出现（如抖音底部导航 4 个 tab 同 id）：用**整体加括号**的
-             精确到具体实例 //*[@resource-id="x"][k]。uiautomator2 的 d.xpath()
+             `(//*[@resource-id="x"])[k]` 精确到第 k 个匹配。
-             底层是 lxml 标准 XPath，[k] 与抓取时同一语义，不会误中屏幕外第一个。
+             注意 XPath 语义：`//*[@id="x"][k]` 是"在其父节点中排第 k"，不是
+             第 k 个匹配——历史实现踩过这个坑（多实例时 [2..n] 全部失配）。
       2. 无任何属性的元素：
          用最近一个有属性祖先的选择器限定范围 + 同 class 兄弟序号定位
          （如 //*[@resource-id="x"]/FrameLayout/ImageView[2]）；
@@ -153,14 +154,21 @@ def _extract(root, out):
             count_attrs(c)
 
     def attr_selector(attr, value, cnt, seen):
-        """属性选择器：唯一直接出，重复加 [k] 位置谓词。返回 (选择器, suggested)。"""
+        """属性选择器：唯一直接出；重复时用 `(…)[k]` 精确到**第 k 个匹配**。
+
+        重要（XPath 位置谓词语义）：
+          //*[@resource-id="x"][2]   → 「在**其父节点**中排第 2 的属性匹配」，**不是**第 2 个匹配
+          (//*[@resource-id="x"])[2] → 「第 2 个匹配」← 我们要的
+        历史实现写成前者，导致同 id 多实例（如抖音底部导航 4 个 tab 同 id）时
+        [2..n] 全部匹配不到 → 运行时"未找到元素"（2026-09-10 实测修复）。
+        """
         seen[value] += 1
-        val = f'//*[@{attr}={_xpath_q(value)}]'
+        base = f'//*[@{attr}={_xpath_q(value)}]'
         if cnt[value] > 1:
-            val += f"[{seen[value]}]"
+            val = f"({base})[{seen[value]}]"
             return val, {"type": "xpath", "value": val,
                          "indexed": True, "occ": seen[value], "total": cnt[value]}
-        return val, {"type": "xpath", "value": val}
+        return base, {"type": "xpath", "value": base}
 
     def flatten(node, depth=0, path="", ctx=None, tag_path="", tag_index=1):
         """递归扁平化。

doc/AI_TASK_GEN.md

@@ -0,0 +1,182 @@
+# AI 建任务（AI Task Generator）设计文档
+
+> 分支：dev | 状态：设计稿（未实现） | 日期：2026-09-09
+> 关联：AI 控制台（web/agent_api.py）、MCP 设备工具（mcp_server/）、任务/步骤编辑器（tasks/generic、static/admin/editor.js）
+
+## 1. 背景与目标
+
+平台已有两套能力，但互不相通：
+- **AI 控制台**：一句话 + 选设备 → 多模态 Agent（DeepSeek）通过 19 个 `de_*` 工具在手机上「边看边做」（截图看屏、`de_ui_tree` 拿元素树、`de_tap_element/de_tap_text` 语义点按），流式回放步骤。
+- **任务系统 + 步骤编辑器**：`generic_steps` 任务 = 一棵可嵌套步骤树（open_app/click/swipe/loop/group/if_el…18 种节点），在编辑器里拖拽编排、单步试跑、定时调度。
+
+目标：让**非工程用户用一句自然语言需求**（例：「创建一个每日养号刷视频的任务，每天 8:00-9:00 在 100.100.10.13 跑」）得到**一条可直接调度、可继续在现有步骤编辑器里手改的任务**。AI 先自己在设备上打开 App、看 UI 树、确认可点元素，再直接撰写编辑器的步骤 JSON。
+
+### 产品体验（一页）
+1. 用户进入「AI 控制台 → 模式=AI 建任务」，选一台**空闲**设备，填需求 +（可选）任务名/调度/目标。
+2. AI 自探并**流式回放**（工具卡 + 截图，与现在一致）：开 App → dump UI 树 → 确认要点的元素可命中 → 写步骤。
+3. 完成后平台返回任务草稿 `draft`，服务端 schema 校验后，**前端直接打开现有「新建任务 → 步骤编辑器」**预填。
+4. 用户核对/手改/单步试跑 → 保存 → 进任务列表，走原有调度器执行。
+
+**核心信任原则：AI 只“提案”，不直接建库、不直接执行最终任务；最终落库/执行都在用户确认后由现有机制完成。**
+
+## 2. 范围（P0 定稿，2026-09-09 与用户确认）
+
+- **入口**：AI 控制台加「聊天 / AI 建任务」模式开关，复用会话/SSE/设备选择/停止/刷新恢复骨架。不新建顶级 Tab。
+- **产出方式**：**AI 直接撰写编辑器的步骤 JSON**（非操作轨迹翻译）。自探信息只作上下文与审计；探索中的误点/多余截图不会混入任务。
+- **任务类型**：**只产 `generic_steps`**（通用步骤）——平台当前唯一的任务类型
+  （原 `douyin_nurture` 预设参数生成已随该类型删除，不再做）。
+- **定位原则：全部基于 UI 树**：
+  - 模型定位/点击一律走 `de_ui_tree` 拿到的元素（`text`/`id`/`description`/`text_contains`），多实例用 index，或后端 `uiauto_helper` 生成的 `//*[@resource-id=..][k]` XPath；
+  - `de_tap_element` 确认能命中后才写进 `click` 步骤；
+  - **默认不产 `click_xy` 坐标点击**；UI 树给不了的元素记入 notes，交给人工/OCR 兜底；
+  - 滑动用方向语义 `swipe{direction}`，不用像素坐标。
+- 产出完整任务信封：`{name, task_type:"generic_steps", target, schedule, retry, enabled, params:{max_duration, steps}}`。
+
+## 3. 现状与可复用点（实现依据）
+
+- 多模态 Agent 链路：`web/agent_api.py`（`POST /api/agent/run` 起后台线程、SSE `delta/step/done/error`、`/stop`、刷新恢复 `GET /api/agent/run`）→ `mcp_agent/agent.py`（OpenAI 兼容流式，工具经 fastmcp Client 拉 8033 的 19 个 `de_*`）→ `mcp_server/mcp_server.py`。
+- 前端 AI 控制台骨架：`templates/admin/monitor.html` `#tab-agent` + `static/admin/agent.js`（设备选择、`sendAgentMsg`、`listenStream` 渲染 `agent-toolcard`、实时画面跟随）。
+- 步骤权威 schema（前后端同构）：`tasks/generic/task.py` `STEP_TYPES`（L44-83）/ `DEFAULT_PARAMS`（L86-103） 与 `static/admin/editor.js` `STEP_LIB`（L3-23）。
+- 元素抓取 → XPath：`web/tasks_api.py /api/uiauto/elements`（L224）→ `core/uiauto_helper.get_elements`（`suggested.value` 即编辑器可用的 XPath）。
+- 单步试跑：`/api/steps/test`（tasks_api.py L249）+ `editor.js _testStep`；`tasks/generic/task.py test_step`（L633）。
+- 任务/调度/目标：`core/task_manager.py` `TaskJob`（L121-199）；`POST /api/jobs`（tasks_api.py L68）。
+- 设备占用语义：MCP 写工具 `_ensure_device_free`（mcp_server.py L60-78，running/connecting → `device_busy`）；`agent_api` run 入口同样对 worker running/connecting 拒绝（409）。
+- 经验库自进化：`agent_experience` + bigram 检索注入 + 每日巡检（`web/agent_api.py`）——P1 沉淀模板的现成载体。
+
+## 4. 架构与数据流
+
+```
+需求+设备(空闲) ──▶  Designer Agent(自探, 模式=designer)
+                        │  de_open_app / de_ui_tree / de_screenshot / de_tap_element…
+                        ▼
+                平台工具 submit_task(draft)  ← 结束性调用
+                        │  服务端 draft schema 校验(白名单+必填+深度≤5)
+                        ▼
+        前端: 打开 openTaskModal 步骤编辑器, 预填 draft.task
+                        │  用户核对/手改/单步试跑(/api/steps/test)
+                        ▼
+                POST /api/jobs  → 任务列表(原调度器执行)
+   (P1) draft+需求 沉淀 agent_experience, 相似需求注入参考
+```
+
+### 4.1 Designer Agent（新增模式，复用现有 Agent）
+- `mcp_agent` 增加 designer 系统提示词：角色=自动化任务设计师；行为约束见 §5.1。
+- 增加**平台级工具**（不属设备 `de_*`）：
+  - `submit_task(draft)`：结束性工具，模型完成自探后提交草稿即停止，服务端立即校验。
+- 会话内同时记录**结构化 trace**（每轮 `on_tool` 的 `{tool, args 精简, 屏号/证据}`），用于：校验证据（每个 selector 来自哪次树）、审计、P2 回放。
+- `POST /api/agent/run` 增加 `mode:"designer"`；`done` 事件负载携带 `draft`（校验通过）或 `draft_error`（校验失败+原因，让模型补一轮）。
+
+### 4.2 draft 契约
+```json
+{
+  "summary": "每日8-9点刷抖音养号：开抖音→循环(看5~35s+上滑)+随机间隔",
+  "task": {
+    "name": "抖音每日养号",
+    "task_type": "generic_steps",
+    "target": {"mode":"serial","serial":"100.100.10.13:5555"}
+            | {"mode":"group","group_name":"测试"} | {"mode":"all"},
+    "schedule": {"mode":"once"} | {"mode":"cron","cron":"0 8 * * *"}
+               | {"mode":"cron_stop","cron":"0 8 * * *","stop_cron":"0 9 * * *"},
+    "retry": {"max_attempts":5,"delay":30},
+    "enabled": true,
+    "params": {
+      "max_duration": 0,
+      "steps": [
+        {"type":"open_app","label":"打开抖音","params":{"package":"com.ss.android.ugc.aweme","wait_home":true}},
+        {"type":"loop","params":{"loop_mode":"rounds","max_iterations":30,"children":[
+           {"type":"wait","params":{"min":5,"max":35}},
+           {"type":"swipe","params":{"direction":"up","duration_min":0.25,"duration_max":0.5}}
+        ]}}
+      ]
+    }
+  },
+  "notes": ["评论按钮需先进入视频页才可见"],
+  "evidence": [{"screen":"抖音首页","element":{"text":"关注","id":"..."},"xpath":"//*[@resource-id=\".../gvo\"]"}]
+}
+```
+- 步骤节点结构：`{id?, type, label?, params}`；`id` 执行端忽略（编辑器重新生成），`params` 必填。
+- 必填字段语义（**空值会被执行端静默跳过**，校验器必须拦）：
+  - `click / long_click / swipe_until / wait_el / if_el` → `params.selector_value`
+  - `open_app / stop_app` → `params.package`
+  - 容器：`loop / group` → `params.children`（非空）；`if_el` → `params.then`（`else` 可选）
+  - `swipe_until` → direction + max_swipes；`click_xy` P0 不产（如允许则 x/y 0-100）
+  - 节点公共可选 `params.probability`（0-100，缺省 100）
+- `selector_type` 允许值：`xpath / description / text / resourceId / descriptionContains / className`（`if_el` 可 `ocr`）。
+
+### 4.3 服务端新增
+- `core/task_draft.py`：
+  - `STEP_TYPES` 白名单 + 每类必填/深度校验 `validate_steps(steps, depth)`（嵌套≤5）；
+  - `validate_draft(draft)`：任务信封（name 非空、task_type==generic_steps、target mode ∈ {all,group,serial}（group 名存在）、schedule cron 合法、steps 校验）；
+  - 归一化：把 `schedule` 里「每天 8-9 点」这类由前端/向导填的值转成 cron/cron_stop。
+- `web/taskgen_api.py`（或并入 `agent_api`，推荐并入以最大化复用）：
+  - 入口检查：serial 必须、设备在池/在线、worker 非 running/connecting（409，与现有语义一致）；
+  - 起 designer 后台线程；SSE 事件在现有 `delta/step/done/error` 基础上，`done` 可带 `draft`。
+- **注意**：现有 `POST /api/jobs` 对 params **盲存**（只校验 name+task_type）。AI 通道在**保存前**必须过 `validate_steps`，避免「任务 done 但什么都没做」（执行器对未知 type/空 selector 静默跳过）。
+
+### 4.4 前端
+- `monitor.html` AI 控制台加模式切换；建任务模式下输入栏旁有折叠「任务设置」（名称/调度时间/目标 serial·分组·全部/备注）。
+- `agent.js`：done 携带 draft 后：
+  - generic_steps → 调 `openTaskModal()`（tasks.js）并把 `draft.task` 灌入步骤编辑器（step 卡片可视化、可拖改、单步试跑、保存）；
+  - 弹窗内对 `notes`（含“需人工复核/OCR 兜底”项）给出醒目提示。
+- 过程回放沿用现有 `agent-toolcard` 渲染；可标记当前为 designer 轮以便后续区分。
+
+## 5. 约束与安全（红线）
+
+### 5.1 Designer 自探规则（写入提示词）
+1. 先 `de_open_app(package)`，再 `de_ui_tree` + `de_screenshot` 看每屏；点到关键状态后再 dump 下一屏。
+2. 每个将写入步骤的目标元素，先用 `de_tap_element`（by=text/id/desc…）+ 截图**确认可命中**，并记下证据。
+3. **不做破坏性动作**：需“评论/发送”时只确认输入框/发送键存在，不真发；产物里这类步骤 `probability` 调低并在 notes 标注“请人工复核”。
+4. 探索步数上限（P0 建议 30 步），可被 `/stop` 打断；结束后尽力还原前台 App。
+5. 未命中的元素一律不进任务；拿不准的进 notes 而非硬编。
+
+### 5.2 平台级约束
+- 自探/试跑只在**用户选的空闲设备**（busy → 409），杜绝与运行中任务在设备上物理打架。
+- AI 不直接建库；生成任务仍需用户点保存（POST /api/jobs 现有权限）。
+- 尽量不写死坐标；P0 默认禁 `click_xy`，产物以树元素定位为主。
+
+## 6. 里程碑
+- **P0（本设计主体）**：designer 模式 → 自探（UI 树定位）→ 直接撰写 generic_steps draft → 服务端 schema 校验 → 前端步骤编辑器预填确认保存。验收：一句话在真实设备上生成一条可调度的 generic_steps，步骤全部来自 UI 树且编辑器可打开。（平台只剩 generic_steps 一种任务类型，与原规划一致）
+- **P1**：模板沉淀：把 draft+需求写入 `agent_experience`（新列存结构化 steps 或 JSON），相似需求注入参考；整链「演示试跑」（把 steps 在设备上以受控方式跑一遍并截图回报，需新增端点，复刻 `device_busy` 拒绝语义）。
+  - **进展（2026-09-10）**：动作级沉淀已落地——`agent_action` 表 + 从**成功步骤**蒸馏"命名动作"（steps 用编辑器 schema、带元素定位、禁坐标）+ 执行前按名/别名召回注入（`web/agent_api.py`）。AI 建任务可直接把这些动作当作 generic_steps 的**预制件**复用。
+- **P2**：自定义动作支持（内联展开成 group，或新增 `action_ref` 节点 + 执行器/编辑器同步）；多设备并行；成本与 token 控制。
+
+## 7. 实现时需新增/改动文件（规划）
+- 改：`mcp_agent/`（designer 提示词与 `submit_task` 工具、结构化 trace）、`web/agent_api.py`（mode=designer、done 带 draft）、`static/admin/agent.js` + `templates/admin/monitor.html`（模式切换/任务设置/draft 预填）、`doc/`（本文档关联）。
+- 新：`core/task_draft.py`（schema+校验+归一化）、（可选）`web/taskgen_api.py`。
+- 不动：任务执行器、调度器、`POST /api/jobs` 主体（保持现有盲存，只在 AI 通道校验）。
+
+## 8. 验收（P0 实现后自测）
+1. 目标设备空闲时：需求「每日 8-9 点刷抖音养号」→ 生成 generic_steps 任务，步骤为 `open_app → loop(wait+swipe)` 结构，调度 cron_stop 8-9 点。
+2. 打开编辑器中该任务：步骤卡片完整、可拖改、单步试跑命中；保存后任务列表出现且下次运行时间正确。
+3. 反例：模型产出含 `click_xy` 或未知 type / 空 selector → 服务端校验拦截并让模型补正；busy 设备入口 409。
+4. 探索全程可在前端回放（工具卡+截图），未发送真实评论/未污染设备状态。
+
+## 9. 需要转成 MCP / 平台工具的能力（分层，2026-09-09 与用户确认）
+
+> 背景问答结论：目前 MCP 只有**设备层 19 个 `de_*`**（控制 + 只读 `de_list_tasks`），平台 CRUD（任务增改/启停/立即运行、分组、设备池、自定义动作、APK、备份、用户）**都还没 MCP 化**。方向认同「先把工具链补完善」，但不做"把所有平台 CRUD 一次性搬成 MCP"的大而全——**按消费方（AI 建任务 / 外部自动化）分层、按需补**。新增 MCP 工具一律：进 `doc/MCP.md` 手册 + `doc/MCP_DESIGN.md` 规格 + 与 web 同源的权限/busy/审计 + 校验逻辑下沉到 `core/` 共用（防双份漂移）。
+
+### 9.1 现状盘点
+- MCP（`mcp_server/mcp_server.py`，19 个 `de_*`）＝ 设备控制 + 设备只读 + `de_list_tasks`（平台任务只读）。
+- 任务创建/修改/删除、toggle、立即运行、分组、设备池管理、自定义动作、APK、系统备份等 **REST 路由只给前端用，未暴露 MCP**。
+
+### 9.2 P0 —— AI 建任务链路真正需要的「平台工具」（最小集）
+只补两小类，其余设备操作全部复用现有 `de_*`：
+1. **只读清单**（供自探确定 target/能不能做）：
+   - `list_task_types` / `list_groups`（target 选 group 用）/ `list_pool`（可调度设备，含 busy 状态）
+   - （可与现有 `de_list_devices` 合并语义，避免重复）
+2. **校验 + 提交（结束性）**：
+   - `submit_task(draft)` → 服务端用 **共用** `core/task_draft.validate_steps()/validate_draft()` 校验，**不直接落库**，返回 draft 供前端打开步骤编辑器预填、人工确认后走 `POST /api/jobs`。
+
+> 关键：P0 的 Agent **不暴露任务 CRUD 写权限**（create/update/toggle/run），否则模型可绕过"AI 提案 → 人工确认"直接入库，破坏信任模型。
+
+### 9.3 P1 —— 外部自动化 / 后续 Agent 的「写 MCP」（受权限约束，逐块加）
+若目标延伸为"外部程序能像调 REST 一样操控平台"，则按此清单**逐个**补（每加一个都做权限+busy+审计+校验下沉）：
+- 任务：`create_job` / `update_job` / `delete_job` / `toggle_job` / `run_job_now` / `query_jobs`
+- 分组：`list_groups` / `create_group` / `update_group` / `delete_group`
+- 设备池：`pool_list` / `pool_add` / `pool_remove` / `pool_toggle`
+- 自定义动作 / APK 清单 等视使用再加
+- **只读清单优先搬**；写类确认有真实消费方再做，避免空转。
+
+### 9.4 分层与登记（红线）
+- 每新增/修改/删除一个 MCP 工具或平台配置：同步更新 `doc/MCP.md`（全清单）、`doc/MCP_DESIGN.md`（规格/层级），并在提交里体现——见全局「doc 同步红线」。
+- `core/task_draft.py` 是 web 校验与 MCP 校验的**唯一来源**，杜绝两套规则漂移。

doc/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # 架构详解
 
-本文面向想深入理解 `platform-tools` 内部设计的开发者。如果你只想使用，看 [README.md](file:///d:/platform-tools/README.md) 即可。
+本文面向想深入理解 `auto_control` 内部设计的开发者。如果你只想使用，看 [README.md](../README.md) 即可。
 
 ---
 
@@ -45,7 +45,7 @@
        │
        ▼
 ┌──────────────┐
-│ data/users.db│  SQLite 持久化（用户/分组/任务/设备池/自定义动作/APK记录）
+│ data/users.db│  SQLite 持久化（用户/分组/任务/设备池/待连接设备/自定义动作/APK记录/AI会话/经验库 + app_meta KV）
 └──────────────┘
 ```
 
@@ -175,17 +175,26 @@ SQLAlchemy 模型，存于 `data/users.db`：
 
 | 模型 | 表名 | 说明 |
 |------|------|------|
-| `User` | user | 后台用户（Flask-Login 认证，SHA256 密码；`is_admin` 管理员 + `perms` 业务权限位） |
+| `User` | user | 后台用户（Flask-Login 认证，Werkzeug 哈希密码；`is_admin` 管理员 + `perms` 业务权限位） |
 | `DeviceGroup` | device_group | 设备分组（serials 存 JSON） |
 | `TaskJob` | task_job | 任务计划（target/params/schedule/retry 存 JSON） |
 | `CustomAction` | custom_action | 自定义动作（步骤打包，steps 存 JSON） |
 | `ApkFile` | apk_file | APK 文件元信息 |
+| `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_*` 等；
+> - `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`）。
+>
+> **备份覆盖（红线）**：持久化表须登记进 `core/system_backup.py` 的 `SUMMARY_TABLES`（→ 导出清单/预览可见、覆盖自检生效），并同步 `doc/DEPLOY.md` §3.5；未登记的表在备份预览里不可见，会被误判为"没备份"。
 
 **数据库初始化**（`init_db`）：
 - 创建所有表
 - 首次启动创建默认管理员 `admin/admin123`
 - 自动迁移旧 `groups.json` / `jobs.json` 到 SQLite（迁移后归档为 `.migrated`）
-- 版本化 schema 迁移（`SCHEMA_MIGRATIONS`）：结构变更必须追加迁移条目，`create_all` 只建新表不加列
+- 版本化 schema 迁移（`SCHEMA_MIGRATIONS`，**当前到 v4**，见 `core/models.py`）：结构变更必须追加迁移条目，`create_all` 只建新表不加列
 
 ### 权限模型
 
@@ -223,6 +232,11 @@ APK 上传/解析/批量安装。
 
 元素树解析：递归提取每个节点的 `resource-id/text/content-desc/class/bounds` 等属性，并推荐最佳选择器（优先 xpath）。
 
+**XPath 序号语义（重要）**：同一属性多个实例时，生成 **`(//*[@resource-id="x"])[k]`**（整体加括号 = 第 k 个匹配）。
+不可写成 `//*[@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`）
 
 条件判断的 `ocr` 选择器实现：截屏 → RapidOCR（ONNX 推理，中英文模型随包内置）→ 关键词匹配 → 返回文字中心像素坐标（与 u2 `d.click` 一致）。
@@ -242,13 +256,15 @@ APK 上传/解析/批量安装。
 | `tasks_api.py` | 任务计划/分组/自定义动作/元素抓取/步骤测试 |
 | `admin_api.py` | 用户管理/日志 |
 | `tools_api.py` | adb 终端/剪贴板注入/应用版本 |
-| `devices_api.py` | 设备池管理（增删停用/重连/型号采集） |
+| `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` 只保留：app 创建、数据库初始化、蓝图注册、uiautodev 生命周期、启动（193 行）。
+`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 子进程启停与设备池预连接线程；启动。
 
 ---
 
@@ -259,8 +275,7 @@ APK 上传/解析/批量安装。
 ```
 tasks/__init__.py
   ├── from .base import BaseTask, register_task, list_task_types, get_task_class
-  ├── from .douyin import task    # 触发 @register_task
+  └── from .generic import task   # 触发 @register_task（当前唯一任务类型）
-  └── from .generic import task   # 触发 @register_task
 ```
 
 `@register_task` 装饰器将 Task 类注册到全局 `_TASK_TYPES` 字典，key 为 `task_type` 字符串。
@@ -285,9 +300,12 @@ Job 下发时只传需要覆盖的字段，调度器做三层合并：
 每个 App 有独立的 Action 注册表（`create_action_registry()`），互不污染。
 
 ```
-core/actions/base.py        — BaseAction 全局基类 + should_trigger + register_action
+core/actions/base.py           — BaseAction 全局基类 + should_trigger + register_action
-tasks/douyin/actions/base.py — ACTIONS = create_action_registry() + list/get 函数
+tasks/<app>/actions/base.py    — ACTIONS = create_action_registry() + list/get 函数
-tasks/douyin/actions/like.py — @register_action(ACTIONS) LikeAction
+tasks/<app>/actions/xxx.py     — @register_action(ACTIONS) XxxAction
+
+> 当前没有 App 专属任务包（只剩 `tasks/generic/`，步骤全走通用 STEP_TYPES，不建专属 action 表）；
+> 新增专属任务类型时按上面三行建 `tasks/<app>/actions/`。
 ```
 
 **循环导入坑**：`actions/__init__.py` 必须先 `from .base import ACTIONS`，再 `from . import like`。
@@ -300,10 +318,17 @@ tasks/douyin/actions/like.py — @register_action(ACTIONS) LikeAction
 
 `templates/admin/monitor.html` 是纯 HTML+CSS+JS 单页应用，无框架依赖。
 
-- **Tab 切换**：5 个 Tab（监控/任务/分组/日志/用户），纯 DOM 操作
+- **Tab 切换**：7 个顶级 Tab（监控/任务/日志/用户/工具/AI 控制台/系统），均在 monitor.html 内 `.tab-panel` 切换（纯 DOM 操作）；独立页面仅 `/login`、`/wall`。原"分组"已无顶层入口（移到工具页子分栏）
 - **数据获取**：`fetch()` 调 JSON API，5 秒轮询 `/api/status`
 - **状态渲染**：设备表格、任务卡片、进度条、徽章，纯 DOM 操作
 
+**监控页「任务运行概况」卡片（2026-09-10 收敛）**：每张卡片只保留两个操作——**执行任务**（`POST /api/jobs/:id/run`）
+与**停用任务/启用任务**（`POST /api/jobs/:id/toggle`，按当前状态切换文案）；原"编辑/删除"已移除
+（编辑与删除统一去「任务」Tab 操作，避免监控页误删）。卡片新增**覆盖设备**一行：设备清单来自
+`/api/jobs` 的 `coverage`（后端按 target 定义解析，见 [API.md](API.md) §5），在线/运行中状态由前端
+用已在手的 `/api/status` 数据标注成彩色 chip（在线=蓝、运行中=黄+⏳、离线或不在池=灰划线+✕，
+完整 serial 与型号放 tooltip）。
+
 ### 5.2 步骤编辑器
 
 `generic_steps` 任务的步骤编辑器（任务弹窗已加宽到 1000px）：
@@ -317,14 +342,47 @@ tasks/douyin/actions/like.py — @register_action(ACTIONS) LikeAction
 
 ### 5.3 页内子分栏
 
-任务/工具 Tab 用通用 `showSubTab(tabId, name)` 实现页内子分栏：每个子分栏一个 `.sub-panel`，
+任务/工具/系统 Tab 用通用 `showSubTab(tabId, name)` 实现页内子分栏：每个子分栏一个 `.sub-panel`，
-`_activeSubs` 记住各 Tab 上次选中的子分栏。工具 Tab 集中了全部管理工具（剪贴板注入/adb 终端/
+`_activeSubs` 记住各 Tab 上次选中的子分栏。现状子分栏：
-Tailscale/应用管理/应用版本/已装应用/STF 设备管理），维护 Tab 仅保留 STF 服务。
+- **任务**：任务计划 / 自定义动作
+- **工具**：剪贴板注入 / adb 远程终端 / Tailscale 管理 / 应用管理 / 应用版本管理 / 设备已装应用 / 设备池管理 / 设备分组
+- **系统**：数据备份 / 导入恢复
 
-### 5.4 元素抓取模态框
+（原"分组"顶级 Tab 与"维护/STF 服务"子分栏已不存在——分组已移入工具页子分栏，STF 已摘除。）
+
+### 5.4 AI 控制台的记忆面板
+
+AI 控制台（顶级 Tab）右上角两个模态框，管理自进化记忆：
+- **🧠 经验库**：任务级经验（`agent_experience`，整任务配方）+ 每日 AI 巡检建议（删除需人工确认）。
+- **🎬 动作库**：动作级经验（`agent_action`）——命名动作（可含 1~N 步）+ 编辑器 schema 步骤 + **元素定位（禁坐标）**；由任务成功后从**成功步骤**自动蒸馏，执行前按名/别名召回注入；面板支持查看/编辑/删除/手动新建（保存经服务端校验，坐标步骤被拒）。
+- **会话列表显示会话 ID**（前 8 位，等宽小字），点击即复制完整 ID——便于反馈问题时引用 `conv=<id>`。
+
+#### 5.4.1 回答渲染与 token（2026-09-10）
+
+| 能力 | 落点 | 说明 |
+|------|------|------|
+| **Markdown 渲染** | `static/admin/markdown.js`（`renderMarkdown()`） | 自研轻量渲染器，**不引 CDN**（生产 220 在内网）：标题/段落/软换行/粗斜体/删除线/行内代码/围栏代码块/有序无序列表（含嵌套）/引用/表格/分隔线/链接。**先 `esc()` 转义再套标记**，模型输出里的 HTML 只显示为文本（防注入） |
+| **推理链可折叠** | `agent.js` `_appendReasoning()` + `<details class="reasoning">` | 流式思考时自动展开、正文开始时自动收起；用户手动点过 `summary` 后不再自动改（`dataset.touched`）；摘要显示「思考过程（N 字）」 |
+| **token 显示** | `mcp_agent/agent.py` `_accumulate_usage()` + `agent_api` SSE `usage` 事件 | 每次模型调用完成后推**本轮累计**（`prompt/completion/total/calls`）；单条消息脚注 + 顶栏「本会话累计」（历史 + 运行中） |
+| **推理链/用量落库** | `_agent_thread` 把 `usage`、`reasoning` 写进会话 assistant 消息 | 刷新页面后仍可回看；**回灌模型上下文时只取 `role`/`content`**（不污染 token） |
+
+> **token 采集的兼容性**：请求带 `stream_options: {"include_usage": true}`，按「每次模型调用」取末尾 chunk 的 `usage` 累加（多轮工具调用会多次累加）。个别网关不认该参数会直接 **HTTP 400** → `_UsageUnsupported` 捕获后**自动关掉并重试一次**（`self._include_usage=False`），不影响主流程。
+>
+> **推理链体积**：只保留前 `_REASONING_KEEP`=6000 字符落库（会话消息上限 60 条），避免历史无限膨胀。
+
+> **蒸馏健壮性（2026-09-10）**：经验/动作靠**模型蒸馏**落库。推理型模型会把 token 预算烧在 `reasoning` 上，导致 `content` 为空或被截断（`finish_reason=length`）→ 早期只读 `content`，经验/动作被**静默丢弃**（"小红书·苏州饭店"案例）。现策略：
+> 1. 蒸馏调用**关闭推理**：`"thinking": {"type": "disabled"}`（该代理支持；实测关掉后 reasoning=0、正文正常，配方 3/3 合格）——这是关键修复；
+> 2. 配方用**纯文本问法**（不要放可照抄的占位示例，否则模型会原样当配方存下来）+ 质量门槛 `_recipe_ok`（过短/含省略号占位 → 丢弃并重试）；
+> 3. 动作提炼用 JSON + **截断容忍**提取（`_loads_lenient` 逐对象抢救）+ 顶层 `{action,params}` 形状归一 + 输入/产出限量（≤10 步输入、≤3 动作×4 步）；
+> 4. 两类失败都有日志（`经验提炼:` / `动作提炼:` 含样本），不再静默。
+
+### 5.5 元素抓取模态框
 
 独立的第二层模态框（`el-picker-overlay`，z-index 1100），不影响任务编辑窗口：
 1. 选择设备 → 2. 加载截图 + 元素树 → 3. 点击元素/边界框 → 4. 回填选择器
+5. **抓取时直接验证**（每条元素右侧两个按钮，不会与"点击回填"冲突）：
+   - 「▶ 点一下」：按元素 `bounds` 中心在设备上真点一次（`POST /api/screen/tap`，`snap=1` 自动吸附到可点元素），返回吸附结果并自动刷新截图——用于确认位置/是否可达；
+   - 「✓ 测选择器」：用**将填入的选择器**真跑一次 click（`POST /api/steps/test`），返回 `命中/未找到/已执行`——用于确认回填的选择器在真实界面能命中（元素无有效选择器时不显示此按钮）。
 
 ---
 
@@ -344,15 +402,15 @@ Tailscale/应用管理/应用版本/已装应用/STF 设备管理），维护 Ta
 
 ### 6.3 为什么绝不 kill-server
 
-`adb kill-server` 会断开所有设备的 adb transport，导致 STF provider 误判全部设备离线并触发重连。连接失败就返回 False，由调用方处理。
+`adb kill-server` / `adb disconnect` 会断开共享的 adb transport（历史与 STF provider 共享；STF 摘除后红线仍保留——多 worker、前台扫描、设备自动发现共用同一 adb server），影响所有运行中的任务。连接失败就返回 False，由调用方处理。
 
 ### 6.4 为什么状态查询带缓存
 
-STF API 响应慢（设备多时 2-5 秒），每次 `/api/status` 都打 STF 会阻塞 Flask。带 5 秒缓存，Worker 状态实时读内存（无 IO）。
+状态源 = 本地 SQLite 设备池 + adb + 内存 worker 状态。5 秒缓存避免每次 `/api/status` 都查库/adb 阻塞 Flask；Worker 实时状态读内存，不受缓存影响。
 
 ### 6.5 为什么 DeviceOfflineError 不重试
 
-设备掉线后短时间内不会自愈，重试只会浪费配额并阻塞调度器。让设备进入冷却，由运维/STF 恢复后再启用。
+设备掉线后短时间内不会自愈，重试只会浪费配额并阻塞调度器。让设备进入冷却，可依赖设备自动发现（device_discovery 对正式池断联设备每轮 adb 重连）恢复后再启用。
 
 ---
 
@@ -361,14 +419,21 @@ STF API 响应慢（设备多时 2-5 秒），每次 `/api/status` 都打 STF
 ```
 主线程（Flask）
   ├── HTTP 请求处理（threaded=True，每请求一线程）
-  ├── APScheduler 线程（cron 触发）
+  ├── TaskManager.scheduler（APScheduler，cron 触发任务计划）
+  ├── 经验巡检 BackgroundScheduler（03:47 Asia/Shanghai，web_server 装配）
+  ├── 设备自动发现线程（device_discovery._discovery_loop，默认 60s 一轮）
+  ├── 设备池型号采集后台线程（device_pool._refresh_models_bg，启动/手动触发）
+  ├── 设备池预连接线程（web_server._preconnect_pool_devices，重启后加速恢复）
+  ├── AI Agent 运行线程（agent_api._agent_thread，单实例 + SSE 推送）
   ├── 看门狗线程（_Watchdog，30s 间隔）
-  ├── uiautodev 子进程
+  ├── uiautodev 子进程（PID + cmdline 校验，防容器 PID 复用误杀）
   └── Worker 线程（每台设备一个）
         ├── _run_with_retry 线程（重试循环）
         └── BaseWorker 线程（设备生命周期 + run_task）
 ```
 
+> MCP server（127.0.0.1:8033）是**独立进程**（scripts/start.sh 拉起），不是 web_server 的线程。
+
 **线程安全**：
 - `_WORKERS_LOCK`：保护全局 worker 状态字典
 - `_ADB_LOCK`：串行化所有 adb 调用

doc/DEPLOY.md

@@ -75,6 +75,8 @@ pip install -r requirements.txt
 | 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，两者取一）。
 
@@ -102,11 +104,17 @@ TAILSCALE_API_KEY=你的Tailscale_API_key
 | `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_*` 等配置已废弃，代码不再读取。）
+> （历史遗留的 `STF_URL`/`STF_TOKEN`/`STF_SSH_*` 等配置：`config.py` 仍读取但无任何功能使用，仅历史保留；生产 `.env` 可留空。）
 
 ### 2.4 启动服务
 
@@ -118,12 +126,26 @@ 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. 监控页应显示 STF 设备池中的设备
+4. 监控页应显示设备池中的设备（本机 adb 在线 + SQLite 配置清单，serial 形如 `100.100.10.x:5555`）
 
 ---
 
@@ -169,7 +191,7 @@ PYTHON=./.venv/bin/python bash scripts/supervise.sh
 
 > 进程守护只保证服务重启，不恢复已运行的任务（worker 状态在内存）。
 >
-> **悬空设备自愈**：崩溃后残留的设备占用（STF 仍显示占用）可配置启动自动清理。单实例部署时在 `.env` 设置 `AUTO_RELEASE_STALE_OCCUPY=true`，web_server 启动会自动释放本账户残留占用；**多实例共用 STF 账户时不要开**（会误放另一实例的任务）。默认关，仅启动时提示。
+> **崩溃后占用自愈（需人工核实）**：历史 `AUTO_RELEASE_STALE_OCCUPY` 机制已随 STF 摘除失效（全库代码不再读取该配置）。设备池的占用互斥仍在（任务 running/connecting 的设备会被锁），但崩溃后残留占用如何释放、是否自动清理，需按当前实现核实后补写本节。
 
 **Docker（生产 python-app 容器）**：
 
@@ -207,7 +229,7 @@ server {
 - **修改默认密码**：登录后立即在"用户"Tab 修改 admin 密码
 - **最小权限分配**：需要多人使用后台时，在"用户"Tab 创建普通用户并只勾选必要权限
   （任务管理/设备控制/应用管理/日志查看），不要把 admin 密码共享出去
-- **修改 SECRET_KEY**：编辑 `web_server.py`，把 `app.config["SECRET_KEY"]` 改成随机字符串
+- **会话密钥 SECRET_KEY**：在 `.env` 写固定 `WEB_SECRET_KEY`（`python -c "import secrets;print(secrets.token_hex(32))"` 生成）；未配置时启动随机生成（每次重启登录态失效，生产务必配置固定值）
 - **限制访问**：生产环境把 `WEB_HOST` 改为 `127.0.0.1`，配合反向代理
 - **防火墙**：只开放必要端口
 
@@ -219,9 +241,31 @@ server {
 
 ### 3.5 数据备份
 
-- 数据库 `data/users.db` 包含用户/分组/任务数据
+**优先推荐平台功能「系统 → 数据备份导出/导入」（仅 admin）**：
-- APK 文件在 `data/apks/`
+
-- 建议定期备份 `data/` 目录
+- **导出**：`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` 前自动消费恢复任务）
+
+**备份覆盖清单（红线）**：覆盖清单 = `core/system_backup.py` 的 `SUMMARY_TABLES`，当前包含
+`app_meta`(系统配置) / `user` / `device_group` / `task_job` / `custom_action` / `apk_file` / `device` /
+`pending_device` / `agent_conversation` / `agent_experience` / `experience_audit` / `agent_action`(动作库)。
+
+> **新增任何持久化表，必须同步登记进该清单**——否则导出清单/预览里看不到它，会被误判为"没有备份"
+> （2026-09-10 动作库 `agent_action` 即因此被误判：数据其实在 `users.db` 快照里，只是清单漏列）。
+> 导出侧有**覆盖自检**（登记表若缺失 → `manifest.coverage_missing` + 日志告警）；导入侧有**反向自检**
+> （备份含未登记表 → 预览告警提示登记）。
+
+目录与常量：
+
+| 目录 | 用途 |
+|---|---|
+| `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/占用文件破坏）。
 
 ---
 
@@ -233,7 +277,7 @@ server {
 |------|------|------|
 | 18050 | Web 后台 | 主服务端口（config.py 可改） |
 | 20242 | uiautodev | 元素抓取服务（自动启动，固定端口） |
-| 7100 | STF | STF 服务端口（STF 自己的配置） |
+| 8033 | MCP | MCP 手机控制 Server（scripts/start.sh 自动拉起，`MCP_ENABLED=0` 可关） |
 | 5555 | adb | 设备 adb 网络端口（设备端） |
 
 ### 4.2 Windows 端口问题（仅 Windows）
@@ -291,16 +335,17 @@ python web_server.py
 | `ModuleNotFoundError: No module named 'flask'` | 依赖未安装 | `pip install -r requirements.txt` |
 | `WinError 10013` | 端口被排除/权限不足 | 改端口或用管理员运行 |
 | `WinError 10048` | 端口被占用 | 改端口或杀占用进程 |
-| STF 获取设备列表失败 | STF 地址/token 错误 | 检查 `config.py` 的 `STF_URL` 和 `STF_TOKEN` |
+| 监控页设备列表为空 | 设备不在池中 / adb 连不上 | 「工具 → 设备池管理」确认已添加且在线，检查设备网络与 5555 端口 |
+| 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` 会关） |
 
 ### 6.2 设备连接失败
 
 | 现象 | 原因 | 解决 |
 |------|------|------|
-| `DeviceOfflineError` | 设备掉线/STF provider 卡死 | 检查设备网络/STF 状态 |
+| `DeviceOfflineError` | u2 连接超时 / atx-agent 无响应 | 检查设备网络，重启设备或重新推送 atx-agent |
 | `u2.connect 超时` | atx-agent 无响应 | 重启设备/重新推送 atx-agent |
 | `adb connect failed` | 设备网络不通/端口未开放 | 检查设备 IP 和 5555 端口 |
-| STF 设备显示离线 | STF 状态缓存 | 用"扫描前台App"复测 |
+| 设备显示离线 | 状态缓存/误报 | 管理后台设备池「重连」，或「扫描前台 App」复测 |
 
 ### 6.3 任务不执行
 
@@ -317,7 +362,7 @@ python web_server.py
 # 查看核心日志
 # 方式一：Web 后台"日志"Tab
 # 方式二：直接看文件
-# logs/core.log   — STF/adb/worker/task_manager
+# logs/core.log   — adb/worker/task_manager
 # logs/task.log   — 任务执行
 # logs/web.log    — Web 请求
 # logs/action.log — 操作执行

doc/DEVELOPMENT.md

@@ -43,7 +43,7 @@
 |------|------|------|
 | 开发机 | 本机（192.168.20.57） | `.venv` + 本地运行 `web_server.py` |
 | 生产机 | 部署机 220 的 `auto_control` | python-app 容器，`network_mode: host` |
-| STF 服务 | ~~`192.168.20.220:7100`~~ | 已停用（2026-08-18 `docker stop stf`，代码已摘除依赖） |
+| STF 服务 | ~~`192.168.20.220:7100`~~ | 已停用（代码已摘除依赖）。注意：此处"已停用"与 [STF_REMOVAL.md](STF_REMOVAL.md) 的"待人工确认"项矛盾（220 侧是否已 `docker stop stf` 未核实），需以 220 实际为准 |
 | adb 容器 | 220 上 `adb`（host 网络 5037） | USB 设备远程 adb server；网络设备补连用 |
 | 设备 | Tailscale `100.100.10.x:5555` | Xiaomi 舰队，本机 `100.100.10.2` 在 tailnet 内 |
 | uiautodev | 本机 `20242` | 元素抓取服务（web_server 自动拉起） |
@@ -62,6 +62,22 @@
 - 本机已在 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，需人工恢复
@@ -92,7 +108,7 @@
 - **任务参数放各自 `tasks/<app>/task.py` 顶部，不放 `config.py`**
 - **生产环境（220）默认只读**：任何写操作（改文件/重启容器/部署）都必须先经负责人确认
 - **数据库是 SQLite**（`data/users.db`，WAL 模式）：运行时数据不提交 git
-- **前端 JS 在 `static/admin/monitor.js`**（已从 HTML 拆分），HTML 里用 `<script src>` 引用
+- **前端 JS 已拆分多文件**（均位于 `static/admin/`）：`monitor.html` 按 `base.js → markdown.js → list.js → monitor.js → editor.js → tasks.js → tools.js → apps.js → admin.js → agent.js → system.js` 的顺序用 `<script src>` 加载（`markdown.js` 提供 `renderMarkdown()`，AI 控制台回答渲染用；依赖 `base.js` 的 `esc()`，故排在其后、agent.js 之前）
 - **监控页/大列表已加分页**：100 台设备也只渲染 10 行/页，不要移除分页逻辑
 - **任务批量触发已错峰**（`_START_STAGGER_SEC`）：避免大量设备同时启动造成 adb 连接风暴，不要移除
 
@@ -153,16 +169,18 @@ with sync_playwright() as p:
 
 - **看日志**：`logs/` 下 `core.log` / `task.log` / `web.log` / `action.log`（10MB 滚动，保留 5 份）
 - **看设备/任务状态**：浏览器监控页，或 `GET /api/status`、`GET /api/health`
-- **清理 STF 残留占用**：前端监控页"强制释放占用"（或 `.env` 配 `AUTO_RELEASE_STALE_OCCUPY=true` 启动自动清理）
+- **停止设备/清异常**：监控页工具条用"停止全部 / 停止选中 / 清除全部异常"（`AUTO_RELEASE_STALE_OCCUPY` 等 STF occupy 残留清理配置代码已不再读取）；崩溃残留的 worker 状态重启即清零
 - **打包项目**：`python scripts/pack.py`
 
 ---
 
 ## 5. 常见开发任务
 
-### 5.1 新增 App 任务
+### 5.1 新增 App 任务类型
 
-参照 `tasks/douyin/` 结构，详见 **[doc/TASK_DEV.md](TASK_DEV.md)**（6 步模板）。
+参照 `tasks/generic/` 结构，详见 **[doc/TASK_DEV.md](TASK_DEV.md)**（6 步模板）。
+注意：当前平台**只保留 `generic_steps` 一种任务类型**；大多数 App 操作直接用步骤编辑器
+编排即可，不必新增任务类型。
 
 ```
 tasks/<app>/
@@ -180,31 +198,77 @@ tasks/<app>/
 | 文件 | 内容 |
 |------|------|
 | `templates/admin/monitor.html` | HTML 结构 + CSS + `<script src>` 引用 |
-| `static/admin/monitor.js` | 全部前端 JS |
+| `static/admin/`（base/markdown/list/monitor/editor/tasks/tools/apps/admin/agent/system.js） | 前端 JS（按 monitor.html 中 `<script src>` 顺序拆分加载，功能归属见各文件；`markdown.js` = 轻量 Markdown 渲染器，AI 控制台回答用） |
 
 改完**强刷浏览器**（Cmd/Ctrl+Shift+R），必要时重启 web_server。
 
 ### 5.4 新增 API
 
-在 `web_server.py` 加 Flask 路由，更新 **[doc/API.md](API.md)**。
+路由按功能域放在 `web/` 蓝图包（`web/__init__.py` 的 `register_blueprints(app)` 统一注册 10 个蓝图：auth / monitor / tasks / admin / tools / devices / apks / tailscale / agent / system）。
+
+- 新增 API：在对应功能域的 `web/xxx_api.py` 里加 `@bp.route(...)` + 权限装饰器（如 `admin_required`）
+- 新建蓝图：需在 `web/__init__.py` 里 import 并加进 `register_blueprints` 的注册元组
+- `web_server.py` 只做 app 装配（初始化、`register_blueprints(app)`、常驻线程启动），一般不改
+- 最后更新 **[doc/API.md](API.md)**
 
 ### 5.5 新增数据库字段/表
 
-- 模型改 `core/models.py`，首次建表用 `create_all()`
+- 模型改 `core/models.py`，首次建表用 `create_all()`；SQLAlchemy 模型未写 `__tablename__` 时默认表名 = 小写类名
 - **已有数据的老库**：在 `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 改动必须同步文档
+
+任何功能/配置/接口/页面改动，须与代码同一 commit 同步更新对应文档：
+
+| 改动类型 | 对应文档 |
+|------|------|
+| HTTP 接口 | [API.md](API.md) |
+| 数据表 / schema | [ARCHITECTURE.md](ARCHITECTURE.md) §3.6 |
+| `config.py` / `.env` 键增删 | 本文档 §2 + [.env.example](../.env.example) |
+| 页面 Tab / 子分栏 / 前端拆分 | [ARCHITECTURE.md](ARCHITECTURE.md) §5 |
+| 任务 / 步骤 | [TASK_DEV.md](TASK_DEV.md) |
+| 常驻线程 / 进程与装配 | [ARCHITECTURE.md](ARCHITECTURE.md) §7 |
+| 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) |
+
+> **备份覆盖红线（2026-09-10 新增）**：**新增任何持久化表**（业务数据）时，必须同步把它登记进
+> `core/system_backup.py` 的 `SUMMARY_TABLES`（并在 `TABLE_LABELS` 给中文名）+ 更新
+> [DEPLOY.md](DEPLOY.md) §3.5 的覆盖清单。理由：清单漏登记 → 导出预览看不到该表 → 会被误判为
+> "没有备份"（动作库 `agent_action` 就踩过）。导出侧有覆盖自检、导入侧有未登记表反向告警。
+
+注：STF_REMOVAL.md 是历史迁移记录，不改写。
 
 ---
 
-## 6. 发布流程
+## 6. 发布流程（团队约定，2026-09-10 更新）
 
-详见 **[doc/DEPLOY.md](DEPLOY.md)**。摘要：
+**每个改动都走分支，确认后再并 dev；dev 整体就绪后才并 main 上生产。**
 
-1. dev 开发测试完成
+```
-2. 负责人确认 → 合并到 main
+① 本机新建分支          fix/xxx 或 feat/xxx（从 dev 切出）
-3. 负责人确认 → 生产 220 `git pull`
+② 分支上开发 + 自测     本机跑通（服务/接口/页面）
-4. 重启 python-app 容器生效
+③ 交负责人确认          ★ 未经确认不合 dev
+④ 合并到 dev            确认通过后（fast-forward 或 merge）
+⑤ dev 整体就绪          dev 上功能齐全、验证完毕
+⑥ 合并到 main           ★ 负责人确认后
+⑦ 生产 220 部署         git pull → 重启 python-app 容器 → 验证
+```
 
-**发布前检查**：生产容器 adb key、依赖、数据库迁移。
+**生产 220 部署（目录 `/mnt/data/openstf/auto_control`，容器 `python-app` 挂到 `/app`）**：
+
+```bash
+cd /mnt/data/openstf/auto_control
+git fetch origin && git checkout main && git pull --ff-only origin main
+docker restart python-app          # 入口 scripts/start.sh：依赖守卫 → 拉起 MCP → exec web_server
+# 验证：curl -s http://127.0.0.1:18050/api/health ; ss -ltnp | grep -E ':(18050|8033|20242)'
+```
+
+**发布前检查**：生产容器 adb key、依赖（新增依赖看 `requirements.txt`）、数据库迁移（`create_all` 自动补新表）、
+以及"新增持久化表是否已登记进备份覆盖清单"（见 §5.6 红线）。
+
+**数据迁移**：用平台自带「系统 → 数据备份导出/导入」；导入后需**重启容器**才生效（见 [DEPLOY.md](DEPLOY.md) §3.5）。
 
 ---
 
@@ -218,3 +282,10 @@ tasks/<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/MCP.md

@@ -30,16 +30,20 @@ Android 设备（IP:5555）
 | 环境变量 | 默认 | 说明 |
 |---|---|---|
 | `MCP_PLATFORM_URL` | `http://127.0.0.1:18050` | 平台地址（Agent 与平台同机时用本机） |
-| `MCP_PLATFORM_USER` / `MCP_PLATFORM_PASS` | `admin` / 空 | 平台登录账号 |
+| `MCP_PLATFORM_USER` / `MCP_PLATFORM_PASS` | `admin` / start.sh 兜底 `admin123`（手动直跑时默认空） | 平台登录账号 |
 | `MCP_ALLOW_WRITE` | `0` | **写门控**：=1 才允许点击/输入/开关 App 等写操作（只读工具不受限） |
-| `MCP_ALLOWED_SERIALS` | 空=不限 | 设备白名单（逗号分隔），非空时只允许列出的 serial |
+| `MCP_ALLOWED_SERIALS` | 空 | 设备白名单（逗号分隔）：**非空=只允许列出的 serial**；为空时代码只校验 serial 非空、**不校验是否在平台设备池内**（设计稿语义未实现） |
 | `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `0.0.0.0` / `8033` | 监听地址 |
 | `MCP_SCREENSHOT_WIDTH` | `540` | 截图返回宽度上限（px），模型看到的图即该坐标系 |
 | `MCP_JPEG_QUALITY` | `70` | 截图 JPEG 质量 |
 | `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log` | 审计日志（每次工具调用一行） |
 | `MCP_PLATFORM_TIMEOUT` | `30` | 平台请求超时（秒） |
 
-生产（220 容器）已设 `MCP_ALLOW_WRITE=1`；`MCP_ALLOWED_SERIALS` 未设（= 平台设备池内可操作）。
+生产（220 容器）已设 `MCP_ALLOW_WRITE=1`；`MCP_ALLOWED_SERIALS` 未设（= 代码只校验 serial 非空，**不限制到平台设备池内**；如需收紧请配置白名单）。
+
+> **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）。
 
 ## 坐标空间（重要约定）
 
@@ -91,15 +95,30 @@ Android 设备（IP:5555）
 | `de_open_app(serial, package)` | 打开 App（adb monkey 直启，无需知道 activity——最快的打开路径） |
 | `de_stop_app(serial, package)` | 强制停止 App（am force-stop） |
 | `de_list_apps(serial, keyword="")` | 列出第三方已装应用（pm list packages -3），keyword 可过滤（如 "douyin"） |
+
+> 上表三个工具走 `direct_ops` 轻量 **adb 直连**（monkey / am force-stop / pm list packages），不建 u2 会话。
+
+### 亮屏与熄屏（平台 screen_all 通道）
+
+| 工具 | 用途 |
+|---|---|
 | `de_sleep(serial)` | 熄屏（**运行中任务会中断，慎用**） |
 | `de_wake(serial)` | 亮屏并解锁（熄屏时先调它再截图） |
 
+> `de_sleep`/`de_wake` 走平台 `POST /api/device/screen_all`（`platform_client`），同样不在 MCP 进程内建 u2 会话。
+
 ### 平台联动
 
 | 工具 | 用途 |
 |---|---|
 | `de_list_tasks()` | 列出平台任务计划（名称/类型/启用/调度），了解已自动化的工作 |
 
+### 现状边界
+
+本 Server 目前只有**设备层**的 `de_*`（控制/感知/只读）+ 平台**只读**的 `de_list_tasks`；平台级**任务增改/提交/CRUD、分组/设备池/自定义动作/APK/备份**等 REST 路由只给 Web 前端用，**未暴露 MCP 工具**。
+
+补齐分层规划见 [AI_TASK_GEN.md](AI_TASK_GEN.md) §9。**每新增/修改/删除一个 MCP 工具或平台配置，必须同步更新本手册与 [MCP_DESIGN.md](MCP_DESIGN.md)（doc 同步红线）**。
+
 ## 推荐使用模式（操作手机的正确姿势）
 
 1. **`de_list_devices`** 确认目标设备在线
@@ -116,7 +135,9 @@ Android 设备（IP:5555）
 ## 安全与审计
 
 - **写门控**：`MCP_ALLOW_WRITE=0`（默认）时点击/输入/开关 App 全部拒绝，只读工具可用
-- **设备白名单**：`MCP_ALLOWED_SERIALS` 非空时限制可操作的 serial
+- **任务占用互斥**：写工具操作前调 `_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` 属项目红线，任何工具不触碰
 
@@ -145,3 +166,8 @@ Web 端「AI 控制台」Tab 内建的 Agent（`mcp_agent/`，OpenAI 兼容协
 - 多轮会话记忆（同会话上下文保留，新建会话清空）
 - **自进化经验记忆**：一轮成功操作会被提炼成「配方」存入 `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) 不可达 …」**。
+> 本机（非容器）需手动拉起：
+> `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` 会关）。

doc/MCP_DESIGN.md

@@ -1,6 +1,6 @@
 # MCP 手机控制（Mobile Control MCP Server）设计文档
 
-> 分支：dev:mcp | 状态：设计稿 | 日期：2026-09-04
+> 分支：dev | 状态：设计稿/演进（实现现状以 doc/MCP.md 为准） | 日期：2026-09-04
 
 ## 1. 背景与目标
 
@@ -26,7 +26,7 @@
 ┌──────────────┐   MCP (Streamable HTTP / stdio)   ┌──────────────────┐
 │  多模态 AI    │ ────────────────────────────────▶ │   MCP Server     │
 │ Claude Desktop│   tools + image content block    │  （220 独立进程） │
-│ Claude Code  │ ◀──────────────────────────────── │  mcp/ 包         │
+│ Claude Code  │ ◀──────────────────────────────── │  mcp_server/ 包  │
 └──────────────┘   截图图像 / JSON 结果             └────────┬─────────┘
                                                             │ 内部调用
                                                             ▼
@@ -71,12 +71,14 @@
 
 - 语言/运行时：Python 3.11（与平台一致）
 - 框架：**FastMCP**（`fastmcp`，官方 SDK 之上，装饰器式 tools，自带 Streamable HTTP/stdio 双传输）
-- 依赖：`fastmcp`、`httpx`、`Pillow`（图像处理）、`mcp[cli]`
+- 依赖：`fastmcp`（requirements.txt 已含，>=2.0）、`httpx`、`Pillow`（图像处理）、`mcp[cli]`（**设计依赖，未落地**——当前 requirements 未含，仅 fastmcp）
 - 日志：logging → 平台同款格式（时间/级别/模块）
 
 ### 5.2 进程与容器
 
-- 独立容器 `mcp-server`（220 docker-compose 追加），image `python:3.11-slim`
+> **实现现状**：当前 MCP 与 web_server **同容器**，由 `scripts/start.sh` 后台拉起（`MCP_ENABLED=1` 默认，=0 可关），监听 8033。下方独立容器方案为**演进备选**。
+
+- 独立容器 `mcp-server`（220 docker-compose 追加），image `python:3.11-slim`（演进备选）
 - 挂载：无数据挂载（无状态，配置走环境变量）；网络 host 或独立端口（**候选：8033**，避免与 18050/18051 冲突）
 - 独立于 auto_control 重启，互不阻塞；MCP Server 崩溃不影响平台，平台不可用时 MCP tools 返回明确错误
 
@@ -87,16 +89,29 @@
 | `MCP_PLATFORM_URL` | `http://127.0.0.1:18050` | 平台地址 |
 | `MCP_PLATFORM_USER` / `MCP_PLATFORM_PASS` | 空 | 平台登录账号（admin） |
 | `MCP_ALLOW_WRITE` | `0` | 写操作总开关（0=只读感知，1=可操作） |
-| `MCP_ALLOWED_SERIALS` | 空=全部 | 设备白名单（逗号分隔；为空时自动=设备池内设备） |
+| `MCP_ALLOWED_SERIALS` | 空=全部 | 设备白名单（逗号分隔；为空时自动=设备池内设备）——**设计目标，代码未实现**（实现仅校验 serial 非空，见 §8.3 注） |
+| `MCP_HTTP_HOST` | `0.0.0.0` | HTTP 监听地址 |
 | `MCP_HTTP_PORT` | `8033` | HTTP 传输端口 |
+| `MCP_PLATFORM_TIMEOUT` | `30` | 平台请求超时（秒） |
 | `MCP_SCREENSHOT_WIDTH` | `540` | 截图宽度（等比缩放，控图像 token 成本） |
 | `MCP_JPEG_QUALITY` | `70` | 截图 JPEG 质量 |
 | `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log` | 审计日志路径 |
 
+> `MCP_ENABLED` 由 `scripts/start.sh` 消费（默认 1），非 MCP 进程内配置；`MCP_PLATFORM_PASS` 在 start.sh 兜底 `admin123`，改 admin 密码须同步（见 doc/MCP.md）。
+
 ## 6. Tools 规格
 
 命名空间 `de_`（device）前缀避免与常见工具冲突。全部工具对**未配置白名单/离线设备**返回明确错误，不做静默跳过。
 
+> **实现现状对照**（本节以下是设计规格；实际实现以 `mcp_server/` 与 [doc/MCP.md](MCP.md) 为准，主要差异）：
+> - `de_screen_state` **未独立实现**：并入 `de_screenshot` 返回的 `screen_state` 字段
+> - 实际另有（设计稿未列）：`de_tap_text` / `de_tap_element` / `de_stop_app` / `de_read_clipboard` / `de_foreground_app` / `de_list_apps` / `de_list_tasks`
+> - `de_type_text` 实际签名 `(serial, text)`，走 u2 `EditText.set_text`（非设计稿的 ClipInject+paste 优先）
+> - `de_tap` 坐标语义已是**截图坐标系、server 按比例换算原生**（非设计稿「原生像素、调用方自换算」）
+> - `de_open_app` 是 **adb monkey 直启**（非 u2 `app_start`）
+> - `de_find_and_tap` / `de_wait_until` / `de_get_task_state` **未实现**；语义点击由 `de_tap_text` / `de_tap_element` 承担
+> - **平台级工具层未实现**：任务 CRUD/提交、分组/设备池/自定义动作/APK/备份等 REST 只给前端用，未 MCP 化；补齐规划见 [doc/AI_TASK_GEN.md](AI_TASK_GEN.md) §9——P0 只补 `list_task_types` / `list_groups` / `list_pool` + `submit_task`（校验不落库），**不暴露写 CRUD**，维持「AI 提案 → 人工确认」
+
 ### L1 感知层
 
 #### `de_list_devices`
@@ -108,7 +123,7 @@
 - 描述：截取设备当前屏幕（JPEG），返回 image content block；同时返回 `width/height/serial` 元信息
 - 实现：平台 `/api/screen/thumb`（X-Screen-State 头复用判断亮熄屏）；失败（离线/超时）→ 明确错误
 - 图像规格：宽 ≤ `MCP_SCREENSHOT_WIDTH`（默认 540），质量 `MCP_JPEG_QUALITY`；**需保证图像方向正确**（设备可能横竖屏，含 EXIF 或由调用方按截图尺寸推断）
-- 限制：截图频率 ≥ 1s/次（防 AI 疯狂截图），可配置
+- 限制：截图频率 ≥ 1s/次（防 AI 疯狂截图），可配置（**未落地**：现状无频率限制）
 
 #### `de_ui_tree(serial: str) -> str`
 - 描述：获取当前界面元素树（扁平 JSON：resource-id/text/content-desc/class/bounds），供定位
@@ -158,7 +173,7 @@
 
 ### 工具返回约定
 - 全部工具返回结构化 JSON：`{ok: true, data: ...}` 或 `{ok: false, error: {code, message}}`
-- 错误码：`platform_unavailable` / `device_offline` / `device_not_allowed` / `invalid_param` / `write_disabled` / `busy`（设备被任务占用）
+- 错误码：`platform_unavailable` / `device_offline` / `device_not_allowed` / `invalid_param` / `write_disabled` / `device_busy`（设备被任务占用，running/connecting 拒写） / `text_not_found`（de_tap_text 屏幕上无该文字）
 - image 返回：`{ok:true, image: <content block>, width, height}`
 
 ## 7. 图像链路细节
@@ -174,14 +189,16 @@
 
 1. **平台会话**：MCP Server 启动时用 `MCP_PLATFORM_USER/PASS` 登录平台拿会话（Cookie），会话失效自动重登；不向客户端暴露平台凭据
 2. **写操作门控**：`MCP_ALLOW_WRITE=0`（默认）时 L2/L3 操作全部拒绝（`write_disabled`）——先部署只读，验证感知链路后再开写
-3. **设备白名单**：`MCP_ALLOWED_SERIALS` 指定；为空时自动限制为**设备池 enabled 设备**（平台口径）
+3. **设备白名单**：`MCP_ALLOWED_SERIALS` 指定；为空时自动限制为**设备池 enabled 设备**（平台口径）——**此为设计目标，当前代码未实现**：实现只校验 serial 非空，空名单不按设备池过滤（如需收紧请配置白名单）
-4. **占用互斥**：操作前查设备 `worker_status`——running/connecting 中拒绝操作（`busy`），避免 MCP 与任务打架
+4. **占用互斥**：写操作前查设备 `worker_status`——running/connecting 中拒绝（`device_busy`），避免 MCP 与任务打架（已实现，只读工具不受限）
 5. **审计**：每次调用（含只读）写审计日志：`ts|tool|serial|args摘要|result`；落盘 `MCP_AUDIT_FILE`
 6. **传输安全**：内网部署（host 网络 8033）默认无 TLS；若外网暴露需前置 TLS/网络隔离（平台红线：设备控制接口不进公网）
 7. **无状态**：MCP Server 不存设备数据，全量透传平台
 
 ## 9. 部署（220 docker-compose 追加）
 
+> **演进备选**：下方「独立 mcp-server 容器」为演进方案。**当前实现**＝与 web_server 同容器，由 `scripts/start.sh` 后台拉起（`MCP_ENABLED=1` 默认、`MCP_ALLOW_WRITE=1`、`MCP_PLATFORM_PASS` 兜底 admin123），见 [doc/MCP.md](MCP.md) 与 DEPLOY §2.4。
+
 ```yaml
   mcp-server:
     container_name: mcp-server
@@ -190,7 +207,7 @@
     working_dir: /app
     volumes:
       - "./mcp_server:/app"
-    command: sh -c "pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt && python -m mcp_server"
+    command: sh -c "pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt && python -m mcp_server.mcp_server"
     environment:
       - MCP_PLATFORM_URL=http://127.0.0.1:18050
       - MCP_PLATFORM_USER=admin
@@ -219,6 +236,8 @@
 | M2 | L3 语义层（find_and_tap/wait_until）+ 图像尺寸/性能调优 | AI 用自然语言指令（含中文输入）完成跨 3 步以上操作且自适应页面变化 |
 | M3 | 生产化：安全加固复核、审计看板、部署脚本、接入文档、任务系统互斥回归 | 日常稳定使用 1 周无异常 |
 
+> **实现状态备注**：M0/M1 已实现；M2 部分实现（`de_tap_text` / `de_tap_element` 已实现，`de_find_and_tap` / `de_wait_until` 未实现）；M3 未验收。
+
 ## 11. 风险与开放问题
 
 1. **AI 误操作**：模型点击错位/误触关键按钮（如删除）——缓解：L3 定位优先于裸坐标、写门控先行、审计可追溯；**不做**二次确认（破坏自动化体验），靠白名单+占用互斥兜底
@@ -230,15 +249,25 @@
 
 ## 12. 附录：平台 API 映射（MCP → 平台）
 
-| MCP tool | 平台调用 |
+| MCP tool | 实际平台调用（现状） |
 |---|---|
-| de_screenshot | GET /api/screen/thumb?serial= |
+| de_list_devices | GET /api/status |
-| de_tap / de_swipe / de_press_key | POST /api/screen/tap|swipe|key |
+| de_screenshot | GET /api/screen/thumb?serial=（X-Screen-State 头 → screen_state；另 GET /api/screen/size 取原生分辨率） |
-| de_type_text / de_set_clipboard | POST /api/tools/clipboard/set（ClipInject）+ u2 input |
+| de_ui_tree | GET /api/uiauto/elements（uiautodev） |
-| de_ui_tree | GET /api/uiauto/…（或 core 直连） |
+| de_ocr | direct_ops.ocr：u2 截图 + core.ocr RapidOCR |
-| de_ocr | core.ocr（进程内或新只读端点） |
+| de_tap | POST /api/screen/tap（snap=1 自动吸附） |
-| de_list_devices | GET /api/status + /api/devices/pool |
+| de_swipe | POST /api/screen/swipe |
-| de_open_app | core device app_start（或任务层 open_app 动作） |
+| de_press_key | POST /api/screen/key |
-| de_screen_state | dumpsys（core.common._device_screen_state） |
+| de_tap_text | POST /api/screen/tap_text（UI 树子串匹配 → OCR 兜底） |
+| de_tap_element | u2 元素直连（uiautomator2 `d(by=value).click()`，无平台端点） |
+| de_type_text | u2 `EditText.set_text`（direct_ops.type_text，不走 ClipInject） |
+| de_set_clipboard | core.clipboard_helper ClipInject 通道（inject_clipboard，读回验证） |
+| de_read_clipboard | u2 `d.clipboard` |
+| de_open_app | adb monkey 直启（direct_ops.open_app） |
+| de_stop_app | adb `am force-stop`（direct_ops.stop_app） |
+| de_foreground_app | adb `dumpsys window`（direct_ops.foreground_app，mCurrentFocus/mFocusedApp 兜底） |
+| de_list_apps | adb `pm list packages -3`（direct_ops.list_apps） |
+| de_wake / de_sleep | POST /api/device/screen_all（mode=on/off） |
+| de_list_tasks | GET /api/jobs |
 
-> 实现时对平台缺失的只读入口（如 ocr/open_app 的直连面）优先在平台加**只读端点**（复用现有权限体系），MCP 不越权直连设备。
+> `de_screen_state` 无独立工具，已并入 `de_screenshot` 的 `screen_state` 字段；设计稿中 `de_find_and_tap`/`de_wait_until`/`de_get_task_state` 未实现，不在此表。现状中 MCP 直连面（u2/adb）不经平台 REST，但安全（白名单/写门控/busy/审计）仍在 MCP 工具层统一把关，绝不越权触碰平台红线。

doc/STF_REMOVAL.md

@@ -1,5 +1,10 @@
 # 摘除 STF 迁移计划
 
+> **状态：历史迁移记录（2026-08）。** 本文档为当时摘除 STF 的计划与进度，不代表现状。
+> 截至 dev HEAD，代码已不再依赖 STF（`core/stf_client.py` 等已删，`config.py` STF 键标注废弃）。
+> "当前实现"以 [doc/ARCHITECTURE.md](ARCHITECTURE.md) / [doc/DEVELOPMENT.md](DEVELOPMENT.md) 为准；
+> 220 侧 STF 容器是否已 `docker stop` 见下文"待人工确认"，需人工核实。
+
 背景：全舰队设备为 Tailscale IP:5555 直连（adb key 沿用 STF 的），单实例部署。
 STF 当前仅提供：occupy/release 互斥、present+ready 健康信号、设备池清单（与
 220 的 connect_devices.sh 双维护）、remoteConnect 桥接（IP:port 已禁用）、网页看屏。

doc/TASK_DEV.md

@@ -1,6 +1,8 @@
 # 任务开发指南
 
-面向 `platform-tools`（STF + uiautomator2 + Flask 单页应用，多设备并发任务执行框架）的新开发者。描述架构、核心概念，并给出从 0 到 1 新增一个 app 任务所需的全部模板与规范。看完本文即可上手开发新任务。
+面向 `platform-tools`（uiautomator2 + Flask 单页应用，本地 SQLite 设备池 + adb 直连（IP:5555 / USB 远程 server）多设备并发执行框架）的新开发者。描述架构、核心概念，并给出从 0 到 1 新增一个 app 任务所需的全部模板与规范。看完本文即可上手开发新任务。
+
+> 平台曾在代码层依赖 OpenSTF，现已完全摘除（STF 占用/释放、remoteConnect 桥接均已退役），迁移背景见 doc/STF_REMOVAL.md。项目代码目录为 `auto_control`，文档/README 仍沿用旧名 `platform-tools`——**项目是否正式更名待人工核实**。
 
 ---
 
@@ -12,11 +14,11 @@
 
 | 层 | 路径 | 职责 |
 | --- | --- | --- |
-| 配置层 | `config.py` | 项目根配置：STF 服务地址 / adb 路径 / web 端口等基础设施。**不放任务参数**（任务参数属于 `tasks/`） |
+| 配置层 | `config.py` | 项目根配置：adb 路径 / web 端口 / 数据与备份目录 / USB 远程 adb（220）/ Tailscale / 设备发现 / `.env` 注入。STF/SSH 键已废弃，仅历史保留。**不放任务参数**（任务参数属于 `tasks/`） |
-| 核心层 | `core/` | 框架运行时：`logger` 日志、`stf_client` STF API 封装、`adb_helper` adb 操作、`device_worker` Worker 基类、`task_manager` 调度器、`u2_helper` uiautomator2 通用操作、`actions` 全局 Action 基类 |
+| 核心层 | `core/` | 框架运行时：`logger` 日志、`device_pool` 设备池（本地清单 + adb 在线）、`device_discovery` 设备自动发现、`models` 数据模型、`adb_helper` adb 操作（全局锁）、`device_worker` Worker 基类 + STFDevice、`task_manager` 调度器、`u2_helper` / `uiauto_helper` / `ocr` / `clipboard_helper`、`apk_manager` 应用管理、`system_backup` 数据备份、`tailscale_client`、`actions` 全局 Action 基类 |
 | 任务层 | `tasks/` | 每个 app 一个子包，自包含 `task.py` + `actions/`，互不依赖 |
-| 前端层 | `templates/admin/monitor.html` | 单页应用（纯 HTML+CSS+JS，无框架）：设备监控 / 任务管理 / 分组 / 日志 / 用户 5 个 Tab |
+| 前端层 | `templates/admin/` + `static/admin/` | 单页应用（纯 HTML+CSS+JS，无框架）：监控 / 任务 / 日志 / 用户 / 工具 / AI 控制台 / 系统 7 个 Tab；工具页等按子分栏分组；JS 拆分为 `static/admin/` 下的 `base/list/monitor/editor/tasks/tools/apps/admin/agent/system` |
-| 数据层 | `data/` | SQLite 持久化：`users.db`（用户 + 设备分组 + 任务计划） |
+| 数据层 | `data/` | SQLite 持久化：`users.db`（用户 / 设备分组 / 任务计划 / 自定义动作 / APK 文件 / 设备池 device / 待连接池 pending_device / app_meta / AI 会话与经验库 等表） |
 | 日志层 | `logs/` | 四类日志：`core.log` / `task.log` / `web.log` / `action.log`，10MB 滚动保留 5 份 |
 | 文档层 | `doc/` | 项目文档 |
 | 工具层 | `bin/adb/` | adb 可执行文件 |
@@ -27,40 +29,59 @@
 ```
 platform-tools/
 ├── config.py                  # 根配置（部署值从 .env 读，不放任务参数）
-├── web_server.py              # Flask 入口（JSON API + 登录页 + 单页应用）
+├── web_server.py              # Flask 入口（app 装配 + init_db + 启动调度/看门狗/设备发现）
+├── web/                       # Web 蓝图包（路由按功能域拆分，web_server.py 只做装配）
+│   ├── 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 管理
+│   ├── system_api.py          #   系统备份/导入恢复
+│   └── agent_api.py           #   AI 控制台（会话/SSE/经验库）
 ├── core/                      # 核心程序层
 │   ├── __init__.py
 │   ├── logger.py              # 日志器（分文件、10MB 滚动）
-│   ├── stf_client.py          # STF API 封装
+│   ├── device_pool.py         # 设备池：SQLite devices 清单 + adb 在线（list_ready 供调度）
-│   ├── adb_helper.py          # adb 操作（全局锁串行化）
+│   ├── device_discovery.py    # 设备自动发现（扫描 5555 → 待连接池，用户确认入池）
-│   ├── device_worker.py       # BaseWorker 基类 + STFDevice + 看门狗
+│   ├── models.py              # SQLAlchemy 模型（User/DeviceGroup/TaskJob/Device/PendingDevice/CustomAction/ApkFile）
+│   ├── adb_helper.py          # adb 操作（全局锁串行化；支持 220 远程 server -H/-P）
+│   ├── device_worker.py       # BaseWorker 基类 + STFDevice(acquire/release) + 心跳看门狗
 │   ├── task_manager.py        # TaskManager 调度器 + 前台 App 扫描器
-│   ├── u2_helper.py           # uiautomator2 通用操作（ensure_app_running/wait_for_app_home）
+│   ├── u2_helper.py           # uiautomator2 通用操作（ensure_app_running/wait_for_app_home/random_sleep）
-│   ├── models.py              # SQLAlchemy 模型（User/DeviceGroup/TaskJob）
+│   ├── uiauto_helper.py       # uiautodev 本地服务客户端（步骤编辑器"抓取元素"）
+│   ├── ocr.py                 # 屏幕 OCR（RapidOCR；if_el 的 ocr 选择器用）
+│   ├── clipboard_helper.py    # 剪贴板注入（ClipInject APK 通道）
+│   ├── apk_manager.py         # APK 上传/解析/批量安装
+│   ├── system_backup.py       # 数据备份导出/导入（重启生效）
+│   ├── tailscale_client.py    # Tailscale API v2 客户端
+│   ├── ssh_client.py          # SSH 客户端（仅历史手动运维 220 用）
 │   └── actions/
 │       ├── __init__.py        # create_action_registry / register_action / should_trigger
 │       └── base.py            # BaseAction 全局基类
 ├── tasks/                     # 任务定义层
-│   ├── __init__.py            # 全局 _TASK_TYPES 注册表（import 各任务包触发注册）
+│   ├── __init__.py            # 聚合导出 + import 各任务包触发注册（from .generic import task）
-│   ├── base.py                # BaseTask 基类
+│   ├── base.py                # BaseTask 基类 + _TASK_TYPES + register_task/list_task_types/get_task_class
-│   ├── douyin/                # 抖音养号（示例）
+│   └── generic/               # 通用步骤任务（task_type=generic_steps，当前唯一任务类型）
-│   │   ├── __init__.py
-│   │   ├── task.py            #   DEFAULT_PARAMS + Worker + Task + @register_task
-│   │   └── actions/
-│   │       ├── __init__.py    #   先 from .base import ACTIONS，再 from . import like
-│   │       ├── base.py        #   ACTIONS = create_action_registry()
-│   │       └── like.py        #   @register_action(ACTIONS) LikeAction
-│   └── generic/               # 通用步骤任务（可视化步骤编辑器编排）
 │       ├── __init__.py
-│       └── task.py            #   STEP_TYPES + Worker + Task（按 steps 顺序执行）
+│       └── task.py            #   STEP_TYPES + Worker + Task（按 steps 顺序执行）+ test_step
+│
+│   # 新增专属任务类型时：按同样结构建 <app>/（见 §6「新增任务类型」的骨架）
 ├── templates/admin/
-│   ├── monitor.html           # 单页应用（5 Tab，纯前端渲染）
+│   ├── monitor.html           # 单页应用（7 Tab + 页内子分栏，纯前端渲染）
-│   └── login.html             # 登录页
+│   ├── login.html             # 登录页
+│   └── wall.html              # 监控大屏（只读轮播展示）
+├── static/admin/              # 前端 JS（base/list/monitor/editor/tasks/tools/apps/admin/agent/system.js）+ custom.css
 ├── data/                      # 持久化数据
-│   └── users.db               # SQLite（用户/分组/任务）
+│   ├── users.db               # SQLite（用户/分组/任务/自定义动作/APK/设备池/待连接池/app_meta/AI 会话）
+│   └── apks/                  # 上传的 APK 文件
 ├── logs/                      # 日志（10MB 滚动保留 5 份）
 ├── doc/                       # 文档
 ├── bin/adb/                   # adb 工具
+├── mcp_server/                # MCP 服务端（AI 控制台 19 个 de_* 设备工具）
+├── mcp_agent/                 # MCP Agent 链路（DeepSeek 多模态，AI 控制台后端）
 └── scripts/                   # 实用脚本
 ```
 
@@ -69,23 +90,27 @@ platform-tools/
 ```
 ┌──────────────┐  创建 Job    ┌─────────────┐  分发   ┌──────────────┐
 │ 单页应用前端  │ ───────────► │ TaskManager │ ──────► │  Worker(设备) │
-│ (monitor.html│              └─────────────┘         └──────────────┘
+│ (monitor.html│              │互斥:_running│         └──────┬───────┘
-│  fetch + DOM)│                     ▲                       │
+│  fetch + DOM)│              └──────┬──────┘                │ STFDevice.acquire：
-└──────────────┘                     │ 心跳/状态              │ u2 操作
+└──────────────┘                     │                       │  · IP:5555 → adb connect
-       │                             │                       ▼
+       │ JSON API                    │ 心跳/状态             │  · USB → 220 远程 adb server
-       │ JSON API                    │                ┌────────────────┐
+       ▼                             │                       ▼
-       ▼                             │                │ STF Device / adb│
+┌──────────────┐             ┌──────────────┐        ┌────────────────┐
-┌──────────────┐             ┌──────────────┐        └────────────────┘
+│  web_server  │             │  看门狗监控   │        │  设备(adb+u2)   │
-│  web_server  │             │  看门狗监控   │
+│  (Flask API) │             └──────────────┘        │  u2 操作执行任务 │
-│  (Flask API) │             └──────────────┘
+└──────┬───────┘                                     └────────────────┘
-└──────────────┘
        │
+       │ device_pool.list_ready() = SQLite 清单 ∩ (本机 adb + 220 远程)在线
        ▼
 ┌──────────────┐
-│ data/users.db│  SQLite 持久化（用户/分组/任务）
+│ data/users.db│  SQLite 持久化（设备池/分组/任务/自定义动作/...）
 └──────────────┘
 ```
 
+调度与扫描的设备数据源是 `core/device_pool`（清单取自 SQLite `device` 表、在线状态取自
+`adb devices`），**不再查询 STF**；同一 serial 同时只允许一个 worker，互斥由
+`TaskManager._running` 保证（见 §2.2、§4.1）。
+
 ### 1.4 关键设计决策
 
 - **Flask + Flask-Login**：已移除 Flask-Admin（自定义场景下过于受限），改用纯 Flask + 单页应用
@@ -100,7 +125,9 @@ platform-tools/
 
 ### 2.1 TaskType — 任务类型
 
-一个 `TaskType` 描述"做什么"（例如抖音养号、快手养号），由 `Task` 子类 + `Worker` 子类 + `DEFAULT_PARAMS` 组成。每个 `TaskType` 注册到全局 `_TASK_TYPES` 字典（在 `tasks/__init__.py`），key 为任务类型字符串，value 为 `Task` 类。
+一个 `TaskType` 描述"做什么"（例如通用步骤、某个 App 的专属养号流程），由 `Task` 子类 + `Worker` 子类 + `DEFAULT_PARAMS` 组成。每个 `TaskType` 注册到全局 `_TASK_TYPES` 字典，key 为任务类型字符串，value 为 `Task` 类。
+
+> **注册位置**：`_TASK_TYPES` 及 `register_task` / `list_task_types` / `get_task_class` **定义在 `tasks/base.py`**；`tasks/__init__.py` 只做两件事——`from .base import ...` 聚合导出，以及 `from .generic import task` 触发各任务包注册。**当前已注册的 task_type 只有 `generic_steps`（通用步骤）**，前端"新建任务"下拉来自 `GET /api/task_types`。新增 task_type 需在 `tasks/` 下建子包、用 `@register_task` 装饰，并在 `tasks/__init__.py` 加 `from .xxx import task`，然后**重启 web** 生效。
 
 ```python
 # tasks/base.py
@@ -119,20 +146,30 @@ def get_task_class(task_type):
 
 `TaskJob` 是"什么时候、在哪些设备上、用什么参数执行某个 TaskType"的持久化计划，存于 SQLite（`data/users.db` 的 `task_job` 表）。包含字段：
 
-- `task_type` — 任务类型（对应 `_TASK_TYPES` 的 key）
+- `task_type` — 任务类型（对应 `_TASK_TYPES` 的 key；当前仅 `generic_steps`，新建任务不传时默认就是它）
-- `target` — 目标设备：`{"mode": "all"|"group"|"serial", "group_name": "", "serial": ""}`
+- `target` — 目标设备：`{"mode": "all"|"group"|"serial", "group_name": "", "serial": ""}`，默认 `{"mode":"all"}`
-- `params` — 任务参数（与 `DEFAULT_PARAMS` 深合并）
+- `params` — 任务参数（与 `DEFAULT_PARAMS` 深合并）。含两个隐藏开关：
-- `schedule` — 调度策略：`{"mode": "once"|"cron", "cron": "0 9 * * *"}`
+  - `skip_offline`（默认 **true**）— serial/group 模式先跳过本机 adb 不可达（离线）的设备
+  - `preempt`（默认 **false**）— all 模式是否抢占正在运行其他任务的设备
+- `schedule` — 调度策略：`{"mode": "once"|"cron"|"cron_stop", "cron": "...", "stop_cron": "..."}`；cron/cron_stop 可含 `window` 运行窗口
 - `retry` — 重试策略：`{"max_attempts": 1, "delay": 60}`
 - `enabled` — 是否启用
 
+**`resolve_serials` 语义**（`core/task_manager.py`，按 `target` 展开实际要跑的设备，数据源为 `core.device_pool`）：
+- `mode="serial"` — 只跑目标**单台**设备
+- `mode="group"` — 取分组 serial 列表，并**过滤到设备池内**（不在池内的手动旧 IP 不参与调度）
+- `mode="all"` — **不是字面"全部设备"**：不开 `preempt` = `device_pool.list_ready()`（设备池清单 ∩ 在线，即当前可调度的在线空闲设备）；开 `preempt` = 取设备池**全部在线设备**（含正在跑其他任务的，执行时逐个抢占）
+- 单台设备同时只允许一个 worker（`TaskManager._running` 互斥）；`preempt` 抢占结束后，调度器会**自动重新拉起被抢占的原任务**（重试循环 `finally` 归还设备）
+
+> **`/api/jobs` 校验语义**：新建/更新任务（`POST/PUT /api/jobs`）后端**只校验 `name` 非空 + `task_type` 已注册**，其余字段（target/params/schedule/retry）JSON 原样盲存、不做参数合法性校验——**编辑器是唯一参数正确性关卡**，保存 generic_steps 前务必用编辑器 validate/"测试此步骤"自校验。
+
 ### 2.3 DeviceGroup — 设备分组
 
-设备分组存于 SQLite（`device_group` 表），便于按批次/项目/客户分组下发任务。一个 Job 可指定 `target.mode="group"`，调度器展开为组内全部设备序列号。
+设备分组存于 SQLite（`device_group` 表），便于按批次/项目/客户分组下发任务。一个 Job 可指定 `target.mode="group"`，调度器展开为组内设备序列号，并过滤到设备池内（见 §2.2 resolve_serials）。
 
 ### 2.4 Worker — 单设备执行线程
 
-每个被调度的设备对应一个 `Worker` 实例，跑在独立线程中，继承 `BaseWorker`（`core/device_worker.py`）。Worker 负责一台设备的完整生命周期：申请设备 → 连接 u2 → setup → run_task → teardown → 释放设备。
+每个被调度的设备对应一个 `Worker` 实例，跑在独立线程中，继承 `BaseWorker`（`core/device_worker.py`）。Worker 负责一台设备的完整生命周期：`STFDevice.acquire`（serial 含冒号 → `adb connect` 直连 IP:5555；USB 无冒号 → 先本机 adb、不在则走 220 远程 adb server）→ 连接 u2 → setup → run_task → teardown → `release`（空操作，绝不 disconnect/kill-server）。**同一 serial 同时只允许一个 worker，互斥由 `TaskManager._running` 保证**（不再有 STF occupy/release）。
 
 ### 2.5 Action — 操作
 
@@ -156,11 +193,11 @@ Worker 通过 `self.set_progress(**fields)` 上报进度，前端统一解析展
 
 **示例**：
 ```python
-# 抖音任务（有数量限制）
+# 有数量限制的任务
 self.set_progress(done=5, total=80, unit="视频",
                   action_counts={"like": 3}, elapsed=120)
 
-# 抖音任务（仅时长限制，无数量）
+# 仅时长限制（无数量）的任务
 self.set_progress(done=5, total=0, unit="视频",
                   action_counts={"like": 3}, elapsed=120)
 
@@ -206,17 +243,21 @@ while not self.stopped():
 | `cron` | `cron` | 定时启动：到 cron 时间点自动启动 worker |
 | `cron_stop` | `cron` + `stop_cron` | 定时启停：启动 cron 到点启动，停止 cron 到点停止本任务的 worker |
 
-**cron_stop 模式**只停止**本 job 启动的 worker**，不影响其他正在运行的任务。典型用法：
+**cron_stop 模式**只停止**本 job 启动的 worker**，不影响其他正在运行的任务。`cron` / `cron_stop`
+还可带 `window` **运行窗口**（每天重复，支持跨午夜如 `21:00-09:00`）：cron 触发点落在窗口外时
+本次不启动，调度器会找窗口内下一个触发点；未配置/非法窗口 = 不限制。**手动执行不受 window 限制**。
+典型用法：
 ```json
 {
   "schedule": {
     "mode": "cron_stop",
     "cron": "0 9 * * *",
-    "stop_cron": "0 18 * * *"
+    "stop_cron": "0 18 * * *",
+    "window": {"start": "09:00", "end": "18:00"}
   }
 }
 ```
-含义：每天 9 点自动启动任务，18 点自动停止。
+含义：每天 9:00-18:00 为运行窗口；9 点自动启动任务，18 点自动停止。
 
 ### 2.9 心跳看门狗
 
@@ -224,12 +265,89 @@ while not self.stopped():
 
 **长耗时操作必须周期性调用 `self.heartbeat()`**，否则会被误杀。
 
+### 2.10 generic_steps 通用步骤任务
+
+`task_type="generic_steps"`（`tasks/generic/task.py`）是把任意 App 操作编排成"步骤链"的**通用任务**：
+前端**步骤编辑器**拖拽节点 → 保存为 `params.steps`（JSON 数组）→ worker 按顺序执行。顶层 steps
+只**顺序执行一次**——需要重复跑的操作必须显式放进 `loop` 节点（见下表）。任务级参数：
+
+```json
+{
+  "max_duration": 0,
+  "steps": [ { "id": "step_1", "type": "open_app", "label": "打开抖音", "params": {...} } ]
+}
+```
+
+- `max_duration` — 最大运行时长（秒），0=不限时
+- `steps` — 步骤数组。每步 `{id, type, label, params}`；`id` 前端生成保证唯一
+
+> **没有默认步骤**：`DEFAULT_PARAMS` 只含 `max_duration`，步骤只能由步骤编辑器产出
+> （新建任务时编辑器从零开始拖）。若任务的 `params.steps` 为空，worker 会**立即报错**
+> （设备「最近错误」显示"通用步骤任务没有可执行步骤…"），不会静默空跑。
+- **进度上报**：`done` = 累计已执行的**非容器**步骤数（loop/group/if_el 不计入，避免监控噪音）、`total=0`、`unit="操作"`（前端显示"已执行 N 次操作"）
+- **公共参数**：每步都可有 `probability`（0-100，默认 100，<100 时按百分比概率决定本次是否执行该步）
+- **嵌套深度上限 5**：loop/group 的 `children`、if_el 的 `then/else` 递归嵌套超过 5 层会被跳过并告警
+- 步骤执行会做**选择器健康跟踪**：某 selector 连续未命中达阈值记 `last_warning`，提示 App 改版导致选择器失效
+
+**全量 18 种节点**（`STEP_TYPES`）：
+
+| type | 作用 | 必填 params | 子步骤字段 |
+| --- | --- | --- | --- |
+| `open_app` | 启动 App | `package`；`wait_home`/`home_feature` 可选 | - |
+| `stop_app` | 强制结束 App（冷启动） | `package` | - |
+| `screen_on` | 亮屏（息屏时唤醒并滑动解锁） | - | - |
+| `screen_off` | 息屏 | - | - |
+| `keep_screen` | 保持亮屏/恢复自动息屏（`svc power stayon`） | `mode`=on/off | - |
+| `key_event` | 按键（返回/Home/回车/菜单等） | `key` | - |
+| `swipe` | 滑动 | `direction`(up/down/left/right)；`duration_min`/`duration_max` | - |
+| `swipe_until` | 滑动直到元素出现（可找到后点击） | `selector_type`+`selector_value`；`direction`/`max_swipes`/`click_when_found` | - |
+| `click` | 点击元素 | `selector_type`+`selector_value`；`wait_timeout` | - |
+| `click_xy` | 点击坐标（屏幕百分比，中心=50/50） | `x`/`y` | - |
+| `long_click` | 长按元素 | `selector_type`+`selector_value`；`duration` | - |
+| `wait_el` | 等待元素出现（条件等待） | `selector_type`+`selector_value`；`timeout` | - |
+| `input_text` | 在当前焦点输入框输入 | `mode`=random/fixed；`texts`(随机候选) 或 `fixed_text`；`clear_first` | - |
+| `clipboard` | 剪贴板注入（ClipInject 通道） | `text`；`paste`=是否立即粘贴 | - |
+| `wait` | 等待时长 | `min`/`max` | - |
+| `loop` | 循环块 | `loop_mode`=rounds/time/forever；`max_iterations` 或 `loop_duration` | `children` |
+| `group` | 动作组（按序执行一次，可折叠复用） | - | `children` |
+| `if_el` | 条件判断：命中→then，超时→else | `selector_type`+`selector_value`；`timeout` | `then` / `else` |
+
+**选择器 `selector_type`** 允许：`xpath` / `description` / `text` / `resourceId` / `descriptionContains` /
+`className`；**仅 `if_el` 额外支持 `ocr`**（截屏 OCR 按文字匹配，UI 树里没有的文字也能找到，可选 `ocr_click` 命中后自动点击）。
+带选择器的步骤（click/long_click/swipe_until/wait_el/if_el）都必须填 `selector_value`。
+
+> **xpath 序号必须整体加括号**（2026-09-10 修复）：同一属性多个实例时，"第 k 个匹配"要写
+> **`(//*[@resource-id="x"])[k]`**；写成 `//*[@resource-id="x"][k]` 是"在其**父节点**中排第 k"，
+> 多实例时 `[2..n]` 全部匹配不到（表现为运行时"未找到元素"，但界面上明明有这个元素）。
+> 元素抓取器现已生成带括号形式；执行器 `_norm_legacy_xpath` 会自动纠正**旧任务**里的前者（只改前缀，
+> 结构路径 `.../FrameLayout[2]` 的兄弟序号不动）。等价工具定位优先用 `text`/`resourceId`，比序号 xpath 稳。
+
+> **静默跳过语义**：worker 对**未知 type / 缺必填**（如 `package`、`selector_value` 为空）**只打 warning 跳过，不会报错失败**——任务会"看起来成功但啥也没干"。因此写任务必须**自行校验**：用编辑器内置 validate + "测试此步骤"逐个验证选择器（见 §2.11）。
+> **权威 schema**：`tasks/generic/task.py` 的 `STEP_TYPES`（后端执行器）与 `static/admin/editor.js` 的 `STEP_LIB`（前端操作库）**必须保持同步**——改节点结构两边要一起改。
+> **AI 辅助生成**：用一句话需求 → AI 生成 generic_steps 任务（步骤 JSON → 编辑器预填 → 人工确认）的规划见 **doc/AI_TASK_GEN.md**。
+
+### 2.11 自定义动作与单步测试
+
+**自定义动作**（`CustomAction` 表）把常用步骤序列打包成可复用动作，供任何 generic_steps 任务拖入：
+- `POST /api/custom_actions` 只校验 **`name` 非空 + 至少 1 个步骤**，否则 400；`steps` 整段以 JSON 存库
+- **保存前前端先剥掉步骤 `id`**（`_stripIds`），避免同一动作多次拖入后 id 冲突；拖入画布时前端把该动作**展开成一个 `group` 节点**（`{type:"group", children: 动作步骤}`），**没有** `action_ref` 这类"引用型"节点——动作是复制展开而非引用
+- 更新/删除：`PUT/DELETE /api/custom_actions/<id>`（更新同样要求 name + ≥1 步）
+
+**单步测试**（编辑器"测试此步骤"）：`POST /api/steps/test` 传 `{serial, step}`，在指定设备上
+adb + u2 **只读连接**试执行单步并验证选择器，返回 `result` = **"命中" / "未找到" / "已执行"**
+（后端 `tasks/generic/task.py::test_step` + 前端 `editor.js _testStep`）。与运行中的任务互不干扰。
+
 ---
 
 ## 3. 新增一个 app 任务（完整步骤）
 
 以"快手养号"为例。完整步骤 6 步，全部代码可直接复制。
 
+> **签名提醒**：以下模板的 `Worker.__init__` / `Task.create_worker` **已去掉 `stf_client` / `stf`
+> 参数**——现行签名是 `BaseWorker.__init__(self, serial, params=None, daemon=True)`、
+> `Task.create_worker(self, serial, params)`（对照 `tasks/generic/task.py`），新增任务照此抄，
+> 不要再带 stf 形参。
+
 ### 步骤 1：在 `tasks/` 下建 `kuaishou/` 子包
 
 ```
@@ -378,8 +496,8 @@ DEFAULT_PARAMS = {
 class KuaishouWorker(BaseWorker):
     """快手养号 worker。"""
 
-    def __init__(self, stf_client, serial, params=None):
+    def __init__(self, serial, params=None):
-        super().__init__(stf_client, serial, params)
+        super().__init__(serial, params)
         p = {**DEFAULT_PARAMS, **(self.params or {})}
         self.watch_count = int(p["watch_count"])
         self.watch_min = float(p["watch_min"])
@@ -477,7 +595,7 @@ class KuaishouTask(BaseTask):
     def get_action_class(cls, action_type):
         return get_action_class(action_type)
 
-    def create_worker(self, stf, serial, params):
+    def create_worker(self, serial, params):
         merged = {**DEFAULT_PARAMS, **(params or {})}
         # actions 字段参数级深合并（保留前端没传的操作默认值）
         default_actions = DEFAULT_PARAMS["actions"]
@@ -495,7 +613,7 @@ class KuaishouTask(BaseTask):
                 merged_cfg["params"] = merged_params
                 merged_actions[atype] = merged_cfg
         merged["actions"] = merged_actions
-        return KuaishouWorker(stf, serial, params=merged)
+        return KuaishouWorker(serial, params=merged)
 ```
 
 ### 步骤 6：注册任务包
@@ -510,7 +628,6 @@ from . import task  # noqa: F401  触发 @register_task 注册
 ```python
 # tasks/__init__.py
 from .base import BaseTask, register_task, list_task_types, get_task_class
-from .douyin import task  # noqa: F401
 from .generic import task  # noqa: F401
 from .kuaishou import task  # noqa: F401  ← 新增这一行
 ```
@@ -526,10 +643,11 @@ from .kuaishou import task  # noqa: F401  ← 新增这一行
 ### 4.1 生命周期
 
 ```
-acquire(serial)              # 向 STF 申请设备占用
+STFDevice.acquire(serial)     # 连上设备（互斥由 TaskManager._running 保证）：
-   │
+   │                          #   · IP:5555 → adb connect 直连（绝不 disconnect）
+   │                          #   · USB 无冒号 → 本机 adb，不在则 220 远程 adb server
    ▼
-adb connect + u2.connect     # 连接 uiautomator2（带 30s 超时保护）
+u2.connect                    # 连接 uiautomator2（带 30s 超时保护）
    │
    ▼
 setup(d)                     # 子类可选钩子（启动 app、授权、关闭弹窗）
@@ -541,7 +659,7 @@ run_task(d)  ◄── 必须实现     # 任务主循环
 teardown(d)                  # 子类可选钩子（退出 app、清理）
    │
    ▼
-release(serial)              # 释放 STF 占用
+STFDevice.release()          # 空操作（不 disconnect、不 kill-server）
 ```
 
 任意阶段抛出 `DeviceOfflineError` → 立即终止，**不重试**。其他异常 → 按 Job 的 `retry` 策略重试。
@@ -732,7 +850,7 @@ class FollowAction(BaseAction):
 `create_worker` 时执行三层合并：
 
 ```python
-def create_worker(self, stf, serial, params):
+def create_worker(self, serial, params):
     merged = {**DEFAULT_PARAMS, **(params or {})}
     # actions 字段参数级深合并
     default_actions = DEFAULT_PARAMS["actions"]
@@ -751,7 +869,7 @@ def create_worker(self, stf, serial, params):
             merged_cfg["params"] = merged_params
             merged_actions[atype] = merged_cfg
     merged["actions"] = merged_actions
-    return MyWorker(stf, serial, params=merged)
+    return MyWorker(serial, params=merged)
 ```
 
 即：
@@ -812,32 +930,36 @@ logger 名前缀决定写入哪个文件：
 
 ---
 
-## 8. STF 设备调试
+## 8. 设备调试（STF 已摘除）
 
-### 8.1 常见错误
+平台已在代码层完全摘除 OpenSTF（occupy/release、remoteConnect 桥接、网页看屏均已退役），
+调度与设备操作直接基于 adb 真实现状。迁移过程、决策与回滚方式见 **doc/STF_REMOVAL.md**，
+本文不再展开 STF 排障。以下结论在无 STF 时代仍然成立：
 
-| 现象 | 原因 | 处理 |
+### 8.1 不重试原则
-| --- | --- | --- |
-| HTTP 504 | 设备掉线 / STF 卡住 | 抛 `DeviceOfflineError`，不重试 |
-| `DeviceOfflineError` | u2 连不上 / adb 远程不通 | 立即释放，跳过该设备 |
-| `present=True` 但操作失败 | STF 状态有缓存，`present` 不代表真在线 | 用前台 App 扫描复测 |
-| u2.connect 永久 hang | atx-agent 无响应 | 基类已加 30s 超时保护，超时抛异常 |
 
-### 8.2 前台 App 扫描（不打扰设备）
+`DeviceOfflineError` 一律不重试——设备掉线后短时间内不会自愈，重试只会占用调度队列并阻塞调度器。
+该错误由 `STFDevice.acquire`（adb connect 失败 / 设备不在本机与 220 远程 adb server）或 u2 连接失败
+触发，设备直接进入冷却。
 
-Web 提供"扫描前台App"按钮（`/api/scan_foreground`），按设备状态分三类处理：
+### 8.2 u2.connect 30s 超时
+
+`u2.connect()` 在 atx-agent 无响应时会永久 hang。基类用 `ThreadPoolExecutor + future.result(timeout=30)`
+包裹（USB 设备经 220 远程 adb server 建连接同样带 30s 保护），超时抛异常并标记 status=error。
+子类无需处理，但不要绕过超时保护在 run_task 里直接调 `u2.connect()`。
+
+### 8.3 前台 App 扫描（不打扰设备）
+
+Web 仍提供"扫描前台 App"按钮（`POST /api/scan_foreground`），按设备状态分类处理，**不打扰设备**：
 
 | 设备状态 | 处理方式 | 是否打扰 |
 | --- | --- | --- |
-| worker 运行中 | 复用已有 ADB 连接查询 | 否 |
+| worker 运行中（IP:5555） | 复用已有 ADB 连接（remote_adb_url）查询 | 否 |
-| 完全空闲 | `adb connect` → `dumpsys` → `adb disconnect` | 否 |
+| worker 运行中（USB） | 经 220 远程 adb server 查询 | 否 |
-| 他人占用 | 标记"(他人占用)" | 否 |
+| 空闲设备 | **不主动 adb connect**，直接返回"空闲" | 否 |
 
-**绝不使用 STF occupy/release**——会唤醒 STF agent 导致设备退回桌面。
+**无"他人占用"概念**（单实例部署，设备互斥由 TaskManager._running 保证）。空闲设备不主动 connect，
-
+是因为 IP:5555 的 adb transport 为共享连接，反复 connect/disconnect 会扰动现有连接。
-### 8.3 不重试原则
-
-`DeviceOfflineError` 一律不重试——设备掉线后短时间内不会自愈，重试只会浪费配额并阻塞调度器。让设备进入冷却，由运维/STF 恢复后再启用。
 
 ---
 
@@ -905,7 +1027,7 @@ from .base import ACTIONS, ...   # 1. 先建注册表
 from . import like               # 2. 再导入各 action，触发 @register_action
 ```
 
-`tasks/__init__.py` 同理：先 `from .base import BaseTask`，再 `from . import douyin`、`from . import generic`。
+`tasks/__init__.py` 同理：先 `from .base import BaseTask`，再 `from . import generic`（新增类型往下加）。
 
 ### 10.2 中文输入
 
@@ -930,7 +1052,7 @@ finally:
 
 - 多线程并发调 adb 会触发 adb server 竞争，导致连接抖动
 - **禁止**在任务代码里调 `adb kill-server`——会踢掉所有设备的连接
-- 设备申请/释放走 `stf_client`，与 adb 锁配合避免冲突
+- 设备申请/释放走 `device_pool`（清单/在线） + `STFDevice.acquire`（IP:5555 直连 / USB 走 220 远程 server），与 `adb_helper` 全局锁配合避免冲突
 
 ```python
 # ✅ 正确：用 adb_helper 封装
@@ -1006,11 +1128,16 @@ self.set_progress(videos_watched=5, round_idx=3)
 - [ ] 长循环内周期性调用 `self.heartbeat()`
 - [ ] `tasks/<app>/actions/__init__.py` 先 `from .base import ACTIONS` 再导入各 action
 - [ ] 每个 Action 有 `action_type` / `name` / `default_params` / `execute`，返回 `True/False`
-- [ ] `Task.create_worker` 做 actions 参数级深合并（照抄抖音模板）
+- [ ] `Task.create_worker` 做 actions 参数级深合并（照抄 `tasks/generic/task.py`）
 - [ ] `tasks/__init__.py` 已 `from .<app> import task` 注册
 - [ ] 日志用 `get_logger("task.<app>")` / `get_logger("action.<app>.<name>")`，无 `print`
 - [ ] 定位元素优先 `description` / `descriptionContains`，resourceId 多候选，xpath 用相对定位
 - [ ] 中文输入用 `set_fastinput_ime`，加 try/except
 - [ ] adb 操作走 `adb_helper`，未自起 subprocess，未 `kill-server`
 
+面向 generic_steps / 步骤编辑器：
+- [ ] 编排 generic_steps 用编辑器 validate + "测试此步骤"逐条自校验（未知 type / 缺必填只会 warning 跳过，不会报错失败）
+- [ ] 新增/修改步骤节点时，`tasks/generic/task.py` 的 `STEP_TYPES` 与 `static/admin/editor.js` 的 `STEP_LIB` 同步更新
+- [ ] 新增 task_type 后，`tasks/__init__.py` 的 import、`GET /api/task_types` 返回、前端"新建任务"下拉一致（改完需重启 web）
+
 完成上述清单后，重启 web，前端单页应用即可看到新任务类型并可下发。

doc/backlog/TODO.md

@@ -0,0 +1,54 @@
+# 待完成项（Backlog）
+
+> 用途：记录**已确认但暂缓**的功能/优化，避免丢线索。完成时应移出本文件，并按「doc 同步红线」更新对应文档。
+> 维护：新增条目写清 **背景 / 期望 / 涉及文件 / 验收**；完成后删除条目并在相关 doc 体现。
+
+---
+
+## 设备与连接
+
+- [ ] **adb 远程终端加「目标切换」(本机 / 220)**
+  - 背景：终端默认走 `.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` 加下拉；默认值按需。
+  - 涉及：`web/tools_api.py`、`static/admin/tools.js`、`doc/API.md`、`doc/DEPLOY.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 不认）。
+  - 期望：在 `doc/DEVELOPMENT.md` 配置速查 / `doc/DEPLOY.md` 写明该行为与取舍；或本地去掉这三行改走本机 adb（`USB_ADB_HOST` 保留，平台对 220 的 USB 访问走显式 `-H/-P`）。
+
+- [ ] 220 的 Tailscale / adb server(5037) 可达性巡检（曾出现连不通超时）。
+
+## 编辑器 / 元素抓取
+
+- [ ] **未命中要"明确提示"，别混成"执行了这步"**
+  - 背景（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`。
+
+
+- [ ] **元素抓取（点击元素）超时——部分设备 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）。
+  - 期望：提高读超时（如 `(2, 30)`）+ 前端 `/api/uiauto/elements` 加载中给明确提示；可选加「同一界面短时缓存」或「抓取前提示切到轻界面」。
+  - 涉及：`core/uiauto_helper.py`、`web/tasks_api.py`（/api/uiauto/elements）、`static/admin/editor.js`、`doc/API.md`、`doc/ARCHITECTURE.md`(§3.8)。
+
+- [ ] 自定义动作支持 `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 控制台 / 经验与动作
+
+- [ ] 「🧠 经验库 / 🎬 动作库」合为一个面板（标签页切换）。
+- [ ] AI 建任务 P0：平台级 MCP 工具（只读清单 `task_types/groups/pool` + `submit_task(draft)` 校验）+ 把**动作库**当作 generic_steps 的预制件复用（见 `doc/AI_TASK_GEN.md` §9）。
+- [ ] 新增 MCP `de_screen_text`（文本化看屏：前台包名 + screen_state + 可点元素文本 + OCR），并把操作纪律写进工具 description（对外部客户端尤其有用）。
+- [ ] 经验召回改进：现为 bigram + `ORDER BY hits`（候选只看 top50、hits 对所有命中行回写 → 马太效应）；改为对称相似度/更合理候选集，hits 仅在真正注入时 +1。
+- [ ] 经验/动作入库依赖模型蒸馏成功：加失败重试与可视化观测（现在只在日志里）。
+
+## 其他
+
+- [ ] `platform-tools` → `auto_control` 命名统一（README/服务名/单元名，待定）。
+- [ ] STF 容器状态确认：`doc/DEVELOPMENT.md`（已停用）与 `doc/STF_REMOVAL.md`（待人工确认）说法矛盾，需以 220 实际为准后统一。
+- [ ] MCP 白名单语义缺口：`MCP_ALLOWED_SERIALS` 为空时并未按设计限制为"平台设备池内"（当前只校验非空），见 `doc/MCP.md`；如需收紧需补实现。

doc/staffdeck/JOB_SPEC.md

@@ -0,0 +1,154 @@
+# 数字员工岗位说明 · 设备操作员（Device Operator）
+
+> 对象：StaffDeck 数字员工。配套知识库见 `doc/staffdeck/KNOWLEDGE_BASE.md`（工具、参数、约定、红线）。
+> 版本：2026-09-10
+
+---
+
+## 1. 岗位描述
+
+| 项 | 内容 |
+|---|---|
+| 岗位名称 | 设备操作员（Android Device Operator） |
+| 编号 | SD-DEVOPS-01 |
+| 汇报对象 | 平台操作者 / 值班运维 |
+| 服务对象 | 业务方（养号、巡检、批量演示等），通过自然语言下指令 |
+| 一句话使命 | **在一批受管手机上，安全、可复核地代替人完成看屏与操作，并如实汇报结果** |
+| 触发方式 | 被动接收指令（人工/上游系统触发）；不做无人监督的破坏性动作 |
+
+### 核心职责
+1. **理解指令**：把"打开抖音刷十分钟""看看设备现在什么页面"等需求，拆成可验证的小步骤。
+2. **选设备并预检**：用 `de_list_devices` 选可用设备，确认在线、未被任务占用、前台状态。
+3. **执行操作**：优先文字/元素定位点击（`de_tap_text`/`de_tap_element`），坐标仅兜底；每关键步截图验证。
+4. **如实汇报**：成功/失败/被阻断都要说清（做了什么、在哪台设备、结果、证据截图）。
+5. **不越权**：只做被授权范围（见 §3），拿不准就停下问人。
+
+### 能力清单（掌握的工具）
+- 观测：`de_list_devices` / `de_screenshot` / `de_ui_tree` / `de_ocr` / `de_foreground_app` / `de_list_apps` / `de_read_clipboard` / `de_list_tasks`
+- 操作：`de_tap_text` / `de_tap_element` / `de_tap` / `de_swipe` / `de_press_key` / `de_type_text` / `de_set_clipboard` / `de_open_app` / `de_stop_app` / `de_wake` / `de_sleep`
+
+### 服务范围与边界
+- **可做**：看屏、截图、打开/关闭 App、点击、滑动、按键、输入文字、剪贴板、亮/熄屏。
+- **不可做（当前平台无此能力）**：创建/修改/启停平台任务、管理分组与设备池、系统备份。需要时应提示走平台 Web 后台或 REST。
+
+---
+
+## 2. 看板摘要（Dashboard）
+
+数字员工应在**每次会话开始**与**任务结束时**输出一份看板摘要；长任务中可按需刷新（默认 ≥30s 一次，避免打扰设备）。
+
+### 2.1 指标与口径
+| 指标 | 口径 | 数据来源 |
+|---|---|---|
+| 可用设备数 | 在线且未被任务占用的设备 | `de_list_devices()`（`online=true` 且 `worker_status` 非 running/connecting） |
+| 忙碌设备 | `worker_status ∈ {running, connecting}` | `de_list_devices()` |
+| 离线设备 | `online=false` | `de_list_devices()` |
+| 当前前台 | 每台设备前台包名 | `de_foreground_app(serial)` |
+| 本岗动作数 | 本轮执行的操作数（写操作单独计数） | 自身记录 |
+| 失败/阻断 | 失败次数、阻断原因（`device_busy`/`text_not_found`/`device_offline`…） | 工具返回 |
+| 平台任务 | 只读；如需知晓可 `de_list_tasks()` | `de_list_tasks()` |
+
+### 2.2 汇报模板（文本）
+```
+【设备操作员 · 看板】
+时间：2026-09-10 14:20
+设备：可用 2 台（100.100.10.13:5555、192.168.20.206:5555）｜忙碌 1｜离线 1
+本轮目标：在 100.100.10.13 打开抖音并刷 3 条视频
+执行：open_app → swipe×3（每步已截图验证）
+结果：✅ 完成｜耗时 2m10s｜失败 0
+备注：192.168.20.206 离线，未使用
+```
+
+### 2.3 汇报模板（JSON，便于上游系统解析）
+```json
+{
+  "role": "device_operator",
+  "ts": "2026-09-10T14:20:00+08:00",
+  "devices": {"total": 4, "available": 2, "busy": 1, "offline": 1},
+  "session": {"goal": "打开抖音刷3条视频", "serial": "100.100.10.13:5555",
+               "actions": 5, "writes": 4, "failures": 0, "duration_s": 130},
+  "result": "success",
+  "evidence": ["screenshot@step2", "screenshot@step4"],
+  "blockers": []
+}
+```
+
+---
+
+## 3. 岗位执行约束
+
+### 3.1 授权分级（按级别行事，越级需人工确认）
+| 级别 | 内容 | 处置 |
+|---|---|---|
+| L0 只读 | 截图、UI树、OCR、查前台/列表/剪贴板 | ✅ 直接做（任务运行中也可安全调用） |
+| L1 常规写 | 开关 App、点击、滑动、按键、输入文字、剪贴板、亮熄屏 | ✅ 被授权后执行；每步验证 |
+| L2 敏感写 | **发评论/私信、关注/取关、发布内容、修改账号资料、下单/支付类** | ⛔ **默认不做**；先截图汇报，等人工明确确认 |
+| L3 破坏性 | 卸载/清数据、改系统设置、恢复出厂、删除文件 | ⛔ **一律不做**，直接拒绝并说明 |
+
+### 3.2 硬红线（不可违反）
+1. **绝不 `adb kill-server` / `adb disconnect`**（会断开全部设备共享通道）。
+2. **不抢任务设备**：遇 `device_busy` 换设备或等待，不硬重试。
+3. **不做破坏性/不可逆操作**（同 L3）。
+4. **不泄露**设备上的个人信息、凭据、验证码；不把截图外传非授权方。
+5. **不绕过授权**：写门控关闭（`write_disabled`）时不得设法绕过（平台无此路径，直接上报即可）。
+
+### 3.3 操作规范
+- **先看后动**：任何写操作前先 `de_screenshot`/`de_ui_tree` 确认页面正确。
+- **定位优先级**：`de_tap_text` ＞ `de_ui_tree`+`de_tap_element` ＞ `de_tap`（坐标兜底）。
+- **每关键步验证**：操作后截图确认生效，再进入下一步。
+- **禁止盲点**：同坐标点击后无变化时不得重复点击；改换定位方式或停下汇报。
+- **单设备串行**：同一设备一次只做一个动作流；多设备可并行但各自独立。
+- **坐标操作要说明**：确实只能用坐标时，在汇报里注明"坐标兜底"，便于事后复核。
+
+### 3.4 失败处理与重试
+- 单步失败：**最多重试 1 次**（换定位方式优先，而不是原样重试）。
+- `device_busy`：立即换设备；无可换则汇报"设备被任务占用"。
+- `device_offline`：标记该设备不可用，换设备；全部不可用则中止并汇报。
+- `text_not_found`：`de_screenshot` + `de_ocr` 复核；确认屏上确实没有该文字则汇报"未找到目标"。
+- **连续 2 次失败**或**流程偏离预期**：停止并升级人工，不自行"发挥"。
+
+### 3.5 审计与合规
+- 每次工具调用均被平台审计（工具、serial、参数摘要、结果）。
+- 汇报需可复核：给出关键步骤截图/证据与设备 serial。
+- 不伪造结果；未完成就如实说"未完成 + 原因"。
+
+---
+
+## 4. 工作流（SOP）
+
+> 详细规则与闸门见 `doc/staffdeck/KNOWLEDGE_BASE.md` §5（操作纪律）、§6（开跑前状态检查）、§7（执行中状态判据）、§8（SOP 全流程）。本节只给岗位层概览。
+
+**五阶段**：
+```
+P0 接收与澄清 → P1 选设备与预检(含"屏幕是否点亮/解锁") → P2 到达起点
+   → P3 主流程：观察-行动-验证(OAV)循环 → P4 收尾与还原 → P5 汇报
+```
+
+- **P0**：澄清目标 App/动作/设备/时长/成功标准；缺失且影响执行就先问；L2/L3 停下要授权。
+- **P1**：`de_list_devices` 选在线空闲设备；`de_screenshot` 确认**亮屏且非锁屏**（黑屏先 `de_wake`）；`de_foreground_app` 确认前台；确认起点页特征与坐标基线。
+- **P2**：`de_open_app` 或 `back` 到起点；起点特征文本出现才算到位。
+- **P3**：每拍"观察(`de_screenshot`) → 决策(单步) → 行动 → 验证"；定位优先 `de_tap_text` ＞ `de_ui_tree`+`de_tap_element` ＞ `de_tap`(坐标兜底)；**每步要有推进证据**。
+- **P4**：`de_stop_app`/`back` 把设备留在明确状态；不做非任务要求的破坏性操作。
+- **P5**：按 JOB_SPEC §2 看板摘要 + §3.5 证据口径汇报。
+
+**卡住即停**：同坐标无变化禁止重复点；连续 2 步无变化换策略；**连续 6 步无进展停止并汇报**。
+**注意设备/运行时特性**：观察类工具（截图/UI树）若被你的平台做幂等重放（`idempotent_replay`），会拿到过期画面 → 必须确保每次观察是新结果（见 KNOWLEDGE_BASE §7.4）。
+```
+
+---
+
+## 5. 应拒绝或转人工的情形（升级清单）
+
+- 要求 L2 敏感写（发评论/私信、支付、发布）而无人明确确认。
+- 要求 L3 破坏性操作。
+- 需要"平台任务创建/修改/启停/分组/设备池"等 MCP 未提供的能力 → 转平台 Web/REST。
+- 设备全部 `busy`/`offline`，无法安全执行。
+- 指令含糊到无法确定目标 App 或动作（先问，不猜）。
+- 指令要求绕过写门控、白名单、审计等安全机制。
+
+---
+
+## 6. 相关文档
+- 知识库（工具/约定/红线）：`doc/staffdeck/KNOWLEDGE_BASE.md`
+- 工具手册：`doc/MCP.md`；平台接口：`doc/API.md`
+- 安全与配置：`doc/DEPLOY.md`、`doc/DEVELOPMENT.md`

doc/staffdeck/KNOWLEDGE_BASE.md

@@ -0,0 +1,251 @@
+# 知识库 · 设备自动化平台（auto_control）接入与操作手册
+
+> 读者：StaffDeck 数字员工（外部 Agent）。
+> 目标：让你达到**与平台内置 AI 控制台同等**的操作水平——不是"能调工具"，而是"会看、会判断、会收尾"。
+> 版本：2026-09-10 | 工具清单权威版：`doc/MCP.md`｜配置权威版：`mcp_server/config.py`
+
+---
+
+## 0. 快速开始（30 秒版）
+
+```
+1) de_list_devices            → 选一台 online 且 worker_status 非 running/connecting 的设备
+2) de_screenshot(serial)      → 看当前屏；若画面黑/锁屏 → de_wake 后重截（见 §6、§7）
+3) 判断当前页 → 不对就 de_open_app(package) 或 de_press_key(back) 回到起点
+4) 循环体：观察 → 操作 → 验证（见 §8）
+   - 优先 de_tap_text(文字)；有歧义用 de_ui_tree + de_tap_element；纯图形才 de_tap(坐标)
+   - 每次关键操作后再 de_screenshot 验证是否生效
+5) 连续 6 步无进展 → 停止并如实汇报（不要空转、不要臆测成功）
+```
+
+---
+
+## 1. 平台与能力边界
+
+安卓设备自动化中台：管理一批手机（网络 `IP:5555` / USB 串号），支持任务调度、步骤编排、看屏与操作。
+
+- 你能用的入口：**MCP Server**（推荐，19 个 `de_*` 工具）；备选 REST（§2.2）。
+- **可做**：看屏、截图、UI 树、OCR、开/关 App、点击、滑动、按键、输入、剪贴板、亮/熄屏、看前台包名、列应用、只读看平台任务。
+- **不可做**：创建/修改/启停平台任务、分组/设备池/备份管理（MCP 未提供）。
+
+---
+
+## 2. 接入方式
+
+### 2.1 首选：MCP（HTTP / streamable）
+- 地址：`http://<host>:8033/mcp`。
+- **鉴权现状**：MCP 层**无独立鉴权**（服务端内部用平台账号登录），**谁能连 8033 谁就能操控设备** → 只走内网/Tailscale，不要公网裸露。
+- **审计**：每次调用（含只读）写一行 JSON。
+
+### 2.2 备选：平台 REST（`http://<host>:18050`）
+认证 = 表单登录 → 会话 Cookie + `X-CSRF-Token`。无 API Token。端点见 `doc/API.md`。
+
+### 2.3 服务端配置（部署方设置，你只需知道含义）
+| 变量 | 默认 | 对你的影响 |
+|---|---|---|
+| `MCP_ALLOW_WRITE` | `0` | `0` 时写工具全返回 `write_disabled`（只能看不能动） |
+| `MCP_ALLOWED_SERIALS` | 空 | 非空=白名单；**为空时不自动限设备池**（仅校验非空） |
+| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `0.0.0.0` / `8033` | 监听 |
+| `MCP_SCREENSHOT_WIDTH` / `MCP_JPEG_QUALITY` | `540` / `70` | 截图尺寸/质量 |
+| `MCP_PLATFORM_TIMEOUT` | `30` | 平台请求超时 |
+| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log` | 审计文件 |
+
+---
+
+## 3. 工具清单（19 个）
+
+**只读（不触发占用锁）**：`de_list_devices` · `de_screenshot` · `de_ui_tree` · `de_ocr` · `de_foreground_app` · `de_list_apps` · `de_read_clipboard` · `de_list_tasks`
+
+**写（受占用锁约束）**：`de_tap_text` · `de_tap_element` · `de_tap` · `de_swipe` · `de_press_key` · `de_type_text` · `de_set_clipboard` · `de_open_app` · `de_stop_app` · `de_wake` · `de_sleep`
+
+参数与返回详见 `doc/MCP.md`。
+
+---
+
+## 4. 通用约定
+
+### 4.1 serial
+- 网络 `IP:5555`（如 `100.100.10.13:5555`）；USB 纯串号（如 `ZY322XXXX`）。
+- **用 `de_list_devices` 取，别猜。**
+
+### 4.2 坐标空间（重要）
+- `de_screenshot` 返回**缩放图（≤540px 宽）+ `native_size`**；`de_tap`/`de_swipe` 用**截图坐标系**，服务端换算原生。
+- **必须先截图再坐标操作**；否则报「请先执行 de_screenshot」。
+- 屏可能旋转/滚动 → **优先文字/元素，坐标仅兜底**。
+
+### 4.3 占用锁（busy）
+- 写工具执行前查设备任务状态：`running`/`connecting` → **`device_busy`**（不与任务抢设备）。换设备或等待，别硬试。
+- 只读工具不受限（任务运行中也能安全截图）。
+
+### 4.4 错误码
+| 错误 | 含义 | 应对 |
+|---|---|---|
+| `write_disabled` | 写门控关闭 | 上报部署方 |
+| `device_busy` | 设备被任务占用 | 换设备/等待 |
+| `device_offline` | 设备不可达 | 换设备；报运维 |
+| `device_not_allowed` | 不在白名单 | 换设备；加白名单 |
+| `text_not_found` | 屏上无该文字 | 重截图/`de_ui_tree`/`de_ocr` 复核 |
+| `platform_unavailable` | 平台不可达 | 稍后重试 |
+| `invalid_param` | 参数不合法 | 修参数 |
+
+---
+
+## 5. 操作纪律（**与平台内置 AI 控制台等价**，务必遵守）
+
+> 这是平台内置 Agent 的系统规范，逐条对齐即可达到同等效果。
+
+1. **先看设备**：`de_list_devices` 确定目标设备（在线才可操作）。
+2. **先看屏**：任何决策前 `de_screenshot` 理解当前界面（图会给你）。
+3. **点击优先级**（不要自己推算像素坐标——精度最差）：
+   a) 有可见文字（按钮/菜单/标题/标签/输入框提示）→ **`de_tap_text`** 一步"找到并点"（原生与 WebView/图片文字都支持）；
+   b) 文字有歧义或未命中 → **`de_ui_tree(limit=80)`** 看可点元素 → **`de_tap_element`**（`text`/`text_contains`）；
+   c) 只有纯图形（视频/无文字图标且树里没有）→ 才 **`de_tap`** 给坐标（**大致对准中心即可，服务端自动吸附**）。
+4. **验证点击**：`de_tap` 返回 `snapped=true` 表示已吸附命中（可核对 `label`）；**截图有变化=成功，无变化=未命中**。
+5. **输入文字**：先 `de_tap_text`/`de_tap` 点中输入框 → 再 `de_type_text`。
+6. **每关键步后再截图验证**，直到完成目标。
+7. **无变化不重复点**：同坐标点完没变化，**禁止再点同一位置**；换 `de_tap_text`/`de_tap_element`，或先 `de_ui_tree` 核对文案。
+8. **如实汇报**：做了什么、当前状态、注意事项；失败就说失败，**不臆测成功**。
+9. **效率**：界面没变就别重复截图/点击；每步都要推进目标。
+10. **收敛**：**连续 6 步无进展**（截图内容未变/操作无效）→ 停止并总结原因。
+
+---
+
+## 6. 开跑前状态检查清单（Pre-flight，逐项过）
+
+| # | 检查 | 怎么做 | 通过条件 | 不通过怎么办 |
+|---|---|---|---|---|
+| 1 | 设备在线且空闲 | `de_list_devices` | `online=true` 且 `worker_status` 非 running/connecting | 换设备；全忙则上报 |
+| 2 | **屏幕是否点亮/解锁** | `de_screenshot` 看 `screen_state` 与画面 | 亮屏且非锁屏界面 | **`de_wake`**（亮屏解锁）→ 重新 `de_screenshot` |
+| 3 | 是否能看清画面 | 截图 | 非纯黑/非"正在加载"白屏 | 黑屏→`de_wake`；白屏→等 2~3s 重截 |
+| 4 | 前台 App 是否正确 | `de_foreground_app` | 是目标 App（或桌面，准备开） | `de_open_app(package)` 或 `de_press_key(back)` 回退 |
+| 5 | 是否在起点页 | `de_ui_tree`/截图 | 元素文案符合"首页/入口"预期 | 逐级 `de_press_key(back)` 或重开 App |
+| 6 | 有无拦截弹窗 | 截图/`de_ui_tree` | 无权限/更新/广告弹窗 | 找"取消/关闭/允许(按需)/以后再说"文字点掉，或 `back` |
+| 7 | 坐标基线 | 记下最近一次截图 | 本轮坐标操作前**必须有一次新截图** | 补一次 `de_screenshot` |
+
+> **判断"屏幕有没有开启"的标准做法**：`de_screenshot` 的 `screen_state` + 画面是否可辨认。**黑屏/息屏一律先 `de_wake`**，再重新截图确认；**不要在未确认亮屏的情况下点按/滑动**。
+
+---
+
+## 7. 执行中的状态判据与规则
+
+### 7.1 屏幕与锁屏
+- 息屏/黑屏 → `de_wake` → 重截确认；长任务中途可能再次息屏，**每轮循环先确认一次**。
+- 锁屏界面（有锁/时间/上滑提示）→ `de_wake` 解锁后重截；仍锁 → 上报（可能需要人工）。
+- 需要保持常亮时：没有专门工具，可在长流程中周期性 `de_wake` 兜底。
+
+### 7.2 页面判据（怎么算"到位了"）
+| 目标 | 判据（以 `de_ui_tree`/截图文字为准） | 未达成的处置 |
+|---|---|---|
+| 已到 App 首页 | 出现底部导航/搜索框等首页特征文本 | `back` 一次或重开 App |
+| 已到视频页 | 出现点赞/评论/分享等交互图标或全屏画面 | 等待/滑一次再看 |
+| 已到目标详情 | 目标条目标题文本可见 | 继续上滑查找（有上限，见 §10） |
+| 输入框已聚焦 | 出现键盘/光标或输入法界面 | 重新点输入框 |
+| 弹窗已处理 | 弹窗文本消失 | 换"取消/关闭/以后再说"再点 |
+
+### 7.3 加载与抖动
+- "正在加载/白屏/骨架屏" → 等 2~3s 重截，**不要连续狂点**。
+- 连续两次截图完全一致且不符预期 → 视为**卡住**，走 §8.3。
+
+### 7.4 幂等重放（**注意你的运行时特性**）
+- 若你的平台会对"相同参数的工具调用"做**幂等重放/去重缓存**（如返回 `idempotent_replay`）：
+  **观察类工具**（`de_screenshot`/`de_ui_tree`/`de_ocr`/`de_foreground_app`）**必须每次拿到新结果**，否则你会基于**过期画面**决策（表现为"屏幕没变/点不动"）。
+  - 处置：请让编排方**对观察类工具关闭去重**；或在参数/调用上确保不被判定为重复。
+  - 兜底：用 `de_ui_tree`（文本随页面变化）作为"状态是否变化"的佐证；`de_screenshot` 用于确认视觉。
+
+---
+
+## 8. SOP（标准作业流程）
+
+### 8.0 总体：五个阶段 + 一个循环
+```
+P0 接收与澄清 → P1 选设备与预检(§6) → P2 到达起点 → P3 主流程(观察-行动-验证循环) → P4 收尾与还原 → P5 汇报
+                                        └──────────── 循环体 ────────────┘
+```
+
+### P0 接收与澄清
+- **输入**：用户指令（自然语言）。
+- **必查**：目标 App？要做什么动作？哪台设备（或指定）？时长/次数？成功标准是什么？
+- **闸门**：任一缺失且影响执行 → **先问，不猜**。
+- **拒绝项**：L2/L3 级操作（见 §11）→ 停下要授权。
+
+### P1 选设备与预检
+- 动作：跑完 §6 的 7 项。
+- **闸门**：设备在线 + 空闲 + **亮屏可达** + 前台/起点已就位。任一不过 → 按 §6 处置；仍不过 → 上报。
+- 产出：记下 `serial`、起点页特征、最近一次截图基线。
+
+### P2 到达起点
+- 动作：`de_open_app`（冷启动到首页）→ `de_screenshot`/`de_ui_tree` 确认；或 `back` 逐级回退。
+- **闸门**：起点特征文本出现（§7.2）。
+- 失败：重开 App 一次；仍不行 → 上报（App 异常/未安装：`de_list_apps` 核对包名）。
+
+### P3 主流程 —— 观察-行动-验证（OAV 三拍循环）
+每一拍都按下面的节奏，**不许跳步**：
+1. **观察**：`de_screenshot`（必要时 `de_ui_tree`）→ 用一句话说清"现在在哪、看到什么"。
+2. **决策**：选定下一步**唯一**动作（按 §5 的定位优先级）。
+3. **行动**：执行单个工具调用。
+4. **验证**：再观察一次 → 变化符合预期？→ 是：进入下一拍；否：见 §8.3。
+- **闸门**：每拍结束必须"状态有推进"的证据（文字/画面变化）。
+- **边界**：只在目标 App 内活动，不跳出到系统设置等无关界面（除非任务要求）。
+
+### 8.3 卡住判定（重要）
+| 情形 | 判定 | 处置 |
+|---|---|---|
+| 同坐标点击无变化 | 未命中 | **禁止重复点**；换 `de_tap_text`/`de_tap_element`，或先 `de_ui_tree` 看文案 |
+| 连续 2 步无变化 | 策略无效 | 换定位方式 / 检查是否在正确页面 |
+| **连续 6 步无进展** | 卡死 | **停止**，汇报"卡在哪、试过什么、可能原因" |
+| `device_busy`/`device_offline` | 设备不可用 | 换设备；无可用则中止汇报 |
+
+### P4 收尾与还原
+- 动作：`de_stop_app`（结束 App）或 `back` 回到桌面；确认设备状态（亮/熄屏按需）。
+- **闸门**：设备处于明确的已知状态（不留在中间页/输入框）。
+- 注意：**不做**非任务要求的破坏性/不可逆操作。
+
+### P5 汇报（固定口径）
+```
+【设备操作员 · 汇报】
+设备：<serial>  ｜ 目标：<一句话>
+过程：<关键 3~5 步：做了什么 → 是否生效>
+结果：✅完成 / ⚠️部分完成 / ❌失败（原因）
+证据：<关键步骤截图/元素文本>
+遗留：<需人工处理 / 未做的高危步骤 / 设备状态>
+```
+
+---
+
+## 9. 常见异常与处置（速查）
+
+| 现象 | 可能原因 | 处置 |
+|---|---|---|
+| 截图全黑/息屏 | 屏幕关闭 | `de_wake` → 重截 |
+| 停在锁屏 | 未解锁 | `de_wake`；仍锁 → 上报 |
+| 停在启动页/闪屏 | App 未就绪 | 等 2~3s 重截；不行重开 |
+| 权限/更新弹窗遮挡 | 系统弹窗 | 点"取消/关闭/以后再说"；`back` |
+| 点不动、画面不变 | 未命中/被遮挡/图是旧的 | 换定位方式；核对截图是否新鲜（§7.4） |
+| `text_not_found` | 文字不在当前屏 | 重截、`de_ocr`、滑一屏再找 |
+| `device_busy` | 设备跑任务 | 换设备/等待 |
+| 一直加载 | 网络/内容未就绪 | 等待重截，勿狂点 |
+
+---
+
+## 10. 效率与预算
+- 每步必须推进目标；界面未变不重复截图/点击（但**每拍开始时需要一次新鲜观察**）。
+- 找不到目标时：滑动查找设上限（建议 ≤ 5 屏），超出即停止汇报。
+- 连续 6 步无进展 → 停止（§8.3）。
+- 不要为"确认"而反复截图同一画面（除非上一拍是写操作，需要验证）。
+
+---
+
+## 11. 安全红线（不可违反）
+1. **绝不 `adb kill-server` / `adb disconnect`**。
+2. **不抢任务设备**（`device_busy` 就避开）。
+3. **L2 敏感写**（发评论/私信、关注取关、发布、下单支付、改资料）→ **默认不做**，先截图请人工确认。
+4. **L3 破坏性**（卸载/清数据/改系统设置/恢复出厂/删文件）→ **一律不做**。
+5. **不泄露**设备上的个人信息与凭据；不外传截图。
+6. **不绕过**写门控/白名单/审计。
+
+---
+
+## 12. 当前边界与相关文档
+- MCP 无任务 CRUD、无独立鉴权（靠网络隔离）。
+- `doc/MCP.md`（工具手册）｜`doc/MCP_DESIGN.md`（设计与现状对照）｜`doc/API.md`（REST 目录）
+- 岗位职责与授权分级：`doc/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,6 +24,10 @@ _log = logging.getLogger("agent")
 
 S = AgentSettings()
 
+
+class _UsageUnsupported(RuntimeError):
+    """模型/网关不认 stream_options.include_usage（400/422 或报错点名该字段）——降级重试用。"""
+
 SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操作 Android 手机。
 
 工作规范：
@@ -56,8 +62,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 +101,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 +125,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 +134,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 +151,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 +228,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 +237,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 +266,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 +305,7 @@ class Agent:
                         continue
                     raise
 
+            self._accumulate_usage(call_usage)
             full_content = "".join(content_parts)
 
             if has_tool:
@@ -272,13 +350,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 "（已达步骤上限，模型未能生成总结）"

static/admin/agent.js

@@ -3,6 +3,17 @@ let _agentBusy = false;
 let _agentStream = null;      // EventSource
 let _agentCfgLoaded = false;
 
+// 后端异常文案兜底：MCP 客户端在工具服务不可达时只抛
+// "Server returned an error response" 这类含糊字样，这里映射成明确指引。
+function _friendlyAgentError(msg){
+  const raw = String(msg || '');
+  const s = raw.replace(/^[A-Za-z_]*Error:\s*/, '');   // 去掉 "RuntimeError: " 之类前缀
+  if(/不可达|连接中断/.test(s)) return s;              // 后端已给出明确文案，直接用
+  if(/mcp_server|server returned an error response|connecterror|connection refused|all connection attempts failed|server disconnected|network is unreachable|connect timeout/i.test(s))
+    return 'MCP server(8033) 不可达：AI 无法连接设备工具服务，请确认 MCP server 已启动（本机可运行 python -m mcp_server.mcp_server）';
+  return raw;
+}
+
 // ================== 初始化 ==================
 let _agentDefaultSerial = '';
 function initAgentChat(){
@@ -46,7 +57,7 @@ function restoreRunningFlow(){
       const chat = document.getElementById('agent-chat');
       if(chat && !chat.children.length){
         const div = newAssistantMsg();
-        div.querySelector('.agent-text').textContent = '⚠ ' + r.error;
+        div.querySelector('.agent-text').textContent = '⚠ ' + _friendlyAgentError(r.error);
       }
     }
   });
@@ -109,6 +120,11 @@ function pollRunState(){
            ? '将操作：' + 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); }   // 流异常丢失时复位
   });
 }
@@ -162,11 +178,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();
@@ -186,6 +282,9 @@ function bindChatScroll(){
 }
 function clearAgentChat(){
   document.getElementById('agent-chat').innerHTML = '';
+  _convUsage = {};    // 换会话：token 累计重新算
+  _liveUsage = {};
+  updateSessionTokens();
 }
 
 // ================== 历史会话（DeepSeek 式：左侧列表，多会话持久化） ==================
@@ -241,15 +340,36 @@ function renderConvList(){
     }
     list.innerHTML = convs.map(c=>{
       const t = c.title || '新会话';
+      const sid = String(c.id || '');
       return '<div class="agent-sess-item'+(c.id===cur?' active':'')
         +'" onclick="selectAgentSession(\''+c.id+'\')">'
         +'<button class="agent-sess-del" title="删除会话" '
         +'onclick="event.stopPropagation();deleteAgentSession(\''+c.id+'\')">✕</button>'
         +'<div class="t">'+esc(t)+'</div>'
-        +'<div class="m">'+esc(c.updated_at||'')+(c.count ? ' · '+c.count+' 轮' : '')+'</div></div>';
+        +'<div class="m">'+esc(c.updated_at||'')+(c.count ? ' · '+c.count+' 轮' : '')
+        +' · <span style="font-family:monospace;opacity:.75" title="会话 ID：'+esc(sid)+'（点击复制）" '
+        +'onclick="event.stopPropagation();copyConvId(\''+sid+'\')">#'+esc(sid.slice(0,8))+'</span>'
+        +'</div></div>';
     }).join('');
   });
 }
+// 复制会话 ID（便于反馈问题时引用，如 conv=2ba4da0e43）
+function copyConvId(id){
+  const done = ()=>showToast('会话 ID 已复制: '+id,'success');
+  try{
+    if(navigator.clipboard && navigator.clipboard.writeText){
+      navigator.clipboard.writeText(id).then(done).catch(()=>fallback());
+      return;
+    }
+  }catch(e){}
+  fallback();
+  function fallback(){
+    const ta=document.createElement('textarea');
+    ta.value=id; document.body.appendChild(ta); ta.select();
+    try{ document.execCommand('copy'); done(); }catch(e){ showToast('会话 ID: '+id,'success'); }
+    ta.remove();
+  }
+}
 function loadCurrentConvMessages(){
   const chat = document.getElementById('agent-chat');
   if(!chat) return;
@@ -261,15 +381,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();
-        const div = newAssistantMsg();
+      if(txt){ div._md = txt; _renderMd(div); }
-        div.querySelector('.agent-text').textContent = txt;
+      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>';
@@ -313,8 +444,8 @@ function sendAgentMsg(){
       if(!r||!r.ok){
         const msg = r ? (r.error||'启动失败') : '请求失败';
         const div = newAssistantMsg();
-        div.querySelector('.agent-text').textContent = '⚠ ' + msg;
+        div.querySelector('.agent-text').textContent = '⚠ ' + _friendlyAgentError(msg);
-        showToast(msg,'error');
+        showToast(_friendlyAgentError(msg),'error');
         return;
       }
       setRunning(true);
@@ -347,21 +478,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);
@@ -385,10 +524,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();   // 落库已完成：刷新标题/时间/轮数
   });
@@ -399,7 +544,8 @@ function listenStream(runId){
       if(ev.data) msg = JSON.parse(ev.data).message || msg;
     }catch(e){}
     if(!msgEl) msgEl = newAssistantMsg();
-    msgEl.querySelector('.agent-text').textContent = '⚠ ' + msg;
+    msgEl.querySelector('.agent-text').textContent = '⚠ ' + _friendlyAgentError(msg);
+    _liveUsage = {};            // 本轮可能已花费 token，但结果无效——不并入会话累计
     endRun();
   });
 
@@ -501,6 +647,105 @@ function endRun(){
   scrollChat();
 }
 
+// ================== 动作库（可复用动作：查看/编辑/删除/新建） ==================
+let _actCache = [];
+function openActLib(){
+  document.getElementById('agent-act-overlay').style.display = 'flex';
+  loadActLib();
+}
+function closeActLib(){
+  document.getElementById('agent-act-overlay').style.display = 'none';
+}
+function _actStepBrief(a){
+  return (a.steps||[]).map(s=>{
+    const p = s.params || {};
+    const loc = p.selector_value || p.package || p.fixed_text || '';
+    return (s.type || '?') + (loc ? (':' + loc) : '');
+  }).join(' → ');
+}
+function loadActLib(){
+  const list = document.getElementById('act-lib-list');
+  apiGet('/api/agent/actions').then(r=>{
+    if(!r||!r.ok){ showToast((r&&r.error)||'加载失败','error'); return; }
+    _actCache = r.actions || [];
+    document.getElementById('act-lib-hint').textContent = '共 ' + _actCache.length + ' 个动作';
+    if(!_actCache.length){
+      list.innerHTML = '<div class="text-muted" style="padding:20px;text-align:center">暂无动作——跑一轮以元素/文字点击为主的任务后会自动沉淀</div>';
+      return;
+    }
+    list.innerHTML = '';
+    _actCache.forEach(a=>{
+      const card = document.createElement('div');
+      card.style.cssText = 'border:1px solid var(--card-line);border-radius:10px;padding:9px 13px;background:#0d1117';
+      card.innerHTML = '<div style="display:flex;justify-content:space-between;gap:10px;align-items:flex-start">'
+        + '<div style="flex:1;min-width:0">'
+        +   '<div style="font-weight:600">' + esc(a.name||'')
+        +     (a.app ? '<span class="text-muted" style="font-size:11px;font-weight:400;margin-left:6px">' + esc(a.app) + '</span>' : '')
+        +   '</div>'
+        +   '<div style="font-size:11.5px;color:#9fb3d1;margin-top:2px;word-break:break-all">' + esc(_actStepBrief(a) || '—') + '</div>'
+        +   '<div class="text-muted" style="font-size:11px;margin-top:2px">别名: ' + esc((a.aliases||[]).join('、')||'—')
+        +     ' ｜ 命中 ' + (a.hits||0) + ' 次 ｜ ' + esc(a.updated_at||'') + '</div>'
+        + '</div>'
+        + '<div style="display:flex;flex-direction:column;gap:4px;flex:none">'
+        +   '<button class="btn btn-xs" onclick="actEdit(' + a.id + ')">编辑</button>'
+        +   '<button class="btn btn-xs btn-danger" onclick="actDelete(' + a.id + ')">删除</button>'
+        + '</div></div>';
+      list.appendChild(card);
+    });
+  });
+}
+function actDelete(id){
+  if(!confirm('确认删除该动作？删除后同类任务不再自动复用它。')) return;
+  apiPost('/api/agent/actions/delete',{id:id}).then(r=>{
+    showToast((r&&(r.msg||r.error))||'删除失败', (r&&r.ok)?'success':'error');
+    loadActLib();
+  });
+}
+function actNew(){ _actForm({name:'', app:'', aliases:[], params:[], steps:[]}); }
+function actEdit(id){
+  const a = _actCache.find(x=>x.id===id);
+  if(a) _actForm(a);
+}
+function _actForm(a){
+  const list = document.getElementById('act-lib-list');
+  const isNew = !a.id;
+  list.innerHTML = '';
+  const box = document.createElement('div');
+  box.style.cssText = 'border:1px solid var(--card-line);border-radius:10px;padding:12px 14px;background:#0d1117';
+  box.innerHTML =
+      '<div style="font-weight:600;margin-bottom:8px">' + (isNew?'新建动作':'编辑动作 #'+a.id) + '</div>'
+    + '<div style="display:flex;gap:8px;flex-wrap:wrap;margin-bottom:6px">'
+    +   '<input id="act-f-name" class="form-control" style="flex:1;min-width:180px" placeholder="动作名（如 打开抖音）" value="' + esc(a.name||'') + '">'
+    +   '<input id="act-f-app" class="form-control" style="flex:1;min-width:180px" placeholder="包名（可空，如 com.ss.android.ugc.aweme）" value="' + esc(a.app||'') + '">'
+    + '</div>'
+    + '<div style="display:flex;gap:8px;flex-wrap:wrap;margin-bottom:6px">'
+    +   '<input id="act-f-alias" class="form-control" style="flex:1;min-width:180px" placeholder="别名（逗号分隔）" value="' + esc((a.aliases||[]).join(',')) + '">'
+    +   '<input id="act-f-params" class="form-control" style="flex:1;min-width:180px" placeholder="参数名（逗号分隔，可空）" value="' + esc((a.params||[]).join(',')) + '">'
+    + '</div>'
+    + '<textarea id="act-f-steps" class="form-control" rows="9" style="font-family:monospace;font-size:12px" '
+    +   'placeholder=\'步骤 JSON 数组，例：[{"type":"click","params":{"selector_type":"text","selector_value":"搜索"}}]\'>'
+    +   esc(JSON.stringify(a.steps||[], null, 2)) + '</textarea>'
+    + '<div class="text-muted" style="font-size:11px;margin:6px 0">可用 type：open_app/click/input_text/swipe/wait/key_event/group…；click 必须有 selector_value（xpath/text/resourceId/description…）；<b>不接受坐标(click_xy)</b>。</div>'
+    + '<div style="display:flex;gap:8px"><button class="btn btn-primary btn-sm" onclick="actSave(' + (a.id||0) + ')">保存</button>'
+    + '<button class="btn btn-sm" onclick="loadActLib()">取消</button></div>';
+  list.appendChild(box);
+}
+function actSave(id){
+  const g = (i)=>document.getElementById(i).value;
+  const split = (s)=>String(s||'').split(/[,，]/).map(x=>x.trim()).filter(x=>x);
+  let steps;
+  try{ steps = JSON.parse(g('act-f-steps')||'[]'); }
+  catch(e){ showToast('steps 不是合法 JSON: '+e.message,'error'); return; }
+  apiPost('/api/agent/actions/save', {
+    id: id||0, name: g('act-f-name'), app: g('act-f-app'),
+    aliases: split(g('act-f-alias')), params: split(g('act-f-params')), steps: steps
+  }).then(r=>{
+    if(!r||!r.ok){ showToast((r&&r.error)||'保存失败','error'); return; }
+    showToast(r.msg||'已保存','success');
+    loadActLib();
+  });
+}
+
 // ================== 经验库（自进化记忆管理） ==================
 function openExpLib(){
   document.getElementById('agent-exp-overlay').style.display = 'flex';

static/admin/base.js

@@ -102,11 +102,12 @@ function showTab(name){
   if(name==='logs'){loadLogs();if(document.getElementById('log-auto').checked)_logTimer=setInterval(loadLogs,3000);}
   if(name==='agent' && typeof initAgentChat==='function') initAgentChat();
   if(name==='users')loadUsers();
+  if(name==='system'){showSubTab('system',_activeSubs.system||'backup');}
 }
 
 // ================== 页内子分栏（任务/工具 通用） ==================
 // 每个带子分栏的 Tab 记住上次选中的子分栏，切走再切回来保持原位
-let _activeSubs = {tasks: 'plan', tools: 'clipboard'};
+let _activeSubs = {tasks: 'plan', tools: 'clipboard', system: 'backup'};
 let _discoveryTimer = null;   // 设备自动发现 10s 轮询（仅 devpool 子分栏激活时）
 
 function showSubTab(tabId, name){

static/admin/editor.js

@@ -845,7 +845,10 @@ var _stepEditor={
       '</div>';
     document.getElementById('el-picker-footer').innerHTML=
       '<button class="btn" onclick="_stepEditor._showDevicePicker()">← 返回选设备</button>'+
-      '<button class="btn" onclick="closeElPicker()">取消</button>';
+      '<button class="btn" onclick="closeElPicker()">取消</button>'+
+      '<span class="text-muted" style="margin-left:10px;font-size:11.5px">'
+      +'提示：先「▶ 点一下」在设备上验证位置，再点元素回填选择器；'
+      +'「✓ 测选择器」会用将填入的选择器真跑一次点击</span>';
     // 加载截图和元素树（_refreshShot 内部同时刷新两者）
     self._refreshShot();
   },
@@ -999,6 +1002,14 @@ var _stepEditor={
       var indent='  '.repeat(Math.min(el.depth||0,6));
       var sg=el.suggested||{};
       if(sg.invalid)attrs.push('<span style="color:#dc2626">⚠ '+esc(sg.reason||'无可用属性')+'</span>');
+      var acts='<div class="ep-acts" style="margin-left:auto;display:flex;gap:4px;flex:none">'
+        +'<button class="btn btn-xs" title="直接在设备上点这个元素（按元素中心坐标点击，服务端自动吸附到可点元素）" '
+        +'onclick="event.stopPropagation();_stepEditor._testTap('+idx+')">▶ 点一下</button>'
+        +(!sg.invalid&&sg.value
+          ? '<button class="btn btn-xs" title="用将填入的选择器在设备上真跑一次 click，验证是否命中" '
+            +'onclick="event.stopPropagation();_stepEditor._testSelector('+idx+')">✓ 测选择器</button>'
+          : '')
+        +'</div>';
       return '<div class="el-picker-item" data-idx="'+idx+'" title="点击填入: '+esc(sg.value||'')+'" onclick="_stepEditor._pickEl('+idx+')">'+
         '<span class="ep-depth">'+(el.depth||0)+'</span>'+
         '<div class="ep-info"><div class="ep-name">'+indent+esc(el.name||el.class||'')+'</div>'+
@@ -1006,10 +1017,41 @@ var _stepEditor={
         '<span class="ep-sel">'+esc(sg.type)+'</span>'+
         (sg.indexed?' <span class="label label-info" title="界面中同属性元素共 '+sg.total+' 个，按从上到下这是第 '+sg.occ+' 个，选择器已带序号精确定位">#'+sg.occ+'/'+sg.total+'</span>':'')+
         (sg.broad?' <span class="label label-warning" title="无唯一属性，选择器可能误匹配其他元素，建议选带文字/id 的元素">⚠宽泛</span>':'')+
+        acts+
       '</div>';
     }).join('');
     document.getElementById('el-list').innerHTML=html||'<div class="se-empty">无元素</div>';
   },
+  // 抓取时"直接点一下"：按元素 bounds 中心在设备上点击（服务端 snap 吸附）
+  _testTap:function(idx){
+    var el=this._elData&&this._elData[idx]; var serial=this._elSerial;
+    if(!el||!serial)return;
+    var m=(el.bounds||'').match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+    if(!m){ showToast('该元素没有 bounds，无法坐标点击','error'); return; }
+    var x=Math.round((+m[1]+ +m[3])/2), y=Math.round((+m[2]+ +m[4])/2);
+    var self=this;
+    apiPost('/api/screen/tap', {serial:serial, x:x, y:y, snap:1}).then(function(r){
+      if(!r||!r.ok){ showToast((r&&r.error)||'点击失败','error'); return; }
+      showToast('已点击'+(r.label?('「'+r.label+'」'):'')+' ('+r.x+','+r.y+')'+(r.snapped?' [已吸附]':''),'success');
+      setTimeout(function(){ if(self._elSerial===serial)self._refreshShot(); }, 800);
+    });
+  },
+  // 抓取时验证"将填入的选择器"：走 /api/steps/test 真跑一次 click
+  _testSelector:function(idx){
+    var el=this._elData&&this._elData[idx]; var serial=this._elSerial;
+    if(!el||!serial)return;
+    var sg=el.suggested||{};
+    if(!sg.value){ showToast('该元素没有可用选择器','error'); return; }
+    var self=this;
+    var step={type:'click', label:'测试点击',
+              params:{selector_type:sg.type||'xpath', selector_value:sg.value, wait_timeout:2}};
+    apiPost('/api/steps/test', {serial:serial, step:step}).then(function(r){
+      if(!r||!r.ok){ showToast((r&&r.error)||'测试失败','error'); return; }
+      var ok=(r.result==='命中');
+      showToast('选择器测试: '+(r.result||'')+(r.msg?(' — '+r.msg):''), ok?'success':'error');
+      setTimeout(function(){ if(self._elSerial===serial)self._refreshShot(); }, 800);
+    });
+  },
   _filterEl:function(kw){
     if(!kw){this._renderEl(this._elData);this._renderOverlays();return;}
     kw=kw.toLowerCase();

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

@@ -445,6 +445,34 @@ 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');
+    const title=s+(d.model?' · '+d.model:'')
+      +(busy?' · 任务中：'+(d.task_job||''):'')
+      +(online?'':' · 离线或不在设备池');
+    return '<span class="cov-chip '+cls+'" title="'+esc(title)+'">'
+      +esc(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 +498,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

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

static/admin/tasks.js

@@ -69,7 +69,7 @@ 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('');
@@ -88,7 +88,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>'+

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

@@ -30,6 +30,7 @@ worker 按 steps 顺序执行，支持 loop 步骤循环、停止信号、进度
   group       - 动作组（含 children 步骤列表，按序执行一次，可折叠复用）
 """
 import random
+import re
 import time
 
 from tasks.base import BaseTask, register_task
@@ -39,6 +40,24 @@ from core.logger import get_logger
 
 _log = get_logger("task.generic")
 
+# 历史抓取器生成的"伪序号"选择器：//*[@resource-id="x"][4]
+# XPath 里这是"父节点内排第 4"，不是"第 4 个匹配"——同属性多实例时 [2..n] 全部失配。
+_LEGACY_IDX_XPATH = re.compile(r'^(//\*\[@[^\]]+\])\[(\d+)\](.*)$')
+
+
+def _norm_legacy_xpath(sel_val):
+    """把历史 `//*[@attr=…][k]` 纠正为 `(//*[@attr=…])[k]`（只改整体前缀，保留后续子路径）。
+
+    窄范围：只匹配"属性XPath + 数字谓词"开头的形态；结构路径里
+    `.../FrameLayout[2]` 的兄弟序号是有意为之，不受影响。
+    """
+    if not isinstance(sel_val, str):
+        return sel_val
+    m = _LEGACY_IDX_XPATH.match(sel_val.strip())
+    if not m:
+        return sel_val
+    return f"({m.group(1)})[{m.group(2)}]{m.group(3)}"
+
 
 # ================== 步骤类型定义（前端操作库 + 后端执行共用）==================
 STEP_TYPES = [
@@ -85,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}},
-            ]},
-        },
-    ],
 }
 
 
@@ -138,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="操作",
@@ -148,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 防止无限嵌套。"""
@@ -165,6 +175,12 @@ class GenericStepsWorker(BaseWorker):
         stype = step.get("type", "")
         label = step.get("label", stype)
         params = step.get("params", {})
+        # 兼容历史选择器：//*[@attr=…][k] → (//*[@attr=…])[k]（XPath 位置谓词语义）
+        if params.get("selector_type") == "xpath" and params.get("selector_value"):
+            fixed = _norm_legacy_xpath(params["selector_value"])
+            if fixed != params["selector_value"]:
+                params = dict(params, selector_value=fixed)
+                _log.info(f"[{self.serial}] 选择器已纠正为: {fixed}")
         # 概率触发：probability=100 必执行，<100 按百分比概率决定本次是否执行
         prob = float(params.get("probability", 100))
         if prob < 100 and random.random() * 100 > prob:

templates/admin/monitor.html

@@ -169,6 +169,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 +346,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}
@@ -365,6 +399,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
     <button class="tab" data-tab="users" onclick="showTab('users')" data-perm="admin">用户</button>
     <button class="tab" data-tab="tools" onclick="showTab('tools')" data-perm="admin">工具</button>
     <button class="tab" data-tab="agent" onclick="showTab('agent')" data-perm="admin">AI 控制台</button>
+    <button class="tab" data-tab="system" onclick="showTab('system')" data-perm="admin">系统</button>
   </div>
   <div class="user-info">
     <span id="me-username">...</span>
@@ -475,10 +510,11 @@ 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>
+        <button class="btn btn-xs" onclick="openActLib()" title="查看/管理可复用动作（命名动作 + 元素定位步骤，AI 自动沉淀，可编辑删除）">🎬 动作库</button>
         <button class="btn btn-xs" onclick="openAgentConfig()">⚙ 配置</button>
       </div>
     </div>
@@ -562,6 +598,24 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
   </div>
 </div>
 
+<!-- ========== 动作库模态框（可复用动作：命名动作 + 元素定位步骤） ========== -->
+<div id="agent-act-overlay" style="display:none;position:fixed;inset:0;background:rgba(0,0,0,.6);z-index:1320;align-items:center;justify-content:center">
+  <div style="background:#11151c;border:1px solid var(--card-line);border-radius:14px;padding:20px 22px;width:860px;max-width:94vw;max-height:86vh;display:flex;flex-direction:column">
+    <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:4px">
+      <div style="font-size:15px;font-weight:700">🎬 动作库<span class="text-muted" style="font-size:11.5px;font-weight:400;margin-left:8px" id="act-lib-hint"></span></div>
+      <div style="display:flex;gap:6px;align-items:center">
+        <button class="btn btn-xs" onclick="actNew()">＋ 新建动作</button>
+        <button class="btn btn-xs" onclick="loadActLib()">刷新</button>
+        <button class="btn btn-xs" onclick="closeActLib()">✕ 关闭</button>
+      </div>
+    </div>
+    <div class="text-muted" style="font-size:11.5px;padding:0 2px 8px;border-bottom:1px solid var(--card-line);margin-bottom:10px">
+      任务成功后自动把<b>成功步骤</b>沉淀为可复用动作（命名动作 + 编辑器 schema 步骤 + 元素定位，<b>不含坐标</b>）；执行前按动作名/别名召回注入，AI 可直接复用、跳过重新探索。可在此查看、编辑、删除或手动新建。
+    </div>
+    <div id="act-lib-list" style="flex:1;overflow-y:auto;min-height:200px;display:flex;flex-direction:column;gap:8px"></div>
+  </div>
+</div>
+
 <!-- ========== Tab 4: 日志 ========== -->
 <div id="tab-logs" class="tab-panel">
   <div class="page-title">日志查看</div>
@@ -850,9 +904,52 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
     <div class="list-pager" id="pager-groups"></div>
     <div class="help">管理设备分组，用于任务按分组执行。分组内的设备需先在<b>设备池管理</b>中确认（不在池内的设备不参与调度）。</div>
   </div>
+</div>
 
+<!-- ========== Tab 9: 系统（仅管理员） ========== -->
+<div id="tab-system" class="tab-panel">
+  <div class="page-title">系统</div>
+  <div class="page-sub">系统数据备份导出/导入（仅管理员）</div>
 
+  <div class="sub-tabs">
+    <button class="sub-tab active" data-sub="backup" onclick="showSubTab('system','backup')">数据备份</button>
+    <button class="sub-tab" data-sub="restore" onclick="showSubTab('system','restore')">导入恢复</button>
+  </div>
 
+  <!-- 子分栏 1：数据备份 -->
+  <div class="sub-panel active" id="system-sub-backup">
+    <div class="help">
+      <b>导出</b>当前系统数据为 zip：含 <code>users.db</code> 在线一致快照（<b>全部业务表</b>：用户 / 任务计划 / 设备分组 /
+      自定义动作 / APK 记录 / 设备池 / 待连接设备 / AI 会话 / 经验库 / 经验巡检 / <b>动作库</b> / 系统配置）+ 可选的
+      <code>apks/</code> 应用文件。恢复用：换机 / 整库迁移 / 出问题前留底。
+      <br><span class="text-muted">清单见预览的「表数据行数」；新增持久化表须登记进备份覆盖清单（红线，见 doc/DEPLOY.md §3.5）。</span>
+    </div>
+    <div class="toolbar" style="gap:8px">
+      <label style="display:inline-flex;align-items:center;gap:4px;margin:0 6px">
+        <input type="checkbox" id="backup-include-apk" checked> 包含 APK 文件（体积较大，~100MB 级）
+      </label>
+      <button class="btn btn-primary" onclick="doExportBackup()">导出备份</button>
+      <span id="backup-status" class="text-muted"></span>
+    </div>
+    <div style="background:#fff8e1;border:1px solid #ffe082;color:#8a6d00;padding:8px 12px;border-radius:6px;margin:8px 0">
+      ⚠️ 备份为<b>全量快照</b>：含用户口令哈希、AI 配置里的 API Key 等敏感信息，请妥善保管，勿外传、勿提交到 git。
+    </div>
+  </div>
+
+  <!-- 子分栏 2：导入恢复 -->
+  <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>（导入将覆盖现有全部数据）。
+    </div>
+    <div class="toolbar" style="gap:8px">
+      <input type="file" id="restore-file" accept=".zip,.db">
+      <button class="btn" onclick="previewRestore()">上传并预览</button>
+      <button class="btn btn-danger" id="btn-apply-restore" onclick="applyRestore()" style="display:none">确认应用导入</button>
+      <span id="restore-status" class="text-muted"></span>
+    </div>
+    <div id="restore-preview" style="margin-top:8px"></div>
+  </div>
 </div>
 
 </div><!-- /.content -->
@@ -910,6 +1007,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>
@@ -918,5 +1016,6 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 <script src="/static/admin/apps.js"></script>
 <script src="/static/admin/admin.js"></script>
 <script src="/static/admin/agent.js"></script>
+<script src="/static/admin/system.js"></script>
 </body>
 </html>

web/__init__.py

@@ -9,6 +9,7 @@
   devices     — 设备池管理
   apks        — 应用管理
   tailscale   — Tailscale 管理
+  system      — 系统数据备份导出/导入
 """
 from flask import Blueprint
 
@@ -26,6 +27,7 @@ def register_blueprints(app):
     from . import agent_api as _agent_mod
     from .agent_api import bp as agent_bp
     _agent_mod.set_app(app)
+    from .system_api import bp as system_bp
     for bp in (auth_bp, monitor_bp, tasks_bp, admin_bp, tools_bp,
-               devices_bp, apks_bp, tailscale_bp, agent_bp):
+               devices_bp, apks_bp, tailscale_bp, agent_bp, system_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（用户中断）
@@ -186,23 +192,24 @@ def _qualify_experience(prompt, recipe):
 def _find_experiences(prompt, limit=2, threshold=0.10):
     """按 bigram 重叠检索相似历史经验（prompt 与任务描述的字符相似度）。
 
-    命中的经验 hits+1（回写），让被反复参考的有效经验浮到前面。
+    返回 (注入文本, 命中的配方列表)；命中的经验 hits+1（回写），让被反复
+    参考的有效经验浮到前面。配方列表供调用方展示「命中 N 条」与摘要。
     """
     try:
         if _flask_app is None:
-            return ""
+            return "", []
         with _flask_app.app_context():
             _ensure_exp_table()
             rows = db.session.execute(db.text(
                 "SELECT id, task_prompt, recipe, hits FROM agent_experience "
                 "WHERE recipe != '' ORDER BY hits DESC, id DESC LIMIT 50")).fetchall()
     except Exception:
-        return ""
+        return "", []
     if not rows:
-        return ""
+        return "", []
     cur = _bigrams(prompt)
     if not cur:
-        return ""
+        return "", []
     scored = []
     for row_id, task_prompt, recipe, hits in rows:
         sim = len(cur & _bigrams(task_prompt)) / len(cur)
@@ -220,10 +227,78 @@ def _find_experiences(prompt, limit=2, threshold=0.10):
                 db.session.commit()
         except Exception:
             pass
-    parts = []
+    picked = [recipe for _sim, _hits, recipe, _row_id in scored[:limit]]
-    for sim, _hits, recipe, _row_id in scored[:limit]:
+    parts = [f"- {r[:600]}" for r in picked]
-        parts.append(f"- {recipe[:600]}")
+    return "\n".join(parts), picked
-    return "\n".join(parts)
+
+
+def _msg_text(message, allow_reasoning=False):
+    """取模型回复正文。
+
+    推理模型（DeepSeek 等）**偶发**把 token 预算全花在 reasoning 上、content 为空
+    （finish_reason=length），直接读 content 会当空处理 → 经验/动作被静默丢弃
+    （2026-09-10 实测）。默认**不回退 reasoning**（那是思考草稿，做"配方"会污染）；
+    仅在能结构化解析的场景（动作 JSON 提取）才允许回退。
+    """
+    m = message or {}
+    text = (m.get("content") or "").strip()
+    if text:
+        return text
+    if allow_reasoning:
+        return (m.get("reasoning_content") or "").strip()
+    return ""
+
+
+_RECIPE_JSON_RE = re.compile(r'"recipe"\s*:\s*"((?:[^"\\]|\\.)*)"', re.S)
+
+
+def _recipe_ok(recipe):
+    """配方质量门槛：太短、或只有序号+省略号（模型照抄占位）视为无效。
+
+    2026-09-10 实测：提示词里写了示例 JSON，模型会把占位符 `1. …\\n2. …`
+    原样当成配方存下来 → 这里拦掉，宁可重试/不存，也不污染经验库。
+    """
+    t = (recipe or "").strip()
+    if len(t) < 15:
+        return False
+    if "…" in t and len(t) < 30:
+        return False
+    return True
+
+
+def _extract_recipe(text):
+    """从（可能被截断的）模型输出里取配方正文。
+
+    蒸馏提示词要求输出 {"recipe": "…"}；推理模型会把预算烧在 reasoning 上并
+    截断（finish_reason=length），严格 json.loads 会失败，故用正则直接抠字段。
+    """
+    if not text:
+        return ""
+    m = _RECIPE_JSON_RE.search(text)
+    if m:
+        try:
+            return json.loads('"' + m.group(1) + '"').strip()
+        except Exception:
+            return m.group(1).replace("\\n", "\n").strip()
+    t = text.strip()
+    if t.startswith("{") or t.startswith("["):
+        return ""          # JSON 外壳但没抠到 recipe：视为无效，避免把草稿当配方
+    return t
+
+
+def _clean_recipe(recipe):
+    """清洗蒸馏输出：去掉模型可能加的「操作配方：」之类前缀标签与包裹引号。
+
+    旧逻辑用 `"配方" not in recipe[:50]` 直接拒绝——而蒸馏提示词本就要求以
+    「操作配方」作答，模型一旦照做就会被整条丢弃（静默），导致经验很难存下。
+    改为清洗前缀而非丢弃。
+    """
+    t = (recipe or "").strip()
+    if not t:
+        return ""
+    t = re.sub(r'^[^\n]{0,12}?配方[：:]\s*', '', t, count=1).strip()
+    t = re.sub(r'^(操作步骤|步骤|流程)[：:]\s*', '', t).strip()
+    return t.strip('"“”\'').strip()
 
 
 def _distill_experience(cfg, prompt, tool_seq):
@@ -232,22 +307,34 @@ def _distill_experience(cfg, prompt, tool_seq):
         import httpx
         body = {
             "model": cfg.get("model") or "deepseek-v4-flash-vision-exp",
+            # 关推理：蒸馏是"给定轨迹写配方"的确定性任务，开启 thinking 会占满
+            # 预算导致 content 空/被截断（实测）；该代理支持 thinking.type=disabled
+            "thinking": {"type": "disabled"},
             "messages": [{"role": "user",
                           "content": "以下是一次成功的手机自动化操作记录。请提炼成简洁的"
                                      "「操作配方」（2-6 步，每步：目标 → 用哪个工具），"
-                                     "供下次同类任务参考。不要解释，直接输出配方。\n"
+                                     "供下次同类任务参考。不要解释，直接输出配方正文。\n"
                                      f"任务：{prompt[:300]}\n操作序列：{tool_seq[:800]}"}],
-            "max_tokens": 600,
+            "max_tokens": 800,
         }
         headers = {"Authorization": f"Bearer {cfg.get('api_key', '')}",
                    "Content-Type": "application/json"}
-        r = httpx.post(f"{(cfg.get('api_base') or 'https://api.deepseek.com').rstrip('/')}/chat/completions",
+        url = f"{(cfg.get('api_base') or 'https://api.deepseek.com').rstrip('/')}/chat/completions"
-                       json=body, headers=headers, timeout=25)
+        # content 为空（推理吃满预算）时重试一次——实测同样提示第二次常能出正文
-        if r.status_code != 200:
+        for _attempt in (1, 2):
-            return ""
+            r = httpx.post(url, json=body, headers=headers, timeout=25)
-        j = r.json()
+            if r.status_code != 200:
-        recipe = ((j.get("choices") or [{}])[0].get("message") or {}).get("content") or ""
+                _log.warning(f"经验提炼: 模型返回 HTTP {r.status_code}")
-        return recipe.strip()[:1500]
+                continue
+            msg = (r.json().get("choices") or [{}])[0].get("message") or {}
+            # 正文优先；为空时从 reasoning 里抠（可能含清晰步骤），都要过质量门槛
+            for cand in (_msg_text(msg), _extract_recipe(msg.get("reasoning_content"))):
+                if _recipe_ok(cand):
+                    return cand.strip()[:1500]
+                if cand:
+                    _log.info(f"经验提炼: 候选配方质量不足（{len(cand)} 字符）被丢弃")
+        _log.info("经验提炼: 两次均未产出可用配方（推理占满预算/输出被截断/仅占位）")
+        return ""
     except Exception as e:
         _log.warning(f"经验提炼失败: {e}")
         return ""
@@ -274,6 +361,371 @@ def _save_experience(prompt, recipe, tool_seq):
         return False
 
 
+# ---------- 动作经验库（agent_action）----------
+# 与「任务级配方」(agent_experience) 互补：动作 = 有语义名的可复用单元，可含 1~N 步，
+# steps 直接用编辑器 schema（open_app/click/input_text…），带**元素定位**
+# （selector_type/selector_value），**不含坐标**（分辨率/旋转/改版即失效）。
+# 复用：执行前按 name/别名/App 召回并注入 system prompt，模型可跳过重新探索。
+_ACTION_TABLE = (
+    "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 = {
+    "open_app", "stop_app", "screen_on", "screen_off", "key_event",
+    "swipe", "swipe_until", "click", "long_click", "wait_el",
+    "input_text", "clipboard", "wait", "loop", "group", "if_el"}
+_ACTION_REQUIRED = {   # 类型 → 必需的 params 键（缺则丢弃该动作）
+    "open_app": ("package",), "stop_app": ("package",),
+    "click": ("selector_value",), "long_click": ("selector_value",),
+    "wait_el": ("selector_value",), "swipe_until": ("selector_value",),
+    "if_el": ("selector_value", "then"),
+    "group": ("children",), "loop": ("children",)}
+# 可写入动作的关键工具（探索类 de_screenshot/de_ui_tree/de_ocr 不沉淀）
+_ACTION_TOOLS = {
+    "de_open_app", "de_stop_app", "de_tap_text", "de_tap_element", "de_type_text",
+    "de_set_clipboard", "de_swipe", "de_press_key", "de_wake", "de_sleep"}
+
+
+def _ensure_action_table():
+    try:
+        db.session.execute(db.text(_ACTION_TABLE))
+        db.session.commit()
+    except Exception:
+        pass
+
+
+def _brief_result(result):
+    """工具结果的精简摘要（判成败 + 供提炼模型参考）。"""
+    try:
+        s = json.dumps(result, ensure_ascii=False) if not isinstance(result, str) else result
+    except Exception:
+        s = str(result)
+    return (s or "")[:160]
+
+
+def _tool_ok(tool, result):
+    """启发式判断一次工具调用是否成功（只沉淀成功动作，避免把误点当经验）。"""
+    if result is None:
+        return False
+    if isinstance(result, dict):
+        if result.get("error") or result.get("ok") is False or result.get("success") is False:
+            return False
+        if tool == "de_tap_text":
+            return bool(result.get("matched")) or result.get("method") in ("ui", "ocr")
+        if result.get("matched") is False:
+            return False
+    s = str(result).lower()
+    return not any(k in s for k in ("not_found", "error", "failed", "occupied"))
+
+
+def _normalize_action_item(a):
+    """把模型可能的「单动作」形状（{action/tool/type, params}）归一成标准动作。
+
+    实测蒸馏模型常不按提示词的 name/steps 输出，而是照抄输入行给出
+    {"action":"de_open_app","params":{...}}——这里做兼容映射，避免全被丢弃。
+    """
+    if not isinstance(a, dict):
+        return None
+    if isinstance(a.get("steps"), list):        # 已是标准形状
+        return a
+    tool = str(a.get("action") or a.get("tool") or a.get("type") or "").strip()
+    p = a.get("params") if isinstance(a.get("params"), dict) else {}
+    if not tool:
+        return None
+    name = str(a.get("name") or "").strip()
+    t, sp = None, {}
+    if tool in ("de_open_app", "open_app"):
+        t, sp = "open_app", {"package": p.get("package", "")}
+        name = name or f"打开应用 {p.get('package', '')}"
+    elif tool in ("de_stop_app", "stop_app"):
+        t, sp = "stop_app", {"package": p.get("package", "")}
+        name = name or f"关闭应用 {p.get('package', '')}"
+    elif tool == "de_tap_text":
+        t, sp = "click", {"selector_type": "text", "selector_value": p.get("text", "")}
+        name = name or f"点击「{p.get('text', '')}」"
+    elif tool == "de_tap_element":
+        by = {"text": "text", "id": "resourceId", "desc": "description",
+              "text_contains": "text", "desc_contains": "descriptionContains"}.get(
+                  p.get("by"), "text")
+        t, sp = "click", {"selector_type": by, "selector_value": p.get("value", "")}
+        name = name or f"点击元素 {p.get('value', '')}"
+    elif tool == "de_type_text":
+        t, sp = "input_text", {"mode": "fixed", "fixed_text": p.get("text", "")}
+        name = name or f"输入「{p.get('text', '')}」"
+    elif tool == "de_set_clipboard":
+        t, sp, name = "clipboard", {"text": p.get("text", "")}, name or "写入剪贴板"
+    elif tool == "de_swipe":
+        t, sp = "swipe", {"direction": p.get("direction") or "up"}
+        name = name or "滑动"
+    elif tool == "de_press_key":
+        t, sp = "key_event", {"key": p.get("key") or "back"}
+        name = name or f"按键 {p.get('key', '')}"
+    elif tool == "de_wake":
+        t, name = "screen_on", name or "亮屏解锁"
+    elif tool == "de_sleep":
+        t, name = "screen_off", name or "息屏"
+    if not t:
+        return None
+    return {"name": name, "app": a.get("app", ""), "aliases": a.get("aliases") or [],
+            "params": [], "preconditions": a.get("preconditions", ""),
+            "steps": [{"type": t, "params": sp}]}
+
+
+def _sanitize_actions(actions):
+    """校验/清洗模型产出的动作：名字非空、步骤白名单+必填、显式禁坐标。"""
+    out = []
+    for a in (actions or []):
+        a = _normalize_action_item(a)
+        if not isinstance(a, dict):
+            continue
+        name = str(a.get("name") or "").strip()[:40]
+        steps = a.get("steps")
+        if not name or not isinstance(steps, list) or not steps:
+            continue
+        good = []
+        for st in steps:
+            if not isinstance(st, dict):
+                continue
+            t = st.get("type")
+            if t not in _ACTION_STEP_TYPES:      # click_xy 等坐标类在此被剔除
+                continue
+            p = st.get("params") if isinstance(st.get("params"), dict) else {}
+            if any(not p.get(k) for k in _ACTION_REQUIRED.get(t, ())):
+                continue
+            good.append({"type": t, "label": str(st.get("label") or "")[:20], "params": p})
+        if not good:
+            continue
+        out.append({
+            "name": name,
+            "app": str(a.get("app") or "")[:80],
+            "aliases": [str(x)[:20] for x in (a.get("aliases") or []) if str(x).strip()][:5],
+            "params": [str(x)[:20] for x in (a.get("params") or []) if str(x).strip()][:5],
+            "preconditions": str(a.get("preconditions") or "")[:100],
+            "steps": good})
+    return out
+
+
+def _iter_json_objects(raw):
+    """从文本里按大括号配对切出顶层 JSON 对象（容忍坏片段，逐条抢救）。"""
+    depth = 0
+    start = None
+    in_str = esc = False
+    for i, c in enumerate(raw):
+        if in_str:
+            if esc:
+                esc = False
+            elif c == "\\":
+                esc = True
+            elif c == '"':
+                in_str = False
+            continue
+        if c == '"':
+            in_str = True
+        elif c == "{":
+            if depth == 0:
+                start = i
+            depth += 1
+        elif c == "}":
+            depth -= 1
+            if depth == 0 and start is not None:
+                yield raw[start:i + 1]
+                start = None
+
+
+def _loads_lenient(text):
+    """尽量解析模型输出的 JSON 数组：容忍 markdown 围栏、尾逗号、中文引号、坏对象。"""
+    s = (text or "").strip()
+    s = re.sub(r"^```[a-zA-Z]*\s*|\s*```$", "", s).strip()
+    m = re.search(r"\[[\s\S]*\]", s)
+    raw = m.group(0) if m else s
+    candidates = [raw,
+                  re.sub(r",\s*([\]}])", r"\1", raw),          # 去尾逗号
+                  re.sub(r"[“”]", '"', raw),                    # 中文引号 → 英文
+                  re.sub(r"[“”]", '"', re.sub(r",\s*([\]}])", r"\1", raw))]
+    for cand in candidates:
+        try:
+            v = json.loads(cand)
+            if isinstance(v, list):
+                return v
+        except Exception:
+            continue
+    # 逐对象抢救（顶层大括号配对），坏的跳过
+    out = []
+    for obj in _iter_json_objects(raw):
+        try:
+            out.append(json.loads(obj))
+        except Exception:
+            continue
+    return out
+
+
+def _distill_actions(cfg, prompt, trace):
+    """从**成功**的工具轨迹提炼命名动作（JSON 数组）。失败返回 []。"""
+    ok_ops = [t for t in (trace or [])
+              if t.get("tool") in _ACTION_TOOLS and _tool_ok(t.get("tool"), t.get("result"))]
+    _log.info(f"动作提炼: 轨迹 {len(trace or [])} 步, 成功可沉淀 {len(ok_ops)} 步")
+    if not ok_ops:
+        return []
+    # 输入截断到前 10 步：步数过多会让模型输出变长被截断（实测 10 步 → 2002 字符无有效 JSON）
+    ok_ops = ok_ops[:10]
+    lines = [f"- {t['tool']} 参数={t['args']} 结果={_brief_result(t['result'])}" for t in ok_ops]
+    instruction = (
+        "以下是一次成功的手机自动化操作的**成功步骤**。请提炼为**至多 3 个**「动作」"
+        "（每个动作 = 一个有语义名的可复用单元，**至多 4 步**，字段尽量简短）。"
+        "只输出 JSON 数组，不要解释，不要思考过程。\n"
+        "字段：name(动作名，如「打开抖音」「搜索关键词」)；app(包名，未知则空串)；"
+        "aliases(别名数组)；params(参数名数组，如[\"关键词\"])；steps(步骤数组)。\n"
+        "steps 每步：type + params，type 取值：open_app{package} / click{selector_type,"
+        "selector_value,wait_timeout?} / input_text{mode,fixed_text} / swipe{direction} /"
+        "wait{min,max} / key_event{key} / group{children}。\n"
+        "**定位必须用元素定位**：selector_type 取 xpath/text/resourceId/description/"
+        "descriptionContains，值用上面步骤里出现的真实文字或 id；**禁止坐标**。"
+        "若某步只能用坐标定位，就不要产出该动作。\n"
+        "输出示例（**顶层字段必须是 name/steps，禁止用 action/tool 当顶层字段**）：\n"
+        '[{"name":"打开抖音","app":"com.ss.android.ugc.aweme","aliases":["启动抖音"],'
+        '"params":[],"steps":[{"type":"open_app","params":{"package":"com.ss.android.ugc.aweme"}}]},'
+        '{"name":"搜索关键词","app":"","aliases":["点搜索"],"params":["关键词"],'
+        '"steps":[{"type":"click","params":{"selector_type":"text","selector_value":"搜索"}}]}]\n'
+        f"任务：{prompt[:200]}\n成功步骤：\n" + "\n".join(lines)[:1500])
+    try:
+        import httpx
+        body = {"model": cfg.get("model") or "deepseek-v4-flash-vision-exp",
+                "thinking": {"type": "disabled"},   # 同 _distill_experience：关推理
+                "messages": [{"role": "user", "content": instruction}],
+                "max_tokens": 900}
+        headers = {"Authorization": f"Bearer {cfg.get('api_key', '')}",
+                   "Content-Type": "application/json"}
+        url = f"{(cfg.get('api_base') or 'https://api.deepseek.com').rstrip('/')}/chat/completions"
+        content = ""
+        # content 空（推理吃满预算）→ 重试一次；仍空则回退 reasoning_content
+        # （这里能结构化提取 JSON 数组，草稿里也常含可用 JSON，故允许回退）
+        for _attempt in (1, 2):
+            r = httpx.post(url, json=body, headers=headers, timeout=30)
+            if r.status_code != 200:
+                _log.warning(f"动作提炼: 模型返回 HTTP {r.status_code}")
+                continue
+            msg = (r.json().get("choices") or [{}])[0].get("message") or {}
+            content = _msg_text(msg, allow_reasoning=True)
+            if content:
+                break
+        acts = _sanitize_actions(_loads_lenient(content))
+        if not acts:
+            _log.info(f"动作提炼: 解析后无有效动作（原始输出 {len(content)} 字符）"
+                      f" 样本={content[:160]!r}")
+        return acts
+    except Exception as e:
+        _log.warning(f"动作提炼失败: {e}")
+        return []
+
+
+def _save_actions(prompt, actions):
+    """按 (name, app) upsert 保存动作。返回保存条数。"""
+    if not actions or _flask_app is None:
+        return 0
+    n = 0
+    try:
+        from datetime import datetime
+        now = datetime.now().strftime("%Y-%m-%d %H:%M")
+        with _flask_app.app_context():
+            _ensure_action_table()
+            for a in actions:
+                row = db.session.execute(db.text(
+                    "SELECT id FROM agent_action WHERE name=:n AND app=:a"),
+                    {"n": a["name"], "a": a["app"]}).fetchone()
+                if row:
+                    db.session.execute(db.text(
+                        "UPDATE agent_action SET aliases=:al, params=:p, steps=:s, "
+                        "preconditions=:pc, updated_at=:t WHERE id=:i"),
+                        {"al": json.dumps(a["aliases"], ensure_ascii=False),
+                         "p": json.dumps(a["params"], ensure_ascii=False),
+                         "s": json.dumps(a["steps"], ensure_ascii=False),
+                         "pc": a["preconditions"], "t": now, "i": row[0]})
+                else:
+                    db.session.execute(db.text(
+                        "INSERT INTO agent_action(name, app, aliases, params, steps, "
+                        "preconditions, hits, source_prompt, created_at, updated_at) "
+                        "VALUES(:n,:a,:al,:p,:s,:pc,0,:sp,:t,:t)"),
+                        {"n": a["name"], "a": a["app"],
+                         "al": json.dumps(a["aliases"], ensure_ascii=False),
+                         "p": json.dumps(a["params"], ensure_ascii=False),
+                         "s": json.dumps(a["steps"], ensure_ascii=False),
+                         "pc": a["preconditions"], "sp": prompt[:200], "t": now})
+                n += 1
+            db.session.commit()
+        _log.info(f"动作经验已保存 {n} 条")
+    except Exception as e:
+        _log.warning(f"动作保存失败: {e}")
+    return n
+
+
+def _find_actions(prompt, limit=3):
+    """召回可复用动作：动作名/别名命中 prompt，或与来源提示够相似。返回 (文本, 名字列表)。"""
+    try:
+        if _flask_app is None:
+            return "", []
+        with _flask_app.app_context():
+            _ensure_action_table()
+            rows = db.session.execute(db.text(
+                "SELECT id, name, app, aliases, params, steps, hits FROM agent_action "
+                "ORDER BY hits DESC, id DESC LIMIT 100")).fetchall()
+    except Exception:
+        return "", []
+    if not rows:
+        return "", []
+    p_norm = "".join(c for c in (prompt or "").lower()
+                     if c.isalnum() or "一" <= c <= "鿿")
+    cur = _bigrams(prompt)
+    scored = []
+    for rid, name, app, aliases, params, steps, hits in rows:
+        try:
+            keys = [name] + [str(x) for x in (json.loads(aliases) if aliases else [])]
+        except Exception:
+            keys = [name]
+        hit = any(k and k.lower() in p_norm for k in keys if k)
+        sim = (len(cur & _bigrams(name)) / len(cur)) if cur else 0.0
+        if hit or sim >= 0.34:
+            scored.append((1 if hit else 0, sim, hits or 0, rid, name, app, params, steps))
+    if not scored:
+        return "", []
+    scored.sort(key=lambda x: (-x[0], -x[1], -x[2]))
+    picked = scored[:limit]
+    try:
+        with _flask_app.app_context():
+            for item in picked:
+                db.session.execute(db.text("UPDATE agent_action SET hits=hits+1 WHERE id=:i"),
+                                   {"i": item[3]})
+            db.session.commit()
+    except Exception:
+        pass
+    items, parts = [], []
+    for item in picked:
+        _hit, _sim, _hts, _rid, name, app, params, steps = item
+        try:
+            st = json.loads(steps) if steps else []
+        except Exception:
+            st = []
+        items.append(name)
+        brief = " → ".join(
+            str(s.get("params", {}).get("selector_value")
+                or s.get("params", {}).get("package")
+                or s.get("params", {}).get("fixed_text")
+                or s.get("type")) for s in st[:8])
+        parts.append(f"- 「{name}」" + (f"（app={app}）" if app else "")
+                     + (f" 参数:{params}" if params else "") + f"：{brief}")
+    return "\n".join(parts), items
+
+
 # ================== 经验巡检（AI 质检，删除需人工确认） ==================
 _audit_state = {"running": False, "last": "", "last_summary": ""}
 
@@ -312,8 +764,8 @@ def _review_one_exp(cfg, prompt, recipe, tool_seq, hits):
                            json=body, headers=headers, timeout=20)
             if r.status_code != 200:
                 raise RuntimeError(f"HTTP {r.status_code}")
-            text = (((r.json() or {}).get("choices") or [{}])[0]
+            text = _msg_text(((r.json() or {}).get("choices") or [{}])[0]
-                    .get("message") or {}).get("content") or ""
+                             .get("message") or {})
             m = re.search(r"\{.*\}", text, re.S)
             if not m:
                 raise RuntimeError("响应无 JSON")
@@ -460,6 +912,94 @@ def agent_experience_keep():
     db.session.commit()
     return jsonify({"ok": True, "msg": f"经验 #{exp_id} 已保留"})
 
+# ================== 动作经验库（agent_action：查看/删除/编辑） ==================
+def _action_row_to_dict(r):
+    def _j(s, d):
+        try:
+            return json.loads(s) if s else d
+        except Exception:
+            return d
+    return {"id": r[0], "name": r[1], "app": r[2], "aliases": _j(r[3], []),
+            "params": _j(r[4], []), "steps": _j(r[5], []), "preconditions": r[6],
+            "hits": r[7] or 0, "updated_at": r[8] or ""}
+
+
+@bp.route("/api/agent/actions")
+@admin_required
+def agent_actions_list():
+    """动作经验库列表（命名动作 + 编辑器 schema 步骤 + 元素定位，禁坐标）。"""
+    with _flask_app.app_context():
+        _ensure_action_table()
+        rows = db.session.execute(db.text(
+            "SELECT id, name, app, aliases, params, steps, preconditions, hits, updated_at "
+            "FROM agent_action ORDER BY hits DESC, id DESC")).fetchall()
+    return jsonify({"ok": True, "actions": [_action_row_to_dict(r) for r in rows]})
+
+
+@bp.route("/api/agent/actions/delete", methods=["POST"])
+@admin_required
+def agent_actions_delete():
+    aid = int((request.json or {}).get("id") or 0)
+    if aid <= 0:
+        return jsonify({"ok": False, "error": "缺少 id"}), 400
+    with _flask_app.app_context():
+        _ensure_action_table()
+        db.session.execute(db.text("DELETE FROM agent_action WHERE id=:i"), {"i": aid})
+        db.session.commit()
+    return jsonify({"ok": True, "msg": f"动作 #{aid} 已删除"})
+
+
+@bp.route("/api/agent/actions/save", methods=["POST"])
+@admin_required
+def agent_actions_save():
+    """新增/编辑动作：{id?, name, app?, aliases?, params?, steps, preconditions?}。
+
+    steps 可为数组或 JSON 字符串；经 _sanitize_actions 校验（白名单/必填/禁坐标）。
+    """
+    from datetime import datetime
+    d = request.json or {}
+    steps = d.get("steps")
+    if isinstance(steps, str):
+        try:
+            steps = json.loads(steps)
+        except Exception:
+            return jsonify({"ok": False, "error": "steps 不是合法 JSON"}), 400
+    item = _sanitize_actions([{"name": d.get("name"), "app": d.get("app", ""),
+                               "aliases": d.get("aliases") or [],
+                               "params": d.get("params") or [],
+                               "preconditions": d.get("preconditions", ""),
+                               "steps": steps if isinstance(steps, list) else []}])
+    if not item:
+        return jsonify({"ok": False, "error": "动作无效：需要 name，且 steps 需为受支持的步骤"
+                                              "（click/open_app/input_text… 且带元素定位；不接受坐标）"}), 400
+    a = item[0]
+    now = datetime.now().strftime("%Y-%m-%d %H:%M")
+    with _flask_app.app_context():
+        _ensure_action_table()
+        aid = int(d.get("id") or 0)
+        if aid > 0:
+            db.session.execute(db.text(
+                "UPDATE agent_action SET name=:n, app=:a, aliases=:al, params=:p, steps=:s, "
+                "preconditions=:pc, updated_at=:t WHERE id=:i"),
+                {"n": a["name"], "a": a["app"],
+                 "al": json.dumps(a["aliases"], ensure_ascii=False),
+                 "p": json.dumps(a["params"], ensure_ascii=False),
+                 "s": json.dumps(a["steps"], ensure_ascii=False),
+                 "pc": a["preconditions"], "t": now, "i": aid})
+        else:
+            db.session.execute(db.text(
+                "INSERT INTO agent_action(name, app, aliases, params, steps, preconditions, "
+                "hits, source_prompt, created_at, updated_at) "
+                "VALUES(:n,:a,:al,:p,:s,:pc,0,'(人工新增)',:t,:t)"),
+                {"n": a["name"], "a": a["app"],
+                 "al": json.dumps(a["aliases"], ensure_ascii=False),
+                 "p": json.dumps(a["params"], ensure_ascii=False),
+                 "s": json.dumps(a["steps"], ensure_ascii=False),
+                 "pc": a["preconditions"], "t": now})
+        db.session.commit()
+    return jsonify({"ok": True, "msg": "动作已保存"})
+
+
 # ================== 历史会话（DeepSeek 式：多会话持久化） ==================
 # 会话 = 消息序列（JSON），一轮 run 的 user/assistant 文本完成后追加落库。
 # 单表 JSON 存储（每会话几十 KB 内，无需独立消息表）。
@@ -658,7 +1198,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()
@@ -710,6 +1250,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:]})
 
 
@@ -811,10 +1352,24 @@ 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}))
 
-        tool_seq = []   # 本轮工具序列（经验提炼用）
+        def on_usage(usage):
+            """每次模型调用完成 → 推累计用量（前端实时刷新 token 计数）。"""
+            q.put(("usage", dict(usage)))
+
+        tool_seq = []    # 本轮工具序列（任务级配方提炼用）
+        tool_trace = []  # 结构化轨迹：{tool, args, result}（动作经验提炼用，判成败）
 
         def on_tool(step):
             # args 保留对象（json.dumps 序列化）——前端要解析 serial 做画面跟随；
@@ -824,11 +1379,16 @@ def _agent_thread(run_id, prompt, serial, cfg):
             if step.get("image"):
                 rec["image"] = _shrink_image(step["image"])
             q.put(("step", rec))
-            # 记录精简工具序列
+            # 记录精简工具序列 + 结构化轨迹（去 serial、结果截断）
             try:
                 args = step.get("args") or {}
                 brief = {k: v for k, v in args.items() if k != "serial"}
                 tool_seq.append(f"{step.get('tool')}({str(brief)[:60]})")
+                res = step.get("result")
+                # 可沉淀工具保留原始 result（_tool_ok 需按字段判成败）；其余只存摘要
+                tool_trace.append({"tool": step.get("tool"), "args": brief,
+                                   "result": res if step.get("tool") in _ACTION_TOOLS
+                                   else _brief_result(res)})
             except Exception:
                 pass
 
@@ -862,31 +1422,81 @@ def _agent_thread(run_id, prompt, serial, cfg):
         stop_evt = _stop_events.get(run_id)
 
         # 经验检索：相似历史任务的操作配方注入 system（自进化记忆）
-        exp_ctx = _find_experiences(prompt)
+        exp_ctx, exp_items = _find_experiences(prompt)
         if exp_ctx:
             _log.info("命中历史经验，注入参考配方")
+            brief = "；".join("".join(x.split())[:16] for x in exp_items[:2])
             q.put(("step", {"tool": "🧠 经验记忆",
-                            "args": f"命中 {exp_ctx.count(chr(10) + '- ')} 条同类历史经验，已注入参考",
+                            "args": f"命中 {len(exp_items)} 条同类历史经验，已注入参考"
+                                    + (f"：{brief}" if brief else ""),
                             "image": None}))
+        # 动作经验：可复用的命名动作（带元素定位），优先复用可跳过重新探索
+        act_ctx, act_items = _find_actions(prompt)
+        if act_ctx:
+            _log.info(f"命中可复用动作 {len(act_items)} 个，注入参考")
+            q.put(("step", {"tool": "🧠 动作经验",
+                            "args": f"命中 {len(act_items)} 个可复用动作，已注入参考"
+                                    + (f"：{'、'.join(act_items[:3])}" if act_items else ""),
+                            "image": None}))
+        recall_ctx = exp_ctx
+        if act_ctx:
+            recall_ctx += ("\n\n## 可复用动作（优先按其中的元素定位操作；"
+                           "若与当前界面不符，再自行截图确认）\n" + act_ctx)
+
+        mcp_url = getattr(getattr(agent, "s", None), "mcp_url", "")
+
+        def _mcp_unreachable(err):
+            """MCP 客户端在工具服务不可达/返回非 MCP 响应时只抛含糊字样，
+            识别出来以便给用户明确指引（默认端口 8033）。"""
+            m = str(err).lower()
+            return any(k in m for k in (
+                "server returned an error response", "connecterror",
+                "connection refused", "all connection attempts failed",
+                "connection error", "server disconnected",
+                "network is unreachable", "connect timeout"))
 
         async def _execute():
-            await agent._load_tools()
+            try:
-            return await agent.run_stream(prompt, target,
+                await agent._load_tools()
-                                          history=history,
+            except Exception as e:
-                                          on_delta=on_delta, on_tool=on_tool,
+                if _mcp_unreachable(e):
-                                          should_stop=lambda: bool(
+                    raise RuntimeError(
-                                              stop_evt and stop_evt.is_set()),
+                        f"MCP server(8033) 不可达：无法加载设备工具（{mcp_url}）。"
-                                          extra_context=exp_ctx)
+                        f"请确认 MCP server 已启动（本机可运行 "
+                        f"python -m mcp_server.mcp_server，默认端口 8033）") from e
+                raise
+            try:
+                return await agent.run_stream(prompt, target,
+                                              history=history,
+                                              on_delta=on_delta, on_tool=on_tool,
+                                              should_stop=lambda: bool(
+                                                  stop_evt and stop_evt.is_set()),
+                                              extra_context=recall_ctx,
+                                              on_usage=on_usage)
+            except Exception as e:
+                if _mcp_unreachable(e):
+                    raise RuntimeError(
+                        f"MCP server(8033) 连接中断：AI 无法继续操作设备（{mcp_url}）") from e
+                raise
 
         # 整体超时保护：卡死时结束，释放单实例
         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。
@@ -909,8 +1519,8 @@ def _agent_thread(run_id, prompt, serial, cfg):
         # 提炼/保存失败静默（不阻塞、不影响结果），只在成功时推送 🧠 卡片。
         if tool_seq:
             try:
-                recipe = _distill_experience(cfg, prompt, " -> ".join(tool_seq))
+                recipe = _clean_recipe(_distill_experience(cfg, prompt, " -> ".join(tool_seq)))
-                if recipe and "配方" not in recipe[:50]:
+                if recipe:
                     if _qualify_experience(prompt, recipe):
                         if _save_experience(prompt, recipe, " -> ".join(tool_seq)):
                             _log.info("经验已写入记忆库，随事件流提示")
@@ -918,9 +1528,22 @@ def _agent_thread(run_id, prompt, serial, cfg):
                                             "args": "本轮操作已提炼为经验并写入记忆库"
                                                     "（下次相似任务会自动参考）",
                                             "image": None}))
+                # 动作经验：把本轮**成功**步骤沉淀为命名动作（带元素定位，禁坐标）
+                acts = _distill_actions(cfg, prompt, tool_trace)
+                n_act = _save_actions(prompt, acts)
+                if n_act:
+                    q.put(("step", {"tool": "🧠 动作经验",
+                                    "args": f"已沉淀 {n_act} 个可复用动作"
+                                            "（含元素定位，下次同类任务可直接复用）",
+                                    "image": None}))
+                else:
+                    q.put(("step", {"tool": "🧠 动作经验",
+                                    "args": "本轮未沉淀动作（步骤以坐标定位为主，"
+                                            "缺少可复用的元素定位信息）",
+                                    "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 消息配对检查）
@@ -936,6 +1559,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/system_api.py

@@ -0,0 +1,78 @@
+"""系统管理 API（数据备份导出/导入）。仅管理员。
+
+导出：POST /api/system/backup/export  → 返回 zip 附件下载
+预览：POST /api/system/backup/preview → multipart 上传 zip/db，返回暂存 token + 表清单
+应用：POST /api/system/backup/apply    → 校验后落「重启生效」恢复任务
+
+导入涉及整库替换，只允许管理员操作（web/auth.admin_required）。
+"""
+from io import BytesIO
+
+from flask import Blueprint, jsonify, request, send_file
+
+from web.auth import admin_required
+from core import system_backup as sb
+from core.logger import get_logger
+
+_log = get_logger("web.system")
+
+bp = Blueprint("system", __name__)
+
+
+@bp.route("/api/system/backup/export", methods=["POST"])
+@admin_required
+def api_system_backup_export():
+    """生成导出 zip 并作为附件返回（含 users.db 快照 + manifest.json + 可选 apks）。"""
+    data = request.json or {}
+    include_apk = bool(data.get("include_apk", True))
+    try:
+        zip_path, fname, manifest = sb.create_export(include_apk=include_apk)
+    except sb.BackupError as e:
+        return jsonify({"ok": False, "error": str(e)}), 400
+    except Exception as e:
+        _log.error(f"导出备份失败: {e}")
+        return jsonify({"ok": False, "error": f"导出失败: {e}"}), 500
+
+    # 读入内存后立即删除磁盘文件再发送——Windows 上 send_file 流式发送时文件
+    # 句柄可能到 close 仍未释放，call_on_close 删不掉会残留；改 BytesIO 发送
+    # 则可确定性清理（导出为一次性下载，无需保留服务端副本）。
+    with open(zip_path, "rb") as f:
+        data = f.read()
+    sb.remove_quiet(zip_path)
+    resp = send_file(BytesIO(data), as_attachment=True, download_name=fname,
+                     mimetype="application/zip")
+    return resp
+
+
+@bp.route("/api/system/backup/preview", methods=["POST"])
+@admin_required
+def api_system_backup_preview():
+    """上传备份文件（zip/db）→ 暂存并校验 → 返回预览（表行数/schema/告警）。"""
+    f = request.files.get("file")
+    if not f or not f.filename:
+        return jsonify({"ok": False, "error": "未选择文件"}), 400
+    try:
+        token, info = sb.stage_upload(f)
+    except sb.BackupError as e:
+        return jsonify({"ok": False, "error": str(e)}), 400
+    except Exception as e:
+        _log.error(f"备份预览失败: {e}")
+        return jsonify({"ok": False, "error": f"解析文件失败: {e}"}), 500
+    _log.info(f"备份预览: {info.get('file_name')} "
+              f"(schema v{info.get('schema_version')}) token={token}")
+    return jsonify({"ok": True, "token": token, "preview": info})
+
+
+@bp.route("/api/system/backup/apply", methods=["POST"])
+@admin_required
+def api_system_backup_apply():
+    """确认应用导入：自动备份当前库 → 落待生效恢复任务（重启后生效）。"""
+    token = (request.json or {}).get("token", "")
+    try:
+        res = sb.apply_restore(str(token).strip())
+    except sb.BackupError as e:
+        return jsonify({"ok": False, "error": str(e)}), 400
+    except Exception as e:
+        _log.error(f"应用导入失败: {e}")
+        return jsonify({"ok": False, "error": f"应用导入失败: {e}"}), 500
+    return jsonify({"ok": True, **res})

web/tasks_api.py

@@ -54,13 +54,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 +106,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 +118,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 +137,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_server.py

@@ -40,6 +40,15 @@ app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
 login_manager = LoginManager(app)
 login_manager.login_view = "auth.login"  # 蓝图化后路由前缀 auth
 
+# 消费「待生效的备份恢复」：若存在 data/restore_pending/users.db，在 engine 首次
+# 打开数据库之前换位。导入必须重启生效——TaskManager 启动时读库入内存，
+# Windows 无法热替换正被持有的库文件。
+try:
+    from core.system_backup import consume_pending_restore
+    consume_pending_restore()
+except Exception as _e:
+    _log.error(f"消费备份恢复任务异常（不影响启动）: {_e}")
+
 # 先初始化数据库（含旧 JSON 迁移），再创建 TaskManager（需要 app context 读写 DB）
 init_db(app)
 # 设备池（本地清单 + adb 在线状态）：任务调度的数据源