Midscene Skills 怎么用:让 Agent 看截图操作手机

让 Agent 操作手机,麻烦在于很多 App 拿不到界面树:游戏、小程序、Flutter、自绘控件,按钮在代码层面根本找不到。字节跳动 web-infra-dev 团队开源的 Midscene 换了个思路,只看截图。它的 Skills 仓库把这套能力打包给 Claude Code 这类编程 Agent,一条命令装好,就能用自然语言操作安卓、iOS、鸿蒙和桌面。这篇按官方 README 和各平台 SKILL.md 讲安装、模型配置、操作流程和排错。
它是什么,适合谁
Midscene.js 是 MIT 许可的开源项目,截至 11 月 9 日 GitHub 约 1.55 万星,最新版 v1.17.7 发布于 11 月 6 日。midscene-skills 是同团队的 Skill 仓库,也是 MIT,skills/ 目录下有 6 个 Skill:
| Skill | 控制对象 | 底层连接 | 命令包 |
|---|---|---|---|
| android-automation | 安卓手机、模拟器 | ADB | @midscene/android@1 |
| ios-automation | iPhone | WebDriverAgent | @midscene/ios@1 |
| harmony-automation | HarmonyOS NEXT 设备 | HDC | @midscene/harmony@1 |
| computer-automation | macOS / Windows / Linux 桌面 | 系统输入 | @midscene/computer@1 |
| browser | 无头 Chrome,或你已登录的 Chrome | Puppeteer;CDP 或 Midscene 扩展桥接 | @midscene/web@1 |
| vitest-midscene-e2e | Web、安卓、iOS 的端到端测试 | Vitest | 生成测试脚手架 |
和读界面树的方案比,纯截图的好处是不挑技术栈,自绘控件和游戏画面一样能点;代价是每一步都要过一次视觉模型,速度和费用都比直接调 ADB 高,定位也可能偏。所以 SKILL.md 建议先用 ADB 把目标 App 打开到前台,界面上的交互再交给 Midscene。
适合做真机冒烟测试、在 App 里查数据、给自动化测试补视觉断言的开发者和测试同学。前置条件:装好 Node.js;安卓要有 ADB 并在手机上打开 USB 调试;鸿蒙要装 HDC(随 DevEco Studio 提供,或设置 HDC_HOME);iOS 要先让 WebDriverAgent 在设备上跑起来。
第一步:安装 Skill
# 通用
npx skills add web-infra-dev/midscene-skills
# 只装给 Claude Code
npx skills add web-infra-dev/midscene-skills -a claude-code
第二步:配一个会「看图找按钮」的模型
Midscene 需要视觉定位强的模型,就是能从截图里准确框出界面元素的那种。配置走四个环境变量,可以写进当前目录的 .env,Midscene 会自动读。用阿里云百炼的千问 3.5,SKILL.md 给的写法是:
MIDSCENE_MODEL_API_KEY="你的百炼 key"
MIDSCENE_MODEL_NAME="qwen3.5-plus"
MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
MIDSCENE_MODEL_FAMILY="qwen3.5"
MIDSCENE_MODEL_REASONING_ENABLED="false"
换豆包,就把模型名写成 doubao-seed-2-0-lite、地址写火山方舟的 https://ark.cn-beijing.volces.com/api/v3、family 写 doubao-seed。文档列的常用模型还有智谱 GLM-4.6V、Gemini 3 Pro / Flash。截图会发给你配置的模型服务,手机上有敏感信息时要想清楚。
第三步:跑一次安卓任务
装好后直接对 Agent 说「用 Midscene 安卓 skill 打开设置,进 Wi-Fi 页面,告诉我连的是哪个网络」。Agent 背后执行的是这样一串命令,每条都是无状态的 CLI:
npx -y @midscene/android@1 connect --device-id emulator-5554
npx -y @midscene/android@1 launch --uri com.android.settings
npx -y @midscene/android@1 take_screenshot
npx -y @midscene/android@1 act --prompt "打开 Wi-Fi 设置,告诉我当前连接的网络名"
npx -y @midscene/android@1 assert --prompt "页面上显示了 Wi-Fi 开关和已连接的网络"
npx -y @midscene/android@1 disconnect
act 一次调用里能点、长按、输入、滑动、拖拽、双指缩放,也能按返回、主页键。assert 只检查当前屏幕,不做操作,适合当验收;加 --message 可以在 CI 日志里写你自己的失败说明。每次运行会生成 HTML 报告,带逐步回放;要喂给别的工具时用 report-tool --action to-markdown 转成 Markdown。
同一个 App 里连续几步操作,合成一条 act 写,别拆成三条。
SKILL.md 给 Agent 定了四条硬规则,你写自己的工作流时也照这个来:命令不能放后台跑;一次只跑一条,看完截图再决定下一步;每条命令留够时间,常见要 1 分钟左右,复杂的 act 更久;做完要主动汇报结果和截图路径。
让它更准、更快的几个开关
- 先用 ADB 把 App 拉到前台:
adb shell am start -n 包名/Activity比让模型一路点进去快得多。 - 描述要具体:写「右上角的搜索图标」「列表第三项」,别只写「那个开关」。
- 点偏了加
--deep-locate,多一轮视觉推理定位;多步任务规划乱加--deep-think。两者都会慢一点,可以叠加。 - 截图慢或不稳:每条命令都加
--use-scrcpy。 - Toast、加载条这种一闪而过的状态:另开终端
record start --output ./obs.json,操作完 Ctrl+C,再assert --record ./obs.json。 - 要点一个指定图标:用
tap --locate传参考图,比纯文字描述稳。
跑通之后:沉淀成 E2E 测试
一次性操作靠对话就够了,要反复跑就得变成测试。vitest-midscene-e2e 这个 Skill 管这件事:它会拉一份官方样板工程到 ~/.midscene/boilerplate/,对照着给你的项目补齐 Vitest 配置和 .env,不覆盖已有文件。Web 走 Playwright,安卓走 ADB 加 scrcpy,iOS 走 WebDriverAgent。它对写法有一条硬性要求:用户用自然语言描述的一步,就整句交给 aiAct,不要拆成 aiTap、aiInput 几个细粒度调用:
await ctx.agent.aiAct('在搜索框输入 "iPhone",然后点搜索按钮');
这样写出来的用例,界面改版、按钮挪位置也不用改选择器,代价同样是每一步都要调一次模型。
常见坑
| 现象 | 处理 |
|---|---|
| 设备显示 unauthorized | 解锁手机,点允许 USB 调试,再 adb devices |
| 设备显示 offline | 重插线,adb kill-server && adb start-server |
| 命令超时 | 屏幕灭了或锁着:adb shell input keyevent KEYCODE_WAKEUP 后解锁 |
| 连了多台设备,操作错了机器 | 每条命令带 --device-id |
| iOS 连接被拒或超时 | WebDriverAgent 没在跑;已有会话就传 --wda-host、--wda-port、--session-id |
| macOS 桌面控制无效 | 给终端开「隐私与安全性 → 辅助功能」权限后重启终端 |
README 开头有一句安全提醒:它能控制屏幕上的一切,结果不一定可预期。建议用测试机或模拟器,别在装着支付和工作账号的主力机上让 Agent 自由发挥。另一条思路是走 MCP、带审批规则的手机 Agent,可以对照站内的 Pinky 手机 Agent。
完成标准
adb devices(或hdc list targets)能看到设备,connect成功。- 一条
act完成多步操作,assert通过,HTML 报告里能看到回放。 - Agent 结束时主动给出结果和截图路径。
最后
先拿安卓模拟器配好千问或豆包的 key,让 Agent 跑一遍「打开设置查 Wi-Fi」,跑通了再换成你自己的 App。