Kotlin Toolchain 0.11 发布：主要是把 Amper 干没了

我最近在学 Agent 相关的知识，同时在更新系列文章 ------ 用 Kotlin 构建你的第一个 Agent。

这个系列打算不使用 Gradle，使用最近的构建工具 Amper 去做。然后上周 Amper 发布了 0.11 版本，结果最大变化是 Amper 没了！

没了，但不是完全没，准确的说是整合进了 Kotlin Toolchain。

随着 Kotlin Toolchain 0.11.0 的发布，Amper 已正式升级为 Kotlin Toolchain，进入 Alpha 阶段。

这个版本除了产品变更，还带来了 JVM 库的发布能力、新的插件开发 API，以及一些开发者体验改进。

要使用 Kotlin Toolchain 的最新功能，需要 IntelliJ IDEA 2026.1.2 或更新版本，以及最新版的 Kotlin Toolchain 插件。*

Amper 更名为 Kotlin Toolchain

Amper 最初的目标是探索一套统一、声明式的构建体验。

随着项目演进，JetBrains 意识到生态需要的不是又一个构建工具，而是一个统一的 Kotlin 入口，Kotlin Toolchain 就是这个入口。

我其实一开始并不看好 Amper 作为构建工具，虽然 Gradle 有各种不好的地方，但是最近的 9.0 之后的版本，其实还是挺好用的：

有浪子回头的迹象，构建速度一直在优化；
Gradle 的生态虽然写过插件的没有人不骂，但是现在已经太庞大了，几乎垄断了整个 Jvm 的世界。

Amper 再怎么优秀，是无法弥补这个差距的（除非...拥抱 Rust）。

现在，安装 Kotlin Toolchain 之后，只需要一个 kotlin 命令，覆盖创建项目、构建、运行、测试、打包和发布。后续还会加入代码格式化、文档生成等功能。开发者不需要在项目初期就选择构建工具，也不需要为运行第一行代码而配置复杂的插件。

当然，Kotlin 团队这么做，实际上也是为了 AI 铺路，AI 是最需要终端工具的，连 Android 都发布了 android cli。

Amper 中已有的功能全部迁移到了 Kotlin Toolchain，项目因此直接以 Alpha 阶段起步。Alpha 阶段意味着 JetBrains 已承诺长期维护，可以上手试用并反馈。

如果你已经在使用 Amper，需要注意以下两点：

将 amper 和 amper.bat 包装脚本替换为新的 kotlin 和 kotlin.bat。
在 IntelliJ IDEA 中安装 Kotlin Toolchain IDE 插件来替代 Amper IDE 插件，旧的可以卸载。

考虑到没多少人用，直接安装最近的 Kotlin Toolchain 就行了。

全局安装

项目中的包装脚本适合 clone 即构建的场景，无需额外安装，但并非所有场景都适用。

0.11 起，kotlin 命令行支持全局安装，可以在任意目录直接使用，无需 ./kotlin 前缀。通过 SDKMAN! 安装：

sh 复制代码

sdk install kotlintoolchain

注意： SDKMAN! 以外还有其他安装方式，详见文档。

全局安装带来的改进：

在项目深层子目录中执行 kotlin 命令更方便。
可以在任意目录执行项目无关的命令，如 kotlin tool jaeger 或 kotlin clean-shared-caches。
用 init 创建新项目更自然，无需手动下载或从其他项目复制包装脚本。

全局 kotlin 命令会自动定位项目中的包装脚本，运行对应版本的工具链，因此不同项目可以使用不同版本。

发布

这个版本加入了库发布功能，该功能目前处于预览阶段，支持将 JVM 库发布到 Maven 仓库，包括 Maven Central。

注意： Kotlin Multiplatform 库的发布尚未支持，正在开发中。

普通 Maven 仓库

发布到 Maven Central 以外的仓库，在 module.yaml 中配置：

yaml 复制代码

product: jvm/lib

repositories:
  - id: myMavenRepoId
    url: https://maven.pkg.github.com/my-org/my-maven-repo 
    publish: true
    credentials:
      file: creds.properties # 存放凭证的 properties 文件
      usernameKey: maven.username # 用户名的属性名
      passwordKey: maven.password # 密码的属性名

settings:
 publishing:
   enabled: true
   group: com.example
   artifactId: greeter # 可选，默认使用模块名
   version: 1.0.0

凭证文件示例（creds.properties）：

prop 复制代码

maven.username=john.doe
maven.password=MyVerySecurePassword123

通过仓库 ID 执行发布：

sh 复制代码

kotlin publish myMavenRepoId

所有开启发布功能且声明了对应仓库的模块都会被发布。

Maven Central

发布到 Maven Central 通常涉及多个环节：sources JAR、javadoc JAR、PGP 签名、POM 元数据、校验和等。Kotlin Toolchain 现在自动处理这些步骤，开发者只需声明要发布的内容。

前置条件：在 Maven Central Publisher Portal 上准备好账号、命名空间、用户令牌，以及 PGP 签名密钥。

发布到 Maven Central 不需要手动声明仓库，在发布配置中设置 mavenCentral: enabled 并填写必要信息即可。最简配置：

yaml 复制代码

product: jvm/lib

description: 对该模块的有意义描述

settings:
  publishing:
    enabled: true
    group: com.example # group 必须与 Maven Central 命名空间一致
    version: 1.0.0
    # artifactId 可选，默认使用模块名
    mavenCentral: enabled
    signArtifacts: true # 自动签名，无需外部 GPG 工具
    publishSources: true
    pom:
      url: https://example.com
      scm: https://github.com/my-org/example.git # SCM 连接和开发者连接自动推导
      developers:
        - name: John Doe
      licenses:
        - name: MIT
          url: https://opensource.org/license/mit

配置完成后，一条命令即可发布：

sh 复制代码

kotlin publish mavenCentral

该命令会构建并签名所有产物，打包为 Maven Central 部署包，上传后等待验证。之后通过 Central portal UI 检查部署状态并完成发布。

也可以通过 publishingMode: auto 启用全自动发布，跳过手动验证。

Cinterop 支持

Kotlin Toolchain 现在根据模块 cinterop 文件夹中的定义文件生成 C 库的自定义绑定。

IDE 在项目同步时也会辅助生成绑定。

终端 UI 改进

kotlin 命令的输出有以下改进：

已完成的任务有了更好的进度指示器，主进度条集成了终端原生进度显示：

Kotlin JVM 编译器的诊断信息渲染也有所改进（需要 Kotlin 2.4.0+）：

IDE 改进

库源码下载

库的源码现在会在同步完成后自动下载。

同步先完成，开发者可以直接开始工作，源码在后台下载。

模块级依赖解析

此前，IDE 插件的依赖解析在项目级别进行，与 CLI 行为不一致，可能导致模块中的依赖版本不正确或编辑器出现错误警告。现已与 CLI 对齐，每个模块独立解析，诊断结果保持一致。

插件开发改进

为本地插件作者新增了 checks 和 commands 声明、新的任务输入 API，以及诊断相关改进。

新的引用

在 plugin.yaml 中连接任务输入时，可以使用内置引用访问项目信息。本次新增两个引用：

${project.rootDir} ------ 项目根目录。
${module.classes} ------ 编译后的原始 class 文件目录。

自定义检查

kotlin check 命令用于确保项目通过所有质量检查，默认运行常规单元测试，插件可以注册额外的检查。

在插件中通过 checks 顶层列表添加自定义检查：

yaml 复制代码

# my-lint-plugin/plugin.yaml
tasks:
  runLinter:
    action: !kotlinJavaLint
      sources: ${module.kotlinJavaSources}

checks:
  - name: lint
    performedBy: runLinter

lint 检查也可以通过 kotlin check lint 单独运行。列出项目中的检查使用 kotlin show checks。详见插件文档。

自定义命令

插件有时需要暴露公开入口，例如生成 changelog、按需打印信息或发布自定义格式的包。由于插件的任务默认视为私有，本次引入了自定义命令来作为公开入口。

自定义命令基于普通任务实现，可以获取构建数据（源文件、编译后的 JAR、运行时 classpath 等）并依赖其他任务。在 plugin.yaml 中使用 commands 顶层节点注册：

yaml 复制代码

# my-lint-plugin/plugin.yaml
tasks:
  updateBaseline:
    action: !runDetektForBaseline
      sources: ${module.kotlinJavaSources}
      outputFile: ${module.rootDir}/detekt/baseline.xml

commands:
  # 命令名与任务名一致时的简写
  - updateBaseline

通过 kotlin do command 执行：

sh 复制代码

kotlin do updateBaseline

该命令会运行关联的任务及其依赖项。列出所有自定义命令使用 kotlin show commands。

注册生成文件的新方式

plugin.yaml 新增了 generated 顶层节点，用于注册生成的源码、资源和类文件。从 0.11.0 起，任务动态提供原生库时也可以注册 cinterop 定义：

yaml 复制代码

tasks:
  generateStuff:
    action: !myGenerateStuffAction
      outputSources: ${taskOutputDir}/src
      outputResources: ${taskOutputDir}/res
      outputDefFiles: ${taskOutputDir}/cinterop

generated:
  sources:
    - directory: ${tasks.generateStuff.action.outputSources}
      language: kotlin
  resources:
    - directory: ${tasks.generateStuff.action.outputResources}
  cinteropDefinitions:
    - directory: ${tasks.generateStuff.action.outputDefFiles}

这替代了任务中已弃用的 markOutputAs 属性（后续版本将移除）。所有回馈构建的输出以统一方式注册，在各自节点下清晰可辨，便于人类、AI agent 和其他工具识别。

其他改进

lib 更名为 kmp/lib

lib 产品类型更名为 kmp/lib，以更准确地反映其含义（与 jvm/lib 区分）。旧的 lib 值已弃用，后续版本将移除。

模板嵌套

模板现在可以应用其他模板，构建层级化的设置结构。语法不变，在模板文件中使用 apply 节点：

yaml 复制代码

# spring.module-template.yaml
apply:
  - ./jvm.module-template.yaml

settings:
  springBoot: enabled

Maven classifier 支持

Maven 依赖声明现在支持 classifier，可以指定依赖库的特定产物：

yaml 复制代码

dependencies:
      - io.netty:netty-transport-native-epoll:4.2.13.Final:linux-x86_64

run 命令改进

run 命令在只有一个选项适用于当前主机时，不再需要显式指定模块或平台。

项目有多个模块但只有一个能在当前主机上运行时，无需指定模块。例如以下项目结构：

vbnet 复制代码

.
├── linux-cli/
├── macos-cli/
├── windows-cli/
├── shared/
├── kotlin
├── kotlin.bat
└── project.yaml

在 Windows 上执行 kotlin run 会自动启动 windows-cli 模块。

模块有多个目标平台但只有一个能在当前主机上运行时，也无需指定平台。例如：

yaml 复制代码

# linux-app/module.yaml
product: linux/app

# linuxArm64 和 linuxX64 平台默认均存在

在 ARM 机器上 kotlin run -m linux-app 会启动 ARM64 版本，在 x86 机器上则启动 x86-64 版本。

默认版本更新

工具链和框架的默认版本已更新：

Kotlin 2.3.21
Compose Hot Reload 1.1.1
KSP 2.3.7
Ktor 3.4.3
SpringBoot 4.0.6
Lombok 1.18.46
JUnit Platform 6.0.3

注意

Amper 用户无法通过常规自动更新路径迁移到 Kotlin Toolchain。需要手动将项目中的 amper 和 amper.bat 替换为 Kotlin 包装脚本。先全局安装 toolchain，再通过 Kotlin CLI 生成新的包装脚本：

sh 复制代码

kotlin update --create

替换后，后续更新使用 kotlin update 即可。

一点想法

Amper 才出来没多久就改名 Kotlin Toolchain，节奏是真快。

不过放到现在也不意外，计划永远没有变化快，AI 时代谁都得跟着 AI 的节奏来。

比起再造一个构建工具，往 CLI 工具方向走其实是个更实际的想法。AI agent 调 CLI 比折腾一堆 GUI 和插件顺手太多，开发者日常用起来门槛也低，应该会比 Amper 单做构建工具更受欢迎。

原文：Kotlin Toolchain 0.11: The Next Step for Amper