<!-- Source: https://hermesbible.com/docs/user-guide/skills/google-workspace -->

Section: Skills · URL: https://hermesbible.com/docs/user-guide/skills/google-workspace

Google Workspace Skill

Gmail、Calendar、Drive、Contacts、Sheets 與 Docs 整合工具，適用於 Hermes。使用 OAuth2 並支援自動 Token 刷新。優先使用 Google Workspace CLI (gws)（若已安裝可提供更完整的功能覆蓋），否則退回使用 Google 官方 Python Client Libraries。

Skill 路徑： skills/productivity/google-workspace/

設定

設定流程完全由 Agent 驅動——只要請 Hermes 設定 Google Workspace，它會引導你完成每個步驟。流程如下：

1. 建立 Google Cloud 專案 並啟用所需的 API（Gmail、Calendar、Drive、Sheets、Docs、People）
2. 建立 OAuth 2.0 憑證（選擇 Desktop app 類型）並下載 Client Secret JSON 檔案
3. 授權 — Hermes 產生授權 URL，你在瀏覽器中批准後，將 Redirect URL 貼回
4. 完成 — 後續 Token 會自動刷新

TIP — 僅需 Email 功能的使用者

如果你只需要 Email 功能（不需要 Calendar/Drive/Sheets），可以改用 himalaya skill——它透過 Gmail App Password 運作，設定僅需 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"

回傳 JSON 格式，每封郵件包含 id、from、subject、date、snippet 和 labels 欄位。

讀取

$GAPI gmail get MESSAGE_ID

回傳完整郵件內文（優先使用純文字格式，若無則使用 HTML）。

傳送

# 基本傳送
$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

# 自訂寄件者標頭（顯示名稱 + Email）
$GAPI gmail send --to user@example.com --subject "Hello" \
  --from '"Research Agent" <user@example.com>' --body "Message text"

# 附帶 CC
$GAPI gmail send --to user@example.com --cc "team@example.com" \
  --subject "Update" --body "FYI"

自訂寄件者標頭

--from 參數可用於自訂 outgoing 郵件的寄件者顯示名稱。當多個 Agent 共用同一個 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 允許你在已驗證的 Email 地址上自訂顯示名稱，無需額外設定。收件者會看到自訂的顯示名稱（例如 "Research Agent"），而 Email 地址保持不變。

重要： 如果你在 --from 中使用了不同的 Email 地址（非驗證帳號的地址），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 標頭），並使用原始郵件的 Thread ID。

標籤

# 列出所有標籤
$GAPI gmail labels

# 新增/移除標籤
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD

Calendar

# 列出事件（預設為接下來 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

WARNING

Calendar 時間必須包含時區偏移量（例如 -07:00）或使用 UTC（Z）。像 2026-03-01T10:00:00 這樣沒有時區的日期時間會被視為不明確，系統會預設為 UTC。

Drive

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

Sheets

# 讀取範圍
$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

回傳文件標題與完整文字內容。

Contacts

$GAPI contacts list --max 20

輸出格式

所有命令皆回傳 JSON。各服務的主要欄位：

疑難排解

---

---

CLI 介面