boltun-ai/README.md

Boltun AI

Telegram-бот для групповых чатов с AI-личностями. Стек: Node.js, TypeScript, grammY, Mastra (DeepSeek напрямую или через OpenRouter), SQLite.

Возможности

• Отвечает только администраторам из ADMIN_IDS, остальных молча игнорирует.
• Вопросы: /ask <вопрос>, упоминание @бота, ответ на сообщение бота, в личке — любое сообщение.
• Контекст из чата: бот сохраняет сообщения чата в SQLite (последние HISTORY_LIMIT на чат). Попросите «посмотри последние 100 сообщений и перескажи» — агент сам вызовет инструмент read_chat_messages и загрузит переписку в контекст. Если задать /ask ответом на чьё-то сообщение, оно тоже попадёт в контекст.
• Участники: бот запоминает имя, фамилию и ник каждого, кто пишет в чат (и тех, кого упомянули по имени-ссылке). Можно спрашивать «что писал @ivan?», «что думает Иван про выручку?», «кто тут самый активный?» — агент найдёт человека по нику или имени (инструменты list_chat_members, read_member_messages) и обращается к людям по имени.
• Личности: задаются в коде, из чата не редактируются. Сейчас одна — boltun (Dirty D).
  • /personas — список и выбор кнопками
  • /persona <id> — выбрать

Промпты и личности

• prompts/system.md — общие правила бота (формат ответа, инструменты). Читается при старте.
• prompts/personas/<id>.md — промпт личности; список личностей (id и название) — в src/constants/personas.ts.
• pnpm seed синхронизирует личности с БД (добавляет, обновляет, удаляет лишние). В Docker seed выполняется при каждом старте контейнера, локально — в pnpm dev.

Поменял промпт — перезапусти бота (или pnpm seed + перезапуск).

Telegram Bot API не отдаёт историю чата задним числом: бот видит только сообщения, пришедшие после его добавления. Чтобы он видел все сообщения группы, отключите privacy mode в @BotFather (/setprivacy → Disable) до добавления в группу или сделайте бота админом группы.

Запуск локально

nvm use            # Node 24
pnpm install
cp .env.example .env   # заполнить BOT_TOKEN, ADMIN_IDS и DEEPSEEK_API_KEY (или OPENROUTER_API_KEY)
pnpm dev

Свой Telegram ID можно узнать, написав боту /whoami в личку.

Переменные окружения

Переменная	Обязательна	Описание
BOT_TOKEN	да	токен от @BotFather
ADMIN_IDS	да	Telegram ID админов через запятую
DEEPSEEK_API_KEY	да*	ключ DeepSeek — модель идёт напрямую в api.deepseek.com
OPENROUTER_API_KEY	да*	ключ OpenRouter — альтернатива DeepSeek напрямую
AI_MODEL	нет	модель Mastra model router <провайдер>/<модель>. По умолчанию deepseek/deepseek-flash, если задан DEEPSEEK_API_KEY, иначе openrouter/deepseek/deepseek-v4-flash. Пример посильнее: deepseek/deepseek-v4-pro

* нужен ключ того провайдера, чья модель выбрана; бот проверяет это при старте. | DB_PATH | нет | путь к SQLite, по умолчанию data/bot.db (в Docker — /app/data/bot.db) | | HISTORY_LIMIT | нет | сколько сообщений на чат хранить, по умолчанию 2000 |

Деплой (Dokploy)

Приложение собирается из Dockerfile (Build Type: Dockerfile). Бот работает через long polling — домен и порты не нужны, достаточно одной реплики.

1. Создать проект и приложение, источник — этот git-репозиторий, ветка main.
2. Build Type — Dockerfile.
3. Environment — переменные из таблицы выше.
4. Volumes — volume, смонтированный в /app/data (там SQLite-база, иначе история и личности пропадут при передеплое).
5. Deploy.