strukto-ai/mirage · 上手攻略

• 仓库：strukto-ai/mirage
• 链接：https://github.com/strukto-ai/mirage
• 分类：AI Agent 工具 / 虚拟文件系统 / 多后端集成
• 作者：Tom
• 更新：2026-08-27

是什么

Mirage 是一个面向 AI Agent 的统一虚拟文件系统（Unified Virtual Filesystem）。它的核心思想是：把 S3、Google Drive、Slack、Gmail、Redis、GitHub 等各种服务和数据源，以目录的形式挂载到同一个虚拟根目录下，让 AI Agent 用熟悉的 ls、grep、cat 等命令就能跨后端读写数据。

换句话说，Mirage 把 N 个服务的 SDK / API / MCP 协议，统一翻译成一套 POSIX 文件系统语义，任何会 bash 的 LLM 无需学新词汇就能直接上手。

解决什么问题

AI Agent 在对接多个外部服务时，每个服务都要写一套 SDK 调用或 MCP 工具，学习成本高、代码难复用。Mirage 的思路是：不要让 Agent 学习 50 种 API，只要 Agent 会用文件系统，就能操作所有后端。

典型痛点： - 对 Slack 搜消息要用 Slack SDK、对 Redis 要用 redis-py、对 S3 要用 boto3——三个 API 三套逻辑 - 每个服务有自己的认证、错误处理、重试策略 - 跨服务的数据流水线（如"把 Slack 某频道的附件存到 S3"）要写胶水代码

Mirage 用统一的 Workspace + execute() 抽象解决了以上问题。

快速安装

Python SDK（推荐，Python ≥ 3.11）：

# 用 uv 安装（推荐）
uv add mirage-ai

# pip 备选
pip install mirage-ai

# 如果需要 S3/GCS 等额外后端依赖
uv add "mirage-ai[s3]"
pip install mirage-ai[s3]

Node.js SDK（Node.js ≥ 20）：

# 服务器端
npm install @struktoai/mirage-node

# 浏览器/Edge 端
npm install @struktoai/mirage-browser

# Agent 适配器（OpenAI / Vercel AI / LangChain / Mastra）
npm install @struktoai/mirage-agents

CLI（无需 SDK，直接用命令）：

# 方式 1：官方安装脚本
curl -fsSL https://strukto.ai/mirage/install.sh | sh

# 方式 2：npm 全局
npm install -g @struktoai/mirage-cli

# 方式 3：uvx（无需安装，直接跑）
uvx mirage-ai

# 方式 4：npx
npx @struktoai/mirage-cli

⚠️ macOS / Linux 依赖 FUSE：FUSE-based 挂载需要平台支持（macOS 原生支持，Linux 需要安装 FUSE）；纯 in-memory（RAMResource）不需要 FUSE，Windows 不可用。

核心用法

最小可跑示例（Python）

import asyncio
from mirage import MountMode, Workspace
from mirage.resource.ram import RAMResource

async def main():
    # 建立一个虚拟工作区，/data 挂载为内存文件系统
    ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)

    # 执行 shell 命令——完全和本地 bash 一样的语法
    await ws.execute('echo "hello mirage" | tee /data/hello.txt')
    result = await ws.execute("cat /data/hello.txt")
    print(await result.stdout_str())  # -> hello mirage

    await ws.close()

asyncio.run(main())

多后端挂载（跨 S3 / Redis / Slack 查询）

import os
from mirage import MountMode, Workspace
from mirage.resource.s3 import S3Config, S3Resource
from mirage.resource.redis import RedisConfig, RedisResource
from mirage.resource.slack import SlackConfig, SlackResource

ws = Workspace({
    "/tmp": RAMResource(),                          # 内存目录
    "/redis": RedisResource(RedisConfig(url="redis://localhost:6379")),  # Redis
    "/s3": S3Resource(S3Config(bucket="my-bucket", region="us-east-1")),  # AWS S3
    "/slack": SlackResource(SlackConfig(token=os.environ["SLACK_BOT_TOKEN"])),  # Slack
}, runtimes=["python", "vfs"])

# 一条 grep 横扫 Redis 和 S3
result = await ws.execute("grep -rln 'session' /redis /s3")
print(await result.stdout_str())

# 把 Slack 某频道的 Python 脚本跑在 /tmp，结果写入 Redis
await ws.execute(
    "python3 /slack/channels/general__C0.../files/script.py > /redis/report.txt"
)

注册 CLI 工具（用名字而非路径调度）

from mirage import Workspace
from mirage.resource.slack import SlackConfig, SlackResource
from mirage import SLACK

ws = Workspace({
    "/slack": SlackResource(SlackConfig(token=slack_bot_token)),
})

# 把 slack 注册为一个 CLI 命令
ws.register_cli("slack", SLACK, {"token": slack_bot_token})

# 之后直接用命令名调用，不需要记住路径
await ws.execute('slack send-message --channel general --text "report is up"')

执行前预估资源（Estimate / Dry-run）

# 不实际执行，只预估网络流量 / 读取次数 / 精度
plan = await ws.execute("cat /data/large.jsonl | wc -l", provision=True)
print(plan.network_read)  # 预估网络读取字节数
print(plan.read_ops)      # 预估读取操作次数
print(plan.precision)      # "exact" / "range" / "unknown"

⚠️ provision=True 返回 ProvisionResult，告诉你这次命令会读多少网络数据、做多少次读取操作。precision 为 unknown 时代表 Mirage 无法估算（通常是自定义命令未注册 provision 函数）。

CLI 方式使用 Mirage

# 创建工作区配置（YAML）
mirage workspace create ws.yaml --id demo

# 执行命令
mirage execute --workspace_id demo --command "cp /s3/report.csv /data/report.csv"

# 快照（导出整个工作区状态）
mirage workspace snapshot demo demo.tar

# 恢复快照
mirage workspace load demo.tar --id demo-restored

内置后端一览（约 50 个）

类别	支持的后端
存储	RAM、磁盘、S3 / R2 / OCI / Supabase / GCS
数据库	Redis、MongoDB / GridFS、Postgres、LanceDB、Qdrant
协作工具	Gmail、Google Drive / Docs / Sheets / Slides、Slack、Discord、Email
代码	GitHub、Linear、Notion、Trello
网络	SSH

⚠️ 实际支持后端数量以官方文档（https://docs.mirage.strukto.ai/python/resource/index）为准，README 描述约 50 个，后端列表随版本更新。

两层缓存机制

Mirage 对远程后端有内置两层缓存，减少重复 API 调用：

1. Index 缓存（元数据缓存）：第一次 ls 命中 API，后续从缓存读直到 TTL 过期（默认 10 分钟）
2. File 缓存（内容缓存）：第一次读取拉取远程内容，后续从缓存读（默认 512MB，上限可配置）

# 共享缓存（多 worker / 多进程 / 多机器共享）
import { RedisFileCacheStore, RedisIndexCacheStore } 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 },
  }
)

默认 in-process RAM 缓存（零配置），加 Redis 可跨进程/机器共享。

Agent 框架集成

框架	Python	TypeScript
OpenAI Agents SDK	✅	✅
Vercel AI SDK	—	✅
LangChain	✅	✅
Pydantic AI	✅	—
Mastra	—	✅
CAMEL	✅	—
OpenHands	✅	—
Claude Code（coding agent）	✅（通过 FUSE/MCP/native adapter）	✅
DeepSeek Harness	—	✅
Codex	—	✅

典型适用场景

场景	为什么用 Mirage
多服务数据聚合流水线	grep -rln session /redis /s3 /slack 一条命令跨三个后端
AI Agent 对接多个外部 API	不需要给 Agent 写 50 个工具，只要会 bash 就行
Workspace 便携性	clone/snapshot/版本化工作区，Agent 运行状态可迁移
数据处理沙盒	MontyRuntime 捕获 Python 输出，脚本在 Workspace 内隔离运行

坑与注意

1. Windows 不支持 FUSE-based 挂载：只有 RAM / Redis 等非 FUSE 后端在 Windows 上可用，磁盘类后端需要 Linux/macOS。

2. Python ≥ 3.11 / Node.js ≥ 20：旧版本 Python 不支持（使用了 3.11+ 语法特性如 match-case 等）。

3. provision 精度不是 always exact：对于自定义命令如果不注册 provision 函数，precision 会返回 unknown，此时 network_read 和 read_ops 是 floor 而非精确值。

4. 输出有默认上限：cat、grep、rg、head、tail 默认最多返回 2000 行，超出时截断但 exit code 保持 0，可通过 Limit(max_lines=...) 自定义。

5. Slack/GitHub/Gmail 等需要真实 API Token：README 示例中 slack_bot_token 等凭证需要从各平台申请并通过环境变量传入，Mirage 本身不提供这些凭证。

6. "约 50 个后端"非精确数字：README 描述"Around 50 built-in backends"，具体支持列表和稳定性以 docs.mirage.strukto.ai 为准。

与同类对比

方案	核心思路	优点	缺点
Mirage	虚拟文件系统统一所有后端	Agent 无需学新 API；pipeline 天然组合	需要理解 Workspace 概念；Windows 支持有限
MCP（Model Context Protocol）	协议标准化工具接口	生态大；多框架兼容	每个工具独立，pipeline 不如文件系统自然
LangChain Tool	每个服务一个 Tool 类	成熟；生态丰富	不同 Tool 接口各异，跨服务 pipeline 繁琐
直接 SDK 调用	各服务原生 API	无额外依赖	认证/重试/类型全自理

Mirage 的差异化定位是工具层的统一抽象，而不是再做一个 SDK。它的价值在于：Agent 视角下，50 个后端都是同一个文件系统的不同目录。

一句话推荐结论

"想让 AI Agent 用 grep、ls、cat 跨 S3 / Slack / Redis / GitHub 操作数据，而不用给每个服务单独写 SDK 吗？Mirage 就是答案——本质是一个把 50 个后端挂到同一个虚拟文件系统根目录的中间层"。

---

来源：GitHub README（https://github.com/strukto-ai/mirage）+ 官方文档 Python Quickstart（https://docs.mirage.strukto.ai/python/quickstart）+ Introduction（https://docs.mirage.strukto.ai/home/introduction.md）。Python/TypeScript 代码示例直接来自官方文档。⚠️ 后端数量"约 50 个"来自 README 原文，精确后端列表和稳定性以官方文档为准。