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

# FilesSDKFilesystem

Stocke des fichiers dans tout système de stockage sous-jacent pris en charge par [FilesSDK](https://files-sdk.dev), une abstraction unifiée au-dessus de S3, Cloudflare R2, Google Cloud Storage, Azure Blob, Vercel Blob, MinIO, du système de fichiers local et plus encore. Pour en savoir plus sur l'interface, consultez l'[interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem).

Utilisez `FilesSDKFilesystem` lorsque vous souhaitez qu'un adaptateur unique puisse cibler plusieurs systèmes de stockage sous-jacents avec le même code. Remplacez le pilote sous-jacent sans modifier la configuration du Workspace. Si vous ne ciblez qu'un seul système et souhaitez disposer d'options qui lui sont spécialement adaptées, privilégiez le Provider dédié, par exemple [`S3Filesystem`](https://mastra.zisheng.pro/fr/reference/workspace/s3-filesystem) ou [`GCSFilesystem`](https://mastra.zisheng.pro/fr/reference/workspace/gcs-filesystem).

## Installation

**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` est une dépendance homologue que vous configurez avec l'adaptateur que vous souhaitez utiliser.

## Utilisation

Créez une instance `Files` à partir de FilesSDK avec l'adaptateur de votre choix, puis transmettez-la à `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,
})
```

### Remplacement des adaptateurs

La même instance `FilesSDKFilesystem` fonctionne avec tous les adaptateurs FilesSDK. Remplacez la fabrique du pilote pour changer de système sous-jacent :

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

Consultez la [documentation de FilesSDK](https://files-sdk.dev) pour découvrir le catalogue complet des adaptateurs et les options de configuration.

### Montages en lecture seule

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

Toutes les opérations d'écriture (`writeFile`, `appendFile`, `deleteFile`, `copyFile`, `moveFile`, `mkdir`, `rmdir`) lèvent `WorkspaceReadOnlyError`, tandis que les lectures réussissent.

## Paramètres du constructeur

**files** (`Files`): Instance Files de FilesSDK préconfigurée et associée à l'adaptateur et aux identifiants que vous souhaitez utiliser.

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

**displayName** (`string`): Nom d'affichage lisible dans l'interface utilisateur.

**icon** (`FilesystemIcon`): Identifiant de l'icône pour l'interface utilisateur.

**description** (`string`): Courte description de ce système de fichiers destinée à l'interface utilisateur.

**readOnly** (`boolean`): Lorsque la valeur est true, toutes les opérations d'écriture sont bloquées. (Default: `false`)

## Propriétés

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

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

**provider** (`string`): Identifiant du Provider ('files-sdk').

**readOnly** (`boolean | undefined`): Indique si le système de fichiers est en mode lecture seule.

## Méthodes

`FilesSDKFilesystem` implémente l'[interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem) et fournit toutes les méthodes standard d'un système de fichiers :

- `readFile(path, options?)` - Lit le contenu d'un fichier
- `writeFile(path, content, options?)` - Écrit du contenu dans un fichier
- `appendFile(path, content)` - Ajoute du contenu à un fichier
- `deleteFile(path, options?)` - Supprime un fichier
- `copyFile(src, dest, options?)` - Copie un fichier
- `moveFile(src, dest, options?)` - Déplace ou renomme un fichier
- `mkdir(path, options?)` - Crée un répertoire (aucune opération pour les stockages d'objets)
- `rmdir(path, options?)` - Supprime un répertoire
- `readdir(path, options?)` - Répertorie le contenu d'un répertoire
- `exists(path)` - Vérifie si un chemin existe
- `stat(path)` - Renvoie les métadonnées d'un fichier ou d'un répertoire

### `init()`

Initialise le système de fichiers. Vérifie que l'adaptateur configuré peut répertorier les clés avec les identifiants fournis.

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

### `getInfo()`

Renvoie les métadonnées de cette instance de système de fichiers.

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

### `files`

L'instance `Files` de FilesSDK sous-jacente est exposée comme propriété publique si vous devez appeler directement des API propres à l'adaptateur.

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

## Sémantique du stockage d'objets

`FilesSDKFilesystem` traite le système sous-jacent configuré comme un stockage d'objets, même lorsque l'adaptateur sous-jacent est hiérarchique (tel que `fs`). Le comportement reste ainsi cohérent entre les adaptateurs :

- **`mkdir`** n'effectue aucune opération. Les répertoires existent implicitement lorsque des clés portant ce préfixe existent.
- **`exists`** renvoie `true` uniquement lorsqu'une clé exacte est présente comme fichier, ou lorsque le chemin est un préfixe qui contient au moins une clé enfant. Les répertoires vides résiduels des adaptateurs hiérarchiques ne sont pas pris en compte.
- **`deleteFile`** lève `FileNotFoundError` lorsque la clé n'existe pas, sauf si `{ force: true }` est transmis.
- **`deleteFile`** appliqué à un répertoire délègue l'opération à `rmdir({ recursive: true })`, conformément au comportement de [`S3Filesystem`](https://mastra.zisheng.pro/fr/reference/workspace/s3-filesystem) et de [`GCSFilesystem`](https://mastra.zisheng.pro/fr/reference/workspace/gcs-filesystem).
- **`moveFile`** est implémenté sous la forme d'un appel à `copyFile` suivi d'un appel à `deleteFile`. Il n'est pas **atomique**. Si la suppression de la source échoue après une copie réussie, la destination demeure et la source n'est pas supprimée.
- **`appendFile`** est une opération de lecture-modification-écriture. Des ajouts simultanés à la même clé peuvent s'écraser mutuellement. Ce comportement est inhérent au stockage d'objets et n'est pas propre à FilesSDK.
- **`readdir({ recursive: true })`** émet les entrées des répertoires intermédiaires (par exemple, `a/b` est émis en même temps que `a/b/c.txt`).

## Voir aussi

- [Interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem)
- [Référence de S3Filesystem](https://mastra.zisheng.pro/fr/reference/workspace/s3-filesystem)
- [Référence de GCSFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/gcs-filesystem)
- [Référence de AzureBlobFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/azure-blob-filesystem)
- [Présentation de Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)
- [Documentation de FilesSDK](https://files-sdk.dev)