MaaAssistantArknights 战斗流程协议Copilot JSON完全指南字段详解、实例与源码级解析实现【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights本文基于官方协议文档 copilot-schema.md并深入 MaaCore 中的解析与执行源码完整讲解resource/copilot/*.json战斗流程协议文件的使用方法。读完后你将能够独立编写一份可被 MAA 正确解析执行的 Copilot 作业 JSON理解每个字段的默认值、取值范围与解析规则并掌握条件等待、超时控制、子弹时间等机制在 BattleProcessTask 中的底层实现。一、什么是战斗流程协议文件战斗流程协议Copilot文件是驱动 MAA 自动完成一场战斗的“作业脚本”你只需要在resource/copilot/目录下放一个.json文件描述关卡名、所需干员或干员组、以及按时间轴排列的操作序列部署、开技能、撤退、切倍速等MAA 便会自动完成编队、进入战斗并逐步执行这些操作。官方协议文档中特别强调JSON 文件本身不支持注释原文档中的注释仅用于演示直接复制使用会导致解析失败。从源码结构看一个 Copilot 文件最终会被解析为battle::copilot::CombatData结构它由三部分组成定义见 AsstBattleDef.hstruct CombatData // 作业 JSON 数据 { BasicInfo info; // stage_name、doc 描述等基础信息 OperUsageGroups groups; // 干员/干员组及其用法 std::vectorAction actions; // 战斗时间轴动作序列 };解析入口是单例 CopilotConfigparse()依次调用parse_basic_info()、parse_groups()、parse_actions()任何一处opers解析失败都会使整个文件判定为无效见 CopilotConfig.cpp#L18-L34。二、顶层字段一览stage_name必选关卡名填写关卡中文名、code、stageId、levelId 等均可只要能保证唯一。解析时它是唯一用json.at()缺失即报错读取的顶层字段见 CopilotConfig.cpp#L42。战斗执行时 MAA 会用它在 Tile 数据中查找地图格子信息找不到会回调UnsupportedLevel并终止见 BattleProcessTask.cpp#L72-L88。opers指定干员干员列表数组元素字段如下字段必选默认值说明name是-干员名role否无干员职业英文职业名大小写不限用于区分同名干员如不同形态的阿米娅skill否0技能序号取值[0, 3]skill_usage否0技能用法取值 0~3见下文skill_times否1技能使用次数skill_usage为 2 时生效默认 1 是为兼容早期作业requirements否空练度要求自动编队时校验skill_usage的四个取值与源码枚举SkillUsage一一对应见 AsstBattleDef.h#L117-L1240— 不自动使用依赖actions字段显式开技能1— 好了就用有多少次用多少次例如棘刺 3 技能、桃金娘 1 技能2— 使用 X 次次数由skill_times设置例如山 2 技能用 1 次、重岳 3 技能用 5 次3— 自动判断使用时机文档原文注画饼.jpg。全自动技能填 0。requirements练度要求子字段字段默认值说明elite-1精英化等级-1 不作要求level-1干员等级-1 不作要求skill_level-1技能等级-1 不作要求module-1模组编号-1 无要求0 表示不使用模组1~4 对应不同编号模组module_level-模组等级暂不支持potential-潜能要求暂不支持源码在 parse_oper_usage 中对requirements做了几项静默修正与合法性校验编写作业时需要注意技能序号与稀有度匹配若指定skill超出干员稀有度上限如五星干员指定 3 技能、三星以下指定 1 技能源码会记日志并把skill强制改为 0而不是报错阿米娅作为特例允许 3 技能。精英化要求下限推断skill_level 7即专精会推断出至少精二skill_level 4至少精一指定了模组module 0同样推断至少精二。若你显式填写的elite低于推断值该干员解析直接失败、整个文件无效。找不到干员时跳过检查干员名在干员数据中不存在例如召唤物、无人机等时requirements直接按缺省值 0 读取。groups干员组当一个位置可以放多个备选干员时使用群组。字段name群组名必选自己随便取名字与actions中部署动作的name对应即可opers备选干员数组无序会优先选练度高的元素用法同上述opers字段。注意若是指定时刻使用的技能不同干员的技能 CD 可能不同请留意。源码 parse_groups 中还有两个值得了解的规则只写opers不写groups时每个干员名会被自动当作组名因此actions里直接填干员名即可命中群组级最低要求取组内最低初始elite_min 2、level_min 90遇到精英要求更低的干员时等级下限随精英阶段调整为 80精一或 70初始再取最小值。也就是说组内任何一个低练度备选都会拉低整组的最低门槛。三、actions战斗时间轴必选actions是战斗中的操作序列有序执行完前一个才会去执行下一个。每个动作的完整字段如下完整注释版示例见官方协议文档 copilot-schema.mdtype操作类型可选默认Deploy协议文档列出的 10 种类型及中文别名中英文皆可效果相同目前作业站发布只支持英文英文中文行为Deploy部署部署干员费用不够时一直等待到费用够除非 timeoutSkill技能开技能CD 没转好时一直等待除非 timeoutRetreat撤退撤退干员SpeedUp二倍速可切换的开关用一次变二倍速再用一次变回一倍速BulletTime子弹时间点击指定干员进入 1/5 速度进行任意 action 后恢复正常速度SkillUsage技能用法运行时修改某干员的技能用法必选skill_usageOutput打印界面不显示该步骤仅用于输出doc内容可做字幕SkillDaemon摆完挂机仅自动使用“好了就用”的技能其他什么都不做直到战斗结束MoveCamera移动镜头用于“引航者试炼”模式还需填写distance字段ResetStopwatch重置全局计时器重置全局计时器配合elapsed_time条件使用源码的 ActionTypeMapping 映射表 还额外支持两个集成战略SSS专用类型协议文档正文未列出但同样能被解析DrawCard别名“抽卡 / 抽牌 / 调配 / 调配干员”与CheckIfStartOver别名“检查重开”可配合tool_men字段声明所需工具人职业数量。未知的type字符串会被记日志并跳过该步骤见 CopilotConfig.cpp#L277-L283。各类型的关键使用约束部署name或location二选一direction必填见下文源码缺省为Right技能推荐正常干员用name开技能仅对场地上自动的装置等不填name、改用location开技能撤退推荐用name撤退仅多个同名召唤物时用location定位撤退子弹时间name或location必填一项即点哪个干员进入子弹时间战场上的干员或待部署区的干员均可会自动判断见 enter_bullet_time若下一个动作是“技能 / 撤退”需填与下一个动作相同的name或location若下一个动作是“部署”随便填谁但最好不要填待部署的那个人头像被点了会影响识别摆完挂机源码实现为直接wait_until_end()期间“好了就用”的技能会被策略层自动开启见 BattleProcessTask.cpp#L348-L350移动镜头distance必选[x 移动格子数, y 移动格子数]可为小数、可为负x 为正镜头右移y 为正镜头上移。例distance: [-1, 1]且location: [5, 6]实际会部署在[6, 7]。name / role / location / directionname干员名或群组名。type为部署时必选为技能 / 撤退时可选role干员职业可选英文职业名大小写不限用于区分同名干员。源码用 parse_role_type 将其映射到内部Role枚举guard/warrior均为近卫支持vanguard/pioneer等旧名location格子坐标[x, y]。部署时必选技能、撤退时按上述规则可选。坐标信息可在地图网站如map.ark-nights.com/areas查看将“坐标展示”选为“MAA”即为 MAA 使用的坐标direction部署干员的朝向部署时必选。Left | Right | Up | Down | None或中文左 | 右 | 上 | 下 | 无。从源码看该字段缺省时解析为Right无法识别的字符串也会回退为Right见 string_to_direction因此建议始终显式填写。技能控制字段skill_usage修改技能用法type为“技能用法”时必选。典型场景刚下桃金娘需要她帮忙打几个怪、不能自动开技能中后期平稳了再需要自动开技能则可以在对应时刻的SkillUsage动作里设为 1skill_times技能使用次数可选默认 1源码中SkillUsage动作要求name与location二选一两者都填会记错误日志并跳过该步骤只填location且该格子尚未部署时会注册一个drone_x_y的虚拟召唤物名再设置用法见 BattleProcessTask.cpp#L293-L332。延时与超时pre_delay前置延时可选默认 0单位毫秒。当前动作的所有条件参数全部满足后开始计时计时结束后执行动作部署动作在延时结束后还会刷新一次待部署区信息画面可能已变化post_delay后置延时可选默认 0单位毫秒。当前动作执行完成后开始计时计时结束后进入下一个动作。源码还兼容历史遗留字段rear_delay见 CopilotConfig.cpp#L299-L301timeout超时时间type为“技能”时可选默认 -1不限制单位毫秒。当完成条件和pre_delay后开始计时等待超时则放弃当前动作、转而执行下一个动作值为 0 时只检查一次skip_if_not_ready已废弃使用timeout: 0代替。源码中检测到该字段会打印DEPRECATED警告若同时写了timeout该步骤会被直接忽略见 CopilotConfig.cpp#L319-L333。条件字段等待条件以下五个条件目前为**且**关系全部满足才执行动作字段默认说明kills0击杀数条件没达到就一直等待costs0费用条件没达到就一直等待。费用受潜能等影响可能并不完全正确仅适合对时间轴要求不严格的战斗且仅在费用是两位数时识别较准三位数费用可能识别错不推荐使用cost_changes0费用变化量条件。注意从开始执行本 action 起计算前一个 action 结束时的费用作为基准支持负数例如“孑”等吸费干员使费用变少两位费用识别较准cooling-1CD 中干员数量条件默认 -1 不识别elapsed_time0毫秒为单位的全局计时条件。从上一次type: ResetStopwatch的 action 开始计算使用前必须先执行过ResetStopwatch否则源码只会打警告日志而不等待见 BattleProcessTask.cpp#L492-L509文档中的TODO注释表明条件间“或”关系condition_type: 0 且 / 1 或尚未实现。条件等待的实现集中在 wait_condition其检查顺序为cost_changes→kills→costs→cooling→elapsed_time最后若动作是部署还要额外等待该干员费用足够或 CD 转好扫描待部署区直到目标干员available。等待期间每帧都会执行策略动作do_strategic_action处理“好了就用”类技能的自动开启并且受全局截屏间隔配置copilot_fight_screencap_interval做帧率限制防止 CPU 占用过高见 BattleProcessTask.cpp#L227-L241。描述字段doc描述可选。会显示在界面上没有实际作用doc_color描述文字颜色可选默认灰色。顶层其余字段minimum_required最低要求 MAA 版本号必选。格式如v6.7.0、v6.8.0-beta.1。仓库内保全派驻录像识别功能自动生成的作业文件也遵循这一约定生成时写入minimum_required: v4.0.0见 CombatRecordRecognitionTask.cpp#L217-L221doc描述对象可选含title/title_color/details/details_color四个字段。建议在details里写上作业作者名、参考的视频攻略链接等difficulty作业对应难度可选默认 0。0缺省未设置1支持普通难度2支持突袭难度3支持普通、突袭难度。四、完整字段示例官方协议文档原样继承以下 JSON 与官方协议文档 copilot-schema.md 的“完整字段一览”一致注释仅用于演示请勿直接复制使用注释中的“作业站”指发布社区作业的平台{ stage_name: 暴君, // 关卡名必选。关卡中文名、code、stageId、levelId等只要能保证唯一均可。 opers: [ { name: 重岳, // 干员名 role: guard, // 干员职业。可选用于区分同名干员填英文职业名大小写不限 skill: 3, // 技能序号。可选默认为 0取值范围 [0, 3] skill_usage: 2, // 技能用法。可选默认为 0 // 0 - 不自动使用依赖 actions 字段 // 1 - 好了就用有多少次用多少次例如干员 棘刺 3 技能、桃金娘 1 技能等 // 2 - 使用 X 次例如干员 山 2 技能用 1 次、重岳 3 技能用 5 次通过 skill_times 字段设置 // 3 - 自动判断使用时机画饼.jpg // 如果是全自动的技能填 0 skill_times: 5, // 技能使用次数。可选默认为 1 requirements: { // 练度要求自动编队时校验。可选默认为空 elite: 2, // 精英化等级。可选默认为 -1即不作要求 level: 90, // 干员等级。可选默认为 -1即不作要求 skill_level: 10, // 技能等级。可选默认为 -1即不作要求 module: 1, // 模组编号。可选默认为 -1即不作要求0 表示不使用模组1-4 对应不同编号的模组 module_level: 3, // 模组等级。暂不支持 potential: 1 // 潜能要求。暂不支持 } } ], groups: [ { name: 任意正常群奶, // 群组名必选 // 自己随便取名字与下面 deploy 中的 name 对应起来就行 opers: [ // 干员任选其一无序会优先选练度高的用法同上述 opers 字段 { name: 夜莺, skill: 3, skill_usage: 2 // 若是指定时刻不同的干员技能 cd 可能不同请留意 }, { name: 白面鸮, skill: 2, skill_usage: 2 } ] } ], actions: [ { type: 部署, // 操作类型可选默认为 Deploy // Deploy | Skill | Retreat | SpeedUp | BulletTime | SkillUsage | Output | SkillDaemon | MoveCamera | ResetStopwatch // 部署 | 技能 | 撤退 | 二倍速 | 子弹时间 | 技能用法 | 打印 | 摆完挂机 | 移动镜头 | 重置全局计时器 // 中英文皆可效果相同但目前作业站发布只支持英文 // 若为 部署当费用不够时会一直等待到费用够除非 timeout // 若为 技能当技能 cd 没转好时一直等待到技能 cd 好除非 timeout // 二倍速 是可切换的即使用一次变成二倍速再次使用又变回一倍速 // 子弹时间 即点击任意干员后的 1/5 速度再进行任意 action 会恢复正常速度 // name 或 location 必填一项即点哪个干员进入子弹时间战场上的干员或待部署区的干员均可会自动判断 // 若下一个动作是 技能 / 撤退需要填与下一个动作相同的 name 或 location // 若下一个动作是 部署随便填谁但最好不要填待部署的那个人头像被点了会影响识别 // 打印 界面不显示这条步骤仅用于输出 doc 里的内容用来做字幕之类的 // 摆完挂机 仅使用 好了就用 的技能其他什么都不做直到战斗结束 // 移动镜头 用于 “引航者试炼” 模式还需要填写 distance 字段 // 重置全局计时器 重置全局计时器请参考 “elapsed_time” 条件 // 目前下面五个条件是且的关系即 kills: 0, // 击杀数条件如果没达到就一直等待。可选默认为 0直接执行 costs: 50, // 费用条件如果没达到就一直等待。可选默认为 0直接执行 // 费用受潜能等影响可能并不完全正确仅适合对时间轴要求不严格的战斗。 // 否则请使用下面的 cost_changes // 另外仅在费用是两位数的时候识别的比较准三位数的费用可能会识别错不推荐使用 cost_changes: 5, // 费用变化量条件如果没达到就一直等待。可选默认为 0直接执行 // 注意是从开始执行本 action 开始计算的即前一个 action 结束时的费用作为基准 // 支持负数即费用变少了例如“孑”等吸费干员使得费用变少了 // 另外仅在费用是两位数的时候识别的比较准三位数的费用可能会识别错不推荐使用 cooling: 2, // CD 中干员数量条件如果没达到就一直等待。可选默认为 -1不识别 elapsed_time: 1000, // 以毫秒为单位全局计时条件如果没达到就一直等待。可选默认为 0直接执行 // 注意是从上一次执行 type:ResetStopwatch 的 action 开始计算的 // 使用前必须执行过 type:ResetStopwatch 的 action 重置计时器不然会卡住 name: 棘刺, // 干员名 或 群组名type 为 部署 时必选为 技能 | 撤退 时可选 role: guard, // 干员职业。可选用于区分同名干员填英文职业名大小写不限 location: [ 5, 5 ], // 部署干员的位置。 // type 为 部署 时必选。 // type 为 技能 | 撤退 时可选 // 技能仅推荐场地上自动的装置等不填写 name并使用 location 开启技能。正常部署的干员推荐使用 name 开启技能 // 撤退仅推荐有多个同名召唤物时不填写 name并使用 location 进行撤退。正常部署的干员推荐 name 进行撤退 direction: 左, // 部署干员的干员朝向。type 为 部署 时必选 // Left | Right | Up | Down | None // 左 | 右 | 上 | 下 | 无 // 中英文皆可效果相同但目前作业站发布只支持英文 // skip_if_not_ready: false已废弃使用 timeout: 0 代替 skill_usage: 1, // 修改技能用法。当 type 为 技能用法 时必选 // 举例刚下桃金娘需要她帮忙打几个怪不能自动开技能中后期平稳了需要她自动开技能 // 则可以在对应时刻设置为 1 skill_times: 5, // 技能使用次数。可选默认为 1 pre_delay: 0, // 前置延时。可选默认为 0单位毫秒 // 当前 action 的所有条件参数全部满足后开始计时计时结束后执行 type 对应动作 post_delay: 0, // 后置延时。可选默认为 0单位毫秒 // 当前 action 的 type 对应动作执行完成后开始计时计时结束后开始下一个 action timeout: 999999999, // 超时时间。当 type 为 技能 时可选。默认 -1即不限制单位毫秒 // 当完成条件和 pre_delay 后开始计时等待超时则放弃当前动作转而执行下一个动作值为 0 时只检查一次 distance: [ 4.5, 0 ], // type 为 移动镜头 时必选 // [ x 移动格子数y 移动格子数 ]可为小数可为负 // x 值为正时代表镜头右移y 值为正时代表镜头上移 // 例distance: [-1, 1]location: [5, 6]实际会部署在 [6, 7] doc: 下棘刺了, // 描述可选。会显示在界面上没有实际作用 doc_color: orange // 描述文字的颜色可选默认灰色。会显示在界面上没有实际作用。 }, // 举例 1部署一个群组里的干员 { name: 任意正常群奶, location: [ 5, 6 ], direction: 右 }, // 举例 2带自定义字幕 { name: 史尔特尔, location: [ 4, 5 ], direction: 左, doc: 你史尔特尔奶奶来啦, doc_color: red }, // 举例 3切二倍速 { type: 二倍速 } ], minimum_required: v6.7.0, // 最低要求 maa 版本号必选例如 v6.7.0, v6.8.0-beta.1 doc: { // 描述可选。 title: 低练度高成功率作业, title_color: dark, details: 对练度要求很低balabala……, // 建议在这里写上你的名字作者名、参考的视频攻略链接等 details_color: dark }, difficulty: 0 // 作业对应难度可选默认值为0。 // 0: 缺省未设置 // 1: 支持普通难度 // 2: 支持突袭难度 // 3: 支持普通、突袭难度 }五、可直接运行的最小完整示例下面是一份去掉演示注释、可被 CopilotConfig::parse 直接解析的“部署—群奶组选择—开技能—挂机”作业骨架供编写自己的作业时参考{ stage_name: LV-7, opers: [ { name: 史尔特尔, skill: 3, skill_usage: 2, skill_times: 2 }, { name: 棘刺, skill: 3, skill_usage: 1 } ], groups: [ { name: 群奶, opers: [ { name: 夜莺, skill: 3 }, { name: 白面鸮, skill: 2 } ] } ], actions: [ { type: SpeedUp }, { name: 棘刺, location: [5, 5], direction: Right, doc: 下棘刺了 }, { name: 群奶, location: [5, 6], direction: Right }, { name: 史尔特尔, location: [4, 5], direction: Left }, { type: Skill, name: 史尔特尔, timeout: 10000 }, { type: SkillDaemon } ], minimum_required: v6.7.0, doc: { title: 示例作业, details: 示例MAA Copilot 协议最小可运行骨架 } }六、执行管线从 JSON 到战斗动作的源码链路理解执行链路有助于排错。任务入口是 CopilotTask参数与加载set_params 支持两种模式——单文件filename对应上面这类作业或多文件copilot_list多任务串联由MultiCopilotTaskPlugin驱动同时解析use_sanity_potion理智药、formation/formation_index自动编队、add_trust、ignore_requirements、support_unit_usage、user_additional用户自定义补员等接口参数。loop_times 1时会复制整条子任务链实现循环刷图。注意参数里的is_paradox字段自 v6.1.2 起已废弃会直接报错并提示使用独立的ParadoxCopilotTask。任务链构造器按序组装子任务多任务插件 →BattleStartPre可重试 3 次→ 理智药 / 快捷编队 → BattleFormationTask自动编队→BattleStartAll→ 跳过“干员将被禁用”确认框 → BattleProcessTask战斗主流程。战斗主流程BattleProcessTask::_run 依次完成calc_tiles_info计算格子信息、update_deployment(true)识别待部署区、to_group()把组名映射为实际编入的干员然后逐个do_action执行动作序列需要时再wait_until_end()。组名解析to_group()从编队任务拿到“干员 → 组名”映射后用 algorithm::get_char_allocation_for_each_group 求解每个组实际由哪位干员承担无解时回退为组内第一个干员动作里的name在执行前经 get_name_from_group 做“先按组名查、再按干员名查”的解析这正是“groups 会优先选练度高的”能落到具体干员上的原因。动作通知每个动作执行前都会通过 notify_action 回调SubTaskExtraInfo消息what: CopilotAction含action、target、doc、doc_color、elapsed_timeGUI 上的字幕即来源于此。七、常见问题与排错要点费用等待不精确costs/cost_changes依赖 OCR 识别费用两位数识别较准、三位数易错时间轴要求严格的战斗优先用cost_changes相对量比绝对量稳或击杀数kills条件elapsed_time“卡住”全局计时器必须由ResetStopwatch动作先行启用否则源码仅打印Timer not enabled警告动作会一直等待同名干员务必配合role消歧义例如不同形态的阿米娅可通过role如caster与warrior区分非法技能序号作业里给低稀有度干员指定了过高的skill时不会报错而是被静默改为 0默认技能需检查日志中的cannot use skill index提示技能用timeout: 0旧字段skip_if_not_ready: true等价于timeout: 0只检查一次新作业请直接使用timeout未知动作类型type写错时该步骤被跳过而不是失败时间轴会“静默缺失一步”排查时可对照日志中的Unknown action type输出。八、延伸阅读官方协议文档本文主体来源docs/zh-cn/protocol/copilot-schema.md协议总览与消息回调格式docs/zh-cn/protocol/README.md、docs/zh-cn/protocol/callback-schema.md解析实现src/MaaCore/Config/Miscellaneous/CopilotConfig.cpp数据结构定义src/MaaCore/Common/AsstBattleDef.h任务入口与战斗执行src/MaaCore/Task/Interface/CopilotTask.cpp、src/MaaCore/Task/Miscellaneous/BattleProcessTask.cpp集成战略SSS在 Copilot 协议上的扩展字段DrawCard、CheckIfStartOver、strategies等docs/zh-cn/protocol/sss-schema.md【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考