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

# FilesSDKFilesystem

将文件存储在 [FilesSDK](https://files-sdk.dev) 支持的任意存储后端中。FilesSDK 对 S3、Cloudflare R2、Google Cloud Storage、Azure Blob、Vercel Blob、MinIO、本地文件系统等提供了统一抽象。有关接口详情，请参阅 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)。

如果希望用同一套代码对接多个存储后端，请使用 `FilesSDKFilesystem`。无需更改 Workspace 设置，只需替换底层 driver 即可切换后端。如果只针对一个后端，并希望使用该后端的一等配置选项，建议使用专用 Provider（例如 [`S3Filesystem`](https://mastra.zisheng.pro/reference/workspace/s3-filesystem) 或 [`GCSFilesystem`](https://mastra.zisheng.pro/reference/workspace/gcs-filesystem)）。

## 安装

**npm**:

```bash
npm install @mastra/files-sdk files-sdk
```

**pnpm**:

```bash
pnpm add @mastra/files-sdk files-sdk
```

**Yarn**:

```bash
yarn add @mastra/files-sdk files-sdk
```

**Bun**:

```bash
bun add @mastra/files-sdk files-sdk
```

`files-sdk` 是 peer dependency，需要使用所选适配器对其进行配置。

## 用法

使用所选适配器创建 FilesSDK `Files` 实例，然后将其传给 `FilesSDKFilesystem`：

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { FilesSDKFilesystem } from '@mastra/files-sdk'
import { Files } from 'files-sdk'
import { s3 } from 'files-sdk/s3'

const files = new Files({
  adapter: s3({
    bucket: 'my-bucket',
    region: 'us-east-1',
  }),
})

const workspace = new Workspace({
  filesystem: new FilesSDKFilesystem({ files }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

### 更换适配器

同一个 `FilesSDKFilesystem` 可以与任意 FilesSDK 适配器配合使用。替换 driver factory 即可切换后端：

```typescript
import { Files } from 'files-sdk'
import { r2 } from 'files-sdk/r2'
import { gcs } from 'files-sdk/gcs'
import { azure } from 'files-sdk/azure'
import { fs } from 'files-sdk/fs'

// Cloudflare R2
const r2Files = new Files({ adapter: r2({ accountId, bucket, accessKeyId, secretAccessKey }) })

// Google Cloud Storage
const gcsFiles = new Files({ adapter: gcs({ bucket, projectId }) })

// Azure Blob
const azureFiles = new Files({ adapter: azure({ container, connectionString }) })

// Local filesystem (useful for tests and development)
const localFiles = new Files({ adapter: fs({ root: './workspace' }) })
```

如需完整的适配器目录和配置选项，请参阅 [FilesSDK 文档](https://files-sdk.dev)。

### 只读挂载

```typescript
const filesystem = new FilesSDKFilesystem({
  files,
  readOnly: true,
})
```

所有写入操作（`writeFile`、`appendFile`、`deleteFile`、`copyFile`、`moveFile`、`mkdir`、`rmdir`）都会抛出 `WorkspaceReadOnlyError`，读取操作则可正常执行。

## 构造函数参数

**files** (`Files`): 预先配置的 FilesSDK Files 实例，已绑定要使用的适配器和凭据。

**id** (`string`): 此文件系统实例的唯一标识符。 (Default: `自动生成`)

**displayName** (`string`): 在 UI 中显示的易读名称。

**icon** (`FilesystemIcon`): UI 中使用的图标标识符。

**description** (`string`): 在 UI 中显示的此文件系统的简短说明。

**readOnly** (`boolean`): 设为 true 时，所有写入操作都会被阻止。 (Default: `false`)

## 属性

**id** (`string`): 文件系统实例标识符。

**name** (`string`): Provider 名称（'FilesSDKFilesystem'）。

**provider** (`string`): Provider 标识符（'files-sdk'）。

**readOnly** (`boolean | undefined`): 文件系统是否处于只读模式。

## 方法

`FilesSDKFilesystem` 实现了 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)，提供所有标准文件系统方法：

- `readFile(path, options?)` - 读取文件内容
- `writeFile(path, content, options?)` - 将内容写入文件
- `appendFile(path, content)` - 将内容追加到文件
- `deleteFile(path, options?)` - 删除文件
- `copyFile(src, dest, options?)` - 复制文件
- `moveFile(src, dest, options?)` - 移动文件或重命名
- `mkdir(path, options?)` - 创建目录（对于对象存储不执行任何操作）
- `rmdir(path, options?)` - 删除目录
- `readdir(path, options?)` - 列出目录内容
- `exists(path)` - 检查路径是否存在
- `stat(path)` - 获取文件或目录元数据

### `init()`

初始化文件系统。验证已配置的适配器能否使用所提供的凭据列出键。

```typescript
await filesystem.init()
```

### `getInfo()`

返回此文件系统实例的元数据。

```typescript
const info = filesystem.getInfo()
// { id: '...', name: 'FilesSDKFilesystem', provider: 'files-sdk', status: 'ready' }
```

### `files`

底层 FilesSDK `Files` 实例以公共属性形式公开，便于在需要时直接调用特定于适配器的 API。

```typescript
const url = await filesystem.files.url('reports/q3.pdf')
```

## 对象存储语义

`FilesSDKFilesystem` 会将配置的后端视为对象存储，即使底层适配器具有层级结构（例如 `fs`）也是如此。这样可确保不同适配器的行为一致：

- **`mkdir`** 不执行任何操作。当存在以某个前缀开头的键时，对应目录便隐式存在。
- **`exists`** 仅在存在完全匹配的文件键，或路径是至少包含一个子键的前缀时返回 `true`。层级适配器中遗留的空目录不算在内。
- 当键不存在时，**`deleteFile`** 会抛出 `FileNotFoundError`，除非传入 `{ force: true }`。
- 对目录调用 **`deleteFile`** 会委托给 `rmdir({ recursive: true })`，行为与 [`S3Filesystem`](https://mastra.zisheng.pro/reference/workspace/s3-filesystem) 和 [`GCSFilesystem`](https://mastra.zisheng.pro/reference/workspace/gcs-filesystem) 一致。
- **`moveFile`** 通过先执行 `copyFile`，再执行 `deleteFile` 来实现。此操作**不具备原子性**。如果复制成功后删除源文件失败，目标文件会保留，源文件也不会被移除。
- **`appendFile`** 是读取-修改-写入操作。并发追加同一个键时可能相互覆盖。这是对象存储的固有特性，并非 FilesSDK 特有。
- **`readdir({ recursive: true })`** 会生成中间目录条目（例如，除 `a/b/c.txt` 外还会生成 `a/b`）。

## 相关内容

- [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)
- [S3Filesystem 参考](https://mastra.zisheng.pro/reference/workspace/s3-filesystem)
- [GCSFilesystem 参考](https://mastra.zisheng.pro/reference/workspace/gcs-filesystem)
- [AzureBlobFilesystem 参考](https://mastra.zisheng.pro/reference/workspace/azure-blob-filesystem)
- [Workspace 概览](https://mastra.zisheng.pro/docs/workspace/overview)
- [FilesSDK 文档](https://files-sdk.dev)