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

# GoogleDriveFilesystem

將檔案儲存在單一 Google Drive 資料夾中。每個目錄都會對應至所設定根目錄下的一個 Drive 資料夾，而路徑則採用 POSIX 語意（例如 `/notes/todo.txt`）。有關介面詳情，請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)。

## 安裝

**npm**:

```bash
npm install @mastra/google-drive
```

**pnpm**:

```bash
pnpm add @mastra/google-drive
```

**Yarn**:

```bash
yarn add @mastra/google-drive
```

**Bun**:

```bash
bun add @mastra/google-drive
```

## 用法

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

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GoogleDriveFilesystem } from '@mastra/google-drive'

const workspace = new Workspace({
  filesystem: new GoogleDriveFilesystem({
    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
    accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
  }),
})

const agent = new Agent({
  id: 'drive-agent',
  name: 'Drive Agent',
  model: 'openai/gpt-5-mini',
  workspace,
})
```

### 驗證

提供以下其中一個驗證選項：

- **`accessToken`**：預先取得的 OAuth access token。請使用 `https://www.googleapis.com/auth/drive` scope，讓 token 能夠查看與已驗證身分共享的資料夾。
- **`getAccessToken`**：傳回 token 的 callback，適合在外部重新整理 token 時使用。
- **`serviceAccount`**：Google service account。請與 service account 電郵地址共享目標資料夾。

#### Service account

對後端 Agent 而言，建議使用 service account 驗證。此方式毋須使用者同意流程，亦毋須處理 token 重新整理。你只需要 service account JSON key 檔案中的**兩個值**：`client_email` 及 `private_key`。

##### 設定 service account

1. 開啟 [Google Cloud Console](https://console.cloud.google.com/)，然後選擇或建立項目。
2. 前往 **APIs & Services > Library**，搜尋 **Google Drive API**，然後選擇 **Enable**。
3. 前往 **APIs & Services > Credentials**，選擇 **Create credentials > Service account**，然後填妥表格。角色可以留空：Drive 權限是透過共享資料夾授予，而非 IAM 角色。
4. 開啟新的 service account，前往 **Keys** 分頁，然後選擇 **Add key > Create new key > JSON**。瀏覽器會下載 JSON key 檔案。
5. 從 JSON 檔案複製 `client_email` 值。你將使用此地址共享 Drive 資料夾。

##### 與 service account 共享 Drive 資料夾

Service account 是獨立的 Google 身分。在你明確與它共享內容之前，它無法查看 Drive 中的任何內容。

1. 在 [Google Drive](https://drive.google.com/) 開啟目標資料夾。
2. 選擇 **Share**。
3. 貼上 service account 的 `client_email` 地址。
4. 將角色設為 **Editor**（可讀寫）或 **Viewer**（唯讀存取），然後選擇 **Send**。
5. 從 URL 複製資料夾 ID。它是 `https://drive.google.com/drive/folders/<folderId>` 中 `/folders/` 之後的部分。

> **注意:** Service account 無法在標準「My Drive」資料夾中建立檔案。Service account 沒有個人 Drive 儲存配額，因此它建立的任何檔案都必須由具有配額的實體擁有。如果你只共享個人 Drive 資料夾，讀取操作可正常運作，但寫入會因配額錯誤而失敗。
>
> 如需寫入權限，請將資料夾放在**共用雲端硬碟**（前稱 Team Drive）內，並將 service account 加為該共用雲端硬碟的成員。共用雲端硬碟會提供 service account 所建立檔案需要的儲存配額。
>
> 對個人 Drive 資料夾執行唯讀工作負載則不受此限制。

##### 設定檔案系統

將 JSON 檔案中的 `client_email` 及 `private_key` 複製到你的環境：

```bash
GOOGLE_DRIVE_FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz
GOOGLE_DRIVE_CLIENT_EMAIL=my-bot@my-project.iam.gserviceaccount.com
# Wrap the value in quotes — the key contains newlines that must be preserved.
GOOGLE_DRIVE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkq...\n-----END PRIVATE KEY-----\n"
```

```typescript
import { GoogleDriveFilesystem } from '@mastra/google-drive'

const filesystem = new GoogleDriveFilesystem({
  folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
  serviceAccount: {
    clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
    privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
  },
})
```

你**毋須**複製整個 JSON 檔案，亦毋須傳入 `project_id`、`client_id`、`private_key_id` 或 `token_uri` 等其他欄位，因為這些欄位不會被使用。只有 `clientEmail` 及 `privateKey` 是必填項目；`privateKeyId`、`scopes` 及 `subject` 則為選填項目。`scopes` 預設為 `['https://www.googleapis.com/auth/drive']`，這是 service account 查看與其共享的資料夾所需的 scope。範圍較窄的 `drive.file` scope 只允許存取應用程式自行建立的檔案，因此與 service account 共享的資料夾會傳回 `404 Not Found`。

`GoogleDriveFilesystem` 會在簽署前自動將 `privateKey` 字串標準化。它會移除外層引號（包括以 JSON 包裝的值內已逸出的引號），並將字面值 `\n` 序列轉換為真正的換行。它亦會將 `\r\n` 換行符號標準化，並移除結尾逗號。無論你的 `.env` 載入器如何處理該值，key 都能正常運作。

##### 疑難排解

- **`404 File not found: <folderId>`**：Service account 無權存取該資料夾。請確認資料夾已與確切的 `client_email` 地址共享，且資料夾 ID 與 URL 相符。
- **寫入時出現 `storageQuotaExceeded`**：資料夾位於個人「My Drive」中。請將資料夾移至共用雲端硬碟，並將 service account 加為成員。
- **`error:1E08010C:DECODER routines::unsupported`**：`privateKey` 值格式錯誤。請確認該值包含完整 PEM block，且換行得以保留（字面值 `\n` 亦可）。

### 唯讀模式

傳入 `readOnly: true` 可封鎖寫入操作（`writeFile`、`appendFile`、`deleteFile`、`copyFile`、`moveFile`、`mkdir`、`rmdir`）。

```typescript
const filesystem = new GoogleDriveFilesystem({
  folderId,
  accessToken,
  readOnly: true,
})
```

## 建構函式參數

**folderId** (`string`): 作為 Workspace 根目錄的 Google Drive 資料夾 ID。所有路徑都會在此資料夾內解析。

**accessToken** (`string`): 有權存取該資料夾的 OAuth access token。

**getAccessToken** (`() => string | Promise<string>`): 傳回最新 OAuth access token 的 callback。每次有請求需要授權時都會呼叫。

**serviceAccount** (`{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }`): 透過 OAuth 2.0 JWT 流程產生 access token 所使用的 service account 憑證。

**id** (`string`): 此檔案系統實例的唯一識別碼 (Default: `` `google-drive:${folderId}` ``)

**readOnly** (`boolean`): 設為 true 時，所有寫入操作都會被封鎖。 (Default: `false`)

**instructions** (`InstructionsOption`): 覆寫傳回至 Tool 說明的預設指示。

## 屬性

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

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

**provider** (`string`): Provider 識別碼（'google-drive'）

**readOnly** (`boolean | undefined`): 檔案系統是否處於唯讀模式

## 方法

GoogleDriveFilesystem 實作了 [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?)` - 使用 Drive `files.copy` API 複製檔案
- `moveFile(src, dest, options?)` - 透過更換 parent，在資料夾之間移動檔案
- `mkdir(path, options?)` - 建立資料夾
- `rmdir(path, options?)` - 移除資料夾
- `readdir(path, options?)` - 列出資料夾內容（支援 `recursive` 及 `extension` 篩選）
- `stat(path)` - 傳回檔案或資料夾的 Drive 中繼資料
- `exists(path)` - 檢查檔案或資料夾是否存在

## 注意事項

- Google Drive 允許一個資料夾內有多個同名檔案。`GoogleDriveFilesystem` 會選取第一個相符項目來解析路徑，因此依賴路徑查找時，請確保每個資料夾內的名稱均為唯一。
- 當 `recursive` 未設定（預設值）或設為 `true` 時，`writeFile` 會自動建立上層資料夾。設為 `recursive: false` 則要求上層資料夾必須已經存在。
- 系統會遵從 `WriteOptions` 的 `expectedMtime`。當已儲存的 `modifiedTime` 不同時，寫入會遭 `StaleFileError` 拒絕，以支援樂觀並行控制。
- 此 Provider 只會透過內置 `fetch` 呼叫 Drive REST endpoint（`https://www.googleapis.com/drive/v3` 及 `https://www.googleapis.com/upload/drive/v3`），毋須其他 dependency。