Telegram-поверхность агента snens: bridge, Jev-роутер сессий, стриминг ответов
  • Go 78%
  • Python 21%
  • Shell 1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-17 20:43:47 +01:00
.github/workflows публичный релиз: убрать личное, починить найденное при аудите 2026-10-24 01:10:23 +02:00
cmd/snens-telegram публичный релиз: убрать личное, починить найденное при аудите 2026-10-24 01:10:23 +02:00
deploy публичный релиз: убрать личное, починить найденное при аудите 2026-10-24 01:10:23 +02:00
docs публичный релиз: убрать личное, починить найденное при аудите 2026-10-24 01:10:23 +02:00
internal tgbot: подписаться на видео, анимации и кружки 2026-11-04 16:41:11 +01:00
scripts test speech smoke: assert voice artifacts cleanup 2026-11-17 20:43:00 +01:00
.env.example публичный релиз: убрать личное, починить найденное при аудите 2026-10-24 01:10:23 +02:00
.gitignore публичный релиз: убрать личное, починить найденное при аудите 2026-10-24 01:10:23 +02:00
go.mod feat: add durable Telegram HTTP surface adapter 2026-10-08 21:01:06 +02:00
go.sum feat: add durable Telegram HTTP surface adapter 2026-10-08 21:01:06 +02:00
LICENSE публичный релиз: убрать личное, починить найденное при аудите 2026-10-24 01:10:23 +02:00
README.md docs: сверка установленного бинаря с коммитом через go version -m 2026-11-17 20:43:47 +01:00
SECURITY.md публичный релиз: убрать личное, починить найденное при аудите 2026-10-24 01:10:23 +02:00

snens-telegram

Telegram-поверхность агента snens: отдельный процесс, который ходит в API ядра как обычный клиент. Не плагин и не встроенный канал — снаружи ядра, со своим состоянием.

Ядро — харнесс («модель → инструмент → результат»). Здесь живёт всё, что нужно, чтобы говорить с ним из Telegram: приём сообщений, группировка пачки, стрим ответа правкой сообщения, вложения и голос, маршрутизация чатов на сессии и свои инструменты поверхности.

Telegram ──► snens-telegram ──HTTP/SSE──► snens serve ──► провайдер модели
                    │
                    └── SQLite: привязки чатов, курсоры, команды

Что умеет

  • Только личные чаты разрешённых пользователей (ALLOWED_USER_IDS). Пустой список запрещает запуск: доступ к боту — это доступ к shell машины с ядром.
  • Первое сообщение в чате создаёт сессию с поверхностью telegram.
  • Пачка сообщений собирается по чату: 800 мс тишины, максимум 3 секунды. Порядок сообщений и источник пересылки сохраняются.
  • Ответ стримится правкой одного сообщения; длинные ответы разбиваются; reasoning скрыт. Ввод во время работы передаётся агенту как steer в тот же ход.
  • /new — новая сессия (прежний ход останавливается, неотправленный ввод отменяется, история сохраняется), /stop — отменить работу, /help.
  • Фото и документы скачиваются и уходят в сессию вложениями: изображения — модели как картинки, файлы — с путём, MIME и размером. Голосовые расшифровываются (STT), если задан ключ речи.
  • Инструменты поверхности send_file, send_photo, send_voice — доступны только сессиям этой поверхности.
  • Групповой режим (опция, по умолчанию выключен): бот в доверенных чатах (ALLOWED_CHAT_IDS), отвечает на адресованное, видит контекст разговора.

Чего нет: обещаний совместимости с чем-либо, кроме ядра snens той же версии.

Быстрый старт

Нужно: Go 1.24+, запущенное ядро (snens serve, по умолчанию 127.0.0.1:7420), токен бота от @BotFather.

git clone <этот репозиторий> && cd snens-telegram
cp .env.example .env && chmod 600 .env     # вписать TELEGRAM_TOKEN и ALLOWED_USER_IDS
scripts/build.sh                          # соберёт bin/snens-telegram
bin/snens-telegram --env .env

Свой user ID узнаётся у @userinfobot. Токен ядра читается из <каталог данных snens>/api.token; если инстанс лежит в нестандартном месте, задайте SNENS_API_TOKEN_FILE.

Проверить, что всё сходится, до запуска бота:

go build ./... && go vet ./... && go test ./...

Настройка

Всё — через окружение или .env (см. .env.example с комментариями к каждой переменной). Обязательные две: TELEGRAM_TOKEN и ALLOWED_USER_IDS.

переменная дефолт что задаёт
TELEGRAM_TOKEN — (обязательна) токен бота
ALLOWED_USER_IDS — (обязательна) кому можно писать боту, через запятую
SNENS_API_URL http://127.0.0.1:7420 адрес ядра
SNENS_API_TOKEN_FILE <данные>/snens/api.token файл токена ядра
SURFACE_STATE_PATH data/surface.db SQLite состояния поверхности
ATTACHMENT_DIR data/attachments куда складывать скачанное
ALLOWED_CHAT_IDS пусто доверенные группы; пусто — групповой режим выключен
OPENROUTER_API_KEY пусто ключ речи (STT/TTS); пусто — речь выключена

Остальные (DEBOUNCE_*, GROUP_CONTEXT_*, MAX_DOWNLOAD_BYTES, модели речи) — с разумными дефолтами, менять не обязательно.

Относительные пути считаются от рабочего каталога процесса. Для сервиса задавайте абсолютные — иначе состояние уедет в другой каталог при смене WorkingDirectory.

Как сервис

deploy/snens-telegram.service — обезличенный шаблон systemd. Пути в нём через %h; поправьте ExecStart и EnvironmentFile под свою раскладку.

mkdir -p ~/.config/systemd/user
cp deploy/snens-telegram.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now snens-telegram.service
journalctl --user -u snens-telegram -f

UMask=0077 в юните важен: в состоянии поверхности лежат id чатов, а в .env — токен бота.

Обновление — скриптом, а не руками (bin/ в .gitignore, забытая сборка даёт рестарт-петлю status=203/EXEC):

scripts/build.sh --check      # go vet + go test, ничего не ставить
scripts/build.sh --restart    # собрать, атомарно подменить bin/, перезапустить юнит

Шаблон юнита в репозитории ExecStartPre не содержит: он обезличенный и не знает, откуда запускается. Если юнит работает из этого дерева, добавьте строку — пропавший бинарь соберётся на старте (и только в этом случае: устаревший молча не пересобирается):

ExecStartPre=%h/projects/snens-telegram/scripts/ensure-binary.sh

Выкатка рядом с ядром

Юнит поверхности рассчитан на работающее ядро (snens serve, по умолчанию 127.0.0.1:7420) и ссылается на его юнит в After/Wants. Core unit должен быть готов и поднят к моменту старта поверхности; готовность проверяется по факту — порт слушается, файл токена ядра читается, — отдельного согласования выкатка поверхности не требует.

Подмена bin/snens-telegram под работающим поллером не рушит процесс (он держит старый inode), но для прода предпочтителен явный стоп: два поллера на один токен конфликтуют, и окно простоя лучше делать видимым.

systemctl --user stop snens-telegram
scripts/build.sh                      # собрать и атомарно заменить bin/
systemctl --user start snens-telegram

Если код не менялся, пересобирать не обязательно: сверьте установленный бинарь с сборкой текущего коммита и, при совпадении, ставьте его как есть.

go build -o /tmp/snens-telegram ./cmd/snens-telegram
cmp -s /tmp/snens-telegram bin/snens-telegram && echo same

Ещё дешевле — спросить сам бинарь, из какого коммита он собран (сборка при этом не нужна; +dirty означает дерево с незакоммиченными правками):

go version -m bin/snens-telegram | grep '^\s*mod'

Разработка

go build ./...                  # сборка
go vet ./...                    # подозрительные места
go test ./... -count=1          # тесты
go test -race ./...             # гонки (адаптер держит состояние под мьютексами)
gofmt -l .                      # форматирование

Сквозные проверки (scripts/*-smoke.py) поднимают настоящий HTTP/SSE сервер ядра, мок-провайдера модели и эмулятор Telegram Bot API — платных запросов и доступа к Telegram не требуют. Требуют собранный бинарь ядра: путь задаётся SNENS_BIN.

Слои:

путь что
cmd/snens-telegram сборка процесса: конфиг, клиент ядра, бот, адаптер
internal/tgbot транспорт: telebot, входящие, отправка, лимиты Telegram
internal/api клиент ядра /v1: сессии, сообщения, история, вложения
internal/surface адаптер: привязки чатов, группировка, стрим, команды, события
internal/media входящие вложения и речь (скачивание, STT)
internal/outbound исходящие вложения и TTS, инструменты send_*
internal/render Telegram-разметка: разбиение длинных ответов, форматирование
internal/speech клиент OpenAI-совместимого STT/TTS
internal/config чтение настроек из окружения

Ограничения

  • Telegram Bot API не даёт идемпотентной отправки: гарантии exactly-once при падении между доставкой и сохранением состояния невозможны. Повторы HTTP-команд к ядру идут с прежними command_id, SSE восстанавливается по курсору.
  • Один процесс на токен бота: два поллера на один токен конфликтуют.
  • Групповой режим требует прав администратора в чате (или выключенного privacy mode), иначе Telegram не отдаёт боту все сообщения.

Лицензия

MIT, см. LICENSE.