Skills 在 Spring Boot 中的应用#

1
MCP（模型上下文协议）
2
├── 作用：让 AI 能够访问数据库、API、文件系统
3
└── 定位：工具调用能力的扩展
4

5
Skills（技能系统）
6
├── 作用：让 AI 快速掌握领域知识和工作流程
7
└── 定位：专业能力的封装和复用

1
你是一位就职于苹果公司的顶级前端工程师。请创建一个包含CSS和JavaScript的HTML文件，用于生成动画天气卡片。卡片需要以不同动画效果直观展示以下天气状况：
2

3
风力（如：飘动的云朵、摇曳的树木或风线）
4
降雨（如：下落的雨滴、形成的水洼）
5
晴天（如：闪耀的光线、明亮的背景）
6
下雪（如：飘落的雪花、积雪效果）
7

8
所有天气卡片需要并排显示，背景采用深色设计。所有HTML、CSS和JavaScript代码都需包含在这个单一文件中。JavaScript部分需包含切换不同天气状态的功能（例如通过函数或按钮组），以演示每种天气的动画效果。
9

10
将前端显示效果优化得更精致流畅，打造出价值20元/月的精品天气应用既视感。

1
<properties>
2
    <java.version>17</java.version>
3
    <spring-boot.version>3.4.4</spring-boot.version>
4
    <spring-ai.version>1.0.0-M6</spring-ai.version>
5
</properties>

1
<dependencies>
2
    <!-- Spring AI 核心依赖 -->
3
    <dependency>
4
        <groupId>org.springframework.ai</groupId>
5
        <artifactId>spring-ai-core</artifactId>
6
        <version>${spring-ai.version}</version>
7
    </dependency>
8

9
    <!-- Spring AI OpenAI 集成（兼容 DeepSeek 等） -->
10
    <dependency>
11
        <groupId>org.springframework.ai</groupId>
12
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
13
        <version>${spring-ai.version}</version>
14
    </dependency>
15

16
    <!-- Spring AI Anthropic 集成 -->
17
    <dependency>
18
        <groupId>org.springframework.ai</groupId>
19
        <artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
20
        <version>${spring-ai.version}</version>
21
    </dependency>
22
</dependencies>

1
<repositories>
2
    <repository>
3
        <id>spring-milestones</id>
4
        <name>Spring Milestones</name>
5
        <url>https://repo.spring.io/milestone</url>
6
        <snapshots>
7
            <enabled>false</enabled>
8
        </snapshots>
9
    </repository>
10
</repositories>

1
spring:
2
  ai:
3
    # Anthropic 配置（使用 Claude 模型）
4
    anthropic:
5
      chat:
6
        enabled: true
7
        options:
8
          model: claude-sonnet-4-20250514  # 或者 claude-opus-4-20250514
9
      api-key: ${ANTHROPIC_API_KEY}  # 环境变量配置
10

11
    # 或者使用 DeepSeek（更经济的选择）
12
    openai:
13
      chat:
14
        enabled: true
15
        options:
16
          model: deepseek-chat  # DeepSeek 支持 Tools 调用
17
      base-url: https://api.deepseek.com
18
      api-key: ${DEEPSEEK_API_KEY}
19

20
    # Agent Skills 配置
21
    agent:
22
      skills-enabled: true  # 启用 Skills 功能
23
      skills-directory: classpath:skills/  # Skills 文件目录

1
┌─────────────────────────────────────────────────────┐
2
│                   Spring Boot 应用                   │
3
├─────────────────────────────────────────────────────┤
4
│                                                     │
5
│  ┌─────────────────────────────────────────────┐  │
6
│  │         ChatClient (AI 对话客户端)            │  │
7
│  └──────────────┬──────────────────────────────┘  │
8
│                 │                                   │
9
│  ┌──────────────▼──────────────────────────────┐  │
10
│  │      ToolCallbackProvider (工具注册)         │  │
11
│  └──────────────┬──────────────────────────────┘  │
12
│                 │                                   │
13
│  ┌──────────────▼──────────────────────────────┐  │
14
│  │         Skills (技能封装层)                  │  │
15
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  │  │
16
│  │  │ Skill 1  │  │ Skill 2  │  │ Skill N  │  │  │
17
│  │  │ (数据分析)│  │(文档生成)│  │(代码审查)│  │  │
18
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  │  │
19
│  └───────┼────────────┼────────────┼──────────┘  │
20
│          │            │            │              │
21
│  ┌───────▼────────────▼────────────▼──────────┐  │
22
│  │      底层工具实现（数据库、API、脚本等）      │  │
23
│  └─────────────────────────────────────────────┘  │
24
└─────────────────────────────────────────────────────┘

1
src/main/resources/
2
└── skills/
3
    ├── data-analysis/
4
    │   ├── skill.md          # 技能定义文件
5
    │   ├── tools.py          # Python 脚本（可选）
6
    │   └── schema.json       # 数据结构定义（可选）
7
    │
8
    ├── document-generator/
9
    │   ├── skill.md
10
    │   ├── template.md       # 文档模板
11
    │   └── examples/         # 示例文档
12
    │
13
    └── code-reviewer/
14
        ├── skill.md
15
        ├── checkstyle.xml    # 代码规范配置
16
        └── rules/            # 审查规则

1
# Data Analysis Skill
2

3
## 触发条件
4
当用户需要以下操作时，自动激活此技能：
5
- 查询数据库中的用户数据
6
- 生成统计报表
7
- 分析业务趋势
8
- 导出数据到 Excel
9

10
## 可用工具
11

12
### 1. queryUsers
13
- 描述：根据条件查询用户信息
14
- 参数：name（用户姓名，可选）、department（部门，可选）
15
- 返回：用户列表
16

17
### 2. generateReport
18
- 描述：生成数据统计报表
19
- 参数：startDate、endDate、reportType（daily/weekly/monthly）
20
- 返回：报表数据
21

22
### 3. exportToExcel
23
- 描述：将数据导出为 Excel 文件
24
- 参数：data、filename
25
- 返回：文件下载链接
26

27
## 执行流程
28
1. 理解用户需求
29
2. 选择合适的工具
30
3. 执行查询或分析
31
4. 格式化输出结果

1
package com.example.skills.tools;
2

3
import org.springframework.ai.tool.annotation.Tool;
4
import org.springframework.ai.tool.annotation.ToolParam;
5
import org.springframework.stereotype.Service;
6
import lombok.RequiredArgsConstructor;
7
import lombok.extern.slf4j.Slf4j;
8

9
import java.util.List;
10
import java.util.Map;
11

12
/**
13
 * 数据分析技能工具类
14
 */
15
@Slf4j
16
@Service
17
@RequiredArgsConstructor
18
public class DataAnalysisTools {
19

20
    private final UserService userService;
21
    private final ReportService reportService;
22

23
    /**
24
     * 查询用户信息
25
     */
26
    @Tool(name = "queryUsers", description = "根据条件查询用户信息")
27
    public List<Map<String, Object>> queryUsers(
28
            @ToolParam(description = "用户姓名（模糊查询）") String name,
29
            @ToolParam(description = "部门名称") String department
30
    ) {
31
        log.info("执行用户查询：name={}, department={}", name, department);
32

33
        // 调用业务服务查询数据
34
        List<Map<String, Object>> users = userService.queryUsers(name, department);
35

36
        log.info("查询到 {} 条用户记录", users.size());
37
        return users;
38
    }
39

40
    /**
41
     * 生成统计报表
42
     */
43
    @Tool(name = "generateReport", description = "生成数据统计报表")
44
    public Map<String, Object> generateReport(
45
            @ToolParam(description = "开始日期，格式：yyyy-MM-dd") String startDate,
46
            @ToolParam(description = "结束日期，格式：yyyy-MM-dd") String endDate,
47
            @ToolParam(description = "报表类型：daily/weekly/monthly") String reportType
48
    ) {
49
        log.info("生成报表：startDate={}, endDate={}, type={}", startDate, endDate, reportType);
50

51
        // 生成报表数据
52
        Map<String, Object> report = reportService.generateReport(startDate, endDate, reportType);
53

54
        log.info("报表生成成功");
55
        return report;
56
    }
57

58
    /**
59
     * 导出数据到 Excel
60
     */
61
    @Tool(name = "exportToExcel", description = "将数据导出为 Excel 文件")
62
    public String exportToExcel(
63
            @ToolParam(description = "要导出的数据列表") List<Map<String, Object>> data,
64
            @ToolParam(description = "文件名称（不含扩展名）") String filename
65
    ) {
66
        log.info("导出数据到 Excel：filename={}, 数据量={}", filename, data.size());
67

68
        // 导出 Excel
69
        String downloadUrl = reportService.exportToExcel(data, filename);
70

71
        log.info("Excel 导出成功：{}", downloadUrl);
72
        return downloadUrl;
73
    }
74
}

1
package com.example.skills.config;
2

3
import com.example.skills.tools.DataAnalysisTools;
4
import org.springframework.ai.chat.client.ChatClient;
5
import org.springframework.ai.tool.MethodToolCallbackProvider;
6
import org.springframework.ai.tool.ToolCallbackProvider;
7
import org.springframework.context.annotation.Bean;
8
import org.springframework.context.annotation.Configuration;
9
import lombok.extern.slf4j.Slf4j;
10

11
/**
12
 * Skills 配置类
13
 */
14
@Slf4j
15
@Configuration
16
public class SkillsConfig {
17

18
    /**
19
     * 注册数据分析技能
20
     */
21
    @Bean
22
    public ToolCallbackProvider dataAnalysisSkillProvider(DataAnalysisTools dataAnalysisTools) {
23
        log.info("开始注册数据分析技能...");
24

25
        MethodToolCallbackProvider provider = MethodToolCallbackProvider.builder()
26
                .toolObjects(dataAnalysisTools)
27
                .build();
28

29
        // 打印注册的工具信息
30
        for (var tool : provider.getToolCallbacks()) {
31
            log.info("已注册工具：{} - {}",
32
                    tool.getToolDefinition().name(),
33
                    tool.getToolDefinition().description());
34
        }
35

36
        return provider;
37
    }
38

39
    /**
40
     * 创建数据分析 ChatClient
41
     */
42
    @Bean
43
    public ChatClient dataAnalysisChatClient(
44
            ChatClient.Builder builder,
45
            ToolCallbackProvider dataAnalysisSkillProvider
46
    ) {
47
        return builder
48
                .defaultSystem("""
49
                        你是一个专业的数据分析助手。
50
                        你可以帮助用户：
51
                        1. 查询数据库中的用户信息
52
                        2. 生成各类统计报表
53
                        3. 将数据导出为 Excel 文件
54

55
                        请使用简洁、专业的语言与用户交流。
56
                        当提供数据时，请用表格或列表的形式展示，确保易读性。
57
                        """)
58
                .defaultTools(dataAnalysisSkillProvider)
59
                .build();
60
    }
61
}

1
package com.example.skills.controller;
2

3
import org.springframework.ai.chat.client.ChatClient;
4
import org.springframework.web.bind.annotation.*;
5
import lombok.RequiredArgsConstructor;
6
import lombok.extern.slf4j.Slf4j;
7

8
/**
9
 * 数据分析 API 控制器
10
 */
11
@Slf4j
12
@RestController
13
@RequestMapping("/api/data-analysis")
14
@RequiredArgsConstructor
15
public class DataAnalysisController {
16

17
    private final ChatClient dataAnalysisChatClient;
18

19
    @PostMapping("/chat")
20
    public String chat(@RequestBody String userMessage) {
21
        log.info("用户请求：{}", userMessage);
22

23
        String response = dataAnalysisChatClient.prompt()
24
                .user(userMessage)
25
                .call()
26
                .content();
27

28
        log.info("AI 响应：{}", response);
29
        return response;
30
    }
31
}

1
POST /api/data-analysis/chat
2

3
{
4
  "userMessage": "帮我查询技术部的所有用户"
5
}

1
POST /api/data-analysis/chat
2

3
{
4
  "userMessage": "生成2025年1月的月度报表"
5
}

1
POST /api/data-analysis/chat
2

3
{
4
  "userMessage": "把技术部用户导出成Excel"
5
}

1
用户输入
2
    │
3
    ├─→ Claude 理解意图
4
    │       │
5
    │       ├─→ 判断需要哪个 Skill
6
    │       │
7
    │       └─→ 选择合适的 Tool
8
    │               │
9
    │               ├─→ Tool 1: queryUsers
10
    │               ├─→ Tool 2: generateReport
11
    │               └─→ Tool 3: exportToExcel
12
    │                       │
13
    │                       └─→ 执行 Java 方法
14
    │                               │
15
    │                               ├─→ 查询数据库
16
    │                               ├─→ 调用业务服务
17
    │                               └─→ 返回结果
18
    │                                       │
19
    └─→ Claude 格式化输出
20
            │
21
            └─→ 返回给用户

1
skills/
2
├── data-analysis/      # 数据分析技能
3
│   └── skill.md
4
├── document-writer/    # 文档编写技能
5
│   └── skill.md
6
└── code-reviewer/      # 代码审查技能
7
    └── skill.md

1
@Configuration
2
public class MultiSkillsConfig {
3

4
    @Bean
5
    public ToolCallbackProvider dataAnalysisSkillProvider(DataAnalysisTools tools) {
6
        return MethodToolCallbackProvider.builder()
7
                .toolObjects(tools)
8
                .build();
9
    }
10

11
    @Bean
12
    public ToolCallbackProvider documentWriterSkillProvider(DocumentWriterTools tools) {
13
        return MethodToolCallbackProvider.builder()
14
                .toolObjects(tools)
15
                .build();
16
    }
17

18
    @Bean
19
    public ChatClient multiSkillChatClient(
20
            ChatClient.Builder builder,
21
            @Qualifier("dataAnalysisSkillProvider") ToolCallbackProvider dataSkills,
22
            @Qualifier("documentWriterSkillProvider") ToolCallbackProvider docSkills
23
    ) {
24
        return builder
25
                .defaultSystem("""
26
                        你是一个全能的 AI 助手，具备以下能力：
27

28
                        1. 数据分析：查询数据、生成报表、导出 Excel
29
                        2. 文档编写：生成 API 文档、编写技术方案
30
                        3. 代码审查：检查代码质量、提供优化建议
31

32
                        根据用户的需求，自动选择合适的技能完成任务。
33
                        """)
34
                .defaultTools(dataSkills, docSkills)
35
                .build();
36
    }
37
}

1
// 示例：不同的用户请求会自动路由到不同的技能
2

3
"帮我查询销售数据"      → Data Analysis Skill
4
"生成 API 文档"        → Document Writer Skill
5
"审查这段代码"         → Code Reviewer Skill
6
"分析用户增长趋势"     → Data Analysis Skill
7
"编写接口使用说明"     → Document Writer Skill

1
skills/
2
└── {skill-name}/
3
    ├── skill.md          # 必需：技能定义
4
    ├── schema.json       # 可选：数据结构
5
    ├── tools.py          # 可选：脚本工具
6
    ├── templates/        # 可选：模板文件
7
    └── examples/         # 可选：示例数据