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.
UtilisationLien direct vers 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 :
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 constructeurLien direct vers Paramètres du constructeur
basePath:
id?:
contained?:
allowedPaths?:
basePath.instructions?:
readOnly?:
PropriétésLien direct vers Propriétés
id:
name:
provider:
basePath:
readOnly:
allowedPaths:
MéthodesLien direct vers Méthodes
init()Lien direct vers init
Initialise le système de fichiers. Crée le répertoire de base s’il n’existe pas.
await filesystem.init()
Appelée par workspace.init().
Initialisation différéeLien direct vers 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()Lien direct vers destroy
Libère les ressources du système de fichiers.
await filesystem.destroy()
Appelée par workspace.destroy().
setAllowedPaths(pathsOrUpdater)Lien direct vers setallowedpathspathsorupdater
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.
// 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:
readFile(path, options?)Lien direct vers readfilepath-options
Lit le contenu d’un fichier.
const content = await filesystem.readFile('/docs/guide.md')
const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })
Paramètres :
path:
options?:
encoding?:
writeFile(path, content, options?)Lien direct vers writefilepath-content-options
Écrit du contenu dans un fichier.
await filesystem.writeFile('/docs/new.md', '# New Document')
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
Paramètres :
path:
content:
options?:
recursive?:
overwrite?:
expectedMtime?:
appendFile(path, content)Lien direct vers appendfilepath-content
Ajoute du contenu à un fichier existant.
await filesystem.appendFile('/logs/app.log', 'New log entry\n')
Paramètres :
path:
content:
deleteFile(path, options?)Lien direct vers deletefilepath-options
Supprime un fichier.
await filesystem.deleteFile('/docs/old.md')
await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing
Paramètres :
path:
options?:
force?:
copyFile(src, dest, options?)Lien direct vers copyfilesrc-dest-options
Copie un fichier vers un nouvel emplacement.
await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
await filesystem.copyFile('/src/config.json', '/backup/config.json', { overwrite: false })
Paramètres :
src:
dest:
options?:
overwrite?:
moveFile(src, dest, options?)Lien direct vers movefilesrc-dest-options
Déplace ou renomme un fichier.
await filesystem.moveFile('/docs/draft.md', '/docs/final.md')
await filesystem.moveFile('/temp/upload.txt', '/files/document.txt')
Paramètres :
src:
dest:
options?:
overwrite?:
mkdir(path, options?)Lien direct vers mkdirpath-options
Crée un répertoire.
await filesystem.mkdir('/docs/api')
await filesystem.mkdir('/deeply/nested/path', { recursive: true })
Paramètres :
path:
options?:
recursive?:
rmdir(path, options?)Lien direct vers rmdirpath-options
Supprime un répertoire.
await filesystem.rmdir('/docs/old')
await filesystem.rmdir('/docs/nested', { recursive: true })
Paramètres :
path:
options?:
recursive?:
force?:
readdir(path, options?)Lien direct vers readdirpath-options
Répertorie le contenu d’un répertoire.
const entries = await filesystem.readdir('/docs')
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
exists(path)Lien direct vers existspath
Vérifie si un chemin existe.
const exists = await filesystem.exists('/docs/guide.md')
stat(path)Lien direct vers statpath
Obtient les métadonnées d’un fichier ou d’un répertoire.
const stat = await filesystem.stat('/docs/guide.md')
// { type: 'file', size: 1234, modifiedAt: Date, createdAt: Date, path: '/docs/guide.md' }
getInfo()Lien direct vers getinfo
Renvoie les métadonnées de cette instance de système de fichiers.
const info = filesystem.getInfo()
// { id: '...', name: 'LocalFilesystem', provider: 'local', basePath: '/workspace', readOnly: false }
getInstructions(opts?)Lien direct vers getinstructionsopts
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.
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 :
const instructions = filesystem.getInstructions({ requestContext })
Paramètres :
opts.requestContext?:
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.
Résolution des cheminsLien direct vers Résolution des chemins
Fonctionnement de basePathLien direct vers how-basepath-works
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
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écutionLien direct vers 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 absolusLien direct vers 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 :
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.