gdrive-access

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Drive Access

Google Drive 访问

List, download, and sync files from Google Drive programmatically via Claude Code CLI.

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

MANDATORY PREFLIGHT (Execute Before Any Drive Operation)

强制预检（执行任何Drive操作前必须完成）

CRITICAL: You MUST complete this preflight checklist before running any gdrive commands. Do NOT skip steps.

重要提示：在运行任何gdrive命令之前，你必须完成此预检清单。请勿跳过步骤。

Step 1: Check CLI Binary Exists

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

bash

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

If BINARY_NOT_FOUND: Build it first:

bash

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

bash

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

如果返回BINARY_NOT_FOUND：先构建它：

bash

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

Step 2: Check GDRIVE_OP_UUID Environment Variable

步骤2：检查GDRIVE_OP_UUID环境变量

bash

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

If NOT_SET: You MUST run the Setup Flow below. Do NOT proceed to gdrive commands.

bash

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

如果返回NOT_SET：你必须运行下面的设置流程。请勿继续执行gdrive命令。

Step 3: Verify 1Password Authentication

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

bash

op account list 2>&1 | head -3

If error or not signed in: Inform user to run

op signin

first.

bash

op account list 2>&1 | head -3

如果出现错误或未登录：告知用户先运行

op signin

。

Setup Flow (When GDRIVE_OP_UUID is NOT_SET)

设置流程（当GDRIVE_OP_UUID未设置时）

Follow these steps IN ORDER. Use AskUserQuestion at decision points.

按顺序遵循这些步骤。在决策点使用AskUserQuestion。

Setup Step 1: Check 1Password CLI

设置步骤1：检查1Password CLI

bash

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

If OP_CLI_MISSING: Stop and inform user:

1Password CLI is required. Install with:
brew install 1password-cli

bash

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

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

需要1Password CLI。安装方式：
brew install 1password-cli

Setup Step 2: Discover Drive OAuth Items in 1Password

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

bash

op item list --vault Employee --format json 2>/dev/null | jq -r '.[] | select(.title | test("drive|oauth|google"; "i")) | "\(.id)\t\(.title)"'

Parse the output and proceed based on results:

bash

op item list --vault Employee --format json 2>/dev/null | jq -r '.[] | select(.title | test("drive|oauth|google"; "i")) | "\(.id)\t\(.title)"'

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

Setup Step 3: User Selects OAuth Credentials

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

If items found, use AskUserQuestion with discovered items:

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 - dental-quizzes (abc12...)", description: "Can also access Drive" },
    ],
    multiSelect: false
  }]
})

If NO items found, use AskUserQuestion to guide setup:

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
  }]
})

If "Create new OAuth credentials": Read and present references/gdrive-api-setup.md
If "I have credentials elsewhere": Guide user to add to 1Password with required fields
If "Skip for now": Inform user the skill won't work until configured

如果找到条目，使用AskUserQuestion并传入发现的条目：

AskUserQuestion({
  questions: [{
    question: "哪个1Password条目包含你的Google Drive OAuth凭据？",
    header: "Drive OAuth",
    options: [
      // 从op item list结果中填充 - 示例：
      { label: "Google Drive API (56peh...)", description: "Employee保险箱中的OAuth客户端" },
      { label: "Gmail API - dental-quizzes (abc12...)", description: "也可访问Drive" },
    ],
    multiSelect: false
  }]
})

如果未找到条目，使用AskUserQuestion引导设置：

AskUserQuestion({
  questions: [{
    question: "在1Password中未找到Google Drive OAuth凭据。你想如何继续？",
    header: "设置",
    options: [
      { label: "创建新的OAuth凭据（推荐）", description: "我会引导你完成Google Cloud Console设置" },
      { label: "我在其他地方已有凭据", description: "帮助我将其添加到1Password" },
      { label: "暂时跳过", description: "我稍后再设置" }
    ],
    multiSelect: false
  }]
})

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

Setup Step 4: Confirm mise Configuration

设置步骤4：确认mise配置

After user selects an item (with UUID), use AskUserQuestion:

AskUserQuestion({
  questions: [{
    question: "Add GDRIVE_OP_UUID to .mise.local.toml in current project?",
    header: "Configure",
    options: [
      { label: "Yes, add to .mise.local.toml (Recommended)", description: "Creates/updates gitignored config file" },
      { label: "Show me the config only", description: "I'll add it manually" }
    ],
    multiSelect: false
  }]
})

If "Yes, add to .mise.local.toml":

Check if
```
.mise.local.toml
```
exists
If exists, append
```
GDRIVE_OP_UUID
```
to
```
[env]
```
section
If not exists, create with:

toml

[env]
GDRIVE_OP_UUID = "<selected-uuid>"

Verify
```
.mise.local.toml
```
is in
```
.gitignore
```

If "Show me the config only": Output the TOML for user to add manually.

用户选择条目（包含UUID）后，使用AskUserQuestion：

AskUserQuestion({
  questions: [{
    question: "将GDRIVE_OP_UUID添加到当前项目的.mise.local.toml中？",
    header: "配置",
    options: [
      { label: "是，添加到.mise.local.toml（推荐）", description: "创建/更新被git忽略的配置文件" },
      { label: "仅展示配置", description: "我会手动添加" }
    ],
    multiSelect: false
  }]
})

如果选择“是，添加到.mise.local.toml”：

检查
```
.mise.local.toml
```
是否存在
如果存在，将
```
GDRIVE_OP_UUID
```
追加到
```
[env]
```
部分
如果不存在，创建文件并写入：

toml

[env]
GDRIVE_OP_UUID = "<selected-uuid>"

验证
```
.mise.local.toml
```
是否在
```
.gitignore
```
中

如果选择“仅展示配置”：输出TOML内容供用户手动添加。

Setup Step 5: Reload and Verify

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

bash

mise trust 2>/dev/null || true
cd . && echo "GDRIVE_OP_UUID after reload: ${GDRIVE_OP_UUID:-NOT_SET}"

If still NOT_SET: Inform user to restart their shell or run

source ~/.zshrc

bash

mise trust 2>/dev/null || true
cd . && echo "重新加载后的GDRIVE_OP_UUID: ${GDRIVE_OP_UUID:-NOT_SET}"

如果仍显示NOT_SET：告知用户重启shell或运行

source ~/.zshrc

。

Setup Step 6: Test Connection

设置步骤6：测试连接

bash

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

If OAuth prompt appears: This is expected on first run. Browser will open for Google consent.

bash

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

如果出现OAuth提示：这是首次运行时的正常现象。浏览器会打开以获取Google授权。

Drive Commands (Only After Preflight Passes)

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

bash

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

bash

GDRIVE_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gdrive-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)

JSON输出（用于解析）

$GDRIVE_CLI list <folder_id> --json

undefined

$GDRIVE_CLI list <folder_id> --json

undefined

Extracting Folder ID from URL

从URL提取文件夹ID

Google Drive folder URL:

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

Google Drive文件夹URL：

https://drive.google.com/drive/folders/1wqqqvBmeUFYuwOOEQhzoChC7KzAk-mAS
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                       这就是文件夹ID

Drive Search Syntax

Drive搜索语法

Query	Description
`name contains 'keyword'`	Name contains keyword
`name = 'exact name'`	Exact name match
`mimeType = 'application/pdf'`	By file type
`modifiedTime > '2026-01-01'`	Modified after date
`trashed = false`	Not in trash
`'<folderId>' in parents`	In specific folder

Reference: https://developers.google.com/drive/api/guides/search-files

查询语句	描述
`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

Environment Variables

环境变量

Variable	Required	Description
`GDRIVE_OP_UUID`	Yes	1Password item UUID for OAuth credentials
`GDRIVE_OP_VAULT`	No	1Password vault (default: Employee)

变量名	是否必填	描述
`GDRIVE_OP_UUID`	是	用于OAuth凭据的1Password条目UUID
`GDRIVE_OP_VAULT`	否	1Password保险箱（默认：Employee）

Token Storage

令牌存储

OAuth tokens stored at:

~/.claude/tools/gdrive-tokens/<uuid>.json

Central location (not in plugin, not in project)
Organized by 1Password UUID (supports multi-account)
Created with chmod 600

OAuth令牌存储在：

~/.claude/tools/gdrive-tokens/<uuid>.json

集中存储（不在插件或项目中）
按1Password UUID分类（支持多账户）
创建时设置chmod 600权限

Google Docs Export

Google Docs导出

Google Docs (Docs, Sheets, Slides) are automatically exported:

Google Type	Export Format
Document	.docx
Spreadsheet	.xlsx
Presentation	.pptx
Drawing	.png

Google Docs（文档、表格、幻灯片）会自动导出为以下格式：

Google类型	导出格式
Document	.docx
Spreadsheet	.xlsx
Presentation	.pptx
Drawing	.png

References

参考资料

gdrive-api-setup.md - Google Cloud OAuth setup guide

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

Post-Change Checklist

变更后检查清单

YAML frontmatter valid (no colons in description)
Trigger keywords current
Path patterns use $HOME not hardcoded paths
References exist and are linked

YAML前置元数据有效（描述中无冒号）
触发关键词为当前最新
路径模式使用$HOME而非硬编码路径
参考资料存在且已正确链接