# 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](architecture/decisions/0002-harness-neutral-skill-bundle.md)) | > | «Лицензия TBD, планируется MIT» (вопрос 2) | решено: проза CC BY-ND 4.0, код Apache-2.0 ([ADR-0003](architecture/decisions/0003-split-licensing-prose-and-code.md)) | > | `docs/licensing-options.md` как открытый выбор | материал к решению, само решение — в ADR-0003 | > | целевая версия UE открыта (вопрос 5) | платформа — 5.8; решено 2026-09-06 прогнать все 232 рецепта по 5.8-дереву и развести версии по результату | > | фазы 1–2: свой мост и MCP-сервер | сужены [ADR-0005](architecture/decisions/0005-native-transport-narrows-adr-0001.md): транспорт берём у движка | > | вопрос 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 **Проблема:** проект был жёстко завязан на конкретный студийный проект — пути к его дереву, Perforce-правила, конфигурация под конкретный редактор. Скиллы и инструменты не переносились в чужие проекты без переписывания. **Решение:** сделать из LyraResearch **самостоятельный публичный продукт** `ue-toolchain`, не зависящий от студии и от конкретного проекта. ## 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/` под публичный формат. - Убрать упоминания студийных проектов и 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, каждый шаг плана имеет артефакт.