# Требования к десктопному клиенту 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. Как проверяем

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