diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index a02dc19..829424d 100644 --- a/REQUIREMENTS.md +++ b/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. Как проверяем Проверка — **живой прогон**, а не «собралось». Правило пользователя: перед показом -гонять сценарий руками. Сценарии по этим требованиям будут отдельно. +гонять сценарий руками; на экран смотреть, а не верить описанию.