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
設定平台憑證。存取 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 是讀取、修改再寫入的操作，並非不可分割操作。同時向相同路徑附加內容時，操作之間可能互相覆寫。如有多個並行寫入者，請使用 writeFile 並分別指定不同 key。
建構函式參數建構函式參數 的直接連結
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 回應。