База Знаний ForjBot (Master Knowledge Base)
База Знаний ForjBot (Master Knowledge Base)
Статус документа: Полное консолидированное руководство по платформе на август 2026 г.
1. Архитектура и Архитектурное видение (3-Tier)
graph TD
subgraph Layer1 ["1. Слой Каналов (Channel Layer)"]
TG["Telegram"]
VK["VK"]
WC["WebChat"]
end
subgraph Layer2 ["2. Слой Адаптеров (Adapter Layer)"]
TA["TelegramAdapter"]
VA["VKAdapter"]
WA["WebChatAdapter"]
end
subgraph Layer3 ["3. Ядро Платформы (Core Layer)"]
Disp["core_dispatcher.py"]
LLM["LLM Client & Prompts"]
RAG["Vector RAG & Agent Loop"]
end
TG & VK & WC -->|IncomingMessage| TA & VA & WA
TA & VA & WA --> Disp --> LLM --> RAG
RAG -->|BasePlatformAdapter| TA & VA & WA
2. Система Памяти (L1–L4) и Гибридный Поиск
flowchart TD
L1["L1. Краткосрочный Контекст\n(short_term_context_n = 10..30)"] --> L2["L2. Сжатый Контекст\n(background_summary + style_profile)"]
L2 --> L3["L3. Граф Фактов\n(UserFact + FactRelation)"]
L3 --> L4["L4. База Знаний RAG\n(PostgreSQL FTS + PGVector TEI)"]
Формула RRF (Reciprocal Rank Fusion)
RRF_Score = 1 / (60 + Rank_vector) + 1 / (60 + Rank_fts)
3. Каталог Плагинов и Медиа-Модулей
| Категория | Название | Ключевые возможности |
|---|---|---|
| Плагин | WebSearchPlugin |
Поиск Tavily/Ollama (search_web), скачивание (fetch_url), автообучение _auto_learn |
| Плагин | CharacterPlugin |
Внешность персонажа character_appearance, инструмент update_character_appearance |
| Плагин | IntentRouterPlugin |
Экспресс-классификация намерений пользователя |
| Плагин | JailbreakGuardPlugin |
Защита от взлома, авто-бан BotConfig.jailbreak_auto_ban_on_heuristic, отчёты AbuseReport |
| Плагин | MultiAgentPlugin |
Маршрутизация диалога между суб-агентами |
| Плагин | NsfwPhotoPlugin |
Генерация обычных и откровенных фото (tease_photo, explicit_photo, photo_category) |
| Плагин | QuickQuestionsPlugin |
Варианты быстрых ответов (quick reply chips) |
| Плагин | RelationshipPlugin |
Метрика лояльности User.metric_score, metric_delta и спад decay_users_metric |
| Плагин | RemindersPlugin |
Напоминания через инструмент schedule_reminder и крон check_and_send_reminders |
| Медиа | PhotoCapability |
Изображения via Stability AI, Google Imagen, DashScope, OpenAI |
| Медиа | RagPhotosCapability |
Картинки из базы знаний via attach_document_image |
| Медиа | VoiceCapability |
Синтез речи (TTS) OpenAI / DashScope с автоподбором голоса по User.bot_gender |
| Медиа | VideoCapability |
Видеогенерация DashScope Video API (generate_video) |
| Медиа | Reactions & Stickers |
Эмодзи-реакции и отсылка стикеров по эмоциям |
4. Нативный Agent Loop и Tool Calling
flowchart LR
Msg["Сообщение"] --> LLM["LLM (tools=[...])"]
LLM -->|tool_calls| Status["send_tool_status('Поиск...')"]
Status --> Exec["Исполнение Инструмента"]
Exec --> LLM
LLM -->|Plain Text| Reply["Ответ Пользователю"]
5. WebChat и Веб-Виджет
- WebSocket (
WS /ws/webchat/{token}): Дуплексный стриминг текстовых реплик и визуальных статусов. - Подпись Сессий: HMAC-подпись
issue_session/sign_session_id. - Капча: Поддержка Yandex SmartCaptcha и Cloudflare Turnstile.
- Лид-Форма: Сбор контактов (имя, телефон, email), начисление бонусов
lead_reward_grantedи немедленный экспорт в CRM.
6. Безопасность и SSRF Guard
- Encryption at Rest: Ключи API хранятся зашифрованными
ENC:<fernet_token>. Валидация канарейкиcheck_encryption_canaryна старте. МаскированиеSECRET_MASKв интерфейсе. - SSRF Guard: Валидация
http_guard.validate_outbound_url(), блокировка приватных IP (127.0.0.1, 10.0.0.0/8, 169.254.169.254) и исключения черезSSRF_ALLOWED_HOSTS.
7. Статус Оплаты (Заморозка /buy)
ЗАМОРОЗКА ОПЛАТЫ: Раздел монетизации и команда /buy временно ЗАМОРОЖЕНЫ. Присутствует только базовый draft-прототип для Telegram Stars (XTR) (send_stars_invoice).