Справочник атрибутов разметки

Сначала подключите выбор элементов и подготовьте сценарий. Здесь собраны правила определения элемента и его атрибуты.

Определите выбираемые элементы

Выбираемыми считаются:

• элементы с data-ai-context-id, data-ai-label, data-ai-kind, data-ai-action, data-ai-kb-doc-id, data-ai-kb-query, data-ai-reveals-context-id или data-ai-reveal-action;
• стандартные элементы button, a, input, textarea, select, label, summary;
• текстовые и структурные элементы article, section, li, p, h1-h6;
• элементы с ролями button, link, menuitem, tab, checkbox, combobox, radio, option, searchbox, textbox;
• элементы с aria-label или aria-labelledby.

data-ai-section сам по себе только описывает секцию. Если нужно выбрать весь блок, добавьте на него data-ai-label, data-ai-kind или data-ai-context-id.

Название выбранного элемента определяется по первому подходящему источнику: data-ai-label, aria-labelledby, связанный или ближайший label, aria-label, title, placeholder, затем видимый текст. Поэтому сначала исправляйте обычную HTML/ARIA-подпись, а data-ai-label используйте, когда интерфейсное название недостаточно понятно вне страницы.

Для повторяющихся строк и карточек всегда задавайте data-ai-entity-type и data-ai-entity-id парой. Общий data-ai-context-id описывает вид элемента, например строку лида, а пара сущности указывает на конкретного лида. Атрибуты читаются с самого выбранного элемента и не наследуются от родителя: если внутри повторяющейся карточки есть отдельная выбираемая кнопка, повторите пару сущности и на ней. Если на экране несколько элементов с одним контекстным ключом, действие без этой пары считается неоднозначным и не выполняется. Передача только одного из двух атрибутов также недопустима.

Добавьте нужные атрибуты

Все значения — строки. Ограничения в таблице соответствуют объёму данных, который виджет сохраняет в контексте выбранного элемента.

Атрибут	Для чего нужен	Ограничение / пример
data-ai-area	Стабильное имя крупной области страницы.	До 80 символов; например header, navigation, content, form, modal.
data-ai-section	Смысловой раздел внутри страницы.	До 120 символов; например catalog, checkout-payment, profile-settings.
data-ai-label	Понятное человеку название элемента вне контекста страницы.	До 180 символов.
data-ai-kind	Тип элемента в терминах продукта.	До 80 символов; например primary-action, form-field, product-card.
data-ai-action	Смысл действия элемента.	До 120 символов; например cart.add или checkout.pay. Не выдаёт разрешение на выполнение.
data-ai-context-id	Стабильная связь с документацией и точная цель действия.	До 120 символов; рекомендуется lowercase-ключ через точки, например checkout.payment.submit.
data-ai-kb-doc-id	Прямая ссылка на известный стабильный ID документа базы знаний.	До 80 символов. Не используйте как основную связь для переимпортируемой MD-документации.
data-ai-kb-query	Запасная поисковая фраза для базы знаний.	До 240 символов; например как оплатить заказ.
data-ai-entity-type	Тип конкретной сущности в повторяющемся списке.	До 80 символов; например product, plan, order.
data-ai-entity-id	ID конкретной сущности.	До 120 символов; например SKU или публичный ID тарифа. Всегда используйте вместе с data-ai-entity-type.
data-ai-reveals-context-id	Контекстный ключ или корень ключей, которые показывает этот переключатель.	Один или несколько ключей через пробел; до 2 000 символов суммарно.
data-ai-reveal-action	Способ раскрыть скрытую цель.	click, hover или focus; без атрибута используется click.
data-ai-value	Текущее значение нестандартного списка или значение его варианта для действия выбора.	Например off. Не помещайте сюда секреты; это значение для управления списком, а не его подпись.

Для действий на основной странице виджет сравнивает data-ai-context-id, data-ai-entity-type и data-ai-entity-id с учётом регистра и знаков: Catalog.save и catalog.save, item-a и item_a — разные ключи. Передавайте их в команды и документацию без изменений. Значения data-ai-reveals-context-id должны совпадать с ключом цели или его корнем: catalog раскрывает catalog.save, но не catalogue.save и не Catalog.save.

data-ai-action описывает назначение элемента, но не заменяет авторизацию, проверку прав и подтверждение на стороне сайта. data-ai-reveals-context-id и data-ai-reveal-action нужны только для нестандартных меню и панелей; стандартные связи aria-controls, popovertarget, commandfor и <details>/<summary> виджет определяет сам.

Чтобы data-ai-context-id извлекался из Markdown при загрузке в базу знаний, используйте не более 120 символов и как минимум две непустые части через точку. В частях допустимы латинские буквы, цифры, _ и -. Например, checkout.payment.submit подходит, а payment, checkout..submit и ключ с пробелом — нет.

Не помещайте в атрибуты пароли, токены, email, телефон, персональные данные или секретные служебные ID. Значения атрибутов и видимый текст выбранного элемента передаются агенту вместе с вопросом.

Примеры разметки показывают формы, карточки и нестандартные списки. Чтобы агент находил инструкцию, свяжите ключи с Markdown-документацией.