Python 安卓模拟器自动化入门指南

Macro Automation Studio（MAS）通过屏幕来驱动安卓应用：它观察设备画面，找到需要的元素，然后点击。这一页带你从全新安装走到第一个 Python 安卓模拟器自动化宏跑起来，目标可以是安卓模拟器、云设备或你自己的手机。适合在 Windows 或 Mac 上第一次使用的用户。

开始之前

• 已安装 MAS 并登录。参见安装 MAS。
• 有可以自动化的目标：这台电脑上的安卓模拟器、一台云设备，或你自己的手机。参见设备。
• 账户有有效的订阅或免费试用。应用里除登录页和订阅页之外的每一页都需要它。没有订阅时，MAS 会打开订阅页并停在那里。套餐见价格页。

Macro Automation Studio 入门：选择设备

每次运行只针对一台设备。选一种适合你的：

添加模拟器：

1. 启动模拟器，在它的设置中打开 ADB。每篇模拟器指南都会说明这个设置在哪里。
2. 在 MAS 中打开设备组，点击新建组。类型保持本地。
3. 打开这个组，点击添加设备。
4. 输入设备名称，在端口列表中选择模拟器的端口。列表为空时点击刷新。
5. 点击添加设备。

云设备在云设备页用创建按钮创建，之后会和本地设备一起出现在运行目标中。手机的接入方式见设备页。

获得宏的三种方式

运行 Marketplace 脚本

1. 打开 Marketplace，搜索应用或游戏。
2. 打开一个条目，点击下载。脚本会出现在宏页面，并带有”从 Marketplace 下载”标签。
3. 在设备组中打开你的组，在设备的宏选择器里选中这个脚本，点击启动。
4. 在设备卡片的日志标签页查看进度。完成后点击停止。

带截图的完整流程见如何运行 Marketplace 中的宏。发布你自己的脚本见 Marketplace 页。

让 MAS Agent 编写

1. 打开 Agent，在设备下选择一台设备。
2. 用平常的话描述任务，点击编写。
3. 当出现”Agent 需要你的输入”卡片时回答它。Agent 会停下来提问，而不是猜。
4. 宏通过 3 次验证运行后，点击添加到我的宏。

结果是一个普通的 Python 项目，可以在 Code Editor 中打开。编写过程消耗 AI 积分；运行完成的宏不消耗任何积分。详见 MAS Agent 页。

用 Python 写安卓模拟器自动化

1. 打开宏，点击新建项目。
2. 选择代码型，把目标设备设为移动端，给项目命名，点击创建项目。
3. 打开项目。Code Editor 会显示 src/app.py。粘贴下面的脚本。
4. 选择你的设备，点击运行（F5）。停止是 Shift+F5，保存是 Ctrl+S。

SDK 概览解释了各个命名空间；API 参考列出了每个函数。

你的第一个脚本

这个脚本读取设备信息、截一张图，并对整个屏幕做 OCR。设备上不会有任何改动。

import mas

device = mas.get_device_info()
print(f"Connected to: {device.name}")

screen = mas.get_screen_size()
print(f"Screen: {screen.width}x{screen.height}")

shot = mas.take_screenshot()
print(f"Screenshot: {shot.width}x{shot.height}")

result = mas.read_text()
print(f"Screen text: {result.text[:100]}")

mas.log("First script finished")

mas.log 向运行控制台写入一条带级别的日志。普通的 print 也可以。

常用模式

找图并点击

在 Asset Lab 中裁剪按钮，它会带着一个 ID 进入你的图片库，然后用 mas.images 声明它。find_object_retry 最多查找三次，每次间隔两秒，没有匹配时返回 None。

import mas

images = mas.images({"play_button": 42})

match = mas.find_object_retry(images.play_button, total_tries=3, time_sleep=2.0)
if match:
    mas.click(match.x, match.y, delay_ms=1000)
else:
    mas.log("Play button not found", level="warning")

find_object 默认使用 0.8 的匹配阈值。click 在点击后等待 1000 毫秒让应用响应；在紧凑的循环里可以调低 delay_ms。

读取某个区域的文字

import mas
from mas import Region

score = mas.read_text(region=Region(x1=800, y1=10, x2=1050, y2=60), psm=7)
if score.text.strip().isdigit():
    print(f"Current score: {int(score.text)}")

psm=7 把区域当作单行文本处理，适合计数器。先在 Asset Lab 里画出区域并实时测试，再把坐标复制过来。

处理错误

import mas

try:
    match = mas.find_object_retry(42)
    if match:
        mas.click(match.x, match.y)
except mas.DeviceNotConnectedError:
    mas.log("No device connected", level="error")
except mas.ImageNotFoundError:
    mas.log("Image ID is not in your library", level="error")
except mas.TimeoutError:
    mas.log("The device did not answer in time", level="error")
except mas.RPCError as e:
    mas.log(f"RPC error: {e}", level="error")

故障排查

Could not discover RPC port

脚本是在 MAS 之外启动的，或者应用没有运行。请从 Code Editor 或设备卡片运行脚本；应用启动脚本时会把连接信息传给它。

应用打开的是订阅页，而不是我点击的页面

你的订阅权限缺失或已过期。开始试用或选择一个套餐，然后再回来。参见计费。

找不到设备，或一直停在”连接中”

模拟器的 ADB 没开、模拟器还在启动，或者它监听的是另一个端口。参见 ADB 故障排查。