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

# MesaFilesystem

標準の Mastra `WorkspaceFilesystem` インターフェースを介して、Workspace のファイルを [Mesa](https://docs.mesa.dev/content/getting-started/introduction) リポジトリに保存します。

Agent にバージョン管理されたファイルストレージが必要な場合は、`MesaFilesystem` を使用します。ローカルディレクトリには [`LocalFilesystem`](https://mastra.zisheng.pro/ja/reference/workspace/local-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) を使用してください。

> **情報:** `MesaFilesystem` は Mastra プロセス内で動作します。
>
> [Mesa の POSIX マウント](https://docs.mesa.dev/content/mesafs/posix-mount)（Sandbox 内で Mesa Filesystem を使用する機能）は、まだ `@mastra/mesa` パッケージに含まれていません。今後対応予定です。

## インストール

**npm**:

```bash
npm install @mastra/mesa
```

**pnpm**:

```bash
pnpm add @mastra/mesa
```

**Yarn**:

```bash
yarn add @mastra/mesa
```

**Bun**:

```bash
bun add @mastra/mesa
```

## 使用例

1つの Mesa リポジトリをマウントし、Filesystem を Workspace に渡します。

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { MesaFilesystem } from '@mastra/mesa'

const workspace = new Workspace({
  filesystem: new MesaFilesystem({
    apiKey: process.env.MESA_API_KEY,
    org: 'acme',
    repos: [{ name: 'docs', bookmark: 'main' }],
  }),
})

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

`apiKey` を省略すると、`MESA_API_KEY` を使用します。

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

**apiKey** (`string`): Mesa API キー。省略した場合は MESA\_API\_KEY を使用します。

**org** (`string`): Mesa 組織の slug。省略した場合は Mesa SDK がデフォルトの組織を解決します。

**repos** (`RepoConfig[]`): マウントする Mesa リポジトリ。

**cache** (`{ diskCache?: { path: string; maxSizeBytes?: number } }`): Mesa Filesystem のキャッシュ設定。

**ttl** (`number`): Mesa マウントトークンの有効期間（秒）。

**readOnly** (`boolean`): すべてのリポジトリを読み取り専用でマウントするかどうか。 (Default: `false`)

## プロパティ

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

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

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

**readOnly** (`boolean | undefined`): 書き込み操作を禁止するかどうか。

**client** (`Mesa | undefined`): この Provider が作成した Mesa SDK クライアント。初期化前は undefined です。

**filesystem** (`MesaFileSystem`): 有効な Mesa Filesystem。Mesa SDK の未加工の Filesystem が必要な場合、初期化後にアクセスします。

**change** (`MesaFileSystem["change"]`): マウント済み Filesystem の Mesa 変更管理操作。

**bookmark** (`MesaFileSystem["bookmark"]`): マウント済み Filesystem の Mesa ブックマーク管理操作。

## メソッド

`MesaFilesystem` は [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)を実装します。

### ファイル操作

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

Mesa からファイルを読み取ります。

```typescript
const content = await filesystem.readFile('/acme/docs/README.md', {
  encoding: 'utf-8',
})
```

戻り値：`Promise<string | Buffer>`

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

Mesa へファイルを書き込みます。

```typescript
await filesystem.writeFile('/acme/docs/report.md', '# Report')
```

戻り値：`Promise<void>`

#### `appendFile(path, content)`

ファイルへ内容を追記します。

```typescript
await filesystem.appendFile('/acme/docs/log.txt', 'new line\n')
```

戻り値：`Promise<void>`

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

ファイルを削除します。

```typescript
await filesystem.deleteFile('/acme/docs/old-report.md')
```

戻り値：`Promise<void>`

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

ファイルをコピーします。

```typescript
await filesystem.copyFile('/acme/docs/report.md', '/acme/docs/archive/report.md')
```

戻り値：`Promise<void>`

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

ファイルを移動または名前変更します。

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

戻り値：`Promise<void>`

### ディレクトリ操作

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

ディレクトリを作成します。

```typescript
await filesystem.mkdir('/acme/docs/reports', { recursive: true })
```

戻り値：`Promise<void>`

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

ディレクトリを削除します。

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

戻り値：`Promise<void>`

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

ディレクトリのエントリを一覧表示します。

```typescript
const entries = await filesystem.readdir('/acme/docs', {
  recursive: true,
  extension: '.md',
})
```

戻り値：`Promise<FileEntry[]>`

### パス操作

#### `exists(path)`

パスが存在するか確認します。

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

戻り値：`Promise<boolean>`

#### `stat(path)`

ファイルまたはディレクトリのメタデータを返します。

```typescript
const stat = await filesystem.stat('/acme/docs/README.md')
```

戻り値：`Promise<FileStat>`

#### `realpath(path)`

Mesa の正規パスを返します。

```typescript
const realPath = await filesystem.realpath('/acme/docs/README.md')
```

戻り値：`Promise<string>`

### Mesa の操作

#### `bash(options?)`

この Filesystem 用に Mesa ベースの Bash ランタイムを作成します。

```typescript
const bash = await filesystem.bash({
  cwd: '/acme/docs',
})
```

戻り値：`Promise<Bash>`

## パスのセマンティクス

メソッドには絶対パスを指定します。`MesaFilesystem` のパスは Mesa マウントをルートとし、組織 slug とリポジトリ名を含める必要があります。

```typescript
await filesystem.readFile('/acme/docs/README.md')
```

先頭のスラッシュを省略しないでください。

```typescript
await filesystem.readFile('acme/docs/README.md') // Incorrect
await filesystem.readFile('/acme/docs/README.md') // Correct
```

組織はコンストラクターの `org` から取得します。`org` を省略した場合は、Mesa SDK のデフォルト組織の推論結果を使用します。組織は常にパスの最初のセグメントになります。

複数のリポジトリをマウントすると、各リポジトリを組織セグメント配下で利用できます。

```typescript
const filesystem = new MesaFilesystem({
  org: 'acme',
  repos: [
    { name: 'docs', bookmark: 'main' },
    { name: 'website', bookmark: 'main' },
  ],
})

await filesystem.readFile('/acme/docs/README.md')
await filesystem.readFile('/acme/website/package.json')
```

## Mesa のバージョン管理 API

Mesa 固有の変更操作とブックマーク操作には、基盤となる Mesa Filesystem へアクセスします。

```typescript
await filesystem.writeFile('/acme/docs/draft.md', 'Draft')

const current = await filesystem.change.current({
  repo: 'docs',
})

await filesystem.bookmark.move({
  repo: 'docs',
  name: 'main',
  changeId: current.changeId,
})
```

バージョン管理のセマンティクスの詳細は、[Mesa のドキュメント](https://docs.mesa.dev/content/concepts/versioning)を参照してください。

## 読み取り専用モード

Mastra を介した書き込み操作を禁止するには、`readOnly: true` を設定します。

```typescript
const filesystem = new MesaFilesystem({
  repos: [{ name: 'docs', bookmark: 'main' }],
  readOnly: true,
})
```

読み取り操作は引き続き動作します。書き込み操作は `WorkspaceReadOnlyError` をスローします。

## 並行処理

`overwrite: false` と `expectedMtime` は、書き込み前に事前チェックを行います。Mesa がアプリマウント向けのネイティブ条件付き書き込みに対応しない限り、これらのチェックはアトミックではありません。

## 関連項目

- [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)
- [Filesystem ドキュメント](https://mastra.zisheng.pro/ja/docs/workspace/filesystem)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)
- [Mesa ドキュメント](https://docs.mesa.dev/content/getting-started/introduction)