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