症狀： 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 分工
