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

# MesaFilesystem

透過標準 Mastra `WorkspaceFilesystem` 介面，將 Workspace 檔案儲存在 [Mesa](https://docs.mesa.dev/content/getting-started/introduction) repo。

當 Agent 需要版本化檔案儲存空間時，請使用 `MesaFilesystem`。本機目錄請使用 [`LocalFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/local-filesystem)。物件儲存空間請使用 [`S3Filesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/s3-filesystem)、[`GCSFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/gcs-filesystem) 或 [`AzureBlobFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/azure-blob-filesystem)。

> **資訊:** `MesaFilesystem` 在 Mastra 程序中執行。
>
> [Mesa 的 POSIX mount](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
```

## 用法範例

Mount 一個 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 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`): 以唯讀方式 mount 所有 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"]`): 已 mount 檔案系統的 Mesa 變更管理操作。

**bookmark** (`MesaFileSystem["bookmark"]`): 已 mount 檔案系統的 Mesa bookmark 管理操作。

## 方法

`MesaFilesystem` 會實作 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/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 mount 為根目錄，並必須包括 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 推斷。它仍會是路徑的第一個部分。

Mount 多個 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 特有的變更及 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 為 app mount 加入原生條件式寫入功能，否則這些檢查不具原子性。

## 相關內容

- [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)
- [檔案系統文件](https://mastra.zisheng.pro/zh-HK/docs/workspace/filesystem)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)
- [Mesa 文件](https://docs.mesa.dev/content/getting-started/introduction)