核心用法
gws-drive 是 Google Workspace Drive API v3 的命令行封装，提供对 Google Drive 完整资源模型的程序化访问。基础调用范式为 gws drive <resource> <method> [flags]，覆盖 12 大类资源：files（文件）、drives（共享硬盘）、permissions（权限）、comments（评论）、replies（回复）、revisions（版本）、changes（变更追踪）、channels（推送通道）、accessproposals（访问申请）、approvals（审批）、apps（应用）及 operations（长时操作）。
高频场景：
- 文件管理：
files.create/upload/download/export/copy/update支持最大 5,120 GB 单文件上传，Google 文档导出限 10 MB - 共享硬盘：
drives.create/list/hide/unhide/update实现团队级存储空间管理 - 权限控制：
permissions.create/list/update/delete管理文件/硬盘级 ACL，注意并发操作仅保留最后更新 - 变更订阅：
changes.watch+channels.stop构建实时同步流水线 - 元数据检索：所有 list/get 方法需显式设置
fields参数控制返回字段
辅助工具：+upload 子命令提供带自动元数据的简化上传流；gws schema drive.<resource>.<method> 用于预检参数schema。
显著优点
1. 官方原生：直接映射 Google Drive REST API v3，功能完备度与官方文档 1:1 对应
2. 批量友好：支持 5TB+ 级大文件传输，满足企业级备份需求
3. 细粒度权限：支持共享硬盘、文件级、修订版本三级权限矩阵
4. 变更追踪：changes 资源提供增量同步能力，适合构建本地镜像
5. 标签系统：files.listLabels/modifyLabels 支持 Google Drive 标签策略集成
潜在局限与风险
功能局限：
- 并发限制：同一文件权限操作并发时仅最后更新生效，需客户端串行化
- 版本历史截断：
revisions.list对高频编辑文档可能返回不完整历史 - 导出限制：Google 文档导出内容硬限 10 MB，大文档需分批处理
- 访问申请权限：
accessproposals.list仅限审批者调用，普通用户 403
安全风险：
- OAuth 令牌：依赖
gws-shared的 OAuth2 凭据，需严格保管 refresh_token - 权限扩散：
permissions.create支持 anyoneWithLink 等公开范围，误配置可导致数据泄露 - 版本永久删除：
revisions.delete对二进制文件不可逆，且无法删除最终版本 - 24小时链接：
files.download生成的操作链接有效期仅 24 小时
适合人群
- 需要自动化 Google Drive 运维的 DevOps/系统管理员
- 构建本地-云端同步工具的开发工程师
- 企业 IT 团队进行共享硬盘治理与权限审计
- 需批量处理大文件传输的数据工程师
常规风险提示
- 认证失效：OAuth 令牌过期未刷新将导致所有 API 调用 401
- 配额耗尽：Drive API 存在项目级 QPS 限制，高频操作需申请配额提升
- 数据误删：
revisions.delete与files.update的 patch 语义可能产生非预期覆盖 - 权限升级：建议定期审计
permissions.list输出，清理异常共享配置