使用 YAML 格式的自动化脚本

兼容保留，建议迁移到 Midscene Test

“旧版 YAML”，特指由 @midscene/cli 提供的 YAML 自动化协议：工作流顶层使用 tasks，每个 task 使用 flow，平台和 Agent 等运行配置通常也写在 YAML 中，并通过 midscene 命令或包含 files、setup、concurrent 等字段的 YAML 批配置运行。

旧链路已进入维护状态：继续保证现有项目兼容，并处理必要的问题，但不再新增语法、能力、配置项或 CLI 参数。已有用例、批配置、目录结构和 midscene 命令可以保持不变；升级后会通过共享执行内核运行，并生成新的 Test 报告页面。新项目、新增用例和后续能力建设推荐直接使用 Midscene Test。

旧文件和 YAML 批配置使用 midscene，原生 cases/steps 文件和 TypeScript 项目配置使用 midscene-test。两种格式可以放在同一个仓库的不同目录中，但不能在同一个文件或同一次命令中混用。先阅读 Midscene Test 概览，再按照迁移到 Midscene Test转换字段并切换命令。

在大多数情况下，开发者编写自动化脚本只是为了执行一些简单流程，比如检查某些内容是否出现，或者验证某个关键用户路径是否可用。此时维护一个大型测试项目会显得毫无必要。

⁠Midscene 提供了一种基于 .yaml 文件的自动化测试方法，这有助于你专注于编写流程，而不是测试框架。

这里有一个示例，通过阅读它的内容，你应该已经理解了它的工作原理。

page:
  url: https://www.bing.com

tasks:
  - name: 搜索天气
    flow:
      - ai: 搜索 "今日天气"
      - sleep: 3000

  - name: 检查结果
    flow:
      - aiAssert: 结果中展示了天气信息

样例项目

你可以在这里找到使用 YAML 脚本做自动化的样例项目

配置 AI 模型服务

下面以豆包 Seed 2.1 Turbo 为例：

export MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export MIDSCENE_MODEL_API_KEY="your-api-key"
export MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
export MIDSCENE_MODEL_FAMILY="doubao-seed"

将 your-api-key 替换为你的 API Key。

如需使用千问（Qwen）、GLM、Gemini 或 GPT-5 等其他模型，请参考使用模型 API Key。

全部配置项请参考模型配置。

如果需要通过命令行执行 YAML 工作流，请查看 YAML 脚本运行器，了解安装、.env 支持以及 midscene 命令的用法。

脚本文件结构

脚本文件使用 YAML 格式来描述自动化任务。它定义了要操作的目标（如网页或安卓应用）以及一系列要执行的步骤。

一个标准的 .yaml 脚本文件包含 page、browser、web、android、ios、harmony 或 computer 部分配置环境，可选的 agent 部分配置 AI Agent 行为，以及一个 tasks 部分来定义自动化任务。

page:
  url: https://www.bing.com

# tasks 部分定义了要执行的一系列步骤
tasks:
  - name: 搜索天气
    flow:
      - ai: 搜索 "今日天气"
      - sleep: 3000
      - aiAssert: 结果显示天气信息

使用 page: 表示 page-level Agent。使用 browser: 表示一个 Agent 管理 browser 和它的 active page。web: 仍作为兼容入口保留；web.mode: browser 会映射到 BrowserAgent，普通 web: 会映射到 PageAgent。不要在同一份脚本里同时使用 page、browser、web 或已废弃的 target。

`agent` 部分

agent 部分用于配置 AI Agent 的行为和测试报告相关选项。所有字段都是可选的。

# AI agent 配置
agent:
  # 测试标识符，用于报告和缓存识别，可选
  testId: <string>

  # 报告组名称，可选
  groupName: <string>

  # 报告组描述，可选
  groupDescription: <string>

  # 是否生成测试报告，可选，默认 true
  generateReport: <boolean>

  # 是否自动打印报告消息，可选，默认 true
  autoPrintReportMsg: <boolean>

  # 自定义报告文件名，可选
  reportFileName: <string>

  # AI 最大重规划循环次数，可选，默认 20（UI-TARS 模型为 40）
  replanningCycleLimit: <number>

  # 提供给 AI 的补充信息，可选；default 是共享的缺省回退值
  aiContexts:
    default: <string>
    aiAct: <string>
    aiQuery: <string>

  # 缓存配置，可选
  cache:
    # 缓存策略，可选，可选值：'read-only' | 'read-write' | 'write-only'
    strategy: <string>
    # 缓存 ID，必填
    id: <string>

Agent 配置说明

适用环境：Web、iOS 和 Android 环境都支持 agent 配置
testId 优先级：CLI 参数 > YAML agent.testId > 文件名
aiContexts：提供给 AI 的补充信息，例如业务事实、规则、约束或输出要求。如果配置了 default，仅当本次调用和对应 API 都没有自己的 context 时才使用它。单次调用的 context 覆盖 API 级值，API 级值覆盖 default，这些值不会自动合并；空字符串会显式清空继承的用户 context。关于上下文知识的编写和传入方式，参见为 GUI Agent 补充应用知识。
aiActContext / aiActionContext：aiContexts.aiAct 的已废弃兼容字段，均仍受支持。解析规则为 aiContexts.aiAct ?? aiActContext ?? aiActionContext；空字符串也会覆盖低优先级的兼容字段。新 YAML 脚本请使用 aiContexts.aiAct。
缓存配置：详细用法请参考缓存功能文档

使用示例

# agent 配置，适用于所有环境
agent:
  testId: "checkout-test"
  groupName: "E2E 测试套件"
  groupDescription: "完整的购物流程测试"
  generateReport: true
  autoPrintReportMsg: false
  reportFileName: "checkout-report"
  replanningCycleLimit: 30
  aiContexts:
    default: "页面中的价格单位是美元。"
    aiAct: "如果出现弹窗，点击同意。如果出现登录页面，跳过它。"
  cache:
    id: "checkout-cache"
    strategy: "read-write"

# iOS 环境配置
ios:
  launch: https://www.bing.com
  wdaPort: 8100

# 或 Android 环境配置
android:
  deviceId: s4ey59
  launch: https://www.bing.com

tasks:
  - name: 搜索天气
    flow:
      - ai: 搜索 "今日天气"
      - aiAssert: 结果显示天气信息

Web target 部分

推荐的 page-level target：

page:
  url: https://example.com

推荐的 browser-level target：

browser:
  url: https://example.com
  autoFollowNewPage: true

兼容写法：

web:
  mode: browser
  url: https://example.com
  autoFollowNewPage: true

共享配置：

page:
  # 访问的 URL，必填。如果提供了 `serve` 参数，则提供相对路径
  url: <url>

  # 在本地路径下启动一个静态服务，可选
  serve: <root-directory>

  # 浏览器 UA，可选
  userAgent: <ua>

  # 浏览器视口宽度，可选，默认 1440
  viewportWidth: <width>

  # 浏览器视口高度，可选，默认 800
  viewportHeight: <height>

  # 浏览器设备像素比，可选，默认跟随系统
  deviceScaleFactor: <scale>

  # JSON 格式的浏览器 Cookie 文件路径，可选
  cookie: <path-to-cookie-file>

  # Chrome 下载目录（仅 Puppeteer 模式），可选
  # 相对路径会基于当前工作目录解析
  # bridgeMode 不支持该选项
  downloadPath: <path-to-download-directory>

  # 随每个请求发送的额外 HTTP 请求头（仅 Puppeteer 模式），可选
  # 适用于服务器会校验自定义请求头的场景
  # 值必须是字符串；像 true、false、纯数字这类会被 YAML 解析为非字符串的值需加引号，如 "true"
  extraHTTPHeaders:
    X-Custom-Token: my-token
    Accept-Language: en-US

  # Puppeteer 模式下等待网络空闲的策略，可选
  # `timeout` 会作用于初始打开 YAML 中的 `web.url`，以及后续 `aiTap`、`aiInput` 等操作后的等待
  # `continueOnNetworkIdleError` 只作用于初始打开 YAML 中的 `web.url`
  waitForNetworkIdle:
    # 每次网络空闲等待的超时时间，可选，默认 2000ms
    timeout: <ms>
    # 初始打开 YAML 中的 `web.url` 时，如果网络空闲等待超时，是否继续执行，可选，默认 true
    # 后续脚本执行中的等待即使超时也总是继续执行
    continueOnNetworkIdleError: <boolean>

  # 输出 aiQuery/aiAssert 结果的 JSON 文件路径，可选
  output: <path-to-output-file>

  # 是否保存日志内容到 JSON 文件，可选，默认 `false`。如果为 true，保存到 `unstableLogContent.json` 文件中。如果为字符串，则保存到该字符串指定的路径中。日志内容的结构可能会在未来发生变化。
  unstableLogContent: <boolean | path-to-unstable-log-file>

  # 是否限制页面在当前 tab 打开，可选，默认 true
  # 仅 page mode 可用，不要与 `browser:` 或 `web.mode: browser` 同时使用
  forceSameTabNavigation: <boolean>

  # BrowserAgent 是否自动继续在新打开的页面中执行，可选，默认 false
  # 仅 browser mode 可用。请使用 `browser:` 或 `web.mode: browser`
  autoFollowNewPage: <boolean>

  # CDP 连接端点，可选。设置后通过 CDP 连接到已有浏览器实例，而非启动新浏览器。
  # 与 bridgeMode 互斥，不可同时使用。
  cdpEndpoint: ws://localhost:9222/devtools/browser

  # 桥接模式，可选，默认 false，可以为 'newTabWithUrl' 或 'currentTab'。更多详情请参阅后文
  bridgeMode: false | 'newTabWithUrl' | 'currentTab'

  # 是否在桥接断开时关闭新创建的标签页，可选，默认 false
  closeNewTabsAfterDisconnect: <boolean>

  # 是否忽略 HTTPS 证书错误，可选，默认 false
  acceptInsecureCerts: <boolean>

  # 自定义 Chrome 启动参数（仅 Puppeteer 模式，不支持桥接模式），可选
  # 用于自定义 Chrome 浏览器行为，例如禁用第三方 Cookie 阻止
  # ⚠️ 安全警告：某些参数（如 --no-sandbox、--disable-web-security）可能降低浏览器安全性
  # 仅在受控的测试环境中使用
  chromeArgs:
    - '--disable-features=ThirdPartyCookiePhaseout'
    - '--disable-features=SameSiteByDefaultCookies'
    - '--window-size=1920,1080'

Chrome Bridge

先完成 Chrome Bridge 环境配置。在 web 中设置 bridgeMode：

配置	行为
`newTabWithUrl`	使用 `url` 创建并连接新标签页
`currentTab`	连接当前激活标签页，忽略 `url`

web:
  url: https://example.com
  bridgeMode: newTabWithUrl
  closeNewTabsAfterDisconnect: true

tasks:
  - name: Check the page
    flow:
      - aiAssert: The page shows Example Domain

使用 YAML 脚本运行器运行，首次连接时在插件中确认授权。closeNewTabsAfterDisconnect 默认 false；设为 true 时清理桥接创建的新标签页，不关闭连接前已有的标签页。

Bridge 模式与 cdpEndpoint、web.mode: browser 互斥。它复用桌面浏览器配置，以下字段会被忽略：

userAgent
viewportWidth / viewportHeight
deviceScaleFactor
waitForNetworkIdle
cookie
extraHTTPHeaders
downloadPath
chromeArgs

`android` 部分

android:
  # 设备 ID，可选，默认使用第一个连接的设备
  deviceId: <device-id>

  # 启动 URL，可选，默认使用设备当前页面
  launch: <url>

  # 输出 aiQuery/aiAssert 结果的 JSON 文件路径，可选
  output: <path-to-output-file>

  # 其他 AndroidDevice 构造函数支持的所有选项
  # 例如：androidAdbPath, remoteAdbHost, remoteAdbPort,
  # imeStrategy, displayId, autoDismissKeyboard, keyboardDismissStrategy,
  # keyboardTypeDelay, minScreenshotBufferSize, alwaysRefreshScreenInfo 等
  # 完整配置项请参考 AndroidDevice 的构造函数文档

查看完整的 Android 配置项

YAML 脚本现在支持 AndroidDevice 构造函数的所有配置选项。完整的配置项列表请参考 Android API 参考中的 AndroidDevice。

Android 平台特定动作

Android 平台提供了一些特定的动作，可以在 YAML 脚本的 flow 中使用：

runAdbShell - 执行 ADB Shell 命令

在 Android 设备上执行 ADB shell 命令。传入的内容只需要包含 shell 命令本身，不要包含 adb shell 前缀。如需设置命令超时，请将 timeout 作为 runAdbShell 的同级字段。

android:
  deviceId: 'test-device'

tasks:
  - name: 清除应用数据
    flow:
      - runAdbShell: 'pm clear com.example.app'

  - name: 获取电池信息
    flow:
      - runAdbShell: 'dumpsys battery'

  - name: 点击屏幕坐标
    flow:
      - runAdbShell: 'input tap 100 200'

  - name: 执行带超时的命令
    flow:
      - runAdbShell: 'dumpsys activity services'
        timeout: 60000

常用 ADB Shell 命令：

pm clear <package> - 清除应用数据
dumpsys battery - 获取电池信息
dumpsys window - 获取窗口信息
settings get secure android_id - 获取设备 ID
input tap <x> <y> - 点击屏幕坐标
input keyevent <keycode> - 发送按键事件

launch - 启动应用或 URL

启动 Android 应用或打开 URL。

android:
  deviceId: 'test-device'

tasks:
  - name: 启动设置应用
    flow:
      - launch: com.android.settings

  - name: 打开网页
    flow:
      - launch: https://www.example.com

terminate - 终止应用

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

android:
  deviceId: 'test-device'

tasks:
  - name: 终止设置应用
    flow:
      - terminate: com.android.settings

`ios` 部分

ios:
  # WebDriverAgent 端口，可选，默认 8100
  wdaPort: <port>

  # WebDriverAgent 主机地址，可选，默认 localhost
  wdaHost: <host>

  # 网关带路径前缀时，用 wdaBaseUrl 替代 wdaHost/wdaPort。
  # 同时设置 wdaBaseUrl 与 wdaHost 或 wdaPort 会报错。
  # wdaBaseUrl: <url>

  # 可单独设置 MJPEG 流地址，包括网关路径；不能与 wdaMjpegPort 同时设置。
  # wdaMjpegUrl: <url>

  # 本地 MJPEG 流端口，可选。与 wdaMjpegUrl 二选一。
  # wdaMjpegPort: <port>

  # 是否自动关闭键盘，可选，默认 false
  autoDismissKeyboard: <boolean>

  # 启动 URL 或应用包名，可选，默认使用设备当前页面
  launch: <url-or-bundle-id>

  # 输出 aiQuery/aiAssert 结果的 JSON 文件路径，可选
  output: <path-to-output-file>

  # 是否保存日志内容到 JSON 文件，可选，默认 `false`。如果为 true，保存到 `unstableLogContent.json` 文件中。如果为字符串，则保存到该字符串指定的路径中。日志内容的结构可能会在未来发生变化。
  unstableLogContent: <boolean | path-to-unstable-log-file>

  # 其他 IOSDevice 构造函数支持的所有选项
  # 完整配置项请参考 IOSDevice 的构造函数文档

连接带路径前缀的网关时，只设置 wdaBaseUrl。MJPEG 流可以使用单独的地址：

ios:
  wdaBaseUrl: ${WDA_BASE_URL}
  wdaMjpegUrl: ${WDA_MJPEG_URL}

运行脚本前，请设置这两个环境变量。Studio Recorder 导出的 YAML 也引用环境变量。这样，网关路径和访问令牌不会写入文件。

查看完整的 iOS 配置项

YAML 脚本现在支持 IOSDevice 构造函数的所有配置选项。完整的配置项列表请参考 iOS API 参考中的 IOSDevice。

iOS 平台特定动作

iOS 平台提供了一些特定的动作，可以在 YAML 脚本的 flow 中使用：

runWdaRequest - 执行 WebDriverAgent API 请求

在 iOS 设备上直接执行 WebDriverAgent API 请求。

ios:
  launch: 'com.apple.mobilesafari'

tasks:
  - name: 通过 WDA 按下主屏幕按钮
    flow:
      - runWdaRequest:
          method: POST
          endpoint: /session/test/wda/pressButton
          data:
            name: home

  - name: 获取设备信息
    flow:
      - runWdaRequest:
          method: GET
          endpoint: /wda/device/info

参数：

method（字符串，必需）：HTTP 方法（GET、POST、DELETE 等）
endpoint（字符串，必需）：WebDriverAgent API 端点
data（任意类型，可选）：请求体数据

常用 WebDriverAgent 端点：

/wda/screen - 获取屏幕信息
/wda/device/info - 获取设备信息
/session/{sessionId}/wda/pressButton - 按硬件按钮
/session/{sessionId}/wda/apps/launch - 启动应用
/session/{sessionId}/wda/apps/terminate - 终止应用
/session/{sessionId}/wda/apps/activate - 激活应用

launch - 启动应用或 URL

启动 iOS 应用或打开 URL。

ios:
  wdaPort: 8100

tasks:
  - name: 启动设置应用
    flow:
      - launch: com.apple.Preferences

  - name: 打开网页
    flow:
      - launch: https://www.example.com

terminate - 终止应用

通过 Bundle ID 终止（关闭）正在运行的 iOS 应用。

ios:
  wdaPort: 8100

tasks:
  - name: 终止设置应用
    flow:
      - terminate: com.apple.Preferences

`harmony` 部分

harmony 部分用于通过 HDC 进行 HarmonyOS 设备自动化。设备通过 hdc 连接,运行前请先确认 hdc list targets 能列出你的设备。

harmony:
  # 要连接的 HarmonyOS 设备 ID,可选,默认使用第一个已连接的设备。
  deviceId: <device-id>

  # 要启动的应用,可选,默认使用设备当前屏幕。
  launch: <bundle-name>

  # HDC 可执行文件路径,可选。
  hdcPath: <path-to-hdc>

  # 输入完成后是否自动收起键盘,可选,默认为 true。
  autoDismissKeyboard: <boolean>

  # 应用名到 bundle name 或显式 bundle/Ability 目标的自定义映射,可选。
  # 用户提供的映射优先级高于默认映射。
  appNameMapping:
    <app-name>: <bundle-name-or-bundle/ability>

  # 用于输出 aiQuery/aiAssert 结果的 JSON 文件路径,可选。
  output: <path-to-output-file>

  # HarmonyDevice 构造函数支持的其他所有选项

HarmonyOS 平台专属动作

launch - 启动应用

通过 bundle name 或显式 bundle/Ability 目标启动 HarmonyOS 应用。

harmony:
  deviceId: 'test-device'
  appNameMapping:
    视频: com.example.video/PhoneAbility

tasks:
  - name: 启动应用
    flow:
      - launch: 视频

terminate - 终止应用

通过 Bundle 名或映射的应用名终止(强制停止)正在运行的 HarmonyOS 应用。

harmony:
  deviceId: 'test-device'

tasks:
  - name: 终止应用
    flow:
      - terminate: com.example.app

runHdcShell - 执行 HDC Shell 命令

在 HarmonyOS 设备上执行 HDC shell 命令。

harmony:
  deviceId: 'test-device'

tasks:
  - name: 导出窗口信息
    flow:
      - runHdcShell:
          command: 'hidumper -s WindowManagerService -a'

`computer` 部分

computer 部分用于 PC 桌面自动化。它允许你控制桌面环境，包括鼠标移动、键盘输入和屏幕查询。

computer:
  # 使用的显示器 ID，可选，默认使用主显示器
  displayId: <display-id>

  # 输出 aiQuery/aiAssert 结果的 JSON 文件路径，可选
  output: <path-to-output-file>

使用示例

computer: {}

tasks:
  - name: 打开浏览器并搜索
    flow:
      - aiAct: 按下 Cmd+Space
      - sleep: 500
      - aiAct: 输入 "Safari" 并按回车
      - sleep: 2000
      - aiAct: 按下 Cmd+L 聚焦地址栏
      - aiAct: 输入 "https://www.bing.com"
      - aiAct: 按下回车
      - sleep: 3000
      - aiAct: 在搜索框中输入 "今日天气" 并按回车
      - aiAssert: 结果显示天气信息

平台说明

上面的示例脚本使用 macOS 命令。对于 Windows，请修改脚本：

使用 按下 Windows 键 代替 按下 Cmd+Space
使用 输入 "Chrome" 代替 输入 "Safari"
使用 按下 Ctrl+L 代替 按下 Cmd+L

`tasks` 部分

tasks 部分是一个数组，定义了脚本执行的步骤。记得在每个步骤前添加 - 符号，表明这些步骤是个数组。

flow 部分的接口与 API 几乎相同，除了一些参数的嵌套层级。

tasks:
  - name: <name>
    continueOnError: <boolean> # 可选，错误时是否继续执行下一个任务，默认 false
    flow:
      # 自动规划(Auto Planning, .ai)
      # ----------------

      # 执行一个交互，`ai` 是 `aiAct` 的简写方式
      - ai: <prompt>
        cacheable: <boolean> # 可选，当启用 [缓存功能](./caching.mdx) 时,是否允许缓存当前 API 调用结果。默认值为 True
        deepThink: <boolean> # 可选，引导 aiAct 注重任务拆解，并将任务 Planning 和 UI 元素定位拆解为不同的模型调用。默认值为 false。
        deepLocate: <boolean> # 可选，在 aiAct 执行过程中为 UI 元素定位开启深度定位。默认值为 false。

      # 这种用法与 `ai` 相同
      # 注意：在之前版本中也被写作 `aiAction`，当前版本兼容两种写法
      - aiAct: <prompt>
        cacheable: <boolean> # 可选，当启用 [缓存功能](./caching.mdx) 时，是否允许缓存当前 API 调用结果。默认值为 True
        deepThink: <boolean> # 可选，引导 aiAct 注重任务拆解，并将任务 Planning 和 UI 元素定位拆解为不同的模型调用。默认值为 false。
        deepLocate: <boolean> # 可选，在 aiAct 执行过程中为 UI 元素定位开启深度定位。默认值为 false。

      # 即时操作(Instant Action, .aiTap, .aiHover, .aiInput, .aiKeyboardPress, .aiScroll)
      # ----------------

      # 点击一个元素，用 prompt 描述元素位置
      - aiTap: <prompt>
        deepLocate: <boolean> # 可选，是否为该元素开启深度定位。默认值为 False
        xpath: <xpath> # 可选，目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
        cacheable: <boolean> # 可选，当启用 [缓存功能](./caching.mdx) 时，是否允许缓存当前 API 调用结果。默认值为 True
        fileChooserAccept: <path> | [<path1>, <path2>] # 可选，当点击触发文件选择器时，指定要上传的文件路径；仅在 web 中可用

      # 鼠标悬停一个元素，用 prompt 描述元素位置
      - aiHover: <prompt>
        deepLocate: <boolean> # 可选，是否为该元素开启深度定位。默认值为 False
        xpath: <xpath> # 可选，目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空

        cacheable: <boolean> # 可选，当启用 [缓存功能](./caching.mdx) 时，是否允许缓存当前 API 调用结果。默认值为 True

      # 输入文本到一个元素，用 prompt 描述元素位置
      - aiInput: <prompt> # 要输入文本的元素
        value: <输入框的最终文本内容>
        deepLocate: <boolean> # 可选，是否为该元素开启深度定位。默认值为 False
        xpath: <xpath> # 可选，目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空
        cacheable: <boolean> # 可选，当启用 [缓存功能](./caching.mdx) 时，是否允许缓存当前 API 调用结果。默认值为 True

      # 在元素上按下某个按键（如 Enter，Tab，Escape 等），用 prompt 描述元素位置
      - aiKeyboardPress: <prompt> # 要按键的目标元素
        keyName: <按键>
        deepLocate: <boolean> # 可选，是否为该元素开启深度定位。默认值为 False
        xpath: <xpath> # 可选，目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空

        cacheable: <boolean> # 可选，当启用 [缓存功能](./caching.mdx) 时，是否允许缓存当前 API 调用结果。默认值为 True

      # 全局滚动，或滚动 prompt 描述的元素
      - aiScroll: <prompt> # 可选，执行滚动的元素
        scrollType: 'singleAction' # 或 'scrollToBottom' | 'scrollToTop' | 'scrollToRight' | 'scrollToLeft'，默认值为 'singleAction'
        direction: 'down' # 或 'up' | 'left' | 'right'，默认值为 'down'。仅在 scrollType 为 singleAction 时生效
        distance: <number> # 可选，滚动距离，单位为设备的逻辑像素，
        # 也就是自定义设备接入时 size() 返回的宽高所使用的坐标单位。设置为 null 表示由 Midscene 自动决定。
        # 执行时，该距离在触摸设备上会转换为滑动手势的移动距离，在 Web／桌面端会转换为滚轮滚动增量。
        # 页面内容最终的移动距离不保证与该值相同。
        deepLocate: <boolean> # 可选，是否为该元素开启深度定位。默认值为 False
        xpath: <xpath> # 可选，目标元素的 xpath 路径，用于执行当前操作。如果提供了这个 xpath，Midscene 会优先使用该 xpath 来找到元素，然后依次使用缓存和 AI 模型。默认值为空

        cacheable: <boolean> # 可选，当启用 [缓存功能](./caching.mdx) 时，是否允许缓存当前 API 调用结果。默认值为 True

      # 在报告文件中记录当前截图，并添加描述
      - recordToReport: <title> # 可选，截图的标题，如果未提供，则标题为 'untitled'
        content: <content> # 可选，截图的描述

      # 数据提取
      # ----------------

      # 执行一个查询，返回一个 JSON 对象
      - aiQuery: <prompt> # 记得在提示词中描述输出结果的格式
        name: <name> # 查询结果在 JSON 输出中的 key

      # 更多 API
      # ----------------

      # 等待某个条件满足，并设置超时时间(ms，可选，默认 30000)
      - aiWaitFor: <prompt>
        timeout: <ms>

      # 执行一个断言
      - aiAssert: <prompt>
        errorMessage: <error-message> # 可选，当断言失败时打印的错误信息。
        name: <name> # 可选，给断言一个名称，会在 JSON 输出中作为 key 使用

      - aiBoolean: <prompt>
        name: <name> # 可选，给布尔结果一个名称，会在 JSON 输出中作为 key 使用

      # 运行一个 Gherkin Scenario。此功能从 Midscene 1.10 开始支持，目前仍处于 Beta 阶段。
      - runGherkinScenario: |
          Scenario: 添加待办事项
            Given 待办事项页面已经打开
            When 我添加一条名为“买牛奶”的待办事项
            Then 待办事项列表中应该包含“买牛奶”

      # 等待一定时间
      - sleep: <ms>

      # 在 web 页面上下文中执行一段 JavaScript 代码
      - javascript: <javascript>
        name: <name> # 可选，给返回值一个名称，会在 JSON 输出中作为 key 使用

  - name: <name>
    flow:
      # ...

runGherkinScenario 从 Midscene 1.10 开始支持，目前仍处于 Beta 阶段。支持规则和限制请参考 BDD 风格脚本（Gherkin）。

步骤结果名称

带有 name 的步骤会把结果写入当前 YAML 运行结果和 JSON 输出中。使用 name 标记需要出现在运行结果里的值。

tasks:
  - name: 保存提取结果
    flow:
      - aiString: 读取页面中的商品 id
        name: product_id

      - aiQuery: 提交商品 id 后，获取搜索结果
        name: search_result

使用 `aiTap` 上传文件

当点击某个按钮会弹出文件选择器时，可以在 aiTap 步骤上直接设置 fileChooserAccept。它支持单个路径，也支持路径数组。

tasks:
  - name: 上传单个文件
    flow:
      - aiTap: 选择文件按钮
        fileChooserAccept: ./fixtures/document.pdf

  - name: 上传多个文件
    flow:
      - aiTap: 上传图片按钮
        fileChooserAccept:
          - ./fixtures/image1.jpg
          - ./fixtures/image2.png

如果你已经在用 locate 对象写 prompt、images 等定位信息，fileChooserAccept 仍然要和 locate 保持同级，不要放到 locate 或 aiTap 的嵌套对象里：

tasks:
  - name: 带 locate 的文件上传
    flow:
      - aiTap:
        locate:
          prompt: 点击上传按钮
        fileChooserAccept: ./fixtures/document.pdf

注意：

fileChooserAccept 仅在 web 页面（Playwright、Puppeteer 或 Chrome extension Bridge mode）中可用。
相对路径会基于当前命令执行目录解析，而不是基于 YAML 文件所在目录解析。
如果文件不存在，脚本会在执行点击前直接报错。
Chrome extension Bridge mode 上传本地文件时，需要在 chrome://extensions > Midscene > “Details” 中开启插件的 “Allow access to file URLs” 权限。开启后请从目标 http(s):// 页面重新连接桥接模式。
Chrome extension Bridge mode 不支持目录上传输入框（webkitdirectory / directory）。如需上传目录，请使用 Playwright。

使用图像提示

对于支持在提示词中附带图像的步骤（参见 API 参考），可以把提示词改写为对象，并通过设置 images 字段（一个包含 name 和 url 的对象数组）来附加图像。该对象包含以下字段：

prompt：发送给模型的文本描述。
images（可选）：提示词引用的参考图像，每一项需要提供 name 和 url。
convertHttpImage2Base64（可选）：在图片链接无法公开访问时，将 HTTP 链接转换为 Base64 再发送给模型。

图片 URL 可以是本地路径、Base64 字符串或远程链接。如果图片链接无法被模型访问，请设置 convertHttpImage2Base64: true，Midscene 会将图像下载后以 Base64 字符串的形式发送给模型。

对于 aiTap、aiHover、aiDoubleClick、aiRightClick 等交互操作，请把文本和图像配置写在 locate 字段中，locate 与操作指令同级。

tasks:
  - name: 校验品牌一致性
    flow:
      - aiHover:
        locate:
          prompt: 将鼠标移动到包含 GitHub 标志的区域。
          images:
            - name: GitHub 标志
              url: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png
          convertHttpImage2Base64: true

      - aiTap:
        locate:
          prompt: 点击包含 GitHub 标志的区域。
          images:
            - name: GitHub 标志
              url: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png
          convertHttpImage2Base64: true

旧的嵌套写法（将 locate 缩进到操作指令内部，例如 aiTap: \n locate: ...）仍然支持，但不推荐使用。

对于 aiAct（及其简写 ai），以及 aiAsk、aiQuery、aiBoolean、aiNumber、aiString、aiAssert 等视觉问答类步骤，都可以直接在操作指令下设置 prompt 和 images 字段。

tasks:
  - name: 校验品牌一致性
    flow:
      - aiAssert:
          prompt: 判断页面上是否出现该图像。
          images:
            - name: 目标标志
              url: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png
          convertHttpImage2Base64: true

注意事项

`agent.runYaml` 只会解析 `tasks` 字段

当使用 agent.runYaml() api 时，YAML 文件中只有 tasks 字段会被解析和执行。

因为此时 agent 已经在 js 脚本中完成初始化，无法根据 YAML 中的 agent 配置再次初始化。

#使用 YAML 格式的自动化脚本

#配置 AI 模型服务

#脚本文件结构

#agent 部分

#使用示例

#Web target 部分

#Chrome Bridge

#android 部分

#Android 平台特定动作

#ios 部分

#iOS 平台特定动作

#harmony 部分

#HarmonyOS 平台专属动作

#computer 部分

#使用示例

#tasks 部分

#步骤结果名称

#使用 aiTap 上传文件

#使用图像提示

#注意事项

#agent.runYaml 只会解析 tasks 字段

使用 YAML 格式的自动化脚本

配置 AI 模型服务

脚本文件结构

`agent` 部分

使用示例

Web target 部分

Chrome Bridge

`android` 部分

Android 平台特定动作

`ios` 部分

iOS 平台特定动作

`harmony` 部分

HarmonyOS 平台专属动作

`computer` 部分

使用示例

`tasks` 部分

步骤结果名称

使用 `aiTap` 上传文件

使用图像提示

注意事项

`agent.runYaml` 只会解析 `tasks` 字段