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:
+556
@@ -0,0 +1,556 @@
|
||||
# API 接口文档
|
||||
|
||||
`platform-tools` Web 后台提供 JSON API，所有接口需登录后访问（Flask-Login session 认证）。
|
||||
|
||||
**Base URL**：`http://localhost:18050`
|
||||
|
||||
**认证方式**：Cookie Session（先 POST `/login` 获取 session cookie，后续请求带上）
|
||||
|
||||
**通用响应格式**：
|
||||
```json
|
||||
{"ok": true, "data": "..."}
|
||||
{"ok": false, "error": "错误信息"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 认证
|
||||
|
||||
### POST /login
|
||||
|
||||
用户登录。
|
||||
|
||||
**请求**（form-data）：
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| username | string | 用户名 |
|
||||
| password | string | 密码 |
|
||||
|
||||
**响应**：成功重定向到 `/`，失败返回登录页（含 error 信息）。
|
||||
|
||||
### GET /logout
|
||||
|
||||
登出，重定向到登录页。
|
||||
|
||||
---
|
||||
|
||||
## 2. 页面路由
|
||||
|
||||
### GET /
|
||||
|
||||
单页应用首页（需登录）。响应头设置 `Cache-Control: no-store` 防止缓存。
|
||||
|
||||
### GET /login
|
||||
|
||||
登录页面（GET）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 设备状态
|
||||
|
||||
### GET /api/status
|
||||
|
||||
获取设备池 + Worker 综合状态（带 5 秒缓存）。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"server_time": 1700000000.0,
|
||||
"fg_scanning": false,
|
||||
"fg_last_scan": 1700000000.0,
|
||||
"devices": [
|
||||
{
|
||||
"serial": "192.168.1.100:5555",
|
||||
"model": "Pixel 6",
|
||||
"device_name": "测试机1",
|
||||
"present": true,
|
||||
"ready": true,
|
||||
"stf_occupied": false,
|
||||
"owner": "",
|
||||
"worker_status": "idle",
|
||||
"foreground_app": "空闲",
|
||||
"progress": {"done": 5, "total": 80, "unit": "视频", "action_counts": {"like": 3}},
|
||||
"current_action": "观看视频 6",
|
||||
"last_error": "",
|
||||
"running_job": "",
|
||||
"task_job": "",
|
||||
"attempt": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**worker_status 取值**：`idle` / `connecting` / `running` / `done` / `error` / `failed` / `released`
|
||||
|
||||
### POST /api/scan_foreground
|
||||
|
||||
手动触发前台 App 扫描（后台异步执行，不打扰设备）。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "扫描已启动"}
|
||||
{"ok": false, "error": "已有扫描在进行中"}
|
||||
```
|
||||
|
||||
### GET /api/devices
|
||||
|
||||
返回所有在线设备 serial 列表（供分组表单勾选用）。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "devices": ["192.168.1.100:5555", "192.168.1.101:5555"]}
|
||||
```
|
||||
|
||||
### GET /api/device/screenshot
|
||||
|
||||
获取设备当前画面截图（PNG）。
|
||||
|
||||
**参数**：
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| serial | string | 设备 serial |
|
||||
| t | int | 时间戳（避免缓存，前端自动加） |
|
||||
|
||||
**响应**：成功返回 `image/png`，失败返回 JSON 错误。
|
||||
|
||||
> 用 `adb exec-out screencap -p`，只读操作，任务运行中调用安全。
|
||||
|
||||
---
|
||||
|
||||
## 4. 任务类型
|
||||
|
||||
### GET /api/task_types
|
||||
|
||||
返回所有已注册任务类型。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"task_types": [
|
||||
{
|
||||
"task_type": "douyin_nurture",
|
||||
"name": "抖音养号",
|
||||
"description": "自动观看抖音视频...",
|
||||
"default_params": {"watch_count": 80, "...": "..."}
|
||||
},
|
||||
{
|
||||
"task_type": "generic_steps",
|
||||
"name": "通用步骤",
|
||||
"description": "通过步骤编辑器编排...",
|
||||
"default_params": {"steps": [...]}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/actions
|
||||
|
||||
返回指定任务类型支持的专属操作。
|
||||
|
||||
**参数**：
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| task_type | string | 任务类型 |
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"actions": [
|
||||
{"action_type": "like", "name": "点赞", "description": "...", "default_params": {"rate": 0.3}}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 任务计划 CRUD
|
||||
|
||||
### GET /api/jobs
|
||||
|
||||
列出所有任务计划。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"jobs": [{"id": "abc123", "name": "抖音养号", "task_type": "douyin_nurture", "...": "..."}],
|
||||
"task_types": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/jobs
|
||||
|
||||
创建任务计划。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{
|
||||
"name": "抖音养号",
|
||||
"task_type": "douyin_nurture",
|
||||
"target": {"mode": "all"},
|
||||
"params": {"watch_count": 50, "actions": {"like": {"params": {"rate": 0.5}}}},
|
||||
"schedule": {"mode": "once"},
|
||||
"retry": {"max_attempts": 3, "delay": 60},
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "任务已创建", "job": {"id": "abc123", "...": "..."}}
|
||||
```
|
||||
|
||||
### PUT /api/jobs/:job_id
|
||||
|
||||
更新任务计划。只需传要更新的字段。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"params": {"watch_count": 100}}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "任务已更新", "job": {"...": "..."}}
|
||||
```
|
||||
|
||||
### DELETE /api/jobs/:job_id
|
||||
|
||||
删除任务计划。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "任务已删除"}
|
||||
```
|
||||
|
||||
### POST /api/jobs/:job_id/run
|
||||
|
||||
立即执行任务（异步，不阻塞）。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "任务 抖音养号 已触发"}
|
||||
```
|
||||
|
||||
### POST /api/jobs/:job_id/toggle
|
||||
|
||||
启用/停用任务。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"enabled": false}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "任务已停用"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 设备分组
|
||||
|
||||
### GET /api/groups
|
||||
|
||||
列出所有分组。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"groups": [
|
||||
{"name": "A组", "serials": ["192.168.1.100:5555"], "description": "测试组"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/groups
|
||||
|
||||
创建分组。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"name": "A组", "serials": ["192.168.1.100:5555"], "description": "测试组"}
|
||||
```
|
||||
|
||||
### PUT /api/groups/:name
|
||||
|
||||
更新分组。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"serials": ["192.168.1.100:5555", "192.168.1.101:5555"], "description": "更新描述"}
|
||||
```
|
||||
|
||||
### DELETE /api/groups/:name
|
||||
|
||||
删除分组。
|
||||
|
||||
---
|
||||
|
||||
## 7. 运行控制
|
||||
|
||||
### POST /api/stop_device
|
||||
|
||||
停止单台设备的 worker（并阻止后续重试）。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"serial": "192.168.1.100:5555"}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "已发送停止信号给 192.168.1.100:5555"}
|
||||
```
|
||||
|
||||
### POST /api/stop_all
|
||||
|
||||
停止所有运行中的 worker。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "stopped": ["192.168.1.100:5555", "192.168.1.101:5555"]}
|
||||
```
|
||||
|
||||
### POST /api/release
|
||||
|
||||
释放当前账户占用的所有 STF 设备（清理用）。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "released": ["192.168.1.100:5555"]}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 用户管理
|
||||
|
||||
### GET /api/users
|
||||
|
||||
列出所有用户。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "users": [{"id": 1, "username": "admin", "is_admin": true}]}
|
||||
```
|
||||
|
||||
### POST /api/users
|
||||
|
||||
创建用户。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"username": "user1", "password": "pass123", "is_admin": false}
|
||||
```
|
||||
|
||||
### PUT /api/users/:uid
|
||||
|
||||
更新用户（修改密码/管理员权限）。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"password": "newpass", "is_admin": true}
|
||||
```
|
||||
|
||||
### DELETE /api/users/:uid
|
||||
|
||||
删除用户（不能删除 admin 和当前登录用户）。
|
||||
|
||||
---
|
||||
|
||||
## 9. 日志
|
||||
|
||||
### GET /api/logs
|
||||
|
||||
查看日志文件内容。
|
||||
|
||||
**参数**：
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|------|------|------|------|
|
||||
| file | string | `core.log` | 日志文件名 |
|
||||
| lines | int | 300 | 返回最后 N 行 |
|
||||
|
||||
**可选文件**：`core.log` / `task.log` / `web.log` / `action.log`
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"content": "2026-08-08 10:00:00 [INFO] [core.worker] ...",
|
||||
"file": "core.log",
|
||||
"files": {"core": "core.log", "task": "task.log", "web": "web.log", "action": "action.log"}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 自定义动作
|
||||
|
||||
### GET /api/custom_actions
|
||||
|
||||
列出所有自定义动作（步骤打包）。
|
||||
|
||||
### POST /api/custom_actions
|
||||
|
||||
创建自定义动作。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"name": "登录流程", "icon": "📦", "steps": [{"type": "click", "...": "..."}]}
|
||||
```
|
||||
|
||||
### PUT /api/custom_actions/:action_id
|
||||
|
||||
更新自定义动作。
|
||||
|
||||
### DELETE /api/custom_actions/:action_id
|
||||
|
||||
删除自定义动作。
|
||||
|
||||
---
|
||||
|
||||
## 11. 元素抓取（uiauto2）
|
||||
|
||||
### GET /api/uiauto/status
|
||||
|
||||
探测 uiauto2 本地服务是否运行。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "running": true}
|
||||
```
|
||||
|
||||
### GET /api/uiauto/devices
|
||||
|
||||
获取 uiauto2 已连接的设备列表。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "devices": [{"serial": "192.168.1.100:5555", "model": "Pixel 6"}]}
|
||||
```
|
||||
|
||||
### GET /api/uiauto/screenshot
|
||||
|
||||
通过 uiauto2 获取设备截图（JPEG）。
|
||||
|
||||
**参数**：
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| serial | string | 设备 serial |
|
||||
|
||||
**响应**：成功返回 `image/jpeg`，失败返回 JSON 错误。
|
||||
|
||||
### GET /api/uiauto/elements
|
||||
|
||||
获取设备 UI 元素树。
|
||||
|
||||
**参数**：
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| serial | string | 设备 serial |
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"elements": [
|
||||
{
|
||||
"depth": 0,
|
||||
"name": "android.widget.FrameLayout",
|
||||
"resource_id": "",
|
||||
"text": "",
|
||||
"description": "",
|
||||
"class": "android.widget.FrameLayout",
|
||||
"bounds": "[0,0][1080,2400]",
|
||||
"suggested": {"type": "xpath", "value": "//*"}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 应用管理（APK）
|
||||
|
||||
### GET /api/apks
|
||||
|
||||
列出所有已上传的 APK。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"apks": [
|
||||
{
|
||||
"id": "abc123",
|
||||
"display_name": "抖音",
|
||||
"package_name": "com.ss.android.ugc.aweme",
|
||||
"version_name": "25.0.0",
|
||||
"version_code": 2500,
|
||||
"size": 104857600,
|
||||
"upload_time": "2026-08-08 10:00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/apks/upload
|
||||
|
||||
上传 APK 文件（自动解析包名/版本/应用名）。
|
||||
|
||||
**请求**（multipart/form-data）：
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| file | file | APK 文件 |
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "apk": {"...": "..."}, "msg": "上传成功: 抖音"}
|
||||
```
|
||||
|
||||
### DELETE /api/apks/:apk_id
|
||||
|
||||
删除 APK 文件和记录。
|
||||
|
||||
### POST /api/apks/install
|
||||
|
||||
批量安装 APK 到指定设备。
|
||||
|
||||
**请求**（JSON）：
|
||||
```json
|
||||
{"apk_id": "abc123", "serials": ["192.168.1.100:5555", "192.168.1.101:5555"]}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{"ok": true, "msg": "开始安装 抖音 到 2 台设备"}
|
||||
```
|
||||
|
||||
### GET /api/apks/install/status
|
||||
|
||||
获取安装任务实时状态。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"status": {
|
||||
"apk_name": "抖音",
|
||||
"finished": false,
|
||||
"total": 2,
|
||||
"success": 1,
|
||||
"failed": 0,
|
||||
"skipped": 0,
|
||||
"installing": 1,
|
||||
"pending": 0,
|
||||
"items": {
|
||||
"192.168.1.100:5555": {"name": "Pixel 6", "status": "success", "msg": "安装成功(已验证)"},
|
||||
"192.168.1.101:5555": {"name": "Pixel 7", "status": "installing", "msg": "正在安装..."}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user