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
474
docs/cursor/08_agent_first_onboarding.md
Normal file
474
docs/cursor/08_agent_first_onboarding.md
Normal file
@@ -0,0 +1,474 @@
|
||||
# 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).
|
||||
|
||||
Компоненти:
|
||||
|
||||
```
|
||||
src/features/onboarding-agent/
|
||||
AgentOnboardingChat.tsx
|
||||
useOnboardingState.ts
|
||||
scripts/
|
||||
script.json
|
||||
parser.ts
|
||||
transitions.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 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";
|
||||
```
|
||||
|
||||
Перехід між кроками базується на:
|
||||
|
||||
* відповіді користувача,
|
||||
* успішності 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";
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
function parseYesNo(input: string) {
|
||||
if (input.match(/^так|yes|y$/i)) return true;
|
||||
if (input.match(/^ні|no|n$/i)) return false;
|
||||
}
|
||||
```
|
||||
|
||||
Або гібридний:
|
||||
|
||||
* парсимо 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"
|
||||
/>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 7. Acceptance Criteria (як перевіряти)
|
||||
|
||||
* `/onboarding` відкривається як чат.
|
||||
* Користувач спілкується з агентом.
|
||||
* На кожному кроці агент відповідає правильно.
|
||||
* Усі API виклики працюють:
|
||||
|
||||
* `/teams`
|
||||
* `/teams/{id}`
|
||||
* `/channels`
|
||||
* `/agents`
|
||||
* Після завершення → redirect.
|
||||
* UX: користувач не бачить жодної форми. Все — діалог.
|
||||
|
||||
---
|
||||
|
||||
# 8. Для Cursor
|
||||
|
||||
Коли ти даси йому задачу, використовуй цей формат:
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user