feat: 新增通用步骤任务+元素抓取，完善全部项目文档
- 新增 generic_steps 通用步骤任务（可视化步骤编辑器编排流程，支持 open_app/click/swipe/input_text/wait/loop/group） - 新增 core/uiauto_helper.py 封装 uiautodev 元素抓取客户端 - web_server 新增元素抓取/截图/设备列表等 API - monitor.html 新增步骤编辑器、元素抓取模态框、独立关闭逻辑 - 新增 README.md 项目总览（快速上手/架构/配置/FAQ） - 新增 doc/ARCHITECTURE.md 架构详解、doc/DEPLOY.md 部署指南、doc/API.md 接口文档 - 修复 doc/TASK_DEV.md：移除已删除的 comment 引用，补充 generic 包，更新注册示例 - .gitignore 忽略 .claude/ 工具产物
This commit is contained in:
@@ -111,6 +111,35 @@ class TaskJob(db.Model):
|
||||
return f"<TaskJob {self.name}>"
|
||||
|
||||
|
||||
class CustomAction(db.Model):
|
||||
"""自定义动作（把一系列步骤打包成一个可复用的动作）。
|
||||
|
||||
steps 字段存 JSON 数组，格式同 generic_steps 的 step schema。
|
||||
前端拖拽到画布时，展开为 group 步骤（type='group'）。
|
||||
"""
|
||||
id = db.Column(db.String(32), primary_key=True)
|
||||
name = db.Column(db.String(120), nullable=False)
|
||||
icon = db.Column(db.String(4), default="📦")
|
||||
steps = db.Column(db.Text, default="[]") # JSON 数组
|
||||
created_at = db.Column(db.String(20), default="")
|
||||
|
||||
def get_steps(self):
|
||||
try:
|
||||
return json.loads(self.steps or "[]")
|
||||
except Exception:
|
||||
return []
|
||||
|
||||
def set_steps(self, v):
|
||||
self.steps = json.dumps(v or [], ensure_ascii=False)
|
||||
|
||||
def to_dict(self):
|
||||
return {"id": self.id, "name": self.name, "icon": self.icon or "📦",
|
||||
"steps": self.get_steps(), "created_at": self.created_at or ""}
|
||||
|
||||
def __repr__(self):
|
||||
return f"<CustomAction {self.name}>"
|
||||
|
||||
|
||||
class ApkFile(db.Model):
|
||||
"""上传的 APK 文件元信息（应用管理功能）。"""
|
||||
id = db.Column(db.String(32), primary_key=True) # uuid 前 8 位
|
||||
|
||||
+96
-71
@@ -302,6 +302,7 @@ class TaskManager:
|
||||
self.groups = {} # name -> DeviceGroup(内存业务对象)
|
||||
self.jobs = {} # id -> TaskJob(内存业务对象)
|
||||
self._running = {} # serial -> {"worker", "job_id", "started_at", "attempt"}
|
||||
self._stop_requested = set() # serial 集合：用户请求停止，阻止后续重试
|
||||
self._lock = threading.Lock()
|
||||
self._fg_scanner = _ForegroundScanner(self.stf)
|
||||
self._load()
|
||||
@@ -557,88 +558,112 @@ class TaskManager:
|
||||
异常分类：
|
||||
DeviceOfflineError — 设备掉线，立即放弃不重试（换设备也没用）
|
||||
其他异常 — 按 max_attempts 重试
|
||||
用户停止（stop_device）会加入 _stop_requested，阻止任何后续重试。
|
||||
"""
|
||||
for attempt in range(1, max_attempts + 1):
|
||||
# 同一 serial 同时只能一个 worker
|
||||
try:
|
||||
for attempt in range(1, max_attempts + 1):
|
||||
# 用户已请求停止 → 不再启动新 attempt
|
||||
with self._lock:
|
||||
if serial in self._stop_requested:
|
||||
_log.info(f"{serial} 用户已请求停止，取消重试 (job={job.name})")
|
||||
return
|
||||
# 同一 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
|
||||
# 用户请求停止（无论 attempt 第几次、status 是什么）→ 不重试
|
||||
with self._lock:
|
||||
if serial in self._stop_requested:
|
||||
_log.info(f"{serial} 用户已请求停止，不再重试 (job={job.name})")
|
||||
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:
|
||||
# 用户在 sleep 期间点停止也能中断
|
||||
with self._lock:
|
||||
if serial in self._stop_requested:
|
||||
_log.info(f"{serial} 用户已请求停止，取消重试 (job={job.name})")
|
||||
return
|
||||
# 检查是否是端口耗尽类临时错误，需要更长退避等端口释放
|
||||
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}次失败")
|
||||
finally:
|
||||
# 清除停止标志：整个重试循环结束（成功/失败/停止）后允许下次任务
|
||||
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}次失败")
|
||||
self._stop_requested.discard(serial)
|
||||
|
||||
# ---- 运行控制 ----
|
||||
def stop_device(self, serial):
|
||||
"""停止指定设备的 worker。"""
|
||||
"""停止指定设备的 worker，并阻止后续重试。
|
||||
|
||||
无论 worker 当前在运行还是在重试 sleep 中，都会阻止下一次重试。
|
||||
"""
|
||||
with self._lock:
|
||||
self._stop_requested.add(serial)
|
||||
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
|
||||
if info:
|
||||
w = info.get("worker")
|
||||
if w and w.is_alive():
|
||||
w.stop()
|
||||
return True
|
||||
# worker 已结束但重试循环可能还在 sleep —— 仍然返回 True 表示已阻止重试
|
||||
return True
|
||||
|
||||
def stop_all(self):
|
||||
"""停止所有运行中的 worker。"""
|
||||
"""停止所有运行中的 worker，并阻止后续重试。"""
|
||||
with self._lock:
|
||||
items = list(self._running.items())
|
||||
for s, _ in items:
|
||||
self._stop_requested.add(s)
|
||||
stopped = []
|
||||
for serial, info in items:
|
||||
w = info.get("worker")
|
||||
|
||||
@@ -0,0 +1,178 @@
|
||||
"""uiauto2 (uiautodev) 本地服务客户端封装。
|
||||
|
||||
uiautodev 启动后本地监听 http://localhost:20242，提供设备元素树查询。
|
||||
前端步骤编辑器"抓取元素"按钮通过本模块拉取当前设备 UI 树供选择。
|
||||
|
||||
依赖：
|
||||
- 用户需先 `pip install uiautodev` 并运行 `uiauto.dev` 启动本地服务
|
||||
- 未运行时本模块函数返回友好错误，不抛异常
|
||||
|
||||
API 参考（uiautodev 0.14）：
|
||||
- GET /api/info — 服务信息（用于探测是否运行）
|
||||
- GET /api/android/{serial}/dump_hierarchy — 元素树 JSON
|
||||
"""
|
||||
import requests
|
||||
|
||||
from core.logger import get_logger
|
||||
|
||||
_log = get_logger("core.uiauto")
|
||||
|
||||
# uiautodev 默认本地端口（固定 20242）
|
||||
_UIAUTO_BASE = "http://localhost:20242"
|
||||
# 请求超时（秒）。connect 超时短，避免前端等太久
|
||||
_TIMEOUT = (1, 8)
|
||||
|
||||
|
||||
def is_running():
|
||||
"""探测 uiauto2 本地服务是否在运行。"""
|
||||
try:
|
||||
r = requests.get(f"{_UIAUTO_BASE}/api/info", timeout=_TIMEOUT)
|
||||
return r.status_code == 200
|
||||
except Exception:
|
||||
return False
|
||||
|
||||
|
||||
def list_devices():
|
||||
"""获取 uiauto2 已连接的设备列表。
|
||||
|
||||
返回 (ok, data_or_error)：
|
||||
ok=True — data 是设备列表 [{serial, model, product, name, status}, ...]
|
||||
ok=False — data 是错误消息字符串
|
||||
"""
|
||||
try:
|
||||
r = requests.get(f"{_UIAUTO_BASE}/api/android/list", timeout=_TIMEOUT)
|
||||
r.raise_for_status()
|
||||
data = r.json()
|
||||
return True, data
|
||||
except requests.exceptions.ConnectionError:
|
||||
return False, "uiauto2 未启动，请运行 `uiauto.dev`"
|
||||
except Exception as e:
|
||||
_log.warning(f"list_devices 异常: {e}")
|
||||
return False, f"获取设备列表失败: {e}"
|
||||
|
||||
|
||||
def get_screenshot(serial):
|
||||
"""获取设备截图（通过 uiauto2 服务）。
|
||||
|
||||
返回 (ok, data_or_error)：
|
||||
ok=True — data 是 JPEG 二进制数据
|
||||
ok=False — data 是错误消息字符串
|
||||
"""
|
||||
if not serial:
|
||||
return False, "缺少 serial"
|
||||
try:
|
||||
r = requests.get(
|
||||
f"{_UIAUTO_BASE}/api/android/{serial}/screenshot/0",
|
||||
timeout=_TIMEOUT,
|
||||
)
|
||||
r.raise_for_status()
|
||||
return True, r.content
|
||||
except requests.exceptions.ConnectionError:
|
||||
return False, "uiauto2 未启动"
|
||||
except Exception as e:
|
||||
_log.warning(f"get_screenshot 异常: {e}")
|
||||
return False, f"截图失败: {e}"
|
||||
|
||||
|
||||
def get_elements(serial):
|
||||
"""获取指定设备的 UI 元素树。
|
||||
|
||||
返回 (ok, data_or_error)：
|
||||
ok=True — data 是元素列表 [{name, attrs:{...}, children:[...]}, ...]
|
||||
ok=False — data 是错误消息字符串
|
||||
|
||||
元素树由 uiautodev 的 U2AndroidDriver.dump_hierarchy 返回（JSON）。
|
||||
我们递归提取每个节点的关键属性（resource-id/text/description/class/...），
|
||||
供前端列表展示和选择。
|
||||
"""
|
||||
if not serial:
|
||||
return False, "缺少 serial"
|
||||
try:
|
||||
r = requests.get(
|
||||
f"{_UIAUTO_BASE}/api/android/{serial}/hierarchy",
|
||||
timeout=_TIMEOUT,
|
||||
)
|
||||
if r.status_code == 404:
|
||||
return False, f"设备 {serial} 未连接到 uiauto2"
|
||||
r.raise_for_status()
|
||||
data = r.json()
|
||||
# uiautodev hierarchy 返回 Node 树：{key, name, bounds, rect, properties, children}
|
||||
# 提取成扁平的可选列表（保留层级缩进信息）
|
||||
elements = []
|
||||
_flatten(data, elements, depth=0)
|
||||
if not elements:
|
||||
return False, "当前界面未抓取到元素"
|
||||
return True, elements
|
||||
except requests.exceptions.ConnectionError:
|
||||
return False, "uiauto2 未启动，请运行 `uiauto.dev`"
|
||||
except requests.exceptions.Timeout:
|
||||
return False, "uiauto2 请求超时"
|
||||
except Exception as e:
|
||||
_log.warning(f"get_elements 异常: {e}")
|
||||
return False, f"抓取失败: {e}"
|
||||
|
||||
|
||||
def _flatten(node, out, depth=0, path=""):
|
||||
"""递归扁平化元素树，提取关键属性供前端选择。
|
||||
|
||||
uiautodev dump_hierarchy 返回 Node 格式：
|
||||
{key, name, bounds(归一化浮点), rect({x,y,width,height}), properties({所有属性}), children}
|
||||
其中 properties 包含原始 XML 属性（resource-id/text/content-desc/class/bounds 字符串等）。
|
||||
"""
|
||||
if not isinstance(node, dict):
|
||||
return
|
||||
props = node.get("properties") or {}
|
||||
name = node.get("name") or props.get("class") or ""
|
||||
# bounds：优先取 properties 中的原始字符串 "[x1,y1][x2,y2]"（前端渲染 overlay 用）
|
||||
bounds_str = props.get("bounds", "")
|
||||
if not bounds_str and node.get("rect"):
|
||||
r = node["rect"]
|
||||
bounds_str = f"[{r['x']},{r['y']}][{r['x']+r['width']},{r['y']+r['height']}]"
|
||||
# 关键属性（前端选择器用）
|
||||
item = {
|
||||
"depth": depth,
|
||||
"path": path,
|
||||
"name": name,
|
||||
"resource_id": props.get("resource-id", ""),
|
||||
"text": props.get("text", ""),
|
||||
"description": props.get("content-desc", ""),
|
||||
"class": props.get("class", ""),
|
||||
"package": props.get("package", ""),
|
||||
"clickable": props.get("clickable", ""),
|
||||
"bounds": bounds_str,
|
||||
# 推荐选择器（优先级：resource-id > text > description > class）
|
||||
"suggested": _suggest_selector(props),
|
||||
}
|
||||
out.append(item)
|
||||
# 递归子节点
|
||||
children = node.get("children") or []
|
||||
for i, child in enumerate(children):
|
||||
_flatten(child, out, depth + 1, f"{path}/{i}")
|
||||
|
||||
|
||||
def _suggest_selector(attrs):
|
||||
"""根据属性推荐最佳选择器（前端一键填入用）。
|
||||
|
||||
优先返回 xpath（最稳定，uiautomator2 原生支持），
|
||||
其次 resourceId / text / description / class。
|
||||
"""
|
||||
cls = attrs.get("class", "")
|
||||
rid = attrs.get("resource-id", "")
|
||||
text = attrs.get("text", "")
|
||||
desc = attrs.get("content-desc", "")
|
||||
# 优先生成 xpath：resource-id 最稳定
|
||||
if rid:
|
||||
# 简短类名（去掉包前缀）
|
||||
short_cls = cls.split(".")[-1] if cls else "*"
|
||||
return {"type": "xpath",
|
||||
"value": f'//*[@resource-id="{rid}"]'}
|
||||
if text:
|
||||
return {"type": "xpath",
|
||||
"value": f'//*[@text="{text}"]'}
|
||||
if desc:
|
||||
return {"type": "xpath",
|
||||
"value": f'//*[@content-desc="{desc}"]'}
|
||||
if cls:
|
||||
return {"type": "xpath",
|
||||
"value": f'//{cls}'}
|
||||
return {"type": "xpath", "value": "//*"}
|
||||
Reference in New Issue
Block a user