企业官网建设流程全解析

如何在 Midscene YAML 自动化的提示词中附加参考图片

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

在 Midscene 的 YAML 自动化脚本中，很多步骤（aiTap、aiAssert等）的提示词只是一段字符串。当纯文字无法把目标描述清楚时——比如页面上有一个特定的 Logo、按钮图标和周围元素很难用语言区分——可以在提示词中附带参考图片，让模型对照图片来定位或判断目标。本文基于 Midscene 官方文档 Automate with scripts in YAML 和 API 参考，说明如何在 YAML 脚本中正确附加images、如何运行脚本，以及如何验证附加图片后断言是否生效。

准备条件

按照 YAML script runner 文档，运行 YAML 脚本需要：

1. 终端使用的 Node.js 版本为20.19+、22.12+或24+。部分 CLI 执行路径使用 Rstest/Rspack 工具链，会拒绝更旧的 Node 20 补丁版本（如20.17.0），遇到Unsupported Node.js version提示时需升级 Node.js。
2. 安装 CLI（推荐全局安装，也可按项目安装）：

npm i -g @midscene/cli

3. 在运行命令的目录下创建.env文件，配置模型服务（这些是 dotenv 读取的键值对，不要加export前缀）：

MIDSCENE_MODEL_BASE_URL="replace with your model service URL/v1" MIDSCENE_MODEL_API_KEY="replace with your API Key" MIDSCENE_MODEL_NAME="replace with your model name" MIDSCENE_MODEL_FAMILY="replace with your model family"

.env放在你运行midscene命令的目录中，不一定与 YAML 文件同目录。完整的模型配置说明见 Supported models and setup。

提示词改为对象：prompt、images、convertHttpImage2Base64

原本写成字符串的步骤提示词，需要改写为对象形式。该对象包含以下字段：

• prompt：发送给模型的文本描述；
• images（可选）：提示词引用的参考图片，是一个对象数组，每一项需要提供name（在提示词中引用该图片用的名字）和url；
• convertHttpImage2Base64（可选）：设为true时，Midscene 会先把 HTTP 图片链接下载并转成 Base64 再发送给模型，适用于图片链接无法被模型公开访问的情况。

url可以是三种形式：本地路径、Base64 字符串或远程链接。

两类步骤的写法不同

交互类步骤：images写在locate字段中

对于aiTap、aiHover、aiDoubleClick、aiRightClick这类交互操作，文本和图片要放在locate字段里，且locate与操作指令同级（不要嵌套在操作指令内部，旧的嵌套写法仍受支持但官方不推荐）。文档给出的示例：

tasks: - name: Verify branding flow: - aiHover: locate: prompt: Move the cursor to the region containing the GitHub logo. images: - name: GitHub logo url: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png convertHttpImage2Base64: true - aiTap: locate: prompt: Tap the region containing the GitHub logo. images: - name: GitHub logo url: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png convertHttpImage2Base64: true

执行与视觉问答类步骤：prompt和images直接写在操作指令下

对于aiAct（及其简写ai），以及aiAsk、aiQuery、aiBoolean、aiNumber、aiString、aiAssert等视觉问答类步骤，可以直接在操作指令下设置prompt和images字段。例如用参考图片断言页面上是否出现了该 Logo（文档示例）：

tasks: - name: Verify branding flow: - aiAssert: prompt: Check whether the image appears on the page. images: - name: target logo url: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png convertHttpImage2Base64: true

完整脚本与运行

把上面的步骤放进一个完整脚本（以 Web 页面为例），例如verify-branding.yaml：

page: url: https://www.github.com tasks: - name: Verify branding flow: - aiTap: locate: prompt: Tap the region containing the GitHub logo. images: - name: GitHub logo url: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png convertHttpImage2Base64: true - aiAssert: prompt: Check whether the image appears on the page. images: - name: target logo url: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png convertHttpImage2Base64: true

在脚本所在目录（或能访问到该文件的目录）执行：

midscene ./verify-branding.yaml # 如果 Midscene 安装在项目中 npx midscene ./verify-branding.yaml

Web 场景如果需要看到浏览器窗口，可以追加--headed参数。

验证结果

按 YAML script runner 文档，CLI 会打印执行进度，结束后生成可视化报告。输出目录中包含：

• 由--summary指定的 JSON 汇总文件（默认index.json），包含所有脚本的执行状态和统计；
• 每个 YAML 文件对应的单独执行结果（JSON）；
• 每个脚本的可视化报告（HTML）。

判断本次任务是否完成：

1. aiAssert步骤执行通过（该步骤用附带的参考图片判断页面内容，若断言失败 CLI 会报错，可配置errorMessage自定义失败信息）；
2. 生成的 JSON 汇总中该脚本执行状态正常；
3. 打开可视化报告，核对执行过程中发送给模型的截图和步骤记录。

限制与注意事项

• 图片尺寸：遵循模型服务商对图片尺寸和边长的限制，过大或过小的图片可能被拒绝，具体限制需查对应服务商的文档。
• 模型无法访问的图片链接：如果url是模型侧无法访问的 HTTP 链接（例如需要登录内网），设置convertHttpImage2Base64: true，Midscene 会下载图片并以 Base64 形式发送给模型。
• 本地图片路径：相对路径基于当前命令执行目录解析，与 YAML 脚本中其他文件路径（如fileChooserAccept）的规则一致，写路径前先确认执行目录。
• 嵌套写法：locate缩进在操作指令内部的旧写法仍然支持，但不推荐，新脚本请使用locate与操作指令同级的写法。
• 同一能力在 API 中的等价形式：如果你不用 YAML 而是用 JS API，同样的提示词对象可直接传给agent.aiTap()、agent.aiAssert()、agent.aiAct()等方法，字段结构一致（prompt/images/convertHttpImage2Base64），见 API 参考 "Prompt input with images"。
• 该文档同时标注了 YAML 自动化属于 legacy 方案，Midscene Test 为 Beta；本文描述的是 legacy YAML 脚本的行为，以文档为准。

相关文档：Automate with scripts in YAML、YAML script runner、API reference。

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene