使用 AI 编写 Kronos 代码

本章介绍如何在 AI 编程助手中安装和使用 Kronos ORM 技能。

什么是 kronos-orm-guide

kronos-orm-guide 是从 Kronos 仓库 main 分支发布的 AI 技能。它帮助 AI 编程助手理解 Kronos ORM API，并为你的项目生成正确的 ORM 代码。

该技能会教会 AI 助手：

• 使用合适的注解定义 📚KPojo 数据类
• 编写 CRUD 操作：select、insert、update、delete、upsert
• 使用条件 DSL：where、having、on
• 编写联表查询、联合查询和子查询
• 使用 📚事务、级联操作和 DDL 表操作
• 使用聚合、字符串、日期、数学等内置函数
• 配置命名策略、逻辑删除和乐观锁

一键安装

从 main 分支把 skill 安装到 AI 工具约定的技能目录：

如果目标目录已存在，在 degit 后添加 --force。

Claude Code 从 .claude/skills/ 读取项目 skill。Codex 从 .agents/skills/ 读取项目 skill。Windsurf 和其他可读取 .agents/skills/ 的工具使用默认命令。

准备项目上下文

让 AI 助手先读取 skill 和决定 Kronos 配置的项目文件，再开始生成代码。

<skill-dir>/kronos-orm-guide/SKILL.md
<skill-dir>/kronos-orm-guide/references/advanced.md
<skill-dir>/kronos-orm-guide/references/annotations.md
build.gradle.kts 或 pom.xml
src/main/kotlin/... 现有 KPojo 类

Claude 使用 .claude/skills 作为 <skill-dir>，Codex 和通用 agent 使用 .agents/skills，Cursor 使用 .cursor/skills。

需要结合 docs 生成代码时，优先给相关页面链接，不要粘贴大段示例。常见任务对应这些页面：

要求生成当前 API

提示词中写清构建工具、数据库和期望的 Kronos API，可以让回答落在当前编译器插件和 DSL 写法上。

使用 Kronos ORM skill。为这个 JVM Kotlin Gradle 项目添加 Kronos。
使用 Kotlin 2.4.21、com.kotlinorm.kronos-gradle-plugin、kronos-core
和 kronos-jdbc-wrapper。使用 KronosJdbcWrapper 配置 Kronos.dataSource。
全局设置使用 Kronos object 的直接属性赋值。

期望的依赖形态如下：

plugins {
    kotlin("jvm") version "2.4.21"
    id("com.kotlinorm.kronos-gradle-plugin") version "0.4.0"
}

kotlin {
    compilerOptions {
        freeCompilerArgs.addAll("-Xcollection-literals", "-Xcontext-sensitive-resolution")
    }
}

dependencies {
    implementation("com.kotlinorm:kronos-core:0.4.0")
    implementation("com.kotlinorm:kronos-jdbc-wrapper:0.4.0")
}

生成 ORM 代码时，一次只让 AI 处理一个实体和一个可运行查询。

使用 Kronos ORM，为 tb_user 表创建 User KPojo，包含 id、name、email、
deleted 和 version 字段。然后写一个查询，选择 id 和 name，
按 email 域名筛选用户，并用 build() 打印生成 SQL 和 paramMap。

回答应使用当前 DSL 形态。

@Table("tb_user")
data class User(
    @PrimaryKey(identity = true)
    var id: Int? = null,
    var name: String? = null,
    var email: String? = null,
    @LogicDelete
    @Default("0") // @Default("false") for Postgres
    var deleted: Boolean? = false,
    @Version
    var version: Int? = null
) : KPojo

val task = User()
    .select { [it.id, it.name] }
    .where { it.email like "%@example.com" }
    .build()

println(task.sql)
println(task.paramMap)

技能内容

示例提示词

技能激活后，可以向 AI 助手提出 Kronos 相关任务：

• "创建一个包含 id、name、email 和时间戳的 User 实体"
• "写一个 User 和 Order 联表查询，带分页"
• "添加一个事务，插入用户及其订单"
• "如何为这个实体配置逻辑删除？"
• "写一个按 email 冲突时更新的 upsert"

AI 会根据技能中的 API 知识生成符合 Kronos DSL 习惯的代码，而不是泛泛的 ORM 写法。

验证回答

AI 修改代码后，先让它运行窄范围构建检查，并在执行数据库写入前查看 SQL。

./gradlew compileKotlin

[Kronos] Kronos compiler plugin K2 initialized
BUILD SUCCESSFUL

查询和变更操作先要求给出 build() 示例，让 SQL 和参数可见。

val task = User(id = 7)
    .delete()
    .where()
    .build()

println(task.sql)
println(task.paramMap)

参与 Kronos 仓库本身开发时，使用 📚使用 AI 参与开发，不要使用面向业务项目的 ORM skill。