develop-minecraft-server-plugin 是面向 Minecraft Java 服务端插件开发的 Codex Skill，覆盖新项目创建、现有项目扩展、故障修复、版本迁移、第三方生态接入、测试验证和构建交付。本文档独立放在仓库根目录，供中文开发者了解 Skill 能力，不会作为 Skill 指令自动载入开发上下文。
支持的开发任务
- 从零创建 Bukkit、Spigot、Paper 或可选 Folia 插件
- 阅读并扩展 Maven、Gradle Groovy DSL、Gradle Kotlin DSL 或现有工程
- 开发命令、监听器、权限、配置、存储、定时任务和插件间集成
- 构建 Inventory GUI、可配置菜单和新版 Dialog UI
- 调试启动失败、事件异常、线程问题、配置问题和跨版本兼容问题
- 迁移旧版插件，拆分核心业务与不同服务端版本的实现
- 编译、测试、启动测试服、检查日志并交付可部署 JAR
默认版本策略
| 场景 | 默认策略 |
|---|---|
| 未指定版本 | 以 Paper 1.21 作为兼容性开发基线 |
| 当前版本资料 | 提供 Minecraft/Paper 26.2 API 参考 |
| 新版 UI | 按需使用 1.21.6+ Dialog 或目标版本实际提供的 API |
| Folia | 仅在明确需要时启用，并采用正确的实体、区域、全局和异步调度器 |
| 1.12.2 | 使用独立平台实现处理材料、物品数据、事件、文本和 Java 工具链差异 |
| 跨版本差异过大 | 优先输出独立 JAR，避免脆弱的全局反射兼容层 |
开发规划与工程边界
开始修改前，Skill 会检查项目结构、构建文件、插件描述符、Java 版本、目标 API、测试、Git 状态和现有代码约定。开发计划会覆盖：
- 目标版本与 Java 工具链
- Folia 支持决策
- 命令、权限、事件和界面
- 配置、存储和数据迁移
- 第三方插件依赖
- 模块边界与跨版本策略
- 测试范围、验收标准和风险
核心业务规则会尽量保持平台无关。Paper、Folia、1.12.2 和第三方插件调用通过小型适配器接入，避免版本判断和供应商对象扩散到业务代码。
插件 API 集成
Skill 按业务语义选择 API，而不是把所有数值都塞进同一种经济接口。| 功能 | 默认优先方案 |
|---|---|
| RPG 或自定义属性 | AttributePlus |
| 普通单货币经济 | Vault |
| 多种具名货币 | VaultUnlock |
| 点券、充值积分或高级余额 | PlayerPoints |
| 经验值、等级、饥饿度、饱和度、生命值、物品 | 独立的 Bukkit/Paper 原版数值适配器 |
| 普通权限判断 | Bukkit/Paper 权限接口 |
| 权限组、继承、上下文或临时权限 | LuckPerms API |
| 解析其他插件变量或输出本插件变量 | PlaceholderAPI |
经济操作会明确货币标识、精度、舍入、负余额、离线玩家、事务失败和补偿策略。PlayerPoints 只被视为游戏内积分账本，不会代替真实支付、退款或订单验签系统。
第三方 UI 与模型引擎
Skill 提供以下引擎的官方文档入口：- 1.12.2：龙核、龙之核心新 Wiki、龙之核心旧 Wiki、萌芽
- 高版本：PaiUI、ArcartX v2
GUI 与配置能力
- 使用 YAML 作为默认运维配置格式
- 使用标准
#编写 YAML 注释 - 为不直观的配置项提供中文说明、默认值、范围、单位和重载行为
- 使用字符矩阵和语义槽位组织可配置 Inventory GUI
- 支持显示条件、点击动作、变量、权限、冷却和版本化材料
- 将 GUI 展示层与购买、领取、传送等服务端业务动作分离
- 在适用版本中使用 Dialog UI，同时复用条件、动作和业务服务
item/block 贴图，支持 6×9 或 3×9 箱子加玩家背包、物品拖放、名称、作用、Lore、附魔、属性和 NBT 编辑，并可导出 JSON 或直接提交给 AI 的提示词。“常用”分类预置玻璃板、箭矢、屏障、结构方块、羊毛、物品展示框和绿宝石等高频物品，也支持右键收藏其他物品。只有插件确实需要可配置 GUI 时才使用该工具。当插件涉及箱子 GUI 时，Skill 会先询问是否使用编辑器。用户同意后可在 Codex 内置浏览器中直接打开；设计完成并回复确认后，Codex 可从页面读取结构化导出，无需用户手动寻找和上传下载文件。浏览器控制不可用时仍可使用下载或复制方式交接。
仓库还内置独立的 Paper Dialog UI 编辑器，面向本地 Paper 26.2 Experimental API。它覆盖通知、确认、多动作、Dialog 列表和服务器链接五种类型，以及文本/物品正文、四种输入控件、完整动作按钮和可选退出按钮。编辑器提供实时预览、物品库、撤销/重做、类型约束校验，以及中文键 YAML、JSON 和 AI 提示词导出；AI 也可通过页面桥接直接读取设计与校验结果。该导出是开发需求制品，实际 Java 代码仍需查询目标版本 API，且所有客户端响应必须在服务端重新验证。
离线 API 资料
仓库内置可全文检索的 API 源码快照：- Paper 26.2
- Paper 1.21.1
- Paper 1.21.6
- Spigot/Bukkit 1.12.2
Material 定义。查询时会锁定目标版本，避免把现代材料或方法误用于 1.12.2。配套 PowerShell 脚本支持：
- 检查现有插件项目结构和依赖
- 搜索指定版本的本地 API 源码
- 检查 YAML 中文注释
- 在明确需要时刷新 API 快照
- 生成或导入 GUI 编辑器物品资源
运行时安全
- 文件、数据库和网络阻塞操作不会放在服务端关键线程执行
- Bukkit/Paper API 只在允许的线程或 Folia 调度上下文调用
- 玩家输入、命令参数、配置、序列化数据和外部响应都会验证
- SQL 使用参数化语句并明确事务边界
- 客户端 UI 回调必须在服务端重新检查权限、余额、状态和冷却
- 插件关闭时释放任务、监听器、线程池、数据库连接和第三方挂钩
- NMS 仅在确有必要时使用，并按版本隔离
测试与验收
Skill 会根据改动风险选择并执行适当检查：- 校验插件描述符、配置文件和资源文件。
- 编译项目并运行静态检查。
- 执行单元测试和适用的 MockBukkit 测试。
- 启动匹配版本的 Paper 或 Folia 测试服。
- 检查插件启用、核心行为、日志、重载策略和关闭清理。
- 分别验证每个声明支持的 Minecraft、服务端和第三方插件版本。
- 修复缺陷后复现原问题并执行回归测试。
按需加载
Skill 使用索引按任务加载参考资料：- 普通命令或监听器任务只读取基础工作流、平台和测试规则
- RPG、属性或经济任务才读取插件 API 手册
- GUI 任务才读取 GUI 规范并按需打开可视化编辑器
- 龙核、萌芽、PaiUI 或 ArcartX 任务才打开对应外部文档链接
- Folia、多版本或 1.12.2 任务才加载相关平台策略
使用示例
代码：
使用 $develop-minecraft-server-plugin 开发一个 Paper 1.21 装备分解插件，GUI 可配置，兼容 Vault 和 PlaceholderAPI，并提供完整测试。[/BGCOLOR]
[BGCOLOR=rgb(246, 248, 250)]
代码：
使用 $develop-minecraft-server-plugin 把这个 1.12.2 RPG 插件迁移到现代 Paper，同时保留独立的旧版构建，并接入 AttributePlus。[/BGCOLOR]
[BGCOLOR=rgb(246, 248, 250)]
代码：
使用 $develop-minecraft-server-plugin 为现有插件增加 Folia 支持，检查所有调度、实体访问和数据库调用。[/BGCOLOR]
[BGCOLOR=rgb(246, 248, 250)]仓库结构
代码：
develop-minecraft-server-plugin/[/BGCOLOR]
[BGCOLOR=rgb(246, 248, 250)]├─ SKILL.md # Skill 入口与主工作流
├─ references/ # 按需加载的开发规范和 API 手册
├─ scripts/ # 检查、查询和资源维护脚本
├─ assets/api-cache/ # 离线 Paper/Bukkit API 快照
├─ assets/gui-editor/ # 可视化 GUI 编辑器
├─ assets/dialog-editor/ # 可视化 Dialog UI 编辑器
└─ agents/ # Skill 展示元数据安装与调用
将develop-minecraft-server-plugin 目录安装到 Codex 的 skills 目录，然后在任务中使用 $develop-minecraft-server-plugin，或直接提出 Bukkit、Paper、Folia、Minecraft 插件开发需求触发该 Skill。
