企业官网建设流程全解析

• 测试
• 移动开发
• 开发工具
• CLI

Maestro 是一个面向移动端与 Web 的端到端自动化测试框架，而maestro-ai模块则为它引入了 AI 能力：既是一个可复用的 Kotlin 库，也是一个可直接运行的 CLI 演示程序，用于评估大语言模型（LLM）对应用截图"找缺陷（defects）"的能力。读完本文，你将掌握该模块的环境变量配置、构建方式、命令行用法、截图/提示词命名约定，以及它背后从 LLM 客户端到 Maestro Cloud 预测引擎的完整实现链路。

模块定位：库 + 可执行 Demo App

maestro-ai模块实现的是 Maestro 中的 AI 支持能力（AI support for use in Maestro），它的定位是"both a library and an executable demo app"——即同时提供：

• 可复用的 AI 库：通过 AI.kt 抽象类与 IAPredictionEngine.kt 接口，封装对 OpenAI、Anthropic 以及 Maestro Cloud 预测服务的调用；
• 可执行演示程序：通过 DemoApp.kt 提供一个基于 Clikt 的命令行工具maestro-ai-demo，用于在一批截图与提示词上评估 LLM 的缺陷检测结果。

模块的 Gradle 元数据（gradle.properties）将其声明为maestro-ai构件（artifact），打包方式为 jar。

运行前置条件：配置 API Key

演示程序需要 LLM 提供方的 API Key，通过环境变量MAESTRO_CLI_AI_KEY注入。README 给出了两类示例：

# OpenAI export MAESTRO_CLI_AI_KEY=sk-... # Anthropic export MAESTRO_CLI_AI_KEY=sk-ant-api-...

从源码看，该环境变量名在 AI.kt 中统一定义为常量AI_KEY_ENV_VAR = "MAESTRO_CLI_AI_KEY"，同时还有AI_MODEL_ENV_VAR = "MAESTRO_CLI_AI_MODEL"用于指定默认模型。在 DemoApp.kt 中，程序启动时会读取该环境变量，若未设置会直接抛出异常："OpenAI API key is not provided"。

注意（源码级补充）：虽然 README 只提到MAESTRO_CLI_AI_KEY，但maestro-ai-demo在运行阶段还会检查MAESTRO_CLOUD_API_KEY（DemoApp.kt），未设置时会抛出MAESTRO_CLOUD_API_KEY is not available错误。这是因为缺陷预测请求实际上由 Maestro Cloud 的预测服务完成（详见下文"云端预测引擎"一节），因此本地演示需要同时具备两个 Key。

构建 Demo App

使用 Gradle 任务installDist构建：

./gradlew :maestro-ai:installDist

构建完成后，启动脚本会生成在：

./maestro-ai/build/install/maestro-ai-demo/bin/maestro-ai-demo

该脚本即后续所有命令行示例中使用的可执行文件。由于installDist会生成包含全部运行依赖的发行目录，构建后即可直接运行，无需额外配置 classpath。

使用方式：从单张截图到批量评估

第一步：查看帮助

maestro-ai-demo --help

程序基于 Clikt 框架实现，--help会列出全部参数、默认值及说明，是理解其余选项的最快途径。

对单张截图执行缺陷检测

maestro-ai-demo foo_1_bad.png

该命令对名为foo_1_bad.png的截图执行一次缺陷检测，并根据结果打印 PASS 或 FAIL。

批量检测 + 输出调试信息

maestro-ai-demo \ --model gpt-4o-2024-08-06 \ --show-prompts \ --show-raw-response \ test-ai-fixtures/uber_*_bad.png

该命令会：

• 对test-ai-fixtures/目录下所有匹配uber_*_bad.png的截图（即 Uber 应用"有缺陷"的截图样本）逐一执行检测；
• 通过--model gpt-4o-2024-08-06显式指定使用 OpenAI 的该型号；
• 通过--show-prompts打印发送给 LLM 的提示词；
• 通过--show-raw-response打印 LLM 的原始返回内容，便于核对解析逻辑与排查问题。

截图与提示词命名约定

maestro-ai-demo之所以能"自动判断"一次检测是对是错，依赖一套严格的命名约定（定义于 DemoApp.kt 的文档注释与解析逻辑）：

• 截图文件名格式为{app_name}_{screenshot_number}_{good|bad}.png，例如：
  • foo_1_bad.png—— 表示应用foo的第 1 张截图，应检出缺陷；
  • bar_2_good.png—— 表示应用bar的第 2 张截图，不应检出缺陷。
• 截图可以可选地关联一个提示词文件，提示词会被模型当作断言命令（assertion command）使用；提示词文件名必须与截图同名且扩展名为.txt：
  • {app_name}_{screenshot_number}_{good|bad}.txt
• 解析时文件名被按_切分为三段：应用名、序号（必须是整数）、状态标记（good/bad）；程序只接受 PNG 输入，否则会拒绝（DemoApp.kt）。

输出格式

单张截图的输出要么是 PASS 要么是 FAIL，同时包含截图名、检测结果以及（若存在）检出的缺陷。例如：

PASS uber_2_bad.png: 1 defects found (as expected) * layout: The prompt for entering a verification code is visible, indicating that the 2-factor authentication process is present. The screen instructs the user to enter a verification code generated for Uber, which is a typical 2-factor authentication step.

这里的缺陷对象是 ApiClient.kt 中定义的Defect(category, reasoning)：category表示缺陷类别（如layout），reasoning是模型给出的推理说明。

判定规则（DemoApp.kt）：

命令行选项一览

以下选项均来自 DemoApp.kt 的实际定义：

其中模型选择逻辑在 DemoApp.kt：model.startsWith("gpt")构造OpenAI客户端，model.startsWith("claude")构造Claude客户端，二者默认温度均为0.2f，并将MAESTRO_CLI_AI_KEY传入作为 API Key。

底层架构：从统一抽象到双云客户端

AI 抽象基类

AI.kt 定义了核心抽象方法chatCompletion，参数包括：prompt（提示词）、images（截图字节列表，会被 Base64 编码后内联进请求）、temperature、model、maxTokens、imageDetail、identifier以及jsonSchema。其中jsonSchema仅在 OpenAI 的 "Structured Outputs"（结构化输出）特性上受支持，这是代码注释中明确指出的注意事项。

基类还提供共享的默认 HTTP 客户端：开启 JSON Content Negotiation（ignoreUnknownKeys = true），并设置超时——连接超时 10 秒、socket/请求超时 60 秒，对应移动端 LLM 推理的典型耗时。

OpenAI 客户端

openai/Client.kt 请求https://api.openai.com/v1/chat/completions，关键实现事实：

• 默认模型gpt-4o，默认max_tokens=1024，默认图像细节imageDetail="high"；
• 截图以data:image/png;base64,...形式作为image_url内容块与文本提示词合并进user消息；
• 请求中固定携带seed = 1566以增强结果可复现性；
• 传入jsonSchema时启用response_format = json_schema结构化输出；
• 请求体结构见 openai/Request.kt。

Anthropic 客户端

anthropic/Client.kt 请求https://api.anthropic.com/v1/messages，关键实现事实：

• 默认模型claude-3-5-sonnet-20240620，默认max_tokens=1024；
• 认证使用x-api-key请求头，并携带anthropic-version: 2023-06-01；
• 截图以base64+image/png的image内容块形式发送；
• 请求体结构见 anthropic/Request.kt（model、max_tokens、messages）。

云端预测引擎：缺陷检测的最终执行者

maestro-ai-demo中的每一次检测最终都由 Prediction.kt 与 cloud/ApiClient.kt 完成：

• 缺陷检测：findDefects(apiKey, screen)调用POST {baseUrl}/v2/find-defects，返回FindDefectsResponse(defects)；
• 带断言的检测：performAssertion(apiKey, screen, assertion)同样走/v2/find-defects接口，但请求体中携带assertion字段——这正是截图关联.txt提示词时被用作"断言命令"的路径；
• 文本提取：extractTextWithAi(apiKey, query, screen)调用POST {baseUrl}/v2/extract-text，用于按查询从屏幕中提取文本；
• 服务地址：默认 Base URL 为https://api.copilot.mobile.dev，可通过环境变量MAESTRO_CLOUD_API_URL覆盖（ApiClient.kt）。

这些能力同时被抽象为 IAPredictionEngine.kt 接口（findDefects/performAssertion/extractText三个方法），并由 CloudPredictionAIEngine.kt 提供基于 Maestro Cloud 的实现。也就是说，Demo App 中的工作流可归纳为：本地将截图（+可选断言提示词）打包，经 Maestro Cloud 预测服务获得category + reasoning形式的缺陷列表，再按good/bad约定判定 PASS/FAIL，用于评估模型效果。

典型应用场景

• 模型能力基准测试：准备一批标注了good/bad的截图（如 README 示例中的test-ai-fixtures/uber_*_bad.png），批量运行maestro-ai-demo，统计 PASS/FAIL 以评估不同模型（OpenAI / Anthropic）在不同温度下的漏报与误报率；
• 提示词工程调试：通过--show-prompts与--show-raw-response观察发送给模型的提示词与原始返回，定位解析失败或误判原因；
• 回归验证：在固定--seed、低--temperature下对同一批截图反复运行，验证输出稳定性。

需要说明的是，当前仓库的maestro-ai模块尚未包含自动化测试源码，其正确性主要依赖上述命名约定与 PASS/FAIL 判定逻辑的自我校验机制；test-ai-fixtures目录也不在本仓库内，读者需自行准备符合命名约定的截图与提示词样本进行实验。

• 测试
• 移动开发
• 开发工具
• CLI