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

# MesaFilesystem

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

當 Agent 需要具版本控制的檔案儲存空間時，請使用 `MesaFilesystem`。本機目錄請使用 [`LocalFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/local-filesystem)；物件儲存則請使用 [`S3Filesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/s3-filesystem)、[`GCSFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/gcs-filesystem) 或 [`AzureBlobFilesystem`](https://mastra.zisheng.pro/zh-TW/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 組織 slug。省略時，Mesa SDK 會解析預設組織。

**repos** (`RepoConfig[]`): 要掛載的 Mesa repo。

**cache** (`{ diskCache?: { path: string; maxSizeBytes?: number } }`): Mesa 檔案系統快取設定。

**ttl** (`number`): Mesa 掛載 Token 的有效期限，單位為秒。

**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 變更管理操作。

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

## 方法

`MesaFilesystem` 實作 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/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 執行環境。

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

傳回值：`Promise<Bash>`

## 路徑語意

方法需要絕對路徑。對 `MesaFilesystem` 而言，路徑以 Mesa 掛載點為根目錄，且必須包含組織 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` 時，則由 Mesa SDK 的預設組織推斷而來。它一律是第一個路徑區段。

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

```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 掛載加入原生條件式寫入功能，否則這些檢查不是原子操作。

## 相關內容

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