【免费下载链接】kotlin-agent-skills
A collection of AI agent skills useful for projects using Kotlin language
当 Kotlin Multiplatform（KMP）项目升级到 Android Gradle Plugin 9.0 时，kotlin.multiplatform与com.android.application、com.android.library插件将无法共存于同一模块，构建直接报错。开源项目kotlin-agent-skills提供了一套 AI Agent 技能，能自动分析你的项目结构，按三条迁移路径（Library 插件替换、Android App 拆分、全量重构）一次性解决 AGP 9.0 插件不兼容难题。
为什么 AGP 9.0 会让 KMP 构建失败？
AGP 9.0 带来了一个根本性变化：Android 应用/库插件与 Kotlin Multiplatform 插件不再允许出现在同一个模块里。同时它还内置了 Kotlin 支持（不再需要org.jetbrains.kotlin.android插件）、引入了单变体（single-variant）架构，并调整了大量 Gradle 属性默认值。
换句话说，过去"一个composeApp模块打天下"的 KMP 项目结构，在 AGP 9.0 下必须改变。好消息是：kotlin-agent-skills 仓库里的 kotlin-tooling-agp9-migration 技能已经把完整的迁移方法论整理成了 AI 可读的指南，包括：
- references/MIGRATION-LIBRARY.md：库模块迁移前后对照
- references/MIGRATION-APP-SPLIT.md：App + Shared 模块拆分全攻略
- references/MIGRATION-FULL-RESTRUCTURE.md：按平台拆分模块的完整重构方案
- scripts/analyze-project.sh：一键扫描项目的分析脚本
三条迁移路径：先看模块插件组合再选路
迁移前的第一步是分析项目：读取settings.gradle.kts找出所有模块，再逐个查看各模块应用了哪些插件。技能内置了一个判断表，让你 30 秒内定位自己的路径：
| 当前模块插件组合 | 迁移路径 | 是否必须 |
|---|---|---|
kotlin.multiplatform+com.android.library | 路径 A：插件替换 | 推荐 |
kotlin.multiplatform+com.android.application | 路径 B：强制拆分 Android 模块 | 必须 |
| 单模块包含多平台入口（Android/Desktop/Web） | 路径 C：全量重构 | 推荐 |
| 纯 Android 模块（无 KMP） | 走 Built-in Kotlin 迁移 | — |
路径 A：Library 模块的插件替换（改动最小）
适用于"KMP + Android 库"模块。核心动作只有一个：把com.android.library换成新插件com.android.kotlin.multiplatform.library。配套调整包括：
- 删除
org.jetbrains.kotlin.android插件（AGP 9.0 已内置 Kotlin） - 把顶层
android {}配置搬进kotlin { android {} }新 DSL - 源码目录改名：
src/main→src/androidMain，src/androidTest→src/androidDeviceTest - 依赖从顶层
dependencies {}移入kotlin { sourceSets {} }
细节较多的坑（比如忘记开androidResources导致 Compose 资源崩溃）都记录在 references/KNOWN-ISSUES.md 中。
路径 B：Android App 强制拆分（AGP 9.0 硬性要求）
这是所有 KMP +com.android.application模块必须走的路。思路是把composeApp一分为二：
- 新建
androidApp模块，只放MainActivity、应用级AndroidManifest.xml、图标与主题等资源 - 原模块按路径 A 转为纯 KMP 库（改名
shared），保留 iOS / Desktop / Web 等共享代码 androidApp通过implementation(projects.shared)依赖共享模块
⚠️ 容易踩的坑：两个模块的namespace必须不同；applicationId、targetSdk、versionCode等 App 配置要全部移出共享模块；IDE 运行配置也要切到新的androidApp。
路径 C：全量重构（对齐 JetBrains 新默认结构）
如果你嫌"拆一半"不够整洁，路径 C 会把每个平台都拆成独立入口模块，这也是 JetBrains 新模板的默认结构：
project/ ├── shared/ ← 纯共享 KMP 库（原 composeApp） ├── androidApp/ ← Android 入口 ├── desktopApp/ ← Desktop 入口（如有） ├── webApp/ ← Wasm/JS 入口（如有） └── iosApp/ ← iOS Xcode 工程（通常本就独立）操作顺序固定：先执行路径 B（AGP 9.0 强制要求），再把desktopMain的main()函数移入desktopApp、把 Web 入口移入webApp，最后把composeApp正式改名为shared并清理残留。若部分平台用原生 UI（如 SwiftUI），还可以进一步拆出sharedLogic+sharedUI两层。
版本要求速查：AGP 9.0 迁移最低门槛
不管走哪条路径，以下版本必须同步升级，完整矩阵见 references/VERSION-MATRIX.md：
| 组件 | 最低版本 | 推荐版本 |
|---|---|---|
| AGP | 9.0.0 | 9.0.1+ |
| Gradle | 9.1.0 | 9.1.0+ |
| JDK | 17 | 17+ |
| SDK Build Tools | 36.0.0 | 36.0.0 |
| Kotlin (KGP) | 2.0.0（KMP 库插件） | 2.3.0+ |
| KSP | 2.3.1 | 2.3.6 |
| Compose Multiplatform | 1.9.3 | 1.10.0+ |
| Android Studio | Otter 3 (2025.2.3) | 最新稳定版 |
两个特别提醒：
- IDE 选择：截至 2026.1，IntelliJ IDEA 尚不支持 AGP 9.0 的 Android 目标，请用 Android Studio；IDEA 仍可开发 JVM / iOS / JS 等非 Android 目标
- 第三方插件：迁移前务必盘点所有插件并对照 references/PLUGIN-COMPATIBILITY.md。KSP（≥2.3.1）、Hilt（≥2.59）、Compose（≥1.9.3）已适配；而
androidx.baselineprofile、com.github.triplet.play等需要临时加android.newDsl=false开关；New Relic、华为 AGConnect 等插件目前无解，需等待官方更新
如何上手使用 kotlin-agent-skills 技能
kotlin-agent-skills 遵循 Agent Skills 标准，每个技能都是包含SKILL.md说明文件的独立文件夹。安装方式任选其一：
方式一：使用 skills CLI
npx skills add Kotlin/kotlin-agent-skills方式二：Claude Code 插件市场
claude plugin marketplace add Kotlin/kotlin-agent-skills claude plugin install kotlin-agent-skills@Kotlin方式三：手动复制（最直观）
先克隆仓库：
git clone https://gitcode.com/gh_mirrors/ko/kotlin-agent-skills然后把技能文件夹拷进你的 Agent 技能目录：
cp -r kotlin-agent-skills/skills/kotlin-tooling-agp9-migration .claude/skills/之后让 Agent 在 KMP 项目目录中执行，它会自动运行项目分析（可配合 scripts/analyze-project.sh 输出结构化摘要），判断你的模块属于哪条路径，并逐步给出修改方案。
迁移完成后：用清单逐项验收
改完代码不等于迁移完成。技能自带了一份 assets/checklist.md 验收清单，核心检查点如下：
- ✅
./gradlew build全量构建通过，无报错 - ✅ KMP 模块中不再出现
com.android.library/com.android.application旧插件 - ✅ 所有模块已移除
org.jetbrains.kotlin.android（由内置 Kotlin 接管） - ✅
kapt已迁移到 KSP 或com.android.legacy-kapt - ✅ 各平台目标均可构建：Android、iOS（
xcodebuild）、Desktop、JS/Wasm - ✅
./gradlew :shared:allTests测试全部通过 - ✅ 无 variant API / DSL 弃用警告
如果某个第三方插件暂时卡住迁移，可以在gradle.properties中临时关闭内置 Kotlin（android.builtInKotlin=false）争取时间——但请记住这只是临时手段，技能文档中也明确要求在解除阻塞后恢复默认配置。
常见问题：库模块的 BuildConfig 去哪了？
路径 A 的新插件采用单变体架构，KMP 库模块不再生成BuildConfig类。技能给出的推荐方案是使用expect/actual+ 依赖注入的AppConfiguration接口模式，或引入 BuildKonfig 等编译期常量工具；NDK/JNI 代码则建议抽回独立的com.android.library模块。更多细节（R8 keep 规则收紧、targetSdk默认值变化等）可查阅 references/KNOWN-ISSUES.md。
总结
KMP 项目升级 AGP 9.0 看似是一场"推倒重来"，其实只是三件事：选对路径（A/B/C）、对齐版本、清理旧 DSL。kotlin-agent-skills 的 kotlin-tooling-agp9-migration 技能 把官方文档、版本矩阵、插件兼容表和验收清单打包成了一个 AI 可以直接执行的知识库。把技能装进你的编码 Agent，让它先分析项目、再按路径动手，插件不兼容的难题就可以一次搞定。
【免费下载链接】kotlin-agent-skills
A collection of AI agent skills useful for projects using Kotlin language
相关推荐
10分钟解决QuickLook插件不兼容问题：旧版本插件迁移完全指南
10分钟解决QuickLook插件不兼容问题：旧版本插件迁移完全指南 你是否遇到过升级QuickLook后，常用插件突然失效的情况？本文将系统讲解如何将旧版本插
桌面应用插件系统攻克Glide缓存路径迁移难题：文件重命名完全指南
攻克Glide缓存路径迁移难题：文件重命名完全指南 Glide作为Android平台专注于平滑滚动的图片加载与缓存库，其高效的缓存机制是实现流畅体验的核心。然而
移动开发缓存图像处理CoreDNS 1.8.0 发布解读：transfer 插件升级与三项不兼容变更迁移指南
CoreDNS 1.8.0 发布解读：transfer 插件升级与三项不兼容变更迁移指南 CoreDNS 1.8.0 是 2020 年 10 月发布的一个重要版
后端网络云原生
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
