{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

Google Workspace

Gmail, Lịch, Drive, Tài liệu, Trang tính thông qua gws CLI hoặc Python.

Siêu dữ liệu kỹ năng

Nguồn	Đi kèm (được cài đặt theo mặc định)
Đường dẫn

skills/productivity/Google-workspace ` | | Phiên bản |

1.1.0 ` | | Tác giả | Nghiên cứu Nous | | Giấy phép | MIT | | Nền tảng | Linux, macOS, Windows | | Thẻ |

Google

, `Gmail

, `Calendar

, `Drive

, `Sheets

, `Docs

, `Contacts

, `Email

, OAuth | | Kỹ năng liên quan | XPROTECTX25XPROTECTX |

Tham khảo: đầy đủ SKILL.md

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

Google Workspace

Gmail, Lịch, Drive, Danh bạ, Trang tính và Tài liệu — thông qua OAuth do Hermes quản lý và trình bao bọc CLI mỏng. Khi cài đặt `gws

, kỹ năng này sẽ sử dụng nó làm chương trình phụ trợ thực thi để có phạm vi phủ sóng Google Workspace rộng hơn; nếu không thì nó sẽ quay trở lại việc triển khai ứng dụng khách Python đi kèm.

Tài liệu tham khảo

references/gmail-search-syntax.md — Toán tử tìm kiếm Gmail (is:unread, from:, new_than:, v.v.)

Tập lệnh

`scripts/setup.py

• Thiết lập OAuth2 (chạy một lần để ủy quyền)

scripts/Google_API.py — CLI trình bao bọc tương thích. Nó ưu tiên gws cho các hoạt động khi có sẵn, trong khi vẫn duy trì hợp đồng đầu ra JSON hiện có của Hermes.

Thiết lập lần đầu

Quá trình thiết lập hoàn toàn không tương tác — bạn điều khiển từng bước để nó hoạt động trên CLI, Telegram, Discord hoặc bất kỳ nền tảng nào.

Xác định một tốc ký đầu tiên:

GSETUP="Python $\{Hermes_HOME:-$HOME/.Hermes}/skills/productivity/Google-workspace/scripts/setup.py"

`

### Bước 0: Kiểm tra xem đã thiết lập chưa

`bash
$GSETUP --check

`
``Nếu nó in 
`AUTHENTICATED

, hãy chuyển đến phần Sử dụng - quá trình thiết lập đã hoàn tất.

### Bước 1: Phân loại - hỏi người dùng xem họ cần gì

Trước khi bắt đầu thiết lập OAuth, hãy hỏi người dùng HAI câu hỏi:

**Câu hỏi 1: "Bạn cần những dịch vụ nào của Google? Chỉ cần gửi email, hoặc cũng có thể
Lịch/Drive/Trang tính/Tài liệu?"**
- **Chỉ gửi email** → Họ hoàn toàn không cần kỹ năng này. Sử dụng kỹ năng 
`himalaya

  thay vào đó — nó hoạt động với Mật khẩu ứng dụng Gmail (Cài đặt → Bảo mật → Ứng dụng
  Mật khẩu) và mất 2 phút để thiết lập. Không cần dự án Google Cloud.
  Tải kỹ năng Himalaya và làm theo hướng dẫn thiết lập của nó.
- **Email + Lịch** → Tiếp tục với kỹ năng này nhưng sử dụng

--services email,calendar
` trong quá trình xác thực nên màn hình đồng ý chỉ yêu cầu
  phạm vi họ thực sự cần.
- **Chỉ Lịch/Drive/Trang tính/Tài liệu** → Tiếp tục với kỹ năng này và sử dụng một
  bộ 

--services
` hẹp hơn như 
`calendar,drive,sheets,docs

.
- **Quyền truy cập đầy đủ vào Workspace** → Tiếp tục với kỹ năng này và sử dụng mặc định
  Bộ dịch vụ 
`all

.

**Câu hỏi 2: "Tài khoản Google của bạn có sử dụng Bảo vệ nâng cao (phần cứng không?
cần có khóa bảo mật để đăng nhập)? Nếu bạn không chắc chắn thì có lẽ bạn không
— đó là thứ mà lẽ ra bạn phải đăng ký một cách rõ ràng."**
- **Không / Không chắc chắn** → Thiết lập bình thường. Tiếp tục bên dưới.
- **Có** → Quản trị viên Workspace của họ phải thêm ID ứng dụng khách OAuth vào tổ chức
  danh sách ứng dụng được phép trước khi Bước 4 hoạt động. Hãy cho họ biết trước.

### Bước 2: Tạo thông tin xác thực OAuth (một lần, ~5 phút)

Nói với người dùng:`> Bạn cần ứng dụng khách Google Cloud OAuth. Đây là thiết lập một lần:
>
> 1. Tạo hoặc chọn dự án:
> https://console.cloud.Google.com/projectselector2/home/dashboard
> 2. Kích hoạt các API cần thiết từ Thư viện API:
> https://console.cloud.Google.com/APIs/library
> Kích hoạt: API Gmail, API Lịch Google, API Google Drive,
> API Google Trang tính, API Google Tài liệu, API Mọi người
> 3. Tạo ứng dụng khách OAuth tại đây:
> https://console.cloud.Google.com/APIs/credentials
> Thông tin xác thực → Tạo thông tin xác thực → ID ứng dụng khách OAuth 2.0
> 4. Loại ứng dụng: "Ứng dụng dành cho máy tính để bàn" → Tạo
> 5. Nếu ứng dụng vẫn đang trong giai đoạn Thử nghiệm, hãy thêm tài khoản Google của người dùng làm người dùng thử nghiệm tại đây:
> https://console.cloud.Google.com/auth/audience
> Đối tượng → Người dùng thử nghiệm → Thêm người dùng
> 6. Tải xuống tệp JSON và cho tôi biết đường dẫn tệp
>
> Lưu ý quan trọng của Hermes CLI: nếu đường dẫn tệp bắt đầu bằng 

/

, KHÔNG chỉ gửi đường dẫn trống dưới dạng tin nhắn của chính nó trong CLI, vì nó có thể bị nhầm với lệnh gạch chéo. Thay vào đó hãy gửi nó trong một câu, như:
> 
`The JSON file path is: /home/user/Downloads/CLIent_secret_....JSON
``Khi họ cung cấp đường dẫn:

``` bash
$GSETUP --CLIent-secret /path/to/CLIent_secret.JSON

`
`Nếu họ dán các giá trị bí mật của khách hàng / ID khách hàng thô thay vì đường dẫn tệp,
tự mình viết một tệp JSON OAuth trên máy tính để bàn hợp lệ, lưu nó ở đâu đó
rõ ràng (ví dụ 

~/Downloads/Hermes-Google-CLIent-secret.JSON

), sau đó chạy

`
--CLIent-secret
` đối với tệp đó.

### Bước 3: Lấy URL ủy quyền

Sử dụng bộ dịch vụ đã chọn ở Bước 1. Ví dụ:

``` bash
$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

`
``Điều này trả về JSON với trường 
`auth_url
` và cũng lưu URL chính xác vào

~/.Hermes/Google_OAuth_last_url.txt

.

Quy tắc đại lý cho bước này:

- Trích xuất trường 
`auth_url
` và gửi URL chính xác đó cho người dùng dưới dạng một dòng.
- Thông báo cho người dùng rằng trình duyệt có thể sẽ bị lỗi trên 
`http://localhost:1
` sau khi được phê duyệt và điều này là điều được mong đợi.
- Yêu cầu họ sao chép TOÀN BỘ URL được chuyển hướng từ thanh địa chỉ trình duyệt.
- Nếu người dùng nhận được 
`Error 403: access_denied

, hãy gửi trực tiếp họ đến 
`https://console.cloud.Google.com/auth/audience
` để thêm họ làm người dùng thử nghiệm.

### Bước 4: Đổi mã

Người dùng sẽ dán lại một URL như 
`http://localhost:1/?code=4/0A...&scope=...

hoặc chỉ là chuỗi mã. Hoặc hoạt động. Bước 

--auth-url
` lưu trữ tạm thời
phiên OAuth đang chờ xử lý cục bộ để 

--auth-code
` có thể hoàn tất trao đổi PKCE
sau này, ngay cả trên các hệ thống không đầu:

``` bash
$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format JSON

`
``Nếu 

`
--auth-code
` không thành công do mã đã hết hạn, đã được sử dụng hoặc đến từ
tab trình duyệt cũ hơn, giờ đây nó trả về 
`fresh_auth_url
` mới. Trong trường hợp đó,
ngay lập tức gửi URL mới cho người dùng và yêu cầu họ thử lại với URL mới nhất
chỉ chuyển hướng trình duyệt.

### Bước 5: Xác minh

``` bash
$GSETUP --check

`
``Nên in 
`AUTHENTICATED

. Quá trình thiết lập đã hoàn tất - mã thông báo sẽ tự động làm mới kể từ bây giờ.

### Ghi chú
- Token được lưu trữ tại 

~/.Hermes/Google_token.JSON
` và tự động làm mới.

- Trạng thái/trình xác minh phiên OAuth đang chờ xử lý được lưu trữ tạm thời tại 

~/.Hermes/Google_OAuth_pending.JSON
` cho đến khi quá trình trao đổi hoàn tất.
- Nếu 
`gws
` được cài đặt, 
`Google_API.py
` sẽ trỏ nó vào cùng tệp thông tin xác thực 

~/.Hermes/Google_token.JSON

. Người dùng không cần phải chạy luồng 
`gws auth login
` riêng biệt.
- Để thu hồi: 

$GSETUP --revoke

## Cách sử dụng

Tất cả các lệnh đều thông qua tập lệnh API. Đặt 
`GAPI
` làm tốc ký:

``` bash
GAPI="Python $\{Hermes_HOME:-$HOME/.Hermes}/skills/productivity/Google-workspace/scripts/Google_API.py"

`

### Gmail

`bash

# 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 "<h1Q4</h1<pDetails...</p" --html
$GAPI gmail send --to user@example.com --subject "Hello" --from '"Research Agent" <user@example.com>' --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" <user@example.com' --body "Thanks"

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

`

### Lịch

``` bash

# 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

`

### Lái xe

``` bash

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

# Get metadata for a single file
$GAPI drive get FILE_ID

# Upload a local file (auto-detects MIME type)
$GAPI drive upload /path/to/report.pdf
$GAPI drive upload /path/to/image.png --name "Logo.png" --parent FOLDER_ID

# Download (binary files download as-is; Google-native files export to a
# sensible default — Docs→pdf, Sheets→csv, Slides→pdf, Drawings→png)
$GAPI drive download FILE_ID
$GAPI drive download DOC_ID --output ~/doc.pdf
$GAPI drive download DOC_ID --export-mime text/plain --output ~/doc.txt

# Create a folder
$GAPI drive create-folder "Reports"
$GAPI drive create-folder "Q4" --parent FOLDER_ID

# Share
$GAPI drive share FILE_ID --email alice@example.com --role reader
$GAPI drive share FILE_ID --email alice@example.com --role writer --notify
$GAPI drive share FILE_ID --type anyone --role reader        # anyone with link
$GAPI drive share FILE_ID --type domain --domain example.com --role reader

# Delete — defaults to trash (reversible). Use --permanent to skip the trash.
$GAPI drive delete FILE_ID
$GAPI drive delete FILE_ID --permanent

`

### Danh bạ

``` bash
$GAPI contacts list --max 20

`

### Trang tính

`bash

# Create a new spreadsheet
$GAPI sheets create --title "Q4 Budget"
$GAPI sheets create --title "Inventory" --sheet-name "Stock"

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

`

### Tài liệu

``` bash

# Read
$GAPI docs get DOC_ID

# Create a new Doc (optionally seeded with body text)
$GAPI docs create --title "Meeting Notes"
$GAPI docs create --title "Draft" --body "First paragraph..."

# Append text to the end of an existing Doc
$GAPI docs append DOC_ID --text "Additional content to append"

`

## Định dạng đầu ra

Tất cả các lệnh đều trả về JSON. Phân tích bằng 
`jq
` hoặc đọc trực tiếp. Các trường chính:
- **Tìm kiếm Gmail**: 

[\{id, threadId, from, to, subject, date, snippet, labels}]

- **Gmail nhận**: 

\{id, threadId, from, to, subject, date, labels, body}

- **Gửi/trả lời Gmail**: 

\{status: "sent", id, threadId}

- **Danh sách lịch**: 

[\{id, summary, start, end, location, description, htmlLink}]

- **Tạo lịch**: 

\{status: "created", id, summary, htmlLink}

- **Tìm kiếm trên ổ đĩa**: 

[\{id, name, mimeType, modifiedTime, webViewLink}]

- **Lái xe nhận**: 

\{id, name, mimeType, modifiedTime, size, webViewLink, parents, owners}

- **Tải lên ổ đĩa**: 

\{status: "uploaded", id, name, mimeType, webViewLink}

- **Tải xuống ổ đĩa**: 

\{status: "downloaded", id, name, path, mimeType}

- **Thư mục tạo ổ đĩa**: 

\{status: "created", id, name, webViewLink}

- **Chia sẻ ổ đĩa**: 

\{status: "shared", permissionId, fileId, role, type}

- **Xóa ổ**: 

\{status: "trashed" | "deleted", fileId, permanent}

- **Danh sách liên hệ**: 

[\{name, emails: [...], phones: [...]}]

- **Tờ nhận**: 

[[cell, cell, ...], ...]

- **Tạo trang tính**: 

\{status: "created", spreadsheetId, title, spreadsheetUrl}

- **Tạo tài liệu**: 

\{status: "created", documentId, title, url}

- **Tài liệu đính kèm**: 

\{status: "appended", documentId, inserted_at, characters}

## Quy tắc
1. **Không bao giờ gửi email, tạo/xóa sự kiện trên lịch, xóa tệp Drive, chia sẻ tệp hoặc sửa đổi Tài liệu/Trang tính mà không xác nhận với người dùng trước.** Hiển thị những gì sẽ được thực hiện (người nhận, ID tệp, nội dung, vai trò chia sẻ) và yêu cầu phê duyệt. Đối với 
`drive delete

, ưu tiên thùng rác mặc định (có thể đảo ngược) hơn 

--permanent

.
2. **Kiểm tra xác thực trước khi sử dụng lần đầu** — chạy 
`setup.py --check

. Nếu không thành công, hãy hướng dẫn người dùng thiết lập.
3. **Sử dụng tham chiếu cú ​​pháp tìm kiếm của Gmail** cho các truy vấn phức tạp — tải nó bằng 
`skill_view("Google-workspace", file_path="references/gmail-search-syntax.md")

.
4. **Thời gian trong lịch phải bao gồm múi giờ** — luôn sử dụng ISO 8601 với độ lệch (ví dụ: 
`2026-03-01T10:00:00-06:00

) hoặc UTC (
`Z

).
5. **Tôn trọng giới hạn tốc độ** — tránh các lệnh gọi API tuần tự diễn ra nhanh chóng. Đọc hàng loạt khi có thể.

## Khắc phục sự cố| Vấn đề | Sửa chữa |
|----------|------|
| 
`NOT_AUTHENTICATED
` | Chạy các bước thiết lập 2-5 ở trên |
| 
`REFRESH_FAILED
` | Mã thông báo bị thu hồi hoặc hết hạn — làm lại Bước 3-5 |
| 
`HttpError 403: Insufficient Permission
` | Thiếu phạm vi API - 

$GSETUP --revoke
` sau đó làm lại Bước 3-5 |
| 
`AUTHENTICATED (partial)
` hoặc "Phạm vi thiếu mã thông báo" | Các khả năng ghi mới (Ghi/xóa Drive, tạo/chỉnh sửa Tài liệu) yêu cầu ủy quyền lại. 

$GSETUP --revoke
` sau đó làm lại Bước 3-5 để cấp phạm vi nâng cấp. |
| 
`HttpError 403: Access Not Configured
` | API chưa được bật - người dùng cần bật nó trong Google Cloud Console |
| 
`ModuleNotFoundError
` | Chạy 

$GSETUP --install-deps
` |
| Bảo vệ nâng cao chặn xác thực | Quản trị viên Workspace phải đưa mã ứng dụng khách OAuth vào danh sách cho phép |

## Thu hồi quyền truy cập

``` bash
$GSETUP --revoke

`