> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 메사파일 시스템

작업공간 파일을 다음 위치에 저장합니다.[Mesa](https://docs.mesa.dev/content/getting-started/introduction)표준 Mastra를 통한 저장소`WorkspaceFilesystem`인터페이스.

Agent에 버전 관리 파일 스토리지가 필요할 때 `MesaFilesystem`을 사용합니다. 로컬 디렉터리에는 [`LocalFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/local-filesystem)을 사용합니다. 객체 스토리지에는 [`S3Filesystem`](https://mastra.zisheng.pro/ko/reference/workspace/s3-filesystem), [`GCSFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/gcs-filesystem) 또는 [`AzureBlobFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/azure-blob-filesystem)을 사용합니다.

> **정보:** `MesaFilesystem`Mastra 프로세스에서 실행됩니다.
>
> [Mesa의 POSIX 마운트](https://docs.mesa.dev/content/mesafs/posix-mount)(Sandbox 내에서 Mesa 파일 시스템을 사용하기 위한 기능)는 아직 `@mastra/mesa` 패키지에 포함되어 있지 않습니다. 곧 지원될 예정입니다.

## 설치

**npm**:

```bash
npm install @mastra/mesa
```

**pnpm**:

```bash
pnpm add @mastra/mesa
```

**Yarn**:

```bash
yarn add @mastra/mesa
```

**Bun**:

```bash
bun add @mastra/mesa
```

## 사용예

Mesa 저장소 하나를 마운트하고 파일 시스템을 작업 공간에 전달합니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { MesaFilesystem } from '@mastra/mesa'

const workspace = new Workspace({
  filesystem: new MesaFilesystem({
    apiKey: process.env.MESA_API_KEY,
    org: 'acme',
    repos: [{ name: 'docs', bookmark: 'main' }],
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

`apiKey`를 생략하면 `MESA_API_KEY`를 대신 사용합니다.

## 생성자 매개변수

**apiKey** (`string`): Mesa API 키입니다. 생략하면 MESA\_API\_KEY를 대신 사용합니다.

**org** (`string`): Mesa 조직 슬러그입니다. 생략하면 Mesa SDK가 기본 조직을 확인합니다.

**repos** (`RepoConfig[]`): 마운트할 Mesa 저장소입니다.

**cache** (`{ diskCache?: { path: string; maxSizeBytes?: number } }`): Mesa 파일 시스템 캐시 구성입니다.

**ttl** (`number`): Mesa 마운트 토큰의 수명(초)입니다.

**readOnly** (`boolean`): 모든 저장소를 읽기 전용으로 마운트합니다. (Default: `false`)

## 속성

**id** (`string`): 파일 시스템 인스턴스 식별자입니다.

**name** (`string`): Provider 이름('MesaFilesystem')입니다.

**provider** (`string`): Provider 식별자('mesa')입니다.

**readOnly** (`boolean | undefined`): 쓰기 작업이 차단되는지 여부입니다.

**client** (`Mesa | undefined`): 이 Provider가 생성한 Mesa SDK 클라이언트입니다. 초기화 전에는 undefined입니다.

**filesystem** (`MesaFileSystem`): 활성 Mesa 파일 시스템입니다. 원시 Mesa SDK 파일 시스템이 필요할 때 초기화 후 이 속성에 액세스합니다.

**change** (`MesaFileSystem["change"]`): 마운트된 파일 시스템의 Mesa 변경 관리 작업입니다.

**bookmark** (`MesaFileSystem["bookmark"]`): 마운트된 파일 시스템의 Mesa 북마크 관리 작업입니다.

## 행동 양식

`MesaFilesystem`구현[WorkspaceFilesystem interface](https://mastra.zisheng.pro/ko/reference/workspace/filesystem).

### 파일 작업

#### `readFile(path, options?)`

메사에서 파일을 읽습니다.

```typescript
const content = await filesystem.readFile('/acme/docs/README.md', {
  encoding: 'utf-8',
})
```

보고:`Promise<string | Buffer>`

#### `writeFile(path, content, options?)`

메사에 파일을 씁니다.

```typescript
await filesystem.writeFile('/acme/docs/report.md', '# Report')
```

보고:`Promise<void>`

#### `appendFile(path, content)`

파일에 콘텐츠를 추가합니다.

```typescript
await filesystem.appendFile('/acme/docs/log.txt', 'new line\n')
```

보고:`Promise<void>`

#### `deleteFile(path, options?)`

파일을 삭제합니다.

```typescript
await filesystem.deleteFile('/acme/docs/old-report.md')
```

보고:`Promise<void>`

#### `copyFile(src, dest, options?)`

파일을 복사합니다.

```typescript
await filesystem.copyFile('/acme/docs/report.md', '/acme/docs/archive/report.md')
```

보고:`Promise<void>`

#### `moveFile(src, dest, options?)`

파일을 이동하거나 이름을 바꿉니다.

```typescript
await filesystem.moveFile('/acme/docs/draft.md', '/acme/docs/final.md')
```

보고:`Promise<void>`

### 디렉토리 작업

#### `mkdir(path, options?)`

디렉터리를 생성합니다.

```typescript
await filesystem.mkdir('/acme/docs/reports', { recursive: true })
```

보고:`Promise<void>`

#### `rmdir(path, options?)`

디렉터리를 제거합니다.

```typescript
await filesystem.rmdir('/acme/docs/reports', { recursive: true })
```

보고:`Promise<void>`

#### `readdir(path, options?)`

디렉토리 항목을 나열합니다.

```typescript
const entries = await filesystem.readdir('/acme/docs', {
  recursive: true,
  extension: '.md',
})
```

보고:`Promise<FileEntry[]>`

### 경로 작업

#### `exists(path)`

경로가 존재하는지 확인합니다.

```typescript
const exists = await filesystem.exists('/acme/docs/README.md')
```

보고:`Promise<boolean>`

#### `stat(path)`

파일 또는 디렉터리 메타데이터를 반환합니다.

```typescript
const stat = await filesystem.stat('/acme/docs/README.md')
```

보고:`Promise<FileStat>`

#### `realpath(path)`

메사로부터 표준 경로를 반환합니다.

```typescript
const realPath = await filesystem.realpath('/acme/docs/README.md')
```

보고:`Promise<string>`

### 메사 운영

#### `bash(options?)`

이 파일 시스템에 대해 Mesa 기반 Bash 런타임을 생성합니다.

```typescript
const bash = await filesystem.bash({
  cwd: '/acme/docs',
})
```

보고:`Promise<Bash>`

## 경로 의미론

메서드에는 절대 경로가 필요합니다. `MesaFilesystem`에서 경로의 루트는 Mesa 마운트이며 조직 슬러그와 저장소 이름을 포함해야 합니다:

```typescript
await filesystem.readFile('/acme/docs/README.md')
```

선행 슬래시를 생략하지 마십시오.

```typescript
await filesystem.readFile('acme/docs/README.md') // Incorrect
await filesystem.readFile('/acme/docs/README.md') // Correct
```

조직은 생성자의 `org`에서 가져오며, `org`를 생략하면 Mesa SDK의 기본 조직 추론을 통해 가져옵니다. 조직은 항상 첫 번째 경로 세그먼트입니다. 여러 저장소를 마운트하면 각 저장소를 조직 세그먼트에서 사용할 수 있습니다.

```typescript
const filesystem = new MesaFilesystem({
  org: 'acme',
  repos: [
    { name: 'docs', bookmark: 'main' },
    { name: 'website', bookmark: 'main' },
  ],
})

await filesystem.readFile('/acme/docs/README.md')
await filesystem.readFile('/acme/website/package.json')
```

## 메사 버전 관리 API

Mesa 관련 변경 및 북마크 작업을 위해 기본 Mesa 파일 시스템에 액세스합니다.

```typescript
await filesystem.writeFile('/acme/docs/draft.md', 'Draft')

const current = await filesystem.change.current({
  repo: 'docs',
})

await filesystem.bookmark.move({
  repo: 'docs',
  name: 'main',
  changeId: current.changeId,
})
```

버전 관리 의미에 대한 자세한 내용은 다음에서 확인할 수 있습니다.[Mesa's docs](https://docs.mesa.dev/content/concepts/versioning).

## 읽기 전용 모드

Mastra를 통한 쓰기 작업을 차단하려면 `readOnly: true`를 설정합니다:

```typescript
const filesystem = new MesaFilesystem({
  repos: [{ name: 'docs', bookmark: 'main' }],
  readOnly: true,
})
```

읽기 작업은 계속 작동합니다. 쓰기 작업 던지기`WorkspaceReadOnlyError`.

## 동시성

`overwrite: false`와 `expectedMtime`은 쓰기 전에 사전 검사를 사용합니다. Mesa가 앱 마운트에 네이티브 조건부 쓰기를 추가하지 않는 한 이러한 검사는 원자적이지 않습니다.

## 관련된

- [WorkspaceFilesystem 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/filesystem)
- [파일 시스템 문서](https://mastra.zisheng.pro/ko/docs/workspace/filesystem)
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)
- [메사 문서](https://docs.mesa.dev/content/getting-started/introduction)