MaaAssistantArknights 远程控制 API 协议详解getTask 轮询、reportStatus 上报与任务编排实战【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknightsMAAMaaAssistantArknights《明日方舟》全日常一键小助手提供了一套完整的远程控制协议允许第三方服务通过两个匿名可访问的 HTTP(S) 端点对 MAA 实例进行任务下发、状态查询与结果回收。本文以仓库中的 remote-control-schema.md 协议文档为骨架结合 RemoteControlService.cs 等核心源码完整讲解任务获取端点与任务上报端点的数据契约、全部任务类型、MAA 侧轮询与双队列执行机制并给出 QQBot 与网站两种可落地的服务端实现思路帮助开发者独立搭建自己的 MAA 控制中台。一、协议总览两个端点、一条轮询链路远程控制的核心思想非常简单MAA 客户端作为被控方主动向服务端轮询任务执行完毕后把结果回报给服务端。整个协议只依赖两个端点且服务端无需任何鉴权逻辑匿名访问端点在服务端侧对 MAA 完全透明端点作用调用方向调用频率任务获取端点getTask获取待执行任务列表MAA → 服务端固定间隔轮询默认 1 秒可配置任务上报端点reportStatus汇报任务执行结果MAA → 服务端每个任务执行完毕后两个端点的路径完全自由只要符合 HTTP(S) 协议即可例如https://your-control-host.net/maa/getTask与https://your-control-host.net/maa/reportStatus。安全警告协议原文明确强调如果端点使用http://明文协议MAA 每次连接都会发出安全警告将明文传输服务部署到公网是极其危险且不推荐的行为仅可用于本地测试。从源码看这一检查实现在IsEndpointValid方法中端点必须以https://或http://开头前者直接放行后者会弹出RemoteControlConnectionTestWarningHttpUnsafe警告见 RemoteControlService.cs。关于 JSON 注释的提醒JSON 本身不支持注释协议文档中代码块里的//注释仅用于教学演示实际传输时请务必删除。二、任务获取端点getTask2.1 请求格式MAA 以固定间隔默认 1000ms配置项RemoteControlPollIntervalMs持续向该端点发起POST请求Content-Typeapplication/json请求体固定携带两个字段{ user: ea6c39eb-a45f-4d82-9ecc-33a7bf2ae4dc, device: f7cd9682-3de9-4eef-9137-ec124ea9e9ec }user用户标识符由用户手动填写在 MAA 设置界面通常是平台侧分配的用户编号或密钥device设备标识符由 MAA 自动生成的 UUID 字符串标识当前这台 MAA 实例。如果需要复用该端点实现其他业务可以在请求中附加自定义参数但MAA 只会传递user与device这两个字段。这一点在源码中得到印证——轮询循环构造请求时只序列化了new { user uid, device did }见 RemoteControlService.cs。2.2 响应格式端点必须以 JSON 格式返回响应核心字段是tasks——一个任务对象数组。如果响应中没有tasks字段该连接将被视为无效。{ tasks: [ { id: b353c469-b902-4357-bd8f-d133199eea31, type: CaptureImage }, { id: 15be4725-5bd3-443d-8ae3-0a5ae789254c, type: LinkStart }, { id: 15be4725-5bd3-443d-8ae3-0a5ae789254c, type: LinkStart-Recruiting }, { id: b353c469-b902-4357-bd8f-d133199eea31, type: Toolbox-GachaOnce }, { id: b353c469-b902-4357-bd8f-d133199eea31, type: Settings-ConnectAddress, params: value }, { id: b353c469-b902-4357-bd8f-d133199eea31, type: CaptureImageNow }, { id: b353c469-b902-4357-bd8f-d133199eea31, type: StopTask }, { id: b353c469-b902-4357-bd8f-d133199eea31, type: HeartBeat } ] }每个任务对象包含字段类型说明id字符串任务唯一 ID任务执行结果上报reportStatus时原样带回type字符串任务类型决定 MAA 执行的动作见下文任务类型清单params字符串可选任务参数目前仅Settings-*系列任务使用同理tasks之外也可以附加自定义返回值但MAA 只读取tasks字段。2.3 任务类型完整清单MAA 把任务分为两类顺序执行任务Sequential Tasks与即时执行任务Instant Tasks。从源码看两类任务分别进入_sequentialTaskQueue与_instantTaskQueue两个独立队列由两个独立的执行循环消费见 RemoteControlService.cs。顺序执行任务按下发顺序排队执行前一个任务结束才开始下一个。例如先下发公开招募任务、再下发截图任务则截图会在招募任务结束后才执行。支持的类型type 值功能说明LinkStart一键长草完整流程LinkStart-Base一键长草——基建LinkStart-WakeUp一键长草——唤醒LinkStart-Combat一键长草——战斗LinkStart-Recruiting一键长草——公开招募LinkStart-Mall一键长草——信用商店LinkStart-Mission一键长草——领取奖励LinkStart-AutoRoguelike一键长草——自动肉鸽集成战略LinkStart-Reclamation一键长草——生息演算Toolbox-GachaOnce工具箱——单抽Toolbox-GachaTenTimes工具箱——十连CaptureImage截图当前模拟器画面执行完毕后将 Base64 字符串放入上报 payloadSettings-ConnectAddress修改连接设置中的ConnectAddress属性连接地址params传新值Settings-Stage1修改作战任务的关卡选择Stageparams传关卡名其中LinkStart-*系列的特点是按当前配置单独执行对应子功能忽略主界面上的功能勾选状态。从源码LinkStart(IEnumerablestring originalNames)方法可见MAA 会按任务名查找对应类型的已保存任务配置如InfrastTask、FightTask、RoguelikeTask等并序列化后执行见 RemoteControlService.cs。各任务类型的实际动作逻辑如下表源码ExecuteSequentialJobLoop中的switch分支type 值源码动作LinkStart等待空闲后调用TaskQueueViewModel.LinkStart()启动完整一键长草流程LinkStart-*子功能按Base/WakeUp/Combat/Recruiting/Mall/Mission/AutoRoguelike/Reclamation映射到对应任务配置并启动Toolbox-GachaOnce/Toolbox-GachaTenTimes调用ToolboxViewModel.GachaOnce()/GachaTenTimes()执行抽卡CaptureImage通过AsstProxy连接模拟器并抓取最新画面用 PNG 编码后转 Base64 存入 payloadSettings-ConnectAddress在 UI 线程上把ConnectAddress设置为params值Settings-Stage1在 UI 线程上把作战任务的Stage设置为params值即时执行任务可以在顺序任务执行期间随时插入MAA 保证这类任务尽可能快地返回结果通常用于控制远程控制功能本身。多个即时任务同样按下发顺序执行但由于执行速度很快一般无需关注其先后次序type 值功能说明CaptureImageNow立即截图与CaptureImage基本相同但不等待其他任务直接执行StopTask尝试结束当前正在执行的任务若任务列表还有其他任务则继续执行下一个。注意该任务不等待当前任务确认停止后才返回远端应使用心跳任务HeartBeat确认停止命令是否生效HeartBeat心跳任务立即返回payload 为当前顺序任务队列中正在执行的任务 ID若当前无任务执行则返回空字符串去重与可重入getTask 端点应当是可重入的可以反复返回相同的任务列表MAA 会自动记录已接收的任务 ID对相同 ID 的任务不会重复执行。源码中_enqueueTaskIds列表承担这一职责——轮询时若任务 ID 已存在则直接跳过见 RemoteControlService.cs。补充说明协议原文 noteSettings系列任务不是收到后立即执行而是排在前面任务之后按顺序执行若服务端下发了未知类型的任务MAA 会将其忽略源码中同时会解锁一个NotFound404成就彩蛋见 RemoteControlService.cs。三、任务上报端点reportStatus每当 MAA 完成一个任务无论顺序任务还是即时任务都会向该端点发起一次POST上报。请求头Content-Typeapplication/json请求体{ user: ea6c39eb-a45f-4d82-9ecc-33a7bf2ae4dc, device: f7cd9682-3de9-4eef-9137-ec124ea9e9ec, task: 15be4725-5bd3-443d-8ae3-0a5ae789254c, status: SUCCESS, payload: }字段类型说明user字符串用户标识符与 getTask 请求一致device字符串设备标识符与 getTask 请求一致task字符串本次上报的任务 ID与 getTask 下发时的id一一对应status字符串执行结果SUCCESS或FAILED。注意即使任务本身执行失败绝大多数情况下仍返回SUCCESSFAILED只在上文任务说明中明确指出的特殊场景如截图失败返回payload字符串随上报携带的数据内容因任务类型而异。例如截图任务上报时这里携带截图的 Base64 字符串上报端点的响应完全随意MAA 既不读取响应内容也不校验 HTTP 状态码若上报请求失败如网络异常MAA 只会在日志中记录一条错误RemoteControlService report task failed.不会重试也不会阻塞主流程。这意味着服务端可以放心地异步处理上报结果不必追求即时响应。四、MAA 侧实现原理源码级剖析远程控制功能在仓库中的实现集中于 RemoteControlService.cs其运行模型可概括为一拉三循环轮询循环PollJobTaskLoop以RemoteControlPollIntervalMs默认 1000ms为周期调用 getTask 端点解析返回的tasks数组按类型把任务分别投入顺序队列与即时队列并记录任务 ID 去重见 RemoteControlService.cs。顺序任务执行循环ExecuteSequentialJobLoop不断从顺序队列取出任务执行每个任务完成后立即调用 reportStatus 上报再取出下一个见 RemoteControlService.cs。即时任务执行循环ExecuteInstantJobLoop独立消费即时队列保证HeartBeat、StopTask、CaptureImageNow能随时插入执行见 RemoteControlService.cs。几个值得注意的实现细节单例注入RemoteControlService以单例方式注册在依赖注入容器中见 Bootstrapper.cs轮询与执行循环随 MAA 启动常驻运行。心跳的实现HeartBeat任务读取的是_currentSequentialTaskId字段——即当前正在执行的顺序任务的 ID为空则表示当前空闲见 RemoteControlService.cs。因此心跳不仅是保活更是查询 MAA 当前运行状态的唯一手段。停止的实现StopTask调用AsstProxy.AsstStop()尝试终止当前任务且不等待结果立即上报返回见 RemoteControlService.cs所以远端要用心跳确认停止生效。连接测试设置界面提供测试连接按钮其实现ConnectionTest()会向 getTask 端点发送一次 POST依据 HTTP 状态码判断连通性非 2xx 状态码会以 Toast 提示失败原因见 RemoteControlService.cs。这正是下文网站示例中401 即测试失败的机制来源。设备标识符可手动重新生成对应源码RegenerateDeviceIdentity()生成新的 GUID见 RemoteControlService.cs。4.1 客户端配置项与界面被控端 MAA 需要在设置 → 远程控制界面填写以下配置界面定义见 RemoteControlUserControl.xaml配置模型见 RemoteControl.cs界面字段配置项说明获取任务端点RemoteControlGetTaskEndpointUrigetTask 端点完整 URL汇报任务端点RemoteControlReportStatusUrireportStatus 端点完整 URL轮询间隔 (ms)RemoteControlPollIntervalMs轮询周期默认 1000毫秒用户标识符RemoteControlUserIdentity平台侧分配给用户的标识设备标识符只读RemoteControlDeviceIdentityMAA 自动生成的设备 UUID可一键重新生成界面还提供测试连接按钮与指向开发者文档的链接。一个安全细节值得注意user、device以及两个端点地址在保存到本地配置时均经过加密处理SimpleEncryptionHelper.Encrypt见 RemoteControlUserControlModel.cs同时界面上方明确提示随意填入未知来源的地址可能会导致您的账户受到损失见 zh-cn.xaml。五、工作流示例一通过 QQBot 控制 MAA协议文档给出了一个完整可参考的服务端设计范式。开发者 A 希望用 QQBot 控制 MAA于是开发了一个部署在公网的后端提供两个端点https://myqqbot.com/maa/getTask https://myqqbot.com/maa/reportStatus完整的流程设计如下getTask 兼任注册接口getTask 接口对收到的任何参数都默认返回200 OK与空任务列表{tasks:[]}同时每次收到请求都去数据库查重——若设备未注册则把device与user记录入库。这样 getTask 顺带完成了用户注册功能用户无需单独走注册流程。引导用户配置QQBot 提供一条指令让用户提交deviceId。使用说明要求用户把 QQ 号填入 MAA 的用户标识符并把 MAA 的设备标识符通过 QQ 聊天发给 Bot。基于轮询的自动绑定Bot 收到标识符后按消息的 QQ 号查库查不到就提示用户先配置 MAA。由于 MAA 配置完成后就会持续轮询 getTask用户只要配置过提交时库里必然已有对应记录——MAA 的持续轮询天然构成了设备验证手段。标记验证并放行任务Bot 找到记录后将其标记为已验证此后该deviceuser组合的 getTask 请求才会返回真实任务列表。任务下发与结果回传用户在 QQ 中下发指令Bot 把任务写入数据库getTask 轮询时即可取走该 Bot 还贴心地在每次用户指令后默认附带一条截图任务。任务执行完毕后MAA 调用 reportStatus 上报结果Bot 收到后在 QQ 侧给用户发消息并展示截图。这个流程把注册、验证、下发、回传四个环节全部建立在两个匿名端点上是远程控制协议最典型的落地形态。六、工作流示例二通过网站批量管理 MAA开发者 B 面向多实例批量管理场景建设了一个网站自有用户体系后端同样只暴露两个匿名端点https://mywebsite.com/maa/getTask https://mywebsite.com/maa/reportStatus与 QQBot 方案的关键差异在于显式授权与状态码语义网站在连接 MAA 实例界面给每个用户分配一个随机字符串开发者称之为用户密钥并提供输入框让用户填写设备 ID。使用说明要求用户把用户密钥填入 MAA 的用户标识符再把 MAA 生成的设备标识符填到网站上。只有用户成功创建 MAA 连接后getTask 才返回200 OK否则返回401 Unauthorized。这一状态码语义与 MAA 的连接测试机制天然衔接用户在 MAA 设置里点测试连接时若信息填错设备未在网站绑定MAA 会收到 401 并提示测试失败。用户在网站上即可下发任务、查看任务队列、浏览截图其底层实现与 QQBot 示例一致全部由 getTask 与 reportStatus 两个端点组合完成。两种工作流对比QQBot 方案更轻量、以轮询驱动注册验证网站方案更严谨用 HTTP 状态码表达授权状态适合需要批量纳管大量 MAA 实例的运营场景。七、开发者落地清单与注意事项基于协议文档与源码实现服务端开发者在实现时应注意以下几点端点必须为 HTTP(S)路径任意生产环境务必使用 HTTPS避免明文传输用户标识与设备标识被窃取。getTask 必须返回tasks数组否则连接判为无效没有任务时返回{tasks:[]}即可。任务 ID 必须唯一且稳定——MAA 按 ID 去重重复下发相同 ID 不会再次执行需要重跑同一任务时应生成新 ID。截图任务的体量模拟器全屏截图的 Base64 可能达到数十 MB很容易超过常见网关Nginx、网关代理等的默认请求体大小限制。若需要下发CaptureImage/CaptureImageNow务必提前调大上报端点的最大请求尺寸否则截图上报会被网关拦截。状态判定策略绝大多数任务无论成败都上报SUCCESS只有明确失败场景才上报FAILED同时StopTask不等确认即返回因此停止是否生效当前是否空闲应依靠HeartBeat的 payload 来判断而不是依赖 StopTask 的上报结果。顺序任务与即时任务分开设计需要先 A 后 B的编排全部用顺序任务HeartBeat、StopTask、CaptureImageNow是即时任务可随时穿插。本地配置加密用户标识符、设备标识符与端点地址在 MAA 本地以加密形式存储服务端应同样以安全方式保管用户标识与设备绑定关系。八、总结MAA 远程控制协议的设计极简而实用MAA 主动轮询的模型免去了服务端到客户端的反向连接与内网穿透需求匿名端点配合用户/设备双标识让注册、验证、下发、上报四个环节可以在任意后端技术栈上轻松实现。理解 RemoteControlService.cs 中的轮询 双队列执行 结果上报闭环以及 RemoteControl.cs 中五个配置项的语义即可在此基础上构建 QQBot、网站控制台、消息推送机器人等任意形态的 MAA 远程管理平台。更多协议细节可查阅仓库中的 英文版协议文档多语言文档位于 docs 目录下的各语言protocol/子目录。【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考