DebugBridge

模组

· 作者 weikeng

连接 MCP 客户端和本地工具到正在运行的 Minecraft 客户端,以实现实时 Groovy 脚本编写、游戏状态检查以及内置的 Web UI。适用于模组开发者和 AI 辅助调试。

0 本站下载 0 关注 更新于 2 个月前

最新 2.1.0 · 26.2 · Fabric

一键开服(送7天)

DebugBridge

一款用于 Minecraft(1.19、1.21.11、精确版 26.1 和稳定版 26.2)的 Fabric 客户端模组,通过本地 WebSocket 服务器暴露游戏状态,并附带一个 Vue Web UI 用于可视化检查。专为 AI 辅助 Minecraft 开发与调试而构建。

2.1.0 更新内容

v2.1.0 为所有受支持的目标版本提供了相同的稳定功能线:Minecraft 1.19.x、1.21.11、精确版 26.1 和稳定版 26.2。之前的 26.2 开发模块现已成为稳定版 26.2 分支;源目录仍为 mod/fabric-26.2-dev/。

相较于 2.0.0,此版本还增强了现有桥接功能的健壮性:

  • record_video 默认使用临时存储,具有 24 小时 TTL 和自动清理功能(storage: "persistent" 会将文件保存在游戏目录下)
  • runCommand 保持相同的选择加入式协议契约,但现在使用原生的按版本提供者,而非 Groovy 往返调用
  • 配置值经过范围验证,对象引用有界,脚本执行复用其工作线程,并且更防御性地处理了录制/断开连接/纹理/实体刷新竞争条件
  • 精确版 26.1 可以在标题屏幕上渲染物品纹理(getItemTextureById 不再因 Components not bound yet 而失败)
  • Web UI 的物品栏槽位、实体颜色和商店刷新行为更加可靠

Groovy 5 脚本模型和端点集与 v2.0.0 兼容。请从 v2.1.0 发布页面 获取匹配的 jar 包。

功能介绍

DebugBridge 在 Minecraft 内部运行一个仅限本地主机的 WebSocket 服务器(默认端口 9876,扫描 9876–9886)。外部工具——CLI 脚本、捆绑的 Vue Web UI 或 MCP 客户端(如 Claude Code)——可以通过两个互补的 API 检查和与正在运行的游戏进行交互:

原生端点(快速、高级)

专为返回单次往返的结构化 JSON 而设计的 Java 端点——无脚本开销:

端点 返回内容
snapshot 玩家位置、生命值、食物值、维度、游戏模式、时间、天气
nearbyEntities 范围内的实体:类型、位置、装备、距离(可选 includeIcons 以获取物品纹理)
entityDetails 完整的实体信息:带伤害/自定义名称的装备槽位、载具、乘客、属性、容器内容
lookedAtEntity 玩家瞄准的实体(射线检测)
nearbyBlocks 范围内的区块实体:告示牌、箱子、旗帜、信标、熔炉等
blockDetails 区块实体内容:告示牌行、箱子库存、头颅配置文件、信标等级
screenInspect 当前打开的屏幕/gui:类型、标题、带物品堆叠的容器槽位(可选 includeIcons)
chatHistory 最近的客户端聊天消息(可选 includeJson 以获取样式化组件)
screenshot 将帧缓冲区捕获为 JPEG
record_video 将 N 个帧缓冲区帧捕获为默认为临时的 JPEG 网格或逐帧文件
getItemTexture / getItemTextureById / getEntityItemTexture 将物品图标渲染为 PNG(尊重损坏度、自定义模型数据、染色皮革、玩家头颅)
setEntityGlow / setBlockGlow / clearBlockGlow 使用世界内的轮廓高亮显示实体或方块
search 按名称模式搜索已加载的类
status 服务器健康和连接信息

两个端点家族在 config/debugbridge.json 中默认被禁用:runCommand (run_command_enabled) 通过原生按版本提供者以玩家身份发送命令,以及会话控制三件套 disconnect / joinServer / quit (session_control_enabled) 允许自动化循环离开世界、加入服务器或关闭客户端。joinServer 预先接受服务器资源包,并推迟连接直到客户端稳定(没有加载叠加层——在启动资源重新加载期间加入会无声地丢弃服务器资源包),仅在连接尝试实际开始后确认;一旦桥接端口在启动后响应,即可安全触发。

Groovy 执行(execute 端点)

在 Minecraft JVM 内运行 Groovy 脚本,通过感知映射的 Java 桥接器完全访问 Minecraft API——编写 Mojang 名称,它们会自动解析为运行时(intermediary)名称,即使在混淆构建中也是如此。便捷的全局变量 mc、player 和 level 已预绑定。沙箱允许进行文件 I/O 以读写数据。每个请求都有可配置的超时时间(默认 10 秒,最大 5 分钟)。

// 便捷的全局变量已可用
println "Player at: " + player.blockPosition().toShortString()
println "Dimension: " + mc.level.dimension().location()

// 通过 Mojang 名称加载任何其他内容(在混淆构建中也有效)。
// 优先使用单引号:双引号的 GString 会插值 $,
// 例如 Display$TextDisplay 这样的内部类名称。
def Vec3 = java.type('net.minecraft.world.phys.Vec3')

// 迭代 Java 集合。将批量循环包装在 sync { } 中,以便每次调用的
// 反射调度批处理为单个游戏线程跳转。
sync {
    java.list(level.entitiesForRendering()).each { entity ->
        if (entity.distanceTo(player) < 10) {
            println "Nearby: " + java.typeName(entity)
        }
    }
}

Vue Web UI

web-ui/ 目录包含一个基于 Vue 3 + Pinia + Tailwind 的应用程序,用于可视化检查游戏状态:

  • Dashboard — 玩家快照概览
  • Entities panel — 附近实体列表,带有详细钻取、装备图标、高亮切换
  • Blocks panel — 附近区块实体浏览器(告示牌、箱子等)
  • Screen inspector — 当前 GUI/物品栏槽位查看器
  • Groovy inspector — Java 对象的钻取对象浏览器
  • Console — 连接到运行中客户端的交互式 Groovy REPL
  • Chat history — 最近的客户端消息

自 v2.0.0 起内置 —— 模组自身提供构建好的 UI,访问地址为 http://localhost:<bridge port + 100>(默认 ; 加入游戏时的聊天消息会以可点击链接的形式打印确切 URL)。 仅限本地回环、仅静态资源,且提供的页面会连接至为其提供服务的桥接实例,因此并排运行的多个游戏实例各自拥有独立的 UI。可在 config/debugbridge.json 中通过 "web_ui_enabled": false 禁用此功能。

对于 UI 开发,开发服务器仍然有效(支持 HMR):

cd web-ui
npm run dev          # → http://localhost:5173

Web UI 直接连接到 WebSocket 服务器——无需 MCP 层。

架构

+-----------------------------------+
|  MCP Client (Claude Code, etc.)   |
+---------------+-------------------+
                | MCP Protocol (stdio)
+---------------v-------------------+
|  mcdev-mcp Server (TypeScript)    |
|  Runtime + static analysis tools  |
| github.com/use-ai-for-mc/mcdev-mcp|
+---------------+-------------------+
                | WebSocket (localhost:9876–9886)
+---------------v-------------------+
|  DebugBridge Mod [THIS REPO]      |
|  +-----------------------------+  |
|  | BridgeServer (WebSocket)    |  |
|  | Native endpoints + execute  |  |
|  | Groovy runtime + Java bridge |  |
|  | Mojang mapping resolver     |  |
|  +-----------------------------+  |
+-----------------------------------+
                ^
                | WebSocket (same port)
+---------------+-------------------+
|  Vue Web UI (bundled, :9976;      |
|  npm dev server :5173)            |
+-----------------------------------+

Mojang 映射支持

模组在启动时自动下载官方 Mojang 映射文件,并使用它们将人类可读的名称(如 net.minecraft.client.Minecraft)转换为运行时使用的混淆名称。在 1.21.11 及更高版本中,Mojang 提供未混淆的名称,映射操作变为空操作(no-op)。

针对精确的 26.1 和 26.2 稳定版本的构建直接面向 Mojang 命名的类,完全跳过映射下载和重映射过程。

安全模型

DebugBridge 仅绑定到 localhost (127.0.0.1)。 只有运行在同一台机器上的进程才能连接。调试端口永远不会暴露给网络。

这是一个开发和调试工具,而非远程管理系统。任何拥有 localhost 访问权限的人已经可以完全控制 Minecraft 进程,因此该桥接不会引入新的攻击面。

  • 仅客户端 —— 完全在客户端运行,无法影响服务器或其他玩家
  • 无出站连接 —— 仅在启动时从 Mojang 官方 API 下载映射文件
  • 受控功能 —— runCommand 和会话控制默认禁用(需通过配置手动启用)
  • 开发者警告 —— 首次启动屏幕会告知用户模组已激活;在被接受之前不提供任何服务
  • Web UI 服务器 —— 同样仅限本地回环;仅提供 jar 包内捆绑的静态资源(仅 GET 请求,无目录列表,拒绝路径遍历)

仓库结构

mod/
  core/          — 共享 Java 代码:BridgeServer、Groovy 运行时、映射解析器、Provider 接口
  fabric-1.19/   — 适用于 Minecraft 1.19.x 的 Fabric 模组(Provider 实现 + Mixins)
  fabric-1.21.11/— 适用于 Minecraft 1.21.11 的 Fabric 模组(Provider 实现 + Mixins)
  fabric-26.1/   — 适用于精确 Minecraft 26.1 版本的 Fabric 模组(Provider 实现 + Mixins)
  fabric-26.2-dev/— 适用于 Minecraft 26.2 稳定版的 Fabric 模组
web-ui/          — Vue 3 + Pinia + Tailwind 检查应用

安装

从 GitHub releases 获取对应 Minecraft 版本的 jar 包 (debugbridge-1.19-*.jar、debugbridge-1.21.11-*.jar、debugbridge-26.1-*.jar 或 debugbridge-26.2-*.jar),将其放入实例的 mods/ 文件夹中,并使用 Fabric Loader 启动。仅限客户端——服务器端无需安装任何内容。 首次运行时,模组会在游戏内显示开发者警告,并在你接受之前保持非活跃状态;相同的验证机制会将 developer_mode_accepted 写入 config/debugbridge.json。一旦接受,内置 Web UI 位于 (游戏内启动消息会打印确切 URL)。

对于本地精确 26.1 Prism Launcher 实例,请使用仓库脚本:

JAVA_HOME_26_1=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home \
  PRISM_INSTANCE_NAME=26.1 \
  ./build-and-deploy-26.1.sh

要在不构建或不触碰实例的情况下检查选定的 Prism 实例、Java 路径、解析的 Gradle 版本、目标模组目录以及冒烟测试端口:

JAVA_HOME_26_1=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home \
  PRISM_INSTANCE_NAME=26.1 \
  ./build-and-deploy-26.1.sh --preflight

该脚本构建 mod/fabric-26.1,暂存 jar 包,使用 unzip -tq 进行验证,并原子式地将其替换到选定 Prism 实例的 mods/ 目录中。它会验证构建和暂存的 jar 包声明了确切的 Minecraft 26.1 版本以及 com.debugbridge.fabric261.DebugBridgeMod 入口点,然后才替换已安装的 jar 包。如果桥接在最终冒烟测试中使用非默认端口,请在调用脚本时设置 SMOKE_PORT=<port>; 部署后的命令提示将使用该端口。

构建

稳定的 1.x Fabric 模块需要 JDK 21+,fabric-26.1 和稳定版 26.2 需要 JDK 25(模块路径为 fabric-26.2-dev,与 26.x 版本清单声明的运行时匹配),Web UI 需要 Node >=20.19。

# Fabric mods
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew build
# JARs -> mod/fabric-*/build/libs/

# Exact 26.1 bridge
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :fabric-26.1:jar

# 26.2 stable bridge
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test :fabric-26.2-dev:jar

# Web UI
cd web-ui
npm install
npm run dev          # dev server at http://localhost:5173
npm run build        # production build → web-ui/dist/

测试

三层自动化,在关键处发力:

1. 核心单元测试 — 纯 JVM,不依赖 Minecraft。通过 .github/workflows/build.yml 在每个 PR 时运行。

cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test

覆盖 Groovy 桥接运行时、映射解析器内核(使用存根化的 Fabric SPI),以及每个端点的 wire-contract 测试(使用存根提供者)。

2. 针对实时模组的冒烟测试 — tools/smoke-test.mjs。通过 WebSocket 连接,调用每个内核候选端点并验证响应。耗时约 30 秒。需要 Node 22+ 以支持内置的 WebSocket 全局对象。

# 对正在运行的 1.21.11 模组进行冒烟测试
node tools/smoke-test.mjs --port 9876 --version 1.21.11

# 同时测试 1.19(默认端口:1.21.11=9876, 1.19=9877)
node tools/smoke-test.mjs --port 9877 --version 1.19

# 部署到 Prism 实例后,精确测试 26.1
node tools/smoke-test.mjs --port 9876 --version 26.1 --game-dir-contains '/instances/26.1/' --include-textures
node tools/record-video-smoke.mjs --port 9876 --version 26.1 --game-dir-contains '/instances/26.1/'

3. Wire-shape 回归模式 — 同一脚本配合 --regression DIR 使用。将每个实时响应的结构形状(各层级的键集合、值类型)与捕获的基准文件进行比较;发现漂移则失败。

# 在已知良好的构建后一次性捕获基线
node tools/smoke-test.mjs --port 9876 --version 1.21.11 \
    --fixtures tools/fixtures/1.21.11

# 之后,在新构建部署后,检查是否有漂移
node tools/smoke-test.mjs --port 9876 --version 1.21.11 \
    --regression tools/fixtures/1.21.11

形状比较器容忍值差异(瞬态游戏状态),但会标记任何结构性变化——新增/移除的键、类型不匹配。条件字段可能导致误报: snapshot.target 仅在玩家瞄准某物时才存在;nearbyEntities[].primaryEquipment 仅在最近的实体穿戴物品时才存在。请从内容丰富的状态中捕获基准文件,或将条件字段差异视为预期行为。

用法

与 Claude Code / MCP 一起使用

安装 mcdev-mcp 并在你的 MCP 客户端中进行配置。MCP 服务器会自动连接到 DebugBridge(扫描端口 9876–9886)。工具包括:

  • Runtime(需要此模组):mc_execute、mc_snapshot、mc_nearby_entities、mc_entity_details、mc_looked_at_entity、mc_nearby_blocks、mc_block_details、mc_screen_inspect、mc_chat_history、mc_screenshot、mc_record_video、mc_get_item_texture、mc_set_entity_glow、mc_set_block_glow、mc_clear_block_glow
  • Session control / dev loop(需要 session_control_enabled):mc_join_server、mc_leave_server、mc_quit_client,以及用于驱动 rebuild → relaunch → rejoin 循环的 mc_wait_for_bridge / mc_wait_until_in_world
  • Static(离线可用):mc_get_class、mc_get_method、mc_search、mc_find_refs、mc_find_hierarchy

直接 WebSocket

连接到 ws://127.0.0.1:9876 并发送 JSON:

{
  "id": "1",
  "type": "execute",
  "payload": {
    "code": "return player.blockPosition().toShortString()"
  }
}

每个请求都会收到一个匹配的 {id, type, payload} 响应。

record_video 存储

录制文件默认为临时文件,以免 AI 驱动的冒烟测试填满游戏目录:

{
  "id": "rec-1",
  "type": "record_video",
  "payload": {
    "frames": 120,
    "interval": "frame",
    "output": "grid",
    "storage": "temp",
    "ttlHours": 24
  }
}

storage 默认为 "temp",并写入系统临时目录下由 DebugBridge 拥有的子文件夹中。响应中包含 storage、directory 和 expiresAt。使用 "storage": "persistent" 可将输出保留在 <gameDir>/debugbridge-recordings/<requestId>/ 下;requestId 是一个可选的清理后的子目录名称,而非任意文件系统路径。

JAR 中捆绑的依赖

  • Apache Groovy 5.0.6 — JVM 脚本运行时(Apache-2.0)
  • Java-WebSocket 1.6.0 — WebSocket 服务器(MIT)
  • Gson 2.14.0 — JSON 解析(Apache 2.0)

许可证

MIT License — 详见 LICENSE 文件。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源