auto_control/doc/API.md

API 接口文档

platform-tools Web 后台提供 JSON API，所有接口需登录后访问（Flask-Login session 认证）。

Base URL：http://localhost:18050

认证方式：Cookie Session（先 POST /login 获取 session cookie，后续请求带上）

通用响应格式：

{"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 秒缓存）。

响应：

{
  "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 扫描（后台异步执行，不打扰设备）。

响应：

{"ok": true, "msg": "扫描已启动"}
{"ok": false, "error": "已有扫描在进行中"}

GET /api/devices

返回所有在线设备 serial 列表（供分组表单勾选用）。

响应：

{"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

返回所有已注册任务类型。

响应：

{
  "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	任务类型

响应：

{
  "ok": true,
  "actions": [
    {"action_type": "like", "name": "点赞", "description": "...", "default_params": {"rate": 0.3}}
  ]
}

---

5. 任务计划 CRUD

GET /api/jobs

列出所有任务计划。

响应：

{
  "ok": true,
  "jobs": [{"id": "abc123", "name": "抖音养号", "task_type": "douyin_nurture", "...": "..."}],
  "task_types": [...]
}

POST /api/jobs

创建任务计划。

请求（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
}

响应：

{"ok": true, "msg": "任务已创建", "job": {"id": "abc123", "...": "..."}}

PUT /api/jobs/:job_id

更新任务计划。只需传要更新的字段。

请求（JSON）：

{"params": {"watch_count": 100}}

响应：

{"ok": true, "msg": "任务已更新", "job": {"...": "..."}}

DELETE /api/jobs/:job_id

删除任务计划。

响应：

{"ok": true, "msg": "任务已删除"}

POST /api/jobs/:job_id/run

立即执行任务（异步，不阻塞）。

响应：

{"ok": true, "msg": "任务 抖音养号 已触发"}

POST /api/jobs/:job_id/toggle

启用/停用任务。

请求（JSON）：

{"enabled": false}

响应：

{"ok": true, "msg": "任务已停用"}

---

6. 设备分组

GET /api/groups

列出所有分组。

响应：

{
  "ok": true,
  "groups": [
    {"name": "A组", "serials": ["192.168.1.100:5555"], "description": "测试组"}
  ]
}

POST /api/groups

创建分组。

请求（JSON）：

{"name": "A组", "serials": ["192.168.1.100:5555"], "description": "测试组"}

PUT /api/groups/:name

更新分组。

请求（JSON）：

{"serials": ["192.168.1.100:5555", "192.168.1.101:5555"], "description": "更新描述"}

DELETE /api/groups/:name

删除分组。

---

7. 运行控制

POST /api/stop_device

停止单台设备的 worker（并阻止后续重试）。

请求（JSON）：

{"serial": "192.168.1.100:5555"}

响应：

{"ok": true, "msg": "已发送停止信号给 192.168.1.100:5555"}

POST /api/stop_all

停止所有运行中的 worker。

响应：

{"ok": true, "stopped": ["192.168.1.100:5555", "192.168.1.101:5555"]}

POST /api/release

释放当前账户占用的所有 STF 设备（清理用）。

响应：

{"ok": true, "released": ["192.168.1.100:5555"]}

---

8. 用户管理

GET /api/users

列出所有用户。

响应：

{"ok": true, "users": [{"id": 1, "username": "admin", "is_admin": true}]}

POST /api/users

创建用户。

请求（JSON）：

{"username": "user1", "password": "pass123", "is_admin": false}

PUT /api/users/:uid

更新用户（修改密码/管理员权限）。

请求（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

响应：

{
  "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）：

{"name": "登录流程", "icon": "📦", "steps": [{"type": "click", "...": "..."}]}

PUT /api/custom_actions/:action_id

更新自定义动作。

DELETE /api/custom_actions/:action_id

删除自定义动作。

---

11. 元素抓取（uiauto2）

GET /api/uiauto/status

探测 uiauto2 本地服务是否运行。

响应：

{"ok": true, "running": true}

GET /api/uiauto/devices

获取 uiauto2 已连接的设备列表。

响应：

{"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

响应：

{
  "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。

响应：

{
  "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 文件

响应：

{"ok": true, "apk": {"...": "..."}, "msg": "上传成功: 抖音"}

DELETE /api/apks/:apk_id

删除 APK 文件和记录。

POST /api/apks/install

批量安装 APK 到指定设备。

请求（JSON）：

{"apk_id": "abc123", "serials": ["192.168.1.100:5555", "192.168.1.101:5555"]}

响应：

{"ok": true, "msg": "开始安装 抖音 到 2 台设备"}

GET /api/apks/install/status

获取安装任务实时状态。

响应：

{
  "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": "正在安装..."}
    }
  }
}