核心功能
gws-gmail-watch 是一款 CLI 工具，用于实时监控 Gmail 收件箱并将新邮件以 NDJSON（Newline Delimited JSON）格式流式输出。它通过 Google Cloud Pub/Sub 实现推送通知机制，而非传统轮询，大幅降低 API 调用频率与延迟。
显著优点
1. 实时推送架构：基于 Pub/Sub 的 push 模型，响应延迟秒级，适合自动化工作流触发
2. 灵活的输出控制：支持 --msg-format（full/raw/metadata/minimal）、文件分流（--output-dir）、单次拉取（--once）等模式
3. 资源生命周期管理：--cleanup 标志可自动销毁临时创建的 Topic/Subscription，避免 GCP 资源残留
4. 标签过滤：通过 --label-ids 精确筛选（如 INBOX、UNREAD），减少无效数据处理
潜在局限
- 7天订阅过期：Gmail watch 令牌需定期 renew，长期无人值守场景需配合 cron 或 systemd 定时器
- GCP 依赖：强制需要启用了 Pub/Sub API 的 Google Cloud 项目，个人用户配置门槛较高
- 无内置持久化：消息仅流式传递，断线期间无本地队列缓冲，可能丢失未及时处理的消息
- 权限复杂度：需同时配置 Gmail API 授权、GCP IAM（Pub/Sub 发布/订阅权限）、服务账号密钥
适合人群
- 需要将 Gmail 接入 CI/CD 流水线或事件驱动架构的 DevOps 工程师
- 构建邮件自动化工作流（如自动归档、智能回复、安全审计）的开发者
- 已有 GCP 基础设施的企业用户
常规风险
- 凭证泄露：
gws依赖 OAuth 2.0 或服务账号 JSON，需遵循gws-shared的安全存储规范 - 权限过度授予：默认可能获得完整的 Gmail 读权限，建议通过 GCP IAM 限制至
pubsub.subscriber+gmail.labels最小集 - 资源费用：Pub/Sub 消息量与网络出口可能产生意外账单，测试环境务必启用
--cleanup