rmalde/minecraft-agent

Astra planner and JEV controller for Minecraft, with native recording, tested routes, and run verification.

Astra 与 JEV Minecraft 代理

这是什么 – 一个开源机器人，通过结合两种语言模型服务，完整游玩 Minecraft Java 1.16.5 速通（末影龙战斗）：

Astra（或较旧的 Sol）作为规划器：根据当前世界状态，设定高层目标、物品目标和路径点。
JEV 接收规划器的目标和详细游戏观察，从有限集合中选择一个具体动作（移动、挖掘、合成、进食、战斗等）。

机器人通过标准玩家协议（通过 Mineflayer 库）与原版服务器通信。一个隐藏、只读的 Minecraft 客户端镜像游戏状态以进行视频录制；机器人不会修改任何游戏规则或实体。

运作方式

组件	角色
服务器	官方原版 1.16.5 服务器（提供于 `server/`）。运行自定义 Java 传感器（`DragonObserver`），通过本地 HTTP 端点暴露龙头位置。
Mineflayer	Node‑JS 库，实现玩家连接、路径寻找和低层动作（挖掘、放置、攻击、打开箱子等）。
规划器（Astra / Sol）	通过 OpenRouter（`/api/v1/chat/completions`）调用。接收完整结构化观察（方块、库存、坐标），返回目标和路径点。
JEV	Typesafe 的决策模型（`typesafe/jev-1.13`），通过 `/api/alpha/decisions` 访问。从当前观察中选择一个合法动作。
原生客户端与录制器	一个隐藏 Minecraft 客户端（从源码构建）渲染世界，并以 960 × 540 @ 20 fps 录制视频，叠加显示模型名称、时间、坐标、目标和选择的动作。
胶水脚本	`nether-agent.mjs` 编排循环：读取传感器 → 发送给规划器 → 发送规划器输出和观察给 JEV → 通过 Mineflayer 执行选定动作。

所有通信皆为文本形式；模型从未看到截图。机器人可以看到已加载区块中的方块数据，并获得种子码和已知传送门坐标。

快速开始

先决条件
- Node ≥ 18、Java 17、Python 3、存储在 Google Secret Manager 中的本地 OpenRouter API 密钥。
- Minecraft Java 1.16.5 客户端（仓库不包含它）。

安装

npm install               # Node 依赖
cd native-client && python3 install.py && ./build.sh

启动服务器

cd server && ./start-server.sh   # 使用提供的种子码启动 server.jar

运行全新代理（将 NEW_RUN 替换为唯一名称）

PLANNER_MODEL=openai/gpt-6-astra RUN_ID=NEW_RUN \
NATIVE_VIEW=1 WAIT_NATIVE=1 NATIVE_RECORD=1 \
DRAGON_SENSOR_URL=http://127.0.0.1:3093 \
node nether-agent.mjs NEW_RUN

脚本会在第一次动作前等待隐藏原生客户端（python3 native-client/launch.py）。

验证
```
node --test evidence.test.mjs native-mirror.test.mjs ...
```
测试检查运行是否产生所需的胜利证据（victory.json），以及所有策略检查是否通过。

成功证据

README 记录了完整运行（nether‑final‑08），用六次床爆炸击杀末影龙，以满血离开传送门，并在 8 分 43 秒内完成 – 比先前最佳快 40%。
日志（runs/<run>/events.jsonl）包含每个模型请求/响应、选定动作和游戏结果。
本地存储的视频（full-playthrough-banner.mp4）显示隐藏客户端渲染、叠加 HUD 和最终胜利事件。
自动化测试（evidence.test.mjs、combat‑lab 脚本）验证龙死亡条件和世界状态与记录的证据相符。

范围与限制

速通专用 – 路线、种子码和世界配置固定；机器人不是通用 Minecraft AI。
只读传感器 – 机器人无法授予物品、修改生命值或改变龙 AI；它只发出正常玩家动作。
模型成本 – 每次运行约 35 次规划器调用和 130 次 JEV 决策；需要 OpenRouter 点数。
平台 – 开发脚本针对 macOS；其他操作系统需要手动调整路径。

下一步探索

optimization/nether/config.json – 固定路线和路径点。
observer/DragonObserver.java – 龙头传感器的源码。
combat-lab/ – 床爆炸战斗逻辑的隔离测试环境。
链接的 TypeSafe 和 OpenAI 文档以获取更深入的模型 API 细节。

结论 – 此仓库提供一个可重现、全自动的 Minecraft 速通机器人，展示使用大型语言模型（Astra）和类型化决策模型（JEV）的结构化状态控制。这是 LLM 驱动的具身代理在复杂、实时虚拟环境中运作的具体示例。