Android 环境、构建与交付

安装门槛

Android Studio 是正常安装软件，由用户运行已核验官方安装包。安装包放用户普通下载目录，不放仓库或 Codex bin。准备好后停止等待用户安装，不自动运行安装器。安装时建议采用默认位置，首次向导安装 Android SDK；不必创建项目，也不必先下载模拟器或 NDK。

首次完成后记录实际安装版本、JDK、SDK、Build Tools、Kotlin、Compose、AGP 与 Gradle 的兼容组合，锁入版本目录、Wrapper 和依赖校验文件。安装位置用环境探测／local.properties，不写到可提交源码。官方参考：

工程与路径

源码位于相邻 安卓程序源代码/，模块 androidApp、sharedCore、sharedUi。在 Android Studio 打开工程根，不分别打开子模块。先验证中文和空格路径；若 Android 工具拒绝该路径，通过受保护的仓库外 ASCII 构建目录同步源码并执行，结果回收到交付目录。同步只包含源码及明确资源，不复制私有登记、密钥、缓存或 .git；脚本记录源摘要，不覆盖用户目录。

已安装工具链：Android Studio Quail 4 Patch 1（用户确认中文）、JBR 25.0.3、SDK 37；工程固定 Gradle 9.5.0、AGP 9.3.1、Kotlin 2.4.20、Compose 1.12.1。Wrapper 使用官方发行地址和 SHA-256。首次 :androidApp:assembleDebug 与 :sharedCore:jvmTest 已在隔离 ASCII 路径通过；这只是骨架及协议验证，不等于功能验收。lint 与真实 BLE 已有通过记录，具体覆盖范围见测试结果归档。

在仓库根执行下列命令，参数替换为本机实际目录，不把替换后的路径提交：

python "移动端相关内容/安卓app/构建与发布/build_android.py" --work-root "<受保护临时目录的ASCII路径>" --jdk "<Android Studio的jbr目录>" --sdk "<Android SDK目录>"

脚本每次创建独立 qms-build-* 子目录，只复制工程源码，忽略 build、.gradle、.kotlin、local.properties。默认使用 Wrapper；可用 --gradle 指定已核验的同版本 Gradle，避免重复下载。默认运行 JVM 测试和 assembleDebug，可在末尾显式传任务列表。保留构建目录用于查看测试报告和 androidApp/build/outputs/apk/debug/androidApp-debug.apk；验证后只清理本次明确目录。Android 调试签名沿用用户默认 Android 密钥目录，不复制到源码或隔离工程。

路径实测：AGP 默认拒绝非 ASCII 路径；启用 android.overridePathCheck=true 后编译继续，但当前 JBR／Gradle 下 JVM 测试出现类加载失败。在 ASCII 隔离目录同一测试通过，故当前使用该回退。2026-09-25 已在全新且包含空格的 ASCII 构建根目录重新执行全部 92 个任务，JVM 测试及两个 debug APK 均成功；保留中文源码位置。

APK 与签名

应用名“奇妙小屏幕”，applicationId 为 org.qimiaoscreen.controller，minSdk 26，首版版本 0.1.0。
仅 debug 签名，沿用本机调试密钥并记录证书摘要（不记录私钥）。正式签名只有用户明确命令才配置或执行。
调试签名更换可能无法覆盖安装；不能自动卸载并清除用户配置来掩盖。需要时先报告原因。
App versionCode 独立递增，设备版本／协议版本分别登记，不能因设备部署自动提升 App 版本。
每次交付放 交付包/<App版本>-<versionCode>/：APK、SHA256SUMS、manifest.json、README.md。manifest 包含 App／协议／兼容设备信息、源摘要、工具链版本和签名证书摘要，不包含本机路径或测试机标识。
APK 与发布元数据保留在私有 Git 仓库，需要时沿用 Git LFS；构建缓存、SDK、真实登记、调试及正式签名私钥都不提交。
本任务不导出核桃派 IMG／OTA；设备功能时间按根规则更新，设备发布版本不因普通部署占号。

交付前检查

从隔离目录依文档重新构建并验证；完成相关测试、协议互操作和真实 BLE 联调；运行根仓库卫生检查。交付说明准确区分通过、未验证和不适用。第二台手机验收 APK 放到同一清晰可找到的交付目录，用户安装后再进行实机互斥测试。

可重复打包

python "移动端相关内容/安卓app/构建与发布/package_debug.py" --build "<本轮隔离工程目录>" --sdk "<Android SDK目录>"

运行前将 JAVA_HOME 指向正常安装的 Android Studio jbr。脚本逐文件核对隔离工程与当前源码的 SHA-256，调用 Build Tools 36.0.0 的 apksigner 验证 Android Debug 证书，创建版本独立目录，保存 APK、摘要、工具链和源文件清单。已存在交付目录拒绝覆盖。结果默认标为开发验证包，必须结合测试报告说明验收范围，不用打包成功替代验收。versionCode 2 包含本轮连接清理和界面信息补充，可覆盖同证书的 code 1。

本轮 App 0.2.0 / versionCode 3 为四栏界面及设备记忆优化，仍仅 debug 签名。关于页显示本次 Gradle 构建日期（北京时间），不修改设备发布版本。

构建排障与测试复盘

手动调用隔离工程 Wrapper 时，每个新 shell 都须明确使用已登记的 JDK/SDK（JAVA_HOME/ANDROID_HOME）；前一工具调用的进程环境不会自动传到下一次调用。缺少 SDK location 时先检查环境，不重复下载工具、不改动中文源码位置。

Gradle Kotlin DSL 里 java 可能被插件扩展名遮蔽；构建日期实现显式 import ZonedDateTime、ZoneId、DateTimeFormatter，避免直接以 java.time... 引用引发解析错误。日期仍使用北京时间，不通过硬编码本机路径解决。

Python 在 Windows 缺少 IANA tzdata 时，固定北京时间时间戳可使用标准库 timezone(timedelta(hours=8))；这一方法只适用于明确要求的固定 UTC+08:00 时间，不当作任意地区夏令时转换方案，也不因该情况自动新增依赖。

打包前重新核对隔离源码、实际 APK、构建日期和签名摘要；测试源码调整也要同步隔离工程，不能测试旧测试 APK。测试/构建遇到的新问题在完成后更新相应文档并在最终反馈说明，具体输入和真机排障见测试排障指南。

Android 0.2.1 / versionCode 4：顶栏长文本循环、连接条目断开／扫描保留、居中预览；仅debug签名。交付和本轮覆盖范围见交付包0.2.1-4及测试结果归档2026-09-27_界面细节优化。

6.7 KiB Raw Blame History Unescape Escape