企业官网建设流程全解析

ECC kotlin-build-resolver 深度解析：Kotlin/Gradle 构建错误的最小化修复工作流

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本篇技术指南围绕 ECC 仓库中的kotlin-build-resolverAgent 定义文档展开，系统讲解该构建错误修复专家的诊断命令序列、五步解决工作流、十类常见 Kotlin/Gradle 错误的成因与修复模式，以及配套的 Gradle 排障技巧。读完本文，你可以理解该 Agent 如何在 Kiro 与 Claude Code 等编码助手环境中被调用，并掌握一套"外科手术式"最小改动修复 Kotlin 构建失败、依赖冲突与静态分析违规的可复用方法论。

kotlin-build-resolver 在 ECC 中的定位

ECC（Everything Claude Code）是一套面向 AI 编码助手的工程化插件仓库，AGENTS.md 将其描述为"提供 68 个专用 Agent、286 个 Skill、94 个 Command 与自动化 Hook 工作流的生产级插件"。在这套体系中，kotlin-build-resolver是语言专属的构建错误修复 Agent 之一，AGENTS.md 的 Agent 清单中明确标注：

仓库中该 Agent 实际存在两个定义文件，内容同源但面向不同宿主：

• .kiro/agents/kotlin-build-resolver.md：面向 Kiro 的 Markdown 定义，frontmatter 中声明allowedTools: read, shell，即只授予读取与 Shell 两类工具——这与"诊断构建、执行 Gradle 命令"的职责边界完全吻合；
• agents/kotlin-build-resolver.md：面向 Claude Code 风格的定义，frontmatter 中声明tools: Read, Write, Edit, Bash, Grep, Glob与model: sonnet，额外附带"Prompt Defense Baseline"（提示注入防御基线）一节，并在正文中多出一节 Kotlin 编译器 Flag 配置（本文后文会完整展开）。

两个文件共同声明的核心使命是一致的：修复 Kotlin 构建错误、Gradle 配置问题与依赖解析失败，且所有修复都必须最小化、外科手术式（minimal, surgical changes）。.kiro/README.md 的 Agent 清单对它的描述也印证了这一点：

kotlin-build-resolver— Kotlin/Gradle build error resolution specialist. Fixes Gradle, KSP, and dependency errors.

它不是一个通用助手，而是被 commands/kotlin-build.md 中定义的/kotlin-build命令显式调用的专项 Agent。该命令的 frontmatter 写道："Fix Kotlin/Gradle build errors, compiler warnings, and dependency issues incrementally. Invokes the kotlin-build-resolver agent for minimal, surgical fixes." docs/COMMAND-REGISTRY.json 也注册了这条命令与kotlin-build-resolverAgent、kotlin-patternsSkill 的绑定关系。

适用场景

根据 commands/kotlin-build.md 的"When to Use"章节，当出现以下情况时应触发该 Agent：

• ./gradlew build失败并报出错误；
• Kotlin 编译器报告编译错误；
• ./gradlew detekt报告静态分析违规；
• Gradle 依赖解析失败；
• 拉取（pull）远程变更后构建被破坏。

Agent 的五项核心职责

文档将其 Core Responsibilities 列为：

1. 诊断 Kotlin 编译错误（Diagnose Kotlin compilation errors）
2. 修复 Gradle 构建配置问题（Fix Gradle build configuration issues）
3. 解决依赖冲突与版本不匹配（Resolve dependency conflicts and version mismatches）
4. 处理 Kotlin 编译器的错误与警告（Handle Kotlin compiler errors and warnings）
5. 修复 detekt 与 ktlint 违规（Fix detekt and ktlint violations）

值得注意的是职责 3 与 5：它不只是"编译通过"的工具人，还覆盖构建链上的静态分析工具链。这与/kotlin-build命令声明的三级修复优先级一致——构建错误优先，detekt 违规次之，ktlint 格式警告最后（详见后文"修复优先级策略"）。

诊断命令序列：四条命令建立完整证据面

文档规定 Agent 接手后必须按顺序执行以下诊断命令：

./gradlew build 2>&1 ./gradlew detekt 2>&1 || echo "detekt not configured" ./gradlew ktlintCheck 2>&1 || echo "ktlint not configured" ./gradlew dependencies --configuration runtimeClasspath 2>&1 | head -100

逐条来看这四条命令的设计意图：

1. ./gradlew build 2>&1——主构建检查。2>&1将 stderr 合并进 stdout，保证编译错误信息（Kotlin 编译器错误默认输出到 stderr）能被完整捕获并解析。这是整个工作流的错误源。
2. ./gradlew detekt 2>&1 || echo "detekt not configured"——静态分析检查。||兜底分支是关键设计：detekt 并非所有项目都配置，若任务不存在命令会失败，兜底输出 "detekt not configured" 让 Agent 明确知道"未配置"而非误判为"分析失败"，从而跳过该环节继续工作。
3. ./gradlew ktlintCheck 2>&1 || echo "ktlint not configured"——代码风格检查，同样的容错模式。
4. ./gradlew dependencies --configuration runtimeClasspath 2>&1 | head -100——输出运行时依赖树的前 100 行。依赖树是排查版本冲突（version conflict）与传递依赖问题的第一手证据，head -100截断则是为了避免超长输出撑爆 Agent 上下文。

kotlin-build.md 命令文档在此基础上补充了第五条"可选深检"命令：

# Optional deep refresh when caches or dependency metadata are suspect ./gradlew build --refresh-dependencies

即当怀疑是本地缓存或依赖元数据损坏导致解析失败时，用--refresh-dependencies强制重新拉取。

五步解决工作流

文档的 Resolution Workflow 是整个 Agent 的行为骨架：

1. ./gradlew build -> Parse error message 2. Read affected file -> Understand context 3. Apply minimal fix -> Only what's needed 4. ./gradlew build -> Verify fix 5. ./gradlew test -> Ensure nothing broke

这五步构成一个"构建—定位—最小修复—验证—回归"的闭环，其中有两个值得强调的设计：

• 第 2 步先读文件再动手：要求 Agent 在应用任何修复前读取受影响的源文件、理解上下文，而不是凭错误信息盲目猜测。这直接对应前文职责边界中只授予read与shell工具的克制姿态；
• 第 4、5 步的双重验证：每次修复后必须重跑./gradlew build验证该错误已消除，全部修完后再跑./gradlew test确认没有回归。commands/kotlin-build.md 的"Fix Strategy"进一步明确了执行顺序：一次只修一个错误，每改必验（One fix at a time, verify each change），并给出三级优先级：

1. 先修构建错误——代码必须先能编译；
2. 再修 detekt 违规——代码质量问题；
3. 最后修 ktlint 警告——格式问题。

一次典型修复会话

kotlin-build.md 内置了一个完整的 Example Session，展示了该工作流的实际运行形态。初始诊断：

$ ./gradlew build e: src/main/kotlin/com/example/service/UserService.kt:25:15 Unresolved reference: UserRepository e: src/main/kotlin/com/example/routes/UserRoutes.kt:42:9 Type mismatch: inferred type is String but Int was expected e: src/main/kotlin/com/example/routes/UserRoutes.kt:58:5 'when' expression must be exhaustive

Fix 1：Unresolved reference（缺失 import），在UserService.kt顶部补上：

// Added import import com.example.repository.UserRepository

重跑构建后剩 2 个错误。

Fix 2：Type mismatch（String与Int不匹配），将路由参数读取改为安全转换：

// Changed val count = call.parameters["count"] // To val count = call.parameters["count"]?.toIntOrNull() ?: return@get call.respond(HttpStatusCode.BadRequest, "Invalid count")

重跑构建后剩 1 个错误。

Fix 3：'when' expression must be exhaustive（sealed 枚举分支不完整），补上缺失分支：

// Added missing branch when (user.role) { Role.ADMIN -> handleAdmin(user) Role.USER -> handleUser(user) Role.MODERATOR -> handleModerator(user) // Added }

最终验证./gradlew detekt无问题、./gradlew test全部通过，会话以汇总表收尾：

注意 Fix 2 中的修复手法——toIntOrNull()加 Elvis 运算符兜底返回 400 响应，而非强转或!!。这正是 skills/kotlin-patterns/SKILL.md 中"Null safety"原则的实践：利用?:提供默认值，禁止!!强制解包。

常见错误修复模式速查表

文档的"Common Fix Patterns"给出了十类高频 Kotlin 编译/构建错误及其成因与修复方式，这是该 Agent 的"错误知识库"，完整继承如下：

其中几条与 Kotlin 语言特性直接相关，结合仓库中的 kotlin-patterns Skill 可以看得更深：

• 'when' expression must be exhaustive：Kotlin 对 sealed 类层次结构要求when穷尽所有分支。Skill 文档给出的标准做法是用sealed class建模有限状态层次（如Result<out T>的Success/Failure/Loading），并配合穷尽when；修复方向是补齐缺失分支。而 .kiro/steering/kotlin-patterns.md 的 steering 规则更进一步："Always use exhaustivewhenwith sealed types — noelsebranch"，即在项目规则层面，修复首选补分支而非加else兜底；
• Suspend function can only be called from coroutine：涉及协程调用链，修复方向是给调用函数加suspend修饰符或放入协程作用域（launch）。Skill 文档中给出了coroutineScope+async/await的结构化并发正例，可作为修复后代码形态的参考；
• Smart cast impossible：Kotlin 智能转换要求被转换的属性不可变且不被并发修改，标准修复是"局部val拷贝"或let作用域函数——这与 Skill 中"Scope Functions"一节let: Transform nullable or scoped result的用法一致；
• Could not resolve: group:artifact:version：属于 Gradle 依赖解析失败，修复手段是补仓库声明或纠正版本号，后文"Gradle 排障工具箱"中的dependencyInsight命令正是定位此类冲突的工具。

Gradle 排障工具箱

文档给出了六条 Gradle 层排障命令，覆盖冲突定位、缓存清理与调试：

# Check dependency tree for conflicts ./gradlew dependencies --configuration runtimeClasspath # Force refresh dependencies ./gradlew build --refresh-dependencies # Clear project-local Gradle build cache ./gradlew clean && rm -rf .gradle/build-cache/ # Check Gradle version compatibility ./gradlew --version # Run with debug output ./gradlew build --debug 2>&1 | tail -50 # Check for dependency conflicts ./gradlew dependencyInsight --dependency <name> --configuration runtimeClasspath

各命令的适用情境：

其中dependencyInsight是处理"同一库两个版本共存"类问题的核心命令：它不只告诉你冲突存在，而是展示 Gradle 的仲裁过程（选中的版本、被弃用的版本、各自的请求方路径），是决定"对齐到哪个版本"的直接依据。

Kotlin 编译器 Flag：从根上收紧构建门禁

agents/kotlin-build-resolver.md 相比 Kiro 版本额外提供了一节"Kotlin Compiler Flags"，给出build.gradle.kts中常见的编译期选项配置：

// build.gradle.kts - Common compiler options kotlin { compilerOptions { freeCompilerArgs.add("-Xjsr305=strict") // Strict Java null safety allWarningsAsErrors = true } }

• -Xjsr305=strict：让 Kotlin 编译器严格识别 Java 库中的 JSR-305 空注解（@Nullable/@NonNull），在与 Java 混合的项目里能更早暴露平台类型（platform type）的空安全陷阱；
• allWarningsAsErrors = true：把警告升级为错误。这条 flag 与 Agent"修复警告而非抑制警告"的职责直接呼应——文档的 Key Principles 明确写着Never suppress warnings without explicit approval（未经明确批准绝不抑制警告）。

关键原则与停止条件

文档的 Key Principles 是约束 Agent 行为边界的六条铁律：

• Surgical fixes only—— 只做手术式修复，不顺手重构，只改错误本身；
• Never suppress warnings without explicit approval—— 未经明确批准不得抑制警告；
• Never change function signatures unless necessary—— 非必要不改变函数签名（防止修复扩散破坏调用方）；
• Always run./gradlew buildafter each fix to verify—— 每次修复后必须重跑构建验证；
• Fix root cause over suppressing symptoms—— 治本优先于压制表象（例如补 import 而不是加@Suppress）；
• Prefer adding missing imports over wildcard imports—— 优先补精确 import，禁止用import xxx.*通配符掩盖问题。

为防止 Agent 陷入无效循环，文档定义了明确的 Stop Conditions——出现任一情况即停止并向用户报告：

1. 同一错误连续 3 次修复尝试后依然存在；
2. 修复引入的错误比解决的还多；
3. 错误需要超出本次修复范围（scope）的架构级改动；
4. 缺失需要用户决策的外部依赖。

kotlin-build.md 中的停止条件表述与之一致（same error after 3 attempts / more errors introduced / architectural changes / missing external dependencies），说明命令层与 Agent 层共享同一套熔断语义。

结构化输出格式

Agent 的每个修复动作必须以固定格式输出，保证结果可审计：

[FIXED] src/main/kotlin/com/example/service/UserService.kt:42 Error: Unresolved reference: UserRepository Fix: Added import com.example.repository.UserRepository Remaining errors: 2

全部完成后以一行总结收尾：

Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list

[FIXED]条目包含文件路径与行号、原始错误、所做修复、剩余错误数四个字段；最终摘要给出构建状态、修复计数与改动文件清单。这种机器可解析的汇报格式便于 CI 或上层编排器（如 ECC 的loop-operator、verification-loop工作流）接力处理。

生态衔接：命令、Skill 与 Steering 规则

kotlin-build-resolver并非孤立存在，它与仓库中的若干组件构成完整的 Kotlin 工程闭环：

• /kotlin-build命令（commands/kotlin-build.md）：用户侧入口。文档"Related"一节明确声明Agent: agents/kotlin-build-resolver.md、Skill: skills/kotlin-patterns/，即命令调用该 Agent 并加载 kotlin-patterns 技能上下文；
• kotlin-patternsSkill（skills/kotlin-patterns/SKILL.md）：Agent 文档结尾指引"For detailed Kotlin patterns and code examples, seeskill: kotlin-patterns"。该 Skill 覆盖空安全、不可变性、sealed 类、协程、Gradle Kotlin DSL 等七大领域，其中"Gradle Kotlin DSL"一节给出了带 detekt、Kover、Kotest、Koin 插件的完整build.gradle.kts示例，可作为理解"哪些依赖/插件配置容易引发构建问题"的参考；
• kotlin-patternsSteering 文件（.kiro/steering/kotlin-patterns.md）：Kiro 环境下的常驻规则，fileMatchPattern: "*.kt"意味着编辑任何 Kotlin 文件时自动加载。它的"Reference"一节反向指回了两个 Agent："See agents:kotlin-reviewer,kotlin-build-resolverfor Kotlin-specific review and build error resolution"；
• /kotlin-test与/kotlin-review命令：kotlin-build.md 的"Related Commands"将它们列为下游衔接——构建修好后用/kotlin-test（Kotest + Kover 覆盖率，见 commands/kotlin-test.md）跑测试，用/kotlin-review做代码质量审查；
• Kiro 安装路径：.kiro/install.sh 可将整套 agents/skills/hooks 非破坏性地复制到任意 Kiro 项目，安装后通过/kotlin-build-resolver（IDE）或kiro-cli --agent kotlin-build-resolver（CLI）直接唤起，具体见 .kiro/README.md 的 Usage 章节。

从这一组组件的调用关系可以推断：/kotlin-build命令负责"何时修、按什么顺序修"，kotlin-build-resolverAgent 负责"怎么修、何时停"，kotlin-patternsSkill 与 steering 文件负责"修出来的代码是否符合项目 Kotlin 惯例"，三层职责分离正是 ECC"Agent-First"原则（见 AGENTS.md Core Principles 第 1 条）的落地形态。

小结

kotlin-build-resolver的价值在于把"修 Kotlin 构建"这一高频工程活动收敛成一套确定性流程：四条诊断命令建立证据面（构建、detekt、ktlint、依赖树），五步闭环保证"一修一验"，十类错误速查表覆盖从 import 缺失到协程调用违规的主要编译错误，六条 Gradle 排障命令处理依赖冲突与缓存问题，配合"外科手术式最小改动"的六条原则与四条熔断停止条件，使修复过程既收敛又可审计。对维护 Kotlin 项目的团队而言，这份 Agent 定义本身就是一份可直接落地的 Gradle 故障排查手册——即使不使用 AI 助手，其中"先诊断后修复、修复必验证、熔断不硬试"的工作流也值得直接借鉴到日常 CI 排障中。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC