Minecraft代理项目：Astra规划器与JEV控制器

rmalde/minecraft-agent

本项目使用 GPT-6 Astra 或 GPT-5.6 Sol 进行规划，并使用 JEV 在 Minecraft Java 1.16.5 中选择玩家动作。它使用官方原版服务器（vanilla server）和 Mineflayer。一个只读的 Java 传感器可以报告精确的末影龙头部位置。它不会改变游戏规则或实体状态。每个被选中的动作都通过正常的玩家协议发送到游戏中。

Latest verified result

最新一次运行 nether-final-08 用时 8 分 43.300 秒完成。之前的录像用时 14 分 31.800 秒。新的运行缩短了 40%。末地战斗阶段用时 152 秒，而之前为 332 秒。龙的飞行和落地时间在不同运行之间会有所差异。

该代理从一个全新的 Survival/Peaceful 世界中以空库存开始。Astra 负责规划，JEV 选择动作。它在下界（the Nether）中行进，在首次落地时用六次床爆杀死了末影龙，并以满血、零死亡到达了出口。在整个运行过程中没有重启、没有改动源码，也没有操作员介入修复。

该运行共使用了 131 次 JEV 决策和 35 次 Astra 调用。所有 17 项运行检查、8 项路线/镜头/画面检查以及 29 项本地测试全部通过。完整的早期录像和动作日志在本地测试和新的录制之前已审阅过。

摄像机控制使用连续的转动，每个轴的限速为每秒 240 度，加速度为每秒 960 度的平方。一个隐藏的原生 Minecraft 客户端在不接收桌面输入的情况下渲染游戏画面。捕获内容包括生命值、饥饿值、快捷栏（hotbar）、手持物品、物品栏、合成界面以及原生动画。

录像分辨率为 960 × 540，帧率 20 帧每秒，无音频。半透明的全宽顶部横幅使用 Menlo 字体，显示模型名称、已用毫秒数、XYZ 坐标、规划器目标以及所选动作。这些标签使用已记录的响应和游戏事件。

录制内容和生成的证据保留在本地，并被排除在 Git 之外。

本地录像位于 runs/nether-final-08/full-playthrough-banner.mp4。其校验、计时对比和动作日志位于同一运行目录中。本仓库包含代码、测试、构建脚本和路线数据。它不包括 Minecraft 二进制文件、已下载的运行时、保存的世界或凭据。

Credentials

模型调用从 Google Secret Manager 获取 OpenRouter 密钥，并将其保存在进程内存中。当前的脚本引用了原始部署的项目和密钥名称；这些名称不是凭据。请在 model-relay.mjs 和 models.mjs 中为你自己的项目配置这些引用。对于中继，需要使用 Google application default credentials 进行身份验证，并授权访问该密钥，然后在启动代理时设置 MODEL_RELAY=http://127.0.0.1:3099。不要将密钥放入源文件或运行日志中。

原生渲染器和启动脚本是在 macOS 上开发的。运行时路径和本地服务器设置必须为另一台机器进行配置。历史评审记录描述了早期版本；请使用当前代码以及上面的结果来获取最新行为。

Game settings

- Seed:
- Mode: Survival
- Difficulty: Peaceful（本次录制）
- Verified active End portal center: -1130, 34, 856
- Main server: 127.0.0.1:25576
- Native display: hidden read-only Minecraft client
- Status: http://127.0.0.1:3078所选种子包含一个村庄、三个装有 21 块黑曜石的物资箱，以及一个天然激活的末地传送门。该路线利用下界作为通行捷径，并要求在战斗前完成进出。它不需要烈焰棒。这是一个实用的速通种子，但不证明它就是最简单的种子。该路线在单独的一个测试世界中勘测过。终局放置与移动使用普通的玩家交互。

Model roles

规划器（planner）设置当前目标、物品目标和行进路点。JEV 从当前游戏观测中选取一个可用动作。动作包括行进、挖掘一个方块、收集掉落物、合成、打开箱子、进食、睡眠以及战斗交互。Mineflayer 处理移动路径和游戏协议。这是结构化状态控制，而非基于截图或单个按键的控制。模型可以看见已加载区块中的方块。已提供已知种子的坐标。

- Model IDs: openai/gpt-6-astra（默认）或 openai/gpt-5.6-sol（PLANNER_MODEL），通过 /api/v1/chat/completions
- typesafe/jev-1.13，通过 /api/alpha/decisions密钥从 Google Secret Manager 加载到进程内存中。通用环境变量 OPENROUTER_API_KEY 会被忽略，以防止误用无关密钥。该密钥不会被写入运行日志。

Files and evidence

runs/<run>/events.jsonl 存储请求、模型响应、所选动作、游戏结果和完成事件。

status.json 存储当前进度。victory.json 文件需要龙死亡证据和离开传送门事件。死亡证据可以是进度达成（kill advancement）或服务器提供的零生命值加上末影龙死亡阶段。Java 1.16.5 的退出事件使用数值原因 4。最终审阅还必须检查世界 DragonFight 状态和录像。床杀可以省略进度达成。

新的录制使用官方 Minecraft Java 1.16.5 客户端。一个只读的本地协议镜像向此客户端发送游戏状态。录像中包含原生实体模型、纹理、移动、挖掘和手部动画、快捷栏、手持物品、生命值、饥饿值、气泡条以及末影龙生命值。捕获分辨率为 960 × 540，帧率 20 帧每秒，无音频。窗口为隐藏状态；焦点和光标控制被禁用。捕获读取游戏帧缓冲区（frame buffer），而非桌面内容。较早的 recorded-06 录像使用的是 Prismarine Viewer 和自定义 HUD。

combat-lab 目录是一个独立的测试服务器。它可以使用预先准备的物品和位置来测试战斗代码。combat-lab 的结果不能算作完整的 Survival 运行。

Start a run

使用 npm install 安装依赖。从 server 目录使用兼容的 Java 运行时启动 server/server.jar。已安装的 Minecraft Java 运行时可用于此服务器。

使用 ./start-server.sh 以其只读传感器启动主服务器。如需进行新的录制，首先在 server/server.properties 中选择一个未被占用的世界名称。使用相同的新建日志目录。从该目录启动代理：

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

当本地镜像在 25578 端口监听时，启动 python3 native-client/launch.py。代理会在执行第一个动作前等待隐藏的客户端和录制器启动。原生客户端使用一个隔离的游戏目录。它不会更改用户的 Minecraft 设置。录制器在退出传送门事件后停止。如需在动作边界停止测试，创建 runs/NEW_RUN/stop。在关闭原生客户端之前，请等待 full-playthrough.mp4.finished.json 生成。

原生客户端的依赖通过 python3 native-client/install.py 安装；通过 ./native-client/build.sh 构建显示与捕获适配器。提供的启动脚本使用其本地 Java 17 运行时。模型访问需要可用的 OpenRouter 额度。

仅新建一个日志目录并不会重置世界。停止服务器，选择一个未被占用的新 level-name，并使用相同的种子重新启动。请将旧世界作为证据保留。

运行 node --test evidence.test.mjs native-mirror.test.mjs optimization/*.test.mjs optimization/pass-2/policy.test.mjs optimization/nether/*.test.mjs 来检查完成事件、原生数据包、动作策略以及寻路取消逻辑。针对移动、合成、战斗和录制的实时服务器测试仍然是必需的。

Sources

- Official TypeSafe introduction and Doom demo: 结构化游戏状态、类型化决策以及实时动作循环。
- JEV Minecraft demo: 作者通过 Mineflayer 描述 JEV 选择。
- Minecraft demo source: 同时记录了有界直接动作和更早的批量动作。
- Mario example: 结构化观测和小规模合法动作集。
- StarCraft example: 有界动作、记录的模型概率以及显式的胜利检查。
- StarCraft Twitter post: 通过公开的 JEV 项目索引找到；Twitter 直接访问被拦截。
- TypeSafe launch Twitter post: 直接访问被拦截。
- New seed human speedrun.
- Previous seed report: Java 1.16 种子与传送门坐标。
- One-cycle guide: 床的支撑、掩体和时机。
- Mineflayer、Pathfinder 和 Prismarine Viewer。
- Official Astra model documentation.

Combat implementation

end-combat.mjs 提供一个有界（bounded）的床攻击。JEV 选择该动作。该动作会放置一张床，对准它，并在观察到的龙头部进入攻击窗口之后执行一次 use 命令。如果玩家失去掩体或气泡进入掩体，则中止。本地测试中，每次床的攻击伤害从 11 提升到了 46，方法是先瞄准再收紧窗口。稍后一个预准备测试使用七张床杀死了末影龙，最终剩余 13 点生命值，期间没有使用伤害保护。其证据位于 combat-lab/eight-bed-test-03.jsonl。该测试使用了本地测试驱动、预准备物品和预先准备好的末影龙打法。Sol 和 JEV 的首次完整流程在 practice-02 中成功完成。

observer/DragonObserver.java 为服务器龙逻辑添加一个只读观测调用。其 HTTP 端点仅限本地。使用 ./build-observer.sh 构建。该传感器的任何部分都不会给予物品、移动玩家、改变生命值或更改末影龙的 AI。

combat-probe.mjs 是一个硬编码到 25577 端口的本地测试驱动。它不调用任何模型，也绝不应作为模型控制的运行来展示。combat-lab 文件包含预准备的位置、物品以及其他测试改动。

床的时机研究也使用了 AltoClef 的床战斗源码。本项目中的动作实现是独立的。

Recording and control limits

最终路线已在 optimization/nether/config.json 中固定。Astra 接收游戏状态和路线观测；JEV 选择有界动作。Mineflayer 执行寻路和定时方块交互。这不是仅基于截图或单个按键的控制。原生视图镜像了机器人的状态。其摄像机使用小幅转动，物品栏界面显示当前物品和光标状态。最终运行没有使用任何实时操作员指导或修复。

一次录制如果代理需要代码更新，可能包含多个捕获文件。请保留所有活跃的游戏过程。需在合并后的视频中标注每次更新暂停。请报告死亡和暂停；不要把这样的录制描述为无死亡或不间断的运行。

新的原生视频是一段连续的捕获。使用 node overlay.mjs nether-final-02 添加信息条。使用 node verify-run.mjs nether-final-02 nether-final-02 full-playthrough-overlay.mp4 进行校验。如要重建较早的 viewer 视频，请运行 node assemble-video.mjs recorded-06，并使用 node verify-run.mjs recorded-06 进行校验。原始捕获文件、动作日志、视频清单和世界均已保留。较早的 viewer 清单记录了它的开发暂停；这些不适用于新的连续录制。overlay 会将退出事件标记为完成。当前代码在胜利之后会阻止执行其他游戏动作。

分离实验室中的一项测试显示，长距离落入末地传送门会把坠落伤害带进末地。该提议的动作被拒绝。录制的玩家改用短距、经过检查的向下挖掘台阶。