744c149300
Some checks failed
Build and Deploy Docs / build-and-deploy (push) Has been cancelled
- Created logs/ structure (sessions, operations, incidents) - Added session-start/log/end scripts - Installed Git hooks for auto-logging commits/pushes - Added shell integration for zsh - Created CHANGELOG.md - Documented today's session (2026-01-10)
26 KiB
26 KiB
Архітектура розширеного чату
Дата: 2025-11-23
🏗️ Структура компонентів
┌─────────────────────────────────────────────────────────────┐
│ │
│ MicroDaoOrchestratorChatEnhanced (Головний компонент) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ Chat Header │ │ │
│ │ │ 👑 Оркестратор мікроДАО - [Agent Name] │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ Messages Area │ │ │
│ │ │ │ │ │
│ │ │ 👤 User: Привіт! │ │ │
│ │ │ 🤖 Agent: Вітаю! Чим можу допомогти? │ │ │
│ │ │ 👤 User: [Image] Що це? │ │ │
│ │ │ 🤖 Agent: Це сонячна панель... │ │ │
│ │ │ 💭 Loading... │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ MultimodalInput │ │ │
│ │ │ ┌────┬────┬────┬────┐ │ │ │
│ │ │ │ 🎤 │ 🖼️ │ 📎 │ 🌐 │ [Text Input] [Send] │ │ │
│ │ │ └────┴────┴────┴────┘ │ │ │
│ │ │ Голос Фото Файл Веб │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
▼ Згорнути/Розгорнути
┌─────────────────────────────────────────────────────────────┐
│ │
│ KnowledgeBase (База знань агента) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 📊 База знань - [Agent Name] [Завантажити файл] │ │
│ │ ───────────────────────────────────────────────────── │ │
│ │ │ │
│ │ 📄 energy-guide.pdf (2.5 MB) [🗑️] │ │
│ │ ✅ Векторна БД ✅ Графова БД │ │
│ │ Status: Completed │ │
│ │ │ │
│ │ 📄 solar-panels.docx (150 KB) [🗑️] │ │
│ │ ⏳ Векторна БД ⏳ Графова БД │ │
│ │ Status: Vectorized │ │
│ │ │ │
│ │ ─────────────────────────────────────────────────── │ │
│ │ Статистика: │ │
│ │ Всього: 2 | Векторизовано: 2 | У графі: 1 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
▼ Згорнути/Розгорнути
┌─────────────────────────────────────────────────────────────┐
│ │
│ SystemPromptEditor (Системний промпт) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ⚙️ Системний промпт - [Agent Name] [Редагувати] [🔄] │ │
│ │ ───────────────────────────────────────────────────── │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────────┐ │ │
│ │ │ Ти - Helion, AI-агент платформи Energy Union. │ │ │
│ │ │ Допомагай користувачам з технологіями │ │ │
│ │ │ EcoMiner/BioMiner, токеномікою та DAO governance. │ │ │
│ │ │ │ │ │
│ │ │ Твої основні функції: │ │ │
│ │ │ - Консультації з енергетичними технологіями │ │ │
│ │ │ - Пояснення токеноміки Energy Union │ │ │
│ │ │ - Допомога з onboarding в DAO │ │ │
│ │ │ ... │ │ │
│ │ └───────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 345 символів │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
▼ Згорнути/Розгорнути
┌─────────────────────────────────────────────────────────────┐
│ │
│ TelegramIntegration (Telegram інтеграція) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 💬 Telegram інтеграція - [Agent Name] ✅ Підключено │ │
│ │ ───────────────────────────────────────────────────── │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────────┐ │ │
│ │ │ Ім'я бота: @helion_bot │ │ │
│ │ │ Підключено: 23.11.2025 10:00 │ │ │
│ │ │ │ │ │
│ │ │ [Відкрити бота] [Копіювати посилання] │ │ │
│ │ │ │ │ │
│ │ │ Токен: 1234567890:ABCdef...ghij │ │ │
│ │ └───────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ [Від'єднати бота] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
🔄 Data Flow
┌─────────────┐
│ User │
└──────┬──────┘
│
│ (Input: text/voice/image/file)
▼
┌─────────────────────────┐
│ MultimodalInput │
│ - Voice → STT │
│ - Image → Base64 │
│ - File → FormData │
│ - Text → String │
└──────────┬──────────────┘
│
│ (message + context)
▼
┌──────────────────────────────┐
│ MicroDaoOrchestrator │
│ ChatEnhanced │
│ - Add user message │
│ - Prepare payload │
│ - Call Router API │
└──────────┬───────────────────┘
│
│ POST /route
▼
┌──────────────────────────────┐
│ Router (NODE1) │
│ - Match agent rule │
│ - Load system_prompt │
│ - Call LLM (qwen3:8b) │
└──────────┬───────────────────┘
│
│ Response
▼
┌──────────────────────────────┐
│ MicroDaoOrchestrator │
│ ChatEnhanced │
│ - Parse response │
│ - Add assistant message │
│ - Update UI │
└──────────┬───────────────────┘
│
│ (display message)
▼
┌─────────────┐
│ User │
└─────────────┘
🗂️ Component Hierarchy
MicroDaoOrchestratorChatEnhanced
├── State Management
│ ├── messages: ChatMessage[]
│ ├── input: string
│ ├── attachedImages: File[]
│ ├── attachedFiles: File[]
│ ├── knowledgeFiles: KnowledgeFile[]
│ ├── systemPrompt: string
│ ├── telegramConnected: boolean
│ └── UI states (show/hide sections)
│
├── Main Chat Window
│ ├── Header (Crown icon, agent name, close button)
│ ├── Messages Area
│ │ ├── User messages (right, purple)
│ │ ├── Agent messages (left, white)
│ │ ├── Images preview
│ │ ├── Attachments list
│ │ └── Loading spinner
│ └── MultimodalInput
│ ├── Voice button (🎤)
│ ├── Image button (🖼️)
│ ├── File button (📎)
│ ├── Web search button (🌐)
│ ├── Text input (textarea)
│ └── Send button
│
├── KnowledgeBase (collapsible)
│ ├── Header (title, upload button)
│ ├── Upload Area (drag & drop)
│ ├── Files List
│ │ ├── File item
│ │ │ ├── Name, size, status
│ │ │ ├── Vector DB indicator
│ │ │ ├── Graph DB indicator
│ │ │ └── Actions (reindex, delete)
│ │ └── ...
│ └── Statistics (total, vectorized, graphed)
│
├── SystemPromptEditor (collapsible)
│ ├── Header (title, edit/save buttons, reset)
│ ├── Display mode
│ │ └── Read-only prompt text
│ ├── Edit mode
│ │ └── Textarea with prompt
│ └── Character count
│
└── TelegramIntegration (collapsible)
├── Header (title, status indicator)
├── Connected state
│ ├── Bot info (username, date)
│ ├── Bot token (masked)
│ ├── Actions (open bot, copy link)
│ └── Disconnect button
└── Disconnected state
├── Instructions
├── Token input
└── Connect button
🔌 Services Architecture
┌──────────────────────────────────────────────────────────┐
│ Frontend Layer │
│ ┌────────────────────────────────────────────────────┐ │
│ │ MicroDaoOrchestratorChatEnhanced │ │
│ │ - Manages UI state │ │
│ │ - Handles user interactions │ │
│ │ - Orchestrates services │ │
│ └────────┬──────────────┬──────────────┬──────────────┘ │
│ │ │ │ │
└───────────┼──────────────┼──────────────┼─────────────────┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌─────────────────┐
│ voiceService │ │ webSearch │ │ knowledgeBase │
│ │ │ Service │ │ Service │
├───────────────┤ ├──────────────┤ ├─────────────────┤
│ - startRec() │ │ - search() │ │ - uploadFile() │
│ - stopRec() │ │ - format() │ │ - getFiles() │
│ - speak() │ │ - extract() │ │ - deleteFile() │
│ - stopSpeak() │ │ │ │ - reindex() │
└───────┬───────┘ └──────┬───────┘ └────────┬────────┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Web Speech │ │ Router API │ │ Backend API │
│ API │ │ (NODE1) │ │ (NODE1) │
├───────────────┤ ├──────────────┤ ├─────────────────┤
│ - STT │ │ POST /route │ │ Knowledge Base │
│ - TTS │ │ mode: web │ │ System Prompt │
│ │ │ search │ │ Telegram │
└───────────────┘ └──────────────┘ └─────────────────┘
🌊 Message Flow Example
1. User sends voice message
User: [Press 🎤]
↓
MultimodalInput:
- voiceService.startRecording()
- Show "Recording..." indicator
↓
User: [Speaks] "Привіт, ти хто?"
↓
Web Speech API:
- Converts speech to text
- Returns: "Привіт, ти хто?"
↓
MultimodalInput:
- Sets input value
- User clicks Send
↓
MicroDaoOrchestratorChatEnhanced:
- Creates user message
- Adds to messages state
- Calls sendMessageMutation.mutate()
↓
API Call:
POST http://144.76.224.179:9102/route
{
"agent": "helion",
"message": "Привіт, ти хто?",
"mode": "chat",
"payload": {
"context": {
"system_prompt": "Ти - Helion..."
}
}
}
↓
Router (NODE1):
- Matches rule: helion_agent
- Uses LLM: local_qwen3_8b
- Calls Ollama API
- Generates response
↓
Response:
{
"ok": true,
"data": {
"text": "Привіт! Я - Helion, AI-агент..."
}
}
↓
MicroDaoOrchestratorChatEnhanced:
- Parses response
- Creates assistant message
- Adds to messages state
- UI updates automatically
↓
User: [Sees response in chat]
2. User uploads image
User: [Clicks 🖼️]
↓
MultimodalInput:
- Opens file picker
↓
User: [Selects image.jpg]
↓
MultimodalInput:
- Calls onImageUpload(file)
- Adds to attachedImages
- Shows preview
↓
User: [Types] "Що це?"
↓
User: [Clicks Send]
↓
MicroDaoOrchestratorChatEnhanced:
- Creates user message with image
- Converts image to base64
- Calls API with image data
↓
API Call:
POST /route
{
"agent": "helion",
"message": "Що це?",
"payload": {
"context": {
"system_prompt": "...",
"images": ["data:image/jpeg;base64,/9j/4AAQ..."]
}
}
}
↓
Router → LLM:
- Processes image (if vision model)
- Generates response
↓
User: [Sees response about the image]
3. User uploads file to knowledge base
User: [Opens KnowledgeBase section]
↓
User: [Drags document.pdf]
↓
KnowledgeBase:
- Validates file (size, type)
- Calls onUpload(file)
↓
MicroDaoOrchestratorChatEnhanced:
- Creates KnowledgeFile object
- Status: pending
- Adds to knowledgeFiles state
↓
knowledgeBaseService:
- uploadFile(agentId, file)
↓
API Call:
POST /api/knowledge/upload
FormData: {file, agent_id}
↓
Backend:
- Saves file
- Starts vectorization
- Returns file_id
↓
Background Processing:
1. Extract text from PDF
2. Create chunks
3. Generate embeddings
4. Store in Vector DB ✅
5. Extract entities
6. Create relationships
7. Store in Graph DB ✅
↓
Status Updates:
pending → vectorized → graphed → completed
↓
UI Updates:
- Shows progress
- Updates indicators
- Shows ✅ when done
💾 State Management
// Main component state
interface ChatState {
// Messages
messages: ChatMessage[];
input: string;
// Multimodal
isRecording: boolean;
attachedImages: File[];
attachedFiles: File[];
// Knowledge Base
knowledgeFiles: KnowledgeFile[];
// System Prompt
systemPrompt: string;
// Telegram
telegramConnected: boolean;
telegramBotUsername?: string;
telegramBotToken?: string;
// UI
showKnowledgeBase: boolean;
showSystemPrompt: boolean;
showTelegram: boolean;
}
// React Query state
const sendMessageMutation = useMutation({
mutationFn: async (message: string) => {...},
onSuccess: (data) => {...},
onError: (error) => {...},
});
🎨 Styling System
Tailwind CSS Classes Structure:
Main Container:
- bg-white rounded-lg shadow-lg border
Headers:
- bg-gradient-to-r from-[color]-600 to-[color]-700
- Colors: purple (main), indigo (KB), amber (prompt), blue (telegram)
Buttons:
- Primary: bg-purple-600 hover:bg-purple-700
- Secondary: bg-gray-100 hover:bg-gray-200
- Success: bg-green-600 hover:bg-green-700
- Danger: bg-red-600 hover:bg-red-700
Messages:
- User: bg-purple-600 text-white (right aligned)
- Agent: bg-white border text-gray-800 (left aligned)
Status Indicators:
- Pending: text-yellow-500
- Success: text-green-600
- Error: text-red-500
- Info: text-blue-600
Icons: lucide-react
- 24px (h-6 w-6) for headers
- 20px (h-5 w-5) for buttons
- 16px (h-4 w-4) for inline icons
📦 File Structure Summary
Total Files Created: 12
Components (6):
✅ MicroDaoOrchestratorChatEnhanced.tsx (450+ lines)
✅ MicroDaoOrchestratorChatWrapper.tsx (50+ lines)
✅ chat/MultimodalInput.tsx (250+ lines)
✅ chat/KnowledgeBase.tsx (300+ lines)
✅ chat/SystemPromptEditor.tsx (200+ lines)
✅ chat/TelegramIntegration.tsx (250+ lines)
Services (3):
✅ voiceService.ts (150+ lines)
✅ webSearchService.ts (100+ lines)
✅ knowledgeBaseService.ts (200+ lines)
Index Files (2):
✅ chat/index.ts (5 lines)
✅ services/index.ts (5 lines)
Documentation (5):
✅ ORCHESTRATOR-CHAT-ENHANCED.md (800+ lines)
✅ INTEGRATION-EXAMPLE.md (500+ lines)
✅ ENHANCED-CHAT-SUMMARY.md (600+ lines)
✅ CHAT-ARCHITECTURE.md (400+ lines)
✅ CHAT-MESSAGE-FIX.md (200+ lines)
Total Lines of Code: ~4000+
🚀 Quick Reference
Import Component
import { MicroDaoOrchestratorChatEnhanced } from '@/components/microdao/MicroDaoOrchestratorChatEnhanced';
Basic Usage
<MicroDaoOrchestratorChatEnhanced
orchestratorAgentId="helion"
onClose={() => setShowChat(false)}
/>
With Services
import { voiceService, webSearchService, knowledgeBaseService } from '@/services';
// Voice
voiceService.startRecording(onResult, onError);
voiceService.speak("Привіт!");
// Web Search
const results = await webSearchService.search("query", "helion");
// Knowledge Base
await knowledgeBaseService.uploadFile("helion", file);
🎯 Key Features Matrix
| Feature | Component | Service | Status |
|---|---|---|---|
| Text Chat | Main | - | ✅ |
| Voice Input | MultimodalInput | voiceService | ✅ |
| Voice Output | - | voiceService | ⏳ |
| Image Upload | MultimodalInput | - | ✅ |
| Image Recognition | - | Router API | ⏳ |
| File Upload | MultimodalInput | - | ✅ |
| Web Search | MultimodalInput | webSearchService | ✅ |
| Knowledge Base | KnowledgeBase | knowledgeBaseService | ✅ Frontend |
| System Prompt | SystemPromptEditor | - | ✅ Frontend |
| Telegram | TelegramIntegration | - | ✅ Frontend |
✅ = Готово
⏳ = Потрібна Backend реалізація
🔗 Related Documentation
- 📄 ORCHESTRATOR-CHAT-ENHANCED.md - Детальна документація
- 📄 INTEGRATION-EXAMPLE.md - Приклади використання
- 📄 ENHANCED-CHAT-SUMMARY.md - Підсумок виконаної роботи
- 📄 CHAT-MESSAGE-FIX.md - Виправлення bug
- 📄 TIMEOUT-FIX.md - Оптимізація таймаутів
Дата створення: 2025-11-23
Статус: ✅ Production Ready (Frontend)