Maestro AI 模块深度解析：基于 LLM 的移动端截图缺陷检测与评估工具

测试移动开发开发工具CLI【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址https://gitcode.com/GitHub_Trending/ma/Maestro点击查看免费下载Maestro 是一个面向移动端与 Web 的端到端自动化测试框架而maestro-ai模块则为它引入了 AI 能力既是一个可复用的 Kotlin 库也是一个可直接运行的 CLI 演示程序用于评估大语言模型LLM对应用截图找缺陷defects的能力。读完本文你将掌握该模块的环境变量配置、构建方式、命令行用法、截图/提示词命名约定以及它背后从 LLM 客户端到 Maestro Cloud 预测引擎的完整实现链路。模块定位库 可执行 Demo Appmaestro-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_KEYsk-... # Anthropic export MAESTRO_CLI_AI_KEYsk-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_KEYDemoApp.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表示缺陷类别如layoutreasoning是模型给出的推理说明。判定规则DemoApp.kt截图状态模型结果判定bad应检出缺陷检出 ≥1 个缺陷PASS无漏报bad应检出缺陷未检出缺陷FAILfalse-negative漏报good不应检出缺陷未检出缺陷PASS无误报good不应检出缺陷检出 ≥1 个缺陷FAILfalse-positive误报命令行选项一览以下选项均来自 DemoApp.kt 的实际定义选项类型默认值说明screenshots位置参数多个路径必填要检测的截图文件支持通配符如test-ai-fixtures/uber_*_bad.png--model字符串gpt-4o使用的 LLM 模型以gpt开头走 OpenAI 客户端以claude开头走 Anthropic 客户端否则报错--show-only-fails布尔flag关闭只输出失败的测试PASS 的不打印--show-prompts布尔flag关闭打印发送给 LLM 的提示词--show-raw-response布尔flag关闭打印 LLM 的原始返回--temperature浮点数0.2LLM 采样温度越低输出越稳定、可复现--parallel布尔flag关闭并发执行所有测试注意可能触发限流其中模型选择逻辑在 DemoApp.ktmodel.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 NegotiationignoreUnknownKeys true并设置超时——连接超时 10 秒、socket/请求超时 60 秒对应移动端 LLM 推理的典型耗时。OpenAI 客户端openai/Client.kt 请求https://api.openai.com/v1/chat/completions关键实现事实默认模型gpt-4o默认max_tokens1024默认图像细节imageDetailhigh截图以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_tokens1024认证使用x-api-key请求头并携带anthropic-version: 2023-06-01截图以base64image/png的image内容块形式发送请求体结构见 anthropic/Request.ktmodel、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【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址https://gitcode.com/GitHub_Trending/ma/Maestro点击查看免费下载相关推荐Maestro AI功能解析自动检测UI缺陷与提取文本Maestro AI功能解析自动检测UI缺陷与提取文本 Maestro作为一款移动UI自动化测试工具其AI功能为测试流程带来了革命性的提升。本文将深入解析M测试移动开发开发工具CLILaVague项目评估模块深度解析如何科学评测检索器与LLM性能LaVague项目评估模块深度解析如何科学评测检索器与LLM性能 引言Web Agent性能评估的挑战与机遇 在AI Web AgentWeb智能体快速AI AgentGUI 自动化AI 应用大模型RAG揭秘Phoenix AI评估模块LLM辅助评价的完整实现机制与实战指南揭秘Phoenix AI评估模块LLM辅助评价的完整实现机制与实战指南 Phoenix作为一款强大的AI可观测性与评估工具其评估模块为开发者提供了全面的LL可观测性AI 评测LLMOpsAI 应用人工智能上一篇5分钟彻底解决Windows更新问题Reset Windows Update Tool完整指南下一篇Zotero-reference终极指南5个高效技巧让学术写作事半功倍创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考