Mirage：给 AI Agent 装上一个「统一虚拟文件系统」

当你在写代码时，AI 需要同时访问项目代码、文档、API 文档、测试文件……问题是这些文件散落在不同地方，AI 需要理解它们的关联关系才能做出正确决策。

Mirage 解决的就是这个问题：给 AI Agent 构建一个统一的虚拟文件系统，所有资源都在一个逻辑视图里。

Mirage 是什么

GitHub: https://github.com/strukto-ai/mirage Stars: 2,084 ⭐ | TypeScript

Mirage 是一个统一虚拟文件系统，专门为 AI Agent 设计。它不是真的去移动文件，而是在逻辑层面把所有相关资源聚合到一个视图中，让 AI 可以像操作本地文件一样访问分散在不同位置的资源。

// 初始化 Mirage
const mirage = new Mirage();

// 添加多个数据源
mirage.addSource({
  type: 'local',
  path: './src',
  pattern: '**/*.ts'
});

mirage.addSource({
  type: 'github',
  repo: 'facebook/react',
  path: '/docs'
});

mirage.addSource({
  type: 'url',
  url: 'https://api.example.com/docs'
});

// AI 只需要查询 Mirage，而不是每个数据源
const results = await mirage.query("这个项目的架构是怎样的？");

核心能力

1. 多数据源聚合

• 本地文件（任何目录结构）
• GitHub 仓库（任意分支、任意路径）
• URL（在线文档、API 文档）
• 数据库（Schema 查询）
• API 响应（REST/GraphQL）

所有这些在 Mirage 里变成一个统一的文件系统视图。

2. 语义理解

Mirage 不只是索引文件内容，它会理解：

• 哪个文件依赖哪个文件
• 文档和代码的对应关系
• API 定义和实现的映射

3. 上下文感知查询

传统 RAG：你问"这个函数怎么用"，它返回最相关的几个文本块。

Mirage：它知道这个函数在哪个文件、被哪些地方调用、文档怎么写的、测试怎么写的，返回的是一个完整的上下文单元。

为什么需要这个

AI Agent 的「上下文爆炸」问题

当 AI 需要理解一个复杂项目时，它面临：

• 文件太多（看不完）
• 分散在不同位置（GitHub、本地、API文档）
• 依赖关系复杂（需要理解上下文）

结果是：AI 要么漏掉关键信息，要么上下文太长超出 Token 限制。

Mirage 的思路：不试图给 AI 所有信息，而是给它最有结构的上下文。

使用场景

✅ 代码审查：让 AI 理解完整项目结构后做审查 ✅ 技术问答：回答"这个系统怎么设计"这类需要跨文件理解的问题 ✅ 代码生成：生成代码时知道依赖关系、现有模式 ✅ 文档生成：理解代码后自动生成配套文档

和其他方案对比

Mirage 的价值：让 AI 看到的不只是文本，而是结构化的知识。

结语

Mirage 解决的是一个很实际的问题：AI Agent 需要理解复杂项目，但文件散落在各处、没有结构。

它的思路很清晰：在数据源和 AI 之间加一个结构化层，让 AI 看到的不再是碎片化的文本，而是有组织的知识视图。

如果你在做 AI Coding 工具（尤其是面向复杂项目的），Mirage 的思路值得参考。

相关链接

• GitHub: https://github.com/strukto-ai/mirage
• 标签: AI Agent, 虚拟文件系统, 代码理解, RAG, 上下文管理