gws 快速上手基于 Google Discovery Service 动态生成命令面的 Workspace 全能 CLI【免费下载链接】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/cligwsGoogle Workspace CLI是一款为人类与 AI Agent 打造的单一命令行工具它的独特之处在于不内置静态命令列表而是在运行时读取 Google 官方的 Discovery Service 文档动态生成覆盖 Drive、Gmail、Calendar 及所有 Workspace API 的命令面。读完本文你将掌握gws的安装方式、三分钟快速上手流程以及其零样板代码 结构化 JSON 输出背后两阶段解析的架构原理并能立即用它完成列文件、读邮件等真实操作。设计理念零样板代码命令面由 Discovery 文档动态生成传统 REST 调用需要对着 API 文档手写curl而gws走了一条完全不同的路线它把 Google 官方的 Discovery Service 当作唯一的命令说明书在每次运行时动态构建 CLI 结构。这意味着当 Google 为某个 Workspace API 新增端点或方法时gws会自动感知并支持无需升级二进制文件。从源码结构看这一机制由三部分组成Discovery 文档的抓取与解析discovery.rs 定义了RestDescription、RestResource、RestMethod等数据结构将 Discovery JSON 反序列化为内存模型命令树的动态构建commands.rs 的build_cli把文档中的 resources/methods 递归映射为clap::Command子命令树两阶段参数解析main.rs 先读取第一个非标志参数识别服务名再用构建好的clap命令树重新解析剩余参数。以gws drive files list为例调用链是drive→ 解析为 Discovery API 名drive、版本v3见 services.rs→ 抓取并缓存 Discovery 文档 →build_cli生成files资源下的list方法 → 校验参数、鉴权、执行 HTTP 请求。安装方式gws提供多种安装途径你可以按环境选择。方式一下载预编译二进制推荐从 GitHub Releases 页面下载对应操作系统与架构的预编译二进制解压后将gwsWindows 下为gws.exe放入$PATH即可。当前仓库在 npm/package.json 中声明的支持平台包括平台目标三元组macOSApple Silicon / Intelaarch64-apple-darwin/x86_64-apple-darwinLinuxglibcaarch64-unknown-linux-gnu/x86_64-unknown-linux-gnuLinuxmuslaarch64-unknown-linux-musl/x86_64-unknown-linux-muslWindowsx86_64-pc-windows-msvc方式二npm便捷层npm 包本质上是下载 GitHub Release 二进制的自动化包装器需要 Node.js 18npm install -g googleworkspace/cli方式三从源码构建cargo install google-workspace-cli # crates.io # 或直接构建仓库 cargo build # 开发构建产物在 target/debug/gws方式四Nix仓库提供 Nix flake见 flake.nixnix run github:googleworkspace/cli快速开始安装完成后三条命令即可完成首次验证gws auth login # OAuth 登录 gws drive files list --params {pageSize: 5} # 列出最近 5 个 Drive 文件 gws gmail users.messages list --params {maxResults: 3} # 读取收件箱前 3 封邮件--params接收 JSON 字符串形式的 URL/查询参数--json则用于 POST/PATCH/PUT 的请求体。所有命令的输出默认都是结构化 JSON方便脚本与 AI Agent 直接消费。深入一个命令背后发生了什么服务注册表与版本解析gws内置了一份服务注册表services.rs把用户友好的别名映射到 Discovery API 名与版本号。当前支持 18 个服务包括drive(v3)、gmail(v1)、calendar(v3)、sheets(v4)、docs(v1)、chat(v1)、classroom(v1)、forms(v1)、keep(v1)、meet(v2)、tasks(v1)、people(v1)、script(v1)、slides(v1)、admin-reports(reports_v1)、events(workspaceevents v1)、modelarmor(v1)、workflow(v1) 等。对于未收录的 API还支持api:version语法直接指定。Discovery 文档抓取与 24 小时缓存discovery.rs 展示了两级 URL 策略先请求标准的https://www.googleapis.com/discovery/v1/apis/{service}/{version}/rest失败时回退到https://{service}.googleapis.com/$discovery/restForms、Keep、Meet 等新 API 使用该模式。文档会缓存到~/.config/gws/cache/目录由 google-workspace-cli 的 discovery.rs 封装TTL 为 24 小时命中缓存时直接反序列化返回避免重复网络请求。校验、鉴权与执行executor.rs 的execute_method是核心执行函数按顺序完成参数校验解析--params/--json的 JSON按 Discovery 文档 schema 校验请求体并检查必填参数如 path 参数缺失会立即报 Validation 错误URL 构建把 path 模板中的{param}占位符替换为实际值查询参数按 repeated 标记展开为多个 query 项鉴权从方法 scopes 列表中选取第一个通常是最宽的scope 换取 token请求发送与响应处理支持 JSON、二进制--output落盘两种响应二进制响应会流式写入文件并输出含saved_file、mimeType、bytes的 JSON 元数据。分页NDJSON 流式输出列表类方法常用分页gws提供三个标志默认值可参见 main.rs 与对应单测标志作用默认值--page-all自动翻页每页一行 JSONNDJSON关闭--page-limit N最大翻页数10--page-delay MS页间延迟100 msgws drive files list --params {pageSize: 100} --page-all | jq -r .files[].name翻页循环由nextPageToken驱动executor.rs并遵守--page-limit与--page-delay约束。安全辅助--dry-run 与路径校验--dry-run会在不发送真实请求的前提下本地校验参数并输出将发出的 URL、method、query 参数与 body。此外--upload与--output指定的文件路径会先经过路径穿越校验main.rs确认安全后才执行 I/O。常用标志速查标志说明--params JSONURL/查询参数JSON 字符串--json JSON请求体POST/PATCH/PUT--upload PATH以 multipart 方式上传本地文件作为媒体内容--upload-content-type MIME上传文件 MIME 类型省略时按扩展名自动推断--output PATH二进制响应的输出文件路径--format FMT输出格式json默认、table、yaml、csv--api-version VER覆盖 API 版本如 v2、v3--dry-run本地校验请求不真正发送结构化退出码脚本可以根据退出码分支处理而无需解析错误文本。退出码定义在 error.rs退出码含义典型场景0成功命令正常完成1API 错误Google 返回 4xx/5xx2鉴权错误凭据缺失、过期或无效3校验错误参数错误、未知服务、非法标志4Discovery 错误无法获取 API schema 文档5内部错误意外失败环境变量与配置文件gws全部环境变量均为可选GOOGLE_WORKSPACE_CLI_TOKEN预获取的 OAuth2 访问令牌优先级最高GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILEOAuth 凭据 JSON 路径用户或服务账号GOOGLE_WORKSPACE_CLI_CLIENT_ID/GOOGLE_WORKSPACE_CLI_CLIENT_SECRETOAuth 客户端 ID 与密钥GOOGLE_WORKSPACE_CLI_CONFIG_DIR覆盖配置目录默认~/.config/gwsGOOGLE_WORKSPACE_CLI_LOGstderr 日志级别如gwsdebug默认关闭GOOGLE_WORKSPACE_PROJECT_ID覆盖 GCP 项目 ID用于配额计费。环境变量也可写入.env文件入口在 main.rs 通过dotenvy自动加载。在仓库中继续深入根 README.md 提供了完整的鉴权流程、Agent Skills 索引与高级用法crates/google-workspace/src/services.rs 查看全部服务注册表crates/google-workspace/src/discovery.rs 查看 Discovery 文档解析与缓存实现crates/google-workspace-cli/src/commands.rs 查看命令树构建逻辑crates/google-workspace-cli/src/executor.rs 查看请求执行、multipart 上传与分页实现crates/google-workspace-cli/src/main.rs 查看两阶段解析的完整入口流程。开发者模式下可用cargo test运行单元测试覆盖分页默认值、服务解析、scope 选择、命令树构建等关键逻辑用./scripts/coverage.sh生成 HTML 覆盖率报告。提示本工具并非 Google 官方支持的产品Apache-2.0 许可见 LICENSE且处于活跃开发期v1.0 之前可能发生破坏性变更。【免费下载链接】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），仅供参考