Spring AI中Skill集成的实现原理

@Override
protected void loadSkillsToRegistry() {
    Map<String, SkillMetadata> mergedSkills = new HashMap<>();

    // 第一步：加载用户级 Skill（默认 ~/saa/skills）
    if (userSkillsDirectory != null) {
        List<SkillMetadata> userSkills = scanner.scan(userSkillsDirectory, "user");
        for (SkillMetadata skill : userSkills) {
            mergedSkills.put(skill.getName(), skill);
        }
    }

    // 第二步：加载项目级 Skill（默认 ./skills）
    // 同名 Skill 会覆盖用户级，实现优先级合并
    if (projectSkillsDirectory != null) {
        List<SkillMetadata> projectSkills = scanner.scan(projectSkillsDirectory, "project");
        for (SkillMetadata skill : projectSkills) {
            mergedSkills.put(skill.getName(), skill);
        }
    }

    this.skills = mergedSkills;
}

public SkillMetadata loadSkill(Path skillDir, String source) {
    Path skillFile = skillDir.resolve("SKILL.md");
    if (!Files.exists(skillFile)) { return null; }

    String content = Files.readString(skillFile);
    Map<String, Object> frontmatter = parseFrontmatter(content);

    String name = (String) frontmatter.get("name");
    String description = (String) frontmatter.get("description");

    // 校验名称格式（小写+数字+连字符，最长64字符）
    String directoryName = skillDir.getFileName().toString();
    validateSkillName(name, directoryName, skillFile);

    // 校验并截断描述长度（规范：最大1024字符）
    if (descriptionStr.length() > MAX_SKILL_DESCRIPTION_LENGTH) {
        descriptionStr = descriptionStr.substring(0, MAX_SKILL_DESCRIPTION_LENGTH);
    }

    // 去除 frontmatter，保留正文
    String fullContent = removeFrontmatter(content);

    return SkillMetadata.builder()
            .name(name)
            .description(descriptionStr)
            .skillPath(skillDir.toString())
            .source(source)
            .fullContent(fullContent)
            .build();
}

//FileSystemSkillRegistry

public static final String DEFAULT_SYSTEM_PROMPT_TEMPLATE = """

       ## Skills System

       You have access to a skills library that provides specialized capabilities and domain knowledge. All skills are stored in a Skill Registry with a file system based storage.

       ### Available Skills

       {skills_list}

       ### How to Use Skills (Progressive Disclosure)

       Skills follow a **progressive disclosure** pattern - you know they exist (name + description above), but you only read the full instructions when needed:

       1. **Recognize when a skill applies**: Check if the user's task matches any skill's description
       2. **Read the skill's full instructions**: The skill list above shows the exact skill id to use with `read_skill`
       3. **Follow the skill's instructions**: SKILL.md contains step-by-step workflows, best practices, and examples
       4. **Access supporting files**: Skills may include Python scripts, configs, or reference docs - use absolute paths

       #### How to Read The Full Skill Instruction

       You are currently using the file system based Skill Registry. Please follow the skill loading guidelines below:

       {skills_load_instructions}

       **Important:**

         - **For SKILL.md files (skill instructions)**: Always use `read_skill` to read skill instructions. Do not attempt to access SKILL.md files through other methods.
         - **For other supporting files that skill uses (scripts, references, etc.)**: You may use other appropriate tools to read or access these files as needed, always use absolute paths from the skill list.

       #### When to Use Skills

         - When the user's request matches a skill's domain (e.g., "research X" → web-research skill)
         - When you need specialized knowledge or structured workflows
         - When a skill provides proven patterns for complex tasks

       #### Skills are Self-Documenting

         - Each SKILL.md tells you exactly what the skill does and how to use it
         - The skill list above shows the full path for each skill's SKILL.md file

       #### Executing Skill Scripts

       Skills may contain Python scripts or other executable files. Always use absolute paths from the skill list.

       ### Example Workflow

       User: "Can you research the latest developments in quantum computing?"

       1. Check available skills above → See "web-research" skill with its skill id
       2. Read the skill using the id shown in the list
       3. Follow the skill's research workflow (search → organize → synthesize)
       4. Use any helper scripts with absolute paths

       Remember: Skills are tools to make you more capable and consistent. When in doubt, check if a skill exists for the task!
       """;

@Override
public ChatClientRequest before(ChatClientRequest chatClientRequest, AdvisorChain advisorChain) {
    // 加载/重新加载 Skill 注册信息
    loadSkillsToRegistry();

    List<SkillMetadata> skills = skillRegistry.listAll();
    if (skills.isEmpty()) { return chatClientRequest; }

    // 构建 Skill 提示词并追加到 System Message
    String skillsPrompt = buildSkillsPrompt(skills, skillRegistry, skillRegistry.getSystemPromptTemplate());
    SystemMessage systemMessage = chatClientRequest.prompt().getSystemMessage();
    SystemMessage enhanced = enhanceSystemMessage(systemMessage, skillsPrompt);

    return chatClientRequest.mutate()
        .prompt(chatClientRequest.prompt().augmentSystemMessage(enhanced.getText()))
        .build();
}

@HookPositions(HookPosition.BEFORE_AGENT)
public class SkillsAgentHook extends AgentHook {

    private final SkillRegistry skillRegistry;
    private final ToolCallback readSkillTool;
    private final Map<String, List<ToolCallback>> groupedTools;

    @Override
    public CompletableFuture<Map<String, Object>> beforeAgent(OverAllState state, RunnableConfig config) {
        if (autoReload) {
            skillRegistry.reload();
        }
        return CompletableFuture.completedFuture(Map.of());
    }

    @Override
    public List<ModelInterceptor> getModelInterceptors() {
        return List.of(
            SkillsInterceptor.builder()
                .skillRegistry(this.skillRegistry)
                .groupedTools(this.groupedTools)
                .build());
    }

    @Override
    public List<ToolCallback> getTools() {
        return List.of(readSkillTool);  // 暴露 read_skill 工具给 Agent
    }
}

@Override
public ModelResponse interceptModel(ModelRequest request, ModelCallHandler handler) {
    List<SkillMetadata> skills = skillRegistry.listAll();
    if (skills.isEmpty()) { return handler.call(request); }

    // 1. 扫描历史消息，提取 read_skill 调用的 skill_name
    Set<String> readSkillNames = extractReadSkillNames(request.getMessages());

    // 2. 根据 skill_name 注入关联的动态工具
    List<ToolCallback> skillTools = new ArrayList<>(request.getDynamicToolCallbacks());
    for (String skillName : readSkillNames) {
        List<ToolCallback> toolsForSkill = getGroupedTools().get(skillName);
        if (toolsForSkill != null)
            skillTools.addAll(toolsForSkill);
    }

    // 3. 注入 Skill 列表到 System Prompt
    String skillsPrompt = buildSkillsPrompt(skills, skillRegistry, skillRegistry.getSystemPromptTemplate());
    SystemMessage enhanced = enhanceSystemMessage(request.getSystemMessage(), skillsPrompt);

    // 4. 构建增强后的请求
    return handler.call(ModelRequest.builder(request)
        .systemMessage(enhanced)
        .dynamicToolCallbacks(skillTools)
        .build());
}

private Set<String> extractReadSkillNames(List<Message> messages) {
    Set<String> names = new LinkedHashSet<>();
    for (Message message : messages) {
        if (!(message instanceof AssistantMessage am) || !am.hasToolCalls()) continue;
        for (AssistantMessage.ToolCall toolCall : am.getToolCalls()) {
            if (!ReadSkillTool.READ_SKILL.equals(toolCall.name())) continue;
            String skillName = parseSkillNameFromArguments(toolCall.arguments());
            if (skillName != null) names.add(skillName);
        }
    }
    return names;
}

public class ReadSkillTool implements BiFunction<ReadSkillRequest, ToolContext, String> {

    public static final String READ_SKILL = "read_skill";
    private final SkillRegistry skillRegistry;

    @Override
    public String apply(ReadSkillRequest request, ToolContext toolContext) {
        if (request.skillName == null || request.skillName.isEmpty())
            return "Error: skill_name is required";

        // 从 SkillRegistry 读取完整内容
        String content = skillRegistry.readSkillContent(request.skillName);
        return content;
    }

    // LLM 调用时的请求结构
    public static class ReadSkillRequest {
        @JsonProperty(required = true, value = "skill_name")
        @JsonPropertyDescription("The name of the skill to read")
        public String skillName;
    }
}