• 人工智能
• AI Agent
• MCP 服务
• GUI 自动化
• 移动开发
• 测试

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 对象，且满足：

同时给出了三条铁律：整段响应只能包含该 JSON，前后不得有任何摘要、评注或 Markdown 围栏；响应的第一个字符必须是{，最后一个字符必须是}。这种"机器可解析 + 人类可读 steps"的双重要求，与 mobilecli 命令本身"结构化 JSON 输出"的设计一脉相承——例如mobilecli.devices命令返回{status:"ok", data:{devices:[...]}}格式（见 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 [--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 idcom.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（mcpServersJSON），Claude Code 可用claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest；安装后先让 Agent 执行mobile_list_available_devices验证连通。
3. 运行模式：默认 stdio；需要远程服务时用--listen [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。这份文档既是验收脚本，也是理解"平台无关移动自动化"架构的最短路径。

• 人工智能
• AI Agent
• MCP 服务
• GUI 自动化
• 移动开发
• 测试