MesaFilesystem

透過標準 Mastra WorkspaceFilesystem 介面，將 Workspace 檔案儲存在 Mesa repo 中。

當 Agent 需要具版本控制的檔案儲存空間時，請使用 MesaFilesystem。本機目錄請使用 LocalFilesystem；物件儲存則請使用 S3Filesystem、GCSFilesystem 或 AzureBlobFilesystem。

資訊

MesaFilesystem 會在 Mastra 處理程序中執行。

Mesa 的 POSIX 掛載（用於在 Sandbox 中使用 Mesa 檔案系統）尚未納入 @mastra/mesa 套件，近期即將支援。

安裝

npm

npm install @mastra/mesa

pnpm

pnpm add @mastra/mesa

Yarn

yarn add @mastra/mesa

Bun

bun add @mastra/mesa

使用範例

掛載一個 Mesa repo，並將檔案系統傳給 Workspace：

src/mastra/workspace.ts

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { MesaFilesystem } from '@mastra/mesa'

const workspace = new Workspace({
  filesystem: new MesaFilesystem({
    apiKey: process.env.MESA_API_KEY,
    org: 'acme',
    repos: [{ name: 'docs', bookmark: 'main' }],
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

省略 apiKey 時，會改用 MESA_API_KEY。

建構函式參數

apiKey?:

string

Mesa API 金鑰。省略時會改用 MESA_API_KEY。

org?:

string

Mesa 組織 slug。省略時，Mesa SDK 會解析預設組織。

repos:

RepoConfig[]

要掛載的 Mesa repo。

cache?:

{ diskCache?: { path: string; maxSizeBytes?: number } }

Mesa 檔案系統快取設定。

ttl?:

number

Mesa 掛載 Token 的有效期限，單位為秒。

readOnly?:

boolean

= false

以唯讀模式掛載所有 repo。

屬性

id:

string

檔案系統執行個體識別碼。

name:

string

Provider 名稱（'MesaFilesystem'）。

provider:

string

Provider 識別碼（'mesa'）。

readOnly:

boolean | undefined

是否封鎖寫入操作。

client:

Mesa | undefined

此 Provider 建立的 Mesa SDK client。初始化前為 undefined。

filesystem:

MesaFileSystem

作用中的 Mesa 檔案系統。初始化後需要原始 Mesa SDK 檔案系統時，可存取此屬性。

change:

MesaFileSystem["change"]

已掛載檔案系統的 Mesa 變更管理操作。

bookmark:

MesaFileSystem["bookmark"]

已掛載檔案系統的 Mesa bookmark 管理操作。

方法

MesaFilesystem 實作 WorkspaceFilesystem 介面。

檔案操作

readFile(path, options?)

從 Mesa 讀取檔案。

const content = await filesystem.readFile('/acme/docs/README.md', {
  encoding: 'utf-8',
})

傳回值：Promise<string | Buffer>

writeFile(path, content, options?)

將檔案寫入 Mesa。

await filesystem.writeFile('/acme/docs/report.md', '# Report')

傳回值：Promise<void>

appendFile(path, content)

將內容附加至檔案。

await filesystem.appendFile('/acme/docs/log.txt', 'new line\n')

傳回值：Promise<void>

deleteFile(path, options?)

刪除檔案。

await filesystem.deleteFile('/acme/docs/old-report.md')

傳回值：Promise<void>

copyFile(src, dest, options?)

複製檔案。

await filesystem.copyFile('/acme/docs/report.md', '/acme/docs/archive/report.md')

傳回值：Promise<void>

moveFile(src, dest, options?)

移動檔案或重新命名。

await filesystem.moveFile('/acme/docs/draft.md', '/acme/docs/final.md')

傳回值：Promise<void>

目錄操作

mkdir(path, options?)

建立目錄。

await filesystem.mkdir('/acme/docs/reports', { recursive: true })

傳回值：Promise<void>

rmdir(path, options?)

移除目錄。

await filesystem.rmdir('/acme/docs/reports', { recursive: true })

傳回值：Promise<void>

readdir(path, options?)

列出目錄項目。

const entries = await filesystem.readdir('/acme/docs', {
  recursive: true,
  extension: '.md',
})

傳回值：Promise<FileEntry[]>

路徑操作

exists(path)

檢查路徑是否存在。

const exists = await filesystem.exists('/acme/docs/README.md')

傳回值：Promise<boolean>

stat(path)

傳回檔案或目錄的中繼資料。

const stat = await filesystem.stat('/acme/docs/README.md')

傳回值：Promise<FileStat>

realpath(path)

傳回 Mesa 的標準路徑。

const realPath = await filesystem.realpath('/acme/docs/README.md')

傳回值：Promise<string>

Mesa 操作

bash(options?)

為此檔案系統建立由 Mesa 支援的 Bash 執行環境。

const bash = await filesystem.bash({
  cwd: '/acme/docs',
})

傳回值：Promise<Bash>

路徑語意

方法需要絕對路徑。對 MesaFilesystem 而言，路徑以 Mesa 掛載點為根目錄，且必須包含組織 slug 和 repo 名稱：

await filesystem.readFile('/acme/docs/README.md')

請勿省略開頭斜線：

await filesystem.readFile('acme/docs/README.md') // Incorrect
await filesystem.readFile('/acme/docs/README.md') // Correct

組織取自建構函式中的 org；省略 org 時，則由 Mesa SDK 的預設組織推斷而來。它一律是第一個路徑區段。

掛載多個 repo 時，可在組織區段下存取各 repo：

const filesystem = new MesaFilesystem({
  org: 'acme',
  repos: [
    { name: 'docs', bookmark: 'main' },
    { name: 'website', bookmark: 'main' },
  ],
})

await filesystem.readFile('/acme/docs/README.md')
await filesystem.readFile('/acme/website/package.json')

Mesa 版本控制 API

存取底層 Mesa 檔案系統，以執行 Mesa 專用的變更和 bookmark 操作：

await filesystem.writeFile('/acme/docs/draft.md', 'Draft')

const current = await filesystem.change.current({
  repo: 'docs',
})

await filesystem.bookmark.move({
  repo: 'docs',
  name: 'main',
  changeId: current.changeId,
})

如需版本控制語意的更多詳細資訊，請參閱 Mesa 文件。

唯讀模式

設定 readOnly: true，即可封鎖透過 Mastra 執行的寫入操作：

const filesystem = new MesaFilesystem({
  repos: [{ name: 'docs', bookmark: 'main' }],
  readOnly: true,
})

讀取操作仍可正常執行。寫入操作會擲回 WorkspaceReadOnlyError。

並行操作

overwrite: false 和 expectedMtime 會在寫入前執行預先檢查。除非 Mesa 為 app 掛載加入原生條件式寫入功能，否則這些檢查不是原子操作。

相關內容

• WorkspaceFilesystem 介面
• 檔案系統文件
• Workspace 概觀
• Mesa 文件