名称与 Lore 操作

CoreLib 提供统一的物品名称和 Lore 操作系统。所有 Emaki 插件通过 name_actions 和 lore_actions 配置段来精确控制物品的名称和描述展示。

操作系统是无状态的——每次渲染都从零开始执行完整的操作链。当状态变化（如强化回退）时，系统用新的变量值重新执行操作链，自动得到正确的展示结果。

---

名称操作（name_actions）

对物品名称执行精确修改。操作按配置顺序依次执行。

replace

完全替换物品名称。会清除之前所有的前缀和后缀。

name_actions:
  - action: "replace"
    value: "<gold>%quality_name% 烈焰剑</gold>"

prepend_prefix

在名称前面添加前缀。

name_actions:
  - action: "prepend_prefix"
    value: "<red>[+%star%] </red>"

append_suffix

在名称后面添加后缀。

name_actions:
  - action: "append_suffix"
    value: " <gray>[%quality_name%]</gray>"

regex_replace

对名称进行正则替换。仅在名称已被 replace 设置为显式模板后生效。

name_actions:
  - action: "regex_replace"
    regex_pattern: "\\[\\+\\d+\\]"
    replacement: "[+%star%]"

---

Lore 操作（lore_actions）

对物品 Lore 执行精确修改。操作按配置顺序依次执行。

append

在 Lore 最后一行后面添加内容。

lore_actions:
  - action: "append"
    content:
      - ""
      - "<gray>强化等级: <gold>+%star%</gold></gray>"

prepend

在 Lore 第一行前面添加内容。

lore_actions:
  - action: "prepend"
    content:
      - "<gradient:#F2C46D:#C9703D>强化等级 +%star%</gradient>"
      - ""

insert_below

在匹配行的下面插入内容。别名：search_insert_below、search_insert。

lore_actions:
  - action: "insert_below"
    anchor: "物理伤害"
    content:
      - "<gray>强化加成: <gold>+%physical_attack%</gold></gray>"

insert_above

在匹配行的上面插入内容。别名：search_insert_above。

lore_actions:
  - action: "insert_above"
    anchor: "品质"
    content:
      - ""
      - "<yellow>强化效果:</yellow>"

replace_line

替换第一个匹配的行。

lore_actions:
  - action: "replace_line"
    anchor: "强化等级"
    content:
      - "<gradient:#F2C46D:#C9703D>强化等级 +%star%</gradient>"

delete_line

删除所有匹配的行。

lore_actions:
  - action: "delete_line"
    anchor: "旧的强化信息"

regex_replace

对所有 Lore 行进行正则替换。

lore_actions:
  - action: "regex_replace"
    regex_pattern: "\\+\\d+"
    replacement: "+%star%"

---

匹配字段

insert_below、insert_above、replace_line、delete_line 操作中的匹配文本支持多个字段名（按优先级）：

字段	优先级	说明
target_pattern	最高	匹配目标文本
pattern	中	匹配目标文本
anchor	最低	匹配目标文本

匹配方式为包含匹配（contains），不是精确匹配。

---

变量替换

所有操作中的 value、content、anchor、replacement、regex_pattern 都支持 {变量名} 格式的变量替换。

可用变量取决于使用操作的插件：

插件	可用变量
EmakiStrengthen	%star%, %temper%, %max_temper%, %temper_color%, 以及所有 variables 中的值
EmakiForge	%quality%, %quality_name%, %multiplier%, %player_name%, %player_uuid%, 以及所有锻造属性值
EmakiGem	%slot_index%, %slot_type%, %gem_name%, %gem_level%, %display_name%, 以及所有 variables 中的值

---

回退机制

操作系统通过 ItemOperationLedger 实现精确回退。每次执行 name_actions 或 lore_actions 时，系统会记录操作详情到物品 PDC。

当需要撤销操作时（如宝石提取、强化降级）：

1. 系统通过 operationId 定位到具体的操作记录。
2. ItemOperationReverter 根据记录精确撤销对应的名称/Lore 修改。
3. 其他模块的操作不受影响。

镶嵌宝石 → Ledger.apply(operationId="gem_ruby_slot0", ...)
强化成功 → Ledger.apply(operationId="strengthen_star3", ...)
提取宝石 → Ledger.revert(operationId="gem_ruby_slot0")  ← 只撤销宝石的修改

对于强化系统的 Lore 更新（replace_line 策略），每次强化成功时：

1. 先 revert 上一次强化的 lore_action 操作。
2. 再 apply 新星级的 lore_action 操作。
3. 这样确保属性行始终只有一行，数值为最新值。

---

完整配置示例

EmakiStrengthen 配方

全局 Lore 操作（每次强化都执行）：

name_actions:
  - action: "append_suffix"
    value: " <yellow>[+%star%]</yellow>"

lore_actions:
  - action: "prepend"
    content:
      - "<gradient:#F2C46D:#C9703D>强化等级 +%star%</gradient>"
      - "<gray>锻印: %temper_color%%temper%/%max_temper%</gray>"

星级 Lore 操作（★1 使用 append，★2+ 使用 replace_line）：

# ★1: 首次添加属性行
stars:
  1:
    effects:
      - type: "lore_action"
        lore_actions:
          - action: "append"
            content:
              - "<gray>物理伤害: <gold>+4</gold></gray>"
  # ★2+: 通过 anchor 匹配并替换已有行
  2:
    effects:
      - type: "lore_action"
        lore_actions:
          - action: "replace_line"
            anchor: "物理伤害:"
            content:
              - "<gray>物理伤害: <gold>+8</gold></gray>"

EmakiForge 配方

name_actions:
  - action: "prepend_prefix"
    value: "<light_purple>[%quality_name%]</light_purple> "

lore_actions:
  - action: "append"
    content:
      - ""
      - "<gray>锻造品质: <white>%quality_name%</white></gray>"
      - "<gray>品质倍率: <white>x%multiplier%</white></gray>"
      - "<gray>锻造者: <white>%player_name%</white></gray>"