MaaFW 应用常规结构

约 735 字大约 2 分钟

这章带你认识一个 MaaFW 应用项目长什么样、每个部分负责什么。

后面的内容都以 create-maa-project 生成的新项目结构为准。

项目结构一览

刚创建的 Pipeline 项目，大致长这样：

my-project/
├── .github/                                  # GitHub 配置
├── .vscode/                                  # VSCode 配置
├── resource/
│   └── base/                                 # 默认资源目录（Bundle），写自动化逻辑的主要地方
│       ├── image/                            # 模板/特征匹配用的图片素材
│       ├── model/
│       │   └── ocr/                          # OCR 模型文件
│       ├── pipeline/
│       │   └── tutorial.json                 # Pipeline 节点定义文件（自动化流程的核心逻辑）
│       └── default_pipeline.json             # 所有节点共享的默认参数
├── tasks/
│   └── tutorial.json                         # 任务配置：用户能选什么任务、选项
├── tools/                                    # 检查、格式化、构建发布脚本
├── interface.json                            # 项目接口：通用 GUI 读它来加载项目
├── package.json                              # 开发工具的依赖和脚本
├── README.md                                 # 项目说明文档
└── LICENSE

如果创建的是 Agent 项目（需要 Custom），还会多出这些 Python 部分：

my-project/
├── ...                                      # 其余文件、文件夹同 Pipeline 项目
├── agent/
│   ├── custom/
│   │   ├── action/                          # 自定义动作
│   │   └── reco/                            # 自定义识别
│   ├── utils/                               # 辅助模块
│   ├── bootstrap.py                         # Agent 启动脚本（环境与依赖准备）
│   └── main.py                              # Agent 主入口
├── pyproject.toml                           # Python 项目配置
└── requirements.txt                         # Python 依赖

文件不少，但新手先重点关注三部分：

interface.json — 项目接口
tasks/ + resource/ — 任务的入口和执行的逻辑、资源
agent/ — 只有需要 Custom 时才会出现

interface.json：项目接口

interface.json 是 MaaFW 项目的接口声明。通用 GUI 和工具通过它知道：项目叫什么、支持哪些控制器、加载哪些资源包、提供哪些任务入口等信息。

{
    "interface_version": 2,
    "name": "my-project",
    "controller": [
        {
            "name": "Android",
            "label": "Android / Emulator",
            "type": "Adb"
        }
    ],
    "resource": [
        {
            "name": "base",
            "path": [
                "./resource/base"
            ]
        }
    ],
    "import": [
        "./tasks/tutorial.json"
    ]
}

实际生成的 interface.json 还有 version、description 等描述性字段，上面为突出核心结构做了精简。任务少时可以直接写进它的 task 字段；任务多时，拆到外部文件再用 import 导入，保持 interface.json 简洁。这里用的是拆分写法。

import 进来的 tasks/tutorial.json 大致长这样：

{
    "task": [
        {
            "name": "Tutorial",
            "entry": "Tutorial.Start"
        }
    ]
}

而 task.entry 指向的 Tutorial.Start，则定义在 resource/base/pipeline/tutorial.json 里：

{
    "Tutorial.Start": {
        "recognition": "OCR",
        "roi": [0, 0, 1280, 720],
        "expected": ".*",
        "action": "DoNothing"
    }
}

这是脚手架自带的占位节点：OCR 匹配画面上的任意文字，然后什么也不做，保证任务从创建起就能跑通。后面的章节会把它替换成真正的自动化逻辑。

两个新手常踩的坑：

resource[].path 指向 Bundle 根目录（如 resource/base/），不是某个 Pipeline 文件。
task.entry 指向 Pipeline 节点名，不是 Pipeline 文件名。

一个任务实际怎么跑起来

运行前，通用 GUI 连接目标设备、加载资源。

运行时就是第一章说的“截图→识别→动作→下一节点”循环——具体每步做什么，全在 resource/base/ 的 Pipeline 里。