核心用法
gws calendar +agenda 是一款专为 Google Workspace 设计的命令行日程查询工具，通过 gws CLI 框架提供跨日历的事件聚合视图。核心功能包括：
- 多时间维度查询：支持
--today/--tomorrow/--week快捷标签，或通过--days N自定义天数范围 - 日历级过滤：使用
--calendar指定单个日历（支持名称或 ID），默认查询全部授权日历 - 时区灵活控制：自动采用 Google 账户时区，可通过
--timezone强制覆盖（IANA 格式如America/New_York）
典型工作流：
gws calendar +agenda --week --format table # 周视图表格输出 gws calendar +agenda --days 3 --calendar 'Work' # 指定日历未来3天
显著优点
| 维度 | 亮点 |
|------|------|
| **安全性** | **只读操作**，明确承诺「never modifies events」，无写入风险 |
| **效率** | 跨日历聚合一次查询，避免逐个日历切换 |
| **集成度** | 继承 `gws` 统一认证体系，OAuth 令牌管理集中化 |
| **可编排** | CLI 输出易于 pipe 到脚本、通知系统或 AI 工作流 |
潜在局限
- 功能边界：纯查询工具，不支持创建/编辑/删除事件；需配合
gws-calendar主模块进行事件管理 - 依赖链路：强依赖
gws核心与gws-shared认证层，需预先完成 OAuth 授权流程 - 输出控制：
--format等全局标志在共享文档中定义，实际可用性需查阅gws-shared - 离线限制：完全依赖 Google Calendar API 实时查询，无本地缓存机制
适合人群
- 开发者/SRE：快速检查日程冲突、构建值班通知脚本
- 远程协作团队：多时区成员快速对齐会议安排
- 自动化工作流：CI/CD 流水线中集成日程检查（如部署窗口验证）
常规风险
- OAuth 范围风险：虽为只读，但仍需
calendar.readonly权限；令牌泄露可导致日历信息暴露 - 时区陷阱：跨时区团队易因默认时区设定产生理解偏差，建议显式使用
--timezone - 日历可见性：查询结果受 Google 账户权限控制，共享日历若权限不足将静默过滤