PlatformFilesystem
將檔案儲存在 Mastra Platform Workspace bucket 中。每個 Mastra Platform 環境可有一個 bucket，PlatformFilesystem 讓 Agent 可對其進行 read、write、list、delete 和 move 操作。
相關 Provider：用於直接存取 S3 的 S3Filesystem，以及用於本機目錄的 LocalFilesystem。
介面詳情請參閱 WorkspaceFilesystem 介面。
安裝「安裝」的直接連結
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/platform-workspace
pnpm add @mastra/platform-workspace
yarn add @mastra/platform-workspace
bun add @mastra/platform-workspace
設定 Platform 憑證。access token、專案 ID 與 bucket 名稱均會回退使用環境變數，因此 Mastra Platform 部署可以不傳入任何建構函式選項。
- .env 檔案
- 建構函式
MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
new PlatformFilesystem({
accessToken: 'your-platform-access-token',
projectId: 'your-project-id',
bucketName: 'your-bucket-name',
})
在 Mastra Platform 部署中，MASTRA_PLATFORM_ACCESS_TOKEN、MASTRA_PROJECT_ID 與 MASTRA_PLATFORM_BUCKET_NAME 會自動注入，因此可以不傳入任何選項來呼叫建構函式。在本機開發時，MASTRA_PLATFORM_ACCESS_TOKEN 可設為來自組織設定頁面 API Tokens 區段的 sk_ API token。
使用方式「使用方式」的直接連結
將 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,
})
讀取與寫入檔案「讀取與寫入檔案」的直接連結
物件 key 會逐區段進行百分比編碼，因此包含 ?、#、%、&、+ 或空格的檔名在整個流程中都會保留：
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 即可以唯讀模式掛載 bucket。任何變更資料的呼叫都會拋出 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 是「讀取—修改—寫入」操作，並非原子性操作。同時對相同路徑附加內容可能會彼此覆寫。如果會同時寫入，請使用不同 key 呼叫 writeFile。
建構函式參數「建構函式參數」的直接連結
accessToken?:
projectId?:
bucketName?:
readOnly?:
displayName?:
description?:
icon?:
instructions?:
id?:
fetch?:
屬性「屬性」的直接連結
id:
name:
provider:
readOnly:
錯誤「錯誤」的直接連結
檔案系統特定錯誤與標準 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 時，code 與 proxyMessage 會是 undefined，例如負載平衡器回傳的 HTML 502 回應。