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

# WorkspaceFilesystem

**追加バージョン：** `@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()`

Filesystem を初期化します。`workspace.init()` から呼び出されます。

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

### `destroy()`

リソースを解放します。`workspace.destroy()` から呼び出されます。

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

### `getInfo()`

Filesystem のメタデータを取得します。

```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?)`

この Filesystem の動作を説明するテキストを返します。Workspace が 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`

## 関連項目

- [Workspace クラス](https://mastra.zisheng.pro/ja/reference/workspace/workspace-class)
- [Sandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)