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

# FilesSDKFilesystem

將檔案儲存在 [FilesSDK](https://files-sdk.dev) 支援的任何儲存後端：這是涵蓋 S3、Cloudflare R2、Google Cloud Storage、Azure Blob、Vercel Blob、MinIO、本機檔案系統等服務的統一抽象層。有關介面詳情，請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)。

如想使用單一配接器，以相同程式碼連接多個儲存後端，請使用 `FilesSDKFilesystem`。你可以更換底層驅動程式，而毋須更改 Workspace 設定。如果只連接一個後端，並想使用該後端的原生選項，則建議使用專用 Provider（例如 [`S3Filesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/s3-filesystem) 或 [`GCSFilesystem`](https://mastra.zisheng.pro/zh-HK/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 配接器使用。只需更換驅動程式 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`): 在使用者介面顯示、方便閱讀的名稱。

**icon** (`FilesystemIcon`): 使用者介面的圖示識別碼。

**description** (`string`): 在使用者介面顯示的檔案系統簡短說明。

**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/zh-HK/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()`

初始化檔案系統，並驗證已設定的配接器能否使用所提供的憑證列出 key。

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

### `getInfo()`

傳回此檔案系統實例的中繼資料。

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

### `files`

底層 FilesSDK `Files` 實例會公開為 public property，讓你在有需要時直接呼叫配接器專用 API。

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

## 物件儲存語意

即使底層配接器採用階層式結構（例如 `fs`），`FilesSDKFilesystem` 仍會將已設定的後端視為物件儲存。這可確保各配接器的行為一致：

- **`mkdir`** 不會執行任何操作。當存在以某個 prefix 開頭的 key 時，目錄便會隱含存在。
- **`exists`** 只有在檔案的確切 key 存在，或路徑是至少包含一個子 key 的 prefix 時，才會傳回 `true`。階層式配接器上殘留的空目錄不計算在內。
- 如果 key 不存在，**`deleteFile`** 會拋出 `FileNotFoundError`，除非傳入 `{ force: true }`。
- 對目錄執行 **`deleteFile`** 時，會委派給 `rmdir({ recursive: true })`，其行為與 [`S3Filesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/s3-filesystem) 及 [`GCSFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/gcs-filesystem) 相同。
- **`moveFile`** 的實作方式是先執行 `copyFile`，再執行 `deleteFile`。此操作並非**不可分割**。如果複製成功後刪除來源失敗，目的地會保留，而來源不會被移除。
- **`appendFile`** 是讀取、修改再寫入的操作。同時向同一個 key 附加內容可能互相覆寫。這是物件儲存的固有特性，並非 FilesSDK 特有。
- **`readdir({ recursive: true })`** 會輸出中間目錄項目（例如，輸出 `a/b/c.txt` 時亦會同時輸出 `a/b`）。

## 相關內容

- [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)
- [S3Filesystem 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/s3-filesystem)
- [GCSFilesystem 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/gcs-filesystem)
- [AzureBlobFilesystem 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/azure-blob-filesystem)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)
- [FilesSDK 文件](https://files-sdk.dev)