Maa 教程

外观

MaaFW 是什么

约 1486 字大约 5 分钟

MaaFW，全称 MaaFramework。它是基于图像识别和模拟操作的自动化黑盒测试框架，在 MAA（《明日方舟》小助手）的开发经验基础上去芜存菁、完全重写，低代码的同时拥有高扩展性。

图像识别：先看见

MaaFW 的判断依据主要来自截图。

它会从设备、模拟器或桌面窗口获取当前画面，然后用不同识别方式判断目标是否出现，例如：

  • OCR：识别画面中的文字
  • TemplateMatch：匹配你准备好的模板图片
  • FeatureMatch：用特征点匹配更复杂的图像目标
  • ColorMatch：根据颜色范围判断目标状态

对新手来说，识别方式不用急着记全。大部分情况下，识别方式的作用就是：判断当前画面是否符合某个条件。

模拟操作：再动手

识别命中以后，MaaFW 会执行对应的动作。大部分动作是通过控制器模拟用户输入，常见动作包括：

  • 点击目标位置
  • 滑动屏幕
  • 输入文本
  • 按键
  • 启动或关闭应用

这些动作不是直接调用目标应用的业务接口，而是模拟用户或系统输入。

黑盒：不依赖内部实现

黑盒的意思是：MaaFW 不关心目标应用内部怎么实现的，只看最终呈现出来的画面，然后模拟操作。

这带来好处，也有代价。

好处是：

  • 可以处理没有公开 API 的应用
  • 很适合做用户视角的自动化流程

代价是：

  • 画面变化会影响稳定性
  • 分辨率、语言、主题、弹窗都会影响识别
  • 问题定位依赖画面——无法通过代码调用栈追踪，只能靠截图和日志反推

不过黑盒是默认方式，不是硬性限制。通过 Custom 自定义识别，你可以接入别的能力——比如 Poco 这类基于控件元素（控件树）的框架，直接读取控件信息来判断状态，而不只是靠截图。

也就是说：图像识别是 MaaFW 的默认方式，但不是唯一方式。需要更精确的状态判断时，可以用 Custom 把控件级的识别能力补进来。Custom 怎么写，后面会专门讲。

Pipeline 是 MaaFW 应用的核心逻辑

MaaFW 应用的大部分核心逻辑写在 Pipeline（流水线）里。

Pipeline 是一组 JSON 节点（Node）。每个节点最核心的是三件事：

  1. 识别什么
  2. 做什么动作
  3. 下一步去哪里

一个极简例子大概长这样：

{
    "ClickStart": {
        // "点击“开始”文本",
        "recognition": "OCR",
        "expected": "开始",
        "action": "Click",
        "next": ["Confirm"]
    },
    "Confirm": {
        // "点击“确认”文本",
        "recognition": "OCR",
        "expected": "确认",
        "action": "Click"
    }
}

它实际跑起来的过程就是：

  1. ClickStart 识别到“开始” → 点击“开始” → 下一步到 Confirm
  2. Confirm 识别到“确认” → 点击“确认” → 结束

节点怎么设计、流程怎么编排、出问题了怎么定位——后面都会讲到。

MaaFW 应用不只是 Pipeline

一个能交给用户使用的 MaaFW 应用，不只有 Pipeline。

一个完整的应用通常会包含：

  • interface.json：告诉通用 GUI 你的项目有哪些功能以及如何运行
  • resource/：存放项目资源
  • Custom：通过自定义代码实现更复杂的识别或动作

所以本课程会从 Pipeline 入手，再延伸到 ProjectInterface 和 Custom。

MaaFW 适合做什么

能用 MaaFW 的前提是：

  • 目标应用能稳定截图
  • 自动化目标可以通过画面识别判断
  • 操作路径相对明确

满足这些条件后，下面几种场景尤其适合 MaaFW：

  • 需要覆盖桌面或 Android 平台——MaaFW 支持 Windows、macOS、Linux 以及 Android，不用为不同平台切换框架
  • 目标应用没有可供调用的业务 API——只能通过画面来理解和操作
  • 想用声明式方式编排流程——用 JSON 写 Pipeline 就能组织复杂的自动化流程，不需要大量编程

MaaFW 不适合做什么

MaaFW 不是万能自动化工具。不适合的情况分两类。

有更直接的替代方案时：

  • 目标有稳定完整的业务 API——直接调 API 远比截图识别可靠
  • 目标已有成熟的专项工具能覆盖全流程——比如网页自动化用 Playwright 或 Selenium 就足够了，MaaFW 的截图循环在这里不会带来额外增益
  • 你需要验证代码逻辑、数据库状态或接口契约——单元测试和集成测试是更好的选择

画面无法反映状态时：

  • 自动化目标的变化不体现在画面上，纯靠截图无法判断当前处于什么状态

MaaFW 的默认方式是“像用户一样看和操作”。当某个场景已有工具能更直接地覆盖全流程时，把 MaaFW 加进来通常不会带来额外增益——不是因为“做不到”，而是因为“没必要”。

新手最容易混淆的几个点

刚接触 MaaFW 时，下面几个概念容易被搞混。

MaaFW 是框架，不是具体应用。

M9A（《重返未来：1999》小助手）等具体应用都是基于 MaaFW 构建的，MaaFW 本身不提供现成的自动化功能，它提供的是“看图、操作、编排”的能力。

通用 GUI 和你的应用逻辑是分开的。

通用 GUI 根据统一的 ProjectInterface 协议加载 interface.json，和你编写的资源交互，让用户可以选择和运行任务。两者相互独立，可以排列组合。

本章小结

MaaFW 的核心思路可以压缩成一句话：

通过截图理解当前状态，通过模拟操作推动流程，再用 Pipeline 把这些步骤组织起来。

下一章会展示一个常规 MaaFW 应用的项目结构和文件组织。