企业官网建设流程全解析

Midscene.js 让 AI 仅凭一张截图操作屏幕：跨平台 UI 自动化新手指南

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

你受够了选择器每次重构就碎掉吗？Midscene.js 是一个 AI 驱动的 UI 自动化工具：它让多模态模型直接"看懂"截图，理解界面上的每个按钮和输入框，再替你完成点击、输入、断言。Web、Android、iOS、鸿蒙、桌面应用，一套 API 全部覆盖，你只需要用自然语言描述操作目标。

它到底是什么：给机器装了一双"会看屏幕的眼睛"

传统 UI 自动化要么靠 CSS 选择器，要么读 DOM 和无障碍树。问题在于：结构一变选择器就失效；纯图标按钮、<canvas>画布、原生 App、跨域 iframe，这些工具统统"看不见"。

Midscene 换了一条路：它只认截图。你给它一句"点击登录按钮"，视觉模型在屏幕上找到那个按钮的坐标，直接点下去。它不关心元素有没有语义化标注，人眼能看到的，它就能操作。

整个能力浓缩成三个 API：aiAct（规划并执行多步操作）、aiQuery（提取结构化数据）、aiAssert（按用户实际看到的画面做断言）。比"元素存在不存在"更进一步，它能验证颜色、高亮、布局这类视觉状态。

Playground：左侧输入指令，右侧实时看到操作结果

五分钟跑通：先装个浏览器插件，一行代码都不用写

别急着搭项目，Midscene 的 Web 端 Playground 就是一个 Chrome 插件，装好就能玩。

第一步，准备一个多模态模型。它会承担"看屏幕"的工作，所以选模型的关键标准是 UI 定位能力。以豆包为例，设置四个环境变量：

export MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" export MIDSCENE_MODEL_API_KEY="your-api-key" export MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628" export MIDSCENE_MODEL_FAMILY="doubao-seed"

Qwen3.x、GLM、Gemini、UI-TARS 等模型在官方文档的"支持的模型与配置"页都能直接复制对应配置，开源模型也可以自己部署。

第二步，从 Chrome 商店安装 Midscene 插件，把上面这组配置粘贴到插件设置里，保存。

第三步，打开任意网页，在侧边栏输入符合页面内容的指令，比如"点击登录按钮"或"提取页面中的商品 {name, price}[]"。跑通了！看到界面上真的被点下去的那一刻，你就明白这套东西的直觉有多强。

Bridge 模式：终端里的 SDK 可以接管你的桌面浏览器

玩熟之后想进代码？装核心包npm install @midscene/web，创建 Agent 后你会发现，插件里验证过的指令能原封不动搬进脚本：

await agent.aiAct('搜索耳机，把第一件商品加入购物车'); const products = await agent.aiQuery<{ name: string; price: number }[]>( '页面中的商品，{name: string, price: number}[]'); await agent.aiAssert('购物车数量显示为 1');

它是怎么工作的：一次"看—想—做"的循环

说白了，就是让 AI 扮演一个盯着屏幕的测试员。

1. 截图：当前屏幕就是唯一输入，DOM 不参与定位。
2. 看懂：多模态模型分析截图，判断"登录按钮"在哪个位置，并规划接下来要做几步。
3. 生成操作：输出点击、输入、滑动等动作序列，交给各平台适配器执行。
4. 执行并验证：动作完成后重新截图核对，确认目标达成或继续下一步，全程记录进可视化报告，可逐步回放。

这一整套"规划—定位—执行"的循环在核心包 packages/core/src/agent/ 中实现，Web、Android 等平台只是换掉了"手"（点按方式）和"眼"（截图来源），大脑共用同一套逻辑。这也是它跨平台的根本原因。

Android Playground 左侧完整展示了规划、定位、操作三步循环

三个真实场景：测试、提速、远程遥控

场景一：E2E 回归测试。背景：团队每周跑回归，UI 一改就批量红。做法：把 Midscene 挂进现有 Playwright 或 Vitest 用例，自然语言描述步骤，断言写"用户实际看到什么"。效果：标记或样式变化不再牵连用例，维护成本大幅下降，失败时还能打开回放报告逐步看 AI 当时"看到"了什么。

场景二：重复任务提速。背景：同一个脚本每天跑几十次，模型调用又慢又花钱。做法：给 Agent 配置缓存cache: { id: 'my-flow' }，规划结果和元素定位会被存到midscene_run/cache目录，命中即复用，失效自动回退重算。效果：官方文档中的示例执行耗时从 51 秒降到 28 秒，且查询类操作天然不缓存，不用担心拿到旧数据。

场景三：网页上远程操控手机。背景：想演示或调试 Android 应用，但不想搭设备农场。做法：手机通过 USB 连上 adb，启动 Android Playground，浏览器里就有实时画面，输入"打开设置查看当前安卓版本号"即可远程操作。效果：零代码完成真机操作，官方甚至用它订过圣诞节酒店——是的，真订成功了。

踩坑与调优：五个经验值

• aiAct 比即时操作慢：单步明确的点击、输入，直接用aiTap等即时 API；只有多步骤、带条件分支的任务才值得交给aiAct去规划。
• 定位不准别硬刚，换模型：选 UI 定位能力强的模型（Qwen3.x、UI-TARS、Doubao-Seed 这类），小元素容易点偏时给aiAct加deepLocate: true。
• 缓存记得给 id：cache: { id: 'xxx' }才能让多次运行命中同一条缓存；缓存存的是规划而非查询结果，数据提取永远走模型，放心用。
• 描述像"指给别人看"："右上角第一个蓝色按钮"比"提交按钮"更稳，尤其当元素长得差不多时，加位置线索能明显减少误点。
• 复杂任务失败先看报告：多步任务中途翻车，打开可视化回放定位到具体哪一步规划偏了，再考虑开启deepThink加强任务拆解。

生态与集成：往哪接都留了口

写在最后

当模型越来越会"看"，UI 自动化的门槛就从"会写选择器"变成了"会写人话"。打开官方文档跑一遍 Chrome 插件里的注册表单案例，你会发现比预想中快得多——剩下的，留给你的第一个真实用例。

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