wiki/tasks/bytik/TZ.md

ТЗ: Telegram-бот «Байтик» 🤖

Детский ИИ-помощник для Егора (8 лет, ДР 17.04.2018) Проект: proj_bytik | Дата создания: 2026-04-14

---

1. Цель

Telegram-бот, который:

• Отвечает на вопросы ребёнка простым языком
• Присылает 1-2 раза в день энциклопедические факты (утро 7:30 MSK)
• Поздравляет с праздниками и ДР
• Работает только в одной группе (whitelist chat_id)
• Строгая детская цензура 0+

---

2. Требования к боту

2.1 Whitelist (критично)

• Разрешённый chat_id: будет прописан в .env (ALLOWED_CHAT_ID)
• Бот принимает сообщения только из этой группы
• Сообщения из ЛС и других групп — полный игнор (без ответа)
• При добавлении в новую группу — автоматически leave_chat
• Проверка: message.chat.id для text, callback_query.message.chat.id для inline

2.2 Обработка сообщений

• Получает текст от пользователя в разрешённом чате
• Отправляет промпт в LLM (OpenRouter API, Qwen 3.6-Plus)
• Получает ответ → отправляет в Telegram
• Поддерживает диалог (хранит последние 5-10 сообщений как контекст)

2.3 Системный промпт (обязателен)

Ты — Байтик, дружелюбный робот-помощник для мальчика Егора (8 лет).

Правила:
- Объясняй сложные вещи просто, с примерами, которые понятны 8-летнему
- Используй эмодзи, чтобы было весело
- Если спрашивают на русском — отвечай на русском
- Иногда (когда уместно) отвечай на простом английском, по типу "Did you know..." — это помогает учить язык
- Если вопрос про что-то тревожное (смерть, война, болезни): мягко уйди от темы, а если настаивает — скажи "Это серьёзный вопрос, лучше спроси у папы!"
- НИКОГДА не используй ненормативную лексику, страшные подробности, или взрослые темы
- Если не знаешь ответа — честно скажи, но предложи "давай поищем вместе!"
- Иногда используй смешные факты и шутки
- Будь терпелив — ребёнок может задавать один и тот же вопрос много раз
- Используй короткие ответы для детей до 12 лет, не более 200 слов

2.4 Утренняя рассылка

• Время: 07:30 MSK (04:30 UTC)
• Присылать 1 интересный энциклопедический факт
• Темы по интересам Егора: машины, самолёты, корабли (Титаник!), лего, животные, география, математика, IT, Minecraft
• Формат: текст + эмодзи, иногда картинка
• Можно иногда отправлять голосовое сообщение (через ElevenLabs TTS)

2.5 Праздники и ДР

• 17 апреля: поздравление с ДР (особое, весёлое)
• 1 января: Новый Год
• 23 февраля: День защитника Отечества
• 8 марта: Международный женский день
• 12 апреля: День космонавтики (Егор любит, будет в тему!)
• Другие: можно добавить в конфиг

2.6 Голосовые сообщения (опционально)

• Иногда факты/ответы — голосом
• ElevenLabs TTS (или Yandex SpeechKit fallback)
• Конвертация в OGG Opus (требование Telegram)

---

3. Архитектура

3.1 Технологии

• Язык: Python 3.11+
• Telegram: aiogram 3.x
• LLM: OpenRouter API (openrouter/openrouter/auto или явно openrouter/qwen/qwen3.6-plus)
• TTS (опционально): ElevenLabs API / Yandex SpeechKit
• Конфиг: .env (python-dotenv)
• Хранение диалога: JSON-файлы по user_id в data/chat_history/

3.2 Структура проекта

bytik/
├── bot.py              # Точка входа
├── config.py           # Загрузка конфига из .env
├── prompts.py          # Системный промпт + факты
├── llm.py              # Обёртка над OpenRouter API
├── tts.py              # Голосовые сообщения
├── scheduler.py        # Планировщик (рассылка + праздники)
├── chat_history.py     # Хранение контекста диалогов
├── facts.json          # Энциклопедические факты
├── holidays.json       # Праздники
├── data/
│   └── chat_history/   # JSON файлы с историей
├── .env                # Секреты
├── .env.example        # Пример
└── requirements.txt    # Зависимости

3.3 .env.example

BOT_TOKEN=<telegram_bot_token>
ALLOWED_CHAT_ID=<group_chat_id>
OPENROUTER_API_KEY=<key>
OPENROUTER_MODEL=openrouter/qwen/qwen3.6-plus
ELEVENLABS_API_KEY=<key>  # optional

---

4. Инфраструктура

• Хост: mva154 (контейнер OpenClaw) или vpn-srv
• Запуск: как Docker container (предпочтительно) или systemd service
• Бэкапы: chat_history JSON-файлы
• Логи: logs/bytik.log

---

5. Безопасность

5.1 Whitelist — ОБЯЗАТЕЛЬНО

• Все входящие сообщения проходят фильтр message.chat.id == ALLOWED_CHAT_ID
• Невалидные сообщения — молчаливый игнор
• При my_chat_member: left или добавлении в новую группу → leave_chat()

5.2 Контент-фильтр

• LLM промпт уже содержит ограничения
• Валидация ответа: если содержит мат / adult контент → не отправлять, логировать
• Можно добавить дополнительный фильтр (список запрещённых слов)

---

6. Этапы реализации

Фаза 1 (MVP)

• Бот принимает сообщения из whitelist группы
• Отправляет в LLM, получает ответ, шлёт в Telegram
• Системный промпт с детской цензурой

Фаза 2

• Утренняя рассылка (7:30 MSK)
• Праздничные поздравления
• Контекст диалога (последние N сообщений)

Фаза 3

• Голосовые сообщения (TTS)
• Картинки (генерация или подбор)

---

7. Критерии приёмки

• Бот отвечает только в разрешённой группе
• Игнорирует ЛС и другие группы
• Системный промпт блокирует взрослый контент
• Утренняя рассылка в 07:30 MSK
• Поздравление с ДР Егора (17.04)
• Ответы простые, понятные 8-летнему
• Контекст диалога сохраняется
• Логи пишутся в файл

---

8. Примечания

• День рождения Егора — 17.04.2018 (скоро 8 лет!)
• Интересы: машины, самолёты, корабли, лего, животные, география, математика, IT, Minecraft
• LLM: Qwen 3.6-Plus (OpenRouter)
• Дедлайн: фаза 1 готова к 16.04.2026 (чтобы ДР поздравить!)