#API 参考（iOS）

当你需要自定义 iOS 设备行为、将 Midscene 接入依赖 WebDriverAgent 的工作流，或排查 WDA 请求问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等），请参考平台无关的 API 参考。

#Action Space（动作空间）

IOSDevice 使用以下动作空间，Midscene Agent 在规划任务时可以使用这些操作：

• Tap —— 点击元素。
• DoubleClick —— 双击元素。
• Input —— 输入文本，支持 replace/typeOnly/clear 模式（append 是 typeOnly 的已废弃别名）。支持可选参数 autoDismissKeyboard。
• Scroll —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
• DragAndDrop —— 从一个元素拖拽到另一个元素。
• KeyboardPress —— 按下指定键位。
• LongPress —— 长按目标元素，可选自定义时长。
• Pinch —— 双指缩放手势。scale > 1 放大，scale < 1 缩小。
• ClearInput —— 清空输入框内容。
• Launch —— 打开网页、Bundle ID 或 URL Scheme。
• Terminate —— 通过 Bundle ID 关闭正在运行的 iOS 应用。
• RunWdaRequest —— 直接调用 WebDriverAgent REST 接口。
• IOSHomeButton —— 执行 iOS 系统 Home 操作。
• IOSAppSwitcher —— 打开 iOS 多任务视图。

#IOSDevice

创建一个由 WebDriverAgent 支撑、供 IOSAgent 驱动的设备连接。

#导入

import { IOSDevice } from '@midscene/ios';

#构造函数

const device = new IOSDevice({
  // 设备参数...
});

#设备选项

• wdaPort?: number —— WebDriverAgent 端口，默认 8100。
• wdaHost?: string —— WebDriverAgent host，默认 'localhost'。
• iOSDeviceClassOverride?: string —— 使用 agentFromWebDriverAgent() 或 iOS Playground 时替换默认 IOSDevice 的 npm module path。目标模块必须导出 IOSDevice class 或 default class。
• autoDismissKeyboard?: boolean —— 文本输入后自动隐藏键盘，默认 true。
• customActions?: DeviceAction<any>[] —— 向 Agent 暴露的额外设备动作。

#使用说明

• 请确认已开启开发者模式且 WDA 能访问设备；真机转发端口时可借助 iproxy。
• 通过 wdaHost/wdaPort 可指向远程设备或自建的 WDA。
• 通用交互方法请查阅 API 参考（通用）。

#示例

#快速开始

import { IOSAgent, IOSDevice } from '@midscene/ios';

const device = new IOSDevice({ wdaHost: 'localhost', wdaPort: 8100 });
await device.connect();

const agent = new IOSAgent(device, {
  aiActionContext: 'If any permission dialog appears, accept it.',
});

await agent.launch('https://ebay.com');
await agent.aiAct('Search for \"Headphones\"');
const items = await agent.aiQuery(
  '{itemTitle: string, price: Number}[], list headphone products',
);
console.log(items);

#自定义 Host 与端口

const device = new IOSDevice({
  wdaHost: '192.168.1.100',
  wdaPort: 8300,
});
await device.connect();

#IOSAgent

将 Midscene 的 AI 规划能力绑定到 IOSDevice，通过 WebDriverAgent 实现 UI 自动化。

#导入

import { IOSAgent } from '@midscene/ios';

#构造函数

const agent = new IOSAgent(device, {
  // 通用 Agent 参数...
});

#iOS 特有选项

• customActions?: DeviceAction<any>[] —— 通过 defineAction 扩展规划器的可用动作。
• appNameMapping?: Record<string, string> —— 将友好的应用名称映射到 Bundle Identifier。当你在 launch(target) 或 terminate(bundleId) 里传入应用名称时，Agent 会在此映射中查找对应的 Bundle ID；若未找到映射，则按原样使用 target。用户提供的 appNameMapping 优先级高于默认映射。
• 其余字段与 API constructors 一致：generateReport、reportFileName、aiActionContext、modelConfig、cacheId、createOpenAIClient、onTaskStartTip 等。

#使用说明

#iOS 特有方法

#agent.launch()

打开网页、原生应用或自定义 Scheme。

function launch(target: string): Promise<void>;

• target: string —— 目标地址（网页 URL、Bundle Identifier、URL scheme、tel/mailto 等）或应用名称。若传入应用名称且在 appNameMapping 中存在映射，将自动解析为对应 Bundle ID；若未找到映射，则直接按 target 启动。

await agent.launch('https://www.apple.com');
await agent.launch('com.apple.Preferences');
await agent.launch('myapp://profile/user/123');
await agent.launch('tel:+1234567890');

#agent.terminate()

通过 Bundle ID 终止（关闭）正在运行的 iOS 应用。

function terminate(bundleId: string): Promise<void>;

• bundleId: string —— 要终止的应用的 Bundle Identifier（如 com.apple.Preferences）。若传入应用名称且在 appNameMapping 中存在映射，将自动解析为对应 Bundle ID。

await agent.terminate('com.apple.Preferences');
await agent.terminate('com.apple.mobilesafari');

#agent.runWdaRequest()

当你需要更底层的控制能力时，执行原始的 WebDriverAgent REST 请求。

function runWdaRequest(
  method: string,
  endpoint: string,
  data?: Record<string, any>,
): Promise<any>;

• method: string —— HTTP 动词（GET、POST、DELETE 等）。
• endpoint: string —— WebDriverAgent 接口路径。
• data?: Record<string, any> —— 可选的 JSON 请求体。

const screen = await agent.runWdaRequest('GET', '/wda/screen');
await agent.runWdaRequest('POST', '/session/test/wda/pressButton', { name: 'home' });

#应用间导航

• agent.home(): Promise<void> —— 回到主屏。
• agent.appSwitcher(): Promise<void> —— 打开多任务视图。

#辅助工具

#agentFromWebDriverAgent()

连接 WebDriverAgent 并返回可用的 IOSAgent。

function agentFromWebDriverAgent(
  opts?: PageAgentOpt & IOSDeviceOpt,
): Promise<IOSAgent>;

• opts?: PageAgentOpt & IOSDeviceOpt —— 在一个对象中同时传入通用 Agent 选项与 IOSDevice 的配置。
• 设置 MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE 可通过环境变量应用同一个设备 class override。显式传入的选项优先级高于环境变量。

import { agentFromWebDriverAgent } from '@midscene/ios';

const agent = await agentFromWebDriverAgent({
  wdaHost: 'localhost',
  wdaPort: 8100,
  iOSDeviceClassOverride: '@your-scope/ios-device',
  aiActionContext: 'Accept permission dialogs automatically.',
});

#扩展自定义交互动作

通过 defineAction 创建处理器并传入 customActions，即可扩展 Agent 的动作空间。这些动作会追加在内置动作之后，可在规划阶段被调用。

import { getMidsceneLocationSchema, z } from '@midscene/core';
import { defineAction } from '@midscene/core/device';
import { agentFromWebDriverAgent } from '@midscene/ios';

const ContinuousClick = defineAction({
  name: 'continuousClick',
  description: 'Click the same target repeatedly',
  paramSchema: z.object({
    locate: getMidsceneLocationSchema(),
    count: z
      .number()
      .int()
      .positive()
      .describe('How many times to click'),
  }),
  async call({ locate, count }) {
    console.log('click target center', locate.center);
    console.log('click count', count);
  },
});

const agent = await agentFromWebDriverAgent({
  customActions: [ContinuousClick],
});

await agent.aiAct('Click the red button five times');

#相关阅读

• iOS 快速开始 获取搭建与脚本示例。
• 与任意界面集成 查看自定义动作与 Schema 细节。