Midscene.js 快速入门指南：5 分钟跑通你的第一个 AI 自动化任务

Midscene.js 快速入门指南5 分钟跑通你的第一个 AI 自动化任务【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene如果你每天要手动重复点击网页、逐条核对页面内容Midscene.js 值得花 10 分钟了解。它是一个基于视觉理解的 GUI 智能体GUI Agent你用自然语言描述目标和预期结果它通过截图看懂界面、定位元素再执行点击、输入、滚动等操作并自带一套 E2E 测试工具链。适合想减少选择器维护、降低脚本成本的测试工程师和开发者也适合刚接触 AI 自动化的新手。一分钟搞懂Midscene.js 能做什么传统 UI 自动化依赖 CSS 选择器和 XPath。页面一改版脚本就批量报错。Midscene.js 的思路相反它把人能看见的界面当作唯一事实来源用纯视觉方式定位元素。你给它一张截图和一句指令多模态模型负责找出目标控件的位置它再模拟真实的点击和输入。这意味着canvas渲染的图表、只有图标的按钮、跨域 iframe 里的控件都不需要额外的 DOM 标注就能操作。它把常用操作分成三组 APIaiAct负责自主规划多步流程aiTap、aiInput等负责单次固定动作aiQuery、aiAssert负责读取数据和校验界面状态。同一套 API 覆盖 WebPlaywright、Puppeteer、Androidadb、iOS、HarmonyOS 和桌面应用。官方基准中AndroidWorld 任务通过率达 93.1%AppControlBench 60 个任务的模型调用总成本仅 0.59 美元。环境准备与最小示例5 分钟跑通 Web 自动化准备 Node.js 环境后安装依赖npm i -D midscene/web playwright tsx配置一个多模态模型以阿里云 Qwen 为例替换成你的 API Keyexport 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写一个最小脚本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(type Headphones in search box, hit Enter); await agent.aiWaitFor(there is at least one headphone item on page); const items await agent.aiQuery( {itemTitle: string, price: number}[], find items and their prices, ); console.log(items); await browser.close();运行npx tsx demo.ts终端会打印商品列表同时生成一份 HTML 执行报告里面包含每一步的截图、AI 决策过程和断言结果。核心能力一览自然语言自主执行aiAct描述目标即可它自己拆解步骤、定位元素、处理分支。适合登录注册、下单等流程较长的多步任务。视觉断言aiAssert用一句话描述界面上应该出现什么条件不成立时抛出带原因的报错。适合回归测试里校验布局、颜色、高亮态。结构化数据提取aiQuery指定返回类型和字段直接从屏幕读取数据。适合报表生成、竞品数据收集。跨平台统一 API同一套调用方式切换 Web、Android、iOS、HarmonyOS 和桌面端。适合一套代码覆盖多端的 E2E 项目。三个高频实战场景场景一登录流程回归测试问题登录页每季度改版一次基于选择器的脚本经常静默失败。步骤用aiAct完成输入账号密码并登录随后用aiAssert校验页面右上角出现用户头像。效果界面只要对用户可见、可用脚本就不受内部结构变化影响断言失败时HTML 报告直接给出截图和模型判定的原因排查时间明显缩短。场景二定时收集页面数据入库问题业务方需要每周从若干管理后台页面抓取指标手动截图记录效率低。步骤在脚本里循环访问目标页每次调用aiQuery并按约定的 JSON 结构返回字段写入数据库或 CSV。效果数据口径由提示词里声明的字段固定下来页面微调后多数情况下无需改代码配合下一节的缓存重复页面能少调模型。场景三Android 真机冒烟测试问题App 每次发版前要在真机上手动走一遍核心链路耗时且容易漏。步骤先确认真机已通过adb devices被识别然后安装midscene/android用AndroidAgent驱动设备完成打开应用、进入设置页、读取版本号这类步骤。也可以先跑 Playground 验证连通性npx --yes midscene/android-playground。效果真机上的操作与 Web 侧写法一致冒烟用例可以沉淀为可重复执行的脚本而不是停留在测试人员的脑子里。进阶话题为任务选对模型Midscene.js 支持 Qwen、Doubao-Seed、GLM、Gemini、UI-TARS 等多模态模型其中不少开源模型可以自托管。默认一个 Default 模型即可覆盖多数场景当规划、数据提取成为瓶颈时可以再叠加独立的 Planning 模型和 Insight 模型分工处理。选择依据见 模型支持列表与配置。用缓存降低重复任务成本对同一套指令反复执行的场景开启缓存后可以跳过重复的 AI 规划与定位调用官方文档中的示例把执行时间从 51 秒降到 28 秒。缓存文件存放在./midscene_run/cache目录查询类结果aiQuery、aiAssert等永远不缓存保证数据实时性。const agent new PlaywrightAgent(page, { cache: { id: login-regression }, });看懂执行报告每次运行都会输出一份交互式 HTML 报告逐步截图、元素定位框、AI 的决策说明、动作与断言结果都在其中。报告文件由运行结束时打印的路径给出直接丢给协作方就能复现失败现场不用再靠口述。问题排查手册现象同一元素时灵时不灵点击打偏。对策目标控件很小或和相邻元素很像时给aiTap传入{ deepLocate: true }启用多轮精确定位或在指令里写得更具体例如右上角的购物车图标而不是购物车。现象本地 Ollama 模型报 403。对策设置环境变量OLLAMA_ORIGINS*后重启允许扩展访问本地模型服务。现象Chrome 扩展报Cannot access a chrome-extension:// URL of different extension。对策这是与另一个 Chrome 扩展的冲突。在开发者工具里找到 URL 以chrome-extension://开头的 iframe 或 script记下扩展 ID到chrome://extensions/禁用它后刷新页面。学习资源与下一步Playwright 集成指南从直连 Agent 到嵌入 Playwright 测试用例的完整路径Android 平台指南设备连接、Playground 与 SDK 用法缓存机制说明缓存策略、失效与回退规则API 参考全部 Agent 方法的参数与返回值建议你先装 Chrome 扩展版 Playground不写代码地把常跑的几个指令试一遍跑通之后把其中最固定的一条改写成aiAssert断言作为你项目里的第一个自动化用例。选一个你每周都要手动做的检查动作今天就让它由脚本替你完成。报告里的每一步截图都会告诉你AI 到底替你做了什么。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考