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

> 在 Macro Automation Studio 中开始 Python 安卓模拟器自动化：连接设备，然后运行 Marketplace 脚本、让 MAS Agent 编写，或亲手写出第一个宏。

Source: https://automationmacro.com/zh-CN/docs/getting-started (开始, updated 2026-09-05)

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

## 开始之前

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

> [!NOTE]
> Python SDK 已经装好了。MAS 自带 Python 3.13 环境和 `mas` 包，所以在 Code Editor 里 `import mas` 直接可用，你不需要做任何配置。

## Macro Automation Studio 入门：选择设备

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

| 设备 | 运行位置 | 适合 |
|---|---|---|
| 模拟器（BlueStacks、LDPlayer、MuMu Player、MEmu） | 这台电脑上，通过 adb | 入门和本地测试 |
| 云设备 | MAS 的云端，通过 WebRTC 串流到应用 | 电脑关机后仍要继续的运行 |
| 你自己的手机 | 这台电脑上，通过 adb（进阶） | 只在真机上才正常的应用 |

添加模拟器：

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

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

## 获得宏的三种方式

### 运行 Marketplace 脚本

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

带截图的完整流程见[如何运行 Marketplace 中的宏](/docs/run-macro-from-marketplace)。发布你自己的脚本见 [Marketplace](/docs/marketplace) 页。

### 让 MAS Agent 编写

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

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

### 用 Python 写安卓模拟器自动化

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

[SDK 概览](/docs/sdk)解释了各个命名空间；[API 参考](/docs/api-reference)列出了每个函数。

## 你的第一个脚本

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

```python
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`。

```python
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`。

### 读取某个区域的文字

```python
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 里画出区域并实时测试，再把坐标复制过来。

### 处理错误

```python
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 或设备卡片运行脚本；应用启动脚本时会把连接信息传给它。

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

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

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

模拟器的 ADB 没开、模拟器还在启动，或者它监听的是另一个端口。参见 [ADB 故障排查](/docs/adb-troubleshooting)。