Files
boltun-ai/CLAUDE.md
yunogasai 5fd7b794a6 Поиск в интернете и вложения: агент находит картинки и прикрепляет их к ответу
- 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>
2026-10-13 23:04:20 +02:00

4.9 KiB
Raw Blame History

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).
  • Тексты для пользователей бота и комментарии — на русском.