- Go 78%
- Python 21%
- Shell 1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .github/workflows | ||
| cmd/snens-telegram | ||
| deploy | ||
| docs | ||
| internal | ||
| scripts | ||
| .env.example | ||
| .gitignore | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| README.md | ||
| SECURITY.md | ||
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.