教程2026-11-09 · 智涌AI

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

Midscene Skills 教程头图:终端里依次执行安装 Skill、连接安卓模拟器、打开设置、act 操作 Wi-Fi 页面和 assert 断言,最后生成 HTML 报告;标注 6 个 Skill、3 个移动平台、每条命令约 1 分钟

让 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-automationiPhoneWebDriverAgent@midscene/ios@1
harmony-automationHarmonyOS NEXT 设备HDC@midscene/harmony@1
computer-automationmacOS / Windows / Linux 桌面系统输入@midscene/computer@1
browser无头 Chrome,或你已登录的 ChromePuppeteer;CDP 或 Midscene 扩展桥接@midscene/web@1
vitest-midscene-e2eWeb、安卓、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 更久;做完要主动汇报结果和截图路径。

让它更准、更快的几个开关

跑通之后:沉淀成 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。

完成标准

最后

先拿安卓模拟器配好千问或豆包的 key,让 Agent 跑一遍「打开设置查 Wi-Fi」,跑通了再换成你自己的 App。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。