MAA 远程控制协议Remote Control Schema全解析基于 HTTP(S) 双端点的任务下发与状态上报【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights导读MaaAssistantArknights以下简称 MAA的远程控制协议是一套完全基于 HTTP(S) 的双匿名端点机制MAA 客户端通过「任务获取端点」周期性轮询远端下发的任务清单按序执行后通过「任务上报端点」把结果回报给服务端。本文以官方协议文档为核心结合仓库内 RemoteControlService.cs 等源码实现完整讲解请求/响应格式、全部任务类型语义、客户端配置项并给出 QQBot 与网站两个端到端落地示例。读完本文你可以独立实现一个控制 MAA 的远程服务端。一、协议概览与安全前提要远程控制 MAA你提供的服务必须满足两个硬性条件必须是HTTP(S) 服务并对外暴露两个匿名可访问的 Web 端点两个端点分别承担「任务获取」与「任务上报」职责路径可自定义但必须是http或https协议的 Web 端点。端点使用http明文协议时MAA 会在每次连接时弹出「不安全」警告。协议文档明确警示在公网上部署明文传输服务非常危险仅建议用于测试生产环境务必使用 HTTPS。此外协议文档特别提醒JSON 文件本身不支持注释文档示例中的行内注释仅为讲解用途实际部署时必须移除后才能使用。二、任务获取端点Get Task2.1 轮询机制MAA 会以固定间隔持续轮询任务获取端点默认间隔为1 秒可在 MAA 设置中调整。拿到任务清单后MAA 按清单顺序依次执行。端点路径自由例如https://your-control-host.net/maa/getTask被控端 MAA 需要在设置的「任务获取端点Get Task Endpoint」输入框中填入该端点地址。2.2 请求格式该端点必须能接收Content-Typeapplication/json的 POST 请求请求体格式如下{ user: ea6c39eb-a45f-4d82-9ecc-33a7bf2ae4dc, // 用户在 MAA 设置中填写的用户标识符 device: f7cd9682-3de9-4eef-9137-ec124ea9e9ec // MAA 自动生成的设备标识符 ... }其中user用户在 MAA 设置中手动填写的用户标识用于服务端区分不同用户deviceMAA自动生成的设备标识符标识具体的 MAA 实例客户端其余字段为可选协议约定 MAA只发送user和device两个字段若你的端点有其他用途可以自行附加可选参数。2.3 响应格式与任务类型端点必须以 JSON 格式返回响应且至少包含tasks字段——若响应中没有tasksMAA 会认为连接无效。{ 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任务上报时用于关联该任务type字符串任务类型决定任务行为下表详述params字符串可选部分任务如Settings-*系列需要携带的修改值顺序执行任务Sequential Tasks这类任务会按下发顺序进入队列排队依次执行CaptureImage截图任务。捕获当前模拟器画面以 Base64 字符串放入任务上报的payload。注意下发该任务前要确认你的端点允许的最大请求体大小——截图可能达数十 MB会超过常见网关的默认限制例如 nginx 默认client_max_body_size仅 1MB。LinkStart触发「一键长草」StartUp主流程。LinkStart-[TaskName]仅执行一键长草的某个子功能基于当前设置忽略主界面勾选状态。可选值见下文。Toolbox-GachaOnce/Toolbox-GachaTenTimes工具箱的「抽卡 1 次 / 抽卡 10 次」任务。Settings-[SettingsName]修改设置的任务等价于在连接设置中修改对应属性。出于安全考虑并非所有设置都可被远程修改可选值见下文修改目标值放在params字段。LinkStart-[TaskName]的type可选值LinkStart-Base // 基建换班 LinkStart-WakeUp // 唤醒 LinkStart-Combat // 刷理智作战 LinkStart-Recruiting // 公开招募 LinkStart-Mall // 信用商店 LinkStart-Mission // 领取奖励 LinkStart-AutoRoguelike // 自动肉鸽集成战略 LinkStart-Reclamation // 生息演算Settings-[SettingsName]的type可选值Settings-ConnectAddress // 连接设置中的连接地址ConnectAddress Settings-Stage1 // 作战任务的关卡选择注意Settings系列任务同样属于顺序执行任务不会收到即插即执行而是排在前面任务结束后再执行。立即执行任务Instant Tasks这类任务可以在顺序任务执行期间插入MAA 保证尽快返回结果主要用于控制远程控制功能本身CaptureImageNow立即截图任务。与CaptureImage类似但不等待其他任务立刻执行。StopTask停止当前任务。尝试结束正在运行的任务若队列中还有后续任务则继续执行。该任务不等确认停止完成就返回是否真正停止需通过HeartBeat确认。HeartBeat心跳任务。立即返回把当前「顺序执行队列」中正在执行的任务 ID 放入payload若无任务在执行则返回空字符串。多个立即执行任务之间也按下发顺序执行但由于它们执行极快顺序通常无需在意。2.4 执行顺序与幂等去重任务按顺序执行例如先下发公开招募任务、再下发截图任务那么截图会在招募结束后才执行。端点必须可重入reentrant即可以反复被轮询并重复返回待执行任务列表。MAA 会自动记录已接收的任务 ID同一 ID 的任务不会重复执行。从源码看这一机制由 RemoteControlService.cs 的PollJobTaskLoop实现每次轮询解析响应中的tasks数组通过_enqueueTaskIds列表做 ID 去重然后按类型分流进_sequentialTaskQueue顺序执行队列与_instantTaskQueue立即执行队列两个并发队列。轮询间隔取自RemoteControlPollIntervalMs配置项默认 1000 毫秒RemoteControl.cs。未知的任务类型会走default分支触发NotFound404成就追踪而不会中断服务。三、任务上报端点Report StatusMAA 完成一个任务后会通过该端点把执行结果上报给远程服务端。端点路径自由例如https://your-control-host.net/maa/reportStatus被控端 MAA 需要在设置的「任务上报端点Report Task Endpoint」输入框中填入该地址。3.1 请求格式同样是Content-Typeapplication/json的 POST 请求请求体格式如下{ user: ea6c39eb-a45f-4d82-9ecc-33a7bf2ae4dc, // 用户在 MAA 设置中填写的用户标识符 device: f7cd9682-3de9-4eef-9137-ec124ea9e9ec, // MAA 自动生成的设备标识符 task: 15be4725-5bd3-443d-8ae3-0a5ae789254c, // 被上报任务的任务 ID与任务获取时下发的 ID 一致 status: SUCCESS, // 任务执行结果SUCCESS 或 FAILED payload: // 上报数据字符串依任务类型而定如截图任务的 Base64 ... }字段语义user/device与任务获取端点中的含义一致task本次上报关联的任务 ID必须与 Get Task 下发的id对应用于服务端匹配任务与结果status任务执行结果取值SUCCESS或FAILED。一般情况下无论任务成功与否都返回SUCCESS仅在任务说明中明确标注的特殊情况如CaptureImage截图失败才返回FAILEDpayload上报数据字符串随任务类型变化例如截图任务在此放入 Base64 编码的截图片数据。3.2 响应约定该端点的返回内容完全自由MAA 不读取返回体、也不校验状态码。上报请求失败时MAA 仅在日志中记录错误不影响主流程。从源码看ExecuteSequentialJobLoop 在每次顺序任务执行完毕后会把user、device、status、task、payload组装成匿名对象通过Instances.HttpService.PostAsJsonAsyncPOST 到RemoteControlReportStatusUri请求失败仅输出RemoteControlService report task failed.错误日志。立即执行队列的 ExecuteInstantJobLoop 行为一致。HeartBeat的payload直接取当前正在执行的顺序任务 ID 字段_currentSequentialTaskId这就是远程端判断「当前在跑什么任务 / 是否卡死」的依据。四、MAA 客户端侧配置与交互4.1 五个核心配置项协议对应的客户端配置在 RemoteControl.cs 中定义共五项配置项配置键默认值说明任务获取端点RemoteControl.RemoteControlGetTaskEndpointUri空字符串Get Task 端点地址任务上报端点RemoteControl.RemoteControlReportStatusUri空字符串Report Status 端点地址用户标识符RemoteControl.RemoteControlUserIdentity空字符串用户手动填写用于服务端区分用户设备标识符RemoteControl.RemoteControlDeviceIdentity空字符串MAA 自动生成标识本机实例轮询间隔RemoteControl.RemoteControlPollIntervalMs1000毫秒轮询 Get Task 与两个执行循环的间隔配置键的完整定义见 ConfigurationKeys.cs。设置面板的视图模型 RemoteControlUserControlModel.cs 会在写入时通过SimpleEncryptionHelper.Encrypt对端点地址、用户标识与设备标识做加密存储读取时解密——这解释了为什么端点中会看到不可读的密文。4.2 设备标识的生成与连接测试设备标识由 MAA 自动生成RegenerateDeviceIdentity方法用Guid.NewGuid().ToString(N)重新生成一个 32 位无连字符的 UUIDRemoteControlService.cs并允许用户手动点击「重新生成Regenerate」刷新。IsEndpointValid对端点做合法性校验RemoteControlService.cs以https://开头 → 合法以http://开头 → 合法但提示「不安全」其他协议 → 非法直接判定连接测试失败。ConnectionTest方法会真实向 Get Task 端点发起一次 POST请求体为{ user, device }非 2xx 状态码即弹出「连接测试失败」提示RemoteControlService.cs。这正好对应协议文档网站示例中「连接测试」的行为。4.3 设置界面布局设置页 RemoteControlUserControl.xaml 从上到下依次为安全提示横幅、任务获取端点输入框、任务上报端点输入框、轮询间隔输入框、用户标识输入框附带「测试连接」按钮、只读且可复制的设备标识框附带「重新生成」按钮以及跳转远程控制开发文档的超链接。界面文案与警告如RemoteControlTooltips「输入未知来源的地址可能导致账号丢失」定义在 en-us.xaml 等本地化资源中。五、示例工作流一用 QQBot 控制 MAA开发者 A 想用自建 QQBot 控制 MAA于是开发了一个暴露在公网的 backend提供两个端点https://myqqbot.com/maa/getTask https://myqqbot.com/maa/reportStatus完整交互链路如下被动注册为方便用户getTask接口对任何参数都默认返回 200 OK 和空tasks列表。每次收到请求时检查数据库里是否已有该device没有则把device与user记录下来——这个接口顺带充当了用户注册功能。上报设备 IDA 在 QQBot 里提供让用户提交deviceId的命令并在使用说明中引导用户把 QQ 号填入 MAA 的「用户标识符」把 MAA 的「设备标识符」复制发给机器人。绑定验证机器人收到标识符后根据消息发送者的 QQ 号查数据库查不到就提示用户先完成 MAA 配置因为 MAA 一旦配置好就会持续轮询请求用户来发消息时数据库里应当已有记录。查到后把该记录标记为「已认证」此后getTask对已认证的deviceuser组合才返回真实任务列表。下发任务用户在 QQ 里发送指令如「开始长草」机器人把任务写入数据库下一次getTask轮询就会返回该任务。A 还贴心地在用户每次下指令时自动追加一个截图任务。结果回报MAA 执行完任务调用reportStatus机器人收到结果后通过 QQ 消息把通知和截图发给用户。六、示例工作流二用网站批量管理 MAA开发者 B 想通过网站批量管理大量 MAA 实例自建了带会员系统的后端同样开放两个匿名端点https://mywebsite.com/maa/getTask https://mywebsite.com/maa/reportStatus交互要点用户密钥网站提供 MAA 连接页面展示一个称为「用户密钥User Key」的随机字符串并提供「设备标识符」输入框用户把密钥填入 MAA 的「用户标识符」再把 MAA 的设备标识符填回网站。鉴权与测试联动网站设定只有成功创建连接后getTask才返回 200 OK否则返回 401 Unauthorized。因此用户一旦在 MAA 中填错信息并点击「连接测试」会立刻收到失败通知——这正是上一节ConnectionTest校验逻辑的典型应用。任务管理用户可在网站上发任务、查看队列、查看截图实现方式与 QQBot 示例相同本质都是「getTask下发 reportStatus回报」的组合。两个示例共同揭示了协议的设计哲学getTask即“拉取指令”reportStatus即“回传结果”而userdevice二元组是服务端做用户识别与绑定的锚点。注册、鉴权、任务队列、通知推送等业务能力全部由服务端在两端点之外自行实现。七、开发要点总结协议本质两个 HTTP(S) 匿名 POST 端点即可完成远程控制闭环无需 MAA 端安装任何额外组件安全红线生产环境必须使用 HTTPS不要将Settings-*之外的敏感配置暴露为可远程修改项协议仅开放ConnectAddress与Stage1两项负载考量轮询默认每秒一次服务端需能承受每实例每秒一次 GET 任务完成后一次 POST若任务列表长期为空可返回{tasks: []}保持连接有效容量考量CaptureImage/CaptureImageNow的截图片 Base64 可能达数十 MB务必调大网关与 Web 框架的请求体上限否则上报会失败虽然 MAA 只记日志但截图功能将不可用幂等设计getTask返回的任务 ID 会被 MAA 去重服务端应保证同一任务稳定使用同一 ID才能避免任务重复或丢失状态确认StopTask不等停止完成即返回判断任务是否真正停止必须依赖HeartBeat返回的当前执行任务 ID。完整协议文档见 remote-control-schema.md英文版见 en-us 版本客户端实现可深入阅读 RemoteControlService.cs 与 RemoteControlUserControl.xaml。【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考