> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/strukto-ai/mirage) · [上游 README](https://github.com/strukto-ai/mirage/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Mirage：面向 AI Agent 的统一虚拟文件系统


Python 文档
TypeScript 文档

英文 README 简体中文 README 繁體中文 README 法文 README 越南文 README 韩文 README

Mirage 是 **面向 AI Agent 的统一虚拟文件系统（Unified Virtual File System）**：它将 S3、Google Drive、Slack、Gmail、Redis 等服务与数据源并列挂载为同一文件系统。任何已熟悉 bash 的 LLM 都可以开箱即用，在各后端之间读取、grep 和管道串联，无需学习任何新词汇。 ```ts 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。 ## 架构

Mirage 架构：AI Agent 与 Application → Mirage Bash 与 VFS → Dispatcher & Cache → Infrastructure 与 Remote

## 安装 - **Python** ≥ 3.11，用于 `mirage-ai` 包和 `mirage` CLI - **Node.js** ≥ 20，用于 TypeScript SDK - **macOS** 或 **Linux**（基于 FUSE 的挂载需要平台支持） ### Python ```bash uv add mirage-ai # installs the `mirage` library and the `mirage` CLI binary ``` ### TypeScript ```bash 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 ```bash 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 ```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 ```ts 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 ```bash 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](https://docs.mirage.strukto.ai/python/agents/openai-agents), [LangChain](https://docs.mirage.strukto.ai/python/agents/langchain), [Pydantic AI](https://docs.mirage.strukto.ai/python/agents/pydantic-ai), [CAMEL](https://docs.mirage.strukto.ai/python/agents/camel), [OpenHands](https://docs.mirage.strukto.ai/python/agents/openhands), [Agno](https://docs.mirage.strukto.ai/python/agents/agno) | | TypeScript | [Vercel AI SDK](https://docs.mirage.strukto.ai/typescript/agents/vercel), [OpenAI Agents SDK](https://docs.mirage.strukto.ai/typescript/agents/openai), [LangChain](https://docs.mirage.strukto.ai/typescript/agents/langchain), [Mastra](https://docs.mirage.strukto.ai/typescript/agents/mastra) | | 编程 Agent | [Claude Code](https://docs.mirage.strukto.ai/python/agents/claude-code), [Codex](https://docs.mirage.strukto.ai/python/agents/codex), [OpenCode](https://docs.mirage.strukto.ai/typescript/agents/opencode), [Pi](https://docs.mirage.strukto.ai/typescript/agents/pi) | ## Cache 每个 `Workspace` 都具备双层缓存，针对远程后端的重复操作会命中本地状态，而非再次访问网络： - **Index cache（索引缓存）：** 列表与元数据。首次目录遍历会访问 API；之后的请求在 TTL 过期前（默认 10 分钟）从索引提供。 - **File cache（文件缓存）：** 对象字节。首次读取从源端流式传输；之后的流水线从缓存读取（默认 512 MB）。 两层默认使用进程内 RAM，零配置即可使用。Redis 存储可在 worker、进程和机器之间共享缓存状态： ```ts 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](https://docs.mirage.strukto.ai/home/cache) for the full miss/hit lifecycle. ## Contributors 感谢所有为 Mirage 做出贡献的人。 Mirage contributors