Android Starter

修订记录

修订时间（CST）	修订人	修订说明
2026-09-16	whisper	将 GitHub Endpoint 配置入口迁入应用 TOML
2026-09-16	whisper	直接复用框架占位地址并明确 Endpoint 装配入口
2026-09-15	whisper	使用接口级拦截器演示 GitHub 请求配置
2026-09-14	whisper	同步三 Tab、多 Activity 与 Project 模块结构
2026-09-11	whisper	明确 Foundation 共享主题职责并补充模块文档入口
2026-09-11	whisper	增加 App 图标主题和示例规划文档入口
2026-09-01	whisper	明确 Kit 定位和设计文档入口
2026-08-31	whisper	统一 Prism 文档入口
2026-08-31	whisper	区分项目规范与智能体规则
2026-08-28	whisper	建立开源仓库入口文档

Android Starter 是一个持续演进的 Android 多模块起始工程. 它提供通用架构, 应用业务基座, Android 工具, 日志, 路由, 能力发现, Dao 注册和可选构建配置能力, 用于快速建立新的 Android 应用, 而不是绑定具体业务的成品应用.

项目当前仍处于开发阶段. 公共 API 和模块边界可能继续调整; 用于正式项目时建议固定到经过验证的 commit 或 release tag.

设计边界

• app 是组合根, 负责选择环境, Endpoint 和应用级实现.
• architecture 只提供通用技术抽象, 不解释具体业务响应, 错误码, Meta 或域名.
• foundation 承载应用业务基座中的响应映射, Meta 建模, 领域转换和跨页面共享设计系统.
• 下层模块不读取 app BuildConfig, 也不感知 product flavor.
• Prism, Aster 和 Habitat 通过独立插件接入, 不应成为所有项目的隐式前提.

模块

模块	职责
app	示例应用和最终装配入口
feature/function	通用 View 与功能演示页面
feature/project	GitHub 项目概览、下拉刷新与 Room/Habitat 缓存
architecture	Business 管线, Architecture UI 和网络创建骨架
foundation	应用业务基座, 共享主题及 architecture 抽象的应用级实现
kit	业务无关的 Android 工具, 扩展和通用 UI 组件
quill	可插拔, 延迟构建消息的日志能力
aster	Activity 路由和 Capability 发现的 runtime / compiler
aster-gradle-plugin	Aster 的 Android Variant 与 Manifest 接入
habitat	Dao 注册和发现的 runtime / compiler
habitat-gradle-plugin	Habitat 的 Android Variant 与 Manifest 接入
build-logic	可选 Prism TOML 应用配置插件

构建基线

维度	当前基线
Android Gradle Plugin	9.2.1
Gradle Wrapper	9.6.1
Android compileSdk / targetSdk	37 / 37
Android minSdk	24
Gradle 运行 JDK	21
Java / Kotlin JVM target	17
JVM 模块 Kotlin	2.4.10
KSP	2.3.10

推荐使用支持上述版本的 Android Studio, 并安装 Android SDK 37. 其它版本组合没有被本仓库声明为已验证 基线.

快速开始

在仓库根目录执行:

./gradlew :app:assembleDebug

开始实际应用开发前至少完成以下调整:

1. 修改 app-config.toml 中的 applicationId 和应用所需的 Endpoint 配置. 示例通过 buildConfig.GITHUB_API_ENDPOINT 配置 GitHub 地址, 由 Prism 生成 app 的 BuildConfig 后注入路由拦截器. 默认 Retrofit 直接使用框架的 ROUTING_PLACEHOLDER_BASE_URL, 不需要重复配置 API_HOST. 这些值在构建时确定, 修改后需要重新构建安装; 不作为运行时环境切换入口.
2. 修改 app/build.gradle.kts 中的 namespace, 并迁移 com.whisper.starter 示例包.
3. 调整应用名称, 图标, 主题, 版本和签名配置.
4. 根据项目需要保留或移除 Prism, Aster, Habitat, Quill, Kit 等可选能力.

Prism 的配置契约和完整退出步骤见 Prism 使用文档.

验证

当前公共模块和示例 app 可以使用以下命令完成主要验证:

./gradlew \
  :architecture:testDebugUnitTest \
  :architecture:lintDebug \
  :architecture:bundleDebugAar \
  :foundation:testDebugUnitTest \
  :app:compileDebugKotlin \
  --no-configuration-cache

涉及 Aster, Habitat, Prism, Quill 或 Kit 时, 还应按照对应开发文档扩大测试范围.

文档

• App: 设计, 开发, 使用.
• Function: 设计, 开发, 使用.
• Project: 设计, 开发, 使用.
• Foundation: 设计, 开发, 使用.
• Architecture: 设计, 开发, 使用.
• Network: 设计, 开发, 使用.
• Prism: 设计, 开发, 使用.
• Aster: 设计, 开发, 使用.
• Habitat: 设计, 开发, 使用.
• Quill: 设计, 开发, 使用.
• Kit: 设计, 开发, 使用.

所有维护者遵守 代码规范 和 开发规范. 使用智能体维护项目时, 还需遵守智能体专属的 执行规范.

许可证

本项目使用 Apache License 2.0. 该许可证允许个人和组织免费使用, 修改, 商用, 再许可和分发源码或 二进制产物, 同时要求分发者保留许可证及必要的归属说明, 并标明对文件所做的修改.

本项目按 "AS IS" 提供, 不提供任何明示或默示保证. 在适用法律允许的范围内, 作者和贡献者不对使用或无法使用 本项目造成的损失承担责任. 具体权利, 义务, 免责和责任限制以英文许可证原文为准.

Copyright 2025-2026 whisper.