> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# MesaFilesystem

通过标准 Mastra `WorkspaceFilesystem` 接口，将 Workspace 文件存储在 [Mesa](https://docs.mesa.dev/content/getting-started/introduction) repo 中。

当 Agent 需要版本化文件存储时，请使用 `MesaFilesystem`。对于本地目录，请使用 [`LocalFilesystem`](https://mastra.zisheng.pro/reference/workspace/local-filesystem)。对于对象存储，请使用 [`S3Filesystem`](https://mastra.zisheng.pro/reference/workspace/s3-filesystem)、[`GCSFilesystem`](https://mastra.zisheng.pro/reference/workspace/gcs-filesystem) 或 [`AzureBlobFilesystem`](https://mastra.zisheng.pro/reference/workspace/azure-blob-filesystem)。

> **信息:** `MesaFilesystem` 在 Mastra 进程中运行。
>
> [Mesa 的 POSIX 挂载](https://docs.mesa.dev/content/mesafs/posix-mount)（用于在 Sandbox 中使用 Mesa 文件系统）尚未包含在 `@mastra/mesa` 包中。相关支持即将推出。

## 安装

**npm**:

```bash
npm install @mastra/mesa
```

**pnpm**:

```bash
pnpm add @mastra/mesa
```

**Yarn**:

```bash
yarn add @mastra/mesa
```

**Bun**:

```bash
bun add @mastra/mesa
```

## 用法示例

挂载一个 Mesa repo，并将文件系统传给 Workspace：

```typescript
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`): 以只读方式挂载所有 repo。 (Default: `false`)

## 属性

**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 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)。

### 文件操作

#### `readFile(path, options?)`

从 Mesa 读取文件。

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

返回：`Promise<string | Buffer>`

#### `writeFile(path, content, options?)`

将文件写入 Mesa。

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

返回：`Promise<void>`

#### `appendFile(path, content)`

向文件追加内容。

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

返回：`Promise<void>`

#### `deleteFile(path, options?)`

删除文件。

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

返回：`Promise<void>`

#### `copyFile(src, dest, options?)`

复制文件。

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

返回：`Promise<void>`

#### `moveFile(src, dest, options?)`

移动文件或重命名。

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

返回：`Promise<void>`

### 目录操作

#### `mkdir(path, options?)`

创建目录。

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

返回：`Promise<void>`

#### `rmdir(path, options?)`

删除目录。

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

返回：`Promise<void>`

#### `readdir(path, options?)`

列出目录条目。

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

返回：`Promise<FileEntry[]>`

### 路径操作

#### `exists(path)`

检查路径是否存在。

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

返回：`Promise<boolean>`

#### `stat(path)`

返回文件或目录元数据。

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

返回：`Promise<FileStat>`

#### `realpath(path)`

返回 Mesa 中的规范路径。

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

返回：`Promise<string>`

### Mesa 操作

#### `bash(options?)`

为此文件系统创建由 Mesa 支持的 Bash runtime。

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

返回：`Promise<Bash>`

## 路径语义

方法要求使用绝对路径。对于 `MesaFilesystem`，路径以 Mesa 挂载点为根，并且必须包含 org slug 和 repo 名称：

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

不要省略开头的斜杠：

```typescript
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 路径段下访问：

```typescript
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 操作：

```typescript
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 文档](https://docs.mesa.dev/content/concepts/versioning)。

## 只读模式

设置 `readOnly: true` 可阻止通过 Mastra 执行写入操作：

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

读取操作仍可正常执行。写入操作会抛出 `WorkspaceReadOnlyError`。

## 并发

`overwrite: false` 和 `expectedMtime` 会在写入前执行预检查。除非 Mesa 为应用挂载添加原生条件写入功能，否则这些检查不具备原子性。

## 相关内容

- [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)
- [文件系统文档](https://mastra.zisheng.pro/docs/workspace/filesystem)
- [Workspace 概览](https://mastra.zisheng.pro/docs/workspace/overview)
- [Mesa 文档](https://docs.mesa.dev/content/getting-started/introduction)