MRA

安卓打包（MaaFwApp）

MRA 的安卓版通过 MaaFwApp 出包。MaaFwApp 是 MaaFramework 的通用 Android GUI，在构建期把一份 Project Interface V2 资源打进 APK，运行时通过 Shizuku 或 root 起特权进程，截屏与点击走本机 native controller，不经过 adb。

接入模型：MaaFwApp 以子模块形式放在 Android/MaaFwApp，MRA 只提供一份打包配方 Android/profile.yaml（指明资源在哪、包名/图标、agent 怎么拉起）， MaaFwApp 照配方出 APK。换资源 = 改资源 + 重新出包，不改外壳代码。

资源随 APK 绑定，Android 端不支持热更新，也暂不支持 Mirror酱。

本接入参考了 MAA1999/M9A 的标准写法：子模块 + Android/profile.yaml

相对路径，配方本身自洽，本地与 CI 共用同一份。

目录结构差异说明

M9A 的资源是扁平的（interface.json、resource/、agent/ 都在仓库根），配方可 assets: .. 直接引用；MRA 的 PI 在 assets/ 子目录，而 agent/、LICENSE、图标在仓库根，与 assets/ 不同层。配方的 include 只能匹配 assets 目录里的文件，因此出包前先跑 python tools/stage_android.py：把 agent/、LICENSE 拷进 assets/，并由 logo.ico 生成 assets/logo.png。这些产物已加进 .gitignore。

版本对齐

Android 上 agent 用的 maa Python 绑定和它背后的 MaaFramework 都来自 agent 内核 MaaAgentCoreAndroid（公开索引没有 Android 版 maafw 轮子），APK 里 client 侧的 MaaFramework .so 必须与内核同版本，否则前后端版本不一致。

所以 workflow 只钉一个值：android.yml 顶部的 AGENT_CORE_TAG（形如 3.13.15-maafw5.14.0）， MaaFramework 的 tag 由它的 maafw 段反推（v5.14.0）。升级时只改这一处，或手动触发时填 agent_core_tag。agent/requirements.txt 里桌面端的 MaaFw==X.X.X 会被 build_agent_bundle.py 丢掉，不影响安卓。

自动出包（CI）

.github/workflows/android.yml：

检出 MRA 及子模块（MaaCommonAssets、MaaFwApp）
由 AGENT_CORE_TAG 解析出 MaaFramework 版本
python configure.py 生成 OCR 模型，python tools/stage_android.py --version <tag> 铺 agent / LICENSE / 图标并写入版本号
scripts/setup_maa_framework.py 铺 MaaFramework 的 Android .so
scripts/build_agent_bundle.py --core-tag <AGENT_CORE_TAG> 基于 agent/requirements.txt 组装内嵌 Python 运行时
按 Android/profile.yaml 出包，产物 MRA-<tag>-android-<variant>.apk

push / PR 自动出 debug 包；手动 workflow_dispatch 可选 debug/release 与 agent 内核 tag
打 v* tag 时出 release 包并附到对应 Release
debug 只出 arm64-v8a；release 出双 ABI（arm64-v8a + x86_64）

本地出包

需要 JDK 17、Android SDK、Python 3（含 Pillow）。

git clone --recursive https://github.com/Saratoga-Official/MRA.git
cd MRA
# 已经 clone 过的：git submodule update --init --recursive

# 铺资源
python configure.py
python tools/stage_android.py

# 铺 MaaFramework .so 与 agent 运行时（版本与 android.yml 的 AGENT_CORE_TAG 一致）
cd Android/MaaFwApp
python scripts/setup_maa_framework.py --abi arm64-v8a --tag v5.14.0
python scripts/build_agent_bundle.py --out ../agent-dist \
    --core-tag 3.13.15-maafw5.14.0 --abi arm64-v8a \
    --requirements ../../agent/requirements.txt

# 指定配方与 ABI（写进 Android/MaaFwApp/local.properties，不进 git）
cat > local.properties <<EOF
sdk.dir=<你的 Android SDK 路径>
pi.profile=<MRA 仓库绝对路径>/Android/profile.yaml
build.debugAbi=arm64-v8a
EOF

./gradlew :app:assembleDebug     # 或 installDebug 直接装到连接的设备

产物在 Android/MaaFwApp/app/build/outputs/apk/。改了 agent/、LICENSE 或图标要重跑 tools/stage_android.py；改 assets/ 里的资源直接重新 assembleDebug 即可；换了 agent/requirements.txt 再跑一遍 build_agent_bundle.py。本地出 release 双 ABI 包时， setup_maa_framework.py 与 build_agent_bundle.py 都要再加 x86_64，并在 local.properties 写 build.releaseAbi=arm64-v8a,x86_64。

Release 签名

默认 assembleRelease 出未签名包。配置签名后再出 release：在 MaaFwApp 的 local.properties 或环境变量提供 KEYSTORE_PATH、KEYSTORE_PASSWORD、KEY_ALIAS、KEY_PASSWORD。 CI 走仓库 Secrets：ANDROID_KEYSTORE_BASE64、ANDROID_KEYSTORE_PASSWORD、ANDROID_KEY_ALIAS、 ANDROID_KEY_PASSWORD；未配置时 release 包未签名，日常用 debug 包即可。

常见问题

现象	排查
一点开始就 native 加载失败	`setup_maa_framework.py` 未跑或 ABI 不符
开始任务提示未带 agent 运行时	agent bundle 未打进，检查 `Android/agent-dist` 与 ABI 是否对齐
agent 连上后行为异常、报协议错误	client `.so` 与 agent 内核的 MaaFramework 版本不一致，见「版本对齐」
换了资源装上还是旧内容	清应用数据；版本号未变时可能沿用旧解包
查看运行日志	`adb logcat -s MaaFw`

This site is open source. Improve this page.