SELF-HOSTED RUNTIME
Весь код запускается на машине пользователя. Нет backend-серверов LetterBot. Нет регистрации. Нет аккаунтов. Запуск через letterbot.bat или Python-окружение.
TECHNICAL DEEP DIVE · v28.0.0
[INFO] // для инженеров и технических заказчиков
LetterBot — это не скрипт на коленке
Внутри — локальная система с чёткими контурами запуска, проверки, диагностики и релиза. Ниже — честный технический разбор без маркетинга.
[INFO] // архитектурный обзор
Что внутри: слои системы
Короткий ответ: LetterBot — event-driven локальный runtime с детерминированным ядром приоритизации, опциональным LLM-усилением, SQLite как единственным хранилищем состояния и Telegram как основным UX-контуром.
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. Не долбит сервер бесконечно.
[OK] // живой старт
Как выглядит запуск в реальном логе
Фрагмент реального лога запуска. Видно: проверка конфига, healthcheck по обоим ящикам, инициализация Telegram, политика первого запуска.
[2026-03-13 08:01:02] INFO letterbot_startup version=28.0.0 [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
[WARN] // движок приоритизации
Priority v2: скоринг, а не магия
Приоритет — не «AI решил». Это детерминированный скоринг с объяснимыми причинами и shadow-движком качества.
Как работает Priority v2
INVOICE +0.4
INVOICE, CONTRACT, SECURITY_ALERT, PRICE_LIST, NEWSLETTER, NOTIFICATION — классификация типа определяет базовый вес.
PRIO_DEADLINE_1D +0.35
Детектируются ключевые слова дедлайна. «До завтра», «к среде», «срок оплаты» — конкретные паттерны с весами.
PRIO_AMOUNT_BASE +0.2
Суммы извлекаются из тела письма и вложений (PDF, XLSX). Пороги настраиваются в конфиге.
PRIO_FREQ_SPIKE_3X +0.25
Всплеск активности от отправителя (3× выше нормы) — аномальный сигнал, повышает приоритет.
Quality Gates и Shadow Engine
Shadow Priority Engine — параллельный движок качества. Система считает shadow_accuracy, preview_accept_rate, commitment_fulfillment_rate. Ручные коррекции пользователя становятся обучающим сигналом.
Quality Gates защищают от плохих решений. allow_auto_priority=false до тех пор, пока shadow_accuracy < 0.82 и corrections_count < 50. Система не включает автодействия, пока не уверена в качестве.
Контролируемые метрики качества
corrections_total
ручные исправления приоритета
shadow_accuracy
точность теневого движка
preview_accept_rate
принятие предложенных действий
commitment_fulfillment_rate
исполнение обязательств
[ERR] // надёжность
Graceful degradation: честнее, чем зелёный экран
Большинство AI-ботов при потере LLM либо молчат, либо продолжают притворяться. LetterBot честно переходит в деградированный режим и остаётся полезным.
В DEGRADED_NO_LLM режиме:
- llm_provider: «heuristic» — детерминированное ядро
- IMAP polling продолжается
- Telegram inbound активен
- action_line сохраняется
- Пользователь получает уведомление о деградации
- При восстановлении LLM — автоматический выход из режима
Явно отключается в деградации:
LLM-preview, auto-priority, дайджесты с AI-нарративом, anomaly detection. Всё — с явным указанием причины в логе.
LOG: ПЕРЕХОД В DEGRADED MODE
[08:15:44] ERROR llm_provider_check provider=gigachat status=timeout
[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
[OK] // наблюдаемость
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 ящиков, качество решений — в одном месте.
[INFO] // конфигурация
2-file конфигурация: settings.ini + accounts.ini
Вся конфигурация — в INI-файлах. Никакого YAML, JSON или облачных настроек. Понятно, редактируется в любом текстовом редакторе.
settings.ini — общие параметры
# Общие настройки LetterBot [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
accounts.ini — аккаунты и секреты
# Аккаунты и секреты [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
Если конфиг отсутствует — система не падает молча. Автобутстрап выводит список нужных файлов и Windows-команду для их создания из шаблона. Порог первого запуска минимален.
[INFO] // для заказчиков
Заказчики у фрилансеров покупают не AI-лозунги, а надёжность запуска и понятную эксплуатацию. Им нужно: продукт стартовал, не молчит, честно показывает ошибки и не требует лишней инфраструктуры.
Предсказуемый запуск
IMAP healthcheck, Telegram validation, schema check — всё до первого письма. Нет тихих отказов.
Понятная эксплуатация
Два ini-файла. letterbot.bat. Локальный /doctor. Никаких docker-compose, никаких облачных консолей.
Инженерная честность
Деградация явная. Причины приоритетов видны. Shadow accuracy считается. Не притворяется умнее, чем есть.
Открыт для code review
Весь исходный код на GitHub под AGPL-3.0. Читайте, форкайте, аудитируйте. Issues и PR приветствуются.