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

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 绑定，所以运行同一个宏的每台设备都要和制作时的分辨率保持一致。各篇模拟器指南推荐了每款模拟器的尺寸，云设备则以固定的显示预设创建。

术语表

各部分在哪里运行

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

你的电脑驱动模拟器

你电脑或 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 会话额外充值积分。取消订阅后，访问权限保留到已付费周期结束。计费页解释具体机制；数字见价格页。

下一步

在设备页设置一台设备，在 Asset Lab 裁剪第一个模板，或者如果你更想从代码开始，阅读 SDK 概览。