gcal-pro 是一个 Google Calendar 集成工具，让用户通过自然对话来查看、创建和管理日历事件。它适合在用户询问日程安排、想要添加、编辑或删除事件时使用。
主要能力
免费版（Free Tier）提供以下只读功能：
- 查看事件（今天、明天、本周、本月）
- 搜索事件
- 列出日历
- 查找空闲时间段
Pro 版（一次性付费 12 美元）在免费版基础上增加：
- 创建事件
- 快速添加（自然语言）
- 更新/重新安排事件
- 删除事件
- 通过 cron 发送晨间简报
使用方式
所有操作通过命令行脚本完成，核心脚本为 scripts/gcal_core.py。常用命令包括：
- 查看今天：python scripts/gcal_core.py today
- 查看明天：python scripts/gcal_core.py tomorrow
- 查看本周：python scripts/gcal_core.py week
- 搜索事件：python scripts/gcal_core.py search -q "meeting"
- 列出日历：python scripts/gcal_core.py calendars
- 查找空闲时间：python scripts/gcal_core.py free
- 快速添加（Pro）：python scripts/gcal_core.py quick -q "Lunch Friday noon"
- 删除事件（Pro）：python scripts/gcal_core.py delete --id EVENT_ID -y
- 晨间简报（Pro）：python scripts/gcal_core.py brief
创建事件也可通过 Python 结构化调用，例如从 scripts.gcal_core 导入 create_event 和 parse_datetime，传入 summary、start、location 等参数，confirmed 设为 False 可显示确认提示。
首次设置
首次使用需要完成以下步骤：
- 用户必须创建 Google Cloud 项目并获取 OAuth 凭据
- 将 client_secret.json 保存到 ~/.config/gcal-pro/
- 运行认证：python scripts/gcal_auth.py auth
- 浏览器打开后，用户授予日历访问权限即完成
- 检查认证状态：python scripts/gcal_auth.py status
文件位置
~/.config/gcal-pro/ 目录下包含：
- client_secret.json：OAuth 应用凭据（用户提供）
- token.json：用户访问令牌（自动生成）
- license.json：Pro 许可证（如已购买）
安全与确认
对于删除或重大修改等破坏性操作，必须先与用户确认：显示事件详情，询问是否删除/重新安排，只有在用户确认后才使用 confirmed=True 或 -y 标志继续。
时区处理
所有时间按用户本地时区解释（默认 America/New_York）。当用户指定时区（如 "2 PM EST"）时遵循该时区。显示时间使用用户本地时区，存储为带时区的 ISO 8601 格式。
错误处理
常见错误及解决方案：
- "client_secret.json not found"：设置未完成，需完成 Google Cloud 设置
- "Token refresh failed"：令牌过期或被撤销，运行 python scripts/gcal_auth.py auth --force
- "requires Pro tier"：免费用户尝试写入操作，提示升级或说明限制
- "Event not found"：事件 ID 无效，先搜索正确事件
与 Clawdbot 集成
该技能可与 Clawdbot 的以下功能配合：
- Cron：安排晨间简报
- Memory：存储日历偏好
- Messaging：通过 Telegram/WhatsApp 等渠道发送简报
升级提示
当免费用户尝试 Pro 操作时，应提示：创建事件需要 gcal-pro Pro（一次性 12 美元），Pro 包含创建、编辑、删除事件及晨间简报，并提供升级链接。
限制
- 免费版无法进行任何写入操作（创建、编辑、删除）
- 需要用户自行配置 Google Cloud 项目和 OAuth 凭据
- Pro 版为一次性付费，具体购买链接资料中未提供完整地址
- 默认时区为 America/New_York，用户可指定其他时区