Google Sheets 技能

通过 Google Sheets API v4 从 Google Sheets 获取数据，将数据缓存在本地磁盘，并基于该数据回答用户问题。

会话记忆

在整个对话过程中持续维护以下上下文，并在获取新信息时及时更新：

SHEET_CONTEXT = {
  spreadsheetId: null,   // 当前活跃的 Sheet ID
  activeTab: null,       // 当前正在操作的工作表（tab）
  tabs: [],              // 已缓存的工作表名称列表
  headers: {},           // 每个工作表的已缓存表头：{ tabName: [...] }
  rawData: {},           // 每个工作表的已缓存行数据：{ tabName: [[...]] }
  cacheFile: null,       // 磁盘上缓存文件的路径
}

规则：

• 一旦确定 spreadsheetId → 后续所有步骤均使用该 ID，不再重复询问
• 若缓存文件已存在且未过期（仍在 TTL 有效期内）→ 跳过 API 请求
• 在向用户提问前，必须始终先检查会话上下文

步骤 1 — 获取 Sheet ID

按如下顺序检查：

1. SHEET_CONTEXT.spreadsheetId 已设置 → 直接使用
2. 消息中包含 URL → 提取 /d/ 和 /edit 之间的 ID： https://docs.google.com/spreadsheets/d/**SHEET_ID**/edit
3. 用户直接提供 ID → 保存并立即使用
4. 以上均未找到 → **仅询问一次**：

“您能分享一下 Google Sheet 链接或 Sheet ID 吗？我会在本次对话中记住它 😊”

收到后 → 立即保存至 SHEET_CONTEXT.spreadsheetId 并继续执行后续步骤。

步骤 2 — 从 Google Sheets API 获取数据

使用 Google Sheets API v4。根据表格类型选择认证方式：

选项 A：公开表格（任何拥有链接的人都可访问）

# 列出所有工作表（tabs）
curl -s "https://sheets.googleapis.com/v4/spreadsheets/{SHEET_ID}?key={GOOGLE_API_KEY}&fields=sheets.properties" 
  | python3 -c "import sys,json; d=json.load(sys.stdin); [print(s['properties']['title']) for s in d['sheets']]"

# 获取指定工作表的数据
curl -s "https://sheets.googleapis.com/v4/spreadsheets/{SHEET_ID}/values/{TAB_NAME}!A1:Z1000?key={GOOGLE_API_KEY}" 
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d.get('values',[])))"

选项 B：私有表格（使用 Service Account 认证）

import os, json
from google.oauth2 import service_account
from googleapiclient.discovery import build

creds = service_account.Credentials.from_service_account_file(
    os.environ["GOOGLE_SERVICE_ACCOUNT_JSON"],
    scopes=["https://www.googleapis.com/auth/spreadsheets.readonly"]
)
service = build("sheets", "v4", credentials=creds)

# 列出所有工作表（tabs）
meta = service.spreadsheets().get(spreadsheetId=SHEET_ID).execute()
tabs = [s["properties"]["title"] for s in meta["sheets"]]

# 获取指定工作表的数据
result = service.spreadsheets().values().get(
    spreadsheetId=SHEET_ID,
    range=f"{TAB_NAME}!A1:Z1000"
).execute()
rows = result.get("values", [])

将结果分别保存至 SHEET_CONTEXT.headers[tabName] 和 SHEET_CONTEXT.rawData[tabName]。

步骤 3 — 磁盘缓存

将获取的数据缓存至磁盘，避免跨轮次重复调用 API。

缓存路径

~/.openclaw/workspace/.cache/sheets/{spreadsheetId}/{tabName}.json

缓存文件结构

{
  "spreadsheetId": "abc123",
  "tabName": "Sheet1",
  "fetchedAt": 1710000000,
  "ttl": 300,
  "headers": ["Name", "Status", "Date"],
  "rows": [
    ["Task A", "Done", "2024-01-01"],
    ["Task B", "Pending", "2024-01-02"]
  ]
}

缓存脚本（通过 exec 工具运行）

import os, json, time, shutil

CACHE_DIR = os.path.expanduser("~/.openclaw/workspace/.cache/sheets")
TTL = 300  # 5 分钟 — 若数据极少变动，可提升至 3600

def cache_path(sheet_id, tab):
    d = os.path.join(CACHE_DIR, sheet_id)
    os.makedirs(d, exist_ok=True)  # 首次使用时自动创建目录
    return os.path.join(d, f"{tab.replace('/', '_')}.json")

def load_cache(sheet_id, tab):
    path = cache_path(sheet_id, tab)
    if not os.path.exists(path):
        return None
    with open(path) as f:
        c = json.load(f)
    if time.time() - c.get("fetchedAt", 0) > c.get("ttl", TTL):
        return None  # 缓存已过期 — 将重新拉取
    return c

def save_cache(sheet_id, tab, headers, rows):
    path = cache_path(sheet_id, tab)
    with open(path, "w") as f:
        json.dump({
            "spreadsheetId": sheet_id,
            "tabName": tab,
            "fetchedAt": int(time.time()),
            "ttl": TTL,
            "headers": headers,
            "rows": rows
        }, f, ensure_ascii=False)

def clear_cache(sheet_id=None):
    target = os.path.join(CACHE_DIR, sheet_id) if sheet_id else CACHE_DIR
    if os.path.exists(target):
        shutil.rmtree(target)

缓存流程

cached = load_cache(SHEET_ID, TAB_NAME)
if cached:
    headers, rows = cached["headers"], cached["rows"]
else:
    # 从 API 拉取...
    headers, rows = fetched_rows[0], fetched_rows[1:]
    save_cache(SHEET_ID, TAB_NAME, headers, rows)

何时清空缓存

步骤 4 — 回答用户

• 始终注明数据来源的 Sheet / Tab 名称
• 展示多行数据时，使用 Markdown 表格
• 以与用户相同的 语言 回复
• 若数据超过 500 行，先分析前 200 行，并询问用户是否需要缩小查询范围

openclaw.json 中的配置

添加至 skills.entries 下（顶层字段，**不要**嵌套在 agents 内）：

公开表格

{
  "skills": {
    "entries": {
      "google-sheets-soha": {
        "enabled": true,
        "env": {
          "GOOGLE_API_KEY": "AIza..."
        }
      }
    }
  }
}

私有表格

{
  "skills": {
    "entries": {
      "google-sheets-soha": {
        "enabled": true,
        "env": {
          "GOOGLE_SERVICE_ACCOUNT_JSON": "/home/node/.openclaw/google-sa.json"
        }
      }
    }
  }
}

错误处理