症状： Cursor Agent 刚读完 node_modules 里某个包的 README，却把结论写进你的生产配置；或者 Claude Code 在沙箱里「成功」改了文件，你一刷新发现改的是临时挂载层，真实仓库纹丝不动。
根因： 现代 AI Agent 几乎从不直接摸你的硬盘——它操作的是一层 虚拟文件系统（Virtual File System, VFS）：有路径、有读写 API，但边界、持久性与权限和「真实文件」完全不同。
我们在 2026 年 7 月帮三支团队排障：一支把 Agent 日志里的 /workspace/src 当成本机路径去 ls；一支在 CI 里没挂载工作区，Agent 以为删了缓存其实只删了内存视图；还有一支把 MCP 返回的「文件内容」当磁盘真值，导致 RAG 索引了过期快照。本文把 VFS 为何存在、真实文件与虚拟文件差在哪、怎么设计边界 一次讲清。口径截至 2026-08-08。
Quick Answer：Agent 眼里的「文件」往往不是磁盘上的文件
| 你的困惑 | 一句话答案 | 立刻检查 |
|---|---|---|
| Agent 读了文件但我本机没有 | 多半是 VFS 映射路径 或 MCP/远程仓快照 | 对比 Agent 日志路径与 pwd、挂载表 |
| 沙箱里改成功、仓库没变 | 写入的是 临时 overlay，未同步到真实工作区 | 看 sandbox 是否 --writable 且挂载同一目录 |
| 为什么不让 Agent 直接读全盘 | 安全与上下文成本：VFS 做白名单与配额 | 列出 Agent 工具允许的根路径 |
| 虚拟文件和内存里的字符串有何不同 | 虚拟文件有 路径、元数据、版本，可被工具链索引 | 是否有 path、mtime、hash |
| 和向量库里的文档块算哪种 | 属于 逻辑文件视图，通常不可直接 write | 区分「检索片段」与「可编辑工作区」 |
为什么 AI Agent 需要虚拟文件系统？
大模型本身没有「打开文件夹」的能力——它只能通过 工具（Tools） 间接访问外界。虚拟文件系统就是工具层与真实存储之间的 中介层，通常同时解决四件事：
- 安全边界： 只允许读
/workspace，禁止~/.ssh、云凭证、客户数据盘。真实 OS 若直接暴露，一次 prompt 注入就可能变成全盘读取。 - 上下文预算： 仓库可能有 50GB，但模型一次只能消化几万 token。VFS 负责 按需切片：读前 200 行、按 glob 列目录、返回 diff 而非整文件。
- 可复现与审计： 沙箱快照、overlay 层、MCP 缓存都可以打上
snapshot_id，出问题时能回答「Agent 当时看到的是哪一版文件」。 - 跨环境一致： 本机 Mac、远程云 Mac、CI Runner 上的「项目根」可能路径不同；VFS 用逻辑根
/workspace统一 Agent 心智模型。
用户案例：某团队让 Agent 直接
cat生产日志目录，一次误把含 API Key 的 debug 行送进 Claude 上下文。改用只读 VFS 挂载 + 路径白名单后，同类事件归零，且 token 消耗降约 35%（不再扫无关大文件）。
这和「长上下文能装下整仓」并不矛盾——见 Kimi K3 1M 与 Agent 边界：即使窗口够大，仍需要 VFS 决定装什么、以什么粒度装。
真实文件与虚拟文件：四层对比
「虚拟」不是「假的文字」——而是 通过 API 呈现的文件接口，底层可能是磁盘、内存、远程 Git、向量库或混合体。
| 维度 | 真实文件（OS 文件） | 虚拟文件（Agent VFS 视图） |
|---|---|---|
| 存储位置 | 本地磁盘、NFS、对象存储挂载 | 可能是上述任一层的 子集或投影 |
| 持久性 | 默认持久，重启仍在 | 可能是临时 overlay、会话缓存、只读快照 |
| 路径语义 | 绝对路径唯一对应 inode | 逻辑路径可重映射（容器内 /workspace） |
| 元数据 | mtime、权限、xattr 由内核维护 | 可由框架合成（content_hash、source_commit） |
| 读写权限 | Unix ACL、沙箱策略 | 工具级策略：只读检索 vs 可写编辑 |
| 一致性 | 多进程需处理锁与竞态 | 框架可选择「快照读」避免中途被改 |
一个易混点：内存里的字符串不是虚拟文件，除非框架给它路径并让其他工具能 read(path)。否则它只是对话上下文，无法被 grep、diff、测试_runner 复用——这也是 Agent 框架要把「读到的内容」写进 VFS 或工作区的原因。
| 操作 | 对真实文件 | 对典型 Agent VFS |
|---|---|---|
read | 读磁盘块 | 可能读快照；可能截断；可能触发 RAG |
write | 直接改 inode | 可能写 overlay；可能需用户确认 |
delete | 不可恢复（若无备份） | 可能只删视图层；可能进回收站逻辑 |
list | 遍历目录项 | 可能隐藏 .git、node_modules |
五种常见虚拟文件形态（2026 实践）
| 形态 | 典型产品/场景 | Agent 看到什么 | 风险点 |
|---|---|---|---|
| 工作区挂载 | Cursor、Claude Code、Devin 类 | 项目目录映射为可读写根 | 挂载范围过大；误含密钥文件 |
| 沙箱 overlay | Docker、macOS sandbox、WASM | 底层只读 + 上层可写层 | 未合并 overlay 导致「假成功」 |
| 远程仓快照 | 云 Mac、GitHub API、MCP git | 某 commit 的文件树 | 与本地未提交改动不一致 |
| 逻辑文档块 | RAG、Knowledge Base PDF 管线 | 带 source_id 的文本块，非完整文件 | 块被当全文；过期版本未过滤 |
| 结构索引视图 | 代码知识图谱、Tree-sitter 图 | 「虚拟路径」指向符号与依赖边 | 图过期；与真实代码漂移 |
实测片段（2026-07，三环境对比）： 同一仓库在「本机直接读盘」「Docker 只读挂载 + overlay」「MCP 只返回 GitHub 默认分支」三种 VFS 下，Agent 对「未推送分支上的新接口」感知率分别为 100%、100%、0%。选错 VFS 形态比选错模型更致命。
路径映射与沙箱：三支团队的踩坑实录
坑 1：容器内路径 ≠ 本机路径
Agent 日志写 Edited /workspace/apps/api/src/main.ts，你在 Mac 上找 /workspace/... 当然没有。要在运维文档写清：逻辑根 → 宿主路径 对照表。
坑 2：只读挂载 + 无写权限工具
部分 CI 为安全把仓只读挂载，Agent 的 write 工具却在内存里「模拟成功」。验收方式：write 后立刻用独立 shell git status，不要信 Agent 自然语言回复。
坑 3：把检索结果当可编辑文件
RAG 返回的 chunk 没有稳定路径，Agent 若「根据检索内容改代码」容易 hallucinate 路径。规范：检索 → 用真实 read 拉工作区文件 → 再 edit。
坑 4：大目录未在 VFS 层过滤
允许 list / 时扫进 node_modules、构建产物，token 爆炸且引入噪声依赖版本信息。应在 VFS 配置 ignore_globs，与 .gitignore 对齐并更严。
AGENTS.md 或 .cursor/rules，与 CI 挂载脚本同源维护，避免「本地能跑、流水线不能写」。VFS 与 RAG、代码图谱如何分工？
三者都帮 Agent「看见」仓库，但层级不同：
- VFS（工作区层）： 可编辑真源；适合「改这一行」「跑测试」。
- RAG / Knowledge Base（检索层）： 不可直接编辑的逻辑文件切片；适合「政策 PDF、历史工单、跨仓文档」。脏数据问题见 PDF 向量库防污染。
- 代码图谱（结构层）： 虚拟「谁调用谁」视图；适合「改接口会影响哪些模块」。深度案例见 大型仓库代码知识图谱。
| 任务 | 优先用 | 避免 |
|---|---|---|
| 改函数实现 | VFS read/write | 只检索旧 chunk |
| 查合规 PDF 条款 | RAG + 来源元数据 | glob 扫全盘 PDF |
| 评估重构影响面 | 代码图谱 + 少量 read | 让模型通读全仓 |
| 长文档单次问答 | 长上下文 + VFS 按需读章节 | 把整本书 embed 进 prompt |
七步验收清单：上线 Agent 前与每月复查
- 画出 VFS 边界图：哪些路径可读、可写、不可见。
- 验证路径映射：容器/远程与本机对照表是否进文档。
- 执行一次「假写入」测试：确认 write 后磁盘真变更。
- 对齐 ignore 规则：
node_modules、密钥、大二进制不进 list。 - 分离检索与编辑：RAG 结果必须经真实 read 再改代码。
- 记录快照版本：远程/MCP 视图标注 commit 或
snapshot_id。 - 审计敏感读：日志记录超出项目根的 read 尝试。
在远程云 Mac 上跑 Agent 时，工作区挂载与本地 IDE 应指向同一 Git 状态。可按 30 分钟 AI 开发环境搭建 固定 SSH 与目录约定，减少「两边 VFS 不一致」。
场景收束：算力与部署放哪一层？
虚拟文件系统本身不占 GPU，但 VFS 背后的解析、索引、沙箱 会吃 CPU 与磁盘 IO：PDF 入库、代码图谱构建、容器 overlay 都在抢同一台机器。
常见拆分：本机/笔记本 做交互式编辑 VFS；专用 Runner 跑批量索引与只读评测 VFS；需要 macOS 专属链（Xcode、某些 CLI）时，用 Macstripe 云 Mac 作为远程工作区挂载点，Agent 通过 SSH 或 MCP 操作同一逻辑根，而不把全盘暴露给模型。
常见问题
虚拟文件系统是不是「模拟盘」？
不完全是。模拟盘强调存储；Agent VFS 更强调权限、投影与工具 API——同一逻辑文件可能来自 Git 快照、overlay 或检索块，而不必是单独分区。
Agent 能直接读我整个硬盘吗？
正规产品默认不能；若工具配置不当或 prompt 诱导执行 shell，仍可能越界。应使用路径白名单与 OS 级沙箱，并审计 read 工具日志。
为什么沙箱里改完文件，仓库没变？
写入发生在 overlay 或会话层，未合并到绑定挂载；或 Agent 只改了内存视图。用 git status 独立验证。
RAG 里的文档算虚拟文件吗？
算逻辑文件视图：有来源 ID 与片段偏移，通常不可直接 write。编辑代码仍以工作区 VFS 为准。
远程 Agent 和本地 Agent 的 VFS 要一致吗？
逻辑上应一致（同一分支、同一根路径约定）。物理路径可以不同，但必须在文档中映射，并标注快照版本。
总结
适合立刻梳理 VFS 的团队： 多环境跑 Agent（本机 + CI + 云 Mac）、接入了 RAG 或 MCP 远程仓、或出现过「Agent 说改了但 git 没动」。
可以暂缓的情况： 仅在本机小仓用只读问答、且不接自动 write 工具。
记住：AI Agent 操作的是文件接口，不一定是你的磁盘真值。 真实文件持久、全局、受 OS 权限约束；虚拟文件为安全、上下文与可复现而裁剪与映射。把两层分清，Agent 才既能干活，又不越界。
延伸阅读：Knowledge Base 与向量库 · 代码知识图谱 · 长上下文与 RAG 分工
