MaaFramework (maaxyz/maaframework)

MaaFramework

https://github.com/maaxyz/maaframework
Admin
MaaFramework is a new generation black-box testing framework based on image recognition, offering...

Tokens:83,984
Snippets:436
Trust Score:7.2
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# MaaFramework

## 简介

**MaaFramework** 是基于图像识别技术的新一代自动化黑盒测试框架，源于 MAA (MaaAssistantArknights) 项目的开发经验。该框架支持多平台（Windows、Linux、macOS、Android），提供低代码 JSON Pipeline 配置与多语言 API（Python、C++、C#、Go、Rust、Node.js）相结合的开发模式，让开发者能够轻松编写自动化测试和任务脚本。

框架核心功能包括：OCR 文字识别、模板匹配、特征匹配、颜色匹配、神经网络分类与检测等图像识别算法，以及点击、滑动、按键、文本输入等设备控制操作。通过 JSON Pipeline 协议，开发者可以用声明式的方式定义自动化任务流程，无需编写复杂代码即可实现强大的自动化功能。

---

## API 文档

### 初始化与资源加载

MaaFramework 的基本工作流程：创建资源 -> 创建控制器 -> 创建 Tasker -> 绑定并执行任务。

```python
from maa.library import Library
from maa.resource import Resource
from maa.controller import AdbController
from maa.tasker import Tasker

# 1. 初始化库（指定 MaaFramework 动态库路径）
Library.open("/path/to/MaaFramework/bin")

# 2. 创建并加载资源
resource = Resource()
res_job = resource.post_bundle("./resource")
res_job.wait()
print(f"资源加载状态: {resource.loaded}")  # True

# 3. 创建 ADB 控制器并连接设备
controller = AdbController(
    adb_path="/path/to/adb",
    address="127.0.0.1:5555"
)
conn_job = controller.post_connection()
conn_job.wait()
print(f"设备连接状态: {controller.connected}")  # True

# 4. 创建 Tasker 并绑定资源和控制器
tasker = Tasker()
tasker.bind(resource, controller)
print(f"Tasker 初始化: {tasker.inited}")  # True

# 5. 执行任务
task_job = tasker.post_task("StartUpAndClickButton")
task_job.wait()
result = task_job.get()
print(f"任务完成: {result.status}")
```

---

### Pipeline JSON 配置

Pipeline 是 MaaFramework 的核心配置格式，用于定义自动化任务流程。每个节点包含识别算法和执行动作。

```json
{
    "点击开始按钮": {
        "recognition": "OCR",
        "expected": "开始",
        "action": "Click",
        "next": ["点击确认图标"]
    },
    "点击确认图标": {
        "recognition": "TemplateMatch",
        "template": "confirm.png",
        "threshold": 0.8,
        "action": "Click",
        "next": ["等待加载完成"]
    },
    "等待加载完成": {
        "recognition": "DirectHit",
        "action": "DoNothing",
        "post_wait_freezes": {
            "time": 2000,
            "threshold": 0.95
        }
    }
}
```

---

### OCR 文字识别

OCR 识别用于在屏幕上查找指定文本，支持正则表达式匹配。

```json
{
    "查找登录按钮": {
        "recognition": "OCR",
        "expected": ["登录", "Login", "Sign in"],
        "roi": [100, 200, 300, 100],
        "threshold": 0.5,
        "action": "Click"
    },
    "识别数字": {
        "recognition": "OCR",
        "expected": "\\d+",
        "replace": [
            ["O", "0"],
            ["l", "1"]
        ],
        "order_by": "Horizontal",
        "index": 0
    }
}
```

---

### 模板匹配 (TemplateMatch)

通过图片模板在屏幕上查找匹配区域，支持多模板和绿色掩码。

```json
{
    "查找图标": {
        "recognition": "TemplateMatch",
        "template": ["icon_a.png", "icon_b.png"],
        "threshold": [0.7, 0.8],
        "roi": [0, 0, 1280, 720],
        "method": 5,
        "green_mask": false,
        "action": "Click"
    },
    "点击多个目标": {
        "recognition": "TemplateMatch",
        "template": "target.png",
        "threshold": 0.7,
        "order_by": "Score",
        "index": 0,
        "action": "Click"
    }
}
```

---

### 特征匹配 (FeatureMatch)

具有尺度不变性和旋转不变性的图像匹配算法，适用于动态场景。

```json
{
    "特征识别": {
        "recognition": "FeatureMatch",
        "template": "feature_target.png",
        "detector": "SIFT",
        "count": 10,
        "ratio": 0.6,
        "green_mask": false,
        "action": "Click"
    }
}
```

---

### 颜色匹配 (ColorMatch)

在指定区域内查找符合颜色范围的像素区域。

```json
{
    "查找红色按钮": {
        "recognition": "ColorMatch",
        "roi": [0, 0, 1280, 720],
        "method": 40,
        "lower": [0, 100, 100],
        "upper": [10, 255, 255],
        "count": 500,
        "connected": true,
        "action": "Click"
    }
}
```

---

### 神经网络检测 (NeuralNetworkDetect)

使用 YOLO 等深度学习模型进行目标检测。

```json
{
    "检测敌人": {
        "recognition": "NeuralNetworkDetect",
        "model": "yolo_enemy.onnx",
        "labels": ["Enemy", "Boss", "NPC"],
        "expected": [0, 1],
        "threshold": 0.5,
        "order_by": "Score",
        "action": "Click"
    }
}
```

---

### 点击动作 (Click)

执行点击操作，支持多种目标定位方式。

```json
{
    "点击识别区域": {
        "recognition": "TemplateMatch",
        "template": "button.png",
        "action": "Click",
        "target": true,
        "target_offset": [0, 0, 0, 0]
    },
    "点击固定坐标": {
        "recognition": "DirectHit",
        "action": "Click",
        "target": [640, 360]
    },
    "点击区域随机点": {
        "recognition": "DirectHit",
        "action": "Click",
        "target": [100, 100, 200, 200]
    }
}
```

---

### 滑动动作 (Swipe)

执行滑动操作，支持折线滑动路径。

```json
{
    "向下滑动": {
        "recognition": "DirectHit",
        "action": "Swipe",
        "begin": [640, 500],
        "end": [640, 200],
        "duration": 500
    },
    "折线滑动": {
        "recognition": "DirectHit",
        "action": "Swipe",
        "begin": [100, 100],
        "end": [[200, 200], [300, 100], [400, 200]],
        "duration": [200, 200, 200]
    }
}
```

---

### 多指滑动 (MultiSwipe)

支持多个触控点同时滑动，适用于多点触控场景。

```json
{
    "双指缩放": {
        "recognition": "DirectHit",
        "action": "MultiSwipe",
        "swipes": [
            {
                "contact": 0,
                "begin": [400, 360],
                "end": [200, 360],
                "duration": 500
            },
            {
                "contact": 1,
                "begin": [880, 360],
                "end": [1080, 360],
                "duration": 500
            }
        ]
    }
}
```

---

### 按键与文本输入

执行按键操作和文本输入。

```json
{
    "按返回键": {
        "recognition": "DirectHit",
        "action": "ClickKey",
        "key": 4
    },
    "输入搜索文本": {
        "recognition": "TemplateMatch",
        "template": "search_box.png",
        "action": "InputText",
        "input_text": "MaaFramework"
    },
    "启动应用": {
        "recognition": "DirectHit",
        "action": "StartApp",
        "package": "com.example.app"
    }
}
```

---

### 任务流程控制

使用 next、on_error、timeout 等控制任务流程。

```json
{
    "主任务": {
        "next": [
            "[JumpBack]处理弹窗",
            "执行步骤A",
            "执行步骤B"
        ],
        "timeout": 30000,
        "on_error": ["错误处理"]
    },
    "处理弹窗": {
        "recognition": "OCR",
        "expected": "确定",
        "action": "Click",
        "next": []
    },
    "执行步骤A": {
        "recognition": "TemplateMatch",
        "template": "step_a.png",
        "action": "Click",
        "pre_delay": 500,
        "post_delay": 1000
    }
}
```

---

### Python 自定义识别器

通过继承 CustomRecognition 实现自定义识别逻辑。

```python
from maa.custom_recognition import CustomRecognition
from maa.context import Context
from maa.define import Rect
import numpy as np

class MyRecognition(CustomRecognition):
    def analyze(
        self,
        context: Context,
        argv: CustomRecognition.AnalyzeArg
    ) -> CustomRecognition.AnalyzeResult:
        # 获取截图
        image = argv.image

        # 自定义图像处理逻辑
        # ...

        # 返回识别结果
        return CustomRecognition.AnalyzeResult(
            box=Rect(100, 100, 50, 50),
            detail="自定义识别成功"
        )

# 注册自定义识别器
resource.register_custom_recognition("MyReco", MyRecognition())
```

Pipeline 中使用：
```json
{
    "使用自定义识别": {
        "recognition": "Custom",
        "custom_recognition": "MyReco",
        "custom_recognition_param": {"key": "value"},
        "action": "Click"
    }
}
```

---

### Python 自定义动作

通过继承 CustomAction 实现自定义操作逻辑。

```python
from maa.custom_action import CustomAction
from maa.context import Context

class MyAction(CustomAction):
    def run(
        self,
        context: Context,
        argv: CustomAction.RunArg
    ) -> bool:
        # 获取控制器并执行操作
        controller = context.tasker.controller

        # 执行点击
        controller.post_click(100, 200).wait()

        # 执行滑动
        controller.post_swipe(100, 300, 400, 300, 500).wait()

        # 动态修改后续任务流
        context.override_next(argv.node_name, ["NextTask1", "NextTask2"])

        return True

# 注册自定义动作
resource.register_custom_action("MyAct", MyAction())
```

Pipeline 中使用：
```json
{
    "执行自定义动作": {
        "recognition": "DirectHit",
        "action": "Custom",
        "custom_action": "MyAct",
        "custom_action_param": {"param1": "value1"}
    }
}
```

---

### 控制器操作

直接使用 Controller 对象进行设备控制。

```python
# 截图
job = controller.post_screencap()
job.wait()
image = controller.cached_image
print(f"截图尺寸: {image.shape}")

# 点击（支持多指）
controller.post_click(640, 360, contact=0, pressure=1).wait()

# 滑动
controller.post_swipe(100, 500, 100, 200, duration=500).wait()

# 按键
controller.post_click_key(4).wait()  # Android BACK 键

# 输入文本
controller.post_input_text("Hello MaaFramework").wait()

# 启动/关闭应用
controller.post_start_app("com.example.app").wait()
controller.post_stop_app("com.example.app").wait()

# 获取设备分辨率
width, height = controller.resolution
print(f"设备分辨率: {width}x{height}")

# 执行 Shell 命令（仅 ADB 控制器）
shell_job = controller.post_shell("getprop ro.build.version.sdk")
shell_job.wait()
output = shell_job.get()
print(f"Android SDK 版本: {output}")
```

---

### 任务结果查询

查询任务执行详情和识别结果。

```python
# 执行任务并获取结果
task_job = tasker.post_task("MainTask")
task_job.wait()
task_detail = task_job.get()

print(f"任务入口: {task_detail.entry}")
print(f"任务状态: {task_detail.status}")

# 遍历执行的节点
for node_id in task_detail.node_id_list:
    node = tasker.get_node_detail(node_id)
    print(f"节点: {node.name}, 完成: {node.completed}")

    # 获取识别详情
    if node.recognition:
        reco = node.recognition
        print(f"  识别算法: {reco.algorithm}")
        print(f"  命中: {reco.hit}, 位置: {reco.box}")

    # 获取动作详情
    if node.action:
        act = node.action
        print(f"  动作: {act.action}, 成功: {act.success}")

# 获取最新执行的特定节点
latest = tasker.get_latest_node("ClickButton")
if latest:
    print(f"最新执行: {latest.name}")
```

---

### Win32 控制器

控制 Windows 桌面应用程序。

```python
from maa.controller import Win32Controller
from maa.toolkit import Toolkit

# 查找窗口
windows = Toolkit.desktop_window_list()
for win in windows:
    print(f"窗口: {win.window_name}, 类名: {win.class_name}")

# 创建 Win32 控制器
target_hwnd = windows[0].handle
controller = Win32Controller(
    hWnd=target_hwnd,
    screencap_method=4,  # FramePool
    mouse_method=2,      # Seize
    keyboard_method=2    # Seize
)

controller.post_connection().wait()
print(f"连接状态: {controller.connected}")

# 鼠标滚动（仅 Win32 支持）
controller.post_scroll(0, 120).wait()  # 向上滚动一格
```

---

### Agent 服务器模式

通过 Agent 进程注册自定义识别和动作，与通用 UI 配合使用。

```python
from maa.agent.agent_server import AgentServer

# 使用装饰器注册自定义识别器
@AgentServer.custom_recognition("MyReco")
class MyRecognition:
    def analyze(self, context, argv):
        # 识别逻辑
        return {"box": [100, 100, 50, 50]}

# 使用装饰器注册自定义动作
@AgentServer.custom_action("MyAct")
class MyAction:
    def run(self, context, argv):
        context.controller.post_click(100, 100).wait()
        context.override_next(["TaskA", "TaskB"])
        return True

# 启动 Agent 服务
if __name__ == "__main__":
    import sys
    sock_id = sys.argv[1] if len(sys.argv) > 1 else ""
    AgentServer.start_up(sock_id)
```

---

### 调试与日志

配置调试选项和日志输出。

```python
from maa.tasker import Tasker
from maa.define import LoggingLevelEnum

# 设置日志目录
Tasker.set_log_dir("./logs")

# 设置控制台日志级别
Tasker.set_stdout_level(LoggingLevelEnum.All)

# 启用调试模式（获取 raw/draws 图像）
Tasker.set_debug_mode(True)

# 保存识别结果图像
Tasker.set_save_draw(True)

# 错误时保存截图
Tasker.set_save_on_error(True)

# 设置识别图像质量
Tasker.set_draw_quality(85)

# 加载插件
Tasker.load_plugin("/path/to/plugin.dll")
```

---

### 资源推理设备配置

配置神经网络推理使用的硬件设备。

```python
# 使用 CPU
resource.use_cpu()

# 使用 DirectML (Windows GPU)
resource.use_directml(device_id=0)

# 使用 CoreML (macOS)
resource.use_coreml()

# 自动选择最佳设备
resource.use_auto_ep()
```

---

### 组合识别 (And/Or)

组合多个识别条件进行复杂判断。

```json
{
    "图文同时存在": {
        "recognition": "And",
        "all_of": [
            {
                "sub_name": "icon",
                "recognition": "TemplateMatch",
                "template": "icon.png"
            },
            {
                "recognition": "OCR",
                "roi": "icon",
                "roi_offset": [50, 0, 100, 30],
                "expected": "确认"
            }
        ],
        "box_index": 0,
        "action": "Click"
    },
    "任意按钮存在": {
        "recognition": "Or",
        "any_of": [
            {
                "recognition": "TemplateMatch",
                "template": "confirm.png"
            },
            {
                "recognition": "OCR",
                "expected": ["OK", "确定"]
            }
        ],
        "action": "Click"
    }
}
```

---

## 总结

MaaFramework 提供了一套完整的自动化测试解决方案，主要使用场景包括：游戏自动化脚本（日常任务、资源收集）、移动端 App 自动化测试、桌面应用程序自动化、以及各类需要图像识别的自动化场景。通过低代码 JSON Pipeline 配置，开发者可以快速搭建自动化流程，而无需深入了解底层实现。

框架的集成模式灵活多样：对于简单场景，可以纯 JSON 配置结合通用 UI 运行；对于复杂逻辑，可以在 Agent 进程中注册自定义识别器和动作；对于深度定制需求，可以使用 Python/C++/C# 等语言 API 进行全代码开发。MaaFramework 还提供了丰富的生态工具，包括可视化 Pipeline 编辑器、VSCode 插件、调试器等，大幅降低了开发和调试成本。