虚拟文件系统
Virtual File System
Agent 可见的虚拟路径与物理路径之间的映射和隔离机制
子问题
1.虚拟路径到物理路径映射
2.线程级目录隔离
3.本地与容器路径统一
4.文件上传与产出管理
5.命令输出中物理路径的反向虚拟化
6.Skills 目录的独立只读挂载
7.Gateway API 层虚拟路径安全解析
各项目的解法1 solutions
Signals
横向对比
| 维度 | DeerFlow |
|---|---|
| 虚拟路径方案 | 固定前缀 /mnt/user-data + 三子目录映射，工具层正则批量替换 |
| 目录隔离粒度 | 线程级：.deer-flow/threads/{thread_id}/user-data/{workspace,uploads,outputs} |
| 双后端统一 | 本地用 replace_virtual_path 软替换，Docker 用 volume mount 硬映射 |
| 路径安全防护 | Gateway 层 resolve()+startswith() 防路径遍历，403 拒绝 |
| 懒初始化策略 | 中间件只计算路径，工具首次调用时 ensure_thread_directories_exist() |
| 双向映射 | LocalSandbox 正向解析命令输入 + 反向解析命令输出，Agent 始终看虚拟路径 |
| Skills 挂载 | /mnt/skills 独立映射，容器只读挂载，本地通过 path_mappings 字典 |
最佳实践
1.统一虚拟路径接口屏蔽底层存储差异，每线程独立目录防止数据泄漏
2.工具层正则替换排除 shell 元字符避免误匹配
3.中间件懒初始化只计算路径不创建目录减少 I/O
4.LocalSandbox 双向映射确保 Agent 输入输出路径一致