MaaAssistantArknights 外服适配实战指南截图裁剪、ROI 计算、模板/文字覆盖与日志排错【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights本文为 MaaAssistantArknights明日方舟小助手的外服适配教程讲解如何让小助手在国服以外的客户端如美服 YoStarEN、日服 YoStarJP 等上正常识别界面并执行日常任务从获取规范化截图、用 ImageCropper 裁剪 ROI到覆盖tasks.json中的模板图片、text文字与roi范围最后通过asst.log定位识别失败的具体任务。读完后你将具备独立完成一个新外服/新客户端适配的完整工作流能力包括“外服未定义字段自动回退官服、已定义字段覆盖官服”这一核心覆盖机制。一、准备工作与资源覆盖原理在开始适配之前请先确认以下条件源自 外服适配教学已安装并正确配置所需软件确保当前支持的功能皆可正常执行已阅读 任务流程协议对各字段的含义与用法有基本了解并理解、#类型任务的定义理解资源覆盖逻辑外服的task.json与模板图片中未提及或缺失的内容会自动以官服内容作为备选若外服的task.json中已定义相关字段则会覆盖并重写官服的设置具备基本英文能力需能阅读英文日志Log并透过日志分析缺失的图片或信息建议按任务链进行修改例如针对Award任务建议根据官服task.json的next顺序逐步替换“模板图片”“文字”或“修改 ROI”确保每一步修改都能正常执行。这有助于快速定位错误避免因一次改动过多而难以侦测。覆盖机制在源码中的依据上述覆盖逻辑并非“口头约定”在 任务流程协议 的“多檔案任務”一节中有明确定义如果后载入的任务文件例如外服tasks.json中定义了与先载入文件例如国服tasks.json同名的任务——若外服任务没有baseTask字段则继承官服同名任务的其余字段若外服任务带有baseTask字段则不继承官服同名任务的字段而是直接覆盖特别地在没有模板任务时可以用baseTask: #none来避免继承不必要的字段。从仓库实际资源结构看每个外服客户端都有独立的资源子目录。以仓库当前内容为例resource/global/下已包含YoStarEN、YoStarJP、YoStarKR、txwy等目录美服目录结构为resource/global/YoStarEN/resource/ ├── PaddleOCR/rec/ # 该客户端独立的 OCR 识别模型inference.onnx keys.txt ├── item_index.json ├── recruitment.json ├── tasks/ # 该客户端的任务链定义tasks.json 及子目录 ├── template/ # 该客户端的模板图片 └── version.json这意味着适配一个新外服时你只需在对应客户端的tasks/与template/目录中补齐差异部分其余内容任务链结构、未覆盖的字段、未覆盖的模板都会自动回退到官服资源这就是“未提及内容以官服为备选”的落地形态。修改前准备参考官服task.json准备好外服专用的模板图片与文字内容确保在修改过程中能随时获取这些素材。二、获取规范化的屏幕截图模板与 ROI 都依赖截图高质量的截图是适配成功的前提。文档给出四条硬性要求使用模拟器内建的截图工具进行截取并储存截图尺寸需大于1280*720长宽比为16:9截图中不应包含无关内容如系统工作列、状态列、通知中心等确保截图涵盖所有需要辨识的内容。为什么要以1280*720为基准因为 任务流程协议 规定roi、rectMove、specificRect等坐标字段均以1280*720为基准自动缩放不填写时roi默认为[0, 0, 1280, 720]。而仓库自带的裁剪工具 ImageCropper 在读取本地截图时会将其统一缩放到短边 720resize_to_target_short_side(image, 720)见 main.py对 ADB 设备实时截图也会通过set_screenshot_target_short_side(720)让控制器输出短边 720 的截图main.py。因此只要截图符合 16:9裁剪出的 ROI 数值就能直接写进task.json而不必再换算。三、ImageCropper裁剪 ROI 与输出 ColorMatch 参数为了裁剪图片并获取文字或图片的ROI建议使用仓库自带的 tools/ImageCropper 工具。ImageCropper是一个功能强大的工具支持对预先准备好的截图或通过 ADB 连接设备当前仓库版本还支持通过--pc参数抓取 PC 端窗口进行 ROI 区域截取、储存及取色操作。环境配置需要Python环境推荐版本为3.11最低需求为3.9以上。安装依赖Windows 用户推荐直接执行 install.bat或手动安装依赖清单见 requirements.txt核心为MaaFw~5.10与opencv_python~4.13python -m pip install -r requirements.txt使用步骤若有预先准备好的截图请存放到./src/路径下执行 start.bat 或python main.py [device serial]设备地址为选填。工具会自动搜索已连接的 ADB 设备请根据提示选择按 ENTER 跳过选择亦可直接使用python main.py [device serial]连接指定设备在窗口中左键选择目标区域滚轮缩放图片右键移动图片可使用快捷键操作S或ENTER储存目标区域F储存全屏幕标准化截图R不储存仅在控制台输出 ROI 范围C不储存输出 ROI 范围与 ColorMatch 所需字段Z、DELETE或BACKSPACE复原0~9缩放窗口Q或ESC退出任意键跳过或刷新目前截图裁剪后的图片会储存在./dst/路径下。示例输出内容src: Screenshot_xxx.png dst: Screenshot_xxx.png_426,272,177,201.png original roi: 476, 322, 77, 101, amplified roi: 426, 272, 177, 201其中Screenshot_xxx.png为放入src资料夹的完整截图档案名称Screenshot_xxx.png_426,272,177,201.png为截取后的图片original roi为鼠标选取的原始区域amplified roi为扩大后的区域你在task.json中的roi字段中应填入此数值。源码级说明original roi 与 amplified roi 的区别为什么要把选区“放大”后再填进roi看 main.py 中的amplify函数# ROI 放大方法 def amplify(rect: list[int]) - list[int]: x, y, w, h rect return [x - 50, y - 50, w 100, h 100]即选区四边各向外扩展 50 像素宽、高各 100。用上面的示例验证original roi: 476, 322, 77, 101→476-50426, 322-50272, 77100177, 101100201与amplified roi完全一致。这样做的目的是给模板比对/OCR 留出一圈“上下文”边距避免因游戏画面轻微位移导致目标刚好被裁出roi。ROI 数据本身由 roi.py 中的Roi类描述其rectangle属性输出[x, y, width, height]见 Roi.rectangle与task.json的roi字段格式[x, y, width, height]一致可直接复制。另外需要注意文档示例中的dst文件名格式为“源图名_amplified roi.png”而当前仓库版本的 main.py 生成的文件名为{源图名}_{original roi}__{amplified roi}.png两段坐标的含义与上述输出完全一致按实际输出生成的文件为准即可。C 键一键生成 ColorMatch 配置当外服某些元素难以用模板比对例如图标背景复杂时可以改用颜色匹配。按C/c时main.py 会调用 colormatcher.py 做 K-means 颜色聚类kmeansClusterColors默认聚 3 类并输出形如下面的 JSON{ recognition: ColorMatch, roi: [], method: 4, lower: [[...]], upper: [[...]], count: [42], connected: false }其中method: 4对应cv2.COLOR_BGR2RGB注释中说明常用值4 RGB40 HSV6 灰度lower/upper/count数组可对照 任务流程协议 中HSVCount/RGBCount方法的colorScales、count等字段填入task.jsonc小写输出connected: falseC大写输出connected: true对应“是否只统计相连区域”的语义。这一步让你在适配时不必手工调色取色直接从截图中算出可用的颜色阈值。四、替换模板图片MatchTemplate 任务在修改模板图片之前需要先开启对应客户端的模板图片资料夹以及官服的模板图片资料夹。例如仓库内已验证存在美服的模板图片资料夹位置为 resource/global/YoStarEN/resource/template官服的模板图片资料夹位置为 resource/template下分Award、Battle、Recruit等子目录。请参考task.json中提到的模板图片template字段缺省为“任务名称.png”文件放在template及其子目录下、载入时递归搜索对比官服和外服的模板图片找出外服中缺少的模板。通常情况下除了标志Logo等图片外包含文字的模板都需要透过屏幕截图来替换国服按钮上的中文与外服英文字形差异过大直接复用官服模板必然比对待对失败。如果图片尺寸明显大于官服对应的模板图片则需要同步修改roi的大小。将截取并重新命名完成的模板图片文件名需与任务名/template字段对应放入对应客户端的模板图片资料夹中即可。五、修改文字内容OcrDetect 任务在修改文字内容之前需要开启对应客户端的task.json与官服的task.json。例如美服的task.json位置为 resource/global/YoStarEN/resource/tasks/tasks.json官服的task.json位置为 resource/tasks/tasks.json。找到对应任务后将text字段修改为该客户端内显示的内容。请注意辨识内容可以是游戏中完整内容的部分字串——这与 任务流程协议 中fullMatch字段默认false的语义一致false时只要text是识别结果的子串即算命中例如text: [开始]在实际识别到“开始行动”时也算成功因此外服适配时可以只填关键词。修改原则通常情况下除非是纯 ASCII 字符辨识可配合isAscii: true否则包含文字的text都建议替换为外服显示内容若文字长度明显大于官服例如“任務”与“Mission”长度差距过大则需要调整外服该任务的roi大小否则文字会被roi边界裁断导致识别失败若对应客户端的task.json中没有该任务则需手动新增任务并填写text字段即可——依据“多檔案任務”的继承规则新增任务会继承官服同名任务的其余字段action、next、maxTimes等只补差异字段即可不必整段复制。六、修改 ROI 范围开启对应客户端的task.json例如美服路径resource/global/YoStarEN/resource/tasks/tasks.json找到对应需要修改roi范围的任务使用你准备好的外服截图根据amplified roi数值来调整roi的范围大小通常情况下roi不需要修改只有当辨识内容与官服的大小差距过大时才需要调整若外服客户端的task.json中该任务不存在则手动新增并填上roi字段。roi格式为[x, y, width, height]以1280*720为基准自动缩放尽量填写以减小辨识范围可节省效能、加快辨识速度见 任务流程协议。七、储存设定并重启软件DEBUG.txt 快速迭代技巧修改完成后重新储存并重新启动软件以载入档案并使修改生效。或者你也可以在软件目录下新建一个DEBUG.txt再开启软件如此一来每次点击「Link Start」时程式都会重新载入模板与档案无需反复重启。这一行为在源码中可以得到印证GUI 侧TaskQueueViewModel.cs 中会检查File.Exists(DEBUG) || File.Exists(DEBUG.txt)来决定 Link Start 时是否重新载入资源Bootstrapper.cs 则在检测到该文件时将日志级别提升到Verbose核心侧Logger.hpp 会在存在DEBUG.txt时输出Debug mode enabled (DEBUG.txt found)并启用更详尽的日志ScreenshotTaskPlugin.cpp 中need_save_debug_img std::filesystem::exists(DEBUG.txt)即调试模式下会额外保存每步的截图便于核对“程式当时看到了什么画面”。所以调试期建议在软件根目录保留一个DEBUG.txt可命名为DEBUG或DEBUG.txt配合日志与调试截图排错正式提交前再移除。八、解读 asst.log定位识别失败的环节有时候修改完task.json后发现程式仍无法正确执行此时可以透过查看日志来找出错误点进而修改对应任务。日志档案位于软件根目录的debug资料夹下档名为asst.log。如果你是自行编译 MAA则日志会在建置输出目录如build\bin\RelWithDebInfo的debug资料夹中具体取决于编译时选择的建置组态。以下是一段日志示例[2022-12-18 17:43:17.535][INF][Px7ec][Tx15c8] {taskchain:Award,details:{to_be_recognized:[AwardReturnTo,Award,ReceiveAward,DailyTask,WeeklyTask,AwardCloseAnno,AwardCloseAnnoTexas,AwardTodaysSupplies,AwardFromStageSN],cur_retry:10,retry_times:20},first:[AwardBegin],taskid:2,class:asst::ProcessTask,subtask:ProcessTask,pre_task:AwardBegin} [2022-12-18 17:43:18.398][INF][Px7ec][Tx15c8] Call C:\Program Files\BlueStacks_nxt\.\HD-Adb.exe -s 127.0.0.1:5555 exec-out screencap | gzip -1 ret 0 , cost 862 ms , stdout size: 2074904 , socket size: 0 [2022-12-18 17:43:18.541][TRC][Px7ec][Tx15c8] OcrPack::recognize | roi: [ 500, 50, 300, 150 ] [2022-12-18 17:43:18.541][TRC][Px7ec][Tx15c8] Ocr Pipeline with asst::WordOcr | enter [2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] Ocr Pipeline with asst::WordOcr | leave, 93 ms [2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] OcrPack::recognize | raw: [{ : [ 0, 0, 300, 150 ], score: 0.000000 }] [2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] OcrPack::recognize | proc: [] [2022-12-18 17:43:18.637][TRC][Px7ec][Tx15c8] asst::ProcessTask::_run | leave, 1101 ms [2022-12-18 17:43:18.638][TRC][Px7ec][Tx15c8] ready to sleep 500 [2022-12-18 17:43:19.144][TRC][Px7ec][Tx15c8] end of sleep 500 [2022-12-18 17:43:19.144][TRC][Px7ec][Tx15c8] asst::ProcessTask::_run | enter在示例日志中你可以看到字段含义taskchain代表目前执行中的任务链details任务的具体内容包含待辨识字段to_be_recognized、目前重试次数cur_retry以及总重试次数retry_timesfirst代表任务的起始taskid任务编号class与subtask分别代表任务类别与子任务pre_task代表前一个执行的任务此外日志还会记录指令的执行状况如Call行会显示实际执行的 ADB 命令、耗时与返回值和 OCR 辨识信息如OcrPack::recognize其中raw/proc为空数组即表示该roi内什么都没识别到与示例中score: 0.000000、proc: []对应。在示例日志中to_be_recognized、cur_retry:10,retry_times:20表示已重复辨识 10 次上限为 20 次一旦达到上限就会跳过该任务并回报错误。若先前的任务没问题基本可以确定是此处辨识出错。此时应检查日志提到的任务确认三件事是否有对应的模板图片档案模板文件名是否与任务名/template字段一致、是否放在了正确客户端的template目录下text文字是否正确是否写成了官服文案、是否超出roi可容纳的长度roi范围是否精准是否把目标完整框住。透过检查对应模板图片若发现外服模板资料夹中有该图片但尺寸明显大于官服图片导致官服的roi设定无法正常辨识此时就必须修改外服客户端的task.json中的roi使其与外服图片大小相符——这正是第六节流程在排错场景下的闭环。九、提交你的修改适配完成并验证可用后欢迎把你的外服资源修改回馈给社区。提交方式请参考 GitHub Pull Request 指南。提交前建议自查新增/替换的模板图片文件名与task.json中任务名或template字段一致所有roi数值来自amplified roi而非original roitext字段为外服实际显示内容或其可命中的子串移除了软件根目录的DEBUG.txt并在干净环境下完整跑通目标任务链。至此你已经掌握了 MaaAssistantArknights 外服适配的完整链路以官服资源为底、按“多檔案任務”规则做字段级覆盖、用 ImageCropper 产出可直接入 JSON 的模板与 ROI、用 DEBUG 模式与asst.log做最小步长排错。按这套流程任何新外服或新客户端的适配都可以分解为若干次“改一处 → 跑一次 → 看日志”的小循环而不是一次性的大改。【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考