feat: Add presence heartbeat for Matrix online status
- matrix-gateway: POST /internal/matrix/presence/online endpoint - usePresenceHeartbeat hook with activity tracking - Auto away after 5 min inactivity - Offline on page close/visibility change - Integrated in MatrixChatRoom component
This commit is contained in:
Apple
463
docs/greenfood/greenfood_agents.md
Normal file
463
docs/greenfood/greenfood_agents.md
Normal file
@@ -0,0 +1,463 @@
|
||||
# GREENFOOD Crew - Документація
|
||||
|
||||
**Версія**: 1.0.0
|
||||
**Дата**: 2025-11-18
|
||||
**Статус**: Ready for Development
|
||||
|
||||
---
|
||||
|
||||
## Огляд
|
||||
|
||||
GREENFOOD Crew — це команда з 13 спеціалізованих AI-агентів для управління ERP-системою крафтових виробників продуктів харчування. Система забезпечує повний цикл від onboarding виробника до доставки товару покупцю та фінансових розрахунків.
|
||||
|
||||
---
|
||||
|
||||
## Архітектура
|
||||
|
||||
### Головний оркестратор
|
||||
|
||||
**GREENFOOD Assistant** — єдина точка входу для всіх користувачів системи. Розпізнає роль користувача, виявляє намір та делегує завдання відповідним доменним агентам.
|
||||
|
||||
### 12 доменних агентів
|
||||
|
||||
Агенти організовані за функціональними доменами:
|
||||
|
||||
#### 🏭 Операційні агенти (Operations)
|
||||
1. **Product & Catalog Agent** - Каталог товарів
|
||||
2. **Batch & Quality Agent** - Партії та контроль якості
|
||||
3. **Warehouse Agent** - Управління складами
|
||||
4. **Logistics & Delivery Agent** - Логістика та доставка
|
||||
|
||||
#### 💼 Продажі та підтримка (Sales & Support)
|
||||
5. **Seller Agent** - Менеджер з продажу
|
||||
6. **Customer Care Agent** - Служба підтримки
|
||||
|
||||
#### 💰 Фінанси (Finance)
|
||||
7. **Finance & Pricing Agent** - Бухгалтерія та ціноутворення
|
||||
|
||||
#### 📢 Маркетинг (Marketing)
|
||||
8. **SMM & Campaigns Agent** - Соціальні мережі та кампанії
|
||||
9. **SEO & Web Experience Agent** - SEO та веб-досвід
|
||||
|
||||
#### 📊 Аналітика та governance (Analytics & Governance)
|
||||
10. **Analytics & BI Agent** - Аналітика даних
|
||||
11. **Compliance & Audit Agent** - Аудит та compliance
|
||||
|
||||
#### 🚀 Успіх клієнтів (Success)
|
||||
12. **Vendor Success Agent** - Менеджер успіху комітентів
|
||||
|
||||
---
|
||||
|
||||
## Ролі та відповідальність агентів
|
||||
|
||||
### 1. GREENFOOD Assistant
|
||||
**Роль**: Фронтовий оркестратор
|
||||
**Мета**: Розуміти користувача, виявляти намір, делегувати завдання
|
||||
**Ключові функції**:
|
||||
- Ідентифікація ролі користувача (комітент, складський, логіст, бухгалтер, маркетолог, покупець)
|
||||
- Перетворення запиту на чітку дію
|
||||
- Координація роботи доменних агентів
|
||||
- Формування зрозумілих результатів для користувача
|
||||
|
||||
**Делегування**: Так (може делегувати іншим агентам)
|
||||
|
||||
---
|
||||
|
||||
### 2. Product & Catalog Agent
|
||||
**Роль**: Менеджер каталогу товарів
|
||||
**Мета**: Підтримувати чистий, структурований каталог без дублів
|
||||
**Ключові функції**:
|
||||
- Створення та редагування карточок товарів
|
||||
- Перевірка дублікатів
|
||||
- Управління атрибутами (вага, склад, алергени, строк придатності)
|
||||
- Управління медіа (фото, відео)
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- ProductCatalogAPI
|
||||
- ImageUploadTool
|
||||
- DuplicateDetectorTool
|
||||
|
||||
---
|
||||
|
||||
### 3. Batch & Quality Agent
|
||||
**Роль**: Менеджер партій та якості
|
||||
**Мета**: Забезпечити трасованість партій та контроль якості
|
||||
**Ключові функції**:
|
||||
- Створення та відстеження партій товарів
|
||||
- Контроль строків придатності
|
||||
- Управління статусами партій (на складі, в дорозі, реалізована, прострочена)
|
||||
- Фіксація інцидентів якості та рекламацій
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- BatchTrackingAPI
|
||||
- QualityCheckTool
|
||||
- ExpiryAlertTool
|
||||
|
||||
---
|
||||
|
||||
### 4. Vendor Success Agent
|
||||
**Роль**: Менеджер успіху комітентів
|
||||
**Мета**: Швидкий запуск та зростання виробників
|
||||
**Ключові функції**:
|
||||
- Onboarding нових комітентів (чеклісти, документи)
|
||||
- Виявлення слабких місць (порожній каталог, відсутні фото)
|
||||
- Проактивні рекомендації для покращення
|
||||
- Моніторинг метрик успіху
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- VendorOnboardingAPI
|
||||
- ChecklistTool
|
||||
- RecommendationEngine
|
||||
|
||||
---
|
||||
|
||||
### 5. Warehouse Agent
|
||||
**Роль**: Начальник складу
|
||||
**Мета**: Коректні та актуальні залишки товарів
|
||||
**Ключові функції**:
|
||||
- Управління залишками товарів
|
||||
- Фіксація руху товарів (прихід, переміщення, відвантаження)
|
||||
- Структурування складу (зони, стелажі, температурні зони)
|
||||
- Сигналізація про критичні залишки
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- WarehouseAPI
|
||||
- InventoryTool
|
||||
- StockMovementTool
|
||||
- ZoneManagementTool
|
||||
|
||||
---
|
||||
|
||||
### 6. Logistics & Delivery Agent
|
||||
**Роль**: Логіст і диспетчер
|
||||
**Мета**: Мінімальні затримки та витрати на доставку
|
||||
**Ключові функції**:
|
||||
- Створення маршрутів доставки
|
||||
- Управління статусами доставок
|
||||
- Інтеграція з перевізниками (API)
|
||||
- Формування трек-номерів
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- LogisticsAPI
|
||||
- DeliveryTrackerTool
|
||||
- CourierIntegrationTool
|
||||
|
||||
---
|
||||
|
||||
### 7. Seller Agent
|
||||
**Роль**: Менеджер з продажу
|
||||
**Мета**: Допомога в оформленні замовлень та підборі товарів
|
||||
**Ключові функції**:
|
||||
- Формування кошика замовлення
|
||||
- Пропозиції альтернатив, апсели, крос-сели
|
||||
- Перевірка можливості виконання замовлення
|
||||
- Розуміння контексту клієнта (роздріб/опт, новий/постійний)
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- SalesAPI
|
||||
- BasketTool
|
||||
- RecommendationEngine
|
||||
- PricingTool
|
||||
|
||||
---
|
||||
|
||||
### 8. Customer Care Agent
|
||||
**Роль**: Служба підтримки
|
||||
**Мета**: Швидко вирішувати проблеми клієнтів
|
||||
**Ключові функції**:
|
||||
- Ідентифікація клієнта та його замовлення
|
||||
- Відповіді на питання (статус, доставка, повернення)
|
||||
- Фіксація рекламацій та причин повернень
|
||||
- Пропозиція наступних кроків
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- SupportAPI
|
||||
- OrderLookupTool
|
||||
- ComplaintTool
|
||||
- TicketingTool
|
||||
|
||||
---
|
||||
|
||||
### 9. Finance & Pricing Agent
|
||||
**Роль**: Бухгалтер і фінансовий стратег
|
||||
**Мета**: Прозорі взаєморозрахунки та здорова економіка
|
||||
**Ключові функції**:
|
||||
- Ведення балансів учасників
|
||||
- Моделі ціноутворення (опт, роздріб, акції, промокоди)
|
||||
- Розрахунок комісій та виплат
|
||||
- Робота з токенами (DAAR/DAARION) та фіатом
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- FinanceAPI
|
||||
- PricingEngine
|
||||
- BalanceTool
|
||||
- PayoutCalculator
|
||||
|
||||
---
|
||||
|
||||
### 10. SMM & Campaigns Agent
|
||||
**Роль**: Маркетолог та контент-агент
|
||||
**Мета**: Просування товарів через цифрові канали
|
||||
**Ключові функції**:
|
||||
- Створення контенту для соцмереж, розсилок, банерів
|
||||
- Перевірка наявності товарів перед промо
|
||||
- Планування кампаній з чіткою метою
|
||||
- Честна комунікація без маніпуляцій
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- ContentGeneratorTool
|
||||
- CampaignAPI
|
||||
- SocialMediaTool
|
||||
- ImageGeneratorTool
|
||||
|
||||
---
|
||||
|
||||
### 11. SEO & Web Experience Agent
|
||||
**Роль**: SEO-оптимізатор
|
||||
**Мета**: Видимість в пошуку та зрозумілість для користувачів
|
||||
**Ключові функції**:
|
||||
- Оптимізація заголовків, описів, метаданих
|
||||
- Покращення структури контенту
|
||||
- Використання реальних даних про товари
|
||||
- Блоки довіри, FAQ, structured data
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- SEOAnalyzerTool
|
||||
- MetaGeneratorTool
|
||||
- ContentStructureTool
|
||||
|
||||
---
|
||||
|
||||
### 12. Analytics & BI Agent
|
||||
**Роль**: Аналітик даних
|
||||
**Мета**: Перетворення даних на actionable insights
|
||||
**Ключові функції**:
|
||||
- Формування зрозумілих звітів
|
||||
- Виявлення трендів, сезонності, аномалій
|
||||
- Пропозиції варіантів дій із вказанням ризиків
|
||||
- Роз'яснення в простих термінах
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- AnalyticsAPI
|
||||
- ReportGeneratorTool
|
||||
- TrendAnalyzerTool
|
||||
- ForecastingTool
|
||||
|
||||
---
|
||||
|
||||
### 13. Compliance & Audit Agent
|
||||
**Роль**: Внутрішній аудитор
|
||||
**Мета**: Відповідність політикам та здоровій бізнес-логіці
|
||||
**Ключові функції**:
|
||||
- Аналіз логів подій (зміни цін, списання, повернення)
|
||||
- Виявлення ризикових операцій
|
||||
- Формування попереджень та рекомендацій
|
||||
- Нейтральний, фактичний стиль
|
||||
|
||||
**Інструменти (TODO)**:
|
||||
- AuditLogTool
|
||||
- RiskDetectorTool
|
||||
- ComplianceCheckerTool
|
||||
|
||||
---
|
||||
|
||||
## Команди (Crews) для бізнес-сценаріїв
|
||||
|
||||
### 1. Onboard Vendor Crew
|
||||
**Мета**: Запуск нового комітента (виробника)
|
||||
**Агенти**: GREENFOOD Assistant, Vendor Success, Product & Catalog, Warehouse, Finance & Pricing
|
||||
**Етапи**:
|
||||
1. Привітання та збір інформації
|
||||
2. Створення карточок товарів
|
||||
3. Налаштування складу та партій
|
||||
4. Налаштування фінансів та ціноутворення
|
||||
5. Чекліст успішного запуску
|
||||
|
||||
**Виклик**:
|
||||
```python
|
||||
from services.greenfood.crew.greenfood_crews import GREENFOOD_CREWS, GREENFOOD_TASK_CREATORS
|
||||
|
||||
vendor_data = {
|
||||
"name": "Еко Мед Карпати",
|
||||
"products": ["Гірський мед", "Мед з липи", "Мед з акації"],
|
||||
"contact": "...",
|
||||
}
|
||||
|
||||
tasks = GREENFOOD_TASK_CREATORS["onboard_vendor"](vendor_data)
|
||||
crew = GREENFOOD_CREWS["onboard_vendor"]
|
||||
crew.tasks = tasks
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Fulfill Order Crew
|
||||
**Мета**: Виконання замовлення від прийняття до доставки
|
||||
**Агенти**: GREENFOOD Assistant, Seller, Warehouse, Logistics, Customer Care, Finance & Pricing
|
||||
**Етапи**:
|
||||
1. Прийняття замовлення
|
||||
2. Формування та підтвердження кошика
|
||||
3. Резервація товарів на складі
|
||||
4. Створення маршруту доставки
|
||||
5. Фінансові проводки
|
||||
6. Повідомлення клієнта
|
||||
|
||||
**Виклик**:
|
||||
```python
|
||||
order_data = {
|
||||
"customer_name": "Іван Петренко",
|
||||
"items": [{"product_id": "123", "quantity": 2}],
|
||||
"delivery_address": "м. Львів, вул. Шевченка 1",
|
||||
}
|
||||
|
||||
tasks = GREENFOOD_TASK_CREATORS["fulfill_order"](order_data)
|
||||
crew = GREENFOOD_CREWS["fulfill_order"]
|
||||
crew.tasks = tasks
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Monthly Settlement Crew
|
||||
**Мета**: Місячні звіряння та розрахунки
|
||||
**Агенти**: GREENFOOD Assistant, Finance & Pricing, Analytics & BI, Compliance & Audit, Vendor Success
|
||||
**Етапи**:
|
||||
1. Ініціація процесу звіряння
|
||||
2. Формування аналітичних звітів
|
||||
3. Розрахунок фінансових показників та актів звіряння
|
||||
4. Audit та виявлення ризиків
|
||||
5. Персоналізовані рекомендації комітентам
|
||||
|
||||
**Виклик**:
|
||||
```python
|
||||
period_data = {
|
||||
"period": "2025-11",
|
||||
"vendors": ["vendor_1", "vendor_2"],
|
||||
}
|
||||
|
||||
tasks = GREENFOOD_TASK_CREATORS["monthly_settlement"](period_data)
|
||||
crew = GREENFOOD_CREWS["monthly_settlement"]
|
||||
crew.tasks = tasks
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Marketing Campaign Crew (додатковий)
|
||||
**Мета**: Запуск маркетингової кампанії
|
||||
**Агенти**: GREENFOOD Assistant, Warehouse, SMM & Campaigns, SEO & Web, Finance & Pricing, Analytics & BI
|
||||
**Етапи**:
|
||||
1. Прийняття запиту на кампанію
|
||||
2. Перевірка наявності товарів
|
||||
3. Створення контенту
|
||||
4. SEO-оптимізація посадкових сторінок
|
||||
5. Налаштування цін та промокодів
|
||||
6. Налаштування відстеження KPI
|
||||
|
||||
---
|
||||
|
||||
## Зв'язки між агентами
|
||||
|
||||
### Найчастіші взаємодії
|
||||
|
||||
```
|
||||
GREENFOOD Assistant (центральний хаб)
|
||||
├── Product & Catalog ←→ Batch & Quality
|
||||
├── Warehouse ←→ Logistics & Delivery
|
||||
├── Warehouse ←→ Batch & Quality
|
||||
├── Seller ←→ Warehouse
|
||||
├── Seller ←→ Finance & Pricing
|
||||
├── Customer Care ←→ Logistics
|
||||
├── SMM & Campaigns ←→ Warehouse
|
||||
├── SMM & Campaigns ←→ SEO & Web
|
||||
├── Analytics & BI ←→ (всі агенти)
|
||||
├── Compliance & Audit ←→ (всі агенти)
|
||||
└── Vendor Success ←→ (всі агенти)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Інтеграція з DAGI Router
|
||||
|
||||
### Додавання в router-config.yml
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
greenfood:
|
||||
description: "GREENFOOD Assistant - ERP orchestrator"
|
||||
default_llm: local_qwen3_8b
|
||||
system_prompt: |
|
||||
Ти — GREENFOOD Assistant, фронтовий оркестратор ERP-системи...
|
||||
```
|
||||
|
||||
### Виклик через Router
|
||||
|
||||
```python
|
||||
from router_client import send_to_router
|
||||
|
||||
response = await send_to_router({
|
||||
"mode": "crew",
|
||||
"agent": "greenfood",
|
||||
"message": "Онбордь нового комітента 'Еко Мед Карпати'",
|
||||
"metadata": {
|
||||
"scenario": "onboard_vendor",
|
||||
"vendor_data": {...},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Файлова структура
|
||||
|
||||
```
|
||||
services/greenfood/
|
||||
├── __init__.py
|
||||
└── crew/
|
||||
├── __init__.py
|
||||
├── greenfood_prompts.py # 13 системних промтів
|
||||
├── greenfood_agents.py # 13 агентів
|
||||
└── greenfood_crews.py # 4 crews + task creators
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Наступні кроки
|
||||
|
||||
### Фаза 1: Базова інтеграція
|
||||
- [ ] Підключити GREENFOOD Assistant до DAGI Router
|
||||
- [ ] Протестувати базовий діалог
|
||||
- [ ] Додати інструменти (tools) для агентів
|
||||
|
||||
### Фаза 2: Інструменти та API
|
||||
- [ ] Реалізувати ProductCatalogAPI
|
||||
- [ ] Реалізувати WarehouseAPI
|
||||
- [ ] Реалізувати FinanceAPI
|
||||
- [ ] Додати інтеграції з зовнішніми сервісами
|
||||
|
||||
### Фаза 3: Crews та workflows
|
||||
- [ ] Протестувати onboard_vendor_crew
|
||||
- [ ] Протестувати fulfill_order_crew
|
||||
- [ ] Протестувати monthly_settlement_crew
|
||||
- [ ] Додати monitoring та logging
|
||||
|
||||
### Фаза 4: UI та UX
|
||||
- [ ] Web-інтерфейс для комітентів
|
||||
- [ ] Дашборди для різних ролей
|
||||
- [ ] Mobile app для складських та логістів
|
||||
- [ ] Інтеграція з Telegram для швидких запитів
|
||||
|
||||
---
|
||||
|
||||
## Контакти та підтримка
|
||||
|
||||
**Репозиторій**: `/Users/apple/github-projects/microdao-daarion`
|
||||
**Модуль**: `services/greenfood/crew`
|
||||
**Версія crewAI**: 0.28.0+
|
||||
**Python**: 3.11+
|
||||
|
||||
---
|
||||
|
||||
*Документ створено: 2025-11-18*
|
||||
*Останнє оновлення: 2025-11-18*
|
||||
|
||||
Reference in New Issue
Block a user