Cua Volume 是 Cua 中面向单个用户的版本化共享卷。每个用户拥有一个卷，该用户的所有 Space 与智能体共享同一份文件。每次写入都会产生一个新版本，删除操作也会保留历史记录。同一批文件会出现在用户的 Mac（Finder）以及每个 Space 中，通常在数秒内完成同步。
一、卷的位置
卷在不同运行环境中的挂载路径不同：
- Linux Space：/volume（当 /volume 不存在时为 ~/Cua Volume）
- macOS Space：~/Cua Volume
- 无挂载（目前如 Windows，或该 Space 没有挂载）：使用下文列出的 volume_* 工具
需要确认卷是“已挂载”而不只是“存在”：在 Linux 上可用 mountpoint -q /volume 检查，在 macOS 上可用 ls ~/"Cua Volume" 检查。如果 /volume 中只有一个只读的 CUA-VOLUME-UNAVAILABLE.txt，那并不是卷本身，该文件会说明原因（例如容器缺少 /dev/fuse）。若卷未挂载，请改用工具访问；写入未挂载文件夹的内容不会被保存。
二、目录结构与权限
卷内按文件夹划分权限：
- public/：只读，来自用户的共享参考资料。
- agents/<you>/：可读写，是当前智能体的主目录，包含 memory、outputs/、inbox/ 等。
- spaces/<this space>/：可读写，是当前 Space 的暂存与输出目录。
- 其他智能体的主目录、其他 Space：不可见；如需访问，使用 volume_request_access 申请。
需要让用户看到的结果，应放在 agents/<you>/outputs/（或当前 Space 的文件夹）中，并把路径告知用户。如果写入被拒绝，说明该文件夹不属于你：不要换到别处重试以绕过限制，而应发起申请。
三、工具（cua MCP 服务器）
- volume_ls、volume_read、volume_write：在没有挂载的情况下访问同一批文件；会显示每个文件的同步状态。
- volume_delete、volume_history、volume_restore：在提供该能力时，用于删除、查看旧版本、恢复某个版本。
- volume_request_access：向用户申请更多权限（某个文件夹、r 或 rw，以及原因）；用户在 Cua 中批准。
- volume_sync_status：同步健康状况、每台设备上次同步时间、仍在上传的文件、冲突情况。
在 Space 内，这些工具会从用户机器获取应答，因此展示的是该机器视角下的同步状态，而不仅是当前 Space 的视角。
四、同步与冲突
另一台设备刚写入的文件可能需要几秒才能到达。在依赖某个文件之前，先检查 volume_sync_status：feed 为 live（正在同步）、off（存储仅在本机，无需等待）或 offline（存储桶不可达，查看 last_error；此时应如实说明，而不要信任可能过期的文件）。devices 会显示每台设备上次同步的时间。
volume_ls 与 volume_read 会在必要时为文件标记同步状态：pending_upload（尚未存储，其他设备还看不到）、conflict（某次写入被更晚的写入覆盖，保留在 conflict_path）、conflict_copy，以及 written_by（最后写入该文件的设备）。
通过挂载进行的自身写入，会在关闭文件时（或停止写入片刻后）上传。在告知用户文件已就绪之前，请先关闭文件。
当两台设备修改同一文件时，后写入者胜出，另一版本会以 name (conflict from <device> <date>).ext 的形式保留在旁边，不会丢失内容。不要自行删除冲突副本：应告知用户，或在任务要求时把两者合并到当前文件中。
五、禁止在卷中存放密钥
API 密钥、令牌、密码和私钥应存放在用户的 Keyvault 中。对智能体主目录的写入会被扫描；包含密钥的写入会被拒绝（secret_detected）并记录日志。不要绕过该拒绝，应移除密钥。