strukto-ai--mirage/readme/README.zh-TW.md

Mirage 是 面向 AI Agent 的統一虛擬檔案系統：它把 S3、Google Drive、Slack、Gmail、Redis 等服務和資料來源並排掛載為同一個檔案系統。任何已經會用 bash 的 LLM 都可以開箱即用地對每個後端進行讀取、grep 和管線操作，不需要學習新的詞彙。

ws = Workspace(
    {
        "/tmp":   (RAMResource(), MountMode.EXEC),
        "/redis": (RedisResource(url=redis_url), MountMode.WRITE),
        "/slack": (SlackResource(SlackConfig(token=slack_bot_token)), MountMode.EXEC),
    },
    # monty 捕獲 python，腳本在工作區內以沙箱方式執行
    runtimes=[MontyRuntime(captures=["python", "python3"]), "vfs"],
)

# 一次 grep 掃遍所有資料來源
await ws.execute("grep -rln session /redis /tmp")

# 執行放在 Slack 裡的腳本，把報告寫入 Redis
await ws.execute(
    "python3 /slack/channels/general__C0.../files/example__F0....py > /redis/report.txt"
)

# 以頭部命令名安裝一個型別化 CLI：依名稱分派，而不是依路徑，
# 並且像其他程式一樣可以透過 `man`、`type`、`which` 發現
ws.register_cli("slack", SLACK, {"token": slack_bot_token})
await ws.execute('slack send-message --channel general --text "report is up"')

關於

• 一個介面，而不是 N 個 SDK 和 M 個 MCP。 每個服務都使用同一套檔案系統語意，管線可以像在本機磁碟上一樣跨服務組合。
• 約 50 個內建後端： RAM、Disk、Redis、S3 / R2 / OCI / Supabase / GCS、Gmail / GDrive / GDocs / GSheets / GSlides、GitHub / Linear / Notion / Trello、Slack / Discord / Email、MongoDB / GridFS / Postgres / LanceDB / Qdrant、SSH 等，並排掛載在同一個根目錄下。
• 可攜的工作區： 克隆、快照和版本化工作區；Agent 執行可以在機器之間遷移，而不必重啟或重新設定系統。
• 可嵌入： Python 和 TypeScript SDK 直接執行在 FastAPI、Express、瀏覽器應用或任何非同步執行環境的行程內，不需要獨立的行程。
• Agent 整合： 透過 SDK 支援 OpenAI Agents SDK、Vercel AI SDK、LangChain、Pydantic AI、CAMEL 和 OpenHands；編碼 Agent 則透過原生轉接器、可安裝外掛、MCP 或 FUSE 接入。

架構

安裝

• Python ≥ 3.11，用於 mirage-ai 套件和 mirage CLI
• Node.js ≥ 20，用於 TypeScript SDK
• macOS 或 Linux（基於 FUSE 的掛載需要平台支援）

Python

uv add mirage-ai    # 安裝 `mirage` 函式庫和 `mirage` CLI 執行檔

TypeScript

npm install @struktoai/mirage-node      # Node.js 伺服器和 CLI
npm install @struktoai/mirage-browser   # 瀏覽器 / edge 執行環境
npm install @struktoai/mirage-agents    # OpenAI / Vercel AI / LangChain / Mastra 介接器

兩個執行環境套件都會自動引入 @struktoai/mirage-core。

CLI

curl -fsSL https://strukto.ai/mirage/install.sh | sh
# 或
npm install -g @struktoai/mirage-cli
# 或
uvx mirage-ai
# 或
npx @struktoai/mirage-cli

快速開始

Python

from mirage import Workspace
from mirage.resource.ram import RAMResource
from mirage.resource.s3 import S3Config, S3Resource

ws = Workspace({
    "/data": RAMResource(),
    "/s3":   S3Resource(S3Config(bucket="my-bucket")),
})

await ws.execute("cp /s3/report.csv /data/report.csv")
await ws.execute("grep alert /s3/data/log.jsonl | wc -l")

await ws.snapshot("demo.tar")

TypeScript

import { Workspace, RAMResource, S3Resource } from '@struktoai/mirage-node'

const ws = new Workspace({
  '/data': new RAMResource(),
  '/s3':   new S3Resource({ bucket: 'my-bucket' }),
})

await ws.execute('cp /s3/report.csv /data/report.csv')
await ws.execute('grep alert /s3/data/log.jsonl | wc -l')

await ws.snapshot('demo.tar')

CLI

mirage workspace create ws.yaml --id demo
mirage execute   --workspace_id demo --command "cp /s3/report.csv /data/report.csv"
mirage provision --workspace_id demo --command "cat /s3/data/large.jsonl"
mirage workspace snapshot demo demo.tar
mirage workspace load demo.tar --id demo-restored

Agent 框架

Mirage 可以作為沙箱或工具層接入 Agent 框架。read 等 POSIX 操作也可以按資源和檔案類型自訂：Mirage 不內建任何檔案類型渲染器，因此某種格式如何渲染完全取決於你註冊的實作，而針對特定資源和副檔名註冊的命令優先於通用命令。

	整合
Python	OpenAI Agents SDK、LangChain、Pydantic AI、CAMEL、OpenHands、Agno
TypeScript	Vercel AI SDK、OpenAI Agents SDK、LangChain、Mastra
編碼 Agent	Claude Code、Codex、DeepSeek Harness、Grok Build、OpenCode、Pi

快取

每個 Workspace 都有兩層快取，讓針對遠端後端的重複操作命中本機狀態而不是網路：

• 索引快取： 目錄列表和中繼資料。第一次遍歷目錄會呼叫 API；之後在 TTL 過期前（預設 10 分鐘）都從索引讀取。
• 檔案快取： 物件位元組。第一次讀取從來源端串流拉取；之後的管線直接讀快取（預設 512 MB）。

兩層預設都使用行程內 RAM，零設定。Redis 儲存可以在 worker、行程和機器之間共享快取狀態：

import { RedisFileCacheStore, S3Resource, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/s3': new S3Resource({ bucket: 'my-bucket' }) },
  {
    cache: new RedisFileCacheStore({ url: 'redis://localhost:6379/0', cacheLimit: '8GB' }),
    index: { type: 'redis', url: 'redis://localhost:6379/0', ttl: 600 },
  },
)

完整的 miss/hit 生命週期見快取文件。

貢獻者

感謝所有為 Mirage 做出貢獻的人。