agentik-desktop/README.md

# agentik-desktop — дизайн десктопного клиента

Десктопный клиент агента **agentik** (Jetpack Compose Desktop). UI общается с агентом
через опубликованную библиотеку `pw.binom.agentik:client` — она даёт готовые
`Agent` / `Conversation`, живой поток событий и `interrupt()` для кнопки «Стоп».

Это пока **только дизайн**, не код приложения.

## Что где лежит

**`approved/` — принятое. Это решение, на него опираемся в реализации.**

```
approved/001-sidebar-utility.html            # ОСНОВА: привычный мессенджер
approved/005-new-chat-picker.html            # модалка «Новый диалог»
approved/README.md                           # что одобрено и когда
```

**`sketches/` — предложения. Не решение, а варианты и черновики.**

```
sketches/002-rail-voice-first/index.html     # голос — главное действие
sketches/003-three-pane-command/index.html   # три панели + состояние агента
sketches/004-settings-agents/index.html      # настройки агентов + проверка связи
sketches/005-new-chat-picker/index.html      # черновик модалки нового диалога
```

`BORROW-FROM-ASSISTENT.md` — что берём из `ai/assistent` (приёмы, плагины, версии),
а что не берём (архитектура, экраны, дизайн — своё).
`MIC-ASR-SEARCH.md` — библиотеки для микрофона и распознавания: своё готовое
(`mic-kmp`, `asr-kmp`, `vad-kmp`), вместо копирования кода из assistent.
`CACHE.md` — кэш сообщений на клиенте: что для него есть в библиотеке, схема
загрузки «только новое», где может порваться.
`THEMES.md` — цветовые темы: цвета не пишем в коде, берём из схемы. Тем будет
несколько, поэтому ни одного цвета числом.
`MARKDOWN-SOURCE.md` — откуда брать готовую отрисовку Markdown (файлы и адреса).
`REQUIREMENTS.md` — требования. Статус: накидываем, ни один пункт не обязателен
к исполнению в том виде, как записан.

## Одобренное

`approved/` — макеты, которые пользователь **принял**. Это решение, на него
опираемся в реализации. Отличие от `sketches/`: там предложения, здесь принятое.

- **`001-sidebar-utility.html`** — **основа дизайна**: привычный мессенджер,
  список диалогов + чат, папки («Все чаты / Работа / Дом»). Выбран как основа.
- **`005-new-chat-picker.html`** — модалка «Новый диалог» при нескольких
  ассистентах. Одобрена 2026-09-19. Пояснительной панели над окном в ней нет
  (в `sketches/005` была — это была заметка для проверки, не часть интерфейса).

**Правило:** одобренное живёт **только** в `approved/`. Если макет приняли —
он переезжает туда, а не остаётся «выбранным» среди вариантов.

## Что решено

- **Сначала десктоп, затем Android — по тем же лекалам.** Десктопный клиент
  делаем образцом: понятный, удобный и **читаемый по коду**. Когда получится —
  Android повторяет те же решения. Поэтому цель — максимально простой код,
  который пользователь открывает и понимает.
- **Основа — вариант 1** (`approved/001-sidebar-utility.html`). Остальные остаются рядом как
  источник идей.
- Стиль — тёмный, из уже принятой темы клиента assistent: фон `#121218`,
  панели `#17212B`, акцент `#6AB2F2`, текст `#EBEBEB`.
- **Тем будет несколько — цвета берём из цветовой схемы, не пишем числом в коде.**
  Имена по смыслу («фон», «панель», «акцент»), чтобы смена темы ничего не ломала.
  В макетах числа — это нормально. Разбор и список того, что забывают: `THEMES.md`.
- **Узкое окно** — на экране что-то одно: либо список диалогов, либо чат.
  Переключение кнопкой «Назад», как в Телеграме. Широкое — обе части сразу.
- **Подсказка о горячих клавишах** под полем ввода убрана.
- **Счётчиков токенов и кольца заполнения не будет.** В библиотеке `client`
  таких данных нет вообще: ни модели, ни отправлено/получено, ни предела
  контекста. Правило: нет данных — нет цифры.
- **Несколько агентов** — предусмотреть. Различение: **цвет или картинка** на выбор.
  Цвет помечает диалоги агента (полоска у строки, точка у группы); картинка
  показывается кружком вместо цвета. **Картинку клиент копирует себе**, а не берёт
  по исходному адресу — иначе значок пропадёт вместе с файлом.
- **Markdown** — показывать разметкой, а не сырыми символами. Готовый рендер
  лежит в репозитории `ai/assistent` — писать свой не надо, брать оттуда.
  Точные координаты файлов — в `MARKDOWN-SOURCE.md`.
- **Папки над списком диалогов** («Все чаты», «Работа», «Дом») — часть выбранного
  варианта 1, не терять их при доработках.
- **Проверка связи с агентом** — в отдельном окне поверх настроек: идёт → отвечает
  → не отвечает, с подробностями и подсказкой. Добавить агента можно только
  после успешной проверки.
- **Новый диалог** — при нескольких ассистентах спрашиваем, в каком создавать
  (диалог живёт внутри ассистента, отдельно его не создать). Один ассистент —
  окна нет, создаётся сразу. Ноль ассистентов — кнопки «＋» нет вообще.

## Заимствования: только приёмы, не архитектура

Из репозитория `ai/assistent` берём **приёмы отрисовки, плагины и версии**.
Архитектуру, слои, готовые экраны и окна — **не берём**: дизайн у нас свой,
нарисованный (см. `sketches/`). Разбор по пунктам — в `BORROW-FROM-ASSISTENT.md`,
там же таблица «берём / не берём».

## Как смотреть

Открыть в браузере любой из файлов — каждый самодостаточный, без сборки.
В четвёртом сверху переключатель состояний: список агентов, форма, проверка
связи (успех и ошибка), список диалогов с двумя агентами.

## Что предстоит решить

1. **Запись** — по нажатию (нажал — говоришь — нажал) или на удержание.
2. Форма показа хода работы агента в свёрнутом виде.
3. Различение агентов: одного цвета может оказаться мало.
4. Где хранится список агентов.
5. Нужны ли папки для диалогов, как в мобильном клиенте, или хватит поиска.
6. **Где хранится кэш сообщений** — файл или лёгкая база (см. `CACHE.md`).
7. **Что делать с куском прерванного ответа** в кэше — иначе схема даст сбой
   на первом же нажатии «Стоп» (`CACHE.md`, п. 3.2).

## Что сознательно не решается здесь

- **Откуда берётся распознавание речи.** Отдельная тема, к интерфейсу не
  относится: в дизайне показано только место кнопки и что происходит на экране
  во время записи. Кто именно превращает голос в текст — решается потом.
  Готовые библиотеки уже найдены, см. `MIC-ASR-SEARCH.md`.