tgdyk: Telegram как поток событий для локальных агентов

Telegram — это место, где у многих из нас живут сигналы: рабочие чаты, каналы, алерты, личные сообщения. Если вы строите агента или автоматизацию, рано или поздно возникает задача: дать инструменту глаза в вашем Telegram.

Bot API для этого не подходит. Бот — отдельная сущность: он не видит ваши диалоги, не читает каналы, на которые подписаны вы, и работает только там, куда его явно добавили. Нужна пользовательская сессия. Библиотеки вроде Telethon или gramjs решают задачу, но каждый скрипт тащит за собой клиент целиком: авторизацию, хранение сессии, реконнекты. Когда инструментов становится несколько, это превращается в дублирование одной и той же инфраструктуры.

Я написал tgdyk — маленький локальный демон, который решает ровно одну задачу: держит одну пользовательскую сессию Telegram и раздаёт живые обновления TDLib локальным инструментам в виде NDJSON.

Как это работает

Один бинарник на Rust поверх TDLib. Четыре команды:

• setup — вводите api_id, api_hash с my.telegram.org/apps, телефон и код. Один раз.
• daemon — запускает TDLib и публикует обновления через локальный Unix-сокет.
• stream — печатает сырые обновления TDLib построчно как JSON.
• doctor — проверяет TDLib, конфиг, пути и связь с демоном.

Дальше — обычная Unix-композиция:

./tgdyk stream | jq .

Только новые текстовые сообщения:

./tgdyk stream | jq -r 'select(.["@type"] == "updateNewMessage") | .message.content.text.text // empty'

На этом ответственность tgdyk заканчивается. Всё, что дальше — фильтрация, роутинг, реакция — собирается из того, что у вас уже есть: shell, jq, Python-скрипт, вызов LLM.

Зачем это агентам

Типичный сценарий: агент работает в фоне, и вам нужно, чтобы события из Telegram попадали к нему без опроса и без вашего участия. Сообщение в рабочем чате, алерт из канала мониторинга, реплай на ваш пост — всё это приходит в поток как структурированный JSON, и дальше вы решаете, что с этим делать: разбудить агента, положить в очередь, дёрнуть вебхук.

Пайплайн собирается из одной строки:

./tgdyk stream \
  | jq -c 'select(.["@type"] == "updateNewMessage")' \
  | while read -r msg; do
      # здесь ваш обработчик: скрипт, очередь, вызов агента
      echo "$msg" >> inbox.ndjson
    done

Никакого SDK, никакой привязки к языку. Если инструмент умеет читать stdin или Unix-сокет, он умеет читать ваш Telegram.

Писать эти пайплайны руками, кстати, не обязательно. Современные агенты хорошо владеют CLI и Unix-композицией — jq, потоки, редиректы, systemd-юниты. Достаточно сказать своему агенту «подпишись на канал X и складывай алерты в очередь», и он соберёт обвязку сам. tgdyk даёт ему примитив, из которого это собирается надёжно.

Дизайн-решения

Сырые обновления. tgdyk не придумывает свою схему поверх TDLib. Типы TDLib — это и есть контракт: они документированы, стабильны и покрывают всё, что происходит в аккаунте. Любая обёртка означала бы потерю информации и ещё один слой, который надо поддерживать.

Только live. tgdyk не хранит историю и не умеет replay. Если вам нужна персистентность — это одна строчка в вашем пайплайне (>> inbox.ndjson), и вы сами выбираете формат и место хранения. Единственное, что лежит на диске — стандартная локальная база TDLib с сессией и кэшем.

Локальный Unix-сокет. Никаких портов, токенов и слоя авторизации. Доступ к потоку определяется правами файловой системы. Это осознанное сужение: tgdyk — инструмент для вашей машины, а не сетевой сервис.

TDLib в комплекте. Сборка TDLib — известная боль. Релизы включают libtdjson для macOS (Intel и Apple Silicon) и Linux (x64 и arm64), так что путь от скачивания до потока — несколько команд.

Ограничения

stream отдаёт только то, что происходит после подключения — запускайте его до событий, которые хотите поймать. Демон работает в foreground: systemd, tmux или supervisor — на ваше усмотрение. И главное: это ваша пользовательская сессия. Всё, что подключается к сокету, видит ваш аккаунт целиком — относитесь к машине, где крутится демон, соответственно.

Итог

tgdyk занимает одно узкое место в пайплайне: живой мост между вашим Telegram-аккаунтом и локальными инструментами. Всё остальное — ваша композиция.

Rust, MIT, бинарные релизы для macOS и Linux: github.com/pavel-voronin/tgdyk