Mirage：让AI Agent像操作文件一样调用工具，统一虚拟文件系统部署教程

在AI Agent开发中，一个常见痛点是：不同Agent框架（Claude Code、OpenAI Agents、LangChain等）使用不同的工具调用接口，导致工具复用困难。Mirage项目提出了一个优雅的解决方案——将所有工具抽象为虚拟文件系统中的文件和目录，让AI Agent通过文件操作来调用工具。这个项目在GitHub上获得了超过1700颗星。

Mirage解决什么问题

当前AI Agent开发的痛点

• 每个Agent框架有自己的工具注册和调用方式
• 为Claude Code写的工具不能直接给OpenAI Agents用
• 工具的输入输出格式不统一
• 工具组合和编排缺乏标准化方式

Mirage的方案

Mirage将所有工具抽象为虚拟文件系统中的资源：

• 工具 = 文件
• 工具集合 = 目录
• 调用工具 = 读写文件
• 工具组合 = 文件路径导航

这种设计让AI Agent可以使用统一的文件操作语义来发现、调用和组合工具，无需关心底层框架的差异。

支持的Agent框架

• Claude Code（Anthropic）
• OpenAI Agents
• LangChain
• 其他支持自定义工具的Agent框架

安装和部署

环境要求

• Node.js 18+
• npm 或 pnpm

安装步骤

# 克隆仓库
git clone https://github.com/nicepkg/mirage.git
cd mirage

# 安装依赖
npm install

# 构建项目
npm run build

基本使用

# 启动Mirage服务
npm start

# 或者作为MCP服务器运行
npx mirage --mcp

配置Agent连接

以Claude Code为例，在claude_desktop_config.json中添加Mirage作为MCP服务器：

{
  "mcpServers": {
    "mirage": {
      "command": "npx",
      "args": ["mirage", "--mcp"]
    }
  }
}

配置完成后，Claude Code会自动发现Mirage提供的虚拟文件系统，并通过文件操作来调用工具。

核心概念

虚拟文件系统结构

/mirage/
├── tools/           # 工具目录
│   ├── search/      # 搜索工具
│   ├── read/        # 读取工具
│   └── write/       # 写入工具
├── resources/       # 资源目录
│   ├── files/       # 文件资源
│   └── data/        # 数据资源
└── config/          # 配置目录

工具调用流程

1. Agent列出目录，发现可用工具
2. Agent读取工具的元数据（参数、返回类型等）
3. Agent通过写入特定文件来调用工具
4. Agent读取结果文件来获取工具输出

使用场景

• 多Agent协作：不同Agent框架通过共享文件系统协作
• 工具市场：开发者可以发布工具到虚拟文件系统，供所有Agent使用
• 工作流编排：通过文件路径和权限控制工具的使用方式
• 开发调试：文件系统的日志和状态可以帮助调试Agent行为

适合谁

• AI Agent开发者和研究者
• 需要在多个Agent框架之间共享工具的团队
• 对AI工具标准化感兴趣的工程师
• 想了解MCP（Model Context Protocol）实际应用的开发者

注意事项

• 项目仍在早期阶段，API可能会有变化
• 虚拟文件系统是抽象概念，不是真正的文件系统操作
• 性能开销需要在实际场景中评估
• 建议先在开发环境中测试，不要直接用于生产

本文参考来源：Mirage GitHub仓库