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

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

【免费下载链接】MaaEndMaaEnd 终末地小助手：基于视觉 AI 的「明日方舟：终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEnd

MaaEnd 是基于视觉 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{})

四步走：

1. 新建子包，实现maa.CustomRecognitionRunner（对截图做识别，输出位置/数据）；
2. 包内register.go调用maa.AgentServerRegisterCustomRecognition；
3. 主入口registerAll()接入子包Register()；
4. 在 Pipeline 节点的recognition字段中使用注册名，即可在 Pipeline JSON 中被调用。

批量注册的实际案例可参考 aerosalvage/register.go——一个子包注册了 3 个识别器（气球状态、网格、初始状态）。

注册名改了？别忘了同步 Schema ⚠️

注册机制还有一条隐藏规则：注册名是对外契约。改名或删除组件时，除了更新 Pipeline 中的用法，还必须同步两处 JSON Schema 的enum：

• Custom Action 名 → tools/schema/custom.action.schema.json
• Custom Recognition 名 → tools/schema/custom.recognition.schema.json

同时遵循 AGENTS.md 中的两条「参数极简」约定：

• custom_action_param/custom_recognition_param只保留用户明确需要的参数，不要自行设计大接口；
• 无参数或允许任意值透传时，无需创建空参数 Schema。

注册时常见的 5 个坑，一次列清：

1. 只改了子包 register.go，忘了registerAll()——组件根本不会被加载；
2. 注册名拼写与 Pipeline 中不一致——节点静默跳过，排查困难；
3. Schema enum 未同步——编辑期校验报错或误报；
4. 把业务流程写进了 Go——违背「Pipeline 管流程，Go 管难点」，会被 Review 打回；
5. 忘了提交前格式化——按规范执行pnpm format:go（Go）、pnpm format（JSON）。

动手前先看这三份资料 📚

• 全局规范：AGENTS.md（编码指南与审查重点）
• 公共包用法：docs/zh_cn/developers/go-service-pkg.md（And 解包、条件计算等pkg/工具）
• 节点测试写法：docs/zh_cn/developers/node-testing.md——新增识别节点后在 tests/ 目录补充用例

掌握「两级注册 + Schema 同步」这套机制后，你就能像 MaaEnd 维护者一样，把任意复杂视觉算法安全地扩展进整个自动化流程中了。

【免费下载链接】MaaEndMaaEnd 终末地小助手：基于视觉 AI 的「明日方舟：终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEnd