MaaFgo 是基于 MAA 开发思路衍生出的 FGO 自动化工具v1.2 是它在脚本组织、配置独立性和运行稳定性上的一个迭代版本。对于关注 FGO 自动化工具的玩家来说v1.2 关心的不是“能不能跑”而是“长任务跑起来稳不稳定、配置改起来是否容易、出问题后日志能否说明原因”。这篇文章会先解释 MaaFgo v1.2 解决了什么问题再给出从环境准备、配置、运行到排查的完整链路最后补充二次开发和稳定性建议。适合三类读者一是想把 v1.2 用起来的使用者二是想理解图像识别自动化工具原理的开发者三是准备基于 MaaFgo 做二次开发的社区贡献者。由于 MaaFgo 本身属于社区开源项目版本细节可能随仓库更新变化。文章里涉及路径、参数、命令和日志都是常见的工程结构示意。落地到真实环境时要以你拉取到的源码、README 和 Release 说明为准。1. MaaFgo 是什么v1.2 版本更新了什么1.1 从 MAA 到 MaaFgo自动化脚本的工程化思路MAA 原本是面向《明日方舟》的自动化辅助工具社区里逐渐形成了一套通用的图像识别、模拟器控制、任务调度和状态记录机制。MaaFgo 是这套思路在 FGO 场景下的社区实现。它不直接修改游戏内存也不注入代码而是通过截图识别画面中的按钮和文本然后通过 ADB 向模拟器发送触摸事件。这种方案的好处是通用性较强。只要画面特征清晰脚本就可以根据识别坐标做出点击操作。缺点也很明显识别依赖模板图片和阈值模拟器分辨率、UI 缩放、活动界面变化都可能影响识别结果。v1.2 的很多改动本质上都是在降低这种不确定性带来的维护成本。在工程层面MaaFgo 可以拆成几层设备层负责连接模拟器识别层负责从截图里找目标区域任务层负责任务队列和跳转逻辑配置层负责把参数外置。v1.2 的核心变化就是在这些层次之间把边界划得更清楚。1.2 v1.2 版本的更新重点根据常见社区项目的发布习惯v1.2 版本通常会在以下几个方面有明显变化第一配置文件形式更规范。旧版本可能把任务参数和识别阈值混在一个脚本文件里v1.2 更倾向于把设备参数、任务流程、模板图片路径拆开方便使用者不修改代码就调整行为。第二任务流程支持更细粒度的控制。比如单个任务可以设置最大失败次数、失败后的等待时间、是否跳转到下一个任务。这样长任务挂机时不会因为一次误识别就卡死在某个界面。第三日志输出结构更清晰。每个关键步骤会带上时间、任务名、图片名称、匹配度、动作类型方便定位是哪一步出了问题。第四识别阈值和截图区域可以按任务单独覆盖。同一张模板图在活动界面和普通界面可能有不同表现v1.2 允许在单个任务节点内覆盖全局参数。还有一点值得注意v1.2 可能会调整依赖库的版本。升级前不要直接拉代码覆盖旧目录先看 requirements 文件是否有变化避免因为依赖不兼容导致运行时报错。1.3 要不要升级到 v1.2如果你的旧版本已经稳定运行并且你只是做最简单的日常点击升级动力可能不强。但只要你有下面这些需求建议升级一次运行多个任务希望失败后跳过而不是中断全部。需要频繁调整识别阈值但不想改代码。任务跑挂后需要从日志里快速定位问题。准备在多个模拟器上运行需要把设备配置独立出来。反过来如果你只是临时体验自动化流程主力环境又是旧版本那么先不要在生产模拟器上升级。建议复制一份项目目录跑通 v1.2 后再决定是否替换。2. 环境准备升级前先把依赖和目录理顺2.1 v1.2 对运行环境的基本要求MaaFgo 本质上运行在主机上通过 ADB 控制模拟器。所以核心环境包含三部分主机操作系统、Python 运行时、模拟器环境。常见主机环境是 Windows。因为 MAA 生态里的模拟器控制和 ADB 工具大多优先适配 Windows。Linux 和 macOS 也可以运行但可能要额外处理模拟器连接、截图权限和 ADB 路径问题。Python 版本建议使用 3.9 到 3.11。这是目前社区自动化项目里相对稳妥的范围。太老的版本可能不支持新的类型注解语法太新的版本可能遇到某些图像处理库尚未完全适配。模拟器方面推荐使用支持 ADB 连接的 Android 模拟器并开启“USB 调试”或对应模拟器的 ADB 调试选项。分辨率设置建议按项目文档推荐值来常见的是 1280x720 或 1920x1080。DPI 不要随意调太高否则模板匹配可能因为缩放比例不一致而失效。环境项推荐配置说明操作系统Windows 10/11兼容性最好Python3.9 - 3.11避免过新或过旧模拟器支持 ADB 的主流模拟器需开启调试模式ADBplatform-tools 最新版单独配置路径分辨率1280x720 或 1920x1080全局统一屏幕 DPI使用模拟器默认值不要随意放大缩小2.2 获取代码与安装依赖假设你已经将 MaaFgo 仓库克隆到本地。下面是一组常见的初始化命令仅用于说明步骤git clone https://github.com/your-org/maafgo.git cd maafgo python -m venv .venv .venv\Scripts\activate pip install -r requirements.txt如果你在 Linux/macOS最后一步虚拟环境激活命令不同source .venv/bin/activate pip install -r requirements.txt这里要注意venv 不是必须的但强烈建议使用。MaaFgo 依赖的 OpenCV、Pillow、onnxruntime 等库版本比较敏感直接装到系统 Python 里可能会和别的项目冲突。venv 可以把依赖隔离在项目目录中出问题后直接删除 .venv 重建即可。如果下载依赖很慢可以配置国内镜像源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后验证依赖是否可用的常用命令是python -c import cv2; print(cv2.__version__) python -c import PIL; print(PIL.__version__)如果输出版本信息说明基础图像库已经就绪。2.3 项目目录结构与配置文件v1.2 风格的目录结构通常长这样maafgo/ ├── config/ │ ├── device.json │ ├── tasks.json │ └── templates/ ├── assets/ │ ├── start_button.png │ └── confirm_button.png ├── logs/ ├── src/ │ ├── core/ │ ├── recognizer/ │ ├── executor/ │ └── main.py ├── requirements.txt └── README.mdconfig/device.json存放模拟器连接信息config/tasks.json存放任务列表assets放模板图片logs放运行日志。这样划分的好处是运行环境差异只需要改 device 文件任务调整只需要改 tasks 文件模板更新只需要替换 images。如果你从旧版本升级不要直接覆盖 config 目录。建议先备份旧配置再对比新旧字段。2.4 旧版本数据迁移升级时最容易踩坑的是配置文件字段变化。v1.2 可能把原来的单一参数threshold改成了threshold: { default: 0.85, manual: 0.90 }之类的嵌套结构。直接沿用旧配置会导致 KeyError 或读取不到参数。迁移建议先备份旧项目中的 config、assets、logs。运行新版本提供的迁移脚本或手动对照 README 修改字段。如果旧版本有自定义模板图片检查图片路径和尺寸是否需要更新。小范围跑一个任务确认日志里没有 WARNING 和 ERROR。不要一次性把所有任务都迁移过来。先挑一个最简单的任务跑通再逐步扩大。3. 用 v1.2 跑通一个最小自动化任务3.1 配置模拟器和设备连接先打开模拟器并确保能被 ADB 识别。这里以模拟器端口 5555 为例adb devices如果输出包含device状态说明连接正常。如果显示offline尝试重启 adb serveradb kill-server adb start-server adb devicesMaaFgo 的device.json可以写成这样{ adb_path: D:/platform-tools/adb.exe, serial: 127.0.0.1:5555, screen_width: 1280, screen_height: 720 }注意adb_path要写实际路径。如果 adb 已经在系统 PATH 中可以直接写adb但显式路径更稳定尤其是多个模拟器共存时。3.2 编写最小任务配置假设我们要完成一个最简单的操作识别按钮并点击。tasks.json可以这样配置{ tasks: [ { name: click_start, action: click, image: assets/start_button.png, threshold: 0.85, wait_after: 1500 } ], global: { loop: 1, log_level: INFO } }这段配置表达的意思很直接在屏幕上寻找assets/start_button.png匹配度达到 0.85 以上时点击识别坐标点击完成后等待 1.5 秒。如果 v1.2 支持原生 YAML 配置也可以写成tasks: - name: click_start action: click image: assets/start_button.png threshold: 0.85 wait_after: 1500 global: loop: 1 log_level: INFO配置文件使用 JSON 还是 YAML取决于项目实现。这里不纠结格式关键是理解字段含义。3.3 启动脚本并观察输出如果项目入口是src/main.py启动方式类似python src/main.py --config config/tasks.json正常运行时日志可能输出2025-01-01 12:00:01 INFO load config: config/tasks.json 2025-01-01 12:00:02 INFO connect device: 127.0.0.1:5555 2025-01-01 12:00:02 INFO run task: click_start 2025-01-01 12:00:03 INFO capture screen: 1280x720 2025-01-01 12:00:04 INFO template found: start_button.png, match0.92, pos(640,520) 2025-01-01 12:00:04 INFO tap (640, 520) 2025-01-01 12:00:06 INFO task completed: click_start关键输出是match0.92和pos(640,520)。match 表示模板匹配相似度pos 是识别区域中心坐标。如果这两个值符合预期说明最小任务已经跑通。3.4 关键配置项速查表配置项示例值含义调大/调小的影响threshold0.85模板匹配最低相似度调大更容易漏识别调小更容易误触loop10任务循环次数决定挂机时长wait_after2000点击后等待毫秒数太短会导致画面未加载完imageassets/a.png模板图相对路径路径错误时识别失败serial127.0.0.1:5555模拟器 ADB 序列号配置错会连不上设备log_levelINFO日志输出级别DEBUG 会输出更多调试信息在 v1.2 中threshold往往既可以配置成全局参数也可以在每个 task 里单独覆盖。全局适合统一控制局部适合特殊界面。注意最小任务跑通只代表“脚本能运行”不代表“脚本适合长时间运行”。长时间运行还需要处理网络波动、弹窗、异常中断等情况。4. 理解 v1.2 的内部工作路径4.1 任务队列如何被解析和执行MaaFgo v1.2 的任务系统通常按这个顺序执行读取配置 - 解析任务列表 - 连接设备 - 对每个任务执行“截图、识别、动作、等待”循环。任务队列的设计决定了失败处理策略。旧版遇到异常往往直接退出v1.2 更倾向于给每个任务增加错误分支。例如{ name: battle, action: click, image: assets/battle_start.png, max_retry: 3, on_fail: skip }max_retry表示最多重试次数on_fail表示失败后是跳过还是中止。这样的好处是任务列表可以在无人值守时继续跑不会被单点异常卡死。执行器内部可以看作一个有限状态机。每个任务从待执行变为执行中再根据识别结果进入成功、重试或跳过状态。如果你要修改运行逻辑优先关注状态流转而不是直接在识别代码里加业务判断。4.2 图像识别区域与阈值调整图像识别不是对整张截图做无限精确匹配。MaaFgo 通常会把截图转成灰度图然后使用 OpenCV 的模板匹配函数计算模板图在截图各个位置的相似度。相似度最大值超过阈值就认为找到了目标。这里有一个常见误区阈值越高越安全但不代表越好。太高会导致按钮因为分辨率、明暗变化而识别不到太低又会在背景相似的位置误触。v1.2 把阈值做成可配置目的就是让你根据实际画面微调。如果你的按钮始终识别不到先检查模板图和游戏内实际画面是否一致。如果按钮是动态变化的比如包含倒计时、颜色变化可能需要截取不含动态部分的固定区域作为模板。日志里的 match 值是最好的调参依据。在 DEBUG 级别下你可以看到每个候选区域的匹配度根据实际值决定阈值设置。比如正常识别时 match 是 0.93识别失败时 match 只有 0.72阈值就可以放在 0.80 到 0.88 之间。4.3 日志、状态机和错误恢复v1.2 的日志设计会直接影响排错效率。一份好日志至少包含时间戳确定问题发生的时间顺序。任务名定位到具体任务。图片名和匹配度判断是识别问题还是逻辑问题。动作和坐标确认是否执行了点击。异常栈区分是代码异常还是业务状态异常。如果你发现脚本卡住不要只看最后一行日志而是回溯最近几个任务的状态。常见的卡住顺序是上一个任务点击后没有确认成功。下一个任务等待的界面图标不匹配。系统进入了一个没有对应模板的弹窗。v1.2 的错误恢复机制通常包括超时检测和重启任务。超时检测会为截图识别设置一个最大等待时间超过后就认为当前画面未达预期。重启任务则是在连续失败后重新初始化状态。5. 常见问题排查从现象到根因5.1 排查顺序设备、配置、识别、执行MaaFgo 出问题后建议按固定顺序排查不要一开始就怀疑图像识别算法。第一层是设备连接。用adb devices确认模拟器在线。如果连不上所有任务都会卡在 connect 阶段。第二层是配置读取。检查 JSON/YAML 格式是否正确路径是否存在字段名是否和项目文档一致。v1.2 升级后最常出现的问题就是旧配置字段失效。第三层是识别结果。打开 DEBUG 日志看识别到了什么坐标、匹配度是多少。如果画面里按钮存在但匹配度很低优先调整模板图和阈值。第四层是执行动作。确认点击坐标是否落在按钮范围内点击后画面是否发生变化。如果坐标正确但游戏无反应可能是模拟器窗口没有激活或者 ADB 输入事件被拦截。5.2 高频问题处理表问题现象常见原因检查方式处理建议设备连接失败adb 路径错误或模拟器未开启调试adb devices设置正确 adb_path重启模拟器配置文件不生效字段名不匹配或格式错误用 JSON/YAML 校验工具检查对照 README 修正字段识别不到按钮模板图过旧、分辨率不一致、阈值过高查看 DEBUG 日志 match 值重新截图调整阈值点击位置不对屏幕分辨率与配置不一致打印截图尺寸和点击坐标统一分辨率和配置任务卡住不跳过未配置 max_retry 或 on_fail查看任务状态日志为任务添加失败策略偶尔误触阈值过低模板背景相似检查日志中 match 较低的点击调高阈值或缩小模板区域运行一段时间后假死内存占用过高或连接断开观察日志和系统资源添加任务间等待增加自动重连5.3 如何提供有效 issue 信息如果你要向 MaaFgo 仓库提交 issue只写“运行失败”很难定位问题。建议提供五类信息版本信息MaaFgo v1.2 的 commit hash 或 Release 版本号。运行环境操作系统、Python 版本、模拟器名称、分辨率、ADB 版本。日志片段从 connect 到失败的完整日志不是最后三行。配置文件去掉敏感路径后的 device.json 和 tasks.json。截图包含目标按钮的实际画面和模板图片。一段可靠的 issue 描述就像一段排错文档它可以让维护者快速判断是配置问题、识别问题还是核心逻辑问题。注意使用自动化工具前请阅读游戏用户协议确认你的使用场景被允许。下面提到的二次开发仅面向学习和正当的工程实践。6. 从使用到二次开发v1.2 的可维护性设计6.1 把配置和代码分离v1.2 在配置设计上的一个明显趋势是把“容易变的东西”从代码里抽出来。最容易变的包括按钮图片、识别阈值、等待时间、设备连接参数。这些都应该放在 config 或 assets 目录下而不是硬编码在 Python 文件里。为什么这么做因为使用者和开发者的角色往往重叠。使用者不想为了改一个等待时间而去读源码开发者也不希望每次活动更新都重写任务逻辑。配置外置后适配新活动只需要增加模板图和任务配置。在二开时尽量不要破坏这个边界。新增任务类型时先考虑配置字段能否表达而不是在识别器里加 if-else。6.2 长任务运行时的稳定性建议长时间运行是 MaaFgo 的主要使用场景也是最容易暴露问题的场景。以下几个地方值得关注第一任务间加等待时间。游戏界面切换需要加载时间连续点击太快容易漏掉中间状态。wait_after不要设置得太短建议 1 到 3 秒。第二添加超时机制。每个任务都应该有最大执行时间超过后要么跳过要么重启当前任务。没有超时的脚本一旦遇到意外界面会一直卡到天荒地老。第三日志按日期分割。日志文件持续写入不分割会越来越大也不利于事后排查。v1.2 如果支持日志按大小或时间滚动建议开启。第四空闲时释放资源。每轮任务结束后可以主动释放截图缓存和内存对象避免长时间运行后占用过高。6.3 二次开发建议如果你想在 v1.2 基础上增加功能建议从以下模块入手增加新的动作类型比如swipe、wait、check_gone。增加多步条件判断比如识别到按钮 A 就点击 A否则点击 B。增加异常恢复策略比如网络弹窗出现时自动关闭。新增动作时要同步考虑动作是否需要在配置中携带参数。例如swipe动作需要起点、终点和持续时间{ name: swipe_home, action: swipe, from: [640, 600], to: [640, 300], duration: 500 }这样设计的好处是核心执行器只负责解释配置不关心具体业务。7. v1.2 之后扩展方向与学习建议7.1 多设备与多账号管理v1.2 如果已经支持设备配置外置那么多个模拟器并存就变得容易。你可以为每个模拟器写一份 device 配置然后用参数指定要运行的配置python src/main.py --device config/device_1.json --task config/tasks.json但要提醒一句多路并行不是简单启动多个进程。每个进程会独立截图、识别和控制模拟器对 CPU 和内存的占用会成倍增长。真正稳定运行还需要考虑模拟器资源分配、adb server 冲突、日志文件隔离等问题。如果只是偶尔切换账号手动切换配置通常就够用。不必一开始就追求全自动多开。7.2 新活动适配流程FGO 的活动界面经常变化v1.2 版本升级后原有的模板图片可能仍然有效也可能因为 UI 调整而失效。适配一个新活动的推荐流程是先用模拟器手动进入活动界面截图保存关键按钮。把图片裁剪成合适的模板越小越好但要保留明显特征。在任务配置中新增一个任务先用低阈值试跑。根据 DEBUG 日志中的 match 值调整阈值。把任务组合成完整流程跑一次全流程验证。不要试图一个模板图片适配所有界面。一套活动流程正常需要 5 到 10 张模板图每张图只服务于一个关键操作。7.3 学习自动化思路的路径MaaFgo 是一个不错的自动化工程学习样本。你可以在不注册任何账号的情况下直接阅读源码研究它的架构。建议按以下顺序学习先跑通最小任务理解配置到执行的整体流程。阅读识别模块理解模板匹配的输入输出。阅读任务执行模块理解状态流转和异常处理。尝试修改一个动作类型感受配置驱动的好处。最后再研究多任务组合和复杂界面适配。如果你是初学者不用一次性读懂所有代码。把一个任务从截图到点击的完整链路走通就已经能理解很多自动化工具的核心原理了。回到开头的问题MaaFgo v1.2 升级的重点不是追求功能数量而是让自动化任务更可控、更可维护、更可排查。无论你是使用者还是开发者都应该先把“最小任务跑通”这一步做到位再逐步扩展。跑通一个任务只是开始真正有价值的是理解它为什么能跑通、什么情况下会失败、失败后如何从日志里找到原因。带着这套排查思路去看 v1.2 的源码和配置会比直接复制别人的配置有用得多。