Midscene.js 快速入门3 步让 AI 接管网页与手机的 UI 操作【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene每到周五下午 4 点测试工程师林瑶都要用真机手点一遍登录 → 填表单 → 下单的发布流程每次耗时 40 分钟漏一步就得从头再来。直到她遇到了 Midscene.js——一个用自然语言驱动 UI 自动化的 GUI Agent截图即界面说一句话就能完成操作。一句话定位Midscene.js 是什么Midscene.js 是一个 AI 视觉驱动的 UI 自动化框架它只靠一张截图识别界面元素你用自然语言描述目标它自动完成点击、输入和数据提取。它支持 Web、Android、iOS、桌面 4 类平台一套 API 通用。适合想省掉重复手工操作的 QA、想写更少维护成本的开发者以及不想写代码也要做自动化的普通用户。Midscene.js 的 Web Playground左侧输入自然语言指令右侧浏览器实时执行 UI 自动化操作先说痛点为什么基于选择器的自动化越来越难维护选择器太脆弱你是否也曾在一次前端重构后花 3 小时批量修复 CSS 选择器#login-btn改名、canvas渲染的图标按钮、没有语义标签的自绘组件选择器工具全都够不着。Midscene 不读 DOM 结构直接看截图定位——人眼能看到的元素它都能点到。每个平台一套工具Web 用 PlaywrightAndroid 用 AppiumiOS 用 WebDriverAgent——3 套 API、3 套学习成本还得各自维护。Midscene 用同一个agent.aiAct()调用 Web 和手机平台差异被封装在设备对象里。DOM 验证不了用户真正看到的东西传统断言只能确认节点存在却无法判断高亮颜色对不对、布局有没有错位。Midscene 的aiAssert对截图做视觉断言验证的是渲染结果而非节点。维度传统选择器自动化Midscene.js元素定位写 CSS/XPath界面改动就重写截图 自然语言AI 自动适应覆盖范围无语义节点、canvas、原生 App 够不着屏幕上可见即可操作平台Web / Android / iOS 各需一套工具一套 API 覆盖 4 类平台断言方式DOM 节点是否存在视觉内容是否符合预期编写门槛需要编程和选择器经验自然语言或 YAML 即可最快上手路径3 步跑通第一个脚本第 1 步配置模型约 1 分钟Midscene 需要一个具备 UI 定位能力的多模态模型。以 Qwen 为例4 个环境变量即可export MIDSCENE_MODEL_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 export MIDSCENE_MODEL_API_KEYyour-api-key export MIDSCENE_MODEL_NAMEqwen3.7-plus export MIDSCENE_MODEL_FAMILYqwen3第 2 步写一个最小脚本约 2 分钟npm install midscene/web playwright tsx --save-dev// demo.ts启动浏览器把页面交给 Midscene Agent import { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; const browser await chromium.launch({ headless: false }); const page await browser.newPage(); await page.goto(https://www.ebay.com); const agent new PlaywrightAgent(page); // 页面交给 Agent await agent.aiAct(type Headphones in search box, hit Enter); // 自然语言搜索 const items await agent.aiQuery( // 提取结构化数据 {itemTitle: string, price: number}[], ); console.log(items); await browser.close();第 3 步运行看结果约 1 分钟npx tsx demo.ts几秒后你会看到无头浏览器里弹出搜索框、输入 Headphones 并回车终端打印出商品名和价格数组。整个流程没有任何一行选择器。核心能力拆解Agent 能替你做的 5 件事1. aiAct一句话完成多步操作它是规划型 API观察界面 → 拆解步骤 → 逐个执行适合有分支、有弹窗的不确定路径。await agent.aiAct( 搜索耳机把第一个商品加入购物车并确认购物车数量变为 1, );2. aiQuery把界面变成结构化 JSON描述你要的字段和类型AI 返回严格结构化的数据直接进你的分析流程。const trends await agent.aiQuery( 热搜榜前 10 条{title: string, heat: number}[], );3. aiAssert / aiWaitFor以用户视角做断言页面加载慢弹窗没关用等待和视觉断言兜底而不是猜 sleep 毫秒数。await agent.aiWaitFor(there is at least one headphone item on page); // 等内容出现 await agent.aiAssert(There is a category filter on the left); // 视觉断言布局4. 缓存同一脚本重复跑51 秒变 28 秒开启缓存后相同指令和元素定位会命中midscene_run/cache下的记录减少模型调用失效时自动回退到 AI 重新分析。官方案例中一次回归耗时从 51s 降到 28s。开启缓存后的执行时间线重复步骤直接命中缓存整体耗时从 51 秒降到 28 秒const agent new PlaywrightAgent(page, { cache: { id: smoke-test }, // 读 写缓存 });5. YAML 脚本不写代码也能自动化产品、测试都能直接改的.yaml文件CLI 一条命令就能跑page: url: https://www.bing.com tasks: - name: Search for weather flow: - ai: Search for todays weather - sleep: 3000 - aiAssert: The results show weather information实战场景4 个可以直接照抄的用法场景 1电商主路径夜间回归问题发布前要人工走一遍浏览 → 搜索 → 加购 → 结算耗时且漏测。思路把路径拆成一句 aiAct 目标 关键节点视觉断言丢进 CI 定时跑。关键代码await agent.aiAct(搜索 wireless mouse加购第一个商品); await agent.aiAssert(购物车显示 1 件商品并有小计金额);场景 2Android 真机冒烟测试问题应用发版后要在真机上确认核心功能可用手测每台设备 10 分钟。思路getConnectedDevices()枚举已连接设备循环创建 Agent同一套脚本跑多机型。关键代码import { AndroidAgent, AndroidDevice, getConnectedDevices } from midscene/android; const devices await getConnectedDevices(); const device new AndroidDevice(devices[0].udid); const agent new AndroidAgent(device); await agent.aiAct(打开设置应用查看当前电池电量); await agent.aiAssert(电量百分比已显示);Android Playground左侧是操作步骤右侧是设备屏幕实时投屏AI 如何操作真机一目了然场景 3跨站数据收集问题每天手动从 3 个平台复制价格、销量做对比表容易抄错。思路每个站点一句 aiQuery 拿结构化结果汇总后写文件。关键代码await agent.goto(https://www.ebay.com); const data await agent.aiQuery( 前 5 个商品{name: string, price: number, rating: number}[], );场景 4视觉回归而不只是功能回归问题功能没坏但按钮变灰、价格红标丢了传统断言发现不了。思路用 aiAssert 直接描述应该长什么样让 AI 对截图做视觉判断。关键代码await agent.aiAssert( 促销标签以红色显示在商品图右上角, );iOS Playground与 Web、Android 相同的操作能力设备屏幕在右侧实时回显高频问题新手最容易卡住的 4 个点Q1AI 找不到元素或点歪了怎么办把描述写具体右上角蓝色登录按钮优于登录按钮目标小或与相邻元素难区分时给单次调用加deepLocate: true提高定位精度。Q2执行太慢怎么优化优先用aiTap、aiInput等即时 API 代替会整体规划的aiAct适当调低截图分辨率减少 token调试阶段开启缓存。Q3截图会发给谁隐私敏感怎么办截图会发送给配置的模型服务。担心数据出域时可以接入自托管的开源模型如 UI-TARS、Qwen-VL 系列链路完全在本地。Q4必须联网用云端模型吗不是。Midscene 支持任意 OpenAI 兼容接口本地起 Ollama 也能跑但要注意模型本身要具备 UI 定位能力纯文本模型会定位失败。行动清单从体验到深入安装 Chrome 扩展在任意网页里试用 3 条指令Click the login button、Products on the page, {name: string, price: number}[]、A navigation bar appears at the top约 5 分钟按最快上手路径跑通你的第一个 demo.ts约 10 分钟把一个现有手工测试改写成 YAML 脚本让同事也能直接跑连上 Android 真机用同一套 API 跑一次冒烟读模型配置文档为自己的场景挑性价比最高的模型遇到问题进官方社区提问踩到坑或想到新功能直接提 issue / PR资源区仓库内文档索引快速开始Chrome 扩展 模型配置apps/site/docs/en/quick-start.mdxPlaywright 集成完整示例apps/site/docs/en/integrate-with-playwright.mdx核心 API 概念aiAct / aiQuery / aiAssertapps/site/docs/en/basics.mdx缓存机制详解apps/site/docs/en/caching.mdxYAML 脚本写法apps/site/docs/en/automate-with-scripts-in-yaml.mdx支持的模型与配置apps/site/docs/en/model-common-config.mdxWeb 自动化 demopackages/web-integration/demo/Android 示例packages/android/demo/iOS 示例packages/ios/examples/可视化 Playground 应用apps/playground/今天就选一个你每天重复的界面操作——一段回归、一次填表、一轮数据搬运——把它交给 Midscene.js。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考