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

# MesaFilesystem

Stocke les fichiers du Workspace dans des dépôts [Mesa](https://docs.mesa.dev/content/getting-started/introduction) au moyen de l’interface Mastra standard `WorkspaceFilesystem`.

Utilisez `MesaFilesystem` lorsque des Agents ont besoin d’un stockage de fichiers versionné. Pour un répertoire local, utilisez [`LocalFilesystem`](https://mastra.zisheng.pro/fr/reference/workspace/local-filesystem). Pour le stockage d’objets, utilisez [`S3Filesystem`](https://mastra.zisheng.pro/fr/reference/workspace/s3-filesystem), [`GCSFilesystem`](https://mastra.zisheng.pro/fr/reference/workspace/gcs-filesystem) ou [`AzureBlobFilesystem`](https://mastra.zisheng.pro/fr/reference/workspace/azure-blob-filesystem).

> **Info:** `MesaFilesystem` s’exécute dans le processus Mastra.
>
> Le [montage POSIX de Mesa](https://docs.mesa.dev/content/mesafs/posix-mount) (permettant d’utiliser un système de fichiers Mesa dans un Sandbox) ne fait pas encore partie du package `@mastra/mesa`. Sa prise en charge sera bientôt disponible.

## Installation

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## Exemple d’utilisation

Montez un dépôt Mesa et transmettez le système de fichiers à un 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,
})
```

Lorsque `apiKey` est omis, `MESA_API_KEY` est utilisée comme valeur de repli.

## Paramètres du constructeur

**apiKey** (`string`): Clé d’API Mesa. Lorsque cette valeur est omise, MESA\_API\_KEY est utilisée comme valeur de repli.

**org** (`string`): Slug de l’organisation Mesa. Lorsqu’il est omis, le SDK Mesa détermine l’organisation par défaut.

**repos** (`RepoConfig[]`): Dépôts Mesa à monter.

**cache** (`{ diskCache?: { path: string; maxSizeBytes?: number } }`): Configuration du cache du système de fichiers Mesa.

**ttl** (`number`): Durée de vie du token de montage Mesa, en secondes.

**readOnly** (`boolean`): Monte tous les dépôts en lecture seule. (Default: `false`)

## Propriétés

**id** (`string`): Identifiant de l’instance du système de fichiers.

**name** (`string`): Nom du Provider ('MesaFilesystem').

**provider** (`string`): Identifiant du Provider ('mesa').

**readOnly** (`boolean | undefined`): Indique si les opérations d’écriture sont bloquées.

**client** (`Mesa | undefined`): Client du SDK Mesa créé par ce Provider. Non défini avant l’initialisation.

**filesystem** (`MesaFileSystem`): Système de fichiers Mesa actif. Accédez-y après l’initialisation lorsque vous avez besoin du système de fichiers brut du SDK Mesa.

**change** (`MesaFileSystem["change"]`): Opérations Mesa de gestion des changements pour le système de fichiers monté.

**bookmark** (`MesaFileSystem["bookmark"]`): Opérations Mesa de gestion des signets pour le système de fichiers monté.

## Méthodes

`MesaFilesystem` implémente l’[interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem).

### Opérations sur les fichiers

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

Lit un fichier depuis Mesa.

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

Renvoie : `Promise<string | Buffer>`

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

Écrit un fichier dans Mesa.

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

Renvoie : `Promise<void>`

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

Ajoute du contenu à la fin d’un fichier.

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

Renvoie : `Promise<void>`

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

Supprime un fichier.

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

Renvoie : `Promise<void>`

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

Copie un fichier.

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

Renvoie : `Promise<void>`

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

Déplace ou renomme un fichier.

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

Renvoie : `Promise<void>`

### Opérations sur les répertoires

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

Crée un répertoire.

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

Renvoie : `Promise<void>`

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

Supprime un répertoire.

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

Renvoie : `Promise<void>`

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

Répertorie les entrées d’un répertoire.

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

Renvoie : `Promise<FileEntry[]>`

### Opérations sur les chemins

#### `exists(path)`

Vérifie si un chemin existe.

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

Renvoie : `Promise<boolean>`

#### `stat(path)`

Renvoie les métadonnées d’un fichier ou d’un répertoire.

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

Renvoie : `Promise<FileStat>`

#### `realpath(path)`

Renvoie le chemin canonique fourni par Mesa.

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

Renvoie : `Promise<string>`

### Opérations Mesa

#### `bash(options?)`

Crée un environnement d’exécution Bash reposant sur Mesa pour ce système de fichiers.

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

Renvoie : `Promise<Bash>`

## Sémantique des chemins

Les méthodes attendent des chemins absolus. Pour `MesaFilesystem`, les chemins ont pour racine le montage Mesa et doivent inclure le slug de l’organisation ainsi que le nom du dépôt :

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

N’omettez pas la barre oblique initiale :

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

L’organisation provient de `org` dans le constructeur ou, lorsque `org` est omis, de l’inférence de l’organisation par défaut du SDK Mesa. Elle reste le premier segment du chemin.

Lorsque vous montez plusieurs dépôts, chacun d’eux est disponible sous le segment de l’organisation :

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

## API de versionnement Mesa

Accédez au système de fichiers Mesa sous-jacent pour effectuer les opérations de changement et de signet propres à Mesa :

```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,
})
```

Pour en savoir plus sur la sémantique du versionnement, consultez la [documentation de Mesa](https://docs.mesa.dev/content/concepts/versioning).

## Mode lecture seule

Définissez `readOnly: true` pour bloquer les opérations d’écriture via Mastra :

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

Les opérations de lecture continuent de fonctionner. Les opérations d’écriture déclenchent `WorkspaceReadOnlyError`.

## Accès concurrent

`overwrite: false` et `expectedMtime` utilisent des vérifications préalables avant l’écriture. Ces vérifications ne sont pas atomiques, sauf si Mesa ajoute des écritures conditionnelles natives pour les montages d’application.

## Ressources associées

- [Interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem)
- [Documentation du système de fichiers](https://mastra.zisheng.pro/fr/docs/workspace/filesystem)
- [Vue d’ensemble du Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)
- [Documentation Mesa](https://docs.mesa.dev/content/getting-started/introduction)