SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场google-master

google-master

办公与效率

查看项目

更新于 10-15 08:14

技能介绍

用途

google-master 是一个共享资源库，供所有 Google 集成技能引用，用于消除重复内容。它本身不是面向用户的技能，用户不应直接加载，而应直接调用所需的特定技能（gmail、google-docs、google-sheets、google-calendar）。

它解决的问题是：各 Google 技能原本会重复包含 OAuth 设置、凭据管理、错误处理和 API 模式等内容。解决方案是将共享内容抽取到 google-master/references/ 和 google-master/scripts/ 中，再由各技能引用。

主要能力

统一认证与配置：

  • google_auth.py 为所有 Google 服务提供统一 OAuth。支持参数：--check（检查是否已认证并就绪）、--login（发起 OAuth 登录流程）、--logout（移除已存储令牌）、--status（显示详细认证状态）、--service（指定服务：gmail、docs、sheets、calendar 或 all，默认 all）、--json（以 JSON 输出，默认 False）。退出码：0 表示已配置且就绪；1 表示需要登录（凭据存在但未认证）；2 表示未配置（缺少凭据或依赖）。
  • check_google_config.py 用于预检校验，支持 --json 参数输出结构化 JSON 供 AI 使用，适用于快速检查 Google 集成是否已配置及诊断。

共享参考文档：

  • setup-guide.md：完整设置向导，涵盖创建 Google Cloud 项目、启用 API（Gmail、Docs、Sheets、Calendar）、创建 OAuth 2.0 凭据、将凭据添加到 .env 文件、首次认证流程。
  • error-handling.md：故障排查，涵盖常见错误与解决方案、HTTP 错误码（401、403、404）、作用域/权限问题、速率限制、令牌刷新失败。
  • api-patterns.md：常见模式，涵盖认证头、分页、批量请求、错误响应。

统一令牌作用域：首次登录时统一令牌会请求所有作用域。Gmail：gmail.readonly、gmail.send、gmail.compose、gmail.modify、gmail.labels；Docs：documents、drive；Sheets：spreadsheets、drive.readonly；Calendar：calendar、calendar.events。用户授权一次后，所有 Google 技能即可工作。

使用方式

文件位置：OAuth 凭据位于 .env（GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_PROJECT_ID），即来自 Google Cloud 的应用身份；访问令牌位于 01-memory/integrations/google-token.json，即用户已认证的令牌。

各技能通过导入共享认证模块来引用本库，示例代码：

import sys
from pathlib import Path

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

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

智能错误检测流程：当 Google 技能因缺少配置而失败时，AI 应先运行配置检查并输出 JSON：

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

然后解析 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。

若缺少凭据，引导用户访问 https://console.cloud.google.com/，依次进入 APIs & Services > Credentials > Create OAuth Client ID（Desktop app），复制 Client ID 和 Client Secret 并添加到 .env：

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

随后运行 --login 进行认证。

使用示例：用户说“send an email to john@example.com”时，AI 加载 gmail 技能（而非 google-master）；gmail 的 SKILL.md 提示先运行预检；AI 执行 python google-master/scripts/google_auth.py --check --service gmail；若退出码为 0 则继续执行 gmail_operations.py；若为 1 则自动运行 --login；若为 2 则加载 error-handling.md 并引导用户完成设置。google-master 从不被直接加载，它只是一个资源库。

适用场景

适用于需要统一管理多个 Google 服务（Gmail、Docs、Sheets、Calendar）认证与配置的场景，作为这些技能的共同底层依赖。

限制

本技能不是面向用户的技能，不应直接加载。新增 Google 服务（如 Google Drive、Google Tasks）时，需在 google_auth.py 的 SCOPES 字典中添加作用域、创建带操作脚本的新技能文件夹、从 google-master 导入 get_service()，并在本 SKILL.md 中记录。版本 1.0，创建于 2025-12-17，更新于 2025-12-17，状态为 Production Ready。