MaaXYZ/MaaFramework

基于图像识别的自动化黑盒测试框架 | An automation black-box testing framework based on image recognition

MaaFramework란?

MaaFramework는 이미지 인식을 기반으로 한 오픈소스 자동화 및 블랙박스 테스트 프레임워크입니다. 개발자는 화면을 감시하고 컴퓨터 비전으로 UI 요소를 인식한 다음 마우스/키보드(또는 터치) 동작을 시뮬레이션하는 로우코드 "파이프라인"을 작성할 수 있습니다. 코어 라이브러리는 최신 C++20으로 작성되었으며 다양한 언어(Python, C#, Node, Go, Rust 등)와 플랫폼(Windows, Linux, macOS, Android)용으로 제공됩니다.

왜 중요한가

이미지 기반 UI 자동화 – 내부 후크나 접근성 API가 필요 없이 스크린샷 매칭으로 모든 그래픽 프로그램(게임, 앱, 웹 페이지)을 제어할 수 있습니다.
로우코드, 높은 확장성 – 파이프라인은 간단한 선언적 형식으로 기술되지만 사용자 정의 인식기, 컨트롤러, 데이터 소스를 플러그인할 수 있습니다.
다국어 바인딩 – 동일한 엔진을 Python, .NET, JavaScript/Node, Go, Rust 등에서 사용할 수 있어 기존 테스트 스위트에 통합하기 쉽습니다.
생태계 – 코어를 둘러싼 커뮤니티 도구(GUI, 디버거, 로그 분석기, CLI 헬퍼, 스킬 라이브러리)가 성장하고 있어 처음부터 시작하지 않고도 완전한 기능을 갖춘 봇이나 테스트 장비를 구축할 수 있습니다.

핵심 개념(README에 설명됨)

개념	설명	사용 방법
파이프라인	이미지 매칭 단계, 판단 로직, 시뮬레이션 입력을 연결하는 로우코드 "레시피".	시퀀스를 설명하는 YAML/JSON 파일을 작성하면 프레임워크가 자동으로 실행합니다.
프로젝트 인터페이스(PI) v2	전체 자동화 프로젝트(리소스, 파이프라인, 구성)를 패키징하는 프로토콜.	PI 패키지를 내보내거나 가져와 봇/테스트 스위트를 공유하거나 버전 관리합니다.
바인딩	언어별 래퍼(Python `maafw`, .NET `Maa.Framework.Runtimes`, Node `@maaxyz/maa-node` 등).	pip, NuGet, npm, cargo 또는 go 모듈로 설치하고 선호하는 언어에서 동일한 C++ 코어를 호출합니다.
커뮤니티 도구	GUI(MFAAvalonia, MFW‑CFA, MXU, MWU), 디버거(MaaDebugger), 로그 분석기(MaaLogAnalyzer, MaaLogs), CLI 유틸리티(maafw‑cli, MaaCtl), AI 에이전트용 스킬 라이브러리.	워크플로에 맞는 도구를 선택하세요(예: MaaDebugger로 파이프라인 단계별 실행, MaaLogAnalyzer로 실행 추적 시각화).

시작하기(README의 빠른 시작 단계)

웹사이트 방문 – https://maafw.com/ 에서 더 풍부한 문서를 확인하세요.
빠른 시작 가이드 읽기 – docs/zh_cn/1.1-快速开始.md 에서 필요한 언어 바인딩 설치와 샘플 파이프라인 실행 방법을 설명합니다.
라이브러리 통합 – 언어별 통합 문서(2.1-集成文档.md)를 따라 API 목록(2.2-集成接口一览.md)을 살펴보세요.
파이프라인 작성 – "파이프라인 로우코드 프로토콜"(3.1-任务流水线协议.md)을 사용하여 봇이 수행할 단계를 설명하세요.
커뮤니티 확장 살펴보기 – UI 프런트엔드, 디버거, 스킬 팩은 社区项目 아래에 나열됩니다.

MaaFramework는 누가 사용할까?

대상	일반적인 사용 사례
게임 자동화 개발자	화면 스크래핑과 시뮬레이션 탭에 의존하는 모바일/PC 게임용 봇(예: 명일방주용 "M9A", 음양사용 "MaaYYs") 구축.
QA 엔지니어	소스 코드나 접근성 후크가 없는 애플리케이션에 대한 블랙박스 UI 테스트 생성.
AI 에이전트 연구자	시각적 인식과 행동이 필요한 에이전트의 "환경"으로 프레임워크 사용(예: `maafw-cli` 또는 `MaaEvidenceKit` 통해).
도구 개발자	MaaFramework 파이프라인을 오케스트레이션하는 사용자 정의 GUI, 디버거, CI 파이프라인 개발.

더 많은 정보

소스 코드 – https://github.com/MaaXYZ/MaaFramework
패키지 저장소 – PyPI (maafw), NuGet, npm (@maaxyz/maa-node), Go (maa-framework-go), crates.io (maa-framework).
커뮤니티 허브 – https://hub.maafw.com 에서 파이프라인, 스킬, 모듈 공유.
문서 – 영어(README_en.md) 및 중국어(README.md) 버전과 웹사이트.

TL;DR

MaaFramework는 컴퓨터 비전을 사용하여 UI 상호 작용을 구동하는 C++ 기반의 크로스 플랫폼 자동화 엔진입니다. 로우코드 파이프라인 언어, 다양한 언어 바인딩, 활발한 GUI, 디버거, CLI 도구 생태계를 제공하여 게임 봇, UI 테스트, AI 에이전트 환경에 적합합니다.