mintbot 如何处理文件

当你通过 Telegram、Web 面板或 API 向 mintbot 智能体发送照片、文档、语音消息、表格、截图或 PDF 时，文件会保存在你自己的智能体 VPS 上，不会存到其他任何地方。你想留多久就留多久，而 LLM 拿到的是专门为它准备的工作副本。

这是一个不起眼的设计决定，却影响深远。值得把它讲清楚，因为这正是 mintbot 与面向大众的 AI 聊天产品差别最大的地方之一。

原件原封不动地留在你的 VPS 上——模型看到的始终只是为它准备的工作副本。

完整流程

1. 文件到达智能体 VPS。 拖进 Web 面板的 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/ 文件夹，方便它在项目其他文件旁边直接处理这个文件。

2. 原件不容改动。 从这一刻起，mintbot 内部的任何环节都不会修改已存储的文件。为 LLM 做准备的适配器只会生成工作副本——缩小后的 JPEG、解码后的文本。与原件逐字节一致的文件会一直留在磁盘上，直到你删除它。没有中央存储，没有保留期限计时器，也不会在智能体之间泄露：每个智能体 VPS 只知道自己主人的文件。

3. 模型拿到为它准备的版本。 智能体把文件交给 LLM 时，一个小型分发器会根据 MIME 类型和扩展名选出合适的适配器：

   适配器	处理范围	模型拿到什么
   图片	JPG, PNG, WebP, GIF, HEIC (iPhone), AVIF, TIFF, BMP	长边缩放到 1568 px，重新编码为 JPEG q85，并直接嵌入请求。解码在一个独立的短生命周期进程中进行，内存上限按你的 VPS 规格设定，因此再大的照片也拖不慢智能体
   PDF	不超过 32 MB 的 .pdf	以原生 PDF 形式嵌入——Claude 直接读取文字和版式。更大的 PDF 留在磁盘上，由智能体自行提取文字（例如用 pdftotext）
   文本	.txt, .md, .csv, .json, .yaml, .svg, 源代码 (.py, .js, .ts, .go, .rs, …), 日志, diff	按 UTF-8 解码（失败时回退到 latin-1），最多嵌入 500 KB；更长的文件在此处截断，完整原件仍留在磁盘上
   音频	.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 中，模型下次需要这个文件时可以立即加载。适配器有变化时，缓存会自动重建。

4. 模型上下文里没有会过期的 URL。 图片或 PDF 发给 LLM 时，会直接嵌入同一个请求——不会有日后返回 404 的 URL，也没有带有效期的签名链接。如果模型只需要一个指向文件的引用，用的是内部地址 https://agent<id>.<domain>/<panel_token>/api/local/uploads/<upload_id>/raw——由你智能体自己的面板令牌保护，只要文件还在磁盘上就一直有效。

为什么这比大众 AI 聊天更好

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

Telegram 机器人的一个常见坑能让这种差别一目了然。Telegram 为每张照片保留一个永久的 file_id，但机器人拿到的下载链接只保证在大约一小时内有效。只保存这个链接的机器人，打开昨天的照片就会返回 404。mintbot 在文件到达的那一刻就把它复制进你的智能体档案库——如果你回复一张较早的照片，它会通过永久的 file_id 重新获取。从那以后，这张照片就是你的了。

由此带来三点：

• 文件属于你，而不属于 LLM 服务商。 下个月从 Claude 换到 GPT，你的文件历史也会原封不动地跟着你走，因为它们在你的 VPS 上，而不在某个厂商的存储里。
• 你可以以后再问。 “三个月前你帮我分析过一份合同——能把它和这份新草稿比较一下吗？”这样的请求行得通，因为原件还在磁盘上。换作大众聊天产品，旧文件通常早就没了。
• 模型总能拿到它最好用的版本。 视觉模型拿到缩放后的 JPEG，文本模型拿到 UTF-8，能读 PDF 的模型拿到原生 PDF。手机可以直接上传 HEIC，开箱即用——图片解码器会加载 Pillow 的 HEIF 插件，魔数检查也能识别那些把文件误标为 application/octet-stream 的手机。

在哪里管理你的文件

智能体的 Web 面板里有一个文件管理器，位于设置 → 文件管理器。它可以浏览整个智能体 VPS；位于 /var/lib/mintbot-agent/uploads/ 的上传档案库，就是你的对话不断填充的那一部分。在那里你可以：

• 浏览文件夹，下载、重命名、移动或删除文件
• 新建文件夹
• 拖放上传新文件——分块上传，单个文件最大 4 GB
• 直接在浏览器里编辑小型文本文件（最大 1 MB）

大小限制：在聊天中附加的文件最大 500 MB；Telegram 只允许机器人获取不超过 20 MB 的文件；文件管理器单个文件最大 4 GB。除此之外，唯一的上限就是你的磁盘——mintbot 始终会预留一点空闲空间，确保服务器正常运行。磁盘满了时，智能体会告诉你，并直接给出文件管理器的链接，方便你腾出空间；你也可以直接让智能体删除旧文件。

在文件管理器中删除文件，会将它从磁盘上移除，智能体也就再也无法把它展示给 LLM。正是这一点让原件真正“属于你”：只有你有权删除它。

总结

大多数 AI 聊天产品把你的上传当作用完即弃的对话上下文。mintbot 则把它们当作你的数据——存放在你的 VPS 上，归你所有，并按需转换成模型当下需要的形式。mintbot 许多更有意思的能力，都建立在这个基础之上。