00:00:00
Google Workspace 技能
Hermes 的 Gmail、日历、云端硬盘、通讯录、表格和文档集成。使用支持自动令牌刷新的 OAuth2。当可用时优先使用 Google Workspace CLI (gws) 以获得更广泛的覆盖，否则回退到 Google 的 Python 客户端库。
技能路径： skills/productivity/google-workspace/
设置
设置完全由代理驱动 — 让 Hermes 设置 Google Workspace，它会引导您完成每个步骤。流程如下：
- 创建 Google Cloud 项目 并启用所需的 API（Gmail、日历、云端硬盘、表格、文档、通讯录）
- 创建 OAuth 2.0 凭据（桌面应用类型）并下载客户端密钥 JSON
- 授权 — Hermes 生成授权 URL，您在浏览器中批准，粘贴回重定向 URL
- 完成 — 从那时起令牌自动刷新
仅邮件用户
如果您只需要邮件（不需要日历/云端硬盘/表格），请改用 himalaya 技能 — 它使用 Gmail 应用密码，只需 2 分钟。无需 Google Cloud 项目。
Gmail
搜索
bash
$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"返回包含每条消息的 id、from、subject、date、snippet 和 labels 的 JSON。
阅读
bash
$GAPI gmail get MESSAGE_ID以文本形式返回完整邮件正文（优先纯文本，回退到 HTML）。
发送
bash
# 基本发送
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
# HTML 邮件
$GAPI gmail send --to user@example.com --subject "Report" \
--body "<h1>Q4 Results</h1><p>Details here</p>" --html
# 自定义 From 标头（显示名称 + 邮箱）
$GAPI gmail send --to user@example.com --subject "Hello" \
--from '"Research Agent" <user@example.com>' --body "Message text"
# 带抄送
$GAPI gmail send --to user@example.com --cc "team@example.com" \
--subject "Update" --body "FYI"自定义 From 标头
--from 标志允许您在外发邮件上自定义发件人显示名称。当多个代理共享同一个 Gmail 帐户但您希望收件人看到不同名称时，这很有用：
bash
# 代理 1
$GAPI gmail send --to client@co.com --subject "Research Summary" \
--from '"Research Agent" <shared@company.com>' --body "..."
# 代理 2
$GAPI gmail send --to client@co.com --subject "Code Review" \
--from '"Code Assistant" <shared@company.com>' --body "..."工作原理： --from 值在 MIME 消息上设置为 RFC 5322 From 标头。Gmail 允许自定义您自己认证邮箱地址的显示名称，无需任何额外配置。收件人看到自定义显示名称（例如 "Research Agent"），而邮箱地址保持不变。
重要： 如果您在 --from 中使用不同的邮箱地址（不是认证的帐户），Gmail 要求该地址在 Gmail 设置 → 帐户 → 发件地址中配置为作为别名发送。
--from 标志适用于 send 和 reply：
bash
$GAPI gmail reply MESSAGE_ID \
--from '"Support Bot" <shared@company.com>' --body "We're on it"回复
bash
$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."自动将回复串成线程（设置 In-Reply-To 和 References 标头）并使用原始消息的线程 ID。
标签
bash
# 列出所有标签
$GAPI gmail labels
# 添加/移除标签
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD日历
bash
# 列出事件（默认未来 7 天）
$GAPI calendar list
$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
# 创建事件（需要时区）
$GAPI calendar create --summary "Team Standup" \
--start 2026-03-01T10:00:00-07:00 --end 2026-03-01T10:30:00-07:00
# 带位置和参与者
$GAPI calendar create --summary "Lunch" \
--start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z \
--location "Cafe" --attendees "alice@co.com,bob@co.com"
# 删除事件
$GAPI calendar delete EVENT_ID警告
日历时间必须包含时区偏移（例如 -07:00）或使用 UTC（Z）。裸日期时间如 2026-03-01T10:00:00 是有歧义的，将被视为 UTC。
云端硬盘
bash
$GAPI drive search "quarterly report" --max 10
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5表格
bash
# 读取范围
$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"]]'文档
bash
$GAPI docs get DOC_ID返回文档标题和完整文本内容。
通讯录
bash
$GAPI contacts list --max 20输出格式
所有命令返回 JSON。每项服务的关键字段：
| 命令 | 字段 |
|---|---|
gmail search | id, threadId, from, to, subject, date, snippet, labels |
gmail get | id, threadId, from, to, subject, date, labels, body |
gmail send/reply | status, id, threadId |
calendar list | id, summary, start, end, location, description, htmlLink |
calendar create | status, id, summary, htmlLink |
drive search | id, name, mimeType, modifiedTime, webViewLink |
contacts list | name, emails, phones |
sheets get | 单元格值的二维数组 |
故障排除
| 问题 | 解决方法 |
|---|---|
NOT_AUTHENTICATED | 运行设置（让 Hermes 设置 Google Workspace） |
REFRESH_FAILED | 令牌已撤销 — 重新运行授权步骤 |
HttpError 403: Insufficient Permission | 缺少范围 — 撤销并使用正确的服务重新授权 |
HttpError 403: Access Not Configured | API 未在 Google Cloud Console 中启用 |
ModuleNotFoundError | 使用 --install-deps 运行设置脚本 |