github-featured/strukto-ai--mirage
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
strukto-ai--mirage/readme/README.ko.md
T
Zecheng Zhang a1a769848e docs: fix the README hero snippet, resync the mirrors, and give each CLI page its own icon (#801) 
* docs(readme): fix the hero snippet and resync every mirror

The hero snippet called ws.command(...), which exists in neither
language: registration is the standalone command() plus mount.register.
It is replaced with a Python example that mounts ram, redis and slack
side by side, captures python with monty, and installs a CLI, all of it
run against the published 0.0.5 packages first.

Two more corrections. The filetype sentence promised parsed PDF pages,
which the filetype removal took away, so it now says a format renders
however you register it. DeepSeek Harness joins the coding agents row.

The eleven mirrors are regenerated from the root rather than patched,
which also closes drift they had accumulated: a stale backend list, the
old CLI + daemon integrations line, a missing Grok Build entry and a
Codex link pointing at the wrong docs path.

* docs(cli): give each CLI page its own icon

Every CLI page shared icon: terminal, so the sidebar was nine identical
rows. Each now takes the icon its service already uses elsewhere in the
docs: slack, discord, github for gh, google for gws, envelope for
himalaya, book for ntn and chart-gantt for linear (matching the notion
and linear setup pages, since Font Awesome carries no brand mark for
either), and git-alt for git. gws and himalaya also get their names
spelled GWS and Himalaya; the rest stay lowercase because that is the
head word you type.

* examples(filetype): register through the public mount accessor

The example reached into ws._registry.mount_for, but ws.mount is public
and returns the same MountEntry. Output is unchanged, so the CI truth
file still matches.
2026-08-14 21:41:01 -07:00

199 lines
11 KiB
Markdown
Raw Permalink Blame History

<p align="center">
<img src="../assets/mirage-og-light@2x.png" alt="Mirage: AI 에이전트를 위한 통합 가상 파일 시스템" width="900">
</p>
<p align="center">
<a href="https://docs.mirage.strukto.ai" alt="문서">
<img src="https://img.shields.io/badge/mirage-%EB%AC%B8%EC%84%9C-0C0C0C?labelColor=FAFAFA" /></a>
<a href="https://www.strukto.ai" alt="웹사이트">
<img src="https://img.shields.io/badge/strukto.ai-%EC%A0%9C%EC%9E%91-0C0C0C?labelColor=FAFAFA" /></a>
<a href="https://github.com/strukto-ai/mirage/blob/main/LICENSE" alt="라이선스">
<img src="https://img.shields.io/github/license/strukto-ai/mirage?label=%EB%9D%BC%EC%9D%B4%EC%84%A0%EC%8A%A4&color=0C0C0C&labelColor=FAFAFA" /></a>
<a href="https://discord.gg/u8BPQ65KsS" alt="Discord">
<img src="https://img.shields.io/badge/discord-%EC%B0%B8%EC%97%AC-0C0C0C?labelColor=FAFAFA&logo=discord&logoColor=0C0C0C" /></a>
<br/>
<a href="https://docs.mirage.strukto.ai/python/quickstart" alt="Python 문서">
<img src="https://img.shields.io/badge/python-%EB%AC%B8%EC%84%9C-0C0C0C?labelColor=FAFAFA&logo=python&logoColor=0C0C0C" alt="Python 문서"></a>
<a href="https://pypi.org/project/mirage-ai/" alt="PyPI 버전">
<img src="https://img.shields.io/pypi/v/mirage-ai.svg?color=0C0C0C&labelColor=FAFAFA"/></a>
<br/>
<a href="https://docs.mirage.strukto.ai/typescript/quickstart" alt="TypeScript 문서">
<img src="https://img.shields.io/badge/typescript-%EB%AC%B8%EC%84%9C-0C0C0C?labelColor=FAFAFA&logo=typescript&logoColor=0C0C0C" alt="TypeScript 문서"></a>
<a href="https://www.npmjs.com/package/@struktoai/mirage-node" alt="NPM 버전">
<img src="https://img.shields.io/npm/v/@struktoai/mirage-node.svg?color=0C0C0C&labelColor=FAFAFA"/></a>
</p>
<p align="center">
<a href="../README.md"><img alt="README in English" src="https://img.shields.io/badge/English-d9d9d9"></a>
<a href="./README.zh-CN.md"><img alt="简体中文 README" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>
<a href="./README.zh-TW.md"><img alt="繁體中文 README" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>
<a href="./README.fr.md"><img alt="README en Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>
<a href="./README.vi.md"><img alt="README Tiếng Việt" src="https://img.shields.io/badge/Ti%E1%BA%BFng%20Vi%E1%BB%87t-d9d9d9"></a>
<a href="./README.ko.md"><img alt="README 한국어" src="https://img.shields.io/badge/%ED%95%9C%EA%B5%AD%EC%96%B4-d9d9d9"></a>
</p>
Mirage는 **AI 에이전트를 위한 통합 가상 파일 시스템**입니다. S3, Google Drive, Slack, Gmail, Redis 같은 서비스와 데이터 소스를 나란히 하나의 파일 시스템으로 마운트합니다. bash를 이미 아는 LLM이라면 새로운 어휘 없이 바로 모든 백엔드를 읽고, grep하고, 파이프로 연결할 수 있습니다.
```python
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 등을 하나의 루트 아래 나란히 마운트합니다.
- **이식 가능한 워크스페이스:** 워크스페이스를 클론, 스냅샷, 버전 관리할 수 있습니다. 에이전트 실행을 재시작이나 재설정 없이 머신 간에 옮길 수 있습니다.
- **임베딩 가능:** Python과 TypeScript SDK가 FastAPI, Express, 브라우저 앱 또는 모든 비동기 런타임의 프로세스 안에서 직접 실행됩니다. 별도 프로세스가 필요 없습니다.
- **에이전트 통합:** SDK를 통해 OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, OpenHands를 지원하며, 코딩 에이전트는 네이티브 어댑터, 설치형 플러그인, MCP 또는 FUSE로 연결된다.
## 아키텍처
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="../assets/mirage-arch-dark.svg">
<img src="../assets/mirage-arch-light.svg" alt="Mirage 아키텍처: AI 에이전트와 애플리케이션 → Mirage Bash와 VFS → Dispatcher와 캐시 → 인프라와 원격 서비스" width="720">
</picture>
</p>
## 설치
- **Python** ≥ 3.11: `mirage-ai` 패키지와 `mirage` CLI
- **Node.js** ≥ 20: TypeScript SDK
- **macOS** 또는 **Linux** (FUSE 기반 마운트는 플랫폼 지원 필요)
### Python
```bash
uv add mirage-ai # `mirage` 라이브러리와 `mirage` CLI 바이너리를 설치
```
### TypeScript
```bash
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
```bash
curl -fsSL https://strukto.ai/mirage/install.sh | sh
# 또는
npm install -g @struktoai/mirage-cli
# 또는
uvx mirage-ai
# 또는
npx @struktoai/mirage-cli
```
## 빠른 시작
### Python
```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
```ts
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
```bash
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
```
## 에이전트 프레임워크
Mirage는 샌드박스 또는 도구 계층으로 에이전트 프레임워크에 연결된다. `read` 같은 POSIX 연산도 리소스와 파일 타입별로 커스터마이즈할 수 있다: Mirage는 파일 타입 렌더러를 전혀 포함하지 않으므로 형식은 등록한 방식대로 렌더링되며, 특정 리소스와 확장자에 등록한 명령이 일반 명령보다 우선한다.
| | 통합 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Python | [OpenAI Agents SDK](https://docs.mirage.strukto.ai/python/agents/openai-agents), [LangChain](https://docs.mirage.strukto.ai/python/agents/langchain), [Pydantic AI](https://docs.mirage.strukto.ai/python/agents/pydantic-ai), [CAMEL](https://docs.mirage.strukto.ai/python/agents/camel), [OpenHands](https://docs.mirage.strukto.ai/python/agents/openhands), [Agno](https://docs.mirage.strukto.ai/python/agents/agno) |
| TypeScript | [Vercel AI SDK](https://docs.mirage.strukto.ai/typescript/agents/vercel), [OpenAI Agents SDK](https://docs.mirage.strukto.ai/typescript/agents/openai), [LangChain](https://docs.mirage.strukto.ai/typescript/agents/langchain), [Mastra](https://docs.mirage.strukto.ai/typescript/agents/mastra) |
| 코딩 에이전트 | [Claude Code](https://docs.mirage.strukto.ai/python/agents/claude-code), [Codex](https://docs.mirage.strukto.ai/typescript/agents/codex), [DeepSeek Harness](https://docs.mirage.strukto.ai/typescript/agents/dsh), [Grok Build](https://docs.mirage.strukto.ai/typescript/agents/grok-build), [OpenCode](https://docs.mirage.strukto.ai/typescript/agents/opencode), [Pi](https://docs.mirage.strukto.ai/typescript/agents/pi) |
## 캐시
모든 `Workspace`에는 2계층 캐시가 있어, 원격 백엔드에 대한 반복 작업이 네트워크 대신 로컬 상태를 사용합니다:
- **인덱스 캐시:** 디렉터리 목록과 메타데이터. 첫 디렉터리 탐색은 API를 호출하고, 이후에는 TTL이 만료될 때까지(기본 10분) 인덱스에서 제공합니다.
- **파일 캐시:** 객체 바이트. 첫 읽기는 원본에서 스트리밍하고, 이후 파이프라인은 캐시에서 읽습니다(기본 512 MB).
두 계층 모두 기본값은 설정이 필요 없는 프로세스 내 RAM입니다. Redis 스토어를 쓰면 워커, 프로세스, 머신 간에 캐시 상태를 공유합니다:
```ts
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 라이프사이클은 [캐시 문서](https://docs.mirage.strukto.ai/home/cache)를 참고하세요.
## 기여자
Mirage에 기여해 주신 모든 분께 감사드립니다.
<a href="https://github.com/strukto-ai/mirage/graphs/contributors">
<img src="https://contrib.rocks/image?repo=strukto-ai/mirage" alt="Mirage 기여자" />
</a>
Reference in New Issue View Git Blame Copy Permalink