Google Sheets CLI

google-sheets-cli

通过本 skill 调用 Google Sheets API。适合新建、读取和编辑 Google Sheets 在线文档。

执行约定

• 给 Agent 解析的输出一律加 --json，并且全局参数必须放在子命令前。
• 写操作会真实修改在线表格；范围不确定时先读目标 range。

认证

OAuth 通常只需要配置一次；日常任务不要把认证细节加载进上下文。

• 查看当前凭据路径与认证状态：./scripts/gsheets_cli.py --json auth doctor。
• 缺少 client secret、token 失效、Workspace 策略阻止等认证问题，按 google-workspace-oauth.md 处理。

日常操作

常用命令族：

• auth import-client|login|doctor|logout|paths
• spreadsheet create|get
• values get|update|batch-update|append|clear|update-rich-text

示例：

./scripts/gsheets_cli.py --json spreadsheet create \
  --title "审计结果" --sheet-title "问题" --sheet-title "说明" \
  --frozen-row-count 1
./scripts/gsheets_cli.py --json spreadsheet get --spreadsheet-id <spreadsheet-id>
./scripts/gsheets_cli.py --json values get --spreadsheet-id <spreadsheet-id> --range "Sheet1!A1:D20"
./scripts/gsheets_cli.py --json values update --spreadsheet-id <spreadsheet-id> --range "Sheet1!B2" --values-json '[["DONE"]]'
./scripts/gsheets_cli.py --json values append --spreadsheet-id <spreadsheet-id> --range "Sheet1!A:D" --values-json '[["a","b","c","d"]]'

values update|batch-update|append 的每个单元格必须是 JSON 标量：string、number、boolean 或 null。Mongo Extended JSON 等对象值需先转换为字符串或拆成独立列；CLI 会在请求前报告具体的行列位置，避免收到难以定位的 Google API 400。

批量写入：

./scripts/gsheets_cli.py --json values batch-update \
  --spreadsheet-id <spreadsheet-id> \
  --updates-json '[{"range":"Sheet1!B2","values":[["DONE"]]},{"range":"Sheet1!C2","values":[["ok"]]}]'

复杂 JSON 可以使用 @path 从文件读取：

./scripts/gsheets_cli.py --json values batch-update \
  --spreadsheet-id <spreadsheet-id> \
  --updates-json @/tmp/sheets-updates.json \
  && rm -- /tmp/sheets-updates.json

如果 JSON 文件由 Agent 为当前单次写操作临时创建，且成功后不再复用，在同一次 shell 调用中把写操作与 rm -- <明确路径> 用 && 串行执行。写操作失败时保留文件，不要 使用 ; 无条件删除，也不要用变量、通配符或目录作为清理目标。用户提供的 JSON、 写入前的范围备份，以及后续验证或回滚仍需复用的文件不得自动清理。

读取格式与 table 元数据

spreadsheet get 默认只返回 metadata，可查看 sheet id、标题、filter、banded ranges 和 table 列定义；只读单元格内容用 values get --range。

需要单元格格式、下拉校验、列宽或行高时，通过 --range（可重复）和 --fields 限定返回内容，避免拉取大型 workbook 的全量 grid data：

./scripts/gsheets_cli.py --json spreadsheet get \
  --spreadsheet-id <spreadsheet-id> \
  --range "'Sheet1'!A1:H5" \
  --fields 'sheets(properties(sheetId,title),data(columnMetadata,rowMetadata,rowData(values(formattedValue,effectiveFormat,dataValidation))))'

--fields 使用 Sheets API 字段掩码，指定后由掩码决定是否返回 grid data，--include-grid-data 不再生效。

更新 table / dropdown 的注意事项

• 写线上表格前，先用 values get 备份目标范围到 /tmp/...json，并把所有写操作限定到目标 sheet/range；不要误动其它 tab。
• values update 只改值，不会自动扩展 Google Sheets table 的范围、列名、filter、banded range 或 dropdown metadata。新增列后，如果要保持 table 结构，需要用 Sheets API spreadsheets.batchUpdate 调 updateTable、updateBanding、setBasicFilter、updateDimensionProperties 等请求，并使用目标 sheet 的 sheetId 限定范围。
• Google Sheets API 当前的 TableColumnDataValidationRule 只能表达 dropdown 的 ONE_OF_LIST 选项，不能表达 Google Sheets UI 里的 dropdown chip 背景色、选项颜色、display style 或 multi-select 等 UI metadata。用 updateTable 重写 columnProperties 时，原 UI 选项颜色可能丢失。
• 不要尝试用 API 自动“修复” dropdown chip 颜色。已验证 copyPaste + PASTE_DATA_VALIDATION 不可靠，条件格式也不等价：设置背景色会把整个单元格染色，只设置文字色也只是灰色 chip 内的文字变色，都会偏离原生 chip 视觉。遇到这类需求时，应明确告知这是 Google Sheets API 缺口，保留现状、回退写入，或让用户在 UI/模板中手工维护。
• table dropdown 列不要再对同一范围叠加普通 setDataValidation；Google Sheets 会报错类似 无法对指定类型的列中的单元格进行此操作。应通过 updateTable.columnProperties[].dataValidationRule 维护 table dropdown 选项。

链接写入

• Google Sheets 不支持 Markdown 的 [text](url) 链接语法；不要把 Markdown 链接直接写进单元格并期待 UI 渲染成链接。
• 只需要整格都是同一个链接时，可用 values update --value-input-option USER_ENTERED 写入 =HYPERLINK("https://example.com", "显示文本")。注意：这种方式会让整个单元格显示文本都成为同一个链接。
• 只想让单元格中的一小段文字带链接时，不要现场写 Python；优先用 values update-rich-text。该命令会用 Sheets API updateCells 写 userEnteredValue.stringValue 和 textFormatRuns[].format.link.uri。

示例：只让备注里的 knots-frontend !96 这段文字带链接：

./scripts/gsheets_cli.py --json values update-rich-text \
  --spreadsheet-id <spreadsheet-id> \
  --range "Sheet1!I10" \
  --text "延期到 7/9：Backup AZ 约束仍在 knots-frontend !96 中。" \
  --links-json '[{"text":"knots-frontend !96","url":"https://git.example.com/group/project/-/merge_requests/96"}]'

如果同一段显示文字在单元格中出现多次，改用 start / end 明确字符位置：[{"start":18,"end":36,"url":"https://..."}]。

权限范围

CLI 使用 Google Sheets scope：https://www.googleapis.com/auth/spreadsheets。

该 scope 可读取和修改用户有权限访问的 Google Sheets。若公司 Workspace 阻止该 OAuth client 访问，需由 Workspace 管理员允许对应 OAuth Client ID。

参考

• gsheets_cli.py
• google-workspace-oauth.md
• Google Sheets API
• Read & write cell values