Spring AI Alibaba 实战：构建模块化、可热插拔的 AI Agent 技能系统

<skill-name>/
├── SKILL.md          # 【必须】核心定义文件
├── references/       # 【可选】API 文档、参考手册
└── scripts/          # 【可选】辅助脚本或代码片段

---
name: data-analyst
description: 用于执行复杂的数据清洗、统计分析和可视化任务，支持 Pandas 和 Matplotlib
---

# 数据分析专家技能

## 角色设定
你是一名资深数据分析师，擅长使用 Python Pandas 处理数据。

## 操作指南
1. 首先使用 `file_reader` 读取 CSV/Excel 文件。
2. 检查数据缺失值并进行清洗。
3. 根据用户需求生成统计图表。

## 注意事项
- 严禁直接输出原始敏感数据。
- 绘图时务必使用中文标签。

@Component
public class DynamicSkillManager {

    private volatile SkillRegistry currentRegistry;
    private final String userSkillsPath = "/var/data/my-app/skills";

    @PostConstruct
    public void init() {
        refresh();
    }

    /**
     * 重新扫描文件系统并构建新的 Registry
     */
    public void refresh() {
        // 1. 系统技能
        SkillRegistry sysReg = ClasspathSkillRegistry.builder()
            .classPathSkillsDirectory("skills")
            .build();
        
        // 2. 用户技能
        SkillRegistry userReg = FileSystemSkillRegistry.builder()
            .projectSkillsDirectory(userSkillsPath)
            .build();

        // 3. 组合
        this.currentRegistry = new CompositeSkillRegistry(
            List.of(sysReg, userReg)
        );
    }

    public SkillRegistry getRegistry() {
        return this.currentRegistry;
    }
}

@Configuration
public class AgentConfig {

    @Autowired
    private DynamicSkillManager skillManager;

    @Bean
    public ReactAgent smartAgent(ChatModel chatModel) {
        // 创建 Hook，它会自动处理元数据注入和 read_skill 工具注册
        SkillsAgentHook hook = SkillsAgentHook.builder()
            .skillRegistry(skillManager.getRegistry())
            .build();

        return ReactAgent.builder()
            .name("business-agent")
            .model(chatModel)
            .hooks(List.of(hook))
            .build();
    }
}

@RestController
public class SkillController {

    @Autowired
    private DynamicSkillManager skillManager;
    
    @Autowired
    private AgentFactory agentFactory; // 假设存在 Agent 工厂

    @PostMapping("/api/skills/upload")
    public ResponseEntity<String> uploadSkill(@RequestParam("file") MultipartFile file) {
        try {
            // 1. 安全校验与解压到 /var/data/my-app/skills/
            skillService.extractAndSave(file); 
            
            // 2. 触发注册表刷新（重新扫描目录）
            skillManager.refresh();
            
            // 3. 注意：如果 Hook 持有的是旧 Registry 引用，可能需要重建 Agent 
            // 或者确保 Hook 内部每次调用都从 Manager 获取最新 Registry
            
            return ResponseEntity.ok("Skill uploaded and activated.");
        } catch (Exception e) {
            return ResponseEntity.status(500).body("Upload failed: " + e.getMessage());
        }
    }
}

@Tool(description = "搜索可用的技能列表")
public String searchSkills(String keyword) {
    List<Skill> skills = skillManager.getRegistry().listSkills();
    // 过滤并返回匹配的技能名称和描述
    return skills.stream()
        .filter(s -> s.getDescription().contains(keyword))
        .map(s -> s.getName() + ": " + s.getDescription())
        .collect(Collectors.joining("\n"));
}