从零服主实战

目标：在不安装任何联动插件的情况下，让玩家获得 200 最大生命、一把增加 25 物理攻击的结构化武器，并验证来源、战斗和持久化边界。

1. 使用默认 SQLite

保持 database.yml 的默认值：

config-version: 1
type: SQLITE
sqlite:
  file: storage/sealattributes.db
mysql:
  host: 127.0.0.1
  port: 3306
  database: sealattributes
  username: sealattributes
  password: change-me
  use-ssl: false
  allow-public-key-retrieval: false
pool:
  minimum-idle: 1
  maximum-pool-size: 1
  connection-timeout-ms: 5000
  validation-timeout-ms: 2000
  idle-timeout-ms: 600000
  maximum-lifetime-ms: 1800000
queue:
  storage-threads: 1
  capacity: 2048
timeouts:
  query-seconds: 5
  startup-seconds: 15
  preload-seconds: 15
  shutdown-seconds: 5
health-checkpoint:
  interval-seconds: 60
reconnect:
  interval-seconds: 15
migration:
  mysql-backup-confirmed: false

这是完整、可复制的默认结构。SQLite 必须保持单 worker、单连接池；相对路径不能用 .. 逃出插件目录。

2. 修改玩家基础生命

在 attributes.yml 中把 player-default 的生命改为 200，保留实体 100：

config-version: 1
base-profiles:
  player-default:
    max_health: 200.0
  entity-default:
    max_health: 100.0
attributes: {}

attributes: {} 是合法写法：22 项内置定义会使用代码默认值。保存后执行：

/sa reload

预期先收到开始消息，随后成功；失败则八份旧配置全部继续生效，不会只应用其中一半。

3. 验证生命投影

/sa inspect YourName sealattributes:max_health
/sa health YourName

inspect 的 RPG 最大生命应为 200；health 显示当前生命和 Paper 最终有效最大生命。默认 health-bar.mode: SCALED 会把客户端心条投影到 40 的刻度，不代表 RPG 上限变成 40。

若原生投影漂移，管理员执行：

/sa health repair YourName first_install_projection_check

原因必须 3～160 字符，命令会写审计日志。

4. 准备结构化测试物品

SealAttributes 不提供“生成物品”命令。可信物品插件需要把 UTF-8 JSON 写入物品 PDC sealattributes:item_attributes。规范负载：

{
  "schema": 1,
  "attributes": [
    {
      "id": "sealattributes:physical_attack",
      "operation": "ADD",
      "value": 25.0
    }
  ]
}

完整写入代码见 装备与物品数据。把物品拿在主手，执行：

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

预期：物品检查为有效；来源中出现 sealattributes:equipment/main_hand；默认 10 攻击加 25，结果为 35。把物品移走后来源撤销，结果回到 10。

5. 不借助物品测试永久来源

管理员可直接写专用 provider sealattributes_admin：

/sa source set YourName tutorial/health sealattributes:max_health ADD 50 PERMANENT first_server_tutorial

预期：命令先显示写入开始，异步落库后显示成功；生命变为 250。重登后仍存在。查看与删除：

/sa source show YourName tutorial/health
/sa source remove YourName tutorial/health tutorial_cleanup

show/remove 的 source ID 不带 provider；命令固定操作 sealattributes_admin:tutorial/health。不要拿管理员来源模拟常驻业务系统，正式职业/任务插件应使用公开 API 和自己的命名空间。

6. 战斗与诊断

让两名玩家近战一次，再执行：

/sa combat trace YourName
/sa doctor YourName

trace 仅保存内存中最近一次战斗，不写数据库，重启即失。默认权威模式不会自动混算另一个战斗插件的额外伤害。

7. 停服验收

正常停止服务器，确认 storage stopped: drained=true，然后备份整个 plugins/SealAttributes/。这证明队列在此次停服完成排空；它不证明备份已可恢复。生产上线前应在隔离副本实际恢复并登录验收。

常见错误：

• 把 JSON 直接写进 Lore：不会被 STRUCTURED 模式读取；
• 同时写规范 JSON 和扁平 PDC：整个物品输入无效；
• 把百分比写成 0.15：物品输入中的百分比使用人类百分数，15% 写 15；
• 用 /reload 替代 /sa reload：生命周期不受支持；
• 把测试探针 JAR 放进 plugins/：这些不是生产插件。