ue-toolchain/docs/handoff.md

Handoff: LyraResearch → ue-toolchain

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

---

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, каждый шаг плана имеет артефакт.