WorkspaceFilesystem
Added in: @mastra/core@1.1.0
The WorkspaceFilesystem interface defines how workspaces interact with file storage.
MethodsMethods的直接链接
readFile(path, options?)readfilepath-options的直接链接
Read file contents.
const content = await filesystem.readFile('/docs/guide.md', { encoding: 'utf-8' })
const buffer = await filesystem.readFile('/image.png') // Buffer
Parameters:
path:
options?:
encoding?:
Returns: Promise<string | Buffer>
writeFile(path, content, options?)writefilepath-content-options的直接链接
Write file contents.
await filesystem.writeFile('/docs/new.md', '# New Document')
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
Parameters:
path:
content:
options?:
recursive?:
overwrite?:
expectedMtime?:
deleteFile(path, options?)deletefilepath-options的直接链接
Delete a file.
await filesystem.deleteFile('/docs/old.md')
await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing
Parameters:
path:
options?:
force?:
appendFile(path, content)appendfilepath-content的直接链接
Append content to a file, creating it if it doesn't already exist. Parent directories are created automatically.
await filesystem.appendFile('/logs/app.log', 'New log entry\n')
Parameters:
path:
content:
copyFile(src, dest, options?)copyfilesrc-dest-options的直接链接
Copy a file to a new location.
await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
Parameters:
src:
dest:
options?:
overwrite?:
moveFile(src, dest, options?)movefilesrc-dest-options的直接链接
Move or rename a file.
await filesystem.moveFile('/docs/draft.md', '/docs/final.md')
Parameters:
src:
dest:
options?:
overwrite?:
readdir(path, options?)readdirpath-options的直接链接
List directory contents.
const entries = await filesystem.readdir('/docs')
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
Returns: Promise<FileEntry[]>
interface FileEntry {
name: string
type: 'file' | 'directory'
size?: number
isSymlink?: boolean
symlinkTarget?: string
}
mkdir(path, options?)mkdirpath-options的直接链接
Create a directory.
await filesystem.mkdir('/docs/api')
await filesystem.mkdir('/deeply/nested/path', { recursive: true })
Parameters:
path:
options?:
recursive?:
rmdir(path, options?)rmdirpath-options的直接链接
Remove a directory.
await filesystem.rmdir('/docs/old')
await filesystem.rmdir('/docs/nested', { recursive: true })
Parameters:
path:
options?:
recursive?:
force?:
exists(path)existspath的直接链接
Check if a path exists.
const exists = await filesystem.exists('/docs/guide.md')
Returns: Promise<boolean>
stat(path)statpath的直接链接
Get file or directory metadata.
const stat = await filesystem.stat('/docs/guide.md')
// { name: 'guide.md', path: '/docs/guide.md', type: 'file', size: 1234, createdAt: Date, modifiedAt: Date }
Returns: Promise<FileStat>
interface FileStat {
name: string // File or directory name (basename only)
path: string // Path relative to the filesystem basePath
type: 'file' | 'directory'
size: number
createdAt: Date
modifiedAt: Date
mimeType?: string
}
Optional methodsOptional methods的直接链接
init()init的直接链接
Initialize the filesystem. Called by workspace.init().
await filesystem.init?.()
destroy()destroy的直接链接
Clean up resources. Called by workspace.destroy().
await filesystem.destroy?.()
getInfo()getinfo的直接链接
Get filesystem metadata.
const info = await filesystem.getInfo?.()
// { id, name, provider, status, error, readOnly, icon, metadata }
Returns: Promise<FilesystemInfo>
interface FilesystemInfo {
id: string
name: string
provider: string
status?: string
error?: string // Error message when status is 'error'
readOnly?: boolean
icon?: string // Icon identifier for UI display
metadata?: Record<string, unknown> // Provider-specific, e.g. LocalFilesystem includes basePath
}
getInstructions(opts?)getinstructionsopts的直接链接
Returns a description of how this filesystem works. Injected into the agent's system message when the workspace is assigned to an agent.
const instructions = filesystem.getInstructions?.()
// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
Parameters:
opts.requestContext?:
instructions function if one was provided in the constructor.Returns: string
walk(path, options?)walkpath-options的直接链接
Native recursive tree walk executed by the provider in as few calls as possible. When implemented, the workspace list_files tool uses it instead of issuing one readdir round trip per directory, which matters for remote providers (sandboxes, object stores). If walk throws, tools fall back to the readdir-based walk automatically and log a warning through the workspace logger, since the fallback issues one round trip per directory.
const entries = await filesystem.walk?.('.', { maxDepth: 3 })
// [{ name: 'index.ts', type: 'file', path: 'src/index.ts' }, ...]
Parameters:
path:
options.maxDepth?:
options.includeHidden?:
options.includeGitignoreFiles?:
.gitignore files even when hidden entries are excluded. list_files sets this so it can apply each directory's .gitignore. Providers may ignore it.options.skipDirectoryNames?:
node_modules. list_files filters the results as well, so providers may ignore it.Returns: Promise<WalkEntry[]>
interface WalkEntry extends FileEntry {
path: string // Relative to the walk root, POSIX separators, no leading "./"
}
grep(options)grepoptions的直接链接
Native content search executed by the provider (for example with rg or grep inside a sandbox). When implemented, the workspace grep tool delegates to it instead of downloading every file to search host-side. Throw UnsupportedGrepPatternError when a pattern can't run natively so that callers catch it and fall back to the host-side implementation. That fallback is logged at info level; any other error from grep also triggers the fallback but is logged as a warning, since the host-side search reads every candidate file.
const results = await filesystem.grep?.({
pattern: 'TODO',
path: '.',
caseSensitive: true,
includeHidden: false,
})
// [{ path: 'src/index.ts', matches: [{ line: 3, column: 6, text: '// TODO: fix' }] }]
Parameters:
options.pattern:
options.path:
options.caseSensitive:
options.includeHidden:
options.maxCountPerFile?:
grep -m).options.maxTotalMatches?:
options.contextLines?:
Returns: Promise<FilesystemGrepResult[]>
interface FilesystemGrepResult {
path: string // Relative to the search root, POSIX separators
matches: FilesystemGrepMatch[]
}
interface FilesystemGrepMatch {
line: number // 1-based line number
column: number // 0-based UTF-16 (JS string) index, not a byte offset
text: string // Full matched line, without trailing newline
before?: string[] // Context lines before the match
after?: string[] // Context lines after the match
}