microdao-daarion/docs/cursor/10_agent_ui_system.md

10 — Agent UI System (MicroDAO)

Повна специфікація агентського інтерфейсу

Цей документ описує, як агент стає першим інтерфейсом взаємодії в MicroDAO.
Уся взаємодія — чатова.
Агент — навігатор, помічник, аналітик та еволюційна сутність.

---

1. Мета

Зробити агента центральною точкою взаємодії користувача зі спільнотою.

У результаті:

• новачок спілкується з агентом для створення microDAO;

• учасник команди — взаємодіє з агентом через командний чат;

• агент сам ініціює корисні дії;

• агент має власний чат, власну панель еволюції і власну пам'ять;

• агент виконує функції внутрішнього інтелекту команди.

---

2. Типи агентів у UI

2.1. Guide Agent (провідник)

Працює в онбордингу.

Показує:

• підказки,

• кроки,

• питання,

• підтверджує створення команд/каналів.

2.2. Team Assistant (внутрішній агент)

Доступний всередині кожної microDAO.

Основні функції:

• відповіді у спільних чатах,

• автоматичні підсумки,

• створення follow-ups,

• пропозиції задач,

• аналіз документації,

• self-improvement.

2.3. Personal Agent (опція 2025+)

Асистент конкретного користувача.

---

3. Компоненти Agent UI

3.1. Agent Bubble

Маленький фіксований аватар агента у нижньому правому куті (як у Copilot / ChatGPT):

• натискаєш → відкривається Agent Chat;

• агент може блиматиме (notifying) при певних подіях.

3.2. Agent Chat Window

Окремий чат у форматі інтерфейсу:

---
| Team Assistant (ім'я агента)      |
|   Chat messages                    |
|   Input field                      |
```text

Функції:

- ставити питання агенту;

- отримувати аналіз;

- генерувати документи (MVP — текст);

- зворотній зв'язок 👍/👎;

- self-review автозапуск.

## 3.3. Inline Agent Messages у каналах

Агент може писати в каналі:

Способи:

- коли його тегнули: @assistant

- коли користувач попросив: "Підсумуй останнє"

- коли канал просить допомогу (опційно)

- коли тригери (як у Slack bots)

Повідомлення агента виглядають так:

- інший фон,

- аватар агента,

- дрібний значок "AI".

---

## 4. Sidebar інтеграція

У лівому меню зʼявляється новий розділ:

```text
Агенти
• Team Assistant
• (у майбутньому: Personal Agent)
```text

При натисканні → сторінка агента.

---

## 5. Сторінка агента

### Розташування

`/t/:teamId/agent/:agentId`

Складається з 4 вкладок:

## 5.1. "Чат"

Центральне місце взаємодії з агентом.

Вигляд: стандартний чат + тред з агентом.

## 5.2. "Памʼять"

Показує:

- довгострокові факти,

- короткострокові факти,

- терміни,

- ключові меседжі.

Кнопки:

- «Очистити коротку»

- «Очистити довгострокову»

- «Експорт памʼяті»

## 5.3. "Самонавчання"

(інтегровано з документом 09)

Поля:

- toggle: self-improvement ON/OFF

- рівень: basic / extended

- джерела: канал / вся microDAO / DAGI

- статус останнього review:

  - дата

  - кількість знайдених помилок

  - кількість пропозицій

Кнопка:

- «Запустити self-review зараз»

## 5.4. "Еволюція"

Показує:

- список пропозицій,

- версії агента,

- детальні diffs,

- кнопки accept/reject/edit.

UI приклад:

```text
Версія: v4.2
Запропоновано 2 покращення:

[1] Нове правило: "Відповідати українською, якщо канал український."  [Прийняти] [Відхилити]

[2] FAQ: "Як додати учасника до команди?"  [Прийняти] [Редагувати]
```text

---

## 6. Взаємодія агента з подіями

## 6.1. У каналі

Тригери для агента:

- `@assistant` — пряме звернення.  

- Фрази:  

  - "Підсумуй будь ласка"  

  - "Що сталося?"  

  - "Створи таску з цього"  

  - "Які наступні кроки?"  

- Коли новий учасник приєднався:

  - агент робить welcome-репліку.

---

## 7. Взаємодія агента з Follow-Ups & Projects

### 7.1. Follow-ups

Агент може:

- створювати follow-up автоматично,

- пропонувати: "Хочеш я створю задачу з цього?",

- групувати follow-ups.

### 7.2. Projects

Агент може:

- пропонувати задачі,

- заповнювати опис задач,

- будувати мінімальні roadmaps,

- робити автоматичні щоденні підсумки по проєкту (summary).

---

## 8. Notification Logic

Агент sparingly надсилає нотифікації:

Типи:

- завершений self-review,

- знайдені проблеми,

- нові пропозиції змін,

- нагадування про follow-ups,

- важливі зміни у спільноті.

UI:

- Badge на іконці агента,

- "пульсація" Agent Bubble,

- push (на майбутнє).

---

## 9. Анімації та UX-поведінка

- Аватар агента реагує на події (мʼяка анімована "пульсація").

- У чаті агент не відповідає миттєво (0.3–0.7s delay).

- Пише «…друкую» (typing indicator).

- Помилки агента обробляються як звичайні системні помилки.

---

## 10. Інтеграція з Agent-First Onboarding

Після онбордингу:

- той самий агент-провідник стає Team Assistant

- або передає користувача "головному" агенту команди

Після завершення онбордингу агент каже:

> "Якщо хочеш, я можу показати тобі, як працює ваша молоденька microDAO."

---

## 11. Завдання для Cursor

```text
You are a senior React/TS engineer.

Implement Agent UI System using:

- 10_agent_ui_system.md
- 08_agent_first_onboarding.md
- 03_api_core_snapshot.md
- 05_coding_standards.md

Deliverables:

1. AgentBubble component
2. AgentChatWindow component
3. Agent page with tabs: Chat / Memory / Learning / Evolution
4. Inline agent messages in channels
5. Hook: useAgentActions()

Output:

- list of modified files
- diff
- summary
```text

---

## 12. Компоненти та структура файлів

## 12.1. Компоненти UI

```text
src/components/agent/
  AgentBubble.tsx           # Фіксований аватар у правому нижньому куті
  AgentChatWindow.tsx       # Окно чату з агентом
  AgentMessage.tsx          # Повідомлення агента в каналах
  AgentAvatar.tsx           # Аватар агента з анімаціями
  AgentTypingIndicator.tsx  # Індикатор набору тексту
```text

## 12.2. Сторінки

```text
src/pages/
  AgentPage.tsx             # Головна сторінка агента з вкладками
  AgentChatTab.tsx          # Вкладка чату
  AgentMemoryTab.tsx        # Вкладка пам'яті
  AgentLearningTab.tsx      # Вкладка самонавчання
  AgentEvolutionTab.tsx     # Вкладка еволюції
```text

## 12.3. Hooks

```text
src/hooks/
  useAgentActions.ts        # Дії агента (відповіді, аналіз)
  useAgentNotifications.ts # Нотифікації від агента
  useAgentMemory.ts         # Робота з пам'яттю агента
  useAgentEvolution.ts     # Еволюція агента (з 09_evolutionary_agent.md)
```text

## 12.4. Типи

```text
src/types/
  agent.ts                  # Типи для агентів
    - Agent
    - AgentMessage
    - AgentSuggestion
    - AgentVersion
    - AgentMemory
```text

---

## 13. Інтеграція з каналами

## 13.1. Відображення повідомлень агента

Повідомлення агента в каналі мають:

- Спеціальний фон (наприклад, світло-синій)
- Аватар агента з іконкою AI
- Індикатор "AI" біля імені
- Кнопки фідбеку 👍/👎 (опціонально)

## 13.2. Тригери для агента

Система розпізнає наступні тригери:

- `@assistant` або `@agent` — пряме звернення
- Фрази-команди:
  - "Підсумуй"
  - "Створи задачу"
  - "Що сталося?"
  - "Які наступні кроки?"
  - "Допоможи з..."

## 13.3. Автоматичні дії

Агент може автоматично:

- Привітати нового учасника
- Підсумувати довгі обговорення
- Запропонувати створити задачу з важливого повідомлення
- Нагадати про дедлайни

---

## 14. API інтеграція

## 14.1. Отримання відповіді від агента

```ts
POST /agents/{agentId}/chat
{
  "message": "Підсумуй останні повідомлення",
  "context": {
    "channelId": "channel-123",
    "threadId": "thread-456"
  }
}
```text

## 14.2. Отримання пам'яті агента

```ts
GET /agents/{agentId}/memory
```text

## 14.3. Оновлення налаштувань самонавчання

```ts
PATCH /agents/{agentId}/learning
{
  "enabled": true,
  "level": "extended",
  "sources": ["channel", "team"]
}
```text

---

## 15. UX деталі

## 15.1. Agent Bubble

- Розмір: 56x56px
- Позиція: fixed, bottom-right, 24px від країв
- Z-index: 1000
- Анімація: м'яка пульсація при нових нотифікаціях
- Badge: червоний кружечок з кількістю нових подій

## 15.2. Agent Chat Window

- Розмір: 400x600px (desktop), fullscreen (mobile)
- Позиція: fixed, bottom-right, над Agent Bubble
- Анімація відкриття: slide-up з fade
- Закриття: кнопка X або клік поза вікном

## 15.3. Typing Indicator

- Показується під час генерації відповіді
- Анімація: три точки, що пульсують
- Текст: "Агент друкує..."

---

## 16. Обробка помилок

## 16.1. Помилки API

Якщо агент не може відповісти:

- Показати дружнє повідомлення: "Вибач, зараз не можу відповісти. Спробуй пізніше."
- Запропонувати альтернативу
- Логувати помилку для аналізу

## 16.2. Таймаути

Якщо відповідь занадто довга:

- Показати індикатор завантаження
- Запропонувати скасувати
- Після 30 секунд — показати попередження

---

## 17. Тестування

## 17.1. Unit Tests

- Тести для `AgentBubble`
- Тести для `AgentChatWindow`
- Тести для `useAgentActions`
- Тести для розпізнавання тригерів

## 17.2. Integration Tests

- Тестування повного flow: питання → відповідь → фідбек
- Тестування інтеграції з каналами
- Тестування нотифікацій

## 17.3. E2E Tests

- Користувач відкриває Agent Chat → ставить питання → отримує відповідь
- Користувач тегує агента в каналі → агент відповідає
- Користувач приймає пропозицію еволюції → агент оновлюється

---

## 18. Результат

MicroDAO стає не месенджером з агентами, а **агентською операційною системою спільнот**, де ШІ — активний навігатор, який еволюціонує та живе поруч з людьми.

Агент:

- є першим інтерфейсом для нових користувачів,
- допомагає у щоденній роботі команди,
- еволюціонує разом зі спільнотою,
- залишається під повним контролем користувачів,
- інтегрується з усіма функціями MicroDAO.

---

**Готово.**  
Це **повна специфікація агентського UI системи**, готова до використання в Cursor.