google-sheets

用途

Google Sheets 技能用于通过 OAuth 认证读取、写入和管理 Google 表格数据。当用户提到「google sheets」「spreadsheet」「update sheet」「read sheet」「append to sheet」等关键词或相关引用时，适合加载此技能处理对应请求。

主要能力

该技能提供以下操作：

读取（Read）：通过 read_range() 读取指定范围的数据。
写入（Write）：通过 write_range() 向指定范围写入数据。
追加（Append）：通过 append_rows() 在表格末尾追加行。
清空（Clear）：通过 clear_range() 清除数值但保留格式。
批量（Batch）：通过 batch_update() 更新多个区域。
创建（Create）：通过 create_spreadsheet() 新建表格。
信息（Info）：通过 get_spreadsheet_info() 获取元数据和工作表列表。
列表（List）：通过 list_spreadsheets() 列出可访问的表格。

使用方式

预检（始终第一步）

先执行认证检查：

python3 00-system/skills/google/google-master/scripts/google_auth.py --check --service sheets

退出码含义：

0：就绪，继续处理用户请求。
1：需要登录，运行 python3 00-system/skills/google/google-master/scripts/google_auth.py --login。
2：缺少依赖，参见 setup-guide。

常用命令

读取数据：

python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py read <spreadsheet_id> "Sheet1!A1:D10"

写入数据：

python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py write <spreadsheet_id> "Sheet1!A1" --values '[["Name", "Amount"], ["Contract A", 5000]]'

追加行：

python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py append <spreadsheet_id> "Sheet1!A:D" --values '[["New Row", "Data", "Here", "Now"]]'

获取表格信息：

python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py info <spreadsheet_id>

列出表格：

python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py list --query "tracking"

创建表格：

python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py create "New Spreadsheet" --sheets "Data" "Summary"

常见工作流

提取数据并更新表格：

from sheets_operations import append_rows

data = [
    ["Contract A", "2024-01-15", 5000, "Active"],
    ["Contract B", "2024-02-01", 7500, "Pending"]
]
result = append_rows(spreadsheet_id, "Contracts!A:D", data)
print(f"Added {result['updated_rows']} rows")

批量更新多个单元格：

from sheets_operations import batch_update

data = [
    {"range": "Sheet1!A1", "values": [["Header 1"]]},
    {"range": "Sheet1!B1", "values": [["Header 2"]]},
]
batch_update(spreadsheet_id, data)

表格 ID 与 A1 记法

表格 ID 位于 URL 中：

https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit

A1 记法示例：

A1：单个单元格
A1:B5：从 A1 到 B5 的范围
Sheet1!A1:B5：特定工作表中的范围
A:A：整列 A
1:1：整行 1

适用场景

适合需要把外部数据写入表格、向表格追加记录、批量更新多个单元格，或创建与列出表格的自动化任务。

限制与准备

首次使用需要在 Google Cloud Console 配置 OAuth 凭据（启用 Google Sheets API 与 Drive API，选择「Desktop app」），安装依赖：

pip install google-auth google-auth-oauthlib google-api-python-client

并在 Nexus 根目录的 .env 文件中配置：

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_PROJECT_ID=your-project-id

然后运行：

python3 00-system/skills/google/google-master/scripts/google_auth.py --login

关于错误处理的常见问题与解决方案，参见配套的 error-handling 参考文档。