檔案系統

新增於： @mastra/core@1.1.0

檔案系統 Provider 讓 Agent 能讀取、寫入及管理檔案。在 Workspace 上設定檔案系統後，Agent 會取得檔案操作 Tool。

檔案系統 Provider 會處理 Workspace 的所有檔案操作：

• 讀取 - 讀取檔案內容
• 寫入 - 建立及更新檔案
• 列出 - 瀏覽目錄，並可選擇使用 glob 模式篩選
• 刪除 - 移除檔案與目錄
• Stat - 取得檔案中繼資料
• 複製／移動 - 在不同位置間複製或移動檔案
• Grep - 使用規則運算式模式搜尋檔案內容

支援的 Provider

可用的 Provider：

• LocalFilesystem：將檔案儲存在磁碟目錄中
• S3Filesystem：將檔案儲存在 Amazon S3 或 S3 相容儲存空間（R2、MinIO、Tigris）
• GCSFilesystem：將檔案儲存在 Google Cloud Storage
• PlatformFilesystem：將檔案儲存在 Mastra Platform Workspace Bucket
• GoogleDriveFilesystem：將檔案儲存在 Google Drive 資料夾內
• AzureBlobFilesystem：將檔案儲存在 Azure Blob Storage
• FilesSDKFilesystem：將檔案儲存在任何 FilesSDK Adapter（S3、R2、GCS、Azure Blob、Vercel Blob、本機檔案系統等）；適合以單一 Provider 對接多種後端
• AgentFSFilesystem：透過 AgentFS 將檔案儲存在 Turso/SQLite 資料庫中
• MesaFilesystem：將檔案儲存在具有版本控制的 Mesa Repo 中
• ArchilFilesystem：將檔案儲存在 Archil 彈性無伺服器磁碟中

提示

LocalFilesystem 不需要外部服務，是最簡單的入門方式。雲端儲存空間可使用 S3Filesystem、GCSFilesystem 或 AzureBlobFilesystem；版本化儲存空間可使用 MesaFilesystem；不依賴外部服務的資料庫型儲存空間可使用 AgentFSFilesystem。

基本用法

建立含檔案系統的 Workspace，並將它指派給 Agent。Agent 隨後便能在執行任務時讀取、寫入及管理檔案：

src/mastra/agents/file-agent.ts

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a helpful file management assistant.',
  workspace,
})

// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace')

範圍限制

LocalFilesystem 預設會在受限模式下執行，所有檔案操作都限制在 basePath 內。這能防止路徑遍歷攻擊與 symlink 逸出。

在受限模式中：

• 相對路徑（例如 src/index.ts）會以 basePath 為基準解析
• 絕對路徑（例如 /home/user/.config/file.txt）會視為真實檔案系統路徑；若落在 basePath 與任何 allowedPaths 之外，便會擲回 PermissionError
• 波浪號路徑（例如 ~/Documents）會展開至家目錄，並遵循相同的範圍限制規則

如果 Agent 需要存取 basePath 之外的特定路徑，請使用 allowedPaths 授予權限，而不必完全停用範圍限制。相對路徑會以 basePath 為基準解析，絕對路徑則保持原樣：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    allowedPaths: ['~/.claude/skills', '../shared-data'],
  }),
})

可在執行階段使用 setAllowedPaths() 方法更新允許的路徑：

// Add a path dynamically
workspace.filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])

這是實現最低權限存取的建議方式，Agent 只能前往你明確允許的目錄。

如果 Agent 需要不受限制地存取整個檔案系統，請停用範圍限制：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    contained: false,
  }),
})

當 contained 為 false 時，絕對路徑會視為不受限制的真實檔案系統路徑。

動態檔案系統

filesystem 選項除了靜態執行個體，也接受解析器函式。解析器會接收 requestContext，並為每個請求傳回一個檔案系統，讓單一 Workspace 能依呼叫端的身分、角色或租戶使用不同檔案系統。

src/mastra/workspaces.ts

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: ({ requestContext }) => {
    const role = requestContext.get('agent-role') || 'guest'
    return new LocalFilesystem({
      basePath: `/workspaces/${role}`,
      readOnly: role !== 'admin',
    })
  },
})

const agent = new Agent({
  id: 'multi-role-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})

每個請求都會為 Workspace Tool 與 Workspace 指示解析自己的檔案系統：

import { RequestContext } from '@mastra/core/request-context'

// Admin request — reads and writes from /workspaces/admin/
const adminCtx = new RequestContext([['agent-role', 'admin']])
await agent.generate('Write report.txt with Q4 results', { requestContext: adminCtx })

// Viewer request — reads from /workspaces/viewer/, writes are blocked
const viewerCtx = new RequestContext([['agent-role', 'viewer']])
await agent.generate('Read info.txt', { requestContext: viewerCtx })

Workspace 指示會使用相同的 requestContext，因此 Agent 能看見已解析 Provider 的檔案系統情境。

解析器也可以是非同步函式，例如從資料庫查詢設定：

const workspace = new Workspace({
  filesystem: async ({ requestContext }) => {
    const tenantConfig = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalFilesystem({ basePath: tenantConfig.storagePath })
  },
})

備註

filesystem 與 mounts 互斥。同一個 Workspace 中不能同時使用解析器函式與 mounts。

唯讀模式

若要防止 Agent 修改檔案，請啟用唯讀模式：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    readOnly: true,
  }),
})

使用靜態檔案系統時，寫入 Tool（write_file、edit_file、delete、mkdir）會完全排除在 Agent 的 Tool 集合之外。Agent 仍可讀取及列出檔案。

使用動態檔案系統時，由於解析器執行前無法得知 readOnly，因此寫入 Tool 一律會包含在內。寫入操作改在執行階段遭到阻擋；若解析出的檔案系統為唯讀，Tool 便會傳回錯誤。

掛載與 CompositeFilesystem

在 Workspace 上使用 mounts 選項時，Mastra 會建立 CompositeFilesystem，依路徑前綴將檔案操作路由至正確的 Provider。

import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/skills': new GCSFilesystem({
      bucket: 'agent-skills',
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

採用此設定後：

• read_file('/data/input.csv') 會從 S3 Bucket 讀取
• write_file('/skills/guide.md', content) 會寫入 GCS Bucket
• list_directory('/') 會傳回 /data 與 /skills 的虛擬項目
• Sandbox 中的命令可透過 FUSE 掛載存取 /data 與 /skills 的檔案

路徑路由

所有檔案路徑都必須以掛載前綴開頭，因為路徑不符合任何掛載點時操作會失敗。列出根目錄（/）會傳回各掛載點的虛擬目錄項目。

掛載路徑不能巢狀，例如不能同時掛載 /data 與 /data/sub。

filesystem 與 mounts 的比較

filesystem 與 mounts 是 Workspace 上互斥的選項：

• 只有單一儲存空間 Provider，且不需要將其掛載至 Sandbox 時，請使用 filesystem。Agent 會取得直接操作該 Provider 的檔案 Tool。
• 需要在 Sandbox 中存取雲端儲存空間，或要合併多個 Provider 時，請使用 mounts。Workspace 會為檔案 Tool 建立 CompositeFilesystem，並透過 FUSE 將儲存空間掛載至 Sandbox。

進行本機開發時通常不需要 mounts；讓 LocalFilesystem 與 LocalSandbox 指向同一目錄，即可對相同檔案同時使用檔案 Tool 與命令執行功能。詳情請參閱設定模式。

Agent Tool

在 Workspace 上設定檔案系統後，Agent 會取得讀取、寫入、列出及刪除檔案的 Tool。詳情請參閱 Workspace 類別參考。

相關資源

• LocalFilesystem 參考
• S3Filesystem 參考
• GCSFilesystem 參考
• GoogleDriveFilesystem 參考
• AzureBlobFilesystem 參考
• FilesSDKFilesystem 參考
• AgentFSFilesystem 參考
• MesaFilesystem 參考
• Workspace 概觀
• Sandbox