Discord-MC-Chat (DMCC) 重构设计文档 (v3)

1. 项目概述

Discord-MC-Chat (DMCC) 是一个 Minecraft 模组，旨在为 Discord 和 Minecraft 服务器之间建立一个功能强大、可高度定制的双向通信桥梁。

本次 v3 重构的核心目标是实现一个统一的、基于"服务端-客户端 (Server-Client)"的通信架构 。在此架构下，所有运行模式都将复用同一套核心逻辑，以达到最大程度的代码复用、架构一致性和未来的可扩展性。

项目初期将优先实现对 NeoForge 26.1 的兼容。但为了未来能够无缝支持 Fabric 等其他加载器，整体架构设计严格遵循平台无关原则，所有核心代码中不得含有任何启动器专属的调用，仅通过 Mixin 进行注入。

2. 核心功能需求

2.1 双向通信与格式处理

• 全方位消息转发: 在 Discord 和 Minecraft 之间实时转发普通聊天。不仅如此，系统还会拦截并转发原版系统广播（如 /say 和 /tellraw @a），确保 Discord 玩家不会错过任何游戏内公共事件。
• 玩家指令广播与过滤: 支持将玩家在游戏内执行的命令广播至 Discord。内置强大的正则过滤列表（excluded_commands ），自动拦截私密指令（如 /login, /msg），保障服务器与玩家安全。
• 富文本与多媒体解析: 支持 Markdown、Discord 表情符号、Unicode 表情符号、@ 提及、图片、GIF 和超链接在两个平台间的自动双向解析与渲染。
• 伪用户 Webhook 支持: 可选通过 Webhook 发送 Minecraft 消息，在 Discord 端完美呈现玩家的独立头像与游戏名。
• 自定义格式与国际化: 允许用户高度自定义所有消息的显示格式（基于 YAML 模板）。此外，系统内置动态翻译拉取机制，自动从官方源获取各语言资产，精准翻译成就、进度与死亡信息。

2.2 状态同步与事件通知

• 玩家与服务器事件: 实时播报玩家加入/离开服务器、死亡、获得进度/成就，以及服务器启动/关闭事件。
• 频道看板与状态监控 (Channel Monitor):
  • 文字频道 Topic: 定期动态更新频道的 Topic（如在线人数、历史总玩家数、各子服状态）。
  • 语音频道名称: 动态更新指定的语音频道名称，用作服务器状态（Status: Online）和人数（Players: X/Y）的直观数据看板。
• Bot 状态展示: 根据游戏内在线人数与状态，实时同步更新 Discord Bot 的活动状态（Activity）和在线状态。
• 性能预警: 定期监控服务器 MSPT（每 tick 毫秒数），超过设定阈值时在 Discord 频道自动发出警告。
• 自动更新检查: 自动校验 DMCC 版本并对比兼容性，发现新版本时在指定频道发送更新日志，并支持一键提醒管理员（Ping Admins）。

2.3 深度管理与控制功能

• 双向控制台日志流 (Console Forwarding):
  • 实时推流: 专设后台线程将 latest.log 增量实时切片推送到 Discord 指定控制台频道。
  • 频道直连终端: 拥有权限的管理员可直接在该 Discord 控制台频道中发送文本，系统会将其等同于控制台指令在游戏内直接执行。
  • 敏感信息过滤: 考虑到有些人会选择公开此 Discord 频道，因此提供可选但默认启用的敏感信息过滤器（如 IP 地址），确保安全。
• Discord 侧斜杠命令: 提供 /info, /stats, /log, /whitelist 等管理命令。支持通过 Discord 查阅完整日志文件（打包传输）与计分板排行。
• 系统重载: 动态重载 DMCC 配置文件（/dmcc reload 或 Discord /reload）。
• 账户绑定管辖: 提供完整的账户绑定管理命令（link / unlink / links），支持跨端协同认证。

3. 系统架构

3.1 统一的"服务端-客户端 (Server-Client)"架构

DMCC 所有运行模式都基于一个统一的通信模型，该模型包含两个核心组件：

1. 服务端 (Server): 整个系统的"大脑"与中央路由。它作为后台服务运行，是唯一负责与 Discord API (通过 JDA) 直接通信的组件。它处理所有跨服路由、身份解析和鉴权凭证下发。此组件不得包含任何 net.minecraft 的导入（反射除外）。
2. 客户端 (Client): 部署在每个 Minecraft 服务器上的"触手"。负责捕获游戏内的所有事件发送给 Server，并接收来自 Server 的指令（执行本地命令与委托鉴权）。

两者之间通过基于 Netty 的 TCP 协议（共享密钥与一次性哈希质询认证）进行安全通信。

3.2 运行模式与部署

1. 单体服务器模式 (single_server): 在同一 JVM 中同时启动内部 Server 和内部 Client，直接连通 Discord。推荐绝大多数普通服主使用。
2. 多服务器-客户端模式 (multi_server_client): 只启动 Client 端，不连接 Discord API，而是作为子服连接到外部独立运行的 DMCC Server。
3. 独立模式 (standalone): 只启动 Server 端（无 Minecraft 进程），作为多服务器架构的中央中枢，负责聚合各个子服的消息与状态，并与 Discord 进行数据交换。

4. 账户绑定系统 (Account Linking)

账户绑定系统是连接无状态 Discord 社区和有状态 Minecraft 世界的数据总线，也是 DMCC 权限系统的基石。

4.1 非对称映射关系

• 一个 Discord 账户可关联多个 Minecraft 账户（方便玩家管理大号与小号）。
• 一个 Minecraft 账户只能关联一个 Discord 账户（确保游戏内身份的绝对唯一性）。
• 数据持久化: 绑定关系作为永久数据存储在 Server 端的 account_linking/links.json 中，以 Discord ID 为主键。查询时，Discord 显示名与正版玩家名均通过 API 实时动态解析，离线玩家则保留绑定时的历史快照。

4.2 安全绑定工作流 (严格的 MC 优先原则)

为防止在正版/离线服务器中出现身份冒用，严禁在 Discord 端直接输入游戏名进行绑定。

1. 玩家进服自动检查: 玩家每次进入 Minecraft 服务器时，Client 通过网络包请求 Server 检查其 UUID 是否已绑定。
2. 自动生成凭证: 若未绑定，Server 生成一个 6 位临时验证码（如 A7X9P2），Client 在游戏内发送包含内联可点击元素的消息指引玩家在 Discord 执行 /link A7X9P2，验证码 5 分钟有效。
3. 手动刷新凭证: Minecraft 端提供 /dmcc link 命令进行验证码续期或重新生成。
4. 确认所有权: 玩家前往 Discord，使用斜杠命令 /link A7X9P2 完成最终绑定。

4.3 跨平台交互反馈

• 同频渲染: 玩家在游戏内的聊天名字颜色，将自动同步为其绑定的 Discord 账户的最高角色颜色。
• 跨平台艾特提醒: 跨平台提及 (@) 时，自动在游戏内通过 Action Bar、Title 或 Chat 高亮提醒对应的玩家。

5. 零信任委托权限系统 (Delegated Authorization)

DMCC v3 彻底摒弃了在 Discord 端硬编码判定命令权限的做法，转而采用 “身份映射 + 边缘委托鉴权” 的微服务安全架构。

5.1 扩展的权限基准 (-1 到 4)

所有权限均对齐 Minecraft 原生的 OP 等级，并向下扩展：

• -1 级: 任意 Discord 用户（包括未绑定账号的游客）。适用于无害的查询命令（如 help, info）。
• 0 级: 基础绑定玩家，或被赋予基础信任身份的未绑定用户，对应 Minecraft 原生的 OP 等级 0。
• 1 ~ 4 级: 对应 Minecraft 原生的 OP 等级 1-4。

5.2 身份与 OP 映射 (Mappings)

Discord 用户的身份将通过以下规则在 Server 端结算为一个具体的 OP 等级凭证：

1. user_mappings: 基于特定 Discord User ID 指定 OP 等级（优先级最高）。
2. role_mappings: 遍历用户拥有的 Discord 角色，取映射的最高 OP 等级。
3. 绑定账号保底: 如果用户有绑定 Minecraft 玩家，则保底获得 OP 0 等级。

(注：系统将取上述条件中命中的最高 OP 等级作为该请求的最终凭证。)

5.3 核心路由与委托鉴权

当 Discord 用户发起命令时（如 /reload 或 /execute SMP reload）：

1. Server 不负责拦截业务逻辑，它仅计算出该用户的 OP 凭证（例如：OP=2），并将“指令内容”连同“凭证标签”一起打包，通过 Netty 发送给对应的目标 Client。
2. Client 边缘鉴权：目标客户端收到请求后，读取自身本地 config.yml 中设定的安全阀值（例如 reload: 4），发现凭证（OP 2）不足，由 Minecraft 客户端直接驳回请求。
3. 动态 UI：Discord 端斜杠命令的参数补全，同样附带 OP 凭证请求给 Client，Client 仅返回该凭证有权查看的补全项（例如仅为管理员自动补全系统文件名）。

5.4 优雅解决白名单悖论 (Whitelist Catch-22)

玩家因白名单进不去服务器 -> 无法证明身份绑定 -> 无法获得白名单。 解决方案： DMCC 在 Client 端提供独立的 whitelist 代理命令（默认所需权限为 0 级）。玩家加入 Discord 频道并获得基础角色（映射为 OP 0）后，即可在 Discord 执行 /whitelist <他的ID> 预先上白名单，进服后再走正常绑定流程。

5.5 Minecraft OP 强制同步机制 (sync_op_level_to_minecraft)

开启此项后，DMCC 将成为服务器权限的“唯一真理来源”（Single Source of Truth）：

• 每次同步均执行“全量重算 + 强制覆盖”。
• Discord 身份映射将被硬写入服务器的原生 OP 列表中；管理员在游戏内手打的原生 /op 授权，会在下一次同步时被 DMCC 依据配置冲刷覆盖。
• 解绑账号将触发 OP 自动降级与回收。

6. 多服务器配置模型（Standalone + Multi Server）

当 DMCC 处于 standalone + multi_server_client 架构时，不同子服务器可使用不同 OP 映射策略。

在 standalone 配置的 user_mappings 与 role_mappings 中，每个条目包含一个顶层 op_level（给 Standalone 自身查询使用），以及一个 server_overrides 列表字典。若 server_overrides 中没有某子服务器的对应条目，则该子服务器自动降级使用顶层 op_level 作为默认回退值。

7. 命令列表与权限参考

命令	默认 OP 等级	模组运行 multi_server_client	模组运行 single_server	独立运行 standalone	说明
console <command>	0	❌	✅	❌	通过 Discord 模拟控制台执行任意指令。
console <at> <command>	0	❌	❌	✅	通过 Discord 模拟远程子服务器控制台执行任意指令。
execute <at> <command>	-1	❌	❌	✅	远程执行中枢，仅 Standalone 存在。负责将请求连同鉴权凭证委托给 Client。
help	-1	✅	✅	✅	动态显示用户当前有权执行的可用命令。
info	-1	✅	✅	✅	查看状态。Client 只显自身数据，Server 聚合全局数据。
link	0	✅	✅	❌	Minecraft 端生成或刷新 6 位验证码。
link <code>	0	❌	✅	✅	Discord 端使用验证码完成最终绑定。
links	4	❌	✅	✅	管理员查询所有已绑定的账户关系数据。
log <file>	4	✅	✅	✅	将指定的后台日志文件打包传输至 Discord，支持自动补全。
reload	4	✅	✅	✅	重新加载 DMCC 配置。
shutdown	4	❌	❌	✅	仅用于安全关闭 Standalone 中央进程。
stats <type> <stat>	-1	✅	✅	❌	查看计分板与统计数据。支持基于权限过滤的动态自动补全。
unlink	0	✅	✅	✅	解绑当前 MC 玩家 / 当前 Discord 用户的所有关联玩家。
whitelist <player>	0	✅	✅	❌	DMCC 专用的低权限白名单命令代理。

v3 移除了 v2 提供的 /stop 快捷指令。若需在 Discord 端关闭 Minecraft 服务器，拥有 4 级权限的管理员请直接使用 /console stop 模拟控制台发起安全停机。