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を必要とせず、スクリーンショットを照合することで、あらゆるグラフィカルなプログラム（ゲーム、アプリ、Webページ）を制御できます。
ローコードで高い拡張性 – パイプラインはシンプルな宣言形式で記述できますが、カスタム認識器、コントローラー、データソースをプラグインできます。
多言語バインディング – 同じエンジンを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のクイックスタート手順）

Webサイトを訪れる – 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）版、およびWebサイト。

TL;DR

MaaFrameworkは、コンピュータビジョンを使用してUI操作を駆動するC++ベースのクロスプラットフォーム自動化エンジンです。ローコードのパイプライン言語、多数の言語バインディング、そして活発なGUI、デバッガ、CLIツールのエコシステムを提供しており、ゲームボット、UIテスト、AIエージェント環境に適しています。