Как mintbot обращается с файлами¶

Когда вы отправляете своему агенту mintbot фотографию, документ, голосовое сообщение, таблицу, скриншот или PDF — через Telegram, веб-панель или API — файл не проходит через центральную инфраструктуру mintbot по пути к языковой модели. Он приземляется прямо на VPS вашего собственного агента, остаётся там столько, сколько вы захотите, а LLM получает преобразованную копию, оптимизированную именно под него.

Это тихое проектное решение с громкими последствиями. Стоит его развернуть, потому что это одно из мест, где mintbot сильнее всего расходится с потребительским LLM-чатом.

Поток от начала до конца¶

Загрузка приходит на VPS агента. Фотография из Telegram, PDF, перетянутый в веб-панель, голосовая заметка, скриншот, вставленный в чат. Локальный API агента принимает байты, нюхает магический заголовок, чтобы понять, что это за файл на самом деле (телефоны и браузеры удивительно часто маркируют файлы неправильно), считает SHA-256 и записывает файл в каталог /var/lib/mintbot-agent/uploads/<shard>/<sha256>.<ext> на VPS вашего собственного агента. В локальный каталог попадает строка с источником (telegram / panel / api), ID загрузившего, MIME-типом и исходным именем файла.
Оригинал священен. С этого момента внутри mintbot никто сохранённый файл больше не меняет. Адаптеры, которые готовят его для LLM, выдают только рабочие копии — уменьшенные JPEG, перекодированный текст, извлечённые миниатюры. Байт в байт оригинал остаётся на диске, пока вы сами не удалите его через файловый менеджер агента. Нет центрального хранилища, нет таймера хранения, нет утечек между агентами: VPS каждого агента знает только о загрузках своего владельца.

Модель получает оптимизированную для LLM версию. Когда агент решает показать файл LLM, маленький диспетчер по MIME-типу и расширению выбирает нужный адаптер, и адаптер выдаёт блоки контента, которые модель может прочитать:

Адаптер	Что обрабатывает	Выход
Image	JPG, PNG, WebP, GIF, HEIC (iPhone), AVIF и всё остальное, что умеет открывать Pillow	Уменьшен до 1568 px по длинной стороне, перекодирован в JPEG q85, base64-inline в контексте модели
PDF	`.pdf` до 32 MB	Base64-inline как нативный PDF (модели Anthropic читают его напрямую)
Text	`.md`, `.csv`, `.json`, `.yaml`, исходный код (`.py`, `.js`, `.ts`, `.go`, `.rs`, …), логи, диффы	UTF-8 декодирован (с откатом на latin-1), inline текстом до лимита по размеру
Audio	`.mp3`, `.ogg`, `.opus`, `.m4a`, `.wav`, `.flac`	Голосовые из Telegram бот уже транскрибирует inline; прямые загрузки пока получают плейсхолдер, Whisper STT придёт следующей волной
Video	`.mp4`, `.mov`, `.webm`, `.mkv`	Пока плейсхолдер; извлечение keyframe через ffmpeg + транскрипция звука придут следующей волной
Office docs	`.docx`, `.xlsx`, `.pptx`, `.odt`, `.ods`, `.odp`	Пока плейсхолдер; нативное извлечение текста (python-docx / openpyxl / python-pptx) придёт следующей волной
Unknown	Всё остальное	Текстовый плейсхолдер: «пользователь приложил файл `<mime>`, он сохранён на диске с upload ID `<id>`» — чтобы модель могла хотя бы рассуждать о том, что было отправлено

Каждое преобразование кешируется рядом с оригиналом как <sha256>.cache/v<N>.json, так что во второй раз, когда модели нужен тот же файл, загрузка происходит мгновенно. Поднятие версии адаптера автоматически инвалидирует кеш.

В контекст модели не попадают истекающие URL. Когда изображение или PDF уходит к LLM, оно отправляется base64-inline в том же ходе — без URL, который позже может стать 404, без подписанной ссылки с таймером. Для более крупных файлов, где модели нужен только указатель, URL внутренний — https://agent<id>.<domain>/<panel_token>/api/local/uploads/<upload_id>/raw — защищённый panel token'ом вашего собственного агента и действующий до тех пор, пока файл лежит на диске.

Почему это выигрывает у потребительского LLM-чата¶

Когда вы загружаете фотографию в ChatGPT или PDF в Claude.ai, файл попадает в хранилище провайдера, привязывается к этому разговору, и политика хранения провайдера решает, когда он исчезнет. По истечении определённого срока файла уже нет, даже если вы ещё видите беседу, в которой он был. Переход с одного провайдера на другой означает начинать с нуля.

Одна типичная ловушка Telegram-бота наглядно показывает контраст. Сам Telegram хранит для каждой фотографии вечно действующий file_id, но сторонние боты, запрашивающие файл по Telegram file_id, получают временный URL, истекающий через 24 часа. Старые боты, ссылающиеся на вчерашнюю фотографию, отдают 404. mintbot решает это раз и навсегда: при первом появлении Telegram-файла он перекачивает байты через вечно действующий file_id и копирует их в архив вашего агента. С этого момента фотография — ваша.

Из такого устройства вытекают три вещи:

Файлы принадлежат вам, а не провайдеру LLM. В следующем месяце поменяете Claude на GPT-5 — история файлов уйдёт с вами, нетронутая, потому что она лежит на вашем VPS, а не в хранилище провайдера.
Можно переспросить позже. «Три месяца назад ты разбирал для меня договор — можешь сравнить его с этим новым черновиком?» работает, потому что оригинал всё ещё на диске. В потребительском чате старый файл обычно уже исчез.
Модель всегда получает версию, которую способна использовать лучше всего. Vision-модели получают уменьшенный JPEG, текстовые читатели — UTF-8, PDF-читатели — нативный PDF. Телефоны могут грузить HEIC, и это просто работает — плагин HEIF Pillow подгружается на старте, а нюхач магических байтов ловит телефоны, маркирующие загрузку как application/octet-stream.

Где управлять своими файлами¶

В верхней панели веб-интерфейса агента есть файловый менеджер. Он показывает весь VPS агента, а архив загрузок в каталоге /var/lib/mintbot-agent/uploads/ — это та часть, которую заполняют ваши разговоры. Оттуда можно:

Переименовывать, удалять или перемещать загруженные файлы
Просматривать их по дате, источнику или имени файла
Перетаскивать новые загрузки (chunked, поддерживает файлы в несколько гигабайт)
Редактировать небольшие текстовые файлы inline

Удаление файла из панели убирает как сам blob, так и строку в каталоге. Агент больше не сможет показать его LLM. Именно это и делает оригинал «вашим»: право удаления только у вас.

Итог¶

Большинство LLM-чат-продуктов относятся к вашим загрузкам как к эфемерному контексту разговора. mintbot относится к ним как к вашим данным — сохранённым на вашем VPS, принадлежащим вам, по запросу превращаемым именно в ту форму, которая нужна модели в этом ходе. Многие из наиболее интересных возможностей mintbot стоят как раз на этом фундаменте.