插件开发规范与协作流程

本页是锐界幻境服务端插件开发的统一约束。它面向自研插件、跨插件功能和维护改动；AI 读取本页后，应将这里的检查顺序、边界和验收要求作为执行规则，而不是只把它当作参考文章。

玩家可见玩法请写入玩家页面；独立插件的安装与配置资料请写入原创插件文档；合法物理效果的反作弊兼容遵循自定义物理与反作弊桥接层。

先核对事实

开始改动前，先检查项目说明、未提交改动、构建文件、插件描述文件、源码分层、现有测试、目标服务端和已安装依赖。当前代码、实际 JAR、配置快照与启动日志优先于旧手册、历史聊天和网络示例。

需要明确记录的最小事实集：

项目	必须确认的内容
目标环境	Minecraft、Paper/Leaf/Folia、Java、构建工具与最终产物
行为边界	玩家路径、命令、事件、取消规则、异常路径与明确不做的事
状态与数据	内存状态、持久化、迁移、重载和失败后的恢复方式
外部集成	已安装的依赖、硬依赖或软依赖、可降级行为与实际 API 来源
验收范围	静态检查、单元测试、测试服场景和需要实服确认的项目

不要根据旧文档猜测命令、权限、配置键、API 类名或物品标识。需要精确 API 时，先查项目本地依赖与源码；本地没有证据时，再查对应版本的官方资料或 JAR。

设计变更边界

删除数据、替换存储格式、修改公开接口、提高最低服务端版本、引入付费或封闭依赖、部署到正式服，均需先确认影响与迁移方案。普通功能改动不以此为由重复询问已知信息。

AI 执行顺序

AI 处理插件需求时按以下顺序工作。需求已明确要求直接实施时，保留简短的实施清单即可，不再设置重复的确认步骤。

1. 盘点当前项目与工作树，找出已有实现、相邻功能和真正的目标版本。
2. 将需求整理为可观察的验收条件：谁在何处执行什么操作，成功、失败与边界时分别发生什么。
3. 写出本次改动的范围、依赖、状态生命周期、配置变更、测试场景和未决问题；只有会改变架构、公开行为或数据安全的未知项才需要停下确认。
4. 先完成一条可用的纵向路径：描述文件与启动、配置、领域逻辑、命令或事件入口、必要的界面与集成、对应测试。
5. 再补齐其他平台、兼容层、异常分支和迁移，不把未验证的兼容性写成已支持。
6. 依次运行项目已有的格式、编译、静态分析与测试；再在匹配的测试服验证行为、日志、重载和停服清理。
7. 交付时列出实际改动、产物、依赖、配置或迁移、已执行的检查、未执行的运行时验收和风险。

设计与模块边界

业务规则、数据模型和判定逻辑应尽量不依赖 Bukkit、Paper 或某个第三方插件；将平台调用、命令、监听器、界面和具体集成放在窄适配层中。跨插件调用通过本项目的服务接口隔离，避免把某个供应方的对象泄漏到核心模型。

新功能按职责拆分，而不是按文件数量拆分：

• 领域层负责规则、状态转换、费用与奖励等可测试逻辑。
• 平台层负责 Paper/Leaf/Folia 调度、事件、实体、背包和消息。
• 集成层负责经济、权限、变量、属性、菜单和资源系统；每项集成都有缺失时的明确行为。
• 配置与数据层负责读取、校验、迁移、保存和面向服主的错误提示。

需要支持多个服务端版本时，先确定主目标上的完整行为，再用独立适配层实现差异。不要把版本判断散落在业务逻辑中，也不要因为编译通过就宣称跨版本、Folia 或基岩版联动可用。

生命周期、事件与并发

插件启动顺序应可追踪：建立普通对象，加载并校验配置，初始化数据与依赖，注册行为，最后宣布可用。禁用时必须释放本插件创建的任务、缓存、连接、界面状态和钩子。

所有临时玩家状态以 UUID 或等价的稳定标识管理，并明确创建、刷新、过期和清理条件。至少覆盖主动取消、死亡、传送、切换世界、下线、重载与插件禁用；不要把客户端可伪造的展示数据、Lore、PDC 或权限本身当作唯一可信状态。

遵守当前目标平台的线程约束：阻塞文件、网络和数据库工作不占用服务端线程；回到正确的玩家、实体或区域上下文后再触碰游戏状态。声明 Folia 支持时，必须为全局、区域、实体、异步、延迟和重复任务定义归属与取消方式，不能只用传统全局调度替代。

事件处理只取消本功能确实拥有的行为，避免通过宽泛取消、常驻豁免或“手持某物品”绕过其他系统。高频事件应限制分配、查询和日志量；异常状态与正常装备或技能不一致时，保守拒绝并记录管理员日志。

配置、数据与玩家资产

面向服主的配置默认使用清晰的 UTF-8 YAML。非显而易见的字段应在附近说明用途、单位、范围、默认值、副作用、可选值、是否支持重载和版本限制；YAML 注释只能使用 #。

• 发布的默认配置必须可直接启动，缺失项只补默认值，不覆盖已有玩家设置。
• 配置校验报错要指出文件、完整路径、错误值、原因、可接受范围和示例。
• 结构变化使用配置版本与前向迁移；可能造成数据损失时先备份并给出迁移说明。
• 密钥、连接信息、令牌和生产数据不得进入示例、公开文档或普通日志。
• 涉及货币、物品、背包或奖励时，检查、扣除与发放必须是同一受控流程；中途失败要能回滚或安全退出，并防止快速重复触发。

命令、界面与外部集成

命令的执行者、别名、参数、补全、错误反馈和描述文件注册必须一致。新增命令前先检查现有别名与其他插件冲突；不要只在代码中注册而遗漏描述文件或帮助信息。

菜单按所属库存和槽位职责判断交互，不只靠标题匹配。涉及玩家资产时，覆盖拖拽、Shift 点击、数字键、双击、收集到光标、副手、关闭界面、掉线、死亡、背包已满和快速连点；重复执行必须安全。

接入权限、经济、变量、属性、菜单或资源系统前，确认服务器实际安装的版本和 API。硬依赖缺失时以可操作的错误停止相关功能；软依赖缺失时只降级受影响功能。禁止照抄其他版本的类名、方法签名、权限节点或配置格式。

兼容与安全专项

合法移速、鞘翅加速、碰撞箱变化等物理效果，不得通过关闭反作弊分类或发放全局 bypass 解决。产生效果的插件必须维护短时、可清理的服务端合法状态，并只桥接严格匹配的低层违规。完整规则、日志字段和验收矩阵见自定义物理与反作弊桥接层。

不要将玩家页、插件开发页和管理资料混在一起：玩家页面说明用途、操作与风险；开发者页面说明接口、状态、配置和验收；仅供维护的密钥、内部地址、后台操作与故障记录不进入公开页面。

验证与交付

验证从低成本检查逐级推进，上一层通过不等于下一层已证明。

层级	至少验证什么	不能证明什么
静态	描述文件、YAML、编译、格式、静态分析和现有测试	服务端实际加载、事件时序和第三方联动
单元与模拟	领域规则、解析、迁移、映射、费用和失败回滚	新版 API、Folia 调度或真实客户端行为
测试服	首次启动、命令、事件、重载、重启、日志、异常路径和禁用清理	正式服负载、真实经济和长期兼容性
实服验收	目标玩家路径、跨插件联动、Java/基岩差异、性能与监控	后续版本更新后的持续有效性

每个声称支持的产物与服务端组合都要有独立记录：Java、服务端构建、依赖、配置样例、执行命令、场景和结果。不要用 Paper 测试代替 Folia 或旧版本测试，也不要用 MockBukkit 结果证明它不覆盖的现代 API。

交付报告至少说明：改动文件与产物、目标环境、必需与可选依赖、配置和迁移、命令或接口变化、实际运行的检查、已修复的问题、尚未验证的场景与服主需要完成的动作。只有在目标服务器上实际启用并走完对应路径，才能写“已验收”。

团队协作阶段

阶段	目标	完成条件
A. 设计	明确玩法、价值、边界与验收	可观察的需求与排除项已记录
B. 评审	处理平衡、兼容、数据与维护风险	影响范围、依赖和迁移方案已确认
C. 实现	按模块边界完成可用纵向路径	代码、配置、资源和文档同步更新
D. 验收	验证正常、异常、重载与联动路径	对应检查和测试服证据齐全
E. 发布	部署、观察并维护玩家说明	正式服结果与后续待办已记录

上线后若发现严重缺陷、平衡问题或兼容变化，应回到评审或实现阶段，而不是只修改玩家文案掩盖问题。

参考来源

本文吸收并适配了 develop-minecraft-server-plugin-skill 的工程纪律：先检查证据、明确平台与依赖边界、分层实现、按风险验证并以事实交付。本站以锐界幻境当前项目和服务端环境为准，不直接复制外部示例或默认版本假设。