agentik-desktop/REQUIREMENTS.md

# Требования к десктопному клиенту 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).** Если я или агент пишем текст, похожий на
  разметку, показывать его разметкой, а не сырыми символами: списки, выделение,
  код, таблицы, ссылки. Код для этого писать не надо — готовый рендер уже есть
  в репозитории `ai/assistent`, брать оттуда.
- **R13.1.** **Откуда брать — точно.** См. `MARKDOWN-SOURCE.md`: репозиторий
  `ai/assistent`, ветка `main`, коммит `2c5b3f9`. Копировать 4 файла:
  модель разметки, парсер, отрисовку и десктопную обёртку открытия ссылок.
  Одна внешняя зависимость — `ru.otpbank.ai:markdown:0.51.0` (есть в Nexus).

## 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. Как проверяем

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