Aller au contenu principal

FilesSDKFilesystem

Stocke des fichiers dans tout système de stockage sous-jacent pris en charge par FilesSDK, 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.

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 ou GCSFilesystem.

Installation
Lien direct vers Installation

npm install @mastra/files-sdk files-sdk

files-sdk est une dépendance homologue que vous configurez avec l'adaptateur que vous souhaitez utiliser.

Utilisation
Lien direct vers Utilisation

Créez une instance Files à partir de FilesSDK avec l'adaptateur de votre choix, puis transmettez-la à FilesSDKFilesystem :

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

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 pour découvrir le catalogue complet des adaptateurs et les options de configuration.

Montages en lecture seule
Lien direct vers Montages en lecture seule

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

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
= false
Lorsque la valeur est true, toutes les opérations d'écriture sont bloquées.

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 ('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
Lien direct vers Méthodes

FilesSDKFilesystem implémente l'interface WorkspaceFilesystem 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()
Lien direct vers init

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

await filesystem.init()

getInfo()
Lien direct vers getinfo

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

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

files
Lien direct vers 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.

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

Sémantique du stockage d'objets
Lien direct vers 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 et de GCSFilesystem.
  • 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).
On this page