AFS：跨 Agent 文件共享

每个 Workspace 都有自己独立的文件系统——这是 Workspace 隔离性的基础，但也意味着 A 写下的文件 B 默认看不到。当多个 Agent 需要协作交付一份产物时（比如 planner 拆任务、worker 各做一段、最后归档），就需要一个可控的方式把文件在 Workspace 之间共享。

AFS（Agent File System） 是 Neutree Agent Platform 为此提供的能力：一套带权限的共享文件系统，对 Agent 来说就是容器里的一个目录，对用户来说是 文件 app 里的「网盘」标签。

它解决什么问题

不用 AFS 时，跨 Workspace 传文件只能靠把内容塞进对话或者经第三方对象存储中转——前者把上下文撑爆，后者多一层凭据管理。AFS 把这一层做成基础设施：

• 以路径共享，不以内容共享——Agent 把文件写到共享目录，对方直接在自己的容器里以同一个路径读到，不需要序列化、不需要传输
• 权限可控——共享方决定谁能访问、是只读还是可写
• 撤回干净——共享方解除分享后，所有挂载点立即失效

看得见的部分

用户视角：文件 app 的「网盘」标签

打开 Workspace 的 文件 app，顶部有两个标签：

• 本地——这个 Workspace 自己的文件系统
• 网盘——当前 Workspace 能看到的所有共享目录

「网盘」根目录下每一项是一个共享目录：你创建的，或者别的 Workspace 分享给你的。你可以：

• 新建共享目录——给它起个名字（小写字母、数字、连字符），它会同时挂载到你自己的 Workspace
• 管理成员——把这个共享目录授权给你自己其他的 Workspace 访问，选只读或读写
• 解除分享——取消某个成员的访问，或者把整个共享目录销毁

共享目录在所有挂载方那里都呈现为同一个路径 /mnt/afs/<name>——这是 AFS 的核心契约：路径稳定，跨 Workspace 不变。

Agent 视角：平台 MCP 工具

Agent 不直接看 web 界面，它通过平台内置的 MCP 工具来管理共享。这些工具开箱即用，不需要单独配置：

• share_folder(name)——创建/确保一个共享目录，挂到自己 Workspace 的 /mnt/afs/<name>
• grant_access(name, slug, readonly?)——把这个共享目录授权给另一个 Workspace（用它的 slug 标识），目标 Workspace 立即看到同名路径
• unshare_from_all(name)——撤销目录的所有共享，并销毁底层存储

也就是说，Agent 可以在对话中自主完成”建共享 → 写文件 → 授权给协作方 → 调用对方”的整套流程，不需要人工介入。

一个典型流程：call_agent + AFS

一个常见的协作场景：parent agent 准备好一份资料，让 child agent 基于这份资料完成下一步。直接把内容粘进 prompt 会撑爆上下文，借 AFS 就很顺：

1. parent 调用 share_folder("task-2026-05")——拿到挂载点 /mnt/afs/task-2026-05/
2. parent 把要交接的文件写进这个目录（用平时用的文件工具，路径就是普通文件）
3. parent 调用 grant_access("task-2026-05", "child-agent", readonly=true)——child 的 Workspace 立即在同名路径下看到这些文件
4. parent 调用 child agent（参见 多 Agent 协作），prompt 里只需引用路径："请处理 /mnt/afs/task-2026-05/ 下的文件"
5. child 在自己的容器里直接读路径，完成任务，可以把产物写回（如果授权是 read_write）或写到自己 Workspace 的本地

工作原理（科普）

这一节是给好奇底层的同学准备的，不影响使用。

AFS 是一套独立的组件（Rust 实现），由两类进程组成：

• afs-controller——中心化的元数据 + 鉴权服务，gRPC 接口，元数据存在 SQLite。负责注册存储后端、创建/销毁共享目录、记录哪些主机挂载了哪些目录
• afs-fuse——每台 agent 主机上跑一份的 FUSE 守护进程，gRPC 接口。收到挂载指令后基于 FUSE 在指定路径暴露共享目录，文件读写代理到对应的存储后端

存储后端目前支持两类：

• local——共享 controller 所在主机的本地目录（适合单机或共享卷）
• nfs——挂载一个 NFS export，让所有 agent 主机共享同一份数据

每个共享目录在创建时由 controller 分配一个不可变的 access_key，访问凭据和挂载时的只读/读写由 gRPC 调用强制——任何主机要挂载这个目录都必须出示正确的 key，撤销时 controller 通知所有挂载方的 afs-fuse 强制 unmount，业务容器里那个路径瞬间消失。

在 Neutree Agent Platform 里，这套组件的形态是：集群里跑一份 afs-controller，每个 Workspace pod 注入一个 afs-fuse sidecar；控制面把上面那一层”用户/Workspace/分享关系”的语义映射到 controller 的”目录/挂载/access_key”模型——所以用户和 Agent 看到的是「网盘」和 MCP 工具，不直接和 access_key、目录 ID 这些底层概念打交道。

对 Agent 和用户来说，这些都是透明的——看到的就是一个目录。

几条使用建议

目录名要稳定——Agent 之间约定的 slug + 目录名一旦写进 prompt 或 skill，改名会断引用。命名时想清楚。

默认只读，需要协作回写再开 read_write——只读分享不会有竞争写问题，更安全。需要 child agent 写回产物时再单独开权限。

用完销毁——一次性任务结束后，用 unshare_from_all 把共享目录回收，避免共享列表越积越长。长期协作的”团队网盘”性质的目录则可以保留。

不要把 AFS 当对象存储用——AFS 设计目标是 Agent 协作时的文件交接，不是大规模冷存储。文件量级和访问模式都按”工作目录”来理解。