https://github.com/maaxyz/maaframework
基于图像识别的自动化黑盒测试框架 | An automation black-box testing framework based on image recognition
https://github.com/maaxyz/maaframework
black-box-testing computer-vision
Last synced: about 2 months ago
JSON representation
基于图像识别的自动化黑盒测试框架 | An automation black-box testing framework based on image recognition
- Host: GitHub
- URL: https://github.com/maaxyz/maaframework
- Owner: MaaXYZ
- License: lgpl-3.0
- Created: 2023-04-24T14:50:25.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2026-02-17T16:32:00.000Z (4 months ago)
- Last Synced: 2026-02-17T22:40:39.862Z (4 months ago)
- Topics: black-box-testing, computer-vision
- Language: C++
- Homepage: https://maafw.com
- Size: 16.9 MB
- Stars: 3,249
- Watchers: 17
- Forks: 350
- Open Issues: 70
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# MaaFramework
_✨ 基于图像识别的自动化黑盒测试框架 ✨_
[English](./README_en.md) | [简体中文](./README.md)
## 简介
**MaaFramework** 是基于图像识别技术、运用 [MAA](https://github.com/MaaAssistantArknights/MaaAssistantArknights) 开发经验去芜存菁、完全重写的新一代自动化黑盒测试框架。
低代码的同时仍拥有高扩展性，旨在打造一款丰富、领先、且实用的开源库，助力开发者轻松编写出更好的黑盒测试程序，并推广普及。
## 即刻开始
> [!TIP]
> 访问我们的 [官网](https://maafw.com/) 以获得更优秀的文档阅读体验。
> 找不到相关文档？试试问 [AI](https://deepwiki.com/MaaXYZ/MaaFramework) ！
- [快速开始](docs/zh_cn/1.1-快速开始.md) & [术语解释](docs/zh_cn/1.2-术语解释.md)
- [代码集成](docs/zh_cn/2.1-集成文档.md) & [API](docs/zh_cn/2.2-集成接口一览.md)
- [Pipeline 低代码协议](docs/zh_cn/3.1-任务流水线协议.md)
- [项目接口 PI 协议](docs/zh_cn/3.3-ProjectInterfaceV2协议.md)
## 社区项目
### 通用 UI
- [MFAAvalonia](https://github.com/SweetSmellFox/MFAAvalonia)     [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
基于 Avalonia 的 通用 GUI。由 MaaFramework 强力驱动！
- [MFW-CFA](https://github.com/overflow65537/MFW-PyQt6)     [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
基于 PySide6 的通用 GUI。由 MaaFramework 强力驱动！
- [MXU](https://github.com/MistEO/MXU)     
基于 Tauri 2 + React 的轻量级跨平台通用 GUI。由 MaaFramework 强力驱动！
- [MWU](https://github.com/ravizhan/MWU)     
基于 Vue + FastAPI 的轻量级跨平台通用 WebUI。由 MaaFramework 强力驱动！
### 开发工具
- [MaaDebugger](https://github.com/MaaXYZ/MaaDebugger)     [](https://pypi.org/project/MaaDebugger/)
MaaFramework Pipeline 调试器
- [maa-support-extension](https://github.com/neko-para/maa-support-extension)    [](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support)
MaaFramework VSCode 插件
- [MFAToolsPlus](https://github.com/SweetSmellFox/MFAToolsPlus)    
基于 Avalonia 框架开发的跨平台开发工具箱，提供便捷的数据获取和模拟测试方法
- [MaaPipelineEditor](https://github.com/kqcoxn/MaaPipelineEditor)     [](https://mpe.codax.site/stable/)
可视化阅读与构建 Pipeline，[功能完备](https://github.com/kqcoxn/MaaPipelineEditor?tab=readme-ov-file#%E4%BA%AE%E7%82%B9)，极致轻量跨平台，提供渐进式[本地功能扩展](https://mpe.codax.site/docs/guide/server/deploy.html)，无缝兼容新旧项目
- [MaaInspector](https://github.com/TanyaShue/MaaInspector)   
基于 vue-flow 的可视化编辑器，集成节点预览,编辑,调试于一体的简单好用的 MaaFramework Pipeline 编辑器
- [MaaLogAnalyzer](https://github.com/MaaXYZ/MaaLogAnalyzer)     [](https://marketplace.visualstudio.com/items?itemName=Windsland52.maa-log-analyzer) [](https://mla.maafw.com/)
MaaFramework 日志分析工具，提供用户友好的多视角可视化任务执行流程分析
- [MaaLogs](https://github.com/amiliyaai/MaaLogs)     [](https://maalogs.maafw.com/)
MaaFramework 日志分析工具，支持多项目日志解析、可视化任务流程和 AI 智能分析
- [prettier-plugin-maafw-sort](https://github.com/neko-para/maa-support-extension/tree/main/pkgs/prettier-plugin-maafw-sort)     [](https://www.npmjs.com/package/@nekosu/prettier-plugin-maafw-sort)
Prettier 插件，按照生命周期顺序自动排序 pipeline 字段
- [Auto Green Background](https://github.com/Joe-Bao/Auto-Green-Background)     [](https://github.com/Joe-Bao/Auto-Green-Background/releases)
自动涂绿幕工具（Python/OpenCV，适用于TemplateMatch），支持多算法分割、固定画布输出、实时预览与便携版开箱即用打包。
- [maafw-cli](https://github.com/otowa-kotori/maafw-cli)     [](https://pypi.org/project/maafw-cli/)
用于AI Agent的 MaaFramework 命令行界面。
- [maaframework-skills](https://github.com/Kutius/maaframework-skills)   
Claude Code skill for MaaFramework — 面向 AI 辅助开发的结构化参考文档。
### 应用程序
- [M9A](https://github.com/MaaXYZ/M9A)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge) [](https://1999.fan)
亿韭韭韭 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MSBA](https://github.com/overflow65537/MAA_SnowBreak)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
尘白禁区 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaYYs](https://github.com/TanyaShue/MaaYYs)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
阴阳师小助手。图像技术 + 模拟控制，当赛博屯屯鼠，自动日常，解放你的双手！由 MaaFramework 强力驱动！
- [MPA](https://github.com/overflow65537/MAA_Punish)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
战双帕弥什 小助手。图像技术 + 模拟控制，解放双手！由 玛丽的黑咖啡 2.0 强力驱动！
- [MRA](https://github.com/Saratoga-Official/MRA)     [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
战舰少女R 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaYuan](https://github.com/syoius/MaaYuan)     [](https://mirrorchyan.com/zh/projects?source=maafw-badge) [](https://maayuan.top)
代号鸢/如鸢 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [Maa-HBR](https://github.com/KarylDAZE/Maa-HBR)     [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
炽焰天穹/HBR 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaGF2Exilium](https://github.com/DarkLingYun/MaaGF2Exilium)     [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
少女前线 2: 追放自动化助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaXuexi](https://github.com/ravizhan/MaaXuexi)     
学习强国 自动化助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MAA_MHXY_MG](https://github.com/gitlihang/Maa_MHXY_MG)     [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
梦幻西游手游 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaTOT](https://github.com/Coxwtwo/MaaTOT)    
未定事件簿 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaGumballs](https://github.com/KhazixW2/MaaGumballs)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
不思议迷宫小助手是一款由图像识别与模拟控制技术驱动的辅助工具。它能够帮助大家解放双手，一键开启敲砖大冒险，由 MaaFramework 强力支持。
- [MMleo](https://github.com/fictionalflaw/MMleo)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
偶像梦幻祭 2 小助手。使用图像识别+模拟控制技术，解放双手！助力屯屯鼠的制作人生涯！由 MaaFramework 强力驱动！
- [SLIMEIM_Maa](https://github.com/miaojiuqing/SLIMEIM_Maa)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
魔王与龙的建国谭小助手。使用图像识别+模拟控制技术，解放双手！由 MaaFramework 强力驱动！
- [Maa_bbb](https://github.com/miaojiuqing/Maa_bbb)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
崩坏三小助手。使用图像识别+模拟控制技术，解放双手！PC 端与模拟器端同步支持，由 MaaFramework 强力驱动！
- [MAN](https://github.com/duorua/narutomobile)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge) [](https://naruto.natsuu.top)
火影忍者手游小助手。使用图像识别+模拟控制技术，解放双手！由 MaaFramework 强力驱动！
- [MaaGakumasu](https://github.com/SuperWaterGod/MaaGakumasu)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
学园偶像大师小助手。使用图像技术 + 模拟控制 + 深度学习，解放双手！由 MaaFramework 强力驱动！
- [MaaStarResonance](https://github.com/233Official/MaaStarResonance)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge)
星痕共鸣小助手。使用图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MAG](https://github.com/Kazaorus/MAG)     
深空之眼小助手。使用图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MAAAE](https://github.com/NewWYoming/MAAAE)     
白荆回廊 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MBCCtools](https://github.com/quietlysnow/MBCCtools)    
无期迷途 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaEOV](https://github.com/Tigerisu/MaaEOV)    
异象回声 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MAA Star Resonance](https://github.com/26F-Studio/maa-star-resonance)    
星痕共鸣小助手。使用 Electron + 文本图像识别 + ADB 模拟控制 技术，解放双手！由 MaaFramework 和 Quasar 强力驱动！
- [StellaSora-Auto-Helper](https://github.com/SodaCodeSave/StellaSora-Auto-Helper)    
星塔旅人 小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaDuDuL](https://github.com/kqcoxn/MaaDuDuL)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge) [](https://mddl.codax.site)
嘟嘟脸恶作剧 小助手。图像技术 + 模拟控制，自动捏脸，解放双手！由 MaaFramework 强力驱动！
- [MaaLYSK](https://github.com/Witty36/MaaLYSK)      [](https://mirrorchyan.com/zh/projects?rid=MaaLYSK) [](https://maalysk.top)
恋与深空 小助手。使用图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaEnd](https://github.com/MaaEnd/MaaEnd)      [](https://mirrorchyan.com/zh/projects?source=maafw-badge) [](https://maaend.com)
终末地小助手。由 MaaFramework 与 MXU 驱动，绝赞开发中！
- [MaaGFNeuralCloud](https://github.com/PinkMMF/MaaGFNeuralCloud)    
少女前线：云图计划自动化助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaFgo](https://github.com/xlxyvergil/MaaFgo)   
FGO 小助手。使用图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
- [MaaNTE](https://github.com/1bananachicken/MaaNTE)    
异环小助手。图像技术 + 模拟控制，解放双手！由 MaaFramework 强力驱动！
## 生态共建
MAA 正计划建设为一类项目，而非舟的单一软件。
若您的项目依赖于 MaaFramework ，我们欢迎您将它命名为 MaaXXX, MXA, MAX 等等。当然，这是许可而不是限制，您也可以自由选择其他与 MAA 无关的名字，完全取决于您自己的想法！
同时，我们也非常欢迎您提出 PR ，在上方的社区项目列表中添加上您的项目！
## 声明与许可
### 开源许可
本项目采用 [`LGPL-3.0`](./LICENSE.md) 许可证进行开源。
### 分发说明
本项目支持 GPU 加速功能，其在 Windows 平台上依赖于 Microsoft 提供的独立组件 [DirectML](https://learn.microsoft.com/en-us/windows/ai/directml/)。DirectML 并非本项目的开源部分，也不受 LGPL-3.0 的约束。为方便用户，我们随安装包附带了一个未经修改的 DirectML.dll 文件。如果您无需 GPU 加速功能，可安全删除该 DLL 文件，软件的核心功能仍可正常运行。
### 免责声明
#### 预期用途
本项目旨在为软件开发提供**自动化黑盒测试工具**，包括图像识别、界面操作模拟等合法技术场景。开发者应确保其使用方式符合所有适用法律法规及目标软件的服务条款。
#### 禁止滥用
禁止将本项目用于以下用途（包括但不限于）：
- 破坏、绕过或干扰任何软件、游戏、服务的正常功能（如反作弊机制、授权验证系统）。
- 开发或分发违反第三方服务条款的工具（如游戏外挂、作弊器、自动化脚本）。
- 任何侵犯他人合法权益或违反法律的行为（如数据窃取、网络攻击）。
#### 责任豁免
本项目按“原样”提供，作者**不承担**因以下行为导致的任何直接、间接或衍生责任：
- 使用者违反本声明或法律法规的行为。
- 第三方利用本项目开发的工具造成的损害（如账号封禁、法律纠纷）。
- 因使用本项目导致的任何技术或经济损失。
#### 用户义务
使用本项目即表示您同意：
- 自行承担所有使用风险。
- 确保您的应用场景合法，并已获得相关授权（如目标软件厂商的许可）。
- 若您的行为导致法律纠纷，您应独立承担责任并免除本项目作者的一切责任。
## 开发
_请留意，仅当您准备开发 MaaFramework 本身时，才需要阅读本章节内容。若您仅希望基于 MaaFramework 开发自己的应用，则请参考 [即刻开始](#即刻开始)。_
- [构建指南](docs/zh_cn/4.1-构建指南.md)
- [接口设计](docs/zh_cn/4.2-标准化接口设计.md)
## 鸣谢
### 开源库
- [opencv](https://github.com/opencv/opencv)
Open Source Computer Vision Library
- [fastdeploy](https://github.com/PaddlePaddle/FastDeploy)
⚡️An Easy-to-use and Fast Deep Learning Model Deployment Toolkit for ☁️Cloud 📱Mobile and 📹Edge.
- [onnxruntime](https://github.com/microsoft/onnxruntime)
ONNX Runtime: cross-platform, high performance ML inferencing and training accelerator
- [boost](https://www.boost.org/)
Boost provides free peer-reviewed portable C++ source libraries.
- [libzmq](https://github.com/zeromq/libzmq)
ZeroMQ core engine in C++, implements ZMTP/3.1
- [cppzmq](https://github.com/zeromq/cppzmq)
Header-only C++ binding for libzmq
- [meojson](https://github.com/MistEO/meojson)
✨ Next-gen C++ JSON/JSON5 Serialization Engine | Zero Dependency | Header-Only | Unleash JSON Potential
- [minitouch](https://github.com/DeviceFarmer/minitouch)
Minimal multitouch event producer for Android.
- [maatouch](https://github.com/MaaAssistantArknights/MaaTouch)
Android native implementation of minitouch input protocol
- [minicap](https://github.com/DeviceFarmer/minicap)
Stream real-time screen capture data out of Android devices.
- [zlib](https://github.com/madler/zlib)
A massively spiffy yet delicately unobtrusive compression library.
- [gzip-hpp](https://github.com/mapbox/gzip-hpp)
Gzip header-only C++ library
- [ViGEmClient](https://github.com/nefarius/ViGEmClient)
ViGEm Client SDK for feeder development.
- ~~[protobuf](https://github.com/protocolbuffers/protobuf)~~
~~Protocol Buffers - Google's data interchange format~~
- ~~[grpc](https://github.com/grpc/grpc)~~
~~The C based gRPC (C++, Python, Ruby, Objective-C, PHP, C#)~~
- ~~[thrift](https://github.com/apache/thrift)~~
~~Apache Thrift~~
### 思路灵感
- [MaaAssistantArknights](https://github.com/MaaAssistantArknights/MaaAssistantArknights)
《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.
**MaaFramework 参考了该项目中 ADB 控制器部分实现思路，但未使用其任何源代码。**
- [ok-script](https://github.com/ok-oldking/ok-script)
全新 Python 游戏自动化框架(支持 Windows 和模拟器)
**MaaFramework 参考该项目中 Win32 控制器部分实现思路，但未使用其任何源代码。**
### 开发者
感谢以下开发者对 MaaFramework 作出的贡献：
[](https://github.com/MaaXYZ/MaaFramework/graphs/contributors)
## 沟通交流
欢迎开发者加入官方 QQ 群（595990173），交流集成与开发实践。群内仅讨论开发相关议题，不提供日常使用/客服支持；为保证讨论质量，长期离题或违规的成员可能会被移除。
## 赞助
