使用 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 CLIgws在 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-driveskills/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数组填入上一步得到的父文件夹 IDgws 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可以是逗号分隔的多个 IDremoveParents原父文件夹 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}请求体bodyfiles create的name、mimeType、parents--params {key: val}URL/查询参数files update的fileId、addParents、removeParentsfiles list的q--format FORMAT输出格式json默认、table、yaml、csvfiles 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.rsupload底层仍调用files.createdetermine_filename从本地路径推断文件名除非显式传入--namebuild_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检索等操作衔接。探索更多查看方法的完整 SchemaRecipe 只展示了每个方法最常用的参数但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 createapplication/vnd.google-apps.folder创建层级目录用parents字段挂载子文件夹用files update的addParents/removeParents移动既有文件用files listq查询验证结果。同时理解了--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），仅供参考