使用 gws 命令行工具创建 Google Drive 文件夹结构并整理归档文件
【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli
导读
本指南讲解如何利用 Google Workspace CLI（gws）在 Google Drive 中创建层级化文件夹结构，并将散落的文件移动到正确位置，最终通过查询语句验证整理结果。gws不依赖静态命令列表，而是运行时从 Google Discovery Service 动态构建命令面，因此本文涉及的命令与底层 Drive API v3 方法一一对应。读完本文，你将掌握gws drive files create、gws drive files update、gws drive files list三个核心方法的完整用法，以及--json、--params、--format等标志位的实战技巧，可直接用于季度项目归档、文档分类整理等日常工作流。
背景：从 Recipe 到可执行命令
本文所讲解的流程来自仓库中的 AI Agent 技能（Skill）定义 skills/recipe-organize-drive-folder/SKILL.md，它属于gws内置的 "recipe"（配方）类技能，定位是生产力场景（domain: productivity）。该 Recipe 的元数据声明了两个依赖：
- 可执行文件：
gws（即 Google Workspace CLI 二进制） - 前置技能：
gws-drive（skills/gws-drive/SKILL.md）
同样的配方也以结构化数据形式登记在 crates/google-workspace-cli/registry/recipes.toml 中，名称为organize-drive-folder，类别为productivity，服务为drive，说明该 Recipe 可被 Agent 运行时（如 OpenClaw 等）直接检索并执行。
在动手之前，请确保：
gws已安装并位于$PATH（参考 README.md 的安装章节：可下载预编译二进制、npm install -g @googleworkspace/cli、cargo install或brew install googleworkspace-cli）；- 已完成认证，例如交互式 OAuth 登录
gws auth login，或设置GOOGLE_APPLICATION_CREDENTIALS指向服务账号密钥文件（见 skills/gws-shared/SKILL.md）。
核心操作流程
整个"整理文件夹"配方由四个步骤组成：创建项目文件夹 → 创建子文件夹 → 移动既有文件 → 验证结构。下面逐一展开。
步骤一：创建项目文件夹
文件夹在 Drive API 中本质上是一个mimeType为application/vnd.google-apps.folder的文件。因此创建文件夹使用的就是files.create方法，通过--json传入请求体：
gws drive files create --json '{"name": "Q2 Project", "mimeType": "application/vnd.google-apps.folder"}'命令执行后返回的是 JSON 结构（默认输出格式），其中包含新文件夹的id、name、mimeType、createdTime等字段。请记录返回的id，后续创建子文件夹和移动文件都需要它。
前置技能补充：
files.create是 Drive API v3 中创建文件与文件夹的通用入口，支持最大 5,120 GB 的上传媒体，可接受任意合法 MIME 类型（详见 skills/gws-drive/SKILL.md 中files.create的说明）。创建普通文件时只需将mimeType换成真实类型（如text/plain、application/pdf），创建文件夹则固定使用application/vnd.google-apps.folder。
步骤二：创建子文件夹并挂载到父目录
Drive 的层级结构通过parents字段表达：一个文件夹可以声明一个或多个父目录。创建子文件夹时，在请求体中追加parents数组，填入上一步得到的父文件夹 ID：
gws drive files create --json '{"name": "Documents", "mimeType": "application/vnd.google-apps.folder", "parents": ["PARENT_FOLDER_ID"]}'要点说明：
parents是数组，即使只有一个父目录也要写成["PARENT_FOLDER_ID"]的形式；- 按此模式可递归创建任意深度的目录树，例如先建
Q2 Project，再在其中建Documents、Reports、Assets等子文件夹； - 每次创建后都应记录返回的子文件夹
id，用于后续移动文件或继续嵌套。
步骤三：移动既有文件到目标文件夹
移动文件使用的是files.update方法的addParents/removeParents参数组合，这是 Drive API 标准的"多父目录"模型操作：为文件附加一个新父目录，同时从旧父目录移除，从而实现移动：
gws drive files update --params '{"fileId": "FILE_ID", "addParents": "FOLDER_ID", "removeParents": "OLD_PARENT_ID"}'参数说明：
| 参数 | 含义 | 说明 |
|---|---|---|
fileId | 待移动文件的 ID | 必填，位于 URL 路径中 |
addParents | 新父文件夹 ID | 可以是逗号分隔的多个 ID |
removeParents | 原父文件夹 ID | 若文件之前在根目录，需先确认其实际父目录 |
注意事项：
fileId、addParents、removeParents都是URL/查询参数，因此放在--params中，而不是--json（--json只承载请求体）。这是新手最容易混淆的地方，两者的区别在 skills/gws-shared/SKILL.md 的方法标志位表格中有明确说明：--params传 URL/query 参数，--json传请求体；- 如果只想把文件从根目录（My Drive 顶层）移入文件夹，需要知道它的当前父目录 ID。可先用
gws drive files get --params '{"fileId": "FILE_ID"}'查看返回的parents字段； - 由于该操作是写操作，建议先在命令末尾追加
--dry-run做本地校验（不会真正调用 API），确认无误后再执行。
步骤四：验证文件夹结构
移动完成后，用files.list配合q查询参数验证目标文件夹的内容。q是 Drive 的搜索查询语法，"FOLDER_ID in parents"会返回所有父目录为该文件夹的文件与子文件夹：
gws drive files list --params '{"q": "FOLDER_ID in parents"}' --format table这里使用了--format table将 JSON 响应渲染为对齐的文本表格，便于人工快速核对。可选的输出格式包括json（默认）、table、yaml、csv，由 crates/google-workspace-cli/src/formatter.rs 中的OutputFormat枚举定义与解析。
进阶验证技巧：
# 只看该文件夹下未被删除的内容（默认会包含回收站文件） gws drive files list --params '{"q": "FOLDER_ID in parents and trashed = false"}' --format table # 限定类型：只看子文件夹 gws drive files list --params '{"q": "FOLDER_ID in parents and mimeType = \"application/vnd.google-apps.folder\""}' --format table参数速查：--json、--params 与 --format
整个 Recipe 只用到两类传参方式和一种输出控制，理解它们的边界即可举一反三：
| 标志位 | 作用 | 本文中的应用 |
|---|---|---|
--json '{"key": "val"}' | 请求体（body） | files create的name、mimeType、parents |
--params '{"key": "val"}' | URL/查询参数 | files update的fileId、addParents、removeParents；files list的q |
--format <FORMAT> | 输出格式：json（默认）、table、yaml、csv | files list用table便于人工核对 |
--dry-run | 本地校验、不调用 API | 建议在写操作前使用 |
--page-all | 自动分页并以 NDJSON 流式输出 | 大批量归档时可配合jq处理 |
Shell 引号技巧（来自 skills/gws-shared/SKILL.md）：--json与--params的值必须整体包在单引号中，避免 shell 展开内层的双引号；如果查询条件中本身含双引号（如mimeType = "..."），在 bash 下可直接混用，但若在 zsh 中遇到!等特殊字符时需改用双引号包裹并转义内层引号。
源码视角：命令面如何被动态构建
理解上述命令的底层机制，有助于你在不查文档的情况下探索更多 Drive 操作。gws的命令面不是在编译期写死的，而是运行时从 Google Discovery Service 拉取 REST 描述（RestDescription）动态生成，相关逻辑位于 crates/google-workspace-cli/src/discovery.rs 与 crates/google-workspace-cli/src/commands.rs。这也是为什么gws drive --help能直接列出files、permissions、drives、changes等全部资源及方法——它们都来自官方 Discovery Document。
在动态命令之外，每个服务还可以注入自定义 Helper 命令。Drive 服务对应 crates/google-workspace-cli/src/helpers/drive.rs，其inject_commands方法注册了一个+upload辅助命令，用于"带自动元数据上传文件"：
# 直接上传到指定文件夹（自动推断文件名与 MIME 类型） gws drive +upload ./report.pdf --parent FOLDER_ID # 自定义目标文件名 gws drive +upload ./data.csv --name 'Sales Data.csv'从源码看（drive.rs），+upload底层仍调用files.create：determine_filename从本地路径推断文件名（除非显式传入--name），build_metadata将文件名与可选的parents组装成请求体，随后经由executor::execute_method执行真正的上传。--parent会被写入元数据的parents数组——这与步骤二中"创建子文件夹"时手写parents字段是同一个机制。仓库还为这些辅助函数提供了单元测试（drive.rs），覆盖显式命名、路径推断、非法路径、父目录元数据四种情况。
因此，如果你要把本地文件批量归档进刚建好的文件夹，与其逐个files.update，不如直接：
gws drive +upload ./Q2-budget.xlsx --parent FOLDER_ID完整实战：一次季度归档
把四个步骤串成一个完整场景（季度末归档）：
# 1. 创建项目文件夹 gws drive files create --json '{"name": "Q2 Project", "mimeType": "application/vnd.google-apps.folder"}' # → 记录返回 id，假设为 FOLDER_ID # 2. 创建子文件夹 gws drive files create --json '{"name": "Documents", "mimeType": "application/vnd.google-apps.folder", "parents": ["FOLDER_ID"]}' gws drive files create --json '{"name": "Reports", "mimeType": "application/vnd.google-apps.folder", "parents": ["FOLDER_ID"]}' # 3. 移动既有文件（写操作，可先加 --dry-run 演练） gws drive files update --params '{"fileId": "FILE_ID", "addParents": "FOLDER_ID", "removeParents": "OLD_PARENT_ID"}' # 4. 验证结构 gws drive files list --params '{"q": "FOLDER_ID in parents"}' --format table执行顺序与依赖关系：步骤一产出FOLDER_ID，步骤二依赖它作为parents，步骤三依赖步骤一/二产出的文件夹 ID 与文件的旧父目录 ID，步骤四再次依赖FOLDER_ID做验证。每步返回的id都值得保存，便于后续permissions.create共享、files.list检索等操作衔接。
探索更多：查看方法的完整 Schema
Recipe 只展示了每个方法最常用的参数，但gws提供了在线的 Schema 检视能力。gws schema命令接受service.resource.method形式的点分路径，从 Discovery Document 中解析出该方法的 HTTP 方法、URL 路径、全部参数（含必填、类型、默认值、枚举）、请求体与响应结构，实现细节见 crates/google-workspace-cli/src/schema.rs：
# 查看 files.list 的完整参数 gws schema drive.files.list # 查看 files.update 的参数（含 addParents/removeParents） gws schema drive.files.update # 查看 File 类型的字段定义 gws schema drive.File文档 skills/gws-drive/SKILL.md 也给出同样的建议：调用任何 API 方法前先用gws drive --help浏览资源与方法，再用gws schema drive.<resource>.<method>检视参数，最后依据输出构建--params与--json。例如files.update的参数列表会明确展示addParents、removeParents均为可重复字符串参数，files.list则会展示q、pageSize、fields等全部查询参数及其默认值，这比记忆本文的速查表更全面、更不会过时。
安全规则与写操作提示
整理文件夹属于写操作（创建、移动），请遵守 skills/gws-shared/SKILL.md 中的安全规则：
- 绝不直接输出密钥、令牌等敏感信息；
- 执行写/删命令前先与用户确认；
- 破坏性操作优先使用
--dry-run本地校验； - 涉及敏感内容时可使用
--sanitize <TEMPLATE>让响应经过 Model Armor 内容安全筛查。
对本文的流程而言，最实用的防御手段是：移动文件前先用files.get确认fileId与旧父目录 ID 无误，再用--dry-run演练files.update，最后才真正执行。
总结
围绕 skills/recipe-organize-drive-folder/SKILL.md 这份 Recipe，你已掌握一套完整的 Drive 文件夹整理闭环：用files create+application/vnd.google-apps.folder创建层级目录，用parents字段挂载子文件夹，用files update的addParents/removeParents移动既有文件，用files list+q查询验证结果。同时理解了--json（请求体）与--params（查询参数）的分工、--format table的输出渲染，以及gws schema这一随时可用的参数探索入口。这套方法论同样适用于recipe-create-events-from-sheet、recipe-bulk-download-folder等其他 Drive 相关配方，是使用gws管理 Workspace 文件的基础能力。
【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
