跳到主要内容

PlatformFilesystem

将文件存储在 Mastra Platform Workspace 存储桶中。每个 Mastra Platform 环境都可以有一个存储桶，PlatformFilesystem 可让 Agent 对其执行 read、write、list、delete 和 move 操作。

相关 Provider：用于直接访问 S3 的 S3Filesystem，以及用于本地目录的 LocalFilesystem。

信息

有关接口的详细信息，请参阅 WorkspaceFilesystem 接口。

安装
安装的直接链接

npm install @mastra/platform-workspace

配置 Platform 凭据。访问令牌、项目 ID 和存储桶名称会回退到环境变量，因此 Mastra Platform 部署可以不传任何构造函数选项。

MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name

在 Mastra Platform 部署中，MASTRA_PLATFORM_ACCESS_TOKEN、MASTRA_PROJECT_ID 和 MASTRA_PLATFORM_BUCKET_NAME 会自动注入，因此调用构造函数时可以不传选项。在本地开发时，MASTRA_PLATFORM_ACCESS_TOKEN 可以使用组织设置页面 API Tokens 下的 sk_ API 令牌。

用法
用法的直接链接

将 PlatformFilesystem 添加到 Workspace 并分配给 Agent：

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem } from '@mastra/platform-workspace'

const workspace = new Workspace({
  filesystem: new PlatformFilesystem({
    // accessToken, projectId, bucketName all fall back to env vars
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'File Agent',
  instructions: 'You are a research assistant that reads and writes reports.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

读取和写入文件
读取和写入文件的直接链接

对象键会逐段进行百分号编码，因此包含 ?、#、%、&、+ 或空格的文件名可以在整个流程中保持不变：

const fs = new PlatformFilesystem()

await fs.writeFile('/analyses/repo.md', markdown)
const content = await fs.readFile('/analyses/repo.md')
const entries = await fs.readdir('/analyses')
await fs.moveFile('/analyses/repo.md', '/analyses/repo-final.md')

只读模式
只读模式的直接链接

传入 readOnly: true 以只读方式挂载存储桶。任何修改调用都会抛出 WorkspaceReadOnlyError：

const fs = new PlatformFilesystem({ readOnly: true })

await fs.readFile('/analyses/repo.md') // ok
await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError

覆盖语义
覆盖语义的直接链接

writeFile 支持 overwrite: false，当目标已存在时会抛出 FileExistsError。

copyFile 和 moveFile 始终会覆盖目标。向任一方法传入 overwrite: false 都会抛出错误，而不会静默覆盖。

追加文件
追加文件的直接链接

appendFile 是一次“读取—修改—写入”操作，并非原子操作。并发追加到同一路径可能相互覆盖。存在并发写入者时，请使用 writeFile 写入不同的键。

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

accessToken?:

string
Platform 访问令牌。回退到 MASTRA_PLATFORM_ACCESS_TOKEN 环境变量。

projectId?:

string
Platform 项目 ID。回退到 MASTRA_PROJECT_ID 环境变量。

bucketName?:

string
用于存储文件的 Platform 存储桶名称。回退到 MASTRA_PLATFORM_BUCKET_NAME 环境变量。

readOnly?:

boolean
= false
为 true 时，所有修改调用都会抛出 WorkspaceReadOnlyError。

displayName?:

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

description?:

string
在 Workspace UI 中显示的简短说明。

icon?:

FilesystemIcon
在 Workspace UI 中显示的图标。

instructions?:

string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)
由 getInstructions() 返回的自定义指令。字符串会完全替换默认值；函数会接收默认值，并可针对每个请求进行扩展或自定义。

id?:

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

fetch?:

typeof fetch
自定义 fetch 实现，主要用于测试。

属性
属性的直接链接

id:

string
文件系统实例标识符。

name:

string
Provider 名称（'PlatformFilesystem'）。

provider:

string
Provider 标识符（'platform'）。

readOnly:

boolean | undefined
文件系统是否以只读方式挂载。

错误
错误的直接链接

文件系统特有错误与标准 Workspace 错误类型一致：

  • FileNotFoundError：路径不存在。由 readFile、stat 和 deleteFile 抛出（除非设置了 force: true）。
  • FileExistsError：调用 writeFile 时传入了 overwrite: false，且目标已存在。
  • WorkspaceReadOnlyError：对只读文件系统进行了修改调用。

其他 Platform API 失败会抛出 PlatformApiError。结构化的 { error: { message, type } } 响应会被解析为 .code（机器可读类型）和 .proxyMessage（供用户阅读的字符串）：

import { FileNotFoundError } from '@mastra/core/workspace'
import { PlatformApiError } from '@mastra/platform-workspace'

try {
  await fs.readFile('/missing.txt')
} catch (err) {
  if (err instanceof FileNotFoundError) {
    // handle missing file
  } else if (err instanceof PlatformApiError) {
    if (err.code === 'authentication_error') {
      // refresh token
    }
    console.error(err.status, err.code, err.proxyMessage)
  }
}

FileNotFoundError、FileExistsError 和 WorkspaceReadOnlyError 是从 @mastra/core/workspace 重新导出的标准 Workspace 错误类型。PlatformApiError 是 @mastra/platform-workspace 特有的错误。

当响应正文不是 JSON 时（例如负载均衡器返回的 HTML 502），code 和 proxyMessage 为 undefined。

On this page