企业官网建设流程全解析

Midscene.js：基于视觉 AI 的跨平台 GUI 自动化工具，3 分钟跑起来

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

Midscene.js 是面向 E2E 测试的 GUI 自动化框架：它让多模态大模型（能看图的大模型）直接看界面截图来定位元素，你用自然语言驱动网页、Android、iOS 和桌面应用，不用再写 CSS 选择器或 XPath。

一句话：把「找选择器、点元素」变成「用自然语言描述你要做什么」。

🚀 3 分钟跑起来

用官方 CLI 就能完成第一次自动化，一共四步：

1. 安装 CLI。需要 Node.js 20.19+、22.12+ 或 24+：npm i -g @midscene/cli。
2. 配置模型。Midscene 需要一个有 UI 定位能力的多模态模型。在工具运行目录下建.env：

MIDSCENE_MODEL_BASE_URL="<你的模型服务地址>/v1" MIDSCENE_MODEL_API_KEY="<你的API-KEY>" MIDSCENE_MODEL_NAME="<模型名称>" MIDSCENE_MODEL_FAMILY="<模型系列>"

3. 编写脚本。新建bing-search.yaml，用自然语言描述每一步：

page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索"今日天气" - sleep: 3000 - aiAssert: 结果显示天气信息

4. 运行。执行midscene ./bing-search.yaml，命令行实时输出执行进度，结束后自动生成一份可视化 HTML 报告，每一步的截图和耗时都能回看。

不想先写代码的话，可以装 Chrome 扩展，在浏览器侧边栏里直接试同一套自然语言指令，再把它搬进自动化脚本：

🔍 它是怎么做到的

理解三个要点就够：

纯视觉，不依赖 DOM。元素定位完全由模型看截图完成。canvas 渲染的内容、只有图标没有文字标记的按钮、没有语义结构的原生应用，只要人眼能看到，它就能操作。附带的好处是 token 消耗只和截图分辨率、任务复杂度相关，不会随页面 DOM 节点数量膨胀。

Agent 核心 + 平台适配层。所有平台共用aiAct（规划并执行交互）、aiQuery（提取结构化数据）、aiAssert（断言界面状态）这套 API，区别只在底层连接方式：Web 接 Playwright / Puppeteer，Android 接 adb 和 scrcpy，iOS 接 WebDriverAgent。模型引擎在 packages/core/，浏览器连接层在 packages/web-integration/。

模型可插拔。默认一个多模态模型就够用；遇到复杂多步任务，可以再配置 Planning 模型负责规划、Insight 模型负责数据提取和页面理解，各干各的擅长活。

🛠️ 能帮你做什么

Web 测试集成。在现有 Playwright 用例里加一个 Agent，断言不再绑定选择器：

const agent = new PlaywrightAgent(page); await agent.aiAct('在搜索框输入 Headphones 并回车'); const items = await agent.aiQuery( '{itemTitle: string, price: number}[]', ); await agent.aiAssert('页面顶部显示导航栏');

UI 重构之后，只要页面「看起来还是一样的」，测试通常不用改。需要登录态的页面可以用桥接模式直接连你日常在用的浏览器，省去重新登录：

移动设备测试。adb 连上 Android 手机后，同样一句aiAct就能打开应用、进入设置、读出系统版本号；iOS、HarmonyOS 和桌面端也有完整的连接方式和 Playground。

数据提取与监控。aiQuery按你给的字段定义直接返回结构化数据，比如从商品列表页提取{name, price}数组；aiNumber可以取出当前股价、库存数这类数值，直接喂给你的监控脚本。

⚙️ 进阶选项

AI 规划与元素定位缓存。创建 Agent 时加上cache: { id: "demo-cache" }，相同指令在相似页面上会直接复用已缓存的规划，缓存文件存放在./midscene_run/cache。官方文档给出的实测例子中，执行耗时从 51 秒降到 28 秒；缓存的规划因页面变化执行失败时，会自动回退到模型重新规划，而不是直接报错。

可视化报告与解析。每次运行产出的 HTML 报告记录了分步截图、耗时和 AI 推理过程，失败时可以回看每一步 AI 当时「看到」的画面。npx @midscene/web report-tool还能把报告拆成截图 + JSON，或转录成 Markdown，方便归档或交给其他工具二次消费。

❓ 你可能关心的问题

可以离线跑吗？取决于模型。自托管 UI-TARS、Qwen-VL 这类开源模型即可完全本地运行；用云端模型则需要网络。

必须用指定模型吗？不需要。Qwen、Doubao、GLM、Gemini、GPT、UI-TARS 等都有对应配置，通过MIDSCENE_MODEL_*环境变量切换即可。

加载动画和动态内容怎么处理？用aiWaitFor('页面加载完成')等待视觉条件成立再继续，比固定 sleep 更稳。

执行快不快？单次操作通常秒级，取决于模型响应和网络；开启缓存后，同一脚本重复执行的耗时可接近减半。

结语

Midscene.js 的价值，是把「界面一改、脚本就挂」这件事从你身上挪给了模型。如果你已有测试项目，建议先拿一条用例，把一处选择器断言换成aiAssert感受差异，再逐步扩大覆盖；完整 API 与平台指南见 apps/site/docs/zh/。

下一步：今天就用@midscene/cli写下你的第一个脚本，跑完打开报告，看每一步 AI 看到了什么——这是上手最快的方式。

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