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

# 플랫폼파일 시스템

Mastra Platform 작업 공간 버킷에 파일을 저장합니다. 각 Mastra 플랫폼 환경은 하나의 버킷을 가질 수 있으며,`PlatformFilesystem`Agent를 제공합니다`read`, `write`, `list`, `delete`, 그리고`move`이에 대한 작전.

관련 Provider: S3에 직접 액세스하려면 [`S3Filesystem`](https://mastra.zisheng.pro/ko/reference/workspace/s3-filesystem), 로컬 디렉터리에는 [`LocalFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/local-filesystem)을 사용합니다.

> **정보:** 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[WorkspaceFilesystem interface](https://mastra.zisheng.pro/ko/reference/workspace/filesystem).

## 설치

**npm**:

```bash
npm install @mastra/platform-workspace
```

**pnpm**:

```bash
pnpm add @mastra/platform-workspace
```

**Yarn**:

```bash
yarn add @mastra/platform-workspace
```

**Bun**:

```bash
bun add @mastra/platform-workspace
```

플랫폼 자격 증명을 구성합니다. 액세스 토큰, 프로젝트 ID 및 버킷 이름은 환경 변수로 대체되므로 Mastra 플랫폼 배포는 생성자 옵션을 0으로 전달할 수 있습니다.

**.env file**:

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
```

**Constructor**:

```typescript
new PlatformFilesystem({
  accessToken: 'your-platform-access-token',
  projectId: 'your-project-id',
  bucketName: 'your-bucket-name',
})
```

Mastra 플랫폼 배포에서는 `MASTRA_PLATFORM_ACCESS_TOKEN`, `MASTRA_PROJECT_ID`, `MASTRA_PLATFORM_BUCKET_NAME`이 자동으로 주입되므로 옵션 없이 생성자를 호출할 수 있습니다. 로컬 개발에서는 `MASTRA_PLATFORM_ACCESS_TOKEN`에 조직 설정 페이지의 **API Tokens**에서 가져온 `sk_` API 토큰을 사용할 수 있습니다.

## 용법

Workspace에 `PlatformFilesystem`을 추가하고 Agent에 할당합니다:

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem } from '@mastra/platform-workspace'

const workspace = new Workspace({
  filesystem: new PlatformFilesystem({
    // accessToken, projectId, bucketName all fall back to env vars
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'File Agent',
  instructions: 'You are a research assistant that reads and writes reports.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})
```

### 파일 읽기 및 쓰기

객체 키는 세그먼트별로 퍼센트 인코딩되므로 파일 이름의 `?`, `#`, `%`, `&`, `+` 또는 공백이 전체 과정에서 보존됩니다:

```typescript
const fs = new PlatformFilesystem()

await fs.writeFile('/analyses/repo.md', markdown)
const content = await fs.readFile('/analyses/repo.md')
const entries = await fs.readdir('/analyses')
await fs.moveFile('/analyses/repo.md', '/analyses/repo-final.md')
```

### 읽기 전용 모드

버킷을 읽기 전용으로 마운트하려면 `readOnly: true`를 전달합니다. 변경 작업을 수행하는 모든 호출은 `WorkspaceReadOnlyError`를 발생시킵니다:

```typescript
const fs = new PlatformFilesystem({ readOnly: true })

await fs.readFile('/analyses/repo.md') // ok
await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError
```

### 의미론 덮어쓰기

`writeFile`은 `overwrite: false`를 지원하며 대상이 이미 존재하면 `FileExistsError`를 발생시킵니다. `copyFile`과 `moveFile`은 항상 대상을 덮어씁니다. 두 메서드 중 하나에 `overwrite: false`를 전달하면 조용히 덮어쓰는 대신 오류가 발생합니다.

### 파일 추가

`appendFile`은 읽기-수정-쓰기 방식이며 원자적이지 않습니다. 동일한 경로에 동시에 추가하면 서로 덮어쓸 수 있습니다. 동시 작성자가 있다면 서로 다른 키와 함께 `writeFile`을 사용하세요.

## 생성자 매개변수

**accessToken** (`string`): 플랫폼 액세스 토큰입니다. MASTRA\_PLATFORM\_ACCESS\_TOKEN 환경 변수를 대신 사용할 수 있습니다.

**projectId** (`string`): 플랫폼 프로젝트 ID입니다. MASTRA\_PROJECT\_ID 환경 변수를 대신 사용할 수 있습니다.

**bucketName** (`string`): 파일을 저장할 플랫폼 버킷 이름입니다. MASTRA\_PLATFORM\_BUCKET\_NAME 환경 변수를 대신 사용할 수 있습니다.

**readOnly** (`boolean`): true이면 변경 작업을 수행하는 모든 호출이 WorkspaceReadOnlyError를 발생시킵니다. (Default: `false`)

**displayName** (`string`): Workspace UI에 표시되는 사람이 읽기 쉬운 이름입니다.

**description** (`string`): Workspace UI에 표시되는 간단한 설명입니다.

**icon** (`FilesystemIcon`): Workspace UI에 표시되는 아이콘입니다.

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): getInstructions()에서 반환되는 사용자 지정 지침입니다. 문자열은 기본값을 완전히 대체하며, 함수는 기본값을 전달받아 요청별로 확장하거나 사용자 지정할 수 있습니다.

**id** (`string`): 이 파일 시스템 인스턴스의 고유 식별자입니다. (Default: `자동 생성`)

**fetch** (`typeof fetch`): 주로 테스트에 사용하는 사용자 지정 fetch 구현입니다.

## 속성

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

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

**provider** (`string`): Provider 식별자('platform').

**readOnly** (`boolean | undefined`): 파일 시스템이 읽기 전용으로 마운트되었는지 여부입니다.

## 오류

파일 시스템 관련 오류는 표준 작업 공간 오류 유형과 일치합니다.

- `FileNotFoundError`: 경로가 존재하지 않습니다. `readFile`, `stat`, `deleteFile`에서 발생합니다(`force: true`가 설정된 경우 제외).
- `FileExistsError`: 대상이 이미 존재하는 상태에서 `overwrite: false`로 `writeFile`을 호출했습니다.
- `WorkspaceReadOnlyError`: 읽기 전용 파일 시스템에서 변경 작업을 호출했습니다. 그 밖의 플랫폼 API 오류는 `PlatformApiError`를 발생시킵니다. 구조화된 `{ error: { message, type } }` 응답은 `.code`(머신 판독 가능한 유형)와 `.proxyMessage`(사람이 읽을 수 있는 문자열)로 파싱됩니다.

```typescript
import { FileNotFoundError } from '@mastra/core/workspace'
import { PlatformApiError } from '@mastra/platform-workspace'

try {
  await fs.readFile('/missing.txt')
} catch (err) {
  if (err instanceof FileNotFoundError) {
    // handle missing file
  } else if (err instanceof PlatformApiError) {
    if (err.code === 'authentication_error') {
      // refresh token
    }
    console.error(err.status, err.code, err.proxyMessage)
  }
}
```

`FileNotFoundError`, `FileExistsError`, `WorkspaceReadOnlyError`는 `@mastra/core/workspace`의 표준 Workspace 오류 유형을 다시 내보낸 것입니다. `PlatformApiError`는 `@mastra/platform-workspace` 전용입니다. 응답 본문이 JSON이 아닌 경우(예: 로드 밸런서가 반환한 HTML 502) `code`와 `proxyMessage`는 `undefined`입니다.

## 관련된

- [플랫폼샌드박스 참조](https://mastra.zisheng.pro/ko/reference/workspace/platform-sandbox)
- [S3파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/s3-filesystem)
- [WorkspaceFilesystem 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/filesystem)