Публичный и административный Telegram-боты на YETI3 SDK

Два отдельных модуля: yeti3-telegram-public==1.0.0 и yeti3-telegram-admin==1.0.0. Общий транспорт — yeti3-telegram==0.1.0. Модули используют Engine, ModuleManifest и capability registry SDK. Транспорт автоматически устанавливается вместе с любым из модулей.

Единый сценарий SDK

python -m pip install --index-url https://engine.yeti3.ru/sdk/simple/ yeti3-sdk==0.1.2
yeti3 init my-public-bot --scenario telegram-public
cd my-public-bot
# Заполните bot.json и задайте YETI3_TELEGRAM_TOKEN
yeti3 run

Для административного бота используйте --scenario telegram-admin. Пошаговая настройка обоих вариантов ниже.

1. Создайте окружение инструмента

Python 3.12+, macOS или Linux. Запуск polling на Windows в этой версии не поддерживается.

python3 -m venv .venv-tg-tools
source .venv-tg-tools/bin/activate
python -m pip install --index-url https://engine.yeti3.ru/sdk/simple/ yeti3-telegram==0.1.0

2. Выберите сценарий

Публичный бот:

yeti3-telegram init public my-public-bot
cd my-public-bot

Или административный, в отдельной папке и с отдельным токеном:

yeti3-telegram init admin my-admin-bot
cd my-admin-bot

Каждый сценарий создаёт bot.json, README, requirements.txt и собственное окружение .venv. Версии закреплены. Повторный init не перезаписывает папку. Если установка прервалась, выполните .venv/bin/python -m pip install -r requirements.txt.

3. Заполните bot.json

Публичный бот:

{
  "role": "public",
  "title": "Мой магазин",
  "site_url": "https://example.org",
  "welcome": "Поможем выбрать товар. /site — открыть магазин",
  "admin_ids": []
}

Административный бот: укажите реальные числовые Telegram user ID. Имя пользователя @username не используется для проверки прав.

{
  "role": "admin",
  "admin_ids": [123456789]
}

Пустой список запрещает запуск административного сценария. Групповые чаты, боты и пользователи вне списка не получают административных ответов.

4. Подключите Telegram и запустите

Создайте бота в официальном @BotFather. Введите токен через менеджер секретов сервера либо в текущем bash/zsh без сохранения в истории:

read -s YETI3_TELEGRAM_TOKEN
export YETI3_TELEGRAM_TOKEN
yeti3-telegram check
yeti3-telegram run

После read вставьте токен и нажмите Enter. Команда check вызывает getMe и getWebhookInfo; run получает новые сообщения через long polling. Если у бота уже активен webhook, транспорт откажется запускаться, не удаляя webhook. Один процесс на токен. На сервере запускайте под менеджером служб с отдельным пользователем, каталогом проекта и защищённым окружением.

Проверка конфигурации без токена и без запросов к Telegram:

yeti3-telegram check --offline

Команды ботов

Публичный: /start — приветствие, /site — ссылка на сайт, /help — помощь. Административный: /status — состояние подключённого ядра, /checks — его самопроверки, /help — команды. Он не исполняет shell, не удаляет данные и не управляет другими серверами. В отдельном CLI-процессе это состояние его собственного Engine; для состояния сайта зарегистрируйте модуль в Engine самого сайта.

Подключение к существующему Engine

from yeti3_core import Engine
from yeti3_telegram_admin import Package

engine = Engine()
bot = engine.register(Package(admin_ids=[123456789]))
engine.boot()
# Ваш доверенный Telegram-транспорт передаёт update в bot.handle(update).
# Возвращается {"chat_id": ..., "text": ...} либо None при запрете доступа.
engine.shutdown()

Не публикуйте handle(update) как незащищённый HTTP endpoint: входной Update должен поступать только от доверенного Telegram-транспорта. Предлагаемый CLI получает его непосредственно от api.telegram.org по HTTPS.

Надёжность и данные

Offset входящих событий сохраняется в SQLite. Повторный update не создаёт повторной отправки. Если сеть оборвалась при sendMessage, доставка получает статус uncertain: Telegram мог уже принять ответ, поэтому автоматический повтор не выполняется. Это не гарантия exactly-once. Проверьте доставку в Telegram; не меняйте статус вручную без проверки. Подтверждённые исходящие тексты удаляются. Каталог data/ содержит очередь, CALMF и цепочку ядра; храните его вне публичной статики. В репозиторий не добавляются токен и окружение.

Проверены логика команд, ограничения доступа, дубликаты, перезапуск и ошибки транспорта. Проверка с реальными ботами требует ваших отдельных токенов; без неё публикация пакетов не означает запуск живых Telegram-ботов.

Публикация и стоимость

Рекомендуемые цены для вашей публикации: публичный модуль — 100 Φ, административный — 200 Φ за 30 дней доступа. Цены в каталоге пока не назначены. Публикация допускается только после успешной серверной проверки. Проверка автономного модуля не проверяет внешний транспорт Telegram. Установка из SDK-индекса не подменяет платную установку каталога.

Документация API: https://core.telegram.org/bots/api

Архивы для вашей проверки

Публичный бот · ZIP · Административный бот · ZIP

Архивы содержат автономные SDK-модули, манифест и тесты. Сетевой транспорт устанавливается отдельной зависимостью сценария. Платная публикация в каталоге оставлена владельцу.