# 图像识别脚本的工作原理：MAS 核心概念

> 图像识别脚本在 MAS 中如何工作：模板图片和 OCR 读取安卓屏幕，拟人化输入通过 adb 发送，以及宏在哪里运行。

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

Macro Automation Studio（MAS）像人一样自动化安卓应用：看屏幕、做判断、然后点击。这一页解释图像识别脚本是如何工作的、你在应用里会遇到的名词，以及每个部分在哪里运行。读完这一页，其余的文档就都能看懂了。

## 图像识别脚本如何"看"屏幕

MAS 不修改 APK，也不读取应用内存。它从外部通过 adb 工作，依靠三个基本构件。

### 模板图片

模板是屏幕上的一小块裁剪：一个按钮、一个图标、一个角标。你在 Asset Lab 中从实时设备画面裁剪它，它会带着一个数字 ID 进入你的图片库，脚本通过这个 ID 引用它。运行时，`find_object` 截取一张新截图，用 OpenCV 模板匹配在其中搜索模板。匹配默认需要 0.8 的相似度（`threshold=0.8`），返回中心点，所以下一行就可以点击。

图片文件可以是 jpg、png、gif 或 webp，单张最大 10 MB。模板要小而有辨识度：整屏截图只能匹配那一个屏幕，而一个按钮在任何出现的地方都能匹配。

### 安卓上的 OCR 自动化

文字通过 `read_text` 用 Tesseract OCR 读取。你传入一个 `Region(x1, y1, x2, y2)`，让引擎只看一个计数器或一个标签，而不是整个屏幕，再加上一个页面分割模式（`psm=7` 表示单行，`psm=8` 表示单个词）。`ColorConversion.BLACK_WHITE` 对嘈杂背景上的彩色文字很有帮助。Asset Lab 有实时 OCR 测试，你可以在写进代码之前先调好区域。

### 拟人化输入

输入以真实的触摸和按键事件发送：`click`、`swipe`、`input_text`、`key_press`、`zoom_in` 和 `zoom_out`。时间节奏由你决定。`click` 在点击后等待 `delay_ms=1000`，`swipe` 持续 `duration_ms=1000`，按住 500 毫秒以上的按键算作长按。更慢、间隔更松的宏看起来没那么机械。

### 坐标与屏幕尺寸

每个坐标都是相对屏幕左上角的像素偏移。`get_screen_size()` 返回宽和高；`get_device_info()` 返回同样的信息外加设备名称。模板和区域与你截取它们时的分辨率和 DPI 绑定，所以运行同一个宏的每台设备都要和制作时的分辨率保持一致。各篇模拟器指南推荐了每款模拟器的尺寸，云设备则以固定的显示预设创建。

## 术语表

| 术语 | 在 MAS 中的含义 |
|---|---|
| 宏 | 在一台设备上自动化一项任务的 Python 程序。你运行、定时、分享和出售的单位。 |
| 项目 | 宏背后的文件夹：`src/app.py`、可选的参数表单、资源和 git 历史。 |
| 设备 | MAS 能驱动的一个安卓目标，用它的 adb 端口标识；云设备则用它的 ID。 |
| 设备组 | **设备组**页上一组有名字的设备。组里每台设备都有自己的宏、参数、代理和 Webhook；**全部启动**会依次运行它们。 |
| 设置方案 | 一个宏的一组有名字的参数值。设备跟随某个方案，修改方案会更新所有使用它的设备。"Default" 方案始终存在。 |
| 云设备 | MAS 在自己的服务器上为你运行的安卓设备。它上面的宏在服务端运行，屏幕通过 WebRTC 串流。 |
| MAS Agent | **Agent** 页上的 AI 编写者。描述任务，它会探索设备，在需要决定时提问，并编译出一个通过 3 次验证运行的宏。 |
| Marketplace | 应用内的现成脚本目录。下载一个，它就成为**宏**页里的一个宏。 |
| Asset Lab | 在实时画面上裁剪模板、拾取坐标点和测试 OCR 区域的辅助工具。 |
| UI Builder | 参数表单（`.uibproj`）和运行时仪表盘（`.uibrt`）的设计器。 |
| Code Editor | MAS 内置的 Python IDE，从**宏**页按项目打开，带调试器和运行控制台。 |

## 各部分在哪里运行

有三个地方在干活，知道自己在看哪一个会很有帮助。

### 你的电脑驱动模拟器

你电脑或 Mac 上的 MAS 通过进程名和监听端口找到模拟器，然后用 `adb connect 127.0.0.1:<port>` 与每一个通信。本地设备的截图、点击和 OCR 都在你的机器上完成，所以宏运行期间应用必须保持打开。定时任务也是一样。

### 云设备在 MAS 的云端运行

云设备位于 MAS 的服务器上。你在它上面运行宏时，MAS 会上传项目的一个快照，并在设备旁边运行它。你可以在应用里实时观看屏幕，也可以完全关掉应用；运行都会继续。空闲的设备大约一小时不活动后会停止，并保留数据。

### 脚本通过 JSON-RPC 与应用通信

宏是一个普通的 Python 进程。MAS 在自己的 Python 3.13 环境中以 `python -u -m src.app` 启动它，并通过环境变量（`MAS_RPC_PORT`、`MAS_RPC_HOST`、`MAS_DEVICE_ID`、`MAS_SESSION_TOKEN`）传入连接信息。每个 `mas.*` 调用都是一个通过本地套接字发出的 JSON-RPC 2.0 请求；应用掌管 adb、OpenCV 和 Tesseract，并把结果送回来。在云设备上，同样的调用通过沙盒内的 unix 套接字传输。这就是为什么 `import mas` 不需要安装，也是为什么在 MAS 之外启动的脚本会报 "Could not discover RPC port"。

### AI 只在编写时参与，运行时不参与

MAS Agent 在探索和编译时消耗 AI 积分。它产出的宏是普通 Python，和其他宏一样在你的模拟器或云设备上运行，过程中不需要 Agent 参与。

## 订阅

应用里除登录页和**订阅**页之外的每一页都需要有效的订阅权限：免费试用或付费套餐。套餐按设备数计量，也就是你自己的模拟器或手机可以同时运行多少台。云设备是附加项，自带每月积分，还可以为 Agent 会话额外充值积分。取消订阅后，访问权限保留到已付费周期结束。[计费](/docs/billing)页解释具体机制；数字见[价格页](/pricing)。

## 下一步

在[设备](/docs/devices)页设置一台设备，在 [Asset Lab](/docs/asset-lab) 裁剪第一个模板，或者如果你更想从代码开始，阅读 [SDK 概览](/docs/sdk)。