企业官网建设流程全解析

Midscene.js 完整指南：用自然语言控制浏览器、手机与桌面界面的 AI UI 自动化框架

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

Midscene.js 是一个 AI 自动化框架：你用自然语言描述操作，它就替你控制浏览器、Android、iOS、HarmonyOS 与桌面端界面。它面向写测试脚本的工程师、做 UI 自动化的人，以及只想用一句话驱动界面的普通用户。

Web Playground：左侧是自然语言指令面板，右侧浏览器根据指令实时操作页面

它是做什么的

Midscene.js 是一款视觉驱动的 UI 自动化工具：它不解析页面代码，而是像人一样"看"屏幕截图，再按你写的中文或英文指令去点击、输入、提取数据。

用两句话解释它的两个核心概念：视觉识别，就是模型对当前截图做理解，直接判断"搜索框在哪、按钮长什么样"，不依赖 DOM（即网页的 HTML 结构代码）；自然语言指令，就是你用一句"在搜索框输入耳机，敲回车"代替locator('#search').fill(...)这类选择器代码，模型把这句话翻译成实际的点击和输入动作。

和 Selenium / Playwright 差在哪

同样是驱动浏览器或设备，Midscene.js 与 Selenium、Playwright 这类经典 UI 自动化工具在工作方式上有三个明显差别：

注意它并非要取代 Playwright：官方推荐的做法是继续用 Playwright/Puppeteer 负责打开页面、管理会话，把"看懂界面、找到元素、执行动作"这一层交给 Midscene 的 Agent。

动手体验

整个过程只有三步：装包、写第一行脚本、跑起来。以 Puppeteer 集成为例，先执行npm install @midscene/web puppeteer tsx dotenv --save-dev，再按模型配置文档设置好MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY等环境变量。

import puppeteer from "puppeteer"; import { PuppeteerAgent } from "@midscene/web/puppeteer"; const browser = await puppeteer.launch({ headless: false }); const page = await browser.newPage(); await page.goto("https://www.ebay.com"); await new Promise((r) => setTimeout(r, 5000)); const agent = new PuppeteerAgent(page); await agent.aiAct('在搜索框输入 "Headphones"，敲回车'); const items = await agent.aiQuery( '{itemTitle: string, price: number}[]，找到列表里的商品标题和价格', ); console.log(items); await browser.close();

运行npx tsx demo.ts，浏览器会自动打开、搜索并打印商品列表。三个核心 API 各有分工：aiAct执行交互动作，aiQuery从页面提取结构化数据，aiAssert对界面状态做断言。完整脚本可以参考 Web 集成示例。

不想写代码的话，也可以安装官方 Chrome 扩展，在任意网页的侧边栏里直接输入指令体验：

Chrome 扩展侧边栏：输入 type "Midscene.js" and click search，扩展自动完成输入与点击

能力全景

🤖 让 AI 直接看屏幕，而不是读代码

传统 UI 自动化工具依赖页面结构：选择器一改就断，没有语义化标注的元素（纯图标按钮、自定义控件、<canvas>）对它们是"看不见"的，原生 App 和跨域 iframe 也基本触达不到。Midscene 只凭截图工作——人眼能看到的东西，它就能定位。这也带来一个额外收益：你能断言的是用户真实看到的效果，比如"按钮是绿色高亮"，而不是"某个节点存在于 DOM 里"。

🖥️ 一套指令通吃 Web、Android、iOS 与桌面

跨平台自动化在 Midscene 里不是四套框架，而是同一组 API。Web 端用PuppeteerAgent或PlaywrightAgent，Android 端通过 adb 连接真机并投屏到浏览器，iOS 端走模拟器或真机，HarmonyOS 和桌面端同理。对测试团队来说，一套写法的指令可以平移到不同端，学习成本只付一次。

Android Playground：左侧展示 AI 分解的每一步（Planning、Locate、Tap），右侧为 Redmi K30 Ultra 的实时屏幕投影

⚡ 用缓存把重复步骤跑快

AI 模型每调用一次都有延迟，重复执行同一脚本时浪费明显。Midscene 内置缓存机制：aiAct这类规划类操作会把指令的执行计划存下来，Web 端还会缓存元素的 XPath 定位信息，命中缓存就直接复用，失效则自动回退到模型重新分析。官方文档给出的实测数据是同一脚本执行耗时从 51 秒降到 28 秒。启用方式只需在创建 Agent 时传入cache: { id: 'my-cache' }，细节见 缓存文档。

两个真实例子

每天定时抓取竞品价格

监控 10 个竞品的价格，传统写法要为每个页面维护一套选择器，改版一次就修一次。用 Midscene 的思路是：goto到商品页后，用aiQuery声明一个提取结构（商品名、价格、库存），把返回的 JSON 数组落盘或推送到告警渠道。页面换了导航栏、换了卡片样式，只要"价格"还在屏幕上，提取逻辑通常不用动。

const sku = await agent.aiQuery( '{name: string, price: number, stock: string}，当前商品的价格与库存', ); if (sku.price < threshold) await sendAlert(sku);

定时任务里跑这一段，就是一份无人值守的价格雷达。

批量注册表单

运营场景里常见"给 50 个测试账号批量填注册表单"。选择器方案要为每个输入框硬编码定位；Midscene 的写法是把整页交给一条aiAct：依次填写用户名、密码、邮箱并同意条款。因为模型是看着当前截图做规划的，字段顺序变了、页面加了验证码提示，它都会按当前布局重新判断该填哪个框，而不是机械执行旧坐标。

踩坑经验

• 指令执行后提示找不到元素：多数是指令太笼统。加上位置、颜色等特征词，例如"右上角蓝色登录按钮"，并且一条指令只描述一个动作；确认截图清晰、模型服务可用后再重试。
• Android 设备连不上：常见原因是 USB 调试未开、设备未授权或 adb 未装好。打开开发者选项里的 USB 调试，在设备上确认授权弹窗，再执行adb devices检查设备是否在线；iOS 则需先完成模拟器与 WebDriverAgent 的初始化。
• 脚本越跑越慢：重复执行的脚本应开启缓存，命中时跳过模型调用；另外把大任务拆小，每次截图只覆盖必要区域，也能减少开销。
• 点击位置有偏移：与所用模型的定位能力和截图分辨率有关。按模型策略选 UI 定位能力强的多模态模型，必要时降低截图尺寸，不同服务商的兼容问题 FAQ 里也有对应处理办法。

小结

Midscene.js 把"看懂界面"这一层从你的代码里拿走了：一套 API、一组自然语言指令，覆盖 Web、Android、iOS、HarmonyOS 与桌面端的 UI 自动化。建议从快速开始入手，配合API 参考把指令写进现有测试；遇到具体问题可以到 Discord 或飞书交流群里提问，仓库的 issues 区也欢迎你的反馈。

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