474 lines
13 KiB
Markdown
474 lines
13 KiB
Markdown
# 08 — Agent-First Onboarding Specification (MicroDAO)
|
||
|
||
Цей документ описує нову модель онбордингу MicroDAO:
|
||
**користувач входить у чат з агентом-провідником, який крок за кроком створює спільноту, канал і налаштовує агента.**
|
||
|
||
Весь процес — діалоговий.
|
||
Усі API-виклики — ті самі, що в 03_api_core_snapshot.md.
|
||
|
||
---
|
||
|
||
## 1. Мета
|
||
|
||
Замінити класичні форми/кроки онбордингу повністю **агентським інтерфейсом**.
|
||
Увесь onboarding виконується через `AgentOnboardingChat`, який:
|
||
|
||
- говорить з користувачем живою мовою,
|
||
- ставить запитання,
|
||
- парсить відповіді,
|
||
- викликає API,
|
||
- підтверджує успішні кроки,
|
||
- веде користувача до створення першої microDAO,
|
||
- налаштовує приватного агента,
|
||
- завершує онбординг фразою та редіректом.
|
||
|
||
---
|
||
|
||
## 2. Загальна архітектура
|
||
|
||
Усі дії будуються на:
|
||
|
||
- **state-machine** (опис нижче),
|
||
- **Chat UI** (аналог звичайного чату),
|
||
- **репліках агента** (скрипт),
|
||
- **розпізнаванні наміру користувача** (regex / LLM / кнопки),
|
||
- **викликах API** (з 03_api_core_snapshot.md).
|
||
|
||
Компоненти:
|
||
|
||
```text
|
||
src/features/onboarding-agent/
|
||
AgentOnboardingChat.tsx
|
||
useOnboardingState.ts
|
||
scripts/
|
||
script.json
|
||
parser.ts
|
||
transitions.ts
|
||
```text
|
||
|
||
---
|
||
|
||
## 3. State Machine
|
||
|
||
```ts
|
||
type OnboardingStep =
|
||
| "greet"
|
||
| "ask_profile"
|
||
| "ask_team_name"
|
||
| "ask_team_desc"
|
||
| "ask_mode"
|
||
| "ask_channel_name"
|
||
| "ask_channel_type"
|
||
| "ask_agent_enable"
|
||
| "ask_agent_prefs"
|
||
| "ask_invites"
|
||
| "done";
|
||
```text
|
||
|
||
Перехід між кроками базується на:
|
||
|
||
- відповіді користувача,
|
||
- успішності API-виклику.
|
||
|
||
---
|
||
|
||
## 4. Повний сценарій діалогу (репліки агента)
|
||
|
||
Нижче — готовий сценарій, який можна покласти в JSON або хардкод.
|
||
|
||
## 4.1. greet
|
||
|
||
**Агент:**
|
||
|
||
> Привіт! Я — агент-провідник MicroDAO.
|
||
> Зараз ми разом створимо твою першу спільноту та особистого помічника.
|
||
> Як до тебе звертатися?
|
||
|
||
Після відповіді → `ask_profile`.
|
||
|
||
---
|
||
|
||
## 4.2. ask_profile
|
||
|
||
**Агент:**
|
||
|
||
> Приємно познайомитися, {name}.
|
||
> Якою мовою хочеш працювати — українською чи англійською?
|
||
|
||
Після відповіді — зберегти `locale` → `ask_team_name`.
|
||
|
||
---
|
||
|
||
## 4.3. ask_team_name
|
||
|
||
**Агент:**
|
||
|
||
> Як назвемо твою майбутню microDAO?
|
||
> Наприклад: "Креативна Майстерня", "AI-Команда Альфа", "Моя Спільнота".
|
||
|
||
Читаємо будь-який текст → `POST /teams` → `ask_team_desc`.
|
||
|
||
---
|
||
|
||
## 4.4. ask_team_desc
|
||
|
||
**Агент:**
|
||
|
||
> Класно. А як би ти описав спільноту одним реченням?
|
||
> (Не обов'язково, можеш написати "пропустити".)
|
||
|
||
Зберегти опис → `ask_mode`.
|
||
|
||
---
|
||
|
||
## 4.5. ask_mode
|
||
|
||
**Агент:**
|
||
|
||
> Обери режим для твоєї microDAO:
|
||
> **1)** Відкрита — є публічний канал, гості можуть читати.
|
||
> **2)** Приватна — тільки запрошені, чати зашифровані.
|
||
> Напиши `1` або `2`.
|
||
|
||
Після відповіді:
|
||
|
||
- map → `"public"` / `"confidential"`
|
||
- `PATCH /teams/{teamId}`
|
||
→ `ask_channel_name`.
|
||
|
||
---
|
||
|
||
## 4.6. ask_channel_name
|
||
|
||
**Агент:**
|
||
|
||
> Давай створимо перший канал.
|
||
> Як би ти хотів його назвати? (`general`, `core`, `support`)
|
||
|
||
Після відповіді → `ask_channel_type`.
|
||
|
||
---
|
||
|
||
## 4.7. ask_channel_type
|
||
|
||
**Агент:**
|
||
|
||
> Це буде публічний канал чи приватна кімната?
|
||
> Напиши: **public** або **private**.
|
||
|
||
Mapping:
|
||
|
||
- `public` → `type: "public"`
|
||
- `private` → `type: "group"`
|
||
|
||
API:
|
||
`POST /channels`
|
||
|
||
Після успіху → `ask_agent_enable`.
|
||
|
||
---
|
||
|
||
## 4.8. ask_agent_enable
|
||
|
||
**Агент:**
|
||
|
||
> У MicroDAO кожна спільнота має власного ШІ-агента, який памʼятає контекст і самонавчається.
|
||
> Хочеш одразу створити командного агента?
|
||
|
||
Очікувані відповіді: так / ні.
|
||
|
||
- Якщо «ні» → `ask_invites`
|
||
- Якщо «так» → `ask_agent_prefs`
|
||
|
||
---
|
||
|
||
## 4.9. ask_agent_prefs
|
||
|
||
**Агент:**
|
||
|
||
> Добре. Налаштуємо агента.
|
||
> Якою мовою він має відповідати?
|
||
|
||
Після відповіді →
|
||
|
||
**Агент:**
|
||
|
||
> Який у нього фокус?
|
||
> Вибери одне: **general**, **business**, **technical**, **creative**.
|
||
|
||
Після відповіді →
|
||
|
||
**Агент:**
|
||
|
||
> Що він має памʼятати?
|
||
>
|
||
> 1. Лише цей канал
|
||
> 2. Усі канали спільноти
|
||
|
||
Після відповіді:
|
||
|
||
Викликаємо:
|
||
`POST /agents`
|
||
|
||
Потім → `ask_invites`.
|
||
|
||
---
|
||
|
||
## 4.10. ask_invites
|
||
|
||
**Агент:**
|
||
|
||
> Все готово!
|
||
> Хочеш зараз запросити людей до своєї microDAO?
|
||
> Я підготую посилання, яке можна надіслати будь-кому.
|
||
|
||
Після відповіді — показати UI-елемент з інвайт-лінком.
|
||
|
||
→ `done`.
|
||
|
||
---
|
||
|
||
## 4.11. done
|
||
|
||
**Агент:**
|
||
|
||
> Вітаю!
|
||
> Твоя microDAO **{team.name}** створена.
|
||
> Я створив канал **#{channel.title}** і готовий допомагати.
|
||
> Можеш почати працювати або поставити мені питання:
|
||
> "Що ти вмієш?" / "Як користуватися каналами?" / "Як запросити команду?"
|
||
|
||
redirect → `/t/:teamId/c/:channelId`.
|
||
|
||
---
|
||
|
||
## 5. Intent Parser (як агент розуміє відповіді)
|
||
|
||
Мінімальний підхід (regex):
|
||
|
||
```ts
|
||
function parseMode(input: string) {
|
||
if (input.match(/1|пуб/i)) return "public";
|
||
if (input.match(/2|прив/i)) return "confidential";
|
||
}
|
||
```text
|
||
|
||
```ts
|
||
function parseYesNo(input: string) {
|
||
if (input.match(/^так|yes|y$/i)) return true;
|
||
if (input.match(/^ні|no|n$/i)) return false;
|
||
}
|
||
```text
|
||
|
||
Або гібридний:
|
||
|
||
- парсимо regex,
|
||
- якщо незрозуміло → питаємо LLM:
|
||
*"Чи відповідь користувача означає Так/Ні/Інше?"*
|
||
|
||
---
|
||
|
||
## 6. Компонент `AgentOnboardingChat.tsx`
|
||
|
||
### Мінімальна структура
|
||
|
||
```tsx
|
||
export function AgentOnboardingChat() {
|
||
const { step, setStep, state, updateState } = useOnboardingState();
|
||
|
||
const handleUserMessage = async (text: string) => {
|
||
addMessage({ author: "user", text });
|
||
|
||
switch (step) {
|
||
case "greet":
|
||
updateState({ name: text });
|
||
addAgent("Приємно познайомитися, " + text + "...");
|
||
setStep("ask_profile");
|
||
break;
|
||
|
||
case "ask_profile":
|
||
updateState({ locale: detectLocale(text) });
|
||
addAgent("Як назвемо твою microDAO?");
|
||
setStep("ask_team_name");
|
||
break;
|
||
|
||
case "ask_team_name":
|
||
const team = await api.post("/teams", { name: text });
|
||
updateState({ teamId: team.id });
|
||
addAgent("А як би ти описав спільноту?");
|
||
setStep("ask_team_desc");
|
||
break;
|
||
|
||
// ... і так далі для кожного step.
|
||
}
|
||
};
|
||
|
||
return (
|
||
<ChatUI
|
||
messages={messages}
|
||
onSend={handleUserMessage}
|
||
agentAvatar="guide"
|
||
/>
|
||
);
|
||
}
|
||
```text
|
||
|
||
---
|
||
|
||
## 7. Acceptance Criteria (як перевіряти)
|
||
|
||
- `/onboarding` відкривається як чат.
|
||
- Користувач спілкується з агентом.
|
||
- На кожному кроці агент відповідає правильно.
|
||
- Усі API виклики працюють:
|
||
|
||
- `/teams`
|
||
- `/teams/{id}`
|
||
- `/channels`
|
||
- `/agents`
|
||
- Після завершення → redirect.
|
||
- UX: користувач не бачить жодної форми. Все — діалог.
|
||
|
||
---
|
||
|
||
## 8. Для Cursor
|
||
|
||
Коли ти даси йому задачу, використовуй цей формат:
|
||
|
||
```text
|
||
You are a senior React/TS engineer.
|
||
|
||
Implement the Agent-first onboarding at `/onboarding` using the specification in:
|
||
- 08_agent_first_onboarding.md
|
||
- 03_api_core_snapshot.md
|
||
- 05_coding_standards.md
|
||
|
||
Create the component `AgentOnboardingChat.tsx` and supporting files.
|
||
|
||
Output:
|
||
- list of modified files
|
||
- diff
|
||
- summary
|
||
```text
|
||
|
||
---
|
||
|
||
## 9. Інтеграція з існуючим кодом
|
||
|
||
## 9.1. Заміна класичного онбордингу
|
||
|
||
Існуючий `OnboardingPage.tsx` можна:
|
||
- залишити як fallback для користувачів, які не хочуть агентський онбординг,
|
||
- або повністю замінити на `AgentOnboardingChat`.
|
||
|
||
## 9.2. Використання API клієнтів
|
||
|
||
Використовувати існуючі API клієнти з `src/api/`:
|
||
- `teams.ts` — для створення команди
|
||
- `channels.ts` — для створення каналу
|
||
- `agents.ts` — для створення агента
|
||
- `auth.ts` — для автентифікації
|
||
|
||
## 9.3. State Management
|
||
|
||
Використовувати `useOnboardingState` hook або розширити існуючий `useOnboarding.ts` для агентського онбордингу.
|
||
|
||
---
|
||
|
||
## 10. UI/UX Вимоги
|
||
|
||
## 10.1. Chat Interface
|
||
|
||
- Повідомлення агента з аватаром
|
||
- Повідомлення користувача справа
|
||
- Індикатор набору тексту (typing indicator) під час обробки
|
||
- Кнопки швидких відповідей (опціонально)
|
||
- Плавні анімації появи повідомлень
|
||
|
||
## 10.2. Візуальні елементи
|
||
|
||
- Аватар агента (іконка або зображення)
|
||
- Індикатор прогресу онбордингу (опціонально)
|
||
- Підказки для користувача
|
||
- Обробка помилок з дружніми повідомленнями
|
||
|
||
## 10.3. Мобільна адаптація
|
||
|
||
- Адаптивний дизайн для мобільних пристроїв
|
||
- Зручний ввід тексту на мобільних
|
||
- Оптимізація для маленьких екранів
|
||
|
||
---
|
||
|
||
## 11. Обробка помилок
|
||
|
||
## 11.1. Помилки API
|
||
|
||
Якщо API виклик не вдався:
|
||
- Показати дружнє повідомлення від агента
|
||
- Запропонувати спробувати ще раз
|
||
- Зберегти стан, щоб не втратити прогрес
|
||
|
||
## 11.2. Незрозумілі відповіді
|
||
|
||
Якщо агент не розуміє відповідь:
|
||
- Задати уточнююче питання
|
||
- Показати приклади правильних відповідей
|
||
- Запропонувати кнопки з варіантами
|
||
|
||
## 11.3. Таймаути
|
||
|
||
- Обробка повільних API викликів
|
||
- Показ індикатора завантаження
|
||
- Повідомлення про затримку
|
||
|
||
---
|
||
|
||
## 12. Тестування
|
||
|
||
## 12.1. Unit Tests
|
||
|
||
- Тести для `parser.ts` (розпізнавання намірів)
|
||
- Тести для `transitions.ts` (переходи між станами)
|
||
- Тести для компонента `AgentOnboardingChat`
|
||
|
||
## 12.2. Integration Tests
|
||
|
||
- Тестування повного flow онбордингу
|
||
- Тестування API інтеграції
|
||
- Тестування обробки помилок
|
||
|
||
## 12.3. E2E Tests
|
||
|
||
- Повний сценарій онбордингу від початку до кінця
|
||
- Різні варіанти відповідей користувача
|
||
- Перевірка редіректу після завершення
|
||
|
||
---
|
||
|
||
## 13. Майбутні покращення
|
||
|
||
## 13.1. LLM Integration
|
||
|
||
- Використання LLM для розпізнавання намірів
|
||
- Більш природна мова агента
|
||
- Контекстне розуміння відповідей
|
||
|
||
## 13.2. Персоналізація
|
||
|
||
- Адаптація мови агента під користувача
|
||
- Запам'ятовування попередніх відповідей
|
||
- Рекомендації на основі профілю
|
||
|
||
## 13.3. Мультимовність
|
||
|
||
- Підтримка багатьох мов
|
||
- Автоматичне визначення мови
|
||
- Перемикання мови під час онбордингу
|
||
|
||
---
|
||
|
||
**Готово.**
|
||
Це **повна специфікація агентського онбордингу**, готова до використання в Cursor.
|
||
|