strukto-ai--mirage/readme/README.vi.md

Mirage là hệ thống tệp ảo thống nhất cho AI Agent: nó gắn các dịch vụ và nguồn dữ liệu như S3, Google Drive, Slack, Gmail và Redis cạnh nhau thành một hệ thống tệp duy nhất. Bất kỳ LLM nào đã biết bash đều có thể đọc, grep và nối pipe trên mọi backend ngay từ đầu, không cần từ vựng mới.

ws = Workspace(
    {
        "/tmp":   (RAMResource(), MountMode.EXEC),
        "/redis": (RedisResource(url=redis_url), MountMode.WRITE),
        "/slack": (SlackResource(SlackConfig(token=slack_bot_token)), MountMode.EXEC),
    },
    # monty bắt python, nên script chạy trong sandbox bên trong workspace
    runtimes=[MontyRuntime(captures=["python", "python3"]), "vfs"],
)

# một lệnh grep quét mọi nguồn
await ws.execute("grep -rln session /redis /tmp")

# chạy script nằm trong Slack, ghi báo cáo vào Redis
await ws.execute(
    "python3 /slack/channels/general__C0.../files/example__F0....py > /redis/report.txt"
)

# cài một CLI có kiểu dưới một từ khóa: điều phối theo tên, không theo đường dẫn,
# và có thể khám phá qua `man`, `type`, `which` như mọi chương trình khác
ws.register_cli("slack", SLACK, {"token": slack_bot_token})
await ws.execute('slack send-message --channel general --text "report is up"')

Giới thiệu

• Một giao diện thay vì N SDK và M MCP. Mọi dịch vụ đều dùng cùng một ngữ nghĩa hệ thống tệp, và pipeline kết hợp giữa các dịch vụ tự nhiên như trên đĩa cục bộ.
• Khoảng 50 backend tích hợp sẵn: 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 và nhiều hơn nữa, được gắn cạnh nhau dưới một gốc duy nhất.
• Workspace di động: clone, snapshot và đánh phiên bản workspace; phiên chạy agent di chuyển giữa các máy mà không cần khởi động lại hay cấu hình lại hệ thống.
• Nhúng được: SDK Python và TypeScript chạy ngay trong tiến trình của FastAPI, Express, ứng dụng trình duyệt hoặc bất kỳ runtime bất đồng bộ nào; không cần tiến trình riêng.
• Tích hợp agent: OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL và OpenHands qua các SDK; các agent lập trình qua adapter gốc, plugin cài được, MCP hoặc FUSE.

Kiến trúc

Cài đặt

• Python ≥ 3.11 cho gói mirage-ai và CLI mirage
• Node.js ≥ 20 cho SDK TypeScript
• macOS hoặc Linux (mount dựa trên FUSE cần nền tảng hỗ trợ)

Python

uv add mirage-ai    # cài thư viện `mirage` và binary CLI `mirage`

TypeScript

npm install @struktoai/mirage-node      # máy chủ Node.js và CLI
npm install @struktoai/mirage-browser   # trình duyệt / edge runtime
npm install @struktoai/mirage-agents    # adapter OpenAI / Vercel AI / LangChain / Mastra

Cả hai gói runtime đều tự động kéo theo @struktoai/mirage-core.

CLI

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

Bắt đầu nhanh

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

Framework agent

Mirage cắm vào các framework agent như một lớp sandbox hoặc công cụ. Các thao tác POSIX như read cũng có thể tùy biến theo tài nguyên và loại tệp: Mirage không đi kèm bộ render định dạng nào, nên một định dạng hiển thị đúng theo cách bạn đăng ký, và lệnh đăng ký cho một tài nguyên và phần mở rộng cụ thể sẽ thắng lệnh chung.

	Tích hợp
Python	OpenAI Agents SDK, LangChain, Pydantic AI, CAMEL, OpenHands, Agno
TypeScript	Vercel AI SDK, OpenAI Agents SDK, LangChain, Mastra
Coding agent	Claude Code, Codex, DeepSeek Harness, Grok Build, OpenCode, Pi

Bộ nhớ đệm

Mỗi Workspace có bộ nhớ đệm hai tầng, để công việc lặp lại trên các backend từ xa dùng trạng thái cục bộ thay vì mạng:

• Cache chỉ mục: danh sách thư mục và metadata. Lần duyệt thư mục đầu tiên gọi API; các lần sau đọc từ chỉ mục cho đến khi TTL hết hạn (mặc định 10 phút).
• Cache tệp: byte của đối tượng. Lần đọc đầu tiên stream từ nguồn; các pipeline sau đọc từ cache (mặc định 512 MB).

Cả hai tầng mặc định dùng RAM trong tiến trình, không cần cấu hình. Store Redis chia sẻ trạng thái cache giữa các worker, tiến trình và máy:

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 },
  },
)

Xem tài liệu cache để biết vòng đời miss/hit đầy đủ.

Người đóng góp

Cảm ơn tất cả những người đã đóng góp cho Mirage.