Chạy và xác minh tác nhân Minecraft Astra và JEV

Dự án làm gì

Tác nhân Minecraft Astra và JEV hoàn thành một tuyến đường Minecraft Java 1.16.5 được định trước bằng các quan sát trò chơi có cấu trúc và các hành động người chơi trong phạm vi giới hạn. GPT-6 Astra, hoặc tùy chọn GPT-5.6 Sol, lập kế hoạch mục tiêu, vật phẩm cần có và các điểm mốc di chuyển. Sau đó JEV chọn một hành động khả dụng, còn Mineflayer thực hiện việc di chuyển, tìm đường và các tương tác thông thường theo giao thức trò chơi.

Đây không phải là cơ chế điều khiển chỉ dựa trên ảnh chụp màn hình và cũng không mô phỏng từng lần nhấn phím riêng lẻ. Các mô hình nhận trạng thái có cấu trúc, bao gồm các khối trong những chunk đã tải và tọa độ được cung cấp cho seed đã biết. Các hành động khả dụng gồm di chuyển, đào một khối, nhặt vật phẩm rơi, chế tạo, mở rương, ăn, ngủ và tương tác chiến đấu.

Lần chạy được xác minh gần nhất, nether-final-08, hoàn thành trong 8 phút 43.300 giây. Lần chạy bắt đầu với kho đồ trống trong một thế giới Sinh tồn mới ở độ khó Bình yên, di chuyển qua Nether, tiêu diệt Ender Dragon bằng sáu vụ nổ giường ngay trong lần hạ cánh đầu tiên, rồi đi vào cổng thoát với đầy đủ máu và không chết lần nào. Lần chạy này sử dụng 131 quyết định JEV và 35 lần gọi Astra.

Dự án sử dụng máy chủ vanilla chính thức và gửi các hành động đã chọn qua giao thức người chơi thông thường. Cảm biến rồng Java chỉ đọc: cảm biến báo cáo chính xác vị trí đầu rồng nhưng không cấp vật phẩm, di chuyển thực thể, thay đổi máu hoặc thay đổi luật chơi.

Tính năng chính

• Phân tách vai trò mô hình: Astra hoặc Sol lập kế hoạch cho mục tiêu hiện tại, còn JEV chọn một hành động trong phạm vi giới hạn từ quan sát hiện tại.
• Tương tác Minecraft thông thường: Mineflayer xử lý việc di chuyển, tìm đường, tương tác với khối, chế tạo, thao tác kho đồ và giao tiếp qua giao thức.
• Tuyến đường hỗ trợ bởi Nether: Tuyến cố định sử dụng Nether làm đường tắt di chuyển trước khi chiến đấu ở The End.
• Quan sát rồng chỉ đọc: Một cảm biến Java cục bộ báo cáo vị trí đầu rồng để căn thời điểm đặt giường chính xác mà không sửa đổi trạng thái thực thể.
• Ghi hình bản địa: Một máy khách Minecraft Java 1.16.5 chính thức chạy ẩn kết xuất mô hình, kết cấu, hoạt ảnh, màn hình kho đồ, máu, thanh đói, không khí, trạng thái thanh vật phẩm nhanh, vật phẩm đang cầm và máu của rồng theo dạng bản địa.
• Điều khiển camera có giới hạn: Việc xoay camera được giới hạn ở mức 240 độ mỗi giây trên mỗi trục, với gia tốc 960 độ mỗi giây bình phương.
• Bằng chứng có cấu trúc: Nhật ký sự kiện JSONL, tệp trạng thái, bằng chứng chiến thắng, manifest video và các kiểm tra trạng thái thế giới hỗ trợ việc xác minh sau này.
• Kiểm thử tự động: Kho mã nguồn bao gồm các kiểm tra sự kiện hoàn thành, gói tin bản địa, chính sách hành động và việc hủy bộ tìm đường.

Kiến trúc và cấu hình mô hình

Mô hình lập kế hoạch mặc định là openai/gpt-6-astra, được gọi thông qua /api/v1/chat/completions. Bạn có thể chọn openai/gpt-5.6-sol thông qua biến môi trường PLANNER_MODEL. JEV sử dụng typesafe/jev-1.13 thông qua /api/alpha/decisions.

Mô hình lập kế hoạch không trực tiếp thực hiện các chuỗi hành động tùy ý. Mô hình xác lập mục tiêu hiện tại, các vật phẩm mong muốn và điểm mốc. JEV đánh giá quan sát có cấu trúc hiện tại rồi chọn một hành động được phép. Sự phân tách này giữ cho từng quyết định riêng lẻ nằm trong phạm vi giới hạn, đồng thời cho phép toàn bộ lần chạy tuân theo một kế hoạch dài hơn.

Yêu cầu và các giới hạn quan trọng

Các tập lệnh khởi chạy và kết xuất bản địa được phát triển trên macOS. Trên hệ điều hành khác, bạn phải điều chỉnh đường dẫn runtime, vị trí Java và cài đặt máy chủ cục bộ. Tập lệnh khởi chạy bản địa được cung cấp sử dụng runtime Java 17 cục bộ riêng.

Bạn cần Node.js và npm, Python 3 cho các tập lệnh máy khách bản địa, một runtime Java tương thích, Google Application Default Credentials, quyền truy cập vào một secret Google Secret Manager chứa khóa OpenRouter và đủ hạn mức OpenRouter. Các tệp nhị phân Minecraft, runtime đã tải xuống, thế giới đã lưu, bản ghi và thông tin xác thực được cố ý loại khỏi Git.

Cấu hình trò chơi được ghi chép là:

• Seed: 8398967436125155523
• Chế độ: Survival
• Độ khó sử dụng cho bản ghi đã xác minh: Peaceful
• Tâm cổng The End đang hoạt động: -1130, 34, 856
• Máy chủ chính: 127.0.0.1:25576
• Endpoint trạng thái: http://127.0.0.1:3078
• Endpoint cảm biến rồng cục bộ được tác nhân sử dụng: http://127.0.0.1:3093
• Cổng mirror giao thức bản địa: 25578

Seed này có một ngôi làng, ba rương tiếp tế chứa 21 obsidian và một cổng The End tự nhiên đang hoạt động. Tuyến đường được ghi chép không yêu cầu que blaze. Các tọa độ được khảo sát trong một thế giới kiểm thử riêng, nhưng việc di chuyển và đặt vật phẩm trong lần chạy cuối đều sử dụng tương tác người chơi thông thường.

Bước 1: Cài đặt các dependency Node.js

Từ thư mục gốc của kho mã nguồn, cài đặt các gói của dự án:

npm install

Thao tác này cài đặt các dependency JavaScript được tác nhân, bộ chuyển tiếp mô hình, logic tuyến đường, công cụ bằng chứng và các bài kiểm thử sử dụng.

Bước 2: Cấu hình quyền truy cập mô hình an toàn

Tác nhân cố ý bỏ qua biến môi trường chung OPENROUTER_API_KEY. Thay vào đó, các lệnh gọi mô hình tải khóa từ Google Secret Manager và chỉ giữ khóa trong bộ nhớ của tiến trình. Khóa không được xuất hiện trong các tệp mã nguồn hoặc nhật ký chạy.

1. Mở model-relay.mjs và models.mjs.
2. Thay thế các tham chiếu đến dự án Google Cloud và secret của bản triển khai ban đầu bằng các tham chiếu đến dự án của bạn.
3. Xác thực cục bộ bằng Google Application Default Credentials.
4. Cấp quyền cho danh tính đã xác thực để truy cập secret đã chọn.
5. Khởi động model relay theo thiết lập relay của kho mã.
6. Thiết lập URL relay khi khởi chạy agent:

MODEL_RELAY=http://127.0.0.1:3099

Không dán khóa OpenRouter vào mã nguồn, tập lệnh shell, nhật ký sự kiện hoặc siêu dữ liệu lần chạy. Dự án được thiết kế để lấy khóa từ Secret Manager và giữ khóa trong bộ nhớ của tiến trình.

Bước 3: Chuẩn bị máy chủ và trình quan sát rồng

Đặt JAR máy chủ Minecraft Java 1.16.5 vanilla tương thích tại server/server.jar. README lưu ý rằng môi trường chạy Minecraft Java đã cài đặt có thể chạy máy chủ này.

Trình quan sát rồng được triển khai trong observer/DragonObserver.java. Biên dịch bằng:

./build-observer.sh

Khởi động máy chủ chính cùng cảm biến chỉ đọc bằng:

./start-server.sh

Trình quan sát thêm một lệnh gọi quan sát chỉ dành cho cục bộ vào mỗi lượt xử lý của rồng trên máy chủ. Lệnh này phải luôn ở chế độ chỉ đọc; không thay đổi AI của rồng hoặc trạng thái của bất kỳ người chơi hay thực thể nào.

Tạo một thế giới thực sự mới

Thư mục lần chạy mới không đặt lại thế giới Minecraft. Trước khi ghi hình một lần chạy mới, hãy dừng máy chủ và chọn một level-name chưa được sử dụng trong server/server.properties. Giữ nguyên seed đã cấu hình, sau đó khởi động lại máy chủ.

Sử dụng cùng tên mới đó cho thư mục nhật ký của lần chạy. Giữ lại các thế giới trước đó nếu chúng là một phần bằng chứng của các lần chạy trước.

Bước 4: Cài đặt và biên dịch client native

Client native ẩn cung cấp phần kết xuất Minecraft chính thức được sử dụng trong các bản ghi hình mới. Cài đặt các dependency phía Python và biên dịch bộ điều hợp hiển thị và ghi hình:

python3 native-client/install.py
./native-client/build.sh

Client sử dụng một thư mục trò chơi tách biệt nên không ghi đè các thiết lập Minecraft thông thường của người dùng. Tính năng lấy nét desktop và điều khiển con trỏ bị vô hiệu hóa, còn việc ghi hình đọc framebuffer của trò chơi thay vì ghi lại desktop.

Bước 5: Cố định cấu hình lần chạy

Chọn một mã định danh duy nhất, được biểu diễn bên dưới là NEW_RUN. Cố định lần chạy trước khi khởi chạy agent:

node optimization/nether/freeze-run.mjs NEW_RUN

Tuyến đường cuối cùng được định nghĩa trong optimization/nether/config.json. Việc cố định lần chạy giúp bảo toàn cấu hình gắn với nhật ký và bản ghi hình tạo ra từ lần chạy đó.

Bước 6: Khởi động agent

Khởi chạy agent từ thư mục gốc của kho mã. Lệnh sau chọn Astra, bật chế độ xem native và trình ghi, chờ client native, rồi kết nối với cảm biến rồng:

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

Nếu URL relay chưa có trong môi trường của tiến trình, hãy thêm 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

Để sử dụng Sol làm planner, hãy thay đổi giá trị model:

PLANNER_MODEL=openai/gpt-5.6-sol

Bước 7: Khởi chạy client Minecraft ẩn

Chờ đến khi máy chủ phản chiếu giao thức cục bộ lắng nghe trên cổng 25578. Sau đó mở một terminal khác và chạy:

python3 native-client/launch.py

Vì WAIT_NATIVE=1 đã được bật, agent sẽ chờ client ẩn và trình ghi trước khi thực hiện hành động đầu tiên. Trình ghi dừng sau sự kiện cổng thoát.

Bản ghi hình tạo ra được thiết kế ở độ phân giải 960 × 540, tốc độ 20 khung hình/giây và không có âm thanh. Bản ghi có thể hiển thị máu, đói, thanh vật phẩm nhanh, vật phẩm đang cầm, màn hình kho đồ và chế tạo, hoạt ảnh native và máu của rồng.

Giám sát và dừng lần chạy an toàn

Trạng thái hiện tại có tại endpoint trạng thái cục bộ:

http://127.0.0.1:3078

Tiến độ hiện tại cũng được ghi vào status.json. Để yêu cầu dừng ở ranh giới hành động, hãy tạo tệp sau:

runs/NEW_RUN/stop

Không lập tức kết thúc client native sau khi lần chạy kết thúc. Hãy chờ dấu hiệu hoàn tất bản ghi:

runs/NEW_RUN/full-playthrough.mp4.finished.json

Điều này giúp tránh làm bản ghi cuối bị cắt ngắn hoặc hỏng.

Tìm hiểu bằng chứng được tạo ra

Mỗi lần chạy lưu bằng chứng trong runs/<run>. Các tệp quan trọng nhất gồm:

• events.jsonl: các yêu cầu, phản hồi của model, hành động đã chọn, kết quả trò chơi và sự kiện hoàn tất.
• status.json: tiến độ mới nhất của lần chạy.
• victory.json: chỉ được tạo khi có bằng chứng bắt buộc về cái chết của rồng và cổng thoát.
• full-playthrough.mp4: bản ghi native khi tính năng ghi hình được bật.
• full-playthrough.mp4.finished.json: xác nhận quá trình hoàn tất bản ghi đã hoàn thành.

Bằng chứng về cái chết của rồng có thể là thành tựu hạ rồng hoặc máu bằng 0 do máy chủ báo cáo kết hợp với giai đoạn hấp hối của rồng. Điểm khác biệt này quan trọng vì việc hạ rồng bằng giường có thể không tạo thành tựu hạ rồng. Với Java 1.16.5, sự kiện thoát sử dụng lý do dạng số 4.

Một bản đánh giá cuối hợp lệ không nên chỉ dựa vào victory.json. Bản đánh giá cũng phải kiểm tra trạng thái DragonFight của thế giới và video.

Chạy các bước kiểm tra tự động

Sử dụng bộ kiểm thử Node của repository để kiểm tra các sự kiện hoàn tất, gói tin mirror native, chính sách hành động và việc hủy pathfinder:

node --test evidence.test.mjs native-mirror.test.mjs optimization/*.test.mjs optimization/pass-2/policy.test.mjs optimization/nether/*.test.mjs

Các bài kiểm thử này không thay thế cho việc xác thực trực tiếp. Di chuyển, chế tạo, chiến đấu, tích hợp máy chủ và ghi hình vẫn cần được kiểm thử trên một máy chủ Minecraft đang chạy.

Cách hoạt động của chiến đấu ở End

Triển khai chiến đấu trong end-combat.mjs cung cấp một đòn tấn công bằng giường có giới hạn để JEV lựa chọn. Hành động này đặt một chiếc giường, ngắm vào nó, chờ đến khi đầu rồng được quan sát đi vào khoảng thời gian tấn công đã cấu hình, rồi gửi một lệnh sử dụng.

Hành động sẽ bị hủy nếu người chơi mất chỗ nấp hoặc nếu hơi thở rồng đi vào khu vực che chắn. Theo README, việc tinh chỉnh cục bộ đã tăng sát thương từ 11 lên 46 cho mỗi giường bằng cách ngắm trước khi sử dụng và thu hẹp khoảng thời gian tấn công.

Lần chạy được xác minh cuối cùng đã hạ rồng bằng sáu vụ nổ giường ngay trong lần đáp đầu tiên. Tuy nhiên, thời điểm rồng bay và đáp thay đổi giữa các lần chạy, vì vậy không thể đảm bảo thời gian hoàn tất giống hệt nhau.

Sử dụng đúng combat lab

Thư mục combat-lab là một môi trường kiểm thử riêng biệt. Môi trường này có thể sử dụng vị trí, kho đồ và các thay đổi kiểm thử khác đã được chuẩn bị sẵn. Trình điều khiển được mã hóa cứng, combat-probe.mjs, sử dụng cổng 25577 và không gọi bất kỳ model nào.

Không bao giờ trình bày kết quả của combat lab như một lần chạy Survival hoàn chỉnh do model điều khiển. Kết quả phòng lab chỉ xác thực hành vi chiến đấu riêng lẻ, không xác thực toàn bộ lộ trình từ kho đồ trống.

Mẹo ghi hình và xác minh nâng cao

Thêm và xác minh lớp phủ thông tin

Repository mô tả quy trình lớp phủ, bổ sung một banner trong suốt ở phía trên hiển thị tên model, số mili giây đã trôi qua, tọa độ XYZ, mục tiêu của planner và hành động được chọn. Các nhãn này dựa trên phản hồi model và sự kiện trò chơi đã ghi lại.

Đối với lần chạy ví dụ được mô tả, hãy tạo và xác minh lớp phủ bằng:

node overlay.mjs nether-final-02
node verify-run.mjs nether-final-02 nether-final-02 full-playthrough-overlay.mp4

Đối với bản ghi Prismarine Viewer cũ hơn, các lệnh được mô tả là:

node assemble-video.mjs recorded-06
node verify-run.mjs recorded-06

Quy trình recorded-06 cũ sử dụng Prismarine Viewer và HUD tùy chỉnh. Các bản ghi mới sử dụng client Minecraft Java 1.16.5 chính thức thông qua mirror giao thức chỉ đọc.

Bảo toàn thời gian tạm dừng và lịch sử cập nhật mã

Nếu bản ghi chứa nhiều tệp ghi hình vì agent cần cập nhật mã, hãy bảo toàn mọi phần chơi đang diễn ra. Đánh dấu từng khoảng tạm dừng cập nhật trong video kết hợp và báo cáo tất cả lần chết cũng như thời gian tạm dừng. Không được mô tả lần chạy như không bị gián đoạn hoặc không có người chết trừ khi mô tả đó chính xác.

Tránh các chiến lược vào cổng không an toàn

Một bài kiểm thử trong lab cho thấy cú rơi dài xuống cổng End có thể mang sát thương do rơi vào End. Lộ trình được ghi lại đã loại bỏ chiến lược đó và thay vào đó sử dụng các bước đào xuống ngắn, có kiểm tra. Hãy giữ ràng buộc an toàn này khi sửa đổi hành vi của lộ trình.

Giữ trạng thái chiến thắng ở dạng kết thúc

Triển khai hiện tại ngăn không cho thực hiện hành động trò chơi khác sau khi chiến thắng. Hãy giữ nguyên hành vi này nếu bạn sửa vòng lặp hành động, vì các hành động sau chiến thắng có thể khiến log và bản ghi khó diễn giải hơn.

Giữ artifact cục bộ ngoài Git

Bản ghi và bằng chứng được tạo ra được giữ cục bộ theo thiết kế. Đường dẫn được ghi lại của video mới nhất là runs/nether-final-08/full-playthrough-banner.mp4, cùng với dữ liệu xác minh, so sánh thời gian và log hành động trong cùng thư mục lần chạy. Không commit bản ghi, runtime đã tải xuống, tệp nhị phân máy chủ, thế giới hoặc thông tin xác thực.

Danh sách kiểm tra khắc phục sự cố

• Agent không bắt đầu: Xác nhận mirror đang lắng nghe trên cổng 25578 và client native đã kết nối. Khi WAIT_NATIVE=1, việc chờ là hành vi dự kiến.
• Yêu cầu model thất bại: Xác minh Google Application Default Credentials, quyền Secret Manager, tham chiếu project và secret trong model-relay.mjs và models.mjs, relay khả dụng trên cổng 3099 và credit OpenRouter.
• Lần chạy bắt đầu trong thế giới cũ: Dừng máy chủ và đặt một level-name thực sự chưa được sử dụng. Chỉ tạo một thư mục lần chạy mới là chưa đủ.
• Không có dữ liệu quan sát rồng: Build observer, khởi động máy chủ với sensor của observer và xác nhận agent sử dụng DRAGON_SENSOR_URL=http://127.0.0.1:3093.
• Không xuất hiện dấu hiệu bản ghi hoàn tất: Để client native tiếp tục chạy cho đến khi full-playthrough.mp4.finished.json được ghi.
• Đường dẫn dành riêng cho nền tảng không hoạt động: Điều chỉnh đường dẫn Java, runtime Minecraft, client native và máy chủ vì các script được phát triển trên macOS.

Kết luận

Dự án Astra và JEV minh họa một agent Minecraft có cấu trúc, định hướng bằng bằng chứng, thay vì một game bot không bị giới hạn. Astra hoặc Sol lập kế hoạch lộ trình, JEV chọn các hành động có giới hạn, Mineflayer thực thi chúng thông qua giao thức thông thường và một sensor chỉ đọc hỗ trợ chiến đấu với rồng một cách chính xác. Một lần chạy đáng tin cậy yêu cầu xử lý thông tin xác thực cẩn thận, một thế giới thực sự mới, ghi hình native đồng bộ, log được bảo toàn, các bài kiểm thử tự động và việc xem xét cuối cùng cả trạng thái trò chơi lẫn bằng chứng video.

Để tìm hiểu về các nền tảng liên quan, hãy tham khảo bài giới thiệu chính thức của TypeSafe, kho lưu trữ Mineflayer và tài liệu chính thức về mô hình Astra.