> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 基本概念

本文介绍 Midscene 的视觉路线、使用方式和关键 API，帮助你理解并使用 GUI Agent。想先动手体验，可以直接阅读[开始使用](/zh/get-started.md)。

## 基于视觉的自动化路线

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

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

视觉路线需要模型具备 UI 定位能力，支持的模型见[模型选择指南](/zh/model-selection.md)。数据提取和页面理解仍可按需附带 DOM 信息，详见 [API 参考](/zh/reference.md#extraction-location-assertion)。

## 选择适合你的使用方式 {#choose-your-path}

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

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

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

| 你想做什么                           | 从这里开始                                                                                                            |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| 先体验自然语言操作与断言                    | [开始使用](/zh/get-started.md)                                                                                       |
| 用 YAML 组织 Web、移动端或桌面端测试         | [创建测试项目](/zh/midscene-test/use.md)                                                                               |
| 在 JavaScript/TypeScript 工程中编写测试 | [接入 Playwright Test](/zh/integrate-with-playwright.md)、[Rstest](/zh/sdk/rstest.md) 或 [Vitest](/zh/sdk/vitest.md) |
| 运行独立自动化流程                       | [独立脚本](/zh/sdk/standalone.md)                                                                                    |
| 让 AI 编程助手操作应用                   | [Midscene Skills](/zh/skills.md)                                                                                 |

## 关键 API {#javascript-orchestration}

### 规划并交互

**`aiAct`**

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

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

典型用法：

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

### 即时交互

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

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

**`aiTap`**

[`aiTap`](/zh/reference.md#agentaitap) 用于定位并点击元素。

典型用法：

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

**`aiInput`**

[`aiInput`](/zh/reference.md#agentaiinput) 用于定位输入框并输入指定内容。它默认使用 `replace` 模式：先清空输入框中的现有内容，再输入新内容。

典型用法：

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

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

即时交互 API 还包括 `aiHover`、`aiClearInput`、`aiKeyboardPress`、`aiScroll`、`aiPinch`、`aiLongPress`、`aiDoubleClick` 和 `aiRightClick`。各 API 支持的平台不同，详见 API 参考中的[规划与交互](/zh/reference.md#planning-interaction)。

### 界面理解（Insight）

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

**`aiAssert`**

[`aiAssert`](/zh/reference.md#agentaiassert) 用于检查自然语言描述的条件。条件成立时，该方法正常结束；条件不成立时，该方法会抛出错误，并在错误信息中说明模型返回的原因。

典型用法：

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

**`aiQuery`**

[`aiQuery`](/zh/reference.md#agentaiquery) 用于从界面中提取结构化数据。请在提示词中描述所需数据，以及数据的预期类型或结构。

典型用法：

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

**`aiBoolean`**

[`aiBoolean`](/zh/reference.md#agentaiboolean) 用于询问与界面有关的问题，并返回布尔值。

典型用法：

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

其他便捷方法包括：返回数字的 [`aiNumber`](/zh/reference.md#agentainumber)，以及返回字符串的 [`aiString`](/zh/reference.md#agentaistring) 和 [`aiAsk`](/zh/reference.md#agentaiask)。

### 按需增强规划与定位

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

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

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

## 下一步

- [模型选择指南](/zh/model-selection.md)：了解何时使用默认模型，以及何时组合多个模型。
- [开始使用](/zh/get-started.md)：配置平台与模型，完成第一次运行。
- [创建测试项目](/zh/midscene-test/use.md)：编写和运行 YAML 测试。
- [API 参考](/zh/reference.md)：查询完整参数和平台支持情况。