原创 开源 工具 BlackBoxPro —— 专为AI Agent 全自动为 Minecraft 服务器插件、mod自动化测试 2.2.4

[MD] # BlackBoxPro — Minecraft 自动化黑盒测试框架 > 像真实玩家一样操作，像自动化测试一样验证。 > 模组版本需要额外开发，如有需要请反馈 GitHub Issues 或自主开发 --- ## 这是什么？ BlackBoxPro 是一套面向 Minecraft 服务端插件开发者的**自动化黑盒测试框架**。 它由两部分组成：安装在客户端的 **Mod** 和安装在服务端的 **Plugin**。服务端通过 Plugin Message Channel 或 HTTP API 向客户端下发 JSON 指令，Mod 在客户端**模拟真实玩家的一切行为**——走路、挖矿、打开箱子、点击 GUI、输入聊天、截图——然后将执行结果回传给服务端。 你不再需要手动登录游戏反复测试，也不需要写 Mock 来伪造客户端行为。BlackBoxPro 让你的测试脚本直接驱动一个真实的 Minecraft 客户端。 --- ## 能做什么？ ### 112 个 Action，覆盖玩家能做的一切 | 能力 | 举例 | | ---------- | ------------------------------------------------------------ | | 移动与寻路 | 走到指定坐标、A* 寻路、看向目标、跳跃、潜行、冲刺 | | 方块交互 | 挖掘方块、放置方块、使用物品 | | 实体交互 | 攻击实体、右键交互、挥手 | | 容器操作 | 打开箱子、点击槽位、Shift 转移、悬停查看 Tooltip | | 聊天与命令 | 发送消息、执行命令、点击聊天中的可点击文本 | | 截图验证 | 普通截图、Tooltip 渲染截图，保存到本地供视觉比对 | | 状态查询 | 玩家状态、背包物品、方块信息、记分板、Boss Bar、聊天历史等 17 种查询 | | 复合行为 | 批量执行、挖掘方块（自动看向+挖掘+等待）、合成配方 | | 客户端控制 | 连接服务器、创建/加入/离开世界、修改客户端设置 | ### 双通道通讯 ``` 服务端插件 ──── Plugin Message Channel ────▶ 客户端 Mod 外部工具 ──── HTTP POST :38081 ──────────▶ 客户端 Mod 外部工具 ──── HTTP POST :38080 ──────────▶ 服务端插件 ──▶ 客户端 Mod ``` - **Plugin Message Channel**：服务端插件直接向在线玩家的 Mod 下发指令，适合集成测试 - **HTTP API**：任何外部工具（Python 脚本、CI 流水线、Postman）都能通过 HTTP 直接调用，零依赖接入 ### 物理引擎驱动的移动 不是简单的 `setPosition` 传送。BlackBoxPro 通过 `InjectedInput` 注入键盘输入，让 Minecraft 原生物理引擎处理碰撞、重力、速度，移动行为与真实玩家完全一致。 --- ## 支持的版本 | Minecraft | Mod Loader | 说明 | | --------- | ----------------- | ----------------------- | | 1.21.11 | Fabric / NeoForge | 最新版，112 个 Action | | 1.21.1 | Fabric / NeoForge | 112 个 Action | | 1.12.2 | Forge | 兼容子集，105 个 Action | 服务端插件基于 Paper/Spigot + TabooLib，兼容主流服务端。 --- ## 快速上手 ### 1. 安装 - 将对应版本的 Mod jar 放入客户端 `mods/` 目录 - 将 Plugin jar 放入服务端 `plugins/` 目录 - 启动服务端和客户端，玩家加入服务器后自动建立通讯通道 ### 2. 发送第一条指令 通过服务端命令： ``` /blackbox exec <玩家名> query_player_state ``` 或通过 HTTP API： ```bash curl -X POST http://localhost:38081/execute \ -H "Content-Type: application/json" \ -d '{"id":"test-1","action":"query_player_state","params":{}}' ``` 响应： ```json { "id": "test-1", "status": "success", "data": { "x": 100.5, "y": 64.0, "z": -200.3, "health": 20.0, "food": 20, "gameMode": "survival", "dimension": "minecraft:overworld" } } ``` ### 3. 编写测试脚本 用任何语言通过 HTTP API 编写自动化测试： ```python import requests, time API = "http://localhost:38081/execute" def action(action_id, params=None): resp = requests.post(API, json={ "id": f"test-{time.time()}", "action": action_id, "params": params or {} }) return resp.json() # 走到商店 NPC 面前 action("navigate_to", {"x": 100, "y": 64, "z": -200, "speed": 1.0}) # 右键交互 NPC（实体 ID 42） action("interact_entity", {"entityId": 42}) # 等待 GUI 打开，查询容器状态 time.sleep(1) result = action("query_container_slots", {"windowId": 1}) # 截图留证 action("screenshot", {"testId": "shop_test", "prefix": "npc_gui"}) # 验证第一个槽位的物品 slots = result["data"]["slots"] assert slots[0]["itemId"] == "minecraft:diamond_sword" print("Test passed!") ``` ### 4. 服务端插件 API（Java/Kotlin） ```kotlin // 异步调用，CompletableFuture 风格 val future = BlackBoxApi.request(player, "query_player_state") future.thenAccept { response -> val health = response.data?.get("health")?.asDouble println("玩家血量: $health") } // 批量执行 BlackBoxApi.fire(player, "batch", JsonObject().apply { add("actions", gson.toJsonTree(listOf( mapOf("action" to "sneak_start"), mapOf("action" to "wait", "params" to mapOf("ticks" to 20)), mapOf("action" to "sneak_stop") ))) }) ``` --- ## 典型使用场景 | 场景 | 做法 | | ------------ | --------------------------------------------------------- | | 商店插件测试 | 走到 NPC → 右键打开 GUI → 点击购买槽位 → 查询背包验证物品 | | 传送系统测试 | 执行 `/warp spawn` → 查询玩家坐标 → 断言位置正确 | | 权限系统测试 | 以不同权限玩家执行命令 → 验证返回消息 | | GUI 视觉回归 | 打开 GUI → 截图 → 与基准图对比 | | 战斗系统测试 | 切换武器 → 攻击实体 → 查询实体血量变化 | | 聊天交互测试 | 触发带 ClickEvent 的消息 → 模拟点击 → 验证效果 | | 记分板验证 | 查询 sidebar 记分板 → 断言分数与预期一致 | --- ## 项目架构 ``` BlackBoxPro/ ├── common/ # 共享协议层（JSON 消息模型） ├── mod/ │ ├── 1.21.11/ # Fabric + NeoForge（runtime 共享核心） │ ├── 1.21.1/ # Fabric + NeoForge │ └── 1.12.2/ # Forge（独立构建） └── plugin/ # Bukkit 服务端插件（TabooLib） ``` - Kotlin 全栈，Gradle 多模块聚合构建 - `runtime` 模块承载跨 Loader 共享逻辑，Fabric/NeoForge 仅保留平台胶水代码 - CI/CD 通过 GitHub Actions 自动构建，push 到 main 即发布 Release --- ## 开源地址 **GitHub**: [https://github.com/YsGqHY/BlackBoxPro](https://github.com/YsGqHY/BlackBoxPro) MIT 协议开源，欢迎 Star、Fork、提 Issue。 --- ## 构建 ```bash # 全量构建 ./gradlew buildAll # 产物收集在 build/libs/ 目录 ``` 也可以直接从 [GitHub Releases](https://github.com/YsGqHY/BlackBoxPro/releases) 下载预编译 jar。 [/MD]