WorkspaceFilesystem

添加于： @mastra/core@1.1.0

WorkspaceFilesystem 接口定义 Workspace 如何与文件存储交互。

方法

readFile(path, options?)

读取文件内容。

const content = await filesystem.readFile('/docs/guide.md')
const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })

参数：

path:

string

相对于 basePath 的文件路径

options?:

Options

readFile 选项。

Options

encoding?:

'utf-8' | 'binary'

文本或二进制编码

返回值： Promise<string | Buffer>

writeFile(path, content, options?)

写入文件内容。

await filesystem.writeFile('/docs/new.md', '# New Document')
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })

参数：

path:

string

相对于 basePath 的文件路径

content:

string | Buffer

文件内容

options?:

Options

配置选项。

Options

recursive?:

boolean

如果父目录不存在，则创建父目录

overwrite?:

boolean

覆盖现有文件

expectedMtime?:

Date

如果提供此参数，而文件当前的修改时间与之不匹配，则写入会失败并抛出 StaleFileError。可将其用于乐观并发控制，以检测读取和写入之间发生的外部修改。

deleteFile(path, options?)

删除文件。

await filesystem.deleteFile('/docs/old.md')
await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing

参数：

path:

string

文件路径

options?:

Options

配置选项。

Options

force?:

boolean

如果文件不存在，不抛出错误

appendFile(path, content)

将内容追加到文件；如果文件尚不存在，则创建该文件。父目录会自动创建。

await filesystem.appendFile('/logs/app.log', 'New log entry\n')

参数：

path:

string

文件路径

content:

string | Buffer

要追加的内容

copyFile(src, dest, options?)

将文件复制到新位置。

await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')

参数：

src:

string

源文件路径

dest:

string

目标文件路径

options?:

Options

配置选项。

Options

overwrite?:

boolean

如果目标已存在，则将其覆盖

moveFile(src, dest, options?)

移动文件或重命名。

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

参数：

src:

string

源文件路径

dest:

string

目标文件路径

options?:

Options

配置选项。

Options

overwrite?:

boolean

如果目标已存在，则将其覆盖

readdir(path, options?)

列出目录内容。

const entries = await filesystem.readdir('/docs')
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]

返回值： Promise<FileEntry[]>

interface FileEntry {
  name: string
  type: 'file' | 'directory'
  size?: number
  isSymlink?: boolean
  symlinkTarget?: string
}

mkdir(path, options?)

创建目录。

await filesystem.mkdir('/docs/api')
await filesystem.mkdir('/deeply/nested/path', { recursive: true })

参数：

path:

string

目录路径

options?:

Options

配置选项。

Options

recursive?:

boolean

创建父目录

rmdir(path, options?)

删除目录。

await filesystem.rmdir('/docs/old')
await filesystem.rmdir('/docs/nested', { recursive: true })

参数：

path:

string

目录路径

options?:

Options

配置选项。

Options

recursive?:

boolean

递归删除内容

force?:

boolean

如果目录不存在，不抛出错误

exists(path)

检查路径是否存在。

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

返回值： Promise<boolean>

stat(path)

获取文件或目录元数据。

const stat = await filesystem.stat('/docs/guide.md')
// { name: 'guide.md', path: '/docs/guide.md', type: 'file', size: 1234, createdAt: Date, modifiedAt: Date }

返回值： 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
}

可选方法

init()

初始化文件系统。由 workspace.init() 调用。

await filesystem.init?.()

destroy()

清理资源。由 workspace.destroy() 调用。

await filesystem.destroy?.()

getInfo()

获取文件系统元数据。

const info = await filesystem.getInfo?.()
// { id, name, provider, basePath, readOnly, status, storage? }

返回值： Promise<FilesystemInfo>

interface FilesystemInfo {
  id: string
  name: string
  provider: string
  basePath?: string
  readOnly?: boolean
  status?: string
  storage?: {
    totalBytes?: number
    usedBytes?: number
    availableBytes?: number
  }
}

getInstructions(opts?)

返回此文件系统工作方式的说明。将 Workspace 分配给 Agent 时，该说明会注入 Agent 的系统消息中。

const instructions = filesystem.getInstructions?.()
// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'

参数：

opts.requestContext?:

RequestContext

如果构造函数中提供了 instructions 函数，则转发给该函数。

返回值： string

相关内容

• Workspace 类
• Sandbox 接口