ECC for Kiro 的 java-build-resolver：Java/Maven/Gradle 构建错误解决 Agent 设计与实操指南

本文以 ECC（Everything Claude Code）仓库中 Kiro 适配层的 java-build-resolver Agent 文档为主体，完整拆解该 Java 构建错误解决 Agent 的工作方法：框架自动检测、诊断命令集、分框架（Spring Boot / Quarkus）的修复模式、Maven/Gradle 疑难排查命令、停止条件与标准化输出格式。读完后，你将掌握一套可复制到任意 Java 项目的"最小手术式"构建排障流程，并理解该 Agent 在 ECC Kiro 生态中的定义格式与安装使用方式。

一、角色定位：只修构建错误，不做重构

java-build-resolver 是 ECC Kiro 适配层（.kiro/agents/）中面向 Java 生态的构建错误解决专家，其文档 java-build-resolver.md 开头即定义了核心使命与边界：

• 使命：以"最小、手术式（minimal, surgical changes）"的改动，修复 Java 编译错误、Maven/Gradle 配置问题与依赖解析失败；
• 边界：不做重构、不重写代码——只修构建错误本身。

这种"职责单点化"设计是 ECC Agent 体系的关键特征：与同目录下的代码审查 Agent（如 java-reviewer.md 中声明的 "You DO NOT refactor or rewrite code — you report findings only"）形成互补——审查 Agent 只报告问题，解决 Agent 只修复问题，两者都不越界。该 Agent 的 frontmatter 同时声明了最小权限集 allowedTools: fs_read + shell，即只允许读文件与执行 shell 命令，这正是"诊断 + 修复 + 验证"三类动作所需的全部能力。

二、第一步：框架检测（Spring Boot 还是 Quarkus）

文档要求在任何修复动作之前先执行框架检测：

cat pom.xml 2>/dev/null || cat build.gradle 2>/dev/null || cat build.gradle.kts 2>/dev/null

判定规则非常直接：

检测信号	应用的规则集
构建文件中包含 quarkus	[QUARKUS] 规则
构建文件中包含 spring-boot	[SPRING] 规则
两者均未检测到	仅使用通用 Java 规则

从源码结构看，这条检测链的顺序有讲究：优先 Maven（pom.xml），回退到 Gradle Groovy DSL（build.gradle），再回退到 Kotlin DSL（build.gradle.kts），用 2>/dev/null 吞掉文件不存在的报错，|| 短路保证只读到第一个存在的构建文件。同目录的 java-reviewer.md 使用了同一套检测语义，只是用 find ... | xargs grep -l 'spring-boot\|quarkus' 适配多模块工程（一次扫描 20 个构建文件），可见"先定框架、再套规则"是 ECC 整个 Java Agent 家族的统一范式。

三、诊断命令集：按序执行，先复现后解析

文档给出的诊断命令需要按顺序执行：

./mvnw compile -q 2>&1 || mvn compile -q 2>&1
./mvnw test -q 2>&1 || mvn test -q 2>&1
./gradlew build 2>&1
./mvnw dependency:tree 2>&1 | head -100
./gradlew dependencies --configuration runtimeClasspath 2>&1 | head -100

逐行解读：

1. ./mvnw compile -q 2>&1 || mvn compile -q 2>&1：优先使用项目自带的 Maven Wrapper（版本锁定，避免本机 Maven 版本偏差），-q 静默模式让报错成为唯一噪音输出；Wrapper 不存在时回退到全局 mvn。
2. ./mvnw test -q ...：编译通过后跑测试，确认失败是否来自测试代码而非主代码。
3. ./gradlew build 2>&1：Gradle 工程的等价入口（含编译 + 测试）。
4. ./mvnw dependency:tree | head -100：打印依赖树前 100 行，用于定位传递依赖与版本冲突。
5. ./gradlew dependencies --configuration runtimeClasspath | head -100：Gradle 侧的等价物，聚焦运行期 classpath。

"复现错误 → 阅读受影响文件 → 最小修复 → 再次编译验证 → 跑测试确认无回归"是后面六步工作流的完整展开。

四、六步解决工作流

1. Detect framework (Spring Boot / Quarkus)
2. ./mvnw compile OR ./gradlew build  -> Parse error message
3. Read affected file                 -> Understand context
4. Apply minimal fix                  -> Only what's needed
5. ./mvnw compile OR ./gradlew build  -> Verify fix
6. ./mvnw test OR ./gradlew test      -> Ensure nothing broke

要点在于第 4 步的 "Only what's needed" 与第 6 步的回归验证：每一步修复都必须以一次完整的 build 验证收尾，测试步骤用于确保修复没有引入新的破坏。这与后文"每次修复后必须重新构建"的关键原则一一对应。

五、常见修复模式速查表

5.1 通用 Java

错误	成因	修复
cannot find symbol	缺少 import、拼写错误、缺少依赖	添加 import 或依赖
incompatible types	类型错误、缺少强制转换	添加显式 cast 或修正类型
method X cannot be applied to given types	参数类型或数量错误	修正参数或检查重载
variable X might not have been initialized	局部变量未初始化	使用前初始化变量
package X does not exist	缺少依赖或 import 错误	在构建文件中添加依赖
Annotation processor threw uncaught exception	Lombok/MapStruct 配置错误	检查注解处理器配置
Could not resolve: group:artifact:version	缺少仓库或版本错误	添加仓库或修正版本

5.2 [SPRING] Spring Boot 特有

错误	成因	修复
No qualifying bean of type X	缺少 @Component/@Service 或组件扫描未覆盖	添加注解或修正扫描路径
Circular dependency involving X	构造器注入形成环	重构依赖关系或使用 @Lazy
Failed to configure a DataSource	缺少数据库驱动或 datasource 配置	添加驱动依赖或配置项

5.3 [QUARKUS] Quarkus 特有

错误	成因	修复
UnsatisfiedResolutionException	缺少 CDI 注解或扩展	添加 @ApplicationScoped 或对应扩展
Build step X threw an exception	构建时增强（augmentation）失败	检查缺失的扩展或反射配置
BlockingNotAllowedOnIOThread	在 Vert.x 事件循环上执行阻塞调用	添加 @Blocking 或改用响应式客户端
Panache entity not enhanced	构建时未检测到实体	检查扫描包路径与 Panache 扩展

可以推断，QUARKUS 表中的 BlockingNotAllowedOnIOThread 与 java-reviewer.md 审查项 "Blocking call on reactive thread: Use @Blocking or reactive client" 是同一问题在"修复侧"与"审查侧"的镜像——审查时标记、修复时处理。

六、Maven 疑难排查命令

./mvnw dependency:tree -Dverbose
./mvnw clean install -U
./mvnw dependency:analyze
./mvnw help:effective-pom
./mvnw compile -DskipTests

• dependency:tree -Dverbose：显示被仲裁掉的依赖版本，是排查版本冲突的首选；
• clean install -U：强制刷新快照依赖，排除本地仓库缓存污染；
• dependency:analyze：报告未使用/缺失声明的依赖；
• help:effective-pom：查看合并 profile 后的最终 POM，用于理解"为什么这个属性是这个值"。

七、Gradle 疑难排查命令

./gradlew dependencies --configuration runtimeClasspath
./gradlew build --refresh-dependencies
./gradlew clean && rm -rf .gradle/build-cache/
./gradlew dependencyInsight --dependency <name> --configuration runtimeClasspath

其中 dependencyInsight 是 Gradle 侧最有力的单依赖溯源命令——针对某个 group:artifact 名称，完整展示它由谁传递引入、为何选择了该版本，与 Maven 的 dependency:tree -Dverbose 定位等价。

八、关键原则与停止条件

8.1 五条关键原则

• 只做手术式修复——不重构，只修错误；
• 未经明确批准，绝不用 @SuppressWarnings 压制警告；
• 非必要不改方法签名；
• 每次修复后必须重新构建验证；
• 修根因，而非压制表象。

8.2 停止条件（Stop Conditions）

满足以下任一条件时必须停止并报告，而不是继续盲目尝试：

• 同一错误在 3 次修复尝试后依然存在；
• 修复引入的错误比解决的多；
• 错误需要超出范围（out of scope）的架构级改动；
• 缺少需要用户决策的外部依赖。

这一节是该 Agent 设计中最具工程价值的部分：它把"何时放弃"写成了明确规则，避免 Agent 在无效循环中持续消耗。

九、标准化输出格式

每次修复后，Agent 按如下模板输出进度：

Framework: [SPRING|QUARKUS|UNKNOWN]
[FIXED] src/main/java/com/example/service/PaymentService.java:87
Error: cannot find symbol — symbol: class IdempotencyKey
Fix: Added import com.example.domain.IdempotencyKey
Remaining errors: 1

任务结束时输出汇总行：

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

这种"框架 + 状态 + 数量 + 文件清单"的定式输出让上层编排者（或其他 Agent）可以机器可读地判断任务是否收敛。

十、深入仓库：双格式定义、安装与生态联动

10.1 Markdown 与 JSON 双格式

ECC 的 Kiro 适配层中每个 Agent 都有成对定义：

• java-build-resolver.md：YAML frontmatter（name/description/allowedTools）+ 完整提示词，供 Kiro IDE 使用，通过 /java-build-resolver 自动选择或显式调用；
• java-build-resolver.json：CLI 格式，prompt 字段内嵌了同一份提示词，另含 allowedTools: ["fs_read", "shell"]、空 mcpServers/hooks 等结构化字段，供 kiro-cli 通过 /agent swap 切换。

值得注意的是，JSON 版本末尾比 Markdown 版本多引用了一个技能——Markdown 版写 "See skill: springboot-patterns"，JSON 版写 "See skill: springboot-patterns or skill: quarkus-patterns"。两个技能在仓库根目录均有实体：skills/springboot-patterns/SKILL.md（REST 分层、JPA 仓储、事务服务、DTO 校验等模式）与 skills/quarkus-patterns/SKILL.md（CDI 服务、Panache、Camel 消息、GraalVM 原生编译等模式），即构建错误修复之外，Agent 可进一步引用这些模式库做纵深参考。

10.2 安装方式

按 .kiro/README.md 与 install.sh，将整套 Agent（含 java-build-resolver）安装到任意 Kiro 项目只需：

# 安装到指定项目
cd .kiro
./install.sh /path/to/your/project

# 或安装到当前目录
./install.sh

# 或全局安装（对所有 Kiro 项目生效）
./install.sh ~

安装器采用非破坏性拷贝（不会覆盖已有文件）。README 的组件清单中，java-build-resolver 被描述为 "Java/Maven/Gradle build error resolution specialist. Fixes compilation and dependency errors."，与 java-reviewer（"Enterprise patterns, security, and performance"）同属 Java 工具链的两个分工。CLI 侧使用方式为 kiro-cli --agent java-build-resolver 直接以该 Agent 启动会话，或在会话内 /agent swap 切换。

10.3 在 Java 工作流中的位置

从仓库结构可以推断出该 Agent 在 ECC Java 工作流中的分工链：写代码阶段引用 java-coding-standards/jpa-patterns 等技能约束风格，构建失败时交给 java-build-resolver 做收敛式修复，代码合入前由 java-reviewer 按 CRITICAL/HIGH 优先级清单审查安全与架构问题。三者共享同一套"先检测 Spring Boot / Quarkus 框架、再套框架规则"的判定逻辑，构成 ECC 对 Java 生态的一致化覆盖。

十一、小结

java-build-resolver 的价值不在于某条修复命令，而在于它把"Java 构建排障"固化成了可执行协议：框架检测 → 顺序诊断 → 错误解析 → 最小修复 → 构建验证 → 测试回归，配合明确的停止条件与机器可读的输出格式，使 Agent 的每一次介入都可验证、可审计、可中断。这套协议与 ECC 仓库中的技能库（skills/springboot-patterns/SKILL.md、skills/quarkus-patterns/SKILL.md）和双格式 Agent 定义体系（.kiro/agents/*.md + .kiro/agents/*.json）共同构成了 Kiro 环境下完整的 Java 工程质量闭环。