Кейсы

Кейс — короткое решение, снятое с живого сайта: какой фрейм взять, какие ключи написать во frontmatter и как проверить результат. Каждый кейс — отдельный раздел этой страницы. Переменные OP_TOKEN, API и SITE заданы, как в быстром старте. Пошаговые сценарии от пустого сайта — в рецептах.

Чат Framesuite на странице

Когда брать. Посадочная страница ассистента: на первом экране во всю ширину чат Framesuite, под ним статья. Так устроены главные ИИ-сайтов — посетитель сразу пишет в чат, а поисковик видит полноценную статью. Чат может открываться на стартовом экране ассистента или сразу на отдельном агенте.

Какой фрейм. Системный фрейм headless из библиотеки. Его нет на сайте — поставьте из библиотеки: POST /frames/system/headless/install (см. фреймы). Вложенные фреймы доезжают сами. Править разметку не нужно: какой чат и какого агента показать, решает frontmatter страницы.

Чат ассистента

---
name: "ИИ чат онлайн"
seo_title: "ИИ чат онлайн бесплатно"
seo_description: "Задайте вопрос ИИ прямо на странице."
slug: "ai-chat"
url: "/ai-chat/"
lang: "ru"
status: "publish"
frame: "headless"
data.assistant: "<assistant_id>"
data.agent_view: "profile"
cta: 1
---

Первый абзац статьи — сразу текст, без заголовка `#`: заголовок H1 фрейм берёт из `name`.

## Раздел статьи

Текст.

Отдельный агент

Тот же фрейм, к ключам добавляется слаг агента:

---
name: "AI logo creator"
slug: "logo-creator"
url: "/logo-creator/"
lang: "en"
status: "publish"
frame: "headless"
data.assistant: "<assistant_id>"
data.agent: "<agent_slug>"
data.agent_view: "profile"
cta: 1
---

Публикация — обычная: curl -s -X POST "$API/site/$SITE/pages/markdown" -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' -d "$(jq -n --rawfile md page.md '{markdown: $md}')" | jq '{id, url, frame, warnings}'. Поменять агента или ассистента — поправить ключ и опубликовать страницу ещё раз, фрейм не трогается.

Параметры

Ключ	Обязателен	Что делает
`frame: "headless"`	да	фрейм страницы: чат на первом экране, статья под ним
`data.assistant`	да	id чата Framesuite — 12 знаков из ссылки на чат `framesuite.app/f/<assistant_id>`. Нет ключа — нет чата: ни контейнера, ни скриптов, ни запроса к Framesuite
`data.agent_view`	да	первый экран: `profile` — карточка агента, `chat` — сразу переписка. Ставьте `profile`; другие значения отбрасываются
`data.agent`	для агента	слаг агента внутри ассистента — тот, что в ссылке на агента `?agent=<agent_slug>`. Латиница, цифры, `-` и `_`, до 100 знаков. Нет ключа — чат открывается без агента
`data.lib`	нет	страница приложения, с которой открывается чат, например `agents` — каталог агентов. Латиница в нижнем регистре, цифры, `-` и `_`, до 32 знаков
`cta: 1`	нет	общий блок призыва к действию в подвале, если он есть на сайте (см. frontmatter)

Агент, его экран и lib уходят в приложение параметрами запроса, в адресную строку страницы не попадают. Ключи можно писать и вложенно под data: — читаются так же.

Что под чатом

Под чатом — статья из тела страницы: H1 из name, подпись автора и кнопки «Поделиться», текст, справа оглавление по H2–H3 тела, блок вопросов из набора faq и подвал сайта. Подпись автора выводится, если у автора страницы есть запись в наборе author, оглавление — если в теле есть подзаголовки. Шапки сайта и пейджера нет — этим headless и отличается от article: там сверху шапка и заголовок статьи, а чата нет. Тело — чистый markdown: первой строкой не пишите # … (будет второй H1) и не вставляйте чат в тело.

Проверка

curl -s "https://example.com/ai-chat/" > page.html
grep -c 'id="ai-assistant-mount"' page.html          # 1 — чат на месте
grep -o '"slug":"[^"]*"' page.html | head -1          # id из data.assistant
grep -o '"entry":{[^}]*}' page.html                   # {"agent":"<agent_slug>","agent_view":"profile"}
grep -c '<h1' page.html                               # 1

Частые ошибки

Старый блок acf/widget. Вставка чата блоком первой версии (iframe с ?agent_view=profile&new=1) на страницах v2 ломает вёрстку. Не используйте: чат ставит фрейм headless, тело остаётся текстом.

Пустой data.assistant. Ошибка в имени ключа или пустое значение — и страница собирается без чата: вместо него в коде комментарий op/assistant: у страницы нет id ассистента. Проверьте выгрузкой GET /pages/{ref}/markdown, что ключ дошёл.

Нет data.agent_view. Без него вход неполный, чат открывается не на том экране. Пишите data.agent_view: "profile" всегда, в том числе без агента.

Чужой фрейм с похожим именем. На некоторых сайтах есть свой фрейм assistant — не системный, со своей разметкой (заголовок и оглавление там пишутся в теле). Для новых страниц берите системный headless; про assistant — отдельная страница.