Mirage

Mirage 是一个面向 AI Agent 的统一虚拟文件系统：它提供了一棵单一的文件树，可以将 S3、Google Drive、Slack、Gmail 和 Redis 等多种服务与数据源像挂载本地磁盘一样挂载在一起，形成统一的文件系统。

AI Agent 可以通过一套相同的类 Unix 工具访问所有后端，流水线（pipelines）可以像在本地磁盘上一样自然地跨服务组合。这是一个模拟环境，Agent 在底层看到的是一个统一的文件系统。任何已经掌握 bash 的 LLM 都可以直接使用 Mirage，无需学习任何新词汇。

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')

// 注册一个新命令，可在所有挂载点使用
ws.command('summarize', ...)

// 为特定的资源 + 文件类型覆盖命令 ——
// 在 /s3 中对 Parquet 文件执行 `cat`，会将行渲染为 JSON 而非原始字节。
ws.command('cat', { resource: 's3', filetype: 'parquet' }, ...)

await ws.execute('summarize /github/mirage/README.md')
await ws.execute('cat /s3/events/2026-05-06.parquet | jq .user')

关于

• 统一文件系统，涵盖所有后端： 每个服务都遵循相同的文件系统语义，因此 Agent 只需要理解一种抽象，而无需处理 N 个 SDK 和 M 个 MCP，从而充分利用 LLM 最熟悉的 Linux 文件系统和 bash 词汇。
• 多种资源，单一挂载： 支持 RAM、Disk、Redis、S3 / R2 / OCI / Supabase / GCS、Gmail / GDrive / GDocs / GSheets / GSlides、GitHub / Linear / Notion / Trello、Slack / Discord / Telegram / Email、MongoDB、SSH 等，全部挂载在单个根目录下。
• 通用的 bash 工具： Agent 可以重复使用同一套 Unix 工具，无需为每个服务学习新的 API。流水线可以像在本地磁盘上一样跨服务自由组合，这正是现代 LLM 训练语料中最核心的部分。
• 便携式工作空间： 支持克隆、快照和版本化环境。无需重启或重新配置系统，即可在不同机器间迁移 Agent 运行环境。
• 嵌入式集成： 提供 Python 和 TypeScript SDK，让你能够直接在 FastAPI、Express、浏览器应用或任何异步运行时中为 AI Agent 提供虚拟文件系统，无需额外进程。你可以直接在代码中克隆、快照和版本化工作空间。
• 兼容主流 Agent 框架： 支持 OpenAI Agents SDK、Vercel AI SDK (TypeScript)、LangChain、Pydantic AI、CAMEL 和 OpenHands。
• 轻量级 CLI + 守护进程： 可接入 Claude Code 和 Codex 等编码 Agent，让它们通过熟悉的 bash 命令访问每一个挂载资源，从而在每一步操作中完成更多有价值的工作。

架构

安装

先决条件

• Python ≥ 3.12（用于 mirage-ai 包和 mirage CLI）
• Node.js ≥ 20（用于 TypeScript SDK）
• macOS 或 Linux（基于 FUSE 的挂载需要平台支持）

Python

uv add mirage-ai

这会安装 mirage 库和 mirage CLI 二进制文件。

TypeScript

选择符合你运行环境的包：

npm install @struktoai/mirage-node      # Node.js 服务器和 CLI
npm install @struktoai/mirage-browser   # 浏览器 / Edge 运行时
npm install @struktoai/mirage-core      # 与运行时无关的基础库

@struktoai/mirage-node 和 @struktoai/mirage-browser 会自动引入 @struktoai/mirage-core。

CLI

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

或者使用你选择的包管理器：

npm install -g @struktoai/mirage-cli

uvx mirage-ai

npx @struktoai/mirage-cli

快速上手 (Python)

from mirage import Workspace
from mirage.resource.gdocs import GDocsConfig, GDocsResource
from mirage.resource.ram import RAMResource
from mirage.resource.s3 import S3Config, S3Resource
from mirage.resource.slack import SlackConfig, SlackResource

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

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")

快速上手 (TypeScript)

import {
  Workspace,
  RAMResource,
  S3Resource,
  SlackResource,
  GDocsResource,
} from '@struktoai/mirage-browser'

const ws = new Workspace({
  '/data':  new RAMResource(),
  '/s3':    new S3Resource({ bucket: 'my-bucket' }),
  '/slack': new SlackResource({}),
  '/docs':  new GDocsResource({}),
})

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