google-sheets

Google Sheets

与 Google Sheets 交互，以管理电子表格、处理数据和操作公式。

安装

依赖项：pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

设置验证

安装后，验证技能是否已正确配置：

$SKILL_DIR/scripts/google-sheets.py check

此命令将检查：

• Python 依赖项（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
• 身份验证配置
• 与 Google Sheets API 的连接

如果缺少任何内容，检查命令会提供设置说明。

身份验证

Google Sheets 使用 OAuth 2.0 进行身份验证。完整设置说明请参阅：

1. GCP 项目设置指南 - 创建项目并启用 Sheets API
2. Google OAuth 设置指南 - 配置凭据

快速开始

1. 创建 ~/.config/agent-skills/google.yaml：

   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   

2. 运行 $SKILL_DIR/scripts/google-sheets.py check，触发 OAuth 流程并验证设置。

遇到范围或身份验证错误时，请参阅 OAuth 故障排除指南。

命令

请参阅 permissions.md，了解各命令的读写分类。

check

验证配置和连接。

$SKILL_DIR/scripts/google-sheets.py check

此命令会验证：

• 已安装 Python 依赖项
• 已配置身份验证
• 可以连接到 Google Sheets API
• 创建测试电子表格以验证写入权限

auth setup

存储 OAuth 2.0 客户端凭据，以使用自定义 OAuth 流程。

$SKILL_DIR/scripts/google-sheets.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

凭据会保存到 ~/.config/agent-skills/google-sheets.yaml。

选项：

• --client-id - OAuth 2.0 客户端 ID（必需）
• --client-secret - OAuth 2.0 客户端密钥（必需）

auth reset

清除已存储的 OAuth 令牌。下一个需要身份验证的命令会自动触发重新身份验证。

$SKILL_DIR/scripts/google-sheets.py auth reset

遇到范围或身份验证错误时，请使用此命令。

auth status

显示当前 OAuth 令牌信息，不会调用 API。

$SKILL_DIR/scripts/google-sheets.py auth status

显示：是否已存储令牌、已授予的范围、刷新令牌是否存在、令牌过期时间以及客户端 ID。

spreadsheets create

创建新的 Google Sheets 电子表格。

$SKILL_DIR/scripts/google-sheets.py spreadsheets create --title "My Spreadsheet"

选项：

• --title - 电子表格标题（必需）
• --sheets - 以逗号分隔的工作表名称（可选）

示例：

# Create with default Sheet1
$SKILL_DIR/scripts/google-sheets.py spreadsheets create --title "Sales Data"

# Create with custom sheets
$SKILL_DIR/scripts/google-sheets.py spreadsheets create \
  --title "Q1 Report" \
  --sheets "Summary,January,February,March"

# Output:
# ✓ Spreadsheet created successfully
# Title: Q1 Report
# Spreadsheet ID: 1abc...xyz
# Sheets: 4 (Summary, January, February, March)
# URL: https://docs.google.com/spreadsheets/d/1abc...xyz/edit

spreadsheets get

获取电子表格元数据和结构。

$SKILL_DIR/scripts/google-sheets.py spreadsheets get SPREADSHEET_ID

参数：

• spreadsheet_id - Google Sheets 电子表格 ID

示例：

$SKILL_DIR/scripts/google-sheets.py spreadsheets get 1abc...xyz

# Output:
# Title: Sales Data
# Spreadsheet ID: 1abc...xyz
# Sheets: 2 (Sheet1, Summary)
# URL: https://docs.google.com/spreadsheets/d/1abc...xyz/edit

values read

读取范围内的单元格值。

$SKILL_DIR/scripts/google-sheets.py values read SPREADSHEET_ID --range "Sheet1!A1:D5"

参数：

• spreadsheet_id - Google Sheets 电子表格 ID

选项：

• --range - A1 表示法中的范围（必需，例如 "Sheet1!A1:D5"）
• --format - 值格式：FORMATTED_VALUE（默认）、UNFORMATTED_VALUE 或 FORMULA

示例：

# Read a range
$SKILL_DIR/scripts/google-sheets.py values read 1abc...xyz --range "Sheet1!A1:C3"

# Output (formatted as table):
# Name      | Age | City
# Alice     | 30  | NYC
# Bob       | 25  | LA

# Read formulas
$SKILL_DIR/scripts/google-sheets.py values read 1abc...xyz \
  --range "Sheet1!D1:D10" \
  --format FORMULA

有关 A1 表示法的详细信息，请参阅 references/range-notation.md。

values write

向范围写入值。

$SKILL_DIR/scripts/google-sheets.py values write SPREADSHEET_ID \
  --range "Sheet1!A1" \
  --values '[[\"Name\",\"Age\"],[\"Alice\",30]]'

参数：

• spreadsheet_id - Google Sheets 电子表格 ID

选项：

• --range - A1 表示法中的起始范围（必需）
• --values - 以 JSON 二维数组表示的值（必需）

示例：

# Write data starting at A1
$SKILL_DIR/scripts/google-sheets.py values write 1abc...xyz \
  --range "Sheet1!A1" \
  --values '[[\"Product\",\"Price\",\"Quantity\"],[\"Widget\",9.99,100]]'

# Write a single row
$SKILL_DIR/scripts/google-sheets.py values write 1abc...xyz \
  --range "Sheet1!A5" \
  --values '[[\"Total\",999,50]]'

# Output:
# ✓ Values written successfully
#   Updated cells: 6
#   Updated range: Sheet1!A1:C2

注意： 输入的值与用户手动输入的方式相同。公式以 = 开头。

values append

在工作表末尾追加行。

$SKILL_DIR/scripts/google-sheets.py values append SPREADSHEET_ID \
  --range "Sheet1" \
  --values '[[\"New\",\"Row\",\"Data\"]]'

参数：

• spreadsheet_id - Google Sheets 电子表格 ID

选项：

• --range - 工作表名称或范围（必需）
• --values - 以 JSON 二维数组表示的值（必需）

示例：

# Append a single row
$SKILL_DIR/scripts/google-sheets.py values append 1abc...xyz \
  --range "Sheet1" \
  --values '[[\"Charlie\",35,\"Chicago\"]]'

# Append multiple rows
$SKILL_DIR/scripts/google-sheets.py values append 1abc...xyz \
  --range "Sheet1" \
  --values '[[\"David\",28,\"Boston\"],[\"Eve\",32,\"Seattle\"]]'

# Output:
# ✓ Values appended successfully
#   Updated cells: 3
#   Updated range: Sheet1!A4:C4

清除值

清除范围内的值。

$SKILL_DIR/scripts/google-sheets.py values clear SPREADSHEET_ID --range "Sheet1!A1:D10"

参数：

• spreadsheet_id - Google Sheets 电子表格 ID

选项：

• --range - A1 表示法中的范围（必需）

示例：

# Clear a range
$SKILL_DIR/scripts/google-sheets.py values clear 1abc...xyz --range "Sheet1!A1:Z100"

# Output:
# ✓ Values cleared successfully
#   Cleared range: Sheet1!A1:Z100

**警告：**这只会清除值，不会清除格式，也不会清除受保护单元格中的公式。

sheets create

向电子表格中添加新工作表。

$SKILL_DIR/scripts/google-sheets.py sheets create SPREADSHEET_ID --title "New Sheet"

参数：

• spreadsheet_id - Google Sheets 电子表格 ID

选项：

• --title - 工作表标题（必需）

示例：

$SKILL_DIR/scripts/google-sheets.py sheets create 1abc...xyz --title "Q2 Data"

# Output:
# ✓ Sheet created successfully
#   Title: Q2 Data
#   Sheet ID: 123456789

sheets delete

从电子表格中删除工作表。

$SKILL_DIR/scripts/google-sheets.py sheets delete SPREADSHEET_ID --sheet-id 123456789

参数：

• spreadsheet_id - 工作表 ID（必需，不是标题！）

示例：

# Get sheet IDs first
$SKILL_DIR/scripts/google-sheets.py spreadsheets get 1abc...xyz

# Delete a sheet
$SKILL_DIR/scripts/google-sheets.py sheets delete 1abc...xyz --sheet-id 123456789

# Output:
# ✓ Sheet deleted successfully

**警告：**无法删除电子表格中最后剩下的工作表。

示例

创建并填充电子表格

# Create spreadsheet
$SKILL_DIR/scripts/google-sheets.py spreadsheets create --title "Employee Data"

# Write headers (use the spreadsheet ID from the output above)
$SKILL_DIR/scripts/google-sheets.py values write $SS_ID \
  --range "Sheet1!A1" \
  --values '[["Name","Department","Salary","Start Date"]]'

# Append employee records
$SKILL_DIR/scripts/google-sheets.py values append $SS_ID \
  --range "Sheet1" \
  --values '[["Alice","Engineering",120000,"2023-01-15"],["Bob","Sales",95000,"2023-03-01"]]'

# Add a summary sheet
$SKILL_DIR/scripts/google-sheets.py sheets create $SS_ID --title "Summary"

# Read the data
$SKILL_DIR/scripts/google-sheets.py values read $SS_ID --range "Sheet1!A1:D10"

使用公式

# Write data with formulas
$SKILL_DIR/scripts/google-sheets.py values write $SS_ID \
  --range "Sheet1!A1" \
  --values '[["Item","Price","Qty","Total"],["Widget",10,5,"=B2*C2"],["Gadget",20,3,"=B3*C3"]]'

# Read formulas
$SKILL_DIR/scripts/google-sheets.py values read $SS_ID \
  --range "Sheet1!D2:D3" \
  --format FORMULA

# Read calculated values
$SKILL_DIR/scripts/google-sheets.py values read $SS_ID \
  --range "Sheet1!D2:D3" \
  --format FORMATTED_VALUE

批量操作

#!/bin/bash
SS_ID="your-spreadsheet-id"

# Clear old data
$SKILL_DIR/scripts/google-sheets.py values clear $SS_ID --range "Sheet1!A1:Z1000"

# Write new data in batches
$SKILL_DIR/scripts/google-sheets.py values write $SS_ID \
  --range "Sheet1!A1" \
  --values '[["Date","Revenue","Expenses","Profit"]]'

for month in Jan Feb Mar; do
  $SKILL_DIR/scripts/google-sheets.py values append $SS_ID \
    --range "Sheet1" \
    --values "[[\"\$month\",10000,7000,\"=B${ROW}-C${ROW}\"]]"
done

错误处理

**身份验证和权限范围错误不可重试。**如果命令因身份验证错误、权限范围不足错误或权限被拒绝错误（退出代码 1）而失败，请停止并告知用户。不要重试或尝试自行解决问题——这些错误需要用户交互（基于浏览器的 OAuth 授权）。请引导用户查看 OAuth 故障排除指南。

可重试错误：速率限制（HTTP 429）和临时服务器错误（HTTP 5xx）可能在短暂等待后通过重试成功。其他所有错误都应报告给用户。

模型指导

此技能会进行需要结构化输入/输出的 API 调用。建议使用标准能力模型。

故障排除

找不到电子表格

确保使用 URL 中正确的电子表格 ID：

• URL：https://docs.google.com/spreadsheets/d/1abc...xyz/edit
• 电子表格 ID：1abc...xyz

无效范围错误

• 使用正确的 A1 表示法：Sheet1!A1:D5
• 含空格的工作表名称需要加引号：'My Sheet'!A1:B2
• 详情请参阅 references/range-notation.md

--values 的 JSON 解析错误

确保正确转义 JSON：

# Correct
--values '[["Hello","World"]]'
--values "[[\"Name\",\"Age\"]]"

# Incorrect
--values [[Hello,World]]  # Missing quotes

工作表 ID 与工作表标题

命令使用不同的标识符：

• sheets create - 使用标题（字符串）
• sheets delete - 使用工作表 ID（数字）
• 使用 spreadsheets get 查找工作表 ID

API 参考

如需高级用法，请参阅：

• Google Sheets API 文档
• 读取和写入单元格值
• A1 表示法参考
• 公式示例