基于 Midscene 的视觉驱动 Android 自动化工具，无需 DOM 或无障碍标签，通过自然语言控制真机或模拟器完成点击、滑动、输入等全类型 UI 交互。
说明：
## 核心用法
Android Device Automation 是一个基于 **Midscene.js** 的视觉优先 Android 自动化解决方案，通过 `npx -y @midscene/android@1` CLI 工具实现对 Android 设备的自然语言控制。
### 关键能力
– **纯视觉驱动**：完全依赖截图分析，无需应用内嵌代码或无障碍标签，可操控任意可见界面元素
– **全交互覆盖**：支持点击、长按、双击、滑动、拖拽、缩放、文本输入、系统导航（返回/主页/最近任务）等完整手势
– **ADB 深度集成**：底层通过 ADB 与设备通信，支持 `runadbshell` 执行原生 Shell 命令
### 命令体系
| 命令 | 用途 |
|:—|:—|
| `connect` / `disconnect` | 会话生命周期管理 |
| `launch –uri` | 启动应用或打开 URL |
| `take_screenshot` | 获取当前屏幕状态 |
| `act –prompt` | 执行自然语言描述的高阶操作（推荐批量描述复杂流程）|
| `assert –prompt` | 视觉断言验证，用于 QA 检查 |
| `tap –locate` | 基于参考图像的精确定位（支持多模态 JSON 配置）|
| `report-tool` | 报告转换（HTML → Markdown/JSON）|
### 配置要求
必须配置多模态视觉模型环境变量：
– `MIDSCENE_MODEL_API_KEY`
– `MIDSCENE_MODEL_NAME`（推荐：Gemini-3-Flash、Qwen 3.5、Doubao Seed 2.0 Lite、GLM-4.6V）
– `MIDSCENE_MODEL_BASE_URL`
– `MIDSCENE_MODEL_FAMILY`
## 显著优点
1. **零侵入性**：被测应用无需任何改造，适用于 WebView、原生应用、游戏等任意技术栈
2. **自然语言编程**：用人类语言描述操作意图，大幅降低自动化脚本编写门槛
3. **跨应用无缝操作**：可在系统设置、浏览器、第三方应用间自由跳转
4. **完整审计追踪**：自动生成 HTML 报告，含步骤详情与操作回放视频
5. **多设备支持**：通过 `–deviceId` 参数同时管理多个连接设备
## 潜在缺点与局限性
1. **模型依赖性强**：核心功能绑定第三方多模态 LLM，存在 API 成本、延迟（单次指令约 1 分钟）及服务商稳定性风险
2. **非确定性行为**：视觉模型可能对复杂 UI 产生定位偏差，需配合 `assert` 验证与人工复核
3. **同步执行约束**：必须逐条同步执行命令，禁止后台并行，高频率操作场景效率受限
4. **环境配置门槛**：需预先配置 ADB、开启 USB 调试、解决设备授权等 Android 开发环境问题
5. **离线不可用**：完全依赖云端模型推理，无离线模式
## 适合人群
– **移动端 QA 工程师**：进行端到端回归测试、视觉验证测试
– **开发者**：快速复现 Bug、录制操作步骤、生成演示流程
– **自动化脚本编写者**：需要跨技术栈（原生/Hybrid/游戏）的统一自动化方案
– **产品经理/设计师**：无需技术背景即可验证交互原型
## 常规风险
| 风险类别 | 具体描述 | 缓解建议 |
|:—|:—|:—|
| **隐私泄露** | 截图可能包含敏感信息（短信、密码输入框），上传至第三方模型服务商 | 使用私有部署模型；避免在含敏感信息界面执行操作 |
| **误操作风险** | 模型误判导致 unintended 点击（如误触支付按钮） | 关键操作前使用 `assert` 验证当前状态；优先在模拟器/测试机运行 |
| **设备状态异常** | 屏幕锁定、USB 授权失效导致命令超时 | 前置检查设备状态；配置自动唤醒与解锁流程 |
| **成本失控** | 高频截图 + 多轮推理可能导致 API 费用激增 | 合并操作为单条 `act` 指令；控制截图频率 |
| **供应链风险** | `@midscene/android` 依赖 Node.js 生态，版本冲突可能影响稳定性 | 锁定版本号；定期执行依赖健康检查 |
## 工作流最佳实践总结
1. **前置 ADB 启动**：先用 `adb shell am start` 将应用唤至前台，再用 Midscene 接管
2. **批量描述操作**：将连续步骤合并为单条 `act` 指令，减少 API 调用次数
3. **视觉确认闭环**：每次 `act` 后执行 `take_screenshot`，人工或 `assert` 验证结果
4. **结果主动汇报**：任务完成后必须主动输出执行摘要、关键数据、截图路径及文件清单
会员专属
