svharness 0.8.0

package/templates/android-compose/skeleton/agent-env/skills/harness-compose-ui/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: harness-compose-ui
+description: 构建 Jetpack Compose UI 时的最佳实践指引，覆盖 Composable 设计、性能优化、Modifier 规范、列表/网格模式和 Material 3 主题。刚性约束由 rules 加载，本技能聚焦实现模式与配方。
+---
+
+# Jetpack Compose UI — 实现指引
+
+## 概述
+
+本技能指导如何构建高性能、可复用、可测试的 Composable 组件。
+
+> **刚性约束已由 rules 加载，本技能不再重复。** 详见：
+> - `harness-compose-mandatory` — Modifier 位置、key、稳定类型、副作用约束
+> - `harness-mvi-layering` — 容器层/纯 UI 层分离、Reducer 纯函数约束
+
+---
+
+## Composable 设计
+
+### 状态提升（单向数据流）
+
+Composable 必须无状态，状态向下流动，事件向上流动：
+
+```kotlin
+@Composable
+fun NameInput(
+    name: String,                    // 状态向下流动
+    onNameChange: (String) -> Unit,  // 事件向上流动
+    modifier: Modifier = Modifier
+) {
+    TextField(
+        value = name,
+        onValueChange = onNameChange,
+        label = { Text("Name") },
+        modifier = modifier
+    )
+}
+```
+
+屏幕级 Composable 从 ViewModel 获取状态并向下传递：
+
+```kotlin
+@Composable
+fun UserScreen(viewModel: UserViewModel = hiltViewModel()) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    UserContent(
+        uiState = uiState,
+        onNameChange = viewModel::updateName,
+        onSave = viewModel::saveUser
+    )
+}
+```
+
+### 插槽 API
+
+```kotlin
+@Composable
+fun CustomScaffold(
+    topBar: @Composable () -> Unit = {},
+    bottomBar: @Composable () -> Unit = {},
+    content: @Composable (PaddingValues) -> Unit
+) {
+    Scaffold(topBar = topBar, bottomBar = bottomBar, content = content)
+}
+```
+
+更多 API 设计模式见 [references/composable-api-guide.md](references/composable-api-guide.md)。
+
+---
+
+## 性能优化
+
+### 高效重组
+
+```kotlin
+// 列表项使用 key
+@Composable
+fun UserList(users: List<User>) {
+    LazyColumn {
+        items(items = users, key = { it.id }) { user ->
+            UserItem(user)
+        }
+    }
+}
+
+// derivedStateOf 避免不必要的重组
+@Composable
+fun FilteredList(items: List<Item>, query: String) {
+    val filtered by remember(items, query) {
+        derivedStateOf { items.filter { it.name.contains(query, ignoreCase = true) } }
+    }
+    LazyColumn { items(filtered) { item -> ItemRow(item) } }
+}
+
+// Lambda 稳定性：优先方法引用
+@Composable
+fun GoodScreen(viewModel: MyViewModel) {
+    MyButton(onClick = viewModel::doAction)  // 稳定引用
+}
+```
+
+更多性能配方见 [references/performance-recipes.md](references/performance-recipes.md)。
+
+---
+
+## 列表与网格
+
+```kotlin
+// 自适应网格
+@Composable
+fun ProductGrid(products: List<Product>) {
+    LazyVerticalGrid(
+        columns = GridCells.Adaptive(minSize = 160.dp),
+        contentPadding = PaddingValues(16.dp),
+        horizontalArrangement = Arrangement.spacedBy(16.dp),
+        verticalArrangement = Arrangement.spacedBy(16.dp)
+    ) {
+        items(products, key = { it.id }) { product -> ProductCard(product) }
+    }
+}
+
+// 粘性标题
+@Composable
+fun ContactList(contacts: Map<Char, List<Contact>>) {
+    LazyColumn {
+        contacts.forEach { (initial, contactsForInitial) ->
+            stickyHeader {
+                Text(
+                    text = initial.toString(),
+                    modifier = Modifier.fillMaxWidth().background(MaterialTheme.colorScheme.surface).padding(16.dp),
+                    style = MaterialTheme.typography.titleMedium
+                )
+            }
+            items(contactsForInitial, key = { it.id }) { contact -> ContactItem(contact) }
+        }
+    }
+}
+```
+
+---
+
+## Material 3 主题
+
+```kotlin
+@Composable
+fun AppTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    content: @Composable () -> Unit
+) {
+    val colorScheme = when {
+        darkTheme -> darkColorScheme(primary = Purple80, secondary = PurpleGrey80, tertiary = Pink80)
+        else -> lightColorScheme(primary = Purple40, secondary = PurpleGrey40, tertiary = Pink40)
+    }
+    MaterialTheme(colorScheme = colorScheme, typography = Typography, content = content)
+}
+
+// 使用主题值（禁止硬编码）
+@Composable
+fun ThemedCard() {
+    Card(
+        colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.surfaceVariant)
+    ) {
+        Text(
+            text = "Themed content",
+            style = MaterialTheme.typography.bodyLarge,
+            color = MaterialTheme.colorScheme.onSurfaceVariant
+        )
+    }
+}
+```
+
+---
+
+## 反模式速查
+
+| 反模式 | 正确做法 |
+|--------|---------|
+| `viewModel.loadData()` 在组合体内直接调用 | `LaunchedEffect(Unit) { viewModel.loadData() }` |
+| `remember { mutableStateOf(initial) }` 不带 key | `remember(initial) { mutableStateOf(initial) }` |
+| `items.filter { ... }` 直接在组合体内 | `remember(items) { derivedStateOf { items.filter { ... } } }` |
+| `MutableList` 作为 Composable 参数 | 使用 `List` 不可变接口 |
+
+---
+
+## 必须遵守的约束规则
+
+> rules 引用路径：`../rules/<rule-name>.mdc`
+
+- harness-compose-mandatory
+- harness-mvi-layering
+- harness-hilt-injection
+- harness-coroutines-scope

package/templates/android-compose/skeleton/agent-env/skills/harness-compose-ui/references/composable-api-guide.md

@@ -0,0 +1,123 @@
+# Composable API 设计指南
+
+## 参数顺序规范
+
+```kotlin
+@Composable
+fun CustomCard(
+    title: String,                     // 1. 必需数据参数
+    subtitle: String = "",             // 2. 可选数据参数
+    modifier: Modifier = Modifier,     // 3. modifier（第一个可选参数）
+    onClick: () -> Unit = {},          // 4. 事件回调
+    content: @Composable () -> Unit    // 5. 插槽内容（最后）
+) { ... }
+```
+
+## Modifier 规范
+
+```kotlin
+// ✅ 正确：modifier 作为第一个可选参数
+@Composable
+fun FeatureCard(
+    title: String,
+    modifier: Modifier = Modifier,
+    onClick: () -> Unit = {}
+) {
+    Card(modifier = modifier.clickable(onClick = onClick)) {
+        Text(text = title, modifier = Modifier.padding(16.dp))
+    }
+}
+
+// ❌ 错误：modifier 不在第一个可选位置
+@Composable
+fun FeatureCard(
+    modifier: Modifier,
+    title: String
+) { ... }
+```
+
+**Modifier 应用顺序**：`padding().clickable()` 与 `clickable().padding()` 不同。通常在点击监听器之后应用影响布局的修饰符。
+
+## 通用组件模式
+
+### 功能卡片
+
+```kotlin
+@Composable
+fun FeatureCard(
+    title: String,
+    icon: Painter,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Card(
+        modifier = modifier.clickable(onClick = onClick).padding(8.dp),
+        colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.surface)
+    ) {
+        Column(
+            modifier = Modifier.padding(16.dp),
+            horizontalAlignment = Alignment.CenterHorizontally
+        ) {
+            Icon(painter = icon, contentDescription = title)
+            Text(text = title, style = MaterialTheme.typography.bodyMedium)
+        }
+    }
+}
+```
+
+### 状态响应式组件
+
+```kotlin
+@Composable
+fun StatusPanel(
+    status: LoadStatus,
+    modifier: Modifier = Modifier,
+    content: @Composable () -> Unit
+) {
+    when (status) {
+        is LoadStatus.Loading -> LoadingIndicator(modifier = modifier)
+        is LoadStatus.Success -> content()
+        is LoadStatus.Error -> ErrorMessage(status.message, modifier = modifier)
+    }
+}
+```
+
+### 切换组件
+
+```kotlin
+@Composable
+fun SettingSwitch(
+    title: String,
+    checked: Boolean,
+    onCheckedChange: (Boolean) -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .padding(horizontal = 16.dp, vertical = 8.dp),
+        horizontalArrangement = Arrangement.SpaceBetween,
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Text(text = title, style = MaterialTheme.typography.bodyLarge)
+        Switch(checked = checked, onCheckedChange = onCheckedChange)
+    }
+}
+```
+
+## 设计系统文件组织
+
+```
+ui/
+├── components/           ← 通用可复用组件
+│   ├── FeatureCard.kt
+│   ├── StatusPanel.kt
+│   └── SettingSwitch.kt
+├── theme/               ← 主题定义
+│   ├── Color.kt
+│   ├── Type.kt
+│   └── Theme.kt
+└── screens/             ← 页面级 Composable
+    ├── HomeScreen.kt
+    └── SettingsScreen.kt
+```

package/templates/android-compose/skeleton/agent-env/skills/harness-compose-ui/references/performance-recipes.md

@@ -0,0 +1,97 @@
+# Compose 性能优化配方
+
+## 1. LazyColumn key 优化
+
+```kotlin
+// ❌ 无 key：列表项变更时全量重组
+LazyColumn {
+    items(users) { user -> UserItem(user) }
+}
+
+// ✅ 有 key：只有变更项重组
+LazyColumn {
+    items(items = users, key = { it.id }) { user -> UserItem(user) }
+}
+```
+
+**影响**：带 key 时 Compose 可以精准识别哪项变了，避免不必要的重组和动画重置。
+
+## 2. derivedStateOf 避免级联重组
+
+```kotlin
+// ❌ 每次 listState 变化都重组
+val showButton = listState.firstVisibleItemIndex > 5
+
+// ✅ 只在阈值跨越时触发
+val showButton by remember {
+    derivedStateOf { listState.firstVisibleItemIndex > 5 }
+}
+```
+
+## 3. Lambda 稳定性
+
+```kotlin
+// ❌ 每次重组创建新 lambda，子组件无法跳过
+UserList(onClick = { user -> selectUser(user) })
+
+// ✅ 方法引用，稳定不变
+UserList(onClick = viewModel::selectUser)
+
+// ✅ remember 包装
+val onClick = remember(viewModel) { { user: User -> viewModel.selectUser(user) } }
+```
+
+## 4. 不稳定参数稳定化
+
+```kotlin
+// ❌ MutableList 不稳定
+@Composable
+fun ItemList(items: MutableList<Item>) { ... }
+
+// ✅ 使用不可变 List
+@Composable
+fun ItemList(items: List<Item>) { ... }
+
+// ✅ 对自定义类添加 @Stable 注解
+@Stable
+data class UiState(val items: List<Item> = emptyList(), val isLoading: Boolean = false)
+```
+
+## 5. 读取时机优化
+
+```kotlin
+// ❌ 过早读取：Lambda 外部读取状态，Lambda 每次都被重建
+val color = MaterialTheme.colorScheme.primary
+Box(modifier = Modifier.background(color).clickable { /* ... */ })
+
+// ✅ 延迟读取：Lambda 内部读取，只在需要时触发
+Box(modifier = Modifier.background(MaterialTheme.colorScheme.primary).clickable { /* ... */ })
+```
+
+## 6. 避免向后写入
+
+```kotlin
+// ❌ 向后写入：组合期间修改状态
+@Composable
+fun BadExample() {
+    var text by remember { mutableStateOf("") }
+    text = "computed"  // 组合期间写入，触发额外重组
+    Text(text)
+}
+
+// ✅ 正确：使用派生状态
+@Composable
+fun GoodExample() {
+    val text by remember { derivedStateOf { "computed" } }
+    Text(text)
+}
+```
+
+## 7. remember 与 rememberSaveable 选择
+
+| 场景 | 选择 | 原因 |
+|------|------|------|
+| 纯计算缓存 | `remember` | 无需跨配置变更保持 |
+| 用户输入状态 | `rememberSaveable` | 屏幕旋转后恢复 |
+| 滚动位置 | `rememberSaveable`（Saver） | 配置变更后恢复位置 |
+| 临时动画状态 | `remember` | 动画重新启动可接受 |

package/templates/android-compose/skeleton/agent-env/skills/harness-compose-ui/references/state-patterns.md

@@ -0,0 +1,93 @@
+# 状态管理模式集
+
+## ViewModel + StateFlow（MVI 模式）
+
+```kotlin
+@HiltViewModel
+class UserViewModel @Inject constructor(
+    private val userRepository: UserRepository
+) : BaseViewModel<UserContract.State, UserContract.Event, UserContract.Effect, UserContract.Intent>() {
+
+    override val initialState = UserContract.State()
+
+    override val reducer = Reducer<UserContract.State, UserContract.Event> { state, event ->
+        when (event) {
+            is Event.NameChanged -> state.copy(name = event.name)
+            is Event.Loaded -> state.copy(isLoading = false, user = event.user)
+            is Event.Error -> state.copy(isLoading = false, error = event.message)
+        }
+    }
+
+    override fun handleIntent(intent: UserContract.Intent) {
+        when (intent) {
+            is Intent.UpdateName -> dispatch(Event.NameChanged(intent.name))
+            is Intent.Save -> { dispatch(Event.Loading); /* useCase call */ }
+        }
+    }
+}
+```
+
+## remember / rememberSaveable
+
+```kotlin
+// remember：重组时保持状态，配置变更后丢失
+var count by remember { mutableStateOf(0) }
+
+// rememberSaveable：配置变更后仍保持
+var query by rememberSaveable { mutableStateOf("") }
+
+// remember 带 key：key 变化时重新初始化
+var count by remember(userId) { mutableStateOf(0) }
+```
+
+## derivedStateOf
+
+```kotlin
+// 当状态频繁变化但 UI 只需响应阈值时
+val showScrollToTop by remember {
+    derivedStateOf { listState.firstVisibleItemIndex > 5 }
+}
+
+// 计算型状态，依赖变化时才重新计算
+val filteredItems by remember(items, query) {
+    derivedStateOf { items.filter { it.name.contains(query, ignoreCase = true) } }
+}
+```
+
+## collectAsStateWithLifecycle
+
+```kotlin
+// 在 Compose 中收集 ViewModel 状态（生命周期感知）
+@Composable
+fun MyScreen(viewModel: MyViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    MyContent(state = state, onIntent = { viewModel.process(it) })
+}
+```
+
+## CompositionLocal
+
+```kotlin
+// 定义
+val LocalSnackbarHost = compositionLocalOf<SnackbarHostState> {
+    error("No SnackbarHostState provided")
+}
+
+// 提供
+@Composable
+fun App() {
+    val snackbarHostState = remember { SnackbarHostState() }
+    CompositionLocalProvider(LocalSnackbarHost provides snackbarHostState) {
+        Content()
+    }
+}
+
+// 消费
+@Composable
+fun SomeDeepComponent() {
+    val snackbarHostState = LocalSnackbarHost.current
+    // 使用 snackbarHostState
+}
+```
+
+**注意**：CompositionLocal 适用于隐式传递的 UI 基础设施（主题、SnackbarHost），不适用于业务数据。

package/templates/android-compose/skeleton/agent-env/skills/harness-kotlin-coroutines/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: harness-kotlin-coroutines
+description: 在使用 Kotlin 协程、Flow、StateFlow 实现异步操作，或在 Android 应用中管理并发时使用。覆盖结构化并发、调度器、Flow 操作符、防抖节流和异常处理。刚性约束由 rules 加载，本技能聚焦实现模式。
+---
+
+# Kotlin 协程 — 实现指引
+
+## 概述
+
+Android 中使用 Kotlin 协程和 Flow 的异步编程模式。
+
+> **刚性约束已由 rules 加载，本技能不再重复。** 详见：
+> - `harness-coroutines-scope` — GlobalScope 禁用、viewModelScope、runBlocking 禁用、collectAsStateWithLifecycle、repeatOnLifecycle
+> - `harness-hilt-injection` — 调度器注入约束
+
+---
+
+## 结构化并发
+
+```kotlin
+// 并行操作，全部完成或全部失败
+suspend fun loadDashboard(): Dashboard = coroutineScope {
+    val userDeferred = async { userRepository.getUser() }
+    val ordersDeferred = async { orderRepository.getOrders() }
+    Dashboard(user = userDeferred.await(), orders = ordersDeferred.await())
+}
+
+// 带超时
+suspend fun loadWithTimeout(): Data = withTimeout(5000) { api.fetchData() }
+
+// 或超时返回 null
+suspend fun loadOrNull(): Data? = withTimeoutOrNull(5000) { api.fetchData() }
+```
+
+## 调度器
+
+```kotlin
+// IO — 网络、数据库、文件
+withContext(Dispatchers.IO) { database.query() }
+
+// Default — CPU 密集型
+withContext(Dispatchers.Default) { expensiveComputation(data) }
+
+// 注入调度器（推荐）
+class MyRepository @Inject constructor(
+    @DispatcherIO private val ioDispatcher: CoroutineDispatcher
+) {
+    fun getData(): Flow<Data> = flow { emit(api.fetchData()) }.flowOn(ioDispatcher)
+}
+```
+
+## Flow 操作符
+
+```kotlin
+// 转换 + 去重
+userRepository.getUsers()
+    .map { users -> users.filter { it.isActive } }
+    .distinctUntilChanged()
+    .collect { activeUsers -> updateUI(activeUsers) }
+
+// 组合多个 Flow
+val combined = combine(userFlow, settingsFlow) { user, settings -> Pair(user, settings) }
+
+// 搜索模式
+searchQuery
+    .debounce(300)
+    .flatMapLatest { query -> if (query.isEmpty()) flowOf(emptyList()) else searchRepository.search(query) }
+    .collect { results -> updateResults(results) }
+
+// 带指数退避的重试
+api.fetchData().retry(3) { cause ->
+    if (cause is IOException) { delay(1000L * (2.0.pow(retryCount)).toLong()); true } else false
+}
+```
+
+## 异常处理
+
+```kotlin
+// runCatching 模式
+suspend fun safeApiCall(): Result<User> = runCatching { api.getUser() }
+
+// ViewModel 中处理
+fun loadUser() {
+    viewModelScope.launch {
+        safeApiCall()
+            .onSuccess { user -> _uiState.update { it.copy(data = user) } }
+            .onFailure { error -> _uiState.update { it.copy(error = error.message) } }
+    }
+}
+
+// SupervisorJob：子任务独立失败
+class MyViewModel : ViewModel() {
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
+    fun loadMultiple() {
+        scope.launch { userRepository.getUser() }     // 失败不影响另一个
+        scope.launch { orderRepository.getOrders() }
+    }
+}
+```
+
+## 防抖与节流
+
+```kotlin
+// Compose 中的防抖搜索
+@Composable
+fun SearchField(onSearch: (String) -> Unit) {
+    var query by remember { mutableStateOf("") }
+    LaunchedEffect(query) {
+        delay(300)  // 防抖
+        if (query.isNotEmpty()) onSearch(query)
+    }
+    TextField(value = query, onValueChange = { query = it })
+}
+
+// ViewModel 中的 StateFlow 搜索
+val searchResults = _searchQuery
+    .debounce(300)
+    .distinctUntilChanged()
+    .flatMapLatest { query -> searchRepository.search(query) }
+    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
+```
+
+## 取消处理
+
+```kotlin
+suspend fun downloadFile(url: String): ByteArray = withContext(Dispatchers.IO) {
+    val connection = URL(url).openConnection()
+    connection.inputStream.use { input ->
+        val buffer = ByteArrayOutputStream()
+        val data = ByteArray(4096)
+        while (true) {
+            ensureActive()  // 检查取消
+            val count = input.read(data)
+            if (count == -1) break
+            buffer.write(data, 0, count)
+        }
+        buffer.toByteArray()
+    }
+}
+
+// 可取消的轮询 Flow
+fun pollData(): Flow<Data> = flow {
+    while (currentCoroutineContext().isActive) {
+        emit(api.fetchData())
+        delay(5000)
+    }
+}
+```
+
+## 反模式速查
+
+| 反模式 | 正确做法 |
+|--------|---------|
+| `GlobalScope.launch { ... }` | `viewModelScope.launch { ... }` |
+| `runBlocking { api.fetch() }` | `viewModelScope.launch { withContext(IO) { api.fetch() } }` |
+| `lifecycleScope.launch { flow.collect {} }` | `repeatOnLifecycle(STARTED) { flow.collect {} }` |
+| 每次调用创建新 Flow | `stateIn(viewModelScope, WhileSubscribed(5000), initial)` |
+
+---
+
+## 必须遵守的约束规则
+
+> rules 引用路径：`../rules/<rule-name>.mdc`
+
+- harness-coroutines-scope
+- harness-hilt-injection
+- harness-mvi-layering