一、问题出现：上线后频繁报「Skill not found」

本以为本地测试无误后，上线就能顺利运行，结果程序部署到服务器后，日志中频繁出现 Skill not found: 错误，导致相关功能完全无法使用。

二、问题排查：排除常见误区

遇到问题后，首先排查了最容易出现问题的两个点，均排除异常：

1. 确认 Skill 已成功打包：检查部署的 jar 包，解压后确认 skill 相关文件已正常包含在内，不存在打包遗漏的情况；
2. 确认 Skill Name 无误：核对代码中调用 Skill 的名称与配置文件中的名称，完全一致，排除拼写错误、大小写错误等问题。

三、问题根源：找到官方 Issue

排除上述常见问题后，推测可能是框架本身的兼容性问题，于是去 GitHub 上搜索相关问题，果然发现已有其他开发者遇从 Issue 中得知，问题根源在于 SpringBoot 项目打包成 jar 包后，路径机制发生变化，导致 ClasspathSkillRegistry 无法正常加载 resources 下的 Skill 目录，这是目前 spring-ai-alibaba 框架的一个已知 bug。

四、临时解决方案：改用 FileSystemSkillRegistry

由于官方尚未修复该 bug，为了不影响线上功能正常使用，我采用了临时解决方案：将 Skill 目录存放在服务器的文件系统中，通过指定真实路径获取 Skill，对应的查找策略改用 FileSystemSkillRegistry。

修改后的核心代码如下：

/**
 * 获取技能智能体钩子。
 */
private static SkillsAgentHook getSkillsAgentHook() {

    // 注释掉原有的ClasspathSkillRegistry方式（本地可用，打包后失效）
    // SkillRegistry registry = ClasspathSkillRegistry.builder()
    //         .classpathPath("skills")
    //         .build();

    /*
      临时解决方案说明：
      spring ai alibaba 目前使用 ClasspathSkillRegistry 打包后，无法获取 Resource 下的目录
      因此修改为使用 FileSystemSkillRegistry，从文件系统真实路径获取 Skill
      相关 Issue：https://github.com/alibaba/spring-ai-alibaba/issues/4426
     */
    String skillPath = SpringUtils.getProperty("doc.skills-path");
    log.info("skillPath: {}",skillPath);

    FileSystemSkillRegistry registry = FileSystemSkillRegistry.builder()
            .projectSkillsDirectory(skillPath)
            .build();
    return SkillsAgentHook.builder()
            .skillRegistry(registry)
            .build();
}