MaaFramework 实战：5 步创建自定义识别与操作模块
MaaFramework 是一款基于图像识别的自动化黑盒测试框架，通过自定义识别与操作模块，开发者可以轻松扩展框架功能以适应各种复杂场景。本文将详细介绍如何在 5 个简单步骤内完成自定义模块的创建与集成。
1. 准备开发环境
首先确保已正确安装 MaaFramework 开发环境，克隆官方仓库：
# 替换为官方仓库地址
git clone <repository_url>
项目中提供了多种语言的示例代码，其中 NodeJS 版本的自定义模块开发文档位于 docs/zh_cn/NodeJS/J1.2-自定义识别_操作.md，建议先阅读该文档了解基本概念。
2. 定义自定义识别模块
自定义识别模块用于识别屏幕上的特定元素，需要定义识别规则和返回格式。创建识别配置文件，指定识别类型为 Custom 并设置唯一标识符：
{
"Task": {
"recognition": "Custom",
"custom_recognition": "myReco",
"custom_recognition_param": {
"msg": "Hello world!"
}
}
}
在代码中实现识别逻辑，通过注册函数将自定义识别器添加到框架中：
export interface CustomRecognizerSelf {
context: Context;
id: maa.TaskId;
name: string;
param: unknown;
image: maa.ImageData;
}
res.register_custom_recognizer('myReco', function (this: CustomRecognizerSelf, self: CustomRecognizerSelf) {
return [
{ x: 0, y: 0, width: 0, height: 0 },
'识别结果详情'
];
});
3. 创建自定义操作模块
自定义操作模块用于执行特定的交互动作，如点击、滑动等。类似地，先定义操作配置：
{
"Task": {
"action": "Custom",
"custom_action": "myAct",
"custom_action_param": {
"msg": "Hello world!"
}
}
}
然后实现操作逻辑，注册自定义动作：
interface CustomActionSelf {
context: Context;
id: maa.TaskId;
name: string;
param: unknown;
box: maa.Rect;
detail: string;
}
inst.register_custom_action('myAct', function (this: CustomActionSelf, self: CustomActionSelf) => {
// 执行自定义操作逻辑
return true;
});
4. 模块集成与测试
将自定义模块集成到 MaaFramework 项目中，建议参考 sample/nodejs/main.ts 中的示例代码。测试时可使用项目提供的测试图片。
该图片分辨率为 1920x1080，适合用于测试各种屏幕识别场景。通过 Agent 进程托管自定义模块，便于承载复杂逻辑，相关测试代码可参考 test/agent/agent_child_test.py。
5. 高级应用：模块间调用
MaaFramework 支持自定义模块间的相互调用，实现复杂业务逻辑。例如在识别模块中调用其他任务进行辅助识别：
inst.register_custom_recognizer('forward', (self) => {
return self.context.run_recognition('another_task', self.image);
});
在操作模块中调用其他任务执行复合操作：
inst.register_custom_action('forward', (self) => {
return self.context.run_action('another_task', box, detail);
});
通过这种方式，可以构建出功能强大的自动化测试流程，满足各种复杂场景需求。
通过以上 5 个步骤，你已经掌握了 MaaFramework 自定义识别与操作模块的创建方法。更多高级技巧和最佳实践，请参考官方文档 docs/zh_cn/2.2-集成接口一览.md。
