Discord-MC-Chat/README.md

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

## 1. 项目概述

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

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

项目初期将优先实现对 **NeoForge 1.21.10** 的兼容。但为了未来能够无缝支持 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` 模拟控制台发起安全停机。