Midscene.js 上手教程：10 分钟安装并跑通第一个 AI 视觉自动化脚本-开发者社区

Midscene.js 上手教程：10 分钟安装并跑通第一个 AI 视觉自动化脚本

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

电商后台一改版，几百个 XPath 集体失效；App 升个版，写死的坐标又对不上。Midscene.js 是一个 AI 视觉驱动的跨平台自动化框架：多模态大模型直接看截图理解界面，你用一句自然语言描述任务，它就在 Web、Android、iOS、桌面端完成点击、输入和验证，脚本里不写任何选择器和坐标。

Midscene.js 和传统自动化的区别：不看 DOM，只看截图

一句话区分：传统自动化靠选择器或屏幕坐标找元素，Midscene.js 靠 AI 看截图找元素。所谓视觉驱动，就是让模型像人一样"看着界面操作"，而不是在代码里维护一堆 XPath。

元素没有语义标记也没关系：纯图标按钮、canvas 画布、原生 App，人眼能看到它就能定位到
界面改版后通常只需改一句自然语言，不用追着选择器满仓库改
断言的是用户实际看到的内容（高亮、布局、渲染状态），而不只是"某个 DOM 节点存在"

代价是每步多一次模型调用，速度和成本要权衡；对跨端、弱语义的界面，这笔账通常划算。想先感受差异，下面直接跑起来。

🚀 10 分钟完成 Midscene.js 安装并跑通第一个 demo

以 Web 场景为例，这也是最常见的 AI 自动化测试入口。第一步是建项目、装依赖、配模型——环境变量只需关心 API Key、模型名和 Base URL 这三项，它们告诉 Midscene.js 调谁家的模型、用哪把钥匙：

mkdir midscene-demo && cd midscene-demo && pnpm init pnpm add @midscene/web playwright tsx export MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" export MIDSCENE_MODEL_API_KEY="你的Key" export MIDSCENE_MODEL_NAME="qwen3.7-plus" export MIDSCENE_MODEL_FAMILY="qwen3"

接着写第二个文件demo.ts，只干三件事：打开页面、下指令、取数据：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('https://www.ebay.com'); const agent = new PlaywrightAgent(page); await agent.aiAct('在搜索框输入 Headphones 并按回车'); const items = await agent.aiQuery('{title: string, price: number}[]，列出前 5 件商品'); console.log('搜索结果：', items);

运行一下：

npx tsx demo.ts

你应该看到两样东西：终端打印出商品标题和价格数组；同时输出Midscene - report file updated: /xxx/report-xxx.html。浏览器打开这个 HTML，能看到每一步的截图、AI 的规划过程和实际点击位置——这是 Midscene.js 自带的执行报告，后面排查问题全靠它。

不想写代码的话，Quick Start 里有 Chrome 扩展和 Playground 的免代码玩法；写代码的完整细节看 Playwright 接入文档。Web 跑通之后，我们把它搬到手机上。

真实任务：让手机 App 自己打开设置并验证结果

移动端是跨平台自动化脚本的硬骨头。以 Android 为例，目标很朴素：验证"我的设备"页面能正确显示设备信息。

操作：一句aiAct告诉它路径——"打开设置，进入我的设备页面"，它自己规划：先定位设置图标，点击，再进子页面，全程没有坐标
验证：aiAssert下断言"页面显示了设备名称和存储容量"，不通过时脚本直接失败，截图标红留档

await agent.aiAct('打开设置，进入"我的设备"页面'); await agent.aiAssert('页面显示了设备名称和存储容量');

手机上跑之前，模型配置填在 Playground 右上角的齿轮里，格式是KEY=VALUE每行一个，数据只存在你本地浏览器，不会上传：

任务能跑通，不代表环境没问题。下面三个是新手最容易撞上的墙。

连接或执行失败？先查这 3 个地方 🔧

模型报错 401 / 403→ 最可能是环境变量没导出到当前终端 → 在跑脚本的同一个终端里echo $MIDSCENE_MODEL_API_KEY，确认非空再执行
aiAct 反复重试、找不到元素→ 多半是页面没加载完，或指令与当前画面不符（比如在首页让它点"登录成功"页的按钮）→ 打开执行报告的截图时间线，看模型当时到底看到了什么
Android 连接超时、设备列表为空→ USB 调试没开，或手机上的授权弹窗没点"允许" → 终端跑adb devices，看到设备序列号且状态是authorized就对了

三个都排掉了还跑不通，再看报告里每步的报错详情，通常答案就在第一张截图里。