核心用法
gws 是一个面向 Google Workspace 的通用命令行工具，采用 gws <service> <resource> [sub-resource] <method> 的层级结构。共享模式（gws-shared）作为所有服务子命令的基础，统一处理了三大能力：
1. 认证层：支持浏览器交互式 OAuth（gws auth login）与服务账号 JSON 密钥（GOOGLE_APPLICATION_CREDENTIALS 环境变量），覆盖人机交互与自动化 CI/CD 场景。
2. 全局参数：--format 控制输出格式（json/table/yaml/csv），--dry-run 支持本地验证不实际调用 API，--sanitize 集成 Model Armor 对响应内容进行 PII/安全筛查。
3. 请求构造：--params 注入 URL 参数，--json 构造请求体，--upload 支持 multipart 文件上传，--page-all 自动分页并以 NDJSON 流式输出。
显著优点
- 统一体验：跨 Google Sheets、Drive、Calendar 等服务保持一致的 CLI 语法与输出格式。
- 安全内置：
--dry-run与--sanitize原生支持，降低误操作与数据泄露风险；服务账号模式适合无人值守自动化。 - 分页友好：
--page-all配合--page-limit/--page-delay自动处理 API 分页，避免手动循环。 - 输出灵活：支持表格、YAML、CSV 等人类可读格式，便于管道化与脚本集成。
潜在缺点与局限性
- zsh 兼容性陷阱：
!字符在 zsh 中触发历史扩展，需用双引号包裹并转义，对新手不友好。 - JSON 嵌套引号：
--params/--json要求外层单引号、内层双引号，shell 语法敏感。 - Model Armor 依赖：
--sanitize功能需要外部 Model Armor 服务可用，非纯离线工具。 - 版本锁定：
requires: bins: - gws表明 Skill 与 CLI 二进制版本强绑定，升级需同步。
适合人群
- 需要批量操作 Google Workspace 数据的开发者与运维工程师
- 构建自动化工作流（如定时备份 Sheets、批量迁移 Drive 文件）的 DevOps 团队
- 希望通过命令行快速调试 Google API 的 Google Workspace 管理员
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 凭证泄露 | 服务账号密钥文件明文存储 | 使用密钥管理系统，设置 `GOOGLE_APPLICATION_CREDENTIALS` 指向安全路径 |
| 误删除/修改 | 写操作无二次确认 | 强制 `--dry-run` 预览，生产环境配合 `--page-limit` 限制范围 |
| PII 泄露 | API 响应包含敏感信息 | 启用 `--sanitize` 过滤，审计日志定期清理 |
| zsh 历史扩展 | `!` 被解释为历史命令 | 始终使用 `"Sheet1!A1"` 双引号包裹 |
> 来源可信度：Google 官方 Workspace CLI 项目（github.com/googleworkspace/cli），属 T1 级可信来源。