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                      |

Функції:

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

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

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

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

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

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

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

Способи:

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

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

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

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

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

• інший фон,

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

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

---

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

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

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

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

---

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 приклад:

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

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

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

---

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

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

---

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

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

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

12.2. Сторінки

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

12.3. Hooks

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

12.4. Типи

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

---

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

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

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

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

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

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

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

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

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

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

---

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

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

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

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

GET /agents/{agentId}/memory

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

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

---

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.