核心用法
gws-sheets 是 Google Workspace CLI 工具套件中的 Sheets 操作模块，基于 Google Sheets API v4 构建。核心语法为 gws sheets <resource> <method> [flags]，支持 spreadsheets、values、sheets 等多维度资源操作。
主要功能覆盖：
- 表格生命周期管理：create（创建）、get（读取元数据）、batchUpdate（批量更新）
- 数据操作：通过
values子资源实现单元格级读写，支持+append/+read快捷命令 - 高级查询：getByDataFilter 配合 DataFilters 实现按需数据筛选，避免全量传输
- 元数据操作：developerMetadata 支持自定义开发元数据注入
典型工作流：先用 gws schema sheets.values.get 探查参数结构，再构造 --params 或 --json 调用。
显著优点
- 原生 API 映射：直接暴露 Sheets API v4 全部能力，无功能裁剪
- 批量原子性：batchUpdate 保证多操作要么全成功、要么全回滚
- 字段掩码支持：通过
fields参数精确控制返回数据量，降低带宽消耗 - 模块化设计：与
gws-sheets-read/gws-sheets-append等子技能解耦，按需组合
潜在局限
- 学习曲线陡峭：需熟悉 Google Sheets API 的资源模型（spreadsheet/sheet/values 层级）
- 无交互式体验：纯 CLI 驱动，无表格可视化预览，调试复杂公式时效率低
- OAuth 依赖：必须预配置 GCP 项目与 OAuth 凭据（见
../gws-shared/SKILL.md），个人用户配置成本较高 - 配额敏感：Google Sheets API 有默认 100 请求/100秒/用户 限制，大批量操作需实现退避重试
适合人群
- 数据工程师：需将 Sheets 作为轻量级数据仓库或配置中心
- DevOps/SRE：构建 CI/CD 流水线中涉及表格状态同步的场景
- 自动化开发者：用脚本替代手动表格维护，如日报生成、权限同步
常规风险
- 数据覆盖风险：batchUpdate 无预览机制，错误参数可能导致大规模数据丢失
- 权限扩散：OAuth token 通常携带完整 Sheets 权限，泄露后可被用于全表格访问
- API 变更追踪：Google API 偶有破坏性更新，需锁定
gws版本号（当前 v0.20.0） - 并发冲突：多客户端同时编辑时，last-write-wins 可能产生静默数据覆盖