企业官网建设流程全解析

• AI 技能
• AI 插件

本文以 android-dev 技能 的详细指南 detailed-guide.md 为骨架，系统讲解生产级 Android 与跨平台（非 iOS）应用开发的完整生命周期：技术栈选型、分层架构、UI 与设计系统、代码质量、错误处理、测试策略、构建发布、性能优化、调试修复与项目路线图。配合该技能目录下 references 中各技术栈的深度参考文档，读者可掌握可直接落地的架构模板与 Kotlin/Java/Dart/TypeScript 多语言代码范式，适用于从零搭建新项目或对存量应用进行工程化改造的实战场景。

技能定位与适用边界

在开始之前，先明确该技能在 agentic-awesome-skills 仓库中的定位。根据 data/catalog.json 中的技能目录登记，android-dev技能以skills/android-dev/SKILL.md为入口，其 SKILL.md 声明了它的适用场景：技术选型决策、项目架构搭建、UI/设计系统设计、代码质量保障、错误处理、测试策略、构建/CI/CD 与发布流水线、性能优化、调试修复以及全周期开发路线图。

同时必须注意它的明确边界：

• 该技能仅覆盖 Android 及 Android 相邻的交付路径，不覆盖 iOS 专属架构、App Store 发布运营或 Apple 平台 UI 规范（这也是技能描述中反复强调"非 iOS"的原因）；
• 版本号、Play Console 策略阈值与推荐库版本会随时间变化，发布关键细节需以当前 Android / Google Play / 库的官方文档为准；
• 文中的代码片段是架构模式而非完整应用，需要根据实际项目调整包名、依赖版本、权限、隐私声明与安全控制；
• 该指南不能替代设备 QA、无障碍审查、安全审查、法务/隐私审查与商店合规检查。

§1 技术栈选型：六条主流路线的决策矩阵

选型的核心原则是依据团队、需求与平台目标来决定，不要推荐 iOS 专属路径。detailed-guide.md 给出了六条候选路线，每一条在references/目录下都有对应的深度参考文档。

1.1 六条技术路线速览

Native Android — Kotlin + Jetpack Compose（native-android.md）

• 最佳场景：纯 Android 应用、硬件密集型功能、追求顶级 UX 的新项目；
• 语言：Kotlin；UI：Jetpack Compose 声明式 UI；
• 核心库：Room、Retrofit/Ktor、Hilt、WorkManager、DataStore、Navigation Compose。

Native Android — Java + XML Views（java-android.md）

• 最佳场景：存量 Java 代码库、无 Kotlin 经验的团队、遗留应用维护与渐进式 Kotlin 迁移；
• 语言：Java（Google 完全支持，未废弃）；UI：XML 布局（ConstraintLayout、RecyclerView、ViewBinding）；
• 核心库：Room、Retrofit、Hilt、WorkManager、LiveData、ViewModel；
• 关键认知：Java 与 Kotlin 可在同一工程内无缝共存，可逐步迁移。

Flutter（Dart）（flutter.md）

• 最佳场景：Android + Web（+ 桌面端）单代码库、快速迭代、像素级自定义 UI；
• 语言：Dart；UI：Flutter Widget 树（Material 3 / Cupertino 均可，Android 上以 Material 为目标）；
• 核心库：Provider/Riverpod/Bloc、Dio、Drift/Isar、go_router、flutter_local_notifications。

React Native（JavaScript/TypeScript）（react-native.md）

• 最佳场景：Web + Android 代码共享、JS/TS 团队、生态丰富；
• 语言：TypeScript（首选）；UI：RN 核心组件 + NativeWind / React Native Paper；
• 核心库：React Navigation、Zustand/Redux Toolkit、React Query、MMKV。

Kotlin Multiplatform（KMM / Compose Multiplatform）（kmm.md）

• 最佳场景：在 Android + Desktop + Web 间共享业务逻辑，同时保留原生 Android UI；
• 语言：全栈 Kotlin；UI：Android 端原生 Compose，共享 UI 用 Compose Multiplatform；
• 核心库：Ktor、SQLDelight、Koin、kotlinx.serialization、Napier。

Hybrid（Capacitor / Ionic）（hybrid.md）

• 最佳场景：Web 优先团队、简单应用、类 PWA 内容应用；
• 语言：TypeScript + HTML/CSS；UI：Ionic 组件或自定义 Web UI；
• 应避免：重度动画、原生传感器访问、高性能游戏。

1.2 选型决策矩阵

以下是详细指南给出的完整决策矩阵，建议作为团队技术评审时的第一张检查表：

需要特别解释两个容易误读的格子："Android + Web" 一行中 Hybrid 标为 Best，是因为 Web 团队把 Web 资产直接包装成可安装 App 的成本最低；"Android-only (existing Java)" 一行中 KMM 标为 ⚠️，意味着存量 Java 工程引入 KMM 的迁移成本较高，不如直接渐进式转 Kotlin。而 Native performance 一行中 RN 为 ⚠️，源自其 JS 桥接层的固有开销，可通过新架构（Bridgeless）缓解但无法完全消除。

§2 架构设计：Clean Architecture + MVI/MVVM

2.1 核心原则：关注点分离

详细指南的第一条架构铁律：每个生产级 Android 项目必须将 UI、业务逻辑、数据划分为独立、可单独测试的层次。推荐的包结构如下：

app/ ├── ui/ # Composables / Activities / Fragments / Screen states ├── presentation/ # ViewModels, UI State, UI Events ├── domain/ # Use cases, domain models, repository interfaces ├── data/ # Repository impl, remote (API), local (DB), mappers └── di/ # Dependency injection modules

单向数据流是这套架构的血液循环：

User Action → ViewModel/Store → Use Case → Repository → Data Source ↓ UI State (sealed class / StateFlow) ↓ Composable / View renders state

2.2 各技术栈的状态管理范式

Native（MVVM + MVI）：StateFlow/SharedFlow承载响应式状态；sealed class UiState+sealed class UiEvent定义状态与一次性事件；Hilt 做依赖注入，协程 + Flow 处理异步；Repository 模式统一封装 Room + Retrofit。native-android.md 给出了完整的 ViewModel 范式：

// UiState — sealed class 保证 when() 穷尽 sealed class HomeUiState { object Loading : HomeUiState() data class Success(val items: List<Item>) : HomeUiState() data class Error(val message: String) : HomeUiState() } // UiEvent — 一次性事件（导航、Snackbar） sealed class HomeUiEvent { data class NavigateTo(val route: String) : HomeUiEvent() data class ShowSnackbar(val message: String) : HomeUiEvent() } @HiltViewModel class HomeViewModel @Inject constructor( private val getItemsUseCase: GetItemsUseCase ) : ViewModel() { private val _uiState = MutableStateFlow<HomeUiState>(HomeUiState.Loading) val uiState: StateFlow<HomeUiState> = _uiState.asStateFlow() private val _uiEvent = Channel<HomeUiEvent>() val uiEvent = _uiEvent.receiveAsFlow() init { loadItems() } fun loadItems() { viewModelScope.launch { _uiState.value = HomeUiState.Loading getItemsUseCase() .onSuccess { _uiState.value = HomeUiState.Success(it) } .onFailure { _uiState.value = HomeUiState.Error(it.message ?: "Unknown error") } } } }

对应的 Repository 接口定义在 domain 层、实现放在 data 层，UI 层只依赖接口：

// domain 层接口 interface ItemRepository { fun observeItems(): Flow<List<Item>> suspend fun refreshItems(): Result<Unit> suspend fun getItemById(id: String): Result<Item> } // data 层实现 class ItemRepositoryImpl @Inject constructor( private val remoteSource: ItemRemoteDataSource, private val localSource: ItemLocalDataSource, private val mapper: ItemMapper ) : ItemRepository { override fun observeItems(): Flow<List<Item>> = localSource.observeAll().map { mapper.toDomain(it) } override suspend fun refreshItems(): Result<Unit> = runCatching { val dto = remoteSource.fetchItems() localSource.insertAll(mapper.toEntity(dto)) } }

Flutter（BLoC 或 Riverpod）：Bloc/Cubit隔离业务逻辑，AsyncNotifierProvider（Riverpod）同时承载数据与状态，Repository 以抽象类 + 注入实现。flutter.md 展示了HomeBloc中emit(loading)→result.fold(failure/success)的完整状态机，以及 Riverpod 中用AsyncValue.guard包裹加载的替代方案。

React Native（Redux Toolkit 或 Zustand）：RTK Query / React Query 管理服务端状态，Zustand slices 管理客户端状态，用自定义 hooks 按 feature 封装业务逻辑。react-native.md 特别强调：不要把 bearer/refresh token 持久化在 AsyncStorage 或明文 MMKV 中，应使用 react-native-keychain 或 expo-secure-store 等平台背书的安全存储，Zustand 只持久化非敏感 UI 状态。

KMM：共享的commonMain持有 domain + data 层，expect/actual实现平台差异，Kotlin 协程 + Flow 桥接到各平台（Android 上为 StateFlow）。kmm.md 给出了expect fun httpClient(...)在 androidMain 中落地为 OkHttp 引擎的完整示例，以及 SQLDelight 通过expect class DatabaseDriverFactory实现平台驱动的模式。

2.3 大型应用的多模块结构

:app # Entry point, DI wiring :core:ui # Design system, shared composables :core:network # API client, interceptors :core:database # Room / SQLDelight setup :feature:home :feature:profile :feature:settings

模块化的收益在于编译隔离与职责边界：核心模块无业务依赖，feature 模块之间禁止互相引用，一切通过:app组装。

§3 UI 与设计系统

3.1 先设计系统，再写界面

写任何屏幕之前，必须定义五类设计 token：

1. Color tokens— Primary、secondary、surface、on-surface、error，含亮色/暗色两套变体；
2. Typography scale— Material 3 字型系统：Display、headline、title、body、label；
3. Spacing scale— 4dp 网格（4、8、12、16、24、32、48dp）；
4. Shape tokens— 按组件族定义圆角半径；
5. Component library— Button、TextField、Card、BottomSheet、TopAppBar 等。

3.2 Jetpack Compose 编写规则

• 一律使用MaterialThemetoken，严禁硬编码颜色与尺寸；
• 用CompositionLocal传递主题、语言环境、触感反馈；
• 正确使用remember/rememberSaveable（UI 状态要能跨旋转存活）；
• 大型 composable 拆分为子 composable，每个函数 ≤ 80 行；
• 列表必须用LazyColumn/LazyVerticalGrid，绝不用Column+ forEach 渲染大数据；
• 副作用只允许出现在LaunchedEffect、DisposableEffect、SideEffect中；
• 状态提升到最低公共祖先，避免反模式。

3.3 无障碍（不可妥协）

• 所有可交互元素提供contentDescription或semantics { }；
• 最小触控目标48×48dp；
• 每次发布前用 TalkBack 实测；
• 文字使用sp而非dp，支持动态字号；
• 颜色对比度 ≥ 4.5:1（WCAG AA）。

3.4 导航

• Native：Navigation Compose + 类型化NavHost（SafeArgs 等价物）；
• Flutter：go_router 命名路由 + 守卫（flutter.md 给出了基于authStateProvider的redirect守卫示例）；
• RN：React Navigation v7 + 类型化NavigationProp（react-native.md 展示了RootStackParamList的类型驱动导航与登录态条件渲染）；
• 每个可被外部打开的屏幕都要注册 Deep Link；
• 背栈要刻意管理：不压入重复页面，使用popUpTo/launchSingleTop。

3.5 响应式与自适应

• 支持手机、折叠屏、平板全尺寸（WindowSizeClass）；
• 在 320dp、360dp、411dp、600dp+、840dp+ 宽度下测试；
• 折叠屏铰链感知用WindowInfoTracker；
• Android 15+ 必须处理 edge-to-edge 显示与WindowInsets。

§4 代码质量最佳实践

4.1 语言规范

Kotlin：

• 恰当使用data class、sealed class、object、enum class；
• 禁止!!空断言，改用?.let、?: return、带消息的requireNotNull；
• 协程必须显式指定CoroutineScope+Dispatcher，**绝不使用 `GlobalScope``；
• Compose 状态类标注@Stable/@Immutable以优化重组。

Java（java-android.md 有完整对照）：

• 每个方法参数与返回值标注@NonNull/@Nullable；
• 对未检查对象显式判空或使用Objects.requireNonNull；
• Fragment 的onDestroyView()中必须置空binding引用防止内存泄漏；
• 后台任务用ExecutorService（AsyncTask已废弃），或利用 LiveData + Room 内置线程；
• RecyclerView 优先ListAdapter+DiffUtil，不要手动notifyDataSetChanged()；
• 使用ViewBinding，永远不用findViewById。

Dart（Flutter）：强制空安全（无先验判空不得使用!）；不可变状态对象配copyWith；所有无状态 widget 使用const构造。

TypeScript（RN）：tsconfig 恒开strict: true；API 响应用 Zod 或 io-ts 做运行时校验；不用any，用unknown并收窄。

4.2 依赖管理

• 在build.gradle.kts/pubspec.yaml/package.json中锁定所有依赖版本（推荐 Gradle Version Catalog，见 §7）；
• 每月审计依赖安全漏洞；
• 用依赖解析策略规避传递依赖冲突；
• 保持依赖数量最小化——每多一个库都是维护负担。

4.3 代码评审清单（PR 门禁）

• 新公共 API 有 KDoc / DartDoc / JSDoc；
• 无硬编码字符串，统一使用字符串资源 / l10n；
• 设计 token 之外无硬编码尺寸与颜色；
• 主线程无阻塞 I/O；
• 无内存泄漏（单例不持有Activitycontext）；
• 协程作用域 / 流正确取消 / 释放；
• 非平凡功能受 Feature Flag 保护。

§5 错误处理与网络韧性

5.1 黄金法则

绝不允许异常静默地传播给用户或直接崩溃应用。

5.2 错误分类与应对策略

5.3 Result / Either 模式（Kotlin）

详细指南给出的 AppResult 模式是 repository 与 use case 的统一返回值契约：

sealed class AppResult<out T> { data class Success<T>(val data: T) : AppResult<T>() data class Error(val exception: AppException) : AppResult<Nothing>() } sealed class AppException(msg: String) : Exception(msg) { class NetworkException(msg: String) : AppException(msg) class AuthException(msg: String) : AppException(msg) class ParseException(msg: String) : AppException(msg) class UnknownException(msg: String) : AppException(msg) }

所有 repository + use case 函数统一返回AppResult<T>，ViewModel 将其映射为UiState.Error。对应的，Flutter 侧用Either<Failure, List<Item>>（dartz），java-android.md 用带Status枚举的泛型UiState<T>包装器，三种语言实现同一套错误语义。

5.4 崩溃上报

• 第一天就接入Firebase Crashlytics或Sentry；
• 崩溃发生前设置用户标识与自定义键；
• 所有捕获的异常记录非致命日志；
• 开启 ANR 监控；
• 无崩溃会话率目标：≥ 99.5%。

5.5 离线与网络韧性

• Cache-first 策略：先展示陈旧数据，后台刷新新数据；
• Room/Drift/MMKV作为单一事实来源；
• 通过ConnectivityManager暴露网络状态并在 UI 中反映；
• 所有网络调用包裹超时 + 重试策略（native-android.md 的 Retrofit 客户端设 10s connect/read timeout；KMM 的 Ktor 客户端通过HttpTimeout插件设置 10_000ms requestTimeout）。

§6 测试策略：测试金字塔

/\ /E2E\ ← 10% (UI tests: Espresso, Maestro, Appium) /------\ / Integr \ ← 20% (Repository, DB, API contract tests) /----------\ / Unit \ ← 70% (ViewModels, Use Cases, Utilities) /--------------\

6.1 单元测试（70%）

• 每个 ViewModel、UseCase、Repository、Mapper 都要测试；
• Native：JUnit5 + MockK + Turbine（Flow 测试）+ Kotest 断言；native-android.md 给出了用MainDispatcherRule+runTest+viewModel.uiState.test { skipItems(1); assertThat(awaitItem()) }验证 Loading→Success 状态流的完整用例；
• Flutter：flutter_test+mocktail；flutter.md 展示了blocTest声明式断言[loading, success]状态序列；
• RN：Jest +@testing-library/react-native+msw模拟 API；
• 覆盖率目标：domain + presentation 层≥ 80%。

6.2 集成测试（20%）

• Room DB 用内存数据库测试；
• Retrofit/Ktor 用MockWebServer（OkHttp）测试；
• Repository 测试验证缓存 + 远端协调逻辑；
• API 契约测试打到真实 staging 端点。

6.3 UI / E2E 测试（10%）

• Espresso覆盖关键用户旅程（登录、结账、核心操作）；
• Maestro做跨平台 E2E（Flutter + RN 也推荐）；
• 发布前在真机农场（Firebase Test Lab / BrowserStack）运行；
• 每个 PR 跑冒烟测试套件，夜间跑完整 E2E 套件。

6.4 测试数据管理

• 用工厂 / builder 构造测试数据，绝不复制粘贴对象；
• Hermetic 测试：测试用例之间不共享可变状态；
• 复杂依赖（repository、data source）用 Fakes 而非 Mocks。

§7 构建、CI/CD 与发布

7.1 构建变体

debug → dev API, logging on, no minification, debuggable staging → staging API, logging on, minified, not debuggable release → prod API, logging off, minified, signed

7.2 Gradle 最佳实践（Native）

• 新项目只用build.gradle.kts（Groovy DSL 已过时）；
• 用版本目录libs.versions.toml管理所有依赖版本——native-android.md 给出了完整的 toml 示例（kotlin 2.0.0、compose-bom 2024.06.00、hilt 2.51、room 2.6.1、retrofit 2.11.0、coroutines 1.8.1、lifecycle 2.8.2）；
• 用buildConfig注入环境相关常量；
• 生成并提交 Baseline Profiles 以提升启动性能；
• release 启用 R8 全量模式，proguard 规则纳入版本控制。

7.3 CI/CD 流水线

PR Opened └─ lint + unit tests + build debug APK [< 5 min] Merge to main └─ unit + integration tests + staging build [< 15 min] └─ deploy to Firebase App Distribution (QA) Release tag └─ full test suite + E2E on device farm [< 45 min] └─ build release AAB └─ upload to Play Console (internal track) └─ promote: internal → closed testing → open → production

推荐的 CI 平台：GitHub Actions、Bitrise 或 CircleCI。

7.4 Play Store 发布策略

• 永远按internal → closed → open testing顺序推进后再上生产；
• 使用分阶段发布（staged rollout）：5% → 20% → 50% → 100%，每阶段观察 24–48 小时；
• 扩量前监控 Crashlytics + ANR 率 + 评分；
• 重大变更绝不跳过 staged rollout。

7.5 应用签名

• 上传密钥（Play App Signing）存放在 CI secrets，严禁提交到仓库；
• 用 Google Play App Signing 管理分发密钥；
• 在团队 runbook 中记录密钥恢复流程。

7.6 Hybrid 构建补充

hybrid.md 补充了 Capacitor 路线的构建命令：npm run build构建 Web 资产 →npx cap sync android同步原生工程 →npx cap open android打开 Android Studio →cd android && ./gradlew bundleRelease产出 AAB，并强调通过capacitor.config.ts的android.buildOptions.releaseType选择 APK 或 AAB。

§8 性能优化

8.1 启动性能

• 目标：冷启动< 1s，温启动 < 500ms；
• 用App Startup 库延迟初始化第三方库；
• 生成并提交 Baseline Profiles；
• 重初始化移出主线程。

8.2 UI 性能

• 目标60fps（支持设备上 90/120fps）、零卡顿；
• 用 Android Studio Profiler +FrameMetricsAPI 度量；
• 避免在draw()/onMeasure()/ composition 中分配对象；
• Compose 中用derivedStateOf减少不必要的重组；
• 图片加载用 Coil（Compose）/ Glide / Picasso，缩略图绝不加载全分辨率。

8.3 内存

• ViewModel 与单例中不持有Activity/Context引用；
• 生命周期超出持有者的监听器使用 WeakReference；
• Bitmap 回收与内存缓存尺寸管理；
• debug 构建恒开LeakCanary做堆转储 + 泄漏检测。

8.4 网络

• 尊重 HTTP 缓存头；
• 图片走 CDN + WebP 格式；
• 验证 Gzip/Brotli 压缩；
• 适用场景做请求合并；
• 配置连接池。

8.5 电量

• 后台任务只用WorkManager并配适当约束；
• 定位更新只请求所需精度，退后台即停止；
• Wakelock 谨慎使用并显式释放。

§9 调试与缺陷修复

9.1 调试流程

1. 稳定复现——记录精确步骤、设备、OS 版本、账号状态；
2. 隔离——判断问题在 UI、业务逻辑、网络还是持久化层；
3. 插桩——针对性日志/断点，不要散弹式打日志；
4. 假设——改代码前先形成 1–3 条具体假设；
5. 修根因——绝不只打补丁掩盖症状，要回溯到源头；
6. 回归测试——写一个修复前失败、修复后通过的测试；
7. 记录——注释说明修复为什么有效，而不只是做了什么。

9.2 常见 Android Bug 模式速查表

9.3 日志规范

• 生产：只走 Firebase Crashlytics（release 构建无Log.d）；
• Debug/Staging：Timber + debug tree；
• 日志级别：ERROR（崩溃）、WARN（可恢复）、INFO（关键事件）、DEBUG（仅开发）；
• 绝不记录 PII——日志中脱敏邮箱、手机号、token。

9.4 OEM 特有问题

• 关键流程必须在Samsung、Xiaomi/MIUI、OnePlus/OxygenOS、Huawei（无 GMS）上测试；
• 各 OEM 后台限制差异巨大——重点测推送、闹钟、后台同步；
• 维护覆盖主流市场份额设备的实体或云端设备农场。

§10 开发路线图：14 周从 0 到上线

详细指南给出了可执行的分阶段清单，这是任何新 Android 项目的推进模板：

Phase 0 — 基建（第 1-2 周）

• 记录技术选型决策及理由
• 定义模块结构
• 定义设计系统 token（颜色、字型、间距、形状）
• CI 流水线跑通（lint + 单元测试 + 构建）
• 接入崩溃上报（Crashlytics/Sentry）
• 接入分析基线（Firebase/Amplitude）
• 搭建 API 契约 / mock server
• 配置 DI 框架
• 实现导航骨架
• 完成 flavor/构建变体配置

Phase 1 — 核心功能（第 3-8 周）

• 认证流程（登录、注册、token 刷新、登出）
• 带真实导航的核心屏幕壳
• 网络层（客户端、拦截器、错误处理）
• 本地持久化层（DB schema + DAOs）
• Repository 层打通远端 + 本地
• 每个 feature 的 ViewModels + UI states
• 所有 ViewModels + use cases 的单元测试
• Feature flags 基础设施

Phase 2 — 打磨（第 9-12 周）

• 对照 Figma/设计稿做设计 QA
• 无障碍审计（TalkBack、对比度、触控目标）
• 暗色模式实现 + 验证
• 本地化（字符串外置、需要时支持 RTL）
• 每个屏幕的加载、空、错误三态
• Deep link 处理
• Widget / 通知实现
• 离线模式验证

Phase 3 — 加固（第 12-14 周）

• 性能剖析（启动、滚动、内存）
• 设备农场 E2E 测试套件（Firebase Test Lab）
• 安全审查（证书固定、生物识别、安全存储）
• 验证 Proguard / R8 规则
• staging 上无崩溃率 ≥ 99.5%
• Play Store 上架素材、截图、隐私政策

Phase 4 — 发布

• AAB 签名并上传到 internal track
• 定义分阶段发布计划
• 搭建监控看板（Crashlytics、Play Console vitals）
• 记录回滚方案
• 安排值班（on-call）轮换

Phase 5 — 上线后（持续）

• 每日监控无崩溃率
• ANR 率 < 0.47%（Play Store 阈值）
• 监控应用评分；每周处理差评
• 每月评审依赖更新
• 每次新版 Android 发布时参与 OS beta 测试

延伸阅读：按技术栈深入

详细指南的"Additional Resources"指向六个深度参考文档，全部位于 references 目录，均包含完整可运行的代码范式：

• native-android.md — Kotlin、Compose、Room、Hilt、协程；含项目结构、ViewModel/Repository/Compose Screen/Room/Hilt DI 完整代码、libs.versions.toml 与 ViewModel 单元测试；
• java-android.md — Java、XML Views、ViewBinding、LiveData、Retrofit、Room、Hilt 与渐进迁移路径；含UiState<T>泛型包装、AuthInterceptor、ListAdapter + DiffUtil、onDestroyView()防泄漏等 Java 侧实践；
• flutter.md — Dart、BLoC/Riverpod、Drift、go_router；含 freezed 状态/事件、blocTest测试、pubspec.yaml 依赖清单；
• react-native.md — TypeScript、RN 新架构、Hermes；含类型化导航、Zustand + React Query 分工、Zod 运行时校验、axios 401 自动刷新、MMKV 安全存储边界；
• kmm.md — KMM 共享模块、SQLDelight、Ktor、Compose Multiplatform；含expect/actual模式、Koin 双端 DI、shared Flow 消费方式；
• hybrid.md — Capacitor、Ionic、PWA 考量；含 capacitor.config.ts、原生插件调用与自定义@CapacitorPlugin开发。

建议的阅读方式：把 detailed-guide.md 当作全局地图，按当前项目所处阶段（选型、架构、测试、发布……）进入对应章节；需要某一技术栈的完整代码范式时，再加载对应的 reference 文档。对于端到端的新项目启动，完整通读详细指南后再动手，可将本文的清单与代码模板直接转化为工程初稿。

• AI 技能
• AI 插件