Kodlo/ue-toolchain
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9d52cfa5b90a6108932251b4057b79624b75edfb
ue-toolchain/docs/handoff.md
T
ue-toolchain ee80ce6338 docs(adr-0005): narrow ADR-0001 to what the native transport leaves open 
The engine now ships an MCP server, a toolset registry and skill assets --
measured against a live editor rather than read about. Building a second
transport beside it is not a contest this project can win.

ADR-0001 is narrowed, not withdrawn. Its liveness reasoning survives intact:
process over file, tools that vanish honestly, recovery without a restart.
Three mechanisms are dropped (own JSON-RPC server, UDP-broadcast discovery, own
heartbeat) and discovery becomes a probe of the documented endpoint, which the
measurement showed gives a fast negative -- HTTP 404 with a routing error body,
no hang. That is the property the PID file could not provide.

Two layers stay ours: a server that runs without the engine, and tools that run
in a live game outside the editor, the layer the registry's editor-only
declaration leaves uncovered.

The load-bearing claim is flagged as not yet attempted: a runtime tool answering
in a packaged build. Until that runs it is derived, not measured.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 01:43:18 +07:00

15 KiB
Raw Blame History

Handoff: LyraResearch → ue-toolchain

Дата: 2026-09-01 Сессия: Hermes, модель mini-max/m3 Состояние: решено зафиксировать, начата реализация

Документ исторический. Не читать как текущее состояние. Он верно описывает развилку 2026-09-01 и сохраняется ради причин, по которым решения приняты именно так. Что изменилось с тех пор:

Сказано здесь Как на 2026-09-05
«Скиллы не перенесены», 14 штук перенесены: 17 скиллов, 232 записи, plugins/ue-design-skills/
компонент skills/ в корне репозиторий — маркетплейс, бандл на уровень глубже (ADR-0002)
«Лицензия TBD, планируется MIT» (вопрос 2) решено: проза CC BY-ND 4.0, код Apache-2.0 (ADR-0003)
docs/licensing-options.md как открытый выбор материал к решению, само решение — в ADR-0003
целевая версия UE открыта (вопрос 5) платформа — 5.8; решено 2026-09-06 прогнать все 232 рецепта по 5.8-дереву и развести версии по результату
фазы 1–2: свой мост и MCP-сервер сужены ADR-0005: транспорт берём у движка
вопрос 1, публичность приватный Gitea git.kodlo.art; remote ещё не заведён

Открытыми остаются вопросы 1, 3, 4 и 5 из §6.

1. Что произошло

Проект LyraResearch (D:\LLM\ClaudePJs\LyraResearch) — это research-песочница и библиотека скиллов для проектирования на UE 5.6, выращенная из разбора Epic Lyra. Содержит:

  • STRATEGY.md — стратегия разбора
  • LyraStarterGame/ — эталон Epic Lyra 5.6 (НЕ трогаем)
  • .claude/skills/local/ — 14 скиллов для UE-проектирования
  • notes/ — 30+ заметок со ссылками файл:строка
  • plans/ — 3 плана дальнейших работ
  • _tools/ — 20 парсеров/генераторов на Python

Проблема: проект был жёстко завязан на Overmind (NextGenium) — пути D:\Work\NG\..., Perforce-правила, конфигурация под конкретный редактор. Скиллы и инструменты не переносились в чужие проекты без переписывания.

Решение: сделать из LyraResearch самостоятельный публичный продукт ue-toolchain, не зависящий от NextGenium и от конкретного проекта.

2. Целевой продукт

ue-toolchain — набор инструментов для разработки на UE через LLM-агентов.

Состав:

Компонент Назначение Статус
Engine/ UE-плагин редактора (C++): JSON-RPC, discovery, мониторинг не начат
mcp-server/ MCP-сервер на Python: инструменты для Hermes/Claude Code/Codex не начат
skills/ Скиллы для LLM-агентов не перенесён из LyraResearch
installer/ CLI: установка плагина + регистрация MCP + скиллы не начат
docs/ ADR и документация 1 ADR готов
examples/ Минимальный UE-проект для тестов не начат

Форма: комплекс (плагин + MCP-сервер + скиллы + установщик + локальная автодокументация).

Аудитория: публичный релиз. README, лицензия, тесты на нескольких версиях UE, документация инструментов.

Название: ue-toolchain. Репозиторий ue-toolchain, пакет ue-toolchain-mcp.

3. Что сделано в этой сессии

Создан репозиторий D:\LLM\ClaudePJs\ue-toolchain\

ue-toolchain/
├── .git/
├── .gitignore
├── README.md
└── docs/architecture/decisions/
    └── 0001-discovery-over-pid-file.md

Зафиксирован ADR-0001: Discovery over PID file

Файл: docs/architecture/decisions/0001-discovery-over-pid-file.md Коммиты: cec48f6 (initial), ff491e8 (clean-up)

Суть решения:

VibeUE (текущий MCP-сервер для UE) привязан к PID-файлу на диске. Это создаёт четыре проблемы:

  1. Cold start требует существующего файла → 60-секундные зависания.
  2. После закрытия редактора MCP-сервер остаётся зомби (файл есть, процесса нет).
  3. Два редактора → конфликт за один файл, случайный победитель.
  4. Перезапуск редактора требует перезапуска MCP.

Решение: UDP-broadcast discovery на 127.0.0.1:8088 (loopback-only), TCP для данных, heartbeat каждые 5 секунд, graceful degradation.

Архитектура MCP-сервера:

┌─────────────────────────────────────────────────────────────┐
│ MCP server (всегда работает, не зависит от UE)              │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ filesystem   │  │ project      │  │ editor tools     │  │
│  │ tools        │  │ analysis     │  │ (только если     │  │
│  │ (всегда)     │  │ tools        │  │  есть соединение)│  │
│  │              │  │ (всегда)     │  │                  │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Ключевые принципы:

  • Процесс — источник истины, не файл.
  • Файловые и аналитические инструменты работают без редактора.
  • Редакторные инструменты появляются в tools/list только при живом соединении.
  • @mcp.tool(requires_editor=True/False) фильтрует видимость.
  • Multi-instance: два редактора не конфликтуют (UDP + TCP-порт на инстанс).
  • Heartbeat каждые 5с, 3 пропуска → инструменты скрываются.
  • Авто-recovery без перезапуска MCP.

Confirmation criteria (будут проверяться при реализации):

  • Cold start <1с без редактора → только файловые инструменты.
  • Cold start <1с с редактором → + редакторные инструменты после discovery.
  • Закрытие редактора → редакторные инструменты исчезают за ≤15с, нет зависаний tools/call.
  • Перезапуск редактора → инструменты возвращаются за ≤5с, без рестарта MCP.
  • Два редактора → --project= выбирает нужный; без флага — первый ответ (детерминированно, с логом).

Что НЕ вошло в ADR-0001 (явно):

  • Удалённый сценарий (редактор на одной машине, агент на другой) — отложен до реального запроса, не упреждается.
  • Конкретная версия UE — будет в отдельном ADR когда определимся.
  • Конкретная лицензия — README говорит «TBD (планируется MIT)».

4. Что нужно сделать дальше (план из 5 фаз)

Фаза 0 — Перенос существующего (1-2 недели)

  • Переписать 14 скиллов из LyraResearch/.claude/skills/local/ под публичный формат.
  • Убрать упоминания NG, Overmind, Perforce.
  • Переписать _tools/*.py на универсальные пути.
  • Перенести заметки в references/ скиллов.
  • README, LICENSE (MIT), CONTRIBUTING.md, CHANGELOG.md.

Фаза 1 — UE-плагин минимальный (3-4 недели)

  • Скелет Engine/Source/UEToolchain/.
  • TCP-сервер с JSON-RPC 2.0.
  • Команды: ping, version, list_open_levels, load_asset, get_blueprint_graph.
  • Python-клиент с автотестами через mock-сервер.
  • Smoke-тест: плагин собирается в Lyra.

Фаза 2 — MCP-сервер (2 недели)

  • Python-пакет ue_toolchain_mcp с FastMCP.
  • Инструменты низкого уровня: load_asset, get_blueprint_graph, set_node_property, run_console_command.
  • Инструменты высокого уровня: edit_blueprint_node, take_screenshot, start_pie.
  • UDP-discovery + heartbeat (по ADR-0001).
  • Тесты: мок UE-сервера.

Фаза 3 — Установщик (1-2 недели)

  • CLI на Typer/Click: ue-toolchain install/uninstall/doctor.
  • Авто-копирование плагина, правка .uproject, регистрация MCP.
  • doctor: проверяет плагин, мост, видимость MCP в клиенте.

Фаза 4 — Автодокументирование (параллельно с 1-3)

  • Сканер: обход Source/, Content/, Plugins/ → граф.
  • Генератор индексов: компактные .md на 1-2k токенов.
  • Инкрементальное обновление по mtime + hash.
  • MCP-инструмент search_docs(query).

Фаза 5 — Полировка и релиз (2-3 недели)

  • CI: сборка плагина на 5.4/5.5/5.6/5.7.
  • Пример проекта examples/MinimalProject/.
  • Документация на сайте.
  • Видео-демо, troubleshooting.
  • Первый релиз v0.1.0.

5. Что НЕ было сделано (явно зафиксировано)

  • Скиллы не перенесены. Это первая задача фазы 0.
  • MCP-сервер не начат. Скелет + один инструмент ue_ping() — минимальный первый шаг для проверки архитектуры discovery.
  • UE-плагин не начат. Это фаза 1, требует редактора UE и компиляции.
  • Установщик не начат. Это фаза 3.
  • Автодокументирование не начато. Это фаза 4, параллельная работа.
  • Лицензия не выбрана. README говорит TBD, планируется MIT.
  • Версия UE не зафиксирована. Будет в ADR когда определимся.
  • Удалённый транспорт не рассматривается. Явно отложено (см. ADR-0001).

6. Открытые вопросы, требующие решения

# Вопрос Когда решать
1 Репозиторий публичный GitHub или пока приватный? Перед первым релизом
2 Лицензия (MIT или другое)? Перед первым релизом
3 Язык документации: английский или двуязычный? Перед фазой 5
4 Платформа: только Windows или Linux/Mac тоже? Перед фазой 5 (CI)
5 Целевая версия UE: только 5.6 или 5.4-5.7? Перед фазой 1

7. Куда смотреть в следующей сессии

Если продолжаем работу:

  1. D:\LLM\ClaudePJs\ue-toolchain\ — репозиторий проекта, ветка main.
  2. docs/architecture/decisions/0001-discovery-over-pid-file.md — единственный пока ADR, формат MADR.
  3. LyraResearch/ — источник для переноса скиллов и скриптов (фаза 0).

Порядок следующих шагов:

  1. Решить 5 открытых вопросов из таблицы выше.
  2. Начать фазу 0 (перенос скиллов) — это не требует редактора UE, чисто текстовая работа.
  3. Параллельно можно начать скелет MCP-сервера (фаза 2, инструмент ue_ping()) — проверка архитектуры discovery на практике.

Чего НЕ делать:

  • Не возвращать PID-файл обратно (ADR-0001 явно запрещает).
  • Не создавать ADR «на будущее» — только когда есть реальный запрос.
  • Не трогать LyraResearch/LyraStarterGame/ — это эталон, он чужой.

8. Комментарии к процессу

  • Стиль решений: принимаем маленькие ADR-ы с явными confirmation criteria, не обещаем больше, чем делаем.
  • Источник знаний: LyraResearch остаётся как «мастерская» — заметки, разборы, скрипты. В ue-toolchain переносится только то, что переживёт любой проект.
  • Имена: ue-toolchain (репозиторий), ue_toolchain_mcp (pip-пакет), UEToolchain (UE-модуль плагина), uetc (префикс консольных команд).
  • Язык: заметки и ADR — на русском (как эта сессия). Документация для публичного релиза — на английском (фаза 5).
  • Цикл работы: короткие итерации с измеримым результатом. Каждый ADR имеет confirmation criteria, каждый шаг плана имеет артефакт.
Reference in New Issue View Git Blame Copy Permalink