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

1. 项目概述

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

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

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

2. 核心功能需求

2.1 通信功能

• 双向消息转发: 在 Discord 和 Minecraft 之间实时转发聊天消息。
• 格式兼容: 支持 Markdown、Discord 表情符号、提及和超链接在两个平台间的自动转换。
• Webhook 支持: 可选通过 Webhook 以玩家头像发送 Minecraft 消息到 Discord。
• 自定义格式: 允许用户高度自定义所有消息的显示格式。

2.2 事件通知

• 玩家事件: 玩家加入/离开服务器、死亡、获得进度/成就。
• 服务器事件: 服务器启动/关闭。
• 性能监控: 当服务器 MSPT (每 tick 毫秒数) 超过阈值时，在 Discord 发出警告。

2.3 管理功能

• 通过 Discord 查询服务器状态（TPS, MSPT, 在线玩家等）。
• 通过 Discord 执行 Minecraft 控制台命令。
• 通过 Discord 管理白名单。
• 通过 Discord 查看和过滤服务器日志。
• 通过 Discord 重载 DMCC 配置文件。
• 通过 Discord 远程启动/关闭子服务器（仅限多服务器模式）。

2.4 账户链接功能

• 身份绑定: 支持将 Minecraft 玩家账户与 Discord 账户进行一对一关联。
• 角色颜色同步: 游戏内聊天消息显示与玩家 Discord 角色的颜色一致。
• 跨平台提及: 在 Discord 中@用户时，对应的 Minecraft 玩家会收到游戏内提醒。
• 权限同步: 可选基于 Discord 角色自动授予玩家游戏内的 OP 权限。

3. 系统架构

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

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

1. 服务端 (Server): 整个系统的“大脑”。它作为后台服务运行，是唯一负责与 Discord API (通过 JDA) 直接通信的组件。它处理所有核心逻辑，如消息格式化、命令解析和权限验证。此组件在任何情况下都不得包含任何 net.minecraft 的导入（反射除外），以确保其可以在没有 Minecraft 环境的情况下独立运行。
2. 客户端 (Client): 部署在每个 Minecraft 服务器上的“触手”。它作为 Minecraft 模组运行，负责捕获游戏内的所有事件，并将其发送给 服务端 (Server)。同时，它也接收并执行来自 服务端 (Server) 的指令。

两者之间通过一个定义好的、基于 TCP Sockets 的网络协议进行通信。

3.2 运行模式与部署

DMCC 支持三种运行模式，这三种模式只是上述统一架构的不同部署方式：

1. 单体服务器模式 (single_server):

   • 在此模式下，DMCC 在后台同时启动一个内部服务端和一个内部客户端。内部客户端会自动通过本地回环地址 (localhost) 连接到内部服务端。
   • 这是为单个 Minecraft 服务器提供的开箱即用的解决方案。
   • 支持停止 DMCC 自身的命令，但不支持管理子服务器。

2. 多服务器-客户端模式 (multi_server_client):

   • 在此模式下，DMCC 只启动一个客户端。
   • 此客户端会连接到一个外部独立运行的服务端。
   • 用于将多个 Minecraft 服务器连接到一个中央服务端。

3. 独立模式 (standalone):

   • 在此模式下，DMCC 只启动一个服务端。
   • 此服务端会监听一个网络端口，等待一个或多个外部的客户端连接。
   • 作为多服务器架构的中央“大脑”而存在，提供最强的稳定性和隔离性。
   • 支持管理子服务器的命令（如 /start <server>, /stop <server>）以及停止自身进程的命令。

3.3 配置文件策略

为了降低用户心智负担并保证配置的准确性，采用两步配置流程：

1. mode.yml: 用户首先在此文件中选择一种运行模式。这是唯一需要手动选择的文件。（仅作为 Minecraft 模组运行时需要，若不是 Minecraft 环境，则自动选择 standalone 模式）
2. config.yml: DMCC 会根据 mode.yml 中选择的模式，从内部模板生成一份对应的、最小化的 config.yml。此配置文件将被严格验证，其注释会清晰地解释所有配置项，特别是双轨权限模型。

4. 模块化设计

为了保持结构清晰，项目将主要划分为三个逻辑模块。

4.1 通用模块 (Common)

此模块没有 Minecraft 依赖，

此模块包含被服务端和客户端共享的代码，是整个项目的基础。

• 主要职责:
  • 定义服务端和客户端之间通信的网络协议和数据结构。
  • 提供统一的日志系统 (Logger)，能同时兼容 Minecraft 和独立环境。
  • 提供强大的国际化（i18n）管理器，支持从本地和网络加载语言文件。
  • 提供健壮的配置管理器 (ConfigManager, ModeManager)。
  • 提供事件总线 (EventManager) 用于内部解耦。
  • 提供其他通用工具类（字符串处理、时间工具等）。

此模块同时实现了“大脑”的所有功能，完全独立于 Minecraft。

• 主要职责:
  • Discord 连接: 初始化并管理 JDA 实例，处理所有与 Discord API 的底层交互。
  • 事件处理: 监听 Discord 事件（如消息接收、斜杠命令）。
  • 命令系统:
    • 注册所有 Discord 斜杠命令。
    • 解析并分派命令到对应的处理器。
    • 根据模式（standalone vs single_server）动态启用/禁用命令（如 start/stop <server>, execute）。
  • 权限管理:
    • 实现完整的双轨权限模型（见 5.1 节）。
  • 消息处理与转发:
    • 接收来自所有客户端的数据，进行格式化、聚合后，通过普通消息或 Webhook 发送到 Discord。
    • 接收来自 Discord 的消息，解析后向指定的客户端派发“显示消息”指令。
  • 账户链接: 管理账户链接数据（建议使用 JSON 文件存储），并处理链接请求的验证逻辑。
  • 定时任务与监控:
    • 管理所有定时任务（如检查更新、更新频道主题）。
    • 接收客户端上报的性能数据（MSPT），并在超过阈值时触发警告。
  • 状态管理: 管理 Discord Rich Presence，显示服务器状态、在线人数等信息。

4.2 客户端模块 (Client)

此模块有 Minecraft 依赖，是连接 Minecraft 的桥梁。

• 主要职责:
  • 模组初始化: 作为 NeoForge（未来为 Fabric）的入口点，初始化客户端组件。
  • 事件捕获:
    • 通过 Mixin 注入 Minecraft，捕获所有相关事件：
      • 玩家事件: PlayerJoin, PlayerQuit, PlayerChat, PlayerCommand, PlayerDie, PlayerAdvancement。
      • 服务器事件: ServerStarted, ServerStopping, ServerStopped。
      • 命令输出: 拦截 /say, /tellraw 等命令的输出。
  • 数据上报: 将捕获到的事件和性能数据（MSPT）打包，通过网络协议发送给服务端。
  • 指令执行:
    • 接收并执行来自服务端的指令，如在游戏聊天框显示格式化后的消息、执行控制台命令。
  • 游戏内命令: 注册并处理 /dmcc 相关子命令（如 /dmcc link 用于生成链接码）。

5. 关键设计详解

5.1 权限管理模型 (双轨制)

DMCC 采用一个灵活的双轨权限模型来确定谁是“DMCC 管理员”。

1. 路径一：原生继承模型 (Minecraft -> DMCC)

   • 来源: 玩家在 Minecraft 中的 OP 等级。
   • 运作方式: 在 config.yml 中定义 dmcc_admin.minecraft_op_level_requirement。任何在游戏中拥有等于或高于此 OP 等级的玩家，都将自动被视为“DMCC 管理员”。
   • 目的: 这是成为 DMCC 管理员的基础方式。若 Discord 用户想使用管理命令，其链接的 MC 账户必须满足此要求。

2. 路径二：角色同步模型 (Discord -> Minecraft)

   • 来源: 用户在 Discord 中的角色。
   • 运作方式: 这是一个可选功能。用户可在配置中定义一个 Discord 角色到游戏 OP 等级的映射。服务端模块会周期性地检查已链接用户的角色，并通过向客户端发送指令来自动授予或撤销其在游戏中的 OP 权限。
   • 协同作用: 一旦一个玩家通过此路径被授予了足够的 OP 等级，他也会因为路径一的规则而自动成为“DMCC 管理员”。

5.2 账户链接流程

1. 发起: 玩家在游戏中执行 /dmcc link 命令。
2. 生成: 客户端模块生成一个有时效性的一次性链接码，并通知服务端该验证码与当前玩家的 UUID 关联。
3. 验证: 玩家在 Discord 中对机器人使用 /link <code> 命令。
4. 确认: 服务端模块验证链接码是否有效、未过期。验证成功后，将玩家的 Minecraft UUID 和 Discord User ID 保存到持久化存储中（如 linked_accounts.json），并通知用户链接成功。

5.3 数据流示例 (Minecraft -> Discord)

1. [客户端] 玩家在 Minecraft 中发送消息 "Hello World"。
2. [客户端] MixinServerGamePacketListenerImpl 捕获聊天事件。
3. [客户端] 将事件数据（玩家UUID, 玩家名, 消息内容）打包，通过网络发送给 服务端。
4. [服务端] 接收到数据包，解析出内容。
5. [服务端] 检查该玩家是否已链接账户，获取其 Discord 角色颜色（如果启用了该功能）。
6. [服务端] 根据 config.yml 中的消息格式模板，生成最终的字符串，例如 [SMP-1] <Xujiayao> Hello World。
7. [服务端] 通过 JDA 将格式化后的消息发送到指定的 Discord 频道。