企业官网建设流程全解析

如何用 Midscene.js 完成跨平台 UI 自动化

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

Midscene.js 是一个基于视觉语言模型的开源 UI 自动化工具。它不依赖页面结构，也不需要你为每个按钮写选择器，而是拿截图加自然语言指令替你完成操作，一套 API 覆盖 Web、Android、iOS、HarmonyOS 和桌面端，适合做 E2E 测试的工程师，以及任何需要自动化跨平台界面的开发者。

第一次体验：跑通最小 Web 脚本

理解 Midscene.js 最快的方式，是运行一个 8 行的 YAML 脚本，亲眼看着浏览器把搜索做完。

选一个任务

这里选官方示例里的场景：打开 Bing，搜索"today's weather"，并验证结果页出现了天气信息。这个流程只有搜索和断言两步，恰好能跑完"截图 → 理解 → 操作 → 校验"的完整闭环。

准备环境

只需要 Node.js（20.19 及以上）和 CLI：

git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene npm i -g @midscene/cli

然后在运行目录下创建.env文件，写入四个变量：MIDSCENE_MODEL_BASE_URL（模型服务地址）、MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_NAME（模型名）、MIDSCENE_MODEL_FAMILY（模型系列）。模型要求是能定位界面元素的多模态模型，官方示例使用 Qwen3.x，也支持 GLM-4.6V、gemini-3.5-flash、UI-TARS，包括可自托管的开源模型。

运行最短脚本

创建bing-search.yaml：

page: url: https://www.bing.com tasks: - name: Search for weather flow: - ai: Search for "today's weather" - sleep: 3000 - aiAssert: The results show weather information

flow 里ai是自然语言操作，sleep等待 3 秒，aiAssert做断言。执行：

npx midscene ./bing-search.yaml

终端会打印执行进度，结束后生成可视化报告，每一步的截图和判断都能在报告里回看。

如果你暂时不想写代码，也可以从 Chrome 应用商店安装 Midscene 扩展，浏览器右侧会出现指令栏：Click the login button（aiAct）、Products on the page, {name: string, price: number}[]（aiQuery）、A navigation bar appears at the top of the page（aiAssert），三类指令都能直接执行，验证过的指令之后可以原样搬进脚本。

工作原理白话版：截图如何变成点击

Midscene.js 的核心是"截图 + 多模态大模型"，元素定位完全基于截图，不读页面源码。

可以这样理解：传统 DOM 方案像查页面的"楼宇目录"，靠 ID、类名在源码里找按钮，速度快，但目录一重构就失效；图标按钮、canvas、跨域 iframe 这类没有语义标记的元素，在目录里根本不存在。Midscene 则像一个站在屏幕前的人：每一步先截图，交给视觉语言模型，问"登录按钮在哪、现在页面显示什么"，模型给出坐标后再去点击。人眼能看到的，它都能操作。

这个机制还有一个附带好处：断言校验的是"用户真正看到的东西"，比如颜色、高亮、布局是否正确，而不只是"这个 DOM 节点存不存在"。

一个场景深挖：移动端登录回归

移动端自动化最常见的落点是回归测试：每个版本发布后，都要把登录这类核心流程过一遍。

以 Android 为例，目标是验证某应用的"用户名 + 密码"登录流程。脚本要点有两个：

• 在android: deviceId字段填入设备号（用adb devices查询），CLI 才知道要控制哪台设备；
• tasks段落用白话写流程：打开登录页，在用户名和密码输入框分别填入内容，点击"登录"按钮，最后用一条aiAssert确认主页已显示。

跑法和 Web 完全一致，用同一条midsceneCLI 命令即可拿到逐步报告。回归场景的价值在维护成本：界面改版后，只要按钮还认得出是"登录按钮"，脚本一行都不用改。

其他场景都是同一套机制的变体：Web 表单填写提交、电商页面提取结构化数据、iOS 系统设置项切换，以及 Bridge 模式——用本地脚本控制你桌面上已登录的 Chrome，脚本与手动操作共用同一个浏览器会话。

适用边界与成本：什么场景不适合

Midscene.js 的代价是每一步都对应一次模型调用：比纯 DOM 操作慢，且消耗 API 费用或算力。运行依赖网络和模型服务，断网不可用。

因此，几百次的高频断言、毫秒级时序测试、预算严格受限的场景，传统方案仍然更合适。它更匹配需要"看"的场景：跨平台回归、视觉校验，以及 canvas、原生控件这类 DOM 够不着的操作。

下一步

想继续深入，仓库内这几个入口就够：

• 快速开始（扩展安装 + 模型配置）：apps/site/docs/en/quick-start.mdx
• YAML 脚本 runner 详解：apps/site/docs/en/yaml-script-runner.mdx
• CLI 脚本示例集：packages/cli/tests/midscene_scripts/
• Bridge 模式（本地脚本控制桌面 Chrome）：apps/site/docs/en/bridge-mode.mdx

实操建议：先把 bing-search 示例完整跑通，确认报告符合预期后，把 URL 换成你自己的页面，跑通再考虑接入 CI。

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