企业官网建设流程全解析

MAA 外服客户端适配怎么做：替换模板图片、修改 tasks.json 文本与 ROI

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights

MAA Assistant（MaaAssistantArknights）默认资源面向国服客户端，如果你要在 YoStarEN（美服）等外服客户端上跑日常，直接复用国服资源会导致模板匹配不上、文字识别不到。本教程覆盖外服适配的完整路径：先截图并用 ImageCropper 拿到 ROI，再依次替换外服客户端的模板图片、修改tasks.json中的text文本、按需调整roi，最后重启软件（或用DEBUG.txt热重载）并通过日志验证修改是否生效。

修改前需要准备什么

开始之前，官方教程要求你确认以下条件（见 外服适配教程）：

1. 已安装并正确配置 MAA，所支持的功能能正常运行；
2. 已阅读 任务流程协议，理解各字段含义，以及@、#类型任务的用法；
3. 理解资源回退机制：外服的task.json和模板图片中未提及、缺少的内容，会使用国服的task.json和模板图片作为备选；外服文件中的内容会覆盖并改写国服对应任务的相应字段；
4. 能阅读英文日志，通过日志找出缺失的图片等信息；
5. 建议按任务链顺序逐步修改。以Award任务为例：按国服task.json中Award任务的next顺序，逐步替换模板图片 / 文本 / 修改roi，保证每一步修改后都能运行或迅速发现错误，避免一次改太多内容后不知道卡在哪一步。

另外，动手前先参考国服task.json，准备好与国服不同的外服模板图片和文本内容，并确保随时能获取这些素材。

获取截图与 ROI：使用 ImageCropper

模板替换和 ROI 调整都依赖一张干净的外服游戏截图。截图要求：

• 使用模拟器自带的截图工具截图并保存；
• 尺寸大于1280*720，长宽比16:9；
• 不包含任务栏、状态栏、通知栏等无关内容；
• 包含所有需要识别的内容。

裁剪截图、获取 ROI 用仓库内置的 ImageCropper 工具（MaaAssistantArknights/tools/ImageCropper），它支持对预先准备好的截图、ADB 连接的设备进行 ROI 区域的截取、保存、取色操作。

环境配置：需要python环境，推荐版本3.11，最低3.9以上。

安装依赖：Windows 用户推荐直接运行install.bat，或手动执行：

python -m pip install -r requirements.txt

使用步骤：

1. 把预先准备好的截图放到工具目录下的./src/路径；
2. 运行start.bat，或python main.py [device serial]（设备地址可选）：
   • 工具会自动搜索已连接的 ADB 设备，按提示选择设备（按 ENTER 跳过选择）；
   • 也可以直接用python main.py [device serial]连接指定设备；
3. 弹窗中左键选择目标区域，滚轮缩放图片，右键移动图片；
4. 使用快捷键操作：
   • S或ENTER：保存目标区域；
   • F：保存全屏标准化截图；
   • R：不保存，只输出 ROI 范围；
   • C：不保存，输出 ROI 范围和 ColorMatch 所需字段；
   • Z、DELETE或BACKSPACE：撤销；
   • 0~9：缩放窗口；
   • Q或ESC：退出；
   • 任意键：跳过 / 刷新当前截图。
5. 目标区域截图保存在./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

其中original roi是鼠标选取的区域，amplified roi是扩大后的区域。tasks.json中roi字段要填的是amplified roi这个值。roi的格式为[ x, y, width, height ]，以 1280*720 为基准自动缩放（见 任务流程协议）。

替换外服模板图片

打开对应客户端的模板图片文件夹和国服的模板图片文件夹做对比：

• 美服：MaaAssistantArknights\resource\global\YoStarEN\resource\template
• 国服：MaaAssistantArknights\resource\template

参考task.json中提到的模板图片，对比国服和外服，找出外服缺少的模板。通常来说，除了标志类图片，包含文字的模板都需要通过截图来替换——用前面裁剪出的外服截图作为新模板，重命名后放入对应客户端的模板图片文件夹。

判断标准：如果外服图片尺寸明显大于国服对应模板图片，说明识别范围不够，需要修改该任务的roi大小。

修改 tasks.json 的 text 文本

打开对应服务器的tasks.json和国服的tasks.json对照修改：

• 美服：MaaAssistantArknights\resource\global\YoStarEN\resource\tasks\tasks.json
• 国服：MaaAssistantArknights\resource\tasks\tasks.json

找到对应任务，把text字段改成该服务器内实际显示的内容。两点依据来自任务流程协议：text是要识别的文字内容，任一匹配即认为识别到；识别内容可以是游戏内完整内容的子串。

通常需要替换的情况：

• 除非是纯 ASCII 字符识别，否则包含文字的text都要替换；
• 如果文字长度明显大于国服（例如"任务"和"Mission"长度差距过大），对应识别区域装不下，需要修改外服该任务的roi大小。

如果对应外服的tasks.json中没有该任务，则直接添加任务，只需填写text字段即可。

修改 ROI 范围

ROI 调整的规则很简单，按以下步骤操作：

1. 打开对应服务器的tasks.json，如美服为MaaAssistantArknights\resource\global\YoStarEN\resource\tasks\tasks.json；
2. 找到需要修改roi范围的任务，用准备好的外服游戏界面截图，根据 ImageCropper 输出的amplified roi调整roi范围；
3. 通常情况下roi不需要修改，只有和国服的识别内容大小差距过大时才需要改；
4. 如果外服tasks.json中任务不存在，则添加任务并写上roi字段。

让修改生效并验证

修改完成后，两种方式让 MAA 加载新文件：

• 重新启动软件，重新加载文件使修改生效；
• 或在软件目录下新建一个DEBUG.txt后再打开软件——这样每次点击开始都会重新加载模板和文件，不需要重启。

验证是否成功：

1. 运行软件，确认能在外服客户端中正常使用；
2. 如不能正常运行，检查修改是否正确，或查看日志输出找到出错位置。

定位问题：解读 asst.log

改完tasks.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":["Award@ReturnTo","Award","ReceiveAward","DailyTask","WeeklyTask","Award@CloseAnno","Award@CloseAnnoTexas","Award@TodaysSupplies","Award@FromStageSN"],"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.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: []

各字段含义：

• taskchain：当前进行中的任务；
• details：任务内容，包括需要识别的字段（to_be_recognized）、当前重试次数（cur_retry）和总重试次数（retry_times）；
• first：任务的开始；
• taskid：任务编号；
• class/subtask：任务的类别和子任务；
• pre_task：前一个任务；
• 此外日志还会记录命令执行情况（如Call）和 OCR 信息（如OcrPack::recognize）。

上面示例中"cur_retry":10,"retry_times":20表示已重复识别 10 次，最大识别 20 次；达到最大次数后会跳过该任务并报错，继续执行下一个任务。如果前面的任务没有问题，基本可以确定是这里识别出了问题：回到日志中提到的任务，依次检查外服模板文件夹里是否有对应的模板文件、任务的text是否正确、任务识别的roi范围是否正确。

文档给出的一个实际例子：查日志发现美服模板文件夹里有对应图，但大小明显大于国服图片，导致国服的roi用在美服上识别不出来，于是修改美服tasks.json中对应任务的roi，使其与美服图片大小对应。

下一步

验证通过后，如果你的修改希望回馈社区，参考 GitHub Pull Request 指南 提交你的修改。

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights