企业官网建设流程全解析

5分钟让手机听你指挥：Midscene 真机自动化快速上手

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

读完整篇文章，你能把一台 Android 真机接上 Midscene，用一句自然语言让它打开设置、读取数据，再把这些操作固化成可重复执行的 YAML 自动化脚本。Midscene 是一个 AI 驱动的 GUI 自动化框架，核心能力是用自然语言控制 Android、iOS、浏览器和桌面，不依赖控件 ID 和 XPath。

手里有一台真机：5分钟接入 Android Playground

读完这节，你会得到一个正在实时投屏的 Playground 窗口，之后所有验证都在它上面完成，不用先写任何代码。

准备工作只有三件事：

1. 装好 adb 并确认真机或模拟器能连上，手机需开启「开发者选项 → USB 调试」：

adb devices -l

2. 输出里出现device状态的序列号，说明连接就绪。
3. 启动 Android Playground：

npx --yes @midscene/android-playground

Playground 会在浏览器打开一个窗口，右侧是设备投屏。点齿轮按钮，把模型 API Key 粘贴进去保存即可。

注意这一步：配置粘贴错一个字段，后面所有指令都会失败。模型、Key、Base URL 的完整字段说明见文档 apps/site/docs/zh/platforms/android.mdx。

第一个任务：让它打开设置并读出结果

读完这节，你会理解 Midscene 的三个核心动作：aiAct（做）、aiQuery（查）、aiAssert（验），之后写脚本就是它们的排列组合。

把它想象成一个「看着屏幕的实习生」：你说目标，它自己找按钮、判断页面状态，你不用告诉它按钮在第几像素。

在左侧输入框输入：

aiAction: Open the settings to check the current android version number.

左边时间线会逐步展开：Planning → 定位 Settings 图标 → Tap → 再次规划。这就是 Midscene 的工作方式——每一步都基于当前截图重新规划，所以页面弹窗、广告不会轻易让它跑偏。

验证成功后，换个「查询」试试：

aiQuery: 当前设备的型号，{model: string, miui: string}

结构化数据会直接显示在结果区。最后加一句断言收尾：

aiAssert: 页面顶部显示 My device

三个动作都跑通，说明模型、设备、投屏链路全部正常。

脚本化：把一条指令变成可重复的 YAML 任务

读完这节，你能把 Playground 里验证过的流程写成 YAML 文件，一条命令批量跑完，并自动生成执行报告。

在 Playground 里验证过的指令，几乎可以原样搬进 YAML。参考仓库里的示例 packages/cli/tests/multi_yaml_scripts/，一个最小脚本长这样：

android: deviceId: emulator-5554 tasks: - name: 搜索耳机 flow: - aiAction: open browser and navigate to ebay.com - aiAction: type "Headphones" in search box - aiQuery: "{name: string, price: number}[]" - aiAssert: There is a Filter button on the page

用 CLI 执行：

npx --yes @midscene/cli ./script.yaml

想一次跑多个文件时，写一个索引文件，用concurrent控制并发、files列出脚本，仓库里的 multi_yaml_android_scripts 示例 就是现成模板。想换到 iOS 或桌面，只需要把android段换成对应平台配置，任务流程不变。

跑完后在控制台会看到报告路径，浏览器打开即可逐帧回放每一步截图和 AI 决策：

避坑清单：连接、模型与报告常见问题

读完这节，你遇到前八成的报错都能自己排掉，不用翻 issue。

• adb 连接正常但点击报INJECT_EVENTS权限错误：真机注入事件需要受信任的调用方，先换官方模拟器跑通流程，真机则确认设备已授权并重启 adb 服务。
• 本地 Ollama 报 403：设置环境变量OLLAMA_ORIGINS="*"后再启动。
• 页面跳转有延迟导致断言失败：别猜时间，用aiWaitFor等条件成立，例如aiWaitFor: There is at least one product on the page。
• 指令越模糊，行为越随机：「点击右上角的设置图标」比「打开设置」稳定得多，写脚本时尽量带上位置线索。
• 浏览器扩展冲突：在 Chrome 扩展里报Cannot access a chrome-extension:// URL时，是其他扩展向页面注入了脚本，进chrome://extensions/逐个禁用排查。
• 报告里查问题：失败步骤的截图就在报告对应节点，对照 AI 的规划文字基本能定位是模型识别偏差还是页面变了。

这套工具适合谁，从哪里继续

读完这节，你能判断 Midscene 是否适合你的场景，并知道下一步该看哪份文档。

适合你，如果：你要测 App 但讨厌维护一堆控件选择器；你要把「回归一遍主流程」从半小时压到一句话加一杯咖啡；你要在 Android、iOS、Web 之间复用同一套自然语言描述。不适合你，如果你需要毫秒级精度的操作回放，或对成本敏感的超大批量点击测试——它每一步都依赖多模态模型推理，稳定性换的是算力开销。

继续深入，建议按这个顺序看：快速开始（浏览器扩展玩法）→ Android 平台指南（SDK 与自定义动作）→ YAML 脚本运行器（完整字段参考）。仓库地址：git clone https://gitcode.com/GitHub_Trending/mid/midscene

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene