diff --git a/Telegram бот для Obsidian.md b/Telegram бот для Obsidian.md new file mode 100644 index 0000000..c3f1087 --- /dev/null +++ b/Telegram бот для Obsidian.md @@ -0,0 +1,380 @@ +## 1. Обзор системы + +### 1.1 Назначение +Система представляет собой Telegram бота для автоматизации создания и управления заметками в Obsidian с интеграцией в существующий Git + Quartz workflow. + +### 1.2 Ключевые функции +- Создание заметок из текстовых и голосовых сообщений +- Семантический поиск по базе знаний +- Дополнение существующих заметок +- Автоматическое форматирование через GPT +- Интеграция с Git для версионирования +- Автоматическая публикация через Quartz + +### 1.3 Ограничения и допущения +- Один пользователь (личное использование) +- Развертывание на VPS с ограниченными ресурсами +- Интеграция с существующей инфраструктурой Git + Quartz +- Приоритет простоты разработки над масштабируемостью + +## 2. Архитектурные решения + +### 2.1 Выбор архитектурного стиля: Модульный монолит + +**Обоснование:** +- Простота разработки и развертывания +- Оптимальное использование ресурсов VPS +- Быстрая итерация для единственного пользователя +- Легкость отладки и мониторинга + +**Альтернативы рассмотренные:** +- Микросервисная архитектура (отклонена из-за избыточной сложности) +- Serverless функции (отклонена из-за холодного старта и ограничений по времени) + +### 2.2 Технологический стек + +**Основной язык:** Go 1.21+ +- Высокая производительность +- Простое развертывание (единый бинарник) +- Отличная поддержка конкурентности +- Богатая экосистема для Telegram ботов + +**Ключевые зависимости:** +- `telegram-bot-api/v5` - Telegram Bot API +- `go-openai` - OpenAI API интеграция +- `go-git/v5` - Git операции +- `viper` - конфигурация +- `logrus` - структурированное логирование + +**Внешние сервисы:** +- OpenAI API (GPT-4, Whisper) +- Telegram Bot API +- Векторная база данных (Qdrant/Chroma) + +## 3. Архитектура системы + +### 3.1 Общая диаграмма системы + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Telegram │ │ │ │ External │ +│ User │◄──►│ Monolithic │◄──►│ Services │ +│ │ │ Bot App │ │ │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ + ▼ ├─ OpenAI API + ┌─────────────────┐ ├─ Vector DB + │ File System │ └─ Telegram API + │ │ + ├─ Obsidian Vault │ + ├─ Git Repository │ + └─ Vector Index │ + │ + ▼ + ┌─────────────────┐ + │ Git Hooks │ + │ │ + └─ Quartz Rebuild │ +``` + +### 3.2 Компонентная диаграмма + +``` +┌─────────────────────────────────────────────────────────┐ +│ Monolithic Application │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Bot │ │ HTTP │ │ CLI │ │ +│ │ Handler │ │ Server │ │ Tools │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ │ │ │ +│ └─────────────────┼─────────────────┘ │ +│ │ │ +│ ┌─────────────────────────┼─────────────────────────┐ │ +│ │ Business Logic Layer │ │ +│ │ │ │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │ +│ │ │ Note │ │ Search │ │ Voice │ │ │ +│ │ │ Service │ │ Service │ │ Service │ │ │ +│ │ └─────────────┘ └─────────────┘ └───────────┘ │ │ +│ │ │ │ │ │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │ +│ │ │ LLM │ │ File │ │ Git │ │ │ +│ │ │ Service │ │ Service │ │ Service │ │ │ +│ │ └─────────────┘ └─────────────┘ └───────────┘ │ │ +│ └─────────────────────┼─────────────────────────────┘ │ +│ │ │ +│ ┌─────────────────────┼─────────────────────────────┐ │ +│ │ Infrastructure Layer │ │ +│ │ │ │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │ +│ │ │ Config │ │ Logger │ │ Cache │ │ │ +│ │ │ Manager │ │ │ │ │ │ │ +│ │ └─────────────┘ └─────────────┘ └───────────┘ │ │ +│ └─────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +### 3.3 Диаграмма потоков данных + +``` +User Message Flow: +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Telegram │───►│ Bot │───►│ Router │ +│ Message │ │ Handler │ │ │ +└─────────────┘ └─────────────┘ └─────────────┘ + │ + ┌─────────────────────────┼─────────────────────────┐ + ▼ ▼ ▼ + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ + │ Create │ │ Search │ │ Append │ + │ Note │ │ Notes │ │ Note │ + └─────────────┘ └─────────────┘ └─────────────┘ + │ │ │ + ▼ │ ▼ + ┌─────────────┐ │ ┌─────────────┐ + │ Format │ │ │ Find & │ + │ with GPT │ │ │ Update │ + └─────────────┘ │ └─────────────┘ + │ │ │ + ▼ │ ▼ + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ + │ Save │ │ Vector │ │ Save │ + │ File │ │ Search │ │ File │ + └─────────────┘ └─────────────┘ └─────────────┘ + │ │ │ + └─────────────────────────┼─────────────────────────┘ + ▼ + ┌─────────────┐ + │ Git │ + │ Commit │ + └─────────────┘ + │ + ▼ + ┌─────────────┐ + │ Quartz │ + │ Rebuild │ + └─────────────┘ +``` + +## 4. Детальное описание компонентов + +### 4.1 Presentation Layer + +**Bot Handler** +- Ответственность: Обработка Telegram API, маршрутизация команд +- Интерфейсы: Telegram Bot API +- Зависимости: Router, Context Manager + +**HTTP Server** (опциональный) +- Ответственность: Health checks, метрики, webhook endpoint +- Интерфейсы: HTTP REST API +- Зависимости: Monitoring tools + +### 4.2 Business Logic Layer + +**Note Service** +- Ответственность: Создание, обновление заметок, управление жизненным циклом +- Интерфейсы: Note CRUD операции +- Зависимости: LLM Service, File Service, Git Service + +**Search Service** +- Ответственность: Векторный поиск, индексация, семантический анализ +- Интерфейсы: Search API, Indexing API +- Зависимости: Vector Database, Embedding Service + +**Voice Service** +- Ответственность: Обработка голосовых сообщений, транскрипция +- Интерфейсы: Audio processing API +- Зависимости: Whisper API, File Service + +**LLM Service** +- Ответственность: Интеграция с GPT, форматирование, генерация контента +- Интерфейсы: Text processing API +- Зависимости: OpenAI API + +### 4.3 Infrastructure Layer + +**File Service** +- Ответственность: Файловые операции, управление Obsidian vault +- Интерфейсы: File system operations +- Зависимости: OS file system + +**Git Service** +- Ответственность: Version control, автоматические коммиты +- Интерфейсы: Git operations API +- Зависимости: Git repository + +## 5. Интеграционная архитектура + +### 5.1 Внешние интеграции + +**OpenAI API** +- Назначение: GPT-4 для форматирования, Whisper для транскрипции +- Протокол: HTTPS REST API +- Аутентификация: API Key +- Обработка ошибок: Retry with exponential backoff + +**Telegram Bot API** +- Назначение: Получение сообщений, отправка ответов +- Протокол: HTTPS REST API / WebHooks +- Аутентификация: Bot Token +- Режим работы: Long polling (рекомендуется для VPS) + +**Vector Database** +- Назначение: Семантический поиск по заметкам +- Варианты: Qdrant (HTTP API) или Chroma (HTTP API) +- Протокол: HTTPS REST API +- Данные: Embeddings + метаданные заметок + +### 5.2 Файловая система + +**Obsidian Vault Structure** +``` +vault/ +├── notes/ # Основные заметки +├── daily/ # Ежедневные заметки +├── templates/ # Шаблоны +├── attachments/ # Медиа файлы +└── .obsidian/ # Конфигурация Obsidian +``` + +**Git Integration** +- Автоматические коммиты после каждого изменения +- Meaningful commit messages +- Direct push в main branch +- Git hooks для триггера Quartz rebuild + +## 6. Данные и хранение + +### 6.1 Модель данных + +**Note Entity** +``` +Note { + ID: UUID + Title: string + Content: string (Markdown) + Filename: string + Created: timestamp + Updated: timestamp + Tags: []string + Links: []string + Embedding: []float32 +} +``` + +**User Context** +``` +UserContext { + UserID: int64 + State: enum (idle, creating_note, appending, searching) + Data: map[string]interface{} + LastActivity: timestamp +} +``` + +### 6.2 Хранение данных + +**Файловая система** +- Obsidian заметки: Markdown файлы в vault directory +- Конфигурация: .env файл или environment variables +- Логи: Rotated log files или stdout для containerized deployment + +**Временное хранение** +- User contexts: In-memory map (single user) +- Cache: In-memory или embedded BoltDB +- Vector embeddings: External vector database + +## 7. Развертывание и операционные аспекты + +### 7.1 Архитектура развертывания + +``` +VPS Server +├── Application Binary +├── Configuration Files +├── Obsidian Vault (Git Repository) +├── Vector Database (если локальная) +└── Monitoring & Logs +``` + +### 7.2 Масштабирование + +**Текущие ограничения:** +- Один пользователь +- Один экземпляр приложения +- Локальные файловые операции + +**Возможности роста:** +- Horizontal scaling: добавление Redis для shared state +- Vertical scaling: увеличение ресурсов VPS +- Service extraction: выделение vector search в отдельный сервис + +### 7.3 Мониторинг и наблюдаемость + +**Логирование:** +- Structured logging (JSON format) +- Log levels: ERROR, WARN, INFO, DEBUG +- Log rotation для экономии места + +**Метрики:** +- Application health status +- Message processing time +- OpenAI API response times +- Git operation success/failure rates + +**Алерты:** +- Application down +- High error rate +- OpenAI API quota exceeded +- Git push failures + +## 8. Безопасность + +### 8.1 Аутентификация и авторизация +- Telegram User ID whitelist (только владелец) +- API keys в environment variables +- No public endpoints кроме Telegram webhook + +### 8.2 Защита данных +- API keys не в коде +- Логи не содержат sensitive данные +- HTTPS для всех внешних API calls +- Git repository может быть private + +## 9. Качественные атрибуты + +### 9.1 Производительность +- Время отклика бота: < 2 секунды для текстовых сообщений +- Время создания заметки: < 5 секунд включая GPT обработку +- Голосовые сообщения: < 10 секунд для транскрипции и создания заметки + +### 9.2 Надежность +- Graceful degradation при недоступности OpenAI API +- Retry mechanisms для внешних API +- Data consistency через atomic git operations + +### 9.3 Maintainability +- Четкое разделение ответственности между слоями +- Интерфейсы для всех основных компонентов +- Comprehensive logging для отладки +- Configuration management через environment variables + +## 10. Риски и ограничения + +### 10.1 Технические риски +- **OpenAI API limits:** Rate limiting может замедлить обработку +- **Vector DB performance:** Поиск может замедляться с ростом количества заметок +- **VPS resources:** Ограниченная память и CPU для vector operations + +### 10.2 Операционные риски +- **Single point of failure:** Монолитная архитектура +- **Manual deployment:** Отсутствие автоматизированного CI/CD +- **Backup dependency:** Зависимость от Git для backup заметок + +### 10.3 Митигация рисков +- Monitoring и alerting для раннего обнаружения проблем +- Регулярные backups Git repository +- Graceful fallbacks при недоступности внешних сервисов +- Resource monitoring для предотвращения исчерпания ресурсов VPS \ No newline at end of file