介绍
# gcal-pro
通过自然对话管理 Google Calendar。
## 快速参考
| 动作 | 命令 | 等级 | |--------|---------|------| | 查看今天 | `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` | 免费 | | 快速添加 | `python scripts/gcal_core.py quick -q "Lunch Friday noon"` | 专业版 | | 删除事件 | `python scripts/gcal_core.py delete --id EVENT_ID -y` | 专业版 | | 晨间简报 | `python scripts/gcal_core.py brief` | 专业版 |
## 设置
**首次设置必填：**
1. 用户必须创建 Google Cloud 项目和 OAuth 凭证 2. 将 `client_secret.json` 保存到 `~/.config/gcal-pro/` 3. 运行身份验证： ```bash python scripts/gcal_auth.py auth ``` 4. 浏览器打开 → 用户授予日历访问权限 → 完成
**检查认证状态：** ```bash python scripts/gcal_auth.py status ```
## 等级
### 免费版 - 查看事件（今天、明天、本周、本月） - 搜索事件 - 列出日历 - 查找空闲时间段
### 专业版（$12 一次性付费） - 包含免费版的所有功能，以及： - 创建事件 - 快速添加（自然语言） - 更新/重新安排事件 - 删除事件 - 通过 cron 发送晨间简报
## 使用模式
### 查看日程
当用户问“我的日历上有什么？”或“我今天有什么安排？”时：
```bash cd /path/to/gcal-pro python scripts/gcal_core.py today ```
对于特定时间范围： - "tomorrow" → `python scripts/gcal_core.py tomorrow` - "this week" → `python scripts/gcal_core.py week` - "meetings with Alex" → `python scripts/gcal_core.py search -q "Alex"`
### 创建事件（专业版）
当用户说“把 X 添加到我的日历”或“安排 Y”：
**选项 1：快速添加（自然语言）** ```bash python scripts/gcal_core.py quick -q "Lunch with Alex Friday at noon" ```
**选项 2：结构化创建（通过 Python）** ```python from scripts.gcal_core import create_event, parse_datetime
create_event( summary="Lunch with Alex", start=parse_datetime("Friday noon"), location="Cafe Roma", confirmed=True # Set False to show confirmation prompt ) ```
### 修改事件（专业版）
**⚠️ 执行破坏性操作需要确认！**
在删除或大幅修改事件之前，务必与用户确认：
1. 显示事件详情 2. 询问“是否删除/重新安排此事件？” 3. 仅在用户确认后使用 `confirmed=True` 或 `-y` 标志继续
**删除：** ```bash # First, find the event python scripts/gcal_core.py search -q "dentist" # Shows event ID
# Then delete (with user confirmation) python scripts/gcal_core.py delete --id abc123xyz -y ```
### 查找空闲时间
当用户问“我什么时候有空？”或“找个时间开个 1 小时的会”：
```bash python scripts/gcal_core.py free ```
### 晨间简报（专业版 + Cron）
通过 Clawdbot cron 设置以发送每日日程：
```python from scripts.gcal_core import generate_morning_brief print(generate_morning_brief()) ```
**Cron 设置示例：** - 计划：每天上午 8:00 - 操作：运行 `python scripts/gcal_core.py brief` - 投递：将输出发送到用户的消息频道
## 错误处理
| 错误 | 原因 | 解决方案 | |-------|-------|----------| | "client_secret.json not found" | 设置未完成 | 完成 Google Cloud 设置 | | "Token refresh failed" | 过期/已撤销 | 运行 `python scripts/gcal_auth.py auth --force` | | "requires Pro tier" | 免费用户尝试写入操作 | 提示升级或说明限制 | | "Event not found" | 无效的事件 ID | 先搜索正确的事件 |
## 时区处理
- 所有时间均按用户的本地时区解释（默认：America/New_York） - 当用户指定时区时（例如“2 PM EST”），予以遵守 - 以用户的本地时区显示时间 - 以带时区的 ISO 8601 格式存储
## 响应格式
**对于事件列表，使用此格式：**
``` 📅 **Monday, January 27** • 9:00 AM — Team standup • 12:00 PM — Lunch with Alex 📍 Cafe Roma • 3:00 PM — Client call
📅 **Tuesday, January 28** • 10:00 AM — Dentist appointment 📍 123 Main St ```
**对于确认：**
``` ✓ Event created: "Lunch with Alex" 📅 Friday, Jan 31 at 12:00 PM 📍 Cafe Roma ```
**对于晨间简报：**
``` ☀️ Good morning! Here's your day: 📆 Monday, January 27, 2026
You have 3 events today: • 9:00 AM — Team standup • 12:00 PM — Lunch with Alex • 3:00 PM — Client call
👀 Tomorrow: 2 events ```
## 文件位置
``` ~/.config/gcal-pro/ ├── client_secret.json # OAuth app credentials (user provides) ├── token.json # User's access token (auto-generated) └── license.json # Pro license (if purchased) ```
## 与 Clawdbot 集成
此技能可与以下功能配合使用： - **Cron**：安排晨间简报 - **Memory**：存储日历偏好设置 - **Messaging**：通过 Telegram/WhatsApp 等发送简报
## 升级提示
当免费用户尝试专业版操作时，回复：
> ⚠️ 创建事件需要 **gcal-pro 专业版**（$12 一次性付费）。 > > 专业版包括：创建、编辑、删除事件 + 晨间简报。 > > 👉 升级：[gumroad-link] > > 目前，我可以为您展示日程（免费）——您想看看今天的事件吗？