用途：面向 Minecraft 服务端插件开发，目标为 Paper/Bukkit/Spigot 的 JavaPlugin 行为。不适用于客户端模组或加载器 API，也不适用于纯原版数据包/命令内容。
主要能力：提供 Paper 26.3 + Java 25 与旧版 1.21.x + Java 21 的 Gradle 项目搭建示例；plugin.yml 与 paper-plugin.yml 描述符写法；JavaPlugin 主类、事件监听器（含 EventPriority 与 Cancellable）、命令执行器与 Tab 补全；调度器（含 Folia 区域线程注意事项）；Persistent Data Container；Adventure/MiniMessage 文本；YAML 配置；Vault 经济/权限集成；Paper 专有 API。附带 references/runtime-patterns.md 与 references/paper-plugin-commands.md 参考文件。
使用方式：用 Gradle 构建，依赖 compileOnly("io.papermc.paper:paper-api:26.3.build.+")，Java 25 工具链，Gradle 9.1+；构建命令 ./gradlew build，产物在 build/libs/。可用 ./scripts/validate-plugin-layout.sh --root /path/to/plugin-project 校验布局与描述符，--strict 将警告视为失败；校验器需要 Node。部署时将 JAR 复制到 server/plugins/ 并重启服务器。
适用场景：新建或维护 Paper/Bukkit/Spigot 服务端插件，处理事件、命令、配置、数据持久化与可选插件集成。
限制：Paper 为推荐目标；Bukkit 基础 API 不建议用于新插件；Folia 需专用调度 API。paper-plugin.yml 为实验性 Paper 专有格式，不是 plugin.yml 的直接替代，不使用 commands 字段或 getCommand(...)。Vault 需声明为 compileOnly 并 soft-depend，且不能假定存在兼容经济插件。Gradle 8.8 无法在 Java 25 上运行。旧版 1.21.x 项目应保留其依赖、Java 21 工具链与 api-version，除非有意迁移并验证。