compose-expert

用途

Compose Expert 用于处理 Compose Multiplatform 中跨 Android 与 Desktop 共享 composable 的视觉 UI 模式。适用场景包括：创建或重构共享 UI 组件、判断某段 UI 应放在 commonMain 还是保留平台专属、构建自定义 ImageVector 图标（robohash 模式）、状态管理（remember、derivedStateOf、produceState）、重组优化（@Stable/@Immutable 的视觉用法）、Material3 主题与样式，以及性能相关（惰性列表、图片加载）。

主要能力

共享 UI 组件：Buttons、cards、lists、dialogs、inputs。
状态可视化：Loading、empty、error 状态。
自定义图标：ImageVector 资源（robohash、自定义路径）。
主题工具：颜色计算、样式辅助。
Material3 组件：任何使用 Material 原语的 UI。
状态管理模式：remember、derivedStateOf、produceState。
重组优化：@Immutable、@Stable 的视觉用法。
性能：惰性列表使用 key 参数保持稳定标识、图片加载。

核心理念

默认共享：除非平台专家另有说明，共享 composable 放在 :commonsUI（共享层的 Compose 部分，即 commonMain），无头状态与 ViewModel 留在 :commons。屏幕、导航宿主和底部栏/侧栏/常驻抽屉都归属 commonsUI，并通过 ScreenLayoutSpec / LocalScreenLayout 适配窗口，而非按平台分别实现。

决策框架

仅使用 Material3 原语 → 在 commonMain 共享；
需要平台系统 API → 平台专属；
纯视觉组件且无导航 → 在 commonMain 共享；
需要平台 UX 模式 → 咨询 android-expert 或 desktop-expert。
不确定时默认共享，因为后续拆分比合并更容易。

使用方式与约定

共享 composable 采用“状态下行、事件上行”结构：

@Composable
fun SharedComponent(
    data: DataClass,          // 状态参数（只读）
    isLoading: Boolean,
    onAction: () -> Unit,     // 事件参数（只写）
    modifier: Modifier = Modifier,
    colors: ComponentColors = ComponentDefaults.colors()
) { /* 实现 */ }

约定：modifier 上方为必需的状态/事件参数；modifier 参数用于布局控制；modifier 下方为可选自定义参数。示例 AddButton 使用 OutlinedButton 与共享常量 ActionButtonShape、ActionButtonPadding 保证一致性。

状态管理模式：

remember：跨重组缓存，用于简单 UI 状态（开关、计数器、文本输入）。
derivedStateOf：优化高频变化，输入频繁变化、派生结果很少变化时使用（如滚动位置 → 是否显示按钮）。
produceState：将异步操作、Flow、LiveData、回调转为 Compose 状态，composable 离开组合时协程取消。
状态提升（State Hoisting）：状态上移、事件下传，使 composable 可复用、可测试。

重组优化：对传入 composable 的 data class 标注 @Immutable；使用稳定参数避免不必要的重组。

保持平台专属的内容

入口点：Android Activity/Service、Desktop Window、托盘、菜单栏；
系统集成：文件选择器、通知、分享面板、相机、media3、WebView；
共享 UI 内的平台叶子节点：通过 expect/actual 或由 shim 填充的 slot 实现。

自定义图标

Amethyst 使用 ImageVector 实现多平台图标：通过 roboBuilder DSL 构建，使用 PathData 添加路径，rememberVectorPainter 渲染。优点是纯 Kotlin、无 XML、Android/Desktop/iOS 通用、GPU 加速、类型安全。提供 CustomIcons 缓存模式（getOrPut）。

Material3 主题

全部共享 composable 使用 Material3 保持一致性：颜色取自 MaterialTheme.colorScheme.，字体取自 MaterialTheme.typography.，形状取自 MaterialTheme.shapes.*。附带 isLightTheme() 主题检测辅助（基于背景色亮度），以及 ThemedIcon 示例。

常见视觉模式与组件

状态可视化：LoadingState、EmptyState、ErrorState、ContentList，均位于 commonsUI/commonMain。
Relay 状态指示（Amethyst 模式）：0 个中继 → 红色 + X 图标；1–2 个 → 黄色 + Check；3 个及以上 → 绿色 + Check。
占位模式：通用 PlaceholderScreen + 预设文案的具体包装（如 SearchPlaceholder）。

附带资源

references/shared-composables-catalog.md — 共享 UI 组件完整目录；
references/state-patterns.md — 状态管理模式与可视化示例；
references/icon-assets.md — 自定义 ImageVector 图标模式；
references/rich-text-parsing.md — RichTextParser、UrlParser、GalleryParser、Patterns、MediaContentModels、NIP-92 imeta enrichment；
scripts/find-composables.sh — 查找代码库中所有 @Composable 函数。

常见工作流

创建共享组件：在 commonsUI/src/commonMain/kotlin/.../ui/components/ 创建，仅用 Material3 原语，提升状态，添加 modifier 参数，使用 MaterialTheme，在 Android 与 Desktop 上测试。
转换现有组件：读取 amethyst/ 或 desktopApp/ 中的实现，识别纯视觉逻辑（无平台 API），在 commonsUI/commonMain 中以提升状态创建，替换平台实现，必要时保留平台专属包装。
自定义图标：从设计工具导出 SVG，用 Android Studio 转为 PathData，用 roboBuilder 创建图标函数，动态生成时加缓存，包在 @Composable 中便于使用。

导航与相关技能

导航外壳已共享（ScreenLayoutSpec 按窗口大小选择底部栏、侧栏或常驻抽屉），正随 AppNavigation 迁移至 commonsUI。仅平台叶子节点需委派：Activity/Intent 管线 → android-expert；窗口、托盘、菜单栏、多窗口 → desktop-expert；当前遗留的 desktopApp 侧栏外壳 → desktop-expert（待替换）。相关技能：kotlin-expert（@Immutable 细节、StateFlow、密封类）、android-expert（Android 导航与平台 API）、desktop-expert（Desktop 导航、窗口管理、OS 特性）、kotlin-coroutines（异步模式、Flow 集成）。

限制

本技能聚焦 Compose Multiplatform 的 UI 与状态模式，不覆盖 Kotlin 语言细节、平台导航与系统集成、构建配置，这些分别委派给对应技能。资料未提供收费、价格或平台支持细节。