Midscene.js实战指南三步跑通自然语言UI自动化告别选择器维护【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene界面一改版选择器全挂上周写的 UI 自动化今天要重新修两天。Midscene.js视觉驱动的 GUI 自动化框架干的就是这件事你用自然语言描述操作它看截图定位元素并完成点击、输入、断言覆盖 Web 浏览器、Android、iOS、HarmonyOS 和桌面端。维护测试从追选择器变成改一句话。它是怎么做到的1. 只看截图找元素不碰 DOM传统方案的定位链条是写 CSS/XPath 选择器 → 页面结构一变就失效。而且没有语义标记的元素纯图标按钮、canvas 画布、原生 App 控件、跨域 iframe对 DOM 方案天然不可见。Midscene 的思路是截一张图问模型元素在哪——就像新员工不背工位编号而是看着屏幕找人。定位只依赖截图所以界面上人眼看得见的东西它都能点到。右侧是真实设备的实时投屏左侧可以看到任务被拆解成 Planning → Insight / Locate → Action / Tap 的逐步执行过程。2. 一句话变多步执行计划你只输入打开设置查看 Android 版本Midscene 内部的规划模型planning model会把它拆成找设置图标 → 点进 My device → 读出 MIUI 版本。这个先规划、再定位、后执行的循环由 Agent 自动驱动相关实现在 核心 Agent 模块。传统脚本里每一步都得你手写Midscene 里你只描述目标路径由模型规划界面变化时下一轮还能重新规划。3. 一套 API 打穿所有平台浏览器、手机、桌面用的是同一套核心aiAct执行操作、aiQuery提取结构化数据、aiAssert断言界面状态。相当于一个万能遥控器——换设备不改代码只换设备驱动。桥接模式Bridge Mode下你本机的脚本还能直接操控正在使用的桌面 Chrome连登录态都能复用实现见 桥接模式文档。最小可跑通体验最快的路径是 Chrome 扩展版 Playground不用建项目装好环境可选如果你打算深入用 SDK先克隆仓库装依赖git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene pnpm install准备模型配置。Midscene 需要带 UI 定位能力的多模态模型配置就是四个环境变量以千问为例MIDSCENE_MODEL_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 MIDSCENE_MODEL_API_KEY你的API密钥 MIDSCENE_MODEL_NAMEqwen3.7-plus MIDSCENE_MODEL_FAMILYqwen3在 Chrome Web Store 安装 Midscene 扩展把上面这段配置粘贴到侧边栏的设置面板保存打开任意网页输入点击搜索框输入手机回车。几秒钟后你会看到它自己定位、点击、输入。验证指令没问题后把它搬进代码只需一行await agent.aiAct(点击登录按钮)完整集成方式见 Playwright 集成文档 或 Puppeteer 集成文档。Android 设备场景则按 Android 平台指南 启动 Android Playground输入打开设置查看 Android 版本即可复现开头的例子。能力全景它能帮你做什么Web 表单与流程操作aiAct指令示例打开 GitHub 注册页填写所有必填字段并提交。适合登录、下单、数据录入这类多步流程。页面结构化取数aiQuery指令示例页面中的商品{name: string, price: number}[]。返回的是一段 JSON能直接喂给下游脚本替代脆弱的爬虫选择器。界面状态断言aiAssert指令示例页面顶部显示导航栏且购物车图标为红色。注意它断言的是用户实际看到的画面——颜色、高亮、布局都能查这在 DOM 断言里做不到。移动 App 跨端巡检指令示例在淘宝搜索手机记录第一个商品的价格。同一句话换到 Android、iOS 设备上的 Playground 也能跑实现分布在 Android 包、iOS 包 等平台模块。想批量跑可以把步骤写成 YAML 交给脚本执行器天然适合 CI见 YAML 脚本执行文档。从示例到生产配置项建议说明模型选择定位用 Doubao-Seed-2.1-turbo 或 qwen3.7-plus官方内测中前者定位最快且效果好预算敏感可用开源模型如 UI-TARS自建见 模型配置参考规划/洞察模型可单独配置用MIDSCENE_PLANNING_MODEL_*/MIDSCENE_INSIGHT_MODEL_*前缀分开设规划用强的、定位用快的缓存cache: { id: 登录流程 }相同指令相似页面直接复用上次规划官方案例执行耗时从 51 秒降到 28 秒生产环境用read-only策略保证缓存一致详见 缓存文档失败处理依赖自动回退缓存规划执行失败时自动回退到实时 AI 规划偶发弹窗、网络抖动不必自己写重试结果留存每步自动生成 HTML 报告含截图、执行步骤、耗时统计可直接归档进 CI 产物避坑清单模型老是点不准、反复瞎试→ 选了没有 UI 定位能力的模型或MIDSCENE_MODEL_FAMILY没设/设错 → 换 Doubao-Seed、Qwen3.x 等带定位能力的模型按文档补全 family 变量。扩展报错Cannot access a chrome-extension:// URL of different extension→ 其他扩展向页面注入了 iframe/script互相冲突 → 开发者工具里找到chrome-extension://开头的节点按扩展 ID 禁用冲突扩展刷新重试。本地 Ollama 模型报 403→ 浏览器扩展被同源策略挡了 → 启动 Ollama 前设OLLAMA_ORIGINS*。缓存结果过期执行到一半跑偏→ 页面改版后旧 XPath/规划仍被命中 → 缓存失效会自动回退 AI 重算频繁出问题时清掉./midscene_run/cache目录或临时cache: false调试。Android 设备连不上→ USB 调试没开或 adb 服务挂了 → 先adb devices确认设备在列不行就adb kill-server adb start-server换根数据线试试。跑一条用例要花一两分钟、API 费用心疼→ 每次都实时调模型 → 开缓存高频巡检场景把定位模型换成更快的一档。延伸与资源文档目录中文快速开始、各平台指南、API 参考都在这里核心 AI 模型调用实现想了解模型适配层怎么写的看这里任务调度核心规划-执行循环的底层逻辑报告应用每次执行的 HTML 报告长什么样桥接模式 与 数据隐私说明Midscene.js 让看屏幕的 AI接管了最脆弱的那环——定位。下一步装好扩展给你手上任意一个测试用例换一句自然语言跑一遍看报告。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考