项目功能
Astra 和 JEV Minecraft 智能体使用结构化游戏观测和受限的玩家操作，完成预定义的 Minecraft Java 1.16.5 路线。GPT-6 Astra，或可选的 GPT-5.6 Sol，会规划目标、物品目标和旅行路标。随后，JEV 选择一个可用操作，而 Mineflayer 负责移动、寻路和常规游戏协议交互。
这不是仅基于截图的控制，也不会模拟单个键盘按键。模型接收结构化状态，包括已加载区块中的方块，以及已知种子所提供的坐标。可用操作包括移动、挖掘一个方块、收集掉落物、合成、打开箱子、进食、睡觉和战斗交互。
最近一次经过验证的运行 nether-final-08 用时 8 分钟 43.300 秒 完成。它在和平难度的新生存世界中以空背包开始，穿越下界，在第一次着陆时使用六次床爆炸杀死末影龙，随后满血且零死亡进入返回传送门。本次运行使用了 131 次 JEV 决策和 35 次 Astra 调用。
该项目使用官方原版服务器，并通过标准玩家协议发送选定的操作。其 Java 龙传感器是只读的：它报告龙头的精确位置，但不会授予物品、移动实体、修改生命值或改变游戏规则。
主要功能
- 模型角色分离：Astra 或 Sol 规划当前目标，而 JEV 根据当前观测从受限操作中选择一个操作。
- 标准 Minecraft 交互：Mineflayer 处理移动、寻路、方块交互、合成、背包操作和协议通信。
- 借助下界的路线：固定路线在末地战斗前利用下界作为旅行捷径。
- 只读龙观测：本地 Java 传感器报告龙头位置，以便精确安排床爆炸时机，同时不修改实体状态。
- 原生录制：隐藏的官方 Minecraft Java 1.16.5 客户端渲染原生模型、纹理、动画、背包界面、生命值、饥饿值、空气值、快捷栏状态、手持物品和龙的生命值。
- 受控摄像机移动：摄像机每个轴的转动速度限制为每秒 240 度，加速度为每秒平方 960 度。
- 结构化证据：JSONL 事件日志、状态文件、胜利证据、视频清单和世界状态检查支持后续验证。
- 自动化测试：代码库包含对完成事件、原生数据包、操作策略和寻路器取消功能的检查。
架构与模型配置
默认规划器模型是 openai/gpt-6-astra，通过 /api/v1/chat/completions 调用。你可以通过 PLANNER_MODEL 环境变量选择 openai/gpt-5.6-sol。JEV 通过 /api/alpha/decisions 使用 typesafe/jev-1.13。
规划器不会直接执行任意操作序列。它会确定当前目标、所需物品和路标。JEV 评估当前的结构化观测，并选择一个允许的操作。这种分离使单次决策保持受限，同时让整个运行能够遵循更长期的计划。
要求与重要限制
启动脚本和原生渲染脚本是在 macOS 上开发的。在其他操作系统上，你必须调整运行时路径、Java 位置和本地服务器设置。随附的原生启动脚本使用其自带的本地 Java 17 运行时。
你需要 Node.js 和 npm、用于原生客户端脚本的 Python 3、兼容的 Java 运行时、Google Application Default Credentials、对包含 OpenRouter 密钥的 Google Secret Manager 密钥的访问权限，以及足够的 OpenRouter 余额。Minecraft 二进制文件、下载的运行时、保存的世界、录制文件和凭据均有意排除在 Git 之外。
文档所述的游戏配置如下：
- 种子：
8398967436125155523 - 模式：
Survival - 验证录制所使用的难度：
Peaceful - 启用的末地传送门中心：
-1130, 34, 856 - 主服务器：
127.0.0.1:25576 - 状态端点：
http://127.0.0.1:3078 - 智能体使用的本地龙传感器端点：
http://127.0.0.1:3093 - 原生协议镜像端口：
25578
该种子包含一个村庄、三个补给箱（内含 21 个黑曜石）以及一个自然激活的末地传送门。文档所述路线不需要烈焰棒。坐标是在单独的测试世界中测量的，但最终运行中的移动和放置均使用标准玩家交互。
步骤 1：安装 Node.js 依赖
在代码库根目录中安装项目软件包：
npm install这会安装智能体、模型中继、路线逻辑、证据工具和测试所使用的 JavaScript 依赖。
步骤 2：配置安全的模型访问
智能体会有意忽略通用的 OPENROUTER_API_KEY 环境变量。相反，模型调用会从 Google Secret Manager 加载密钥，并仅将其保存在进程内存中。密钥不应出现在源文件或运行日志中。
- 打开
model-relay.mjs和models.mjs。 - 将原始部署中的 Google Cloud 项目和密钥引用替换为你自己的项目引用。
- 使用 Google 应用默认凭据在本地进行身份验证。
- 授予已验证身份访问所选密钥的权限。
- 按照仓库中的中继设置启动模型中继。
- 启动代理时设置中继 URL：
MODEL_RELAY=http://127.0.0.1:3099不要将 OpenRouter 密钥粘贴到源代码、Shell 脚本、事件日志或运行元数据中。项目设计为从 Secret Manager 获取密钥，并将其保存在进程内存中。
步骤 3：准备服务器和龙观察器
将兼容的原版 Minecraft Java 1.16.5 服务器 JAR 放置在 server/server.jar。README 说明，已安装的 Minecraft Java 运行时可以运行此服务器。
龙观察器实现在 observer/DragonObserver.java 中。使用以下命令构建：
./build-observer.sh使用以下命令启动主服务器及其只读传感器：
./start-server.sh观察器会向服务器的龙 tick 添加一个仅限本地的观测调用。它必须保持只读，不得更改龙的 AI，也不得更改任何玩家或实体状态。
创建真正全新的世界
新的运行目录不会重置 Minecraft 世界。在开始全新录制前，停止服务器，并在 server/server.properties 中选择一个未使用的 level-name。保持已配置的种子不变，然后重启服务器。
对运行日志目录使用相同的新名称。当之前的世界构成早期运行的证据时，请保留它们。
步骤 4：安装并构建原生客户端
隐藏的原生客户端提供新录制中使用的官方 Minecraft 渲染。安装其 Python 端依赖，并构建显示与捕获适配器：
python3 native-client/install.py
./native-client/build.sh客户端使用独立的游戏目录，因此不会覆盖用户正常的 Minecraft 设置。桌面焦点和光标控制已禁用，捕获读取游戏帧缓冲区，而不是录制桌面。
步骤 5：冻结运行配置
选择一个唯一标识符，以下以 NEW_RUN 表示。在启动代理前冻结运行：
node optimization/nether/freeze-run.mjs NEW_RUN最终路线定义在 optimization/nether/config.json 中。冻结运行有助于保留与其生成的日志和录制相关联的配置。
步骤 6：启动代理
从仓库根目录启动代理。以下命令选择 Astra，启用原生视图和录制器，等待原生客户端，并连接到龙传感器：
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如果进程环境中尚未设置中继 URL，也要将其加入：
MODEL_RELAY=http://127.0.0.1:3099 \
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若要改用 Sol 作为规划器，请更改模型值：
PLANNER_MODEL=openai/gpt-5.6-sol步骤 7：启动隐藏的 Minecraft 客户端
等待本地协议镜像监听 25578 端口。然后打开另一个终端并运行：
python3 native-client/launch.py由于已启用 WAIT_NATIVE=1，代理会等待隐藏客户端和录制器就绪后再执行首次操作。录制器会在退出传送门事件发生后停止。
生成的捕获内容设计为 960 × 540 分辨率、每秒 20 帧且无音频。它可以显示生命值、饥饿值、快捷栏、手持物品、背包和合成界面、原生动画以及龙的生命值。
安全监控并停止运行
可通过本地状态端点查看当前状态：
http://127.0.0.1:3078当前进度也会写入 status.json。若要请求在操作边界处停止，请创建以下文件：
runs/NEW_RUN/stop运行结束后不要立即终止原生客户端。请等待录制完成标记：
runs/NEW_RUN/full-playthrough.mp4.finished.json这有助于避免最终捕获内容被截断或损坏。
了解生成的证据
每次运行都会将证据存储在 runs/<run> 下。最重要的文件包括：
events.jsonl：请求、模型响应、选定操作、游戏结果和完成事件。status.json：最新的运行进度。victory.json：仅当存在所需的龙死亡和退出传送门证据时生成。full-playthrough.mp4：启用录制时生成的原生录制文件。full-playthrough.mp4.finished.json：确认录制最终处理已完成。
龙死亡证据可以是击杀进度，或服务器报告的零生命值与龙处于死亡阶段的组合。这一区别很重要，因为使用床击杀可能不会产生击杀进度。对于 Java 1.16.5，退出事件使用数字原因 4。
有效的最终审查不应仅依赖 victory.json。还应检查世界的 DragonFight 状态和视频。
运行自动化检查
使用仓库的 Node 测试套件检查完成事件、原生镜像数据包、操作策略和寻路器取消功能：
node --test evidence.test.mjs native-mirror.test.mjs optimization/*.test.mjs optimization/pass-2/policy.test.mjs optimization/nether/*.test.mjs这些测试不能替代实时验证。移动、制作、战斗、服务器集成和录制仍需在运行中的 Minecraft 服务器上进行测试。
末地战斗的工作方式
end-combat.mjs 中的战斗实现向 JEV 暴露了一次有边界的床攻击，供其选择。该操作会放置一张床、瞄准床位，等待观测到的龙头进入配置的攻击窗口，然后发送一次使用指令。
如果玩家失去掩体，或龙息进入掩体区域，该操作就会中止。根据 README，通过在使用前瞄准并收紧攻击窗口，本地调优将每张床造成的伤害从 11 提高到了 46。
最终验证运行在龙首次落地时通过六次床爆炸击杀了末影龙。不过，末影龙的飞行和降落时机在不同运行之间会有所变化，因此无法保证完成时间完全相同。
正确使用战斗实验环境
combat-lab 目录是独立的测试环境。它可能使用预设位置、物品栏以及其他测试修改。其中的硬编码驱动程序 combat-probe.mjs 使用端口 25577，并且不会调用任何一个模型。
切勿将 combat-lab 的结果描述为完整的模型控制生存模式运行。实验室结果只能验证隔离的战斗行为，不能验证从空物品栏开始的完整路线。
高级录制与验证技巧
添加并验证信息叠加层
仓库记录了一套叠加层工作流：添加半透明顶部横幅，显示模型名称、经过的毫秒数、XYZ 坐标、规划器目标和所选操作。这些标签基于记录的模型响应和游戏事件。
对于文档中的示例运行，使用以下命令创建并验证叠加层：
node overlay.mjs nether-final-02
node verify-run.mjs nether-final-02 nether-final-02 full-playthrough-overlay.mp4对于较早的 Prismarine Viewer 录制，文档中的命令如下：
node assemble-video.mjs recorded-06
node verify-run.mjs recorded-06较早的 recorded-06 工作流使用 Prismarine Viewer 和自定义 HUD。新录制通过只读协议镜像使用官方 Minecraft Java 1.16.5 客户端。
保留暂停和代码更新历史
如果一次录制包含多个捕获文件，原因是代理需要代码更新，则应保留每个有效的游戏过程片段。在合并视频中标记每次更新暂停，并报告所有死亡和暂停。除非描述准确，否则不得将此类运行描述为不间断或零死亡。
避免不安全的传送门进入策略
一项实验室测试显示，长距离坠落进入末地传送门可能会将摔落伤害带入末地。记录的路线拒绝了这一策略，改为使用短距离、经过检查的向下挖掘步骤。修改路线行为时应保留这一安全约束。
保持胜利状态终止
当前实现会阻止胜利后执行其他游戏操作。如果修改操作循环，请保留此行为，因为胜利后的操作可能使日志和录制内容更难解读。
不要将本地产物加入 Git
录制文件和生成的证据按设计保留在本地。最新视频的文档路径为 runs/nether-final-08/full-playthrough-banner.mp4，其验证结果、时间对比和操作日志位于同一运行目录中。不要提交录制文件、下载的运行时、服务器二进制文件、世界存档或凭据。
故障排查清单
- 代理没有开始运行：确认镜像正在监听端口
25578，并且原生客户端已经连接。使用WAIT_NATIVE=1时，等待是预期行为。 - 模型请求失败：验证 Google Application Default Credentials、Secret Manager 权限、
model-relay.mjs和models.mjs中的项目与密钥引用、端口3099上的中继可用性，以及 OpenRouter 额度。 - 运行从旧世界开始：停止服务器并设置一个确实未使用过的
level-name。仅创建新的运行目录是不够的。 - 无法获取末影龙观测结果：构建观测器，启动带有其传感器的服务器，并确认代理使用
DRAGON_SENSOR_URL=http://127.0.0.1:3093。 - 没有出现录制完成标记：保持原生客户端运行，直到写入
full-playthrough.mp4.finished.json。 - 平台特定路径失败：调整 Java、Minecraft 运行时、原生客户端和服务器路径，因为提供的脚本是在 macOS 上开发的。
结论
Astra 和 JEV 项目展示的是一种结构化、以证据为导向的 Minecraft 代理，而不是不受限制的游戏机器人。Astra 或 Sol 规划路线，JEV 选择有边界的操作，Mineflayer 通过常规协议执行这些操作，而只读传感器则支持精确的末影龙战斗。可靠的运行需要谨慎处理凭据、真正全新的世界、同步的原生录制、完整保留的日志、自动化测试，以及对游戏状态和视频证据进行最终审查。
如需了解相关基础，请参阅TypeSafe 官方介绍、Mineflayer 代码库以及Astra 模型官方文档。