跳到主要内容

GoogleDriveFilesystem

将文件存储在单个 Google Drive 文件夹中。每个目录都会映射到已配置根目录下的一个 Drive 文件夹，路径遵循 POSIX 语义（例如 /notes/todo.txt）。有关接口详情，请参阅 WorkspaceFilesystem 接口。

安装
安装的直接链接

npm install @mastra/google-drive

用法
用法的直接链接

将 GoogleDriveFilesystem 添加到 Workspace，并将其分配给 Agent：

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，以便令牌能够查看与已验证身份共享的文件夹。
  • getAccessToken：返回令牌的回调。适用于在外部刷新令牌的情况。
  • serviceAccount：Google service account。请与该 service account 的电子邮件地址共享目标文件夹。

Service account
Service account的直接链接

对于后端 Agent，推荐使用 service account 身份验证。它不需要用户授权流程，也不需要处理令牌刷新。你只需从 service account JSON 密钥文件中获取两个值：client_email 和 private_key。

设置 service account
设置 service account的直接链接
  1. 打开 Google Cloud Console，选择或创建一个项目。
  2. 前往 APIs & Services > Library，搜索 Google Drive API，然后选择 Enable。
  3. 前往 APIs & Services > Credentials，选择 Create credentials > Service account 并填写表单。role 可以留空：Drive 权限通过共享文件夹授予，而非通过 IAM role 授予。
  4. 打开新建的 service account，前往 Keys 标签页，然后选择 Add key > Create new key > JSON。浏览器会下载一个 JSON 密钥文件。
  5. 从 JSON 文件中复制 client_email 值。该地址就是共享 Drive 文件夹时要使用的地址。
与 service account 共享 Drive 文件夹
与 service account 共享 Drive 文件夹的直接链接

Service account 本身是一个独立的 Google 身份。在你显式与其共享内容之前，它无法看到 Drive 中的任何内容。

  1. 在 Google Drive 中打开目标文件夹。
  2. 选择 Share。
  3. 粘贴 service account 的 client_email 地址。
  4. 将 role 设置为 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 复制到环境变量中：

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"
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 加载器如何处理该值，密钥都能正常使用。

故障排除
故障排除的直接链接
  • 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）。

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 的回调。每个需要授权的请求都会调用它。

serviceAccount?:

{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }
通过 OAuth 2.0 JWT 流程签发 access token 的 service account 凭据。

id?:

string
= `google-drive:${folderId}`
此文件系统实例的唯一标识符

readOnly?:

boolean
= false
设为 true 时，所有写入操作都会被阻止。

instructions?:

InstructionsOption
覆盖返回给 Tool 描述的默认指令。

属性
属性的直接链接

id:

string
文件系统实例标识符

name:

string
Provider 名称（'GoogleDriveFilesystem'）

provider:

string
Provider 标识符（'google-drive'）

readOnly:

boolean | undefined
文件系统是否处于只读模式

方法
方法的直接链接

GoogleDriveFilesystem 实现了 WorkspaceFilesystem 接口，提供所有标准文件系统方法：

  • 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 会自动创建 parent 文件夹。设置 recursive: false 可要求 parent 文件夹必须已经存在。
  • 支持 WriteOptions 中的 expectedMtime。当存储的 modifiedTime 不同时，写入会被拒绝并抛出 StaleFileError，以支持乐观并发控制。
  • 该 Provider 仅通过内置 fetch 调用 Drive REST endpoint（https://www.googleapis.com/drive/v3 和 https://www.googleapis.com/upload/drive/v3），无需额外依赖。
On this page