适合谁
- 已经会用 bash 命令、希望以文件系统方式统一访问多种数据源的 AI 代理开发者
- 需要在 S3、Google Drive、Slack、OneDrive/SharePoint 等多个后端间进行数据管道操作的场景
- 希望将代理工作区嵌入 Python/TypeScript 应用(FastAPI、Express 等)中运行的团队
M
47FMRS · D
Mirage 将约 50 种数据源统一为单一虚拟文件系统,通过标准 bash 命令(cp、grep、wc、cat、find 等)供 AI 代理跨后端操作,并支持 MCP、FUSE、原生适配器等多种代理集成方式;其价值在于消除多套 SDK/MCP 的学习成本,但通用命令执行接口也意味着权限和风险需要按挂载后端的敏感程度谨慎管理。
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)的行为,体现了其跨后端文件操作的一致性设计。
工具能力
execute
对挂载在工作区中的资源(如 S3、OneDrive、SharePoint、Slack 等)执行类 bash 命令(如 cp、grep、wc、cat、find),实现跨后端的文件读取、检索与管道组合。
安装接入
根据语言环境选择安装方式: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 示例。
选型与风险
不适合谁
- 只需要访问单一服务且不需要跨后端统一接口的简单场景
- 非 macOS/Linux 平台且依赖 FUSE 挂载的场景
- 需要明确、细粒度权限控制而非通用 bash 命令执行接口的高安全性场景
所需权限
- 所挂载各后端(如 OneDrive、SharePoint、S3、Slack、Gmail 等)的访问凭据或 API 令牌
- 本地文件系统读写权限(用于 RAM/Disk 资源及缓存)
- 访问远程 API 所需的网络出站权限
风险与副作用
- 单一的类 bash 执行接口可能允许代理对多个已挂载的敏感系统执行大范围读取、复制或覆盖操作
- 跨后端内容(如从 Slack、邮件等抓取的文本)存在提示注入风险,可能影响代理后续行为
- 索引缓存和文件缓存存在 TTL(默认 10 分钟/内容不过期直到失效),可能导致读取到过期数据
- 凭据一旦配置给工作区,代理即可能获得比预期更广的跨服务访问范围
常见排障
- 确认平台为 macOS 或 Linux,因为基于 FUSE 的挂载需要相应平台支持
- 确认 Python 版本 ≥3.11 或 Node.js 版本 ≥20,否则 SDK 安装或运行会失败
- 检查各已挂载后端(如 OneDrive/SharePoint)的凭据和环境变量是否正确配置
- 如读取到旧数据,检查索引缓存(默认 10 分钟)和文件缓存(默认 512MB)的 TTL 设置
- 涉及多进程/多机器共享缓存时,确认 Redis 缓存存储配置(URL、缓存上限)是否正确
使用场景
让编码代理用统一的 bash 语义跨多个云存储和 SaaS 后端检索、复制、汇总数据
在 OneDrive/SharePoint 等办公文档源上执行文件复制等操作而不触发不必要的重新解析
构建可跨机器移植的代理工作区(克隆、快照、版本化)
支持客户端
Claude Code部分支持