Midscene.js 上手指南：用自然语言操作界面，5 分钟跑通 AI 视觉 UI 自动化-编程实验室

Midscene.js 上手指南：用自然语言操作界面，5 分钟跑通 AI 视觉 UI 自动化

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

你每次发版前都要改选择器，页面一重构脚本就全红；或者你想让机器人替你点一遍 App，却得先啃 DOM 结构。Midscene.js 把这件事换了个做法：它对界面截图、用视觉模型理解、再执行点击和输入。你只管说人话，它负责在界面上找到目标并完成操作——这就是自然语言驱动的 UI 自动化。

1. 先跑起来：免安装快速上手

最省事的路径是 Chrome 扩展。在 Chrome 商店安装 Midscene 扩展后，打开它，填入一个视觉模型（比如 Qwen3-VL）的 API Key，不需要 clone 代码、不装依赖。

然后打开任意网页，点扩展图标，输入一句话，例如"在搜索框输入 Midscene，然后回车"。它会自己找到输入框、填词、提交。你不需要写任何代码，也不用关心按钮在 DOM 里的哪一层。

2. 它能替你做什么

网页回归测试：前端同学每次改完页面，让它自动走查核心链路（搜索、下单、登录），替代手工点点点。
移动端 App 测试：Android 和 iOS 同学不写 XPath，直接描述"打开设置查看系统版本"，App 改 UI 后脚本不用跟着重写。
界面数据提取：运营同学需要从活动页抓取价格、标题等字段，它按截图读出来并整理成结构化 JSON。
跨端流程串联：测试同学让浏览器和手机设备在同一个任务里接力操作，省去两端脚本互相同步的维护成本。

3. 它是怎么工作的

整条链路很短：每次执行前它先截一张图，把图交给视觉语言模型，模型按你的指令理解界面并定位到具体元素，最后由它完成点击、输入这些原子操作。

关键点在于"只看图"。元素有没有语义标签、是原生 App 还是 canvas 画出来的，它都不关心——只要人眼能在截图里看到的东西，它就能定位到。

核心引擎在 packages/core/src/，Android 控制逻辑在 packages/android/src/，界面交互组件在 packages/visualizer/src/。

4. 三种接入姿势

4.1 浏览器扩展

适合谁：想立刻验证效果的人，包括非开发角色。怎么接：装扩展、填模型 Key，打开网页就能说人话。能做什么：在你正在看的页面上直接执行 Action（操作）、Query（取数）、Assert（断言）三类指令，顺便观察它的每一步决策。

4.2 JavaScript SDK

适合谁：要把自动化写进测试或 CI 的同学。怎么接：装@midscene/web，配合 Playwright 或 Puppeteer 建一个 Agent，先配好模型环境变量（MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_API_KEY等）。能做什么：aiAct执行操作、aiQuery提取数据、aiAssert断言界面状态，全部用自然语言参数表达。

import { PlaywrightAgent } from '@midscene/web/playwright'; const agent = new PlaywrightAgent(page); // page 由 Playwright 打开 await agent.aiAct('在搜索框输入 Midscene，按回车'); // 自然语言操作 const items = await agent.aiQuery( // 提取结构化数据 '{title: string, price: number}[], 列出页面上的商品' );

4.3 桥接模式

适合谁：需要复用你自己登录态、Cookie 和浏览器插件的场景。怎么接：扩展开启桥接模式后，本地跑一段脚本连接它，SDK 提供connectCurrentTab()接管当前标签页。能做什么：脚本操作你真实使用的 Chrome，实现"人看得到、脚本也能操作"的同一会话，适合带登录态的业务流程。

5. 避坑与进阶技巧

开启缓存复用：给 Agent 加cache: { id: "xxx" }，重复执行同一条指令时会直接复用计划与元素定位，官方用例里执行耗时从 51 秒降到 28 秒；缓存文件落在./midscene_run/cache，界面大改后删掉重新生成即可。
按场景选视觉模型：追求速度选轻量模型，复杂页面和精细定位换能力更强的模型；模型通过环境变量切换，先拿同一个脚本横评通过率再定。
用可视化报告排错：每次运行都会生成 HTML 报告，逐步回看截图、AI 规划和耗时，失败在哪一步、当时界面上是什么样子，一眼可见，比翻控制台日志快得多。