gdrive-access

Google Drive 访问

通过 Claude Code 以编程方式列出、下载和同步 Google Drive 中的文件。

自演进技能：此技能会随着使用不断改进。如果指令有误、参数发生偏移或需要采用变通方法，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

强制预检（执行任何 Drive 操作前）

重要：运行任何 gdrive 命令前，必须完成此预检清单。不得跳过任何步骤。

步骤 1：检查 CLI 二进制文件是否存在

ls -la "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts/gdrive" 2>/dev/null || echo "BINARY_NOT_FOUND"

如果 BINARY_NOT_FOUND：请先构建：

cd ~/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts && bun install && bun run build

步骤 2：检查 GDRIVE_OP_UUID 环境变量

echo "GDRIVE_OP_UUID: ${GDRIVE_OP_UUID:-NOT_SET}"

如果 NOT_SET：必须运行下方的设置流程。不得继续运行 gdrive 命令。

步骤 3：验证 1Password 身份验证

op account list 2>&1 | head -3

如果出现错误或尚未登录：请告知用户先运行 op signin。

---

设置流程（当 GDRIVE_OP_UUID 为 NOT_SET 时）

按顺序执行以下步骤。在需要做出决定时使用 AskUserQuestion。

设置步骤 1：检查 1Password CLI

command -v op && echo "OP_CLI_INSTALLED" || echo "OP_CLI_MISSING"

如果 OP_CLI_MISSING：停止并告知用户：

需要 1Password CLI。使用以下命令安装：brew install 1password-cli

设置步骤 2：在 1Password 中查找 Drive OAuth 项目

unset HTTPS_PROXY HTTP_PROXY   # the OAuth proxy 502s api.1password.com
op vault list                  # FIRST: see which vaults this credential can actually reach
op item list --vault "<vault-from-above>" --format json 2>/dev/null | jq -r '.[] | select(.title | test("drive|oauth|google"; "i")) | "\(.id)\t\(.title)"'

⚠ 不要将 Employee 硬编码。 当 op 在 服务账户令牌下运行时，它只能查看授予该令牌的保管库，而 --vault Employee 会报错 "Employee" isn't a vault in this account；如果直接通过管道传递输出，这会令人困惑地表现为 jq: parse error。请始终先运行 op vault list，再据此设置 GDRIVE_OP_VAULT。服务账户还要求每次运行 op item get 时都指定 --vault；否则会出现 a vault query must be provided。

解析输出，并根据结果继续：

设置步骤 3：由用户选择 OAuth 凭据

如果找到项目，使用 AskUserQuestion 展示找到的项目：

AskUserQuestion({
  questions: [{
    question: "Which 1Password item contains your Google Drive OAuth credentials?",
    header: "Drive OAuth",
    options: [
      // POPULATE FROM op item list RESULTS - example:
      { label: "Google Drive API (56peh...)", description: "OAuth client in Employee vault" },
      { label: "Gmail API - project-f (abc12...)", description: "Can also access Drive" },
    ],
    multiSelect: false
  }]
})

如果未找到任何项目，使用 AskUserQuestion 引导用户完成设置：

AskUserQuestion({
  questions: [{
    question: "No Google Drive OAuth credentials found in 1Password. How would you like to proceed?",
    header: "Setup",
    options: [
      { label: "Create new OAuth credentials (Recommended)", description: "I'll guide you through Google Cloud Console setup" },
      { label: "I have credentials elsewhere", description: "Help me add them to 1Password" },
      { label: "Skip for now", description: "I'll set this up later" }
    ],
    multiSelect: false
  }]
})

• 如果选择“创建新的 OAuth 凭据”：阅读并展示 references/gdrive-api-setup.md
• 如果选择“我在其他地方有凭据”：引导用户将其添加到 1Password，并填写必需字段
• 如果选择“暂时跳过”：告知用户配置完成前，此技能无法使用

设置步骤 4：确认环境配置

CLI 仅从进程环境中读取 GDRIVE_OP_UUID（以及可选的 GDRIVE_OP_VAULT）。用户选择项目（含 UUID）后，使用 AskUserQuestion：

AskUserQuestion({
  questions: [{
    question: "Export GDRIVE_OP_UUID from your shell profile (~/.zshrc)?",
    header: "Configure",
    options: [
      { label: "Yes, add to ~/.zshrc (Recommended)", description: "Appends an export line; applies to every new shell" },
      { label: "Show me the line only", description: "I'll add it manually, or pass it inline per call" }
    ],
    multiSelect: false
  }]
})

如果选择“是，添加到 ~/.zshrc”：检查是否已经存在 GDRIVE_OP_UUID 导出语句，然后追加：

export GDRIVE_OP_UUID="<selected-uuid>"
export GDRIVE_OP_VAULT="<vault-from-step-2>"   # only if not Employee

如果选择“只显示这一行”：输出供用户手动添加的导出语句。也可以在每次调用时内联传入变量（如 Step 6 所示：GDRIVE_OP_UUID=<uuid> gdrive ...）。

设置步骤 5：重新加载并验证

source ~/.zshrc && echo "GDRIVE_OP_UUID after reload: ${GDRIVE_OP_UUID:-NOT_SET}"

如果仍为 NOT_SET：告知用户重启 shell。

设置步骤 6：测试连接

GDRIVE_OP_UUID="${GDRIVE_OP_UUID}" $HOME/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts/gdrive list 1wqqqvBmeUFYuwOOEQhzoChC7KzAk-mAS

如果出现 OAuth 提示：这是首次运行时的正常情况。浏览器将打开 Google 授权页面。

---

Drive 命令（仅在预检通过后）

GDRIVE_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts/gdrive"

# List files in a folder
$GDRIVE_CLI list <folder_id>

# List with details (size, modified date)
$GDRIVE_CLI list <folder_id> --verbose

# Search for files
$GDRIVE_CLI search "name contains 'training'"

# Get file info
$GDRIVE_CLI info <file_id>

# Download a single file
$GDRIVE_CLI download <file_id> -o ./output.pdf

# Sync entire folder to local directory
$GDRIVE_CLI sync <folder_id> -o ./output_dir

# Sync with subfolders
$GDRIVE_CLI sync <folder_id> -o ./output_dir -r

# JSON output (for parsing)
$GDRIVE_CLI list <folder_id> --json

创建原生 Google 文档（写入）

create-doc 会上传本地 HTML（或 .docx）源文件，并让 Drive 将其转换为原生 Google 文档（application/vnd.google-apps.document）——团队可以直接打开并评论，无需执行“转换”步骤。这是推荐的 Drive 使用方式：在元数据中使用目标 mimeType，并将源文件字节作为媒体，通过 multipart 上传调用 files.create（简单上传会静默跳过转换）。

# Markdown is the usual author format → HTML (highest-fidelity import) → native Google Doc
pandoc notes.md -o /tmp/notes.html --standalone
$GDRIVE_CLI create-doc /tmp/notes.html --name "Meeting Notes" --parent <folder_id>
# → prints the new Doc's id, mimeType (application/vnd.google-apps.document), and docs.google.com link

# Overwrite an existing Doc's contents in place (keeps the same id / link / comments):
$GDRIVE_CLI create-doc /tmp/notes.html --update <doc_id>

为什么不用 rclone / .docx？ rclone 的 --drive-import-formats 用于此场景并不可靠（有名称冲突和同步混淆等问题），而普通 .docx 文件虽然可以在 Drive 中通过 Docs 打开，但它不是_原生_文档。上述 Drive API 转换是可靠的 FOSS 方案。

写入范围（需重新授权一次）。 create-doc 需要 drive.file 范围（创建和管理此应用创建的文件——遵循最小权限原则，而非完整云端硬盘权限）。该范围与原有的 drive.readonly 一同添加，因此首次写入时会重新请求授权。如果没有，请强制触发： rm ~/.claude/tools/gdrive-tokens/$GDRIVE_OP_UUID.json，然后重新运行。--update 仅适用于此应用创建的文档（受 drive.file 限制）；若要覆盖由外部创建的文档，请扩大范围至 auth/drive。

速率限制与重试（内置）

当项目短时间内发送过多请求时，Drive 会返回 HTTP 403 rateLimitExceeded / userRateLimitExceeded（有时也会返回 429）——我们在连续执行多次写入时遇到了这种情况。CLI 现在会对每次 Drive 调用应用带抖动的指数退避（lib/drive.ts 中的 withBackoff）：等待 min(2^n·1000 + random_ms, 64s)，重试次数有限，符合 Google 官方指南。非速率限制错误仍会直接报错。若要主动避免超出限制：批量处理 / 错开批量操作，避免冗余的元数据调用，也不要每次调用都刷新令牌。

已保存的令牌失效时：Error: invalid_grant

Token expired, refreshing... 后出现 Error: invalid_grant，表示已保存的刷新令牌已被撤销或过期——并非访问令牌。刷新无法恢复它。原因包括：OAuth 客户端的 Google Cloud 发布状态仍为**“Testing”**（此时刷新令牌会在 7 天后过期）、用户撤销了应用访问权限，或密码已更改。通过此 CLI 唯一的修复方法是重新完整授权，这需要使用交互式浏览器：

rm ~/.claude/tools/gdrive-tokens/$GDRIVE_OP_UUID.json   # then re-run any gdrive command

无需浏览器的备用方案：rclone。 如果 rclone listremotes 显示同一 Google 账号下有一个 type = drive 远程端，它会使用独立的令牌，通常仍可正常工作。已于 2026-09-02 验证：当 invalid_grant 导致 CLI 完全无法使用时，该方案仍可用。通过 ID 访问任意文件夹——包括“与我共享”下没有“我的云端硬盘”路径的文件夹：

rclone lsjson --recursive --max-depth 2 --drive-root-folder-id <folder_id> <remote>:
rclone lsjson --metadata --drive-root-folder-id <folder_id> <remote>:<subfolder>   # adds owner + btime (created)
rclone copy --drive-root-folder-id <folder_id> "<remote>:<subfolder>/<file>" ./dest/

只有 --metadata 能获取所有者和创建时间（btime）；普通 lsjson 不会返回这两项。请始终说明使用了哪种方式——rclone 远程端关联的 Google 身份可能与 GDRIVE_OP_UUID 不同。

从 URL 提取文件夹 ID

Google Drive 文件夹 URL：

https://drive.google.com/drive/folders/1wqqqvBmeUFYuwOOEQhzoChC7KzAk-mAS
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                       This is the folder ID

Drive 搜索语法

查询	说明
name contains 'keyword'	名称包含关键词
name = 'exact name'	名称完全匹配
mimeType = 'application/pdf'	按文件类型搜索
modifiedTime > '2026-01-01'	修改时间晚于指定日期
trashed = false	不在回收站中
'<folderId>' in parents	位于指定文件夹中

参考：https://developers.google.com/drive/api/guides/search-files

环境变量

变量	必需	描述
GDRIVE_OP_UUID	是	用于 OAuth 凭据的 1Password 条目 UUID
GDRIVE_OP_VAULT	通常	1Password 保管库。代码默认值为 Employee，服务账户令牌通常无法访问此保管库——运行 op vault list 并显式设置此变量

令牌存储

OAuth 令牌存储在：~/.claude/tools/gdrive-tokens/<uuid>.json

• 集中存储（不在插件或项目中）
• 按 1Password UUID 组织（支持多个账户）
• 创建时设置 chmod 600

Google Docs 导出

Google Docs（Docs、Sheets、Slides）会自动导出：

Google 类型	导出格式
文档	.docx
电子表格	.xlsx
演示文稿	.pptx
绘图	.png

参考资料

• gdrive-api-setup.md - Google Cloud OAuth 设置指南

变更后检查清单

• YAML frontmatter 有效（描述中不含冒号）
• 触发关键词是最新的
• 路径模式使用 $HOME，而非硬编码路径
• 参考资料均存在且已添加链接

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确认位置。 — 编辑前，找到此 SKILL.md 的规范路径。
1. 哪里失败了？ — 修正导致失败的指令。
2. 哪些方面比预期更有效？ — 将其提升为推荐实践。
3. 哪些内容发生了偏差？ — 修正不再符合实际情况的脚本、参考资料或依赖项。
4. 记录下来。 — 添加演进日志条目，注明触发原因、修正内容和证据。

切勿推迟。下一次调用会继承你留下的一切。