2026 AI Agent 檔案系統設計指南：權限沙箱、分層儲存與完整架構圖

先给结论：给 Agent「整盘读写」是最危险的默认值；2026 年务实做法是 四层 Agent File System（AFS）——工作區可写、记忆与製品分区、工具快取可丢弃，前面加 Policy Gateway 做路徑白名单与稽核。个人验证用 MCP filesystem；團隊生产用遠端 Mac 节点 + 快照工作區。

最後更新於 2026 年 8 月 8 日。文中架构与路徑约定适用于 Claude Code、Cursor Agent、LangGraph 与自研 tool-calling 栈；具体 MCP 实现名因版本而异，分层思想可复用。

如果你正在给 coding agent 接 MCP、或在评估「要不要让 Agent 直接改本機仓库」，真正的问题不是「用不用 filesystem 工具」，而是：哪些路徑可写、写坏了怎么回滚、记忆文件与代码仓库是否混放。这也是 Agent File System（AFS）要解决的问题——它不是替代 ext4/APFS，而是在 Agent 与操作系统之间加一层带策略的虚拟文件视图。

为什么 Agent 不能「直接读硬碟」（Why）

早期 demo 常把 Agent 指向用户主目錄或 monorepo 根目錄，短期省事，长期有三类事故：

1. 越权读取——.env、SSH 私钥、浏览器設定被 read_file 扫进上下文，再经日志或 PR 泄露。
2. 不可回滚的写入——Agent 批量重命名、删除 node_modules 旁的設定，或把 staging 密钥写进源码。
3. 状态与代码耦合——对话摘要、向量索引、构建日志与 Git 跟踪文件混在同一棵树，无法按策略备份或 TTL 清理。

传统 CI 用「一 job 一 workspace」解决类似问题（参见 iOS CI 与遠端 Mac 打包）。Agent 同样需要：执行边界先于模型能力——模型再强，写错目錄照样炸。

Agent File System 四层分类（What）

把 Agent 能「看到」的路徑收成四层，每层独立挂载策略与生命周期：

非对称结论： 多数團隊翻车点在 L1 与 L2 混用——把「用户偏好 JSON」写在仓库里并提交 Git，导致合并冲突与隐私泄露；记忆应走 独立 Memory 层，而不是另一个文件夹。

完整架構圖（How it fits together）

下图是推荐的生产拓扑：Agent 运行时只通过 Policy Gateway 访问四层儲存；底层可落在本地磁碟、容器 volume，或 遠端 Cloud Mac 节点。

┌─────────────────────────────────────────────────────────────────────────────┐
│                         Agent Runtime（Claude Code / Cursor / LangGraph）      │
└───────────────────────────────────┬─────────────────────────────────────────┘
                                    │ tool calls (read/write/list/glob)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Policy Gateway（路徑策略 + 稽核 + 速率限制）                  │
│   allow: /workspace/** RW   |   deny: ~/.ssh, /etc, ../outside-root          │
└───────────────────────────────────┬─────────────────────────────────────────┘
                                    │
          ┌─────────────────────────┼─────────────────────────┐
          ▼                         ▼                         ▼
┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│  L1 Workspace    │    │  L2 Memory Store │    │  L3 Artifacts    │
│  当前任务可写区     │    │  摘要/偏好/向量索引  │    │  构建产物/日志/报告  │
│  git clone 沙箱  │    │  SQLite/Redis/PG │    │  只读或 TTL 清理    │
└────────┬─────────┘    └────────┬─────────┘    └────────┬─────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                    ┌────────────────────────┐
                    │  L4 Tool Cache         │
                    │  npm/pip/derived index │
                    │  可重建、可整区删除       │
                    └────────────┬───────────┘
                                 ▼
                    ┌────────────────────────┐
                    │  Host Volume / Remote  │
                    │  Mac Node（Cloud Mac）  │
                    └────────────────────────┘

关键设计决策：

• Gateway 是唯一入口——禁止 Agent 进程直接 open() 宿主机路徑；所有读写经 MCP / 自定义 FS API。
• L1 与 L3 分离——构建产物不要写回 Git 工作區；Agent 读製品时走只读挂载。
• L4 默认可丢——快取目錄不进 nightly backup，缩小 RPO/RTO。
• 遠端节点 = 移动 L1——SSH 到 Cloud Mac 时，/workspace 即该会话的完整 blast radius。

核心对比：三种 AFS 实现路徑

真正分水岭不是「能不能 list 目錄」，而是 策略是否可版本化、可稽核、可在一键之内销毁工作區。

場景怎么选（决策矩阵）

推荐组合（Stack）

组合 A — 个人最快（1 天）

• MCP filesystem：allowed_directories 仅含项目根
• .cursorignore / .claudeignore 排除 .env*、*.pem
• 记忆先用项目内 .agent/memory.json（不进 Git）——仅适合单人

组合 B — 小團隊生产（推荐）

• Cloud Mac 节点：每任务 /workspace/<job-id> 目錄 + APFS 快照
• Policy Gateway：YAML 声明 allow/deny 路徑前缀
• L2 用 Postgres 或 Redis（见 Memory 文）；L3 对象儲存或 /artifacts
• 稽核：每次 write 记 path, agent_id, diff_hash

组合 C — 企业合规

• L1 仅挂载客户授权的 sparse checkout
• 密钥走 vault；Agent 上下文永不包含明文 token
• 工作區生命周期：任务结束自动销毁 volume

常见誤區

1. 把 MCP root 设成 ~——等于把整台电脑交给模型。
2. 记忆文件 commit 进 Git——冲突、泄露、无法按用户删除（GDPR）。
3. 製品与源码同目錄——Agent glob **/* 把 2GB 构建产物塞进上下文。
4. 无写前快照——一次错误 rm -rf 无法恢复。
5. 快取当永久儲存——删快取后 Agent「失忆」其实是路徑依赖未解耦。
6. 本地与遠端混用路徑——开发机 /Users/foo/project 与 CI /workspace 設定双份漂移。

落地步骤（7 步 Action Plan）

1. 画出四层目錄表——列出 L1–L4 实际绝对路徑与负责人。
2. 定义 Policy YAML——allow/deny 前缀、单文件大小上限、扩展名黑名单。
3. 接入 Gateway——所有 Agent 工具调用经同一 FS 服务，禁止旁路。
4. 分离 Memory——从仓库移除已提交的 .agent/*；迁到 L2 儲存。
5. 設定快照或 Git worktree——L1 每次任务前创建恢复点。
6. 挂载 Artifacts 只读——构建流水线写 L3，Agent 仅 read。
7. 跑 7 天红队——故意让 Agent 读取 ../.ssh、写 /etc，验证 deny 生效。

Policy Gateway 設定示例

# afs-policy.yaml
version: 1
workspace_root: /workspace
rules:
  - action: allow
    paths: ["/workspace/**"]
    modes: [read, write, list]
  - action: allow
    paths: ["/memory/**"]
    modes: [read]
  - action: allow
    paths: ["/artifacts/**"]
    modes: [read]
  - action: allow
    paths: ["/cache/**"]
    modes: [read, write, delete]
  - action: deny
    paths: ["**/.env", "**/.env.*", "**/id_rsa", "**/.ssh/**"]
  - action: deny
    paths: ["../**", "/etc/**", "/var/**"]
max_file_bytes: 5242880
audit_log: /var/log/afs-audit.jsonl

FAQ

Agent File System 和操作系统檔案系統是什么关系？

AFS 是逻辑视图 + 策略层，底层仍可用 APFS、ext4 或网络卷。Agent 不应直接感知 OS 路徑，只应看到 Gateway 暴露的虚拟树。

MCP filesystem 够用于生产吗？

个人与小團隊内测够；生产还需要稽核、快照、多租户隔离与集中策略——通常要自建 Gateway 或遠端工作區。

L2 Memory 能用 Git LFS 吗？

不推荐。记忆需要按用户删除、加密与 TTL；应用数据库或对象儲存更合适。

遠端 Mac 节点如何对齐 AFS？

登录后将 /workspace 设为唯一可写区；git clone 在会话内完成；任务结束销毁目錄或回滚快照。详见 說明中心 与 方案定價。

如何防止 Agent 读太多文件撑爆上下文？

Gateway 层限制单次 list 条数、禁止无 glob 的递归 **，并对 read 做累计 token 预算。

总结

2026 年设计 Agent File System，核心不是「给工具加 read_file」，而是 用四层分区 + Policy Gateway 把执行边界写进基础设施。个人从 MCP 白名单起步；團隊把 L1 放到可快照的遠端 Mac 工作區，Memory 与 Artifacts 绝不与 Git 混放。

上线前自问：如果 Agent 此刻执行 write，最坏能破坏哪一层？ 若答案是「整台电脑」，你还缺 AFS。

遠端 Mac 工作區检查清单

把 AFS 映射到 Cloud Mac 节点时，请把会话当成可销毁的 CI Runner：

• /workspace 使用独立卷，不要与系统盘混用。
• 在 workspace 内 git clone --depth 1；不要用 SSHFS 挂载开发者笔记本目錄。
• 首次 Agent 写入前打快照，并用 task_id 标记便于客服复现。
• 稽核日志实时传出节点；假设工作區卷可能每小时被清空。
• L2 Memory 放在区域级数据库，不要把用户 embedding 只存在 Mac 卷里。

与 OpenClaw 遠端构建 联用的團隊，常把同一套快照纪律同时用于编译任务与 Agent 改码会话，减少「我本機能跑」的环境漂移。

延伸阅读

• 自建 Agent Memory vs SaaS 選型 →
• OpenClaw 遠端 Mac 自動化 →