feat: support android app

.github/workflows/android-release.yml

@@ -0,0 +1,103 @@
+name: Android Release
+
+on:
+  push:
+    tags:
+      - "android-v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  apk:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    env:
+      PI_PROFILE: ${{ github.workspace }}/Android/profile.yaml
+      KEYSTORE_BASE64: ${{ secrets.KEYSTORE_BASE64 }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v3
+
+      - name: Install CMake
+        run: sdkmanager "cmake;3.22.1"
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Cache MaaFramework zips
+        uses: actions/cache@v4
+        with:
+          path: Android/MaaFwApp/.maa-cache
+          key: maa-fw-${{ runner.os }}-${{ hashFiles('Android/MaaFwApp/scripts/setup_maa_framework.py') }}
+
+      - name: Cache agent core
+        uses: actions/cache@v4
+        with:
+          path: Android/MaaFwApp/.maafw
+          key: maa-agent-core-${{ runner.os }}-${{ hashFiles('Android/MaaFwApp/scripts/build_agent_bundle.py') }}
+
+      - name: Fetch MaaFramework native libraries
+        working-directory: Android/MaaFwApp
+        run: python scripts/setup_maa_framework.py
+
+      - name: Build agent runtime
+        working-directory: Android/MaaFwApp
+        run: |
+          python scripts/build_agent_bundle.py \
+            --out "${GITHUB_WORKSPACE}/Android/agent-dist" \
+            --abi arm64-v8a \
+            --requirements "${GITHUB_WORKSPACE}/requirements.txt" \
+            --exclude pillow --require pillow==11.0.0 \
+            --extra-index-url https://chaquo.com/pypi-13.1/
+
+      - name: Decode keystore
+        if: env.KEYSTORE_BASE64 != ''
+        run: |
+          echo "${KEYSTORE_BASE64}" | base64 -d > "${GITHUB_WORKSPACE}/release.jks"
+          echo "KEYSTORE_PATH=${GITHUB_WORKSPACE}/release.jks" >> "${GITHUB_ENV}"
+
+      - name: Write local.properties
+        working-directory: Android/MaaFwApp
+        run: |
+          echo "sdk.dir=${ANDROID_HOME}" > local.properties
+          echo "pi.profile=${PI_PROFILE}" >> local.properties
+
+      - name: Assemble release APK
+        working-directory: Android/MaaFwApp
+        env:
+          KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
+          KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
+          KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
+        run: |
+          chmod +x gradlew
+          ./gradlew :app:assembleRelease --no-daemon --stacktrace
+
+      - name: Upload APK
+        uses: actions/upload-artifact@v4
+        with:
+          name: M9A-Meow-release
+          path: Android/MaaFwApp/app/build/outputs/apk/release/*.apk
+          if-no-files-found: error
+
+      - name: Publish GitHub Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: Android/MaaFwApp/app/build/outputs/apk/release/*.apk
+          generate_release_notes: true

.github/workflows/android.yml

@@ -0,0 +1,117 @@
+name: Android
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - "Android/**"
+      - "agent/**"
+      - "requirements.txt"
+      - "interface.json"
+      - ".github/workflows/android.yml"
+  pull_request:
+    paths:
+      - "Android/**"
+      - "agent/**"
+      - "requirements.txt"
+      - "interface.json"
+      - ".github/workflows/android.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: android-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  apk:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      PI_PROFILE: ${{ github.workspace }}/Android/profile.yaml
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v3
+
+      - name: Install CMake
+        run: sdkmanager "cmake;3.22.1"
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+        with:
+          cache-read-only: ${{ github.event_name == 'pull_request' }}
+
+      - name: Cache MaaFramework zips
+        uses: actions/cache@v4
+        with:
+          path: Android/MaaFwApp/.maa-cache
+          key: maa-fw-${{ runner.os }}-${{ hashFiles('Android/MaaFwApp/scripts/setup_maa_framework.py') }}
+
+      - name: Cache agent core
+        uses: actions/cache@v4
+        with:
+          path: Android/MaaFwApp/.maafw
+          key: maa-agent-core-${{ runner.os }}-${{ hashFiles('Android/MaaFwApp/scripts/build_agent_bundle.py') }}
+
+      - name: Cache agent bundle
+        uses: actions/cache@v4
+        with:
+          path: Android/agent-dist
+          key: m9a-agent-${{ runner.os }}-${{ hashFiles('requirements.txt', 'Android/MaaFwApp/scripts/build_agent_bundle.py') }}
+
+      - name: Fetch MaaFramework native libraries
+        working-directory: Android/MaaFwApp
+        run: python scripts/setup_maa_framework.py --abi arm64-v8a
+
+      - name: Build agent runtime
+        working-directory: Android/MaaFwApp
+        run: |
+          if [ -x "${GITHUB_WORKSPACE}/Android/agent-dist/arm64-v8a/bundle/bin/python3" ]; then
+            echo "agent bundle cache hit"
+            exit 0
+          fi
+          python scripts/build_agent_bundle.py \
+            --out "${GITHUB_WORKSPACE}/Android/agent-dist" \
+            --abi arm64-v8a \
+            --requirements "${GITHUB_WORKSPACE}/requirements.txt" \
+            --exclude pillow --require pillow==11.0.0 \
+            --extra-index-url https://chaquo.com/pypi-13.1/
+
+      - name: Write local.properties
+        working-directory: Android/MaaFwApp
+        run: |
+          {
+            echo "sdk.dir=${ANDROID_HOME}"
+            echo "pi.profile=${PI_PROFILE}"
+            echo "build.debugAbi=arm64-v8a"
+          } > local.properties
+
+      - name: Assemble debug APK
+        working-directory: Android/MaaFwApp
+        run: |
+          chmod +x gradlew
+          ./gradlew :app:assembleDebug --no-daemon --stacktrace
+
+      - name: Upload APK
+        uses: actions/upload-artifact@v4
+        with:
+          name: M9A-Meow-debug
+          path: Android/MaaFwApp/app/build/outputs/apk/debug/*.apk
+          if-no-files-found: error
+          retention-days: 14

.gitignore

@@ -21,3 +21,8 @@ maafw.log
 
 # node 相关
 .pnpm-store/
+.idea
+# Android 客户端：agent 产物在子模块外，必须在这里忽略
+Android/agent-dist/
+*.jks
+*.jks.b64

.gitmodules

@@ -1,3 +1,7 @@
 [submodule "MaaCommonAssets"]
 	path = MaaCommonAssets
 	url = https://github.com/MaaXYZ/MaaCommonAssets.git
+[submodule "Android/MaaFwApp"]
+	path = Android/MaaFwApp
+	url = https://github.com/Aliothmoon/MaaFwApp.git
+	branch = main

Android/README.md

@@ -0,0 +1,45 @@
+# Android 客户端
+
+外壳是 [MaaFwApp](https://github.com/Aliothmoon/MaaFwApp) 子模块，资源和 agent 用本仓库的树，改完直接出包。
+
+## 首次
+
+```bash
+git submodule update --init --recursive Android/MaaFwApp
+python Android/MaaFwApp/scripts/setup_maa_framework.py --abi arm64-v8a
+python Android/MaaFwApp/scripts/build_agent_bundle.py \
+    --out Android/agent-dist \
+    --requirements requirements.txt \
+    --exclude pillow --require pillow==11.0.0 \
+    --extra-index-url https://chaquo.com/pypi-13.1/
+```
+
+在 `Android/MaaFwApp/local.properties` 里写（不进 git）：
+
+```properties
+sdk.dir=<Android SDK>
+pi.profile=../profile.yaml
+build.debugAbi=arm64-v8a
+```
+
+## 出包
+
+```bash
+./Android/MaaFwApp/gradlew -p Android/MaaFwApp :app:installDebug
+```
+
+改 `interface.json`、`tasks/`、`agent/` 后重新 `installDebug` 即可，不必再指外部路径。换了 `requirements.txt` 再跑一遍 `build_agent_bundle.py`。
+
+升外壳：
+
+```bash
+git -C Android/MaaFwApp fetch
+git -C Android/MaaFwApp checkout origin/main
+git add Android/MaaFwApp
+```
+
+## CI
+
+改 `Android/`、`agent/`、`requirements.txt` 或 `interface.json` 后，Actions 会打一份 arm64 debug APK。打 `android-v*` tag（或手动跑 Android Release）出 release 包。
+
+Release 签名可选，仓库 Secrets：`KEYSTORE_BASE64`、`KEYSTORE_PASSWORD`、`KEY_ALIAS`、`KEY_PASSWORD`。不配就打未签名包。

Android/profile.yaml

@@ -0,0 +1,46 @@
+# Android 打包配方。相对路径相对本文件。
+# assets 指向上一级，也就是本仓库根；改任务 / agent 不用再设环境变量。
+
+assets: ..
+
+include:
+  - interface.json
+  - tasks/**
+  - resource/**
+  - data/**
+  - agent/**
+  - config/**
+  - logo.ico
+  - CONTACT
+  - LICENSE
+
+# images/ 不能整目录挖：银行等 option 的 icon 指在这里
+exclude:
+  - resource/announcement/*.md
+  - resource/announcement/images/CCMain.png
+  - resource/announcement/images/mojing_tjb.jpg
+  - resource/announcement/images/uttu.png
+  - resource/announcement/images/SOSMain.png
+  - resource/announcement/images/newbie-main-interface.png
+
+# 出运行时（在 android/MaaFwApp 下执行）：
+#   python scripts/build_agent_bundle.py --out ../agent-dist \
+#     --requirements ../../requirements.txt \
+#     --exclude pillow --require pillow==11.0.0 --extra-index-url https://chaquo.com/pypi-13.1/
+agent:
+  sourceDir: agent-dist
+  abi: [arm64-v8a]
+  runtimes:
+    - location: bundle
+      executable: bin/python3
+      args: [-u, agent/main.py]
+      env:
+        PYTHONHOME: "{bundle}/prefix"
+        PYTHONPATH: "{bundle}/site-packages/pure.zip:{bundle}/site-packages"
+        LD_LIBRARY_PATH: "{bundle}/prefix/lib:{bundle}/site-packages/chaquopy/lib:{nativeLibs}"
+        MAAFW_BINARY_PATH: "{nativeLibs}"
+
+app:
+  id: m9a
+  label: M9A
+  icon: logo.png

docs/zh_cn/develop/structure.md

@@ -19,6 +19,10 @@ icon: hugeicons:structure-01
     - launch.json # 调试配置
     - settings.json # 项目设置
     - tasks.json # 任务配置
+- Android/ # Android 客户端（MaaFwApp 子模块 + 打包配方）
+    - MaaFwApp/ # 外壳子模块
+    - profile.yaml # 打包配方，资源指向上一级本仓库
+    - README.md # 出包说明
 - agent/ # Agent模块代码
     - custom/ # 自定义识别和任务
     - utils/ # 工具函数