AI Agent 的「万能硬盘」来了！Mirage 让 AI 用 Bash 一招打天下！

GitHub: https://github.com/strukto-ai/mirage
标签: AI Agent, 文件系统抽象, Bash工具, 数据源统一, Mirage, 零API学习
发布平台: 程序员茄子（chenxutan.com）

引言：AI Agent 的尴尬现状

2026 年，AI Agent 已经遍地开花。

从 OpenAI 的 Agents SDK 到 Vercel AI SDK，从 LangChain 到 CAMEL，各种 Agent 框架层出不穷，每个都在试图让 AI 变得更「能干」。

但有一个尴尬的现实一直没变：

AI Agent 每接入一个新服务，就得学一套新 API。

想让 Agent 读 S3 上的日志？你得给它配 AWS SDK。想让 Agent 搜 Slack 聊天记录？又得接 Slack API。想让 Agent 查 GitHub Issue？再来一套 GitHub API。

每加一个数据源，都是一次新的对接工作。Agent 的「工具箱」越来越臃肿，提示词越来越长，出错的概率也越来越高。

一、讽刺的现实：AI 最擅长 Bash，却被困在 API 里

更讽刺的是，这些 LLM 最擅长的是什么？

是 Bash。

GPT、Claude、Gemini 这些大模型，在 Shell 脚本、Unix 命令上的训练数据量是任何单一 API SDK 的成千上万倍。

• cat、grep、head、wc、管道操作——这些命令对 AI 来说就像母语一样自然。

但现实是：

• AI 面对 Slack 消息时不能用 grep
• AI 面对 S3 文件时不能用 cat
• AI 面对 MongoDB 数据时不能用管道串联

这个割裂的局面，被一个叫 Mirage 的项目彻底打破了。

二、Mirage 是什么

项目简介

Mirage 的全称是 「A Unified Virtual File System for AI Agents」——面向 AI Agent 的统一虚拟文件系统。

由 strukto-ai 团队开发，2026 年 5 月 6 日刚刚发布首个公开版本 v0.0.1-alpha.1，采用 Apache 2.0 开源协议。

核心思路

用一句话概括 Mirage 的核心思路：

把所有数据源都映射成同一个文件系统，让 AI Agent 用 Bash 命令统一操作。

这就像给 AI 装了一个「万能硬盘」。

三、所有数据源，统一成一个文件树

S3 存储桶、Google Drive、Gmail 邮箱、Slack 频道、GitHub 仓库、Linear 任务、Notion 文档、MongoDB 数据库、Redis 缓存、甚至远程 SSH 服务器——

所有这些五花八门的数据源，全部被挂载到同一个虚拟文件树下。

AI 看到的，就是一个统一的目录结构：

/
├── s3/          ← S3 存储桶
├── slack/       ← Slack 工作区
├── github/      ← GitHub 仓库
├── gmail/       ← Gmail 邮箱
├── gdrive/      ← Google Drive
├── notion/      ← Notion 工作区
├── mongo/       ← MongoDB 数据库
├── redis/       ← Redis 缓存
├── ssh/         ← 远程 SSH 服务器
└── data/        ← 本地内存/RAM

对 AI Agent 来说，操作 Slack 消息和操作本地文件没有区别。

AI 不需要学任何新东西。它只需要做它最擅长的事——写 Bash。

四、核心亮点

1. 一个文件系统，搞定所有后端

不管底层是 S3、Slack、GitHub 还是 MongoDB，对 AI 来说它们都是「文件」。

2. 熟悉的 Unix 命令，跨所有挂载点通用

• cat、grep、head、wc、find、ls、cp、mv
• 管道操作、重定向
• 这些命令在每一个挂载点上都能用。

3. 可移植的工作空间

支持快照、克隆、回滚。Agent 的整个执行环境可以打包成一个 tar 文件，迁移到另一台机器上直接恢复，不需要重新配置。

4. 两层缓存，重复读取零网络调用

每个 Workspace 都内置了两层缓存：

• 索引缓存：避免重复 API 调用
• 文件缓存：本地缓存，零网络开销

5. 主流 Agent 框架全支持

Mirage 不是要你换框架，而是无缝嵌入你已经在用的框架。

五、支持的数据源

Mirage 首批支持的挂载资源已经相当全面：

而且这个列表还在快速增长中。

六、快速上手

环境要求

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

Python 安装

uv add mirage-ai

这会同时安装 mirage 库和 mirage CLI 命令行工具。

TypeScript 安装

# Node.js 服务端 / CLI
npm install @struktoai/mirage-node

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

# 运行时无关的核心原语（被上面两个自动依赖）
npm install @struktoai/mirage-core

CLI 安装

四种方式任选：

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

# 方式二：npm 全局安装
npm install -g @struktoai/mirage-cli

# 方式三：uvx 直接运行
uvx mirage-ai

# 方式四：npx 直接运行
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')

九、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

十、接入 OpenAI Agents SDK

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from mirage.agents.openai_agents import MirageSandboxClient

client = MirageSandboxClient(ws)

agent = SandboxAgent(
    name="Mirage Sandbox Agent",
    model="gpt-5.4-nano",
    instructions=ws.file_prompt,
)

result = await Runner.run(
    agent,
    "Summarize /s3/data/report.parquet into /report.txt.",
    run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),
)

十一、两层缓存详解

Mirage 的两层缓存都可以独立配置后端：

Redis 共享缓存（适合多进程 / Serverless）

from mirage import Workspace
from mirage.cache import RedisFileCacheStore, RedisIndexCacheStore

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

默认配置

• 内存缓存（512MB 文件缓存 + 10 分钟索引 TTL）
• 适合单进程应用和 Notebook 场景

十二、架构设计哲学

Mirage 的巧妙之处在于，它没有试图让 AI 变得更「聪明」，而是让世界变得更「简单」。

与其教 AI 一百种 API，不如把所有东西都变成 AI 已经会的东西。

这个洞察很深刻：

十三、适用场景

十四、与其他方案对比

Mirage 不是要替代它们，而是无缝嵌入你已经在用的框架。

十五、总结

核心价值

推荐理由

对于正在折腾 AI Agent 的开发者来说，Mirage 绝对值得放进工具箱。一个 uv add mirage-ai 就能让你的 Agent 用 Bash 打天下，这种体验，试过就回不去了。

GitHub: https://github.com/strukto-ai/mirage
文档: https://github.com/strukto-ai/mirage#readme

本文首发于「程序员茄子」博客，原文链接：https://chenxutan.com