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

# PlatformFilesystem

Stocke des fichiers dans le bucket d'un Workspace Mastra Platform. Chaque environnement Mastra Platform peut posséder un bucket, et `PlatformFilesystem` fournit aux Agents les opérations `read`, `write`, `list`, `delete` et `move` sur celui-ci.

Providers associés : [`S3Filesystem`](https://mastra.zisheng.pro/fr/reference/workspace/s3-filesystem) pour un accès direct à S3, [`LocalFilesystem`](https://mastra.zisheng.pro/fr/reference/workspace/local-filesystem) pour les répertoires locaux.

> **Info:** Pour en savoir plus sur l'interface, consultez [l'interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem).

## Installation

**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
```

Configurez les identifiants de la plateforme. Le token d'accès, l'identifiant du projet et le nom du bucket utilisent par défaut des variables d'environnement. Un déploiement Mastra Platform peut donc n'utiliser aucune option du constructeur.

**Fichier .env**:

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

**Constructeur**:

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

Dans un déploiement Mastra Platform, `MASTRA_PLATFORM_ACCESS_TOKEN`, `MASTRA_PROJECT_ID` et `MASTRA_PLATFORM_BUCKET_NAME` sont injectés automatiquement ; le constructeur peut donc être appelé sans options. Pour le développement local, `MASTRA_PLATFORM_ACCESS_TOKEN` peut contenir un token d'API `sk_` provenant de la section **Tokens d'API** de la page des paramètres de votre organisation.

## Utilisation

Ajoutez un `PlatformFilesystem` à un Workspace et attribuez-le à un 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,
})
```

### Lecture et écriture de fichiers

Les clés des objets sont encodées en pourcentage par segment. Les noms de fichiers contenant `?`, `#`, `%`, `&`, `+` ou des espaces sont donc préservés de bout en bout :

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

### Mode lecture seule

Transmettez `readOnly: true` pour monter le bucket en lecture seule. Tout appel de modification lève `WorkspaceReadOnlyError` :

```typescript
const fs = new PlatformFilesystem({ readOnly: true })

await fs.readFile('/analyses/repo.md') // ok
await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError
```

### Sémantique de remplacement

`writeFile` prend en charge `overwrite: false` et lève `FileExistsError` lorsque la destination existe déjà.

`copyFile` et `moveFile` remplacent toujours la destination. La transmission de `overwrite: false` à l'une de ces méthodes lève une erreur au lieu de remplacer silencieusement la destination.

### Ajout à des fichiers

`appendFile` est une opération de lecture-modification-écriture qui n'est pas atomique. Des ajouts simultanés au même chemin peuvent s'écraser mutuellement. Pour les écritures simultanées, utilisez `writeFile` avec des clés distinctes.

## Paramètres du constructeur

**accessToken** (`string`): Token d'accès à la plateforme. Utilise par défaut la variable d'environnement MASTRA\_PLATFORM\_ACCESS\_TOKEN.

**projectId** (`string`): Identifiant du projet de la plateforme. Utilise par défaut la variable d'environnement MASTRA\_PROJECT\_ID.

**bucketName** (`string`): Nom du bucket de la plateforme dans lequel stocker les fichiers. Utilise par défaut la variable d'environnement MASTRA\_PLATFORM\_BUCKET\_NAME.

**readOnly** (`boolean`): Lorsque la valeur est true, tous les appels de modification lèvent WorkspaceReadOnlyError. (Default: `false`)

**displayName** (`string`): Nom lisible par les utilisateurs affiché dans les interfaces des Workspaces.

**description** (`string`): Courte description affichée dans les interfaces des Workspaces.

**icon** (`FilesystemIcon`): Icône affichée dans les interfaces des Workspaces.

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Instructions personnalisées renvoyées par getInstructions(). Une chaîne remplace entièrement les valeurs par défaut ; une fonction reçoit ces valeurs et peut les étendre ou les personnaliser pour chaque requête.

**id** (`string`): Identifiant unique de cette instance de système de fichiers. (Default: `Généré automatiquement`)

**fetch** (`typeof fetch`): Implémentation personnalisée de fetch, principalement destinée aux tests.

## Propriétés

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

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

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

**readOnly** (`boolean | undefined`): Indique si le système de fichiers a été monté en lecture seule.

## Erreurs

Les erreurs propres au système de fichiers correspondent aux types d'erreurs standard du Workspace :

- `FileNotFoundError` : le chemin n'existe pas. Levée par `readFile`, `stat` et `deleteFile` (sauf si `force: true` est défini).
- `FileExistsError` : `writeFile` a été appelé avec `overwrite: false` alors que la destination existe déjà.
- `WorkspaceReadOnlyError` : un appel de modification a été effectué sur un système de fichiers en lecture seule.

Les autres échecs de l'API Platform lèvent `PlatformApiError`. Les réponses structurées `{ error: { message, type } }` sont analysées dans `.code` (type lisible par une machine) et `.proxyMessage` (chaîne lisible par les utilisateurs) :

```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` et `WorkspaceReadOnlyError` sont des réexportations des types d'erreurs standard du Workspace provenant de `@mastra/core/workspace`. `PlatformApiError` est propre à `@mastra/platform-workspace`.

`code` et `proxyMessage` valent `undefined` lorsque le corps de la réponse n'est pas au format JSON, par exemple pour une réponse HTML 502 provenant d'un répartiteur de charge.

## Voir aussi

- [Référence de PlatformSandbox](https://mastra.zisheng.pro/fr/reference/workspace/platform-sandbox)
- [Référence de S3Filesystem](https://mastra.zisheng.pro/fr/reference/workspace/s3-filesystem)
- [Interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem)