故障排查

通用五步法

1. 停止重复操作，保留现场。
2. 找控制台最早的一条 SealItems 错误，不只看最后一行。
3. 执行 /si health。
4. 缩小到一个配置文件、一个物品、一个玩家和一个操作。
5. 在测试服修复并重载；不要在正式服用随机改法试错。

配置重载失败

检查 issue 中的完整 path。常见原因：未知字段、Tab 缩进、数字写成文本、概率没加引号、引用 ID 不存在、GUI 槽位冲突、属性 operation 无效、迁移成环。

失败后旧快照通常仍在使用，所以“玩家还可以用旧配置”不是新配置成功。修复后再次 reload，并用 /si health 核对计数/快照。

/si give 找不到物品

• 文件是否在 items/ 而非 examples/。
• /si reload items 是否成功。
• /si list 是否出现 ID。
• ID 大小写是否一致。
• 是否因为其他交叉引用错误导致整批候选未发布。

物品显示为 PROTECTED

/si inspect 查看 reason。典型原因：不支持 schema、ID/指纹/UUID/revision 损坏、当前配置已删除该物品、stackable/individual 身份矛盾、状态 codec 损坏。先备份和定位来源，不要 NBT 编辑器“补字段”。

属性不生效

检查 SealAttributes 插件、API writable、属性 ID/operation、装备槽、未鉴定状态、宝石 equipped 限制和定义过期。详见 SealAttributes 联动。

鉴定/改造/宝石命令打不开

• 玩家是否有对应权限。
• 规则总开关和逐物品规则是否启用。
• GUI 快照是否 published。
• provider: arcartx 时玩家资源是否就绪。
• 输入物品是否是 READY individual。
• 未鉴定策略是否禁止操作。

先临时用 provider: vanilla 区分“业务问题”和“ArcartX 前端问题”。

费用不足但看起来材料一样

SealItems 费用只接受正确稳定 ID 的 SealItems 材料。普通 PAPER、同名物品或另一个插件的相同材质都不算。手持材料用 /si inspect。

Vault/PlayerPoints 冻结

这表示扣费事实不确定或 provider 身份变化，是安全保护。保留审计信息，核对经济流水，修复 provider 后成功重载相关规则，再从 /si health 确认恢复。不要让玩家反复点击。

掉落不触发

把规则触发概率临时设 '100%'；确认总/vanilla 开关、世界、实体、spawn reason、table ID。命令生成实体可能不满足 NATURAL。测试成功后恢复概率。

ArcartX 还是旧界面

检查 plugins/ArcartX/ui/*.new；SealItems 不覆盖自定义模板。比较合并后执行对应 GUI reload。还要确认玩家资源包真的重新加载。

IDEA 一堆红，但命令行能构建

1. IDEA 选择项目 Gradle Wrapper 和 JDK 21。
2. 重新加载 Gradle Project，而不是只重启编辑器。
3. 检查 Gradle Sync/Build 工具窗口第一处依赖错误。
4. 保留仓库的 dependency locks 与 verification metadata。
5. 运行 ./gradlew clean check --rerun-tasks；CLI 成功只证明构建，IDEA 仍红时要修复 IDE 模型/索引/同步。

详见 构建、IDEA 与贡献。

报告问题模板

服务端核心/版本：
Java 版本：
SealItems 版本或 commit：
SealAttributes/Vault/PlayerPoints/MythicMobs/ArcartX 版本：
复现步骤：
期望结果：
实际结果：
/si health：
第一条完整错误与 Caused by：
相关 YAML（删去密码/密钥）：
是否能在干净测试服复现：