google-drive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Drive

Architecture

架构

gdrive

is a Python orchestrator CLI that uses rclone as its transport layer. rclone handles all Google Drive API communication -- OAuth, file transfers, format conversion, retry/rate-limiting.

gdrive

adds the intelligence on top: a manifest that tracks synced files, format-aware push/pull that re-imports Google Docs as native format, conflict detection, and multi-remote management. Think of rclone as the engine and gdrive as the driver.

Designed for a pull-edit-push cycle, especially paired with Anthropic's official document skills for reading and editing office files:

docx

xlsx

pptx

, and

pdf

(from

https://github.com/anthropics/skills

gdrive

是一个Python编排CLI工具，使用rclone作为传输层。rclone负责处理所有Google Drive API通信——OAuth、文件传输、格式转换、重试/速率限制。

gdrive

在其之上添加了智能功能：一个追踪已同步文件的清单、支持格式感知的推送/拉取（可将Google Docs重新导入为原生格式）、冲突检测以及多远程管理。可以把rclone看作引擎，gdrive则是驾驶员。

专为拉取-编辑-推送周期设计，尤其适合搭配Anthropic官方的文档技能来读取和编辑办公文件：

docx

、

xlsx

、

pptx

和

pdf

（来自

https://github.com/anthropics/skills

）。

Before First Use

首次使用前准备

Before running any gdrive command, ensure dependencies are available. Check and install silently -- don't ask the user for permission to install these.

rclone: Run

which rclone

. If missing, install it:

Linux:

sudo apt install -y rclone

(or

curl https://rclone.org/install.sh | sudo bash

)

macOS:
```
brew install rclone
```

uv: Run

which uv

. If missing:

curl -LsSf https://astral.sh/uv/install.sh | sh

Project sync: Run
```
uv sync --project <skill-dir>
```
to ensure the venv and deps are ready.
Auth: Run
```
gdrive ls
```
. If it shows "No remotes configured", the user needs to run
```
gdrive auth setup
```
(interactive -- tell the user what's about to happen and that they'll need to complete OAuth in a browser).

For headless machines (no

$DISPLAY

), instruct the user to set up an SSH tunnel first:

ssh -L 53682:localhost:53682 <remote-host>

Then run

gdrive auth setup

on the remote host and open the printed URL on their local machine.

See

references/setup.md

for the full setup guide.

运行任何gdrive命令之前，请确保依赖项已就绪。自动检查并安装——无需询问用户权限即可安装这些依赖。

rclone：运行

which rclone

。如果未找到，则安装它：

Linux：

sudo apt install -y rclone

（或

curl https://rclone.org/install.sh | sudo bash

）

macOS：
```
brew install rclone
```

uv：运行

which uv

。如果未找到：

curl -LsSf https://astral.sh/uv/install.sh | sh

项目同步：运行
```
uv sync --project <skill-dir>
```
确保虚拟环境和依赖已准备好。
认证：运行
```
gdrive ls
```
。如果显示 "No remotes configured"，用户需要运行
```
gdrive auth setup
```
（交互式操作——告知用户即将发生的操作，以及他们需要在浏览器中完成OAuth认证）。

对于无图形界面的机器（无

$DISPLAY

），指导用户先建立SSH隧道：

ssh -L 53682:localhost:53682 <remote-host>

然后在远程主机上运行

gdrive auth setup

，并在本地机器上打开打印出的URL。

完整设置指南请查看

references/setup.md

。

Invocation

调用方式

All commands use this pattern:

bash

uv run --project /path/to/skills/google-drive gdrive <command> [args]

For brevity, examples below use

gdrive

directly.

所有命令遵循以下模式：

bash

uv run --project /path/to/skills/google-drive gdrive <command> [args]

为简洁起见，以下示例直接使用

gdrive

。

Commands

命令

auth -- Manage remotes

auth -- 管理远程连接

bash

gdrive auth setup     # interactive: configure rclone remotes (run once per machine)
gdrive auth status    # report which remotes are configured and authenticate
gdrive auth logout    # forget gdrive's remote registrations (rclone state stays)

bash

gdrive auth setup     # 交互式操作：配置rclone远程连接（每台机器运行一次）
gdrive auth status    # 报告已配置的远程连接及认证状态
gdrive auth logout    # 清除gdrive的远程注册信息（rclone状态保留）

ls -- List drives or files

ls -- 列出云端或文件

bash

undefined

bash

undefined

List configured remotes

列出已配置的远程连接

gdrive ls

List files at a remote path

列出远程路径下的文件

gdrive ls mydrive: gdrive ls mydrive:Projects/2025/

Detailed listing

详细列表

gdrive ls -l mydrive:Reports/

Recursive listing

递归列出

gdrive ls -R mydrive:Templates/

undefined

gdrive ls -R mydrive:Templates/

undefined

cp -- Copy files on remote

cp -- 在远程端复制文件

bash

gdrive cp mydrive:Reports/Q4-Summary.docx mydrive:Archive/Q4-Summary.docx

Server-side copy. Works across different remotes (unlike mv). Does not update the manifest.

bash

gdrive cp mydrive:Reports/Q4-Summary.docx mydrive:Archive/Q4-Summary.docx

服务器端复制。可跨不同远程连接使用（与mv不同）。不会更新清单。

pull -- Download files

pull -- 下载文件

bash

undefined

bash

undefined

Download to current directory

下载到当前目录

gdrive pull mydrive:Reports/Q4-Summary

Download to specific location

下载到指定位置

gdrive pull mydrive:Reports/Q4-Summary ./reports/

Force overwrite local changes

强制覆盖本地更改

gdrive pull -f mydrive:Reports/Q4-Summary

Pull all files in a folder

拉取文件夹中的所有文件

gdrive pull mydrive:Reports/

Pull to a specific local directory

拉取到指定本地目录

gdrive pull mydrive:Reports/ ./local-reports/

Filter by glob pattern

按通配符模式过滤

gdrive pull mydrive:Reports/ --include "*.docx"

Recursive pull (includes subdirectories)

递归拉取（包含子目录）

gdrive pull -R mydrive:Projects/


Google Docs/Sheets/Slides are automatically exported:

| Google Format | Exported As |
|---|---|
| Google Doc | .docx |
| Google Sheet | .xlsx |
| Google Slides | .pptx |

The manifest tracks the original MIME type so push can re-import correctly.

gdrive pull -R mydrive:Projects/


Google Docs/Sheets/Slides会自动导出：

| Google格式 | 导出格式 |
|---|---|
| Google Doc | .docx |
| Google Sheet | .xlsx |
| Google Slides | .pptx |

清单会追踪原始MIME类型，以便推送时能正确重新导入。

push -- Upload files

push -- 上传文件

bash

undefined

bash

undefined

Push a tracked file (uses manifest for destination)

推送已追踪的文件（使用清单中的目标路径）

gdrive push ./Q4-Summary.docx

Push to explicit destination

推送到明确的目标路径

gdrive push ./report.docx mydrive:Reports/Q4-Summary.docx

Force overwrite

强制覆盖

gdrive push -f ./Q4-Summary.docx

Push all locally-modified tracked files

推送所有本地已修改的已追踪文件

gdrive push --all

Filter batch push by remote

按远程连接过滤批量推送

gdrive push --all -r mydrive

Force batch push (skip conflict checks)

强制批量推送（跳过冲突检查）

gdrive push --all -f


Format-aware upload: if a file was originally a Google Doc (per manifest), it's automatically re-imported as a Google Doc on push. For new files, you'll be prompted.

Conflict detection: if the remote file changed since last sync, push prompts before overwriting. Use `-f` to skip.

gdrive push --all -f


格式感知上传：如果文件原本是Google Doc（根据清单），推送时会自动重新导入为Google Doc。对于新文件，会提示用户。

冲突检测：如果远程文件自上次同步后已更改，推送前会提示确认。使用`-f`可跳过提示。

status -- Check sync state

status -- 检查同步状态

bash

undefined

bash

undefined

Show all tracked files

显示所有已追踪文件

gdrive status

Filter by remote

按远程连接过滤

gdrive status -r mydrive


Categories:
- **Up to date** -- local matches last sync
- **Local changes** -- local file modified since last pull
- **Missing locally** -- tracked file deleted or moved locally

gdrive status -r mydrive


分类：
- **最新** -- 本地文件与上次同步一致
- **本地已更改** -- 本地文件自上次拉取后已修改
- **本地缺失** -- 已追踪文件在本地被删除或移动

mkdir -- Create directories

mkdir -- 创建目录

bash

gdrive mkdir mydrive:Projects/2025/NewProject

bash

gdrive mkdir mydrive:Projects/2025/NewProject

mv -- Move files on remote

mv -- 在远程端移动文件

bash

gdrive mv mydrive:old/path.docx mydrive:new/path.docx

Updates manifest entries referencing the moved path.

bash

gdrive mv mydrive:old/path.docx mydrive:new/path.docx

更新清单中引用该移动路径的条目。

search -- Find files

search -- 查找文件

bash

undefined

bash

undefined

Search all configured remotes

在所有已配置的远程连接中搜索

gdrive search budget

Search a specific remote

在指定远程连接中搜索

gdrive search mydrive: budget report


Uses Google Drive's name-contains query. Shows results with file type, date, and web link.

gdrive search mydrive: budget report


使用Google Drive的名称包含查询。显示结果时会包含文件类型、日期和网页链接。

rm -- Delete remote files

rm -- 删除远程文件

bash

gdrive rm mydrive:path/to/old-file.docx
gdrive rm -f mydrive:path/to/old-file.docx  # skip confirmation

Deletes the remote file and cleans up any matching manifest entries.

bash

gdrive rm mydrive:path/to/old-file.docx
gdrive rm -f mydrive:path/to/old-file.docx  # 跳过确认

删除远程文件并清理清单中对应的条目。

untrack -- Remove from manifest

untrack -- 从清单中移除

bash

gdrive untrack ./local-file.docx

Removes the file from manifest tracking without deleting anything locally or on the remote.

bash

gdrive untrack ./local-file.docx

将文件从清单追踪中移除，不会删除本地或远程的文件。

doctor -- Health check

doctor -- 健康检查

bash

gdrive doctor

Validates: rclone installed, config file exists, all remotes have working tokens, no orphaned rclone remotes, all manifest entries have existing local files.

bash

gdrive doctor

验证：rclone已安装、配置文件存在、所有远程连接的令牌可用、无孤立的rclone远程连接、所有清单条目对应的本地文件存在。

open -- Get web URL

open -- 获取网页URL

bash

gdrive open mydrive:Reports/Q4-Summary

Prints the Google Drive web URL for the file.

bash

gdrive open mydrive:Reports/Q4-Summary

打印文件的Google Drive网页URL。

link -- Get shareable link

link -- 获取可分享链接

bash

gdrive link mydrive:Reports/Q4-Summary

Prints a shareable Google Drive link for the file.

bash

gdrive link mydrive:Reports/Q4-Summary

打印文件的Google Drive可分享链接。

share -- Set permissions

share -- 设置权限

bash

undefined

bash

undefined

Share with a user (default: reader)

与用户共享（默认：查看者）

gdrive share mydrive:Reports/Q4-Summary.docx user@example.com

Share as writer

以编辑者身份共享

gdrive share mydrive:Reports/Q4-Summary.docx user@example.com --role writer

Share as commenter

以评论者身份共享

gdrive share mydrive:Reports/Q4-Summary.docx user@example.com --role commenter

Share with anyone who has the link

与任何拥有链接的人共享

gdrive share mydrive:Reports/Q4-Summary.docx --anyone


Calls the Google Drive API directly (rclone has no sharing support). Uses the OAuth token from rclone config.

gdrive share mydrive:Reports/Q4-Summary.docx --anyone


直接调用Google Drive API（rclone不支持共享功能）。使用rclone配置中的OAuth令牌。

Workflow: Pull-Edit-Push

工作流：拉取-编辑-推送

The primary workflow for editing Google Drive documents:

bash

undefined

编辑Google Drive文档的主要工作流：

bash

undefined

1. Pull the document (exports Google Doc as .docx)

1. 拉取文档（将Google Doc导出为.docx）

gdrive pull mydrive:Proposals/Client-Brief

2. Edit with a document skill

2. 使用文档技能编辑

(use docx, xlsx, or pptx skill to read/modify the file)

（使用docx、xlsx或pptx技能读取/修改文件）

3. Check what changed

3. 检查更改内容

gdrive status

4. Push back (re-imports as Google Doc)

4. 推送回去（重新导入为Google Doc）

gdrive push ./Client-Brief.docx


**Mixed editing (agent XML + user in Google Docs):**
If the user edited the doc directly in Google Docs between sessions, the pulled version may have different structure (reordered sections, removed content). Always re-inspect with `pandoc` before editing XML. Don't assume previous XML line numbers or structure.

gdrive push ./Client-Brief.docx


**混合编辑（Agent XML + 用户在Google Docs中编辑）：**
如果用户在会话之间直接在Google Docs中编辑了文档，拉取的版本可能结构不同（章节重新排序、内容删除）。编辑XML之前务必使用`pandoc`重新检查。不要假设之前的XML行号或结构不变。

Manifest

清单

The manifest at

~/.config/skills/gdrive/manifest.json

tracks:

Remote location and Google Drive file ID
Original MIME type (for format-aware re-import)
MD5 hashes at last sync (local and remote)
Timestamps for change detection

The manifest enables:

Pushing tracked files without specifying the remote path
Detecting local modifications via MD5 comparison
Re-importing exported Google Docs as native format on push
Detecting moved files by MD5 hash

位于

~/.config/skills/gdrive/manifest.json

的清单会追踪：

远程位置和Google Drive文件ID
原始MIME类型（用于格式感知的重新导入）
上次同步时的MD5哈希值（本地和远程）
用于更改检测的时间戳

清单支持以下功能：

无需指定远程路径即可推送已追踪文件
通过MD5比较检测本地修改
推送时将导出的Google Docs重新导入为原生格式
通过MD5哈希检测移动的文件

Remote Naming Convention

远程连接命名规范

Shared drives are configured as separate rclone remotes. Pick a short prefix per drive so commands stay readable, e.g.:

```
mydrive
```
-- a personal My Drive
```
team-engineering
```
-- an engineering shared drive
```
team-design
```
-- a design shared drive

Lowercased, hyphenated names work best. The

auth

wizard suggests names based on each drive's title and lets you override.

共享云端配置为独立的rclone远程连接。为每个云端选择简短的前缀，以便命令保持可读性，例如：

```
mydrive
```
-- 个人云端
```
team-engineering
```
-- 工程团队共享云端
```
team-design
```
-- 设计团队共享云端

小写、连字符分隔的名称效果最佳。

auth

向导会根据每个云端的标题建议名称，并允许用户修改。

Troubleshooting

故障排除

"File not found" on pull -- Check the path with

gdrive ls remote:path/

first. Google Docs don't have file extensions on the remote.

Push doesn't re-import as Google Doc -- Ensure the file was originally pulled (has manifest entry with Google MIME type). For new files, use

--drive-import-formats

flag.

Manifest out of sync -- Run

gdrive untrack

on stale entries, or delete

~/.config/skills/gdrive/manifest.json

to reset.

General setup issues -- Run

gdrive doctor

to diagnose problems with rclone, remotes, and manifest health.

拉取时提示“文件未找到” -- 先使用

gdrive ls remote:path/

检查路径。Google Docs在远程端没有文件扩展名。

推送未重新导入为Google Doc -- 确保文件最初是通过拉取获得的（清单中有Google MIME类型的条目）。对于新文件，使用

--drive-import-formats

标志。

清单不同步 -- 对过时条目运行

gdrive untrack

，或删除

~/.config/skills/gdrive/manifest.json

重置清单。

通用设置问题 -- 运行

gdrive doctor

诊断rclone、远程连接和清单健康状况的问题。

Configuration Files

配置文件

Manifest:
```
~/.config/skills/gdrive/manifest.json
```
Config:
```
~/.config/skills/gdrive/config.json
```
rclone config:
```
~/.config/rclone/rclone.conf
```
(managed by rclone)
Override the gdrive config dir with
```
GDRIVE_CONFIG_DIR=/path/to/dir
```

清单：
```
~/.config/skills/gdrive/manifest.json
```
配置：
```
~/.config/skills/gdrive/config.json
```
rclone配置：
```
~/.config/rclone/rclone.conf
```
（由rclone管理）
使用
```
GDRIVE_CONFIG_DIR=/path/to/dir
```
覆盖gdrive配置目录

Migrating from earlier versions

从早期版本迁移

If upgrading from a build that stored config at

~/.config/gdrive/

, run

gdrive config migrate --apply

to move the manifest and config to the new location.

gdrive auth status

emits a

deprecation_warning

until the migration runs.

The interactive wizard previously invoked as

gdrive auth

is now

gdrive auth setup

. The bare

gdrive auth

is now a command group containing

setup

status

, and

logout

Add to

.gitignore

in any repo using this skill:

.gdrive-manifest.json

如果从将配置存储在

~/.config/gdrive/

的版本升级，请运行

gdrive config migrate --apply

将清单和配置移动到新位置。在完成迁移之前，

gdrive auth status

会发出

deprecation_warning

。

之前作为

gdrive auth

调用的交互式向导现在是

gdrive auth setup

。不带参数的

gdrive auth

现在是包含

setup

、

status

和

logout

的命令组。

在任何使用此技能的仓库中添加到

.gitignore

：

.gdrive-manifest.json