32 KiB
Site Engine
Движок сайтов на Markdown + YAML: страницы собираются из layouts и fragments, контент и структура живут в файлах, результат — статический сайт. Подключение агента по MCP — часть архитектуры (этап M3).
Документы проекта лежат в docs/: ТЗ v0.1, архитектурное ревью и журнал принятых решений (ADR-001…006). Код следует журналу решений. Правила веток и коммитов — BRANCHING.md.
Предложение по подключению внешнего агента, API keys/scopes, онбоардингу и этапам развития MCP — MCP и внешний агент. Это основа будущей спецификации; MCP-сервер пока не реализован.
Быстрый старт
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 не трогает.
Актуальный пример на схеме версии 1 — examples/site-studio: услуги, сценарии, кейсы, связи и схемы полей. Проверка: 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: 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.
Каталог фрагментов
Фрагмент определяется файлом fragment.yaml, поиск рекурсивный. Поддерживаются прежнее плоское размещение fragments/richtext/fragment.yaml и категории fragments/content/richtext/fragment.yaml. ID берётся из манифеста и не зависит от имени папки; в блоках по-прежнему указывается fragment: richtext.
Для вложенного размещения категория определяется первым каталогом относительно fragments/ и имеет приоритет над category в YAML. Для плоского размещения сохраняется категория из YAML, по умолчанию misc. Встроенные фрагменты разложены по content, data, forms, marketing, media, system; дополнительные категории сайта допустимы. Повторные ID, включая совпадения с builtin, запрещены.
В конструкторе категория видна рядом с названием; назначение остаётся под названием. Поиск учитывает ID, название, описание и категорию, фильтры объединяют прежние русские подписи со стандартными категориями.
Данные для добавления блока можно вынести в соседний preview.yaml:
name: Пример текстовой секции
props:
title: Новый раздел
text: Начальный текст раздела
props из этого файла переопределяет одноимённые значения inline fragment.yaml:preview, затем применяются defaults полей. Название самого фрагмента остаётся в fragment.yaml:name. Некорректный preview входит в диагностику загрузки и не пропускается молча.
Этапы 1–5 спецификации 002 реализованы: категории, файловая тема, ширина блоков, отдельный Site Studio и Theme Manager. Экран /admin/theme доступен через «Дизайн сайта»; для нового сайта мастер открывается через /admin/setup/theme. Отчёт этапа 5 подготовлен к пользовательской приёмке.
Тема и ширина секций
В site.yaml тема подключается через theme: {file: theme.yaml}. Документ темы:
schema: 1
preset: minimal
preset_version: 1
overrides:
colors:
primary: '#4255b9'
ui:
container:
mode: boxed
max_width: 1080
gutter: {desktop: 36, tablet: 24, mobile: 16}
Доступны перенесённые из дизайна пресеты minimal, dark, editorial, bold, natural, custom версии 1. Один resolver проверяет цвета, разрешённые шрифты, числовые токены, дополнительные цвета и градиенты для CLI, сборки и preview. Недостаточный контраст — предупреждение. Без настройки темы новый сайт использует minimal@1 без записи файла; явная неправильная ссылка и старый inline theme.tokens дают ошибку. Конфигурации studio-site и ai-studio обновлены в исходниках; автоматической миграции нет.
Блок может задать layout: {section_width: full, content_width: boxed}: первая ширина отвечает за фон секции, вторая — за содержимое. Допустимы inherit, boxed, fluid, full; наследование идёт от темы. В конструкторе эти поля находятся в инспекторе «Макет блока · ширина» и сохраняются в YAML при явном Save. Изменение preview не записывает страницу.
Theme Manager переносит четыре шага исходного Antirion: пресеты, цвета/градиенты, шрифты, дизайн-токены/ширину. Правки остаются в памяти вкладки до «Сохранить тему»; YAML экспортируется после серверной проверки. Стенд компонентов и реальная страница используют изолированное серверное превью. Save изменяет workspace, публикация — отдельное действие. Состояние мастера (пропуск/повтор/завершение) хранится в SITE_STATE_DIR/theme-onboarding.json; палитры в нём нет. Для новых ресурсов нужна пересборка образа. Проверка: PYTHONPATH=src python scripts/qa_theme_manager_002.py.
Тема и вычисленные токены фиксируются в manifest.json релиза; fingerprint учитывает файлы сайта и ресурсы рендера. Откат возвращает готовый HTML/CSS выбранного релиза, сохраняя рабочие файлы. Подробный контракт и таблица CSS-переменных — runtime 002, приёмка — проверки этапов 2–3.
Структура проекта
site-engine/
├── pyproject.toml # зависимости ядра и extras: server, mcp, images, dev
├── Makefile Dockerfile # Dockerfile — для M2+ (админка, формы, MCP)
├── docs/ # ТЗ, ревью, журнал решений
├── examples/studio-site/ # сайт-пример из SiteMap.md (услуги, формы, коллекция, редирект)
├── .env.example # переменные окружения для админки
├── tests/ # 206 тестов: ядро, сборка, безопасность, запись, вход и редактор
└── src/site_engine/
├── cli.py # validate · build · preview · fragments
├── errors.py # Issue/Report: код, путь к полю, серьёзность, подсказка
├── core/
│ ├── values.py # Literal | Binding | LinkRef | Query (ADR-002)
│ ├── models.py # Block, Page, Entry, Fragment, Layout, Collection…
│ ├── registry.py # чистая загрузка каталога сайта в память (ADR-001)
│ ├── routes.py # нормализация маршрутов, таблица, коллизии
│ ├── resolve.py # привязки, ссылки, запросы MVP
│ ├── validate.py # workspace-проверки, release-проверки, правила сайта
│ ├── draft_check.py # проверка при сохранении: новый текст файла против реестра
│ ├── page_ops.py # добавить, переместить, удалить блок по id в сыром front matter
│ └── render.py # Jinja SandboxedEnvironment, разрешение props по схеме
├── build/pipeline.py # load → validate → render → релиз → атомарный current
├── parsing/ # безопасный YAML, front matter, Markdown (raw HTML выключен)
├── storage/ # safe_join, atomic_write, SiteLock, .engine/history
├── services/ # auth (вход админа), ContentService (if_match, история), publish; stubs: changeset, forms
├── builtin/ # base.css и 15 фрагментов ядра (ADR-006)
├── db/ # SQLAlchemy-модели служебных таблиц (M2)
├── web/ # FastAPI-фабрика; admin/: handlers (вход, обзор), editor (страницы, блоки, записи, публикация), forms, шаблоны, routes-адаптер
└── mcp/ # перечень инструментов MVP (M3)
Запуск в Docker
Один том /data, в нём три каталога. Всё, что важно сохранить, лежит на хосте в ./data.
| На хосте | В контейнере | Что это |
|---|---|---|
data/site |
/data/site |
Ваш сайт: site.yaml, pages/, content/, фрагменты. Его правит редактор |
data/dist |
/data/dist |
Опубликованные релизы и симлинк current |
data/state |
/data/state |
Состояние входа и журнал audit.jsonl |
docker build -t site-engine .
docker run --rm -it site-engine site-engine hash-password # спросит пароль, напечатает хеш
docker run --rm site-engine site-engine gen-secret # ключ подписи сессий
cp .env.example .env # впишите хеш и ключ
mkdir -p data && cp -r examples/studio-site data/site # или положите свой сайт в data/site
docker run -d --name site-engine -p 8181:8000 --env-file .env -v "$PWD/data:/data" site-engine
Админка: http://localhost:8181/admin/ (на обзоре сверху показаны абсолютные пути, которыми пользуется приложение), опубликованный сайт: http://localhost:8181/. Проверка того, что видит контейнер:
docker logs site-engine # строка «site-engine: site=/data/site, dist=/data/dist, state=/data/state, admin=on»
docker exec site-engine env | grep '^SITE_' # SITE_ROOT, SITE_DIST, SITE_STATE_DIR должны начинаться с /data/
Если вместо /data/... там относительные пути (examples/studio-site, dist), эти строки остались в вашем .env от старой версии: удалите SITE_ROOT, SITE_DIST, SITE_STATE_DIR из .env, так как значения из --env-file перекрывают значения из образа. При старте приложение само пишет об этом предупреждение.
Правила для .env при docker run --env-file:
- Без кавычек. Docker не снимает их, они станут частью значения.
- Без комментариев в конце строки.
KEY=value # текстдаёт значение «value # текст». - Знак
$в хеше экранировать не нужно. (Дляdocker composeи его.envего нужно удваивать:$$.)
Приложение проверяет эти значения строго: хеш, ключ, логин, флаг Secure и host с лишними символами не принимаются молча, /admin/ не включается, а в docker logs пишется причина.
| Симптом | Причина |
|---|---|
/admin/ даёт 404 |
Не заданы SITE_ADMIN_PASSWORD_HASH и SITE_SECRET_KEY, ключ короче 32 символов или в значении кавычки или комментарий; причина в docker logs: «админка отключена: …» |
| «Сайт не загружен» на обзоре | В data/site нет site.yaml или том не смонтирован; на обзоре виден абсолютный путь, который проверял движок |
| Опубликованного сайта нет на хосте | Том не смонтирован (-v "$PWD/data:/data"): релизы лежат внутри контейнера и пропадут вместе с ним |
| После ввода пароля снова страница входа | Cookie с флагом Secure не принимается по http:// с адреса не localhost: поставьте SITE_COOKIE_SECURE=0 |
Ответ 422 с "loc": ["query","request"] |
Образ собран из версии до исправления: пересоберите docker build |
Контейнер работает от root, поэтому файлы в data/ на Linux будут принадлежать root. Чтобы этого избежать, добавьте --user "$(id -u):$(id -g)".
Вход в админку
Самый простой вариант: один администратор, без ролей, логин и хеш пароля задаются переменными окружения, БД для входа не нужна.
site-engine hash-password # спросит пароль (от 12 символов) и напечатает scrypt-хеш
site-engine gen-secret # ключ подписи сессий
cp .env.example .env # впишите SITE_ADMIN_PASSWORD_HASH и SITE_SECRET_KEY
SITE_COOKIE_SECURE=0 uvicorn site_engine.web.app:create_app --factory --env-file .env # локально по http
Без SITE_ADMIN_PASSWORD_HASH и SITE_SECRET_KEY (не короче 32 символов) /admin/ не включается вообще: нет пароля — нет входа. После входа /admin/ показывает страницы сайта со статусами, коллекции и результат проверки (только чтение; редактор — следующий шаг).
| Мера | Как сделано |
|---|---|
| Пароль | scrypt (N=2^15, r=8, p=1), соль на каждый хеш, сравнение за постоянное время |
| Сессия | Подписанная cookie se_session: HttpOnly, SameSite=Strict, Secure (выключается только SITE_COOKIE_SECURE=0), Path=/admin, срок SITE_SESSION_HOURS (по умолчанию 8) |
| Выход | Увеличивает «эпоху» в .engine/auth_epoch: все выданные cookie сразу недействительны, в том числе украденные |
| Перебор | 5 неудач за 15 минут блокируют IP (429 + Retry-After), общий порог 30 на все адреса; хеш считается и при неверном логине, поэтому по времени логин не угадать |
| CSRF | POST принимается только с Origin или Referer того же хоста; выход дополнительно требует токен, привязанный к сессии |
| Заголовки | CSP без inline, frame-ancestors 'none', no-store, X-Frame-Options: DENY, nosniff |
| Аудит | .engine/audit.jsonl: вход, неудача, блокировка, выход; без паролей и без введённого логина |
Ограничения этого варианта:
- Один пользователь, роль всегда
admin; таблицыusersиapi_tokensизdb/models.pyпока не используются. - Окно попыток хранится в памяти процесса: при нескольких воркерах у каждого свой счётчик, после перезапуска он обнуляется.
- За обратным прокси
request.client.host— адрес прокси, поэтому ограничение по IP работает как общее. Доверие кX-Forwarded-Forнужно включать явно (задача M2). - Выход завершает все сессии администратора сразу, отдельного списка устройств нет.
- Отдельная смена пароля: сгенерировать новый хеш и перезапустить сервис; чтобы разлогинить всех, поменяйте
SITE_SECRET_KEY.
Редактор
После входа в /admin/ доступны страницы, контент и публикация. Все правки идут через ContentService: блокировка сайта, if_match по хешу файла, проверка синтаксиса, история в .engine/history/, атомарная запись. Редактор пишет только в pages/ и content/; фрагменты, layouts, схемы и site.yaml через него изменить нельзя.
| Экран | Что умеет |
|---|---|
| Страницы | Список со статусами и адресами; создание черновика (путь, заголовок, layout) |
| Страница | Заголовок, статус, layout, адрес, описание, текст Markdown; блоки по регионам и слотам: добавить, ↑/↓, скрыть и показать, удалить; предпросмотр в изолированном фрейме; список проблем страницы |
| Блок | Форма строится из манифеста фрагмента: текст, Markdown, число, список, группа, выбор, ссылка (страница, запись, адрес), запрос к коллекции, ассет; у каждого поля поле «привязка» (entry.title, page.body…); якорь, заметка, скрыть, requires по флагам сайта |
| Контент | Записи коллекций: поля по схеме, статус, текст Markdown, создание черновика, предпросмотр |
| Публикация | Сборка релиза, список релизов, возврат к прежнему релизу |
Гарантии, которые проверены тестами:
- Без потерь. Форма открывается из файла и отправляется обратно без изменений: у каждого блока примера, всех страниц и записей YAML остаётся тем же по смыслу. Неизвестные ключи не пропадают, привязки сохраняются.
- Конфликты. Если файл изменили в другом окне, правка получит 409, а чужие изменения не будут перезаписаны.
- Проверка при сохранении. Нельзя сохранить неизвестный фрагмент, несуществующий layout, блок в закреплённый регион, значение не того типа,
{{ }}в данных, привязку к чужому корню. Пропуск обязательного поля не блокирует сохранение (ADR-003), но он виден в «Проверке страницы», и сборка релиза с ним не пройдёт; опубликованный сайт при этом не меняется. - Безопасность. Каждый POST требует CSRF-токен и Origin своего хоста; id страниц, блоков и записей проверяются регулярным выражением и поиском в реестре, до пути на диске недоступны; пассивное превью использует iframe без scripts, интерактивное — отдельный origin и только nonce bridge; в аудит попадают id и тип действия, но не содержимое.
Что работает иначе, чем можно ожидать:
- Обычные формы и локальный htmx. Порядок блоков меняется кнопками ↑/↓, элементы списков добавляются через «пустую строку» формы. htmx 2.0.11 поставляется в
src/site_engine/web/admin/static/и включает существующийhx-boost; источник, лицензия и SHA-256 — в VENDOR.md. Без JS сохраняются обычные формы. CDN и Node-сборка не нужны; SortableJS пока не подключён. Конфигурация запрещает eval, скрипты из ответов и сторонние запросы, отключает сохранение HTML в localStorage и разрешает показ HTML-ошибок 4xx. Новый редактор использует HTML-фрагменты htmx, общий буфер в памяти и явный Save; без JS доступна обычная форма исходника.
Развитие админки описано в 001 — Antirion Rework: htmx/Jinja → HTML UI → серверный API-клиент → типизированный JSON API FastAPI → сервисы. JSON API, общий буфер Конструктора/«Эксперта», ручной Save и интерактивное превью реализованы. Контракт, env и запуск второго процесса: runtime.md; приёмка: verification.md.
Publication перенесён из оригинального дизайна: проверка → неизменяемый кандидат → preview/diff → отдельная публикация с комментарием и проверкой актуальности. История/откат сохраняют workspace. Контракт и границы — publication-backend.md, проверки — verification-publication.md.
- Конструктор пересобирает YAML: комментарии и форматирование могут измениться. «Эксперт» и переходы режимов без правок сохраняют точный исходник. «Применить к буферу» не пишет файл; «Сохранить документ» записывает весь документ с CAS, историей и аудитом. До Save исходник можно скачать.
- Ассеты выбираются по пути из подсказки, загрузки файлов в редакторе пока нет.
- Блоки перемещаются кнопками ↑/↓ или перед указанным ID. Между регионами/слотами действует проверка схемы; циклы и изменение fixed-блоков запрещены.
- Запись коллекции со «лишним» ключом, которого нет в схеме, нельзя сохранить в статусе
published, пока ключ не уберут из файла: так требует ADR-003.
Что реализовано
| Этап | Состояние |
|---|---|
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 встроенных фрагментов, сайт-пример; отдельный steps поставляется с ai-studio |
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (services/publish.py), превью страницы через CLI. Превью по токену реализовано в 001; нет 404-страницы из коробки и системы публичных тем |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), вход одного администратора с аудитом входов и обзорная страница админки. Аудит Save/create/publish/rollback реализован; нет ролей, приёма заявок и outbox |
| M3 MCP и редактор | Готово: редактор страниц, блоков и записей на ContentService, предпросмотр, публикация и откат из админки. Нет: patch_page, changeset (rename, delete), MCP-сервера, перетаскивания, загрузки файлов |
| M4 | Не начат |
Что проверено, а что нет
Приёмка 001 включает полную регрессию ядра/CLI/админки, настоящий FastAPI, JSON-контракт и ASGI-клиент, Chromium на двух origin, адаптивные экраны и установленный wheel без design/. Воспроизводимые команды, результаты и ограничения: verification.md. Docker/proxy deployment, БД и MCP-сервер не запускались. Ядро сохраняет dataclass; Pydantic используется на границе API.
Соответствие журналу решений
| Решение | Где в коде |
|---|---|
| ADR-001: сборка не читает SQLite | core/registry.load_site, build/pipeline.build_site |
ADR-002: 4 вида значений, bind, запросы MVP |
core/values.py, core/resolve.py; {{ }} в данных запрещены (validate.py) |
| ADR-003: draft / release / live, версия формы в релизе | validate_workspace vs validate_release, _forms/<id>@<версия>.json, switch_current |
ADR-004: if_match, блокировка сайта, история |
services/content.py, storage/locks.py, storage/history.py |
| ADR-005: границы доверия | SandboxedEnvironment, Markdown без raw HTML, safe_join, токены темы, YAML без алиасов |
ADR-006: 15 встроенных фрагментов, локальный steps в ai-studio, editorial, requires только feature.* |
builtin/fragments/, examples/ai-studio/fragments/steps/, models.Page.editorial, render._feature_on |
Как расширять
- Новый фрагмент: папка
fragments/<имя>/сайта сfragment.yaml,template.html.j2, необязательнымstyle.css.idплоский и уникальный, затенение встроенных запрещено. - Новая коллекция:
collections/<id>.yaml, записи вcontent/<id>/*.md, при необходимостиdisplay/<id>.yaml. - Новое правило сайта: запись в
site.yaml: rules(сейчасrequire_fragmentдля коллекции иrequire_fieldдля форм).
Известные ограничения M0
- Поле
propsв шаблоне — объектProps:props.itemsчитает поле «items», а не метод словаря. layout.extendsпроверяется на существование, наследование шаблонов делается обычным{% extends 'layout/<id>' %}.- CSS и JS собираются в один бандл с хешем в имени; минификации и изоляции по страницам пока нет.
- Нет приёма заявок и MCP: сетевая поверхность записи включается только вместе с контуром «вход, роли, аудит, лимиты» (ADR-006). Вход, аудит правок и редактор уже есть; роли и приём заявок остаются на M2.