> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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-TW/reference/workspace/s3-filesystem)，以及用於本機目錄的 [`LocalFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/local-filesystem)。

> **資訊:** 介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/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
```

設定 Platform 憑證。access 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` 是「讀取—修改—寫入」操作，並非原子性操作。同時對相同路徑附加內容可能會彼此覆寫。如果會同時寫入，請使用不同 key 呼叫 `writeFile`。

## 建構函式參數

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

**projectId** (`string`): Platform 專案 ID。若未提供，則使用 MASTRA\_PROJECT\_ID 環境變數。

**bucketName** (`string`): 用於儲存檔案的 Platform 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-TW/reference/workspace/platform-sandbox)
- [S3Filesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/s3-filesystem)
- [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/filesystem)