butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2adc54b51271a91e86d471ddd04bf8e19f6df28d
auto_control/doc/DEVELOPMENT.md
T

8.2 KiB
Raw Blame History

开发手册（DEVELOPMENT）

面向本项目开发者：开发流程、git 工作流、环境说明、技术红线、本地开发、常见开发任务。

1. 开发流程与 git 工作流

1.1 分支策略

分支 用途
dev 开发分支，所有新功能/修复都在这里开发
main 生产分支（主分支），只放已确认的稳定版本

生产环境 = 部署机 192.168.20.220 的 /mnt/data/openstf/auto_control（python-app 容器运行 web_server.py）。

1.2 git 操作铁律（重要）

所有 git 操作都必须先经项目负责人明确确认后才能执行，包括但不限于：

  • commit / push（即使 push 到 dev 也要确认）
  • merge（dev → main）
  • revert / checkout / reset / branch -D 等

标准流程：

1. 在 dev 分支开发、本地测试
2. 完成改动 → 把改动清单 + 建议 commit 信息 列给负责人
3. 负责人确认 → 才能 commit + push dev
4. 需要发布 → 负责人确认后再合并到 main
5. 部署生产 → 负责人明确指示后才 pull 到 220

不允许"开发完顺手就 commit/push"。即使是一次性小改动，也要先确认。

2. 环境说明

环境 位置 说明
开发机 本机（192.168.20.57） .venv + 本地运行 web_server.py
生产机 部署机 220 的 auto_control python-app 容器，network_mode: host
STF 服务 192.168.20.220:7100 已停用（2026-08-18 docker stop stf，代码已摘除依赖）
adb 容器 220 上 adb（host 网络 5037） USB 设备远程 adb server；网络设备补连用
设备 Tailscale 100.100.10.x:5555 Xiaomi 舰队，本机 100.100.10.2 在 tailnet 内
uiautodev 本机 20242 元素抓取服务（web_server 自动拉起）

2.1 adb key（关键）

  • 本机 ~/.android/adbkey 沿用历史 key（原取自 STF adb 容器，全部设备都信任）
  • 不要随意更换 key——设备会变 unauthorized 连不上
  • 旧 key 备份在 ~/.android/adbkey.local.bak
  • 生产环境的容器也需要用这把 key（部署时处理）

2.2 设备连接方式

  • 设备 serial 是 IP:5555（Tailscale 地址），直连优先（只 connect、绝不 disconnect）
  • USB 设备（serial 无冒号）：插本机走本地 adb；插 220 走远程 adb server（USB_ADB_HOST:5037）
  • 本机已在 tailnet 内，直连可靠且快（<1s）
  • 设备加入/退出平台：工具 → 设备池管理（SQLite 清单，自动连接 + 型号采集）

3. 技术红线（开发限制）—— 违反会打断共享 adb transport，需人工恢复

这些是踩过坑后总结的，任何修改都不能引入。违反任何一条都会导致设备连接被全部重建（历史原因：STF provider 共享同一 adb transport，摘除 STF 后仍保留此约束）：

  1. 绝不 adb kill-server

    • 会断开所有设备的 adb transport，全部设备连接被重建，运行中任务中断
    • 见 core/adb_helper.py

  2. 绝不对 IP:5555 设备 adb disconnect

    • 该地址的 adb transport 是共享的（历史与 STF provider 共用），disconnect 会断掉全部相关连接
    • 直连模式下 release() 不 disconnect
    • 见 core/device_worker.py STFDevice.release()

  3. 空闲设备扫描不主动 connect/disconnect

    • IP:5555 的 transport 由多方共享（历史与 STF provider 共用），外部 connect/disconnect 会扰动共享连接
    • _ForegroundScanner._scan_free 对空闲设备直接返回"空闲"，不碰 adb
    • 见 core/task_manager.py

  4. adb key 保持历史 key 不变（见 2.1，设备信任该 key）

  5. 直连优先，不引入第三方桥接（见 2.2）

3.1 其他开发限制

  • web_server.py 以 debug=False 运行，不热重载：改 core/、tasks/、templates/、static/ 后必须重启 web_server（前端 HTML 改完强刷浏览器）
  • 任务参数放各自 tasks/<app>/task.py 顶部，不放 config.py
  • 生产环境（220）默认只读：任何写操作（改文件/重启容器/部署）都必须先经负责人确认
  • 数据库是 SQLite（data/users.db，WAL 模式）：运行时数据不提交 git
  • 前端 JS 在 static/admin/monitor.js（已从 HTML 拆分），HTML 里用 <script src> 引用
  • 监控页/大列表已加分页：100 台设备也只渲染 10 行/页，不要移除分页逻辑
  • 任务批量触发已错峰（_START_STAGGER_SEC）：避免大量设备同时启动造成 adb 连接风暴，不要移除

4. 本地开发手册

4.1 首次安装

# 用 Python 3.12 建 venv（README 推荐版本）
/opt/homebrew/bin/python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt

# macOS：adb 用系统自带的（bin/adb/adb 是被 gitignore 的符号链接）
ln -sf /opt/homebrew/bin/adb bin/adb/adb

# 确认 adb key（必须是 STF 容器的 key，否则设备连不上）
ls -la ~/.android/adbkey

4.2 启动

.venv/bin/python web_server.py
# 访问 http://localhost:18050/  账号 admin/admin123

启动日志看到以下即成功：

[INFO] [core.worker] 心跳看门狗已启动
[INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
[INFO] [web] 启动服务: http://localhost:18050/

4.3 测试

  • 后端逻辑：直接 .venv/bin/python -c "..." 调用（如 tasks/、core/ 的函数）
  • 前端 UI：Playwright（系统 python3 已装），脚本示例见下
  • 浏览器冒烟：切 6 个 tab、开任务编辑器，确认无 JS 错误
# Playwright 冒烟示例（python3 运行）
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    b = p.chromium.launch(headless=True)
    pg = b.new_page()
    pg.goto("http://127.0.0.1:18050/login")
    pg.fill("input[name=username]", "admin")
    pg.fill("input[name=password]", "admin123")
    pg.click("input[type=submit], button[type=submit]")
    pg.wait_for_load_state("networkidle")
    # ... 检查各 tab、编辑器
    b.close()

4.4 常用调试

  • 看日志：logs/ 下 core.log / task.log / web.log / action.log（10MB 滚动，保留 5 份）
  • 看设备/任务状态：浏览器监控页，或 GET /api/status、GET /api/health
  • 清理 STF 残留占用：前端监控页"强制释放占用"（或 .env 配 AUTO_RELEASE_STALE_OCCUPY=true 启动自动清理）
  • 打包项目：python scripts/pack.py

5. 常见开发任务

5.1 新增 App 任务

参照 tasks/douyin/ 结构，详见 doc/TASK_DEV.md（6 步模板）。

tasks/<app>/
  __init__.py     # from . import task
  task.py         # DEFAULT_PARAMS + Worker + @register_task
  actions/        # 专属操作（可选）

5.2 新增专属操作

在 tasks/<app>/actions/ 建 .py，继承 BaseAction + @register_action(ACTIONS)，在 __init__.py import。

5.3 修改前端

文件 内容
templates/admin/monitor.html HTML 结构 + CSS + <script src> 引用
static/admin/monitor.js 全部前端 JS

改完强刷浏览器（Cmd/Ctrl+Shift+R），必要时重启 web_server。

5.4 新增 API

在 web_server.py 加 Flask 路由，更新 doc/API.md。

5.5 新增数据库字段/表

  • 模型改 core/models.py，首次建表用 create_all()
  • 已有数据的老库：在 core/models.py 的 SCHEMA_MIGRATIONS 里加迁移（版本号递增 + SQL）

6. 发布流程

详见 doc/DEPLOY.md。摘要：

  1. dev 开发测试完成
  2. 负责人确认 → 合并到 main
  3. 负责人确认 → 生产 220 git pull
  4. 重启 python-app 容器生效

发布前检查：生产容器 adb key、依赖、数据库迁移。

7. 文档索引

文档 内容
README 项目总览、快速上手
DEVELOPMENT.md 本文档：流程/准则/限制/手册
TASK_DEV.md 任务开发指南（新增 App 任务模板）
ARCHITECTURE.md 架构详解（分层、数据流、设计决策）
API.md 全部 HTTP 接口说明
DEPLOY.md 部署指南（环境、生产、故障排查）
Reference in New Issue View Git Blame Copy Permalink