API 接口#

与 Puppeteer 集成#

初始化方法：

import { PuppeteerAgent } from '@midscene/web/puppeteer';

const mid = new PuppeteerAgent(puppeteerPageInstance);

你可以在快速开始 中找到完整的集成样例。

与 Playwright 集成#

你可以在快速开始 中找到完整的集成样例。

API#

在以下文档中，你可能会看到带有 mid. 前缀的函数调用。如果你在 Playwright 中使用了解构赋值（object destructuring），如 async ({ ai, aiQuery }) => { /* ... */}，你可以不带这个前缀进行调用。这只是语法的区别。

.aiAction(steps: string) 或 .ai(steps: string) - 控制界面#

你可以使用 .aiAction 来执行一系列操作。它接受一个参数 steps: string 用于描述这些操作。在这个参数中，你应该清楚地描述每一个步骤，然后 Midscene 会自动为你分析并执行。

.ai 是 .aiAction 的简写。

以下是一些优质示例：

await mid.aiAction('在任务框中输入 "Learn JS today"，然后按回车键创建任务');
await mid.aiAction('将鼠标移动到任务列表中的第二项，然后点击第二个任务右侧的删除按钮');

// 使用 `.ai` 简写
await mid.ai('点击任务列表下方的 "completed" 状态按钮');

务必使用清晰、详细的步骤描述。使用非常简略的指令（如 “发一条微博” ）会导致非常不稳定的执行结果或运行失败。

在底层，Midscene 会将页面上下文和截图发送给 LLM，以详细规划步骤。随后，Midscene 会逐步执行这些步骤。如果 Midscene 认为无法执行，将抛出一个错误。

你的任务会被拆解成下述内置方法，你可以在可视化工具中看到它们：

1. 定位（Locator）：使用自然语言描述找到目标元素
2. 操作（Action）：点击、滚动、键盘输入、悬停（hover）
3. 其他：等待（sleep）

目前，Midscene 无法规划包含条件和循环的步骤。

关联文档:

• FAQ: Midscene 能否根据一句话指令实现智能操作？比如执行 "发一条微博"'
• 编写提示词的技巧

.aiQuery(dataShape: any) - 从页面提取数据#

这个方法可以从 UI 提取自定义数据。它不仅能返回页面上直接书写的数据，还能基于“理解”返回数据（前提是多模态 AI 能够推理）。返回值可以是任何合法的基本类型，比如字符串、数字、JSON、数组等。你只需在 dataDemand 中描述它，Midscene 就会给你满足格式的返回。

例如，从页面解析详细信息：

const dataA = await mid.aiQuery({
  time: '左上角展示的日期和时间，string',
  userInfo: '用户信息，{name: string}',
  tableFields: '表格的字段名，string[]',
  tableDataRecord: '表格中的数据记录，{id: string, [fieldName]: string}[]',
});

你也可以用纯字符串描述预期的返回值格式：

// dataB 将是一个字符串数组
const dataB = await mid.aiQuery('string[]，列表中的任务名称');

// dataC 将是一个包含对象的数组
const dataC = await mid.aiQuery('{name: string, age: string}[], 表格中的数据记录');

.aiAssert(assertion: string, errorMsg?: string) - 进行断言#

.aiAssert 的功能类似于一般的断言（assert）方法，但可以用自然语言编写条件参数 assertion。Midscene 会调用 AI 来判断条件是否为真。若条件不满足，SDK 会抛出一个错误并在 errorMsg 后附上 AI 生成的错误原因。

await mid.aiAssert('"Sauce Labs Onesie" 的价格是 7.99');

const items = await mid.aiQuery(
  '"{name: string, price: number}[], 返回商品名称和价格列表)',
);
const onesieItem = items.find(item => item.name === 'Sauce Labs Onesie');
expect(onesieItem).toBeTruthy();
expect(onesieItem.price).toBe(7.99);

.aiWaitFor(assertion: string, {timeoutMs?: number, checkIntervalMs?: number }) - 等待断言执行成功#

.aiWaitFor 帮助你检查你的断言是否满足，或是是否发生了超时错误。考虑到 AI 服务的成本，检查间隔不会超过 checkIntervalMs 毫秒。默认配置将 timeoutMs 设为 15 秒，checkIntervalMs 设为 3 秒：也就是说，如果所有断言都失败，并且 AI 服务总是立即响应，则最多检查 5 次。

考虑到 AI 服务的时间消耗，.aiWaitFor 并不是一个特别高效的方法。使用一个普通的 sleep 可能是替代 waitFor 的另一种方式。

await mid.aiWaitFor("界面上至少有一个耳机的信息");

调试配置（可选）#

打印 AI 性能信息#

设置 MIDSCENE_DEBUG_AI_PROFILE 变量，你可以看到每次调用 AI 的时间和 token 数量。

export MIDSCENE_DEBUG_AI_PROFILE=1

使用 LangSmith#

LangSmith 是一个用于调试大语言模型的平台。想要集成 LangSmith，请按以下步骤操作：

# 设置环境变量

# 启用调试标志
export MIDSCENE_LANGSMITH_DEBUG=1 

# LangSmith 配置
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
export LANGCHAIN_API_KEY="your_key_here"
export LANGCHAIN_PROJECT="your_project_name_here"

启动 Midscene 后，你应该会看到类似如下的日志：

DEBUGGING MODE: langsmith wrapper enabled