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

# 작업 공간파일 시스템

**추가된 항목:** `@mastra/core@1.1.0`

`WorkspaceFilesystem` 인터페이스는 Workspace가 파일 스토리지와 상호 작용하는 방식을 정의합니다.

## 행동 양식

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

파일 내용을 읽습니다.

```typescript
const content = await filesystem.readFile('/docs/guide.md')
const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })
```

**매개변수:**

**path** (`string`): basePath에 상대적인 파일 경로

**options** (`Options`): readFile 옵션입니다.

**options.encoding** (`'utf-8' | 'binary'`): 텍스트 또는 바이너리 인코딩

**보고:** `Promise<string | Buffer>`

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

파일 내용을 작성합니다.

```typescript
await filesystem.writeFile('/docs/new.md', '# New Document')
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
```

**매개변수:**

**path** (`string`): basePath에 상대적인 파일 경로

**content** (`string | Buffer`): 파일 내용

**options** (`Options`): 구성 옵션입니다.

**options.recursive** (`boolean`): 상위 디렉터리가 없으면 생성합니다

**options.overwrite** (`boolean`): 기존 파일을 덮어씁니다

**options.expectedMtime** (`Date`): 이 값을 제공하면 파일의 현재 수정 시간이 일치하지 않을 때 StaleFileError와 함께 쓰기가 실패합니다. 읽기와 쓰기 사이에 발생한 외부 수정을 감지하는 낙관적 동시성 제어에 사용합니다.

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

파일을 삭제합니다.

```typescript
await filesystem.deleteFile('/docs/old.md')
await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing
```

**매개변수:**

**path** (`string`): 파일 경로

**options** (`Options`): 구성 옵션입니다.

**options.force** (`boolean`): 파일이 없어도 오류를 발생시키지 않습니다

### `appendFile(path, content)`

콘텐츠를 파일에 추가하고 콘텐츠가 아직 없으면 콘텐츠를 만듭니다. 상위 디렉터리가 자동으로 생성됩니다.

```typescript
await filesystem.appendFile('/logs/app.log', 'New log entry\n')
```

**매개변수:**

**path** (`string`): 파일 경로

**content** (`string | Buffer`): 추가할 내용

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

파일을 새 위치에 복사합니다.

```typescript
await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
```

**매개변수:**

**src** (`string`): 소스 파일 경로

**dest** (`string`): 대상 파일 경로

**options** (`Options`): 구성 옵션입니다.

**options.overwrite** (`boolean`): 대상이 있으면 덮어씁니다

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

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

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

**매개변수:**

**src** (`string`): 소스 파일 경로

**dest** (`string`): 대상 파일 경로

**options** (`Options`): 구성 옵션입니다.

**options.overwrite** (`boolean`): 대상이 존재하면 덮어쓰기

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

디렉터리 내용을 나열합니다.

```typescript
const entries = await filesystem.readdir('/docs')
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
```

**보고:** `Promise<FileEntry[]>`

```typescript
interface FileEntry {
  name: string
  type: 'file' | 'directory'
  size?: number
  isSymlink?: boolean
  symlinkTarget?: string
}
```

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

디렉터리를 만듭니다.

```typescript
await filesystem.mkdir('/docs/api')
await filesystem.mkdir('/deeply/nested/path', { recursive: true })
```

**매개변수:**

**path** (`string`): 디렉터리 경로

**options** (`Options`): 구성 옵션입니다.

**options.recursive** (`boolean`): 상위 디렉터리 생성

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

디렉터리를 제거합니다.

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

**매개변수:**

**path** (`string`): 디렉터리 경로

**options** (`Options`): 구성 옵션입니다.

**options.recursive** (`boolean`): 콘텐츠를 재귀적으로 제거

**options.force** (`boolean`): 디렉터리가 없어도 예외를 발생시키지 않음

### `exists(path)`

경로가 존재하는지 확인하십시오.

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

**보고:** `Promise<boolean>`

### `stat(path)`

파일 또는 디렉터리 메타데이터를 가져옵니다.

```typescript
const stat = await filesystem.stat('/docs/guide.md')
// { name: 'guide.md', path: '/docs/guide.md', type: 'file', size: 1234, createdAt: Date, modifiedAt: Date }
```

**보고:** `Promise<FileStat>`

```typescript
interface FileStat {
  name: string // File or directory name (basename only)
  path: string // Path relative to the filesystem basePath
  type: 'file' | 'directory'
  size: number
  createdAt: Date
  modifiedAt: Date
  mimeType?: string
}
```

## 선택적 방법

### `init()`

파일 시스템을 초기화합니다. 호출자`workspace.init()`.

```typescript
await filesystem.init?.()
```

### `destroy()`

리소스를 정리합니다. 호출자`workspace.destroy()`.

```typescript
await filesystem.destroy?.()
```

### `getInfo()`

파일 시스템 메타데이터를 가져옵니다.

```typescript
const info = await filesystem.getInfo?.()
// { id, name, provider, basePath, readOnly, status, storage? }
```

**보고:** `Promise<FilesystemInfo>`

```typescript
interface FilesystemInfo {
  id: string
  name: string
  provider: string
  basePath?: string
  readOnly?: boolean
  status?: string
  storage?: {
    totalBytes?: number
    usedBytes?: number
    availableBytes?: number
  }
}
```

### `getInstructions(opts?)`

이 파일 시스템이 작동하는 방식에 대한 설명을 반환합니다. 작업 영역이 Agent에 할당될 때 Agent의 시스템 메시지에 삽입됩니다.

```typescript
const instructions = filesystem.getInstructions?.()
// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
```

**매개변수:**

**opts.requestContext** (`RequestContext`): 생성자에 instructions 함수가 제공된 경우 해당 함수로 전달됩니다.

**보고:** `string`

## 관련된

- [작업공간 클래스](https://mastra.zisheng.pro/ko/reference/workspace/workspace-class)
- [샌드박스 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/sandbox)