星枢 AI 开源项目趋势分析 查看项目

JavaScript · 项目报告

rmalde/minecraft-agent

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

已完成 打开 GitHub
R
532星标
52Fork
3Issue
未知许可证

分析结果

项目分析

该仓库是一个面向 Minecraft Java 1.16.5 的 AI 智能体实验项目，使用 Astra/Sol 作为高层规划器，使用 JEV 进行动作选择，并通过 Mineflayer 与原版 Minecraft 服务端交互。项目目标是在固定种子、固定路线和可验证证据链下完成从空背包生存开局到击败末影龙的完整流程。README 声称最新验证运行 nether-final-08 用时 8 分 43.300 秒，使用下界捷径、和平难度、自然激活末地传送门和床爆击杀末影龙，并提供事件日志、状态文件、视频录制和验证脚本等本地证据机制。该项目更像是 AI 游戏控制、自动化验证和 Minecraft speedrun 路线实验的研究原型，而不是开箱即用的通用 Minecraft 机器人。

适用领域 AI 游戏智能体 / Minecraft 自动化 / 大模型规划 / 强化/决策模型应用 / Mineflayer 机器人开发 / 游戏状态观测与动作选择 / 自动化测试与运行验证 / Minecraft Speedrun 路线实验 / 视频录制与证据链生成
配置难度 高。需要同时理解 Node.js、Mineflayer、Minecraft Java 服务端、Java 传感器、Python 原生客户端启动、视频捕获、GCP Secret Manager、OpenRouter 模型调用以及多进程本地端口协作。对于只想运行普通 Minecraft Bot 的开发者来说配置复杂；对于熟悉 Minecraft 自动化和 AI Agent 的开发者，仍需要较长时间适配本机环境并排查运行链路。
商业价值 中等偏低到中等。该项目的直接商业化价值有限，因为它依赖固定游戏版本、固定路线、外部模型和未声明许可证，且目标是研究性 Minecraft 通关实验。不过它在 AI Agent 架构、游戏自动化测试、可验证运行日志、游戏录制证据链和结构化状态决策方面具有较高参考价值。对游戏 AI 研究团队、自动化测试平台、Agent 评测基准和游戏内容生成/验证工具开发者来说，可作为技术原型和灵感来源。
01

技术亮点

  • 设计上区分高层规划器 Astra/Sol 与低层动作选择器 JEV，便于研究多层 Agent 架构。
  • 使用结构化游戏状态和有限动作集合，而不是纯截图控制或逐键盘鼠标输入，降低了控制复杂度。
  • 基于 Mineflayer 与官方原版服务端协议交互，没有通过修改游戏规则或直接篡改实体状态完成任务。
  • 提供只读 DragonObserver，用于获取末影龙头部位置，辅助床爆时机判断。
  • 包含完整运行日志机制：events.jsonl、status.json、victory.json 以及完成事件验证。
  • 支持隐藏原生 Minecraft 客户端渲染和帧缓冲捕获，录制内容包含血量、饥饿值、快捷栏、物品、动画和末影龙血量等。
  • README 对运行条件、种子、路线、端口、模型角色和验证标准描述较详细。
  • 提供多类测试，覆盖证据事件、native mirror packet、动作策略和 pathfinder 取消等逻辑。
  • 末影龙战斗实现有明确的有界床攻击动作，包含瞄准、等待攻击窗口、失去掩体中止等安全逻辑。
  • 强调证据留存、视频复核和不得将 combat-lab 准备环境冒充完整生存运行，实验边界说明较清楚。
02

目标用户

  • 研究 AI Agent 在游戏环境中决策与执行的开发者
  • 熟悉 Node.js、Minecraft 服务端和 Mineflayer 的工程师
  • 希望复现实验性 Minecraft 自动通关流程的技术用户
  • 研究大模型规划器与低层动作控制结合方式的开发者
  • 对 Minecraft Speedrun 路线、下界旅行和末影龙战斗自动化感兴趣的玩家或研究者
  • 需要构建游戏运行日志、视频证据和自动验证流程的开发者
03

配置要求

  • Minecraft Java 1.16.5 原版服务端，默认主服务端地址为 127.0.0.1:25576。
  • 固定种子：8398967436125155523。
  • 推荐或验证配置为 Survival 模式、Peaceful 难度。
  • 需要配置 server/server.properties，尤其是 level-name，新的日志目录不会自动重置世界。
  • 需要可用的 OpenRouter 模型访问额度。
  • OpenRouter API Key 不从 OPENROUTER_API_KEY 读取，而是通过 Google Secret Manager 加载。
  • 需要 Google Application Default Credentials，并授予访问对应 Secret 的权限。
  • 需要修改 model-relay.mjs 和 models.mjs 中原作者部署所使用的 GCP 项目和 secret 名称。
  • 运行 agent 时需要设置 MODEL_RELAY=http://127.0.0.1:3099。
  • 默认规划模型为 openai/gpt-6-astra，也可通过 PLANNER_MODEL 使用 openai/gpt-5.6-sol。
  • JEV 模型接口使用 typesafe/jev-1.13。
  • Dragon 只读传感器默认地址示例为 http://127.0.0.1:3093。
  • 状态服务默认地址为 http://127.0.0.1:3078。
  • 原生隐藏客户端和录制脚本主要在 macOS 上开发，其他系统需要调整运行路径、本地服务端路径和 Java 运行时配置。
  • 原生客户端启动脚本使用本地 Java 17 runtime。
  • 录制文件、事件日志、生成证据、Minecraft 二进制、运行时、世界存档和凭证不会包含在 Git 仓库中，需要本地自行准备或生成。
04

适用场景

  • 复现固定种子下的 Minecraft 自动通关实验
  • 研究大模型如何根据结构化游戏状态制定阶段性目标
  • 测试 JEV 或类似决策模型在有限动作集合中的选择能力
  • 基于 Mineflayer 开发 Minecraft 自动化任务，例如移动、采集、开箱、合成、睡觉、战斗等
  • 分析 Minecraft 路线规划、下界捷径和床爆末影龙战斗的自动化实现
  • 构建带有事件日志、状态文件、胜利验证和视频录制的游戏实验证据系统
  • 开发或改造 Minecraft Java 客户端的隐藏渲染、录制和状态镜像工具
05

部署与配置

  • 安装 Node.js 环境，并在仓库根目录执行 npm install 安装 JavaScript 依赖。
  • 准备 Minecraft Java 1.16.5 官方服务端，将 server.jar 放在 server 目录下，并确保使用兼容的 Java 运行时。
  • 根据 README 构建只读 DragonObserver 传感器：执行 ./build-observer.sh。
  • 启动主服务端及只读传感器：执行 ./start-server.sh。
  • 如需原生隐藏客户端录制，先安装 Python 依赖：执行 python3 native-client/install.py。
  • 构建原生显示和捕获适配器：执行 ./native-client/build.sh。
  • 为新运行选择未使用的 world 名称，修改 server/server.properties 中的 level-name，并为 runs 目录准备同名日志目录。
  • 冻结或准备运行配置，例如执行 node optimization/nether/freeze-run.mjs NEW_RUN。
  • 配置模型访问：在 Google Secret Manager 中保存 OpenRouter Key，并修改 model-relay.mjs 和 models.mjs 中的项目与 secret 引用。
  • 启动模型 relay 后，设置 MODEL_RELAY=http://127.0.0.1:3099。
  • 启动 agent，例如：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。
  • 当本地 mirror 监听 25578 端口后，启动隐藏原生客户端：python3 native-client/launch.py。
  • 运行测试可使用：node --test evidence.test.mjs native-mirror.test.mjs optimization/*.test.mjs optimization/pass-2/policy.test.mjs optimization/nether/*.test.mjs。
06

风险与注意事项

  • README 中提到的 GPT-6 Astra、GPT-5.6 Sol 等模型名称和接口可能不是公开可用或稳定可用资源，复现高度依赖原作者环境。
  • 项目严重依赖外部模型服务、OpenRouter 额度、Google Secret Manager 和特定 relay 配置，普通开发者上手成本较高。
  • 原生渲染与录制工具主要在 macOS 开发，跨平台运行可能需要大量路径、依赖和脚本修改。
  • 没有声明 license，商业使用、二次分发和代码复用存在法律不确定性。
  • 最新运行的视频和证据文件明确不包含在 Git 中，外部用户无法仅凭仓库完整验证 README 中的成绩。
  • 运行结果依赖固定种子、固定路线、Peaceful 难度、自然激活末地传送门和已知坐标，不代表通用 Minecraft 通关能力。
  • 使用只读龙头传感器和已知 seed 坐标，对研究纯视觉或未知环境智能体的用户参考价值有限。
  • live server 行为、移动、合成、战斗和录制仍需真实服务器测试，单元测试不能完全保证实际运行成功。
  • Minecraft 版本固定为 Java 1.16.5，升级到其他版本可能涉及协议、实体行为、末地事件和服务端差异。
  • 端口、世界名、运行目录、模型 relay、本地客户端、传感器等组件较多，配置错误容易导致运行失败或证据不完整。
  • Speedrun 场景存在龙飞行、降落时间等随机性，即使代码不变也可能产生不同耗时。
  • 项目更像研究演示和实验系统，而非可维护的生产级框架。

历史记录

热榜历史快照

2026-09-24 第29名 新收录 · github_search