SealItems 联动实战

联动目标是让 SealItems 成为装备属性的唯一发布者，SealAttributes 只负责聚合与结算。完整 SealItems 内容侧配置见 SealItems：SealAttributes 联动。

正确来源契约

SealItems 使用 provider sealitems，发布七个稳定来源：

sealitems:equipment/main_hand
sealitems:equipment/off_hand
sealitems:equipment/head
sealitems:equipment/chest
sealitems:equipment/legs
sealitems:equipment/feet
sealitems:equipment/resonance

六个槽各自是该槽全部安全属性组件的完整快照；跨槽套装/宝石共鸣只进入 resonance。不要截断、分片或按“暴击/生命”等玩法再拆来源。

切换步骤

1. 在测试服确认 SealItems 构建确实支持当前 SealAttributes API baseline。
2. 正常停服，确认 storage drained，并备份两个插件目录和数据库。
3. 编辑 sources.yml：

config-version: 1
built-in-equipment-reader:
  enabled: false
item-mode: STRUCTURED
equipment-slots: [MAIN_HAND, OFF_HAND, HEAD, CHEST, LEGS, FEET]
structured:
  schema-version: 1
  pdc-key: sealattributes:item_attributes
lore:
  formats:
    number: ["{name} {value}"]
    percent: ["{name} {value}%"]
  aliases: {}
  templates: []

4. 安装双方正式运行 JAR，完整启动；不能先启动内置读取器再热关。
5. 登录并依次执行：

/sa doctor YourName
/sa sources YourName
/sa inspect YourName sealattributes:physical_attack

6. 装备/卸下主副手与四件护甲，替换带孔物品，触发共鸣变化；每次确认对应来源修订递增且旧贡献消失。
7. 重登、重启、正常停服，验证永久业务来源和资源没有被装备重建误删。

避免双算

错误状态的明显证据：同一玩家同时出现

sealattributes:equipment/main_hand
sealitems:equipment/main_hand

这会把一件装备计算两遍。立即停止业务流量，完整停服，确认内置 reader 为 false，再启动。provider 已绑定后尝试热切换会被 SealAttributes 拒绝整次重载，这是防止短暂双写的设计。

属性归属

• SealItems 负责物品身份、词条、品质、孔位、宝石和共鸣计算；
• SealAttributes 负责接收最终安全贡献、聚合、战斗和展示；
• SealItems 不应读取玩家显示 Lore 后重新解释数值；
• SealAttributes 不会理解 SealItems 的物品内部业务结构，只接受 SourceSnapshot。

当前 SealAttributes 能接收任意合法 sealitems:* 来源，但这不自动证明某个 SealItems 版本已经实现宝石到来源的完整发布链。必须用实际 SealItems 构建验收 sockets/resonance，不要把 PDC 中“存在宝石”当成“属性已发布”。

验收矩阵

动作	应观察到的结果
装主手	仅 sealitems:equipment/main_hand 出现/修订增加
换另一把主手	同键整体替换，无旧属性残留
卸下主手	同键撤销
换头盔	只影响 head 与可能的 resonance
宝石/共鸣改变	槽来源和/或 resonance 按 SealItems 契约变化
/sa refresh	不负责刷新 SealItems 来源
SealItems API gate 明确 false	发布被 fail closed 拒绝
gate 异常/未知	同样拒绝，不猜测允许

排错顺序

1. SealItems 自己是否生成了正确最终组件；
2. /sa sources 是否出现对应 sealitems:* 键和新修订；
3. /sa inspect 聚合是否正确；
4. combat trace 是否用到预期快照；
5. 是否同时存在内置 sealattributes:equipment/*；
6. 是否超过单快照 512 贡献或单主体 256 来源。

不要通过反复重载掩盖 owner epoch 或依赖顺序问题；停服后用双方确定版本进行干净启动。