MagentaDolphin
cd041ec1bf
Acceptance review found four documents describing a state that no longer holds. None of the original text is deleted: the reason a decision was taken is part of the record, so supersession is marked rather than rewritten. - README: license section reflects ADR-0003, ADR-0003 added to the decision list, status line says which component actually ships. - handoff.md: banner marking it historical, with a table of what changed since 2026-09-01 (skills moved, layout, licence, engine version still open). - licensing-options.md: status struck through, pointing at ADR-0003. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
211 lines
15 KiB
Markdown
211 lines
15 KiB
Markdown
# 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.6; платформа исследования переведена на 5.8 (`LyraResearch/plans/ue58-native-mcp-strategy.md`). В поставку решение ещё не доехало — **открыто** |
|
||
>
|
||
> Открытыми остаются вопросы 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, каждый шаг плана имеет артефакт.
|