跳到主要内容

JeecgBoot AI Skills 使用指南

一、什么是 Skills？​

Skills 是 JeecgBoot AI 平台的可插拔能力扩展机制。通过在指定目录中放置 Markdown 文件，就能让 AI 助手学会新的"技能"——比如自动创建 Online 表单等。

核心特点：

  • 零代码扩展 — 只需编写 Markdown 文件，无需修改 Java 代码
  • 自动触发 — AI 根据用户的问题自动匹配并激活合适的 Skill
  • 即放即用 — 将 Skill 文件夹放入 skills 目录，重启后即可生效

二、快速开始​

2.1 配置 Skills 目录​

在 application-dev.yml 中配置 skills 文件路径：

jeecg:
  ai-chat:
    skills-dir: D:\jeecg-skills              # Skills 目录（FunctionCall 函数调用模式）
    skills-shell-dir: D:\jeecg-ai-skill-shell  # Shell Skills 目录（命令行模式）

对应 Java 配置类：org.jeecg.config.AiChatConfig，属性 skillsDir 和 shellSkillsDir。

skills-dir 与 skills-shell-dir 的区别：

skills-dir（FunctionCall 函数调用模式）skills-shell-dir（Shell 命令行模式）
工作原理AI 通过 activate_skill FunctionCall 按需激活技能，再按指令执行Skill 内容直接注入系统消息，注册 run_shell_command 工具，无需 FunctionCall 激活
注册的工具activate_skill + read_skill_resourcerun_shell_command + read_skill_resource
适用场景支持 FunctionCall 的模型（推荐，大多数场景）命令行场景，或不支持 FunctionCall 的模型
技能触发方式模型根据 description 判断并主动调用 activate_skill 获取详细指令技能内容在对话开始时全量注入，模型直接按指令执行
配置目录如 D:\jeecg-skills如 D:\jeecg-ai-skill-shell

两者的 SKILL.md 编写规范相同，只是加载和触发机制不同。一般推荐使用 skills-dir（FunctionCall 模式），按需激活更高效；如果模型不支持 FunctionCall 或在命令行环境下使用，则配置 skills-shell-dir。

2.2 创建目录结构​

D:\jeecg-skills\                    # ← skills-dir 指向的根目录
├── my-first-skill\                 # 每个 Skill 是一个子文件夹
│   ├── SKILL.md                    # 【必须】Skill 定义文件（入口）
│   └── references\                 # 【可选】参考文档子目录
│       └── api-reference.md
├── another-skill\
│   └── SKILL.md
└── ...

2.3 编写 SKILL.md​

每个 SKILL.md 文件包含两部分：YAML 前置元数据 + Markdown 正文。

---
name: my-first-skill
description: Use when user asks to do something specific, or says "关键词1", "关键词2"
---

# 我的第一个 Skill

这里写 AI 需要遵循的工作流步骤...

## Step 1: 解析用户需求
从用户描述中提取关键信息...

## Step 2: 执行操作
调用xxx工具完成操作...

## Step 3: 返回结果
向用户展示操作结果...

2.4 验证是否生效​

启动项目后，在 AI 对话中输入与 Skill 触发条件匹配的问题。查看后台日志：

FunctionCall 函数调用模式（skills-dir）日志：

[Skills] skillsPath config value: 'D:\jeecg-skills'        ← 配置路径读取成功
[Skills] skillsDir set to: D:\jeecg-skills                  ← 参数设置成功
[LLMHandler] Skills loaded: 2 from D:\jeecg-skills          ← Skills 文件加载成功
[LLMHandler] Skill tool registered: activate_skill           ← 工具注册成功
[LLMHandler] Skill tool registered: read_skill_resource      ← 工具注册成功

看到以上日志说明 Skills 加载成功。如果模型成功调用了技能，还会看到：

[LLMHandler] Executing tool: activate_skill                  ← 模型主动激活技能
[LLMHandler] Executing tool: read_skill_resource             ← 模型读取参考文档（可选）

Shell 命令行模式（skills-shell-dir）日志：

[LLMHandler] Skills loaded (Shell Mode): 2 from D:\jeecg-ai-skill-shell  ← Shell Skills 加载成功
[LLMHandler] Shell skill tool registered: run_shell_command               ← Shell 命令工具注册成功

三、SKILL.md 编写规范​

3.1 YAML 前置元数据​

用 --- 包裹的 YAML 头部，定义 Skill 的身份与触发条件：

---
name: weekly-report     # Skill 唯一标识符（必须，建议用英文短横线命名）
description: 生成工作周报。触发词："写周报"、"生成周报"、"本周周报"、"帮我写周报"、"weekly report"、"工作总结"、"本周工作总结"   # 触发条件描述（必须）
---
字段必须说明
name是Skill 唯一标识符，用于工具注册和日志输出
description是触发条件，AI 根据此描述判断是否激活该 Skill

description 编写技巧：

  1. 用英文或中文写"Use when user asks to..."，描述适用场景
  2. 在后面列出中英文关键词，用引号包裹
  3. 描述具体的用户行为模式，如"先经理审批再HR审批"
  4. 越具体越好，避免与其他 Skill 产生歧义

3.2 Markdown 正文结构​

正文部分是 AI 执行该 Skill 时的"操作手册"。推荐结构：

# Skill 标题

一句话描述该 Skill 的功能。

## 前置条件（可选）
说明需要用户提供哪些信息（如本周完成的工作）。

## 交互流程

### Step 0: 判断操作类型
根据用户意图选择不同的处理分支。

### Step 1: 解析需求
从用户的自然语言描述中提取结构化信息。

### Step 2: 执行操作
调用工具完成实际操作。

### Step 3: 返回结果
向用户展示操作结果和后续建议。

## 参考文档（可选）
列出 references/ 目录中的参考文档及其用途。

3.3 引用参考文档​

将补充文档放在 Skill 文件夹的 references/ 子目录下，在 SKILL.md 中通过相对路径引用：

## 参考文档

详细的 API JSON 格式请参考 `references/api-reference.md`。

AI 可以在执行 Skill 时按需读取这些参考文档。

四、自定义 Skill 开发示例​

示例：创建一个"工作周报生成器"Skill​

这是一个不调用任何工具的纯文本 Skill，用户只需说一句话，AI 自动生成结构化周报。

目录结构：

D:\jeecg-skills\
└── weekly-report\
    └── SKILL.md

SKILL.md 完整内容：

---
name: weekly-report
description: 生成工作周报。触发词："写周报"、"生成周报"、"本周周报"、"帮我写周报"、"weekly report"、"工作总结"、"本周工作总结"
---

# 工作周报生成器

根据用户提供的工作要点，生成一份结构化的工作周报。

## 交互流程

### Step 1: 收集信息

如果用户直接提供了工作内容，跳到 Step 2。

如果用户只说"帮我写周报"没有给具体内容，则询问：

请提供以下信息，我来帮你生成周报：

1. **本周完成的工作**（列几个要点即可）
2. **遇到的问题**（可选）
3. **下周计划**（可选）

示例：完成了用户模块开发、修复了登录bug、参加了需求评审

### Step 2: 生成周报

**必须使用以下格式输出，不要省略任何部分：**

# 工作周报

**姓名**：[如用户提供则填写，否则留空]
**日期**：[本周一] ~ [本周日]
**部门**：[如用户提供则填写，否则留空]

---

## 一、本周工作完成情况

| 序号 | 工作内容 | 完成状态 | 备注 |
|------|---------|---------|------|
| 1 | [从用户要点扩写] | ✅ 已完成 | [细化说明] |
| 2 | [从用户要点扩写] | ✅ 已完成 | [细化说明] |

## 二、遇到的问题及解决方案

| 问题描述 | 解决方案 | 当前状态 |
|---------|---------|---------|
| [如用户提供] | [给出建议方案] | 已解决/进行中 |

> 如无问题，写"本周工作推进顺利，未遇到阻塞性问题。"

## 三、下周工作计划

| 序号 | 计划内容 | 优先级 | 预计完成时间 |
|------|---------|--------|------------|
| 1 | [从上下文推导或用户提供] | 高/中/低 | [日期] |

## 四、工作心得

[一段 2-3 句话的简短总结，积极正面]

### 生成规则

1. **扩写要点**：用户可能只给"做了登录功能"，你要扩写为"完成用户登录模块的开发与联调，包括账号密码登录、验证码校验等功能"
2. **语气正式**：使用正式的工作汇报语气，不要口语化
3. **下周计划**：如果用户没提供，根据本周工作合理推导（如"继续优化xx"、"进行xx的测试验收"）
4. **日期自动填充**：根据当前日期计算本周的周一和周日

测试效果：

用户输入：

帮我写周报，完成了用户模块开发、修复了登录bug、参加了需求评审

AI 自动激活 weekly-report 技能，输出格式化周报，包含工作完成情况表格、问题分析、下周计划和工作心得。

五、常见问题​

Q1: Skills 加载不生效？​

  1. 检查 application-dev.yml 中 jeecg.ai-chat.skills-dir（或 skills-shell-dir）是否配置正确
  2. 确认 skills 目录存在且包含子文件夹
  3. 确认每个子文件夹中有 SKILL.md 文件
  4. 查看后台日志是否有 [LLMHandler] Skills loaded: 输出
  5. 如果日志中有 [Skills] skillsPath is empty, skip skills loading，说明 yml 中未配置 skills-dir 或 skills-shell-dir
  6. 如果日志中有 从文件系统加载Skills失败，检查目录权限和路径格式

Q2: AI 没有调用正确的 Skill？​

  1. 检查 SKILL.md 的 description 字段是否包含足够的关键词和触发词
  2. 确保关键词覆盖中英文，以及用户可能的各种表述方式
  3. 避免多个 Skill 的 description 有过多重叠
  4. 查看日志中是否有 [LLMHandler] Executing tool: activate_skill，如果没有说明模型未触发技能调用

Q3: 如何调试 Skill 执行过程？​

后台日志中会输出以下关键信息：

[Skills] skillsPath config value: 'D:\jeecg-skills'        ← 配置读取
[Skills] skillsDir set to: D:\jeecg-skills                  ← 参数设置
[LLMHandler] Skills loaded: 2 from D:\jeecg-skills          ← 加载成功（数字为 Skill 数量）
[LLMHandler] Skill tool registered: activate_skill           ← activate_skill 工具注册
[LLMHandler] Skill tool registered: read_skill_resource      ← read_skill_resource 工具注册
[LLMHandler] Executing tool: activate_skill                  ← 模型调用了 activate_skill
[LLMHandler] Executing tool: read_skill_resource             ← 模型调用了 read_skill_resource