MaaNTE Python Custom Action 开发指南图像识别搞不定时如何编写复杂自定义逻辑【免费下载链接】MaaNTEMaaNTE. Nevertheless to Everless automatic assistant 异环小助手项目地址: https://gitcode.com/gh_mirrors/maa/MaaNTEMaaNTE 是《异环》Neverless的开源自动助手基于 MaaFramework 用 Pipeline JSON 实现识别 → 操作的游戏自动化。当图像识别搞不定——需要多轮重试、动态决策、复杂循环时就用 PythonCustom Action接管。本文是一份面向新手的完整指南教你快速编写复杂自定义逻辑。一、先理解分工Pipeline 管流程Python 管难点MaaNTE 的核心设计哲学只有一句话出自 编码规范Pipeline 管流程Python 管难点。Pipeline JSON位于assets/resource/base/pipeline/负责绝大多数工作模板匹配、OCR、点击、按键、流程跳转。Python Custom Action位于agent/custom/action/只处理 JSON 写不动的难点复杂状态机、滚动查找、声音触发、模型推理等。没有必要的 Python 逻辑会大大增加代码复杂度所以写自定义动作前的第一原则是先问自己这个逻辑能否用 Pipeline 节点表达那么什么场景图像识别搞不定、必须上 Python需要循环滚动列表直到找到目标如做咖啡选配方需要多次识别 条件分支组成的复杂状态机需要解析多个识别结果做二次计算如读多行 OCR 文本需要长循环等待且随时响应停止指令二、环境准备一键搭建开发环境开发 Python Custom Action 只需 Python 3.11 与 Git克隆仓库时注意带上子模块内含模型资源git clone --recurse-submodules https://gitcode.com/gh_mirrors/maa/MaaNTE cd MaaNTE python -m venv .venv .venv/Scripts/activate # Windows pip install -r requirements.txt推荐使用 VS Code 并安装Maa Pipeline Support插件可以右键对节点直接测试识别与动作所有坐标换算基于1280×720基准。三、最小示例从 20 行代码读懂 Custom Action项目里最简单的自定义动作是click_overrideCommon/click.py完整源码不到 30 行看懂它就掌握了骨架用装饰器AgentServer.custom_action(click_override)注册动作名类继承CustomAction实现run(self, context, argv)方法通过context.tasker.controller拿到控制器执行点击解析argv.custom_action_paramPipeline 里传来的参数返回CustomAction.RunResult(successTrue/False)。而一个复杂逻辑的代表作是自动做咖啡AutoCoffee/auto_make_coffee.py它的写法值得逐段学习截图get_image(controller)拿到 numpy 数组直接喂给 OpenCV 做模板匹配调用 Pipeline 已有识别节点context.run_recognition(MakeCoffeeStart, img)——复用 JSON 里定义的识别Python 只做编排响应停止每个长循环里检查context.tasker.stopping这是规范里明确要求的安全检查进度提示用maafocus.PrintT(context, coffee.making, ...)把消息推送到客户端界面。四、必备工具箱Common/utils.py 的三个函数写自定义动作前先看 Common/utils.py三个工具函数覆盖 90% 的场景函数作用get_image(controller)截屏返回 numpy 数组可配合 OpenCV 任意发挥click_rect(controller, rect, delay)点击指定 rect 的中心点match_template_in_region(img, region, template, ...)在指定区域内模板匹配返回(hit, score, x, y)load_params(custom_action_param)容错解析 Pipeline 传入的参数None/dict/JSON 字符串通吃from Common.utils import get_image, click_rect, match_template_in_region img get_image(controller) hit, score, x, y match_template_in_region(img, [0, 0, 1280, 720], template, 0.8) if hit: click_rect(controller, [x, y, 50, 50])五、注册与调用让 Pipeline 用上你的动作Python 侧注册两步走在 agent/custom/action/ 下新建你的 Python 文件写好AgentServer.custom_action(你的动作名)在 agent/custom/action/__init__.py 中from .你的模块 import *并把类名加入__all__。Pipeline 侧调用在节点里把action设为Custom类型{ action: { type: Custom, param: { custom_action: auto_make_coffee, custom_action_param: { count: 10 } } } }custom_action的值必须与 Python 装饰器里的名字完全一致custom_action_param会以 JSON 字符串形式传到 Python。六、避坑清单新手最常踩的 5 个坑结合 编码规范 的常见坑章节坐标不是 720p 基准——所有roi、target、box必须基于 1280×720MaaFramework 会自动适配用户设备长循环不检查停止——忘记检查context.tasker.stopping会让用户无法停止任务用户消息和调试日志混用——给玩家看的用maafocus.PrintT()支持 i18n调试用utils.logger能用 Pipeline 表达却硬写 Python——不必要的 Python 逻辑会让维护者崩溃先复用再新增本地能跑用户不行——检查用户的帧率、颜色滤镜、HDR 设置是否与基准一致HDR 下截图取色会失真。七、下一步继续阅读自定义动作文档现成动作清单与编写要点Pipeline 编写指南识别/动作类型的完整参考节点测试如何高效验证识别节点快速开始从需求到 PR 的完整开发流程掌握识别 → 操作 → 再识别的铁律把流程交给 Pipeline、把难点交给 Python你就能为 MaaNTE 贡献稳定可靠的复杂自动化功能了。【免费下载链接】MaaNTEMaaNTE. Nevertheless to Everless automatic assistant 异环小助手项目地址: https://gitcode.com/gh_mirrors/maa/MaaNTE创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考