文件空间管理

FileRoom 是 Agent 工作区和 DocSpace 文件能力之间的权限边界。数据库保存房间、节点、版本、回收站和对象键；对象存储保存实际内容；VFS 通过内存或 backing store 提供 Agent 统一文件 API。

房间、成员与分享

FileRoomController、FileRoomMemberController、FileRoomSharingController 和 FileRoomRecycleBinController 分别处理房间、成员、邀请/加入申请、分享链接和回收站。FileRoomAccessService 是真正的授权边界：每次列举、读取、写入、移动、删除和分享都要结合 tenantId、roomId、userId、成员权限、资源状态和操作类型。

ACL 变化通过 FileRoomAclChangedEvent/EventBridge 通知相关缓存和运行时。不能只修改成员表而保留旧 ACL；Agent 已绑定的 room 也要在工具调用时重新确认。分享链接具备有效期、访问次数或 Token budget，不能把对象存储地址当作永久公开 URL。

分片上传的真实状态机

FileRoomChunkUploadServiceImpl 默认分片大小为 8MB，并解析 Content-Range。调用顺序是 init -> upload part -> status -> complete；完成时检查分片是否齐全、大小/范围是否合法、合并结果哈希和对象存储写入，之后才建立正式 VFS 节点。BatchUploadService 复用相同的状态语义。

Spring multipart 的 max-file-size/max-request-size 不能小于业务分片和批量请求所需范围。初始化、完成、删除都要扣减/释放配额；重复 complete、缺块、临时文件丢失和对象存储失败必须保留可诊断、可重试的上传任务。

提供器与智能体工作空间

RoomStorageProviderRegistry 可选择本地、SFTP、SMB 或云存储 Provider。数据库只保留节点、对象键、大小、哈希、版本和权限元数据，文件内容不应进入普通业务表。Agent session 创建时固定 roomId、provider 和相对目录，LoadAgentConfigNode 再将其转换为 sandboxRoomId/sandboxRelativePath；恢复时必须重新校验绑定，不能接受请求中的任意绝对路径。

删除先写入 VfsRecycleBinEntity，异步任务再清理对象；对象删除失败时保留重试状态。上传失败查 multipart、分片和配额后再查 Provider，Agent 找不到文件查 room binding、相对路径和挂载状态。

上传分片完成后再合并和计算哈希；下载/预览返回短期签名或受保护的流。删除先进入回收站，异步清理对象，任何一步失败都保留可重试状态。