HTTP REST API
启动:
bash
npx mobai-api # 监听 http://localhost:3210所有端点支持 JSON。需要认证时带 Authorization: Bearer <token>,见 认证。
设备
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /devices | 列所有设备 + 状态 |
| GET | /devices/events | SSE 设备连接/断开事件流 |
| GET | /devices/:id/screenshot | 截图 PNG(binary) |
| GET | /devices/:id/screenshot/base64 | 截图 base64 |
| POST | /devices/:id/tap | {x,y} 或 {label} |
| POST | /devices/:id/swipe | {fx,fy,tx,ty,ms?} 或 {direction} |
| POST | /devices/:id/input | {text} |
| POST | /devices/:id/press | {keycode} |
| POST | /devices/:id/launch | {action?, package?, force?, clearData?} |
| POST | /devices/:id/save-screenshot | {name} — 存到本地报告目录 |
UI 观察 + 断言
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /devices/:id/ui | dump UI XML |
| POST | /devices/:id/find | {label} → 坐标 |
| POST | /devices/:id/assert | {pattern, regex?} 文本断言 |
| POST | /devices/:id/assert-visual | {prompt, model?} Gemini 视觉断言 |
| POST | /devices/:id/wait-stable | {timeoutMs?, hammingMax?, stableFrames?} |
| POST | /devices/:id/dismiss-modal | {maxRounds?, extraDismissLabels?} |
| GET | /devices/:id/ocr | Gemini OCR |
| GET | /devices/:id/analyze | analyze_screen 结构化 JSON |
| GET | /devices/:id/elements | get_elements 结构化元素列表 |
| GET | /devices/:id/anomaly | detect_anomaly UI 异常 |
| POST | /devices/:id/smart-tap | {description} 按自然语言描述点 |
App 管理
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /devices/:id/install | {path} |
| POST | /devices/:id/uninstall | {package} |
| POST | /devices/:id/reset | {package} 清数据 |
| GET | /devices/:id/packages | ?thirdPartyOnly=true&filter=... |
诊断
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /devices/:id/logcat | ?buffer=main&tail=500&since_package=... |
| POST | /devices/:id/logcat-clear | {buffer} |
| GET | /devices/:id/crashes | ?since_package=... |
| GET | /devices/:id/metrics | 一次性性能采样 |
| GET | /devices/:id/metrics/stream | SSE 实时性能流(每秒) |
端口转发
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /devices/:id/forward | {local, remote} adb reverse |
| GET | /devices/:id/forward | 列转发 |
| DELETE | /devices/:id/forward | 删除 |
本地化
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /devices/:id/set-locale | {locale} Android 切语言 |
Web 自动化
桌面 Web(全局,一个 Chrome 实例):
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /web/launch | {url?, headless?} 启动 Chrome |
| POST | /web/close | 关闭 |
| POST | /web/navigate | {url} |
| GET | /web/pages | 标签页列表 |
| POST | /web/click | {selector} 或 {text} |
| POST | /web/type | {selector, text} |
| GET | /web/screenshot | 返 PNG |
| POST | /web/assert | {selector, text?, visible?} |
| POST | /web/wait-for | {selector, timeoutMs?} |
| POST | /web/evaluate | {code} 跑 JS |
| GET | /web/title | 当前 tab 标题 |
设备 Web(Android WebView / Chrome,通过 CDP):
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /devices/:id/web/tabs | 设备上的 Chrome tab |
| POST | /devices/:id/web/execute-js | {code, tabIndex?} |
| GET | /devices/:id/web/dom | ?tabIndex=0 HTML |
| POST | /devices/:id/web/click | {selector, tabIndex?} |
| POST | /devices/:id/web/navigate | {url, tabIndex?} |
DSL 执行
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /devices/:id/run-script | {yaml, runtimeVars?} — 执行 DSL,返回 steps + 结果 |
| POST | /tests/parallel | {serials, yaml} 多设备并行 |
报告
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /reports/upload | 上传测试包到云 |
| GET | /reports/list | 用户测试包列表 |
通知
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /notify | {channel: slack|discord, text} |
系统
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | / | 健康检查 |
| GET | /docs | API 参考(内置) |
| GET | /usage | 当前计量用量 |
速率限制
| 路径 | 限流 |
|---|---|
/api/auth/* | 10 req/min per IP |
| 其他 | 60 req/min per IP(可通过 RATE_LIMIT env 覆盖) |
超限返 429 + Retry-After header。
CORS
通过 CORS_ORIGINS 环境变量白名单:
bash
CORS_ORIGINS='https://tapilot.dev,https://app.tapilot.dev,tauri://localhost'