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

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

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

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

1. Общее

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

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

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

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

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

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

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

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

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

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

R20. Предусмотреть возможность подключать несколько агентов и видеть их в одном клиенте. Не «много людей», а один клиент — несколько агентов.
R21. Возможный способ различения — по аватару: у каждого агента свой аватар, по нему и отличаем. Тема аватаров не продумана, это накидка.
R22. Другие возможные способы (на выбор, обсудить):
- Цветовой акцент — у каждого агента свой цвет: полоса у пузыря ответа, цвет имени в шапке;
- Группировка в списке — диалоги сгруппированы по агентам, с заголовком группы (как секции каналов);
- Переключатель агента — как выбор аккаунта в Телеграме: все диалоги одного агента разом;
- Метка в строке диалога — маленький значок/буква агента рядом с названием.
R23. У библиотеки уже есть всё для этого: агент создаётся вызовом с двумя значениями — имя и адрес. Имя клиент знает сам, сервер его не хранит. Каждому агенту — своё имя и адрес.
R23.1. Экран настроек агентов (sketches/004-settings-agents) — окно поверх чата, не отдельная страница. Два состояния: список агентов и форма нового.
R23.2. В строке агента видно: имя, адрес, состояние («на связи» / «не отвечает»), кнопки изменить и удалить.
R23.3. Форма нового агента: название, адрес сервера, и чем отличать в списке — цвет или картинка. Под каждым полем — пояснение простым языком.
R23.3.1. Переключатель «Цвет / Картинка»: выбирается что-то одно. Цвет — простой выбор из готовых, им помечаются диалоги агента в списке (полоска у строки, точка у группы). Картинка — файл с диска; показывается круглым превью, рядом «Выбрать файл…» и «Убрать».
R23.3.2. Картинку копировать себе, а не брать по исходному адресу. Выбранный файл сохраняется внутрь клиента (в свою папку), и дальше используется только эта копия. Ссылку на исходный путь не хранить: файл могут удалить, переименовать, флешку вынуть — и значок у агента пропадёт. Работает и для картинки на диске, и для картинки по ссылке: скачать и положить себе.
R23.3.3. Выбранная картинка показывается кружком там же, где был бы цвет: в списке агентов, в списке диалогов, в шапке чата. Убрать её можно в любой момент — тогда снова становится цвет.
R23.4. Проверка связи до сохранения — в отдельном окне поверх настроек, не строкой внутри формы. Нажал «Проверить связь» — открылось второе окно, в нём идёт проверка. Пока идёт: «спрашиваю агента…» с крутящимся значком. Результат — зелёный значок «отвечает» или красный «не отвечает», и под ним подробности: ответ на запрос, адрес, число диалогов, отклик в миллисекундах. Кнопка «Добавить агента» становится доступной только при успехе. Есть «Проверить снова». Закрытие окна возвращает к настройкам. Основа: агент отвечает на запрос состояния и отдаёт список диалогов; оба запроса ничего не меняют.
R23.5. Цвет агента работает не только в настройках: тем же цветом помечаются его диалоги в списке (полоска у строки, точка у группы).
R23.6. Список агентов сохраняется между запусками. Где именно — не решено.
R23.7. Доступа по паролю/ключу у библиотеки нет — поля для него не делать.

7. Состояние агента: что показывать

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

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

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

7.2. Решение: счётчиков токенов и кольца в интерфейсе НЕ будет

R24. Показывать израсходованные токены, долю от предела и кольцо заполнения не нужно. Данных для этого в библиотеке нет — значит и рисовать нечего. Кольцо из макета удалено.
R25. Никаких полей наугад: нет данных — нет цифры. Не подставлять правдоподобные числа вместо отсутствующих.
R26. Если когда-нибудь агент начнёт отдавать такие числа — вернёмся к вопросу. До тех пор тема закрыта.

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

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

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

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

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

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

14 KiB Raw Blame History