Google Workspace Skill
Gmail、日历、Drive、联系人、Sheets 和 Docs 集成 for Hermes。使用 OAuth2 自动刷新令牌。当可用时，优先使用 Google Workspace CLI（gws） 以获得更广泛的覆盖，否则回退到 Google 的 Python 客户端库。
设置
设置完全由 Agent 驱动 — 让 Hermes 设置 Google Workspace，它会引导你完成每一步。流程：
- 启动设置：告诉 Hermes「设置 Google Workspace」
- OAuth 同意：Hermes 打开浏览器进行 Google OAuth 同意
- 授权：选择你的 Google 账户并授权
- 完成：Hermes 保存凭证并验证连接
可用工具
| 工具 | 描述 | 所需范围 |
|---|---|---|
gmail_send | 发送电子邮件 | gmail.send |
gmail_read | 读取邮件 | gmail.read |
gmail_search | 搜索邮件 | gmail.read |
calendar_list | 列出日历事件 | calendar.read |
calendar_create | 创建日历事件 | calendar.events |
drive_list | 列出 Drive 文件 | drive.read |
drive_upload | 上传文件到 Drive | drive.file |
sheets_create | 创建电子表格 | sheets |
sheets_update | 更新电子表格 | sheets |
docs_create | 创建文档 | docs |
示例用法
发送邮件
hermes > Send an email to [email protected] with subject "Meeting" and body "Let's meet tomorrow at 3pm"
查看日历
hermes > What's on my calendar for tomorrow?
上传文件
hermes > Upload my report.pdf to Drive
OAuth 范围
默认范围：
scopes:
- https://www.googleapis.com/auth/gmail.send
- https://www.googleapis.com/auth/gmail.readonly
- https://www.googleapis.com/auth/calendar
- https://www.googleapis.com/auth/drive.readonly
- https://www.googleapis.com/auth/drive.file
- https://www.googleapis.com/auth/spreadsheets
- https://www.googleapis.com/auth/documents
令牌管理
自动刷新
Hermes 自动处理 OAuth 令牌刷新。当访问令牌过期时，使用刷新令牌获取新令牌。
手动刷新
如果需要手动刷新：
hermes google-workspace auth refresh
检查状态
hermes google-workspace auth status
输出示例：
Google Workspace Status:
- Gmail: ✅ 已连接 ([email protected])
- Calendar: ✅ 已连接
- Drive: ✅ 已连接
- Sheets: ✅ 已连接
- Docs: ✅ 已连接
Token expires: 2026-04-01 12:00:00
错误处理
| 错误代码 | 含义 | 解决方法 |
|---|---|---|
NOT_AUTHENTICATED | 未进行身份验证 | 运行设置（让 Hermes 设置 Google Workspace） |
TOKEN_EXPIRED | 令牌已过期 | Hermes 自动刷新 |
INSUFFICIENT_PERMISSIONS | 范围不足 | 重新授权或调整范围 |
QUOTA_EXCEEDED | 超出 API 配额 | 等待或减少请求 |
NETWORK_ERROR | 网络问题 | 检查网络连接 |
配置
自定义范围
# config.yaml
google_workspace:
scopes:
- https://www.googleapis.com/auth/gmail.send
- https://www.googleapis.com/auth/calendar
# 添加或删除范围
多个账户
支持多个 Google 账户：
hermes google-workspace account add personal
hermes google-workspace account add work
hermes google-workspace account switch personal
安全说明
- 凭证存储在
~/.hermes/google_token.json - 客户端密钥存储在
~/.hermes/google_client_secret.json - 令牌不会显示给模型
- 支持 OAuth2 令牌撤销
故障排除
常见问题
Q: Hermes 说「Not authenticated」
A: 运行 hermes google-workspace auth setup 开始 OAuth 流程。
Q: Token 过期错误持续出现
A: 尝试 hermes google-workspace auth refresh --force。
Q: Gmail 发送失败 A: 确保你的 Google 账户允许「不够安全的应用」访问，或使用 App Password。