Document CMS branching and external agent integration

This commit is contained in:
2026-11-17 11:45:00 +03:00
parent 21838f545a
commit 78265b64c2
4 changed files with 345 additions and 11 deletions
+14 -9
View File
@@ -2,22 +2,24 @@
Движок сайтов на Markdown + YAML: страницы собираются из **layouts** и **fragments**, контент и структура живут в файлах, результат — статический сайт. Подключение агента по MCP — часть архитектуры (этап M3).
Документы проекта лежат в `docs/`: ТЗ v0.1, архитектурное ревью и журнал принятых решений (ADR-001…006). Код следует журналу решений.
Документы проекта лежат в `docs/`: ТЗ v0.1, архитектурное ревью и журнал принятых решений (ADR-001…006). Код следует журналу решений. Правила веток и коммитов — [BRANCHING.md](docs/BRANCHING.md).
Предложение по подключению внешнего агента, API keys/scopes, онбоардингу и этапам развития MCP — [MCP и внешний агент](docs/extends/mcp-agent-integration.md). Это основа будущей спецификации; MCP-сервер пока не реализован.
## Быстрый старт
```bash
pip install -e ".[dev]" # ядру нужны jinja2, PyYAML, markdown-it-py, click
site-engine validate examples/studio-site
site-engine build examples/studio-site --out /tmp/studio-dist
site-engine preview examples/studio-site drafts/next > /tmp/draft.html
site-engine fragments # 17 встроенных фрагментов
make test # или: pytest
pip install -e ".[server,dev]" # ядру нужны jinja2, PyYAML, markdown-it-py, click
site-engine validate examples/site-studio
site-engine build examples/site-studio --out /tmp/site-studio-dist
site-engine preview examples/site-studio index > /tmp/site-preview.html
site-engine fragments # каталог встроенных фрагментов
make test # временная историческая фикстура, без записи в examples/
```
Результат сборки: `OUT/<build_id>/` и симлинк `OUT/current`, который переключается атомарно. Неудачная сборка `current` не трогает.
Расширенный пример для проверки перед возможным переносом сайта — [examples/ai-studio](examples/ai-studio/README.md), также на схеме версии 1: услуги, сценарии, кейсы, обложки, связи и понятные схемы полей. Проверка: `site-engine validate examples/ai-studio`, сборка: `site-engine build examples/ai-studio --out /tmp/ai-studio-dist`, браузерная приёмка: `PYTHONPATH=src python scripts/qa_ai_studio.py`. `studio-site` остаётся базовой фикстурой; отдельный запуск нового примера описан в его README.
Актуальный пример на схеме версии 1 — [examples/site-studio](examples/site-studio/README.md): услуги, сценарии, кейсы, связи и схемы полей. Проверка: `site-engine validate examples/site-studio`, сборка: `site-engine build examples/site-studio --out /tmp/site-studio-dist`, браузерная приёмка: `PYTHONPATH=src python scripts/qa_site_studio_002.py`. Полная регрессия: `PYTHONPATH=src python scripts/run_regression.py` (или `make test`). Runner извлекает старую фикстуру `studio-site` из Git-коммита `231490b` во временный каталог и мигрирует её тему; нужны Git и эта история, дополнительные файлы из `/tmp` не требуются. Обычные `pytest`/`unittest discover` пока не готовят эту фикстуру. Целевые тесты нового UI и браузерные QA используют собственные фикстуры и текущий Site Studio.
Отдельный перенос публичного дизайна из `design/examples/site-studio/` — [examples/site-studio](examples/site-studio/README.md): 13 страниц, пять layouts, общие `steps` и `entry_card`, файловая тема и ширины секций, сохранённые черновики и отключённые коллекции. `site-engine validate examples/site-studio`, `site-engine build examples/site-studio --out /tmp/site-studio-dist`; браузерная сверка с оригиналом — `PYTHONPATH=src python scripts/qa_site_studio_002.py`. Отчёт — [этап 4](specs/002-site-studio-theme/verification-stage-4.md).
@@ -203,7 +205,10 @@ SITE_COOKIE_SECURE=0 uvicorn site_engine.web.app:create_app --factory --env-file
- **Обычные формы и локальный htmx.** Порядок блоков меняется кнопками ↑/↓, элементы списков добавляются через «пустую строку» формы. htmx 2.0.11 поставляется в `src/site_engine/web/admin/static/` и включает существующий `hx-boost`; источник, лицензия и SHA-256 — в [VENDOR.md](src/site_engine/web/admin/static/VENDOR.md). Без JS сохраняются обычные формы. CDN и Node-сборка не нужны; SortableJS пока не подключён. Конфигурация запрещает eval, скрипты из ответов и сторонние запросы, отключает сохранение HTML в localStorage и разрешает показ HTML-ошибок 4xx. Новый редактор использует HTML-фрагменты htmx, общий буфер в памяти и явный Save; без JS доступна обычная форма исходника.
Развитие админки описано в [001 — Antirion Rework](specs/001-antirion-admin/spec.md): htmx/Jinja → HTML UI → серверный API-клиент → типизированный JSON API FastAPI → сервисы. JSON API, общий буфер Конструктора/«Эксперта», ручной Save и интерактивное превью реализованы. Контракт, env и запуск второго процесса: [runtime.md](specs/001-antirion-admin/runtime.md); приёмка: [verification.md](specs/001-antirion-admin/verification.md).
- **Конструктор пересобирает YAML** после предупреждения: комментарии и форматирование могут измениться. «Эксперт» и переходы режимов без правок сохраняют точный исходник. «Применить к буферу» не пишет файл; «Сохранить документ» записывает весь документ с CAS, историей и аудитом. До Save исходник можно скачать.
Publication перенесён из оригинального дизайна: проверка → неизменяемый кандидат → preview/diff → отдельная публикация с комментарием и проверкой актуальности. История/откат сохраняют workspace. Контракт и границы — [publication-backend.md](specs/001-antirion-admin/publication-backend.md), проверки — [verification-publication.md](specs/001-antirion-admin/verification-publication.md).
- **Конструктор пересобирает YAML**: комментарии и форматирование могут измениться. «Эксперт» и переходы режимов без правок сохраняют точный исходник. «Применить к буферу» не пишет файл; «Сохранить документ» записывает весь документ с CAS, историей и аудитом. До Save исходник можно скачать.
- **Ассеты** выбираются по пути из подсказки, загрузки файлов в редакторе пока нет.
- **Блоки перемещаются** кнопками ↑/↓ или перед указанным ID. Между регионами/слотами действует проверка схемы; циклы и изменение fixed-блоков запрещены.
- **Запись коллекции со «лишним» ключом**, которого нет в схеме, нельзя сохранить в статусе `published`, пока ключ не уберут из файла: так требует ADR-003.