docs: add handoff document for project continuation

Фиксирует состояние проекта на момент завершения сессии 2026-09-01: что сделано (ADR-0001, репозиторий), что не сделано (фазы 0-5), открытые вопросы и порядок следующих шагов. Документ нужен, чтобы продолжить работу через неделю/месяц без необходимости перечитывать всю сессию.
2026-09-02 19:12:13 +07:00
parent ff491e86dd
commit 9e2194c298
1 changed files with 196 additions and 0 deletions
@@ -0,0 +1,196 @@
+# 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, каждый шаг плана имеет артефакт.