核心用法
Cal.com Skill 通过 Maton 平台代理，以托管 OAuth 方式接入 Cal.com API，让用户无需处理复杂的 OAuth 流程即可管理完整的日程系统。
主要功能覆盖：
- 事件类型管理：创建、配置会议模板（时长、标题、slug、隐藏状态等）
- 预订操作：查询可用时段、创建/取消预订，支持过滤状态（upcoming/past/cancelled/accepted）
- 日程与可用性：管理个人工作时段、查询可用时间段、预锁定时段
- 日历集成：查看已连接的 Google Calendar 等外部日历
- 视频会议：配置 Google Meet、Daily.co 等会议工具
- Webhook 自动化：事件级与用户级双重 webhook，支持 14 种触发事件
- 团队与资源：查看团队成员、管理已验证邮箱等资源
典型工作流：
1. 通过 Maton 平台创建 OAuth 连接
2. 获取 MATON_API_KEY 并配置环境变量
3. 调用 /me 验证连接，创建事件类型
4. 查询可用时段 → 创建预订 → 配置 webhook 通知
显著优点
- 零 OAuth 复杂度：Maton 代理自动注入令牌，开发者只需单一 API Key
- 企业级功能覆盖：完整支持 Cal.com v2 API，包括团队管理、多时区日程、视频会议集成
- 安全设计：所有写操作强制要求显式用户确认，防止意外变更
- 灵活的 webhook 体系：支持事件级与用户级双重订阅，14 种细粒度触发器
- 多账户支持：通过
Maton-Connection头部可在同一环境切换多个 Cal.com 账户
潜在缺点与局限性
- 依赖 Maton 平台：Cal.com 原生 OAuth 被完全封装，若 Maton 服务中断则不可用
- API 稳定性问题：文档明确指出
/v2/schedules（无 ID）端点可能返回 500 错误 - 时区处理复杂度：所有时间默认为 UTC，需客户端处理 IANA 时区转换
- 预订前置检查：创建预订前必须先查询可用时段，否则可能失败
- 个人数据暴露风险：预订数据包含参会者姓名、邮箱，需合规使用
适合人群
- 需要快速集成日程功能的 SaaS 开发者
- 构建自动化工作流（CRM 同步、会议提醒）的技术团队
- 已使用 Maton 生态、希望统一管理多平台 OAuth 连接的企业
- 对原生 Cal.com API 认证流程感到繁琐的独立开发者
常规风险
| 风险类别 | 具体说明 | 缓解建议 |
|---------|---------|---------|
| **数据隐私** | Webhook 将参会者 PII（姓名、邮箱）发送至外部 URL | 创建前务必确认 subscriberUrl 归属与 HTTPS 加密 |
| **权限泄露** | API Key 泄露可导致账户内所有日程数据被读取 | 使用环境变量存储，避免硬编码或日志输出 |
| **意外变更** | 写操作虽需确认，但批量操作仍有误操作空间 | 生产环境建议配合审计日志与二次确认机制 |
| **供应商锁定** | 完全依赖 Maton 代理层 | 评估 Cal.com 原生 API 作为备选方案的可行性 |
| **时区错误** | UTC 与本地时间转换错误导致预订冲突 | 使用标准 IANA 库，关键操作前进行时区验证 |