Spring AI Lab v0.3.0 新增 Skill 系统：AI 提示词即插即用
版本亮点：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()` 方法，执行逻辑简洁清晰，共几步：
- 如果配置了 `externalDir`，先初始化外部目录（自动创建 + 可选种子化）
- 加载外部目录的 Skill（高优先级）
- 加载 classpath 内置 Skill 作为兜底（仅注册外部不存在的同名 Skill）
- 如果开启了热加载，启动 `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