SpringAI Agent 实战：Java 开发者接入 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 建议使用启动参数或环境变量设置
      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 目录下新建 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. 以中文的方式返回代码评审结果

4. Skills 结构说明

SpringAI 支持的 Skills 不仅包含 SKILL.md（元数据 + 指令），还可以包含脚本、模板和参考资料。典型结构如下：

my-skill/
├── 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);

    private 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 作为待评审对象。这段代码实现了长文档分割成较小块的功能，包含向量化和检索逻辑。

(此处省略具体代码块，实际运行时请确保文件路径正确)

3. 核心 Bean 定义

配置 Agent 实现代码评审，主要涉及 CommandLineRunner 和 ChatClient.Builder。

Bean 定义与依赖注入

• CommandLineRunner: Spring 启动后自动执行。
• ChatClient.Builder: 构建聊天客户端。
• @Value("${agent.skills.dirs:Unknown}"): 注入技能目录资源列表。

ChatClient 配置链

• 系统提示词: 始终运用现有技能协助用户。
• 技能工具: SkillsTool.builder() 动态加载预定义技能。
• 文件系统工具: FileSystemTools.builder() 允许读取本地文件（用于读取待评审代码）。
• Shell 工具: ShellTools.builder() 支持脚本执行（若技能中包含脚本）。
• Advisor: 处理工具调用逻辑及自定义日志记录。

代码评审执行流程

@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. 第一轮: 用户原始诉求 -> 大模型识别意图，响应 command: code-reviewer。
2. 第二轮: 系统接收响应，读取技能约束，大模型返回需要读取的代码文件路径。
3. 第三轮: 系统读取代码内容发送给大模型，大模型返回最终评审结果。

(此处展示运行截图，显示日志交互过程)

下面是完整的返回文本示例：

基于对代码的详细分析，我为您提供以下代码评审报告：

## 📋 代码评审报告 - DocumentChunker.java

### ✅ **优点**
1. **功能完整性强**：代码实现了完整的文档分块功能...
2. **良好的文档注释**：类和方法都有清晰的中文注释...

### ⚠️ **需要改进的问题**
#### 1. **线程安全问题**
// 问题：静态实例不是线程安全的
public static DocumentChunker DEFAULT_CHUNKER = new DocumentChunker();
**建议**：使用 `volatile` 或 `AtomicReference`，或者移除静态实例让用户自己管理。

#### 2. **参数验证不足**
// 问题：构造函数没有参数验证
public DocumentChunker(int maxChunkSize, int overlapSize) { ... }
**建议**：添加参数验证，确保 `maxChunkSize > 0` 且 `overlapSize < maxChunkSize`。

### 🔧 **具体改进建议**
#### 1. **添加参数验证**
...

### 🎯 **总体评价**
这是一个功能完整、设计合理的文档分块工具类，主要问题集中在线程安全、参数验证和代码可维护性方面。

三、小结

SpringAI 的 Agent 开发范式配合 Skills 机制，让 AI 应用的工程化变得非常简单。整个过程门槛较低，但背后的设计哲学值得深思——在 AI 时代，如何将现有的技能（如可复用、模块化设计）转变到大模型应用开发，是每位程序员的重要课题。

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

1. 发现（启动阶段）：通过 SKILL.md 中的元数据，快速实现技能的安装注册。
2. 语义匹配（对话过程中）：当用户发出请求时，LLM 检查工具定义中的技能描述。如果语义匹配，则调用该技能工具。
3. 执行（技能调用时）：SkillsTool 从磁盘加载完整的 SKILL.md 内容返回给 LLM，LLM 按指令执行。若引用其他文件或脚本，则通过 FileSystemTools 或 ShellTools 按需访问。

这套机制展示了如何将传统软件工程经验有效迁移到 AI 应用中。