跳至主要內容

FilesSDKFilesystem

將檔案儲存在 FilesSDK 支援的任何儲存後端。FilesSDK 為 S3、Cloudflare R2、Google Cloud Storage、Azure Blob、Vercel Blob、MinIO、本機檔案系統等提供統一的抽象層。介面詳情請參閱 WorkspaceFilesystem 介面。

若想以相同程式碼透過單一 Adapter 使用多種儲存後端，請使用 FilesSDKFilesystem。你可以更換底層驅動程式，而不必變更 Workspace 設定。如果只使用一種後端，且需要該後端的完整設定選項，建議使用專用 Provider（例如 S3Filesystem 或 GCSFilesystem）。

安裝
「安裝」的直接連結

npm install @mastra/files-sdk files-sdk

files-sdk 是 peer dependency，你需要為它設定要使用的 Adapter。

使用方式
「使用方式」的直接連結

使用你選擇的 Adapter 建立 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,
})

更換 Adapter
「更換 Adapter」的直接連結

同一個 FilesSDKFilesystem 可搭配任何 FilesSDK Adapter 使用。只要替換驅動程式工廠函式，即可切換後端：

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

如需完整的 Adapter 清單與設定選項，請參閱 FilesSDK 文件。

唯讀掛載
「唯讀掛載」的直接連結

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

所有寫入操作（writeFile、appendFile、deleteFile、copyFile、moveFile、mkdir、rmdir）都會擲回 WorkspaceReadOnlyError，讀取操作則可正常執行。

建構函式參數
「建構函式參數」的直接連結

files:

Files
已預先設定並繫結至所需 Adapter 與認證資訊的 FilesSDK Files 執行個體。

id?:

string
= Auto-generated
此檔案系統執行個體的唯一識別碼。

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」的直接連結

初始化檔案系統。確認已設定的 Adapter 能使用所提供的認證資訊列出鍵。

await filesystem.init()

getInfo()
「getinfo」的直接連結

傳回此檔案系統執行個體的中繼資料。

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

files
「files」的直接連結

底層 FilesSDK Files 執行個體會公開為屬性，供你直接呼叫 Adapter 專用 API。

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

物件儲存語意
「物件儲存語意」的直接連結

FilesSDKFilesystem 會將已設定的後端視為物件儲存，即使底層 Adapter 採用階層式結構（例如 fs）也是如此。這可讓各 Adapter 的行為保持一致：

  • mkdir 不執行任何操作。只要存在具有該前綴的鍵，就會隱含存在對應目錄。
  • exists 只有在完全相符的鍵以檔案形式存在，或該路徑是包含至少一個子鍵的前綴時，才會傳回 true。階層式 Adapter 上殘留的空目錄不算在內。
  • 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