# AI 自动操作手机：用 MAS Agent 从提示词生成宏

> 描述一个安卓自动化任务，让 MAS Agent 在模拟器或云设备上探索应用，得到一个经过验证、可在 Studio 中编辑的 Python 宏。

Source: https://automationmacro.com/zh-CN/docs/agent (MAS Agent, updated 2026-09-05)

MAS Agent 是 Macro Automation Studio（MAS）内置的、能 AI 自动操作手机应用的智能体。你用平常的话描述任务，Agent 就在设备上探索应用，绘制它的屏幕地图，从实时画面截取需要的按钮和读数，然后写出一个带模板图片和 OCR 区域的标准 MAS Python 宏。随后它在同一台设备上用 3 次验证运行检验这个宏，再交给你。从此以后，宏在没有模型参与的情况下重放，不消耗任何积分。

## 开始之前

- 已安装并登录 MAS，处于免费试用或付费套餐中。参见[安装](/docs/install)。
- 一台 Agent 可以驱动的设备：已在**设备组**中添加的运行中模拟器，或处于**就绪**状态的云设备。
- 要自动化的应用已装在该设备上，并已经通过登录页。
- 账户中有 AI 积分。[计费](/docs/billing)页解释积分如何运作。

## 用 Agent 开始一次安卓自动化会话

1. 在侧边栏打开 **Agent**。
2. 选择**设备**。列表分为**本地模拟器**和**云设备**两组。刚启动的模拟器没出现时，点击**刷新设备**。
3. 选择**提供方**和**模型**。**云端模型**在 MAS 服务器上运行，从你的 AI 积分中计费。
4. 在提示框中输入任务，例如"领取每日奖励并关闭所有弹窗"，然后点击**编写**。

会话在哪里运行取决于设备：

- **本地模拟器**：MAS 在你的机器上启动 Agent 引擎（"Starting the agent engine..."）。引擎通过 adb 与模拟器通信，所以模拟器和应用要保持打开。
- **云设备**：会话在 MAS 服务器上、设备旁边启动（"Running on our servers"）。你可以关掉应用，稍后再回来查看；对话保存在你的账户里。云设备始终使用**云端模型**。

每台设备同一时间只能运行一个 Agent。如果另一个聊天正占用同一台设备，MAS 会提供**前往那个聊天**或**停止它，在这里继续**。

## 阶段：Agent 如何从提示词生成宏

**概览**标签页显示当前阶段，**进度**清单用通俗的话跟踪它。

| 阶段 | Agent 在做什么 | 你看到的里程碑 |
|---|---|---|
| SCOUT | 探索应用，学习它的各个屏幕 | 聊天中的笔记 |
| PLAN | 写出计划并请你批准 | "Planning the automation..." |
| HARVEST | 在实时画面上裁剪模板图片、测量 OCR 区域 | "Capturing the buttons and readouts the macro will need..." |
| CODIFY | 编写 Python 项目 | "Writing your macro..." |
| REVIEW | 对照观察结果审阅草稿 | "Reviewing the generated code against what I observed..." |
| VALIDATE | 在你的设备上运行宏 | "Testing the macro on your device..." |
| REPAIR | 修复测试发现的问题，然后回到 HARVEST 或 CODIFY | "Fixing an issue found during testing..." |
| DONE | 交给你结果卡片 | "Done"，每次运行都通过时显示 "graduated" |

问题卡片打开期间，阶段显示为 WAITING_FOR_USER，会话计时暂停。修复受进度约束，而不是受次数约束：当同样的失败在未改动的代码上重复出现时，验证会暂停，直到 Agent 给出新的诊断或向你提问。25 个修复周期的硬上限会结束一个原本会无限循环的会话。

## 提问、计划与引导

Agent 会提问，而不是猜。当屏幕可能有两种解读，或某一步会花费或销毁某样东西时，它会停下来把问题交给你。

- 标题为 **Agent 需要你的输入**的问题卡片包含一到四个问题。选择一个选项或输入自定义答案，然后点击**发送回答**。
- 计划是这次会话的契约：目标、主循环和成功判定。任何游戏内消费都需要你事先批准一个上限值，Agent 才会在应用里花费任何东西。
- 想在运行中调整方向，在它工作时在输入框里输入内容并点击**引导**。消息会进入 Agent 的下一次决策。
- **停止**会立即结束会话。工作会被保存；在同一个聊天里发送后续消息即可继续。

## 预算与积分

**预算**面板显示这次会话的步数、积分（或费用）、token 和游戏内消费。预算为 0 表示不限制，每一项默认都是如此：你的积分余额才是真正的限制。余额归零时，MAS 拒绝进一步的模型调用，会话带着已有成果停止。

积分只在 Agent 探索、编写和测试时消耗。完成的宏在任何设备上运行都不消耗积分。Agent 页上的**积分**读数在会话进行中实时更新，**充值积分**会打开订阅页。机制见[计费](/docs/billing)页；费率见[价格页](/pricing)。

## 菜单地图

地图是 Agent 对一个应用的记忆：它见过的每个屏幕，以及连接这些屏幕的按钮。Agent 工作时地图会自动生长，**地图**标签页把它显示为一张图，并统计屏幕、跳转、点击和未探索按钮的数量。

- **绘制此应用地图**会有条理地遍历菜单（约 8 分钟）；**深度遍历**会打开更深的菜单（约 20 分钟）。两者都只做导航：遇到任何售卖内容 Agent 都会退出。
- **共享我的地图**会把你的遍历结果与其他绘制同一应用的账户汇总。贡献在被另一个账户证实之前保持私密，你可以在**我的贡献**下撤回。关闭共享后，你的地图仍然服务于你自己的会话。

## 添加到我的宏

结果卡片显示**完成**时，点击**添加到我的宏**。MAS 在你的项目文件夹中创建项目，把每张模板图片上传到图片库的 `agent/` 文件夹下，改写代码中的图片 ID，并初始化 git。聊天随后会提供**在 IDE 中打开**、在同一台设备上**测试运行**，以及一张计划卡片（**一次**、**每天**或**每周**，然后**创建计划**）。定时运行使用设备卡片上保存的参数。

之后要修改宏，在工作区列表的**改进**下选中它，描述要添加或更改的内容。Agent 会从现有项目出发，原地更新它。

## 项目包含什么

| 文件 | 用途 |
|---|---|
| `src/app.py` | 宏本体：`mas.images({...})` 注册表、每个屏幕一个函数、主循环 |
| `src/script_args.py` | 根据参数表单生成的参数解析器 |
| `script_runner.uibproj` | 供 UI Builder 使用的参数表单 |
| `images/manifest.json` | 所有采集模板的名称到文件映射；安装后文件仍保留 |
| `task.yaml` | 验证规范 |
| `agent_session.json` | 记录哪个会话编写了这个项目，供之后的改进会话使用 |
| `README.md` | 目标和参数表 |

`task.yaml` 记录任务名称、提示词、应用包名、设备、入口前置条件（启动时必须可见的模板）、超时、`script_runs: 3`、测试参数和检查项。检查类型有 `exit_code`、`template`、`ocr_region`、`storage`、`adb_shell`、`element_visible` 和 `element_text`，每一项带 `when: active`、`idempotent` 或 `always`。验证是冒烟测试：主循环限制为两次迭代。Studio 的运行时从不读取 `task.yaml`。

安装后，你可以像编辑其他项目一样编辑它：用完整 SDK 修改 `src/app.py` 里的流程，在 [Asset Lab](/docs/asset-lab) 和图片库中修改模板图片，在代码中修改 OCR 区域，在 [UI Builder](/docs/ui-builder) 中修改参数表单。[Studio 导览](/docs/studio)介绍编辑器、运行和调试器。

## 会玩手游的 AI，以及其他任何屏幕操作流程

MAS Agent 能处理模拟器和云设备上以屏幕为驱动的流程：探索时遇到的弹窗和打断、用 OCR 读取的计数器和计时器以便宏等待或跳过，以及在设备组上按计划执行同一套流程。对于无法从屏幕读出的决定、开始前的预算，以及任何破坏性操作或购买行为，它都会先问你。

它只从屏幕工作。它从不修改 APK，也不读取游戏内存，并且需要一台它能看见的设备。没有任何自动化工具是 100% 无风险的，请负责任地使用自动化，并自行斟酌决定。

同一个 Agent 也可以通过 [MCP 服务器](/docs/mcp)从 Claude Code、Cursor、Codex 和其他客户端访问，它暴露了 `author_macro`、`get_agent_session`、`answer_agent_session`、`stop_agent_session` 和 `get_map`。

## 故障排查

### Agent 提了一个问题并在等待

会话是有意暂停的，计时也停了，所以没有任何消耗。打开**聊天**标签页，回答卡片并点击**发送回答**。标记为 "Question expired" 的卡片属于已结束的会话；改在输入框中回复，后续会话会带着完整的对话开始。

### 验证一直失败

阅读聊天中失败的检查项：一个从未出现的模板、一个没匹配上的 OCR 模式，或一个宏从未保存的存储值。用你知道的信息**引导** Agent，或回答它的问题。如果模拟器崩溃了，Agent 会在连续五次设备错误后停止；重启模拟器并在聊天中发消息即可继续。

### 达到预算上限

会话结束是因为你设置的预算用完了，或者积分余额归零。工作已保存。从订阅页充值积分，或提高预算，然后在同一个聊天中发送后续消息。