审计与签名

锻造成功后会往成品物品里写入哪些追溯数据, 它们存在哪里, 以及它们和物品刷新之间的关系

锻造成功后, Forge 会往结果物品里写入审计数据, 用来追溯锻造来源, 并验证物品有没有被篡改

数据落在哪里

锻造审计数据同时存在于两个地方:

CoreLib 物品层快照: namespace 为 forge, layer version 为 1, payload 就是下面的审计字段表. 刷新物品时从这里读回
emakiforge:forge PDC 分区: 把关键字段压成扁平的键, 供占位符和变量系统读取. 见锻造层 PDC 键

审计字段

锻造完成后, 下面这些字段会写进审计 payload:

字段	说明
`schema`	审计结构的标识, 当前固定是 `forge_audit_v2`
`schema_version`	审计结构版本, 当前为 `2`
`stage`	来源阶段, 当前固定为 `forge`
`recipe_id`	使用的配方 ID
`quality`	品质等级名称; 品质没解析出来时是空字符串
`multiplier`	品质倍率
`forged_at`	锻造时间戳 (毫秒)
`materials_signature`	材料贡献数据算出来的一段哈希签名
`output_item`	输出物品来源的简写. 只有配方配置了输出物品来源时才写入
`materials`	材料贡献列表, 见下表

materials[] 每个条目的字段:

字段	说明
`material_id` / `count_key` / `audit_id`	材料的身份键. 只有配置里显式声明过才写入; 没声明时这个键会被移除
`material_item`	兼容身份: 物品源简写, 或 `matcher:<摘要>`
`category`	材料分类 (必需还是可选)
`amount`	计划投入的数量
`amount_consumed`	实际消耗的数量
`slot`	材料所在的界面槽位
`sequence`	处理顺序
`matched_source`	实际匹配到的物品源简写
`matcher`	matcher 的摘要键; 没有 matcher 时是空字符串
`allocation`	这一条材料在各个槽位上的分配明细
`legacy_identity` / `identity_diagnostic`	当有身份键没显式声明时, 补充的兼容身份和诊断标记

材料签名

materials_signature 只对实际消耗量大于 0 的材料贡献计算哈希签名. 算签名时用到的输入包括材料定义摘要, 数量, 消耗量, 槽位, 分类, 顺序, 匹配来源和分配明细. 相同的材料贡献组合总是得到相同的签名, 所以可以用它来比对物品的锻造材料数据和自己预期的是不是一致

锻造层 PDC 键

命名空间 emakiforge, 分区 forge 下的扁平键:

键	类型	说明
`forge_recipe_id`	string	锻造出这个物品用的配方 ID
`quality_id`	string	品质 ID (与品质名同值)
`quality_display`	string	品质显示名
`quality_multiplier`	string	品质倍率, 按 `0.##` 格式化之后存进去
`material_id`	string	显式声明过的 `material_id` 列表, 用逗号连在一起; 没有就移除这个键
`count_key`	string	显式声明过的 `count_key` 列表, 用逗号连在一起; 没有就移除这个键
`audit_id`	string	显式声明过的 `audit_id` 列表, 用逗号连在一起; 没有就移除这个键
`matched_source`	string	匹配到的来源简写列表, 用逗号连在一起
`amount_consumed`	integer	全部材料实际消耗量加起来的总数
`matcher_digest`	string	matcher 摘要列表, 用逗号连在一起
`allocation`	string	分配明细算出来的一段签名

这些键会被 CoreLib 变量系统读取为 forge_quality_id, forge_quality_display, forge_quality_multiplier, forge_recipe_id 四个变量

与刷新的关系

Forge 的物品刷新服务会读审计数据里的 recipe_id 和 quality, 照着它们重建锻造层的展示. 审计数据缺失, 品质已经不在当前品质池里, 或者配方已经被删掉时, 这件物品就无法重建锻造层展示, 并且会打一条警告

读材料审计记录时, 现在的实现按 audit_id → material_id → count_key → 旧 material_item / source 的顺序逐个尝试. 用旧身份成功解析出来之后, 会标记成需要迁移, 并在刷新时重建; 身份全部解析不出来时, 保留原物品并记一条 warning, 不会用不完整的结果覆盖原来的状态.材料的身份键必须保持不变: 纯 matcher 材料会按 matcher 内容摘要推导身份, 改动 matcher 之后, 旧成品会报"未找到材料" (console.forge_refresh_missing_material). 这个行为已经由源码证实, 但本轮没有在真实的 Paper/Folia 服务器上验证旧 PDC 审计数据

用途场景

交易或回收系统可以读审计数据, 判断物品的配方来源和品质
外部统计可以按 recipe_id, quality 和 forged_at 汇总锻造产出

NOTE

Forge 没有提供查看审计数据的内置命令. 需要人工查看时, 请用能读物品 PDC 和物品层快照的外部工具

审计与签名 ​

数据落在哪里 ​

审计字段 ​

材料签名 ​

锻造层 PDC 键 ​

与刷新的关系 ​