#API 参考（Android）

当你需要自定义设备行为、把 Midscene 接入框架，或排查 adb 问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等）的参数说明，请参考平台无关的 API 参考。

#Action Space（动作空间）

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

• Tap —— 点击元素。
• DoubleClick —— 双击元素。
• Input —— 输入文本，支持 replace/typeOnly/clear 模式（append 是 typeOnly 的已废弃别名）。支持可选参数 autoDismissKeyboard。
• Scroll —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
• DragAndDrop —— 从一个元素拖拽到另一个元素。
• KeyboardPress —— 按下指定键位。
• LongPress —— 长按目标元素，可选自定义时长。
• PullGesture —— 上拉或下拉（如下拉刷新），可选距离与持续时间。
• Pinch —— 双指缩放手势。scale > 1 放大，scale < 1 缩小。
• ClearInput —— 清空输入框内容。
• Launch —— 打开网页或 package/.Activity。
• Terminate —— 按包名强制停止应用。
• RunAdbShell —— 执行原始 adb shell 命令。
• AndroidBackButton —— 触发系统返回。
• AndroidHomeButton —— 回到桌面。
• AndroidRecentAppsButton —— 打开多任务/最近应用。

#AndroidDevice

创建一个可供 AndroidAgent 驱动的 adb 设备实例。

#导入

import { AndroidDevice, getConnectedDevices } from '@midscene/android';

#构造函数

const device = new AndroidDevice(deviceId, {
  // 设备参数...
});

#设备选项

• deviceId: string —— 来自 adb devices 或 getConnectedDevices() 的值。
• autoDismissKeyboard?: boolean —— 输入完成后自动隐藏键盘，默认 true。
• keyboardDismissStrategy?: 'esc-first' | 'back-first' —— 关闭键盘的顺序，默认 'esc-first'。
• androidAdbPath?: string —— adb 可执行文件的自定义路径。
• remoteAdbHost?: string / remoteAdbPort?: number —— 指向远程 adb server。
• imeStrategy?: 'always-yadb' | 'yadb-for-non-ascii' —— 控制何时调用 yadb 进行文本输入，默认 'yadb-for-non-ascii'。
  • 'yadb-for-non-ascii'（默认）—— 对 Unicode 字符（包括 Latin Unicode 如 ö、é、ñ）、中文、日文以及格式化符号（如 %s、%d）使用 yadb。纯 ASCII 文本使用更快的原生 adb input text。
  • 'always-yadb' —— 对所有文本输入始终使用 yadb，提供最大兼容性，但对纯 ASCII 文本稍慢。
• displayId?: number —— 在设备镜像多个屏幕时，选择特定虚拟屏幕。
• screenshotResizeScale?: number —— 已废弃。 此选项已移除，不再生效。如需控制发送给 AI 模型的截图尺寸，请使用 AgentOpt 中的 screenshotShrinkFactor。
• alwaysRefreshScreenInfo?: boolean —— 每一步都重新查询旋转角度与屏幕尺寸，默认 false。
• scrcpyConfig?: object —— Scrcpy 高性能截图配置，默认关闭。详见下方 Scrcpy 截图模式。

#Scrcpy 截图模式

默认情况下，Midscene 通过 adb shell screencap 截图，每次耗时约 500–2000ms。开启 Scrcpy 模式后，通过 H.264 视频流实时获取画面，每次截图耗时约 100–200ms。

开启方式：

const device = new AndroidDevice(deviceId, {
  scrcpyConfig: {
    enabled: true,
  },
});

可选参数：

#使用说明

• 可以使用 getConnectedDevices() 发现设备，udid 与 adb devices 输出一致。
• 可以使用 remoteAdbHost/remoteAdbPort 连接远程 adb；如果 adb 不在 PATH 中，可设置 androidAdbPath。

#示例

#快速开始

import { AndroidAgent, AndroidDevice, getConnectedDevices } from '@midscene/android';

const [first] = await getConnectedDevices();
const device = new AndroidDevice(first.udid);
await device.connect();

const agent = new AndroidAgent(device, {
  aiActionContext: 'If a permissions dialog appears, accept it.',
});

await agent.launch('https://www.ebay.com');
await agent.aiAct('search "Headphones" and wait for results');
const items = await agent.aiQuery(
  '{itemTitle: string, price: number}[], find item in list and corresponding price',
);
console.log(items);

#启动原生 App

await agent.launch('com.android.settings/.Settings');
await agent.back();
await agent.home();

#AndroidAgent

将 Midscene 的 AI 规划能力绑定到 AndroidDevice，实现 UI 自动化。

#导入

import { AndroidAgent } from '@midscene/android';

#构造函数

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

#Android 特有选项

• customActions?: DeviceAction[] —— 通过 defineAction 扩展规划器的可用动作。
• appNameMapping?: Record<string, string> —— 将友好的应用名称映射到包名。当你在 launch(target) 里传入应用名称时，Agent 会在此映射中查找对应的包名；若未找到映射，则按原样尝试启动 target。
• 其余字段与 API constructors 一致：generateReport、reportFileName、aiActionContext、modelConfig、cacheId、createOpenAIClient、onTaskStartTip 等。

#使用说明

#Android 特有方法

#agent.launch()

启动网页或原生 Android activity/package。

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

• target: string —— 可以是网页 URL，也可以是 package/.Activity 形式的字符串，例如 com.android.settings/.Settings，也可以是应用包名、URL 或应用名称。若传入应用名称且在 appNameMapping 中存在映射，将自动解析为对应包名；若未找到映射，则直接按 target 启动。

#agent.runAdbShell()

通过连接的设备运行原始的 adb shell 命令。

function runAdbShell(command: string): Promise<string>;

• command: string —— 原样传递给 adb shell 的命令。

const result = await agent.runAdbShell('dumpsys battery');
console.log(result);

#agent.terminate()

终止（强制停止）正在运行的 Android 应用。

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

• uri: string —— 应用包名、appNameMapping 中的应用名称，或 package/.Activity（仅使用包名部分）。

await agent.terminate('com.android.settings');

#导航辅助

• agent.back(): Promise<void> —— 触发 Android 系统的返回操作。
• agent.home(): Promise<void> —— 返回桌面。
• agent.recentApps(): Promise<void> —— 打开多任务/最近应用界面。

#辅助工具

#agentFromAdbDevice()

从任意已连接的 adb 设备创建 AndroidAgent。

function agentFromAdbDevice(
  deviceId?: string,
  opts?: PageAgentOpt & AndroidDeviceOpt,
): Promise<AndroidAgent>;

• deviceId?: string —— 连接特定设备；留空表示使用“第一个可用设备”。
• opts?: PageAgentOpt & AndroidDeviceOpt —— 在一个对象中合并 Agent 选项与 AndroidDevice 的设置。

#getConnectedDevices()

列举 Midscene 可驱动的 adb 设备。

function getConnectedDevices(): Promise<Array<{
  udid: string;
  state: string;
  port?: number;
}>>;

#相关阅读

• Android 快速开始 获取搭建与脚本示例。