Mirage 统一虚拟文件系统
让 AI 代理用 Bash 跨服务读取、搜索和处理数据。
- Star 数
- ★ 3.6k
- 最近更新
- 4 天前
- License
- Apache-2.0
- 主语言
- TypeScript
- FA 评分
- 54/100 · 缺口较多
30 秒速览
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code · OpenAI API
- 开始前需要
- 典型场景
- 构建运维分析代理的团队，可把日志 S3 桶和 Slack 频道挂到同一工作区，用 grep 与 wc 统计告警。
- 主要局限
- 远程数据源依赖各自的网络连接、资源配置和凭据；示例中的 Slack 需要
SLACK_BOT_TOKEN。 - 源码审查
- 54/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Mirage 是面向 AI 代理的统一虚拟文件系统，将 S3、Google Drive、Slack、Gmail、Redis 等服务挂载到同一工作区路径树中。它提供 Python 与 TypeScript SDK、mirage CLI，以及可选的 FUSE 挂载方式；SDK 可在 FastAPI、Express、浏览器应用或异步运行时进程内运行。代理或应用通过 Workspace.execute 运行 Bash 风格命令，在不同后端之间读取、筛选、复制和管道处理文件。Workspace 还支持快照、加载与缓存，以便移动或复用工作区状态。仓库同时列出 OpenAI Agents SDK、LangChain、Vercel AI SDK、Claude Code、Codex 等集成路径。
开发者以 Workspace 创建挂载表，例如将 RAMResource 挂到 /data、将 S3Resource 挂到 /s3，随后调用 await ws.execute("cp /s3/report.csv /data/report.csv") 或 grep、find、wc 等命令。命令可跨挂载目录组合，并可用 ws.command 注册命令，或按 resource 与 filetype 覆盖如 cat 的行为。mirage CLI 可创建工作区、执行命令、provision 资源、生成快照并从 demo.tar 载入工作区。每个 Workspace 提供索引缓存和文件缓存；可配置 RedisFileCacheStore 与 Redis 索引来在工作进程、进程或机器间共享缓存。
- 构建运维分析代理的团队，可把日志 S3 桶和 Slack 频道挂到同一工作区，用 grep 与 wc 统计告警。
- 需要在远程对象存储与临时工作区之间处理报表的 Python 服务，可通过 Workspace.execute 将 /s3/report.csv 复制到 /data。
- 为 OpenAI Agents SDK、LangChain 或 Pydantic AI 添加统一数据访问层的开发者，可采用仓库列出的 Python 集成路径。
- 在 Node.js 服务中整合 Google Drive、Gmail、GitHub、Notion 或 Slack 数据的团队，可使用 TypeScript SDK 将相应后端挂载为目录。
- 需要迁移或保存代理运行状态的工程团队，可使用 workspace snapshot 和 load 命令导出、恢复工作区。
如何安装或部署这个 Agent？
Python 环境需 3.11 或更高版本：uv add mirage-ai。Node.js 环境需 20 或更高版本：npm install @struktoai/mirage-node；浏览器或边缘运行时可安装 @struktoai/mirage-browser，代理适配器可安装 @struktoai/mirage-agents。CLI 可用 npm install -g @struktoai/mirage-cli、uvx mirage-ai、npx @struktoai/mirage-cli，或 README 所示安装脚本。使用远程资源时须提供相应资源配置；示例中的 SlackResource 读取 SLACK_BOT_TOKEN，S3Resource 配置 bucket。
如何使用这个 Agent？
Python 最小示例：from mirage import Workspace、from mirage.resource.ram import RAMResource，然后创建 ws = Workspace({"/data": RAMResource()}) 并执行 await ws.execute("ls /data")。要访问 S3，可加入 "/s3": S3Resource(S3Config(bucket="my-bucket"))，再运行 await ws.execute("cp /s3/report.csv /data/report.csv")。CLI 流程可从 mirage workspace create ws.yaml --id demo 开始，再执行 mirage execute --workspace_id demo --command "cp /s3/report.csv /data/report.csv"。
这个 Agent 有哪些优点和局限？
- 以路径、Bash 命令和管道统一访问多个数据后端，避免为每个服务编写不同的调用方式。
- Python 和 TypeScript SDK 可进程内嵌入，并提供 CLI、MCP、FUSE 和多种代理框架集成路径。
- 索引缓存与文件缓存默认在进程内启用，并可用 Redis 在多个 worker、进程和机器间共享。
- 工作区可 clone、snapshot 和 version，CLI 也支持将快照载入为新的工作区。
- 远程数据源依赖各自的网络连接、资源配置和凭据；示例中的 Slack 需要
SLACK_BOT_TOKEN。 - Python、Node.js 与 FUSE 的运行条件不同；FUSE 挂载还受 macOS 或 Linux 的平台支持限制。
- 仓库宣称约 50 个后端，但给出的内容未逐一说明每个后端的权限模型、操作覆盖范围或故障处理行为。
- 缓存具有默认 10 分钟索引 TTL 和 512 MB 文件缓存上限，实时性或大文件工作负载可能需要调整配置。
这个 Agent 与同类方案有什么区别？
Mirage 的定位是用一个文件系统接口替代分别学习多个服务 SDK 与多个 MCP 接口；它保留 Bash 风格的 read、grep、pipe 等工作方式，而不是为每个后端引入独立命令语义。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|
| Mirage 统一虚拟文件系统 当前 | 54 · 缺口较多 | ★ 3.6k | 4 天前 | TypeScript | Codex · Claude Code · OpenAI API |
| AnyAgent | 41 · 缺口较多 | ★ 1.2k | 4 个月前 | Python | — |
| Agentic AI 工程课程 | 39 · 缺口较多 | ★ 6.2k | 4 天前 | Jupyter Notebook | OpenAI API |
| OpenGAP | 51 · 缺口较多 | ★ 2.9k | 2 个月前 | TypeScript | Codex · Claude Code · OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：CLI测试验证了认证模式（local/token/jwt），token文件权限为600，健康检查绕过认证，但未发现用户确认机制或数据流透明度的文档。扣分原因：用户确认缺失，数据流透明度仅部分提及（缓存），敏感数据处理有认证但未明确加密。
证据显示：CLI测试覆盖了退出码传播、管道行为、命令限制等，表明错误处理有测试。扣分原因：依赖可用性未明确，失败消息未在文档中详细说明。
证据显示：README列出了多种后端和集成，支持Python和TypeScript，有CLI和SDK。扣分原因：能力边界未明确，触发精度（命令）有示例但未全面，环境适配有说明但未深入。
证据显示：README结构清晰，安装说明详细，有示例，许可证为Apache-2.0。扣分原因：命名稳定性未明确，已知限制未列出，版本变更日志未提供，维护责任未明确。
证据显示：输出可用性有示例，边际价值高（统一文件系统），成本效益未量化。扣分原因：成本效益未提供数据。
证据显示：README中的声明有部分文档链接，但未提供具体证据。扣分原因：声明可追溯性不足，跨来源验证有限，事实与推断未明确分离。
- 未发现用户确认机制，执行命令可能无提示。
- 数据流透明度有限，缓存机制可能隐藏数据访问。
- 依赖安全未明确，需检查依赖漏洞。
- 已知限制未列出，可能影响生产使用。
常见问题
它是否只适用于某一种模型或代理框架？
远程服务的数据会每次都重新请求吗？
能否把工作区迁移到另一台机器？
mirage workspace snapshot 与 mirage workspace load。