- web_search: серверный поиск OpenRouter (openrouter:web_search, для Gemini — Google Search) в отдельном агенте Mastra без памяти; основному агенту — сводка со ссылками, она остаётся у него до конца ответа. WEB_SEARCH=false — выключить - page_images: картинки со страницы (og:image, крупные <img> с alt), без иконок, логотипов и заглушек - attach_media / attach_file: вложения по ссылке (фото, GIF, видео, аудио, файлы) и файлы, составленные агентом; сборщик в requestContext, байты не попадают в результаты инструментов и Memory - Бот шлёт вложения после текста: фото и видео альбомом, не принял Telegram как медиа — файлом; пишет в архив - libs/public-fetch: скачивание ссылок модели только из публичного интернета (без внутренней сети и редиректов туда), до 20 МБ и 15 секунд - Ключи инструментов совпадают с id из промптов (модель видела readChatMessages, а промпт звал read_chat_messages) - MAX_AGENT_STEPS 6: поиск → картинки страницы → прикрепить → ответ Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.9 KiB
4.9 KiB
Boltun AI
Telegram-бот на Node.js + TypeScript + grammY, AI через Mastra (OpenRouter — по умолчанию Gemini 3.8 Flash, или DeepSeek напрямую). Хранилище — SQLite (better-sqlite3).
Команды
pnpm dev— seed личностей + запуск с автоперезагрузкой (читает.env)pnpm seed/pnpm seed:dev— синхронизировать личности изconstants/personas.ts+prompts/personas/*.mdс БДpnpm import-history:dev <result.json>— загрузить экспорт чата из Telegram Desktop с диска (в проде —/importботу)pnpm typecheck— проверка типовpnpm build/pnpm start— сборка вdist/и запуск- Node.js 24 (
.nvmrc); Mastra требует Node >= 22.13
Архитектура
Зависимости идут сверху вниз: bot → services → repositories → libs. Сборка всех слоёв (composition root) — в src/index.ts.
src/
index.ts — создание зависимостей и запуск бота
config.ts — чтение и валидация env
types.ts — доменные типы (Persona, ChatMessage, ChatMember)
constants/ — список личностей (id, название) и прочие константы
scripts/ — отдельные точки входа (seed, import-history)
libs/ — инфраструктура без бизнес-логики (SQLite и миграции, промпты, форматирование Telegram, парсер экспорта, загрузка из интернета)
repositories/ — только SQL и маппинг строк в доменные типы, по репозиторию на таблицу
services/ — бизнес-логика; зависят от репозиториев, не знают про grammY
assistant/ — AI на Mastra: агент, память (Memory), промпты, tools
bot/ — grammY: сборка бота, общие хелперы ответа, скачивание фото
handlers/ — тонкие Composer'ы: разбор команды → вызов сервиса → ответ
prompts/ — тексты промптов: system.md (правила бота), web-search.md (агент поиска) и personas/<id>.md
- Вложения ответа (attach_media, attach_file) инструменты складывают в сборщик из
requestContext, бот отправляет их после текста; байты файлов не попадают в результаты инструментов и Memory. - Ссылки, которые выбрала модель, скачиваем только через
libs/public-fetch.ts(без внутренней сети, с лимитами). - Память разделена: архив чата (
messagesв SQLite бота, читается инструментами) и контекст диалога (Mastra Memory,data/memory.db, тред на чат)./clearчистит только контекст. - Где Mastra закрывает потребность (память, бюджет токенов, фильтры, процессоры) — используем Mastra, а не своё.
- Промпты храним только в
prompts/*.md, не в коде. - Личности не редактируются из чата: источник правды — код и
prompts/, в БД их кладётseed. - Изменения схемы БД — через
migrateвlibs/db.ts(у пользователей уже есть базы). - Каждый модуль — фабрика
createX(deps), тип экспортируется какReturnType<typeof createX>. - Хендлеры не ходят в репозитории напрямую — только через сервисы.
- Правила доступа (только админы) — в
bot/create-bot.tsчерезbot.filter.
Стиль кода
- Пиши функционально: стрелочные функции и фабрики (
const createX = (...) => ({ ... })), без классов. - Не используй ключевое слово
function— толькоconst fn = (...) => .... - Не используй
let(иvar) — толькоconst; вместо циклов с мутацией —map/filter/reduce/рекурсия. - Отделяй пустой строкой объявления констант и логические блоки друг от друга.
- Импорты локальных файлов — с расширением
.js(ESM,module: NodeNext). - Тексты для пользователей бота и комментарии — на русском.