Mirage：为AI Agent设计的统一虚拟文件系统，2500+星

AI编程Agent（如Claude Code、Codex等）在处理文件时面临一个共同问题：它们需要访问和操作文件系统，但直接操作真实文件系统既危险又不便。Mirage项目解决了这个问题——它为AI Agent提供了一个统一的虚拟文件系统。

什么是Mirage？

Mirage是一个用TypeScript编写的虚拟文件系统（VFS），专门为AI Agent设计。它提供了一个安全、隔离的文件操作环境，让AI Agent可以在不影响真实文件系统的情况下读写文件。

项目地址：https://github.com/strukto-ai/mirage

为什么需要虚拟文件系统？

AI Agent在执行任务时经常需要：

• 读取项目文件了解代码结构
• 创建临时文件存储中间结果
• 修改配置文件
• 生成代码文件

如果直接操作真实文件系统，存在几个问题：

• 安全风险：AI可能会误删重要文件
• 隔离性差：多个Agent同时操作可能冲突
• 难以回滚：操作一旦执行就难以撤销
• 跨平台差异：不同操作系统的文件系统行为不同

Mirage的核心特性

1. FUSE支持

Mirage使用FUSE（Filesystem in Userspace）技术，可以在用户空间实现完整的文件系统。这意味着：

• 不需要内核模块
• 可以在任何支持FUSE的系统上运行
• 文件系统行为完全可控

2. 多后端支持

Mirage支持多种存储后端：

• 内存：最快的选项，适合临时文件
• 本地磁盘：持久化存储
• S3兼容存储：云端存储
• 自定义后端：可以实现自己的存储逻辑

3. 快照和回滚

Mirage支持文件系统快照，可以随时回滚到之前的状态。这对于AI Agent特别有用：

# 创建快照
mirage snapshot save "before-refactor"

# 执行操作...

# 回滚到快照
mirage snapshot restore "before-refactor"

4. 权限控制

可以精细控制AI Agent的文件操作权限：

• 只读模式：只能读取文件
• 受限写入：只能写入特定目录
• 完全访问：可以读写所有文件

5. 多Agent支持

Mirage支持多个Agent同时操作，每个Agent有自己的命名空间，互不干扰。

使用场景

1. AI编程助手

让Claude Code、Codex等工具在安全的环境中操作文件，避免误删代码。

2. 代码沙箱

为代码执行提供隔离的文件系统，防止恶意代码影响真实环境。

3. 协作开发

多个AI Agent可以同时在同一个项目上工作，互不干扰。

4. 测试环境

为测试提供干净的文件系统环境，每次测试后自动清理。

如何使用

安装

npm install @strukto-ai/mirage

基本使用

import { Mirage } from '@strukto-ai/mirage';

// 创建虚拟文件系统
const vfs = new Mirage({
  backend: 'memory',  // 使用内存存储
  readOnly: false
});

// 写入文件
await vfs.writeFile('/hello.txt', 'Hello, World!');

// 读取文件
const content = await vfs.readFile('/hello.txt');

// 列出文件
const files = await vfs.readdir('/');

挂载为FUSE文件系统

# 挂载虚拟文件系统
mirage mount /path/to/mount --backend memory

# 卸载
mirage unmount /path/to/mount

与其他方案的对比

• Docker：Docker提供完整的容器隔离，但资源开销大。Mirage更轻量
• chroot：chroot只提供文件系统隔离，功能有限。Mirage功能更丰富
• tmpfs：tmpfs是内存文件系统，但没有快照、权限控制等功能

总结

Mirage为AI Agent提供了一个安全、灵活的文件操作环境。随着AI编程Agent的普及，这类基础设施会越来越重要。如果你正在开发或使用AI编程工具，Mirage值得一试。

项目地址：https://github.com/strukto-ai/mirage