Aller au contenu principal

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 pour un accès direct à S3, LocalFilesystem pour les répertoires locaux.

info

Pour en savoir plus sur l'interface, consultez l'interface WorkspaceFilesystem.

Installation
Lien direct vers Installation

npm install @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.

MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_PLATFORM_BUCKET_NAME=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
Lien direct vers Utilisation

Ajoutez un PlatformFilesystem à un Workspace et attribuez-le à un Agent :

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
Lien direct vers 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 :

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
Lien direct vers Mode lecture seule

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

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
Lien direct vers 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
Lien direct vers 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
Lien direct vers 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
= false
Lorsque la valeur est true, tous les appels de modification lèvent WorkspaceReadOnlyError.

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
= Généré automatiquement
Identifiant unique de cette instance de système de fichiers.

fetch?:

typeof fetch
Implémentation personnalisée de fetch, principalement destinée aux tests.

Propriétés
Lien direct vers 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
Lien direct vers 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) :

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.

On this page