1. 为什么 AI Agent 需要一个专属文件柜

1.1 Agent 的记忆困境：上下文窗口装不下一整个世界

我带的团队今年上半年接了三个跟 AI Agent 相关的项目，从客服工单分流做到内部知识助手，再到一个跨境电商的商品图处理流水线。这三个项目在架构上南辕北辙，但都在同一个地方栽过跟头：文件放在哪。Agent 每秒都在产出东西，用户上传的 PDF、模型生成的中间截图、工具调用返回的 ZIP 包、一次会话结束后要交付的 Excel 报表，这些东西如果只靠上下文窗口传来传去，很快就会撞上天花板。

上下文窗口的容量是有限资源，而且贵。把一份 8MB 的产品手册塞进对话里，既不经济也不现实，模型本身也读不完。更麻烦的是，Agent 常常是「多轮、多工具、多产物」的，第三步的工具需要读取第一步生成的图表，第五步需要把三份临时文件合并成一个交付件。这一整套流程里，真正需要进上下文的只有一句「文件在哪」的指针，而不是文件本体。这个认知转变很关键：Agent 的核心不是「记住所有内容」，而是「知道去哪找」。

所谓的「专属文件柜」，本质就是这个指针系统的后端。它得满足几个硬条件：每个会话的文件互相隔离，不能让 A 用户的合同出现在 B 用户的列表里；文件要有生命周期管理，临时产物到期自动消失，不然存储账单会一年翻十倍；Agent 拿到的访问凭证必须是短期的、范围受限的，因为 Agent 是会调外部工具的，凭证泄露的概率比人手操作高得多；最后，读写接口要足够简单，能被封装成一个或两个工具函数，别让模型在调用前还得学一套复杂的 API。

我这半年陆陆续续试过几种方案，从最简单的本地临时目录，到自建 MinIO，再到直接用通用对象存储，每种都有各自的坑。最近某云厂商放出了面向智能体场景的 Agent Bucket 服务，我拿两个项目做了迁移重跑，其中有踩到的问题，也有意外好用的地方，下面把整个流程和判断依据摊开讲。

1.2 从「临时目录」到「专属桶」：三种常见土办法的坑

在 Agent Bucket 这类产品出现之前，绝大多数团队用的都是下面几条路，我把它们各自的失败姿势记下来，方便你对照自己现在的架构。

第一种是容器内的本地临时目录。开发阶段特别顺手，/tmp/agent_workspace/一建，读写都是本地 IO，速度飞快。但它有两个致命问题：容器重启文件就没了，Serverless 部署下更是每次调用都是全新环境；多副本部署时，用户第二步的请求打到另一个实例，文件直接消失，前端表现成「刚才上传的图怎么不见了」。我们第一个项目上线第三天就遇到了这个，排查了两个小时才发现是负载均衡把请求打散了。

第二种是自己搭一套对象存储，比如自建一个兼容 S3 协议的私有集群。可控性确实高，但运维成本被严重低估了。容量规划、跨可用区冗余、版本控制、跨域策略、临时凭证签发，这些都要自己做。更现实的问题是，Agent 场景的访问模式跟传统 Web 应用完全不同：写入碎片化、读取突发性强、文件数量可能几小时涨到几十万。我们自己那套集群在一次压测里被小文件冲垮过，运维同事花了整整一个周末加索引。

第三种是直接用通用对象存储桶。这是最接近正确答案的做法，但「通用」两个字恰恰是问题所在。通用桶是为人类工程师设计的，默认权限模型是账号级；而 Agent 需要的是会话级、任务级的细粒度隔离。你得自己在前缀命名、IAM 策略、临时凭证服务之间手动缝一套逻辑出来，缝不好的地方就会出事故。我见过一个真实案例：某团队把临时凭证的有效期设成了 24 小时，结果一个越权问题在内部审计时才被发现，凭证在会话结束后还能继续访问整个桶。

所以核心矛盾很清楚：通用存储的抽象层次太低，Agent 需要的是「开箱即用的隔离 + 收得回来的钥匙 + 自动打扫的保洁」。Agent Bucket 这类产品瞄准的正是这个空档。

1.3 Agent Bucket 到底特殊在哪：四个面向智能体的能力差异

我把通用对象存储桶和 Agent Bucket 的差别归纳成四块，你可以拿这四条去对照评估任何同类产品。

第一是隔离粒度的下沉。通用桶的隔离单位是桶，Agent Bucket 的隔离单位可以细到会话（Session）或任务（Task）。这不只是命名规范的区别，背后是权限模型的重构。一个 Agent 会话启动时申请到的凭证，只能访问这个会话前缀下的对象，跨会话访问会被服务端直接拒绝，而不是靠客户端自觉。

第二是凭证的自动化签发。传统做法是你得自己实现一套临时凭证服务，跟账号系统、会话系统对接。Agent Bucket 把这个能力内置了，会话初始化的时候顺手就把短期凭证给你，有效期通常从几十分钟到几小时，过期自动失效。这一步省掉的工作量比听起来大很多。

第三是生命周期与配额的前置约束。Agent 产出的文件天然是「短命的」，绝大部分在 72 小时内没人看。产品层面直接支持按前缀设置过期策略，还能对单个会话的容量上限做硬限制，防止某个死循环的 Agent 一晚上把桶写爆。这条在真实生产里救过我们一次。

第四是多模态友好的元数据。通用桶的元数据就是个键值对字典，Agent Bucket 一般会在元数据里强制或建议携带 MIME 类型、来源工具、会话 ID、内容摘要等信息，方便后续做检索、审计和内容安全过滤。别小看这一点，等你需要回答「这张图是哪个工具生成的」时，就知道有多值钱。

注意：不同云厂商对 Agent Bucket 的实现差异不小，有的把能力做在存储层，有的做在独立的网关层。上面这四条是我实际用下来感受到的能力边界，具体参数以你手上的产品文档为准，别直接照搬我的配置。

2. 动手前先想清楚：桶结构与命名规范设计

2.1 三层前缀模型：租户 / 会话 / 产物

我在动手写第一行代码之前，强制自己做了一件事：把键名（Key）的规范定死，并且写成文档让所有 Agent 工具函数统一遵守。这一步看起来像形式主义，实际上是整个方案能不能长期活着的基础。键名一旦混乱，后面的生命周期策略、权限策略、审计检索全部无从谈起。

我最后落地的是三层前缀模型：{tenant_id}/{session_id}/{artifact_type}/{filename}。举个具体的例子，t-8f3a/s-20240612-0007/image/chart_03.png。四段的含义分别是租户、会话、产物类型、文件名。

为什么是这个顺序，而不是反过来？因为对象存储的列举操作是前缀匹配的，你把变化频率最低的放最前面，列出「某租户下所有文件」就只需要一次前缀查询。如果反过来把文件名放前面，想统计某个租户的存储占用就只能全量扫描，几十万对象扫一次要几秒到几十秒，Agent 的响应时间根本受不了。

第三段artifact_type是我加的，值域限定在upload（用户上传）、gen（模型生成）、tool（工具中间产物）、final（最终交付件）这四类。这一段的用处在于批量清理：会话结束时，gen和tool可以立刻删，final保留 7 天，upload按合规要求保留 30 天。如果只有一个扁平的会话前缀，你没法做差异化清理，只能一刀切。

提示：键名里绝对不要出现用户可控的原始字符串作为路径段。用户上传的文件名可能是../../etc/passwd这类内容，也可能是带%2F的编码串。我的做法是把原始文件名做 URL 安全编码后只保留最后一段，路径段一律用系统生成的 ID。

2.2 文件命名与元数据约定

文件名这一层我踩过一个不大不小的坑。最初我直接把用户上传的原始文件名当键名最后一段，结果出现三种情况：中文文件名在某些客户端里显示成乱码；同名文件互相覆盖；带空格和特殊字符的文件名在生成预签名 URL 时需要额外转义，偶尔会导致签名不匹配。

后来改成了「时间戳 + 短哈希 + 原扩展名」的格式，例如20240612T093015Z_a3f9c1.png。原始文件名不丢，塞进元数据的original-name字段里，前端展示的时候读元数据即可。时间戳用 UTC 的 ISO 紧凑格式，好处是按字典序排列就是时间序，列目录天然有序，不用额外排序。

元数据我固定了六个字段，全部小写短横线命名，避免不同 SDK 之间的兼容问题：

content-sha256这个字段值得单独说。Agent 有个典型行为是反复生成相似内容，比如同一个图表因为参数微调重画五次。上传前先算哈希，命中已有对象就直接复用，既省存储又省请求数。我们一个图像处理项目里，这个去重把写入量压掉了将近四成。

2.3 生命周期策略与冷热分层

对象存储最容易被忽视的成本项是「存了但没人看」的数据。Agent 的产物里，真正被用户下载过的比例极低，我统计过我们一个客服助手项目的样本，大约只有 6% 的生成文件被打开过。剩下 94% 就是纯占位。

生命周期策略我按三层来配，具体规则写在下面这张表里，你可以直接抄。

这张表背后的取舍逻辑是：删除时间的设定不看「技术上能留多久」，而看「业务上什么时候还会有人找」。用户上传的合同扫描件，一个月后可能因为纠纷被翻出来；模型生成的调试截图，三天后连生成它的开发者都想不起来是干什么的。转低频和转归档的意义在于，那些「可能有人找但概率不高」的数据，用更便宜的存储层兜着，需要的时候再取回。

这里有个实操细节：生命周期规则是按前缀匹配的，规则的生效是异步的，通常有几十小时到一天的延迟。所以你不能指望它做「秒级清理」，会话结束时要立刻删的东西，还是得靠代码里主动调用删除接口。生命周期规则是兜底，不是主力。

3. 权限与凭证：Agent 拿钥匙的正确姿势

3.1 为什么不能把长期密钥塞进 Prompt

先说一个我亲眼见过的反面案例。某团队为了让 Agent 能上传文件，把一对长期访问密钥写进了系统提示词里，理由是「这样模型自己就能拼请求了」。这个做法的问题不在于模型会不会泄密，而在于整条链路上有太多环节能看到提示词：日志系统、调试工具、第三方可观测平台、模型服务商。密钥一旦写进提示词，它的生命周期就完全不可控了。

正确姿势只有一个：Agent 永远不接触长期凭证。它接触的应该是「会话级临时凭证」，有效期以分钟或小时计，权限范围限定在本次会话前缀下，会话结束就失效。这个模型跟传统 Web 应用里的临时令牌是一个思路，只是 Agent 场景对它的依赖更重，因为 Agent 的调用链更长、更不可预测。

我把这套逻辑落成了三条铁律，写在团队文档最上面：任何 Agent 运行时环境不得持有长期密钥；所有文件操作必须通过工具函数转发，工具函数内部才持有短凭证；凭证的申请与回收与会话生命周期绑定，会话关闭时必须显式失效。

第二条容易被绕过。有些人图省事，让模型自己用 HTTP 工具去拼请求，这就等于把凭证间接暴露给模型。工具函数这层封装看着多此一举，实际上是唯一的权限收口点。

3.2 临时凭证 + 细粒度策略的落地写法

具体到代码层面，我的做法是会话初始化时向凭证服务申请一组临时凭证，同时带上一个内联的策略（Policy），把权限死死限制在本会话前缀内。下面这段是核心逻辑，我做了脱敏，参数名你按手上的 SDK 对应改。

def issue_session_credential(tenant_id: str, session_id: str, ttl_seconds: int = 3600): prefix = f"{tenant_id}/{session_id}/" policy = { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject", ], "Resource": f"arn:aws:s3:::agent-bucket/{prefix}*", }, { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "arn:aws:s3:::agent-bucket", "Condition": { "StringLike": {"s3:prefix": [f"{prefix}*"]} }, }, ], } return sts_client.assume_role( RoleArn="arn:aws:iam::000000000000:role/agent-session-role", RoleSessionName=f"{tenant_id}-{session_id}", DurationSeconds=ttl_seconds, Policy=json.dumps(policy), )["Credentials"]

这段代码里有两个点值得展开。第一，ListBucket权限必须配Condition限制前缀，否则凭证持有者可以列举整个桶的对象名，这本身就是一种信息泄露，对象的键名往往包含业务含义。第二，DurationSeconds不要图省事设成最大值，一小时对绝大多数会话足够，超长会话可以在过期前用续期接口换新凭证，而不是一开始就发一张长期票。

ttl_seconds这个参数怎么定？我的经验公式是：单次会话的最长预期时长乘以 1.5。我们客服助手的会话平均 8 分钟，最长 25 分钟，所以设成 3600 秒（1 小时）已经很宽裕。图像处理流水线是异步的，一个任务可能跑 40 分钟，那个场景我设成了 7200 秒。

注意：临时凭证的有效期和预签名 URL 的有效期是两个独立的东西，别混为一谈。凭证过期后，用这个凭证签出来的 URL 会在签名校验阶段直接失败，即使 URL 本身标称还有效。

3.3 预签名 URL 的有效期与使用边界

预签名 URL 是 Agent 场景里最实用的一个能力。它的价值在于：你不需要把文件内容读进后端再转发，也不需要用凭证去换一次下载，只要生成一个带签名的链接丢给前端或者丢给下游工具，剩下的交给浏览器和 CDN。对于图片、PDF 这类大文件，这一招能把后端的带宽压力降一个数量级。

有效期怎么定，我踩过两种极端。设太短，比如 60 秒，用户在页面上停留一会儿点下载就报错，投诉率明显上升；设太长，比如 7 天，等于把一个不需要任何身份的公开链接散播出去了，只要链接被转发出去，文件就等于公开了。

我现在的默认配置是按文件类型分档：

还有一个容易被忽略的细节：预签名 URL 默认是 GET，如果你要的是上传链接（PUT），那就得单独签，而且上传链接的安全性要求更高，因为它允许写入。我的做法是上传链接一律只签给「固定键名 + 固定大小上限」的场景，键名由后端生成，前端不能改，这样即使链接泄露，攻击者也只能覆写那一个已知文件，不能往桶里塞垃圾。

4. 完整实操：把文件柜接进 Agent 的工具链

4.1 初始化客户端与连通性自检

基础环境我用的是一台普通云主机加 Python 3.11，没有特殊依赖。客户端走的是 S3 兼容协议，任何兼容这套协议的 SDK 都能用，我这边用的是 boto3，理由是生态成熟、签名实现稳定、排查问题时网上的资料多。

import boto3 from botocore.config import Config s3 = boto3.client( "s3", endpoint_url="https://agent-bucket.example-cloud.com", region_name="ap-example-1", aws_access_key_id=cred["AccessKeyId"], aws_secret_access_key=cred["SecretAccessKey"], aws_session_token=cred["SessionToken"], config=Config( signature_version="s3v4", s3={"addressing_style": "virtual"}, retries={"max_attempts": 3, "mode": "standard"}, connect_timeout=5, read_timeout=30, ), )

几个参数值得说说。addressing_style设成virtual而不是path，是因为虚拟主机风格在多数服务端上走的是同一条解析路径，跟 CDN 对接时更顺。max_attempts设成 3 而不是默认值，是因为 Agent 场景里网络抖动比人手操作时更常见，重试三次能覆盖绝大部分瞬时故障，再多就是浪费响应时间了。read_timeout给 30 秒，是因为分片上传的单个分片可能较大，超时设置太短会频繁中断。

初始化完之后我会跑一个自检，逻辑很简单：往临时前缀写一个几百字节的小文件，读回来比对内容，然后删掉。这一步的目的是把「凭证不对」「endpoint 写错」「桶名拼错」「时钟偏移导致签名失败」这几类问题在上线前一次性排掉，而不是等 Agent 跑起来之后看着一堆 403 抓瞎。

自检里我特意加了一个时钟校验。S3 V4 签名对客户端时间很敏感，默认容忍窗口是 15 分钟，机器时间偏了就会收到RequestTimeTooSkewed。容器环境里这个问题比你想象中常见，尤其是长时间运行的 Pod。

4.2 上传 / 列举 / 下载 / 删除四件套

日常操作其实就这四个动作，我把它们封装成了四个函数，统一处理异常、统一打日志、统一带元数据。

def put_artifact(s3, bucket, tenant_id, session_id, artifact_type, data: bytes, ext: str, original_name: str): ts = datetime.utcnow().strftime("%Y%m%dT%H%M%SZ") digest = hashlib.sha256(data).hexdigest() key = f"{tenant_id}/{session_id}/{artifact_type}/{ts}_{digest[:6]}{ext}" s3.put_object( Bucket=bucket, Key=key, Body=data, ContentType=guess_mime(ext), Metadata={ "session-id": session_id, "artifact-type": artifact_type, "original-name": urllib.parse.quote(original_name), "content-sha256": digest, }, ) return key

注意original-name我做了 URL 编码。元数据是纯 ASCII 的，中文直接塞进去在部分服务端实现上会报错或者被截断，编码成%E5%AD%A3%E5%BA%A6...这种形式最稳，读的时候解一次就行。

列举我用list_objects_v2加分页，这里有个必须处理的问题：Agent 一个会话下可能有几百个对象，单次返回最多 1000 个，超过就要用ContinuationToken翻页。我封装了一个生成器，调用方只管 for 循环，翻页逻辑藏在里面。

def iter_objects(s3, bucket, prefix): token = None while True: kwargs = {"Bucket": bucket, "Prefix": prefix, "MaxKeys": 1000} if token: kwargs["ContinuationToken"] = token resp = s3.list_objects_v2(**kwargs) for obj in resp.get("Contents", []): yield obj if not resp.get("IsTruncated"): break token = resp.get("NextContinuationToken")

删除这块我特别提醒一句：批量删除接口一次最多传 1000 个键，而且它返回的失败列表必须检查，不能假定全成功。我们曾经有过一次「以为删干净了结果临时文件还在计费」的事故，就是因为没看返回体里的Errors字段。

4.3 把文件操作封装成 Function Calling 工具

这一节是整个方案里我最看重的部分，因为它决定了模型能不能自然地用好这个文件柜。

工具的设计原则是「少而稳」。我最初设计了七个工具，上传、下载、列举、删除、重命名、搜索、生成链接，结果模型的选择准确率惨不忍睹，经常该用列举的时候去调搜索。后来收敛到三个，准确率立刻上来了：

• save_file(content_base64, filename, kind)：写文件，返回键名
• list_files(kind, limit)：列文件，返回键名、大小、时间的精简列表
• get_file_link(key, ttl_minutes)：拿下载链接

三个工具的参数都刻意做得简单，kind就是前面说的四类产物类型，用枚举限制死。模型不需要知道租户 ID 和会话 ID，这两个值由工具层从上下文里自己取，绝不暴露给模型去填。这个设计的好处是模型即使产生了幻觉，也编不出一个越权的键名来。

{ "name": "save_file", "description": "把生成的内容保存为文件，返回文件标识。适合保存报表、图片、长文本等需要交付给用户的内容。", "parameters": { "type": "object", "properties": { "content_base64": {"type": "string", "description": "文件内容的 base64 编码"}, "filename": {"type": "string", "description": "带扩展名的文件名，例如 report.xlsx"}, "kind": {"type": "string", "enum": ["gen", "final"]} }, "required": ["content_base64", "filename", "kind"] } }

description里我特意写了「适合保存报表、图片、长文本」，这句话不是废话，它显著降低了模型在闲聊时调用工具的概率。工具的说明文字本身就是提示词的一部分，写清楚边界比写清楚功能更重要。

工具层里还有一道防线：大小上限。我给save_file设了 20MB 的硬限制，超了直接返回错误让模型自己想别的办法（比如拆成多个文件）。这条防线拦住过好几次模型把整个网页 HTML 转 base64 硬塞进来的情况。

4.4 一条完整的端到端会话演示

把上面的零件串起来，跑一遍真实链路，这样你能看到整体节奏。

假设用户说「帮我分析这个 CSV，出一张趋势图和一份结论摘要」。会话启动，系统分配t-8f3a/s-20240612-0007/，签发 1 小时临时凭证。用户上传 CSV，走upload前缀，键名t-8f3a/s-20240612-0007/upload/20240612T093015Z_a3f9c1.csv，同时算哈希记进元数据。

Agent 第一步调工具读文件，工具层用get_object拉内容，只把表头和统计摘要喂给模型，而不是整份 CSV 塞进上下文。这一步是省 token 的关键，一份 5MB 的 CSV 转成文本大概 200 万字符，直接塞进去任何模型都撑不住。

模型给出图表参数，代码执行工具画出 PNG，调save_file存到gen前缀。摘要文本存成 MD，也走gen。最后模型判断这一轮交付完成，把图和摘要复制或重命名为final前缀下的两个对象。这个「gen 转 final」的动作看着多余，实际是生命周期策略的开关，gen三天后自动消失，final留 90 天。

会话结束，前端拿到两个预签名链接（有效期 60 分钟）展示给用户。后台起一个延迟任务，2 小时后清理该会话的gen和tool前缀，upload和final交给生命周期规则慢慢处理。

整条链路我实测下来，一次会话的对象数量在 3 到 12 个之间，总写入量平均 1.2MB，请求数大约 20 次。这个量级对任何对象存储都是毛毛雨，真正的成本压力来自并发会话数和留存策略，后面会算。

5. 踩坑实录与排查速查表

5.1 权限类报错：403 的六种不同面孔

403 是这套方案里出现频率最高的错误码，但它背后的原因至少有六种，看错误信息里的Code字段才能区分。我整理了一张对照表，遇到直接查。

我吃过最久的一次亏是NoSuchBucket伪装成 403。当时一直以为策略有问题，查了两个小时，最后发现是 endpoint 指向了另一个地域，桶根本不在那儿。

5.2 大文件与分片上传：阈值怎么算

单个put_object一般有 5GB 的上限，超过就得用分片上传。分片大小不是随便定的，它由两个约束夹出来：单个分片最小 5MB（最后一片除外），单个对象最多 10000 个分片。

算个具体的：一个 20GB 的文件，如果按最小 5MB 切片，需要 4096 片，在 10000 的限额内，可行但分片数偏多，请求数上去成本也上去。我一般按「目标分片数控制在 500 以内」来反推，20GB / 500 ≈ 41MB，取 64MB 更整齐，实际分片数 320 个。

$$分片大小 = \max\left(5\text{MB},\ \left\lceil \frac{文件大小}{500} \right\rceil\right)$$

分片上传还有两个坑。一是并发度，我设成 4 到 8 之间，太高反而因为带宽争抢变慢，太低浪费等待时间。二是失败重传，只需重传失败的那一片，不要整个重来，所以每一片的上传结果要单独记录。

5.3 中文名、编码与 Content-Type 的连锁问题

这个坑很典型。用户上传一个叫季度总结.xlsx的文件，如果不设ContentType，服务端会默认成application/octet-stream，浏览器下载时直接变成下载而不是预览，某些前端组件的图片预览也会失败。

解决方案是维护一张扩展名到 MIME 的映射表，写入时显式指定。xlsx 对应的类型是application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，这串东西记不住就查表，别猜。

中文文件名还有第二个坑：Content-Disposition。如果你希望浏览器下载时显示原始中文名，需要在响应头里写attachment; filename*=UTF-8''...这种 RFC 5987 格式。预签名 URL 里没法直接改响应头，我的做法是下载时后端加一层 302 转发，或者干脆在前端用download属性指定文件名，绕开这个问题。

5.4 并发写与覆盖冲突：Agent 的重试陷阱

Agent 有个特性是喜欢重试。工具调用超时了重试，返回不符合预期重试，有时候同一个内容会写三次。如果键名是固定的，就会出现互相覆盖，运气不好还会读到写了一半的对象。

我的解法是在键名里带哈希前六位，内容相同哈希相同，覆盖了也无所谓，内容一样的。内容不同哈希就不同，天然不冲突。这个设计让整个系统在并发场景下变得幂等，不需要额外的分布式锁。

还有一个更隐蔽的问题：读己之写的一致性。写入后立刻读取，绝大多数现代对象存储是强一致的，但如果你在前面加了 CDN 或者缓存层，就可能读到旧版本。我在工具层做了一件事：save_file返回键名之后，如果需要立刻展示，直接用本地内存里的那份数据渲染，不等回读。等下拉刷新的时候再从存储读，这时一致性早就完成了。

5.5 常见问题速查表

这张表里的每一条我都真实遇到过，其中「列举前缀少了结尾斜杠」这条最坑，因为它不会报错，只是安静地返回一个包含相邻会话文件的列表。当你发现 A 用户看到了 B 用户的文件名时，先查这里。

6. 成本、安全与后续扩展

6.1 容量与请求成本估算

不算账的方案都是耍流氓。我按一个中等规模场景算一遍，你可以拿自己的数据替换。

假设日活会话 1000 次，每次会话产生 8 个文件、平均 300KB，那么日写入量约 2.4GB。保留策略是滚动 30 天，稳态存储量约 72GB。按常见的对象存储单价每 GB 每月 0.1 元计算，存储成本每月 7 元左右，这个数字小到可以忽略。

请求成本才是主要项。每次会话大约 20 次请求（写入 8 次、读取 5 次、列举 3 次、删除 4 次），日请求量 2 万次，月请求量 60 万次。按每万次 0.01 元算，每月 6 元。加上流量，假设 20% 的文件被下载，日流出量 480MB，月 14GB，按每 GB 0.5 元算，每月 7 元。

三项加起来每月不到 25 元。这个结论很重要：在 Agent 场景里，存储几乎从来不是成本瓶颈，真正的成本在模型调用和计算资源上。所以选型的时候不要把精力花在抠存储单价上，应该花在「会不会因为存储设计不当导致模型多跑几轮」上。我见过一个反面案例，因为文件读取接口返回了全量内容，导致上下文超限触发了截断重试，一个月的模型费用多花了四位数。

6.2 安全红线：目录穿越、类型白名单与内容审核

文件柜这东西一旦接上 Agent，攻击面就变大了，因为 Agent 会把外部输入当作指令。我列了几条必须做的防御。

目录穿越。键名里出现..必须拒绝，服务端虽然有防护，但客户端也要拦一道。我的做法是键名生成完全由后端控制，用户提供的文件名只进元数据，永不进路径。

类型白名单。允许上传的扩展名用白名单限制，图片、PDF、常见办公文档、纯文本，其余一律拒绝。SVG 要特别小心，它里面可以嵌脚本，如果前端直接渲染会有风险，我的处理是 SVG 一律转成 PNG 再存。

大小与频率限制。单文件上限 20MB，单会话总容量上限 200MB，单会话文件数上限 100 个。这三个数字不是拍脑袋，是算出来的：超过这个量级，Agent 会话本身就该被拆分了，说明任务设计有问题。

内容审核。用户上传的图片和文本，在落盘前要过一遍内容安全检查。这一层我做成了异步的，先存再查，查出来有问题就标记删除，避免阻塞主流程。但要注意，异步检查意味着存在一个短暂的窗口期，敏感内容可能被预签名链接访问到，所以高风险场景下建议改成同步检查。

注意：不要把桶设置成公共读。哪怕你觉得里面只有图片。一旦公共读，键名就成了唯一的安全边界，而键名是可以被穷举和猜测的。所有访问都必须走预签名或者后端代理。

6.3 后续可以怎么扩展：从文件柜到知识库

这套东西跑顺之后，我做了两个扩展，效果都不错，顺手记下来。

第一个是给文件加向量索引。文件落盘之后触发一个异步任务，抽取文本、切块、算向量，存进检索服务。这样 Agent 就能回答「我上次给你的那份文档里第三章讲了什么」这类问题，从「能存文件」升级到「能读文件」。这一层的成本比存储高不少，因为嵌入模型要跑，所以只对final和upload两类做，gen和tool跳过。

第二个是做审计面板。因为所有键名都带了租户、会话、Agent ID 和时间戳，只要按前缀聚合一下就能出报表：哪个 Agent 写得最多、哪些文件从没被下载过、清理任务实际删了多少。这个面板帮我们发现过一个 Agent 的死循环，它在 20 分钟里写了 300 多个几乎一样的文件，如果没有审计面板，这事要等到月底看账单才会发现。

对了，还有个不在计划内但很有用的副产品：因为元数据里存了content-sha256，我把所有会话的哈希做了个全局统计，发现某些咨询类问题的中间产物高度重复。后来针对这批高频内容做了一层结果缓存，命中率大约 12%，直接省掉了这部分模型调用。

最后分享一个我在这套方案里坚持了很久的小习惯：每接一个新 Agent，第一件事不是写业务逻辑，而是先把文件柜的三个工具函数接上，跑通一次「上传-列举-下载-删除」的完整闭环，再开始写提示词。原因是文件操作是最容易被低估的失败点，早跑通早暴露问题，比等业务逻辑写完了再回头查一个 403 要省太多时间。我这两个月搬了三个项目过来，最慢的一次调试用了半天，最快的一次二十分钟，差距全在有没有提前把权限和前缀规范定死。