功能概述
gws-calendar 是基于 Google Calendar API v3 的命令行工具封装，提供对日历资源的完整 CRUD 操作能力。该技能覆盖六大核心资源模块：
- calendars：创建/删除/修改日历元数据，支持清除主日历全部事件
- events：完整的事件生命周期管理，支持快速创建（quickAdd）、递归事件实例查询、跨日历移动
- calendarList：管理用户订阅的日历列表（与 calendars 区分，侧重用户视角的订阅关系）
- acl：细粒度访问控制，支持共享权限的增删改查及实时监听
- freebusy：批量查询多日历空闲/忙碌状态，适合会议排期场景
- settings / colors：用户偏好设置与颜色定义查询
显著优势
1. 原生 API 完整性：直接暴露 Google Calendar API 全部能力，无功能裁剪，支持 patch 语义更新、watch 实时推送等企业级特性
2. 结构化辅助命令：内置 +insert、+agenda 等封装指令，降低常见操作的学习成本
3. 领域专用场景：ACL 管理适合企业域权限治理；freebusy 查询是会议调度系统的核心依赖
4. 实时同步能力：通过 watch/stop/channel 机制支持事件变更的推送订阅
局限性与风险
- 认证门槛高：需预先配置 OAuth 2.0 或域级委托（domain-wide delegation），文档明确警告"勿用服务账号"以避免数据所有权混乱
- 破坏性操作无二次确认：
calendars.clear会永久删除主日历全部事件，delete操作不可逆 - 递归事件复杂性：instances 方法返回的是展开后的单个实例，修改需理解 Google 的递归规则（RRULE）机制
- 配额与速率限制：未提及具体配额策略，高频调用可能触发 API 限流
适用人群
- 开发者/运维工程师：需要脚本化日历管理、CI/CD 中的会议自动化
- 企业管理员：域级日历权限治理、资源日历配置
- 效率工具集成者：将日历能力嵌入自有产品（需评估 OAuth 审核流程）
常规风险
| 风险类型 | 说明 |
|---------|------|
| 数据误删 | clear/delete 操作不可逆，建议操作前备份 |
| 权限扩散 | acl.insert 若配置不当可能导致日历意外公开 |
| 凭证泄露 | 依赖 `../gws-shared/SKILL.md` 的认证配置，需确保凭据文件权限控制 |
| 递归逻辑错误 | patch 递归事件可能仅影响单个实例或整个序列，需明确 `recurringEventId` 参数 |
> 安全提示：生产环境使用前务必阅读 gws-shared 中的安全规则，并启用最小权限原则（仅申请需要的 calendar 作用域）。