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

# FilesSDKFilesystem

[FilesSDK](https://files-sdk.dev) が対応する任意のストレージバックエンドにファイルを保存します。FilesSDK は S3、Cloudflare R2、Google Cloud Storage、Azure Blob、Vercel Blob、MinIO、ローカル Filesystem などを統一的に抽象化します。インターフェースの詳細は、[WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)を参照してください。

同じコードで複数のストレージバックエンドを扱う単一のアダプターが必要な場合は、`FilesSDKFilesystem` を使用します。Workspace の設定を変えずに、基盤となるドライバーを切り替えられます。対象が1つのバックエンドのみで、そのバックエンド専用のオプションが必要な場合は、専用 Provider（[`S3Filesystem`](https://mastra.zisheng.pro/ja/reference/workspace/s3-filesystem) や [`GCSFilesystem`](https://mastra.zisheng.pro/ja/reference/workspace/gcs-filesystem) など）を推奨します。

## インストール

**npm**:

```bash
npm install @mastra/files-sdk files-sdk
```

**pnpm**:

```bash
pnpm add @mastra/files-sdk files-sdk
```

**Yarn**:

```bash
yarn add @mastra/files-sdk files-sdk
```

**Bun**:

```bash
bun add @mastra/files-sdk files-sdk
```

`files-sdk` は peer dependency であり、使用するアダプターとともに設定します。

## 使用方法

任意のアダプターを指定して FilesSDK の `Files` インスタンスを作成し、`FilesSDKFilesystem` へ渡します。

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { FilesSDKFilesystem } from '@mastra/files-sdk'
import { Files } from 'files-sdk'
import { s3 } from 'files-sdk/s3'

const files = new Files({
  adapter: s3({
    bucket: 'my-bucket',
    region: 'us-east-1',
  }),
})

const workspace = new Workspace({
  filesystem: new FilesSDKFilesystem({ files }),
})

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

### アダプターを切り替える

同じ `FilesSDKFilesystem` を任意の FilesSDK アダプターで使用できます。バックエンドを切り替えるには、ドライバーファクトリーを置き換えます。

```typescript
import { Files } from 'files-sdk'
import { r2 } from 'files-sdk/r2'
import { gcs } from 'files-sdk/gcs'
import { azure } from 'files-sdk/azure'
import { fs } from 'files-sdk/fs'

// Cloudflare R2
const r2Files = new Files({ adapter: r2({ accountId, bucket, accessKeyId, secretAccessKey }) })

// Google Cloud Storage
const gcsFiles = new Files({ adapter: gcs({ bucket, projectId }) })

// Azure Blob
const azureFiles = new Files({ adapter: azure({ container, connectionString }) })

// Local filesystem (useful for tests and development)
const localFiles = new Files({ adapter: fs({ root: './workspace' }) })
```

アダプターの完全なカタログと設定オプションは、[FilesSDK ドキュメント](https://files-sdk.dev)を参照してください。

### 読み取り専用マウント

```typescript
const filesystem = new FilesSDKFilesystem({
  files,
  readOnly: true,
})
```

すべての書き込み操作（`writeFile`、`appendFile`、`deleteFile`、`copyFile`、`moveFile`、`mkdir`、`rmdir`）は `WorkspaceReadOnlyError` をスローし、読み取り操作は成功します。

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

**files** (`Files`): 使用するアダプターと認証情報に紐付けて事前設定した FilesSDK の Files インスタンス。

**id** (`string`): この Filesystem インスタンスの一意な識別子。 (Default: `Auto-generated`)

**displayName** (`string`): UI に表示するわかりやすい名前。

**icon** (`FilesystemIcon`): UI に表示するアイコンの識別子。

**description** (`string`): UI に表示する Filesystem の短い説明。

**readOnly** (`boolean`): true の場合、すべての書き込み操作を禁止します。 (Default: `false`)

## プロパティ

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

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

**provider** (`string`): Provider 識別子（'files-sdk'）。

**readOnly** (`boolean | undefined`): Filesystem が読み取り専用モードかどうか。

## メソッド

`FilesSDKFilesystem` は [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)を実装し、標準の Filesystem メソッドをすべて提供します。

- `readFile(path, options?)` - ファイルの内容を読み取ります
- `writeFile(path, content, options?)` - ファイルに内容を書き込みます
- `appendFile(path, content)` - ファイルに内容を追記します
- `deleteFile(path, options?)` - ファイルを削除します
- `copyFile(src, dest, options?)` - ファイルをコピーします
- `moveFile(src, dest, options?)` - ファイルを移動または名前変更します
- `mkdir(path, options?)` - ディレクトリを作成（オブジェクトストアでは何もしません）
- `rmdir(path, options?)` - ディレクトリを削除します
- `readdir(path, options?)` - ディレクトリの内容を一覧表示します
- `exists(path)` - パスが存在するか確認します
- `stat(path)` - ファイルまたはディレクトリのメタデータを取得します

### `init()`

Filesystem を初期化します。指定された認証情報で、設定済みアダプターがキーを一覧表示できることを確認します。

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

### `getInfo()`

この Filesystem インスタンスのメタデータを返します。

```typescript
const info = filesystem.getInfo()
// { id: '...', name: 'FilesSDKFilesystem', provider: 'files-sdk', status: 'ready' }
```

### `files`

アダプター固有の API を直接呼び出せるよう、基盤となる FilesSDK の `Files` インスタンスが public プロパティとして公開されます。

```typescript
const url = await filesystem.files.url('reports/q3.pdf')
```

## オブジェクトストアのセマンティクス

`FilesSDKFilesystem` は、基盤となるアダプターが階層型（`fs` など）でも、設定されたバックエンドをオブジェクトストアとして扱います。これにより、アダプター間で動作が統一されます。

- **`mkdir`** は何もしません。その接頭辞を持つキーが存在すると、ディレクトリも暗黙的に存在します。
- **`exists`** が `true` を返すのは、完全一致するキーがファイルとして存在する場合、またはパスが1つ以上の子キーを含む接頭辞である場合だけです。階層型アダプターに残った空のディレクトリは対象外です。
- **`deleteFile`** は、`{ force: true }` を渡さない限り、キーが存在しない場合に `FileNotFoundError` をスローします。
- ディレクトリに対する **`deleteFile`** は、[`S3Filesystem`](https://mastra.zisheng.pro/ja/reference/workspace/s3-filesystem) および [`GCSFilesystem`](https://mastra.zisheng.pro/ja/reference/workspace/gcs-filesystem) と同様に、`rmdir({ recursive: true })` へ処理を委譲します。
- **`moveFile`** は `copyFile` の後に `deleteFile` を実行する形で実装されており、**アトミックではありません**。コピーの成功後にコピー元の削除が失敗すると、コピー先は残り、コピー元も削除されません。
- **`appendFile`** は読み取り、変更、書き込みを行う操作です。同じキーへの同時追記は互いに上書きする可能性があります。これはオブジェクトストレージ固有の性質であり、FilesSDK に限ったものではありません。
- **`readdir({ recursive: true })`** は中間ディレクトリのエントリも返します（たとえば、`a/b/c.txt` とともに `a/b` も返します）。

## 関連項目

- [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)
- [S3Filesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/s3-filesystem)
- [GCSFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/gcs-filesystem)
- [AzureBlobFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/azure-blob-filesystem)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)
- [FilesSDK ドキュメント](https://files-sdk.dev)