传统的检索增强生成在文档助手场景中面临一个根本性瓶颈：向量检索只能返回与查询语义最接近的文本片段，当答案跨越多个页面或用户需要精确语法而该内容未进入 Top-K 结果时，系统便无能为力。Mintlify 提出的 ChromaFs 架构从根本上重新定义了 AI 与文档交互的方式 —— 用虚拟文件系统替代向量检索，让 AI Agent 像操作真实代码仓库一样探索文档。
传统方案的困境在于基础设施成本与延迟的矛盾。为 Agent 提供文件系统能力的常规做法是启动隔离沙箱并克隆代码仓库，这种方案在异步后台 Agent 场景下可以接受，因为延迟不是首要考量。但在用户面对的前端助手场景中，等待时间变得不可接受 ——Mintlify 当时的 P90 会话创建时间约为 46 秒。更关键的是，按照每月 85 万次对话计算，即便使用最 minimal 的沙箱配置（1 vCPU、2 GiB 内存、5 分钟会话生命周期），年度计算成本也将超过 7 万美元。
ChromaFs 的核心洞察是：Agent 不需要一个真实的文件系统，只需要文件系统的幻象。文档已经被索引、分块并存储在 Chroma 向量数据库中以支持搜索，因此只需在此基础上构建一个虚拟文件系统层，将 UNIX 命令翻译为向量数据库查询即可。这一设计将启动时间从 46 秒缩短至约 100 毫秒，同时由于复用了已有的数据库基础设施，边际对话成本降至几乎为零。
虚拟文件系统的实现基于 Vercel Labs 开发的 just-bash，这是一个 TypeScript 重写的 bash 实现，支持 grep、cat、ls、find 和 cd 命令，同时暴露可插拔的 IFileSystem 接口。ChromaFs 拦截所有文件系统调用并将其翻译为 Chroma 查询，而 just-bash 负责解析、管道和标志逻辑。
路径树的引导是首个关键工程点。ChromaFs 需要在 Agent 执行任何命令前知道有哪些文件存在。解决方案是将整个文件树存储为 gzipped JSON 文档，存入 Chroma 集合中的特殊键 __path_tree__。该 JSON 结构包含每个路径的访问权限元数据，如 auth/oauth 标记为公开，而 internal/billing 仅限 admin 和 billing 组访问。服务器初始化时获取并解压该文档，在内存中构建两个结构：一个路径 Set 和一个目录到子项的 Map。由于树结构被缓存，同一站点的后续会话完全跳过 Chroma 获取，ls、cd 和 find 命令直接在本地内存解析，无需任何网络调用。
页面重组机制解决了分块与完整性的矛盾。Chroma 中的文档按页面分块以生成向量嵌入，当 Agent 执行 cat /auth/oauth.mdx 时，ChromaFs 按 page slug 查询所有匹配的分块，按 chunk_index 排序后拼接为完整页面。重组结果会被缓存，确保同一会话中重复读取同一文件不会再次触发数据库查询。对于存放在客户 S3 存储桶中的大型 OpenAPI 规范文件，系统采用延迟加载策略 —— 在目录列表中显示文件指针，但仅在实际执行 cat 命令时才拉取内容。
grep 命令的工程实现最具技术含量。直接对虚拟文件系统中的每个文件进行网络扫描会极其缓慢。ChromaFs 采取两层过滤策略：首先将 just-bash 的 grep 拦截，解析标志后翻译为 Chroma 查询（固定字符串使用 $contains 操作符，正则表达式使用 $regex）。Chroma 作为粗筛层识别哪些文件可能包含匹配内容，然后将这些分块批量预取到 Redis 缓存。随后将 grep 命令重写为仅针对已匹配文件的内存执行，交给 just-bash 进行精筛。这种架构下，大型递归查询可在毫秒级完成。
访问控制作为一等公民内置于架构中。传统沙箱方案需要管理 Linux 用户组、chmod 权限或为每个客户层级维护隔离的容器镜像。ChromaFs 在构建文件树前，根据当前用户的会话令牌过滤路径树，移除用户无权访问的路径。由于过滤发生在树构建阶段，Agent 完全无法访问或引用已被剪枝的路径，实现了细粒度的基于角色访问控制。
关键工程参数方面，P90 启动时间控制在 100 毫秒以内，chunk 缓存建议设置为会话级或站点级，Redis 批量预取阈值可根据实际文档规模调整，路径树 JSON 的压缩比通常可达 70% 以上。对于实现类似系统的团队，建议初始路径树大小控制在 1 MB 以内以确保快速加载，grep 粗筛阶段返回的候选文件数量建议限制在 100 个以内以控制 Redis 缓存压力。
ChromaFs 架构的实质是将语义层抽象提升到文件系统层面进行操作，而非在向量空间中漫无目的地检索。当 AI Agent 能够使用 cd 导航目录结构、使用 grep 定位精确内容、使用 cat 获取完整页面时，文档助手的可用性和可靠性获得了质的飞跃。这种设计模式为 RAG 替代方案提供了一个可落地的工程范式。
资料来源：https://www.mintlify.com/blog/how-we-built-a-virtual-filesystem-for-our-assistant