9. 运行时文件系统（AGFS）

AGFS 是 FlowNex 自建的 Agent Graph File System，用于承载 Agent 运行时文件、任务产物、多 Agent 协作文件、文件版本、快照回滚和知识候选沉淀。

AGFS Agent 运行时文件世界

它是 FlowNex 与普通 2C Agent 产品、普通 OSS 附件系统之间的重要分水岭。

9.1 为什么需要 AGFS

Agent 执行任务时会产生大量文件：

  1. 用户上传附件。
  2. 中间数据。
  3. 清洗结果。
  4. 脚本输出。
  5. 日志。
  6. 图表。
  7. 报告。
  8. 最终交付物。

如果这些文件只存在本地临时目录或普通 OSS 中，会出现几个问题：

  1. 跨轮无法稳定继续使用。
  2. 跨实例恢复复杂。
  3. 多 Agent 无法实时共享。
  4. 文件被脚本误删后难以恢复。
  5. 文件版本和任务血缘不可追踪。
  6. 高价值产物难以沉淀为知识资产。

AGFS 的目标是让 Agent 的文件世界具备企业级基础设施能力：

可共享
可追踪
可版本化
可回滚
可审计
可沉淀

9.2 AGFS 与普通 OSS 文件管理的区别

OSS 是对象存储，不是文件系统。

OSS 适合保存文件正文，但不擅长处理：

  1. 目录。
  2. 重命名。
  3. 随机写。
  4. 文件版本语义。
  5. 多 Agent 实时协作。
  6. 文件系统级快照。
  7. POSIX 风格工具兼容。

AGFS 在 OSS 之上提供文件系统语义。

能力 普通 OSS AGFS
文件正文存储 支持 支持，底层可复用 OSS
目录树 需要模拟 原生元数据建模
路径读写 不友好 标准文件路径
多 Agent 共享 弱 强
版本历史 需要业务自建 文件级版本
快照回滚 不支持 workspace / task checkpoint
文件血缘 不支持 关联任务、消息、Skill、Agent
工具透明访问 弱 可通过 FUSE 支持

9.3 AGFS 核心概念

AGFS 的核心概念包括：

  1. Space：文件空间，例如用户空间、项目空间、任务空间。
  2. Mount：运行时挂载实例，绑定某个空间根节点。
  3. FileNode：文件或目录节点。
  4. FileVersion：单文件版本。
  5. Checkpoint：某个时刻的空间快照。
  6. VersionTree：用于快速路径解析和一致性判断的内存树。
  7. ShadowDir：不上云的本地目录。
  8. FileEvent：文件生命周期事件。
  9. RuntimeFileAsset：文件与业务任务的关系。

9.4 Space / Mount / File Node / Version / Checkpoint

Space

Space 表示一棵文件树的业务归属。

建议类型：

  1. USER_SPACE：用户个人空间。
  2. PROJECT_SPACE：项目共享空间。
  3. CONVERSATION_SPACE：会话空间。
  4. TASK_SPACE：任务临时空间。
  5. TEAM_SPACE：团队共享空间。

Mount

Mount 表示运行时将某个 Space 挂载到某个 workspace 路径。

挂载参数包括：

  1. spaceType。
  2. rootFileId。
  3. mountPath。
  4. tenantCode。
  5. userId。
  6. conversationId。
  7. taskId。

Mount 的设计允许沙箱先启动，等任务认领时再动态挂载具体项目空间。

File Node

File Node 表示目录或文件。

字段建议：

  1. fileId。
  2. parentId。
  3. name。
  4. nodeType。
  5. mimeType。
  6. size。
  7. version。
  8. objectKey。
  9. shadowFlag。
  10. deleteFlag。

File Version

File Version 表示单个文件的一次内容版本。

字段建议：

  1. versionId。
  2. fileId。
  3. versionNo。
  4. objectKey。
  5. contentHash。
  6. size。
  7. createdByAgent。
  8. createdByTaskId。
  9. createTime。

Checkpoint

Checkpoint 表示一组文件节点在某个时间点的快照。

适用场景：

  1. Agent 执行前自动 checkpoint。
  2. 多 Agent 子任务开始前 checkpoint。
  3. 用户手动保存 checkpoint。
  4. Reviewer 发现问题后回滚。

Checkpoint 可以支持：

  1. 后向回滚。
  2. 前向保留。
  3. 文件级恢复。
  4. 目录级恢复。
  5. 任务级恢复。

9.5 MCP / Shell / FUSE / HTTP File API

AGFS 应提供多种访问入口。

MCP

MCP 入口面向 LLM 和 Agent。

适合能力：

  1. 列目录。
  2. 读文件。
  3. 写文件。
  4. 搜索文件。
  5. 创建 checkpoint。
  6. 恢复版本。

Shell

Shell 入口面向运行时和高级用户。

适合场景：

  1. cat。
  2. ls。
  3. grep。
  4. python script.py。
  5. npm build。

FUSE

FUSE 入口用于让现成工具透明访问 AGFS。

适合场景：

  1. npm。
  2. git。
  3. Python。
  4. Office 文档转换。
  5. 数据处理工具。

HTTP File API

HTTP File API 是 AGFS Server 的统一协议层。

所有入口最终应归一到同一套 API，避免 MCP、Shell、FUSE 各自实现业务逻辑。

9.6 Version Tree

Version Tree 用于将高频路径解析从网络操作变为内存操作。

Agent 执行任务时会频繁调用：

  1. ls。
  2. stat。
  3. open。
  4. read。
  5. grep。

如果每次都查询远程元数据服务，性能会不可接受。

Version Tree 的基本思想：

  1. 每个节点有单调递增版本号。
  2. Server 内存维护当前文件树。
  3. 后台定期检查根节点版本。
  4. 远端版本更新时增量或局部刷新。
  5. 本地写操作期间通过操作计数器避免竞态刷新。

目标是让大部分路径解析走本地内存，同时保证多 Agent 协作时不会长期读到旧状态。

9.7 Close-to-Open 一致性

多 Agent 共享文件时，一致性非常重要。

默认建议采用 close-to-open 一致性：

  1. 一个 Agent 写入并 close 文件后。
  2. 另一个 Agent reopen 文件时需要校验版本。
  3. 同一个文件句柄内的多次读写不重复校验。

这样可以在性能和正确性之间取得平衡。

一致性策略建议支持两档：

策略 适用场景 特点
CTO 多 Agent 互读产物 open 时校验版本，默认推荐
RELAXED 延迟优先场景 依赖后台同步，可能短暂读旧

9.8 Shadow Dir

Shadow Dir 用于处理不应进入云端主树的本地目录。

典型目录：

  1. node_modules。
  2. .venv。
  3. vendor。
  4. .cache。
  5. 构建临时目录。

这些目录特点：

  1. 文件数量巨大。
  2. 可重建。
  3. 只对当前运行环境有意义。
  4. 上传云端价值低。
  5. 会拖慢元数据和对象存储。

Shadow Dir 的策略是：

  1. 在 mkdir 时识别特定 basename。
  2. 在元数据树中标记为 shadow。
  3. 后续子树读写重定向到客户端本地路径。
  4. 不写入对象存储。
  5. 不进入 AGFS 主版本树。

9.9 文件版本与快照回滚

AGFS 需要同时支持单文件版本和 workspace checkpoint。

单文件版本适合：

  1. 恢复某个文件的历史版本。
  2. 对比文件修改。
  3. 找回误覆盖内容。

Checkpoint 适合：

  1. 回滚整个任务期间的变更。
  2. 回滚某个目录。
  3. 多 Agent 子任务失败后撤回。
  4. 用户明确要求“回到刚才那个版本”。

任务执行前建议自动创建 checkpoint。

当任务成功且用户接受结果时，可以保留 forward 状态；当任务失败或用户不满意时，可以 rollback 到执行前。

9.10 多 Agent 共享工作区

AGFS 是多 Agent 协作的文件底座。

多 Agent 共享工作区需要满足：

  1. 多个 runtime 实例挂载同一个 project_space。
  2. 一个 Agent 写入的文件，其他 Agent 可及时读取。
  3. 文件修改事件可被记录。
  4. 子任务产物可被 Reviewer 和 Synthesizer 使用。
  5. 每个 Agent 的修改可以通过 checkpoint 区分和回滚。

示例：

Researcher 写入 /workspace/research/context.md
DataAgent 写入 /workspace/data/analysis.xlsx
Writer 读取上述文件并写入 /workspace/output/report.md
Reviewer 读取 report.md 并写入 /workspace/review/comments.md
Synthesizer 汇总最终输出

9.11 文件血缘与知识候选沉淀

AGFS 文件需要和业务对象建立关系。

建议记录：

  1. 文件由哪个任务生成。
  2. 文件由哪个 Task Step 生成。
  3. 文件由哪个 Agent 角色生成。
  4. 文件由哪个 Skill 生成。
  5. 文件读取了哪些输入文件。
  6. 文件是否被用户下载或采纳。
  7. 文件是否被多次复用。
  8. 文件是否被标记为知识候选。

文件沉淀路径：

EPHEMERAL
  -> FINAL_ARTIFACT
  -> CONTEXT_FILE
  -> KNOWLEDGE_CANDIDATE
  -> KNOWLEDGE_ASSET

注意：

AGFS 文件进入 KNOWLEDGE_CANDIDATE 后，并不意味着自动进入 OpenViking 知识库。它应先进入知识中心草稿，经过人工或规则审核后，再进入组织知识治理流程。