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

53 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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