Document CMS branching and external agent integration
This commit is contained in:
@@ -4,7 +4,9 @@
|
|||||||
|
|
||||||
- Python 3.12+, пакет `site_engine` в `src/`. Публичный сайт — статический HTML из Markdown/YAML и Jinja2; FastAPI обслуживает админку, публикацию и статику.
|
- Python 3.12+, пакет `site_engine` в `src/`. Публичный сайт — статический HTML из Markdown/YAML и Jinja2; FastAPI обслуживает админку, публикацию и статику.
|
||||||
- Контент — файлы; сборка не зависит от SQLite. Конвейер: `core/registry.py` → `core/validate.py` → `core/render.py` → `build/pipeline.py`.
|
- Контент — файлы; сборка не зависит от SQLite. Конвейер: `core/registry.py` → `core/validate.py` → `core/render.py` → `build/pipeline.py`.
|
||||||
|
- Ветки и состав коммитов: [docs/BRANCHING.md](docs/BRANCHING.md).
|
||||||
- Контекст и архитектура: `README.md`, `docs/TZ-site-engine-decisions.md` (ADR-001…006). Часть ТЗ ещё не реализована; фактические возможности сверяй с кодом и тестами.
|
- Контекст и архитектура: `README.md`, `docs/TZ-site-engine-decisions.md` (ADR-001…006). Часть ТЗ ещё не реализована; фактические возможности сверяй с кодом и тестами.
|
||||||
|
- Внешний агент/MCP: `docs/extends/mcp-agent-integration.md` — архитектурное предложение и этапы для будущей спеки (общий слой, API keys/scopes, онбоардинг, changeset). Это не реализованный контракт.
|
||||||
|
|
||||||
## Куда подключать дизайн
|
## Куда подключать дизайн
|
||||||
|
|
||||||
@@ -19,6 +21,10 @@
|
|||||||
- Новый перенос — `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/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).
|
- Фоновый редактор — `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).
|
||||||
|
|
||||||
|
- Content Editor — `/admin/content/{collection}/{id}`, исходник `design/content-antirion.html` / `assets/content-editor.{css,js}`. CSS/SVG воспроизводятся `scripts/sync_content_design.py --check`, адаптеры отдельно. Общая очередь 003, schema-driven поля, настоящие relations/usages/check/duplicate/delete; CAS-записи через ContentService. Live/Page — immutable release; Live/Card не хранится. Контракт/границы — `specs/001-antirion-admin/content-backend.md`, QA — `scripts/qa_content_001.py`, отчёт — `verification-content.md`. Пользователь разрешил переход к этапу 5.
|
||||||
|
|
||||||
|
- Publication — `/admin/publish`, оригинал `design/publication-antirion.html` / `assets/publication.{css,js}`. CSS/SVG: `scripts/sync_publication_design.py --check`; адаптеры отдельно. PublicationService: private `SITE_STATE_DIR/publication`, build без activation, hashes source/renderer/output + expected_live под SiteLock, preview точного релиза, activate без рендера; rollback не меняет workspace. Старые релизы без provenance имеют неизвестное сравнение. Ошибки после commit передают committed_build; не повторять POST вслепую. Контракт/ограничения — `specs/001-antirion-admin/publication-backend.md`, QA — `scripts/qa_publication_001.py`, отчёт — `verification-publication.md`. Этап 5 подготовлен к проверке пользователя. Начальный JSON — hidden textarea, не script: htmx удаляет script при allowScriptTags:false. Вход через меню/повторные переходы/Back-Forward — `scripts/qa_publication_navigation_001.py`.
|
||||||
|
|
||||||
## Правила интеграции
|
## Правила интеграции
|
||||||
|
|
||||||
- Админский дизайн переносить из выбранных `design/antirion-rework.html` и связанных editor/publication-макетов: сохранять разметку, CSS, иконки и сценарии, заменяя mock-данные API. Самостоятельное подобие макета недопустимо. Повторный перенос идёт по [этапам](specs/001-antirion-admin/design-transfer.md); после каждого этапа пользователь проверяет результат до перехода к следующему.
|
- Админский дизайн переносить из выбранных `design/antirion-rework.html` и связанных editor/publication-макетов: сохранять разметку, CSS, иконки и сценарии, заменяя mock-данные API. Самостоятельное подобие макета недопустимо. Повторный перенос идёт по [этапам](specs/001-antirion-admin/design-transfer.md); после каждого этапа пользователь проверяет результат до перехода к следующему.
|
||||||
@@ -43,14 +49,14 @@
|
|||||||
Из корня репозитория:
|
Из корня репозитория:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
PYTHONPATH=src python -m unittest discover -s tests -v
|
PYTHONPATH=src python scripts/run_regression.py
|
||||||
PYTHONPATH=src python -m site_engine.cli validate examples/site-studio
|
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
|
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`.
|
Дополнительная приёмка 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.
|
Собранный сайт — `/tmp/site-studio-dist/current/`. Старые тесты ещё ссылаются на удалённый examples/studio-site; scripts/run_regression.py автоматически извлекает временную базовую фикстуру из истории и мигрирует файловую тему, не меняя checkout. Нужны Git и коммит 231490b (в shallow clone следует получить историю). Обычный unittest discover без runner пока не готовит эту фикстуру. Не восстанавливай удалённые примеры в рабочем дереве ради тестов. Целевые проверки 003 используют независимую фикстуру и текущий Site Studio.
|
||||||
|
|
||||||
- Пример сайта используется как фикстура тестов: изменения контента и разметки сверяй с соответствующими проверками. Для изменений поведения обновляй целевые тесты; для чистого CSS проверяй сборку и внешний вид в браузере.
|
- Пример сайта используется как фикстура тестов: изменения контента и разметки сверяй с соответствующими проверками. Для изменений поведения обновляй целевые тесты; для чистого CSS проверяй сборку и внешний вид в браузере.
|
||||||
- Черновики могут быть неполными; релиз содержит только `published`. Ошибка сборки не должна менять текущий релиз, публикация и откат переключают `current` атомарно.
|
- Черновики могут быть неполными; релиз содержит только `published`. Ошибка сборки не должна менять текущий релиз, публикация и откат переключают `current` атомарно.
|
||||||
|
|||||||
@@ -2,22 +2,24 @@
|
|||||||
|
|
||||||
Движок сайтов на Markdown + YAML: страницы собираются из **layouts** и **fragments**, контент и структура живут в файлах, результат — статический сайт. Подключение агента по MCP — часть архитектуры (этап M3).
|
Движок сайтов на 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
|
```bash
|
||||||
pip install -e ".[dev]" # ядру нужны jinja2, PyYAML, markdown-it-py, click
|
pip install -e ".[server,dev]" # ядру нужны jinja2, PyYAML, markdown-it-py, click
|
||||||
site-engine validate examples/studio-site
|
site-engine validate examples/site-studio
|
||||||
site-engine build examples/studio-site --out /tmp/studio-dist
|
site-engine build examples/site-studio --out /tmp/site-studio-dist
|
||||||
site-engine preview examples/studio-site drafts/next > /tmp/draft.html
|
site-engine preview examples/site-studio index > /tmp/site-preview.html
|
||||||
site-engine fragments # 17 встроенных фрагментов
|
site-engine fragments # каталог встроенных фрагментов
|
||||||
make test # или: pytest
|
make test # временная историческая фикстура, без записи в examples/
|
||||||
```
|
```
|
||||||
|
|
||||||
Результат сборки: `OUT/<build_id>/` и симлинк `OUT/current`, который переключается атомарно. Неудачная сборка `current` не трогает.
|
Результат сборки: `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).
|
Отдельный перенос публичного дизайна из `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 доступна обычная форма исходника.
|
- **Обычные формы и локальный 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).
|
Развитие админки описано в [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-блоков запрещены.
|
- **Блоки перемещаются** кнопками ↑/↓ или перед указанным ID. Между регионами/слотами действует проверка схемы; циклы и изменение fixed-блоков запрещены.
|
||||||
- **Запись коллекции со «лишним» ключом**, которого нет в схеме, нельзя сохранить в статусе `published`, пока ключ не уберут из файла: так требует ADR-003.
|
- **Запись коллекции со «лишним» ключом**, которого нет в схеме, нельзя сохранить в статусе `published`, пока ключ не уберут из файла: так требует ADR-003.
|
||||||
|
|||||||
@@ -0,0 +1,88 @@
|
|||||||
|
# Git-ветки и коммиты Flexly CMS
|
||||||
|
|
||||||
|
## Именование
|
||||||
|
|
||||||
|
Для новой функциональности и изменений по спецификации используем:
|
||||||
|
|
||||||
|
```text
|
||||||
|
<type>/spec-<NNN>-<slug>
|
||||||
|
```
|
||||||
|
|
||||||
|
Примеры для существующих спецификаций:
|
||||||
|
|
||||||
|
```text
|
||||||
|
feat/spec-001-content-publication
|
||||||
|
fix/spec-001-publication-navigation
|
||||||
|
feat/spec-002-theme-manager
|
||||||
|
fix/spec-003-editor-update-queue
|
||||||
|
docs/spec-001-runtime
|
||||||
|
```
|
||||||
|
|
||||||
|
`spec-001`, `spec-002`, `spec-003` соответствуют каталогам в `specs/`:
|
||||||
|
`001-antirion-admin`, `002-site-studio-theme`, `003-background-editor`.
|
||||||
|
Несколько этапов одной спецификации могут иметь отдельные ветки с разными slug.
|
||||||
|
Номер новой спецификации выбирается по каталогу `specs/`, а не по числу веток.
|
||||||
|
|
||||||
|
Для небольшой работы без спецификации достаточно `<type>/<slug>`, например
|
||||||
|
`docs/mcp-agent-integration` или `chore/test-runner`. В проекте нет обязательного
|
||||||
|
трекерного префикса; чужие идентификаторы `po-N` не используются.
|
||||||
|
|
||||||
|
`slug` — короткое описание строчными ASCII-буквами в kebab-case. Не добавляем
|
||||||
|
даты, имя автора и служебные суффиксы. Рекомендуемая длина имени — до 80 символов.
|
||||||
|
Если инструмент создаёт ветку автоматически, передаём имя в этом формате.
|
||||||
|
Существующие ветки ради нового правила не переименовываем.
|
||||||
|
|
||||||
|
## Типы
|
||||||
|
|
||||||
|
| Тип | Назначение |
|
||||||
|
|---|---|
|
||||||
|
| `feat` | Новая возможность или этап спецификации |
|
||||||
|
| `fix` | Исправление дефекта или регрессии |
|
||||||
|
| `docs` | Только документация, спецификации и архитектурные предложения |
|
||||||
|
| `chore` | Зависимости, инструменты, CI и техническое обслуживание |
|
||||||
|
| `hotfix` | Срочное исправление работающего развёртывания |
|
||||||
|
|
||||||
|
Тип выбираем по цели. Тесты, необходимые для новой возможности или исправления,
|
||||||
|
входят в ту же ветку; отдельные типы `test`, `refactor`, `ci`, `perf` не нужны.
|
||||||
|
|
||||||
|
## База и жизненный цикл
|
||||||
|
|
||||||
|
- Основная ветка проекта — `main`. Отдельная интеграционная `dev` сейчас не используется.
|
||||||
|
- Новые рабочие ветки создаём от актуальной локальной `main`; получение изменений
|
||||||
|
с remote выполняем, когда он настроен и доступен. Не подразумеваем наличие
|
||||||
|
branch protection, автоматического CI или обязательной платформы для PR.
|
||||||
|
- Для следующей самостоятельной работы предпочитаем рабочую ветку. Текущие
|
||||||
|
изменения, уже подготовленные в `main`, можно завершить там по согласованной
|
||||||
|
команде пользователя на коммит; перенос ради самого имени ветки не требуется.
|
||||||
|
- Перед объединением проверяем diff, запускаем проверки по изменению и описываем
|
||||||
|
результат. Для интерфейса проверяем настоящий FastAPI в браузере, включая
|
||||||
|
переходы через htmx, широкое и мобильное окно. Для runtime/API выполняем
|
||||||
|
соответствующие серверные тесты; перед выпуском — полную регрессию и wheel.
|
||||||
|
Команды и ограничения — [AGENTS.md](../AGENTS.md) и отчёты в `specs/`.
|
||||||
|
- Каждый согласованный этап переноса дизайна проверяет пользователь, как указано
|
||||||
|
в [AGENTS.md](../AGENTS.md). Успешная автоматическая проверка не заменяет эту приёмку.
|
||||||
|
- Способ объединения выбираем по задаче, сохраняя понятную историю. Не переписываем
|
||||||
|
опубликованную историю и не делаем force-push без отдельного согласования.
|
||||||
|
- Push, публикация PR и развёртывание — отдельные действия. Разрешение на локальный
|
||||||
|
коммит само по себе не означает разрешение на выпуск на сервер.
|
||||||
|
- После объединения рабочую ветку можно удалить, если она больше не нужна;
|
||||||
|
удаление ветки на remote согласуем отдельно.
|
||||||
|
|
||||||
|
## Состав коммитов
|
||||||
|
|
||||||
|
Коммит должен содержать законченное изменение: исходники, необходимые шаблоны и
|
||||||
|
статику, тесты, актуальный контракт и документацию. Общие изменения одного
|
||||||
|
runtime не разделяем так, чтобы промежуточный коммит переставал работать.
|
||||||
|
Независимые архитектурные документы и инструменты можно коммитить отдельно.
|
||||||
|
Заголовок начинаем с действия и указываем результат; допустим формат
|
||||||
|
`feat(admin): add publication candidates` или привычный проекту `Add publication candidates`.
|
||||||
|
|
||||||
|
При добавлении ресурсов админки проверяем их включение в wheel, происхождение
|
||||||
|
дизайна в `static/VENDOR.md` и отсутствие изменений сгенерированного контракта
|
||||||
|
без соответствующего API. `design/`, `examples/site-studio/`, исходники builtin
|
||||||
|
и `AGENTS.md` — версионируемые части проекта; состав конкретного коммита зависит
|
||||||
|
от задачи.
|
||||||
|
|
||||||
|
Не добавляем секреты и рабочие артефакты: `.env`, `data/`, `.engine/`, служебное
|
||||||
|
состояние, `dist/`, `build/`, журналы и браузерные снимки из `/tmp`. Перед коммитом
|
||||||
|
проверяем `git diff --cached` и `git diff --check`.
|
||||||
@@ -0,0 +1,235 @@
|
|||||||
|
# Внешний агент: MCP, подключение и подготовка изменений
|
||||||
|
|
||||||
|
Дата: 2026-11-17.
|
||||||
|
|
||||||
|
Статус: архитектурное предложение по результатам обсуждения. Документ сохраняет направление развития и этапы для будущей спецификации; сам по себе не означает готовность MCP, утверждение точного API или начало реализации. Имена новых инструментов и scopes предварительные. Номер будущей спеки здесь не резервируется.
|
||||||
|
|
||||||
|
## 1. Цель и границы
|
||||||
|
|
||||||
|
Агент подключается по MCP, получает доступный ему контекст сайта, готовит набор изменений, проверяет его и передаёт человеку на просмотр. Применение изменений к рабочим файлам и публикация — отдельные операции с отдельными разрешениями.
|
||||||
|
|
||||||
|
Один прикладной контракт должен обслуживать человека, агента и автоматизацию: одинаковые предметные операции, права, схемы, валидация, контроль версий и ошибки. Контент остаётся в Markdown/YAML, публичный сайт — статическим результатом штатного renderer. Отдельная реализация CMS для агента не нужна.
|
||||||
|
|
||||||
|
Первый рабочий сценарий: агент изучает страницы, коллекции и каталог фрагментов, предлагает изменения нескольких документов, получает diff и preview, человек проверяет и применяет точную версию предложения. Агент по умолчанию не публикует сайт и не меняет исполняемый код.
|
||||||
|
|
||||||
|
## 2. Что уже есть, а чего пока нет
|
||||||
|
|
||||||
|
| Область | Фактическое состояние на дату документа |
|
||||||
|
|---|---|
|
||||||
|
| MCP | В `src/site_engine/mcp/server.py` перечислены 15 предполагаемых инструментов; `build_server()` вызывает `NotImplementedError`. Работающего подключения нет |
|
||||||
|
| Зависимость SDK | Extra `mcp` в `pyproject.toml`; наличие зависимости не означает готовность сервера |
|
||||||
|
| JSON API | FastAPI `/admin/api/v1/`, DTO на Pydantic, внутренний клиент HTML-адаптера |
|
||||||
|
| Авторизация API | Credentials для внутренних запросов UI, привязанные к админской сессии. Для внешнего агента не предназначены |
|
||||||
|
| Документы | PageService/EntryService/DocumentService: чтение, создание, преобразование, проверка, явное сохранение |
|
||||||
|
| Запись | ContentService: безопасные пути, SiteLock, CAS/etag, история, атомарная запись отдельного файла |
|
||||||
|
| Кандидат в памяти | Общая очередь редактора и overlay одного документа без записи исходника. Это ещё не сохранённый многодокументный changeset |
|
||||||
|
| Preview | Реальный renderer, immutable snapshots, TTL и CSP; владельцем сейчас служит пользовательская сессия, отзыв связан с эпохой админской авторизации |
|
||||||
|
| Изучение контента | Схемы, категории фрагментов, метаданные коллекций; структурированные связи и usages записей. Полного индекса Markdown/Jinja/JS нет |
|
||||||
|
| Релизы | Сборка, публикация и откат; это не workflow согласования предложений агента |
|
||||||
|
| API keys и RBAC | В `db/models.py` есть декларативные модели User/ApiToken с хешем, scopes и сроками; работающий жизненный цикл ключей и политики агента не реализованы |
|
||||||
|
| Changeset | `services/changeset.py` — заглушка. `ContentService.update_files` не гарантирует восстановление после аварии между записями файлов |
|
||||||
|
|
||||||
|
Текущая архитектура подходит для развития MCP. Основные пробелы — общая авторизация предметных операций, внешний доступ, изоляция предлагаемых изменений и согласование их точной версии.
|
||||||
|
|
||||||
|
## 3. Общий прикладной слой
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
H[Человек: админка / htmx] --> F[FastAPI JSON]
|
||||||
|
A[Внешний агент] --> M[MCP / Streamable HTTP]
|
||||||
|
F --> S[Общие операции и политика доступа]
|
||||||
|
M --> S
|
||||||
|
S --> D[Документы, схемы, валидация, preview]
|
||||||
|
S --> C[Changeset и согласование]
|
||||||
|
D --> W[Файловый workspace]
|
||||||
|
C --> W
|
||||||
|
W --> R[Сборка и immutable-релизы]
|
||||||
|
```
|
||||||
|
|
||||||
|
Выделить транспортно-независимый слой прикладных операций поверх существующих сервисов. Он принимает доверенный контекст вызывающего, проверяет доступ, вызывает предметные сервисы и возвращает единый результат. FastAPI преобразует его в HTTP/JSON, MCP — в результат инструмента. Ядро сохраняет dataclass; общие DTO и схемы операций находятся вне HTML-обработчиков и могут использовать Pydantic на границах.
|
||||||
|
|
||||||
|
Из HTTP-маршрутов вынести повторно используемую оркестрацию update/validate/preview, нормализацию предметных ошибок и проверки разрешений. HTTP-статусы, cookies, CSRF и рендер HTML остаются транспортными задачами. Инфраструктурные ошибки логируются со стеком на сервере и безопасным request ID для клиента.
|
||||||
|
|
||||||
|
В одном процессе MCP вызывает общие операции напрямую. При отдельном развёртывании допустим серверный API-клиент с той же политикой доступа. Открывать внутренний UI-токен внешнему клиенту нельзя. Дублировать renderer, парсер схем, проверки или файловые записи в MCP нельзя.
|
||||||
|
|
||||||
|
Агент получает типизированные операции: metadata, entry_fields, add/update/move/delete block и т. п. Операция `inspector`, работающая с именами HTML-полей, остаётся внутренним адаптером UI. Блоки адресуются по стабильному ID; новые ID следуют правилу `<fragment_id>_<suffix>`.
|
||||||
|
|
||||||
|
Авторизация действует на общем входе в прикладные операции, включая чтение. Низкоуровневые файловые сервисы сохраняют собственные ограничения путей и CAS. Внешний транспорт не может обойти политику прямым вызовом иной операции.
|
||||||
|
|
||||||
|
## 4. Подключение, API keys и scopes
|
||||||
|
|
||||||
|
### 4.1 Транспорт и идентичность
|
||||||
|
|
||||||
|
Для удалённых агентов — Streamable HTTP, предполагаемый путь `/mcp`, первоначально внутри того же FastAPI-приложения. Версию протокола и SDK, lifecycle сессии и поведение reverse proxy уточнить в спецификации с учётом выбранных клиентов.
|
||||||
|
|
||||||
|
Подключение — отдельная сущность с владельцем, именем агента/интеграции, разрешениями и статусом. Ключ — сменяемый credential подключения, а не пароль администратора. Контекст операции включает владельца, тип актора `agent`, ID подключения, ID credential без секрета, разрешения, область объектов и correlation/request ID.
|
||||||
|
|
||||||
|
API key подходит для управляемой интеграции, если клиент умеет передавать Bearer credential. Подключение через стандартную интерактивную авторизацию для разных MCP-клиентов требует OAuth-процесса по поддерживаемой версии MCP. Нельзя обещать совместимость API key со всеми клиентами. Минимальную матрицу клиентов и способ авторизации выбрать до реализации транспорта.
|
||||||
|
|
||||||
|
### 4.2 Жизненный цикл ключа
|
||||||
|
|
||||||
|
- Создание владельцем с явной областью доступа и сроком действия; секрет показывается один раз.
|
||||||
|
- Криптографически случайный секрет; в служебном хранилище только стойкий проверочный хеш и несекретный идентификатор, название, владелец, сроки и состояние.
|
||||||
|
- Просмотр метаданных, последнее использование, отзыв и ротация. Секреты не попадают в ответы диагностики, аудит, URL или логи.
|
||||||
|
- Отзыв/истечение проверяются на каждом запросе; существующая MCP-сессия не продолжает работу по отозванному ключу.
|
||||||
|
- Права ключа не превышают действующие права владельца; блокировка владельца и сокращение прав учитываются без повторного подключения.
|
||||||
|
- Состояние ключей, отзыва и операций общее для workers и сохраняется после перезапуска. Одного process-local словаря недостаточно.
|
||||||
|
|
||||||
|
Использовать либо расширить имеющиеся модели служебной БД после проверки миграций и транзакций. Хранилище ключей и workflow не становится источником контента сайта.
|
||||||
|
|
||||||
|
### 4.3 Модель разрешений
|
||||||
|
|
||||||
|
Предварительное разделение действий:
|
||||||
|
|
||||||
|
| Разрешение | Назначение |
|
||||||
|
|---|---|
|
||||||
|
| `content:read` | Чтение разрешённых документов и их метаданных |
|
||||||
|
| `catalog:read` | Доступ к разрешённым схемам фрагментов, коллекций, layouts/display и правилам |
|
||||||
|
| `assets:read` | Поиск и чтение разрешённых ассетов |
|
||||||
|
| `changeset:write` | Создание и изменение своих предложений, передача на проверку |
|
||||||
|
| `preview:read` | Получение preview разрешённого кандидата |
|
||||||
|
| `changeset:apply` | Применение конкретного разрешённого/согласованного предложения |
|
||||||
|
| `assets:upload` | Отдельно разрешённая безопасная загрузка |
|
||||||
|
| `content:write` | Опциональная прямая запись в workspace для доверенной автоматизации |
|
||||||
|
|
||||||
|
Это варианты для будущей матрицы, не готовые публичные имена. Правила доступа к чужим changeset, согласования и административных действий определить отдельно. `publish`/`rollback` по умолчанию не выдаются и не включаются в первый набор инструментов агента.
|
||||||
|
|
||||||
|
Scope задаёт действие, а отдельные ограничения — сайт, разделы страниц, коллекции и при необходимости объекты/поля. Пустая или отсутствующая область не должна случайно означать полный доступ. Проверять итоговое состояние документа: raw source, status, route, layout, ссылки и вложенные блоки не должны обходить ограничения через другой формат команды.
|
||||||
|
|
||||||
|
Фильтрация действует до пагинации и расчёта счётчиков; учитывается в поиске, refs/usages, diff, preview и ошибках. Недоступные документы не раскрываются через соседние результаты. Рендер использует только разрешённую проекцию: возможность увидеть данные, подтягиваемые query/refs/layout, должна быть согласована с правами. Если корректный preview требует недоступных данных, возвращать явное ограничение, не скрытую утечку.
|
||||||
|
|
||||||
|
## 5. Онбоардинг и контекст агента
|
||||||
|
|
||||||
|
Протокольное подключение и знакомство с сайтом — разные шаги. После initialize клиенту доступен небольшой инструмент `get_agent_context`:
|
||||||
|
|
||||||
|
- Идентичность и назначение сайта, язык, включённые features.
|
||||||
|
- Эффективные права и область доступа этого подключения.
|
||||||
|
- Версия контракта и схемы, поддерживаемые операции, лимиты.
|
||||||
|
- Версия workspace и текущего релиза, способ получения схем и правил.
|
||||||
|
- Семантика draft/workspace/changeset/live, порядок проверки и согласования.
|
||||||
|
- Инструкции по ID, типизированным ссылкам, bindings, query и явным ограничениям движка.
|
||||||
|
|
||||||
|
Стартовый ответ компактный. Документы и схемы загружаются по необходимости. MCP resources публикуют руководство, правила и схемы; prompts могут предлагать типовые сценарии. Критичные сведения доступны также инструментами: поддержка resources/prompts зависит от клиента. Наличие инструкции не заменяет серверную проверку прав.
|
||||||
|
|
||||||
|
Каталог формируется из настоящих `fragment.yaml`: ID, name, description, категория, поля, defaults, слоты, допустимые места использования и preview. Категории `content`, `data`, `forms`, `marketing`, `media`, `system`, дополнительные категории и старое плоское размещение сохраняют существующую семантику. Отдельный вручную поддерживаемый каталог для агента не создавать.
|
||||||
|
|
||||||
|
Текст страниц, записей и ассетов передаётся как данные сайта. Он не может выдавать новые полномочия, подменять правила подключения или становиться доверенной инструкцией сервера.
|
||||||
|
|
||||||
|
## 6. Инструменты и объём ответов
|
||||||
|
|
||||||
|
Существующие 15 ToolSpec не покрывают весь самостоятельный рабочий цикл. Предлагаемый состав по задачам:
|
||||||
|
|
||||||
|
| Область | Возможности для будущего контракта |
|
||||||
|
|---|---|
|
||||||
|
| Ориентация | `get_agent_context`, `get_site_info`, получение правил |
|
||||||
|
| Контент | `list_pages`, `get_page`, `list_collections`, `list_entries`, `get_entry`, `search_content` |
|
||||||
|
| Схемы | `list_fragments`, `get_fragment_schema`, `get_collection_schema`, получение layout/display и ограничений регионов |
|
||||||
|
| Ассеты | `list_assets`, `get_asset`; `upload_asset` только после отдельной реализации загрузок |
|
||||||
|
| Зависимости | `get_references`, `get_usages` с явным указанием покрытия анализа |
|
||||||
|
| Предложения | Создание/чтение changeset, добавление типизированных операций, изменение и отказ от предложения |
|
||||||
|
| Проверка | `validate_changeset`, `get_changeset_diff`, `get_preview_url` |
|
||||||
|
| Согласование | `submit_changeset`, просмотр состояния; approve/apply только соответствующим акторам |
|
||||||
|
| Расширения | Rename со ссылками, меню, data, тема — отдельные разрешения и этапы |
|
||||||
|
|
||||||
|
Точный набор и объединение инструментов определить в спецификации. Не нужно отдельного инструмента на каждую кнопку UI. Создание страницы/записи и изменение блоков могут быть операциями changeset вместо немедленной записи инструментами `create_*`/`patch_*`.
|
||||||
|
|
||||||
|
Обязательные свойства контракта:
|
||||||
|
|
||||||
|
- Пагинация, стабильный порядок, фильтры и максимальный размер ответа у списков. Сначала краткие сведения, полный source/schema — отдельным запросом.
|
||||||
|
- Ограничение размера исходников, числа операций, глубины структуры, стоимости query/рендера и частоты вызовов.
|
||||||
|
- У чтения документа — source/модель и `etag`; у схем — версия/fingerprint; у кандидата — собственная revision.
|
||||||
|
- Проверка dry-run не пишет workspace. Создание самого changeset и временных preview — явно описанные служебные записи.
|
||||||
|
- MCP-результаты структурированы; предметная ошибка отличается от протокольной. Полезные поля: `code`, `message`, `request_id`, `issues`, путь поля, признак возможности повтора и сведения о фактическом commit.
|
||||||
|
- Нет неограниченного `read_file`/`write_file`, произвольных путей, выполнения Python/Jinja/JS или доступа к секретам через контентные инструменты.
|
||||||
|
|
||||||
|
Текущие структурированные refs/usages можно переиспользовать, сохранив ограничение: произвольные ссылки в Markdown/Jinja/JS пока не индексируются. Ответ не должен обещать полноту графа зависимостей.
|
||||||
|
|
||||||
|
## 7. Changeset и семантика черновиков
|
||||||
|
|
||||||
|
Различать три сущности:
|
||||||
|
|
||||||
|
1. `status: draft` — статус документа и участие в публикации.
|
||||||
|
2. Changeset — ещё не применённое предложение изменить один или несколько документов.
|
||||||
|
3. Релиз — immutable опубликованный снимок сайта.
|
||||||
|
|
||||||
|
Запрет агенту вызывать publish недостаточен: запись в общий workspace может попасть в следующую публикацию человека. Поэтому обычный агент сначала работает с изолированным changeset. Существующая опубликованная страница не переводится автоматически в draft ради подготовки новой редакции.
|
||||||
|
|
||||||
|
Предлагаемый цикл:
|
||||||
|
|
||||||
|
1. Прочитать нужные документы и схемы, получить базовые версии.
|
||||||
|
2. Создать changeset с целью и автором.
|
||||||
|
3. Добавить операции для существующих/новых документов; новые блоки получают стабильные ID.
|
||||||
|
4. Построить общий overlay нескольких документов с учётом взаимных ссылок и queries.
|
||||||
|
5. Проверить схемы, ссылки, маршруты и рендер; получить diff и preview.
|
||||||
|
6. Передать конкретную revision человеку.
|
||||||
|
7. Человек согласовывает и применяет эту версию; общий workspace меняется через ContentService и механизм журнала.
|
||||||
|
8. Публикация выполняется отдельно по правилам релизного процесса.
|
||||||
|
|
||||||
|
Хранить ID, владельца и актора, цель, базовые etag, revision, операции/подготовленные исходники, schema fingerprint, результаты проверки и сведения о согласовании/применении. Предварительные состояния: editing → submitted → approved → applied; rejected/discarded, conflict и операция с неопределённым результатом должны иметь явное поведение. Точный автомат состояний определить в спеках.
|
||||||
|
|
||||||
|
Любое изменение после согласования создаёт новую revision и снимает применимость прежнего согласования. Удаление/rename требует проверки зависимостей и явного списка затронутых объектов. Прямая запись в workspace возможна позднее как отдельная привилегия доверенной автоматизации.
|
||||||
|
|
||||||
|
Текущий редактор человека продолжает хранить несохранённые правки в памяти вкладки и писать только по Save. Changeset агента не вводит скрытый autosave документов и не меняет этот контракт.
|
||||||
|
|
||||||
|
## 8. Конкурентность, применение и восстановление
|
||||||
|
|
||||||
|
Diff, validation, preview и согласование привязываются к одной revision changeset, базовым версиям документов и значимым схемам/зависимостям. Применение перепроверяет их под блокировкой. Для точного просмотренного результата учитывать также изменения данных, влияющих на query/рендер: одного etag изменяемого файла недостаточно. Гранулярность проверки зависимостей либо fingerprint всего workspace выбрать в спецификации.
|
||||||
|
|
||||||
|
При конфликте возвращать изменившиеся объекты и разрешённые свежие версии. Агент должен перечитать данные и явно пересобрать предложение. Автоматическая подстановка нового etag и перезапись по принципу «последний победил» недопустимы.
|
||||||
|
|
||||||
|
Многодокументное применение требует staging, предварительной проверки набора, журнала и восстановления после сбоя по ADR-004. Нельзя заявлять атомарность нескольких файлов на уровне ОС. Определить, как чтение/публикация исключают наблюдение частично применённого состояния, и выполнять recovery до открытия доступа к workspace.
|
||||||
|
|
||||||
|
Создание и применение поддерживают ключ идемпотентности и запрос результата операции. Повтор с тем же ключом и другим payload — конфликт. После таймаута или отказа аудита агент сначала выясняет результат, а не повторяет запись вслепую. Сохранить семантику текущих `committed`/`deleted`, дополнив её ID операции и состоянием.
|
||||||
|
|
||||||
|
Согласование changeset не означает согласование любого будущего релиза: публикация общего workspace может включать другие изменения. В этапе 5 админки уже реализованы неизменяемый кандидат релиза и guarded activation (см. [publication-backend.md](../../specs/001-antirion-admin/publication-backend.md)). Связь reviewed changeset агента с этим кандидатом остаётся отдельной задачей будущей MCP-спеки; до неё не обещать публикацию «только проверенного набора».
|
||||||
|
|
||||||
|
## 9. Preview, аудит и эксплуатация
|
||||||
|
|
||||||
|
Preview агента связывается с подключением, changeset/revision и разрешённым набором данных. Нужен жизненный цикл отдельно от sid и общей эпохи админской сессии: TTL, отзыв, последствия отзыва ключа/подключения, ограничения количества snapshots. У проверяющего человека должен быть доступ через собственную авторизацию или отдельный ограниченный токен просмотра; credential агента ему не передаётся.
|
||||||
|
|
||||||
|
Сохраняются immutable snapshots, CSP, изоляция origin, запрет исполнения JS сайта в административном preview и отсутствие побочных записей workspace при рендере.
|
||||||
|
|
||||||
|
Аудит связывает владельца, подключение, ключ по несекретному ID, changeset/revision, request/correlation ID, операции проверки/применения и человека, который согласовал/применил/опубликовал. Не логировать секреты, полные тела документов и персональные данные. Успешный commit с отказом аудита должен быть отличим от отказа записи.
|
||||||
|
|
||||||
|
Лимиты на ключ/подключение и дорогие операции, совместимость нескольких workers, очистка snapshots/заброшенных changeset, резервное копирование служебного состояния и recovery входят в работоспособность интеграции. Подключение не должно зависеть от памяти единственного процесса.
|
||||||
|
|
||||||
|
## 10. Этапы реализации
|
||||||
|
|
||||||
|
Это последовательность для будущей спецификации. Сейчас ни один новый этап этим документом не считается выполненным.
|
||||||
|
|
||||||
|
| Этап | Состав | Проверяемый результат / зависимость |
|
||||||
|
|---|---|---|
|
||||||
|
| 1. Выделить общий прикладной слой | Общие команды/DTO и контекст актора; оркестрация read/update/validate/preview; единые ошибки и точка политики доступа. FastAPI и UI сохраняют поведение | Одни предметные операции доступны из адаптеров, нет копирования логики MCP и обхода сервиса; регрессия текущих UI/API проходит |
|
||||||
|
| 2. API keys и scopes | Сущности подключения/ключа, хеши, выпуск, TTL, отзыв, ротация, владелец; разрешения действий и объектов; миграции и аудит | Ключ с ограничением видит и меняет только разрешённое; отзыв действует между запросами и после рестарта, в нескольких workers. Внешнюю запись пока не включать |
|
||||||
|
| 3. MCP-подключение и онбоардинг | SDK/Streamable HTTP, выбранный способ авторизации, `get_agent_context`, resources/prompts, лимиты и диагностика; решение по OAuth | Реальный выбранный внешний клиент подключается, понимает права и получает контекст. Критичные сведения доступны без поддержки resources. Зависит от этапов 1–2 |
|
||||||
|
| 4. Инструменты чтения | Страницы/коллекции/записи, поиск, схемы, layouts/display, фрагменты с категориями, ассеты, refs/usages; пагинация | Агент самостоятельно находит данные и допустимые способы редактирования без догадок и утечек. Первый полезный релиз MCP только на чтение |
|
||||||
|
| 5. Изолированный changeset | Сохранённое предложение, версии базы/схем, типизированные операции, overlay нескольких документов, операции создания и отказа | Агент готовит связанные документы; исходный workspace и live не меняются. Это служебная подготовка, не разрешение прямой записи |
|
||||||
|
| 6. Проверка, diff и preview | Валидация всего кандидата и зависимостей, diff, preview точной revision, отдельные токены просмотра и доступ проверяющего | Человек и агент видят один кандидат; нет смешения live/workspace/changeset, проверка не пишет исходники. Зависит от этапа 5 |
|
||||||
|
| 7. Согласование и надёжное применение | Submit/review/approve/apply, права и точная revision; CAS зависимостей, staging/journal/recovery, идемпотентность, результат операции и аудит | Применяется согласованный набор; конфликт не затирает чужие данные; авария восстанавливается. Согласование можно выполнить текущим UI/API или CLI; новый экран требует отдельного согласованного дизайна |
|
||||||
|
| 8. Расширение по потребности | OAuth для дополнительных клиентов, если не вошёл в этап 3; uploads, rename, меню/data/тема, опциональная прямая запись, интеграция с reviewed release candidate | Каждая возможность имеет отдельный scope, зависимость и проверки. Доступ к шаблонам/JS/схемам и publish/rollback не включается автоматически |
|
||||||
|
|
||||||
|
Разработку инфраструктуры changeset можно вести параллельно с инструментами чтения после фиксации общего контракта, но включение внешней записи зависит от проверки доступа и надёжности соответствующего пути. Публикация и RBAC могут потребовать отдельных спецификаций; не сводить все направления в один неделимый релиз.
|
||||||
|
|
||||||
|
Для будущей приёмки предусмотреть: реальный MCP-клиент; успешный onboarding; фильтрацию чтения/поиска/preview; истечение и отзыв ключа; согласованный многодокументный набор; конфликт с правками человека; таймаут после commit и безопасный повтор; аварию между записями и recovery; совместимость старой админки; отсутствие публикации без отдельного права.
|
||||||
|
|
||||||
|
## 11. Что решить при написании спецификации
|
||||||
|
|
||||||
|
- Какие внешние клиенты поддерживаем сначала, какая версия MCP/SDK и способ авторизации обязательны; нужен ли OAuth уже в первом релизе.
|
||||||
|
- Точная матрица ролей/scopes/объектов, доступ к общим данным рендера и правила для недоступных зависимостей.
|
||||||
|
- Размещение общего прикладного слоя и общих DTO без лишней переработки ядра.
|
||||||
|
- Служебное хранилище ключей, changeset и результатов операций; миграции, retention, recovery и работа нескольких workers.
|
||||||
|
- Точный набор инструментов и схемы операций, включая dry-run, source vs typed operations и лимиты ответов.
|
||||||
|
- Автомат состояний, полномочия согласующего, последствия изменения базы/схем и условия повторного согласования.
|
||||||
|
- Гранулярность workspace/dependency fingerprint, проверка коллизий маршрутов и взаимных ссылок новых документов.
|
||||||
|
- Гарантии применения нескольких файлов и поведение всех читателей при незавершённом commit.
|
||||||
|
- Жизненный цикл preview при отзыве ключа и способ доступа человека к предложению.
|
||||||
|
- Где человек проверяет предложение: существующие инструменты на первом этапе или новый экран. UI переносится из предоставленного дизайна; самостоятельно новый дизайн не придумывается.
|
||||||
|
|
||||||
|
## 12. Связанные документы и код
|
||||||
|
|
||||||
|
- [Исходное ТЗ, разделы 11–12](../TZ-site-engine.md) — исторический более широкий набор возможностей.
|
||||||
|
- [Журнал решений, ADR-004…006](../TZ-site-engine-decisions.md) — CAS, восстановимые changeset, права и границы MVP. Этот документ предлагает уточнения для новой спеки, не подменяет принятые ADR и не возвращает автоматически отложенные возможности старого ТЗ.
|
||||||
|
- [Заготовка MCP](../../src/site_engine/mcp/server.py), [заготовка changeset](../../src/site_engine/services/changeset.py), [модели служебной БД](../../src/site_engine/db/models.py).
|
||||||
|
- [Текущий JSON API](../../src/site_engine/web/api/routes.py), [DTO](../../src/site_engine/web/api/models.py), [DocumentService](../../src/site_engine/services/documents.py), [ContentService](../../src/site_engine/services/content.py).
|
||||||
|
- [Спецификация админки](../../specs/001-antirion-admin/spec.md) и [доработки Content](../../specs/001-antirion-admin/content-backend.md).
|
||||||
|
- [Фоновый редактор](../../specs/003-background-editor/spec.md) — stateless update, overlay и явное сохранение; эти механизмы переиспользуются без изменения поведения текущего UI.
|
||||||
Reference in New Issue
Block a user