安装与第一次启动

1. 放置 JAR

1. 正常停止服务器，不要在运行中覆盖插件 JAR。
2. 把 SealItems-<版本>.jar 放进服务端的 plugins/。
3. 把需要的软依赖也放进 plugins/。
4. 启动服务器，等待控制台出现服务端 Done。

典型目录：

server/
├─ paper-1.21.x.jar
├─ plugins/
│  ├─ SealItems-0.1.0-SNAPSHOT.jar
│  ├─ SealAttributes.jar        # 可选
│  ├─ Vault.jar                 # 可选
│  ├─ PlayerPoints.jar          # 可选
│  ├─ MythicMobs.jar            # 可选
│  ├─ ArcartX.jar               # 可选
│  └─ SealItems/                # 首次启动后生成
└─ world/

2. 第一次启动后的目录

plugins/SealItems/
├─ config.yml
├─ messages.yml
├─ items/
├─ qualities/
├─ affixes/
├─ affix-schemes/
└─ gameplay/
   ├─ identification/{rules.yml,gui.yml}
   ├─ affix-modification/{rules.yml,gui.yml}
   ├─ loot/{rules.yml,messages.yml,tables/}
   └─ sockets/
      ├─ settings.yml
      ├─ socket-types.yml
      ├─ profiles.yml
      ├─ operations.yml
      ├─ limit-profiles.yml
      ├─ migrations.yml
      ├─ gui.yml
      ├─ gems/
      └─ resonances/

仓库/JAR 内的 examples/complete/ 只是示例，不会自动加载。必须把文件复制到正式目录才会生效。

3. 判断启动是否成功

进入服务器或控制台执行：

/si health

重点检查：runtime 是否 READY；主配置和物品定义是否 published；定义数量是否符合预期；安装 SealAttributes 时联动是否 writable；经济 provider 是否匹配或被冻结；玩法规则与 GUI 是否发布。

插件可能进入“只读诊断”而不让服务端崩溃。此时先修复控制台报告，不要给玩家发装备。

4. 最小启动验证

第一次不要马上启用所有玩法。先创建 第一个物品，然后：

/si reload items
/si list
/si give 你的玩家名 tutorial_token 1
/si inspect

5. ArcartX 首次安装

若安装 ArcartX，SealItems 会把三套模板安装到 plugins/ArcartX/ui/。不会覆盖已有同名模板；版本变化时可能生成 .new 文件。看到 .new 代表需要比较并手工合并，详见 GUI 与 ArcartX。

6. 安装失败快速判断

现象	首查
UnsupportedClassVersionError	服务端实际 Java 不是 21
插件列表没有 SealItems	JAR 路径、完整性、启动日志第一处错误
SealItems 只读	/si health 和第一条配置 issue
属性不生效	SealAttributes 是否安装、API 是否 writable、属性 ID 是否存在
GUI 命令拒绝	玩法是否启用、GUI 是否 published、权限是否存在
ArcartX 不显示	provider、版本、玩家资源就绪、.new 是否待合并

更完整流程见 故障排查。