chore: organize documentation structure for monorepo
- Create /docs structure (microdao, daarion, agents) - Organize 61 cursor technical docs - Add README files for each category - Copy key documents to public categories - Add GitHub setup instructions and scripts
This commit is contained in:
Apple
555
docs/cursor/10_agent_ui_system.md
Normal file
555
docs/cursor/10_agent_ui_system.md
Normal file
@@ -0,0 +1,555 @@
|
||||
# 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. Отримання відповіді від агента
|
||||
|
||||
```ts
|
||||
POST /agents/{agentId}/chat
|
||||
{
|
||||
"message": "Підсумуй останні повідомлення",
|
||||
"context": {
|
||||
"channelId": "channel-123",
|
||||
"threadId": "thread-456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 14.2. Отримання пам'яті агента
|
||||
|
||||
```ts
|
||||
GET /agents/{agentId}/memory
|
||||
```
|
||||
|
||||
## 14.3. Оновлення налаштувань самонавчання
|
||||
|
||||
```ts
|
||||
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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user