KMP DevHub 是一个基于 WanAndroid 开放 API 的 Kotlin Multiplatform 应用。项目共享网络、缓存、Repository、分页、会话、业务状态和 ViewModel；Android 使用 Jetpack Compose，iOS 使用 SwiftUI，不共享 UI。
README 面向开发者，说明项目是什么、如何运行、采用哪些库以及当前交付边界。Codex 的执行规范、源码集约束和 skill 路由则维护在 AGENTS.md，两者不要混写。
- 首页文章、置顶、Banner、热门内容、常用网站、热词和最新项目。
- 知识体系、导航、公众号、教程、鸿蒙、项目、广场、问答、工具和 Maven 查询。
- 搜索、登录、注册、退出、个人信息、积分和排行榜。
- 文章/站外文章/网站收藏，用户分享和个人分享；首页与内容列表支持行内收藏切换（乐观更新，失败回滚并提示）。
- TODO v2 的列表、筛选（全部/未完成/已完成）、新增、编辑、完成切换和删除。
- 已读/未读消息与未读数量；读取未读消息是有服务端副作用的操作。
- Android/iOS 原生刷新、加载更多、WebView（统一
isSafeWebUrl安全拦截与加载进度）、暗色模式、动态字体和宽屏布局基础。
接口路径、鉴权和分页起点见 docs/API_COVERAGE.md，目录职责和命名约定见 docs/ARCHITECTURE.md。
| 能力 | 共享/Android | iOS |
|---|---|---|
| 网络 | Ktor Client 3.5.2，OkHttp engine | Ktor Darwin engine |
| JSON/异步/时间 | Kotlinx Serialization、Coroutines/StateFlow、Kotlinx Datetime | 观察共享状态 |
| DI/ViewModel | Koin 4.2.2、KMP ObservableViewModel 1.0.2 | KMP NativeCoroutines 1.0.5 |
| KV 与会话 | 腾讯官方 com.tencent:mmkv-kmp:2.4.2 |
同一个 KMP artifact |
| 日志 | Kermit 2.1.0 | 输出到系统日志 |
| UI | AndroidX Compose Material 3 | SwiftUI |
| 导航 | Navigation 3 1.1.7、Material 3 Adaptive | TabView、NavigationStack、NavigationSplitView |
| 图片 | Coil 3.6.0 | NukeUI 13.2.0 |
| Web | AndroidX WebKit | WebKit / WKWebView |
全部 Gradle 版本集中在 gradle/libs.versions.toml。iOS Swift Package 固定在 Xcode 工程中。
Android Compose + Nav3 ─┐
├─ shared ViewModel / StateFlow
iOS SwiftUI + Router ───┘ │
Repository（单一数据来源）
├─ Ktor RemoteDataSource
└─ MMKV CacheDataSource
shared 保持为一个 framework，并按基础设施、领域模型、数据和 feature 组织：
core/network：Ktor、统一 Envelope、超时、GET 重试和脱敏日志。core/cache：项目存储接口、MMKV 适配器、TTL 和容量控制。core/session：加密 Cookie、登录状态和-1001会话失效。core/paging：统一分页起点、请求去重、过期响应隔离和业务 ID 去重。domain/model/<feature>：按content、home、todo、account拆分的领域模型。data/<feature>：按数据所有权拆分的 Repository；data/WanAndroidApi.kt是远端 API 边界。feature/<feature>/presentation：每个业务独立的UiState、Effect 和 ViewModel。
平台 UI、导航、WebView、图片对象和密钥系统均留在平台侧。
public_cache_v1：公共内容 JSON；不加密，不存隐私，约 20 MiB 上限。preferences_v1：主题和最多 20 条搜索历史。secure_session_v1：Cookie、用户 ID 和最小会话；AES-256 加密。
Android 使用 Keystore 包装随机 MMKV 密钥，iOS 将随机密钥保存在 Keychain。密码不会单独保存，Cookie 不进入公共缓存或日志。图片缓存由 Coil/Nuke 独立管理。
公共内容采用缓存优先与后台刷新：短期内容新鲜 15 分钟、保留 7 天；栏目内容新鲜 6 小时、保留 14 天；结构数据新鲜 24 小时、保留 30 天。账号、TODO、消息和搜索结果不写入公共持久缓存。
.
├── shared/ # core / domain model / data / feature presentation
├── androidApp/ # feature/*/ui Scene + Navigation 3 + 公共 UI
├── iosApp/ # Application / Navigation / Features / UI / Infrastructure
├── docs/API_COVERAGE.md # API 覆盖矩阵
├── .agents/skills/ # 项目安装的 KMP skills
├── AGENTS.md # Codex 项目级执行规范
└── gradle/libs.versions.toml
- Android：Android Studio、兼容当前 AGP/Kotlin 的 JDK，最低 API 24。
- iOS：macOS、Xcode，最低 iOS 16；首次打开由 Swift Package Manager 解析 Nuke 等依赖。
- 首次构建需要网络访问 Maven 和 Swift Package 仓库。
Android Studio 中选择 androidApp 运行，或执行：
./gradlew :androidApp:assembleDebugiOS 使用 Xcode 打开 iosApp/iosApp.xcodeproj。真机前需在 iosApp/Configuration/Config.xcconfig 配置 TEAM_ID、正式 Bundle ID 与签名。
当前实现是完整工程骨架与主要垂直切片，不等同于已经通过发布验收。MMKV KMP 2.4.2 仍是 experimental；正式商业发布前必须完成自动化测试、真机冷启动、登录/Cookie、全部数据形状、无障碍、性能与应用商店隐私审查。还需确认 WanAndroid 内容/商用授权、正式包标识、签名、隐私政策和商店资料。
双端 Debug 构建已在本机验证通过：./gradlew :androidApp:assembleDebug 与 iosApp 的 xcodebuild ... -configuration Debug build（iPhone 17 Pro 模拟器）。
本仓库当前的 Codex 验证约束是只执行 git diff --check，不会自动执行 Gradle、Xcode、测试、模拟器或截图测试。
AGENTS.md 的推荐写法是：只写项目稳定事实和可执行约束，包括项目边界、沟通规范、修改原则、验证范围、skill 触发规则和禁止事项；不要复制 README 的产品介绍，也不要写容易过期的临时任务进度。
已安装 skills 及作用：
| Skill | 作用 |
|---|---|
kotlin-project-feature-implementation |
新功能的源码集、分层、状态管线和最小垂直切片。 |
kotlin-project-architecture-review |
架构、模块边界、状态持有者和演进风险评审。 |
kotlin-kmp-code-review |
已实现代码的正确性、并发、性能、安全和维护性审查。 |
kotlin-project-state-management |
ViewModel、StateFlow、UiState、Effect 和生命周期设计。 |
kotlin-data-kmp-data-layer |
API、Repository、缓存、单一数据源和错误模型。 |
kotlin-platform-kmp-bridges |
commonMain/平台源码集、系统 API 和 Swift/Kotlin 边界。 |
kotlin-testing-kmp |
KMP 测试设计、实现与评审；不会绕过项目验证限制。 |
kotlin-build-kmp-gradle-governance |
Gradle、Version Catalog、target、插件和依赖治理。 |
kotlin-project-bugfix |
根因定位和最小安全修复。 |
kotlin-kmp-refactor-safety |
重构、迁移与可靠性加固的范围和兼容性控制。 |
每个 skill 的完整规则以 .agents/skills/<skill>/SKILL.md 为准。