好奇心花园🪴

搜索

SearchSearch

最近的笔记

Google Workspace — 通过 gws CLI 或 Python 操作 Gmail、日历、云端硬盘、文档、表格

2026年5月24日13分钟阅读

{/* 本页面由 website/scripts/generate-skill-docs.py 从技能 SKILL.md 自动生成。请编辑源 SKILL.md 而非本页面。 */}

Google Workspace

通过 gws CLI 或 Python 操作 Gmail、日历、云端硬盘、文档、表格。

技能元数据

来源内置（默认安装）
路径skills/productivity/google-workspace
版本1.1.0
作者Nous Research
许可证MIT
平台linux, macos, windows
标签Google, Gmail, Calendar, Drive, Sheets, Docs, Contacts, Email, OAuth
相关技能himalaya

参考：完整 SKILL.md

:::info 以下是此技能被触发时 Hermes 加载的完整技能定义。这是技能激活时代理所看到的指令。 :::

Google Workspace

Gmail、日历、云端硬盘（Drive）、联系人（Contacts）、表格（Sheets）和文档（Docs）——通过 Hermes 管理的 OAuth 和轻量级 CLI 封装器实现。安装了 gws 时，技能将其用作执行后端以覆盖更广泛的 Google Workspace 功能；否则回退到捆绑的 Python 客户端实现。

参考资料

  • references/gmail-search-syntax.md — Gmail 搜索操作符（is:unread, from:, newer_than: 等）

脚本

  • scripts/setup.py — OAuth2 设置（运行一次以授权）
  • scripts/google_api.py — 兼容性封装 CLI。可用时优先使用 gws 执行操作，同时保留 Hermes 现有的 JSON 输出约定。

首次设置

设置完全非交互式——你可以逐步驱动，以便在 CLI、Telegram、Discord 或任何平台上工作。

首先定义快捷方式：

GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"

步骤 0：检查是否已设置

$GSETUP --check

如果显示 AUTHENTICATED，跳转到使用部分——设置已完成。

步骤 1：分类——询问用户需要什么

在开始 OAuth 设置之前，询问用户两个问题：

问题 1：“你需要哪些 Google 服务？仅邮件，还是也包括日历/云端硬盘/表格/文档？”

  • 仅邮件 → 他们根本不需要此技能。改用 himalaya 技能——它使用 Gmail 应用密码（设置 → 安全 → 应用密码），设置仅需 2 分钟。无需 Google Cloud 项目。
  • 邮件 + 日历 → 继续使用此技能，但在认证时使用 --services email,calendar，以便授权屏幕仅请求他们实际需要的权限。
  • 仅日历/云端硬盘/表格/文档 → 继续使用此技能，使用更窄的 --services 集，如 calendar,drive,sheets,docs。
  • 完整 Workspace 访问 → 继续使用此技能，使用默认的 all 服务集。

问题 2：“你的 Google 账户是否使用高级保护（Advanced Protection，需要硬件安全密钥才能登录）？如果不确定，很可能没有——这是你需要明确注册的功能。”

  • 否 / 不确定 → 正常设置。继续以下步骤。
  • 是 → 他们的 Workspace 管理员必须先将 OAuth 客户端 ID 添加到组织的已允许应用列表中，步骤 4 才能生效。请提前告知用户。

步骤 2：创建 OAuth 凭据（一次性，约 5 分钟）

告诉用户：

你需要一个 Google Cloud OAuth 客户端。这是一次性设置：

  1. 创建或选择项目： https://console.cloud.google.com/projectselector2/home/dashboard
  2. 从 API 库启用所需 API： https://console.cloud.google.com/apis/library 启用：Gmail API、Google Calendar API、Google Drive API、 Google Sheets API、Google Docs API、People API
  3. 在此处创建 OAuth 客户端： https://console.cloud.google.com/apis/credentials 凭据 → 创建凭据 → OAuth 2.0 客户端 ID
  4. 应用类型：“桌面应用” → 创建
  5. 如果应用仍处于测试状态，在此处将用户的 Google 账户添加为测试用户： https://console.cloud.google.com/auth/audience 受众 → 测试用户 → 添加用户
  6. 下载 JSON 文件并告诉我文件路径

重要 Hermes CLI 说明：如果文件路径以 / 开头，请不要在 CLI 中将裸路径作为单独消息发送，因为它可能被误认为是斜杠命令。而是在句子中发送，例如： JSON 文件路径是：/home/user/Downloads/client_secret_....json

一旦他们提供路径：

$GSETUP --client-secret /path/to/client_secret.json

如果他们粘贴的是原始的 client ID / client secret 值而不是文件路径，请自行为其编写一个有效的桌面 OAuth JSON 文件，保存在显式位置（例如 ~/Downloads/hermes-google-client-secret.json），然后对该文件运行 --client-secret。

步骤 3：获取授权 URL

使用步骤 1 中选择的服务集。示例：

$GSETUP --auth-url --services email,calendar --format json
$GSETUP --auth-url --services calendar,drive,sheets,docs --format json
$GSETUP --auth-url --services all --format json

这会返回包含 auth_url 字段的 JSON，并将确切 URL 保存到 ~/.hermes/google_oauth_last_url.txt。

此步骤的代理规则：

  • 提取 auth_url 字段，将该确切 URL 作为单行发送给用户。
  • 告诉用户，批准后浏览器可能会在 http://localhost:1 上失败，这是预期的。
  • 告诉用户复制浏览器地址栏中的完整重定向 URL。
  • 如果用户遇到 Error 403: access_denied，直接引导他们到 https://console.cloud.google.com/auth/audience 将自己添加为测试用户。

步骤 4：交换授权码

用户将粘贴回类似 http://localhost:1/?code=***&scope=... 的 URL，或仅粘贴代码字符串。两种方式均可。--auth-url 步骤在本地临时存储待处理的 OAuth 会话，以便 --auth-code 稍后能完成 PKCE 交换，即使在无头系统上也可行：

$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format json

如果 --auth-code 因代码过期、已被使用或来自旧的浏览器标签页而失败，现在会返回一个新的 fresh_auth_url。在这种情况下，立即将新 URL 发送给用户，让他们仅使用最新的浏览器重定向重试。

步骤 5：验证

$GSETUP --check

应显示 AUTHENTICATED。设置完成——令牌从此自动刷新。

注意事项

  • 令牌存储在 ~/.hermes/google_token.json 并自动刷新。
  • 待处理的 OAuth 会话状态/验证器临时存储在 ~/.hermes/google_oauth_pending.json，直到交换完成。
  • 如果安装了 gws，google_api.py 会将其指向相同的 ~/.hermes/google_token.json 凭据文件。用户无需运行单独的 gws auth login 流程。
  • 撤销：$GSETUP --revoke

使用

所有命令都通过 API 脚本进行。将 GAPI 设为快捷方式：

GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"

Gmail

# 搜索（返回 JSON 数组，包含 id, from, subject, date, snippet）
$GAPI gmail search "is:unread" --max 10
$GAPI gmail search "from:boss@company.com newer_than:1d"
$GAPI gmail search "has:attachment filename:pdf newer_than:7d"
 
# 读取完整消息（返回包含正文文本的 JSON）
$GAPI gmail get MESSAGE_ID
 
# 发送
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1><p>Details...</p>" --html
$GAPI gmail send --to user@example.com --subject "Hello" --from '"Research Agent" <user@example.com>' --body "Message text"
 
# 回复（自动串联并设置 In-Reply-To）
$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
$GAPI gmail reply MESSAGE_ID --from '"Support Bot" <user@example.com>' --body "Thanks"
 
# 标签
$GAPI gmail labels
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD

日历

# 列出事件（默认未来 7 天）
$GAPI calendar list
$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
 
# 创建事件（需要带时区的 ISO 8601）
$GAPI calendar create --summary "Team Standup" --start 2026-03-01T10:00:00-06:00 --end 2026-03-01T10:30:00-06:00
$GAPI calendar create --summary "Lunch" --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z --location "Cafe"
$GAPI calendar create --summary "Review" --start 2026-03-01T14:00:00Z --end 2026-03-01T15:00:00Z --attendees "alice@co.com,bob@co.com"
 
# 删除事件
$GAPI calendar delete EVENT_ID

云端硬盘（Drive）

# 搜索已有文件
$GAPI drive search "quarterly report" --max 10
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
 
# 获取单个文件的元数据
$GAPI drive get FILE_ID
 
# 上传本地文件（自动检测 MIME 类型）
$GAPI drive upload /path/to/report.pdf
$GAPI drive upload /path/to/image.png --name "Logo.png" --parent FOLDER_ID
 
# 下载（二进制文件原样下载；Google 原生文件导出为合理的默认格式——文档→pdf，表格→csv，幻灯片→pdf，绘图→png）
$GAPI drive download FILE_ID
$GAPI drive download DOC_ID --output ~/doc.pdf
$GAPI drive download DOC_ID --export-mime text/plain --output ~/doc.txt
 
# 创建文件夹
$GAPI drive create-folder "Reports"
$GAPI drive create-folder "Q4" --parent FOLDER_ID
 
# 共享
$GAPI drive share FILE_ID --email alice@example.com --role reader
$GAPI drive share FILE_ID --email alice@example.com --role writer --notify
$GAPI drive share FILE_ID --type anyone --role reader        # 拥有链接的任何人
$GAPI drive share FILE_ID --type domain --domain example.com --role reader
 
# 删除——默认移至回收站（可恢复）。使用 --permanent 跳过回收站。
$GAPI drive delete FILE_ID
$GAPI drive delete FILE_ID --permanent

联系人

$GAPI contacts list --max 20

表格（Sheets）

# 创建新的电子表格
$GAPI sheets create --title "Q4 Budget"
$GAPI sheets create --title "Inventory" --sheet-name "Stock"
 
# 读取
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
 
# 写入
$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'
 
# 追加行
$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'

文档（Docs）

# 读取
$GAPI docs get DOC_ID
 
# 创建新文档（可选包含正文文本）
$GAPI docs create --title "Meeting Notes"
$GAPI docs create --title "Draft" --body "First paragraph..."
 
# 在现有文档末尾追加文本
$GAPI docs append DOC_ID --text "Additional content to append"

输出格式

所有命令返回 JSON。使用 jq 解析或直接读取。关键字段：

  • Gmail 搜索：[{id, threadId, from, to, subject, date, snippet, labels}]
  • Gmail 获取：{id, threadId, from, to, subject, date, labels, body}
  • Gmail 发送/回复：{status: "sent", id, threadId}
  • 日历列表：[{id, summary, start, end, location, description, htmlLink}]
  • 日历创建：{status: "created", id, summary, htmlLink}
  • Drive 搜索：[{id, name, mimeType, modifiedTime, webViewLink}]
  • Drive 获取：{id, name, mimeType, modifiedTime, size, webViewLink, parents, owners}
  • Drive 上传：{status: "uploaded", id, name, mimeType, webViewLink}
  • Drive 下载：{status: "downloaded", id, name, path, mimeType}
  • Drive 创建文件夹：{status: "created", id, name, webViewLink}
  • Drive 共享：{status: "shared", permissionId, fileId, role, type}
  • Drive 删除：{status: "trashed" | "deleted", fileId, permanent}
  • 联系人列表：[{name, emails: [...], phones: [...]}]
  • Sheets 获取：[[cell, cell, ...], ...]
  • Sheets 创建：{status: "created", spreadsheetId, title, spreadsheetUrl}
  • Docs 创建：{status: "created", documentId, title, url}
  • Docs 追加：{status: "appended", documentId, inserted_at, characters}

规则

  1. 未经用户确认，切勿发送邮件、创建/删除日历事件、删除 Drive 文件、共享文件或修改文档/表格。 展示将要执行的操作（收件人、文件 ID、内容、共享角色）并请求批准。对于 drive delete，优先使用默认的回收站（可恢复）而非 --permanent。
  2. 首次使用前检查认证——运行 setup.py --check。如果失败，引导用户完成设置。
  3. 复杂查询使用 Gmail 搜索语法参考——通过 skill_view("google-workspace", file_path="references/gmail-search-syntax.md") 加载。
  4. 日历时间必须包含时区——始终使用带偏移的 ISO 8601（例如 2026-03-01T10:00:00-06:00）或 UTC（Z）。
  5. 尊重速率限制——避免快速连续调用 API。尽可能批量读取。

故障排除

问题修复
NOT_AUTHENTICATED运行上述设置步骤 2-5
REFRESH_FAILED令牌被撤销或过期——重新执行步骤 3-5
HttpError 403: Insufficient Permission缺少 API 范围——$GSETUP --revoke 然后重新执行步骤 3-5
AUTHENTICATED (partial) 或”令牌缺少范围”新的写入能力（Drive 写入/删除、Docs 创建/编辑）需要重新授权。$GSETUP --revoke 然后重新执行步骤 3-5 以授予升级后的范围
HttpError 403: Access Not ConfiguredAPI 未启用——用户需要在 Google Cloud Console 中启用它
ModuleNotFoundError运行 $GSETUP --install-deps
高级保护阻止认证Workspace 管理员必须将 OAuth 客户端 ID 加入白名单

撤销访问

$GSETUP --revoke

关系图谱

反向链接