Требования: сверка с исходниками (токенов в client нет), несколько агентов, markdown

REQUIREMENTS.md

@@ -1,106 +1,138 @@
 # Требования к десктопному клиенту agentik
 
-**Статус:** накидываем. Это черновик — ни один пункт не является обязательным к
-исполнению в том виде, как записан. Позже пересматриваем.
+**Статус:** накидываем. Ни один пункт не обязателен к исполнению в том виде, как
+записан. Позже пересматриваем.
 
 **Основа дизайна:** вариант 1 (`sketches/001-sidebar-utility`) — выбран.
-Что в нём уже показано вживую: убрана подсказка под полем ввода, кольцо токенов
-с раскрытием, узкое окно с кнопкой «назад».
 
-**Сейчас описываем только поведение.** Кода нет и не пишем, пока требования не устоятся.
+**Сейчас описываем только поведение.** Кода не пишем, пока требования не устоятся.
 
 ---
 
 ## 1. Общее
 
-- **R1.** Клиент — только для одного ассистента, не для переписки с людьми.
-  Никаких «пользователей», «контактов», «групп» — их нет и не должно быть.
-- **R2.** Стиль — тёмная тема, уже принятая в клиентах пользователя
+- **R1.** Стиль — тёмная тема, уже принятая в клиентах пользователя
   (фон `#121218`, панели `#17212B`, текст `#EBEBEB`).
-- **R3.** Что видно на экране в любой момент: список диалогов, выбранный диалог
+- **R2.** Что видно на экране в любой момент: список диалогов, выбранный диалог
   и поле ввода. Больше ничего обязательного нет.
 
 ## 2. Раскладка и адаптивность
 
-- **R4.** **Широкое окно** — две части: список диалогов слева, открытый диалог справа.
-- **R5.** **Узкое окно** — на экране что-то одно: либо список диалогов, либо
+- **R3.** **Широкое окно** — две части: список диалогов слева, открытый диалог справа.
+- **R4.** **Узкое окно** — на экране что-то одно: либо список диалогов, либо
   конкретный диалог. Переключение — как в Телеграме.
-- **R6.** В узком окне у открытого диалога сверху слева — кнопка «Назад».
+- **R5.** В узком окне у открытого диалога сверху слева — кнопка «Назад».
   Нажатие возвращает к списку диалогов на всю ширину.
-- **R7.** Порог «широкое/узкое» — по ширине окна, одна величина. Какой именно
+- **R6.** Порог «широкое/узкое» — по ширине окна, одна величина. Какой именно
   размер считать порогом — решим позже.
 
 ## 3. Список диалогов
 
-- **R8.** Список диалогов — это список бесед с одним и тем же ассистентом,
-  различающихся темой (задача, контекст, история).
-- **R9.** Группировка диалогов остаётся: «Работа», «Дом» и подобное. Подпись и
-  состав групп — настраиваемые.
-- **R10.** В строке диалога: название, последнее сообщение, время, счётчик
+- **R7.** Группировка диалогов со временем появится — «Работа», «Дом» и подобное.
+  Сейчас это накидка, состав групп ещё не определён.
+- **R8.** В строке диалога: название, последнее сообщение, время, счётчик
   непрочитанных.
-- **R11.** Есть поиск по диалогам.
+- **R9.** Есть поиск по диалогам.
 
 ## 4. Открытый диалог
 
-- **R12.** Показ сообщений: мои и ассистента, с временем.
-- **R13.** Ответ ассистента можно прервать — на видном месте кнопка «Стоп».
-- **R14.** Сообщения приходят вживую, по мере генерации (текст дотекает).
+- **R10.** Показ сообщений: мои и ассистента, с временем.
+- **R11.** Ответ ассистента можно прервать — на видном месте кнопка «Стоп».
+- **R12.** Сообщения приходят вживую, по мере генерации: текст дотекает куском
+  за куском, а не появляется целиком в конце. Отображать именно так.
+- **R13.** **Разметка (markdown).** Если я или агент пишем текст, похожий на
+  разметку, показывать его разметкой, а не сырыми символами: списки, выделение,
+  код, таблицы, ссылки. Код для этого писать не надо — готовая библиотека уже
+  используется в клиенте assistent.
 
 ## 5. Панель ввода
 
-- **R15.** Поле ввода, кнопка «Отправить» и **отдельная кнопка записи микрофона**.
-- **R16.** Подсказка о горячих клавишах под полем **убирается** — её не должно быть.
-  (Убрать «Ctrl+R — запись · Enter — отправить · Shift+Enter — новая строка».)
-- **R17.** Пока идёт запись, ввод текста не должен вводить в заблуждение:
-  должно быть понятно, что сейчас пишется голос.
-- **R18.** Отмена записи — явная.
+- **R14.** Поле ввода, кнопка «Отправить» и **отдельная кнопка записи микрофона**.
+- **R15.** Подсказка о горячих клавишах под полем **убирается** — её не должно быть.
+- **R16.** Пока идёт запись, должно быть понятно, что сейчас пишется голос.
+- **R17.** Отмена записи — явная.
+- **R18.** Голос: кнопка включает микрофон и останавливает его. Точная механика
+  (по нажатию или на удержание) — решим позже.
+- **R19.** Распознавание речи — **отдельная тема, здесь не решается.** Важно только:
+  где кнопка, что видно во время записи, что происходит после.
 
-## 6. Голос
+## 6. Несколько агентов
 
-- **R19.** Кнопка записи включает микрофон и останавливает его. Точная механика
-  (по нажатию или на удержание) — см. раздел 10.
-- **R20.** Распознавание речи — **отдельная тема, здесь не решается.** В интерфейсе
-  важно только: где кнопка, что видно во время записи, что происходит после.
+- **R20.** Предусмотреть возможность подключать **несколько агентов** и видеть их
+  в одном клиенте. Не «много людей», а один клиент — несколько агентов.
+- **R21.** Возможный способ различения — **по аватару**: у каждого агента свой
+  аватар, по нему и отличаем. Тема аватаров не продумана, это накидка.
+- **R22.** Другие возможные способы (на выбор, обсудить):
+  - **Цветовой акцент** — у каждого агента свой цвет: полоса у пузыря ответа,
+    цвет имени в шапке;
+  - **Группировка в списке** — диалоги сгруппированы по агентам, с заголовком
+    группы (как секции каналов);
+  - **Переключатель агента** — как выбор аккаунта в Телеграме: все диалоги
+    одного агента разом;
+  - **Метка в строке диалога** — маленький значок/буква агента рядом с названием.
+- **R23.** У библиотеки уже есть всё для этого: агент создаётся вызовом с двумя
+  значениями — имя и адрес. Имя клиент знает сам, сервер его не хранит. Каждому
+  агенту — своё имя и адрес.
 
-## 7. Состояние агента
+## 7. Состояние агента: сколько израсходовано
 
-- **R21.** Показывать, **сколько токенов израсходовано** за диалог целиком.
-- **R22.** Показывать, **сколько занято сейчас** и **сколько всего доступно**.
-- **R23.** Показывать это **кольцом заполнения** — как сильно заполнено.
-- **R24.** По умолчанию состояние **свёрнуто**; по нажатию — разворачивается
-  с подробностями.
-- **R25.** Место и точный вид — решим позже.
+Здесь свериться с исходниками оказалось важнее всего. Ниже — **по факту из кода**,
+не по догадкам.
+
+### 7.1. Что есть в самой библиотеке `client` (что клиент реально получает)
+
+- **У каждого события и каждого сообщения есть дата.** Значит доступно: длительность
+  хода, сколько времени агент думал, когда пришёл ответ.
+- **Есть события:** начало ответа, рассуждение, текст по мере генерации, картинка,
+  вызов инструмента (имя, аргументы, заголовок), результат инструмента, конец хода,
+  прерывание, ошибка.
+- **Есть события о диалогах:** создан, удалён, переименован.
+- **По диалогу:** название, время последнего изменения, умеет ли принимать и отдавать
+  картинки, временный он или постоянный.
+- **Токенов, модели, цены, предела контекста — в библиотеке НЕТ.** Ни одного числа.
+  Проверено сплошным поиском: числовых полей в протоколе не существует вообще.
+
+### 7.2. Что при этом ЕСТЬ внутри самого агента (но до клиента не доходит)
+
+- **Токены по каждому ходу**: сколько отправлено, сколько получено. Хранятся
+  вместе с ответом ассистента.
+- **Сумма по диалогу**: число ходов, всего отправлено, всего получено.
+- **Предел контекста** — агент его знает из своих настроек.
+- **Порог сжатия** — при заполнении агент сокращает историю (по умолчанию на 80 %).
+
+То есть цифры существуют, но лежат в агенте и в протокол не выведены.
+
+### 7.3. Что из этого следует для интерфейса
+
+- **R24.** В макете сейчас нарисованы три поля, которых в библиотеке нет:
+  «модель», «отправлено в модель», «получено от модели». Это заглушки. Либо
+  выкидываем, либо доводим агент так, чтобы он их отдавал.
+- **R25.** Показывать надо **только то, что есть**. Остальное либо честно помечаем
+  как отсутствующее, либо не рисуем вовсе.
+- **R26.** Кольцо заполнения имеет смысл, когда агент начнёт отдавать два числа:
+  занято сейчас и предел. Тогда видно долю. Что именно считать «занятым»
+  (последний ход или вся история) — уточнить.
+- **R27.** Всё, что показываем по цифрам, должно быть сверено с исходниками
+  **до** отрисовки. Правило: нет данных — нет цифры.
 
 ## 8. Ход работы агента
 
-- **R26.** Показывать не только ответы ассистента, но и происходящее вокруг них:
+- **R28.** Показывать не только ответы ассистента, но и происходящее вокруг них:
   вызовы инструментов, рассуждения, ошибки.
-- **R27.** Свёрнутый вид — одна строка: кратко, что происходит
+- **R29.** Свёрнутый вид — одна строка: кратко, что происходит
   (например, «вызов инструмента: такой-то»).
-- **R28.** Развёрнутый вид — подробности этого шага: аргументы, результат, время.
-- **R29.** Сворачивание/разворачивание — по нажатию на строку.
-- **R30.** Что именно показывать в строке — решим позже.
+- **R30.** Развёрнутый вид — подробности шага: аргументы, результат, время.
+- **R31.** Сворачивание и разворачивание — по нажатию на строку.
 
-## 9. Отдельным списком: чего в библиотеке agentik СЕЙЧАС нет
+## 9. Решения, которые ещё не приняты
 
-Проверено по коду `pw.binom.agentik:client` (версия 3):
-
-- **Токенов нет вообще.** Ни в сообщениях, ни в событиях, ни в диалоге. То есть
-  R21–R23 сейчас не из чего взять — потребуется доработка на стороне агента
-  и протокола. Это не задача дизайна, но без неё кольцо нарисовать нечем.
-- **Есть события** (их и показываем в R26–R30): начало ответа, рассуждение,
-  текст по мере генерации, картинка, вызов инструмента, результат инструмента,
-  конец хода, прерывание, ошибка.
-- **Есть события о диалогах целиком:** создан, удалён, переименован.
-- **Есть:** прерывание ответа, история сообщений, список диалогов.
-
-## 10. Решения, которые ещё не приняты
-
-- Запись: по нажатию (нажал — говоришь — нажал) или на удержание.
+- Запись: по нажатию или на удержание.
 - Нужны ли вложения (картинки) в этом клиенте.
-- Как именно выглядит кольцо токенов и где живёт.
+- Как именно различать агентов (см. R21–R22).
+- Доводим ли агент, чтобы он отдавал цифры по токенам.
+- Как выглядит кольцо и где живёт.
 
-## 11. Как проверяем
+## 10. Как проверяем
 
 Проверка — **живой прогон**, а не «собралось». Правило пользователя: перед показом
-гонять сценарий руками. Сценарии по этим требованиям будут отдельно.
+гонять сценарий руками; на экран смотреть, а не верить описанию.