Midscene实战手册用自然语言驱动UI自动化的完整路径【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene是一个基于视觉语言模型的UI自动化库不写选择器仅凭一张截图和一句自然语言就能驱动浏览器、Android、iOS和桌面应用。这份手册从一个npm安装开始带你跑通三个实战场景并给出一套上线前的检查项。 先跑起来——最短路径接入Midscene来我给你看个东西。装好依赖配好模型四件套环境变量MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_FAMILY建议放.env然后跑一个最小脚本npm i midscene/web playwright tsx --save-dev npx tsx demo.tsimport { 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); const items await agent.aiQuery({itemTitle: string, price: number}[]); console.log(items);跑通后你会看到两样东西终端里打印出商品标题和价格的结构化数组midscene_run/report/目录下多出一个报告 HTML浏览器打开后能逐步回看每一步的截图和 AI 实际执行的动作点。它是怎么看懂屏幕的整个链路就四步我按因果顺序说你输入一句自然语言比如agent.aiAct(点击登录按钮)。系统截一张当前屏幕的图不读 DOM不解析选择器。视觉语言模型看图完成两类工作把元素定位到像素坐标locate或把复杂指令拆成步骤计划plan。系统按坐标执行点击、输入返回执行结果或你要的结构化数据。有意思的是正因为全程只依赖截图Canvas 区域、原生 App、跨域 iframe 这些DOM 够不着的地方它一样能操作——人能看见的它就能点。代价也明确每步都要过一次模型推理所以下文会聊怎么把它变便宜。三个场景从登录流到批量巡检同一套aiAct、aiQuery、aiAssertAPI 覆盖全部平台下面三个场景是我觉得落地率最高的。RPA流程编排把每天重复的审批跑成一条YAMLIT 同事手里常有一类活系统里有一套固定的每日审批流页面简单但步骤多为它写一整套 Playwright 脚本太重。Midscene 的 YAML 脚本就是为这种活准备的。写一份 YAMLflow里每行一条指令单步操作用- ai: 点击同意按钮。每步之间用sleep或aiWaitFor等系统响应再执行下一步。结尾加aiAssert: 审批列表中所有条目状态为已通过然后midscene ./approve.yaml一条命令跑完。踩坑提示这类流程最常见的翻车点是等待时间给太短在页面还没渲染完时点了下一屏。教学演示自动录制同一场演示稳定回放一百次培训讲师的痛点很实在每年要讲一百遍同一个功能手工演示经常中途卡住页面版本一更新脚本全失效。先在 Chrome 扩展的 Playground 里用自然语言把指令试通——扩展和midscene/web共享同一套能力试通的指令可以直接抄进代码。把验证过的指令序列写进 YAML每节课跑一遍演示路径和第一次完全一致。用aiQuery把当前步骤的关键数据投到大屏当讲解素材比口述更稳。踩坑提示每节课开播前不重置演示环境清 cookies 或换新账号回放很容易被上一场的残留状态卡死。竞品数据定时采集每天早上一份结构化表格运营分析师每天早上要一份竞品页的商品标题、价格、库存状态。这种页面常常是单页应用选择器极不稳定传统方案维护成本很高。给aiQuery直接挂上 schemaagent.aiQuery({name: string, price: number}[])返回类型固定下游直接落库。把结果写入 CSV 或数据库丢进定时任务每天跑一次。抽取失败时先看报告里的截图确认是页面改版了还是网络没加载完再决定改指令还是加等待。踩坑提示不写 schema 时模型会自由发挥返回字段名同一天两个字段名不一样的情况真实发生过解析层会很痛苦。 上生产之前先检查这三项我上线前一般会看这三件事按出事的概率从高到低排。错误恢复重试策略加降级路径脚本层的重试自己兜底失败后先等页面回到稳定状态再试别在旧画面上反复点for (let attempt 1; attempt 3; attempt) { try { await agent.aiAct(click the submit button); break; } catch (err) { if (attempt 3) throw err; await agent.aiWaitFor(页面回到稳定状态, { timeoutMs: 5000 }); } }另外两层不用你操心模型请求本身有内置重试次数用MIDSCENE_MODEL_RETRY_COUNT调默认 1 次计划层面缓存的aiAct方案如果运行时失败会自动丢弃缓存并回退到 AI 重新规划这是它内置的降级路径。你要做的只是失败后把页面状态恢复到可重入的位置。成本控制先开缓存再按任务分级选模型缓存是成本大头的第一解。构造 Agent 时传cache: { id: my-job }aiAct的执行计划和 Web 端的元素 XPath 位置都会被缓存官方文档里的实测案例把同一任务从 51 秒压到 28 秒。要注意aiQuery、aiAssert这类查询类 API 从不缓存保证你拿到的永远是实时数据CI 里想命中缓存需要把midscene_run/cache目录提交进仓库。选模型按任务复杂度分级简单定位、识别用便宜快的模型复杂多步规划用能力强的模型。Midscene 支持按意图分别配置——MIDSCENE_INSIGHT_MODEL_*配识别模型MIDSCENE_PLANNING_MODEL_*配规划模型不必全局一个模型打天下。可观测性先分清是AI识别错了还是脚本逻辑错了失败时别急着改代码先打开报告 HTML两个排查手法基本能定位到责任方看失败那一步的截图和动作标记。标记落在目标元素上但下一步走偏是脚本逻辑问题——等待时间、步骤顺序标记根本没落在目标上才是 AI 识别错了这时改指令措辞或换模型。看报告里有没有cache提示。命中缓存却行为诡异时删掉缓存文件重跑一次能立刻确认是不是旧缓存在捣乱。 接进你现有的流水线四个集成点每个都是改哪里、加什么已有 Playwright 用例在playwright.config.ts的reporter里加一行[midscene/web/playwright-reporter]再加一个 fixture 文件扩展test实例之后用例里直接解构出aiTap、aiAssert等参数写法见 web-integration 里的 fixture 导出。非测试类自动化写 YAML用midscene/cli一条midscene ./your-script.yaml跑掉CLI 会打印进度并产出报告。CI 流水线把midscene_run/cache提交进仓库保命中报告 HTML 归档为 artifact容器里字体加载容易卡截图超时加环境变量PW_TEST_SCREENSHOT_NO_FONTS_READY1。调试入口装 Chrome 扩展指令先人工验证再进代码别拿生产脚本当试错工具。fixture 最小写法就五行import { test as base } from playwright/test; import { PlaywrightAiFixture } from midscene/web/playwright; export const test base.extend( PlaywrightAiFixture({ waitForNetworkIdleTimeout: 2000 }), );跑完之后每份报告长这样每个用例的截图、耗时、缓存命中都在时间轴上写在最后最实在的一个优势同一套aiAct/aiQueryAPI 能驱动浏览器、Android、iOS 和桌面Chrome 扩展里试通的指令可以原样搬进脚本而开缓存后固定流程的官方实测执行时间从 51 秒降到 28 秒。边界也要说清楚如果目标页面 DOM 结构稳定、断言要精确到像素、预算又很紧传统选择器方案依然更便宜更快纯视觉路线不是它的最优解。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene实战手册：用自然语言驱动UI自动化的完整路径
Midscene实战手册用自然语言驱动UI自动化的完整路径【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene是一个基于视觉语言模型的UI自动化库不写选择器仅凭一张截图和一句自然语言就能驱动浏览器、Android、iOS和桌面应用。这份手册从一个npm安装开始带你跑通三个实战场景并给出一套上线前的检查项。 先跑起来——最短路径接入Midscene来我给你看个东西。装好依赖配好模型四件套环境变量MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_FAMILY建议放.env然后跑一个最小脚本npm i midscene/web playwright tsx --save-dev npx tsx demo.tsimport { 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); const items await agent.aiQuery({itemTitle: string, price: number}[]); console.log(items);跑通后你会看到两样东西终端里打印出商品标题和价格的结构化数组midscene_run/report/目录下多出一个报告 HTML浏览器打开后能逐步回看每一步的截图和 AI 实际执行的动作点。它是怎么看懂屏幕的整个链路就四步我按因果顺序说你输入一句自然语言比如agent.aiAct(点击登录按钮)。系统截一张当前屏幕的图不读 DOM不解析选择器。视觉语言模型看图完成两类工作把元素定位到像素坐标locate或把复杂指令拆成步骤计划plan。系统按坐标执行点击、输入返回执行结果或你要的结构化数据。有意思的是正因为全程只依赖截图Canvas 区域、原生 App、跨域 iframe 这些DOM 够不着的地方它一样能操作——人能看见的它就能点。代价也明确每步都要过一次模型推理所以下文会聊怎么把它变便宜。三个场景从登录流到批量巡检同一套aiAct、aiQuery、aiAssertAPI 覆盖全部平台下面三个场景是我觉得落地率最高的。RPA流程编排把每天重复的审批跑成一条YAMLIT 同事手里常有一类活系统里有一套固定的每日审批流页面简单但步骤多为它写一整套 Playwright 脚本太重。Midscene 的 YAML 脚本就是为这种活准备的。写一份 YAMLflow里每行一条指令单步操作用- ai: 点击同意按钮。每步之间用sleep或aiWaitFor等系统响应再执行下一步。结尾加aiAssert: 审批列表中所有条目状态为已通过然后midscene ./approve.yaml一条命令跑完。踩坑提示这类流程最常见的翻车点是等待时间给太短在页面还没渲染完时点了下一屏。教学演示自动录制同一场演示稳定回放一百次培训讲师的痛点很实在每年要讲一百遍同一个功能手工演示经常中途卡住页面版本一更新脚本全失效。先在 Chrome 扩展的 Playground 里用自然语言把指令试通——扩展和midscene/web共享同一套能力试通的指令可以直接抄进代码。把验证过的指令序列写进 YAML每节课跑一遍演示路径和第一次完全一致。用aiQuery把当前步骤的关键数据投到大屏当讲解素材比口述更稳。踩坑提示每节课开播前不重置演示环境清 cookies 或换新账号回放很容易被上一场的残留状态卡死。竞品数据定时采集每天早上一份结构化表格运营分析师每天早上要一份竞品页的商品标题、价格、库存状态。这种页面常常是单页应用选择器极不稳定传统方案维护成本很高。给aiQuery直接挂上 schemaagent.aiQuery({name: string, price: number}[])返回类型固定下游直接落库。把结果写入 CSV 或数据库丢进定时任务每天跑一次。抽取失败时先看报告里的截图确认是页面改版了还是网络没加载完再决定改指令还是加等待。踩坑提示不写 schema 时模型会自由发挥返回字段名同一天两个字段名不一样的情况真实发生过解析层会很痛苦。 上生产之前先检查这三项我上线前一般会看这三件事按出事的概率从高到低排。错误恢复重试策略加降级路径脚本层的重试自己兜底失败后先等页面回到稳定状态再试别在旧画面上反复点for (let attempt 1; attempt 3; attempt) { try { await agent.aiAct(click the submit button); break; } catch (err) { if (attempt 3) throw err; await agent.aiWaitFor(页面回到稳定状态, { timeoutMs: 5000 }); } }另外两层不用你操心模型请求本身有内置重试次数用MIDSCENE_MODEL_RETRY_COUNT调默认 1 次计划层面缓存的aiAct方案如果运行时失败会自动丢弃缓存并回退到 AI 重新规划这是它内置的降级路径。你要做的只是失败后把页面状态恢复到可重入的位置。成本控制先开缓存再按任务分级选模型缓存是成本大头的第一解。构造 Agent 时传cache: { id: my-job }aiAct的执行计划和 Web 端的元素 XPath 位置都会被缓存官方文档里的实测案例把同一任务从 51 秒压到 28 秒。要注意aiQuery、aiAssert这类查询类 API 从不缓存保证你拿到的永远是实时数据CI 里想命中缓存需要把midscene_run/cache目录提交进仓库。选模型按任务复杂度分级简单定位、识别用便宜快的模型复杂多步规划用能力强的模型。Midscene 支持按意图分别配置——MIDSCENE_INSIGHT_MODEL_*配识别模型MIDSCENE_PLANNING_MODEL_*配规划模型不必全局一个模型打天下。可观测性先分清是AI识别错了还是脚本逻辑错了失败时别急着改代码先打开报告 HTML两个排查手法基本能定位到责任方看失败那一步的截图和动作标记。标记落在目标元素上但下一步走偏是脚本逻辑问题——等待时间、步骤顺序标记根本没落在目标上才是 AI 识别错了这时改指令措辞或换模型。看报告里有没有cache提示。命中缓存却行为诡异时删掉缓存文件重跑一次能立刻确认是不是旧缓存在捣乱。 接进你现有的流水线四个集成点每个都是改哪里、加什么已有 Playwright 用例在playwright.config.ts的reporter里加一行[midscene/web/playwright-reporter]再加一个 fixture 文件扩展test实例之后用例里直接解构出aiTap、aiAssert等参数写法见 web-integration 里的 fixture 导出。非测试类自动化写 YAML用midscene/cli一条midscene ./your-script.yaml跑掉CLI 会打印进度并产出报告。CI 流水线把midscene_run/cache提交进仓库保命中报告 HTML 归档为 artifact容器里字体加载容易卡截图超时加环境变量PW_TEST_SCREENSHOT_NO_FONTS_READY1。调试入口装 Chrome 扩展指令先人工验证再进代码别拿生产脚本当试错工具。fixture 最小写法就五行import { test as base } from playwright/test; import { PlaywrightAiFixture } from midscene/web/playwright; export const test base.extend( PlaywrightAiFixture({ waitForNetworkIdleTimeout: 2000 }), );跑完之后每份报告长这样每个用例的截图、耗时、缓存命中都在时间轴上写在最后最实在的一个优势同一套aiAct/aiQueryAPI 能驱动浏览器、Android、iOS 和桌面Chrome 扩展里试通的指令可以原样搬进脚本而开缓存后固定流程的官方实测执行时间从 51 秒降到 28 秒。边界也要说清楚如果目标页面 DOM 结构稳定、断言要精确到像素、预算又很紧传统选择器方案依然更便宜更快纯视觉路线不是它的最优解。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考