文件系统与虚拟文件系统机制

两层文件能力

fs 领域提供用户可见的文件房间、目录、上传、分享、回收站和下载 API；agent/vfs 提供 Agent 运行时使用的虚拟工作区。两者通过 VfsBackingStore 或 DocSpace 对接，而不是让 Agent 直接操作宿主机目录。房间存储由 RoomStorageProviderRegistry 按挂载类型选择 file、sftp、smb 等 provider。

虚拟文件系统

VirtualFileSystem 基于 Jimfs 创建 Unix 风格的内存文件系统，有两种模式：

• 纯内存模式：无 backing store，适合短生命周期任务和测试。
• DocSpace 挂载模式：启动时加载目录树和空文件 stub，文件内容首次读取时懒加载。

挂载模式维护路径到远程节点 ID 的映射，并记录创建、修改和删除集合。调用 flushToBackingStore() 时按“删除 → 创建目录 → 上传新文件 → 同步脏文件”的顺序批量写回。

文件空间接口

FileRoomController 的基础路径为 /v1/files/rooms，覆盖房间、目录、上传、批量删除、批量更新、文件浏览器兼容接口、分享链接和下载。上传参数受 Spring multipart 限制：代码默认单文件 16 MB、请求 32 MB；分片上传需要同时检查前端分片大小和服务端限制。

房间的 fileSystemUrl 只保存协议和根路径，账号、密码、token 等认证信息放在独立的 fileSystemAuthConfig 并加密存储；返回前端时会清理敏感配置。平台云端房间的真实根路径来自 fs.storage-profiles，不能由前端覆盖。

安全边界

• 所有路径都要经过 VfsAuthHelper、房间成员和租户校验。
• 不允许把用户传入路径直接拼接到宿主机路径。
• 沙箱命令通过 VirtualShell 和 VirtualShellTool 执行，工作目录应由 SandboxWorkspaceResolver 解析。
• 生产环境必须为会话账本、文件空间和对象存储配置持久化卷。