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

# PlatformFilesystem

Mastra Platform の Workspace バケットにファイルを保存します。各 Mastra Platform 環境は1つのバケットを持つことができ、`PlatformFilesystem` はそのバケットに対する `read`、`write`、`list`、`delete`、`move` 操作を Agent に提供します。

関連 Provider：S3 への直接アクセスには [`S3Filesystem`](https://mastra.zisheng.pro/ja/reference/workspace/s3-filesystem)、ローカルディレクトリには [`LocalFilesystem`](https://mastra.zisheng.pro/ja/reference/workspace/local-filesystem) を使用します。

> **情報:** インターフェースの詳細は、[WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/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
```

Platform の認証情報を設定します。アクセストークン、プロジェクト ID、バケット名は環境変数を使用できるため、Mastra Platform へのデプロイではコンストラクターオプションを省略できます。

**.env ファイル**:

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

**コンストラクター**:

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

Mastra Platform へのデプロイでは、`MASTRA_PLATFORM_ACCESS_TOKEN`、`MASTRA_PROJECT_ID`、`MASTRA_PLATFORM_BUCKET_NAME` が自動挿入されるため、オプションなしでコンストラクターを呼び出せます。ローカル開発では、組織の設定ページにある **API Tokens** で取得した `sk_` API トークンを `MASTRA_PLATFORM_ACCESS_TOKEN` に設定できます。

## 使用方法

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` は読み取り、変更、書き込みを行う操作であり、アトミックではありません。同じパスへの同時追記は互いに上書きする可能性があります。複数の Writer が同時に処理する場合は、異なるキーで `writeFile` を使用してください。

## コンストラクターパラメーター

**accessToken** (`string`): Platform のアクセストークン。未指定の場合は環境変数 MASTRA\_PLATFORM\_ACCESS\_TOKEN を使用します。

**projectId** (`string`): Platform のプロジェクト ID。未指定の場合は環境変数 MASTRA\_PROJECT\_ID を使用します。

**bucketName** (`string`): ファイルを保存する Platform バケット名。未指定の場合は環境変数 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`): この Filesystem インスタンスの一意な識別子。 (Default: `Auto-generated`)

**fetch** (`typeof fetch`): カスタム fetch 実装。主にテストで使用します。

## プロパティ

**id** (`string`): Filesystem インスタンスの識別子。

**name** (`string`): Provider 名（'PlatformFilesystem'）。

**provider** (`string`): Provider 識別子（'platform'）。

**readOnly** (`boolean | undefined`): Filesystem が読み取り専用でマウントされたかどうか。

## エラー

Filesystem 固有のエラーは、Workspace の標準エラー型に対応します。

- `FileNotFoundError`：パスが存在しません。`readFile`、`stat`、`deleteFile` からスローされます（`force: true` を設定した場合を除く）。
- `FileExistsError`：`overwrite: false` で `writeFile` を呼び出し、コピー先がすでに存在します。
- `WorkspaceReadOnlyError`：読み取り専用の Filesystem で変更を伴う呼び出しが行われました。

その他の Platform 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` です。

## 関連項目

- [PlatformSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/platform-sandbox)
- [S3Filesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/s3-filesystem)
- [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)