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

# PlatformFilesystem

将文件存储在 Mastra Platform Workspace 存储桶中。每个 Mastra Platform 环境都可以有一个存储桶，`PlatformFilesystem` 可让 Agent 对其执行 `read`、`write`、`list`、`delete` 和 `move` 操作。

相关 Provider：用于直接访问 S3 的 [`S3Filesystem`](https://mastra.zisheng.pro/reference/workspace/s3-filesystem)，以及用于本地目录的 [`LocalFilesystem`](https://mastra.zisheng.pro/reference/workspace/local-filesystem)。

> **信息:** 有关接口的详细信息，请参阅 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/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 凭据。访问令牌、项目 ID 和存储桶名称会回退到环境变量，因此 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 令牌。

## 用法

将 `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,
})
```

### 读取和写入文件

对象键会逐段进行百分号编码，因此包含 `?`、`#`、`%`、`&`、`+` 或空格的文件名可以在整个流程中保持不变：

```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` 以只读方式挂载存储桶。任何修改调用都会抛出 `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` 写入不同的键。

## 构造函数参数

**accessToken** (`string`): Platform 访问令牌。回退到 MASTRA\_PLATFORM\_ACCESS\_TOKEN 环境变量。

**projectId** (`string`): Platform 项目 ID。回退到 MASTRA\_PROJECT\_ID 环境变量。

**bucketName** (`string`): 用于存储文件的 Platform 存储桶名称。回退到 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 时（例如负载均衡器返回的 HTML 502），`code` 和 `proxyMessage` 为 `undefined`。

## 相关内容

- [PlatformSandbox 参考](https://mastra.zisheng.pro/reference/workspace/platform-sandbox)
- [S3Filesystem 参考](https://mastra.zisheng.pro/reference/workspace/s3-filesystem)
- [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)