真正的变化在后面几节。发布格式换了，编译方案换了，还有三处默认值被悄悄调严。我把两个编译器装在同一台机器上，同一份源码各喂一遍，出来的结果不一样。

这次发布，重点不在语法

四项稳定特性里，有两项其实是「把选择变成默认」：按名解构的 only-syntax 模式、未使用返回值检查器。老代码一行不用改，新代码的表达力会变。

实验性的两项也在同一路数上，companion 扩展与 companion 块、完整 value class。都是让语言少一点莫名其妙的限制。

语言层这次最安静。真正铺开来看，是文档后半段那三节：Kotlin Multiplatform 的发布格式、新的编译方案、Apple 平台的增量编译。这三条不影响你写什么，影响你交付什么、多久能编完。

一个 .kar 文件，替掉七千多个文件

官方的原话是这样：

The new format publishes platform artifacts (except for JVM and Android) as a single .kar archive, which is a ZIP archive additionally compressed with XZ.

一个库支持几个目标，过去就要发几套产物。现在除 JVM 和 Android 之外的平台产物，全打成一份 .kar，本质是 ZIP 再套一层 XZ 压缩。

数字比描述直观。官方拿 cryptography-kotlin 举例：发布产物从 7539 个文件、91 MB，变成 1036 个文件、23 MB。整个多模块工程。

开启方式一行配置，单个模块写在构建脚本里，全工程写在 gradle.properties：

kotlin.publicationFormat=KOTLIN_ARCHIVE

两个限定必须一起看。除 JVM 和 Android，这两个生态仍旧走标准的 Maven 产物。消费侧已经全面可用，你依赖的库将来换格式，你的构建不用动。发布侧还是实验特性，你自己要发库的话，得单独验一遍流水线。

为什么 Maven Central 卡的是文件数

原文只说了一句「Maven Central 最近引入了发布体积限制」。这句话背后的事，比体积有意思。

卡住库作者的不是总字节数，是文件数。一个支持六个目标的库，每个目标一套产物，再算上源码包和元数据，随便就上几千个文件。每个文件在仓库里是一条独立记录、一次上传、一次索引，对仓库是运维成本，对使用者是依赖解析时第一屏的请求数。

所以文件数从 7539 掉到 1036，降了百分之八十六，比体积从 91 MB 掉到 23 MB 更关键。省下来的是请求和索引，不是带宽。

JVM 和 Android 被排除在外，也说明一件事：这两个生态还锚在标准 Maven 分类器上，动不了。跨平台库的真实处境是「多目标，主流平台守老格式，其余走归档」，这个混合结构会持续一阵子。

这条改动对下游完全透明，正因为透明，它才敢被推荐给所有人。受益的是库作者和维护发布流水线的人，不是写业务代码的你我。

新的编译方案：common 代码不该偷偷用上平台 API

这一节官方写得克制，四条：让编译器处理 common source sets 的方式与 IDE 一致；防止 common 代码意外解析到平台特有声明；改进重载解析与类型推断的一致性；为 common source set 启用增量编译。

前三条在修一个老坑。commonMain 里写错一个 import，IDE 标红但命令行能过，或者反过来，两边都对不上。原因是 IDE 和编译器各有一套解析器，各算各的。

统一之后有个副作用：以前能编过的代码，现在可能编不过了。这不是退步，那些代码本来就摸到了不该看见的符号，只是没人拦。

第四条才是日常收益。common 终于有增量编译了，天天开 IDE 的人感受最直接。CI 上反而看不出来，因为流水线每次都是全量构建。

JetBrains 在九月专门为这个方案写过一篇博客，标题里用了 reliable 这个词。要修的问题正好就是「不可靠」：同一份 common 代码，IDE 和编译器给出两种结论。

编译器变严了，三处默认值都改了

先看最直观的一处。同一份代码，2.4.21 直接编不过，2.5.0-Beta2 默认就过：

(val mail = email, val name = username) = user

括号里带 val，用等号指定取哪个属性，变量名不用和属性同名。

顺带说个老坑。val (email, username) = user 这种按位写法两个版本都通过，但值是按位置分的。我把 User(username, email) 解成 email=alice、username=alice@example.com，变量名全错，编译器一声不吭。这个特性存在的理由就是它。

第二处是未使用返回值检查器。同一个文件，2.4.21 静默通过，2.5.0-Beta2 直接给 warning：unused return value of 'plus'。表达式算出了非 Unit 的值又没人用，它会指出来。

第三处是跨模块内联。2.4.0 引入时是可选的，2.5.0-Beta2 默认开启，回退开关是 -Xklib-ir-inliner=disabled。

另外还有一处不在默认值上：类型推断的约束生成减少了，处理复杂泛型时不再卡住。官方写得很克制，只说了可能改变推断结果、重载选择、诊断。翻译成人话是，升级后某些代码会推断出不同的类型，而那些代码你之前认为是对的。回退开关 -XXLanguage:-EliminateSecondKindIncorporation。

value class 这一刀切得最深

值类以前只允许一个属性，还得配 @JvmInline。现在多属性可以，另外多了抽象 value class 和 value object 两种形态。

本机实测：2.4.21 对多属性 value class 直接报错，提示要开 -XXLanguage:+FullValueClasses；2.5.0-Beta2 加上 -Xfull-value-classes 就通过。

value object 同理，2.4.21 说 modifier 'value' is not applicable to 'standalone object'，2.5 加上开关能编能跑。

有个细节比文档更能说明问题。value object 上写 ===，编译器直接报错，identity 比较被语言禁掉了，因为它本来就没有身份。

真正的坑在迁移。value class 不再默认 inline。官方给的时间表是 2.5.20 开始出 warning，2.6 或 2.7 变 error。2.5.0-Beta2 上这个开关还认不出来，编译器回的是 flag 不支持，说明窗口确实要等到 2.5.20 才开。

也就是说现在升级不会炸。但你要在 2.5.20 之前把老代码标清楚，决定哪些继续 inline、哪些放手。一个只包一个 String 的值类到底该不该 inline，本来就是取舍，语言不该替所有人做这个默认。

标准库补了两个小口子

if 表达式这块补了三个函数：onTrue()、onFalse()、ifOrNull()。以前写「添加成功了就打印一句」，得先存个局部变量再套 if/else，现在一行接住：

val added = tags.add("wasm").onTrue { println("Tag added") }

返回值还是原来那个布尔，判断和副作用挤在一条链上，不用再为这种小场景单独造变量。

另一半是 Unicode 码点。Char 只装得下 UTF-16 的一个代码单元，碰上 emoji 这种代理对，按 Char 遍历会把一个字符拆成两半。新的 CodePoint 是个 value class，底层用 Int 存码点，能查它占几个 UTF-16 单元、属于哪个类别、是不是字母。

这两处都要 @OptIn(ExperimentalStdlibApi::class)。留意一下 CodePoint 的形态：它本身就是 value class 放宽之后才写得出来的东西，语言和标准库在这一版里对上了。

我在本机看到的两个意外

第一个意外是编译没有变快。489 行的工程，2.4.21 预热后中位数 2.86 秒，2.5.0-Beta2 是 2.99 秒，产物都是 161 KB。差异落在噪声区间，不能说变慢，但也谈不上推断优化在小工程上有什么收益。这类优化只在大型泛型代码里才显形，小样本看不出来。

第二个是开关的适用范围。-Xklib-ir-inliner=disabled 在 JVM 编译器上直接不被接受，提示 flag 不支持。它只在编 klib 的平台有意义，也就是 Native、JS、Wasm 那几路。

文档里写的「默认开启」，按平台分开读才对。

升级前该做的三件事

JDK 门槛抬了。编译器的最低要求从 8 提到 17，现在低于这个版本直接报 error。CI 镜像和 Docker 基础镜像要跟着升，这一步通常比代码改动更耗时间。

发布 Kotlin Multiplatform 库的话，.kar 先别急着开。发布侧还是实验特性，可以在流水线里试跑，别直接推正式版。

测试要跑一遍。未使用返回值检查和类型推断的变化，都属于静默通过但结果不同的那类，读文档看不出问题，跑测试才看得见。

最后

2.5 这一轮的动作大多落在默认值上：默认打包、默认检查、默认内联，还有默认按名字解构。每改一处都配了回退开关，说明官方清楚会踩到人，也说明这些默认值还没定稿。

你手上有没有那种「IDE 标红、命令行却能编过」的代码？升级到 2.5 之后它大概得老实交代。欢迎在评论区聊聊你踩到的变化。

参考资料： Kotlin 2.5.0-Beta2 更新说明 Kotlin 版本发布计划 Kotlin Multiplatform 新编译方案

10 月 6 日，JetBrains 的 Amper 博客发了最后一篇，标题是《Amper Is Now the Kotlin Toolchain》。名字后面还挂着一句 Moving to the Kotlin Blog，是字面意思，这个栏目从那天起不再更新，以后并到 Kotlin 博客里去。

改名的不是博客，是 Amper 自己。它现在叫 Kotlin Toolchain，是 Kotlin 的官方工具链。

这类新闻很容易被划过去，觉得又是改个名冲业绩。但我把它的代码和文档翻了一遍，发现这次不太一样：它是在把 Amper 这三个字从代码里一层一层往外清。

清到什么程度？看 0.13 的发布说明就明白了。破坏性变更里有两条，一条是把环境变量 AMPER_BUILD_DIR 改名成 KOTLIN_TOOLCHAIN_BUILD_DIR，另一条是把模块布局里那个叫 amper 的名字改成 default。

一个名字能从配置文件里清到环境变量里，说明这不是营销动作。

三个月里的三个动作

我按时间把这个过程排了一下：

仓库搬家在 5 月，宣布转正在 6 月，把名字从代码里清干净是 10 月。前两个动作你在新闻里看得到，第三个动作只有翻开 0.13 的发布说明才看得到。

6 月那篇里有句话我挺喜欢，它解释了为什么要换名字：

As the project evolved, it became clear that the ecosystem doesn't just need
another build tool – it needs a unified entry point into all of Kotlin.

译文：随着项目往前走，我们看清了一件事，这个生态要的不是又一个构建工具，而是一个通往整个 Kotlin 的统一入口。

我在这台机器上装了一遍

不看文档里的说法，看它实际怎么跑。装法是官方给的脚本，我没直接管道给 shell，先拉下来读了一遍，脚本里带 SHA256 校验，做题还算规矩。

curl -fsSL -o /tmp/kt-install.sh https://kotl.in/install.sh

它默认会往你的 shell 配置里追加一行 PATH，我用它自己的开关跳过了，不碰我的 zshrc：

KOTLIN_CLI_NO_MODIFY_PATH=1 sh /tmp/kt-install.sh

装完是这样：

Kotlin Toolchain version 0.13.0 (abc7a5f, 2026-10-01)
Installed Kotlin CLI to /Users/trevorwang/.local/bin/kotlin

然后建项目。它有一批非交互的模板，我选了 JVM 命令行那个：

kotlin init --from-template=jvm-cli --no-git

0.34 秒生成完。我以为要看一堆文件，结果整个项目的配置文件就一行：

product: jvm/app

源码三个文件：main.kt 里一句 println，World.kt 里一个 object，test 目录里两个测试。

构建、运行、测试全跑了一遍

第一次构建它自己下了一个 Temurin JDK 25，下完抬头就是绿的。装、建、编、跑、测连着走一遍是这样：

整个过程 30.8 秒，扣掉下 JDK 的时间，剩下的很快。测试那段是红的，因为模板里故意放了一个 assertTrue(false)，函数名就叫 shouldFail。我猜它是想让你先看一眼失败的输出长什么样，顺带告诉你退出码是 1。

还有个命令我挺喜欢，kotlin show settings。它把每个模块生效的设置打出来，默认值后面标一行 # default：

compose:
  version: 1.12.1  # default
junit: junit-5  # default

哪些是你自己写的，哪些是它默认给的，一眼分得清。

三行 YAML 编四个平台

单个 JVM 不够看，我又用 kmp/lib 模板建了一个。它给我的 module.yaml 全文，加上各平台编出来的结果是这样：

平台专属的源码不用 Groovy 那套 source set 命名，是目录后缀：src@jvm、src@android、src@ios，里面各放一份 actual。共享的那份 expect 放在 src。

构建的时候还能只挑平台：

kotlin build -p jvm -p android

11.3 秒，四行绿字，产物是 kt-kmp-jvm.jar 和 kt-kmp-jvm.aar。

这里有个我事先没想到的细节。翻它下载缓存的目录时我发现，为了编 Android，它往我的 Android SDK 里放了一个平台包，时间戳跟这次构建对得上：

~/Library/Android/sdk/platforms/android-37.0/            11:35
~/Library/Android/sdk/platforms/06259a9c8a-platform-37.0_r02.zip.flag

加上前面那个 Temurin JDK、测试用的 JUnit 运行器、iOS 要用的 Kotlin/Native，全是它自己拉下来的。对新人友好到有点过分，装完一个命令，什么都不配，JVM 和 Android 就能编。代价是第一次构建得等下载，而且它会往你的 SDK 目录里放东西。

iOS 那条腿，它停在了 Xcode 上

把 iOS 也加上试试：

kotlin build -p iosArm64
Downloading .../kotlin-native-prebuilt-2.4.20-macos-aarch64.tar.gz
ERROR: Xcode first-launch setup could not be completed.
       Run `sudo xcodebuild -runFirstLaunch` and try again.
ERROR: Task 'xcodeEnvironment' failed: Xcode environment is not ready

它先把 Kotlin/Native 2.4.20 下下来，然后停在这一步。这个检查是 0.13 新加的，发布说明里写的是 Check and/or provision Xcode components automatically。

有意思的地方在这：Kotlin/Native 本身在我这台机器上是能编的，之前我拿它直编过 iOS arm64 的 framework，9.8 秒出产物。工具链检查的是 Xcode 那套组件有没有完成首次启动安装，比编译器本身的要求更靠前，而这一步要 root，得自己跑一次带 sudo 的命令。

这个行为我觉得是好的。它没有编到一半丢给你一个莫名其妙的链接错误，而是停在前置检查上，把该敲的命令写给你。

名字还没清干净的两个地方

第一处，它下载发行包的地址还是老地址，里面带着 amper 两个字，packages.jetbrains.team/maven/p/amper/amper。

第二处更逗，Android 那边的修复清单里有一条，说它以前会把 Android SDK 装成非规范的名字，那个名字叫 Amper-33。

仓库、博客、命令行、环境变量、模块布局，一路清过来，边角还没扫完。这种细节比新闻稿实在，你从里面能看出一次改名到底动了几层。

界面那一侧，多了个开关

命令行那套说完了，界面这一侧的变化同样明显。

插件在 Marketplace 里就叫 Kotlin Toolchain，装的版本是 262.10968.205。它的自我介绍第一句是：

Provides support for Kotlin Toolchain, JetBrains' build tool for Kotlin and
Java projects.

译文：为 Kotlin Toolchain 提供支持，也就是 JetBrains 那套面向 Kotlin 和 Java 项目的构建工具。

功能列表里有三件我关心的：跑和调 JVM、Kotlin Multiplatform、native 的测试，管多模块工程和版本目录，还有 Compose Desktop 与 Compose Multiplatform 的热重载。页面顶部另有一行提示，说部分功能要 Ultimate 订阅才有。

真正有意思的是新建项目那个对话框。Build system 那一栏不再是 Gradle 一个选项，变成了两个并列，右边那个就是 Kotlin Toolchain。

它给这两条各写了一句说明，原话是这样：

Gradle — Flexible and backed by a mature plugin ecosystem
Kotlin Toolchain — Easy to use, declarative, and AI-friendly

译文：Gradle 灵活，背后有成熟的插件生态；Kotlin Toolchain 好用、声明式，对 AI 友好。

AI-friendly 这个词是它自己写上去的。一家做 IDE 的公司在新建项目的默认文案里把「对 AI 友好」当卖点，放在今年不算意外，但这个位置挺说明问题。

勾平台那部分跟 CLI 的模板一个思路，Android、iOS、Desktop、Web、Server 五个复选框，iOS 和 Web 还能选 UI 要不要跟其他端共享。勾完 Android 加 iOS 建出来，结构是这样：

根目录一份 project.yaml 列模块，androidApp、desktopApp、iosApp、shared、webApp、core、server 七个。每个模块自己一份 module.yaml，跟刚才 CLI 里那份三行的配置是同一个东西。版本号仍然放在 libs.versions.toml 里，Gradle 那套习惯它没丢，wrapper 脚本叫 kotlin 和 kotlin.bat。

运行配置那边也能直接用，设备栏里挑 iPhone 17 | iOS 27.0 就能跑 iosApp。

那你要不要换

官方 FAQ 里有一段，直接回答为什么不去改 Gradle，我把原话贴出来：

With the Kotlin Toolchain, we want to show you our design and get your feedback,
as it will help us to decide which direction to take the design. At the same time,
we are also working with the Gradle team to improve Gradle support in our IDEs
and Gradle itself.

译文：我们想把设计摆出来给你看，靠反馈决定往哪走。同样的时间，我们也在和 Gradle 团队一起改进 IDE 里的 Gradle 体验，以及 Gradle 本身。

话说得客气，意思很清楚：这不是要把 Gradle 换掉，是一次同台展示。

迁移那件事也有意思。Maven 项目给了转换命令 kotlin tool convert-project，能自动转一部分。Gradle 项目没有工具，官方解释是 Gradle 脚本本身是任意代码，写不出确定性的转换规则。

那怎么办？FAQ 里有一句让我停下来的话，大意是这种事 AI agent 挺擅长，配一套技能就行。我去看了那套技能，在 Kotlin 组织底下，叫 kotlin-agent-skills，1,071 星，十个技能文件，其中两个专门讲怎么从 Gradle 迁到 Kotlin Toolchain。

里面规矩写得很硬：每一个第三方 Gradle 插件只有三条路，砍掉、换成原生等价物、自己重写，不存在留着继续用的选项；而你自己写的 buildSrc 那套约定插件不算插件，算配置，要变成模块模板。

这句话值得抄在本子上。把构建脚本当代码看，AI 能帮你做机械翻译；把构建脚本当配置看，那套隐式约定才是迁移里最贵的东西。

收尾

这周的动作概括一下：Amper 这个名字退休，它留下的东西成了 Kotlin 的官方工具链，门面是一个 kotlin 命令加一份 YAML。

新项目值得试，三行配置编四个平台，这套体验确实舒服。老项目先别动，它还是 Alpha，官方自己都写了不保证所有迁移场景。

仓库和文档在这：

github.com/JetBrains/kotlin-toolchain
kotlin-toolchain.org

最后留个问题：如果让你现在把手上的 KMP 项目从 Gradle 迁过来，你猜最先卡住你的是哪一步？

10 月 5 日 JetBrains 发了篇不长的公告，标题直白：KMP 插件里停掉 Swift 语言的 IDE 支持。生效版本写得很具体，IntelliJ IDEA 2026.3 和 Android Studio Rabbit 2 | 2026.2.2。

撤掉的功能清单也具体，我抄一下：

This includes editing, syntax highlighting, and navigation within Swift
files and between Swift and Kotlin.

译文：包括 Swift 文件里的编辑、语法高亮，以及 Swift 文件之间、Swift 与 Kotlin 之间的跳转。

看到这几行，很多人的第一反应是 KMP 的 iOS 是不是要凉。先别急，同一篇公告的第二段就把边界划出来了。

撤掉的是哪一层

原文第二段是这么写的：

Running iOS applications and debugging Kotlin code on iOS will remain fully
supported. Kotlin/Native functionality, such as Swift Export and importing
Swift packages into Kotlin projects, is not affected.

译文：运行 iOS 应用、在 iOS 上调试 Kotlin 代码，仍然完整支持。Kotlin/Native 的功能，比如 Swift Export 和把 Swift 包导入 Kotlin 项目，不受影响。

也就是说，被拿掉的是 IDE 里读改 Swift 的那一层。编译器、Native 工具链、跟 Xcode 对接的那条路都还在。

后半句我在这台机器上验了一遍。本机已经有 Kotlin/Native 2.4.0 的预编译包和 Xcode 26.2，我拿它把一份小代码编成 iOS 的 framework：

kotlinc-native -target ios_arm64 -produce framework -o out/shared src/shared.kt

九点八秒，产物是一个 Mach-O 64-bit arm64 的动态库，外加一份给 Xcode 用的头文件。这条链一步没退，撤 Swift 功能没动它。

那 iOS 到底靠哪几条链跑起来

把链路拆开看，顺序是这样：

1. Kotlin/Native 把共享代码编成 Apple 能用的 framework，就是我上面那九点八秒。
2. Xcode 把这个 framework 链进 iOS 应用，Gradle 里那条 embedAndSignAppleFrameworkForXcode 干的就是这件事。
3. Swift 壳调 Kotlin。现在主要走 Objective-C 头文件那套互通，官方另外在推 Swift Export，还在 Alpha，目标是让 Kotlin 直接导出成 Swift 模块，省掉头文件那一层。
4. IDE 里读改 Swift 只是开发时的顺手，撤掉它，上面三层一步没动。

想明白这四条，公告的轻重就出来了。

他们为什么撤

官方给的理由是使用量。他们的埋点和用户调研显示，做 KMP 项目的 iOS 开发者多数用 Xcode 写 Swift，而在 KMP 插件里干活的人越来越多用 Kotlin 和 Compose Multiplatform。

还有一层历史包袱：这套 Swift 工具最初是给 AppCode 开发的，而 AppCode 早就停了；后来挪到 Fleet，再挪进 KMP 插件。要让它的核心架构跟上 Swift、Xcode 和 IntelliJ 平台的持续变化，投入不小。他们权衡之后决定不做，并且写明目前不打算用别的功能替代。

这个取舍其实跟 KMP 这几个月的动作是一条线：他们把力气花在让 Kotlin 侧更好，而不是替 Xcode 干活。

社区那边的进度，比二手报道新

同一天热榜上还有另一条，方向正好相反。开源 OSM 编辑器 StreetComplete 的 iOS 版进了 TestFlight，这是它多年移植工作后的第一个可测版本。

这个移植从 2023 年 12 月开的追踪 issue 算起，到现在还 open 着，累计 51 条评论，维护者说全量移植大概是一人年的工作量，2024 年上半年靠 Prototype Fund 的资金全职推进，到当年 9 月完成约一半。

二手报道里有个说法已经过期了。它写 Compose Multiplatform 的 MapLibre 地图库还不存在，是移植的卡点。我去读了 StreetComplete 的构建文件，现在写的是这行：

implementation("org.maplibre.compose:maplibre-compose:0.19.0")

这个库在 Maven Central 上从 0.11.0 一路发到了 0.19.0，那个缺口已经补上。

代价也得说清楚。原型基金到期了，维护者在 issue 里写后续资金不乐观，OpenStreetMap 没钱，NLNet 的项目也在收缩，众筹这几家赞助没涨。已知问题还挂着：iOS 15.x 上地图不工作，表单只能用手势返回，bug 还多。

我数了一遍它的仓库

顺手把这个仓库按源集数了一遍，比看新闻有说服力：

• commonMain：1,281 个 Kotlin 文件，3.6MB
• commonTest：287 个文件，1.3MB
• androidMain：34 个文件，43KB
• iosMain：33 个文件，42KB

也就是说，两端各补四十多 KB 的壳，就把同一个 app 接到了 iOS 和 Android 上。iOS 侧那 33 个文件里，最大的一块是 IosModule.kt，六千字节，干的是依赖注入装配，剩下的都是网络、同步、上传、周期清理这类平台专属件。

看清这个比例，公告的影响面也就清楚了：撤掉的功能，作用范围就是这四十二 KB 的壳，和共享的三点六 MB 无关。

这两件事其实是一件事

JetBrains 的选择是「Kotlin 侧我做好，Swift 侧交给 Xcode」。StreetComplete 的做法正好配合这个分工：共享逻辑和 UI 都写在 Kotlin 和 Compose 里，Swift 那边只留一层壳。

所以判断很简单，问自己几句：

• 你项目里的 Swift 平时在哪儿写。本来就是 Xcode 开着，这条公告对你几乎没影响。
• 你要是在 Android Studio 里统一读改 Swift，那从现在起要改流程，或者用旧版本。
• 别把 IDE 支持和编译链支持混着看。前者撤了，后者没动。
• 技术路线通，不等于项目能到终点。StreetComplete 这一条提醒的是钱和人。

手上这个版本还能用多久

门槛是 Android Studio Rabbit 2 | 2026.2.2 和 IntelliJ IDEA 2026.3，本机装的是 2026.2，所以你现在手里那些 Swift 功能还在，只是往后不再更新。急着用就晚点再升，不急就随它去，反正 Swift 真正的家一直是 Xcode。

你的 KMP 项目里，iOS 那侧的 Swift 是在哪儿写的？评论区聊聊。

参考资料：

• https://blog.jetbrains.com/kotlin/2026/10/discontinuing-swift-language-ide-support-in-the-kotlin-multiplatform-plugin/
• https://github.com/streetcomplete/StreetComplete/issues/5421

你写 Kotlin Multiplatform 的时候大概遇到过：IDE 里那行代码红着，划红线说找不到符号，你犹豫半天不敢提交，结果一构建，绿的，跑起来还对。

以前我们把这事归给 IDE 抽风、索引没建好、清一下缓存。9 月 28 日 JetBrains 发了篇博客，开头第一句就直白得很：

The current compilation approach to Kotlin Multiplatform projects works, but sometimes can lead to unexpected or hard-to-predict behavior.

翻译成人话：现在这套编译方式能跑，但有时候会给你难以预测的行为。然后它列了两个例子，都是我们遇到过但说不清原因的：

The IDE analysis disagrees with the compiler on an overload, type inference, or whether the code should compile at all – with the IDE being stricter than the compiler.

Your commonTest code can unexpectedly call something from a platform source set, breaking your assumptions.

一句是 IDE 比编译器严格，一句是 commonTest 会悄悄调到平台源集的东西。下面我先把机制讲清，再给我实测的结果，因为官方那个例子里，修法的代价只给你看了一半。

为什么会有这种分歧

关键在「common 代码编译时，是拿什么去解析依赖的」。

KMP 模块里，commonMain 不是独立编出来一个产物就完事。编 JVM target 的时候，编译器把 commonMain 和 jvmMain 一起，对着依赖的平台产物（JVM 上是 jar）来编。于是 commonMain 里的调用，有机会隐式落到依赖方 jvmMain 的声明上。

而 IDE 的代码分析不这么干。它假设 common 代码只能看见依赖的 common 声明，也就是 metadata KLIB 里列出来的那部分。jvmMain 的声明不在里面，所以 IDE 报红。

两边对同一行代码有两套理解，谁都不算错，但你会被夹在中间。官方还给了一个更难受的版本：重载选择不一致，IDE 跳转到 commonMain 的重载，运行时打印的却是平台那一个。

以及类型推断分歧，common 侧推出来是 Any，JVM 编译直接报 Unresolved reference。这条反过来也成立：同一个例子开着开关，common 阶段就把 currentEvent() 的返回类型定成 Event，.name 有依据，JVM 编译直接通过。所以这个特性两头都会发生，既会让侥幸能过的代码报错，也会把原来报错的代码修好。

上面这两条路径的差别，画出来是这样：

新方案就是一个开关

Kotlin 2.5.0-Beta1 引入了一个可选的「分离编译」（separate compilation），让编译器在编 common 源集时也走 metadata KLIB 那套严格解析，跟 IDE 对齐。

# gradle.properties
kotlin.kmp.separateCompilation=true

官方标了 Experimental，默认关闭。附带一个好处：它让 common 源集的增量编译成为可能，这是以前做不到的。

官方给的例子读起来很轻松，原来 IDE 报红、编译却能过的代码，现在编译也报错；把 expect/actual 显式连起来就好了。

实测一：它真的会拦下来

我在本机搭了个最小的 KMP 工程（Kotlin 2.5.0-Beta1，两个 target：jvm 和 js），两个模块：

lib/  src/commonMain/Marker.kt      # 只有接口
      src/jvmMain/Foo.kt            # class Foo，只声明在平台源集
app/  src/commonMain/Main.kt        # 直接 new 一个 lib 的 Foo

app 依赖 lib，app 的 commonMain 里 new 一个只存在于 lib/jvmMain 的类。

不打开开关：

> Task :app:compileKotlinJvm
BUILD SUCCESSFUL in 30s

打开开关，同一份代码：

e: app/src/commonMain/kotlin/Main.kt:3:12 Unresolved reference 'Foo'.
e: app/src/commonMain/kotlin/Main.kt:6:13 Unresolved reference 'Foo'.
BUILD FAILED in 2s

官方说的没错，而且拦得很干脆，不是警告。

commonTest 那条也一样。我在 app 的 jvmMain 放了个 PlatformOnly 类，让 commonTest 去 new 它：关着开关 BUILD SUCCESSFUL，打开就是 Unresolved reference 'PlatformOnly'。

实测二：修法的代价，官方例子没给你看

官方的修法是显式 expect/actual。lib 的 commonMain 声明 expect，平台源集给 actual。我照着改，JVM 端确实过了：

// lib/commonMain
expect class Foo()

// lib/jvmMain
actual class Foo actual constructor()

开着开关，:app:compileKotlinJvm 是 BUILD SUCCESSFUL in 1s。这一半官方说得对。

然后我去编同一个模块的 JS 端：

e: lib/commonMain/kotlin/Marker.kt:5:1 The 'expect' declaration 'lib.Foo'
   has no 'actual' declaration in module '<commonMain> for JS'.
BUILD FAILED in 2s

expect/actual 是成对契约，每个 target 都得补一个 actual。博客里的例子只演了 JVM 那一侧，你多平台项目里一开，有几个 target 就是几份 actual。

官方没提的一件事：版本号不是门槛

博客说这个特性是 Kotlin 2.5.0-Beta1 引入的。我拿同一份「坏代码」在 Kotlin 2.4.20（当前稳定版）上又试了一遍：

# 不加这个属性
BUILD SUCCESSFUL in 704ms

# 加上 kotlin.kmp.separateCompilation=true
e: app/src/commonMain/kotlin/Main.kt:3:12 Unresolved reference 'Foo'.
BUILD FAILED in 11s

属性在 2.4.20 上照样切换行为，我核过这份工程确实解析到 kotlin-gradle-plugin:2.4.20。

所以这个开关不是 2.5 才存在的东西，只是官方到 2.5.0-Beta1 才把它当特性讲出来。反过来看：别把版本号当门槛，也别把「我 2.4 上试了没事」当结论，两边都不牢靠，得在你自己的工程上跑一遍才算数。

一张速查表

把上面这些现象和官方那节 Known issues 收成一张表，撞上对应情形时对着看：

你的项目该不该开

结合官方那节 Known issues，我的判断清单是这样：

• 依赖的库有没有正经发 metadata KLIB。新方案让它从「最好有」变成「必须有」，作者偷懒的库一开就报错，而错不在你。
• 工程有多依赖「common 调平台」这种写法。我手上那个 KMP 项目平台差异走接口、几乎不写 expect/actual，开之前得先把这类调用扫一遍，否则会一次性冒出一堆 Unresolved reference。
• 用不用 cinterop。官方点明了这两处已知问题（KT-88178、KT-41509），原生 C 互操作的项目要谨慎。
• 只有一个 target 的模块不受影响，官方说得很直白。
• 它还是 Experimental，默认关着。当预览用，别当升级项。

顺带一句 iOS 那条战线

同一周 JetBrains 还发了篇 TeamCity 的设计复盘，讲怎么把 Kotlin Multiplatform 的 iOS 打包做成引导式流程：装个插件，push 之后 IDE 弹一个 Configure CI 的提示，跟着走就能从首次 push 到跑测试、签名、发 TestFlight，最后接上 GitHub 每次推送自动跑。

中间生成四个文件（teamcity.yaml 加 Fastfile、Appfile、Gemfile），先留在你本地不提交，第一次构建跑在托管的 macOS agent 上，验过再让你自己提交。

这块我没实测，本机没有 TeamCity 账号，那段内容全部来自官方那篇设计复盘和它指向的官方教程。

最后

回到开头那个 IDE 报红、编译能过的瞬间。它过去既不是 IDE 的 bug，也不是你的错觉，是两套解析规则长期没对齐。官方现在的做法是把编译器往 IDE 那边拉：更严格、更可预测，代价是以前侥幸能过的代码，要先补成显式的。

我下一步想在手上那个 KMP 项目里开一次，把冒出来的 Unresolved reference 全列出来，看看这个项目到底欠了多少 expect/actual。

你的 Kotlin Multiplatform 项目开过这个开关吗？开完报了多少错？评论区聊聊。

参考资料：

• A More Reliable Compilation Scheme for Kotlin Multiplatform Modules：https://blog.jetbrains.com/kotlin/2026/09/a-more-reliable-compilation-scheme-for-kotlin-multiplatform-modules/
• Designing the Kotlin Multiplatform and TeamCity Integration：https://blog.jetbrains.com/teamcity/2026/09/designing-the-kotlin-multiplatform-and-teamcity-integration/
• 官方 iOS CI/CD 教程：https://kotlinlang.org/docs/multiplatform/ios-ci-cd-teamcity.html

同一份 JSON，同一个 App，同一次运行。

第一张，表单是满的：访客 Ada Lovelace、日期 Oct 1, 2026、时间 7:30 PM、人数 2，下面两个按钮 Cancel 和 Confirm booking，全套 Material 3 的原生控件。

第二张，同一个表单，字段全空。不光空，两个日期时间控件的标签都没了，只剩两个灰色圆角空框。

差别只在于我什么时候把 updateDataModel 这条消息发进去。前一秒和组件一起发，字段就丢；晚一秒单独发，字段就落上。这条我后面细说，它是我这次踩到的最值钱的一个坑。

A2UI 是什么

一句话，官方原话：

A2UI (Agent to UI) is a declarative UI protocol for agent-driven interfaces. AI agents generate rich, interactive UIs that render natively across platforms (web, mobile, desktop) without executing arbitrary code.

agent 不吐 HTML 或者 JavaScript，它吐一段声明式 JSON 描述界面长什么样，客户端拿自己的原生组件把它渲染出来。官方给的对照场景特别典型：

User: “Book a table for 2 tomorrow at 7pm” Agent: “Okay, for what day?” User: “Tomorrow” Agent: “What time?”

来回三轮只为填一个表单。换成 agent 直接生成一个带日期选择器、时间选择器和提交按钮的表单，用户是在操作界面，不是在跟它说话。

这套协议里我觉得最聪明的设计是 catalog（组件目录）。它不是让 agent 自由发明界面，而是先由客户端声明一份契约：我可以用这些组件、这些属性、这些本地函数。agent 只能在契约里挑选和组合。协议原文写得很直白：

Rather than having an agent generate arbitrary UI code or invent unregistered components, the catalog acts as a contract that defines the specific UI elements, properties, and functions available to the agent.

加上「传的是数据不是代码」这条，安全上的账就好算了：没有 iframe，也没有任意代码执行。

Compose 这边的官方渲染器

9 月 23 日 AndroidX 发了 Jetpack Compose 的 A2UI 渲染器，1.0.0-alpha01。我在 Google Maven 上逐个确认过这些 artifact 都存在：

implementation("androidx.a2ui.compose:compose-runtime:1.0.0-alpha01")  // 基于 Compose Snapshot 状态做细粒度重组
implementation("androidx.a2ui.compose:compose-ui:1.0.0-alpha01")       // 组件与 catalog 定义
implementation("androidx.a2ui:a2ui-model:1.0.0-alpha01")               // 协议数据层
implementation("androidx.a2ui:a2ui-engine:1.0.0-alpha01")              // 解析、schema 校验
implementation("androidx.compose.material3:material3-a2ui:1.0.0-alpha01")  // Basic Catalog 的 Material 3 实现

material3-a2ui 就是成品：Basic Catalog 的 Material 3 实现，一行就能起。你要给它补的是图像、视频、音频播放器，以及打开 URL 和处理本地化文案的回调。官方故意不带 Coil 和 Media3：

The A2UI libraries intentionally don’t bundle external media and networking dependencies, such as Coil, Glide, or Media3. Instead, you provide your own renderers.

还有一个 KMP 开发者会立刻关心的问题。我拆了 compose-runtime 的 Gradle module 元数据：

- releaseVariantReleaseApiPublication     type=aar
- releaseVariantReleaseRuntimePublication type=aar

只有 aar，没有 klib 也没有 JVM 变体。这一版是 Android 独占，Compose Multiplatform 现在用不上。

最小接线

数据层就两个对象：一个 parser，一个 processor。

private val parser = A2uiMessageParser()

private val catalog = materialA2uiBasicCatalogV1(
    image = MaterialA2uiBasicCatalogV1Defaults.image { url, _, _, modifier, _ ->
        Placeholder("image", url, modifier)
    },
    urlOpener = { url -> Log.i(TAG, "open $url") },
    messageFormatter = { pattern, locale, args -> /* MessageFormat */ },
    localeProvider = A2uiLocaleProvider.Default,
)

private val processor = A2uiMessageProcessor(catalogs = listOf(catalog))
val surfaces = processor.activeSurfaces

init {
    viewModelScope.launch(Dispatchers.Default) { processor.collectMessages() }
    viewModelScope.launch(Dispatchers.Default) {
        processor.outboundEvents.collect { Log.e(TAG, "OUTBOUND: $it") }
    }
}

界面侧就是一遍遍历，把每个 surface 交给 A2uiSurface：

surfaces.forEach { surface ->
    key(surface.id) {
        A2uiSurface(surfaceModel = surface, modifier = Modifier.fillMaxWidth())
    }
}

喂进去的是三段协议消息，createSurface 开画布、updateComponents 描述组件树、updateDataModel 给绑定值：

{ "version": "v0.9",
  "createSurface": { "surfaceId": "booking",
                     "catalogId": "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json" } }

{ "version": "v0.9",
  "updateComponents": { "surfaceId": "booking",
    "components": [
      { "id": "root", "component": "Column", "children": ["title", "nameField", "actions"] },
      { "id": "title", "component": "Text", "text": "Book a Table", "variant": "h1" },
      { "id": "nameField", "component": "TextField", "label": "Guest name",
        "value": { "path": "/booking/name" }, "variant": "shortText" }
    ] } }

注意组件属性里的 value 不是值本身，而是一个 path，指向数据模型。这也是为什么第三段消息发不发得进去，决定你的表单是满的还是空的。

跑起来之后，坑一个接一个

下面每一条都是我真撞上、并且找到原因或绕法的，官方那两页文档一条都没写。

一、updateDataModel 跟 updateComponents 同一批发，会被静默丢弃。 这是最坑的一条。surface 正常出现，没有任何报错，所有用 path 绑定的属性一律空着。我把同样的字节晚一秒重发一次，字段立刻填上。logcat 里三条消息全是 parsed OK，surface 也变成了 1 个，但值就是没落：

parsed OK -> A2uiCreateSurfaceMessage surfaceId=booking
parsed OK -> A2uiUpdateComponentsMessage surfaceId=booking
parsed OK -> A2uiUpdateDataModelMessage surfaceId=booking
activeSurfaces.size=1 ids=[booking]

所以我最终的写法是：先发 createSurface 和 updateComponents，等 surface 出现之后再推数据模型。这刚好也是流式 agent 的真实顺序，算歪打正着。

二、catalogId 是 v0_9，不是 v0_9_1。 文档站上那段「stable」示例写的是 version: v0.9.1 和 .../v0_9_1/...。库里的真实常量是 protocol = v0.9 和 .../v0_9/catalogs/basic/catalog.json。parser 两种版本号都收，但 createSurface.catalogId 必须跟你注册的那个 catalog 的 id 完全一致，对不上 surface 就永远不出现，同样不报错。我的做法是干脆不从文档抄字符串，直接从库的常量里取。

三、processInput 不是 A2uiMessageProcessor 的方法。 它是 androidx.a2ui.model.processor 包里的顶层扩展函数，必须 import androidx.a2ui.model.processor.processInput，照文档那行直接抄会编译不过。

四、失败是静默的。 processInput 内部会把 A2uiException 吞掉，转成 processor.processError(...)，只从 outboundEvents 发出去。你要是没收集这个流（文档里收集了，但没说漏掉的代价），协议错误和解析失败就完全看不到，屏幕上只有一个白框。调试这个库的第一件事，是把 outboundEvents 接上。

五、material3-a2ui:1.0.0-alpha01 跟当前稳定版 Compose BOM 不兼容。 它的 POM 硬要 androidx.compose.* 1.13.0-alpha03，material3 还卡了个 [1.5.0-alpha28] 的严格区间。用稳定 BOM 解析出来的是 1.12.x，装不上。最后我把 BOM 摘掉，手动钉版本。

六、compileSdk 37 minor 1 的写法没文档。 compileSdk = 37 找不到已经装好的 android-37.1。能用的写法是：

compileSdk { version = release(37) { minorApiLevel = 1 } }

七、surface 的根组件 id 必须叫 root。 它是个私有常量，写成别的名字，你的 Column 就不是根。

八、枚举取值全靠猜。 这些值写错就是 schema 失败，而文档里没有：

Text.variant           h1 h2 h3 h4 h5 caption body
Button.variant         primary secondary borderless
TextField.variant      shortText longText number obscured

我的办法是 javap 拆 AAR 里的枚举，一个个读出来。

另外还有一条跟 A2UI 无关但绕不开的：AGP 9.x 下再挂 org.jetbrains.kotlin.android 会被直接拒掉，官方说 AGP 9.0 起 Kotlin 支持已经内置，只需要保留 compose 插件。

我的判断

能跑通，而且渲染出来的确实是原生 Material 3，不是套壳网页。但 alpha 阶段的文档跟不上代码：真实的 catalogId、processInput 的形态、消息时序、版本钉法，全得自己拆包看。这套东西现在适合做概念验证，别急着往生产里放。

KMP 侧要再等等。只有 aar 这一件事，就决定了 Compose Multiplatform 现在只能用 Android 那一头。

我下一步想试的是把 outbound 那条路走通：用户点了 Confirm booking，事件回到 agent，agent 根据结果再发一条 updateComponents 改界面。这条链路我只接了线，没真按过按钮，所以这一篇里不敢说它成不成。

你会让你的 AI Chat 客户端由 agent 直接生成界面吗？还是更愿意自己写死界面、只让 agent 填内容？评论区聊聊。

参考资料：

• A2UI 协议官网：https://a2ui.org/
• Jetpack Compose 的 A2UI 渲染器（官方文档）：https://developer.android.com/develop/ui/compose/agentic
• 自定义 catalog：https://developer.android.com/develop/ui/compose/agentic/manage-catalogs
• A2UI Compose 版本页：https://developer.android.com/jetpack/androidx/releases/a2ui-compose

验证边界：两张截图、三段消息的解析日志、catalogId 与协议版本常量、消息时序的 A/B 对照、构建与安装，都在本机跑真机模拟器得到（Android 模拟器 API 36.1，APK 13,471,211 字节，构建 BUILD SUCCESSFUL）。组件属性名与枚举取值来自 javap 拆包。按钮点击回传 agent 那条链路没有实测；图像/视频/音频用的是占位渲染器，没有接真实加载库。

用户在地铁里改一份清单：新建两层、给其中一层改名、把不要的那一层删掉。整个过程离线，回到地面才上传。

你希望数据到服务端时是一笔事务。可如果客户端是按行标记同步状态的，这一笔就会被拆成几笔各自为政的请求，其中任何一笔失败，账号里就留下半截数据。

Nitivakya 的作者 premi jit chowdhury 最近把这次返工写成了文章。这个 App 用 KMP + SQLDelight + Supabase，原本只是每日一句古语，靠一张 favoriteEntity 上的 localState 字段（DIRTY / SYNCED / DELETED）就活得挺好。直到他加了 Actions，结构变成 Action 到 Action Levels 再到 Action Level Items 的嵌套树。

A row-level flag tracks final row state, not multi-entity mutation intent.

他的原话是，行级标记记录的是这一行的最终状态，不是多实体变更的意图。这句话是整个返工的起点。

三处具体的塌方

他在帖子里列了三条失败，我先照抄再消化。

2 separate table REST calls caused foreign-key 500 errors over shaky connections. Full-snapshot uploads risked overwriting server-calculated streak progress. Row-level flags couldn’t express a simultaneous “Create Level A + Update Level B + Delete Level C” edit.

子表先到、父表后到，服务端直接回外键约束错误，子行永久卡在 DIRTY。绕开分散请求、改成整棵快照上传，又会把服务端自己算的连续打卡记录覆盖掉。第三条最难绕：一个保存手势里的增删改混在一起，行标记根本表达不了。

我认同的判断是，问题不在于状态标错了，而在于行级标记这个粒度天然承载不了「这次编辑到底发生了什么」。

他的新架构：本地态给 UI，outbox 管上传

改完之后的形态是两层分开。本地实体表保留 localState，只用来给 Compose 渲染状态点；同步交给一张汇总的 outbox 表，里面存稀疏 JSON DTO，只带这次真正改动的字段。

CREATE TABLE syncQueueEntity (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  userId TEXT NOT NULL,
  type TEXT NOT NULL,
  operation TEXT NOT NULL,
  entityId TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'PENDING',
  createdAt INTEGER NOT NULL,
  payload TEXT,
  UNIQUE(userId, type, entityId)
);

那个唯一约束是关键，同一实体的多次编辑被收敛到一行。Kotlin 侧的 withSync 在同一个数据库事务里做三件事：执行本地写入、把新 payload 深合并进队列里的旧 payload、碰上先建后删就把队列行直接删掉。

入队用 ON CONFLICT 加一层状态机守卫，避免把「离线新建」误标成「更新」：

INSERT INTO syncQueueEntity (userId, type, operation, entityId, createdAt, payload)
VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT(userId, type, entityId) DO UPDATE SET
  operation = CASE
      WHEN syncQueueEntity.operation = 'INSERT' AND excluded.operation = 'UPDATE' THEN 'INSERT'
      ELSE excluded.operation
  END,
  status = 'PENDING',
  createdAt = syncQueueEntity.createdAt,
  payload = excluded.payload;

上传时不再分表调用，而是一个 Supabase RPC 进 PostgreSQL。函数体里先 FOR UPDATE 锁住那一行，再依次做删除与 upsert，整个函数本身就是一个事务。

CREATE OR REPLACE FUNCTION public.update_action(
    p_action_id uuid, p_updated_at timestamptz,
    p_action_updates jsonb DEFAULT NULL,
    p_levels_upsert jsonb DEFAULT NULL,
    p_levels_delete uuid[] DEFAULT NULL,
    p_items_upsert jsonb DEFAULT NULL,
    p_items_delete uuid[] DEFAULT NULL)
RETURNS void LANGUAGE plpgsql SECURITY INVOKER AS $$
BEGIN
    PERFORM 1 FROM public.actions WHERE id = p_action_id AND user_id = auth.uid() FOR UPDATE;
    IF p_levels_delete IS NOT NULL THEN
        DELETE FROM public.action_levels WHERE id = ANY(p_levels_delete);
    END IF;
    -- 接着是 levels 与 JSONB items 的原子 upsert
END;
$$;

我拿本机跑了一遍

文章里的 SQL 我照着在 sqlite3 3.54.0 上跑了一遍（脚本 /tmp/kmp-article/outbox.sql 与 atomicity.sql），三段结论都对得上。

先在离线状态 INSERT，再对同一实体 UPDATE，operation 确实还是 INSERT，createdAt 也没被刷新，只有 payload 换成了新的。

而 INSERT 之后直接 DELETE，SQL 这一层兜不住：行还在，operation 变成 DELETE，payload 被 NULL 冲掉。作者说这种自我抵消是在 Kotlin 事务里做的，实测坐实了这个分工。

外键那条也复现了。先插子表得到 FOREIGN KEY constraint failed，放进事务里则回滚得干干净净，父表子表都没留下半行。这就是他坚持走 RPC 而不是分表 REST 的核心理由。

Kotlin 侧我用 Gradle 缓存里的 kotlinc（kotlin-compiler-embeddable 2.4.10）编译跑了 deepMerge 与抵消逻辑。四次离线编辑，新建 level-3、给 level-3 改名、新建 level-4、删掉 level-4，最后收敛成一行一条 payload：

队列行 entityId=action-101 operation=INSERT
合并后 payload={"levelsUpsert":{"level-3":{"title":"Deep Meditation","sequence":3},
"level-4":{"title":"Breath Work","sequence":4}},"levelsDelete":{"level-4":{"id":"level-4"}}}
入队次数=4，最终队列行数=1

换成新建 action-202 再删除，队列里一行都不剩，网络调用是零。

我实测撞上的一个边界

上面那条 payload 里，level-4 同时出现在 levelsUpsert 和 levelsDelete 里，它既被创建又被删除。

作者的 deepMerge 只做键级合并，不会跨这两个 map 去抵消同一个实体。所以「先建后删」的自动抵消只覆盖了 INSERT 加 DELETE 这一层，也就是整行取消；同一层里「建了又删」要靠服务端 RPC 按顺序处理，或者客户端在合并时自己剔除。

换句话说，稀疏 payload 省掉了整树上传的代价，但它把一部分冲突消解的活分给了两个地方：客户端的事务，和服务端函数的执行顺序。这两处只要有一处逻辑不齐，就会出现本地看着删了、服务端还留着的状态。

拿去自查的四条

第一，你的行级标记记录的是最终状态还是变更意图。如果是前者，嵌套结构一上来就会露馅。

第二，子实体先于父实体到达服务端会怎样。如果答案是报错然后卡在 DIRTY，那你的同步链路上少了一个原子入口。

第三，整棵快照上传会不会覆盖服务端算出来的字段。打卡、积分、统计这类字段最容易被静默改写。

第四，插入又删除这种自我抵消，你是在客户端做的还是留给服务端。两边都做不算坏事，两边都没做就是数据缺口。

最后

这次返工值得看的地方，不是 outbox 这个模式本身，而是作者把「什么时候该换架构」写清楚了：简单的一对一标记，行级 flag 够用；一旦出现嵌套的复合编辑，就该把变更意图当成一等公民存起来。

你怎么处理复合离线编辑？欢迎在评论区聊聊你的方案。

参考资料：

• 原文：https://premjitchowdhury.medium.com/when-offline-sync-relying-only-on-local-state-breaks-and-how-i-fixed-it-in-nitivakya-kmp-245e05892ac3
• 原帖：https://www.reddit.com/r/Kotlin/comments/1wrdk0q/when_offline_sync_relying_only_on_local_state/
• Supabase 数据库函数与 RPC：https://supabase.com/docs/guides/database/functions

验证边界：文中 SQLite 的三段结论与 Kotlin 的合并逻辑在本机真跑过（sqlite3 3.54.0、kotlinc 2.4.10）；Supabase RPC 函数与 PostgREST 的真实行为没有连项目验证，函数体摘录自原文。

网盘客户端这东西不算新鲜，但「一套代码双端跑」这句话我今年听得太多了，多到有点麻木。所以真正让我停下来的不是它支持双端，是它把双端这件事做成了什么形状。

我把仓库拉下来数了一遍，然后在一个地方愣住了。

先把结构摆出来

Piko 是 Kotlin Multiplatform 加 Compose Multiplatform，五个模块，实测的代码量是这样：

• shared 状态与业务，commonMain 79 个文件
• ui 共享界面，commonMain 74 个文件，只有这一个 source set
• app Android 入口，22 个文件
• desktopApp 桌面入口，29 个文件
• cli 开发用的命令行工具，不上线

前两个加起来 153 个文件、3 万 1 千多行 Kotlin，是两端共用的部分。后两个是两端的入口，加起来 51 个文件、8 千多行。

看到这里还算正常。不正常的是我接着敲的这条命令。

一行 expect/actual 都没有

在 KMP 里，平台差异的教科书答案就是 expect/actual：公共代码里写 expect fun，各平台 source set 里写 actual fun。我本来想数数它用了多少处，好写进文章当例子。

grep -rn "^\s*expect " --include="*.kt" shared ui app desktopApp
expect 声明: 0
actual 实现: 0

我以为是自己的正则写错了，换了几种写法，结果一样。一个 3 万 1 千行共享代码、全仓库 4 万 6 千行 Kotlin 的项目，expect/actual 用了零次。

更奇怪的是 source set 的分布。它的 shared 里没有 androidMain，ui 里连 desktopMain 都没有，shared 唯一一个平台相关的 source set 叫 jvmSharedMain，里面只有一个文件、67 行。

这就不是「用得少」了，是压根换了一套做法。

它的答案：接口，加运行时注入

作者在自己的架构笔记里写了一句话，我觉得比教程里任何一段都值钱：

平台差异用接口，不用 expect/actual

理由是这句注释，写在能力的接口定义上：

实现要拿 Context、窗口与各自的播放后端，这些都是运行时对象，不是编译期的平台差异。

这句话点破了我以前的糊涂账。expect/actual 解决的是「编译期差异」，同一个函数名，两个平台各写一份实现，编译器帮你挑。但客户端真正要分家的东西，几乎全是运行时对象：Android 要拿 Context、要注册 ActivityResult 启动器、播放要走 libmpv 的 SurfaceView；桌面端要窗口句柄、要 MPV 的原生 DLL、播放画面要零拷贝进 Skia。这些东西的共同点是，它们在编译期看起来是同一种东西，只是构造方式不同。

而构造方式不同，恰恰是依赖注入最擅长的事。

它是这么做的。共用的 ui 模块里定义一个接口，叫 PikoPlatform，把界面要跟平台要的能力全列在里面：剪贴板、系统取色、下载目录选择、本地文件的打开与分享、全屏对话框、应用内更新。

两个入口各实现一份，AndroidPikoPlatform 和 DesktopPikoPlatform，最后在入口处拼进根界面 PikoApp(services, platform, appearance, videoPlayer)。界面内部通过 LocalPikoPlatform 取用，不再回头找单例。

平台没有的能力，用 null 说出来

接口方案最容易被嫌的地方是啰嗦：同样是「分享文件」，Android 有系统分享面板，桌面端没有对应物，那接口该怎么写。

它的处理是这样的。能力字段可以是可空的：

/** 为 null 表示该平台没有应用内更新。 */
val updater: AppUpdateService?

/** 为 null 表示该平台不提供片段下载的画面预览，入口随之隐藏。 */
val videoPreview: VideoPreviewSupport?

也有的写成布尔：

/** 系统分享面板。桌面端没有对应物时为 false，界面不显示「分享」。 */
val canShare: Boolean

还有更细的：软键盘是否弹出，桌面端恒为 false；快捷键主修饰键，Windows 是 Ctrl，macOS 给的是 ⌘，由一个 shortcutModifier 属性吐出来。

这套约定带来的好处是，界面只需要问一次「你能不能」，然后自己决定藏不藏入口，不需要为了一个只有单端存在的功能，在公共代码里到处塞平台判断。这类判断一旦多起来，公共代码就名存实亡了。

第三种手段：中间 source set

接口解决的是「两端真的不一样」。但还有一类代码是「两端完全一样，只是要用 JDK 的 API」。Piko 里这类代码的样本是网络代理选择器 PikoProxySelector，67 行。

它要把一个进程级的 ProxySelector 装进 JVM，理由是 SDK 内部自己建 OkHttpClient，拿不到构造参数，只能从全局进去。这段代码在 Android 和桌面端一字不差。

如果按教科书走，这就是两份 actual，内容复制粘贴。它的做法是在中间加一层 source set，用构建脚本声明这个组里同时装两种 JVM 目标：

applyDefaultHierarchyTemplate {
    common {
        group("jvmShared") {
            withCompilations {
                it.platformType == KotlinPlatformType.jvm ||
                    it.platformType == KotlinPlatformType.androidJvm
            }
        }
    }
}

jvmSharedMain 这个目录就这么来的。写完一份，两个 JVM 系目标都编译它。这个手段我在这篇文章之前没在任何教程里见过，但它是三个手段里省事最多的一个。

所以到这儿，KMP 划边界的手段其实有三档：

1. 能共用就直接放 commonMain，这是绝大多数代码的位置
2. 两端行为真的不同，用接口加运行时注入
3. 两端代码相同、只是要用 JDK API，加一个中间 source set

expect/actual 是第四档。它没被用，是因为前三档刚好覆盖了这个项目的全部需求。我现在的看法是，expect/actual 更像是给「纯声明式差异」准备的，比如一个常量、一个没有运行时状态的函数。真正复杂的客户端，落到那一档的东西比想象中少。

那 3 万 1 千行共享代码长什么样

ui/src/commonMain 是整个界面：主题、导航、网盘、传输、设置、回收站、登录，加上各种组件。入口是 PikoApp，两端各自把依赖拼好再传进去。

Android 这边在 Application 里装配：

val clientManager = PikoClientManager(AndroidPikoSessionStore(this, sessionManager), appScope)
services = PikoServices(
    preferences = sessionManager,
    clientManager = clientManager,
    downloadManager = PikoDownloadCoordinator(
        storage = AndroidPikoDownloadStorage(this, sessionManager, appScope),
        segmentDownloader = AndroidPikoSegmentDownloader(this),
        // ...
    ),
    uploadSources = AndroidPikoUploadSources(this),
)
platform = AndroidPikoPlatform(this) { appUpdater }

桌面端在 main 里装配，形状一样，实现换了一套：DesktopPikoPlatform(settings)、DesktopPikoDownloadStorage、FilePikoSessionStore。会话存储这个例子最能说明问题，公共接口只有 21 行：

interface PikoSessionStore : SessionStore {
    suspend fun loadLastAccount(): String?
    suspend fun saveLastAccount(account: String)
    suspend fun loadCredentials(account: String): PikoCredentials?
    // ...
}

Android 侧走 DataStore，桌面端往 ~/.piko 下写文件。界面和业务代码完全不知道这件事。

这里有个我觉得挺值得留意的对照：接口规定了两端要做什么，但管不住两端实现得差多远。我翻了桌面端那份实现，它把会话、账号、密码分开写在 ~/.piko 的三个文件里，密码那一个是明文写的。自己的机器上自用没什么问题，多人共用的机器上就值得掂量一下。同一件事，同一份接口，两端的严谨程度可以差出一截。

踩坑提醒

它的架构笔记里记了不少实测出来的坑，我挑几个跨平台的记下来。

两端的 Compose 版本可以对不上，同一行代码可能只在一端报错。 它桌面端的界面库钉在 Compose Multiplatform 1.12.0，Android 端由 BOM 决定。原因很具体：CMP 1.13 带的 skiko 把渲染后端包进了 OnScreenRedrawer，而它用的播放库要从里面直接拿 Direct3DRedrawer 做 D3D11 画面直通，一开播放器窗口就抛异常。所以这个项目里，升级 CMP 不是改一个数字的事，得等上游播放库跟上。

Android 端的 Compose 反而要退回稳定版。 它的版本目录里写着：1.13 的 alpha 在列表快速滚动时崩溃，可交互的 ListItem 在测量阶段读副文本基线，为对齐而摆放的子节点去查找尚未入表的父节点。BOM 因此换成稳定版，ui 与 foundation 落到 1.12.x。

改共用模块必须两端都编译。 作者把这句话直接写进了给协作者看的文件里，因为 shared 和 ui 的改动会同时波及两个入口模块，只编译一端看不出来。而两端的 material3 版本本来就不是一个，同一行代码完全可能只在一端报错。

加一个偏好项要同时改三处。 公共接口一处，Android 的 DataStore 实现一处，桌面的设置存储一处。同类的还有全局导航栈：主界面的位置放在仓库层并持久化，所以目录选择器这类浮层必须自己维护一份路径栈，动了仓库层那份，主界面的位置会跟着跑。

依赖要用 api 而不是 implementation，是有原因的。 shared 用了 api(libs.cmp.runtime)，因为它对外暴露的状态类型直接是 Compose 的 State，消费方拿得到这些类型才能编译。反面例子是 kotlinx-serialization：SDK 那边以 implementation 声明，不会传递过来，调用方得自己引一份。

一个许可证细节：源码是 MIT，但 Android 安装包整体是 GPLv3。 因为它内置的 mpv 与 FFmpeg 是以 GPL 构建的。自己用没关系，想二次分发要看清楚这一点。

它跑起来是什么样

Piko 的官方 README 里有各端的截图，我挑两张放这儿，上面是 Android，下面是同一个窗口里的桌面端。

两张图值得对比的不是内容，是导航。手机上导航栏在底边，桌面窗口里挪到了左侧，中间那层判断只看窗口宽度，不看是什么设备。所以桌面缩窄到一定程度会变成手机的样子，平板分屏走的是同一套判断。这层自适应也写在共用代码里。

功能上它做得比我预期的多：磁力链接能按作品、分区、集数解析，字幕跟着视频归组，广告文件自动排除，保存之前可以先完整预览再勾选要的文件。播放进度跟 PikPak 官方客户端同步，下载和在线播放都是 8 条连接并发。还支持无损截取视频片段、上传、服务端解压、全盘搜索、查找重复、看网盘用量和本月流量。

值得一提的是它的开发方式，提交记录里能看到 Claude 的协作者署名，README 里也写了用 LLM 辅助写代码时的要求：理解新增代码的逻辑，并在真机上验证。作者在帖子里说配色这块自己审美欠缺，这套界面是 M3 生成加人工调的。

最后

小项目要双端，我的建议是先把 shared 和 ui 切出来，让它俩干干净净地只剩 commonMain，平台实现全部塞进两个入口模块。这样每次想偷懒往共用模块里加平台判断的时候，都会先卡一下。

PikoProxySelector 那 67 行给我印象最深。它本来最像需要 expect/actual 的地方，最后是加了一层 source set 解决的。手段够多的时候，你反而不会去动那个最笨的。

项目地址：https://github.com/NihilDigit/piko

java.lang.IllegalStateException: user 42 not found
	at demo.ChainKt.fetchUser(Chain.kt:11)
	at demo.ChainKt$fetchUser$1.invokeSuspend(Chain.kt)
	at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:34)
	at kotlinx.coroutines.DispatchedTaskKt.resume(DispatchedTask.kt:233)
	at kotlinx.coroutines.DispatchedTaskKt.dispatch(DispatchedTask.kt:152)
	... 后面十几行全是协程内部

一行自己的代码，然后全是框架。你知道了出事的位置，但不知道是谁叫的它。fetchUser 在这个工程里被好几个地方调用，每一个都可能传进 42。

这不是偶发，是协程的常态。而修它只要加一个依赖。

为什么调用链会消失

协程的核心是把异步代码写成同步的样子。编译器把每个 suspend 函数改造成一个状态机，函数"返回"的时候并不是真的从 JVM 调用栈上返回，而是把结果交给 continuation，由调度器决定在哪、什么时候继续。

问题就在这个"继续"上。挂起的那一刻，中间那些帧已经从 JVM 栈上弹掉了；恢复执行时，是一个全新的栈——从调度器开始，直接跳到 fetchUser 的续体。loadProfile 和 renderScreen 在这个过程中没有任何帧留在栈上，异常自然也就找不到它们。

所以丢帧不是 bug，是这套机制的必然结果。Kotlin 团队知道这件事，也给过方案：打开 kotlinx.coroutines.debug 会启用 stacktrace recovery。

只是它救不回来。我在本地把这个例子跑了一遍，属性确认进了应用 JVM：

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug=on
java.lang.IllegalStateException: user 42 not found
	at demo.ChainKt.fetchUser(Chain.kt:11)
	at demo.ChainKt$fetchUser$1.invokeSuspend(Chain.kt)
	at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:34)

loadProfile 和 renderScreen 依然不在。这个官方机制只覆盖一部分场景，而挂起再恢复这条最常见的路径，恰好不在里面。

Decoroutinator 换了个思路

Stacktrace-decoroutinator 的做法是把协程恢复的这套实现整个替换掉，作者自己的说法比较直接：

Decoroutinator replaces the coroutine resumption implementation. It generates methods at runtime with names that match the entire coroutine call stack.

Decoroutinator 替换掉协程的恢复实现。它在运行时生成一批方法，方法名对应整条协程调用链。

These methods do nothing except call each other sequentially in coroutine call stack order, creating real JVM stack frames.

这些方法什么都不做，只是按协程调用链的顺序依次互相调用，从而造出真实的 JVM 栈帧。

翻译成人话：它不试图从 continuation 里"猜"调用链，而是真的把那些帧造出来。既然异常要靠 JVM 栈来找调用者，那就让栈上有东西可找。

项目是 Apache-2.0，⭐374，拿过 Kotlin Foundation 的 grants，最新版 2.6.6 是 9 月 10 号发的，仓库 9 月中旬还有提交。对一个小工具来说，这个维护状态算是相当健康。

先看效果，再讲怎么装

我把同一个源文件放进三个模块，唯一差别是 Decoroutinator 开不开。第一次运行是原始版本：

$ ./gradlew :plain:run
java.lang.IllegalStateException: user 42 not found
	at demo.ChainKt.fetchUser(Chain.kt:11)
	at demo.ChainKt$fetchUser$1.invokeSuspend(Chain.kt)
	at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:34)
	at kotlinx.coroutines.DispatchedTaskKt.resume(DispatchedTask.kt:233)
	...

整个堆栈 21 行，属于 demo. 这个包的只有 4 帧，其中两帧还是同一个函数。

加上装饰器之后：

$ ./gradlew :decoroutinated:run
java.lang.IllegalStateException: user 42 not found
	at demo.ChainKt.fetchUser(Chain.kt:11)
	at demo.ChainKt$fetchUser$1.invokeSuspend(Chain.kt)
	at kotlin.coroutines.jvm.internal.DecoroutinatorBaseContinuationAccessorImpl.invokeSuspend(base-continuation-accessor.kt:15)
	at dev.reformator.stacktracedecoroutinator.common.internal.Provider.callInvokeSuspendIfResultIsNotCoroutineSuspended(provider-impl.kt:123)
	at dev.reformator.stacktracedecoroutinator.provider.SharedSpec.$decoroutinator$resume(provider-api.kt:106)
	at demo.ChainKt.loadProfile(Chain.kt:15)
	at demo.ChainKt.renderScreen(Chain.kt:21)
	at demo.MainKt$main$1.invokeSuspend(Main.kt:8)
	...

31 行，demo. 包 7 帧。关键的不是行数变多，是这两行回来了：

	at demo.ChainKt.loadProfile(Chain.kt:15)
	at demo.ChainKt.renderScreen(Chain.kt:21)

renderScreen 第 21 行调了 loadProfile，loadProfile 第 15 行调了 fetchUser——完整的调用链，带行号。此时你一眼能看出是谁传进去的 42。

代码本身一个字没改。下面是装的三种方式。

JVM 上，一行插件就够

plugins {
  kotlin("jvm") version "2.3.21"
  application
  id("dev.reformator.stacktracedecoroutinator") version "2.6.6"
}

这是最省事的一条路。插件会在构建期往你的类里生成辅助方法，运行时不需要额外的 JVM 参数。

同一个库还有另外两种启用方式，都走 JVM instrumentation 而不是构建期生成：

# 方式二：JVM 启动参数
-javaagent:/path/to/stacktrace-decoroutinator-jvm-agent-2.6.6.jar

// 方式三：加依赖，然后在任何协程跑起来之前调一次
import dev.reformator.stacktracedecoroutinator.jvm.DecoroutinatorJvmApi

fun main() {
  DecoroutinatorJvmApi.install()
  // 之后照常跑你的代码
}

依赖坐标是 dev.reformator.stacktracedecoroutinator:stacktrace-decoroutinator-jvm:2.6.6。

方式三有个副作用值得先说：它靠动态加载 Java agent 来实现，JVM 会给你打一行警告——

WARNING: A Java agent has been loaded dynamically
WARNING: Dynamic loading of agents will be disallowed by default in a future release

现在只是警告，未来版本默认会禁掉。如果你的环境对这点敏感，用方式一或方式二更稳。

KMP 项目里，插件不管用

这部分是我这次踩得最实的坑，也是想写给 KMP 读者的主要原因。

看到插件用法，第一反应自然是把它挂到 multiplatform 模块上。我这么做了，结果堆栈一点没恢复——和没装一样。更麻烦的是当时还顺带报了另一个错：

Exception in thread "main" java.lang.NoClassDefFoundError:
dev/reformator/stacktracedecoroutinator/provider/BaseContinuationExtractor
	at demo.MainKt.main(Main.kt:6)

意思是插件确实改写了字节码，但把自己运行时需要的类留在了 classpath 外面。我照着插件在普通 kotlin("jvm") 模块里注入的那三个构件手动补上，NoClassDefFoundError 消失了——但堆栈依然没恢复。

原因不难推：这个插件只把自己接进普通 JVM 模块的编译任务，KMP 的 jvm target 编译任务不在它的接管范围内。所以字节码动了一点，真正负责生成"伪造调用链"的那部分没跑。

对 KMP 项目，正确做法是绕开构建期生成，改用运行期 instrumentation。两种都实测通过：

kotlin {
  jvmToolchain(21)
  jvm()
  sourceSets {
    jvmMain.dependencies {
      implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
      // 方式三需要它；用 agent 的话这一行可以不要
      implementation("dev.reformator.stacktracedecoroutinator:stacktrace-decoroutinator-jvm:2.6.6")
    }
  }
}

// 方式二：agent 只加在运行参数上，源码和依赖都不用动
val decoroutinatorAgent by configurations.creating
dependencies {
  decoroutinatorAgent("dev.reformator.stacktracedecoroutinator:stacktrace-decoroutinator-jvm-agent:2.6.6")
}
tasks.register<JavaExec>("runKmp") {
  mainClass.set("demo.MainKt")
  classpath = files(kotlin.targets.getByName("jvm").compilations.getByName("main").output.allOutputs,
                    configurations.getByName("jvmRuntimeClasspath"))
  jvmArgs("-javaagent:${decoroutinatorAgent.singleFile.absolutePath}")
}

这两种在 KMP 模块里都跑出了恢复后的堆栈，loadProfile、renderScreen 都在，demo. 包 7 帧。

还有一句必须说清楚的：Native 和 JS 目标用不了，而且不是配置问题。这库的原理是在 JVM 上造栈帧，没有 JVM 就没有这套机制。作者在 issue #5 里被问过要不要做多平台版本，回复是暂时没有计划——那个 issue 从 2022 年开到现在还开着。

所以 KMP 项目的实际选择是：只给 JVM/Android 侧装，iOS 侧照旧。如果你主要在看 iOS 崩溃，这篇帮不上忙。

几个已知的坑

官方 README 里列了几个，都是真的会撞上的：

• Android 只支持插件方式，而且它依赖 MethodHandle，需要 API 26（Android 8）以上。低版本会自动关掉恢复而不是崩，所以放心引入。
• 开了 R8/ProGuard 会失效。混淆会把运行时需要的代码改掉名，得把 decoroutinatorAndroidProGuardRules() 加到 release 的规则里。
• 和 Jacoco 一起用时覆盖率会丢。这是 Jacoco 自己的限制，解决办法是让 Jacoco 的 agent 排在 Decoroutinator 前面。
• Shadow 插件有已知冲突（shadow#882），要打 fat jar 的话得先看 workaround。
• Robolectric 会把它的类放进单独的 classloader，导致测试报错，需要在 packagesToNotAcquire 里排掉 dev.reformator.stacktracedecoroutinator.。

另外，如果只想在测试里用，官方推荐把测试放到单独的子项目里应用插件；不好拆的话有个开关：

stacktraceDecoroutinator {
  androidTestsOnly = true
}

想知道运行时到底装上没有，可以查状态：

DecoroutinatorCommonApi.getStatus { it() }

Android 那边它还能顺带把 DebugProbes 打包进去，配合 embedDebugProbesForAndroid = true 用，能在运行期 dump 协程状态。

要不要装

我倾向装，尤其是团队里还有人在用"加日志猜"的方式定位协程问题时。

它做的事很单一：让 JVM 栈上有真实的帧。没有 API 变化，没有侵入式的重构，删掉就是一个依赖的事。代价是运行时多了一层 instrumentation，以及上面那串坑——其中大部分只在 Android 打包场景才遇到，纯 JVM 项目基本无感。

有一点值得留意：它改变的是恢复实现本身。所以上线前值得在预发环境跑一轮，确认没有行为差异，而不是直接在核心链路打开。

完整的对照工程在 https://github.com/trewvip-arch/decoroutinator-kmp-demo

三个模块共用同一份源码，plain / decoroutinated / kmp，跑一遍就能看到本文所有堆栈输出的原始版本：

./gradlew :plain:run          # 不装，链是断的
./gradlew :decoroutinated:run # 插件方式，链完整
./gradlew :kmp:runKmp         # KMP + agent，链完整
./gradlew :kmp:runKmpInstall  # KMP + install()，链完整

实测环境：Stacktrace-decoroutinator 2.6.6、Kotlin 2.3.21、kotlinx-coroutines 1.11.0、JDK 21、macOS。文中所有堆栈输出都是真跑出来的。

Google 的 adk-kotlin 1.0 在 9 月 7 号 GA，1.1.0 是 9 月 15 号，Ktor 3.6.0 的构件 9 月 16 号上的 Maven Central。我拿这三个搭了个能用的东西：一个能自己查证「某个 KMP 库到底支不支持 iOS」的 agent，服务端和客户端放在同一个 KMP 工程里。

先交代一件事。写这篇文章的过程中我踩了个坑，照着源码写的请求体在真服务器上直接返回 400，而且不带任何错误信息。折腾了小半个钟头才定位到，是版本问题。这个放在后面单独讲，因为它比教程本身更值得记住。

这个 agent 解决什么问题

KMP 开发者最常问的一个问题是：「这个库支持 iOS 吗？」

README 经常不给答案，或者给的是过期的答案。真正权威的地方是库发布到 Maven Central 上的 Gradle module metadata——那个 .module 文件是构建过程生成的，里面列的就是这次编译真实产出的平台变体。

所以工具做的事很直接：把 .module 拉下来，解析出所有变体名，数一数里面有没有 iOS 相关的。

@Tool
fun checkLibraryPlatforms(
  @Param("Maven group id, e.g. com.google.adk") group: String,
  @Param("Maven artifact id, e.g. google-adk-kotlin-core") artifact: String,
  @Param("Version to check, e.g. 1.1.0") version: String,
): String {
  val url = "https://repo1.maven.org/maven2/${group.replace('.', '/')}/" +
    "$artifact/$version/$artifact-$version.module"
  // ... 拉取、解析、统计 iOS 变体
}

@Tool 和 @Param 是 ADK 的注解，后面会说它为什么重要。

结构：为什么是两个模块

adk-kotlin-agent-quickstart/
├── shared/          KMP 模块
│   └── src/
│       ├── commonMain/   Ktor 客户端 + 协议 DTO（jvm / iOS 共用）
│       ├── jvmMain/      CLI 入口 + CIO 引擎
│       └── iosMain/      Darwin 引擎
└── agent-server/    纯 JVM 模块：ADK agent + HTTP 服务

看起来可以塞进一个模块，但塞不进去。google-adk-kotlin-webserver 内部依赖的是 Ktor 2.3.13，而客户端要用 Ktor 3.6.0。放一起的话 Gradle 按「最高版本获胜」把服务端也拉到 Ktor 3，而 ADK 的代码是按 Ktor 2 的 API 编译的，运行时会直接炸。

这不是猜的。跑起来之后看类路径，服务端确实是这一串：

ktor-server-netty-jvm-2.3.13.jar
ktor-server-core-jvm-2.3.13.jar
ktor-client-core-jvm-2.3.13.jar
...

客户端那边是 3.6.0。物理隔开，各自安好。

版本锁定

KSP 必须和 Kotlin 严格配对，这是最容易埋雷的地方。我直接照抄了 google/adk-kotlin 仓库自己构建用的组合：

[versions]
kotlin = "2.3.21"
ksp = "2.3.9"          # 和 kotlin 一起升，别单独动
adk = "1.1.0"
ktor = "3.6.0"

服务端依赖三个：

dependencies {
  implementation(libs.adk.core)        // agents / models / tools / sessions / runners
  ksp(libs.adk.processor)              // 编译期生成工具 schema
  implementation(libs.adk.webserver)   // 把 agent 用 HTTP 暴露出去
}

工具是怎么变成 schema 的

ADK for Kotlin 和 Python 版最大的差别在这儿。Python 靠运行时反射，Kotlin 这边是 KSP 编译期生成。

KmpSupportAgent 里的这一行是关键：

tools = KmpLibraryService().generatedTools()

generatedTools() 这个函数在整个工程里我一行都没写过。编译完之后，它出现在：

agent-server/build/generated/ksp/main/kotlin/com/example/adk/server/
├── CheckLibraryPlatformsTool.kt
├── ListAvailableVersionsTool.kt
└── KmpLibraryService_GeneratedTools.kt

后者的内容是：

public fun KmpLibraryService.generatedTools(): List<FunctionTool> = listOf( ... )

好处是运行时不需要反射，R8/混淆、Native 镜像、启动时间这几个方向上都干净。代价是工具签名改了必须重新编译，动态注册工具这种玩法就别想了。

agent 本体

object KmpSupportAgent {
  @JvmField
  val rootAgent = LlmAgent(
    name = "kmp_library_platform_agent",
    model = Gemini(name = "gemini-3.1-flash-lite"),
    instruction = Instruction("""
      You are an assistant for Kotlin Multiplatform developers.
      When the user asks whether a library supports a platform, never answer
      from memory. Call `checkLibraryPlatforms` and read the result.
      ...
    """.trimIndent()),
    tools = KmpLibraryService().generatedTools(),
  )
}

顺带说下 @JvmField。官方示例里每个 agent 的 rootAgent 都带着它，我一开始也照抄了，还以为它是必需的。其实它只是让 Kotlin object 的属性变成真正的静态字段（而不是 INSTANCE.getRootAgent()），方便 Java 调用方访问。我试着去掉它重新编译运行，服务端照样起来、/list-apps 照样返回——因为 AdkServerConfig.inMemory(agent) 是直接拿 agent 对象，全程不走反射。抄没问题，但别以为少了它就启动不了。

instruction 里我特意写清楚了一件事：platform.type 是个聚合标记，Kotlin/Native 的目标统一报 native，具体是哪个 Apple 目标只出现在变体名里。不写这句，模型容易看着 native 这个词就自己下结论，而它并不能从 native 推出到底有没有 iOS。

起服务

fun main() {
  val config = AdkServerConfig.inMemory(KmpSupportAgent.rootAgent)
  AdkDevServer(config).start(wait = true)
}

AdkDevServer 会顺带挂上开发界面。路由长这样：

实测三个能直接验：

$ curl -s localhost:8080/list-apps
["kmp_library_platform_agent"]

$ curl -s localhost:8080/version
{"version":"1.1.0","language":"kotlin","language_version":"21.0.10"}

$ curl -s -X POST -H "Content-Type: application/json" -d '{}' \
    localhost:8080/apps/kmp_library_platform_agent/users/demo-user/sessions
{"id":"b86f7324-81db-49df-8007-1700077ebdb4","appName":"kmp_library_platform_agent",...}

/run_sse 用的是标准 SSE，每个事件一行 data: <json>，后面跟一个空行。服务端的实现是手写的，因为 Ktor 2.x 没有 SSE 插件。源码里的注释挺有意思：

Ktor 2.x has no SSE plugin, so stream manually. Use async respondBytesWriter, not respondTextWriter, whose blocking bridge parks via a coroutines internal gone in 1.11.0.

Ktor 2.x 没有 SSE 插件，所以手动流式输出。要用异步的 respondBytesWriter，不能用 respondTextWriter——它的阻塞桥接依赖了一个在 kotlinx-coroutines 1.11.0 里已经被删掉的内部实现。

也就是说这一句注释本身在提醒你：升级 coroutines 版本可能把这个 API 弄坏。

客户端：写在 commonMain 里

真正跨平台的部分在这里。请求构造和 SSE 解析全部写在 commonMain，不碰平台 API：

fun run(prompt: String, sessionId: String? = null): Flow<Event> = channelFlow {
  val sid = sessionId ?: createSession()
  httpClient.preparePost("$baseUrl/run_sse") {
    contentType(ContentType.Application.Json)
    setBody(RunRequest(appName, userId, sid, Content.text("user", prompt), streaming = true))
  }.execute { response ->
    val channel = response.bodyAsChannel()
    while (true) {
      val line = channel.readLine() ?: break
      if (!line.startsWith("data:")) continue
      val payload = line.removePrefix("data:").trim()
      if (payload.isEmpty()) continue
      val event = json.decodeFromString<Event>(payload)
      send(event)
      if (event.turnComplete) break
    }
  }
}

只有引擎是分平台的，用一个 expect/actual 收口：

// commonMain
expect fun createPlatformHttpClient(json: Json): HttpClient

// jvmMain
actual fun createPlatformHttpClient(json: Json) = HttpClient(CIO) { ... }

// iosMain
actual fun createPlatformHttpClient(json: Json) = HttpClient(Darwin) { ... }

循环退出靠两个字段：partial 标记这是一个还没说完的流式分片，turnComplete 标记这一轮结束。没有 turnComplete 就得靠连接关闭来判断，那会拖到超时。

那个 400

现在讲开头说的坑。

我照着自己的理解写请求体，用了 app_name / user_id / new_message 这套命名——毕竟 Python 版 ADK 就是这样，而且我确实在仓库源码里看到 ApiModels.kt 给每个多词属性都挂了一个别名：

@JsonNames("app_name") val appName: String,
@JsonNames("user_id") val userId: String,

请求发出去：

HTTP/1.1 400 Bad Request
Content-Length: 0

没有 body，没有堆栈，服务端日志里连一行 ERROR 都没有。试着换成 camelCase 再发一次，返回变成 500——这说明反序列化通过了，失败发生在更后面（模型调用）。也就是说：

• camelCase → 解析成功，一路走到 Gemini SDK
• snake_case → 根本没进到业务逻辑

@JsonNames 在 kotlinx-serialization 里是「备用名」，理论上两种拼写都应该认。我甚至单独写了个最小复现，用同样的注解和同样的 Json 配置，snake_case 解析是成功的。所以问题不在 kotlinx。

问题在版本。我去翻了 tag：

v1.1.0 的 ApiModels.kt：
  data class AgentRunRequest(
    val appName: String,
    val userId: String,
    ...
  )
  → 一个 @JsonNames 都没有

那两个别名提交 94dcdd13（feat: accept snake_case and camelCase in web server request bodies）的日期是 2026-09-15，进的是 main，在 v1.1.0 tag 之后。仓库里还有个测试文件写着「服务端读 snake_case」——它描述的是 main 的行为，不是你能下载到的 1.1.0 的行为。

拿真实的 AgentRunRequest 和真实的 adkJson 解码 snake_case，报错很明确：

kotlinx.serialization.MissingFieldException: Fields [appName, userId] are required
for type with serial name '...AgentRunRequest', but they were missing

所以规则是：对 1.1.0，一律用 camelCase。 snake_case 要等下一个版本。

这件事的教训不是「要看 tag」，而是「读 main 的源码不等于读你依赖的那个版本」。我如果没真的把请求发出去试一遍，这篇文章里的示例代码就是照抄一个未发布行为、一跑就 400 的代码。

真要说自查手法，/version 这个端点很有用——服务端会自报版本，然后去对照那个 tag 的源码，比对着 main 猜要靠谱。

工具跑出来的样子

这一段不需要模型，工具是纯 Kotlin，可以直接跑：

./gradlew :agent-server:runTools

先拿 ADK 自己开刀：

com.google.adk:google-adk-kotlin-core:1.1.0
platform.type values: androidJvm, common, jvm
variants mentioning iOS: 0
Verdict: no iOS target. This library cannot be consumed from an
iosArm64 / iosSimulatorArm64 source set.

再拿 Ktor 对照：

io.ktor:ktor-client-core:3.6.0
platform.type values: common, js, jvm, native, wasm
variants mentioning iOS: 9
  - iosArm64ApiElements-published
  - iosSimulatorArm64ApiElements-published
  - iosX64ApiElements-published
  ...（共 9 个，含 Api / Metadata / Sources 三类）
Verdict: iOS targets are published, so Apple targets can depend on it.

同一个函数、同一套判断逻辑，两个库的结论正好相反。这个反差下面单独说。

版本查询和错误路径也顺带看一眼：

com.google.adk:google-adk-kotlin-core — latest=1.1.0
recent: 0.5.0, 0.6.0, 0.7.0, 0.8.0, 0.9.0, 1.0.0, 1.0.1, 1.1.0

Could not fetch metadata for com.google.adk:does-not-exist:9.9.9 (HTTP 404).
The coordinates or version are probably wrong.

错误路径返回的是一句人话，不是抛异常。工具返回给模型的是字符串，异常直接把这一轮对话打断，模型连「这个库不存在」都说不出来。

跨端这件事

shared 这块是真跨平台。我实际编译过：

$ ./gradlew :shared:compileKotlinIosSimulatorArm64 :shared:compileKotlinIosArm64
BUILD SUCCESSFUL in 33s

同一份 commonMain 代码，JVM 和 iOS 都过。

而 agent-server 永远只能在 JVM（或者 Android）上。这不是配置问题——google-adk-kotlin-core 发布到 Maven Central 的 Gradle 变体只有 common / androidJvm / jvm 三个，google-genai-kotlin 也一样。没有 iOS 变体，也没有 Native 变体。

所以如果你想在 iOS 上跑 agent，路只有两条：把它放在服务端，iOS 只做客户端（就像这个工程的结构）；或者等上游补 Native 支持。我为此在 ADK 仓库开了个 issue，编号 #504，目前还没回复。

顺带一说，这个「agent 只在服务端」的切分其实多数场景更合理——模型密钥不会进客户端包，工具执行和权限检查也都在你能控住的地方。

怎么跑

export GOOGLE_API_KEY=...
./run-stack.sh

这个脚本干四件事：把服务端装出来并起在 8080、轮询 /list-apps 等它真就绪、跑客户端、跑完收掉服务端并把客户端的退出码原样传出来。

（第一版这个脚本是漏的：它借 Gradle 生成的启动脚本起服务，而那个脚本把 java 当子进程跑，kill 只杀掉外壳，服务端会变成孤儿一直占着 8080。改成直接起 java，$! 才是服务端本体。）

也可以拆开：

./gradlew :agent-server:run     # 终端 1
./gradlew :shared:runClient     # 终端 2

最后交代清楚我验证到哪一步了，别让你照着跑的时候产生落差。

跑通的：整个工程编译通过（含 KSP 代码生成）；服务端启动；/list-apps、/version、建会话都返回 200；客户端发出的 /run_sse 请求被服务端接受，并进入 com.google.genai.kotlin 的模型调用层。

没跑通的：一次真实的模型对话。这需要你自己的 Gemini API key，我这边没有。所以文章开头那个「查 iOS 支持情况」的完整对话输出，我没有贴——它得接上有效 key 才能看到，我不想贴一段没跑过的输出。

代码在 https://github.com/trewvip-arch/adk-kotlin-agent-quickstart

Apache-2.0。有问题直接在仓库里开 issue。

之前介绍 ADK for Kotlin 1.0 的时候，我写过一句"未来如果 iOS 侧也支持，那就是一套代码三端复用"。当时这个词用得很滑——它跟"KMP 核心"这句话摆在一起，很容易让人读成"iOS 应该也能跑"。

后来有读者来问：它既然是 Kotlin Multiplatform 写的，那 iOS 是不是本来就能用？

这个问题我当初不该带过。所以这次我自己去查了，查的方式不是看文档怎么说，而是直接拆它的构建产物。

结论先放这儿：不能。而且这不是加一行 target 就能解决的事。

查一个 KMP 库到底支持什么，有个很硬的地方

先说方法，因为这个方法比这次结论更有用。

KMP 库在发布时会生成一份 Gradle module metadata（.module 文件），里面列着这个库实际编译出来的所有平台变体。它是构建系统的产物，不是谁写的宣传文案——一个库说自己"支持多平台"，但元数据里没有对应的变体，那构建时就是拿不到，编译直接失败。

所以想知道一个库的真实平台覆盖，一行命令就够：

# 通用查法：把 group 换成包名路径
curl -sL "https://repo1.maven.org/maven2/com/google/adk/google-adk-kotlin-core/1.1.0/google-adk-kotlin-core-1.1.0.module" \
  | python3 -c "
import sys, json
d = json.load(sys.stdin)
vs = d.get('variants', [])
plats = sorted({v['attributes'].get('org.jetbrains.kotlin.platform.type', '?') for v in vs})
names = [v['name'] for v in vs]
ios = [n for n in names if 'ios' in n.lower()]
print('platform.type :', ', '.join(plats))
print('含 ios 的变体 :', len(ios), '个')
for n in ios[:4]: print('   -', n)
"

拿 ADK for Kotlin 跑一下，输出是：

platform.type : androidJvm, common, jvm
含 ios 的变体 : 0 个

怎么读这个结果

有个地方容易看错，我自己第一次就差点搞混：iOS target 不会出现在 platform.type 里。

Kotlin/Native 在 platform.type 上统一标记为 native，具体是哪个 Apple 平台，看的是变体名。所以正确的读法是两层一起看：

• platform.type 有 native → 说明这个库编译了 Kotlin/Native 目标
• 变体名里出现 iosArm64 / iosSimulatorArm64 / iosX64 → iOS 才是真能用

拿一个确定支持 iOS 的库对照一下，比如 Ktor：

platform.type : common, js, jvm, native, wasm
含 ios 的变体 : 9 个
   - iosArm64ApiElements-published
   - iosArm64SourcesElements-published
   - iosSimulatorArm64ApiElements-published
   ...

64 个变体，9 个带 ios。这才是"真支持 iOS"的样子。

ADK 那边是 8 个变体，platform.type 只有 androidJvm / common / jvm，带 ios 的变体是 0 个。

我顺手验了一遍所有版本，包括最新的 1.1.0：都没有 iOS。

再看源码结构，结论是一致的。core/src/ 下面的 source set 是这些：

androidMain
commonJvmAndroidMain      ← 注意这个名字
commonMain
jvmMain
（没有 iosMain）

而 core/build.gradle.kts 里的 target 声明，只有 jvm() 加 Android，一行 iOS 都没有。

Maven Central 上 com.google.adk 这个 group 下，iOS 相关的 artifact 是 0 个。

三道坎，一道比一道难

知道"没有 iOS"还不够，值得看看为什么没有。因为答案决定了"自己动手"要花多大代价。

坎一：他们特意劈了一层叫 commonJvmAndroidMain

这个 source set 名字本身就是答案——JVM 和 Android 共享的那部分。它 dependsOn(commonMain)，里面装着：

那条 reactive-streams 是关键信号。它是 JVM 世界的响应式流规范，苹果那边不存在这个东西。而 ADK 的 Java 互操作签名就建立在这上面——源码注释里的原话是 “the api-vs-implementation question for the Java-interop signatures”。

作者其实很清楚代码分两层：一层是真正的跨平台公共逻辑，一层是"JVM 和 Android 共享"的逻辑。他们特意做了这个区分，就是因为它现在只想支持这两个平台。

坎二：jvmMain 里也全是 JVM 专属

gson、google-cloud-storage、mcp（MCP 的 Java SDK）、ktor。Google Cloud Storage 和 MCP 的 Java SDK 都没有 iOS 版本，会话持久化和云存储那部分要另给 iOS 写一套。

坎三（这条最要命）：google-genai-kotlin 自己也不支持 iOS

commonMain 的依赖里有这么一行：

commonMain {
  api(libs.google.genai.kotlin)   // com.google.genai:google-genai-kotlin:1.0.0
}

我拿同一个方法查了它：

平台变体: androidJvm, common, jvm

Google 自家那个生成式 AI 的 Kotlin SDK，也没有 iOS target。

而且它是 api 依赖，不是 implementation——意思是它出现在所有消费者的编译路径上，绕不过去。

所以真相是：想让 ADK for Kotlin 跑 iOS，你得先把 Google 的 GenAI Kotlin SDK 移植到 iOS。 那是另一个 SDK 的工程量，而且东西在 Google 手里，不在你能改的范围内。

那"自己编译支持 iOS"到底意味着什么

不是 fork 一下加三行 target。粗略拆一下：

后两项都不在你的仓库里。尤其第三项——那是要往上动别人的东西。

1.1.0 的方向，反而把这件事说清楚了

ADK for Kotlin 1.1.0 是 9 月 15 日发的（1.0 是 9 月 7 日 GA，1.0.1 是 9 月 10 日，节奏很快）。看它的新增特性：

• AppFunctionsToolset，对接 Android 的 AppFunctions
• Android AppFunctions 转换层
• 把 app 的 AppFunctions 说明注入模型指令
• 针对 Java 的 BaseFutureSkillSource 基类、长时运行工具的 Java 版示例
• Plugin.onRunError 回调

修的问题也在同一片区域：未知工具名不再终止整个调用、workflow agent 的会话恢复修正、MCP server 拒绝请求时保持 turn 存活。

注意这些功能的重心。1.1.0 里最实在的新能力是 Android AppFunctions 那条线——让 agent 去调用 Android 应用暴露的函数。

这说明 iOS 的缺口不是疏忽，是战略选择。Google 的精力在 Android 侧：Gemini Nano、ML Kit、LiteRT-LM、Firebase AI、现在的 AppFunctions，全是为 Android 铺的。ADK for Kotlin 的 “Kotlin Multiplatform” 目前是 “Kotlin Multiplatform（Android + JVM）“的缩写——那个 common 层是给这两个平台共享用的，不是给 iOS 预留的。

那做 iOS 的人怎么办

三条路，按我的推荐顺序。

路线 A：Agent 放服务端，iOS 只做客户端（推荐）

ADK for Kotlin 的 JVM 那条腿是完整可用的——这是它的主战场之一，不是残废版。

所以把 agent 逻辑跑在服务端 JVM 上，iOS 通过 HTTP 调过去。而 ADK 生态里正好有为此准备的东西：A2A（Agent-to-Agent）协议，google-adk-kotlin-a2a 这个模块就是干这个的（它同样只有 JVM 版，但服务端本来就用 JVM）。

代价是失去端侧能力——隐私、离线、低延迟这三样没法兼顾。 好处是今天就能用，零移植风险。

对大多数产品来说这个取舍是划算的：你的 agent 需要联网调模型，那它本来就不是纯离线的。

路线 B：自己写一层"ADK-lite for iOS”

只取 commonMain 的设计思路（编排、会话、记忆、工具 schema），在 iOS 侧用 KMP 生态里现成的积木重搭：

• Ktor 做网络（KMP 原生支持 iOS）
• 直接调 Gemini REST API，绕开 google-genai-kotlin
• SQLDelight 做持久化

但这就不是"用 ADK"了，是照着它的设计自己实现一遍。业务逻辑能共享，框架得重写。

路线 C：等，或者催

1.0 到 1.1.0 只隔了 8 天，迭代速度不慢。如果 iOS 在路线图上，等是划算的。

顺便说一件我顺手做的事：我在仓库里开了个 issue 把这件事问清楚了——

https://github.com/google/adk-kotlin/issues/504

问了三件事：iOS 在不在路线图上、真正的阻塞点是什么（我怀疑是 GenAI Kotlin SDK 缺 native target，而不是 ADK 本身）、现阶段官方推荐什么架构。

之所以觉得这个 issue 有价值：这个仓库目前总共只有几个 issue，而其中一个上个月提的 feature request 两天内就被打了 need attention 标签。说明团队确实在看。有 iOS 需求的同学可以去点个赞，需求信号比什么都管用。

比结论更值钱的是那个查法

回到开头那个方法。

以后你评估任何 KMP 库——不管是 ADK、还是别的什么"跨平台"框架——别只看 README 和发布说明。README 会写 “runs on all supported platforms” 这种话，看着很全，但 “supported” 是谁定义的、支持到什么程度，文档通常不说。

去看 .module 文件。 那里面列的是构建系统真正能拿到的东西：

• 有 iosArm64 / iosSimulatorArm64 → iOS 真能用
• 有 js / wasmJs → Web 真能用
• 只有 common / jvm / androidJvm → 那就是只有 JVM 和安卓

一行 curl 就能做完的事，能省掉你两周的重构。

KMP 这两年最大的认知陷阱就是这个：“基于 KMP 构建"和"KMP 全平台可用"是两件不同的事。 前者说的是代码怎么组织的，后者说的才是你能拿到什么。ADK for Kotlin 是个很好的例子——它的内核确实是精心设计过的跨平台架构，但它目前选择把 iOS 那扇门关着。

核查方式：直接读取 com.google.adk:google-adk-kotlin-core 各版本（含 1.1.0）在 Maven Central 上的 Gradle module metadata、core/build.gradle.kts 与 core/src/ 的 source set 结构、com.google.genai:google-genai-kotlin 的平台变体，并核对了 ADK for Kotlin v1.0.0 / v1.0.1 / v1.1.0 的 Release Notes。

Android、iOS、桌面，这是 KMP 这几年稳定覆盖的三块地方。第四条腿是 WebAssembly——上周发的 Chasm 2.0 就跟这个方向有关。

不过在看它之前，有个特别容易搞混的地方得先说清楚，不然容易对整条路线的判断跑偏。

Chasm：一个用 Kotlin 写的 Wasm 运行时

它的自我介绍就一句话：Chasm is a WebAssembly runtime built on Kotlin Multiplatform。翻译过来是"用 KMP 构建的 WebAssembly 运行时"。

注意语序。它是"用 Kotlin 写了个能跑 Wasm 的东西"，不是"把 Kotlin 编译成 Wasm"。这两件事是反的，后面细说。

项目现在 227 star（我第一版写的时候是 221），支持到 Wasm 3.0 规范（除了 Memory64 和向量指令），实现了 Tail Call、Typed Function References、Wasm GC、Multiple Memories、Exception Handling、Wide Arithmetic 这几组提案。能跑 GC 和异常处理的运行时，已经不算玩具了。

2.0 是 9 月 16 日发的，作者明说了是 breaking changes：新增 Android target（min SDK 28）；JVM target 最低提到 JDK 17；重写 Host Function API，以前是传一个值列表进去、返回一个值列表，现在改成直接读写运行时的栈；移除了废弃的 macosX64 和 iosX64 target；Gradle 插件不再支持 AGP 8。

补一句进度：截至我写这段（9 月 21 日），2.0 之后仓库还没有新提交、也没有新 release，作者在收反馈的阶段。这个节奏是对的——大版本刚发，先稳住再迭代。

里面最让我注意的是作者交代的一句设计取舍：

我想在每个平台的原生约束内做所有事，那意味着不用 FFI 之类的东西。

做跨平台的人能体会这句话的重量。通常要让 JVM 调一个 Wasm 运行时，最省事的做法是套一层 C 接口，但他选了最费劲的那条路——每个平台写原生实现。代价是工作量翻倍，好处是不依赖 FFI、不引入 ABI 兼容的麻烦。

别搞混：这两个方向是反的

我猜不少同学看到"Kotlin"和"Wasm"放一起，第一反应是"KMP 支持 Wasm 了？"

不是。这是两件方向相反的事。

Kotlin/Wasm 是官方的编译目标，做的事是把 Kotlin 源码编译成 .wasm，丢到浏览器里跑。方向是往外送。

Chasm 干的是相反的活：拿现成的 .wasm 文件，在自己的运行时里执行，跑在 JVM、Android、iOS 上。方向是往里接。

搞混这两个，对整条路线的理解就全歪了。

KMP 的第四条腿，指的是官方那条

官方文档写得很直白：Kotlin/Wasm 能把 Kotlin 编译成 WebAssembly，用来做基于 Compose Multiplatform 的 Web 应用，或者跑在浏览器外的独立 Wasm 虚拟机里（后者靠 WASI 访问平台能力）。

两个要点。

一是 Compose Multiplatform 的 Web 平台，编译目标就是 Kotlin/Wasm。也就是说 Compose 写的界面真的能跑在浏览器里，和 Android、iOS、桌面共用同一套 UI 代码。这才是"第四条腿"的实际含义。

二是它对浏览器有硬要求：得支持 WebAssembly 的垃圾回收（WasmGC）和异常处理这两个提案。我一开始以为 Safari 会是个大坑，查完官方资料才发现门槛比想象的低。具体版本是：

Safari 那条值得单独解释。18.2 是 2024 年底的版本，对应 iOS 18.2 / macOS 15.2；而在 iOS 和 iPadOS 上 Safari 是跟着系统走的，用户不单独更新它。所以这条门槛翻译过来其实是「用户的设备别太老」，而不是「别用 Safari」。这条要是判断错了，选型结论会完全反过来。

还有个细节值得知道：异常处理提案现在有新旧两版。Kotlin 工具链两版都支持，但 wasmJs target 默认用的是旧版（legacy）——为了兼容面更宽。想换新版得显式配置。

实测：Wasm 端的成本

拿本机一个真实的 KMP 项目测的（含 JS 和 Wasm 双 target）。先说写第一版时的数据，环境是 Kotlin 2.4.0 + CMP 1.11.1：

$ ./gradlew :app:webApp:wasmJsBrowserDistribution
→ BUILD SUCCESSFUL in 4m 10s
→ 50 actionable tasks: 50 executed

4 分 10 秒，还是依赖已缓存的情况。

产物是这些：

两个 wasm 加起来 14.2 MiB，整个目录大概 15MB。

然后我把项目临时升到 Kotlin 2.4.20 + CMP 1.12.0 又跑了一遍：

$ ./gradlew :app:webApp:wasmJsBrowserDistribution
→ BUILD SUCCESSFUL in 3m 33s
→ 50 actionable tasks: 48 executed, 2 up-to-date

变化不算剧烈，但方向是清楚的：构建快了半分钟多，业务 wasm 缩了 0.30 MiB（约 5%）。

得说清楚这不是严格对等的比较——第二次跑有两个任务命中了缓存，所以 3m33s 里有一小部分是省下来的，不是代码变快了。但"这条线在持续变快变小"这个结论是站得住的。

对比一下桌面端（JVM 打包）的数据：那边是 133MB，差了差不多九倍。原因也简单——桌面那 133M 里 77M 是 JVM 运行时、20M 是 Skia，而浏览器里这两样都不用打包，没有 JVM，渲染直接交给浏览器的 Canvas 和 WebGL。

这就是 Wasm 端最实在的好处，不用背运行时的包袱。

不过 webpack 在构建时给了一串警告，说几个资源超出了建议上限 244 KiB，点名了 webApp.js 的 529 KiB 和两个 wasm。8.25 MiB 比它建议的数字大了三十多倍。意思是不做代码分割、不做按需加载的话，用户第一次打开页面就得下 15MB。弱网环境下这是实打实的体验问题。

顺带说说这一个月 Web 端补了什么

升版本的时候我顺手翻了两份 release notes，有几条对做中文应用的人特别有用，值得单独拎出来。

CMP 1.12（8 月 25 日）的 Web 改动：

• Noto 字体自动加载——遇到主题字体没覆盖的符号时，会自动去加载 Noto。做中文或多语言应用的人应该知道这意味着什么：以前生僻字直接显示成豆腐块
• 专门修了两个豆腐块问题：输入框首次绘制时未知符号的 tofu，以及同一段文本第二次及后续绘制时的 tofu
• 修了 div#cmp_a11y_root 尺寸为 0×0 的 bug。这个挺严重——它直接导致 Compose 渲染出来的内容，对基于命中测试的无障碍工具是不可见的
• 滚轮事件现在两个轴都传（修了斜向滚动）、Chrome 上加了精确的触控板手势识别、修了 pointercancel 之后指针状态残留的问题（系统手势、掌拒、设备断开都会触发这个）
• 移动浏览器上聚焦输入框导致软键盘被隐藏的问题也修了
• 另外 web target 补上了触觉反馈支持和 Modifier.keepScreenOn

CMP 1.13.0-alpha01（9 月 10 日）：

• 删掉了废弃的 compose.web.targets(...) Gradle 插件 API。如果你老的构建脚本里还留着这个，升级会直接报错
• 实验性支持 Web 上的系统窗口 insets
• 新增渲染 WebGL 纹理的实验性 API
• 浏览器或设备不支持 WebGL2 时，给一个看得懂的提示，而不是一个晦涩的崩溃

Kotlin 2.4.20（9 月 7 日）的 Wasm 后端动静更大——这次 release notes 里跟 Wasm 相关的条目有六十多条。挑三条你迟早会碰到的：

• 默认开启 range checks（越界检查）。安全性提升，代价是一点性能
• 弃用并禁止 wasmExports。如果你在用 JS 互操作直接摸 wasm 的导出，升级会挂
• 开始做「用 stack-switching 提案生成 suspend 函数」的原型。这条现在还用不上，但方向值得记住——它是 Wasm 未来处理异步的官方路线

还有一条升级注意事项：这次为了重构可调用引用、生成统一的 fun interface 基类，破坏了 klib 的二进制兼容性。如果你的依赖里有别人发布的 wasmJs klib，可能需要对方也重新发布一次。这类破坏在多平台生态里比 JVM 那边敏感得多——升级前先跑一遍构建，别等到发版才发现。

适合什么，不适合什么

最划算的场景是已经有 KMP 项目、想白捡一个 Web 端，跟桌面端一样，加个 target 的事。内部工具、管理后台也行，不在乎首屏 15MB，在乎一套代码。

能真正发挥优势的是逻辑复杂、UI 相对固定的应用，共享的业务代码越多，这笔账越划算。

反过来，面向 C 端的营销页、轻量站点就别上了，15MB 首屏加上老浏览器不兼容，等于劝退。依赖 SEO 的产品也不行，Wasm 渲染出来的页面爬虫看不到内容。如果只需要 Web 一个平台，那直接用 React 或 Vue 更省事。

判断标准可以压成一句话：你的核心价值是不是"已经写好的那套 Kotlin 代码"？是就用 Wasm，不是就别为了技术统一硬上。

附：一个最小可跑的工程

三步能跑起来。

第一步，在 build.gradle.kts 里加 target：

plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.composeMultiplatform)
    alias(libs.plugins.composeCompiler)
}

kotlin {
    @OptIn(org.jetbrains.kotlin.gradle.ExperimentalWasmDsl::class)
    wasmJs {
        browser()
        binaries.executable()
    }

    sourceSets {
        commonMain.dependencies {
            implementation(compose.runtime)
            implementation(compose.foundation)
            implementation(compose.material3)
        }
    }
}

第二步，写入口，路径是 src/wasmJsMain/kotlin/main.kt：

import androidx.compose.ui.ExperimentalComposeUiApi
import androidx.compose.ui.window.ComposeViewport
import kotlinx.browser.document

@OptIn(ExperimentalComposeUiApi::class)
fun main() {
    ComposeViewport(document.body!!) {
        App()
    }
}

第三步，UI 放 commonMain，三端共用：

@Composable
fun App() {
    MaterialTheme {
        var count by remember { mutableStateOf(0) }
        Column(Modifier.padding(24.dp)) {
            Text("Hello, Wasm!")
            Button(onClick = { count++ }) {
                Text("点了 $count 次")
            }
        }
    }
}

跑起来：

./gradlew wasmJsBrowserDevelopmentRun   # 开发模式，带热重载
./gradlew wasmJsBrowserDistribution     # 打生产包

ComposeViewport 是 Compose Multiplatform 在 Web/Wasm 上的挂载点，地位跟 Android 的 setContent、桌面的 application 差不多。所以"第四条腿"的接入成本就是加一个 target、写一个入口函数，UI 代码继续和别的端共用。

Chasm 怎么用

回到开头那个项目，给个它的实际用法（README 里的最小示例）：

plugins {
    id("io.github.charlietap.chasm.gradle") version "3.0.0-2.0.0"
}

chasm {
    modules {
        create("ExampleService") {
            binary = layout.projectDirectory.file("src/main/resources/example.wasm")
            packageName = "com.example"
        }
    }
}

加上这段，构建会去读你的 .wasm 文件，然后生成一个 Kotlin 类 ExampleService，里面每个导出函数都变成一个能直接调的 Kotlin 函数。等于把一个现成的 Wasm 模块当普通 Kotlin 库用。

它底层是个统一的 Wasm 虚拟机抽象：JVM 和 native 平台用 Chasm 自己的实现，浏览器里则复用宿主内置的 VM。

能解决什么问题？比如你有一份编译成 Wasm 的 C/C++/Rust 库，想在 iOS 应用里用，以前得写 FFI 胶水，现在直接当 Kotlin 库调。又比如做一个跨平台插件系统，让插件以 Wasm 形式分发，宿主负责执行。

这块是我觉得 Chasm 值得单独讲的真正原因——它展示了 Wasm 的另一半可能性。

我的看法

Chasm 和 Kotlin/Wasm 同时出现在新闻里是件好事。一个把 Kotlin 送出去，一个把 Wasm 请进来，从两个方向把两者接上了。这种双向的连接，说明生态开始有厚度。

但 Wasm 真正的门槛不在技术，在体积和兼容性。15MB 的包、GC 和异常处理的浏览器要求，都是实打实的商业约束，不是工程洁癖。我测出 4 分 10 秒构建时间的时候就在想，这技术已经很成熟了——但成熟不等于适合你的产品。

还有一点，KMP 这四块地方的权重差得挺远。Android 和 iOS 是十年积累，桌面端五六年，Web/Wasm 才刚起步两三年。用同一个标准要求它们不合理，你在 Android 上习惯了的顺滑，到 Wasm 上大概率要重新适应。

想给项目加 Web 端的话，我的建议是先在现有项目里加个 Wasm target，跑个 Hello World 试试。就上面那份配置，半小时能验证完。重点是"在现有项目里"——你会立刻撞到真问题：依赖的库有没有 wasmJs 版本（这是最常见的卡点）、expect/actual 有没有漏掉 wasmJs 分支、构建时间多花多久。这些在玩具项目里遇不到，只有真实依赖才会暴露。花半小时撞墙，比花两周重构完发现库不支持划算得多。

你会给 KMP 项目加 Web 端吗？15MB 的首屏包能接受吗？评论区聊聊。

参考资料：CharlieTap/chasm 仓库与 2.0.0 Release Notes、Kotlin 官方文档 Kotlin/Wasm 概览与「Supported versions and configuration」、WebAssembly 官方 roadmap（GC 支持版本）、Compose Multiplatform 1.12.0 与 1.13.0-alpha01 Release Notes、Kotlin 2.4.20 Release Notes、Reddit r/Kotlin 讨论帖。实测环境：Mac mini（M4，16GB），项目为含 JS/Wasm 双 target 的 KMP 应用，分别在 Kotlin 2.4.0 + CMP 1.11.1 与 Kotlin 2.4.20 + CMP 1.12.0 下各构建一次（升级为临时操作，测完已还原项目版本）。

苹果 M6 的跑分这两天陆续曝光。单核比 M4 那款高约 24%，多核高约 48%，多核直接追平了 M3 Max——一颗中端定位的芯片，多核打平上一代旗舰，确实挺夸张。

GPU 那边，12 核在 Geekbench 上跑出单核 4071、多核 22783，比 M5 高 20% 左右。

然后我就看到有人开始讨论：芯片都这么快了，是不是可以把桌面端也搞起来？

我拿自己手上的项目试了试。结论有点扫兴：这件事基本跟芯片跑分没关系。

我在机器上跑了什么

本机是 Mac mini，M4，10 核，16G 内存。项目是个 KMP + Compose Multiplatform 的 AI Chat 客户端，shared 放共享逻辑，desktopApp 是桌面入口。

打包就一条命令：

./gradlew :desktopApp:createDistributable

跑了两遍，第一遍 22 秒，第二遍 8 秒。都挺快——但这两次依赖早下好了，代码也没怎么动。真正的第一次冷构建（下依赖、编 Kotlin、生成运行时镜像）是要按分钟算的。

快是快，不过这不是重点。重点是最后一个数字：

$ du -sh lange.aichat.app
133M

一百三十三兆，一个聊天客户端。

拆开看才有意思：

77M 是 JVM 本身，再加 20M 的 Skia，光是让程序能跑起来的底座就 97M。你自己写的那部分，可能就几百 K。而且那 77M 已经是 jlink 裁过一遍的结果了，不是原始大小。

所以账很清楚：Compose Desktop 写起来舒服，但分发成本摆在那。除非把 JVM 这个前提换掉（GraalVM native-image 那条路），否则百兆上下就是常态。

M6 快这么多，用处到底在哪

编译。Kotlin 编译、Gradle 并行任务、native 链接，这些都是吃多核的活，多核加 48% 能实打实缩短构建时间。

我顺手把同一个仓库里的另一个 target 也测了：

./gradlew :app:webApp:wasmJsBrowserDistribution
→ BUILD SUCCESSFUL in 4m 10s

4 分 10 秒，50 个任务全跑了一遍，CPU 和内存吃得满满的。天天要跑好几次构建的人，对这种多核提升感受最直接。

那最终用户呢？

一个聊天客户端，用户能感觉到的瓶颈是这些：冷启动——JVM 加载加 Compose 初始化，吃的是单核和 IO，多核帮不上多少；滚动和动画——看 Skia 的，GPU 那 20% 对 2D 界面来说过剩；首屏——看网络。

M6 再快一半，用户也不会觉得你的应用变快了。

那到底该不该做桌面端

我自己是这么看的。

已经有 KMP 项目、想多覆盖一个平台的，可以直接加。shared 逻辑本来就在那，无非多写一个入口。做内部工具、开发者工具的也能加，反正只给自己团队装，没人在乎包多大。

真正值得单独立项的是另一类需求：要在本地读写文件、要开多窗口常驻后台、要在本机跑模型。这些是桌面能做、手机做不了的。这种场景下 133M 根本不算事——用户装的是工具，不是玩具。

反过来，面向普通消费者的轻量小工具得谨慎。用户不会为一个查天气的小应用下 133M。对冷启动有硬要求的也一样，JVM 那条冷启动曲线绕不过去，除非上 GraalVM。

顺带一提，Compose Multiplatform 1.13 已经在做 AppCDS 和 AOT 了（1.13.0-alpha01 的更新里写了"显著加快应用启动"）。如果你现在正因为启动慢犹豫，可以再等一两个版本。

最后

M6 很好。构建能快一截，这点对天天敲代码的人是真实收益。

但它改变不了桌面端的取舍。卡人的是包体积和冷启动，这两样芯片管不着。如果你的动机是"吃到新硬件红利"，那可能看错地方了——桌面端真正的红利在打包技术上（jlink、AppCDS、GraalVM），不在 CPU 跑分上。

如果你已经在做 KMP，桌面端其实是最便宜的那一端，shared 已经写好了，加个入口就多一个平台。这个理由跟芯片无关，但我觉得比跑分实在。

你会给项目加桌面端吗？能接受多大的包？评论区聊聊。

测试环境：Mac mini（Apple M4，10 核，16GB），macOS 27.0，JDK 21.0.10，Kotlin 2.4.0 + Compose Multiplatform 1.11.x。M6 跑分来自 Geekbench 曝光成绩，及 cnBeta、Notebookcheck、凤凰网科技等公开报道。

先说昨天的新闻：Claude Code 2.1.277 开始支持 AGENTS.md（9 月 18 日）。

The Register 的标题起得很直接——“Anthropic 决定支持 OpenAI 的 markdown 指令规范”。

如果你不是天天泡在 AI 编程工具里，可能会觉得：一个配置文件名，至于吗？

至于。因为这场拉锯的起点，是 Shopify CEO 公开放的一句狠话。

时间倒回 8 月 26 日。Shopify CEO Tobi Lütke 在 X 上表态：

我正考虑在 Shopify 禁用 Claude Code，直到他们愿意读取 AGENTS.md、.agents/skills 等文件。

一家电商巨头，威胁要全公司禁用一款主流 AI 编程工具——原因只是它不肯读一个 markdown 文件。

而他给出的理由，我觉得比新闻本身更有价值：

AGENTS.md 和 CLAUDE.md 都会沿目录树递归生效。数千名开发者维护一个 monorepo，难免有目录漏掉一份文件，结果就是一部分开发者用上"被切掉一块脑子"的智能体。

我们用自动化解决了问题，但这是笔愚蠢的复杂度税，根本不该付。

“被切掉一块脑子的智能体”——这个说法，凡是维护过大型仓库的人应该都会心一沉。

先把 AGENTS.md 说清楚

AGENTS.md 的官方定义只有一句话：

Think of AGENTS.md as a README for agents.

给 agent 看的 README。

README 给人看——怎么快速上手、项目是做什么的。而 AGENTS.md 装的是 agent 需要、但不适合塞进 README 的东西：构建步骤、测试怎么跑、代码约定、几条铁律。

它现在的地位比很多人想的高：

• 已被 6 万+ 开源项目采用
• 起源于多家协作：OpenAI Codex、Amp、Google 的 Jules、Cursor、Factory
• 现在由 Linux 基金会旗下的 Agentic AI Foundation 托管

官方给的最小示例长这样：

# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons

就这么简单。 没有 schema，没有特殊语法——就是一份 markdown。

而它真正好用的地方在于：一份文件跨多个 agent 通用。Codex、Cursor、Jules、Copilot、Claude Code 都读它，你不用为每个工具维护一份配置。

顺带一提，Claude Code 之前坚持用自己的 CLAUDE.md。开发者从 2025 年 8 月就开始提需求，相关 issue 攒了近 5000 个 GitHub 点赞，最后被关了，回复是"不予修复"。直到 Shopify 威胁禁用，才等来了 9 月 18 日的支持。

为什么"一份文件"会升级成平台工程问题

很多人会想：不就是让 Claude Code 多读一个文件吗，为什么 Shopify 要上升到"全公司禁用"？

因为在一个几千人的 monorepo 里，一个文件格式差异会变成失控。

Lütke 说的那个机制值得抄下来：

monorepo/
├── AGENTS.md          ← 全局规则（技术栈、提交规范）
├── backend/
│   └── AGENTS.md      ← 后端特有（不要动 db/migrations）
├── mobile/
│   └── AGENTS.md      ← 移动端特有（打包、签名）
└── infra/
    └── AGENTS.md      ← 基础设施特有

AGENTS.md 是"就近生效"的——agent 读到当前目录最近的那份，继承上层的规则。

问题就出在这儿：

• 假设团队同时用 Cursor（读 AGENTS.md）和 Claude Code（只读 CLAUDE.md）
• mobile/ 目录下写了 AGENTS.md，但没人记得再写一份 CLAUDE.md
• 用 Cursor 的开发者：agent 知道"打包前要跑签名脚本"
• 用 Claude Code 的开发者：agent 不知道

同一份代码，同一个任务，两个 agent 给出的结果不一样。 而这区别不会被任何报警发现——你只是偶尔发现某个同事的 AI"特别笨"。

这就是 Lütke 说的"复杂度税"：不是不能解决，而是这个问题根本不该存在。

落到实操：一个 KMP + AI Chat 客户端怎么写

好了，新闻讲完，接下来是正题。

假设我们在做的是一个 Kotlin Multiplatform + Compose Multiplatform 的 AI Chat 客户端——一套 Kotlin 代码，跑 Android 和 iOS。

这种项目写 AGENTS.md 有它的特殊性：同一个仓库里，三种代码的规则完全不同。

先看目录树：

ai-chat/
├── AGENTS.md                      # 根：全局铁律 + 通用命令
├── settings.gradle.kts
├── gradle/
│   └── libs.versions.toml         # 版本目录（依赖版本唯一来源）
├── shared/                        # 共享业务逻辑（无 UI）
│   ├── AGENTS.md                  # 这一层的规矩
│   ├── build.gradle.kts
│   └── src/
│       ├── commonMain/kotlin/     # ← 三端共享
│       ├── androidMain/kotlin/    # ← Android 实现
│       ├── iosMain/kotlin/        # ← iOS 实现
│       └── commonTest/kotlin/
├── composeApp/                    # Compose Multiplatform UI
│   ├── AGENTS.md
│   └── src/
│       ├── commonMain/
│       ├── androidMain/
│       └── iosMain/
├── androidApp/                    # Android 壳工程
│   ├── AGENTS.md
│   └── src/main/AndroidManifest.xml
└── iosApp/                        # iOS 壳工程（Xcode）
    ├── AGENTS.md
    └── iosApp.xcodeproj

注意：这个结构本身就是给 agent 的第一层信息。 如果 agent 分不清 shared/ 和 composeApp/ 的区别，它就会把 UI 代码写到逻辑层里。

根 AGENTS.md：只写"全局铁律"和"通用命令"

# AGENTS.md

KMP + Compose Multiplatform 的 AI Chat 客户端。
一套 Kotlin 代码，编译到 Android / iOS。

## 项目结构
- `shared/`     — 共享业务逻辑，**不含任何 UI**
- `composeApp/` — Compose Multiplatform UI（三端共用同一套界面）
- `androidApp/` — Android 壳（Activity / Application / manifest）
- `iosApp/`     — iOS 壳（Xcode 工程 / SwiftUI 入口）

## 构建与测试
- 全量编译：      `./gradlew build`
- 共享层编译：    `./gradlew :shared:compileKotlinMetadata`
- Android 装到机：`./gradlew :androidApp:installDebug`
- 跑全部测试：    `./gradlew allTests`
- 只跑一个类：    `./gradlew :shared:allTests --tests "*ChatRepository*"`
- iOS 框架：      `./gradlew :shared:linkDebugFrameworkIosSimulatorArm64`

## 铁律（违反会导致三端编译失败）
1. `commonMain` 里**禁止**出现 `java.*`、`android.*`、`platform.*`
2. 平台差异一律走 `expect` / `actual`，不要写 `if (isAndroid)`
3. **不要为 iOS 复制一份逻辑** —— 那就失去了用 KMP 的意义
4. 新依赖先加到 `gradle/libs.versions.toml`，模块里只引别名，**不要写死版本号**
5. 改 `commonMain` 之后，必须能同时编译 Android 和 iOS

这里有几个写法上的讲究，我认为很关键：

① 命令要"可复制执行"，不要描述。 写 ./gradlew :shared:compileKotlinMetadata，不要写"编译一下共享模块"。agent 拿到能直接跑的命令，才不用猜。

② 铁律要写"违反的后果"。 “禁止在 commonMain 用 java.*” 是个规定；但加上"会导致三端编译失败"，agent 才知道这是硬约束，不是风格偏好。

③ 用"唯一来源"消灭歧义。 “版本号只写在 libs.versions.toml"——这一句能让 agent 不再到处硬编码版本。

shared/AGENTS.md：只写"这一层特有的”

子目录的 AGENTS.md 不该重复根目录的内容，只写"进到这个目录才需要知道的事"：

# shared/ — 共享业务逻辑

## 三端目录的职责
- `commonMain/` — 平台无关逻辑。要用平台能力，在这里先 `expect` 声明
- `androidMain/` — `expect` 的 Android 实现（用 Android SDK / JVM API）
- `iosMain/`     — `expect` 的 iOS 实现（用 Kotlin/Native + Foundation）
- **每加一个 `expect`，必须同时补齐 androidMain 和 iosMain 两份 `actual`**

## 目录约定
- `data/`      — Repository、数据源、DTO
- `domain/`    — 领域模型、UseCase
- `platform/`  — expect/actual 的平台抽象
                   （KeyValueStore、HttpEngine、AppInfo…）

## 网络（AI Chat 的核心）
- 统一用 **Ktor**，禁止在共享层直接用 OkHttp 或 URLSession
- 流式响应统一返回 `Flow<ChatChunk>`，不要在 shared 里做 UI 状态管理
- 超时、重试、错误映射统一在 `data/remote/` 里处理

## 命令
- 测试：      `./gradlew :shared:allTests`
- iOS 框架：  `./gradlew :shared:linkDebugFrameworkIosSimulatorArm64`

看见没，这一层装的全是"KMP 特有"的知识：

• expect/actual 的配对规则（这是 KMP 最容易出错的地方）
• 网络层为什么必须用 Ktor（因为 OkHttp 在 iOS 上不存在）
• 流式响应为什么用 Flow（AI Chat 的核心特征）

这些是通用 README 里不会写、但 agent 每次都会踩的东西。

三端壳工程：各自写"别乱碰什么"

androidApp/AGENTS.md：

# androidApp/ — Android 壳

## 这里只放什么
- Activity、Application、AndroidManifest.xml、res/ 资源
- **业务逻辑一律放 shared/，UI 一律放 composeApp/**

## 常用命令
- 装机：    `./gradlew :androidApp:installDebug`
- 看日志：  `adb logcat -s AiChat:V`

## 注意
- 新增权限必须改 AndroidManifest.xml，并**同步更新本文件**
- 改 minSdk 前先确认 shared/ 里用到的 API 兼容性

iosApp/AGENTS.md：

# iosApp/ — iOS 壳（Xcode 工程）

## 重要：这里不用 Gradle 构建
- 这是 Xcode 工程，**不要尝试用 gradlew 构建它**
- 改了 shared/ 的代码后，先跑：
    `./gradlew :shared:linkDebugFrameworkIosSimulatorArm64`
  让 Xcode 拿到新框架，再去 Xcode 里 Run

## Swift 侧只做桥接
- 生命周期、权限申请、导航容器
- 业务逻辑**全部回 shared**，不要在 Swift 里重写一遍

## 常见坑
- Info.plist 缺权限描述：模拟器运行才报错，Xcode 不提示
- 改了 framework 的 export 后要 Clean Build Folder
- Kotlin 的 sealed class 在 Swift 侧要遍历所有分支（写全，别用 default）

为什么这三份要分开写？

因为**“该做什么"和"不该做什么"在不同目录里完全相反**：

• 在 shared/，你要写"不要碰平台 API”
• 在 androidApp/，你要写"不要写业务逻辑"
• 在 iosApp/，你要写"不要用 Gradle 构建这个目录"

同一个仓库，规则互相冲突。 一份根 AGENTS.md 写不下这些——这就是"就近生效"存在的意义。

顺带一提：如果团队里工具是混用的

AGENTS.md 只是"约定"，不同工具读它的方式仍有差异。官方给了一些配置参考：

• Aider：在 .aider.conf.yml 里加一行 read: AGENTS.md
• Gemini CLI：在 .gemini/settings.json 里配置 { "context": { "fileName": "AGENTS.md" } }
• 老文件迁移：mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md（软链保留兼容）

放到 KMP 项目里，还有一种情况是工具版本不齐——比如有人的 Claude Code 还没升到 2.1.277。这时候可以在关键目录放一个 CLAUDE.md -> AGENTS.md 的软链顶上。

但请记住 Lütke 那句话：这就是在付"复杂度税"。

能统一升级工具，就别维护两份文件——软链是过渡方案，不是终局。

几个我踩过的坑

① 别把 AGENTS.md 写成 README 的翻译版。 README 是给人看的"项目介绍"，AGENTS.md 是给 agent 的"操作手册"。区别在于：README 讲 what，AGENTS.md 讲 how，而且要能直接执行。

② 别写"应该是"“建议"“尽量”。 agent 对模糊表述的处理方式是不可预测的。要么是硬约束（写清后果），要么就不要写。

③ 别让它过期。 过期的命令比没有命令更糟——agent 会照着跑，然后卡在一个已经不存在的任务上。改构建脚本时顺手改 AGENTS.md，应该成为习惯。

④ 别贪多。 官方那个最小示例就十几行，够用了。上下文是有预算的，你写给 agent 的每一行，都在挤占它理解代码的空间。

⑤ 目录树画出来。 这个投入产出比最高。一张准确的目录树，能省掉 agent 十次 ls。

我的看法

第一，AGENTS.md 的胜负，本质是"平台中立"对"工具绑定"的胜利。

Anthropic 拖了近一年才支持，最后还是支持了。原因很简单：当 6 万个项目用同一个格式，你不支持，就是在给用户加税。

Shopify 那句"复杂度税”，戳中的是所有大仓库的真实痛点。

第二，对 KMP 项目来说，AGENTS.md 的价值可能比对普通项目更高。

因为 KMP 的坑特别"目录相关"：

• 这段代码在 commonMain 还是 iosMain？规则完全不同
• 这个 API 三端都有吗？
• 改完要不要重新 link iOS 框架？

这些判断，如果每次都靠人在对话里说一遍，成本很高；写进目录级的 AGENTS.md，就变成了一次性投入。

第三，这件事的长期意义可能比看起来大。

当 AI 编程工具从"补全代码"走向"独立完成任务"，“仓库里有没有一份说清楚规矩的文件”，会越来越像"这个项目有没有自动化测试"——是工程成熟度的标志之一。

而且写它还有个附带好处：写 AGENTS.md 的过程，本身就是一次团队规范的梳理。 你会被迫把那些"只有老员工才知道"的隐含规则写下来——这件事的价值，可能比让 AI 聪明一点更大。

想问问你：

你现在的项目里有 AGENTS.md 吗？ 如果还没有，你觉得最难写的是哪部分——是构建命令，还是那些"只可意会"的约定？

或者你在 KMP 项目里踩过什么坑，后来靠文档解决了？ 评论区聊聊，我可以整理成下一篇。

参考资料：AGENTS.md 官方规范（agents.md）、The Register（9/18）、36Kr / CSDN 关于 Shopify 与 Anthropic 争议的报道（8/26）、Claude Code 2.1.277 更新说明。

前段时间我写过一篇鸿蒙 KMP 的文章，当时查到一个关键信息：社区发布的正式版，是基于 KMP 2.2.21 / CMP 1.9.2 做的鸿蒙适配。

前两天再去翻那个仓库，发现它的分支列表里多了一行字：

develop-2.4 框架 KMP 2.4.21 _ CMP 1.12.0 版本对应的文档集合

而且这个分支21 小时前刚更新过。

另外还有一条：

main-2.2（默认分支） 框架 KMP 2.2.21 _ CMP 1.9.2 版本对应的文档集合

一边是已经发出去的正式版，一边是正在推进的新基线。

KMP 在鸿蒙这条线上，开始跟上游的最新版本对齐了。

而几乎同一时间，上游 JetBrains 刚发布 Kotlin 2.4.20。

两条线，撞在了一个时间点上。

先把上游这条线讲清楚：Kotlin 2.4.20 改了什么

如果你只扫一眼更新日志，可能会觉得"哦，又是个修修补补的版本"——两百多条变更里，大半是 bugfix。

但里面有几个点，对写 KMP 的人来说很实在。

第一，Swift 互操作终于"能打了"。

这次 Swift export 支持把 Kotlin 的 sealed class 直接映射成 Swift 的 enum：

// 不用再写 default 了
let name = switch shape.sealedType() {
case .circle(let t):    "圆"
case .rectangle(let t): "方"
}   // ← 穷尽检查

以前处理这种多态类型，Swift 侧要么写一堆 if let，要么被迫加一个永远走不到的 default 分支——穷尽性检查直接失效。现在编译器能帮你查漏了。

还有跨语言继承：Kotlin 类型可以继承 Swift 的类/协议（含纯 Swift 库），不用再包一层。

这两件事指向同一个方向：KMP 在 iOS 侧一直被人诟病的"互操作摩擦"，正在被一点点磨平。

第二，klib 增量编译进 Beta。

kotlin.incremental.native=true

改一行 Kotlin 代码，不用再等整个 native 模块重编。这个体验改善，做过 Kotlin/Native 的人应该懂。

第三，Kotlin/JS 的测试工具链从 Karma 换成了 Playwright——算是跟上时代。

所以上游这条线的主旋律是：把跨语言的接缝处理得更顺。

再看鸿蒙这条线：它现在走到哪了

要理解鸿蒙这边，得先看它的版本号规则——这是昨天刚发布的正式版公告里写的：

版本号采用「上游基线 + 鸿蒙适配序号」：2.2.21-1.0.0 / 1.9.2-1.0.0 表示基于上游 KMP 2.2.21、CMP 1.9.2 的鸿蒙适配正式版。

这个规则很关键。它说明了一件事：

鸿蒙适配不是另起炉灶，而是在追上游的版本。

所以你会看到 2.2.21-1.0.0 这样的编号——前面的 2.2.21 是它对应的上游 Kotlin 版本，后面的 1.0.0 是鸿蒙适配自己的迭代号。

已经发布并进了 Maven 仓的有：

而 develop-2.4 这条新分支，目标基线就是 KMP 2.4.21 / CMP 1.12.0。

开发节奏公告里也写了：

develop 分支：用于每月开发态代码合入，每月准出后合入 main 分支。

翻译一下：每月推进一版，成熟了才合进正式线。 不是拍脑袋发版，而是有节奏的滚动。

这条线上最近在忙什么

翻了 develop-2.4 的提交记录，最近的动作挺有意思。

最新一条是把 CAPI 用户手册适配到 API 26——把 OHOS CAPI 版本更新到 API26，并且同步更新了「模块、最低 API 与典型依赖库」，还专门加了一节说明**「CAPI 升级至 API 26 后导致的特殊变更」**。

另一条是更新 akinterop 到 1.0.1、sqldelight 到 2.2.1-1.1.0。

这两个方向，恰好对应鸿蒙跨平台落地的两个真实卡点：

• CAPI 跟着鸿蒙系统版本走——系统升级，桥接层就得跟着升，这是"不断档"的问题
• 三方库的适配版本号——生态库能不能跟上，决定了项目敢不敢用

顺带一提：CMP 1.12 上游给的亮点

既然 develop-2.4 这条线要跟到 CMP 1.12.0，那 1.12 上游改了什么，也值得看一眼。

CMP 1.12.0 是 8 月 25 日发布的，最亮的一条在 Desktop 侧：

MCP server was introduced for Compose Hot Reload that enables AI agents to interact with a running Compose application in real time

翻译一下：给 Compose 热重载加了个 MCP server，让 AI agent 能实时和一个正在运行的 Compose 应用交互。

这条挺微妙的——Compose 和 AI 的结合点，正在从"用 AI 写 Compose 代码"，走向"让 AI 直接操作跑着的应用"。

当然它也带了一批破坏性调整，迁移时要留心：

• NativeCanvas、NativePaint 这些 typealias 的弃用级别被提到了 ERROR
• SwingPanel 的 background 参数弃用

从 1.9.2 跳到 1.12.0，不只是版本号变了——迁移成本也是要算进去的。

两件事凑在一起，说明了什么

把这两条线放在一起看，我看到的是一个挺清晰的图景：

KMP 的"一码多端"，正在多条战线上同时推进。

• 上游在打磨跨语言互操作的体验（Swift export、增量编译）
• 鸿蒙这条社区线在追上游版本（2.2 → 2.4）、补系统适配（CAPI → API 26）、扩三方库生态

它们不是同一个团队在做，但走的是同一个方向——让"写一套 Kotlin，跑更多平台"这件事，摩擦更小一点。

对开发者来说，判断标准其实很简单：

当你评估一个新平台时，问的不再是"支持不支持"，而是"上游跟到哪个版本了、库够不够用、性能顶不顶得住"。

从"能不能跑"到"跟得上吗"，这本身就是个阶段性的变化。

但社区的真实声音，比公告更值得听

公告总是漂亮的。我特意去翻了社区讨论区，那才是这条线真正的体温。

最热的一帖，是问"能不能尽快合并到 JetBrains 官方分支"（30 天前发起，7 条回复）。

发起人的原话挺直接的：

我现有的纯 KMP&CMP 应用项目添加鸿蒙平台存在大量库不支持问题，编译过程还出现几个已适配的库存在内部依赖冲突，希望尽快合并上游方便整个 KMP 社区的库开发者新增 ohos 的库版本，CPF 社区对库支持的进度过于慢了。

他具体点了三个库：androidx-datastore、androidx-room3、androidx-sqlite——“这三个基本就是大家普遍使用的持久化方式的基础依赖库了”。

然后是最扎心的部分：

它们都没有 ohos x86 的支持。开发者在 win 平台几乎无法直接开发测试一个正常功能的应用，起码你得一直接一台鸿蒙手机充当测试平台……

他还举了个具体的坑：从某个镜像仓库拉到的 room3 alpha 版本，生成代码会报 androidx.sqlite 缺少实现；而用上游的 room3 3.0.1 就没问题。

官方回复了，态度挺实在：

您好，关于 ohos x86 的支持，已在规划中，感谢您的关注。

其他帖子也各有各的真实：

• “skia 渲染模式下页面帧生产被拖至约 3 秒一帧，疑似 VsyncOnDemand 延迟注销机制异常”——性能问题
• “material3 导致移植已有项目阻塞”——组件库的坑
• “当前 webView 有支持吗？”——能力覆盖
• “大家有项目真实上线吗？有遇到什么坑吗”——底下有人回了四个字：“正在做语音助手 KMP 版本适配”

这几条加起来，才是这条线的真实状态：能跑通、有人在用、但生态和性能还在补课。

为什么"跟上上游"是件慢活

看到社区那句"进度过于慢了"，可能会有人觉得是投入不够。

但这里有个技术现实值得说清楚：鸿蒙适配改的是编译器后端，不是写个插件。

翻 CPF-KMP-CMP 的仓库列表，你会看到这些名字：

kotlin、compose-multiplatform、compose-multiplatform-core、skiko、akinterop、cicd-toolkit……

它们是 Kotlin 编译器、Compose 框架、图形渲染层的鸿蒙分支。

这意味着这份工作至少包括：

• 给 Kotlin/Native 加一个新的编译目标（target）
• 把 Compose 的渲染管线接到鸿蒙的 Render Service
• 让 Skiko 封装的 Skia 图形库能在鸿蒙上跑起来

而每次上游发新版本，这些改动都要重新对齐一遍。

这也是"上游基线 + 适配序号"这个版本号规则真正的含义——它精确描述了这份工作的性质：持续的追踪，而不是一次性的移植。

再看那句"每月开发态代码合入，每月准出后合入 main"，感觉就不一样了：

这不是慢，这是在用一个能持续的速度，做一件很重的事。

我的几点看法

第一，“适配"这件事的本质是"跟上游”，不是"造轮子"。

从版本号规则（上游基线 + 适配序号）就能看出来——鸿蒙这条线的核心工作是把上游的编译器/UI 框架搬到鸿蒙上跑通，而不是自己另搞一套 API。

这意味着它的天花板和上游绑在一起：上游把 Swift 互操作做顺了，那是 iOS 的红利；上游把编译器改进了，鸿蒙这边跟进才能吃到。

第二，社区抱怨的那三条，其实指向同一个问题。

x86 支持、三方库版本、性能——表面看是三件事，本质都是**“生态成熟度”**。

而生态成熟度有个残酷的特点：它不能靠热情解决，只能靠时间和真实项目打磨。 官方回"已在规划中"，是实话，也是实话里透出的无奈。

第三，如果你在评估要不要上这条线，我给个判断框架。

别问"支持鸿蒙吗"——问这三个问题：

1. 上游跟到哪个版本了？（现在是 2.2.21 稳定、2.4.21 开发中）
2. 我依赖的库适配了吗？（尤其是持久化、网络这类基础库——room3、datastore 是公认痛点）
3. 我的开发机是什么？（如果需要 x86 模拟器，现在还得等；Mac M 系列 + 真机的组合比较稳）

三个都过了，再动手；有一个卡住，就先把方案记在备忘录里。

最后

Kotlin 2.4 和鸿蒙 2.4，看起来是两件不相干的事。

但它们其实在回答同一个问题：

一套 Kotlin 代码，能跑多少地方、跑得多好？

上游在把跨语言的接缝磨平，鸿蒙这条线在把版图铺开。

这两件事，都在让那个数字变大。

想问问你：

你手上的 KMP 项目，会因为"鸿蒙适配跟到 2.4 了"而重新考虑吗？

或者你已经踩过这条线的坑了？ 评论区聊聊，我挺想知道真实项目的反馈。

参考资料：CPF-KMP-CMP 社区仓库（AtomGit/GitCode）分支与 Release 公告、社区讨论区公开帖、JetBrains Kotlin 2.4.20 发布说明。

9 月 7 日，JetBrains 发布了 Kotlin 2.4.20。

如果你只是扫一眼更新日志，可能会觉得"哦，又是个修修补补的版本"——毕竟两百多条变更里，大半是 bugfix。

但对写 KMP 的人来说，这个版本有几个东西是真香的。尤其是 Swift 互操作这块，终于补上了长期以来的几块短板。

先说结论：这次最值得关注的是三个方向——Swift 互操作能力、编译速度、跨平台一致性。下面一个个拆。

一、Swift export 支持 sealed class：iOS 同学的 switch 终于不用写 default 了

用 KMP 写过 iOS 的人，大概率都遇到过这个别扭的场景。

你在 Kotlin 里定义了一个很优雅的 sealed interface：

sealed interface Shape

class Circle : Shape
class Rectangle : Shape

fun createCircle(): Shape = Circle()

逻辑上天衣无缝，Kotlin 侧 pattern matching 一把梭。

但到了 Swift 那边，Kotlin 的 sealed 类型只能当成一个普通类来用，你根本没法做穷尽匹配，只能写一堆 if 判断，最后再兜一个 default。

更难受的是：哪天 Kotlin 侧加了新的子类，Swift 侧的编译不会报错——于是线上就可能出现一个没人处理的 case。

2.4.20 把这个问题解决了。sealed 类型现在会映射成 Swift 的 enum，编译器会生成一个 sealedType() 方法：

let shape = createCircle()

let name = switch shape.sealedType() {
case let .circle(type): "It's a \(type.value)"
case let .rectangle(type): "It's a \(type.value)"
}

注意这里——没有 default。

Swift 编译器会检查穷尽性，而且因为映射成了 enum，Xcode 的自动补全也跟着好用了。哪天 Kotlin 侧加了新的 sealed 子类，Swift 侧会直接编译报错提醒你处理。

这比"运行时才发现漏了 case"强太多了。

二、跨语言继承：用纯 Swift 库，不用再绕路了

第二个变化更实际：Swift export 支持跨语言继承了。

什么意思？说个真实场景——你想在 iOS 侧用 CryptoKit 这个纯 Swift 库，但它没法直接导入 Kotlin。

以前的做法要么是写一层 Objective-C 桥接，要么干脆放弃，在 Kotlin 侧找个替代实现。现在可以直接这么干：

Kotlin 侧声明接口和一个开放基类：

interface CryptoProvider {
    fun hashMD5(input: String): String
}

fun processHash(provider: CryptoProvider, input: String): String =
    provider.hashMD5(input)

open class SwiftBase

Swift 侧继承基类、实现接口，然后把对象传回 Kotlin：

import CryptoKit

final class IosCryptoProvider: SwiftBase, CryptoProvider {
    func hashMD5(input: String) -> String {
        guard let data = input.data(using: .utf8) else { return "failed" }
        return Insecure.MD5.hash(data: data).description
    }
}

let provider = IosCryptoProvider()
print(processHash(provider: provider, input: "Hello, world!"))

Kotlin 收到这个 Swift 对象时，就把它当成接口的普通实现来调用。

这就是官方说的 reverse import 模式：契约写在 Kotlin，实现在 Swift。对那些必须依赖平台原生库的场景，这条路终于顺了。

三、增量编译进 Beta：改一行代码，不用再等一杯咖啡

这条可能是最能改善日常开发体验的。

Kotlin/Native 的编译速度一直是 KMP 的痛点之一。klib 的增量编译其实从 1.9.20 就有了，但一直在打磨。这次正式进入 Beta，官方说 debug 构建的编译时间大幅减少。

打开方式很简单，在 gradle.properties 里加一行：

kotlin.incremental.native=true

官方还提到，他们计划在后续版本里默认开启这个选项。

顺带一提，导出 XCFramework 的时候，assembleSharedXCFramework 任务现在会自动生成 Package.swift 文件。以前发布带 SwiftPM 依赖的 XCFramework，得自己处理 SwiftPM 包的分发问题，现在省事了。

四、Wasm 侧：几个不容易注意但很关键的改动

如果你的项目有 web 端，这几点值得留意。

伴生对象初始化顺序对齐 JVM

以前 Kotlin/Wasm 里，父类和子类的 companion object 初始化顺序可能和 JVM 相反。跨平台项目里，这种差异最容易变成"本地跑得好好的，换个平台就出鬼"的 bug。现在统一按 JVM 的行为来了。

Wasmtime 运行时支持

wasmWasi 目标以前只能用 Node.js 跑，还得先做一层 JavaScript 引导。现在可以直接用 Wasmtime 这个独立的 WebAssembly 运行时：

kotlin {
    wasmWasi {
        wasmtime()
    }
}

新增编译模式

以前只有 monolith 模式（整个项目和依赖一起编译，生成单个二进制，体积最小但每次都全量）。现在多了两个多模块模式，可以按需选择：

• 开发时用 multimodule-closed-world，只重编译改动的模块，迭代更快
• 生产构建仍用 monolith，保证产物最小

配置方式：

kotlin.wasm.compilationMode=multimodule-open-world

注意一个 breaking change：@JsFun 声明里现在用顶层 require() 会直接报错。如果之前这么写过，得迁移到 @JsModule 注解或者 import() 表达式。

五、Kotlin/JS：Karma 退役，Playwright 接棒

Kotlin/JS 的浏览器测试一直用 Karma 当启动器，但 Karma 项目已经停止维护两年了。

2.4.20 引入了新的测试 DSL：底层换成 Playwright 驱动（支持 Chromium、Firefox、WebKit 三家），测试运行器用 Mocha，打包工具暂时还是 webpack（官方说后续会换 Vite）。

用法是在 browser {} 里加一个 test {} 块：

kotlin {
    js {
        browser {
            @OptIn(ExperimentalJsTestDsl::class)
            test {
                timeout = 2.seconds
                chromium()
                firefox()
                webkit()
            }
        }
    }
}

另外，suspend lambda 现在可以导出成 JavaScript 的 async 函数了——这个对跨端调用挺实用。

六、标准库和其他

几个顺手能用的：

• 协程堆栈恢复：新增 StackTraceRecoverable 接口。协程之间抛异常时，能看清异常从哪来、被谁重新抛出。自带复杂构造参数的异常，实现一下 copyForStackTraceRecovery() 就行。
• 集合工具：新增了检查集合元素相等性和唯一性的函数。
• kotlin.test：新增断言函数重载。
• Gradle：完全兼容 Gradle 7.6.3 到 9.7.0；Problems API 现在带编译器诊断 ID 并做了分组，排错时能快速定位问题来源。
• 编译器：JVM 21+ 上 when 表达式的 invokedynamic 编译从实验转正（默认开启）；新增 kotlinr 运行命令和独立的 native image。

这些变化对 KMP 开发者意味着什么

把上面串起来看，我觉得 2.4.20 释放了三个信号：

1. iOS 互操作正在从"能用"走向"好用"

sealed class 映射成 enum、跨语言继承支持纯 Swift 库——这两条直击 KMP 在 iOS 侧最常被吐槽的点。以前大家说 KMP “Android 体验好，iOS 差点意思”，现在这个差距在肉眼可见地缩小。

2. 编译体验被当成正经事在解决

klib 增量编译进 Beta、Wasm 多模块编译模式，都是在解决同一件事：让日常开发不用等。编译速度是 KMP 最现实的劝退点之一，这方向对了。

3. 跨平台一致性越来越被重视

Wasm 的伴生对象初始化顺序对齐 JVM，看起来是个小改动，但这类"平台间行为不一致"恰恰是跨平台项目最难缠的问题。官方在主动收窄这些差异。

顺带提一句另一条新闻：Google 前几天发布了 ADK for Kotlin 1.0，可以用 Kotlin 写生产级 AI Agent。Kotlin 和 AI Agent 这两个圈子，今年的交集肉眼可见地多起来了。

升级建议

• 一般项目：直接升。这个版本以修复为主，风险不大。
• KMP 项目：强烈建议升，Swift export 那几个改动是实打实的体验提升。
• 用 Wasm 的项目：升级前先检查 @JsFun 里的 require() 调用，这是唯一的 breaking change。
• 想试增量编译：先加 kotlin.incremental.native=true 试试水，有问题及时反馈给官方。

Kotlin 的版本节奏一直很稳，不搞大跃进。这种"每次解决几个真问题"的迭代方式，其实对生产项目最友好。

参考资料：What’s new in Kotlin 2.4.20 · GitHub Release

如果你是个资深工程师，找工作时会写什么要求？

钱多、事少、技术栈新、团队靠谱——大概就这些。

Jake Wharton 不一样。这位被国内开发者称为"J 神"的 Android / Kotlin 开源大神，给自己列了九项择业标准。

第一条是：不加入 AI 公司，不参与以 AI 为核心的产品，也不接受公司强制工程师使用 AI。

他估算了一下，这一条直接排除了约 80% 的潜在雇主。

先别急着说他"清高"。他并非没有选择——美国资深 Kotlin 工程师的基本年薪通常 20 万美元起，外加每年约 10 万美元的股权（四年归属）。进入 AI 赛道回报可能更高。

但他还是这么干了。

InfoQ 前几天发了这场两小时访谈的完整稿，一万三千多字。我读完最有感触的不是他的结论，而是他给的理由。

他是谁：Kotlin 成为 Android 官方语言的推手之一

不熟悉 Kotlin 圈的人可能不知道这个名字的重量。

Jake Wharton 是 OkHttp、Okio、Retrofit 这些明星开源库的作者或核心贡献者——写过 Android 的人大概率都用过他的库。

更关键的是：他是 Google Kotlin 团队的第一位工程师。

在加入 Google 之前，他在 Square（后来的 Cash App）工作。当时为了说服公司内部采用 Kotlin，他写了一份论证文档。这份文档后来被他公开，间接推动了整个 Android 社区对 Kotlin 的兴趣。

后来 Google 决定让 Kotlin 成为 Android 官方一等语言，他加入了那个团队。

他说，这个机会"几乎不可能拒绝"——因为没有什么比加入负责整个 Android 工具链的公司、并推动 Kotlin 成为官方语言，是更大的认可了。

所以他不是"反技术"的人，是把职业生涯押在语言和工具链上的人。

那问题就来了：这样一个人，为什么对 AI 编程如此抗拒？

理由一：AI 的推广方向，和过去所有工具都相反

这是我读完最认同的一段。Jake Wharton 原话：

传统上，一项开发工具通常由工程师自下而上推动。可能是一名工程师喜欢上一门新语言，比如 Kotlin；也可能是一款新 IDE，比如 IntelliJ IDEA；或者是一套新的构建系统。工程师在实际工作中发现它有价值，热情逐渐感染其他人，然后大家再去说服工程管理者批准采用它。

但 AI 工具的推广方向似乎完全相反。为什么要由一家公司的 CEO 告诉工程师，日常工作应该使用什么工具？

这个观察很锋利。

回想 Kotlin 是怎么起来的：一群工程师真的觉得它好用，在项目里偷偷开始用，然后慢慢说服老板。 从下往上，自发的。

而 AI 编程工具的落地路径，在不少公司是这样的：高管看到新闻，要求全员必须用 AI 提效，纳入考核。 从上往下，行政式的。

工具的合法性，过去来自它真的好用；现在，有时候来自它被规定必须用。

这个转变，值得每个工程师想一想。

理由二：交出的是能力，不只是工作

关于"AI 会让工程师变成齿轮"这个说法，他的完整表述是这样的：

AI 可以帮助工程师处理重复劳动，但最不负责任的用法，是让 AI 生成超出使用者能力范围的代码。如果没有大模型就无法完成任务，开发者往往也无法真正理解、验证和维护结果。

一旦形成依赖，工程师交出去的不只是部分工作，还包括自己的能力和议价权，最终可能变成一枚更容易被低成本替换的齿轮。

注意这句话的边界——他没有说"不要用 AI"，他说的是"不要用 AI 生成超出你能力范围的代码"。

这两句话差别很大。

前者的意思是"AI 会取代你"，后者说的是一个更具体、也更隐蔽的风险：

如果一个需求，你原本需要花两天想明白怎么设计，现在让 AI 十秒钟吐出来一段能跑但你不完全理解的代码——

代码是有了，但你对这个系统的理解，其实退化了。

几次之后，你维护的东西里，有一块是你自己看不懂的。

到那时候，你的价值锚点在哪里？

理由三：版权和许可证，这笔账还没算清

这条他讲得很直接：

在我看来，它们建立在大规模使用受版权保护内容的基础上。模型训练忽视了艺术家的版权，也忽视了开源代码的许可证。

能够在网上访问一项内容，并不意味着你就拥有重新组合、改写它，甚至逐字输出它的权利。

对一个把大量心血投入开源项目的人来说，这个立场很好理解——他的代码被人拿去训练模型，然后模型生成的东西反过来又卖给他，这笔账在伦理上确实没算清。

他还补了个细节：现在开源维护者要应对的负担里，多了一项——大量低质量的 AI 生成 PR。

这个我信。维护过开源项目的人应该都有体感。

但他并不认为 AI 会消失

别误读他。访谈里他对 AI 的能力判断，其实相当克制也很清醒：

“AI 已经强大得令人不安”，但这并不意味着它能够稳定、无误地承担整个软件工程过程。

对他而言，AI 最多只能是工具箱中的一件工具，而不能成为工程能力的地基。

“不能成为地基”——这个比喻我觉得很准。

工具箱里的工具，是你可以不用的；地基，是没有就站不住的。

他还提到一个反直觉的观点：AI 能写代码，不等于开源库失去价值。因为开源的价值不只是"给你一段能用的代码"，而是持续维护带来的长期红利——

可能有人今天修复了一个你暂时不会遇到的边缘 Bug，两年后你的业务重构，本来会触发这个问题，但因为你使用的是同一个开源库，它已经被提前解决。

这段逻辑很严密：AI 给你的是当下的一份代码，开源给你的是一个持续演进的公共基础设施。 这两者不是一回事。

顺带聊了 Kotlin 圈的事，这几条和我们相关

访谈后半段聊 Kotlin，有几条对你我这种写 Kotlin 的人挺有价值：

1. “Kotlin 很像是 Java 十年后想要成为的样子”

他解释：Java 必须避免破坏已有代码，所以语言演进慢；Kotlin 能把很多未来可能进 Java 的现代特性提前给开发者用，还能兼容停留在 Java 8 / 11 的老代码库。

2. 会 Kotlin 已经不是职业优势了

这句听着扎心，但他的解释很公道：

我不确定它现在还能算是一项优势。从某种意义上说，这反而体现了 Kotlin 的成功：它已经成为一项默认要求，而不再是一种稀缺、难以找到的能力。

因为 Google 把 Kotlin 定成 Android 官方语言，现在学 Android 就直接学 Kotlin，用人单位默认你会。

但——

如果开发者掌握的不只是常规 Kotlin，而是 Kotlin Multiplatform 等相对进阶的能力，那么它仍然可能构成差异化优势，让你从其他 Kotlin 开发者中脱颖而出。

“KMP 还是差异化优势” 这句话，大概是这段访谈对我们最直接的信号。

3. Meta 把 Kotlin 格式化工具捐了

就在他录制这期节目的那一周，Meta 把自己的 Kotlin 格式化工具贡献给了 Kotlin Foundation，未来可能成为官方格式化工具。

4. 2026 年的 Kotlin 由三方共治

理想状态是 JetBrains、Google 和社区三方共同参与。Kotlin Foundation 成立的目的之一，就是让这门语言不再完全隶属于 JetBrains——避免任何一家公司单独控制它。

我的两难：一边写 AI 客户端，一边听他反 AI

说点私人的。

我最近在写一本关于 AI Chat 客户端的小册子——从零搭一个跨平台的 AI 聊天应用。用的技术栈就是 KMP。

所以读这篇访谈时，我有种奇妙的错位感：我一边在用 AI 能力做产品，一边听行业里最受尊敬的人之一说，AI 正在毁掉工程。

但冷静下来想，我其实不觉得矛盾。

他反对的从来不是"AI 这个工具"，而是三件事：

1. 把 AI 当成强制性的组织纪律，而不是可选择的工具
2. 用 AI 替代思考，让自己失去验证和维护的能力
3. 建立在版权和许可证问题上的商业模式

这三条里，只有第二条是我需要时刻警惕的——尤其是在我自己写代码、写教程的时候。

工具会越来越强，这是趋势，拦不住也不用拦。但"我的判断力还在不在自己手上"，这件事只能自己负责。

这大概就是他那句"不能成为地基"的意思。

最后

这场访谈里，他还有一句话我印象很深：

我不认为过去几年软件的整体质量得到了提高，也不认为这类工具长期来看会改善软件质量。但一些公司高管看到的却是另一幅图景。

到底哪幅图景是对的？现在谁也不知道，可能需要五年才能验证。

但有一个风险是确定的：如果一个人把自己的能力全部外包出去，那无论 AI 有没有那么强，他都已经没有议价权了。

你怎么看这件事？你现在的工作里，AI 参与了多少？

欢迎在评论区聊聊——尤其想知道，有没有人跟我一样，一边用 AI 做产品，一边对它的边界心里发毛。

参考资料：Jake Wharton 访谈全文（InfoQ，2026-09-11） · 访谈原视频

做 Kotlin 的人这两年大概都有个心结。

AI Agent 的浪潮一波接一波，但翻开源码一看——LangChain、CrewAI、AutoGen，清一色 Python。想在自己熟悉的 Kotlin 生态里搭一套 Agent，要么自己拿 HTTP 客户端手搓，要么用 Python 写个服务再从 Kotlin 调，中间隔着进程和序列化的双重麻烦。

9 月 9 日，Google 把这个空缺补上了：Agent Development Kit (ADK) for Kotlin 1.0 正式 GA。

而且这次不是简单地把 Python 版翻译一遍——它的底层是一个 Kotlin Multiplatform (KMP) 核心。

这个细节很关键，后面细说。

先看它到底是个什么东西

ADK for Kotlin 的定位很清楚：与后端模型、会话存储、记忆系统完全解耦。

说人话就是：Agent 的逻辑用 Kotlin 写一遍，模型可以接 Gemini，也可以接别的；会话存内存、存 Room、还是存云端，随你换。

1.0 版本已经和 ADK Python / Java 版功能对齐，把 Python 生态里那些成熟的多智能体模式搬了过来：

• 层级多智能体：Agent 可以链式编排，把任务委派给专门的子 Agent
• 上下文压缩：历史对话太长时自动摘要，把 token 控制在窗口内
• Human-in-the-loop：敏感操作可以暂停，等用户确认后再继续执行
• 会话可恢复：Agent 交互状态能序列化保存，跨会话恢复
• Java 互操作：现存的 Java 应用可以直接调用 Kotlin 写的 Agent
• Vertex AI 集成：企业级的 Session、RAG Memory、Memory Bank 服务

这里有一条我觉得特别值得说的：上下文压缩。

写过 AI Chat 的人都懂，多轮对话的历史管理是个绕不开的活儿。做滑动窗口会丢信息，全量塞进去会爆 token。ADK 把它做成了框架内置能力，不用自己造轮子。

技术亮点：为什么说它是"Kotlin 原生"

这是我觉得 ADK for Kotlin 最有意思的地方。

用注解定义工具，编译期生成 schema

Python 的 Agent 框架普遍靠运行时反射来解析函数签名、生成工具描述。ADK for Kotlin 走了另一条路——用 KSP（Kotlin Symbol Processing）在编译期生成。

你的代码写起来就是普通的 Kotlin 函数：

class InfrastructureDiagnosticsService {

    @Tool
    suspend fun getServiceMetrics(
        @Param("Target service or database cluster") serviceName: String,
        @Param("Time window in minutes") windowMinutes: Int? = 15,
    ): ServiceMetrics {
        // 查监控后端：Datadog、Prometheus、Cloud Monitoring
        return ServiceMetrics(
            serviceName = serviceName,
            cpuUsagePercent = 91.4,
            connectionPoolUsagePercent = 98.5,
            p99LatencyMs = 2450,
            errorRatePercent = 4.2,
        )
    }
}

编译期 KSP 会自动生成 generatedTools() 扩展函数。

这意味着三件事：类型安全（schema 和函数签名不会对不上）、支持 suspend 函数（协程天然融入）、零运行时反射（启动快、体积小，对 Android 尤其友好）。

对写惯了编译期校验的 Kotlin 开发者来说，这个设计取向应该会很有共鸣——能在编译期发现的问题，就别拖到运行时。

Skill 机制：渐进式披露

ADK 里有个叫 Skill 的概念，我觉得设计得挺巧。

你把标准作业流程写成 SKILL.md 放在 resources 里：

---
name: database-incident-triage
description: Standard operating procedure for diagnosing database latency spikes.
allowed-tools: [getServiceMetrics, fetchRecentDeployments, notifyOnCall]
---

# Database Incident Triage SOP

1. **Telemetry**: Call `getServiceMetrics` to inspect CPU, latency, and pool saturation.
2. **Correlation**: Call `fetchRecentDeployments` to check for recent changes.
3. **Safety Rules**: Never restart primary nodes during peak hours.
4. **Notify**: Broadcast diagnosis to `#production-alerts`.

Agent 只在需要时才把这份 SOP 加载进上下文，附带的资源文件（比如 assets/mitigation_rules.txt）也是按需拉取。

官方管这叫 progressive disclosure——token 花在刀刃上，别一上来就把所有知识灌给模型。

上手实战：一个数据库故障诊断 Agent

官方给的示例很实在。假设线上数据库告警了，我们要个 Agent 来帮忙分诊：

object IncidentTriageDemoAgent {
    val rootAgent = LlmAgent(
        name = "incident_triage_agent",
        model = Gemini(name = "gemini-3.8-flash"),
        instruction = Instruction(
            """
            You are an SRE on-call diagnostic assistant.
            1. Load the matching triage SOP using `load_skill`.
            2. Follow the playbook steps strictly.
            3. Use your diagnostics tools to inspect telemetry and notify the team.
            """.trimIndent()
        ),
        // 编译期生成的函数工具（零反射）
        tools = InfrastructureDiagnosticsService().generatedTools(),
        // 动态技能工具集
        toolsets = listOf(SkillToolset(NewFileSystemSource(resolveSkillsDir()))),
    )
}

跑起来：

fun main() = runBlocking {
    val runner = InMemoryRunner(
        agent = IncidentTriageDemoAgent.rootAgent,
        appName = "IncidentTriageApp"
    )

    val alert = "ALERT [P1]: Database latency spike detected on 'users-postgres-cluster'!"

    val events = runner.runAsync(
        userId = "oncall-sre",
        sessionId = UUID.randomUUID().toString(),
        newMessage = Content.fromText(Role.USER, alert)
    ).toList()

    for (event in events) {
        event.content?.parts?.firstOrNull()?.text?.let { println("Agent: $it") }
    }
}

注意这里用的是 runBlocking + 流式事件——协程是这套框架的一等公民，不是硬塞进去的。

Agent 接到告警后会自动走完一套流程：加载 SOP → 调 getServiceMetrics() 发现连接池饱和 98.5% → 调 fetchRecentDeployments() 定位到 25 分钟前的一次部署 → 推送诊断到告警频道 → 建议回滚。

这就是一个完整的工具调用 + 领域知识 + 自主决策的闭环。

Android 端侧：不只有云端

如果你做移动端，ADK for Kotlin 的 Android 扩展可能更让你兴奋。

移动端 AI 的难点在于平衡：云端推理能力强，但延迟、隐私、离线可用性都是问题。ADK for Kotlin 1.0 给了一套模块化的 Android 方案：

• LiteRT-LM：端侧跑小模型
• ML Kit（beta）：本地推理能力
• Firebase AI Logic：云端 + 端侧的混合编排
• Room 持久化：会话历史存 SQLite，进程被杀也不丢
• AppSearch 索引记忆：端侧全文检索的记忆服务
• FileArtifactService：生成的文件（对账单、回执）直接落本地存储

官方那个"金融助手"示例把这些串起来了：

fun createAndroidRunner(applicationContext: Context, agent: LlmAgent): InMemoryRunner {
    return InMemoryRunner(
        agent = agent,
        appName = "AndroidFinancialApp",
        // SQLite 持久化：进程死亡也能恢复会话
        sessionService = RoomSessionService.fromContext(applicationContext),
        // 端侧全文索引记忆
        memoryService = AppSearchMemoryService.fromContext(applicationContext),
        // 应用私有文件存储
        artifactService = FileArtifactService.fromExternalFilesDir(applicationContext)
    )
}

而且它把 HITL 做得很实用。转账这种敏感操作，定义工具时加个标记就行：

@Tool(
    name = "transferFunds",
    description = "Transfers money to another account. Requires explicit user approval.",
    requireConfirmation = true
)
fun transferFunds(
    @Param("Recipient account ID") recipientId: String,
    @Param("Amount in USD") amount: Double
): String { /* ... */ }

Agent 执行到这里会自动暂停，等用户在 UI 上点确认再继续。

这一条对做金融、医疗类 App 的同学，基本是刚需。

对 KMP 开发者意味着什么

回到开头说的那个"KMP 核心"。

ADK for Kotlin 的核心引擎是跨平台的，跟模型后端、会话存储、记忆系统全都解耦。这个架构选择的含义是：Agent 的业务逻辑可以共享。

想象一下：你的 Agent 编排逻辑、工具定义、SOP 技能文件，在 Android 上能跑，在服务端 JVM 上也能跑，未来如果 iOS 侧也支持，那就是一套代码三端复用——这不就是 KMP 一直在讲的故事吗。

结合我们之前聊的 Kotlin 2.4.20（Swift export 的 sealed class 映射、跨语言继承），Kotlin 在跨端 + AI 这两条线上的拼图，今年开始明显拼上了。

对做 AI Chat 客户端的开发者来说，还有个更直接的启发：框架级的能力（会话持久化、上下文压缩、HITL）已经有成熟实现了，不用再从零造。

怎么开始

加依赖就行：

dependencies {
    // 核心引擎 + KSP 处理器
    implementation("com.google.adk:google-adk-kotlin-core:1.0.0")
    ksp("com.google.adk:google-adk-kotlin-processor:1.0.0")

    // Android 端侧扩展（可选）
    implementation("com.google.adk:google-adk-kotlin-mlkit-android:1.0.0-beta")
    implementation("com.google.adk:google-adk-kotlin-litertlm:1.0.0")
    implementation("com.google.adk:google-adk-kotlin-firebase-android:1.0.0")
}

官方资源：

• 📖 文档与入门：adk.dev
• 🐙 GitHub：github.com/google/adk-kotlin
• 📱 Android 指南：Building Android agents with ADK
• ☕ Java 互操作示例：ADK Kotlin Java sample

小结

ADK for Kotlin 1.0 的意义，我觉得不在于它又多了个 Agent 框架，而在于：

Kotlin 生态终于有了一套编译期安全、协程原生、跨端可复用的 Agent 开发方案。

它没有把 Python 的套路硬搬过来，而是按 Kotlin 的语言特性重新设计了一遍——KSP 代替反射、协程代替回调、KMP 核心代替单平台实现。

对做 KMP 的人来说，这是个值得认真看看的东西。

参考资料：Announcing ADK for Kotlin 1.0 - Google Developers Blog（2026-09-09，作者 Guillaume Laforge）

先说个数字：四。

Android、iOS、桌面 —— 这是 Kotlin Multiplatform 这几年稳定覆盖的主力阵地（Web / Wasm 也在推进中）。写一套共享逻辑，加一套 Compose UI，几个平台一起跑。

而昨天，这个名单要加上第四个成员了：鸿蒙。

而且这次不是"理论上能跑"，是正式版本发布——组件进了 Maven 仓，Android Studio 插件市场上能搜到工具链插件，文档在 AtomGit 上。

最让我意外的是发布方那句话：

已经在其他平台使用 CMP 的开发团队，界面业务代码可直接复用同一套 Compose 写法，不必为鸿蒙完全重新写一套 ArkUI。

不用重写 ArkUI。 这五个字对做跨端的人来说，分量挺重的。

先把事实说清楚

这次发布的是 KMP&CMP 鸿蒙首版本，2026 年 9 月 15 日发布。

几个关键信息：

• 谁做的：CPF-KMP-CMP SIG 社区伙伴共建（注意，是社区 SIG，不是 JetBrains 官方，后面我会细说这个区别）
• 基于什么：源社区 KMP 2.2.21 / CMP 1.9.2
• 目标：把"逻辑跨端共享、UI 原生渲染"这套开发范式带到鸿蒙上
• 获取方式：组件已发布至 Maven 仓；工具链插件 KMP OHOS Support 在 Android Studio 插件市场搜索安装

官方对适用人群的定位也很清楚：

对已经使用 KMP/CMP 做跨端业务的团队，该版本有助于降低迁到鸿蒙的改造成本。鸿蒙开发团队也可借助这套能力，做 Kotlin 与 ArkTS 混合开发，拓展技术选型。

翻译一下就是：KMP 团队想上鸿蒙，现在成本低了；鸿蒙团队想用 Kotlin，现在有路子了。

顺便说个背景——这事其实铺垫了三个月。今年 6 月社区版就开了 Beta，8 月 InfoQ 还报道过一版实测数据（渲染内存降 95%、GC 卡顿率降 90%）。现在算是正式落地。

亮点一：Compose 直接跑鸿蒙，不用重写 UI

这是我觉得最有价值的一条。

在鸿蒙上开发，官方路线是 ArkTS + ArkUI。对已经在做 KMP/CMP 的团队来说，这意味着鸿蒙端要单独维护一套 UI——业务逻辑能共享，但界面得重写一遍。

这次发布把这条路铺平了：

CPF-KMP-CMP 在鸿蒙侧提供了 compose.ui、compose.foundation、compose.material、compose.material3 的平台实现，可延续熟悉的声明式 UI 习惯开发鸿蒙端界面。

compose.material3 都在。 也就是说，你写惯了的那套 Compose 代码，在鸿蒙上是能认的。

对一个已经在 Android/iOS 上跑 CMP 的项目来说，这意味着鸿蒙端的接入成本，从"重写一套 UI"降到"加一个 target"。

差别有多大？做过跨端的人应该懂。

亮点二：Kotlin ↔ ArkTS 双向互操作

第二条对存量项目很关键。

现实情况是：很多鸿蒙项目已经用 ArkTS 写了一堆东西（系统能力、业务模块），不可能整体推翻重写成 Kotlin。

这次的解法是 akinterop：

共享逻辑可继续写 Kotlin，系统侧或存量模块仍用 ArkTS 时，用 akinterop 做双向互操作：注解 / 装饰器声明意图，工具链生成桥接，少写 C 胶水。基础类型、容器与异常可跨侧传递，存量工程可渐进接入，不必为互通推倒重来。

“渐进接入，不必推倒重来” —— 这句话是给存量项目的定心丸。

注解声明意图、工具链生成桥接——比手写 C 胶水的体验好太多，写过 JNI 的人都懂那种痛。

亮点三：统一渲染（这条是技术核心）

这条比较硬核，但我觉得是整件事里最有技术含量的一环。

先说问题：传统的跨平台 UI 方案，通常要自建一套渲染管线。

自建有什么坏处？报道里说得很直接：

传统跨平台 UI 方案常自建渲染管线，这容易带来额外初始化与合成开销，也容易出现启动慢、动画和系统表现不一致等问题。

自渲染意味着你的 UI 不走系统那条路——启动要多一步初始化，动画节奏跟系统对不齐，看起来就"不像原生"。

这次的方案是反过来的：

CPF-KMP-CMP 将 Compose 绘制能力对接鸿蒙 Render Service / RenderNode 系统渲染能力，由鸿蒙系统统一完成合成与刷新调度（统一渲染需 API 19 及以上）。

把绘制能力交给鸿蒙系统自己去合成，收益是连锁的：

• 更快首帧：少了自渲染的初始化等待，启动和跳转更利落
• 精细化局部刷新：状态变了才更新，还支持局部录制——只重绘变化的区域
• 原生组件友好混排：Compose 页面能和 ArkUI、C-API 混排，地图、视频这类原生能力更容易嵌进来
• 对齐系统动画：帧节奏走系统的 DisplaySync，动画体验跟鸿蒙原生应用一致

最后一条尤其重要。跨平台应用"一眼假"的原因，往往不是布局不对，而是动画的节奏感不对——帧率调度跟系统不在一个节拍上。

⚠️ 注意一个限制：统一渲染需要 API 19 及以上。老设备上会退化。

性能账：省了 20% 编译时间，降了 30% 堆内存

这次给了几个挺具体的数字，不像很多"性能优化"的模糊说法：

编译侧（并行编译）：

将 LLVM IR 切分后多线程跑局部优化再合并，缩短大规模工程的编译等待；典型场景下约可节省 20%+ 耗时。

内存侧（CommonGC）：

采用并发标记—复制回收算法，降低内存碎片、减少 GC 停顿时间，典型场景下 KN 堆占用约可下降 30%。

另外还有两个工程化的优化很实用：

• 模块化拆分：单一 KMP 工程可配置成多个 .so，配合分布式编译进一步缩短构建
• Debug 增量编译：macOS / Linux 上支持基于静态库缓存的增量编译——只重编改动的部分，不必每次全量重链

（做 KMP 的人看到"全量重链"四个字应该会有点应激反应）

还有个细节我挺喜欢——后台不空转：

统一渲染路径支持按需申请 VSync 信号，当页面没有内容变化时，主动抑制刷新绘制；同时支持 LTPO 硬件特性，应用退到后台之后自动停止无效绘制循环……该行为为框架默认行为，不需要业务额外编写代码。

默认行为，不需要业务写代码。这种"框架替你操心"的设计，比让你手动去 onPause 里关动画友好多了。

上手：三步跑起来

流程比我想象的简单：

(1) DevEco Studio：用 6.0.0+ 下载 HarmonyOS SDK API 17+，打开工程里的 harmonyApp 配好调试签名。 (2) Android Studio：日常写 KMP&CMP 代码。 (3) Android Studio：选设备和 harmonyApp 点 Run（推包时保持 DevEco 运行）。

注意第 3 步那个括号——推包时要保持 DevEco Studio 开着。这类"两个 IDE 配合"的细节最容易踩坑，官方提前说了。

文档在 AtomGit（搜 CPF-KMP-CMP/docs），想深入看的可以去翻。

为什么鸿蒙这块拼图特别重要

说句实在话：对国内的 KMP 开发者，鸿蒙这块拼图可能比 Web/Wasm 重要得多。

原因很现实——在国内做移动端，鸿蒙已经不太是"要不要考虑"的问题了，而是"什么时候必须做"的问题。 尤其在政企、金融、车机、IoT 这些领域，推进速度比很多人预期的快。

而过去 KMP 团队面对鸿蒙的选择挺尴尬的：

• 共享逻辑能复用，但 UI 得重写（ArkUI）→ 相当于鸿蒙端要额外养一个人
• 或者干脆放弃 KMP，鸿蒙端单独起个工程 → 共享逻辑的优势全丢了

这次发布的意义就在这儿：它把"鸿蒙端 UI 也要重写"这个成本项，从等式里拿掉了一大半。

对一个小团队来说，这可能就是从"做不起"到"做得起"的差别。

说点冷静的：这事该怎么看

热点归热点，我得把几个边界说清楚，免得你判断失误。

第一，这是社区 SIG 项目，不是 JetBrains 官方。

发布方是 CPF-KMP-CMP SIG，不是 JetBrains 也不是华为官方发布。这不代表它不好——恰恰相反，这种"生态底座"通常就是靠社区 SIG 一点点啃出来的——但你心里的预期要摆正：

• 长期维护性取决于社区活跃度，不像官方 API 那样有明确承诺
• 遇到问题，答案在社区（Issue/Discussion），不在官方文档里

第二，API 19+ 才能用统一渲染。

如果目标设备里有大量低版本鸿蒙，那这项最大的性能红利你吃不到，得评估一下自己的设备分布。

第三，但它解决的是个真问题。

跨平台上鸿蒙，过去的选项基本是两个：

• 要么鸿蒙端单独写 ArkUI，维护两套 UI
• 要么放弃鸿蒙，等官方支持

现在多了第三条：共享逻辑照写，Compose UI 复用，ArkTS 存量用 akinterop 桥接。

对一个已经投了 KMP 的团队来说，这个第三条路的性价比，是很难忽视的。

放回这几天的脉络里看

有意思的是，这事跟咱们前两天聊的两个话题，正好串成了一条线。

Jake Wharton 那篇里，他说得很清楚：

会 Kotlin 已经不是职业优势了……但掌握 Kotlin Multiplatform 这类相对进阶的能力，仍然可能构成差异化优势。

Shopify 那篇的结论是：AI 把"重复实现"变便宜之后，“共享 UI 派"受冲击最大，而"共享逻辑 + 原生 UI"这条路更抗打。

然后是今天：KMP 的版图，又扩了一块——而且是块很大的版图。

三件事指向同一个方向：跨平台的价值，正在从"省人力"转向"架构治理 + 生态覆盖”。

一个平台一个平台地啃下来，本来就是 KMP 这条路线的核心叙事。鸿蒙这块拼图补上，对国内开发者尤其是——它可能是很多人第一次真正有理由认真看 KMP。

最后留个问题给大家：

如果鸿蒙能用 Compose 写 UI，你会为它单独维护一套 ArkUI，还是直接把 KMP 项目扩到鸿蒙？

还有——你手上的项目，鸿蒙是"必须做"还是"再看看"？

评论区聊聊，我挺想知道大家的真实处境。

参考资料：

• KMP&CMP 鸿蒙首版本正式发布（快科技/驱动之家，2026-09-15）
• 文档集合：AtomGit 搜索 CPF-KMP-CMP/docs