核心用法
gws-sheets 是 gws 工具套件中专用于 Google Sheets API v4 的命令行技能。基础调用格式为 gws sheets <resource> <method> [flags]，涵盖 spreadsheets、values、sheets、developerMetadata 四大资源类别。核心能力包括：创建表格 (create)、全量获取 (get)、批量更新 (batchUpdate)、数据过滤读取 (getByDataFilter)，以及嵌套的 values 资源操作（读/写单元格）。
工具提供两个 Helper 命令加速常见场景：+append 快速追加行数据，+read 直接读取表格内容。所有 API 调用前建议先用 gws schema sheets.<resource>.<method> 查看参数结构，通过 --params 或 --json 传入请求体。
显著优点
1. 原生 API 覆盖完整：直接映射 Sheets API v4 全部功能，无抽象层损耗，支持批量更新原子性（全部成功或全部失败）。
2. 数据筛选精确：getByDataFilter 支持 DataFilters 多条件过滤，避免全表下载，降低带宽与成本。
3. 元数据操作能力：独立的 developerMetadata 资源，支持读写表格/工作表/行列级别的开发者元数据，便于构建复杂数据索引。
4. CLI 集成友好：与 gws 共享认证体系（见 gws-shared/SKILL.md），单点登录后多技能复用凭证。
潜在缺点与局限性
- 学习曲线陡峭：需理解 Sheets API 的资源模型（spreadsheet → sheet → range），
gws schema输出为原始 JSON Schema，对非开发者不友好。 - 无离线能力：完全依赖 Google 云端服务，网络中断即不可用。
- 批量更新原子性陷阱：虽然
batchUpdate保证事务性，但错误定位需解析 replies 数组中的空值位置，调试成本高。 - 版本锁定：v0.22.4 绑定特定 API 版本，Google 新版功能可能存在滞后。
适合人群
- 数据工程师/分析师：需将 Sheets 作为轻量级数据存储或交接接口的自动化流程。
- DevOps/SRE：构建基于 Google Workspace 的运营看板或配置管理系统。
- 有一定 API 基础的开发者：能阅读 JSON Schema 并构造复杂请求体。
不适合：完全无编程背景的业务用户、需离线编辑的场景、对实时协作有强需求的团队（CLI 操作会覆盖他人编辑）。
常规风险
1. 数据覆盖风险：batchUpdate 和 values 写入操作默认无确认，错误范围参数可能导致整表数据被覆盖。
2. 配额消耗：Google Sheets API 有每日读写配额限制，高频自动化需监控用量。
3. 凭证泄露：共享 gws-shared 认证文件若权限配置宽松，可能导致整个 Google Workspace 数据暴露。
4. 并发编辑冲突：多人同时编辑时，CLI 读取的 get 结果可能瞬间失效，写入覆盖他人变更。