核心用法
Google Sheets Agent 是一个轻量级、零依赖的 Node.js 脚本，专为由 AI Agent 设计的 Google Sheets 自动化操作。它完全摒弃了官方的 googleapis SDK，仅使用 Node.js 内置的 https 和 crypto 模块，通过服务账号（Service Account）JWT 认证实现 headless 访问。
主要功能
- list: 列出服务账号可访问的所有表格
- meta: 获取表格元数据（工作表名称、网格大小）
- read: 读取指定范围的数据（默认
Sheet1!A:ZZ） - append: 向表格追加行数据（通过 stdin 传入 JSON 数组）
- write: 覆盖指定范围的数据
认证机制
支持三种凭证加载方式（按优先级）：环境变量 GOOGLE_SA_KEY_JSON → 文件路径 GOOGLE_SA_KEY_FILE → 1Password CLI (op 命令)。Token 内存缓存 1 小时，自动处理刷新。
显著优点
1. 零依赖：无需安装 googleapis 等重型包，冷启动极快
2. 无头认证：服务账号 JWT 流程，彻底摆脱 OAuth 浏览器弹窗和人工授权
3. Agent 原生设计：纯 JSON 输出到 stdout，日志输出到 stderr，便于管道串联
4. 安全凭证管理：原生支持 1Password 集成，避免密钥硬编码
5. 权限粒度精细：读操作使用 spreadsheets.readonly，写操作才申请完整权限
潜在局限
- Google Cloud 门槛：需自行创建服务账号、启用 API、管理 IAM，对非技术用户有学习成本
- 非交互式限制：无法处理需要用户同意的 OAuth 场景（如访问终端用户的私人表格）
- 错误处理简约：依赖 exit code 和 stderr，复杂重试逻辑需外层封装
- 内存缓存限制：Token 仅内存缓存，进程重启需重新认证
适合人群
- 构建自动化工作流的开发者和技术型用户
- 需要将 Agent 输出持久化到表格的 AI 应用
- 追求极简依赖、快速部署的 Serverless/容器化场景
- 已使用 1Password 管理密钥的安全敏感团队
常规风险
1. 凭证泄露：服务账号 JSON 密钥一旦泄露，攻击者可获得永久访问权限（需通过 1Password 或安全密钥管理缓解）
2. 权限过度授予：若将服务账号设为表格 Owner，误操作 write 可能破坏数据（建议最小权限原则）
3. API 配额：Google Sheets API 有每日请求限额，高频写入场景需考虑批量优化
4. 依赖 Google Cloud 稳定性：服务账号机制依赖 Google IAM，区域性故障会影响可用性
---
来源：The Agent Wire / ClawHub，发布于 AI 技能共享平台