跳到主要内容

FilesSDKFilesystem

将文件存储在 FilesSDK 支持的任意存储后端中。FilesSDK 对 S3、Cloudflare R2、Google Cloud Storage、Azure Blob、Vercel Blob、MinIO、本地文件系统等提供了统一抽象。有关接口详情，请参阅 WorkspaceFilesystem 接口。

如果希望用同一套代码对接多个存储后端，请使用 FilesSDKFilesystem。无需更改 Workspace 设置，只需替换底层 driver 即可切换后端。如果只针对一个后端，并希望使用该后端的一等配置选项，建议使用专用 Provider（例如 S3Filesystem 或 GCSFilesystem）。

安装
安装的直接链接

npm install @mastra/files-sdk files-sdk

files-sdk 是 peer dependency，需要使用所选适配器对其进行配置。

用法
用法的直接链接

使用所选适配器创建 FilesSDK Files 实例，然后将其传给 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,
})

更换适配器
更换适配器的直接链接

同一个 FilesSDKFilesystem 可以与任意 FilesSDK 适配器配合使用。替换 driver factory 即可切换后端：

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' }) })

如需完整的适配器目录和配置选项，请参阅 FilesSDK 文档。

只读挂载
只读挂载的直接链接

const filesystem = new FilesSDKFilesystem({
  files,
  readOnly: true,
})

所有写入操作（writeFile、appendFile、deleteFile、copyFile、moveFile、mkdir、rmdir）都会抛出 WorkspaceReadOnlyError，读取操作则可正常执行。

构造函数参数
构造函数参数的直接链接

files:

Files
预先配置的 FilesSDK Files 实例，已绑定要使用的适配器和凭据。

id?:

string
= 自动生成
此文件系统实例的唯一标识符。

displayName?:

string
在 UI 中显示的易读名称。

icon?:

FilesystemIcon
UI 中使用的图标标识符。

description?:

string
在 UI 中显示的此文件系统的简短说明。

readOnly?:

boolean
= false
设为 true 时，所有写入操作都会被阻止。

属性
属性的直接链接

id:

string
文件系统实例标识符。

name:

string
Provider 名称（'FilesSDKFilesystem'）。

provider:

string
Provider 标识符（'files-sdk'）。

readOnly:

boolean | undefined
文件系统是否处于只读模式。

方法
方法的直接链接

FilesSDKFilesystem 实现了 WorkspaceFilesystem 接口，提供所有标准文件系统方法：

  • readFile(path, options?) - 读取文件内容
  • writeFile(path, content, options?) - 将内容写入文件
  • appendFile(path, content) - 将内容追加到文件
  • deleteFile(path, options?) - 删除文件
  • copyFile(src, dest, options?) - 复制文件
  • moveFile(src, dest, options?) - 移动文件或重命名
  • mkdir(path, options?) - 创建目录（对于对象存储不执行任何操作）
  • rmdir(path, options?) - 删除目录
  • readdir(path, options?) - 列出目录内容
  • exists(path) - 检查路径是否存在
  • stat(path) - 获取文件或目录元数据

init()
init的直接链接

初始化文件系统。验证已配置的适配器能否使用所提供的凭据列出键。

await filesystem.init()

getInfo()
getinfo的直接链接

返回此文件系统实例的元数据。

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

files
files的直接链接

底层 FilesSDK Files 实例以公共属性形式公开，便于在需要时直接调用特定于适配器的 API。

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

对象存储语义
对象存储语义的直接链接

FilesSDKFilesystem 会将配置的后端视为对象存储，即使底层适配器具有层级结构（例如 fs）也是如此。这样可确保不同适配器的行为一致：

  • mkdir 不执行任何操作。当存在以某个前缀开头的键时，对应目录便隐式存在。
  • exists 仅在存在完全匹配的文件键，或路径是至少包含一个子键的前缀时返回 true。层级适配器中遗留的空目录不算在内。
  • 当键不存在时，deleteFile 会抛出 FileNotFoundError，除非传入 { force: true }。
  • 对目录调用 deleteFile 会委托给 rmdir({ recursive: true })，行为与 S3Filesystem 和 GCSFilesystem 一致。
  • moveFile 通过先执行 copyFile，再执行 deleteFile 来实现。此操作不具备原子性。如果复制成功后删除源文件失败，目标文件会保留，源文件也不会被移除。
  • appendFile 是读取-修改-写入操作。并发追加同一个键时可能相互覆盖。这是对象存储的固有特性，并非 FilesSDK 特有。
  • readdir({ recursive: true }) 会生成中间目录条目（例如，除 a/b/c.txt 外还会生成 a/b）。
On this page