Mirage

官方

统一虚拟文件系统,让AI代理用bash命令跨云存储、SaaS与数据库操作数据。

分类: 文件系统第 18 / 24
Stars: ★ 3.8k 非常热门
运行环境: Node.js 20+ · Python 3.11+ · 预编译二进制
凭据: 可选 API Key
许可证: Apache-2.0
最近提交: 今天
工具数: 1

47FMRS · D

Mirage 将约 50 种数据源统一为单一虚拟文件系统,通过标准 bash 命令(cp、grep、wc、cat、find 等)供 AI 代理跨后端操作,并支持 MCP、FUSE、原生适配器等多种代理集成方式;其价值在于消除多套 SDK/MCP 的学习成本,但通用命令执行接口也意味着权限和风险需要按挂载后端的敏感程度谨慎管理。

最强项 · 文档质量 12/20 最弱项 · 可靠性 6/20

可靠性

6/20

安全与权限

8/20

维护活跃度

10/20

文档质量

12/20

安装易用性

11/20

查看各项评分依据

可靠性 6/20: 所提供的“服务器清单”实际上只是 integ/unix/office/server.json 中的单条集成测试用例（针对 cp+wc 场景，覆盖 onedrive/sharepoint 等目标），并非真实的 MCP 工具清单、初始化/tool-list 握手说明或运行时行为定义。没有任何 CI workflow 证据,也看不到工具声明与实际行为的对应关系,更没有错误处理、依赖控制或多场景测试覆盖的证明。按静态评审规则,没有真实 CI + 覆盖关键路径的测试证据时可靠性不得超过 12,而此处仅有一条孤立测试片段,远不足以证明关键路径可复现,因此评分保持在低区间。
安全与权限 8/20: README 中展示的凡例使用环境变量存放凭据（如 SLACK_BOT_TOKEN）而非硬编码密钥,这是可取的做法,且未发现红线级问题（无恶意代码、无凭据泄露、无危险默认操作的证据）。但 Mirage 将约 50 种后端（S3、Gmail、Slack、GitHub、MongoDB 等）统一挂载为同一文件系统,通过类 bash 命令（cp、rm 等）跨服务操作,而所给材料完全没有展示最小权限设计、跨资源访问边界、危险操作确认机制或权限范围收窄的证据。清单本身的测试用例（跨 office 云存储的复制操作）也未展示任何权限校验或确认流程。风险面广而控制证据缺失,因此扣分明显。
维护活跃度 10/20: 仓库为 Apache-2.0 许可、未归档、star 数较高（3383,仅作为发现信号不计入打分）,但 106 个未关闭 issue 显示存在一定积压。所给材料中没有发布记录、变更日志、依赖更新策略或安全响应渠道的直接证据,无法判断版本治理是否规范,只能基于“未归档+有许可证+看起来活跃”的最基本信号打分,处于中等偏下水平。
文档质量 12/20: README 整体质量较好：提供 Python/TypeScript/CLI 的安装与快速开始示例、架构图、缓存机制说明、多语言版本以及丰富的 Agent 框架集成对照表。但针对被评审的具体服务器功能（office 文件在 onedrive/sharepoint 间复制、“no re-enrich”这一行为语义、副本大小预期等）完全没有专门说明,用户无法从文档判断该测试用例背后的实际语义、限制或故障排除方法,存在明显的功能级文档空白。
安装易用性 11/20: 安装路径多样（uv add、npm install、curl 安装脚本、npx/uvx）,CLI quickstart 命令清晰,平台要求（macOS/Linux, Python≥3.11, Node≥20）说明明确。但材料中没有给出任何主流客户端（如 Claude Desktop 等）的 MCP 配置示例,仅在文档链接中提到“MCP”作为集成方式之一,缺乏可直接复制的最小可用配置。按静态评审规则,没有可验证的执行证据时安装易用性不得超过 15,故评分低于该上限。

静态评测 · 未实际运行收录于 2026-08-06

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件执行命令或代码访问网络

适合谁

已经会用 bash 命令、希望以文件系统方式统一访问多种数据源的 AI 代理开发者
需要在 S3、Google Drive、Slack、OneDrive/SharePoint 等多个后端间进行数据管道操作的场景
希望将代理工作区嵌入 Python/TypeScript 应用(FastAPI、Express 等)中运行的团队

不适合谁

只需要访问单一服务且不需要跨后端统一接口的简单场景
非 macOS/Linux 平台且依赖 FUSE 挂载的场景
需要明确、细粒度权限控制而非通用 bash 命令执行接口的高安全性场景

所需权限

所挂载各后端(如 OneDrive、SharePoint、S3、Slack、Gmail 等)的访问凭据或 API 令牌
本地文件系统读写权限(用于 RAM/Disk 资源及缓存)
访问远程 API 所需的网络出站权限

风险与副作用

单一的类 bash 执行接口可能允许代理对多个已挂载的敏感系统执行大范围读取、复制或覆盖操作
跨后端内容(如从 Slack、邮件等抓取的文本)存在提示注入风险,可能影响代理后续行为
索引缓存和文件缓存存在 TTL(默认 10 分钟/内容不过期直到失效),可能导致读取到过期数据
凭据一旦配置给工作区,代理即可能获得比预期更广的跨服务访问范围

安装接入

准备工作

运行环境：Node.js 20+ · Python 3.11+ · 预编译二进制

SLACK_BOT_TOKEN 可选密钥 Slack 机器人的 bot token，用于挂载 SlackResource 访问 Slack 频道；从 Slack App 的 OAuth 凭据页面获取。

根据语言环境选择安装方式:Python 用户可通过 uv add mirage-ai 安装 mirage-ai 包及 mirage CLI(需 Python ≥3.11);TypeScript/Node.js 用户可通过 npm install @struktoai/mirage-node(或 mirage-browser、mirage-agents)安装(需 Node.js ≥20);也可通过官方安装脚本或 npm install -g @struktoai/mirage-cli 获取独立 CLI。安装后需在工作区配置中声明要挂载的后端(如 OneDrive、SharePoint)及其访问凭据,再通过 MCP、原生适配器或 FUSE 方式接入具体的编码代理。源码中未给出具体的 MCP 客户端配置 JSON 示例。

验证是否装好

在客户端工具列表中确认出现 execute 工具，然后执行一条如 cp /s3/report.csv /data/report.csv 的命令，若成功返回即说明连接正常。

常见排障

确认平台为 macOS 或 Linux,因为基于 FUSE 的挂载需要相应平台支持
确认 Python 版本 ≥3.11 或 Node.js 版本 ≥20,否则 SDK 安装或运行会失败
检查各已挂载后端(如 OneDrive/SharePoint)的凭据和环境变量是否正确配置
如读取到旧数据,检查索引缓存(默认 10 分钟)和文件缓存(默认 512MB)的 TTL 设置
涉及多进程/多机器共享缓存时,确认 Redis 缓存存储配置(URL、缓存上限)是否正确

试试这样问

连接成功后，可以直接对 AI 助手这样说：

把 /s3/report.csv 复制到 /data/local.csv 并确认文件存在
在 /slack/channels 中搜索包含 alert 的消息并统计条数
统计 /s3/data 下所有 .l 文件的行数
对 /data/local.csv 运行 summarize 命令

工具能力 1

execute 写入

对挂载在工作区中的资源(如 S3、OneDrive、SharePoint、Slack 等)执行类 bash 命令(如 cp、grep、wc、cat、find),实现跨后端的文件读取、检索与管道组合。

使用场景

让编码代理用统一的 bash 语义跨多个云存储和 SaaS 后端检索、复制、汇总数据

在 OneDrive/SharePoint 等办公文档源上执行文件复制等操作而不触发不必要的重新解析

构建可跨机器移植的代理工作区(克隆、快照、版本化)

支持客户端

Claude Code部分支持

依据项目文档列出，未经本站实测。

详细介绍

Mirage 是一个面向 AI 代理的统一虚拟文件系统(VFS),可将 S3、Google Drive、Slack、Gmail、OneDrive/SharePoint、Redis 等约 50 种后端服务并排挂载为同一个文件系统。已经掌握 bash 的大模型无需学习新的工具词汇,即可用 cp、grep、wc、cat、find 等命令在不同后端之间读取、检索和组合数据流。项目提供 Python 和 TypeScript SDK、CLI,并可通过原生适配器、插件、MCP 或 FUSE 接入 OpenAI Agents SDK、LangChain、Claude Code 等代理框架。示例测试用例(office_server_copy_no_reenrich)展示了在 OneDrive、SharePoint 等目标上对 Office 文档执行 cp 复制且不触发重新解析(re-enrich)的行为,体现了其跨后端文件操作的一致性设计。