Refine CI workflows and fix macOS matrix gap

.github/workflows/README.md

@@ -0,0 +1,143 @@
+# CI/CD Workflow 说明
+
+## 概述
+
+本项目使用 GitHub Actions 进行持续集成和构建。Workflow 配置文件：
+
+- [ubuntu-build.yml](./ubuntu-build.yml)
+- [windows-build.yml](./windows-build.yml)
+- [macos-build.yml](./macos-build.yml)
+
+发布流程配置文件：[release.yml](./release.yml)
+
+## 构建矩阵
+
+### 维度说明
+
+项目支持以下构建配置的组合：
+
+1. **操作系统** (3种)
+   - Windows (windows-latest)
+   - macOS (macos-latest)
+   - Ubuntu (ubuntu-latest)
+
+2. **NDK 版本** (2种)
+   - r26d (稳定版本)
+   - r27c (较新版本)
+
+3. **构建系统** (2种)
+   - CMake (`--enable-cmake`)
+   - ndk-build (传统构建方式)
+
+4. **FFmpeg 支持** (2种)
+   - with-ffmpeg (`--enable-video-module`) - 支持视频录制功能
+   - no-ffmpeg (`--disable-video-module`) - 纯图片处理，体积更小
+
+5. **内存页大小** (2种)
+   - 4kb (默认) (`--disable-16kb-page-size`)
+   - 16kb (`--enable-16kb-page-size`) - 针对新 Android 设备优化
+
+理论上共有 **3 × 2 × 2 × 2 × 2 = 48** 种组合。
+
+## 触发策略
+
+### 1. Master 分支推送 (全量构建)
+
+当代码推送到 `master` 分支时，运行**所有 48 个构建任务**，确保所有配置组合都能正常工作。
+
+```yaml
+on:
+  push:
+    branches: [ "master" ]
+```
+
+**构建任务数量：** 48
+- Windows: 16 (2 NDK × 2 build-system × 2 ffmpeg × 2 page-size)
+- macOS: 16 (2 NDK × 2 build-system × 2 ffmpeg × 2 page-size)
+- Ubuntu: 16 (2 NDK × 2 build-system × 2 ffmpeg × 2 page-size)
+
+### 2. Pull Request (精简构建)
+
+PR 时运行**精简的 18 个构建任务**，在保证质量的同时节省资源：
+
+```yaml
+on:
+  pull_request:
+    branches: [ "master" ]
+```
+
+**构建任务数量：** 18
+
+#### Windows (1个任务)
+- NDK: r26d
+- 构建系统: CMake
+- FFmpeg: 启用
+- 页大小: 16KB
+
+#### macOS (1个任务)
+- NDK: r27c
+- 构建系统: ndk-build
+- FFmpeg: 禁用
+- 页大小: 4KB
+
+#### Ubuntu (16个任务 - 全量)
+- NDK: r26d + r27c
+- 构建系统: CMake + ndk-build
+- FFmpeg: 启用 + 禁用
+- 页大小: 4KB + 16KB
+- 全部组合: 2 × 2 × 2 × 2 = 16
+
+### 3. 其他分支推送
+
+非 master 分支的推送**不会触发** workflow，避免资源浪费。只有创建 PR 时才会触发精简构建。
+
+### 4. workflow 分支（全量构建）
+
+当分支名包含 `workflow` 时，会触发**全量构建**（等同于 master 全量矩阵），用于验证完整矩阵是否可通过。
+
+## 产物命名规则
+
+构建产物 (APK) 使用以下命名格式：
+
+```text
+apk-{OS}-{NDK}-{BuildSystem}-{FFmpeg}-{PageSize}.apk
+```
+
+**示例：**
+- `apk-Linux-r26d-cmake-ffmpeg-4kb.apk`
+- `apk-Windows-r27c-ndk-build-noffmpeg-16kb.apk`
+- `apk-macOS-r26d-cmake-ffmpeg-16kb.apk`
+
+## Lint 检查
+
+代码质量检查在 PR 和 master 分支推送时运行，确保主干代码质量。
+
+## Release 工作流（测试分支）
+
+当分支名包含 `workflow` 且触发 `release.yml` 时，将从 `build.gradle` 读取 `versionName`，生成 `v{版本号}-test` 的测试标签，**仅构建并上传 APK 工件**，不会创建 Release 或发布任何内容。
+
+## 本地测试
+
+可以使用项目根目录的 `tasks.sh` 脚本在本地进行构建测试：
+
+```bash
+# CMake 构建，启用视频模块，16KB 页大小
+./tasks.sh --release --enable-cmake --enable-video-module --enable-16kb-page-size --build
+
+# ndk-build 构建，禁用视频模块，默认页大小
+./tasks.sh --release --disable-video-module --disable-16kb-page-size --build
+```
+
+## 注意事项
+
+1. **NDK 版本**：确保本地安装了对应版本的 NDK
+2. **构建时间**：全量构建（48个任务）可能需要较长时间
+3. **产物大小**：启用 FFmpeg 的版本体积较大（包含视频编解码库）
+4. **页大小**：16KB 页大小版本需要 Android API 35+ 支持
+
+## 资源优化
+
+通过 PR 精简构建策略（18个任务 vs 48个任务），可以：
+- 节省约 62.5% 的 CI/CD 资源
+- 缩短 PR 反馈时间
+- 保持足够的测试覆盖率（Ubuntu 全量测试）

.github/workflows/macos-build.yml

@@ -0,0 +1,134 @@
+name: macOS Build
+
+on:
+  push:
+    branches:
+      - "master"
+      - "*workflow*"
+  pull_request:
+    branches: [ "master" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: "${{ matrix.os-name }} | NDK-${{ matrix.ndk }} | ${{ matrix.build-system }} | ${{ matrix.ffmpeg }} | ${{ matrix.page-size }}"
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJson(github.event_name == 'pull_request' && '[{"os":"macos-latest","os-name":"macOS","ndk":"r27c","build-system":"ndk-build","ffmpeg":"no-ffmpeg","page-size":"4kb"}]' || '[{"os":"macos-latest","os-name":"macOS","ndk":"r26d","build-system":"cmake","ffmpeg":"with-ffmpeg","page-size":"16kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r27c","build-system":"cmake","ffmpeg":"with-ffmpeg","page-size":"16kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r26d","build-system":"ndk-build","ffmpeg":"with-ffmpeg","page-size":"16kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r27c","build-system":"ndk-build","ffmpeg":"with-ffmpeg","page-size":"16kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r26d","build-system":"cmake","ffmpeg":"no-ffmpeg","page-size":"16kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r27c","build-system":"cmake","ffmpeg":"no-ffmpeg","page-size":"16kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r26d","build-system":"ndk-build","ffmpeg":"no-ffmpeg","page-size":"16kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r27c","build-system":"ndk-build","ffmpeg":"no-ffmpeg","page-size":"16kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r26d","build-system":"cmake","ffmpeg":"with-ffmpeg","page-size":"4kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r27c","build-system":"cmake","ffmpeg":"with-ffmpeg","page-size":"4kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r26d","build-system":"ndk-build","ffmpeg":"with-ffmpeg","page-size":"4kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r27c","build-system":"ndk-build","ffmpeg":"with-ffmpeg","page-size":"4kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r26d","build-system":"cmake","ffmpeg":"no-ffmpeg","page-size":"4kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r27c","build-system":"cmake","ffmpeg":"no-ffmpeg","page-size":"4kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r26d","build-system":"ndk-build","ffmpeg":"no-ffmpeg","page-size":"4kb"},{"os":"macos-latest","os-name":"macOS","ndk":"r27c","build-system":"ndk-build","ffmpeg":"no-ffmpeg","page-size":"4kb"}]') }}
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Android SDK
+      uses: android-actions/setup-android@v3
+
+    - name: Install NDK
+      shell: bash
+      run: |
+        NDK_FLAVOR="${{ matrix.ndk }}"
+        NDK_FLAVOR=$(printf "%s" "$NDK_FLAVOR" | tr -d '\r\n')
+        case "$NDK_FLAVOR" in
+          r26d*) NDK_VERSION="26.2.11394342" ;;
+          r27c*) NDK_VERSION="27.2.12479018" ;;
+          *)
+            echo "Error: Unsupported NDK version $NDK_FLAVOR"
+            exit 1
+            ;;
+        esac
+        set +o pipefail
+        yes | sdkmanager "ndk;${NDK_VERSION}"
+        SDKMANAGER_STATUS=${PIPESTATUS[1]}
+        set -o pipefail
+        if [ "$SDKMANAGER_STATUS" -ne 0 ]; then
+          echo "Error: sdkmanager failed with status $SDKMANAGER_STATUS"
+          exit "$SDKMANAGER_STATUS"
+        fi
+        echo "ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/${NDK_VERSION}" >> "$GITHUB_ENV"
+        echo "$ANDROID_SDK_ROOT/ndk/${NDK_VERSION}" >> "$GITHUB_PATH"
+
+    - name: Install build tools
+      run: brew install ninja
+
+    - name: Setup JDK 17
+      uses: actions/setup-java@v4
+      with:
+        java-version: '17'
+        distribution: 'temurin'
+        cache: gradle
+
+    - name: Grant execute permission for scripts
+      run: chmod +x gradlew tasks.sh
+
+    - name: Configure build parameters
+      shell: bash
+      run: |
+        # Set build system flag
+        if [ "${{ matrix.build-system }}" == "cmake" ]; then
+          echo "BUILD_SYSTEM_FLAG=--enable-cmake" >> $GITHUB_ENV
+        else
+          echo "BUILD_SYSTEM_FLAG=" >> $GITHUB_ENV
+        fi
+
+        # Set FFmpeg flag
+        if [ "${{ matrix.ffmpeg }}" == "with-ffmpeg" ]; then
+          echo "FFMPEG_FLAG=--enable-video-module" >> $GITHUB_ENV
+        else
+          echo "FFMPEG_FLAG=--disable-video-module" >> $GITHUB_ENV
+        fi
+
+        # Set page size flag
+        if [ "${{ matrix.page-size }}" == "16kb" ]; then
+          echo "PAGE_SIZE_FLAG=--enable-16kb-page-size" >> $GITHUB_ENV
+        else
+          echo "PAGE_SIZE_FLAG=--disable-16kb-page-size" >> $GITHUB_ENV
+        fi
+
+        # Set artifact name
+        OS_SHORT="${{ runner.os }}"
+        NDK_SHORT="${{ matrix.ndk }}"
+        BUILD_SYS="${{ matrix.build-system }}"
+        if [ "${{ matrix.ffmpeg }}" == "with-ffmpeg" ]; then
+          FFMPEG_SHORT="ffmpeg"
+        else
+          FFMPEG_SHORT="noffmpeg"
+        fi
+        PAGE_SHORT="${{ matrix.page-size }}"
+
+        echo "ARTIFACT_NAME=apk-${OS_SHORT}-${NDK_SHORT}-${BUILD_SYS}-${FFMPEG_SHORT}-${PAGE_SHORT}" >> $GITHUB_ENV
+
+    - name: Setup project (ndk-build mode)
+      if: matrix.build-system == 'ndk-build'
+      shell: bash
+      run: ./tasks.sh --setup-project
+
+    - name: Build APK
+      shell: bash
+      run: ./tasks.sh --release $BUILD_SYSTEM_FLAG $FFMPEG_FLAG $PAGE_SIZE_FLAG --build
+
+    - name: Find and rename APK
+      shell: bash
+      run: |
+        APK_FILE=$(find "cgeDemo/build" -name "*.apk" | grep -i release | head -n 1)
+        if [ -z "$APK_FILE" ]; then
+          echo "Error: No release APK found in cgeDemo/build"
+          exit 1
+        fi
+        mkdir -p artifacts
+        cp "$APK_FILE" "artifacts/cgeDemo-${{ env.ARTIFACT_NAME }}.apk"
+        echo "APK saved as: artifacts/cgeDemo-${{ env.ARTIFACT_NAME }}.apk"
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ env.ARTIFACT_NAME }}
+        path: artifacts/*.apk
+        compression-level: 0
+        retention-days: 15
+        if-no-files-found: error
+