🪄 Mirage — 虚拟文件系统让 AI Agent 操控所有后端（2.3k⭐）

🪄 Mirage — 一个虚拟文件系统让 AI Agent 操作所有后端（2.3k⭐）

LLM 原生懂 bash，但不懂你的 SaaS API。每个后端（S3、Slack、Gmail、GitHub）都要学一套新 SDK / MCP，组合起来更是灾难。Mirage 的做法很直接：把所有服务挂载到一个虚拟文件系统下，Agent 用 cp、grep、cat 就能跨服务干活。

const ws = new Workspace({
  '/data':   new RAMResource(),
  '/s3':     new S3Resource({ bucket: 'logs' }),
  '/slack':  new SlackResource({}),
  '/github': new GitHubResource({}),
})

await ws.execute('grep alert /slack/general/*.json | wc -l')
await ws.execute('cat /github/mirage/README.md')
await ws.execute('cp /s3/report.csv /data/local.csv')

核心思路

一个树，N 个后端。 RAM、Disk、Redis、S3、Gmail、Slack、GitHub、Linear、Notion、MongoDB、SSH…都挂到同一个根目录下。Agent 不需要学 20 套 API，只需要会用 bash 的那几个命令。因为 LLM 训练数据里最不缺的就是 Unix 命令用法。

安装

# Python
uv add mirage-ai

# TypeScript
npm install @struktoai/mirage-node

# CLI
curl -fsSL https://strukto.ai/mirage/install.sh | sh

快速上手（Python）

from mirage import Workspace
from mirage.resource.s3 import S3Resource, S3Config
from mirage.resource.slack import SlackConfig, SlackResource

ws = Workspace({
    "/data":  RAMResource(),
    "/s3":    S3Resource(S3Config(bucket="my-bucket")),
    "/slack": SlackResource(SlackConfig()),
})

await ws.execute("cp /s3/report.csv /data/report.csv")
await ws.execute("grep alert /s3/data/log.jsonl | wc -l")
ws.snapshot("demo.tar")

跟 Agent 框架的集成

Mirage 提供了现成的适配器：

• OpenAI Agents SDK — 用 MirageSandboxClient 把 Workspace 作为沙箱注入
• Vercel AI SDK — mirageTools(ws) 暴露为 typed AI SDK tool set
• LangChain、Pydantic AI、CAMEL、OpenHands 也都有适配器

两层缓存

每个 Workspace 自带双层缓存：索引缓存（目录列表 + 元数据，默认 10 分钟 TTL）和文件缓存（对象内容，默认 512 MB）。支持 RAM 和 Redis 两种后端，适合单进程和分布式场景。

Mirage 的想法很讨巧——不给 LLM 新语法，而是把新世界伪装成它已经熟悉的东西。如果你的 Agent 每天要跟 3 个以上的后端打交道，这个项目值得一试。

🪄 Mirage — A Virtual Filesystem That Lets AI Agents Reach Every Backend (2.3k⭐)

LLMs natively understand bash, but they don't speak SaaS APIs. Every backend (S3, Slack, Gmail, GitHub) requires a new SDK or MCP — and composing them is a nightmare. Mirage takes a straightforward approach: mount all your services under one virtual filesystem, and let agents use cp, grep, and cat across them.

One tree, N backends. RAM, Disk, Redis, S3, Gmail, Slack, GitHub, Linear, Notion, MongoDB, SSH — all mounted under the same root. Agents don't need to learn 20 APIs; they just need the handful of Unix commands LLMs know best.

Integration with major agent frameworks: OpenAI Agents SDK (MirageSandboxClient), Vercel AI SDK (mirageTools(ws)), LangChain, Pydantic AI, CAMEL, and OpenHands all have adapters.

Two-layer cache ships with every workspace — index cache (listings + metadata, 10-min TTL) and file cache (object bytes, 512 MB default). RAM or Redis backends.

# Install
pip install mirage-ai
# or
npm install @struktoai/mirage-node

Mirage's trick is elegant: instead of teaching LLMs a new language, it disguises every backend as something they already know. If your agent touches more than 3 services daily, this is worth a look.

GitHub: https://github.com/strukto-ai/mirage