5.2 Midscene 实战：自然语言定位与断言

5.2 Midscene 实战：自然语言定位与断言

本节摘要：本节把视觉流派落成一个可上手的库：Midscene（字节出品，web-infra-dev 组织开源，约 1.5 万 stars，2026-10-16 社区口径；MIT 许可），定位是视觉驱动的 UI 自动化与自然语言 E2E——把截图定位、动作执行、数据抽取、结果断言包成三件套 API：ai（一句话执行任意 UI 操作或规划）、aiQuery（自然语言抽取结构化数据）、aiAssert（自然语言断言）。先讲环境与三件套语义，然后在第 0.2 节的靶场页面上跑完整用例：填待办、抽取列表、断言结果，逐步解读模型看到的截图与定位框这类视觉中间产物。双语形态：JS 用例为主线（嵌入 Jest 或独立脚本均可），Python 用例给出对照（以官方文档为准）。AI 增强断言与传统断言的对照说明 aiAssert 买来什么、付出什么。Midscene 的中文文档质量在同类库里数一数二，延伸学习以官方中文文档为准。所有示例打在本地测试页上。

学习目标

• 说出三件套（ai、aiQuery、aiAssert）的语义边界与返回值形态。
• 在靶场上独立跑通一个完整的 Midscene 用例并解读其视觉中间产物。
• 写出 JS 与 Python 两种形态的自然语言用例。
• 对照传统断言说出 aiAssert 的增益与代价，知道何时两者并用。

一、它是什么：三件套语义

Midscene 的 API 面收敛在三个动词上（与第 1.1 节三原语的对应关系一目了然）：

形态上有两个工程特点：其一，它是库不是服务——嵌进你的测试代码（JS 的 Jest 系或独立脚本、Python 用例），与现有工程共存，而非另起一个平台；其二，定位以视觉为主（截图加多模态模型），配合bridging 的桥接机制消费页面结构——所以它落在视觉流派，但不是纯像素。环境准备与第 0.2 节一致（Node 与依赖安装），额外按官方文档安装 Midscene 的包并配置模型（视觉能力是硬要求，模型必须支持图像输入；密钥走环境变量）。

二、完整用例走查

任务：在靶场上添加待办「买牛奶」，抽取列表，断言结果。JS 主线版本：

// midscene_demo.mjs —— Midscene 三件套完整用例（写法示意，以官方文档为准）
import puppeteer from "puppeteer";
import { PuppeteerAgent } from "@midscene/web/puppeteer";

const browser = await puppeteer.launch({ headless: false });
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 800 });
await page.goto("http://127.0.0.1:8080/demo_todo.html");

const agent = new PuppeteerAgent(page);

// 执行：一句话完成填与点（对应 act）
await agent.ai("在「新待办」输入框填入 买牛奶，点击「添加」按钮");

// 抽取：自然语言取结构化数据（对应 extract）
const items = await agent.aiQuery("提取待办列表的全部条目文本", {
  type: "array",
  items: { type: "string" },
});
console.log("抽取结果:", JSON.stringify(items));

// 断言：自然语言验证状态（对应验证）
await agent.aiAssert("列表中包含一条内容为 买牛奶 的待办");

await browser.close();
​

用例里三个值得点破的细节：视口被显式固定（1280 乘 800）——第 5.1 节坐标换算的防坑第一招在 API 层的落实；指令书写沿用第 3.2 节三原则（引用可见文本「新待办」「添加」），好指令的纪律跨流派通用；aiAssert 的断语写的是用户可感知的状态（「列表中包含某待办」）而不是实现细节（「第三个 li 的 textContent 等于」）——这是自然语言断言与代码断言的本质分野，下文展开。

三、解读视觉中间产物

Midscene 每次视觉操作都产出可回放的中间材料：模型看到的截图（带定位框标注）、模型的推理与动作输出、断言的判定依据。一次执行后查看报告（官方提供可视化报告，入口以文档为准），典型画面（文字示意）：

# midscene_trace.txt —— 一次 ai 操作的中间产物示意（节选）
步骤 1: ai("在「新待办」输入框填入 买牛奶，点击「添加」按钮")
  截图: demo_todo.png（1280x800）
  定位: 输入框 → 框选区域 (412, 301, 868, 345)   ← 模型给出的边界框
        按钮「添加」→ 框选区域 (412, 355, 500, 395)
  执行: fill("买牛奶") → click(添加)
步骤 2: aiQuery("提取待办列表的全部条目文本")
  定位: 列表区域 → 框选 (412, 420, 868, 560)
  输出: ["买牛奶"]
​

把这份材料与第 4.2 节的快照 trace 对比着读，两个流派的气质差异一目了然：快照 trace 是文本清单加 ref（可 diff、可缓存、可固化），视觉 trace 是带框截图加坐标（可回放、直观、但每次都要重新看图）。第 5.1 节的成本结论在这里变得具体：Midscene 的每步都在付视觉的钱，也因此它的用例天然适合「页面语义欠账但视觉清晰」的场景，而不是把结构化能做的活抢过来干。

四、Python 形态与运行方式

Midscene 提供 Python 用例支持（包名与入口以官方文档为准），三件套语义与 JS 版对齐：

# midscene_demo.py —— Midscene Python 用例（写法示意，以官方中文文档为准）
from midscene import Agent

agent = Agent.from_playwright("http://127.0.0.1:8080/demo_todo.html")
agent.ai("在「新待办」输入框填入 回复邮件，点击「添加」按钮")
agent.ai_query("提取待办列表的全部条目文本")
agent.ai_assert("列表中包含一条内容为 回复邮件 的待办")
agent.release()
​

运行方式的选型口径：JS 侧可嵌入 Jest 等测试框架做成 E2E 用例（第 9 章的主线），也可如本书示例写成独立脚本；Python 侧适合把 UI 自动化并进已有的 Python 工程链（数据处理、运维脚本）。两侧的用例语义等价，选离你工程近的那侧。无论哪侧，中文文档都是第一手资料——Midscene 的中文文档在同类项目里属第一梯队，安装、模型配置、报告解读都有中文页面，延伸学习直接以官方中文文档为准。

一个双语并行的实操提示：同一靶场任务先在 JS 侧调通（报告与回放工具链更成熟，排障快），再翻译成 Python 版沉进工程链——指令文本与断言语义在两侧可以原样复用，因为它们本来就是自然语言，没有「翻译成本」。这个「先调试侧、后工程侧」的两步走，能把视觉用例的调试时间压到最低。

五、AI 增强断言：买来什么，付出什么

aiAssert 是三件套里最有争议也最有价值的一个，拿传统断言对照：

实践口径：结构性断言用代码，感知性断言用 aiAssert，关键流程两者并用——「列表包含买牛奶」用代码（它本来就是结构信息），「页面主体内容可见、无报错遮罩」用 aiAssert（传统断言写不清）。误判概率的存在意味着 aiAssert 的失败需要人工复核报告，不能直接当崩溃信号熔断生产流程——这条纪律在第 6 章验证与重试里会升级成完整的分级处理策略。

六、常见坑与排查

这张表的公共主题仍是纪律：视觉流派的自由度最大，对写法纪律的要求也最高——好在这个纪律并不新鲜，第 3.2 节的指令三原则与第 1.1 节的语义锚思想，在这里逐条适用。把「固定视口、语义断语、用户视角」三条当作用例模板的默认头部，多数坑在写用例时就被堵住。

本节要点回顾

• 三件套与三原语一一对应：ai 执行、aiQuery 抽取、aiAssert 断言（验证的原语化）。
• 工程三细节：固定视口、指令三原则跨流派通用、断言写用户感知而非实现细节。
• 视觉中间产物是带框截图加坐标：可回放但每次付视觉的钱，别抢结构化的活。
• 双语形态语义等价，选离工程近的；先调试侧后工程侧的两步走最省时；中文文档是第一手延伸资料。
• 五类常见坑（模型无视觉、视口漂移、断语模糊、页面未就绪、指令夹实现细节）多可在用例模板头部堵住。
• aiAssert 口径：结构性用代码、感知性用自然语言、关键流程并用；误判需人工复核。

Midscene 是「嵌进你测试代码的视觉库」，另一个问题是反过来：把浏览器自动化做成服务，用工作流描述任务。下一节对照 Skyvern——视觉与 DOM 混合的工作流自动化，顺带看清 AGPL 许可注记与浏览器基建的生态位。