google-drive

Google Drive

用于管理、搜索和共享 Google Drive 中的文件。

安装

依赖项：pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

验证设置

安装后，请验证此技能是否已正确配置：

$SKILL_DIR/scripts/google-drive.py check

此命令将检查：

• Python 依赖项（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
• 身份验证配置
• 与 Google Drive API 的连接

如果有任何缺失，检查命令会提供设置说明。

身份验证

Google Drive 使用 OAuth 2.0 进行身份验证。完整的设置说明请参阅：

1. GCP 项目设置指南 - 创建项目并启用 Drive API
2. Google OAuth 设置指南 - 配置凭据

快速入门

1. 创建 ~/.config/agent-skills/google.yaml：

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

2. 运行 $SKILL_DIR/scripts/google-drive.py check，触发 OAuth 流程并验证设置。

如果遇到范围或身份验证错误，请参阅 OAuth 故障排除指南。

脚本用法

请参阅 permissions.md，了解每个命令的读写分类。

# Setup and auth
$SKILL_DIR/scripts/google-drive.py check
$SKILL_DIR/scripts/google-drive.py auth setup --client-id ID --client-secret SECRET
$SKILL_DIR/scripts/google-drive.py auth reset
$SKILL_DIR/scripts/google-drive.py auth status

# Files
$SKILL_DIR/scripts/google-drive.py files list [--query QUERY] [--max-results N] [--order-by FIELD]
$SKILL_DIR/scripts/google-drive.py files search [--name NAME] [--mime-type TYPE] [--folder ID]
$SKILL_DIR/scripts/google-drive.py files get FILE_ID
$SKILL_DIR/scripts/google-drive.py files download FILE_ID --output PATH
$SKILL_DIR/scripts/google-drive.py files export FILE_ID [--format markdown|text|pdf] [--lines N] [--output PATH]
$SKILL_DIR/scripts/google-drive.py files upload PATH [--parent ID] [--name NAME] [--mime-type TYPE] [--convert-to MIME_TYPE]
$SKILL_DIR/scripts/google-drive.py files move FILE_ID --parent FOLDER_ID
$SKILL_DIR/scripts/google-drive.py files delete FILE_ID
$SKILL_DIR/scripts/google-drive.py files rename FILE_ID --name NAME
$SKILL_DIR/scripts/google-drive.py files copy FILE_ID [--name NAME] [--parent ID]

# Folders
$SKILL_DIR/scripts/google-drive.py folders create NAME [--parent ID]
$SKILL_DIR/scripts/google-drive.py folders list FOLDER_ID [--max-results N]

# Sharing and permissions
$SKILL_DIR/scripts/google-drive.py share FILE_ID --email EMAIL [--role ROLE] [--no-notify]
$SKILL_DIR/scripts/google-drive.py permissions list FILE_ID
$SKILL_DIR/scripts/google-drive.py permissions delete FILE_ID PERMISSION_ID

# Comments
$SKILL_DIR/scripts/google-drive.py comments list FILE_ID [--max-results N] [--include-deleted]
$SKILL_DIR/scripts/google-drive.py comments get FILE_ID COMMENT_ID
$SKILL_DIR/scripts/google-drive.py comments create FILE_ID --content TEXT [--quoted-text TEXT]
$SKILL_DIR/scripts/google-drive.py comments update FILE_ID COMMENT_ID --content TEXT
$SKILL_DIR/scripts/google-drive.py comments delete FILE_ID COMMENT_ID

# Replies
$SKILL_DIR/scripts/google-drive.py replies list FILE_ID COMMENT_ID [--max-results N] [--include-deleted]
$SKILL_DIR/scripts/google-drive.py replies get FILE_ID COMMENT_ID REPLY_ID
$SKILL_DIR/scripts/google-drive.py replies create FILE_ID COMMENT_ID --content TEXT [--action resolve|reopen]
$SKILL_DIR/scripts/google-drive.py replies update FILE_ID COMMENT_ID REPLY_ID --content TEXT
$SKILL_DIR/scripts/google-drive.py replies delete FILE_ID COMMENT_ID REPLY_ID

完整的参数详情和示例请参阅 command-reference.md。

示例

验证设置

$SKILL_DIR/scripts/google-drive.py check

查找最近的 PDF 文件

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

按名称搜索文档

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

下载文件

# First, find the file ID
$SKILL_DIR/scripts/google-drive.py files search --name "report.pdf"

# Then download it
$SKILL_DIR/scripts/google-drive.py files download FILE_ID -o ./report.pdf

导出 Google 文档

# Export as markdown (default)
$SKILL_DIR/scripts/google-drive.py files export FILE_ID

# Export as plain text (useful as fallback for large docs)
$SKILL_DIR/scripts/google-drive.py files export FILE_ID --format text

# Export first 50 lines only
$SKILL_DIR/scripts/google-drive.py files export FILE_ID --format text --lines 50

# Export as PDF
$SKILL_DIR/scripts/google-drive.py files export FILE_ID --format pdf --output ./doc.pdf

上传并共享文件

# Upload the file
$SKILL_DIR/scripts/google-drive.py files upload ./presentation.pdf --name "Q4 Presentation"

# Share with a colleague
$SKILL_DIR/scripts/google-drive.py share FILE_ID --email [email protected] --role writer

上传并转换格式

使用 --convert-to 将上传的文件转换为原生 Google 格式：

# Upload HTML and convert to Google Docs
$SKILL_DIR/scripts/google-drive.py files upload ./report.html \
  --convert-to "application/vnd.google-apps.document"

# Upload CSV and convert to Google Sheets
$SKILL_DIR/scripts/google-drive.py files upload ./data.csv \
  --convert-to "application/vnd.google-apps.spreadsheet"

**注意：**若要将 Markdown 文件导入为格式正确的 Google 文档（支持 frontmatter、行间距和项目符号处理，并进行可读性检查），请改用 google-docs 技能的 documents import 命令——它提供针对 Markdown 的转换和导入后格式设置，而 --convert-to 不具备这些功能。

永久删除文件

$SKILL_DIR/scripts/google-drive.py files delete FILE_ID

重命名文件

$SKILL_DIR/scripts/google-drive.py files rename FILE_ID --name "New Name"

复制文件

# Copy with default name ("Copy of <original>")
$SKILL_DIR/scripts/google-drive.py files copy FILE_ID

# Copy with custom name into a specific folder
$SKILL_DIR/scripts/google-drive.py files copy FILE_ID --name "Backup" --parent FOLDER_ID

将文件整理到文件夹中

# Create a folder
$SKILL_DIR/scripts/google-drive.py folders create "Project Documents"

# Upload files to the folder
$SKILL_DIR/scripts/google-drive.py files upload ./doc1.pdf --parent FOLDER_ID
$SKILL_DIR/scripts/google-drive.py files upload ./doc2.pdf --parent FOLDER_ID

# List folder contents
$SKILL_DIR/scripts/google-drive.py folders list FOLDER_ID

列出文件的评论

$SKILL_DIR/scripts/google-drive.py comments list FILE_ID

添加提及用户的评论

若要提及用户，请在评论内容中使用带有 @ 前缀的用户邮箱。

$SKILL_DIR/scripts/google-drive.py comments create FILE_ID \
  --content "Hey @[email protected] please review this section"

回复评论并将其解决

$SKILL_DIR/scripts/google-drive.py replies create FILE_ID COMMENT_ID \
  --content "Fixed in latest revision" --action resolve

重新打开已解决的评论

$SKILL_DIR/scripts/google-drive.py replies create FILE_ID COMMENT_ID \
  --content "Actually this still needs work" --action reopen

Drive 搜索查询语法

请参阅 drive-queries.md，了解运算符、可搜索字段和查询示例。

常见 MIME 类型

请参阅 api-reference.md，了解与 --mime-type 和搜索查询配合使用的 MIME 类型。

不支持的操作

请参阅 api-reference.md，了解尚未实现的操作及其替代方案。

错误处理

**身份验证和范围错误不可重试。**如果命令因身份验证错误、范围不足错误或权限被拒绝错误（退出代码为 1）而失败，请停止并告知用户。不要重试或尝试自行解决问题——这些错误需要用户交互（通过浏览器进行 OAuth 授权）。请引导用户参阅 OAuth 故障排除指南。

可重试错误：限流（HTTP 429）和临时服务器错误（HTTP 5xx）等待片刻后重试可能会成功。其他所有错误都应报告给用户。

模型指南

此技能会发起需要结构化输入和输出的 API 调用。建议使用标准能力的模型。

故障排除

无法下载 Google Docs

Google Docs、Sheets 和 Slides 不是二进制文件，无法使用 files download 下载。请改用 files export 将其导出为 Markdown、纯文本或 PDF。对于较大的文档，请使用 --lines N 限制输出。