跳转至

mintbot 如何处理文件

当你向 mintbot 智能体发送照片、文档、语音、表格、截图或 PDF 时——无论是通过 Telegram、Web 面板还是 API——文件在送往语言模型的路上不会经过 mintbot 的中央基础设施。它会直接落到你自己的智能体 VPS 上，想留多久就留多久；LLM 拿到的只是为它优化过的副本。

这是一个不张扬的设计决定，却带来很大的差别。值得展开讲讲，因为它是 mintbot 与消费级 LLM 聊天产品最不同的地方之一。

端到端流程

  1. 上传抵达智能体 VPS。 来自 Telegram 的照片、拖进 Web 面板的 PDF、语音备忘、粘贴进对话的截图，都会由智能体的本地 API 接收字节。它会嗅探文件的 magic header 来判断真实类型（手机和浏览器误标的情况非常常见），计算 SHA-256 哈希，然后写入智能体自己 VPS 上的 /var/lib/mintbot-agent/uploads/<shard>/<sha256>.<ext>。本地目录中还会记录一行元数据：来源（telegram / panel / api）、上传者 ID、MIME 类型和原始文件名。

  2. 原件不可随意改动。 从这一刻起，mintbot 内部不会再修改已保存的原始文件。为 LLM 准备文件的适配器只会生成工作副本：调整大小后的 JPEG、转码出的文本、提取出的缩略图。逐字节不变的原件会留在磁盘上，直到你从智能体的文件管理器里亲手删除。没有中央存储桶，没有保留倒计时，智能体之间也不会互相泄漏：每台智能体 VPS 只知道自己主人的上传。

  3. 模型拿到 LLM 友好的版本。 当智能体决定把文件展示给 LLM 时，一个小调度器会根据 MIME 类型和扩展名挑出正确的适配器，适配器再输出模型能读取的内容块：

    适配器 处理 输出
    Image JPG、PNG、WebP、GIF、HEIC（iPhone）、AVIF，以及任何 Pillow 能打开的格式 缩放到长边 1568 px，以 JPEG q85 重编码，在模型上下文中 base64 内联
    PDF .pdf ≤ 32 MB 作为原生 PDF 进行 base64 内联（Anthropic 系模型可直接读取）
    Text .md、.csv、.json、.yaml，源代码（.py、.js、.ts、.go、.rs、…），日志，diff 以 UTF-8 解码（latin-1 兜底），文本内联到大小上限
    Audio .mp3、.ogg、.opus、.m4a、.wav、.flac Telegram 语音条 bot 已经内联转写；直接上传目前是占位，Whisper STT 会在下一轮上线
    Video .mp4、.mov、.webm、.mkv 目前是占位；ffmpeg 关键帧 + 音频转写会在下一轮上线
    Office docs .docx、.xlsx、.pptx、.odt、.ods、.odp 目前是占位；原生文本抽取（python-docx / openpyxl / python-pptx）会在下一轮上线
    Unknown 其他一切 文本占位：“用户附了一个 <mime> 文件，磁盘上以上传 ID <id> 保留” —— 至少让模型能推理“用户发了什么”

    每一次转换都会缓存在原件旁边的 <sha256>.cache/v<N>.json 中。模型第二次需要同一文件时，就能瞬间载入。适配器版本升级后，缓存会自动失效。

  4. 模型上下文里不会出现会过期的 URL。 图片或 PDF 进入 LLM 时，会在同一轮里直接 base64 内联——没有以后可能变成 404 的 URL，也没有带倒计时的签名链接。对于更大的文件，或模型只需要一个指针的情况，URL 是内部地址：https://agent<id>.<domain>/<panel_token>/api/local/uploads/<upload_id>/raw。它由你自己智能体的面板 token 保护，只要文件还在磁盘上就一直有效。

为什么这比消费级 LLM 聊天体验更强

当你把一张照片上传到 ChatGPT，或者把一份 PDF 丢给 Claude.ai，文件进入的是服务商的存储，并绑定在那个会话上；什么时候消失，由服务商的保留策略决定。过一段时间文件就没了，哪怕你仍然能看到当时的对话。换一家服务商，更是一切从头开始。

一个常见的 Telegram bot 坑能很好地说明这种反差。Telegram 本身会为每张照片保留一个永久的 file_id，但第三方 bot 拿这个 file_id 去取文件时，拿到的是一个 24 小时就失效的临时 URL。 引用昨天那张照片的旧 bot 会得到 404。mintbot 一次性解决了这件事：第一次见到 Telegram 文件时，它会通过永久有效的 file_id 重新拉取字节，并复制到你的智能体归档里。从那一刻起，这张照片就是你的了。

这个设计带来三件事：

  • 文件属于你，不属于 LLM 服务商。 下个月你从 Claude 换到 GPT-5，文件历史会原封不动跟着你走——因为它在你的 VPS 上，而不是在某家厂商的存储桶里。
  • 你以后还能再问。 “三个月前你帮我分析过一份合同——能不能拿来跟这份新草稿比一比？”这是说得通的，因为原件还在磁盘上。消费级聊天里，那份旧文件通常已经没了。
  • 模型总是拿到最适合它处理的版本。 视觉模型拿到缩放后的 JPEG，文本读取者拿到 UTF-8，PDF 读取者拿到原生 PDF。手机直接传 HEIC 也能用——Pillow 的 HEIF 插件会在启动时加载，magic byte 嗅探器会抓住那些被手机误标成 application/octet-stream 的上传。

在哪里管理你的文件

智能体 Web 面板顶栏有一个 文件管理器。它能浏览整台智能体 VPS，而 /var/lib/mintbot-agent/uploads/ 这个上传归档，就是你的对话不断填充内容的地方。在那里你可以：

  • 重命名、删除、移动已上传的文件
  • 按日期、来源或文件名浏览
  • 拖拽上传新文件（分块上传，支持几 GB 的大文件）
  • 在线编辑小型文本文件

从面板删除文件会同时移除 blob 和目录中的记录。之后智能体就无法再把它展示给 LLM 了。这件事才是让原件“属于你”的关键——拥有删除权的只有你。

结语

大多数 LLM 聊天产品把你的上传当作短暂的对话上下文。mintbot 把它当作你的数据：存在你的 VPS 上，由你拥有，并按需变形成模型在那一轮最擅长处理的样子。mintbot 大部分有意思的能力，都是建在这块地基上的。