阶段0: 设备池（SQLite devices 表 + core/device_pool.py 清单/在线状态/CRUD，首次启动自动从 STF 导入）+ STF 摘除迁移计划文档

core/device_pool.py

@@ -0,0 +1,162 @@
+"""设备池（STF 替代数据源）：SQLite devices 表 = 设备清单，本地 adb = 在线状态。
+
+阶段 0：纯新增模块，不改现有行为。task_manager / web_server 的 STF 调用
+在阶段 1 逐个切换到本模块，阶段 3 摘除 STF 后删除 seed 相关代码。
+
+设计：
+  - list_configured() — devices 表里 enabled 的设备（清单，管理页维护）
+  - list_online()     — 本机 `adb devices` 里 state=device 的设备（实时）
+  - list_ready()      — configured ∩ online（调度用，取代 STF list_free_devices）
+  - CRUD              — add/update/remove/set_enabled（设备池管理页用）
+  - 首次启动自动从 STF 导入现有设备（一次性，app_meta 标记防重复）
+
+红线：全模块不 connect / 不 kill-server / 不 disconnect，遵守既有技术约束。
+后台线程（task_manager 等）调用时由本模块自行推 app context，调用方无需关心。
+"""
+import time
+
+from sqlalchemy import text
+
+from core.adb_helper import _adb
+from core.logger import get_logger
+from core.models import db, Device
+
+_log = get_logger("core.device_pool")
+
+_app = None
+
+
+def init_app(app):
+    """web_server 启动时调用：绑定 Flask app，并做首次设备导入。"""
+    global _app
+    _app = app
+    try:
+        _seed_from_stf_if_empty()
+    except Exception as e:
+        _log.warning(f"设备池初始化异常（不影响启动）: {e}")
+
+
+def _ctx():
+    """后台线程访问 db 需自行推 app context（与 task_manager._db 同思路）。"""
+    if _app is None:
+        raise RuntimeError("device_pool 未关联 Flask app（web_server 启动时调用 init_app）")
+    return _app.app_context()
+
+
+# ================== 清单 ==================
+def list_configured(enabled_only=True):
+    """devices 表里的设备清单（serial 列表）。"""
+    with _ctx():
+        q = Device.query
+        if enabled_only:
+            q = q.filter_by(enabled=True)
+        return [d.serial for d in q.order_by(Device.serial).all()]
+
+
+def list_devices():
+    """全量设备行（设备池管理页用）。"""
+    with _ctx():
+        return [d.to_dict() for d in Device.query.order_by(Device.serial).all()]
+
+
+# ================== 在线状态 ==================
+def list_online():
+    """本机 adb devices 中 state=device 的设备（实时）。"""
+    out = _adb("devices") or ""
+    serials = []
+    for line in out.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[0] and parts[1] == "device":
+            serials.append(parts[0])
+    return serials
+
+
+def is_online(serial):
+    """设备当前是否在线（本机 adb 可达且状态正常）。"""
+    return serial in list_online()
+
+
+def list_ready():
+    """可调度设备：清单 ∩ 在线（取代 STF list_free_devices）。"""
+    online = set(list_online())
+    return [s for s in list_configured() if s in online]
+
+
+# ================== 管理（CRUD） ==================
+def add_device(serial, name="", note="", enabled=True):
+    """添加/更新设备（upsert）。返回 True 新增 / False 已存在并更新。"""
+    serial = (serial or "").strip()
+    if not serial:
+        return False
+    with _ctx():
+        d = Device.query.get(serial)
+        if d:
+            d.name, d.note, d.enabled = name or "", note or "", enabled
+            db.session.commit()
+            return False
+        db.session.add(Device(serial=serial, name=name or "", note=note or "",
+                              enabled=enabled,
+                              created_at=time.strftime("%Y-%m-%d %H:%M")))
+        db.session.commit()
+        _log.info(f"设备池新增设备: {serial}")
+        return True
+
+
+def remove_device(serial):
+    """删除设备。返回是否删除成功。"""
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d:
+            return False
+        db.session.delete(d)
+        db.session.commit()
+        _log.info(f"设备池删除设备: {serial}")
+        return True
+
+
+def set_enabled(serial, enabled):
+    """启用/停用设备（停用后不参与调度）。返回是否成功。"""
+    with _ctx():
+        d = Device.query.get(serial)
+        if not d:
+            return False
+        d.enabled = enabled
+        db.session.commit()
+        return True
+
+
+# ================== 首次导入（阶段 3 摘除 STF 后删除） ==================
+def _seed_from_stf_if_empty():
+    """首次启动把 STF 现有设备导入本地清单。
+
+    条件：device 表为空 且 未导入过（app_meta 标记）。STF 不可达时跳过，
+    不写标记，下次启动重试。摘除 STF 后此函数随 stf_client 一起删除。
+    """
+    try:
+        from core.stf_client import STFClient
+    except Exception:
+        return
+    with _ctx():
+        if Device.query.count() > 0:
+            return
+        seeded = db.session.execute(text(
+            "SELECT value FROM app_meta WHERE key='devices_seeded_from_stf'")).scalar()
+        if seeded:
+            return
+        try:
+            # 导入全部 serial（不限于 present）：STF 池 = 配置的舰队，
+            # present=false 的是掉线/陈旧记录，导入后显示离线，管理页可删
+            serials = [d["serial"] for d in STFClient().list_all_devices()]
+        except Exception as e:
+            _log.warning(f"从 STF 导入设备清单失败（可稍后手动添加）: {e}")
+            return
+        if not serials:
+            _log.warning("STF 无在线设备，跳过设备池首次导入")
+            return
+        now = time.strftime("%Y-%m-%d %H:%M")
+        for s in serials:
+            db.session.add(Device(serial=s, created_at=now))
+        db.session.execute(text(
+            "INSERT OR REPLACE INTO app_meta(key,value) VALUES('devices_seeded_from_stf','1')"))
+        db.session.commit()
+        _log.info(f"设备池首次导入 {len(serials)} 台设备（来源 STF）")

core/models.py

@@ -216,11 +216,38 @@ class ApkFile(db.Model):
         return f"<ApkFile {self.display_name}>"
 
 
+class Device(db.Model):
+    """设备池（本地设备清单，替代 STF 池作为调度数据源）。
+
+    serial 即 adb 序列号（IP:5555 或 USB 序列号）；enabled=False 不参与调度。
+    """
+    serial = db.Column(db.String(120), primary_key=True)
+    name = db.Column(db.String(80), default="")       # 备注名（可选）
+    enabled = db.Column(db.Boolean, default=True)     # 是否参与调度
+    note = db.Column(db.Text, default="")             # 备注
+    created_at = db.Column(db.String(20), default="") # 添加时间
+
+    def to_dict(self):
+        return {"serial": self.serial, "name": self.name or "",
+                "enabled": bool(self.enabled), "note": self.note or "",
+                "created_at": self.created_at or ""}
+
+    def __repr__(self):
+        return f"<Device {self.serial}>"
+
+
 # 版本化 schema 迁移：新增结构变更时在此追加 (版本号, 说明, SQL)
 # 版本号单调递增，只执行比当前 schema_version 新的迁移。
 SCHEMA_MIGRATIONS = [
     (1, "用户权限位：user 表新增 perms 列（JSON 数组，默认空=无业务权限，管理员不受限）",
      "ALTER TABLE user ADD COLUMN perms TEXT DEFAULT '[]'"),
+    (2, "设备池：device 表（本地设备清单，替代 STF 池）",
+     "CREATE TABLE IF NOT EXISTS device ("
+     "serial VARCHAR(120) PRIMARY KEY,"
+     "name VARCHAR(80) DEFAULT '',"
+     "enabled BOOLEAN DEFAULT 1,"
+     "note TEXT DEFAULT '',"
+     "created_at VARCHAR(20) DEFAULT '')"),
 ]
 
 

doc/STF_REMOVAL.md

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

web_server.py

@@ -68,6 +68,10 @@ login_manager.login_view = "login"
 # 先初始化数据库（含旧 JSON 迁移），再创建 TaskManager（需要 app context 读写 DB）
 init_db(app)
 stf = STFClient()
+# 设备池（本地清单 + adb 在线状态）：阶段 0 起作为 STF 的替代数据源，
+# 首次启动自动从 STF 导入现有设备；阶段 3 摘除 STF 后此模块独立运行
+from core import device_pool
+device_pool.init_app(app)
 mgr = TaskManager(stf, app=app)
 apk_mgr = ApkManager(stf, app=app)