// для инженеров и технических заказчиков
LetterBot — это не скрипт на коленке
Внутри — локальная система с чёткими контурами запуска, проверки, диагностики и релиза. Ниже — честный технический разбор без маркетинга.
// архитектурный обзор
Что внутри: слои системы
SELF-HOSTED RUNTIME
Весь код запускается на машине пользователя. Нет backend-серверов LetterBot. Нет регистрации. Нет аккаунтов. Запуск через letterbot.bat или Python-окружение.
DETERMINISTIC CORE
Ядро приоритизации работает без внешних AI: анализ типа письма, суммы, дедлайна, вложения, частотных аномалий отправителя. Priority v2 — скоринговый движок с reason codes.
OPTIONAL LLM LAYER
GigaChat (Sber) и Cloudflare Workers AI — опциональные усилители. Если недоступны — система не падает, а переходит в DEGRADED_NO_LLM. OpenAI не поддерживается.
SQLITE AS STATE
Единственное хранилище — data/mailbot.sqlite на диске пользователя. Схема проверяется на старте. Backup — просто скопировать файл.
EVENT MODEL
Система мыслится как event-driven runtime. События: priority_v2_computed, notification_sla_degraded, relationship_health_updated, trust_score_updated. Events — долгосрочная память.
TELEGRAM-FIRST UX
Telegram — не просто канал уведомлений. Постоянный telegram_inbound_polled/processed — двусторонняя операционная поверхность. Приоритеты, снуз, команды.
READ-ONLY COCKPIT
Локальный web UI на 127.0.0.1:8787. Маршруты: /, /api/dashboard, /archive, /health, /events, /doctor, /commitments. Не подключается к интернету.
DOCTOR / VALIDATE-CONFIG
Отдельная поверхность диагностики — /doctor в web и в CLI. Автобутстрап конфигов: если config.ini или accounts.ini отсутствуют, система подсказывает команду.
ONE-FOLDER WINDOWS RELEASE
ZIP-архив на GitHub Releases. Распаковать → заполнить accounts.ini и settings.ini → запустить letterbot.bat. Python не нужен — dist включает runtime.
RELEASE VERIFICATION
Встроенная верификация релиза на старте. Определяет версию, проверяет целостность. Логирует результат явно — нет тихих ошибок.
2-FILE CONFIG MODE
Конфигурация разделена: settings.ini — общие параметры, accounts.ini — секреты и аккаунты. Зрелее, чем monolithic config-файл.
IMAP HEALTHCHECK
mail_account_healthcheck по каждому ящику на старте и в процессе. При сбоях — backoff_minutes, cooldown_reason, imap_account_skipped_backoff. Не долбит сервер бесконечно.
// живой старт
Как выглядит запуск в реальном логе
Фрагмент реального лога запуска. Видно: проверка конфига, healthcheck по обоим ящикам, инициализация Telegram, политика первого запуска.
[2026-03-13 08:01:02] INFO config_mode Using new 2-file config mode (settings.ini + accounts.ini)
[2026-03-13 08:01:03] INFO db_schema_check emails schema OK · priority_reason persistence OK
[2026-03-13 08:01:03] INFO telegram_startup_validation passed
[2026-03-13 08:01:04] INFO mail_account_healthcheck account=work@company.ru status=OK latency=142ms
[2026-03-13 08:01:04] INFO mail_account_healthcheck account=personal@yandex.ru status=OK latency=98ms
[2026-03-13 08:01:05] WARN ingest_policy allow_prestart_emails=false bootstrap_window_hours=24 bootstrap_max=50
[2026-03-13 08:01:05] INFO llm_provider mode=heuristic (no LLM configured)
[2026-03-13 08:01:05] INFO auto_priority_gate allow_auto_priority=false gates_failed=[corrections_count<50, shadow_accuracy<0.82]
[2026-03-13 08:01:06] INFO web_cockpit started http://127.0.0.1:8787 routes=[/,/archive,/health,/events,/doctor,/commitments]
[2026-03-13 08:01:06] INFO system_ready polling_interval=60s accounts=2 telegram=active
[2026-03-13 08:02:06] INFO imap_poll account=work@company.ru new=3 duplicates=0
[2026-03-13 08:02:07] INFO email_body_segmentation quoted_removed=true signature_removed=true
[2026-03-13 08:02:07] INFO attachment_extract type=xlsx chars=1405
[2026-03-13 08:02:08] INFO priority_v2_computed score=0.91 priority=URGENT reasons=[PRIO_AMOUNT_BASE,PRIO_DEADLINE_1D,PRIO_ATTACHMENT_XLSX]
[2026-03-13 08:02:08] INFO telegram_notification_sent chat_id=*** msg_id=4821 priority=URGENT
// движок приоритизации
Priority v2: скоринг, а не магия
Приоритет — не «AI решил». Это детерминированный скоринг с объяснимыми причинами и shadow-движком качества.
КАК РАБОТАЕТ PRIORITY V2
INVOICE, CONTRACT, SECURITY_ALERT, PRICE_LIST, NEWSLETTER, NOTIFICATION — классификация типа определяет базовый вес
Детектируются ключевые слова дедлайна. «До завтра», «к среде», «срок оплаты» — конкретные паттерны с весами
Суммы извлекаются из тела письма и вложений (PDF, XLSX). Пороги настраиваются в конфиге.
Всплеск активности от отправителя (3× выше нормы) — аномальный сигнал, повышает приоритет
QUALITY GATES И SHADOW ENGINE
shadow_accuracy, preview_accept_rate, commitment_fulfillment_rate. Ручные коррекции пользователя становятся обучающим сигналом.
allow_auto_priority=false до тех пор, пока shadow_accuracy < 0.82 и corrections_count < 50. Система не включает автодействия, пока не уверена в качестве.
Контролируемые метрики качества
// надёжность
Graceful degradation: честнее, чем зелёный экран
Большинство AI-ботов при потере LLM либо молчат, либо продолжают притворяться. LetterBot честно переходит в деградированный режим и остаётся полезным.
llm_provider: "heuristic"— детерминированное ядро- IMAP polling продолжается
- Telegram inbound активен
action_lineсохраняется- Пользователь получает уведомление о деградации
- При восстановлении LLM — автоматический выход из режима
LOG: ПЕРЕХОД В DEGRADED MODE
[08:15:44] WARN system_mode_change NORMAL → DEGRADED_NO_LLM
[08:15:44] INFO degraded_capabilities
disabled: [llm_preview, auto_priority,
ai_digest, anomaly_detection]
active: [imap_poll, telegram_inbound,
heuristic_priority, action_line]
[08:15:44] INFO telegram_notification ⚠ Система перешла в режим деградации (LLM недоступен). Базовые уведомления продолжают работу.
[08:22:31] INFO llm_provider_recovery provider=gigachat status=OK
[08:22:31] INFO system_mode_change DEGRADED_NO_LLM → NORMAL
// наблюдаемость
Observability до уровня SLA доставки
Для пользовательского email-AI наблюдаемость на уровне SLA — редкость. LetterBot мониторит не только письма, но и состояние каналов доставки.
SLA ДОСТАВКИ
notification_sla_degraded с причинами: delivery_rate_below_slo, latency_p90_exceeds_slo, error_spike. Доставка сама является объектом мониторинга.
RELATIONSHIP HEALTH
relationship_health_computed, trust_score_updated, relationship_anomaly_none. Долгосрочная модель взаимодействий с контрагентами. Silent-partner risk — когда контакт перестал отвечать.
EVENTS BACKFILL
events_backfill_started — система восстанавливает пропущенные события. Event stream — долгосрочная наблюдаемая память, а не просто лог.
WEEKLY DIGEST ANALYTICS
Еженедельный дайджест: общее количество писем, счета (с суммами), договоры, просроченные обязательства, silent-partner risks. Дедупликация по chat_id между аккаунтами.
IMAP BACKOFF METRICS
При IMAP-сбоях: next_retry_at, backoff_minutes, cooldown_reason. Не бесконечное долбление — управляемый backoff.
DOCTOR ENDPOINT
http://127.0.0.1:8787/doctor — forensic поверхность. Состояние всех систем, конфигурация, health ящиков, качество решений — в одном месте.
// конфигурация
2-file конфигурация: settings.ini + accounts.ini
Вся конфигурация — в INI-файлах. Никакого YAML, JSON или облачных настроек. Понятно, редактируется в любом текстовом редакторе.
[general]
polling_interval_sec = 60
bootstrap_window_hours = 24
bootstrap_max_messages = 50
allow_prestart_emails = false
[priority]
allow_auto_priority = false
min_shadow_accuracy = 0.82
[llm]
# Опционально. OpenAI не поддерживается.
llm_provider = none
# Варианты: gigachat, cloudflare_workers_ai
[digest]
daily_time = 09:00
weekly_day = monday
[telegram]
bot_token = YOUR_BOT_TOKEN
[account.work]
imap_host = imap.yandex.ru
imap_port = 993
username = work@company.ru
password = APP_PASSWORD
telegram_chat_id = -100123456789
[account.personal]
imap_host = imap.mail.ru
imap_port = 993
username = me@mail.ru
password = APP_PASSWORD
telegram_chat_id = 123456789
// для заказчиков
Почему это важно рынку
Предсказуемый запуск
IMAP healthcheck, Telegram validation, schema check — всё до первого письма. Нет тихих отказов.
Понятная эксплуатация
Два ini-файла. letterbot.bat. Локальный /doctor. Никаких docker-compose, никаких облачных консолей.
Инженерная честность
Деградация явная. Причины приоритетов видны. Shadow accuracy считается. Не притворяется умнее, чем есть.
Открыт для code review
Весь исходный код на GitHub под AGPL-3.0. Читайте, форкайте, аудитируйте. Issues и PR приветствуются.