核心用法
gws-sheets-append 是 gws 工具集的 Google Sheets 写入子命令，专用于向电子表格追加数据行。基础调用格式为 gws sheets +append --spreadsheet <ID>，支持两种数据传入方式：--values 接收逗号分隔的简单字符串（如 'Alice,100,true'），适用于单行快速追加；--json-values 接收 JSON 数组格式（如 '[["a","b"],["c","d"]]'），支持批量多行一次性插入。
显著优点
1. 双模式写入：兼顾简单场景（单 --values）与批量场景（--json-values），无需额外脚本转换格式
2. 命令行原生集成：作为 gws 生态的一部分，可与 gws-shared 的认证体系无缝衔接
3. 显式安全提示：文档中以 [!CAUTION] 明确标注 write 操作属性，强制要求用户确认机制
潜在局限
- 无内置预览：追加前无法查看表格当前状态，误操作可能导致数据错位
- 格式敏感：
--values的逗号分隔不支持含逗号的字段值，复杂数据需转 JSON 模式 - 依赖外部认证：需预配置
gws-shared的 OAuth 凭据，首次部署成本较高 - 无事务回滚：追加成功后无法通过本命令撤销
适合人群
- 需从 CI/CD 流水线、定时任务向 Google Sheets 推送数据的 DevOps 工程师
- 构建轻量级数据收集系统的后端开发者
- 熟悉命令行且已在使用
gws工具栈的技术团队
常规风险
| 风险类型 | 说明 |
|---------|------|
| 数据覆盖误操作 | 未确认目标 Sheet 即执行，可能写入错误工作表 |
| 凭证泄露 | `gws-shared` 的 token 若存储不当，可能导致 Sheets 数据被未授权访问 |
| API 配额耗尽 | 高频批量写入可能触发 Google Sheets API 速率限制 |
| 数据类型丢失 | 所有值以字符串形式写入，数值/日期格式需后续手动调整 |