MC Matrix Bridge: 连接Minecraft服务器和Matrix房间的Forge/NeoForge模组
内容提要
MC Matrix Bridge 是一款 Forge/NeoForge 纯服务端模组，实现 Minecraft 服务器聊天与 Matrix 房间的双向互通，支持 1.18 至 26.2 多个版本。其采用 core 加薄兼容层架构，仅需服主安装，玩家使用原版客户端即可。功能包括双向聊天、连接提示、服务器事件转发、Matrix 指令及 Event Taps 事件监控。项目基本由 AI 开发，作者负责架构设计与人工测试。
延伸解读
纯服务端设计降低部署门槛
该模组只需服主在服务器端安装，玩家使用原版客户端即可接入，无需额外下载或配置。这得益于其将聊天转发、指令处理等逻辑全部放在服务端，并通过兼容层监听游戏事件。对于希望快速搭建跨平台聊天桥接的服主而言，这种设计避免了要求所有玩家安装模组的协调成本，尤其适合与外部社群联动的场景。
多版本兼容依赖薄兼容层架构
项目将核心逻辑（Matrix客户端、消息队列、去重等）与Minecraft版本解耦，每个游戏版本仅需实现一层很薄的兼容层，负责事件监听和指令注册。这种架构使得从1.18到26.2的Forge/NeoForge版本可以共享大部分代码，但也带来构建复杂性：不同版本需要不同的Gradle和Java环境，且部分API变化需通过反射处理，增加了维护负担。
Event Taps提供灵活的事件监控
Event Taps允许在运行时订阅任意Forge/NeoForge事件并转发到Matrix，可用于调试或监控服务器状态。使用时需注意限制：同时最多开启10个监听，转发间隔默认至少1秒，每条消息截断至2048字符，且在Matrix端操作要求权限等级不低于50。这些限制有助于防止消息刷屏，但也意味着高频事件需谨慎选择。
AI开发模式与人工测试并重
作者负责架构设计、需求定义和人工测试，代码编写主要交由AI代理完成，并通过AGENTS.md积累项目约束。开发过程中仍需要人工介入纠正，例如重构重复代码、修复构建错误和CI失败。发布前作者会用真实Matrix和Minecraft服务器进行人工验证，说明AI生成代码仍需结合自动化测试与人工检查来保证可靠性。
Q&A
MC Matrix Bridge 是什么？它主要解决什么问题？
MC Matrix Bridge 是一个 Forge/NeoForge 纯服务端模组，用于将 Minecraft 服务器聊天与 Matrix 房间双向连接。它解决了 Forge 高版本缺乏类似模组的问题，让玩家在游戏外也能通过 Matrix 与服务器内玩家交流。
安装 MC Matrix Bridge 需要哪些前置条件？
需要一个 Forge 或 NeoForge 服务器，以及一个未开启端到端加密的 Matrix 房间。根据服务器加载器和 Minecraft 版本选择对应的 jar（共 9 个），放入 mods/ 文件夹后启动服务器生成配置文件，并填写 matrix.homeserver、matrix.roomId 和 matrix.accessToken 三项必填配置。
MC Matrix Bridge 支持哪些 Minecraft 版本和加载器？
支持 Forge 1.18.x 到 1.21.x 以及 26.1.x、26.2.x，同时支持 NeoForge 1.21.x 和 26.1.x、26.2.x。共提供 9 个 jar，对应不同 Java 版本：Forge 1.18-1.20 用 Java 17，Forge/NeoForge 1.21 用 Java 21，26.x 用 Java 25。
这个模组有哪些主要功能？
主要功能包括：双向聊天（带 [MC] 和 [Matrix] 前缀）、纯服务端运行（玩家用原版客户端即可）、连接提示（支持中英文）、可选的服务器事件转发（玩家进出、服务器启停）、Matrix 指令（!mc list 查看在线玩家，!mc help 查看帮助）以及 Event Taps（订阅并转发任意 Forge/NeoForge 事件到 Matrix）。
Event Taps 是什么？如何使用？
Event Taps 允许在运行时订阅任意 Forge/NeoForge 事件并转发到 Matrix，用于调试和监控。可在游戏内用 /matrix event 或在 Matrix 中用 !mc event 控制（要求发送者权限等级至少 50）。支持指定事件、持续时间和过滤条件，同时最多开启 10 个，转发间隔至少 1 秒，消息截断到 2048 字符。
MC Matrix Bridge 的架构是怎样的？为什么能支持多个版本？
采用 core 加薄兼容层架构：core 包含与 Minecraft 版本无关的全部逻辑（Matrix 客户端、消息队列、去重、Event Taps 等），每个 Minecraft 版本一个兼容层，负责监听事件、注册指令和广播消息。由于模组涉及的 Minecraft API 较少，大部分代码可复用，只需为每个版本写很小的兼容层即可交叉编译到多个版本。
这个项目是如何用 AI 开发的？作者负责什么？
项目基本由 AI 开发，作者负责架构设计（跨版本方案、仓库组织、交叉编译思路）和人工测试。开发时先与 agent 讨论想法，将结果整理到 AGENTS.md 中，再让 agent 编写代码。使用过 Cursor、Codex、OpenCode 等工具，后期主力为 OpenCode 加 oh-my-opencode 多 agent 编排层。每次发布前作者仍会用真实服务器人工测试。
