MaaAssistantArknights 任务流程协议详解resource/tasks 字段、虚任务表达式与 Schema 校验【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights本文详解 MaaAssistantArknightsMaa中resource/tasks任务配置的完整协议全部字段含义与默认值、四类识别算法的专用参数、任务列表表达式#*^的运算规则、模板任务与虚任务的继承机制以及如何结合 JSON Schema 在编辑器中做配置校验。读完后你将能够读懂乃至独立编写 Maa 的tasks.json任务流理解next/sub/exceededNext等控制流字段的展开逻辑并在执行中通过lazy_parse与set_task_base动态改写任务行为。一、任务配置的基本模型Maa 的自动任务由resource/tasks目录下的 JSON 文件定义每个任务是一个以任务名如TaskName为键的对象运行时按“识别algorithm→ 动作action→ 流转sub / next / exceededNext / onErrorNext”的顺序推进。整份任务图的骨架可以概括为{ TaskName: { // 任务名称带 时可能为特殊任务字段默认值会有不同 baseTask: xxx, // 以 xxx 任务为模板产生任务 algorithm: MatchTemplate, // 选填辨识算法类型不填写时默认为 MatchTemplate // - JustReturn: 不进行辨识直接执行 action // - MatchTemplate: 比对图片 // - OcrDetect: 文字辨识 // - FeatureMatch: 特征比对 action: ClickSelf, // 选填辨识到后的动作不填写时默认为 DoNothing // - ClickSelf: 点击辨识到的位置目标范围内随机一点 // - ClickRect: 点击 specificRect 指定区域不建议使用 // - DoNothing: 什么都不做 // - Stop: 停止目前任务 // - Swipe: 滑动对应 specificRect 与 rectMove 字段 // - Input: 输入文字要求 algorithm 为 JustReturn对应 inputText sub: [SubTaskName1, SubTaskName2], // 选填子任务不推荐使用。会在执行完目前任务后依序执行每一个子任务 // 可以套娃子任务再套子任务但要注意不要写出无穷循环 subErrorIgnored: true, // 选填是否忽略子任务的错误不填写默认 false // false 时子任务出错则不继续执行后续任务true 时子任务出错没有影响 next: [OtherTaskName1, OtherTaskName2], // 选填执行完目前任务和 sub 任务后下一个要执行的任务 // 会从前往后依序辨识执行第一个比对成功的 // 不填写默认执行完目前任务直接停止 // 对相同任务第一次辨识后第二次就不再辨识 // next: [ A, B, A, A ] - next: [ A, B ] // 不允许 JustReturn 型任务位于非最后一项 maxTimes: 10, // 选填该任务最大执行次数不填写时默认为无穷大 // 达到最大次数后若存在 exceededNext 字段则执行 exceededNext否则直接任务停止 exceededNext: [OtherTaskName1, OtherTaskName2], // 选填达到最大执行次数后要执行的任务 // 不填写时达到上限则停止填写后就执行这里的而不是 next 里的 onErrorNext: [OtherTaskName1, OtherTaskName2], // 选填执行出错时后续要执行的任务 preDelay: 1000, // 选填辨识到后延迟多久才执行 action单位毫秒默认 0 postDelay: 1000, // 选填action 执行完后延迟多久才去辨识 next单位毫秒默认 0 roi: [0, 0, 1280, 720], // 选填辨识范围格式 [ x, y, width, height ] // 以 1280 * 720 为基准自动缩放不填写时默认 [ 0, 0, 1280, 720 ] // 尽量填写减小辨识范围可以减少效能消耗加快辨识速度 cache: false, // 选填是否使用快取默认 false // 开启后第一次辨识到目标时以后永远只在第一次辨识到的位置进行辨识可大幅节省效能 // 仅适用于待辨识目标位置完全不会变的任务 rectMove: [0, 0, 0, 0], // 选填辨识后的目标移动不建议使用。以 1280 * 720 为基准自动缩放 // 例如辨识到 A但实际要点 A 下方 10 像素 5*2 区域内的某位置 // 可填 [ 0, 10, 5, 2 ]可以的话尽量直接辨识要点击的位置 // 当 action 为 Swipe 时有效且必填表示滑动终点 reduceOtherTimes: [OtherTaskName1, OtherTaskName2], // 选填执行后减少其他任务的执行计数 // 例如执行了使用理智药说明上一次点蓝色开始按钮没生效所以蓝色开始要 -1 specificRect: [100, 100, 50, 50], // action 为 ClickRect 时有效且必填指定点击位置范围内随机一点 // action 为 Swipe 时有效且必填表示滑动起点。以 1280 * 720 为基准自动缩放 specialParams: [int, ...], // 某些特殊辨识器需要的参数 // action 为 Swipe 时选填[0] 为 duration[1] 为额外滑动方向0 不启用1/2/3/4 为上/下/左/右 // [2]、[3] 为滑动轨迹缓入、缓出斜率需乘 10 输入默认均为 10 // 如需正常进入并缓出建议 [2]、[3] 分别填 37, 1 highResolutionSwipeFix: false, // 选填是否启用高解析度滑动修复默认 false // 现阶段应只有关卡导航未使用 unity 滑动方式时需要开启 } }注意JSON 文件本身不支持注释上述行内注释仅供理解参考实际编写tasks.json时请勿保留。从源码看任务的加载与展开上述配置最终由 TaskData 单例解析。从源码结构看TaskData内部维护了三层映射见 TaskData.hm_json_all_tasks_info原始的 JSON 任务定义m_raw_all_tasks_info未展开虚任务的任务信息m_all_tasks_info已展开虚任务、可直接执行的任务信息。对外提供get()取已展开任务、load()/lazy_parse()加载配置、set_task_base()修改baseTask等接口并以inline static auto Task TaskData::get_instance();暴露为全局Task句柄——这正是后文“执行中更改任务”一节中示例代码里Task.get(...)的来源。二、四类识别算法的专用字段任务中algorithm之外的字段按算法分属不同“衍生类别参数”。这与 docs/maa_tasks_schema.json 中的oneOf结构JustReturnTask/MatchTemplateTask/OcrDetectTask/FeatureMatchTask四种定义均allOf引用公共的BaseTask一一对应。MatchTemplate模板比对以下字段仅当algorithm为MatchTemplate缺省值时有效template: xxx.png, // 要比对的文件名可为字串或字串列表默认 任务名称.png // 範本圖可放在 template 及其子資料夾下載入時遞迴搜尋 templThreshold: 0.8, // 比對得分門檻超過才認為辨識到可為數字或數字列表預設 0.8 maskRange: [1, 255], // 灰階遮罩範圍如將圖片不需辨識部分塗黑灰階 0並設 [1, 255] 即可忽略塗黑處 method: Ccoeff, // 範本比對演算法可為列表預設 Ccoeff // - Ccoeff: 對顏色不敏感對應 cv::TM_CCOEFF_NORMED // - RGBCount: 依 colorScales 二值化後以 F1-score 計算 RGB 空間相似度再與 Ccoeff 結果內積 // - HSVCount: 類似 RGBCount顏色空間換為 HSV nmsDistance: 0, // 多結果去重NMS半徑單位像素兩個命中位置橫縱座標差都小於該值時只留最高分 // 不填或 0 時按範本短邊的一半取值method為HSVCount或RGBCount时还需注意colorScales: [ // 数色遮罩范围此两种 method 下必填 [ [23, 150, 40], // 结构 [[lower1, upper1], [lower2, upper2], ...] [25, 230, 150] ] // 内层为 int 时是灰階为 arrayint,3 时是三通道颜色 ... // 最外层代表不同颜色范围待辨识区域为它们对应遮罩的联集 ], colorWithClose: true, // 数色时是否先做闭运算处理遮罩默认 true // 闭运算可填补小黑点提高效果但图中包含文字时建议 false pureColor: false, // 为 true 时忽略範本比對得分完全依赖颜色比對结果默认 false // 适用于颜色特征明显但模板比对效果不佳的场景建议相应提高 templThresholdOcrDetect文字辨识以下字段仅当algorithm为OcrDetect时有效text: [ 接管作戰, 代理指揮 ], // 必填项要辨识的文字任一匹配成功即认为辨识到 ocrReplace: [ // 选填针对常见辨识错误进行替换支援正規表示式 [ 千員, 幹員 ], [ .擊幹員, 狙擊幹員 ] ], fullMatch: false, // 是否全字比對不能多字預設 false // false 时子串即可text 为 开始实际辨识到 开始行动 也算成功 replaceFull: false, // ocrReplace 命中时是否替换整段文字預設 false withoutDet: false, // 是否不使用检测模型預設 false isAscii: false, // 要辨识的文字是否为 ASCII 字符預設 falsewithoutDet为true时额外可用useRaw: true, // 是否使用原圖比對預設 truefalse 時為灰階比對 binThreshold: [140, 255], // 二值化灰階門檻值預設 [140, 255] // 灰階值不在範圍內的像素視為背景最終保留 [lower, upper] 區間像素作為文字前景注docs/maa_tasks_schema.json 中OcrDetectTask的required为[algorithm, text]并在useRaw/binThreshold的描述中标注了生效条件可作为编辑器校验的依据。JustReturn Input纯文字输入algorithm为JustReturn且action为Input时inputText: A string text. // 必填项要输入的文字內容Schema 中该组合通过条件校验强制inputText必填BaseTask的allOf分支之一。FeatureMatch特征点比对以下字段仅当algorithm为FeatureMatch时有效template: xxx.png, // 要比對的圖片檔案名稱預設 任務名稱.png count: 4, // 比對特徵點的數量要求門檻值預設 4 ratio: 0.6, // KNN 比對演算法的距離比值 [0 - 1.0]越大越寬鬆預設 0.6 detector: SIFT, // 特徵點檢測器預設 SIFT // 可選SIFT / ORB / BRISK / KAZE / AKAZE / SURF // SIFT複雜度高具尺度、旋轉不變性效果最好 // ORB速度極快具旋轉不變性無尺度不變性 // BRISK速度快具尺度、旋轉不變性 // KAZE適用於 2D/3D 圖像具尺度、旋轉不變性 // AKAZE速度較快具尺度、旋轉不變性三、任务列表表达式任务列表类型字段sub、next、onErrorNext、exceededNext、reduceOtherTimes的值支持表达式计算符号含义实例型任务FightReturnTo#一元虚任务#self#二元虚任务StartUpThemes#next*重复多个任务(ClickCornerAfterPRTSClickCorner)*10任务列表合并在 next 系列字段中同名任务只保留最靠前者AB^任务列表差在前者但不在后者顺序不变(AABC)^(ABD)结果为C运算符优先级为#一元 #二元 *^。这一套词法在源码中由 TaskDataSymbol 实现其Type枚举At、Sharp、Mul、Add、Sub即^、LParen/RParen等与symbol_repr_to_type映射表完整对应上表中的各符号虚任务关键字则以SharpSub/SharpNext/SharpSelf/SharpBack/SharpNone等独立词元出现src/MaaCore/Config/TaskData/TaskDataSymbol.h#L44-L65说明表达式在解析阶段就被切分为带类型的符号流再由TaskData的compile_raw_tasklist/compile_tasklist两阶段编译为最终任务列表。四、特殊任务类型4.1 模板任务模板任务包括衍生任务与型任务其核心可理解为根据父任务修改字段的默认值。衍生任务baseTask存在字段baseTask的任务即衍生任务baseTask对应的任务称为其父任务。规则若是模板比对任务字段template的默认值仍为任务名称.png若字段algorithm与父任务不同则衍生类别参数不继承只继承TaskInfo定义的参数其余字段的默认值均为父任务对应字段。隐式型任务存在任务A且所有任务文件中均未直接定义的形如BA的任务即隐式型任务A称其父任务。规则任务列表类型字段sub、next、onErrorNext、exceededNext、reduceOtherTimes的默认值为父任务对应字段直接增加B前缀如遇任务名称开头为#则增加B前缀其余字段的默认值均为父任务对应字段包括template。显式型任务存在任务A且任务文件中直接定义了BA时即显式型任务。规则任务列表类型字段默认值为父任务对应字段增加B前缀遇#开头增加B前缀若是模板比对任务template默认值仍为任务名称.png若algorithm与父任务不同衍生类别参数不继承其余字段默认值为父任务对应字段。4.2 虚任务#型任务虚任务形如#{sharp_type}或B#{sharp_type}其中{sharp_type}可为none、self、back、next、sub、on_error_next、exceeded_next、reduce_other_times可分指令虚任务#none/#self/#back与字段虚任务#next等虚任务类型含义简单范例none空任务直接跳过A: {next: [#none, T1]}被视为A: {next: [T1]}A#none T1被视为T1self目前任务名称A: {next: [#self]}中的#self被视为AB: {next: [ABC#self]}中的ABC#self被视为Bback#前面的任务名称AB#back被视为AB#back直接出现则被跳过next、sub等#前任务名称对应字段以next为例A#next被视为Task.get(A)-next#next直接出现则被跳过三个值得记住的备注#none一般配合模板任务增加前缀的特性使用或用在字段baseTask中避免多文件继承不必要的字段XXX#self与#self含义相同当几个任务都有next: [ #back ]时T1T2T3代表依序执行T3、T2、T1层层回退到父任务。4.3 多文件任务若后载入的任务文件例如外服tasks.json下称文件二中定义了先载入文件例如国服tasks.json下称文件一中已存在的同名任务文件二的任务没有baseTask字段直接继承文件一中同名任务的字段文件二的任务有baseTask字段不继承文件一而是直接覆盖。特别地在没有模板任务时可用baseTask: #none避免继承不必要的字段。4.4 使用示例衍生任务baseTask。假设Return: { action: ClickSelf, next: [ Stop ] }, Return2: { baseTask: Return }则Return2实际展开为Return2: { algorithm: MatchTemplate, // 直接继承 template: Return2.png, // 任务名称.png action: ClickSelf, // 直接继承 next: [ Stop ] // 直接继承与模板任务相比这里没有前缀 }型任务。假设任务A含A: { template: A.png, next: [ N1, #back ] }若BA未被直接定义其实际参数为BA: { template: A.png, next: [ BN1, B#back ] }若BA有定义BA: {}则实际参数为BA: { template: BA.png, next: [ BN1, B#back ] }虚任务。给定{ A: { next: [N1, N2] }, C: { next: [BA#next] }, Loading: { next: [#self, #next, #back] }, B: { next: [Other, BLoading] } }可得到Task.get(C)-next { BN1, BN2 }; Task.get(BLoading)-next { BLoading, Other, B }; Task.get(Loading)-next { Loading }; Task.get_raw(BLoading)-next { B#self, B#next, B#back };对应源码中Task.get()返回已展开任务m_all_tasks_info而展开前的原始列表仍保留在m_raw_all_tasks_info中——这正是示例里get_raw与get结果不同的原因。4.5 注意事项表达式优先级陷阱若任务列表字段中定义了包含低优先级运算的任务实际结果可能不符预期与二元#的运算顺序特例{ A: { next: [N0] }, B: { next: [A#next] }, CA: { next: [N1] } }此时CB - next即CA#next为[ N1 ]而不是[ CN0 ]。与的运算顺序特例{ A: { next: [#back N0] }, BA: {} }此时Task.get(A)-next { N0 }; Task.get_raw(BA)-next { B#back N0 }; Task.get(BA)-next { B, N0 }; // 注意不是 [ B, BN0 ]事实上可反向利用该特性避免增加不必要的前缀只需定义{ A: { next: [#none N0] } }五、执行中更改任务Task.lazy_parse()可在执行中载入 JSON 任务配置文件规则与上文多文件任务一节相同Task.set_task_base()可修改任务的baseTask字段。两者的 C 声明见 TaskData.h 中的bool lazy_parse(const json::value json)与void set_task_base(const std::string task_name, std::string base_task_name)。示例按模式切换任务基类假设有任务配置文件{ A: { baseTask: A_default }, A_default: { next: [xxx] }, A_mode1: { next: [yyy] }, A_mode2: { next: [zzz] } }以下代码可根据mode的值改变任务A同时会改变其他依赖A的任务例如BAswitch (mode) { case 1: Task.set_task_base(A, A_mode1); // 基本上相当于用 A_mode1 的内容直接替换 A下同 break; case 2: Task.set_task_base(A, A_mode2); break; default: Task.set_task_base(A, A_default); break; }该机制在仓库中有大量真实用例例如src/MaaCore/Task/Roguelike/RoguelikeConfig.cpp中通过Task.set_task_base(m_theme RoguelikeStages, m_theme RoguelikeStages_default)切换主题默认阶段src/MaaCore/Task/Roguelike/BlackFlow/BlackFlowRoutingTaskPlugin.cpp中则按路线状态在多个BlackFlowRoguelike...基类之间来回切换实现“同一入口任务名、运行时换行为”的效果。六、Schema 校验本仓库为tasks.json配置了 JSON Schema 校验Schema 文件为 docs/maa_tasks_schema.json。其要点顶层patternProperties以^(?!\$)匹配所有任务键每个任务对象通过oneOf匹配四种算法任务定义之一BaseTask中用if/then条件校验实现了字段联动约束action为ClickRect时specificRect必填action为Swipe时specificRect与rectMove均必填algorithm为JustReturn且action为Input时inputText必填MatchTemplateTask中templThreshold支持数组且注明“多模板时阈值数量需与模板数量一致”OcrDetectTask将algorithm与text列为必填。Visual Studio在MaaCore.vcxproj中已对其完成设置内建功能开箱即用。提示效果较为晦涩且有部分信息缺失。Visual Studio Code在.vscode/settings.json中已对其完成设置使用 Visual Studio Code 打开该项目文件夹即可使用提示效果较好。推荐配合 Maa Pipeline Support 扩展提供模板预览、next跳转、任务引用查询、任务表达式展开计算等功能实现高效编辑扩展教程见 docs/zh-tw/develop/vsc-ext-tutorial.md。七、编写任务时的实践建议结合本文各节日常编写tasks.json时可遵循控制流优先用next表达sub不推荐仅用于必须串行且与主流程解耦的场合next支持“取第一个识别成功者”的分支语义缩小roi所有坐标字段以 1280×720 为基准自动缩放填写更小的roi能减少性能消耗并加快识别cache只给固定位置目标用目标位置会变的任务保持默认false善用型任务与虚任务替代重复配置但注意第四节列出的优先级特例多文件国服/外服维护时外服覆盖用baseTask显式声明无父类时用baseTask: #none切断继承运行时动态行为用set_task_base/lazy_parse实现避免为每个分支复制整份任务图。【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考