555 lines
14 KiB
Markdown
555 lines
14 KiB
Markdown
# 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
|
||
|
||
Окремий чат у форматі інтерфейсу:
|
||
|
||
```text
|
||
---
|
||
| 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.
|
||
|