Mirage：面向 AI 智能体的统一虚拟文件系统

构建能够与现实世界数据交互的 AI 智能体通常是一场支离破碎的噩梦。你最终不得不处理十几种不同的 SDK，管理每个服务的身份验证，并编写自定义的胶水代码，仅仅是为了让智能体从 S3 读取文件并向 Slack 发布摘要。

Mirage 通过将每个后端视为单一统一虚拟文件系统 (VFS) 的一部分，改变了这一范式。你无需教智能体如何使用 Slack API、GitHub API 和 S3 SDK，只需将它们挂载为目录即可。你的智能体随后可以使用它已经熟悉的 Unix 工具——ls、cat、grep、cp——来与整个技术栈进行交互。

为什么 Mirage 很重要

现代大语言模型 (LLM) 在海量的代码和文档语料库上进行了训练，这使它们在 bash 和文件系统语义方面表现得极其流利。通过将远程服务抽象为文件系统，Mirage 利用了这种现有的“知识”，从而最大限度地减少了幻觉和 API 特有的错误。

主要优势包括：

统一抽象：无论是 Google Drive、Redis 还是本地目录，它们看起来都像是一个标准的文件树。
Bash 原生：智能体使用标准的命令行工具即可跨服务执行复杂操作。
可移植工作区：你可以将整个环境（包括远程数据状态）快照到一个文件中，使智能体的运行过程可复现且易于调试。
框架无关：它与 OpenAI Agents SDK、Vercel AI SDK、LangChain 和 Pydantic AI 无缝集成。

工作原理

Mirage 在你的智能体和基础设施之间充当中间件层。它使用调度程序和双层缓存系统，以确保智能体的交互既高效又可靠。

缓存层

频繁调用远程 API 既缓慢又昂贵。Mirage 实现了一个强大的双层缓存：

索引缓存 (Index Cache)：存储目录列表和元数据。后续的 ls 或 find 命令将命中本地索引，直到 TTL（生存时间）过期。
文件缓存 (File Cache)：存储对象字节。第一次读取时从源头流式传输，后续读取则直接由本地缓存提供服务。

你可以配置它们使用 RAM 来处理临时任务，或使用 Redis 来处理持久化的多工作节点环境：

const ws = new Workspace(
  { '/s3': new S3Resource({ bucket: 'my-bucket' }) },
  {
    cache: new RedisFileCacheStore({ url: 'redis://localhost:6379/0', limit: '8GB' }),
    index: new RedisIndexCacheStore({ url: 'redis://localhost:6379/0', ttl: 600 }),
  }
);

入门指南

Mirage 提供了 Python 和 TypeScript 的 SDK，可以轻松嵌入到你现有的 FastAPI 或 Express 应用程序中。

Python 快速示例

from mirage import Workspace
from mirage.resource.s3 import S3Resource
from mirage.resource.ram import RAMResource

# 挂载多个源
ws = Workspace({
    "/data": RAMResource(),
    "/s3": S3Resource(bucket="my-logs")
})

# 执行跨服务操作
await ws.execute("cp /s3/report.csv /data/local.csv")
await ws.execute("grep 'error' /data/local.csv | wc -l")

为什么你应该使用它

如果你正在构建自主智能体，你可能花费了太多时间编写将自然语言映射到特定 API 调用的“工具调用”逻辑。Mirage 允许你定义一次工作区，并让智能体自然地在其中导航。

通过使用 Mirage，你构建的不仅仅是一个智能体，而是一个可复现的环境。由于工作区可以进行快照，你可以获取一个运行失败的智能体实例，导出 demo.tar 快照，并准确检查智能体在失败时刻所看到的内容。

对于使用 Claude Code 或类似基于 CLI 智能体的开发者，Mirage 提供了一个轻量级守护进程，允许这些智能体访问你的云基础设施，就像访问本地文件夹一样，从而在无需为每个服务定义自定义工具的情况下，显著扩展了它们的实用性。

来源

strukto-ai/mirage: A Unified Virtual Filesystem For AI Agents