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 org slug。省略时，Mesa SDK 会解析默认 org。

repos:

RepoConfig[]

要挂载的 Mesa repo。

cache?:

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

Mesa 文件系统缓存配置。

ttl?:

number

Mesa 挂载令牌的有效期（秒）。

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 change 管理操作。

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 runtime。

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

返回：Promise<Bash>

路径语义

方法要求使用绝对路径。对于 MesaFilesystem，路径以 Mesa 挂载点为根，并且必须包含 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。它始终是路径的第一个部分。

挂载多个 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 特有的 change 和 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 为应用挂载添加原生条件写入功能，否则这些检查不具备原子性。

相关内容

• WorkspaceFilesystem 接口
• 文件系统文档
• Workspace 概览
• Mesa 文档