用 mobilecli / mobile-mcp 编写 iOS 模拟器验收测试提示词:JSON 契约、任务拆解与底层工具链解析

原创2026-09-29 23:54:361,672 阅读
文章标签:MCP 服务GUI 自动化移动开发人工智能AI AgentCLI

用 mobilecli / mobile-mcp 编写 iOS 模拟器验收测试提示词:JSON 契约、任务拆解与底层工具链解析

test/prompt-ios-simulator.md 是一份面向 LLM/Agent 的 iOS 模拟器验收测试提示词(acceptance test prompt),用于验证 mobilecli(以及其上层 mobile-mcp MCP Server)能否驱动真实的 iOS 模拟器完成"多应用操作 + 网页内容检索 + 截屏解释"的端到端任务。本文将完整解读这份提示词的输出契约与测试任务,并从源码层面剖析其背后的工具调用链——从 mobilecli 二进制定位、devices 设备枚举,到 MobileDevice 封装、xcrun simctl 与 WebDriverAgent 驱动路径——让你既能复现这份验收测试,也能理解 Agent 每一步操作真正落到哪一行代码。

一、提示词的本质:一份可执行的 Agent 验收契约

test/prompt-ios-simulator.md 全文 17 行,是一段可以直接投喂给任意 MCP 客户端(Claude Code、Codex、Gemini、Copilot、Cursor 等)的系统级指令。它的核心意图不是"教用户如何使用",而是用一道真实任务验证 mobilecli 驱动 iOS 模拟器的能力是否达标。

提示词首先为 Agent 确立了严格的输出纪律:

You are running an acceptance test for mobilecli. The output of this prompt must be a json with a simple "pass" boolean.

这要求 Agent 的最终响应必须是唯一的 JSON 对象,且满足:

字段 类型 说明
pass boolean 测试是否通过
error string(可选) 仅当测试失败时出现,用人类可读语言说明问题所在
steps string[] 你为完成任务实际执行的步骤,且必须包含用到的 MCP 工具名

同时给出了三条铁律:整段响应只能包含该 JSON,前后不得有任何摘要、评注或 Markdown 围栏;响应的第一个字符必须是 {,最后一个字符必须是 }。这种"机器可解析 + 人类可读 steps"的双重要求,与 mobilecli 命令本身"结构化 JSON 输出"的设计一脉相承——例如 mobilecli.devices 命令返回 {status:"ok", data:{devices:<a href="https://link.gitcode.com/i/1e0201fe1dd482e9bc5e244c1c76fb07" target="_blank">...]}} 格式(见 [src/mobilecli.ts),Agent 与 CLI 之间始终以确定性 JSON 交换信息。

<test> 标签内的任务描述如下(原文):先断言"只有一个 iOS 模拟器连接";然后使用模拟器前往 Wikipedia 查询"今日文章";启动 Reminders 应用,添加一条"了解今日精选文章"的提醒;接着搜索 NASA 每日天文图片,截图并向人类解释照片内容。

二、测试任务逐条拆解:四步端到端场景

1. 断言"只有一个 iOS 模拟器连接"

这是环境前置校验。Agent 应当调用 mobile_list_available_devices 工具枚举所有可用设备(物理机、模拟器、仿真器),并检查 iOS 类型设备中 state === "online"(已启动)的模拟器恰好为一个。

在源码层面,该工具在 src/server.ts 注册:默认(非 legacy 模式)路径下调用 mobilecli.getDevices({ includeOffline: true }),然后过滤出 state === "online" 的设备。getDevices 最终拼接为 mobilecli devices <a href="https://link.gitcode.com/i/bd622cf4874c7d459ccf7dd8a6148d8b" target="_blank">--include-offline] [--platform ...] [--type ...] 子命令并解析 JSON 响应([src/mobilecli.ts)。值得注意的是 createRobotFromDevice 中还有一个隐性步骤:对于 iOS 模拟器,若 agentStatus 返回 fail,会自动先执行 agentInstall(src/server.ts),即首次使用前自动部署 mobilecli 的 iOS 模拟器 Agent。

测试文件的对应验证逻辑是 test/iphone-simulator.ts:它用 mobilecli.getDevices({ platform:"ios", type:"simulator", includeOffline:false }) 取出已启动模拟器列表,并仅在 >= 1 台时运行用例(test.skip(!hasOneSimulator, ...))——可见"至少/恰好一台"是 iOS 模拟器用例的通用前提(test/iphone-simulator.ts)。

2. 打开 Wikipedia 查询今日文章

Agent 应调用 mobile_open_url 打开 Wikipedia。该工具在 src/server.ts 实现,并带有一个重要的安全闸门:默认只允许 http:// 与 https:// 协议,只有显式设置环境变量 MOBILEMCP_ALLOW_UNSAFE_URLS=1 才会放行其他 URL scheme(见 README.md 环境变量表)。随后 URL 经由 MobileDevice.openUrl 落到 mobilecli url <url> --device <id>(src/mobile-device.ts)。

3. 启动 Reminders 并添加提醒

Agent 应调用 mobile_launch_app 启动提醒事项应用,例如 bundle id com.apple.reminders(这与 test/iphone-simulator.ts 中 restartRemindersApp 使用的包名一致,见 test/iphone-simulator.ts)。mobile_launch_app 支持可选的 locale 参数(逗号分隔的 BCP 47 标签),在 legacy 路径下会转换为 simctl launch <uuid> <bundle> -AppleLanguages "(...)" -AppleLocale <locale>(见 src/iphone-simulator.ts)。

添加提醒文本通常需要组合使用:

  • mobile_list_elements_on_screen 找到"New Reminder"入口(测试中用 e.label === "New Reminder" 定位,见 test/iphone-simulator.ts);
  • mobile_click_on_screen_at_coordinates 或 mobile_tap 点击;
  • mobile_type_keys 键入文字(可配合 submit: true 触发回车提交,服务端实现为 sendKeys 后补按 ENTER,见 src/server.ts)。

4. 搜索 NASA 每日图片并截图解释

Agent 回到浏览器(再次 mobile_open_url 或直接复用网页),搜索 NASA 每日天文图片(APOD),然后调用 mobile_take_screenshot 获取当前画面。mobile_take_screenshot 在 src/server.ts 注册:默认输出 JPEG、质量 75、最大边 1024px(DEFAULT_SCREENSHOT_MAX_SIZE = 1024),maxSize 与 scale 参数可调整缩放;返回时会附带 describeCoordinateMapping 生成的"截图坐标 ↔ 屏幕坐标"映射说明,帮助模型把看到的像素位置换算为真实点按坐标,避免因缩放导致的点击偏差(见 src/coordinate-mapping.ts 与 server.ts 中相关注释)。最后 Agent 将图片内容结合 steps 一并写入 JSON 的说明性解释——这正是提示词第 14 行"take a screenshot to explain to me what's in the photo"的意图:验证 Agent 能否"看图说话"。

三、底层工具链:mobilecli 二进制如何被发现与调用

所有操作最终都汇聚到同一个核心依赖:mobilecli——一个跨平台、跨设备(iOS/Android、模拟器/仿真器/真机)的统一设备 CLI,README 将其定位为"Mobile MCP is built on"的底层工具。src/mobilecli.ts 中的 Mobilecli 类封装了它的一切:

  • 二进制定位(getMobilecliPath,src/mobilecli.ts):优先读取环境变量 MOBILECLI_PATH;否则按 process.platform/process.arch 拼出作用域包名 mobilecli-<platform>-<arch>(Windows 下追加 .exe,arm64/amd64 归一化),依次在 node_modules 根目录下的 mobilecli/bin/(≤1.0.6 的旧布局)与 @mobilenext/mobilecli-*(≥1.0.7 的分平台新布局)中查找。找不到时抛出 Could not find mobilecli binary for platform: ...。
  • 三种执行模式:executeCommand(UTF-8 文本,默认 30s 超时)、executeCommandBuffer(二进制输出,用于截图,MAX_BUFFER_SIZE = 8MB)、spawnCommand(异步子进程,用于录屏、日志流)。
  • 版本自检:getVersion() 解析 mobilecli --version;服务端每次创建设备句柄前调用 ensureMobilecliAvailable(),失败即抛出 ActionableError 并提示查阅 wiki(src/server.ts)。

设备对象则由 MobileDevice 统一封装(src/mobile-device.ts),所有命令统一追加 --device <id> 后缀,并把 dump ui(无障碍元素树)、io tap/swipe/text/button(输入手势)、apps launch/terminate/install(应用管理)、device info/orientation/location(设备信息)等子命令翻译为类型化方法。getElementsOnScreen 会递归展开嵌套元素树为扁平 ScreenElement[](flattenUIElement),使 Agent 拿到带 ref/rect 的结构化 UI 数据——这就是"Accessibility-first"(以无障碍树驱动而非视觉模型)架构的落地。

四、iOS 模拟器的两条驱动路径

仓库同时存在两代 iOS 模拟器驱动,理解它们能帮你判断提示词实际会走哪条路:

  1. 默认路径(mobilecli 原生驱动):createRobotFromDevice 在非 legacy 模式下直接返回 MobileDevice,一切经由 mobilecli 的 iOS Agent 完成。agentVerifiedSimulators 集合保证同一模拟器只做一次 Agent 安装/校验(src/server.ts)。
  2. Legacy 路径(MOBILEMCP_LEGACY_ROBOT=1):iOS 模拟器回落到 src/iphone-simulator.ts 的 Simctl 类——它通过 xcrun simctl launch/terminate/install/listapps/io screenshot 直接控制模拟器,并依赖 WebDriverAgent(端口 8100)执行截图、点按、滑动、键盘输入与元素树导出(src/iphone-simulator.ts);若 WDA 未启动,会先 simctl launch com.facebook.WebDriverAgentRunner.xctrunner 并轮询 10 秒等待就绪。

README 的环境变量表明确说明:MOBILEMCP_LEGACY_ROBOT=1 仅对 Android 真机与 iOS 真机启用旧版 robot,iOS 模拟器始终使用 mobilecli。因此本文提示词场景(iOS 模拟器)在默认配置下走的必然是 mobilecli 路径。

五、环境准备与复现前提

要在本机复现这份验收测试,需要满足(依据 README.md 的 Prerequisites 与 Running 章节):

  1. Xcode 命令行工具与一个已启动的 iOS 模拟器:可用 xcrun simctl list 查看,xcrun simctl boot "iPhone 16" 启动。
  2. Node.js v20+,并通过 MCP 客户端注册服务:标准配置为 npx -y @mobilenext/mobile-mcp@latest(mcpServers JSON),Claude Code 可用 claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest;安装后先让 Agent 执行 mobile_list_available_devices 验证连通。
  3. 运行模式:默认 stdio;需要远程服务时用 --listen <a href="https://link.gitcode.com/i/e4029a6f085992483cff128e1cb9e7f9" target="_blank">host:]port 启动 Streamable HTTP(如 npx @mobilenext/mobile-mcp@latest --listen 3000),并可用 MOBILEMCP_AUTH 设置 Bearer 鉴权(见 [src/index.ts 的 --listen/--stdio 参数解析与 README.md 的授权说明)。
  4. 可选环境变量:MOBILEMCP_DISABLE_TELEMETRY=1 关闭匿名遥测;MOBILEMCP_ALLOW_UNSAFE_URLS=1 放行非 http(s) 协议(本文的 Wikipedia/NASA 页面均为 https,无需设置)。

六、仓库中的同类佐证:测试如何验证这些能力

test/ 目录下的测试用例为本文提示词中的操作提供了直接的能力证明:

  • test/iphone-simulator.ts:验证了 iOS 模拟器上的滑动(swipe up/down 后元素可见性断言)、键入与回车提交(device.sendKeys(random) + pressButton("ENTER") 后用 e.value 断言)、屏幕尺寸(scale >= 1,恰好 3 个属性)以及截图字节数校验。
  • test/ios.ts:验证真机/模拟器截图是合法 PNG 且与 getScreenSize 一致(Math.ceil(pngSize.width / screenSize.scale) === screenSize.width),并强调"WDA 返回的是 point 而非 pixel"这一关键换算关系。
  • test/prompt-android-emulator.md:姊妹篇提示词,覆盖 Android 仿真器场景(安装/前台断言/保存 PNG/滑动手势等),可交叉理解 mobilecli 的平台无关设计。
  • scripts/verify-streamable-http.mjs:验证 HTTP 传输模式的可用性,与 --listen 部署相关。

如果你在运行这份验收测试时看到失败,请检查 JSON 中的 error 与 steps:多数失败可归因于三类——模拟器未启动(mobile_list_available_devices 返回空)、mobilecli 二进制缺失(ensureMobilecliAvailable 抛错)、或 WDA/Agent 未就绪(legacy 路径的 ActionableError 会直接提示查阅 wiki)。

七、小结

test/prompt-ios-simulator.md 虽然只有 17 行,却完整勾勒了 mobilecli 体系的能力边界:结构化 JSON 输出契约(pass/error/steps)、多应用切换与网页内容检索、无障碍元素树驱动的输入、以及截屏 + 坐标映射的视觉反馈闭环。结合 src/mobilecli.ts、src/mobile-device.ts、src/server.ts 等源码,你可以看清每一步 Agent 操作背后的真实调用链——从 MCP 工具到 mobilecli 子命令,再到 xcrun simctl 与 WebDriverAgent。这份文档既是验收脚本,也是理解"平台无关移动自动化"架构的最短路径。

登录后查看全文
mobile-mcp