Google Workspace 技能
為 Hermes 提供 Gmail、日曆（Calendar）、雲端硬盤（Drive）、聯繫人（Contacts）、表格（Sheets）和文檔（Docs）的集成。使用 OAuth2 並支持自動刷新令牌。當可用時，優先使用 Google Workspace CLI (gws) 以獲得更廣泛的覆蓋範圍，否則回退到 Google 的 Python 客戶端庫。
技能路徑： skills/productivity/google-workspace/
設置
設置過程完全由代理驅動——請求 Hermes 設置 Google Workspace，它將引導你完成每一步。流程如下：
- 創建 Google Cloud 項目並啟用所需的 API（Gmail、日曆、雲端硬盤、表格、文檔、People）
- 創建 OAuth 2.0 憑據（桌面應用類型）並下載客戶端密鑰 JSON 文件
- 授權——Hermes 生成一個授權 URL，你在瀏覽器中批准，然後粘貼回重定向 URL
- 完成——此後令牌將自動刷新
如果你只需要電子郵件功能（不需要日曆/雲端硬盤/表格），請改用 himalaya 技能——它配合 Gmail 應用專用密碼使用，只需 2 分鐘即可完成設置。無需創建 Google Cloud 項目。
Gmail
搜索
$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。
閱讀
$GAPI gmail get MESSAGE_ID
以文本形式返回完整的消息正文（優先使用純文本，回退到 HTML）。
發送
# Basic send
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
# HTML email
$GAPI gmail send --to user@example.com --subject "Report" \
--body "<h1>Q4 Results</h1><p>Details here</p>" --html
# Custom From header (display name + email)
$GAPI gmail send --to user@example.com --subject "Hello" \
--from '"Research Agent" <user@example.com>' --body "Message text"
# With CC
$GAPI gmail send --to user@example.com --cc "team@example.com" \
--subject "Update" --body "FYI"
自定義 From 標頭
--from 標誌允許你自定義外發郵件的發件人顯示名稱。當多個代理共享同一個 Gmail 帳戶但你希望收件人看到不同的名稱時，這非常有用：
# Agent 1
$GAPI gmail send --to client@co.com --subject "Research Summary" \
--from '"Research Agent" <shared@company.com>' --body "..."
# Agent 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 命令：
$GAPI gmail reply MESSAGE_ID \
--from '"Support Bot" <shared@company.com>' --body "We're on it"
回覆
$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
自動將回復加入線程（設置 In-Reply-To 和 References 標頭）並使用原始消息的線程 ID。
標籤
# List all labels
$GAPI gmail labels
# Add/remove labels
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
日曆
# 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 (timezone required)
$GAPI calendar create --summary "Team Standup" \
--start 2026-03-01T10:00:00-07:00 --end 2026-03-01T10:30:00-07:00
# With location and attendees
$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"
# Delete event
$GAPI calendar delete EVENT_ID
日曆時間必須包含時區偏移量（例如 -07:00）或使用 UTC（Z）。像 2026-03-01T10:00:00 這樣不帶時區的日期時間是不明確的，將被視為 UTC。
雲端硬盤
$GAPI drive search "quarterly report" --max 10
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
表格
# Read a range
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
# Write to a range
$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"]]'
文檔
$GAPI docs get DOC_ID
返回文檔標題和全文內容。
聯繫人
$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 | 未在 Google Cloud Console 中啟用 API |
ModuleNotFoundError | 使用 --install-deps 運行設置腳本 |