aichat-go

Каждое входящее сообщение Telegram проходит следующий путь:

1. Приём webhook — POST /webhook/{tg_api_key} поступает на публичный HTTP-сервер (:8080). API-ключ в URL маршрутизирует к нужному бандлу проекта.
2. Нормализация в Gateway — TelegramUpdate преобразуется в domain.Message с извлечением текста, подписи, файлов и информации об отправителе.
3. Загрузка состояния — Состояние чата загружается из PostgreSQL по составному ключу (chat_id, project_id).
4. Проверка команд — /start сбрасывает состояние и возвращает приветствие. /debug переключает режим отладки.
5. Сбор файлов — Вложения накапливаются в состоянии. Файлы без текста получают немедленное подтверждение без LLM-вызовов.
6. Диспетчеризация по этапу — На основе вычисленного состояния (CurrentStage()) сообщение направляется соответствующему обработчику этапа.
7. Сохранение состояния — Обновлённое состояние записывается обратно в PostgreSQL.
8. Сброс таймера — Таймер follow-up сбрасывается на шаг 0 для данного чата.

cmd/
  bot/         # Основной бинарник бота
    main.go     # Связка: БД, LLM по уровням, бандлы проектов, HTTP-сервер
    config.go   # Загрузка JSON-конфига с fallback на env-переменные
  crawler/     # CLI-индексатор базы знаний
    main.go     # Подкоманды: init-project, seed, add-urls, register
  cli/         # Локальный readline-интерфейс для тестирования
    main.go     # Тот же конвейер агента, файловый CRM-вывод

internal/
  domain/      types.go        # Stage, Message, ChatState, Lead, Block
  agent/       agent.go        # Точка входа HandleMessage
                toolagent.go    # Tool-calling цикл, диспатч инструментов, системный промпт
                commands.go     # /start, /debug
                lead_commands.go # Группа лидов: /prompt, /stats
                trace.go        # Записи трейса по ходу для отладки
  llm/         toolcaller.go               # Интерфейс ToolCaller, типы Block/Message
                toolcaller_anthropic.go     # Бэкенд Anthropic Messages API
                toolcaller_openai.go        # Бэкенд OpenAI tools spec (включая OpenRouter)
                toolcaller_chain.go         # Цепочка нескольких бэкендов с fallback
                tiered.go       # TieredClient (слоты extract / embedding)
                openai.go       # OpenAI-совместимый провайдер (extract, embeddings)
                claude.go       # Claude провайдер (extract)
                embedding_adapter.go # Форматирование текста для конкретных моделей
  search/      hybrid.go       # DBSF-слияние Qdrant (dense + BM25)
                bm25.go         # BM25Encoder, Tokenize
  db/          postgres.go     # Реализация PostgreSQL
  gateway/     telegram.go     # Нормализация TelegramUpdate
  telegram/    client.go       # HTTP-клиент, retry при 429
  crm/         telegram.go     # TelegramCRM: резюме + история + медиа
  timer/       timer.go        # Планировщик, последовательности, LLM-классификация
  metrics/     metrics.go      # Определения метрик
                llm.go          # Обёртка InstrumentedLLMClient
  crawler/     pipeline.go     # Возобновляемый 4-фазный конвейер
                chunker.go      # Семантический + простой чанкинг
                indexer.go      # Upsert в Qdrant
  i18n/        i18n.go         # T(), Tf(), встроенные локали
                locales/    ru.json, en.json

migrations/  001-013 (последние: 012_chat_history_blocks.sql, 013_drop_3stage_remnants.sql)
nix/         module.nix, example-configuration.nix
flake.nix    Makefile

Finished=true записывается в базу данных до отправки в CRM, а LeadSent=true записывается после. Это предотвращает дублирование лидов при параллельных webhook-запросах или срабатываниях таймера, читающих устаревшее состояние. Если бот падает между двумя записями, система таймеров повторяет отправку в CRM при следующем срабатывании или при перезапуске (через chatStore.ListFinishedUnsent).

Полная последовательность assistant / tool_result блоков для каждого хода хранится в chat_history.blocks (JSONB). На следующем ходе rebuildMessages воспроизводит эти блоки обратно в модель, чтобы она видела свои собственные предыдущие tool_use / tool_result обмены. Для legacy-строк, где blocks пуст, fallback — обычные поля question / reply.

Когда пользователь отправляет файл без текста, бот немедленно подтверждает получение («Принято! Дайте знать, когда закончите.») без обращения к LLM. Файлы накапливаются в ChatState.Files и прикрепляются к лиду при срабатывании send_lead.

Медиафайлы в лиде группируются по типу для наглядного представления:

• Фото + видео — отправляются как медиа-альбом (Telegram группирует их визуально)
• Документы — отправляются как альбом документов
• Голосовые / видео-заметки — отправляются поштучно (Telegram не поддерживает альбомы для них)

На первом ходе, где упоминается сбор контакта, бот отправляет кнопку Telegram request_contact вместе с ответом. Это позволяет пользователям поделиться номером телефона одним нажатием.

• Отправляется только один раз за диалог
• Полученный контакт попадает в ChatState.SharedContact (не в историю) для конфиденциальности
• Включается в передаваемый лид

Планировщик таймеров запускает тот же tool-calling цикл с синтетическим ходом [TIMER PING]. Агент сам решает, отправить ли follow-up сообщение или вызвать send_lead. На последнем интервале (24 ч) таймер передаёт лид безусловно для любого незавершённого чата — независимо от client_status — чтобы ни один лид не потерялся. Горячих клиентов с уже полученным контактом агент должен передавать раньше сам (промт подталкивает к send_lead после 1–2 пингов, если данных достаточно).

Когда срабатывает страховочная отправка, а агент сам так и не вызвал send_lead, state.LeadSummary пустой. Тогда таймер просит агента сделать резюме диалога через Agent.SummarizeForLead — одиночный Complete-вызов (без инструментов) на тире summary (дешёвый mid-тир, например gemma-4-26b-a4b-it). Он рендерит диалог как транскрипт Клиент/Бот плюс блокнот агента и выдаёт резюме на 1–2 абзаца для оператора, чтобы лид никогда не приходил пустым.

set_state(notes="...") — свободный текстовый блокнот агента. Заменил прежнюю структурированную схему contact{method,value} + extras{...}. Модель пишет обычный текст, при каждом вызове перезаписывается полностью — что не перенёс, то потерял. Соглашения живут в описании инструмента, не в схеме:

name: Виктор
contact: phone +79130001234
service: оценка квартиры
city: Барнаул
date: на следующей неделе

Блокнот рендерится в системный суффикс на каждом ходу, так что модель видит своё состояние, и он же служит входом для Agent.SummarizeForLead на 24 ч. Плоская строковая форма выбрана намеренно: слабые toolcaller-модели (например, glm-5.1) роняют закрывающие фигурные скобки на set_state с вложенными объектами — это раньше тихо теряло номера телефонов и упирало цикл в overflow-предохранитель.

После того как сработает send_lead, чат не замолкает. Клиент может продолжать писать ещё до пяти сообщений; каждое добавляется в chat_history, а существующая запись лида в CRM обновляется на месте — для Telegram это editMessageText по основному сообщению с резюме плюс editMessageMedia по прикреплённому файлу истории чата .txt. Текст резюме остаётся неизменным, но появляется подпись history updated: <ts>, чтобы оператор заметил.

Ссылки на артефакты CRM живут в отдельной таблице lead_dispatches (chat_id, project_id, provider) — одна строка на CRM. Multi-CRM поддерживается по построению: чат, отправленный одновременно в Telegram и Bitrix, получит две строки, а пост-отправочное обновление вызовет UpdateLead по каждой.

Входящие сообщения не вызывают HandleMessage напрямую. Каждый шлюз (Telegram webhook, CLI-цикл) вызывает agent.Enqueue, который сохраняет сообщение пользователя как orphan-строку в chat_history (Question заполнен, Reply пустой) и кладёт в per-chat очередь cheggaaa/mb. Одна горутина-воркер на (chat_id, project_id) разгребает очередь последовательно.

Что это даёт:

• Нет гонки двойной отправки: один воркер на чат — структурное решение проблемы конкурентных горутин, которые раньше затирали состояние и слали в CRM по два поста на одного клиента.
• Объединение всплесков: сообщения, прилетевшие пока воркер думал над предыдущим ходом, копятся в очереди и обрабатываются следующей пачкой. Модель видит один объединённый ход пользователя, а не три последовательных.
• Восстановление после краша: orphan-строки, пережившие перезапуск процесса, подбираются следующей пачкой — ни одно сообщение не теряется.

Ответы возвращаются через per-project колбэк agent.Replier (cmd/bot подключает его к tgClient.SendMessage; cmd/cli печатает в stdout). Воркеры завершаются после пяти минут простоя и заново стартуют при следующем сообщении.

• Стандартная формула BM25: IDF * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * dl/avgDL))
• Параметры: k1=1.5, b=0.75
• Токенизатор: Unicode-совместимый (кириллица + латиница), приведение к нижнему регистру, разбивка по не-буквенным/не-цифровым символам
• Хранение: словарь, IDF, avgDL, numDocs хранятся как JSONB в PostgreSQL (таблица bm25_indexes)
• Кеш в памяти: загружается из БД при первом использовании для каждого проекта, инвалидируется при обновлениях краулера

• Префикс (стабильный, кэшируемый): преамбула движка (agent.toolcaller_preamble) + prompt1 проекта + схема инструментов. Бэкенды Anthropic помечают это cache_control: ephemeral — 90% скидка на input при попадании в кэш. OpenAI / DeepSeek / GLM автоматически кэшируют длинные стабильные префиксы (~50% скидка при cached_tokens > 0).
• Суффикс (изменчивый, ломает кэш): снимок состояния на текущий ход — DeterminedURL, контакт, extras, файлы, опциональная подсказка PriceURL, ClientStatus.

Каждая цепочка ToolCaller / Provider имеет независимый retry и fallback:

Попытка 1 → rate-limit/transient? → задержка (1s + jitter) → повтор
Попытка 2 → rate-limit/transient? → задержка (2s + jitter) → повтор
Попытка 3 → rate-limit/transient? → падение далее
Не-transient ошибка? → падение далее немедленно
Все исчерпаны → AllProvidersExhaustedError

Формула задержки: 2^attempt + 10% jitter, максимум 60 с (или Retry-After провайдера, если меньше). Пул ключей ротирует API-ключи round-robin.

Классификация transient-ошибок: rate-limits (429) считаются transient. Для OpenAI-tools бэкендов мы дополнительно считаем transient встроенные ошибки и пустые массивы choices (возвращаем RateLimitError) — наблюдается, когда апстрим DeepSeek/GLM возвращает некорректный success.

Адаптеры эмбеддингов

AdaptedProvider оборачивает провайдер эмбеддингов и форматирует текст в зависимости от режима (документ или запрос). Адаптер выбирается автоматически по имени модели. Модели E5-instruct / Qwen3-Embedding получают префикс Instruct: ...\nQuery: ... для запросов. Авторазбиение по лимиту токенов: если чанк превышает лимит модели, текст разбивается по предложениям, каждая половина эмбеддится рекурсивно, и векторы усредняются + L2-нормализуются.

new-projects/{project-name}/
  1_pages/{urlhash}.json    # одна Page на URL
  2_chunks/{urlhash}.json   # []Chunk на URL
  3_embeds/{urlhash}.json   # []EmbeddedChunk на URL
  3_embeds/bm25.json        # снимок BM25-энкодера

Семантический чанкинг (по умолчанию)

Один LLM-вызов на страницу (уровень Извлечение, temp 0.1) определяет естественные тематические границы. LLM выводит якорные фразы в формате TOPIC: X | STARTS: Y. Исходный текст разрезается по обнаруженным границам, сохраняя точный текст источника без перефразирования LLM. Каждый чанк получает метку темы для эмбеддинга.

Простой чанкинг (--no-llm-chunk)

Разбивка с учётом абзацев и заголовков. Текст разбивается по двойным переносам строк и markdown-заголовкам. Короткие абзацы объединяются до maxChars (по умолчанию 1500). Чанки получают нумерованные метки тем («Part 1», «Part 2» и т.д.).

При индексации текст каждого чанка дополняется меткой темы перед эмбеддингом:

До: "Our basic plan starts at $99/month with unlimited support."
После:  "Topic: Pricing plans\n\nOur basic plan starts at $99/month with unlimited support."

Тема выступает как семантический якорь — эмбеддинг теперь захватывает тему чанка, а не только его поверхностное содержание. Запрос о «стоимости» будет лучше совпадать с чанком, привязанным к теме «Pricing plans», даже если текст чанка не содержит слова «стоимость».

Поисковые запросы не нуждаются в префиксе темы — пространство эмбеддингов выравнивается естественным образом.

# Создать новый проект и сразу заполнить базу знаний
bin/aichat-crawler init-project \
  --name myproject \
  --tg-api-key "123456:ABC-DEF" \
  --tg-lead-group -1001234567890 \
  --language en \
  --prompt1 "You are a sales consultant..." \
  --start-reply "Welcome! How can I help?" \
  --sitemap-url "https://example.com/sitemap.xml"

# Заполнить проект позднее (отдельно от создания)
bin/aichat-crawler seed \
  --project-id "uuid-from-init-output" \
  --project-name myproject \
  --sitemap-url "https://example.com/sitemap.xml"

# Добавить URL в существующий проект
bin/aichat-crawler add-urls \
  --project-name myproject \
  --urls "https://example.com/new-page1,https://example.com/new-page2"

# Установить промпты из файлов
bin/aichat-crawler set \
  --project-name myproject prompt1 @prompts/prompt1.txt

1. Сброс — Каждое входящее сообщение сбрасывает таймер для данного чата, начиная последовательность с шага 0.
2. Срабатывание — Загружается свежее состояние чата и история. Пропускается, если уже Finished + LeadSent. Иначе запускается агентский tool-calling цикл с синтетическим ходом [TIMER PING] (Agent.GeneratePing). Агент сам решает, что делать.
3. Подстраховка на последнем интервале — На последнем интервале (24 ч) планировщик передаёт лид безусловно для любого незавершённого чата, независимо от client_status. Это страховка от потери лида — горячих клиентов агент должен передавать раньше сам (промт подталкивает к send_lead после 1–2 пингов, если контакт получен), но если не вызвал, лид всё равно уходит в 24 ч с тем что собрано.
4. Сохранение — Состояние таймера записывается в PostgreSQL со временем следующего срабатывания. При перезапуске Reload() восстанавливает все активные таймеры, вычисляя оставшуюся задержку и немедленно запуская просроченные.
5. Повтор отправки лида — Если таймер обнаруживает Finished=true, LeadSent=false, он повторяет отправку в CRM вместо запуска агента.
6. Отмена — Когда пользователь отправляет новое сообщение, старый таймер отменяется (горутина завершается + запись в БД обновляется).

Безопасность горутин: Каждая пара чат/проект получает одну горутину. Проверка идентичности current == self предотвращает ситуацию, когда вытесненная горутина очищает состояние более нового таймера.

Бандлы проектов (Telegram-клиент, агент, CRM, база знаний) хранятся в карте в памяти. Новые проекты могут быть зарегистрированы в рантайме двумя путями:

• Админ-группа — команда /project_init создаёт проект, заполняет базу знаний и регистрирует бандл мгновенно. Перезапуск не требуется.
• Внутренний API — POST /api/register-project/{id} для CLI или внешних инструментов, которые заполняют БД самостоятельно.

Шаг 1: Создайте бота в BotFather, скопируйте токен.

Шаг 2: Отправьте одну команду в группе лидов админ-проекта:

/project_init myproject sitemap https://example.com/sitemap.xml 123456:AAH...token

Система проверяет токен, создаёт проект, заполняет базу знаний и отвечает с прогрессом:

> Project "myproject" created (bot: @myproject_bot). Seeding started...
> Scraping completed: 42 pages
> Chunking completed: 156 chunks
> Embeddings completed: 156 vectors
> Upload completed: 42 pages, 156 chunks indexed
> Project "myproject" init finished!
> Test the bot: https://t.me/myproject_bot
> To create the CRM group, click:
> https://t.me/myproject_bot?startgroup=connect_myproject

Шаг 3: Нажмите на deep link. Telegram откроет интерфейс создания группы с уже добавленным ботом. Бот автоматически обнаружит группу и подключит её как группу лидов. ID группы не нужен — обнаруживается автоматически через команду /start connect_{name}.

Команды группы лидов (по проекту)

Команды пользовательского чата

Три миграции в migrations/:

001_initial.sql

CREATE TABLE projects (
  id          UUID PRIMARY KEY,
  name        TEXT UNIQUE,
  tg_lead_group BIGINT,
  tg_api_key  TEXT UNIQUE,
  prompts     JSONB,
  language    TEXT DEFAULT 'ru'
);

CREATE TABLE chat_history (
  id          UUID PRIMARY KEY,
  chat_id     BIGINT,
  project_id  UUID REFERENCES projects(id),
  question    TEXT,
  reply       TEXT,
  dbinfo      JSONB,
  created_at  TIMESTAMPTZ
);

CREATE TABLE chat_states (
  chat_id     BIGINT,
  project_id  UUID REFERENCES projects(id),
  state       JSONB,
  PRIMARY KEY (chat_id, project_id)
);

002_bm25_index.sql

CREATE TABLE bm25_indexes (
  project_id  UUID PRIMARY KEY REFERENCES projects(id),
  vocab       JSONB,
  idf         JSONB,
  avg_dl      FLOAT,
  num_docs    INT,
  updated_at  TIMESTAMPTZ
);

003_timers.sql

CREATE TABLE timers (
  chat_id     BIGINT,
  project_id  UUID REFERENCES projects(id),
  step        INT,
  trigger_at  TIMESTAMPTZ,
  PRIMARY KEY (chat_id, project_id)
);

Ключевые индексы

• idx_chat_history_chat_id на (chat_id, created_at) — поиск истории
• idx_chat_states_project на (project_id) — запросы на уровне проекта
• idx_chat_states_state_gin GIN на (state) — JSONB-запросы по состоянию

type CRM interface {
    SendLead(ctx context.Context, lead domain.Lead) (string, error)
    Name() string
}

Текущая реализация: TelegramCRM. Интерфейс спроектирован для будущих CRM-бэкендов (Bitrix, AmoCRM) через паттерн диспетчера MultiCRM.

services.aichat = {
  enable = true;
  configFile = "/run/secrets/aichat-config.json";
  listenAddr = ":8080";

  # База данных
  enablePostgres = true;
  dbName = "aichat";
  postgresPort = 5432;

  # Qdrant
  enableQdrant = true;
  qdrantPort = 6333;
  qdrantDataDir = "/var/lib/qdrant";

  # Резервное копирование
  enableBackup = true;
  backupDir = "/var/backup/aichat";
  backupRetentionDays = 14;
};

Резервное копирование

• Ежедневный systemd-таймер с RandomizedDelaySec=1h
• pg_dump + снимки Qdrant
• 14-дневное хранение с автоматической очисткой

Секреты (sops-nix)

• Зашифрованы в secrets/production.yaml с использованием age-ключей
• Расшифровываются при загрузке на целевой машине с помощью SSH-ключа хоста
• Ключи: aichat_config (полный JSON-конфиг), cloudflared_creds (учётные данные туннеля)

# Развернуть изменения кода в продакшн
make prod-deploy

# SSH-туннели для доступа краулера к БД + Qdrant продакшна
make prod-tunnel
# PostgreSQL на localhost:15432, Qdrant на localhost:16333

# Заполнить проект на продакшне (при открытом туннеле)
./bin/aichat-crawler --config /tmp/config.prod-tunnel.json init-project \
  --name myproject --tg-api-key "TOKEN" --language ru \
  --no-llm-chunk --workers 1 --urls "URL1,URL2,..."

# Получить файлы трейсов с продакшна
ssh root@server "cat /var/lib/aichat/traces/{chatID}/{dialogID}.log"

После запуска бота и его доступности по HTTPS зарегистрируйте webhook в Telegram:

curl -X POST "https://api.telegram.org/bot{TG_API_KEY}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/webhook/{TG_API_KEY}"}'

URL webhook должен точно соответствовать https://{host}/webhook/{tg_api_key}, где tg_api_key — токен бота из таблицы projects. API-ключ в URL маршрутизирует входящие обновления к нужному бандлу проекта.

Требования: Go 1.22+, PostgreSQL 16, Qdrant

# Собрать все бинарники
make build
# создаёт bin/aichat-bot, bin/aichat-crawler, bin/aichat-cli

# Запустить миграции
make migrate DATABASE_URL="postgres://user:pass@localhost/aichat"

# Запустить бота с JSON-конфигом
bin/aichat-bot --config config.prod.json

# Или с переменными окружения
DATABASE_URL="postgres://user:pass@localhost/aichat" \
OPENAI_API_KEYS="sk-xxx" \
bin/aichat-bot

В продакшне используется Cloudflare Tunnel для маршрутизации HTTPS-трафика к боту без открытия портов. Туннель направляет aichat.example.com на localhost:8080 на сервере.

• Учётные данные туннеля управляются через sops-nix (зашифрованы в покое)
• Настроен в nix/production.nix
• Нет необходимости в TLS-сертификатах или настройке обратного прокси
• Webhook Telegram указывают на URL туннеля

• Группируйте метрики LLM по provider для сравнения производительности и частоты ошибок провайдеров
• Отслеживайте aichat_agent_messages_total по stage, чтобы видеть конверсию воронки (general → service_specific → final)
• Следите за aichat_timer_active_sequences как индикатором общего числа активных диалогов
• Используйте aichat_webhook_request_duration_seconds p95, чтобы замечать медленные ответы (типично: 2-5 с, включая LLM + поиск)
• Мониторьте aichat_crm_leads_total по project для отслеживания генерации лидов по арендаторам

Идентификаторы моделей используют формат "provider/model". Имя провайдера отделяется по первому символу / и сопоставляется с картой providers.

Ограничение модели extract: Должна возвращать контент в поле choices[].message.content. Модели с thinking/reasoning, использующие поле reasoning, не подходят для слота extract.

# Собрать все три бинарника
make build        # создаёт bin/aichat-bot, bin/aichat-crawler, bin/aichat-cli

# Запустить тесты
make test         # go test ./...

# Линтер
make lint         # go vet ./...

# Локальные сервисы для разработки (PostgreSQL + Qdrant через Docker)
make dev-services

# Запустить CLI-интерфейс для тестирования (без Telegram)
bin/aichat-cli --config config.dev.json --project myproject