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: 智谱大模型交互适配器。

3. 配置文件

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

spring:
  ai:
    zhipuai:
      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，它定义了技能资源的存放路径。我们将技能文件放在 resources/.claude/skills 目录下。

4. 定义 Skill

新建目录 code-reviewer，并在其中创建 SKILL.md 文件。

.claude/skills/code-reviewer/
└── 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 的最佳实践
3. 查找潜在的空指针异常
4. 提出提高代码可读性和可维护性的建议
5. 提供具体的逐行反馈，并附上代码示例
6. 以中文的方式返回代码评审结果

SpringAI 支持的 Skills 结构通常包含元数据（名称、描述）、指令脚本及参考资料。上述 SKILL.md 即包含了 Agent 执行任务的核心逻辑。

二、核心实现

1. 交互日志追踪 (MyLoggingAdvisor)

为了清晰观察 Agent 与大模型的交互轮次，我们自定义一个 Advisor 来打印日志。这有助于理解一次用户请求背后实际发生了多少次调用。

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 配置与执行

在 CommandLineRunner 中构建 ChatClient，注入 Skills 资源并配置工具链。

@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\\spring-ai\\app\\demo\\DocumentChunker.java ")
                .call()
                .content();
        System.out.println("The Answer: " + answer);
    };
}

启动项目后，系统会与大模型进行多轮交互。从日志可以看出，整个过程分为三轮：

1. 第一轮：用户发起诉求，大模型识别意图，响应调用技能 code-reviewer。
2. 第二轮：系统读取技能约束，大模型请求读取具体代码文件路径。
3. 第三轮：系统读取代码内容发送给大模型，最终返回评审报告。

最终返回的评审报告涵盖了优点分析、问题指出（如线程安全、参数验证、正则复杂度等）以及改进建议。

三、小结

SpringAI 的 Agent 开发范式配合 Skills 机制，极大地降低了 AI 应用的工程化门槛。虽然实现方式看似简单，但其背后的设计哲学值得深思——在 AI 时代，如何将现有的编程技能（如模块化、复用性）转化为大模型可理解的指令，是每位开发者需要掌握的新能力。

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

1. 发现（Discovery）：启动阶段通过 SKILL.md 中的元数据注册技能。
2. 语义匹配（Matching）：对话过程中，LLM 判断用户请求是否与技能描述匹配。
3. 执行（Execution）：调用技能工具时，加载完整指令，必要时结合 FileSystemTools 或 ShellTools 按需访问外部资源。

项目源码：

• https://github.com/liuyueyi/spring-ai-demo/tree/master/v2/T01-agentic-skills-simple-design