> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 开始使用：iOS · Playground · ChatGPT 订阅 {#get-started}

本页是在 **iOS** 上使用 **Playground**、通过 **ChatGPT 订阅**接入模型的配置步骤。如需其他组合，请查看[全部配置路径](/zh/get-started.md#all-setup-paths)。

## 通过 WDA 连接 iOS 设备
Midscene 通过运行中的 WebDriverAgent（WDA）服务与 iOS 真机或模拟器通信。如果 WDA 服务已启动且可从当前电脑访问，可直接跳至[确认 WDA 服务状态](#verify-wda-status)。

### 构建并启动 WebDriverAgent

开始前，请先准备好以下 iOS 开发环境：

- macOS（iOS 开发与真机调试必需）
- Xcode 及 Xcode 命令行工具（Command Line Tools）
- iOS 模拟器或真机设备

:::info 版本要求

WebDriverAgent 版本须 **>= 7.0.0**。

:::

请参考 Appium 官方文档完成 WebDriverAgent（WDA）的构建与启动：

- **模拟器配置**：[Run Prebuilt WDA](https://appium.github.io/appium-xcuitest-driver/latest/guides/run-prebuilt-wda/)
- **真机配置**：[Real Device Configuration](https://appium.github.io/appium-xcuitest-driver/latest/getting-started/device-setup/)

### 配置真机并转发端口

iOS 模拟器会直接在 `localhost` 上监听端口，无需转发；如果使用模拟器或已配置好的远程 WDA 服务，可跳至[确认 WDA 服务状态](#verify-wda-status)。

使用 iOS 真机时：

1. 使用 USB 数据线将手机连接到 Mac，并在手机弹窗中点击「信任此电脑」。
2. 在手机系统设置中开启**开发者模式**（「设置 > 隐私与安全性 > 开发者模式」）与 **UI Automation**（「设置 > 开发者 > Enable UI Automation」）。
3. 完成开发者证书签名并在真机上启动 WDA 后，使用 `iproxy`（可通过 `brew install libimobiledevice` 安装）将设备上的 WDA 端口（默认为 `8100`）转发到 Mac 本机：

```bash
iproxy 8100 8100 YOUR_DEVICE_ID
```

请将 `YOUR_DEVICE_ID` 替换为真机的实际 UDID，并保持 WDA 与 `iproxy` 进程持续运行。如果同时连接多台设备或使用了自定义端口，请为每台设备映射独立的本机端口，并在 Playground 或项目配置中填写对应端口。

### 确认 WDA 服务状态 {#verify-wda-status}

在运行 Midscene 的电脑上，通过浏览器或终端访问 WDA 的 `/status` 接口：

- **本机默认地址**：`http://localhost:8100/status`（若使用自定义端口、远程服务或网关，请访问实际的服务地址）
- **正常响应示例**：

```json
{
  "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 中包含 `"ready": true` 即表示 WDA 服务已就绪。请记录该服务的主机地址与端口（或网关地址），以便后续在 Playground 和项目配置中使用。

## 使用 ChatGPT 订阅登录

登录命令需要 Node.js `^20.19.0 || ^22.12.0 || >=24.0.0` 和 pnpm。请确认终端中可以执行 `node -v`；如果尚未安装 pnpm，请运行 `npm install -g pnpm`。

首先，在终端运行：

```bash
pnpm dlx @midscene/cli model siwc login
```

按照终端提示，在浏览器中登录 ChatGPT 并授权使用订阅额度。授权时可以自行设置 Agent 名称；完成后，可在 ChatGPT 的使用情况页面查看已授权的 Agent。

命令会将凭据保存到 `~/.midscene/siwc.json`。首次使用前需要手动完成这一步登录。

Playground 会读取该命令保存的凭据。请先保留以下配置，后面的步骤会把它粘贴到 Playground 设置中：

```bash
MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"
```
可用模型以你的 ChatGPT 账号为准。凭据与额度说明请参阅[使用 ChatGPT 订阅](/zh/chatgpt-subscription.md#额度与凭据)。

## 启动 Playground

请确保已安装 Node.js（版本要求 `^20.19.0 || ^22.12.0 || >=24.0.0`），且终端中可正常执行 `node -v`。下方命令使用 pnpm，如果尚未安装，请运行 `npm install -g pnpm`。

1. 在终端运行以下命令启动 iOS Playground：

```bash
pnpm dlx @midscene/ios-playground
```

2. 在打开的 Playground 页面中，点击右上角的齿轮图标，粘贴模型配置并保存。
3. 若浏览器未自动打开，请手动访问终端打印的本地地址，并保持该终端进程持续运行。
4. 若页面弹出连接面板，请填写 WDA 的主机地址与端口（本机默认为 `localhost` 和 `8100`）并创建 Agent（若本机默认端口上的 WDA 已就绪，Playground 可能会自动完成连接；若通过网关代理访问 WDA，请填写完整的 **WebDriverAgent base URL**，切勿同时填写 host / port）。
5. 确认预览区域已正常显示当前设备或模拟器的屏幕画面；若画面未显示，请先排查 WDA 连接与端口转发。

## 执行操作并验证结果

在 iOS 设备或模拟器上打开 Safari 浏览器，跳过首次启动引导，然后在地址栏中输入以下 TodoMVC 地址：

```text
https://todomvc.com/examples/react/dist/#/
```

保持设备解锁且 Safari 位于前台。

1. 在 Playground 中选择 `aiAct`，输入以下指令并运行：

```text
添加一个名为“体验 Midscene”的待办事项，然后将它标记为已完成。
```

2. 待页面中出现已勾选完成的待办事项后，切换到 `aiAssert`，输入以下断言并运行：

```text
列表中存在名为“体验 Midscene”的待办事项，且它已被标记为完成。
```

3. 确认断言执行通过，并在结果面板中查看各步骤的截图与执行过程。至此，WDA 连接、屏幕截图、触控输入和模型调用均已验证完毕。

4. （可选）切换到 `aiQuery`，输入以下查询并运行：

```text
列表中可见的待办事项，返回 {name: string, completed: boolean}[]。
```

结果会包含待办事项名称及其完成状态。`aiQuery` 用于从当前界面提取数据，不会修改页面。

如果执行失败，请结合报错信息排查：若无画面或无法操控设备，请查看[常见问题](/zh/platforms/ios.md#常见问题)；若模型请求报错，请参考[模型连接检查](/zh/model-config.md#verify-model-connectivity)。

验证结束后，请在 TodoMVC 页面中删除刚才创建的“体验 Midscene”待办事项。如果接下来要运行 Midscene Test 的 iOS 示例，请切换到 **All** 视图并确认列表已完全清空（包括已完成事项），因为示例模板在运行前会校验初始列表为空，且不会主动覆盖已有数据。

## 下一步
- **查看更多案例**：[案例展示](/zh/showcases.md)收录了各平台的演示视频和完整执行报告。

- **编写可重复运行的用例**：使用相同的平台和模型[创建 Midscene Test 项目](/zh/get-started/ios-test-chatgpt.md)。用例是 YAML 文件，可以在本地或 CI 中运行。

- **接入 Vitest**：使用相同的平台和模型，[在 Vitest 测试中调用 Midscene](/zh/get-started/ios-sdk-chatgpt.md)。

- **了解 Midscene 的工作方式**：[基本概念](/zh/basics.md)介绍了基于视觉的方案，以及 `aiAct`、即时操作和洞察类 API 的适用场景。