Midscene.js 使用指南5分钟跑通 AI 视觉自动化的最短路径【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个 GUI Agent 自动化框架用自然语言加多模态模型直接操作网页、手机和桌面界面替代写死选择器、一改就挂的 E2E 脚本。本文覆盖从安装 CLI 到跑通 YAML 脚本、JS SDK 交互与缓存优化的最短路径读完你就能独立写出一条带可回放报告的 AI 视觉自动化链路。 快速上手一条命令跑通第一条自动化链路为什么先装 CLIMidscene 的 YAML 运行器把驱动浏览器、配置模型、生成报告都封装进了一条命令是你验证模型连通性最快的方式。第一步全局安装命令行工具然后运行官方文档里的第一个示例脚本内容见 YAML 脚本运行器npm i -g midscene/cli # 安装命令行工具 midscene ./bing-search.yaml # 运行第一个脚本第二步在运行目录下创建.env配置模型。CLI 通过 dotenv 加载它四个变量缺一不可MIDSCENE_MODEL_BASE_URLhttps://替换为你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY替换为你的APIKey MIDSCENE_MODEL_NAME替换为你的模型名称 MIDSCENE_MODEL_FAMILYqwen3 # 与模型系列对应, 取值见模型配置文档注意运行环境终端里的 Node.js 需要20.19、22.12或24版本过低会被构建工具链拒绝。你应该看到什么终端逐步打印执行进度脚本结束后出现一行Midscene - report file updated: /xxx/xxx.html。用浏览器打开这个 HTML你能回放每一步的页面截图、元素高亮框和模型返回内容——这就是验证锚点。不想写脚本也可以先装 Chrome 扩展版 Playground 零代码试指令或跑 Android Playgroundnpx --yes midscene/android-playground体验真机操作。 场景拆解三个真实用例 用自然语言驱动社交 App 消息流业务目标验证社交应用首页信息流能正常加载、帖子大图可点开全程不写任何 XPath。核心能力YAML 的ai规划并交互和aiAssert自然语言断言驱动已连接 adb 的 Android 设备。下面的脚本让 Agent 自主打开应用、滑动、点开帖子并断言结果android: deviceId: R5CT123ABC # 用 adb devices 输出的设备号替换 tasks: - name: 浏览消息流 flow: - ai: 打开红书社交应用 - ai: 在首页信息流向下滑动两次 - ai: 点击第一条帖子的图片 - aiAssert: 图片已进入大图浏览模式结果验证aiAssert不成立会直接抛错脚本以失败退出成功时打开生成的 HTML 报告能看到两次滑动和点开的完整回放。 自动化填写 Web 注册表单业务目标把打开页面、填邮箱、填密码、点提交、确认成功固化成可重复执行的流程用于冒烟测试或批量操作。核心能力page 级 Agentpage:配置ai分步指令。表单控件的视觉特征由模型识别你只描述哪个框、填什么。page: url: https://example.com/register # 替换为你的表单地址 tasks: - name: 完成注册表单 flow: - ai: 在邮箱输入框填入 userexample.com - ai: 在密码输入框填入 Aa123456 并在确认框再次输入 - ai: 点击注册按钮 - aiAssert: 页面出现注册成功提示结果验证页面上出现成功提示且midscene命令退出码为 0报告中可以逐步核对每个输入框实际填入的内容。 从工具类 App 屏幕提取结构化数据业务目标把天气类 App 屏幕上的城市-气温抓成 JSON供后续上报或比对而不是靠人眼看。核心能力JS SDK 的aiAct打开应用aiQuery结构化提取aiAssert界面检查入口在 packages/android/。安装midscene/android后脚本最小形态如下import { AndroidAgent, AndroidDevice, getConnectedDevices } from midscene/android; const device new AndroidDevice((await getConnectedDevices())[0].udid); const agent new AndroidAgent(device); await device.connect(); await agent.aiAct(打开天气应用); const rows await agent.aiQuery( {city: string, temp: string}[], 今日各城市气温, ); console.log(rows); await agent.aiAssert(页面显示的是今天的气温);结果验证终端打印出rows数组字段与你在提示词里声明的结构一致aiAssert通过则说明屏幕内容真实对应今日。用npx tsx demo.ts运行即可。 它是怎么工作的从指令到点击的调用链整条链路只有五个角色。你的 YAML 脚本或 JS 代码由 CLI / Agent API 接收Agent 对当前界面截图并连同自然语言指令发给多模态模型模型返回下一步做什么 元素在哪里设备适配器adb、WebDriverAgent、Puppeteer把点击、输入落到真实界面上每个步骤都被记录成节点执行完生成 HTML 回放报告。想深挖时看这三处Agent 与任务规划在 packages/core/src/agent/模型接入与提示词在 packages/core/src/ai-model/报告生成在 packages/core/src/report.ts。⚡ 进阶技巧让脚本更快更稳重复任务跑得慢、模型调用贵→ 开启规划与定位缓存相同指令在相似页面上直接复用结果缓存落在./midscene_run/cacheagent: cache: id: daily-feed # 相同任务复用规划与定位缓存 tasks: - name: 浏览消息流 flow: - ai: 打开社交应用并进入首页小图标定位不准、容易点错邻居元素→ 给定位类 API 加deepLocate多一轮模型调用换准确度await agent.aiTap(右上角购物车图标, { deepLocate: true });多分支复杂任务偶发失败→ 用deepThink加强任务拆解代价是更多模型调用和延迟await agent.aiAct(完成结账流程, 在下单前停止, { deepThink: true });脚本需要参数化→ YAML 里用${变量}引用.env中的值改参数不用改脚本# 对应 .env 中: topic今日天气 - ai: 在输入框中输入 ${topic}❓ 常见问题FAQ终端报Unsupported Node.js version怎么办结论Node 版本太旧。运行node -v确认版本CLI 部分路径要求20.19、22.12或24升级 Node 后重新安装 CLI 或项目依赖。跑完之后结果在哪看结论自动生成 HTML 报告不需要额外命令。终端会打印Midscene - report file updated: /path/xxx.html用浏览器打开即可逐步回放截图、元素框和返回值。重复执行越来越贵怎么省结论启用缓存。创建 Agent 时传cache: { id: ... }JS或在 YAML 的agent.cache中配置命中缓存的步不再调模型注意aiQuery、aiAssert等查询类操作永不缓存。详见 缓存文档。缓存命中后步骤执行错了结论缓存过期会自动回退到 AI 重新规划一般不用干预。调试期可设cache: false强制实时分析需要彻底重置时删除./midscene_run/cache目录下对应的.cache.yaml。adb devices里找不到手机结论USB 调试未开或未授权。在开发者选项里开启 USB 调试有USB 调试安全设置也一并开启重插数据线手机端点允许再跑adb devices -l确认。MCP server 配置为什么失效了结论MCP 集成已下线最后支持版本是1.9.8。代码级自动化请改用 YAML 运行器、JS SDK 或官方文档提到的 Skills 方案迁移说明见 MCP 文档。 生态资源官方文档与示例入口上手路径快速开始、基本概念、支持的模型与配置脚本写法使用 YAML 格式的自动化脚本、YAML 脚本运行器示例代码YAML 示例项目 packages/test/example/、Android demo、Web demo核心模块packages/core/Agent、模型调用、报告、packages/cli/命令行与 YAML 执行器社区与贡献CONTRIBUTING.md、项目总览 README.mdMidscene.js 的核心价值是把选择器 固定 sleep换成一句自然语言并给你一份能回放的执行证据。 你现在就可以装好 CLI配四个环境变量用上面的bing-search.yaml跑通第一条链路。 之后按场景需要切换到 Android / iOS / 桌面平台的 Playground 或对应 SDK。本文基于仓库当前版本 1.12.5 编写具体命令、参数与模型支持列表以 apps/site/docs/zh/ 下的官方文档为准。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene.js 使用指南：5分钟跑通 AI 视觉自动化的最短路径
Midscene.js 使用指南5分钟跑通 AI 视觉自动化的最短路径【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个 GUI Agent 自动化框架用自然语言加多模态模型直接操作网页、手机和桌面界面替代写死选择器、一改就挂的 E2E 脚本。本文覆盖从安装 CLI 到跑通 YAML 脚本、JS SDK 交互与缓存优化的最短路径读完你就能独立写出一条带可回放报告的 AI 视觉自动化链路。 快速上手一条命令跑通第一条自动化链路为什么先装 CLIMidscene 的 YAML 运行器把驱动浏览器、配置模型、生成报告都封装进了一条命令是你验证模型连通性最快的方式。第一步全局安装命令行工具然后运行官方文档里的第一个示例脚本内容见 YAML 脚本运行器npm i -g midscene/cli # 安装命令行工具 midscene ./bing-search.yaml # 运行第一个脚本第二步在运行目录下创建.env配置模型。CLI 通过 dotenv 加载它四个变量缺一不可MIDSCENE_MODEL_BASE_URLhttps://替换为你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY替换为你的APIKey MIDSCENE_MODEL_NAME替换为你的模型名称 MIDSCENE_MODEL_FAMILYqwen3 # 与模型系列对应, 取值见模型配置文档注意运行环境终端里的 Node.js 需要20.19、22.12或24版本过低会被构建工具链拒绝。你应该看到什么终端逐步打印执行进度脚本结束后出现一行Midscene - report file updated: /xxx/xxx.html。用浏览器打开这个 HTML你能回放每一步的页面截图、元素高亮框和模型返回内容——这就是验证锚点。不想写脚本也可以先装 Chrome 扩展版 Playground 零代码试指令或跑 Android Playgroundnpx --yes midscene/android-playground体验真机操作。 场景拆解三个真实用例 用自然语言驱动社交 App 消息流业务目标验证社交应用首页信息流能正常加载、帖子大图可点开全程不写任何 XPath。核心能力YAML 的ai规划并交互和aiAssert自然语言断言驱动已连接 adb 的 Android 设备。下面的脚本让 Agent 自主打开应用、滑动、点开帖子并断言结果android: deviceId: R5CT123ABC # 用 adb devices 输出的设备号替换 tasks: - name: 浏览消息流 flow: - ai: 打开红书社交应用 - ai: 在首页信息流向下滑动两次 - ai: 点击第一条帖子的图片 - aiAssert: 图片已进入大图浏览模式结果验证aiAssert不成立会直接抛错脚本以失败退出成功时打开生成的 HTML 报告能看到两次滑动和点开的完整回放。 自动化填写 Web 注册表单业务目标把打开页面、填邮箱、填密码、点提交、确认成功固化成可重复执行的流程用于冒烟测试或批量操作。核心能力page 级 Agentpage:配置ai分步指令。表单控件的视觉特征由模型识别你只描述哪个框、填什么。page: url: https://example.com/register # 替换为你的表单地址 tasks: - name: 完成注册表单 flow: - ai: 在邮箱输入框填入 userexample.com - ai: 在密码输入框填入 Aa123456 并在确认框再次输入 - ai: 点击注册按钮 - aiAssert: 页面出现注册成功提示结果验证页面上出现成功提示且midscene命令退出码为 0报告中可以逐步核对每个输入框实际填入的内容。 从工具类 App 屏幕提取结构化数据业务目标把天气类 App 屏幕上的城市-气温抓成 JSON供后续上报或比对而不是靠人眼看。核心能力JS SDK 的aiAct打开应用aiQuery结构化提取aiAssert界面检查入口在 packages/android/。安装midscene/android后脚本最小形态如下import { AndroidAgent, AndroidDevice, getConnectedDevices } from midscene/android; const device new AndroidDevice((await getConnectedDevices())[0].udid); const agent new AndroidAgent(device); await device.connect(); await agent.aiAct(打开天气应用); const rows await agent.aiQuery( {city: string, temp: string}[], 今日各城市气温, ); console.log(rows); await agent.aiAssert(页面显示的是今天的气温);结果验证终端打印出rows数组字段与你在提示词里声明的结构一致aiAssert通过则说明屏幕内容真实对应今日。用npx tsx demo.ts运行即可。 它是怎么工作的从指令到点击的调用链整条链路只有五个角色。你的 YAML 脚本或 JS 代码由 CLI / Agent API 接收Agent 对当前界面截图并连同自然语言指令发给多模态模型模型返回下一步做什么 元素在哪里设备适配器adb、WebDriverAgent、Puppeteer把点击、输入落到真实界面上每个步骤都被记录成节点执行完生成 HTML 回放报告。想深挖时看这三处Agent 与任务规划在 packages/core/src/agent/模型接入与提示词在 packages/core/src/ai-model/报告生成在 packages/core/src/report.ts。⚡ 进阶技巧让脚本更快更稳重复任务跑得慢、模型调用贵→ 开启规划与定位缓存相同指令在相似页面上直接复用结果缓存落在./midscene_run/cacheagent: cache: id: daily-feed # 相同任务复用规划与定位缓存 tasks: - name: 浏览消息流 flow: - ai: 打开社交应用并进入首页小图标定位不准、容易点错邻居元素→ 给定位类 API 加deepLocate多一轮模型调用换准确度await agent.aiTap(右上角购物车图标, { deepLocate: true });多分支复杂任务偶发失败→ 用deepThink加强任务拆解代价是更多模型调用和延迟await agent.aiAct(完成结账流程, 在下单前停止, { deepThink: true });脚本需要参数化→ YAML 里用${变量}引用.env中的值改参数不用改脚本# 对应 .env 中: topic今日天气 - ai: 在输入框中输入 ${topic}❓ 常见问题FAQ终端报Unsupported Node.js version怎么办结论Node 版本太旧。运行node -v确认版本CLI 部分路径要求20.19、22.12或24升级 Node 后重新安装 CLI 或项目依赖。跑完之后结果在哪看结论自动生成 HTML 报告不需要额外命令。终端会打印Midscene - report file updated: /path/xxx.html用浏览器打开即可逐步回放截图、元素框和返回值。重复执行越来越贵怎么省结论启用缓存。创建 Agent 时传cache: { id: ... }JS或在 YAML 的agent.cache中配置命中缓存的步不再调模型注意aiQuery、aiAssert等查询类操作永不缓存。详见 缓存文档。缓存命中后步骤执行错了结论缓存过期会自动回退到 AI 重新规划一般不用干预。调试期可设cache: false强制实时分析需要彻底重置时删除./midscene_run/cache目录下对应的.cache.yaml。adb devices里找不到手机结论USB 调试未开或未授权。在开发者选项里开启 USB 调试有USB 调试安全设置也一并开启重插数据线手机端点允许再跑adb devices -l确认。MCP server 配置为什么失效了结论MCP 集成已下线最后支持版本是1.9.8。代码级自动化请改用 YAML 运行器、JS SDK 或官方文档提到的 Skills 方案迁移说明见 MCP 文档。 生态资源官方文档与示例入口上手路径快速开始、基本概念、支持的模型与配置脚本写法使用 YAML 格式的自动化脚本、YAML 脚本运行器示例代码YAML 示例项目 packages/test/example/、Android demo、Web demo核心模块packages/core/Agent、模型调用、报告、packages/cli/命令行与 YAML 执行器社区与贡献CONTRIBUTING.md、项目总览 README.mdMidscene.js 的核心价值是把选择器 固定 sleep换成一句自然语言并给你一份能回放的执行证据。 你现在就可以装好 CLI配四个环境变量用上面的bing-search.yaml跑通第一条链路。 之后按场景需要切换到 Android / iOS / 桌面平台的 Playground 或对应 SDK。本文基于仓库当前版本 1.12.5 编写具体命令、参数与模型支持列表以 apps/site/docs/zh/ 下的官方文档为准。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考