MaaFramework 提供三种集成方案,满足不同开发场景需求:
适用场景:快速入门、简单逻辑实现
特点:
// 注意:JSON 不支持注释,以下为示意代码,仅供参考思路,无法直接运行
{
"点击开始按钮": {
"recognition": "OCR", // 文字识别引擎
"expected": "开始", // 目标文本
"action": "Click", // 执行点击操作
"next": ["点击确认图标"] // 后续任务链
},
"点击确认图标": {
"recognition": "TemplateMatch",// 图像模板匹配
"template": "确认.png", // 匹配素材路径
"action": "Click"
}
}
💡 v4.x 版本核心特性
特点:
- 保留 JSON 低代码优势
- 通过 AgentServer 注册自定义任务模块
- 无缝衔接 ⭐项目模板
{
"点击确认图标": {
"next": ["自定义处理模块"]
},
"自定义处理模块": {
"recognition": "Custom",
"custom_recognition": "MyReco", // 自定义识别器ID
"action": "Custom",
"custom_action": "MyAct" // 自定义动作ID
}
}
💡 通用 UI 会自动连接您的 AgentServer 子进程,并在执行到 MyReco
/MyAct
时,调用对应的识别/动作。
# Python 伪代码示例
from maa.agent.agent_server import AgentServer
# 注册自定义识别器
@AgentServer.custom_recognition("MyReco")
class CustomReco:
def analyze(ctx):
return (10,10,100,100) # 返回您自己处理的识别结果
# 注册自定义动作
@AgentServer.custom_action("MyAct")
class CustomAction:
def run(ctx):
ctx.controller.post_click(100, 10).wait() # 执行点击
ctx.override_next(["TaskA", "TaskB"]) # 动态调整任务流
# 启动Agent服务
AgentServer.start_up(sock_id)
完整示例参考 模板 Commit。
适用场景:
- 深度定制需求
- 复杂业务逻辑实现
- 需要灵活控制执行流程
# Python 伪代码示例
def main():
# 执行 JSON 预定义任务
result = tasker.post_task("点击开始按钮").wait().get()
if result.completed:
# 执行代码级操作
tasker.controller.post_click(100, 100)
else:
# 获取当前屏幕截图
image = tasker.controller.cached_image
# 注册自定义动作
tasker.resource.register_custom_action("MyAction", MyAction())
# 执行混合任务链
tasker.post_task("点击确认图标").wait()
⭐若您使用项目模板,直接在 文件夹 中修改即可。
my_resource/
├── image/ # 图像素材库
│ ├── my_button_ok.png
│ └── my_icon_close.png
├── model/
│ └── ocr/ # 文字识别模型
│ ├── det.onnx
│ ├── keys.txt
│ └── rec.onnx
└── pipeline/ # 任务流水线
├── my_main.json
└── my_subflow.json
其中以 my_
开头的文件/文件夹均可自行修改名称,其他的则为固定文件名,不可修改,下面依次介绍:
my_resource/pipeline
中的文件,包含主要的脚本执行逻辑,会递归读取目录中所有的 json 格式文件。
小工具:
- JSON Schema
- VSCode 插件
- 基于
interface.json
配置资源 - 支持跳转到任务定义、查找任务引用、重命名任务、补全任务、点击执行任务
- 支持按照 MaaPiCli 模式执行
- 支持连接后截图并裁剪图片
- 基于
my_resource/image
中的文件,主要为 pipeline 所用到的模板匹配图片、特征检测图片等,会按照 pipeline 中设定的 template
等字段读取对应的文件。
所使用的图片需要是无损原图缩放到 720p 后的裁剪。除非你完全清楚 MaaFramework 在做什么,否则请使用下面的截图工具来获取图片。
⭐若您使用项目模板,直接按照其文档,运行 configure.py
即可自动部署模型文件。
my_resource/model/ocr
中的文件,为 PaddleOCR 转 ONNX 后的模型文件。
可使用我们的预转换文件:MaaCommonAssets,选择需要的语种,按照 上述 目录结构存放即可。
若有需要也可以自行对 PaddleOCR 的官方预训练模型进行 fine-tuning (请自行参考 PaddleOCR 官方文档),并转换成 ONNX 文件使用,转换命令可参考 这里
-
使用 MaaDebugger。
-
使用 VSCode 插件。
-
使用 MaaPiCli ,会在同目录下生成
config/maa_option.json
文件,其中:logging
: 保存日志,会生成debug/maa.log
。默认 true 。recording
: 保存录像功能,会保存运行期间所有的截图及操作数据,可使用DbgController
进行复现调试。默认 false 。save_draw
: 保存图像识别可视化结果,会保存运行期间所有图像识别可视化结果绘制图。默认 false 。show_hit_draw
: 显示节点命中弹窗,每次识别成功会弹窗显示识别结果。默认 false 。stdout_level
: 控制台显示日志等级。默认 2(Error),可设为 0 关闭全部控制台日志,或设为 7 打开全部控制台日志。
-
若自行集成,可通过
Toolkit.init_option
/MaaToolkitConfigInitOption
接口开启调试选项。生成的 json 文件同上。
使用 通用 UI(如 MaaPiCli, MFA, MFW 等)或者 自行编写集成代码
⭐若您使用项目模板,直接按照其文档,运行 install.py
后即可自动打包相关文件
使用 Release 包 bin 文件夹中的 MaaPiCli ,并编写 interface.json
置于同目录下,即可使用
实践:
请参考 集成文档