compose-kotlin-agent-skills

Android & Kotlin — 企业级生产技能（2026）

权威 Android 工程工具包。来自 AnimatedClockJetpacl、Authenticator、RepLock 的真实模式。

不是 Android 库、语音助手技能、设备端 LLM SDK 或 Compose UI 库。 这是面向编码 AI 的 Markdown——克隆到 .cursor/skills/ 或 .claude/skills/。参见 README §「这不是什么」。

元索引： AGENTS.md · CI： python3 scripts/validate_skills.py

子技能（模块化）

技能	路径	范围
架构	skills/android-kotlin-architecture/SKILL.md	MVI/MVVM、模块、用例、UDF
Compose UI	skills/android-kotlin-compose/SKILL.md	UI、边到边、性能、动效
测试	skills/android-kotlin-testing/SKILL.md	Turbine、Compose 测试、Hilt 假对象

2026 工具链——不可妥协

工具	最低版本	备注
Kotlin	2.0+ (2.1.x)	仅使用 K2 编译器——不回退到 K1
AGP	9.0+	内置 Kotlin，新的 DSL 默认值
Compose BOM	2025.05+	Material 3，默认启用强跳过
Navigation	3.x（2.9+ 工件）	类型安全的 NavKey、@Serializable 路由
compileSdk / targetSdk	35+	必须启用边到边
JDK	17	AGP 9 所需

[versions]
kotlin = "2.1.20"
agp = "9.0.0"
compose-bom = "2025.05.00"
navigation = "2.9.0"
room = "2.7.1"
hilt = "2.56.2"
lifecycle = "2.9.0"
coroutines = "1.10.2"

Kotlin 2.x / K2 编译器约束

1. 启用 K2——使用默认的 kotlin.compiler.execution.strategy；Hilt/Room 使用 ksp，而非 kapt。
2. 智能转换——优先使用 when (val x = state) { is Loaded -> ... }，避免不安全的 !!。
3. 密封层级——使用 sealed interface UiState + data object Loading : UiState，确保 when 穷尽所有情况。
4. 使用 @JvmInline value class 定义 ID（@JvmInline value class UserId(val raw: String)）。
5. 对传入 Compose 的 UiState 和 UI 模型添加 @Immutable / @Stable。
6. 对库可选用显式 API——在已发布模块中使用 kotlin { explicitApi() }。
7. 禁止使用 !!，测试中除外，但需添加注释——使用 requireNotNull / 提前返回。
8. 使用 data class 的 copy 更新状态——绝不原地修改 UiState 字段。

sealed interface AccountsUiState {
    data object Loading : AccountsUiState
    data class Ready(
        val accounts: List<AccountUi>,
        val query: String = ""
    ) : AccountsUiState
    data class Error(@StringRes val messageRes: Int) : AccountsUiState
}

MVI 防护规范——仅允许原子状态更新

允许的变更： _state.update { it.copy(...) } 或 _state.update { prev -> ... }。

ViewModel 中禁止：

// BANNED
_state.value = AccountsUiState(...)           // naked assign
_state.value.accounts.add(item)               // mutating list inside state
mutableStateOf / mutableStateListOf in VM      // Compose scope only
viewModelScope.launch { _state.value = ... }  // use update inside launch

必需模式：

class AccountsViewModel @Inject constructor(
    private val repository: AccountsRepository
) : ViewModel() {

    private val _state = MutableStateFlow<AccountsUiState>(AccountsUiState.Loading)
    val state: StateFlow<AccountsUiState> = _state.asStateFlow()

    private val _effects = Channel<AccountsEffect>(Channel.BUFFERED)
    val effects: Flow<AccountsEffect> = _effects.receiveAsFlow()

    fun onEvent(event: AccountsEvent) {
        when (event) {
            AccountsEvent.Refresh -> refresh()
            is AccountsEvent.QueryChanged -> _state.update { current ->
                when (current) {
                    is AccountsUiState.Ready -> current.copy(query = event.query)
                    else -> current
                }
            }
        }
    }

    private fun refresh() {
        viewModelScope.launch {
            _state.update { AccountsUiState.Loading }
            repository.load()
                .onSuccess { list ->
                    _state.update { AccountsUiState.Ready(accounts = list.map { it.toUi() }) }
                }
                .onFailure {
                    _state.update { AccountsUiState.Error(R.string.error_load_failed) }
                }
        }
    }
}

UI 收集：

@Composable
fun AccountsRoute(vm: AccountsViewModel = hiltViewModel()) {
    val state by vm.state.collectAsStateWithLifecycle()
    LaunchedEffect(Unit) {
        vm.effects.collect { effect -> /* one-shot: nav, snackbar */ }
    }
    AccountsScreen(state = state, onEvent = vm::onEvent)
}

Navigation 3 + 边到边

@Serializable data object Home
@Serializable data class Detail(val id: String)

@Composable
fun AppNavHost(navController: NavHostController = rememberNavController()) {
    NavHost(navController, startDestination = Home) {
        composable<Home> { HomeScreen(onOpen = { navController.navigate(Detail(it)) }) }
        composable<Detail> { entry ->
            val route = entry.toRoute<Detail>()
            DetailScreen(id = route.id)
        }
    }
}

• 路由 = @Serializable 类型，而非字符串路径
• 在导航参数中传递 ID——在目标 ViewModel 中获取模型
• 在 Activity 中调用 enableEdgeToEdge()——参见 Compose 子技能

深入了解：references/07-navigation.md

禁止的反模式——AI 幻觉速查

包含错误/正确配对及行号的完整表格：references/00-banned-antipatterns.md

在审查任何 Agent 生成的 Kotlin 代码前先加载。Compose 审查清单：skills/android-kotlin-compose/SKILL.md § 审查模式。

参考路由

文件	主题
references/00-banned-antipatterns.md	禁用模式总表——审查时首先加载
references/01-architecture.md	Clean Arch、MVVM、模块
references/02-compose-ui.md	组合、M3、主题
references/03-animations.md	动效、Canvas
references/04-coroutines-flow.md	Flow、错误、取消
references/05-hilt-di.md	DI、作用域
references/06-room-db.md	Room、离线优先
references/07-navigation.md	Nav 3、深层链接
references/08-kmp-cmp.md	KMP、expect/actual
references/09-networking.md	Ktor、JWT
references/10-performance.md	重组、Coil、性能分析
references/11-testing.md	Turbine、UI 测试
references/12-camera-mlkit.md	CameraX、姿势
references/13-release-checklist.md	R8、Play Store
references/14-datastore.md	DataStore、SP 迁移、加密
references/15-paging3.md	Paging 3、RemoteMediator、asState()
references/16-coil-image.md	Coil 3.4、AsyncImage、缓存
references/17-accessibility.md	TalkBack、语义、WCAG
references/18-gradle-build-logic.md	约定插件、KSP、R8、基线配置文件
references/19-xml-to-compose-migration.md	XML → Compose、RxJava → Flow

平台

目标平台（文档所讲内容）： Android · Kotlin Multiplatform · Compose Multiplatform 宿主平台（阅读文档的环境）： macOS · Linux · Windows——AI Agent 运行的任何环境 Agent 兼容性： 27 个安装指南 → agents/README.md

仓库：https://github.com/haidrrrry/compose-kotlin-agent-skills

强制默认规范（摘要）

• 字符串： stringResource / @StringRes——UI 文本一律不得硬编码
• 状态： ViewModel StateFlow + _state.update { }
• UI： 无状态可组合项，modifier 作为第一个可选参数
• 列表： LazyColumn + keys + contentType
• DI： @HiltViewModel + 构造函数注入
• 测试： Fake + Turbine——参见测试子技能

PR 前验证

python3 scripts/validate_skills.py --strict

反驳借口

借口	实际情况
“UiState 小题大做”	data object Loading 只需一行
“之后再加 Keys”	现在就会导致滚动／焦点异常
“原型阶段跳过 Repository”	原型也会发布
“collectAsState 没问题”	后台收集器会耗费电量

示例

路径	模式
examples/animated-clock/	Canvas、rotate()、粒子
examples/authenticator/	Room Flow、combine、CompositionLocal 主题