DeepAgent 上传文件分析
DeepAgent 支持在会话中上传一个或多个文件，并根据用户要求读取、整理、统计和分析文件内容，也可以生成报告、表格、演示文稿等成果文件。
本文说明当前版本的文件存储、生命周期、大小限制、日志审计、安全校验和分析结果存储方式，供项目实施、安全评估和客户沟通使用。
本文描述的是 Data Agent 应用当前实现。反向代理、Ingress、API 网关、容器平台和大模型服务商可能另有请求大小、日志留存及数据处理规则，交付时需结合项目实际部署配置确认。
工作方式
上传文件按会话隔离。同一个会话后续发起请求时，DeepAgent 可以继续读取该会话已经上传的文件。
DeepAgent 使用隔离的虚拟文件系统（VFS）处理文件：
- 用户上传的文件位于 VFS
/uploads目录。 - DeepAgent 生成的报告、表格、演示文稿等成果位于 VFS
/workspace目录。 - 请求开始时，系统将会话文件加载到 VFS；处理过程中及请求结束时，再将变更同步回服务器持久化目录。
文件存储与生命周期
存储位置
上传文件保存在应用服务器的会话私有目录：
DeepAgent 生成或修改的成果文件保存在：
<sessionId> 是会话 ID，不同会话使用不同的存储目录。这些目录不会通过普通静态文件服务直接公开。
保留和清理
上传文件和生成文件是会话级持久化文件，不会在单次分析请求结束后自动删除。当前版本没有为 uploads/ 或 workspace/ 配置自动过期时间，也没有定时清理任务。
系统会定期清理 DeepAgent 的中间运行状态和调试日志，默认保留 72 小时；该清理不包括上传文件和生成文件。
当前产品界面和 API 没有提供单个上传文件的物理删除功能，删除会话时也不会同步删除对应的 DeepAgent 文件目录。管理员可以在服务器上按会话目录人工清理。清理前应确认会话 ID，并避开正在执行的会话。
同一会话上传同名文件时，后上传的文件会覆盖原文件。
文件大小和数量限制
当前 DeepAgent 专用上传链路没有在应用前端或后端设置明确的单文件大小、请求总大小或文件数量限制。
普通表格附件的 10 MB 限制不适用于 DeepAgent 专用上传功能。项目现场的实际上限可能来自：
- Nginx、Ingress 或 API 网关的请求体限制；
- 容器平台和应用服务器的资源限制；
- 上传过程的可用内存；
- 大模型或文件处理工具自身的上下文和处理能力。
在完成部署环境验证前，不应对外承诺固定的最大文件大小。生产环境建议同时在网关和应用服务端配置明确的单文件大小、请求总大小和文件数量限制。
上传记录与日志
当前版本没有独立、完整的文件上传审计表或上传审计日志。
文件随用户消息正式发送后，系统会在 yiask_message.attachments 中保存文件名、VFS 路径和 MIME 类型等附件元数据，并可结合消息的创建人和创建时间确认该附件由谁随消息提交、何时发送。
现有记录存在以下边界：
- 文件上传成功但用户没有发送消息时，不会形成对应的消息附件记录；
- 消息创建时间是发送时间，不是上传接口接收文件的准确时间；
- 上传接口会返回文件大小，但当前客户端没有将该字段带入消息附件，数据库中没有可靠的上传大小记录；
LOG_LEVEL=debug时会记录 DeepAgent 运行和工具调用日志，但这不是文件上传审计日志，且默认 72 小时后清理。
因此，当前实现不能作为具备完整“上传人、上传时间、原始文件名、上传大小”字段的文件审计系统使用。
网关层可记录的内容
如果客户暂时不具备应用源码或不计划进行应用侧改造，可以先在 Nginx、Ingress、API 网关或 WAF 层记录上传接口的基础访问日志。通常可以记录：
- 请求时间、来源 IP、User-Agent 和上传接口路径；
- HTTP 状态码、请求耗时、请求体总大小和响应大小；
- 网关能够识别的登录账号、租户或请求 ID，前提是认证信息已经由网关解析并以可信字段传递；
- 限流、请求体超限、WAF 拦截等网关处理结果。
网关日志通常不能可靠记录文件原始名称、单个文件大小、文件校验值、会话 ID，以及文件是否被 DeepAgent 成功分析。这些字段位于 multipart 请求体或应用业务流程中，仅依靠普通访问日志无法形成完整的文件审计链路。
配置网关日志时，不应直接记录完整请求体、上传文件内容、Cookie、Authorization Header 或访问令牌，避免日志本身造成敏感数据和凭据泄露。应结合客户的安全制度设置日志访问权限、脱敏规则和保留周期。
安全检查与校验
已有校验
上传接口当前执行以下校验：
- 用户必须登录；
- 会话必须存在，并且属于当前用户；
- 指定的 AI 员工必须存在且类型为 DeepAgent；
- 请求中至少包含一个文件；
- 保存文件时仅使用上传文件名的基础名称，降低利用文件名进行目录穿越的风险；
- DeepAgent 在隔离的 VFS sandbox 中操作文件。
当前未提供的检查
当前版本没有提供以下文件安全能力：
- 敏感信息、个人信息、密级或 DLP 识别；
- 病毒、木马和恶意文件扫描；
- 文件扩展名白名单；
- MIME 类型、扩展名和文件头一致性校验；
- 压缩包内容和压缩炸弹检测；
- 服务端文件大小和文件数量限制；
- 文件内容自动脱敏。
VFS sandbox 用于限制 DeepAgent 的文件操作范围，不等同于敏感信息检测、内容脱敏或病毒扫描。
文件分析需要将文件内容提供给所配置的模型或相关处理工具。数据是否离开本地环境、服务商如何留存数据，取决于项目实际配置的大模型供应商、模型部署方式及其数据处理条款。涉及敏感数据时，应在实施阶段完成模型供应商、网络出口、日志和数据留存策略评估。
分析结果存储
DeepAgent 读取文件时产生的中间工具结果可能进入运行 checkpoint 和 Debug 日志。最终向用户展示的分析文字保存在会话消息中，生成的独立成果文件保存在会话的 workspace/ 目录。
生产环境实施建议
正式交付前建议完成以下配置和确认：
- 明确允许上传的文件类型、单文件大小、请求总大小和文件数量，并在服务端强制校验。
- 根据客户的数据留存制度增加上传文件和生成文件清理策略，并确保删除会话时同步清理物理文件。
- 如项目有基础访问审计要求，可先在网关层记录请求时间、来源、请求大小、状态码和拦截结果；如需完整的文件上传审计，可联系产品供应方评估随产品版本或扩展插件交付增强能力，记录上传人、准确上传时间、原始文件名、单文件大小、文件校验值、会话 ID，以及上传成功、失败或被安全策略拦截等状态。
- 按项目安全等级接入病毒扫描、文件类型真实性检查、压缩包检查、敏感信息识别或 DLP。
- 确认模型部署位置、网络出口、模型供应商数据条款，以及日志中是否允许出现文件内容。
- 将
storage/private/deepagent-workspace/纳入容量监控、备份和磁盘告警范围。