Spring AI Lab v0.3.0新增Skill系统，提示词即插即用

前言

Spring AI Lab 是一个基于 Spring AI 的 AI 应用快速开发工具箱，它的定位很明确：把对话、RAG、多 Agent、代码审查这些常见场景，封装成即插即用的 Spring Boot Starter。

这次 v0.3.0 版本带来的核心变化是 Skill 系统——一套让 AI 系统提示词可以随时插拔、热更新、甚至运行时管理的完整方案。这东西解决了一个很实际的痛点：提示词别再跟代码耦合到一起了。

什么是 Skill 系统

说白了，Skill 就是把一段 AI 的角色设定、行为规范和领域知识，打包成一个独立的 `.md` 文件。框架会在用户对话时自动匹配相关的 Skill，然后把对应的系统提示词注入到对话上下文中。整个过程不需要硬编码，不需要手动拼接 Prompt，文件写好往里一丢就行。

一个 Skill 文件长这样（YAML Frontmatter + Markdown）：

---
name: weather-assistant
displayName: 天气助手
description: 提供天气查询、天气预报、气象知识和穿衣建议
category: utility
priority: 5
tags: [天气, 气象, 温度, 出行]
model:
  temperature: 0.3
  maxTokens: 1024
---
# 角色
你是一个专业的天气查询助手...

## 能力范围
- 查询指定城市的实时天气状况
- 提供未来 3-7 天的天气预报

## 约束
- 只回答天气相关问题

这就是一个完整的 Skill 定义。框架自动加载、自动匹配、自动注入，开发者只需要关心内容本身。

核心特性

一、多源加载（三层优先级）

Skill 支持三种来源，按优先级从高到低自动覆盖。逻辑很直观：

① REST API 动态注册（运行时，最高优先级）
    ↓ 覆盖
② 外部文件目录（文件系统，可读写）
    ↓ 覆盖
③ classpath 内置（JAR 内，兜底默认）

同名 Skill 会按优先级覆盖，这意味着：JAR 里自带的 Skill 能保证“开箱即用”，外部目录的 Skill 可以随时增删改，REST API 则适合程序化动态管理。三层结构，兼顾了稳定性与灵活性。

二、外部目录 + 热加载

配置起来很简单：

spring:
  ai:
    lab:
      skill:
        external-dir: /opt/myapp/custom-skills
        hot-reload: true

之后在 `/opt/myapp/custom-skills/` 目录下，你可以直接操作：

# 新增 Skill
vi /opt/myapp/custom-skills/translator.md

# 修改提示词
vi /opt/myapp/custom-skills/weather-assistant.md

# 删除 Skill
rm /opt/myapp/custom-skills/old-skill.md

框架通过 Java 的 `WatchService` 监听文件变更，修改即时生效，不用重启应用。对于生产环境来说，这个特性非常实用——线上调整提示词不需要停机部署。

三、自动初始化

首次部署到生产环境时，外部目录往往是空的。框架提供了一个 `auto-init` 选项：

spring:
  ai:
    lab:
      skill:
        external-dir: /opt/myapp/custom-skills
        auto-init: true

启动时，框架会自动把 JAR 内置的 3 个 Skill 复制到外部目录。之后你直接编辑这些文件就行，不用手动搬运。

四、REST API 管理端点

开启 `enable-management: true` 后，会暴露完整的 CRUD 接口：

spring:
  ai:
    lab:
      skill:
        enable-management: true

方法	路径	说明
GET	`/api/skills`	列出所有 Skill
GET	`/api/skills/{name}`	查看 Skill 详情（含正文）
POST	`/api/skills/{name}`	创建或更新 Skill
DELETE	`/api/skills/{name}`	删除外部 Skill
POST	`/api/skills/reload`	全量重新加载

举个例子，通过接口创建一个新 Skill：

curl -X POST http://localhost:8080/api/skills/translator \
-H "Content-Type: text/plain" \
-d '---
name: translator
displayName: 翻译助手
description: 中英文互译专家
category: utility
priority: 3
---
# 角色
你是一个专业的翻译助手，擅长中英文互译。翻译时保持原文语气和风格。'

文件会自动写入外部目录，Skill 即刻生效。整个过程完全通过 API 完成，适合集成到自动化运维流程中。

完整配置参考

下面是一份完整的配置清单，覆盖了所有关键选项：

spring:
  ai:
    lab:
      skill:
        enabled: true               # 启用 Skill 系统
        directory: skills           # 内置 Skill classpath 路径
        external-dir: ./custom-skills # 外部可写目录
        auto-init: true             # 首次自动种子化内置 Skill
        enable-management: false    # REST API 管理（按需开启）
        hot-reload: true            # 监听文件变更自动刷新
        routing-strategy: semantic  # 路由策略：semantic / keyword / llm
        similarity-threshold: 0.1   # 语义匹配相似度阈值（0-1）
        max-matched-skills: 3       # 每次请求最多匹配的 Skill 数

实现要点

SkillLoader 多源加载逻辑

核心加载类 `SkillLoader` 的 `load()` 方法，执行逻辑其实很简单，就几步：

1. 如果配置了 `externalDir`，先初始化外部目录（自动创建 + 可选种子化）
2. 加载外部目录的 Skill（高优先级）
3. 加载 classpath 内置 Skill 作为兜底（仅注册外部不存在的同名 Skill）
4. 如果开启了热加载，启动 `WatchService` 监听文件变更

文件监听

通过 `java.nio.file.WatchService` 监听外部目录的 `ENTRY_CREATE`、`ENTRY_MODIFY`、`ENTRY_DELETE` 事件，加上 200ms 防抖处理，保证了变更的及时响应。

安全管理

REST API 的路径参数做了 `Path.normalize()` + `startsWith()` 校验，有效防止路径穿越攻击。这一点在开放管理接口时很重要。

向后兼容

这一点要特别提一下：完全向后兼容。如果你不配置 `external-dir`，行为跟之前版本一模一样，只从 `directory` 加载 Skill。升级到 v0.3.0 不用担心旧配置出问题。

测试验证

全部 42 个单元测试通过，零 lint 错误。代码质量这块不用操心。

---

结语

这个项目的初衷一直没有变：让 AI 能力接入 Java 应用，变得像加一个 Spring Boot Starter 一样简单。

从零搭建一个具备对话记忆、多模型路由、容错降级、可观测性的 AI 应用，至少需要一两周时间。但用 Spring AI Lab，引入依赖、配好 Key 就搞定了。v0.3.0 的 Skill 系统进一步把提示词管理从代码中解放出来，让 AI 的“人设”和“知识”可以独立迭代。

项目地址：

• Gitee：https://gitee.com/sjz_zy/spring-ai-lab
• GitHub：https://github.com/Ziye-0911/spring-ai-lab