用途
该技能用于管理用户的 Google Sheets 电子表格，所有操作通过 hatch_gws_cli 命令行工具完成，内置的 Google Workspace CLI 是唯一的实现路径。
主要能力
- 连接管理：查看连接状态、断开连接。
- 表格操作：获取表格信息、创建表格、读取单元格值、追加值、批量更新。
- 辅助命令：提供 +read、+append 等封装辅助命令。
- 内容格式化：通过 Sheets API 写入并设置样式，包括表头样式、数字格式、冻结表头行、设置列宽。
- 结果校验：写回后读取结果以确认表格内容正确。
使用方式
使用 exec 运行命令，基本形式为：
hatch_gws_cli sheets <resource> <method> [flags]
连接管理：
hatch_gws_cli sheets status hatch_gws_cli sheets disconnect
查看方法结构：
hatch_gws_cli schema sheets.spreadsheets.get hatch_gws_cli schema sheets.spreadsheets.create hatch_gws_cli schema sheets.spreadsheets.values.get hatch_gws_cli schema sheets.spreadsheets.values.append hatch_gws_cli schema sheets.spreadsheets.batchUpdate
常见原始 API 调用：
hatch_gws_cli sheets spreadsheets get --params '{"spreadsheetId":"<spreadsheet_id>"}'
hatch_gws_cli sheets spreadsheets create --json '{"properties":{"title":"My Spreadsheet"}}'
hatch_gws_cli sheets spreadsheets values get --params '{"spreadsheetId":"<spreadsheet_id>","range":"Sheet1!A1:D10"}'
hatch_gws_cli sheets spreadsheets values append --params '{"spreadsheetId":"<spreadsheet_id>","range":"Sheet1!A:D","valueInputOption":"USER_ENTERED"}' --json '{"values":[["a","b"],["c","d"]]}'
hatch_gws_cli sheets spreadsheets batchUpdate --params '{"spreadsheetId":"<spreadsheet_id>"}' --json '{"requests":[{"addSheet":{"properties":{"title":"Q2"}}}]}'
辅助命令：
hatch_gws_cli sheets +read ... hatch_gws_cli sheets +append ...
JSON 输出约定：
- status：解析 status、connect_url 和 disconnect_url。
- disconnect：解析 ok、action、status 和 disconnect_url。
格式化表格内容：
通过 Sheets API 写入和格式化表格，不要通过上传文件覆盖。使用 spreadsheets.create、values.update 或 values.append 写入值，并将 valueInputOption 设为 USER_ENTERED，以便 Sheets 解析日期、货币和公式。在一次 spreadsheets.batchUpdate 调用中设置样式：repeatCell 配合 userEnteredFormat 设置表头样式和数字格式；updateSheetProperties 冻结表头行；updateDimensionProperties 设置列宽。新建表格时也可以在 spreadsheets.create 请求体中携带这些格式。
写回后读取验证：
spreadsheets.get 默认不返回单元格数据，需要传入字段掩码，例如：
hatch_gws_cli sheets spreadsheets get --params '{"spreadsheetId":"<spreadsheet_id>","ranges":"<tab>!A1:F10","fields":"sheets(properties(title,gridProperties(frozenRowCount)),data(rowData(values(formattedValue,effectiveFormat(backgroundColor,numberFormat,textFormat)))))"}'
注意：不要用 drive files update 把 .xlsx 文件发布到表格上，因为 Google 会替换文件全部内容，从而丢弃其他标签页和用户的编辑。要修改表格的某一部分，应使用 values.update 或 spreadsheets.batchUpdate；要给用户可下载的工作簿，应构建表格产物并附加文件。
认证与首次使用
认证由封装命令的 status 和 disconnect 子命令处理，不要手写凭据文件或运行原始 gws auth 命令。
首次使用流程：
- 运行 hatch_gws_cli sheets status。
- 如果 status 不可用，告知用户此设备上 Google Sheets 不可用，不要提供替代集成方案或向用户索要凭据。
- 如果 status 为 not_connected 且存在 connect_url，将 <connect_url> 替换为返回的 URL，并分享如下 Markdown 链接：Connect Google Sheets；不要单独粘贴原始 URL。等待用户重新连接。
- 一旦 status 为 connected，即可继续执行 Sheets 操作。
操作规则
- 对不熟悉的 Sheets 方法先使用 schema，确保 --params 和 --json 符合当前内置 CLI 约定。
- 范围使用 A1 表示法，除非用户明确要求其他 API 路径。
- 创建表格、清空单元格以及编辑仅由用户拥有的表格，可在请求明确时直接进行。编辑共享表格前需确认，因为其内容可能被他人查看或修改。
- 将表格 ID 和工作表 ID 视为不透明字符串，只使用先前命令返回或用户明确输入的 ID。
- 运行 hatch_gws_cli sheets disconnect。运行后，若存在 disconnect_url，将 <disconnect_url> 替换为返回的 URL，并分享如下 Markdown 链接：Disconnect Google Sheets；不要单独粘贴原始 URL。
- 需要检查当前表格结构或单元格内容时，优先使用 spreadsheets.get 或 sheets +read。写入或设置样式时，遵循上文“格式化表格内容”。
- 读取或写入后，只向用户确认可见结果。除非用户要求或需要排查故障，不要在展示给用户的文本中暴露原始 API 标识符（表格 ID 和工作表 ID）或其他内部响应字段（分页令牌/游标、原始 JSON）；内部仍可继续使用它们串联后续命令。
适用场景
适用于需要通过命令行以编程方式读取、写入、创建和格式化 Google Sheets 的场景，例如批量追加数据、创建带格式的新表格、更新单元格内容等。
限制
- 所有操作必须通过 hatch_gws_cli 完成，内置 Google Workspace CLI 是唯一实现路径。
- 认证由封装命令处理，不能手写凭据或运行原始 gws auth 命令。
- 若设备上 status 不可用，则无法使用该技能，且不提供替代集成方案。
- 编辑共享表格前需确认。
- 不要通过上传 .xlsx 文件覆盖表格内容。
- 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。