核心用法
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_KEYMIDSCENE_MODEL_NAME（推荐：Gemini-3-Flash、Qwen 3.5、Doubao Seed 2.0 Lite、GLM-4.6V）MIDSCENE_MODEL_BASE_URLMIDSCENE_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. 结果主动汇报：任务完成后必须主动输出执行摘要、关键数据、截图路径及文件清单