/readme

Mirage 是 面向 AI Agent 的统一虚拟文件系统：它把 S3、Google Drive、Slack、Gmail、Redis 等服务和数据源并排挂载为同一个文件系统。任何已经会用 bash 的 LLM 都可以开箱即用地对每个后端进行读取、grep 和管道操作，不需要学习新的词汇。

const ws = new Workspace({
  '/data':  new RAMResource(),
  '/s3':    new S3Resource({ bucket: 'logs' }),
  '/slack': new SlackResource({ token: process.env.SLACK_BOT_TOKEN! }),
})

await ws.execute('grep -r alert /slack/channels/general__C04QX/ | wc -l')
await ws.execute('cp /s3/report.csv /data/local.csv')
await ws.execute('wc -l $(find /s3/data -name "*.jsonl")')

// 命令是可扩展的：可以注册新命令，也可以针对特定资源 + 文件类型
// 覆盖某个命令，例如对 S3 上的 Parquet 文件执行 `cat` 会把行渲染为 JSON。
ws.command('summarize', ...)
ws.command('cat', { resource: 's3', filetype: 'parquet' }, ...)

await ws.execute('summarize /data/local.csv')
await ws.execute('cat /s3/events/2026-05-06.parquet | jq .user')

关于

• 一个接口，而不是 N 个 SDK 和 M 个 MCP。 每个服务都使用同一套文件系统语义，管道可以像在本地磁盘上一样跨服务组合。
• 约 50 个内置后端： RAM、Disk、Redis、S3 / R2 / OCI / Supabase / GCS、Gmail / GDrive / GDocs / GSheets / GSlides、GitHub / Linear / Notion / Trello、Slack / Discord / Email、MongoDB / Postgres / LanceDB、SSH 等，并排挂载在同一个根目录下。
• 可移植的工作区： 克隆、快照和版本化工作区；Agent 运行可以在机器之间迁移，而不必重启或重新配置系统。
• 可嵌入： Python 和 TypeScript SDK 直接运行在 FastAPI、Express、浏览器应用或任何异步运行时的进程内，不需要单独的进程。
• Agent 集成： 通过 SDK 支持 OpenAI Agents SDK、Vercel AI SDK、LangChain、Pydantic AI、CAMEL 和 OpenHands；通过轻量 CLI + daemon 支持 Claude Code 和 Codex 等编码 Agent。

架构

安装

• Python ≥ 3.11，用于 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-agents    # OpenAI / Vercel AI / LangChain / Mastra 适配器

两个运行时包都会自动引入 @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.ram import RAMResource
from mirage.resource.s3 import S3Config, S3Resource

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

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

await ws.snapshot("demo.tar")

TypeScript

import { Workspace, RAMResource, S3Resource } from '@struktoai/mirage-node'

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

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

await ws.snapshot('demo.tar')

CLI

mirage workspace create ws.yaml --id demo
mirage execute   --workspace_id demo --command "cp /s3/report.csv /data/report.csv"
mirage provision --workspace_id demo --command "cat /s3/data/large.jsonl"
mirage workspace snapshot demo demo.tar
mirage workspace load demo.tar --id demo-restored

Agent 框架

Mirage 可以作为沙箱或工具层接入 Agent 框架。read 等 POSIX 操作也可以按资源和文件类型自定义，例如读取 PDF 会返回解析后的页面，而不是原始字节。

	集成
Python	OpenAI Agents SDK、LangChain、Pydantic AI、CAMEL、OpenHands、Agno
TypeScript	Vercel AI SDK、OpenAI Agents SDK、LangChain、Mastra
编码 Agent	Claude Code、Codex、OpenCode、Pi

缓存

每个 Workspace 都有两层缓存，让针对远端后端的重复操作命中本地状态而不是网络：

• 索引缓存： 目录列表和元数据。第一次遍历目录会调用 API；之后在 TTL 过期前（默认 10 分钟）都从索引读取。
• 文件缓存： 对象字节。第一次读取从源端流式拉取；之后的管道直接读缓存（默认 512 MB）。

两层默认都使用进程内 RAM，零配置。Redis 存储可以在 worker、进程和机器之间共享缓存状态：

import { RedisFileCacheStore, S3Resource, Workspace } from '@struktoai/mirage-node'

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

完整的 miss/hit 生命周期见缓存文档。

贡献者

感谢所有为 Mirage 做出贡献的人。