google-drive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Drive

Interact with Google Drive for file management, search, and sharing.

用于与Google Drive交互，实现文件管理、搜索和共享操作。

Installation

安装步骤

Install Python dependencies:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Download the skill from Releases or use directly from this repository.

安装Python依赖包:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

下载技能包：从Releases下载，或直接使用本仓库代码。

Setup Verification

配置验证

After installation, verify the skill is properly configured:

bash

python scripts/google-drive.py check

This will check:

Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
Authentication configuration
Connectivity to Google Drive API

If anything is missing, the check command will provide setup instructions.

安装完成后，验证技能是否配置正确：

bash

python scripts/google-drive.py check

该命令会检查以下内容：

Python依赖包（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
身份认证配置
与Google Drive API的连通性

若有缺失，检查命令会提供对应的配置指导。

Authentication

身份认证

Google Drive uses OAuth 2.0 for authentication. For complete setup instructions, see:

GCP Project Setup Guide - Create project, enable Drive API
Google OAuth Setup Guide - Configure credentials

Google Drive采用OAuth 2.0进行身份认证。完整配置说明请参考：

GCP项目配置指南 - 创建项目、启用Drive API
Google OAuth配置指南 - 配置凭证

Quick Start

快速开始

Create

~/.config/agent-skills/google.yaml

yaml

oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret

Run
```
python scripts/google-drive.py check
```
to trigger OAuth flow and verify setup.

创建

~/.config/agent-skills/google.yaml

文件：

yaml

oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret

运行
```
python scripts/google-drive.py check
```
触发OAuth流程并验证配置。

OAuth Scopes

OAuth权限范围

The skill requests granular scopes for different operations:

Scope	Permission	Used For
`drive.readonly`	Read files and metadata	list, search, download
`drive.file`	Create/edit files created by app	upload, create folders, share
`drive.metadata.readonly`	View file metadata only	get file info

本技能针对不同操作请求细分的权限范围：

权限范围	权限说明	适用场景
`drive.readonly`	读取文件及元数据	列出、搜索、下载文件
`drive.file`	创建/编辑本应用生成的文件	上传文件、创建文件夹、共享文件
`drive.metadata.readonly`	仅查看文件元数据	获取文件信息

Scope Errors

权限范围错误处理

If you encounter "insufficient scope" errors, revoke your token and re-authenticate:

Revoke at https://myaccount.google.com/permissions

Clear token:

keyring del agent-skills google-drive-token-json

Re-run:
```
python scripts/google-drive.py check
```

若遇到“权限范围不足”错误，请撤销现有令牌并重新认证：

访问https://myaccount.google.com/permissions撤销权限

清除令牌：

keyring del agent-skills google-drive-token-json

重新运行：
```
python scripts/google-drive.py check
```

Commands

命令说明

check

Verify configuration and connectivity.

bash

python scripts/google-drive.py check

This validates:

Python dependencies are installed
Authentication is configured
Can connect to Google Drive API
Displays your email address and storage usage

验证配置及连通性。

bash

python scripts/google-drive.py check

该命令会验证：

Python依赖包已安装
身份认证已配置
可连接至Google Drive API
显示你的邮箱地址及存储使用情况

auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.

bash

python scripts/google-drive.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Credentials are saved to

~/.config/agent-skills/google-drive.yaml

存储OAuth 2.0客户端凭证，用于自定义OAuth流程。

bash

python scripts/google-drive.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

凭证将保存至

~/.config/agent-skills/google-drive.yaml

。

files list

List files in your Drive.

bash

undefined

列出Drive中的文件。

bash

undefined

List recent files

列出最近文件

python scripts/google-drive.py files list

List with search query

带搜索条件列出

python scripts/google-drive.py files list --query "name contains 'report'"

List with max results

限制结果数量

python scripts/google-drive.py files list --max-results 20

List sorted by name

按名称排序

python scripts/google-drive.py files list --order-by "name"

Output as JSON

以JSON格式输出

python scripts/google-drive.py files list --json


**Arguments:**
- `--query`: Drive search query (optional)
- `--max-results`: Maximum number of results (default: 10)
- `--order-by`: Sort order (default: "modifiedTime desc")
- `--json`: Output as JSON

python scripts/google-drive.py files list --json


**参数说明：**
- `--query`: Drive搜索查询语句（可选）
- `--max-results`: 最大返回结果数（默认：10）
- `--order-by`: 排序规则（默认："modifiedTime desc"）
- `--json`: 以JSON格式输出结果

files search

Search for files with filters.

bash

undefined

带筛选条件搜索文件。

bash

undefined

Search by name

按文件名搜索

python scripts/google-drive.py files search --name "quarterly report"

Search by MIME type

按MIME类型搜索

python scripts/google-drive.py files search --mime-type "application/pdf"

Search in a specific folder

在指定文件夹内搜索

python scripts/google-drive.py files search --folder FOLDER_ID

Combine filters

组合筛选条件

python scripts/google-drive.py files search --name "budget" --mime-type "application/vnd.google-apps.spreadsheet"

Output as JSON

以JSON格式输出

python scripts/google-drive.py files search --name "report" --json


**Arguments:**
- `--name`: File name to search for (partial match)
- `--mime-type`: MIME type filter
- `--folder`: Parent folder ID
- `--json`: Output as JSON

python scripts/google-drive.py files search --name "report" --json


**参数说明：**
- `--name`: 要搜索的文件名（支持部分匹配）
- `--mime-type`: MIME类型筛选
- `--folder`: 父文件夹ID
- `--json`: 以JSON格式输出结果

files get

Get file metadata by ID.

bash

undefined

通过ID获取文件元数据。

bash

undefined

Get file details

获取文件详情

python scripts/google-drive.py files get FILE_ID

Output as JSON

以JSON格式输出

python scripts/google-drive.py files get FILE_ID --json


**Arguments:**
- `file_id`: The file ID (required)
- `--json`: Output as JSON

python scripts/google-drive.py files get FILE_ID --json


**参数说明：**
- `file_id`: 文件ID（必填）
- `--json`: 以JSON格式输出结果

files download

Download a file from Google Drive.

bash

undefined

从Google Drive下载文件。

bash

undefined

Download a file

下载文件

python scripts/google-drive.py files download FILE_ID --output /path/to/local/file

Short form

简写形式

python scripts/google-drive.py files download FILE_ID -o ./downloaded-file.pdf


**Arguments:**
- `file_id`: The file ID (required)
- `--output`, `-o`: Output file path (required)

**Note:** Google Docs, Sheets, and Slides cannot be downloaded directly. Use the Google Drive web interface to export them.

python scripts/google-drive.py files download FILE_ID -o ./downloaded-file.pdf


**参数说明：**
- `file_id`: 文件ID（必填）
- `--output`, `-o`: 本地输出文件路径（必填）

**注意：** Google Docs、Sheets和Slides无法直接下载，请通过Google Drive网页端导出为可下载格式。

files upload

Upload a file to Google Drive.

bash

undefined

上传文件至Google Drive。

bash

undefined

Upload a file

上传文件

python scripts/google-drive.py files upload /path/to/file.pdf

Upload to a specific folder

上传至指定文件夹

python scripts/google-drive.py files upload /path/to/file.pdf --parent FOLDER_ID

Upload with custom name

自定义上传后的文件名

python scripts/google-drive.py files upload /path/to/file.pdf --name "Quarterly Report 2024"

Upload with specific MIME type

指定MIME类型上传

python scripts/google-drive.py files upload /path/to/file --mime-type "text/csv"

Output as JSON

以JSON格式输出

python scripts/google-drive.py files upload /path/to/file.pdf --json


**Arguments:**
- `path`: Local file path (required)
- `--parent`: Parent folder ID
- `--mime-type`: MIME type (auto-detected if not provided)
- `--name`: Name for the file in Drive
- `--json`: Output as JSON

python scripts/google-drive.py files upload /path/to/file.pdf --json


**参数说明：**
- `path`: 本地文件路径（必填）
- `--parent`: 父文件夹ID
- `--mime-type`: MIME类型（未指定时自动检测）
- `--name`: 在Drive中显示的文件名
- `--json`: 以JSON格式输出结果

folders create

Create a new folder.

bash

undefined

创建新文件夹。

bash

undefined

Create folder in root

在根目录创建文件夹

python scripts/google-drive.py folders create "New Folder"

Create folder inside another folder

在指定文件夹内创建子文件夹

python scripts/google-drive.py folders create "Subfolder" --parent FOLDER_ID

Output as JSON

以JSON格式输出

python scripts/google-drive.py folders create "Documents" --json


**Arguments:**
- `name`: Folder name (required)
- `--parent`: Parent folder ID
- `--json`: Output as JSON

python scripts/google-drive.py folders create "Documents" --json


**参数说明：**
- `name`: 文件夹名称（必填）
- `--parent`: 父文件夹ID
- `--json`: 以JSON格式输出结果

folders list

List contents of a folder.

bash

undefined

列出指定文件夹的内容。

bash

undefined

List folder contents

列出文件夹内容

python scripts/google-drive.py folders list FOLDER_ID

List with max results

限制结果数量

python scripts/google-drive.py folders list FOLDER_ID --max-results 50

Output as JSON

以JSON格式输出

python scripts/google-drive.py folders list FOLDER_ID --json


**Arguments:**
- `folder_id`: The folder ID (required)
- `--max-results`: Maximum number of results (default: 100)
- `--json`: Output as JSON

python scripts/google-drive.py folders list FOLDER_ID --json


**参数说明：**
- `folder_id`: 文件夹ID（必填）
- `--max-results`: 最大返回结果数（默认：100）
- `--json`: 以JSON格式输出结果

Share a file with a user.

bash

undefined

与用户共享文件。

bash

undefined

Share as reader (default)

以读者权限共享（默认）

python scripts/google-drive.py share FILE_ID --email user@example.com

Share as writer

以编辑者权限共享

python scripts/google-drive.py share FILE_ID --email user@example.com --role writer

Share as commenter

以评论者权限共享

python scripts/google-drive.py share FILE_ID --email user@example.com --role commenter

Share without sending notification

共享时不发送通知邮件

python scripts/google-drive.py share FILE_ID --email user@example.com --no-notify

Output as JSON

以JSON格式输出

python scripts/google-drive.py share FILE_ID --email user@example.com --json


**Arguments:**
- `file_id`: File ID to share (required)
- `--email`: Email address to share with (required)
- `--role`: Permission role - reader, writer, commenter, owner (default: reader)
- `--no-notify`: Don't send notification email
- `--json`: Output as JSON

python scripts/google-drive.py share FILE_ID --email user@example.com --json


**参数说明：**
- `file_id`: 要共享的文件ID（必填）
- `--email`: 共享对象的邮箱地址（必填）
- `--role`: 权限角色 - reader（读者）、writer（编辑者）、commenter（评论者）、owner（所有者）（默认：reader）
- `--no-notify`: 不发送通知邮件
- `--json`: 以JSON格式输出结果

permissions list

List permissions for a file.

bash

undefined

列出文件的权限信息。

bash

undefined

List permissions

列出权限

python scripts/google-drive.py permissions list FILE_ID

Output as JSON

以JSON格式输出

python scripts/google-drive.py permissions list FILE_ID --json


**Arguments:**
- `file_id`: The file ID (required)
- `--json`: Output as JSON

python scripts/google-drive.py permissions list FILE_ID --json


**参数说明：**
- `file_id`: 文件ID（必填）
- `--json`: 以JSON格式输出结果

permissions delete

Remove a permission from a file.

bash

undefined

移除文件的某项权限。

bash

undefined

Delete a permission

删除权限

python scripts/google-drive.py permissions delete FILE_ID PERMISSION_ID


**Arguments:**
- `file_id`: The file ID (required)
- `permission_id`: The permission ID to delete (required)

python scripts/google-drive.py permissions delete FILE_ID PERMISSION_ID


**参数说明：**
- `file_id`: 文件ID（必填）
- `permission_id`: 要删除的权限ID（必填）

Examples

使用示例

Verify Setup

验证配置

bash

python scripts/google-drive.py check

bash

python scripts/google-drive.py check

Find recent PDF files

查找最近的PDF文件

bash

python scripts/google-drive.py files list --query "mimeType='application/pdf'" --max-results 5

bash

python scripts/google-drive.py files list --query "mimeType='application/pdf'" --max-results 5

Search for documents by name

按名称搜索文档

bash

python scripts/google-drive.py files search --name "project proposal"

bash

python scripts/google-drive.py files search --name "project proposal"

Download a file

下载文件

bash

undefined

bash

undefined

First, find the file ID

先查找文件ID

python scripts/google-drive.py files search --name "report.pdf"

Then download it

然后下载

python scripts/google-drive.py files download FILE_ID -o ./report.pdf

undefined

python scripts/google-drive.py files download FILE_ID -o ./report.pdf

undefined

Upload and share a file

上传并共享文件

bash

undefined

bash

undefined

Upload the file

上传文件

python scripts/google-drive.py files upload ./presentation.pdf --name "Q4 Presentation"

Share with a colleague

与同事共享

python scripts/google-drive.py share FILE_ID --email colleague@example.com --role writer

undefined

python scripts/google-drive.py share FILE_ID --email colleague@example.com --role writer

undefined

Organize files into folders

将文件整理至文件夹

bash

undefined

bash

undefined

Create a folder

创建文件夹

python scripts/google-drive.py folders create "Project Documents"

Upload files to the folder

上传文件至该文件夹

python scripts/google-drive.py files upload ./doc1.pdf --parent FOLDER_ID python scripts/google-drive.py files upload ./doc2.pdf --parent FOLDER_ID

List folder contents

列出文件夹内容

python scripts/google-drive.py folders list FOLDER_ID

undefined

python scripts/google-drive.py folders list FOLDER_ID

undefined

Drive Search Query Syntax

Drive搜索查询语法

Common search operators:

Operator	Description	Example
`name contains`	Name contains string	`name contains 'report'`
`name =`	Exact name match	`name = 'Budget 2024.xlsx'`
`mimeType =`	File type	`mimeType = 'application/pdf'`
`'ID' in parents`	In folder	`'folder_id' in parents`
`modifiedTime >`	Modified after	`modifiedTime > '2024-01-01'`
`trashed =`	Trashed status	`trashed = false`
`starred =`	Starred status	`starred = true`
`sharedWithMe`	Shared files	`sharedWithMe = true`

Combine operators with

and

or

bash

undefined

常用搜索操作符：

操作符	说明	示例
`name contains`	文件名包含指定字符串	`name contains 'report'`
`name =`	精确匹配文件名	`name = 'Budget 2024.xlsx'`
`mimeType =`	文件类型匹配	`mimeType = 'application/pdf'`
`'ID' in parents`	文件位于指定文件夹内	`'folder_id' in parents`
`modifiedTime >`	文件修改时间晚于指定日期	`modifiedTime > '2024-01-01'`
`trashed =`	文件是否已放入回收站	`trashed = false`
`starred =`	文件是否已标记星标	`starred = true`
`sharedWithMe`	文件是否是他人共享给自己的	`sharedWithMe = true`

可使用

and

或

or

组合多个操作符：

bash

undefined

PDF files modified this year

今年修改过的PDF文件

"mimeType = 'application/pdf' and modifiedTime > '2024-01-01'"

Spreadsheets containing 'budget'

包含'budget'的表格文件

"name contains 'budget' and mimeType = 'application/vnd.google-apps.spreadsheet'"

Files in a specific folder that are not trashed

指定文件夹内未被删除的文件

"'folder_id' in parents and trashed = false"


For the complete reference, see [drive-queries.md](references/drive-queries.md).

"'folder_id' in parents and trashed = false"


完整语法参考：[drive-queries.md](references/drive-queries.md)。

Common MIME Types

常见MIME类型

Type	MIME Type
Folder	`application/vnd.google-apps.folder`
Google Doc	`application/vnd.google-apps.document`
Google Sheet	`application/vnd.google-apps.spreadsheet`
Google Slides	`application/vnd.google-apps.presentation`
PDF	`application/pdf`
Word	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
Text	`text/plain`
CSV	`text/csv`
Image (JPEG)	`image/jpeg`
Image (PNG)	`image/png`

文件类型	MIME类型
文件夹	`application/vnd.google-apps.folder`
Google文档	`application/vnd.google-apps.document`
Google表格	`application/vnd.google-apps.spreadsheet`
Google幻灯片	`application/vnd.google-apps.presentation`
PDF	`application/pdf`
Word文档	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel表格	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint演示文稿	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
文本文件	`text/plain`
CSV文件	`text/csv`
JPEG图片	`image/jpeg`
PNG图片	`image/png`

Troubleshooting

故障排除

Check command fails

check命令执行失败

Run

python scripts/google-drive.py check

to diagnose issues. It will provide specific error messages and setup instructions.

运行

python scripts/google-drive.py check

诊断问题，命令会提供具体错误信息及配置指导。

Authentication failed

身份认证失败

Verify your OAuth client ID and client secret are correct in
```
~/.config/agent-skills/google.yaml
```

Token expired or corrupted - clear and re-authenticate:

bash

keyring del agent-skills google-drive-token-json
python scripts/google-drive.py check

验证
```
~/.config/agent-skills/google.yaml
```
中的OAuth客户端ID和密钥是否正确

令牌过期或损坏 - 清除令牌并重新认证：

bash

keyring del agent-skills google-drive-token-json
python scripts/google-drive.py check

Permission denied

权限被拒绝

Your OAuth token may not have the necessary scopes. Revoke access at https://myaccount.google.com/permissions, clear your token, and re-authenticate.

你的OAuth令牌可能缺少必要的权限范围。访问https://myaccount.google.com/permissions撤销权限，清除令牌后重新认证。

Cannot download Google Docs

无法下载Google Docs

Google Docs, Sheets, and Slides are not binary files - they cannot be downloaded directly. Use the Google Drive web interface to export them to a downloadable format (PDF, DOCX, etc.).

Google Docs、Sheets和Slides并非二进制文件，无法直接下载。请通过Google Drive网页端将其导出为可下载格式（如PDF、DOCX等）。

Import errors

导入错误

Ensure dependencies are installed:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

确保所有依赖包已安装：

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Rate limiting

请求频率限制

Drive API has quota limits. If you hit rate limits, wait a few minutes before retrying. For high-volume usage, consider requesting quota increases in the Google Cloud Console.

Drive API有配额限制。若触发频率限制，请等待几分钟后重试。对于高频使用场景，可在Google Cloud Console申请提高配额。

API Scopes

API权限范围

This skill requests the following OAuth scopes:

https://www.googleapis.com/auth/drive.readonly

- Read files and metadata

```
https://www.googleapis.com/auth/drive.file
```
- Create, modify, delete files created by the app

https://www.googleapis.com/auth/drive.metadata.readonly

- View file metadata only

These scopes provide file management capabilities while following the principle of least privilege.

本技能请求以下OAuth权限范围：

https://www.googleapis.com/auth/drive.readonly

- 读取文件及元数据

```
https://www.googleapis.com/auth/drive.file
```
- 创建、修改、删除本应用生成的文件

https://www.googleapis.com/auth/drive.metadata.readonly

- 仅查看文件元数据

这些权限范围在遵循最小权限原则的前提下，提供完整的文件管理能力。

Security Notes

安全说明

OAuth tokens are stored securely in your system keyring
Client secrets are stored in
```
~/.config/agent-skills/google-drive.yaml
```
with file permissions 600
No passwords are stored - only OAuth tokens
Tokens refresh automatically when using the skill
Browser-based consent ensures you approve all requested permissions

Always review OAuth consent screens before granting access to your Google Drive.

OAuth令牌：安全存储在系统密钥环中
客户端密钥：存储在
```
~/.config/agent-skills/google-drive.yaml
```
，文件权限设为600
无密码存储：仅存储OAuth令牌，不保存密码
令牌自动刷新：使用技能时令牌会自动刷新
浏览器授权：所有请求的权限均需你手动确认

在授予Google Drive访问权限前，请务必仔细查看OAuth授权界面的权限说明。