AI Agent 如何安全修改檔案？Virtual File System 最佳實踐

1. 為什麼 Agent 不能直接改真檔案

編碼 Agent 的工具呼叫看起來只是「改幾個檔案」，但失敗模式與人工誤操作不同：模型會自信地批量執行，且常在無監督循環裡重試。

風險	典型觸發	後果
路徑越界	../../.env	金鑰洩露、系統損壞
破壞性命令	rm -rf	倉庫不可構建、資料遺失
半寫入	重構中途崩潰	型別檢查失敗、灰度踩雷
不可審計	無 diff 的 shell 修改	無法 Code Review

可參考站內 Agent 時代帳單拆解：誤操作後的回滾與值班也是隱性成本。

2. VFS 是什麼：三層視圖

1. Base（唯讀）：乾淨樹快照，Agent 不應永久修改。
2. Overlay（可寫）：所有修改只落在這裡。
3. Publish（合併）：審查與測試通過後才合併到真實工作區。

與 多 Agent 四種架構 的 Executor 隔離一致。

3. 四種常見實作模式

模式	機制	優點
Git worktree	臨時分支	與 PR 流程無縫
OverlayFS / 容器	Docker 可寫層	強隔離、易銷毀
遠端沙箱	每次任務新 VM	最強隔離
IDE 虛擬層	工具 API + 規則	人機協同好

4. 權限與白名單

• 僅允許 $WORKSPACE/**
• .env*、secrets/ 預設唯讀
• 檔案 API 與 shell 雙重閘門

5. 原子寫入與回滾

寫入先進 overlay → 產生 unified diff → 原子 rename 或單次 commit → 綁定 run_id 一鍵還原。

6. 金鑰隔離

執行環境注入占位符；日誌與 diff 脫敏；限制 egress。

7. 落地範例

def safe_resolve(path: str) -> Path:
    p = (SANDBOX / path).resolve()
    if not str(p).startswith(str(SANDBOX)):
        raise PermissionError("path escape")
    return p

8. 檢查清單

• ☐ 無限制 shell 禁止
• ☐ 可寫路徑白名單
• ☐ 每次運行可回滾
• ☐ 長駐 Agent 跑在獨享主機

9. 常見問題

VFS 會拖慢 Agent 嗎？

overlay 開銷通常是毫秒級，遠低於 LLM 往返。

小團隊最低配？

專用分支 + PR，禁止推 main。

與 Docker 衝突嗎？

唯讀掛載程式碼 + 可寫層即可。

多 Agent 並行？

每 Agent 一個 worktree，由 integrator 合併。

Cursor 算 VFS 嗎？

受控工具 + 工作區規則，本質相同抽象。

雲端 Mac 的關係？

長駐 Agent 需要可快照的獨享檔案系統。

延伸閱讀

• 多 Agent 四種架構 →
• MCP 新手指南 →