Требования к десктопному клиенту agentik

Статус: накидываем. Ни один пункт не обязателен к исполнению в том виде, как записан. Позже пересматриваем.

Основа дизайна: вариант 1 (sketches/001-sidebar-utility) — выбран.

Сейчас описываем только поведение. Кода не пишем, пока требования не устоятся.

1. Общее

R1. Стиль — тёмная тема, уже принятая в клиентах пользователя (фон #121218, панели #17212B, текст #EBEBEB).
R2. Что видно на экране в любой момент: список диалогов, выбранный диалог и поле ввода. Больше ничего обязательного нет.

2. Раскладка и адаптивность

R3. Широкое окно — две части: список диалогов слева, открытый диалог справа.
R4. Узкое окно — на экране что-то одно: либо список диалогов, либо конкретный диалог. Переключение — как в Телеграме.
R5. В узком окне у открытого диалога сверху слева — кнопка «Назад». Нажатие возвращает к списку диалогов на всю ширину.
R6. Порог «широкое/узкое» — по ширине окна, одна величина. Какой именно размер считать порогом — решим позже.

3. Список диалогов

R7. Группировка диалогов со временем появится — «Работа», «Дом» и подобное. Сейчас это накидка, состав групп ещё не определён.
R8. В строке диалога: название, последнее сообщение, время, счётчик непрочитанных.
R9. Есть поиск по диалогам.

4. Открытый диалог

R10. Показ сообщений: мои и ассистента, с временем.
R11. Ответ ассистента можно прервать — на видном месте кнопка «Стоп».
R12. Сообщения приходят вживую, по мере генерации: текст дотекает куском за куском, а не появляется целиком в конце. Отображать именно так.
R13. Разметка (markdown). Если я или агент пишем текст, похожий на разметку, показывать его разметкой, а не сырыми символами: списки, выделение, код, таблицы, ссылки. Код для этого писать не надо — готовая библиотека уже используется в клиенте assistent.

5. Панель ввода

R14. Поле ввода, кнопка «Отправить» и отдельная кнопка записи микрофона.
R15. Подсказка о горячих клавишах под полем убирается — её не должно быть.
R16. Пока идёт запись, должно быть понятно, что сейчас пишется голос.
R17. Отмена записи — явная.
R18. Голос: кнопка включает микрофон и останавливает его. Точная механика (по нажатию или на удержание) — решим позже.
R19. Распознавание речи — отдельная тема, здесь не решается. Важно только: где кнопка, что видно во время записи, что происходит после.

6. Несколько агентов

R20. Предусмотреть возможность подключать несколько агентов и видеть их в одном клиенте. Не «много людей», а один клиент — несколько агентов.
R21. Возможный способ различения — по аватару: у каждого агента свой аватар, по нему и отличаем. Тема аватаров не продумана, это накидка.
R22. Другие возможные способы (на выбор, обсудить):
- Цветовой акцент — у каждого агента свой цвет: полоса у пузыря ответа, цвет имени в шапке;
- Группировка в списке — диалоги сгруппированы по агентам, с заголовком группы (как секции каналов);
- Переключатель агента — как выбор аккаунта в Телеграме: все диалоги одного агента разом;
- Метка в строке диалога — маленький значок/буква агента рядом с названием.
R23. У библиотеки уже есть всё для этого: агент создаётся вызовом с двумя значениями — имя и адрес. Имя клиент знает сам, сервер его не хранит. Каждому агенту — своё имя и адрес.

7. Состояние агента: сколько израсходовано

Здесь свериться с исходниками оказалось важнее всего. Ниже — по факту из кода, не по догадкам.

7.1. Что есть в самой библиотеке `client` (что клиент реально получает)

У каждого события и каждого сообщения есть дата. Значит доступно: длительность хода, сколько времени агент думал, когда пришёл ответ.
Есть события: начало ответа, рассуждение, текст по мере генерации, картинка, вызов инструмента (имя, аргументы, заголовок), результат инструмента, конец хода, прерывание, ошибка.
Есть события о диалогах: создан, удалён, переименован.
По диалогу: название, время последнего изменения, умеет ли принимать и отдавать картинки, временный он или постоянный.
Токенов, модели, цены, предела контекста — в библиотеке НЕТ. Ни одного числа. Проверено сплошным поиском: числовых полей в протоколе не существует вообще.

7.2. Что при этом ЕСТЬ внутри самого агента (но до клиента не доходит)

Токены по каждому ходу: сколько отправлено, сколько получено. Хранятся вместе с ответом ассистента.
Сумма по диалогу: число ходов, всего отправлено, всего получено.
Предел контекста — агент его знает из своих настроек.
Порог сжатия — при заполнении агент сокращает историю (по умолчанию на 80 %).

То есть цифры существуют, но лежат в агенте и в протокол не выведены.

7.3. Что из этого следует для интерфейса

R24. В макете сейчас нарисованы три поля, которых в библиотеке нет: «модель», «отправлено в модель», «получено от модели». Это заглушки. Либо выкидываем, либо доводим агент так, чтобы он их отдавал.
R25. Показывать надо только то, что есть. Остальное либо честно помечаем как отсутствующее, либо не рисуем вовсе.
R26. Кольцо заполнения имеет смысл, когда агент начнёт отдавать два числа: занято сейчас и предел. Тогда видно долю. Что именно считать «занятым» (последний ход или вся история) — уточнить.
R27. Всё, что показываем по цифрам, должно быть сверено с исходниками до отрисовки. Правило: нет данных — нет цифры.

8. Ход работы агента

R28. Показывать не только ответы ассистента, но и происходящее вокруг них: вызовы инструментов, рассуждения, ошибки.
R29. Свёрнутый вид — одна строка: кратко, что происходит (например, «вызов инструмента: такой-то»).
R30. Развёрнутый вид — подробности шага: аргументы, результат, время.
R31. Сворачивание и разворачивание — по нажатию на строку.

9. Решения, которые ещё не приняты

Запись: по нажатию или на удержание.
Нужны ли вложения (картинки) в этом клиенте.
Как именно различать агентов (см. R21–R22).
Доводим ли агент, чтобы он отдавал цифры по токенам.
Как выглядит кольцо и где живёт.

10. Как проверяем

Проверка — живой прогон, а не «собралось». Правило пользователя: перед показом гонять сценарий руками; на экран смотреть, а не верить описанию.

11 KiB Raw Blame History