18 KiB
AGENTS.md
Проект
- Python 3.12+, пакет
site_engineвsrc/. Публичный сайт — статический HTML из Markdown/YAML и Jinja2; FastAPI обслуживает админку, публикацию и статику. - Контент — файлы; сборка не зависит от SQLite. Конвейер:
core/registry.py→core/validate.py→core/render.py→build/pipeline.py. - Контекст и архитектура:
README.md,docs/TZ-site-engine-decisions.md(ADR-001…006). Часть ТЗ ещё не реализована; фактические возможности сверяй с кодом и тестами.
Куда подключать дизайн
- Публичный сайт-пример:
examples/site-studio/. Каркас —layouts/<id>/{layout.yaml,layout.html.j2}, композиция страниц —pages/*.md(включая подкаталоги), страницы записей коллекций —display/*.yaml; схемы коллекций —collections/, записи —content/. - Новый независимый публичный пример
examples/site-studio/переносит разметку/CSS изdesign/examples/site-studio/без локальных дублей builtin и mini-renderer.entry_card.entry— ref сto: '*', значение collection/slug; редактор предлагает опубликованные записи включённых коллекций. Fixed ref/refs сохраняют slug + to.collections/*.yaml:requiresограничивает публикацию и queries через feature.<имя>, как у courses/posts. Формы сохраняют HTTP 501 с видимым сообщением. - Встроенные компоненты:
src/site_engine/builtin/fragments/<category>/<id>/—fragment.yaml(поля/слоты),template.html.j2,style.css, необязательныйscript.js. Категории:content,data,forms,marketing,media,system. Тема —site.yaml:theme.file→theme.yaml(schema: 1,preset,preset_version,overrides); inlinetheme.tokensотклоняется. Resolver/валидация/CSS —core/theme.py, immutable пресеты из дизайна —builtin/themes/v1/. Без настройки темы используется minimal@1 в памяти. Общие стили —builtin/base.css, затем стили фрагментов, вычисленные токены иbuiltin/containers.css. - Ширина блока — отдельный
layout: {section_width, content_width}, значенияinherit|boxed|fluid|full. Отсутствующий layout у hero/cta_banner/site_header/site_footer означает full/inherit, у остальных inherit/inherit; явный inherit берёт глобальный mode темы.core/block_layout.pyиlayout_marks.pyприменяют ширину к корням и собственным.f-container/.container, не к контейнерам вложенных блоков. Для независимой ширины фона и текста шаблон должен иметь внешний корень и внутренний контейнер; не оборачивай sticky-header общим служебным div. Контролы инспектора перенесены из design; изменение до Save остаётся в памяти вкладки. - Компоненты сайта ищутся рекурсивно по
fragment.yaml: работаютfragments/<id>/иfragments/<category>/<id>/. Во вложенном размещении категория — первый каталог относительноfragments/, в плоском —categoryиз YAML илиmisc. ID берётся из манифеста, остаётся плоским и уникальным; встроенные фрагменты нельзя затенять. Опциональныйpreview.yaml:propsпереопределяет inlinefragment.yaml:previewпо ключам; затем используются defaults полей. Для особого дизайна используй новый ID и обновляй ссылки на него в блоках; изменения builtin влияют на все сайты. - Изображения, шрифты и прочие файлы сайта —
assets/. Сборщик копирует их в релиз и объединяет CSS/JS использованных фрагментов в общие бандлы с хешами; порядок фрагментов в бандле — по ID, а не по расположению на странице. - Админка — отдельный интерфейс:
src/site_engine/web/admin/templates/иstatic/; runtime —application.py, серверный клиент —api_client.py, формы —forms.py, HTTP-адаптер —routes.py;handlers.pyотвечает за вход/статику,editor.pyсохраняется для совместимости. Работают HTML-формы с локальным htmx; версия, источник и хеш —static/VENDOR.md. - Направление развития —
specs/001-antirion-admin/{spec,plan,tasks}.md: браузер/htmx → HTML UI → серверный API-клиент → JSON FastAPI → сервисы. API/admin/api/v1/реализован вweb/api/с Pydantic DTO; ядро сохраняет dataclass. Runtime UI не обходит API при ошибке. Контракт/запуск —specs/001-antirion-admin/runtime.md, результаты —verification.md. - Новый перенос —
specs/002-site-studio-theme/{spec,plan,tasks}.md: этапы 1–5 реализованы, контракт —runtime.md, результаты проверок —verification.mdиverification-stages-2-3.md. Отдельныйexamples/site-studio/перенесён на штатный renderer (13 опубликованных страниц); проверка —scripts/qa_site_studio_002.py, отчёт —verification-stage-4.md. Theme Manager реализован:/admin/theme,/admin/setup/theme, ThemeService/OnboardingService, snapshot/ETag/CAS и серверный preview overlay. Источники Theme Manager —design/theme-studio-antirion.htmlиdesign/assets/theme-studio.css/theme-studio.js; сохраняй исходную композицию и сценарии. Runtime заменяет mock-хранилище API: edits только в памяти вкладки, явный Save, никакого localStorage с палитрой. CSS экрана ограничен theme-content, sample и страница живут в immutable iframe. Workflow — SITE_STATE_DIR/theme-onboarding.json; существующий сайт не перенаправляется. Проверка — scripts/qa_theme_manager_002.py, отчёт — verification-stage-5.md. Первый Save создаёт файл темы и ссылку через ContentService.update_files под одной блокировкой; каждая запись atomic, обычный отказ второго файла откатывает первый, но это не crash-atomic транзакция нескольких файлов. При ошибке после commit API возвращает committed snapshot; не повторяй запись вслепую. Manifest релиза фиксирует документ/effective tokens темы; build fingerprint учитывает ресурсы движка. Исторический каталог релиза не перезаписывается, rollback не меняет workspace. - Фоновый редактор —
specs/003-background-editor/{spec,plan,tasks,runtime,verification}.md. Рабочая редакция только в памяти вкладки; явный Save через CAS. Один stateless POST update передаёт source один раз и пакет операций; transform/validate/preview используют один Registry. HTML-адаптер вызывает AdminApi, добавляет компактную серверную проекцию. Не блокируй и не заменяй активные поля при обычных правках; очередь сохраняет новый ввод, preview обновляет существующий iframe/Document. При удалении строки списка учитывай более новые отложенные формы, чтобы не повторить удаление. Проверки — tests/test_editor_updates.py и scripts/qa_editor_updates.py (оба режима preview).
Правила интеграции
- Админский дизайн переносить из выбранных
design/antirion-rework.htmlи связанных editor/publication-макетов: сохранять разметку, CSS, иконки и сценарии, заменяя mock-данные API. Самостоятельное подобие макета недопустимо. Повторный перенос идёт по этапам; после каждого этапа пользователь проверяет результат до перехода к следующему. - Не использовать нативные
alert/confirm/promptиbeforeunload-диалоги. Подтверждения действий показывать в модальных окнах интерфейса из дизайна. Пересборка YAML не требует отдельного подтверждения. - Сначала сопоставь секции макета с layouts, фрагментами и полями. Повторяющиеся секции выноси в компоненты, изменяемый контент оставляй в данных. Используй существующий стек; отдельную frontend-сборку вводи только под конкретную необходимость.
- В layout сохраняй
seo_head(),assets_head(),assets_body()и вызовыregion(...); регионы объявляй вlayout.yaml. Во фрагментах используйpropsиslots, ссылки выводи через|href, Markdown — через|md/|md_inline. - Новые props и варианты объявляй в
fragment.yaml: по этой схеме работают валидация и формы редактора. Сохраняй явные ID блоков, привязки{bind: ...}, типизированные ссылки{page: ...}/{entry: ...}/{url: ...}и запросы{query: ...}. Jinja-выражения в данных запрещены. - Именования бери из
design/:hero_home,services_list,benefits_grid,process_steps,cta_home— ID блоков, аhero,collection_list,card_grid,cta_banner— типы Fragment. При добавлении и дублировании генерируй ID как<fragment_id>_<5 случайных символов>, напримерrichtext_81ay7; существующие ID сохраняй. Сохраняй это разделение, не добавляй префиксы тематики сайта к общим компонентам; расширения с отличающимся контрактом получают собственный универсальный ID. - В каталоге Fragment сохраняй
name,descriptionи категории из дизайна: «Список коллекций», «Текстовая секция», «Markdown body», «Карточки». Под названием показывай назначение изfragment.yaml:description, передаваемое через API; ID доступен для поиска и в title.sectionсодержит свой текст и поддерживает слоты,richtextпо умолчанию выводитpage.body. Изменения builtin/API/шаблонов требуют пересборки Docker-образа; одного bind-mount сайта недостаточно. - В админских формах сохраняй
action,method, имена полей,csrf,etag(параметр сервиса —if_match) и передачу ошибок. Запись контента проходит черезContentService: блокировка, проверка версии, валидация, история, атомарная запись. - Для нового UI HTML и JSON имеют отдельные маршруты. Серверный клиент вызывает API через
httpx.ASGITransport; внутренние credentials не попадают в браузер, автор и эпоха проверяются на API-границе. Буфер/превью не сохраняют контент до явного Save. - Ошибки JSON API возвращай как
error: {code, message, request_id, …}с корректным HTTP-статусом. Общая граница —web/error_handling.py: неожиданные исключения записываются со стеком вuvicorn.error, метод, путь и ID связывают HTML-запрос с внутренним API. Не добавляй в лог тело запроса, cookies и Authorization. В htmx ошибки HTTP/сети показываются через уведомление из дизайна; 5xx не должны заменять несохранённый исходник редактора. Проверка отказов —PYTHONPATH=src python scripts/qa_errors_001.py. - Сохраняй autoescape, санитайзер Markdown и CSP. JS для админки подключай внешним локальным файлом. Пассивное превью не исполняет скрипты. Интерактивное использует
web/preview_app.pyна отдельном origin, nonce bridge и защищённые immutable snapshots; JS сайта не запускается. Обычная сборка не получает служебную разметку. - Приём публичных форм пока возвращает HTTP 501; MCP и changeset — заготовки. Не показывай успешную отправку без работающего обработчика.
- Проверяй мобильную и широкую версии, клавиатурную навигацию, фокус, подписи полей и контраст. Анимации учитывают
prefers-reduced-motion. - Правь исходники.
dist/,data/,.engine/и.env— результат сборки, рабочие данные и секреты; не используй их как место для разработки дизайна.
Проверка
Установка зависимостей: python -m pip install -e '.[server,dev]' (extra mcp нужен только для работы с MCP).
Из корня репозитория:
PYTHONPATH=src python -m unittest discover -s tests -v
PYTHONPATH=src python -m site_engine.cli validate examples/site-studio
PYTHONPATH=src python -m site_engine.cli build examples/site-studio --out /tmp/site-studio-dist
Дополнительная приёмка 001: PYTHONPATH=src python scripts/qa_001.py, PYTHONPATH=src python scripts/qa_editor_001.py (нужен Playwright Chromium), PYTHONPATH=src python scripts/qa_selection_001.py (выбор секций и диалоги в обоих режимах превью), python scripts/verify_package_001.py; сравнение с исходным дизайном — scripts/qa_shell_001.py, scripts/qa_pages_001.py и scripts/qa_builder_001.py; экспорт контракта — site-engine export-openapi.
Собранный сайт — /tmp/site-studio-dist/current/. Старые тесты и QA ещё ссылаются на удалённый examples/studio-site; для полной регрессии нужна временная базовая фикстура из истории с миграцией файловой темы (см. specs/003-background-editor/verification.md). Не восстанавливай удалённые примеры в рабочем дереве ради тестов. Целевые проверки 003 используют независимую фикстуру и текущий Site Studio.
- Пример сайта используется как фикстура тестов: изменения контента и разметки сверяй с соответствующими проверками. Для изменений поведения обновляй целевые тесты; для чистого CSS проверяй сборку и внешний вид в браузере.
- Черновики могут быть неполными; релиз содержит только
published. Ошибка сборки не должна менять текущий релиз, публикация и откат переключаютcurrentатомарно. - В отчёте перечисляй выполненные проверки и ограничения окружения; успешные тесты обработчиков не заменяют запуск FastAPI и проверку браузером.