名称： google-chat
描述： 通过 Webhook 或 OAuth 向 Google Chat 空间和用户发送消息。适用于需要向 Google Chat 频道（空间）发送通知、警报或消息，或向特定用户发送直接消息的场景。支持入站 Webhook（用于预定义频道）和 OAuth 2.0（用于向任何空间或用户进行动态消息发送）。

Google Chat 消息发送

通过两种方法向 Google Chat 发送消息：

1. Webhook - 快速、预配置的频道（消息以机器人身份显示）
2. OAuth - 向任何空间或用户进行动态消息发送（需要身份验证）

快速开始

方法一：Webhook（适用于已知频道）

向预配置的频道发送消息：

python3 scripts/send_webhook.py "$WEBHOOK_URL" "您的消息内容"

带线程回复的示例：

python3 scripts/send_webhook.py "$WEBHOOK_URL" "回复消息" --thread_key "unique-thread-id"

配置： 将 Webhook 存储在 google-chat-config.json 中：

{
  "webhooks": {
    "acs_engineering_network": "https://chat.googleapis.com/v1/spaces/...",
    "general": "https://chat.googleapis.com/v1/spaces/..."
  }
}

读取配置并发送：

WEBHOOK_URL=$(jq -r '.webhooks.acs_engineering_network' google-chat-config.json)
python3 scripts/send_webhook.py "$WEBHOOK_URL" "部署完成 ✅"

方法二：OAuth（用于动态消息发送）

首次设置：

1. 将 OAuth 凭据保存到文件（例如 google-chat-oauth-credentials.json）
2. 运行初始身份验证（打开浏览器，保存令牌）：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space "General" \
  "测试消息"

按空间名称发送：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space "Engineering Network" \
  "部署完成"

注意： OAuth 消息会自动包含 🤖 表情前缀。使用 --no-emoji 来禁用此功能：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space "Engineering Network" \
  "不带表情的消息" \
  --no-emoji

列出可用空间：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --list-spaces

发送私信（需要现有空间 ID）：

# 注意：Google Chat API 不支持通过电子邮件创建新的私信会话
# 您需要一个现有私信对话的空间 ID
python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space-id "spaces/xxxxx" \
  "报告已准备就绪"

按空间 ID 发送（速度更快）：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space-id "spaces/AAAALtlqgVA" \
  "直接发送到空间的消息"

依赖项

安装所需的 Python 包：

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

必需的 OAuth 范围：
- https://www.googleapis.com/auth/chat.messages - 发送消息
- https://www.googleapis.com/auth/chat.spaces - 访问空间信息
- https://www.googleapis.com/auth/chat.memberships.readonly - 列出空间成员（用于识别私信）

OAuth 设置指南

如果尚不存在 OAuth 凭据：

1. 访问 Google Cloud Console
2. 选择您的项目或创建一个新项目
3. 启用 Google Chat API
4. 进入 APIs & Services → Credentials
5. 创建 OAuth 2.0 Client ID（选择桌面应用类型）
6. 下载 JSON 文件并保存为 google-chat-oauth-credentials.json

凭据 JSON 文件应类似如下：

{
  "installed": {
    "client_id": "...apps.googleusercontent.com",
    "client_secret": "GOCSPX-...",
    "redirect_uris": ["http://localhost"],
    ...
  }
}

Webhook 设置指南

为 Google Chat 空间创建 Webhook：

1. 在浏览器中打开 Google Chat
2. 进入目标空间
3. 点击空间名称 → Apps & integrations
4. 点击 Manage webhooks → Add webhook
5. 为其命名（例如 "Agustin Networks"）
6. 复制 Webhook URL
7. 将其添加到 google-chat-config.json 文件中

选择合适的方法

在以下情况使用 Webhook：
- 需要重复向相同的频道发送消息
- 消息应以机器人/服务身份显示
- 速度很重要（无需 OAuth 握手）
- 配置是静态的

在以下情况使用 OAuth：
- 需要动态地向不同空间发送消息
- 消息应从您配置的 Google Chat 应用发出
- 空间名称在运行时确定
- 需要列出和发现可用空间

OAuth 限制：
- 无法通过电子邮件地址创建新的私信会话（Google Chat API 限制）
- 发送私信需要现有对话的空间 ID
- 使用 --list-spaces 查找可用的私信空间 ID

消息格式化

两种方法都支持纯文本。对于高级格式化（卡片、按钮），需要构造 JSON 负载：

带卡片的 Webhook 示例：

import json
import urllib.request

payload = {
    "cardsV2": [{
        "cardId": "unique-card-id",
        "card": {
            "header": {"title": "部署状态"},
            "sections": [{
                "widgets": [{
                    "textParagraph": {"text": "生产部署已成功完成"}
                }]
            }]
        }
    }]
}

data = json.dumps(payload).encode("utf-8")
req = urllib.request.Request(webhook_url, data=data, headers={"Content-Type": "application/json"})
urllib.request.urlopen(req)

故障排除

Webhook 错误：
- 验证 Webhook URL 是否正确且处于活动状态
- 检查空间是否仍然存在且 Webhook 未被删除
- 确保消息内容非空

OAuth 错误：
- 如果令牌过期，请重新运行身份验证流程
- 验证 Google Cloud Console 中是否已启用 Google Chat API
- 检查用户是否有权访问目标空间
- 对于私信，确保用户电子邮件正确且在同一工作区

权限错误：
- Webhook：必须是空间的成员
- OAuth：必须有权访问目标空间或用户
- 企业工作区：某些功能可能受管理员策略限制

示例

向工程频道发送部署通知：

WEBHOOK=$(jq -r '.webhooks.acs_engineering_network' google-chat-config.json)
python3 scripts/send_webhook.py "$WEBHOOK" "🚀 生产部署 v2.1.0 已完成"

向特定用户发送任务提醒：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --dm juan@empresa.com \
  "您的报告已准备好审核：https://docs.company.com/report"

将多条消息组织到同一线程中（Webhook）：

WEBHOOK=$(jq -r '.webhooks.general' google-chat-config.json)
THREAD_KEY="deploy-$(date +%s)"

python3 scripts/send_webhook.py "$WEBHOOK" "开始部署..." --thread_key "$THREAD_KEY"
# ... 部署过程 ...
python3 scripts/send_webhook.py "$WEBHOOK" "部署完成 ✅" --thread_key "$THREAD_KEY"