#API 参考

本页汇总通用 Agent API，以及各平台专属的构造函数、选项、操作和辅助方法。

本页记录 API 契约。安装、端到端工作流和故障排查请参考对应指南。平台 Agent 默认继承共享 Agent API；平台章节只记录对应环境的构造方式、选项、能力差异和工具。

本页保留少量完整示例，帮助理解相关 API 如何组合使用。更完整的接入流程和最佳实践请参考各章节末尾的指南链接。

#共享 Agent API

#Agent 选项与配置

Midscene 针对每个不同环境都有对应的 Agent。每个 Agent 的构造函数都接受一组共享的配置项（设备、报告、缓存、AI 配置、钩子等），然后再叠加平台专属的配置，比如浏览器里的导航控制或 Android 的 ADB 配置。

你可以通过下面的链接查看各 Agent 的导入路径和平台专属参数：

• 在 Puppeteer 中，使用 PuppeteerAgent
• 在 Playwright 中，使用 PlaywrightAgent
• 在桥接模式（Bridge mode）中，使用 AgentOverChromeBridge
• 在 Android 中，使用 Android API 参考
• 在 iOS 中，使用 iOS API 参考
• 如果你要把 GUI Agent 集成到自己的界面，请参考 自定义界面 Agent

参数

这些 Agent 有一些相同的构造参数：

• generateReport: boolean: 如果为 true，则生成报告文件。默认值为 true。
• persistExecutionDump: boolean: 如果为 true，Midscene 还会在报告旁边额外写出每次执行对应的 JSON dump 文件。默认值为 false。这个选项要求 generateReport 保持为 true。
• reportFileName: string: 报告输出名称，默认值由 midscene 内部生成。它在不同 outputFormat 下含义不同：
  • single-html（默认）：按文件名处理。Midscene 会在 midscene_run/report/ 下写入 <reportFileName>.html（如果已带 .html 后缀则保持不变）。
  • html-and-external-assets：按目录名处理。Midscene 会在 midscene_run/report/<reportFileName>/ 下写入 index.html 与相关静态资源。
• autoPrintReportMsg: boolean: 如果为 true，则打印报告消息。默认值为 true。
• cache?: false | { id: string; strategy?: 'read-only' | 'read-write' | 'write-only'; cacheDir?: string }：
  • false：完全禁用缓存。
  • id：必填的缓存 ID。
  • strategy：可选缓存策略。默认值为 'read-write'。
  • cacheDir：可选缓存目录路径。配置后，缓存文件会写入该目录，而不是 <MIDSCENE_RUN_DIR>/cache。相对路径会基于当前工作目录解析，而不是基于 MIDSCENE_RUN_DIR。这样可以把缓存、日志和报告目录拆开。
• cacheId: string | undefined（已废弃）：仅用于向后兼容。推荐使用 cache.id。
• aiContexts: { default?: string; [apiName]?: string }：Agent 级 AI 补充信息，可包含业务事实、判断或操作规则、约束以及输出要求。如果配置了 default，它会作为所有 AI API 共享的缺省回退值，仅当本次调用和对应 API 都没有自己的 context 时使用。解析规则为 options.context ?? aiContexts[apiName] ?? aiContexts.default，只使用优先级最高的已定义值，不会自动合并。空字符串会显式清空低优先级的用户 context。默认值为空。
• aiActContext: string（已废弃）：aiContexts.aiAct 的兼容配置。两者同时存在时以 aiContexts.aiAct 为准；没有 aiContexts.aiAct 时，它与 aiContexts.aiAct 的作用相同。新代码请使用 aiContexts.aiAct；更早的名称 aiActionContext 也已废弃，仅为兼容而保留。
• modelConfig: Record<string, string | number>：当前 Agent 的模型配置。传入该参数后，当前 Agent 不再读取系统环境变量中的模型配置。详细用法见下文。
• replanningCycleLimit: number: aiAct 的最大重规划次数。标准模型默认 20，UI-TARS 模型默认 40，AutoGLM 模型默认 100。推荐通过 Agent 入参设置；MIDSCENE_REPLANNING_CYCLE_LIMIT 环境变量仅作兼容读取。
• waitForActionReady: WaitForActionReadyOptions：自定义每个动作后的就绪判断。
• waitAfterAction: number：每次动作后的固定延时，默认为 300 毫秒，见默认等待策略。
• useDeviceTime: boolean：是否使用目标设备的本地时间记录任务时间。目标接口必须实现 getDeviceLocalTimeString。如果未实现，Midscene 会输出警告并改用运行环境的系统时间。默认值为 false。
• onTaskStartTip: (tip: string) => void | Promise<void>：可选回调，在每个子任务执行开始前收到一条可读的任务描述提示。默认值为 undefined。
• createOpenAIClient: (openai, options) => Promise<OpenAI | undefined>：可选的 OpenAI 客户端包装函数，可用于接入可观测性工具或自定义中间件。详细示例见下文。
• onLLMUsage: (usage: AIUsageInfo) => void：可选回调。每次大模型调用的用量信息就绪后，Midscene 会调用一次该函数，可用于实时统计用量和成本。
• outputFormat: 'single-html' | 'html-and-external-assets': 控制报告的生成格式。'single-html'（默认）将所有截图作为 base64 内嵌到单个 HTML 文件中，并把 reportFileName 作为 HTML 文件名。'html-and-external-assets' 将截图保存为独立的 PNG 文件到子目录，并把 reportFileName 作为该目录名，适用于报告文件过大的场景。注意：使用 'html-and-external-assets' 时，报告必须通过 HTTP 服务器或 CDN 地址访问，无法直接使用 file:// 协议打开。这是因为浏览器的 CORS（跨源资源共享）限制会阻止从 file 协议加载相对路径的本地图片。如需在本地测试，可在报告目录下启动简易的 HTTP 服务器。进入报告目录后运行以下命令之一：
  • 使用 Node.js：npx serve
  • 使用 Python：python -m http.server 或 python3 -m http.server 然后通过 http://localhost:3000（或终端显示的端口）访问报告。
• screenshotShrinkFactor: number: 控制截图的缩放比例，以减少发送给 AI 模型的图像大小，从而减少 token 消耗。默认值为 1（不缩放）。如果将其设置为 2，则截图的宽高将缩小为原来的一半，面积缩小为原来的四分之一。你可以根据实际情况调整这个值，以在图像清晰度和 token 消耗之间找到最佳平衡点。
  • 对于移动端设备，将 screenshotShrinkFactor 设置为 2 可以在保持清晰度的同时减少 token 的消耗，但不建议设置的值超过 3，否则可能会导致图像过于模糊，影响 AI 模型的理解。
  • 对于 Web 页面，如果页面内容比较复杂或包含大量细节，不建议设置过高的 screenshotShrinkFactor，以避免截图过于模糊。通常也可以通过 Puppeteer 或 Playwright 的 deviceScaleFactor 在更上游控制截图尺寸。

设备 CLI 可以按单次调用传入可序列化的 Agent 行为参数。waitForActionReady.createWaiter 等包含函数的配置需要通过 JavaScript/TypeScript SDK 传入。把 API 的 camelCase 参数名转换成不带平台前缀的 kebab-case flag，例如 waitAfterAction -> --wait-after-action。各平台 CLI 入口请参考 Skills。

每个动作后的就绪判断

配置 waitForActionReady，自定义何时可以进行下一步。它作用于每个原子动作（如 Input、Tap），包括 aiAct 子步骤和缓存回放；首次页面加载和只读查询不会触发。

• createWaiter: (context: ActionReadyContext) => ActionReadyPlan | Promise<ActionReadyPlan>：在每个动作前注册监听。context 包含 action: { id, name, param } 和 signal；每次执行都有新 ID，参数已完成解析和定位。
• timeoutMs?: number：分别限制 createWaiter、wait 和 dispose 的耗时，默认为 10000 毫秒，取值为 1 到 2147483647 之间的整数；不改变驱动执行动作的超时。

下面的 appMonitor 是用户自己的业务监控适配器：确认同步完成的输入可以跳过等待，登录则观察本次请求及渲染完成，其他动作沿用默认策略。

import { PlaywrightAgent } from '@midscene/web/playwright';

const agent = new PlaywrightAgent(page, {
  waitForActionReady: {
    timeoutMs: 10_000,
    createWaiter: ({ action, signal }) => {
      if (appMonitor.canSkipWaiting(action)) return 'skip';

      const observation = appMonitor.observe(action, { signal });
      if (!observation) return 'default';

      return {
        wait: () => observation.waitUntilReady(),
        dispose: () => observation.dispose(),
      };
    },
  },
});

await agent.aiAct('输入账号密码登录');

• createWaiter 负责注册监听，wait 负责等待动作结果；不要在工厂里等待尚未执行的动作触发事件。就绪信号应对应本次动作，避免旧状态提前放行。
• 'skip' 和自定义 waiter 替代通用动作延时及平台动作后检查。键盘准备、手势时长等驱动必需时序和生命周期回调仍然执行。未配置时行为不变。
• 失败或超时会终止流程，不会自动重放动作或回退到规划；下一次显式调用会创建新 waiter。动作失败时也会清理；取消、超时或 agent.destroy() 会中止 signal。
• 回调中请使用底层 page/device API。回调运行期间，调用同一 Agent 的 UI 方法会明确报错，并发调用也一样。仅凭当前没有网络请求，不能保证 UI 已就绪。

所有平台的 Agent 均支持此 SDK 配置。puppeteerAgentForTarget 在第二个参数中接收它，并保留初始网络空闲等待。

默认等待策略（高级配置）

未配置自定义 waiter 或返回 'default' 时，以下参数生效：

两项 Web 超时参数均可设为 0 跳过检查；检查超时会记录警告并继续执行。

自定义模型

modelConfig: Record<string, string | number> 可选。它允许你通过代码配置模型，而不是通过环境变量。

如果在 Agent 初始化时提供了 modelConfig，系统环境变量中的模型配置将全部被忽略，仅使用该对象中的值。 这里可配置的 key / value 与 模型配置 文档中说明的内容完全一致。Default、Planning 和 Insight 模型的职责请参考模型策略。

自定义 OpenAI 客户端

createOpenAIClient: (openai, options) => Promise<OpenAI | undefined> 可选。它允许你包装 OpenAI 客户端实例，用于集成可观测性工具（如 LangSmith、Langfuse）或应用自定义中间件。

参数说明：

• openai: OpenAI - Midscene 创建的基础 OpenAI 客户端实例，已包含所有必要配置（API 密钥、基础 URL、代理等）
• options: Record<string, unknown> - OpenAI 初始化选项，包括：
  • baseURL?: string - API 接入地址
  • apiKey?: string - API 密钥
  • dangerouslyAllowBrowser: boolean - 在 Midscene 中始终为 true
  • 其他 OpenAI 配置选项

返回值：

• 返回包装后的 OpenAI 客户端实例，或返回 undefined 表示使用原始实例

#规划与交互

这些是 Midscene 中各类 Agent 的主要 API。

agent.ai() 和 agent.aiAct() 会根据自然语言自动规划并执行多个步骤。agent.aiTap()、agent.aiInput() 等即时操作 API 直接执行指定动作，AI 模型只负责定位等底层任务。

#aiAct() 或 ai()

这个方法允许你通过自然语言描述 UI 操作目标和断言条件。执行期间，Midscene 会基于最新的界面状态持续进行 AI 规划和操作，直至完成目标。如果提示词中的断言失败，aiAct 会及时抛出错误。

• 类型

function aiAct(
  prompt: string | object,
  options?: {
    cacheable?: boolean;
    deepThink?: 'unset' | true | false;
    deepLocate?: boolean;
    fileChooserAccept?: string | string[];
    fileChooserAllowedDir?: string;
    abortSignal?: AbortSignal;
    context?: string;
  },
): Promise<string | undefined>;
function ai(prompt: string, options?: Object): Promise<string | undefined>; // 简写形式

• 参数：

  • prompt: string | object - 用自然语言描述的操作目标和断言条件，或使用图片作为提示词。断言条件不是必填项。
  • options?: object - 可选，一个配置对象，包含：
    • cacheable?: boolean - 当启用 缓存功能 时，是否允许缓存当前 API 调用结果。默认值为 true
    • deepThink?: 'unset' | true | false - 控制 Midscene 在 aiAct 执行规划时的具体实现。详见 deepThink 规划模式。
    • deepLocate?: boolean - 是否开启深度定位。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • fileChooserAccept?: string | string[] - 当文件选择器弹出时，指定对应的文件路径。可以是单个文件路径或路径数组。仅在 web 页面（Playwright、Puppeteer 或 Chrome extension Bridge mode）中可用。该选项不受 fileChooserAllowedDir 限制。
      • 注意：如果文件输入框不支持多文件（没有 multiple 属性），但是传入了多个文件，会抛出错误。
      • 注意：如果点击触发了文件选择器但没有传入 fileChooserAccept 参数，文件选择器会被忽略，页面可以继续正常操作。
      • 注意：Chrome extension Bridge mode 上传本地文件时，需要在 chrome://extensions > Midscene > “Details” 中开启插件的 “Allow access to file URLs” 权限。开启后请从目标 http(s):// 页面重新连接桥接模式。
      • 注意：Chrome extension Bridge mode 不支持目录上传输入框（webkitdirectory / directory）。如需上传目录，请使用 Playwright。
    • fileChooserAllowedDir?: string：显式授权当前 aiAct 通过提示词上传文件时可访问的目录。未配置时，模型规划的文件上传会被拒绝。配置后，提示词中的相对路径会基于此目录解析，并校验是否位于此目录下；绝对路径则直接校验是否位于此目录下。位于此目录下的 symlink 也允许上传。建议将其设置为测试用例的 fixtures 目录，以避免 AI 幻觉或页面提示词攻击导致 aiAct 上传敏感文件。
    • abortSignal?: AbortSignal - 可选的 AbortSignal，用于中止 aiAct 的执行。当信号被触发时，Midscene 会停止当前的规划循环并抛出错误。适用于实现超时控制或用户主动取消操作的场景。

• 返回值：

  • 返回执行完成后的规划输出文本；如果规划没有产生输出，则返回 undefined。执行失败时会抛出错误。

• 示例：

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

// 使用 .ai 简写形式
await agent.ai(
  '点击页面顶部的登录按钮，然后在用户名输入框中输入 "test@example.com"',
);

// 使用 abortSignal 设置超时
const controller = new AbortController();
setTimeout(() => controller.abort('timeout'), 30000); // 30 秒超时
await agent.aiAct('填写表单并提交', {
  abortSignal: controller.signal,
});

// 对于复杂任务，可以启用 deepThink 参数
await agent.aiAct('完成 github 账号注册的表单填写。地区必须选择「加拿大」。确保表单上没有遗漏的字段，确保所有的表单项能够通过校验。 只需要填写表单项即可，不需要发起真实的账号注册。 最终请返回表单上实际填写的字段内容', { deepThink: true });

#deepThink 规划模式

deepThink 控制 aiAct 的规划实现：

• 默认情况下，aiAct 会在同一次规划请求中完成下一步规划和目标元素定位。
• 设置为 true 后，aiAct 会更注重任务拆解，并将任务规划和元素定位分为不同的模型调用。复杂任务可能因此更加稳定，但模型调用次数和延迟也会增加。

deepThink 支持 'unset' | true | false。'unset' 是兼容旧写法的取值，与 false 的行为相同。

deepThink 不控制模型原生思考。相关环境变量请参考模型原生思考。

#在 aiAct 提示词中上传文件

如需让 aiAct 上传提示词中提到的文件，请为该次调用显式传入 fileChooserAllowedDir。建议将其设置为测试用例的 fixtures 目录。Midscene 会在打开文件选择器的操作之前规划文件选择器配置；相对路径和绝对路径都会先解析，再校验解析结果是否仍在所选目录内。

const agent = new PlaywrightAgent(page);

await agent.aiAct(
  '先点击“上传头像”按钮并上传 avatar.png；然后点击“上传封面”按钮并上传 cover.png。上传完成后，请确认页面头像显示一只猫、封面显示一片海滩。',
  { fileChooserAllowedDir: './fixtures' },
);

如果一次 aiAct 需要上传多个文件，请在提示词中把每个相对路径与对应的上传操作明确写出。后出现的路径会覆盖此前配置的文件选择器路径。不要将提示词中的文件路径与 options.fileChooserAccept 混用：模型在规划过程中生成的后续文件选择器配置可能覆盖该 option 的值。

此能力仅适用于 web 页面（Playwright、Puppeteer 和 Chrome extension Bridge mode）。当 fixture 不在当前工作目录下，或需要让同一提示词在本地和 CI 环境中复用时，请配置 fileChooserAllowedDir。

在 Chrome extension Bridge mode 中上传本地文件时，需要在 chrome://extensions > Midscene > “Details” 中开启插件的 “Allow access to file URLs” 权限。开启后请切回目标 http(s):// 页面，再重新连接桥接模式。

#aiTap()

点击某个元素

• 类型

function aiTap(locate: string | object, options?: object): Promise<void>;

• 参数：

  • locate: string | object - 用自然语言描述的元素定位，或使用图片作为提示词。
  • options?: object - 可选，一个配置对象，包含：
    • deepLocate?: boolean - 是否开启深度定位。该参数原来叫 deepThink，现已更名为 deepLocate。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
    • cacheable?: boolean - 当启用 缓存功能 时，是否允许缓存当前 API 调用结果。默认值为 true
    • fileChooserAccept?: string | string[] - 当文件选择器弹出时，指定对应的文件路径。可以是单个文件路径或路径数组。仅在 web 页面（Playwright、Puppeteer 或 Chrome extension Bridge mode）中可用。
      • 注意：如果文件输入框不支持多文件（没有 multiple 属性），但是传入了多个文件，会抛出错误。
      • 注意：如果点击触发了文件选择器但没有传入 fileChooserAccept 参数，文件选择器会被忽略，页面可以继续正常操作。
      • 注意：Chrome extension Bridge mode 不支持目录上传输入框（webkitdirectory / directory）。如需上传目录，请使用 Playwright。

• 返回值：

  • Promise<void>

• 示例：

await agent.aiTap('页面顶部的登录按钮');

// 使用 deepLocate 功能精确定位元素
await agent.aiTap('页面顶部的登录按钮', { deepLocate: true });

// 文件上传：点击上传按钮并选择文件
await agent.aiTap('选择文件按钮', { fileChooserAccept: ['./document.pdf'] });
await agent.aiTap('上传图片', { fileChooserAccept: ['./image1.jpg', './image2.png'] });

#aiHover()

在 Web 页面和桌面端（@midscene/computer）中可用，在移动端（Android、iOS 或 HarmonyOS）下不可用。

鼠标悬停某个元素上。

• 类型

function aiHover(locate: string | object, options?: object): Promise<void>;

• 参数：

  • locate: string | object - 用自然语言描述的元素定位，或使用图片作为提示词。
  • options?: object - 可选，一个配置对象，包含：
    • deepLocate?: boolean - 是否开启深度定位。该参数原来叫 deepThink，现已更名为 deepLocate。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
    • cacheable?: boolean - 当启用 缓存功能 时，是否允许缓存当前 API 调用结果。默认值为 true

• 返回值：

  • Promise<void>

• 示例：

await agent.aiHover('页面顶部的登录按钮');

#aiInput()

在某个元素中输入文本。

• 类型

// 推荐用法：定位提示在前，其他选项在 opt 中
function aiInput(
  locate: string | object,
  opt: {
    value: string | number;
    deepLocate?: boolean;
    xpath?: string;
    cacheable?: boolean;
    autoDismissKeyboard?: boolean;
    keyboardTypeDelay?: number;
    inputStrategy?: 'legacy' | 'sequential' | 'bulk';
    mode?: 'replace' | 'clear' | 'typeOnly';
  },
): Promise<void>;

// 兼容用法：保留向后兼容性
function aiInput(
  value: string | number,
  locate: string | object,
  options?: object,
): Promise<void>;

• 参数：

  推荐用法：

  • locate: string | object - 用自然语言描述的元素定位，或使用图片作为提示词。
  • opt: object - 配置对象，包含：
    • value: string | number - 必填，要输入的文本内容。
      • 当 mode 为 'replace' 时：文本将替换输入框中的所有现有内容。
      • 当 mode 为 'typeOnly' 时：直接输入文本，不会先清空输入框。
      • 当 mode 为 'clear' 时：会忽略文本内容，仅清空输入框。
    • deepLocate?: boolean - 是否开启深度定位。该参数原来叫 deepThink，现已更名为 deepLocate。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
    • cacheable?: boolean - 当启用 缓存功能 时，是否允许缓存当前 API 调用结果。默认值为 true
    • autoDismissKeyboard?: boolean - 如果为 true，则键盘会在输入文本后自动关闭，仅在 Android/iOS/HarmonyOS 中有效。默认值为 true。
    • keyboardTypeDelay?: number - 按键间延迟，单位为毫秒。取值必须是有限的非负数。该选项在 legacy 模式下是否生效取决于平台既有的输入路径，详见下表。支持延迟的 legacy 路径会在值大于 0 时逐个 Unicode 码点输入。适用于输入框在快速输入下丢字的场景。
    • inputStrategy?: 'legacy' | 'sequential' | 'bulk' - 控制 Midscene 如何把文本发送给平台。默认值为 'legacy'。
      • 'legacy'：保留各平台现有行为。它是兼容性默认值，升级后不会改变已有测试的输入方式。
      • 'sequential'：逐个 Unicode 码点发送。即使未设置 keyboardTypeDelay 或将其设为 0，Midscene 也会逐个发送。
      • 'bulk'：在平台支持时，只调用一次平台输入操作，以发送完整字符串。Web 的 replace 会先选中旧值，再使用 insertText。这个过程只产生一次插入 input 事件。它不会先产生清空 input 事件，再逐字符产生 input 事件。其他平台只会收到 Midscene 发起的一次底层输入调用。不过，操作系统或驱动仍可能合成多个应用事件。
      • 使用 'bulk' 时，必须省略 keyboardTypeDelay，或将它设为 0。如果值大于 0，Midscene 会抛出错误。所有策略都拒绝负数和非有限数值。动作级配置优先于 Device 或 Agent 的默认值。因此，单次动作选择 'bulk' 时，可以用 keyboardTypeDelay: 0 覆盖正数默认值。
    • mode?: 'replace' | 'clear' | 'typeOnly' - 输入模式。(默认值: 'replace')
      • 'replace': 先清空输入框，然后输入文本。
      • 'typeOnly': 直接输入文本，不会先清空输入框。
      • 'clear': 清空输入框，不会输入新的文本。

  所有平台的 inputStrategy 默认值均为 'legacy'。该模式会沿用先前版本中 Midscene 针对各平台的输入逻辑，具体表现可能因平台而异：

  平台	legacy 行为
  Web / Playwright / Puppeteer	replace 模式会先清空旧值并等待 DOM 稳定，再将完整字符串传给 keyboard.type(value)。浏览器驱动负责处理正数 keyboardTypeDelay。
  Chrome Extension / Bridge	沿用 Web 的“先清空、再输入”流程，通过远端键盘操作发送文本。legacy CDP 输入沿用零延迟行为。Bridge 在 CLI 侧解析策略，再转发键盘操作。
  Android	文本含有非 ASCII 字符或 shell 敏感字符时，通常只调用一次 yadb。为兼容旧行为，该路径忽略 keyboardTypeDelay。原生 input text 路径默认整段发送。keyboardTypeDelay 大于 0 时，改为逐个 Unicode 码点调用。
  iOS	默认调用一次 WDA typeText。keyboardTypeDelay 大于 0 时，改为对每个 Unicode 码点调用一次 typeRawKeys。
  HarmonyOS	默认调用一次 HDC inputText。keyboardTypeDelay 大于 0 时，改为对每个 Unicode 码点调用一次。
  Local Computer	未设置 keyboardTypeDelay 或将其设为 0 时，使用剪贴板粘贴。值大于 0 时，改为逐个 Unicode 码点发送真实键盘事件。
  RDP Computer	未设置 keyboardTypeDelay 或将其设为 0 时，只调用一次后端 typeText。值大于 0 时，改为对每个 Unicode 码点调用一次后端。

  兼容用法（已过时，但仍然支持）：

  • value: string | number - 要输入的文本内容。
  • locate: string | object - 用自然语言描述的元素定位，或使用图片作为提示词。
  • options?: object - 可选的配置对象，类型与推荐用法中的 opt 类型相同。

• 返回值：

  • Promise<void>

• 示例：

// 推荐用法
await agent.aiInput('搜索框', { value: 'Hello World' });

// 兼容用法（不推荐）
await agent.aiInput('Hello World', '搜索框');

#aiClearInput()

清空输入框内容。适合作为一个独立步骤使用：在输入前先清空，或只需删除现有文本而暂时不输入新内容。

• 类型

function aiClearInput(
  locate: string | object,
  opt?: {
    deepLocate?: boolean;
    xpath?: string;
    cacheable?: boolean;
  },
): Promise<void>;

• 参数：

  • locate: string | object - 要清空的输入框的自然语言描述，或通过图像提示。
  • opt?: object - 可选配置对象：
    • deepLocate?: boolean - 是否开启深度定位。默认 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 要操作元素的 xpath，默认空。
    • cacheable?: boolean - 启用缓存功能时是否缓存，默认 true。

• 返回值：

  • 返回 Promise<void>

• 示例：

// 清空搜索框
await agent.aiClearInput('搜索框');

// 先清空再输入新值
await agent.aiClearInput('邮箱输入框');
await agent.aiInput('邮箱输入框', { value: 'user@example.com' });

#aiKeyboardPress()

按下键盘上的某个键。

• 类型

// 推荐用法：定位提示在前，其他选项在 opt 中
function aiKeyboardPress(
  locate: string | object | undefined,
  opt: {
    keyName: string;
    deepLocate?: boolean;
    xpath?: string;
    cacheable?: boolean;
  },
): Promise<void>;

// 兼容用法：保留向后兼容性
function aiKeyboardPress(
  key: string,
  locate?: string | object,
  options?: object,
): Promise<void>;

• 参数：

  推荐用法：

  • locate: string | object | undefined - 可选的元素定位描述，或使用图片作为提示词。传入 undefined 时，不执行 AI 定位和预先点击，按键会直接作用于当前获得焦点的元素。
  • opt: object - 配置对象，包含：
    • keyName: string - 必填，要按下的键，如 Enter、Tab、Escape 等；输入文本请使用 aiInput()。Web 和 Computer Device 支持 Control+A、Shift+Enter 等 modifier shortcut，使用 + 连接按键。可在共享按键名称定义中查看非移动端的候选名称，实际支持情况以平台为准。内置的 Android、iOS 和 Harmony Device 仅支持单键。Harmony 支持一组保守的具名键以及 A-Z、0-9；? 等没有独立键码的输出字符不属于按键名。不支持的按键和移动端组合键会抛出错误；自定义 Device 的支持情况取决于其实现。
    • deepLocate?: boolean - 是否开启深度定位。该参数原来叫 deepThink，现已更名为 deepLocate。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
    • cacheable?: boolean - 当启用 缓存功能 时，是否允许缓存当前 API 调用结果。默认值为 true

  兼容用法（已过时，但仍然支持）：

  • key: string - 要按下的键，如 Enter、Tab、Escape 等。
  • locate?: string | object - 用自然语言描述的元素定位，或使用图片作为提示词。
  • options?: object - 可选的配置对象，类型与推荐用法中的 opt 类型相同。

• 返回值：

  • Promise<void>

• 示例：

// 推荐用法
await agent.aiKeyboardPress('搜索框', { keyName: 'Enter' });
await agent.aiKeyboardPress('搜索框', { keyName: 'Control+A' });

// 对当前获得焦点的元素执行纯键盘操作
await agent.aiKeyboardPress(undefined, { keyName: 'Control+X' });

// 兼容用法（不推荐）
await agent.aiKeyboardPress('Enter', '搜索框');

#aiScroll()

滚动页面或某个元素。

• 类型

// 推荐用法：定位提示在前，其他选项在 opt 中
function aiScroll(
  locate: string | object | undefined,
  opt: {
    scrollType?: 'singleAction' | 'scrollToBottom' | 'scrollToTop' | 'scrollToRight' | 'scrollToLeft';
    direction?: 'down' | 'up' | 'left' | 'right';
    distance?: number | null;
    deepLocate?: boolean;
    xpath?: string;
    cacheable?: boolean;
  },
): Promise<void>;

// 兼容用法：保留向后兼容性
function aiScroll(
  scrollParam: PlanningActionParamScroll,
  locate?: string | object,
  options?: object,
): Promise<void>;

• 参数：

  推荐用法：

  • locate: string | object | undefined - 用自然语言描述的元素定位，或使用图片作为提示词。如果未传入或为 undefined，Midscene 会在当前鼠标位置滚动。
  • opt: object - 配置对象，包含：
    • scrollType?: 'singleAction' | 'scrollToBottom' | 'scrollToTop' | 'scrollToRight' | 'scrollToLeft' - 滚动类型，默认值为 singleAction。
    • direction?: 'down' | 'up' | 'left' | 'right' - 滚动方向，默认值为 down。仅在 scrollType 为 singleAction 时生效。不论是 Android 还是 Web，这里的滚动方向都是指页面哪个方向的内容会进入屏幕。比如当滚动方向是 down 时，页面下方被隐藏的内容会从屏幕底部开始逐渐向上露出。
    • distance?: number | null - 滚动距离，单位为像素。设置为 null 表示由 Midscene 自动决定。
    • deepLocate?: boolean - 是否开启深度定位。该参数原来叫 deepThink，现已更名为 deepLocate。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
    • cacheable?: boolean - 当启用 缓存功能 时，是否允许缓存当前 API 调用结果。默认值为 true

  兼容用法（已过时，但仍然支持）：

  • scrollParam: PlanningActionParamScroll - 滚动参数（包含 scrollType、direction、distance）。
  • locate?: string | object - 用自然语言描述的元素定位，或使用图片作为提示词。
  • options?: object - 可选的配置对象，类型与推荐用法中的 opt 类型相同。

• 返回值：

  • Promise<void>

• 示例：

// 推荐用法
await agent.aiScroll('表单区域', {
  scrollType: 'singleAction',
  direction: 'up',
  distance: 100,
});

// 兼容用法（不推荐）
await agent.aiScroll(
  { scrollType: 'singleAction', direction: 'up', distance: 100 },
  '表单区域',
);

#aiPinch()

执行双指缩放手势，用于放大或缩小。支持 Android、iOS 和 Web（基于 Chromium 的浏览器）。

• 类型

function aiPinch(
  locate: string | object | undefined,
  opt: {
    direction: 'in' | 'out';
    distance?: number;
    duration?: number;
    deepLocate?: boolean;
    xpath?: string;
    cacheable?: boolean;
  },
): Promise<void>;

• 参数：

  • locate: string | object | undefined - 用自然语言描述的缩放目标元素，或使用图片作为提示词。如果未传入，缩放将在屏幕中心执行。
  • opt: object - 配置对象，包含：
    • direction: 'in' | 'out' - 必填。 "in" = 双指收拢（缩小），"out" = 双指张开（放大）。
    • distance?: number - 每根手指移动的距离（像素）。默认值为屏幕较短边的四分之一。
    • duration?: number - 缩放手势持续时间（毫秒），默认值为 500。
    • deepLocate?: boolean - 是否开启深度定位。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 目标元素的 xpath 路径。默认值为空。
    • cacheable?: boolean - 当启用缓存功能时，是否允许缓存。默认值为 true。

• 返回值：

  • Promise<void>

• 示例：

// 在地图上放大（双指张开）
await agent.aiPinch('地图区域', { direction: 'out', distance: 200 });

// 在屏幕中心缩小（双指收拢）
await agent.aiPinch(undefined, { direction: 'in' });

// 自定义持续时间放大
await agent.aiPinch('图片', { direction: 'out', distance: 300, duration: 1000 });

#aiLongPress()

长按（按住不放）某个元素，常用于唤起右键/上下文菜单、触发选中模式或其他长按手势。

• 类型

function aiLongPress(
  locate: string | object,
  opt?: {
    duration?: number;
    deepLocate?: boolean;
    xpath?: string;
    cacheable?: boolean;
  },
): Promise<void>;

• 参数：

  • locate: string | object - 要长按的元素的自然语言描述，或通过图像提示。
  • opt?: object - 可选配置对象：
    • duration?: number - 按住时长（毫秒）。Android 默认 2000，iOS 默认 1000，Web 默认 500。HarmonyOS 使用系统长按时长并忽略此选项。
    • deepLocate?: boolean - 是否启用深度定位，默认 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 要操作元素的 xpath，默认空。
    • cacheable?: boolean - 启用缓存功能时是否缓存，默认 true。

• 返回值：

  • 返回 Promise<void>

• 示例：

// 长按首页的第一篇文章以唤起菜单
await agent.aiLongPress('首页的第一篇文章');

// 自定义长按时长
await agent.aiLongPress('消息气泡', { duration: 2000 });

#aiDoubleClick()

双击某个元素。

• 类型

function aiDoubleClick(locate: string | object, options?: object): Promise<void>;

• 参数：

  • locate: string | object - 用自然语言描述的元素定位，或使用图片作为提示词。
  • options?: object - 可选，一个配置对象，包含：
    • deepLocate?: boolean - 是否开启深度定位。该参数原来叫 deepThink，现已更名为 deepLocate。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
    • cacheable?: boolean - 当启用 缓存功能 时，是否允许缓存当前 API 调用结果。默认值为 true

• 返回值：

  • Promise<void>

• 示例：

await agent.aiDoubleClick('页面顶部的文件名称');

// 使用 deepLocate 功能精确定位元素
await agent.aiDoubleClick('页面顶部的文件名称', { deepLocate: true });

#aiRightClick()

可用于 web 页面和 PC 桌面端（@midscene/computer），不可用于移动设备（Android、iOS 或 HarmonyOS）。

右键点击某个元素。请注意，Midscene 在右键点击后无法与浏览器原生上下文菜单交互。这个接口通常用于已经监听了右键点击事件的元素。

• 类型

function aiRightClick(locate: string | object, options?: object): Promise<void>;

• 参数：

  • locate: string | object - 用自然语言描述的元素定位，或使用图片作为提示词。
  • options?: object - 可选，一个配置对象，包含：
    • deepLocate?: boolean - 是否开启深度定位。该参数原来叫 deepThink，现已更名为 deepLocate。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
    • cacheable?: boolean - 当启用 缓存功能 时，是否允许缓存当前 API 调用结果。默认值为 true

• 返回值：

  • Promise<void>

• 示例：

await agent.aiRightClick('页面顶部的文件名称');

// 使用 deepLocate 功能精确定位元素
await agent.aiRightClick('页面顶部的文件名称', { deepLocate: true });

#提取、定位与断言

#aiAsk()

使用此方法，你可以针对当前页面，直接向 AI 模型发起提问，并获得字符串形式的回答。

aiAsk() 与 aiString() 的查询和返回行为相同，但仍可分别通过 aiContexts.aiAsk 和 aiContexts.aiString 配置 Agent 级 context。

• 类型

function aiAsk(prompt: string | object, options?: object): Promise<string>;

• 参数：

  • prompt: string | object - 用自然语言描述的询问内容，或使用图片作为提示词。
  • options?: object - 可选，一个配置对象，包含：
    • domIncluded?: boolean | 'visible-only' - 是否向模型发送精简后的 DOM 信息，一般用于提取 UI 中不可见的属性，比如图片的链接。如果设置为 'visible-only'，则只发送可见的元素。默认值为 false。
    • screenshotIncluded?: boolean - 是否向模型发送截图。默认值为 true。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。

• 返回值：

  • 返回一个 Promise。返回 AI 模型的回答。

• 示例：

const result = await agent.aiAsk('当前页面的应该怎么进行测试？');
console.log(result); // 输出 AI 模型的回答

除了 aiAsk 方法，你还可以使用 aiQuery 方法，直接从 UI 提取结构化的数据。

#aiQuery()

使用此方法，你可以直接从 UI 提取结构化的数据。只需在 dataDemand 中描述期望的数据格式（如字符串、数字、JSON、数组等），Midscene 即返回相应结果。

• 类型

function aiQuery<T>(dataDemand: string | object, options?: object): Promise<T>;

• 参数：

  • dataDemand: string | object：描述预期的返回值和格式。
  • options?: object - 可选，一个配置对象，包含：
    • domIncluded?: boolean | 'visible-only' - 是否向模型发送精简后的 DOM 信息，一般用于提取 UI 中不可见的属性，比如图片的链接。如果设置为 'visible-only'，则只发送可见的元素。默认值为 false。
    • screenshotIncluded?: boolean - 是否向模型发送截图。默认值为 true。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。

• 返回值：

  • 返回值可以是任何合法的基本类型，比如字符串、数字、JSON、数组等。
  • 你只需在 dataDemand 中描述它，Midscene 就会给你满足格式的返回。

• 示例：

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

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

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

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

// 使用 domIncluded 功能提取 UI 中不可见的属性
const dataD = await agent.aiQuery(
  '{name: string, age: string, avatarUrl: string}[], 表格中的数据记录',
  { domIncluded: true },
);

此外，我们还提供了 aiBoolean(), aiNumber(), aiString() 三个便捷方法，用于直接提取布尔值、数字和字符串。

#aiBoolean()

从 UI 中提取一个布尔值。

• 类型

function aiBoolean(prompt: string | object, options?: object): Promise<boolean>;

• 参数：

  • prompt: string - 用自然语言描述的期望值，或使用图片作为提示词。
  • options?: object - 可选，一个配置对象，包含：
    • domIncluded?: boolean | 'visible-only' - 是否向模型发送精简后的 DOM 信息，一般用于提取 UI 中不可见的属性，比如图片的链接。如果设置为 'visible-only'，则只发送可见的元素。默认值为 false。
    • screenshotIncluded?: boolean - 是否向模型发送截图。默认值为 true。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。

• 返回值：

  • 返回一个 Promise。当 AI 返回结果时解析为布尔值。

• 示例：

const boolA = await agent.aiBoolean('是否存在登录对话框');

// 使用 domIncluded 功能提取 UI 中不可见的属性
const boolB = await agent.aiBoolean('忘记密码按钮是否存在链接', {
  domIncluded: true,
});

#aiNumber()

从 UI 中提取一个数字。

• 类型

function aiNumber(prompt: string | object, options?: object): Promise<number>;

• 参数：

  • prompt: string | object - 用自然语言描述的期望值，或使用图片作为提示词。
  • options?: object - 可选，一个配置对象，包含：
    • domIncluded?: boolean | 'visible-only' - 是否向模型发送精简后的 DOM 信息，一般用于提取 UI 中不可见的属性，比如图片的链接。如果设置为 'visible-only'，则只发送可见的元素。默认值为 false。
    • screenshotIncluded?: boolean - 是否向模型发送截图。默认值为 true。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。

• 返回值：

  • 返回一个 Promise。当 AI 返回结果时解析为数字。

• 示例：

const numberA = await agent.aiNumber('账户剩余的积分');

// 使用 domIncluded 功能提取 UI 中不可见的属性
const numberB = await agent.aiNumber('账户剩余的积分元素的 value 值', {
  domIncluded: true,
});

#aiString()

从 UI 中提取一个字符串。

aiString() 与 aiAsk() 的查询和返回行为相同，但仍可分别通过 aiContexts.aiString 和 aiContexts.aiAsk 配置 Agent 级 context。

• 类型

function aiString(prompt: string | object, options?: object): Promise<string>;

• 参数：

  • prompt: string | object - 用自然语言描述的期望值，或使用图片作为提示词。
  • options?: object - 可选，一个配置对象，包含：
    • domIncluded?: boolean | 'visible-only' - 是否向模型发送精简后的 DOM 信息，一般用于提取 UI 中不可见的属性，比如图片的链接。如果设置为 'visible-only'，则只发送可见的元素。默认值为 false。
    • screenshotIncluded?: boolean - 是否向模型发送截图。默认值为 true。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。

• 返回值：

  • 返回一个 Promise。当 AI 返回结果时解析为字符串。

• 示例：

const stringA = await agent.aiString('当前列表的第一条记录的名称');

// 使用 domIncluded 功能提取 UI 中不可见的属性
const stringB = await agent.aiString('当前列表的第一条记录的跳转链接', {
  domIncluded: true,
});

#aiLocate()

通过自然语言描述一个元素的定位。

• 类型

function aiLocate(
  locate: string | object,
  options?: object,
): Promise<{
  rect: {
    left: number;
    top: number;
    width: number;
    height: number;
  };
  center: [number, number];
  dpr?: number; // 仅 Web：设备像素比
}>;

• 参数：

  • locate: string | object - 用自然语言描述的元素定位，或使用图片作为提示词。
  • options?: object - 可选，一个配置对象，包含：
    • deepLocate?: boolean - 是否开启深度定位。该参数原来叫 deepThink，现已更名为 deepLocate。默认值为 false。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。
    • xpath?: string - 目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
    • cacheable?: boolean - 当启用 缓存功能 时，是否允许缓存当前 API 调用结果。默认值为 true

• 返回值：

  • 返回一个 Promise。当元素定位成功时解析为元素定位信息。
  • rect 在大多数定位链路里表示命中的目标元素边界。
  • 有些模型只支持按点定位，不支持按元素边界定位。在这种情况下，例如 AutoGLM，这里的 rect 会退化成一个包含元素中心的 8x8 小方块，而不是真实的元素边界。
  • 由于 rect 的表现会明显受底层模型能力影响，不建议对这个字段建立过强的边界语义依赖。
  • center 是基于模型定位结果得到的目标点，坐标对应截图的真实像素。如果你想获得更稳定的点击位置，推荐优先使用 center 字段。
  • dpr 是仅供 Web 使用的兼容字段，表示截图物理像素与 CSS 逻辑像素的比例。其他 Agent 类型不保证提供该字段。

• 示例：

const locateInfo = await agent.aiLocate('页面顶部的登录按钮');
console.log(locateInfo);

#aiAssert()

通过自然语言描述一个断言条件，让 AI 判断该条件是否为真。当条件不满足时，SDK 会抛出错误，并在错误信息中追加 AI 返回的详细原因。

• 类型

function aiAssert(
  assertion: string | object,
  errorMsg?: string,
  options?: object,
): Promise<void>;

• 参数：

  • assertion: string | object - 用自然语言描述的断言条件，或使用图片作为提示词。
  • errorMsg?: string - 当断言失败时附加的可选错误提示信息。
  • options?: object - 可选，一个配置对象，包含：
    • domIncluded?: boolean | 'visible-only' - 是否向模型发送精简后的 DOM 信息，一般用于提取 UI 中不可见的属性，比如图片的链接。如果设置为 'visible-only'，则只发送可见的元素。默认值为 false。
    • screenshotIncluded?: boolean - 是否向模型发送截图。默认值为 true。
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。

• 返回值：

  • 返回一个 Promise。当断言成功时解析为 void；若断言失败，则抛出一个错误，错误信息包含 errorMsg 以及 AI 生成的原因。

• 示例：

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

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

#观察与等待

其他事件直接 await 应用的 Promise 或浏览器、设备 API；一次性事件应先订阅再触发。

#startObserving()

startObserving() 会持续记录屏幕。它适合检查短暂出现的 UI，例如 toast、横幅和页面切换。

调用流程很简单：先开始录制，再执行页面操作，最后调用 stop()。stop() 返回 UIObservation。你可以查询或断言录制期间的画面。

function startObserving(options?: {
  intervalMs?: number; // 采样间隔。默认 1,000 ms，最小 200 ms
  maxFrames?: number; // 最多保留的帧数。默认 30
  watchdogMs?: number; // 最长录制时间。默认 300,000 ms；0 表示不限制
}): Promise<UIObserver>;

UIObserver 负责录制：

• observer.bufferedFrameCount: number - 录制过程中当前缓冲的帧数。
• observer.stop(): Promise<UIObservation> - 停止录制，并返回 UIObservation。

UIObservation 保存已经录下的画面。调用 stop() 后，这些画面不再变化。

你可以调用 aiQuery()、aiBoolean()、aiNumber()、aiString()、aiAsk() 和 aiAssert()。这些方法只读取录制画面，不读取当前页面的 DOM。

因此，这些方法不支持 domIncluded。TypeScript 会检查这个错误。JavaScript 在运行时传入该参数，Midscene 也会抛出错误。

UIObservation 还包含 frameCount、startedAt 和 endedAt。使用完后，可以调用 observation.dispose() 清理临时图片。agent.destroy() 也会清理尚未释放的图片。

const observer = await agent.startObserving();
await agent.aiAct('提交表单');
const observation = await observer.stop();
await observation.aiAssert('过程中弹出了成功提示 toast');
const toastCount = await observation.aiNumber('共出现了多少次成功 toast？');
await observation.dispose();

采样和资源占用：

• Midscene 会优先使用连续帧源。Android 使用 scrcpy（scrcpyConfig.enabled），iOS 使用 WDA MJPEG（wdaMjpegFrameSource.enabled），Web 使用 CDP screencast。无法使用连续帧源时，Midscene 会定时截图。移动端此时的采样频率较低。
• data URL 形式的帧会在采样时写入文件。UIObserver 不会把所有图片长期保存在内存中。其他帧会在录制停止时分批解码并保存。查询或断言时，Midscene 才读取图片。
• 模型会接收最多 maxFrames 帧，以及最后一张截图。增大 intervalMs 可以减少采样帧，减小 maxFrames 可以限制帧数。观察帧会显示在报告时间线中，并带有 Observed 标签。
• iOS 的观察帧来自 MJPEG 流，分辨率和质量较低。最后一张截图仍使用完整质量。

#aiWaitFor()

等待某个条件达成。为控制 AI 服务成本，相邻两次检查的开始时间至少间隔 checkIntervalMs 毫秒。

• 类型

function aiWaitFor(
  assertion: string,
  options?: {
    timeoutMs?: number;
    checkIntervalMs?: number;
    context?: string;
  },
): Promise<void>;

• 参数：

  • assertion: string - 用自然语言描述的断言条件
  • options?: object - 可选的配置对象
    • timeoutMs?: number - 超时时间（毫秒，默认为 15000）。每轮检查开始时都会记录时间，只要该时间点仍在超时窗口内，就会进入下一轮检查；否则视为超时
    • checkIntervalMs?: number - 相邻两次检查开始时间的最小间隔（毫秒），默认值为 3000
    • context?: string - 本次调用的额外上下文。详见单次调用上下文。

• 返回值：

  • 返回一个 Promise。当断言成功时解析为 void；若超时，则抛出错误。

• 示例：

// 基本用法
await agent.aiWaitFor('界面上至少有一个耳机的信息');

// 使用自定义配置
await agent.aiWaitFor('购物车图标显示数量为 2', {
  timeoutMs: 30000, // 等待 30 秒
  checkIntervalMs: 5000, // 每 5 秒检查一次
});

#工作流执行与上下文

#runYaml()

执行一个 YAML 格式的自动化脚本。脚本中的 tasks 部分会被解析和执行，并返回所有 .aiQuery 调用的结果。

• 类型

function runYaml(yamlScriptContent: string): Promise<{ result: any }>;

• 参数：

  • yamlScriptContent: string - YAML 格式的脚本内容

• 返回值：

  • 返回一个包含 result 属性的对象，其中包含所有 aiQuery 调用的结果

• 示例：

const { result } = await agent.runYaml(`
tasks:
  - name: search weather
    flow:
      - ai: input 'weather today' in input box, click search button
      - sleep: 3000

  - name: query weather
    flow:
      - aiQuery: "the result shows the weather info, {description: string}"
`);
console.log(result);

#runGherkinScenario()

运行一个 Gherkin Scenario，并把其中的步骤映射为 Midscene Agent 调用。

• 类型

function runGherkinScenario(
  scenarioText: string,
  options?: {
    context?: string;
    abortSignal?: AbortSignal;
    deepThink?: 'unset' | true | false;
    deepLocate?: boolean;
  },
): Promise<void>;

• 参数：

  • scenarioText: string - 一个 Gherkin scenario，或者一组不带 Scenario: 头部的 Gherkin 步骤
  • options?: object - 可选的运行选项
    • context?: string - 应用于本次运行每个步骤的 AI 补充信息。对于每个映射后的 API 调用，它会覆盖 Agent 的 API 级 context 和 aiContexts.default
    • abortSignal?: AbortSignal - 用于中止本次运行的可选信号
    • deepThink?: 'unset' | true | false - 传给 Given 和 When 步骤对应的 aiAct
    • deepLocate?: boolean - 传给 Given 和 When 步骤对应的 aiAct

• 返回值：

  • Promise<void> - 所有步骤执行完成后 resolve。如果某个步骤失败，错误文案会包含 Gherkin 行号、原始步骤，以及当时正在执行的 Midscene 语义动作。

• 示例：

await agent.runGherkinScenario(`
Scenario: 添加待办事项
  Given 待办事项页面已经打开
  When 我添加一条名为“买牛奶”的待办事项
  Then 待办事项列表中应该包含“买牛奶”
`);

关于支持规则、限制、缓存行为和 YAML 用法，请参考 BDD 风格脚本（Gherkin）。

#setAIContext()

设置 Agent 级共享回退 context，或某个 API 的 context。

• 类型

function setAIContext(
  target: 'default' | AiApiName,
  context: string | undefined,
): void;

• 参数：

  • target：使用 'default' 表示所有 AI API 共享的缺省回退值，也可以传入 'aiAct'、'aiTap'、'aiQuery' 或 'aiAssert' 等 API 名称。
  • context：提供给 AI 的补充信息，例如业务事实、规则、约束或输出要求。对 API target 传入 '' 会屏蔽共享默认值；传入 undefined 会移除该 API 的覆盖值，并在已配置 aiContexts.default 时重新回退到该值。对 default target 传入 undefined 会移除共享回退值。

• 示例：

agent.setAIContext('default', '页面中的价格单位是美元。');
agent.setAIContext('aiQuery', '金额不返回货币符号。');
agent.setAIContext('aiQuery', ''); // aiQuery 不使用 aiContexts.default
agent.setAIContext('aiQuery', undefined); // aiQuery 重新继承 aiContexts.default

#setAIActContext()（已废弃）

已废弃的兼容性 setter，用于设置后续 agent.aiAct() 或 agent.ai() 调用发送给 AI 模型的背景知识。新代码请使用 agent.setAIContext('aiAct', context)。该方法仍与后者等价，并覆盖原有的 aiContexts.aiAct。

对于即时操作类型的 API，比如 aiTap()，这个设置不会生效。

• 类型

function setAIActContext(aiActContext: string): void;

• 参数：

  • aiActContext: string - 要发送给 AI 模型的背景知识。

• 示例：

await agent.setAIActContext('如果 “使用cookie” 对话框存在，先关闭它');

#evaluateJavaScript()

仅 Web Agent 可用。

这个方法允许你在 web 页面上下文中执行一段 JavaScript 代码，并返回执行结果。

• 类型

function evaluateJavaScript(script: string): Promise<any>;

• 参数：

  • script: string - 要执行的 JavaScript 代码。

• 返回值：

  • 返回执行结果。

• 示例：

const result = await agent.evaluateJavaScript('document.title');
console.log(result);

#freezePageContext()

冻结当前页面上下文，使后续所有的操作都复用同一个页面快照，避免多次重复获取页面状态。在执行大量并发操作时，它可以显著提升性能。

一些注意点：

• 通常情况下，你不需要使用这个方法，除非你确定“页面状态获取”是脚本性能瓶颈。
• 需要及时调用 agent.unfreezePageContext() 来恢复实时页面状态。
• 不要在交互类操作中使用这个方法，它会让 AI 模型无法感知到页面的最新状态，产生令人困惑的错误。

• 类型

function freezePageContext(): Promise<void>;

• 返回值：

  • Promise<void>

• 示例：

// 冻结页面上下文，确保多个操作看到相同的页面状态
await agent.freezePageContext();

// 执行一些操作...
const results = await Promise.all([
  agent.aiQuery('Username input box value'),
  agent.aiQuery('Password input box value'),
  agent.aiLocate('Login button'),
]);
console.log(results);

// 解冻页面上下文
await agent.unfreezePageContext();

#unfreezePageContext()

解冻页面上下文，恢复使用实时的页面状态。

• 类型

function unfreezePageContext(): Promise<void>;

• 返回值：

  • Promise<void>

#报告、指标与生命周期

#recordToReport()

默认在报告文件中记录当前截图并添加描述，也可以记录调用方传入的截图。

• 类型

interface RecordToReportOptions {
  content?: string;
  /** @deprecated 请改用 screenshots。 */
  screenshotBase64?: string;
  screenshots?: {
    /**
     * PNG/JPEG data URI，或裸 PNG base64 body。
     */
    base64: string;
    description?: string;
  }[];
}

function recordToReport(
  title?: string,
  options?: RecordToReportOptions,
): Promise<void>;

• 参数：

  • title?: string - 可选，截图的标题，如果未提供，则标题为 'untitled'。
  • options?: RecordToReportOptions - 可选，一个配置对象，包含：
    • content?: string - 截图的描述。
    • screenshots?: Array<{ base64: string; description?: string }> - 在同一个报告条目下记录一张或多张传入的截图。设置该选项后，Midscene 不会再自动截图。base64 推荐使用 PNG/JPEG data URI，例如 data:image/png;base64,...；也可以传裸 base64 body，此时会按 PNG 处理。

• 兼容性：

  screenshotBase64?: string 仍然作为向后兼容的单截图覆盖参数被接受。新代码建议使用 screenshots: [{ base64 }]。screenshots 和 screenshotBase64 二者只能传入一个。

• 返回值：

  • Promise<void>

• 示例：

await agent.recordToReport('登录页面', {
  content: '用户 A',
});

const before = await page.screenshot({ encoding: 'base64' });
const after = await page.screenshot({ encoding: 'base64' });
await agent.recordToReport('结算页对比', {
  content: '对比提交前后的页面状态。',
  screenshots: [
    {
      base64: `data:image/png;base64,${before}`,
      description: '提交前',
    },
    {
      base64: `data:image/png;base64,${after}`,
      description: '提交后',
    },
  ],
});

#_unstableLogContent()

从报告文件中获取日志内容。日志内容的结构可能会在未来发生变化。

• 类型

function _unstableLogContent(): object;

• 返回值：

  • 返回一个对象，包含日志内容。

• 示例：

const logContent = agent._unstableLogContent();
console.log(logContent);

大模型用量指标

Midscene 会记录每一次大模型调用的 token 用量。你可以在运行时从 agent 读取聚合后的总量,这对于配合 Langfuse 等工具做成本可观测性非常有用。

#metrics

一个 getter,返回自 agent 创建以来累计的大模型用量快照。

• 类型

interface UsageBucket {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
  calls: number;
}

interface MidsceneUsageMetrics {
  totalPromptTokens: number;
  totalCompletionTokens: number;
  totalTokens: number;
  totalCachedInput: number;
  totalTimeCostMs: number;
  calls: number;
  // 按调用意图拆分:`planning`、`insight`、`default`。
  byIntent: Record<string, UsageBucket>;
  // 按模型名称拆分。
  byModel: Record<string, UsageBucket>;
}

• 示例

await agent.aiAct('搜索耳机');
const usage = agent.metrics;
console.log(usage.totalTokens, usage.byIntent, usage.byModel);

#onLLMUsage 选项

如需实时追踪,可在构造 agent 时传入 onLLMUsage 回调。每次大模型调用的用量一旦就绪即触发一次,回调参数为原始用量信息(token 数、模型名、意图、请求 id 等)。

const agent = new PuppeteerAgent(page, {
  onLLMUsage: (usage) => {
    langfuse.event({ name: usage.intent, value: usage.total_tokens });
  },
});

#destroy()

完成 Agent 报告的收尾（finalization），并释放 Agent 持有的资源。

• 类型

function destroy(): Promise<void>;

• 行为：
  • 停止正在运行的 observer。
  • 调用底层 interface 的可选 destroy() 方法，并等待清理完成。
  • 等待报告写入完成，再完成报告收尾。最后，将最终路径写入 .reportFile。如果没有生成报告，则写入 undefined。
  • 首次调用完成后，再次调用不会重复清理。
  • 如果 interface 清理失败，Midscene 仍会尝试完成报告收尾，然后抛出清理错误。

调用该方法后，请勿继续使用这个 Agent。

属性

#.reportFile

当前报告文件的路径。它的类型是 string | null | undefined。

首次更新报告前，该属性没有可用值。以下情况也不会生成报告路径：关闭报告生成功能、Agent 在没有文件系统访问能力的浏览器环境中运行，或 Agent 没有产生 execution。

报告路径可用后，报告内容仍可能继续更新。使用最终报告前，请调用 await agent.destroy()。该方法会等待报告写入完成，完成报告的 收尾，并将最终路径写入 .reportFile。

#单次调用上下文

context 是提供给 AI 的补充信息，例如业务事实、判断或操作规则、约束以及输出要求。它用于补充 API 的主提示词，而不是替代主提示词。

使用 aiContexts.default 为所有 AI API 提供共享的缺省回退值，使用 aiContexts[apiName] 配置某个 API，再使用单次调用的 options.context 配置某一次请求。如果配置了 aiContexts.default，只有两个更具体的层级都没有提供值时才会选用它；它不会与其他层级自动合并。

const defaultContext =
  '页面中划线价格表示原价，普通价格表示当前售价，所有价格单位均为美元。';
const agent = new PlaywrightAgent(page, {
  aiContexts: {
    default: defaultContext,
    aiAct: '', // 显式不使用默认 context
    aiQuery: '提取金额时只返回数字，不包含货币符号。',
    aiBoolean: `${defaultContext}\n\n仅当当前售价低于原价时，才判断商品正在促销。`,
  },
});

const isOnSale = await agent.aiBoolean('这个商品是否正在促销？');

最终用户 context 为 options.context ?? aiContexts[apiName] ?? aiContexts.default。这些层级互相覆盖，不会自动合并。'' 是一个已定义值，会清空低优先级用户 context；undefined 或未配置字段则继续使用下一个已配置的回退值。如需组合多个 context 片段，请像上例一样显式拼接字符串。

支持的 API key 包括 aiAct、aiTap、aiRightClick、aiDoubleClick、aiHover、aiInput、aiKeyboardPress、aiScroll、aiPinch、aiLongPress、aiClearInput、aiLocate、aiQuery、aiBoolean、aiNumber、aiString、aiAsk、aiAssert 和 aiWaitFor。ai 与已废弃的 aiAction 别名使用 aiAct context。

#共享类型

定位选项：深度定位（deepLocate）

deepLocate 是一个可选参数，适用于所有需要元素定位的 API（aiAct、aiTap、aiHover、aiInput、aiKeyboardPress、aiScroll、aiDoubleClick、aiRightClick、aiLocate 等）。

开启后，Midscene 会调用 AI 模型两次以精确定位元素，从而提升准确性。这在目标元素面积较小、难以和周围元素区分时非常有用。对于新一代模型（如 Qwen3.x / Doubao 2.0 / Gemini 3.5），大多数场景下带来的收益不明显，建议按需开启。

• 默认值：false

// 开启 deepLocate 精确定位较难识别的元素
await agent.aiTap('右上角购物车图标', { deepLocate: true });

#使用图片的提示词输入

你可以在提示词中使用图片作为补充，来描述无法通过自然语言表达的内容。

使用图片作为提示词时，提示词的参数格式如下：

{
  // 提示词文本，其中可提及需要使用的图片
  prompt: string,
  // 提示词中提到的图片
  images?: {
    // 图片名称，需要和提示词文本中提到的图片名称对应
    name: string,
    // 图片 url，可以是本地图片路径、Base64 字符串，或者图片的 http 链接
    url: string
  }[]
  // 开启该选项后，http 格式的图片链接会被转化为 Base64 编码发送给大模型，适用于图片链接不是公开可访问的情况。
  convertHttpImage2Base64?: boolean
}

• 示例一：使用图片描述点击位置

await agent.aiTap({
  prompt: '指定 logo',
  images: [
    {
      name: '指定 logo',
      url: 'https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png',
    },
  ],
});

• 示例二：使用图片进行页面断言

await agent.aiAssert({
  prompt: '页面上是否存在指定 logo',
  images: [
    {
      name: '指定 logo',
      url: 'https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png',
    },
  ],
});

• 示例三：使用图片引导操作（aiAct）

await agent.aiAct({
  prompt: '点击与参考 logo 一致的图标',
  images: [
    {
      name: '指定 logo',
      url: 'https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png',
    },
  ],
});

图片尺寸的注意事项

请遵守模型提供商对图片体积和尺寸的限制。过大或过小的图片都可能被拒绝，准确限制请以模型提供商的文档为准。

#报告工具

ReportMergingTool

每个自动化工作流都可以生成独立报告。ReportMergingTool 可以将这些报告合并，便于统一查看和管理。合并结果可能是独立的 HTML 文件，也可能是包含 index.html 和外部截图资源的目录。

#new ReportMergingTool()

创建一个报告合并工具实例。

• 示例:

import { ReportMergingTool } from '@midscene/core/report';

const reportMergingTool = new ReportMergingTool();

#.append()

将自动化报告添加到待合并列表中。通常在每个自动化工作流结束后调用此方法。

• 类型

type SkippedReportFileAttributes = Omit<
  ReportFileAttributes,
  'testStatus'
> & {
  testStatus: 'skipped';
};

type ReportFileWithAttributes =
  | {
      reportFilePath: string;
      reportAttributes: ReportFileAttributes;
    }
  | {
      reportFilePath?: undefined;
      reportAttributes: SkippedReportFileAttributes;
    };

function append(reportInfo: ReportFileWithAttributes): void;

• 参数:

  • reportInfo: ReportFileWithAttributes - 报告信息对象，包含:
    • reportFilePath: string | undefined - 报告文件的路径，通常是 agent.reportFile。只有当 reportAttributes.testStatus 为 'skipped' 时，才能省略该字段。其他状态缺少路径时，append() 会抛出错误
    • reportAttributes: object - 报告属性
      • testId: string - 自动化工作流的唯一标识符
      • testTitle: string - 自动化工作流标题
      • testDescription: string - 自动化工作流描述
      • testDuration: number - 自动化工作流执行时长(毫秒)
      • testStatus: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted' - 自动化状态

• 返回值:

  • void

• 示例:

import type { TestStatus } from '@midscene/core';

// 在 afterEach 钩子中添加报告
afterEach(async (ctx) => {
  let workflowStatus: TestStatus = 'passed';
  if (ctx.task.result?.state === 'skip') {
    workflowStatus = 'skipped';
  } else if (ctx.task.result?.errors?.[0]?.message.includes('timed out')) {
    workflowStatus = 'timedOut';
  } else if (ctx.task.result?.state === 'fail') {
    workflowStatus = 'failed';
  }

  // 读取最终路径前，先完成报告的 finalization。
  await agent.destroy();
  const reportFilePath = agent.reportFile;
  const reportAttributes = {
    testId: ctx.task.name,
    testTitle: ctx.task.name,
    testDescription: '自动化工作流描述',
    testDuration: Date.now() - startTime,
  };

  if (!reportFilePath) {
    if (workflowStatus !== 'skipped') {
      throw new Error('Midscene 报告未生成');
    }

    reportMergingTool.append({
      reportAttributes: {
        ...reportAttributes,
        testStatus: 'skipped',
      },
    });
    return;
  }

  reportMergingTool.append({
    reportFilePath,
    reportAttributes: {
      ...reportAttributes,
      testStatus: workflowStatus,
    },
  });
});

调用 .mergeReports() 前，应完成所有报告相关 Agent 的收尾。

#.mergeReports()

执行报告合并操作，将所有添加的报告合并为一份报告。

• 类型

function mergeReports(
  reportFileName?: 'AUTO' | string,
  opts?: {
    rmOriginalReports?: boolean;
    overwrite?: boolean;
    outputDir?: string;
  },
): string | null;

• 参数:

  • reportFileName?: 'AUTO' | string - 合并后的报告文件名
    • 默认为 'AUTO'，自动生成文件名
    • 可以指定自定义文件名(不需要 .html 后缀)
  • opts?: object - 可选配置对象
    • rmOriginalReports?: boolean - 是否删除原始报告文件,默认为 false
    • overwrite?: boolean - 如果目标文件已存在是否覆盖，默认为 false
    • outputDir?: string - 合并报告的输出目录。相对路径从当前工作目录开始解析。默认输出到 midscene_run/report/

• 返回值:

  • 成功时返回合并报告的入口 HTML 路径
  • 如果没有添加任何报告，返回 null
  • 所有源报告均使用 single-html 时，输出路径为 <outputDir>/<reportFileName>.html
  • 任一源报告使用 html-and-external-assets 时，输出路径为 <outputDir>/<reportFileName>/index.html，同时输出截图资源

• 示例:

// 基本用法 - 使用自动生成的文件名
afterAll(() => {
  reportMergingTool.mergeReports();
});

// 指定自定义文件名
afterAll(() => {
  reportMergingTool.mergeReports('my-automation-report');
});

// 合并后删除原始报告
afterAll(() => {
  reportMergingTool.mergeReports('my-automation-report', {
    rmOriginalReports: true,
  });
});

// 覆盖已存在的报告文件
afterAll(() => {
  reportMergingTool.mergeReports('my-automation-report', {
    overwrite: true,
  });
});

// 将合并报告写入自定义目录
afterAll(() => {
  reportMergingTool.mergeReports('my-automation-report', {
    outputDir: './test-results',
  });
});

#.clear()

清空待合并的报告列表。如果需要在同一个实例中进行多次合并操作,可以使用此方法清空之前的报告列表。

• 类型

function clear(): void;

• 返回值:

  • void

• 示例:

reportMergingTool.mergeReports('first-batch');
reportMergingTool.clear(); // 清空列表
// 继续添加新的报告...

#Web 浏览器（@midscene/web）

当你需要自定义 Midscene 的浏览器自动化 Agent，或查阅 Web 专属构造参数时，请参考本篇。关于通用参数（报告、Hook、缓存等），请阅读API 参考（通用）。

#Web Action Space（动作空间）

PuppeteerAgent、PlaywrightAgent 和 Chrome Bridge 共用一套 Action Space，Midscene Agent 在规划任务时可以使用这些操作：

• Tap —— 左键点击元素。
• RightClick —— 右键点击元素。
• DoubleClick —— 双击元素。
• Hover —— 悬停目标元素。
• Input —— 输入文本，支持 replace/typeOnly/clear 模式（append 是 typeOnly 的已废弃别名）。
• KeyboardPress —— 按下指定键（可在按键前先聚焦目标）。
• Scroll —— 以元素为起点或从屏幕中央滚动，支持滚动到顶/底/左/右。
• DragAndDrop —— 从一个元素拖拽到另一个元素。
• LongPress —— 长按目标元素，可选自定义时长。
• Swipe —— 触摸式滑动（开启 enableTouchEventsInActionSpace 时可用）。
• Pinch —— 双指缩放手势，用于放大/缩小（开启 enableTouchEventsInActionSpace 时可用；Playwright 仅支持 Chromium 内核浏览器）。
• ClearInput —— 清空输入框内容。
• Navigate —— 在当前标签页打开指定 URL。
• Reload —— 刷新当前页面。
• GoBack —— 浏览器后退。

生命周期与所有权

Puppeteer 和 Playwright Page/Browser Agent 继承通用的 destroy() 方法。调用该方法会完成 Midscene 报告收尾， 并清理 Agent 持有的资源。该方法不会关闭 Agent 使用的 Page、Browser 或 BrowserContext。

#PuppeteerPageAgent / PuppeteerAgent

当你需要在 Puppeteer 控制的浏览器里复用 Midscene 的 AI 操作能力时使用。

PuppeteerPageAgent 绑定单个 Puppeteer Page。PuppeteerAgent 仍作为兼容别名保留。

导入

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

构造器

const agent = new PuppeteerPageAgent(page, {
  // 浏览器特有配置...
});

浏览器特有选项

除了通用 Agent 参数，Puppeteer 还提供：

• forceSameTabNavigation: boolean —— 限制始终在当前标签页内导航，默认 true。
• waitForNavigationTimeout、waitForNetworkIdleTimeout —— 默认等待策略的高级配置。
• enableTouchEventsInActionSpace: boolean —— 在动作空间里增加触摸手势（如滑动），用于需要触摸事件的页面，默认 false。
• keyboardTypeDelay: number —— 按键间延迟，单位为毫秒。取值必须是有限的非负数。在 'legacy' 模式下，Puppeteer 的 page.keyboard.type 负责处理正数延迟。默认值为 undefined。此时，Midscene 不传该选项，而是使用 Puppeteer 自身的默认值。通常无须配置。只有受控输入框在快速输入时丢字，才需要调大该值，例如 80。
• inputStrategy: 'legacy' | 'sequential' | 'bulk' —— Input 动作的默认文本输入策略。使用 'bulk' 可以一次插入完整字符串。使用 'sequential' 可以强制逐个 Unicode 码点输入。'bulk' 要求不设置 keyboardTypeDelay 或将其设为 0。如需延迟输入，请使用 'sequential'。默认值为 'legacy'。
• forceChromeSelectRendering: boolean —— 强制 select 元素使用 Chrome 的 base-select 样式，避免系统原生样式导致截图/元素提取不可见；需要 Puppeteer > 24.6.0。默认值为 true；如需关闭（例如旧版 Chrome/Puppeteer）可设为 false。
• customActions: DeviceAction[] —— 添加额外的自定义动作，让 Agent 可以调用你定义的领域特定动作。

使用说明

#PuppeteerBrowserAgent

当一个 Midscene Agent 需要管理 Puppeteer 浏览器内的页面切换时，使用 PuppeteerBrowserAgent。它绑定 browser 实例，维护一个 active page，并且可以选择自动跟随新打开的页面。

const agent = new PuppeteerBrowserAgent(browser, page, {
  autoFollowNewPage: true,
});

• 构造函数：new PuppeteerBrowserAgent(browser, page, options?) —— 你要显式指定初始 active page 时使用。
• 工厂方法：PuppeteerBrowserAgent.create(browser, options?) —— 你希望 Midscene 自动选择或创建初始 active page 时使用。它会优先使用 initialPage，否则复用浏览器里的第一个页面，或者创建一个新页面。
• initialPage: Page —— 工厂方法使用的初始 Puppeteer 页面。
• autoFollowNewPage: boolean —— 浏览器打开新页面时是否自动切换 active page，默认 false。
• newPageTimeout: number —— waitForNewPage 的超时时间，默认 5000。
• activePage: Page —— Browser Agent 当前控制的页面。
• pages() —— 列出绑定 browser 中的页面。
• newPage() —— 创建新页面并将其设为 active page。
• setActivePage(page: Page) —— 显式指定 Browser Agent 接下来控制哪个 Puppeteer 页面。
• waitForNewPage(action?, options?) —— 先注册监听，再执行 action，然后返回新页面，不会隐式切换 active page。可传入 { timeout: 毫秒数 } 覆盖本次调用的 newPageTimeout。

另请参阅

• 集成到 Puppeteer 获取安装、Fixture 与远程 CDP 配置。

#PlaywrightPageAgent / PlaywrightAgent

在 Playwright 浏览器中使用 Midscene 以支持带 AI 的测试或自动化流程。

PlaywrightPageAgent 绑定单个 Playwright Page。PlaywrightAgent 仍作为兼容别名保留。

导入

import { PlaywrightPageAgent } from '@midscene/web/playwright';

构造器

const agent = new PlaywrightPageAgent(page, {
  // 浏览器特有配置...
});

浏览器特有选项

• forceSameTabNavigation: boolean —— 强制在当前标签页内执行，默认 true。
• waitForNavigationTimeout、waitForNetworkIdleTimeout —— 默认等待策略的高级配置。
• enableTouchEventsInActionSpace: boolean —— 在动作空间里增加触摸手势（如滑动），用于需要触摸事件的页面，默认 false。
• keyboardTypeDelay: number —— 按键间延迟，单位为毫秒。取值必须是有限的非负数。在 'legacy' 模式下，Playwright 的 page.keyboard.type 负责处理正数延迟。默认值为 undefined。此时，Midscene 不传该选项，而是使用 Playwright 自身的默认值。通常无须配置。只有受控输入框在快速输入时丢字，才需要调大该值，例如 80。
• inputStrategy: 'legacy' | 'sequential' | 'bulk' —— Input 动作的默认文本输入策略。使用 'bulk' 可以一次插入完整字符串。使用 'sequential' 可以强制逐个 Unicode 码点输入。'bulk' 要求不设置 keyboardTypeDelay 或将其设为 0。如需延迟输入，请使用 'sequential'。默认值为 'legacy'。
• forceChromeSelectRendering: boolean —— 强制 select 元素使用 Chrome 的 base-select 样式，避免系统原生样式导致截图/元素提取不可见；需要 Playwright ≥ 1.52.0。默认值为 true；如需关闭（例如旧版 Chrome/Playwright）可设为 false。
• customActions: DeviceAction[] —— 添加额外的自定义动作，让 Agent 可以调用你定义的领域特定动作。

使用说明

#PlaywrightBrowserAgent

当一个 Midscene Agent 需要管理 Playwright browser context 内的页面切换时，使用 PlaywrightBrowserAgent。它绑定 browser context，维护一个 active page，并且可以选择自动跟随新打开的页面。

const agent = new PlaywrightBrowserAgent(context, page, {
  autoFollowNewPage: true,
});

• 构造函数：new PlaywrightBrowserAgent(context, page, options?) —— 你要显式指定初始 active page 时使用。
• 工厂方法：PlaywrightBrowserAgent.create(context, options?) —— 你希望 Midscene 自动选择或创建初始 active page 时使用。它会优先使用 initialPage，否则复用 context 里的第一个页面，或者创建一个新页面。
• initialPage: Page —— 工厂方法使用的初始 Playwright 页面。
• autoFollowNewPage: boolean —— context 打开新页面时是否自动切换 active page，默认 false。
• newPageTimeout: number —— waitForNewPage 的超时时间，默认 5000。
• activePage: Page —— Browser Agent 当前控制的页面。
• pages() —— 列出绑定 browser context 中的页面。
• newPage() —— 创建新页面并将其设为 active page。
• setActivePage(page: Page) —— 显式指定 Browser Agent 接下来控制哪个 Playwright 页面。
• waitForNewPage(action?, options?) —— 先注册监听，再执行 action，然后返回新页面，不会隐式切换 active page。可传入 { timeout: 毫秒数 } 覆盖本次调用的 newPageTimeout。

另请参阅

• 集成到 Playwright 获取安装、Fixture 用法和更多配置。

#Chrome Bridge Agent

Bridge mode 允许 Midscene 通过扩展控制当前桌面 Chrome 标签页，而无需再启动独立的自动化浏览器。

导入

import { AgentOverChromeBridge } from '@midscene/web/bridge-mode';

构造器

const agent = new AgentOverChromeBridge({
  allowRemoteAccess: false,
  // 其他桥接配置...
});

桥接配置

• closeNewTabsAfterDisconnect?: boolean —— 是否在销毁时自动关闭桥接创建的新标签页，默认 false。
• allowRemoteAccess?: boolean —— 是否允许远程机器连接，默认 false（监听 127.0.0.1）。
• host?: string —— 自定义 Bridge Server 的监听地址，优先级高于 allowRemoteAccess。
• port?: number —— Bridge Server 端口，默认 3766。
• enableWaterFlowAnimation?: boolean —— Midscene 控制页面时是否显示蓝色动态边框和鼠标指示，默认 true；如需截取不含视觉覆盖层的截图，可设为 false。
• keyboardTypeDelay?: number —— 按键间延迟，单位为毫秒。取值必须是有限的非负数。legacy Bridge 输入沿用零延迟的 CDP 行为。如需在转发 Unicode 码点时应用延迟，请将 inputStrategy 设为 'sequential'。
• inputStrategy?: 'legacy' | 'sequential' | 'bulk' —— 默认文本输入策略。'sequential' 逐个转发 Unicode 码点。'bulk' 只转发一次 insertText 操作，并且要求不设置 keyboardTypeDelay 或将其设为 0。默认值为 'legacy'。

完整安装与能力说明，见 Chrome 插件桥接模式。

使用说明

方法

connectCurrentTab()

function connectCurrentTab(options?: {
  forceSameTabNavigation?: boolean;
}): Promise<void>;

• options.forceSameTabNavigation（默认 true）会拦截新标签并在当前页打开，方便调试；若想保留新标签行为可设为 false，但需要为每个新标签创建新的 Agent。
• 连接当前激活标签页，成功后返回 Promise<void>，如果扩展未允许连接会报错。

connectNewTabWithUrl()

function connectNewTabWithUrl(
  url: string,
  options?: { forceSameTabNavigation?: boolean },
): Promise<void>;

• url —— 新标签页要打开的地址。
• options —— 与 connectCurrentTab 相同。
• 打开新标签并连接成功后返回 Promise<void>。

destroy()

function destroy(closeNewTabsAfterDisconnect?: boolean): Promise<void>;

• closeNewTabsAfterDisconnect —— 运行时覆盖构造器配置，为 true 时销毁时关闭桥接创建的新标签页。
• 包含通用 Agent 清理行为，其中包括报告收尾。
• 清理桥接连接、本地服务和 Agent 报告后，返回 Promise<void>。

另请参阅

• API 参考（通用） 查看共享的 Agent 方法。
• 桥接模式 了解扩展安装、执行顺序与 YAML 用法。

#Android（@midscene/android）

当你需要自定义设备行为、把 Midscene 接入框架，或排查 adb 问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等）的参数说明，请参考平台无关的 API 参考。

#Android Action Space（动作空间）

AndroidDevice 使用以下动作空间，Midscene Agent 在规划任务时可以使用这些操作：

• Tap —— 点击元素。
• DoubleClick —— 双击元素。
• Input —— 输入文本，支持 replace/typeOnly/clear 模式（append 是 typeOnly 的已废弃别名）。支持可选参数 autoDismissKeyboard、keyboardTypeDelay 和 inputStrategy。
• Scroll —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
• DragAndDrop —— 从一个元素拖拽到另一个元素。
• KeyboardPress —— 按下指定键位。
• LongPress —— 长按目标元素，可选自定义时长。
• PullGesture —— 上拉或下拉（如下拉刷新），可选距离与持续时间。
• Pinch —— 双指缩放手势。scale > 1 放大，scale < 1 缩小。
• ClearInput —— 清空输入框内容。
• Launch —— 打开网页或 package/.Activity。
• Terminate —— 按包名强制停止应用。
• RunAdbShell —— 执行原始 adb shell 命令。此动作默认启用。将 exposeRunAdbShellAction 设为 false，可从动作空间中移除此动作。
• AndroidBackButton —— 触发系统返回。
• AndroidHomeButton —— 回到桌面。
• AndroidRecentAppsButton —— 打开多任务/最近应用。

#AndroidDevice

创建一个可供 AndroidAgent 驱动的 adb 设备实例。

导入

import {
  AndroidDevice,
  getConnectedDevices,
  getConnectedDevicesWithDetails,
} from '@midscene/android';

构造函数

const device = new AndroidDevice(deviceId, {
  // 设备参数...
});

设备选项

• deviceId: string —— 来自 adb devices 或 getConnectedDevices() 的值。
• autoDismissKeyboard?: boolean —— 输入完成后自动隐藏键盘，默认 true。
• keyboardDismissStrategy?: 'esc-first' | 'back-first' —— 关闭键盘的顺序，默认 'esc-first'。
• keyboardTypeDelay?: number —— 按键间延迟，单位为毫秒。取值必须是有限的非负数。在 'legacy' 模式下，正数延迟会让原生 input text 路径逐个 Unicode 码点输入。为兼容旧行为，yadb 仍会忽略该选项。如需拆分 yadb 输入，请将 inputStrategy 设为 'sequential'。
• inputStrategy?: 'legacy' | 'sequential' | 'bulk' —— Input 动作的默认文本输入策略。'sequential' 会针对每个 Unicode 码点调用一次 ADB 或 yadb。所选 IME 支持时，'bulk' 只调用一次底层文本接口。'bulk' 要求不设置 keyboardTypeDelay 或将其设为 0。如需延迟输入，请使用 'sequential'。默认值为 'legacy'。
• androidAdbPath?: string —— adb 可执行文件的自定义路径。
• remoteAdbHost?: string / remoteAdbPort?: number —— 指向远程 adb server。
• imeStrategy?: 'always-yadb' | 'yadb-for-non-ascii' —— 控制何时调用 yadb 进行文本输入，默认 'yadb-for-non-ascii'。
  • 'yadb-for-non-ascii'（默认）—— 对 Unicode 字符（包括 Latin Unicode 如 ö、é、ñ）、中文、日文以及格式化符号（如 %s、%d）使用 yadb。纯 ASCII 文本使用更快的原生 adb input text。
  • 'always-yadb' —— 对所有文本输入始终使用 yadb，提供最大兼容性，但对纯 ASCII 文本稍慢。
• screenshotStrategy?: 'auto' | 'always-yadb' —— 控制截图方式，默认 'auto'。
  • 'auto'（默认）—— 先尝试 adb.takeScreenshot，失败后回退到 shell screencap；若 screencap 执行失败，则改用 yadb 工具。scrcpy 仅当 scrcpyConfig.enabled 开启时才会优先尝试。该策略不会分析截图内容：即使某个截图方法执行成功但返回全黑图片，也不会自动切换到 yadb；只有当前一种截图方法执行失败时，才会尝试下一种方法。
  • 'always-yadb' —— 绕过默认的 auto 截图流程（adb.takeScreenshot、screencap，以及开启时的 scrcpy），直接使用 yadb 截图。适用于 screencap 对安全页面（FLAG_SECURE）截出黑屏、但 yadb 能正常截取的场景——能否截取取决于 Android 版本、ROM、root/hook 环境和设备配置，请以实际设备测试结果为准。yadb 只能截取默认显示器（displayId=0）；如果同时设置该策略和非零 displayId，Midscene 会抛出错误。也可通过环境变量 MIDSCENE_ANDROID_SCREENSHOT_STRATEGY=always-yadb 设置。
• displayId?: number —— 在设备镜像多个屏幕时，选择特定虚拟屏幕。
• exposeRunAdbShellAction?: boolean —— 是否在动作空间中暴露内置的 RunAdbShell 动作。默认值：true。设为 false 后，AI 规划器、YAML 脚本和 agent.runAdbShell() 都无法执行 ADB shell 命令。
• customActions?: DeviceAction[] —— 添加额外的自定义动作，让 Agent 可以调用你定义的领域特定动作。
• screenshotResizeScale?: number —— 已废弃。 此选项已移除，不再生效。如需控制发送给 AI 模型的截图尺寸，请使用 AgentOpt 中的 screenshotShrinkFactor。
• minScreenshotBufferSize?: number —— 截图 buffer 大小校验阈值，单位为字节；低于该值的 buffer 会被视为截图采集失败或已损坏。默认 1024（1KB）。设置为 0 仅跳过此大小校验；Midscene 仍会拒绝空 buffer 和无效图片格式。
• alwaysRefreshScreenInfo?: boolean —— 每一步都重新查询旋转角度与屏幕尺寸，默认 false。

scrcpy 配置和状态方法

• scrcpyConfig?: object —— scrcpy 截图配置，默认关闭。

  • enabled?: boolean —— 是否启用 scrcpy 截图，默认 false。
  • maxSize?: number —— 截图的最大宽度或高度。scrcpy 暂时不可用时，ADB/yadb 回退截图也会应用相同限制，避免规划和报告中的图片恢复为设备原始分辨率。必须使用非负整数；默认 0，表示不缩放。
  • videoBitRate?: number —— scrcpy H.264 编码码率，单位为 bps，默认 100000000。调整该值是在编码带宽和截图细节之间取舍；只有独立的链路测量表明有需要时才应调优，并验证识别质量，不能仅凭 freshness 超时告警调整。
  • idleTimeoutMs?: number —— 空闲连接的断开时间，单位为毫秒，默认 30000；设为 0 时禁用。
  • videoResetFrameTimeoutMs?: number —— scrcpy 接受流内视频重置后，等待新鲜关键帧的时间，单位为毫秒。必须使用正整数，默认 800。仅当设备的 display capture 重启长尾更慢时再增大该值。

• device.getScrcpyStatus() —— 返回 enabled、connected、lastError 和 retryAfter。

• device.retryScrcpy(): Promise<void> —— 跳过冷却时间，立即重试 scrcpy 连接。

使用说明

• 可以使用 getConnectedDevices() 发现设备，udid 与 adb devices 输出一致。
• 可以使用 remoteAdbHost/remoteAdbPort 连接远程 adb；如果 adb 不在 PATH 中，可设置 androidAdbPath。

destroy()

function destroy(): Promise<void>;

释放 AndroidDevice 持有的资源，其中包括正在运行的 scrcpy 连接。同时，清除 ADB 状态。该方法可以重复调用。调用完成后，这个 Device 实例不能再执行 ADB 命令，但物理设备仍与 ADB server 保持连接。

调用 AndroidAgent.destroy() 时，会自动执行该方法。每个 AndroidDevice 实例只属于一个 AndroidAgent。

#AndroidAgent

将 Midscene 的 AI 规划能力绑定到 AndroidDevice，实现 UI 自动化。

导入

import { AndroidAgent } from '@midscene/android';

构造函数

const agent = new AndroidAgent(device, {
  // 通用 Agent 参数...
});

Android 特有选项

• appNameMapping?: Record<string, string> —— 将友好的应用名称映射到包名。当你在 launch(target) 里传入应用名称时，Agent 会在此映射中查找对应的包名；若未找到映射，则按原样尝试启动 target。
• 其余字段与通用构造参数一致，包括 generateReport、reportFileName、aiContexts、aiActContext、modelConfig、cache、createOpenAIClient 和 onTaskStartTip 等。

使用说明

Android 特有方法

agent.launch()

启动网页或原生 Android activity/package。

function launch(target: string): Promise<void>;

• target: string —— 可以是网页 URL，也可以是 package/.Activity 形式的字符串，例如 com.android.settings/.Settings，也可以是应用包名、URL 或应用名称。若传入应用名称且在 appNameMapping 中存在映射，将自动解析为对应包名；若未找到映射，则直接按 target 启动。

agent.runAdbShell()

通过连接的设备运行原始的 adb shell 命令。传入的内容只需要包含 shell 命令本身，不要包含 adb shell 前缀。

function runAdbShell(command: string, opt?: { timeout?: number }): Promise<string>;

• command: string —— 原样传递给 adb shell 的命令。例如要传 input tap 100 200，不要传 adb shell input tap 100 200。
• opt.timeout?: number —— 可选的命令执行超时时间，单位为毫秒。

此方法会调用 RunAdbShell 动作。创建 AndroidDevice 时，如果将 exposeRunAdbShellAction 设为 false，此方法将不可用。

const result = await agent.runAdbShell('dumpsys battery', { timeout: 60 * 1000 });
console.log(result);

await agent.runAdbShell('input tap 100 200');

agent.terminate()

终止（强制停止）正在运行的 Android 应用。

function terminate(uri: string): Promise<void>;

• uri: string —— 应用包名、appNameMapping 中的应用名称，或 package/.Activity（仅使用包名部分）。

await agent.terminate('com.android.settings');

导航辅助

• agent.back(): Promise<void> —— 触发 Android 系统的返回操作。
• agent.home(): Promise<void> —— 返回桌面。
• agent.recentApps(): Promise<void> —— 打开多任务/最近应用界面。

#Android 工厂函数和工具

agentFromAdbDevice()

从任意已连接的 adb 设备创建 AndroidAgent。

function agentFromAdbDevice(
  deviceId?: string,
  opts?: AndroidAgentOpt & AndroidDeviceOpt,
): Promise<AndroidAgent>;

• deviceId?: string —— 连接特定设备；留空表示使用“第一个可用设备”。
• opts?: AndroidAgentOpt & AndroidDeviceOpt —— Agent 选项与 AndroidDevice 设置。未传 deviceId 时，Midscene 会通过 adb 自动发现设备。可在 opts 中设置 androidAdbPath、remoteAdbHost 和 remoteAdbPort，指定用于发现和连接设备的 adb。

getConnectedDevices()

列举 Midscene 可驱动的 adb 设备。

function getConnectedDevices(
  deviceOptions?: AndroidDeviceOpt,
): Promise<Array<{
  udid: string;
  state: string;
  port?: number;
}>>;

deviceOptions 是可选参数。省略时，Midscene 使用默认 adb 配置。通过 androidAdbPath 指定 adb 可执行文件，或通过 remoteAdbHost 和 remoteAdbPort 连接远程 adb server：

const devices = await getConnectedDevices({
  androidAdbPath: '/absolute/path/to/adb',
  remoteAdbHost: '192.168.1.10',
  remoteAdbPort: 5038,
});

getConnectedDevicesWithDetails()

与 getConnectedDevices() 功能类似，并额外返回设备品牌、型号、分辨率和屏幕密度。无法获取的字段为 undefined。

function getConnectedDevicesWithDetails(
  deviceOptions?: AndroidDeviceOpt,
): Promise<Array<{
  udid: string;
  state: string;
  port?: number;
  model?: string;
  brand?: string;
  resolution?: string;
  density?: number;
}>>;

相关阅读

• Android 快速开始 获取搭建与脚本示例。

#iOS（@midscene/ios）

当你需要自定义 iOS 设备行为、将 Midscene 接入依赖 WebDriverAgent 的工作流，或排查 WDA 请求问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等），请参考平台无关的 API 参考。

#iOS Action Space（动作空间）

IOSDevice 使用以下动作空间，Midscene Agent 在规划任务时可以使用这些操作：

• Tap —— 点击元素。
• DoubleClick —— 双击元素。
• Input —— 输入文本，支持 replace/typeOnly/clear 模式（append 是 typeOnly 的已废弃别名）。支持可选参数 autoDismissKeyboard、keyboardTypeDelay 和 inputStrategy。
• Scroll —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
• DragAndDrop —— 从一个元素拖拽到另一个元素。
• KeyboardPress —— 按下指定键位。
• LongPress —— 长按目标元素，可选自定义时长。
• Pinch —— 双指缩放手势。scale > 1 放大，scale < 1 缩小。
• ClearInput —— 清空输入框内容。
• Launch —— 打开网页、Bundle ID 或 URL Scheme。
• Terminate —— 通过 Bundle ID 关闭正在运行的 iOS 应用。
• RunWdaRequest —— 直接调用 WebDriverAgent REST 接口。
• IOSHomeButton —— 执行 iOS 系统 Home 操作。
• IOSAppSwitcher —— 打开 iOS 多任务视图。

#IOSDevice

创建一个由 WebDriverAgent 支撑、供 IOSAgent 驱动的设备连接。

导入

import { IOSDevice } from '@midscene/ios';

构造函数

const device = new IOSDevice({
  // 设备参数...
});

设备选项

• wdaPort?: number —— WebDriverAgent 端口，默认 8100。
• wdaHost?: string —— WebDriverAgent host，默认 'localhost'。
• iOSDeviceClassOverride?: string —— 使用 agentFromWebDriverAgent() 或 iOS Playground 时替换默认 IOSDevice 的 npm module path。目标模块必须导出 IOSDevice class 或 default class。
• sessionId?: string —— 复用已有的 WebDriverAgent session ID。传入后，Midscene 不再创建新的 WDA session；清理时只会从这个外部 WebDriver session 分离，不会删除它。
• wdaMjpegPort?: number —— WDA MJPEG 服务端口，用于实时画面流，默认 9100。
• wdaMjpegFrameSource?: { enabled?: boolean } —— 使用 WDA 的 MJPEG stream 作为 agent.startObserving() 的连续帧源。默认关闭；关闭时，观察逻辑会退回到连续调用 screenshotBase64()。
• autoDismissKeyboard?: boolean —— 文本输入后自动隐藏键盘，默认 true。
• keyboardTypeDelay?: number —— 按键间延迟，单位为毫秒。取值必须是有限的非负数。设为正数后，legacy 输入会通过 WDA 的 /wda/keys 接口逐个 Unicode 码点执行。适用于输入框在快速输入下丢字的场景。
• inputStrategy?: 'legacy' | 'sequential' | 'bulk' —— Input 动作的默认文本输入策略。'sequential' 会针对每个 Unicode 码点调用一次 WDA。'bulk' 只调用一次 WDA 文本接口，并且要求不设置 keyboardTypeDelay 或将其设为 0。如需延迟输入，请使用 'sequential'。默认值为 'legacy'。
• customActions?: DeviceAction<any>[] —— 添加额外的自定义动作，让 Agent 可以调用你定义的领域特定动作。

使用说明

• 请确认已开启开发者模式且 WDA 能访问设备；真机转发端口时可借助 iproxy。
• 通过 wdaHost/wdaPort 可指向远程设备或自建的 WDA。
• 多设备并发时，请为每个设备设置不同的 wdaPort 和 wdaMjpegPort，避免 WDA 命令和 MJPEG stream 端口冲突。
• 通用交互方法请查阅 API 参考（通用）。

destroy()

function destroy(): Promise<void>;

尝试停止 MJPEG frame source、删除 WebDriverAgent session，并停止 WDA manager。 清理失败时会记录日志，但 Promise 不会因此被拒绝。该方法可以重复调用。调用完成 后，不能再使用这个 IOSDevice 实例。