Kỹ năng Google Workspace

Tích hợp Gmail, Calendar, Drive, Contacts, Sheets và Docs cho Hermes. Sử dụng OAuth2 với tự động làm mới token. Ưu tiên Google Workspace CLI (gws) khi có sẵn để hỗ trợ rộng hơn, và dùng thư viện Python của Google làm phương án dự phòng.

Skill path: skills/productivity/google-workspace/

Thiết lập

Quy trình thiết lập hoàn toàn do agent hướng dẫn — hãy yêu cầu Hermes thiết lập Google Workspace và nó sẽ hướng dẫn bạn từng bước:

Tạo dự án Google Cloud và bật các API cần thiết (Gmail, Calendar, Drive, Sheets, Docs, People)
Tạo thông tin xác thực OAuth 2.0 (loại Desktop app) và tải xuống file JSON client secret
Ủy quyền — Hermes tạo URL xác thực, bạn phê duyệt trong trình duyệt, dán lại URL chuyển hướng
Hoàn tất — token tự động làm mới từ thời điểm đó

Người dùng chỉ cần email

Nếu bạn chỉ cần email (không cần Calendar/Drive/Sheets), hãy sử dụng kỹ năng himalaya thay thế — nó hoạt động với Gmail App Password và chỉ mất 2 phút. Không cần dự án Google Cloud.

Gmail

Tìm kiếm

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

Trả về JSON với id, from, subject, date, snippet và labels cho mỗi tin nhắn.

Đọc

$GAPI gmail get MESSAGE_ID

Trả về nội dung đầy đủ của tin nhắn dưới dạng văn bản (ưu tiên plain text, dùng HTML nếu không có).

Gửi

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

Tuỳ chỉnh header người gửi

Cờ --from cho phép bạn tuỳ chỉnh tên hiển thị của người gửi trên email đi. Hữu ích khi nhiều agent dùng chung một tài khoản Gmail nhưng bạn muốn người nhận thấy tên khác nhau:

# 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 "..."

Cách hoạt động: Giá trị --from được đặt làm header From RFC 5322 trên tin nhắn MIME. Gmail cho phép tuỳ chỉnh tên hiển thị trên địa chỉ email đã xác thực của bạn mà không cần cấu hình bổ sung. Người nhận sẽ thấy tên hiển thị tuỳ chỉnh (ví dụ "Research Agent") trong khi địa chỉ email vẫn giữ nguyên.

Quan trọng: Nếu bạn sử dụng địa chỉ email khác trong --from (không phải tài khoản đã xác thực), Gmail yêu cầu địa chỉ đó phải được cấu hình làm bí danh Gửi dưới tên trong Gmail Settings → Accounts → Send mail as.

Cờ --from hoạt động với cả send và reply:

$GAPI gmail reply MESSAGE_ID \
  --from '"Support Bot" <shared@company.com>' --body "We're on it"

Trả lời

$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."

Tự động đưa trả lời vào luồng (đặt header In-Reply-To và References) và sử dụng thread ID của tin nhắn gốc.

Nhãn

# 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

Lịch

# 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

cảnh báo

Thời gian lịch phải bao gồm múi giờ (ví dụ -07:00) hoặc sử dụng UTC (Z). Thời gian không có múi giờ như 2026-03-01T10:00:00 sẽ mơ hồ và được coi là UTC.

Drive

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

Sheets

# 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"]]'

Docs

$GAPI docs get DOC_ID

Trả về tiêu đề tài liệu và nội dung văn bản đầy đủ.

Danh bạ

$GAPI contacts list --max 20

Định dạng đầu ra

Tất cả lệnh trả về JSON. Các trường chính theo dịch vụ:

Command	Fields
`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`	2D array of cell values

Xử lý sự cố

Problem	Fix
`NOT_AUTHENTICATED`	Run setup (ask Hermes to set up Google Workspace)
`REFRESH_FAILED`	Token revoked — re-run authorization steps
`HttpError 403: Insufficient Permission`	Missing scope — revoke and re-authorize with the right services
`HttpError 403: Access Not Configured`	API not enabled in Google Cloud Console
`ModuleNotFoundError`	Run setup script with `--install-deps`

Thiết lập​

Gmail​

Tìm kiếm​

Đọc​

Gửi​

Tuỳ chỉnh header người gửi​

Trả lời​

Nhãn​

Lịch​

Drive​

Sheets​

Docs​

Danh bạ​

Định dạng đầu ra​

Xử lý sự cố​