strukto-ai--mirage/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Mirage 是 面向 AI Agent 的统一虚拟文件系统（Unified Virtual File System）：它将 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")')

// Commands are extensible: register new commands, or override one per
// resource + filetype, e.g. `cat` on S3 Parquet renders rows as 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 / Qdrant、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    # installs the `mirage` library and the `mirage` CLI binary

TypeScript

npm install @struktoai/mirage-node      # Node.js servers and CLIs
npm install @struktoai/mirage-browser   # browser / edge runtimes
npm install @struktoai/mirage-agents    # OpenAI / Vercel AI / LangChain / Mastra adapters

两个运行时包都会自动拉取 @struktoai/mirage-core。

CLI

curl -fsSL https://strukto.ai/mirage/install.sh | sh
# or
npm install -g @struktoai/mirage-cli
# or
uvx mirage-ai
# or
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 框架。POSIX 操作（例如 read）还可按资源与文件类型自定义，例如读取 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

Cache

每个 Workspace 都具备双层缓存，针对远程后端的重复操作会命中本地状态，而非再次访问网络：

• Index cache（索引缓存）： 列表与元数据。首次目录遍历会访问 API；之后的请求在 TTL 过期前（默认 10 分钟）从索引提供。
• File cache（文件缓存）： 对象字节。首次读取从源端流式传输；之后的流水线从缓存读取（默认 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 },
  },
)

详见 cache docs for the full miss/hit lifecycle.

Contributors

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