核心用法
gws-sheets 是 Google Sheets API v4 的命令行封装工具，采用资源-方法式调用模式：
gws sheets <resource> <method> [flags]
主要功能模块
电子表格操作
spreadsheets.create：创建新表格spreadsheets.get / getByDataFilter：读取表格元数据，支持字段掩码过滤spreadsheets.batchUpdate：批量应用更新（原子性：任一失败则全部回滚）
数据值操作
spreadsheets.values：读写单元格值- 辅助命令
+append/+read：快速追加行和读取数据
元数据与开发
developerMetadata：读写开发者元数据sheets：工作表级别操作
显著优点
- 原子性批量操作：
batchUpdate确保多步骤更新的一致性 - 灵活的数据过滤：
getByDataFilter支持精确读取子集，减少 API 调用成本 - Schema 驱动：
gws schema命令辅助构建合法参数，降低 API 学习曲线 - Helper 命令简化：
+append/+read覆盖 80% 高频场景
潜在缺点与局限性
- 依赖预认证：需先完成 OAuth 流程（见
gws-shared/SKILL.md） - 无原生查询语法：复杂筛选需通过
getByDataFilter构造 DataFilter 对象 - 权限粒度粗：依赖 Google Cloud 项目级 OAuth 范围，非单元格级权限
- 无离线支持：纯在线 API 封装，断网即不可用
适合人群
- 需要将 Google Sheets 作为轻量级数据库的自动化脚本开发者
- CI/CD 流水线中需读写配置表或报告的技术团队
- 数据分析师：批量导出/同步表格数据到本地环境
常规风险
| 风险类型 | 说明 |
|---------|------|
| 数据覆盖 | `batchUpdate` 无内置预览，误操作可能批量破坏数据 |
| 权限泄露 | OAuth token 存储于本地，共享环境需配置 `gws-shared` 安全规则 |
| API 配额 | 每秒 100 请求限制，大规模操作需实现退避重试 |
| 版本漂移 | v0.22.1 锁定 Sheets API v4，需关注 Google 弃用通知 |
生态依赖
- 前置要求：必须配置
gws-shared完成认证与全局标志设置 - 扩展命令：
gws-sheets-append、gws-sheets-read提供场景化封装