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

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

Это незаметное архитектурное решение с серьёзными последствиями. Его стоит разобрать подробно: именно здесь mintbot сильнее всего отличается от массовых ИИ-чатов.

Схема: загруженный файл сохраняется как оригинал на VPS вашего агента; адаптер, выбранный по типу файла, делает рабочую копию для LLM — Оригинал остаётся на вашем VPS нетронутым — модель видит только рабочую копию, сделанную для неё.

Путь файла от начала до конца¶

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

Если разговор идёт в проекте, агент также кладёт копию в папку uploads/ этого проекта, чтобы работать с файлом рядом с остальными файлами проекта.
Оригинал неприкосновенен. С этого момента ничто внутри mintbot не изменяет сохранённый файл. Адаптеры, которые готовят его для LLM, создают только рабочие копии — уменьшенные JPEG, декодированный текст. Оригинал, байт в байт, остаётся на диске, пока вы его не удалите. Нет центрального хранилища, нет таймера хранения, нет утечек между агентами: VPS каждого агента знает только о файлах своего владельца.

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

Адаптер	Что обрабатывает	Что получает модель
Изображение	JPG, PNG, WebP, GIF, HEIC (iPhone), AVIF, TIFF, BMP	Уменьшается до 1568 px по длинной стороне, перекодируется в JPEG q85 и встраивается прямо в запрос. Декодирование идёт в отдельном короткоживущем процессе с лимитом памяти, рассчитанным под ваш VPS, поэтому огромная фотография не может замедлить агента
PDF	`.pdf` до 32 МБ	Встраивается как полноценный PDF — Claude сам читает текст и вёрстку. Более крупный PDF остаётся на диске, и агент извлекает текст сам (например, с помощью `pdftotext`)
Текст	`.txt`, `.md`, `.csv`, `.json`, `.yaml`, `.svg`, исходный код (`.py`, `.js`, `.ts`, `.go`, `.rs`, …), логи, диффы	Декодируется как UTF-8 (с запасным вариантом latin-1) и встраивается до 500 КБ; более длинный файл обрезается на этой границе, полный оригинал остаётся на диске
Аудио	`.mp3`, `.ogg`, `.opus`, `.m4a`, `.wav`, `.flac`, `.aac`	Голосовые сообщения из Telegram и с микрофона панели приходят уже расшифрованными. Аудиофайл пока не расшифровывается автоматически — агент получает его расположение и инструкции и расшифровывает его, когда вы попросите
Видео	`.mp4`, `.mov`, `.webm`, `.mkv`, `.avi`	Пока не обрабатывается автоматически. По вашей просьбе агент устанавливает `ffmpeg` (заранее сообщив, сколько места на диске он займёт) и сам извлекает кадры или звуковую дорожку
Документы Office	`.docx`, `.xlsx`, `.pptx`, старые `.doc` / `.xls` / `.ppt`, `.odt`, `.ods`, `.odp`	Пока не обрабатываются автоматически. По вашей просьбе агент устанавливает небольшую библиотеку для чтения и извлекает текст
Неизвестный	Всё остальное	Заметка с именем, типом, размером и расположением файла на диске плюс его первые байты в шестнадцатеричном виде — этого хватает, чтобы модель распознала файл и при необходимости открыла его своими инструментами

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

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

Почему это лучше массовых ИИ-чатов¶

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

Распространённая ловушка Telegram-ботов хорошо показывает разницу. Telegram хранит постоянный file_id для каждой фотографии, но ссылка на скачивание, которую получает бот, гарантированно работает лишь около часа. Боты, которые хранят только эту ссылку, на вчерашнюю фотографию отдают 404. mintbot копирует файл в архив вашего агента сразу, как только тот приходит, — а если вы ответите на старую фотографию, заново скачает её по постоянному file_id. С этого момента фотография ваша.

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

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

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

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

Просматривать папки, скачивать, переименовывать, перемещать и удалять файлы
Создавать папки
Перетаскивать новые файлы — они загружаются частями, до 4 ГБ на файл
Редактировать небольшие текстовые файлы (до 1 МБ) прямо в браузере

Ограничения по размеру: файл, прикреплённый в чате, может весить до 500 МБ; Telegram позволяет ботам скачивать файлы только до 20 МБ; Файловый менеджер принимает до 4 ГБ на файл. Дальше единственное ограничение — ваш диск: mintbot всегда оставляет немного свободного места, чтобы сервер продолжал работать. Если диск заполнится, агент сообщит об этом и даст прямую ссылку на Файловый менеджер, чтобы вы освободили место, — или просто попросите агента удалить старые файлы.

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

Итог¶

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