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

# PlatformFilesystem

將檔案儲存在 Mastra Platform Workspace bucket 中。每個 Mastra Platform 環境可以有一個 bucket，而 `PlatformFilesystem` 可讓 Agent 對其執行 `read`、`write`、`list`、`delete` 及 `move` 操作。

相關 Provider：用於直接存取 S3 的 [`S3Filesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/s3-filesystem)，以及用於本機目錄的 [`LocalFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/local-filesystem)。

> **資訊:** 有關介面詳情，請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)。

## 安裝

**npm**:

```bash
npm install @mastra/platform-workspace
```

**pnpm**:

```bash
pnpm add @mastra/platform-workspace
```

**Yarn**:

```bash
yarn add @mastra/platform-workspace
```

**Bun**:

```bash
bun add @mastra/platform-workspace
```

設定平台憑證。存取 token、項目 ID 及 bucket 名稱會使用環境變數作為後備值，因此 Mastra Platform 部署可在不傳入任何建構函式選項的情況下運作。

**.env 檔案**:

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
```

**建構函式**:

```typescript
new PlatformFilesystem({
  accessToken: 'your-platform-access-token',
  projectId: 'your-project-id',
  bucketName: 'your-bucket-name',
})
```

在 Mastra Platform 部署中，系統會自動注入 `MASTRA_PLATFORM_ACCESS_TOKEN`、`MASTRA_PROJECT_ID` 及 `MASTRA_PLATFORM_BUCKET_NAME`，因此呼叫建構函式時可不傳入任何選項。進行本機開發時，`MASTRA_PLATFORM_ACCESS_TOKEN` 可使用你機構設定頁面中 **API Tokens** 下的 `sk_` API token。

## 用法

將 `PlatformFilesystem` 加入 Workspace，並指派給 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem } from '@mastra/platform-workspace'

const workspace = new Workspace({
  filesystem: new PlatformFilesystem({
    // accessToken, projectId, bucketName all fall back to env vars
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'File Agent',
  instructions: 'You are a research assistant that reads and writes reports.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})
```

### 讀取及寫入檔案

物件 key 會逐段進行百分號編碼，因此檔案名稱中的 `?`、`#`、`%`、`&`、`+` 或空格都會從頭到尾獲得保留：

```typescript
const fs = new PlatformFilesystem()

await fs.writeFile('/analyses/repo.md', markdown)
const content = await fs.readFile('/analyses/repo.md')
const entries = await fs.readdir('/analyses')
await fs.moveFile('/analyses/repo.md', '/analyses/repo-final.md')
```

### 唯讀模式

傳入 `readOnly: true`，以唯讀方式掛載 bucket。任何修改資料的呼叫都會拋出 `WorkspaceReadOnlyError`：

```typescript
const fs = new PlatformFilesystem({ readOnly: true })

await fs.readFile('/analyses/repo.md') // ok
await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError
```

### 覆寫語義

`writeFile` 支援 `overwrite: false`；如果目的地已存在，便會拋出 `FileExistsError`。

`copyFile` 及 `moveFile` 一律會覆寫目的地。向其中任何一個方法傳入 `overwrite: false` 時，系統會拋出錯誤，而不會靜默覆寫。

### 附加檔案內容

`appendFile` 是讀取、修改再寫入的操作，並非不可分割操作。同時向相同路徑附加內容時，操作之間可能互相覆寫。如有多個並行寫入者，請使用 `writeFile` 並分別指定不同 key。

## 建構函式參數

**accessToken** (`string`): 平台存取 token。若未提供，則使用 MASTRA\_PLATFORM\_ACCESS\_TOKEN 環境變數。

**projectId** (`string`): 平台項目 ID。若未提供，則使用 MASTRA\_PROJECT\_ID 環境變數。

**bucketName** (`string`): 用於儲存檔案的平台 bucket 名稱。若未提供，則使用 MASTRA\_PLATFORM\_BUCKET\_NAME 環境變數。

**readOnly** (`boolean`): 若為 true，所有修改資料的呼叫都會拋出 WorkspaceReadOnlyError。 (Default: `false`)

**displayName** (`string`): 在 Workspace UI 中顯示、方便使用者理解的名稱。

**description** (`string`): 在 Workspace UI 中顯示的簡短說明。

**icon** (`FilesystemIcon`): 在 Workspace UI 中顯示的圖示。

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): 由 getInstructions() 傳回的自訂指示。字串會完全取代預設值；函式會接收預設值，並可按每次請求擴充或自訂這些值。

**id** (`string`): 此檔案系統實例的唯一識別碼。 (Default: `自動產生`)

**fetch** (`typeof fetch`): 自訂 fetch 實作，主要用於測試。

## 屬性

**id** (`string`): 檔案系統實例識別碼。

**name** (`string`): Provider 名稱（'PlatformFilesystem'）。

**provider** (`string`): Provider 識別碼（'platform'）。

**readOnly** (`boolean | undefined`): 檔案系統是否以唯讀方式掛載。

## 錯誤

檔案系統特定錯誤與標準 Workspace 錯誤類型一致：

- `FileNotFoundError`：路徑不存在。由 `readFile`、`stat` 及 `deleteFile` 拋出（除非已設定 `force: true`）。
- `FileExistsError`：呼叫 `writeFile` 時傳入了 `overwrite: false`，而目的地已存在。
- `WorkspaceReadOnlyError`：在唯讀檔案系統上進行了修改資料的呼叫。

其他 Platform API 失敗會引發 `PlatformApiError`。結構化的 `{ error: { message, type } }` 回應會解析為 `.code`（機器可讀的類別）及 `.proxyMessage`（供使用者閱讀的字串）：

```typescript
import { FileNotFoundError } from '@mastra/core/workspace'
import { PlatformApiError } from '@mastra/platform-workspace'

try {
  await fs.readFile('/missing.txt')
} catch (err) {
  if (err instanceof FileNotFoundError) {
    // handle missing file
  } else if (err instanceof PlatformApiError) {
    if (err.code === 'authentication_error') {
      // refresh token
    }
    console.error(err.status, err.code, err.proxyMessage)
  }
}
```

`FileNotFoundError`、`FileExistsError` 及 `WorkspaceReadOnlyError` 是從 `@mastra/core/workspace` 重新匯出的標準 Workspace 錯誤類型。`PlatformApiError` 則是 `@mastra/platform-workspace` 特有的錯誤類型。

當回應本文並非 JSON 時，`code` 及 `proxyMessage` 會是 `undefined`，例如負載平衡器傳回的 HTML 502 回應。

## 相關內容

- [PlatformSandbox 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/platform-sandbox)
- [S3Filesystem 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/s3-filesystem)
- [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)