google-integration

用途

Google Integration 提供对 Google Workspace 服务的统一接口，核心目标是让用户通过一次 OAuth 登录，即可使用 Gmail、Google Docs、Google Sheets、Google Calendar、Google Drive、Google Tasks 和 Google Slides 的全部功能。所有服务共享同一套凭证和一致的错误处理模式。

主要能力

该集成包含以下服务及其操作：

Gmail：读取、发送、回复、转发邮件，管理草稿和标签。
Google Docs：读取、写入、创建、导出、格式化文档。
Google Sheets：读取、写入、追加、创建、格式化电子表格。
Google Calendar：列出事件、创建、更新、查找空闲时段、检查可用性。
Google Drive：上传、下载、共享、组织文件夹。
Google Tasks：创建、完成、组织任务列表。
Google Slides：创建、编辑幻灯片、添加文本/图片、导出。

使用方式

首次设置

新用户可输入“connect google”运行交互式设置向导。向导会引导完成：创建 Google Cloud 项目、启用所需 API、创建 OAuth 凭证、使用 Google 账户认证。

预检（始终首先运行）

python3 00-system/skills/google/google-master/scripts/check_google_config.py --json

退出码含义：

0：就绪，所有服务可用
1：需要登录，运行下方登录命令
2：缺少凭证或依赖

认证（授予所有服务访问权限）

python3 00-system/skills/google/google-master/scripts/google_auth.py --login

各服务快速开始

Gmail

# 列出最近邮件
python3 00-system/skills/google/gmail/scripts/gmail_operations.py list --max 10

# 发送邮件（先创建草稿，请求确认）
python3 00-system/skills/google/gmail/scripts/gmail_operations.py send --to "user@example.com" --subject "Hello" --body "Message"

Google Docs

# 读取文档
python3 00-system/skills/google/google-docs/scripts/docs_operations.py read <document_id>

# 创建文档
python3 00-system/skills/google/google-docs/scripts/docs_operations.py create "My Document" --content "Initial content"

Google Sheets

# 读取数据
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py read <spreadsheet_id> "Sheet1!A1:D10"

# 追加行
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py append <spreadsheet_id> "Sheet1!A:D" --values '[["New", "Row", "Data"]]'

Google Calendar

# 列出即将到来的事件
python3 00-system/skills/google/google-calendar/scripts/calendar_operations.py list --max 10

# 查找空闲时段
python3 00-system/skills/google/google-calendar/scripts/calendar_operations.py find-slots --duration 30 --from "2025-12-16" --to "2025-12-20"

Google Drive

# 列出根目录文件
python3 00-system/skills/google/google-drive/scripts/drive_operations.py list

# 上传文件
python3 00-system/skills/google/google-drive/scripts/drive_operations.py upload ./local_file.pdf

# 下载文件
python3 00-system/skills/google/google-drive/scripts/drive_operations.py download <file_id> --output ./downloaded.pdf

Google Tasks

# 列出任务
python3 00-system/skills/google/google-tasks/scripts/tasks_operations.py tasks

# 创建任务
python3 00-system/skills/google/google-tasks/scripts/tasks_operations.py create "Call John" --due 2025-12-20

# 完成任务
python3 00-system/skills/google/google-tasks/scripts/tasks_operations.py complete <task_id>

Google Slides

# 列出演示文稿
python3 00-system/skills/google/google-slides/scripts/slides_operations.py list

# 创建演示文稿
python3 00-system/skills/google/google-slides/scripts/slides_operations.py create "Q4 Report"

# 导出为 PDF
python3 00-system/skills/google/google-slides/scripts/slides_operations.py export <presentation_id> ./report.pdf

目录结构

google/
├── SKILL.md                          # 本文件（包概览）
├── google-connect/                   # 设置向导（输入“connect google”）
│   └── SKILL.md                      # 交互式设置工作流
├── google-master/                    # 共享资源（请勿直接加载）
│   ├── SKILL.md                      # 共享资源文档
│   ├── scripts/
│   │   ├── google_auth.py            # 所有服务的统一 OAuth
│   │   └── check_google_config.py    # 预检验证
│   └── references/
│       ├── setup-guide.md            # 完整设置说明
│       └── error-handling.md         # 常见错误与解决方案
├── gmail/
│   ├── SKILL.md                      # Gmail 专属文档
│   └── scripts/gmail_operations.py
├── google-docs/
│   ├── SKILL.md                      # Docs 专属文档
│   └── scripts/docs_operations.py
├── google-sheets/
│   ├── SKILL.md                      # Sheets 专属文档
│   └── scripts/sheets_operations.py
├── google-calendar/
│   ├── SKILL.md                      # Calendar 专属文档
│   └── scripts/calendar_operations.py
├── google-drive/
│   ├── SKILL.md                      # Drive 专属文档
│   └── scripts/drive_operations.py
├── google-tasks/
│   ├── SKILL.md                      # Tasks 专属文档
│   └── scripts/tasks_operations.py
└── google-slides/
    ├── SKILL.md                      # Slides 专属文档
    └── scripts/slides_operations.py

设置

前置条件

pip install google-auth google-auth-oauthlib google-api-python-client

1. 创建 Google Cloud 项目

前往 Google Cloud Console
创建或选择项目
启用 API：Gmail、Docs、Sheets、Calendar、Drive、Tasks、Slides

2. 创建 OAuth 凭证

前往 APIs & Services > Credentials
创建 OAuth 2.0 客户端 ID（桌面应用）
复制 Client ID 和 Client Secret
添加到 .env 文件（位于 Nexus 根目录）：

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_PROJECT_ID=your-project-id

3. 认证

python3 00-system/skills/google/google-master/scripts/google_auth.py --login

这会打开浏览器，一次性授予所有服务的权限。

详细设置请参阅：google-master/references/setup-guide.md

错误处理

请参阅 google-master/references/error-handling.md，其中涵盖：

认证错误（401、403）
速率限制（429）
权限问题
令牌刷新问题

文件位置

文件	路径	用途
OAuth 凭证	.env（GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_PROJECT_ID）	应用身份
访问令牌	01-memory/integrations/google-token.json	用户认证令牌

.env 和令牌文件均在 .gitignore 中，不会被提交。

安全说明

凭证（.env 文件）在 .gitignore 中，永不提交
令牌文件（google-token.json）在 .gitignore 中，永不提交
每个用户使用自己的 Google 账户进行认证

适用场景

适用于需要通过命令行或自动化脚本统一操作多个 Google Workspace 服务的场景，例如批量处理邮件、自动生成文档和表格、管理日历事件、上传下载 Drive 文件、创建任务和演示文稿等。

限制

需要自行创建 Google Cloud 项目并启用相应 API
需要安装 Python 依赖包
需要配置 OAuth 凭证并完成浏览器认证
各服务的具体操作受 Google API 自身的配额和权限限制
资料中未提供收费、价格或平台兼容性的具体信息