minecraft-builder-mcp/docs/IMPLEMENTATION.md

Состояние реализации

Первый прототип собран и проверен на настоящем локальном Paper 26.2, включая графический клиент камеры в Prism и передачу изображения через MCP. Он ещё не закрывает всю v0.1 из дизайна: первый авторизованный ход Codex через ACP остаётся непроверенным.

Реализованные компоненты

world-core содержит независимый от Bukkit редактор. Декларативный рецепт превращается в неизменяемый план с исходными и желаемыми состояниями, явными зависимостями чтения и сроком действия. Перед записью выполняется проверка; непосредственно при записи состояния сверяются повторно. Дисковые намерения сохраняются до изменения мира, результаты — после порции. Файловый ввод-вывод вынесен с серверного потока. Отмена останавливает следующие порции; уже записанное остаётся в истории.

paper-plugin привязывает это ядро к серверному потоку, проверяет владельца, мир, эпоху, область и защищённые части. HTTP доступен только на loopback, с отдельными ключами администратора и агента. Плагин регистрирует /ai, хранит небольшую очередь чата, пересылает ответы только инициатору и управляет телепортацией наблюдателя. Журнал и метаданные находятся в каталоге плагина, игровые блоки остаются ванильными.

bridge предоставляет 14 инструментов MCP по stdio, принимает события чата Paper и запускает закреплённый codex-acp. Диалоги разделены по игроку и проекту, очередь сериализована, остановка распространяется на ACP. Идентификатор сессии и компактная сводка сохраняются. Агент получает отдельный MCP-токен; ключ администратора остаётся у Bridge. Большие ответы ограничены, изображения передаются как MCP image content.

camera-mod содержит локальный HTTP Worker и захват framebuffer Minecraft 26.2. Камера ждёт spectator, нужную позицию и измерение, доступность соседних чанков и стабилизацию кадров. Настройки HUD/FOV восстанавливаются после снимка или ошибки. На настоящем клиенте Prism проверены Mixin, серверная телепортация и валидные PNG с нескольких ракурсов. Владелец и наблюдатель использовали один UUID.

Подтверждённые проверки

Текущая сборка: 100 автоматических тестов без ошибок — 52 в ядре, 17 в Paper-модуле, 20 в Bridge и 11 в модуле камеры. Оба JAR собраны; результаты Java находятся в XML-отчётах Maven/Gradle, общий лог этой проверки — .runtime/build-final.log.

Автоматические Java-тесты проверяют геометрию, ограничения, идемпотентность, зависимости чтения, конфликты, прерывание порции, отмену, undo, журналирование, ошибки диска, восстановление и отдельные HTTP/NBT-контракты. Тесты Bridge используют настоящий MCP stdio и имитатор ACP для диалогов, разрешений, отмены и возобновления. Камера имеет проверки HTTP-аутентификации и валидации, без запуска графического клиента.

На настоящем Paper, в отдельном созданном тестовом мире, успешно выполнены:

• Изменение блока после подготовки плана: операция завершается конфликтом, чужой блок сохраняется.
• Изменение явной зависимости: применение останавливается до записи.
• Постройка, повтор с тем же ключом и проверяемая отмена; при более поздней внешней правке undo отвергается.
• Отмена операции, защита неподдерживаемого исходного блока и отказ за пределами области.
• Принудительное завершение собственного процесса сервера во время 4096-блочной операции, повторный запуск, recovery_required без автоматического воспроизведения.
• Административный разбор восстановления: агентскому ключу отказано, устаревший digest отвергнут, отказ от продолжения сохраняет текущее содержимое мира и разрешает новые операции после записи решения на диск. Защита части не мешает разбору, но продолжает запрещать запись в неё.
• Полый куб через настоящий MCP: 26 блоков; экспорт .schem, библиотека ассетов, undo, импорт на тот же anchor и повторный undo до 27 блоков воздуха.
• Отсутствующая камера возвращает ошибку, без подмены изображения.
• После установки мода в Prism построена 575-блочная башня и получены четыре реальных снимка 1280×720. Последний прошёл весь путь Camera → Paper → Bridge → MCP ImageContent. Первый запрос с изменившимся ракурсом завершился отказом; повтор при неподвижном клиенте успешен. Протокол проверки.

Реальный codex-acp прошёл initialize в отдельном профиле без входа: ACP v1 и поддержка загрузки сессии подтверждены. Это ещё не проверка хода модели или вызова инструментов после авторизации. Тесты не вызывали модель и не расходовали её токены.

Существенные границы

Ручные изменения. Сравнение ожидаемого и текущего состояния защищает от отличающегося блока непосредственно перед записью. Известные события установки/ломания игроком дополнительно инвалидируют владение блока для undo, даже если игрок вернул прежний материал. Полного перехвата изменений других плагинов, команд, физики и всех переходов A→B→A нет; ревизии известных внешних событий пока не сохраняются между запусками. Нельзя считать этот прототип универсальной системой слияния любых параллельных правок.

Авария. JSON-журнал с fsync заменяет запланированную SQLite. Мир Minecraft и наш журнал не образуют одну транзакцию. Неоднозначная операция после сбоя блокирует новые записи. Доступен явный административный обзор и отказ от продолжения по свежему digest, без изменения мира и с отключением неоднозначного undo. Автоматического replay/rollback нет. Полный журнал загружается при старте и пока не имеет архивирования.

Область и производительность. Один владелец, проект и мир; не более 4096 блоков и 512 явных зависимостей на план. Запись — до 128 блоков с целевым бюджетом до 5 мс на порцию; стоимость проверки и JVM не позволяют заявлять жёсткую гарантию времени тика. Полная подготовка ограниченного плана пока выполняется на серверном потоке. Долговременные нагрузочные проверки на большом сервере не проводились.

Контекст. Контекст проекта содержит краткие метаданные, до 20 операций и до 64 частей; точные блоки читаются отдельно. region_changes пока возвращает resync_required. Поэтому агент повторно читает выбранные участки; обещание «читает только дельты» ещё не реализовано. Диалог ACP имеет сохранение и сводку, но расход модели здесь не измерен.

Блоки и схематики. Разрешён ограниченный набор из 61 ванильного материала, включая часть ступеней и плит; точный список возвращает project_context. Waterlogged, контейнеры, двери, redstone и другие сложные блоки не поддерживаются. Проверка окружающих блоков намеренно ограничивает использование возле неподдерживаемой среды. Sponge v2 .schem реализован без зависимости от WorldEdit: до 4096 блоков, до 64 файлов, повороты кратно 90°, без сущностей, block entities и биомов, без преобразования между версиями игры. Неподдерживаемый контент отвергается, а не удаляется при экспорте.

Строительный язык. Есть box, line, cylinder и repeat. Арки, произвольные трансформации, декоративные палитры, исполнение JavaScript/Python и автоматическое согласование рецептов с ручными правками пока отсутствуют. Зарегистрированная часть содержит точную маску фактически записанных блоков, а не весь её bounding box.

Камера. Нужен настроенный spectator-клиент; в проверенном сценарии это тот же игрок, что и владелец проекта. Во время снимка он не может продолжать обычное строительство. Автоматического возврата режима и исходной позиции нет. Готовность кадра эвристическая: serverRevisionVerified: false. Доступность соседних чанков и стабильность рендера не доказывают получение всех серверных обновлений. Реальная стройка и снимки проверены; сторонние шейдеры, отключение посреди кадра и все варианты зависания окна ещё не проверены.

ACP. Выделены отдельные HOME/CODEX_HOME, отключены лишние интеграции, shell и передача административного токена. Это не изоляция на уровне ОС. Закреплённый адаптер переводит режим read-only в workspace-write; временные пути могут оставаться доступными, а закреплённый CLI оставляет флаг unified_exec включённым при отключённом shell_tool. Дополнительные запросы разрешений пока отклоняются. Поведение разрешений динамического Minecraft MCP требует проверки первого настоящего хода. Подробности и диагностика — в Bridge README.

Следующий приёмочный этап

1. Пользователь входит в выделенный Codex-профиль, подключается к Paper и привязывает владельца. Проверяем маленькую постройку из игрового /ai, поток ответа, использование MCP и отмену.
2. Расширяем проверенный сценарий Prism с одним клиентом: проверяем отключение/зависание посреди снимка и удобное переключение между строительством и камерой.
3. Проходим цикл «построил → посмотрел → исправил» и только после этого уточняем готовность релиза, лимиты, дельты контекста и расширение геометрии.