FancyHelper Skill 开发指南

什么是 Skill？

Skill 是 FancyHelper 的知识模块系统。每个 Skill 就是一个 Markdown 文件，里面写明了某个插件或功能的用法指南。AI 在对话中会根据玩家说的话自动匹配、加载对应的 Skill，从而获得专业知识来更好地帮助玩家。

简单来说：写一个 Skill = 教会 AI 一个插件怎么用。

Skill 文件结构

每个 Skill 由两部分组成：YAML Front Matter（元数据） + Markdown 正文（知识内容）。

文件位置

Skill 文件存放在 plugins/FancyHelper/skills/ 目录下，支持两种组织方式：

skills/
├── worldedit/          # 目录格式（推荐，支持远程更新）
│   └── skill.md
├── luckperms/
│   └── skill.md
├── my-skill.md         # 扁平格式（也支持，但不能远程更新）

完整示例

以下是一个标准 Skill 文件的完整结构（以 EssentialsX 为例）：

---
name: "essentialsx"
description: "EssentialsX 基础插件使用指南，涵盖传送、经济、聊天、管理等功能"
triggers:
  - "essentialsx"
  - "essentials"
  - "ess"
  - "传送"
  - "home"
  - "warp"
  - "spawn"
  - "tpa"
  - "经济"
  - "money"
  - "kit"
  - "礼包"
auto_trigger: true
source: "essentialsx"
author: "FancyHelper Team"
version: "1.1.0"
categories:
  - "plugin"
  - "teleport"
  - "economy"
---

# EssentialsX 使用指南

## 插件检查

在使用以下命令前，请先检查服务器是否已安装 EssentialsX 插件。
检查方法：尝试执行 `/essentials version` 命令...
(正文内容省略)

YAML Front Matter 字段详解

必填字段

触发词字段

元数据字段

模板变量字段

variables 使用示例：

variables:
  plugin_name: "MyPlugin"
  config_path: "plugins/MyPlugin/config.yml"

正文中：

请检查 `{{config_path}}` 文件来确认 {{plugin_name}} 的配置。

加载后 {{config_path}} 会被替换为 plugins/MyPlugin/config.yml。

内置模板变量

以下变量无需在 YAML 中定义，系统会自动提供：

触发词设计指南

触发词是 Skill 能否被正确加载的关键。设计原则：

1. 覆盖全面但不泛滥

# 好的触发词设计 — 覆盖插件的常见叫法和相关概念
triggers:
  - "worldedit"      # 插件本名
  - "we"             # 常用缩写
  - "创世神"          # 中文俗称
  - "//set"          # 插件特有命令前缀
  - "//copy"         # 高频使用的命令
  - "选区"            # 核心概念
  - "快速建筑"         # 使用场景

2. 避免过于通用的触发词

# 差 — 太通用了，会误匹配
triggers:
  - "命令"     # 几乎所有对话都可能提到
  - "帮助"     # 太泛
  - "插件"     # 太泛
  - "玩家"     # 太泛

# 好 — 具体、有区分度
triggers:
  - "lp"              # 插件特有简称
  - "权限组"           # 领域概念
  - "permission"      # 英文关键词
  - "lp editor"       # 特有功能

3. 中英文双语覆盖

Minecraft 玩家群体中英文混用很常见，同时覆盖两种语言的触发词：

triggers:
  - "传送"
  - "teleport"
  - "tp"
  - "home"
  - "warp"
  - "地标"

4. 匹配评分机制

AI 匹配触发词时的评分规则：

最终分数 = 基础分 × 权重(%) ÷ 100，然后乘以优先级加成。只有得分 ≥ 30 的才可能被匹配。

正文写作指南

核心原则

正文是给 AI 看的知识库。写清楚"AI 应该知道什么"，而不是"玩家应该知道什么"。

1. 开头：插件检查

每个 Skill 开头应该告诉 AI 如何检查这个插件是否存在：

## 插件检查

在使用以下命令前，请先检查服务器是否已安装 XXX 插件。

检查方法：尝试执行 `/xxx version` 命令，如果返回版本信息则说明插件已安装。

如果插件未安装，请告知玩家 XXX 命令不可用，改用 YYY 替代。

2. 权限说明

写明权限节点格式，AI 才能在帮玩家排查权限问题时给出正确建议：

## 权限规则

XXX 的权限节点遵循固定格式：
- 命令权限：`xxx.command.<命令名>`
- 管理权限：`xxx.admin`

**默认玩家没有任何命令权限**，需要管理员通过 LuckPerms 授予。

3. 命令参考

使用表格整理命令，清晰易读：

## 常用命令

### 传送
| 命令 | 说明 |
|------|------|
| `/home [名称]` | 传送到家 |
| `/sethome [名称]` | 设置家 |
| `/warp <名称>` | 传送到地标 |
| `/tpa <玩家>` | 请求传送到玩家 |

4. 命令示例

给 AI 提供可直接使用的命令模板：

## 常用示例

### 查询玩家权限
/lp user <玩家> permission info

### 授予权限
/lp user <玩家> permission set <节点> true

### 回档玩家操作
/co rollback u:<玩家> t:1h r:20

5. 参数说明

如果命令有复杂的参数语法，详细列出来：

## 参数说明

### 时间参数 `t:`
- `t:10s` - 10秒内
- `t:5m` - 5分钟内
- `t:2h` - 2小时内
- `t:1d` - 1天内
- `t:1w` - 1周内

6. 注意事项

收尾写好坑和限制，避免 AI 给出错误建议：

## 注意事项

1. 回档操作不可自动撤销，请务必确认参数正确
2. 大范围操作可能影响服务器性能
3. 和 EssentialsX 功能重叠，二选一安装即可
4. 权限节点区分大小写

Skill 开发完整流程

第一步：确定 Skill 主题

一个好的 Skill 主题应该：

• 是一个具体的插件或功能（不是泛泛的"Minecraft 教程"）

• 有明确的命令/操作需要记忆

• 你（作为作者）对该主题有足够的了解

适合做 Skill 的主题举例：

• 某个插件的使用指南（AuthMe、GriefPrevention、Dynmap...）

• 某种命令的格式指南（tellraw、title、scoreboard...）

• 某种建筑/红石预设（自动建造、电梯、农场...）

第二步：撰写 Skill 文件

1. 创建目录 skills/<skill-id>/，在其中创建 skill.md

2. skill-id 使用小写英文 + 连字符，如 authme、grief-prevention

3. 填写 YAML Front Matter（参考上面的字段说明）

4. 撰写正文（参考上面的写作指南）

第三步：本地测试

1. 将 skill.md 放到服务器的 plugins/FancyHelper/skills/<skill-id>/skill.md

2. 在游戏内执行 /fancy skill reload 重新加载

3. 执行 /fancy skill list 确认 Skill 已加载

4. 进入 CLI 模式（/cli），说和这个 Skill 相关的话，看 AI 是否自动加载

5. 也可以手动加载测试：/fancy skill load <skill-id>

第四步：测试清单

• [ ] Skill 能正确加载（/fancy skill list 中出现）

• [ ] 触发词能正确匹配（说相关话题时 AI 自动加载）

• [ ] AI 给出的命令是正确的

• [ ] 不存在和其他 Skill 的触发词严重冲突

• [ ] 版本信息、命令语法与实际插件版本一致

通过 PR 贡献 Skill

FancyHelper 的 Skill 通过 FancySkillMarket 仓库分发给所有用户。把你的 Skill 贡献到这个仓库，就能让所有 FancyHelper 用户自动获取。

仓库结构

FancySkillMarket/
├── manifest.json          # Skill 版本清单
├── worldedit/
│   └── skill.md
├── luckperms/
│   └── skill.md
├── cmi/
│   └── skill.md
└── your-skill/           # 你新建的 Skill 目录
    └── skill.md

贡献步骤

1. Fork 仓库

访问 FancySkillMarket 并 Fork 到你的 GitHub 账号下。

2. 创建 Skill 目录和文件

git clone https://github.com/<你的用户名>/FancySkillMarket.git
cd FancySkillMarket

# 创建你的 Skill（以 authme 为例）
mkdir authme
# 将写好的 skill.md 放到 authme/ 目录下

目录名 = Skill ID（就是 skill.md 所在目录的名字）。确保 YAML 中的 source 字段与目录名一致：

source: "authme"   # 必须和目录名一致

3. 更新 manifest.json

在 manifest.json 的 skills 对象中添加你的 Skill：

{
  "skills": {
    "worldedit": { "version": "1.1.0" },
    "luckperms": { "version": "1.1.0" },
    "authme": { "version": "1.0.0" }
  }
}

键名 = 目录名，version = 你的 Skill 版本号。必须和 skill.md 的 YAML Front Matter 中的 version 字段保持完全一致。

4. 提交 PR

git add authme/ manifest.json
git commit -m "feat: add AuthMe skill"
git push origin main

然后在 GitHub 上创建 Pull Request 到 baicaizhale/FancySkillMarket 的 main 分支。

5. PR 标题格式

推荐格式：feat: add <Skill名称> skill

例如：

• feat: add AuthMe skill

• feat: add GriefPrevention skill

• fix: update LuckPerms commands for v5.4

PR 审核标准

提交 PR 前，确认以下几点：

• [ ] skill.md 文件放在以 Skill ID 命名的目录下（如 authme/skill.md）

• [ ] YAML Front Matter 格式正确，所有必填字段完整

• [ ] source 字段与目录名一致

• [ ] 触发词设置合理，不会过于宽泛导致误匹配

• [ ] 正文内容准确，命令语法正确

• [ ] 包含插件检查方式（如何验证插件是否安装）

• [ ] 包含权限节点说明（如果适用）

• [ ] 包含常见使用示例

• [ ] manifest.json 已更新，版本号与 skill.md 一致

• [ ] 版本号遵循语义化版本（major.minor.patch）

• [ ] 不同时包含两个功能高度重叠的插件 Skill（如 CMI 和 EssentialsX 都有了，就不需要再提交一个功能相同的）

更新已有 Skill

如果某个 Skill 的内容需要更新（插件新版改了命令、补充遗漏、修正错误等）：

1. 修改对应的 skill.md 文件

2. 递增版本号（skill.md 的 version 字段 + manifest.json 的 version 字段，两处都要改）

3. 提交 PR

FancyHelper 会在启动时、管理员进服时自动检查 manifest 中的版本号，发现本地版本与远程不同就会自动下载更新。

版本号规范

采用语义化版本（SemVer）：主版本.次版本.修订版本

注意：只要改了 skill.md 的内容，就一定要递增版本号。版本号不变的话，已安装的用户不会收到更新。

常见问题

Q: 我的 Skill 不自动触发怎么办？

1. 检查 auto_trigger 是否为 true

2. 检查触发词是否太偏 — 用 /fancy skill info <id> 查看触发词列表，在 CLI 对话中测试

3. 检查 priority 是否太低 — 如果同时有其他 Skill 匹配，高优先级的会胜出

4. 检查匹配分数 — 只有 ≥ 30 分才会被匹配

Q: 本地 Skill 和远程 Skill 冲突了怎么办？

FancyHelper 加载优先级：后加载的 > 先加载的。如果本地 skills/<id>.md 和远程下载的 skills/<id>/skill.md 同时存在，后加载的会覆盖前者。建议统一使用目录格式。

Q: 怎么调试 Skill 是否被正确解析？

在 config.yml 中设置 settings.debug: true，重载插件后控制台会输出每个 Skill 的注册信息。

Q: Skill 的 ID 有什么命名规范？

• 全部小写

• 只允许字母、数字、下划线和连字符

• 建议和插件/功能名保持一致

• 示例：authme、grief-prevention、dynmap

Q: 可以在 Skill 正文中用图片吗？

不建议。Skill 是给 AI 阅读的纯文本知识库，AI 无法查看图片。用文字、表格、代码块来表达。