SpringAI Agent 实战：利用 Skills 构建代码评审智能体

核心依赖如下：

<dependencies>
    <dependency>
        <groupId>org.springaicommunity</groupId>
        <artifactId>spring-ai-agent-utils</artifactId>
        <version>0.4.1</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-zhipuai</artifactId>
    </dependency>
</dependencies>

• spring-ai-agent-utils: Agent 开发的关键工具包。
• spring-ai-starter-model-zhipuai: 智谱大模型交互适配器。

2. 配置文件

在 resources/application.yml 中配置 LLM 访问信息及 Agent 参数：

spring:
  ai:
    zhipuai:
      # api-key 建议使用环境变量或启动参数注入，避免硬编码
      api-key: ${zhipuai-api-key}
    chat:
      options:
        model: GLM-4.5-Flash
    agent:
      skills:
        dirs: classpath:/.claude/skills
        model: GLM-4.5-Flash

其中 agent.skills.dirs 指定了技能资源的存放路径。

3. 定义 Skills

将技能文件放在 resources/.claude/skills 目录下。创建一个名为 code-reviewer 的技能目录，包含 SKILL.md 文件：

.claude/skills/code-reviewer/
└── SKILL.md

SKILL.md 内容示例：

--- name: code-reviewer description: Reviews Java code for best practices, security issues, and Spring Framework conventions. Use when user asks to review, analyze, or audit code. ---
# Code Reviewer

## Instructions
在审查代码时：
1. 检查是否存在安全漏洞（如 SQL 注入、XSS 等）
2. 验证是否遵循了 Spring Boot 的最佳实践（如正确使用@Service、@Repository 等注解）
3. 查找潜在的空指针异常
4. 提出提高代码可读性和可维护性的建议
5. 提供具体的逐行反馈，并附上代码示例
6. 以中文的方式返回代码评审结果

Skills 结构通常包含元数据指令 (SKILL.md)，也可扩展脚本 (scripts/)、参考资料 (references/) 和模板 (assets/)。

二、核心实现

准备工作就绪后，开始编写核心逻辑。为了让调试更直观，我们先自定义一个日志顾问来观察 Agent 与大模型的交互轮次。

1. 交互日志记录 (MyLoggingAdvisor)

通过实现 BaseAdvisor 接口，我们可以拦截请求和响应，打印出关键的对话信息，包括系统提示词、可用工具列表以及多轮交互的细节。

public class MyLoggingAdvisor implements BaseAdvisor {
    private final int order;
    public final boolean showSystemMessage;
    public final boolean showAvailableTools;
    private AtomicInteger cnt = new AtomicInteger(1);

    public MyLoggingAdvisor(int order, boolean showSystemMessage, boolean showAvailableTools) {
        this.order = order;
        this.showSystemMessage = showSystemMessage;
        this.showAvailableTools = showAvailableTools;
    }

    @Override
    public int getOrder() {
        return this.order;
    }

    @Override
    public ChatClientRequest before(ChatClientRequest chatClientRequest, AdvisorChain advisorChain) {
        System.out.println("======================= 第 " + cnt.getAndAdd(1) + " 轮 ====================================");
        StringBuilder sb = new StringBuilder("\nUSER: ");
        if (this.showSystemMessage && chatClientRequest.prompt().getSystemMessage() != null) {
            sb.append("\n - SYSTEM: ").append(first(chatClientRequest.prompt().getSystemMessage().getText(), 300));
        }
        if (this.showAvailableTools) {
            Object tools = "No Tools";
            if (chatClientRequest.prompt().getOptions() instanceof ToolCallingChatOptions toolOptions) {
                tools = toolOptions.getToolCallbacks().stream()
                        .map(tc -> tc.getToolDefinition().name())
                        .toList();
            }
            sb.append("\n - TOOLS: ").append(ModelOptionsUtils.toJsonString(tools));
        }
        Message lastMessage = chatClientRequest.prompt().getLastUserOrToolResponseMessage();
        if (lastMessage.getMessageType() == MessageType.TOOL) {
            ToolResponseMessage toolResponseMessage = (ToolResponseMessage) lastMessage;
            for (var toolResponse : toolResponseMessage.getResponses()) {
                var tr = toolResponse.name() + ": " + first(toolResponse.responseData(), 1000);
                sb.append("\n - TOOL-RESPONSE: ").append(tr);
            }
        } else if (lastMessage.getMessageType() == MessageType.USER) {
            if (StringUtils.hasText(lastMessage.getText())) {
                sb.append("\n - TEXT: ").append(first(lastMessage.getText(), 1000));
            }
        }
        System.out.println("before: " + sb);
        return chatClientRequest;
    }

    @Override
    public ChatClientResponse after(ChatClientResponse chatClientResponse, AdvisorChain advisorChain) {
        StringBuilder sb = new StringBuilder("\nASSISTANT: ");
        if (chatClientResponse.chatResponse() == null || chatClientResponse.chatResponse().getResults() == null) {
            sb.append(" No chat response ");
            System.out.println("after: " + sb);
            return chatClientResponse;
        }
        for (var generation : chatClientResponse.chatResponse().getResults()) {
            var message = generation.getOutput();
            if (message.getToolCalls() != null) {
                for (var toolCall : message.getToolCalls()) {
                    sb.append("\n - TOOL-CALL: ").append(toolCall.name()).append(" (").append(toolCall.arguments()).append(")");
                }
            }
            if (message.getText() != null) {
                if (StringUtils.hasText(message.getText())) {
                    sb.append("\n - TEXT: ").append(first(message.getText(), 1200));
                }
            }
        }
        System.out.println("after: " + sb);
        return chatClientResponse;
    }

    private String first(String text, int n) {
        if (text.length() <= n) return text;
        return text.substring(0, n) + "...";
    }

    public static Builder builder() {
        return new Builder();
    }

    public static class Builder {
        private int order = 0;
        private boolean showSystemMessage = true;
        private boolean showAvailableTools = true;

        public Builder order(int order) {
            this.order = order;
            return this;
        }

        public Builder showSystemMessage(boolean showSystemMessage) {
            this.showSystemMessage = showSystemMessage;
            return this;
        }

        public Builder showAvailableTools(boolean showAvailableTools) {
            this.showAvailableTools = showAvailableTools;
            return this;
        }

        public MyLoggingAdvisor build() {
            return new MyLoggingAdvisor(this.order, this.showSystemMessage, this.showAvailableTools);
        }
    }
}

2. 待评审代码样本

为了测试效果，我们选取一段文档分块工具类 DocumentChunker.java 作为评审对象。这段代码实现了长文档分割成较小块的功能，包含语义边界识别和重叠机制。

package com.git.hui.springai.app.demo;

import org.springframework.ai.document.Document;
import java.util.ArrayList;
import java.util.List;

/**
 * 文档分块工具类
 * 将长文档分割成较小的块，以便更好地进行向量化和检索
 */
public class DocumentChunker {
    private final int maxChunkSize;
    private final int overlapSize;

    public static DocumentChunker DEFAULT_CHUNKER = new DocumentChunker();

    public DocumentChunker() {
        this(500, 50); // 默认值：最大块大小 500 个字符，重叠 50 个字符
    }

    public DocumentChunker(int maxChunkSize, int overlapSize) {
        this.maxChunkSize = maxChunkSize;
        this.overlapSize = overlapSize;
    }

    /**
     * 将文档分割成块
     *
     * @param document 输入文档
     * @return 分割后的文档块列表
     */
    public List<Document> chunkDocument(Document document) {
        String content = document.getText();
        if (content == null || content.trim().isEmpty()) {
            return List.of(document);
        }
        List<String> chunks = splitText(content);
        List<Document> chunkedDocuments = new ArrayList<>();
        for (int i = 0; i < chunks.size(); i++) {
            String chunk = chunks.get(i);
            String chunkId = document.getId() + "_chunk_" + i;
            Document chunkDoc = new Document(chunkId, chunk, new java.util.HashMap<>(document.getMetadata()));
            chunkDoc.getMetadata().put("chunk_index", i);
            chunkDoc.getMetadata().put("total_chunks", chunks.size());
            chunkDoc.getMetadata().put("original_document_id", document.getId());
            chunkedDocuments.add(chunkDoc);
        }
        return chunkedDocuments;
    }

    /**
     * 将文本分割成块
     *
     * @param text 输入文本
     * @return 分割后的文本块列表
     */
    private List<String> splitText(String text) {
        List<String> chunks = new ArrayList<>();
        String[] sentences = text.split("(?<=。)|(?<=！)|(?<=!)|(?<=？)|(?<=\\?)|(?<=\\n\\n)");
        StringBuilder currentChunk = new StringBuilder();
        for (String sentence : sentences) {
            if (sentence.trim().isEmpty()) continue;
            if (currentChunk.length() + sentence.length() <= maxChunkSize) {
                if (currentChunk.length() > 0) currentChunk.append(sentence);
                else currentChunk.append(sentence);
            } else {
                if (currentChunk.length() == 0) {
                    List<String> subChunks = forceSplit(sentence, maxChunkSize);
                    for (int i = 0; i < subChunks.size(); i++) {
                        String subChunk = subChunks.get(i);
                        if (i < subChunks.size() - 1) chunks.add(subChunk);
                        else currentChunk.append(subChunk);
                    }
                } else {
                    chunks.add(currentChunk.toString());
                    currentChunk = new StringBuilder();
                    if (sentence.length() > overlapSize) {
                        String overlap = sentence.substring(Math.max(0, sentence.length() - overlapSize));
                        currentChunk.append(overlap);
                        currentChunk.append(sentence);
                    } else {
                        currentChunk.append(sentence);
                    }
                }
            }
        }
        if (currentChunk.length() > 0) chunks.add(currentChunk.toString());
        return chunks;
    }

    /**
     * 强制将长文本分割成指定大小的块
     *
     * @param text 输入文本
     * @param maxSize 最大块大小
     * @return 分割后的文本块列表
     */
    private List<String> forceSplit(String text, int maxSize) {
        List<String> chunks = new ArrayList<>();
        int start = 0;
        while (start < text.length()) {
            int end = Math.min(start + maxSize, text.length());
            String chunk = text.substring(start, end);
            chunks.add(chunk);
            start = end;
        }
        return chunks;
    }

    /**
     * 将多个文档分别分割成块
     *
     * @param documents 输入文档列表
     * @return 分割后的文档块列表
     */
    public List<Document> chunkDocuments(List<Document> documents) {
        List<Document> allChunks = new ArrayList<>();
        for (Document document : documents) allChunks.addAll(chunkDocument(document));
        return allChunks;
    }
}

3. Agent 配置与执行

在 Spring Boot 启动类中，我们需要配置 CommandLineRunner 来初始化 Agent 并发起调用。

关键点在于 ChatClient.Builder 的链式配置：

• System Prompt: 设定全局行为准则。
• Skill Tool: 动态加载预定义的 SKILL.md 资源。
• File System / Shell Tools: 赋予 Agent 读取本地文件和执行命令的能力，这对 Skills 中的脚本执行至关重要。
• Advisors: 集成自定义日志顾问，过滤不必要的调试信息。

@Bean
CommandLineRunner commandLineRunner(ChatClient.Builder chatClientBuilder,
                                    @Value("${agent.skills.dirs:Unknown}") List<Resource> agentSkillsDirs) throws IOException {
    return args -> {
        ChatClient chatClient = chatClientBuilder
                .defaultSystem("始终运用现有技能协助用户满足其要求.")
                .defaultToolCallbacks(SkillsTool.builder().addSkillsResources(agentSkillsDirs).build())
                .defaultTools(FileSystemTools.builder().build())
                .defaultTools(ShellTools.builder().build())
                .defaultAdvisors(
                        ToolCallAdvisor.builder().build(),
                        MyLoggingAdvisor.builder().showAvailableTools(false).showSystemMessage(false).build()
                )
                .build();

        var answer = chatClient
                .prompt("按照最佳实际的方式，评审下面的代码实现：D:\\Workspace\\hui\\project\\spring-ai-demo\\v2\\T01-agentic-skills-simple-design\\src\\main\\java\\com\\git\\hui\\springai\\app\\demo\\DocumentChunker.java ")
                .call()
                .content();
        System.out.println("The Answer: " + answer);
    };
}

4. 运行效果

启动项目后，可以看到系统与大模型之间进行了三轮交互：

1. 第一轮：用户提交诉求，大模型识别到需要代码评审，触发 code-reviewer 技能。
2. 第二轮：Agent 根据技能约束，请求读取待评审的代码文件路径。
3. 第三轮：Agent 读取代码内容并发送给大模型，最终返回评审报告。

大模型返回的评审报告涵盖了优点分析、潜在问题（如线程安全、参数验证、正则复杂度等）以及具体的改进建议。这种基于 Skills 的模块化设计，让 AI 能够像处理传统代码一样处理任务，复用性极强。

三、总结

SpringAI 的 Agent 开发范式配合 Skills 机制，极大地降低了 AI 应用的工程化门槛。整个过程不仅简单，更重要的是它背后的设计哲学值得借鉴——在 AI 时代，如何将我们现有的技能（如可复用、模块化设计等）迁移到大模型应用开发，是每一位开发者需要思考的方向。

Spring AI 采用基于工具的集成方法，使任何 LLM 都能回调执行。Skills 的运行过程通常分为三步：

1. 发现：启动阶段通过 SKILL.md 元数据注册技能。
2. 语义匹配：对话过程中，LLM 判断用户请求是否与技能描述匹配。
3. 执行：调用技能工具时，加载完整指令并执行，必要时借助文件系统或 Shell 工具辅助。

这种模式让 Java 开发者在 AI 领域依然能发挥架构设计的优势。