MesaFilesystem

Stocke les fichiers du Workspace dans des dépôts Mesa au moyen de l’interface Mastra standard WorkspaceFilesystem.

Utilisez MesaFilesystem lorsque des Agents ont besoin d’un stockage de fichiers versionné. Pour un répertoire local, utilisez LocalFilesystem. Pour le stockage d’objets, utilisez S3Filesystem, GCSFilesystem ou AzureBlobFilesystem.

info

MesaFilesystem s’exécute dans le processus Mastra.

Le montage POSIX de Mesa (permettant d’utiliser un système de fichiers Mesa dans un Sandbox) ne fait pas encore partie du package @mastra/mesa. Sa prise en charge sera bientôt disponible.

Installation

npm

npm install @mastra/mesa

pnpm

pnpm add @mastra/mesa

Yarn

yarn add @mastra/mesa

Bun

bun add @mastra/mesa

Exemple d’utilisation

Montez un dépôt Mesa et transmettez le système de fichiers à un Workspace :

src/mastra/workspace.ts

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { MesaFilesystem } from '@mastra/mesa'

const workspace = new Workspace({
  filesystem: new MesaFilesystem({
    apiKey: process.env.MESA_API_KEY,
    org: 'acme',
    repos: [{ name: 'docs', bookmark: 'main' }],
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

Lorsque apiKey est omis, MESA_API_KEY est utilisée comme valeur de repli.

Paramètres du constructeur

apiKey?:

string

Clé d’API Mesa. Lorsque cette valeur est omise, MESA_API_KEY est utilisée comme valeur de repli.

org?:

string

Slug de l’organisation Mesa. Lorsqu’il est omis, le SDK Mesa détermine l’organisation par défaut.

repos:

RepoConfig[]

Dépôts Mesa à monter.

cache?:

{ diskCache?: { path: string; maxSizeBytes?: number } }

Configuration du cache du système de fichiers Mesa.

ttl?:

number

Durée de vie du token de montage Mesa, en secondes.

readOnly?:

boolean

= false

Monte tous les dépôts en lecture seule.

Propriétés

id:

string

Identifiant de l’instance du système de fichiers.

name:

string

Nom du Provider ('MesaFilesystem').

provider:

string

Identifiant du Provider ('mesa').

readOnly:

boolean | undefined

Indique si les opérations d’écriture sont bloquées.

client:

Mesa | undefined

Client du SDK Mesa créé par ce Provider. Non défini avant l’initialisation.

filesystem:

MesaFileSystem

Système de fichiers Mesa actif. Accédez-y après l’initialisation lorsque vous avez besoin du système de fichiers brut du SDK Mesa.

change:

MesaFileSystem["change"]

Opérations Mesa de gestion des changements pour le système de fichiers monté.

bookmark:

MesaFileSystem["bookmark"]

Opérations Mesa de gestion des signets pour le système de fichiers monté.

Méthodes

MesaFilesystem implémente l’interface WorkspaceFilesystem.

Opérations sur les fichiers

readFile(path, options?)

Lit un fichier depuis Mesa.

const content = await filesystem.readFile('/acme/docs/README.md', {
  encoding: 'utf-8',
})

Renvoie : Promise<string | Buffer>

writeFile(path, content, options?)

Écrit un fichier dans Mesa.

await filesystem.writeFile('/acme/docs/report.md', '# Report')

Renvoie : Promise<void>

appendFile(path, content)

Ajoute du contenu à la fin d’un fichier.

await filesystem.appendFile('/acme/docs/log.txt', 'new line\n')

Renvoie : Promise<void>

deleteFile(path, options?)

Supprime un fichier.

await filesystem.deleteFile('/acme/docs/old-report.md')

Renvoie : Promise<void>

copyFile(src, dest, options?)

Copie un fichier.

await filesystem.copyFile('/acme/docs/report.md', '/acme/docs/archive/report.md')

Renvoie : Promise<void>

moveFile(src, dest, options?)

Déplace ou renomme un fichier.

await filesystem.moveFile('/acme/docs/draft.md', '/acme/docs/final.md')

Renvoie : Promise<void>

Opérations sur les répertoires

mkdir(path, options?)

Crée un répertoire.

await filesystem.mkdir('/acme/docs/reports', { recursive: true })

Renvoie : Promise<void>

rmdir(path, options?)

Supprime un répertoire.

await filesystem.rmdir('/acme/docs/reports', { recursive: true })

Renvoie : Promise<void>

readdir(path, options?)

Répertorie les entrées d’un répertoire.

const entries = await filesystem.readdir('/acme/docs', {
  recursive: true,
  extension: '.md',
})

Renvoie : Promise<FileEntry[]>

Opérations sur les chemins

exists(path)

Vérifie si un chemin existe.

const exists = await filesystem.exists('/acme/docs/README.md')

Renvoie : Promise<boolean>

stat(path)

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

const stat = await filesystem.stat('/acme/docs/README.md')

Renvoie : Promise<FileStat>

realpath(path)

Renvoie le chemin canonique fourni par Mesa.

const realPath = await filesystem.realpath('/acme/docs/README.md')

Renvoie : Promise<string>

Opérations Mesa

bash(options?)

Crée un environnement d’exécution Bash reposant sur Mesa pour ce système de fichiers.

const bash = await filesystem.bash({
  cwd: '/acme/docs',
})

Renvoie : Promise<Bash>

Sémantique des chemins

Les méthodes attendent des chemins absolus. Pour MesaFilesystem, les chemins ont pour racine le montage Mesa et doivent inclure le slug de l’organisation ainsi que le nom du dépôt :

await filesystem.readFile('/acme/docs/README.md')

N’omettez pas la barre oblique initiale :

await filesystem.readFile('acme/docs/README.md') // Incorrect
await filesystem.readFile('/acme/docs/README.md') // Correct

L’organisation provient de org dans le constructeur ou, lorsque org est omis, de l’inférence de l’organisation par défaut du SDK Mesa. Elle reste le premier segment du chemin.

Lorsque vous montez plusieurs dépôts, chacun d’eux est disponible sous le segment de l’organisation :

const filesystem = new MesaFilesystem({
  org: 'acme',
  repos: [
    { name: 'docs', bookmark: 'main' },
    { name: 'website', bookmark: 'main' },
  ],
})

await filesystem.readFile('/acme/docs/README.md')
await filesystem.readFile('/acme/website/package.json')

API de versionnement Mesa

Accédez au système de fichiers Mesa sous-jacent pour effectuer les opérations de changement et de signet propres à Mesa :

await filesystem.writeFile('/acme/docs/draft.md', 'Draft')

const current = await filesystem.change.current({
  repo: 'docs',
})

await filesystem.bookmark.move({
  repo: 'docs',
  name: 'main',
  changeId: current.changeId,
})

Pour en savoir plus sur la sémantique du versionnement, consultez la documentation de Mesa.

Mode lecture seule

Définissez readOnly: true pour bloquer les opérations d’écriture via Mastra :

const filesystem = new MesaFilesystem({
  repos: [{ name: 'docs', bookmark: 'main' }],
  readOnly: true,
})

Les opérations de lecture continuent de fonctionner. Les opérations d’écriture déclenchent WorkspaceReadOnlyError.

Accès concurrent

overwrite: false et expectedMtime utilisent des vérifications préalables avant l’écriture. Ces vérifications ne sont pas atomiques, sauf si Mesa ajoute des écritures conditionnelles natives pour les montages d’application.

Ressources associées

• Interface WorkspaceFilesystem
• Documentation du système de fichiers
• Vue d’ensemble du Workspace
• Documentation Mesa