Files
boltun-ai/README.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

88 lines
13 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-бот для групповых чатов с AI-личностями. Стек: Node.js, TypeScript, [grammY](https://grammy.dev), [Mastra](https://mastra.ai) (OpenRouter или DeepSeek напрямую), SQLite.
## Возможности
- Отвечает **только администраторам** из `ADMIN_IDS`, остальных молча игнорирует.
- **Вопросы**: `/ask <вопрос>`, упоминание `@бота`, ответ на сообщение бота, в личке — любое сообщение.
- **Контекст из чата**: бот сохраняет сообщения чата в SQLite (последние `HISTORY_LIMIT` на чат). Попросите «посмотри последние 100 сообщений и перескажи» — агент сам вызовет инструмент `read_chat_messages` и загрузит переписку в контекст. Если задать `/ask` ответом на чьё-то сообщение, оно тоже попадёт в контекст.
- **Участники**: бот запоминает имя, фамилию и ник каждого, кто пишет в чат (и тех, кого упомянули по имени-ссылке). Можно спрашивать «что писал @ivan?», «что думает Иван про выручку?», «кто тут самый активный?» — агент найдёт человека по нику или имени (инструменты `list_chat_members`, `read_member_messages`) и обращается к людям по имени.
- **Фото**: пришли фото с подписью, где упомянут бот (в личке — просто фото), или ответь на фото через `/ask` / упоминание — модель посмотрит картинку. Нужна модель со зрением (Gemini через OpenRouter по умолчанию); DeepSeek фото не видит и честно об этом скажет.
- **Интернет и вложения**: «что нового про …», «найди фото капибары», «пришли это файлом». Агент ищет в интернете (`web_search`), достаёт картинки со страниц (`page_images`) и прикрепляет к ответу картинки, GIF, видео, аудио и файлы по ссылке (`attach_media`) или файл, который составил сам (`attach_file`). Вложения уходят после текста ответа: фото и видео — альбомом, не больше 10; не принял Telegram как фото — отправляются файлом.
- Поиск — серверный инструмент OpenRouter [`openrouter:web_search`](https://openrouter.ai/docs/guides/features/server-tools/web-search) (для Gemini — Google Search, ~$0.014 за поиск с баланса OpenRouter, других ключей не нужно). Ищет отдельный агент Mastra без памяти и возвращает основному сводку со ссылками — так найденное остаётся у агента до конца ответа. Только для моделей через OpenRouter; выключить — `WEB_SEARCH=false`.
- Ссылки из интернета бот скачивает сам: только публичные адреса (внутренняя сеть, localhost и редиректы туда запрещены), до 20 МБ, 15 секунд. Файлы в память Mastra не попадают — модели уходит только «прикреплено: фото …».
- **Память — две части**:
- *Контекст диалога* — вопросы к боту и его ответы в этом чате, хранит [Mastra Memory](https://mastra.ai/docs/memory/message-history) (`memory.db` рядом с `DB_PATH`). Подкладывается в каждый запрос, поэтому можно уточнять «а подробнее?». Самые старые реплики Mastra срезает, когда промпт не влезает в `CONTEXT_TOKEN_LIMIT`; результаты инструментов из прошлых ответов (`ToolCallFilter`) и фото в историю не попадают. `/clear` сбрасывает только контекст: в группе — сразу её, в личке с ботом — выбор чата кнопками (или `/clear <ID чата>`) с подтверждением.
- *Архив чата* — вся переписка (живая и импортированная). Модель читает его инструментами по необходимости; `/clear` его не трогает.
- `/archive` — архив чата с кнопками 🗑 для удаления сообщений и «⬅️ Раньше» для листания. В группе — её архив, в личке с ботом — список всех чатов с архивом на выбор. `/archive_del 120-130 135` — удалить пачку по номерам (в личке первым аргументом ID чата, он есть в заголовке списка), `/archive_del all` — стереть весь архив с подтверждением. Номера бывают отрицательными — так Telegram нумерует историю группы до перехода в супергруппу. Служебные команды боту в архив не пишутся.
- `/context` — что сейчас в контексте и в архиве, ID чата, видит ли бот всю переписку; `/import` — загрузить старую переписку из экспорта (см. ниже).
- **Личности**: задаются в коде, из чата не редактируются. Сейчас одна — `boltun` (Dirty D).
- `/personas` — список и выбор кнопками
- `/persona <id>` — выбрать
## Импорт старой переписки
Telegram не отдаёт ботам сообщения, написанные до их добавления, — их можно загрузить из экспорта.
1. Telegram Desktop → меню чата → «Экспорт истории чата». Сними галочки с фото, видео и файлов, формат — **«Машиночитаемый JSON»**.
2. Пришли боту `result.json` с подписью `/import` — прямо в этот чат или боту в личку (в личке бот сам поймёт, какой это чат). Можно и ответить `/import` на уже отправленный файл.
3. Бот ответит, сколько сообщений и участников добавил.
Загружаются только сообщения с текстом: стикеры, голосовые, опросы и медиа без подписи пропускаются. HTML-экспорт не подходит — в нём нет ID авторов.
- Импорт идемпотентен: повторная загрузка ничего не дублирует, уже сохранённые ботом сообщения и ники не перезаписываются.
- Хранится не больше `HISTORY_LIMIT` последних сообщений на чат — для большой истории подними лимит.
- Ников в экспорте нет, только имена: участники из экспорта находятся по имени, ник подтянется, когда человек напишет при боте.
- Файл больше 20 МБ бот скачать не может (ограничение Bot API). Тогда положи его в volume (`/app/data`) и запусти в контейнере `node dist/scripts/import-history.js /app/data/result.json` (локально — `pnpm import-history:dev result.json`).
## Промпты и личности
- `prompts/system.md` — общие правила бота (формат ответа, инструменты). Читается при старте.
- `prompts/web-search.md` — промпт агента, который ищет в интернете для `web_search`.
- `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) **до** добавления в группу или сделайте бота админом группы.
## Запуск локально
```bash
nvm use # Node 24
pnpm install
cp .env.example .env # заполнить BOT_TOKEN, ADMIN_IDS и OPENROUTER_API_KEY (или DEEPSEEK_API_KEY)
pnpm dev
```
Свой Telegram ID можно узнать, написав боту `/whoami` в личку.
## Переменные окружения
| Переменная | Обязательна | Описание |
| --- | --- | --- |
| `BOT_TOKEN` | да | токен от @BotFather |
| `ADMIN_IDS` | да | Telegram ID админов через запятую |
| `OPENROUTER_API_KEY` | да* | ключ OpenRouter; модель по умолчанию — `openrouter/google/gemini-3.8-flash` (видит фото) |
| `DEEPSEEK_API_KEY` | да* | ключ DeepSeek напрямую (api.deepseek.com); используется по умолчанию, если ключа OpenRouter нет — модель `deepseek/deepseek-flash`, только текст |
| `AI_MODEL` | нет | явная модель Mastra model router `<провайдер>/<модель>`, например `deepseek/deepseek-v4-pro` |
| `AI_IMAGE_INPUT` | нет | `true`/`false` — отправлять ли модели фото. Для моделей по умолчанию выставляется само (Gemini — да, DeepSeek — нет); для своей `AI_MODEL` по умолчанию `false` |
| `WEB_SEARCH` | нет | `true`/`false` — поиск в интернете (серверный инструмент OpenRouter, платный). По умолчанию включён для моделей OpenRouter; с другими провайдерами недоступен |
\* нужен ключ того провайдера, чья модель выбрана; бот проверяет это при старте.
| `DB_PATH` | нет | путь к SQLite, по умолчанию `data/bot.db` (в Docker — `/app/data/bot.db`) |
| `HISTORY_LIMIT` | нет | сколько сообщений на чат хранить в архиве, по умолчанию 5000 |
| `CONTEXT_TOKEN_LIMIT` | нет | бюджет токенов на весь промпт (правила, история диалога, вопрос); сверх него срезаются самые старые реплики. По умолчанию 12000 |
| `ANSWER_TOKEN_LIMIT` | нет | максимальная длина ответа в токенах, по умолчанию 1500 |
## Деплой (Dokploy)
Приложение собирается из `Dockerfile` (Build Type: Dockerfile). Бот работает через long polling — домен и порты не нужны, достаточно одной реплики.
1. Создать проект и приложение, источник — этот git-репозиторий, ветка `main`.
2. Build Type — `Dockerfile`.
3. Environment — переменные из таблицы выше.
4. Volumes — volume, смонтированный в `/app/data` (там SQLite-база, иначе история и личности пропадут при передеплое).
5. Deploy.