Агентный слой
Блок отказа
Агент не смог. Блок отвечает на три вопроса подряд: что не вышло, что уже пробовали и что делать дальше.
- Повтор через 1 с — тот же код
- Повтор через 4 с — тот же код
Разметка
<div class="inst-failure" role="alert">
<div class="inst-failure-head">Не удалось прочитать terrain/chunks.bin</div>
<div class="inst-failure-reason">Файл заблокирован другим процессом (EBUSY)</div>
<ul class="inst-failure-tried">
<li>Повтор через 1 с — тот же код</li>
<li>Повтор через 4 с — тот же код</li>
</ul>
<div class="inst-failure-actions">
<button class="inst-btn inst-btn--sm inst-btn--primary" type="button">Повторить</button>
<button class="inst-btn inst-btn--sm" type="button">Пропустить файл</button>
</div>
</div>
Использование
<div class="inst-failure" role="alert">
<div class="inst-failure-head">Не удалось прочитать terrain/chunks.bin</div>
<div class="inst-failure-reason">Файл заблокирован другим процессом (EBUSY)</div>
<ul class="inst-failure-tried">
<li>Повтор через 1 с — тот же код</li>
</ul>
<div class="inst-failure-actions">
<button class="inst-btn inst-btn--sm inst-btn--primary" type="button">Повторить</button>
</div>
</div>
| Что | Обязательно | Почему |
|---|---|---|
role="alert" |
да | Отказ обязан перебить: он сообщает, что действие не выполнено |
inst-failure-actions хотя бы с одним выходом |
да | Блок отказа без действия — это сноска красного цвета |
| Машинный код в причине | да | «Что-то пошло не так» нельзя ни найти в логе, ни отправить в поддержку |
inst-failure-tried на <ul> |
нет, но обычно да | Попытки перечислимы, и их количество объявляется до чтения |
Устройство
Блок отказа без выхода не является блоком отказа — это красное сообщение, на которое нечего ответить. Пользователь агентной системы застревает: работа остановлена, а решения не предложено.
Минимум одно действие. Если продолжить нельзя в принципе — действием является «Отменить прогон».
| Возьмите другое | Когда |
|---|---|
Сноска или баннер с тоном error |
Сообщение, не останавливающее работу |
| Пустое состояние | Пусто не из-за ошибки |
| Запрос подтверждения | Агент не упал, а спрашивает разрешения |
«Что уже пробовали» — не украшение
<ul class="inst-failure-tried">
<li>Повтор через 1 с — тот же код</li>
<li>Повтор через 4 с — тот же код</li>
</ul>
Это единственное, что отличает отчёт агента от обычной ошибки. Без списка пользователь первым делом нажмёт «Повторить» — то есть сделает то, что машина уже сделала дважды.
Правила
Так Выход обязателен
«Повторить», «Пропустить», «Открыть лог». Блок отказа без действия — это сноска красного цвета.
Не так «Что-то пошло не так»
Такую причину нельзя ни найти в логе, ни отправить в поддержку. Нужен машинный код и расшифровка словами.
Так Список того, что уже пробовали
Он снимает первый вопрос человека — «а вы повторяли?» — и показывает, что автоматика своё отработала.
Не так Отказ без role="alert"
Сообщение о невыполненном действии обязано перебить, а не ждать своей очереди.
Доступность
role="alert" |
Обязателен: отказ возникает по инициативе машины и обязан быть объявлен немедленно. Тихо появившийся блок останется незамеченным |
| Не только цвет | Заголовок несёт значок и слово. Красный фон сам по себе ничего не сообщает |
| Причина текстом | Машинный код (EBUSY) сопровождается расшифровкой. Код без объяснения — это не причина, а её идентификатор |
| Фокус | При появлении блока фокус имеет смысл перевести на первое действие: пользователь только что потерял то, чем занимался |
| Контраст | Заголовок и текст проверены на --err-bg в шести темах. Рамка — color-mix от --err-text, декоративная: рядом есть перепад поверхностей |
| Повторяющиеся отказы | Несколько role="alert" подряд перебивают друг друга. Для серии отказов лучше один блок со счётчиком |
API
| Имя | Значение | Что делает |
|---|---|---|
| класс | ||
inst-failure | — | Блок |
inst-failure-head | — | Что не вышло. Со значком |
inst-failure-reason | — | Причина: машинный код и расшифровка |
inst-failure-tried | — | Что уже пробовали, на <ul> |
inst-failure-actions | — | Выход. Обязателен |
| токен | ||
--pad-card | var(--space-6) | |
--radius-lg | 11px | |
--space-3 | 6px | |
--err-bg | light-dark(var(--err-1), color-mix(in oklab, var(--err-4) 16%, transparent)) | |
--err-text | light-dark(var(--err-5), var(--err-3)) | |
--hairline | 1px | |
--text-sm | 0.8125rem | |
--text-xs | 0.75rem | |
--text-muted | light-dark(var(--n-8), var(--n-6)) | |
Почему кит устроен именно так — конституция · Открытый код под MIT, github.com/keshon/instrument