# Google Workspace

Gmail、Calendar、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 服务？仅邮件，还是也包括

Calendar/Drive/Sheets/Docs？"**

• 仅邮件（Email only） → 他们根本不需要本技能。改用 himalaya 技能

——它配合 Gmail 应用专用密码（Settings → Security → App

Passwords）使用，2 分钟即可完成设置。无需 Google Cloud 项目。

加载 himalaya 技能并按其设置说明操作。

• 邮件 + 日历（Email + Calendar） → 继续使用本技能，但在授权时使用

--services email,calendar，这样同意屏幕只会请求

他们实际需要的权限范围。

• 仅 Calendar/Drive/Sheets/Docs → 继续使用本技能，并使用更窄的

--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

凭据（Credentials）→ 创建凭据 → OAuth 2.0 客户端 ID

4. 应用类型："桌面应用（Desktop app）" → 创建

5. 如果应用仍处于测试（Testing）状态，在此处将用户的 Google 账户添加为测试用户：

https://console.cloud.google.com/auth/audience

受众（Audience）→ 测试用户 → 添加用户

6. 下载 JSON 文件并告诉我文件路径

重要的 Hermes CLI 提示：如果文件路径以 `/` 开头，在 CLI 中不要只发送裸路径作为独立消息，因为它可能被误认为是斜杠命令。请改为在句子中附带它，例如：

`The JSON file path is: /home/user/Downloads/client_secret_....json`

一旦他们提供路径：

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

如果用户粘贴的是原始客户端 ID / 客户端密钥值而不是文件路径，

请自行为他们编写一个有效的桌面 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。

本步骤的智能体（Agent）规则：

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

第 4 步：交换授权码

用户会粘贴回形如 http://localhost:1/?code=4/0A...&scope=... 的 URL，

或仅粘贴代码字符串，两种都可以。--auth-url 步骤会在本地保存一个

临时的待处理 OAuth 会话，这样 --auth-code 稍后就能完成 PKCE 交换，

即使在无头（headless）系统上也能工作：

$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

# Search (returns JSON array with 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"

# Read full message (returns JSON with body text)
$GAPI gmail get MESSAGE_ID

# Send
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
$GAPI gmail send --to user@example.com --subject "Report" --body "
Q4
Details...
" --html
$GAPI gmail send --to user@example.com --subject "Hello" --from '"Research Agent" ' --body "Message text"

# Reply (automatically threads and sets In-Reply-To)
$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
$GAPI gmail reply MESSAGE_ID --from '"Support Bot" ' --body "Thanks"

# Labels
$GAPI gmail labels
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD

Calendar

# List events (defaults to next 7 days)
$GAPI calendar list
$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z

# Create event (ISO 8601 with timezone required)
$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"

# Delete event
$GAPI calendar delete EVENT_ID

Drive

$GAPI drive search "quarterly report" --max 10
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5

Contacts

$GAPI contacts list --max 20

Sheets

# Read
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"

# Write
$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'

# Append rows
$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'

Docs

$GAPI docs get DOC_ID

输出格式

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

• Gmail 搜索（Gmail search）：[{id, threadId, from, to, subject, date, snippet, labels}]
• Gmail 读取（Gmail get）：{id, threadId, from, to, subject, date, labels, body}
• Gmail 发送/回复（Gmail send/reply）：{status: "sent", id, threadId}
• 日历列表（Calendar list）：[{id, summary, start, end, location, description, htmlLink}]
• 日历创建（Calendar create）：{status: "created", id, summary, htmlLink}
• 云端硬盘搜索（Drive search）：[{id, name, mimeType, modifiedTime, webViewLink}]
• 联系人列表（Contacts list）：[{name, emails: [...], phones: [...]}]
• 表格读取（Sheets get）：[[cell, cell, ...], ...]

规则

1. 未经用户确认，绝不发送邮件或创建/删除事件。 先展示草稿内容并请求批准。
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 步 |

| HttpError 403: Access Not Configured | API 未启用——用户需要在 Google Cloud Console 中启用它 |

| ModuleNotFoundError | 运行 $GSETUP --install-deps |

| 高级保护阻止授权 | Workspace 管理员必须将 OAuth 客户端 ID 加入白名单 |

撤销访问权限

$GSETUP --revoke