Mirage – strukto-ai 开源的 AI Agent 统一虚拟文件系统

Mirage是什么

Mirage 是 strukto-ai 团队推出的面向 AI Agent 的统一虚拟文件系统。工具将 S3、Slack、Gmail、GitHub、MongoDB 等异构数据源统一挂载为同一棵虚拟文件树，让 AI Agent 无需学习任何新 API，用 Bash 命令（cat、grep、wc、管道等）可跨服务读写、查询和复制数据，实现一个文件系统，搞定所有后端。

Mirage的主要功能

• 统一虚拟挂载：将 S3/R2/GCS、Google 套件（Gmail/Drive/Docs）、Slack/Discord/Telegram、GitHub/Linear/Notion、MongoDB/Redis/PostgreSQL、SSH 远程服务器等全部映射为 /s3、/slack、/github 等标准目录。
• 跨服务 Bash 操作：AI 可用 cat、grep、head、find、cp、mv、管道、重定向等 Unix 命令在任意挂载点上操作，跨服务管道如 grep alert /s3/log.jsonl | wc -l 直接生效。
• 可移植工作空间：支持快照、克隆与回滚，整个 Agent 执行环境可打包为 tar 文件迁移到另一台机器直接恢复，无需重新配置。
• 两层智能缓存：内置索引缓存（目录与元数据）和文件缓存（对象字节），重复读取零网络调用；支持内存（默认 512MB）或 Redis 后端。
• 主流框架无缝接入：提供 OpenAI Agents SDK、Vercel AI SDK、LangChain、Pydantic AI、CAMEL、OpenHands 等适配器。

Mirage的技术原理

• 核心设计哲学：文件系统即通用抽象。 Mirage 的技术根基建立在一条关键洞察之上——现代大语言模型在 Bash、Unix 命令与文件操作上的训练数据远超任何单一 API SDK，因此与其让 AI 学习 N 套异构接口，不如将 S3、Slack、Gmail、MongoDB 等所有后端统一翻译为 AI 已高度内化的 POSIX 风格文件语义，使 Agent 无需掌握任何新词汇，仅凭原生擅长的 Shell 指令即可操作任意数据源。

• 四层分层架构。 Mirage 采用自上而下的四层结构：最上层为 AI Agent 与应用层，通过标准 Bash 或系统调用与系统交互；第二层是 Mirage Bash 与 VFS 层，内含命令注册表和 VFS 操作注册表，负责解析并标准化上层输入；第三层为 Dispatcher 与 Cache 层，按挂载点将请求路由到对应后端，并通过两层缓存拦截重复读取；最底层将 RAM、磁盘、Redis 等本地基础设施与 S3、GitHub、Slack 等远程服务统一挂载为同一棵文件树，FUSE Adapter 则允许外部应用将其作为本地磁盘直接访问。

• VFS 虚拟文件系统抽象层。 虚拟文件系统是 Mirage 的核心翻译引擎，每个后端服务通过实现标准化的 VFS 接口（如 readdir、open、read、stat 等）被映射为”看起来像文件系统”的行为——Slack 频道变为虚拟目录、消息变为 JSON 文件，MongoDB 集合变为目录、文档变为 JSON 文件，VFS 不关心底层是对象存储还是聊天频道，只要求后端提供统一的文件操作语义，从而让上层 Agent 以完全一致的思维模型操作任何后端。

如何使用Mirage

• 环境准备：确保系统安装 Python ≥ 3.12 或 Node.js ≥ 20，操作系统为 macOS 或 Linux。

• 安装部署：Python 通过 uv add mirage-ai 安装；TypeScript 通过 @struktoai/mirage-node 或 @struktoai/mirage-browser 安装；CLI 通过一键脚本、npm、uvx 或 npx 安装。

• 创建与配置工作空间： 在代码中实例化 Workspace 对象，将虚拟路径（如 /s3、/slack）与对应资源驱动（如 S3Resource、SlackResource）进行挂载映射。

• 执行 Bash 命令：通过 ws.execute() 传入标准 Unix 指令（如 cat、grep、cp、管道），Mirage 自动将其翻译为底层各服务的实际 API 调用。

• 快照与迁移：调用 ws.snapshot("demo.tar") 打包整个环境，通过 mirage workspace load demo.tar 在新机器直接恢复，无需重新配置。

• 接入 Agent 框架：通过 MirageSandboxClient 嵌入 OpenAI Agents SDK，或通过 mirageTools(ws) 接入 Vercel AI SDK，LangChain、Pydantic AI、CAMEL、OpenHands 均提供官方适配器。

Mirage的核心优势

• 零学习成本：AI 无需掌握任何新 API 或 MCP，直接复用训练数据最丰富的 Bash 与文件系统语义。
• 跨服务管道原生支持：不同后端之间的数据流转如同本地磁盘操作，Agent 单回合可完成更多实际工作。
• 环境可移植：快照与克隆能力让 Agent 运行环境版本化、可迁移，解决多机部署与 Serverless 场景下的状态一致性问题。
• 高性能缓存：两层缓存机制显著降低远程 API 调用频次，Redis 后端更适配多进程与无服务器架构。
• 框架无关：不强制更换 Agent 框架，以沙盒或工具层形式嵌入现有技术栈。

Mirage的项目地址

• 项目官网：https://www.strukto.ai/mirage

• GitHub仓库：https://github.com/strukto-ai/mirage

Mirage的同类竞品对比

Mirage的应用场景

• 多源日志分析：Agent 同时挂载 S3 日志目录、Slack 告警频道与 GitHub Issue 仓库，通过 grep 与 wc 跨服务统计故障频率并定位根因。

• 自动化报告生成：从 Google Sheets 提取数据、Gmail 获取附件、Notion 读取项目文档，统一汇总到本地虚拟目录后自动生成综合报告。

• 远程服务器运维：通过 SSH 挂载多台远程主机，Agent 用标准 Bash 批量执行诊断命令、复制配置文件与变更系统状态。

• 数据迁移与同步：在 S3、R2、GCS 等不同云存储之间，或从 MongoDB 到本地磁盘，通过 cp 与管道指令完成异构后端的数据迁移。

• Serverless Agent 服务：结合 Redis 共享缓存为无服务器架构的多副本 AI 应用提供有状态、可恢复的虚拟文件层，确保实例重启后环境不丢失。

关注公众号：拾黑（shiheibook）了解更多

[广告]赞助链接：

四季很好，只要有你，文娱排行榜：https://www.yaopaiming.com/
让资讯触达的更精准有趣：https://www.0xu.cn/