AI Agent 的接口太多，一个虚拟文件系统就够了

Agent 正在接入越来越多的后端服务：S3、Slack、Gmail、GitHub、Notion、Google Drive、Redis、PostgreSQL……每接一个，就要学一套新 SDK 的调用方式，或者写一个新的 MCP 工具定义。这不仅拉长了开发周期，也让 Agent 的推理负担持续加重——模型需要在不同 API 风格之间来回切换上下文。
但有一个核心事实很少被讨论：大语言模型最熟练的交互方式，不是 API 调用，而是文件系统。 从训练数据到日常使用，模型见过最多的结构化交互就是 bash 命令、文件路径、管道和重定向。如果能让 Agent 用 cat、grep、cp 和 ls 来操作一切后端服务，就不需要模型去理解 N 套 API 语义。
Mirage 正是基于这个思路诞生的开源项目。它本质上是一个统一虚拟文件系统（Unified Virtual Filesystem），把不同后端服务挂载到同一棵树根下，让 Agent 用一套文件操作命令通吃所有数据源。

问题：Agent 的接口负担正在失控

先看一个典型场景。一个需要从 Slack 提取告警、从 S3 读取日志、把分析结果写入 Google Docs 的 Agent，传统实现需要：

1. 调用 Slack SDK 获取消息
2. 调用 S3 SDK 下载文件
3. 调用 Google Docs API 创建文档
4. 用临时变量在各个 API 返回值之间传递数据
5. 每一步都可能出错，每一步都需要不同的认证方式和错误处理

更麻烦的是，Agent 框架每接一个新工具，就要写一个工具定义——描述参数、返回值、触发条件。模型在推理时还要反复从"工具描述"中理解每个 API 的语义，这在多步工具调用链中会造成显著的上下文开销。
Mirage 的解法很直接：把一切变成文件。

统一文件系统树

Mirage 的核心概念是 Workspace——一个挂载了多种 Resource 的虚拟文件系统。每种后端服务就是一个挂载点，Agent 在挂载点内执行标准的文件操作命令。

from mirage import Workspace
from mirage.resource.ram import RAMResource
from mirage.resource.s3 import S3Config, S3Resource
from mirage.resource.slack import SlackConfig, SlackResource
from mirage.resource.gdocs import GDocsConfig, GDocsResource

ws = Workspace({
    "/data":  RAMResource(),
    "/s3":    S3Resource(S3Config(bucket="my-bucket")),
    "/slack": SlackResource(SlackConfig()),
    "/docs":  GDocsResource(GDocsConfig()),
})

# 从 S3 复制文件到本地
await ws.execute("cp /s3/report.csv /data/report.csv")

# 在 Slack 消息中搜索告警
await ws.execute("grep alert /slack/general/*.json | wc -l")

# 用管道跨服务组合操作
await ws.execute("cat /s3/events/2026-05-06.parquet | jq .user")

当 Agent 需要跨服务操作时，它不需要记住 API 签名——只需要理解文件路径、管道和标准 Unix 命令。S3 上的 Parquet 文件可以直接被 cat，Slack 频道中的消息可以作为 JSON 文件被 grep 搜索，Google Drive 中的文档可以被 cp 复制到本地。
Mirage 目前支持的 Resource 覆盖了主流后端服务：

• 对象存储：S3、R2、GCS、OCI、Supabase
• 消息协作：Slack、Discord、Telegram、Email
• 代码与项目管理：GitHub（仓库、Issues、CI）、Linear、Notion、Trello
• 办公文档：Gmail、Google Drive、Google Docs、Google Sheets、Google Slides
• 数据存储：Redis、MongoDB、PostgreSQL、RAM、磁盘文件
• 远程连接：SSH

每类 Resource 都按文件系统语义做了适配：Slack 的频道变成目录，频道消息变成 JSON 文件；S3 的 bucket 变成目录，对象变成文件；Google Drive 的文件和文件夹映射为目录树。Agent 不需要理解这些后端各自的 API 结构，只需要理解"目录和文件"。

两层缓存：远程资源的操作效率

如果每次 ls 或 cat 都直接调用远程 API，性能会是灾难。Mirage 在 Workspace 内部实现了两层缓存：

• 索引缓存：目录列表和元数据。首次遍历走 API，后续命中直接从缓存返回，直到 TTL 过期。
• 文件缓存：对象内容字节。首次读取从远端流式传输，后续管道操作读缓存。

缓存后端可插拔，内置两种实现：

# 默认：进程内 RAM 缓存，512MB 文件缓存 + 10 分钟索引 TTL
ws = Workspace(mounts, {
    "cache": RAMFileCacheStore(),
    "index": RAMIndexCacheStore(ttl=600),
})

# Redis 共享缓存：跨进程、跨机器共享
ws = Workspace(mounts, {
    "cache": RedisFileCacheStore(url="redis://localhost:6379/0", limit="8GB"),
    "index": RedisIndexCacheStore(url="redis://localhost:6379/0", ttl=600),
})

这个设计对 Agent 场景尤其重要——Agent 经常需要反复查询同一个数据源的元信息（比如列出目录、检查文件是否存在），有了缓存，第二次及之后的同类操作就不会产生网络开销。

融入 Agent 框架

Mirage 本身不限定 Agent 运行时。它为当前主流 Agent 框架提供了适配层：
OpenAI Agents SDK（Python）：

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)),
)

Vercel AI SDK（TypeScript）：

import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { mirageTools } from '@struktoai/mirage-agents/vercel'
import { buildSystemPrompt } from '@struktoai/mirage-agents/openai'

const { text } = await generateText({
  model: openai('gpt-5.4-nano'),
  system: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),
  prompt: "Read /docs/paper.pdf and summarize it.",
  tools: mirageTools(ws),
})

LangChain、Pydantic AI、CAMEL、OpenHands 和 Mastra 都有对应的适配器。无论底层用哪个模型或框架，Agent 看到的都是同一套文件系统接口。 这是 Mirage 的核心价值：它把工具层抽象成了基础设施，而不是每次换模型就要重写工具绑定。

可移植 Workspace

在生产环境中，Agent 的状态迁移是个棘手问题——会话被打断后如何恢复、如何在不同机器间迁移运行中的 Agent。Mirage 的 Workspace 支持快照机制：

# 保存 Workspace 状态到 tar 包
mirage workspace snapshot demo demo.tar

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

快照包含完整的目录结构、文件内容和缓存状态，可以在不同机器间移植。Workspace 也支持版本化管理，这对于 CI/CD 流水线中的 Agent 任务特别有用——每次构建可以 clone 一个干净的 Workspace，跑完任务后丢弃。

什么时候该用，什么时候不该用

Mirage 的优势场景很明确：

• 跨后端服务的数据操作流水线：Agent 需要从多个数据源读取、处理、写入结果
• Agent 工具层标准化：团队维护多个 Agent，希望统一工具接口
• 快速原型验证：不想为每个新数据源写 SDK 调用和工具定义
• 可移植 Agent 环境：需要在不同机器间迁移 Agent 工作状态

不适合的场景：

• 高频低延迟的原子操作：文件系统抽象的额外开销对单次 API 调用来说不可忽略
• 需要精细控制 API 参数的场景：文件系统抽象会屏蔽部分 SDK 特有的配置项
• Agent 只调用单一后端：用 Mirage 引入的抽象层没有收益

工程启示

Mirage 的出现提供了一个值得思考的工程信号：Agent 的工具层抽象，可能正在从"API 集合"走向"接口统一"。过去两年，行业花了大量精力在丰富 Agent 能调用的工具种类上（MCP 协议、函数调用、工具注册），但较少关注模型使用这些工具时的认知负担。
一个经历过海量 bash 操作训练的模型，面对 cat /slack/general/alerts.json 的理解成本，远低于阅读一段 JSON 格式的函数描述再拼接参数。文件系统不仅仅是存储抽象，它可能也是 Agent 最自然的交互界面。
当然，Mirage 还处于早期阶段（v0.0.1 发布仅两天），生态和稳定性有待时间验证。但它选择的抽象方向——用 Unix 文件语义统一所有后端——无论这个项目最终能否成为标准，都值得 AI 工程团队关注和借鉴。

转自：https://mp.weixin.qq.com/s/4-RYNUzuN6XutErlj-qYFg