vault backup: 2025-08-08 09:44:48
This commit is contained in:
Andrey Epifancev
@@ -1,94 +1,220 @@
|
||||
---
|
||||
tags:
|
||||
- mvp
|
||||
- teleram-bot
|
||||
- LLM
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
tags:
|
||||
|
||||
- mvp
|
||||
- telegram-bot
|
||||
- obsidian
|
||||
- go
|
||||
|
||||
---
|
||||
|
||||
## 1. Цели MVP
|
||||
|
||||
- Принимать текстовые сообщения в Telegram.
|
||||
- Создавать заметки в Obsidian Vault в формате Markdown.
|
||||
- Автоматически коммитить и пушить изменения в Git-репозиторий.
|
||||
- Поддерживать базовое форматирование текста через YandexGPT.
|
||||
- Поддержка одного пользователя.
|
||||
- Принимать текстовые сообщения в Telegram
|
||||
- Создавать заметки в Obsidian Vault в формате Markdown
|
||||
- Асинхронно синхронизировать изменения с Git-репозиторием
|
||||
- Поддерживать базовое форматирование текста (без LLM)
|
||||
- Поддержка whitelist пользователей
|
||||
|
||||
> **Не включаем на первом этапе:**
|
||||
> Голосовые сообщения, векторный поиск, Quartz-публикацию.
|
||||
> Голосовые сообщения, векторный поиск, Quartz-публикация, LLM интеграция
|
||||
|
||||
---
|
||||
|
||||
## 2. Компоненты MVP
|
||||
|
||||
### 2.1 Bot Handler (Go + Telegram API)
|
||||
- Используем `telegram-bot-api/v5`.
|
||||
|
||||
- Используем `telegram-bot-api/v5`
|
||||
- Поддерживаем команды:
|
||||
- `/new <текст>` — создать новую заметку.
|
||||
- `/append <имя>` — дописать к существующей заметке (по exact match).
|
||||
- `/list` — список последних 5 заметок.
|
||||
- `/new <текст>` — создать новую заметку
|
||||
- `/append <частичное_имя>` — дописать к существующей заметке (fuzzy search)
|
||||
- `/list` — список последних 5 заметок
|
||||
- Whitelist авторизация по Telegram User ID
|
||||
- Graceful shutdown с завершением pending операций
|
||||
|
||||
### 2.2 Note Service
|
||||
- Создание Markdown-файлов в директории `vault/notes`.
|
||||
- Простая генерация имени файла по дате + заголовку.
|
||||
- Добавление timestamps в YAML frontmatter.
|
||||
- Вызов LLM Service для легкого форматирования (через YandexGPT API).
|
||||
|
||||
### 2.3 LLM Service (YandexGPT)
|
||||
- YandexGPT форматирует Markdown (добавляет заголовки, убирает лишние пробелы).
|
||||
- Транскрипции и поиск по эмбеддингам — **не реализуем** на MVP.
|
||||
- Создание Markdown-файлов в директории `vault/notes`
|
||||
- Умная генерация имени файла: `YYYY-MM-DD-HHMM-slug.md`
|
||||
- Добавление timestamps в YAML frontmatter
|
||||
- Базовое форматирование (первая строка = заголовок)
|
||||
- Fuzzy search для поиска существующих заметок
|
||||
|
||||
### 2.4 Git Service
|
||||
- Используем `go-git/v5`.
|
||||
- После создания/обновления заметки:
|
||||
1. `git add <file>`
|
||||
2. `git commit -m "add note <title>"`
|
||||
3. `git push`
|
||||
### 2.3 Git Service (Асинхронный)
|
||||
|
||||
### 2.5 File Service
|
||||
- Создает файлы в `vault/notes`.
|
||||
- Проверяет уникальность имени.
|
||||
- Обеспечивает atomic save.
|
||||
- Используем `go-git/v5`
|
||||
- **Eventual consistency pattern:**
|
||||
1. Файл сохраняется мгновенно
|
||||
2. Пользователь получает подтверждение
|
||||
3. Git sync идет в фоне через канал
|
||||
4. Батчевые коммиты каждые 30 секунд
|
||||
- Retry logic при ошибках сети
|
||||
- Graceful handling git failures (не влияют на UX)
|
||||
|
||||
### 2.4 File Service
|
||||
|
||||
- Создает файлы в `vault/notes`
|
||||
- Atomic file operations
|
||||
- Проверка уникальности имени файла
|
||||
- Slug generation для читаемых имен
|
||||
|
||||
---
|
||||
|
||||
## 3. Поток обработки сообщений MVP
|
||||
## 3. Поток обработки сообщений
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[User] --> B[Telegram Bot]
|
||||
B --> C[Bot Handler]
|
||||
B --> C[Auth Check]
|
||||
C --> D["/new text"]
|
||||
D --> E[Note Service]
|
||||
E --> F[LLM Service format]
|
||||
F --> G[File Service]
|
||||
G --> H[Git Service]
|
||||
H --> I["Заметка создана: filename"]
|
||||
I --> A
|
||||
E --> F[File Service: Save]
|
||||
F --> G["✅ Instant Response"]
|
||||
G --> A
|
||||
|
||||
subgraph "MVP Flow"
|
||||
F --> H[Git Queue]
|
||||
H --> I[Background Worker]
|
||||
I --> J[Batch Commit + Push]
|
||||
|
||||
subgraph "Synchronous (Fast)"
|
||||
C
|
||||
D
|
||||
E
|
||||
F
|
||||
G
|
||||
end
|
||||
|
||||
subgraph "Asynchronous (Eventual)"
|
||||
H
|
||||
I
|
||||
J
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Технологический стек MVP
|
||||
## 4. Технологический стек
|
||||
|
||||
**Основные зависимости:**
|
||||
- `telegram-bot-api/v5` - Telegram Bot API
|
||||
- `yandexcloud-sdk-go` - YandexGPT API интеграция
|
||||
- `go-git/v5` - Git операции
|
||||
- `viper` - конфигурация
|
||||
- `logrus` - структурированное логирование
|
||||
|
||||
**Внешние сервисы:**
|
||||
- YandexGPT API (YandexGPT Lite/Pro)
|
||||
- Telegram Bot API
|
||||
- `telegram-bot-api/v5` - Telegram Bot API
|
||||
- `go-git/v5` - Git операции
|
||||
- `viper` - конфигурация
|
||||
- `logrus` - структурированное логирование
|
||||
|
||||
**Конфигурация:**
|
||||
- `YANDEX_API_KEY` - API ключ для YandexGPT
|
||||
- `TELEGRAM_BOT_TOKEN` - токен Telegram бота
|
||||
- `VAULT_PATH` - путь к Obsidian vault
|
||||
|
||||
```yaml
|
||||
telegram_token: "your_bot_token"
|
||||
vault_path: "./vault/notes"
|
||||
allowed_user_ids: [123456789]
|
||||
|
||||
git:
|
||||
sync_interval: "30s"
|
||||
max_queue_size: 100
|
||||
|
||||
logging:
|
||||
level: "info"
|
||||
```
|
||||
|
||||
**Внешние сервисы:**
|
||||
|
||||
- Telegram Bot API
|
||||
- Git remote repository
|
||||
|
||||
---
|
||||
|
||||
## 5. Структура проекта
|
||||
|
||||
```
|
||||
obsidian-telegram-bot/
|
||||
├── cmd/
|
||||
│ └── bot/
|
||||
│ └── main.go
|
||||
├── internal/
|
||||
│ ├── bot/ # Telegram handlers + auth
|
||||
│ ├── note/ # Note operations + fuzzy search
|
||||
│ ├── git/ # Async git sync
|
||||
│ └── config/ # Configuration management
|
||||
├── configs/
|
||||
│ └── config.yaml
|
||||
├── vault/
|
||||
│ └── notes/ # Generated markdown files
|
||||
├── go.mod
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Архитектурные решения
|
||||
|
||||
### 6.1 Filename Generation
|
||||
|
||||
```go
|
||||
// Пример: "2024-01-15-1430-team-meeting.md"
|
||||
func generateFilename(text string) string {
|
||||
timestamp := time.Now().Format("2006-01-02-1504")
|
||||
slug := slugify(extractTitle(text)) // Первые 3 слова
|
||||
return fmt.Sprintf("%s-%s.md", timestamp, slug)
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 Error Handling Strategy
|
||||
|
||||
- **File operations:** Fail fast, немедленный ответ пользователю
|
||||
- **Git operations:** Fail gracefully, логирование, retry в фоне
|
||||
- **Network issues:** Не блокируют создание заметок
|
||||
|
||||
### 6.3 Fuzzy Search для /append
|
||||
|
||||
```go
|
||||
// /append meeting -> найдет "2024-01-15-1430-team-meeting.md"
|
||||
func FindNoteByPartialName(query string) ([]string, error)
|
||||
```
|
||||
|
||||
### 6.4 Security
|
||||
|
||||
- Whitelist Telegram User IDs в конфиге
|
||||
- Валидация всех входящих команд
|
||||
- Rate limiting через git sync intervals
|
||||
|
||||
---
|
||||
|
||||
## 7. MVP Success Criteria
|
||||
|
||||
**Функциональные:**
|
||||
|
||||
- ✅ Создание заметки за < 2 секунды
|
||||
- ✅ Git sync работает в фоне без блокировок
|
||||
- ✅ Fuzzy search находит заметки по частичному имени
|
||||
- ✅ Только авторизованные пользователи имеют доступ
|
||||
|
||||
**Технические:**
|
||||
|
||||
- ✅ Graceful shutdown без потери данных
|
||||
- ✅ Логирование всех операций
|
||||
- ✅ Retry logic для git операций
|
||||
- ✅ Читаемые имена файлов
|
||||
|
||||
**Ограничения MVP:**
|
||||
|
||||
- Один пользователь (легко расширить до нескольких)
|
||||
- Только текстовые сообщения
|
||||
- Базовое форматирование без LLM
|
||||
- Локальный git (без конфликт-резолюции)
|
||||
|
||||
---
|
||||
|
||||
## 8. Roadmap после MVP
|
||||
|
||||
**v0.2:** YandexGPT интеграция для улучшенного форматирования
|
||||
**v0.3:** Поддержка голосовых сообщений + транскрипция
|
||||
**v0.4:** Векторный поиск по заметкам
|
||||
**v0.5:** Quartz автопубликация
|
||||
**v1.0:** Multi-user support с персональными vaults
|
||||
Reference in New Issue
Block a user