M9A 项目结构全解析:重返未来:1999 小助手的目录架构与模块职责详解

原创2026-10-04 10:09:051,936 阅读
文章标签:RPAGUI 自动化工作流自动化计算机视觉桌面应用游戏开发

M9A 项目结构全解析:重返未来:1999 小助手的目录架构与模块职责详解

本指南以 M9A(重返未来:1999 小助手 / Assistant For Reverse: 1999)开源仓库的开发文档 structure.md 为核心,逐层拆解仓库顶层目录与关键文件的设计意图:从项目根部的接口声明与工程配置,到 Python Agent 的启动链路、游戏业务数据、任务定义、国际化、测试与工程化工具脚本。读完本文,你将掌握 M9A 的目录地图,能够快速定位“某个功能在哪个文件、某条配置由谁加载、某条命令如何运行”,为二次开发与排障建立清晰索引。

仓库概览:一份 MaaFW 驱动的自动化 Agent 工程

M9A 是基于 MaaFramework(MaaFW)构建的《重返未来:1999》游戏小助手,仓库本质是一个 MaaFW Agent 项目:由 interface.json 声明与客户端(GUI)的接口契约,由 agent/ 目录承载一个 Python 编写的 Agent 服务进程,由 tasks/、data/、resource/ 提供游戏业务逻辑与运行时资源。顶层目录各司其职:

目录 / 文件 定位
agent/ Python Agent 模块:服务入口、自定义识别/动作/数据落盘
tasks/ 任务定义(JSON 流水线),被 interface.json 导入
data/ 游戏业务数据(活动、作战、兑换码、SOS 等)
resource/ MaaFW 运行时资源(镜像中由同步流程生成)
docs/ 中英文档(zh_cn / en_us)
locales/ 界面显示翻译(zh_cn.json / en_us.json)
MaaCommonAssets/ MAA 通用资源子模块(OCR 模型)
tools/ 工程化脚本:同步、校验、打包、数据工具
tests/ pytest 测试套件
Android/ Android 客户端工程(MaaFwApp,独立本地项目)

项目根部的“名片”与接口契约

仓库根目录的几个 JSON/配置类文件是整个项目的骨架,理解它们就能读懂 M9A 与 MaaFW 生态的对接方式。

interface.json:MaaFramework 项目接口声明

interface.json 是 MaaFW 界面(GUI)读取的项目声明文件,定义了语言、控制器、资源、Agent 启动方式与任务导入清单,核心结构如下(节选):

{
    "interface_version": 2,
    "languages": {
        "zh_cn": "locales/zh_cn.json",
        "en_us": "locales/en_us.json"
    },
    "name": "m9a",
    "label": "M9A",
    "icon": "logo.ico",
    "mirrorchyan_rid": "M9A",
    "version": "v0.1.0",
    "controller": [
        { "name": "ADB", "label": "$Controller.Adb", "type": "Adb" },
        { "name": "PC", "label": "PC", "type": "Win32", "permission_required": true,
          "win32": {
              "class_regex": "UnityWndClass",
              "window_regex": "(重返未来|重返未來|Reverse|リバース)[:::].*1999",
              "screencap": "PrintWindow",
              "mouse": "SendMessageWithCursorPos",
              "keyboard": "SendMessageWithCursorPos"
          } },
        { "name": "PlayCover", "type": "PlayCover" }
    ],
    "resource": [
        { "name": "官服", "path": ["./resource/base"] },
        { "name": "国际服(EN)", "path": ["./resource/base", "./resource/global_jp", "./resource/global_en"] }
    ],
    "agent": [
        { "child_exec": "uv", "child_args": ["run", "python", "agent/main.py"] }
    ],
    "group": [
        { "name": "daily", "label": "$Group.Daily" },
        { "name": "standalone", "label": "$Group.Standalone" }
    ],
    "import": [
        "tasks/preset/Daily.json",
        "tasks/StartUp.json",
        "tasks/Wilderness.json"
    ]
}

关键字段解读:

  • languages / label 键:界面文案通过 $Controller.Adb、$Resource.Official、$Group.Daily 这类键引用 locales/*.json 中的翻译,实现多语言界面;
  • controller:支持 ADB(安卓模拟器/真机)、PC(Win32 原生窗口,通过 UnityWndClass 类名与“重返未来…1999”窗口标题正则匹配,截图走 PrintWindow,键鼠走 SendMessageWithCursorPos)、PlayCover(macOS 上运行 iOS 版)三种控制器;
  • resource:按服务器分区(官服、B 服、OPPO 服、小米服、华为服、国际服 EN/JP、港澳台服、国际服 KR 共 9 类),每个资源组按顺序叠加 ./resource/base 与对应渠道目录,实现“基础资源 + 渠道覆盖”的合并机制;
  • agent:声明 Agent 服务以 uv run python agent/main.py 方式拉起(见 interface.json 中的 agent 字段);
  • import:把 tasks/ 下的 30 余个任务文件全部导入界面,形成可勾选的自动化任务列表。

maa-project.json:MAA 工程级配置

maa-project.json 是 MAA 工具链(@nekosu/maa-tools)的工程配置,约束了版本、OCR、运行时与质量门禁:

  • python.requiresPython 为 >=3.13,<3.14,recommendedPython 为 3.13,与 agent/main.py 的启动硬校验一致(不满足即 SystemExit);
  • ocr 声明 OCR 模型来自子模块:"source": "submodule"、"submodulePath": "MaaCommonAssets/OCR",映射到 ppocr_v6/small 的 det/rec/keys 四件套(见 maa-project.json);
  • runtime 声明运行时组件:mfa(MaaFW 本体)走 beta 渠道、mxu(MaaX 工具)走 stable 渠道;
  • resources 声明基准资源组 resource/base;
  • addons 与 features 开关(autoFormat、community、gitCliff、optimizeImages、schemaSync、ci、quality、release、vscode)对应工程化流水线能力。

package.json 与 pyproject.toml:双语言工具链

M9A 同时使用 Node.js 与 Python 两套工具链:

  • package.json 声明 pnpm 管理的脚本:check(聚合 format/schema/i18n/maa 四类校验)、check:schema(node tools/validate-schema.mjs)、check:i18n(node tools/validate-i18n.mjs)、check:py(ruff + pyright + pytest 三连)、format、sync:runtime、sync:schema、optimize:images、release:dry-run 等;devDependencies 包括 @nekosu/maa-tools、prettier 及其 MaaFW 专用插件、ajv(JSON Schema 校验)等;
  • pyproject.toml 声明 Python 工程:依赖 maafw>=5.13.0b0、loguru、pillow、pytz、requests;dev 依赖 pyright、pytest、ruff;[tool.hatch.build.targets.wheel] packages = ["agent"] 表明打包产物即 agent/ 目录;pytest 配置 testpaths = ["tests"]、pythonpath = [".", "agent"],便于测试直接导入 agent 包。

其余根级文件:pnpm-workspace.yaml / pnpm-lock.yaml 管理 Node 依赖,uv.lock 锁定 Python 依赖,.node-version / .python-version 固定运行时版本,logo.ico 为应用图标,LICENSE(AGPL-3.0-or-later)、CONTACT、CONTRIBUTING.md 为合规与协作文件。原文档的 file-tree 中还规划了 .github/(Issue 模板、GitHub Actions 工作流、dependabot 与 changelog 配置)与 .vscode/(扩展推荐、调试、任务配置)等开发协作目录,本镜像中未包含。

agent/:Python Agent 核心模块

agent/ 是仓库最具技术含量的部分,负责接收 MaaFW 界面传来的 socket 指令、执行自定义识别与动作、维护账号与资源热更新。从源码结构看,其内部又分五块:入口、运行时、自定义逻辑、工具库、路径管理。

入口链路:main.py → agent_runtime.py

agent/main.py 是 Agent 进程入口,被 interface.json 的 agent.child_args 拉起。它的职责链:

  1. 校验 Python 版本(>=3.13,<3.14),否则直接退出;
  2. 将 stdout 重配置为 UTF-8 编码;
  3. 计算 agent_dir 与 project_root_dir,若当前工作目录不是项目根则 os.chdir 切换,并把 agent_dir 插入 sys.path;
  4. 调用 ensure_maafw_binary_path(project_root_dir)(来自 maafw_paths.py)——注释明确说明必须早于 agent_runtime 执行,因为 utils 包导入时就会连带 import maa,此后库目录已定死;
  5. 调用 run_agent(project_root_dir) 启动服务。

agent/agent_runtime.py 中的 run_agent(L167 起)完成完整的生命周期:

def run_agent(project_root_dir: str) -> int:
    configure_runtime_paths(project_root=project_root_dir, work_root=os.getcwd())
    # ... 检查 socket id 参数
    from maa.agent.agent_server import AgentServer
    from maa.tasker import Tasker
    _log_maafw_version()          # 以原生库 MaaVersion() 为准记录版本
    _check_resource_version()     # 版本检查(utils/version_checker)
    _hot_update()                 # 资源热更新(utils/manifest_checker + resource_updater)
    import custom
    custom.register_all()         # 注册全部自定义动作/识别/落盘
    Tasker.set_log_dir("./debug/agent")
    socket_id = sys.argv[-1]
    AgentServer.start_up(socket_id)
    AgentServer.join()
    AgentServer.shut_down()
    return 0

值得注意的工程细节:

  • 热更新机制:启动时读取运行时配置目录下的 hot_update.json(默认开启),基于 data/activity/manifest.json、data/combat/manifest.json、data/redeem_code/manifest.json、data/sos/manifest.json 等清单做增量更新;失败时会把“哪些功能受影响、如何重试”整理成用户可读的提示(见 _MANIFEST_FEATURE_HINTS 与 _describe_hot_update_failure);
  • 版本报告策略:_log_maafw_version 的注释指出 pip 元数据不可信(增量更新会残留旧 dist-info),因此以原生库 Library.version() 为准,元数据仅兜底;
  • PI 环境快照:log_pi_environment 会记录 PI_INTERFACE_VERSION、PI_CONTROLLER、PI_RESOURCE 等 8 个环境变量到 debug 日志,便于排障。

custom/:自定义扩展三件套

custom/init.py 通过 sys.modules.setdefault 将 custom.action / custom.reco / custom.sink 注册为可导入别名,并提供 register_all() 依次调用三个子包的注册函数。对应 MaaFW 的三类扩展点:

  • action/:自定义动作(19 个模块,见 agent/custom/action/init.py 的 ACTION_MODULES),例如 combat.py(常规作战)、balanced_farming.py(均衡种植/平衡刷取)、activity.py(活动)、wilderness.py(荒原)、syndrome_of_silence.py(局外演绎:无声综合征)、redeem_code.py(兑换码)、switch_account.py(切号)、warehouse_inventory.py(仓库盘点)等,每个模块对应 tasks/ 下的同名任务;
  • reco/:自定义识别(11 个模块),如 compare_numbers.py(数字比较)、auto_promotion.py、sos_node_template.py(SOS 节点模板)等,处理 OCR 或模板匹配难以直接表达的场景;
  • sink/:自定义数据落盘,目前只有 aspect_ratio.py(长宽比处理),配合 tests/test_aspect_ratio_sink.py 等测试验证。

utils/:工具函数库

utils/ 是 Agent 的公共设施层(共 14 个模块),与运行生命周期一一对应:

  • runtime_paths.py:运行时路径配置(configure_runtime_paths / get_runtime_paths),被 agent_runtime 首行调用;
  • version_checker.py:资源版本检查(check_resource_version);
  • manifest_checker.py:manifest 清单更新检查与缓存(check_manifest_updates / save_manifest_cache_from_result);
  • resource_updater.py:按清单实际下载/更新资源(check_and_update_resources);
  • account_store.py:账号存储(配合 switch_account.py 切号功能,见 tests/test_switch_account.py);
  • http_session.py:带重试与 UA 的 HTTP 会话(见 tests/test_http_session.py);
  • logger.py / exceptions.py / maa_types.py / params.py / pienv.py / time.py / aspect_ratio.py:日志、异常体系、MaaFW 类型封装、参数解析、PI 环境、时区处理与长宽比计算。

tasks/ 与 data/:游戏业务的双层结构

M9A 的业务逻辑采用“数据驱动任务”的设计:data/ 存放游戏数值与清单数据,tasks/ 存放 MaaFW 流水线任务定义(JSON),二者通过 interface.json 的 import 与热更新清单关联起来。

tasks/:任务流水线定义

tasks/ 顶层是 30 余个功能任务 JSON(如 Combat.json、Bank.json、Lucidscape.json、RedeemCode.json、TheSyndromeOfSilence.json、WarehouseInventory.json、8bit.json、MusesBox.json、PreStormProtocol.json 等),每个文件对应一个自动化功能;tasks/preset/ 下还有 4 个预设组合:

  • Daily.json:日常任务集合;
  • DailyActivity.json:日常 + 活动组合;
  • DailyReRelease.json:日常 + 复刻活动组合;
  • StandAlone.json:独立(单发)任务集合。

interface.json 的 group 字段(daily / standalone)正是为归组这些预设而设计,GUI 中可整体勾选。

data/:游戏数据与热更新清单

data/ 按功能分子目录(见 data/ 实际结构):

  • activity/:活动数据,按地区分语言文件 cn.json / en.json / jp.json / tw.json,配合 tests/test_activity.py 与 tools/activity_data/ 工具维护;
  • combat/:作战数据,balanced_farming.json(均衡刷取配置)、drop_index.json(掉落索引)、items.json(物品表),见 tests/test_combat.py;
  • redeem_code/:兑换码(cn.txt);
  • sos/:局外演绎:无声综合征的 items.json(条目)与 nodes.json(节点图)。

这些目录配合 manifest 清单实现热更新:tools/ci/generate_manifest_cache.py 生成清单缓存,utils/manifest_checker.py 在 Agent 启动时检查并增量更新。

docs/ 与 locales/:文档与界面国际化

  • docs/ 按语言分 zh_cn/ 与 en_us/,各自下辖 manual/(使用手册:CLI、连接、FAQ、新手指南、MirrorChyan 等)、develop/(开发文档:自定义、流水线、结构、格式化、i18n、海外客户端适配等)、protocol/(协议文档:活动、作战、物品、SOS、仓库盘点等)。本文对应的 structure.md 即为开发文档之一;
  • locales/ 存放界面显示翻译 en_us.json / zh_cn.json,由 tools/validate-i18n.mjs 校验中英文案键的一致性(见 package.json 的 check:i18n 脚本)。

tools/:工程化与辅助脚本

tools/ 汇聚了仓库的工程化能力,按实际存在的文件可分为五组:

分组 文件 职责
数据工具 activity_data/(analyzeContent.py、getContent.py、main.py) 活动内容分析、抓取与汇总
CI 脚本 ci/download_drop_core.py、ci/generate_manifest_cache.py 掉落核心下载、manifest 缓存生成
同步脚本 sync-runtime.mjs、sync-schema.mjs 同步 MaaFW 运行时、同步 JSON Schema
校验脚本 validate-schema.mjs、validate-i18n.mjs Schema 校验、i18n 一致性校验(由 check:schema / check:i18n 驱动)
构建/配置 android-packaging.mjs、configure.py、optimize-images.mjs、registry/(PC 端注册表工具)、schema/(interface、pipeline、custom.action 等 JSON Schema 与 schema-manifest.json)、sentry/(崩溃与任务报告 CLI) Android 打包、OCR 模型配置、图片优化、PC 注册表修改、Schema 定义与错误上报

对应地,package.json 的 sync:runtime、sync:schema、optimize:images、release:dry-run 等脚本直接调用这些 .mjs 工具;maa-project.json 中的 schemaSync、optimizeImages 等 addon 开关也与之对应。

tests/ 与 Android/:质量保障与客户端

  • tests/:pytest 测试套件,覆盖 Agent 全链路:test_agent_runtime.py(启动生命周期)、test_custom_registration.py(扩展注册)、test_manifest_checker.py / test_resource_updater.py(热更新)、test_combat.py / test_wilderness.py / test_warehouse_inventory.py(具体功能)、test_i18n_validator.py / test_schema_validator.py(工程校验)等,运行方式为 uv run --frozen pytest(见 package.json test:py)。tests/fixtures/ 存放活动公告等测试固件;
  • Android/:MaaFwApp 客户端工程目录,携带自己的 README.md 与 profile.yaml;pyproject.toml 的 ruff 配置特意 extend-exclude = ["Android"],说明它是独立的本地项目,不参与仓库 Python 代码规范。

资源与运行时:MaaCommonAssets 与 resource

  • MaaCommonAssets/:MAA 通用资源 git 子模块(.gitmodules 声明,镜像中为空目录)。根据 maa-project.json 的 ocr 配置,OCR 模型(ppocr_v6/small 的 det.onnx / rec.onnx / keys.txt)即从 MaaCommonAssets/OCR 引入,由 configure.py 负责配置;
  • resource/:MaaFW 运行时资源目录,interface.json 的每个资源组都以 ./resource/base 为基底并叠加渠道目录(bilibili、oppo、mi、huawei、global_jp、global_en、tw、global_kr 等)。该目录在构建/同步阶段由 sync-runtime.mjs 或 MAA 工具链填充,属于运行时生成内容。

小结:一张地图读懂 M9A

把以上内容还原成一张“从上到下的调用链”,即可掌握整个仓库的运转逻辑:

interface.json / maa-project.json(声明与契约)
        │  agent: uv run python agent/main.py
        ▼
agent/main.py(入口:版本校验 → 路径初始化)
        ▼
agent/agent_runtime.py(运行时:版本检查 → 热更新 → 注册 custom → AgentServer)
        │  调用 utils/*(runtime_paths、manifest_checker、resource_updater、account_store…)
        ▼
agent/custom/(action 19 模块 + reco 11 模块 + sink 2 模块)
        │  执行时读取
        ▼
tasks/*.json(任务流水线) ←  data/*(活动/作战/兑换码/SOS 数据,可热更新)
        │  界面文案
        ▼
locales/*.json(多语言)

配合 tools/ 的同步与校验脚本、tests/ 的回归测试,M9A 形成了一套“接口声明 → Agent 执行 → 数据热更新 → 工具链保障”的完整自动化工程。对开发者而言:改游戏逻辑看 agent/custom 与 tasks/,改数据看 data/,改界面看 interface.json 与 locales/,改工程链看 tools/ 与两个配置文件(package.json、pyproject.toml),调试入口则是 agent/main.py 与 agent/agent_runtime.py 以及 ./debug/agent 日志目录。

登录后查看全文
M9A