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

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 中的定位ECCEverything Claude Code是一套面向 AI 编码助手的工程化插件仓库AGENTS.md 将其描述为提供 68 个专用 Agent、286 个 Skill、94 个 Command 与自动化 Hook 工作流的生产级插件。在这套体系中kotlin-build-resolver是语言专属的构建错误修复 Agent 之一AGENTS.md 的 Agent 清单中明确标注Agent用途使用时机kotlin-reviewerKotlin 代码审查Kotlin/Android/KMP 项目kotlin-build-resolverKotlin/Gradle 构建错误Kotlin 构建失败仓库中该 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 列为诊断 Kotlin 编译错误Diagnose Kotlin compilation errors修复 Gradle 构建配置问题Fix Gradle build configuration issues解决依赖冲突与版本不匹配Resolve dependency conflicts and version mismatches处理 Kotlin 编译器的错误与警告Handle Kotlin compiler errors and warnings修复 detekt 与 ktlint 违规Fix detekt and ktlint violations值得注意的是职责 3 与 5它不只是编译通过的工具人还覆盖构建链上的静态分析工具链。这与/kotlin-build命令声明的三级修复优先级一致——构建错误优先detekt 违规次之ktlint 格式警告最后详见后文修复优先级策略。诊断命令序列四条命令建立完整证据面文档规定 Agent 接手后必须按顺序执行以下诊断命令./gradlew build 21 ./gradlew detekt 21 || echo detekt not configured ./gradlew ktlintCheck 21 || echo ktlint not configured ./gradlew dependencies --configuration runtimeClasspath 21 | head -100逐条来看这四条命令的设计意图./gradlew build 21——主构建检查。21将 stderr 合并进 stdout保证编译错误信息Kotlin 编译器错误默认输出到 stderr能被完整捕获并解析。这是整个工作流的错误源。./gradlew detekt 21 || echo detekt not configured——静态分析检查。||兜底分支是关键设计detekt 并非所有项目都配置若任务不存在命令会失败兜底输出 detekt not configured 让 Agent 明确知道未配置而非误判为分析失败从而跳过该环节继续工作。./gradlew ktlintCheck 21 || echo ktlint not configured——代码风格检查同样的容错模式。./gradlew dependencies --configuration runtimeClasspath 21 | 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 whats 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并给出三级优先级先修构建错误——代码必须先能编译再修 detekt 违规——代码质量问题最后修 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 exhaustiveFix 1Unresolved reference缺失 import在UserService.kt顶部补上// Added import import com.example.repository.UserRepository重跑构建后剩 2 个错误。Fix 2Type mismatchString与Int不匹配将路由参数读取改为安全转换// Changed val count call.parameters[count] // To val count call.parameters[count]?.toIntOrNull() ?: returnget call.respond(HttpStatusCode.BadRequest, Invalid count)重跑构建后剩 1 个错误。Fix 3when expression must be exhaustivesealed 枚举分支不完整补上缺失分支// Added missing branch when (user.role) { Role.ADMIN - handleAdmin(user) Role.USER - handleUser(user) Role.MODERATOR - handleModerator(user) // Added }最终验证./gradlew detekt无问题、./gradlew test全部通过会话以汇总表收尾MetricCountBuild errors fixed3Detekt issues fixed0Files modified2Remaining issues0注意 Fix 2 中的修复手法——toIntOrNull()加 Elvis 运算符兜底返回 400 响应而非强转或!!。这正是 skills/kotlin-patterns/SKILL.md 中Null safety原则的实践利用?:提供默认值禁止!!强制解包。常见错误修复模式速查表文档的Common Fix Patterns给出了十类高频 Kotlin 编译/构建错误及其成因与修复方式这是该 Agent 的错误知识库完整继承如下ErrorCauseFixUnresolved reference: XMissing import, typo, missing dependencyAdd import or dependencyType mismatch: Required X, Found YWrong type, missing conversionAdd conversion or fix typeNone of the following candidates is applicableWrong overload, wrong argument typesFix argument types or add explicit castSmart cast impossibleMutable property or concurrent accessUse localvalcopy orletwhen expression must be exhaustiveMissing branch in sealed classwhenAdd missing branches orelseSuspend function can only be called from coroutineMissingsuspendor coroutine scopeAddsuspendmodifier or launch coroutineCannot access X: it is internal in YVisibility issueChange visibility or use public APIConflicting declarationsDuplicate definitionsRemove duplicate or renameCould not resolve: group:artifact:versionMissing repository or wrong versionAdd repository or fix versionExecution failed for task :detektCode style violationsFix detekt findings其中几条与 Kotlin 语言特性直接相关结合仓库中的 kotlin-patterns Skill 可以看得更深when expression must be exhaustiveKotlin 对 sealed 类层次结构要求when穷尽所有分支。Skill 文档给出的标准做法是用sealed class建模有限状态层次如Resultout 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 文档中给出了coroutineScopeasync/await的结构化并发正例可作为修复后代码形态的参考Smart cast impossibleKotlin 智能转换要求被转换的属性不可变且不被并发修改标准修复是局部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 21 | tail -50 # Check for dependency conflicts ./gradlew dependencyInsight --dependency name --configuration runtimeClasspath各命令的适用情境命令用途与情境dependencies --configuration runtimeClasspath打印运行时依赖树排查传递依赖引入的版本冲突build --refresh-dependencies本地缓存的构件/元数据可疑时强制重新解析依赖clean rm -rf .gradle/build-cache/清理项目级 Gradle 构建缓存排除缓存污染--version核对 Gradle 与 Kotlin 插件、JDK 的版本兼容矩阵build --debug 21 \| tail -50开启调试输出并只看尾部 50 行定位卡死或失败的构建任务dependencyInsight --dependency name针对单个依赖做冲突溯源输出谁把哪个版本传递进来的完整决策链其中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(-Xjsr305strict) // Strict Java null safety allWarningsAsErrors true } }-Xjsr305strict让 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 而不是加SuppressPrefer adding missing imports over wildcard imports—— 优先补精确 import禁止用import xxx.*通配符掩盖问题。为防止 Agent 陷入无效循环文档定义了明确的 Stop Conditions——出现任一情况即停止并向用户报告同一错误连续 3 次修复尝试后依然存在修复引入的错误比解决的还多错误需要超出本次修复范围scope的架构级改动缺失需要用户决策的外部依赖。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-patternsSkillskills/kotlin-patterns/SKILL.mdAgent 文档结尾指引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.mdKiro 环境下的常驻规则fileMatchPattern: *.kt意味着编辑任何 Kotlin 文件时自动加载。它的Reference一节反向指回了两个 AgentSee agents:kotlin-reviewer,kotlin-build-resolverfor Kotlin-specific review and build error resolution/kotlin-test与/kotlin-review命令kotlin-build.md 的Related Commands将它们列为下游衔接——构建修好后用/kotlin-testKotest Kover 覆盖率见 commands/kotlin-test.md跑测试用/kotlin-review做代码质量审查Kiro 安装路径.kiro/install.sh 可将整套 agents/skills/hooks 非破坏性地复制到任意 Kiro 项目安装后通过/kotlin-build-resolverIDE或kiro-cli --agent kotlin-build-resolverCLI直接唤起具体见 .kiro/README.md 的 Usage 章节。从这一组组件的调用关系可以推断/kotlin-build命令负责何时修、按什么顺序修kotlin-build-resolverAgent 负责怎么修、何时停kotlin-patternsSkill 与 steering 文件负责修出来的代码是否符合项目 Kotlin 惯例三层职责分离正是 ECCAgent-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考