配置总览

YAML 基础

example:
  item:
    material: DIAMOND_SWORD
    lore:
      - '<gray>第一行'
      - '<gray>第二行'

• 只用空格，不用 Tab；同层级保持相同缩进。
• 含 %、#、冒号或 MiniMessage 的复杂字符串建议加单引号。
• ID 大小写敏感，建议用小写字母、数字、下划线或连字符并保持稳定。
• { key: value } 是单行对象；[a, b] 是列表。
• # 后是注释；颜色值必须写成 '#6A4C93'。

文本格式不是全部相同

位置	格式	例子
物品名称/Lore	MiniMessage	'<aqua>长剑'
品质、词条、GUI、掉落通知	MiniMessage	'<red>{name}'
messages.yml 命令消息	传统 & 色码	'&a重载成功'

目录加载规则

• items/、qualities/、affixes/、affix-schemes/ 可拆成多个 .yml。
• 掉落表、宝石、共鸣支持多文件目录。
• 固定规则文件必须使用约定路径。
• examples/ 永不加载。

主配置 config.yml

safety:
  auto-migrate-stale-items: false
  max-affix-slots-per-item: 6

display:
  unknown-quality: '<gray>未知品质'
  show-affix-lore: true

audit:
  log-affix-modification-success: false

runtime: {}
mysql: {}
redis: {}
integrations: {}

• 自动迁移只扫描在线玩家背包的安全接触事件，不遍历离线玩家、世界掉落、漏斗或未打开容器。
• 词条槽安全上限范围 0..64，默认 6；它不是 SealAttributes 贡献数量限制。
• unknown-quality 控制缺失品质的展示，但缺失定义仍会报告。
• runtime/mysql/redis/integrations 必须保持空对象；当前版本添加字段会被拒绝。

严格校验和原子发布

SealItems 会拒绝未知字段、错误类型、越界数值、无效枚举、缺失引用、冲突 GUI 槽位、成环迁移和无效属性。比如 materail 不会被忽略，而会给出精确路径并拒绝新快照。

推荐修改流程

1. 备份。
2. 一次只改一个系统。
3. 检查缩进。
4. 用最小粒度 /si reload <目标>。
5. 阅读完整返回与控制台 issue。
6. 运行 /si health。
7. 新生成测试物品实测，不只看旧物品。
8. 测试服通过后再上正式服。

下一章开始逐项解释 物品定义。