MaaEnd Go Service开发指南：Custom Action与Custom Recognition注册机制详解

MaaEnd Go Service开发指南Custom Action与Custom Recognition注册机制详解【免费下载链接】MaaEndMaaEnd 终末地小助手基于视觉 AI 的「明日方舟终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEndMaaEnd 是基于视觉 AI 的《明日方舟终末地》自动化工具其 Go Service 通过Custom Action自定义动作与Custom Recognition自定义识别的注册机制把 Pipeline 难以实现的复杂算法扩展为 Pipeline 节点可直接调用的能力。本指南带你彻底搞懂这套注册机制从哪里注册、如何注册、改完还要同步哪些文件。为什么需要注册机制Pipeline 管流程Go 管难点MaaEnd 的主体流程由 Pipeline JSON 以低代码方式描述——截图、识别、点击、跳转全部声明式完成。但有些能力 JSON 写不出来比如网格扫描、图标识别等复杂图像算法需要维护状态的多步交互如 AutoStockpile 的库存决策需要读取/写入本地数据如 IMS 的物品数据库。这些就由 Go 编写的 go-service 承担。Go 进程通过 MaaFramework 的 Agent Server 协议运行入口见 main.go注册一个Custom Action或Custom Recognition后它就能在 Pipeline 里像原生节点一样被action/recognition字段引用——这就是注册机制的核心价值一次注册全流程可用。注册机制全景两级注册结构MaaEnd 采用「子包自注册 主入口统一接入」的两级结构改动时只需记住两处层级文件职责① 子包级每个功能子包内的 register.go调用maa.AgentServerRegisterCustomAction/maa.AgentServerRegisterCustomRecognition注册本包的组件② 主入口级agent/go-service/register.go 的registerAll()按「Pre-Check / General / Business」三类调用各子包的Register()并接入资源路径 Sink例如 falseaction 子包的注册只有几行一目了然func Register() { maa.AgentServerRegisterCustomAction(FalseAction, FalseAction{}) }对应地主入口 register.go 中会有一行falseaction.Register()。registerAll()里的分组注释Pre-Check Custom / General Custom / Business Custom直接告诉了你组件的定位前置检查类如分辨率、HDR 检测、通用能力类OCR、子任务调度、业务功能类自动配送、仓库囤货等。Custom Action 注册四步走 ️以新增一个名为MyAction的自定义动作为例第 1 步新建子包在 agent/go-service/ 下创建myaction/目录通用能力放common/下。第 2 步实现组件。定义一个结构体实现maa.CustomActionRunner接口Run方法返回执行是否成功type MyAction struct{} var _ maa.CustomActionRunner MyAction{} func (a *MyAction) Run(ctx *maa.Context, arg *maa.CustomActionArg) bool { // 通过 ctx 截图、点击、OCR…… return true }可参考最简实现 falseaction/action.go。第 3 步包内注册在子包的register.go中调用maa.AgentServerRegisterCustomAction(MyAction, MyAction{})。第 4 步主入口接入在 registerAll() 中按分类加一行myaction.Register()。Custom Recognition 注册四步走 ️流程完全对称区别是接口换成识别器。参考 autoecofarm/register.go 的双组件注册示例maa.AgentServerRegisterCustomRecognition( autoEcoFarmCalculateSwipeTarget, autoEcoFarmCalculateSwipeTarget{})四步走新建子包实现maa.CustomRecognitionRunner对截图做识别输出位置/数据包内register.go调用maa.AgentServerRegisterCustomRecognition主入口registerAll()接入子包Register()在 Pipeline 节点的recognition字段中使用注册名即可在 Pipeline JSON 中被调用。批量注册的实际案例可参考 aerosalvage/register.go——一个子包注册了 3 个识别器气球状态、网格、初始状态。注册名改了别忘了同步 Schema ⚠️注册机制还有一条隐藏规则注册名是对外契约。改名或删除组件时除了更新 Pipeline 中的用法还必须同步两处 JSON Schema 的enumCustom Action 名 → tools/schema/custom.action.schema.jsonCustom Recognition 名 → tools/schema/custom.recognition.schema.json同时遵循 AGENTS.md 中的两条「参数极简」约定custom_action_param/custom_recognition_param只保留用户明确需要的参数不要自行设计大接口无参数或允许任意值透传时无需创建空参数 Schema。注册时常见的 5 个坑一次列清只改了子包 register.go忘了registerAll()——组件根本不会被加载注册名拼写与 Pipeline 中不一致——节点静默跳过排查困难Schema enum 未同步——编辑期校验报错或误报把业务流程写进了 Go——违背「Pipeline 管流程Go 管难点」会被 Review 打回忘了提交前格式化——按规范执行pnpm format:goGo、pnpm formatJSON。动手前先看这三份资料 全局规范AGENTS.md编码指南与审查重点公共包用法docs/zh_cn/developers/go-service-pkg.mdAnd 解包、条件计算等pkg/工具节点测试写法docs/zh_cn/developers/node-testing.md——新增识别节点后在 tests/ 目录补充用例掌握「两级注册 Schema 同步」这套机制后你就能像 MaaEnd 维护者一样把任意复杂视觉算法安全地扩展进整个自动化流程中了。【免费下载链接】MaaEndMaaEnd 终末地小助手基于视觉 AI 的「明日方舟终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEnd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考