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

# LocalFilesystem

**Ajouté dans :** `@mastra/core@1.1.0`

Stocke les fichiers dans un répertoire du système de fichiers local. Pour plus de détails sur l’interface, consultez [l’interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem).

## Utilisation

Ajoutez un `LocalFilesystem` à un Workspace et attribuez-le à un Agent. L’Agent peut alors lire, écrire et gérer des fichiers dans le cadre de ses tâches :

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})

// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace')
```

## Paramètres du constructeur

**basePath** (`string`): Chemin du répertoire de base sur le disque. Tous les chemins de fichiers sont résolus par rapport à ce répertoire.

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

**contained** (`boolean`): Lorsque cette option vaut true, toutes les opérations sur les fichiers doivent rester dans basePath. Cela empêche les attaques par traversée de chemin et les sorties au moyen de liens symboliques. Consultez le confinement. (Default: `true`)

**allowedPaths** (`string[]`): Répertoires supplémentaires auxquels l’Agent peut accéder en dehors de basePath. (Default: `[]`)

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Instructions personnalisées qui remplacent les instructions par défaut renvoyées par getInstructions(). Transmettez une chaîne pour les remplacer entièrement, ou une fonction pour les étendre avec un accès au requestContext actuel afin de les personnaliser pour chaque requête.

**readOnly** (`boolean`): Lorsque cette option vaut true, toutes les opérations d’écriture sont bloquées. Les opérations de lecture restent autorisées. (Default: `false`)

## Propriétés

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

**name** (`string`): Nom du provider ('LocalFilesystem')

**provider** (`string`): Identifiant du provider ('local')

**basePath** (`string`): Chemin de base absolu sur le disque

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

**allowedPaths** (`readonly string[]`): Ensemble actuel des chemins autorisés résolus. Ces chemins sont permis au-delà de basePath lorsque le confinement est activé.

## Méthodes

### `init()`

Initialise le système de fichiers. Crée le répertoire de base s’il n’existe pas.

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

Appelée par `workspace.init()`.

### Initialisation différée

LocalFilesystem s’initialise lors de la première opération s’il ne l’est pas déjà et crée automatiquement le répertoire de base. L’appel explicite de `init()` est facultatif, mais peut être utile pour créer les répertoires avant la première opération.

### `destroy()`

Libère les ressources du système de fichiers.

```typescript
await filesystem.destroy()
```

Appelée par `workspace.destroy()`.

### `setAllowedPaths(pathsOrUpdater)`

Met à jour les chemins autorisés lors de l’exécution. Accepte un nouveau tableau de chemins, qui remplace le tableau actuel, ou une fonction de mise à jour qui reçoit les chemins actuels et renvoie le nouvel ensemble.

```typescript
// Set directly
filesystem.setAllowedPaths(['/home/user/.config'])

// Update with callback
filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])

// Clear all allowed paths
filesystem.setAllowedPaths([])
```

**Paramètres :**

**pathsOrUpdater** (`string[] | ((current: readonly string[]) => string[])`): Nouveau tableau de chemins autorisés ou fonction de mise à jour recevant les chemins actuels

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

Lit le contenu d’un fichier.

```typescript
const content = await filesystem.readFile('/docs/guide.md')
const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })
```

**Paramètres :**

**path** (`string`): Chemin du fichier relatif à basePath

**options** (`Options`): Options de configuration.

**options.encoding** (`'utf-8' | 'binary'`): Encodage texte ou binaire

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

Écrit du contenu dans un fichier.

```typescript
await filesystem.writeFile('/docs/new.md', '# New Document')
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
```

**Paramètres :**

**path** (`string`): Chemin du fichier relatif à basePath

**content** (`string | Buffer`): Contenu du fichier

**options** (`Options`): Options de configuration.

**options.recursive** (`boolean`): Crée les répertoires parents s’ils n’existent pas

**options.overwrite** (`boolean`): Écrase le fichier existant

**options.expectedMtime** (`Date`): Si cette option est fournie, l’écriture échoue avec une StaleFileError lorsque l’heure de modification actuelle du fichier ne correspond pas. Utilisez-la pour le contrôle de concurrence optimiste afin de détecter les modifications externes entre la lecture et l’écriture.

### `appendFile(path, content)`

Ajoute du contenu à un fichier existant.

```typescript
await filesystem.appendFile('/logs/app.log', 'New log entry\n')
```

**Paramètres :**

**path** (`string`): Chemin du fichier relatif à basePath

**content** (`string | Buffer`): Contenu à ajouter

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

Supprime un fichier.

```typescript
await filesystem.deleteFile('/docs/old.md')
await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing
```

**Paramètres :**

**path** (`string`): Chemin du fichier

**options** (`Options`): Options de configuration.

**options.force** (`boolean`): Ne génère pas d’erreur si le fichier n’existe pas

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

Copie un fichier vers un nouvel emplacement.

```typescript
await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
await filesystem.copyFile('/src/config.json', '/backup/config.json', { overwrite: false })
```

**Paramètres :**

**src** (`string`): Chemin du fichier source

**dest** (`string`): Chemin du fichier de destination

**options** (`Options`): Options de configuration.

**options.overwrite** (`boolean`): Écrase la destination si elle existe

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

Déplace ou renomme un fichier.

```typescript
await filesystem.moveFile('/docs/draft.md', '/docs/final.md')
await filesystem.moveFile('/temp/upload.txt', '/files/document.txt')
```

**Paramètres :**

**src** (`string`): Chemin du fichier source

**dest** (`string`): Chemin du fichier de destination

**options** (`Options`): Options de configuration.

**options.overwrite** (`boolean`): Écrase la destination si elle existe

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

Crée un répertoire.

```typescript
await filesystem.mkdir('/docs/api')
await filesystem.mkdir('/deeply/nested/path', { recursive: true })
```

**Paramètres :**

**path** (`string`): Chemin du répertoire

**options** (`Options`): Options de configuration.

**options.recursive** (`boolean`): Crée les répertoires parents

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

Supprime un répertoire.

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

**Paramètres :**

**path** (`string`): Chemin du répertoire

**options** (`Options`): Options de configuration.

**options.recursive** (`boolean`): Supprime le contenu récursivement

**options.force** (`boolean`): Ne génère pas d’erreur si le répertoire n’existe pas

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

Répertorie le contenu d’un répertoire.

```typescript
const entries = await filesystem.readdir('/docs')
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
```

### `exists(path)`

Vérifie si un chemin existe.

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

### `stat(path)`

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

```typescript
const stat = await filesystem.stat('/docs/guide.md')
// { type: 'file', size: 1234, modifiedAt: Date, createdAt: Date, path: '/docs/guide.md' }
```

### `getInfo()`

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

```typescript
const info = filesystem.getInfo()
// { id: '...', name: 'LocalFilesystem', provider: 'local', basePath: '/workspace', readOnly: false }
```

### `getInstructions(opts?)`

Renvoie une description du fonctionnement des chemins dans ce système de fichiers. Lorsqu’il est attribué à un Agent, ce texte est injecté dans le message système de l’Agent.

```typescript
const instructions = filesystem.getInstructions()
// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
```

Transmettez `requestContext` pour permettre une personnalisation par requête lorsque l’option `instructions` du constructeur est une fonction :

```typescript
const instructions = filesystem.getInstructions({ requestContext })
```

**Paramètres :**

**opts.requestContext** (`RequestContext`): Transmis à la fonction instructions si celle-ci a été fournie au constructeur.

**Renvoie :** `string`

Pour remplacer la sortie par défaut, transmettez une option `instructions` au constructeur. Consultez les [paramètres du constructeur](#constructor-parameters).

## Résolution des chemins

### Fonctionnement de `basePath`

L’option `basePath` définit le répertoire racine de toutes les opérations sur les fichiers. Les chemins de fichiers transmis à des méthodes comme `readFile()` sont résolus par rapport à cette base :

- Les barres obliques initiales sont supprimées : `/docs/guide.md` → `docs/guide.md`
- Le chemin est normalisé et joint à basePath
- Résultat : `./workspace` + `docs/guide.md` → `./workspace/docs/guide.md`

```typescript
const filesystem = new LocalFilesystem({
  basePath: './workspace',
})

// These all resolve to ./workspace/docs/guide.md
await filesystem.readFile('/docs/guide.md')
await filesystem.readFile('docs/guide.md')
```

### Chemins relatifs et contexte d’exécution

Lorsque vous utilisez un chemin relatif pour `basePath`, il est résolu à partir de `process.cwd()`. Dans les projets Mastra, le répertoire de travail actuel varie selon la manière dont vous exécutez votre code :

| Contexte       | Répertoire de travail                                   | Résolution de `./workspace`     |
| -------------- | ------------------------------------------------------- | ------------------------------- |
| `mastra dev`   | `./src/mastra/public/`                                  | `./src/mastra/public/workspace` |
| `mastra start` | `./.mastra/output/`                                     | `./.mastra/output/workspace`    |
| Script direct  | Emplacement depuis lequel vous avez exécuté la commande | Par rapport à cet emplacement   |

Cela peut prêter à confusion lorsqu’un même chemin relatif est résolu vers des emplacements différents.

### Recommandation : utilisez des chemins absolus

Pour obtenir des chemins cohérents dans tous les contextes d’exécution, utilisez une variable d’environnement contenant un chemin absolu :

```typescript
import { LocalFilesystem } from '@mastra/core/workspace'

const filesystem = new LocalFilesystem({
  basePath: process.env.WORKSPACE_PATH!,
})
```

Définissez `WORKSPACE_PATH` dans votre environnement sur un chemin absolu tel que `/home/user/my-project/workspace`. Ainsi, le chemin du Workspace reste cohérent quelle que soit la manière dont vous exécutez votre code.

## Voir aussi

- [Interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem)
- [Classe Workspace](https://mastra.zisheng.pro/fr/reference/workspace/workspace-class)
- [Présentation de Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)