# 构建指南 ## 环境 - JDK 17、Android SDK 35、Android NDK 27.0.12077973(或通过 `ANDROID_NDK_HOME` 指定兼容 NDK)。 - Python 3.11+,使用项目自带的 Gradle wrapper。 - 设置 `JAVA_HOME` 和 `ANDROID_HOME`(或 `ANDROID_SDK_ROOT`)。 只编译应用源码,无需准备完整运行镜像: ```powershell ./gradlew.bat :core:compileKotlin :app:compileBootstrapReleaseKotlin ``` ## 完整包输入 完整 APK 面向 ARM64。源码仓库保留应用与原生源码、运行环境安装配方和来源锁,不包含预制镜像、原生预编译程序或维护者的辅助工具。打包前需要准备: | 输入 | 默认位置 | 内容 | | --- | --- | --- | | 完整镜像与 manifest | `runtime/apk-assets/bootstrap/arm64-v8a/` | Ubuntu、AstrBot、Python 及通用依赖 | | 原生程序 | `app/src/main/jniLibs/` | PRoot、原生运行器及匹配库 | | 基础环境资产 | `app/src/main/assets/bootstrap/` | 初始化使用的资源 | | 源码与许可输入 | `.cache/` 或工程外缓存 | 来源锁指定的上游源码、依赖元数据及源码伴随包 | 从旧版完整构建镜像迁移时,可使用 `prepare_core_runtime.py` 校验原摘要、移除旧客户端程序目录并生成新的清单。输出必须位于独立目录,再重新准备与新基础摘要匹配的桌面资源及发行材料: ```powershell python -B tools/build_support/prepare_core_runtime.py --runtime-dir 'D:/astrbot-build-inputs/old-runtime' --output-dir 'D:/astrbot-build-inputs/core-runtime' ``` 管理器原生运行器来自 `native/process_runner.c`、`native/terminal_runner.c`。正式构建每次重新编译这两个文件,并校验最终 APK 中的程序摘要。直接用 Gradle 验证时,可先准备独立的原生目录: ```powershell python -B tools/build_support/build_native.py --sdk "$env:ANDROID_HOME" --input-dir 'D:/astrbot-build-inputs/app/src/main/jniLibs' --output-dir '.cache/native-libs' ./gradlew.bat '-PnativeLibsDir=../.cache/native-libs' :app:assembleBootstrapRelease ``` 工具保留按锁定来源准备的 PRoot 与其他库,仅替换管理器自己的两个运行器,输出目录与输入目录必须分开。Linux 使用相同脚本和对应 NDK。发行材料要求见[发行材料](发行材料.md)。 完整构建会自动准备固定版本的官方 Shizuku 原始安装包,以及 `runtime/desktop-packages.lock.json` 锁定的 Ubuntu ARM64 桌面依赖,校验大小及 SHA-256。随后使用干净的基础镜像在临时 Linux 根目录中预先安装、配置依赖,导出仅用于全新初始化的增量资源;原始离线包仍保留,供已有环境修复使用。1.5.0 的基础镜像仅包含 AstrBot 与通用依赖;替换基础镜像时需重新绑定桌面锁、预安装资源及发行材料,不能沿用旧摘要。独立 Linux QQ 仍按需官方下载。资产与预编译程序不进入 Git;对应 Ubuntu 包中的原始版权文件随包保留。直接通过 Gradle 打包完整 APK 时,先准备这些资产并传入路径: ```powershell python -B tools/build_support/prepare_optional_assets.py --output-dir '.cache/optional-assets' python -B tools/build_support/prepare_desktop_snapshot.py --runtime-dir 'runtime/apk-assets/bootstrap/arm64-v8a' --bundle-dir '.cache/optional-assets/desktop-packages/arm64-v8a' --output-dir '.cache/optional-assets/desktop-snapshot/arm64-v8a' ./gradlew.bat '-PbundledRuntime=true' '-PoptionalAssetsDir=../.cache/optional-assets' :app:assembleBundledRelease ``` 预安装资源的生成需要 Linux root、GNU tar、`dpkg-deb` 和 ARM64 执行能力。ARM64 Linux 可直接运行;x86 Linux 需配置 `qemu-user-static` 与 binfmt。Windows 构建入口通过默认 WSL 发行版运行该步骤,需事先准备这些构建工具。临时根目录自动清理,校验通过的输出按基础镜像、依赖清单和构建配方摘要缓存复用;不读取手机数据。首次初始化只向尚未提交的环境释放资源;资源摘要或基础镜像关联不符时停止初始化,避免使用损坏资源。已有环境不应用该资源,桌面软件包状态不满足快速激活条件时使用原有离线准备路径。 目标 Python 与构建机的字节码格式一致时,通用模块缓存由构建机生成,避免在 QEMU 中重复执行编译;不一致时仍使用目标 Python。构建期间临时调整的缓存生成入口在导出前恢复原始内容,资源中保留的是原始程序及生成后的缓存。解压时保留文件时间戳,以便目标 Python 复用缓存。 1.4.1 的预安装资源压缩后约 175 MiB;保留原始离线包后,完整 APK 约 1022 MiB。发布时在下载说明和更新目录的版本说明中写明包体增加及原因,不将本地预安装资源加入 Git,也不替换已公开版本的 APK。 正式发行还需按[发行材料](发行材料.md#源码伴随包)准备桌面版权文本及准确版本源码伴随包,在私有构建配置中指定 `desktopMaterialsDirectory`。它与基础镜像、Python 的源码材料分别记录;不能只更新安装包而沿用旧的许可集合。 Harness 默认不安装。其 npm 依赖锁及独立 Node.js 来源随 App 提供,构建检查来源锁与 npm 锁摘要一致,用户选择安装时再下载。 ## 工程外输入 复制 `docs/examples/local.properties.example` 为根目录的 `local.properties`,按本机位置设置: ```properties runtimeAssetsDir=D:/astrbot-build-inputs/runtime/apk-assets distributionAssetsDir=D:/astrbot-build-inputs/runtime/distribution-assets bootstrapAssetsDir=D:/astrbot-build-inputs/app/src/main/assets nativeLibsDir=D:/astrbot-build-inputs/app/src/main/jniLibs ``` 也可用同名 `-P` 参数覆盖。上述输入、本机配置和构建输出不提交 Git。 ## 一键构建正式包 准备完整输入后,仅首次建立新的签名身份时执行: ```powershell python -B -X utf8 tools/build_release.py --init-signing ``` 已有应用必须恢复原密钥,不能重新生成。Windows 双击根目录 `build.bat`,或运行: ```powershell ./build.bat # 其他系统 python3 -B tools/build_release.py ``` 构建入口先核对签名身份,收集实际发行依赖,生成并校验随包许可材料,再构建 ARM64 Release、运行 lint,并检查 APK 签名、包名、版本、架构和摘要。APK 使用同一长期证书同时提供 v1、v2、v3 签名;缺少任一签名或验证失败时停止导出,`release.json` 记录各签名方案的核验结果。默认流程不依赖本地测试或独立维护工具。校验通过后导出到已忽略的 `dist/`,最多保留最近两份候选 APK,并生成 `output-metadata.json`、`release.json` 和 `SHA256SUMS`。 导出前还会读取最终 APK 内的 Ubuntu 清单与镜像,要求两者各自唯一、清单声明为 ARM64 完整环境且镜像 SHA-256 一致,避免资源合并后的错误被带入发行包。`release.json` 的 `bundledRuntime` 记录包内镜像的架构、字节数和摘要;`nativeBuild` 记录 NDK 版本、原生源码及最终程序摘要,防止旧的预编译缓存覆盖源码修复。 长期签名保存在 `.local/signing/`:`release.p12` 是密钥库,`release.properties` 保存别名和密码,`identity.json` 保存公开证书指纹。整个 `.local/` 已被 Git 忽略。请备份整个签名目录;后续版本必须使用相同包名、相同签名并提高 `appVersionCode`,才能覆盖升级。密钥缺失或指纹变化时脚本停止,不生成替代密钥。 构建路径可通过已忽略的 `.local/build.json` 配置: ```json { "javaHome": "D:/tools/jdk-17", "androidSdk": "D:/tools/Android/Sdk", "gradleUserHome": "D:/build-cache/gradle", "workDirectory": "D:/build-cache/astrbot", "outputDirectory": "D:/build-output/astrbot", "sourceCacheDirectory": "D:/build-inputs/cache", "distributionDirectory": "D:/release-materials/astrbot", "pythonSourceDirectory": "D:/release-materials/python-sources" } ``` 也可使用 `--output-dir`、`--signing-properties` 指定输出和私有签名配置。直接运行 Gradle 时,可用 `-PreleaseSigningProperties=配置文件路径` 或 `ASTRBOT_RELEASE_SIGNING_PROPERTIES` 指定相同配置。没有签名配置时,Gradle 可生成 unsigned Release;一键正式构建则要求长期密钥存在。 公开的 [tools 目录](../tools/README.md)只包含上述打包入口及其直接依赖。许可材料记录的实际待确认事项不会因构建通过而清除。 ## 版本与包名 默认包名 `io.astrbot.android`,版本读取根目录 `gradle.properties`;当前正式参数为 `appVersionName=1.5.0`、`appVersionCode=10051`,可通过同名 `-P` 参数覆盖。开发候选可使用独立的预发布版本参数,正式发布前再统一版本及发行材料。每次公开 APK 更新都提高 versionCode。不同包名不能覆盖安装,同包名覆盖还要求签名一致;更新目录签名见[更新与分发](更新与分发.md)。 ## AstrBot 核心镜像 新构建使用 `runtime/provision-base.sh` 和 `runtime/provision-astrbot.py` 准备 Ubuntu、AstrBot 及通用依赖,使用 `runtime/export-runtime.sh` 导出无业务数据的镜像。原有已验证的构建镜像也可通过 `tools/build_support/prepare_core_runtime.py --runtime-dir INPUT --output-dir OUTPUT` 离线派生:验证输入摘要,流式移除旧内置客户端目录,并记录输入、配方与输出摘要。不能使用手机业务目录制作镜像。 `runtime/projects.lock.json` 只声明 AstrBot。桌面依赖锁和预配置桌面快照须绑定新核心镜像的真实 SHA-256;重新收集对应许可、实际 Android 依赖及源码材料后再进行正式发行构建。Linux QQ 是扩展下载项,不进入基础镜像。