Back to Details

google-master

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Google Master

Google Master

This is NOT a user-facing skill. It's a shared resource library referenced by all Google integration skills.
这不是面向用户的技能。 它是所有Google集成技能引用的共享资源库。

Purpose

用途

Provides shared resources to eliminate duplication across:
  • gmail
    - Email operations (read, send, reply, forward)
  • google-docs
    - Document operations (read, write, create, export)
  • google-sheets
    - Spreadsheet operations (read, write, append)
  • google-calendar
    - Calendar operations (events, availability, scheduling)
Instead of loading this skill, users directly invoke the specific skill they need above.
提供共享资源以消除以下技能间的重复内容：
  • gmail
    - 邮件操作（读取、发送、回复、转发）
  • google-docs
    - 文档操作（读取、写入、创建、导出）
  • google-sheets
    - 电子表格操作（读取、写入、追加）
  • google-calendar
    - 日历操作（事件、可用性、日程安排）
请勿加载此技能，用户应直接调用上述所需的特定技能。

Architecture: DRY Principle

架构：DRY原则

Problem solved: Google skills would have duplicated content (OAuth setup, credentials management, error handling, API patterns).
Solution: Extract shared content into 
google-master/references/
and 
google-master/scripts/
, then reference from each skill.
Result:
  • Single OAuth flow for all Google services
  • One credentials source (
    .env
    file with GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_PROJECT_ID)
  • One unified token with all scopes
  • Consistent error handling across skills
解决的问题： Google技能原本会存在重复内容（OAuth设置、凭据管理、错误处理、API模式）。
解决方案： 将共享内容提取到
google-master/references/
和
google-master/scripts/
目录，然后由各个技能引用。
成果：
  • 所有Google服务共用一套OAuth流程
  • 单一凭据源（包含GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_PROJECT_ID的
    .env
    文件）
  • 包含所有权限范围的统一令牌
  • 各技能间错误处理保持一致

Shared Resources

共享资源

All Google skills reference these resources (progressive disclosure).
所有Google技能都会引用这些资源（渐进式披露）。

scripts/

scripts/

Authentication & Configuration

身份验证与配置

google_auth.py - Unified OAuth for all Google services
bash
python google_auth.py --check [--service SERVICE] [--json]
python google_auth.py --login [--service SERVICE]
python google_auth.py --logout
python google_auth.py --status
ArgumentRequiredDefaultDescription
--check
No-Check if authenticated and ready
--login
No-Initiate OAuth login flow
--logout
No-Remove stored token
--status
No-Show detailed auth status
--service
NoallSpecific service: gmail, docs, sheets, calendar, or all
--json
NoFalseOutput as JSON
Exit codes:
  • 0 = configured and ready
  • 1 = needs login (credentials exist but not authenticated)
  • 2 = not configured (missing credentials or dependencies)
When to Use: Run this FIRST before any Google operation. Called automatically by individual skills.
check_google_config.py - Pre-flight validation
bash
python check_google_config.py [--json]
ArgumentRequiredDefaultDescription
--json
NoFalseOutput structured JSON for AI consumption
When to Use: Quick check if Google integration is configured. Use for diagnostics.
google_auth.py - 所有Google服务的统一OAuth认证
bash
python google_auth.py --check [--service SERVICE] [--json]
python google_auth.py --login [--service SERVICE]
python google_auth.py --logout
python google_auth.py --status
参数是否必填默认值描述
--check
否-检查是否已完成认证并就绪
--login
否-启动OAuth登录流程
--logout
否-删除存储的令牌
--status
否-显示详细的认证状态
--service
否all指定服务：gmail、docs、sheets、calendar或all
--json
否False以JSON格式输出
退出码：
  • 0 = 已配置就绪
  • 1 = 需要登录（凭据存在但未认证）
  • 2 = 未配置（缺少凭据或依赖）
使用时机： 在执行任何Google操作前首先运行此脚本。由各个技能自动调用。
check_google_config.py - 预飞验证
bash
python check_google_config.py [--json]
参数是否必填默认值描述
--json
否False输出结构化JSON供AI使用
使用时机： 快速检查Google集成是否已配置。用于诊断排查。

references/

references/

setup-guide.md - Complete setup wizard
  • Creating Google Cloud project
  • Enabling APIs (Gmail, Docs, Sheets, Calendar)
  • Creating OAuth 2.0 credentials
  • Adding credentials to 
    .env
    file
  • First-time authentication flow
error-handling.md - Troubleshooting
  • Common errors and solutions
  • HTTP error codes (401, 403, 404)
  • Scope/permission issues
  • Rate limiting
  • Token refresh failures
api-patterns.md - Common patterns
  • Authentication headers
  • Pagination
  • Batch requests
  • Error responses
setup-guide.md - 完整设置向导
  • 创建Google Cloud项目
  • 启用API（Gmail、Docs、Sheets、Calendar）
  • 创建OAuth 2.0凭据
  • 将凭据添加到
    .env
    文件
  • 首次认证流程
error-handling.md - 故障排除
  • 常见错误及解决方案
  • HTTP错误码（401、403、404）
  • 权限范围/权限问题
  • 速率限制
  • 令牌刷新失败
api-patterns.md - 通用模式
  • 认证请求头
  • 分页
  • 批量请求
  • 错误响应

Service Scopes

服务权限范围

The unified token requests all scopes on first login:
ServiceScopes
Gmailgmail.readonly, gmail.send, gmail.compose, gmail.modify, gmail.labels
Docsdocuments, drive
Sheetsspreadsheets, drive.readonly
Calendarcalendar, calendar.events
Note: User grants all permissions once, then all Google skills work.
统一令牌在首次登录时请求所有权限范围：
服务权限范围
Gmailgmail.readonly, gmail.send, gmail.compose, gmail.modify, gmail.labels
Docsdocuments, drive
Sheetsspreadsheets, drive.readonly
Calendarcalendar, calendar.events
注意： 用户只需一次性授予所有权限，之后所有Google技能即可正常使用。

File Locations

文件位置

FileLocationPurpose
OAuth credentials
.env
(GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_PROJECT_ID)		App identity from Google Cloud
Access token
01-memory/integrations/google-token.json
User's authenticated token
文件位置用途
OAuth凭据
.env
（GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_PROJECT_ID）		来自Google Cloud的应用标识
访问令牌
01-memory/integrations/google-token.json
用户的已认证令牌

How Skills Reference This

技能如何引用此库

Each skill imports the shared auth module:
python
undefined
每个技能都会导入共享的认证模块：
python
undefined

In any Google skill's operations script

在任意Google技能的操作脚本中

import sys from pathlib import Path
import sys from pathlib import Path

Add google-master to path

将google-master添加到路径

NEXUS_ROOT = Path(file).resolve().parents[4] # Adjust based on skill location sys.path.insert(0, str(NEXUS_ROOT / "00-system/skills/google/google-master/scripts"))
from google_auth import get_credentials, get_service
NEXUS_ROOT = Path(file).resolve().parents[4] # 根据技能位置调整 sys.path.insert(0, str(NEXUS_ROOT / "00-system/skills/google/google-master/scripts"))
from google_auth import get_credentials, get_service

Get authenticated service

获取已认证的服务

gmail = get_service('gmail', 'v1') docs = get_service('docs', 'v1') sheets = get_service('sheets', 'v4') calendar = get_service('calendar', 'v3')

---
gmail = get_service('gmail', 'v1') docs = get_service('docs', 'v1') sheets = get_service('sheets', 'v4') calendar = get_service('calendar', 'v3')

---

Intelligent Error Detection Flow

智能错误检测流程

When a Google skill fails due to missing configuration, the AI should:
当Google技能因配置缺失而失败时，AI应执行以下步骤：

Step 1: Run Config Check with JSON Output

步骤1：运行带JSON输出的配置检查

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

Step 2: Parse the 
ai_action
Field

步骤2：解析
ai_action
字段

ai_actionWhat to Do
proceed
Config OK, continue with operation
install_dependencies
Run: 
pip install google-auth google-auth-oauthlib google-api-python-client
need_credentials
Guide user to create OAuth credentials in Google Cloud Console
need_login
Run: 
python google_auth.py --login
ai_action操作说明
proceed
配置正常，继续执行操作
install_dependencies
运行：
pip install google-auth google-auth-oauthlib google-api-python-client
need_credentials
引导用户在Google Cloud Console中创建OAuth凭据
need_login
运行：
python google_auth.py --login

Step 3: Help User Fix Issues

步骤3：帮助用户解决问题

If credentials missing:
  1. Direct user to: https://console.cloud.google.com/
  2. Guide through: APIs & Services > Credentials > Create OAuth Client ID (Desktop app)
  3. Copy Client ID and Client Secret, add to 
    .env
    : 
    GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_PROJECT_ID=your-project-id
  4. Run 
    --login
    to authenticate
如果凭据缺失：
  1. 引导用户访问：https://console.cloud.google.com/
  2. 指导步骤：API与服务 > 凭据 > 创建OAuth客户端ID（桌面应用）
  3. 复制客户端ID和客户端密钥，添加到
    .env
    文件： 
    GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_PROJECT_ID=your-project-id
  4. 运行
    --login
    进行认证

Usage Example

使用示例

User says: "send an email to john@example.com"
What happens:
  1. AI loads 
    gmail
    skill (NOT google-master)
  2. gmail
    SKILL.md says: "Run pre-flight check first"
  3. AI executes: 
    python google-master/scripts/google_auth.py --check --service gmail
  4. If exit code 0: proceed with gmail_operations.py
  5. If exit code 1: run 
    --login
    automatically
  6. If exit code 2: load error-handling.md, guide user through setup
google-master is NEVER loaded directly - it's just a resource library.
用户指令： "给john@example.com发送一封邮件"
执行流程：
  1. AI加载
    gmail
    技能（而非google-master）
  2. gmail
    的SKILL.md中说明："首先运行预飞检查"
  3. AI执行：
    python google-master/scripts/google_auth.py --check --service gmail
  4. 如果退出码为0：继续执行gmail_operations.py
  5. 如果退出码为1：自动运行
    --login
  6. 如果退出码为2：加载error-handling.md，引导用户完成设置
google-master永远不会被直接加载 - 它只是一个资源库。

Adding New Google Services

添加新的Google服务

To add a new Google service (e.g., Google Drive, Google Tasks):
  1. Add scopes to 
    SCOPES
    dict in 
    google_auth.py
  2. Create new skill folder with operations script
  3. Import 
    get_service()
    from google-master
  4. Document in this SKILL.md
Version: 1.0 Created: 2025-12-17 Updated: 2025-12-17 Status: Production Ready
如需添加新的Google服务（如Google Drive、Google Tasks）：
  1. 在
    google_auth.py
    的
    SCOPES
    字典中添加权限范围
  2. 创建新的技能文件夹及操作脚本
  3. 从google-master导入
    get_service()
  4. 在此SKILL.md中添加文档说明
版本: 1.0 创建时间: 2025-12-17 更新时间: 2025-12-17 状态: 已就绪用于生产环境