MesaFilesystem

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

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

資訊

MesaFilesystem 在 Mastra 程序中執行。

Mesa 的 POSIX mount（用於在 Sandbox 內使用 Mesa 檔案系統）尚未包含在 @mastra/mesa 套件中。即將提供支援。

安裝

npm

npm install @mastra/mesa

pnpm

pnpm add @mastra/mesa

Yarn

yarn add @mastra/mesa

Bun

bun add @mastra/mesa

用法範例

Mount 一個 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 key。省略時會後備使用 MESA_API_KEY。

org?:

string

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

repos:

RepoConfig[]

要 mount 的 Mesa repo。

cache?:

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

Mesa 檔案系統快取設定。

ttl?:

number

Mesa mount token 的有效期（秒）。

readOnly?:

boolean

= false

以唯讀方式 mount 所有 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"]

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

bookmark:

MesaFileSystem["bookmark"]

已 mount 檔案系統的 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 runtime。

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

傳回：Promise<Bash>

路徑語意

方法需要使用絕對路徑。對於 MesaFilesystem，路徑以 Mesa mount 為根目錄，並必須包括 org 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；如省略 org，則來自 Mesa SDK 的預設 org 推斷。它仍會是路徑的第一個部分。

Mount 多個 repo 時，每個 repo 都可在 org 部分下使用：

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 mount 加入原生條件式寫入功能，否則這些檢查不具原子性。

相關內容

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