Mirage：AI Agent 的统一虚拟文件系统，把 S3、Google Drive 当本地目录用

AI Agent 在处理文件时有个痛点：它们需要访问各种不同的存储系统——本地文件、S3、Google Drive、Azure Blob——但每个系统的 API 都不一样，Agent 需要为每种存储写不同的代码。

Mirage 是一个新开源项目，它为 AI Agent 提供了一个统一的虚拟文件系统接口。不管底层是 S3、Google Drive 还是本地磁盘，Agent 看到的都是一个普通的目录树，用标准的文件操作 API 就能读写。

项目简介

Mirage（项目地址：https://github.com/strukto-ai/mirage）由 Strukto AI 团队开发，是一个面向 AI Agent 的虚拟文件系统层。它的核心思想是：给 AI Agent 一个”看起来像本地文件系统”的统一接口，底层连接各种实际存储后端。GitHub 上已经获得超过 700 Star。

解决什么问题

AI Agent 在执行任务时经常需要读写文件。传统的做法是为每种存储系统写专门的集成代码：

• 读 S3 → 用 boto3 的 API
• 读 Google Drive → 用 Google Drive API
• 读本地文件 → 用 open() 或 os 模块
• 读 Azure Blob → 用 Azure SDK

这意味着 Agent 的代码里充斥着各种存储 SDK 的调用，代码复杂、难以维护，而且每新增一种存储后端都要改代码。

Mirage 的做法是抽象出一层”虚拟文件系统”，Agent 只需要用标准的文件操作（读、写、列目录、移动、删除），Mirage 负责把这些操作转发到对应的存储后端。

支持的存储后端

• 本地文件系统：标准的本地磁盘读写
• Amazon S3：包括 S3 兼容的 MinIO、阿里云 OSS、腾讯云 COS
• Google Drive：读写 Google Drive 中的文件和文件夹
• Azure Blob Storage：微软云存储
• 内存存储：临时文件存储，适合测试和缓存场景

安装

pip install mirage-fs

或者从源码安装：

git clone https://github.com/strukto-ai/mirage.git
cd mirage
pip install -e .

使用方法

基础用法：挂载本地目录

from mirage import VirtualFS

# 创建虚拟文件系统，挂载本地目录
fs = VirtualFS()
fs.mount("local", "local:///home/user/projects")

# 像操作普通文件系统一样使用
files = fs.listdir("local")
content = fs.read("local/myfile.txt")
fs.write("local/output.txt", "Hello, Mirage!")

挂载 S3

from mirage import VirtualFS

fs = VirtualFS()

# 配置 S3 后端
fs.mount("data", "s3://my-bucket/data", config={
    "aws_access_key_id": "YOUR_KEY",
    "aws_secret_access_key": "YOUR_SECRET",
    "region_name": "us-east-1"
})

# 列出 S3 中的文件
files = fs.listdir("data")

# 读取 S3 中的文件
content = fs.read("data/report.csv")

# 写入 S3
fs.write("data/results.json", json.dumps(results))

多后端组合

from mirage import VirtualFS

fs = VirtualFS()

# 同时挂载多个后端
fs.mount("local", "local:///home/user/work")
fs.mount("cloud", "s3://my-bucket/shared")
fs.mount("drive", "gdrive:///My Documents")

# 在不同后端之间复制文件
content = fs.read("drive/report.docx")
fs.write("local/report.docx", content)
fs.write("cloud/backup/report.docx", content)

在 AI Agent 中使用

Mirage 特别适合与 AI Agent 框架集成。以下是一个与 LangChain 集成的示例：

from mirage import VirtualFS
from mirage.tools import create_file_tool

fs = VirtualFS()
fs.mount("workspace", "s3://agent-bucket/workspace")

# 创建 Agent 可用的文件工具
read_tool = create_file_tool(fs, action="read")
write_tool = create_file_tool(fs, action="write")
list_tool = create_file_tool(fs, action="list")

# 将工具传给 Agent
agent = initialize_agent(
    tools=[read_tool, write_tool, list_tool],
    llm=your_llm
)

核心特性

• 统一接口：所有存储后端使用相同的 read/write/listdir/mkdir/delete API
• 路径透明：Agent 不需要知道文件在哪个后端，用统一的路径访问
• 懒加载：只在实际访问时才连接存储后端，减少不必要的连接开销
• 缓存支持：可配置本地缓存，减少重复的远程读取
• 权限控制：可以为不同挂载点设置读写权限
• 错误处理：统一的错误处理机制，不同后端的错误都会被标准化

适合场景

• AI Agent 开发：为 Agent 提供统一的文件访问能力，不用为每种存储写集成代码
• 数据管道：从多个数据源读取数据，处理后写入多个目标
• 文件同步工具：在不同存储系统之间同步文件
• 开发测试：用内存存储做测试，生产环境切换到 S3，代码不用改
• 多云架构：应用需要同时访问多个云服务商的存储

注意事项

• 项目比较新，某些边缘场景可能还不完善
• Google Drive 需要配置 OAuth 认证，设置相对复杂
• 大文件操作时注意内存使用，某些后端可能不支持流式读写
• 建议在生产环境使用前先做充分测试

简评

Mirage 解决的是 AI Agent 生态中的一个实际问题：存储抽象。随着 AI Agent 越来越需要处理各种文件和数据，一个统一的文件系统接口确实很有价值。虽然项目还比较年轻，但设计理念很清晰，API 也很简洁。如果你在开发 AI Agent 应用，Mirage 值得关注。

来源：https://github.com/strukto-ai/mirage