AuQuestEngine/docs/superpowers/specs/2026-06-14-minimessage-config-design.md

配置可见文本 MiniMessage 支持设计

背景

AuQuestEngine 当前通过 ColorUtil.color 将配置中的 & 颜色码和 #RRGGBB 十六进制颜色转换成 Bukkit legacy 文本。任务配置、语言配置和奖励提示都依赖这个工具，最终通过现有 sendMessage(String) 路径发送给玩家。

本次目标是让配置里的玩家可见文本支持 MiniMessage，同时保留旧配置兼容性。

范围

纳入 MiniMessage 支持的配置文本：

• lang.yml 中的语言文本。
• 任务配置中的 display_name。
• 任务配置中的 description。
• 任务配置中的 messages.receive。
• 任务配置中的 messages.complete。
• 任务配置中的 rewards.messages。

不纳入本次范围：

• rewards.commands，它是控制台命令，不是玩家可见文本。
• 硬编码的命令提示。
• 控制台日志。
• 调试输出。
• API 返回类型调整。

方案

采用兼容式解析：

1. ColorUtil 继续作为统一文本格式入口。
2. 旧格式 &a文本 和 #RRGGBB文本 继续支持。
3. 新格式 <green>文本</green>、<gradient:red:blue>文本</gradient> 等 MiniMessage 标签可用于配置文本。
4. 解析结果仍返回 legacy String，保持现有 Quest、QuestReward、MessageUtil 和 API 方法签名不变。

数据流

配置加载后：

1. 读取 YAML 原始字符串。
2. 通过 ColorUtil.color 统一解析。
3. 对 MiniMessage 文本解析成 Adventure Component。
4. 将 Component 序列化为 legacy String。
5. 现有发送逻辑继续调用 sendMessage(String)。

列表文本通过 ColorUtil.color(List<String>) 逐行处理。

兼容性

旧配置无需迁移：

display_name: "&a[初级] &f新手成长之路"

新配置可以使用 MiniMessage：

display_name: "<green>[初级]</green> <white>新手成长之路</white>"

如果配置文本混用两种格式，优先保证旧 & 颜色码仍能按原行为生效，同时 MiniMessage 标签能被识别。

错误处理

MiniMessage 解析应使用非严格模式，避免配置中未知标签或普通尖括号文本导致任务加载失败。无法识别的文本应尽量保留为可见内容，而不是抛出异常中断插件启用或重载。

测试

新增针对 ColorUtil 的测试，覆盖：

• legacy & 颜色码仍可转换。
• #RRGGBB 仍可转换。
• MiniMessage 基础颜色标签可转换为 legacy 输出。
• MiniMessage 装饰标签可转换为 legacy 输出。
• 列表文本逐行解析。

实现前先写失败测试，再实现最小改动使测试通过。