chore: 初始化仓库（排除 adb 二进制文件以解决推送超时）

core/__init__.py

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

core/actions/__init__.py

@@ -0,0 +1,27 @@
+"""全局操作框架：所有 app 任务共用的 Action 基类与注册机制。
+
+为什么放这里：
+  抖音的点赞/评论 xpath 只适用抖音，留在 tasks/douyin/actions/。
+  但"操作"的抽象（BaseAction 接口、概率触发、注册机制）是通用的，
+  放这里让所有 app 任务共享同一套操作开发范式。
+
+加新 app 的专属操作：
+  在 tasks/<app>/actions/ 下建 .py，继承本模块的 BaseAction，
+  用 @register_action 装饰（注册到该 app 自己的注册表，见下方）。
+
+加跨 app 通用操作（如"滑动到下一个"、"等待元素出现"）：
+  在 core/actions/ 下建 .py，继承 BaseAction。
+"""
+from .base import (
+    BaseAction, ActionContext,
+    register_action, create_action_registry,
+    list_actions, get_action,
+    should_trigger,
+)
+
+__all__ = [
+    "BaseAction", "ActionContext",
+    "register_action", "create_action_registry",
+    "list_actions", "get_action",
+    "should_trigger",
+]

core/actions/base.py

@@ -0,0 +1,120 @@
+"""Action 基类与注册机制（全局通用，所有 app 任务共享接口）。
+
+设计要点：
+  1. BaseAction 定义统一接口：execute(d, params, worker) -> bool
+  2. 每个 app 任务有自己的注册表（create_action_registry），
+     互不污染——抖音的 like 和快手的 like 各注册各的。
+  3. 概率触发、状态上报等通用逻辑放这里，子类不重复写。
+  4. ActionContext 封装执行上下文，方便扩展（传 d/worker/进度/计数器）。
+
+新增 app 专属操作步骤（照着 tasks/douyin/actions/like.py 抄）：
+
+  1. 在 tasks/<app>/actions/ 下新建 my_action.py
+  2. 写一个 BaseAction 子类，用 @register_action 装饰，实现 execute：
+
+       from core.actions import BaseAction, register_action, should_trigger
+       from . import ACTIONS  # 本 app 的注册表
+
+       @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/<app>/actions/__init__.py 加：from . import my_action
+
+  做完前端自动出现该操作的可勾选项。
+"""
+import random
+
+from core.logger import get_logger
+
+_log = get_logger("action")
+
+
+class ActionContext:
+    """操作执行上下文，封装给 Action 用的所有依赖。
+
+    现在只是简单封装，后续可扩展（如传任务参数、设备信息、进度回调）。
+    Action 子类通过 worker 间接访问，或直接用 execute 的 d 参数。
+    """
+
+    def __init__(self, worker=None, params=None):
+        self.worker = worker
+        self.params = params or {}
+
+
+class BaseAction:
+    """所有操作的基类。子类实现 execute。
+
+    约定：
+      execute 返回 True  = 执行成功（会计入 action_counts）
+      execute 返回 False = 跳过/失败（不影响主流程，不抛异常）
+      execute 内部异常由调用方捕获，不影响其他操作和主循环
+    """
+    action_type = "base"
+    name = "基础操作"
+    description = ""
+    default_params = {}
+
+    def execute(self, d, params, worker):
+        """执行操作。
+
+        d: u2.Device — 已连好的设备
+        params: 本操作的参数 dict（已合并默认值）
+        worker: Worker 实例，可调 worker.set_action() 上报状态
+        返回 True=执行成功，False=跳过/失败。
+        """
+        raise NotImplementedError
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}({self.action_type})>"
+
+
+def should_trigger(rate):
+    """按概率决定是否触发（rate 是 0~1 的概率）。"""
+    return random.random() < rate
+
+
+def register_action(registry):
+    """装饰器：把 Action 类注册到指定注册表。
+
+    用法：
+        ACTIONS = create_action_registry()
+        @register_action(ACTIONS)
+        class MyAction(BaseAction): ...
+
+    每个 app 任务有自己的 ACTIONS 注册表，互不污染。
+    """
+    def _decorator(action_cls):
+        registry[action_cls.action_type] = action_cls
+        _log.debug(f"注册操作: {action_cls.action_type} -> {action_cls.__name__}")
+        return action_cls
+    return _decorator
+
+
+def create_action_registry():
+    """创建一个独立的操作注册表（每个 app 任务一个）。
+
+    返回 dict: action_type -> ActionClass
+    """
+    return {}
+
+
+def list_actions(registry):
+    """返回注册表中所有操作的元信息（供前端展示）。"""
+    return [{"action_type": a.action_type, "name": a.name,
+             "description": a.description,
+             "default_params": a.default_params} for a in registry.values()]
+
+
+def get_action(registry, action_type):
+    """按 action_type 取操作类。"""
+    return registry.get(action_type)

core/adb_helper.py

@@ -0,0 +1,154 @@
+"""adb 命令工具封装。
+
+并发关键：adb_connect 绝不 kill-server（会断开其他 worker 正在用的设备），
+用全局锁串行化连接阶段，connect 本身很快，串行不影响整体并发。
+"""
+import re
+import time
+import subprocess
+import threading
+
+from config import ADB_PATH
+from core.logger import get_logger
+
+_log = get_logger("core.adb")
+
+_ADB_LOCK = threading.Lock()
+
+
+def _adb(*args):
+    """执行 adb 命令，返回 (stdout+stderr) 文本。不用 shell=True，避免子进程环境问题。
+
+    用 bytes 模式自己解码（Windows 下 subprocess text=True 会用 GBK 读 adb 输出，
+    遇到非 GBK 字节会崩溃）。
+    """
+    r = subprocess.run([ADB_PATH, *args], capture_output=True)
+    out = (r.stdout or b"") + (r.stderr or b"")
+    try:
+        return out.decode("utf-8", errors="replace").strip()
+    except Exception:
+        return out.decode("gbk", errors="replace").strip()
+
+
+def get_foreground_app(remote_adb_url, timeout=3):
+    """获取设备当前前台 App 包名。
+
+    通过 adb shell dumpsys window 解析 mCurrentFocus。
+    remote_adb_url: adb 连接地址（如 192.168.20.17:12345），设备需已 adb connect。
+    返回包名字符串（如 com.ss.android.ugc.aweme），失败/无设备返回 None。
+    """
+    if not remote_adb_url:
+        return None
+    try:
+        r = subprocess.run(
+            [ADB_PATH, "-s", remote_adb_url, "shell",
+             "dumpsys window | grep mCurrentFocus"],
+            capture_output=True, timeout=timeout
+        )
+        out = (r.stdout or b"").decode("utf-8", errors="replace").strip()
+        if not out:
+            return None
+        low = out.lower()
+        if "device offline" in low or "device not found" in low or "error:" in low:
+            return None
+        # 解析 mCurrentFocus=Window{abc u0 com.xx/com.xx.MainActivity}
+        for line in out.split("\n"):
+            if "mCurrentFocus" not in line:
+                continue
+            # 提取 u0 后面的 token（包名/Activity 或包名）
+            m = re.search(r'\bu0\s+(\S+)', line)
+            if m:
+                token = m.group(1).rstrip("}")
+                if "/" in token:
+                    return token.split("/")[0]
+                return token or None
+        return None
+    except subprocess.TimeoutExpired:
+        return None
+    except Exception:
+        return None
+
+
+def adb_connect(remote_adb_url, retries=5):
+    """adb connect（带重试）。返回 True/False。
+
+    首次常因认证握手未就绪报 failed to authenticate，第2次重试通常 already connected。
+    STF remoteConnect 启用后端口监听可能需要几秒，所以重试间隔递增。
+    若全部重试失败，做一次 kill-server 硬重置后再试（long-running 进程的 adb daemon
+    可能状态坏掉，必须重置）。硬重置在全局锁内，会短暂影响并发 worker，但只在万不得已时触发。
+    """
+    with _ADB_LOCK:
+        if _try_connect(remote_adb_url, retries):
+            return True
+        # 全部失败，硬重置 adb server
+        _log.warning(f"{remote_adb_url} 重试耗尽，执行 kill-server 硬重置")
+        _adb("kill-server")
+        time.sleep(2)
+        _adb("start-server")
+        time.sleep(2)
+        return _try_connect(remote_adb_url, 3)
+    return False
+
+
+def _try_connect(remote_adb_url, retries):
+    """尝试连接，不 kill-server。返回 True/False。"""
+    for attempt in range(1, retries + 1):
+        out = _adb("connect", remote_adb_url)
+        _log.info(f"{remote_adb_url} 第 {attempt} 次尝试: {out}")
+        if "connected" in out.lower() and "failed" not in out.lower():
+            return True
+        time.sleep(1 + attempt)
+    return False
+
+
+def adb_connect_light(remote_adb_url):
+    """轻量 adb connect（扫描专用）：单次尝试，不重试，绝不 kill-server。
+
+    与 adb_connect 的区别：
+      - 不重试：失败立即返回 False
+      - 不 kill-server：避免断开其他 worker 正在使用的 ADB 连接
+    用于前台 App 扫描等非关键路径，连不上就跳过，不影响正在运行的任务。
+    """
+    with _ADB_LOCK:
+        out = _adb("connect", remote_adb_url)
+        if "connected" in out.lower() and "failed" not in out.lower():
+            return True
+        return False
+
+
+def adb_disconnect(remote_adb_url):
+    """adb disconnect。"""
+    try:
+        _adb("disconnect", remote_adb_url)
+    except Exception:
+        pass
+
+
+def identify_device(serial, duration=3):
+    """让设备响铃以供识别（直连 serial，不经过 STF）。
+
+    播放铃声 duration 秒后自动停止。
+    不 disconnect（避免断开 STF agent 共享的 adb 连接）。
+    返回 (ok, msg)。
+    """
+    import subprocess
+    if not adb_connect_light(serial):
+        return False, "adb connect 失败"
+    try:
+        # 异步启动铃声播放（cmd audio play-ringtone 会阻塞，用 Popen）
+        p = subprocess.Popen(
+            [ADB_PATH, "-s", serial, "shell", "cmd", "audio", "play-ringtone"],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        )
+        time.sleep(duration)
+        p.terminate()
+        # 停止铃声
+        subprocess.run(
+            [ADB_PATH, "-s", serial, "shell", "cmd", "audio", "stop-ringtone"],
+            capture_output=True, timeout=5,
+        )
+        _log.info(f"[{serial}] 识别响铃 {duration}s 完成")
+        return True, f"已响铃 {duration} 秒"
+    except Exception as e:
+        _log.warning(f"[{serial}] 识别响铃失败: {e}")
+        return False, str(e)

core/apk_manager.py

@@ -0,0 +1,389 @@
+"""APK 文件管理 + 批量安装。
+
+功能：
+  - upload: 保存 APK 到 data/apks/，用 pyaxmlparser 解析包名/版本/应用名，入库
+  - list_all: 列出所有已上传的 APK
+  - delete: 删文件 + 删数据库记录
+  - install: 批量安装到指定设备（后台线程，直连设备 adb）
+  - get_install_status: 获取安装进度
+
+设备连接策略（直连设备 IP:5555，完全绕过 STF occupy/release）：
+  - worker 运行中：跳过（避免打断任务）
+  - 其他设备（自己占用/空闲/他人占用）：直接 adb connect serial → install → disconnect
+    不经过 STF，不会触发 STF agent 清理，安装的 app 会永久保留
+  - serial 格式为 IP:5555（设备本身的 adb 网络地址），STF 返回的 serial 即此格式
+
+为什么不用 STF occupy/release：
+  STF release 会触发 agent 清理设备（卸载第三方 app、清除数据、回桌面），
+  导致刚安装的 app 被自动删除。直连设备完全绕过 STF，安装完断开连接即可。
+"""
+import os
+import time
+import uuid
+import threading
+import subprocess
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from config import APK_DIR, ADB_PATH
+from core.logger import get_logger
+from core.models import db, ApkFile as ApkRow
+from .stf_client import STFClient
+from .adb_helper import adb_disconnect
+from .device_worker import get_all_worker_status
+
+_log = get_logger("core.apk")
+
+# adb install 超时（秒）。大 APK 安装慢，给 5 分钟
+_INSTALL_TIMEOUT = 300
+# 并发安装数
+_INSTALL_CONCURRENCY = 5
+
+
+class ApkManager:
+    """APK 文件管理 + 批量安装。"""
+
+    def __init__(self, stf_client=None, app=None):
+        self.stf = stf_client or STFClient()
+        self.app = app  # Flask app，用于 db context
+        os.makedirs(APK_DIR, exist_ok=True)
+        self._lock = threading.Lock()
+        self._install_task = None  # 当前安装任务
+
+    def _db(self):
+        if self.app is None:
+            raise RuntimeError("ApkManager 未关联 Flask app")
+        return self.app.app_context()
+
+    # ================== 上传 ==================
+    def upload(self, file_storage):
+        """保存上传的 APK 文件，解析元信息，入库。
+
+        file_storage: werkzeug FileStorage 对象
+        返回: dict (APK 信息) 或 None（失败）
+        """
+        # 生成唯一 id
+        apk_id = uuid.uuid4().hex[:8]
+        original_name = file_storage.filename or f"{apk_id}.apk"
+        if not original_name.lower().endswith(".apk"):
+            original_name += ".apk"
+        disk_filename = f"{apk_id}.apk"
+        disk_path = os.path.join(APK_DIR, disk_filename)
+
+        # 保存文件
+        try:
+            file_storage.save(disk_path)
+        except Exception as e:
+            _log.error(f"保存 APK 文件失败: {e}")
+            return None
+
+        size = os.path.getsize(disk_path)
+        display_name = os.path.splitext(original_name)[0]
+        package_name = ""
+        version_name = ""
+        version_code = 0
+
+        # 解析 APK 元信息
+        try:
+            from pyaxmlparser import APK as APKParser
+            apk = APKParser(disk_path)
+            package_name = apk.package or ""
+            version_name = getattr(apk, "version_name", "") or ""
+            version_code = getattr(apk, "version_code", 0) or 0
+            # 应用名：优先 get_app_name()，其次 application.label
+            try:
+                display_name = apk.get_app_name() or display_name
+            except Exception:
+                try:
+                    display_name = apk.application.label or display_name
+                except Exception:
+                    pass
+            _log.info(f"解析 APK 成功: {display_name} ({package_name} v{version_name})")
+        except ImportError:
+            _log.warning("pyaxmlparser 未安装，跳过 APK 元信息解析")
+        except Exception as e:
+            _log.warning(f"解析 APK 元信息失败（不影响上传）: {e}")
+
+        # 入库
+        upload_time = time.strftime("%Y-%m-%d %H:%M:%S")
+        try:
+            with self._db():
+                row = ApkRow(id=apk_id, filename=disk_filename,
+                             display_name=display_name,
+                             package_name=package_name,
+                             version_name=version_name,
+                             version_code=version_code,
+                             size=size, upload_time=upload_time)
+                db.session.add(row)
+                db.session.commit()
+                _log.info(f"APK 上传成功: {display_name}({apk_id}) {size}字节")
+                return row.to_dict()
+        except Exception as e:
+            _log.error(f"APK 入库失败: {e}")
+            # 入库失败但文件已存，仍然返回基本信息
+            try:
+                os.remove(disk_path)
+            except Exception:
+                pass
+            return None
+
+    # ================== 列表 ==================
+    def list_all(self):
+        """列出所有 APK。"""
+        try:
+            with self._db():
+                rows = ApkRow.query.order_by(ApkRow.upload_time.desc()).all()
+                return [r.to_dict() for r in rows]
+        except Exception as e:
+            _log.error(f"列出 APK 失败: {e}")
+            return []
+
+    # ================== 删除 ==================
+    def delete(self, apk_id):
+        """删除 APK 文件和数据库记录。"""
+        try:
+            with self._db():
+                row = ApkRow.query.get(apk_id)
+                if not row:
+                    return False, "APK 不存在"
+                name = row.display_name or row.filename
+                # 删文件
+                disk_path = os.path.join(APK_DIR, row.filename)
+                if os.path.exists(disk_path):
+                    try:
+                        os.remove(disk_path)
+                    except Exception as e:
+                        _log.warning(f"删除 APK 文件失败: {e}")
+                # 删记录
+                db.session.delete(row)
+                db.session.commit()
+                _log.info(f"已删除 APK: {name}({apk_id})")
+                return True, f"已删除 {name}"
+        except Exception as e:
+            _log.error(f"删除 APK 失败: {e}")
+            return False, str(e)
+
+    # ================== 批量安装 ==================
+    def install(self, apk_id, serials):
+        """批量安装 APK 到指定设备（后台线程执行）。
+
+        参数:
+          apk_id: APK ID
+          serials: 设备 serial 列表
+
+        返回: (ok, msg)
+        """
+        with self._lock:
+            if self._install_task and not self._install_task.get("finished"):
+                return False, "已有安装任务正在进行，请等待完成"
+
+        # 查 APK 信息
+        try:
+            with self._db():
+                row = ApkRow.query.get(apk_id)
+                if not row:
+                    return False, "APK 不存在"
+                apk_path = os.path.join(APK_DIR, row.filename)
+                apk_name = row.display_name or row.filename
+                package_name = row.package_name or ""
+                if not os.path.exists(apk_path):
+                    return False, "APK 文件不存在"
+        except Exception as e:
+            return False, str(e)
+
+        if not serials:
+            return False, "未选择设备"
+
+        # 获取设备信息（型号等）
+        try:
+            all_devices = {d["serial"]: d for d in self.stf.list_all_devices()}
+        except Exception:
+            all_devices = {}
+
+        # 获取 worker 状态（判断设备是否运行中）
+        worker_status = {w["serial"]: w for w in get_all_worker_status()}
+
+        # 构造安装任务
+        items = {}
+        for s in serials:
+            dev = all_devices.get(s, {})
+            model = dev.get("model") or dev.get("manufacturer") or s
+            items[s] = {
+                "name": model,
+                "status": "pending",
+                "msg": "",
+            }
+
+        self._install_task = {
+            "apk_id": apk_id,
+            "apk_name": apk_name,
+            "started_at": time.time(),
+            "finished": False,
+            "total": len(serials),
+            "items": items,
+        }
+
+        # 后台线程执行安装
+        t = threading.Thread(target=self._install_worker,
+                             args=(apk_id, apk_path, apk_name, package_name,
+                                   serials, all_devices, worker_status),
+                             name="apk-install", daemon=True)
+        t.start()
+        _log.info(f"开始安装 {apk_name} 到 {len(serials)} 台设备")
+        return True, f"开始安装 {apk_name} 到 {len(serials)} 台设备"
+
+    def _install_worker(self, apk_id, apk_path, apk_name, package_name,
+                        serials, all_devices, worker_status):
+        """后台安装线程：直连设备安装，完全绕过 STF。"""
+        # 只跳过 worker 运行中的设备，其他设备（空闲/自己占用/他人占用）都直连安装
+        install_list = []
+        for s in serials:
+            w = worker_status.get(s, {})
+            if w.get("status") in ("running", "connecting"):
+                self._set_item(s, "skipped", "任务运行中，已跳过")
+                continue
+            install_list.append(s)
+
+        _log.info(f"安装任务 {apk_name}: 待安装={len(install_list)}, "
+                  f"跳过={len(serials)-len(install_list)}")
+
+        if install_list:
+            with ThreadPoolExecutor(max_workers=_INSTALL_CONCURRENCY) as pool:
+                futures = {pool.submit(self._install_one, s, apk_path,
+                                       package_name): s
+                           for s in install_list}
+                for fut in as_completed(futures, timeout=_INSTALL_TIMEOUT + 60):
+                    s = futures[fut]
+                    try:
+                        fut.result()
+                    except Exception as e:
+                        self._set_item(s, "failed", f"安装异常: {e}")
+
+        # 标记完成
+        if self._install_task:
+            self._install_task["finished"] = True
+        # 统计
+        success = sum(1 for v in self._install_task["items"].values()
+                      if v["status"] == "success")
+        failed = sum(1 for v in self._install_task["items"].values()
+                     if v["status"] == "failed")
+        skipped = sum(1 for v in self._install_task["items"].values()
+                      if v["status"] == "skipped")
+        _log.info(f"安装完成 {apk_name}: 成功={success}, 失败={failed}, 跳过={skipped}")
+
+    def _install_one(self, serial, apk_path, package_name=""):
+        """直连设备安装 APK。
+
+        serial 即设备的 adb 网络地址（IP:5555），直接 adb connect 即可。
+        不经过 STF occupy/release，安装完断开连接，app 永久保留。
+        """
+        from .adb_helper import _adb
+        self._set_item(serial, "installing", f"正在连接 {serial}...")
+        try:
+            # adb connect（带重试，设备网络可能需要几次握手）
+            connected = False
+            last_out = ""
+            for attempt in range(1, 4):  # 最多 3 次
+                out = _adb("connect", serial)
+                last_out = out
+                if "connected" in out.lower() and "failed" not in out.lower():
+                    connected = True
+                    break
+                _log.info(f"[{serial}] adb connect 第{attempt}次: {out}")
+                time.sleep(1 + attempt)
+            if not connected:
+                _log.warning(f"[{serial}] adb connect 失败: 输出={last_out}")
+                self._set_item(serial, "failed", f"adb connect 失败: {last_out[:150]}")
+                return
+
+            # 安装
+            self._set_item(serial, "installing", "正在安装...")
+            r = subprocess.run(
+                [ADB_PATH, "-s", serial, "install", "-r", apk_path],
+                capture_output=True, timeout=_INSTALL_TIMEOUT
+            )
+            out = ((r.stdout or b"") + (r.stderr or b""))
+            try:
+                out = out.decode("utf-8", errors="replace")
+            except Exception:
+                out = out.decode("gbk", errors="replace")
+            out = out.strip()
+            _log.info(f"[{serial}] adb install 返回码={r.returncode}, 输出={out[:300]}")
+            low = out.lower()
+            install_ok = False
+            if "success" in low:
+                install_ok = True
+            elif "already_installed" in low or "already installed" in low:
+                install_ok = True
+
+            if not install_ok:
+                msg = out.replace("\n", " ").strip()[:200]
+                self._set_item(serial, "failed", msg or "安装失败(returncode=%d)" % r.returncode)
+                _log.warning(f"[{serial}] APK 安装失败: {msg}")
+                return
+
+            # 安装后验证：查 pm list packages 确认包名是否真正存在
+            if package_name:
+                self._set_item(serial, "installing", "正在验证安装结果...")
+                try:
+                    rv = subprocess.run(
+                        [ADB_PATH, "-s", serial, "shell", "pm", "list", "packages", package_name],
+                        capture_output=True, timeout=30
+                    )
+                    vout = (rv.stdout or b"").decode("utf-8", errors="replace").strip()
+                    _log.info(f"[{serial}] pm list packages {package_name}: {vout[:200]}")
+                    if package_name in vout:
+                        self._set_item(serial, "success", "安装成功(已验证)")
+                        _log.info(f"[{serial}] APK 安装成功且已验证")
+                    else:
+                        self._set_item(serial, "failed", "adb返回Success但设备上未检测到包，可能被系统拦截")
+                        _log.warning(f"[{serial}] 安装验证失败: adb返回Success但pm list未找到 {package_name}")
+                except Exception as e:
+                    self._set_item(serial, "success", "安装成功(验证异常)")
+                    _log.warning(f"[{serial}] 安装验证异常: {e}")
+            else:
+                self._set_item(serial, "success", "安装成功")
+                _log.info(f"[{serial}] APK 安装成功(无包名，跳过验证)")
+        except subprocess.TimeoutExpired:
+            self._set_item(serial, "failed", "安装超时")
+        except Exception as e:
+            self._set_item(serial, "failed", str(e)[:200])
+            _log.exception(f"[{serial}] 安装异常")
+        finally:
+            # 断开 adb 连接（不影响设备，app 永久保留）
+            adb_disconnect(serial)
+
+    def _set_item(self, serial, status, msg=""):
+        """更新安装任务中某设备的状态。"""
+        if not self._install_task:
+            return
+        items = self._install_task["items"]
+        if serial not in items:
+            items[serial] = {"name": serial, "status": status, "msg": msg}
+        else:
+            items[serial]["status"] = status
+            items[serial]["msg"] = msg
+
+    def get_install_status(self):
+        """获取当前安装任务状态。"""
+        if not self._install_task:
+            return None
+        task = self._install_task
+        items = task["items"]
+        success = sum(1 for v in items.values() if v["status"] == "success")
+        failed = sum(1 for v in items.values() if v["status"] == "failed")
+        skipped = sum(1 for v in items.values() if v["status"] == "skipped")
+        installing = sum(1 for v in items.values() if v["status"] == "installing")
+        pending = sum(1 for v in items.values() if v["status"] == "pending")
+        return {
+            "apk_id": task["apk_id"],
+            "apk_name": task["apk_name"],
+            "started_at": task["started_at"],
+            "finished": task.get("finished", False),
+            "total": task["total"],
+            "success": success,
+            "failed": failed,
+            "skipped": skipped,
+            "installing": installing,
+            "pending": pending,
+            "items": dict(items),
+        }

core/device_worker.py

@@ -0,0 +1,433 @@
+"""设备生命周期 + 通用 Worker 基类 + 全局状态注册表 + 心跳看门狗。
+
+  STFDevice    — 单设备生命周期：acquire（占用+adb连接）→ release（断开+释放）
+  BaseWorker   — 通用 worker 基类：封装 STF 生命周期 + u2 连接 + 状态上报 + stop
+                 + 生命周期钩子(setup/teardown/on_error) + 心跳上报
+                 子类只需实现 run_task(d)，可选实现钩子，不用管 STF/adb/状态/异常
+  _WORKERS     — 全局状态注册表，供 web_server 读取实时状态
+  _watchdog    — 心跳看门狗线程，检测 worker 卡死
+
+新增任务只需写一个 BaseWorker 子类 + 一个 BaseTask 子类，
+完全不用碰这里的代码。
+"""
+import time
+import threading
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeout
+
+import uiautomator2 as u2
+
+from core.logger import get_logger
+from core.stf_client import DeviceOfflineError, STFError
+from .adb_helper import adb_connect, adb_disconnect
+
+_log = get_logger("core.worker")
+
+# 心跳超时阈值（秒）。worker 超过这个时间没更新心跳，判定为卡死
+_HEARTBEAT_TIMEOUT = 120
+# 看门狗检查间隔
+_WATCHDOG_INTERVAL = 30
+# u2.connect / d.info 超时（秒）。超过则放弃，避免 worker 永久 hang
+_U2_CONNECT_TIMEOUT = 30
+_U2_INFO_TIMEOUT = 10
+
+
+class STFDevice:
+    """单设备生命周期：acquire（占用+连接）→ release（断开+释放）。
+
+    用 try/finally 保证设备一定被释放，即使养号中途报错。
+    """
+
+    def __init__(self, stf_client, serial=None):
+        self.stf = stf_client
+        self.serial = serial
+        self.remote_adb_url = None
+
+    def acquire(self, serial=None):
+        self.serial = serial or self.serial or self._pick_free()
+        _log.info(f"[{self.serial}] 选定设备")
+
+        ok, msg = self.stf.occupy(self.serial)
+        if not ok:
+            raise STFError(f"占用设备失败: {msg}", "conflict")
+        _log.info(f"[{self.serial}] STF 占用成功")
+
+        # 优先直连设备 serial（当 serial 本身就是 IP:5555 时，如 Tailscale 网络）
+        # 这比 STF remoteConnect 桥接更稳定，避免桥接地址认证失败
+        if ":" in self.serial:
+            self.remote_adb_url = self.serial
+            _log.info(f"[{self.serial}] 直连设备: {self.remote_adb_url}")
+        else:
+            # serial 不是 IP:port 格式，走 STF remoteConnect 桥接
+            self.remote_adb_url = self.stf.remote_connect(self.serial)
+            _log.info(f"[{self.serial}] STF 桥接: {self.remote_adb_url}")
+
+        if not adb_connect(self.remote_adb_url):
+            raise STFError(f"adb connect 失败: {self.remote_adb_url}", "offline")
+        time.sleep(2)
+
+    def _pick_free(self):
+        free = self.stf.list_free_devices()
+        if not free:
+            raise STFError("没有可用的在线空闲设备", "offline")
+        return free[0]["serial"]
+
+    def release(self):
+        if not self.serial:
+            return
+        # 直连模式（remote_adb_url == serial）：不 disconnect
+        # STF agent 可能共享同一个 adb 连接，disconnect 会导致 STF 设备离线后重新连接
+        if self.remote_adb_url and self.remote_adb_url != self.serial:
+            adb_disconnect(self.remote_adb_url)
+            try:
+                self.stf.remote_disconnect(self.serial)
+            except Exception:
+                pass
+        try:
+            self.stf.release(self.serial)
+            _log.info(f"[{self.serial}] 已释放")
+        except Exception as e:
+            _log.warning(f"[{self.serial}] 释放失败: {e}")
+
+
+# ================== 全局 worker 状态注册表（供 web_server 读取） ==================
+_WORKERS_LOCK = threading.Lock()
+_WORKERS = {}  # serial -> status dict
+
+
+def get_all_worker_status():
+    with _WORKERS_LOCK:
+        return list(_WORKERS.values())
+
+
+def _update_status(serial, **fields):
+    with _WORKERS_LOCK:
+        s = _WORKERS.setdefault(serial, {"serial": serial})
+        s.update(fields)
+        s["last_heartbeat"] = time.time()
+
+
+def _remove_worker(serial):
+    with _WORKERS_LOCK:
+        _WORKERS.pop(serial, None)
+
+
+def get_worker_heartbeat(serial):
+    """返回 worker 最近一次心跳时间，没有返回 0。"""
+    with _WORKERS_LOCK:
+        return _WORKERS.get(serial, {}).get("last_heartbeat", 0)
+
+
+# ================== 心跳看门狗 ==================
+class _Watchdog(threading.Thread):
+    """后台线程：检测 worker 心跳超时，自动标记异常并设置 stop 信号。
+
+    worker 卡死（如 u2 操作 hang 住）时，看门狗能发现并标记状态，
+    避免设备一直被占用却不干活。
+    """
+
+    def __init__(self):
+        super().__init__(daemon=True, name="worker-watchdog")
+        self._stop = threading.Event()
+
+    def run(self):
+        while not self._stop.wait(_WATCHDOG_INTERVAL):
+            try:
+                self._check()
+            except Exception as e:
+                _log.error(f"看门狗检查异常: {e}")
+
+    def _check(self):
+        now = time.time()
+        with _WORKERS_LOCK:
+            stale = []
+            for serial, s in _WORKERS.items():
+                # 只检查运行中的 worker
+                if s.get("status") not in ("running", "connecting"):
+                    continue
+                hb = s.get("last_heartbeat", 0)
+                if hb and now - hb > _HEARTBEAT_TIMEOUT:
+                    stale.append(serial)
+        for serial in stale:
+            _log.error(f"[{serial}] 心跳超时 {now - get_worker_heartbeat(serial):.0f}s，标记卡死")
+            _update_status(serial, status="error",
+                           last_error=f"心跳超时 {_HEARTBEAT_TIMEOUT}s，worker 可能卡死")
+
+    def stop(self):
+        self._stop.set()
+
+
+_watchdog = None
+
+
+def start_watchdog():
+    """启动看门狗（web_server 启动时调一次）。"""
+    global _watchdog
+    if _watchdog is None or not _watchdog.is_alive():
+        _watchdog = _Watchdog()
+        _watchdog.start()
+        _log.info("心跳看门狗已启动")
+
+
+def stop_watchdog():
+    """停止看门狗。"""
+    global _watchdog
+    if _watchdog:
+        _watchdog.stop()
+        _watchdog = None
+
+
+# ================== 通用 Worker 基类 ==================
+class BaseWorker(threading.Thread):
+    """通用 worker 基类。
+
+    自动处理：STF 占用/释放、u2 连接、状态上报、异常捕获、stop 信号、心跳。
+    子类只需实现 run_task(d) 方法，专注业务逻辑。
+
+    生命周期（基类 run() 已封装，不要重写）：
+      1. acquire 设备（STF 占用 + adb 连接）
+      2. u2.connect 拿到 d
+      3. 调用 setup(d)        ← 子类可选钩子，做初始化
+      4. 调用子类 run_task(d)  ← 业务逻辑
+      5. 调用 teardown(d)     ← 子类可选钩子，做清理
+      6. finally: release 设备
+
+    子类可选钩子：
+      setup(d)          — run_task 前的初始化（如启动 app、检查登录）。默认空。
+      teardown(d)       — run_task 后的清理（无论成功失败）。默认空。
+      on_error(d, err)  — run_task 抛异常时回调。默认记录日志。
+
+    子类可用工具方法：
+      self.stopped()       — 判断是否被要求停止（循环里检查）
+      self.set_action(s)   — 上报当前动作（同时刷新心跳）
+      self.set_progress()  — 上报进度字段（同时刷新心跳）
+      self.heartbeat()     — 手动刷新心跳（长操作中间调）
+
+    进度上报规范（通用，适配任意 app）：
+      self.set_progress(done=5, total=80, unit="视频")
+        - done: 已完成数量（int）
+        - total: 总数量（int）
+        - unit: 计数单位（str，如 "视频"/"轮次"/"条"）
+        - action_counts: 操作计数 dict（可选，如 {"like": 3, "comment": 1}）
+        - 也可传任意业务字段，前端会原样展示在"进度"列
+      示例：
+        self.set_progress(done=5, total=80, unit="视频",
+                          action_counts={"like": 3, "comment": 1})
+      前端展示：进度条 + "5/80 视频" + 操作计数徽章
+
+    运行时长终止（通用，适配任意 app）：
+      self.max_duration — 最大运行时长（秒），0=不限时
+      self.is_time_up() — 判断是否已达 max_duration
+      子类在循环里检查 self.stopped() or self.is_time_up()
+      到时自动停（自然结束，不是 error），状态=done
+
+    异常分类（影响上层重试策略）：
+      DeviceOfflineError — 设备掉线/不可用，不重试（换设备也没用）
+      其他异常           — 可重试
+    """
+
+    def __init__(self, stf_client, serial, params=None, daemon=True):
+        super().__init__(daemon=daemon)
+        self.stf = stf_client
+        self.serial = serial
+        self.params = params or {}
+        self._stop_flag = threading.Event()
+        self.d = None  # u2.Device，run_task 里用
+        # 通用进度字段（子类通过 set_progress 上报）
+        self._progress = {"done": 0, "total": 0, "unit": "",
+                          "action_counts": {}}
+        # 通用运行时长终止（子类设 max_duration>0 启用）
+        self.max_duration = 0           # 秒，0=不限时
+        self._start_time = 0.0          # run_task 开始时间戳
+
+    def _start_timer(self):
+        """子类在 run_task 开头调用，启动运行时长计时。"""
+        self._start_time = time.time()
+
+    def is_time_up(self):
+        """是否已达最大运行时长。max_duration=0 时永远返回 False。"""
+        if self.max_duration <= 0 or self._start_time <= 0:
+            return False
+        return (time.time() - self._start_time) >= self.max_duration
+
+    def elapsed(self):
+        """已运行时长（秒）。run_task 未启动时返回 0。"""
+        if self._start_time <= 0:
+            return 0
+        return int(time.time() - self._start_time)
+
+    def stop(self):
+        """外部调用，请求停止（子类应在循环里检查 self.stopped()）。"""
+        self._stop_flag.set()
+
+    def stopped(self):
+        """子类在循环里调用，判断是否被要求停止。"""
+        return self._stop_flag.is_set()
+
+    def set_action(self, action):
+        """上报当前动作（子类用）。同时刷新心跳。"""
+        _update_status(self.serial, current_action=action)
+
+    def set_progress(self, **fields):
+        """上报进度字段（子类用）。同时刷新心跳。
+
+        通用字段（前端会解析展示）：
+          done (int)         — 已完成数量
+          total (int)        — 总数量
+          unit (str)         — 计数单位（"视频"/"轮次"/"条"）
+          action_counts (dict) — 操作计数 {"like": 3, "comment": 1}
+
+        也可传任意业务字段，会合并到 progress 里，前端原样展示。
+
+        示例：
+          self.set_progress(done=5, total=80, unit="视频",
+                            action_counts={"like": 3, "comment": 1})
+        """
+        self._progress.update(fields)
+        # 同步到全局状态字典，前端通过 get_status 读取
+        _update_status(self.serial, progress=dict(self._progress))
+
+    def heartbeat(self):
+        """手动刷新心跳。长操作中间调，避免看门狗误判卡死。"""
+        _update_status(self.serial, last_heartbeat=time.time())
+
+    # ================== 子类实现/可选钩子 ==================
+    def run_task(self, d):
+        """子类实现：拿到 u2.Device d，做具体业务。
+
+        不需要管 STF 占用/释放、异常、状态上报，基类已处理。
+        循环里记得检查 self.stopped() 以便响应停止请求。
+        """
+        raise NotImplementedError
+
+    def setup(self, d):
+        """run_task 前的初始化钩子。默认空，子类按需重写。
+
+        典型用途：启动 app、检查登录状态、进入主页。
+        抛异常会中断任务（走 on_error）。
+        """
+
+    def teardown(self, d):
+        """run_task 后的清理钩子（无论成功失败都调）。默认空，子类按需重写。
+
+        典型用途：退出 app、清理临时文件。
+        抛异常只记日志，不影响主流程。
+        """
+
+    def on_error(self, d, error):
+        """run_task 抛异常时的回调。默认空，子类按需重写。
+
+        典型用途：截图保存现场、上报错误详情。
+        """
+
+    # ================== 基类主循环（不要重写） ==================
+    def run(self):
+        """基类主循环：不要重写。子类实现 run_task + 可选钩子。"""
+        device = STFDevice(self.stf, serial=self.serial)
+        _update_status(self.serial, status="connecting", stf_occupied=False,
+                       last_error="", remote_adb_url="", model="",
+                       current_action="")
+        try:
+            device.acquire()
+            remote = device.remote_adb_url
+            # u2.connect 可能 hang 住（atx-agent 无响应），用线程池+超时保护
+            self.d = self._u2_connect_with_timeout(remote)
+            if self.d is None:
+                raise STFError(f"u2.connect 超时 {_U2_CONNECT_TIMEOUT}s，atx-agent 无响应", "offline")
+            _log.info(f"[{self.serial}] u2 连接成功")
+            model = ""
+            try:
+                info = self._u2_info_with_timeout()
+                if info:
+                    model = info.get("productName") or ""
+            except Exception:
+                pass
+            _update_status(self.serial, status="running", stf_occupied=True,
+                           remote_adb_url=remote, model=model)
+
+            # setup 钩子
+            try:
+                self.setup(self.d)
+            except Exception as e:
+                _log.error(f"[{self.serial}] setup 异常: {e}")
+                raise
+
+            # 业务逻辑
+            _log.info(f"[{self.serial}] 进入 run_task，开始执行业务逻辑")
+            self.run_task(self.d)
+            _log.info(f"[{self.serial}] run_task 执行完毕")
+
+            # teardown 钩子（成功路径）
+            try:
+                self.teardown(self.d)
+            except Exception as e:
+                _log.warning(f"[{self.serial}] teardown 异常: {e}")
+
+            if not self.stopped():
+                _update_status(self.serial, status="done")
+
+        except DeviceOfflineError as e:
+            # 设备掉线，不重试
+            _log.error(f"[{self.serial}] 设备离线: {e}")
+            _update_status(self.serial, status="error", last_error=str(e))
+            self._safe_on_error(e)
+        except Exception as e:
+            err_str = str(e)
+            # 识别 Windows TCP 端口耗尽（WinError 10048）或 adb server 连接失败
+            # 这类错误是临时性的，重试时需要更长退避等端口释放
+            is_transient = ("10048" in err_str
+                            or "connect to adb server failed" in err_str
+                            or "Unable to connect to uiautomator2 server" in err_str)
+            if is_transient:
+                _log.error(f"[{self.serial}] ADB/u2 连接错误（可能端口耗尽）: {e}")
+                _update_status(self.serial, status="error",
+                               last_error=f"[transient] {e}")
+            else:
+                _log.error(f"[{self.serial}] 异常: {e}", exc_info=True)
+                _update_status(self.serial, status="error", last_error=str(e))
+            self._safe_on_error(e)
+        finally:
+            try:
+                device.release()
+            except Exception as e:
+                _log.warning(f"[{self.serial}] release 异常: {e}")
+            # 只在仍在运行/连接中时才标记 released；
+            # done/error/failed 等终态保持不变，避免覆盖业务结果
+            with _WORKERS_LOCK:
+                cur = _WORKERS.get(self.serial, {}).get("status")
+            if cur in ("running", "connecting"):
+                _update_status(self.serial, stf_occupied=False, status="released")
+            else:
+                _update_status(self.serial, stf_occupied=False)
+
+    def _u2_connect_with_timeout(self, remote):
+        """u2.connect 带超时保护，避免 atx-agent 无响应时永久 hang。"""
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            fut = pool.submit(u2.connect, remote)
+            try:
+                return fut.result(timeout=_U2_CONNECT_TIMEOUT)
+            except FuturesTimeout:
+                _log.error(f"[{self.serial}] u2.connect 超时 {_U2_CONNECT_TIMEOUT}s")
+                return None
+            except Exception as e:
+                _log.error(f"[{self.serial}] u2.connect 异常: {e}")
+                return None
+
+    def _u2_info_with_timeout(self):
+        """self.d.info 带超时保护，避免 atx-agent 无响应时永久 hang。"""
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            fut = pool.submit(lambda: self.d.info)
+            try:
+                return fut.result(timeout=_U2_INFO_TIMEOUT)
+            except FuturesTimeout:
+                _log.warning(f"[{self.serial}] d.info 超时 {_U2_INFO_TIMEOUT}s，跳过型号获取")
+                return None
+            except Exception as e:
+                _log.warning(f"[{self.serial}] d.info 异常: {e}")
+                return None
+
+    def _safe_on_error(self, error):
+        """安全调用 on_error 钩子，不让钩子异常影响主流程。"""
+        try:
+            self.on_error(self.d, error)
+        except Exception as e:
+            _log.warning(f"[{self.serial}] on_error 钩子异常: {e}")

core/logger.py

@@ -0,0 +1,84 @@
+"""统一日志系统：按模块分文件，带时间戳和级别，自动滚动。
+
+用法：
+    from core.logger import get_logger
+    log = get_logger("task")          # 写 logs/task.log + 控制台
+    log.info("开始任务")
+    log.error("失败", exc_info=True)
+
+模块划分：
+    core    — 核心程序（STF/adb/worker/task_manager）
+    task    — 任务执行（worker 业务逻辑）
+    web     — web_server 请求/管理
+    action  — 操作执行（点赞/评论等）
+
+所有日志同时输出到控制台和对应文件，logs/ 目录自动创建。
+文件按 10MB 滚动，保留 5 个历史文件。
+"""
+import os
+import logging
+from logging.handlers import RotatingFileHandler
+
+_LOG_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "logs")
+os.makedirs(_LOG_DIR, exist_ok=True)
+
+# 已创建的 logger，避免重复添加 handler
+_LOGGERS = {}
+
+# 模块 → 文件名映射
+_MODULE_FILES = {
+    "core": "core.log",
+    "task": "task.log",
+    "web": "web.log",
+    "action": "action.log",
+}
+
+_FORMAT = "%(asctime)s [%(levelname)s] [%(name)s] %(message)s"
+_DATE_FMT = "%Y-%m-%d %H:%M:%S"
+
+
+def get_logger(name="core"):
+    """获取指定模块的 logger。
+
+    name: 模块名（core/task/web/action），决定写哪个文件。
+          也可传子模块名如 "task.douyin"，会归到 task.log。
+    返回配置好的 logging.Logger。
+    """
+    if name in _LOGGERS:
+        return _LOGGERS[name]
+
+    # 归类到对应文件：取顶层模块名
+    top = name.split(".")[0]
+    filename = _MODULE_FILES.get(top, "core.log")
+
+    log = logging.getLogger(name)
+    log.setLevel(logging.DEBUG)
+    # 避免向 root logger 传播导致重复输出
+    log.propagate = False
+
+    fmt = logging.Formatter(_FORMAT, _DATE_FMT)
+
+    # 文件 handler：10MB 滚动，保留 5 个
+    file_path = os.path.join(_LOG_DIR, filename)
+    fh = RotatingFileHandler(file_path, maxBytes=10 * 1024 * 1024,
+                             backupCount=5, encoding="utf-8")
+    fh.setLevel(logging.DEBUG)
+    fh.setFormatter(fmt)
+
+    # 控制台 handler
+    ch = logging.StreamHandler()
+    ch.setLevel(logging.INFO)
+    ch.setFormatter(fmt)
+
+    log.addHandler(fh)
+    log.addHandler(ch)
+
+    _LOGGERS[name] = log
+    return log
+
+
+# 兼容旧代码的 print 风格：紧急排查时可临时用
+def log_print(msg, level="info", module="core"):
+    """print 的替代品，转发到 logging。"""
+    log = get_logger(module)
+    getattr(log, level, log.info)(msg)

core/models.py

@@ -0,0 +1,242 @@
+"""SQLAlchemy 数据模型 + db 初始化（用户/设备分组/任务计划）。
+
+为什么放这里：
+  web_server 和 task_manager 都要访问这些模型，放 core/ 避免循环依赖。
+  web_server 负责初始化 db（app context），task_manager 只读写数据。
+
+模型说明：
+  User        — 后台用户（Flask-Login 认证）
+  DeviceGroup — 设备分组（持久化，替代旧 groups.json）
+  TaskJob     — 任务计划（持久化，替代旧 jobs.json）
+
+字段设计：
+  DeviceGroup.serials 用 JSON 存列表（SQLite 无数组类型）
+  TaskJob.target/params/schedule/retry 用 JSON 存嵌套结构
+  Flask-Admin 默认用 TextArea 编辑 JSON，够用且通用
+"""
+import os
+import json
+import hashlib
+
+from flask_sqlalchemy import SQLAlchemy
+from flask_login import UserMixin
+
+from core.logger import get_logger
+
+_log = get_logger("core.models")
+
+db = SQLAlchemy()
+
+
+class User(UserMixin, db.Model):
+    """后台用户。"""
+    id = db.Column(db.Integer, primary_key=True)
+    username = db.Column(db.String(80), unique=True, nullable=False)
+    password_hash = db.Column(db.String(120), nullable=False)
+    is_admin = db.Column(db.Boolean, default=True)
+
+    def set_password(self, password):
+        self.password_hash = hashlib.sha256(password.encode()).hexdigest()
+
+    def check_password(self, password):
+        return self.password_hash == hashlib.sha256(password.encode()).hexdigest()
+
+    def __repr__(self):
+        return f"<User {self.username}>"
+
+
+class DeviceGroup(db.Model):
+    """设备分组（替代旧 groups.json 的 DeviceGroup 类）。"""
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String(80), unique=True, nullable=False)
+    serials = db.Column(db.Text, default="[]")        # JSON 列表
+    description = db.Column(db.Text, default="")
+
+    def get_serials(self):
+        try:
+            return json.loads(self.serials or "[]")
+        except Exception:
+            return []
+
+    def set_serials(self, lst):
+        self.serials = json.dumps(lst or [], ensure_ascii=False)
+
+    def to_dict(self):
+        return {"name": self.name, "serials": self.get_serials(),
+                "description": self.description or ""}
+
+    def __repr__(self):
+        return f"<Group {self.name}>"
+
+
+class TaskJob(db.Model):
+    """任务计划（替代旧 jobs.json 的 TaskJob 类）。
+
+    字段含义和旧 TaskJob 一致，只是持久化方式从 JSON 文件改到 SQLite。
+    """
+    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")
+    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
+    retry = db.Column(db.Text, default='{"max_attempts":1,"delay":60}')  # JSON
+    enabled = db.Column(db.Boolean, default=True)
+
+    def _load_json(self, field, default):
+        try:
+            return json.loads(getattr(self, field) or default)
+        except Exception:
+            return json.loads(default)
+
+    def _dump_json(self, field, value):
+        setattr(self, field, json.dumps(value or {}, ensure_ascii=False))
+
+    def get_target(self): return self._load_json("target", '{"mode":"all"}')
+    def set_target(self, v): self._dump_json("target", v)
+    def get_params(self): return self._load_json("params", "{}")
+    def set_params(self, v): self._dump_json("params", v)
+    def get_schedule(self): return self._load_json("schedule", '{"mode":"once"}')
+    def set_schedule(self, v): self._dump_json("schedule", v)
+    def get_retry(self): return self._load_json("retry", '{"max_attempts":1,"delay":60}')
+    def set_retry(self, v): self._dump_json("retry", v)
+
+    def to_dict(self):
+        return {"id": self.id, "name": self.name, "task_type": self.task_type,
+                "target": self.get_target(), "params": self.get_params(),
+                "schedule": self.get_schedule(), "retry": self.get_retry(),
+                "enabled": self.enabled}
+
+    def __repr__(self):
+        return f"<TaskJob {self.name}>"
+
+
+class ApkFile(db.Model):
+    """上传的 APK 文件元信息（应用管理功能）。"""
+    id = db.Column(db.String(32), primary_key=True)   # uuid 前 8 位
+    filename = db.Column(db.String(255), nullable=False)  # 磁盘文件名 (id.apk)
+    display_name = db.Column(db.String(120), default="")  # 应用名
+    package_name = db.Column(db.String(200), default="")  # 包名
+    version_name = db.Column(db.String(50), default="")   # 版本号
+    version_code = db.Column(db.Integer, default=0)        # 版本码
+    size = db.Column(db.Integer, default=0)                # 文件大小(字节)
+    upload_time = db.Column(db.String(20), default="")     # 上传时间
+
+    def to_dict(self):
+        return {"id": self.id, "filename": self.filename,
+                "display_name": self.display_name or "",
+                "package_name": self.package_name or "",
+                "version_name": self.version_name or "",
+                "version_code": self.version_code or 0,
+                "size": self.size or 0,
+                "upload_time": self.upload_time or ""}
+
+    def __repr__(self):
+        return f"<ApkFile {self.display_name}>"
+
+
+def init_db(app):
+    """在 Flask app context 里初始化数据库 + 创建默认管理员。
+
+    web_server 启动时调用。自动迁移旧 groups.json/jobs.json 到 SQLite。
+    """
+    db.init_app(app)
+    with app.app_context():
+        db.create_all()
+        _ensure_default_admin()
+        _migrate_old_json()
+
+
+def _ensure_default_admin():
+    """首次启动创建默认管理员 admin/admin123。"""
+    if not User.query.filter_by(username="admin").first():
+        u = User(username="admin", is_admin=True)
+        u.set_password("admin123")
+        db.session.add(u)
+        db.session.commit()
+        _log.info("已创建默认管理员 admin/admin123，请及时改密码")
+
+
+def _migrate_old_json():
+    """把旧 groups.json / jobs.json 迁移到 SQLite（仅首次）。
+
+    迁移策略：
+      1. 仅当数据库对应表为空时才迁移（首次启动场景）
+      2. 迁移成功后立即把 JSON 文件重命名为 <name>.json.migrated，
+         保留备份但永不再迁移——避免"用户删完全部任务后重启又从旧文件复原"
+      3. 若数据库已有数据但 JSON 文件仍在（历史残留），直接归档，
+         避免将来数据库被清空后又触发迁移导致已删任务复原
+      4. 迁移任务时顺手剔除已废弃的 comment action 配置，
+         避免 _load 阶段还要再写回一次
+    """
+    from config import DATA_DIR
+
+    # 迁移分组
+    groups_file = os.path.join(DATA_DIR, "groups.json")
+    if os.path.exists(groups_file) and DeviceGroup.query.count() == 0:
+        try:
+            with open(groups_file, encoding="utf-8") as f:
+                groups = json.load(f)
+            for g in groups:
+                if not DeviceGroup.query.filter_by(name=g["name"]).first():
+                    row = DeviceGroup(name=g["name"],
+                                      description=g.get("description", ""))
+                    row.set_serials(g.get("serials", []))
+                    db.session.add(row)
+            db.session.commit()
+            _log.info(f"已迁移 {len(groups)} 个分组到数据库")
+            _archive_migrated(groups_file)
+        except Exception as e:
+            _log.error(f"迁移 groups.json 失败: {e}")
+
+    # 迁移任务
+    jobs_file = os.path.join(DATA_DIR, "jobs.json")
+    if os.path.exists(jobs_file) and TaskJob.query.count() == 0:
+        try:
+            with open(jobs_file, encoding="utf-8") as f:
+                jobs = json.load(f)
+            for j in jobs:
+                if TaskJob.query.get(j["id"]):
+                    continue
+                params = j.get("params", {})
+                # 剔除已废弃的 comment action，避免带入数据库
+                actions = params.get("actions", {})
+                if "comment" in actions:
+                    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"),
+                              enabled=j.get("enabled", True))
+                row.set_target(j.get("target", {"mode": "all"}))
+                row.set_params(params)
+                row.set_schedule(j.get("schedule", {"mode": "once"}))
+                row.set_retry(j.get("retry", {"max_attempts": 1, "delay": 60}))
+                db.session.add(row)
+            db.session.commit()
+            _log.info(f"已迁移 {len(jobs)} 个任务到数据库")
+            _archive_migrated(jobs_file)
+        except Exception as e:
+            _log.error(f"迁移 jobs.json 失败: {e}")
+
+    # 清理历史残留：数据库已有数据但 JSON 文件仍在（修复前遗留下来的文件）。
+    # 不归档的话，用户哪天删光所有任务/分组，count==0 又会触发迁移导致已删数据复原。
+    if DeviceGroup.query.count() > 0 and os.path.exists(groups_file):
+        _archive_migrated(groups_file)
+    if TaskJob.query.count() > 0 and os.path.exists(jobs_file):
+        _archive_migrated(jobs_file)
+
+
+def _archive_migrated(file_path):
+    """把已迁移的 JSON 文件重命名为 <name>.migrated，避免下次重启再迁移。
+
+    保留备份以便排查，但 _migrate_old_json 的 exists 判断会跳过它。
+    重命名失败只警告不抛出，不影响启动。
+    """
+    archived = file_path + ".migrated"
+    try:
+        if os.path.exists(archived):
+            os.remove(archived)
+        os.rename(file_path, archived)
+        _log.info(f"已归档迁移文件: {os.path.basename(file_path)} -> {os.path.basename(archived)}")
+    except Exception as e:
+        _log.warning(f"归档 {file_path} 失败（不影响运行）: {e}")

core/stf_client.py

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

core/task_manager.py

@@ -0,0 +1,734 @@
+"""通用任务管理框架：任务类型注册 + 设备分组 + 任务计划 + 定时调度 + 重试 + 持久化。
+
+设计目标：可扩展，未来加非抖音任务只需注册新的 Task 类。
+
+核心概念：
+  TaskType  — 任务类型（如"抖音养号"），可注册，含默认参数和 worker 工厂
+  DeviceGroup — 设备分组，持久化到 SQLite（core.models.DeviceGroup）
+  TaskJob   — 任务计划（类型+目标+参数+调度+重试），持久化到 SQLite（core.models.TaskJob）
+  TaskManager — 统管调度器、分组、任务、运行实例、状态
+
+定时：APScheduler BackgroundScheduler，cron 触发后为每个目标设备起 worker。
+  支持三种调度模式：
+    once     — 手动/立即执行，不注册 cron
+    cron     — 仅注册启动 cron（到点启动 worker）
+    cron_stop — 注册启动 cron + 停止 cron（到点启动，到点停止）
+重试：单设备 worker 失败后按 retry.max_attempts 重试，间隔 retry.delay。
+并发：同一 serial 同时只允许一个 worker，避免冲突。
+"""
+import os
+import json
+import time
+import uuid
+import threading
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from apscheduler.schedulers.background import BackgroundScheduler
+from apscheduler.triggers.cron import CronTrigger
+
+from config import DATA_DIR
+from core.logger import get_logger
+from core.models import db, DeviceGroup as GroupRow, TaskJob as JobRow
+from .stf_client import STFClient, DeviceOfflineError
+from .adb_helper import get_foreground_app, adb_connect_light, adb_disconnect
+from .device_worker import (
+    get_all_worker_status, _update_status, _remove_worker,
+    _WORKERS, _WORKERS_LOCK,
+    start_watchdog, stop_watchdog,
+)
+from tasks import list_task_types, get_task_class
+
+_log = get_logger("core.tm")
+
+
+# ================== 设备分组 ==================
+class DeviceGroup:
+    def __init__(self, name, serials=None, description=""):
+        self.name = name
+        self.serials = serials or []
+        self.description = description
+
+    def to_dict(self):
+        return {"name": self.name, "serials": self.serials, "description": self.description}
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(d["name"], d.get("serials", []), d.get("description", ""))
+
+
+# ================== 任务计划 ==================
+class TaskJob:
+    """一个任务计划：什么任务、跑哪些设备、什么参数、何时跑、失败重试策略。"""
+
+    def __init__(self, job_id=None, name="", task_type="douyin_nurture",
+                 target=None, params=None, schedule=None, retry=None, enabled=True):
+        self.id = job_id or uuid.uuid4().hex[:8]
+        self.name = name
+        self.task_type = task_type
+        # target: {"mode": "all"|"group"|"serial", "group_name": "", "serial": ""}
+        self.target = target or {"mode": "all"}
+        self.params = params or {}
+        self.schedule = schedule or {"mode": "once"}  # {"mode":"once"|"cron", "cron":"0 9 * * *"}
+        self.retry = retry or {"max_attempts": 1, "delay": 60}
+        self.enabled = enabled
+
+    def to_dict(self):
+        return {"id": self.id, "name": self.name, "task_type": self.task_type,
+                "target": self.target, "params": self.params,
+                "schedule": self.schedule, "retry": self.retry, "enabled": self.enabled}
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(d["id"], d["name"], d["task_type"], d.get("target"),
+                   d.get("params"), d.get("schedule"), d.get("retry"), d.get("enabled", True))
+
+    def resolve_serials(self, manager):
+        """根据 target 解析出实际要跑的 serial 列表。"""
+        mode = self.target.get("mode", "all")
+        if mode == "serial":
+            return [self.target["serial"]]
+        if mode == "group":
+            g = manager.groups.get(self.target.get("group_name"))
+            return list(g.serials) if g else []
+        # all：返回所有空闲设备
+        try:
+            return [d["serial"] for d in manager.stf.list_free_devices()]
+        except Exception:
+            return []
+
+
+# ================== 前台 App 扫描器 ==================
+class _ForegroundScanner:
+    """前台 App 扫描器：手动触发，获取所有在线设备的前台 App。
+
+    设计原则：**不打扰设备**，扫描过程不会让设备退出当前 App。
+
+    策略（按设备状态区分获取逻辑）：
+      - worker 运行中设备：用已有 remote_adb_url 直接查询（已有 adb 连接，无额外开销）
+      - 空闲设备：直接 adb connect <serial> → 查询 → adb disconnect（绕过 STF，不打扰设备）
+      - 被别人占用的设备：标记 "他人占用"
+      - STF occupy/release 会打扰设备（可能退回桌面），绝不使用
+
+    serial 格式为 IP:5555（设备本身的 adb 网络地址），可直接 adb connect。
+    adb connect/disconnect 只建立/断开调试连接，不影响设备 UI。
+    dumpsys window 只读取窗口状态，不执行任何操作。
+    """
+
+    def __init__(self, stf):
+        self.stf = stf
+        self._cache = {}            # serial -> app_name
+        self._cache_lock = threading.Lock()
+        self._scanning = threading.Event()  # 标记是否正在扫描
+        self._last_scan_time = 0    # 上次扫描完成时间戳
+        self._last_scan_count = 0   # 上次扫描设备数
+
+    def stop(self):
+        """兼容 TaskManager.shutdown() 调用。"""
+        pass
+
+    def get(self, serial):
+        """读取缓存的前台 App。"""
+        with self._cache_lock:
+            return self._cache.get(serial)
+
+    @property
+    def is_scanning(self):
+        return self._scanning.is_set()
+
+    @property
+    def last_scan_time(self):
+        return self._last_scan_time
+
+    def scan_once(self):
+        """手动触发一次扫描（后台线程执行，不阻塞调用者）。
+
+        如果已有扫描在进行中，直接返回 False。
+        """
+        if self._scanning.is_set():
+            return False
+        t = threading.Thread(target=self._scan_all, name="fg-scan-once", daemon=True)
+        t.start()
+        return True
+
+    def _scan_all(self):
+        """扫描所有在线设备（后台线程执行）。
+
+        按设备归属分四类处理：
+          1. worker 运行中：用已有 remote_adb_url 直接查询（无额外开销）
+          2. 自己账户占用但无 worker：调用 STF remoteConnect 获取隧道查询
+             （不 occupy/release，不打扰设备 UI）
+          3. 完全空闲设备（using=False）：尝试轻量 adb connect serial
+             （单次尝试，不 kill-server，不影响其他 worker）
+          4. 被他人占用：标记 "(他人占用)"
+        """
+        self._scanning.set()
+        _log.info("前台 App 扫描已启动")
+        try:
+            all_devices = self.stf.list_all_devices()
+        except Exception as e:
+            _log.error("前台 App 扫描: 获取设备列表失败: %s", e)
+            self._scanning.clear()
+            return
+
+        # 自己账户已占用的设备列表（用于区分"自己占用"vs"他人占用"）
+        try:
+            my_serials = {d["serial"] for d in self.stf.list_my_devices()}
+        except Exception:
+            my_serials = set()
+
+        worker_status = {w["serial"]: w for w in get_all_worker_status()}
+
+        # 分类设备
+        have_conn = {}    # serial -> remote_adb_url（worker 运行中，已有 adb 连接）
+        my_owned = []      # 自己账户占用但无 running worker，需 remoteConnect 获取隧道
+        free_serials = []  # 完全空闲设备，尝试轻量 adb connect
+        skip_serials = []  # 被他人占用
+
+        for dev in all_devices:
+            if not dev.get("present"):
+                continue
+            serial = dev.get("serial", "")
+            if not serial:
+                continue
+            w = worker_status.get(serial, {})
+            url = w.get("remote_adb_url")
+            if url and w.get("status") in ("running", "connecting"):
+                # 1. 设备正在执行任务，已有 adb 连接，直接查询
+                have_conn[serial] = url
+            elif serial in my_serials:
+                # 2. 自己账户占用但无 worker，可安全 remoteConnect（不打扰设备）
+                my_owned.append(serial)
+            elif dev.get("using"):
+                # 4. 被他人占用
+                skip_serials.append(serial)
+            else:
+                # 3. 完全空闲，尝试轻量 adb connect（不 kill-server）
+                free_serials.append(serial)
+
+        results = {}
+        _log.info("前台 App 扫描分类: 运行中=%d, 自己占用=%d, 空闲=%d, 他人占用=%d",
+                  len(have_conn), len(my_owned), len(free_serials), len(skip_serials))
+
+        # 1. worker 运行中设备：用已有 remote_adb_url 查询（并发 10）
+        if have_conn:
+            with ThreadPoolExecutor(max_workers=min(10, len(have_conn))) as pool:
+                futures = {pool.submit(get_foreground_app, url): s
+                           for s, url in have_conn.items()}
+                for fut in as_completed(futures, timeout=15):
+                    s = futures[fut]
+                    try:
+                        results[s] = fut.result()
+                    except Exception:
+                        results[s] = None
+
+        # 2. 自己占用设备：remoteConnect 获取隧道 → 查询 → 断开（并发 5，不打扰设备）
+        if my_owned:
+            with ThreadPoolExecutor(max_workers=min(5, len(my_owned))) as pool:
+                futures = {pool.submit(self._scan_my_owned, s): s
+                           for s in my_owned}
+                for fut in as_completed(futures, timeout=30):
+                    s = futures[fut]
+                    try:
+                        results[s] = fut.result()
+                    except Exception:
+                        results[s] = None
+
+        # 3. 空闲设备：轻量 adb connect serial → 查询 → disconnect（并发 10）
+        if free_serials:
+            with ThreadPoolExecutor(max_workers=min(10, len(free_serials))) as pool:
+                futures = {pool.submit(self._scan_free, s): s
+                           for s in free_serials}
+                for fut in as_completed(futures, timeout=20):
+                    s = futures[fut]
+                    try:
+                        results[s] = fut.result()
+                    except Exception:
+                        results[s] = None
+
+        # 4. 被别人占用的设备
+        for s in skip_serials:
+            results[s] = "(他人占用)"
+
+        # 更新缓存
+        with self._cache_lock:
+            for s, app in results.items():
+                self._cache[s] = app
+
+        self._last_scan_time = time.time()
+        self._last_scan_count = len(results)
+        self._scanning.clear()
+        _log.info("前台 App 扫描完成: %d 台设备", len(results))
+
+    def _scan_my_owned(self, serial):
+        """自己账户占用的设备：通过 STF remoteConnect 获取隧道查询。
+
+        不调用 occupy/release，只建立/断开 ADB 隧道，不打扰设备 UI。
+        """
+        try:
+            url = self.stf.remote_connect(serial)
+            if not url:
+                return None
+            try:
+                if not adb_connect_light(url):
+                    return None
+                return get_foreground_app(url)
+            finally:
+                adb_disconnect(url)
+                self.stf.remote_disconnect(serial)
+        except Exception:
+            return None
+
+    def _scan_free(self, serial):
+        """空闲设备：轻量 adb connect serial 查询（单次尝试，不 kill-server）。
+
+        serial 通常为 IP:5555，若设备 5555 端口未开放则快速失败。
+        绝不重试、绝不 kill-server，避免影响正在运行的 worker。
+        """
+        try:
+            if not adb_connect_light(serial):
+                return "(不可达)"
+            try:
+                return get_foreground_app(serial)
+            finally:
+                adb_disconnect(serial)
+        except Exception:
+            return None
+
+
+# ================== 任务管理器 ==================
+class TaskManager:
+    def __init__(self, stf_client=None, app=None):
+        self.stf = stf_client or STFClient()
+        self.app = app  # Flask app，用于 db context
+        self.scheduler = BackgroundScheduler(timezone="Asia/Shanghai")
+        self.scheduler.start()
+        start_watchdog()  # 启动心跳看门狗
+        self.groups = {}        # name -> DeviceGroup(内存业务对象)
+        self.jobs = {}          # id -> TaskJob(内存业务对象)
+        self._running = {}      # serial -> {"worker", "job_id", "started_at", "attempt"}
+        self._lock = threading.Lock()
+        self._fg_scanner = _ForegroundScanner(self.stf)
+        self._load()
+
+    def _db(self):
+        """获取 db context。task_manager 在后台线程跑，需自己推 app context。"""
+        if self.app is None:
+            raise RuntimeError("TaskManager 未关联 Flask app，无法访问数据库")
+        return self.app.app_context()
+
+    # ---- 持久化（SQLite，替代旧 JSON 文件）----
+    def _load(self):
+        """从数据库加载分组和任务到内存。"""
+        try:
+            with self._db():
+                for row in GroupRow.query.all():
+                    g = DeviceGroup(row.name, row.get_serials(), row.description or "")
+                    self.groups[g.name] = g
+                dirty = False  # 标记是否有任务参数需要写回
+                for row in JobRow.query.all():
+                    j = TaskJob(job_id=row.id, name=row.name, task_type=row.task_type,
+                               target=row.get_target(), params=row.get_params(),
+                               schedule=row.get_schedule(), retry=row.get_retry(),
+                               enabled=row.enabled)
+                    # 数据规整：移除已废弃的 action 配置（如抖音的 comment 已删除）
+                    if j.task_type == "douyin_nurture":
+                        actions = j.params.get("actions", {})
+                        if "comment" in actions:
+                            del actions["comment"]
+                            row.set_params(j.params)
+                            dirty = True
+                            _log.info(f"任务 {j.name}({j.id}): 已移除废弃的 comment 配置")
+                    self.jobs[j.id] = j
+                if dirty:
+                    db.session.commit()
+                    _log.info("已将规整后的任务参数写回数据库")
+            _log.info(f"从数据库加载 {len(self.groups)} 个分组, {len(self.jobs)} 个任务")
+        except Exception as e:
+            _log.error(f"从数据库加载失败: {e}")
+        # 恢复启用的 cron 任务
+        for job in self.jobs.values():
+            if job.enabled and job.schedule.get("mode") in ("cron", "cron_stop"):
+                self._add_cron(job)
+
+    def _save_groups(self):
+        """保存所有分组到数据库（upsert）。"""
+        with self._db():
+            for g in self.groups.values():
+                row = GroupRow.query.filter_by(name=g.name).first()
+                if not row:
+                    row = GroupRow(name=g.name)
+                    db.session.add(row)
+                row.set_serials(g.serials)
+                row.description = g.description
+            db.session.commit()
+
+    def _save_jobs(self):
+        """保存所有任务到数据库（upsert）。"""
+        with self._db():
+            for j in self.jobs.values():
+                row = JobRow.query.get(j.id)
+                if not row:
+                    row = JobRow(id=j.id)
+                    db.session.add(row)
+                row.name = j.name
+                row.task_type = j.task_type
+                row.set_target(j.target)
+                row.set_params(j.params)
+                row.set_schedule(j.schedule)
+                row.set_retry(j.retry)
+                row.enabled = j.enabled
+            db.session.commit()
+
+    # ---- 分组管理 ----
+    def add_group(self, name, serials, description=""):
+        g = DeviceGroup(name, serials, description)
+        self.groups[name] = g
+        self._save_groups()
+        return g
+
+    def update_group(self, name, serials=None, description=None):
+        g = self.groups.get(name)
+        if not g:
+            return None
+        if serials is not None:
+            g.serials = serials
+        if description is not None:
+            g.description = description
+        self._save_groups()
+        return g
+
+    def delete_group(self, name):
+        if name in self.groups:
+            del self.groups[name]
+            self._save_groups()
+            return True
+        return False
+
+    # ---- 任务计划管理 ----
+    def add_job(self, name, task_type, target, params, schedule, retry, enabled=True):
+        job = TaskJob(name=name, task_type=task_type, target=target, params=params,
+                      schedule=schedule, retry=retry, enabled=enabled)
+        self.jobs[job.id] = job
+        if enabled and schedule.get("mode") in ("cron", "cron_stop"):
+            self._add_cron(job)
+        self._save_jobs()
+        return job
+
+    def update_job(self, job_id, **fields):
+        job = self.jobs.get(job_id)
+        if not job:
+            return None
+        # 更新前先移除旧 cron
+        was_cron = job.enabled and job.schedule.get("mode") in ("cron", "cron_stop")
+        if was_cron:
+            self._remove_cron(job_id)
+        for k, v in fields.items():
+            if v is not None and hasattr(job, k):
+                setattr(job, k, v)
+        if job.enabled and job.schedule.get("mode") in ("cron", "cron_stop"):
+            self._add_cron(job)
+        self._save_jobs()
+        return job
+
+    def delete_job(self, job_id):
+        self._remove_cron(job_id)
+        if job_id in self.jobs:
+            del self.jobs[job_id]
+            self._save_jobs()
+            return True
+        return False
+
+    def toggle_job(self, job_id, enabled):
+        job = self.jobs.get(job_id)
+        if not job:
+            return None
+        job.enabled = enabled
+        if enabled and job.schedule.get("mode") in ("cron", "cron_stop"):
+            self._add_cron(job)
+        else:
+            self._remove_cron(job_id)
+        self._save_jobs()
+        return job
+
+    # ---- APScheduler 集成 ----
+    def _cron_id(self, job_id, kind="start"):
+        """生成 cron job id。kind: start=启动 cron，stop=停止 cron。"""
+        return f"job_{job_id}_{kind}"
+
+    def _add_cron(self, job):
+        """注册定时任务。支持三种模式：
+          - once: 不注册 cron
+          - cron: 只注册启动 cron（到点启动 worker）
+          - cron_stop: 注册启动 cron + 停止 cron（到点启动，到点停止）
+        """
+        mode = job.schedule.get("mode", "once")
+        if mode not in ("cron", "cron_stop"):
+            return
+
+        start_cron = job.schedule.get("cron", "")
+        if start_cron:
+            try:
+                trigger = CronTrigger.from_crontab(start_cron)
+            except Exception as e:
+                _log.error(f"启动 cron 解析失败 {start_cron}: {e}")
+            else:
+                self.scheduler.add_job(self._on_cron_trigger, trigger, args=[job.id],
+                                       id=self._cron_id(job.id, "start"),
+                                       replace_existing=True)
+                _log.info(f"已注册启动定时 {job.name}({job.id}) cron={start_cron}")
+
+        if mode == "cron_stop":
+            stop_cron = job.schedule.get("stop_cron", "")
+            if stop_cron:
+                try:
+                    trigger = CronTrigger.from_crontab(stop_cron)
+                except Exception as e:
+                    _log.error(f"停止 cron 解析失败 {stop_cron}: {e}")
+                else:
+                    self.scheduler.add_job(self._on_cron_stop, trigger, args=[job.id],
+                                           id=self._cron_id(job.id, "stop"),
+                                           replace_existing=True)
+                    _log.info(f"已注册停止定时 {job.name}({job.id}) stop_cron={stop_cron}")
+
+    def _remove_cron(self, job_id):
+        """移除该任务的所有 cron job（启动 + 停止）。"""
+        for kind in ("start", "stop"):
+            try:
+                self.scheduler.remove_job(self._cron_id(job_id, kind))
+            except Exception:
+                pass
+
+    def _on_cron_trigger(self, job_id):
+        """cron 触发：启动该任务的所有目标设备 worker。"""
+        job = self.jobs.get(job_id)
+        if not job:
+            return
+        _log.info(f"定时触发: {job.name}({job.id})")
+        self._run_job(job)
+
+    def _on_cron_stop(self, job_id):
+        """停止 cron 触发：停止该任务正在运行的所有 worker。
+
+        只停本 job 启动的 worker，不影响其他任务。
+        """
+        job = self.jobs.get(job_id)
+        if not job:
+            return
+        with self._lock:
+            items = [(s, info) for s, info in self._running.items()
+                     if info.get("job_id") == job_id]
+        stopped = []
+        for serial, info in items:
+            w = info.get("worker")
+            if w and w.is_alive():
+                w.stop()
+                stopped.append(serial)
+        _log.info(f"定时停止 {job.name}({job.id}): 停止 {len(stopped)} 台设备 {stopped}")
+
+    def run_job_now(self, job_id):
+        """立即执行任务（手动触发）。"""
+        job = self.jobs.get(job_id)
+        if not job:
+            return {"ok": False, "error": "任务不存在"}
+        # 在独立线程跑，不阻塞调用方
+        t = threading.Thread(target=self._run_job, args=(job,), daemon=True)
+        t.start()
+        return {"ok": True, "msg": f"任务 {job.name} 已触发"}
+
+    def _run_job(self, job):
+        """执行任务：为每个目标设备起 worker（含重试循环）。"""
+        serials = job.resolve_serials(self)
+        if not serials:
+            _log.warning(f"任务 {job.name} 无可用设备")
+            return
+        task_cls = get_task_class(job.task_type)
+        if not task_cls:
+            _log.error(f"未知任务类型: {job.task_type}")
+            return
+        task = task_cls()
+        max_attempts = max(1, job.retry.get("max_attempts", 1))
+        delay = job.retry.get("delay", 60)
+
+        for serial in serials:
+            # 每台设备一个重试循环线程，互不影响
+            t = threading.Thread(target=self._run_with_retry,
+                                 args=(task, serial, job, max_attempts, delay), daemon=True)
+            t.start()
+
+    def _run_with_retry(self, task, serial, job, max_attempts, delay):
+        """单设备任务执行 + 重试。
+
+        异常分类：
+          DeviceOfflineError — 设备掉线，立即放弃不重试（换设备也没用）
+          其他异常           — 按 max_attempts 重试
+        """
+        for attempt in range(1, max_attempts + 1):
+            # 同一 serial 同时只能一个 worker
+            with self._lock:
+                if serial in self._running:
+                    _log.warning(f"{serial} 已有任务在跑，跳过 (job={job.name})")
+                    return
+                self._running[serial] = {"job_id": job.id, "started_at": time.time(),
+                                         "attempt": attempt, "task_type": job.task_type}
+            _update_status(serial, task_job=job.name, attempt=attempt,
+                           max_attempts=max_attempts)
+
+            worker = None
+            try:
+                worker = task.create_worker(self.stf, serial, job.params)
+                with self._lock:
+                    self._running[serial]["worker"] = worker
+                _log.info(f"{serial} 开始任务 {job.name} (第{attempt}/{max_attempts}次)")
+                worker.start()
+                worker.join()  # 等待 worker 结束
+                # worker 正常结束（done 或被 stop）
+                with self._lock:
+                    self._running.pop(serial, None)
+                # 判断是否成功：看 status
+                with _WORKERS_LOCK:
+                    st = _WORKERS.get(serial, {}).get("status")
+                # 清除 task_job 标记，避免前端误判"运行中"
+                _update_status(serial, task_job="")
+                if st == "done":
+                    _log.info(f"{serial} 任务 {job.name} 成功完成")
+                    return
+                if st == "released" and attempt == 1:
+                    # 被手动停止，不重试
+                    return
+                _log.warning(f"{serial} 任务未成功(status={st})")
+            except DeviceOfflineError as e:
+                # 设备掉线，立即放弃，不重试
+                _log.error(f"{serial} 设备离线，放弃任务 {job.name}: {e}")
+                with self._lock:
+                    self._running.pop(serial, None)
+                _update_status(serial, status="failed", task_job="",
+                               last_error=f"设备离线: {e}")
+                return
+            except Exception as e:
+                _log.error(f"{serial} 执行异常: {e}", exc_info=True)
+                with self._lock:
+                    self._running.pop(serial, None)
+                _update_status(serial, task_job="")
+
+            if attempt < max_attempts:
+                # 检查是否是端口耗尽类临时错误，需要更长退避等端口释放
+                with _WORKERS_LOCK:
+                    err = _WORKERS.get(serial, {}).get("last_error", "")
+                if err.startswith("[transient]"):
+                    # Windows TCP 端口耗尽，TIME_WAIT 默认 2-4 分钟，等 120 秒
+                    extra_delay = max(delay, 120)
+                    _log.info(f"{serial} ADB 连接临时错误（端口耗尽），{extra_delay}s 后重试 ({attempt+1}/{max_attempts})")
+                    time.sleep(extra_delay)
+                else:
+                    _log.info(f"{serial} {delay}s 后重试 ({attempt+1}/{max_attempts})")
+                    time.sleep(delay)
+
+        _log.error(f"{serial} 任务 {job.name} 重试耗尽，放弃")
+        _update_status(serial, status="failed", last_error=f"{job.name} 重试{max_attempts}次失败")
+
+    # ---- 运行控制 ----
+    def stop_device(self, serial):
+        """停止指定设备的 worker。"""
+        with self._lock:
+            info = self._running.get(serial)
+        if not info:
+            return False
+        w = info.get("worker")
+        if w and w.is_alive():
+            w.stop()
+            return True
+        return False
+
+    def stop_all(self):
+        """停止所有运行中的 worker。"""
+        with self._lock:
+            items = list(self._running.items())
+        stopped = []
+        for serial, info in items:
+            w = info.get("worker")
+            if w and w.is_alive():
+                w.stop()
+                stopped.append(serial)
+        return stopped
+
+    def get_running(self):
+        with self._lock:
+            return {s: dict(v) for s, v in self._running.items()}
+
+    # ---- 状态查询（带缓存，避免 STF 请求阻塞前端）----
+    _status_cache = None       # (timestamp, data, error)
+    _status_cache_lock = threading.Lock()
+    _STATUS_CACHE_TTL = 5.0    # 缓存 5 秒，前端 5 秒刷新刚好命中
+
+    def get_status(self):
+        """综合状态：STF 设备池 + 本地 worker + 运行中的任务。
+
+        带 5 秒缓存：STF 请求慢时避免每次 /api/status 都打 STF 阻塞 Flask。
+        worker 状态实时读（内存，无 IO），不受缓存影响。
+        """
+        with self._status_cache_lock:
+            if self._status_cache:
+                ts, cached, err = self._status_cache
+                if time.time() - ts < self._STATUS_CACHE_TTL:
+                    if err:
+                        return None, err
+                    # 用缓存的设备列表 + 实时 worker 状态重新组装
+                    return self._merge_status(cached), None
+        # 缓存过期或不存在，重新拉 STF
+        try:
+            all_devices = self.stf.list_all_devices()
+        except Exception as e:
+            with self._status_cache_lock:
+                self._status_cache = (time.time(), None, str(e))
+            return None, f"获取设备列表失败: {e}"
+        with self._status_cache_lock:
+            self._status_cache = (time.time(), all_devices, None)
+        return self._merge_status(all_devices), None
+
+    def _merge_status(self, all_devices):
+        """用 STF 设备列表 + 实时 worker 状态 + 前台 App 组装返回结果。"""
+        worker_status = {w["serial"]: w for w in get_all_worker_status()}
+        running = self.get_running()
+
+        result = []
+        for dev in all_devices:
+            serial = dev.get("serial", "")
+            owner = dev.get("owner")
+            w = worker_status.get(serial, {})
+            r = running.get(serial, {})
+            result.append({
+                "serial": serial,
+                "model": dev.get("model") or w.get("model", "") or dev.get("product", ""),
+                "device_name": dev.get("name") or "",
+                "present": dev.get("present", False),
+                "ready": dev.get("ready", False),
+                "stf_occupied": dev.get("using", False),
+                "owner": owner.get("name", "") if owner else "",
+                "worker_status": w.get("status", "idle"),
+                "foreground_app": self._fg_scanner.get(serial),
+                # 通用进度字段（任意 app 通用，前端统一解析展示）
+                # 结构：{"done": int, "total": int, "unit": str, "action_counts": dict}
+                "progress": w.get("progress", {}),
+                "current_action": w.get("current_action", ""),
+                "last_error": w.get("last_error", ""),
+                "running_job": r.get("job_id", ""),
+                "task_job": w.get("task_job", ""),
+                "attempt": r.get("attempt", 0),
+            })
+        return result
+
+    def list_all_serials(self):
+        """返回 STF 上所有在线设备的 serial 列表（供分组表单勾选用）。
+
+        复用 get_status 缓存，避免开页面时阻塞。
+        """
+        devices, err = self.get_status()
+        if err or not devices:
+            return []
+        return [d["serial"] for d in devices if d.get("present")]
+
+    def shutdown(self):
+        self.stop_all()
+        self._fg_scanner.stop()
+        stop_watchdog()
+        self.scheduler.shutdown(wait=False)

core/u2_helper.py

@@ -0,0 +1,114 @@
+"""uiautomator2 通用辅助函数。
+
+所有任务都可复用：应用启动保障、等待首页、安全点击、随机操作等。
+具体业务逻辑（如抖音首页特征元素判断）不放这里，放各自 task 文件。
+"""
+import time
+import random
+
+from core.logger import get_logger
+
+_log = get_logger("core.u2")
+
+
+def ensure_app_running(d, package, max_restart=3, home_check=None):
+    """确保 app 在前台运行，被人为退出/崩溃则自动重启。
+
+    d: u2.Device
+    package: 包名
+    max_restart: 最大重启次数
+    home_check: 可选回调 d->bool，判断是否进入主页。
+                默认只看包名（包名对就返回 True，和原抖音逻辑一致）。
+    返回 True 表示 app 在前台；连续重启失败返回 False。
+    """
+    home_check = home_check or (lambda d: True)
+    for attempt in range(1, max_restart + 1):
+        try:
+            cur = d.app_current()
+        except Exception:
+            cur = {}
+        if cur.get("package") == package and home_check(d):
+            return True
+        _log.info(f"{package} 不在前台(当前:{cur})，第 {attempt}/{max_restart} 次重启...")
+        try:
+            d.app_start(package, wait=True)
+            time.sleep(3)
+            if home_check(d):
+                return True
+        except Exception as e:
+            _log.warning(f"重启异常: {e}")
+        time.sleep(3)
+    return False
+
+
+def wait_for_app_home(d, package, home_check, timeout=40):
+    """等待 app 进入主页。
+
+    home_check: d->bool 回调，返回 True 表示已进入主页。
+    抖音主页 Activity 名仍叫 SplashActivity，不能靠 Activity 名判断，
+    要用界面特征元素（由调用方通过 home_check 传入）。
+    """
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            cur = d.app_current()
+        except Exception:
+            cur = {}
+        if cur.get("package") == package and home_check(d):
+            return True
+        time.sleep(2)
+    return False
+
+
+def random_sleep(min_s, max_s):
+    """随机睡眠（模拟人类操作间隔）。"""
+    time.sleep(random.uniform(min_s, max_s))
+
+
+def safe_click(el, timeout=1):
+    """安全点击：元素存在才点，不抛异常。返回是否点击成功。"""
+    try:
+        if el.exists(timeout=timeout):
+            el.click()
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def safe_set_text(el, text, timeout=1):
+    """安全输入文本：元素存在才输入，不抛异常。返回是否成功。"""
+    try:
+        if el.exists(timeout=timeout):
+            el.set_text(text)
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def find_and_click(d, timeout=1, **selectors):
+    """按定位器找元素并点击，找不到不抛异常。返回是否成功。
+
+    用法：find_and_click(d, text="首页") 或 find_and_click(d, description="搜索")
+    """
+    try:
+        el = d(**selectors)
+        if el.exists(timeout=timeout):
+            el.click()
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def random_swipe_up(d, width_ratio=0.5, height_start=0.8, height_end=0.2, duration=None):
+    """随机上滑（刷视频常用）。坐标按屏幕比例算，适配不同分辨率。
+
+    duration: 滑动时长(秒)，None 则随机 0.25~0.50s。
+    """
+    info = d.info
+    w, h = info["displayWidth"], info["displayHeight"]
+    dur = duration or random.uniform(0.25, 0.50)
+    d.swipe(int(w * width_ratio), int(h * height_start),
+            int(w * width_ratio), int(h * height_end), dur)