iOS 开始使用

本指南会带你完成使用 Midscene 控制 iOS 设备的全部步骤:通过 WebDriverAgent 连接真机、配置模型 API Key、体验零代码 Playground,并运行你的首个 JavaScript 脚本。

配置 AI 模型服务

将你的模型配置写入环境变量,可参考 模型策略 了解更多细节。

export MIDSCENE_MODEL_BASE_URL="https://替换为你的模型服务地址/v1"
export MIDSCENE_MODEL_API_KEY="替换为你的 API Key"
export MIDSCENE_MODEL_NAME="替换为你的模型名称"
export MIDSCENE_MODEL_FAMILY="替换为你的模型系列"

更多配置信息请参考 模型策略模型配置

准备工作

继续之前,请确保 WebDriverAgent 可以与设备通信。

准备工作

安装 Node.js

安装 Node.js 18 或以上版本

准备 API Key

准备一个视觉语言(VL)模型的 API Key。

你可以在 模型策略 文档中查看 Midscene.js 支持的模型和配置。

准备 WebDriver 服务

在开始之前,你需要先设置 iOS 开发环境:

  • macOS(iOS 开发必需)
  • Xcode 和 Xcode 命令行工具
  • iOS 模拟器或真机设备

配置环境

在使用 Midscene iOS 之前,需要先准备 WebDriverAgent 服务。

版本要求

WebDriverAgent 版本需要 >= 7.0.0

请参考官方文档进行设置:

验证环境配置

配置完成后,可以通过访问 WebDriverAgent 的状态接口来验证 服务是否启动:

访问地址http://localhost:8100/status

正确响应示例

{
  "value": {
    "build": {
      "version": "10.1.1",
      "time": "Sep 24 2025 18:56:41",
      "productBundleIdentifier": "com.facebook.WebDriverAgentRunner"
    },
    "os": {
      "testmanagerdVersion": 65535,
      "name": "iOS",
      "sdkVersion": "26.0",
      "version": "26.0"
    },
    "device": "iphone",
    "ios": {
      "ip": "10.91.115.63"
    },
    "message": "WebDriverAgent is ready to accept commands",
    "state": "success",
    "ready": true
  },
  "sessionId": "BCAD9603-F714-447C-A9E6-07D58267966B"
}

如果能够正常访问该端点并返回类似上述的 JSON 响应,说明 WebDriverAgent 已经正确配置并运行。

试用 Playground

Playground 是验证连接、观察 AI 驱动步骤的最快方式,无需编写代码。它与 @midscene/ios 共享相同的核心,因此在 Playground 中通过的流程,在脚本中运行会保持一致。

  1. 启动 Playground CLI:
npx --yes @midscene/ios-playground
  1. 点击窗口中的齿轮按钮进入配置页,粘贴你的 API Key 配置。如果还没有 API Key,请回到 模型配置 获取。

开始体验

配置完成后,你可以立即开始体验 Midscene。它提供了多个关键操作 Tab:

  • Act: 与网页进行交互,这就是自动规划(Auto Planning),对应于 aiAct 方法。比如
在搜索框中输入 Midscene,执行搜索,跳转到第一条结果
填写完整的注册表单,注意主要让所有字段通过校验
  • Query: 从界面中提取 JSON 结构的数据,对应于 aiQuery 方法。

类似的方法还有 aiBoolean(), aiNumber(), aiString(),用于直接提取布尔值、数字和字符串。

提取页面中的用户 ID,返回 { id: string } 结构的 JSON 数据
  • Assert: 理解页面,进行断言,如果不满足则抛出错误,对应于 aiAssert 方法。
页面上存在一个登录按钮,它的下方有一个用户协议的链接
  • Tap: 在某个元素上点击,这就是即时操作(Instant Action),对应于 aiTap 方法。
点击登录按钮

关于自动规划(Auto Planning)和即时操作(Instant Action)的区别,请参考 API 文档。

集成 Midscene Agent

当 Playground 工作正常后,就可以切换到可复用的 JavaScript 脚本。

第 1 步:安装依赖

npm
yarn
pnpm
bun
deno
npm install @midscene/ios --save-dev

第 2 步:编写脚本

下面的示例会在设备上打开 Safari,搜索 eBay,并断言结果列表。

./demo.ts
import {
  IOSAgent,
  IOSDevice,
  agentFromWebDriverAgent,
} from '@midscene/ios';

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
Promise.resolve(
  (async () => {
    // 方式一:直接创建设备和 Agent
    const page = new IOSDevice({
      wdaPort: 8100,
      wdaHost: 'localhost',
    });

    // 👀 初始化 Midscene Agent
    const agent = new IOSAgent(page, {
      aiActionContext:
        'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
    });
    await page.connect();

    // 方式二:使用便捷函数(推荐)
    // const agent = await agentFromWebDriverAgent({
    //   wdaPort: 8100,
    //   wdaHost: 'localhost',
    //   aiActionContext: 'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
    // });

    // 👀 直接打开 ebay.com(推荐做法)
    await page.launch('https://ebay.com');
    await sleep(3000);

    // 👀 输入关键字并执行搜索
    await agent.aiAct('Search for "Headphones"');

    // 👀 等待加载完成
    await agent.aiWaitFor('At least one headphone product is displayed on the page');
    // 或简单地等待几秒:
    // await sleep(5000);

    // 👀 理解页面内容并提取数据
    const items = await agent.aiQuery(
      '{itemTitle: string, price: Number}[], find product titles and prices in the list',
    );
    console.log('Headphone product information', items);

    // 👀 使用 AI 断言
    await agent.aiAssert('Multiple headphone products are displayed on the interface');

    await page.destroy();
  })(),
);

第 3 步:运行示例

npx tsx demo.ts

第 4 步:查看报告

脚本成功后会输出 Midscene - report file updated: /path/to/report/some_id.html。在浏览器中打开对应 HTML 文件即可回放每一步交互、查询与断言。

API 参考与更多资源

需要查看构造函数、辅助方法或平台专属设备 API?请移步 iOS API 参考 获取详细参数及自定义操作等高级主题。若想了解跨平台共用的 API,可阅读 通用 API 参考

常见问题

为什么 WebDriverAgent 已连接,但仍无法控制设备?

请检查以下事项:

  1. 开发者模式:在“设置 > 隐私与安全性 > 开发者模式”中确认已开启。
  2. UI Automation:在“设置 > 开发者 > UI Automation”中确认已开启。
  3. 设备信任:确保设备信任当前 Mac。

模拟器与真机有哪些区别?

特性真机模拟器
端口转发需要 iproxy不需要
开发者模式必须手动开启默认开启
UI Automation 设置需手动开启默认开启
性能真实设备性能取决于 Mac 性能
传感器真实硬件模拟数据

如何自定义 WebDriverAgent 的端口和 Host?

可以通过 IOSDevice 构造函数或 agentFromWebDriverAgent 来指定端口和 Host:

// 方式一:使用 IOSDevice
const device = new IOSDevice({
  wdaPort: 8100,        // 自定义端口
  wdaHost: '192.168.1.100', // 自定义主机
});

// 方式二:使用便捷函数(推荐)
const agent = await agentFromWebDriverAgent({
  wdaPort: 8100,        // 自定义端口
  wdaHost: '192.168.1.100', // 自定义主机
});

针对远程设备,还需要按需设置端口转发:

iproxy 8100 8100 YOUR_DEVICE_ID

更多