#基本概念

本文介绍 Midscene 的视觉路线、使用方式和关键 API，帮助你理解并使用 GUI Agent。想先动手体验，可以直接阅读快速体验 GUI Agent。

#基于视觉的自动化路线

Midscene 根据截图理解界面、定位目标并执行操作，再观察结果。UI 定位和操作不依赖 DOM、Selector 或额外标注，主要有四个优势：

• 契合 E2E 测试的初衷：像用户一样操作软件，从用户视角验证完整流程。根据屏幕上的文字、图标和布局操作，检查实际呈现的结果，包括选中状态、错误提示和元素遮挡。
• 与界面技术栈无关：HTML、Canvas、移动端和桌面应用都以截图呈现。平台提供截图和操作能力后，即可使用同一套 Agent API，减少对应用内部结构的依赖。
• 与主流模型路线一致：Gemini Computer Use 和 UI-TARS 都采用截图驱动的交互方式。Midscene 通过模型适配，让用户在统一 API 下选择模型，并受益于模型能力的进步。
• 成本可承受：在 AppControlBench 评测中，豆包 Seed 2.1 Turbo 执行 60 项任务、通过 58 项，模型调用总费用约 $0.59。实际费用随模型、任务和缓存命中情况变化。

视觉路线需要模型具备 UI 定位能力，支持的模型见模型选择指南。数据提取和页面理解仍可按需附带 DOM 信息，详见 API 参考。

#选择适合你的使用方式

Midscene 提供了一个跨平台 GUI Agent，支持 Web、移动端和桌面应用。它能根据自然语言指令操作界面、检查结果和提取数据。用于测试时，你可以根据用例编写习惯和已有工程选择接入方式。

如果希望用 YAML 组织测试，可以使用 E2E 测试框架 Midscene Test。它支持 Web、移动端和桌面应用，你可以用 YAML 描述测试步骤和预期结果，用 TypeScript 扩展业务操作，并由框架统一管理数据准备、清理、重试和执行报告。

如果已有 JavaScript/TypeScript 测试工程，或倾向于用代码编写用例，可以通过 SDK 将 GUI Agent 接入 Playwright Test、Vitest 等测试框架，为用例增加视觉操作与断言能力。

#关键 API

#规划并交互

aiAct

aiAct 接收用自然语言描述的目标。它会观察界面，规划操作步骤，定位目标元素并执行操作，直至完成目标。提示词也可以包含断言条件。Midscene 会在执行过程中验证这些条件，并在断言失败时及时抛出错误。

aiAct 灵活且自主，适合处理多步骤、包含条件分支或执行路径不确定的任务。执行期间，aiAct 会基于最新的界面状态持续进行 AI 规划，因此它通常比即时交互消耗更多时间和 token。

典型用法：

await agent.aiAct(
  '搜索耳机，将第一件商品加入购物车，并确认购物车数量变为 1',
);

#即时交互

即时交互类 API 每次只执行一个指定操作：先定位 UI 元素，再对该元素执行固定动作。

这类 API 不会规划多个步骤。对于“如果出现弹窗，先关闭弹窗，然后点击结账按钮”这类需求，请使用 aiAct。即时交互 API 会将提示词视为目标元素的描述，而非工作流。

aiTap

aiTap 用于定位并点击元素。

典型用法：

await agent.aiTap('购物车中的结账按钮');

aiInput

aiInput 用于定位输入框并输入指定内容。它默认使用 replace 模式：先清空输入框中的现有内容，再输入新内容。

典型用法：

await agent.aiInput('邮箱地址输入框', {
  value: 'user@example.com',
});

其他输入模式包括 typeOnly 和 clear。typeOnly 会保留现有内容，clear 仅清空输入框。

即时交互 API 还包括 aiHover、aiClearInput、aiKeyboardPress、aiScroll、aiPinch、aiLongPress、aiDoubleClick 和 aiRightClick。各 API 支持的平台不同，详见 API 参考中的规划与交互。

#界面理解（Insight）

界面理解类 API 只观察界面并返回分析结果，不会操作界面。它们默认使用当前截图。在 Web 页面中，如果任务需要读取截图中不可见的 DOM 信息，可以传入 domIncluded。

aiAssert

aiAssert 用于检查自然语言描述的条件。条件成立时，该方法正常结束；条件不成立时，该方法会抛出错误，并在错误信息中说明模型返回的原因。

典型用法：

await agent.aiAssert('购物车中有一件商品，并且页面显示了小计金额');

aiQuery

aiQuery 用于从界面中提取结构化数据。请在提示词中描述所需数据，以及数据的预期类型或结构。

典型用法：

const items = await agent.aiQuery<
  Array<{ name: string; price: number }>
>('购物车中的商品，{name: string, price: number}[]');
// items 示例：[{ name: '无线耳机', price: 99.9 }]

aiBoolean

aiBoolean 用于询问与界面有关的问题，并返回布尔值。

典型用法：

const loginDialogVisible = await agent.aiBoolean('登录对话框是否可见');
// loginDialogVisible 示例：true

其他便捷方法包括：返回数字的 aiNumber，以及返回字符串的 aiString 和 aiAsk。

#按需增强规划与定位

• deepThink：增强规划。用于 aiAct，更注重任务拆解，并将规划和元素定位拆成不同的模型调用，适合复杂的多步骤任务。详见 deepThink 规划模式。
• deepLocate：增强定位。用于 aiAct、aiTap 等需要定位元素的 API，通过额外一次模型调用提高定位准确性，适合较小或难以区分的目标。详见深度定位。

两者默认关闭，可以独立开启，也可以在 aiAct 中组合使用。它们会增加模型调用开销，建议先使用默认配置，遇到规划或定位问题时再按需开启。

await agent.aiAct('完成结账表单，在下单前停止', { deepThink: true });
await agent.aiTap('右上角的购物车图标', { deepLocate: true });

#下一步

• 模型选择指南：了解何时使用默认模型，以及何时组合多个模型。
• 快速体验 GUI Agent：在 Playground 中执行操作并验证结果。
• 创建测试项目：编写和运行 YAML 测试。
• API 参考：查询完整参数和平台支持情况。