Agent Skill 踩坑记录 | SpringBoot 打包后 Skill 加载失败问题排查与解决

在之前的开发中，我使用 ClasspathSkillRegistry 作为 Agent Skill 的查找策略，本地开发环境下调试、运行都一切正常，没有出现任何异常。

感兴趣的小伙伴可以回顾上一篇相关内容：https://www.lucaju.cn/index.php/archives/168/

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

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

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

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

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

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

排除上述常见问题后，推测可能是框架本身的兼容性问题，于是去 GitHub 上搜索相关问题，果然发现已有其他开发者遇到过相同情况，并且提交了 Issue：https://github.com/alibaba/spring-ai-alibaba/issues/4426

从 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();
}

五、后续

需要说明的是，这只是一个临时解决方案——使用该方案后，需要手动将 Skill 配置文件同步到服务器的指定路径（即配置项 doc.skills-path 对应的路径），增加了少量部署成本。

后续会持续关注官方 Issue 的修复进度，待 bug 修复后，再切换回 ClasspathSkillRegistry 方式，减少部署环节的手动操作。

也希望遇到相同问题的小伙伴，能通过这篇踩坑记录少走弯路～