M9A 项目结构全解析:重返未来:1999 小助手的目录架构与模块职责详解
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 拉起。它的职责链:
- 校验 Python 版本(
>=3.13,<3.14),否则直接退出; - 将 stdout 重配置为 UTF-8 编码;
- 计算
agent_dir与project_root_dir,若当前工作目录不是项目根则os.chdir切换,并把agent_dir插入sys.path; - 调用
ensure_maafw_binary_path(project_root_dir)(来自 maafw_paths.py)——注释明确说明必须早于agent_runtime执行,因为 utils 包导入时就会连带 import maa,此后库目录已定死; - 调用
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.jsontest: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 日志目录。