跳至主要內容

FilesSDKFilesystem

將檔案儲存在 FilesSDK 支援的任何儲存後端：這是涵蓋 S3、Cloudflare R2、Google Cloud Storage、Azure Blob、Vercel Blob、MinIO、本機檔案系統等服務的統一抽象層。有關介面詳情，請參閱 WorkspaceFilesystem 介面。

如想使用單一配接器，以相同程式碼連接多個儲存後端，請使用 FilesSDKFilesystem。你可以更換底層驅動程式，而毋須更改 Workspace 設定。如果只連接一個後端，並想使用該後端的原生選項，則建議使用專用 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 配接器使用。只需更換驅動程式 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
在使用者介面顯示、方便閱讀的名稱。

icon?:

FilesystemIcon
使用者介面的圖示識別碼。

description?:

string
在使用者介面顯示的檔案系統簡短說明。

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

初始化檔案系統，並驗證已設定的配接器能否使用所提供的憑證列出 key。

await filesystem.init()

getInfo()
getinfo 的直接連結

傳回此檔案系統實例的中繼資料。

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

files
files 的直接連結

底層 FilesSDK Files 實例會公開為 public property，讓你在有需要時直接呼叫配接器專用 API。

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

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

即使底層配接器採用階層式結構（例如 fs），FilesSDKFilesystem 仍會將已設定的後端視為物件儲存。這可確保各配接器的行為一致：

  • mkdir 不會執行任何操作。當存在以某個 prefix 開頭的 key 時，目錄便會隱含存在。
  • exists 只有在檔案的確切 key 存在，或路徑是至少包含一個子 key 的 prefix 時，才會傳回 true。階層式配接器上殘留的空目錄不計算在內。
  • 如果 key 不存在，deleteFile 會拋出 FileNotFoundError，除非傳入 { force: true }。
  • 對目錄執行 deleteFile 時，會委派給 rmdir({ recursive: true })，其行為與 S3Filesystem 及 GCSFilesystem 相同。
  • moveFile 的實作方式是先執行 copyFile，再執行 deleteFile。此操作並非不可分割。如果複製成功後刪除來源失敗，目的地會保留，而來源不會被移除。
  • appendFile 是讀取、修改再寫入的操作。同時向同一個 key 附加內容可能互相覆寫。這是物件儲存的固有特性，並非 FilesSDK 特有。
  • readdir({ recursive: true }) 會輸出中間目錄項目（例如，輸出 a/b/c.txt 時亦會同時輸出 a/b）。
On this page