From 80ea7b03a9b6b017bbe2730c59ff74e5c2067376 Mon Sep 17 00:00:00 2001 From: MagentaDolphin Date: Wed, 2 Sep 2026 19:12:13 +0700 Subject: [PATCH] docs: add handoff document for project continuation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Фиксирует состояние проекта на момент завершения сессии 2026-09-01: что сделано (ADR-0001, репозиторий), что не сделано (фазы 0-5), открытые вопросы и порядок следующих шагов. Документ нужен, чтобы продолжить работу через неделю/месяц без необходимости перечитывать всю сессию. --- docs/handoff.md | 196 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 docs/handoff.md diff --git a/docs/handoff.md b/docs/handoff.md new file mode 100644 index 0000000..a0637e5 --- /dev/null +++ b/docs/handoff.md @@ -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, каждый шаг плана имеет артефакт.