Midscene.js：3分钟跑通自然语言UI自动化

【免费下载链接】midsceneAI-powered, vision-driven UI automation for every platform.项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

先交代一句结论：Midscene.js 是一个视觉驱动的开源 UI 自动化 SDK。它不读 DOM、不写选择器，只靠截图加上多模态模型，你用自然语言描述"点什么、输入什么、验证什么"，它就能在网页、Android、iOS、鸿蒙和桌面应用上替你完成。下文按我第一次上手的真实过程展开，没有代码基础也能看懂。

第0天：我为什么一直在"追着选择器改"

晚上十点，产品说把按钮文案从"提交"改成"立即提交"。我改完发现，三条用例红了——因为它们的xpath里写着"提交"。这不是第一次了：改个 class、调一下布局、加一层包裹 div，测试就整片崩。选择器是 UI 测试里最脆弱的关节，而维护它们的时间早就超过了写用例的时间。

后来我试过几类"智能定位"工具，本质还是读 DOM、读无障碍树。遇到纯图标按钮、自定义画布控件、跨域 iframe 就抓瞎；原生 App 更是够不着。结构一变，工具跟着瞎。直到有人给我看 Midscene.js 的思路：动作定位只依赖截图，和页面结构完全解耦。结构怎么改，和它没关系。

第1步：装个 Chrome 扩展，先零代码玩起来

第一次上手最友好的方式是 Chrome 扩展。去应用商店搜 Midscene 装上，浏览器右侧会出现一个侧边栏，点齿轮图标把模型配置粘贴进去（它认export KEY="value"这种格式），然后随便打开一个网页，输入一句人话：

在搜索框输入 "Midscene.js" 并点击搜索

页面真的动了 ✨ 侧边栏里有 Action、Query、Assert 三种模式，分别对应"让它操作""让它提取数据""让它验证状态"。整个过程我没写一行代码，十分钟就摸清了它"懂不懂人话"。插件和后面要讲的 SDK 共用同一套核心，在插件里验证通过的指令，写成脚本后行为一致——这一点很关键，等于先试玩再投资。

第2步：写第一个脚本，搜索、提取、断言一次跑通

扩展玩熟了，就该写脚本了。SDK 的起步仪式感很轻：装@midscene/web和playwright，把模型配置写成环境变量，然后写一个几十行的文件。核心就三个方法：

• aiAct('在搜索框输入 "Headphones"，然后回车')——执行动作
• aiQuery('{ title, price }[]，列表中的耳机商品')——按结构提取数据
• aiAssert('页面左侧有一个分类筛选栏')——自然语言断言

跑完，终端会打印一行report file updated，指向一个 HTML 报告。打开它，能看到每一步操作、模型当时的截图、提取到的数据、断言结果，全部按时间线回放。排查 AI 行为时，这个报告比任何日志都好用。

我第一次跑通这个流程，从装依赖到看到报告，大概十分钟。而之前写一条带选择器的用例，光定位元素就要折腾半小时——这是最直观的账。

第3步：把同一套语言搬到手机和桌面

脚本能跑网页不算稀奇，让我真正改观的是它覆盖的边界。项目里每个平台都有独立实现，但 API 是同一套：

• Android：通过 ADB 连接设备，控制任意应用（基于 scrcpy 的屏幕流）
• iOS：借助 WebDriverAgent，iPhone、iPad 都能操作
• 桌面端：Windows、macOS、Linux 的原生键鼠控制
• 另外还有 HarmonyOS，以及<canvas>、跨域 iframe 这类"结构性工具看不见"的界面

我在 Android 上试了一条"打开设置，查看当前系统版本号"。左侧面板会展示 Planning、Insight、Locate、Action 四步：模型先规划，再观察界面、定位元素、执行动作，每一步都能看到它的依据，而不是一个黑盒。

手机和桌面之所以也能跑，是因为它本来就只依赖截图——能截到图，就能被驱动。这也意味着你学会一个平台，其他平台只是换了一块"屏幕"。

踩坑记录：三个提前知道能省时间的事

1. 模型是硬前提。它支持 Qwen3.x、Doubao-Seed-2.1、GLM-4.6V、Gemini、UI-TARS 等，其中部分开源模型可以本地自托管，敏感页面不出网。先确认你的模型有 API key 再开始，不然装上也没反应。
2. 每一次操作都有模型调用成本。它提供了缓存机制，重复的请求可以复用结果；正式跑量之前，先掂量一下单条用例的调用次数，别让账单先于结论到达。
3. 报错先看报告。默认生成的 HTML 报告记录了模型每一步的截图和推理过程，90% 的"它为什么这么点"都能在报告里找到答案 🔍

诚实评估：它适合谁，不适合谁

适合：反复改版导致用例频繁失效的项目；需要覆盖 Web+App+桌面多端的小团队；想验证"用户真正看到的样子"（颜色、高亮、布局）的场景；以及刚入行的测试新人——自然语言用例几乎没有学习门槛。

不适合：对每次执行要求完全确定性、零误差的场景（模型有概率性，和传统断言是两种哲学）；对单次运行成本敏感的极大规模用例；纯性能压测这类不需要"看懂界面"的任务。另外，如果整个项目只需要跑三条固定用例，引入它未必划算。

给你的行动清单

如果你有点心动，我的建议是：先跑通最小示例，再决定要不要接入你的项目。

仓库里有完整的中文上手文档（路径apps/site/docs/zh/quick-start.mdx），核心引擎在packages/core。想动手的话，git clone https://gitcode.com/GitHub_Trending/mid/midscene之后跟着快速开始走一遍：装扩展试两句指令、跑一个脚本、看一份报告。半小时内，你就能判断它适不适合你的团队。

选择器这笔账，大多数项目跑一次重构就回本了。🎯

【免费下载链接】midsceneAI-powered, vision-driven UI automation for every platform.项目地址: https://gitcode.com/GitHub_Trending/mid/midscene