gsuite-sdk 让 Agent 通过 Python 和命令行读取 Google Workspace 资料，也能写表格、发邮件和管理日程。第一次使用建议只做一件事：读取自己创建的小表格，生成一份能逐项核对的状态摘要。
本文使用 SDK 0.5.0 的命令与当前官方 Skill。下面的任务是练习样例，不是一次真实账号试用。需要 Python 3.11+、可访问 Google API 的网络、自己的 Google 账号，以及能执行本地命令的 Claude Code 或 Codex。普通网页聊天中粘贴 Skill，不会自动获得本机命令行和 Google 授权。
先分清三个安装层次
Skill 是 Agent 的操作说明；gsuite-sdk[cli] 提供真正访问 Google 的 gsuite 命令；OAuth 决定这个账号允许命令访问什么。三者缺一，Agent 都不能凭空读取文件。
官方还提供带 MCP 的 Claude Code 插件，以及 REST API。先用 Skill + CLI 完成练习，不需要同时启动服务器或再装 MCP。适合希望进一步写 Python 数据流程的人；只想偶尔总结一张表，也可以直接把脱敏的表格导出给 Agent，不必承担 OAuth 配置。
1. 装 CLI，再装 Skill
在一个专用练习目录打开终端。以下虚拟环境命令用于 macOS/Linux；Windows 创建环境后使用 .venv\Scripts\Activate.ps1 激活。
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "gsuite-sdk[cli]==0.5.0"
gsuite --help
Python 命令可能叫 python；先确认它的版本至少是 3.11。gsuite --help 应显示命令帮助，这只能证明 CLI 可用，还不能证明 Google 授权成功。
在准备使用的项目目录安装官方 Skill：
npx skills add PabloAlaniz/google-suite --skill gsuite-sdk
在安装选择器中选择自己的 Agent，完成后开启新会话。Skill 与 Python 环境要让同一个 Agent 进程能够访问；若新终端找不到 gsuite，先重新激活环境，而不是再授权一次。已经安装官方插件的人先确认已有 Skill，避免重复安装不同版本。
2. 配置表格练习所需的授权
在 Google Cloud Console 创建或选用自己的项目，启用 Google Drive API 和 Google Sheets API。配置 Google Auth Platform 的应用信息和受众；External 应用处于 Testing 时，把自己加入测试用户。创建 Desktop app 类型的 OAuth 客户端，下载客户端 JSON。它不是 API key，也不是服务账号密钥。
把下载文件保存在项目之外的私有位置。然后在练习终端设置绝对路径，替换下方示例：
export GSUITE_CREDENTIALS_FILE="/absolute/private/credentials.json"
export GSUITE_TOKEN_DB_PATH="/absolute/private/tokens.db"
export GSUITE_DEFAULT_TIMEZONE="Asia/Shanghai"
gsuite auth login --scopes drive,sheets
gsuite auth status
登录在浏览器中由你完成。核对账号、应用名和权限；被组织策略或 Google 阻止时先处理配置问题。此次不需要 Gmail、Calendar、Tasks 或 Contacts。注意：drive,sheets 是服务权限集合，包含 Drive 和表格的完整权限，不是只读权限。我们接下来只执行读取，不代表令牌只能读。没有参数的默认登录还会请求 Gmail 和 Calendar。
令牌保存在 tokens.db。凭据和令牌都不要提交 Git、上传网站或贴进聊天；绝对路径也要在 Agent 的运行环境里设置。External + Testing 的这类授权可能在七天后需要重新登录，访问令牌的正常刷新与这种到期不是同一回事。
3. 准备一个能检查的表格
在 Google Sheets 手工新建测试表，把工作表标签改名为 Tasks，填入下面四行。这样不受默认标签是“工作表1”还是“Sheet1”的影响。
| Task | Owner | Status |
|---|---|---|
| Landing page | Ana | done |
| Signup form | Bo | doing |
| Release notes | Ana | todo |
复制表格网址。先在终端读一次，替换 YOUR_SPREADSHEET_ID：它是网址 /d/ 与 /edit 之间的字符串。
gsuite sheets read YOUR_SPREADSHEET_ID --sheet Tasks --range "A1:C4" -o json
--sheet 指定标签，--range 指定该标签里的单元格。不要把范围当成第二个位置参数。正常非空结果是二维数组：第一行是三个表头，后面是三条任务。检查任务、负责人和状态能否与浏览器中的表格对上；这一步通过，再让 Agent 做总结。
空范围在此版本会打印 No data found，而不是 JSON 的 []。自动流程不要只凭退出成功就认定拿到了完整数据；检查输出结构和必要表头，空结果单独处理。Google 可能省略末尾的空单元格，不能假设每行长度相同。
4. 给 Agent 第一个任务
在已加载 Skill、能使用这个虚拟环境的 Claude Code 或 Codex 会话中，可以这样输入：
使用 gsuite-sdk 读取这个测试表：[粘贴表格 URL]。
仅使用 Tasks 标签的 A1:C4，先检查三列表头和三条任务。
不要写入表格，也不要发送、分享或删除任何内容。
列出未完成任务，按负责人分组，保留任务名和原始状态。
说明你读取的标签和范围；读取失败或数据缺失时停止并说明。
检查摘要中应该只有 Signup form（Bo、doing）和 Release notes（Ana、todo），不应把已完成的 Landing page 算进去。这是按样例数据推导的验收标准，不是保证模型一定答对。核对读取范围、两条任务和两名负责人，再扩大到真实资料；不要用模型自己声称“完成”代替检查。
后续怎么用
每周项目摘要： 将读取范围扩大到实际任务区域，明确哪些状态算未完成、截止时间是哪一天。摘要保留原始状态，缺负责人或日期的行单独列出。只读摘要与写回计划是两步，先审核摘要再决定是否更新表格。
Python 数据处理： 当需要固定格式、校验和重复运行时，SDK 比长提示词更容易控制。可按 ID 打开表格并读取指定标签：
from gsuite_core import GoogleAuth
from gsuite_sheets import Sheets
doc = Sheets(GoogleAuth()).open_by_key("YOUR_SPREADSHEET_ID")
ws = doc.worksheet("Tasks")
if ws is None:
raise ValueError("Tasks worksheet is missing")
rows = ws.get("A1:C4")
print(rows)
脚本要在同样的环境变量下运行。按标题打开用 open(title)，按 ID 用 open_by_key(id)，不要混淆。get_all_records() 返回的值是字符串，统计金额前要明确转换规则；空格、货币符号和缺值都要处理。
写回或分享： 另做确认后的任务，先展示目标文件、标签、范围和将要改的值。SDK 的 update 与 append_rows 使用二维列表，例如一格也是 [["done"]]。CSV 导入可能覆盖数据，不能当成追加；发邮件、邀请参会和共享文件也都有外部影响。
卡住时先查哪一层
| 现象 | 先检查 |
|---|---|
找不到 gsuite | 是否安装 [cli]、当前终端是否激活正确环境、Agent 是否使用同一个 PATH。 |
CredentialsNotFoundError | 客户端 JSON 的绝对路径与读取权限；不要用 API key 替代。 |
浏览器 access_denied | 当前账号是否为测试用户，组织是否限制应用，客户端是否为 Desktop app。 |
| 授权成功但读表失败 | 是否启用两项 API、账号是否能打开该表、所授范围是否包含所需服务。 |
| 找不到工作表或读到另一张表 | 用浏览器复制 ID，确认标签是 Tasks；省略 --sheet 会读第一张标签。 |
| JSON 解析失败 | 是否使用 -o json，范围是否为空；先看实际输出，不要把错误文字交给摘要步骤。 |
TokenRefreshError | 先检查账号撤销、Testing 到期及本地令牌位置，再按官方流程重新登录。 |
403 不一定是缺 scope，也可能是文件权限或 API 未启用；不要一遇到错误就把授权扩大到 all。需要新增服务时，再启用对应 API、理解其权限，并用 --force --scopes ... 重新授权。
资料会去哪里
CLI 在本机使用你的 OAuth 调 Google API。Agent 读取的表格内容还可能进入所用模型服务的对话，因此“本地 CLI”不等于“资料全程离线”。首次使用选测试表，真实工作资料按组织规则处理。无需为本练习启动 gsuite serve，更不必把 REST 服务开放到公网。
这份说明围绕 0.5.0 的表格任务编写；官方 Skill 还覆盖其他 Workspace 服务。它与 Google 官方产品不是同一回事，也不提供无限 API 配额。若需求是通过 Python 延伸到数据处理，这条路径合适；若只想要更偏终端日常办公的方案，可以另看 GOG 使用指南，两套命令、授权和令牌不要混用。